@sagmans/dsh-tui 0.3.0 → 0.4.0

package/lib/stash/paths.js

@@ -0,0 +1,83 @@
+// Disk layout for prompt stashes.
+//
+// A stash is scoped to the exact working directory: a linked worktree, a bare
+// checkout, and a plain folder are all just distinct cwd values, so keying on
+// cwd covers every case without any git discovery. The cwd is flattened into a
+// filename-safe key that stays human-readable in the agent directory.
+//
+// Readability cannot be bought with injectivity: a separator made of hyphens
+// cannot be told apart from a hyphen inside a directory name, and truncating a
+// deep path can land on a name a shorter path already owns. Two working
+// directories sharing one bank would let one directory read or delete another's
+// drafts, so every key ends with a digest of the exact cwd. The readable part is
+// then only a label: two distinct cwds collide in the label, never in the file.
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import path from 'node:path';
+/** The directory `DSH_HOME` points at when the environment names none. */
+const DEFAULT_DSH_HOME_DIR = '.dsh';
+/** The subtree of `DSH_HOME` this surface owns. */
+const STASH_DIR_NAME = 'tui-stash';
+// POSIX filenames may not contain "/" or NUL, and everything else is legal, so
+// once separators are flattened the result is filename-safe on the platforms
+// this surface targets. 200 keeps the whole key, digest included, well under the
+// common 255-byte filename limit.
+const SANITIZE_MAX_LENGTH = 200;
+const SEPARATOR = '--';
+const KEY_FORMAT_VERSION = 'v1';
+const KEY_PREFIX = `${KEY_FORMAT_VERSION}${SEPARATOR}`;
+const ESCAPE_CHARACTER = '%';
+const ESCAPED_ESCAPE_CHARACTER = '%25';
+const ESCAPED_SEPARATOR = '%2D%2D';
+const BACKSLASH = '\\';
+const ESCAPED_BACKSLASH = '%5C';
+const HASH_ALGORITHM = 'sha256';
+/** 64 bits of digest, which no deliberate name can be built to collide with. */
+const HASH_LENGTH = 16;
+/** Escape one path segment so it cannot collide with the separator or an escape. */
+function escapeSegment(segment) {
+    return segment
+        .replaceAll(ESCAPE_CHARACTER, ESCAPED_ESCAPE_CHARACTER)
+        .replaceAll(BACKSLASH, ESCAPED_BACKSLASH)
+        .replaceAll(SEPARATOR, ESCAPED_SEPARATOR);
+}
+/** Keep whole characters while fitting a byte budget, so a cut cannot split one. */
+function truncateToUtf8Bytes(value, maxBytes) {
+    let bytes = 0;
+    let result = '';
+    for (const character of value) {
+        const characterBytes = Buffer.byteLength(character);
+        if (bytes + characterBytes > maxBytes)
+            break;
+        result += character;
+        bytes += characterBytes;
+    }
+    return result;
+}
+export function sanitizeCwd(cwd) {
+    const readable = cwd.split('/').filter(Boolean).map(escapeSegment).join(SEPARATOR);
+    const digest = createHash(HASH_ALGORITHM).update(cwd, 'utf8').digest('hex').slice(0, HASH_LENGTH);
+    const suffix = `${SEPARATOR}${digest}`;
+    const budget = SANITIZE_MAX_LENGTH - Buffer.byteLength(KEY_PREFIX) - Buffer.byteLength(suffix);
+    return `${KEY_PREFIX}${truncateToUtf8Bytes(readable, Math.max(budget, 0))}${suffix}`;
+}
+/**
+ * The directory the harness keeps its own state in.
+ *
+ * DSH_HOME is the one thing that moves that directory, and it is resolved the
+ * same way the settings document resolves it, so a scratch home keeps stash data
+ * out of a reader's real home during a test run.
+ */
+export function dshHomeDir(env = process.env, home = homedir()) {
+    const configured = env.DSH_HOME?.trim();
+    return configured === undefined || configured === '' ? path.join(home, DEFAULT_DSH_HOME_DIR) : configured;
+}
+/** The root every working directory's stash file sits under. */
+export function stashBaseDir(env = process.env, home = homedir()) {
+    return path.join(dshHomeDir(env, home), STASH_DIR_NAME);
+}
+export function resolveStashPaths(cwd, baseDir = stashBaseDir()) {
+    const key = sanitizeCwd(cwd);
+    return { cwd, key, file: path.join(baseDir, `${key}.json`) };
+}
+//# sourceMappingURL=paths.js.map

