@arnilo/prism-server 0.0.27 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.1.0] - 2026-08-09
+
+### Changed
+- Released with exact 0.1.0 graph.
+
+## [0.0.28] - 2026-08-08
+
+### Added
+- `createArtifactService` accepts an optional `bodies: ArtifactBodyStore` (core contract from `@arnilo/prism`): when wired, `deliveryLink` resolves through `bodies.presign` and returns an additional bounded-TTL presigned `url` beside the signed link/token; revisions without a recorded `size` fail closed at delivery. `attach`/`revise` accept an optional `size` (validated non-negative safe integer) recorded on the revision.
+- New `@arnilo/prism-server/artifact-bodies` subpath: `createS3ArtifactBodyStore` — reference S3-compatible `ArtifactBodyStore` (AWS S3, MinIO, Cloudflare R2) with hand-rolled SigV4 presigning over native fetch + WebCrypto (validated against the official AWS sig-v4-test-suite get-vanilla vector), path-style addressing, single-chunk PUT with exact Content-Length and verified `x-amz-content-sha256`, ownership verification on every operation, size/SHA-256/MIME verification on put and get (fail closed), legal-hold-aware idempotent delete (host `isHeld` callback), host-resolved credentials (never inline), optional host-owned client-side KMS callback, bounded concurrent transfers, and no bucket/path/key disclosure in errors. `S3ArtifactBodyError` carries frozen `ERR_PRISM_S3_*` codes; limits `maxBodyBytes` 64 MiB/512 MiB, `maxConcurrentTransfers` 4/16, `presignTtlMs` 10 min/24 h, `maxRefBytes` 256 B/1 KiB.
+
 ## [0.0.27] - 2026-08-07
 
 ### Changed

