settld 0.1.2 → 0.2.0

package/docs/spec/OperatorAction.v1.md

@@ -0,0 +1,90 @@
+# OperatorAction.v1
+
+`OperatorAction.v1` is the canonical operator-evidence artifact used for high-risk control actions.
+
+It captures who acted, which case was affected, what action was taken, and why. The signed form binds this surface to an Ed25519 signature for offline verification.
+
+## Purpose
+
+`OperatorAction.v1` enables:
+
+- deterministic replay/audit of emergency operator decisions,
+- hash-based tamper detection over a frozen action surface,
+- stable verification codes for schema/key/hash/signature failures.
+
+## Emergency RBAC + dual-control policy
+
+For `/ops/emergency/*` actions, `OperatorAction.v1` is evaluated against runtime authorization policy:
+
+- Role matrix:
+  - `pause|quarantine`: `oncall|ops_admin|incident_commander`
+  - `revoke|kill-switch`: `ops_admin|incident_commander`
+  - `resume`: follows the strictest targeted control class (`ops_admin|incident_commander` when resuming `revoke|kill-switch`)
+- Dual-control:
+  - `revoke|kill-switch` class actions require both `operatorAction` and `secondOperatorAction`.
+  - The two approvals must be from distinct `actor.operatorId` and distinct `signature.keyId`.
+  - Missing or non-distinct second approvals fail closed.
+
+## Required fields
+
+- `schemaVersion` (const: `OperatorAction.v1`)
+- `caseRef`
+  - `kind` (`challenge|dispute|escalation`)
+  - `caseId`
+- `action` (`APPROVE|REJECT|REQUEST_INFO|OVERRIDE_ALLOW|OVERRIDE_DENY`)
+- `justificationCode` (uppercase machine token)
+- `actor`
+  - `operatorId`
+- `actedAt` (ISO 8601 date-time)
+
+Optional:
+
+- `actionId`
+- `justification`
+- `actor.role` (lowercase token)
+- `actor.tenantId`
+- `actor.sessionId`
+- `actor.metadata`
+- `metadata`
+- `signature`
+  - `schemaVersion` (const: `OperatorActionSignature.v1`)
+  - `algorithm` (const: `ed25519`)
+  - `keyId`
+  - `signedAt` (ISO 8601 date-time)
+  - `actionHash` (`sha256` hex)
+  - `signatureBase64`
+
+Optional fields MUST be omitted when absent (not `null`) unless explicitly allowed by schema.
+
+## Canonicalization + hashing
+
+`actionHash` is computed over canonical JSON (RFC 8785 / JCS) of the unsigned `OperatorAction.v1` object.
+
+Hash algorithm: `sha256` over canonical UTF-8 bytes, lowercase hex output.
+
+`actionHash` is carried inside `signature.actionHash` in the signed envelope.
+
+## Signing and verification
+
+Signing (`signOperatorActionV1`) attaches a `signature` object and signs `actionHash` using Ed25519.
+
+Verification (`verifyOperatorActionV1`) enforces:
+
+1. `action.schemaVersion === OperatorAction.v1`,
+2. `action.signature.schemaVersion === OperatorActionSignature.v1`,
+3. `signature.keyId` matches the expected public key id,
+4. `signature.actionHash` equals recomputed hash,
+5. Ed25519 signature verification succeeds.
+
+Failures return stable codes such as:
+
+- `OPERATOR_ACTION_SCHEMA_MISMATCH`
+- `OPERATOR_ACTION_SIGNATURE_SCHEMA_MISMATCH`
+- `OPERATOR_ACTION_KEY_ID_MISMATCH`
+- `OPERATOR_ACTION_HASH_MISMATCH`
+- `OPERATOR_ACTION_SIGNATURE_INVALID`
+- `OPERATOR_ACTION_SCHEMA_INVALID`
+
+## Schema
+
+See `docs/spec/schemas/OperatorAction.v1.schema.json`.

package/docs/spec/PRODUCER_ERRORS.md

