@segmentstream-cloud/ontology 0.13.0 → 0.14.0

package/dist/service/agent/server.js

@@ -0,0 +1,235 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Layer, Redacted, Result, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { schemaIssues } from "../../runtime/validation.js";
+import { BASE_PATH } from "../api.js";
+import { CurrentPrincipal, withPrincipal, } from "../authentication.js";
+import { RequestId, errorBodyForWire, forbidden, notFound, rateLimited, toServerResponse, unauthorized, unavailable, } from "../errors.js";
+import { secretHash } from "../oauth/protocol.js";
+import { clientAddress, fixedWindowLimiter, } from "../rate-limit.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { logRuntimeRejection } from "../runtime-identity.js";
+import { PAIRING_TTL_MS, PairingRequest, canonicalPairingCode, identityForWire, memberForWire, newPairingCode, } from "./protocol.js";
+/** The agent's endpoints, under the ontology service's path. */
+export const AGENT_PATH = `${BASE_PATH}/agent`;
+const PAIRINGS_PATH = `${AGENT_PATH}/pairings`;
+const IDENTITIES_PATH = `${AGENT_PATH}/identities`;
+/**
+ * Pairings one client address may start per minute; each one is a row in the database. The agent's
+ * functions share a few egress addresses, so the limit leaves room for a busy channel.
+ */
+export const PAIRING_LIMIT = { limit: 60, windowMs: 60_000, maxKeys: 10_000 };
+/** A fresh code collides with a live one about never; a few attempts make it never in practice. */
+const CODE_ATTEMPTS = 3;
+const NO_STORE = { "cache-control": "no-store" };
+function json(body, status = 200) {
+    return HttpServerResponse.jsonUnsafe(body, { status, headers: NO_STORE });
+}
+function jsonBody(request) {
+    return Effect.map(Effect.orDie(request.text), (text) => {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
+function invalidBody(requestId, issues) {
+    return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+        error: "invalid_request",
+        detail: "The request body is invalid.",
+        requestId,
+        issues,
+    }), { status: 400 });
+}
+function pairingNotFound(requestId) {
+    return toServerResponse(notFound(requestId, "The pairing code expired or was already used. Send the agent a message for a new link."));
+}
+function routeParam(name) {
+    return Effect.map(HttpRouter.params, (params) => params[name] ?? "");
+}
+/**
+ * `POST /api/ontology/agent/pairings` (runtime): a sender the agent does not know gets a short code
+ * that a signed-in member approves on the app's connect page. Only the code's hash is stored.
+ */
+function createPairing(store, limiter) {
+    return (request) => Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const retryAfter = limiter.take(clientAddress(request));
+        if (retryAfter !== undefined) {
+            return toServerResponse(rateLimited(requestId, "Too many pairings; try again in a minute.", retryAfter));
+        }
+        const body = yield* jsonBody(request);
+        const decoded = Schema.decodeUnknownResult(PairingRequest)(body, {
+            errors: "all",
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            return invalidBody(requestId, schemaIssues(decoded.failure));
+        }
+        const { provider, external_id: externalId, display } = decoded.success;
+        const trimmedDisplay = display?.trim() || null;
+        for (let attempt = 0; attempt < CODE_ATTEMPTS; attempt++) {
+            const code = newPairingCode();
+            const expiresAt = new Date(Date.now() + PAIRING_TTL_MS);
+            const saved = yield* store.savePairing({
+                id: randomUUID(),
+                codeHash: secretHash(code),
+                provider,
+                externalId,
+                display: trimmedDisplay,
+                expiresAt,
+            });
+            if (saved) {
+                return json({ code, expires_at: expiresAt.toISOString() }, 201);
+            }
+        }
+        return yield* Effect.die(new Error("No free pairing code after several attempts."));
+    });
+}
+/** `GET /api/ontology/agent/pairings/:code` (member): what the connect page shows. */
+function describePairing(store) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const code = canonicalPairingCode(yield* routeParam("code"));
+        const pairing = code === undefined ? undefined : yield* store.findPairing(secretHash(code));
+        if (pairing === undefined) {
+            return pairingNotFound(requestId);
+        }
+        return json({
+            provider: pairing.provider,
+            display: pairing.display,
+            expires_at: pairing.expiresAt.toISOString(),
+        });
+    });
+}
+/**
+ * `POST /api/ontology/agent/pairings/:code/approve` (member): pairs the account with the signed-in
+ * member, once. The account's previous identity and the member's previous identity on the same
+ * channel stop working: each has one live identity per channel, so an approval tricked out of a
+ * member displaces their own account, which they notice.
+ */
+function approvePairing(store, member) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const code = canonicalPairingCode(yield* routeParam("code"));
+        const identity = code === undefined
+            ? undefined
+            : yield* store.approvePairing({
+                codeHash: secretHash(code),
+                userId: member.id,
+                identityId: randomUUID(),
+            });
+        if (identity === undefined) {
+            return pairingNotFound(requestId);
+        }
+        yield* Effect.logInfo("ontology.agent.paired").pipe(Effect.annotateLogs({ identityId: identity.id, provider: identity.provider, requestId }));
+        return json({ identity: identityForWire(identity) });
+    });
+}
+/**
+ * `GET /api/ontology/agent/identities/:provider/:external_id` (runtime): the member an account acts
+ * as, with the roles they hold now. 404 for an account nobody paired; 403 once its identity was
+ * revoked or its member deactivated.
+ */
+function resolveIdentity(store) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const provider = yield* routeParam("provider");
+        const externalId = yield* routeParam("external_id");
+        const identity = yield* store.findIdentity({ provider, externalId });
+        if (identity === undefined) {
+            return toServerResponse(notFound(requestId, "No member paired this account."));
+        }
+        if (identity.revokedAt !== null) {
+            return toServerResponse(forbidden(requestId, "The account's pairing was revoked."));
+        }
+        const member = yield* store.member(identity.userId);
+        if (member === undefined) {
+            return toServerResponse(forbidden(requestId, "The member is inactive."));
+        }
+        return json(memberForWire(member));
+    });
+}
+/** `GET /api/ontology/agent/identities` (member): the member's own live identities. */
+function listIdentities(store, member) {
+    return Effect.gen(function* () {
+        const identities = yield* store.listIdentities(member.id);
+        return json({ identities: identities.map(identityForWire) });
+    });
+}
+/** `DELETE /api/ontology/agent/identities/:id` (member): revokes one of the member's identities. */
+function revokeIdentity(store, member) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const id = yield* routeParam("id");
+        const revoked = yield* store.revokeIdentity({ id, userId: member.id });
+        if (!revoked) {
+            return toServerResponse(notFound(requestId, "You have no such identity."));
+        }
+        yield* Effect.logInfo("ontology.agent.unpaired").pipe(Effect.annotateLogs({ identityId: id, requestId }));
+        return HttpServerResponse.empty({ status: 204, headers: NO_STORE });
+    });
+}
+/**
+ * The routes that pair channel accounts with members for the app's own agent. Runtime routes take
+ * only the deployment's runtime token. Member routes take a member's Neon Auth session or token, and
+ * refuse API keys and the runtime, even acting as a member: only the member pairs or unpairs.
+ * Without the agent tables, it serves nothing.
+ */
+export function agentLayer(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const store = backend.agents;
+        if (store === undefined) {
+            return;
+        }
+        const limiter = fixedWindowLimiter(PAIRING_LIMIT);
+        const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
+        const bearerOf = (request) => Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request);
+        const asRuntime = (answer) => (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const bearer = yield* bearerOf(request);
+            const token = Redacted.value(bearer);
+            const verified = options.verifyRuntime === undefined || token === ""
+                ? undefined
+                : yield* Effect.promise(() => options.verifyRuntime(token));
+            switch (verified?.status) {
+                case "valid":
+                    return yield* answer(request);
+                case "invalid":
+                    yield* logRuntimeRejection(verified.reason);
+                    return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked."));
+                case "unavailable":
+                    return toServerResponse(unavailable(requestId));
+                default:
+                    // Any other credential is authenticated as usual, so that it gets the usual 401, and
+                    // then refused: these routes are the agent's.
+                    return yield* withPrincipal(bearer, options.verifyToken, backend, Effect.succeed(toServerResponse(forbidden(requestId, "Only the app's agent calls this route."))));
+            }
+        });
+        const asMember = (answer) => (request) => Effect.gen(function* () {
+            const bearer = yield* bearerOf(request);
+            const decided = Effect.gen(function* () {
+                const requestId = yield* RequestId;
+                const principal = yield* CurrentPrincipal;
+                if (principal.kind !== "member") {
+                    return toServerResponse(forbidden(requestId, "Only a signed-in member can pair the app's agent."));
+                }
+                return yield* answer(request, principal);
+            });
+            return yield* withPrincipal(bearer, options.verifyToken, backend, decided, {
+                session: { request, exchange: options.exchangeSession },
+            });
+        });
+        yield* router.add("POST", PAIRINGS_PATH, asRuntime(createPairing(store, limiter)));
+        yield* router.add("GET", `${PAIRINGS_PATH}/:code`, asMember(() => describePairing(store)));
+        yield* router.add("POST", `${PAIRINGS_PATH}/:code/approve`, asMember((_, member) => approvePairing(store, member)));
+        yield* router.add("GET", IDENTITIES_PATH, asMember((_, member) => listIdentities(store, member)));
+        yield* router.add("GET", `${IDENTITIES_PATH}/:provider/:external_id`, asRuntime(() => resolveIdentity(store)));
+        yield* router.add("DELETE", `${IDENTITIES_PATH}/:id`, asMember((_, member) => revokeIdentity(store, member)));
+    }));
+}