package/lib/stash/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/stash/paths.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,sEAAsE;AACtE,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,wEAAwE;AACxE,gFAAgF;AAChF,iFAAiF;AACjF,gFAAgF;AAEhF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B,0EAA0E;AAC1E,MAAM,oBAAoB,GAAG,MAAM,CAAA;AAEnC,mDAAmD;AACnD,MAAM,cAAc,GAAG,WAAW,CAAA;AAElC,+EAA+E;AAC/E,6EAA6E;AAC7E,iFAAiF;AACjF,kCAAkC;AAClC,MAAM,mBAAmB,GAAG,GAAG,CAAA;AAC/B,MAAM,SAAS,GAAG,IAAI,CAAA;AACtB,MAAM,kBAAkB,GAAG,IAAI,CAAA;AAC/B,MAAM,UAAU,GAAG,GAAG,kBAAkB,GAAG,SAAS,EAAE,CAAA;AACtD,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAC5B,MAAM,wBAAwB,GAAG,KAAK,CAAA;AACtC,MAAM,iBAAiB,GAAG,QAAQ,CAAA;AAClC,MAAM,SAAS,GAAG,IAAI,CAAA;AACtB,MAAM,iBAAiB,GAAG,KAAK,CAAA;AAC/B,MAAM,cAAc,GAAG,QAAQ,CAAA;AAC/B,gFAAgF;AAChF,MAAM,WAAW,GAAG,EAAE,CAAA;AAYtB,oFAAoF;AACpF,SAAS,aAAa,CAAC,OAAe;IACpC,OAAO,OAAO;SACX,UAAU,CAAC,gBAAgB,EAAE,wBAAwB,CAAC;SACtD,UAAU,CAAC,SAAS,EAAE,iBAAiB,CAAC;SACxC,UAAU,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAA;AAC7C,CAAC;AAED,oFAAoF;AACpF,SAAS,mBAAmB,CAAC,KAAa,EAAE,QAAgB;IAC1D,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,IAAI,MAAM,GAAG,EAAE,CAAA;IACf,KAAK,MAAM,SAAS,IAAI,KAAK,EAAE,CAAC;QAC9B,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAA;QACnD,IAAI,KAAK,GAAG,cAAc,GAAG,QAAQ;YAAE,MAAK;QAC5C,MAAM,IAAI,SAAS,CAAA;QACnB,KAAK,IAAI,cAAc,CAAA;IACzB,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAClF,MAAM,MAAM,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAA;IACjG,MAAM,MAAM,GAAG,GAAG,SAAS,GAAG,MAAM,EAAE,CAAA;IACtC,MAAM,MAAM,GAAG,mBAAmB,GAAG,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;IAC9F,OAAO,GAAG,UAAU,GAAG,mBAAmB,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,CAAA;AACtF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAE,OAAe,OAAO,EAAE;IACvF,MAAM,UAAU,GAAG,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAA;IACvC,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC,UAAU,CAAA;AAC3G,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,YAAY,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAE,OAAe,OAAO,EAAE;IACzF,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,cAAc,CAAC,CAAA;AACzD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,UAAkB,YAAY,EAAE;IAC7E,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAA;IAC5B,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,EAAE,CAAA;AAC9D,CAAC"}

package/lib/stash/private-fs.d.ts

