@aigne/afs-did-space 1.12.0-beta.5

package/dist/download-actions.cjs

@@ -0,0 +1,43 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let zod = require("zod");
+
+//#region src/download-actions.ts
+/**
+* download-actions.ts — arg schema + constants for the DID Space download-plane
+* `prepare-download` action (design §7.2 / §7.4 / §10). Mirrors
+* `upload-actions.ts`; the action HANDLER lives on `DIDSpaceProvider` (decorators
+* must register on the class), so this module holds only the validation shape +
+* resource bounds, unit-testable in isolation.
+*/
+/**
+* Download-plane action names (design §15 decision 1). Kept SEPARATE from
+* `UPLOAD_ACTIONS` — the catalogue iterates `[...UPLOAD_ACTIONS,
+* ...DOWNLOAD_ACTIONS]`; download actions are never folded into the upload list.
+*/
+const DOWNLOAD_ACTIONS = ["prepare-download"];
+/**
+* Max entries per `prepare-download` (design §7.4 / Finding 5). The afs-rpc body
+* cap (24MB) would otherwise admit ~350k cids → ~350k SigV4 signs — the CPU bomb
+* this plane exists to kill. 256 aligns with the client download batch and is a
+* HARD cap, unlike `PrepareUploadArgsSchema` which has `.min(1)` but NO `.max()`
+* (the gap this must not copy). Over-limit → whole request `AFS_VALIDATION_ERROR`.
+*/
+const DOWNLOAD_MAX_ENTRIES = 256;
+/**
+* Default presigned-GET TTL (design §8.3). A SHORT TTL bounds the bearer GET
+* exposure window. `PRESIGN_MAX_EXPIRES_SEC` (7d) is only the signer's
+* upper-bound *validation* value — NEVER the default; passing 7d would
+* needlessly widen the exposure window for no benefit.
+*/
+const DOWNLOAD_GRANT_TTL_SEC = 7200;
+const prepareDownloadEntry = zod.z.object({
+	cid: zod.z.string(),
+	path: zod.z.string().optional()
+});
+const PrepareDownloadArgsSchema = zod.z.object({ entries: zod.z.array(prepareDownloadEntry).min(1).max(DOWNLOAD_MAX_ENTRIES) });
+
+//#endregion
+exports.DOWNLOAD_ACTIONS = DOWNLOAD_ACTIONS;
+exports.DOWNLOAD_GRANT_TTL_SEC = DOWNLOAD_GRANT_TTL_SEC;
+exports.DOWNLOAD_MAX_ENTRIES = DOWNLOAD_MAX_ENTRIES;
+exports.PrepareDownloadArgsSchema = PrepareDownloadArgsSchema;

package/dist/download-actions.mjs

@@ -0,0 +1,40 @@
+import { z } from "zod";
+
+//#region src/download-actions.ts
+/**
+* download-actions.ts — arg schema + constants for the DID Space download-plane
+* `prepare-download` action (design §7.2 / §7.4 / §10). Mirrors
+* `upload-actions.ts`; the action HANDLER lives on `DIDSpaceProvider` (decorators
+* must register on the class), so this module holds only the validation shape +
+* resource bounds, unit-testable in isolation.
+*/
+/**
+* Download-plane action names (design §15 decision 1). Kept SEPARATE from
+* `UPLOAD_ACTIONS` — the catalogue iterates `[...UPLOAD_ACTIONS,
+* ...DOWNLOAD_ACTIONS]`; download actions are never folded into the upload list.
+*/
+const DOWNLOAD_ACTIONS = ["prepare-download"];
+/**
+* Max entries per `prepare-download` (design §7.4 / Finding 5). The afs-rpc body
+* cap (24MB) would otherwise admit ~350k cids → ~350k SigV4 signs — the CPU bomb
+* this plane exists to kill. 256 aligns with the client download batch and is a
+* HARD cap, unlike `PrepareUploadArgsSchema` which has `.min(1)` but NO `.max()`
+* (the gap this must not copy). Over-limit → whole request `AFS_VALIDATION_ERROR`.
+*/
+const DOWNLOAD_MAX_ENTRIES = 256;
+/**
+* Default presigned-GET TTL (design §8.3). A SHORT TTL bounds the bearer GET
+* exposure window. `PRESIGN_MAX_EXPIRES_SEC` (7d) is only the signer's
+* upper-bound *validation* value — NEVER the default; passing 7d would
+* needlessly widen the exposure window for no benefit.
+*/
+const DOWNLOAD_GRANT_TTL_SEC = 7200;
+const prepareDownloadEntry = z.object({
+	cid: z.string(),
+	path: z.string().optional()
+});
+const PrepareDownloadArgsSchema = z.object({ entries: z.array(prepareDownloadEntry).min(1).max(DOWNLOAD_MAX_ENTRIES) });
+
+//#endregion
+export { DOWNLOAD_ACTIONS, DOWNLOAD_GRANT_TTL_SEC, DOWNLOAD_MAX_ENTRIES, PrepareDownloadArgsSchema };
+//# sourceMappingURL=download-actions.mjs.map