package/dist/service/authentication.d.ts

@@ -6,6 +6,7 @@ import type { Principal } from "../runtime.js";
 import type { NeonAuthEnvironment } from "./config.js";
 import { RequestId } from "./errors.js";
 import { OntologyBackend, type SignInIdentity } from "./runtime-contract.js";
+import { type RuntimeCredential, type RuntimeTokenVerifier } from "./runtime-identity.js";
 declare const CurrentPrincipal_base: Context.ServiceClass<CurrentPrincipal, "@segmentstream-cloud/ontology/CurrentPrincipal", Principal>;
 /** The principal the request runs as, provided by {@link Authentication}. */
 export declare class CurrentPrincipal extends CurrentPrincipal_base {
@@ -23,9 +24,10 @@ declare const Authentication_base: HttpApiMiddleware.ServiceClass<Authentication
     readonly bearer: HttpApiSecurity.Http;
 }, CurrentPrincipal, readonly [import("effect/Schema").Top, import("effect/Schema").Top, import("effect/Schema").Top], RequestId>>;
 /**
- * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token
- * 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.
+ * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token,
+ * an API key or the deployment's runtime token acting as a member, all as `Authorization: Bearer …`;
+ * without one, the app's Neon Auth session cookie. Failures answer the request directly, before its
+ * input is decoded.
  */
 export declare class Authentication extends Authentication_base {
 }
