@atomicmemory/core 1.0.0

package/dist/routes/storage-error-handlers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file Wire-envelope mapping for `StorageService` typed errors.
+ *
+ * Extracted from `routes/storage.ts` so the route module stays
+ * focused on route registration and request handling. The mapping
+ * is a data-driven `STORAGE_ERROR_DISPATCH` table — one row per
+ * typed error — plus a focused `sendXxx` helper per error so the
+ * response shape for each is reviewable in isolation.
+ *
+ * Public entry point: `handleStorageError(res, err)` returns true
+ * when it sent a response and the caller should stop. The
+ * `LegacyUserIdRejection` class is re-exported because the route
+ * module throws it from `readUserId` (storage routes reject the
+ * legacy `?user_id=` / body shape; the auth header is the only
+ * accepted source).
+ */
+import type { Response } from 'express';
+/**
+ * Thrown by `readUserId` when a storage route request carries the
+ * legacy `?user_id=` query or body `user_id` shape instead of the
+ * `X-AtomicMemory-User-Id` header. Kept here (not in
+ * `storage-service-errors.ts`) because it is a route-layer concept
+ * — the service doesn't know how identity arrived on the wire.
+ */
+export declare class LegacyUserIdRejection extends Error {
+    constructor();
+}
+/**
+ * Map a service-layer typed error to its HTTP envelope. Returns
+ * `true` when the response was sent and the caller should stop.
+ * Returns `false` when no row matched — the caller (route layer)
+ * should fall through to its generic 500 handler.
+ */
+export declare function handleStorageError(res: Response, err: unknown): boolean;

package/dist/routes/storage-error-handlers.js

