@camstack/addon-export-alexa 1.2.132 → 1.2.134

package/lambda-template/secrets.js

@@ -0,0 +1,105 @@
+/**
+ * Skill credentials, read where they live: AWS Secrets Manager (D753).
+ *
+ * Two credential pairs exist, and they authenticate DIFFERENT parties:
+ *
+ *   lwa    The skill's "Send Alexa Events" (Alexa Skill Messaging) LWA client.
+ *          Authenticates THIS Lambda to api.amazon.com when it exchanges an
+ *          AcceptGrant code and when it refreshes a user's grant. It is the
+ *          one that must never leave the Lambda.
+ *   skill  The account-linking client id/secret typed into the skill's
+ *          Account Linking page. Authenticates AMAZON to this Lambda's
+ *          `/token` route. Amazon holds a copy; nothing else needs one.
+ *
+ * Each secret is a JSON string `{"clientId": "...", "clientSecret": "..."}`.
+ * `skill` may also carry `previousClientSecret`, accepted on `/token` while a
+ * rotation is in flight (change Amazon's copy, then drop the previous one).
+ *
+ * Resolution, per pair:
+ *   1. `<KIND>_SECRET_ID` set   → Secrets Manager, cached for `ttlMs`.
+ *   2. otherwise                → the legacy plain env vars
+ *                                 (`LWA_CLIENT_ID`/`LWA_CLIENT_SECRET`,
+ *                                 `SKILL_CLIENT_ID`/`SKILL_CLIENT_SECRET`), so
+ *                                 this code can be deployed before the secrets
+ *                                 exist and the cut-over has no downtime.
+ *
+ * The cache is what makes a rotation cheap: a new value is picked up within
+ * `ttlMs`, and immediately when LWA answers `invalid_client` (the caller calls
+ * `invalidate`). Error messages name the secret id, never a value.
+ */
+'use strict'
+
+const DEFAULT_SECRET_TTL_MS = 5 * 60 * 1000
+
+const KINDS = {
+  lwa: { secretIdVar: 'LWA_SECRET_ID', idVar: 'LWA_CLIENT_ID', secretVar: 'LWA_CLIENT_SECRET' },
+  skill: {
+    secretIdVar: 'SKILL_SECRET_ID',
+    idVar: 'SKILL_CLIENT_ID',
+    secretVar: 'SKILL_CLIENT_SECRET',
+  },
+}
+
+/**
+ * @param {object} opts
+ * @param {Record<string, string|undefined>} opts.env
+ * @param {(secretId: string) => Promise<string>} opts.fetchSecretString
+ * @param {() => number} [opts.now]
+ * @param {number} [opts.ttlMs]
+ */
+function createSecretSource(opts) {
+  const env = opts.env
+  const now = opts.now || Date.now
+  const ttlMs = typeof opts.ttlMs === 'number' ? opts.ttlMs : DEFAULT_SECRET_TTL_MS
+  const cache = new Map()
+
+  async function load(kind) {
+    const spec = KINDS[kind]
+    const secretId = env[spec.secretIdVar]
+    if (secretId) {
+      const hit = cache.get(kind)
+      if (hit && now() - hit.at < ttlMs) return hit.value
+      const raw = await opts.fetchSecretString(secretId)
+      const value = parseCredentialSecret(raw, secretId)
+      cache.set(kind, { value, at: now() })
+      return value
+    }
+    const clientId = env[spec.idVar]
+    const clientSecret = env[spec.secretVar]
+    if (clientId && clientSecret) return { clientId, clientSecret, source: 'env' }
+    return null
+  }
+
+  return {
+    lwa: () => load('lwa'),
+    skill: () => load('skill'),
+    invalidate: (kind) => {
+      cache.delete(kind)
+    },
+  }
+}
+
+function parseCredentialSecret(raw, secretId) {
+  let obj
+  try {
+    obj = JSON.parse(raw)
+  } catch {
+    throw new Error(`secret ${secretId} is not a JSON object`)
+  }
+  if (
+    !obj ||
+    typeof obj.clientId !== 'string' ||
+    obj.clientId.length === 0 ||
+    typeof obj.clientSecret !== 'string' ||
+    obj.clientSecret.length === 0
+  ) {
+    throw new Error(`secret ${secretId} must be {"clientId": "...", "clientSecret": "..."}`)
+  }
+  const out = { clientId: obj.clientId, clientSecret: obj.clientSecret, source: 'secrets-manager' }
+  if (typeof obj.previousClientSecret === 'string' && obj.previousClientSecret.length > 0) {
+    out.previousClientSecret = obj.previousClientSecret
+  }
+  return out
+}
+
+module.exports = { createSecretSource, parseCredentialSecret, DEFAULT_SECRET_TTL_MS }

package/lambda-template/token-store.js

