@camstack/addon-export-alexa 1.2.132 → 1.2.134

package/lambda-template/index.js

@@ -1,75 +1,147 @@
 /**
- * CamStack Alexa Smart Home Lambda — Option 2 (single hosted skill).
+ * CamStack Alexa Smart Home Lambda — one skill, many hubs, and the skill's
+ * token broker (D753).
  *
- * One Lambda + one skill on developer.amazon.com serves ALL camstack
- * users. The Lambda is stateless: it inspects an inbound event, decodes
- * the bearer JWT payload to extract the operator's hub URL, then proxies
- * the request to that hub's core `/api/oauth2/*` endpoints.
+ * One Lambda + one skill serves every CamStack hub. Directives are routed by
+ * the `hubUrl` claim each hub bakes into the OAuth tokens it mints. Since D753
+ * the Lambda is also the ONLY holder of the skill's LWA client secret: it
+ * exchanges AcceptGrant codes itself, keeps each user's LWA refresh token in
+ * DynamoDB, and hands hubs short-lived Event Gateway access tokens against a
+ * per-link credential (see broker.js).
  *
  * Invocation shapes:
- *   1. Lambda URL HTTP GET  /authorize  → render hub-URL entry form
- *   2. Lambda URL HTTP POST /token      → proxy OAuth token exchange to hub
- *   3. Smart Home directive (event.directive.header):
- *      - Alexa.Authorization/AcceptGrant → exchange LWA code at Amazon,
- *        forward tokens to hub
- *      - everything else                 → forward directive to hub
+ *   1. Function URL GET  /authorize      → hub-URL entry form
+ *   2. Function URL POST /token          → OAuth token exchange, proxied to the hub
+ *   3. Function URL POST /broker/*       → token broker (broker.js)
+ *   4. Smart Home directive:
+ *      - Alexa.Authorization/AcceptGrant → exchange the LWA code here, store the
+ *        grant, give the hub a broker credential (legacy: give it the tokens)
+ *      - everything else                 → forward to the hub
  *
- * Required environment variables:
- *   SKILL_CLIENT_ID       OAuth client id Alexa sends on /token (skill
- *                         manifest "Client ID"). Free-form; we just
- *                         compare it.
- *   SKILL_CLIENT_SECRET   Paired client secret (skill manifest "Client
- *                         Secret"). Free-form; compared against the
- *                         inbound POST body.
- *   LWA_CLIENT_ID         Login With Amazon client id from the skill's
- *                         "Permissions → Send Alexa Events" panel. Used
- *                         in the AcceptGrant LWA token exchange.
- *   LWA_CLIENT_SECRET     Paired LWA client secret.
- *   LAMBDA_REDIRECT_URI   The Function URL + "/token" (e.g.
- *                         https://abc123.lambda-url.eu-west-1.on.aws/token).
- *                         Passed as `redirect_uri` to api.amazon.com.
+ * Configuration (env — none of these is a secret once D753 is deployed):
+ *   LWA_SECRET_ID        Secrets Manager id of {"clientId","clientSecret"} for
+ *                        the skill's "Send Alexa Events" LWA client.
+ *   SKILL_SECRET_ID      Secrets Manager id of {"clientId","clientSecret"
+ *                        [,"previousClientSecret"]} for account linking.
+ *   TOKENS_TABLE         DynamoDB table of broker links. Unset = broker off
+ *                        (pre-D753 behaviour: tokens are handed to the hub).
+ *   LAMBDA_REDIRECT_URI  Function URL + "/token"; the AcceptGrant redirect_uri.
+ *   BROKER_PUBLIC_URL    Optional; defaults to LAMBDA_REDIRECT_URI's origin.
+ *   LEGACY_HUB_FALLBACK  "0" = a hub without the broker route fails AcceptGrant
+ *                        instead of receiving the refresh token. Default on.
+ *   ALLOW_MIGRATION      "0" = refuse /broker/migrate. Default on.
+ *   HUB_INGRESS_TOKEN    Optional defense-in-depth header for hub calls.
+ * Legacy (read only when the *_SECRET_ID is unset): LWA_CLIENT_ID,
+ * LWA_CLIENT_SECRET, SKILL_CLIENT_ID, SKILL_CLIENT_SECRET.
  *
- * Ships as a single file — no node_modules, no transpile. Targets the
- * AWS Lambda Node 20.x runtime which exposes built-in `fetch`.
+ * Ships as plain files — no node_modules, no transpile (`zip` the folder's
+ * .js files). AWS SDK v3 comes with the nodejs22.x runtime.
  */
