@sagmans/dsh-tui 0.3.0 → 0.5.0

package/lib/stash/private-fs.js

@@ -0,0 +1,379 @@
+// No-follow filesystem primitives for sensitive draft storage.
+//
+// Path-based chmod/read helpers can follow a link swapped into place after a
+// check. Opening the validated inode and operating through its handle keeps
+// permission repair and reads bound to the object that was inspected. Ownership
+// and symlink checks are what keep one user's drafts out of another's reach on a
+// shared machine or a network home.
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, readlink, rmdir, rm, unlink } from 'node:fs/promises';
+import path from 'node:path';
+export const PRIVATE_DIR_MODE = 0o700;
+export const PRIVATE_FILE_MODE = 0o600;
+const MAX_QUARANTINE_ATTEMPTS = 1000;
+const NO_FOLLOW_FLAG = constants.O_NOFOLLOW ?? 0;
+const DIRECTORY_FLAG = constants.O_DIRECTORY ?? 0;
+const ROOT_UID = 0;
+const WORLD_WRITABLE_MODE = 0o002;
+const GROUP_WRITABLE_MODE = 0o020;
+const STICKY_MODE = 0o1000;
+/** The kernel's own limit on a link chain, past which the path cannot be opened anyway. */
+const MAX_LINK_HOPS = 32;
+const TOO_MANY_LINKS_MESSAGE = 'passes through too many links to be checked';
+const UNTRUSTED_ANCESTOR_MESSAGE = 'is writable by other users, so a stash kept there could be redirected to another directory by anyone on this machine';
+/** A file that exceeded the caller's byte budget, which is a refusal, not corruption. */
+export class FileTooLargeError extends Error {
+    constructor(label) {
+        super(`${label} is too large`);
+        this.name = 'FileTooLargeError';
+    }
+}
+/**
+ * Prepare the storage directory, and make the directories that name it durable.
+ *
+ * A directory that names a new child holds the only record of that child, so
+ * every directory this call creates is flushed through its parent before the
+ * call returns. A step that fails takes the created directories away again:
+ * leaving them behind would turn the next attempt into one that finds nothing
+ * left to flush, and a save could then report success for a tree that a power
+ * loss is free to drop.
+ *
+ * The rollback only ever removes an empty directory. Another surface can reach a
+ * directory this call just created and save into it while this one is flushing,
+ * and a recursive removal would then delete that surface's committed bank: an
+ * entry left unflushed costs durability, while a removed bank costs the draft.
+ */
+export async function ensurePrivateDirectory(directory, label = 'storage directory', syncDirectory = syncDirectoryEntry) {
+    await assertTrustedAncestors(directory, label);
+    const { created, namingParents } = await createPrivateDirectory(directory);
+    try {
+        const handle = await openValidatedDirectory(directory, label);
+        try {
+            await handle.chmod(PRIVATE_DIR_MODE);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        for (const parent of namingParents)
+            await syncDirectory(parent);
+    }
+    catch (error) {
+        // Deepest first, so a directory is only removed once nothing is named by it.
+        for (const entry of created) {
+            try {
+                await rmdir(entry);
+            }
+            catch {
+                // Anything still in the way belongs to another writer now, and leaving it
+                // is the whole point of not removing the tree recursively.
+                break;
+            }
+        }
+        throw error;
+    }
+}
+/** Create the directory chain, reporting what it created and what names it. */
+async function createPrivateDirectory(directory) {
+    const created = [];
+    let current = path.resolve(directory);
+    for (;;) {
+        if (await pathExists(current))
+            break;
+        created.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    await mkdir(directory, { recursive: true, mode: PRIVATE_DIR_MODE });
+    // The parent of a created directory is where its entry lives; a directory that
+    // was itself just created is named by the next step of the walk.
+    return { created, namingParents: created.map(entry => path.dirname(entry)) };
+}
+/**
+ * Refuse a storage path that anyone but this user (or root) can rewrite.
+ *
+ * Opening the storage directory without following a link protects that one
+ * component, but a directory another user can write is enough to redirect the
+ * storage by replacing an entry below it, so every directory that the path
+ * passes through has to be checked. The writable bit that matters is any bit but
+ * the owner's: a group member can rename an entry just as a stranger can, so only
+ * the sticky bit — which reserves renaming to an entry's owner — makes a shared
+ * directory acceptable.
+ *
+ * Links are followed on purpose, because a link like macOS's `/tmp` is not a
+ * threat and the permissions of what it resolves to are what count. Each link is
+ * therefore read as a link and its target walked in turn, rather than resolved in
+ * one step: a chain that jumps through a shared directory would otherwise be
+ * checked only where it lands, and the directory it jumped through is the one
+ * another user can rewrite.
+ */
+async function assertTrustedAncestors(directory, label) {
+    const currentUid = process.getuid?.();
+    const pending = [path.resolve(directory)];
+    const checked = new Set();
+    let hops = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (checked.has(current))
+            continue;
+        checked.add(current);
+        let stats;
+        try {
+            stats = await lstat(current);
+        }
+        catch (error) {
+            // A directory that is not there yet is created by the caller; its
+            // ancestors still have to be checked, so a miss is not a failure here.
+            if (!hasErrorCode(error, 'ENOENT'))
+                throw error;
+            pending.push(...parentsOf(current));
+            continue;
+        }
+        // A link's own mode decides nothing, but its owner decides everything: in a
+        // directory that is sticky, the one account that can repoint a link is the
+        // one that owns it, so a link this user does not own is not followed.
+        if (stats.isSymbolicLink()) {
+            if (currentUid !== undefined && stats.uid !== currentUid && stats.uid !== ROOT_UID) {
+                throw new Error(`${label} at ${current} is owned by another user`);
+            }
+            hops += 1;
+            if (hops > MAX_LINK_HOPS)
+                throw new Error(`${label} at ${current} ${TOO_MANY_LINKS_MESSAGE}`);
+            // The target is not normalized: `..` after a link has to be resolved by the
+            // filesystem against what the link points at, and collapsing it here would
+            // walk a directory the kernel never visits.
+            const target = await readlink(current);
+            pending.push(path.isAbsolute(target) ? target : `${path.dirname(current)}/${target}`, ...parentsOf(current));
+            continue;
+        }
+        assertTrustedStats(stats, current, label, currentUid);
+        pending.push(...parentsOf(current));
+    }
+}
+/** The one directory that names `current`, if it has one. */
+function parentsOf(current) {
+    const parent = path.dirname(current);
+    return parent === current ? [] : [parent];
+}
+function assertTrustedStats(stats, directory, label, currentUid) {
+    if (currentUid !== undefined && stats.uid !== currentUid && stats.uid !== ROOT_UID) {
+        throw new Error(`${label} at ${directory} is owned by another user`);
+    }
+    const shared = stats.mode & (WORLD_WRITABLE_MODE | GROUP_WRITABLE_MODE);
+    if (shared !== 0 && (stats.mode & STICKY_MODE) === 0) {
+        throw new Error(`${label} at ${directory} ${UNTRUSTED_ANCESTOR_MESSAGE}`);
+    }
+}
+/**
+ * Flush one directory entry without asserting who owns the directory.
+ *
+ * An ancestor may legitimately be root-owned (`/tmp`, a mount point) and still
+ * have to be synced for the entry below it to survive a power loss, so the
+ * ownership rule that guards the storage directory itself is not applied here.
+ * A directory that is already gone needs no flushing.
+ */
+export async function syncDirectoryEntry(directory) {
+    let handle;
+    try {
+        handle = await open(directory, constants.O_RDONLY | DIRECTORY_FLAG);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return;
+        throw error;
+    }
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function assertPrivateDirectory(directory, label) {
+    const handle = await openValidatedDirectory(directory, label);
+    try {
+        return await handle.stat();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function syncPrivateDirectory(directory, label = 'storage directory') {
+    const handle = await openValidatedDirectory(directory, label);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readPrivateTextFile(filePath, label = 'stash file', maxBytes) {
+    const before = await lstat(filePath);
+    assertRegularOwnedFile(before, label);
+    const handle = await open(filePath, constants.O_RDONLY | NO_FOLLOW_FLAG);
+    try {
+        const opened = await handle.stat();
+        assertRegularOwnedFile(opened, label);
+        assertSameIdentity(before, opened, label);
+        await handle.chmod(PRIVATE_FILE_MODE);
+        return { text: await readText(handle, maxBytes, label), identity: identityOf(opened) };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readText(handle, maxBytes, label) {
+    if (maxBytes === undefined)
+        return handle.readFile('utf8');
+    const buffer = Buffer.alloc(maxBytes + 1);
+    let bytesRead = 0;
+    while (bytesRead < buffer.length) {
+        const chunk = await handle.read(buffer, bytesRead, buffer.length - bytesRead, null);
+        if (chunk.bytesRead === 0)
+            break;
+        bytesRead += chunk.bytesRead;
+    }
+    if (bytesRead > maxBytes)
+        throw new FileTooLargeError(label);
+    return buffer.subarray(0, bytesRead).toString('utf8');
+}
+export async function writePrivateFileExclusive(filePath, data) {
+    const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NO_FOLLOW_FLAG;
+    const handle = await open(filePath, flags, PRIVATE_FILE_MODE);
+    let succeeded = false;
+    try {
+        await handle.writeFile(data);
+        await handle.chmod(PRIVATE_FILE_MODE);
+        await handle.sync();
+        succeeded = true;
+    }
+    finally {
+        await handle.close();
+        if (!succeeded)
+            await rm(filePath, { force: true });
+    }
+}
+/**
+ * Move a file aside without losing it.
+ *
+ * A hard-link reservation keeps the original bytes reachable under a new name
+ * before the source is unlinked, so an interrupted quarantine leaves either the
+ * readable original or the readable copy, never neither.
+ */
+export async function quarantinePrivateFile(filePath, identity, label, syncDirectory = syncPrivateDirectory) {
+    for (let attempt = 0; attempt < MAX_QUARANTINE_ATTEMPTS; attempt += 1) {
+        const candidate = `${filePath}.${label}${attempt === 0 ? '' : `-${attempt}`}`;
+        try {
+            await link(filePath, candidate);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'EEXIST'))
+                continue;
+            throw error;
+        }
+        let moved = false;
+        try {
+            const candidateStats = await lstat(candidate);
+            const sourceStats = await lstat(filePath);
+            assertSameIdentity(candidateStats, identity, 'quarantine source');
+            assertSameIdentity(sourceStats, identity, 'quarantine source');
+            await unlink(filePath);
+            moved = true;
+            try {
+                await syncDirectory(path.dirname(filePath));
+            }
+            catch (error) {
+                // The bytes are already under the recovery name and the original is
+                // gone, so the path is the one thing the reader must still be told.
+                // Throwing here would lose it and leave the next read starting empty
+                // with no notice at all.
+                return { path: candidate, syncError: error };
+            }
+            return { path: candidate, syncError: undefined };
+        }
+        finally {
+            if (!moved)
+                await unlink(candidate).catch(() => undefined);
+        }
+    }
+    throw new Error(`unable to reserve quarantine path for ${filePath}`);
+}
+export async function removePrivateDirectory(directory, label = 'storage directory') {
+    let stats;
+    try {
+        stats = await lstat(directory);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return;
+        throw error;
+    }
+    assertDirectory(stats, label);
+    assertCurrentUserOwns(stats, label);
+    await rm(directory, { recursive: true });
+    await syncPrivateDirectory(path.dirname(directory));
+}
+async function openValidatedDirectory(directory, label) {
+    const before = await lstat(directory);
+    assertDirectory(before, label);
+    assertCurrentUserOwns(before, label);
+    const handle = await open(directory, constants.O_RDONLY | DIRECTORY_FLAG | NO_FOLLOW_FLAG);
+    try {
+        const opened = await handle.stat();
+        assertDirectory(opened, label);
+        assertCurrentUserOwns(opened, label);
+        assertSameIdentity(before, opened, label);
+        return handle;
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+function assertDirectory(stats, label) {
+    if (stats.isSymbolicLink())
+        throw new Error(`${label} must not be a symbolic link`);
+    if (!stats.isDirectory())
+        throw new Error(`${label} must be a directory`);
+}
+export function assertRegularOwnedFile(stats, label) {
+    if (stats.isSymbolicLink())
+        throw new Error(`${label} must not be a symbolic link`);
+    if (!stats.isFile())
+        throw new Error(`${label} must be a regular file`);
+    assertCurrentUserOwns(stats, label);
+}
+function assertCurrentUserOwns(stats, label) {
+    const currentUid = process.getuid?.();
+    if (currentUid !== undefined && stats.uid !== currentUid) {
+        throw new Error(`${label} must be owned by the current user`);
+    }
+}
+function assertSameIdentity(actual, expected, label) {
+    if (actual.dev !== expected.dev || actual.ino !== expected.ino) {
+        throw new Error(`${label} changed during validation`);
+    }
+}
+function identityOf(stats) {
+    return { dev: stats.dev, ino: stats.ino };
+}
+export async function pathExists(target) {
+    try {
+        await lstat(target);
+        return true;
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return false;
+        throw error;
+    }
+}
+export function hasErrorCode(value, code) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'code' in value &&
+        value.code === code);
+}
+//# sourceMappingURL=private-fs.js.map

package/lib/stash/private-fs.js.map

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

package/lib/stash/schema.d.ts

@@ -0,0 +1,56 @@
+export declare const STASH_SCHEMA_VERSION = 2;
+/** A stash longer than this is refused rather than stored. */
+export declare const MAX_STASH_ENTRY_BYTES = 1048576;
+export declare function isSafeEntryId(value: string): boolean;
+export declare function assertSafeEntryId(value: string): void;
+/** Refuse one draft that no amount of storage capacity could justify holding. */
+export declare function assertSafeStashText(text: string): void;
+/** The form of a draft that is safe to hand back to a terminal. */
+export declare function sanitizeStashText(text: string): string;
+export interface StashEntry {
+    readonly id: string;
+    readonly text: string;
+    readonly createdAt: number;
+}
+export interface StashFile {
+    readonly version: typeof STASH_SCHEMA_VERSION;
+    /**
+     * The exact session this bank belongs to.
+     *
+     * The key alone cannot prove ownership: it is a flattened label that two
+     * sessions could once have shared. The exact id is compared on every read, so
+     * a file that belongs to another session is quarantined rather than read or
+     * deleted as this one's.
+     */
+    readonly sessionId: string;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    /** Newest first: `entries[0]` is `stash@{0}`. */
+    readonly entries: readonly StashEntry[];
+}
+export type Clock = () => number;
+export declare const createNewId: () => string;
+export declare function createEmptyStashFile(sessionId: string, now: number): StashFile;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function normalizeEntry(raw: unknown): StashEntry | undefined;
+/**
+ * Read one stash file, or nothing when it is not this surface's current format.
+ *
+ * Strict on purpose: a duplicate id, a missing timestamp, or a foreign session
+ * is corruption the store quarantines rather than a shape to repair, because a
+ * silently repaired file can resurrect entries the reader thought they dropped —
+ * or hand another session's drafts to this one.
+ */
+export declare function parseStashFile(raw: unknown): StashFile | undefined;
+export interface ResolvedEntry {
+    readonly entry: StashEntry;
+    readonly index: number;
+}
+/**
+ * Resolve a selector against newest-first entries.
+ *
+ * Index 0 is the newest, mirroring git's index-0-is-tip convention. A selector
+ * is an entry id, a numeric index string, or empty for the most recent entry.
+ */
+export declare function resolveBySelector(entries: readonly StashEntry[], selector: string | undefined): ResolvedEntry | undefined;
+//# sourceMappingURL=schema.d.ts.map

package/lib/stash/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/stash/schema.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,UAAY,CAAA;AAQ9C,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAErD;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEtD;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,oBAAoB,CAAA;IAC7C;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;CACxC;AAED,MAAM,MAAM,KAAK,GAAG,MAAM,MAAM,CAAA;AAEhC,eAAO,MAAM,WAAW,QAAO,MAAsB,CAAA;AAErD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAE9E;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAMD,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAOnE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAclE;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,aAAa,GAAG,SAAS,CAc3B"}

package/lib/stash/schema.js

@@ -0,0 +1,108 @@
+// Stash entry + file schema and pure parsing/validation helpers.
+//
+// Every disk format is validated on read, so a corrupt or hand-edited stash file
+// can never crash the editor: an unparseable file is treated as empty and
+// quarantined by the store. Keeping this module free of fs dependencies makes
+// the schema fully unit-testable.
+import { randomUUID } from 'node:crypto';
+import { stripControlCharacters } from "../text.js";
+export const STASH_SCHEMA_VERSION = 2;
+/** A stash longer than this is refused rather than stored. */
+export const MAX_STASH_ENTRY_BYTES = 1_048_576;
+const ENTRY_ID_MAX_LENGTH = 128;
+const ENTRY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const NUMERIC_SELECTOR_PATTERN = /^\d+$/u;
+const INVALID_ENTRY_ID_MESSAGE = 'invalid stash entry id';
+const ENTRY_TOO_LARGE_MESSAGE = 'stashed draft is too large';
+export function isSafeEntryId(value) {
+    return value.length <= ENTRY_ID_MAX_LENGTH && ENTRY_ID_PATTERN.test(value);
+}
+export function assertSafeEntryId(value) {
+    if (!isSafeEntryId(value))
+        throw new Error(INVALID_ENTRY_ID_MESSAGE);
+}
+/** Refuse one draft that no amount of storage capacity could justify holding. */
+export function assertSafeStashText(text) {
+    if (Buffer.byteLength(text, 'utf8') > MAX_STASH_ENTRY_BYTES)
+        throw new Error(ENTRY_TOO_LARGE_MESSAGE);
+}
+/** The form of a draft that is safe to hand back to a terminal. */
+export function sanitizeStashText(text) {
+    return stripControlCharacters(text);
+}
+export const createNewId = () => randomUUID();
+export function createEmptyStashFile(sessionId, now) {
+    return { version: STASH_SCHEMA_VERSION, sessionId, createdAt: now, updatedAt: now, entries: [] };
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isValidTimestamp(value) {
+    return typeof value === 'number' && Number.isFinite(value) && !Number.isNaN(new Date(value).getTime());
+}
+export function normalizeEntry(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const { id, text, createdAt } = raw;
+    if (typeof id !== 'string' || !isSafeEntryId(id))
+        return undefined;
+    if (typeof text !== 'string')
+        return undefined;
+    if (!isValidTimestamp(createdAt))
+        return undefined;
+    return { id, text: sanitizeStashText(text), createdAt };
+}
+/**
+ * Read one stash file, or nothing when it is not this surface's current format.
+ *
+ * Strict on purpose: a duplicate id, a missing timestamp, or a foreign session
+ * is corruption the store quarantines rather than a shape to repair, because a
+ * silently repaired file can resurrect entries the reader thought they dropped —
+ * or hand another session's drafts to this one.
+ */
+export function parseStashFile(raw) {
+    if (!isRecord(raw) || raw.version !== STASH_SCHEMA_VERSION)
+        return undefined;
+    if (typeof raw.sessionId !== 'string')
+        return undefined;
+    if (!isValidTimestamp(raw.createdAt) || !isValidTimestamp(raw.updatedAt))
+        return undefined;
+    if (!Array.isArray(raw.entries))
+        return undefined;
+    const entries = [];
+    const ids = new Set();
+    for (const rawEntry of raw.entries) {
+        const entry = normalizeEntry(rawEntry);
+        if (entry === undefined || ids.has(entry.id))
+            return undefined;
+        ids.add(entry.id);
+        entries.push(entry);
+    }
+    return { version: STASH_SCHEMA_VERSION, sessionId: raw.sessionId, createdAt: raw.createdAt, updatedAt: raw.updatedAt, entries };
+}
+/**
+ * Resolve a selector against newest-first entries.
+ *
+ * Index 0 is the newest, mirroring git's index-0-is-tip convention. A selector
+ * is an entry id, a numeric index string, or empty for the most recent entry.
+ */
+export function resolveBySelector(entries, selector) {
+    if (entries.length === 0)
+        return undefined;
+    const trimmed = selector?.trim();
+    if (trimmed === undefined || trimmed === '') {
+        const entry = entries[0];
+        return entry === undefined ? undefined : { entry, index: 0 };
+    }
+    const index = entries.findIndex(entry => entry.id === trimmed);
+    if (index >= 0)
+        return { entry: entries[index], index };
+    if (!NUMERIC_SELECTOR_PATTERN.test(trimmed))
+        return undefined;
+    const numeric = Number(trimmed);
+    if (!Number.isSafeInteger(numeric) || numeric >= entries.length)
+        return undefined;
+    const entry = entries[numeric];
+    return entry === undefined ? undefined : { entry, index: numeric };
+}
+//# sourceMappingURL=schema.js.map

package/lib/stash/schema.js.map

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

package/lib/stash/store.d.ts

@@ -0,0 +1,92 @@
+import { rename } from 'node:fs/promises';
+import { type StashFailurePhase } from './lock.ts';
+import type { StashPaths } from './paths.ts';
+import { syncDirectoryEntry } from './private-fs.ts';
+import { type Clock, type ResolvedEntry, type StashEntry, type StashFile } from './schema.ts';
+/**
+ * A stash file larger than this is refused, never quarantined: hiding a
+ * legitimate bank because it grew past a cap would be worse than refusing it.
+ */
+export declare const MAX_STASH_FILE_BYTES = 16777216;
+/**
+ * A bank that cannot be written because it would no longer be readable.
+ *
+ * The cap is only useful if it is enforced before the write: a file that grows
+ * past it is refused by every later read, so letting one save through would turn
+ * a full bank into an unreadable one.
+ */
+export declare class StashFileTooLargeError extends Error {
+    readonly bytes: number;
+    constructor(bytes: number);
+}
+export interface AddEntryInput {
+    readonly text: string;
+    /** Caller-supplied id; generated when omitted. */
+    readonly id?: string;
+    /** Caller-supplied timestamp, used only when a recovery path restores an entry. */
+    readonly createdAt?: number;
+}
+type LoadResult = {
+    kind: 'ready';
+    file: StashFile;
+} | {
+    kind: 'corrupt';
+    quarantinedTo: string | undefined;
+    quarantineSyncFailed: boolean;
+} | {
+    kind: 'unsupported';
+    version: number;
+};
+/** Where a read moved an unreadable bank, and whether that move is durable. */
+export interface QuarantineRecord {
+    readonly path: string;
+    readonly syncFailed: boolean;
+}
+export interface StashWriteOutcome {
+    readonly committed: true;
+    readonly phase: StashFailurePhase;
+    readonly error: unknown;
+}
+export type StashWriter = (filePath: string, file: StashFile, syncDirectory?: typeof syncDirectoryEntry, replaceFile?: typeof rename) => Promise<void | StashWriteOutcome>;
+/** Stash data written by a newer build, which this one must not touch. */
+export declare class UnsupportedStashSchemaError extends Error {
+    readonly detectedVersion: number;
+    readonly supportedVersion: number;
+    constructor(detectedVersion: number, supportedVersion?: number);
+}
+export declare class StashStore {
+    private file;
+    private corruptRecovery;
+    private readonly filePath;
+    private readonly paths;
+    private readonly now;
+    private readonly write;
+    constructor(paths: StashPaths, loaded: LoadResult, now?: Clock, write?: StashWriter);
+    get entries(): readonly StashEntry[];
+    get entryCount(): number;
+    /** The recovery location the last read produced, if any, reported once. */
+    takeQuarantine(): QuarantineRecord | undefined;
+    /** Resolve a selector against the entries currently held. */
+    find(selector: string | undefined): ResolvedEntry | undefined;
+    refresh(): Promise<void>;
+    add(input: AddEntryInput): Promise<ResolvedEntry>;
+    /** Remove one entry by its exact id, reporting what was removed. */
+    removeById(id: string): Promise<ResolvedEntry | undefined>;
+    /** Remove the entry a selector names, reporting what was removed. */
+    drop(selector: string | undefined): Promise<ResolvedEntry | undefined>;
+    /**
+     * Remove drafts, reporting how many were dropped.
+     *
+     * Ids restrict the removal to exactly what a reader confirmed. Clearing
+     * whatever is on disk instead would delete drafts another surface added while
+     * the confirmation was on screen, which is a loss nobody agreed to.
+     */
+    clear(ids?: readonly string[]): Promise<number>;
+    private removeAt;
+    private persistMutation;
+    private reloadFresh;
+}
+export declare function loadStashStore(paths: StashPaths, now?: Clock, write?: StashWriter): Promise<StashStore>;
+export declare function writeStashFile(filePath: string, file: StashFile, syncDirectory?: typeof syncDirectoryEntry, replaceFile?: typeof rename): Promise<void | StashWriteOutcome>;
+export {};
+//# sourceMappingURL=store.d.ts.map