@segmentstream-cloud/ontology 0.9.0 → 0.11.0

package/dist/service/errors.js

@@ -50,11 +50,15 @@ const REQUEST_PARTS = {
 function isJsonParseFailure(issue) {
     return (issue._tag === "InvalidValue" && issue.annotations?.message === "Expected a valid JSON body");
 }
-export function unauthorized(requestId, detail) {
+/**
+ * `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 function unauthorized(requestId, detail, challenge = 'Bearer realm="ontology"') {
     return {
         status: 401,
         body: { error: "unauthorized", detail, requestId },
-        headers: { "www-authenticate": 'Bearer realm="ontology"' },
+        headers: { "www-authenticate": challenge },
     };
 }
 /**

package/dist/service/handlers.d.ts

@@ -1,13 +1,10 @@
 import { Layer } from "effect";
 import { type HttpApiGroup } from "effect/unstable/httpapi";
-import type { Query } from "../query.js";
 import { type BuiltApi } from "./api.js";
 import type { AfterCommitHook } from "./config.js";
-import { type ConnectionTransportFactory } from "./connections.js";
+import type { ConnectionTransportFactory } from "./connections.js";
 import { type RateLimit } from "./rate-limit.js";
 import { OntologyBackend } from "./runtime-contract.js";
-/** The query the runtime receives: every key present only when set, and no empty `include`. */
-export declare function toQuery(decoded: Query): Query;
 /**
  * Sign-in checks one client may make per minute. A person checks once per sign-in, a few times at
  * most; the limit slows down anyone testing addresses to learn who the app's members are.

package/dist/service/handlers.js

@@ -1,19 +1,15 @@
 import { HttpServerResponse } from "effect/unstable/http";
 import { Effect, Layer, Schema } from "effect";
 import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
-import { editsFromWire, generatedResultFromWire, recordFromWire } from "../authoring-records.js";
-import { nameToWire } from "../authoring-names.js";
-import { principalFromWire } from "../authoring.js";
-import { toCamelCase } from "../names.js";
-import { PermissionDenied } from "../errors.js";
-import { missingPermission, permissionOf, READ_VERB } from "../permissions.js";
+import { STORAGE_GROUP } from "../storage/api.js";
+import { Conflict } from "../errors.js";
 import { EMAIL_PATTERN } from "../property.js";
 import { renderCatalog } from "../render.js";
 import { SERVICE_GROUP } from "./api.js";
 import { CurrentPrincipal } from "./authentication.js";
 import { catalogFor, graphOf } from "./catalog.js";
-import { OIDC_TOKEN_HEADER } from "./connections.js";
-import { InvalidActionInput, InvalidRequestBody, RequestId, SignInCheckLimited, schemaIssues, } from "./errors.js";
+import { InvalidRequestBody, SignInCheckLimited, schemaIssues } from "./errors.js";
+import { identityToken, makeOperations, requireRead, toQuery, } from "./operations.js";
 import { clientAddress, fixedWindowLimiter, } from "./rate-limit.js";
 import { OntologyBackend } from "./runtime-contract.js";
 import { ActionEnvelope } from "./schemas.js";
@@ -21,102 +17,6 @@ function dynamicGroup(api, identifier, build) {
     const group = HttpApiBuilder.group;
     return group(api, identifier, build);
 }
-/** The query the runtime receives: every key present only when set, and no empty `include`. */
-export function toQuery(decoded) {
-    const { include, ...rest } = decoded;
-    return include !== undefined && Object.keys(include).length > 0 ? { ...rest, include } : rest;
-}
-function page(result) {
-    return { items: result.items, nextCursor: result.nextCursor ?? null };
-}
-function relationshipTargets(plan) {
-    return new Map(plan.entities.map((planned) => [
-        planned.name,
-        new Map(planned.traversals.map((traversal) => [traversal.name, traversal.target])),
-    ]));
-}
-/** Adds the entities a `where` looks into through relationship filters, at any combinator depth. */
-function filterReads(where, targets, reads) {
-    for (const [key, condition] of Object.entries(where ?? {})) {
-        if (key === "and" || key === "or") {
-            for (const part of condition) {
-                filterReads(part, targets, reads);
-            }
-        }
-        else if (key === "not") {
-            filterReads(condition, targets, reads);
-        }
-        else {
-            const target = targets.get(key);
-            if (target !== undefined) {
-                reads.add(target);
-            }
-        }
-    }
-}
-/**
- * The entities a query on `entity` reads: the entity, the entity of every relationship it includes,
- * and the entity of every relationship its filter looks into.
- */
-function queryReads(entity, query, targets) {
-    const own = targets.get(entity) ?? new Map();
-    const reads = new Set([entity]);
-    for (const name of Object.keys(query.include ?? {})) {
-        const target = own.get(name);
-        if (target !== undefined) {
-            reads.add(target);
-        }
-    }
-    filterReads(query.where, own, reads);
-    return [...reads];
-}
-/**
- * Requires `<entity>:read` on every entity a request reads. A missing one answers 403 for the whole
- * request, before anything is read: nothing is silently left out.
- */
-function requireRead(entities) {
-    return Effect.gen(function* () {
-        const principal = yield* CurrentPrincipal;
-        const missing = missingPermission(entities.map((entity) => permissionOf(entity, READ_VERB)), principal);
-        if (missing !== undefined) {
-            return yield* new PermissionDenied({
-                permission: missing,
-                message: `Reading requires ${missing}, which the principal's roles do not grant.`,
-            });
-        }
-    });
-}
-/**
- * Follows a relationship from one record with the query language: the record's own
- * `<relationship>_id` for a `rel.one`, and for everything to-many a relationship path from the
- * target back to the record (`lead.notes` is notes whose `lead` is the lead, `lead.tags` is tags
- * some of whose `leads` is the lead), combined with the caller's query and paged like any find.
- */
-function traverse(planned, traversal, request, targets) {
-    return Effect.gen(function* () {
-        const backend = yield* OntologyBackend;
-        const { id } = request.params;
-        const query = toQuery(request.query);
-        yield* requireRead([planned.name, ...queryReads(traversal.target, query, targets)]);
-        const source = yield* backend.get({ entity: planned.name, id });
-        if (traversal.kind === "one") {
-            const targetId = source[`${traversal.name}_id`];
-            if (typeof targetId !== "string") {
-                return { items: [], nextCursor: null };
-            }
-            return page(yield* backend.find({
-                entity: traversal.target,
-                query: { ...query, where: { id: { eq: targetId } }, limit: 1 },
-            }));
-        }
-        const match = { id: { eq: id } };
-        const related = traversal.kind === "inverseOfOne"
-            ? { [traversal.opposite]: match }
-            : { [traversal.opposite]: { some: match } };
-        const where = query.where === undefined ? related : { and: [related, query.where] };
-        return page(yield* backend.find({ entity: traversal.target, query: { ...query, where } }));
-    });
-}
 function isJsonMediaType(contentType) {
     if (contentType === undefined || contentType.trim() === "") {
         return true;
@@ -141,68 +41,7 @@ function readEnvelope(request) {
         return yield* Schema.decodeUnknownEffect(ActionEnvelope)(body, { errors: "all" }).pipe(Effect.mapError((error) => new InvalidRequestBody({ reason: "invalid_request", issues: schemaIssues(error.issue) })));
     });
 }
-/**
- * The configured hook as `runAction` runs it after the commit. A failure is logged with the request
- * id here, so the action's caller still gets the committed result.
- */
-function afterCommitOf(hook, request, ontology) {
-    return (committed) => {
-        const definition = ontology.config.entities.find((entity) => nameToWire(entity.name) === committed.entity)?.definition;
-        return Effect.tryPromise(async () => hook({
-            entity: toCamelCase(committed.entity),
-            action: toCamelCase(committed.action),
-            principal: principalFromWire(committed.principal),
-            input: request.generated ? recordFromWire(committed.input, definition) : committed.input,
-            result: request.generated
-                ? generatedResultFromWire(committed.result, committed.action, definition)
-                : committed.result,
-            edits: editsFromWire(committed.edits, ontology.config.entities),
-            requestId: request.requestId,
-        })).pipe(Effect.catchCause((cause) => Effect.logError("ontology.after_commit.failed", cause).pipe(Effect.annotateLogs({
-            requestId: request.requestId,
-            action: `${committed.entity}.${committed.action}`,
-        }))));
-    };
-}
-/** The deployment's OIDC token: Vercel sets it on each request, and in the environment of builds. */
-function identityToken(request) {
-    const header = request.headers[OIDC_TOKEN_HEADER];
-    return typeof header === "string" && header !== "" ? header : process.env.VERCEL_OIDC_TOKEN;
-}
-function runAction(planned, { name, generated }, ontology, hook, connections) {
-    return ({ request }) => Effect.gen(function* () {
-        const backend = yield* OntologyBackend;
-        const principal = yield* CurrentPrincipal;
-        const requestId = yield* RequestId;
-        const envelope = yield* readEnvelope(request);
-        const validateOnly = envelope.options?.validateOnly === true;
-        const outcome = yield* backend.runAction({
-            entity: planned.name,
-            action: name,
-            input: envelope.input,
-            principal,
-            options: { validateOnly },
-            requestId,
-            connections: connections({
-                identityToken: identityToken(request),
-                audit: { action: `${planned.name}.${name}`, principalId: principal.id, requestId },
-            }),
-            ...(hook === undefined
-                ? {}
-                : { afterCommit: afterCommitOf(hook, { requestId, generated }, ontology) }),
-        });
-        const { issues } = outcome.validation;
-        if (!outcome.validation.ok && !validateOnly) {
-            return yield* new InvalidActionInput({ issues });
-        }
-        return {
-            result: outcome.result ?? null,
-            validation: { ok: outcome.validation.ok, issues },
-            edits: outcome.edits,
-        };
-    });
-}
-function entityHandlers(built, planned, hooks, targets, connections) {
+function entityHandlers(built, planned, operationsOf) {
     return dynamicGroup(built.api, planned.name, (handlers) => Effect.gen(function* () {
         if (planned.resolved.entity.definition.source !== undefined) {
             return handlers.handleRaw("sourceCollection", () => requireRead([planned.name]).pipe(Effect.andThen(() => HttpServerResponse.json({
@@ -211,46 +50,38 @@ function entityHandlers(built, planned, hooks, targets, connections) {
             }, { status: 404 }))));
         }
         const backend = yield* OntologyBackend;
-        // Every read checks the caller's permissions first; the backend is called only afterwards.
-        const find = (query) => requireRead(queryReads(planned.name, query, targets)).pipe(Effect.andThen(() => backend.find({ entity: planned.name, query })), Effect.map(page));
-        const readOwn = requireRead([planned.name]);
+        const operations = operationsOf(backend);
         let registered = handlers
-            .handle("find", (request) => find(toQuery(request.query)))
-            .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)));
+            .handle("find", (request) => operations.find(planned, toQuery(request.query)))
+            .handle("query", (request) => operations.find(planned, toQuery(request.payload)))
+            .handle("get", (request) => operations.get(planned, request.params.id))
+            .handle("history", (request) => operations.history(planned, request.params.id, request.query));
+        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)));
+            registered = registered.handle(`related.${traversal.name}`, (request) => operations.traverse(planned, traversal, request.params.id, toQuery(request.query)));
         }
         for (const action of planned.actions) {
-            const handler = runAction(planned, action, built.plan.ontology, hooks.get(`${planned.name}.${action.name}`), connections);
-            registered = registered.handleRaw(`actions.${action.name}`, (request) => handler(request).pipe(Effect.provideService(OntologyBackend, backend)));
+            registered = registered.handleRaw(`actions.${action.name}`, ({ request }) => readEnvelope(request).pipe(Effect.flatMap((envelope) => operations.runAction(planned, action, {
+                input: envelope.input,
+                validateOnly: envelope.options?.validateOnly === true,
+                ...(envelope.options === undefined ? {} : { options: envelope.options }),
+                identityToken: identityToken(request),
+            }))));
         }
         return registered;
     }));
 }
