offline-verifiable authorization and execution receipts for AI and high-consequence software actions

The trust layer for AI and high-consequence software actions. Every decision is traceable, exportable, and independently verifiable.

TypeScript + Python reference · pnpm · Append-only chain · Offline verification · No database required

Decision Passport v0.7.0 is implemented core-first in this repository.

For v0.7.0, this repository is the canonical source for:

1. model semantics
2. verifier semantics
3. fixture and golden output corpus
4. protocol/spec documentation

Primary v0.7.0 scope:

1. DecisionTrail
2. RuntimeClaim
3. OutcomeBinding
4. upgraded verifier semantics for authorization, runtime claim, and outcome linkage

Explicitly out of v0.7.0 scope:

1. hosted guard runtime implementation
2. enterprise-only control plane surfaces
3. broad signing/profile expansion without complete verifier and fixture coverage
4. UI-first feature expansion

Sovereign and OpenClaw Lite can adopt v0.7.0 semantics after they are locked in core. They do not define the canonical model for this release.

This section is normative for what this repository can prove today.

Spec-defined but not fully implemented in this release:

1. full runtime enforcement service behavior and orchestration
2. broad signing and key-management profiles
3. external notarization or identity attestation workflows

Future work (0.8.x or later):

1. hosted guard runtime and replay-state infrastructure
2. richer execution side-effect graph surfaces
3. expanded signing/profile ecosystem with complete parity fixtures

1. A bundle's record hashes, chain links, and manifest chain hash are internally consistent.
2. Payload tampering and chain mutation are detected by verification.
3. Verification runs offline with no database, API key, or cloud dependency.
4. v0.7.0 verifier semantics classify runtime-claim, outcome-linkage, revocation/supersession, and trail-linkage states on supported bundle surfaces.

1. Runtime policy enforcement at execution time.
2. Storage-level immutability by itself.
3. Who authored a bundle, unless a separate signing layer is used.
4. That a hosted guard executor blocked or allowed execution in real time.

Use this repository when you need portable, offline-checkable proof artifacts for AI action history.

Use stronger infrastructure when you need execution claims, fail-closed guard enforcement, replay protection, tenant isolation, signed bundles, or regulated deployment controls.

Logs and traces are operational telemetry. Decision Passport Core is a verifiable proof format with canonical hashing and chain integrity checks. Observability helps you inspect behavior, this repo helps you verify integrity of exported proof artifacts.

git clone https://github.com/brigalss-a/decision-passport-core.git
cd decision-passport-core
pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm verify-demo

No database, API key, or cloud account required.

Use this exact sequence for a fast, trust-focused validation pass:

pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm conformance
pnpm verify-demo
pnpm example:smoke
python -m decision_passport.verify examples/reference-integrations/webhook-approval-receipt.bundle.json
python -m decision_passport.verify examples/reference-integrations/agent-tool-execution-receipt.bundle.json

If all commands pass, you have validated:

1. Core verifier correctness.
2. TypeScript/Python conformance parity.
3. Deterministic reference-integration behavior.
4. Auditor-grade output paths on canonical bundle surfaces.

Python reference implementation is available in python/decision_passport_py and mirrors the protocol surface for offline create and verify flows.

What this verifies:

1. The hash chain engine builds cleanly.
2. A decision chain can be created and exported.
3. The offline verifier confirms PASS when hashes and links are intact.
4. A tampered bundle is rejected as FAIL.
5. HTML verification reports are generated in artifacts/.
6. Current local validation for v0.7.0 release prep requires all release gates in docs/release-checklist.md to pass, including TypeScript suite, conformance parity, demo/reference checks, and Python verifier checks on reference bundles.

cd python/decision_passport_py
pip install -e .
python -m unittest discover -s tests -v
python -m decision_passport.verify ../../fixtures/valid-bundle.json

Serve the repo and open apps/verifier-web/. Drag any bundle JSON onto the page for client-side verification.

npx serve . -l 3000
# Open http://localhost:3000/apps/verifier-web/

Decision Passport is an append-only, hash-linked record system for AI agent actions.

Every material action your AI agent performs, such as a recommendation, an approval decision, or an execution result, is stamped into a tamper-evident chain. That chain is bundled and can be independently verified offline.

This repository provides deterministic verification semantics through canonical hashing and explicit chain rules. Record creation still uses runtime UUID and timestamp values, so fixture regeneration is not byte-identical unless controlled inputs are used.

AI agent runs, tool calls happen, results returned, nothing verifiable is exported.
Hard to explain what was decided.
Hard to prove what executed.
Hard to support external review.

AI agent runs, each material step is stamped into an append-only chain.
Bundle exported as portable JSON proof.
Verifier returns PASS when integrity checks succeed.
External reviewers can independently verify chain integrity.

import { createRecord, createManifest } from '@decision-passport/core';
import { verifyBasicBundle } from '@decision-passport/verifier-basic';

const chainId = `session-${Date.now()}`;