@@ -115,6 +117,9 @@ type Authenticated = {
     readonly status: "rejected";
 } | {
     readonly status: "not_invited";
+} | {
+    readonly status: "forbidden";
+    readonly detail: string;
 } | {
     readonly status: "unavailable";
 };
@@ -125,6 +130,11 @@ export interface CredentialOptions {
      * an access token is rejected, as it was issued for the MCP server only.
      */
     readonly oauthResource?: string;
+    /**
+     * The deployment's own runtime token may authenticate here, acting as the member it names. Without
+     * it a runtime token is just an invalid token.
+     */
+    readonly runtime?: RuntimeCredential;
 }
 /** Resolves a bearer credential to a principal. */
 export declare function authenticate(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier, options?: CredentialOptions): Effect.Effect<Authenticated, never, OntologyBackend>;
@@ -147,7 +157,8 @@ export declare function withPrincipal<E, R>(credential: Redacted.Redacted<string
 }): 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.
+ * a request without a bearer token may authenticate with the app's Neon Auth session cookie; with
+ * `verifyRuntime`, the deployment's own runtime token may act as the member it names.
  */
-export declare function authenticationLayer(verifyToken: TokenVerifier, exchangeSession?: SessionExchange): Layer.Layer<Authentication, never, OntologyBackend>;
+export declare function authenticationLayer(verifyToken: TokenVerifier, exchangeSession?: SessionExchange, verifyRuntime?: RuntimeTokenVerifier): Layer.Layer<Authentication, never, OntologyBackend>;
 export {};

