adam/seahaven-door-unlock-api
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/seahaven-door-unlock-api.git synced 2026-09-30 07:03:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
AWS Lambda middleware — Yealink desk phone DSS key unlocks front door via LenelS2 Elements API
31 commits 2 branches 8 tags 49 MiB
TypeScript 53.7%
HCL 43%
Shell 2.4%
JavaScript 0.9%
Find a file
Adam Moussa b5e75f8306 Add GitHub Actions deploy workflow (#18) 
* Add GitHub Actions deploy workflow (OIDC)

* Add permissions block for OIDC token exchange

* Add concurrency control to prevent parallel deploys
2026-05-08 17:08:22 -04:00
.github Add GitHub Actions deploy workflow (#18) 2026-05-08 17:08:22 -04:00
bin Rename stack to kebab-case 2026-05-01 18:56:59 -04:00
lambda Add lockdown mode and CI/CD pipeline (#3) 2026-05-01 18:52:37 -04:00
lib Add lockdown mode and CI/CD pipeline (#3) 2026-05-01 18:52:37 -04:00
.gitignore Add door unlock API — Yealink DSS key triggers LenelS2 Elements TemporaryUnlock via API Gateway + Lambda 2026-04-22 14:36:55 -04:00
buildspec.yml Add lockdown mode and CI/CD pipeline (#3) 2026-05-01 18:52:37 -04:00
cdk.context.json Add lockdown mode and CI/CD pipeline (#3) 2026-05-01 18:52:37 -04:00
cdk.json Add door unlock API — Yealink DSS key triggers LenelS2 Elements TemporaryUnlock via API Gateway + Lambda 2026-04-22 14:36:55 -04:00
door-unlock-plan.md Add door unlock API — Yealink DSS key triggers LenelS2 Elements TemporaryUnlock via API Gateway + Lambda 2026-04-22 14:36:55 -04:00
package-lock.json Add CI workflow (#17) 2026-05-08 16:03:06 -04:00
package.json Add CI workflow (#17) 2026-05-08 16:03:06 -04:00
README.md Add lockdown mode and CI/CD pipeline (#3) 2026-05-01 18:52:37 -04:00
tsconfig.json Add CI workflow (#17) 2026-05-08 16:03:06 -04:00
yealinkT54W-door-unlock-with-sp.ph.xml Apply display settings to SP template — both templates now match 2026-04-23 11:00:00 -04:00
yealinkT54W-door-unlock.ph.xml Add display settings to door-unlock template and update README 2026-04-22 20:01:09 -04:00
yealinkT58W-door-unlock.ph.xml Add lockdown mode and CI/CD pipeline (#3) 2026-05-01 18:52:37 -04:00

README.md

Sea Haven Door Unlock API

AWS Lambda middleware that allows Yealink desk phones to unlock the front door and manage lockdown profiles via LenelS2 Elements.

Yealink T54W/T58W → HTTPS GET → API Gateway → Lambda → LenelS2 Elements API

Architecture

  • API Gateway (HTTP API) — GET /unlock, GET /lockdown, GET /lockdown/status with throttling (5 burst / 2 sustained req/sec)
  • Unlock Lambda — validates a shared auth token, calls the Elements TemporaryUnlock command
  • Lockdown Lambda — toggles lockdown profiles (start/stop) and checks status, returns Yealink XML TextScreen responses
  • Lockdown Poller Lambda — VPC-connected, polls Elements API every 15 seconds for lockdown status (runs 4x per 1-minute EventBridge schedule)
  • SSM Parameter Store — stores the Elements API key, auth token, door ID, and phone IPs
  • Secrets Manager — stores the Yealink phone admin password
  • Custom Domain — doorunlock.seahaven.com via Route 53 + ACM wildcard cert

Lockdown Profiles

Two lockdown profiles are configured:

Profile Elements ID Line Key
Bohemia - Whole Building 4b4a3e6b-c903-4cce-8cd6-288612bf0542 3
Ronkonkoma - Whole Building ff9876bc-c54f-472e-aef9-d2bffd4b7cf7 4

Pressing the line key toggles the lockdown on/off and displays the current status on the phone screen.

Known limitation: Line key LED color does not currently change to reflect lockdown status. The T58W's XML Browser key type (17) does not support persistent LED color changes via Push XML or Execute commands — LED commands are transient and immediately overridden by the phone's key type management.

SSM Parameters

Parameter Type Description
/seahaven/door-unlock/elements-api-key SecureString LenelS2 Elements API key
/seahaven/door-unlock/auth-token SecureString Shared secret embedded in the Yealink DSS key URL
/seahaven/door-unlock/door-id String Elements device ID for the front door reader
/seahaven/door-unlock/phone-ips String Comma-separated phone IPs for lockdown poller

Secrets Manager

Secret Description
door-unlock-api/phone-password Yealink phone admin password for Push XML

CI/CD

Pushes to main trigger an AWS CodePipeline (V2) that runs cdk deploy via CodeBuild.

Resource Name
Pipeline seahaven-door-unlock-api-pipeline
CodeBuild project seahaven-door-unlock-api-build
Artifact bucket seahaven-door-unlock-api-pipeline-artifacts

The CodeBuild role assumes CDK bootstrap roles for deployment — no separate CloudFormation stage.

Manual Deployment

npm install
npx cdk deploy

Phone Configuration

Configure DSS keys on the Yealink T54W/T58W (via phone web UI or 3CX):

  • Key 2 — Unlock Door

    • Type: URL
    • Value: https://doorunlock.seahaven.com/unlock?token=<auth-token>

  • Keys 3-4 — Lockdown Toggle

    • Type: XML Browser (17)
    • Value: https://doorunlock.seahaven.com/lockdown?token=<auth-token>&profile=bohemia|ronkonkoma

3CX Provisioning Templates

Custom 3CX templates are included with door unlock and lockdown URLs hardcoded.

Template Model Key 2 Keys 3-4 Display
yealinkT54W-door-unlock.ph.xml T54W Unlock Door Managed by 3CX BLF Dim after 5 min, never sleep
yealinkT54W-door-unlock-with-sp.ph.xml T54W Unlock Door Shared Parking SP1-3 Dim after 5 min, never sleep
yealinkT58W-door-unlock.ph.xml T58W Unlock Door Lockdown Toggle (Bohemia/Ronkonkoma) Default T58W display settings