seahaven-door-unlock-api/README.md

# Sea Haven Door Unlock API

AWS Lambda middleware that allows a Yealink T54W desk phone to unlock the front door controlled by LenelS2 Elements. Press a DSS key on the phone, and the door unlocks.

```
Yealink T54W → HTTPS GET → API Gateway → Lambda → LenelS2 Elements API → Door Unlocks
```

## Architecture

- **API Gateway (HTTP API)** — single `GET /unlock` endpoint with throttling (5 burst / 2 sustained req/sec)
- **Lambda (Node.js 20.x)** — validates a shared auth token, calls the Elements `TemporaryUnlock` command
- **SSM Parameter Store** — stores the Elements API key, auth token, and door device ID
- **Custom Domain** — `doorunlock.seahaven.com` via Route 53 + ACM wildcard cert

## 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 |

## Deployment

```bash
npm install
npx cdk deploy
```

## Phone Configuration

Configure a DSS key on the Yealink T54W (via phone web UI or 3CX):

- **Type:** URL
- **Label:** Unlock Door
- **Value:** `https://doorunlock.seahaven.com/unlock?token=<auth-token-value>`

## 3CX Provisioning Templates

Custom 3CX templates are included with the door unlock URL hardcoded on line key 2.

| Template | Model | Line Key 2 | Keys 3+ | 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 | Managed by 3CX BLF | Default T58W display settings |