package/dist/artifact-bodies-s3.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Hand-rolled AWS Signature V4 over native WebCrypto (crypto.subtle) — no SDK dependency.
+ * Validated against the official AWS sig-v4-test-suite get-vanilla vector in
+ * `src/__tests__/artifact-bodies.test.ts`. S3-specific presigning (query-string auth,
+ * UNSIGNED-PAYLOAD for GET/DELETE, signed x-amz-content-sha256 for single-chunk PUT)
+ * lives in `artifact-bodies.ts`; this module is the generic algorithm.
+ */
+/** RFC 3986 percent-encoding as required by SigV4 (encodeURIComponent leaves !'()* unencoded). */
+export declare function awsUriEncode(value: string): string;
+/** SHA-256 hex digest over WebCrypto. */
+export declare function sha256Hex(data: Uint8Array): Promise<string>;
+/** Canonical query string: sorted keys, RFC 3986 encoded, `key=value` joined with `&`. */
+export declare function canonicalQueryString(query: Readonly<Record<string, string>>): string;
+/** Canonical headers block: lowercase name, trimmed/collapsed value, trailing newline. */
+export declare function canonicalHeaders(headers: Readonly<Record<string, string>>, signedHeaders: readonly string[]): string;
+export interface SigV4SignInput {
+    readonly method: string;
+    /** Pre-encoded path (e.g. `/bucket/key`); used verbatim. */
+    readonly path: string;
+    readonly query?: Readonly<Record<string, string>>;
+    /** Lowercase header names. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Subset of header names, sorted; the caller decides what to sign. */
+    readonly signedHeaders: readonly string[];
+    /** Hex SHA-256 of the payload, or "UNSIGNED-PAYLOAD". */
+    readonly payloadHash: string;
+    readonly region: string;
+    readonly service: string;
+    /** `YYYYMMDDTHHMMSSZ`. */
+    readonly amzDate: string;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly sessionToken?: string;
+}
+export interface SigV4Signature {
+    readonly signature: string;
+    readonly canonicalRequest: string;
+}
+/** Full SigV4 pipeline: canonical request -> string-to-sign -> derived-key HMAC. */
+export declare function signV4(input: SigV4SignInput): Promise<SigV4Signature>;
+export interface SigV4PresignInput {
+    readonly method: string;
+    readonly path: string;
+    readonly query?: Readonly<Record<string, string>>;
+    /** Lowercase header names; only `host` is signed for presigned URLs. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly payloadHash: string;
+    readonly region: string;
+    readonly service: string;
+    readonly amzDate: string;
+    readonly expiresSeconds: number;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly sessionToken?: string;
+}
+/** Presign: returns the full query string (X-Amz-* params + X-Amz-Signature) for a URL. */
+export declare function presignV4(input: SigV4PresignInput): Promise<string>;
+export interface SigV4RequestSignInput {
+    readonly method: string;
+    readonly path: string;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Headers to sign (subset of `headers`, sorted); the caller sends exactly these. */
+    readonly signedHeaders: readonly string[];
+    readonly payloadHash: string;
+    readonly region: string;
+    readonly service: string;
+    readonly amzDate: string;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly sessionToken?: string;
+}
+/** Sign a direct request: returns headers including x-amz-date, x-amz-content-sha256, and Authorization. */
+export declare function signRequestV4(input: SigV4RequestSignInput): Promise<{
+    readonly headers: Record<string, string>;
+}>;

package/dist/artifact-bodies-s3.js

@@ -0,0 +1,104 @@
+/**
+ * Hand-rolled AWS Signature V4 over native WebCrypto (crypto.subtle) — no SDK dependency.
+ * Validated against the official AWS sig-v4-test-suite get-vanilla vector in
+ * `src/__tests__/artifact-bodies.test.ts`. S3-specific presigning (query-string auth,
+ * UNSIGNED-PAYLOAD for GET/DELETE, signed x-amz-content-sha256 for single-chunk PUT)
+ * lives in `artifact-bodies.ts`; this module is the generic algorithm.
+ */
+/** RFC 3986 percent-encoding as required by SigV4 (encodeURIComponent leaves !'()* unencoded). */
+export function awsUriEncode(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/** SHA-256 hex digest over WebCrypto. */
+export async function sha256Hex(data) {
+    const digest = await crypto.subtle.digest("SHA-256", data);
+    return Buffer.from(digest).toString("hex");
+}
+async function hmacSha256(key, data) {
+    const imported = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const signature = await crypto.subtle.sign("HMAC", imported, data);
+    return new Uint8Array(signature);
+}
+/** Canonical query string: sorted keys, RFC 3986 encoded, `key=value` joined with `&`. */
+export function canonicalQueryString(query) {
+    return Object.keys(query)
+        .sort()
+        .map((key) => `${awsUriEncode(key)}=${awsUriEncode(query[key])}`)
+        .join("&");
+}
+/** Canonical headers block: lowercase name, trimmed/collapsed value, trailing newline. */
+export function canonicalHeaders(headers, signedHeaders) {
+    return signedHeaders.map((name) => `${name}:${(headers[name] ?? "").trim().replace(/\s+/g, " ")}\n`).join("");
+}
+/** Full SigV4 pipeline: canonical request -> string-to-sign -> derived-key HMAC. */
+export async function signV4(input) {
+    const date = input.amzDate.slice(0, 8);
+    const query = canonicalQueryString(input.query ?? {});
+    const headers = canonicalHeaders(input.headers, input.signedHeaders);
+    const signedNames = input.signedHeaders.join(";");
+    const canonicalRequest = `${input.method}\n${input.path}\n${query}\n${headers}\n${signedNames}\n${input.payloadHash}`;
+    const scope = `${date}/${input.region}/${input.service}/aws4_request`;
+    const stringToSign = `AWS4-HMAC-SHA256\n${input.amzDate}\n${scope}\n${await sha256Hex(new TextEncoder().encode(canonicalRequest))}`;
+    const kDate = await hmacSha256(new TextEncoder().encode(`AWS4${input.secretAccessKey}`), new TextEncoder().encode(date));
+    const kRegion = await hmacSha256(kDate, new TextEncoder().encode(input.region));
+    const kService = await hmacSha256(kRegion, new TextEncoder().encode(input.service));
+    const kSigning = await hmacSha256(kService, new TextEncoder().encode("aws4_request"));
+    const signature = Buffer.from(await hmacSha256(kSigning, new TextEncoder().encode(stringToSign))).toString("hex");
+    return { signature, canonicalRequest };
+}
+/** Presign: returns the full query string (X-Amz-* params + X-Amz-Signature) for a URL. */
+export async function presignV4(input) {
+    const date = input.amzDate.slice(0, 8);
+    const scope = `${date}/${input.region}/${input.service}/aws4_request`;
+    const signedHeaders = ["host"];
+    const query = {
+        "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
+        "X-Amz-Credential": `${input.accessKeyId}/${scope}`,
+        "X-Amz-Date": input.amzDate,
+        "X-Amz-Expires": String(input.expiresSeconds),
+        "X-Amz-SignedHeaders": signedHeaders.join(";"),
+        ...(input.sessionToken === undefined ? {} : { "X-Amz-Security-Token": input.sessionToken }),
+        ...input.query,
+    };
+    const { signature } = await signV4({
+        method: input.method,
+        path: input.path,
+        query,
+        headers: input.headers,
+        signedHeaders,
+        payloadHash: input.payloadHash,
+        region: input.region,
+        service: input.service,
+        amzDate: input.amzDate,
+        accessKeyId: input.accessKeyId,
+        secretAccessKey: input.secretAccessKey,
+        sessionToken: input.sessionToken,
+    });
+    return canonicalQueryString({ ...query, "X-Amz-Signature": signature });
+}
+/** Sign a direct request: returns headers including x-amz-date, x-amz-content-sha256, and Authorization. */
+export async function signRequestV4(input) {
+    const date = input.amzDate.slice(0, 8);
+    const scope = `${date}/${input.region}/${input.service}/aws4_request`;
+    const headers = {
+        ...input.headers,
+        "x-amz-date": input.amzDate,
+        "x-amz-content-sha256": input.payloadHash,
+    };
+    const { signature } = await signV4({
+        method: input.method,
+        path: input.path,
+        headers,
+        signedHeaders: input.signedHeaders,
+        payloadHash: input.payloadHash,
+        region: input.region,
+        service: input.service,
+        amzDate: input.amzDate,
+        accessKeyId: input.accessKeyId,
+        secretAccessKey: input.secretAccessKey,
+        sessionToken: input.sessionToken,
+    });
+    headers.authorization = `AWS4-HMAC-SHA256 Credential=${input.accessKeyId}/${scope}, SignedHeaders=${input.signedHeaders.join(";")}, Signature=${signature}`;
+    return { headers };
+}
+//# sourceMappingURL=artifact-bodies-s3.js.map

package/dist/artifact-bodies.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Reference S3-compatible artifact body store (Phase 11 / 0.0.28): hand-rolled SigV4
+ * presigning over native fetch + WebCrypto, path-style addressing, single-chunk PUT with
+ * exact Content-Length and x-amz-content-sha256 = verified SHA-256 hex (no chunked transfer).
+ * Implements the core `ArtifactBodyStore` contract; hosts may substitute any store.
+ *
+ * Security posture: ownership verified on every operation; size/hash/MIME verified on put
+ * and get (fail closed); delete refuses under legal hold (host `isHeld` callback) and is
+ * idempotent; credentials only via the host resolver; bucket/path/key never appear in
+ * errors, telemetry, or artifact records (the object key is derived from the ref).
+ */
+import { type ArtifactBodyRef, type ArtifactBodyStore } from "@arnilo/prism";
+/** Host-resolved S3 credentials; never inline, never logged. */
+export interface S3Credentials {
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    /** Optional session token (STS); included in the signature scope when present. */
+    readonly sessionToken?: string;
+}
+export interface ArtifactBodyLimits {
+    readonly maxBodyBytes?: number;
+    readonly maxConcurrentTransfers?: number;
+    readonly presignTtlMs?: number;
+    readonly maxRefBytes?: number;
+}
+export interface ResolvedArtifactBodyLimits {
+    readonly maxBodyBytes: number;
+    readonly maxConcurrentTransfers: number;
+    readonly presignTtlMs: number;
+    readonly maxRefBytes: number;
+}
+/** Phase 11 freeze: body 64 MiB/512 MiB; concurrent transfers 4/16; presign TTL 10 min/24 h; ref 256 B/1 KiB. */
+export declare const DEFAULT_ARTIFACT_BODY_LIMITS: ResolvedArtifactBodyLimits;
+export declare const HARD_ARTIFACT_BODY_LIMITS: ResolvedArtifactBodyLimits;
+export declare function resolveArtifactBodyLimits(input?: ArtifactBodyLimits): ResolvedArtifactBodyLimits;
+export interface S3ArtifactBodyStoreOptions {
+    /** Absolute base URL of the S3-compatible endpoint (https; http only for loopback hosts). */
+    readonly endpoint: string;
+    /** Bucket name (path-style addressing; no slashes). */
+    readonly bucket: string;
+    /** SigV4 region scope; default "us-east-1". */
+    readonly region?: string;
+    /** Host resolver for credentials; never inline keys. */
+    readonly credentials: () => S3Credentials | Promise<S3Credentials>;
+    /**
+     * Optional host-owned client-side encryption: `encrypt` runs before upload, `decrypt`
+     * after download. The ref hash/size always refer to the plaintext; the stored bytes are
+     * the ciphertext (so size is verified on the decrypted plaintext when kms is set).
+     */
+    readonly kms?: (op: "encrypt" | "decrypt", body: Uint8Array) => Promise<Uint8Array>;
+    /** Optional legal-hold check; delete refuses (ERR_PRISM_ARTIFACT_BODY_HELD) when held. */
+    readonly isHeld?: (ref: ArtifactBodyRef) => boolean | Promise<boolean>;
+    readonly limits?: ArtifactBodyLimits;
+    /** Test seam; defaults to global fetch. */
+    readonly fetch?: typeof fetch;
+    /** Test seam; defaults to Date.now. */
+    readonly now?: () => number;
+}
+/** Frozen S3 adapter failure reasons. */
+export type S3ArtifactBodyErrorCode = "PRESIGN" | "UPLOAD" | "DOWNLOAD" | "DELETE" | "CREDENTIALS";
+/** Typed S3 adapter failure; `code` is one of the frozen ERR_PRISM_S3_* codes. */
+export declare class S3ArtifactBodyError extends Error {
+    readonly reason: S3ArtifactBodyErrorCode;
+    readonly code: `ERR_PRISM_S3_${S3ArtifactBodyErrorCode}`;
+    constructor(message: string, reason: S3ArtifactBodyErrorCode);
+}
+/** Deterministic object key derived from the ref; bucket/path/key never enter artifact records. */
+export declare function s3ObjectKey(ref: ArtifactBodyRef): string;
+/** Reference S3-compatible ArtifactBodyStore (AWS S3, MinIO, Cloudflare R2). */
+export declare function createS3ArtifactBodyStore(options: S3ArtifactBodyStoreOptions): ArtifactBodyStore;

package/dist/artifact-bodies.js

@@ -0,0 +1,391 @@
+/**
+ * Reference S3-compatible artifact body store (Phase 11 / 0.0.28): hand-rolled SigV4
+ * presigning over native fetch + WebCrypto, path-style addressing, single-chunk PUT with
+ * exact Content-Length and x-amz-content-sha256 = verified SHA-256 hex (no chunked transfer).
+ * Implements the core `ArtifactBodyStore` contract; hosts may substitute any store.
+ *
+ * Security posture: ownership verified on every operation; size/hash/MIME verified on put
+ * and get (fail closed); delete refuses under legal hold (host `isHeld` callback) and is
+ * idempotent; credentials only via the host resolver; bucket/path/key never appear in
+ * errors, telemetry, or artifact records (the object key is derived from the ref).
+ */
+import { ArtifactBodyStoreError } from "@arnilo/prism";
+import { presignV4, sha256Hex, signRequestV4 } from "./artifact-bodies-s3.js";
+/** Phase 11 freeze: body 64 MiB/512 MiB; concurrent transfers 4/16; presign TTL 10 min/24 h; ref 256 B/1 KiB. */
+export const DEFAULT_ARTIFACT_BODY_LIMITS = {
+    maxBodyBytes: 64 * 1024 * 1024,
+    maxConcurrentTransfers: 4,
+    presignTtlMs: 10 * 60 * 1000,
+    maxRefBytes: 256,
+};
+export const HARD_ARTIFACT_BODY_LIMITS = {
+    maxBodyBytes: 512 * 1024 * 1024,
+    maxConcurrentTransfers: 16,
+    presignTtlMs: 24 * 3600 * 1000,
+    maxRefBytes: 1024,
+};
+export function resolveArtifactBodyLimits(input = {}) {
+    const resolved = {
+        maxBodyBytes: DEFAULT_ARTIFACT_BODY_LIMITS.maxBodyBytes,
+        maxConcurrentTransfers: DEFAULT_ARTIFACT_BODY_LIMITS.maxConcurrentTransfers,
+        presignTtlMs: DEFAULT_ARTIFACT_BODY_LIMITS.presignTtlMs,
+        maxRefBytes: DEFAULT_ARTIFACT_BODY_LIMITS.maxRefBytes,
+    };
+    for (const key of Object.keys(DEFAULT_ARTIFACT_BODY_LIMITS)) {
+        const value = input[key];
+        if (value === undefined)
+            continue;
+        if (!Number.isSafeInteger(value) || value < 1 || value > HARD_ARTIFACT_BODY_LIMITS[key]) {
+            throw new ArtifactBodyStoreError(`${key} must be a positive safe integer at or below the hard cap`, "STORE");
+        }
+        resolved[key] = value;
+    }
+    return resolved;
+}
+/** Typed S3 adapter failure; `code` is one of the frozen ERR_PRISM_S3_* codes. */
+export class S3ArtifactBodyError extends Error {
+    reason;
+    code;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "S3ArtifactBodyError";
+        this.code = `ERR_PRISM_S3_${reason}`;
+    }
+}
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const HASH_PATTERN = /^[0-9a-f]{64}$/i;
+const BUCKET_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/;
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+/** Deterministic object key derived from the ref; bucket/path/key never enter artifact records. */
+export function s3ObjectKey(ref) {
+    return `prism-artifacts/${ref.tenantId}/${ref.threadId}/${ref.artifactId}/${ref.version}`;
+}
+function validateRef(ref, limits) {
+    if (![ref.tenantId, ref.accountId, ref.userId].some((v) => typeof v === "string" && v.length > 0)) {
+        throw new ArtifactBodyStoreError("Ownership is required on every body reference", "OWNERSHIP");
+    }
+    for (const [name, value] of [
+        ["threadId", ref.threadId],
+        ["artifactId", ref.artifactId],
+    ]) {
+        if (typeof value !== "string" || value.length === 0 || value.length > 128 || !ID_PATTERN.test(value)) {
+            throw new ArtifactBodyStoreError(`${name} is invalid`, "STORE");
+        }
+    }
+    if (!Number.isSafeInteger(ref.version) || ref.version < 1) {
+        throw new ArtifactBodyStoreError("version must be a positive safe integer", "STORE");
+    }
+    if (!Number.isSafeInteger(ref.size) || ref.size < 0 || ref.size > limits.maxBodyBytes) {
+        throw new ArtifactBodyStoreError("size must be a non-negative safe integer at or below maxBodyBytes", "STORE");
+    }
+    if (typeof ref.hash !== "string" || !HASH_PATTERN.test(ref.hash)) {
+        throw new ArtifactBodyStoreError("hash must be a 64-char SHA-256 hex digest", "STORE");
+    }
+    if (typeof ref.mime !== "string" || ref.mime.length === 0 || Buffer.byteLength(ref.mime, "utf8") > 512) {
+        throw new ArtifactBodyStoreError("mime must be a non-empty string at or below 512 bytes", "STORE");
+    }
+    if (Buffer.byteLength(JSON.stringify(ref), "utf8") > limits.maxRefBytes) {
+        throw new ArtifactBodyStoreError("body reference exceeds maxRefBytes", "STORE");
+    }
+}
+function validateEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new ArtifactBodyStoreError("endpoint must be an absolute URL", "STORE");
+    }
+    const loopback = LOOPBACK.has(url.hostname);
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+        throw new ArtifactBodyStoreError("endpoint must be https (http only for loopback hosts)", "STORE");
+    }
+    if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") {
+        throw new ArtifactBodyStoreError("endpoint must not carry credentials, query, or fragment", "STORE");
+    }
+    return url;
+}
+async function readBoundedStream(stream, maxBytes) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new ArtifactBodyStoreError("body exceeds maxBodyBytes", "SIZE_MISMATCH");
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+function createSemaphore(max) {
+    let active = 0;
+    const waiters = [];
+    return {
+        async run(fn) {
+            if (active >= max)
+                await new Promise((resolve) => waiters.push(resolve));
+            active += 1;
+            try {
+                return await fn();
+            }
+            finally {
+                active -= 1;
+                waiters.shift()?.();
+            }
+        },
+    };
+}
+/** Reference S3-compatible ArtifactBodyStore (AWS S3, MinIO, Cloudflare R2). */
+export function createS3ArtifactBodyStore(options) {
+    const limits = resolveArtifactBodyLimits(options.limits);
+    const base = validateEndpoint(options.endpoint);
+    if (typeof options.bucket !== "string" || !BUCKET_PATTERN.test(options.bucket)) {
+        throw new ArtifactBodyStoreError("bucket must match [A-Za-z0-9][A-Za-z0-9._-]{0,62}", "STORE");
+    }
+    const region = options.region ?? "us-east-1";
+    if (typeof region !== "string" || region.length === 0 || region.length > 64) {
+        throw new ArtifactBodyStoreError("region must be a non-empty string at or below 64 bytes", "STORE");
+    }
+    const fetchImpl = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    const semaphore = createSemaphore(limits.maxConcurrentTransfers);
+    async function resolveCredentials() {
+        let credentials;
+        try {
+            credentials = await options.credentials();
+        }
+        catch (error) {
+            throw new S3ArtifactBodyError(`credential resolution failed: ${error instanceof Error ? error.message : "unknown error"}`, "CREDENTIALS");
+        }
+        if (typeof credentials?.accessKeyId !== "string" ||
+            credentials.accessKeyId.length === 0 ||
+            typeof credentials?.secretAccessKey !== "string" ||
+            credentials.secretAccessKey.length === 0) {
+            throw new S3ArtifactBodyError("credentials must provide non-empty accessKeyId and secretAccessKey", "CREDENTIALS");
+        }
+        return credentials;
+    }
+    function amzDate() {
+        return new Date(now())
+            .toISOString()
+            .replace(/[-:]/g, "")
+            .replace(/\.\d{3}/, "");
+    }
+    function objectPath(ref) {
+        return `/${options.bucket}/${s3ObjectKey(ref)
+            .split("/")
+            .map((segment) => encodeURIComponent(segment))
+            .join("/")}`;
+    }
+    async function presignGet(ref, ttlMs, signal) {
+        const credentials = await resolveCredentials();
+        const date = amzDate();
+        const expiresSeconds = Math.ceil(ttlMs / 1000);
+        let query;
+        try {
+            query = await presignV4({
+                method: "GET",
+                path: objectPath(ref),
+                headers: { host: base.host },
+                payloadHash: "UNSIGNED-PAYLOAD",
+                region,
+                service: "s3",
+                amzDate: date,
+                expiresSeconds,
+                accessKeyId: credentials.accessKeyId,
+                secretAccessKey: credentials.secretAccessKey,
+                ...(credentials.sessionToken === undefined ? {} : { sessionToken: credentials.sessionToken }),
+            });
+        }
+        catch (error) {
+            throw new S3ArtifactBodyError(`presign failed: ${error instanceof Error ? error.message : "unknown error"}`, "PRESIGN");
+        }
+        signal?.throwIfAborted();
+        return `${base.origin}${objectPath(ref)}?${query}`;
+    }
+    return {
+        async put(ref, body, transferOptions) {
+            validateRef(ref, limits);
+            const bytes = body instanceof Uint8Array ? body : await readBoundedStream(body, limits.maxBodyBytes);
+            if (bytes.byteLength > limits.maxBodyBytes) {
+                throw new ArtifactBodyStoreError("body exceeds maxBodyBytes", "SIZE_MISMATCH");
+            }
+            if (bytes.byteLength !== ref.size) {
+                throw new ArtifactBodyStoreError(`body size ${bytes.byteLength} does not match ref size ${ref.size}`, "SIZE_MISMATCH");
+            }
+            const hash = await sha256Hex(bytes);
+            if (hash !== ref.hash.toLowerCase()) {
+                throw new ArtifactBodyStoreError("body SHA-256 does not match the reference hash", "HASH_MISMATCH");
+            }
+            const payload = options.kms ? await options.kms("encrypt", bytes) : bytes;
+            const payloadHash = await sha256Hex(payload);
+            const credentials = await resolveCredentials();
+            const date = amzDate();
+            const path = objectPath(ref);
+            const headers = {
+                host: base.host,
+                "content-type": ref.mime,
+                "x-amz-content-sha256": payloadHash,
+            };
+            const signed = await signRequestV4({
+                method: "PUT",
+                path,
+                headers,
+                signedHeaders: ["host", "content-type", "x-amz-content-sha256"],
+                payloadHash,
+                region,
+                service: "s3",
+                amzDate: date,
+                accessKeyId: credentials.accessKeyId,
+                secretAccessKey: credentials.secretAccessKey,
+                ...(credentials.sessionToken === undefined ? {} : { sessionToken: credentials.sessionToken }),
+            });
+            try {
+                await semaphore.run(async () => {
+                    // host is signed but not sent explicitly: fetch sets it from the URL.
+                    const requestHeaders = { ...signed.headers };
+                    delete requestHeaders.host;
+                    const response = await fetchImpl(`${base.origin}${path}`, {
+                        method: "PUT",
+                        headers: requestHeaders,
+                        body: payload,
+                        ...(transferOptions?.signal === undefined ? {} : { signal: transferOptions.signal }),
+                    });
+                    if (!response.ok) {
+                        throw new S3ArtifactBodyError(`upload failed with HTTP ${response.status}`, "UPLOAD");
+                    }
+                });
+            }
+            catch (error) {
+                if (error instanceof S3ArtifactBodyError)
+                    throw error;
+                throw new S3ArtifactBodyError(`upload failed: ${error instanceof Error ? error.message : "unknown error"}`, "UPLOAD");
+            }
+        },
+        async get(ref, transferOptions) {
+            validateRef(ref, limits);
+            const url = await presignGet(ref, limits.presignTtlMs, transferOptions?.signal);
+            let response;
+            try {
+                response = await semaphore.run(async () => fetchImpl(url, { method: "GET", ...(transferOptions?.signal === undefined ? {} : { signal: transferOptions.signal }) }));
+            }
+            catch (error) {
+                throw new S3ArtifactBodyError(`download failed: ${error instanceof Error ? error.message : "unknown error"}`, "DOWNLOAD");
+            }
+            if (!response.ok)
+                throw new S3ArtifactBodyError(`download failed with HTTP ${response.status}`, "DOWNLOAD");
+            // Fast-fail size/MIME checks (skipped for the stored size when kms is set: the stored
+            // bytes are ciphertext, so size is verified on the decrypted plaintext below).
+            if (!options.kms) {
+                const contentLength = response.headers.get("content-length");
+                if (contentLength === null || Number(contentLength) !== ref.size) {
+                    throw new ArtifactBodyStoreError("download size does not match the reference size", "SIZE_MISMATCH");
+                }
+                const contentType = response.headers.get("content-type");
+                if (contentType === null || contentType !== ref.mime) {
+                    throw new ArtifactBodyStoreError("download MIME type does not match the reference MIME", "MIME_MISMATCH");
+                }
+            }
+            let bytes;
+            try {
+                bytes = await readBoundedStream(response.body ?? new ReadableStream(), limits.maxBodyBytes);
+            }
+            catch (error) {
+                if (error instanceof ArtifactBodyStoreError)
+                    throw error;
+                throw new S3ArtifactBodyError(`download failed: ${error instanceof Error ? error.message : "unknown error"}`, "DOWNLOAD");
+            }
+            if (!options.kms && bytes.byteLength !== ref.size) {
+                throw new ArtifactBodyStoreError(`download size ${bytes.byteLength} does not match ref size ${ref.size}`, "SIZE_MISMATCH");
+            }
+            const plaintext = options.kms ? await options.kms("decrypt", bytes) : bytes;
+            if (plaintext.byteLength !== ref.size) {
+                throw new ArtifactBodyStoreError(`download size ${plaintext.byteLength} does not match ref size ${ref.size}`, "SIZE_MISMATCH");
+            }
+            const hash = await sha256Hex(plaintext);
+            if (hash !== ref.hash.toLowerCase()) {
+                throw new ArtifactBodyStoreError("download SHA-256 does not match the reference hash", "HASH_MISMATCH");
+            }
+            return new ReadableStream({
+                start(controller) {
+                    controller.enqueue(plaintext);
+                    controller.close();
+                },
+            });
+        },
+        async delete(ref, transferOptions) {
+            validateRef(ref, limits);
+            if (options.isHeld) {
+                let held;
+                try {
+                    held = await options.isHeld(ref);
+                }
+                catch (error) {
+                    throw new ArtifactBodyStoreError(`hold check failed: ${error instanceof Error ? error.message : "unknown error"}`, "STORE");
+                }
+                if (held)
+                    throw new ArtifactBodyStoreError("delete refused: resource is under legal hold", "HELD");
+            }
+            const credentials = await resolveCredentials();
+            const date = amzDate();
+            const path = objectPath(ref);
+            let query;
+            try {
+                query = await presignV4({
+                    method: "DELETE",
+                    path,
+                    headers: { host: base.host },
+                    payloadHash: "UNSIGNED-PAYLOAD",
+                    region,
+                    service: "s3",
+                    amzDate: date,
+                    expiresSeconds: Math.ceil(limits.presignTtlMs / 1000),
+                    accessKeyId: credentials.accessKeyId,
+                    secretAccessKey: credentials.secretAccessKey,
+                    ...(credentials.sessionToken === undefined ? {} : { sessionToken: credentials.sessionToken }),
+                });
+            }
+            catch (error) {
+                throw new S3ArtifactBodyError(`presign failed: ${error instanceof Error ? error.message : "unknown error"}`, "PRESIGN");
+            }
+            try {
+                await semaphore.run(async () => {
+                    const response = await fetchImpl(`${base.origin}${path}?${query}`, {
+                        method: "DELETE",
+                        ...(transferOptions?.signal === undefined ? {} : { signal: transferOptions.signal }),
+                    });
+                    // 204 and 404 are both success: body delete is idempotent.
+                    if (response.status !== 204 && response.status !== 404) {
+                        throw new S3ArtifactBodyError(`delete failed with HTTP ${response.status}`, "DELETE");
+                    }
+                });
+            }
+            catch (error) {
+                if (error instanceof S3ArtifactBodyError)
+                    throw error;
+                throw new S3ArtifactBodyError(`delete failed: ${error instanceof Error ? error.message : "unknown error"}`, "DELETE");
+            }
+        },
+        async presign(ref, presignOptions) {
+            validateRef(ref, limits);
+            const ttlMs = presignOptions?.ttlMs ?? limits.presignTtlMs;
+            if (!Number.isSafeInteger(ttlMs) || ttlMs < 1 || ttlMs > limits.presignTtlMs) {
+                throw new ArtifactBodyStoreError("presign TTL must be a positive safe integer at or below presignTtlMs", "STORE");
+            }
+            return presignGet(ref, ttlMs, presignOptions?.signal);
+        },
+    };
+}
+//# sourceMappingURL=artifact-bodies.js.map