@@ -0,0 +1,42 @@
+# Producer error codes (tooling contract)
+
+These error codes are emitted by producer tooling such as `settld-produce` and `settld-trust` when generating bundles or initializing trust material.
+
+These codes are a tooling/API surface (not protocol v1 bundle objects). Meanings are stable within major versions.
+
+Canonical list: `docs/spec/producer-error-codes.v1.txt`.
+
+## Safe details (`causeKind` / `causeCode`)
+
+Producer machine output (`settld-produce --format json`) may include:
+
+- `causeKind`: coarse category (`signer` | `plugin` | `verify` | `input` | `io` | `internal`)
+- `causeCode`: stable internal failure class code (never raw exception text)
+
+`causeCode` is best-effort and is intended for support triage, not strict automation.
+
+## Codes
+
+### `PRODUCE_FAILED`
+Catch-all failure when a more specific code is not available.
+
+### Signer/auth
+
+- `SIGNER_AUTH_MISSING` — remote signer auth configured but token missing.
+- `SIGNER_AUTH_FAILED` — remote signer returned 401/403.
+- `SIGNER_TIMEOUT` — signer call timed out (HTTP or process).
+- `SIGNER_UNREACHABLE` — signer could not be reached (network failure).
+- `SIGNER_BAD_RESPONSE` — signer returned invalid JSON or missing required fields.
+- `SIGNER_MESSAGE_TOO_LARGE` — signing request message exceeds max size.
+- `SIGNER_RESPONSE_TOO_LARGE` — signer response exceeds max size.
+
+### Plugin signer
+
+- `SIGNER_PLUGIN_LOAD_FAILED` — plugin module could not be imported.
+- `SIGNER_PLUGIN_MISSING_EXPORT` — requested export was missing.
+- `SIGNER_PLUGIN_INIT_FAILED` — plugin factory threw during initialization.
+- `SIGNER_PLUGIN_INVALID_PROVIDER` — plugin returned an invalid provider object.
+
+### Post-produce verification
+
+- `VERIFY_AFTER_FAILED` — `--verify-after` failed.

package/docs/spec/PolicyDecision.v1.md

@@ -0,0 +1,83 @@
+# PolicyDecision.v1
+
+`PolicyDecision.v1` is the canonical, hash-addressable policy outcome artifact for settlement decisions.
+
+It captures the exact policy/verification inputs used for decisioning, the normalized outcome, and an optional signer envelope.
+
+## Purpose
+
+`PolicyDecision.v1` provides a deterministic artifact that can be:
+
+- bound into settlement decision/receipt traces,
+- compared across reruns/replays,
+- verified offline using canonical JSON + hash checks.
+
+## Required fields
+
+- `schemaVersion` (const: `PolicyDecision.v1`)
+- `decisionId`
+- `tenantId`
+- `runId`
+- `settlementId`
+- `policyRef`
+  - `policyId` (`string|null`)
+  - `policyVersion` (`integer|null`)
+  - `policyHash`
+  - `verificationMethodHash`
+- `decisionMode` (`automatic|manual-review`)
+- `verificationStatus` (lowercase token)
+- `runStatus` (lowercase token)
+- `shouldAutoResolve` (boolean)
+- `settlementStatus` (lowercase token)
+- `releaseRatePct` (0..100)
+- `releaseAmountCents` (integer >= 0)
+- `refundAmountCents` (integer >= 0)
+- `reasonCodes` (deterministically ordered unique list)
+- `evaluationHash` (`sha256` hex of normalized evaluation input)
+- `createdAt` (ISO 8601)
+- `policyDecisionHash`
+
+Optional:
+
+- `gateId`
+- `metadata`
+- `signature`
+  - `algorithm` (const: `ed25519`)
+  - `signerKeyId`
+  - `policyDecisionHash`
+  - `signature` (base64)
+
+## Canonicalization + hashing
+
+`policyDecisionHash` is computed over canonical JSON (RFC 8785 / JCS) of the full object excluding:
+
+- `policyDecisionHash`
+- `signature`
+
+Hash algorithm: `sha256` over canonical UTF-8 bytes, lowercase hex output.
+
+## Evaluation hash
+
+`evaluationHash` is derived from a stable evaluation input surface (`PolicyDecisionEvaluationInput.v1`) containing:
+
+- policy + verification-method hashes,
+- normalized verification/run/settlement statuses,
+- normalized release/refund outcomes,
+- normalized `reasonCodes`.
+
+This allows lightweight policy-outcome equivalence checks without rehashing the full artifact.
+
+## Signing
+
+When present, `signature.signature` is an Ed25519 signature over `policyDecisionHash` bytes (hex decoded), base64-encoded.
+
+Verifiers should first validate:
+
+- `signature.policyDecisionHash === policyDecisionHash`,
+- `policyDecisionHash` recomputation matches object content,
+
+then verify Ed25519 signature using `signerKeyId` resolution.
+
+## Schema
+
+See `docs/spec/schemas/PolicyDecision.v1.schema.json`.

