hachure 0.1.0 → 0.2.2

package/README.md

@@ -14,17 +14,17 @@ npm i -D hachure
 ```
 
 The package ships the normative JSON schemas, conformance test vectors, and the
-`STATUS_FUNCTION_VERSION` constant that ties implementations to a specific
+`statusFunctionVersion` constant that ties implementations to a specific
 algorithm revision.
 
 **Claiming conformance:** run the test vectors from `testVectors` against your
 implementation. For each vector, call your status-derivation function with
 `vector.input` and `vector.now`, then assert that the derived status for every
 claim ID matches `vector.expect.statusByClaimId`. Passing all vectors for a given
-`STATUS_FUNCTION_VERSION` is the bar for a conforming implementation.
+status function version is the bar for a conforming implementation.
 
 ```js
-import { testVectors, STATUS_FUNCTION_VERSION } from 'hachure';
+import { testVectors, statusFunctionVersion } from 'hachure';
 
 for (const { name, vector } of testVectors) {
   const results = deriveStatuses(vector.input, new Date(vector.now));
@@ -36,7 +36,6 @@ for (const { name, vector } of testVectors) {
 
 ---
 
-
 ## What this is
 
 Hachure is an open format for portable trust state. It defines how claims about
@@ -74,8 +73,8 @@ Resource Shape envelope. Product-specific records use product-scoped namespaces
 Pre-1.0: the format uses hard breaking changes rather than compatibility aliases.
 No forward or backward compatibility guarantees are made across versions. Version
 bumps are reflected in `schemaVersion` (an integer field in TrustBundle, currently
-`3`) and in `STATUS_FUNCTION_VERSION` (a string exported by the reference
-implementation, currently `"1"`).
+`3`) and in the status function version (a string exported by the reference
+implementation as `statusFunctionVersion`, currently `"1"`).
 
 ---
 
@@ -227,6 +226,19 @@ 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. |
+
+---
+
 ## Out of scope: future extension profiles
 
 The following producer domains are explicitly out of scope for this core specification.

package/index.mjs

@@ -2,15 +2,15 @@
  * hachure — canonical npm distribution of the Hachure trust format spec.
  *
  * Exports:
- *   STATUS_FUNCTION_VERSION  — spec-side declaration of the current status
- *                               derivation algorithm version. Reference
- *                               implementations must export a matching value.
- *   schemas                  — Map<recordName, parsedSchemaObject> for every
- *                               normative schema shipped with this package.
- *   testVectors              — Array<{name, vector}> of all conformance test
- *                               vectors. Each vector has `input`, `expect`, and
- *                               `now` fields; run them against your implementation
- *                               to claim conformance.
+ *   statusFunctionVersion  — spec-side declaration of the current status
+ *                             derivation algorithm version. Reference
+ *                             implementations must export a matching value.
+ *   schemas                — Map<recordName, parsedSchemaObject> for every
+ *                             normative schema shipped with this package.
+ *   testVectors            — Array<{name, vector}> of all conformance test
+ *                             vectors. Each vector has `input`, `expect`, and
+ *                             `now` fields; run them against your implementation
+ *                             to claim conformance.
  */
 
 import { readFileSync, readdirSync } from 'node:fs';
@@ -24,7 +24,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // Any implementation claiming conformance at this version must produce the
 // same status outputs as the test vectors for all cases in conformance/.
 // ---------------------------------------------------------------------------
-export const STATUS_FUNCTION_VERSION = '1';
+export const statusFunctionVersion = '1';
 
 // ---------------------------------------------------------------------------
 // Schemas — Map of record name (filename without .schema.json) → parsed JSON.

package/interop-in-toto.md

@@ -124,7 +124,7 @@ A Kontour `TrustBundle` adds **living status** on top:
 |---|---|
 | Status is sealed at signing time. | Status is recomputed from events at query time: `f(claim, events, policy, now)`. |
 | Tamper-evident; content cannot change. | Append-only; new events and evidence accumulate. |
-| Verifier trusts the signer's identity. | Verifier trusts the derivation algorithm (`STATUS_FUNCTION_VERSION`). |
+| Verifier trusts the signer's identity. | Verifier trusts the derivation algorithm (`statusFunctionVersion`). |
 | Useful for supply-chain audits and legal holds. | Useful for operational dashboards, gates, and consumer inquiries. |
 
 The two are complementary: embed the bundle in an in-toto envelope to

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hachure",
-  "version": "0.1.0",
-  "description": "Hachure — canonical distribution of the open trust format: normative JSON schemas, conformance test vectors, and spec constants.",
+  "version": "0.2.2",
+  "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,8 @@
     "index.mjs",
     "README.md",
     "status-function.md",
-    "interop-in-toto.md"
+    "interop-in-toto.md",
+    "verification-endpoint.md"
   ],
   "scripts": {
     "test": "node --test test/index.test.mjs"
@@ -30,5 +31,9 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hachure-org/spec.git"
   }
-}
+}

package/status-function.md

@@ -1,7 +1,7 @@
 # Status Derivation — Specification
 
 **Function:** `status = f(claim, evidence, events, policy, authorityTrace, now)`
-**Version constant:** `STATUS_FUNCTION_VERSION` (currently `"1"`)
+**Version constant:** `statusFunctionVersion` (currently `"1"`)
 **Source of truth:** `src/status.ts` in `@kontourai/surface`
 
 ---
@@ -9,7 +9,7 @@
 ## Principle
 
 Claim status is a pure, versioned, deterministic function (ADR 0003 §7). Given the
-same inputs and the same `STATUS_FUNCTION_VERSION`, any conforming implementation
+same inputs and the same status function version, any conforming implementation
 must derive the same status. There is no stored status field that overrides
 computation; the derived status is always recomputed from the input bundle at
 evaluation time.
@@ -20,7 +20,7 @@ no clock-tick events and no background expiry.
 
 Reproducibility guarantee: if two independent implementations receive the same
 `(claim, evidence, events, policies, authorityTrace, now)` and the same
-`STATUS_FUNCTION_VERSION`, they must return the same `TrustStatus`.
+status function version, they must return the same `TrustStatus`.
 
 ---
 
@@ -214,12 +214,12 @@ From weakest to strongest: `unknown` < `rejected` < `superseded` < `disputed` <
 
 ## Versioning
 
-`STATUS_FUNCTION_VERSION` is a string exported by `@kontourai/surface`. It is
+`statusFunctionVersion` is a string exported by `@kontourai/surface`. It is
 incremented when the algorithm changes in a way that could produce different outputs
 for the same inputs. `InquiryRecord.statusFunctionVersion` captures which version
 was active at resolution time, enabling re-evaluation when the algorithm version
 changes.
 
-Conforming implementations must declare which `STATUS_FUNCTION_VERSION` value they
+Conforming implementations must declare which status function version value they
 implement. Implementations claiming version `"1"` must satisfy all conformance
 cases in `spec/conformance/`.

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.