settld 0.1.2 → 0.2.0

package/docs/spec/SettlementReceipt.v1.md

@@ -0,0 +1,63 @@
+# SettlementReceipt.v1
+
+`SettlementReceipt.v1` is the canonical settlement-finality artifact for one `AgentRunSettlement.v1` transition.
+
+It binds money movement and finality to a `SettlementDecisionRecord` (`v1` or `v2`) through `decisionRef`.
+
+## Purpose
+
+- provide an immutable receipt of what settled (`released|refunded`, amounts, rate);
+- capture finality mode/state (`internal_ledger`, `pending|final`);
+- make downstream audit/reputation updates hash-addressable via `receiptHash`.
+
+## Required fields
+
+- `schemaVersion` (const: `SettlementReceipt.v1`)
+- `receiptId`
+- `tenantId`
+- `runId`
+- `settlementId`
+- `decisionRef` (`decisionId`, `decisionHash`)
+- `status`
+- `amountCents`
+- `releasedAmountCents`
+- `refundedAmountCents`
+- `releaseRatePct`
+- `currency`
+- `runStatus`
+- `resolutionEventId`
+- `finalityProvider`
+- `finalityState`
+- `settledAt`
+- `createdAt`
+- `receiptHash`
+
+Optional fields:
+
+- `bindings` (object) mirroring decision-time authorization/request/response binding context:
+  - `authorizationRef`
+  - `token` (`kid`, `sha256`, `expiresAt`)
+  - `request` (`sha256`)
+  - `response` (`status`, `sha256`)
+  - `providerSig` (`required`, `present`, `verified`, `providerKeyId`, `error`)
+  - `reserve` (`adapter`, `mode`, `reserveId`, `status`)
+  - `policyDecisionFingerprint` (`fingerprintVersion`, `policyId`, `policyVersion`, `policyHash`, `verificationMethodHash`, `evaluationHash`)
+
+## Internal finality semantics (`Kernel v0`)
+
+- `finalityProvider` is `internal_ledger`.
+- `finalityState` is:
+  - `pending` while settlement is still `locked`,
+  - `final` after one-way resolution to `released|refunded`.
+
+## Canonicalization and hashing
+
+`receiptHash` is computed over canonical JSON after removing `receiptHash`:
+
+1. canonicalize JSON with RFC 8785 (JCS),
+2. hash canonical UTF-8 bytes using `sha256`,
+3. encode as lowercase hex.
+
+## Schema
+
+See `schemas/SettlementReceipt.v1.schema.json`.

package/docs/spec/SlaDefinition.v1.md

@@ -0,0 +1,24 @@
+# SlaDefinition.v1
+
+`SlaDefinition.v1` defines a deterministic, offline-evaluable set of SLA rules for a JobProof-derived job stream.
+
+In ClosePack bundles, it is stored at `sla/sla_definition.json`.
+
+## Rules (v1)
+
+Rules are a bounded DSL; each rule has:
+
+- `ruleId` — stable identifier (string).
+- `kind` — one of:
+  - `MUST_START_WITHIN_WINDOW`
+  - `MAX_EXECUTION_MS`
+  - `MAX_STALL_MS`
+  - `PROOF_ZONE_COVERAGE_MIN_PCT`
+
+Rule semantics are evaluated over:
+
+- the embedded JobProof event stream (via the embedded Invoice bundle)
+- the derived job state / proof result emitted in the stream (`PROOF_EVALUATED`), when present
+
+No network fetches and no evidence bytes are required.
+

package/docs/spec/SlaEvaluation.v1.md

@@ -0,0 +1,12 @@
+# SlaEvaluation.v1
+
+`SlaEvaluation.v1` is a deterministic evaluation of `SlaDefinition.v1` against a specific JobProof instance.
+
+In ClosePack bundles, it is stored at `sla/sla_evaluation.json`.
+
+## Determinism contract
+
+If `sla/sla_definition.json` and `sla/sla_evaluation.json` are present, verifiers recompute the evaluation from the embedded JobProof event stream and require **exact match** (canonical JSON) in strict mode.
+
+The evaluation must not depend on external systems or evidence bytes.
+