@@ -0,0 +1,142 @@
+/**
+ * Broker link store — one DynamoDB item per hub link (D753).
+ *
+ * Table `camstack-alexa-tokens` (name from `TOKENS_TABLE`), partition key
+ * `linkId` (S), TTL attribute `ttl` (epoch SECONDS), encrypted at rest (SSE,
+ * KMS). An item is the Lambda's half of one hub's Alexa push grant:
+ *
+ *   linkId           random 128-bit id — the public half of the hub credential
+ *   secretHash       sha256(hex) of the credential's secret half; the secret
+ *                    itself is never stored
+ *   status           'pending' (AcceptGrant in flight) | 'active'
+ *   refreshToken     the user's LWA refresh token — NEVER leaves the Lambda
+ *   accessToken      cached LWA access token (handed to the hub on request)
+ *   accessExpiresAt  ms epoch
+ *   hubUrl           informational: the hub the link was made for
+ *   origin           'accept-grant' | 'migration'
+ *   createdAt, lastUsedAt  ms epoch
+ *   ttl              s epoch; pending links expire in 1h, active ones after
+ *                    an idle period (bumped on every refresh)
+ *   version          optimistic-concurrency counter; every write is
+ *                    conditional on it, so two concurrent refreshes never
+ *                    clobber each other's rotated refresh token
+ *
+ * The store is an interface (`get`/`create`/`replace`/`remove`) so the broker
+ * is tested against an in-memory implementation and the DynamoDB marshalling
+ * is tested on its own.
+ */
+'use strict'
+
+const STRING_FIELDS = [
+  'linkId',
+  'secretHash',
+  'status',
+  'refreshToken',
+  'accessToken',
+  'hubUrl',
+  'origin',
+]
+const NUMBER_FIELDS = ['accessExpiresAt', 'createdAt', 'lastUsedAt', 'ttl', 'version']
+
+function marshal(item) {
+  const out = {}
+  for (const k of STRING_FIELDS) {
+    if (typeof item[k] === 'string') out[k] = { S: item[k] }
+  }
+  for (const k of NUMBER_FIELDS) {
+    if (typeof item[k] === 'number' && Number.isFinite(item[k])) out[k] = { N: String(item[k]) }
+  }
+  return out
+}
+
+function unmarshal(raw) {
+  if (!raw) return null
+  const out = {}
+  for (const k of STRING_FIELDS) {
+    if (raw[k] && typeof raw[k].S === 'string') out[k] = raw[k].S
+  }
+  for (const k of NUMBER_FIELDS) {
+    if (raw[k] && typeof raw[k].N === 'string') out[k] = Number(raw[k].N)
+  }
+  return out
+}
+
+function isConditionalFailure(err) {
+  return Boolean(err) && err.name === 'ConditionalCheckFailedException'
+}
+
+/**
+ * @param {object} opts
+ * @param {(command: 'GetItem'|'PutItem'|'DeleteItem', input: object) => Promise<any>} opts.send
+ * @param {string} opts.tableName
+ */
+function createDynamoTokenStore(opts) {
+  const TableName = opts.tableName
+  const send = opts.send
+  return {
+    async get(linkId) {
+      const res = await send('GetItem', {
+        TableName,
+        Key: { linkId: { S: linkId } },
+        ConsistentRead: true,
+      })
+      return unmarshal(res && res.Item)
+    },
+    async create(item) {
+      await send('PutItem', {
+        TableName,
+        Item: marshal(item),
+        ConditionExpression: 'attribute_not_exists(linkId)',
+      })
+    },
+    /** Replace the whole item iff its stored version is `expectedVersion`. */
+    async replace(item, expectedVersion) {
+      try {
+        await send('PutItem', {
+          TableName,
+          Item: marshal(item),
+          ConditionExpression: 'version = :v',
+          ExpressionAttributeValues: { ':v': { N: String(expectedVersion) } },
+        })
+        return true
+      } catch (err) {
+        if (isConditionalFailure(err)) return false
+        throw err
+      }
+    },
+    async remove(linkId) {
+      await send('DeleteItem', { TableName, Key: { linkId: { S: linkId } } })
+    },
+  }
+}
+
+/** In-memory store with the same contract — tests, and local runs. */
+function createMemoryTokenStore() {
+  const items = new Map()
+  return {
+    items,
+    async get(linkId) {
+      const it = items.get(linkId)
+      return it ? { ...it } : null
+    },
+    async create(item) {
+      if (items.has(item.linkId)) {
+        const err = new Error('exists')
+        err.name = 'ConditionalCheckFailedException'
+        throw err
+      }
+      items.set(item.linkId, { ...item })
+    },
+    async replace(item, expectedVersion) {
+      const cur = items.get(item.linkId)
+      if (!cur || cur.version !== expectedVersion) return false
+      items.set(item.linkId, { ...item })
+      return true
+    },
+    async remove(linkId) {
+      items.delete(linkId)
+    },
+  }
+}
+
+module.exports = { createDynamoTokenStore, createMemoryTokenStore, marshal, unmarshal }

