@segmentstream-cloud/ontology 0.8.0 → 0.10.0

package/dist/service/authentication.js

@@ -1,8 +1,9 @@
 import { Cause, Context, Effect, Layer, Redacted } from "effect";
+import { HttpServerRequest } from "effect/unstable/http";
 import { HttpApiMiddleware, HttpApiSecurity, OpenApi } from "effect/unstable/httpapi";
 import { createRemoteJWKSet, decodeJwt, errors, jwtVerify, } from "jose";
 import { API_KEY_PREFIX } from "../runtime/principals.js";
-import { RequestId, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
+import { RequestId, crossOriginSession, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
 import { OntologyBackend } from "./runtime-contract.js";
 import { ErrorSchemas } from "./schemas.js";
 const CLOCK_TOLERANCE_SECONDS = 5;
@@ -12,8 +13,8 @@ export class CurrentPrincipal extends Context.Service()("@segmentstream-cloud/on
 }
 /**
  * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token
- * or an API key, all as `Authorization: Bearer …`. Failures answer the request directly, before its
- * input is decoded.
+ * or an API key, all as `Authorization: Bearer …`; without one, the app's Neon Auth session cookie.
+ * Failures answer the request directly, before its input is decoded.
  */
 export class Authentication extends HttpApiMiddleware.Service()("@segmentstream-cloud/ontology/Authentication", {
     security: {
@@ -173,6 +174,105 @@ export function tokenVerifier(config) {
     }
     return verifyByIssuer(verifiers);
 }
+/**
+ * The session cookie the app's Neon Auth sets on the app's domain. The ontology service shares the
+ * domain, so a signed-in browser sends it here too: the docs page relies on it.
+ */
+export const NEON_AUTH_SESSION_COOKIE = "__Secure-neon-auth.session_token";
+/** Session tokens kept at once; past it the oldest go first. */
+const SESSION_CACHE_SIZE = 1_000;
+/** A session's token is fetched again this long before it expires. */
+const SESSION_TOKEN_MARGIN_MS = 60_000;
+const SESSION_EXCHANGE_TIMEOUT_MS = 5_000;
+/**
+ * Exchanges a session cookie for its token at Neon Auth's `GET <base URL>/token`, as the app's
+ * `@neondatabase/auth` does, and reuses the token until shortly before it expires. The token is then
+ * verified like any bearer token, so the exchange never vouches for a session on its own.
+ */
+export function neonAuthSessionExchange(config, options = {}) {
+    const fetchToken = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    const endpoint = new URL("token", config.baseUrl.endsWith("/") ? config.baseUrl : `${config.baseUrl}/`);
+    const cache = new Map();
+    return async function exchangeSession(session, origin) {
+        const value = Redacted.value(session);
+        const cached = cache.get(value);
+        if (cached !== undefined && cached.refreshAt > now()) {
+            return { status: "token", token: cached.token };
+        }
+        cache.delete(value);
+        let response;
+        try {
+            response = await fetchToken(endpoint, {
+                headers: { cookie: `${NEON_AUTH_SESSION_COOKIE}=${value}`, origin },
+                redirect: "error",
+                signal: AbortSignal.timeout(SESSION_EXCHANGE_TIMEOUT_MS),
+            });
+        }
+        catch {
+            return { status: "unavailable" };
+        }
+        if (response.status === 401 || response.status === 403) {
+            return { status: "invalid" };
+        }
+        if (!response.ok) {
+            return { status: "unavailable" };
+        }
+        const body = (await response.json().catch(() => undefined));
+        const token = body?.token;
+        if (typeof token !== "string" || token === "") {
+            return { status: "unavailable" };
+        }
+        const expiresAt = tokenExpiry(token);
+        if (expiresAt !== undefined) {
+            if (cache.size >= SESSION_CACHE_SIZE) {
+                cache.delete(cache.keys().next().value);
+            }
+            cache.set(value, { token, refreshAt: expiresAt - SESSION_TOKEN_MARGIN_MS });
+        }
+        return { status: "token", token };
+    };
+}
+/** When a token expires, in milliseconds; `undefined` for a token without a readable `exp`. */
+function tokenExpiry(token) {
+    try {
+        const { exp } = decodeJwt(token);
+        return typeof exp === "number" ? exp * 1_000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+/**
+ * The origin the browser addressed. Vercel and the app's development proxy name it in the forwarded
+ * headers; otherwise it is the request URL's, which Nitro passes on whole.
+ */
+function requestOrigin(request) {
+    const first = (value) => value?.split(",")[0]?.trim() || undefined;
+    const url = URL.canParse(request.originalUrl) ? new URL(request.originalUrl) : undefined;
+    const host = first(request.headers["x-forwarded-host"]) ?? url?.host ?? request.headers.host;
+    if (host === undefined || host === "") {
+        return undefined;
+    }
+    const forwardedProto = first(request.headers["x-forwarded-proto"]);
+    const protocol = forwardedProto === "http" || forwardedProto === "https"
+        ? forwardedProto
+        : (url?.protocol.slice(0, -1) ?? "https");
+    return `${protocol}://${host}`;
+}
+/**
+ * A request the session cookie may authenticate: any read, and a change only when the browser says
+ * it comes from the app's own origin. Browsers send `Origin` with every cross-origin request and
+ * with same-origin `POST`s, so a change without one is refused too.
+ */
+function sessionMayAuthenticate(request) {
+    if (SAFE_METHODS.has(request.method)) {
+        return true;
+    }
+    const origin = request.headers.origin;
+    return origin !== undefined && origin === requestOrigin(request);
+}
 /** Resolves a bearer credential to a principal. */
 export function authenticate(credential, verifyToken) {
     return Effect.gen(function* () {
@@ -198,14 +298,48 @@ export function authenticate(credential, verifyToken) {
             : { status: "authenticated", principal: member }), Effect.catchTag("NotInvited", () => Effect.succeed({ status: "not_invited" })));
     });
 }
-/** The {@link Authentication} middleware, verifying tokens with `verifyToken`. */
-export function authenticationLayer(verifyToken) {
+/**
+ * Resolves the Neon Auth session cookie to a principal through the session's token. `undefined`
+ * when the request has no session cookie, or the service no Neon Auth.
+ */
+function authenticateSession(request, exchangeSession, verifyToken) {
+    return Effect.gen(function* () {
+        const session = request.cookies[NEON_AUTH_SESSION_COOKIE];
+        const origin = requestOrigin(request);
+        if (exchangeSession === undefined || session === undefined || session === "") {
+            return undefined;
+        }
+        if (origin === undefined || !sessionMayAuthenticate(request)) {
+            return { status: "cross_origin" };
+        }
+        const exchange = yield* Effect.promise(() => exchangeSession(Redacted.make(session), origin));
+        switch (exchange.status) {
+            case "token":
+                return yield* authenticate(Redacted.make(exchange.token), verifyToken);
+            case "invalid":
+                return { status: "rejected" };
+            case "unavailable":
+                return { status: "unavailable" };
+        }
+    });
+}
+/**
+ * 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.
+ */
+export function authenticationLayer(verifyToken, exchangeSession) {
     return Layer.effect(Authentication, Effect.gen(function* () {
         const backend = yield* OntologyBackend;
         return Authentication.of({
             bearer: (httpEffect, { credential }) => Effect.gen(function* () {
                 const requestId = yield* RequestId;
-                const outcome = yield* authenticate(credential, verifyToken).pipe(Effect.provideService(OntologyBackend, backend), Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
+                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) {
@@ -217,6 +351,8 @@ export function authenticationLayer(verifyToken) {
                         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":

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>`. */

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/docs.d.ts

@@ -0,0 +1,9 @@
+import { HttpRouter } from "effect/unstable/http";
+/** The API reference page: `GET /api/ontology/docs`. */
+export declare const DOCS_PATH = "/api/ontology/docs";
+/**
+ * The API reference at `/api/ontology/docs`: Scalar over the service's own `openapi.json`. The page
+ * is public and holds no part of the ontology: it loads the document as the reader, with the app's
+ * session cookie when they are signed in to the app, or with a token they paste.
+ */
+export declare const DocsRoute: import("effect/Layer").Layer<never, never, HttpRouter.HttpRouter>;

package/dist/service/docs.js

@@ -0,0 +1,197 @@
+import { Effect } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
+import { BASE_PATH } from "./api.js";
+/** The API reference page: `GET /api/ontology/docs`. */
+export const DOCS_PATH = `${BASE_PATH}/docs`;
+const OPENAPI_PATH = `${BASE_PATH}/openapi.json`;
+/**
+ * Scalar's API reference, pinned with its integrity hash: a different file never runs. Bump both
+ * together: `curl -sL <url> | openssl dgst -sha384 -binary | openssl base64 -A`.
+ */
+const SCALAR_SCRIPT = {
+    src: "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.73.1/dist/browser/standalone.js",
+    integrity: "sha384-kYDGzV91Jnn3TbHINV3nt54riK2uMJDfN5Al8dAkz4FssELTBWbD8rgw32sTKfOi",
+};
+/**
+ * Scalar without its hosted extras: no telemetry, AI agent, MCP button, developer tools or fonts
+ * from scalar.com. Requests from the page go to the ontology itself, never through Scalar's proxy.
+ */
+const SCALAR_CONFIGURATION = {
+    telemetry: false,
+    agent: { disabled: true },
+    mcp: { disabled: true },
+    showDeveloperTools: "never",
+    withDefaultFonts: false,
+    hideClientButton: true,
+    documentDownloadType: "json",
+};
+/** The key the page keeps a pasted token under, for this tab only. */
+const TOKEN_STORAGE_KEY = "segmentstream-ontology-docs-token";
+/** JSON inside a `<script>`: nothing in it can close the element. */
+function scriptJson(value) {
+    return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+function contentSecurityPolicy(nonce) {
+    return [
+        "default-src 'none'",
+        `script-src 'nonce-${nonce}' https://cdn.jsdelivr.net`,
+        // Scalar injects its styles at runtime.
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data: blob: https:",
+        "font-src 'self' data:",
+        "connect-src 'self'",
+        "worker-src 'self' blob:",
+        "base-uri 'none'",
+        "form-action 'none'",
+        "frame-ancestors 'none'",
+    ].join("; ");
+}
+function page(nonce) {
+    const settings = scriptJson({
+        openapi: OPENAPI_PATH,
+        storageKey: TOKEN_STORAGE_KEY,
+        configuration: SCALAR_CONFIGURATION,
+    });
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>Ontology API</title>
+    <style>
+      #sign-in {
+        font: 14px/1.5 system-ui, sans-serif;
+        max-width: 28rem;
+        margin: 15vh auto;
+        padding: 0 1.5rem;
+        color: #18181b;
+      }
+      #sign-in h1 { font-size: 1.25rem; margin: 0 0 .5rem; }
+      #sign-in p { margin: 0 0 1rem; color: #52525b; }
+      #sign-in label { display: block; font-weight: 500; margin-bottom: .25rem; }
+      #sign-in input {
+        box-sizing: border-box;
+        width: 100%;
+        padding: .5rem .625rem;
+        border: 1px solid #d4d4d8;
+        border-radius: .375rem;
+        font: inherit;
+      }
+      #sign-in button {
+        margin-top: .75rem;
+        padding: .5rem .875rem;
+        border: 0;
+        border-radius: .375rem;
+        background: #18181b;
+        color: #fff;
+        font: inherit;
+        cursor: pointer;
+      }
+      #sign-in [role="alert"] { margin-top: .75rem; color: #b91c1c; }
+    </style>
+  </head>
+  <body>
+    <main id="sign-in" hidden>
+      <form>
+        <h1>Ontology API</h1>
+        <p>Sign in to the app in this browser, or paste a bearer token or an API key (ssk_…).</p>
+        <label for="token">Token or API key</label>
+        <input id="token" type="password" autocomplete="off" spellcheck="false" required />
+        <button type="submit">Open the reference</button>
+        <p role="alert"></p>
+      </form>
+    </main>
+    <div id="app"></div>
+    <script
+      nonce="${nonce}"
+      src="${SCALAR_SCRIPT.src}"
+      integrity="${SCALAR_SCRIPT.integrity}"
+      crossorigin="anonymous"
+    ></script>
+    <script nonce="${nonce}">
+      (() => {
+        const settings = ${settings};
+        const signIn = document.getElementById("sign-in");
+        const form = signIn.querySelector("form");
+        const input = document.getElementById("token");
+        const alert = signIn.querySelector("[role=alert]");
+
+        async function load(token) {
+          const response = await fetch(settings.openapi, {
+            credentials: "same-origin",
+            headers: token ? { authorization: "Bearer " + token } : {},
+          });
+
+          if (response.ok) {
+            return { spec: await response.json() };
+          }
+
+          const body = await response.json().catch(() => ({}));
+
+          return { status: response.status, detail: body.detail };
+        }
+
+        function show(spec, token) {
+          signIn.hidden = true;
+          window.Scalar.createApiReference(document.getElementById("app"), {
+            ...settings.configuration,
+            content: spec,
+            authentication: {
+              preferredSecurityScheme: "bearer",
+              ...(token ? { securitySchemes: { bearer: { token } } } : {}),
+            },
+          });
+        }
+
+        async function open(token) {
+          let result;
+
+          try {
+            result = await load(token);
+          } catch {
+            result = { status: 0 };
+          }
+
+          if (result.spec !== undefined) {
+            if (token) {
+              sessionStorage.setItem(settings.storageKey, token);
+            }
+            show(result.spec, token);
+
+            return;
+          }
+
+          sessionStorage.removeItem(settings.storageKey);
+          signIn.hidden = false;
+          alert.textContent =
+            !token && result.status === 401
+              ? ""
+              : (result.detail ?? "The reference could not be loaded. Try again shortly.");
+        }
+
+        form.addEventListener("submit", (event) => {
+          event.preventDefault();
+          open(input.value.trim());
+        });
+
+        open(sessionStorage.getItem(settings.storageKey) ?? "");
+      })();
+    </script>
+  </body>
+</html>
+`;
+}
+/**
+ * The API reference at `/api/ontology/docs`: Scalar over the service's own `openapi.json`. The page
+ * is public and holds no part of the ontology: it loads the document as the reader, with the app's
+ * session cookie when they are signed in to the app, or with a token they paste.
+ */
+export const DocsRoute = HttpRouter.add("GET", DOCS_PATH, Effect.sync(() => {
+    const nonce = crypto.randomUUID().replaceAll("-", "");
+    return HttpServerResponse.html(page(nonce)).pipe(HttpServerResponse.setHeaders({
+        "content-security-policy": contentSecurityPolicy(nonce),
+        "referrer-policy": "no-referrer",
+        "x-content-type-options": "nosniff",
+    }));
+}));

package/dist/service/errors.d.ts

@@ -51,6 +51,11 @@ export declare function unauthorized(requestId: string, detail: string): ErrorRe
  * The detail is written for the person, since the app shows it.
  */
 export declare function notInvited(requestId: string): ErrorResponse;
+/**
+ * A request that changes something came with the session cookie but not from the app's own pages.
+ * The cookie rides along with any request to the app's domain, so only its origin can vouch for it.
+ */
+export declare function crossOriginSession(requestId: string): ErrorResponse;
 export declare function unavailable(requestId: string): ErrorResponse;
 export declare function internalError(requestId: string): ErrorResponse;
 export declare function routeNotFound(requestId: string): ErrorResponse;

package/dist/service/errors.js

@@ -67,6 +67,20 @@ export function notInvited(requestId) {
         body: { error: "not_invited", detail: "Ask your administrator for an invitation.", requestId },
     };
 }
+/**
+ * A request that changes something came with the session cookie but not from the app's own pages.
+ * The cookie rides along with any request to the app's domain, so only its origin can vouch for it.
+ */
+export function crossOriginSession(requestId) {
+    return {
+        status: 403,
+        body: {
+            error: "forbidden",
+            detail: "The session cookie only authenticates requests from the app's own pages; send a bearer token.",
+            requestId,
+        },
+    };
+}
 export function unavailable(requestId) {
     return {
         status: 503,

package/dist/service/handlers.js

@@ -1,6 +1,8 @@
 import { HttpServerResponse } from "effect/unstable/http";
 import { Effect, Layer, Schema } from "effect";
 import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
+import { STORAGE_GROUP } from "../storage/api.js";
+import { Conflict } from "../errors.js";
 import { editsFromWire, generatedResultFromWire, recordFromWire } from "../authoring-records.js";
 import { nameToWire } from "../authoring-names.js";
 import { principalFromWire } from "../authoring.js";
@@ -181,7 +183,7 @@ function runAction(planned, { name, generated }, ontology, hook, connections) {
             action: name,
             input: envelope.input,
             principal,
-            options: { validateOnly },
+            options: { ...envelope.options, validateOnly },
             requestId,
             connections: connections({
                 identityToken: identityToken(request),
@@ -219,6 +221,18 @@ function entityHandlers(built, planned, hooks, targets, connections) {
             .handle("query", (request) => find(toQuery(request.payload)))
             .handle("get", (request) => readOwn.pipe(Effect.andThen(() => backend.get({ entity: planned.name, id: request.params.id }))))
             .handle("history", (request) => readOwn.pipe(Effect.andThen(() => backend.history({ entity: planned.name, id: request.params.id, ...request.query })), Effect.map(page)));
+        for (const property of planned.resolved.properties.filter((property) => property.definition.type === "blob")) {
+            registered = registered.handle(`blobs.${property.name}`, (request) => Effect.gen(function* () {
+                const principal = yield* CurrentPrincipal;
+                if (!backend.blobs) {
+                    return yield* new Conflict({
+                        entity: planned.name,
+                        message: "File storage is not configured.",
+                    });
+                }
+                return yield* backend.blobs.download(planned.name, request.params.id, property.name, request.payload, principal);
+            }));
+        }
         for (const traversal of planned.traversals) {
             registered = registered.handle(`related.${traversal.name}`, (request) => traverse(planned, traversal, request, targets).pipe(Effect.provideService(OntologyBackend, backend)));
         }
@@ -324,11 +338,36 @@ function serviceHandlers(built) {
             .handle("signInCheck", checkSignIn(backend, signInLimiter));
     }));
 }
+function storageHandlers(built) {
+    return dynamicGroup(built.api, STORAGE_GROUP, (handlers) => Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        const configured = () => backend.blobs
+            ? Effect.succeed(backend.blobs)
+            : Effect.fail(new Conflict({ entity: "upload", message: "File storage is not configured." }));
+        let registered = handlers.handle("begin", (request) => Effect.gen(function* () {
+            const principal = yield* CurrentPrincipal;
+            const blobs = yield* configured();
+            return yield* blobs.begin(request.payload, principal);
+        }));
+        for (const method of ["status", "part", "complete", "cancel"]) {
+            registered = registered.handle(method, (request) => Effect.gen(function* () {
+                const principal = yield* CurrentPrincipal;
+                const blobs = yield* configured();
+                return yield* blobs[method](request.params.id, principal);
+            }));
+        }
+        return registered.handle("maintain", () => backend.maintainBlobs ??
+            Effect.fail(new Conflict({ entity: "upload", message: "File storage is not configured." })));
+    }));
+}
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
 export function handlersLayer(built, hooks, connections) {
     const targets = relationshipTargets(built.plan);
     const layers = [
         serviceHandlers(built),
+        ...(built.plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))
+            ? [storageHandlers(built)]
+            : []),
         ...built.plan.entities.map((planned) => entityHandlers(built, planned, hooks, targets, connections)),
     ];
     const [first, ...rest] = layers;

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

@@ -1,4 +1,6 @@
 import { Context, Schema, type Effect, type Layer, type Redacted } from "effect";
+import type { BlobRuntime } from "../storage/sessions.js";
+import type { BlobStorageBinding } from "../storage/provider.js";
 import type { AnyAction } from "../action.js";
 import type { ResolvedEntity } from "../analyze.js";
 import type { ConnectionError, ConnectionTransport } from "../connection.js";
@@ -23,6 +25,8 @@ export interface RunActionInput {
     readonly principal: Principal;
     readonly options: {
         readonly validateOnly?: boolean;
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
     };
     /**
      * Runs once the action has committed, outside its transaction, before `runAction` returns. It
@@ -63,6 +67,10 @@ declare const NotInvited_base: Schema.Class<NotInvited, Schema.TaggedStruct<"Not
 export declare class NotInvited extends NotInvited_base {
 }
 declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segmentstream-cloud/ontology/OntologyBackend", {
+    readonly blobs?: BlobRuntime;
+    readonly maintainBlobs?: Effect.Effect<{
+        readonly removed: number;
+    }, unknown>;
     readonly runAction: (input: RunActionInput) => Effect.Effect<ActionOutcome, PermissionDenied | ActionRejected | Conflict | NotFound | ConnectionError>;
     readonly get: (input: {
         readonly entity: string;
@@ -111,6 +119,7 @@ export interface OntologyServiceRuntime {
     readonly connect: (input: {
         readonly ontology: Ontology;
         readonly databaseUrl: Redacted.Redacted<string>;
+        readonly blobStorage?: Redacted.Redacted<BlobStorageBinding>;
     }) => Layer.Layer<OntologyBackend, unknown>;
 }
 export {};

package/dist/service/schemas.d.ts

@@ -124,6 +124,8 @@ export declare const ActionEnvelope: Schema.Codec<{
     readonly input: unknown;
     readonly options?: {
         readonly validateOnly?: boolean;
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
     };
 }>;
 export declare const ActionResponse: Schema.Struct<{
@@ -151,7 +153,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly column: Schema.optionalKey<Schema.String>;
             readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly name: Schema.String;
-            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"]>;
             readonly label: Schema.String;
             readonly description: Schema.optionalKey<Schema.String>;
             readonly optional: Schema.Boolean;
@@ -163,6 +165,8 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly min: Schema.optionalKey<Schema.Number>;
             readonly max: Schema.optionalKey<Schema.Number>;
             readonly maxLength: Schema.optionalKey<Schema.Number>;
+            readonly accept: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly maxBytes: Schema.optionalKey<Schema.Number>;
             readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly value: Schema.String;
                 readonly label: Schema.String;
@@ -171,6 +175,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
         }>, {
             readonly renamedFrom: "renamed_from";
             readonly maxLength: "max_length";
+            readonly maxBytes: "max_bytes";
         }>>;
         readonly relationships: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
             readonly on: Schema.optionalKey<Schema.encodeKeys<Schema.Struct<{
@@ -259,7 +264,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly column: Schema.optionalKey<Schema.String>;
             readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly name: Schema.String;
-            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"]>;
             readonly label: Schema.String;
             readonly description: Schema.optionalKey<Schema.String>;
             readonly optional: Schema.Boolean;
@@ -271,6 +276,8 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly min: Schema.optionalKey<Schema.Number>;
             readonly max: Schema.optionalKey<Schema.Number>;
             readonly maxLength: Schema.optionalKey<Schema.Number>;
+            readonly accept: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly maxBytes: Schema.optionalKey<Schema.Number>;
             readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly value: Schema.String;
                 readonly label: Schema.String;
@@ -279,6 +286,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
         }>, {
             readonly renamedFrom: "renamed_from";
             readonly maxLength: "max_length";
+            readonly maxBytes: "max_bytes";
         }>>;
         readonly relationships: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
             readonly on: Schema.optionalKey<Schema.encodeKeys<Schema.Struct<{