@decionis/agent-safe-pipeline 0.1.3 → 0.1.4

package/README.md

@@ -1,28 +1,83 @@
 # `@decionis/agent-safe-pipeline`
 
-TypeScript reference implementation of Agent-Safe Pipeline: capture an immutable agent proposal, obtain an independent Decionis decision, coordinate Presence escalation, and execute only through an intent-bound single-use grant and sealed trusted handler registry.
+[![npm version](https://img.shields.io/npm/v/@decionis/agent-safe-pipeline.svg)](https://www.npmjs.com/package/@decionis/agent-safe-pipeline)
+[![Continuous integration](https://github.com/decionis/agent-safe-pipeline/actions/workflows/deploy.yml/badge.svg?branch=master)](https://github.com/decionis/agent-safe-pipeline/actions/workflows/deploy.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/decionis/agent-safe-pipeline/badge)](https://scorecard.dev/viewer/?uri=github.com/decionis/agent-safe-pipeline)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14098/badge)](https://www.bestpractices.dev/projects/14098)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/decionis/agent-safe-pipeline/blob/master/LICENSE)
 
-## Install
+**Let agents propose. Let policy decide.**
+
+`@decionis/agent-safe-pipeline` is the TypeScript reference implementation of the Execution
+Authority architecture. An AI agent may reason, plan, and propose a consequential action. It cannot
+authorize that action, hold the credentials that perform it, or choose which trusted code runs. The
+exact proposal is captured as an immutable, short-lived intent, evaluated independently by Decionis,
+escalated to a verified human when policy requires it, and executed only through a single-use grant
+bound to that one intent. Every decision leaves a Decision Dossier, so the record of what was
+authorized, under which policy, and on whose approval compounds over time.
+
+```text
+Agent -> immutable intent -> Decionis -> ALLOW / ESCALATE / BLOCK -> SafeExecutor -> downstream API
+                                      |
+                                      +-> Presence -> verified human approval -> Decionis re-evaluation
+                                      |
+                                      +-> Decision Dossier -> compounding decision record
+```
+
+The package is a library, not a hosted service. It supplies the boundary; Decionis supplies the
+decision. Its safety claims hold only when the documented trust boundary is preserved: the agent
+runtime never sees Decionis credentials, downstream credentials, or the handler registry.
+
+## Why an execution boundary
+
+Model-level controls shape what an agent says. They cannot prove, after the fact, that a specific
+side effect was authorized by a specific policy at the moment it happened. Prompt filtering,
+fine-tuning, and evaluation all sit before the action; the gap is at execution. This package closes
+it structurally:
+
+- **The agent's input is only the proposal.** Action, target, and parameters. Tenant, actor,
+  downstream system, and credentials come from trusted server configuration and cannot be injected.
+- **The decision is made elsewhere.** Decionis evaluates the canonical intent hash and returns
+  `ALLOW`, `ESCALATE`, or `BLOCK` with a decision identifier and a Decision Dossier identifier.
+- **Approval is evidence, never authority.** Presence proves that a real person approved that exact
+  intent. Decionis verifies the receipt and re-evaluates current policy before any grant exists.
+- **Execution consumes a grant, not a callback.** `SafeExecutor` accepts a captured intent and a
+  decision. It claims the grant atomically, then invokes a handler from a sealed registry.
+- **Everything else fails closed.** A network error, a malformed response, a missing grant, an
+  expired intent, a replayed token, or a binding mismatch all result in no execution.
+
+## Requirements
 
-Install the latest stable release:
+- Node.js 22.14 or later. The package is ESM-only and ships its own TypeScript declarations.
+- A server-side process that holds the Decionis credentials. Never load this package into a
+  browser, an agent sandbox, or any runtime the model can influence.
+- `zod` v4 for handler parameter schemas (installed as a dependency).
+
+## Install
 
 ```bash
 npm install @decionis/agent-safe-pipeline
 ```
 
-To evaluate this prerelease explicitly:
+Stable releases publish under the `latest` tag with npm provenance. Prereleases publish under the
+`next` tag and are never installed by default:
 
 ```bash
-npm install @decionis/agent-safe-pipeline@0.1.3-rc.2
+npm install @decionis/agent-safe-pipeline@next
 ```
 
-Production credentials belong in the trusted executor process, never the agent runtime:
+Decionis credentials belong only in the trusted executor process:
 
 ```text
 DECIONIS_API_URL=https://api.decionis.com
 DECIONIS_API_KEY=server-side-secret
 ```
 
+## Quick start: enforcement
+
+The complete production path in one file. The proposal comes from the agent; everything else comes
+from trusted configuration.
+
 ```ts
 import {
   ActionRegistry,
@@ -33,17 +88,37 @@ import {
 } from "@decionis/agent-safe-pipeline";
 import { z } from "zod";
 
+// 1. Capture the exact proposal. The agent supplies only action, target, and parameters.
+const captured = new IntentCapture().capture(
+  {
+    action: "refund_order",
+    target: "shopify:order:1001",
+    parameters: { orderId: "1001", amountMinor: 35_000 },
+  },
+  {
+    tenantId: config.tenantId,
+    actor: { id: "refund-agent", type: "AI_AGENT" },
+    downstreamTarget: { system: "shopify", operation: "refund", environment: "production" },
+    idempotencyKey: "refund-1001-v1",
+  },
+);
+
+// 2. Ask Decionis. The gate never returns an executable decision without a grant.
 const gate = new DecionisGate({
   baseUrl: process.env.DECIONIS_API_URL!,
   apiKey: process.env.DECIONIS_API_KEY!,
 });
-const captured = new IntentCapture().capture(agentProposal, trustedServerContext);
+const decision = await gate.evaluate(captured);
+
+// 3. Register trusted handlers once, then seal the registry so nothing can be added at runtime.
 const registry = new ActionRegistry()
   .register("refund_order", {
     parametersSchema: z.object({ orderId: z.string(), amountMinor: z.number().int() }).strict(),
     execute: ({ parameters }) => shopify.refund(parameters),
   })
   .seal();
+
+// 4. Execute only through a claimed single-use grant bound to this intent.
 const executor = new SafeExecutor(
   registry,
   new DecionisGrantVerifier({
@@ -51,16 +126,243 @@ const executor = new SafeExecutor(
     apiKey: process.env.DECIONIS_API_KEY!,
   }),
 );
-const result = await executor.run(captured, await gate.evaluate(captured));
+const result = await executor.run(captured, decision);
+
+if (result.outcome === "COMPLETED") {
+  // result.result is the handler's return value.
+  // result.authorization carries the consumed { decisionId, dossierId, grantId, intentHash }.
+}
+```
+
+The executor validates parameters against the handler's schema before the grant is claimed, and the
+grant is claimed before the handler runs. If either step fails, the handler is never invoked.
+
+## Outcomes
+
+Decionis returns one of three verdicts. The executor turns a verdict into exactly one execution
+outcome.
+
+| Verdict                               | Executor behavior                                                       |
+| ------------------------------------- | ----------------------------------------------------------------------- |
+| `ALLOW` with a valid single-use grant | Claim the grant atomically, then invoke the registered handler          |
+| `ESCALATE`                            | Stop. Resolve a DIRECT or MANAGED Presence escalation, then re-evaluate |
+| `BLOCK`, any error, any mismatch      | Fail closed. The handler is never invoked                               |
+
+`SafeExecutor.run` resolves to a discriminated result rather than throwing:
+
+| `outcome`                | Meaning                                                                                                                                                                                   |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `COMPLETED`              | The grant was consumed and the handler returned. `result` holds its value.                                                                                                                |
+| `BLOCKED`                | Nothing ran. `reason` names the refusal: a non-authoritative or non-`ALLOW` decision, a missing or invalid grant, an intent binding or conformance failure, or an unavailable audit sink. |
+| `FAILED_BEFORE_DISPATCH` | The grant was consumed but the handler failed before reaching the provider. Safe to reason about.                                                                                         |
+| `UNKNOWN_AFTER_DISPATCH` | The provider was called and its outcome is unknown. A `recovery` reference supports reconciliation.                                                                                       |
+
+Every outcome that consumed a grant also reports `finalization` (`RECORDED`, `PENDING`, or
+`UNSUPPORTED`). The executor records `COMMITTED`, `FAILED`, or `INDETERMINATE` with Decionis after
+the attempt so commit evidence joins the Decision Dossier chain. Finalization is evidence, never
+authority: it cannot change `outcome` or `executed`.
+
+## Human approval through Presence
+
+When policy escalates, a person must approve that exact intent with independently signed evidence.
+Presence delivers the request to an enrolled device and returns a receipt bound to the intent hash.
+Presence never authorizes execution; Decionis verifies the receipt and re-evaluates policy. The
+package supports two integration levels, and the executor's grant path is identical in both.
+
+| Mode      | Who coordinates Presence | Credentials in the executor | Entry point                                          |
+| --------- | ------------------------ | --------------------------- | ---------------------------------------------------- |
+| `DIRECT`  | Your trusted executor    | Decionis and Presence       | `PresenceApprovalCoordinator`                        |
+| `MANAGED` | Decionis                 | Decionis only               | `DecionisGate.evaluate` with an `escalation` request |
+
+In MANAGED mode, pass routing and ceremony constraints outside the canonical intent, then poll
+Decionis only:
+
+```ts
+const pending = await gate.evaluate(captured, undefined, {
+  escalation: {
+    mode: "MANAGED",
+    approver: { principal_id: approverId, role_id: "APPROVER" },
+    verification_requirements: { methods: ["WEBAUTHN"], level: "HIGH_CONFIDENCE" },
+  },
+});
+// pending.verdict === "ESCALATE"; pending.managedEscalation is set; no grant exists yet.
+
+const authorized = await gate.waitForAuthorization(captured, pending, { signal });
+const result = await executor.run(captured, authorized);
+```
+
+`waitForAuthorization` polls with capped exponential backoff and bounded jitter, and stops at the
+intent or escalation expiry. It returns a normal `ALLOW` decision with a grant only after Decionis
+has verified the Presence evidence and re-evaluated current policy. Approval cannot revive an intent
+after it expires. Presence transport or schema failures and Decionis re-authorization failures
+return stable fail-closed decisions; raw downstream error text never reaches the caller.
+
+## Shadow mode
+
+Measure before you enforce. `ShadowPipeline` wraps an execution path you already run and records
+what Decionis would have decided, without the ability to stop, delay, or alter it.
+
+```ts
+import { DecionisGate, ShadowPipeline } from "@decionis/agent-safe-pipeline";
+
+const shadow = new ShadowPipeline(new DecionisGate({ baseUrl, apiKey, mode: "SHADOW" }), {
+  timeoutMs: 2_000,
+});
+
+const run = await shadow.observe(captured, () => existingRefund(order));
+// run.production is your unchanged result, available as soon as production settles.
+const observation = await run.observation;
+// The observation runs under its own timeout and never rejects; it reports the verdict
+// Decionis would have returned, the dossier identifier, and whether a grant was discarded.
+```
+
+A shadow observation carries no grant, is structurally distinct from a `GateDecision`, and is
+rejected by `SafeExecutor` at runtime. See
+[shadow mode](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/shadow-mode.md).
+
+## Adoption path
+
+The same `IntentCapture`, `ActionRegistry`, and handler code carry through every stage. Nothing is
+rewritten between them.
+
+| Stage       | Authority                                                     | What it proves                                                                   |
+| ----------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Development | `createFixtureAuthorityPair` (refuses `NODE_ENV=production`)  | The intent, registry, and executor wiring is correct                             |
+| Shadow      | `ShadowPipeline` over `DecionisGate` with `mode: "SHADOW"`    | What Decionis would have decided about actions that already run; no grant issued |
+| Enforcement | `DecionisGate` plus `DecionisGrantVerifier` in `SafeExecutor` | Nothing runs without an independent decision and a consumed single-use grant     |
+
+## Local testing
+
+`@decionis/agent-safe-pipeline/testing` ships `LocalPresence` and `LocalAuthority`: loopback doubles
+that the production clients talk to unchanged. They enforce the structural intent-hash binding,
+verify receipts the way Decionis does, issue single-use grants, orchestrate managed escalations, and
+record finalization. The person's ceremony becomes a method call.
+
+```ts
+import { DecionisGate, DecionisGrantVerifier } from "@decionis/agent-safe-pipeline";
+import {
+  LocalAuthority,
+  LocalPresence,
+  LOCAL_AUTHORITY_API_KEY,
+} from "@decionis/agent-safe-pipeline/testing";
+
+const presence = new LocalPresence({ autoComplete: "MANUAL", roles: { "synthetic-cro": "CRO" } });
+const authority = new LocalAuthority({ presence });
+await presence.start();
+await authority.start();
+
+const gate = new DecionisGate({
+  baseUrl: authority.baseUrl,
+  apiKey: LOCAL_AUTHORITY_API_KEY,
+  allowInsecureLoopback: true,
+});
+// ... evaluate, then complete the ceremony with presence.approve(requestId)
+// and assert on grants, receipts, and recorded commits.
 ```
 
-| Outcome                           | Execution behavior                                   |
-| --------------------------------- | ---------------------------------------------------- |
-| ALLOW plus valid single-use grant | Consume grant, then invoke registered handler        |
-| ESCALATE                          | Stop; obtain Presence receipt and ask Decionis again |
-| BLOCK or any error/mismatch       | Fail closed; do not invoke handler                   |
+Both doubles bind to `127.0.0.1` on an ephemeral port and refuse to construct under
+`NODE_ENV=production`. The testing entry also exports the development fixture primitives
+(`createFixtureAuthorityPair`, `FixtureDecisionAuthority`, `FixtureAuthorizationVerifier`,
+`InMemoryReplayStore`). Those remain available at the package root until 1.0; new code should import
+them from the testing entry. See
+[local testing](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/local-testing.md).
+
+## API overview
+
+| Concern        | Exports                                                                                           | Role                                                                                           |
+| -------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Intent         | `IntentCapture`, `CanonicalIntentHasher`, `ExecutionIntentSchema`, `AgentProposalSchema`          | Build the immutable `agent-safe.intent/1` binding and its canonical SHA-256 hash               |
+| Decision       | `DecionisGate`, `DecisionAuthority`, `GateDecision`, `FailClosedDecision`                         | Obtain an independent `ALLOW` / `ESCALATE` / `BLOCK` decision with dossier identifiers         |
+| Human approval | `PresenceApprovalCoordinator`, `ManagedEscalationRequest`, `HumanApprovalEvidence`                | Coordinate DIRECT Presence ceremonies or request MANAGED orchestration by Decionis             |
+| Execution      | `SafeExecutor`, `ActionRegistry`, `DecionisGrantVerifier`, `AuthorizationVerifier`, `ReplayStore` | Claim the single-use grant, validate parameters, invoke a sealed handler, finalize the attempt |
+| Observation    | `ShadowPipeline`, `ShadowObservation`                                                             | Record what the authority would have decided without granting execution                        |
+| Audit          | `AuditRecorder`, `AuditEventV1`, `AuditSink`                                                      | Emit immutable, redacted lifecycle records through one bounded sink call                       |
+| Testing        | `LocalPresence`, `LocalAuthority`, `createFixtureAuthorityPair` (from `/testing`)                 | Loopback doubles and fixture authorities for development and CI                                |
+
+The seam between this package and Decionis is two interfaces, `DecisionAuthority` and
+`AuthorizationVerifier`, plus a published OpenAPI contract. Anyone can implement the interfaces; the
+library checks no plan, key, or entitlement.
+
+## Production invariants
+
+1. Agent input contains only the proposed action, target, and parameters. Tenant, actor, downstream
+   target, and credentials come from trusted runtime configuration.
+2. The exact canonical intent is hashed and expires quickly.
+3. Decionis decides independently. Network errors, malformed responses, missing grants, and binding
+   mismatches fail closed.
+4. Presence proves a human approved that exact intent. It never authorizes execution; Decionis
+   verifies the receipt and re-evaluates policy.
+5. The grant is bound to the intent, decision, audience, and expiry, and is claimed atomically before
+   the handler runs. The attempt is finalized afterwards as evidence, never as authority.
+6. Downstream credentials exist only behind the trusted executor.
+7. Every decision is evidence-bearing. An `ALLOW` without a dossier identifier or grant is refused
+   as non-executable. A dossier identifier is never an execution credential.
+
+Read the [trust boundary](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/trust-boundary.md)
+and the [threat model](https://github.com/decionis/agent-safe-pipeline/blob/master/THREAT-MODEL.md)
+before integrating a real downstream API.
+
+## Assurance and supply chain
+
+- **Provenance.** Every release is published through npm trusted publishing with a provenance
+  attestation, from a keyless-signed release tag, and archived under Zenodo concept DOI
+  [`10.5281/zenodo.22312955`](https://doi.org/10.5281/zenodo.22312955).
+- **Release evidence.** Each GitHub release carries the tarball, a CycloneDX SBOM, Sigstore
+  provenance and SBOM attestations, and a checksum file. See
+  [reproducible builds](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/reproducible-builds.md).
+- **Testing.** Coverage gates of 90% lines, functions, and statements and 85% branches; mutation
+  testing on the trust boundary; deterministic property-based fuzzing of canonical intent handling;
+  a loopback wire-contract harness that exercises the packed package over real HTTP.
+- **Adversarial proof.** The
+  [golden adversarial demo](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/golden-adversarial-demo)
+  runs one legitimate path and eight attacks against the same boundary, offline, and exits 0 only
+  when exactly one action executes.
+- **Scanning.** CodeQL, secret scanning, OpenSSF Scorecard, and OpenSSF Best Practices, with
+  separate production and toolchain dependency audits. The control-to-artifact map is in
+  [SECURITY-EVIDENCE.md](https://github.com/decionis/agent-safe-pipeline/blob/master/SECURITY-EVIDENCE.md).
+
+## Examples
+
+Runnable, offline, and fixture-backed unless noted. Each one uses this package unchanged.
+
+- [`basic-agent`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/basic-agent): the smallest `BLOCK` flow.
+- [`shopify-refund-agent`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/shopify-refund-agent): amount-based `ALLOW` / `ESCALATE` / `BLOCK`.
+- [`github-deploy-agent`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/github-deploy-agent): environment and force-push controls.
+- [`procurement-agent`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/procurement-agent): an in-budget request held by policy.
+- [`mcp-tool-gate`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/mcp-tool-gate): a real stdio MCP server with a governed tool.
+- [`local-escalation`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/local-escalation): DIRECT and MANAGED Presence escalation against loopback doubles.
+- [`presence-live-approval`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/presence-live-approval): DIRECT Presence enforcement against the real services with a FIDO2 or FIDO2-plus-liveness ceremony (needs credentials).
+- [`presence-managed-approval`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/presence-managed-approval): Decionis-managed Presence orchestration against the real services (needs credentials).
+- [`golden-adversarial-demo`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/golden-adversarial-demo): one golden path, eight attacks, zero unauthorized executions.
+
+## Open core
+
+Everything in the repository is Apache-2.0: the architecture, the intent contract, the execution
+boundary, the client adapters, the audit contract, shadow mode, the conformance vectors, and the
+examples. Decionis operates the policy control plane behind `DecionisGate`: policy evaluation, grant
+issuance and atomic consumption, Decision Dossier signing and retention, and Presence.
+[OPEN-CORE.md](https://github.com/decionis/agent-safe-pipeline/blob/master/OPEN-CORE.md) states the
+boundary and the commitments that keep it stable.
+
+## Research
+
+Decionis Research defines the architecture, this package demonstrates it as tested code, and the
+Decionis platform operates it as a hosted authority.
+
+- Jejelowo, Festus. "The Execution Verifiability Gap: Why Model Governance Cannot Authorize
+  Consequential Actions." Decionis Research, version 1.0, 21 August 2026.
+  [Canonical article](https://decionis.com/research/execution-verifiability-gap) ·
+  [Archival PDF](https://decionis.com/research/execution-verifiability-gap-v1.0.pdf)
+
+To cite the software, use the
+[CITATION.cff](https://github.com/decionis/agent-safe-pipeline/blob/master/CITATION.cff) in the
+repository or the Zenodo record above.
+
+## Support and license
 
-Presence transport/schema failures and Decionis reauthorization failures return stable fail-closed
-decisions; raw downstream error text is never part of the coordinator result.
+- Vulnerabilities: [GitHub private vulnerability reporting](https://github.com/decionis/agent-safe-pipeline/security/advisories/new) or `security@decionis.com`. Never open a public issue for a security report.
+- Everything else: [GitHub Issues](https://github.com/decionis/agent-safe-pipeline/issues).
+- Architecture and full documentation: [Agent-Safe Pipeline README](https://github.com/decionis/agent-safe-pipeline#readme).
 
-Support: use [GitHub private vulnerability reporting](https://github.com/decionis/agent-safe-pipeline/security/advisories/new) or `security@decionis.com` for vulnerabilities and [GitHub Issues](https://github.com/decionis/agent-safe-pipeline/issues) for non-sensitive problems. Architecture: [Agent-Safe Pipeline README](https://github.com/decionis/agent-safe-pipeline#readme). License: Apache-2.0. Trademark terms: [TRADEMARKS.md](https://github.com/decionis/agent-safe-pipeline/blob/master/TRADEMARKS.md).
+Apache-2.0. Trademark terms in
+[TRADEMARKS.md](https://github.com/decionis/agent-safe-pipeline/blob/master/TRADEMARKS.md).

package/dist/Index.d.ts

@@ -1,4 +1,5 @@
 export * from "./approval/PresenceApprovalCoordinator.js";
+export * from "./audit/AuditRecorder.js";
 export * from "./decision/DecisionAuthority.js";
 export * from "./decision/DecionisGate.js";
 export * from "./decision/FixtureDecisionAuthority.js";

package/dist/Index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Index.d.ts","sourceRoot":"","sources":["../src/Index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"Index.d.ts","sourceRoot":"","sources":["../src/Index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}

package/dist/Index.js

@@ -1,4 +1,5 @@
 export * from "./approval/PresenceApprovalCoordinator.js";
+export * from "./audit/AuditRecorder.js";
 export * from "./decision/DecisionAuthority.js";
 export * from "./decision/DecionisGate.js";
 export * from "./decision/FixtureDecisionAuthority.js";

package/dist/Index.js.map

@@ -1 +1 @@
-{"version":3,"file":"Index.js","sourceRoot":"","sources":["../src/Index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"Index.js","sourceRoot":"","sources":["../src/Index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}

package/dist/approval/PresenceApprovalCoordinator.d.ts

@@ -1,9 +1,22 @@
 import type { GateResult, HumanApprovalGate } from "@decionis/presence-node";
+import type { AuditRecorder } from "../audit/AuditRecorder.js";
 import type { DecisionAuthority, GateDecision } from "../decision/DecisionAuthority.js";
 import type { CapturedIntent } from "../intent/ExecutionIntent.js";
 export type PresenceGateResult = GateResult;
 export type PresenceApprovalClient = Pick<HumanApprovalGate, "gate" | "outcome">;
+/** Verification requirements Presence enforces for the approval ceremony (docs/22). */
+export type PresenceVerificationRequirements = NonNullable<Parameters<HumanApprovalGate["gate"]>[0]["requirements"]>;
 export interface PresenceApprovalCoordinatorOptions {
+    /** Optional bounded lifecycle audit recorder. */
+    readonly audit?: AuditRecorder;
+    /**
+     * Ceremony Presence must complete before it seals a receipt, such as WebAuthn
+     * alone or WebAuthn with active liveness. Omitted, Presence applies its
+     * default standard-confidence device proof.
+     */
+    readonly requirements?: PresenceVerificationRequirements;
+    /** Approval-request lifetime in seconds (30-600); omitted, Presence applies its default. */
+    readonly ttlSeconds?: number;
     /** Maximum number of outcome lookups after Presence returns HUMAN_REQUIRED. */
     readonly maxAttempts?: number;
     /** Initial exponential-backoff delay in milliseconds. */
@@ -34,6 +47,9 @@ export declare class PresenceApprovalCoordinator {
     private readonly organization;
     private readonly approverId;
     private readonly polling;
+    private readonly audit;
+    private readonly requirements;
+    private readonly ttlSeconds;
     constructor(presence: PresenceApprovalClient, authority: DecisionAuthority, organization: string, approverId: string, options?: PresenceApprovalCoordinatorOptions);
     request(captured: CapturedIntent): Promise<PresenceGateResult>;
     resolveAndReauthorize(captured: CapturedIntent, result: PresenceGateResult, options?: PresenceResolutionOptions): Promise<GateDecision>;
@@ -49,7 +65,16 @@ export declare class PresenceApprovalCoordinator {
     private requestIdOf;
     private evidenceOf;
     private boundedIdentifier;
+    private recordPresence;
     private isRecord;
+    /**
+     * Presence replays a sealed answer for a repeated idempotency key, so the key
+     * must identify exactly one captured intent for one approver: a re-captured
+     * intent has a new hash and must get a new request. The digest keeps the key
+     * inside Presence's `[A-Za-z0-9._:-]{8,128}` alphabet whatever the runtime's
+     * business key or the approver identity contain.
+     */
+    static presenceIdempotencyKey(captured: CapturedIntent, approverId: string): string;
     private static pollingConfiguration;
     private static sleep;
 }

package/dist/approval/PresenceApprovalCoordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PresenceApprovalCoordinator.d.ts","sourceRoot":"","sources":["../../src/approval/PresenceApprovalCoordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EAEb,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAC5C,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjF,MAAM,WAAW,kCAAkC;IACjD,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,yDAAyD;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AA4BD;;;;;GAKG;AACH,qBAAa,2BAA2B;IAIpC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAN7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;gBAG5B,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,iBAAiB,EAC5B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EACnC,OAAO,GAAE,kCAAuC;IAKrC,OAAO,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAwC9D,qBAAqB,CAChC,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,YAAY,CAAC;YAyCV,cAAc;YA2Fd,aAAa;YAiBb,iBAAiB;YAqBjB,gBAAgB;IAgC9B,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,MAAM,CAAC,oBAAoB;mBAuCd,KAAK;CAkB3B"}
+{"version":3,"file":"PresenceApprovalCoordinator.d.ts","sourceRoot":"","sources":["../../src/approval/PresenceApprovalCoordinator.ts"],"names":[],"mappings":"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"}

package/dist/approval/PresenceApprovalCoordinator.js

@@ -1,4 +1,7 @@
+import { createHash } from "node:crypto";
 import { FailClosedDecision } from "../decision/DecisionAuthority.js";
+const MIN_PRESENCE_TTL_SECONDS = 30;
+const MAX_PRESENCE_TTL_SECONDS = 600;
 const DEFAULT_MAX_ATTEMPTS = 20;
 const DEFAULT_INITIAL_DELAY_MS = 250;
 const DEFAULT_MAX_DELAY_MS = 2_000;
@@ -18,21 +21,37 @@ export class PresenceApprovalCoordinator {
     organization;
     approverId;
     polling;
+    audit;
+    requirements;
+    ttlSeconds;
     constructor(presence, authority, organization, approverId, options = {}) {
         this.presence = presence;
         this.authority = authority;
         this.organization = organization;
         this.approverId = approverId;
         this.polling = PresenceApprovalCoordinator.pollingConfiguration(options);
+        this.audit = options.audit;
+        this.requirements = options.requirements;
+        if (options.ttlSeconds !== undefined &&
+            (!Number.isInteger(options.ttlSeconds) ||
+                options.ttlSeconds < MIN_PRESENCE_TTL_SECONDS ||
+                options.ttlSeconds > MAX_PRESENCE_TTL_SECONDS)) {
+            throw new Error("PRESENCE_TTL_INVALID");
+        }
+        this.ttlSeconds = options.ttlSeconds;
     }
     async request(captured) {
         try {
+            // `intentHash` is the structural binding Presence seals into the envelope
+            // when the SDK supports it; the display field below stays the human copy.
+            const action = {
+                intent: captured.intent.action,
+                target: captured.intent.target,
+                surface: "agent_safe_pipeline",
+                intentHash: captured.intentHash,
+            };
             const result = await this.presence.gate({
-                action: {
-                    intent: captured.intent.action,
-                    target: captured.intent.target,
-                    surface: "agent_safe_pipeline",
-                },
+                action,
                 agent: {
                     id: captured.intent.actor.id,
                     display: captured.intent.actor.id,
@@ -49,11 +68,14 @@ export class PresenceApprovalCoordinator {
                         { key: "intent_hash", label: "Intent hash", value: captured.intentHash },
                     ],
                 },
-            }, `presence:${captured.intent.idempotencyKey}`);
+                ...(this.requirements === undefined ? {} : { requirements: this.requirements }),
+                ...(this.ttlSeconds === undefined ? {} : { ttlSeconds: this.ttlSeconds }),
+            }, PresenceApprovalCoordinator.presenceIdempotencyKey(captured, this.approverId));
             const verdict = this.verdictOf(result);
             if (verdict === null || (verdict === "HUMAN_REQUIRED" && this.requestIdOf(result) === null)) {
                 throw new Error("Presence returned an invalid gate response");
             }
+            await this.recordPresence(captured, verdict === "HUMAN_REQUIRED" ? "PRESENCE_ESCALATED" : "PRESENCE_RESOLVED", verdict);
             return result;
         }
         catch {
@@ -74,12 +96,14 @@ export class PresenceApprovalCoordinator {
             return FailClosedDecision.create(captured.intentHash, "PRESENCE_RESPONSE_INVALID");
         }
         if (verdict !== "PROCEED") {
+            await this.recordPresence(captured, "PRESENCE_RESOLVED", verdict);
             return FailClosedDecision.create(captured.intentHash, `PRESENCE_${verdict}`);
         }
         const evidence = this.evidenceOf(resolution.result);
         if (evidence === null) {
             return FailClosedDecision.create(captured.intentHash, "PRESENCE_PROOF_MISSING");
         }
+        await this.recordPresence(captured, "PRESENCE_RESOLVED", verdict, evidence.receiptDossierId);
         const preAuthorizationFailure = this.boundaryFailure(captured, options.signal);
         if (preAuthorizationFailure !== null) {
             return FailClosedDecision.create(captured.intentHash, preAuthorizationFailure);
@@ -268,9 +292,33 @@ export class PresenceApprovalCoordinator {
     boundedIdentifier(value) {
         return typeof value === "string" && value.length > 0 && value.length <= 200;
     }
+    async recordPresence(captured, eventType, verdict, dossierId) {
+        await this.audit?.record({
+            eventType,
+            captured,
+            authority: "NON_AUTHORITATIVE",
+            ...(dossierId === undefined ? {} : { dossierId }),
+            reasonCodes: [`PRESENCE_${verdict}`],
+        });
+    }
     isRecord(value) {
         return typeof value === "object" && value !== null && !Array.isArray(value);
     }
+    /**
+     * Presence replays a sealed answer for a repeated idempotency key, so the key
+     * must identify exactly one captured intent for one approver: a re-captured
+     * intent has a new hash and must get a new request. The digest keeps the key
+     * inside Presence's `[A-Za-z0-9._:-]{8,128}` alphabet whatever the runtime's
+     * business key or the approver identity contain.
+     */
+    static presenceIdempotencyKey(captured, approverId) {
+        const digest = createHash("sha256")
+            .update(captured.intentHash)
+            .update("\u0000")
+            .update(approverId)
+            .digest("hex");
+        return `presence-${digest}`;
+    }
     static pollingConfiguration(options) {
         const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
         const initialDelayMs = options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;