package/dist/download-actions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-actions.mjs","names":[],"sources":["../src/download-actions.ts"],"sourcesContent":["/**\n * download-actions.ts — arg schema + constants for the DID Space download-plane\n * `prepare-download` action (design §7.2 / §7.4 / §10). Mirrors\n * `upload-actions.ts`; the action HANDLER lives on `DIDSpaceProvider` (decorators\n * must register on the class), so this module holds only the validation shape +\n * resource bounds, unit-testable in isolation.\n */\n\nimport { z } from \"zod\";\n\n/**\n * Download-plane action names (design §15 decision 1). Kept SEPARATE from\n * `UPLOAD_ACTIONS` — the catalogue iterates `[...UPLOAD_ACTIONS,\n * ...DOWNLOAD_ACTIONS]`; download actions are never folded into the upload list.\n */\nexport const DOWNLOAD_ACTIONS = [\"prepare-download\"] as const;\n\n/**\n * Max entries per `prepare-download` (design §7.4 / Finding 5). The afs-rpc body\n * cap (24MB) would otherwise admit ~350k cids → ~350k SigV4 signs — the CPU bomb\n * this plane exists to kill. 256 aligns with the client download batch and is a\n * HARD cap, unlike `PrepareUploadArgsSchema` which has `.min(1)` but NO `.max()`\n * (the gap this must not copy). Over-limit → whole request `AFS_VALIDATION_ERROR`.\n */\nexport const DOWNLOAD_MAX_ENTRIES = 256;\n\n/**\n * Default presigned-GET TTL (design §8.3). A SHORT TTL bounds the bearer GET\n * exposure window. `PRESIGN_MAX_EXPIRES_SEC` (7d) is only the signer's\n * upper-bound *validation* value — NEVER the default; passing 7d would\n * needlessly widen the exposure window for no benefit.\n */\nexport const DOWNLOAD_GRANT_TTL_SEC = 2 * 60 * 60; // 2h\n\nconst prepareDownloadEntry = z.object({\n  cid: z.string(),\n  // `path` is for error context / logging ONLY — it never participates in\n  // authorization (authorization looks at whether the cid is referenced, §7.2).\n  path: z.string().optional(),\n});\n\nexport const PrepareDownloadArgsSchema = z.object({\n  entries: z.array(prepareDownloadEntry).min(1).max(DOWNLOAD_MAX_ENTRIES),\n});\n\nexport type PrepareDownloadArgs = z.infer<typeof PrepareDownloadArgsSchema>;\n"],"mappings":";;;;;;;;;;;;;;;AAeA,MAAa,mBAAmB,CAAC,mBAAmB;;;;;;;;AASpD,MAAa,uBAAuB;;;;;;;AAQpC,MAAa,yBAAyB;AAEtC,MAAM,uBAAuB,EAAE,OAAO;CACpC,KAAK,EAAE,QAAQ;CAGf,MAAM,EAAE,QAAQ,CAAC,UAAU;CAC5B,CAAC;AAEF,MAAa,4BAA4B,EAAE,OAAO,EAChD,SAAS,EAAE,MAAM,qBAAqB,CAAC,IAAI,EAAE,CAAC,IAAI,qBAAqB,EACxE,CAAC"}

package/dist/fs-object-store.cjs