package/docs/spec/THREAT_MODEL.md

@@ -0,0 +1,113 @@
+# Threat Model (v1)
+
+This document describes **in-scope threats**, **mitigations**, and **residual risks** for Settld’s bundle protocol and verifier.
+
+It is evidence-backed: each mitigation points to the spec and to executable tests/conformance cases.
+
+## Assets (what we protect)
+
+- **Payload integrity**: bundle payload files are immutable once committed.
+- **Bundle completeness**: a verifier can detect selective omission or selective inclusion attacks.
+- **Manifest integrity anchor**: `manifestHash` is the primary content commitment.
+- **Attestation integrity anchor**: `attestationHash` (bundle head attestation) binds receipts to “this exact bundle.”
+- **Signer authorization**: only allowed signers (per governance policy) can sign head attestations and verification reports.
+- **Key lifecycle correctness**: rotation/revocation windows are enforced per policy + timeline rules.
+- **Trust anchor correctness**: governance roots/time authorities are injected out-of-band and validated.
+- **Verifier correctness**: canonicalization + hashing are deterministic and cross-implementation portable.
+
+## Adversaries / threat actors
+
+- **Malicious producer**: creates a bundle intended to mislead downstream users/auditors.
+- **Malicious distributor**: tampers with, reorders, or swaps bundle contents in transit/storage.
+- **Compromised key**: a signing key is stolen or misused.
+- **Malicious verifier environment**: compromised filesystem, dependency, or runtime; attacker attempts to trick hashing/reading.
+- **Confused-deputy CI**: pipelines unintentionally verify in a permissive posture or ignore warnings.
+
+## Threats → mitigations (explicit mapping)
+
+### T1: Payload tampering (modify payload files after bundling)
+
+- **Mitigation**: manifest enumerates file hashes; verifier re-hashes and compares.
+  - Spec: `ProofBundleManifest.v1.md`, `FinancePackBundleManifest.v1.md`
+  - Enforcement:
+    - Job/Month proof: `packages/artifact-verify/src/job-proof-bundle.js:39` (manifest file hashing)
+    - FinancePack: `packages/artifact-verify/src/finance-pack-bundle.js:40` (manifest file hashing)
+  - Evidence:
+    - Conformance: `conformance/v1/cases.json` case `*_strict_fail_manifest_tamper`
+    - Fixtures: `test/verify-fixture-bundles.test.js` (CLI matrix strict-fail tamper cases)
+
+### T2: Mix-and-match (swap a valid report/attestation from bundle A onto bundle B)
+
+- **Mitigation**: verification report is bound to both `manifestHash` and `bundleHeadAttestation.attestationHash`.
+  - Spec: `VerificationReport.v1.md`, `BundleHeadAttestation.v1.md`
+  - Enforcement:
+    - Proof report subject manifest binding: `packages/artifact-verify/src/job-proof-bundle.js:148`–`174`
+    - Proof report head attestation binding: `packages/artifact-verify/src/job-proof-bundle.js:176`–`184`
+  - Evidence:
+    - Fixtures: `test/verify-fixture-bundles.test.js` includes strict binding mismatch cases
+
+### T3: Replay (present old but valid artifacts after key revocation / outside validity)
+
+- **Mitigation**: key validity windows + prospective revocation timeline enforcement; optional trustworthy `timestampProof` influences effective signing time.
+  - Spec: `RevocationList.v1.md`, `TimestampProof.v1.md`, `GovernancePolicy.v2.md`
+  - Enforcement:
+    - Head attestation timeline enforcement: `packages/artifact-verify/src/job-proof-bundle.js:1152`–`1163`
+    - Verification report timeline enforcement (proof bundles): `packages/artifact-verify/src/job-proof-bundle.js:215`–`233`
+  - Evidence:
+    - Tests: `test/job-proof-bundle-verify-strict-revocation-timeproof.test.js`
+
+### T4: Downgrade (force non-strict / accept legacy surfaces silently)
+
+- **Mitigation**: strict/non-strict is explicit; non-strict “warn + continue” is coded with stable warning codes; `--fail-on-warnings` can harden non-strict deployments.
+  - Spec: `STRICTNESS.md`, `WARNINGS.md`, `VerifyCliOutput.v1.md`
+  - Enforcement:
+    - Missing report strict vs warn: `docs/spec/STRICTNESS.md` and verifier implementations.
+    - CLI warning gating: `packages/artifact-verify/bin/settld-verify.js:112`–`121`
+  - Evidence:
+    - Conformance: `conformance/v1/cases.json` case `financepack_strict_fail_on_warnings_tool_version_unknown`
+
+### T5: Trust-root substitution (attacker provides wrong governance root keys)
+
+- **Mitigation**: verifier requires out-of-band trust roots in strict mode; wrong roots fail signature/trust checks.
+  - Spec: `TRUST_ANCHORS.md`
+  - Enforcement:
+    - Strict requires trusted governance root keys: `packages/artifact-verify/src/job-proof-bundle.js:1338` and `packages/artifact-verify/src/finance-pack-bundle.js:539`
+  - Evidence:
+    - Conformance: `conformance/v1/cases.json` cases `financepack_strict_fail_trust_roots_missing` and `financepack_strict_fail_trust_roots_wrong`
+
+### T6: Path traversal / symlink exfiltration (verifier reads outside-bundle files)
+
+- **Mitigation**: manifest entry paths are validated as bundle-relative; `..` and absolute paths are rejected; symlinks are forbidden for manifest-listed files.
+  - Spec: `REFERENCE_VERIFIER_BEHAVIOR.md`
+  - Enforcement:
+    - Pre-validate manifest entries before any hash-binding: `packages/artifact-verify/src/bundle-path.js:13`–`53`
+    - Enforced pre-validation order:
+      - Proof bundles: `packages/artifact-verify/src/job-proof-bundle.js:1247`–`1250`
+      - FinancePack: `packages/artifact-verify/src/finance-pack-bundle.js:460`–`463`
+    - Symlink refusal:
+      - Proof bundles: `packages/artifact-verify/src/job-proof-bundle.js:75`
+      - FinancePack: `packages/artifact-verify/src/finance-pack-bundle.js:71`
+  - Evidence:
+    - Conformance: `conformance/v1/cases.json` cases `security_manifest_path_traversal`, `security_manifest_duplicate_paths`, `security_bundle_symlink_outside`
+
+### T7: Algorithm confusion / weak algorithms
+
+- **Mitigation**: governance policy carries an allowed-algorithm list; verifier rejects policies that don’t allow required algorithms.
+  - Spec: `GovernancePolicy.v2.md`, `CRYPTOGRAPHY.md`
+  - Enforcement:
+    - Allowed algorithms check: `packages/artifact-verify/src/governance-policy.js:10`–`17` and policy signature verification paths.
+  - Evidence:
+    - Unit/fixture coverage through strict verification test suite.
+
+## Assumptions (must be true for guarantees to hold)
+
+- The verifier process can read bundle files and trust anchors from a reasonably honest filesystem (see `VERIFIER_ENVIRONMENT.md`).
+- Trusted governance roots and (optionally) time authorities are distributed out-of-band and are pinned/managed per `TRUST_ANCHORS.md`.
+- Signature private keys are protected; if keys are compromised, the protocol relies on revocation/rotation to limit blast radius.
+
+## Residual risks (explicitly not solved yet)
+
+- **Compromised build pipeline / dependency supply chain**: a malicious verifier build can lie. Mitigation lives in release discipline + SBOM + reproducible builds (outside v1 protocol core).
+- **Compromised OS or kernel**: an attacker controlling the runtime can tamper with file reads.
+- **UI/operational misuse**: running non-strict without gating warnings may be unacceptable in regulated workflows (see `VERIFIER_ENVIRONMENT.md`).
+

