settld 0.1.1 → 0.1.5

package/docs/spec/SIGNER_PROVIDER_PLUGIN.md

@@ -0,0 +1,32 @@
+# Signer provider plugins (tooling contract)
+
+Signer provider plugins extend `settld-produce` with custom key custody and signing implementations (KMS/HSM/Vault/remote approval flows) without changing bundle protocol objects.
+
+This is a **tooling** contract (not protocol v1). Verifiers remain unchanged.
+
+## CLI usage
+
+`settld-produce --signer plugin --signer-plugin <path|package> [--signer-plugin-export createSignerProvider] [--signer-plugin-config <json>] --gov-key-id <id> --server-key-id <id> ...`
+
+## Plugin contract
+
+Your plugin must export a function (default name: `createSignerProvider`):
+
+- Signature: `async createSignerProvider({ config, env }) -> provider`
+
+Where `provider` is an object implementing:
+
+- `async getPublicKeyPem({ keyId }) -> publicKeyPem`
+- `async sign({ keyId, algorithm, messageBytes, purpose, context }) -> { signatureBase64, signerReceipt? }`
+
+Notes:
+
+- `messageBytes` are the exact bytes to sign (typically 32 bytes: sha256 of canonical JSON).
+- `purpose` is required and must be enforced by the provider (refuse unknown purposes).
+- Do not log or return private key material.
+
+## Packaging guidance
+
+- If `--signer-plugin` is a path, it is resolved relative to the current working directory.
+- If `--signer-plugin` is a package name, it must be resolvable via Node module resolution (installed in the environment where `settld-produce` runs).
+

package/docs/spec/STRICTNESS.md

@@ -0,0 +1,68 @@
+# Strict vs Non-Strict Verification
+
+This document defines the **compatibility contract** for verifier behavior.
+
+## Definitions
+
+- **Strict mode**: missing/invalid protocol surfaces are hard failures.
+- **Non-strict mode**: verifier performs best-effort verification and emits **warnings** for legacy or incomplete bundles, but still rejects tampering (e.g., manifest hash mismatch, file hash mismatch).
+
+## Contract matrix (v1 protocol era)
+
+### Proof bundles (JobProofBundle.v1, MonthProofBundle.v1)
+
+| Surface | Strict | Non-strict |
+|---|---:|---:|
+| `manifest.json` present + `manifestHash` correct | required (fail) | required (fail) |
+| `manifest.json` file hashes correct | required (fail) | required (fail) |
+| trusted governance root keys provided out-of-band | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` present | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` version | **must be `GovernancePolicy.v2`** (fail) | allow `GovernancePolicy.v1` (warn + continue) |
+| `governance/policy.json` signature (governance root) | required (fail) | not required (no check) |
+| `governance/revocations.json` present + signature | required (fail) | not required (no check) |
+| `attestation/bundle_head_attestation.json` present + valid | required (fail) | best-effort (warn + continue) |
+| `verify/verification_report.json` present + signed | required (fail) | best-effort (warn + continue if missing; verify if present) |
+
+### Finance packs (FinancePackBundle.v1)
+
+| Surface | Strict | Non-strict |
+|---|---:|---:|
+| `manifest.json` present + `manifestHash` correct | required (fail) | required (fail) |
+| `manifest.json` file hashes correct | required (fail) | required (fail) |
+| trusted governance root keys provided out-of-band | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` present | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` version | **must be `GovernancePolicy.v2`** (fail) | allow `GovernancePolicy.v1` (warn + continue) |
+| `governance/policy.json` signature (governance root) | required (fail) | not required (no check) |
+| `governance/revocations.json` present + signature | required (fail) | not required (no check) |
+| `attestation/bundle_head_attestation.json` present + valid | required (fail) | best-effort (warn + continue) |
+| `verify/verification_report.json` present + signed | required (fail) | best-effort (warn + continue if missing; verify if present) |
+
+### Invoice bundles (InvoiceBundle.v1)
+
+| Surface | Strict | Non-strict |
+|---|---:|---:|
+| `manifest.json` present + `manifestHash` correct | required (fail) | required (fail) |
+| `manifest.json` file hashes correct | required (fail) | required (fail) |
+| trusted governance root keys provided out-of-band | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` present | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` version | **must be `GovernancePolicy.v2`** (fail) | allow `GovernancePolicy.v1` (warn + continue) |
+| `governance/policy.json` signature (governance root) | required (fail) | not required (no check) |
+| `governance/revocations.json` present + signature | required (fail) | not required (no check) |
+| `attestation/bundle_head_attestation.json` present + valid | required (fail) | best-effort (warn + continue) |
+| `verify/verification_report.json` present + signed | required (fail) | best-effort (warn + continue if missing; verify if present) |
+| `pricing/pricing_matrix_signatures.json` present + valid buyer signature(s) (`PricingMatrixSignatures.v2` required; `PricingMatrixSignatures.v1` legacy accepted only non-strict with `WARN_PRICING_SIGNATURE_V1_BYTES_LEGACY`) | required (fail) | best-effort (warn + continue if missing) |
+
+### Close packs (ClosePack.v1)
+
+| Surface | Strict | Non-strict |
+|---|---:|---:|
+| ClosePack `manifest.json` present + `manifestHash` correct | required (fail) | required (fail) |
+| ClosePack manifest file hashes correct | required (fail) | required (fail) |
+| trusted governance root keys provided out-of-band | required (fail) | best-effort (warn + continue) |
+| ClosePack governance policy surfaces | required (fail) | best-effort (warn + continue) |
+| ClosePack head attestation present + valid | required (fail) | best-effort (warn + continue) |
+| ClosePack verification report present + signed | required (fail) | best-effort (warn + continue if missing; verify if present) |
+| embedded `payload/invoice_bundle/**` strictly verifies under same posture | required (fail) | required (fail) |
+| `evidence/evidence_index.json` present + matches deterministic recomputation | required (fail) | required (fail) |
+| SLA evaluation surfaces (`sla/*`) | optional; if present must recompute + match | optional; missing emits `CLOSE_PACK_SLA_SURFACES_MISSING_LENIENT` |
+| acceptance evaluation surfaces (`acceptance/*`) | optional; if present must recompute + match | optional; missing emits `CLOSE_PACK_ACCEPTANCE_SURFACES_MISSING_LENIENT` |

