@segmentstream-cloud/ontology 0.13.0 → 0.14.0

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

@@ -153,6 +153,72 @@ export interface OAuthStore {
     /** The member a grant acts for, with the roles they hold now; undefined once they may not sign in. */
     readonly memberPrincipal: (userId: string) => Effect.Effect<Principal | undefined>;
 }
+/** A channel account waiting, for ten minutes, for a member to claim it with its pairing code. */
+export interface AgentPairing {
+    readonly id: string;
+    /** The channel, such as `telegram`. */
+    readonly provider: string;
+    /** The account's id on the channel. */
+    readonly externalId: string;
+    /** How the channel names the account, shown on the connect page. */
+    readonly display: string | null;
+    readonly expiresAt: Date;
+}
+/** A channel account paired with a member: the app's agent acts as the member for its messages. */
+export interface AgentIdentity {
+    readonly id: string;
+    readonly provider: string;
+    readonly externalId: string;
+    readonly userId: string;
+    readonly display: string | null;
+    readonly createdAt: Date;
+    /** When the identity stopped working; null while it is live. */
+    readonly revokedAt: Date | null;
+}
+/** A member as the agent names them: their user's name and the roles they hold now. */
+export interface AgentMember {
+    readonly name: string;
+    readonly principal: Principal;
+}
+/**
+ * Where the app's agent keeps pairing codes and the identities they create: the runtime's agent
+ * tables in the workspace database. Codes are stored only as SHA-256 hashes. Expiry is checked
+ * against the database's clock; failures are defects.
+ */
+export interface AgentStore {
+    /** Stores a pairing under its code's hash and forgets expired ones; false when the hash is taken. */
+    readonly savePairing: (pairing: AgentPairing & {
+        readonly codeHash: string;
+    }) => Effect.Effect<boolean>;
+    /** A pairing that has neither expired nor been approved. */
+    readonly findPairing: (codeHash: string) => Effect.Effect<AgentPairing | undefined>;
+    /**
+     * Consumes a live pairing, once, and pairs its account with the member. The account's previous
+     * identity and the member's previous identity on the same provider are revoked: each has one live
+     * identity per provider. `undefined` when the pairing expired or was already approved.
+     */
+    readonly approvePairing: (input: {
+        readonly codeHash: string;
+        readonly userId: string;
+        readonly identityId: string;
+    }) => Effect.Effect<AgentIdentity | undefined>;
+    /** The account's live identity, else its latest revoked one, else `undefined`. */
+    readonly findIdentity: (input: {
+        readonly provider: string;
+        readonly externalId: string;
+    }) => Effect.Effect<AgentIdentity | undefined>;
+    /** The member's live identities, oldest first. */
+    readonly listIdentities: (userId: string) => Effect.Effect<ReadonlyArray<AgentIdentity>>;
+    /** Revokes one of the member's live identities; false when they have no such identity. */
+    readonly revokeIdentity: (input: {
+        readonly id: string;
+        readonly userId: string;
+    }) => Effect.Effect<boolean>;
+    /** An active member by user id; `undefined` for an unknown user, a service or an inactive member. */
+    readonly member: (userId: string) => Effect.Effect<AgentMember | undefined>;
+    /** The member a runtime caller acts for: active, and with a live identity. */
+    readonly actingMember: (userId: string) => Effect.Effect<Principal | undefined>;
+}
 declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segmentstream-cloud/ontology/OntologyBackend", {
     readonly blobs?: BlobRuntime;
     readonly maintainBlobs?: Effect.Effect<{
@@ -192,6 +258,8 @@ declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segm
     readonly replicationEnabled?: Effect.Effect<boolean>;
     /** The OAuth tables, for members who connect agents; without it, agents use API keys. */
     readonly oauth?: OAuthStore;
+    /** The agent tables, which pair channel accounts with members for the app's own agent. */
+    readonly agents?: AgentStore;
 }>;
 /**
  * The runtime as the HTTP service sees it, with its database and ontology already bound. Failures

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,7 @@ 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 { agentLayer } from "./agent/server.js";
 import { makeAggregates } from "./aggregate.js";
 import { platformAggregates } from "./aggregate-platform.js";
 import { ErrorResponsesLive, buildApi } from "./api.js";
@@ -17,6 +18,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 +61,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 +78,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,
@@ -91,14 +94,23 @@ export function createOntologyService(ontology, config) {
         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),
+        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,
+        }), 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.14.0",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",