@totemsdk/proofgraph 1.0.1 → 1.1.1

package/dist/cjs/durable-store.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * Durable `ProofGraphStoragePort` adapter for @totemsdk/proofgraph.
+ *
+ * Implements RFC-007 G8 / §4.3: graph + reverse node index are persisted over a
+ * shared `StorageAdapter`, with restart recovery and concurrent-update safety
+ * (CAS guards on the head pointer and node index, serialized per adapter).
+ *
+ * Layout (single `StorageAdapter`, prefixed keys):
+ *   graph:<graphId>          { json, savedAt }   immutable content-addressed record
+ *   node:<nodeId>            { graphId, savedAt } reverse index (most-recent
+ *                           snapshot that contains the node)
+ *   head                     { graphId, savedAt } most-recent saved graph
+ *
+ * `load()` runs `importProofGraph`, which validates every node/edge and
+ * recomputes the graphId — a tampered or truncated record surfaces as
+ * `StorageError` `corrupt`, never as `not-found` (RFC-007 §4.2 strict).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDurableProofGraphStore = createDurableProofGraphStore;
+const types_1 = require("@totemsdk/storage/types");
+const errors_1 = require("@totemsdk/storage/errors");
+const io_js_1 = require("./io.js");
+const DEFAULT_NAMESPACE = 'totem_proofgraph:v1:';
+const GRAPH_PREFIX = 'graph:';
+const NODE_PREFIX = 'node:';
+const HEAD_KEY = 'head';
+/** Per-adapter mutation lock so concurrent saves never interleave (wots-lease pattern). */
+const storageTails = new WeakMap();
+function withStorageLock(storage, fn) {
+    const previous = storageTails.get(storage) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolve) => { release = resolve; });
+    storageTails.set(storage, previous.then(() => gate));
+    return previous.then(() => fn()).finally(release);
+}
+function isCasStore(adapter) {
+    return typeof adapter.conditionalUpdate === 'function';
+}
+/**
+ * Create a durable `ProofGraphStoragePort` over a CAS-capable adapter.
+ *
+ * The head pointer and every reverse-index entry are guarded with the
+ * adapter's `conditionalUpdate`, and all mutations run serialized per adapter,
+ * so concurrent saves never clobber a newer graph. A non-CAS or low-durability
+ * adapter is rejected at construction (RFC-007 §4.2 no-silent-downgrade).
+ */
+function createDurableProofGraphStore(adapter, options = {}) {
+    const namespace = options.namespace ?? DEFAULT_NAMESPACE;
+    if (typeof adapter.capabilities === 'object') {
+        (0, types_1.assertCapabilities)(adapter, {
+            acknowledge: options.requireAckMode ?? 'durably-acknowledged',
+            atomic: true,
+            conditional: true,
+        });
+    }
+    if (!isCasStore(adapter)) {
+        throw new Error('createDurableProofGraphStore requires a CAS-capable storage adapter (CasStore.conditionalUpdate)');
+    }
+    const cas = adapter.conditionalUpdate.bind(adapter);
+    const graphKey = (graphId) => `${namespace}${GRAPH_PREFIX}${graphId}`;
+    const nodeKey = (nodeId) => `${namespace}${NODE_PREFIX}${nodeId}`;
+    const headKey = () => `${namespace}${HEAD_KEY}`;
+    /** Strictly-increasing savedAt so concurrent saves have deterministic order. */
+    let lastSavedAt = 0;
+    const nextSavedAt = () => {
+        const now = Date.now();
+        lastSavedAt = now > lastSavedAt ? now : lastSavedAt + 1;
+        return lastSavedAt;
+    };
+    function parseGraph(graphId, raw) {
+        if (typeof raw !== 'string' && (typeof raw !== 'object' || raw === null || typeof raw.json !== 'string')) {
+            throw new errors_1.StorageError(`proofgraph record "${graphId}" is malformed`, 'corrupt', { key: graphKey(graphId) });
+        }
+        const json = typeof raw === 'string' ? raw : raw.json;
+        try {
+            return (0, io_js_1.importProofGraph)(json);
+        }
+        catch (err) {
+            throw new errors_1.StorageError(`proofgraph record "${graphId}" failed validation: ${err.message}`, 'corrupt', { key: graphKey(graphId), cause: err });
+        }
+    }
+    async function loadUnchecked(graphId) {
+        const raw = await adapter.get(graphKey(graphId));
+        if (raw === null || raw === undefined)
+            return null;
+        return parseGraph(graphId, raw);
+    }
+    async function loadGraphForNode(nodeId) {
+        const entry = await adapter.get(nodeKey(nodeId));
+        if (entry === null || entry === undefined)
+            return null;
+        return loadUnchecked(entry.graphId);
+    }
+    async function writeIndexIfNewer(key, next) {
+        await cas(key, (current) => {
+            if (current && current.savedAt > next.savedAt)
+                return { abort: 'older snapshot' };
+            return { next };
+        });
+    }
+    return {
+        async save(graph) {
+            const savedAt = nextSavedAt();
+            return withStorageLock(adapter, async () => {
+                // Immutable content-addressed record first (idempotent, safe on retry).
+                const record = { json: (0, io_js_1.exportProofGraph)(graph), savedAt };
+                await adapter.set(graphKey(graph.graphId), record);
+                // Reverse index: most-recent snapshot wins (CAS, never clobbers newer).
+                for (const node of graph.nodes) {
+                    await writeIndexIfNewer(nodeKey(node.id), { graphId: graph.graphId, savedAt });
+                }
+                // Head pointer: does not move backwards.
+                await writeIndexIfNewer(headKey(), { graphId: graph.graphId, savedAt });
+            });
+        },
+        async load(graphId) {
+            return loadUnchecked(graphId);
+        },
+        async findByNodeId(id) {
+            return loadGraphForNode(id);
+        },
+        async latest() {
+            const head = await adapter.get(headKey());
+            if (head === null || head === undefined)
+                return null;
+            return loadUnchecked(head.graphId);
+        },
+        async listGraphIds() {
+            const prefix = `${namespace}${GRAPH_PREFIX}`;
+            const ids = [];
+            for (const key of await adapter.keys()) {
+                if (!key.startsWith(prefix))
+                    continue;
+                ids.push(key.slice(prefix.length));
+            }
+            return ids.sort();
+        },
+        async recover() {
+            return withStorageLock(adapter, async () => {
+                const report = { recoveredHead: false, cleanedIndexKeys: 0 };
+                const graphs = await this.listGraphIds();
+                const head = await adapter.get(headKey());
+                // 1. Head pointer: if absent but graphs exist, adopt the newest record.
+                if ((head === null || head === undefined) && graphs.length > 0) {
+                    let newest = null;
+                    for (const graphId of graphs) {
+                        const record = await adapter.get(graphKey(graphId));
+                        if (!record)
+                            continue;
+                        if (!newest || record.savedAt > newest.savedAt) {
+                            newest = { graphId, savedAt: record.savedAt };
+                        }
+                    }
+                    if (newest) {
+                        await writeIndexIfNewer(headKey(), newest);
+                        report.recoveredHead = true;
+                    }
+                }
+                // 2. Drop reverse-index entries pointing at absent graph records.
+                const nodePrefix = `${namespace}${NODE_PREFIX}`;
+                for (const key of await adapter.keys()) {
+                    if (!key.startsWith(nodePrefix))
+                        continue;
+                    const entry = await adapter.get(key);
+                    if (!entry)
+                        continue;
+                    const graphRecord = await adapter.get(graphKey(entry.graphId));
+                    if (graphRecord === null || graphRecord === undefined) {
+                        await adapter.remove(key);
+                        report.cleanedIndexKeys++;
+                    }
+                }
+                return report;
+            });
+        },
+    };
+}