@@ -0,0 +1,153 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let node_path = require("node:path");
+let node_fs_promises = require("node:fs/promises");
+
+//#region src/fs-object-store.ts
+/**
+* FsObjectStore — a node-fs `ObjectStore` for the Node DID-Space backend.
+*
+* Stores content-addressed blobs at `{spaceDir}/objects/{cid}` (key verbatim —
+* `DIDSpaceProvider.objectKey()` passes `objects/{cid}`, no key translation).
+* Each user space has its own directory, so cross-user isolation is structural:
+* knowing a cid never reaches another user's blob (the cid resolves under THIS
+* space's dir only). Path-traversal keys (`..`, absolute escapes) resolve
+* outside the space dir and are rejected (read→null, write→throw, delete→noop).
+*
+* Lives in the did-space package (not r2) so the r2 package keeps zero node-fs
+* dependency (design §2.B).
+*/
+/** True if any `/`- or `\`-delimited segment of `key` is exactly `..`. */
+function hasDotDotSegment(key) {
+	return key.split(/[\\/]/).includes("..");
+}
+var FsObjectStore = class {
+	root;
+	constructor(spaceDir) {
+		this.root = (0, node_path.resolve)(spaceDir);
+	}
+	/**
+	* Resolve a store key to an absolute path, rejecting any key that escapes the
+	* space dir (path traversal). Returns null when the key is unsafe.
+	*/
+	safePath(key) {
+		if (typeof key !== "string" || key.length === 0) return null;
+		const full = (0, node_path.resolve)(this.root, key);
+		if (full !== this.root && !full.startsWith(this.root + node_path.sep)) return null;
+		return full;
+	}
+	async toBytes(value) {
+		if (typeof value === "string") return new TextEncoder().encode(value);
+		if (value instanceof ArrayBuffer) return new Uint8Array(value);
+		const reader = value.getReader();
+		const chunks = [];
+		let total = 0;
+		for (;;) {
+			const { done, value: chunk } = await reader.read();
+			if (done) break;
+			if (chunk) {
+				chunks.push(chunk);
+				total += chunk.length;
+			}
+		}
+		const merged = new Uint8Array(total);
+		let offset = 0;
+		for (const c of chunks) {
+			merged.set(c, offset);
+			offset += c.length;
+		}
+		return merged;
+	}
+	async get(key) {
+		const full = this.safePath(key);
+		if (!full) return null;
+		let bytes;
+		let uploaded;
+		try {
+			bytes = await (0, node_fs_promises.readFile)(full);
+			uploaded = (await (0, node_fs_promises.stat)(full)).mtime;
+		} catch {
+			return null;
+		}
+		const ab = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+		return {
+			key,
+			size: bytes.byteLength,
+			uploaded,
+			async text() {
+				return new TextDecoder().decode(bytes);
+			},
+			async arrayBuffer() {
+				return ab;
+			}
+		};
+	}
+	async put(key, value) {
+		const full = this.safePath(key);
+		if (!full) throw new Error(`FsObjectStore: unsafe key '${key}'`);
+		const bytes = await this.toBytes(value);
+		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(full), { recursive: true });
+		await (0, node_fs_promises.writeFile)(full, bytes);
+	}
+	async list(options) {
+		const prefix = options?.prefix ?? "";
+		const limit = options?.limit ?? 1e3;
+		const keys = [];
+		const walk = async (dir, rel) => {
+			let entries;
+			try {
+				entries = await (0, node_fs_promises.readdir)(dir, { withFileTypes: true });
+			} catch {
+				return;
+			}
+			for (const ent of entries) {
+				const childRel = rel ? `${rel}/${ent.name}` : ent.name;
+				if (ent.isDirectory()) await walk((0, node_path.join)(dir, ent.name), childRel);
+				else if (ent.isFile()) keys.push(childRel);
+			}
+		};
+		await walk(this.root, "");
+		let matched = keys.filter((k) => k.startsWith(prefix)).sort();
+		if (options?.cursor) {
+			const idx = matched.indexOf(options.cursor);
+			if (idx >= 0) matched = matched.slice(idx + 1);
+		}
+		const truncated = matched.length > limit;
+		const selected = truncated ? matched.slice(0, limit) : matched;
+		return {
+			objects: await Promise.all(selected.map(async (key) => {
+				const s = await (0, node_fs_promises.stat)((0, node_path.join)(this.root, key));
+				return {
+					key,
+					size: s.size,
+					uploaded: s.mtime
+				};
+			})),
+			truncated,
+			cursor: truncated ? selected[selected.length - 1] : void 0
+		};
+	}
+	async head(key) {
+		const full = this.safePath(key);
+		if (!full) return null;
+		try {
+			const s = await (0, node_fs_promises.stat)(full);
+			if (!s.isFile()) return null;
+			return {
+				key,
+				size: s.size,
+				uploaded: s.mtime
+			};
+		} catch {
+			return null;
+		}
+	}
+	async delete(key) {
+		if (hasDotDotSegment(key)) return;
+		const full = this.safePath(key);
+		if (!full) return;
+		await (0, node_fs_promises.rm)(full, { force: true });
+	}
+};
+
+//#endregion
+exports.FsObjectStore = FsObjectStore;