package/docs/spec/TOOL_PROVENANCE.md

@@ -0,0 +1,30 @@
+# Tool provenance (version + commit)
+
+Settld surfaces tool identity in:
+
+- `VerificationReport.v1.tool` (producer/receipt provenance)
+- `VerifyCliOutput.v1.tool` (verifier CLI provenance)
+
+## Commit derivation (best-effort)
+
+When a commit/build identifier is not explicitly provided by the caller, tools try these environment variables in order:
+
+1. `SETTLD_COMMIT_SHA`
+2. `PROXY_BUILD` (Docker build arg often mapped from `GIT_SHA`)
+3. `GIT_SHA`
+4. `GITHUB_SHA`
+
+Accepted values: lowercase hex `[0-9a-f]{7,64}` (normalized to lowercase).
+
+If no valid value is available, tools omit `tool.commit` (or set it to `null` in CLI output) and producers emit `TOOL_COMMIT_UNKNOWN`.
+
+## Version derivation (best-effort)
+
+When a version is not explicitly provided by the caller, tools try:
+
+1. `SETTLD_VERSION` (if set in the environment)
+2. Repo/service version stamp from `SETTLD_VERSION` file (when present in the working directory)
+3. Package `package.json` version (for published tools like `settld-verify`)
+
+If no value is available, tools omit `tool.version` (or set it to `null` in CLI output) and producers emit `TOOL_VERSION_UNKNOWN`.
+

