@segmentstream-cloud/ontology 0.23.0 → 0.24.1

package/dist/runtime/sql-runtime.d.ts

@@ -1,9 +1,9 @@
 import { Effect } from "effect";
 import type { SqlClient } from "effect/unstable/sql";
-import { type NotFound } from "../errors.js";
+import { Conflict, type NotFound } from "../errors.js";
 import type { Ontology } from "../ontology.js";
 import type { Query, QueryResult } from "../query.js";
-import type { OntologyRuntimeService, StoredRecord } from "../runtime.js";
+import type { OntologyRuntimeService, StoredRecord, StoredValues } from "../runtime.js";
 import { InvalidQuery } from "./errors.js";
 import type { Edit, HistoryEntry, HistoryScope } from "./history.js";
 /**
@@ -39,6 +39,16 @@ export interface SqlOntologyRuntime extends OntologyRuntimeService {
         readonly limit?: number;
     }) => Effect.Effect<QueryResult<HistoryEntry>, InvalidQuery>;
 }
+/**
+ * Platform identity bookkeeping touches only User properties and their history. User is excluded
+ * from business replication; keep this internal capability separate from the general runtime so
+ * deleting users, cascading relationships or editing business records still takes its fence.
+ */
+export declare function makePrincipalUserWriter(ontology: Ontology, sql: SqlClient.SqlClient, scope: Pick<HistoryScope, "action" | "actionId">): {
+    recordsSignIn: boolean;
+    create: (values: StoredValues) => Effect.Effect<Readonly<Record<string, unknown>>, Conflict | NotFound, never>;
+    update: (id: string, values: StoredValues) => Effect.Effect<Readonly<Record<string, unknown>>, Conflict | NotFound, never>;
+};
 /**
  * The runtime over one SQL client, normally `@effect/sql-pg`'s. Statements are parameterised; the
  * client runs them on the transaction of the calling fiber, so a runtime made for an action shares

package/dist/runtime/sql-runtime.js

@@ -2,6 +2,8 @@ import { Effect } from "effect";
 import { beginReplicationWrite } from "../replication/transaction.js";
 import { isSqlError } from "effect/unstable/sql/SqlError";
 import { Conflict } from "../errors.js";
+import { toSnakeCase } from "../names.js";
+import { User } from "../user.js";
 import { InvalidQuery, WriteOutsideAction } from "./errors.js";
 import { entityModel, ontologyModel } from "./model.js";
 import { loadRecord, notFound, readHistory, relatedCondition, runQuery, validateQuery, } from "./reads.js";
@@ -41,6 +43,37 @@ function uniqueConflict(entity, error) {
             message: `A ${label} with this ${field.name} already exists.`,
         }));
 }
+/**
+ * Platform identity bookkeeping touches only User properties and their history. User is excluded
+ * from business replication; keep this internal capability separate from the general runtime so
+ * deleting users, cascading relationships or editing business records still takes its fence.
+ */
+export function makePrincipalUserWriter(ontology, sql, scope) {
+    const model = ontologyModel(ontology);
+    const user = entityModel(model, User.name);
+    const allowed = new Set(Object.keys(User.definition.properties).map(toSnakeCase));
+    const client = sql.withoutTransforms();
+    const context = () => ({
+        model,
+        scope: { action: scope.action, actionId: scope.actionId, principalId: null },
+        edits: [],
+        run: (text, params) => client.unsafe(text, params.values),
+    });
+    const write = (values, operation) => Effect.suspend(() => {
+        if (!user.manifest.builtIn ||
+            Object.keys(values).some((name) => !allowed.has(name) || user.fieldsByName.get(name)?.source !== "property")) {
+            return Effect.die(new Error("Principal writes accept only built-in User properties."));
+        }
+        return sql
+            .withTransaction(operation())
+            .pipe(Effect.catchIf(isSqlError, (error) => uniqueConflict(user, error)));
+    });
+    return {
+        recordsSignIn: user.fieldsByName.has("last_sign_in_at"),
+        create: (values) => write(values, () => createRecord(context(), user, values)),
+        update: (id, values) => write(values, () => updateRecord(context(), user, id, values)),
+    };
+}
 /**
  * The runtime over one SQL client, normally `@effect/sql-pg`'s. Statements are parameterised; the
  * client runs them on the transaction of the calling fiber, so a runtime made for an action shares

package/dist/runtime/workload.d.ts

@@ -0,0 +1,23 @@
+import { Schema } from "effect";
+/** Verified platform claims retained with each write; never supplied by request headers. */
+export declare const WorkloadExecution: Schema.Struct<{
+    readonly issuer: Schema.String;
+    readonly audience: Schema.String;
+    readonly organizationId: Schema.String;
+    readonly workspaceId: Schema.String;
+    readonly subject: Schema.String;
+    readonly deploymentId: Schema.String;
+    readonly ontologyDeploymentId: Schema.String;
+    readonly servingOntologyDeploymentId: Schema.String;
+    readonly ontologyOrigin: Schema.String;
+    readonly environment: Schema.Literal<"production">;
+    readonly jobName: Schema.String;
+    readonly runId: Schema.String;
+    readonly executionId: Schema.NullOr<Schema.String>;
+    readonly attemptId: Schema.String;
+    readonly generation: Schema.Number;
+    readonly tokenId: Schema.String;
+    readonly issuedAt: Schema.Number;
+    readonly expiresAt: Schema.Number;
+}>;
+export type WorkloadExecution = typeof WorkloadExecution.Type;