package/dist/artifacts.d.ts

@@ -1,4 +1,4 @@
-import { type AgentIdentity, type ArtifactCitation, type ArtifactDeliveryToken, type ArtifactRecord, type ArtifactRevision, type CheckpointStore, type OwnershipScope, type PersistencePage, type SecretRedactor } from "@arnilo/prism";
+import { type AgentIdentity, type ArtifactBodyStore, type ArtifactCitation, type ArtifactDeliveryToken, type ArtifactRecord, type ArtifactRevision, type CheckpointStore, type OwnershipScope, type PersistencePage, type SecretRedactor } from "@arnilo/prism";
 import type { PrismRequestHandler, PrismServerAuthorization } from "./types.js";
 /** Phase 9 freeze: artifacts/thread 64/256; revisions 32/128; record 8/64 KiB; preview 16/64 KiB;
  *  citations 32/128 and 2/8 KiB each; mime 128/512 B; hash 256/1 KiB; delivery TTL 5 min/24 h;
@@ -78,6 +78,8 @@ export interface ArtifactAttachInput extends ArtifactServiceInput {
     readonly uri: string;
     readonly mime: string;
     readonly hash: string;
+    /** Expected body byte length; required when a blob store is wired for delivery. */
+    readonly size?: number;
     /** Explicit id makes attach idempotent (get-or-create). Generated when omitted. */
     readonly id?: string;
     readonly title?: string;
