@segmentstream-cloud/ontology 0.25.1 → 0.26.1

package/dist/service/member-files.d.ts

@@ -0,0 +1,165 @@
+import { Effect, Schema } from "effect";
+import { CurrentPrincipal } from "./authentication.js";
+import { RequestId } from "./errors.js";
+import type { Operations } from "./operations.js";
+import type { ApiPlan } from "./plan.js";
+import type { OntologyBackend } from "./runtime-contract.js";
+export declare const AttachmentFilters: Schema.Struct<{
+    readonly conversation: Schema.optionalKey<Schema.String>;
+    readonly sender_id: Schema.optionalKey<Schema.String>;
+    readonly from: Schema.optionalKey<Schema.String>;
+    readonly to: Schema.optionalKey<Schema.String>;
+    readonly before: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export declare const MEMBER_FILE_SCHEMAS: {
+    "attachments-list": Schema.Struct<{
+        readonly conversation: Schema.optionalKey<Schema.String>;
+        readonly sender_id: Schema.optionalKey<Schema.String>;
+        readonly from: Schema.optionalKey<Schema.String>;
+        readonly to: Schema.optionalKey<Schema.String>;
+        readonly before: Schema.optionalKey<Schema.String>;
+        readonly limit: Schema.optionalKey<Schema.Int>;
+    }>;
+    "attachments-get": Schema.Struct<{
+        readonly id: Schema.String;
+    }>;
+    "attachments-download": Schema.Struct<{
+        readonly id: Schema.String;
+    }>;
+    "attachments-promote": Schema.Struct<{
+        readonly id: Schema.String;
+        readonly entity: Schema.String;
+        readonly action: Schema.String;
+        readonly input: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+        readonly field: Schema.optionalKey<Schema.String>;
+        readonly record_id: Schema.optionalKey<Schema.String>;
+    }>;
+    "files-download": Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+        readonly property: Schema.optionalKey<Schema.String>;
+    }>;
+};
+export type MemberFileOperation = keyof typeof MEMBER_FILE_SCHEMAS;
+export declare function grantForWire(grant: {
+    url: string;
+    method: string;
+    headers: Readonly<Record<string, string>>;
+    expiresAt: string;
+}): {
+    url: string;
+    method: string;
+    headers: Readonly<Record<string, string>>;
+    expires_at: string;
+};
+export declare function attachmentForWire(attachment: import("../storage/attachments.js").AttachmentView): {
+    id: string;
+    filename: string;
+    content_type: string;
+    size: number;
+    sha256: string;
+    state: string;
+    created_at: string;
+    expires_at: string;
+    promotion: unknown;
+    conversation: string | undefined;
+    sender_id: string | undefined;
+};
+/** The member REST and MCP surfaces run the same runtime operations and action pipeline. */
+export declare function memberFileOperations(backend: OntologyBackend["Service"], plan: ApiPlan, operations: Operations): (kind: MemberFileOperation, args: unknown, identityToken?: string) => Effect.Effect<{
+    download: {
+        url: string;
+        method: string;
+        headers: Readonly<Record<string, string>>;
+        expires_at: string;
+    };
+    file: {
+        id: string;
+        entity: string;
+        property: string;
+        revision_id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+    };
+    attachments?: undefined;
+    nextCursor?: undefined;
+    attachment?: undefined;
+} | {
+    attachments: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    }[];
+    nextCursor: string | null;
+    attachment?: undefined;
+    download?: undefined;
+} | {
+    attachment: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    };
+    deduplicated: boolean;
+    result: {} | null;
+    attachments?: undefined;
+    nextCursor?: undefined;
+    download?: undefined;
+} | {
+    attachment: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    };
+    attachments?: undefined;
+    nextCursor?: undefined;
+    download?: undefined;
+} | {
+    attachment: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    };
+    download: {
+        url: string;
+        method: string;
+        headers: Readonly<Record<string, string>>;
+        expires_at: string;
+    };
+    attachments?: undefined;
+    nextCursor?: undefined;
+}, unknown, RequestId | CurrentPrincipal>;

package/dist/service/member-files.js

