@atomicmemory/core 1.0.0

package/dist/storage/filecoin-cid-validation.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @file Shared Filecoin / IPFS CID structural-SHAPE gates for the
+ * public-projection seam.
+ *
+ * These are NOT codec-aware validators. They are
+ * regex-on-multibase-prefix gates whose only job is to silently
+ * drop adversarial / legacy / manually-planted JSONB column
+ * values before they cross the public projection wire boundary.
+ * True PieceCIDv2 validation — CIDv1, raw codec (0x55),
+ * multihash code 0x1011 — lives at the provider boundary in
+ * `providers/filecoin/piece-cid.ts`, which wraps the live Synapse
+ * SDK parser (`@filoz/synapse-core/piece.asPieceCID`). Write-path
+ * inputs that fail the SDK parser are rejected before they ever
+ * reach `storage_artifacts.uri` or
+ * `raw_storage_metadata.filecoin.piece_cid`, so by induction any
+ * value the public projector sees in a recent row already
+ * round-trips through the SDK.
+ *
+ * Why a separate shape gate exists:
+ *
+ *   - The public projector (`filecoin-public-metadata.ts`) is on
+ *     the EAGER import path. Importing `@filoz/synapse-core` from
+ *     it would defeat the Phase 2 lazy-loading invariant that
+ *     keeps the Synapse SDK out of non-Filecoin-provider
+ *     startups.
+ *
+ *   - Legacy rows from before Phase 3, direct DB writes by
+ *     operators, and adversarial test planting can still place
+ *     non-parseable strings in `raw_storage_metadata`. The shape
+ *     gate is a belt-and-suspenders silent drop so such values
+ *     never make it onto the wire.
+ *
+ * Predicates:
+ *
+ *   - `isPieceCidShape(value)` — accepts strings whose multibase
+ *     prefix is a known PieceCID encoding (legacy `baga…` or
+ *     modern PieceCIDv2 `bafkzci…`) followed by enough base32-lower
+ *     characters to plausibly carry a digest. Does NOT decode
+ *     the bytes or verify the codec/multihash.
+ *
+ *   - `isIpfsCidShape(value)` — broader CIDv1 base32-lower shape;
+ *     reserved for the Phase 4 `ipfs_cid` / CAR-root field. No
+ *     production caller emits the field yet.
+ *
+ * The functions are named `isPieceCid` / `isIpfsCid` (historical
+ * names retained to avoid churn at call sites) but the file
+ * header is the source of truth on what they actually do —
+ * "structural shape only, no codec validation."
+ *
+ * Layering rule: this module sits at the shared-storage layer
+ * and has ZERO dependencies on `providers/filecoin/*` or any
+ * Filecoin vendor package. The boundary test
+ * (`import-boundary-helpers.ts:SHARED_STORAGE_ALLOWLIST`)
+ * explicitly permits provider files to import it via
+ * `../../filecoin-cid-validation.js` — that allowance now exists
+ * only for the public projector's `import { isPieceCid }` (the
+ * provider boundary uses the SDK parser instead).
+ *
+ * Errors: this file does NOT throw — predicates return booleans.
+ */
+/**
+ * Returns `true` if `value` has the surface shape of a PieceCID
+ * string (legacy `baga…` or modern PieceCIDv2 `bafkzci…`
+ * multibase prefix + sufficient base32-lower length). Does NOT
+ * decode the multihash bytes, verify the codec, or confirm the
+ * value parses through the Synapse SDK — see this file's
+ * header for why the codec-aware check lives at the provider
+ * boundary instead.
+ *
+ * Used at the public-projection seam (`filecoin-public-metadata`)
+ * to silently drop adversarial / legacy / manually-planted
+ * column values before the wire.
+ */
+export declare function isPieceCid(value: unknown): value is string;
+/**
+ * Returns `true` if `value` has the surface shape of a CIDv1
+ * base32-lower string (any multicodec). Reserved for the
+ * `ipfs_cid` / CAR-root identity Phase 4 will plumb through; no
+ * production caller emits the field yet. Same shape-only
+ * semantics as {@link isPieceCid}.
+ */
+export declare function isIpfsCid(value: unknown): value is string;