@@ -0,0 +1,61 @@
+import { type Stats } from 'node:fs';
+export declare const PRIVATE_DIR_MODE = 448;
+export declare const PRIVATE_FILE_MODE = 384;
+type FileIdentity = Pick<Stats, 'dev' | 'ino'>;
+export interface PrivateTextFile {
+    readonly text: string;
+    readonly identity: FileIdentity;
+}
+/** Where a quarantined file went, and whether that location reached the disk. */
+export interface QuarantineResult {
+    readonly path: string;
+    /** Set when the directory naming the copy could not be synced. */
+    readonly syncError: unknown;
+}
+/** A file that exceeded the caller's byte budget, which is a refusal, not corruption. */
+export declare class FileTooLargeError extends Error {
+    constructor(label: string);
+}
+/**
+ * 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 declare function ensurePrivateDirectory(directory: string, label?: string, syncDirectory?: typeof syncDirectoryEntry): Promise<void>;
+/**
+ * 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 declare function syncDirectoryEntry(directory: string): Promise<void>;
+export declare function assertPrivateDirectory(directory: string, label: string): Promise<Stats>;
+export declare function syncPrivateDirectory(directory: string, label?: string): Promise<void>;
+export declare function readPrivateTextFile(filePath: string, label?: string, maxBytes?: number): Promise<PrivateTextFile>;
+export declare function writePrivateFileExclusive(filePath: string, data: string | Uint8Array): Promise<void>;
+/**
+ * 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 declare function quarantinePrivateFile(filePath: string, identity: FileIdentity, label: string, syncDirectory?: typeof syncPrivateDirectory): Promise<QuarantineResult>;
+export declare function removePrivateDirectory(directory: string, label?: string): Promise<void>;
+export declare function assertRegularOwnedFile(stats: Stats, label: string): void;
+export declare function pathExists(target: string): Promise<boolean>;
+export declare function hasErrorCode(value: unknown, code: string): boolean;
+export {};
+//# sourceMappingURL=private-fs.d.ts.map

package/lib/stash/private-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-fs.d.ts","sourceRoot":"","sources":["../../src/stash/private-fs.ts"],"names":[],"mappings":"AAQA,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,SAAS,CAAA;AAI/C,eAAO,MAAM,gBAAgB,MAAQ,CAAA;AACrC,eAAO,MAAM,iBAAiB,MAAQ,CAAA;AAgBtC,KAAK,YAAY,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,CAAA;AAE9C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;CAChC;AAED,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED,yFAAyF;AACzF,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,KAAK,EAAE,MAAM;CAI1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,KAAK,SAAsB,EAC3B,aAAa,GAAE,OAAO,kBAAuC,GAC5D,OAAO,CAAC,IAAI,CAAC,CAyBf;AAuGD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAazE;AAED,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAO7F;AAED,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxG;AAED,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,KAAK,SAAe,EACpB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,CAAC,CAa1B;AAeD,wBAAsB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAa1G;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,MAAM,EACb,aAAa,GAAE,OAAO,oBAA2C,GAChE,OAAO,CAAC,gBAAgB,CAAC,CAgC3B;AAED,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY1G;AAwBD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIxE;AAmBD,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQjE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAOlE"}

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,57 @@
+export declare const STASH_SCHEMA_VERSION = 1;
+/** A stash longer than this is refused rather than stored. */
+export declare const MAX_STASH_ENTRY_BYTES = 1048576;
+export declare function stripControlCharacters(text: string): string;
+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 working directory this bank belongs to.
+     *
+     * The key alone cannot prove ownership: it is a flattened label that two
+     * directories could once have shared. The exact path is compared on every
+     * read, so a file that belongs to another directory is quarantined rather than
+     * read or deleted as this one's.
+     */
+    readonly cwd: 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(cwd: 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 working
+ * directory 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 directory'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":"AASA,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,UAAY,CAAA;AA2B9C,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,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,GAAG,EAAE,MAAM,CAAA;IACpB,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,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAExE;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"}