@private.me/xcontinuity 2.1.0

package/dist/cjs/provenance.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * @private.me/xcontinuity — Provenance (Ed25519 Signed Entries)
+ *
+ * Cryptographic provenance for chronicle entries using Ed25519 signatures
+ * via the Web Crypto API. Each entry can be signed by an agent, creating
+ * a verifiable chain of authorship and integrity.
+ *
+ * Uses native Web Crypto EdDSA (Node.js 16.9+, modern browsers).
+ * Zero external dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSigningKeyPair = generateSigningKeyPair;
+exports.publicKeyToAuthorRef = publicKeyToAuthorRef;
+exports.authorRefToPublicKey = authorRefToPublicKey;
+exports.canonicalEntryBytes = canonicalEntryBytes;
+exports.signEntry = signEntry;
+exports.verifyEntry = verifyEntry;
+exports.hashProvenance = hashProvenance;
+exports.verifyChainLink = verifyChainLink;
+const shared_1 = require("@private.me/shared");
+const errors_js_1 = require("./errors.js");
+/**
+ * Generate a new Ed25519 key pair for provenance signing.
+ */
+async function generateSigningKeyPair() {
+    const keyPair = await crypto.subtle.generateKey('Ed25519', true, ['sign', 'verify']);
+    return {
+        publicKey: keyPair.publicKey,
+        privateKey: keyPair.privateKey,
+    };
+}
+/**
+ * Export the public key as an AuthorRef (base64url-encoded 32-byte key).
+ */
+async function publicKeyToAuthorRef(publicKey) {
+    const raw = await crypto.subtle.exportKey('raw', publicKey);
+    return uint8ToBase64Url(new Uint8Array(raw));
+}
+/**
+ * Import an AuthorRef back to a CryptoKey for verification.
+ */
+async function authorRefToPublicKey(authorRef) {
+    const raw = base64UrlToUint8(authorRef);
+    return crypto.subtle.importKey('raw', raw.buffer, 'Ed25519', true, ['verify']);
+}
+/**
+ * Produce canonical bytes for a memory entry, suitable for signing.
+ *
+ * Deterministic serialization: sorted keys, UTF-8 encoded.
+ * Format: `key\0type\0valueBytes\0timestamp`
+ */
+function canonicalEntryBytes(key, value, timestamp, parentHash) {
+    const encoder = new TextEncoder();
+    const keyBytes = encoder.encode(key);
+    const valueStr = canonicalValueString(value);
+    const valueBytes = encoder.encode(valueStr);
+    const tsBytes = encoder.encode(String(timestamp));
+    // Total: key + \0 + value + \0 + timestamp [+ \0 + parentHash]
+    const parentLen = parentHash ? 1 + parentHash.length : 0;
+    const total = keyBytes.length + 1 + valueBytes.length + 1 + tsBytes.length + parentLen;
+    const buf = new Uint8Array(total);
+    let offset = 0;
+    buf.set(keyBytes, offset);
+    offset += keyBytes.length;
+    buf[offset++] = 0;
+    buf.set(valueBytes, offset);
+    offset += valueBytes.length;
+    buf[offset++] = 0;
+    buf.set(tsBytes, offset);
+    offset += tsBytes.length;
+    if (parentHash) {
+        buf[offset++] = 0;
+        buf.set(parentHash, offset);
+    }
+    return buf;
+}
+/**
+ * Sign a memory entry, producing a ProvenanceRecord.
+ */
+async function signEntry(key, value, privateKey, publicKey, parentHash) {
+    try {
+        const timestamp = Date.now();
+        const canonical = canonicalEntryBytes(key, value, timestamp, parentHash);
+        const signature = new Uint8Array(await crypto.subtle.sign('Ed25519', privateKey, canonical.buffer));
+        const author = await publicKeyToAuthorRef(publicKey);
+        return (0, shared_1.ok)({
+            author,
+            timestamp,
+            signature,
+            parentHash,
+        });
+    }
+    catch (e) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('INVALID_SIGNATURE', `Failed to sign entry: ${e instanceof Error ? e.message : String(e)}`));
+    }
+}
+/**
+ * Verify a provenance record against the entry data and author's public key.
+ */
+async function verifyEntry(key, value, provenance, publicKey) {
+    try {
+        if (!provenance.author) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('MISSING_AUTHOR', 'Provenance record has no author'));
+        }
+        const canonical = canonicalEntryBytes(key, value, provenance.timestamp, provenance.parentHash);
+        const valid = await crypto.subtle.verify('Ed25519', publicKey, provenance.signature.buffer, canonical.buffer);
+        return (0, shared_1.ok)(valid);
+    }
+    catch (e) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('INVALID_SIGNATURE', `Verification failed: ${e instanceof Error ? e.message : String(e)}`));
+    }
+}
+/**
+ * Compute the SHA-256 hash of a provenance record for chain linking.
+ */
+async function hashProvenance(provenance) {
+    const encoder = new TextEncoder();
+    const authorBytes = encoder.encode(provenance.author);
+    const tsBytes = encoder.encode(String(provenance.timestamp));
+    const parentLen = provenance.parentHash ? provenance.parentHash.length : 0;
+    const total = authorBytes.length + 1 + tsBytes.length + 1 + provenance.signature.length + parentLen;
+    const buf = new Uint8Array(total);
+    let offset = 0;
+    buf.set(authorBytes, offset);
+    offset += authorBytes.length;
+    buf[offset++] = 0;
+    buf.set(tsBytes, offset);
+    offset += tsBytes.length;
+    buf[offset++] = 0;
+    buf.set(provenance.signature, offset);
+    offset += provenance.signature.length;
+    if (provenance.parentHash) {
+        buf.set(provenance.parentHash, offset);
+    }
+    const hash = await crypto.subtle.digest('SHA-256', buf.buffer);
+    return new Uint8Array(hash);
+}
+/**
+ * Verify a parent hash chain link: the parentHash in the current entry
+ * must equal the hash of the previous entry's provenance.
+ */
+async function verifyChainLink(current, previous) {
+    if (!current.provenance?.parentHash) {
+        return (0, shared_1.ok)(true); // No chain link to verify (root entry)
+    }
+    if (!previous.provenance) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('HASH_CHAIN_BREAK', `Previous entry "${previous.key}" has no provenance to hash`));
+    }
+    const expectedHash = await hashProvenance(previous.provenance);
+    const matches = constantTimeEqual(current.provenance.parentHash, expectedHash);
+    if (!matches) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('HASH_CHAIN_BREAK', `Parent hash mismatch for entry "${current.key}"`));
+    }
+    return (0, shared_1.ok)(true);
+}
+/* ── Internal helpers ── */
+function canonicalValueString(value) {
+    if (value === null)
+        return 'null';
+    if (value instanceof Uint8Array)
+        return `bytes:${uint8ToBase64Url(value)}`;
+    if (typeof value === 'object')
+        return JSON.stringify(value, Object.keys(value).sort());
+    return String(value);
+}
+function uint8ToBase64Url(data) {
+    let binary = '';
+    for (let i = 0; i < data.length; i++) {
+        binary += String.fromCharCode(data[i]);
+    }
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64UrlToUint8(b64url) {
+    const b64 = b64url.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a[i] ^ b[i];
+    }
+    return diff === 0;
+}

