@camstack/addon-export-alexa 1.2.133 → 1.2.135

package/lambda-template/README.md

@@ -22,20 +22,29 @@ The same code runs the built-in CamStack skill and any operator's own
 | `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 |
+| Pair | SSM parameter (SecureString) | 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 |
+| **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:
+Each parameter is a **SecureString** (standard tier, AWS-managed key
+`alias/aws/ssm`) whose value is a JSON string:
 
 ```json
 { "clientId": "…", "clientSecret": "…" }
 ```
 
-`camstack/alexa/skill` may also carry `"previousClientSecret"` — accepted on
+`/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).
 
@@ -69,10 +78,18 @@ your skill's locale: NA → `us-east-1`, EU/IN → `eu-west-1`, FE/AU → `us-we
    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.
+4. **SSM Parameter Store** (free standard tier): in the Lambda's region,
+   Systems Manager → Parameter Store → **Create parameter**, twice:
+   - Name `/camstack/alexa/lwa`, then `/camstack/alexa/skill`
+   - Tier **Standard**, Type **SecureString**
+   - KMS key source **My current account**, KMS key ID `alias/aws/ssm`
+   - Value: the JSON above.
+
+   Enter the values in the console, or with `aws ssm put-parameter --type
+   SecureString --value file://…` from a file you delete afterwards — never as
+   a literal command-line argument. The Lambda reads them with `GetParameter`
+   and `WithDecryption: true`, caches them for 5 minutes, and re-reads the LWA
+   pair at once when LWA answers `invalid_client`.
 5. **DynamoDB**:
 
    ```bash
@@ -94,10 +111,22 @@ your skill's locale: NA → `us-east-1`, EU/IN → `eu-west-1`, FE/AU → `us-we
      "Version": "2012-10-17",
      "Statement": [
        {
-         "Sid": "ReadSkillSecrets",
+         "Sid": "ReadSkillParameters",
+         "Effect": "Allow",
+         "Action": "ssm:GetParameter",
+         "Resource": "arn:aws:ssm:REGION:ACCOUNT:parameter/camstack/alexa/*"
+       },
+       {
+         "Sid": "DecryptSkillParametersViaSsm",
          "Effect": "Allow",
-         "Action": "secretsmanager:GetSecretValue",
-         "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:camstack/alexa/*"
+         "Action": "kms:Decrypt",
+         "Resource": "arn:aws:kms:REGION:ACCOUNT:key/AWS_SSM_KEY_ID",
+         "Condition": {
+           "StringEquals": { "kms:ViaService": "ssm.REGION.amazonaws.com" },
+           "StringLike": {
+             "kms:EncryptionContext:PARAMETER_ARN": "arn:aws:ssm:REGION:ACCOUNT:parameter/camstack/alexa/*"
+           }
+         }
        },
        {
          "Sid": "BrokerLinks",
@@ -109,25 +138,32 @@ your skill's locale: NA → `us-east-1`, EU/IN → `eu-west-1`, FE/AU → `us-we
    }
    ```
 
-   The default `aws/secretsmanager` and `aws/dynamodb` keys need no extra KMS
-   permission. A customer-managed key would need `kms:Decrypt` on it.
+   `AWS_SSM_KEY_ID` is the id of the AWS-managed `alias/aws/ssm` key (KMS
+   console → AWS managed keys, or `aws kms describe-key --key-id
+   alias/aws/ssm`). AWS's guidance on whether the AWS-managed key needs a
+   `kms:Decrypt` grant is inconsistent — its key policy already lets account
+   principals decrypt through SSM — so the statement is included, and scoped so
+   it can only decrypt these two parameters, and only through SSM. A
+   customer-managed key would need the same statement on that key instead. The
+   default `aws/dynamodb` key needs no extra permission.
 
 7. **Environment variables** (none is a secret):
 
 | Name | Value |
 | --- | --- |
-| `LWA_SECRET_ID` | `camstack/alexa/lwa` |
-| `SKILL_SECRET_ID` | `camstack/alexa/skill` |
+| `LWA_PARAM` | `/camstack/alexa/lwa` |
+| `SKILL_PARAM` | `/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. |
+| `DEBUG_DIRECTIVES` | `1` = one `directive_trace` log line per Smart Home directive: namespace / name / endpointId / payloadVersion / payload keys asked, and the answered event (ErrorResponse type and message, StateReport property names and value shapes). Never the bearer token or SDP bodies. Diagnostic; default off. |
 | `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`,
+Legacy, read only when the matching `*_PARAM` is unset: `LWA_CLIENT_ID`,
 `LWA_CLIENT_SECRET`, `SKILL_CLIENT_ID`, `SKILL_CLIENT_SECRET`. Remove them once
-the secrets are in Secrets Manager.
+the parameters exist and `*_PARAM` is set.
 
 ## Skill manifest
 
@@ -137,10 +173,10 @@ the secrets are in Secrets Manager.
 | 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 |
+| | 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` |
+| Permissions | Send Alexa Events | on; its Alexa Client Id/Secret go into `/camstack/alexa/lwa` |
 
 ## Cut-over and compatibility
 
@@ -167,5 +203,5 @@ 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`
+Lambda against fake LWA, hub, SSM Parameter Store and DynamoDB (`npx vitest run`
 in the addon).

package/lambda-template/aws.js

@@ -1,37 +1,53 @@
 /**
- * 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.
+ * Default AWS wiring. The Lambda Node.js 22 runtime ships AWS SDK v3
+ * (`@aws-sdk/client-ssm`, `@aws-sdk/client-dynamodb`), so the deployment stays
+ * a zip of plain files with no node_modules. Required lazily: tests inject a
+ * fake `loadSdk` 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
+ *   ssm:GetParameter                     on parameter/camstack/alexa/*
+ *   kms:Decrypt                          on the `aws/ssm` key, only via SSM and
+ *                                        only for those parameters (D761)
+ *   dynamodb:GetItem/PutItem/DeleteItem  on the tokens table
  */
 'use strict'
 
-function createAwsClients() {
+/**
+ * @param {object} [opts]
+ * @param {(name: string) => any} [opts.loadSdk]  module loader (tests inject a fake)
+ */
+function createAwsClients(opts) {
+  const loadSdk = (opts && opts.loadSdk) || require
   let ddbClient = null
-  let smClient = null
+  let ssmClient = null
+  let ssmSdk = null
 
   async function send(commandName, input) {
-    const ddb = require('@aws-sdk/client-dynamodb')
+    const ddb = loadSdk('@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`)
+  /**
+   * The decrypted value of one SecureString parameter. Errors name the
+   * parameter, never a value.
+   */
+  async function readParameter(name) {
+    if (!ssmSdk) ssmSdk = loadSdk('@aws-sdk/client-ssm')
+    if (!ssmClient) ssmClient = new ssmSdk.SSMClient({})
+    const res = await ssmClient.send(
+      new ssmSdk.GetParameterCommand({ Name: name, WithDecryption: true }),
+    )
+    const value = res && res.Parameter ? res.Parameter.Value : undefined
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new Error(`parameter ${name} has no value`)
     }
-    return res.SecretString
+    return value
   }
 
-  return { send, fetchSecretString }
+  return { send, readParameter }
 }
 
 module.exports = { createAwsClients }

package/lambda-template/broker.js

@@ -4,7 +4,7 @@
  * 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
+ * an SSM SecureString parameter), 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
@@ -119,7 +119,7 @@ function lwaErrorCode(res) {
 
 /**
  * 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
+ * `invalid_client` with a Parameter-Store-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.
  */
@@ -129,7 +129,7 @@ async function lwaTokenCall(deps, params) {
     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') {
+  if (lwaErrorCode(res) === 'invalid_client' && creds.source === 'ssm') {
     deps.secrets.invalidate('lwa')
     const fresh = await deps.secrets.lwa()
     if (fresh && fresh.clientSecret !== creds.clientSecret) {

package/lambda-template/debug-trace.js

@@ -0,0 +1,100 @@
+'use strict'
+
+/**
+ * TEMPORARY diagnostic, on only with `DEBUG_DIRECTIVES=1`: one `directive_trace`
+ * line per Smart Home directive — what Alexa asked and what the skill answered.
+ *
+ * Built from an allow-list of fields, never by dumping the event: the
+ * directive's `scope.token` (the account's bearer) and the SDP bodies never
+ * reach the log. StateReport property values are summarised (a short scalar,
+ * or the object's keys and scalar values) — they are device states, not
+ * credentials.
+ */
+
+const MAX_VALUE_CHARS = 60
+
+function isEnabled(env) {
+  return Boolean(env) && env.DEBUG_DIRECTIVES === '1'
+}
+
+function str(value) {
+  return typeof value === 'string' ? value : undefined
+}
+
+function summariseValue(value) {
+  if (value === null || value === undefined) return String(value)
+  if (typeof value !== 'object') return String(value).slice(0, MAX_VALUE_CHARS)
+  if (Array.isArray(value)) return `[array:${value.length}]`
+  const parts = Object.keys(value).map((k) => {
+    const v = value[k]
+    return v !== null && typeof v === 'object' ? `${k}:{…}` : `${k}:${String(v)}`
+  })
+  return `{${parts.join(',')}}`.slice(0, MAX_VALUE_CHARS)
+}
+
+function payloadShape(payload) {
+  if (!payload || typeof payload !== 'object') return undefined
+  return Object.keys(payload)
+    .filter((k) => k !== 'scope')
+    .map((k) => {
+      const v = payload[k]
+      if (v && typeof v === 'object' && typeof v.value === 'string') {
+        // RTC offers/answers: { format, value: <SDP> } — length only.
+        return `${k}(${str(v.format) || 'object'},${v.value.length}b)`
+      }
+      return k
+    })
+}
+
+function summariseDirective(event) {
+  const d = (event && event.directive) || {}
+  const h = d.header || {}
+  const ep = d.endpoint || {}
+  return {
+    namespace: str(h.namespace),
+    name: str(h.name),
+    endpointId: str(ep.endpointId),
+    payloadVersion: str(h.payloadVersion),
+    payloadKeys: payloadShape(d.payload),
+  }
+}
+
+function summariseResponse(body) {
+  const ev = body && body.event
+  if (!ev || !ev.header) return { kind: 'non-event' }
+  const out = {
+    namespace: str(ev.header.namespace),
+    name: str(ev.header.name),
+    endpointId: str(ev.endpoint && ev.endpoint.endpointId),
+  }
+  const payload = ev.payload || {}
+  if (out.name === 'ErrorResponse') {
+    out.errorType = str(payload.type)
+    out.errorMessage = str(payload.message)
+  } else {
+    out.payloadKeys = payloadShape(payload)
+  }
+  const props = body.context && Array.isArray(body.context.properties) ? body.context.properties : null
+  if (props) {
+    out.properties = props.map(
+      (p) => `${str(p && p.namespace)}.${str(p && p.name)}=${summariseValue(p && p.value)}`,
+    )
+  }
+  return out
+}
+
+/** Log one trace line; never throws into the directive path. */
+function traceDirective(deps, event, response, startedAt) {
+  if (!isEnabled(deps.env)) return
+  try {
+    deps.log.info('directive_trace', {
+      directive: summariseDirective(event),
+      response: summariseResponse(response),
+      ms: deps.now() - startedAt,
+    })
+  } catch {
+    // diagnostics only
+  }
+}
+
+module.exports = { traceDirective, summariseDirective, summariseResponse }

package/lambda-template/index.js

@@ -19,10 +19,13 @@
  *      - everything else                 → forward to the hub
  *
  * 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.
+ *   LWA_PARAM            SSM SecureString parameter name (e.g.
+ *                        /camstack/alexa/lwa) holding {"clientId","clientSecret"}
+ *                        for the skill's "Send Alexa Events" LWA client.
+ *   SKILL_PARAM          SSM SecureString parameter name (e.g.
+ *                        /camstack/alexa/skill) holding {"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.
@@ -31,7 +34,9 @@
  *                        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,
+ *   DEBUG_DIRECTIVES     "1" = log one `directive_trace` line per directive
+ *                        (debug-trace.js; never the bearer). Default off.
+ * Legacy (read only when the *_PARAM is unset): LWA_CLIENT_ID,
  * LWA_CLIENT_SECRET, SKILL_CLIENT_ID, SKILL_CLIENT_SECRET.
  *
  * Ships as plain files — no node_modules, no transpile (`zip` the folder's
@@ -50,11 +55,14 @@ const {
   isBrokerPath,
   shortId,
 } = require('./broker.js')
+const { traceDirective } = require('./debug-trace.js')
 const { timedFetch } = require('./http.js')
 const { createSecretSource } = require('./secrets.js')
 const { createDynamoTokenStore } = require('./token-store.js')
 const {
   decodeBody,
+  acceptGrantErrorEnvelope,
+  completeErrorResponse,
   decodeJwtPayload,
   describe,
   encodeFormUrlEncoded,
@@ -99,7 +107,7 @@ function resolveDeps(overrides) {
       o.secrets ||
       createSecretSource({
         env,
-        fetchSecretString: (id) => awsClients().fetchSecretString(id),
+        readParameter: (name) => awsClients().readParameter(name),
       }),
     store,
     publicUrl: resolveBrokerPublicUrl(env),
@@ -110,18 +118,28 @@ function createHandler(overrides) {
   let deps = null
   return async (event) => {
     if (!deps) deps = resolveDeps(overrides)
+    const startedAt = deps.now()
     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)
+        const res = await handleDirective(event, deps)
+        traceDirective(deps, event, res, startedAt)
+        return res
       }
       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))
+        const res = errorEnvelope(
+          event.directive.header,
+          'INTERNAL_ERROR',
+          describe(err),
+          event.directive.endpoint,
+        )
+        traceDirective(deps, event, res, startedAt)
+        return res
       }
       return jsonResponse(500, { error: 'internal_error', message: describe(err) })
     }
@@ -164,25 +182,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
     })
@@ -196,6 +225,11 @@ 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')
@@ -310,22 +344,22 @@ async function handleAcceptGrant(event, deps) {
   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 errorEnvelope(header, 'ACCEPT_GRANT_FAILED', 'LAMBDA_REDIRECT_URI not set on the Lambda')
+    return acceptGrantErrorEnvelope(header, 'LAMBDA_REDIRECT_URI not set on the Lambda')
   }
 
   let tokens
   try {
     tokens = await exchangeGrantCode(deps, grantCode, redirectUri)
   } catch (err) {
-    return errorEnvelope(header, 'ACCEPT_GRANT_FAILED', describe(err))
+    return acceptGrantErrorEnvelope(header, describe(err))
   }
   const hubUrl = normaliseHubUrl(claims.hubUrl)
 
@@ -333,9 +367,11 @@ async function handleAcceptGrant(event, 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 errorEnvelope(header, 'ACCEPT_GRANT_FAILED', outcome.message)
+      return acceptGrantErrorEnvelope(header, outcome.message)
     }
-    deps.log.warn('accept_grant: hub has no broker route; falling back to the legacy token hand-off')
+    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 })
 }
@@ -392,43 +428,82 @@ async function deliverTokensToLegacyHub(deps, header, input) {
   })
   if (!callbackResp.ok) {
     const text = await callbackResp.text().catch(() => '')
-    return errorEnvelope(
+    return acceptGrantErrorEnvelope(
       header,
-      'ACCEPT_GRANT_FAILED',
       `hub callback ${callbackResp.status}: ${text.slice(0, 200)}`,
     )
   }
   return acceptGrantResponse(header)
 }
 
+/** 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, deps) {
-  const header = event.directive.header
-  const bearer = extractBearer(event.directive)
+  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')
+    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 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),
-  })
+  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 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) {