@forumulate/sdk 0.7.0 → 0.10.0

package/dist/policy-feed.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyWebhookError = void 0;
+exports.policySecretKey = policySecretKey;
+exports.policyFeedSigningString = policyFeedSigningString;
+exports.signPolicyFeedRequest = signPolicyFeedRequest;
+exports.verifyPolicyFeedRequest = verifyPolicyFeedRequest;
+exports.verifyPolicyWebhook = verifyPolicyWebhook;
+exports.signPolicyWebhook = signPolicyWebhook;
+/**
+ * Forumulate policy feed v1, both directions — so any platform can CONSUME a
+ * Legal space's policies, or IMPLEMENT the same protocol itself.
+ *
+ *   feed request   consumer → source. `GET …/policies`, signed with three
+ *                  headers, `forumulate-id`, `forumulate-timestamp` (Unix
+ *                  MILLISECONDS) and `forumulate-signature`, or the same three
+ *                  as `atlas-*` (Atlas's spelling; the source takes both).
+ *                  Signature: `v1,` + base64(HMAC-SHA256(key,
+ *                  "{id}.{timestamp}.GET\n{path}")), `{path}` being the path
+ *                  plus query exactly as requested — with `/api` on
+ *                  forumulate.com. Several space-separated `v1,` values during
+ *                  a rotation; any one matching is enough.
+ *   webhook        source → consumer. Standard Webhooks: `webhook-id`,
+ *                  `webhook-timestamp` (Unix SECONDS), `webhook-signature:
+ *                  v1,<base64 HMAC-SHA256(key, "{id}.{timestamp}.{body}")>`.
+ *                  Bodies: `policy.published` {key, version} and
+ *                  `policy.retired` {key}. A webhook carries no policy text on
+ *                  purpose: the consumer fetches the feed for that.
+ *
+ * THE KEY. A secret is `whsec_` + base64 of 32 random bytes (the Standard
+ * Webhooks spelling), and the HMAC key is the DECODED bytes. A secret without
+ * that prefix is used as its own UTF-8 bytes. The source also accepts a feed
+ * request signed with a `whsec_` secret's raw UTF-8 bytes, because which of
+ * the two an HMAC call gets is the commonest mistake; the verifier below does
+ * the same, the signer always uses the decoded key.
+ *
+ * The server half lives in `packages/shared/src/policy-feed` (node:crypto);
+ * `policy-feed.test.ts` checks this file against it. WebCrypto here.
+ */
+const policy_crypto_1 = require("./policy-crypto");
+const enc = new TextEncoder();
+const SECRET_PREFIX = 'whsec_';
+/** Five minutes, both for the feed's millisecond clock and the webhook's seconds. */
+const DEFAULT_TOLERANCE_SECONDS = 300;
+function bytesToBase64(bytes) {
+    let s = '';
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s);
+}
+function base64ToBytes(s) {
+    try {
+        const bin = atob(s);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+/** The HMAC key a secret stands for: the decoded bytes of a `whsec_` secret, else its UTF-8. */
+function policySecretKey(secret) {
+    if (secret.startsWith(SECRET_PREFIX)) {
+        const raw = base64ToBytes(secret.slice(SECRET_PREFIX.length));
+        if (raw && raw.length > 0)
+            return raw;
+    }
+    return enc.encode(secret);
+}
+async function hmacBase64(key, data) {
+    const k = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return bytesToBase64(new Uint8Array(await crypto.subtle.sign('HMAC', k, enc.encode(data))));
+}
+/** The `v1,` values of a signature header (space separated), at most eight. */
+function signatureValues(header) {
+    return String(header ?? '')
+        .split(/\s+/)
+        .filter((v) => v.startsWith('v1,'))
+        .map((v) => v.slice(3))
+        .filter(Boolean)
+        .slice(0, 8);
+}
+function sameString(a, b) {
+    return (0, policy_crypto_1.equalBytes)(enc.encode(a), enc.encode(b));
+}
+function headerOf(headers, name) {
+    if (typeof headers.get === 'function') {
+        return headers.get(name);
+    }
+    const rec = headers;
+    const hit = Object.keys(rec).find((k) => k.toLowerCase() === name);
+    const v = hit === undefined ? undefined : rec[hit];
+    return Array.isArray(v) ? v.join(' ') : (v ?? null);
+}
+function randomId() {
+    const c = globalThis.crypto;
+    return c?.randomUUID ? `req_${c.randomUUID()}` : `req_${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
+}
+/* ------------------------------------------------------------------ *
+ * Feed requests
+ * ------------------------------------------------------------------ */
+/** The exact string a feed request signs. */
+function policyFeedSigningString(id, timestamp, path) {
+    return `${id}.${timestamp}.GET\n${path}`;
+}
+/**
+ * The three headers that sign one feed request. Use a fresh call per request:
+ * the id is single-use, so a retry must be signed again.
+ *
+ * ```ts
+ * const path = `/api/policy-feed/spaces/${spaceId}/policies`;
+ * const headers = await signPolicyFeedRequest({ secret: process.env.POLICY_FEED_SECRET!, path });
+ * const list = await (await fetch(`https://forumulate.com${path}`, { headers })).json();
+ * ```
+ */
+async function signPolicyFeedRequest(input) {
+    const p = input.prefix ?? 'forumulate';
+    const id = input.id ?? randomId();
+    const ts = String(Math.floor(input.timestamp ?? Date.now()));
+    const secrets = typeof input.secret === 'string' ? [input.secret] : input.secret;
+    if (!secrets.length || secrets.some((s) => !s))
+        throw new TypeError('signPolicyFeedRequest needs a secret');
+    const data = policyFeedSigningString(id, ts, input.path);
+    const sigs = await Promise.all(secrets.map(async (s) => `v1,${await hmacBase64(policySecretKey(s), data)}`));
+    return { [`${p}-id`]: id, [`${p}-timestamp`]: ts, [`${p}-signature`]: sigs.join(' ') };
+}
+/**
+ * Check a signed feed request — the half a policy SOURCE implements. Either
+ * header spelling (`forumulate-*` or `atlas-*`) is read.
+ */
+async function verifyPolicyFeedRequest(input) {
+    let id = null;
+    let ts = null;
+    let sig = null;
+    for (const p of ['forumulate', 'atlas']) {
+        id = headerOf(input.headers, `${p}-id`);
+        ts = headerOf(input.headers, `${p}-timestamp`);
+        sig = headerOf(input.headers, `${p}-signature`);
+        if (id && ts && sig)
+            break;
+    }
+    if (!id || !ts || !sig)
+        return { valid: false, reason: 'missing_headers' };
+    const now = input.now ?? Date.now();
+    // Digits only: `1e12`, hex or a float is refused rather than coerced.
+    if (!/^\d{1,16}$/.test(ts) || Math.abs(Number(ts) - now) > (input.toleranceMs ?? DEFAULT_TOLERANCE_SECONDS * 1000))
+        return { valid: false, reason: 'stale_timestamp' };
+    const presented = signatureValues(sig);
+    const secrets = typeof input.secrets === 'string' ? [input.secrets] : input.secrets;
+    const paths = typeof input.path === 'string' ? [input.path] : input.path;
+    let ok = false;
+    // Every candidate is tried, so the time taken does not say which matched.
+    for (const secret of secrets) {
+        if (!secret)
+            continue;
+        for (const key of [policySecretKey(secret), enc.encode(secret)]) {
+            for (const path of paths) {
+                const expected = await hmacBase64(key, policyFeedSigningString(id, ts, path));
+                for (const s of presented)
+                    if (sameString(s, expected))
+                        ok = true;
+            }
+        }
+    }
+    if (!ok)
+        return { valid: false, reason: 'bad_signature' };
+    // Checked AFTER the signature, so an unsigned flood cannot fill the replay store.
+    if (input.seen && (await input.seen(id)))
+        return { valid: false, reason: 'replayed' };
+    return { valid: true, id };
+}
+/* ------------------------------------------------------------------ *
+ * Webhooks
+ * ------------------------------------------------------------------ */
+class PolicyWebhookError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'PolicyWebhookError';
+    }
+}
+exports.PolicyWebhookError = PolicyWebhookError;
+/**
+ * Verify a `policy.published` / `policy.retired` notice and parse it. Throws
+ * {@link PolicyWebhookError} — the parse can never run ahead of the check.
+ *
+ * `body` must be the RAW request body: a re-serialised object has different
+ * bytes and never verifies. During a secret rotation pass both secrets.
+ * Dedupe on `webhook-id`: a retry of one event reuses it.
+ *
+ * ```ts
+ * const event = await verifyPolicyWebhook(req.headers, rawBody, process.env.POLICY_FEED_SECRET!);
+ * if (event.type === 'policy.published') await refreshPolicies(event.key);
+ * ```
+ */
+async function verifyPolicyWebhook(headers, body, secret, opts = {}) {
+    const id = headerOf(headers, 'webhook-id');
+    const ts = headerOf(headers, 'webhook-timestamp');
+    const sig = headerOf(headers, 'webhook-signature');
+    if (!id || !ts || !sig) {
+        throw new PolicyWebhookError('missing_headers', 'webhook-id, webhook-timestamp and webhook-signature are required');
+    }
+    const tolerance = opts.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    if (!/^\d{1,12}$/.test(ts))
+        throw new PolicyWebhookError('stale_timestamp', 'webhook-timestamp is not Unix seconds');
+    if (tolerance > 0) {
+        const now = Math.floor((opts.now ?? Date.now()) / 1000);
+        if (Math.abs(now - Number(ts)) > tolerance) {
+            throw new PolicyWebhookError('stale_timestamp', 'webhook-timestamp is outside the tolerance window');
+        }
+    }
+    const text = typeof body === 'string' ? body : new TextDecoder().decode(body);
+    const presented = signatureValues(sig);
+    const secrets = typeof secret === 'string' ? [secret] : secret;
+    let ok = false;
+    for (const s of secrets) {
+        if (!s)
+            continue;
+        const expected = await hmacBase64(policySecretKey(s), `${id}.${ts}.${text}`);
+        for (const p of presented)
+            if (sameString(p, expected))
+                ok = true;
+    }
+    if (!ok)
+        throw new PolicyWebhookError('bad_signature', 'Policy webhook signature did not verify (wrong secret or altered body)');
+    let event;
+    try {
+        event = JSON.parse(text);
+    }
+    catch {
+        throw new PolicyWebhookError('bad_body', 'Policy webhook body is not JSON');
+    }
+    if (!event || (event.type !== 'policy.published' && event.type !== 'policy.retired') || typeof event.key !== 'string') {
+        throw new PolicyWebhookError('bad_body', 'Not a policy.published or policy.retired notice');
+    }
+    return event;
+}
+/** Standard Webhooks headers for one notice — the SENDING half, for a platform implementing the protocol. */
+async function signPolicyWebhook(input) {
+    const id = input.id ?? `msg_${randomId().slice(4)}`;
+    const ts = String(Math.floor(input.timestamp ?? Date.now() / 1000));
+    const secrets = typeof input.secret === 'string' ? [input.secret] : input.secret;
+    const sigs = await Promise.all(secrets.map(async (s) => `v1,${await hmacBase64(policySecretKey(s), `${id}.${ts}.${input.body}`)}`));
+    return { 'webhook-id': id, 'webhook-timestamp': ts, 'webhook-signature': sigs.join(' ') };
+}
+//# sourceMappingURL=policy-feed.js.map

package/dist/policy-tickets.d.ts

@@ -0,0 +1,55 @@
+import { type PolicyGateEvent, type PolicyGateKey } from './policy-tokens';
+export interface PolicyTicketInput {
+    orgId: string;
+    /** The Legal space. */
+    spaceId: string;
+    /** Your id for the user. Opaque to Forumulate; up to 200 characters. */
+    subject: string;
+    event: PolicyGateEvent;
+    /** Hashed here, before it leaves your server; never sent in clear. */
+    email?: string;
+    /** The email's hash instead (`policyEmailHash`), e.g. from a ticket you verified. */
+    emailHash?: string;
+    /** Your name for the app (`web`, `ios`), recorded as `sourceApp`. */
+    sourceApp?: string;
+    /** Hosted page only: where to send the reader back. Must match the space's `page.returnUrls`. */
+    returnUrl?: string;
+    /** Hosted page only: echoed back verbatim, like OAuth `state`. */
+    state?: string;
+    locale?: string;
+    /** 30–3600 seconds. Default 600. */
+    ttlSeconds?: number;
+    /** Unix seconds; defaults to now. */
+    now?: number;
+}
+/**
+ * Sign a ticket with a key of the space's keyring — no call to Forumulate.
+ * Hand it to the widget (`ticket` attribute / prop) or put it on the hosted
+ * page's URL with {@link policyGatePageUrl}.
+ */
+export declare function signPolicyTicket(input: PolicyTicketInput, key: PolicyGateKey | string): Promise<string>;
+/**
+ * The hosted acceptance page for a ticket that carries a `returnUrl`:
+ * `https://forumulate.com/policy/{orgId}/{spaceId}?ticket=…`. Redirect the
+ * user there; they come back to `returnUrl` with `policy_token` (or
+ * `policy_error`) and your `state` — read it with {@link readPolicyReturn}.
+ */
+export declare function policyGatePageUrl(input: {
+    orgId: string;
+    spaceId: string;
+    ticket: string;
+    /** The site the page is served from. Default `https://forumulate.com`. */
+    site?: string;
+}): string;
+export interface PolicyReturn {
+    /** The acceptance token, when the user accepted (or there was nothing to accept). */
+    token: string | null;
+    tokenType: 'acceptance' | 'receipt' | null;
+    /** `declined` when a blocking policy was declined. */
+    error: string | null;
+    /** Your `state`, verbatim. Compare it with what you stored before redirecting. */
+    state: string | null;
+}
+/** Read the query the hosted page appended to your return URL. Verify `token` before trusting it. */
+export declare function readPolicyReturn(url: string | URL | URLSearchParams): PolicyReturn;
+//# sourceMappingURL=policy-tickets.d.ts.map

package/dist/policy-tickets.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signPolicyTicket = signPolicyTicket;
+exports.policyGatePageUrl = policyGatePageUrl;
+exports.readPolicyReturn = readPolicyReturn;
+/**
+ * Tickets and the hosted page round trip: the half of the policy gate your
+ * server SIGNS. See `./policy-tokens` for the format and the verifiers.
+ */
+const policy_crypto_1 = require("./policy-crypto");
+const policy_tokens_1 = require("./policy-tokens");
+const enc = new TextEncoder();
+/**
+ * Sign a ticket with a key of the space's keyring — no call to Forumulate.
+ * Hand it to the widget (`ticket` attribute / prop) or put it on the hosted
+ * page's URL with {@link policyGatePageUrl}.
+ */
+async function signPolicyTicket(input, key) {
+    const k = typeof key === 'string' ? ((0, policy_tokens_1.parsePolicyGateKeys)(key)[0] ?? null) : key;
+    if (!k?.secret)
+        throw new TypeError('signPolicyTicket needs a key: { kid, secret } or "pgk_…:pgs_…"');
+    const ttl = Math.min(Math.max(Math.floor(input.ttlSeconds ?? 600), 30), policy_tokens_1.POLICY_TICKET_MAX_SECONDS);
+    const iat = input.now ?? Math.floor(Date.now() / 1000);
+    const claims = {
+        use: 'ticket',
+        aud: policy_tokens_1.POLICY_TOKEN_AUDIENCE,
+        org: input.orgId,
+        spc: input.spaceId,
+        sub: input.subject,
+        evt: input.event,
+        iat,
+        exp: iat + ttl,
+    };
+    if (input.email)
+        claims.eh = await (0, policy_tokens_1.policyEmailHash)(input.email);
+    else if (input.emailHash)
+        claims.eh = input.emailHash;
+    if (input.sourceApp)
+        claims.app = input.sourceApp;
+    if (input.returnUrl)
+        claims.ret = input.returnUrl;
+    if (input.state)
+        claims.st = input.state;
+    if (input.locale)
+        claims.loc = input.locale;
+    const head = (0, policy_crypto_1.base64UrlEncode)(enc.encode(JSON.stringify({ alg: 'HS256', typ: 'JWT', kid: k.kid })));
+    const body = (0, policy_crypto_1.base64UrlEncode)(enc.encode(JSON.stringify(claims)));
+    const sig = await (0, policy_tokens_1.hmacBytes)(enc.encode(k.secret), `${head}.${body}`);
+    return `${head}.${body}.${(0, policy_crypto_1.base64UrlEncode)(sig)}`;
+}
+/**
+ * The hosted acceptance page for a ticket that carries a `returnUrl`:
+ * `https://forumulate.com/policy/{orgId}/{spaceId}?ticket=…`. Redirect the
+ * user there; they come back to `returnUrl` with `policy_token` (or
+ * `policy_error`) and your `state` — read it with {@link readPolicyReturn}.
+ */
+function policyGatePageUrl(input) {
+    const site = (input.site ?? 'https://forumulate.com').replace(/\/+$/, '');
+    const e = encodeURIComponent;
+    return `${site}/policy/${e(input.orgId)}/${e(input.spaceId)}?ticket=${e(input.ticket)}`;
+}
+/** Read the query the hosted page appended to your return URL. Verify `token` before trusting it. */
+function readPolicyReturn(url) {
+    const q = url instanceof URLSearchParams
+        ? url
+        : new URL(String(url), 'https://return.invalid').searchParams;
+    const type = q.get('policy_token_type');
+    return {
+        token: q.get('policy_token'),
+        tokenType: type === 'acceptance' || type === 'receipt' ? type : null,
+        error: q.get('policy_error'),
+        state: q.get('state'),
+    };
+}
+//# sourceMappingURL=policy-tickets.js.map

package/dist/policy-tokens.d.ts

@@ -0,0 +1,188 @@
+export declare const POLICY_TOKEN_AUDIENCE = "forumulate:policy-gate";
+/** A ticket may live this long at most; the API refuses a longer one. */
+export declare const POLICY_TICKET_MAX_SECONDS = 3600;
+export type PolicyGateEvent = 'sign_up' | 'sign_in';
+export type PolicyTokenUse = 'ticket' | 'acceptance' | 'receipt';
+/** A key of the space's keyring. `kid` may be empty for a bare secret. */
+export interface PolicyGateKey {
+    kid: string;
+    secret: string;
+}
+/** One accepted version inside an acceptance token or a receipt. */
+export interface PolicyTokenAcceptance {
+    /** Policy key (`tos`, `privacy`). */
+    k: string;
+    /** The version accepted. */
+    v: string;
+    /** SHA-256 (hex) of exactly the HTML that was shown. */
+    h: string;
+    /** The presentation it was shown in. */
+    p: string;
+    /** Whether the reader scrolled to the end. */
+    s: boolean;
+    /** Unix seconds, on Forumulate's database clock. */
+    at: number;
+}
+export interface PolicyTicketClaims {
+    use: 'ticket';
+    aud: typeof POLICY_TOKEN_AUDIENCE;
+    org: string;
+    spc: string;
+    sub: string;
+    evt: PolicyGateEvent;
+    eh?: string;
+    app?: string;
+    ret?: string;
+    st?: string;
+    loc?: string;
+    iat: number;
+    exp: number;
+    iss?: string;
+}
+export interface PolicyAcceptanceClaims {
+    use: 'acceptance' | 'receipt';
+    aud: typeof POLICY_TOKEN_AUDIENCE;
+    iss: 'forumulate';
+    org: string;
+    spc: string;
+    /** Absent on a receipt. */
+    sub?: string;
+    evt: PolicyGateEvent;
+    /** Nothing blocking is left for this subject and event. */
+    ok: boolean;
+    /** Keys still blocking. */
+    pend: string[];
+    acc: PolicyTokenAcceptance[];
+    ctx?: {
+        ip?: string;
+        ua?: string;
+        loc?: string;
+        app?: string;
+        eh?: string;
+    };
+    jti: string;
+    iat: number;
+    exp: number;
+}
+export type PolicyTokenFailure = 'malformed' | 'unsupported_algorithm' | 'unknown_key' | 'bad_signature' | 'expired' | 'not_yet_valid' | 'wrong_audience' | 'wrong_issuer' | 'wrong_use' | 'wrong_subject' | 'wrong_space' | 'wrong_org' | 'not_satisfied' | 'no_keys';
+export type VerifiedAcceptance = {
+    valid: true;
+    claims: PolicyAcceptanceClaims;
+    /** The key that signed it. */
+    kid: string;
+    /** `claims.ok`: nothing blocking is left. */
+    satisfied: boolean;
+    /** `claims.pend`: the keys still blocking. */
+    pending: string[];
+} | {
+    valid: false;
+    reason: PolicyTokenFailure;
+};
+/** A JSON Web Key Set of symmetric (`kty: "oct"`) keys. */
+export interface PolicyJwks {
+    keys: {
+        kty: string;
+        kid?: string;
+        k?: string;
+        alg?: string;
+    }[];
+}
+export interface VerifyAcceptanceTokenOptions {
+    /**
+     * The keyring: `[{ kid, secret }]`, or the env-var form
+     * `"pgk_a:pgs_…,pgk_b:pgs_…"`. During a rotation keep both keys here; the
+     * token's `kid` picks the right one.
+     */
+    keys?: readonly PolicyGateKey[] | string;
+    /** One bare secret, tried against any `kid`. */
+    secret?: string;
+    /**
+     * A URL serving YOUR keyring as a JWKS of `oct` keys (`k` = base64url of the
+     * secret's UTF-8 bytes) — a private endpoint of your own, e.g. in front of a
+     * secrets manager. The keys are symmetric, so Forumulate never publishes
+     * them; this is for teams that keep secrets out of the environment. Cached
+     * for `jwksCacheSeconds` and refetched once on an unknown `kid`.
+     */
+    jwksUrl?: string;
+    /** The same set, already in hand. */
+    jwks?: PolicyJwks;
+    /** Headers for the `jwksUrl` request (its own authorization). */
+    jwksHeaders?: Record<string, string>;
+    /** Default 300. */
+    jwksCacheSeconds?: number;
+    /** Which kinds to accept. Default `'acceptance'`; add `'receipt'` on a sign-up form. */
+    use?: 'acceptance' | 'receipt' | readonly ('acceptance' | 'receipt')[];
+    /** The token must be for this user (your id for them). */
+    subject?: string;
+    /** The token must be for this Legal space. */
+    spaceId?: string;
+    /** The token must be for this organization. */
+    orgId?: string;
+    /** Refuse a token with blocking policies still pending (`reason: 'not_satisfied'`). */
+    requireSatisfied?: boolean;
+    /** Unix seconds; defaults to now. */
+    now?: number;
+    /** Clock skew tolerated either way, seconds. Default 30. */
+    leewaySeconds?: number;
+    fetch?: typeof fetch;
+}
+export declare function hmacBytes(key: Uint8Array, data: string): Promise<Uint8Array>;
+/**
+ * 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.
+ */
+export declare function parsePolicyGateKeys(value: string | undefined | null): PolicyGateKey[];
+/** SHA-256 hex of a string's UTF-8 bytes (the content hash). */
+export declare function policySha256Hex(text: string): Promise<string>;
+/** How an email becomes `emailHash`: trimmed, lower-cased, SHA-256 hex. */
+export declare function policyEmailHash(email: string): Promise<string>;
+/** Header and claims, UNVERIFIED — for logs and for picking a key. Never for decisions. */
+export declare function decodePolicyToken(token: string): {
+    header: {
+        alg?: string;
+        kid?: string;
+        typ?: string;
+    };
+    claims: Record<string, unknown>;
+} | null;
+/**
+ * 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`.
+ */
+export declare function verifyAcceptanceToken(token: string, opts: VerifyAcceptanceTokenOptions): Promise<VerifiedAcceptance>;
+/** Key options shared by every verifier. */
+export type PolicyKeyOptions = Pick<VerifyAcceptanceTokenOptions, 'keys' | 'secret' | 'jwks' | 'jwksUrl' | 'jwksHeaders' | 'jwksCacheSeconds' | 'fetch'>;
+/**
+ * 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.
+ */
+export declare function verifyPolicyTicket(token: string, opts: PolicyKeyOptions & {
+    subject?: string;
+    spaceId?: string;
+    orgId?: string;
+    now?: number;
+    leewaySeconds?: number;
+}): Promise<{
+    valid: true;
+    claims: PolicyTicketClaims;
+    kid: string;
+} | {
+    valid: false;
+    reason: PolicyTokenFailure;
+}>;
+//# sourceMappingURL=policy-tokens.d.ts.map