hachure 0.1.0

package/conformance/sf-reference-bundle-snapshot.json

@@ -0,0 +1,332 @@
+{
+  "now": "2026-06-10T00:00:00.000Z",
+  "input": {
+    "schemaVersion": 3,
+    "source": "kontour-surface-validation-fixtures",
+    "identityLinks": [
+      {
+        "subjects": [
+          {
+            "subjectType": "repo-surface",
+            "subjectId": "example/repo:src/api"
+          },
+          {
+            "subjectType": "release-channel",
+            "subjectId": "repo-governance:api"
+          }
+        ],
+        "reason": "API source and the named release channel describe the same surface."
+      }
+    ],
+    "claims": [
+      {
+        "id": "claim.repo-governance.api-proof",
+        "subjectType": "repo-surface",
+        "subjectId": "example/repo:src/api",
+        "surface": "repo-governance.developer-evidence",
+        "claimType": "software-evidence",
+        "fieldOrBehavior": "acceptanceCriteriaLane",
+        "value": "npm test passed for API surface change",
+        "createdAt": "2026-04-25T00:00:00.000Z",
+        "updatedAt": "2026-04-25T00:05:00.000Z",
+        "impactLevel": "high",
+        "currentIntegrityRef": "commit-or-run-id-placeholder",
+        "verificationPolicyId": "policy.software-evidence.commit",
+        "subjectAliases": [
+          {
+            "subjectType": "release-channel",
+            "subjectId": "repo-governance:api"
+          }
+        ],
+        "confidenceBasis": {
+          "sourceQuality": "strong",
+          "reviewerAuthority": "system",
+          "evidenceStrength": "strong",
+          "impactLevel": "high"
+        }
+      },
+      {
+        "id": "claim.field-attested-records.registration-status",
+        "subjectType": "attested-record",
+        "subjectId": "field-attested-records:denver-example-record",
+        "surface": "field-attested-records.public-data",
+        "claimType": "public-data-field",
+        "fieldOrBehavior": "registrationStatus",
+        "value": "OPEN",
+        "createdAt": "2026-04-01T00:00:00.000Z",
+        "updatedAt": "2026-04-01T00:00:00.000Z",
+        "impactLevel": "high",
+        "verificationPolicyId": "policy.public-data-field.short-lived",
+        "confidenceBasis": {
+          "sourceQuality": "strong",
+          "extractionConfidence": 0.92,
+          "corroborationCount": 1,
+          "reviewerAuthority": "operator",
+          "evidenceStrength": "moderate",
+          "impactLevel": "high"
+        }
+      },
+      {
+        "id": "claim.fact-resolution.w2-wages",
+        "subjectType": "fact",
+        "subjectId": "fact-resolution:demo-case-2025:w2.wages",
+        "surface": "fact-resolution.financial-facts",
+        "claimType": "verified-financial-fact",
+        "fieldOrBehavior": "w2.wages",
+        "value": 123456,
+        "createdAt": "2026-04-20T00:00:00.000Z",
+        "updatedAt": "2026-04-20T00:00:00.000Z",
+        "impactLevel": "critical",
+        "verificationPolicyId": "policy.financial-fact.historical",
+        "confidenceBasis": {
+          "sourceQuality": "strong",
+          "corroborationCount": 2,
+          "reviewerAuthority": "domain_expert",
+          "evidenceStrength": "strong",
+          "impactLevel": "critical"
+        }
+      },
+      {
+        "id": "claim.surface.future-console",
+        "subjectType": "roadmap-item",
+        "subjectId": "kontour-surface:hosted-console",
+        "surface": "surface.roadmap",
+        "claimType": "roadmap-capability",
+        "fieldOrBehavior": "implementationStatus",
+        "value": "planned",
+        "createdAt": "2026-04-25T00:00:00.000Z",
+        "updatedAt": "2026-04-25T00:00:00.000Z",
+        "impactLevel": "medium",
+        "verificationPolicyId": "policy.roadmap.manual"
+      }
+    ],
+    "evidence": [
+      {
+        "id": "evidence.repo-governance.test-output",
+        "claimId": "claim.repo-governance.api-proof",
+        "evidenceType": "test_output",
+        "method": "validation",
+        "sourceRef": "repo governance evidence check",
+        "sourceLocator": "npm test",
+        "excerptOrSummary": "84 tests passed for the verified repo state.",
+        "observedAt": "2026-04-25T00:05:00.000Z",
+        "collectedBy": "repo-governance",
+        "integrityRef": "commit-or-run-id-placeholder"
+      },
+      {
+        "id": "evidence.field-attested-records.source-excerpt",
+        "claimId": "claim.field-attested-records.registration-status",
+        "evidenceType": "source_excerpt",
+        "method": "observation",
+        "sourceRef": "https://example.org/camps/register",
+        "sourceLocator": "registration section",
+        "excerptOrSummary": "Registration is open now for summer sessions.",
+        "observedAt": "2026-04-01T00:00:00.000Z",
+        "collectedBy": "field-data-crawler"
+      },
+      {
+        "id": "evidence.field-attested-records.admin-attestation",
+        "claimId": "claim.field-attested-records.registration-status",
+        "evidenceType": "human_attestation",
+        "method": "attestation",
+        "sourceRef": "record steward review",
+        "sourceLocator": "FieldAttestation.registrationStatus",
+        "excerptOrSummary": "Admin approved the registration status from the source excerpt.",
+        "observedAt": "2026-04-01T00:10:00.000Z",
+        "collectedBy": "record-steward"
+      },
+      {
+        "id": "evidence.fact-resolution.document-citation",
+        "claimId": "claim.fact-resolution.w2-wages",
+        "evidenceType": "document_citation",
+        "method": "corroboration",
+        "sourceRef": "W-2 imported document",
+        "sourceLocator": "Box 1",
+        "excerptOrSummary": "W-2 Box 1 wages matched the verified fact value.",
+        "observedAt": "2026-04-20T00:00:00.000Z",
+        "collectedBy": "fact-importer",
+        "integrityRef": "document-hash-placeholder"
+      },
+      {
+        "id": "evidence.fact-resolution.calculation-trace",
+        "claimId": "claim.fact-resolution.w2-wages",
+        "evidenceType": "calculation_trace",
+        "method": "validation",
+        "sourceRef": "fact resolution package",
+        "sourceLocator": "verified_facts.w2.wages",
+        "excerptOrSummary": "Resolved fact was promoted to verified_facts before downstream analysis.",
+        "observedAt": "2026-04-20T00:15:00.000Z",
+        "collectedBy": "fact-resolution-service"
+      }
+    ],
+    "policies": [
+      {
+        "id": "policy.software-evidence.commit",
+        "claimType": "software-evidence",
+        "parentType": "developer-claim",
+        "requiredEvidence": [
+          "test_output"
+        ],
+        "requiredMethods": [
+          "validation"
+        ],
+        "requiresCorroboration": false,
+        "acceptanceCriteria": [
+          "evidence check passes for the affected commit or diff"
+        ],
+        "reviewAuthority": "repo policy",
+        "validityRule": {
+          "kind": "commit"
+        },
+        "stalenessTriggers": [
+          "new commit touches the same surface",
+          "evidence check changes"
+        ],
+        "conflictRules": [
+          "failed evidence check supersedes prior passing evidence"
+        ],
+        "impactLevel": "high",
+        "incompatibleStatuses": [
+          {
+            "statuses": [
+              "verified",
+              "rejected"
+            ],
+            "message": "A surface cannot be simultaneously verified and rejected at the same commit."
+          }
+        ]
+      },
+      {
+        "id": "policy.public-data-field.short-lived",
+        "claimType": "public-data-field",
+        "requiredEvidence": [
+          "source_excerpt",
+          "human_attestation"
+        ],
+        "requiredMethods": [
+          "observation",
+          "attestation"
+        ],
+        "requiresCorroboration": true,
+        "acceptanceCriteria": [
+          "field-level review or crawl approval"
+        ],
+        "reviewAuthority": "operator",
+        "validityRule": {
+          "kind": "duration",
+          "durationDays": 14
+        },
+        "stalenessTriggers": [
+          "source page changes",
+          "validity window expires",
+          "user report conflicts"
+        ],
+        "conflictRules": [
+          "new source excerpt conflicts with approved value"
+        ],
+        "impactLevel": "high"
+      },
+      {
+        "id": "policy.financial-fact.historical",
+        "claimType": "verified-financial-fact",
+        "requiredEvidence": [
+          "document_citation",
+          "calculation_trace"
+        ],
+        "requiredMethods": [
+          "corroboration",
+          "validation"
+        ],
+        "requiresCorroboration": true,
+        "acceptanceCriteria": [
+          "resolved fact promoted to verified fact"
+        ],
+        "reviewAuthority": "domain expert",
+        "validityRule": {
+          "kind": "historical"
+        },
+        "stalenessTriggers": [
+          "new source document imported",
+          "conflicting candidate appears"
+        ],
+        "conflictRules": [
+          "multi-candidate facts require manual resolution"
+        ],
+        "impactLevel": "critical"
+      },
+      {
+        "id": "policy.roadmap.manual",
+        "claimType": "roadmap-capability",
+        "requiredEvidence": [
+          "human_attestation"
+        ],
+        "requiredMethods": [
+          "attestation"
+        ],
+        "requiresCorroboration": false,
+        "acceptanceCriteria": [
+          "explicit roadmap acceptance"
+        ],
+        "reviewAuthority": "product owner",
+        "validityRule": {
+          "kind": "manual"
+        },
+        "stalenessTriggers": [
+          "roadmap changed"
+        ],
+        "conflictRules": [
+          "implementation claim without shipped evidence is unsupported"
+        ],
+        "impactLevel": "medium"
+      }
+    ],
+    "events": [
+      {
+        "id": "event.repo-governance.verified",
+        "claimId": "claim.repo-governance.api-proof",
+        "status": "verified",
+        "actor": "repo-governance",
+        "method": "evidence-check",
+        "evidenceIds": [
+          "evidence.repo-governance.test-output"
+        ],
+        "createdAt": "2026-04-25T00:05:00.000Z",
+        "verifiedAt": "2026-04-25T00:05:00.000Z"
+      },
+      {
+        "id": "event.field-attested-records.verified",
+        "claimId": "claim.field-attested-records.registration-status",
+        "status": "verified",
+        "actor": "record-steward",
+        "method": "field-attestation",
+        "evidenceIds": [
+          "evidence.field-attested-records.source-excerpt",
+          "evidence.field-attested-records.admin-attestation"
+        ],
+        "createdAt": "2026-04-01T00:10:00.000Z",
+        "verifiedAt": "2026-04-01T00:10:00.000Z"
+      },
+      {
+        "id": "event.fact-resolution.verified",
+        "claimId": "claim.fact-resolution.w2-wages",
+        "status": "verified",
+        "actor": "fact-resolution-service",
+        "method": "verified-fact-promotion",
+        "evidenceIds": [
+          "evidence.fact-resolution.document-citation",
+          "evidence.fact-resolution.calculation-trace"
+        ],
+        "createdAt": "2026-04-20T00:15:00.000Z",
+        "verifiedAt": "2026-04-20T00:15:00.000Z"
+      }
+    ]
+  },
+  "expect": {
+    "statusByClaimId": {
+      "claim.repo-governance.api-proof": "verified",
+      "claim.field-attested-records.registration-status": "stale",
+      "claim.fact-resolution.w2-wages": "verified",
+      "claim.surface.future-console": "unknown"
+    }
+  }
+}

