open-action-consent 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+Open Action Consent (OAC)
+Copyright 2026 Ishan Srivastava
+
+Code, schemas and test vectors: Apache License 2.0 (LICENSE).
+Specification text: CC BY 4.0 (LICENSE-SPEC).

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# open-action-consent (JavaScript / TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A verifiable "yes" for things AI agents do for people.** Preview → signed Consent → the action runs only if it
+checks out → signed Receipt with Undo. Zero runtime dependencies for the core.
+Spec and source: <https://github.com/Ishan2036924/open-action-consent>
+
+## Everything in this one package
+
+| Part | Import | Also install | Guide |
+|---|---|---|---|
+| Core: previews, consents, mandates, receipts, undo, status lists, key discovery, `Gate` | `open-action-consent` | nothing | [README](https://github.com/Ishan2036924/open-action-consent#readme) |
+| MCP servers (official MCP TypeScript SDK v2) | `open-action-consent/mcp` | `@modelcontextprotocol/server` | [guide](https://github.com/Ishan2036924/open-action-consent/blob/main/guides/mcp-typescript.md) |
+| Vercel AI SDK 7 | `open-action-consent/vercel-ai` | `ai` | [guide](https://github.com/Ishan2036924/open-action-consent/blob/main/guides/vercel-ai.md) |
+
+```
+npm install open-action-consent
+```
+
+```ts
+import { Gate, buildPreview, makeConsent, verifyConsent, KeySet } from "open-action-consent";
+```
+
+Needs Node 22.14+ (or a modern bundler). Python, the Gated Browser and the approval page: `pip install
+open-action-consent`. License: Apache-2.0 (code), CC BY 4.0 (spec text).

package/dist/conformance.d.ts

@@ -0,0 +1,5 @@
+export declare function runCase(c: any): unknown;
+export declare function run(dir: string): {
+    total: number;
+    failures: string[];
+};

package/dist/conformance.js

@@ -0,0 +1,81 @@
+// Conformance runner: `node src/conformance.ts <vectors dir>`. Runs every case in vectors/*.json and exits non-zero
+// if any result differs from the expected one. Same files as the Python runner.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { OACError } from "./errors.js";
+import { canonical, parse } from "./jcs.js";
+import { digest, KeySet, sign } from "./jws.js";
+import * as shapes from "./shapes.js";
+import { tierFor } from "./tiers.js";
+import { checkBinding } from "./preview.js";
+import { MemoryNonces, verifyConsent } from "./consent.js";
+import { checkMandate, loosens } from "./mandate.js";
+import { verifyChain } from "./receipts.js";
+import { checkUndo } from "./undo.js";
+import { vectorKey } from "./testing.js";
+import { bit, decode } from "./status.js";
+import { keysetFrom, metadataUrl } from "./discovery.js";
+const OK = { ok: true };
+const OPS = {
+    jcs: (i) => ({ canonical: canonical(i.value) }),
+    parse: (i) => ({ canonical: canonical(parse(i.text)) }),
+    digest: (i) => ({ digest: digest(i.value) }),
+    tier: (i) => ({ tier: tierFor(i.profile, { policyFloor: i.policy_floor, tainted: i.tainted, hint: i.hint }) }),
+    sign: (i) => ({ token: sign(i.payload, vectorKey(i.key, i.alg ?? "EdDSA"), i.typ) }),
+    profile: (i) => (shapes.profile(i.profile), OK),
+    binding: (i) => (checkBinding(i.preview, i.action, i.profile), OK),
+    verify_consent: (i) => (verifyConsent(i.token, {
+        keys: new KeySet(i.keys), executor: i.executor, sub: i.sub, previews: i.previews, actions: i.actions, profiles: i.profiles,
+        now: i.now, nonces: new MemoryNonces(i.seen_nonces ?? []), policyFloor: i.policy_floor, tainted: i.tainted ?? false,
+    }), OK),
+    check_mandate: (i) => (checkMandate(i.token, {
+        keys: new KeySet(i.keys), action: i.action, profile: i.profile, holder: i.holder, sub: i.sub, now: i.now,
+        tainted: i.tainted, usage: i.usage, revoked: i.revoked ?? [], statusLists: i.status_lists ?? {},
+    }), OK),
+    loosens: (i) => ({ reasons: loosens(i.old, i.new).sort() }),
+    verify_chain: (i) => (verifyChain(i.tokens, { keys: new KeySet(i.keys), executor: i.executor, sub: i.sub, seals: i.seals ?? [],
+        sealKeys: i.seal_keys ? new KeySet(i.seal_keys) : null }), OK),
+    check_undo: (i) => (checkUndo(i.token, {
+        keys: new KeySet(i.keys), executor: i.executor, receiptToken: i.receipt_token, receiptKeys: new KeySet(i.receipt_keys),
+        now: i.now, nonces: new MemoryNonces(i.seen_nonces ?? []), undone: i.undone ?? [], compensation: i.compensation,
+    }), OK),
+    status_bit: (i) => ({ revoked: bit(decode(i.encoded_list), i.index) }),
+    metadata_url: (i) => ({ url: metadataUrl(i.iss) }),
+    keyset_from: (i) => ({ issuer: keysetFrom(i.docs.map((d) => [d[0], d[1]])).issuer(i.kid) }),
+};
+export function runCase(c) {
+    try {
+        return OPS[c.op](c.input);
+    }
+    catch (e) {
+        if (e instanceof OACError)
+            return { error: e.code };
+        throw e;
+    }
+}
+export function run(dir) {
+    let total = 0;
+    const failures = [];
+    for (const name of fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort()) {
+        for (const c of parse(fs.readFileSync(path.join(dir, name))).cases) { // strict parser, as for the wire
+            total += 1;
+            let got;
+            try {
+                got = runCase(c);
+            }
+            catch (e) {
+                got = { crash: String(e) };
+            }
+            if (canonical(got) !== canonical(c.expect))
+                failures.push(`${name} :: ${c.name}: expected ${JSON.stringify(c.expect)}, got ${JSON.stringify(got)}`);
+        }
+    }
+    return { total, failures };
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const { total, failures } = run(process.argv[2] ?? "vectors");
+    for (const f of failures)
+        console.log("FAIL", f);
+    console.log(`oac conformance (typescript): ${total - failures.length}/${total} passed`);
+    process.exit(failures.length ? 1 : 0);
+}

package/dist/consent.d.ts

@@ -0,0 +1,39 @@
+import { KeySet, type SigningKey } from "./jws.ts";
+export declare const TYP = "oac-consent+jws";
+export declare const MAX_S = 900;
+export declare const SKEW_S = 60;
+/** Record jti until exp and return true, or return false if already recorded. Must be atomic (insert-if-absent). */
+export interface NonceStore {
+    useOnce(jti: string, exp: number): boolean;
+}
+export declare class MemoryNonces implements NonceStore {
+    private s;
+    constructor(seen?: Iterable<string>);
+    useOnce(jti: string, exp: number): boolean;
+}
+export declare const newNonce: () => string;
+export declare function makeConsent(o: {
+    key: SigningKey;
+    iss: string;
+    sub: string;
+    aud: string;
+    previews: Record<string, any>[];
+    now: number;
+    ttl?: number;
+    jti?: string;
+    signerKind?: string;
+    payment?: Record<string, any>;
+}): string;
+export declare function checkTime(p: Record<string, any>, now: number, maxS: number): void;
+export declare function verifyConsent(token: string, o: {
+    keys: KeySet;
+    executor: string;
+    sub: string;
+    previews: Record<string, any>[];
+    actions: Record<string, any>[];
+    profiles: Record<string, Record<string, any>>;
+    now: number;
+    nonces: NonceStore;
+    policyFloor?: string;
+    tainted?: boolean;
+}): Record<string, any>;

package/dist/consent.js

@@ -0,0 +1,95 @@
+// Consent (spec section 6): the person's signed yes to one or more Previews. Checks run in the spec's order; the
+// first failure is the one reported. Mirrors consent.py.
+import * as crypto from "node:crypto";
+import * as shapes from "./shapes.js";
+import { OACError } from "./errors.js";
+import { digest, KeySet, sign, verify } from "./jws.js";
+import { actionDigest, checkBinding } from "./preview.js";
+import { tierFor } from "./tiers.js";
+export const TYP = "oac-consent+jws";
+export const MAX_S = 900;
+export const SKEW_S = 60;
+export class MemoryNonces {
+    s = new Map();
+    constructor(seen = []) { for (const j of seen)
+        this.s.set(j, 0); }
+    useOnce(jti, exp) {
+        if (this.s.has(jti))
+            return false;
+        this.s.set(jti, exp);
+        return true;
+    }
+}
+export const newNonce = () => crypto.randomBytes(18).toString("base64url");
+export function makeConsent(o) {
+    const payload = {
+        oac: shapes.VERSION, type: "consent", iss: o.iss, sub: o.sub, aud: o.aud, jti: o.jti ?? newNonce(), iat: o.now,
+        exp: o.now + (o.ttl ?? 300), items: o.previews.map((p) => ({ preview: digest(p), action: p.action })),
+        signer: { kind: o.signerKind ?? "custodial" },
+    };
+    if (o.payment)
+        payload.payment = { ...o.payment };
+    return sign(shapes.consent(payload), o.key, TYP);
+}
+export function checkTime(p, now, maxS) {
+    if (p.iat > now + SKEW_S)
+        throw new OACError("not_yet_valid");
+    if (now >= p.exp)
+        throw new OACError("expired");
+    if (p.exp - p.iat > maxS || p.exp <= p.iat)
+        throw new OACError("lifetime_too_long");
+}
+function payment(p, preview) {
+    const pay = p.payment;
+    if (pay === undefined)
+        throw new OACError("payment_missing", "a pay action needs consent.payment");
+    for (const name of ["amount_minor", "currency", "payee"]) {
+        if (preview.fields[name] !== pay[name])
+            throw new OACError("payment_mismatch", `payment ${name} differs from the preview`);
+    }
+}
+export function verifyConsent(token, o) {
+    const p = verify(token, o.keys, TYP);
+    shapes.consent(p);
+    if (p.aud !== o.executor)
+        throw new OACError("wrong_audience");
+    if (p.sub !== o.sub)
+        throw new OACError("subject_mismatch", "the consent is another person's");
+    checkTime(p, o.now, MAX_S);
+    if (p.items.length !== o.previews.length || o.previews.length !== o.actions.length) {
+        throw new OACError("preview_mismatch", "one preview and one action per item");
+    }
+    let pays = 0;
+    p.items.forEach((item, i) => {
+        const preview = o.previews[i], action = o.actions[i];
+        shapes.preview(preview);
+        if (digest(preview) !== item.preview)
+            throw new OACError("preview_mismatch");
+        if (preview.action !== item.action || actionDigest(action) !== item.action)
+            throw new OACError("action_mismatch");
+        if (preview.sub !== p.sub)
+            throw new OACError("subject_mismatch");
+        if (preview.executor !== o.executor)
+            throw new OACError("executor_mismatch");
+        if (o.now >= preview.exp)
+            throw new OACError("preview_expired");
+        const profile = Object.hasOwn(o.profiles, action.tool) ? o.profiles[action.tool] : undefined;
+        if (profile === undefined)
+            throw new OACError("unknown_tool");
+        shapes.profile(profile);
+        checkBinding(preview, action, profile);
+        if (tierFor(profile, { policyFloor: o.policyFloor, tainted: o.tainted }) === "D")
+            throw new OACError("tier_d");
+        if (profile.effect === "pay") {
+            pays += 1;
+            if (pays > 1)
+                throw new OACError("malformed", "one payment per consent");
+            payment(p, preview);
+        }
+    });
+    if (pays === 0 && Object.hasOwn(p, "payment"))
+        throw new OACError("payment_mismatch", "payment given but no item pays");
+    if (!o.nonces.useOnce(p.jti, p.exp))
+        throw new OACError("replay");
+    return p;
+}

package/dist/discovery.d.ts

@@ -0,0 +1,5 @@
+import { KeySet } from "./jws.ts";
+export declare const MAX_DOC: number;
+export declare function metadataUrl(iss: string): string;
+export declare function keysetFrom(docs: [string, Record<string, any>][]): KeySet;
+export declare function fetchMetadata(iss: string, get?: (url: string) => Promise<Uint8Array>): Promise<Record<string, any>>;

package/dist/discovery.js

@@ -0,0 +1,44 @@
+// Issuer metadata (spec section 3.5): for issuer https://host/path the document is at
+// https://host/.well-known/oac-issuer/path (the RFC 8414 pattern) and its `issuer` must equal the issuer exactly.
+// `keysetFrom` turns documents you already have into a KeySet; `fetchMetadata` is a small, strict HTTPS fetcher.
+import * as shapes from "./shapes.js";
+import { OACError } from "./errors.js";
+import { parse } from "./jcs.js";
+import { KeySet } from "./jws.js";
+export const MAX_DOC = 64 * 1024;
+// Matched as text, same pattern as discovery.py, so every language agrees (no URL parser normalizing ports or IDNs).
+const LABEL = "[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?";
+const ISSUER = new RegExp(`^https://(${LABEL}(\\.${LABEL})*)(:[0-9]{1,5})?((/(?!\\.\\.?(/|$))[A-Za-z0-9._~-]+)*)/?$`);
+export function metadataUrl(iss) {
+    const m = typeof iss === "string" ? ISSUER.exec(iss) : null;
+    if (m === null)
+        throw new OACError("malformed", "an issuer is https://host[:port][/path] in lowercase ASCII, without query or fragment");
+    return `https://${m[1]}${m[5] ?? ""}/.well-known/oac-issuer${m[6]}`;
+}
+export function keysetFrom(docs) {
+    const grouped = {};
+    for (const [iss, doc] of docs) {
+        metadataUrl(iss);
+        shapes.issuerMetadata(doc);
+        if (doc.issuer !== iss)
+            throw new OACError("wrong_issuer", "the metadata names another issuer");
+        (grouped[iss] ??= []).push(...doc.keys);
+    }
+    return new KeySet(grouped);
+}
+export async function fetchMetadata(iss, get) {
+    const fetcher = get ?? (async (url) => {
+        const r = await fetch(url, { redirect: "error", headers: { accept: "application/json" }, signal: AbortSignal.timeout(5000) });
+        if (!r.ok)
+            throw new OACError("malformed", `issuer metadata: HTTP ${r.status}`);
+        const body = new Uint8Array(await r.arrayBuffer());
+        if (body.length > MAX_DOC)
+            throw new OACError("malformed", "issuer metadata too large");
+        return body;
+    });
+    const doc = parse(await fetcher(metadataUrl(iss)));
+    shapes.issuerMetadata(doc);
+    if (doc.issuer !== iss)
+        throw new OACError("wrong_issuer", "the metadata names another issuer");
+    return doc;
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export declare const CODES: Set<string>;
+/** A refusal. `code` is one of CODES; `detail` is for logs, never for deciding anything. */
+export declare class OACError extends Error {
+    readonly code: string;
+    readonly detail: string;
+    constructor(code: string, detail?: string);
+}

package/dist/errors.js

@@ -0,0 +1,28 @@
+// Error codes shared by every OAC implementation (spec section 9). A verifier reports exactly one code: the first
+// check that fails, in the order the spec lists them.
+export const CODES = new Set([
+    "malformed", "not_canonical", "bad_type", "bad_alg", "unknown_key", "bad_signature",
+    "wrong_audience", "not_yet_valid", "expired", "lifetime_too_long", "replay",
+    "preview_mismatch", "action_mismatch", "binding_mismatch", "subject_mismatch", "executor_mismatch",
+    "preview_expired", "unknown_tool", "tier_d", "payment_missing", "payment_mismatch",
+    "holder_mismatch", "tool_not_covered", "tainted", "pay_without_caps", "recipient_not_allowed",
+    "payee_not_allowed", "site_not_allowed", "currency_mismatch", "over_amount", "over_daily_amount", "over_calls",
+    "chain_broken", "chain_seq", "chain_issuer", "receipt_invalid", "receipt_mismatch", "not_reversible",
+    "undo_mode_mismatch", "undo_window_closed",
+    // added after the 2026-11-04 review
+    "wrong_issuer", "undeclared_argument", "revoked", "already_undone", "compensation_mismatch",
+    // 0.1 gap closers: status lists and seals
+    "status_unknown", "seal_mismatch",
+]);
+/** A refusal. `code` is one of CODES; `detail` is for logs, never for deciding anything. */
+export class OACError extends Error {
+    code;
+    detail;
+    constructor(code, detail = "") {
+        if (!CODES.has(code))
+            throw new Error(`unknown OAC error code ${code}`);
+        super(detail ? `${code}: ${detail}` : code);
+        this.code = code;
+        this.detail = detail;
+    }
+}

package/dist/gate.d.ts

@@ -0,0 +1,48 @@
+import { KeySet, type SigningKey } from "./jws.ts";
+import { type NonceStore } from "./consent.ts";
+export declare class NeedsConsent extends Error {
+    readonly preview: Record<string, any>;
+    constructor(preview: Record<string, any>);
+}
+export type ProfileSpec = {
+    effect: string;
+    undo?: string;
+    windowS?: number;
+    tierFloor?: string;
+    binds?: Record<string, string>;
+    otherArgs?: string[];
+};
+export declare class Gate {
+    readonly executor: string;
+    readonly key: SigningKey;
+    readonly signers: KeySet;
+    readonly nonces: NonceStore;
+    readonly policyFloor: string;
+    readonly profiles: Record<string, Record<string, any>>;
+    readonly pending: Map<string, Record<string, any>>;
+    readonly consents: Map<string, string>;
+    readonly receipts: Map<string, string[]>;
+    private readonly clock;
+    private readonly summarize;
+    constructor(o: {
+        executor: string;
+        key: SigningKey;
+        signers: KeySet;
+        nonces?: NonceStore;
+        policyFloor?: string;
+        summarize?: (a: Record<string, any>) => string;
+        clock?: () => number;
+    });
+    profile(tool: string, p: ProfileSpec): Record<string, any>;
+    private prof;
+    tier(tool: string, args: Record<string, unknown>, tainted?: boolean): string;
+    preview(tool: string, args: Record<string, unknown>, person: string, evidence?: Record<string, any>): Record<string, any>;
+    previewById(id: string): Record<string, any> | undefined;
+    acceptConsent(token: string): boolean;
+    private authorize;
+    run<T>(tool: string, args: Record<string, unknown>, fn: (args: Record<string, unknown>) => T | Promise<T>, o: {
+        person: string;
+        tainted?: boolean;
+    }): Promise<[T, string]>;
+    private receipt;
+}