package/dist/storage/filecoin-cid-validation.js

@@ -0,0 +1,122 @@
+/**
+ * @file Shared Filecoin / IPFS CID structural-SHAPE gates for the
+ * public-projection seam.
+ *
+ * These are NOT codec-aware validators. They are
+ * regex-on-multibase-prefix gates whose only job is to silently
+ * drop adversarial / legacy / manually-planted JSONB column
+ * values before they cross the public projection wire boundary.
+ * True PieceCIDv2 validation — CIDv1, raw codec (0x55),
+ * multihash code 0x1011 — lives at the provider boundary in
+ * `providers/filecoin/piece-cid.ts`, which wraps the live Synapse
+ * SDK parser (`@filoz/synapse-core/piece.asPieceCID`). Write-path
+ * inputs that fail the SDK parser are rejected before they ever
+ * reach `storage_artifacts.uri` or
+ * `raw_storage_metadata.filecoin.piece_cid`, so by induction any
+ * value the public projector sees in a recent row already
+ * round-trips through the SDK.
+ *
+ * Why a separate shape gate exists:
+ *
+ *   - The public projector (`filecoin-public-metadata.ts`) is on
+ *     the EAGER import path. Importing `@filoz/synapse-core` from
+ *     it would defeat the Phase 2 lazy-loading invariant that
+ *     keeps the Synapse SDK out of non-Filecoin-provider
+ *     startups.
+ *
+ *   - Legacy rows from before Phase 3, direct DB writes by
+ *     operators, and adversarial test planting can still place
+ *     non-parseable strings in `raw_storage_metadata`. The shape
+ *     gate is a belt-and-suspenders silent drop so such values
+ *     never make it onto the wire.
+ *
+ * Predicates:
+ *
+ *   - `isPieceCidShape(value)` — accepts strings whose multibase
+ *     prefix is a known PieceCID encoding (legacy `baga…` or
+ *     modern PieceCIDv2 `bafkzci…`) followed by enough base32-lower
+ *     characters to plausibly carry a digest. Does NOT decode
+ *     the bytes or verify the codec/multihash.
+ *
+ *   - `isIpfsCidShape(value)` — broader CIDv1 base32-lower shape;
+ *     reserved for the Phase 4 `ipfs_cid` / CAR-root field. No
+ *     production caller emits the field yet.
+ *
+ * The functions are named `isPieceCid` / `isIpfsCid` (historical
+ * names retained to avoid churn at call sites) but the file
+ * header is the source of truth on what they actually do —
+ * "structural shape only, no codec validation."
+ *
+ * Layering rule: this module sits at the shared-storage layer
+ * and has ZERO dependencies on `providers/filecoin/*` or any
+ * Filecoin vendor package. The boundary test
+ * (`import-boundary-helpers.ts:SHARED_STORAGE_ALLOWLIST`)
+ * explicitly permits provider files to import it via
+ * `../../filecoin-cid-validation.js` — that allowance now exists
+ * only for the public projector's `import { isPieceCid }` (the
+ * provider boundary uses the SDK parser instead).
+ *
+ * Errors: this file does NOT throw — predicates return booleans.
+ */
+/**
+ * PieceCID structural shape: CIDv1 base32-lower. Two canonical
+ * multicodec encodings are accepted:
+ *
+ *   - **Legacy `baga…`** — multicodec `fil-commitment-unsealed`
+ *     (0xf101) + sha2-256. Historical Filecoin storage identity;
+ *     ~59–62 chars overall.
+ *
+ *   - **Modern `bafkzci…`** — CIDv1 raw codec (0x55) + multihash
+ *     code 0x1011 (`fr32-sha2-256-trunc254-padded-binary-tree`,
+ *     from `@web3-storage/data-segment`). This is the PieceCIDv2
+ *     shape the live Synapse SDK emits today
+ *     (`@filoz/synapse-core` `isPieceCID`). ~63–66 chars overall.
+ *
+ * The regex requires the `(baga|bafkzci)` prefix and at least 50
+ * additional base32-lower characters, rejecting obvious sentinels
+ * (`baga-test`, `bafkzci-x`) while leaving room for digest-length
+ * variants within either codec family. Codec semantics (CID
+ * version, codec byte, multihash code) are NOT decoded here — the
+ * SDK enforces them on its side. This validator's job is to gate
+ * adversarial JSONB / placeholders / wire-format garbage before
+ * the value reaches the URI parser, the sidecar persister, or the
+ * public projector.
+ *
+ * Charset is base32 lowercase per multibase `b`: `[a-z2-7]`.
+ */
+const PIECE_CID_RE = /^(baga|bafkzci)[a-z2-7]{50,}$/;
+/**
+ * Generic CIDv1 base32-lower shape. Multibase prefix `b` followed
+ * by 55+ base32-lower characters (typical CIDv1 base32 length is
+ * 59 chars; floor at 55 to accommodate variant multihashes).
+ * Accepts both IPFS-style `bafy...` / `bafk...` and PieceCID-style
+ * `baga...`. Phase 4 / filecoin-pin uses this for the `ipfs_cid`
+ * / CAR-root metadata field.
+ */
+const IPFS_CID_RE = /^b[a-z2-7]{55,}$/;
+/**
+ * Returns `true` if `value` has the surface shape of a PieceCID
+ * string (legacy `baga…` or modern PieceCIDv2 `bafkzci…`
+ * multibase prefix + sufficient base32-lower length). Does NOT
+ * decode the multihash bytes, verify the codec, or confirm the
+ * value parses through the Synapse SDK — see this file's
+ * header for why the codec-aware check lives at the provider
+ * boundary instead.
+ *
+ * Used at the public-projection seam (`filecoin-public-metadata`)
+ * to silently drop adversarial / legacy / manually-planted
+ * column values before the wire.
+ */
+export function isPieceCid(value) {
+    return typeof value === 'string' && PIECE_CID_RE.test(value);
+}
+/**
+ * Returns `true` if `value` has the surface shape of a CIDv1
+ * base32-lower string (any multicodec). Reserved for the
+ * `ipfs_cid` / CAR-root identity Phase 4 will plumb through; no
+ * production caller emits the field yet. Same shape-only
+ * semantics as {@link isPieceCid}.
+ */
+export function isIpfsCid(value) {
+    return typeof value === 'string' && IPFS_CID_RE.test(value);
+}