package/conformance/sf-stale-duration.json

@@ -0,0 +1,76 @@
+{
+  "now": "2026-06-10T00:00:00.000Z",
+  "input": {
+    "schemaVersion": 3,
+    "source": "spec-conformance:stale-duration",
+    "claims": [
+      {
+        "id": "claim.public.field",
+        "subjectType": "data-field",
+        "subjectId": "dataset:registration-status",
+        "surface": "public-data.status",
+        "claimType": "public-data-field",
+        "fieldOrBehavior": "registrationStatus",
+        "value": "OPEN",
+        "createdAt": "2026-04-01T00:00:00.000Z",
+        "updatedAt": "2026-04-01T00:00:00.000Z",
+        "impactLevel": "high",
+        "verificationPolicyId": "policy.public-data-field.short-lived"
+      }
+    ],
+    "evidence": [
+      {
+        "id": "evidence.public.source-excerpt",
+        "claimId": "claim.public.field",
+        "evidenceType": "source_excerpt",
+        "method": "observation",
+        "sourceRef": "https://example.org/register",
+        "excerptOrSummary": "Registration is open for summer sessions.",
+        "observedAt": "2026-04-01T00:00:00.000Z",
+        "collectedBy": "crawler"
+      },
+      {
+        "id": "evidence.public.human-attestation",
+        "claimId": "claim.public.field",
+        "evidenceType": "human_attestation",
+        "method": "attestation",
+        "sourceRef": "record-steward review",
+        "excerptOrSummary": "Admin approved registration status from source excerpt.",
+        "observedAt": "2026-04-01T00:10:00.000Z",
+        "collectedBy": "record-steward"
+      }
+    ],
+    "policies": [
+      {
+        "id": "policy.public-data-field.short-lived",
+        "claimType": "public-data-field",
+        "requiredEvidence": ["source_excerpt", "human_attestation"],
+        "requiredMethods": ["observation", "attestation"],
+        "requiresCorroboration": true,
+        "acceptanceCriteria": ["field-level review or crawl approval"],
+        "reviewAuthority": "operator",
+        "validityRule": { "kind": "duration", "durationDays": 14 },
+        "stalenessTriggers": ["validity window expires"],
+        "conflictRules": [],
+        "impactLevel": "high"
+      }
+    ],
+    "events": [
+      {
+        "id": "event.public.verified",
+        "claimId": "claim.public.field",
+        "status": "verified",
+        "actor": "record-steward",
+        "method": "field-attestation",
+        "evidenceIds": ["evidence.public.source-excerpt", "evidence.public.human-attestation"],
+        "createdAt": "2026-04-01T00:10:00.000Z",
+        "verifiedAt": "2026-04-01T00:10:00.000Z"
+      }
+    ]
+  },
+  "expect": {
+    "statusByClaimId": {
+      "claim.public.field": "stale"
+    }
+  }
+}