package/dist/fs-object-store.d.cts

@@ -0,0 +1,21 @@
+import { ObjectStore, ObjectStoreHeadResult, ObjectStoreListOptions, ObjectStoreListResult, ObjectStoreObject } from "./platform/r2/dist/types.cjs";
+
+//#region src/fs-object-store.d.ts
+declare class FsObjectStore implements ObjectStore {
+  private readonly root;
+  constructor(spaceDir: string);
+  /**
+   * Resolve a store key to an absolute path, rejecting any key that escapes the
+   * space dir (path traversal). Returns null when the key is unsafe.
+   */
+  private safePath;
+  private toBytes;
+  get(key: string): Promise<ObjectStoreObject | null>;
+  put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void>;
+  list(options?: ObjectStoreListOptions): Promise<ObjectStoreListResult>;
+  head(key: string): Promise<ObjectStoreHeadResult | null>;
+  delete(key: string): Promise<void>;
+}
+//#endregion
+export { FsObjectStore };
+//# sourceMappingURL=fs-object-store.d.cts.map

package/dist/fs-object-store.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-object-store.d.cts","names":[],"sources":["../src/fs-object-store.ts"],"mappings":";;;cA+Ba,aAAA,YAAyB,WAAA;EAAA,iBACnB,IAAA;cAEL,QAAA;EAHwB;;;;EAAA,QAW5B,QAAA;EAAA,QAOM,OAAA;EAwBR,GAAA,CAAI,GAAA,WAAc,OAAA,CAAQ,iBAAA;EA0B1B,GAAA,CAAI,GAAA,UAAa,KAAA,WAAgB,WAAA,GAAc,cAAA,GAAiB,OAAA;EAQhE,IAAA,CAAK,OAAA,GAAU,sBAAA,GAAyB,OAAA,CAAQ,qBAAA;EA6ChD,IAAA,CAAK,GAAA,WAAc,OAAA,CAAQ,qBAAA;EAY3B,MAAA,CAAO,GAAA,WAAc,OAAA;AAAA"}

package/dist/fs-object-store.d.mts

@@ -0,0 +1,22 @@
+import { ObjectStore, ObjectStoreHeadResult, ObjectStoreListOptions, ObjectStoreListResult, ObjectStoreObject } from "./providers/platform/r2/dist/types.mjs";
+import "./providers/platform/r2/dist/index.mjs";
+
+//#region src/fs-object-store.d.ts
+declare class FsObjectStore implements ObjectStore {
+  private readonly root;
+  constructor(spaceDir: string);
+  /**
+   * Resolve a store key to an absolute path, rejecting any key that escapes the
+   * space dir (path traversal). Returns null when the key is unsafe.
+   */
+  private safePath;
+  private toBytes;
+  get(key: string): Promise<ObjectStoreObject | null>;
+  put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void>;
+  list(options?: ObjectStoreListOptions): Promise<ObjectStoreListResult>;
+  head(key: string): Promise<ObjectStoreHeadResult | null>;
+  delete(key: string): Promise<void>;
+}
+//#endregion
+export { FsObjectStore };
+//# sourceMappingURL=fs-object-store.d.mts.map

package/dist/fs-object-store.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-object-store.d.mts","names":[],"sources":["../src/fs-object-store.ts"],"mappings":";;;;cA+Ba,aAAA,YAAyB,WAAA;EAAA,iBACnB,IAAA;cAEL,QAAA;EAkIe;;;;EAAA,QA1HnB,QAAA;EAAA,QAOM,OAAA;EAwBR,GAAA,CAAI,GAAA,WAAc,OAAA,CAAQ,iBAAA;EA0B1B,GAAA,CAAI,GAAA,UAAa,KAAA,WAAgB,WAAA,GAAc,cAAA,GAAiB,OAAA;EAQhE,IAAA,CAAK,OAAA,GAAU,sBAAA,GAAyB,OAAA,CAAQ,qBAAA;EA6ChD,IAAA,CAAK,GAAA,WAAc,OAAA,CAAQ,qBAAA;EAY3B,MAAA,CAAO,GAAA,WAAc,OAAA;AAAA"}

package/dist/fs-object-store.mjs