+'use strict'
 
-const FETCH_TIMEOUT_MS = 6000
+const crypto = require('node:crypto')
 
-// Use https.request with a no-keep-alive Agent. Node's built-in fetch
-// (undici-backed) reuses pooled sockets aggressively; in AWS Lambda the
-// invocation-to-invocation gaps can leave pooled sockets stale, and the next
-// fetch throws DOMException AbortError in <1s. https.request gives us
-// explicit control. undici itself is not require-able in the Node 20 Lambda
-// runtime, so we use the standard https module directly.
-const https = require('node:https')
-const http = require('node:http')
-const { URL } = require('node:url')
-const NO_KEEPALIVE_AGENT = new https.Agent({ keepAlive: false })
+const { createAwsClients } = require('./aws.js')
+const {
+  activateLink,
+  createLink,
+  exchangeGrantCode,
+  handleBrokerRoute,
+  isBrokerPath,
+  shortId,
+} = require('./broker.js')
+const { timedFetch } = require('./http.js')
+const { createSecretSource } = require('./secrets.js')
+const { createDynamoTokenStore } = require('./token-store.js')
+const {
+  decodeBody,
+  acceptGrantErrorEnvelope,
+  completeErrorResponse,
+  decodeJwtPayload,
+  describe,
+  encodeFormUrlEncoded,
+  errorEnvelope,
+  jsonResponse,
+  normaliseHubUrl,
+  parseFormUrlEncoded,
+  resolveBrokerPublicUrl,
+} = require('./util.js')
 