-/**
- * The caller, as `GET /api/ontology/me` answers: their user record and the roles and permissions
- * authentication resolved. It needs no permission: anyone may learn who they are and what they may do.
- */
-function callerOf(backend) {
-    return Effect.gen(function* () {
-        const principal = yield* CurrentPrincipal;
-        // Authentication resolved the principal from this user a moment ago; its absence is a defect.
-        const user = yield* backend.get({ entity: "user", id: principal.id }).pipe(Effect.orDie);
-        return {
-            user: {
-                id: principal.id,
-                name: String(user.name),
-                email: typeof user.email === "string" ? user.email : null,
-                kind: principal.kind,
-                active: user.active === true,
-            },
-            roles: principal.roles,
-            permissions: principal.permissions,
-        };
-    });
-}
 /**
  * Sign-in checks one client may make per minute. A person checks once per sign-in, a few times at
  * most; the limit slows down anyone testing addresses to learn who the app's members are.
@@ -277,7 +108,7 @@ function checkSignIn(backend, limiter) {
         return yield* backend.checkSignIn(email);
     });
 }
-function serviceHandlers(built) {
+function serviceHandlers(built, operationsOf) {
     const { manifest } = built.plan.ontology;
     const graph = graphOf(manifest);
     const signInLimiter = fixedWindowLimiter(SIGN_IN_CHECK_LIMIT);
@@ -295,7 +126,7 @@ function serviceHandlers(built) {
         return handlers
             .handle("catalog", (request) => Effect.map(permissionsFor(request.query.as), (permissions) => catalogFor(manifest, permissions)))
             .handle("graph", () => Effect.succeed(graph))
-            .handle("me", () => callerOf(backend))
+            .handle("me", () => operationsOf(backend).caller)
             .handle("openapi", () => Effect.sync(() => {
             if (openApi === undefined) {
                 openApi = OpenApi.fromApi(built.api);
@@ -324,12 +155,37 @@ 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 operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections);
     const layers = [
-        serviceHandlers(built),
-        ...built.plan.entities.map((planned) => entityHandlers(built, planned, hooks, targets, connections)),
+        serviceHandlers(built, operationsOf),
+        ...(built.plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))
+            ? [storageHandlers(built)]
+            : []),
+        ...built.plan.entities.map((planned) => entityHandlers(built, planned, operationsOf)),
     ];
     const [first, ...rest] = layers;
     return Layer.mergeAll(first, ...rest);

package/dist/service/mcp/server.d.ts

@@ -0,0 +1,24 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import type { BuiltApi } from "../api.js";
+import { type TokenVerifier } from "../authentication.js";
+import type { AfterCommitHook } from "../config.js";
+import type { ConnectionTransportFactory } from "../connections.js";
+import { RequestId } from "../errors.js";
+import { OntologyBackend } from "../runtime-contract.js";
+/** The URL path of the ontology's MCP server, outside `/api/ontology`: one per app. */
+export declare const MCP_PATH = "/mcp";
+/** The MCP revisions the server speaks, newest first. */
+export declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18"];
+export interface McpServerOptions {
+    readonly built: BuiltApi;
+    readonly hooks: ReadonlyMap<string, AfterCommitHook>;
+    readonly connections: ConnectionTransportFactory;
+    readonly verifyToken: TokenVerifier;
+}
+/**
+ * The ontology's MCP server at `POST /mcp`: Streamable HTTP without sessions, so any instance can
+ * answer any request. Its tools run the same operations as the HTTP routes, behind the same
+ * authentication. `GET` and `DELETE`, which open a server stream and end a session, answer 405.
+ */
+export declare function mcpLayer(options: McpServerOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;