@@ -0,0 +1,153 @@
+import { dirname, join, resolve, sep } from "node:path";
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+
+//#region src/fs-object-store.ts
+/**
+* FsObjectStore — a node-fs `ObjectStore` for the Node DID-Space backend.
+*
+* Stores content-addressed blobs at `{spaceDir}/objects/{cid}` (key verbatim —
+* `DIDSpaceProvider.objectKey()` passes `objects/{cid}`, no key translation).
+* Each user space has its own directory, so cross-user isolation is structural:
+* knowing a cid never reaches another user's blob (the cid resolves under THIS
+* space's dir only). Path-traversal keys (`..`, absolute escapes) resolve
+* outside the space dir and are rejected (read→null, write→throw, delete→noop).
+*
+* Lives in the did-space package (not r2) so the r2 package keeps zero node-fs
+* dependency (design §2.B).
+*/
+/** True if any `/`- or `\`-delimited segment of `key` is exactly `..`. */
+function hasDotDotSegment(key) {
+	return key.split(/[\\/]/).includes("..");
+}
+var FsObjectStore = class {
+	root;
+	constructor(spaceDir) {
+		this.root = resolve(spaceDir);
+	}
+	/**
+	* Resolve a store key to an absolute path, rejecting any key that escapes the
+	* space dir (path traversal). Returns null when the key is unsafe.
+	*/
+	safePath(key) {
+		if (typeof key !== "string" || key.length === 0) return null;
+		const full = resolve(this.root, key);
+		if (full !== this.root && !full.startsWith(this.root + sep)) return null;
+		return full;
+	}
+	async toBytes(value) {
+		if (typeof value === "string") return new TextEncoder().encode(value);
+		if (value instanceof ArrayBuffer) return new Uint8Array(value);
+		const reader = value.getReader();
+		const chunks = [];
+		let total = 0;
+		for (;;) {
+			const { done, value: chunk } = await reader.read();
+			if (done) break;
+			if (chunk) {
+				chunks.push(chunk);
+				total += chunk.length;
+			}
+		}
+		const merged = new Uint8Array(total);
+		let offset = 0;
+		for (const c of chunks) {
+			merged.set(c, offset);
+			offset += c.length;
+		}
+		return merged;
+	}
+	async get(key) {
+		const full = this.safePath(key);
+		if (!full) return null;
+		let bytes;
+		let uploaded;
+		try {
+			bytes = await readFile(full);
+			uploaded = (await stat(full)).mtime;
+		} catch {
+			return null;
+		}
+		const ab = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+		return {
+			key,
+			size: bytes.byteLength,
+			uploaded,
+			async text() {
+				return new TextDecoder().decode(bytes);
+			},
+			async arrayBuffer() {
+				return ab;
+			}
+		};
+	}
+	async put(key, value) {
+		const full = this.safePath(key);
+		if (!full) throw new Error(`FsObjectStore: unsafe key '${key}'`);
+		const bytes = await this.toBytes(value);
+		await mkdir(dirname(full), { recursive: true });
+		await writeFile(full, bytes);
+	}
+	async list(options) {
+		const prefix = options?.prefix ?? "";
+		const limit = options?.limit ?? 1e3;
+		const keys = [];
+		const walk = async (dir, rel) => {
+			let entries;
+			try {
+				entries = await readdir(dir, { withFileTypes: true });
+			} catch {
+				return;
+			}
+			for (const ent of entries) {
+				const childRel = rel ? `${rel}/${ent.name}` : ent.name;
+				if (ent.isDirectory()) await walk(join(dir, ent.name), childRel);
+				else if (ent.isFile()) keys.push(childRel);
+			}
+		};
+		await walk(this.root, "");
+		let matched = keys.filter((k) => k.startsWith(prefix)).sort();
+		if (options?.cursor) {
+			const idx = matched.indexOf(options.cursor);
+			if (idx >= 0) matched = matched.slice(idx + 1);
+		}
+		const truncated = matched.length > limit;
+		const selected = truncated ? matched.slice(0, limit) : matched;
+		return {
+			objects: await Promise.all(selected.map(async (key) => {
+				const s = await stat(join(this.root, key));
+				return {
+					key,
+					size: s.size,
+					uploaded: s.mtime
+				};
+			})),
+			truncated,
+			cursor: truncated ? selected[selected.length - 1] : void 0
+		};
+	}
+	async head(key) {
+		const full = this.safePath(key);
+		if (!full) return null;
+		try {
+			const s = await stat(full);
+			if (!s.isFile()) return null;
+			return {
+				key,
+				size: s.size,
+				uploaded: s.mtime
+			};
+		} catch {
+			return null;
+		}
+	}
+	async delete(key) {
+		if (hasDotDotSegment(key)) return;
+		const full = this.safePath(key);
+		if (!full) return;
+		await rm(full, { force: true });
+	}
+};
+
+//#endregion
+export { FsObjectStore };
+//# sourceMappingURL=fs-object-store.mjs.map