package/docs/spec/PricingMatrix.v1.md

@@ -0,0 +1,20 @@
+# PricingMatrix.v1
+
+This matrix is stored at `pricing/pricing_matrix.json` within Invoice bundles.
+
+## Buyer approval (contract-grade terms)
+
+Pricing terms may be buyer-approved via a detached signature surface:
+
+- `pricing/pricing_matrix_signatures.json` (`PricingMatrixSignatures.v2` recommended)
+
+New bundles SHOULD use `PricingMatrixSignatures.v2` (canonical JSON binding; formatting-independent).
+
+See:
+
+- `PricingMatrixSignatures.v2.md`
+- `PricingMatrixSignatures.v1.md` (legacy; binds to raw file bytes)
+
+## Numeric representation
+
+- prices are expressed in minor units (e.g. cents) as base-10 integer strings (no floats).

package/docs/spec/PricingMatrixSignatures.v1.md

@@ -0,0 +1,30 @@
+# PricingMatrixSignatures.v1
+
+This document provides a **buyer signature surface** for pricing terms.
+
+It is stored at:
+
+- `pricing/pricing_matrix_signatures.json` within Invoice bundles.
+
+`PricingMatrixSignatures.v1` is **legacy**: it binds to raw file bytes, so reformatting `pricing/pricing_matrix.json` (pretty-print/minify/different serializer) changes the binding hash.
+
+New bundles SHOULD use `PricingMatrixSignatures.v2` (canonical JSON binding; formatting-independent). See `PricingMatrixSignatures.v2.md`.
+
+## Binding target
+
+`PricingMatrixSignatures.v1` binds to the exact bytes of:
+
+- `pricing/pricing_matrix.json`
+
+The binding hash is:
+
+- `pricingMatrixHash` — **sha256 hex of raw file bytes** of `pricing/pricing_matrix.json` (the same value committed in the bundle `manifest.json` entry for that file).
+
+Each signature in `signatures[]` signs the `pricingMatrixHash` (bytes of the 32-byte sha256 digest) using Ed25519.
+
+## Strict vs non-strict
+
+- **Strict**: verifiers MUST reject this legacy schema version (hard failure). Use `PricingMatrixSignatures.v2` instead.
+- **Non-strict**: verifiers MAY accept this legacy schema version for compatibility, but MUST emit warning `WARN_PRICING_SIGNATURE_V1_BYTES_LEGACY`. Missing signatures MAY be accepted with warning `PRICING_MATRIX_UNSIGNED_LENIENT`.
+
+Invalid signatures are hard failures (security invariant).

package/docs/spec/PricingMatrixSignatures.v2.md

@@ -0,0 +1,29 @@
+# PricingMatrixSignatures.v2
+
+This document provides a **buyer signature surface** for pricing terms.
+
+It is stored at:
+
+- `pricing/pricing_matrix_signatures.json` within Invoice bundles.
+
+## Binding target
+
+`PricingMatrixSignatures.v2` binds to the canonical JSON value of:
+
+- `pricing/pricing_matrix.json` (`PricingMatrix.v1`)
+
+The binding hash is:
+
+- `pricingMatrixCanonicalHash` — `sha256_hex( utf8( canonical_json_stringify(pricing_matrix_json) ) )`
+
+Canonical JSON is RFC 8785 (JCS). See `CANONICAL_JSON.md`.
+
+Each signature in `signatures[]` signs `pricingMatrixCanonicalHash` (bytes of the 32-byte sha256 digest) using Ed25519.
+
+## Strict vs non-strict
+
+- **Strict**: verifiers MUST require this file to exist and MUST require at least one valid signature from a trusted buyer pricing signer key (see `TRUST_ANCHORS.md`).
+- **Non-strict**: missing signatures MAY be accepted with warning `PRICING_MATRIX_UNSIGNED_LENIENT`.
+
+Invalid signatures are hard failures (security invariant).
+