// 1. Stamp each action
const record1 = createRecord({
  chainId,
  lastRecord: null,
  actorId: 'claude-agent-01',
  actorType: 'ai_agent',
  actionType: 'AI_RECOMMENDATION',
  payload: {
    rationale: 'Policy v2.1, action within approved risk threshold',
    confidence: 0.94,
    policy_version: 'v2.1'
  }
});

const record2 = createRecord({
  chainId,
  lastRecord: record1,
  actorId: '[email protected]',
  actorType: 'human',
  actionType: 'HUMAN_APPROVAL_GRANTED',
  payload: { note: 'Reviewed and approved' }
});

const record3 = createRecord({
  chainId,
  lastRecord: record2,
  actorId: 'claude-agent-01',
  actorType: 'ai_agent',
  actionType: 'EXECUTION_SUCCEEDED',
  payload: { result_summary: 'Email delivered', message_id: 'msg-8821' }
});

// 2. Export a portable proof bundle
const records = [record1, record2, record3];
const bundle = {
  bundle_version: '1.4-basic' as const,
  exported_at_utc: new Date().toISOString(),
  passport_records: records,
  manifest: createManifest(records)
};

// 3. Verify independently (no network, no database)
const result = verifyBasicBundle(bundle);
console.log(result.status); // 'PASS'

decision-passport-core/
├── packages/
│   ├── core/               ← Hash chain engine
│   │   ├── src/types.ts         ActionType, PassportRecord, ChainManifest, BasicProofBundle
│   │   ├── src/chain.ts         createRecord(), verifyChain(), assertValidChain()
│   │   ├── src/hashing.ts       hashCanonical(), hashPayload(): SHA-256, deterministic
│   │   ├── src/canonical.ts     Canonical JSON serialiser (no duplicate hashing)
│   │   ├── src/manifest.ts      createManifest()
│   │   ├── src/explain-tamper.ts explainTamper(): what changed and why it broke
│   │   ├── src/bundle-diff.ts   diffBundles(): compare two bundles field by field
│   │   └── src/errors.ts        ChainValidationError
│   │
│   ├── verifier-basic/     ← Offline bundle verifier
│   │   ├── src/verify-bundle.ts   verifyBundle(): zero external deps
│   │   └── src/html-report.ts     renderVerificationReport(): static HTML export
│   │
│   └── demo/               ← Runnable demo
│       └── src/index.ts         Full demo: record → export → verify → PASS
│
├── apps/
│   └── verifier-web/       ← Browser verifier (drag-and-drop, zero dependencies)
│
├── fixtures/               ← Deterministic conformance fixtures
│   ├── valid-bundle.json
│   ├── tampered-bundle.json
│   ├── broken-prev-hash.json
│   ├── wrong-sequence.json
│   ├── wrong-chain-hash.json
│   ├── malformed-bundle.json
│   ├── unsupported-version.json
│   └── compatible-optional-metadata.json
│
├── python/
│   └── decision_passport_py/    ← Python reference implementation (offline-first)
│
└── artifacts/              ← Generated by verify-demo
    ├── verification-report.html
    ├── tampered-report.html
    └── verification-summary.json

PassportRecord[0]        PassportRecord[1]        PassportRecord[2]
─────────────────        ─────────────────        ─────────────────
id: uuid                 id: uuid                 id: uuid
sequence: 0              sequence: 1              sequence: 2
prev_hash: GENESIS       prev_hash: hash[0]       prev_hash: hash[1]
payload_hash: sha256     payload_hash: sha256     payload_hash: sha256
record_hash: sha256 ──►  record_hash: sha256 ──►  record_hash: sha256
                                                          │
                                                          ▼
                                               ChainManifest
                                               chain_hash = record_hash[2]
                                                          │
                                                          ▼
                                               BasicProofBundle
                                               (portable · verifiable · exportable)

Tampering with any single byte in any record breaks every subsequent hash. The chain becomes self-auditing.

The atomic unit of trust. Every record contains:

type ActionType =
  | 'AI_RECOMMENDATION'       // Agent produces a decision
  | 'HUMAN_APPROVAL_GRANTED'  // Human approves
  | 'HUMAN_APPROVAL_REJECTED' // Human rejects
  | 'POLICY_APPROVAL_GRANTED' // Policy engine approves
  | 'EXECUTION_PENDING'       // Action queued
  | 'EXECUTION_SUCCEEDED'     // Action completed successfully
  | 'EXECUTION_FAILED'        // Action failed
  | 'EXECUTION_ABORTED'       // Action cancelled
  | 'HUMAN_OVERRIDE'          // Human overrides system decision
  | 'POLICY_EXCEPTION';       // Exception granted

Chain summary: chain_id, record_count, first_record_id, last_record_id, chain_hash.

The portable export format (bundle_version: "1.4-basic"). Contains all records + manifest. Self-contained, verifiable offline.

import { verifyBasicBundle } from '@decision-passport/verifier-basic';
import fs from 'fs';

