hachure 0.2.0 → 0.3.0

package/README.md

@@ -226,6 +226,20 @@ validates TrustBundle input against these schemas via `validateTrustBundle()`.
 
 ---
 
+## Profiles
+
+The core specification covers record shapes and status semantics. Profiles are
+optional, independently adoptable conventions for interop and transport. Adopting
+a profile requires no changes to core record shapes or the status function.
+
+| Profile | File | What it covers |
+|---|---|---|
+| in-toto interop | [interop-in-toto.md](interop-in-toto.md) | Wrapping a TrustBundle as a signed in-toto Statement v1 / DSSE envelope. |
+| Verification endpoint | [verification-endpoint.md](verification-endpoint.md) | Producer-served HTTP endpoint for receivers to fetch post-export event deltas. |
+| Assurance | [assurance.md](assurance.md) | Signing as a dial: L0/L1/L2 assurance levels, identity presentation, consumer policy, and human signing ceremony. |
+
+---
+
 ## Out of scope: future extension profiles
 
 The following producer domains are explicitly out of scope for this core specification.

package/assurance.md

@@ -0,0 +1,192 @@
+# Assurance — Extension Profile
+
+**Profile type:** OPTIONAL extension
+**Status:** draft
+**Namespace:** `hachure.org/v1`
+**Depends on:** core record shapes, [interop-in-toto.md](interop-in-toto.md), [verification-endpoint.md](verification-endpoint.md)
+
+---
+
+## Principle: signing is a dial, not a gate
+
+Unsigned records are valid core records.  Forever.  This profile defines how
+consumers express and verify *higher* assurance, and how policies weigh the
+levels against one another.  It is never a prerequisite for producing or
+consuming a TrustBundle.
+
+The assurance model exists because some environments want non-repudiation, audit
+trails that survive producer outages, or cryptographic evidence that a specific
+human exercised a specific authority.  Signing is the mechanism that provides
+those properties — but it is layered on top of an already-valid record, not a
+precondition for record validity.  A bundle with no signatures is not a
+degraded bundle; it is an L0 bundle.
+
+---
+
+## Assurance levels
+
+Three levels are defined.  Higher levels are a strict superset of lower levels:
+an L2 record satisfies any policy that accepts L1 or L0.
+
+### L0 — producer-asserted (default)
+
+The record is unsigned.  Assurance derives entirely from the trustworthiness of
+the transport channel and the producer identity declared in the bundle's
+`source` field.  All TrustBundles that do not carry a DSSE envelope are L0.
+This is the default; no annotation or flag is required.
+
+### L1 — identity-signed (keyless / ephemeral)
+
+The record is wrapped in a DSSE envelope (per
+[interop-in-toto.md](interop-in-toto.md)).  The signing key is short-lived and
+bound to an identity asserted by an OIDC provider at signing time — a CI
+workflow identity (`sub: repo:org/repo:ref:refs/heads/main`) or a human account
+(`sub: user@example.com`).  The certificate binds the ephemeral public key to
+that OIDC identity for the lifetime of the signing event.
+
+An L1 signature MAY be submitted to a public transparency log (Rekor or
+equivalent).  When it is, the resulting log entry UUID SHOULD be stored in the
+bundle's `proof` block as an `IntegrityAnchor` of kind `transparency_log`.
+Transparency-log inclusion is encouraged but not required for L1 conformance.
+
+The OIDC issuer and subject carried in the signing certificate are the
+authoritative identity for the signing event.  Implementations that verify L1
+signatures MUST surface a human-readable identity derived from those fields (see
+[Identity presentation](#identity-presentation) below).
+
+### L2 — held-key (org-controlled KMS/HSM)
+
+The record is wrapped in a DSSE envelope and signed with a long-lived key held
+in an org-controlled key-management system (a KMS or HSM).  The key is not
+ephemeral and is not tied to a per-operation OIDC token.  Key rotation and
+revocation are producer policy; this profile imposes no rotation schedule or
+revocation mechanism.
+
+L2 is appropriate for environments that cannot use public OIDC issuers or
+public transparency logs — air-gapped deployments, highly regulated environments
+with internal PKI requirements, or organisations that maintain their own CA.
+
+Because L2 keys are long-lived, verifiers must obtain the producer's public key
+through an out-of-band channel (internal PKI, a published key-distribution
+endpoint, a previously-trusted bundle).  This profile does not specify that
+channel.
+
+---
+
+## What gets signed
+
+Producers that adopt this profile MAY sign the following record types.  Signing
+any of them does not change the record's schema; the DSSE envelope wraps the
+serialised record and is carried alongside it, not embedded in it.
+
+### TrustBundles
+
+A full TrustBundle, including release bundles, is the primary signing target.
+Signing a bundle asserts that the named producer attests to the entire contents
+at the moment the envelope was created.  The in-toto Statement `subject` array
+SHOULD identify the bundle's `integrityAnchor.value` so downstream verifiers can
+correlate the envelope with a specific bundle revision.
+
+### Attestations
+
+A human's `ReviewOutcome` record carrying an `authorizing` block (ADR 0004) is
+an identity-signed attestation.  When the human's OIDC identity signs that
+record at the moment the authority is exercised (see
+[Human signing ceremony](#human-signing-ceremony)), the result is non-repudiable
+evidence that a specific identity made a specific decision.  This signed
+attestation is the appropriate content for the `identityEvidence` field on a
+Claim: it collapses "someone in this org approved this" into "this OIDC-verified
+identity approved this, cryptographically."
+
+### Verification-endpoint responses
+
+A producer serving a verification-endpoint response (see
+[verification-endpoint.md](verification-endpoint.md)) MAY wrap the response
+bundle in a DSSE envelope before returning it.  A signed response upgrades the
+assurance level of that endpoint from L0 to L1 or L2 according to the key type
+used.  Receivers SHOULD apply the same identity-presentation rules to a signed
+response as to any other signed record.
+
+---
+
+## Identity presentation
+
+Verifiers MUST surface a human-readable identity for every signed record they
+display or log.  Raw key fingerprints are not an acceptable primary display.
+
+Derive the display identity from the DSSE envelope's signing certificate:
+
+- For L1 (OIDC-backed): present the OIDC issuer and subject in a
+  human-readable form.  Examples:
+  - CI workflow: `"signed by github.com/org/repo workflow .github/workflows/release.yml"`
+  - Human account: `"signed by alice@example.com (GitHub)"`
+- For L2 (held key): present the key's subject DN or the KMS key alias as
+  configured by the producer.  Example: `"signed by CN=kontour-release-key, O=Kontour AI"`
+
+Displaying a fingerprint alongside the human-readable identity is permitted and
+encouraged for debugging.  It is not a substitute for the identity string as the
+primary display element.
+
+---
+
+## Consumer policy
+
+Assurance requirements are policy, not wire format.  A consumer expresses its
+requirements through a `VerificationPolicy` that declares a minimum assurance
+level among its `acceptanceCriteria`.  Mismatches between a record's actual
+level and the consumer's required level are **transparency gaps** — structured
+annotations that feed the status function's inputs and surface as `proposed` or
+`assumed` status rather than silent hard failures.
+
+This mirrors the admissibility doctrine in ADR 0004 §4: heuristics emit issues
+for human review; they do not silently decide.  A bundle whose assurance level
+falls below a consumer's requirement is recorded and flagged; a human or an
+automated policy layer decides whether to accept, escalate, or re-request.
+
+Concretely:
+
+- An L0 bundle that satisfies all policy evidence requirements reaches
+  `verified` normally.  If the consumer policy also requires L1, the consumer
+  annotates the gap; the status function sees the annotation as a transparency
+  gap and surfaces the claim at `proposed` pending a signed replacement.
+- An L1 or L2 bundle that satisfies all policy evidence requirements and meets
+  the assurance requirement reaches `verified` without annotation.
+- A signed record with an unverifiable or expired certificate does not silently
+  downgrade to L0.  The verification failure is itself a transparency gap,
+  flagged for the attention queue.
+
+---
+
+## Human signing ceremony
+
+When a human exercises authority — authoring a policy-change attestation,
+signing off a release bundle, or countersigning a ReviewOutcome — the signing
+gesture MUST be interactive and co-located in time with the authorizing act.
+
+The ceremony is an interactive OIDC browser flow: the same gesture as
+sign-in-with-Google or a Stripe payment confirmation.  The human authenticates
+to the OIDC provider, the provider issues a short-lived certificate bound to
+the authenticated identity, and that certificate signs the record.  The entire
+flow completes in the same session as the authorizing act; signing a record
+retroactively from a different session is not a conforming ceremony.
+
+Design intent: friction lands only where authority is exercised.  Routine
+read-only operations, status queries, and bundle consumption carry no signing
+requirement.  The ceremony surfaces once, at the moment of consequence.
+
+---
+
+## Non-goals
+
+- **Mandating a CA or transparency log.** This profile does not require a
+  specific certificate authority, a specific OIDC issuer, or submission to any
+  particular log.  L1 signing with a private OIDC issuer and no public log is
+  valid L1.
+- **Key custody prescriptions.** How a producer acquires, stores, rotates, or
+  revokes L2 keys is producer policy.  This profile does not specify HSM vendor,
+  key-rotation schedule, or revocation-distribution mechanism.
+- **Core-format changes.** No core record schema is altered by this profile.
+  Adopting the assurance profile requires no schema migration and no changes to
+  the status derivation function.
+- **Signing every record.** Signing is always optional.  Producers that sign
+  nothing are fully conformant with the core specification.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hachure",
-  "version": "0.2.0",
-  "description": "Hachure — canonical distribution of the open trust format: normative JSON schemas, conformance test vectors, and spec constants.",
+  "version": "0.3.0",
+  "description": "Hachure \u2014 canonical distribution of the open trust format: normative JSON schemas, conformance test vectors, and spec constants.",
   "type": "module",
   "main": "./index.mjs",
   "exports": {
@@ -15,7 +15,9 @@
     "index.mjs",
     "README.md",
     "status-function.md",
-    "interop-in-toto.md"
+    "interop-in-toto.md",
+    "verification-endpoint.md",
+    "assurance.md"
   ],
   "scripts": {
     "test": "node --test test/index.test.mjs"
@@ -30,5 +32,9 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hachure-org/spec.git"
   }
 }

package/verification-endpoint.md

@@ -0,0 +1,152 @@
+# Verification Endpoint — Extension Profile
+
+**Profile type:** OPTIONAL extension
+**Status:** draft
+**Namespace:** `hachure.org/v1`
+**Depends on:** core record shapes, [status-function.md](status-function.md), [interop-in-toto.md](interop-in-toto.md)
+
+---
+
+## Problem
+
+A TrustBundle is a point-in-time snapshot. Once exported, it carries no channel
+back to the producer. A receiver holding a bundle from last week has no way to
+learn that an authority trace was revoked yesterday, that a blocking evidence item
+was added the day after export, or that a claim has since been superseded. The
+receiver can re-run the status function as many times as it likes, but can only
+produce the same answer from the same stale inputs.
+
+This profile defines a lightweight channel for receivers to ask a producer: *what
+has changed since this bundle was issued?* The response delivers fresh inputs for
+the receiver's own status recomputation. It is testimony with a timestamp — a
+record of what the producer asserted at the moment of response. It is never a
+verdict the receiver is expected to obey.
+
+---
+
+## Discovery
+
+Producers supporting this profile expose a verification endpoint at a well-known
+path on the same host that issued the bundle:
+
+```
+GET https://<producer-host>/.well-known/hachure/verify?ref=<integrityRef>[&ref=...]
+```
+
+Multiple refs may be passed as repeated `ref` query parameters. For large sets,
+a POST variant is also allowed:
+
+```
+POST https://<producer-host>/.well-known/hachure/verify
+Content-Type: application/json
+
+{ "refs": ["<integrityRef>", ...] }
+```
+
+`integrityRef` is the integrity anchor value carried on a claim or bundle
+(`claim.integrityRef` or a bundle-level `integrityAnchor.value`).
+
+Producers MAY require authentication before serving a response. The response
+semantics defined in this profile are unchanged by the presence or absence of
+authentication; the receiver simply may not be able to reach the endpoint
+without valid credentials.
+
+---
+
+## Response shape
+
+The response body is a TrustBundle (see `schemas/trust-bundle.schema.json`)
+scoped to the records matching the requested refs, plus a `metadata` extension
+block. The bundle carries:
+
+- **`source`** — the producer identifier, matching `source` in the original bundle.
+- **`claims`** — all claims whose `integrityRef` was among the requested refs.
+  Each claim is returned in its current form as the producer knows it.
+- **`evidence`** and **`events`** — the delta since issuance where the producer
+  can supply it: new evidence items, new verification events, revocation events,
+  dispute events. Producers that do not track a delta MAY return the full current
+  set for the matched claims; receivers MUST NOT assume the absence of an item
+  means it was never present in the original bundle.
+- **`authorityTrace`** — current authority traces relevant to the matched claims,
+  including any that have been revoked since the original bundle was issued.
+- **`metadata`** — a free-form object on the bundle. This profile defines four
+  reserved keys within `metadata`:
+
+  | Key | Type | Required | Meaning |
+  |---|---|---|---|
+  | `respondedAt` | ISO 8601 string | yes | The timestamp at which the producer assembled this response. |
+  | `statusFunctionVersion` | string | yes | The status function version active at the producer at response time. |
+  | `requestedRefs` | string[] | yes | The full list of refs from the request, in order. |
+  | `unknownRefs` | string[] | yes | Refs from the request that the producer does not recognise. Must be present even if empty. |
+
+Unknown refs are reported in `unknownRefs` honestly. A producer MUST NOT silently
+omit a ref it does not recognise; it MUST include it in `unknownRefs` so the
+receiver can distinguish "no changes" from "not found."
+
+---
+
+## Assurance levels
+
+A response may be signed or unsigned. The two carry different weight.
+
+**Signed response.** A producer that wraps the response bundle in a DSSE envelope
+(per [interop-in-toto.md](interop-in-toto.md)) or attaches a `proof` block provides
+independently verifiable testimony. The receiver can verify the signature using the
+producer's public key before trusting any of the returned data. A signed response is
+as trustworthy as the key and the in-toto statement it protects.
+
+**Unsigned response.** A response delivered without a signature is producer-asserted
+only. Receivers SHOULD treat an unsigned response exactly as they would treat an
+unsigned TrustBundle received over a trusted channel: the transport provides some
+assurance, but the content itself is not independently verifiable. Do not give an
+unsigned response higher trust than the connection that delivered it.
+
+Key distribution and rotation are out of scope for this profile. The same backlog
+item that defers cryptographic signing for testimony records (ADR 0004, §Backlog)
+applies here: until key-management infrastructure exists, signing is OPTIONAL and
+unsigned responses are valid.
+
+---
+
+## Receiver rules
+
+1. **Re-run the status function.** Merge the response bundle's events and evidence
+   with the records in the held bundle, then call the status function over the
+   combined input at your own `now`. Do not treat any status value in the response
+   as a pre-computed verdict.
+
+2. **Fix `now` before evaluating.** The status function is `f(claim, evidence,
+   events, policy, authorityTrace, now)`. The response supplies updated inputs; the
+   receiver controls `now`. Two receivers evaluating the same response at different
+   instants may derive different statuses — that is expected and correct.
+
+3. **Cache by `respondedAt`; honour `max-age`.** A receiver MAY cache a response
+   keyed on the set of requested refs and the `respondedAt` timestamp. Producers MAY
+   include a standard HTTP `Cache-Control: max-age=<seconds>` header as a hint for
+   how long the response is expected to remain fresh. The hint is advisory; the
+   receiver decides its own staleness policy.
+
+4. **Retain the response as a record.** A verification response is itself a record
+   worth keeping. It is testimony: evidence of what the producer asserted at
+   `respondedAt`. A receiver that retains responses can reconstruct the history of
+   its knowledge — when it learned of a revocation, when a dispute event appeared —
+   which is useful for audit and for re-evaluating past InquiryRecords.
+
+5. **Treat signed and unsigned responses differently.** Apply the assurance-level
+   rules above before deciding how to weight the response in a combined evaluation.
+
+---
+
+## Non-goals
+
+- **Transport beyond HTTPS.** This profile specifies only the HTTP/HTTPS request
+  and response shape. Other transport mechanisms (gRPC, message queues, file
+  exchange) are not covered.
+- **Push and webhooks.** This profile is pull-only. Producers notify receivers
+  only when asked. Push notification channels are a separate concern.
+- **Transparency-log inclusion.** Including verification responses in a public
+  transparency log (Rekor or equivalent) is complementary and encouraged for
+  high-assurance scenarios, but it is not required by this profile and is not
+  specified here.
+- **Key management.** Public-key distribution, rotation, and revocation are out
+  of scope. See the ADR 0004 backlog note above.