@segmentstream-cloud/ontology 0.9.0 → 0.11.0

package/dist/migrate/storage.js

@@ -29,6 +29,7 @@ export const COLUMN_TYPES = {
     date: "date",
     timestamp: "timestamptz",
     json: "jsonb",
+    blob: "uuid",
 };
 const ON_DELETE_ACTIONS = {
     setNull: "SET NULL",
@@ -198,6 +199,15 @@ function foreignKeyDefinition(input) {
         `REFERENCES ${quoteIdentifier(input.references)} (${quoteIdentifier(SYSTEM_COLUMNS.id)})`;
     return input.onDelete === undefined ? reference : `${reference} ON DELETE ${input.onDelete}`;
 }
+export function blobForeignKey(entity, property) {
+    const column = columnName(property.name);
+    return {
+        name: foreignKeyName(entity, column),
+        kind: "foreignKey",
+        definition: foreignKeyDefinition({ column, references: "_blobs" }),
+        references: "_blobs",
+    };
+}
 function userReference(table, column) {
     return {
         name: foreignKeyName(table, column),
@@ -389,6 +399,9 @@ export function entityStorage(entity) {
                 userReference(table, SYSTEM_COLUMNS.created_by),
                 userReference(table, SYSTEM_COLUMNS.updated_by),
                 ...checks,
+                ...entity.properties
+                    .filter((property) => property.type === "blob")
+                    .map((property) => blobForeignKey(entity.name, property)),
                 ...ones.map((relationship) => relationshipForeignKey(entity.name, relationship)),
             ],
             indexes: entityIndexes(entity),
@@ -420,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.
@@ -451,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/property.d.ts

@@ -1,6 +1,7 @@
 import { Schema } from "effect";
+import { BlobValue, type BLOB_CONTENT_TYPES } from "./blob.js";
 /** The closed set of storage types. Each has a known column, JSON Schema, filters and rendering. */
-export declare const PROPERTY_TYPES: readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"];
+export declare const PROPERTY_TYPES: readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"];
 export type PropertyType = (typeof PROPERTY_TYPES)[number];
 /** Schema annotation that carries a property's storage metadata. */
 export declare const PROPERTY_ANNOTATION = "segmentstream/ontology/property";
@@ -40,6 +41,8 @@ export interface PropertyDefinition {
     readonly max?: number;
     readonly maxLength?: number;
     readonly options?: ReadonlyArray<SelectOption>;
+    readonly accept?: ReadonlyArray<string>;
+    readonly maxBytes?: number;
 }
 /**
  * A property: an Effect Schema of its value, usable in action inputs, with its storage metadata in
@@ -127,6 +130,11 @@ declare function ref<const O extends ReferenceOptions>(target: string | {
     readonly name: string;
 }, options?: O): ReferenceOf<O>;
 /** Property constructors. */
+export interface BlobOptions extends Omit<PropertyOptions<BlobValue>, "default" | "unique"> {
+    readonly accept: ReadonlyArray<(typeof BLOB_CONTENT_TYPES)[number]>;
+    readonly maxBytes?: number;
+}
+declare function blob<const O extends BlobOptions>(options: O): PropertyOf<BlobValue, O>;
 export declare const p: {
     readonly text: typeof text;
     readonly email: typeof email;
@@ -138,6 +146,7 @@ export declare const p: {
     readonly timestamp: typeof timestamp;
     readonly select: typeof select;
     readonly json: typeof json;
+    readonly blob: typeof blob;
     readonly ref: typeof ref;
 };
 /** The storage metadata of a schema built with a `p.*` constructor, or `undefined` for any other value. */

package/dist/property.js

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 import { humanize } from "./names.js";
+import { BlobValue, MAX_BLOB_BYTES } from "./blob.js";
 import { nameToWire } from "./authoring-names.js";
 /** The closed set of storage types. Each has a known column, JSON Schema, filters and rendering. */
 export const PROPERTY_TYPES = [
@@ -13,6 +14,7 @@ export const PROPERTY_TYPES = [
     "timestamp",
     "select",
     "json",
+    "blob",
 ];
 /** Schema annotation that carries a property's storage metadata. */
 export const PROPERTY_ANNOTATION = "segmentstream/ontology/property";
@@ -47,6 +49,8 @@ function construct({ type, base, options, checks = [], format, selectOptions, })
         ...(options.min !== undefined ? { min: options.min } : {}),
         ...(options.max !== undefined ? { max: options.max } : {}),
         ...(options.maxLength !== undefined ? { maxLength: options.maxLength } : {}),
+        ...(options.accept !== undefined ? { accept: options.accept } : {}),
+        ...(options.maxBytes !== undefined ? { maxBytes: options.maxBytes } : {}),
         ...(selectOptions !== undefined ? { options: selectOptions } : {}),
     };
     // Annotations go on the base node, before the checks, so that the JSON Schema keeps them at the top
@@ -176,7 +180,13 @@ function ref(target, options) {
     }).check(Schema.isPattern(UUID));
     return (settings.optional === true ? Schema.optionalKey(schema) : schema);
 }
-/** Property constructors. */
+function blob(options) {
+    return construct({
+        type: "blob",
+        base: BlobValue,
+        options: { ...options, maxBytes: options.maxBytes ?? MAX_BLOB_BYTES },
+    });
+}
 export const p = {
     text,
     email,
@@ -188,6 +198,7 @@ export const p = {
     timestamp,
     select,
     json,
+    blob,
     ref,
 };
 function findAnnotation(ast, key) {

package/dist/query.js

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 import { wireStruct } from "./wire.js";
+import { BlobValue } from "./blob.js";
 /**
  * The query language of `find` and of the HTTP API's list and query endpoints.
  *
@@ -194,12 +195,13 @@ export function fieldValueSchema(field) {
         case "json":
             return JsonValue;
         case "uuid":
+        case "blob":
             return UuidValue;
     }
 }
 /** Fields a query can sort on: every field but `json` properties. */
 export function isOrderable(field) {
-    return field.storage !== "json";
+    return field.storage !== "json" && field.storage !== "blob";
 }
 const FILTER_IDENTIFIERS = {
     text: "TextFilter",
@@ -212,6 +214,7 @@ const FILTER_IDENTIFIERS = {
     timestamp: "TimestampFilter",
     json: "JsonFilter",
     uuid: "IdFilter",
+    blob: "IdFilter",
 };
 const FILTER_DESCRIPTIONS = {
     TextFilter: "contains and startsWith ignore case.",
@@ -413,6 +416,8 @@ function recordValueSchema(field) {
                 return Schema.Literals(field.options ?? []);
             case "json":
                 return Schema.Json;
+            case "blob":
+                return BlobValue;
             default:
                 return Schema.String;
         }

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

@@ -1,4 +1,5 @@
 import { Effect, Schema } from "effect";
+import { uploadInput, BLOB_UPLOAD_ANNOTATION } from "../blob.js";
 import { action } from "../action.js";
 import { GENERATED_UPSERT_PREFIX } from "../names.js";
 import { generatedActionPermissions } from "../permissions.js";
@@ -16,7 +17,10 @@ export function upsertActionName(property) {
     return `${GENERATED_UPSERT_PREFIX}${property}`;
 }
 /** A property's value schema, refusing days that do not exist, which PostgreSQL would reject. */
-function propertyInput(field) {
+function propertyInput(field, entity) {
+    if (field.storage === "blob") {
+        return uploadInput(entity.name, field.name);
+    }
     const schema = propertyValueSchema(field.property);
     if (field.storage === "date") {
         return schema.check(Schema.makeFilter((value) => isCalendarDate(value) || "Expected a date that exists"));
@@ -44,7 +48,7 @@ function valueFields(entity, { mode }) {
         if (mode === "update" && definition?.managed === true) {
             continue;
         }
-        const value = propertyInput(field);
+        const value = propertyInput(field, entity);
         const required = mode === "create" &&
             !field.nullable &&
             !(definition !== undefined && "default" in definition);
@@ -162,9 +166,10 @@ 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,
+        includeAnnotationKey: (key) => key === REFERENCE_ANNOTATION || key === BLOB_UPLOAD_ANNOTATION,
         onExcessProperty: "error",
     });
     const schema = document.schema;
@@ -178,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/history.d.ts

@@ -57,6 +57,9 @@ export interface HistoryScope {
     readonly action: string;
     readonly actionId: string;
     readonly principalId: string | null;
+    readonly branchId?: string;
+    readonly blobActionKey?: string;
+    readonly createIntent?: string;
 }
 /** `INSERT` of one history row; `at` is the transaction's time, shared by the whole action. */
 export declare function insertHistory(scope: HistoryScope, write: HistoryWrite, params: Params): string;

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/pipeline.d.ts

@@ -32,7 +32,10 @@ export interface ActionRequest<R = never> {
     readonly options?: {
         /** Decode the input and check the permission, without running `prepare` or the handler. */
         readonly validateOnly?: boolean;
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
     };
+    readonly branchId?: string;
     readonly afterCommit?: ReadonlyArray<AfterCommit<R>>;
     /** The request's id, which `prepare` and the handler receive for logs; the action id by default. */
     readonly requestId?: string;
@@ -96,7 +99,8 @@ export declare function findAction(ontology: Ontology, entityName: string, actio
  * 1. decode the input with the action's schema; issues are returned, not raised;
  * 2. check that the principal's permissions cover the action's (PermissionDenied);
  * 3. with `validateOnly`, stop;
- * 4. run `prepare`, when the action has one, without a transaction: reads and the declared
+ * 4. reauthorize and replay a committed blob action, if its idempotency key matches;
+ *    otherwise run `prepare`, when the action has one, without a transaction: reads and the declared
  *    connections only, under {@link PREPARE_TIMEOUT};
  * 5. without a handler, answer with what `prepare` returned;
  * 6. open one transaction and run the handler with what `prepare` returned and the runtime, which