package/docs/spec/SUPPLY_CHAIN.md

@@ -0,0 +1,33 @@
+# Supply chain: releases
+
+This doc describes what Settld release authenticity *does* and *does not* guarantee.
+
+## Threat model (release channel)
+
+### Assets
+
+- Authenticity of published release artifacts (`*.tgz`, conformance pack, audit packet, etc.)
+- Integrity of the mapping: “this tool install corresponds to this commit/release”
+
+### Attacks prevented (assuming release signing key not compromised)
+
+- Artifact swap: attacker replaces one or more release artifacts after build
+- Checksum swap: attacker replaces artifacts *and* checksums together
+- CI compromise without release key access: attacker can run arbitrary steps but cannot forge a valid `ReleaseIndex.v1` signature
+
+### Attacks not prevented
+
+- Release signing key compromise (attacker can sign malicious artifacts)
+- Compromised dependency supply chain *before* release build (mitigated by lockfiles/SBOM, not eliminated)
+
+## Operational response
+
+If the release signing key is suspected compromised:
+
+- Rotate the release signing key and publish an updated `ReleaseTrust.v2` (and revoke the compromised key).
+- Publish a security advisory describing impacted releases and mitigation steps.
+
+## How to verify a release (high-level)
+
+1. Verify `release_index_v1.sig` against `release_index_v1.json` using a trusted `ReleaseTrust.v2`.
+2. Verify each artifact’s `sha256` matches the index.

package/docs/spec/SettlementAdjustment.v1.md

@@ -0,0 +1,45 @@
+# SettlementAdjustment.v1
+
+`SettlementAdjustment.v1` is a deterministic, idempotent adjustment artifact that applies a single escrow operation against funds held in a related `FundingHold.v1`.
+
+Sprint 21 uses exactly one adjustment per `agreementHash` for tool-call holdback disputes.
+
+## Fields
+
+Required:
+
+- `schemaVersion` (const: `SettlementAdjustment.v1`)
+- `adjustmentId` (deterministic ID; for tool-call holdback: `sadj_agmt_${agreementHash}_holdback`)
+- `tenantId`
+- `agreementHash` (sha256 hex)
+- `receiptHash` (sha256 hex)
+- `holdHash` (sha256 hex)
+- `kind` (`holdback_release|holdback_refund`)
+- `amountCents` (non-negative int; must be `<= heldAmountCents` at application time)
+- `currency`
+- `createdAt` (ISO datetime)
+- `adjustmentHash` (sha256 hex; computed from immutable core)
+
+Optional:
+
+- `verdictRef`:
+  - `caseId`
+  - `verdictHash` (sha256 hex)
+- `metadata` (implementation-defined JSON object)
+
+## Hashing
+
+`adjustmentHash` is computed as sha256 of the RFC 8785 canonical JSON of the core object excluding:
+
+- `adjustmentHash`
+- `metadata`
+
+## Invariants
+
+- Adjustments must operate on held escrow funds only (no negative balances, no external clawbacks).
+- Persistence must enforce uniqueness for `adjustmentId` per tenant; duplicates must be treated as idempotent retries returning the existing adjustment.
+
+## Schema
+
+See `docs/spec/schemas/SettlementAdjustment.v1.schema.json`.
+

