@segmentstream-cloud/ontology 0.13.0 → 0.15.0

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

@@ -0,0 +1,59 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { type JWTVerifyGetKey } from "jose";
+/**
+ * The header in which a runtime caller names the member it acts for: the member's user id. The
+ * service honours it only with a verified runtime token, so nobody else can claim a member with it.
+ */
+export declare const ACT_AS_HEADER = "x-segmentstream-act-as";
+/**
+ * Whom the service trusts as its runtime caller: Vercel OIDC tokens of the functions of this
+ * deployment's own project. The app's agent is a service of the same Vercel project as the ontology
+ * service, so `VERCEL_PROJECT_ID` pins exactly the deployment's own functions.
+ */
+export interface RuntimeIdentityConfig {
+    /** The team's issuer: `https://oidc.vercel.com/<team slug>` in team issuer mode. */
+    readonly issuer: string;
+    /** The audience Vercel issues function tokens for: `https://vercel.com/<team slug>`. */
+    readonly audience: string;
+    /** The project the token must name, from `VERCEL_PROJECT_ID`. */
+    readonly projectId: string;
+}
+export type RuntimeVerification = {
+    readonly status: "valid";
+}
+/** The token claims the runtime issuer but fails verification; `reason` names what failed. */
+ | {
+    readonly status: "invalid";
+    readonly reason: string;
+} | {
+    readonly status: "unavailable";
+}
+/** The token does not claim the runtime issuer: it is some other credential. */
+ | {
+    readonly status: "other";
+};
+/** Verifies a bearer token as the deployment's own runtime token. */
+export type RuntimeTokenVerifier = (token: string) => Promise<RuntimeVerification>;
+/** The issuer's key set, at `<issuer>/.well-known/jwks` as Vercel publishes it. */
+export declare function runtimeKeySet(issuer: string): JWTVerifyGetKey;
+/**
+ * Verifies the Vercel OIDC token of a function of this deployment's project, as backend-next
+ * verifies the ontology service's own: RS256 from the team's issuer, for the team's audience,
+ * unexpired, with `project_id` equal to the configured project and `environment` `production`.
+ * The issuer and the audience name the team, so no further owner check is needed. A token that
+ * claims another issuer is `other`, without a key-set fetch.
+ */
+export declare function makeRuntimeTokenVerifier(config: RuntimeIdentityConfig, keySet: JWTVerifyGetKey): RuntimeTokenVerifier;
+/** The runtime verifier on the issuer's remote key set, which jose caches between requests. */
+export declare function runtimeTokenVerifier(config: RuntimeIdentityConfig): RuntimeTokenVerifier;
+/** A runtime token that failed verification: the reason is logged, the token never. */
+export declare function logRuntimeRejection(reason: string): Effect.Effect<void>;
+/** How a request may authenticate as the runtime: the verifier and the member it names, if any. */
+export interface RuntimeCredential {
+    readonly verify: RuntimeTokenVerifier;
+    /** The user id in `X-SegmentStream-Act-As`; `undefined` without the header. */
+    readonly actAs: string | undefined;
+}
+/** The request's runtime credential, or `undefined` while runtime authentication is disabled. */
+export declare function runtimeCredential(verify: RuntimeTokenVerifier | undefined, request: HttpServerRequest.HttpServerRequest): RuntimeCredential | undefined;

package/dist/service/runtime-identity.js

