@segmentstream-cloud/ontology 0.9.0 → 0.11.0

package/dist/runtime/pipeline.js

@@ -1,7 +1,10 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { Cause, Duration, Effect, Option, Schema } from "effect";
 import { SqlClient } from "effect/unstable/sql";
 import { isSqlError } from "effect/unstable/sql/SqlError";
+import { canonicalJson } from "../manifest.js";
+import { Conflict } from "../errors.js";
+import { authorizeBlobOperation } from "../storage/authorization.js";
 import { ConnectionError, ConnectionTransport, connectionContext } from "../connection.js";
 import { PermissionDenied } from "../errors.js";
 import { generatedActionPermissions, missingPermission } from "../permissions.js";
@@ -61,7 +64,8 @@ const NO_CONNECTIONS = {
  * 1. decode the input with the action's schema; issues are returned, not raised;
  * 2. check that the principal's permissions cover the action's (PermissionDenied);
  * 3. with `validateOnly`, stop;
- * 4. run `prepare`, when the action has one, without a transaction: reads and the declared
+ * 4. reauthorize and replay a committed blob action, if its idempotency key matches;
+ *    otherwise run `prepare`, when the action has one, without a transaction: reads and the declared
  *    connections only, under {@link PREPARE_TIMEOUT};
  * 5. without a handler, answer with what `prepare` returned;
  * 6. open one transaction and run the handler with what `prepare` returned and the runtime, which
@@ -107,6 +111,50 @@ export function runAction(ontology, request) {
         const actionId = randomUUID();
         const requestId = request.requestId ?? actionId;
         const context = { input: decoded.value, principal: request.principal, requestId };
+        const hasUploads = (value) => typeof value === "object" &&
+            value !== null &&
+            ("uploadId" in value || Object.values(value).some(hasUploads));
+        const key = request.options?.idempotencyKey;
+        const hasBlobProperties = ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"));
+        const consumesUpload = action.transactional && hasBlobProperties && (hasUploads(decoded.value) || key !== undefined);
+        if (consumesUpload && (!key || key.length > 128 || !request.branchId)) {
+            return yield* new Conflict({
+                entity: request.entity,
+                message: "Upload actions require an idempotency key.",
+            });
+        }
+        const fingerprint = consumesUpload
+            ? createHash("sha256")
+                .update(canonicalJson({
+                qualified,
+                manifestHash: ontology.manifest.hash,
+                branchId: request.branchId ?? null,
+                input: request.input,
+                createIntent: request.options?.createIntent ?? null,
+            }))
+                .digest("hex")
+            : undefined;
+        // A committed retry must not depend on preparation's external services being available.
+        // The handler transaction below still locks and rechecks the key for concurrent requests.
+        if (consumesUpload) {
+            const saved = yield* sql
+                .withTransaction(Effect.gen(function* () {
+                yield* authorizeBlobOperation(ontology, sql, request.principal.id, found.permissions);
+                const [saved] = yield* sql.unsafe(`SELECT fingerprint, outcome FROM "_blob_action_results"
+               WHERE principal_id = $1::uuid AND key = $2`, [request.principal.id, key]);
+                if (saved && saved.fingerprint !== fingerprint) {
+                    return yield* new Conflict({
+                        entity: request.entity,
+                        message: "Idempotency key was used for another action.",
+                    });
+                }
+                return saved?.outcome;
+            }))
+                .pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+            if (saved) {
+                return saved;
+            }
+        }
         const prepared = action.prepare === undefined
             ? undefined
             : yield* prepare(ontology, sql, action, context, request.connections, qualified);
@@ -118,13 +166,49 @@ export function runAction(ontology, request) {
             action: qualified,
             actionId,
             principalId: request.principal.id,
+            ...(key ? { blobActionKey: key } : {}),
+            ...(request.branchId ? { branchId: request.branchId } : {}),
+            ...(request.options?.createIntent ? { createIntent: request.options.createIntent } : {}),
             onEdit: (edit) => edits.push(edit),
         });
         const handle = action.handler;
         const handler = Effect.suspend(() => handle({ ...context, prepared }));
+        let replay;
+        const transactionalHandler = Effect.gen(function* () {
+            if (consumesUpload) {
+                yield* authorizeBlobOperation(ontology, sql, request.principal.id, found.permissions);
+                yield* sql.unsafe(`INSERT INTO "_blob_action_results" (principal_id, key, fingerprint)
+          VALUES ($1::uuid, $2, $3) ON CONFLICT DO NOTHING`, [request.principal.id, key, fingerprint]);
+                const [saved] = yield* sql.unsafe(`SELECT fingerprint, outcome FROM "_blob_action_results" WHERE principal_id = $1::uuid AND key = $2
+           FOR UPDATE`, [request.principal.id, key]);
+                if (saved.fingerprint !== fingerprint) {
+                    return yield* new Conflict({
+                        entity: request.entity,
+                        message: "Idempotency key was used for another action.",
+                    });
+                }
+                if (saved.outcome) {
+                    replay = saved.outcome;
+                    return replay.result;
+                }
+            }
+            const result = yield* handler.pipe(OntologyRuntime.provide(runtime));
+            if (consumesUpload) {
+                yield* sql.unsafe(`UPDATE "_blob_action_results" SET outcome = $1::jsonb
+          WHERE principal_id = $2::uuid AND key = $3`, [
+                    JSON.stringify({ result: result ?? null, validation: VALID, edits }),
+                    request.principal.id,
+                    key,
+                ]);
+            }
+            return result;
+        });
         const result = yield* sql
-            .withTransaction(handler.pipe(OntologyRuntime.provide(runtime)))
+            .withTransaction(transactionalHandler)
             .pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+        if (replay) {
+            return replay;
+        }
         const committed = {
             entity: request.entity,
             action: request.action,

package/dist/runtime/principals.d.ts

@@ -54,6 +54,11 @@ export declare function resolvePrincipalByIdentity(ontology: Ontology, claims: I
  * revoked keys and inactive users are rejected.
  */
 export declare function resolvePrincipalByApiKey(ontology: Ontology, key: string): Effect.Effect<Principal, PrincipalRejected, SqlClient.SqlClient>;
+/**
+ * A member by user id, with the roles they hold now: whom an OAuth grant acts for. `undefined` for
+ * an unknown user, a service and an inactive member.
+ */
+export declare function resolveMemberById(ontology: Ontology, userId: string): Effect.Effect<Principal | undefined, never, SqlClient.SqlClient>;
 export interface CreatedApiKey {
     readonly id: string;
     /** The key itself. It is not stored and cannot be shown again. */

package/dist/runtime/principals.js

@@ -241,6 +241,21 @@ export function resolvePrincipalByApiKey(ontology, key) {
         return yield* activePrincipal(ontology, sql, decodeUser({ id: row.id, kind: row.kind, active: row.active }));
     }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
 }
+/**
+ * A member by user id, with the roles they hold now: whom an OAuth grant acts for. `undefined` for
+ * an unknown user, a service and an inactive member.
+ */
+export function resolveMemberById(ontology, userId) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const [row] = yield* sql.unsafe(`SELECT "id"::text AS "id", "kind"::text AS "kind", "active" AS "active" ` +
+            `FROM "${USER_TABLE}" WHERE "id" = $1::uuid`, [userId]);
+        if (row === undefined || row.kind !== "member" || row.active !== true) {
+            return undefined;
+        }
+        return yield* rolesOf(ontology, sql, decodeUser(row));
+    }).pipe(Effect.orDie);
+}
 /** Issues an API key for a user. */
 export function createApiKey(input) {
     return Effect.gen(function* () {

package/dist/runtime/records.js

@@ -12,6 +12,11 @@ import { validate } from "./validation.js";
  */
 function readExpression(field, column) {
     switch (field.storage) {
+        case "blob":
+            return (`(SELECT json_build_object('id', b.id::text, 'filename', b.filename, ` +
+                `'contentType', b.content_type, 'size', b.size, 'createdAt', ` +
+                `to_char(b.created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))::text ` +
+                `FROM "_blobs" b WHERE b.id = ${column})`);
         case "timestamp":
             return `to_char(${column} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`;
         case "date":
@@ -42,6 +47,7 @@ function readValue(field, value) {
     switch (field.storage) {
         case "integer":
             return Number(value);
+        case "blob":
         case "json":
             return typeof value === "string" ? JSON.parse(value) : value;
         case "timestamp":
@@ -76,6 +82,9 @@ export function bindValue(field, value) {
     if (value === null) {
         return null;
     }
+    if (field.storage === "blob") {
+        return typeof value === "string" ? value : value.id;
+    }
     return field.storage === "json" ? JSON.stringify(value) : value;
 }
 function propertyIssue(field, value) {

package/dist/runtime/service-binding.d.ts

@@ -1,10 +1,11 @@
 import { Layer, Redacted } from "effect";
 import { SqlClient } from "effect/unstable/sql";
 import type { SqlError } from "effect/unstable/sql/SqlError";
+import type { BlobStorageBinding } from "../storage/provider.js";
 import type { Ontology } from "../ontology.js";
 import { OntologyBackend, type OntologyServiceRuntime } from "../service/runtime-contract.js";
 /** The service's backend on the runtime, over the SQL client in context. */
-export declare function backendLayer(ontology: Ontology): Layer.Layer<OntologyBackend, never, SqlClient.SqlClient>;
+export declare function backendLayer(ontology: Ontology, blobStorage?: Redacted.Redacted<BlobStorageBinding>): Layer.Layer<OntologyBackend, never, SqlClient.SqlClient>;
 /**
  * `@effect/sql-pg` on the pooled `ontology_app` connection string, with the TLS server name a
  * Neon endpoint needs.

package/dist/runtime/service-binding.js

@@ -1,9 +1,13 @@
 import * as PgClient from "@effect/sql-pg/PgClient";
 import { Effect, Layer, Redacted } from "effect";
 import { SqlClient } from "effect/unstable/sql";
+import { neonBlobProvider } from "../storage/neon.js";
+import { maintainBlobStorage } from "../storage/maintenance.js";
+import { blobRuntime } from "../storage/sessions.js";
 import { readCatalog } from "../migrate/apply.js";
 import { NotInvited, OntologyBackend, } from "../service/runtime-contract.js";
 import { generatedActions } from "./generated-actions.js";
+import { sqlOAuthStore } from "./oauth.js";
 import { runAction } from "./pipeline.js";
 import { checkSignIn, resolvePrincipalByApiKey, resolvePrincipalByIdentity } from "./principals.js";
 import { postgresTls } from "./postgres-tls.js";
@@ -18,18 +22,26 @@ function rejectedAs(operation) {
     return (rejection) => Effect.logWarning("ontology.principal.rejected").pipe(Effect.annotateLogs({ operation, reason: rejection.reason }), Effect.as(undefined));
 }
 /** The service's backend on the runtime, over the SQL client in context. */
-export function backendLayer(ontology) {
+export function backendLayer(ontology, blobStorage) {
     return Layer.effect(OntologyBackend, Effect.gen(function* () {
         const sql = yield* SqlClient.SqlClient;
         const runtime = makeOntologyRuntime(ontology, sql);
         const withSql = (effect) => Effect.provideService(effect, SqlClient.SqlClient, sql);
+        const binding = blobStorage ? Redacted.value(blobStorage) : undefined;
+        const provider = binding
+            ? yield* Effect.acquireRelease(Effect.sync(() => neonBlobProvider(binding)), (provider) => Effect.sync(() => provider.close?.()))
+            : undefined;
+        const blobs = provider ? blobRuntime(ontology, sql, provider) : undefined;
         return OntologyBackend.of({
+            ...(blobs ? { blobs } : {}),
+            ...(provider ? { maintainBlobs: maintainBlobStorage(sql, provider) } : {}),
             runAction: (input) => withSql(runAction(ontology, {
                 entity: input.entity,
                 action: input.action,
                 input: input.input,
                 principal: input.principal,
                 options: input.options,
+                ...(binding ? { branchId: binding.branchId } : {}),
                 afterCommit: input.afterCommit === undefined ? [] : [input.afterCommit],
                 ...(input.requestId === undefined ? {} : { requestId: input.requestId }),
                 ...(input.connections === undefined ? {} : { connections: input.connections }),
@@ -48,6 +60,7 @@ export function backendLayer(ontology) {
             checkSignIn: (email) => withSql(checkSignIn(ontology, email)),
             resolveApiKey: (key) => withSql(resolvePrincipalByApiKey(ontology, Redacted.value(key))).pipe(Effect.catchTag("PrincipalRejected", rejectedAs("api_key"))),
             appliedHash: readCatalog({ sql }).pipe(Effect.map((manifest) => manifest?.hash), Effect.orDie),
+            oauth: sqlOAuthStore(ontology, sql),
         });
     }));
 }
@@ -66,5 +79,5 @@ export function postgresLayer(databaseUrl) {
 /** The default runtime of `createOntologyService`: the SQL runtime on the workspace database. */
 export const sqlServiceRuntime = {
     generatedActions: (entity, ontology) => generatedActions(ontology, entity.name),
-    connect: ({ ontology, databaseUrl }) => backendLayer(ontology).pipe(Layer.provide(postgresLayer(databaseUrl))),
+    connect: ({ ontology, databaseUrl, blobStorage }) => backendLayer(ontology, blobStorage).pipe(Layer.provide(postgresLayer(databaseUrl))),
 };

package/dist/runtime/writes.js

@@ -1,4 +1,5 @@
 import { Effect } from "effect";
+import { resolveBlobWrites } from "../storage/writes.js";
 import { Conflict } from "../errors.js";
 import { quoteIdentifier } from "../migrate/storage.js";
 import { InvalidValues } from "./errors.js";
@@ -21,7 +22,9 @@ function requireReferences(context, references) {
 }
 function insertRecord(context, entity, values, onConflict) {
     return Effect.gen(function* () {
-        const write = yield* prepareWrite(entity, values, "create");
+        const recordId = uuidv7();
+        const resolved = yield* resolveBlobWrites(context, entity, recordId, values, true);
+        const write = yield* prepareWrite(entity, resolved, "create");
         yield* requireReferences(context, write.references);
         const params = new Params();
         const principal = params.add(context.scope.principalId, "uuid");
@@ -34,7 +37,7 @@ function insertRecord(context, entity, values, onConflict) {
             ...write.columns.map(({ field }) => quoteIdentifier(field.column)),
         ];
         const placeholders = [
-            params.add(uuidv7(), "uuid"),
+            params.add(recordId, "uuid"),
             "now()",
             "now()",
             principal,
@@ -64,11 +67,12 @@ export function createRecord(context, entity, values) {
 }
 export function updateRecord(context, entity, id, values) {
     return Effect.gen(function* () {
-        const write = yield* prepareWrite(entity, values, "update");
         const before = yield* loadRecord(context, entity, id, "update");
         if (before === undefined) {
             return yield* notFound(entity, id);
         }
+        const resolved = yield* resolveBlobWrites(context, entity, id, values, false);
+        const write = yield* prepareWrite(entity, resolved, "update");
         yield* requireReferences(context, write.references);
         let after = before;
         if (write.columns.length > 0) {
@@ -121,6 +125,16 @@ export function upsertRecord(context, entity, property, values) {
                 issues: [{ path: [property], message: `${property} is required` }],
             }));
         }
+        // A file ticket for an existing record must not be consumed by a speculative INSERT.
+        if (entity.fields.some((candidate) => candidate.storage === "blob" && values[candidate.name] != null)) {
+            const lookup = new Params();
+            const [existing] = yield* context.run(`SELECT id::text AS id FROM ${quoteIdentifier(entity.table)}
+        WHERE ${quoteIdentifier(field.column)} = ${lookup.add(bindValue(field, key), field.sqlType)} FOR UPDATE`, lookup);
+            if (existing) {
+                const record = yield* updateRecord(context, entity, existing.id, values);
+                return { record, created: false };
+            }
+        }
         const created = yield* insertRecord(context, entity, values, ` ON CONFLICT (${quoteIdentifier(field.column)}) DO NOTHING`);
         if (created !== undefined) {
             return { record: created, created: true };

package/dist/service/api.js

@@ -1,8 +1,11 @@
 import { Effect, Layer, Schema } from "effect";
 import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi, } from "effect/unstable/httpapi";
+import { storageGroup } from "../storage/api.js";
+import { DownloadRequest, TransferGrant } from "../storage/sessions.js";
 import { permissionOf, READ_VERB } from "../permissions.js";
 import { generatedActions } from "../runtime/generated-actions.js";
 import { Authentication } from "./authentication.js";
+import { actionDescription, requires } from "./descriptions.js";
 import { InvalidRequestBody, RequestId, failureResponse } from "./errors.js";
 import { planApi, } from "./plan.js";
 import { ActionResponse, AsParams, Catalog, ErrorSchemas, Graph, HistoryPage, HistoryParams, IdParam, Me, SignInCheckRequest, SignInCheckResult, Status, actionRequest, entitySchemas, } from "./schemas.js";
@@ -56,10 +59,6 @@ const connectionActionErrors = [
     ErrorSchemas.connectionResponseInvalid,
     ErrorSchemas.connectionUnavailable,
 ];
-/** `Requires lead:read.`, `Requires lead:create and lead:update.` */
-function requires(permissions) {
-    return `Requires ${permissions.join(" and ")}.`;
-}
 function readPermission(entity) {
     return permissionOf(entity, READ_VERB);
 }
@@ -73,17 +72,14 @@ function traversalEndpoint(planned, traversal, target, targetNames) {
     return documented(endpoint, `${label} ${traversal.phrase} ${reach} (${traversal.name})`, `${traversal.description}\n\n${requires(permissions)} Including a relationship requires ` +
         "reading its entity too.");
 }
-function actionEndpoint(planned, { name, action, generated, permissions }) {
+function actionEndpoint(planned, plannedAction) {
+    const { name, action } = plannedAction;
     const endpoint = HttpApiEndpoint.post(`actions.${name}`, `${BASE_PATH}/${planned.name}/actions/${name}`, {
         payload: actionRequest(action.input),
         success: ActionResponse,
         error: action.connections.length > 0 ? connectionActionErrors : actionErrors,
     });
-    const origin = generated ? "Generated action." : "Action.";
-    const calls = action.connections.length > 0
-        ? ` Calls ${action.connections.map((handle) => handle.key).join(", ")} before its transaction.`
-        : "";
-    return documented(endpoint, `${planned.name}.${name}`, `${action.description}\n\n${origin} ${requires(permissions)}${calls}`);
+    return documented(endpoint, `${planned.name}.${name}`, actionDescription(plannedAction));
 }
 function entityGroup(planned, schemas, names) {
     const own = schemas.get(planned.name);
@@ -121,6 +117,14 @@ function entityGroup(planned, schemas, names) {
             error: recordErrors,
         }), `History of a ${definition.label.toLowerCase()}`, `What each action changed on the record, newest first. ${read}`),
         ...planned.traversals.map((traversal) => traversalEndpoint(planned, traversal, schemas.get(traversal.target), names.get(traversal.target) ?? { label: traversal.target, plural: traversal.target })),
+        ...planned.resolved.properties
+            .filter((property) => property.definition.type === "blob")
+            .map((property) => documented(HttpApiEndpoint.post(`blobs.${property.name}`, `${base}/:id/blobs/${property.name}/download`, {
+            params: { id: IdParam },
+            payload: DownloadRequest,
+            success: TransferGrant,
+            error: recordErrors,
+        }), `Download ${property.name}`, `Requires ${planned.name}:read. Historical revisions must belong to this record and field.`)),
         ...planned.actions.map((action) => actionEndpoint(planned, action)),
     ];
     const [first, ...rest] = endpoints.map(authenticated);
@@ -172,6 +176,11 @@ export function buildApi(plan) {
     ]));
     const groups = [
         serviceGroup(),
+        ...(plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))
+            ? [
+                storageGroup(authenticated, actionErrors, (endpoint) => endpoint.middleware(ErrorResponses)),
+            ]
+            : []),
         ...plan.entities.map((planned) => entityGroup(planned, schemas, names)),
     ];
     const api = HttpApi.make("ontology")

package/dist/service/authentication.d.ts

@@ -1,4 +1,5 @@
 import { Context, Effect, Layer, Redacted } from "effect";
+import { HttpServerRequest, type HttpServerResponse } from "effect/unstable/http";
 import { HttpApiMiddleware, HttpApiSecurity } from "effect/unstable/httpapi";
 import { type JWTVerifyGetKey } from "jose";
 import type { Principal } from "../runtime.js";
@@ -117,8 +118,33 @@ type Authenticated = {
 } | {
     readonly status: "unavailable";
 };
+/** Where a credential is presented. */
+export interface CredentialOptions {
+    /**
+     * The resource OAuth access tokens must have been issued for: the MCP server's URL. Elsewhere,
+     * an access token is rejected, as it was issued for the MCP server only.
+     */
+    readonly oauthResource?: string;
+}
 /** Resolves a bearer credential to a principal. */
-export declare function authenticate(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier): Effect.Effect<Authenticated, never, OntologyBackend>;
+export declare function authenticate(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier, options?: CredentialOptions): Effect.Effect<Authenticated, never, OntologyBackend>;
+/** A browser's request, which may authenticate with the app's Neon Auth session cookie. */
+export interface BrowserSession {
+    readonly request: HttpServerRequest.HttpServerRequest;
+    readonly exchange: SessionExchange | undefined;
+}
+/**
+ * Runs `effect` as the principal a bearer credential names, or answers the request as every route
+ * does: 401 without a valid credential, 403 for a person nobody invited or a session cookie sent
+ * from another origin, 503 while sign-in cannot be verified, and a sanitized 500 when
+ * authentication itself fails.
+ */
+export declare function withPrincipal<E, R>(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier, backend: OntologyBackend["Service"], effect: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>, options?: CredentialOptions & {
+    /** The `WWW-Authenticate` challenge of a 401, by whether the credential was missing. */
+    readonly challenge?: (missing: boolean) => string;
+    /** Without a bearer token, the app's session cookie may authenticate this browser request. */
+    readonly session?: BrowserSession;
+}): Effect.Effect<HttpServerResponse.HttpServerResponse, E, Exclude<R, CurrentPrincipal> | RequestId>;
 /**
  * The {@link Authentication} middleware, verifying tokens with `verifyToken`. With `exchangeSession`,
  * a request without a bearer token may authenticate with the app's Neon Auth session cookie.

package/dist/service/authentication.js

@@ -4,6 +4,7 @@ import { HttpApiMiddleware, HttpApiSecurity, OpenApi } from "effect/unstable/htt
 import { createRemoteJWKSet, decodeJwt, errors, jwtVerify, } from "jose";
 import { API_KEY_PREFIX } from "../runtime/principals.js";
 import { RequestId, crossOriginSession, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
+import { ACCESS_TOKEN_PREFIX, principalOfAccessToken } from "./oauth/protocol.js";
 import { OntologyBackend } from "./runtime-contract.js";
 import { ErrorSchemas } from "./schemas.js";
 const CLOCK_TOLERANCE_SECONDS = 5;
@@ -274,13 +275,21 @@ function sessionMayAuthenticate(request) {
     return origin !== undefined && origin === requestOrigin(request);
 }
 /** Resolves a bearer credential to a principal. */
-export function authenticate(credential, verifyToken) {
+export function authenticate(credential, verifyToken, options = {}) {
     return Effect.gen(function* () {
         const backend = yield* OntologyBackend;
         const token = Redacted.value(credential);
         if (token === "") {
             return { status: "missing" };
         }
+        if (token.startsWith(ACCESS_TOKEN_PREFIX)) {
+            const member = options.oauthResource === undefined || backend.oauth === undefined
+                ? undefined
+                : yield* principalOfAccessToken(backend.oauth, token, options.oauthResource);
+            return member === undefined
+                ? { status: "rejected" }
+                : { status: "authenticated", principal: member };
+        }
         if (token.startsWith(API_KEY_PREFIX)) {
             const service = yield* backend.resolveApiKey(credential);
             return service === undefined
@@ -323,6 +332,41 @@ function authenticateSession(request, exchangeSession, verifyToken) {
         }
     });
 }
+/**
+ * Runs `effect` as the principal a bearer credential names, or answers the request as every route
+ * does: 401 without a valid credential, 403 for a person nobody invited or a session cookie sent
+ * from another origin, 503 while sign-in cannot be verified, and a sanitized 500 when
+ * authentication itself fails.
+ */
+export function withPrincipal(credential, verifyToken, backend, effect, options = {}) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const outcome = yield* Effect.gen(function* () {
+            const fromSession = Redacted.value(credential) === "" && options.session !== undefined
+                ? yield* authenticateSession(options.session.request, options.session.exchange, verifyToken)
+                : undefined;
+            return fromSession ?? (yield* authenticate(credential, verifyToken, options));
+        }).pipe(Effect.provideService(OntologyBackend, backend), Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
+            ? Effect.failCause(cause)
+            : Effect.logError("ontology.authentication.failed", cause).pipe(Effect.annotateLogs({ requestId }), Effect.as({ status: "failed" }))));
+        switch (outcome.status) {
+            case "authenticated":
+                return yield* Effect.provideService(effect, CurrentPrincipal, outcome.principal);
+            case "missing":
+                return toServerResponse(unauthorized(requestId, "A bearer token is required.", options.challenge?.(true)));
+            case "rejected":
+                return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked.", options.challenge?.(false)));
+            case "not_invited":
+                return toServerResponse(notInvited(requestId));
+            case "cross_origin":
+                return toServerResponse(crossOriginSession(requestId));
+            case "unavailable":
+                return yield* Effect.logWarning("ontology.authentication.unavailable").pipe(Effect.annotateLogs({ requestId }), Effect.as(toServerResponse(unavailable(requestId))));
+            case "failed":
+                return toServerResponse(internalError(requestId));
+        }
+    });
+}
 /**
  * The {@link Authentication} middleware, verifying tokens with `verifyToken`. With `exchangeSession`,
  * a request without a bearer token may authenticate with the app's Neon Auth session cookie.
@@ -332,32 +376,10 @@ export function authenticationLayer(verifyToken, exchangeSession) {
         const backend = yield* OntologyBackend;
         return Authentication.of({
             bearer: (httpEffect, { credential }) => Effect.gen(function* () {
-                const requestId = yield* RequestId;
                 const request = yield* HttpServerRequest.HttpServerRequest;
-                const outcome = yield* Effect.gen(function* () {
-                    const fromSession = Redacted.value(credential) === ""
-                        ? yield* authenticateSession(request, exchangeSession, verifyToken)
-                        : undefined;
-                    return fromSession ?? (yield* authenticate(credential, verifyToken));
-                }).pipe(Effect.provideService(OntologyBackend, backend), Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
-                    ? Effect.failCause(cause)
-                    : Effect.logError("ontology.authentication.failed", cause).pipe(Effect.annotateLogs({ requestId }), Effect.as({ status: "failed" }))));
-                switch (outcome.status) {
-                    case "authenticated":
-                        return yield* Effect.provideService(httpEffect, CurrentPrincipal, outcome.principal);
-                    case "missing":
-                        return toServerResponse(unauthorized(requestId, "A bearer token is required."));
-                    case "rejected":
-                        return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked."));
-                    case "not_invited":
-                        return toServerResponse(notInvited(requestId));
-                    case "cross_origin":
-                        return toServerResponse(crossOriginSession(requestId));
-                    case "unavailable":
-                        return yield* Effect.logWarning("ontology.authentication.unavailable").pipe(Effect.annotateLogs({ requestId }), Effect.as(toServerResponse(unavailable(requestId))));
-                    case "failed":
-                        return toServerResponse(internalError(requestId));
-                }
+                return yield* withPrincipal(credential, verifyToken, backend, httpEffect, {
+                    session: { request, exchange: exchangeSession },
+                });
             }),
         });
     }));

package/dist/service/config.d.ts

@@ -1,4 +1,5 @@
 import { Redacted, Schema } from "effect";
+import { BlobStorageBinding } from "../storage/provider.js";
 import type { Principal } from "../runtime.js";
 import { type ConnectionTransportFactory, type LocalConnectionContext } from "./connections.js";
 import type { OntologyServiceRuntime } from "./runtime-contract.js";
@@ -29,6 +30,8 @@ export interface NeonAuthEnvironment {
 export interface OntologyEnvironment {
     /** The pooled connection string of the `ontology_app` role. */
     readonly databaseUrl: Redacted.Redacted<string>;
+    readonly blobStorage?: Redacted.Redacted<BlobStorageBinding>;
+    readonly storageMaintenanceKey?: Redacted.Redacted<string>;
     /** The control plane: it issues app tokens and serves their JWKS. */
     readonly segmentstreamUrl: string;
     /** App tokens must be issued for this application: `aud: app:<application id>`. */
@@ -70,6 +73,11 @@ export interface OntologyServiceConfig extends OntologyEnvironment {
      * set, else SegmentStream's proxy with the request's Vercel OIDC token.
      */
     readonly connections?: ConnectionTransportFactory;
+    /**
+     * Serve the MCP server at `/mcp`. On by default: its tools reach exactly what the HTTP routes
+     * reach, with the same credentials.
+     */
+    readonly mcp?: boolean;
 }
 declare const OntologyServiceConfigError_base: Schema.Class<OntologyServiceConfigError, Schema.TaggedStruct<"OntologyServiceConfigError", {
     readonly message: Schema.String;

package/dist/service/config.js

@@ -1,4 +1,5 @@
 import { Redacted, Schema } from "effect";
+import { BlobStorageBinding } from "../storage/provider.js";
 import { LocalConnectionContextError, readLocalConnectionContext, RUNTIME_CONTEXT_FD, } from "./connections.js";
 /** The environment of the workspace deployment's ontology service. */
 export const ENVIRONMENT_VARIABLES = {
@@ -83,12 +84,29 @@ export function configFromEnv(environment = process.env) {
     }
     const neonAuth = neonAuthFromEnv(read);
     const localConnections = localConnectionsFromEnv(environment);
+    let blobStorage;
+    if (read("SEGMENTSTREAM_ONTOLOGY_STORAGE")) {
+        try {
+            blobStorage = Redacted.make(Schema.decodeUnknownSync(BlobStorageBinding)(JSON.parse(read("SEGMENTSTREAM_ONTOLOGY_STORAGE"))));
+        }
+        catch {
+            throw new OntologyServiceConfigError({
+                message: "SEGMENTSTREAM_ONTOLOGY_STORAGE is invalid.",
+            });
+        }
+    }
     return {
         databaseUrl: checkDatabaseUrl(ENVIRONMENT_VARIABLES.databaseUrl, read(ENVIRONMENT_VARIABLES.databaseUrl)),
         segmentstreamUrl: normalizeUrl(ENVIRONMENT_VARIABLES.segmentstreamUrl, read(ENVIRONMENT_VARIABLES.segmentstreamUrl)),
         applicationId: read(ENVIRONMENT_VARIABLES.applicationId),
         workspaceId: read(ENVIRONMENT_VARIABLES.workspaceId),
         organizationId: read(ENVIRONMENT_VARIABLES.organizationId),
+        ...(blobStorage === undefined ? {} : { blobStorage }),
+        ...(read("SEGMENTSTREAM_ONTOLOGY_STORAGE_MAINTENANCE_KEY")
+            ? {
+                storageMaintenanceKey: Redacted.make(read("SEGMENTSTREAM_ONTOLOGY_STORAGE_MAINTENANCE_KEY")),
+            }
+            : {}),
         ...(neonAuth === undefined ? {} : { neonAuth }),
         ...(localConnections === undefined ? {} : { localConnections }),
     };

package/dist/service/descriptions.d.ts

@@ -0,0 +1,8 @@
+import type { PlannedAction } from "./plan.js";
+/** `Requires lead:read.`, `Requires lead:create and lead:update.` */
+export declare function requires(permissions: ReadonlyArray<string>): string;
+/**
+ * What an action's route and its MCP tool say about it: its description, whether it is generated,
+ * the permissions it requires and the connections it calls.
+ */
+export declare function actionDescription({ action, generated, permissions }: PlannedAction): string;

package/dist/service/descriptions.js

@@ -0,0 +1,15 @@
+/** `Requires lead:read.`, `Requires lead:create and lead:update.` */
+export function requires(permissions) {
+    return `Requires ${permissions.join(" and ")}.`;
+}
+/**
+ * What an action's route and its MCP tool say about it: its description, whether it is generated,
+ * the permissions it requires and the connections it calls.
+ */
+export function actionDescription({ action, generated, permissions }) {
+    const origin = generated ? "Generated action." : "Action.";
+    const calls = action.connections.length > 0
+        ? ` Calls ${action.connections.map((handle) => handle.key).join(", ")} before its transaction.`
+        : "";
+    return `${action.description}\n\n${origin} ${requires(permissions)}${calls}`;
+}

package/dist/service/errors.d.ts

@@ -45,7 +45,11 @@ export declare function toServerResponse(response: ErrorResponse): HttpServerRes
 export declare function errorBodyForWire(body: ErrorBody): Readonly<Record<string, unknown>>;
 /** Issues of a schema failure, as `[{ path, message }]`. */
 export declare function schemaIssues(issue: SchemaIssue.Issue): Array<ValidationIssue>;
-export declare function unauthorized(requestId: string, detail: string): ErrorResponse;
+/**
+ * `challenge` is the `WWW-Authenticate` value; the MCP server's names its OAuth metadata, which is
+ * how a client learns where members authorize it.
+ */
+export declare function unauthorized(requestId: string, detail: string, challenge?: string): ErrorResponse;
 /**
  * The token is valid but the `invited` sign-in policy turns its holder away: nobody invited them.
  * The detail is written for the person, since the app shows it.