package/lambda-template/util.js

@@ -0,0 +1,181 @@
+/**
+ * Small pure helpers shared by the Lambda's modules. No I/O here.
+ */
+'use strict'
+
+/** Base64url-decode a JWT's payload WITHOUT verifying it — routing only. */
+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('&')
+}
+
+/** JSON body of a Function URL request, or null when absent/unparseable. */
+function parseJsonBody(event) {
+  const raw = decodeBody(event)
+  if (!raw) return null
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/** `Authorization: Bearer <x>` from a Function URL event (headers are lower-cased). */
+function readBearer(event) {
+  const headers = event.headers || {}
+  const value = headers.authorization || headers.Authorization
+  if (typeof value !== 'string') return null
+  const m = /^bearer\s+(.+)$/i.exec(value.trim())
+  return m ? m[1].trim() : null
+}
+
+/**
+ * The broker's public origin, as hubs must call it. `BROKER_PUBLIC_URL` when
+ * set, else the origin of `LAMBDA_REDIRECT_URI` (which is the Function URL +
+ * `/token`). HTTPS only — a hub refuses anything else.
+ */
+function resolveBrokerPublicUrl(env) {
+  const raw = env.BROKER_PUBLIC_URL || env.LAMBDA_REDIRECT_URI
+  if (!raw) return null
+  try {
+    const u = new URL(raw)
+    return u.protocol === 'https:' ? u.origin : null
+  } catch {
+    return null
+  }
+}
+
+function jsonResponse(statusCode, body) {
+  return {
+    statusCode,
+    headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+    body: JSON.stringify(body),
+  }
+}
+
+/**
+ * `Alexa.ErrorResponse` for a directive. Amazon requires the directive's
+ * `correlationToken` and the target `endpoint` on it (alexa-errorresponse);
+ * both are copied when the directive carried them.
+ */
+function errorEnvelope(header, type, message, endpoint) {
+  const endpointId =
+    endpoint && typeof endpoint.endpointId === 'string' ? endpoint.endpointId : null
+  return {
+    event: {
+      header: {
+        namespace: 'Alexa',
+        name: 'ErrorResponse',
+        messageId: header.messageId,
+        ...(typeof header.correlationToken === 'string'
+          ? { correlationToken: header.correlationToken }
+          : {}),
+        payloadVersion: '3',
+      },
+      ...(endpointId !== null ? { endpoint: { endpointId } } : {}),
+      payload: { type, message },
+    },
+  }
+}
+
+/** AcceptGrant's own error: `Alexa.Authorization/ErrorResponse` (alexa-authorization). */
+function acceptGrantErrorEnvelope(header, message) {
+  return {
+    event: {
+      header: {
+        namespace: 'Alexa.Authorization',
+        name: 'ErrorResponse',
+        messageId: header.messageId,
+        payloadVersion: '3',
+      },
+      payload: { type: 'ACCEPT_GRANT_FAILED', message },
+    },
+  }
+}
+
+/**
+ * Fill in what an `Alexa.ErrorResponse` from a hub may lack — a hub running an
+ * older addon omits `correlationToken` and `endpoint`. Any other body is
+ * returned as it is.
+ */
+function completeErrorResponse(body, directive) {
+  const ev = body && body.event
+  if (!ev || !ev.header || ev.header.name !== 'ErrorResponse' || ev.header.namespace !== 'Alexa') {
+    return body
+  }
+  const header = { ...ev.header }
+  if (
+    header.correlationToken === undefined &&
+    typeof directive.header.correlationToken === 'string'
+  ) {
+    header.correlationToken = directive.header.correlationToken
+  }
+  const endpointId =
+    directive.endpoint && typeof directive.endpoint.endpointId === 'string'
+      ? directive.endpoint.endpointId
+      : null
+  const endpoint = ev.endpoint || (endpointId !== null ? { endpointId } : undefined)
+  return { ...body, event: { ...ev, header, ...(endpoint ? { endpoint } : {}) } }
+}
+
+function describe(err) {
+  if (err instanceof Error) return err.message
+  return String(err)
+}
+
+module.exports = {
+  decodeJwtPayload,
+  normaliseHubUrl,
+  decodeBody,
+  parseFormUrlEncoded,
+  encodeFormUrlEncoded,
+  parseJsonBody,
+  readBearer,
+  resolveBrokerPublicUrl,
+  jsonResponse,
+  errorEnvelope,
+  acceptGrantErrorEnvelope,
+  completeErrorResponse,
+  describe,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-export-alexa",
-  "version": "1.2.132",
+  "version": "1.2.134",
   "description": "Alexa Smart Home Skill export — hub-side OAuth provider + directive handler. The companion AWS Lambda forwards Alexa directives to this addon's /addon/export-alexa/directive endpoint.",
   "keywords": [
     "camstack",