package/dist/fs-object-store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-object-store.mjs","names":[],"sources":["../src/fs-object-store.ts"],"sourcesContent":["/**\n * FsObjectStore — a node-fs `ObjectStore` for the Node DID-Space backend.\n *\n * Stores content-addressed blobs at `{spaceDir}/objects/{cid}` (key verbatim —\n * `DIDSpaceProvider.objectKey()` passes `objects/{cid}`, no key translation).\n * Each user space has its own directory, so cross-user isolation is structural:\n * knowing a cid never reaches another user's blob (the cid resolves under THIS\n * space's dir only). Path-traversal keys (`..`, absolute escapes) resolve\n * outside the space dir and are rejected (read→null, write→throw, delete→noop).\n *\n * Lives in the did-space package (not r2) so the r2 package keeps zero node-fs\n * dependency (design §2.B).\n */\n\n// biome-ignore lint/style/noRestrictedImports: provider internal — FsObjectStore is the Node-only storage primitive (CLAUDE.md provider-internal exception)\nimport { mkdir, readdir, readFile, rm, stat, writeFile } from \"node:fs/promises\";\n// biome-ignore lint/style/noRestrictedImports: provider internal — physical object-store path layout\nimport { dirname, join, resolve, sep } from \"node:path\";\nimport type {\n  ObjectStore,\n  ObjectStoreHeadResult,\n  ObjectStoreListOptions,\n  ObjectStoreListResult,\n  ObjectStoreObject,\n} from \"@aigne/afs-r2\";\n\n/** True if any `/`- or `\\`-delimited segment of `key` is exactly `..`. */\nfunction hasDotDotSegment(key: string): boolean {\n  return key.split(/[\\\\/]/).includes(\"..\");\n}\n\nexport class FsObjectStore implements ObjectStore {\n  private readonly root: string;\n\n  constructor(spaceDir: string) {\n    this.root = resolve(spaceDir);\n  }\n\n  /**\n   * Resolve a store key to an absolute path, rejecting any key that escapes the\n   * space dir (path traversal). Returns null when the key is unsafe.\n   */\n  private safePath(key: string): string | null {\n    if (typeof key !== \"string\" || key.length === 0) return null;\n    const full = resolve(this.root, key);\n    if (full !== this.root && !full.startsWith(this.root + sep)) return null;\n    return full;\n  }\n\n  private async toBytes(value: string | ArrayBuffer | ReadableStream): Promise<Uint8Array> {\n    if (typeof value === \"string\") return new TextEncoder().encode(value);\n    if (value instanceof ArrayBuffer) return new Uint8Array(value);\n    // ReadableStream\n    const reader = (value as ReadableStream<Uint8Array>).getReader();\n    const chunks: Uint8Array[] = [];\n    let total = 0;\n    for (;;) {\n      const { done, value: chunk } = await reader.read();\n      if (done) break;\n      if (chunk) {\n        chunks.push(chunk);\n        total += chunk.length;\n      }\n    }\n    const merged = new Uint8Array(total);\n    let offset = 0;\n    for (const c of chunks) {\n      merged.set(c, offset);\n      offset += c.length;\n    }\n    return merged;\n  }\n\n  async get(key: string): Promise<ObjectStoreObject | null> {\n    const full = this.safePath(key);\n    if (!full) return null;\n    let bytes: Buffer;\n    let uploaded: Date;\n    try {\n      bytes = await readFile(full);\n      uploaded = (await stat(full)).mtime;\n    } catch {\n      return null;\n    }\n    // Copy into a standalone ArrayBuffer slice (Buffer may be a pooled view).\n    const ab = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);\n    return {\n      key,\n      size: bytes.byteLength,\n      uploaded,\n      async text() {\n        return new TextDecoder().decode(bytes);\n      },\n      async arrayBuffer() {\n        return ab as ArrayBuffer;\n      },\n    };\n  }\n\n  async put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void> {\n    const full = this.safePath(key);\n    if (!full) throw new Error(`FsObjectStore: unsafe key '${key}'`);\n    const bytes = await this.toBytes(value);\n    await mkdir(dirname(full), { recursive: true });\n    await writeFile(full, bytes);\n  }\n\n  async list(options?: ObjectStoreListOptions): Promise<ObjectStoreListResult> {\n    const prefix = options?.prefix ?? \"\";\n    const limit = options?.limit ?? 1000;\n\n    // Walk every file under the space dir, key = path relative to root (POSIX-style).\n    const keys: string[] = [];\n    const walk = async (dir: string, rel: string): Promise<void> => {\n      let entries: import(\"node:fs\").Dirent[];\n      try {\n        entries = await readdir(dir, { withFileTypes: true });\n      } catch {\n        return;\n      }\n      for (const ent of entries) {\n        const childRel = rel ? `${rel}/${ent.name}` : ent.name;\n        if (ent.isDirectory()) {\n          await walk(join(dir, ent.name), childRel);\n        } else if (ent.isFile()) {\n          keys.push(childRel);\n        }\n      }\n    };\n    await walk(this.root, \"\");\n\n    let matched = keys.filter((k) => k.startsWith(prefix)).sort();\n    if (options?.cursor) {\n      const idx = matched.indexOf(options.cursor);\n      if (idx >= 0) matched = matched.slice(idx + 1);\n    }\n    const truncated = matched.length > limit;\n    const selected = truncated ? matched.slice(0, limit) : matched;\n\n    const objects = await Promise.all(\n      selected.map(async (key) => {\n        const s = await stat(join(this.root, key));\n        return { key, size: s.size, uploaded: s.mtime };\n      }),\n    );\n    return {\n      objects,\n      truncated,\n      cursor: truncated ? selected[selected.length - 1] : undefined,\n    };\n  }\n\n  async head(key: string): Promise<ObjectStoreHeadResult | null> {\n    const full = this.safePath(key);\n    if (!full) return null;\n    try {\n      const s = await stat(full);\n      if (!s.isFile()) return null;\n      return { key, size: s.size, uploaded: s.mtime };\n    } catch {\n      return null;\n    }\n  }\n\n  async delete(key: string): Promise<void> {\n    // Defense-in-depth layer 3 (design §4.5): reject any `..` path segment.\n    // `safePath` only blocks keys that escape the space root, but a\n    // root-INTERNAL traversal like `objects/../_metadata.db` resolves to\n    // `{root}/_metadata.db` — still inside root, so safePath would allow it and\n    // delete would destroy the index. A real cid never contains `..`, so this\n    // only ever fires on a poisoned GC-queue row.\n    if (hasDotDotSegment(key)) return;\n    const full = this.safePath(key);\n    if (!full) return;\n    await rm(full, { force: true });\n  }\n}\n"],"mappings":"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"}