package/docs/spec/TRUST_ANCHORS.md

@@ -0,0 +1,84 @@
+# Trust anchors (out-of-band)
+
+Strict verification requires **trusted root keys** that are *not* bundled inside artifacts.
+
+This is intentional: bundling trust anchors inside the thing being verified would create a trust-loop.
+
+## Release authenticity trust (separate domain)
+
+Settld release authenticity (verifying the tool distribution artifacts themselves) uses a **separate trust domain** from bundle verification.
+
+- Release trust roots live in `trust/release-trust.json` (see `ReleaseTrust.v2.md`).
+- Release verification CLI: `settld-release verify --dir <release-assets-dir> --trust-file trust/release-trust.json --format json`
+
+Do not mix release signing keys with bundle/governance signing keys (different purpose, different blast radius).
+
+## Governance roots (required for strict)
+
+`GovernancePolicy.v2` and `RevocationList.v1` are signed by governance root keys that must be trusted out-of-band.
+
+Verifier input mechanism:
+
+- `SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON`
+  - JSON object mapping `keyId -> publicKeyPem`
+  - required for strict verification
+
+Recommended operational posture:
+
+- Store the trust roots JSON (or a `trust.json` file that contains it) in version control.
+- Distribute updates via PR + review (treat as a security-sensitive change).
+- Pin tool versions in CI (see `docs/spec/VERSIONING.md`) so a verification receipt can be mapped to a stable tool build.
+- For regulated workflows: run strict mode and gate on warnings (`--fail-on-warnings`) when policy requires it (see `STRICTNESS.md` and `WARNINGS.md`).
+
+## Buyer pricing signer keys (required for strict InvoiceBundle pricing terms)
+
+Invoice bundles may include buyer-approved pricing terms via `pricing/pricing_matrix_signatures.json` (`PricingMatrixSignatures.*`).
+
+Verifier input mechanism:
+
+- `SETTLD_TRUSTED_PRICING_SIGNER_KEYS_JSON`
+  - JSON object mapping `keyId -> publicKeyPem`
+  - required to validate buyer pricing signatures in strict mode
+
+Optional restriction:
+
+- `SETTLD_TRUSTED_PRICING_SIGNER_KEY_IDS_JSON`
+  - JSON array of allowed `keyId` strings
+  - when set and non-empty, only signatures by these key IDs are treated as trusted (even if additional keys are present in `SETTLD_TRUSTED_PRICING_SIGNER_KEYS_JSON`)
+
+Do not overload governance roots: pricing signer trust is a separate trust set with a distinct purpose and blast radius.
+
+## Buyer decision signer keys (required to verify SettlementDecisionReport)
+
+Buyer approval/hold receipts (`SettlementDecisionReport.v1`) are signed and must be verified under a buyer-controlled trust set.
+
+Verifier input mechanism:
+
+- `SETTLD_TRUSTED_SETTLEMENT_DECISION_SIGNER_KEYS_JSON`
+  - JSON object mapping `keyId -> publicKeyPem`
+  - required to validate settlement decision report signatures
+
+## Time authorities (required only when needed)
+
+Bundles may include `timestampProof` objects that require a verifier-trusted time authority key.
+
+Verifier input mechanism:
+
+- `SETTLD_TRUSTED_TIME_AUTHORITY_KEYS_JSON`
+  - JSON object mapping `keyId -> publicKeyPem`
+  - required only when verifying a timestamp proof that must be trusted in strict mode
+
+## Fixture corpus convention
+
+The committed end-to-end fixtures under `test/fixtures/bundles/v1/**` include a `trust.json` file that contains the trusted keys used by tests.
+
+The CLI fixture harness reads that file and injects the corresponding env vars when running `settld-verify` against fixtures.
+
+## Rotation workflow (example)
+
+1. Add the new root key to your trust file (do not remove the old one yet).
+2. Roll out the trust file change to CI/verifier environments.
+3. Begin signing new governance policy streams with the new root key.
+4. Once all verifiers are updated and the old root is no longer needed, remove the old root key from the trust file.
+
+If you remove a trust root key too early, strict verification will fail with trust-related errors (see `ERRORS.md`).

