{
  "markdown": "# Agent-Safe Pipeline\n\n[![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)\n[![CodeQL](https://github.com/decionis/agent-safe-pipeline/actions/workflows/codeql.yml/badge.svg?branch=master)](https://github.com/decionis/agent-safe-pipeline/actions/workflows/codeql.yml)\n[![Secret scanning](https://github.com/decionis/agent-safe-pipeline/actions/workflows/secrets.yml/badge.svg?branch=master)](https://github.com/decionis/agent-safe-pipeline/actions/workflows/secrets.yml)\n[![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)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14098/badge)](https://www.bestpractices.dev/projects/14098)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)\n\n**Let agents propose. Let policy decide.**\n\nAgent-Safe Pipeline is the reference implementation of the Execution Authority architecture: AI-agent actions execute only through an independent authorization boundary, and every authorization decision leaves a verifiable evidence record.\n\nThis repository is a library and runnable reference implementation, not a hosted authorization service or a substitute for provider-side identity, least privilege, network isolation, and incident response. Its safety claims apply only when the documented trust boundary is preserved.\n\n```text\nAgent -> immutable intent -> Decionis -> ALLOW / ESCALATE / BLOCK -> SafeExecutor -> API\n                                      |\n                                      +-> Presence -> verified human approval -> Decionis re-evaluation\n                                      |\n                                      +-> Decision Dossier -> compounding decision record\n```\n\nAgents can reason, plan, and propose actions. They must not determine whether their own actions are authorized, possess downstream privileged credentials, or choose which trusted handler runs.\n\n## Five-minute demo\n\nRequirements: Node.js 22.14 or later and pnpm 9.\n\n```bash\ngit clone https://github.com/decionis/agent-safe-pipeline.git\ncd agent-safe-pipeline\npnpm install --frozen-lockfile\npnpm --filter @decionis/agent-safe-example-basic demo\n```\n\nThe demos use an explicitly non-production fixture authority. A production integration uses `DecionisGate` and `DecionisGrantVerifier` with server-side credentials.\n\n```ts\nconst captured = intentCapture.capture(agentProposal, trustedContext);\nconst decision = await gate.evaluate(captured);\nconst result = await executor.run(captured, decision);\n```\n\nThe executor accepts a captured intent and a decision. It does not accept an arbitrary callback from the agent. A sealed `ActionRegistry` maps action names to trusted handlers and validates parameters before consuming a single-use grant.\n\n## Golden adversarial demo\n\nOne legitimate path and eight adversarial attempts against the same boundary, offline, in a few seconds, with every expectation asserted:\n\n```bash\npnpm --filter @decionis/agent-safe-example-golden-adversarial demo\n```\n\nA treasury agent proposes a USD 250,000 wire, a remote Chief Risk Officer completes a FIDO2 plus liveness ceremony, and exactly one wire executes. Injected authorization fields, a fabricated ALLOW, an asserted approval, a swapped receipt, a post-approval amount change, a replayed grant, 25 concurrent claims, a shadow observation, and an expired grant all fail to execute. The run exits 0 only when that holds. See [`examples/golden-adversarial-demo`](./examples/golden-adversarial-demo), the bank-audience walkthrough in [`docs/remote-cro-authorization.md`](./docs/remote-cro-authorization.md), and the receipt semantics in [`docs/presence-evidence.md`](./docs/presence-evidence.md).\n\n## From the fixture to Decionis\n\nThe package is used in three stages. Each stage uses the same `IntentCapture`, `ActionRegistry`, and handler code, so nothing is rewritten between them.\n\n| Stage       | Authority                                                     | What it proves                                                                           |\n| ----------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |\n| Development | `createFixtureAuthorityPair` (refuses `NODE_ENV=production`)  | The intent, registry, and executor wiring is correct                                     |\n| Shadow      | `ShadowPipeline` over `DecionisGate` with `mode: \"SHADOW\"`    | What Decionis would have decided about actions that already run; no grant is ever issued |\n| Enforcement | `DecionisGate` plus `DecionisGrantVerifier` in `SafeExecutor` | Nothing runs without an independent decision and a consumed single-use grant             |\n\nDecionis credentials belong only in the trusted executor process, never in the agent runtime:\n\n```text\nDECIONIS_API_URL=https://api.decionis.com\nDECIONIS_API_KEY=server-side-secret\n```\n\nSee the [package README](./packages/pipeline/README.md) for the complete enforcement example and [`docs/shadow-mode.md`](./docs/shadow-mode.md) for the shadow rollout path.\n\n## Repository map\n\n- [`packages/pipeline`](./packages/pipeline) — `IntentCapture`, `DecionisGate`, Presence coordination, and `SafeExecutor`.\n- [`examples/golden-adversarial-demo`](./examples/golden-adversarial-demo) — the self-checking proof: one golden path, eight attacks, zero unauthorized executions.\n- [`examples/basic-agent`](./examples/basic-agent) — the smallest BLOCK flow.\n- [`examples/shopify-refund-agent`](./examples/shopify-refund-agent) — amount-based ALLOW / ESCALATE / BLOCK.\n- [`examples/github-deploy-agent`](./examples/github-deploy-agent) — environment and force-push controls.\n- [`examples/procurement-agent`](./examples/procurement-agent) — an in-budget software request held when existing tools still have user capacity.\n- [`examples/mcp-tool-gate`](./examples/mcp-tool-gate) — a real stdio MCP server with a governed tool.\n- [`examples/presence-live-approval`](./examples/presence-live-approval) — a Presence-bound enforcement against the real services with a FIDO2 or FIDO2-plus-liveness ceremony; needs real credentials.\n- [`examples/presence-managed-approval`](./examples/presence-managed-approval) — Decionis-managed Presence orchestration with Decionis-only polling and no Presence credential in the executor.\n- [`ARCHITECTURE.md`](./ARCHITECTURE.md) and [`THREAT-MODEL.md`](./THREAT-MODEL.md) — trust boundary and abuse analysis.\n- [`OPEN-CORE.md`](./OPEN-CORE.md) — what is Apache-2.0 here, what Decionis operates, and the seam between them.\n- [`docs/`](./docs) — concepts, execution intent, outcomes, human approval, [Presence Evidence semantics](./docs/presence-evidence.md), the [remote CRO sequence](./docs/remote-cro-authorization.md), shadow mode, Decision Dossiers, trust boundary, and assurance notes.\n- [`conformance/agent-safe-intent-v1.json`](./conformance/agent-safe-intent-v1.json) — portable canonical-hash test vector.\n- [`conformance/vectors/`](./conformance/vectors/) — edge-case canonical-hash vectors (Unicode/astral, NFC vs NFD, negative zero, fractional/exponent numbers, nested arrays, UTF-16 key sort order), auto-discovered by the conformance test.\n- [`dossiers/`](./dossiers/) — reproducible synthetic Decision Dossier corpus with canonical bytes, SHA-256 digests, Ed25519 signatures, and a deliberately published corpus key.\n- [`tests/integration/contract/`](./tests/integration/contract/) — loopback Decionis and Presence stubs that exercise the packed package's complete wire contract over real HTTP.\n- [`FIXTURE-PROVENANCE.md`](./FIXTURE-PROVENANCE.md) — origin and permitted use of every fixture family.\n- [`DEPENDENCY-LICENSES.md`](./DEPENDENCY-LICENSES.md) — generated inventory method and platform-conditional dependency notes.\n- [`SECURITY-EVIDENCE.md`](./SECURITY-EVIDENCE.md) — control-to-artifact evidence map and published gaps.\n- [`PUBLICATION-SIGNOFFS.md`](./PUBLICATION-SIGNOFFS.md) — human decisions that automation cannot make.\n\n## Production invariants\n\n1. Agent input contains only the proposed action, target, and parameters. Tenant, actor, downstream target, and credentials come from trusted runtime configuration.\n2. The exact canonical intent is hashed and expires quickly.\n3. Decionis independently decides. Network errors, malformed responses, missing grants, or binding mismatches fail closed.\n4. Presence proves a human approved that exact intent; Presence never directly authorizes execution. Decionis verifies the receipt and re-evaluates policy.\n5. The grant is bound to the intent, decision, audience, and expiry and is claimed atomically before the handler runs; the attempt outcome is finalized with the authority afterwards as evidence, never as authority.\n6. Downstream credentials exist only behind the trusted executor.\n7. Every decision is evidence-bearing. An ALLOW whose response lacks a dossier identifier or grant is refused as non-executable, and an executed result retains its consumed `{decisionId, dossierId, grantId}` binding. A dossier identifier is never an execution credential.\n\nPresence supports two explicit integration levels. In DIRECT mode, the trusted executor coordinates\nPresence and returns the receipt reference to Decionis. In MANAGED mode, the executor asks Decionis\nto orchestrate Presence and polls Decionis for a terminal status. Both modes require independently\nsigned Presence evidence, exact-intent verification, current-policy re-evaluation, and the same\nclaim-before-handler grant path. Invitation delivery and Presence evidence are never execution\nauthority, and approval cannot revive a five-minute intent after it expires.\n\nSee [`docs/trust-boundary.md`](./docs/trust-boundary.md) before integrating a real downstream API.\n\n## Decision record\n\nThe Execution Authority architecture has two load-bearing properties. Position on the execution path creates control: nothing runs without an independent decision at the moment of action. The evidence record creates accountability that compounds: every decision adds to an auditable history of what was authorized, under which policy, on whose approval.\n\nEvery Decionis evaluation is recorded as a Decision Dossier, and each `GateDecision` returns the `decisionId` and `dossierId` of that record. Escalations attach the verified Presence `receiptDossierId`, and every executed action returns the consumed grant's `{decisionId, dossierId, grantId, intentHash}` binding, so execution results correlate to their evidence without extra bookkeeping. In the research vocabulary, dossiers compound into a Decision Chain: tamper-evident lineage linking evaluation, approval, and execution evidence across workflows. Decionis maintains that record; this repository's contribution is that execution cannot bypass it.\n\nTreat dossier identifiers as audit and support references, never as execution credentials — see [`docs/decision-dossiers.md`](./docs/decision-dossiers.md).\n\n## Research and specifications\n\nDecionis Research defines the Execution Authority architecture, this repository demonstrates it as runnable, tested code, and the Decionis platform operates it as a hosted authority. The provenance chain is research paper -> protocol contract -> reference implementation (this repository) -> production service.\n\nPublished research:\n\n- 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) · [Research index](https://decionis.com/research).\n\nCompanion notes on the Execution Authority model, the authorization protocol, Presence-verified human approval, and Decision Dossiers are in preparation. Following this repository's discovery rules, a publication link is added here only after its canonical article resolves publicly.\n\n| Research concept              | Implementation in this repository                                                                                                                                                                  |\n| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Execution Authority boundary  | `IntentCapture` -> `DecionisGate` -> `SafeExecutor`                                                                                                                                                |\n| Protocol contract             | Exactly the Decionis `ExecutionAuthorityRequest` and `ExecutionIntentBinding` contract on the wire; `DecionisGate` and `DecionisGrantVerifier` claim and finalize against the published OpenAPI    |\n| Intent integrity              | `CanonicalIntentHasher` plus the [`conformance/`](./conformance) hash vectors                                                                                                                      |\n| Human approval evidence       | DIRECT `PresenceApprovalCoordinator` or MANAGED `DecionisGate` polling; both require Presence receipt verification and Decionis re-evaluation                                                      |\n| Trusted execution             | Sealed `ActionRegistry` and atomic single-use grant consumption in `SafeExecutor`                                                                                                                  |\n| Decision evidence             | `decisionId` and `dossierId` on every gate decision; executed results retain the consumed-grant binding                                                                                            |\n| Failure semantics             | Fail-closed production invariants and [`THREAT-MODEL.md`](./THREAT-MODEL.md)                                                                                                                       |\n| Observation without authority | `ShadowPipeline` over a `SHADOW`-mode gate: failure-isolated, bounded, grant-free, and rejected by `SafeExecutor`; see [`docs/shadow-mode.md`](./docs/shadow-mode.md)                              |\n| MCP governance                | [`examples/mcp-tool-gate`](./examples/mcp-tool-gate)                                                                                                                                               |\n| Operational patterns          | [`examples/shopify-refund-agent`](./examples/shopify-refund-agent), [`examples/github-deploy-agent`](./examples/github-deploy-agent), [`examples/procurement-agent`](./examples/procurement-agent) |\n\n## Open core\n\nEverything in this 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. The seam is two exported interfaces, `DecisionAuthority` and `AuthorizationVerifier`, plus a published OpenAPI contract; the library checks no plan, key, or entitlement. [`OPEN-CORE.md`](./OPEN-CORE.md) states the boundary and the commitments that keep it stable.\n\n## Public-repository policy\n\nThis is intended to be the public, canonical reference implementation. It should not be mirrored: mirrors create contract and security-fix drift. Public content belongs here—architecture, package source, synthetic policies, and runnable examples. Production policy bundles, customer data, credentials, internal infrastructure, and private incident material do not.\n\nDecionis remains the authoritative decision service, Presence remains the human-verification service, and their server internals can evolve independently behind versioned contracts.\n\n## Verify Decision Dossiers\n\nThe repository-owned [`dossiers/`](./dossiers/) corpus checks the offline verifier against synthetic\n`ALLOW`, `BLOCK`, and `ESCALATE` proof bundles, including an owned-workspace, execution-bound\nvector. Its private signing key is intentionally public so anyone can regenerate the corpus; it is\nnot a production credential and cannot establish that a production dossier is authentic.\n\n```bash\npnpm exec decionis-verify \\\n  --file dossiers/vectors/allow.json \\\n  --jwks dossiers/corpus-jwks.json\n```\n\nTo verify the distinct production claim, obtain a live dossier through an authorized route and run\nthe pinned verifier against the live JWKS without committing the dossier:\n\n```bash\nnpx -y @decionis/verify@0.2.0 \\\n  --file /absolute/path/to/live-decision-dossier.json \\\n  --jwks https://api.decionis.com/v1/.well-known/decision-dossier-jwks.json\n```\n\nSee the [corpus README](./dossiers/README.md) for regeneration, provenance, expected failures, and\nthe trust boundary between synthetic conformance and production verification.\n\n## Status\n\nThe package is published as [`@decionis/agent-safe-pipeline`](https://www.npmjs.com/package/@decionis/agent-safe-pipeline). Install the latest stable release with `npm install @decionis/agent-safe-pipeline`; prereleases require an explicit version such as `npm install @decionis/agent-safe-pipeline@0.1.3-rc.2`.\n\nArchived releases are citable under [Zenodo concept DOI\n`10.5281/zenodo.22312955`](https://doi.org/10.5281/zenodo.22312955). The\n[release-metadata contract](./docs/zenodo-release-metadata.md) explains the\npreflight checks, version-DOI verification, and human publication boundary.\n\n## Development\n\n```bash\npnpm install --frozen-lockfile\npnpm verify\n```\n\n`pnpm verify` enforces formatting, Markdown lint, fixture conventions, canonical licensing, separate\nproduction/toolchain audits, deterministic performance tests, types, tests, and coverage thresholds\nof 90% for lines/functions/statements and 85% for branches. `pnpm mutation` checks that\ntrust-boundary tests kill deliberate code mutations. `pnpm fuzz` runs deterministic property tests\nagainst canonical intent handling; CI also runs them weekly with a larger bounded sample.\nInstallation activates the repository's `simple-git-hooks` pre-commit guardrails.\n\n### Fixture provenance and loopback origins\n\nEvery fixture-bearing file is listed in [`fixtures/manifest.json`](./fixtures/manifest.json) and\nchecked by `pnpm fixture:check`: the unit tests under `packages/pipeline/test`, example sources,\nconformance vectors, the dossier corpus, synthetic policies, and the integration harness under\n`tests/integration`. The gate requires synthetic identities (`synthetic-` or `fixture_` prefixes,\ntenants in the reserved UUID block) and parses every URL-shaped literal it finds, which must resolve\nto `localhost`, `127.0.0.1`, `example.com`, or a `.example` or `.invalid` domain. Nothing in the\ntests, examples, or harness reaches the network beyond loopback.\n\nTwo consequences matter when you add or evaluate tests:\n\n- Loopback stubs bind to `127.0.0.1` on an ephemeral port and build their base URL from a plain\n  string constant, `const LOOPBACK_ORIGIN = \"http://127.0.0.1\"`, appending the port separately. A\n  template literal that interpolates inside the URL, such as `` `http://127.0.0.1:${port}` ``, is\n  read by the gate as literal text and rejected as an invalid URL. That is deliberate: the gate does\n  not guess what an interpolated host would resolve to.\n- A new fixture-bearing file needs its manifest entry in the same change. Discovery uses\n  `git ls-files`, so an untracked file is invisible to the gate until it is staged, and the manifest\n  and discovery must match exactly.\n\nSee [`FIXTURE-PROVENANCE.md`](./FIXTURE-PROVENANCE.md) for the full construction rules and\n[`tests/integration/contract/`](./tests/integration/contract/) for the loopback harness that\nfollows them.\n\nApache-2.0 licensed. See [`LICENSE`](./LICENSE), [`TRADEMARKS.md`](./TRADEMARKS.md), [`SECURITY.md`](./SECURITY.md), and [`CONTRIBUTING.md`](./CONTRIBUTING.md). Report suspected vulnerabilities through [GitHub's private advisory form](https://github.com/decionis/agent-safe-pipeline/security/advisories/new), not a public issue.\n",
  "bytes": 20489,
  "sha": "e6249c41a61c3315e02298827753da4b03fb11308060f5238ee337c0c50bc3e3",
  "repo_slug": "decionis/agent-safe-pipeline",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_decionis_mcp_9f04f72f/readme"
}