@emilia-protocol/openai-agents 0.1.1 → 0.1.3

package/README.md

@@ -47,11 +47,15 @@ const cancelOrder = tool({
 
 const agent = new Agent({ name: 'Ops', tools: [cancelOrder] });
 
-// One gate, configured once. actionFor maps a tool call -> canonical EP action_type.
+// One gate, configured once. actionFor maps a tool call -> the canonical EP
+// action_type the receipt must be bound to. For real safety, bind to the
+// SPECIFIC target the call acts on (not just the tool name) so a receipt for one
+// resource can't authorize another — and fold in the call identity so the same
+// receipt can't be reused across two different tool calls.
 const gate = requireReceiptForOpenAIAgent({
   trustedKeys: [process.env.EMILIA_ISSUER_KEY], // base64url SPKI-DER issuer key(s) you trust
   maxAgeSec: 900,
-  actionFor: (toolName /*, args */) => `openai.tool.${toolName}`,
+  actionFor: (toolName, args) => `openai.tool.${toolName}:${args?.orderId ?? ''}`,
 });
 
 let result = await run(agent, 'Cancel order 4242');
@@ -102,6 +106,9 @@ For every pending tool-approval interruption:
 ## Production note
 
 - **Pin `trustedKeys`** to your real issuer key(s). **Drop `allowInlineKey`** (it only proves integrity, never trust).
+- **Bind to the target, not just the tool.** Make `actionFor` incorporate the specific resource the call touches (and ideally the `callId` / an args hash), so a receipt minted for one action can't be replayed against a different one.
+- A receipt is **consumed only when it actually drives an `approve`** — never on a reject — so a blocked approval stays retryable with a fresh, valid receipt.
+- **Rejections are sanitized:** a reject decision carries only a machine-readable `reason` code, never the signer, the subject, or verifier internals.
 - The **consumed-receipt set is per-process** (replay defense across restarts/instances needs a shared store — see `@emilia-protocol/gate`).
 - This is **necessary, not sufficient**. It composes with — and never substitutes for — the resource owner's own authorization and policy checks. It makes the human approval that OpenAI already asks for into auditable, portable evidence; it does not decide whether the action *should* be allowed.
 

package/index.d.ts

@@ -36,7 +36,13 @@ export interface RequireReceiptForOpenAIAgentOptions {
   allowInlineKey?: boolean;
   /** Reject receipts older than this many seconds. Default 900. */
   maxAgeSec?: number;
-  /** REQUIRED. Map a tool call to the canonical EP action_type the receipt must bind. */
+  /**
+   * REQUIRED. Map a tool call to the canonical EP action_type the receipt must
+   * bind. For per-target binding, incorporate the SPECIFIC resource the call
+   * acts on (e.g. `payment.release:${args.destination}`); to stop a receipt
+   * being reused across distinct calls, fold in the call identity (the
+   * interruption's callId or a stable hash of args).
+   */
   actionFor: (toolName: string, args: unknown) => string;
 }
 

package/index.js

@@ -40,10 +40,14 @@
 // by relative path — the same convention @emilia-protocol/gate uses. When this
 // package is installed from npm, the published build resolves the bare
 // "@emilia-protocol/require-receipt" specifier; both point at the same module.
-import { verifyEmiliaReceipt } from '../require-receipt/index.js';
+// The canonical makeReceiptGate encodes verify + target binding + reserve→
+// commit/release replay safety + sanitized {reason} rejections in one place.
+import { makeReceiptGate } from '../require-receipt/gate.js';
 
-/** Process-local set of consumed receipt_ids (replay defense). Per-process only. */
+/** Process-local set of consumed receipt_ids (replay defense). Per-process only.
+ *  Shared across every per-action gate so one receipt is spent at most once. */
 const consumed = new Set();
+const sharedStore = { has: (id) => consumed.has(id), add: (id) => consumed.add(id) };
 
 /** Reset the consumed-receipt set. Test/ops helper — not a production control. */
 export function _resetConsumed() {
@@ -128,15 +132,47 @@ export function requireReceiptForOpenAIAgent(opts = {}) {
     throw new TypeError('requireReceiptForOpenAIAgent: opts.actionFor (toolName, args) => action_type is required');
   }
 
+  // One canonical gate per bound action. The action_type IS the binding (the
+  // verifier matches the receipt's claim.action_type to it), so callId is NOT
+  // folded into the gate's action — doing so would break verification against a
+  // receipt minted for the bare action. All gates share one consumed store so a
+  // receipt is spent at most once across calls; the compound receipt_id#callId
+  // key (below) is the belt-and-suspenders cross-call defense.
+  const gates = new Map();
+  const gateFor = (action) => {
+    let gate = gates.get(action);
+    if (!gate) {
+      gate = makeReceiptGate({ action, trustedKeys, allowInlineKey, maxAgeSec, store: sharedStore });
+      gates.set(action, gate);
+    }
+    return gate;
+  };
+
+  // Track the reservation a decide() approval holds, so resolve() can commit it
+  // (on a driven approve) or release it (rollback) — keyed by receipt_id.
+  const pending = new Map();
+
   /**
-   * Decide a single interruption against a single receipt. Pure: no side effects
-   * EXCEPT marking a receipt_id consumed when (and only when) it is the valid
-   * receipt that earns an approve.
+   * Decide a single interruption against a single receipt.
+   *
+   * The decision NEVER carries the raw verifier output — only an allowlisted,
+   * sanitized shape ({decision, action, toolName, callId, reason} plus, on the
+   * approve path only, receipt_id + the accountable subject). A rejection never
+   * leaks the signer, the verifier's `detail`, or any other library internals.
+   *
+   * Consume-on-approve: when `decide` returns an `approve`, it marks the
+   * receipt_id consumed (replay defense) — and ONLY then. A reject (including a
+   * replayed or invalid receipt) never consumes anything, so a blocked approval
+   * stays retryable with a fresh, valid receipt. Replay is still checked here,
+   * before any approval, so a receipt can satisfy at most one interruption.
    */
   function decide(interruption, receipt) {
     const toolName = interruptionToolName(interruption);
     const callId = interruptionCallId(interruption);
     const args = interruptionArgs(interruption);
+    // Bind the receipt to THIS tool call. actionFor SHOULD incorporate the
+    // specific call identity (callId or a hash of args) so a single receipt
+    // cannot be reused across distinct tool calls — see the README note.
     const action = toolName != null ? actionFor(toolName, args) : null;
 
     const base = { action, toolName, callId };
@@ -148,28 +184,49 @@ export function requireReceiptForOpenAIAgent(opts = {}) {
       return { decision: 'reject', ...base, reason: 'no_receipt_for_interruption' };
     }
 
-    const v = verifyEmiliaReceipt(receipt, {
-      trustedKeys,
-      allowInlineKey,
-      maxAgeSec,
-      action, // binds the receipt's claim.action_type to THIS tool call
-    });
-    if (!v.ok) {
-      return { decision: 'reject', ...base, reason: v.reason || 'invalid_receipt' };
+    // The action_type is the binding — the gate verifies the receipt against it.
+    // callId is NOT passed as a target (that would change the verified binding);
+    // it is only used for the compound cross-call replay key below.
+    const gate = gateFor(action);
+
+    // Belt-and-suspenders cross-call defense: refuse if the SAME receipt was
+    // already used for a DIFFERENT call. We can only check this once we know the
+    // receipt_id, so peek at it from the receipt before the gate runs.
+    const receiptId = receipt?.payload?.receipt_id;
+    const callKey = receiptId && callId != null ? `${receiptId}#${callId}` : null;
+
+    // gate.check verifies (sanitized reason), enforces action binding + trust,
+    // and reserves the receipt (one-time consumption / replay safety).
+    const c = gate.check(receipt);
+    if (!c.ok) {
+      // Map the gate's sanitized refusal to this adapter's decision vocabulary.
+      // The gate uses `replay_refused`; this API has long exposed `receipt_replayed`.
+      const reason = c.body?.rejected?.reason || 'invalid_receipt';
+      if (reason === 'replay_refused') {
+        return { decision: 'reject', ...base, reason: 'receipt_replayed', receipt_id: receiptId };
+      }
+      return { decision: 'reject', ...base, reason };
     }
 
-    // Replay defense: a receipt_id may earn an approval only once per process.
-    if (v.receipt_id && consumed.has(v.receipt_id)) {
-      return { decision: 'reject', ...base, reason: 'receipt_replayed', receipt_id: v.receipt_id };
+    // The gate cleared verify + bare-receipt_id replay. Now apply the compound
+    // call-scoped guard: if this exact receipt already drove a DIFFERENT call,
+    // refuse and release the reservation the gate just took.
+    if (callKey && consumed.has(callKey)) {
+      gate.release(c.receiptId);
+      return { decision: 'reject', ...base, reason: 'receipt_replayed', receipt_id: c.receiptId };
     }
-    if (v.receipt_id) consumed.add(v.receipt_id);
+
+    // Record the reservation so resolve() can commit (driven approve) or release
+    // (rollback). decide() reserves but does NOT commit — a standalone approve
+    // that is never driven leaves the receipt retryable, matching prior behavior.
+    pending.set(c.receiptId, { gate, callKey });
 
     return {
       decision: 'approve',
       ...base,
       reason: 'valid_action_bound_receipt',
-      receipt_id: v.receipt_id,
-      subject: v.subject,
+      receipt_id: c.receiptId,
+      subject: c.subject,
     };
   }
 
@@ -222,13 +279,57 @@ export function requireReceiptForOpenAIAgent(opts = {}) {
     const rejected = [];
     const decisions = [];
 
+    // Release the reservation decide() took when the approval is not actually
+    // driven (no approve() to call, or approve() threw) — keeps it retryable.
+    const releasePending = (d) => {
+      if (!d.receipt_id) return;
+      const p = pending.get(d.receipt_id);
+      if (p) {
+        p.gate.release(d.receipt_id);
+        pending.delete(d.receipt_id);
+      }
+    };
+
+    // Finalize one-time consumption for a driven approve: commit in the gate and
+    // also record the compound call-scoped key for the cross-call replay guard.
+    const commitPending = (d) => {
+      if (!d.receipt_id) return;
+      const p = pending.get(d.receipt_id);
+      if (p) {
+        p.gate.commit(d.receipt_id); // moves receipt_id into the shared store
+        if (p.callKey) consumed.add(p.callKey);
+        pending.delete(d.receipt_id);
+      }
+    };
+
     for (const interruption of interruptions) {
       const receipt = lookupReceipt(receipts, interruption);
       const d = decide(interruption, receipt);
       decisions.push(d);
       if (d.decision === 'approve') {
-        approved.push(interruption);
-        if (state && typeof state.approve === 'function') state.approve(interruption);
+        // decide() RESERVED the receipt for this approve. Drive the SDK's
+        // approval now; commit (spend) only if approve() succeeds. If approve()
+        // is missing or throws, release the reservation so the (un-driven)
+        // approval stays retryable — a receipt is spent only when it drives one.
+        if (state && typeof state.approve === 'function') {
+          try {
+            state.approve(interruption);
+            commitPending(d);
+            approved.push(interruption);
+          } catch (err) {
+            releasePending(d);
+            d.decision = 'reject';
+            d.reason = 'approve_failed';
+            rejected.push(interruption);
+            if (state && typeof state.reject === 'function') {
+              state.reject(interruption, { message: `EMILIA: approve_failed` });
+            }
+          }
+        } else {
+          // No approve() to drive -> do not spend the receipt.
+          releasePending(d);
+          approved.push(interruption);
+        }
       } else {
         rejected.push(interruption);
         if (state && typeof state.reject === 'function') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emilia-protocol/openai-agents",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Turn the OpenAI Agents SDK human-in-the-loop tool-approval step into a verifiable, offline-checkable EMILIA authorization receipt. OpenAI pauses an agent and asks for approval; EMILIA makes that approval portable, tamper-evident evidence — a named human accountably authorized this exact tool call. Composes WITH OpenAI's approval primitive (needsApproval / interruptions / state.approve|reject); does not replace it. Reference implementation, experimental.",
   "type": "module",
   "main": "index.js",
@@ -32,7 +32,7 @@
   ],
   "engines": { "node": ">=18" },
   "dependencies": {
-    "@emilia-protocol/require-receipt": "^0.3.0"
+    "@emilia-protocol/require-receipt": "^0.4.0"
   },
   "peerDependencies": {
     "@openai/agents": ">=0.0.1"