package/docs/spec/ProduceCliOutput.v1.md

@@ -0,0 +1,46 @@
+# ProduceCliOutput.v1
+
+`ProduceCliOutput.v1` is the machine-readable output emitted by `settld-produce --format json`.
+
+This is a public contract intended for CI/pipelines:
+
+- It is JSON Schema defined (see `docs/spec/schemas/ProduceCliOutput.v1.schema.json`).
+- Arrays of `errors[]` and `warnings[]` MUST be deterministically ordered (recommended sort: `(code, path)`).
+- Optional fields MUST be omitted when absent (not `null`) unless the schema explicitly allows `null`.
+
+## High-level shape
+
+- `schemaVersion`: `"ProduceCliOutput.v1"`
+- `tool`: tool identity (best-effort)
+- `mode`: deterministic controls that influenced generation
+- `target`: what was produced and where it was written
+- `ok`: overall success
+- `produceOk`: whether production succeeded (even if `verifyAfter` failed)
+- `verifyAfter` (optional): result of a post-produce verification step when requested
+- `warnings[]`: structured warning codes
+- `errors[]`: structured error codes
+- `result`: summary of produced bundle hashes and identifiers
+
+## Error/warning items (safe diagnostics)
+
+Each item in `errors[]` / `warnings[]` may include:
+
+- `code`: stable, machine-readable code (see `docs/spec/PRODUCER_ERRORS.md`).
+- `causeKind`: coarse category for operators (`signer` | `plugin` | `verify` | `input` | `io` | `internal`).
+- `causeCode`: stable, non-secret subcode identifying the internal failure class (never raw exception text).
+
+Producer tooling MUST NOT embed arbitrary exception strings in stdout JSON output; use `--explain` (stderr) for operator diagnostics.
+
+## `--explain` (deterministic stderr)
+
+`settld-produce --explain` prints a deterministic, non-secret diagnostic summary to **stderr**.
+
+Contract:
+
+- Output is deterministic for the same inputs/environment.
+- Output MUST NOT include secrets (tokens, secret header values, private keys).
+- Output ends with **exactly one** trailing newline.
+
+## Relationship to protocol objects
+
+`ProduceCliOutput.v1` describes tooling behavior; it does not change bundle protocol semantics.

package/docs/spec/ProofBundleManifest.v1.md

@@ -0,0 +1,24 @@
+# ProofBundleManifest.v1 (JobProof / MonthProof)
+
+This manifest is stored at `manifest.json` within JobProof and MonthProof bundles.
+
+## Hashing contract
+
+- `hashing.schemaVersion = "ProofBundleManifestHash.v1"`
+- file order: `path_asc`
+- excludes: `["verify/**"]`
+
+Rationale: `verify/verification_report.json` must reference `manifestHash`, so including `verify/**` in the manifest would create circular hashing.
+
+## manifestHash
+
+`manifestHash = sha256_hex( canonical_json_stringify(manifest_without_hash) )`
+
+## File entries
+
+`files[]` entries include:
+
+- `name` (path relative to bundle root)
+- `sha256` (hex sha256 of raw file bytes)
+- `bytes` (byte length)
+

package/docs/spec/README.md