@@ -0,0 +1,145 @@
+import { Effect, Schema } from "effect";
+import { NotFound } from "../errors.js";
+import { schemaIssues } from "../runtime/validation.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { InvalidRequestBody, RequestId } from "./errors.js";
+const Id = Schema.String.check(Schema.isUUID());
+const DateTime = Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/));
+export const AttachmentFilters = Schema.Struct({
+    conversation: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(200))),
+    sender_id: Schema.optionalKey(Id),
+    from: Schema.optionalKey(DateTime),
+    to: Schema.optionalKey(DateTime),
+    before: Schema.optionalKey(Id),
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 200 }))),
+});
+const AttachmentId = Schema.Struct({ id: Id });
+const Promotion = Schema.Struct({
+    id: Id,
+    entity: Schema.String,
+    action: Schema.String,
+    input: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown)),
+    field: Schema.optionalKey(Schema.String),
+    record_id: Schema.optionalKey(Id),
+});
+const File = Schema.Struct({
+    entity: Schema.String,
+    id: Id,
+    property: Schema.optionalKey(Schema.String),
+});
+export const MEMBER_FILE_SCHEMAS = {
+    "attachments-list": AttachmentFilters,
+    "attachments-get": AttachmentId,
+    "attachments-download": AttachmentId,
+    "attachments-promote": Promotion,
+    "files-download": File,
+};
+export function grantForWire(grant) {
+    return {
+        url: grant.url,
+        method: grant.method,
+        headers: grant.headers,
+        expires_at: grant.expiresAt,
+    };
+}
+export function attachmentForWire(attachment) {
+    return {
+        id: attachment.id,
+        filename: attachment.filename,
+        content_type: attachment.contentType,
+        size: attachment.size,
+        sha256: attachment.sha256,
+        state: attachment.state,
+        created_at: attachment.createdAt,
+        expires_at: attachment.expiresAt,
+        promotion: attachment.promotion,
+        conversation: attachment.conversation,
+        sender_id: attachment.senderId,
+    };
+}
+function decode(schema, input) {
+    return Schema.decodeUnknownEffect(schema)(input, { onExcessProperty: "error" }).pipe(Effect.mapError((error) => new InvalidRequestBody({ reason: "invalid_request", issues: schemaIssues(error) })));
+}
+/** The member REST and MCP surfaces run the same runtime operations and action pipeline. */
+export function memberFileOperations(backend, plan, operations) {
+    return (kind, args, identityToken) => Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        const requestId = yield* RequestId;
+        if (kind === "files-download") {
+            const input = yield* decode(File, args);
+            if (!backend.blobs) {
+                return yield* new NotFound({
+                    entity: input.entity,
+                    id: input.id,
+                    message: "File storage is unavailable.",
+                });
+            }
+            const result = yield* backend.blobs.downloadFile(input.entity, input.id, input.property ?? "content", {}, principal);
+            return { ...result, download: grantForWire(result.download) };
+        }
+        if (principal.kind !== "member") {
+            return yield* new NotFound({
+                entity: "attachment",
+                id: "",
+                message: "Attachment not found.",
+            });
+        }
+        const attachments = backend.attachments;
+        if (!attachments) {
+            return yield* new NotFound({
+                entity: "attachment",
+                id: "",
+                message: "Attachment storage is unavailable.",
+            });
+        }
+        if (kind === "attachments-list") {
+            const input = yield* decode(AttachmentFilters, args);
+            if ((input.from !== undefined && !Number.isFinite(Date.parse(input.from))) ||
+                (input.to !== undefined && !Number.isFinite(Date.parse(input.to))) ||
+                (input.from !== undefined &&
+                    input.to !== undefined &&
+                    Date.parse(input.from) > Date.parse(input.to))) {
+                return yield* new InvalidRequestBody({ reason: "invalid_request", issues: [] });
+            }
+            const { sender_id, ...rest } = input;
+            const result = yield* attachments.listForMember({ ...rest, ...(sender_id === undefined ? {} : { senderId: sender_id }) }, principal);
+            return {
+                attachments: result.attachments.map(attachmentForWire),
+                nextCursor: result.nextCursor,
+            };
+        }
+        if (kind === "attachments-promote") {
+            const input = yield* decode(Promotion, args);
+            const promoted = yield* attachments.promoteForMember(input.id, {
+                entity: input.entity,
+                action: input.action,
+                input: input.input ?? {},
+                ...(input.field === undefined ? {} : { field: input.field }),
+                ...(input.record_id === undefined ? {} : { recordId: input.record_id }),
+            }, principal, (call) => Effect.gen(function* () {
+                const entity = plan.entities.find((item) => item.name === call.entity);
+                const action = entity?.actions.find((item) => item.name === call.action);
+                if (!entity || !action) {
+                    return yield* Effect.die(new Error("The promotion action was not planned."));
+                }
+                const answer = yield* operations.runAction(entity, action, {
+                    input: call.input,
+                    options: call.options,
+                    validateOnly: false,
+                    identityToken,
+                });
+                return { result: answer.result, edits: answer.edits };
+            }).pipe(Effect.provideService(CurrentPrincipal, principal), Effect.provideService(RequestId, requestId)));
+            return { ...promoted, attachment: attachmentForWire(promoted.attachment) };
+        }
+        const { id } = yield* decode(AttachmentId, args);
+        if (kind === "attachments-get") {
+            return { attachment: attachmentForWire(yield* attachments.getForMember(id, principal)) };
+        }
+        const result = yield* attachments.readForMember(id, principal);
+        return {
+            attachment: attachmentForWire(result.attachment),
+            download: grantForWire(result.download),
+        };
+    });
+}

