@forumulate/sdk 0.7.0 → 0.10.0

package/dist/policy-tokens.js

@@ -0,0 +1,251 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POLICY_TICKET_MAX_SECONDS = exports.POLICY_TOKEN_AUDIENCE = void 0;
+exports.hmacBytes = hmacBytes;
+exports.parsePolicyGateKeys = parsePolicyGateKeys;
+exports.policySha256Hex = policySha256Hex;
+exports.policyEmailHash = policyEmailHash;
+exports.decodePolicyToken = decodePolicyToken;
+exports.verifyAcceptanceToken = verifyAcceptanceToken;
+exports.verifyPolicyTicket = verifyPolicyTicket;
+/**
+ * The policy gate's tokens, on YOUR server: sign a ticket, verify an
+ * acceptance token, offline.
+ *
+ * The gate hands three kinds of compact HS256 JWT around, all signed with a
+ * key of the Legal space's keyring (`pgk_…` id, `pgs_…` secret):
+ *
+ *   ticket      your server → the browser: "this browser acts for user S, for
+ *               event E". You sign it; the widget and the hosted page present
+ *               it, so nobody can accept in somebody else's name.
+ *   acceptance  Forumulate → your server: "S accepted these exact versions,
+ *               shown this way, and is / is not clear to proceed".
+ *   receipt     an acceptance with no subject yet (a sign-up form accepted
+ *               before the account existed); redeem it with
+ *               `client.policies.claim`.
+ *
+ * The same key signs tickets (you) and acceptance tokens (us), so a verifier
+ * MUST check `use`: without that, a ticket — which you hand to the browser —
+ * would verify as proof of acceptance. `verifyAcceptanceToken` checks it, and
+ * the audience, the issuer, the expiry and (when you pass them) the subject
+ * and the space.
+ *
+ * The format is the one in `packages/shared/src/policy-gate/token.ts`, which
+ * signs the real tokens; `policy-tokens.test.ts` signs with that file and
+ * verifies with this one, so the two cannot drift apart quietly. It is a plain
+ * JWT on purpose: any JWT library in any language verifies it with the secret.
+ *
+ * WebCrypto only — Node ≥ 20, Bun, Deno, Workers, Auth0 Actions, a browser.
+ */
+const policy_crypto_1 = require("./policy-crypto");
+exports.POLICY_TOKEN_AUDIENCE = 'forumulate:policy-gate';
+/** A ticket may live this long at most; the API refuses a longer one. */
+exports.POLICY_TICKET_MAX_SECONDS = 3600;
+const enc = new TextEncoder();
+async function hmacBytes(key, data) {
+    const k = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return new Uint8Array(await crypto.subtle.sign('HMAC', k, enc.encode(data)));
+}
+/**
+ * Parse a keyring from one environment variable: `kid:secret` pairs separated
+ * by commas or whitespace (`FORUMULATE_POLICY_GATE_KEYS`). A bare secret is
+ * kept with an empty `kid` and tried against every token.
+ */
+function parsePolicyGateKeys(value) {
+    return (value ?? '')
+        .split(/[\s,]+/)
+        .filter(Boolean)
+        .map((entry) => {
+        const i = entry.indexOf(':');
+        return i > 0 && entry.startsWith('pgk_')
+            ? { kid: entry.slice(0, i), secret: entry.slice(i + 1) }
+            : { kid: '', secret: entry };
+    });
+}
+/** SHA-256 hex of a string's UTF-8 bytes (the content hash). */
+async function policySha256Hex(text) {
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', enc.encode(text)));
+    let out = '';
+    for (const b of digest)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+/** How an email becomes `emailHash`: trimmed, lower-cased, SHA-256 hex. */
+function policyEmailHash(email) {
+    return policySha256Hex(email.trim().toLowerCase());
+}
+/** Header and claims, UNVERIFIED — for logs and for picking a key. Never for decisions. */
+function decodePolicyToken(token) {
+    const parts = String(token ?? '').split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const dec = new TextDecoder();
+        const header = JSON.parse(dec.decode((0, policy_crypto_1.base64UrlDecode)(parts[0])));
+        const claims = JSON.parse(dec.decode((0, policy_crypto_1.base64UrlDecode)(parts[1])));
+        if (!header || typeof header !== 'object' || !claims || typeof claims !== 'object')
+            return null;
+        return { header, claims };
+    }
+    catch {
+        return null;
+    }
+}
+const jwksCache = new Map();
+function ringFromJwks(set) {
+    const out = [];
+    for (const k of set?.keys ?? []) {
+        if (k.kty !== 'oct' || typeof k.k !== 'string')
+            continue;
+        if (k.alg && k.alg !== 'HS256')
+            continue;
+        try {
+            out.push({ kid: k.kid ?? '', bytes: (0, policy_crypto_1.base64UrlDecode)(k.k) });
+        }
+        catch {
+            /* a malformed entry is skipped, not fatal: the others may still verify */
+        }
+    }
+    return out;
+}
+async function loadJwks(opts, force) {
+    const url = opts.jwksUrl;
+    const ttl = (opts.jwksCacheSeconds ?? 300) * 1000;
+    const hit = jwksCache.get(url);
+    if (hit && !force && Date.now() - hit.at < ttl)
+        return hit.keys;
+    const f = opts.fetch ?? globalThis.fetch;
+    const res = await f(url, { headers: { accept: 'application/json', ...(opts.jwksHeaders ?? {}) } });
+    if (!res.ok)
+        throw new Error(`Could not load the policy gate keys from ${url}: HTTP ${res.status}`);
+    const keys = ringFromJwks((await res.json()));
+    jwksCache.set(url, { at: Date.now(), keys });
+    return keys;
+}
+function staticRing(opts) {
+    const ring = [];
+    const list = typeof opts.keys === 'string' ? parsePolicyGateKeys(opts.keys) : (opts.keys ?? []);
+    for (const k of list)
+        if (k.secret)
+            ring.push({ kid: k.kid ?? '', bytes: enc.encode(k.secret) });
+    if (opts.secret)
+        ring.push({ kid: '', bytes: enc.encode(opts.secret) });
+    ring.push(...ringFromJwks(opts.jwks));
+    return ring;
+}
+/** The key(s) to try: the one named by `kid`, else every id-less key. */
+function candidates(ring, kid) {
+    const named = ring.filter((k) => k.kid && k.kid === kid);
+    return named.length ? named : ring.filter((k) => !k.kid);
+}
+/**
+ * Verify an acceptance token (or receipt) OFFLINE, against your copy of the
+ * space's keyring. Returns a result rather than throwing, so the reason is in
+ * hand for a log line:
+ *
+ * ```ts
+ * const r = await verifyAcceptanceToken(token, {
+ *   keys: process.env.FORUMULATE_POLICY_GATE_KEYS,
+ *   subject: user.id,
+ *   spaceId: process.env.FORUMULATE_LEGAL_SPACE,
+ *   requireSatisfied: true,
+ * });
+ * if (!r.valid) return res.status(403).send(r.reason);
+ * ```
+ *
+ * Online verification (no key on your server) is `client.policies.verify`.
+ */
+async function verifyAcceptanceToken(token, opts) {
+    const signed = await verifySignature(token, opts);
+    if (!signed.ok)
+        return { valid: false, reason: signed.reason };
+    const c = signed.claims;
+    const uses = opts.use === undefined ? ['acceptance'] : typeof opts.use === 'string' ? [opts.use] : opts.use;
+    // A ticket is signed with the same key; checking `use` is what keeps one
+    // from passing as proof of acceptance.
+    const failed = checkClaims(c, uses, opts);
+    if (failed)
+        return { valid: false, reason: failed };
+    if (c.iss !== 'forumulate')
+        return { valid: false, reason: 'wrong_issuer' };
+    const pending = Array.isArray(c.pend) ? c.pend : [];
+    const satisfied = c.ok === true;
+    if (opts.requireSatisfied && !satisfied)
+        return { valid: false, reason: 'not_satisfied' };
+    return { valid: true, claims: c, kid: signed.kid, satisfied, pending };
+}
+/**
+ * Verify a TICKET (yours, signed with the same keyring), for a server that
+ * receives one back: a bridge between an auth platform's redirect and the
+ * hosted page, say. A ticket meant to live longer than an hour is refused.
+ */
+async function verifyPolicyTicket(token, opts) {
+    const signed = await verifySignature(token, opts);
+    if (!signed.ok)
+        return { valid: false, reason: signed.reason };
+    const c = signed.claims;
+    const failed = checkClaims(c, ['ticket'], opts);
+    if (failed)
+        return { valid: false, reason: failed };
+    if (typeof c.iat !== 'number' || c.exp - c.iat > exports.POLICY_TICKET_MAX_SECONDS)
+        return { valid: false, reason: 'expired' };
+    return { valid: true, claims: c, kid: signed.kid };
+}
+/** The checks every kind shares: audience, use, time, and the ids you pinned. */
+function checkClaims(c, uses, opts) {
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    const leeway = opts.leewaySeconds ?? 30;
+    if (c.aud !== exports.POLICY_TOKEN_AUDIENCE)
+        return 'wrong_audience';
+    if (typeof c.use !== 'string' || !uses.includes(c.use))
+        return 'wrong_use';
+    if (typeof c.exp !== 'number' || c.exp + leeway < now)
+        return 'expired';
+    if (typeof c.iat === 'number' && c.iat - leeway > now)
+        return 'not_yet_valid';
+    if (opts.subject !== undefined && c.sub !== opts.subject)
+        return 'wrong_subject';
+    if (opts.spaceId !== undefined && c.spc !== opts.spaceId)
+        return 'wrong_space';
+    if (opts.orgId !== undefined && c.org !== opts.orgId)
+        return 'wrong_org';
+    return null;
+}
+/** The signature half: HS256 only, the key picked by `kid`, compared in constant time. */
+async function verifySignature(token, opts) {
+    const parts = String(token ?? '').split('.');
+    const decoded = parts.length === 3 ? decodePolicyToken(token) : null;
+    if (!decoded)
+        return { ok: false, reason: 'malformed' };
+    // `alg` is read from the token only to REFUSE anything but HS256, never to
+    // choose an algorithm: that is the classic `alg: none` hole.
+    if (decoded.header.alg !== 'HS256')
+        return { ok: false, reason: 'unsupported_algorithm' };
+    let sig;
+    try {
+        sig = (0, policy_crypto_1.base64UrlDecode)(parts[2]);
+    }
+    catch {
+        return { ok: false, reason: 'malformed' };
+    }
+    let ring = staticRing(opts);
+    if (opts.jwksUrl)
+        ring = ring.concat(await loadJwks(opts, false));
+    if (!ring.length)
+        return { ok: false, reason: 'no_keys' };
+    let keys = candidates(ring, decoded.header.kid);
+    if (!keys.length && opts.jwksUrl) {
+        // A kid we have not seen: the keyring was rotated since the cache filled.
+        ring = staticRing(opts).concat(await loadJwks(opts, true));
+        keys = candidates(ring, decoded.header.kid);
+    }
+    if (!keys.length)
+        return { ok: false, reason: 'unknown_key' };
+    for (const key of keys) {
+        if ((0, policy_crypto_1.equalBytes)(await hmacBytes(key.bytes, `${parts[0]}.${parts[1]}`), sig)) {
+            return { ok: true, claims: decoded.claims, kid: key.kid };
+        }
+    }
+    return { ok: false, reason: 'bad_signature' };
+}
+//# sourceMappingURL=policy-tokens.js.map

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/schema.d.ts
-size: 41339026 bytes
-sha256: c747558055875df3c7006a060a53b57e9df6bc42e11b34c60ea3ee68ec437a0d
+size: 36704471 bytes
+sha256: 7f11d91a26719f96df4319c5f35eeef6cb0acdc29f4895f52f36c18d0b4903f7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forumulate/sdk",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "description": "Typed TypeScript client for the Forumulate REST API.",
   "license": "MIT",
   "homepage": "https://forumulate.com/reference",
@@ -25,6 +25,7 @@
     "dist",
     "!dist/**/*.map",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "publishConfig": {