package/dist/cjs/evidence.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Durable evidence-chain owner for @totemsdk/proofgraph (RFC-007 G8 / §4.3).
+ *
+ * Evidence *bytes* are owned by the minimal `ArtifactStore` over a pluggable
+ * backend; graph references alone do not satisfy the flight-evidence gate. This
+ * module wires a ProofGraph's `evidence` nodes to content-addressed artifacts,
+ * and restores the bytes on demand with commit-time digest verification.
+ *
+ * Restore semantics (RFC-007 §4.3): `corrupt` (bytes present but digest
+ * mismatch — tampered or truncated) is surfaced strictly, never collapsed into
+ * `not-found` (bytes absent); `unavailable` (backend unreachable, or the
+ * backend deleted a blob the local index still references) is also surfaced.
+ */
+import type { ProofGraph } from './types.js';
+import { ArtifactStore } from '@totemsdk/storage/artifacts';
+import type { ArtifactRef } from '@totemsdk/storage/artifacts';
+import type { StorageAdapter } from '@totemsdk/core';
+/**
+ * RFC-007 Amendment A (A3): the enforced binding between a claim's commitment
+ * and the artifact that addresses it.
+ *
+ * Invariant: `contentHash === artifact.digest`. `assertEvidenceBinding` throws
+ * `StorageError('corrupt')` when it does not hold, so an unrecoverable
+ * commitment cannot be constructed or restored.
+ */
+export interface EvidenceArtifactBinding {
+    readonly nodeId: string;
+    /** The commitment from the claim (hex, with or without `0x`). */
+    readonly contentHash: string;
+    /** The content-addressed artifact; `artifact.digest` must equal `contentHash`. */
+    readonly artifact: ArtifactRef;
+}
+export declare function normalizeEvidenceHash(hash: string): string;
+/** Throws `StorageError('corrupt')` unless `contentHash === artifact.digest`. */
+export declare function assertEvidenceBinding(binding: EvidenceArtifactBinding): void;
+export interface ProofGraphEvidenceStoreOptions {
+    /** Namespace the ArtifactStore writes artifact bytes under. */
+    namespace?: string;
+    /**
+     * true (default) — a `corrupt` or `unavailable` evidence read throws
+     * `StorageError` (never fail-open). `not-found` is always returned as a
+     * result, never thrown. Set false to return audit-able results instead.
+     */
+    strict?: boolean;
+}
+/** Per-evidence-node restore result. */
+export interface ProofGraphEvidenceResult {
+    nodeId: string;
+    status: 'ok' | 'not-found' | 'corrupt' | 'unavailable';
+    ref?: ArtifactRef;
+    /** The claim commitment this evidence is bound to, when known. */
+    contentHash?: string;
+    bytes?: Uint8Array;
+    message?: string;
+}
+export interface PutEvidenceOptions {
+    /**
+     * Explicit commitment per node. Falls back to the evidence node's
+     * `data.contentHash` (set by `addProof`). When a commitment is known, the
+     * stored bytes MUST hash to it and the artifact digest MUST equal it, or the
+     * put throws `StorageError('corrupt')`.
+     */
+    contentHashFor?: (nodeId: string) => string | undefined;
+    /**
+     * When true, every evidence node must have a commitment — a missing
+     * commitment throws. Default false (back-compat for nodes without one).
+     */
+    requireContentHash?: boolean;
+}
+export interface ProofGraphEvidenceStore {
+    /**
+     * Persist evidence bytes for every `evidence` node of `graph`.
+     * `bytesFor` maps a node id to the bytes to store; nodes with no bytes are
+     * skipped. When a commitment is known (node `data.contentHash` or
+     * `options.contentHashFor`), the claim→hash→artifact binding is enforced:
+     * `sha3_256(bytes) === contentHash === artifact.digest`.
+     * Returns the refs persisted, in graph node order.
+     */
+    putEvidence(graph: ProofGraph, bytesFor: (nodeId: string) => Uint8Array | undefined, options?: PutEvidenceOptions): Promise<ArtifactRef[]>;
+    /**
+     * Restore evidence bytes for every `evidence` node of `graph`, verifying
+     * each artifact's committed digest on read. With `strict` (default), corrupt
+     * or unavailable reads throw; otherwise a per-node result is returned.
+     */
+    restoreEvidence(graph: ProofGraph): Promise<ProofGraphEvidenceResult[]>;
+    /** Count of local index entries (persisted evidence mappings). */
+    listCount(): Promise<number>;
+}
+export declare function createProofGraphEvidenceStore(artifacts: ArtifactStore, index: StorageAdapter, options?: ProofGraphEvidenceStoreOptions): ProofGraphEvidenceStore;

