mindoodb 0.0.65 → 0.0.67

package/dist/core/quarantine/QuarantineDocument.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Quarantine records: how a device remembers a write the server turned away,
+ * so it can be found again and offered again.
+ *
+ * A device that pushes an entry and gets a `"policy"` rejection back is holding
+ * something awkward: an entry that was legitimate when it was written, is
+ * cryptographically sound, and is refused only because a right was withdrawn in
+ * the meantime. It must not be dropped — the right may come back — and it must
+ * not block the database's push either. So the push moves on and leaves a
+ * record here.
+ *
+ * This matters most for entries that arrived over peer-to-peer sync: a device
+ * can hold, and have already merged, a change it did not write itself and whose
+ * author has since lost the right to write it. Without a record, the refusal
+ * would be a line in a log that disappears on reload.
+ *
+ * ## Why `userdirectory`
+ *
+ * The record deliberately does *not* live in the database it is about. The
+ * whole reason it exists is that someone lost their write right there, so
+ * writing the record there would earn the same refusal as the entry it
+ * documents. `userdirectory` is a database every member can write their own
+ * documents in without an administrator approving anything.
+ *
+ * - **`qtn_` prefix** — makes it a *personal document* (see
+ *   {@link PERSONAL_DOC_ID_PREFIXES}), so the write invariant lets its creator
+ *   change and delete it, and the admin delete it.
+ * - **`default` key, not `$publicinfos`** — the hoster holds the
+ *   `$publicinfos` key, and which of a tenant's writes were refused is none of
+ *   the hoster's business. `default` keeps it readable for every member, so it
+ *   can serve as an audit trail, and opaque to the server.
+ *
+ * ## One record per author, database, document and class
+ *
+ * The id is derived rather than random, which makes recording idempotent: a
+ * retry that fails the same way updates the record in place instead of adding
+ * another. A cascade of refused entries on one document therefore collapses
+ * into one record holding a capped list of entry ids.
+ *
+ * The **author's key fingerprint is part of the derivation**, and that is
+ * load-bearing rather than decorative. Without it, two members refused on the
+ * same document for the same reason would derive the same id — and since the
+ * personal-document invariant only lets the *creator* write a document, the
+ * second member's record would be refused by the very invariant that is
+ * supposed to protect it. Folding the author in makes id and ownership agree.
+ *
+ * ## Why records must be verified on read
+ *
+ * Any tenant member can write a `qtn_` document claiming anything. Since these
+ * records say "this person tried to write something they were not allowed to
+ * write", an unverified one is a way to put words in someone else's mouth.
+ * {@link verifyQuarantineRecord} accepts a record only when:
+ *
+ * 1. the doc id is derived from the payload's own fields, including the
+ *    fingerprint of the `signingPublicKey` it names,
+ * 2. the `doc_create` entry was signed by exactly that key, and
+ * 3. that key is an active (non-revoked) grant in the tenant.
+ *
+ * **Known limit — a record is evidence of an honest client, not of an honest
+ * one's absence.** Nothing compels a device to write a record, so the absence
+ * of one proves nothing. Like the `dev_` records, this is useful for auditing
+ * cooperating devices, not for catching a malicious one.
+ */
+import type { MindooDB, MindooDoc, SigningKeyPair } from "../types";
+import type { PutRejectionClass } from "../appendonlystores/types";
+export declare const QUARANTINE_DOC_ID_PREFIX = "qtn_";
+export declare const QUARANTINE_FORM = "userdirectory";
+export declare const QUARANTINE_TYPE = "quarantine";
+export declare const QUARANTINE_SCHEMA_VERSION = 1;
+/**
+ * How many entry ids one record carries.
+ *
+ * A quarantined write usually drags its causal dependents along, so one
+ * refusal can mean a long list. The list is for finding the entries again, and
+ * a bounded one does that just as well while keeping the record — which syncs
+ * to every member of the tenant — from growing without limit.
+ */
+export declare const MAX_QUARANTINED_ENTRY_IDS = 200;
+/** Payload of a `qtn_` document. Encrypted with {@link DEFAULT_TENANT_KEY_ID}. */
+export interface QuarantineDocumentPayload {
+    form: typeof QUARANTINE_FORM;
+    type: typeof QUARANTINE_TYPE;
+    schemaVersion: number;
+    /**
+     * Signing public key (PEM) of the device that recorded this. The whole
+     * verification chain hangs off this field.
+     */
+    signingPublicKey: string;
+    /** Database the refused entries belong to. Not `userdirectory` itself. */
+    dbid: string;
+    /** Document the refused entries belong to. */
+    quarantinedDocId: string;
+    /** Why the target refused them. */
+    rejectionClass: PutRejectionClass;
+    /** The target's own wording, kept verbatim for the audit view. */
+    reason: string;
+    /** Refused entry ids, capped at {@link MAX_QUARANTINED_ENTRY_IDS}. */
+    entryIds: string[];
+    /** How many refused entries did not fit into {@link entryIds}. */
+    omittedEntryCount?: number;
+    firstSeenAt: number;
+    updatedAt: number;
+}
+/** A record that passed {@link verifyQuarantineRecord}. */
+export interface QuarantineRecordDoc {
+    docId: string;
+    signingPublicKey: string;
+    /** Fingerprint of {@link signingPublicKey}, colon-separated hex. */
+    signingKeyFingerprint: string;
+    dbid: string;
+    quarantinedDocId: string;
+    rejectionClass: PutRejectionClass;
+    reason: string;
+    entryIds: string[];
+    omittedEntryCount: number;
+    firstSeenAt: number;
+    updatedAt: number;
+}
+/** The directory calls a quarantine record needs to verify a claim. */
+export interface QuarantineDirectory {
+    /** True when the key belongs to an active, non-revoked grant. */
+    validatePublicSigningKey(publicKey: string, opts?: {
+        forceRefresh?: boolean;
+    }): Promise<boolean>;
+}
+/** What identifies one quarantine record. */
+export interface QuarantineRecordKey {
+    /** Fingerprint of the recording device's signing key, colon-separated hex. */
+    signingKeyFingerprint: string;
+    dbid: string;
+    quarantinedDocId: string;
+    rejectionClass: PutRejectionClass;
+}
+/** Is this a quarantine record id? */
+export declare function isQuarantineDocId(docId: string | undefined | null): boolean;
+/**
+ * Deterministic document id for one (author, database, document, class).
+ *
+ * Deterministic so that recording the same refusal again updates the record
+ * instead of accumulating one per attempt. Hashed rather than concatenated
+ * because custom ids must match `^[a-z][a-z0-9_]*$` (`CUSTOM_DOC_ID_REGEX`) and
+ * a document id can hold anything.
+ */
+export declare function quarantineDocumentId(key: QuarantineRecordKey, subtle: SubtleCrypto): Promise<string>;
+/** Thrown when a caller tries to record a quarantine about a quarantine record. */
+export declare class QuarantineRecursionError extends Error {
+    constructor(docId: string);
+}
+/**
+ * Record (or extend) the quarantine for one document's refused entries.
+ *
+ * Idempotent in the sense that matters: calling it again with entry ids the
+ * record already holds writes nothing at all. That is not an optimisation. A
+ * write here appends an entry, which syncs, which can trigger the next push,
+ * which would record again — so a record that rewrote itself on every attempt
+ * would feed a loop the user pays for in bandwidth and history size.
+ *
+ * @throws QuarantineRecursionError when asked to record a `qtn_` document,
+ *   which would let one refusal generate an unbounded chain of records.
+ */
+export declare function recordPushQuarantine(input: {
+    /** The tenant's `userdirectory`, not the database the entries belong to. */
+    db: MindooDB;
+    /** Signing public key (PEM) of this device — must match the identity writing the document. */
+    signingPublicKey: string;
+    dbid: string;
+    quarantinedDocId: string;
+    rejectionClass: PutRejectionClass;
+    reason: string;
+    entryIds: readonly string[];
+    subtle: SubtleCrypto;
+    signingKeyPair?: SigningKeyPair;
+    signingKeyPassword?: string;
+    now?: number;
+}): Promise<MindooDoc>;
+/**
+ * Withdraw a record, because the entries were finally accepted or the user gave
+ * up on them.
+ */
+export declare function clearQuarantineRecord(input: {
+    db: MindooDB;
+    key: QuarantineRecordKey;
+    subtle: SubtleCrypto;
+}): Promise<void>;
+/**
+ * Check one record's claim. Returns the verified record, or `null` when any step
+ * of the chain described in the module docs fails.
+ */
+export declare function verifyQuarantineRecord(input: {
+    db: MindooDB;
+    directory: QuarantineDirectory;
+    doc: MindooDoc;
+    subtle: SubtleCrypto;
+}): Promise<QuarantineRecordDoc | null>;
+/**
+ * Every verified quarantine record in this `userdirectory` replica.
+ *
+ * Requires the tenant `default` key to be unlocked; records that cannot be
+ * decrypted are simply absent. Unverifiable records are skipped silently —
+ * they are the expected shape of an attack, not an error to surface.
+ */
+export declare function listQuarantineRecords(input: {
+    db: MindooDB;
+    directory: QuarantineDirectory;
+    subtle: SubtleCrypto;
+    /** Restrict to one database, e.g. for the sync view of a single database. */
+    dbid?: string;
+    /** Restrict to records this device wrote itself. */
+    signingKeyFingerprint?: string;
+}): Promise<QuarantineRecordDoc[]>;
+//# sourceMappingURL=QuarantineDocument.d.ts.map