const bundle = JSON.parse(fs.readFileSync('./bundle.json', 'utf8'));
const result = verifyBasicBundle(bundle);

console.log(result.status);  // 'PASS' | 'FAIL'
console.log(result.summary);      // short human summary
console.log(result.reasonCodes);  // stable machine-readable reason codes
console.log(result.checks);       // array of individual check results
console.log(result.nextSteps);    // concise triage guidance on FAIL

A CLI verifier is also available at packages/verifier-basic/src/cli.ts:

pnpm tsx packages/verifier-basic/src/cli.ts ./bundle.json

Compare two bundles to see exactly what changed:

pnpm diff-bundles fixtures/valid-bundle.json fixtures/tampered-bundle.json

Or use the API:

import { diffBundles } from '@decision-passport/core';

const result = diffBundles(bundleA, bundleB);
console.log(result.identical); // false
console.log(result.summary);   // '1 difference(s) found: 1 field change(s).'
console.log(result.findings);  // structured diff findings

The Python package in python/decision_passport_py is protocol-first and offline-only, not an API wrapper.

cd python/decision_passport_py
pip install -e .
python -m decision_passport.verify ../../fixtures/valid-bundle.json
python -m decision_passport.diff ../../fixtures/valid-bundle.json ../../fixtures/tampered-bundle.json

The verifier checks:

1. Every record_hash matches the recomputed deterministic hash
2. Every prev_hash correctly chains to the previous record
3. Sequence numbers are gapless and correct
4. chain_hash in the manifest matches the terminal record

If the input is malformed, verification returns FAIL with a structure reason code. If integrity checks fail, verification returns FAIL with integrity reason codes.

• Schema and versioning: bundle structure, record fields, hashing rules, evolution guidance
• Compatibility matrix: which tools work with which formats
• Verifier compatibility promise: 12-month supported/deprecated/unsupported policy
• Verifier auditor output: deterministic verdict/code/location/reason/remediation_hint contract
• Protocol conformance: normative verifier checks and fixture outcomes
• Conformance manifest: machine-readable expected verdict map for canonical fixtures
• JSON Schemas: machine-readable schemas for BasicProofBundle, ChainManifest, PassportRecord
• Release verification: how to verify a published release locally
• Release provenance: official release artifacts, 3-minute local verification, and trust limitations
• Reference integrations: two ultra-small end-to-end examples (webhook approval receipt and agent/tool execution receipt)
• Append-only guarantees: what the protocol enforces, what verification detects, storage-level limits
• Bundle Diff: how to compare two bundles, generate diff artifacts, and interpret findings

• Boundaries: exact scope, non-goals, and trust boundary edges
• Threat model: addressed threats, assumptions, and residual risk
• Verification model: PASS and FAIL semantics, safe interpretation
• Tamper cases: concrete failure patterns and investigation guidance

Core is free and open source.

Hosted, business, enterprise, and sovereign deployment options are available on request.

Contact: [email protected]

• Core hash chain engine
• BasicProofBundle export
• Offline verifier (zero-dependency)
• CLI verifier
• Demo with sample data
• Tamper explainer (explainTamper(): what changed and why it broke)
• HTML verification report export
• Browser verifier (drag-and-drop, client-side only)
• Deterministic valid + tampered fixtures
• ASCII chain visualiser
• Policy version binding helpers
• Redaction mode (metadata-only and hash-only bundles)
• Bundle diff utility (diffBundles(): compare two bundles)
• OpenClaw Lite bridge (see decision-passport-openclaw-lite)
• Trusted timestamping integration (RFC 3161)

This repository is the public protocol layer. The full ecosystem:

To keep this repository technically honest, we keep public feedback channels focused on reproducible verifier and conformance evidence.

• Adoption and validation signals: docs/adoption-signals.md
• Verifier contract feedback template: .github/ISSUE_TEMPLATE/verifier-contract-feedback.md
• Conformance/integration feedback template: .github/ISSUE_TEMPLATE/conformance-or-integration-feedback.md

When reporting feedback, include exact commands, fixture/bundle inputs, and expected vs actual verifier outputs.

Contributions to the public protocol are welcome.

Fork the repository on GitHub, then run:

git clone https://github.com/YOUR_USERNAME/decision-passport-core.git
cd decision-passport-core
git checkout -b feat/my-improvement
pnpm install --frozen-lockfile
pnpm test

Then open a pull request with a clear description of what changed and why.

Apache-2.0. See full text in LICENSE file.

You may use, modify, and distribute this software freely, including in commercial products. The express patent grant protects you and your users. Product names, logos, and hosted offerings remain the intellectual property of Bespoke Champions League Ltd.

Decision Passport is built and maintained by Bespoke Champions League Ltd, London, United Kingdom.

It powers the trust layer inside Bespea. Decision Passport emerged from a real-world problem: AI systems making material delivery, execution, and approval decisions without a portable, verifiable record.

Maintainer: Grigore-Andrei Traistaru Founder [email protected] https://bespea.com