package/dist/service/authentication.js

@@ -3,9 +3,10 @@ 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, crossOriginSession, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
+import { RequestId, crossOriginSession, forbidden, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
 import { ACCESS_TOKEN_PREFIX, principalOfAccessToken } from "./oauth/protocol.js";
 import { OntologyBackend } from "./runtime-contract.js";
+import { ACT_AS_HEADER, logRuntimeRejection, runtimeCredential, } from "./runtime-identity.js";
 import { ErrorSchemas } from "./schemas.js";
 const CLOCK_TOLERANCE_SECONDS = 5;
 const JWKS_TIMEOUT_MS = 5_000;
@@ -13,9 +14,10 @@ const JWKS_TIMEOUT_MS = 5_000;
 export class CurrentPrincipal extends Context.Service()("@segmentstream-cloud/ontology/CurrentPrincipal") {
 }
 /**
- * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token
- * 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.
+ * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token,
+ * an API key or the deployment's runtime token acting as a member, 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: {
@@ -274,6 +276,29 @@ function sessionMayAuthenticate(request) {
     const origin = request.headers.origin;
     return origin !== undefined && origin === requestOrigin(request);
 }
+/**
+ * The member a verified runtime caller acts for: the member `X-SegmentStream-Act-As` names, with the
+ * roles they hold now, while they are active and paired with the agent. Without the header, the
+ * runtime may call only the agent's own routes, which authenticate it themselves.
+ */
+function actingMember(actAs) {
+    return Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        if (actAs === undefined) {
+            return {
+                status: "forbidden",
+                detail: `The app's agent names the member it acts for in ${ACT_AS_HEADER}.`,
+            };
+        }
+        const member = backend.agents === undefined ? undefined : yield* backend.agents.actingMember(actAs);
+        return member === undefined
+            ? {
+                status: "forbidden",
+                detail: "The member is inactive or has not paired with the app's agent.",
+            }
+            : { status: "authenticated", principal: member };
+    });
+}
 /** Resolves a bearer credential to a principal. */
 export function authenticate(credential, verifyToken, options = {}) {
     return Effect.gen(function* () {
@@ -296,6 +321,21 @@ export function authenticate(credential, verifyToken, options = {}) {
                 ? { status: "rejected" }
                 : { status: "authenticated", principal: service };
         }
+        if (options.runtime !== undefined) {
+            const { verify, actAs } = options.runtime;
+            const runtime = yield* Effect.promise(() => verify(token));
+            switch (runtime.status) {
+                case "valid":
+                    return yield* actingMember(actAs);
+                case "invalid":
+                    yield* logRuntimeRejection(runtime.reason);
+                    return { status: "rejected" };
+                case "unavailable":
+                    return { status: "unavailable" };
+                case "other":
+                    break;
+            }
+        }
         const verification = yield* Effect.promise(() => verifyToken(token));
         if (verification.status !== "valid") {
             return verification.status === "invalid"
@@ -358,6 +398,8 @@ export function withPrincipal(credential, verifyToken, backend, effect, options
                 return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked.", options.challenge?.(false)));
             case "not_invited":
                 return toServerResponse(notInvited(requestId));
+            case "forbidden":
+                return toServerResponse(forbidden(requestId, outcome.detail));
             case "cross_origin":
                 return toServerResponse(crossOriginSession(requestId));
             case "unavailable":
@@ -369,16 +411,19 @@ export function withPrincipal(credential, verifyToken, backend, effect, options
 }
 /**
  * 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.
+ * a request without a bearer token may authenticate with the app's Neon Auth session cookie; with
+ * `verifyRuntime`, the deployment's own runtime token may act as the member it names.
  */
-export function authenticationLayer(verifyToken, exchangeSession) {
+export function authenticationLayer(verifyToken, exchangeSession, verifyRuntime) {
     return Layer.effect(Authentication, Effect.gen(function* () {
         const backend = yield* OntologyBackend;
         return Authentication.of({
             bearer: (httpEffect, { credential }) => Effect.gen(function* () {
                 const request = yield* HttpServerRequest.HttpServerRequest;
+                const runtime = runtimeCredential(verifyRuntime, request);
                 return yield* withPrincipal(credential, verifyToken, backend, httpEffect, {
                     session: { request, exchange: exchangeSession },
+                    ...(runtime === undefined ? {} : { runtime }),
                 });
             }),
         });

package/dist/service/config.d.ts

@@ -3,6 +3,7 @@ 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";
+import type { RuntimeIdentityConfig } from "./runtime-identity.js";
 /** The environment of the workspace deployment's ontology service. */
 export declare const ENVIRONMENT_VARIABLES: {
     readonly databaseUrl: "SEGMENTSTREAM_ONTOLOGY_DATABASE_URL";
@@ -25,6 +26,17 @@ export declare const NEON_AUTH_ENVIRONMENT_VARIABLES: {
     readonly baseUrl: "NEON_AUTH_BASE_URL";
     readonly jwksUrl: "NEON_AUTH_JWKS_URL";
 };
+/**
+ * The deployment's own runtime callers, such as the app's agent: the issuer and the audience of the
+ * team's Vercel OIDC tokens, set together by the platform on deployments that have an agent. Without
+ * them a runtime token is an invalid token. Tokens must also name the project in Vercel's
+ * `VERCEL_PROJECT_ID`, as the agent runs in the same Vercel project as the ontology service.
+ */
+export declare const RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES: {
+    readonly issuer: "SEGMENTSTREAM_RUNTIME_OIDC_ISSUER";
+    readonly audience: "SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE";
+    readonly projectId: "VERCEL_PROJECT_ID";
+};
 /** Where the workspace's Neon Auth issues and publishes the keys of its users' tokens. */
 export interface NeonAuthEnvironment {
     /** The Auth URL, such as `https://ep-….neon.tech/ontology/auth`. Its origin is the issuer. */
@@ -51,6 +63,11 @@ export interface OntologyEnvironment {
     readonly appCredential?: Redacted.Redacted<string>;
     /** Present once the workspace has Neon Auth: members then sign in with its tokens. */
     readonly neonAuth?: NeonAuthEnvironment;
+    /**
+     * Present on deployments with a runtime caller: the deployment's own Vercel OIDC tokens then
+     * authenticate, acting as the member `X-SegmentStream-Act-As` names.
+     */
+    readonly runtimeIdentity?: RuntimeIdentityConfig;
     /**
      * The local grant `segmentstream exec --connection …` passed, in development. Without it, actions
      * call connections through SegmentStream with the deployment's Vercel OIDC token.
@@ -99,8 +116,8 @@ export declare class OntologyServiceConfigError extends OntologyServiceConfigErr
 /**
  * Reads the service's configuration from the environment. It fails closed: a missing or invalid
  * variable throws {@link OntologyServiceConfigError} naming every missing variable, and never the
- * value of the database URL. The Neon Auth variables are optional, but only as a pair. The app
- * credential is optional and kept redacted.
+ * value of the database URL. The Neon Auth and runtime identity variables are optional, but only as
+ * pairs. The app credential is optional and kept redacted.
  */
 export declare function configFromEnv(environment?: Readonly<Record<string, string | undefined>>): OntologyEnvironment;
 export {};

package/dist/service/config.js

@@ -23,6 +23,17 @@ export const NEON_AUTH_ENVIRONMENT_VARIABLES = {
     baseUrl: "NEON_AUTH_BASE_URL",
     jwksUrl: "NEON_AUTH_JWKS_URL",
 };
+/**
+ * The deployment's own runtime callers, such as the app's agent: the issuer and the audience of the
+ * team's Vercel OIDC tokens, set together by the platform on deployments that have an agent. Without
+ * them a runtime token is an invalid token. Tokens must also name the project in Vercel's
+ * `VERCEL_PROJECT_ID`, as the agent runs in the same Vercel project as the ontology service.
+ */
+export const RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES = {
+    issuer: "SEGMENTSTREAM_RUNTIME_OIDC_ISSUER",
+    audience: "SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE",
+    projectId: "VERCEL_PROJECT_ID",
+};
 /** The service cannot start: its configuration is incomplete or invalid. */
 export class OntologyServiceConfigError extends Schema.TaggedError()("OntologyServiceConfigError", { message: Schema.String }) {
 }
@@ -60,6 +71,35 @@ function neonAuthFromEnv(read) {
         jwksUrl: httpUrl(NEON_AUTH_ENVIRONMENT_VARIABLES.jwksUrl, read(NEON_AUTH_ENVIRONMENT_VARIABLES.jwksUrl)).href,
     };
 }
+/**
+ * The runtime issuer and audience, both or neither, and the project the tokens must name. A partial
+ * configuration is a broken deployment, so the service refuses to start rather than run without the
+ * agent's identity, or trust tokens of every project of the team.
+ */
+function runtimeIdentityFromEnv(read) {
+    const { issuer, audience, projectId } = RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES;
+    const pair = [issuer, audience];
+    const missingPair = pair.filter((name) => read(name) === "");
+    if (missingPair.length === pair.length) {
+        return undefined;
+    }
+    if (missingPair.length > 0) {
+        throw new OntologyServiceConfigError({
+            message: `The ontology service cannot start: ${pair.join(" and ")} are set together; ` +
+                `${missingPair.join(", ")} is not set.`,
+        });
+    }
+    if (read(projectId) === "") {
+        throw new OntologyServiceConfigError({
+            message: `The ontology service cannot start: ${projectId} is not set, which runtime tokens must name.`,
+        });
+    }
+    return {
+        issuer: httpUrl(issuer, read(issuer)).href.replace(/\/+$/, ""),
+        audience: read(audience),
+        projectId: read(projectId),
+    };
+}
 function checkDatabaseUrl(name, value) {
     // The value is a credential: errors name the variable, never the value.
     if (!URL.canParse(value)) {
@@ -76,8 +116,8 @@ function checkDatabaseUrl(name, value) {
 /**
  * Reads the service's configuration from the environment. It fails closed: a missing or invalid
  * variable throws {@link OntologyServiceConfigError} naming every missing variable, and never the
- * value of the database URL. The Neon Auth variables are optional, but only as a pair. The app
- * credential is optional and kept redacted.
+ * value of the database URL. The Neon Auth and runtime identity variables are optional, but only as
+ * pairs. The app credential is optional and kept redacted.
  */
 export function configFromEnv(environment = process.env) {
     const read = (name) => environment[name]?.trim() ?? "";
@@ -90,6 +130,7 @@ export function configFromEnv(environment = process.env) {
         });
     }
     const neonAuth = neonAuthFromEnv(read);
+    const runtimeIdentity = runtimeIdentityFromEnv(read);
     const localConnections = localConnectionsFromEnv(environment);
     let blobStorage;
     if (read("SEGMENTSTREAM_ONTOLOGY_STORAGE")) {
@@ -118,6 +159,7 @@ export function configFromEnv(environment = process.env) {
             ? { appCredential: Redacted.make(read(APP_CREDENTIAL_VARIABLE)) }
             : {}),
         ...(neonAuth === undefined ? {} : { neonAuth }),
+        ...(runtimeIdentity === undefined ? {} : { runtimeIdentity }),
         ...(localConnections === undefined ? {} : { localConnections }),
     };
 }

package/dist/service/errors.d.ts

@@ -92,6 +92,12 @@ export declare function notInvited(requestId: string): ErrorResponse;
  * 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;
+/** The caller is authenticated but may not do this; the detail says why. */
+export declare function forbidden(requestId: string, detail: string): ErrorResponse;
+/** A client asked too often; it may ask again after `retryAfterSeconds`. */
+export declare function rateLimited(requestId: string, detail: string, retryAfterSeconds: number): ErrorResponse;
+/** The resource does not exist, or not for this caller; the detail says what to do. */
+export declare function notFound(requestId: string, detail: 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

@@ -129,6 +129,22 @@ export function crossOriginSession(requestId) {
         },
     };
 }
+/** The caller is authenticated but may not do this; the detail says why. */
+export function forbidden(requestId, detail) {
+    return { status: 403, body: { error: "forbidden", detail, requestId } };
+}
+/** A client asked too often; it may ask again after `retryAfterSeconds`. */
+export function rateLimited(requestId, detail, retryAfterSeconds) {
+    return {
+        status: 429,
+        body: { error: "rate_limited", detail, requestId },
+        headers: { "retry-after": String(retryAfterSeconds) },
+    };
+}
+/** The resource does not exist, or not for this caller; the detail says what to do. */
+export function notFound(requestId, detail) {
+    return { status: 404, body: { error: "not_found", detail, requestId } };
+}
 export function unavailable(requestId) {
     return {
         status: 503,

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

@@ -8,6 +8,7 @@ import type { ConnectionTransportFactory } from "../connections.js";
 import { RequestId } from "../errors.js";
 import type { ReplicationKick } from "../replication.js";
 import { OntologyBackend } from "../runtime-contract.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.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. */
@@ -18,6 +19,8 @@ export interface McpServerOptions {
     readonly connections: ConnectionTransportFactory;
     readonly replicate: ReplicationKick;
     readonly verifyToken: TokenVerifier;
+    /** The deployment's runtime tokens, acting as a member; `undefined` while that is disabled. */
+    readonly verifyRuntime?: RuntimeTokenVerifier | undefined;
     /** The facade the aggregate routes run; the aggregate tool runs its model-level aggregate. */
     readonly aggregates: Aggregates;
 }

package/dist/service/mcp/server.js

@@ -12,6 +12,7 @@ import { publicOrigin } from "../oauth/protocol.js";
 import { mcpChallenge, mcpResource } from "../oauth/server.js";
 import { identityToken, makeOperations, toQuery } from "../operations.js";
 import { OntologyBackend } from "../runtime-contract.js";
+import { runtimeCredential } from "../runtime-identity.js";
 import { ActionResponse, HistoryPage, HistoryParams, IdParam, Me, } from "../schemas.js";
 import { mcpTools, visibleTools } from "./tools.js";
 /** The URL path of the ontology's MCP server, outside `/api/ontology`: one per app. */
@@ -346,7 +347,7 @@ function crossOrigin(request) {
     return !URL.canParse(origin) || new URL(origin).host !== new URL(publicOrigin(request)).host;
 }
 /** `POST /mcp`: one JSON-RPC message in, one JSON response out, nothing kept between requests. */
-function handlePost(server, verifyToken, backend) {
+function handlePost(server, verifyToken, verifyRuntime, backend) {
     const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
     return (request) => Effect.gen(function* () {
         const requestId = yield* RequestId;
@@ -389,14 +390,18 @@ function handlePost(server, verifyToken, backend) {
             }
         });
         const origin = publicOrigin(request);
+        const runtime = runtimeCredential(verifyRuntime, request);
         // With the OAuth tables, members' access tokens work here, and a 401 tells the client where
-        // the member authorizes it.
-        return yield* withPrincipal(yield* Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request), verifyToken, backend, answer, backend.oauth === undefined
-            ? {}
-            : {
-                oauthResource: mcpResource(origin),
-                challenge: (missing) => mcpChallenge(origin, missing),
-            });
+        // the member authorizes it. The app's agent calls as the member it names.
+        return yield* withPrincipal(yield* Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request), verifyToken, backend, answer, {
+            ...(runtime === undefined ? {} : { runtime }),
+            ...(backend.oauth === undefined
+                ? {}
+                : {
+                    oauthResource: mcpResource(origin),
+                    challenge: (missing) => mcpChallenge(origin, missing),
+                }),
+        });
     });
 }
 /**
@@ -415,7 +420,7 @@ export function mcpLayer(options) {
             operations: makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate),
             aggregate: options.aggregates.model,
         };
-        yield* router.add("POST", MCP_PATH, handlePost(server, options.verifyToken, backend));
+        yield* router.add("POST", MCP_PATH, handlePost(server, options.verifyToken, options.verifyRuntime, backend));
         yield* router.add("GET", MCP_PATH, METHOD_NOT_ALLOWED);
         yield* router.add("DELETE", MCP_PATH, METHOD_NOT_ALLOWED);
     }));