@blamejs/core 0.10.15 → 0.11.1

package/lib/dbsc.js

@@ -0,0 +1,299 @@
+"use strict";
+/**
+ * @module b.dbsc
+ * @nav    Identity
+ * @title  Device Bound Session Credentials
+ * @order  378
+ *
+ * @intro
+ *   IETF draft-ietf-oauth-attestation-based-client-auth + Chrome's
+ *   DBSC proposal — binds an HTTP session to a browser-generated key
+ *   pair so a stolen session cookie alone can't impersonate the user
+ *   from a different device. The browser holds the private key in
+ *   secure hardware; every refresh proves possession via a signed
+ *   challenge.
+ *
+ *   Server flow:
+ *     1. `b.dbsc.challenge()` — mint a random challenge, sign it
+ *        with the operator's HMAC key for replay defense, return
+ *        the challenge string + the `Sec-Session-Challenge` header
+ *        value. The browser auto-resolves the challenge via the
+ *        DBSC refresh endpoint.
+ *     2. `b.dbsc.verifyBindingAssertion(jwt, { challenge, expectedAud })`
+ *        — verify the browser-supplied JWT signed by the binding
+ *        public key. Returns `{ valid, sub, jkt }` where `jkt` is
+ *        the JWK thumbprint of the binding key.
+ *
+ *   Composes existing b.crypto + b.auth.jwt; DBSC mandates ES256 /
+ *   RS256 (browser TPM hardware). The framework refuses HS256 /
+ *   none on parsed JWTs.
+ *
+ * @card
+ *   IETF DBSC challenge minter + binding-assertion verifier. Stops device-portable session theft by binding cookies to hardware keys.
+ */
+
+var nodeCrypto    = require("node:crypto");
+var validateOpts  = require("./validate-opts");
+var safeJson      = require("./safe-json");
+var bCrypto       = require("./crypto");
+var canonicalJson = require("./canonical-json");
+var jwtExternal   = require("./auth/jwt-external");
+var C             = require("./constants");
+var { defineClass } = require("./framework-error");
+
+var DbscError = defineClass("DbscError", { alwaysPermanent: true });
+
+var DEFAULT_CHALLENGE_TTL_MS = C.TIME.minutes(5);
+
+/**
+ * @primitive b.dbsc.challenge
+ * @signature b.dbsc.challenge(opts)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Mint a fresh DBSC challenge. Returns `{ challenge, expiresAt,
+ * headerValue }` where `headerValue` is the `Sec-Session-Challenge`
+ * value to set on the response. The challenge is HMAC-SHA3-512
+ * signed so the server can verify the same challenge it issued
+ * on the assertion-verify path without persisting it.
+ *
+ * @opts
+ *   secretKey:    Buffer,     // operator HMAC secret (>=32 bytes)
+ *   ttlMs:        number,     // default 5 minutes
+ *   nonce:        string,     // optional caller-supplied nonce (default: 32-byte random)
+ *
+ * @example
+ *   var c = b.dbsc.challenge({ secretKey: opSecret });
+ *   res.setHeader("Sec-Session-Challenge", c.headerValue);
+ */
+function challenge(opts) {
+  opts = validateOpts.requireObject(opts, "dbsc.challenge", DbscError, "dbsc/bad-opts");
+  validateOpts(opts, ["secretKey", "ttlMs", "nonce"], "dbsc.challenge");
+  if (!Buffer.isBuffer(opts.secretKey) || opts.secretKey.length < 32) {                               // allow:raw-byte-literal — 32-byte HMAC secret floor
+    throw new DbscError("dbsc/bad-secret",
+      "challenge: opts.secretKey must be a Buffer (>= 32 bytes)");
+  }
+  validateOpts.optionalPositiveFinite(opts.ttlMs, "dbsc.challenge: ttlMs",
+    DbscError, "dbsc/bad-ttl");
+  var ttlMs     = opts.ttlMs || DEFAULT_CHALLENGE_TTL_MS;
+  var nonceBuf  = opts.nonce ? Buffer.from(String(opts.nonce), "utf8") : bCrypto.generateBytes(32);   // allow:raw-byte-literal — 32-byte nonce
+  var expiresAt = Date.now() + ttlMs;
+  var msg = nonceBuf.toString("base64") + "." + expiresAt;
+  var mac = nodeCrypto.createHmac("sha3-512", opts.secretKey).update(msg).digest("base64");
+  var challengeStr = msg + "." + mac;
+  return {
+    challenge:   challengeStr,
+    expiresAt:   expiresAt,
+    headerValue: challengeStr,
+  };
+}
+
+/**
+ * @primitive b.dbsc.verifyChallenge
+ * @signature b.dbsc.verifyChallenge(challengeStr, { secretKey })
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Verify a challenge string previously issued by `challenge()`.
+ * Returns truthy when the HMAC matches and the challenge hasn't
+ * expired. Refuses with typed errors on shape / expiry / MAC
+ * mismatch.
+ *
+ * @example
+ *   var ok = b.dbsc.verifyChallenge(req.headers["sec-session-challenge"],
+ *     { secretKey: process.env.DBSC_HMAC_KEY });
+ */
+function verifyChallenge(challengeStr, opts) {
+  opts = validateOpts.requireObject(opts, "dbsc.verifyChallenge",
+    DbscError, "dbsc/bad-opts");
+  if (typeof challengeStr !== "string") {
+    throw new DbscError("dbsc/bad-challenge",
+      "verifyChallenge: challenge must be a string");
+  }
+  if (!Buffer.isBuffer(opts.secretKey) || opts.secretKey.length < 32) {                               // allow:raw-byte-literal — 32-byte HMAC secret floor
+    throw new DbscError("dbsc/bad-secret",
+      "verifyChallenge: opts.secretKey must be a Buffer (>= 32 bytes)");
+  }
+  var parts = challengeStr.split(".");
+  if (parts.length !== 3) {
+    throw new DbscError("dbsc/bad-challenge-shape",
+      "verifyChallenge: challenge must have 3 dot-separated parts");
+  }
+  var expiresAt = parseInt(parts[1], 10);
+  if (!isFinite(expiresAt) || expiresAt <= 0) {
+    throw new DbscError("dbsc/bad-expires",
+      "verifyChallenge: expiresAt is not a positive integer");
+  }
+  if (Date.now() > expiresAt) {
+    throw new DbscError("dbsc/expired",
+      "verifyChallenge: challenge expired");
+  }
+  var msg = parts[0] + "." + parts[1];
+  var expected = nodeCrypto.createHmac("sha3-512", opts.secretKey).update(msg).digest("base64");
+  if (!bCrypto.timingSafeEqual(Buffer.from(expected, "utf8"), Buffer.from(parts[2], "utf8"))) {
+    throw new DbscError("dbsc/bad-mac",
+      "verifyChallenge: HMAC mismatch (forged or wrong secret)");
+  }
+  return { valid: true, expiresAt: expiresAt };
+}
+
+/**
+ * @primitive b.dbsc.verifyBindingAssertion
+ * @signature b.dbsc.verifyBindingAssertion(assertion, opts)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Verify a DBSC binding-assertion JWT. The browser signs a JWT with
+ * the device-bound private key whose header includes the JWK
+ * thumbprint of the binding key. Returns `{ valid, jkt, claims }`.
+ * Refuses HS256 / none (algorithm-confusion class) and any
+ * mismatched audience / challenge.
+ *
+ * @opts
+ *   secretKey:     Buffer,     // HMAC secret used by challenge() (for re-verify)
+ *   expectedAud:   string,     // expected RP origin
+ *   maxAgeSec:     number,     // default 300s
+ *
+ * @example
+ *   var v = b.dbsc.verifyBindingAssertion(req.body, {
+ *     secretKey:   opSecret,
+ *     expectedAud: "https://rp.example",
+ *   });
+ *   if (!v.valid) throw 401;
+ *   v.jkt;   // → JWK thumbprint of the binding key (use as a session pin)
+ */
+function verifyBindingAssertion(assertion, opts) {
+  opts = validateOpts.requireObject(opts, "dbsc.verifyBindingAssertion",
+    DbscError, "dbsc/bad-opts");
+  validateOpts(opts, ["secretKey", "expectedAud", "maxAgeSec"],
+    "dbsc.verifyBindingAssertion");
+  if (typeof assertion !== "string") {
+    throw new DbscError("dbsc/bad-assertion",
+      "verifyBindingAssertion: assertion must be a string JWT");
+  }
+  validateOpts.requireNonEmptyString(opts.expectedAud, "expectedAud",
+    DbscError, "dbsc/missing-aud");
+  var parts = assertion.split(".");
+  if (parts.length !== 3) {
+    throw new DbscError("dbsc/bad-jwt-shape",
+      "verifyBindingAssertion: JWT must have 3 parts");
+  }
+  var headerJson, payloadJson;
+  try { headerJson  = safeJson.parse(Buffer.from(parts[0], "base64url").toString("utf8")); }
+  catch (_e) { throw new DbscError("dbsc/bad-jwt-header", "JWT header is not parseable JSON"); }
+  try { payloadJson = safeJson.parse(Buffer.from(parts[1], "base64url").toString("utf8")); }
+  catch (_e) { throw new DbscError("dbsc/bad-jwt-payload", "JWT payload is not parseable JSON"); }
+  // Algorithm-confusion defense — DBSC mandates ES256 / RS256 from
+  // hardware-backed keys; refuse symmetric or none algs.
+  if (headerJson.alg !== "ES256" && headerJson.alg !== "RS256") {
+    throw new DbscError("dbsc/bad-alg",
+      "verifyBindingAssertion: alg " + headerJson.alg + " refused (DBSC mandates ES256 / RS256)");
+  }
+  if (!headerJson.jwk || typeof headerJson.jwk !== "object") {
+    throw new DbscError("dbsc/no-jwk",
+      "verifyBindingAssertion: JWT header missing jwk (binding-key proof)");
+  }
+  // Verify the JWT signature against the embedded jwk (proof-of-
+  // possession of the binding-key). Refuse alg/kty mismatches at the
+  // import boundary (alg-confusion defense — JWT_KEY_CONFUSION-class
+  // attacks pass an HS256 jwk for an ES256-claimed token).
+  jwtExternal._assertAlgKtyMatch(headerJson.alg, headerJson.jwk);
+  var pubKey;
+  try { pubKey = nodeCrypto.createPublicKey({ key: headerJson.jwk, format: "jwk" }); }
+  catch (e) {
+    throw new DbscError("dbsc/bad-jwk",
+      "verifyBindingAssertion: jwk could not be imported: " + ((e && e.message) || String(e)));
+  }
+  var signingInput = parts[0] + "." + parts[1];
+  var sigBytes = Buffer.from(parts[2], "base64url");
+  var ok;
+  if (headerJson.alg === "ES256") {
+    // JWT raw r||s → DER for nodeCrypto.verify.
+    if (sigBytes.length !== 64) {                                                                     // allow:raw-byte-literal — P-256 r||s shape
+      throw new DbscError("dbsc/bad-sig", "ES256 signature must be 64 bytes raw");
+    }
+    var derSig = _ecdsaRawToDer(sigBytes);
+    ok = nodeCrypto.verify("sha256", Buffer.from(signingInput, "utf8"), pubKey, derSig);
+  } else {
+    ok = nodeCrypto.verify("sha256", Buffer.from(signingInput, "utf8"), pubKey, sigBytes);
+  }
+  if (!ok) {
+    throw new DbscError("dbsc/bad-signature",
+      "verifyBindingAssertion: JWT signature does not verify against embedded jwk");
+  }
+  // Validate audience + freshness.
+  if (payloadJson.aud !== opts.expectedAud) {
+    throw new DbscError("dbsc/bad-aud",
+      "verifyBindingAssertion: aud '" + payloadJson.aud + "' != expected '" + opts.expectedAud + "'");
+  }
+  // Freshness — every assertion MUST carry either an `iat` (so the
+  // age check below can reject stale tokens) or a `challenge` (so the
+  // re-verify below pins the assertion to a server-issued nonce with
+  // its own expiry). An assertion lacking both replays indefinitely
+  // until the signing key rotates — refuse at the verifier boundary.
+  if (typeof payloadJson.iat !== "number" && !payloadJson.challenge) {
+    throw new DbscError("dbsc/no-freshness",
+      "verifyBindingAssertion: assertion must carry either 'iat' (age-checked) " +
+      "or 'challenge' (server-nonce-bound); without freshness material the " +
+      "assertion replays indefinitely");
+  }
+  var maxAge = (opts.maxAgeSec || 300) * 1000;                                                        // allow:raw-byte-literal allow:raw-time-literal — 5min default
+  if (typeof payloadJson.iat === "number" && Date.now() - payloadJson.iat * 1000 > maxAge) {          // allow:raw-byte-literal allow:raw-time-literal — sec→ms
+    throw new DbscError("dbsc/stale",
+      "verifyBindingAssertion: iat is more than " + opts.maxAgeSec + "s old");
+  }
+  // Re-verify any embedded challenge if the assertion claims one.
+  if (payloadJson.challenge) {
+    verifyChallenge(payloadJson.challenge, { secretKey: opts.secretKey });
+  }
+  // Compute JWK thumbprint (RFC 7638) for operator-side session-pin.
+  var jkt = _jwkThumbprint(headerJson.jwk);
+  return { valid: true, jkt: jkt, claims: payloadJson };
+}
+
+function _ecdsaRawToDer(raw) {
+  if (raw.length !== 64) throw new DbscError("dbsc/bad-sig", "raw r||s must be 64 bytes");            // allow:raw-byte-literal — P-256 r||s shape
+  var r = _trimLeadingZeros(raw.slice(0, 32));                                                        // allow:raw-byte-literal — 32-byte r
+  var s = _trimLeadingZeros(raw.slice(32));                                                           // allow:raw-byte-literal — 32-byte s offset
+  function _intDer(buf) {
+    // Prepend 0x00 if high bit set (positive INTEGER per DER).
+    if (buf[0] & 0x80) buf = Buffer.concat([Buffer.from([0x00]), buf]);                               // allow:raw-byte-literal — DER sign-bit pad
+    return Buffer.concat([Buffer.from([0x02, buf.length]), buf]);                                      // allow:raw-byte-literal — ASN.1 INTEGER tag
+  }
+  var rDer = _intDer(r);
+  var sDer = _intDer(s);
+  var seqBody = Buffer.concat([rDer, sDer]);
+  return Buffer.concat([Buffer.from([0x30, seqBody.length]), seqBody]);                               // allow:raw-byte-literal — ASN.1 SEQUENCE tag
+}
+
+function _trimLeadingZeros(buf) {
+  var i = 0;
+  while (i < buf.length - 1 && buf[i] === 0x00) i += 1;                                                // allow:raw-byte-literal — leading zero byte
+  return buf.slice(i);
+}
+
+function _jwkThumbprint(jwk) {
+  // RFC 7638 canonical thumbprint: alphabetic key-name ordering + no
+  // whitespace + SHA-256 + base64url. For EC P-256 the required keys
+  // are { crv, kty, x, y }.
+  var members;
+  if (jwk.kty === "EC") {
+    members = { crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y };
+  } else if (jwk.kty === "RSA") {
+    members = { e: jwk.e, kty: jwk.kty, n: jwk.n };
+  } else {
+    throw new DbscError("dbsc/bad-jwk-kty",
+      "jwkThumbprint: unsupported kty " + jwk.kty);
+  }
+  var canonical = canonicalJson.stringify(members);
+  return bCrypto.toBase64Url(
+    nodeCrypto.createHash("sha256").update(Buffer.from(canonical, "utf8")).digest()
+  );
+}
+
+module.exports = {
+  challenge:                challenge,
+  verifyChallenge:          verifyChallenge,
+  verifyBindingAssertion:   verifyBindingAssertion,
+  DbscError:                DbscError,
+};