-exports.handler = async (event) => {
-  try {
-    if (event && event.requestContext && event.requestContext.http) {
-      return await handleLambdaUrl(event)
-    }
-    if (event && event.directive && event.directive.header) {
-      return await handleDirective(event)
-    }
-    return jsonResponse(400, { error: 'unknown_event' })
-  } catch (err) {
-    console.error('camstack-alexa: unhandled error', err)
-    if (event && event.directive && event.directive.header) {
-      return errorEnvelope(event.directive.header, 'INTERNAL_ERROR', describe(err))
+/** The header that tells a hub where its skill's broker lives (D753). */
+const BROKER_HEADER = 'x-camstack-broker'
+
+/**
+ * Build the dependency set once per container — the secret cache and the SDK
+ * clients must survive across invocations. Anything passed in wins (tests).
+ */
+function resolveDeps(overrides) {
+  const o = overrides || {}
+  const env = o.env || process.env
+  let aws = null
+  const awsClients = () => {
+    if (!aws) aws = createAwsClients()
+    return aws
+  }
+  const store =
+    o.store !== undefined
+      ? o.store
+      : env.TOKENS_TABLE
+        ? createDynamoTokenStore({
+            send: (name, input) => awsClients().send(name, input),
+            tableName: env.TOKENS_TABLE,
+          })
+        : null
+  return {
+    env,
+    fetch: o.fetch || timedFetch,
+    now: o.now || Date.now,
+    randomBytes: o.randomBytes || crypto.randomBytes,
+    log: o.log || console,
+    secrets:
+      o.secrets ||
+      createSecretSource({
+        env,
+        fetchSecretString: (id) => awsClients().fetchSecretString(id),
+      }),
+    store,
+    publicUrl: resolveBrokerPublicUrl(env),
+  }
+}
+
+function createHandler(overrides) {
+  let deps = null
+  return async (event) => {
+    if (!deps) deps = resolveDeps(overrides)
+    try {
+      if (event && event.requestContext && event.requestContext.http) {
+        return await handleLambdaUrl(event, deps)
+      }
+      if (event && event.directive && event.directive.header) {
+        return await handleDirective(event, deps)
+      }
+      return jsonResponse(400, { error: 'unknown_event' })
+    } catch (err) {
+      deps.log.error('camstack-alexa: unhandled error', describe(err))
+      if (event && event.directive && event.directive.header) {
+        return errorEnvelope(
+          event.directive.header,
+          'INTERNAL_ERROR',
+          describe(err),
+          event.directive.endpoint,
+        )
+      }
+      return jsonResponse(500, { error: 'internal_error', message: describe(err) })
     }
-    return jsonResponse(500, { error: 'internal_error', message: describe(err) })
   }
 }
 
 // ── Lambda Function URL (HTTP) routes ────────────────────────────────
 
-async function handleLambdaUrl(event) {
+async function handleLambdaUrl(event, deps) {
   const path = event.rawPath || '/'
   if (path === '/authorize') return handleAuthorizePage(event)
-  if (path === '/token') return handleTokenProxy(event)
+  if (path === '/token') return handleTokenProxy(event, deps)
+  if (isBrokerPath(path)) return handleBrokerRoute(event, deps)
   return { statusCode: 404, headers: { 'content-type': 'text/plain' }, body: 'Not found' }
 }
 
@@ -99,25 +171,36 @@ function handleAuthorizePage(event) {
     button { margin-top: 1rem; width: 100%; padding: 0.7rem; font-size: 0.95rem; font-weight: 500; background: #2563eb; color: white; border: none; border-radius: 0.375rem; cursor: pointer; }
     button:hover { background: #1d4ed8; }
     .hint { font-size: 0.8rem; color: #6b7280; margin-top: 0.5rem; }
+    .err { font-size: 0.85rem; color: #b91c1c; margin: 0.75rem 0 0; }
   </style>
 </head>
 <body>
   <div class="card">
     <h1>Link CamStack to Alexa</h1>
     <p>Enter the public HTTPS URL of your CamStack hub. Alexa will then ask the hub to authorize this Echo.</p>
-    <form id="f">
+    <form id="f" novalidate>
       <label for="hubUrl">Hub URL</label>
       <input id="hubUrl" name="hubUrl" type="url" placeholder="https://camstack.example.com" required autofocus>
       <p class="hint">Must be reachable from the public internet (Cloudflare Tunnel, Tailscale Funnel, etc.).</p>
+      <p id="err" class="err" role="alert" hidden></p>
       <button type="submit">Continue</button>
     </form>
   </div>
   <script>
     document.getElementById('f').addEventListener('submit', function (ev) {
       ev.preventDefault()
-      var hubUrl = document.getElementById('hubUrl').value.trim().replace(/\\/$/, '')
-      if (!hubUrl) return
-      var qs = ${JSON.stringify(qs)}
+      var err = document.getElementById('err')
+      var hubUrl = document.getElementById('hubUrl').value.trim().replace(/\\/+$/, '')
+      var parsed = null
+      try { parsed = new URL(hubUrl) } catch (e) { parsed = null }
+      if (!parsed || parsed.protocol !== 'https:' || !parsed.hostname) {
+        err.textContent = 'Enter the full address of your hub, starting with https:// (for example https://camstack.example.com).'
+        err.hidden = false
+        return
+      }
+      err.hidden = true
+      hubUrl = parsed.origin + parsed.pathname.replace(/\\/+$/, '')
+      var qs = ${jsonForScript(qs)}
       var url = hubUrl + '/api/oauth2/authorize' + '?' + (qs ? qs + '&' : '') + 'integration=export-alexa'
       window.location.href = url
     })
@@ -131,27 +214,47 @@ function handleAuthorizePage(event) {
   }
 }
 
+/** JSON for an inline <script>: `<` escaped so the value cannot close the tag. */
+function jsonForScript(value) {
+  return JSON.stringify(value).replace(/</g, '\\u003c')
+}
+
+/** Constant-time string equality that does not leak length via timing. */
+function safeEqual(a, b) {
+  const ab = Buffer.from(String(a), 'utf8')
+  const bb = Buffer.from(String(b), 'utf8')
+  if (ab.length !== bb.length) {
+    crypto.timingSafeEqual(ab, ab)
+    return false
+  }
+  return crypto.timingSafeEqual(ab, bb)
+}
+
 /**
- * Proxy the OAuth token exchange. Alexa POSTs form-urlencoded body to
- * this Function URL with the client_id/client_secret from the skill
- * manifest; we verify those, decode the code/refresh_token JWT payload
- * to find the hub URL claim, then forward the same body to the hub's
- * own /api/oauth2/token endpoint.
+ * Proxy the OAuth token exchange. Alexa POSTs a form-urlencoded body with the
+ * account-linking client_id/client_secret; we verify those (current secret, or
+ * `previousClientSecret` mid-rotation), decode the code/refresh_token JWT
+ * payload to find the hub URL claim, then forward the body to the hub's own
+ * /api/oauth2/token endpoint.
  */
-async function handleTokenProxy(event) {
+async function handleTokenProxy(event, deps) {
   if (event.requestContext.http.method !== 'POST') {
     return jsonResponse(405, { error: 'method_not_allowed' })
   }
   const body = parseFormUrlEncoded(decodeBody(event))
-  const skillId = process.env.SKILL_CLIENT_ID
-  const skillSecret = process.env.SKILL_CLIENT_SECRET
-  if (!skillId || !skillSecret) {
+  const skill = await deps.secrets.skill()
+  if (!skill) {
     return jsonResponse(500, {
       error: 'unconfigured',
-      message: 'SKILL_CLIENT_ID / SKILL_CLIENT_SECRET not set',
+      message: 'account-linking client credentials are not configured',
     })
   }
-  if (body.client_id !== skillId || body.client_secret !== skillSecret) {
+  const secretOk =
+    typeof body.client_secret === 'string' &&
+    (safeEqual(body.client_secret, skill.clientSecret) ||
+      (skill.previousClientSecret !== undefined &&
+        safeEqual(body.client_secret, skill.previousClientSecret)))
+  if (body.client_id !== skill.clientId || !secretOk) {
     return jsonResponse(401, { error: 'invalid_client', message: 'client credentials mismatch' })
   }
 
@@ -171,7 +274,7 @@ async function handleTokenProxy(event) {
   }
 
   const target = `${normaliseHubUrl(claims.hubUrl)}/api/oauth2/token`
-  const upstream = await timedFetch(target, {
+  const upstream = await deps.fetch(target, {
     method: 'POST',
     headers: { 'content-type': 'application/x-www-form-urlencoded' },
     body: encodeFormUrlEncoded(body),
@@ -186,141 +289,210 @@ async function handleTokenProxy(event) {
 
 // ── Smart Home directives ────────────────────────────────────────────
 
-async function handleDirective(event) {
+async function handleDirective(event, deps) {
   const header = event.directive.header
   const ns = `${header.namespace}/${header.name}`
   if (ns === 'Alexa.Authorization/AcceptGrant') {
-    return handleAcceptGrant(event)
+    return handleAcceptGrant(event, deps)
   }
-  return forwardDirective(event)
+  return forwardDirective(event, deps)
 }
 
-async function handleAcceptGrant(event) {
+function hubHeaders(deps, bearer) {
+  return {
+    'content-type': 'application/json',
+    authorization: `Bearer ${bearer}`,
+    // Defense-in-depth shared secret — the export-alexa "Ingress token"
+    // setting. Sent only when configured; the hub enforces it when the
+    // operator turns on "Require ingress token".
+    ...(deps.env.HUB_INGRESS_TOKEN ? { 'x-camstack-ingress': deps.env.HUB_INGRESS_TOKEN } : {}),
+  }
+}
+
+function brokerAvailable(deps) {
+  return deps.store !== null && typeof deps.publicUrl === 'string'
+}
+
+function acceptGrantResponse(header) {
+  return {
+    event: {
+      header: {
+        namespace: 'Alexa.Authorization',
+        name: 'AcceptGrant.Response',
+        messageId: header.messageId,
+        payloadVersion: '3',
+      },
+      payload: {},
+    },
+  }
+}
+
+async function handleAcceptGrant(event, deps) {
   const header = event.directive.header
   const payload = event.directive.payload || {}
   const grantCode = payload.grant && payload.grant.code
   const granteeToken = payload.grantee && payload.grantee.token
   if (!grantCode || !granteeToken) {
-    return errorEnvelope(
-      header,
-      'ACCEPT_GRANT_FAILED',
-      'payload missing grant.code or grantee.token',
-    )
+    return acceptGrantErrorEnvelope(header, 'payload missing grant.code or grantee.token')
   }
   const claims = decodeJwtPayload(granteeToken)
   if (!claims || typeof claims.hubUrl !== 'string' || claims.hubUrl.length === 0) {
-    return errorEnvelope(header, 'ACCEPT_GRANT_FAILED', 'grantee token has no hubUrl claim')
+    return acceptGrantErrorEnvelope(header, 'grantee token has no hubUrl claim')
+  }
+  const redirectUri = deps.env.LAMBDA_REDIRECT_URI
+  if (!redirectUri) {
+    return acceptGrantErrorEnvelope(header, 'LAMBDA_REDIRECT_URI not set on the Lambda')
   }
 
-  const lwaClientId = process.env.LWA_CLIENT_ID
-  const lwaClientSecret = process.env.LWA_CLIENT_SECRET
-  const redirectUri = process.env.LAMBDA_REDIRECT_URI
-  if (!lwaClientId || !lwaClientSecret || !redirectUri) {
-    return errorEnvelope(
-      header,
-      'ACCEPT_GRANT_FAILED',
-      'LWA_CLIENT_ID / LWA_CLIENT_SECRET / LAMBDA_REDIRECT_URI not set on the Lambda',
+  let tokens
+  try {
+    tokens = await exchangeGrantCode(deps, grantCode, redirectUri)
+  } catch (err) {
+    return acceptGrantErrorEnvelope(header, describe(err))
+  }
+  const hubUrl = normaliseHubUrl(claims.hubUrl)
+
+  if (brokerAvailable(deps)) {
+    const outcome = await linkViaBroker(deps, { hubUrl, granteeToken, tokens })
+    if (outcome.kind === 'linked') return acceptGrantResponse(header)
+    if (outcome.kind !== 'hub-without-broker' || deps.env.LEGACY_HUB_FALLBACK === '0') {
+      return acceptGrantErrorEnvelope(header, outcome.message)
+    }
+    deps.log.warn(
+      'accept_grant: hub has no broker route; falling back to the legacy token hand-off',
     )
   }
+  return deliverTokensToLegacyHub(deps, header, { hubUrl, granteeToken, tokens })
+}
 
-  // Exchange Amazon's grant code for LWA tokens we can hand to the hub
-  // so it can hit the Event Gateway later (proactive doorbell push).
-  const lwaResp = await timedFetch('https://api.amazon.com/auth/o2/token', {
-    method: 'POST',
-    headers: { 'content-type': 'application/x-www-form-urlencoded' },
-    body: encodeFormUrlEncoded({
-      grant_type: 'authorization_code',
-      code: grantCode,
-      client_id: lwaClientId,
-      client_secret: lwaClientSecret,
-      redirect_uri: redirectUri,
-    }),
+/**
+ * The D753 link: store the grant here, give the hub only a credential and a
+ * first access token. The item stays `pending` until the hub accepted it, so a
+ * hub that refuses (or does not have the route) leaves nothing behind.
+ */
+async function linkViaBroker(deps, input) {
+  const { item, credential } = await createLink(deps, {
+    status: 'pending',
+    tokens: input.tokens,
+    hubUrl: input.hubUrl,
+    origin: 'accept-grant',
   })
-  if (!lwaResp.ok) {
-    const text = await lwaResp.text().catch(() => '')
-    return errorEnvelope(header, 'ACCEPT_GRANT_FAILED', `LWA exchange ${lwaResp.status}: ${text}`)
+  let resp
+  try {
+    resp = await deps.fetch(`${input.hubUrl}/addon/export-alexa/oauth/broker-link`, {
+      method: 'POST',
+      headers: hubHeaders(deps, input.granteeToken),
+      body: JSON.stringify({
+        brokerUrl: deps.publicUrl,
+        brokerCredential: credential,
+        lwaAccessToken: item.accessToken,
+        expiresAt: item.accessExpiresAt,
+      }),
+    })
+  } catch (err) {
+    await deps.store.remove(item.linkId)
+    return { kind: 'failed', message: `hub broker-link unreachable: ${describe(err)}` }
+  }
+  if (resp.ok) {
+    await activateLink(deps, item)
+    deps.log.info('accept_grant: linked via broker', { link: shortId(item.linkId) })
+    return { kind: 'linked' }
   }
-  const lwa = await lwaResp.json()
-  const expiresInSec = typeof lwa.expires_in === 'number' ? lwa.expires_in : 3600
+  await deps.store.remove(item.linkId)
+  if (resp.status === 404) return { kind: 'hub-without-broker', message: 'hub broker-link 404' }
+  const text = await resp.text().catch(() => '')
+  return { kind: 'failed', message: `hub broker-link ${resp.status}: ${text.slice(0, 200)}` }
+}
 
-  // Push the tokens back to the hub. The hub authenticates this request
-  // via the bearer (= the same grantee token Alexa just gave us), so it
-  // can attribute the LWA tokens to the right operator user.
-  const hubUrl = normaliseHubUrl(claims.hubUrl)
-  const callback = `${hubUrl}/addon/export-alexa/oauth/lwa-tokens`
-  const callbackResp = await timedFetch(callback, {
+/** Pre-D753 hand-off: the hub receives the refresh token itself. */
+async function deliverTokensToLegacyHub(deps, header, input) {
+  const callbackResp = await deps.fetch(`${input.hubUrl}/addon/export-alexa/oauth/lwa-tokens`, {
     method: 'POST',
-    headers: {
-      'content-type': 'application/json',
-      authorization: `Bearer ${granteeToken}`,
-      ...(process.env.HUB_INGRESS_TOKEN
-        ? { 'x-camstack-ingress': process.env.HUB_INGRESS_TOKEN }
-        : {}),
-    },
+    headers: hubHeaders(deps, input.granteeToken),
     body: JSON.stringify({
-      lwaAccessToken: lwa.access_token,
-      lwaRefreshToken: lwa.refresh_token,
-      expiresAt: Date.now() + expiresInSec * 1000,
+      lwaAccessToken: input.tokens.accessToken,
+      lwaRefreshToken: input.tokens.refreshToken,
+      expiresAt: deps.now() + input.tokens.expiresInSec * 1000,
     }),
   })
   if (!callbackResp.ok) {
     const text = await callbackResp.text().catch(() => '')
-    return errorEnvelope(
+    return acceptGrantErrorEnvelope(
       header,
-      'ACCEPT_GRANT_FAILED',
-      `hub callback ${callbackResp.status}: ${text}`,
+      `hub callback ${callbackResp.status}: ${text.slice(0, 200)}`,
     )
   }
+  return acceptGrantResponse(header)
+}
 
-  return {
-    event: {
-      header: {
-        namespace: 'Alexa.Authorization',
-        name: 'AcceptGrant.Response',
-        messageId: header.messageId,
-        payloadVersion: '3',
-      },
-      payload: {},
-    },
-  }
+/** HTTP statuses that mean the hub itself is down or unreachable behind its tunnel. */
+function isBridgeDownStatus(status) {
+  return status === 502 || status === 503 || status === 504 || (status >= 520 && status <= 530)
 }
 
-async function forwardDirective(event) {
-  const header = event.directive.header
-  const bearer = extractBearer(event.directive)
+async function forwardDirective(event, deps) {
+  const directive = event.directive
+  const header = directive.header
+  const endpoint = directive.endpoint
+  const bearer = extractBearer(directive)
   if (!bearer) {
     return errorEnvelope(
       header,
       'INVALID_AUTHORIZATION_CREDENTIAL',
       'directive has no bearer token',
+      endpoint,
     )
   }
   const claims = decodeJwtPayload(bearer)
   if (!claims || typeof claims.hubUrl !== 'string' || claims.hubUrl.length === 0) {
-    return errorEnvelope(header, 'INVALID_AUTHORIZATION_CREDENTIAL', 'bearer has no hubUrl claim')
+    return errorEnvelope(
+      header,
+      'INVALID_AUTHORIZATION_CREDENTIAL',
+      'bearer has no hubUrl claim',
+      endpoint,
+    )
   }
   const target = `${normaliseHubUrl(claims.hubUrl)}/addon/export-alexa/directive`
-  const directiveHeaders = {
-    'content-type': 'application/json',
-    authorization: `Bearer ${bearer}`,
-    // Defense-in-depth shared secret — the export-alexa "Ingress token"
-    // setting. Sent only when configured; the hub enforces it when the
-    // operator turns on "Require ingress token".
-    ...(process.env.HUB_INGRESS_TOKEN
-      ? { 'x-camstack-ingress': process.env.HUB_INGRESS_TOKEN }
-      : {}),
+  let resp
+  try {
+    resp = await deps.fetch(target, {
+      method: 'POST',
+      headers: {
+        ...hubHeaders(deps, bearer),
+        // Where this skill's broker lives. A hub linked before D753 uses it to
+        // migrate its refresh token here (zero-touch); the hub only believes it
+        // on a directive whose bearer it verified.
+        ...(brokerAvailable(deps) ? { [BROKER_HEADER]: deps.publicUrl } : {}),
+      },
+      body: JSON.stringify(event),
+    })
+  } catch (err) {
+    // The hub is the bridge every endpoint sits behind (alexa-errorresponse).
+    return errorEnvelope(
+      header,
+      'BRIDGE_UNREACHABLE',
+      `hub unreachable: ${describe(err)}`,
+      endpoint,
+    )
   }
-  const resp = await timedFetch(target, {
-    method: 'POST',
-    headers: directiveHeaders,
-    body: JSON.stringify(event),
-  })
   const text = await resp.text()
+  let parsed
   try {
-    return JSON.parse(text)
+    parsed = JSON.parse(text)
   } catch {
-    return errorEnvelope(header, 'INTERNAL_ERROR', `hub returned non-JSON: ${text.slice(0, 256)}`)
+    const type = isBridgeDownStatus(resp.status) ? 'BRIDGE_UNREACHABLE' : 'INTERNAL_ERROR'
+    return errorEnvelope(header, type, `hub returned ${resp.status}, non-JSON`, endpoint)
   }
+  if (!parsed || typeof parsed !== 'object' || !parsed.event || !parsed.event.header) {
+    // e.g. `{ error: 'invalid_ingress_token' }` — never hand Alexa a non-event.
+    return errorEnvelope(
+      header,
+      'INTERNAL_ERROR',
+      `hub returned ${resp.status} without an Alexa event`,
+      endpoint,
+    )
+  }
+  return completeErrorResponse(parsed, directive)
 }
 
 function extractBearer(directive) {
@@ -341,227 +513,6 @@ function extractBearer(directive) {
   return null
 }
 
-// ── Helpers ──────────────────────────────────────────────────────────
-
-function decodeJwtPayload(token) {
-  if (typeof token !== 'string') return null
-  const parts = token.split('.')
-  if (parts.length < 2) return null
-  try {
-    const padded = parts[1].replace(/-/g, '+').replace(/_/g, '/')
-    const json = Buffer.from(padded, 'base64').toString('utf8')
-    return JSON.parse(json)
-  } catch {
-    return null
-  }
-}
-
-function normaliseHubUrl(raw) {
-  return raw.replace(/\/+$/, '')
-}
-
-function decodeBody(event) {
-  if (!event.body) return ''
-  if (event.isBase64Encoded) {
-    return Buffer.from(event.body, 'base64').toString('utf8')
-  }
-  return event.body
-}
-
-function parseFormUrlEncoded(body) {
-  const out = {}
-  if (!body) return out
-  for (const pair of body.split('&')) {
-    if (!pair) continue
-    const eq = pair.indexOf('=')
-    const key = decodeURIComponent(eq >= 0 ? pair.slice(0, eq) : pair).replace(/\+/g, ' ')
-    const value = decodeURIComponent(eq >= 0 ? pair.slice(eq + 1) : '').replace(/\+/g, ' ')
-    out[key] = value
-  }
-  return out
-}
-
-function encodeFormUrlEncoded(obj) {
-  return Object.keys(obj)
-    .filter((k) => obj[k] !== undefined && obj[k] !== null)
-    .map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(String(obj[k]))}`)
-    .join('&')
-}
-
-async function timedFetch(url, init = {}) {
-  // Returns a fetch-compatible response object: { ok, status, statusText,
-  // text(), json() }. The handler only uses .text() / status.
-  //
-  // Emits a single structured timing log line on completion (or failure),
-  // measuring DNS / TCP / TLS / request-sent / first-byte / last-byte sub-
-  // timings. Read these from CloudWatch with:
-  //   filter @message like /timedFetch_timing/
-  // to see end-to-end where the wall-clock seconds go (DNS hang vs TCP RTT
-  // vs TLS handshake vs hub processing time vs body download).
-  return new Promise((resolve, reject) => {
-    let settled = false
-    const parsed = new URL(url)
-    const isHttps = parsed.protocol === 'https:'
-    const lib = isHttps ? https : http
-    const headers = { ...(init.headers || {}), connection: 'close' }
-    if (init.body !== undefined && headers['content-length'] === undefined) {
-      headers['content-length'] = Buffer.byteLength(init.body)
-    }
-    const T0 = process.hrtime.bigint()
-    const marks = {
-      dns: null,
-      tcpConnect: null,
-      tlsHandshake: null,
-      requestSent: null,
-      firstByte: null,
-      lastByte: null,
-    }
-    const ms = (a, b) => Number((b - a) / 1_000_000n)
-    const logTiming = (status, extras = {}) => {
-      const T_end = process.hrtime.bigint()
-      const total = ms(T0, T_end)
-      const stages = {
-        dns: marks.dns ? ms(T0, marks.dns) : null,
-        tcp: marks.tcpConnect ? ms(T0, marks.tcpConnect) : null,
-        tls: marks.tlsHandshake ? ms(T0, marks.tlsHandshake) : null,
-        reqSent: marks.requestSent ? ms(T0, marks.requestSent) : null,
-        firstByte: marks.firstByte ? ms(T0, marks.firstByte) : null,
-        lastByte: marks.lastByte ? ms(T0, marks.lastByte) : null,
-      }
-      // Stage durations between marks, easier to read at a glance:
-      const between = {
-        dns_ms: stages.dns,
-        tcp_handshake_ms:
-          stages.tcp != null && stages.dns != null ? stages.tcp - stages.dns : stages.tcp,
-        tls_handshake_ms: stages.tls != null && stages.tcp != null ? stages.tls - stages.tcp : null,
-        request_send_ms:
-          stages.reqSent != null && (stages.tls ?? stages.tcp) != null
-            ? stages.reqSent - (stages.tls ?? stages.tcp)
-            : null,
-        wait_first_byte_ms:
-          stages.firstByte != null && stages.reqSent != null
-            ? stages.firstByte - stages.reqSent
-            : null,
-        download_ms:
-          stages.lastByte != null && stages.firstByte != null
-            ? stages.lastByte - stages.firstByte
-            : null,
-      }
-      console.log(
-        'timedFetch_timing',
-        JSON.stringify({
-          url: `${parsed.protocol}//${parsed.hostname}${parsed.pathname}`,
-          method: (init.method || 'GET').toUpperCase(),
-          status,
-          total_ms: total,
-          stages_cum_ms: stages,
-          between_ms: between,
-          ...extras,
-        }),
-      )
-    }
-    const req = lib.request(
-      {
-        protocol: parsed.protocol,
-        hostname: parsed.hostname,
-        port: parsed.port || (isHttps ? 443 : 80),
-        path: `${parsed.pathname}${parsed.search}`,
-        method: (init.method || 'GET').toUpperCase(),
-        headers,
-        agent: isHttps ? NO_KEEPALIVE_AGENT : undefined,
-      },
-      (res) => {
-        marks.firstByte = process.hrtime.bigint()
-        const chunks = []
-        res.on('data', (c) => chunks.push(c))
-        res.on('end', () => {
-          if (settled) return
-          settled = true
-          clearTimeout(timer)
-          marks.lastByte = process.hrtime.bigint()
-          const body = Buffer.concat(chunks).toString('utf8')
-          const headersApi = {
-            get: (name) => {
-              const v = res.headers[String(name).toLowerCase()]
-              if (Array.isArray(v)) return v.join(', ')
-              return v == null ? null : String(v)
-            },
-          }
-          logTiming(res.statusCode, { responseBodyBytes: body.length })
-          resolve({
-            ok: res.statusCode >= 200 && res.statusCode < 300,
-            status: res.statusCode,
-            statusText: res.statusMessage || '',
-            headers: headersApi,
-            text: async () => body,
-            json: async () => JSON.parse(body),
-          })
-        })
-        res.on('error', (err) => {
-          if (settled) return
-          settled = true
-          clearTimeout(timer)
-          logTiming('res_error', { error: err && err.message })
-          reject(err)
-        })
-      },
-    )
-    req.on('socket', (socket) => {
-      socket.on('lookup', () => {
-        marks.dns = process.hrtime.bigint()
-      })
-      socket.on('connect', () => {
-        marks.tcpConnect = process.hrtime.bigint()
-      })
-      socket.on('secureConnect', () => {
-        marks.tlsHandshake = process.hrtime.bigint()
-      })
-    })
-    req.on('finish', () => {
-      marks.requestSent = process.hrtime.bigint()
-    })
-    req.on('error', (err) => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      logTiming('req_error', { error: err && err.message, code: err && err.code })
-      reject(err)
-    })
-    const timer = setTimeout(() => {
-      if (settled) return
-      settled = true
-      req.destroy(new Error(`timedFetch timeout after ${FETCH_TIMEOUT_MS}ms`))
-      logTiming('timeout', { timeout_ms: FETCH_TIMEOUT_MS })
-      reject(new Error(`timedFetch timeout after ${FETCH_TIMEOUT_MS}ms`))
-    }, FETCH_TIMEOUT_MS)
-    if (init.body !== undefined) req.write(init.body)
-    req.end()
-  })
-}
-
-function jsonResponse(statusCode, body) {
-  return {
-    statusCode,
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify(body),
-  }
-}
-
-function errorEnvelope(header, type, message) {
-  return {
-    event: {
-      header: {
-        namespace: 'Alexa',
-        name: 'ErrorResponse',
-        messageId: header.messageId,
-        payloadVersion: '3',
-      },
-      payload: { type, message },
-    },
-  }
-}
-
-function describe(err) {
-  if (err instanceof Error) return err.message
-  return String(err)
-}
+exports.handler = createHandler()
+exports.createHandler = createHandler
+exports.BROKER_HEADER = BROKER_HEADER