package/docs/spec/TenantSettings.v1.md

@@ -0,0 +1,90 @@
+# TenantSettings.v1
+
+`TenantSettings.v1` is the **tenant-scoped configuration contract** for Settld Verify Cloud / Magic Link.
+
+This version is legacy and is superseded by `TenantSettings.v2` (which adds artifact storage controls and archival export sinks).
+
+It controls:
+
+- default verification posture (`auto|strict|compat`)
+- tenant-specific governance trust roots (for strict verification without deploy-time env config)
+- tenant-specific pricing signer keys (for strict verification of buyer-approved pricing terms)
+- retention and quota limits
+- buyer policy controls for vendor submissions
+- buyer portal authentication + RBAC (service-level)
+- buyer decision authentication controls (service-level)
+- buyer decision signing configuration (service-level)
+- webhook configuration
+
+## Schema
+
+See `schemas/TenantSettings.v1.schema.json`.
+
+## Vendor / contract policy controls (service-level)
+
+`vendorPolicies` and `contractPolicies` are **service-level** enforcement knobs for Verify Cloud. They do **not** change `InvoiceBundle.v1`.
+
+Policy selection precedence:
+
+1. `contractPolicies[contractId]` (if `contractId` is present on the run)
+2. `vendorPolicies[vendorId]` (if `vendorId` is present on the run)
+3. no policy
+
+Policy fields:
+
+- `requiredMode`: `auto|strict|compat` override for how the hosted verifier runs (independent of uploader requested mode).
+- `failOnWarnings`: if true, hosted output is failed when any warnings are present (same as CLI `--fail-on-warnings` posture).
+- `allowAmberApprovals`: if false, buyers cannot record **Approve** decisions when status is Amber.
+- `requireProducerReceiptPresent`: if true, hosted output fails if `verify/verification_report.json` is missing (even in compat mode).
+- `requiredPricingMatrixSignerKeyIds`: when set, hosted verification fails unless `pricing/pricing_matrix_signatures.json` includes at least one trusted signature whose `signerKeyId` is allowlisted by this policy.
+- `retentionDays`: optional per-policy retention override for runs matching that vendor/contract.
+
+## Decision authentication (service-level)
+
+`decisionAuthEmailDomains` configures optional **email OTP gating** for buyer decision actions (`Approve`/`Hold`) on Magic Links.
+
+- If empty (default): decision capture is unauthenticated and relies on typed actor name+email.
+- If non-empty: decision capture requires an email OTP, and the email domain MUST match one of the configured domains.
+
+This is a service control plane feature (not part of the frozen `InvoiceBundle.v1` protocol).
+
+## Buyer portal authentication + RBAC (service-level)
+
+Verify Cloud supports **buyer portal** access without sharing the tenant API key.
+
+This is a service control plane feature (not part of the frozen `InvoiceBundle.v1` protocol).
+
+### Authentication
+
+`buyerAuthEmailDomains` configures **email OTP login** for buyer users.
+
+- If empty (default): buyer portal OTP login is disabled.
+- If non-empty: buyers can request an OTP and establish a session if their email domain matches one of the configured domains.
+
+### Roles
+
+`buyerUserRoles` is an optional mapping from **buyer email → role**:
+
+- `admin`: manage settings, ingest keys, policies, exports, billing
+- `approver`: view inbox, export audit packet/CSV, approve/hold (via signed `SettlementDecisionReport.v1`)
+- `viewer`: view inbox only
+
+If an email is not listed in `buyerUserRoles`, it is treated as `viewer`.
+
+## Pricing signer trust (service-level)
+
+`pricingSignerKeysJson` is an optional tenant-scoped trust set for **buyer pricing signer keys**.
+
+It is used to populate `SETTLD_TRUSTED_PRICING_SIGNER_KEYS_JSON` for hosted verification runs so that
+`pricing/pricing_matrix_signatures.json` can be validated in strict mode.
+
+`trustedPricingSignerKeyIds` is an optional allowlist of key IDs. When set and non-empty, Verify Cloud MUST treat only those key IDs as trusted pricing signers (even if additional keys exist in `pricingSignerKeysJson`).
+
+## Settlement decision signing (service-level)
+
+`settlementDecisionSigner` configures how Verify Cloud signs buyer approval/hold receipts (`SettlementDecisionReport.v1`).
+
+Supported modes:
+
+- local PEM private key (pilot posture)
+- delegated remote signer (hardened key custody)