package/dist/storage/filecoin-public-metadata.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @file Provider-neutral public projection of the Filecoin
+ * `raw_documents.raw_storage_metadata.filecoin` sidecar.
+ *
+ * Routes, document services, and SDK packages MUST import the
+ * public projector from this module — NOT from
+ * `src/storage/providers/filecoin/`. The provider directory is the
+ * implementation seam (upload allowlist, denylist, provider-client
+ * wiring); leaking it through route imports would couple the route
+ * layer to the eventual provider package boundary.
+ *
+ * Mirror rule: the upload-side allowlist + denylist in
+ * `providers/filecoin/metadata.ts` is the SOURCE of truth for what
+ * fields the upload implementation may stamp on outgoing uploads;
+ * this module is the SOURCE of truth for what survives onto the
+ * wire when reading those rows back. The two contracts overlap by
+ * design (CIDs + copy state) but live in different files so the
+ * route layer never has to learn the provider package shape.
+ *
+ * Synapse public shape:
+ *
+ *   {
+ *     ipfs_cid?: string,
+ *     piece_cid?: string,
+ *     copy_count?: number,
+ *     provider_ids?: string[],
+ *     copy_statuses?: string[],
+ *   }
+ *
+ * Phase 4 renamed the legacy ambiguous `cid` slot to `ipfs_cid`
+ * — see harvest plan §Phase 4. The slot is optional and only
+ * populated by drivers that emit an IPFS / CAR-root identity
+ * alongside the PieceCID (today: none; planned: filecoin-pin).
+ * The canonical storage URI stays `filecoin://piece/<pieceCid>`
+ * regardless of whether `ipfs_cid` is present — IPFS CID is a
+ * resolution-hint field, not a row-identity field.
+ *
+ * The internal `copies: [{ provider_id, status }]` shape is
+ * flattened by `projectFilecoinPublicMetadata`; legacy onramp keys
+ * (`onramp`, `gateway_url`, `deal_ids`, `onramp_status`, etc.) are
+ * NOT emitted by this projector.
+ */
+export interface FilecoinPublicMetadata {
+    readonly ipfs_cid?: string;
+    readonly piece_cid?: string;
+    readonly copy_count?: number;
+    readonly provider_ids?: ReadonlyArray<string>;
+    readonly copy_statuses?: ReadonlyArray<string>;
+}
+/**
+ * Reduce the internal Filecoin sidecar to a wire-safe public
+ * projection. Returns an empty object when the input is malformed
+ * or the projection has no recognised content; callers can drop
+ * the empty object from the wire response.
+ *
+ * Phase 3 hardening: `piece_cid` is gated by the shared codec-
+ * blind shape predicate (`isPieceCid` in
+ * `./filecoin-cid-validation.ts`) before crossing the public
+ * boundary — adversarial / legacy / manually-planted JSONB values
+ * that don't match the structural shape are silently dropped
+ * rather than echoed onto the wire. The shape gate is a belt-and-
+ * suspenders defence; on the WRITE path the provider boundary
+ * already rejected anything that doesn't round-trip through the
+ * Synapse SDK parser, so for rows written via the normal pipeline
+ * this gate is a no-op. The `ipfs_cid` slot uses the broader
+ * CIDv1 base32 shape predicate (`isIpfsCid`) — real codec-aware
+ * parsing happens on the WRITE path inside
+ * `providers/filecoin/ipfs-cid.ts` via `multiformats/cid`. The
+ * projector intentionally stays eager-import-safe and vendor-light
+ * here, defeating any attempt to leak adversarial JSONB onto the
+ * wire even on legacy rows the SDK parser never gated.
+ */
+export declare function projectFilecoinPublicMetadata(internal: unknown): FilecoinPublicMetadata;

