@segmentstream-cloud/ontology 0.10.0 → 0.11.0

package/dist/migrate/storage.js

@@ -433,6 +433,87 @@ export const USER_ROLES_TABLE = "_user_roles";
  * secret only as a salted PBKDF2 hash.
  */
 export const API_KEYS_TABLE = "_api_keys";
+/** OAuth clients that registered themselves to connect agents to the MCP server. */
+export const OAUTH_CLIENTS_TABLE = "_oauth_clients";
+/** Authorization requests waiting for a member's consent, for a few minutes. */
+export const OAUTH_REQUESTS_TABLE = "_oauth_requests";
+/** What a member allowed a client to do: revoking a grant stops its tokens. */
+export const OAUTH_GRANTS_TABLE = "_oauth_grants";
+/** Authorization codes, access tokens and refresh tokens, stored only as SHA-256 hashes. */
+export const OAUTH_TOKENS_TABLE = "_oauth_tokens";
+/** The OAuth tables, in the order they are created. */
+export const OAUTH_TABLES = [
+    OAUTH_CLIENTS_TABLE,
+    OAUTH_REQUESTS_TABLE,
+    OAUTH_GRANTS_TABLE,
+    OAUTH_TOKENS_TABLE,
+];
+/** The OAuth tables of the MCP server's authorization server. Every statement is idempotent. */
+export const OAUTH_TABLES_DDL = [
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_CLIENTS_TABLE)} (`,
+        `  "id" text NOT NULL,`,
+        `  "name" text NOT NULL,`,
+        `  "redirect_uris" jsonb NOT NULL,`,
+        `  "auth_method" text NOT NULL,`,
+        `  "secret_hash" text,`,
+        `  "client_uri" text,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  CONSTRAINT "${OAUTH_CLIENTS_TABLE}_pkey" PRIMARY KEY ("id")`,
+        `)`,
+    ].join("\n"),
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_REQUESTS_TABLE)} (`,
+        `  "id" text NOT NULL,`,
+        `  "client_id" text NOT NULL,`,
+        `  "redirect_uri" text NOT NULL,`,
+        `  "state" text,`,
+        `  "code_challenge" text NOT NULL,`,
+        `  "scope" text NOT NULL,`,
+        `  "resource" text NOT NULL,`,
+        `  "expires_at" timestamptz NOT NULL,`,
+        `  CONSTRAINT "${OAUTH_REQUESTS_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${OAUTH_REQUESTS_TABLE}_client_id_fkey" FOREIGN KEY ("client_id") ` +
+            `REFERENCES ${quoteIdentifier(OAUTH_CLIENTS_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_GRANTS_TABLE)} (`,
+        `  "id" uuid NOT NULL,`,
+        `  "client_id" text NOT NULL,`,
+        `  "user_id" uuid NOT NULL,`,
+        `  "scope" text NOT NULL,`,
+        `  "resource" text NOT NULL,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  "revoked_at" timestamptz,`,
+        `  CONSTRAINT "${OAUTH_GRANTS_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${OAUTH_GRANTS_TABLE}_client_id_fkey" FOREIGN KEY ("client_id") ` +
+            `REFERENCES ${quoteIdentifier(OAUTH_CLIENTS_TABLE)} ("id") ON DELETE CASCADE,`,
+        `  CONSTRAINT "${OAUTH_GRANTS_TABLE}_user_id_fkey" FOREIGN KEY ("user_id") ` +
+            `REFERENCES ${quoteIdentifier(USER_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    `CREATE INDEX IF NOT EXISTS "${OAUTH_GRANTS_TABLE}_user_id_idx" ` +
+        `ON ${quoteIdentifier(OAUTH_GRANTS_TABLE)} ("user_id")`,
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_TOKENS_TABLE)} (`,
+        `  "hash" text NOT NULL,`,
+        `  "grant_id" uuid NOT NULL,`,
+        `  "kind" text NOT NULL,`,
+        `  "redirect_uri" text,`,
+        `  "code_challenge" text,`,
+        `  "expires_at" timestamptz NOT NULL,`,
+        `  "used_at" timestamptz,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  CONSTRAINT "${OAUTH_TOKENS_TABLE}_pkey" PRIMARY KEY ("hash"),`,
+        `  CONSTRAINT "${OAUTH_TOKENS_TABLE}_kind_check" CHECK ("kind" IN ('code', 'access', 'refresh')),`,
+        `  CONSTRAINT "${OAUTH_TOKENS_TABLE}_grant_id_fkey" FOREIGN KEY ("grant_id") ` +
+            `REFERENCES ${quoteIdentifier(OAUTH_GRANTS_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    `CREATE INDEX IF NOT EXISTS "${OAUTH_TOKENS_TABLE}_grant_id_idx" ` +
+        `ON ${quoteIdentifier(OAUTH_TOKENS_TABLE)} ("grant_id")`,
+];
 /**
  * The runtime's own tables beside the catalog. They are created with it, after the entity tables
  * because they refer to the built-in user table, and every statement is idempotent.
@@ -464,6 +545,7 @@ export const RUNTIME_TABLES_DDL = [
         `)`,
     ].join("\n"),
     `CREATE INDEX IF NOT EXISTS "${API_KEYS_TABLE}_user_id_idx" ON ${quoteIdentifier(API_KEYS_TABLE)} ("user_id")`,
+    ...OAUTH_TABLES_DDL,
 ];
 export function columnDefinition(column) {
     const parts = [quoteIdentifier(column.name), column.type];

package/dist/names.d.ts

@@ -21,7 +21,15 @@ export declare const HISTORY_SUFFIX = "_history";
 /** The combinators of the query language, which take the place of field names in a `where`. */
 export declare const RESERVED_MEMBER_NAMES: readonly ["and", "or", "not"];
 /** Routes of the ontology service under `/api/ontology/`, which an entity's routes would shadow. */
-export declare const RESERVED_ENTITY_NAMES: readonly ["graph", "status", "describe", "openapi", "docs", "mcp", "me"];
+export declare const RESERVED_ENTITY_NAMES: readonly ["graph", "status", "describe", "openapi", "docs", "mcp", "me", "oauth"];
+/** The MCP tools of every stored entity's reads: `lead_find`, `lead_get` and `lead_history`. */
+export declare const MCP_READ_TOOLS: readonly ["find", "get", "history"];
+/** The MCP tools of the ontology as a whole. No entity tool can take them: they have no underscore. */
+export declare const MCP_GLOBAL_TOOLS: readonly ["describe", "me"];
+/** The longest tool name that Claude and OpenAI accept. */
+export declare const MCP_TOOL_NAME_MAX_LENGTH = 64;
+/** The MCP tool of an entity's read or action: `lead_find`, `lead_change_status`. */
+export declare function mcpToolName(entity: string, operation: string): string;
 /** `/api/ontology/<entity>/{id}/history`, which a relationship's traversal would shadow. */
 export declare const RESERVED_RELATIONSHIP_NAMES: readonly ["history"];
 export declare function isSystemProperty(name: string): boolean;

package/dist/names.js

@@ -57,7 +57,18 @@ export const RESERVED_ENTITY_NAMES = [
     "docs",
     "mcp",
     "me",
+    "oauth",
 ];
+/** The MCP tools of every stored entity's reads: `lead_find`, `lead_get` and `lead_history`. */
+export const MCP_READ_TOOLS = ["find", "get", "history"];
+/** The MCP tools of the ontology as a whole. No entity tool can take them: they have no underscore. */
+export const MCP_GLOBAL_TOOLS = ["describe", "me"];
+/** The longest tool name that Claude and OpenAI accept. */
+export const MCP_TOOL_NAME_MAX_LENGTH = 64;
+/** The MCP tool of an entity's read or action: `lead_find`, `lead_change_status`. */
+export function mcpToolName(entity, operation) {
+    return `${entity}_${operation}`;
+}
 /** `/api/ontology/<entity>/{id}/history`, which a relationship's traversal would shadow. */
 export const RESERVED_RELATIONSHIP_NAMES = ["history"];
 export function isSystemProperty(name) {

package/dist/nitro.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The paths the ontology service answers, for the workspace's `ontology/nitro.config.ts`. They come
+ * from the SDK, so a path the service adds arrives with an upgrade and the config stays as it is.
+ * This entry imports nothing: Nitro loads it while it builds.
+ */
+export declare const ONTOLOGY_SERVICE_PATHS: readonly ["/api/ontology", "/api/ontology/**", "/mcp", "/.well-known/oauth-protected-resource", "/.well-known/oauth-protected-resource/mcp", "/.well-known/oauth-authorization-server"];
+/** A Nitro route to the service's handler, loaded on its first request. */
+export interface OntologyRoute {
+    readonly handler: string;
+    readonly lazy: true;
+}
+/** The Nitro routes that send every path of the ontology service to one handler. */
+export declare function ontologyRoutes(handler: string): Record<string, OntologyRoute>;

package/dist/nitro.js

@@ -0,0 +1,18 @@
+/**
+ * The paths the ontology service answers, for the workspace's `ontology/nitro.config.ts`. They come
+ * from the SDK, so a path the service adds arrives with an upgrade and the config stays as it is.
+ * This entry imports nothing: Nitro loads it while it builds.
+ */
+export const ONTOLOGY_SERVICE_PATHS = [
+    "/api/ontology",
+    "/api/ontology/**",
+    "/mcp",
+    // The MCP server's OAuth metadata, on the app's origin.
+    "/.well-known/oauth-protected-resource",
+    "/.well-known/oauth-protected-resource/mcp",
+    "/.well-known/oauth-authorization-server",
+];
+/** The Nitro routes that send every path of the ontology service to one handler. */
+export function ontologyRoutes(handler) {
+    return Object.fromEntries(ONTOLOGY_SERVICE_PATHS.map((path) => [path, { handler, lazy: true }]));
+}

package/dist/runtime/generated-actions.d.ts

@@ -1,3 +1,4 @@
+import { Schema } from "effect";
 import { type AnyAction } from "../action.js";
 import type { JsonSchemaObject } from "../analyze.js";
 import type { Ontology } from "../ontology.js";
@@ -14,6 +15,8 @@ export declare function upsertActionName(property: string): string;
  * and services by the app or the CLI.
  */
 export declare function generatedActions(ontology: Ontology, entityName: string): GeneratedActions;
+/** An action's input as JSON Schema (draft 2020-12), as the manifest describes authored actions. */
+export declare function actionInputJsonSchema(input: Schema.Top): JsonSchemaObject;
 /** A generated action, described as the manifest describes authored ones. */
 export interface GeneratedActionManifest {
     readonly name: string;

package/dist/runtime/generated-actions.js

@@ -166,7 +166,8 @@ function buildGeneratedActions(ontology, entityName) {
     }
     return actions;
 }
-function inputJsonSchema(input) {
+/** An action's input as JSON Schema (draft 2020-12), as the manifest describes authored actions. */
+export function actionInputJsonSchema(input) {
     const document = Schema.toJsonSchemaDocument(input, {
         includeAnnotationKey: (key) => key === REFERENCE_ANNOTATION || key === BLOB_UPLOAD_ANNOTATION,
         onExcessProperty: "error",
@@ -182,6 +183,6 @@ export function generatedActionManifests(ontology, entityName) {
         name,
         description: generated.description,
         permissions: generatedActionPermissions(entityName, name),
-        input: inputJsonSchema(generated.input),
+        input: actionInputJsonSchema(generated.input),
     }));
 }

package/dist/runtime/oauth.d.ts

@@ -0,0 +1,9 @@
+import { SqlClient } from "effect/unstable/sql";
+import type { Ontology } from "../ontology.js";
+import type { OAuthStore } from "../service/runtime-contract.js";
+/**
+ * The OAuth store on the runtime's OAuth tables, as `ontology_app`. Expiry is the database's
+ * `now()`; codes and refresh tokens are used with one `UPDATE … WHERE "used_at" IS NULL`, so two
+ * concurrent uses cannot both succeed.
+ */
+export declare function sqlOAuthStore(ontology: Ontology, sql: SqlClient.SqlClient): OAuthStore;

package/dist/runtime/oauth.js

@@ -0,0 +1,165 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { OAUTH_CLIENTS_TABLE, OAUTH_GRANTS_TABLE, OAUTH_REQUESTS_TABLE, OAUTH_TOKENS_TABLE, } from "../migrate/storage.js";
+import { resolveMemberById } from "./principals.js";
+const CLIENTS = `"${OAUTH_CLIENTS_TABLE}"`;
+const REQUESTS = `"${OAUTH_REQUESTS_TABLE}"`;
+const GRANTS = `"${OAUTH_GRANTS_TABLE}"`;
+const TOKENS = `"${OAUTH_TOKENS_TABLE}"`;
+const CLIENT_COLUMNS = `"id", "name", "redirect_uris"::text AS "redirect_uris", "auth_method", "secret_hash", ` +
+    `"client_uri"`;
+/** A timestamp as epoch milliseconds, which every driver returns as a plain number. */
+function epochMs(column) {
+    return `(extract(epoch from ${column}) * 1000)::double precision`;
+}
+const REQUEST_COLUMNS = `"id", "client_id", "redirect_uri", "state", "code_challenge", "scope", "resource", ` +
+    `${epochMs(`"expires_at"`)} AS "expires_at"`;
+/** The grant's columns, read through the alias `g`. */
+const GRANT_COLUMNS = `"g"."id"::text AS "grant_id", "g"."client_id" AS "client_id", ` +
+    `"g"."user_id"::text AS "user_id", "g"."scope" AS "scope", "g"."resource" AS "resource"`;
+function text(value) {
+    return String(value);
+}
+function nullableText(value) {
+    return value === null || value === undefined ? null : String(value);
+}
+function date(value) {
+    return new Date(Number(value));
+}
+function clientOf(row) {
+    return {
+        id: text(row.id),
+        name: text(row.name),
+        redirectUris: JSON.parse(text(row.redirect_uris)),
+        authMethod: text(row.auth_method),
+        secretHash: nullableText(row.secret_hash),
+        clientUri: nullableText(row.client_uri),
+    };
+}
+function requestOf(row) {
+    return {
+        id: text(row.id),
+        clientId: text(row.client_id),
+        redirectUri: text(row.redirect_uri),
+        state: nullableText(row.state),
+        codeChallenge: text(row.code_challenge),
+        scope: text(row.scope),
+        resource: text(row.resource),
+        expiresAt: date(row.expires_at),
+    };
+}
+function grantOf(row) {
+    return {
+        id: text(row.grant_id),
+        clientId: text(row.client_id),
+        userId: text(row.user_id),
+        scope: text(row.scope),
+        resource: text(row.resource),
+    };
+}
+function tokenOf(row) {
+    return {
+        hash: text(row.hash),
+        grantId: text(row.grant_id),
+        kind: text(row.kind),
+        expiresAt: date(row.expires_at),
+        ...(row.redirect_uri === null ? {} : { redirectUri: text(row.redirect_uri) }),
+        ...(row.code_challenge === null ? {} : { codeChallenge: text(row.code_challenge) }),
+    };
+}
+const INSERT_TOKEN = `INSERT INTO ${TOKENS} ("hash", "grant_id", "kind", "redirect_uri", "code_challenge", ` +
+    `"expires_at") VALUES ($1, $2::uuid, $3, $4, $5, $6::timestamptz)`;
+function tokenValues(token) {
+    return [
+        token.hash,
+        token.grantId,
+        token.kind,
+        token.redirectUri ?? null,
+        token.codeChallenge ?? null,
+        token.expiresAt.toISOString(),
+    ];
+}
+/**
+ * The OAuth store on the runtime's OAuth tables, as `ontology_app`. Expiry is the database's
+ * `now()`; codes and refresh tokens are used with one `UPDATE … WHERE "used_at" IS NULL`, so two
+ * concurrent uses cannot both succeed.
+ */
+export function sqlOAuthStore(ontology, sql) {
+    const rows = (statement, values = []) => sql.unsafe(statement, values).pipe(Effect.orDie);
+    return {
+        saveClient: (client) => rows(`INSERT INTO ${CLIENTS} ("id", "name", "redirect_uris", "auth_method", "secret_hash", ` +
+            `"client_uri") VALUES ($1, $2, $3::jsonb, $4, $5, $6)`, [
+            client.id,
+            client.name,
+            JSON.stringify(client.redirectUris),
+            client.authMethod,
+            client.secretHash,
+            client.clientUri,
+        ]).pipe(Effect.asVoid),
+        findClient: (id) => rows(`SELECT ${CLIENT_COLUMNS} FROM ${CLIENTS} WHERE "id" = $1`, [id]).pipe(Effect.map(([row]) => (row === undefined ? undefined : clientOf(row)))),
+        saveRequest: (request) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`DELETE FROM ${REQUESTS} WHERE "expires_at" <= now()`);
+            yield* rows(`INSERT INTO ${REQUESTS} ("id", "client_id", "redirect_uri", "state", ` +
+                `"code_challenge", "scope", "resource", "expires_at") ` +
+                `VALUES ($1, $2, $3, $4, $5, $6, $7, $8::timestamptz)`, [
+                request.id,
+                request.clientId,
+                request.redirectUri,
+                request.state,
+                request.codeChallenge,
+                request.scope,
+                request.resource,
+                request.expiresAt.toISOString(),
+            ]);
+        }))
+            .pipe(Effect.orDie),
+        findRequest: (id) => rows(`SELECT ${REQUEST_COLUMNS} FROM ${REQUESTS} WHERE "id" = $1 AND "expires_at" > now()`, [
+            id,
+        ]).pipe(Effect.map(([row]) => (row === undefined ? undefined : requestOf(row)))),
+        takeRequest: (id) => rows(`DELETE FROM ${REQUESTS} WHERE "id" = $1 AND "expires_at" > now() ` +
+            `RETURNING ${REQUEST_COLUMNS}`, [id]).pipe(Effect.map(([row]) => (row === undefined ? undefined : requestOf(row)))),
+        saveGrant: (grant, code) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`INSERT INTO ${GRANTS} ("id", "client_id", "user_id", "scope", "resource") ` +
+                `VALUES ($1::uuid, $2, $3::uuid, $4, $5)`, [grant.id, grant.clientId, grant.userId, grant.scope, grant.resource]);
+            yield* rows(INSERT_TOKEN, tokenValues(code));
+        }))
+            .pipe(Effect.orDie),
+        useToken: (hash, kind) => Effect.gen(function* () {
+            const [used] = yield* rows(`UPDATE ${TOKENS} AS "t" SET "used_at" = now() FROM ${GRANTS} AS "g" ` +
+                `WHERE "t"."hash" = $1 AND "t"."kind" = $2 AND "t"."used_at" IS NULL ` +
+                `AND "t"."expires_at" > now() AND "g"."id" = "t"."grant_id" ` +
+                `AND "g"."revoked_at" IS NULL ` +
+                `RETURNING "t"."hash" AS "hash", "t"."kind" AS "kind", ` +
+                `"t"."redirect_uri" AS "redirect_uri", "t"."code_challenge" AS "code_challenge", ` +
+                `${epochMs(`"t"."expires_at"`)} AS "expires_at", ${GRANT_COLUMNS}`, [hash, kind]);
+            if (used !== undefined) {
+                return { status: "valid", token: tokenOf(used), grant: grantOf(used) };
+            }
+            const [reused] = yield* rows(`SELECT ${GRANT_COLUMNS} FROM ${TOKENS} AS "t" ` +
+                `JOIN ${GRANTS} AS "g" ON "g"."id" = "t"."grant_id" ` +
+                `WHERE "t"."hash" = $1 AND "t"."kind" = $2 AND "t"."used_at" IS NOT NULL ` +
+                `AND "t"."expires_at" > now() AND "g"."revoked_at" IS NULL`, [hash, kind]);
+            return reused === undefined
+                ? { status: "invalid" }
+                : { status: "reused", grant: grantOf(reused) };
+        }),
+        saveTokens: (tokens) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`DELETE FROM ${TOKENS} WHERE "expires_at" <= now()`);
+            for (const token of tokens) {
+                yield* rows(INSERT_TOKEN, tokenValues(token));
+            }
+        }))
+            .pipe(Effect.orDie),
+        findAccess: (hash) => rows(`SELECT ${GRANT_COLUMNS} FROM ${TOKENS} AS "t" ` +
+            `JOIN ${GRANTS} AS "g" ON "g"."id" = "t"."grant_id" ` +
+            `WHERE "t"."hash" = $1 AND "t"."kind" = 'access' AND "t"."expires_at" > now() ` +
+            `AND "g"."revoked_at" IS NULL`, [hash]).pipe(Effect.map(([row]) => (row === undefined ? undefined : grantOf(row)))),
+        findGrantOfToken: (hash) => rows(`SELECT ${GRANT_COLUMNS} FROM ${TOKENS} AS "t" ` +
+            `JOIN ${GRANTS} AS "g" ON "g"."id" = "t"."grant_id" WHERE "t"."hash" = $1`, [hash]).pipe(Effect.map(([row]) => (row === undefined ? undefined : grantOf(row)))),
+        revokeGrant: (id) => rows(`UPDATE ${GRANTS} SET "revoked_at" = now() WHERE "id" = $1::uuid AND "revoked_at" IS NULL`, [id]).pipe(Effect.asVoid),
+        memberPrincipal: (userId) => resolveMemberById(ontology, userId).pipe(Effect.provideService(SqlClient.SqlClient, sql)),
+    };
+}

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/service-binding.js

@@ -7,6 +7,7 @@ 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";
@@ -59,6 +60,7 @@ export function backendLayer(ontology, blobStorage) {
             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),
         });
     }));
 }

package/dist/service/api.js

@@ -5,6 +5,7 @@ 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";
@@ -58,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);
 }
@@ -75,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);

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

@@ -73,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/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;