@sanning/proof 0.6.0 → 0.8.0

package/dist/evidence.d.ts

@@ -12,6 +12,32 @@ export declare const ANCHOR_TRACE_BODY_TYPE_V1 = "sanning.anchor.trace/v1";
 /** Every anchor-trace body this kernel verifies. Order is newest-first. */
 export declare const ANCHOR_TRACE_BODY_TYPES: readonly ["sanning.anchor.trace/v2", "sanning.anchor.trace/v1"];
 export declare const EXPORT_BODY_TYPE = "sanning.evidence.export/v1";
+/**
+ * The Sanning-signed interval stamp body (evidence-bundle.md §5.2, DL-58).
+ *
+ * Its own `body_type` rather than a widened anchor-trace body, and the reason
+ * is the whole decision: an anchor-trace checkpoint carries a PRODUCER-signed
+ * `sanning.events/v1` envelope, and a stamp has no producer signature at all —
+ * Sanning places it, under DL-52, for a customer who holds no chain identity.
+ * The two rejected options were making `envelope` optional and synthesising an
+ * envelope that Sanning signs; the second would have made a Sanning
+ * attestation indistinguishable ON THE WIRE from a producer's, which is
+ * unrecoverable once witnessed.
+ */
+export declare const STAMP_TRACE_BODY_TYPE = "sanning.stamp.trace/v1";
+export declare const STAMP_EVIDENCE_BODY_TYPE = "sanning.stamp.evidence/v1";
+/**
+ * The version string INSIDE a witnessed stamp body — a different string from
+ * the `body_type` above, and the two are easy to confuse.
+ *
+ * `sanning.stamp.trace/v1` discriminates the BUNDLE BODY: it is the reader's
+ * dispatch key. `sanning.stamp/v1` is the control plane's own version of the
+ * bytes it hands a witness (`control-plane/src/stamp-tree.ts`,
+ * `STAMP_BODY_VERSION`). A `sanning.stamp.trace/v1` body pins the inner
+ * version to exactly this value: two answers to one question inside one
+ * signature is the §5.1.2 mixed-vocabulary reject, one layer down.
+ */
+export declare const STAMP_BODY_VERSION = "sanning.stamp/v1";
 export interface EvidenceIssuer {
     kind: string;
     tenant_id?: string;
@@ -85,6 +111,78 @@ export interface AnchorTraceBody {
     checkpoints: TraceCheckpoint[];
     events: TraceEvent[];
 }
+/**
+ * One sub-tree of a stamp, as the WITNESSED bytes carry it.
+ *
+ * Keyed in the body by a blinded reference (an HMAC under a per-org secret we
+ * never publish), so a reader learns that the org runs N agents and their
+ * relative volumes and learns no name. The RANGE is deliberately in the clear:
+ * it is what makes a later per-agent slice claim checkable by a third party
+ * without Sanning, and hiding it would put us back in the trust path.
+ */
+export interface StampSubtree {
+    first_leaf: number;
+    leaf_count: number;
+    /** Hex RFC-9162 root over this sub-tree's leaves alone. */
+    root: string;
+}
+/**
+ * The stamp body as the control plane witnesses it
+ * (`control-plane/src/stamp-tree.ts`, `StampBody`).
+ *
+ * Never read from the bundle directly — it is parsed out of `stamp_bytes`,
+ * which is the only authority. Present as a type so the parse has a shape.
+ */
+export interface StampBody {
+    stamp_version: string;
+    /** The org, BLINDED. Not an org id, and not reversible without the secret. */
+    org_ref: string;
+    interval_start: string;
+    interval_end: string;
+    merkle_root: string;
+    leaf_count: number;
+    subtrees: Record<string, StampSubtree>;
+}
+/** One entry of a `sanning.stamp.trace/v1` body's `stamps[]` (§5.2). */
+export interface StampEntry {
+    /**
+     * The stamp's identity within this bundle, DERIVED: hex SHA-256 of the
+     * DECODED `stamp_bytes`, not of the hex text. A verifier MUST recompute it.
+     */
+    stamp_ref: string;
+    /** Lowercase hex of the exact JCS bytes that were handed to the witness. */
+    stamp_bytes: string;
+    /**
+     * Where the stamp was witnessed, IF IT HAS BEEN (§5.1.1). Absent is honest:
+     * a sealed-but-unconfirmed stamp is witnessed by nobody, and an emitter that
+     * filled this in from a submission receipt would be claiming a chain
+     * position that does not exist yet.
+     */
+    anchor_ref?: AnchorRef;
+}
+export interface StampTraceBody {
+    stamps: StampEntry[];
+}
+/** §5.3's inclusion: §5.1's shape with `stamp_ref` as the join key. */
+export interface StampEvidenceInclusion {
+    leaf_hash: string;
+    leaf_index: number;
+    leaf_count: number;
+    audit_path: string[];
+    /** Resolves against `stamps[].stamp_ref` in the SAME body. */
+    stamp_ref: string;
+}
+export interface StampEvidenceEvent {
+    envelope: Envelope;
+    record_bytes?: string;
+    content?: string;
+    inclusion: StampEvidenceInclusion;
+}
+export interface StampEvidenceBody {
+    /** Byte-identical to §5.2.2 — one definition, one place to change. */
+    stamps: StampEntry[];
+    events: StampEvidenceEvent[];
+}
 export interface EvidenceBundle {
     spec_version: string;
     body_type: string;
@@ -149,6 +247,54 @@ export interface EventResult {
     ok: boolean;
     errors: string[];
 }
+/** One sub-tree's recomputed result (§5.2). */
+export interface StampSubtreeResult {
+    /** The blinded key the body spells it under. Meaningless without the org's secret. */
+    ref: string;
+    firstLeaf: number;
+    leafCount: number;
+    root: string;
+}
+/** One `stamps[]` entry's result (§5.2). */
+export interface StampResult {
+    /** The stamp's derived identity, as the bundle spells it. "" when unusable. */
+    stampRef: string;
+    /** The asserted `stamp_ref` equals SHA-256 of the decoded `stamp_bytes`. */
+    stampRefOk: boolean;
+    /**
+     * The witnessed bytes decoded, parsed, and re-canonicalized to themselves.
+     *
+     * The last clause is not pedantry. The plane stores these bytes as TEXT and
+     * replays them verbatim precisely because a round-trip through a normalizing
+     * serializer is not guaranteed to reproduce what was signed; a body that is
+     * not JCS-canonical is one that every re-deriving reader hashes differently.
+     */
+    bodyOk: boolean;
+    stampVersion: string | null;
+    intervalStart: string | null;
+    intervalEnd: string | null;
+    merkleRoot: string | null;
+    leafCount: number | null;
+    /**
+     * Every sub-tree range accounts for exactly one leaf of the stamp: the
+     * ranges sorted by `first_leaf` tile `[0, leaf_count)` with no gap and no
+     * overlap, and their counts sum to `leaf_count`.
+     */
+    subtreesOk: boolean;
+    subtrees: StampSubtreeResult[];
+    /**
+     * Where it was witnessed, or `null` for a stamp nothing has witnessed yet.
+     *
+     * `null` is NOT a failure and never an accusation — it is the honest state
+     * of every stamp for the first minutes of its life and the permanent state
+     * of every stamp when no witness is configured. It does hold the bundle at
+     * `partial`: a stamp is Sanning's own assertion until something independent
+     * carries it.
+     */
+    anchorRef: AnchorRef | null;
+    ok: boolean;
+    errors: string[];
+}
 export interface EvidenceBundleResult {
     status: EvidenceStatus;
     specVersionOk: boolean;
@@ -160,6 +306,7 @@ export interface EvidenceBundleResult {
     events: EventResult[];
     assertedStatus: string | null;
     export?: ExportResult;
+    stamps?: StampResult[];
     errors: string[];
 }
 export interface AttestationRecord {
@@ -304,6 +451,7 @@ export interface DisclosedContentResult {
  * know their payload is text decode it themselves and own that assumption.
  */
 export declare function disclosedContent(bundle: unknown, options?: VerifyEvidenceOptions): Promise<DisclosedContentResult>;
+export declare function resolveTraceEvents(bundle: unknown): TraceEvent[] | undefined;
 export interface ComposeVerdictResult {
     verdict: VerdictObject;
     sourceStatus: EvidenceStatus;