open-action-consent 0.2.1 → 0.3.0

package/dist/conformance.js

@@ -1,5 +1,4 @@
-// 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.
+// Run the shared vectors: node src/conformance.ts vectors
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { OACError } from "./errors.js";
@@ -15,6 +14,7 @@ import { checkUndo } from "./undo.js";
 import { vectorKey } from "./testing.js";
 import { bit, decode } from "./status.js";
 import { keysetFrom, metadataUrl } from "./discovery.js";
+import { claim, MemoryOccurrences } from "./occurrence.js";
 const OK = { ok: true };
 const OPS = {
     jcs: (i) => ({ canonical: canonical(i.value) }),
@@ -27,6 +27,7 @@ const OPS = {
     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,
+        device: i.device,
     }), 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,
@@ -39,6 +40,11 @@ const OPS = {
         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),
+    claim_occurrence: (i) => {
+        const key = ["person", "tool", "occurrence"];
+        claim(new MemoryOccurrences(i.state ? [[key, i.state]] : []), key);
+        return 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) }),

package/dist/consent.d.ts

@@ -1,4 +1,5 @@
 import { KeySet, type SigningKey } from "./jws.ts";
+import { type DeviceCheck } from "./webauthn.ts";
 export declare const TYP = "oac-consent+jws";
 export declare const MAX_S = 900;
 export declare const SKEW_S = 60;
@@ -36,4 +37,5 @@ export declare function verifyConsent(token: string, o: {
     nonces: NonceStore;
     policyFloor?: string;
     tainted?: boolean;
+    device?: DeviceCheck;
 }): Record<string, any>;

package/dist/consent.js

@@ -1,11 +1,11 @@
-// 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.
+// Consents (spec 6): the person's signed yes to one or more Previews.
 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";
+import { verifyDeviceProof } from "./webauthn.js";
 export const TYP = "oac-consent+jws";
 export const MAX_S = 900;
 export const SKEW_S = 60;
@@ -89,6 +89,8 @@ export function verifyConsent(token, o) {
     });
     if (pays === 0 && Object.hasOwn(p, "payment"))
         throw new OACError("payment_mismatch", "payment given but no item pays");
+    if (o.device)
+        verifyDeviceProof(token, o.device);
     if (!o.nonces.useOnce(p.jti, p.exp))
         throw new OACError("replay");
     return p;

package/dist/discovery.js

@@ -1,12 +1,10 @@
-// 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.
+// Issuer metadata (spec 3.5): where an issuer publishes its public keys.
 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).