@@ -100,6 +102,8 @@ export interface ArtifactReviseInput extends ArtifactRefInput {
     /** Defaults to the previous revision's mime when omitted. */
     readonly mime?: string;
     readonly hash: string;
+    /** Expected body byte length; required when a blob store is wired for delivery. */
+    readonly size?: number;
     readonly changeNote?: string;
     readonly producerRunId?: string;
     readonly citations?: readonly ArtifactCitation[];
@@ -135,6 +139,8 @@ export interface ArtifactDeliveryInput extends ArtifactRefInput {
 export interface ArtifactDeliveryResult {
     readonly link: string;
     readonly token: ArtifactDeliveryToken;
+    /** Presigned blob-store delivery URL; present only when a body store is wired. */
+    readonly url?: string;
 }
 export type ArtifactDecisionEvent = {
     readonly type: "artifact_attached" | "artifact_revised";
@@ -157,6 +163,8 @@ export interface CreateArtifactServiceOptions {
     /** Host HMAC key material for signing/verifying delivery links. */
     readonly linkSecret: string;
     readonly limits?: ArtifactLimits;
+    /** Optional blob store: delivery links then resolve through `bodies.presign`. */
+    readonly bodies?: ArtifactBodyStore;
     /** Audit seam (redacted refs only); hosts bridge to @arnilo/prism-policy. */
     readonly onDecision?: (event: ArtifactDecisionEvent) => void | Promise<void>;
 }

package/dist/artifacts.js

@@ -119,6 +119,9 @@ export function createArtifactService(store, options) {
         const uri = assertSafeUri(input.uri, limits.uriBytes);
         assertBounded(input.mime, limits.mimeBytes, "mime_too_large");
         assertBounded(input.hash, limits.hashBytes, "hash_too_large");
+        if (input.size !== undefined && (!Number.isSafeInteger(input.size) || input.size < 0)) {
+            throw new ArtifactError("size is invalid", "invalid_input");
+        }
         if (input.changeNote !== undefined)
             assertBounded(input.changeNote, limits.noteBytes, "change_note_too_large");
         if (input.producerRunId !== undefined)
@@ -130,6 +133,7 @@ export function createArtifactService(store, options) {
             uri,
             mime: input.mime,
             hash: input.hash,
+            ...(input.size === undefined ? {} : { size: input.size }),
             ...(input.changeNote === undefined ? {} : { changeNote: input.changeNote }),
             ...(input.producerRunId === undefined ? {} : { producerRunId: input.producerRunId }),
             ...(citations === undefined ? {} : { citations }),
@@ -278,9 +282,9 @@ export function createArtifactService(store, options) {
             const version = input.version ?? record.lastValidatedVersion ?? latest?.version;
             if (version === undefined)
                 throw new ArtifactError("Artifact has no revisions", "invalid_input");
-            if (!record.revisions.some((revision) => revision.version === version)) {
+            const revision = record.revisions.find((item) => item.version === version);
+            if (!revision)
                 throw new ArtifactError("Revision not found", "not_found");
-            }
             const ttlSeconds = bounded(input.ttlSeconds, limits.deliveryLinkTtlSeconds, limits.deliveryLinkTtlSeconds, "ttlSeconds");
             const now = Date.now();
             const token = {
@@ -291,7 +295,31 @@ export function createArtifactService(store, options) {
                 issuedAt: new Date(now).toISOString(),
                 expiresAt: new Date(now + ttlSeconds * 1000).toISOString(),
             };
-            return { link: signArtifactDeliveryLink(token, options.linkSecret), token };
+            const result = { link: signArtifactDeliveryLink(token, options.linkSecret), token };
+            if (options.bodies) {
+                // Delivery resolves through the blob store: presign the exact revision's body.
+                // A revision without a recorded size cannot be addressed; fail closed.
+                if (revision.size === undefined) {
+                    throw new ArtifactError("Revision has no recorded size; cannot resolve a body reference", "invalid_input");
+                }
+                const ref = {
+                    artifactId: record.id,
+                    threadId: input.threadId,
+                    version,
+                    mime: revision.mime,
+                    size: revision.size,
+                    // Artifact hashes conventionally carry a `sha256:` prefix; the body
+                    // ref contract is bare 64-char hex, so normalize before addressing.
+                    hash: revision.hash.startsWith("sha256:") ? revision.hash.slice("sha256:".length) : revision.hash,
+                    ...input.ownership,
+                };
+                const url = await options.bodies.presign(ref, {
+                    ttlMs: ttlSeconds * 1000,
+                    ...(input.signal === undefined ? {} : { signal: input.signal }),
+                });
+                return { ...result, url };
+            }
+            return result;
         },
     };
     async function decide(input, state) {
@@ -435,6 +463,7 @@ export function createArtifactHandler(options) {
                         uri: readString(body.uri, "uri"),
                         mime: readString(body.mime, "mime"),
                         hash: readString(body.hash, "hash"),
+                        ...(body.size === undefined ? {} : { size: readNonNegativeInt(String(body.size), "size") }),
                         ...(body.id === undefined ? {} : { id: readString(body.id, "id") }),
                         ...(body.title === undefined ? {} : { title: readString(body.title, "title") }),
                         ...(body.changeNote === undefined ? {} : { changeNote: readString(body.changeNote, "changeNote") }),
@@ -464,6 +493,7 @@ export function createArtifactHandler(options) {
                         artifactId: route.artifactId,
                         uri: readString(body.uri, "uri"),
                         hash: readString(body.hash, "hash"),
+                        ...(body.size === undefined ? {} : { size: readNonNegativeInt(String(body.size), "size") }),
                         ...(body.mime === undefined ? {} : { mime: readString(body.mime, "mime") }),
                         ...(body.changeNote === undefined ? {} : { changeNote: readString(body.changeNote, "changeNote") }),
                         ...(body.producerRunId === undefined ? {} : { producerRunId: readString(body.producerRunId, "producerRunId") }),
@@ -745,4 +775,10 @@ function readPositiveInt(value, name) {
         throw new PrismServerError(`${name} must be a positive safe integer`, 400, "ERR_PRISM_SERVER_INPUT");
     return parsed;
 }
+function readNonNegativeInt(value, name) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        throw new PrismServerError(`${name} must be a non-negative safe integer`, 400, "ERR_PRISM_SERVER_INPUT");
+    return parsed;
+}
 //# sourceMappingURL=artifacts.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism-server",
-  "version": "0.0.27",
+  "version": "0.1.0",
   "description": "Optional framework-free Web Request-to-Response handler for explicitly selected Prism agents and workflows.",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./artifact-bodies": {
+      "types": "./dist/artifact-bodies.d.ts",
+      "default": "./dist/artifact-bodies.js"
     }
   },
   "files": [
@@ -25,8 +29,8 @@
     "pack:dry-run": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "@arnilo/prism": "0.0.27",
-    "@arnilo/prism-workflows": "0.0.27"
+    "@arnilo/prism": "0.1.0",
+    "@arnilo/prism-workflows": "0.1.0"
   },
   "devDependencies": {
     "@arnilo/prism": "file:../..",