@@ -0,0 +1,185 @@
+/**
+ * @file Wire-envelope mapping for `StorageService` typed errors.
+ *
+ * Extracted from `routes/storage.ts` so the route module stays
+ * focused on route registration and request handling. The mapping
+ * is a data-driven `STORAGE_ERROR_DISPATCH` table — one row per
+ * typed error — plus a focused `sendXxx` helper per error so the
+ * response shape for each is reviewable in isolation.
+ *
+ * Public entry point: `handleStorageError(res, err)` returns true
+ * when it sent a response and the caller should stop. The
+ * `LegacyUserIdRejection` class is re-exported because the route
+ * module throws it from `readUserId` (storage routes reject the
+ * legacy `?user_id=` / body shape; the auth header is the only
+ * accepted source).
+ */
+import { ArtifactDeleteInFlightError, ArtifactInUseError, ArtifactNotReadyError, ArtifactUnavailableError, BackendNotRegisteredError, FilecoinDirectStorageNotSupportedError, InvalidArtifactMetadataError, ManagedStorageDisabledError, PointerContentNotManagedError, PutPostPersistError, StorageArtifactNotFoundError, UnregisteredProviderError, UnsupportedPointerSchemeError, } from '../services/storage-service-errors.js';
+/**
+ * Thrown by `readUserId` when a storage route request carries the
+ * legacy `?user_id=` query or body `user_id` shape instead of the
+ * `X-AtomicMemory-User-Id` header. Kept here (not in
+ * `storage-service-errors.ts`) because it is a route-layer concept
+ * — the service doesn't know how identity arrived on the wire.
+ */
+export class LegacyUserIdRejection extends Error {
+    constructor() {
+        super('legacy ?user_id= query or body user_id is no longer accepted; ' +
+            'send X-AtomicMemory-User-Id header instead');
+        this.name = 'LegacyUserIdRejection';
+    }
+}
+const STORAGE_ERROR_DISPATCH = [
+    [StorageArtifactNotFoundError, (r, e) => send404NotFound(r, e)],
+    [PointerContentNotManagedError, (r, e) => send409PointerContent(r, e)],
+    [FilecoinDirectStorageNotSupportedError, (r, e) => send501Filecoin(r, e)],
+    [UnsupportedPointerSchemeError, (r, e) => send400UnsupportedScheme(r, e)],
+    [ArtifactInUseError, (r, e) => send409InUse(r, e)],
+    [ArtifactDeleteInFlightError, (r, e) => send409DeleteInFlight(r, e)],
+    [ManagedStorageDisabledError, (r, e) => send503ManagedDisabled(r, e)],
+    [BackendNotRegisteredError, (r, e) => send503BackendUnavailable(r, e)],
+    [UnregisteredProviderError, (r, e) => send503UnregisteredProvider(r, e)],
+    [PutPostPersistError, (r, e) => send503PutPostPersist(r, e)],
+    [ArtifactNotReadyError, (r, e) => send409ArtifactNotReady(r, e)],
+    [ArtifactUnavailableError, (r, e) => send410ArtifactUnavailable(r, e)],
+    [InvalidArtifactMetadataError, (r, e) => send400Metadata(r, e)],
+    [LegacyUserIdRejection, (r, e) => send400LegacyUserId(r, e)],
+];
+/**
+ * Map a service-layer typed error to its HTTP envelope. Returns
+ * `true` when the response was sent and the caller should stop.
+ * Returns `false` when no row matched — the caller (route layer)
+ * should fall through to its generic 500 handler.
+ */
+export function handleStorageError(res, err) {
+    for (const [ctor, handler] of STORAGE_ERROR_DISPATCH) {
+        if (err instanceof ctor)
+            return handler(res, err);
+    }
+    return false;
+}
+function send404NotFound(res, err) {
+    res.status(404).json({ error_code: 'artifact_not_found', error: err.message });
+    return true;
+}
+function send409PointerContent(res, err) {
+    res.status(409).json({
+        error_code: 'pointer_content_not_managed',
+        error: err.message,
+        uri: err.uri,
+        hint: 'Fetch the URI directly; the server does not proxy pointer content.',
+    });
+    return true;
+}
+function send501Filecoin(res, err) {
+    res.status(501).json({
+        error_code: err.provider === 'filecoin'
+            ? 'filecoin_direct_storage_not_yet_supported'
+            : 'provider_direct_storage_not_yet_supported',
+        error: err.message,
+        follow_up: 'Use document ingestion or pointer mode.',
+    });
+    return true;
+}
+function send400UnsupportedScheme(res, err) {
+    res.status(400).json({
+        error_code: 'invalid_pointer_uri_scheme',
+        error: err.message,
+        allowed_schemes: err.allowedSchemes,
+    });
+    return true;
+}
+function send409InUse(res, err) {
+    res.status(409).json({
+        error_code: 'artifact_in_use',
+        error: err.message,
+        referenced_by_document_count: err.referencedByDocumentCount,
+        follow_up: "Pass `?policy=with_documents` to cascade.",
+    });
+    return true;
+}
+function send409DeleteInFlight(res, err) {
+    res.status(409).json({
+        error_code: 'delete_in_flight',
+        error: err.message,
+        artifact_id: err.artifactId,
+        current_status: err.currentStatus,
+        retryable: true,
+    });
+    return true;
+}
+function send503ManagedDisabled(res, err) {
+    res.status(503).json({ error_code: 'managed_storage_disabled', error: err.message });
+    return true;
+}
+function send503BackendUnavailable(res, err) {
+    // Sanitized envelope: provider_id is the only identifier the
+    // client can use to ask the operator to re-register the adapter.
+    // Internal stack/error text stays server-side.
+    res.status(503).json({
+        error_code: 'storage_backend_unavailable',
+        error: `the storage backend for provider '${err.providerId}' is not registered with this deployment`,
+        provider_id: err.providerId,
+    });
+    return true;
+}
+function send503UnregisteredProvider(res, err) {
+    // Composition-level variant of `storage_backend_unavailable`:
+    // fires at putManaged entry when the active backend's provider
+    // isn't registered with the deployment's registry. Same wire
+    // envelope as `BackendNotRegisteredError` so clients have one
+    // contract.
+    res.status(503).json({
+        error_code: 'storage_backend_unavailable',
+        error: `provider '${err.providerId}' is not registered with this deployment`,
+        provider_id: err.providerId,
+    });
+    return true;
+}
+function send503PutPostPersist(res, err) {
+    // Sanitized envelope: artifact_id + provider_id are public; the
+    // orphan URI lives on the server side (event log + the row's
+    // internal `last_error`) and is NEVER on the wire.
+    res.status(503).json({
+        error_code: 'put_post_persist_failed',
+        error: 'the storage backend accepted the bytes but the server could not finalize the artifact',
+        artifact_id: err.artifactId,
+        provider_id: err.providerId,
+    });
+    return true;
+}
+function send409ArtifactNotReady(res, err) {
+    res.status(409).json({
+        error_code: 'artifact_not_ready',
+        error: err.message,
+        artifact_id: err.artifactId,
+        hint: 'The managed upload is still pending finalization; retry after a short delay.',
+    });
+    return true;
+}
+function send410ArtifactUnavailable(res, err) {
+    res.status(410).json({
+        error_code: 'artifact_unavailable',
+        error: err.message,
+        artifact_id: err.artifactId,
+        reason: err.reason,
+    });
+    return true;
+}
+function send400Metadata(res, err) {
+    const isHeader = err.reason.toLowerCase().includes('header');
+    res.status(400).json({
+        error_code: isHeader ? 'invalid_metadata_header' : 'invalid_metadata',
+        error: err.message,
+        hint: err.reason,
+    });
+    return true;
+}
+function send400LegacyUserId(res, err) {
+    res.status(400).json({
+        error_code: 'legacy_user_id_unsupported',
+        error: err.message,
+        hint: 'Pass identity in the X-AtomicMemory-User-Id header instead.',
+    });
+    return true;
+}

