@arnilo/prism-server 0.0.96 → 0.1.1

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

@@ -0,0 +1,207 @@
+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;
+ *  delivery token 4/16 KiB. Compare is exactly 2 revisions (hash+metadata only; host renders content). */
+export declare const DEFAULT_ARTIFACTS_PER_THREAD = 64;
+export declare const HARD_ARTIFACTS_PER_THREAD = 256;
+export declare const DEFAULT_ARTIFACT_REVISIONS = 32;
+export declare const HARD_ARTIFACT_REVISIONS = 128;
+export declare const DEFAULT_ARTIFACT_RECORD_BYTES: number;
+export declare const HARD_ARTIFACT_RECORD_BYTES: number;
+export declare const DEFAULT_ARTIFACT_PREVIEW_BYTES: number;
+export declare const HARD_ARTIFACT_PREVIEW_BYTES: number;
+export declare const DEFAULT_ARTIFACT_CITATIONS = 32;
+export declare const HARD_ARTIFACT_CITATIONS = 128;
+export declare const DEFAULT_ARTIFACT_CITATION_BYTES: number;
+export declare const HARD_ARTIFACT_CITATION_BYTES: number;
+export declare const DEFAULT_ARTIFACT_MIME_BYTES = 128;
+export declare const HARD_ARTIFACT_MIME_BYTES = 512;
+export declare const DEFAULT_ARTIFACT_HASH_BYTES = 256;
+export declare const HARD_ARTIFACT_HASH_BYTES = 1024;
+export declare const DEFAULT_ARTIFACT_URI_BYTES: number;
+export declare const HARD_ARTIFACT_URI_BYTES: number;
+export declare const DEFAULT_ARTIFACT_NOTE_BYTES = 1024;
+export declare const HARD_ARTIFACT_NOTE_BYTES: number;
+export declare const DEFAULT_ARTIFACT_TITLE_BYTES = 256;
+export declare const HARD_ARTIFACT_TITLE_BYTES: number;
+export declare const DEFAULT_ARTIFACT_LIST_PAGE_LIMIT = 50;
+export declare const HARD_ARTIFACT_LIST_PAGE_LIMIT = 200;
+export declare const DEFAULT_DELIVERY_LINK_TTL_SECONDS = 300;
+export declare const HARD_DELIVERY_LINK_TTL_SECONDS: number;
+export declare const DEFAULT_DELIVERY_LINK_TOKEN_BYTES: number;
+export declare const HARD_DELIVERY_LINK_TOKEN_BYTES: number;
+export declare const DEFAULT_ARTIFACT_REQUEST_BYTES: number;
+export declare const HARD_ARTIFACT_REQUEST_BYTES: number;
+export interface ArtifactLimits {
+    readonly artifactsPerThread?: number;
+    readonly revisionsPerArtifact?: number;
+    readonly recordBytes?: number;
+    readonly previewBytes?: number;
+    readonly citations?: number;
+    readonly citationBytes?: number;
+    readonly mimeBytes?: number;
+    readonly hashBytes?: number;
+    readonly uriBytes?: number;
+    readonly noteBytes?: number;
+    readonly titleBytes?: number;
+    readonly listPageLimit?: number;
+    readonly deliveryLinkTtlSeconds?: number;
+    readonly deliveryLinkTokenBytes?: number;
+    readonly maxRequestBytes?: number;
+}
+export interface ResolvedArtifactLimits {
+    readonly artifactsPerThread: number;
+    readonly revisionsPerArtifact: number;
+    readonly recordBytes: number;
+    readonly previewBytes: number;
+    readonly citations: number;
+    readonly citationBytes: number;
+    readonly mimeBytes: number;
+    readonly hashBytes: number;
+    readonly uriBytes: number;
+    readonly noteBytes: number;
+    readonly titleBytes: number;
+    readonly listPageLimit: number;
+    readonly deliveryLinkTtlSeconds: number;
+    readonly deliveryLinkTokenBytes: number;
+    readonly maxRequestBytes: number;
+}
+export declare function resolveArtifactLimits(input?: ArtifactLimits): ResolvedArtifactLimits;
+export interface ArtifactServiceInput {
+    readonly ownership: OwnershipScope;
+    readonly identity?: AgentIdentity;
+    readonly signal?: AbortSignal;
+}
+export interface ArtifactAttachInput extends ArtifactServiceInput {
+    readonly threadId: string;
+    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;
+    readonly changeNote?: string;
+    readonly producerRunId?: string;
+    readonly citations?: readonly ArtifactCitation[];
+    readonly preview?: Readonly<Record<string, unknown>>;
+}
+export interface ArtifactListInput extends ArtifactServiceInput {
+    readonly threadId: string;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface ArtifactRefInput extends ArtifactServiceInput {
+    readonly threadId: string;
+    readonly artifactId: string;
+}
+export interface ArtifactReviseInput extends ArtifactRefInput {
+    readonly uri: string;
+    /** 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[];
+    readonly preview?: Readonly<Record<string, unknown>>;
+}
+export interface ArtifactCompareInput extends ArtifactRefInput {
+    readonly from: number;
+    readonly to: number;
+}
+export interface ArtifactCompareResult {
+    readonly artifactId: string;
+    readonly from: ArtifactRevision;
+    readonly to: ArtifactRevision;
+    /** Hash+metadata-bounded change flags; the host renders content bodies. */
+    readonly changed: {
+        readonly hash: boolean;
+        readonly mime: boolean;
+        readonly uri: boolean;
+        readonly citations: boolean;
+    };
+}
+export interface ArtifactDecisionInput extends ArtifactRefInput {
+    readonly version: number;
+    readonly note?: string;
+    /** Redacted reviewer ref; derived from identity when omitted. */
+    readonly reviewer?: string;
+}
+export interface ArtifactDeliveryInput extends ArtifactRefInput {
+    /** Defaults to the last validated revision, else the latest. */
+    readonly version?: number;
+    readonly ttlSeconds?: number;
+}
+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";
+    readonly artifactId: string;
+    readonly threadId: string;
+    readonly version: number;
+    readonly actor?: string;
+    readonly timestamp: string;
+} | {
+    readonly type: "artifact_approved" | "artifact_rejected";
+    readonly artifactId: string;
+    readonly threadId: string;
+    readonly version: number;
+    readonly reviewer: string;
+    readonly timestamp: string;
+};
+export interface CreateArtifactServiceOptions {
+    /** Required: records are redacted before persist and on every response. */
+    readonly redactor: SecretRedactor;
+    /** 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>;
+}
+export interface ArtifactService {
+    attach(input: ArtifactAttachInput): Promise<ArtifactRecord>;
+    list(input: ArtifactListInput): Promise<PersistencePage<ArtifactRecord>>;
+    get(input: ArtifactRefInput): Promise<ArtifactRecord>;
+    revise(input: ArtifactReviseInput): Promise<ArtifactRecord>;
+    compare(input: ArtifactCompareInput): Promise<ArtifactCompareResult>;
+    approve(input: ArtifactDecisionInput): Promise<ArtifactRecord>;
+    reject(input: ArtifactDecisionInput): Promise<ArtifactRecord>;
+    lastValidated(input: ArtifactRefInput): Promise<ArtifactRevision>;
+    deliveryLink(input: ArtifactDeliveryInput): Promise<ArtifactDeliveryResult>;
+}
+export declare function createArtifactService(store: CheckpointStore, options: CreateArtifactServiceOptions): ArtifactService;
+/** Sign an expiring delivery token: base64url(payload).base64url(HMAC-SHA256). */
+export declare function signArtifactDeliveryLink(token: ArtifactDeliveryToken, secret: string): string;
+/** Verify signature + expiry and parse a delivery link. Fail-closed on any tamper/expiry. */
+export declare function verifyArtifactDeliveryLink(link: string, secret: string, maxBytes?: number): ArtifactDeliveryToken;
+export type ArtifactOperation = "artifact.attach" | "artifact.list" | "artifact.get" | "artifact.revise" | "artifact.compare" | "artifact.approve" | "artifact.reject" | "artifact.last-validated" | "artifact.delivery-link" | "artifact.download";
+export interface ArtifactAuthorizationInput {
+    readonly request: Request;
+    readonly operation: ArtifactOperation;
+    readonly threadId?: string;
+    readonly artifactId?: string;
+    /** Present for download: the verified delivery token to reauthorize against. */
+    readonly deliveryToken?: ArtifactDeliveryToken;
+    readonly signal: AbortSignal;
+}
+export type ArtifactAuthorizer = (input: ArtifactAuthorizationInput) => false | PrismServerAuthorization | Promise<false | PrismServerAuthorization>;
+export interface CreateArtifactHandlerOptions {
+    readonly service: ArtifactService;
+    readonly authorize: ArtifactAuthorizer;
+    readonly linkSecret: string;
+    readonly basePath?: string;
+    readonly redactor?: SecretRedactor;
+    readonly limits?: ArtifactLimits;
+}
+/** Framework-free HTTP adapter for one mounted artifact service (default base `/prism/artifacts`). */
+export declare function createArtifactHandler(options: CreateArtifactHandlerOptions): PrismRequestHandler;