@@ -0,0 +1,109 @@
+# Settld Protocol Specs
+
+This directory freezes the **wire-format contracts** that Settld emits and verifies (bundles, manifests, attestations, and verification reports).
+
+These specs are written so an independent implementer can build a verifier without reading Settld’s source.
+
+## Canonicalization + hashing (global rules)
+
+- **Canonical JSON**: JSON objects are canonicalized using RFC 8785 (JCS).
+- **Hashing**: all hashes in these specs are `sha256` over UTF-8 bytes of canonical JSON (or raw file bytes, as specified), represented as lowercase hex.
+- **Derived outputs**: bundle manifests intentionally **exclude** `verify/**` to avoid circular hashing; those files are verified out-of-band by signature and by binding to the `manifestHash`.
+- **x402 gateway parity**: `x-settld-verification-codes` uses shared reason-code normalization (trim + dedup + lexical sort), and policy fingerprint headers (`x-settld-policy-hash`, `x-settld-policy-version`, `x-settld-policy-verification-method-hash`, `x-settld-policy-evaluation-hash`) must mirror `decisionRecord.bindings.policyDecisionFingerprint`.
+
+## Documents
+
+- `CANONICAL_JSON.md` — canonical JSON rules used before hashing/signing.
+- `VERSIONING.md` — tool vs protocol versioning policy (SemVer + protocol object evolution).
+- `REFERENCE_VERIFIER_BEHAVIOR.md` — filesystem/path/ordering rules to prevent cross-impl drift.
+- `REFERENCE_IMPLEMENTATIONS.md` — reference verifier implementations and conformance parity policy.
+- `THREAT_MODEL.md` — explicit threats, mitigations, and residual risks (evidence-backed).
+- `INVARIANTS.md` — checklist mapping protocol claims → spec → code → tests → codes.
+- `MONEY_RAIL_STATE_MACHINE.md` — deterministic payout/collection lifecycle and transition rules.
+- `ESCROW_NETTING_INVARIANTS.md` — deterministic escrow mutation, settlement partition, and netting invariants.
+- `CRYPTOGRAPHY.md` — crypto primitives + byte-level hashing/signing inventory.
+- `VERIFIER_ENVIRONMENT.md` — operational assumptions and hardening guidance.
+- `ProofBundleManifest.v1.md` — JobProof/MonthProof manifest + hashing contract.
+- `FinancePackBundleManifest.v1.md` — FinancePack manifest + hashing contract.
+- `BundleHeadAttestation.v1.md` — signed head commitment for bundles.
+- `GovernancePolicy.v1.md` — signer authorization policy (strict verification).
+- `GovernancePolicy.v2.md` — signer authorization policy (signed by governance root).
+- `RevocationList.v1.md` — prospective revocation/rotation list (signed by governance root).
+- `TimestampProof.v1.md` — trustworthy signing time proof (for historical acceptance).
+- `VerificationReport.v1.md` — signed, machine-ingestible strict verification report.
+- `PricingMatrixSignatures.v2.md` — buyer signature surface for pricing terms in `InvoiceBundle.v1` (canonical JSON binding; recommended).
+- `PricingMatrixSignatures.v1.md` — legacy buyer signature surface (raw bytes binding).
+- `ClosePack.v1.md` — pre-dispute invoice package embedding `InvoiceBundle.v1` + evidence index.
+- `ClosePackManifest.v1.md` — ClosePack manifest + hashing contract.
+- `EvidenceIndex.v1.md` — deterministic evidence reference index for ClosePack.
+- `SlaDefinition.v1.md` / `SlaEvaluation.v1.md` — deterministic SLA rules + evaluation surfaces for ClosePack.
+- `AcceptanceCriteria.v1.md` / `AcceptanceEvaluation.v1.md` — deterministic acceptance rules + evaluation surfaces for ClosePack.
+- `VerifyCliOutput.v1.md` — `settld-verify --format json` machine output contract.
+- `VerifyAboutOutput.v1.md` — `settld-verify --about --format json` tool metadata contract.
+- `ProduceCliOutput.v1.md` — `settld-produce --format json` machine output contract.
+- `ToolManifest.v1.md` — signed tool/capability manifest that can be pinned by hash.
+- `ToolCallAgreement.v1.md` — hash-addressable agreement binding a tool call (`callId` + `inputHash`) to settlement terms.
+- `ToolCallEvidence.v1.md` — hash-addressable evidence binding a tool call output (`outputHash`) to an agreement hash.
+- `AgentIdentity.v1.md` — portable autonomous agent identity contract.
+- `AgentPassport.v1.md` — delegated identity envelope binding principal, keyset anchors, delegation root, and policy envelope.
+- `DelegationGrant.v1.md` — deterministic delegated-authority grant contract (scope + spend + chain + validity).
+- `ExecutionIntent.v1.md` — canonical pre-execution intent contract binding request fingerprint, risk profile, and policy/spend envelope.
+- `PolicyDecision.v1.md` — hash-addressable policy outcome artifact with normalized decision results and optional signature.
+- `OperatorAction.v1.md` — canonical operator decision audit artifact with deterministic hash binding and optional signature.
+- `AgentWallet.v1.md` — deterministic autonomous wallet snapshot contract.
+- `AgentRun.v1.md` — deterministic agent run snapshot contract.
+- `AgentEvent.v1.md` — append-only event envelope for agent runs.
+- `AgentRunSettlement.v1.md` — deterministic run escrow/settlement contract.
+- `MarketplaceOffer.v2.md` — canonical pre-contract offer artifact derived from negotiation proposals.
+- `MarketplaceAcceptance.v2.md` — canonical acceptance artifact bound to a `MarketplaceOffer.v2` hash.
+- `SettlementDecisionRecord.v1.md` — legacy settlement decision artifact (historical verification).
+- `SettlementDecisionRecord.v2.md` — settlement decision artifact with replay-critical policy pinning (current).
+- `SettlementReceipt.v1.md` — canonical settlement finality receipt bound to a decision hash.
+- `FundingHold.v1.md` — deterministic escrow hold for holdback/challenge-window workflows.
+- `SettlementAdjustment.v1.md` — deterministic, idempotent adjustment artifact for held-funds release/refund.
+- `SettlementKernel.v1.md` — binding invariants + stable verification error semantics for settlement decision/receipt integrity.
+- `ArbitrationCase.v1.md` — formal arbitration case contract with appeal linkage.
+- `DisputeOpenEnvelope.v1.md` — signed dispute opener-proof envelope bound to tool-call hold/receipt/agreement hashes.
+- `ArbitrationVerdict.v1.md` — signed arbitration verdict contract with appeal references.
+- `DisputeCaseLifecycle.v1.md` — fail-closed dispute/arbitration transition state machine and guard rules.
+- `ArbitrationOutcomeMapping.v1.md` — deterministic dispute outcome to settlement directive mapping contract.
+- `ReputationEvent.v1.md` — append-only, deterministic economic reputation fact artifact.
+- `AgentReputation.v1.md` — deterministic trust score snapshot derived from runs + settlement outcomes.
+- `AgentReputation.v2.md` — reputation with recency windows (`7d`, `30d`, `allTime`) for marketplace ranking.
+- `InteractionDirectionMatrix.v1.md` — frozen `4x4` directional interaction matrix (`agent|human|robot|machine`).
+- `TenantSettings.v2.md` — Magic Link / Verify Cloud tenant configuration contract (current).
+- `TenantSettings.v1.md` — legacy (still accepted for stored settings migration).
+- `WARNINGS.md` — warning codes (closed set) and semantics.
+- `ERRORS.md` — error codes (stable identifiers) and semantics.
+- `PRODUCER_ERRORS.md` — producer/tooling error codes (stable identifiers) and semantics.
+- `x402-error-codes.v1.txt` — stable x402 authorize-payment / execution-intent API error codes.
+- `STRICTNESS.md` — strict vs non-strict verification contract.
+- `TRUST_ANCHORS.md` — verifier trust anchors and out-of-band key injection.
+- `TOOL_PROVENANCE.md` — tool version/commit derivation rules.
+- `REMOTE_SIGNER.md` — tooling contract for remote/delegated signing (no private keys on disk).
+- `RemoteSignerRequest.v1.md` / `RemoteSignerResponse.v1.md` — versioned stdio wrapper contract for process-based signers.
+- `SIGNER_PROVIDER_PLUGIN.md` — tooling contract for signer provider plugins (KMS/HSM/Vault integrations).
+- `ReleaseIndex.v1.md` — signed release manifest (artifact authenticity).
+- `ReleaseIndexSignatures.v1.md` — detached multi-signature wrapper for `ReleaseIndex.v1`.
+- `ReleaseTrust.v1.md` — trusted release signing keys (legacy/simple mapping).
+- `ReleaseTrust.v2.md` — trusted release signing keys with rotation/revocation + quorum.
+- `SUPPLY_CHAIN.md` — release-channel threat model and verification procedure.
+
+## Legacy archive
+
+Legacy protocol objects are retained under `docs/spec/legacy/` (including `legacy/schemas/`) for historical verification only.
+Current integrations should use the active specs listed above.
+
+## Schemas + examples
+
+- `schemas/` contains JSON Schema for the on-disk JSON documents.
+- `examples/` contains minimal example instances (illustrative, not authoritative vectors).
+
+## Quickstart
+
+See `docs/QUICKSTART_VERIFY.md` for a CI-friendly verifier quickstart using `settld-verify --format json`.
+
+## Conformance + audit evidence
+
+- Conformance oracle: `conformance/v1/README.md`
+- Audit packet (specs + vectors + conformance + checksums): `npm run audit:packet`

