@camstack/addon-export-alexa 1.2.130 → 1.2.132

package/lambda-template/README.md

@@ -0,0 +1,116 @@
+# CamStack Alexa Lambda (Option 2 — single hosted skill)
+
+This Lambda is paired with **one** Alexa Smart Home skill published on
+[developer.amazon.com](https://developer.amazon.com) under the camstack
+brand. Every camstack user reaches the same Lambda; the Lambda decodes
+each user's bearer JWT to learn which hub URL to forward to, so it
+remains completely stateless.
+
+## What it does
+
+| Invocation                                               | Action                                                                                   |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `GET  <FUNCTION_URL>/authorize`                          | Renders an HTML form asking the user for their hub URL, then redirects to the hub's OAuth `/authorize`. |
+| `POST <FUNCTION_URL>/token`                              | Decodes the inbound JWT, looks up the `hubUrl` claim, proxies the form-encoded token request to the hub. |
+| Smart Home directive (`event.directive`)                 | Decodes the bearer, forwards JSON to `${hubUrl}/addon/export-alexa/directive`.            |
+| `Alexa.Authorization/AcceptGrant`                        | Exchanges the grant code at `api.amazon.com`, then POSTs LWA tokens back to the hub.      |
+
+## Deployment
+
+The Lambda is a single 10 kB file with **no node_modules**. The whole
+build is just `zip index.zip index.js`. It ships in the published
+`@camstack/addon-export-alexa` npm package (`npm pack` it and take
+`package/lambda-template/`), which is how the public docs page "Your own Alexa
+skill" tells operators to get it.
+
+Deploy it in the AWS region that serves your skill's locale: NA →
+`us-east-1`, EU/IN → `eu-west-1`, FE/AU → `us-west-2`.
+
+1. Create a new Lambda function in your AWS account:
+   - **Runtime:** Node.js 22.x or newer (the file uses only Node built-ins)
+   - **Architecture:** arm64 (or x86_64 — irrelevant for a small JS Lambda)
+   - **Timeout:** 8 seconds (Alexa's hard limit)
+   - **Memory:** 256 MB is plenty
+
+2. Upload `index.js` (zip first or paste into the inline editor).
+
+3. Add a **Function URL** trigger:
+   - **Auth type:** NONE
+   - Note the assigned URL — it looks like
+     `https://abc123xyz.lambda-url.eu-west-1.on.aws/`.
+
+4. Configure environment variables (see below).
+
+5. Add an **Alexa** → **Alexa Smart Home** trigger and paste the skill id
+   (`amzn1.ask.skill.…`). Create the skill first to get it.
+
+6. Note the Lambda **ARN** (Function overview → Function ARN).
+
+## Environment variables
+
+| Name                           | Value                                                                                                                                                                                                             |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SKILL_CLIENT_ID`              | Any opaque string. Paste the same value into the Alexa skill manifest's **Client ID** field on Account Linking.                                                                                                    |
+| `SKILL_CLIENT_SECRET`          | Any opaque string. Paste the same value into the Alexa skill manifest's **Client Secret** field.                                                                                                                   |
+| `LWA_CLIENT_ID`                | From the skill's **Permissions → Send Alexa Events** panel. Used for the AcceptGrant LWA token exchange.                                                                                                           |
+| `LWA_CLIENT_SECRET`            | Paired LWA client secret.                                                                                                                                                                                          |
+| `LAMBDA_REDIRECT_URI`          | The Function URL + `/token`, e.g. `https://abc123xyz.lambda-url.eu-west-1.on.aws/token`.                                                                                                                           |
+| `HUB_INGRESS_TOKEN`            | Optional defense-in-depth shared secret. Copy it from the CamStack Alexa addon's **Ingress token (Lambda)** setting. Sent as the `X-CamStack-Ingress` header on hub calls (`/directive`, `/oauth/lwa-tokens`); the hub enforces it once you enable **Require ingress token**. Leave unset to skip. |
+Generate the two skill secrets with anything strong, e.g.
+`openssl rand -hex 32`. The Lambda only compares them — no decoding.
+
+## Skill manifest fields
+
+In the [Alexa developer console](https://developer.amazon.com/alexa/console/ask)
+for your **Smart Home** skill:
+
+### 1. Endpoint
+
+| Field             | Value                                                              |
+| ----------------- | ------------------------------------------------------------------ |
+| Default endpoint  | `<LAMBDA_ARN>` (Function overview → Function ARN)                  |
+
+### 2. Account Linking
+
+| Field                                  | Value                                                                        |
+| -------------------------------------- | ---------------------------------------------------------------------------- |
+| Authorization Grant Type               | Auth Code Grant                                                              |
+| Authorization URI                      | `<FUNCTION_URL>/authorize`                                                   |
+| Access Token URI                       | `<FUNCTION_URL>/token`                                                       |
+| Client ID                              | `SKILL_CLIENT_ID` env var (same string)                                      |
+| Client Secret                          | `SKILL_CLIENT_SECRET` env var (same string)                                  |
+| Client Authentication Scheme           | Credentials in request body (**not** HTTP Basic — the Lambda reads them from the body) |
+| Scope                                  | _(leave empty)_                                                              |
+| Domain List                            | _(leave empty — operators supply arbitrary hub URLs at runtime)_             |
+
+### 3. Permissions (proactive events)
+
+Enable **Send Alexa Events** and copy the generated LWA client id /
+secret into the Lambda env (`LWA_CLIENT_ID` / `LWA_CLIENT_SECRET`).
+
+## How the routing works
+
+Every hub-issued JWT (auth code, access token, refresh token) carries a
+`hubUrl` claim equal to that hub's public HTTPS origin. The Lambda
+**base64-decodes** the payload — no signature check. The hub verifies
+the signature when the request lands. Threat model: a forged token with
+a malicious `hubUrl` only reaches that malicious hub; cross-hub
+spillover is not possible because the malicious hub still has to mint a
+token its own auth-manager signed before Alexa stores it.
+
+> The hub no longer validates `client_id` / `client_secret`. That pair is
+> checked only here in the Lambda. On the hub, `/api/oauth2/authorize` is a
+> session-authenticated route — an unauthenticated browser is redirected
+> to the normal CamStack login.
+
+## Local testing
+
+```bash
+# Pretend to be Alexa's token endpoint hitting the Lambda.
+curl -X POST "$FUNCTION_URL/token" \
+  -H 'content-type: application/x-www-form-urlencoded' \
+  -d 'grant_type=authorization_code' \
+  -d 'code=<some-jwt-with-hubUrl-claim>' \
+  -d "client_id=$SKILL_CLIENT_ID" \
+  -d "client_secret=$SKILL_CLIENT_SECRET"
+```

package/lambda-template/index.js

@@ -0,0 +1,567 @@
+/**
+ * CamStack Alexa Smart Home Lambda — Option 2 (single hosted skill).
+ *
+ * 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.
+ *
+ * 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
+ *
+ * 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.
+ *
+ * Ships as a single file — no node_modules, no transpile. Targets the
+ * AWS Lambda Node 20.x runtime which exposes built-in `fetch`.
+ */
+
+const FETCH_TIMEOUT_MS = 6000
+
+// 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 })
+
+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))
+    }
+    return jsonResponse(500, { error: 'internal_error', message: describe(err) })
+  }
+}
+
+// ── Lambda Function URL (HTTP) routes ────────────────────────────────
+
+async function handleLambdaUrl(event) {
+  const path = event.rawPath || '/'
+  if (path === '/authorize') return handleAuthorizePage(event)
+  if (path === '/token') return handleTokenProxy(event)
+  return { statusCode: 404, headers: { 'content-type': 'text/plain' }, body: 'Not found' }
+}
+
+/**
+ * Render the "Enter your CamStack hub URL" form. Submitting the form
+ * forwards the original Alexa query params (response_type, client_id,
+ * redirect_uri, state, scope) — plus `integration=export-alexa` — to
+ * `${hubUrl}/api/oauth2/authorize`. From there the browser stays on the hub's
+ * origin until the OAuth code round-trips back to Alexa.
+ */
+function handleAuthorizePage(event) {
+  const qs = event.rawQueryString || ''
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>CamStack · Link your hub</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; max-width: 480px; margin: 4rem auto; padding: 0 1rem; color: #1f2937; background: #f9fafb; }
+    .card { background: #fff; border: 1px solid #e5e7eb; border-radius: 0.75rem; padding: 2rem; box-shadow: 0 1px 2px rgba(0,0,0,0.04); }
+    h1 { font-size: 1.25rem; margin: 0 0 0.5rem; }
+    p { font-size: 0.9rem; color: #4b5563; margin: 0 0 1.5rem; }
+    label { display: block; font-size: 0.85rem; font-weight: 500; margin-bottom: 0.5rem; }
+    input { width: 100%; padding: 0.6rem 0.75rem; font-size: 0.95rem; border: 1px solid #d1d5db; border-radius: 0.375rem; box-sizing: border-box; font-family: ui-monospace, Menlo, monospace; }
+    input:focus { outline: 2px solid #2563eb; outline-offset: 1px; border-color: #2563eb; }
+    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; }
+  </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">
+      <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>
+      <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 url = hubUrl + '/api/oauth2/authorize' + '?' + (qs ? qs + '&' : '') + 'integration=export-alexa'
+      window.location.href = url
+    })
+  </script>
+</body>
+</html>`
+  return {
+    statusCode: 200,
+    headers: { 'content-type': 'text/html; charset=utf-8' },
+    body: html,
+  }
+}
+
+/**
+ * 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.
+ */
+async function handleTokenProxy(event) {
+  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) {
+    return jsonResponse(500, {
+      error: 'unconfigured',
+      message: 'SKILL_CLIENT_ID / SKILL_CLIENT_SECRET not set',
+    })
+  }
+  if (body.client_id !== skillId || body.client_secret !== skillSecret) {
+    return jsonResponse(401, { error: 'invalid_client', message: 'client credentials mismatch' })
+  }
+
+  const tokenInput = body.grant_type === 'refresh_token' ? body.refresh_token : body.code
+  if (!tokenInput) {
+    return jsonResponse(400, {
+      error: 'invalid_request',
+      message: 'code or refresh_token is required',
+    })
+  }
+  const claims = decodeJwtPayload(tokenInput)
+  if (!claims || typeof claims.hubUrl !== 'string' || claims.hubUrl.length === 0) {
+    return jsonResponse(400, {
+      error: 'invalid_grant',
+      message: 'token has no hubUrl claim — was it minted by a hub that supports cloud-mode?',
+    })
+  }
+
+  const target = `${normaliseHubUrl(claims.hubUrl)}/api/oauth2/token`
+  const upstream = await timedFetch(target, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: encodeFormUrlEncoded(body),
+  })
+  const text = await upstream.text()
+  return {
+    statusCode: upstream.status,
+    headers: { 'content-type': upstream.headers.get('content-type') || 'application/json' },
+    body: text,
+  }
+}
+
+// ── Smart Home directives ────────────────────────────────────────────
+
+async function handleDirective(event) {
+  const header = event.directive.header
+  const ns = `${header.namespace}/${header.name}`
+  if (ns === 'Alexa.Authorization/AcceptGrant') {
+    return handleAcceptGrant(event)
+  }
+  return forwardDirective(event)
+}
+
+async function handleAcceptGrant(event) {
+  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',
+    )
+  }
+  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')
+  }
+
+  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',
+    )
+  }
+
+  // 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,
+    }),
+  })
+  if (!lwaResp.ok) {
+    const text = await lwaResp.text().catch(() => '')
+    return errorEnvelope(header, 'ACCEPT_GRANT_FAILED', `LWA exchange ${lwaResp.status}: ${text}`)
+  }
+  const lwa = await lwaResp.json()
+  const expiresInSec = typeof lwa.expires_in === 'number' ? lwa.expires_in : 3600
+
+  // 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, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${granteeToken}`,
+      ...(process.env.HUB_INGRESS_TOKEN
+        ? { 'x-camstack-ingress': process.env.HUB_INGRESS_TOKEN }
+        : {}),
+    },
+    body: JSON.stringify({
+      lwaAccessToken: lwa.access_token,
+      lwaRefreshToken: lwa.refresh_token,
+      expiresAt: Date.now() + expiresInSec * 1000,
+    }),
+  })
+  if (!callbackResp.ok) {
+    const text = await callbackResp.text().catch(() => '')
+    return errorEnvelope(
+      header,
+      'ACCEPT_GRANT_FAILED',
+      `hub callback ${callbackResp.status}: ${text}`,
+    )
+  }
+
+  return {
+    event: {
+      header: {
+        namespace: 'Alexa.Authorization',
+        name: 'AcceptGrant.Response',
+        messageId: header.messageId,
+        payloadVersion: '3',
+      },
+      payload: {},
+    },
+  }
+}
+
+async function forwardDirective(event) {
+  const header = event.directive.header
+  const bearer = extractBearer(event.directive)
+  if (!bearer) {
+    return errorEnvelope(
+      header,
+      'INVALID_AUTHORIZATION_CREDENTIAL',
+      'directive has no bearer token',
+    )
+  }
+  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')
+  }
+  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 }
+      : {}),
+  }
+  const resp = await timedFetch(target, {
+    method: 'POST',
+    headers: directiveHeaders,
+    body: JSON.stringify(event),
+  })
+  const text = await resp.text()
+  try {
+    return JSON.parse(text)
+  } catch {
+    return errorEnvelope(header, 'INTERNAL_ERROR', `hub returned non-JSON: ${text.slice(0, 256)}`)
+  }
+}
+
+function extractBearer(directive) {
+  if (
+    directive.endpoint &&
+    directive.endpoint.scope &&
+    typeof directive.endpoint.scope.token === 'string'
+  ) {
+    return directive.endpoint.scope.token
+  }
+  if (
+    directive.payload &&
+    directive.payload.scope &&
+    typeof directive.payload.scope.token === 'string'
+  ) {
+    return directive.payload.scope.token
+  }
+  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)
+}