package/docs/spec/TenantSettings.v2.md

@@ -0,0 +1,99 @@
+# TenantSettings.v2
+
+`TenantSettings.v2` is the **tenant-scoped configuration contract** for Settld Verify Cloud / Magic Link.
+
+It is a backwards-compatible evolution of `TenantSettings.v1` that adds:
+
+- per-tenant artifact storage cost controls (`artifactStorage`)
+- tenant-configurable archival export sink (`archiveExportSink`)
+- buyer notification delivery config (`buyerNotifications`)
+- automatic settlement decision policy controls (`autoDecision`)
+- payment trigger delivery controls (`paymentTriggers`)
+- tenant-scoped request rate limits (`rateLimits`)
+
+## Schema
+
+See `schemas/TenantSettings.v2.schema.json`.
+
+## Vendor / contract policy controls (service-level)
+
+Unchanged from `TenantSettings.v1`:
+
+- `vendorPolicies` and `contractPolicies` are Verify Cloud enforcement knobs and do **not** change `InvoiceBundle.v1`.
+
+## Artifact storage controls (service-level)
+
+`artifactStorage` controls what Verify Cloud persists under `MAGIC_LINK_DATA_DIR`.
+
+Fields:
+
+- `storeBundleZip` (default `true`): persist `zips/<token>.zip` so a buyer can download the exact bytes that were verified.
+- `storePdf` (default `true`): persist `pdf/<token>.pdf` when an invoice claim is present.
+- `precomputeMonthlyAuditPackets` (default `false`): allow the service to cache monthly audit packet zips for export sinks (still safe to generate on-demand).
+
+These are service controls (not part of the frozen `InvoiceBundle.v1` protocol).
+
+## Archival export sink (service-level)
+
+`archiveExportSink` configures an optional monthly archival push of:
+
+- monthly audit packet ZIP (`/v1/tenants/:tenant/audit-packet?month=…`)
+- monthly CSV export (`/v1/tenants/:tenant/export.csv?month=…`)
+
+Supported sink types:
+
+- `s3`: S3-compatible object storage.
+
+Secrets (e.g. `secretAccessKey`) are encrypted at rest when `MAGIC_LINK_SETTINGS_KEY_HEX` is configured.
+
+## Buyer notifications (service-level)
+
+`buyerNotifications` configures post-verification delivery of buyer links.
+
+Fields:
+
+- `emails`: recipient list (normalized lowercase emails).
+- `deliveryMode`: `smtp|webhook|record`.
+- `webhookUrl`: required when `deliveryMode=webhook`.
+- `webhookSecret`: optional HMAC secret for webhook delivery (encrypted at rest when settings key is configured).
+
+Notification delivery is idempotent per run token.
+
+## Auto-decision policy (service-level)
+
+`autoDecision` configures optional automatic buyer decisions immediately after verification completes.
+
+Fields:
+
+- `enabled`: turn policy automation on/off.
+- `approveOnGreen`: auto-approve `green` runs.
+- `approveOnAmber`: auto-approve `amber` runs.
+- `holdOnRed`: auto-hold `red` runs.
+- `templateIds`: optional template allowlist. When set, auto-decision only applies to listed SLA template IDs.
+- `actorName` / `actorEmail`: actor identity stamped into `SettlementDecisionReport.v1` for automated decisions.
+
+Automated decisions are best-effort and respect idempotency/lockout (`DECISION_ALREADY_RECORDED`).
+
+## Payment triggers (service-level)
+
+`paymentTriggers` configures optional outbound delivery when an artifact is approved.
+
+Fields:
+
+- `enabled`: enable/disable payment trigger delivery.
+- `deliveryMode`: `record|webhook`.
+- `webhookUrl`: required when `enabled=true` and `deliveryMode=webhook`.
+- `webhookSecret`: optional HMAC signing secret (encrypted at rest when settings key is configured).
+
+Delivery is idempotent per approved decision report hash.
+
+## Tenant rate limits (service-level)
+
+`rateLimits` configures tenant + IP window limits:
+
+- `uploadsPerHour` (default `100`)
+- `verificationViewsPerHour` (default `1000`)
+- `decisionsPerHour` (default `300`)
+- `otpRequestsPerHour` (default `300`)
+
+Exceeded limits return `429` with a `Retry-After` header.