package/docs/spec/SettlementDecisionRecord.v1.md

@@ -0,0 +1,48 @@
+# SettlementDecisionRecord.v1
+
+`SettlementDecisionRecord.v1` is the canonical decision artifact for an `AgentRunSettlement.v1` state transition.
+
+It binds one settlement decision to:
+
+- the settlement principal (`settlementId`, `runId`, `tenantId`),
+- the governing policy/verifier references,
+- and the execution lineage (`runLastEventId`, `runLastChainHash`, `resolutionEventId`).
+
+## Purpose
+
+- make settlement decisions replayable and attributable;
+- bind payout/refund decisions to specific run/settlement lineage;
+- provide a stable hash (`decisionHash`) for downstream receipt binding.
+
+## Required fields
+
+- `schemaVersion` (const: `SettlementDecisionRecord.v1`)
+- `decisionId`
+- `tenantId`
+- `runId`
+- `settlementId`
+- `decisionStatus`
+- `decisionMode`
+- `policyRef`
+- `verifierRef`
+- `workRef`
+- `decidedAt`
+- `decisionHash`
+
+Optional fields:
+
+- `agreementId`
+- `decisionReason`
+- `verificationStatus`
+
+## Canonicalization and hashing
+
+`decisionHash` is computed over canonical JSON after removing `decisionHash` from the object:
+
+1. canonicalize JSON with RFC 8785 (JCS),
+2. hash canonical UTF-8 bytes using `sha256`,
+3. encode as lowercase hex.
+
+## Schema
+
+See `schemas/SettlementDecisionRecord.v1.schema.json`.

package/docs/spec/SettlementDecisionRecord.v2.md

@@ -0,0 +1,51 @@
+# SettlementDecisionRecord.v2
+
+`SettlementDecisionRecord.v2` is the canonical decision artifact for an `AgentRunSettlement.v1` state transition.
+
+It is identical in semantic intent to `SettlementDecisionRecord.v1`, but adds **replay-critical policy pinning** so decisions can be re-evaluated deterministically from protocol artifacts alone.
+
+## Purpose
+
+- make settlement decisions replayable and attributable;
+- bind payout/refund decisions to specific run/settlement lineage;
+- provide a stable hash (`decisionHash`) for downstream receipt binding;
+- pin the **exact policy hash used** during evaluation (`policyHashUsed`).
+
+## Required fields
+
+- `schemaVersion` (const: `SettlementDecisionRecord.v2`)
+- all required fields from `SettlementDecisionRecord.v1`
+- `policyHashUsed` (sha256 hex, lowercase)
+
+Optional fields:
+
+- all optional fields from `SettlementDecisionRecord.v1`
+- `policyNormalizationVersion` (string; OPTIONAL; v2 emitters SHOULD include this to pin the normalization algorithm used to compute `policyHashUsed`)
+- `verificationMethodHashUsed` (sha256 hex, lowercase; OPTIONAL; omit when absent)
+- `bindings` (object; OPTIONAL) - settlement receipt trail bindings for gateway-style flows:
+  - `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`)
+
+## Policy pinning rules
+
+- `policyHashUsed` MUST be the hash of the normalized policy object actually evaluated.
+- If the evaluated policy is carried inline (for example, in an agreement payload), `policyHashUsed` MUST match the normalized inline policy payload.
+- If the policy is resolved from a policy registry, `policyHashUsed` MUST match the policy payload referenced by the registry entry.
+- `verificationMethodHashUsed` SHOULD be set when verifier selection depends on an explicit verification method payload.
+
+## Canonicalization and hashing
+
+`decisionHash` is computed over canonical JSON after removing `decisionHash` from the object:
+
+1. canonicalize JSON with RFC 8785 (JCS),
+2. hash canonical UTF-8 bytes using `sha256`,
+3. encode as lowercase hex.
+
+## Schema
+
+See `schemas/SettlementDecisionRecord.v2.schema.json`.

package/docs/spec/SettlementDecisionReport.v1.md

