@camstack/addon-export-alexa 1.2.131 → 1.2.133

package/lambda-template/README.md

@@ -0,0 +1,171 @@
+# CamStack Alexa Lambda — skill endpoint + token broker
+
+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**.
+
+The same code runs the built-in CamStack skill and any operator's own
+("custom") skill. Each deployment uses its own secrets.
+
+## What it does
+
+| 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). |
+
+### 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": "…" }
+```
+
+`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).
+
+### The broker credential
+
+`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).
+
+## Files
+
+`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:
+
+```bash
+cd lambda-template && rm -f ../camstack-alexa-lambda.zip && zip -j ../camstack-alexa-lambda.zip *.js
+```
+
+## Deployment
+
+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`.
+
+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 }

package/lambda-template/broker.js

@@ -0,0 +1,382 @@
+/**
+ * The Alexa token broker (D753).
+ *
+ * The skill's LWA client secret authenticates every grant exchange and every
+ * refresh at api.amazon.com. Before D753 a copy of it lived in every hub — in
+ * public source and in a public npm package. Now it lives ONLY here (read from
+ * Secrets Manager), together with each user's LWA refresh token, and a hub
+ * gets exactly what it needs to push events: a short-lived access token.
+ *
+ * A hub authenticates to the broker with a PER-LINK credential
+ * `csb1.<linkId>.<secret>` minted at link time:
+ *   - no shared secret: each link has its own, so one leaked hub exposes one
+ *     link, never the skill;
+ *   - only sha256(secret) is stored, compared in constant time;
+ *   - revocable: delete the item (`/broker/revoke`, or the item's TTL lapses);
+ *   - rotatable: `/broker/rotate` swaps the secret atomically, and every
+ *     re-link mints a fresh one (the old item expires on its idle TTL).
+ *
+ * HTTP routes (Function URL, POST only):
+ *   /broker/token    Bearer <credential>         → { accessToken, expiresAt }
+ *   /broker/migrate  { refreshToken }            → { brokerCredential, brokerUrl, accessToken, expiresAt }
+ *   /broker/rotate   Bearer <credential>         → { brokerCredential }
+ *   /broker/revoke   Bearer <credential>         → { ok: true }
+ *
+ * `/broker/migrate` is the zero-touch path for a hub linked before D753: it
+ * still holds a refresh token (and, until it updates, the leaked secret). The
+ * broker proves the token is a live grant OF THIS SKILL by refreshing it with
+ * the skill's secret — possession of that token is already the full power of
+ * the grant, so the broker hands back nothing the caller did not have. The hub
+ * then deletes its copy. Disable with `ALLOW_MIGRATION=0` once every hub moved.
+ *
+ * Nothing here logs a token, a code, a credential or a secret.
+ */
+'use strict'
+
+const crypto = require('node:crypto')
+const { encodeFormUrlEncoded, jsonResponse, parseJsonBody, readBearer } = require('./util.js')
+
+const LWA_TOKEN_URL = 'https://api.amazon.com/auth/o2/token'
+const CREDENTIAL_PREFIX = 'csb1'
+/** Hand out a cached access token only while it has at least this much life left. */
+const ACCESS_TOKEN_MIN_LIFE_MS = 5 * 60 * 1000
+/** A pending (mid-AcceptGrant) item that never activated is gone after this. */
+const PENDING_TTL_SEC = 60 * 60
+/** An active link nobody refreshed for this long is purged by DynamoDB TTL. */
+const IDLE_TTL_SEC = 180 * 24 * 60 * 60
+
+class BrokerError extends Error {
+  constructor(status, code, message) {
+    super(message)
+    this.status = status
+    this.code = code
+  }
+}
+
+// ── Credentials ──────────────────────────────────────────────────────
+
+function sha256Hex(value) {
+  return crypto.createHash('sha256').update(value, 'utf8').digest('hex')
+}
+
+/** @param {(n: number) => Buffer} randomBytes */
+function mintCredential(randomBytes, linkId) {
+  const id = linkId || randomBytes(16).toString('base64url')
+  const secret = randomBytes(32).toString('base64url')
+  return {
+    linkId: id,
+    secretHash: sha256Hex(secret),
+    credential: `${CREDENTIAL_PREFIX}.${id}.${secret}`,
+  }
+}
+
+const B64URL = /^[A-Za-z0-9_-]+$/
+
+function parseCredential(raw) {
+  if (typeof raw !== 'string') return null
+  const parts = raw.split('.')
+  if (parts.length !== 3 || parts[0] !== CREDENTIAL_PREFIX) return null
+  const [, linkId, secret] = parts
+  if (!B64URL.test(linkId) || !B64URL.test(secret)) return null
+  if (linkId.length < 16 || linkId.length > 64 || secret.length < 32 || secret.length > 128) {
+    return null
+  }
+  return { linkId, secret }
+}
+
+function secretMatches(secret, storedHash) {
+  if (typeof storedHash !== 'string' || storedHash.length !== 64) return false
+  const a = Buffer.from(sha256Hex(secret), 'hex')
+  const b = Buffer.from(storedHash, 'hex')
+  return a.length === b.length && crypto.timingSafeEqual(a, b)
+}
+
+// ── LWA ──────────────────────────────────────────────────────────────
+
+async function postLwa(deps, params, creds) {
+  const resp = await deps.fetch(LWA_TOKEN_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: encodeFormUrlEncoded({
+      ...params,
+      client_id: creds.clientId,
+      client_secret: creds.clientSecret,
+    }),
+  })
+  const text = await resp.text().catch(() => '')
+  let body = null
+  try {
+    body = JSON.parse(text)
+  } catch {
+    body = null
+  }
+  return { ok: resp.ok, status: resp.status, body }
+}
+
+function lwaErrorCode(res) {
+  return res.body && typeof res.body.error === 'string' ? res.body.error : null
+}
+
+/**
+ * One call to the LWA token endpoint with the skill's credentials. On
+ * `invalid_client` with a Secrets-Manager-sourced secret, drops the cache and
+ * retries once with a freshly read value — so a rotation takes effect on the
+ * very next call instead of after the cache TTL.
+ */
+async function lwaTokenCall(deps, params) {
+  const creds = await deps.secrets.lwa()
+  if (!creds) {
+    throw new BrokerError(500, 'unconfigured', 'LWA client credentials are not configured')
+  }
+  let res = await postLwa(deps, params, creds)
+  if (lwaErrorCode(res) === 'invalid_client' && creds.source === 'secrets-manager') {
+    deps.secrets.invalidate('lwa')
+    const fresh = await deps.secrets.lwa()
+    if (fresh && fresh.clientSecret !== creds.clientSecret) {
+      deps.log.warn('broker: LWA rejected the cached client secret; retried with a fresh read')
+      res = await postLwa(deps, params, fresh)
+    }
+  }
+  return res
+}
+
+function readLwaTokens(res, fallbackRefreshToken) {
+  const b = res.body || {}
+  if (typeof b.access_token !== 'string' || b.access_token.length === 0) return null
+  const expiresIn = typeof b.expires_in === 'number' && b.expires_in > 0 ? b.expires_in : 3600
+  const refreshToken =
+    typeof b.refresh_token === 'string' && b.refresh_token.length > 0
+      ? b.refresh_token
+      : fallbackRefreshToken
+  if (!refreshToken) return null
+  return { accessToken: b.access_token, refreshToken, expiresInSec: expiresIn }
+}
+
+/** Exchange an AcceptGrant code. Throws BrokerError on any failure. */
+async function exchangeGrantCode(deps, code, redirectUri) {
+  const res = await lwaTokenCall(deps, {
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: redirectUri,
+  })
+  const tokens = res.ok ? readLwaTokens(res, null) : null
+  if (!tokens) {
+    throw new BrokerError(502, 'lwa_exchange_failed', `LWA exchange ${res.status} ${lwaErrorCode(res) || ''}`.trim())
+  }
+  return tokens
+}
+
+/** Refresh a grant. `invalid_grant` → 410 (the user disabled the skill / Amazon revoked it). */
+async function refreshGrant(deps, refreshToken) {
+  const res = await lwaTokenCall(deps, { grant_type: 'refresh_token', refresh_token: refreshToken })
+  if (!res.ok) {
+    if (lwaErrorCode(res) === 'invalid_grant') {
+      throw new BrokerError(410, 'grant_revoked', 'Amazon no longer honours this grant; re-link the skill')
+    }
+    throw new BrokerError(502, 'lwa_unavailable', `LWA refresh ${res.status} ${lwaErrorCode(res) || ''}`.trim())
+  }
+  const tokens = readLwaTokens(res, refreshToken)
+  if (!tokens) throw new BrokerError(502, 'lwa_malformed', 'LWA refresh answered without an access token')
+  return tokens
+}
+
+// ── Link lifecycle ───────────────────────────────────────────────────
+
+function nowSec(deps) {
+  return Math.floor(deps.now() / 1000)
+}
+
+/**
+ * Create a link item for freshly obtained tokens. `status` is `pending` for an
+ * AcceptGrant (activated only after the hub accepted the credential) and
+ * `active` for a migration (the caller already proved possession).
+ */
+async function createLink(deps, opts) {
+  const minted = mintCredential(deps.randomBytes)
+  const now = deps.now()
+  const item = {
+    linkId: minted.linkId,
+    secretHash: minted.secretHash,
+    status: opts.status,
+    refreshToken: opts.tokens.refreshToken,
+    accessToken: opts.tokens.accessToken,
+    accessExpiresAt: now + opts.tokens.expiresInSec * 1000,
+    ...(opts.hubUrl ? { hubUrl: opts.hubUrl } : {}),
+    origin: opts.origin,
+    createdAt: now,
+    lastUsedAt: now,
+    ttl: nowSec(deps) + (opts.status === 'pending' ? PENDING_TTL_SEC : IDLE_TTL_SEC),
+    version: 1,
+  }
+  await deps.store.create(item)
+  return { item, credential: minted.credential }
+}
+
+async function activateLink(deps, item) {
+  const next = { ...item, status: 'active', ttl: nowSec(deps) + IDLE_TTL_SEC, version: item.version + 1 }
+  const ok = await deps.store.replace(next, item.version)
+  if (!ok) throw new BrokerError(409, 'conflict', 'link changed while activating')
+  return next
+}
+
+/** Resolve the request's credential to an ACTIVE item, or throw 401. */
+async function authenticate(deps, event) {
+  const parsed = parseCredential(readBearer(event))
+  if (!parsed) throw new BrokerError(401, 'invalid_credential', 'broker credential missing or malformed')
+  const item = await deps.store.get(parsed.linkId)
+  // One answer for "no such link", "not active" and "wrong secret" — the
+  // response must not tell a prober which linkIds exist.
+  if (!item || item.status !== 'active' || !secretMatches(parsed.secret, item.secretHash)) {
+    throw new BrokerError(401, 'invalid_credential', 'broker credential not recognised')
+  }
+  return item
+}
+
+/** A valid access token for the item, refreshing (and persisting) when needed. */
+async function currentAccessToken(deps, item) {
+  const now = deps.now()
+  if (item.accessToken && item.accessExpiresAt - now > ACCESS_TOKEN_MIN_LIFE_MS) return item
+  let tokens
+  try {
+    tokens = await refreshGrant(deps, item.refreshToken)
+  } catch (err) {
+    if (err instanceof BrokerError && err.code === 'grant_revoked') {
+      await deps.store.remove(item.linkId)
+      deps.log.warn('broker: grant revoked by Amazon; link removed', { link: shortId(item.linkId) })
+    }
+    throw err
+  }
+  const next = {
+    ...item,
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken,
+    accessExpiresAt: now + tokens.expiresInSec * 1000,
+    lastUsedAt: now,
+    ttl: nowSec(deps) + IDLE_TTL_SEC,
+    version: item.version + 1,
+  }
+  if (await deps.store.replace(next, item.version)) return next
+  // Someone refreshed concurrently. Their write carries the newest refresh
+  // token; serve what they stored rather than overwrite it.
+  const fresh = await deps.store.get(item.linkId)
+  if (fresh && fresh.status === 'active' && fresh.accessExpiresAt > now) return fresh
+  throw new BrokerError(503, 'conflict', 'concurrent refresh; retry')
+}
+
+function shortId(linkId) {
+  return typeof linkId === 'string' ? linkId.slice(0, 6) : '?'
+}
+
+// ── HTTP routes ──────────────────────────────────────────────────────
+
+const ROUTES = {
+  '/broker/token': routeToken,
+  '/broker/migrate': routeMigrate,
+  '/broker/rotate': routeRotate,
+  '/broker/revoke': routeRevoke,
+}
+
+function isBrokerPath(path) {
+  return Object.prototype.hasOwnProperty.call(ROUTES, path)
+}
+
+async function handleBrokerRoute(event, deps) {
+  if (event.requestContext.http.method !== 'POST') {
+    return jsonResponse(405, { error: 'method_not_allowed' })
+  }
+  if (!deps.store) {
+    return jsonResponse(503, { error: 'broker_unconfigured', message: 'TOKENS_TABLE is not set' })
+  }
+  try {
+    return await ROUTES[event.rawPath](event, deps)
+  } catch (err) {
+    if (err instanceof BrokerError) {
+      if (err.status >= 500) deps.log.warn('broker: request failed', { route: event.rawPath, code: err.code })
+      return jsonResponse(err.status, { error: err.code, message: err.message })
+    }
+    throw err
+  }
+}
+
+async function routeToken(event, deps) {
+  const item = await authenticate(deps, event)
+  const current = await currentAccessToken(deps, item)
+  return jsonResponse(200, { accessToken: current.accessToken, expiresAt: current.accessExpiresAt })
+}
+
+async function routeMigrate(event, deps) {
+  if (deps.env.ALLOW_MIGRATION === '0') {
+    return jsonResponse(403, { error: 'migration_disabled', message: 're-link the skill instead' })
+  }
+  const brokerUrl = deps.publicUrl
+  if (!brokerUrl) {
+    return jsonResponse(503, { error: 'broker_unconfigured', message: 'broker public URL unknown' })
+  }
+  const body = parseJsonBody(event)
+  const refreshToken = body && typeof body.refreshToken === 'string' ? body.refreshToken : ''
+  if (refreshToken.length === 0 || refreshToken.length > 4096) {
+    return jsonResponse(400, { error: 'invalid_request', message: 'refreshToken is required' })
+  }
+  let tokens
+  try {
+    tokens = await refreshGrant(deps, refreshToken)
+  } catch (err) {
+    if (err instanceof BrokerError && err.code === 'grant_revoked') {
+      throw new BrokerError(400, 'invalid_grant', 'not a live grant of this skill')
+    }
+    throw err
+  }
+  const hubUrl = body && typeof body.hubUrl === 'string' ? body.hubUrl.slice(0, 512) : undefined
+  const { item, credential } = await createLink(deps, {
+    status: 'active',
+    tokens,
+    hubUrl,
+    origin: 'migration',
+  })
+  deps.log.info('broker: migrated a pre-broker grant', { link: shortId(item.linkId) })
+  return jsonResponse(200, {
+    brokerCredential: credential,
+    brokerUrl,
+    accessToken: item.accessToken,
+    expiresAt: item.accessExpiresAt,
+  })
+}
+
+async function routeRotate(event, deps) {
+  const item = await authenticate(deps, event)
+  const minted = mintCredential(deps.randomBytes, item.linkId)
+  const next = { ...item, secretHash: minted.secretHash, version: item.version + 1 }
+  if (!(await deps.store.replace(next, item.version))) {
+    throw new BrokerError(409, 'conflict', 'link changed while rotating; retry')
+  }
+  deps.log.info('broker: credential rotated', { link: shortId(item.linkId) })
+  return jsonResponse(200, { brokerCredential: minted.credential })
+}
+
+async function routeRevoke(event, deps) {
+  const item = await authenticate(deps, event)
+  await deps.store.remove(item.linkId)
+  deps.log.info('broker: link revoked by its hub', { link: shortId(item.linkId) })
+  return jsonResponse(200, { ok: true })
+}
+
+module.exports = {
+  BrokerError,
+  LWA_TOKEN_URL,
+  ACCESS_TOKEN_MIN_LIFE_MS,
+  PENDING_TTL_SEC,
+  IDLE_TTL_SEC,
+  mintCredential,
+  parseCredential,
+  secretMatches,
+  sha256Hex,
+  lwaTokenCall,
+  exchangeGrantCode,
+  refreshGrant,
+  createLink,
+  activateLink,
+  currentAccessToken,
+  isBrokerPath,
+  handleBrokerRoute,
+  shortId,
+}