package/lib/fedcm.js

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * @module b.fedcm
+ * @nav    Identity
+ * @title  FedCM Identity Provider
+ * @order  375
+ *
+ * @intro
+ *   W3C FedCM (Federated Credential Management API, candidate
+ *   recommendation 2024) identity-provider-side helpers. Operators
+ *   running an IdP wire four endpoints per the spec; this module
+ *   ships response-shape builders + the well-known config emitter.
+ *
+ *   Endpoints (FedCM §5):
+ *     - `/.well-known/web-identity` — discovery
+ *     - `<config_url>` — IdP config doc (FedCM §6.3 IdentityProviderAPIConfig)
+ *     - `accounts_endpoint` — returns the user's accounts at this IdP
+ *     - `id_assertion_endpoint` — mints the id_token / verifiable
+ *       credential bound to the relying-party origin
+ *
+ *   The framework does NOT make the FedCM browser API call itself —
+ *   that's user-agent surface. Operators wire response builders into
+ *   their router and supply the per-account session state.
+ *
+ * @card
+ *   FedCM IdP-side response builders (well-known + config + accounts + id_assertion) per W3C FedCM 2024 candidate recommendation.
+ */
+
+var validateOpts  = require("./validate-opts");
+var safeUrl       = require("./safe-url");
+var { defineClass } = require("./framework-error");
+
+var FedcmError = defineClass("FedcmError", { alwaysPermanent: true });
+
+/**
+ * @primitive b.fedcm.wellKnown
+ * @signature b.fedcm.wellKnown({ provider_urls })
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build the `/.well-known/web-identity` JSON body. `provider_urls`
+ * lists the operator's IdP config URLs (FedCM §5).
+ *
+ * @example
+ *   res.setHeader("Content-Type", "application/json");
+ *   res.end(JSON.stringify(b.fedcm.wellKnown({
+ *     provider_urls: ["https://idp.example/fedcm/config.json"],
+ *   })));
+ */
+function wellKnown(opts) {
+  opts = validateOpts.requireObject(opts, "fedcm.wellKnown", FedcmError, "fedcm/bad-opts");
+  if (!Array.isArray(opts.provider_urls) || opts.provider_urls.length === 0) {
+    throw new FedcmError("fedcm/no-provider-urls",
+      "wellKnown: provider_urls must be a non-empty array");
+  }
+  for (var i = 0; i < opts.provider_urls.length; i += 1) {
+    var u = opts.provider_urls[i];
+    var parsed;
+    try { parsed = safeUrl.parse(u); }
+    catch (_e) {
+      throw new FedcmError("fedcm/bad-provider-url",
+        "wellKnown: provider_urls[" + i + "] is not a parseable URL");
+    }
+    if (parsed.protocol !== "https:") {
+      throw new FedcmError("fedcm/bad-provider-url",
+        "wellKnown: provider_urls[" + i + "] must be https");
+    }
+  }
+  return { provider_urls: opts.provider_urls.slice() };
+}
+
+/**
+ * @primitive b.fedcm.config
+ * @signature b.fedcm.config(opts)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build the IdentityProviderAPIConfig JSON body served at the
+ * operator's `config_url` per FedCM §6.3. Required fields:
+ * accounts_endpoint, client_metadata_endpoint, id_assertion_endpoint,
+ * login_url, branding (icon / name / colors).
+ *
+ * @example
+ *   res.end(JSON.stringify(b.fedcm.config({
+ *     accounts_endpoint:        "/fedcm/accounts",
+ *     client_metadata_endpoint: "/fedcm/client_metadata",
+ *     id_assertion_endpoint:    "/fedcm/id_assertion",
+ *     login_url:                "https://idp.example/login",
+ *     branding: { background_color: "#000", color: "#fff", name: "Example IdP" },
+ *   })));
+ */
+function config(opts) {
+  opts = validateOpts.requireObject(opts, "fedcm.config", FedcmError, "fedcm/bad-opts");
+  validateOpts(opts, ["accounts_endpoint", "client_metadata_endpoint",
+                       "id_assertion_endpoint", "login_url", "branding",
+                       "disconnect_endpoint"], "fedcm.config");
+  var required = ["accounts_endpoint", "client_metadata_endpoint",
+                   "id_assertion_endpoint", "login_url"];
+  for (var i = 0; i < required.length; i += 1) {
+    validateOpts.requireNonEmptyString(opts[required[i]], required[i],
+      FedcmError, "fedcm/missing-" + required[i]);
+  }
+  if (!opts.branding || typeof opts.branding !== "object") {
+    throw new FedcmError("fedcm/missing-branding", "config: opts.branding required");
+  }
+  var out = {
+    accounts_endpoint:        opts.accounts_endpoint,
+    client_metadata_endpoint: opts.client_metadata_endpoint,
+    id_assertion_endpoint:    opts.id_assertion_endpoint,
+    login_url:                opts.login_url,
+    branding: {
+      name:             opts.branding.name             || "",
+      background_color: opts.branding.background_color || "#000000",
+      color:            opts.branding.color            || "#ffffff",
+    },
+  };
+  if (opts.branding.icons) out.branding.icons = opts.branding.icons.slice();
+  if (opts.disconnect_endpoint) out.disconnect_endpoint = opts.disconnect_endpoint;
+  return out;
+}
+
+/**
+ * @primitive b.fedcm.accountsResponse
+ * @signature b.fedcm.accountsResponse({ accounts })
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build the JSON body for the accounts_endpoint response. Each
+ * account: { id, name, email, picture?, approved_clients? }
+ * Operator supplies the per-user account state.
+ *
+ * @example
+ *   res.setHeader("Set-Cookie", "Sec-FedCM-CSRF=...");
+ *   res.end(JSON.stringify(b.fedcm.accountsResponse({
+ *     accounts: [{
+ *       id: "1234", name: "Alice", email: "alice@example.com",
+ *       approved_clients: ["rp.example"],
+ *     }],
+ *   })));
+ */
+function accountsResponse(opts) {
+  opts = validateOpts.requireObject(opts, "fedcm.accountsResponse",
+    FedcmError, "fedcm/bad-opts");
+  if (!Array.isArray(opts.accounts)) {
+    throw new FedcmError("fedcm/no-accounts",
+      "accountsResponse: opts.accounts must be an array");
+  }
+  var sanitized = opts.accounts.map(function (a, i) {
+    if (!a || typeof a !== "object") {
+      throw new FedcmError("fedcm/bad-account",
+        "accountsResponse: accounts[" + i + "] must be an object");
+    }
+    if (typeof a.id !== "string" || a.id.length === 0) {
+      throw new FedcmError("fedcm/bad-account",
+        "accountsResponse: accounts[" + i + "].id required (string)");
+    }
+    var out = { id: a.id, name: a.name || "", email: a.email || "" };
+    if (a.given_name)   out.given_name   = a.given_name;
+    if (a.picture)      out.picture      = a.picture;
+    if (Array.isArray(a.approved_clients)) out.approved_clients = a.approved_clients.slice();
+    return out;
+  });
+  return { accounts: sanitized };
+}
+
+/**
+ * @primitive b.fedcm.idAssertionResponse
+ * @signature b.fedcm.idAssertionResponse({ token })
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build the JSON body for the id_assertion_endpoint response. The
+ * operator mints the `token` (typically a signed JWT or verifiable
+ * credential) and the framework wraps it in the FedCM-spec shape.
+ *
+ * @example
+ *   res.end(JSON.stringify(b.fedcm.idAssertionResponse({ token: jwt })));
+ */
+function idAssertionResponse(opts) {
+  opts = validateOpts.requireObject(opts, "fedcm.idAssertionResponse",
+    FedcmError, "fedcm/bad-opts");
+  validateOpts.requireNonEmptyString(opts.token, "token",
+    FedcmError, "fedcm/missing-token");
+  return { token: opts.token };
+}
+
+/**
+ * @primitive b.fedcm.clientMetadataResponse
+ * @signature b.fedcm.clientMetadataResponse(opts)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build the JSON body for the FedCM client_metadata_endpoint
+ * response. Returns the relying-party policy URLs the browser
+ * surfaces during the IdP login prompt (privacy policy + terms of
+ * service). Both URLs are validated as https.
+ *
+ * @opts
+ *   privacy_policy_url:    string,    // required https URL
+ *   terms_of_service_url:  string,    // required https URL
+ *
+ * @example
+ *   res.end(JSON.stringify(b.fedcm.clientMetadataResponse({
+ *     privacy_policy_url:   "https://rp.example/privacy",
+ *     terms_of_service_url: "https://rp.example/tos",
+ *   })));
+ */
+function clientMetadataResponse(opts) {
+  opts = validateOpts.requireObject(opts, "fedcm.clientMetadataResponse",
+    FedcmError, "fedcm/bad-opts");
+  validateOpts(opts, ["privacy_policy_url", "terms_of_service_url"],
+    "fedcm.clientMetadataResponse");
+  validateOpts.requireNonEmptyString(opts.privacy_policy_url, "privacy_policy_url",
+    FedcmError, "fedcm/missing-privacy-url");
+  validateOpts.requireNonEmptyString(opts.terms_of_service_url, "terms_of_service_url",
+    FedcmError, "fedcm/missing-tos-url");
+  if (!/^https:/i.test(opts.privacy_policy_url)) {
+    throw new FedcmError("fedcm/bad-privacy-url",
+      "clientMetadataResponse: privacy_policy_url must be https");
+  }
+  if (!/^https:/i.test(opts.terms_of_service_url)) {
+    throw new FedcmError("fedcm/bad-tos-url",
+      "clientMetadataResponse: terms_of_service_url must be https");
+  }
+  return {
+    privacy_policy_url:   opts.privacy_policy_url,
+    terms_of_service_url: opts.terms_of_service_url,
+  };
+}
+
+/**
+ * @primitive b.fedcm.disconnectResponse
+ * @signature b.fedcm.disconnectResponse(opts)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build the JSON body for the FedCM disconnect_endpoint response.
+ * The browser calls this when the user revokes their FedCM grant;
+ * the IdP returns the disconnected account id so the browser can
+ * update its local state. `account_id` is REQUIRED per the spec.
+ *
+ * @opts
+ *   account_id: string,   // required — identifier of the account that was disconnected
+ *
+ * @example
+ *   res.end(JSON.stringify(b.fedcm.disconnectResponse({ account_id: "1234" })));
+ */
+function disconnectResponse(opts) {
+  opts = validateOpts.requireObject(opts, "fedcm.disconnectResponse",
+    FedcmError, "fedcm/bad-opts");
+  validateOpts.requireNonEmptyString(opts.account_id, "account_id",
+    FedcmError, "fedcm/missing-account-id");
+  return { account_id: opts.account_id };
+}
+
+module.exports = {
+  wellKnown:              wellKnown,
+  config:                 config,
+  accountsResponse:       accountsResponse,
+  clientMetadataResponse: clientMetadataResponse,
+  idAssertionResponse:    idAssertionResponse,
+  disconnectResponse:     disconnectResponse,
+  FedcmError:             FedcmError,
+};