package/dist/runtime/workload.js

@@ -0,0 +1,22 @@
+import { Schema } from "effect";
+/** Verified platform claims retained with each write; never supplied by request headers. */
+export const WorkloadExecution = Schema.Struct({
+    issuer: Schema.String,
+    audience: Schema.String,
+    organizationId: Schema.String,
+    workspaceId: Schema.String,
+    subject: Schema.String,
+    deploymentId: Schema.String,
+    ontologyDeploymentId: Schema.String,
+    servingOntologyDeploymentId: Schema.String,
+    ontologyOrigin: Schema.String,
+    environment: Schema.Literal("production"),
+    jobName: Schema.String,
+    runId: Schema.String,
+    executionId: Schema.NullOr(Schema.String),
+    attemptId: Schema.String,
+    generation: Schema.Number,
+    tokenId: Schema.String,
+    issuedAt: Schema.Number,
+    expiresAt: Schema.Number,
+});

package/dist/runtime/writes.js

@@ -1,7 +1,7 @@
 import { Effect } from "effect";
 import { resolveBlobWrites } from "../storage/writes.js";
 import { Conflict } from "../errors.js";
-import { quoteIdentifier } from "../migrate/storage.js";
+import { ACTION_ATTRIBUTION_TABLE, quoteIdentifier } from "../migrate/storage.js";
 import { InvalidValues } from "./errors.js";
 import { uuidv7 } from "./ids.js";
 import { diffRecords, insertHistory } from "./history.js";