package/dist/cjs/ratification.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * @private.me/xcontinuity — Ratification (TrustStore)
+ *
+ * Central store for trust-annotated memory entries.
+ * Integrates provenance (signing), trust tiers, chronicle (history),
+ * adjudicator (conflict resolution), and event hooks.
+ *
+ * Key flows:
+ *   write()  — store an entry with automatic trust tier assignment
+ *   ratify() — sign an entry, promoting it to 'ratified' tier
+ *   restore() — rebuild trust state from a chronicle
+ *   hypothesisMode() — sandbox for speculative writes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Hypothesis = exports.TrustStore = void 0;
+const shared_1 = require("@private.me/shared");
+const errors_js_1 = require("./errors.js");
+const trust_js_1 = require("./trust.js");
+const provenance_js_1 = require("./provenance.js");
+const chronicle_js_1 = require("./chronicle.js");
+const adjudicator_js_1 = require("./adjudicator.js");
+class TrustStore {
+    entries = new Map();
+    chronicle = new chronicle_js_1.Chronicle();
+    adjudicator;
+    defaultMaxAge;
+    listeners = new Map();
+    sequenceCounter = 0;
+    constructor(config = {}) {
+        this.adjudicator = config.adjudicator ?? new adjudicator_js_1.PolicyAdjudicator();
+        this.defaultMaxAge = config.defaultMaxAge;
+    }
+    /**
+     * Write an entry to the trust store.
+     *
+     * Assigns trust tier based on provenance, checks for contradictions
+     * against the chronicle, and emits events.
+     */
+    write(key, value, provenance, signatureVerified = false) {
+        const tier = (0, trust_js_1.baselineTier)(provenance, signatureVerified);
+        const oldEntry = this.entries.get(key);
+        // Check for contradictions
+        const contradictions = [];
+        if (oldEntry !== undefined) {
+            if ((0, chronicle_js_1.detectContradiction)(value, oldEntry.value)) {
+                contradictions.push(oldEntry.key);
+                this.emit('contradiction', {
+                    key,
+                    existing: oldEntry,
+                    incoming: { key, value, provenance, tier, contradictions, maxAge: this.defaultMaxAge },
+                });
+            }
+        }
+        const entry = {
+            key,
+            value,
+            provenance,
+            tier,
+            contradictions,
+            maxAge: this.defaultMaxAge,
+            ratifiedAt: tier === 'ratified' ? Date.now() : undefined,
+        };
+        this.entries.set(key, entry);
+        // Record in chronicle
+        const stateId = `entry-${this.sequenceCounter}`;
+        this.chronicle.appendWithContradictionCheck({
+            stateId,
+            sessionId: 'trust-store',
+            sequence: this.sequenceCounter++,
+            timestamp: Date.now(),
+            tags: [tier],
+            parentStateId: oldEntry ? `entry-${this.sequenceCounter - 2}` : undefined,
+        }, key, value, oldEntry?.value);
+        // Emit change event
+        this.emit('change', { key, oldEntry, newEntry: entry });
+        // Emit tier change if applicable
+        if (oldEntry && oldEntry.tier !== tier) {
+            this.emit('tierChange', {
+                key,
+                oldTier: oldEntry.tier,
+                newTier: tier,
+                reason: provenance ? 'provenance changed' : 'new write',
+            });
+        }
+        return (0, shared_1.ok)(entry);
+    }
+    /**
+     * Ratify an entry by signing it with Ed25519, promoting to 'ratified' tier.
+     */
+    async ratify(key, privateKey, publicKey) {
+        const existing = this.entries.get(key);
+        if (!existing) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('ENTRY_NOT_FOUND', `No entry for key "${key}"`));
+        }
+        // Sign the entry
+        const signResult = await (0, provenance_js_1.signEntry)(key, existing.value, privateKey, publicKey, existing.provenance?.parentHash);
+        if (!signResult.ok)
+            return signResult;
+        const oldTier = existing.tier;
+        const ratified = {
+            ...existing,
+            provenance: signResult.value,
+            tier: 'ratified',
+            ratifiedAt: Date.now(),
+        };
+        this.entries.set(key, ratified);
+        if (oldTier !== 'ratified') {
+            this.emit('tierChange', {
+                key,
+                oldTier,
+                newTier: 'ratified',
+                reason: 'ratified by signing',
+            });
+        }
+        this.emit('change', { key, oldEntry: existing, newEntry: ratified });
+        return (0, shared_1.ok)(ratified);
+    }
+    /**
+     * Read an entry, applying effective tier (decay + contradictions).
+     */
+    read(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        const effective = (0, trust_js_1.effectiveTier)(entry);
+        if (effective !== entry.tier) {
+            // Update stored tier to reflect decay/contradictions
+            const updated = { ...entry, tier: effective };
+            this.entries.set(key, updated);
+            this.emit('tierChange', {
+                key,
+                oldTier: entry.tier,
+                newTier: effective,
+                reason: effective === 'inherited' ? 'TTL decay' : 'contradiction downgrade',
+            });
+            return updated;
+        }
+        return entry;
+    }
+    /**
+     * Read an entry only if it meets a minimum trust tier.
+     */
+    readAtTier(key, minTier) {
+        const entry = this.read(key);
+        if (!entry)
+            return undefined;
+        const tierRank = { ratified: 3, inherited: 2, quarantined: 1 };
+        if (tierRank[entry.tier] < tierRank[minTier])
+            return undefined;
+        return entry;
+    }
+    /** Check if a key exists in the store. */
+    has(key) {
+        return this.entries.has(key);
+    }
+    /** Delete an entry. */
+    delete(key) {
+        const existing = this.entries.get(key);
+        if (!existing)
+            return false;
+        this.entries.delete(key);
+        return true;
+    }
+    /** Get all keys. */
+    keys() {
+        return Array.from(this.entries.keys());
+    }
+    /** Get all entries. */
+    all() {
+        return Array.from(this.entries.values());
+    }
+    /** Get the chronicle (read-only access). */
+    getChronicle() {
+        return this.chronicle;
+    }
+    /** Get the entry count. */
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * Restore trust state from an array of memory entries.
+     * Used to rebuild state after loading from persistence.
+     */
+    restore(entries) {
+        this.entries.clear();
+        this.chronicle.clear();
+        this.sequenceCounter = 0;
+        for (const entry of entries) {
+            this.entries.set(entry.key, entry);
+            this.chronicle.append({
+                stateId: `entry-${this.sequenceCounter}`,
+                sessionId: 'trust-store',
+                sequence: this.sequenceCounter++,
+                timestamp: entry.provenance?.timestamp ?? Date.now(),
+                tags: [entry.tier],
+            });
+        }
+    }
+    /**
+     * Create a hypothesis (sandbox) that can be committed or discarded.
+     *
+     * All writes in the hypothesis are isolated from the main store.
+     * Call commit() to merge into the main store, or discard() to abandon.
+     */
+    hypothesisMode() {
+        // Snapshot current entries
+        const snapshot = new Map();
+        for (const [key, entry] of this.entries) {
+            snapshot.set(key, entry);
+        }
+        return new Hypothesis(this, snapshot);
+    }
+    /* ── Event System ── */
+    /** Subscribe to trust store events. */
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+    }
+    /** Unsubscribe from trust store events. */
+    off(event, listener) {
+        const set = this.listeners.get(event);
+        if (set) {
+            set.delete(listener);
+        }
+    }
+    /** Remove all event listeners. */
+    removeAllListeners() {
+        this.listeners.clear();
+    }
+    /** Emit an event to all registered listeners. */
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (set) {
+            for (const listener of set) {
+                listener(payload);
+            }
+        }
+    }
+    /* ── Internal: used by Hypothesis ── */
+    /** @internal Merge entries from a hypothesis into the main store. */
+    _mergeHypothesis(entries) {
+        for (const [key, entry] of entries) {
+            const existing = this.entries.get(key);
+            this.entries.set(key, entry);
+            this.emit('change', { key, oldEntry: existing, newEntry: entry });
+            if (existing && existing.tier !== entry.tier) {
+                this.emit('tierChange', {
+                    key,
+                    oldTier: existing.tier,
+                    newTier: entry.tier,
+                    reason: 'hypothesis committed',
+                });
+            }
+        }
+    }
+}
+exports.TrustStore = TrustStore;
+/**
+ * A sandboxed hypothesis for speculative writes.
+ *
+ * Changes are isolated until commit() is called.
+ * Memory is bounded — the hypothesis shares the parent's maxAge config.
+ */
+class Hypothesis {
+    parent;
+    baseSnapshot;
+    changes = new Map();
+    committed = false;
+    discarded = false;
+    constructor(parent, baseSnapshot) {
+        this.parent = parent;
+        this.baseSnapshot = baseSnapshot;
+    }
+    /** Write a speculative entry (isolated from main store). */
+    write(key, value, tier = 'inherited') {
+        if (this.committed || this.discarded) {
+            throw new Error('Hypothesis already finalized');
+        }
+        const entry = {
+            key,
+            value,
+            tier,
+            contradictions: [],
+        };
+        this.changes.set(key, entry);
+        return entry;
+    }
+    /** Read from hypothesis (falls back to base snapshot). */
+    read(key) {
+        return this.changes.get(key) ?? this.baseSnapshot.get(key);
+    }
+    /** Commit all hypothesis changes into the main store. */
+    commit() {
+        if (this.committed || this.discarded) {
+            throw new Error('Hypothesis already finalized');
+        }
+        this.committed = true;
+        this.parent._mergeHypothesis(this.changes);
+    }
+    /** Discard all hypothesis changes. */
+    discard() {
+        if (this.committed || this.discarded) {
+            throw new Error('Hypothesis already finalized');
+        }
+        this.discarded = true;
+        this.changes.clear();
+    }
+    /** Check if the hypothesis has been finalized. */
+    get isFinalized() {
+        return this.committed || this.discarded;
+    }
+    /** Get the number of speculative changes. */
+    get changeCount() {
+        return this.changes.size;
+    }
+}
+exports.Hypothesis = Hypothesis;