package/lib/hal.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * @module b.hal
+ * @nav    HTTP
+ * @title  HAL hypermedia
+ * @order  173
+ *
+ * @intro
+ *   HAL (Hypertext Application Language, IETF draft-kelly-json-hal-08).
+ *   Wraps resources with `_links` + `_embedded` so clients discover
+ *   navigation + nested resources without out-of-band routing. The
+ *   spec is small; the framework's helper is correspondingly small.
+ *
+ *   Content-Type: `application/hal+json`
+ *
+ *   Reserved properties:
+ *     - `_links`     — { rel: linkObject | linkObject[] } per RFC 8288
+ *     - `_embedded`  — { rel: resource | resource[] }
+ *     - `_templates` — HAL-FORMS extension (operator-supplied)
+ *
+ * @card
+ *   HAL (draft-kelly-json-hal) + HAL-FORMS hypermedia response builder. Content-Type negotiation + _links/_embedded structure helpers per RFC 8288.
+ */
+
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var HalError = defineClass("HalError", { alwaysPermanent: true });
+
+var CONTENT_TYPE = "application/hal+json";
+
+/**
+ * @primitive b.hal.resource
+ * @signature b.hal.resource(payload, opts?)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build a HAL resource. `payload` is the operator's domain object;
+ * `opts.links` is a map of `{ rel: href | linkObject | linkObject[] }`;
+ * `opts.embedded` is a map of `{ rel: resource | resource[] }`.
+ *
+ * @opts
+ *   links:    { [rel]: string | LinkObject | LinkObject[] },
+ *   embedded: { [rel]: object | object[] },
+ *   templates: { [name]: HalFormTemplate },     // HAL-FORMS extension
+ *
+ * @example
+ *   var r = b.hal.resource(
+ *     { title: "Hello", body: "World" },
+ *     { links: { self: "/articles/1",
+ *                next: { href: "/articles/2", title: "Next article" } } }
+ *   );
+ */
+function resource(payload, opts) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new HalError("hal/bad-payload",
+      "resource: payload must be a non-array object");
+  }
+  opts = opts || {};
+  validateOpts(opts, ["links", "embedded", "templates"], "hal.resource");
+  // Build resource by shallow-clone (don't mutate operator input).
+  var out = {};
+  var keys = Object.keys(payload);
+  for (var i = 0; i < keys.length; i += 1) {
+    var k = keys[i];
+    if (k === "_links" || k === "_embedded" || k === "_templates") {
+      // Operator-supplied reserved keys in payload override opts —
+      // refuse to avoid ambiguity.
+      throw new HalError("hal/reserved-key",
+        "resource: payload must not contain reserved key '" + k + "' (use opts." +
+        (k === "_templates" ? "templates" : k.slice(1)) + ")");
+    }
+    out[k] = payload[k];
+  }
+  if (opts.links) {
+    if (typeof opts.links !== "object" || Array.isArray(opts.links)) {
+      throw new HalError("hal/bad-links", "resource: opts.links must be a non-array object");
+    }
+    out._links = _normaliseLinks(opts.links);
+  }
+  if (opts.embedded) {
+    if (typeof opts.embedded !== "object" || Array.isArray(opts.embedded)) {
+      throw new HalError("hal/bad-embedded", "resource: opts.embedded must be a non-array object");
+    }
+    out._embedded = opts.embedded;
+  }
+  if (opts.templates) {
+    if (typeof opts.templates !== "object" || Array.isArray(opts.templates)) {
+      throw new HalError("hal/bad-templates", "resource: opts.templates must be a non-array object");
+    }
+    out._templates = opts.templates;
+  }
+  return out;
+}
+
+function _normaliseLinks(links) {
+  var out = {};
+  var keys = Object.keys(links);
+  for (var i = 0; i < keys.length; i += 1) {
+    var rel = keys[i];
+    var val = links[rel];
+    if (typeof val === "string") {
+      out[rel] = { href: val };
+    } else if (Array.isArray(val)) {
+      out[rel] = val.map(function (v, idx) {
+        if (typeof v === "string") return { href: v };
+        if (v && typeof v === "object" && typeof v.href === "string") return v;
+        throw new HalError("hal/bad-link",
+          "_links." + rel + "[" + idx + "] must be a string or LinkObject");
+      });
+    } else if (val && typeof val === "object" && typeof val.href === "string") {
+      out[rel] = val;
+    } else {
+      throw new HalError("hal/bad-link",
+        "_links." + rel + " must be a string, LinkObject, or LinkObject[]");
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  resource:      resource,
+  CONTENT_TYPE:  CONTENT_TYPE,
+  HalError:      HalError,
+};