+// matched as text, not with a URL parser, so every language agrees
 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) {

package/dist/errors.js

@@ -1,5 +1,4 @@
-// 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.
+// Error codes shared by every OAC implementation.
 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",
@@ -9,10 +8,15 @@ export const CODES = new Set([
     "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
+    // identity, arguments, revocation, undo
     "wrong_issuer", "undeclared_argument", "revoked", "already_undone", "compensation_mismatch",
-    // 0.1 gap closers: status lists and seals
+    // status lists and seals
     "status_unknown", "seal_mismatch",
+    // device proofs (WebAuthn)
+    "device_proof_missing", "device_proof_mismatch", "unknown_credential", "challenge_mismatch", "wrong_origin",
+    "rp_mismatch", "user_not_present", "user_not_verified",
+    // business occurrences
+    "occurrence_unresolved", "duplicate_occurrence",
 ]);
 /** A refusal. `code` is one of CODES; `detail` is for logs, never for deciding anything. */
 export class OACError extends Error {

package/dist/gate.d.ts

@@ -1,9 +1,13 @@
 import { KeySet, type SigningKey } from "./jws.ts";
 import { type NonceStore } from "./consent.ts";
+import { type OccurrenceStore } from "./occurrence.ts";
 export declare class NeedsConsent extends Error {
     readonly preview: Record<string, any>;
     constructor(preview: Record<string, any>);
 }
+/** Throw from a tool when the action surely did not happen. Other errors count as unknown. */
+export declare class ActionFailed extends Error {
+}
 export type ProfileSpec = {
     effect: string;
     undo?: string;
@@ -11,17 +15,20 @@ export type ProfileSpec = {
     tierFloor?: string;
     binds?: Record<string, string>;
     otherArgs?: string[];
+    occurrence?: string;
 };
 export declare class Gate {
     readonly executor: string;
     readonly key: SigningKey;
     readonly signers: KeySet;
     readonly nonces: NonceStore;
+    readonly occurrences: OccurrenceStore;
     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[]>;
+    readonly tokens: Map<string, string>;
     private readonly clock;
     private readonly summarize;
     constructor(o: {
@@ -29,6 +36,7 @@ export declare class Gate {
         key: SigningKey;
         signers: KeySet;
         nonces?: NonceStore;
+        occurrences?: OccurrenceStore;
         policyFloor?: string;
         summarize?: (a: Record<string, any>) => string;
         clock?: () => number;
@@ -40,9 +48,15 @@ export declare class Gate {
     previewById(id: string): Record<string, any> | undefined;
     acceptConsent(token: string): boolean;
     private authorize;
+    private outcome;
     run<T>(tool: string, args: Record<string, unknown>, fn: (args: Record<string, unknown>) => T | Promise<T>, o: {
         person: string;
         tainted?: boolean;
     }): Promise<[T, string]>;
+    /** Record what the provider says happened to an unknown attempt: ok or failed. */
+    resolve(tool: string, occurrence: string, o: {
+        person: string;
+        outcome: "ok" | "failed";
+    }): void;
     private receipt;
 }

package/dist/gate.js

@@ -1,11 +1,10 @@
-// A framework-neutral executor gate (twin of gate.py): tier, Preview, Consent hand-over, verification right before
-// the action, run, signed Receipt. A pending Preview is reused for the same person and action until it expires, so
-// a framework that re-runs a step after an interruption gets the Preview the person approved.
+// Executor gate shared by the framework adapters. Same behaviour as gate.py.
 import * as crypto from "node:crypto";
 import * as shapes from "./shapes.js";
 import { OACError } from "./errors.js";
 import { digest, KeySet, tokenDigest, verify } from "./jws.js";
 import { MemoryNonces, verifyConsent } from "./consent.js";
+import { checkOpen, claim, MemoryOccurrences, occurrenceKey, resolve } from "./occurrence.js";
 import { actionDigest, buildPreview } from "./preview.js";
 import { makeReceipt } from "./receipts.js";
 import { tierFor } from "./tiers.js";
@@ -13,16 +12,21 @@ export class NeedsConsent extends Error {
     preview;
     constructor(preview) { super("the person must approve this preview"); this.preview = preview; }
 }
+/** Throw from a tool when the action surely did not happen. Other errors count as unknown. */
+export class ActionFailed extends Error {
+}
 export class Gate {
     executor;
     key;
     signers;
     nonces;
+    occurrences;
     policyFloor;
     profiles = {};
     pending = new Map(); // person \0 action digest -> preview
     consents = new Map();
     receipts = new Map();
+    tokens = new Map(); // authority digest in a receipt -> the exact token
     clock;
     summarize;
     constructor(o) {
@@ -30,6 +34,7 @@ export class Gate {
         this.key = o.key;
         this.signers = o.signers;
         this.nonces = o.nonces ?? new MemoryNonces();
+        this.occurrences = o.occurrences ?? new MemoryOccurrences();
         this.policyFloor = o.policyFloor ?? "A";
         this.clock = o.clock ?? (() => Math.floor(Date.now() / 1000));
         this.summarize = o.summarize ?? ((a) => `${a.tool}: ` + Object.keys(a.args).sort().map((k) => `${k}=${JSON.stringify(a.args[k])}`).join(", ").slice(0, 480));
@@ -39,6 +44,8 @@ export class Gate {
             tier_floor: p.tierFloor ?? "A", binds: { ...(p.binds ?? {}) } };
         if (p.otherArgs?.length)
             doc.other_args = [...p.otherArgs];
+        if (p.occurrence)
+            doc.occurrence = p.occurrence;
         this.profiles[tool] = shapes.profile(doc);
         return doc;
     }
@@ -89,38 +96,61 @@ export class Gate {
         const tier = this.tier(tool, args, tainted);
         if (tier === "D")
             throw new OACError("tier_d", "this action never runs");
+        const occurrence = occurrenceKey(person, this.profiles[tool], args);
         if (tier === "A" || tier === "B")
-            return [tier, { kind: "tier" }, null];
+            return [tier, { kind: "tier" }, null, claim(this.occurrences, occurrence)];
         const action = { tool, args: { ...args } };
         const preview = this.preview(tool, args, person);
         const pd = digest(preview);
         const token = this.consents.get(pd);
-        if (!token)
+        if (!token) {
+            checkOpen(this.occurrences, occurrence);
             throw new NeedsConsent(preview);
-        const c = verifyConsent(token, { keys: this.signers, executor: this.executor, sub: person, previews: [preview], actions: [action],
-            profiles: this.profiles, now: this.clock(), nonces: this.nonces, policyFloor: this.policyFloor, tainted });
+        }
+        const claimed = claim(this.occurrences, occurrence);
+        let c;
+        try {
+            c = verifyConsent(token, { keys: this.signers, executor: this.executor, sub: person, previews: [preview], actions: [action],
+                profiles: this.profiles, now: this.clock(), nonces: this.nonces, policyFloor: this.policyFloor, tainted });
+        }
+        catch (e) {
+            if (claimed)
+                this.occurrences.release(claimed);
+            throw e;
+        }
         this.pending.delete(person + "\0" + actionDigest(action));
-        return ["C", { kind: "consent", ref: c.jti }, pd];
+        this.tokens.set(tokenDigest(token), token);
+        return ["C", { kind: "consent", ref: c.jti, digest: tokenDigest(token) }, pd, claimed];
+    }
+    outcome(claimed, error) {
+        const outcome = error === undefined ? "ok" : claimed === null || error instanceof ActionFailed ? "failed" : "unknown";
+        if (claimed)
+            this.occurrences.finish(claimed, outcome);
+        return outcome;
     }
     async run(tool, args, fn, o) {
-        const [tier, authority, pd] = this.authorize(tool, args, o.person, o.tainted ?? true);
+        const [tier, authority, pd, claimed] = this.authorize(tool, args, o.person, o.tainted ?? true);
         let result;
         try {
             result = await fn(args);
         }
         catch (e) {
-            this.receipt(o.person, tool, args, tier, authority, pd, null, true);
+            this.receipt(o.person, tool, args, tier, authority, pd, null, this.outcome(claimed, e ?? new Error("thrown")));
             throw e;
         }
-        return [result, this.receipt(o.person, tool, args, tier, authority, pd, result, false)];
+        return [result, this.receipt(o.person, tool, args, tier, authority, pd, result, this.outcome(claimed, undefined))];
+    }
+    /** Record what the provider says happened to an unknown attempt: ok or failed. */
+    resolve(tool, occurrence, o) {
+        resolve(this.occurrences, [o.person, tool, occurrence], o.outcome);
     }
-    receipt(person, tool, args, tier, authority, pd, result, failed) {
+    receipt(person, tool, args, tier, authority, pd, result, outcome) {
         const profile = this.profiles[tool];
         const chain = this.receipts.get(person) ?? [];
         this.receipts.set(person, chain);
         const now = this.clock();
         const undo = { kind: profile.undo.kind };
-        if (undo.kind !== "none" && !failed) {
+        if (undo.kind !== "none" && outcome === "ok") {
             undo.until = now + profile.undo.window_s;
             if (undo.kind === "native")
                 undo.token = "u_" + crypto.randomBytes(12).toString("base64url");
@@ -133,9 +163,11 @@ export class Gate {
             rd = digest(String(result));
         }
         const payload = { iss: this.executor, sub: person, seq: chain.length + 1, prev: chain.length ? tokenDigest(chain[chain.length - 1]) : null,
-            iat: now, tool, tier, authority, action: actionDigest({ tool, args: { ...args } }), outcome: failed ? "failed" : "ok", result: rd, undo };
+            iat: now, tool, tier, authority, action: actionDigest({ tool, args: { ...args } }), outcome, result: rd, undo };
         if (pd)
             payload.preview = pd;
+        if (Object.hasOwn(profile, "occurrence"))
+            payload.occurrence = args[profile.occurrence];
         const r = makeReceipt(this.key, payload);
         chain.push(r);
         return r;

package/dist/index.d.ts

@@ -8,5 +8,7 @@ export { makeConsent, MemoryNonces, verifyConsent, type NonceStore } from "./con
 export { checkMandate, loosens, makeMandate } from "./mandate.ts";
 export { makeReceipt, verifyChain } from "./receipts.ts";
 export { checkUndo, makeUndo } from "./undo.ts";
-export { Gate, NeedsConsent, type ProfileSpec } from "./gate.ts";
-export declare const VERSION = "0.2.1";
+export { ActionFailed, Gate, NeedsConsent, type ProfileSpec } from "./gate.ts";
+export { MemoryOccurrences, type OccurrenceStore } from "./occurrence.ts";
+export { verifyDeviceProof, type DeviceCheck } from "./webauthn.ts";
+export declare const VERSION = "0.3.0";

package/dist/index.js

@@ -1,4 +1,4 @@
-// OAC (Open Action Consent) v0.1 reference SDK for TypeScript. Spec: spec/oac-v0.1.md.
+// Open Action Consent for TypeScript. Spec: spec/oac-v0.1.md
 export { CODES, OACError } from "./errors.js";
 export { canonical, parse } from "./jcs.js";
 export { digest, generate, KeySet, sign, tokenDigest, verify } from "./jws.js";
@@ -9,5 +9,7 @@ export { makeConsent, MemoryNonces, verifyConsent } from "./consent.js";
 export { checkMandate, loosens, makeMandate } from "./mandate.js";
 export { makeReceipt, verifyChain } from "./receipts.js";
 export { checkUndo, makeUndo } from "./undo.js";
-export { Gate, NeedsConsent } from "./gate.js";
-export const VERSION = "0.2.1";
+export { ActionFailed, Gate, NeedsConsent } from "./gate.js";
+export { MemoryOccurrences } from "./occurrence.js";
+export { verifyDeviceProof } from "./webauthn.js";
+export const VERSION = "0.3.0";

package/dist/jcs.js

@@ -1,6 +1,4 @@
-// RFC 8785 (JCS) canonical JSON for the OAC subset, plus a strict parser. OAC carries integers only (money in minor
-// units, time in unix seconds), so JCS reduces to: keys sorted by UTF-16 code units (JavaScript's default sort),
-// no whitespace, strings as JSON.stringify writes them, integers in plain decimal within +-(2^53 - 1).
+// RFC 8785 canonical JSON for OAC's integer-only subset, and a strict parser.
 import { OACError } from "./errors.js";
 export const MAX_DEPTH = 64; // arrays and objects nested deeper than this are refused
 function str(s) {

package/dist/jws.d.ts

@@ -23,7 +23,7 @@ export declare function thumbprint(jwk: Jwk): string;
 export declare function ed25519FromSeed(seed: Uint8Array): SigningKey;
 export declare function p256FromSeed(seed: Uint8Array): SigningKey;
 export declare function generate(alg?: string): SigningKey;
-/** Public keys a verifier trusts, grouped by issuer: {iss: [jwk, ...]}. A kid maps to one key and one issuer. */
+/** Trusted public keys, grouped by issuer: {iss: [jwk, ...]}. Each key has one issuer. */
 export declare class KeySet {
     private keys;
     constructor(byIssuer: Record<string, Jwk[]>);

package/dist/jws.js

@@ -1,7 +1,4 @@
-// Keys, digests and the JWS envelope (RFC 7515 compact). Header = exactly {alg, kid, typ}, JCS-canonical; payload =
-// JCS-canonical JSON; a token whose bytes are not the canonical form of what they parse to is refused.
-// Algorithms: EdDSA (Ed25519, RFC 8037) and ES256 (P-256, raw r||s, low-S only). kid = the RFC 7638 JWK thumbprint.
-// Every trusted key belongs to exactly one issuer, and a token's `iss` must be its key's issuer.
+// Keys, digests and the compact JWS envelope used by every signed OAC object.
 import * as crypto from "node:crypto";
 import { OACError } from "./errors.js";
 import { canonical, canonicalBytes, parse } from "./jcs.js";
@@ -66,7 +63,7 @@ export function generate(alg = "EdDSA") {
     }
     throw new OACError("bad_alg", alg);
 }
-/** Public keys a verifier trusts, grouped by issuer: {iss: [jwk, ...]}. A kid maps to one key and one issuer. */
+/** Trusted public keys, grouped by issuer: {iss: [jwk, ...]}. Each key has one issuer. */
 export class KeySet {
     keys = new Map();
     constructor(byIssuer) {

package/dist/mandate.d.ts

@@ -20,5 +20,5 @@ export declare function checkMandate(token: string, o: {
     statusLists?: Record<string, string>;
     policyFloor?: string;
 }): Record<string, any>;
-/** What a replacement mandate allows that the old one did not; non-empty = the signer needs fresh proof (spec 7.4). */
+/** What the new mandate allows that the old one did not (spec 7.4). */
 export declare function loosens(old: Record<string, any>, nw: Record<string, any>): string[];

package/dist/mandate.js

@@ -1,5 +1,4 @@
-// Mandates (spec section 7): standing, bounded, expiring permission. Covers tier C only; never tier D; never waives
-// the taint floor; a pay tool needs caps and a payee list. Mirrors mandate.py, check for check.
+// Mandates (spec 7): standing, bounded permission that can replace a Consent on tier C.
 import * as shapes from "./shapes.js";
 import { OACError } from "./errors.js";
 import { canonical } from "./jcs.js";
@@ -77,7 +76,7 @@ export function checkMandate(token, o) {
         throw new OACError("over_calls");
     return p;
 }
-/** What a replacement mandate allows that the old one did not; non-empty = the signer needs fresh proof (spec 7.4). */
+/** What the new mandate allows that the old one did not (spec 7.4). */
 export function loosens(old, nw) {
     shapes.mandate(old);
     shapes.mandate(nw);
@@ -117,8 +116,7 @@ export function loosens(old, nw) {
             }
         }
     }
-    // recipients: no list means nobody, so any list where there was none, or a new entry, loosens.
-    // payees and sites: no list means no limit, so dropping the list, or a new entry, loosens.
+    // no recipient list means nobody; no payee or site list means anyone
     if (nb.recipients !== undefined && (ob.recipients === undefined || newOnes(nb.recipients, ob.recipients)))
         out.push("recipients");
     for (const key of ["payees", "sites"]) {

package/dist/mcp/index.d.ts

@@ -1,7 +1,9 @@
 import { type McpServer } from "@modelcontextprotocol/server";
 import { KeySet, MemoryNonces, type SigningKey } from "../index.ts";
+import { type OccurrenceStore } from "../occurrence.ts";
 export declare const ID = "com.atlasiw/oac";
 export declare const PROFILE_KEY = "com.atlasiw/oac-profile", PREVIEW_KEY = "com.atlasiw/oac-preview", RECEIPT_KEY = "com.atlasiw/oac-receipt", CONSENT_KEY = "com.atlasiw/oac-consent";
+export declare const OUTCOME_KEY = "com.atlasiw/oac-outcome";
 type Ctx = any;
 type Result = {
     content: {
@@ -17,11 +19,12 @@ export interface OACOptions {
     signers: KeySet;
     consentUrl: (preview: Record<string, any>) => string;
     person: (ctx: Ctx) => string;
-    /** From the host runtime, never the model; default: tainted (spec section 4). */
+    /** From the host, never the model. Defaults to tainted. */
     tainted?: (ctx: Ctx) => boolean;
     summarize?: (action: Record<string, any>) => string;
     policyFloor?: string;
     clock?: () => number;
+    occurrences?: OccurrenceStore;
 }
 export declare class OAC {
     readonly profiles: Record<string, Record<string, any>>;
@@ -29,6 +32,8 @@ export declare class OAC {
     readonly consents: Map<string, string>;
     readonly nonces: MemoryNonces;
     readonly receipts: Map<string, string[]>;
+    readonly tokens: Map<string, string>;
+    readonly occurrences: OccurrenceStore;
     private readonly stateKey;
     readonly o: OACOptions;
     constructor(o: OACOptions);
@@ -42,15 +47,23 @@ export declare class OAC {
         tierFloor?: string;
         binds?: Record<string, string>;
         otherArgs?: string[];
+        occurrence?: string;
     }): Record<string, unknown>;
     /** Register a tool on an McpServer with its OAC profile; every call goes through `guard`. */
     registerTool(server: McpServer, name: string, config: Record<string, any>, profile: Parameters<OAC["profile"]>[1], handler: (args: any, ctx: Ctx) => Promise<Result>): void;
     preview(id: string): Record<string, any> | undefined;
-    /** The signer page hands over a Consent: kept only if valid for this executor over a pending preview, never replaced. */
+    /** Keep a valid Consent for a pending preview. Never replaces one already kept. */
     acceptConsent(token: string): boolean;
     private seal;
     private unseal;
     guard(name: string, args: Record<string, unknown>, ctx: Ctx, handler: (args: any, ctx: Ctx) => Promise<Result>, clientCaps?: Record<string, any> | undefined): Promise<any>;
+    private run;
+    private finish;
+    /** Record what the provider says happened to an unknown attempt: ok or failed. */
+    resolve(tool: string, occurrence: string, o: {
+        person: string;
+        outcome: "ok" | "failed";
+    }): void;
     private ask;
     private withReceipt;
 }

package/dist/mcp/index.js

@@ -1,13 +1,11 @@
-// OAC for the official MCP TypeScript SDK v2 (@modelcontextprotocol/server 2.4+): import from "open-action-consent/mcp". The SDK has no tool-call
-// interceptor, so OAC wraps each tool: `oac.registerTool(server, name, config, profile, handler)`.
-// Tier A/B run (B with a receipt and undo token); tier C answers input_required with a URL-mode elicitation and
-// runs only with a valid signed Consent; tier D, unprofiled tools and undeclared arguments never run. Unlike the
-// Python SDK, v2 does not integrity-protect requestState, so OAC signs its own (HMAC-SHA256, short expiry).
+// OAC for the MCP TypeScript SDK v2. The SDK has no interceptor, so this wraps each tool. See guides/mcp-typescript.md.
 import * as crypto from "node:crypto";
 import { inputRequired, inputResponse } from "@modelcontextprotocol/server";
 import { actionDigest, buildPreview, digest, KeySet, makeReceipt, MemoryNonces, OACError, shapes, tierFor, tokenDigest, verify, verifyConsent } from "../index.js";
+import { checkOpen, claim, MemoryOccurrences, occurrenceKey, resolve } from "../occurrence.js";
 export const ID = "com.atlasiw/oac";
 export const PROFILE_KEY = `${ID}-profile`, PREVIEW_KEY = `${ID}-preview`, RECEIPT_KEY = `${ID}-receipt`, CONSENT_KEY = `${ID}-consent`;
+export const OUTCOME_KEY = `${ID}-outcome`;
 const ASK = "oac_consent";
 const STATE_TTL_S = 900;
 const refused = (text) => ({ content: [{ type: "text", text }], isError: true });
@@ -17,9 +15,11 @@ export class OAC {
     consents = new Map();
     nonces = new MemoryNonces();
     receipts = new Map();
+    tokens = new Map(); // authority digest in a receipt -> the exact token
+    occurrences;
     stateKey = crypto.randomBytes(32);
     o;
-    constructor(o) { this.o = o; }
+    constructor(o) { this.o = o; this.occurrences = o.occurrences ?? new MemoryOccurrences(); }
     now() { return (this.o.clock ?? (() => Math.floor(Date.now() / 1000)))(); }
     /** Capability settings to put under `capabilities.extensions[ID]`. */
     settings() { return { version: "0.1", executor: this.o.executor }; }
@@ -28,6 +28,8 @@ export class OAC {
             tier_floor: p.tierFloor ?? "A", binds: { ...(p.binds ?? {}) } };
         if (p.otherArgs?.length)
             doc.other_args = [...p.otherArgs];
+        if (p.occurrence)
+            doc.occurrence = p.occurrence;
         this.profiles[tool] = shapes.profile(doc);
         return { [PROFILE_KEY]: doc };
     }
@@ -38,7 +40,7 @@ export class OAC {
         server.registerTool(name, { ...config, _meta: { ...(config._meta ?? {}), ...meta } }, (args, ctx) => this.guard(name, args ?? {}, ctx, handler, caps(ctx)));
     }
     preview(id) { return [...this.previews.values()].find((p) => p.id === id); }
-    /** The signer page hands over a Consent: kept only if valid for this executor over a pending preview, never replaced. */
+    /** Keep a valid Consent for a pending preview. Never replaces one already kept. */
     acceptConsent(token) {
         let p;
         try {
@@ -89,16 +91,23 @@ export class OAC {
         }
         if (tier === "D")
             return refused("Refused: this action is never allowed (tier D).");
-        if (tier === "A" || tier === "B")
-            return this.withReceipt(await handler(args, ctx), person, profile, action, tier, { kind: "tier" }, null);
+        if (tier === "A" || tier === "B") {
+            let claimed;
+            try {
+                claimed = claim(this.occurrences, occurrenceKey(person, profile, args));
+            }
+            catch (e) {
+                return refused(`Refused (${e instanceof OACError ? e.code : "error"}). Nothing ran.`);
+            }
+            return this.run(handler, args, ctx, person, profile, action, tier, { kind: "tier" }, null, claimed);
+        }
         const missing = {};
         if (!clientCaps?.extensions?.[ID])
             missing.extensions = { [ID]: {} };
         if (!clientCaps?.elicitation?.url)
             missing.elicitation = { url: {} };
         if (Object.keys(missing).length) {
-            // spec mcp-extension 6: never run without a consent page. The v2 SDK turns errors thrown in a tool into tool
-            // results, so the -32021 data travels in the refusal instead of as a protocol error.
+            // the v2 SDK turns thrown errors into tool results, so -32021 travels in the refusal
             return { ...refused("Refused (-32021): this client cannot show an approval page (needs the OAC extension and URL elicitation). Nothing ran."),
                 _meta: { [`${ID}-missing`]: missing } };
         }
@@ -115,16 +124,52 @@ export class OAC {
         if (!preview || !token)
             return this.ask(action, profile, person);
         let consent;
+        let claimed = null;
         try {
+            claimed = claim(this.occurrences, occurrenceKey(person, profile, args));
             consent = verifyConsent(token, { keys: this.o.signers, executor: this.o.executor, sub: person, previews: [preview], actions: [action],
                 profiles: this.profiles, now: this.now(), nonces: this.nonces, policyFloor: this.o.policyFloor, tainted });
         }
         catch (e) {
+            if (claimed)
+                this.occurrences.release(claimed);
             return refused(`Refused (${e instanceof OACError ? e.code : "error"}). Nothing ran.`);
         }
-        return this.withReceipt(await handler(args, ctx), person, profile, action, "C", { kind: "consent", ref: consent.jti }, digest(preview));
+        this.tokens.set(tokenDigest(token), token);
+        const authority = { kind: "consent", ref: consent.jti, digest: tokenDigest(token) };
+        return this.run(handler, args, ctx, person, profile, action, "C", authority, digest(preview), claimed);
+    }
+    // a timed-out payment may still have gone through, so an error is "unknown" unless the tool says "failed"
+    async run(handler, args, ctx, person, profile, action, tier, authority, previewDigest, claimed) {
+        let result;
+        try {
+            result = await handler(args, ctx);
+        }
+        catch (e) {
+            this.withReceipt(null, person, profile, action, tier, authority, previewDigest, this.finish(claimed, claimed ? "unknown" : "failed"));
+            throw e;
+        }
+        let outcome = "ok";
+        if (result?.isError === true)
+            outcome = claimed && result._meta?.[OUTCOME_KEY] !== "failed" ? "unknown" : "failed";
+        return this.withReceipt(result, person, profile, action, tier, authority, previewDigest, this.finish(claimed, outcome));
+    }
+    finish(claimed, outcome) {
+        if (claimed)
+            this.occurrences.finish(claimed, outcome);
+        return outcome;
+    }
+    /** Record what the provider says happened to an unknown attempt: ok or failed. */
+    resolve(tool, occurrence, o) {
+        resolve(this.occurrences, [o.person, tool, occurrence], o.outcome);
     }
     ask(action, profile, person) {
+        try {
+            checkOpen(this.occurrences, occurrenceKey(person, profile, action.args));
+        }
+        catch (e) {
+            return refused(`Refused (${e instanceof OACError ? e.code : "error"}). Nothing ran.`);
+        }
         const summarize = this.o.summarize ?? ((a) => `${a.tool} with ${JSON.stringify(a.args)}`.slice(0, 500));
         const p = buildPreview({ profile, action, executor: this.o.executor, sub: person, summary: summarize(action), now: this.now() });
         const d = digest(p);
@@ -135,24 +180,27 @@ export class OAC {
         });
         return { ...result, _meta: { ...(result._meta ?? {}), [PREVIEW_KEY]: p } };
     }
-    withReceipt(result, person, profile, action, tier, authority, previewDigest) {
-        const failed = result?.isError === true;
+    withReceipt(result, person, profile, action, tier, authority, previewDigest, outcome) {
         const chain = this.receipts.get(person) ?? [];
         this.receipts.set(person, chain);
         const now = this.now();
         const undo = { kind: profile.undo.kind };
-        if (undo.kind !== "none" && !failed) {
+        if (undo.kind !== "none" && outcome === "ok") {
             undo.until = now + profile.undo.window_s;
             if (undo.kind === "native")
                 undo.token = "u_" + crypto.randomBytes(12).toString("base64url");
         }
         const payload = { iss: this.o.executor, sub: person, seq: chain.length + 1, prev: chain.length ? tokenDigest(chain[chain.length - 1]) : null,
-            iat: now, tool: action.tool, tier, authority, action: actionDigest(action), outcome: failed ? "failed" : "ok", undo,
-            result: digest(JSON.parse(JSON.stringify(result.content ?? []))) };
+            iat: now, tool: action.tool, tier, authority, action: actionDigest(action), outcome, undo,
+            result: digest(JSON.parse(JSON.stringify(result?.content ?? []))) };
         if (previewDigest)
             payload.preview = previewDigest;
+        if (Object.hasOwn(profile, "occurrence"))
+            payload.occurrence = action.args[profile.occurrence];
         const receipt = makeReceipt(this.o.key, payload);
         chain.push(receipt);
+        if (result === null)
+            return null;
         return { ...result, _meta: { ...(result._meta ?? {}), [RECEIPT_KEY]: receipt } };
     }
 }

package/dist/occurrence.d.ts

@@ -0,0 +1,24 @@
+export type OccurrenceKey = [person: string, tool: string, occurrence: string];
+export interface OccurrenceStore {
+    /** Mark the key running and return null, or return its blocking state. Must be atomic. */
+    claim(key: OccurrenceKey): string | null;
+    finish(key: OccurrenceKey, outcome: string): void;
+    /** Drop a claim whose action never started. */
+    release(key: OccurrenceKey): void;
+    state(key: OccurrenceKey): string | null;
+}
+/** For tests and examples. A real store keeps these states in a table with a unique key. */
+export declare class MemoryOccurrences implements OccurrenceStore {
+    private s;
+    constructor(states?: Iterable<[OccurrenceKey, string]>);
+    claim(key: OccurrenceKey): string | null;
+    finish(key: OccurrenceKey, outcome: string): void;
+    release(key: OccurrenceKey): void;
+    state(key: OccurrenceKey): string | null;
+}
+export declare function occurrenceKey(person: string, profile: Record<string, any>, args: Record<string, unknown>): OccurrenceKey | null;
+/** Refuse early, before the person is asked, when the occurrence cannot run now. */
+export declare function checkOpen(store: OccurrenceStore, key: OccurrenceKey | null): void;
+export declare function claim(store: OccurrenceStore, key: OccurrenceKey | null): OccurrenceKey | null;
+/** Record what the provider says happened. A "running" record left by a crash counts as unknown. */
+export declare function resolve(store: OccurrenceStore, key: OccurrenceKey, outcome: string): void;

package/dist/occurrence.js

@@ -0,0 +1,46 @@
+// Business occurrences (spec 5.1): one order or payment runs at most once.
+import { OACError } from "./errors.js";
+/** For tests and examples. A real store keeps these states in a table with a unique key. */
+export class MemoryOccurrences {
+    s = new Map();
+    constructor(states = []) { for (const [k, v] of states)
+        this.s.set(JSON.stringify(k), v); }
+    claim(key) {
+        const now = this.s.get(JSON.stringify(key));
+        if (now === "running" || now === "unknown" || now === "ok")
+            return now;
+        this.s.set(JSON.stringify(key), "running");
+        return null;
+    }
+    finish(key, outcome) { this.s.set(JSON.stringify(key), outcome); }
+    release(key) { this.s.delete(JSON.stringify(key)); }
+    state(key) { return this.s.get(JSON.stringify(key)) ?? null; }
+}
+export function occurrenceKey(person, profile, args) {
+    return Object.hasOwn(profile, "occurrence") ? [person, profile.tool, args[profile.occurrence]] : null;
+}
+function refuse(state) {
+    if (state === "ok")
+        throw new OACError("duplicate_occurrence", "this occurrence already ran");
+    if (state === "running" || state === "unknown")
+        throw new OACError("occurrence_unresolved", "an earlier attempt has no known outcome yet");
+}
+/** Refuse early, before the person is asked, when the occurrence cannot run now. */
+export function checkOpen(store, key) {
+    if (key !== null)
+        refuse(store.state(key));
+}
+export function claim(store, key) {
+    if (key === null)
+        return null;
+    refuse(store.claim(key));
+    return key;
+}
+/** Record what the provider says happened. A "running" record left by a crash counts as unknown. */
+export function resolve(store, key, outcome) {
+    const state = store.state(key);
+    if ((outcome !== "ok" && outcome !== "failed") || (state !== "running" && state !== "unknown")) {
+        throw new Error("only an attempt with no known outcome can be resolved, to ok or failed");
+    }
+    store.finish(key, outcome);
+}

package/dist/preview.js

@@ -1,5 +1,4 @@
-// Actions and Previews (spec sections 3 and 5). Every structured Preview field is bound to one argument by the tool's
-// Action Profile, so what the person reads is provably what will run.
+// Actions and Previews (spec 5 and 6.1).
 import * as crypto from "node:crypto";
 import * as shapes from "./shapes.js";
 import { OACError } from "./errors.js";

package/dist/receipts.js

@@ -1,5 +1,4 @@
-// Receipts (spec section 8): the executor's signed record of each action, chained per person. prev = digest of the
-// previous receipt's whole token, so a dropped, reordered or edited receipt breaks the chain. Mirrors receipts.py.
+// Receipts (spec 8): the executor's signed record of each action, chained per person.
 import * as shapes from "./shapes.js";
 import { OACError } from "./errors.js";
 import { KeySet, sign, tokenDigest, verify } from "./jws.js";
@@ -19,8 +18,11 @@ export function checkSemantics(r) {
     const tier = r.tier, kind = r.authority.kind, undo = r.undo;
     if (tier === "D")
         throw new OACError("receipt_invalid", "a tier D action never runs");
-    if ((kind !== "tier") !== Object.hasOwn(r.authority, "ref"))
-        throw new OACError("receipt_invalid", "consent, mandate and undo authority carry a ref; tier carries none");
+    for (const name of ["ref", "digest"]) {
+        if ((kind !== "tier") !== Object.hasOwn(r.authority, name)) {
+            throw new OACError("receipt_invalid", `consent, mandate and undo authority carry a ${name}; tier carries none`);
+        }
+    }
     if (kind === "tier" && tier !== "A" && tier !== "B")
         throw new OACError("receipt_invalid", "tier C needs a consent, mandate or undo authority");
     if (undo.kind === "none" && ("until" in undo || "token" in undo))
@@ -35,6 +37,7 @@ export function checkSemantics(r) {
 }
 export function verifyChain(tokens, o) {
     const out = [];
+    const done = new Set();
     tokens.forEach((token, i) => {
         const r = verify(token, o.keys, TYP);
         shapes.receipt(r);
@@ -53,6 +56,12 @@ export function verifyChain(tokens, o) {
             if (r.prev !== tokenDigest(tokens[i - 1]))
                 throw new OACError("chain_broken");
         }
+        if (Object.hasOwn(r, "occurrence") && r.outcome === "ok" && r.authority.kind !== "undo") {
+            const key = JSON.stringify([r.tool, r.occurrence]);
+            if (done.has(key))
+                throw new OACError("duplicate_occurrence", "the same occurrence ran twice");
+            done.add(key);
+        }
         out.push(r);
     });
     if (o.seals && o.seals.length) {

package/dist/shapes.d.ts

@@ -8,7 +8,7 @@ export declare function check(v: unknown, fields: Fields, what: string): void;
 export declare const PREVIEW_FIELDS: Record<string, Check>;
 export declare const REQUIRED_BINDS: Record<string, string[]>;
 export declare function profile(v: any): Record<string, any>;
-/** Every argument is declared (bound or other_args); bound values are valid fields; pay/send carry their fields. */
+/** Every argument is declared and every bound value is a valid field. */
 export declare function checkAction(actionDoc: Record<string, any>, prof: Record<string, any>): void;
 export declare function action(v: any): Record<string, any>;
 export declare function preview(v: any): Record<string, any>;
@@ -21,4 +21,5 @@ export declare function receipt(v: any): Record<string, any>;
 /** What a mandate already did, from the executor's own counters (spec 7.3). */
 export declare function usage(v: any): Record<string, number>;
 export declare function undoRequest(v: any): Record<string, any>;
+export declare function deviceProof(v: any): Record<string, any>;
 export {};

package/dist/shapes.js

@@ -1,5 +1,4 @@
-// Field-level checks for every OAC object: the same rules as schemas/*.schema.json plus the cross-field rules a JSON
-// Schema cannot say (marked "rule"). Every failure is `malformed`. Unknown fields are refused. Mirrors shapes.py.
+// Field checks for every OAC object. Same rules as schemas/, plus the cross-field ones.
 import { OACError } from "./errors.js";
 import { canonical } from "./jcs.js";
 export const VERSION = "0.1";
@@ -10,6 +9,7 @@ const RAILS = ["stripe_link", "ap2", "vi", "other"];
 const HOLDERS = ["agent", "client", "run"];
 const SIGNERS = ["custodial", "device"];
 const AUTHORITIES = ["consent", "mandate", "tier", "undo"];
+const OUTCOMES = ["ok", "failed", "unknown"];
 export const PREVIEW_MAX_S = 900;
 const YEAR_S = 366 * 86400;
 const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
@@ -46,15 +46,16 @@ const DIGEST = re(/^sha-256:[A-Za-z0-9_-]{43}$/);
 const NONCE = re(/^[A-Za-z0-9_-]{16,128}$/);
 const CURRENCY = re(/^[A-Z]{3}$/);
 const HOST = re(/^[a-z0-9]([a-z0-9.-]{0,251}[a-z0-9])?$/);
-// one bare ASCII address; a recipient rule is an address or "@domain" (same classes as shapes.py)
+// one bare ASCII address, no display name or list; a recipient rule may also be "@domain"
 const LOCAL = "[A-Za-z0-9!#$%&'*+/=?^_`{|}~.-]{1,64}";
 const DOMAIN = "[A-Za-z0-9]([A-Za-z0-9.-]{0,188}[A-Za-z0-9])?";
 const EMAIL = re(new RegExp(`^${LOCAL}@${DOMAIN}$`));
 const ADDR = re(new RegExp(`^(${LOCAL})?@${DOMAIN}$`));
-// characters that let displayed text lie (controls, bidi overrides, zero-width): refused in what a person reads
+// controls, bidi overrides and zero-width characters can make shown text lie
 const UNSAFE = /[\x00-\x1f\x7f-\x9f\u200b-\u200f\u2028-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/;
 const text = (lo, hi) => (v) => strCp(lo, hi)(v) && !UNSAFE.test(v);
 const LAST4 = re(/^[0-9]{4}$/);
+const OCCURRENCE = re(/^[A-Za-z0-9_.:-]{1,128}$/);
 const TIME = int(0);
 const UNDO = { kind: [true, oneOf(...UNDO_KINDS)], window_s: [true, int(0, YEAR_S)], note: [false, strCp(1, 200)] };
 export const PREVIEW_FIELDS = {
@@ -67,7 +68,6 @@ export const PREVIEW_FIELDS = {
     site: HOST,
     count: int(0),
 };
-// rule: a pay tool must show amount, currency and payee; a send tool must show who receives it
 export const REQUIRED_BINDS = { pay: ["amount_minor", "currency", "payee"], send: ["to"] };
 const has = (o, k) => Object.hasOwn(o, k);
 function undoRule(u, what) {
@@ -81,7 +81,7 @@ export function profile(v) {
     check(v, {
         oac: [true, constant(VERSION)], type: [true, constant("action-profile")], tool: [true, TOOL],
         effect: [true, oneOf(...EFFECTS)], undo: [true, obj(UNDO, "undo")], tier_floor: [true, oneOf(...TIERS)],
-        binds: [false, binds], other_args: [false, others],
+        binds: [false, binds], other_args: [false, others], occurrence: [false, ARG],
     }, "action profile");
     undoRule(v.undo, "action profile");
     if (v.effect === "read" && v.undo.kind !== "none")
@@ -94,9 +94,14 @@ export function profile(v) {
     const missing = (REQUIRED_BINDS[v.effect] ?? []).filter((f) => !has(v.binds ?? {}, f));
     if (missing.length)
         throw new OACError("malformed", `action profile: a ${v.effect} tool must bind ${missing[0]}`);
+    if (v.effect === "pay" && !has(v, "occurrence"))
+        throw new OACError("malformed", "action profile: a pay tool names its occurrence argument");
+    if (has(v, "occurrence") && !bound.includes(v.occurrence) && !other.includes(v.occurrence)) {
+        throw new OACError("malformed", "action profile: the occurrence argument is not declared");
+    }
     return v;
 }
-/** Every argument is declared (bound or other_args); bound values are valid fields; pay/send carry their fields. */
+/** Every argument is declared and every bound value is a valid field. */
 export function checkAction(actionDoc, prof) {
     const binds = prof.binds ?? {}, args = actionDoc.args;
     const declared = new Set([...Object.values(binds), ...(prof.other_args ?? [])]);
@@ -111,6 +116,9 @@ export function checkAction(actionDoc, prof) {
         if (!has(args, binds[field]))
             throw new OACError("malformed", `a ${prof.effect} action needs ${binds[field]}`);
     }
+    if (has(prof, "occurrence") && !OCCURRENCE(args[prof.occurrence])) {
+        throw new OACError("malformed", `argument ${prof.occurrence} must name the occurrence`);
+    }
 }
 export function action(v) {
     check(v, { tool: [true, TOOL], args: [true, isObj] }, "action");
@@ -189,15 +197,15 @@ export function seal(v) {
     return v;
 }
 export function receipt(v) {
-    const authority = { kind: [true, oneOf(...AUTHORITIES)], ref: [false, strCp(1, 256)] };
+    const authority = { kind: [true, oneOf(...AUTHORITIES)], ref: [false, strCp(1, 256)], digest: [false, DIGEST] };
     const undo = { kind: [true, oneOf(...UNDO_KINDS)], until: [false, TIME], token: [false, strCp(1, 512)] };
     const payment = { rail: [true, oneOf(...RAILS)], ref: [true, strCp(1, 256)], last4: [false, LAST4], order: [false, strCp(1, 256)] };
     check(v, {
         oac: [true, constant(VERSION)], type: [true, constant("receipt")], iss: [true, ID], sub: [true, ID], seq: [true, int(1)],
         prev: [true, (p) => p === null || DIGEST(p)], iat: [true, TIME], tool: [true, TOOL], tier: [true, oneOf(...TIERS)],
         authority: [true, obj(authority, "authority")], action: [true, DIGEST], preview: [false, DIGEST],
-        outcome: [true, oneOf("ok", "failed")], result: [true, DIGEST], undo: [true, obj(undo, "undo")],
-        undoes: [false, DIGEST], payment: [false, obj(payment, "payment")],
+        outcome: [true, oneOf(...OUTCOMES)], result: [true, DIGEST], undo: [true, obj(undo, "undo")],
+        undoes: [false, DIGEST], payment: [false, obj(payment, "payment")], occurrence: [false, OCCURRENCE],
     }, "receipt");
     return v;
 }
@@ -216,3 +224,12 @@ export function undoRequest(v) {
     }, "undo request");
     return v;
 }
+export function deviceProof(v) {
+    const b64 = re(/^[A-Za-z0-9_-]{1,8192}$/);
+    check(v, {
+        oac: [true, constant(VERSION)], type: [true, constant("device-proof")], consent: [true, DIGEST],
+        credential: [true, re(/^[A-Za-z0-9_-]{1,1366}$/)], authenticator_data: [true, b64], client_data_json: [true, b64],
+        signature: [true, b64],
+    }, "device proof");
+    return v;
+}

package/dist/status.js

@@ -1,6 +1,4 @@
-// Status lists (spec section 7.5): which Mandates a signer revoked. W3C Bitstring Status List encoding (GZIP, then
-// multibase base64url "u"; index 0 = left-most bit; at least 16 KB), in a signed OAC object (typ oac-status+jws).
-// Exactly one gzip member and nothing after it: read by hand, because Node's gunzip joins members and skips zeros.
+// Status lists (spec 7.5): which Mandates a signer revoked, as a W3C bitstring.
 import * as zlib from "node:zlib";
 import * as shapes from "./shapes.js";
 import { OACError } from "./errors.js";

package/dist/testing.js

@@ -1,5 +1,4 @@
-// Deterministic keys for test vectors and examples ONLY: each seed is sha-256 of a public label. Never use them for
-// anything real.
+// Fixed keys for tests and vectors. The seeds are public: never use them for anything real.
 import * as crypto from "node:crypto";
 import { ed25519FromSeed, p256FromSeed } from "./jws.js";
 export function vectorKey(label, alg = "EdDSA") {

package/dist/tiers.js

@@ -1,5 +1,4 @@
-// Approval tiers (spec section 4): A runs, B runs with a receipt and an Undo, C needs a Consent or a Mandate, D never
-// runs. tier = max(implied by the effect, profile floor, executor policy, taint floor, any hint); a hint can only raise.
+// Approval tiers (spec 4). A hint can raise the tier, never lower it.
 import * as shapes from "./shapes.js";
 import { OACError } from "./errors.js";
 const ORDER = "ABCD";

package/dist/undo.js

@@ -1,5 +1,4 @@
-// Undo requests (spec section 8.3): native restores prior state inside the window; compensate runs a new action that
-// needs its own Consent, named here; none cannot be undone. Mirrors undo.py.
+// Undo requests (spec 8.3).
 import * as shapes from "./shapes.js";
 import { OACError } from "./errors.js";
 import { KeySet, sign, tokenDigest, verify } from "./jws.js";

package/dist/vercel-ai/index.js

@@ -1,12 +1,8 @@
-// OAC for the Vercel AI SDK (ai 7): import from "open-action-consent/vercel-ai". The SDK can pause a tool call for approval (`toolApproval` -> a
-// `tool-approval-request`) and resume when a `tool-approval-response` with `approved: true` is sent back. That
-// approval is a boolean (optionally HMAC-signed by the server). `withOAC` adds OAC: tier C (computed, not the
-// model's say) asks for approval with the Preview's summary as the reason, and the tool's execute runs only if the
-// person's signed Consent verifies for exactly this call; an approval without it runs nothing.
+// OAC for the Vercel AI SDK: an approval runs nothing without a signed Consent. See guides/vercel-ai.md.
 import { Gate, NeedsConsent, OACError } from "../index.js";
 export const NOT_APPROVED = "Not approved: the person has not signed a consent for exactly this action. Nothing ran.";
 export function withOAC(gate, tools, profiles, o) {
-    const tainted = o.tainted ?? (() => true); // spec section 4: unknown = tainted
+    const tainted = o.tainted ?? (() => true); // unknown means tainted
     const wrapped = {};
     for (const [name, t] of Object.entries(tools)) {
         gate.profile(name, profiles[name]);

package/dist/webauthn.d.ts

@@ -0,0 +1,12 @@
+import { type Jwk } from "./jws.ts";
+export declare const USER_PRESENT = 1, USER_VERIFIED = 4;
+/** What an executor that requires a passkey knows about the person and itself. */
+export type DeviceCheck = {
+    proof: Record<string, any> | null;
+    credentials: Record<string, Jwk>;
+    rp_id: string;
+    origins: string[];
+};
+/** The WebAuthn challenge for a Consent: SHA-256 of the token's ASCII bytes, base64url. */
+export declare const challenge: (consentToken: string) => string;
+export declare function verifyDeviceProof(consentToken: string, check: DeviceCheck): void;

package/dist/webauthn.js

@@ -0,0 +1,55 @@
+// Device proofs (spec 3.6): a WebAuthn assertion from the person's passkey over one exact Consent token.
+import * as crypto from "node:crypto";
+import * as shapes from "./shapes.js";
+import { OACError } from "./errors.js";
+import { parse } from "./jcs.js";
+import { b64url, b64urlDecode, tokenDigest } from "./jws.js";
+export const USER_PRESENT = 0x01, USER_VERIFIED = 0x04;
+/** The WebAuthn challenge for a Consent: SHA-256 of the token's ASCII bytes, base64url. */
+export const challenge = (consentToken) => b64url(crypto.createHash("sha256").update(consentToken, "ascii").digest());
+function verifyEs256Der(jwk, data, sig) {
+    if (jwk.kty !== "EC" || jwk.crv !== "P-256")
+        throw new OACError("bad_alg", "a credential key is P-256");
+    let ok = false;
+    try {
+        const pub = crypto.createPublicKey({ key: { kty: "EC", crv: "P-256", x: jwk.x, y: jwk.y }, format: "jwk" });
+        ok = crypto.verify("sha256", data, { key: pub, dsaEncoding: "der" }, sig);
+    }
+    catch {
+        ok = false;
+    }
+    if (!ok)
+        throw new OACError("bad_signature");
+}
+export function verifyDeviceProof(consentToken, check) {
+    const proof = check.proof;
+    if (proof === null || proof === undefined)
+        throw new OACError("device_proof_missing");
+    shapes.deviceProof(proof);
+    if (proof.consent !== tokenDigest(consentToken))
+        throw new OACError("device_proof_mismatch", "the proof is for another consent");
+    const jwk = Object.hasOwn(check.credentials, proof.credential) ? check.credentials[proof.credential] : undefined;
+    if (jwk === undefined)
+        throw new OACError("unknown_credential");
+    const auth = b64urlDecode(proof.authenticator_data), client = b64urlDecode(proof.client_data_json);
+    if (auth.length < 37)
+        throw new OACError("malformed", "authenticator data is too short");
+    const clientHash = crypto.createHash("sha256").update(client).digest();
+    verifyEs256Der(jwk, Buffer.concat([auth, clientHash]), b64urlDecode(proof.signature));
+    const data = parse(client);
+    if (data === null || typeof data !== "object" || Array.isArray(data) || data.type !== "webauthn.get") {
+        throw new OACError("malformed", "client data is not an assertion");
+    }
+    if (data.challenge !== challenge(consentToken))
+        throw new OACError("challenge_mismatch");
+    const origins = typeof check.origins === "string" ? [check.origins] : [...check.origins];
+    if (!origins.includes(data.origin) || data.crossOrigin === true)
+        throw new OACError("wrong_origin");
+    const rpHash = crypto.createHash("sha256").update(check.rp_id).digest();
+    if (!Buffer.from(auth.subarray(0, 32)).equals(rpHash))
+        throw new OACError("rp_mismatch");
+    if (!(auth[32] & USER_PRESENT))
+        throw new OACError("user_not_present");
+    if (!(auth[32] & USER_VERIFIED))
+        throw new OACError("user_not_verified");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-action-consent",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Open Action Consent: a verifiable yes for actions AI agents take for people. Core SDK plus MCP (SDK v2) and Vercel AI SDK integrations.",
   "license": "Apache-2.0",
   "type": "module",