@camstack/addon-export-alexa 1.2.132 → 1.2.134

package/lambda-template/README.md

@@ -1,116 +1,179 @@
-# CamStack Alexa Lambda (Option 2 — single hosted skill)
+# CamStack Alexa Lambda — skill endpoint + token broker
 
-This Lambda is paired with **one** Alexa Smart Home skill published on
-[developer.amazon.com](https://developer.amazon.com) under the camstack
-brand. Every camstack user reaches the same Lambda; the Lambda decodes
-each user's bearer JWT to learn which hub URL to forward to, so it
-remains completely stateless.
+One Lambda serves one Alexa Smart Home skill and every CamStack hub linked to
+it. It routes each request to the right hub by the `hubUrl` claim the hub bakes
+into its OAuth tokens, and — since D753 — it is the **only** place the skill's
+Login With Amazon (LWA) client secret lives. Hubs never hold it: they receive
+short-lived Event Gateway tokens from this Lambda's **token broker**.
 
-## What it does
-
-| Invocation                                               | Action                                                                                   |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `GET  <FUNCTION_URL>/authorize`                          | Renders an HTML form asking the user for their hub URL, then redirects to the hub's OAuth `/authorize`. |
-| `POST <FUNCTION_URL>/token`                              | Decodes the inbound JWT, looks up the `hubUrl` claim, proxies the form-encoded token request to the hub. |
-| Smart Home directive (`event.directive`)                 | Decodes the bearer, forwards JSON to `${hubUrl}/addon/export-alexa/directive`.            |
-| `Alexa.Authorization/AcceptGrant`                        | Exchanges the grant code at `api.amazon.com`, then POSTs LWA tokens back to the hub.      |
-
-## Deployment
-
-The Lambda is a single 10 kB file with **no node_modules**. The whole
-build is just `zip index.zip index.js`. It ships in the published
-`@camstack/addon-export-alexa` npm package (`npm pack` it and take
-`package/lambda-template/`), which is how the public docs page "Your own Alexa
-skill" tells operators to get it.
-
-Deploy it in the AWS region that serves your skill's locale: NA →
-`us-east-1`, EU/IN → `eu-west-1`, FE/AU → `us-west-2`.
-
-1. Create a new Lambda function in your AWS account:
-   - **Runtime:** Node.js 22.x or newer (the file uses only Node built-ins)
-   - **Architecture:** arm64 (or x86_64 — irrelevant for a small JS Lambda)
-   - **Timeout:** 8 seconds (Alexa's hard limit)
-   - **Memory:** 256 MB is plenty
-
-2. Upload `index.js` (zip first or paste into the inline editor).
-
-3. Add a **Function URL** trigger:
-   - **Auth type:** NONE
-   - Note the assigned URL — it looks like
-     `https://abc123xyz.lambda-url.eu-west-1.on.aws/`.
-
-4. Configure environment variables (see below).
-
-5. Add an **Alexa** → **Alexa Smart Home** trigger and paste the skill id
-   (`amzn1.ask.skill.…`). Create the skill first to get it.
-
-6. Note the Lambda **ARN** (Function overview → Function ARN).
+The same code runs the built-in CamStack skill and any operator's own
+("custom") skill. Each deployment uses its own secrets.
 
-## Environment variables
-
-| Name                           | Value                                                                                                                                                                                                             |
-| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `SKILL_CLIENT_ID`              | Any opaque string. Paste the same value into the Alexa skill manifest's **Client ID** field on Account Linking.                                                                                                    |
-| `SKILL_CLIENT_SECRET`          | Any opaque string. Paste the same value into the Alexa skill manifest's **Client Secret** field.                                                                                                                   |
-| `LWA_CLIENT_ID`                | From the skill's **Permissions → Send Alexa Events** panel. Used for the AcceptGrant LWA token exchange.                                                                                                           |
-| `LWA_CLIENT_SECRET`            | Paired LWA client secret.                                                                                                                                                                                          |
-| `LAMBDA_REDIRECT_URI`          | The Function URL + `/token`, e.g. `https://abc123xyz.lambda-url.eu-west-1.on.aws/token`.                                                                                                                           |
-| `HUB_INGRESS_TOKEN`            | Optional defense-in-depth shared secret. Copy it from the CamStack Alexa addon's **Ingress token (Lambda)** setting. Sent as the `X-CamStack-Ingress` header on hub calls (`/directive`, `/oauth/lwa-tokens`); the hub enforces it once you enable **Require ingress token**. Leave unset to skip. |
-Generate the two skill secrets with anything strong, e.g.
-`openssl rand -hex 32`. The Lambda only compares them — no decoding.
-
-## Skill manifest fields
-
-In the [Alexa developer console](https://developer.amazon.com/alexa/console/ask)
-for your **Smart Home** skill:
-
-### 1. Endpoint
+## What it does
 
-| Field             | Value                                                              |
-| ----------------- | ------------------------------------------------------------------ |
-| Default endpoint  | `<LAMBDA_ARN>` (Function overview → Function ARN)                  |
+| Invocation | Action |
+| --- | --- |
+| `GET  <FUNCTION_URL>/authorize` | HTML form asking for the hub URL, then redirects to the hub's OAuth `/authorize`. |
+| `POST <FUNCTION_URL>/token` | Checks the account-linking client id/secret, decodes the `hubUrl` claim, proxies the token request to the hub. |
+| Smart Home directive | Forwards to `${hubUrl}/addon/export-alexa/directive`, adding `X-CamStack-Broker: <broker origin>` when the broker is on. |
+| `Alexa.Authorization/AcceptGrant` | Exchanges the grant code at `api.amazon.com` **here**, stores the grant in DynamoDB, gives the hub a per-link broker credential (`POST /addon/export-alexa/oauth/broker-link`). |
+| `POST <FUNCTION_URL>/broker/token` | `Bearer <credential>` → `{ accessToken, expiresAt }` (refreshed here when < 5 min left). |
+| `POST <FUNCTION_URL>/broker/migrate` | `{ refreshToken }` from a hub linked before D753 → a broker link. |
+| `POST <FUNCTION_URL>/broker/rotate` | `Bearer <credential>` → `{ brokerCredential }`; the old one stops working. |
+| `POST <FUNCTION_URL>/broker/revoke` | `Bearer <credential>` → deletes the link (and the refresh token). |
+
+Errors Alexa receives follow the Smart Home contract: every `Alexa.ErrorResponse`
+carries the directive's `correlationToken` and `endpoint`; a hub that cannot be
+reached (network error, or a tunnel's 502–504 / 52x page) is
+`BRIDGE_UNREACHABLE`; a hub reply that is not an Alexa event becomes
+`INTERNAL_ERROR`; AcceptGrant failures are `Alexa.Authorization` /
+`ACCEPT_GRANT_FAILED`. The `/authorize` page accepts only an `https://` hub URL
+and shows its error on the page.
+
+### The two credential pairs
+
+| Pair | Secrets Manager id | Authenticates | Who else holds it |
+| --- | --- | --- | --- |
+| **LWA "Send Alexa Events"** client (skill console → Permissions → Alexa Skill Messaging) | `camstack/alexa/lwa` | this Lambda → `api.amazon.com` (code exchange, refresh) | nobody |
+| **Account-linking** client (skill console → Account Linking) | `camstack/alexa/skill` | Amazon → this Lambda's `/token` | Amazon |
+
+Each secret is a JSON string:
+
+```json
+{ "clientId": "…", "clientSecret": "…" }
+```
 
-### 2. Account Linking
+`camstack/alexa/skill` may also carry `"previousClientSecret"` — accepted on
+`/token` while you rotate it (change the value in the skill console, then remove
+the previous one).
 
-| Field                                  | Value                                                                        |
-| -------------------------------------- | ---------------------------------------------------------------------------- |
-| Authorization Grant Type               | Auth Code Grant                                                              |
-| Authorization URI                      | `<FUNCTION_URL>/authorize`                                                   |
-| Access Token URI                       | `<FUNCTION_URL>/token`                                                       |
-| Client ID                              | `SKILL_CLIENT_ID` env var (same string)                                      |
-| Client Secret                          | `SKILL_CLIENT_SECRET` env var (same string)                                  |
-| Client Authentication Scheme           | Credentials in request body (**not** HTTP Basic — the Lambda reads them from the body) |
-| Scope                                  | _(leave empty)_                                                              |
-| Domain List                            | _(leave empty — operators supply arbitrary hub URLs at runtime)_             |
+### The broker credential
 
-### 3. Permissions (proactive events)
+`csb1.<linkId>.<secret>` — 128-bit id + 256-bit secret, minted per link at
+AcceptGrant. The table stores only `sha256(secret)`; comparison is constant
+time; an unknown link and a wrong secret get the same 401. It opens exactly one
+link, is revoked by deleting the item, rotated by `/broker/rotate` or by any
+re-link, and lapses after 180 days without a refresh (DynamoDB TTL).
 
-Enable **Send Alexa Events** and copy the generated LWA client id /
-secret into the Lambda env (`LWA_CLIENT_ID` / `LWA_CLIENT_SECRET`).
+## Files
 
-## How the routing works
+`index.js` (handler), `broker.js`, `secrets.js`, `token-store.js`, `util.js`,
+`http.js`, `aws.js`. No `node_modules`: AWS SDK v3 ships with the nodejs22.x
+runtime. Build:
 
-Every hub-issued JWT (auth code, access token, refresh token) carries a
-`hubUrl` claim equal to that hub's public HTTPS origin. The Lambda
-**base64-decodes** the payload — no signature check. The hub verifies
-the signature when the request lands. Threat model: a forged token with
-a malicious `hubUrl` only reaches that malicious hub; cross-hub
-spillover is not possible because the malicious hub still has to mint a
-token its own auth-manager signed before Alexa stores it.
+```bash
+cd lambda-template && rm -f ../camstack-alexa-lambda.zip && zip -j ../camstack-alexa-lambda.zip *.js
+```
 
-> The hub no longer validates `client_id` / `client_secret`. That pair is
-> checked only here in the Lambda. On the hub, `/api/oauth2/authorize` is a
-> session-authenticated route — an unauthenticated browser is redirected
-> to the normal CamStack login.
+## Deployment
 
-## Local testing
+It ships in the published `@camstack/addon-export-alexa` npm package (`npm pack`
+it and take `package/lambda-template/`). Deploy it in the AWS region that serves
+your skill's locale: NA → `us-east-1`, EU/IN → `eu-west-1`, FE/AU → `us-west-2`.
 
-```bash
-# Pretend to be Alexa's token endpoint hitting the Lambda.
-curl -X POST "$FUNCTION_URL/token" \
-  -H 'content-type: application/x-www-form-urlencoded' \
-  -d 'grant_type=authorization_code' \
-  -d 'code=<some-jwt-with-hubUrl-claim>' \
-  -d "client_id=$SKILL_CLIENT_ID" \
-  -d "client_secret=$SKILL_CLIENT_SECRET"
-```
+1. **Lambda**: Node.js 22.x, arm64, handler `index.handler`, timeout 8 s or
+   more, 128–256 MB. Upload the zip.
+2. **Function URL**: auth type `NONE` (Amazon's account linking and the hubs
+   call it). Note the URL.
+3. **Trigger**: **Alexa** → **Alexa Smart Home**, with your skill id
+   (`amzn1.ask.skill.…`). Create the skill first to get it.
+4. **Secrets Manager**: create `camstack/alexa/lwa` and `camstack/alexa/skill`
+   (JSON above) in the Lambda's region. Enter the values in the console, or
+   with `--secret-string file://…` from a file you delete afterwards — never as
+   a command-line argument.
+5. **DynamoDB**:
+
+   ```bash
+   aws dynamodb create-table --table-name camstack-alexa-tokens \
+     --attribute-definitions AttributeName=linkId,AttributeType=S \
+     --key-schema AttributeName=linkId,KeyType=HASH \
+     --billing-mode PAY_PER_REQUEST \
+     --sse-specification Enabled=true,SSEType=KMS \
+     --deletion-protection-enabled
+   aws dynamodb wait table-exists --table-name camstack-alexa-tokens
+   aws dynamodb update-time-to-live --table-name camstack-alexa-tokens \
+     --time-to-live-specification Enabled=true,AttributeName=ttl
+   ```
+
+6. **IAM** — add to the Lambda's execution role (replace region/account):
+
+   ```json
+   {
+     "Version": "2012-10-17",
+     "Statement": [
+       {
+         "Sid": "ReadSkillSecrets",
+         "Effect": "Allow",
+         "Action": "secretsmanager:GetSecretValue",
+         "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:camstack/alexa/*"
+       },
+       {
+         "Sid": "BrokerLinks",
+         "Effect": "Allow",
+         "Action": ["dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:DeleteItem"],
+         "Resource": "arn:aws:dynamodb:REGION:ACCOUNT:table/camstack-alexa-tokens"
+       }
+     ]
+   }
+   ```
+
+   The default `aws/secretsmanager` and `aws/dynamodb` keys need no extra KMS
+   permission. A customer-managed key would need `kms:Decrypt` on it.
+
+7. **Environment variables** (none is a secret):
+
+| Name | Value |
+| --- | --- |
+| `LWA_SECRET_ID` | `camstack/alexa/lwa` |
+| `SKILL_SECRET_ID` | `camstack/alexa/skill` |
+| `TOKENS_TABLE` | `camstack-alexa-tokens`. Unset = broker off: AcceptGrant hands the tokens to the hub as before D753. |
+| `LAMBDA_REDIRECT_URI` | Function URL + `/token`. AcceptGrant's `redirect_uri`; its origin is the broker URL advertised to hubs. |
+| `BROKER_PUBLIC_URL` | Optional override of that origin (https only). |
+| `LEGACY_HUB_FALLBACK` | `0` = a hub without `/oauth/broker-link` (pre-D753 addon) fails AcceptGrant instead of receiving the refresh token. Default on, for the cut-over. |
+| `ALLOW_MIGRATION` | `0` = refuse `/broker/migrate`. Default on until every hub has migrated. |
+| `HUB_INGRESS_TOKEN` | Optional defense-in-depth header (`X-CamStack-Ingress`), copied from the addon's **Ingress token** setting. |
+
+Legacy, read only when the matching `*_SECRET_ID` is unset: `LWA_CLIENT_ID`,
+`LWA_CLIENT_SECRET`, `SKILL_CLIENT_ID`, `SKILL_CLIENT_SECRET`. Remove them once
+the secrets are in Secrets Manager.
+
+## Skill manifest
+
+| Section | Field | Value |
+| --- | --- | --- |
+| Smart Home | Default endpoint | the Lambda ARN |
+| Account Linking | Authorization grant type | Auth Code Grant |
+| | Authorization URI | `<FUNCTION_URL>/authorize` |
+| | Access Token URI | `<FUNCTION_URL>/token` |
+| | Client ID / Secret | the `camstack/alexa/skill` values |
+| | Authentication scheme | Credentials in request body (**not** HTTP Basic — the Lambda reads them from the body) |
+| | Scope, Domain list | empty |
+| Permissions | Send Alexa Events | on; its Alexa Client Id/Secret go into `camstack/alexa/lwa` |
+
+## Cut-over and compatibility
+
+| Lambda | Hub addon | Result |
+| --- | --- | --- |
+| new, broker on | new | Broker links. Hub holds no secret. |
+| new, broker on | old (pre-D753) | AcceptGrant falls back to the legacy hand-off (hub 404 on `/oauth/broker-link`) unless `LEGACY_HUB_FALLBACK=0`. |
+| new, broker off (`TOKENS_TABLE` unset) | any | Exactly the pre-D753 behaviour. |
+| old | new | Links, but the hub cannot renew the grant (no secret): events stop after ~1 h until the Lambda is upgraded. **Upgrade the Lambda first.** |
+
+A hub linked before D753 migrates itself: the first directive after the Lambda
+advertises `X-CamStack-Broker` lets it trade its refresh token for a broker
+link (`/broker/migrate`, which proves the token by refreshing it with the
+skill's secret) and delete its copy.
+
+## Logs
+
+CloudWatch. `timedFetch_timing` (one per outbound call: host, path, status,
+timings), `accept_grant: linked via broker`, `broker: migrated a pre-broker
+grant`, `broker: credential rotated`, `broker: link revoked by its hub`,
+`broker: grant revoked by Amazon; link removed`, `broker: request failed`. No
+log line carries a token, code, credential or secret.
+
+## Tests
+
+`packages/addon-export-alexa/src/__tests__/lambda-broker.spec.ts` — the whole
+Lambda against fake LWA, hub, Secrets Manager and DynamoDB (`npx vitest run`
+in the addon).

package/lambda-template/aws.js

@@ -0,0 +1,37 @@
+/**
+ * Default AWS wiring. The Lambda Node.js 22 runtime ships AWS SDK v3, so the
+ * deployment stays a zip of plain files with no node_modules. Required lazily:
+ * tests inject fakes and never load the SDK.
+ *
+ * Execution-role permissions this needs (see README → IAM):
+ *   secretsmanager:GetSecretValue   on the two camstack/alexa/* secrets
+ *   dynamodb:GetItem/PutItem/DeleteItem on the tokens table
+ */
+'use strict'
+
+function createAwsClients() {
+  let ddbClient = null
+  let smClient = null
+
+  async function send(commandName, input) {
+    const ddb = require('@aws-sdk/client-dynamodb')
+    if (!ddbClient) ddbClient = new ddb.DynamoDBClient({})
+    const Command = ddb[`${commandName}Command`]
+    if (typeof Command !== 'function') throw new Error(`unknown DynamoDB command ${commandName}`)
+    return ddbClient.send(new Command(input))
+  }
+
+  async function fetchSecretString(secretId) {
+    const sm = require('@aws-sdk/client-secrets-manager')
+    if (!smClient) smClient = new sm.SecretsManagerClient({})
+    const res = await smClient.send(new sm.GetSecretValueCommand({ SecretId: secretId }))
+    if (typeof res.SecretString !== 'string') {
+      throw new Error(`secret ${secretId} has no SecretString`)
+    }
+    return res.SecretString
+  }
+
+  return { send, fetchSecretString }
+}
+
+module.exports = { createAwsClients }