@@ -0,0 +1,102 @@
+import { Effect } from "effect";
+import { createRemoteJWKSet, decodeJwt, errors, jwtVerify } from "jose";
+/**
+ * The header in which a runtime caller names the member it acts for: the member's user id. The
+ * service honours it only with a verified runtime token, so nobody else can claim a member with it.
+ */
+export const ACT_AS_HEADER = "x-segmentstream-act-as";
+const CLOCK_TOLERANCE_SECONDS = 5;
+const JWKS_TIMEOUT_MS = 5_000;
+/** The environment that a Vercel function token must name: channels run only in production. */
+const PRODUCTION = "production";
+/** The issuer without a trailing slash, as Vercel writes it in `iss` and as its JWKS URL starts. */
+function normalizedIssuer(issuer) {
+    let end = issuer.length;
+    while (end > 0 && issuer[end - 1] === "/") {
+        end -= 1;
+    }
+    return issuer.slice(0, end);
+}
+/** The issuer's key set, at `<issuer>/.well-known/jwks` as Vercel publishes it. */
+export function runtimeKeySet(issuer) {
+    return createRemoteJWKSet(new URL(`${normalizedIssuer(issuer)}/.well-known/jwks`), {
+        timeoutDuration: JWKS_TIMEOUT_MS,
+    });
+}
+/** The key set could not be read: not the token's fault. Every other jose error is about the token. */
+function keySetUnavailable(error) {
+    if (!(error instanceof errors.JOSEError)) {
+        return true;
+    }
+    return (error instanceof errors.JWKSTimeout ||
+        error instanceof errors.JWKSInvalid ||
+        error.code === errors.JOSEError.code);
+}
+/** What about a token failed, for the operator's log: a jose code or a claim name, never a value. */
+function failureReason(error) {
+    if (error instanceof errors.JWTClaimValidationFailed || error instanceof errors.JWTExpired) {
+        return `claim:${error.claim}`;
+    }
+    return error instanceof errors.JOSEError ? error.code : "invalid";
+}
+function claimedIssuer(token) {
+    try {
+        const { iss } = decodeJwt(token);
+        return typeof iss === "string" ? iss : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Verifies the Vercel OIDC token of a function of this deployment's project, as backend-next
+ * verifies the ontology service's own: RS256 from the team's issuer, for the team's audience,
+ * unexpired, with `project_id` equal to the configured project and `environment` `production`.
+ * The issuer and the audience name the team, so no further owner check is needed. A token that
+ * claims another issuer is `other`, without a key-set fetch.
+ */
+export function makeRuntimeTokenVerifier(config, keySet) {
+    const issuer = normalizedIssuer(config.issuer);
+    return async function verifyRuntimeToken(token) {
+        if (claimedIssuer(token) !== issuer) {
+            return { status: "other" };
+        }
+        try {
+            const { payload } = await jwtVerify(token, keySet, {
+                algorithms: ["RS256"],
+                issuer,
+                audience: config.audience,
+                clockTolerance: CLOCK_TOLERANCE_SECONDS,
+                requiredClaims: ["exp", "iat", "iss", "aud", "project_id", "environment"],
+            });
+            if (payload.project_id !== config.projectId) {
+                return { status: "invalid", reason: "claim:project_id" };
+            }
+            if (payload.environment !== PRODUCTION) {
+                return { status: "invalid", reason: "claim:environment" };
+            }
+            return { status: "valid" };
+        }
+        catch (error) {
+            return keySetUnavailable(error)
+                ? { status: "unavailable" }
+                : { status: "invalid", reason: failureReason(error) };
+        }
+    };
+}
+/** The runtime verifier on the issuer's remote key set, which jose caches between requests. */
+export function runtimeTokenVerifier(config) {
+    return makeRuntimeTokenVerifier(config, runtimeKeySet(config.issuer));
+}
+/** A runtime token that failed verification: the reason is logged, the token never. */
+export function logRuntimeRejection(reason) {
+    return Effect.logWarning("ontology.runtime_identity.rejected").pipe(Effect.annotateLogs({ reason }));
+}
+/** The request's runtime credential, or `undefined` while runtime authentication is disabled. */
+export function runtimeCredential(verify, request) {
+    if (verify === undefined) {
+        return undefined;
+    }
+    const actAs = request.headers[ACT_AS_HEADER]?.trim();
+    return { verify, actAs: actAs === undefined || actAs === "" ? undefined : actAs };
+}

package/dist/service/service.d.ts

@@ -13,8 +13,8 @@ export interface OntologyService {
     readonly dispose: () => Promise<void>;
 }
 /**
- * The ontology service: the derived HttpApi and the MCP server at `/mcp`, wired to the runtime,
- * behind Neon Auth, app-token and API-key authentication. Every response carries `x-ontology-hash`
+ * The ontology service: the derived HttpApi, the MCP server at `/mcp` and the agent's pairing routes,
+ * wired to the runtime, behind Neon Auth, app-token, API-key and runtime-token authentication. Every response carries `x-ontology-hash`
  * and `x-request-id`; failures answer with a JSON error and never a stack or SQL.
  */
 export declare function createOntologyService(ontology: Ontology, config: OntologyServiceConfig): OntologyService;

package/dist/service/service.js

@@ -4,6 +4,8 @@ import { HttpApiBuilder } from "effect/unstable/httpapi";
 import { storageMaintenanceAuthenticationLayer } from "../storage/maintenance-auth.js";
 import { nameToWire } from "../authoring-names.js";
 import { sqlServiceRuntime } from "../runtime/service-binding.js";
+import { deployedAgentChannel } from "./agent/channel.js";
+import { agentLayer } from "./agent/server.js";
 import { makeAggregates } from "./aggregate.js";
 import { platformAggregates } from "./aggregate-platform.js";
 import { ErrorResponsesLive, buildApi } from "./api.js";
@@ -17,6 +19,7 @@ import { deployedReplication } from "./replication.js";
 import { mcpLayer } from "./mcp/server.js";
 import { oauthLayer } from "./oauth/server.js";
 import { planApi } from "./plan.js";
+import { runtimeTokenVerifier } from "./runtime-identity.js";
 /** The header every response carries: the hash of the manifest the service serves. */
 export const ONTOLOGY_HASH_HEADER = "x-ontology-hash";
 /** The header every response carries: the correlation id quoted in error bodies and logs. */
@@ -59,8 +62,8 @@ function decorate(response, requestId, hash) {
     });
 }
 /**
- * The ontology service: the derived HttpApi and the MCP server at `/mcp`, wired to the runtime,
- * behind Neon Auth, app-token and API-key authentication. Every response carries `x-ontology-hash`
+ * The ontology service: the derived HttpApi, the MCP server at `/mcp` and the agent's pairing routes,
+ * wired to the runtime, behind Neon Auth, app-token, API-key and runtime-token authentication. Every response carries `x-ontology-hash`
  * and `x-request-id`; failures answer with a JSON error and never a stack or SQL.
  */
 export function createOntologyService(ontology, config) {
@@ -76,6 +79,7 @@ export function createOntologyService(ontology, config) {
     const hooks = afterCommitHooks(plan, config.afterCommit);
     const verifyToken = tokenVerifier(config);
     const exchangeSession = config.neonAuth === undefined ? undefined : neonAuthSessionExchange(config.neonAuth);
+    const verifyRuntime = config.runtimeIdentity === undefined ? undefined : runtimeTokenVerifier(config.runtimeIdentity);
     const backend = runtime.connect({
         ontology,
         databaseUrl: config.databaseUrl,
@@ -86,19 +90,33 @@ export function createOntologyService(ontology, config) {
             ? deployedConnections(config)
             : localConnections(config.localConnections));
     const replicate = deployedReplication(config);
+    // The agent's runtime identity is configured only on deployments that have an agent.
+    const agentChannel = config.runtimeIdentity === undefined || config.agentUrl === undefined
+        ? undefined
+        : deployedAgentChannel(config.agentUrl);
     const aggregates = makeAggregates({
         manifest: ontology.manifest,
         transport: platformAggregates({ ...config, manifestHash: ontology.manifest.hash }),
     });
-    const routes = HttpApiBuilder.layer(built.api).pipe(Layer.provide(handlersLayer(built, hooks, connections, replicate, aggregates)), Layer.provide([
-        authenticationLayer(verifyToken, exchangeSession),
+    const routes = HttpApiBuilder.layer(built.api).pipe(Layer.provide(handlersLayer(built, hooks, connections, replicate, aggregates, agentChannel)), Layer.provide([
+        authenticationLayer(verifyToken, exchangeSession, verifyRuntime),
         ErrorResponsesLive,
         storageMaintenanceAuthenticationLayer(config.storageMaintenanceKey),
     ]));
     const mcp = config.mcp === false
         ? Layer.empty
-        : Layer.mergeAll(mcpLayer({ built, hooks, connections, verifyToken, replicate, aggregates }), oauthLayer({ verifyToken }));
-    const application = Layer.mergeAll(routes, mcp, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
+        : Layer.mergeAll(mcpLayer({
+            built,
+            hooks,
+            connections,
+            verifyToken,
+            verifyRuntime,
+            replicate,
+            aggregates,
+            agentChannel,
+        }), oauthLayer({ verifyToken }));
+    const agent = agentLayer({ verifyToken, verifyRuntime, exchangeSession });
+    const application = Layer.mergeAll(routes, mcp, agent, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
     const web = HttpRouter.toWebHandler(application, { disableLogger: true });
     const hash = ontology.manifest.hash;
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",