package/dist/gc-queue.d.cts

@@ -0,0 +1,43 @@
+//#region src/gc-queue.d.ts
+/**
+ * GcQueue — pure-storage interface for the deferred object-GC queue (design §4.4).
+ *
+ * The queue holds CIDs whose backing object MIGHT be reclaimable, with the
+ * time they were enqueued. It is **storage only** — it has NO reference/liveness
+ * method. Liveness is decided separately by `referencedAnywhere` (see
+ * `reference-check.ts`) and applied by `runGc`. This split keeps the sweeper
+ * storage-agnostic and stops the queue from re-introducing the legacy three-way
+ * `isReferenced` (which would pin every overwritten cid forever, §0.2).
+ *
+ * Schema (unchanged across runtimes):
+ *   gc_queue (cid TEXT PRIMARY KEY, queued_at INTEGER)
+ *
+ * Impls: `D1GCQueue` (Cloudflare D1), `SqliteGcQueue` (Node `_metadata.db`),
+ * `MemoryGcQueue` (testing). All three pass the shared conformance suite.
+ */
+interface GcQueue {
+  /** Create the `gc_queue` table if absent. Idempotent. */
+  ensureTable(): Promise<void>;
+  /** Enqueue CIDs for deferred GC. Idempotent — duplicates are ignored. Empty array is a no-op. */
+  enqueue(cids: string[]): Promise<void>;
+  /**
+   * Fetch candidate CIDs whose grace period has expired (enqueued more than
+   * `graceMs` ago). `runGc` always passes `graceMs` explicitly (canonical 7d) —
+   * an impl's own default is never relied upon (design §4.4).
+   */
+  fetchCandidates(limit?: number, graceMs?: number): Promise<Array<{
+    cid: string;
+  }>>;
+  /** Remove a CID from the queue (after its object was deleted, or it was kept). */
+  remove(cid: string): Promise<void>;
+  /**
+   * Remove MANY CIDs in one backend round trip (afs-rpc-batch P3 write-
+   * dequeue: a batch write re-references its cids — rescuing them from a
+   * pending GC must not cost one subrequest per cid on CF). Optional:
+   * callers fall back to per-cid `remove`.
+   */
+  removeMany?(cids: string[]): Promise<void>;
+}
+//#endregion
+export { GcQueue };
+//# sourceMappingURL=gc-queue.d.cts.map