package/dist/storage/filecoin-public-metadata.js

@@ -0,0 +1,110 @@
+/**
+ * @file Provider-neutral public projection of the Filecoin
+ * `raw_documents.raw_storage_metadata.filecoin` sidecar.
+ *
+ * Routes, document services, and SDK packages MUST import the
+ * public projector from this module — NOT from
+ * `src/storage/providers/filecoin/`. The provider directory is the
+ * implementation seam (upload allowlist, denylist, provider-client
+ * wiring); leaking it through route imports would couple the route
+ * layer to the eventual provider package boundary.
+ *
+ * Mirror rule: the upload-side allowlist + denylist in
+ * `providers/filecoin/metadata.ts` is the SOURCE of truth for what
+ * fields the upload implementation may stamp on outgoing uploads;
+ * this module is the SOURCE of truth for what survives onto the
+ * wire when reading those rows back. The two contracts overlap by
+ * design (CIDs + copy state) but live in different files so the
+ * route layer never has to learn the provider package shape.
+ *
+ * Synapse public shape:
+ *
+ *   {
+ *     ipfs_cid?: string,
+ *     piece_cid?: string,
+ *     copy_count?: number,
+ *     provider_ids?: string[],
+ *     copy_statuses?: string[],
+ *   }
+ *
+ * Phase 4 renamed the legacy ambiguous `cid` slot to `ipfs_cid`
+ * — see harvest plan §Phase 4. The slot is optional and only
+ * populated by drivers that emit an IPFS / CAR-root identity
+ * alongside the PieceCID (today: none; planned: filecoin-pin).
+ * The canonical storage URI stays `filecoin://piece/<pieceCid>`
+ * regardless of whether `ipfs_cid` is present — IPFS CID is a
+ * resolution-hint field, not a row-identity field.
+ *
+ * The internal `copies: [{ provider_id, status }]` shape is
+ * flattened by `projectFilecoinPublicMetadata`; legacy onramp keys
+ * (`onramp`, `gateway_url`, `deal_ids`, `onramp_status`, etc.) are
+ * NOT emitted by this projector.
+ */
+import { isIpfsCid, isPieceCid } from './filecoin-cid-validation.js';
+/**
+ * Reduce the internal Filecoin sidecar to a wire-safe public
+ * projection. Returns an empty object when the input is malformed
+ * or the projection has no recognised content; callers can drop
+ * the empty object from the wire response.
+ *
+ * Phase 3 hardening: `piece_cid` is gated by the shared codec-
+ * blind shape predicate (`isPieceCid` in
+ * `./filecoin-cid-validation.ts`) before crossing the public
+ * boundary — adversarial / legacy / manually-planted JSONB values
+ * that don't match the structural shape are silently dropped
+ * rather than echoed onto the wire. The shape gate is a belt-and-
+ * suspenders defence; on the WRITE path the provider boundary
+ * already rejected anything that doesn't round-trip through the
+ * Synapse SDK parser, so for rows written via the normal pipeline
+ * this gate is a no-op. The `ipfs_cid` slot uses the broader
+ * CIDv1 base32 shape predicate (`isIpfsCid`) — real codec-aware
+ * parsing happens on the WRITE path inside
+ * `providers/filecoin/ipfs-cid.ts` via `multiformats/cid`. The
+ * projector intentionally stays eager-import-safe and vendor-light
+ * here, defeating any attempt to leak adversarial JSONB onto the
+ * wire even on legacy rows the SDK parser never gated.
+ */
+export function projectFilecoinPublicMetadata(internal) {
+    if (!isRecord(internal))
+        return {};
+    const out = {};
+    if (isIpfsCid(internal['ipfs_cid'])) {
+        out.ipfs_cid = internal['ipfs_cid'];
+    }
+    if (isPieceCid(internal['piece_cid'])) {
+        out.piece_cid = internal['piece_cid'];
+    }
+    const copiesProjection = projectCopies(internal['copies']);
+    if (copiesProjection !== null) {
+        out.copy_count = copiesProjection.copy_count;
+        if (copiesProjection.provider_ids.length > 0) {
+            out.provider_ids = copiesProjection.provider_ids;
+        }
+        if (copiesProjection.copy_statuses.length > 0) {
+            out.copy_statuses = copiesProjection.copy_statuses;
+        }
+    }
+    return out;
+}
+function projectCopies(value) {
+    if (!Array.isArray(value))
+        return null;
+    const provider_ids = [];
+    const copy_statuses = [];
+    for (const entry of value) {
+        if (!isRecord(entry))
+            continue;
+        const providerId = entry['provider_id'];
+        if (typeof providerId === 'string' && providerId.length > 0) {
+            provider_ids.push(providerId);
+        }
+        const status = entry['status'];
+        if (typeof status === 'string' && status.length > 0) {
+            copy_statuses.push(status);
+        }
+    }
+    return { copy_count: value.length, provider_ids, copy_statuses };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/storage/local-fs-store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `local_fs` adapter for `RawContentStore`.
+ *
+ * Stores blobs on the local filesystem under a configured root. Used for
+ * development and single-node test deployments — production setups
+ * configure the S3 adapter instead.
+ *
+ * Storage URI shape: `local-fs://<adapter-relative-key>`. The key is the
+ * same string the caller passed to `put()`; the absolute filesystem path
+ * is reconstructed by joining `root + key`. We never persist the absolute
+ * path on the wire so the same DB row stays portable when the root moves.
+ *
+ * Atomicity: writes go through a `<key>.tmp.<nonce>` sibling and are
+ * promoted with `fs.rename`, so a crash mid-write never leaves a
+ * partial blob at the final key. `delete` is idempotent — `ENOENT`
+ * surfaces as `{ deleted: false }` rather than an error.
+ *
+ * Path safety: every adapter-relative key resolves through `path.resolve`
+ * and is rejected if it escapes `root`. That keeps a malicious or
+ * mistaken `..`-laden key from writing/reading outside the configured
+ * sandbox.
+ */
+import { type PutRawContentInput, type RawContentDeleteResult, type RawContentGetResult, type RawContentHeadResult, type RawContentHints, type RawContentStore, type RawContentStoreCapabilities, type StoredRawContent } from './raw-content-store.js';
+export interface LocalFsRawContentStoreOptions {
+    /** Absolute or relative path to the storage root. Resolved at construction. */
+    root: string;
+}
+export declare class LocalFsRawContentStore implements RawContentStore {
+    readonly provider: "local_fs";
+    readonly capabilities: RawContentStoreCapabilities;
+    private readonly root;
+    constructor(options: LocalFsRawContentStoreOptions);
+    put(input: PutRawContentInput): Promise<StoredRawContent>;
+    get(storageUri: string): Promise<RawContentGetResult>;
+    head(storageUri: string, _hints?: RawContentHints): Promise<RawContentHeadResult>;
+    delete(storageUri: string, _hints?: RawContentHints): Promise<RawContentDeleteResult>;
+    private resolveKey;
+    private resolveUri;
+}

package/dist/storage/local-fs-store.js

@@ -0,0 +1,145 @@
+/**
+ * `local_fs` adapter for `RawContentStore`.
+ *
+ * Stores blobs on the local filesystem under a configured root. Used for
+ * development and single-node test deployments — production setups
+ * configure the S3 adapter instead.
+ *
+ * Storage URI shape: `local-fs://<adapter-relative-key>`. The key is the
+ * same string the caller passed to `put()`; the absolute filesystem path
+ * is reconstructed by joining `root + key`. We never persist the absolute
+ * path on the wire so the same DB row stays portable when the root moves.
+ *
+ * Atomicity: writes go through a `<key>.tmp.<nonce>` sibling and are
+ * promoted with `fs.rename`, so a crash mid-write never leaves a
+ * partial blob at the final key. `delete` is idempotent — `ENOENT`
+ * surfaces as `{ deleted: false }` rather than an error.
+ *
+ * Path safety: every adapter-relative key resolves through `path.resolve`
+ * and is rejected if it escapes `root`. That keeps a malicious or
+ * mistaken `..`-laden key from writing/reading outside the configured
+ * sandbox.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { RawStorageUriError, } from './raw-content-store.js';
+const PROVIDER = 'local_fs';
+const URI_PREFIX = 'local-fs://';
+/**
+ * `local_fs` is path-addressed (the URI is the on-disk path under the
+ * configured root — a subsequent `put` to the same key replaces the
+ * bytes that path resolves to), bytes are retrievable the instant
+ * `put` resolves, and `deleteSemantics: 'delete'` means the adapter
+ * issues `fs.unlink` for the managed file. Filesystem-level
+ * snapshots, backup tooling, or undeletion utilities live outside
+ * the adapter contract; AtomicMemory does not assert what they do
+ * with the deleted inode.
+ */
+const CAPABILITIES = Object.freeze({
+    addressing: 'location',
+    retrievalConsistency: 'immediate',
+    deleteSemantics: 'delete',
+    supportsHead: true,
+    supportsGet: true,
+});
+export class LocalFsRawContentStore {
+    provider = PROVIDER;
+    capabilities = CAPABILITIES;
+    root;
+    constructor(options) {
+        if (!options.root || options.root.length === 0) {
+            throw new Error('LocalFsRawContentStore: root is required');
+        }
+        this.root = resolve(options.root);
+    }
+    async put(input) {
+        const target = this.resolveKey(input.key);
+        await fs.mkdir(dirname(target), { recursive: true });
+        const tmp = `${target}.tmp.${randomBytes(8).toString('hex')}`;
+        try {
+            await fs.writeFile(tmp, input.body);
+            await fs.rename(tmp, target);
+        }
+        catch (err) {
+            await fs.rm(tmp, { force: true }).catch(() => undefined);
+            throw err;
+        }
+        return {
+            storageUri: `${URI_PREFIX}${input.key}`,
+            storageProvider: PROVIDER,
+            contentHash: sha256Hex(input.body),
+            sizeBytes: input.body.length,
+            status: 'stored',
+            providerMetadata: {},
+        };
+    }
+    async get(storageUri) {
+        const target = this.resolveUri(storageUri);
+        const body = await fs.readFile(target);
+        return {
+            body,
+            metadata: {
+                contentLength: body.length,
+                contentType: null,
+                contentHash: sha256Hex(body),
+                providerMetadata: {},
+            },
+        };
+    }
+    async head(storageUri, _hints) {
+        const target = this.resolveUri(storageUri);
+        try {
+            const stat = await fs.stat(target);
+            return {
+                exists: true,
+                metadata: {
+                    contentLength: stat.size,
+                    contentType: null,
+                    contentHash: null,
+                    providerMetadata: { mtime: stat.mtime.toISOString() },
+                },
+            };
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return { exists: false, metadata: null };
+            throw err;
+        }
+    }
+    async delete(storageUri, _hints) {
+        const target = this.resolveUri(storageUri);
+        try {
+            await fs.unlink(target);
+            return { deleted: true, semantics: 'deleted' };
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return { deleted: false, semantics: 'deleted' };
+            throw err;
+        }
+    }
+    resolveKey(key) {
+        if (isAbsolute(key)) {
+            throw new RawStorageUriError(`local_fs key must be relative: ${key}`);
+        }
+        const target = resolve(this.root, key);
+        const inside = relative(this.root, target);
+        if (inside.startsWith('..') || isAbsolute(inside)) {
+            throw new RawStorageUriError(`local_fs key escapes root: ${key}`);
+        }
+        return target;
+    }
+    resolveUri(storageUri) {
+        if (!storageUri.startsWith(URI_PREFIX)) {
+            throw new RawStorageUriError(`expected local-fs:// URI, got: ${storageUri}`);
+        }
+        return this.resolveKey(storageUri.slice(URI_PREFIX.length));
+    }
+}
+function sha256Hex(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}
+function isNotFound(err) {
+    return typeof err === 'object' && err !== null && err.code === 'ENOENT';
+}

package/dist/storage/pointer-uri-allowlist.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Pointer-URI scheme allowlist + validator.
+ *
+ * Step 5 of the storage-sibling plan. Pointer-mode artifacts carry a
+ * caller-supplied URI that the server stores but NEVER fetches; even
+ * so, narrowing what schemes can be persisted protects downstream
+ * consumers (browser UIs, future server-side prefetchers) from
+ * unauthenticated or weak references. Default allowlist is
+ * `https://`, `s3://`, `gs://`, `ipfs://`. Operators can opt in
+ * `http://` or `local-fs://` via the `RAW_STORAGE_POINTER_URI_SCHEMES`
+ * csv knob — adding a scheme is the operator attesting that
+ * downstream consumers are safe against that scheme's specific
+ * risks.
+ *
+ * The startup parser fails closed on unknown scheme tokens so
+ * typos surface deterministically.
+ */
+declare const KNOWN_SCHEMES: readonly ["https", "s3", "gs", "ipfs", "http", "local-fs"];
+type KnownScheme = (typeof KNOWN_SCHEMES)[number];
+/**
+ * Parse the `RAW_STORAGE_POINTER_URI_SCHEMES` env value. Empty /
+ * undefined → defaults. Unknown tokens → throw.
+ */
+export declare function parsePointerUriSchemes(value: string | undefined): ReadonlyArray<KnownScheme>;
+/**
+ * Extract the URI scheme (lowercase, no trailing colon) without
+ * relying on `URL` parsing — `s3://` and `ipfs://` are not
+ * recognised by the WHATWG URL parser. Returns null when the input
+ * does not start with a scheme.
+ */
+export declare function extractScheme(uri: string): string | null;
+/**
+ * Test whether `uri` carries an allowlisted scheme. The active
+ * allowlist is captured at startup and passed in from the route
+ * layer — keeps this module free of any config singleton import.
+ */
+export declare function isAllowlistedPointerUri(uri: string, allowlist: ReadonlyArray<KnownScheme>): boolean;
+export {};

package/dist/storage/pointer-uri-allowlist.js

@@ -0,0 +1,70 @@
+/**
+ * @file Pointer-URI scheme allowlist + validator.
+ *
+ * Step 5 of the storage-sibling plan. Pointer-mode artifacts carry a
+ * caller-supplied URI that the server stores but NEVER fetches; even
+ * so, narrowing what schemes can be persisted protects downstream
+ * consumers (browser UIs, future server-side prefetchers) from
+ * unauthenticated or weak references. Default allowlist is
+ * `https://`, `s3://`, `gs://`, `ipfs://`. Operators can opt in
+ * `http://` or `local-fs://` via the `RAW_STORAGE_POINTER_URI_SCHEMES`
+ * csv knob — adding a scheme is the operator attesting that
+ * downstream consumers are safe against that scheme's specific
+ * risks.
+ *
+ * The startup parser fails closed on unknown scheme tokens so
+ * typos surface deterministically.
+ */
+const KNOWN_SCHEMES = ['https', 's3', 'gs', 'ipfs', 'http', 'local-fs'];
+const DEFAULT_SCHEMES = ['https', 's3', 'gs', 'ipfs'];
+/**
+ * Parse the `RAW_STORAGE_POINTER_URI_SCHEMES` env value. Empty /
+ * undefined → defaults. Unknown tokens → throw.
+ */
+export function parsePointerUriSchemes(value) {
+    if (value === undefined || value.trim().length === 0)
+        return DEFAULT_SCHEMES;
+    const entries = value.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+    if (entries.length === 0)
+        return DEFAULT_SCHEMES;
+    const out = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        if (!isKnownScheme(entry)) {
+            throw new Error(`Invalid RAW_STORAGE_POINTER_URI_SCHEMES entry '${entry}'. ` +
+                `Must be one of: ${KNOWN_SCHEMES.join(', ')}.`);
+        }
+        if (seen.has(entry)) {
+            throw new Error(`Duplicate scheme '${entry}' in RAW_STORAGE_POINTER_URI_SCHEMES.`);
+        }
+        seen.add(entry);
+        out.push(entry);
+    }
+    return out;
+}
+/**
+ * Extract the URI scheme (lowercase, no trailing colon) without
+ * relying on `URL` parsing — `s3://` and `ipfs://` are not
+ * recognised by the WHATWG URL parser. Returns null when the input
+ * does not start with a scheme.
+ */
+export function extractScheme(uri) {
+    const match = /^([a-zA-Z][a-zA-Z0-9+.\-]*):\/\//.exec(uri);
+    if (match === null)
+        return null;
+    return match[1].toLowerCase();
+}
+/**
+ * Test whether `uri` carries an allowlisted scheme. The active
+ * allowlist is captured at startup and passed in from the route
+ * layer — keeps this module free of any config singleton import.
+ */
+export function isAllowlistedPointerUri(uri, allowlist) {
+    const scheme = extractScheme(uri);
+    if (scheme === null)
+        return false;
+    return allowlist.includes(scheme);
+}
+function isKnownScheme(value) {
+    return KNOWN_SCHEMES.includes(value);
+}