package/dist/routes/storage-response-formatters.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file Wire-shape projections for the direct storage API.
+ *
+ * Every public response for the
+ * `/v1/storage/artifacts*` routes flows through `formatStoredArtifact`
+ * which:
+ *
+ *   1. Builds the wire object by EXPLICIT named-key construction.
+ *      Internal columns (`stored_hash`, `last_error`, `delete_attempt_id`)
+ *      are never read. The plaintext `content_hash` is included only
+ *      when the row's `disclose_content_hash` was true at put time.
+ *   2. Runs the result through provider-specific redaction
+ *      (`redactArtifactPublic`) so `identifiers` / `provider_details`
+ *      land in a closed allowlist for each known provider.
+ *   3. Validates the projection with `StoredArtifactResponseSchema.strict()`
+ *      — the formatter is the primary projector; the schema is the
+ *      defence-in-depth lock that drops any field that slipped past
+ *      the named-key construction.
+ *
+ * Callers throw if the schema parse fails; that signals a regression
+ * in the projection logic itself (the schema is impossible to
+ * violate by data alone since the formatter constructs the object
+ * key-by-key).
+ */
+import type { StorageArtifactRow } from '../db/storage-artifact-repository.js';
+import { type StoredArtifactResponse } from '../schemas/storage-schemas.js';
+/**
+ * Project a repository row into its wire shape.
+ *
+ * @throws ZodError if the strict schema rejects the projected object —
+ *   that means the formatter dropped an internal field on the wire.
+ *   Tests must catch any regression here.
+ */
+export declare function formatStoredArtifact(row: StorageArtifactRow): StoredArtifactResponse;
+/** Wire headers for `HEAD /v1/storage/artifacts/:id`. */
+export interface ArtifactHeadHeaders {
+    contentType: string;
+    contentLength: number;
+    artifactId: string;
+    storageMode: 'pointer' | 'managed';
+    storageStatus: string;
+    provider: string;
+}
+export declare function formatArtifactHeadHeaders(row: StorageArtifactRow): ArtifactHeadHeaders;

package/dist/routes/storage-response-formatters.js