package/dist/cjs/evidence.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Durable evidence-chain owner for @totemsdk/proofgraph (RFC-007 G8 / §4.3).
+ *
+ * Evidence *bytes* are owned by the minimal `ArtifactStore` over a pluggable
+ * backend; graph references alone do not satisfy the flight-evidence gate. This
+ * module wires a ProofGraph's `evidence` nodes to content-addressed artifacts,
+ * and restores the bytes on demand with commit-time digest verification.
+ *
+ * Restore semantics (RFC-007 §4.3): `corrupt` (bytes present but digest
+ * mismatch — tampered or truncated) is surfaced strictly, never collapsed into
+ * `not-found` (bytes absent); `unavailable` (backend unreachable, or the
+ * backend deleted a blob the local index still references) is also surfaced.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeEvidenceHash = normalizeEvidenceHash;
+exports.assertEvidenceBinding = assertEvidenceBinding;
+exports.createProofGraphEvidenceStore = createProofGraphEvidenceStore;
+const errors_1 = require("@totemsdk/storage/errors");
+const core_1 = require("@totemsdk/core");
+const DEFAULT_NS = 'totem-proofgraph-evidence';
+const INDEX_PREFIX = 'totem_proofgraph_evidence:v1:';
+function normalizeEvidenceHash(hash) {
+    return hash.replace(/^0x/i, '').toLowerCase();
+}
+/** Throws `StorageError('corrupt')` unless `contentHash === artifact.digest`. */
+function assertEvidenceBinding(binding) {
+    if (normalizeEvidenceHash(binding.contentHash) !== normalizeEvidenceHash(binding.artifact.digest)) {
+        throw new errors_1.StorageError(`evidence binding mismatch for node "${binding.nodeId}": contentHash ${binding.contentHash} !== artifact.digest ${binding.artifact.digest}`, 'corrupt', { key: binding.nodeId });
+    }
+}
+function evidenceNodeIds(graph) {
+    return graph.nodes.filter((node) => node.type === 'evidence').map((node) => node.id);
+}
+/** The claim commitment carried on an evidence node (`data.contentHash`). */
+function nodeContentHash(graph, nodeId) {
+    const value = graph.nodes.find((node) => node.id === nodeId)?.data?.contentHash;
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function createProofGraphEvidenceStore(artifacts, index, options = {}) {
+    if (!artifacts.capabilities.writable) {
+        throw new Error('createProofGraphEvidenceStore requires a writable artifact store');
+    }
+    const namespace = options.namespace ?? DEFAULT_NS;
+    const strict = options.strict ?? true;
+    const indexKey = (nodeId) => `${INDEX_PREFIX}${nodeId}`;
+    return {
+        async putEvidence(graph, bytesFor, options = {}) {
+            const refs = [];
+            for (const nodeId of evidenceNodeIds(graph)) {
+                const bytes = bytesFor(nodeId);
+                if (!bytes)
+                    continue;
+                const contentHash = options.contentHashFor?.(nodeId) ?? nodeContentHash(graph, nodeId);
+                if (!contentHash && options.requireContentHash) {
+                    throw new errors_1.StorageError(`evidence commitment missing for node "${nodeId}"`, 'corrupt', { key: indexKey(nodeId) });
+                }
+                // Byte-identity invariant: the stored bytes must hash to the commitment.
+                const digest = (0, core_1.toHex)((0, core_1.sha3_256)(bytes));
+                if (contentHash && normalizeEvidenceHash(contentHash) !== digest) {
+                    throw new errors_1.StorageError(`evidence commitment mismatch for node "${nodeId}": sha3(bytes) ${digest} !== contentHash ${contentHash}`, 'corrupt', { key: indexKey(nodeId) });
+                }
+                const receipt = await artifacts.put(namespace, bytes).catch((err) => {
+                    throw new errors_1.StorageError(`evidence put failed for node "${nodeId}": ${err.message}`, 'write-failed', { key: indexKey(nodeId), cause: err });
+                });
+                if (contentHash) {
+                    // The artifact must address exactly the committed hash.
+                    assertEvidenceBinding({ nodeId, contentHash, artifact: receipt.ref });
+                }
+                const entry = {
+                    ref: receipt.ref,
+                    ...(contentHash ? { contentHash: normalizeEvidenceHash(contentHash) } : {}),
+                };
+                await index.set(indexKey(nodeId), entry);
+                refs.push(receipt.ref);
+            }
+            return refs;
+        },
+        async restoreEvidence(graph) {
+            const results = [];
+            const fail = (err) => {
+                if (err instanceof errors_1.StorageError)
+                    throw err;
+                throw new errors_1.StorageError(`evidence read failed: ${err.message}`, 'unavailable', { cause: err });
+            };
+            for (const nodeId of evidenceNodeIds(graph)) {
+                const entry = await index.get(indexKey(nodeId));
+                if (!entry) {
+                    results.push({ nodeId, status: 'not-found', message: 'no evidence artifact persisted for node' });
+                    continue;
+                }
+                const { ref, contentHash } = entry;
+                if (contentHash) {
+                    // Index-tamper guard: the enforced binding must still hold.
+                    assertEvidenceBinding({ nodeId, contentHash, artifact: ref });
+                }
+                const read = await artifacts.get(ref).catch(fail);
+                switch (read.status) {
+                    case 'ok':
+                        results.push({ nodeId, status: 'ok', ref, ...(contentHash ? { contentHash } : {}), bytes: read.bytes });
+                        break;
+                    case 'corrupt':
+                        if (strict) {
+                            throw new errors_1.StorageError(`evidence artifact corrupt for node "${nodeId}": ${read.message ?? 'digest mismatch'}`, 'corrupt', { key: indexKey(nodeId) });
+                        }
+                        results.push({ nodeId, status: 'corrupt', ref, message: read.message ?? 'digest mismatch' });
+                        break;
+                    case 'unavailable':
+                        if (strict) {
+                            throw new errors_1.StorageError(`evidence artifact unavailable for node "${nodeId}": ${read.message ?? 'backend unavailable'}`, 'unavailable', { key: indexKey(nodeId) });
+                        }
+                        results.push({ nodeId, status: 'unavailable', ref, message: read.message ?? 'backend unavailable' });
+                        break;
+                    case 'not-found':
+                        results.push({ nodeId, status: 'not-found', ref, message: read.message ?? 'evidence artifact not found' });
+                        break;
+                }
+            }
+            return results;
+        },
+        async listCount() {
+            let count = 0;
+            for (const key of await index.keys()) {
+                if (key.startsWith(INDEX_PREFIX))
+                    count++;
+            }
+            return count;
+        },
+    };
+}

package/dist/cjs/graph.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Proof graph mutation functions — all pure, all returning NEW graphs.
+ *
+ * Immutable pattern: every mutation returns a brand-new ProofGraph with a
+ * recomputed graphId. Nodes and edges are deduplicated by ID so adding the
+ * same proof twice is idempotent.
+ */
+import type { SignedProof } from '@totemsdk/proof';
+import type { SignedIdentityClaim, TotemIdentityDocument } from '@totemsdk/identity';
+import type { SignedManifest } from '@totemsdk/manifest';
+import type { ProofGraph, ProofGraphEdge, ProofGraphEdgeType, ProofGraphNodeType, ReceiptLikeInput, AnchorInput } from './types.js';
+/**
+ * Create an empty ProofGraph.
+ */
+export declare function createProofGraph(metadata?: Record<string, unknown>): ProofGraph;
+/**
+ * Attach or replace mutable metadata. Does NOT affect graphId.
+ */
+export declare function setGraphMetadata(graph: ProofGraph, metadata: Record<string, unknown>): ProofGraph;
+/**
+ * Build a ProofGraphEdge with a deterministic ID from its fields.
+ * Convenience helper so callers don't need to import computeEdgeId.
+ */
+export declare function buildEdge(type: ProofGraphEdgeType, from: string, to: string, proofId?: string, data?: Record<string, unknown>): ProofGraphEdge;
+/**
+ * Add a node directly (type + refId pair). Idempotent — skipped if the node already exists.
+ */
+export declare function addNode(graph: ProofGraph, type: ProofGraphNodeType, refId: string, data?: Record<string, unknown>): ProofGraph;
+/**
+ * Append a ProofGraphEdge and recompute graphId. Idempotent by edge ID.
+ * Spec API: addEdge(graph, edge). Use buildEdge() to construct the edge object.
+ */
+export declare function addEdge(graph: ProofGraph, edge: ProofGraphEdge): ProofGraph;
+/**
+ * Index a TotemIdentityDocument into the graph.
+ * Creates an 'identity' node with refId = doc.id.
+ */
+export declare function addIdentityDocument(graph: ProofGraph, doc: TotemIdentityDocument): ProofGraph;
+/**
+ * Index a SignedProof into the graph.
+ *
+ * Nodes created:
+ *   proof      — proofId (stores the full SignedProof in .data)
+ *   identity   — signature.address (issuer key address)
+ *   subject    — proof.subject.id
+ *   evidence   — ev.id (one per evidence ref)
+ *   anchor     — anchor.hash (if present)
+ *
+ * Edges created (all referencing the proofId):
+ *   proves      proof → subject
+ *   issued_by   proof → identity (signer)
+ *   about       proof → subject
+ *   references  proof → evidence (one per evidence ref, in array order)
+ *   anchored_to proof → anchor (if present)
+ */
+export declare function addProof(graph: ProofGraph, signedProof: SignedProof): ProofGraph;
+/**
+ * Index a SignedIdentityClaim into the graph.
+ *
+ * Nodes created:
+ *   identity-claim — claim.id (stores the full signed claim in .data)
+ *   address        — issuer address
+ *   address/identity — target address (for delegates_to / rotates_to / revokes)
+ *
+ * Edges created based on claim.type:
+ *   all types    → issued_by  (claim-node → issuer address)
+ *   delegates_to → delegates_to edge (claim-node → delegated address)
+ *   revokes      → revokes edge      (claim-node → subject identity)
+ *   rotates_to   → controls edge     (claim-node → new address)
+ */
+export declare function addIdentityClaim(graph: ProofGraph, signedClaim: SignedIdentityClaim): ProofGraph;
+/**
+ * Index a SignedManifest into the graph.
+ *
+ * Nodes created:
+ *   manifest — computed manifest ID (stores manifest content in .data)
+ *   address  — resolved author/agent/operator address
+ *
+ * Edge created:
+ *   manifests_as  manifest → address
+ */
+export declare function addManifest(graph: ProofGraph, signedManifest: SignedManifest): ProofGraph;
+/**
+ * Add a signed manifest **revision** without collapsing other revisions.
+ *
+ * Creates:
+ *   manifest (logical)   refId = manifestId
+ *   manifest (revision)  refId = manifestEnvelopeId, data = { manifestId, manifestEnvelopeId, signedManifest }
+ *   address              resolved author/operator address
+ *   manifests_as         manifestId → address
+ *   revision_of          manifestEnvelopeId → manifestId
+ */
+export declare function addManifestRevision(graph: ProofGraph, signedManifest: SignedManifest): ProofGraph;
+/**
+ * Add a receipt-like node (payment, subscription, claim receipt) to the graph.
+ * If receipt.proofId is set, adds a 'supports' edge from the receipt to that proof.
+ */
+export declare function addReceiptLike(graph: ProofGraph, receipt: ReceiptLikeInput): ProofGraph;
+/**
+ * Add a standalone anchor node. If anchor.proofId is set, adds an 'anchored_to'
+ * edge from the proof to this anchor.
+ */
+export declare function addAnchor(graph: ProofGraph, anchor: AnchorInput): ProofGraph;