package/dist/gc-queue.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gc-queue.d.cts","names":[],"sources":["../src/gc-queue.ts"],"mappings":";;AAgBA;;;;;;;;;;;;;;;UAAiB,OAAA;EAYf;EAVA,WAAA,IAAe,OAAA;EAUiB;EAPhC,OAAA,CAAQ,IAAA,aAAiB,OAAA;EAOkC;;;;;EAA3D,eAAA,CAAgB,KAAA,WAAgB,OAAA,YAAmB,OAAA,CAAQ,KAAA;IAAQ,GAAA;EAAA;EAW/B;EARpC,MAAA,CAAO,GAAA,WAAc,OAAA;;;;;;;EAQrB,UAAA,EAAY,IAAA,aAAiB,OAAA;AAAA"}

package/dist/gc-queue.d.mts

@@ -0,0 +1,43 @@
+//#region src/gc-queue.d.ts
+/**
+ * GcQueue — pure-storage interface for the deferred object-GC queue (design §4.4).
+ *
+ * The queue holds CIDs whose backing object MIGHT be reclaimable, with the
+ * time they were enqueued. It is **storage only** — it has NO reference/liveness
+ * method. Liveness is decided separately by `referencedAnywhere` (see
+ * `reference-check.ts`) and applied by `runGc`. This split keeps the sweeper
+ * storage-agnostic and stops the queue from re-introducing the legacy three-way
+ * `isReferenced` (which would pin every overwritten cid forever, §0.2).
+ *
+ * Schema (unchanged across runtimes):
+ *   gc_queue (cid TEXT PRIMARY KEY, queued_at INTEGER)
+ *
+ * Impls: `D1GCQueue` (Cloudflare D1), `SqliteGcQueue` (Node `_metadata.db`),
+ * `MemoryGcQueue` (testing). All three pass the shared conformance suite.
+ */
+interface GcQueue {
+  /** Create the `gc_queue` table if absent. Idempotent. */
+  ensureTable(): Promise<void>;
+  /** Enqueue CIDs for deferred GC. Idempotent — duplicates are ignored. Empty array is a no-op. */
+  enqueue(cids: string[]): Promise<void>;
+  /**
+   * Fetch candidate CIDs whose grace period has expired (enqueued more than
+   * `graceMs` ago). `runGc` always passes `graceMs` explicitly (canonical 7d) —
+   * an impl's own default is never relied upon (design §4.4).
+   */
+  fetchCandidates(limit?: number, graceMs?: number): Promise<Array<{
+    cid: string;
+  }>>;
+  /** Remove a CID from the queue (after its object was deleted, or it was kept). */
+  remove(cid: string): Promise<void>;
+  /**
+   * Remove MANY CIDs in one backend round trip (afs-rpc-batch P3 write-
+   * dequeue: a batch write re-references its cids — rescuing them from a
+   * pending GC must not cost one subrequest per cid on CF). Optional:
+   * callers fall back to per-cid `remove`.
+   */
+  removeMany?(cids: string[]): Promise<void>;
+}
+//#endregion
+export { GcQueue };
+//# sourceMappingURL=gc-queue.d.mts.map

package/dist/gc-queue.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gc-queue.d.mts","names":[],"sources":["../src/gc-queue.ts"],"mappings":";;AAgBA;;;;;;;;;;;;;;;UAAiB,OAAA;EAYf;EAVA,WAAA,IAAe,OAAA;EAUiB;EAPhC,OAAA,CAAQ,IAAA,aAAiB,OAAA;EAOkC;;;;;EAA3D,eAAA,CAAgB,KAAA,WAAgB,OAAA,YAAmB,OAAA,CAAQ,KAAA;IAAQ,GAAA;EAAA;EAW/B;EARpC,MAAA,CAAO,GAAA,WAAc,OAAA;;;;;;;EAQrB,UAAA,EAAY,IAAA,aAAiB,OAAA;AAAA"}