package/conformance/sf-verified-commit.json

@@ -0,0 +1,68 @@
+{
+  "now": "2026-06-10T00:00:00.000Z",
+  "input": {
+    "schemaVersion": 3,
+    "source": "spec-conformance:verified-commit",
+    "claims": [
+      {
+        "id": "claim.api.rate-limit",
+        "subjectType": "api",
+        "subjectId": "public-api",
+        "surface": "api.guarantees",
+        "claimType": "software-evidence",
+        "fieldOrBehavior": "rate limit is enforced",
+        "value": "100 requests/minute",
+        "createdAt": "2026-04-25T00:00:00.000Z",
+        "updatedAt": "2026-04-25T00:05:00.000Z",
+        "impactLevel": "high",
+        "currentIntegrityRef": "commit:abc123",
+        "verificationPolicyId": "policy.software-evidence.commit"
+      }
+    ],
+    "evidence": [
+      {
+        "id": "evidence.api.rate-limit.test",
+        "claimId": "claim.api.rate-limit",
+        "evidenceType": "test_output",
+        "method": "validation",
+        "sourceRef": "ci:1847",
+        "excerptOrSummary": "Rate-limit tests passed.",
+        "observedAt": "2026-04-25T00:05:00.000Z",
+        "collectedBy": "ci",
+        "integrityRef": "commit:abc123"
+      }
+    ],
+    "policies": [
+      {
+        "id": "policy.software-evidence.commit",
+        "claimType": "software-evidence",
+        "requiredEvidence": ["test_output"],
+        "requiredMethods": ["validation"],
+        "requiresCorroboration": false,
+        "acceptanceCriteria": ["evidence check passes for the affected commit"],
+        "reviewAuthority": "repo policy",
+        "validityRule": { "kind": "commit" },
+        "stalenessTriggers": ["new commit touches the same surface"],
+        "conflictRules": [],
+        "impactLevel": "high"
+      }
+    ],
+    "events": [
+      {
+        "id": "event.api.rate-limit.verified",
+        "claimId": "claim.api.rate-limit",
+        "status": "verified",
+        "actor": "ci",
+        "method": "npm test",
+        "evidenceIds": ["evidence.api.rate-limit.test"],
+        "createdAt": "2026-04-25T00:05:00.000Z",
+        "verifiedAt": "2026-04-25T00:05:00.000Z"
+      }
+    ]
+  },
+  "expect": {
+    "statusByClaimId": {
+      "claim.api.rate-limit": "verified"
+    }
+  }
+}