package/dist/core/quarantine/QuarantineDocument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QuarantineDocument.d.ts","sourceRoot":"","sources":["../../../src/core/quarantine/QuarantineDocument.ts"],"names":[],"mappings":"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"}

package/dist/core/quarantine/QuarantineDocument.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ * Quarantine records: how a device remembers a write the server turned away,
+ * so it can be found again and offered again.
+ *
+ * A device that pushes an entry and gets a `"policy"` rejection back is holding
+ * something awkward: an entry that was legitimate when it was written, is
+ * cryptographically sound, and is refused only because a right was withdrawn in
+ * the meantime. It must not be dropped — the right may come back — and it must
+ * not block the database's push either. So the push moves on and leaves a
+ * record here.
+ *
+ * This matters most for entries that arrived over peer-to-peer sync: a device
+ * can hold, and have already merged, a change it did not write itself and whose
+ * author has since lost the right to write it. Without a record, the refusal
+ * would be a line in a log that disappears on reload.
+ *
+ * ## Why `userdirectory`
+ *
+ * The record deliberately does *not* live in the database it is about. The
+ * whole reason it exists is that someone lost their write right there, so
+ * writing the record there would earn the same refusal as the entry it
+ * documents. `userdirectory` is a database every member can write their own
+ * documents in without an administrator approving anything.
+ *
+ * - **`qtn_` prefix** — makes it a *personal document* (see
+ *   {@link PERSONAL_DOC_ID_PREFIXES}), so the write invariant lets its creator
+ *   change and delete it, and the admin delete it.
+ * - **`default` key, not `$publicinfos`** — the hoster holds the
+ *   `$publicinfos` key, and which of a tenant's writes were refused is none of
+ *   the hoster's business. `default` keeps it readable for every member, so it
+ *   can serve as an audit trail, and opaque to the server.
+ *
+ * ## One record per author, database, document and class
+ *
+ * The id is derived rather than random, which makes recording idempotent: a
+ * retry that fails the same way updates the record in place instead of adding
+ * another. A cascade of refused entries on one document therefore collapses
+ * into one record holding a capped list of entry ids.
+ *
+ * The **author's key fingerprint is part of the derivation**, and that is
+ * load-bearing rather than decorative. Without it, two members refused on the
+ * same document for the same reason would derive the same id — and since the
+ * personal-document invariant only lets the *creator* write a document, the
+ * second member's record would be refused by the very invariant that is
+ * supposed to protect it. Folding the author in makes id and ownership agree.
+ *
+ * ## Why records must be verified on read
+ *
+ * Any tenant member can write a `qtn_` document claiming anything. Since these
+ * records say "this person tried to write something they were not allowed to
+ * write", an unverified one is a way to put words in someone else's mouth.
+ * {@link verifyQuarantineRecord} accepts a record only when:
+ *
+ * 1. the doc id is derived from the payload's own fields, including the
+ *    fingerprint of the `signingPublicKey` it names,
+ * 2. the `doc_create` entry was signed by exactly that key, and
+ * 3. that key is an active (non-revoked) grant in the tenant.
+ *
+ * **Known limit — a record is evidence of an honest client, not of an honest
+ * one's absence.** Nothing compels a device to write a record, so the absence
+ * of one proves nothing. Like the `dev_` records, this is useful for auditing
+ * cooperating devices, not for catching a malicious one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuarantineRecursionError = exports.MAX_QUARANTINED_ENTRY_IDS = exports.QUARANTINE_SCHEMA_VERSION = exports.QUARANTINE_TYPE = exports.QUARANTINE_FORM = exports.QUARANTINE_DOC_ID_PREFIX = void 0;
+exports.isQuarantineDocId = isQuarantineDocId;
+exports.quarantineDocumentId = quarantineDocumentId;
+exports.recordPushQuarantine = recordPushQuarantine;
+exports.clearQuarantineRecord = clearQuarantineRecord;
+exports.verifyQuarantineRecord = verifyQuarantineRecord;
+exports.listQuarantineRecords = listQuarantineRecords;
+const types_1 = require("../types");
+const fingerprint_1 = require("../userkeys/fingerprint");
+exports.QUARANTINE_DOC_ID_PREFIX = "qtn_";
+exports.QUARANTINE_FORM = "userdirectory";
+exports.QUARANTINE_TYPE = "quarantine";
+exports.QUARANTINE_SCHEMA_VERSION = 1;
+/**
+ * How many entry ids one record carries.
+ *
+ * A quarantined write usually drags its causal dependents along, so one
+ * refusal can mean a long list. The list is for finding the entries again, and
+ * a bounded one does that just as well while keeping the record — which syncs
+ * to every member of the tenant — from growing without limit.
+ */
+exports.MAX_QUARANTINED_ENTRY_IDS = 200;
+/** Is this a quarantine record id? */
+function isQuarantineDocId(docId) {
+    return typeof docId === "string" && docId.startsWith(exports.QUARANTINE_DOC_ID_PREFIX);
+}
+/**
+ * Deterministic document id for one (author, database, document, class).
+ *
+ * Deterministic so that recording the same refusal again updates the record
+ * instead of accumulating one per attempt. Hashed rather than concatenated
+ * because custom ids must match `^[a-z][a-z0-9_]*$` (`CUSTOM_DOC_ID_REGEX`) and
+ * a document id can hold anything.
+ */
+async function quarantineDocumentId(key, subtle) {
+    const material = [
+        key.signingKeyFingerprint.replace(/:/g, "").toLowerCase(),
+        key.dbid,
+        key.quarantinedDocId,
+        key.rejectionClass,
+    ].join("\u0000");
+    const digest = await subtle.digest("SHA-256", new TextEncoder().encode(material));
+    const hex = [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+    return `${exports.QUARANTINE_DOC_ID_PREFIX}${hex.slice(0, 40)}`;
+}
+/** Thrown when a caller tries to record a quarantine about a quarantine record. */
+class QuarantineRecursionError extends Error {
+    constructor(docId) {
+        super(`Refusing to record a quarantine for ${docId}: quarantine records are not themselves quarantined`);
+        this.name = "QuarantineRecursionError";
+    }
+}
+exports.QuarantineRecursionError = QuarantineRecursionError;
+/**
+ * Record (or extend) the quarantine for one document's refused entries.
+ *
+ * Idempotent in the sense that matters: calling it again with entry ids the
+ * record already holds writes nothing at all. That is not an optimisation. A
+ * write here appends an entry, which syncs, which can trigger the next push,
+ * which would record again — so a record that rewrote itself on every attempt
+ * would feed a loop the user pays for in bandwidth and history size.
+ *
+ * @throws QuarantineRecursionError when asked to record a `qtn_` document,
+ *   which would let one refusal generate an unbounded chain of records.
+ */
+async function recordPushQuarantine(input) {
+    if (isQuarantineDocId(input.quarantinedDocId)) {
+        throw new QuarantineRecursionError(input.quarantinedDocId);
+    }
+    const fingerprint = await (0, fingerprint_1.fingerprintPublicKeyPem)(input.signingPublicKey, input.subtle);
+    const docId = await quarantineDocumentId({
+        signingKeyFingerprint: fingerprint,
+        dbid: input.dbid,
+        quarantinedDocId: input.quarantinedDocId,
+        rejectionClass: input.rejectionClass,
+    }, input.subtle);
+    const doc = (await input.db.getDocument(docId).catch(() => null)) ??
+        // Not `assumeUniqueId`: the id is derived rather than random, so two
+        // replicas creating it concurrently must share Automerge ancestry to
+        // converge instead of forking. That path also forbids `initialValues`,
+        // which is why the payload goes in through `changeDoc` below — the same
+        // call that extends an existing record.
+        (await input.db.createDocument({
+            id: docId,
+            decryptionKeyId: types_1.DEFAULT_TENANT_KEY_ID,
+            signingKeyPair: input.signingKeyPair,
+            signingKeyPassword: input.signingKeyPassword,
+        }));
+    const current = doc.getData();
+    const known = new Set(Array.isArray(current.entryIds) ? current.entryIds : []);
+    const added = input.entryIds.filter((id) => !known.has(id));
+    const alreadyDescribed = current.type === exports.QUARANTINE_TYPE &&
+        current.schemaVersion === exports.QUARANTINE_SCHEMA_VERSION &&
+        current.signingPublicKey === input.signingPublicKey &&
+        current.dbid === input.dbid &&
+        current.quarantinedDocId === input.quarantinedDocId &&
+        current.rejectionClass === input.rejectionClass &&
+        current.reason === input.reason;
+    if (alreadyDescribed && added.length === 0) {
+        return doc;
+    }
+    const merged = [...known, ...added];
+    const kept = merged.slice(0, exports.MAX_QUARANTINED_ENTRY_IDS);
+    const omitted = (current.omittedEntryCount ?? 0) + (merged.length - kept.length);
+    const now = input.now ?? Date.now();
+    await input.db.changeDoc(doc, (editable) => {
+        const data = editable.getData();
+        data.form = exports.QUARANTINE_FORM;
+        data.type = exports.QUARANTINE_TYPE;
+        data.schemaVersion = exports.QUARANTINE_SCHEMA_VERSION;
+        data.signingPublicKey = input.signingPublicKey;
+        data.dbid = input.dbid;
+        data.quarantinedDocId = input.quarantinedDocId;
+        data.rejectionClass = input.rejectionClass;
+        data.reason = input.reason;
+        data.entryIds = kept;
+        if (omitted > 0) {
+            data.omittedEntryCount = omitted;
+        }
+        data.firstSeenAt = typeof current.firstSeenAt === "number" ? current.firstSeenAt : now;
+        data.updatedAt = now;
+    });
+    return doc;
+}
+/**
+ * Withdraw a record, because the entries were finally accepted or the user gave
+ * up on them.
+ */
+async function clearQuarantineRecord(input) {
+    const docId = await quarantineDocumentId(input.key, input.subtle);
+    await input.db.deleteDocument(docId).catch(() => {
+        // Already gone, or never recorded from this device.
+    });
+}
+/**
+ * Check one record's claim. Returns the verified record, or `null` when any step
+ * of the chain described in the module docs fails.
+ */
+async function verifyQuarantineRecord(input) {
+    const docId = input.doc.getId();
+    const data = input.doc.getData();
+    const signingPublicKey = typeof data.signingPublicKey === "string" ? data.signingPublicKey : "";
+    const dbid = typeof data.dbid === "string" ? data.dbid : "";
+    const quarantinedDocId = typeof data.quarantinedDocId === "string" ? data.quarantinedDocId : "";
+    const rejectionClass = data.rejectionClass;
+    if (data.type !== exports.QUARANTINE_TYPE ||
+        !signingPublicKey ||
+        !dbid ||
+        !quarantinedDocId ||
+        typeof rejectionClass !== "string") {
+        return null;
+    }
+    // 1. The id must be derived from the payload's own fields, so a record cannot
+    //    sit under an id describing a different author, database or document than
+    //    the one it names.
+    const fingerprint = await (0, fingerprint_1.fingerprintPublicKeyPem)(signingPublicKey, input.subtle);
+    const expectedId = await quarantineDocumentId({
+        signingKeyFingerprint: fingerprint,
+        dbid,
+        quarantinedDocId,
+        rejectionClass: rejectionClass,
+    }, input.subtle);
+    if (expectedId !== docId) {
+        return null;
+    }
+    // 2. That key must be the one that actually created the document. Without
+    //    this, any member could record a refusal in someone else's name.
+    const creatorKey = await resolveCreateSigner(input.db, docId);
+    if (!creatorKey || normalizePem(creatorKey) !== normalizePem(signingPublicKey)) {
+        return null;
+    }
+    // 3. And it must still be a live grant, so revoked devices drop out.
+    if (!(await input.directory.validatePublicSigningKey(signingPublicKey).catch(() => false))) {
+        return null;
+    }
+    return {
+        docId,
+        signingPublicKey,
+        signingKeyFingerprint: fingerprint,
+        dbid,
+        quarantinedDocId,
+        rejectionClass: rejectionClass,
+        reason: typeof data.reason === "string" ? data.reason : "",
+        entryIds: Array.isArray(data.entryIds)
+            ? data.entryIds.filter((id) => typeof id === "string")
+            : [],
+        omittedEntryCount: typeof data.omittedEntryCount === "number" ? data.omittedEntryCount : 0,
+        firstSeenAt: typeof data.firstSeenAt === "number" ? data.firstSeenAt : 0,
+        updatedAt: typeof data.updatedAt === "number" ? data.updatedAt : 0,
+    };
+}
+/**
+ * Every verified quarantine record in this `userdirectory` replica.
+ *
+ * Requires the tenant `default` key to be unlocked; records that cannot be
+ * decrypted are simply absent. Unverifiable records are skipped silently —
+ * they are the expected shape of an attack, not an error to surface.
+ */
+async function listQuarantineRecords(input) {
+    // `idPrefix` matching is boundary-aware: "qtn" matches `qtn_…`, not `qtnx…`.
+    const docIds = await input.db.getAllDocumentIds({ idPrefix: "qtn" });
+    const records = [];
+    for (const docId of docIds) {
+        if (!isQuarantineDocId(docId)) {
+            continue;
+        }
+        const doc = await input.db.getDocument(docId).catch(() => null);
+        if (!doc) {
+            continue;
+        }
+        const record = await verifyQuarantineRecord({
+            db: input.db,
+            directory: input.directory,
+            doc,
+            subtle: input.subtle,
+        });
+        if (!record) {
+            continue;
+        }
+        if (input.dbid !== undefined && record.dbid !== input.dbid) {
+            continue;
+        }
+        if (input.signingKeyFingerprint !== undefined &&
+            record.signingKeyFingerprint !== input.signingKeyFingerprint) {
+            continue;
+        }
+        records.push(record);
+    }
+    return records;
+}
+/** Signing key that wrote the `doc_create` entry, or null when it is not here yet. */
+async function resolveCreateSigner(db, docId) {
+    try {
+        // History is ordered causally, so `doc_create` is on the first page.
+        const page = await db.getDocumentHistoryPage(docId, { limit: 10 });
+        const create = page.entries.find((entry) => entry.entryType === "doc_create");
+        return create?.changeCreatedByPublicKey ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** PEM formatting varies by transport; compare the key material, not the wrapping. */
+function normalizePem(pem) {
+    return pem.replace(/\s+/g, "");
+}
+//# sourceMappingURL=QuarantineDocument.js.map

package/dist/core/quarantine/QuarantineDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QuarantineDocument.js","sourceRoot":"","sources":["../../../src/core/quarantine/QuarantineDocument.ts"],"names":[],"mappings":"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"}

package/dist/core/quarantine/QuarantineView.d.ts

@@ -0,0 +1,90 @@
+/**
+ * One list for both kinds of quarantine.
+ *
+ * A change can be held back in two directions, and from the user's side they are
+ * the same complaint — "something I have is not where it should be, and nobody
+ * is retrying it":
+ *
+ * - **inbound** — an entry arrived here (over peer-to-peer sync, usually) and
+ *   was refused at materialization, so it sits in the local store without
+ *   affecting any document. Recorded in the metadata checkpoint, local to this
+ *   device, keyed per document. See `QuarantineRecord`.
+ * - **outbound** — an entry was written here and the server refused to ingest
+ *   it, so the push moved on without it. Recorded as a `qtn_` document in
+ *   `userdirectory`, which syncs to the whole tenant. See
+ *   {@link QuarantineRecordDoc}.
+ *
+ * The two live in different places for good reasons — an inbound refusal is a
+ * local verdict that every replica reaches on its own and would be pointless to
+ * broadcast, whereas an outbound one is exactly what other members need to see —
+ * but a user looking for a missing change does not know which of the two
+ * happened. So the storage stays split and the *reading* is unified here.
+ *
+ * ## Why the directions keep their own vocabulary
+ *
+ * Their reasons are genuinely different: an inbound refusal names the check that
+ * failed on this device (`tier2_denied`, `cascade_dependent`, …), an outbound one
+ * names what the server said (`policy`, `purged`, …). Flattening both into one
+ * enum would invent equivalences that do not hold, so {@link QuarantineViewRecord}
+ * is a discriminated union: `direction` tells a caller which vocabulary `reason`
+ * is drawn from, and which fields are even present.
+ */
+import type { QuarantineRecord, QuarantineReason } from "../accesscontrol/materializationGuard";
+import type { PutRejectionClass } from "../appendonlystores/types";
+import { type QuarantineRecordDoc } from "./QuarantineDocument";
+/** Which way the refused change was going. */
+export type QuarantineDirection = "inbound" | "outbound";
+/** What both directions can answer. */
+interface QuarantineViewCommon {
+    /** Database the refused entries belong to. */
+    dbid: string;
+    /** Document the refused entries belong to. */
+    documentId: string;
+    /** The refusing side's own wording, for the audit view. */
+    detail: string;
+    /** Refused entry ids, capped at {@link MAX_QUARANTINED_ENTRY_IDS}. */
+    entryIds: string[];
+    /** How many refused entries did not fit into {@link entryIds}. */
+    omittedEntryCount: number;
+    /** When this refusal was first seen. */
+    firstSeenAt: number;
+    /** When it was last confirmed. */
+    updatedAt: number;
+}
+/**
+ * One row of the unified quarantine view: all the entries of one document held
+ * back for one reason, in one direction.
+ */
+export type QuarantineViewRecord = (QuarantineViewCommon & {
+    direction: "inbound";
+    /** Which materialization check refused the entries on this device. */
+    reason: QuarantineReason;
+}) | (QuarantineViewCommon & {
+    direction: "outbound";
+    /** How the target classified its refusal. */
+    reason: PutRejectionClass;
+    /** Fingerprint of the signing key whose push was refused. */
+    signingKeyFingerprint: string;
+    /** The `qtn_` document holding this record, so a caller can withdraw it. */
+    recordDocId: string;
+});
+/**
+ * Fold the local materialization log into view rows.
+ *
+ * The log holds one record per entry, because an inbound refusal is decided per
+ * entry; the view groups them per (database, document, reason) so one poisoned
+ * entry dragging fifty dependents along reads as one problem rather than
+ * fifty-one — matching how the outbound records are already shaped.
+ */
+export declare function inboundQuarantineView(log: readonly QuarantineRecord[]): QuarantineViewRecord[];
+/** Turn verified `qtn_` records into view rows. */
+export declare function outboundQuarantineView(records: readonly QuarantineRecordDoc[]): QuarantineViewRecord[];
+/**
+ * The whole quarantine view, newest first.
+ *
+ * Newest first because the list is read when a change has gone missing, and the
+ * change someone is looking for is almost always the last one they made.
+ */
+export declare function mergeQuarantineViews(...groups: readonly (readonly QuarantineViewRecord[])[]): QuarantineViewRecord[];
+export {};
+//# sourceMappingURL=QuarantineView.d.ts.map

package/dist/core/quarantine/QuarantineView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QuarantineView.d.ts","sourceRoot":"","sources":["../../../src/core/quarantine/QuarantineView.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAChG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3F,8CAA8C;AAC9C,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,UAAU,CAAC;AAEzD,uCAAuC;AACvC,UAAU,oBAAoB;IAC5B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAC5B,CAAC,oBAAoB,GAAG;IACtB,SAAS,EAAE,SAAS,CAAC;IACrB,sEAAsE;IACtE,MAAM,EAAE,gBAAgB,CAAC;CAC1B,CAAC,GACF,CAAC,oBAAoB,GAAG;IACtB,SAAS,EAAE,UAAU,CAAC;IACtB,6CAA6C;IAC7C,MAAM,EAAE,iBAAiB,CAAC;IAC1B,6DAA6D;IAC7D,qBAAqB,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAEP;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,SAAS,gBAAgB,EAAE,GAC/B,oBAAoB,EAAE,CA4BxB;AAED,mDAAmD;AACnD,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,mBAAmB,EAAE,GACtC,oBAAoB,EAAE,CAcxB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,MAAM,EAAE,SAAS,CAAC,SAAS,oBAAoB,EAAE,CAAC,EAAE,GACtD,oBAAoB,EAAE,CAUxB"}