package/docs/spec/REFERENCE_IMPLEMENTATIONS.md

@@ -0,0 +1,29 @@
+# Reference implementations
+
+Settld’s protocol is intended to be language/toolchain independent.
+
+This repo contains multiple verifier implementations that are expected to agree on `conformance/v1/`:
+
+## JavaScript (Node)
+
+- CLI: `packages/artifact-verify/bin/settld-verify.js`
+- Conformance runner: `node conformance/v1/run.mjs --node-bin packages/artifact-verify/bin/settld-verify.js`
+- Release authenticity CLI: `packages/artifact-verify/bin/settld-release.js`
+- Release conformance runner: `node conformance/v1/run-release.mjs --release-node-bin packages/artifact-verify/bin/settld-release.js`
+
+## Python
+
+- CLI: `reference/verifier-py/settld-verify-py`
+- Conformance runner: `node conformance/v1/run.mjs --bin reference/verifier-py/settld-verify-py`
+
+## Parity policy
+
+- Verifier behavior is specified by:
+  - `STRICTNESS.md`
+  - `REFERENCE_VERIFIER_BEHAVIOR.md`
+  - `WARNINGS.md`
+  - `ERRORS.md` / `error-codes.v1.txt`
+- Conformance is the executable oracle; implementations must match the expected outcomes for all cases.
+- CLI output is a tooling contract (`VerifyCliOutput.v1`); output must be deterministic for the same inputs.
+
+Release authenticity verification (`settld-release verify`) is currently implemented in Node and gated by release conformance.