package/index.mjs

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, dirname, basename } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Spec-side declaration of the status function version.
+// 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';
+
+// ---------------------------------------------------------------------------
+// Schemas — Map of record name (filename without .schema.json) → parsed JSON.
+// ---------------------------------------------------------------------------
+function loadSchemas() {
+  const schemasDir = join(__dirname, 'schemas');
+  const map = new Map();
+  for (const file of readdirSync(schemasDir).sort()) {
+    if (!file.endsWith('.schema.json')) continue;
+    const name = file.replace(/\.schema\.json$/, '');
+    map.set(name, JSON.parse(readFileSync(join(schemasDir, file), 'utf8')));
+  }
+  return map;
+}
+
+export const schemas = loadSchemas();
+
+// ---------------------------------------------------------------------------
+// Test vectors — Array of { name, vector } loaded from conformance/*.json.
+// Each vector: { now, input, expect: { statusByClaimId } }
+// ---------------------------------------------------------------------------
+function loadTestVectors() {
+  const conformanceDir = join(__dirname, 'conformance');
+  const vectors = [];
+  for (const file of readdirSync(conformanceDir).sort()) {
+    if (!file.endsWith('.json')) continue;
+    const name = basename(file, '.json');
+    const vector = JSON.parse(readFileSync(join(conformanceDir, file), 'utf8'));
+    vectors.push({ name, vector });
+  }
+  return vectors;
+}
+
+export const testVectors = loadTestVectors();