package/docs/spec/TimestampProof.v1.md

@@ -0,0 +1,25 @@
+# TimestampProof.v1
+
+This document defines a **trustworthy signing time** proof that can be embedded inside signed protocol documents (e.g. `BundleHeadAttestation.v1` and `VerificationReport.v1`).
+
+## Semantics
+
+`TimestampProof.v1` is an **independent attestation of time** over a specific message hash. It exists so strict verification can support “historical acceptance” under prospective revocation rules without trusting a signer-controlled timestamp field.
+
+v1 supports one proof kind:
+
+- `kind = "ed25519_time_authority"` — an Ed25519 signature by a trusted time authority key.
+
+Fields:
+
+- `timestamp`: the asserted timestamp (RFC3339 / ISO string).
+- `messageHash`: `sha256` hex of the canonical JSON bytes of the signed document’s **core payload**, computed **without** the `timestampProof` field.
+- `signerKeyId` / `signature`: the time authority signature.
+
+## Trust model (strict verification)
+
+Strict verification MUST treat the time as trustworthy only if:
+
+- the proof verifies cryptographically, and
+- the proof’s signer key is trusted out-of-band by the verifier (a “time authority” trust anchor).
+

package/docs/spec/ToolCallAgreement.v1.md

@@ -0,0 +1,34 @@
+# ToolCallAgreement.v1
+
+`ToolCallAgreement.v1` binds a payable tool invocation to deterministic settlement terms.
+
+The output is a hash-addressable agreement (`agreementHash`) that can be referenced by downstream holds, disputes, and receipts without trusting an online service.
+
+## Fields
+
+Required:
+
+- `schemaVersion` (const: `ToolCallAgreement.v1`)
+- `toolId` (string)
+- `manifestHash` (sha256 hex; hash of the referenced `ToolManifest.v1`)
+- `callId` (string; tool-call correlation id)
+- `inputHash` (sha256 hex; hash of canonical JSON of the tool-call input payload)
+- `acceptanceCriteria` (object or `null`)
+- `settlementTerms` (object or `null`)
+- `payerAgentId` (string or `null`)
+- `payeeAgentId` (string or `null`)
+- `createdAt` (ISO 8601 date-time)
+- `agreementHash` (sha256 hex)
+
+## Canonicalization + hashing
+
+1. Canonicalize using RFC 8785 (JCS).
+2. The `agreementHash` is `sha256` over UTF-8 bytes of canonical JSON of the **agreement core**:
+   - the full `ToolCallAgreement.v1` object **excluding** the `agreementHash` field.
+
+Implementations must treat the nullable fields (`acceptanceCriteria`, `settlementTerms`, `payerAgentId`, `payeeAgentId`) as present with explicit `null` when absent so `agreementHash` does not depend on “omitted vs null” representation.
+
+## Schema
+
+See `docs/spec/schemas/ToolCallAgreement.v1.schema.json`.
+