package/docs/spec/REFERENCE_VERIFIER_BEHAVIOR.md

@@ -0,0 +1,68 @@
+# Reference Verifier Behavior (v1)
+
+This document specifies **portable verifier behavior** for areas where independent implementations tend to drift (filesystem semantics, path handling, and manifest evaluation order).
+
+It complements:
+
+- `CANONICAL_JSON.md` (RFC 8785 / JCS)
+- `STRICTNESS.md` (strict vs non-strict contract)
+- `TRUST_ANCHORS.md` (trust root injection)
+- `WARNINGS.md` (warning code contract)
+- `conformance/v1/` (executable oracle)
+
+## Bundle-relative paths (manifest `files[].name`)
+
+The manifest `files[].name` values describe **bundle-relative** file paths.
+
+An implementation:
+
+1. MUST treat `files[].name` as a **portable** path using `/` as the separator (regardless of host OS).
+2. MUST reject any `files[].name` that is empty or not a string.
+3. MUST reject any `files[].name` that starts with `/` (absolute path).
+4. MUST reject any `files[].name` that contains `\` (backslash), `:` (Windows drive / URI ambiguity), or `\u0000` (NUL).
+5. MUST reject any `files[].name` that ends with `/` (directory marker).
+6. MUST reject any `files[].name` containing a `.` or `..` segment (path traversal).
+7. MUST resolve each `files[].name` against the bundle root and MUST reject any entry that escapes the bundle root (even if it “looks relative”).
+8. MUST treat a manifest containing a rejected path as a hard failure in **both** strict and non-strict modes.
+
+Conformance expects such failures to surface as `MANIFEST_PATH_INVALID`.
+
+## Duplicate manifest entries
+
+1. MUST treat duplicate `files[].name` values as invalid.
+2. MUST treat duplicate-path manifests as a hard failure in **both** strict and non-strict modes.
+
+Conformance expects such failures to surface as `MANIFEST_DUPLICATE_PATH`.
+
+## Symlinks
+
+1. MUST NOT follow filesystem symlinks when verifying a manifest-listed file.
+2. MUST treat any manifest-listed path that resolves to a symlink (at the filesystem level) as invalid in **both** strict and non-strict modes (this is a security invariant, not a compatibility affordance).
+
+Conformance expects such failures to surface as `MANIFEST_SYMLINK_FORBIDDEN`.
+
+## File hashing semantics
+
+1. MUST hash file contents as **raw bytes** (no newline normalization, no UTF-8 re-encoding).
+2. MUST treat missing files referenced by the manifest as verification failures.
+3. MUST ignore filesystem metadata (mtime, permissions) for hashing and matching purposes.
+
+## Manifest evaluation order (error precedence)
+
+To keep behavior stable and portable, implementations:
+
+1. MUST validate manifest structure (path validity and duplicate-path checks) **before** reporting hash-binding mismatches (for example, before `manifestHash mismatch` / attestation binding checks).
+2. MUST then compute and compare `manifestHash` using canonical JSON (RFC 8785) exactly as specified in `ProofBundleManifest.v1.md` / `FinancePackBundleManifest.v1.md`.
+
+This ordering prevents ambiguous “first failure wins” behavior across implementations and is relied upon by `conformance/v1/`.
+
+## Trust anchors (portable minimum)
+
+1. MUST support out-of-band injection of trusted governance roots via `SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON` (see `TRUST_ANCHORS.md`).
+2. MUST treat missing trusted governance roots as a hard failure in strict mode when governance-root signatures are required.
+
+## Strict vs non-strict (portable minimum)
+
+1. MUST apply strict/non-strict downgrades only where explicitly documented in `STRICTNESS.md`.
+2. MUST NOT downgrade the security invariants in this document (path traversal, duplicate paths, symlink refusal).
+

package/docs/spec/REMOTE_SIGNER.md

@@ -0,0 +1,66 @@
+# Remote signer (tooling contract)
+
+This document specifies the **RemoteSigner API** used by producer tooling (`settld-produce`) to obtain signatures without storing private keys on disk.
+
+This is a tooling/config surface (not a bundle protocol object). Verifiers do not change: they still verify signatures using **public keys** and **trust anchors**.
+
+## Goals
+
+- Allow bundle production with **no private key material on disk** (CI-friendly).
+- Ensure signing requests are **purpose-bound** (avoid turning the signer into a generic signing oracle).
+- Keep requests deterministic and auditable via a stable request shape.
+
+## Endpoints (v1)
+
+### `GET /v1/public-key?keyId=<keyId>`
+
+Return the public key PEM for the requested key id.
+
+Response: `RemoteSignerPublicKeyResponse.v1` (see `docs/spec/schemas/RemoteSignerPublicKeyResponse.v1.schema.json`).
+
+### `POST /v1/sign`
+
+Sign the provided message bytes under a specific key and purpose.
+
+Request: `RemoteSignerSignRequest.v1` (see `docs/spec/schemas/RemoteSignerSignRequest.v1.schema.json`).
+
+Response: `RemoteSignerSignResponse.v1` (see `docs/spec/schemas/RemoteSignerSignResponse.v1.schema.json`).
+
+## Purpose binding (required)
+
+Remote signers **MUST** refuse signing requests with unknown `purpose` values.
+
+Producer tools set `purpose` to one of:
+
+- `event_payload`
+- `governance_policy`
+- `revocation_list`
+- `timestamp_proof`
+- `pricing_matrix`
+- `bundle_head_attestation`
+- `verification_report`
+- `settlement_decision_report`
+
+## Security notes
+
+- The `messageBase64` value is **the exact bytes signed**. For Settld bundle objects this is typically `sha256(canonical_json)` represented as raw 32 bytes.
+- Signers should log: `requestId`, `keyId`, `purpose`, and selected `context` fields for auditability.
+- Remote signer endpoints should be protected with authentication/authorization (otherwise they are a signing oracle).
+
+## Authentication (recommended)
+
+For HTTP signers, producer tooling can attach a bearer token and custom headers:
+
+- `--signer-auth bearer --signer-token-env SETTLD_SIGNER_TOKEN`
+- `--signer-auth bearer --signer-token-file /path/to/token.txt`
+- `--signer-header "X-Request-Source: ci"`
+
+Tokens and secret header values are tooling-only; they must never be written into bundles or CLI JSON outputs.
+
+## Local-process / stdio signers
+
+Producer tooling also supports invoking a signer as a local process (no HTTP) where the signer reads a JSON request from stdin and prints JSON to stdout.
+
+This mode is designed for CI environments where binding/listening to local sockets may be restricted, and for integrations where the signer itself talks to an HSM/KMS.
+
+Note: some sandboxed CI environments disable piping stdin into child processes. The reference dev signer (`settld-signer-dev`) supports `--request-json-base64 <b64>` to avoid stdin piping in those environments.