package/interop-in-toto.md

@@ -0,0 +1,133 @@
+# in-toto Interop: TrustBundle as an in-toto Statement v1
+
+**Module:** `@kontourai/surface` — `src/interop/in-toto.ts`
+**Public exports:** `toInTotoStatement`, `toDsseEnvelope`, `buildPaeBytes`, `parseDssePayload`
+
+---
+
+## Overview
+
+This module lets a producer publish a TrustBundle as a signed software-supply-chain
+attestation by wrapping it in the in-toto Statement v1 format and optionally enveloping
+it in DSSE (Dead Simple Signing Envelope).  It adds no new crypto dependency: all
+cryptographic operations are injected via a caller-supplied `Signer`.
+
+---
+
+## Statement shape
+
+`toInTotoStatement(bundle, { subjects })` produces an in-toto Statement v1:
+
+```jsonc
+{
+  "_type": "https://in-toto.io/Statement/v1",
+  "subject": [
+    {
+      "name": "<producer-chosen artifact reference>",
+      "digest": { "sha256": "<hex>" }
+    }
+  ],
+  "predicateType": "https://hachure.org/v1/bundle",
+  "predicate": { /* the TrustBundle verbatim */ }
+}
+```
+
+| Field | Value | Note |
+|---|---|---|
+| `_type` | `https://in-toto.io/Statement/v1` | Fixed; identifies the in-toto spec version. |
+| `subject` | caller-supplied `[{ name, digest }]` | At least one required. The producer knows which artifact digests are relevant; Surface does not infer them. |
+| `predicateType` | `https://hachure.org/v1/bundle` | Stable URI identifying Kontour trust bundles. |
+| `predicate` | the TrustBundle | The full bundle becomes the predicate; no fields are stripped or remapped. |
+
+The `predicateType` URI is stable for the lifetime of `hachure.org/v1`.  If the
+TrustBundle schema is broken (a new `apiVersion`), a new predicate type URI will be
+registered rather than reusing this one.
+
+---
+
+## DSSE envelope and PAE
+
+`toDsseEnvelope(statement, signer)` returns a DSSE envelope:
+
+```jsonc
+{
+  "payloadType": "application/vnd.in-toto+json",
+  "payload": "<base64-standard>",
+  "signatures": [
+    { "keyid": "<from signer>", "sig": "<base64 signature over PAE>" }
+  ]
+}
+```
+
+The payload is the base64-standard-encoded UTF-8 JSON serialisation of the Statement.
+
+**Pre-Authentication Encoding (PAE)** — the bytes handed to `signer.sign()`:
+
+```
+PAE(type, body) = "DSSEv1" SP DEC(byte_len(type)) SP type SP DEC(byte_len(body)) SP body
+```
+
+`buildPaeBytes(payloadType, bodyString): Uint8Array` is exported so callers can
+verify the pre-image independently or pass it directly to a WebCrypto
+`SubtleCrypto.sign()` call.
+
+### Injecting a signer
+
+```ts
+import { toInTotoStatement, toDsseEnvelope } from "@kontourai/surface/interop/in-toto";
+
+const signer = {
+  keyid: "my-key-id",
+  async sign(paeBytes: Uint8Array): Promise<string> {
+    // e.g. WebCrypto:
+    const raw = await crypto.subtle.sign("RSASSA-PKCS1-v1_5", privateKey, paeBytes);
+    return Buffer.from(raw).toString("base64");
+  },
+};
+
+const statement = toInTotoStatement(bundle, { subjects });
+const envelope = await toDsseEnvelope(statement, signer);
+```
+
+---
+
+## Sigstore / Rekor anchoring guidance
+
+The DSSE envelope produced by this module is structurally compatible with
+[Sigstore](https://sigstore.dev) tooling:
+
+1. **Sign with Sigstore Cosign** — Cosign's `attest` command accepts DSSE envelopes.
+   Pass `--type custom` and `--predicate <bundle.json>` together with the
+   `predicateType` URI to have Cosign wrap the bundle and upload the signed envelope
+   to the [Rekor](https://docs.sigstore.dev/logging/overview/) transparency log.
+
+2. **Upload to Rekor directly** — Use the Rekor `hashedrekord` or `dsse` entry type
+   with the DSSE envelope JSON.  Once uploaded, Rekor returns a `LogEntry` UUID that
+   can be stored in a `TrustBundle.proof` field (Kontour Resource Shape) as an
+   `IntegrityAnchor` of kind `transparency_log`.
+
+3. **Verify** — Retrieve the envelope from Rekor, decode `payload` from base64,
+   reconstruct PAE via `buildPaeBytes`, verify the signature against the signer's
+   public key, and check the `predicate` against the live `TrustBundle`.
+
+---
+
+## What Kontour adds on top of a frozen attestation
+
+An in-toto Statement is a **frozen attestation**: it captures a point-in-time
+assertion and anchors it cryptographically.  That is exactly what the DSSE envelope
+provides.
+
+A Kontour `TrustBundle` adds **living status** on top:
+
+| Frozen attestation (in-toto envelope) | Living bundle (Surface) |
+|---|---|
+| 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`). |
+| 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
+*anchor what was known at release time*; continue querying the live bundle to track
+*what is true now*.  An `InquiryRecord` (ADR 0003 §6) records the live status at
+inquiry time, linking the frozen and living views.