package/dist/service/schemas.js

@@ -1,6 +1,7 @@
 import { BlobValue } from "../blob.js";
 import { Schema, SchemaTransformation } from "effect";
 import { wireStruct } from "../wire.js";
+import { BatchErrorDetails } from "../errors.js";
 import { AGGREGATE_FILTER_OPERATORS, ENTITY_AGGREGATE_FILTER_OPERATORS, filterValuesIssue, MAXIMUM_FILTER_VALUES, } from "../aggregate-filters.js";
 import { isValueMatched, OntologyManifestWire } from "../manifest.js";
 import { entityQuerySchemas, queryLinks } from "../query.js";
@@ -510,14 +511,17 @@ export const ErrorSchemas = {
     notFound: errorBody("NotFound", 404, ["not_found"], {
         entity: Schema.optionalKey(Schema.String),
         id: Schema.optionalKey(Schema.String),
+        batch: Schema.optionalKey(BatchErrorDetails),
     }),
     conflict: errorBody("Conflict", 409, ["conflict"], {
         entity: Schema.optionalKey(Schema.String),
         property: Schema.optionalKey(Schema.String),
+        batch: Schema.optionalKey(BatchErrorDetails),
     }),
     unsupportedMediaType: errorBody("UnsupportedMediaType", 415, ["unsupported_media_type"]),
     unprocessable: errorBody("Unprocessable", 422, ["invalid_input", "action_rejected"], {
         issues: Schema.Array(ValidationIssue),
+        batch: Schema.optionalKey(BatchErrorDetails),
     }),
     rateLimited: errorBody("RateLimited", 429, ["rate_limited"]),
     internal: errorBody("InternalError", 500, ["internal_error"]),

package/dist/service/service.js

@@ -4,6 +4,7 @@ import { HttpApiBuilder } from "effect/unstable/httpapi";
 import { storageMaintenanceAuthenticationLayer } from "../storage/maintenance-auth.js";
 import { nameToWire } from "../authoring-names.js";
 import { sqlServiceRuntime } from "../runtime/service-binding.js";
+import { memberFileRoutes } from "./member-file-routes.js";
 import { attachmentsLayer } from "./agent/attachments.js";
 import { filesLayer } from "./agent/files.js";
 import { platformConversations } from "./agent/conversations.js";
@@ -131,7 +132,15 @@ export function createOntologyService(ontology, config) {
         verifyToken,
         verifyRuntime,
     });