@@ -0,0 +1,155 @@
+/**
+ * @file Wire-shape projections for the direct storage API.
+ *
+ * Every public response for the
+ * `/v1/storage/artifacts*` routes flows through `formatStoredArtifact`
+ * which:
+ *
+ *   1. Builds the wire object by EXPLICIT named-key construction.
+ *      Internal columns (`stored_hash`, `last_error`, `delete_attempt_id`)
+ *      are never read. The plaintext `content_hash` is included only
+ *      when the row's `disclose_content_hash` was true at put time.
+ *   2. Runs the result through provider-specific redaction
+ *      (`redactArtifactPublic`) so `identifiers` / `provider_details`
+ *      land in a closed allowlist for each known provider.
+ *   3. Validates the projection with `StoredArtifactResponseSchema.strict()`
+ *      — the formatter is the primary projector; the schema is the
+ *      defence-in-depth lock that drops any field that slipped past
+ *      the named-key construction.
+ *
+ * Callers throw if the schema parse fails; that signals a regression
+ * in the projection logic itself (the schema is impossible to
+ * violate by data alone since the formatter constructs the object
+ * key-by-key).
+ */
+import { redactArtifactPublic } from '../storage/artifact-public-redaction.js';
+import { StoredArtifactResponseSchema, } from '../schemas/storage-schemas.js';
+/** Closed allowlists of nested keys we may publish per state envelope. */
+const REPLICATION_KEYS = ['desiredCopies', 'confirmedCopies'];
+const VERIFICATION_KEYS = ['providerProofStatus', 'lastVerifiedAt'];
+const RETRIEVAL_KEYS = ['status', 'lastCheckedAt'];
+/**
+ * Project a repository row into its wire shape.
+ *
+ * @throws ZodError if the strict schema rejects the projected object —
+ *   that means the formatter dropped an internal field on the wire.
+ *   Tests must catch any regression here.
+ */
+export function formatStoredArtifact(row) {
+    const redacted = redactArtifactPublic(row.provider, {
+        identifiers: row.identifiers,
+        providerDetails: row.providerDetails,
+    });
+    const wire = {
+        artifact_id: row.id,
+        provider: row.provider,
+        mode: row.mode,
+        uri: row.uri,
+        status: row.status,
+        size_bytes: row.sizeBytes,
+        content_type: row.contentType,
+        content_encoding: row.contentEncoding,
+        identifiers: redacted.identifiers,
+        lifecycle: deriveLifecycle(row),
+        metadata: projectPublicMetadata(row.metadata),
+        created_at: row.createdAt.toISOString(),
+        updated_at: row.updatedAt.toISOString(),
+    };
+    if (row.discloseContentHash && row.plaintextHash !== null) {
+        wire.content_hash = row.plaintextHash;
+    }
+    if (Object.keys(redacted.providerDetails).length > 0) {
+        wire.provider_details = redacted.providerDetails;
+    }
+    const replication = projectStateEnvelope(row.replication, REPLICATION_KEYS);
+    if (replication !== null)
+        wire.replication = replication;
+    const verification = projectStateEnvelope(row.verification, VERIFICATION_KEYS);
+    if (verification !== null)
+        wire.verification = verification;
+    const retrieval = projectStateEnvelope(row.retrieval, RETRIEVAL_KEYS);
+    if (retrieval !== null)
+        wire.retrieval = retrieval;
+    return StoredArtifactResponseSchema.parse(wire);
+}
+/**
+ * Lifecycle is a derived projection from `(provider, mode)`: pointer
+ * artifacts have no async lifecycle (`availability: 'immediate'`,
+ * no delete semantics); managed artifacts get the location-addressed
+ * shape on `local_fs`/`s3` and delayed/tombstone semantics on
+ * content-addressed eventual providers (`filecoin`). Any
+ * other backend reports an empty envelope (fail-closed). The row's
+ * `lifecycle` JSONB column is reserved for future per-row overrides;
+ * the derived projection currently wins.
+ */
+function deriveLifecycle(row) {
+    if (row.mode === 'pointer')
+        return { availability: 'immediate' };
+    if (row.provider === 'local_fs' || row.provider === 's3') {
+        return { availability: 'immediate', deleteSemantics: 'delete' };
+    }
+    if (row.provider === 'filecoin') {
+        return { availability: 'delayed', deleteSemantics: 'tombstone' };
+    }
+    return {};
+}
+/**
+ * Defensive projection for the public `metadata` field.
+ *
+ * Write paths validate metadata with `validateArtifactMetadata`
+ * (closed leaf-type set: string | number | boolean; ≤4 KiB), but a
+ * row that was inserted before that check existed — or via a
+ * direct SQL ops fix — could carry arrays, nested objects, or
+ * other non-leaf values. The previous formatter blindly cast the
+ * raw JSONB through `as Record<string, string | number | boolean>`,
+ * which silently leaked the unsanitized shape onto the wire.
+ *
+ * This projection iterates the row's own keys and emits ONLY the
+ * leaf-type entries; everything else (arrays, nested objects,
+ * null, undefined, functions) is dropped. Non-object inputs
+ * project to `{}`. The closed allowlist matches the write-side
+ * `ArtifactMetadata` contract.
+ */
+function projectPublicMetadata(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (typeof raw === 'string' || typeof raw === 'number' || typeof raw === 'boolean') {
+            out[key] = raw;
+        }
+    }
+    return out;
+}
+/**
+ * Project a state envelope (replication / verification / retrieval)
+ * via the same project-then-validate discipline as the top-level
+ * artifact: build an allowlisted object by named keys, drop unknown
+ * keys, and only emit the envelope when at least one allowlisted
+ * key is populated.
+ */
+function projectStateEnvelope(raw, keys) {
+    if (raw === null)
+        return null;
+    const out = {};
+    for (const key of keys) {
+        const value = raw[key];
+        if (value === undefined || value === null)
+            continue;
+        out[key] = value;
+    }
+    if (Object.keys(out).length === 0)
+        return null;
+    return out;
+}
+export function formatArtifactHeadHeaders(row) {
+    return {
+        contentType: row.contentType ?? 'application/octet-stream',
+        // Pointer artifacts report 0 — the server has no bytes to count.
+        contentLength: row.mode === 'managed' ? (row.sizeBytes ?? 0) : 0,
+        artifactId: row.id,
+        storageMode: row.mode,
+        storageStatus: row.status,
+        provider: row.provider,
+    };
+}

