sealkeep 0.9.0 → 0.11.0

package/dist/src/index-publication-state.js

@@ -0,0 +1,696 @@
+import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { acquireDurableTicketLock } from "./durable-ticket-lock.js";
+import { canonicalPhrase } from "./mnemonic.js";
+const STATE_VERSION = 2;
+const PUBLICATION_POLICY_VERSION = 1;
+const STATE_FILE = "index-publication-state.v2.json";
+const STATE_CHECKSUM_DOMAIN = "sealkeep:index-publication-state:v2\0";
+const KEY_DERIVATION_DOMAIN = "sealkeep:index-publication-state:key:v1\0";
+export class IndexPublicationStateError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.name = "IndexPublicationStateError";
+        this.code = code;
+        this.cause = cause;
+    }
+}
+export class IndexPublicationConflictError extends Error {
+    code = "INDEX_PUBLICATION_STATE_CONFLICT";
+    constructor(message = "The index publication requirement changed") {
+        super(message);
+        this.name = "IndexPublicationConflictError";
+    }
+}
+export function indexPublicationStatePath(dataDir) {
+    return join(dataDir, "index", STATE_FILE);
+}
+function lockQueuePath(dataDir) {
+    return join(dataDir, "index", ".index-publication-state.lock");
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function validScope(value) {
+    if (!isObject(value))
+        return false;
+    if (value.kind === "account")
+        return nonEmpty(value.vaultId) && Object.keys(value).length === 2;
+    return value.kind === "team"
+        && nonEmpty(value.spaceKey)
+        && Number.isSafeInteger(value.membershipVersion)
+        && Number(value.membershipVersion) > 0
+        && Object.keys(value).length === 3;
+}
+function validRequirement(value) {
+    return isObject(value)
+        && nonEmpty(value.archiveId)
+        && nonEmpty(value.archiveRef)
+        && nonEmpty(value.entryDigest)
+        && validScope(value.scope)
+        && Object.keys(value).length === 4;
+}
+function validReceipt(value) {
+    return isObject(value)
+        && nonEmpty(value.requirementKey)
+        && value.policyVersion === PUBLICATION_POLICY_VERSION
+        && nonEmpty(value.publisherId)
+        && nonEmpty(value.generationId)
+        && nonEmpty(value.registryReceiptId)
+        && Number.isSafeInteger(value.registryRevision)
+        && Number(value.registryRevision) >= 0
+        && nonEmpty(value.objectRef)
+        && typeof value.ciphertextSha256 === "string"
+        && /^[0-9a-f]{64}$/.test(value.ciphertextSha256)
+        && Number.isSafeInteger(value.ciphertextBytes)
+        && Number(value.ciphertextBytes) >= 0
+        && nonEmpty(value.committedAt)
+        && Object.keys(value).length === 10;
+}
+function validStoredRequirement(value, key) {
+    return isObject(value)
+        && value.logicalKey === key
+        && nonEmpty(value.logicalKey)
+        && nonEmpty(value.requirementKey)
+        && Number.isSafeInteger(value.requirementRevision)
+        && Number(value.requirementRevision) > 0
+        && nonEmpty(value.requiredAt)
+        && validRequirement(value.requirement)
+        && Object.keys(value).length === 5;
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+}
+function checksum(ledger) {
+    // Construct the wire payload explicitly. `Omit<..., "checksum">` is a
+    // compile-time property only; a spread of a parsed ledger still carries its
+    // old checksum at runtime and must never feed it into the next checksum.
+    const payload = {
+        version: STATE_VERSION,
+        generation: ledger.generation,
+        revision: ledger.revision,
+        requirements: ledger.requirements,
+        receipts: ledger.receipts,
+    };
+    return createHash("sha256")
+        .update(STATE_CHECKSUM_DOMAIN, "utf8")
+        .update(canonicalJson(payload), "utf8")
+        .digest("hex");
+}
+function equalText(left, right) {
+    const a = Buffer.from(left, "utf8");
+    const b = Buffer.from(right, "utf8");
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+function parseLedger(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isObject(value)
+        || value.version !== STATE_VERSION
+        || !nonEmpty(value.generation)
+        || !Number.isSafeInteger(value.revision)
+        || Number(value.revision) < 0
+        || !isObject(value.requirements)
+        || !isObject(value.receipts)
+        || typeof value.checksum !== "string")
+        return null;
+    const requirements = value.requirements;
+    const receipts = value.receipts;
+    if (Object.entries(requirements).some(([key, requirement]) => !validStoredRequirement(requirement, key)))
+        return null;
+    if (Object.entries(receipts).some(([logicalKey, receipt]) => {
+        if (!validReceipt(receipt))
+            return true;
+        const requirement = requirements[logicalKey];
+        return !requirement || receipt.requirementKey !== requirement.requirementKey;
+    }))
+        return null;
+    const withoutChecksum = {
+        version: STATE_VERSION,
+        generation: value.generation,
+        revision: Number(value.revision),
+        requirements: requirements,
+        receipts: receipts,
+    };
+    const expected = checksum(withoutChecksum);
+    if (!/^[0-9a-f]{64}$/.test(value.checksum) || !equalText(value.checksum, expected))
+        return null;
+    return { ...withoutChecksum, checksum: value.checksum };
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+async function readLedger(dataDir, options = {}) {
+    const read = options.readFile ?? ((path, encoding) => readFile(path, encoding));
+    try {
+        const ledger = parseLedger(await read(indexPublicationStatePath(dataDir), "utf8"));
+        return ledger
+            ? { status: "ok", ledger }
+            : { status: "unreadable", errorCode: "CORRUPT" };
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code === "ENOENT")
+            return { status: "missing" };
+        return { status: "unreadable", errorCode: code ?? "UNKNOWN", cause: error };
+    }
+}
+function keySeed(material) {
+    if (typeof material === "string") {
+        if (!material.length)
+            throw new TypeError("Publication phrase must not be empty");
+        return Buffer.from(canonicalPhrase(material), "utf8");
+    }
+    if ("phrase" in material) {
+        if (!material.phrase.length)
+            throw new TypeError("Publication phrase must not be empty");
+        return Buffer.from(canonicalPhrase(material.phrase), "utf8");
+    }
+    if ("vaultId" in material) {
+        if (!material.vaultId.length)
+            throw new TypeError("Publication vault id must not be empty");
+        // The ledger stores publication coordination metadata, not transcript
+        // plaintext or archive keys.  Keying its opaque identities by the stable
+        // vault id lets both the indexer and the deletion gate address the same
+        // obligations without asking a background retention pass to unlock the
+        // user's recovery phrase.
+        return createHash("sha256")
+            .update("sealkeep:index-publication-state:vault-id:v1\0", "utf8")
+            .update(material.vaultId, "utf8")
+            .digest();
+    }
+    if (!(material.key instanceof Uint8Array) || material.key.byteLength === 0) {
+        throw new TypeError("Publication key material must not be empty");
+    }
+    // Always copy caller-owned bytes. Derivation zeroizes only this private copy.
+    return Buffer.from(material.key);
+}
+function withDerivedKey(material, work) {
+    const seed = keySeed(material);
+    let key;
+    try {
+        key = createHmac("sha256", seed).update(KEY_DERIVATION_DOMAIN, "utf8").digest();
+        return work(key);
+    }
+    finally {
+        key?.fill(0);
+        seed.fill(0);
+    }
+}
+function exactScope(scope) {
+    return scope.kind === "account"
+        ? ["account", scope.vaultId]
+        : ["team", scope.spaceKey, scope.membershipVersion];
+}
+function logicalScope(scope) {
+    return scope.kind === "account"
+        ? ["account", scope.vaultId]
+        : ["team", scope.spaceKey];
+}
+function hmacKey(key, purpose, values) {
+    return `${purpose}1:${createHmac("sha256", key).update(canonicalJson(values), "utf8").digest("hex")}`;
+}
+function identitiesWithKey(key, requirement) {
+    if (!validRequirement(requirement))
+        throw new TypeError("Invalid index publication requirement");
+    return {
+        // membershipVersion is deliberately absent: a roster change replaces the
+        // same logical team/archive slot instead of creating a parallel obligation.
+        logicalKey: hmacKey(key, "l", [PUBLICATION_POLICY_VERSION, logicalScope(requirement.scope), requirement.archiveId]),
+        requirementKey: hmacKey(key, "r", [
+            PUBLICATION_POLICY_VERSION,
+            exactScope(requirement.scope),
+            requirement.archiveRef,
+            requirement.entryDigest,
+        ]),
+    };
+}
+function identities(material, requirement) {
+    return withDerivedKey(material, (key) => identitiesWithKey(key, requirement));
+}
+export function indexPublicationRequirementKey(material, requirement) {
+    return identities(material, requirement).requirementKey;
+}
+export function indexPublicationLogicalKey(material, requirement) {
+    return identities(material, requirement).logicalKey;
+}
+function exactRequirement(left, right) {
+    return canonicalJson(left) === canonicalJson(right);
+}
+function receiptSatisfies(requirement, receipt) {
+    return Boolean(receipt
+        && receipt.policyVersion === PUBLICATION_POLICY_VERSION
+        && equalText(receipt.requirementKey, requirement.requirementKey));
+}
+function handleFor(ledger, requirement) {
+    return {
+        logicalKey: requirement.logicalKey,
+        requirementKey: requirement.requirementKey,
+        ledgerGeneration: ledger.generation,
+        requirementRevision: requirement.requirementRevision,
+    };
+}
+function matchesHandle(ledger, requirement, expected) {
+    return Boolean(requirement
+        && ledger.generation === expected.ledgerGeneration
+        && requirement.logicalKey === expected.logicalKey
+        && requirement.requirementKey === expected.requirementKey
+        && requirement.requirementRevision === expected.requirementRevision);
+}
+function validateLedgerKeys(ledger, material) {
+    return withDerivedKey(material, (key) => Object.entries(ledger.requirements).every(([logicalKey, stored]) => {
+        const expected = identitiesWithKey(key, stored.requirement);
+        return equalText(logicalKey, expected.logicalKey)
+            && equalText(stored.logicalKey, expected.logicalKey)
+            && equalText(stored.requirementKey, expected.requirementKey);
+    }));
+}
+function unreadableError(read) {
+    const corrupt = read.errorCode === "CORRUPT";
+    return new IndexPublicationStateError(corrupt ? "INDEX_PUBLICATION_STATE_CORRUPT" : "INDEX_PUBLICATION_STATE_UNREADABLE", corrupt
+        ? "Index publication state is corrupt"
+        : `Index publication state could not be read (${read.errorCode})`, read.cause);
+}
+async function syncDirectory(path) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        if (process.platform !== "win32")
+            throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function writeLedger(dataDir, ledger, uuid) {
+    const target = indexPublicationStatePath(dataDir);
+    const directory = dirname(target);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const complete = { ...ledger, checksum: checksum(ledger) };
+    const temporary = join(directory, `.${STATE_FILE}.${uuid()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(`${JSON.stringify(complete)}\n`, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, target);
+        await syncDirectory(directory);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+function emptyLedger(uuid) {
+    const withoutChecksum = {
+        version: STATE_VERSION,
+        generation: uuid(),
+        revision: 0,
+        requirements: Object.create(null),
+        receipts: Object.create(null),
+    };
+    return { ...withoutChecksum, checksum: checksum(withoutChecksum) };
+}
+async function withMutation(dataDir, material, options, mutate, initializeMissing = false) {
+    const lockOptions = {
+        signal: options.signal,
+        ...(options.lockTimeoutMs === undefined ? {} : { timeoutMs: options.lockTimeoutMs }),
+        ...(options.lockPollMs === undefined ? {} : { pollMs: options.lockPollMs }),
+    };
+    const lock = await acquireDurableTicketLock(lockQueuePath(dataDir), indexPublicationStatePath(dataDir), lockOptions);
+    try {
+        const read = await readLedger(dataDir, options);
+        if (read.status === "unreadable")
+            throw unreadableError(read);
+        const uuid = options.uuid ?? randomUUID;
+        const ledger = read.status === "missing" ? emptyLedger(uuid) : read.ledger;
+        if (!validateLedgerKeys(ledger, material)) {
+            throw new IndexPublicationStateError("INDEX_PUBLICATION_STATE_CORRUPT", "Index publication state contains invalid keyed requirements");
+        }
+        const outcome = mutate(ledger, (options.now ?? (() => new Date().toISOString()))());
+        if (outcome.changed || (initializeMissing && read.status === "missing")) {
+            await lock.assertOwned();
+            await writeLedger(dataDir, outcome.ledger, uuid);
+        }
+        return outcome.value;
+    }
+    finally {
+        await lock.release();
+    }
+}
+export async function readIndexPublicationState(dataDir, options = {}) {
+    const read = await readLedger(dataDir, options);
+    if (read.status !== "ok")
+        return read.status === "missing"
+            ? { status: "missing" }
+            : { status: "unreadable", errorCode: read.errorCode };
+    return {
+        status: "ok",
+        generation: read.ledger.generation,
+        revision: read.ledger.revision,
+        requirements: Object.keys(read.ledger.requirements).length,
+        satisfied: Object.entries(read.ledger.requirements)
+            .filter(([logicalKey, requirement]) => receiptSatisfies(requirement, read.ledger.receipts[logicalKey]))
+            .length,
+    };
+}
+/**
+ * Installs or refreshes one exact obligation. Repeating the same tuple is a
+ * true no-op; changing a tuple removes only that logical archive's receipt.
+ */
+export async function recordIndexPublicationRequirement(dataDir, material, requirement, options = {}) {
+    const identity = identities(material, requirement);
+    return withMutation(dataDir, material, options, (ledger, now) => {
+        const current = ledger.requirements[identity.logicalKey];
+        if (options.expected === null && current)
+            throw new IndexPublicationConflictError();
+        if (options.expected && !matchesHandle(ledger, current, options.expected)) {
+            throw new IndexPublicationConflictError();
+        }
+        if (current
+            && current.requirementKey === identity.requirementKey
+            && exactRequirement(current.requirement, requirement)) {
+            return {
+                changed: false,
+                ledger,
+                value: handleFor(ledger, current),
+            };
+        }
+        const revision = ledger.revision + 1;
+        const stored = {
+            ...identity,
+            requirementRevision: revision,
+            requiredAt: now,
+            requirement: structuredClone(requirement),
+        };
+        const requirements = { ...ledger.requirements, [identity.logicalKey]: stored };
+        const receipts = { ...ledger.receipts };
+        delete receipts[identity.logicalKey];
+        const next = { ...ledger, revision, requirements, receipts };
+        return {
+            changed: true,
+            ledger: next,
+            value: {
+                logicalKey: identity.logicalKey,
+                requirementKey: identity.requirementKey,
+                ledgerGeneration: ledger.generation,
+                requirementRevision: revision,
+            },
+        };
+    });
+}
+/**
+ * Atomically installs a checkpoint's obligations with one lock acquisition and
+ * one fsync. Large vaults routinely contain thousands of sessions, so making
+ * each row its own durable transaction would turn indexing into minutes of
+ * avoidable disk latency. Duplicate logical slots are rejected because their
+ * order would otherwise decide which exact tuple survived.
+ */
+export async function recordIndexPublicationRequirements(dataDir, material, requirements, options = {}) {
+    const prepared = requirements.map((requirement) => ({
+        requirement,
+        identity: identities(material, requirement),
+    }));
+    if (new Set(prepared.map((item) => item.identity.logicalKey)).size !== prepared.length) {
+        throw new TypeError("Duplicate logical index publication requirement");
+    }
+    return withMutation(dataDir, material, options, (ledger, now) => {
+        let revision = ledger.revision;
+        let changed = false;
+        const storedByLogical = { ...ledger.requirements };
+        const receipts = { ...ledger.receipts };
+        const result = [];
+        for (const item of prepared) {
+            const current = storedByLogical[item.identity.logicalKey];
+            if (current
+                && current.requirementKey === item.identity.requirementKey
+                && exactRequirement(current.requirement, item.requirement)) {
+                result.push({ requirement: structuredClone(item.requirement), handle: handleFor(ledger, current) });
+                continue;
+            }
+            revision += 1;
+            changed = true;
+            const stored = {
+                ...item.identity,
+                requirementRevision: revision,
+                requiredAt: now,
+                requirement: structuredClone(item.requirement),
+            };
+            storedByLogical[item.identity.logicalKey] = stored;
+            delete receipts[item.identity.logicalKey];
+            result.push({
+                requirement: structuredClone(item.requirement),
+                handle: {
+                    logicalKey: item.identity.logicalKey,
+                    requirementKey: item.identity.requirementKey,
+                    ledgerGeneration: ledger.generation,
+                    requirementRevision: revision,
+                },
+            });
+        }
+        return {
+            changed,
+            ledger: changed
+                ? { ...ledger, revision, requirements: storedByLogical, receipts }
+                : ledger,
+            value: result,
+        };
+    }, true); // Explicit registration of zero obligations must survive an empty-vault build.
+}
+/**
+ * Records positive publication proof only while the exact requirement and its
+ * local generation/revision still match the writer's pre-publication handle.
+ */
+export async function recordIndexPublicationReceipt(dataDir, material, requirement, expected, details, options = {}) {
+    const identity = identities(material, requirement);
+    if (details.requirementKey !== undefined && details.requirementKey !== identity.requirementKey) {
+        throw new TypeError("Publication receipt requirement key does not match the requirement");
+    }
+    if (details.policyVersion !== undefined && details.policyVersion !== PUBLICATION_POLICY_VERSION) {
+        throw new TypeError("Publication receipt policy version does not match");
+    }
+    const receipt = {
+        requirementKey: identity.requirementKey,
+        policyVersion: PUBLICATION_POLICY_VERSION,
+        publisherId: details.publisherId,
+        generationId: details.generationId,
+        registryReceiptId: details.registryReceiptId,
+        registryRevision: details.registryRevision,
+        objectRef: details.objectRef,
+        ciphertextSha256: details.ciphertextSha256,
+        ciphertextBytes: details.ciphertextBytes,
+        committedAt: details.committedAt,
+    };
+    if (!validReceipt(receipt))
+        throw new TypeError("Invalid index publication receipt");
+    return withMutation(dataDir, material, options, (ledger) => {
+        const current = ledger.requirements[identity.logicalKey];
+        if (!current
+            || !matchesHandle(ledger, current, expected)
+            || current.requirementKey !== identity.requirementKey
+            || !exactRequirement(current.requirement, requirement)) {
+            return { changed: false, ledger, value: false };
+        }
+        const previous = ledger.receipts[identity.logicalKey];
+        if (previous && canonicalJson(previous) === canonicalJson(receipt)) {
+            return { changed: false, ledger, value: true };
+        }
+        const next = {
+            ...ledger,
+            revision: ledger.revision + 1,
+            receipts: { ...ledger.receipts, [identity.logicalKey]: receipt },
+        };
+        return { changed: true, ledger: next, value: true };
+    });
+}
+/** Installs all still-current receipts from one verified remote generation. */
+export async function recordIndexPublicationReceipts(dataDir, material, writes, options = {}) {
+    const prepared = writes.map((write) => {
+        const identity = identities(material, write.requirement);
+        if (write.details.requirementKey !== undefined && write.details.requirementKey !== identity.requirementKey) {
+            throw new TypeError("Publication receipt requirement key does not match the requirement");
+        }
+        if (write.details.policyVersion !== undefined && write.details.policyVersion !== PUBLICATION_POLICY_VERSION) {
+            throw new TypeError("Publication receipt policy version does not match");
+        }
+        const receipt = {
+            requirementKey: identity.requirementKey,
+            policyVersion: PUBLICATION_POLICY_VERSION,
+            publisherId: write.details.publisherId,
+            generationId: write.details.generationId,
+            registryReceiptId: write.details.registryReceiptId,
+            registryRevision: write.details.registryRevision,
+            objectRef: write.details.objectRef,
+            ciphertextSha256: write.details.ciphertextSha256,
+            ciphertextBytes: write.details.ciphertextBytes,
+            committedAt: write.details.committedAt,
+        };
+        if (!validReceipt(receipt))
+            throw new TypeError("Invalid index publication receipt");
+        return { ...write, identity, receipt };
+    });
+    if (new Set(prepared.map((item) => item.identity.logicalKey)).size !== prepared.length) {
+        throw new TypeError("Duplicate logical index publication receipt");
+    }
+    return withMutation(dataDir, material, options, (ledger) => {
+        let recorded = 0;
+        let stale = 0;
+        let changed = false;
+        const receipts = { ...ledger.receipts };
+        for (const item of prepared) {
+            const current = ledger.requirements[item.identity.logicalKey];
+            if (!current
+                || !matchesHandle(ledger, current, item.handle)
+                || current.requirementKey !== item.identity.requirementKey
+                || !exactRequirement(current.requirement, item.requirement)) {
+                stale += 1;
+                continue;
+            }
+            recorded += 1;
+            if (receipts[item.identity.logicalKey]
+                && canonicalJson(receipts[item.identity.logicalKey]) === canonicalJson(item.receipt))
+                continue;
+            receipts[item.identity.logicalKey] = item.receipt;
+            changed = true;
+        }
+        return {
+            changed,
+            ledger: changed ? { ...ledger, revision: ledger.revision + 1, receipts } : ledger,
+            value: { recorded, stale },
+        };
+    });
+}
+/** Missing, corrupt and unreadable state all deliberately return no proof. */
+export async function getIndexPublicationReceipt(dataDir, material, requirement, options = {}) {
+    const identity = identities(material, requirement);
+    const read = await readLedger(dataDir, options);
+    if (read.status !== "ok" || !validateLedgerKeys(read.ledger, material))
+        return null;
+    const stored = read.ledger.requirements[identity.logicalKey];
+    const receipt = read.ledger.receipts[identity.logicalKey];
+    if (!stored
+        || stored.requirementKey !== identity.requirementKey
+        || !exactRequirement(stored.requirement, requirement)
+        || !receiptSatisfies(stored, receipt))
+        return null;
+    return structuredClone(receipt);
+}
+export async function hasIndexPublicationReceipt(dataDir, material, requirement, options = {}) {
+    return (await getIndexPublicationReceipt(dataDir, material, requirement, options)) !== null;
+}
+/**
+ * Lists only durable obligations which lack their exact positive receipt.
+ * Missing state has no recorded requirements. Corrupt/EACCES state throws so
+ * callers cannot mistake an I/O fault for an authoritative empty list.
+ */
+export async function listUnsatisfiedIndexPublicationRequirements(dataDir, material, options = {}) {
+    const read = await readLedger(dataDir, options);
+    if (read.status === "missing")
+        return [];
+    if (read.status === "unreadable")
+        throw unreadableError(read);
+    if (!validateLedgerKeys(read.ledger, material)) {
+        throw new IndexPublicationStateError("INDEX_PUBLICATION_STATE_CORRUPT", "Index publication state contains invalid keyed requirements");
+    }
+    return Object.entries(read.ledger.requirements)
+        .filter(([logicalKey, requirement]) => !receiptSatisfies(requirement, read.ledger.receipts[logicalKey]))
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([, stored]) => ({
+        ...handleFor(read.ledger, stored),
+        requirement: structuredClone(stored.requirement),
+        requiredAt: stored.requiredAt,
+    }));
+}
+/**
+ * Lists every exact obligation together with its positive receipt, if any.
+ * Missing state is an empty non-authoritative list; corrupt or unreadable state
+ * throws so destructive callers cannot interpret an I/O failure as success.
+ */
+export async function listIndexPublicationRequirements(dataDir, material, options = {}) {
+    const read = await readLedger(dataDir, options);
+    if (read.status === "missing")
+        return [];
+    if (read.status === "unreadable")
+        throw unreadableError(read);
+    if (!validateLedgerKeys(read.ledger, material)) {
+        throw new IndexPublicationStateError("INDEX_PUBLICATION_STATE_CORRUPT", "Index publication state contains invalid keyed requirements");
+    }
+    return Object.entries(read.ledger.requirements)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([logicalKey, stored]) => {
+        const receipt = read.ledger.receipts[logicalKey];
+        return {
+            ...handleFor(read.ledger, stored),
+            requirement: structuredClone(stored.requirement),
+            requiredAt: stored.requiredAt,
+            receipt: receiptSatisfies(stored, receipt) ? structuredClone(receipt) : null,
+        };
+    });
+}
+/** Invalidates one exact receipt; there is intentionally no global clear. */
+export async function invalidateIndexPublicationReceipt(dataDir, material, requirement, expected, options = {}) {
+    const identity = identities(material, requirement);
+    return withMutation(dataDir, material, options, (ledger) => {
+        const current = ledger.requirements[identity.logicalKey];
+        if (!current
+            || !matchesHandle(ledger, current, expected)
+            || current.requirementKey !== identity.requirementKey
+            || !exactRequirement(current.requirement, requirement)) {
+            return { changed: false, ledger, value: false };
+        }
+        if (!ledger.receipts[identity.logicalKey])
+            return { changed: false, ledger, value: true };
+        const receipts = { ...ledger.receipts };
+        delete receipts[identity.logicalKey];
+        return {
+            changed: true,
+            ledger: { ...ledger, revision: ledger.revision + 1, receipts },
+            value: true,
+        };
+    });
+}
+/** Removes one no-longer-applicable obligation using the same per-entry CAS. */
+export async function removeIndexPublicationRequirement(dataDir, material, requirement, expected, options = {}) {
+    const identity = identities(material, requirement);
+    return withMutation(dataDir, material, options, (ledger) => {
+        const current = ledger.requirements[identity.logicalKey];
+        if (!current
+            || !matchesHandle(ledger, current, expected)
+            || current.requirementKey !== identity.requirementKey
+            || !exactRequirement(current.requirement, requirement)) {
+            return { changed: false, ledger, value: false };
+        }
+        const requirements = { ...ledger.requirements };
+        const receipts = { ...ledger.receipts };
+        delete requirements[identity.logicalKey];
+        delete receipts[identity.logicalKey];
+        return {
+            changed: true,
+            ledger: { ...ledger, revision: ledger.revision + 1, requirements, receipts },
+            value: true,
+        };
+    });
+}