-    const application = Layer.mergeAll(routes, mcp, agent, attachments, filesLayer({ plan: built.plan, verifyRuntime }), conversations === undefined
+    const application = Layer.mergeAll(routes, mcp, agent, attachments, memberFileRoutes({
+        plan: built.plan,
+        hooks,
+        connections,
+        replicate,
+        agentChannel,
+        verifyToken,
+        exchangeSession,
+    }), filesLayer({ plan: built.plan, verifyRuntime }), conversations === undefined
         ? Layer.empty
         : conversationRoutes({
             transport: conversations,

package/dist/storage/attachments.d.ts

@@ -30,6 +30,8 @@ export interface AttachmentCaller {
      * that reads them. Group attachments are shared across authorized sessions in the same chat.
      */
     readonly sessionId?: string;
+    /** Trusted user boundary; never accepted from agent tool arguments. */
+    readonly access?: "member";
 }
 export interface ReceiveAttachment {
     readonly source: (typeof ATTACHMENT_SOURCES)[number];
@@ -50,6 +52,16 @@ export interface AttachmentView {
     readonly createdAt: string;
     readonly expiresAt: string;
     readonly promotion: unknown;
+    readonly conversation?: string;
+    readonly senderId?: string;
+}
+export interface AttachmentSearch {
+    readonly conversation?: string;
+    readonly senderId?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly before?: string;
+    readonly limit?: number;
 }
 export interface PromotionTarget {
     /** The entity whose action adopts the file, such as `document`. */
@@ -103,6 +115,20 @@ export declare function attachmentRuntime(ontology: Ontology, sql: SqlClient.Sql
         deduplicated: boolean;
         result: {} | null;
     }, unknown, never>;
+    listForMember: (filters: AttachmentSearch, principal: Principal) => Effect.Effect<{
+        attachments: AttachmentView[];
+        nextCursor: string | null;
+    }, PermissionDenied | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
+    getForMember: (id: string, principal: Principal) => Effect.Effect<AttachmentView, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
+    readForMember: (id: string, principal: Principal) => Effect.Effect<{
+        attachment: AttachmentView;
+        download: TransferGrant;
+    }, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    promoteForMember: (id: string, target: PromotionTarget, principal: Principal, run: PromotionRunner) => Effect.Effect<{
+        attachment: AttachmentView;
+        deduplicated: boolean;
+        result: {} | null;
+    }, unknown, never>;
 };
 export type AttachmentRuntime = ReturnType<typeof attachmentRuntime>;
 export type AttachmentFailure = ActionRejected | Conflict | NotFound | PermissionDenied;

package/dist/storage/attachments.js

@@ -96,6 +96,8 @@ function view(row) {
         createdAt: row.created_at,
         expiresAt: row.expires_at,
         promotion: row.promotion ?? null,
+        conversation: row.conversation,
+        senderId: row.owner_id,
     };
 }
 /** Persisted phases surround every provider call; no external I/O holds a database transaction. */
@@ -110,6 +112,14 @@ export function attachmentRuntime(ontology, sql, provider) {
             return "denied";
         }
         yield* authorizeBlobOperation(ontology, sql, caller.principal.id, []);
+        if (caller.access === "member") {
+            const admin = yield* authorizeBlobOperation(ontology, sql, caller.principal.id, [
+                "agent_chat:update",
+            ]).pipe(Effect.as(true), Effect.catchTag("PermissionDenied", () => Effect.succeed(false)));
+            if (admin) {
+                return "administrator";
+            }
+        }
         const separator = caller.conversation.indexOf(":");
         const [chat] = yield* sql.unsafe(`SELECT id::text FROM "agent_chat"
          WHERE provider = $1 AND external_id = $2 FOR SHARE`, [caller.conversation.slice(0, separator), caller.conversation.slice(separator + 1)]);
@@ -148,19 +158,21 @@ export function attachmentRuntime(ontology, sql, provider) {
             caller.principal.id,
             caller.conversation,
             binding.branchId,
-            access === "group" && scope === "session",
+            (access === "group" || access === "administrator") && scope === "session",
         ]);
         const row = rows[0];
         if (!row) {
             return yield* missing(id);
         }
         if (access === "private" &&
+            caller.access !== "member" &&
             scope === "session" &&
             row.session_id !== null &&
             row.session_id !== caller.sessionId) {
             return yield* missing(id);
         }
         if (access === "private" &&
+            caller.access !== "member" &&
             scope === "session" &&
             row.session_id === null &&
             caller.sessionId !== undefined) {
@@ -401,6 +413,9 @@ export function attachmentRuntime(ontology, sql, provider) {
         const prepared = yield* sql.withTransaction(Effect.gen(function* () {
             const row = yield* load(id, caller);
             yield* authorizeBlobOperation(ontology, sql, caller.principal.id, found.permissions, caller.principal.execution);
+            if (caller.access === "member" && row.expired) {
+                return yield* unavailable("The attachment expired or was purged.");
+            }
             if (row.state === "promoted") {
                 return { kind: "done", row };
             }
@@ -419,7 +434,7 @@ export function attachmentRuntime(ontology, sql, provider) {
              WHERE sha256 = $1 AND branch_id = $2 AND state = 'promoted' AND id <> $3::uuid
                AND promotion->>'action' = $4 AND promotion->>'deduplicated_from' IS NULL
                AND conversation = $5 AND (owner_id = $6::uuid OR $7)
-               AND ($7 OR session_id IS NULL OR session_id = $8)
+               AND ($7 OR $9 OR session_id IS NULL OR session_id = $8)
              ORDER BY created_at LIMIT 1`, [
                 row.sha256,
                 binding.branchId,
@@ -427,8 +442,9 @@ export function attachmentRuntime(ontology, sql, provider) {
                 qualified,
                 caller.conversation,
                 caller.principal.id,
-                (yield* accessScope(caller)) === "group",
+                ["group", "administrator"].includes(yield* accessScope(caller)),
                 caller.sessionId ?? null,
+                caller.access === "member",
             ]);
             if (earlier) {
                 const promotion = {
@@ -528,7 +544,106 @@ export function attachmentRuntime(ontology, sql, provider) {
         }));
         return { attachment: view(promoted), deduplicated: false, result: outcome.result ?? null };
     });
-    return { receive, complete, list, read, discard, promote };
+    /** Resolve the chat from storage, then authorize with the same locked loader. */
+    const memberCaller = (id, principal) => sql.withTransaction(Effect.gen(function* () {
+        if (!/^[0-9a-f-]{36}$/i.test(id)) {
+            return yield* missing(id);
+        }
+        const [row] = yield* sql.unsafe(`SELECT conversation FROM "${ATTACHMENTS_TABLE}" WHERE id = $1::uuid AND branch_id = $2`, [id, binding.branchId]);
+        if (!row) {
+            return yield* missing(id);
+        }
+        const caller = {
+            principal,
+            conversation: row.conversation,
+            access: "member",
+        };
+        yield* load(id, caller);
+        return caller;
+    }));
+    const getForMember = (id, principal) => Effect.gen(function* () {
+        const caller = yield* memberCaller(id, principal);
+        const row = yield* sql.withTransaction(load(id, caller));
+        if (!READABLE.has(row.state) || row.expired) {
+            return yield* unavailable("The attachment expired, was purged, or is not ready.");
+        }
+        return view(row);
+    });
+    const readForMember = (id, principal) => Effect.gen(function* () {
+        return yield* read(id, yield* memberCaller(id, principal));
+    });
+    const promoteForMember = (id, target, principal, run) => Effect.gen(function* () {
+        return yield* promote(id, target, yield* memberCaller(id, principal), run);
+    });
+    const listForMember = (filters, principal) => sql.withTransaction(Effect.gen(function* () {
+        const [member] = yield* sql.unsafe(`SELECT kind::text, active FROM "user" WHERE id = $1::uuid FOR SHARE`, [principal.id]);
+        if (member?.kind !== "member" || !member.active) {
+            return yield* missing("chat");
+        }
+        yield* authorizeBlobOperation(ontology, sql, principal.id, []);
+        const admin = yield* authorizeBlobOperation(ontology, sql, principal.id, [
+            "agent_chat:update",
+        ]).pipe(Effect.as(true), Effect.catchTag("PermissionDenied", () => Effect.succeed(false)));
+        if (filters.conversation !== undefined) {
+            const scope = yield* accessScope({
+                principal,
+                conversation: filters.conversation,
+                access: "member",
+            });
+            if (scope === "denied") {
+                return yield* missing("chat");
+            }
+            if (scope === "private") {
+                const [sent] = yield* sql.unsafe(`SELECT 1 FROM "${ATTACHMENTS_TABLE}" WHERE branch_id = $1 AND conversation = $2
+                AND owner_id = $3::uuid LIMIT 1`, [binding.branchId, filters.conversation, principal.id]);
+                if (sent === undefined) {
+                    return yield* missing("chat");
+                }
+            }
+        }
+        const limit = filters.limit ?? 50;
+        const rows = yield* sql.unsafe(`${SELECT} WHERE a.branch_id = $1
+          AND ($2 OR EXISTS (
+            SELECT 1 FROM "agent_chat" c JOIN "agent_chat_members" m ON m.agent_chat_id = c.id
+            WHERE c.provider || ':' || c.external_id = a.conversation AND m.user_id = $3::uuid
+          ) OR (a.owner_id = $3::uuid AND NOT EXISTS (
+            SELECT 1 FROM "agent_chat" c WHERE c.provider || ':' || c.external_id = a.conversation
+          )))
+          AND ($4::text IS NULL OR a.conversation = $4)
+          AND ($5::uuid IS NULL OR a.owner_id = $5::uuid)
+          AND ($6::timestamptz IS NULL OR a.created_at >= $6::timestamptz)
+          AND ($7::timestamptz IS NULL OR a.created_at <= $7::timestamptz)
+          AND ($8::uuid IS NULL OR (a.created_at, a.id) < (
+            SELECT created_at, id FROM "${ATTACHMENTS_TABLE}" WHERE id = $8::uuid AND branch_id = $1
+          ))
+        ORDER BY a.created_at DESC, a.id DESC LIMIT $9`, [
+            binding.branchId,
+            admin,
+            principal.id,
+            filters.conversation ?? null,
+            filters.senderId ?? null,
+            filters.from ?? null,
+            filters.to ?? null,
+            filters.before ?? null,
+            limit + 1,
+        ]);
+        return {
+            attachments: rows.slice(0, limit).map(view),
+            nextCursor: rows.length > limit ? rows[limit - 1].id : null,
+        };
+    }));
+    return {
+        receive,
+        complete,
+        list,
+        read,
+        discard,
+        promote,
+        listForMember,
+        getForMember,
+        readForMember,
+        promoteForMember,
+    };
 }
 /**
  * Expires attachments past their deadline and removes the bytes of every expired or discarded one

package/dist/storage/neon.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CreateMultipartUploadCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListMultipartUploadsCommand, ListPartsCommand, S3Client, UploadPartCommand, } from "@aws-sdk/client-s3";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 import { Effect } from "effect";
@@ -168,6 +169,53 @@ export function neonBlobProvider(binding) {
                 throw error;
             }
         }),
+        sha256: (key, size) => attempt("blob.sha256", async () => {
+            const response = await client.send(new GetObjectCommand(object(key)));
+            if (!response.Body) {
+                throw new Error("Neon returned no object body.");
+            }
+            const hash = createHash("sha256");
+            const reader = response.Body.transformToWebStream().getReader();
+            let received = 0;
+            let failure;
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        break;
+                    }
+                    received += value.byteLength;
+                    if (received > size) {
+                        throw new Error("The stored object exceeds its declared size.");
+                    }
+                    hash.update(value);
+                }
+                if (received !== size) {
+                    throw new Error("The stored object does not match its declared size.");
+                }
+                return hash.digest("hex");
+            }
+            catch (cause) {
+                failure = cause;
+                throw cause;
+            }
+            finally {
+                try {
+                    await reader.cancel();
+                }
+                catch (cleanup) {
+                    if (failure !== undefined) {
+                        throw new AggregateError([failure, cleanup], "Hashing and stream cleanup failed.", {
+                            cause: cleanup,
+                        });
+                    }
+                    throw cleanup;
+                }
+                finally {
+                    reader.releaseLock();
+                }
+            }
+        }),
         readPrefix: (key) => attempt("blob.read_prefix", async () => {
             const response = await client.send(new GetObjectCommand({ ...object(key), Range: "bytes=0-511" }));
             if (!response.Body) {

package/dist/storage/provider.d.ts

@@ -60,6 +60,8 @@ declare const BlobProvider_base: Context.ServiceClass<BlobProvider, "@segmentstr
         }>;
     }) => Effect.Effect<void, BlobStorageError>;
     readonly inspect: (key: string) => Effect.Effect<StoredObject | undefined, BlobStorageError>;
+    /** Hash immutable content without buffering it. */
+    readonly sha256: (key: string, size: number) => Effect.Effect<string, BlobStorageError>;
     readonly readPrefix: (key: string) => Effect.Effect<Uint8Array, BlobStorageError>;
     /** The whole object, at most `maxBytes`; for verifying an agent attachment's digest. */
     readonly read: (key: string, maxBytes: number) => Effect.Effect<Uint8Array, BlobStorageError>;