@@ -0,0 +1,44 @@
+# SettlementDecisionReport.v1
+
+`SettlementDecisionReport.v1` is a canonical JSON object that records a buyer’s **Approve/Hold** decision for a specific `InvoiceBundle.v1`.
+
+It is intended to be archived alongside the invoice bundle zip and re-verified later **offline** (without access to the hosted service).
+
+## Purpose
+
+- Provide a portable, cryptographically verifiable receipt of a buyer decision.
+- Bind the decision to a specific invoice bundle instance (mix-and-match defense).
+- Capture the effective hosted verification posture and result summary the decision was made under.
+
+## Core fields
+
+- `schemaVersion = "SettlementDecisionReport.v1"`
+- `decision`: `"approve"` or `"hold"`
+- `decidedAt`: ISO timestamp of the decision action
+- `invoiceBundle` (binding target):
+  - `manifestHash`: invoice bundle manifest hash
+  - `headAttestationHash`: invoice bundle head attestation hash
+- `policy`: effective policy snapshot (requiredMode / failOnWarnings / allowAmberApprovals / requiredPricingMatrixSignerKeyIds / etc.)
+- `verification`: summary slice of the hosted verification output (stable codes)
+- `tool`: `{ name, version, commit }` (best-effort provenance for the hosted verifier build)
+- `actor` (optional): service-level claims about who clicked approve/hold (e.g., email, auth method)
+
+## Report hash + signature
+
+- `reportHash` is computed over the canonical JSON object with `reportHash`, `signature`, `signerKeyId`, and `signedAt` removed.
+- If the report is signed, it includes:
+  - `signature` (base64 Ed25519 signature)
+  - `signerKeyId`
+  - `signedAt`
+
+Signature algorithm:
+
+- The signed message is the bytes of the 32-byte sha256 digest (`reportHash` hex decoded).
+- Algorithm: Ed25519.
+
+## Trust anchors (out-of-band)
+
+To verify a settlement decision report, the verifier needs trusted buyer decision signer public keys out-of-band.
+
+See `TRUST_ANCHORS.md`.
+

package/docs/spec/SettlementKernel.v1.md

@@ -0,0 +1,59 @@
+# SettlementKernel.v1
+
+`SettlementKernel.v1` defines the binding invariants between `AgentRunSettlement.v1`, `SettlementDecisionRecord.v1|v2`, and `SettlementReceipt.v1`.
+
+The kernel is considered valid only when artifact hash integrity, identity binding, and temporal ordering all hold.
+
+## Kernel invariants
+
+- Settlement object exists and has the expected `runId`.
+- `decisionRecord` exists and has a valid `decisionHash` (`sha256` over canonical JSON without `decisionHash`).
+- `decisionRecord.runId` and `decisionRecord.settlementId` match settlement.
+- `settlementReceipt` exists and has a valid `receiptHash` (`sha256` over canonical JSON without `receiptHash`).
+- `settlementReceipt.runId` and `settlementReceipt.settlementId` match settlement.
+- `settlementReceipt.decisionRef` must exist and bind to `decisionRecord` (`decisionId` + `decisionHash`).
+- Temporal ordering must hold:
+  - `decisionRecord.decidedAt` is valid ISO date-time.
+  - `settlementReceipt.createdAt` is valid ISO date-time.
+  - `settlementReceipt.settledAt`, when present, is valid ISO date-time.
+  - `settlementReceipt.createdAt >= decisionRecord.decidedAt`.
+  - `settlementReceipt.settledAt >= decisionRecord.decidedAt` (when present).
+  - `settlementReceipt.settledAt >= settlementReceipt.createdAt` (when present).
+
+## Verification error code semantics
+
+When kernel verification fails, implementations return one or more stable codes:
+
+- `settlement_missing`
+- `settlement_run_id_mismatch`
+- `decision_record_missing`
+- `decision_record_hash_invalid`
+- `decision_record_hash_mismatch`
+- `decision_record_run_id_mismatch`
+- `decision_record_settlement_id_mismatch`
+- `settlement_receipt_missing`
+- `settlement_receipt_hash_invalid`
+- `settlement_receipt_hash_mismatch`
+- `settlement_receipt_run_id_mismatch`
+- `settlement_receipt_settlement_id_mismatch`
+- `settlement_receipt_decision_ref_missing`
+- `settlement_receipt_decision_id_mismatch`
+- `settlement_receipt_decision_hash_mismatch`
+- `decision_record_decided_at_invalid`
+- `settlement_receipt_created_at_invalid`
+- `settlement_receipt_settled_at_invalid`
+- `settlement_receipt_before_decision`
+- `settlement_receipt_settled_before_decision`
+- `settlement_receipt_settled_before_created`
+
+## API-level enforcement
+
+- Settlement mutation routes reject invalid bindings with:
+  - HTTP `409`
+  - error code `SETTLEMENT_KERNEL_BINDING_INVALID`
+  - `details.errors[]` containing kernel verification codes above.
+
+- `/ops/network/command-center` exposes settlement-kernel health via:
+  - `commandCenter.settlement.kernelVerificationErrorCount`
+  - `commandCenter.settlement.kernelVerificationErrorCountsByCode[]`
+  - alert type `settlement_kernel_verification_error_code` when configured thresholds are breached.

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`.
+