package/dist/routes/storage.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Direct storage API routes (`/v1/storage/*`).
+ *
+ * Step 3 added `GET /v1/storage/capabilities`; Step 5 adds the
+ * artifact CRUD surface on top of the same router:
+ *
+ *   POST   /v1/storage/artifacts            pointer (JSON body) or
+ *                                            ?mode=managed (raw bytes)
+ *   GET    /v1/storage/artifacts/:id        public metadata
+ *   GET    /v1/storage/artifacts/:id/content bytes (managed) or 409 (pointer)
+ *   HEAD   /v1/storage/artifacts/:id        metadata via response headers
+ *   DELETE /v1/storage/artifacts/:id?policy=...
+ *   POST   /v1/storage/artifacts/:id/verify backend.head()-based shim
+ *
+ * Body parsing is per-route:
+ *   * Pointer-mode put + verify use the standard JSON parser.
+ *   * Managed-mode put uses `express.raw({ type: '*\/*' })` with the
+ *     configured byte cap; the route extracts the caller-supplied
+ *     `X-AtomicMemory-Metadata` header (base64-encoded JSON) and
+ *     validates it against the decoded-JSON cap.
+ *
+ * Redaction posture: every public response runs through
+ * `formatStoredArtifact` (or its sibling formatters) which projects
+ * an allowlisted shape THEN `.strict()`-parses through the schema in
+ * `STORAGE_RESPONSE_SCHEMAS`. Internal columns (`stored_hash`,
+ * `last_error`, `delete_attempt_id`) never reach the wire.
+ */
+import { Router } from 'express';
+import { type StorageCapabilitiesSnapshot } from '../storage/storage-capabilities.js';
+import { type StorageService } from '../services/storage-service.js';
+/** Composition-time inputs for the storage router. */
+export interface StorageRouterOptions {
+    capabilities: StorageCapabilitiesSnapshot;
+    service: StorageService;
+    /** Body cap for managed-mode uploads (bytes). */
+    managedUploadMaxBytes: number;
+}
+export declare function createStorageRouter(opts: StorageRouterOptions): Router;