@@ -13,6 +13,12 @@ import { columnOf, Params } from "./statement.js";
 function recordEdit(context, entity, edit) {
     return Effect.gen(function* () {
         const params = new Params();
+        if (context.scope.execution !== undefined) {
+            const attribution = new Params();
+            yield* context.run(`INSERT INTO "${ACTION_ATTRIBUTION_TABLE}" (action_id, execution) VALUES (` +
+                `${attribution.add(context.scope.actionId, "uuid")}, ` +
+                `${attribution.add(JSON.stringify(context.scope.execution), "jsonb")}) ON CONFLICT DO NOTHING`, attribution);
+        }
         yield* context.run(insertHistory(context.scope, { entity, edit }, params), params);
         context.edits.push(edit);
     });

package/dist/runtime.d.ts

@@ -1,8 +1,11 @@
 import { Context, Effect } from "effect";
 import type { Conflict, NotFound } from "./errors.js";
 import type { Where } from "./query.js";
+import type { WorkloadExecution } from "./runtime/workload.js";
 /** Who runs an action: an app member or a service principal, both `user` records. */
 export interface Principal {
+    /** Present only for a verified managed pipeline worker. */
+    readonly execution?: WorkloadExecution;
     /** The id of the principal's `user` record. */
     readonly id: string;
     readonly kind: "member" | "service";

package/dist/service/authentication.d.ts

@@ -2,6 +2,7 @@ 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 { WorkloadExecution } from "../runtime/workload.js";
 import type { Principal } from "../runtime.js";
 import type { NeonAuthEnvironment } from "./config.js";
 import { RequestId } from "./errors.js";
@@ -32,6 +33,10 @@ declare const Authentication_base: HttpApiMiddleware.ServiceClass<Authentication
 export declare class Authentication extends Authentication_base {
 }
 export interface TokenVerifierConfig {
+    /** Production workload activation and the deployment actually serving the request. */
+    readonly workloadTarget?: {
+        readonly deploymentId: string;
+    };
     /** The control plane: the issuer of app tokens and the host of their JWKS. */
     readonly segmentstreamUrl: string;
     readonly applicationId: string;
@@ -39,6 +44,9 @@ export interface TokenVerifierConfig {
     readonly organizationId: string;
 }
 export type TokenVerification = {
+    readonly status: "workload";
+    readonly execution: WorkloadExecution;
+} | {
     readonly status: "valid";
     readonly identity: SignInIdentity;
 } | {
@@ -56,6 +64,9 @@ export declare function neonAuthKeySet(jwksUrl: string): JWTVerifyGetKey;
  * `SEGMENTSTREAM_URL` for this application (`aud: app:<application id>`), organization and workspace.
  */
 export declare function makeTokenVerifier(config: TokenVerifierConfig, keySet: JWTVerifyGetKey): TokenVerifier;
+export declare const WORKLOAD_TOKEN_TYPE = "segmentstream-ontology-workload+jwt";
+/** A separate verifier: a workload token can never resolve as a human or act as an agent. */
+export declare function makeWorkloadTokenVerifier(config: TokenVerifierConfig, keySet: JWTVerifyGetKey): TokenVerifier;
 /**
  * Neon Auth's issuer is the origin of its Auth URL: `https://ep-….neon.tech/ontology/auth` issues
  * tokens with `iss: https://ep-….neon.tech`.

package/dist/service/authentication.js

@@ -1,7 +1,7 @@
 import { Cause, Context, Effect, Layer, Redacted } from "effect";
 import { HttpServerRequest } from "effect/unstable/http";
 import { HttpApiMiddleware, HttpApiSecurity, OpenApi } from "effect/unstable/httpapi";
-import { createRemoteJWKSet, decodeJwt, errors, jwtVerify, } from "jose";
+import { createRemoteJWKSet, decodeJwt, decodeProtectedHeader, errors, jwtVerify, } from "jose";
 import { API_KEY_PREFIX } from "../runtime/principals.js";
 import { RequestId, crossOriginSession, forbidden, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
 import { ACCESS_TOKEN_PREFIX, principalOfAccessToken } from "./oauth/protocol.js";
@@ -76,6 +76,7 @@ export function makeTokenVerifier(config, keySet) {
         try {
             const verified = await jwtVerify(token, keySet, {
                 algorithms: ["ES256"],
+                typ: "JWT",
                 issuer,
                 audience,
                 clockTolerance: CLOCK_TOLERANCE_SECONDS,
@@ -90,6 +91,96 @@ export function makeTokenVerifier(config, keySet) {
         return identity === undefined ? { status: "invalid" } : { status: "valid", identity };
     };
 }
+export const WORKLOAD_TOKEN_TYPE = "segmentstream-ontology-workload+jwt";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** A separate verifier: a workload token can never resolve as a human or act as an agent. */
+export function makeWorkloadTokenVerifier(config, keySet) {
+    return async (token) => {
+        if (config.workloadTarget === undefined) {
+            return { status: "invalid" };
+        }
+        let payload;
+        try {
+            const verified = await jwtVerify(token, keySet, {
+                algorithms: ["ES256"],
+                typ: WORKLOAD_TOKEN_TYPE,
+                issuer: new URL(config.segmentstreamUrl).origin,
+                audience: `ontology:${config.applicationId}`,
+                clockTolerance: CLOCK_TOLERANCE_SECONDS,
+                requiredClaims: [
+                    "sub",
+                    "exp",
+                    "iat",
+                    "jti",
+                    "org",
+                    "wsp",
+                    "deploymentId",
+                    "ontologyDeploymentId",
+                    "ontologyOrigin",
+                    "environment",
+                    "jobName",
+                    "runId",
+                    "executionId",
+                    "attemptId",
+                    "generation",
+                ],
+            });
+            payload = verified.payload;
+        }
+        catch (error) {
+            return keySetUnavailable(error) ? { status: "unavailable" } : { status: "invalid" };
+        }
+        const strings = ["jti", "jobName"];
+        const ids = ["deploymentId", "ontologyDeploymentId", "runId", "attemptId"];
+        if (payload.org !== config.organizationId ||
+            payload.wsp !== config.workspaceId ||
+            payload.sub !== `pipeline-workers:${config.workspaceId}` ||
+            payload.environment !== "production" ||
+            payload.aud !== `ontology:${config.applicationId}` ||
+            strings.some((name) => typeof payload[name] !== "string" || payload[name].trim() === "") ||
+            ids.some((name) => typeof payload[name] !== "string" || !UUID.test(payload[name])) ||
+            (payload.executionId !== null &&
+                (typeof payload.executionId !== "string" || !UUID.test(payload.executionId))) ||
+            !Number.isSafeInteger(payload.generation) ||
+            payload.generation < 1 ||
+            !Number.isSafeInteger(payload.iat) ||
+            !Number.isSafeInteger(payload.exp) ||
+            payload.iat > Math.floor(Date.now() / 1000) + CLOCK_TOLERANCE_SECONDS ||
+            payload.exp <= payload.iat ||
+            payload.exp - payload.iat > 300 ||
+            typeof payload.ontologyOrigin !== "string" ||
+            !URL.canParse(payload.ontologyOrigin)) {
+            return { status: "invalid" };
+        }
+        const origin = new URL(payload.ontologyOrigin);
+        if (origin.protocol !== "https:" || origin.origin !== payload.ontologyOrigin) {
+            return { status: "invalid" };
+        }
+        return {
+            status: "workload",
+            execution: {
+                issuer: payload.iss,
+                audience: payload.aud,
+                organizationId: config.organizationId,
+                workspaceId: config.workspaceId,
+                subject: payload.sub,
+                deploymentId: payload.deploymentId,
+                ontologyDeploymentId: payload.ontologyDeploymentId,
+                servingOntologyDeploymentId: config.workloadTarget.deploymentId,
+                ontologyOrigin: payload.ontologyOrigin,
+                environment: "production",
+                jobName: payload.jobName,
+                runId: payload.runId,
+                executionId: payload.executionId,
+                attemptId: payload.attemptId,
+                generation: payload.generation,
+                tokenId: payload.jti,
+                issuedAt: payload.iat,
+                expiresAt: payload.exp,
+            },
+        };
+    };
+}
 /**
  * Neon Auth's issuer is the origin of its Auth URL: `https://ep-….neon.tech/ontology/auth` issues
  * tokens with `iss: https://ep-….neon.tech`.
@@ -166,11 +257,21 @@ export function verifyByIssuer(verifiers) {
  * once it has Neon Auth. Both are accepted while workspaces move to Neon Auth.
  */
 export function tokenVerifier(config) {
+    const platformKeys = remoteKeySet(config.segmentstreamUrl);
+    const human = makeTokenVerifier(config, platformKeys);
+    const workload = makeWorkloadTokenVerifier(config, platformKeys);
+    const platform = (token) => {
+        try {
+            return decodeProtectedHeader(token).typ === WORKLOAD_TOKEN_TYPE
+                ? workload(token)
+                : human(token);
+        }
+        catch {
+            return Promise.resolve({ status: "invalid" });
+        }
+    };
     const verifiers = new Map([
-        [
-            new URL(config.segmentstreamUrl).origin,
-            makeTokenVerifier(config, remoteKeySet(config.segmentstreamUrl)),
-        ],
+        [new URL(config.segmentstreamUrl).origin, platform],
     ]);
     if (config.neonAuth !== undefined) {
         verifiers.set(neonAuthIssuer(config.neonAuth.baseUrl), makeNeonAuthTokenVerifier(config.neonAuth, neonAuthKeySet(config.neonAuth.jwksUrl)));
@@ -337,6 +438,14 @@ export function authenticate(credential, verifyToken, options = {}) {
             }
         }
         const verification = yield* Effect.promise(() => verifyToken(token));
+        if (verification.status === "workload") {
+            const principal = backend.resolvePipelineWorker === undefined
+                ? undefined
+                : yield* backend.resolvePipelineWorker(verification.execution);
+            return principal === undefined
+                ? { status: "rejected" }
+                : { status: "authenticated", principal };
+        }
         if (verification.status !== "valid") {
             return verification.status === "invalid"
                 ? { status: "rejected" }

package/dist/service/config.d.ts

@@ -66,6 +66,10 @@ export interface OntologyEnvironment {
      * `segmentstreamUrl` for `workspaceId`; previews and local development have none.
      */
     readonly appCredential?: Redacted.Redacted<string>;
+    /** Production deployment identity; absent in local, preview and earlier deployments. */
+    readonly workloadTarget?: {
+        readonly deploymentId: string;
+    };
     /** Present once the workspace has Neon Auth: members then sign in with its tokens. */
     readonly neonAuth?: NeonAuthEnvironment;
     /**

package/dist/service/config.js

@@ -134,6 +134,13 @@ export function configFromEnv(environment = process.env) {
             message: `The ontology service cannot start: ${list} ${verb} not set.`,
         });
     }
+    const deploymentId = read("SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID");
+    if (deploymentId !== "" &&
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(deploymentId)) {
+        throw new OntologyServiceConfigError({
+            message: "SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID must be a UUID.",
+        });
+    }
     const neonAuth = neonAuthFromEnv(read);
     const runtimeIdentity = runtimeIdentityFromEnv(read);
     const localConnections = localConnectionsFromEnv(environment);
@@ -163,6 +170,10 @@ export function configFromEnv(environment = process.env) {
         ...(read(APP_CREDENTIAL_VARIABLE)
             ? { appCredential: Redacted.make(read(APP_CREDENTIAL_VARIABLE)) }
             : {}),
+        ...(environment.VERCEL_ENV === "production" &&
+            read("SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID") !== ""
+            ? { workloadTarget: { deploymentId: read("SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID") } }
+            : {}),
         ...(neonAuth === undefined ? {} : { neonAuth }),
         ...(runtimeIdentity === undefined ? {} : { runtimeIdentity }),
         ...(runtimeIdentity === undefined || read(AGENT_HOST_VARIABLE) === ""

package/dist/service/handlers.js

@@ -1,3 +1,4 @@
+import { effectivePermissions } from "../permissions.js";
 import { HttpServerResponse } from "effect/unstable/http";
 import { Effect, Layer, Schema } from "effect";
 import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
@@ -145,7 +146,7 @@ function serviceHandlers(built, operationsOf, aggregate) {
                 return undefined;
             }
             const principal = yield* CurrentPrincipal;
-            return principal.permissions;
+            return effectivePermissions(principal);
         });
         return handlers
             .handle("catalog", (request) => Effect.map(permissionsFor(request.query.as), (permissions) => catalogFor(manifest, permissions)))

package/dist/service/mcp/server.js

@@ -1,3 +1,4 @@
+import { effectivePermissions } from "../../permissions.js";
 import { Cause, Data, Effect, Layer, Option, Schema, SchemaTransformation } from "effect";
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
@@ -175,7 +176,7 @@ function runTool({ built, operations, aggregate, conversations }, tool, args, re
             case "describe": {
                 const principal = yield* CurrentPrincipal;
                 return {
-                    text: describeCatalog(built.plan.ontology.manifest, principal.permissions),
+                    text: describeCatalog(built.plan.ontology.manifest, effectivePermissions(principal)),
                 };
             }
             case "aggregate": {
@@ -285,7 +286,7 @@ function readResource({ built }, uri) {
                     {
                         uri,
                         mimeType: "application/json",
-                        text: JSON.stringify(encodeManifest(catalogFor(manifest, principal.permissions))),
+                        text: JSON.stringify(encodeManifest(catalogFor(manifest, effectivePermissions(principal)))),
                     },
                 ];
             case DESCRIBE_URI:
@@ -293,7 +294,7 @@ function readResource({ built }, uri) {
                     {
                         uri,
                         mimeType: "text/plain",
-                        text: describeCatalog(manifest, principal.permissions),
+                        text: describeCatalog(manifest, effectivePermissions(principal)),
                     },
                 ];
             default:
@@ -354,7 +355,7 @@ function dispatch(server, message, request) {
                         title: "Ontology",
                         version: server.built.plan.ontology.manifest.hash,
                     },
-                    instructions: instructions(server, principal.permissions),
+                    instructions: instructions(server, effectivePermissions(principal)),
                 });
             case "ping":
                 return rpcResult(id, {});

package/dist/service/operations.d.ts

@@ -74,19 +74,39 @@ export declare function makeOperations(backend: Backend, plan: ApiPlan, hooks: R
         readonly after?: string;
         readonly limit?: number;
     }) => Effect.Effect<QueryResult<{
+        readonly at: string;
         readonly id: string;
-        readonly recordId: string;
-        readonly action: string;
-        readonly actionId: string;
         readonly kind: "create" | "update" | "delete" | "link" | "unlink";
-        readonly principalId: string | null;
-        readonly at: string;
+        readonly action: string;
         readonly changes: {
             readonly [x: string]: {
                 readonly before: import("effect/Schema").Json;
                 readonly after: import("effect/Schema").Json;
             };
         };
+        readonly principalId: string | null;
+        readonly recordId: string;
+        readonly actionId: string;
+        readonly execution?: {
+            readonly issuer: string;
+            readonly audience: string;
+            readonly organizationId: string;
+            readonly workspaceId: string;
+            readonly subject: string;
+            readonly deploymentId: string;
+            readonly ontologyDeploymentId: string;
+            readonly servingOntologyDeploymentId: string;
+            readonly ontologyOrigin: string;
+            readonly environment: "production";
+            readonly jobName: string;
+            readonly runId: string;
+            readonly executionId: string | null;
+            readonly attemptId: string;
+            readonly generation: number;
+            readonly tokenId: string;
+            readonly issuedAt: number;
+            readonly expiresAt: number;
+        } | undefined;
     }>, PermissionDenied | import("../errors.js").NotFound | import("../index.js").InvalidQuery, CurrentPrincipal>;
     /** The records a relationship reaches from one record, as a page of the target entity. */
     traverse: (planned: PlannedEntity, traversal: Traversal, id: string, query: Query) => Effect.Effect<QueryResult<Readonly<Record<string, unknown>>>, PermissionDenied | import("../errors.js").NotFound | import("../index.js").InvalidQuery, CurrentPrincipal>;

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

@@ -274,6 +274,7 @@ declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segm
      * Finds, links or creates the member's user. `undefined` when the user may not sign in, and
      * {@link NotInvited} when the sign-in policy turns away a person nobody invited.
      */
+    readonly resolvePipelineWorker?: (execution: import("../runtime/workload.js").WorkloadExecution) => Effect.Effect<Principal | undefined>;
     readonly resolvePrincipal: (identity: SignInIdentity) => Effect.Effect<Principal | undefined, NotInvited>;
     /**
      * Whether a person may sign in with this address, and how, read before the app emails them.