package/docs/spec/ToolCallEvidence.v1.md

@@ -0,0 +1,47 @@
+# ToolCallEvidence.v1
+
+`ToolCallEvidence.v1` records the outcome of a tool invocation (`outputHash`, optional references/metrics) and binds it to a `ToolCallAgreement.v1` via `agreementHash`.
+
+The output is a hash-addressable evidence record (`evidenceHash`) that can be optionally signed by an agent key.
+
+## Fields
+
+Required:
+
+- `schemaVersion` (const: `ToolCallEvidence.v1`)
+- `agreementHash` (sha256 hex; points to `ToolCallAgreement.v1`)
+- `callId` (string; must match the agreement `callId`)
+- `inputHash` (sha256 hex; must match the agreement `inputHash`)
+- `outputHash` (sha256 hex; hash of canonical JSON of the tool-call output payload)
+- `outputRef` (string or `null`; optional pointer to stored output)
+- `metrics` (object or `null`; optional timing/quality metrics)
+- `startedAt` (ISO 8601 date-time)
+- `completedAt` (ISO 8601 date-time)
+- `createdAt` (ISO 8601 date-time)
+- `evidenceHash` (sha256 hex)
+
+Optional:
+
+- `signature` (object): Ed25519 signature over `evidenceHash`
+  - `algorithm` (const: `ed25519`)
+  - `signerKeyId` (string)
+  - `evidenceHash` (sha256 hex; must equal the parent `evidenceHash`)
+  - `signature` (base64)
+
+## Canonicalization + hashing
+
+1. Canonicalize using RFC 8785 (JCS).
+2. The `evidenceHash` is `sha256` over UTF-8 bytes of canonical JSON of the **evidence core**:
+   - the full `ToolCallEvidence.v1` object excluding `evidenceHash` and `signature`.
+
+Implementations must treat the nullable fields (`outputRef`, `metrics`) as present with explicit `null` when absent so `evidenceHash` does not depend on “omitted vs null” representation.
+
+## Signing
+
+- When present, `signature.signature` is an Ed25519 signature over the **bytes** of `evidenceHash` (hex), base64-encoded.
+- Verifiers should ensure `signature.evidenceHash` matches the enclosing `evidenceHash` before verifying the signature.
+
+## Schema
+
+See `docs/spec/schemas/ToolCallEvidence.v1.schema.json`.
+