@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/runtime/statement.js

@@ -0,0 +1,31 @@
+import { quoteIdentifier } from "../migrate/storage.js";
+/**
+ * Collects the parameters of one statement. Values are always bound as parameters, cast to the
+ * column's type; only identifiers from the definition are written into the SQL text.
+ */
+export class Params {
+    values = [];
+    /** Binds a value and returns its placeholder, cast when a type is given: `$3::bigint`. */
+    add(value, cast) {
+        this.values.push(value);
+        const placeholder = `$${this.values.length}`;
+        return cast === undefined ? placeholder : `${placeholder}::${cast}`;
+    }
+}
+/** `"t0"."owner_id"`. */
+export function columnOf(alias, column) {
+    return `${quoteIdentifier(alias)}.${quoteIdentifier(column)}`;
+}
+/** Hands out table aliases, `t0`, `t1`, …, unique within one statement. */
+export class Aliases {
+    next = 0;
+    take(prefix = "t") {
+        const alias = `${prefix}${this.next}`;
+        this.next += 1;
+        return alias;
+    }
+}
+/** `%` and `_` match literally in LIKE patterns built from caller text; `\` is the escape. */
+export function escapeLike(text) {
+    return text.replace(/[\\%_]/g, (character) => `\\${character}`);
+}

package/dist/runtime/user-identities.d.ts

@@ -0,0 +1,66 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { type SqlError } from "effect/unstable/sql/SqlError";
+import type { Conflict, NotFound } from "../errors.js";
+import type { Ontology } from "../ontology.js";
+import type { StoredRecord } from "../runtime.js";
+import type { UserIdentityOrigin } from "../user-identity.js";
+import { type IdentityAccount } from "./user-identity-sql.js";
+export * from "./user-identity-sql.js";
+/**
+ * Whether the deployed ontology keeps `user_identity`: its table exists and the catalog declares
+ * it. The platform reads databases an earlier SDK deployed too, which have no such table, or keep
+ * one no runtime writes once an earlier SDK was deployed again; those read the legacy stores.
+ */
+export declare function userIdentitiesAvailable(sql: SqlClient.SqlClient): Effect.Effect<boolean, SqlError>;
+export interface IdentityCreate extends IdentityAccount {
+    /** Keeps an id issued before the record, such as a channel account's `_agent_identities` id. */
+    readonly id?: string;
+    readonly userId: string;
+    readonly origin: UserIdentityOrigin;
+    readonly username?: string | null;
+    readonly display?: string | null;
+}
+/**
+ * The platform's writes of `user_identity`: each runs in its own savepoint of the caller's
+ * transaction and records history under `scope`, without a principal. Only these writes change the
+ * entity; the general runtime refuses to. They change `user_identity` alone: callers write the
+ * legacy stores beside them.
+ */
+export declare function makeIdentityWriter(ontology: Ontology, sql: SqlClient.SqlClient, scope: {
+    readonly action: string;
+    readonly actionId: string;
+}): {
+    /** Creates a live identity; Conflict when its account or member key is held. */
+    create: (input: IdentityCreate) => Effect.Effect<StoredRecord, Conflict | NotFound>;
+    /** Revokes a live identity at `at`, freeing its keys; a revoked one changes nothing. */
+    revoke: (id: string, at: string) => Effect.Effect<StoredRecord, Conflict | NotFound>;
+    /** Records the account's current username and display; unchanged values write nothing. */
+    describe: (id: string, values: {
+        readonly username?: string | null;
+        readonly display?: string | null;
+    }) => Effect.Effect<StoredRecord, Conflict | NotFound>;
+};
+export type IdentityWriter = ReturnType<typeof makeIdentityWriter>;
+/** A sign-in identity as the runtime reads it. */
+export interface SignInIdentityRow {
+    readonly id: string;
+    readonly provider: string;
+    readonly issuer: string | null;
+    readonly subject: string;
+}
+/** The member's live sign-in identities: email, SegmentStream and app-token accounts. */
+export declare function liveSignInIdentities(sql: SqlClient.SqlClient, userId: string): Effect.Effect<ReadonlyArray<SignInIdentityRow>, SqlError>;
+/** The user the live account belongs to, or undefined; an account no key can name has none. */
+export declare function userOfAccount(sql: SqlClient.SqlClient, account: IdentityAccount): Effect.Effect<string | undefined, SqlError>;
+/**
+ * Records a live sign-in identity of the member unless the account is held already, by them or by
+ * another member: the caller decides what the latter means. An account no key can name is not
+ * recorded, and so never signs in.
+ */
+export declare function ensureSignInIdentity(writer: IdentityWriter, sql: SqlClient.SqlClient, input: IdentityAccount & {
+    readonly userId: string;
+    readonly origin: UserIdentityOrigin;
+}): Effect.Effect<void, Conflict | NotFound | SqlError>;
+/** Runs {@link USER_IDENTITY_SYNC_SQL} in the caller's transaction. */
+export declare function syncUserIdentities(sql: SqlClient.SqlClient): Effect.Effect<void, SqlError>;

package/dist/runtime/user-identities.js

@@ -0,0 +1,106 @@
+import { Effect } from "effect";
+import { isSqlError } from "effect/unstable/sql/SqlError";
+import { entityModel, ontologyModel } from "./model.js";
+import { uniqueConflict } from "./sql-runtime.js";
+import { accountKey, isRecordableAccount, memberKey, SIGN_IN_ORIGIN_SQL, USER_IDENTITY_ENTITY_ID, USER_IDENTITY_SYNC_SQL, USER_IDENTITY_TABLE, } from "./user-identity-sql.js";
+import { createRecord, updateRecord } from "./writes.js";
+export * from "./user-identity-sql.js";
+/**
+ * Whether the deployed ontology keeps `user_identity`: its table exists and the catalog declares
+ * it. The platform reads databases an earlier SDK deployed too, which have no such table, or keep
+ * one no runtime writes once an earlier SDK was deployed again; those read the legacy stores.
+ */
+export function userIdentitiesAvailable(sql) {
+    return Effect.gen(function* () {
+        const [tables] = yield* sql.unsafe(`SELECT to_regclass($1) IS NOT NULL AS "identities", ` +
+            `to_regclass('"_ontology"') IS NOT NULL AS "catalog"`, [`"${USER_IDENTITY_TABLE}"`]);
+        if (tables?.identities !== true || tables.catalog !== true) {
+            return false;
+        }
+        const [catalog] = yield* sql.unsafe(`SELECT EXISTS (SELECT 1 FROM "_ontology" WHERE "id" ` +
+            `AND "manifest"->'entities' @> $1::jsonb) AS "declared"`, [JSON.stringify([{ id: USER_IDENTITY_ENTITY_ID }])]);
+        return catalog?.declared === true;
+    });
+}
+/**
+ * The platform's writes of `user_identity`: each runs in its own savepoint of the caller's
+ * transaction and records history under `scope`, without a principal. Only these writes change the
+ * entity; the general runtime refuses to. They change `user_identity` alone: callers write the
+ * legacy stores beside them.
+ */
+export function makeIdentityWriter(ontology, sql, scope) {
+    const model = ontologyModel(ontology);
+    const entity = entityModel(model, USER_IDENTITY_TABLE);
+    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),
+    });
+    // A unique violation is a held key; any other database failure is a defect, as in the runtime.
+    const write = (operation) => sql.withTransaction(operation()).pipe(Effect.catchTag("ScopeViolated", (error) => Effect.die(error)), Effect.catchIf(isSqlError, (error) => uniqueConflict(entity, error)));
+    return {
+        /** Creates a live identity; Conflict when its account or member key is held. */
+        create: (input) => Effect.suspend(() => {
+            const values = {
+                provider: input.provider,
+                issuer: input.issuer,
+                subject: input.subject,
+                username: input.username ?? null,
+                display: input.display ?? null,
+                origin: input.origin,
+                revoked_at: null,
+                account_key: accountKey(input),
+                member_key: memberKey(input.userId, input.provider),
+                user: input.userId,
+            };
+            return write(() => createRecord(context(), entity, values, undefined, input.id));
+        }),
+        /** Revokes a live identity at `at`, freeing its keys; a revoked one changes nothing. */
+        revoke: (id, at) => write(() => updateRecord(context(), entity, id, {
+            revoked_at: at,
+            account_key: null,
+            member_key: null,
+        })),
+        /** Records the account's current username and display; unchanged values write nothing. */
+        describe: (id, values) => write(() => updateRecord(context(), entity, id, {
+            ...(values.username === undefined ? {} : { username: values.username }),
+            ...(values.display === undefined ? {} : { display: values.display }),
+        })),
+    };
+}
+/** The member's live sign-in identities: email, SegmentStream and app-token accounts. */
+export function liveSignInIdentities(sql, userId) {
+    return sql.unsafe(`SELECT "i"."id"::text AS "id", "i"."provider", "i"."issuer", "i"."subject" ` +
+        `FROM "${USER_IDENTITY_TABLE}" AS "i" WHERE "i"."user_id" = $1::uuid ` +
+        `AND "i"."origin"::text IN ${SIGN_IN_ORIGIN_SQL} AND "i"."revoked_at" IS NULL ` +
+        `ORDER BY "i"."created_at", "i"."id"`, [userId]);
+}
+/** The user the live account belongs to, or undefined; an account no key can name has none. */
+export function userOfAccount(sql, account) {
+    if (!isRecordableAccount(account)) {
+        return Effect.succeed(undefined);
+    }
+    return sql
+        .unsafe(`SELECT "user_id"::text AS "user_id" FROM "${USER_IDENTITY_TABLE}" WHERE "account_key" = $1`, [accountKey(account)])
+        .pipe(Effect.map(([row]) => row?.user_id));
+}
+/**
+ * Records a live sign-in identity of the member unless the account is held already, by them or by
+ * another member: the caller decides what the latter means. An account no key can name is not
+ * recorded, and so never signs in.
+ */
+export function ensureSignInIdentity(writer, sql, input) {
+    return Effect.gen(function* () {
+        if (!isRecordableAccount(input) || (yield* userOfAccount(sql, input)) !== undefined) {
+            return;
+        }
+        yield* writer.create(input);
+    });
+}
+// @legacy identities.legacy-stores-dual-write
+/** Runs {@link USER_IDENTITY_SYNC_SQL} in the caller's transaction. */
+export function syncUserIdentities(sql) {
+    return sql.unsafe(USER_IDENTITY_SYNC_SQL).unprepared.pipe(Effect.asVoid);
+}

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

@@ -0,0 +1,86 @@
+import type { UserIdentityOrigin } from "../user-identity.js";
+/**
+ * Members' external accounts live in the built-in `user_identity` entity. Until the contract step
+ * removes them, the stores earlier SDKs read stay written beside it in the same transaction: the
+ * member's `user.identity_provider` and `identity_subject`, `_user_identities` for SegmentStream
+ * (OIDC) bindings and `_agent_identities` for channel accounts. See
+ * docs/workspace-user-identities.md. This module holds SQL only, so that the planner can use it.
+ */
+export declare const USER_IDENTITY_TABLE = "user_identity";
+/** The built-in entity's stable id, by which a manifest includes it. */
+export declare const USER_IDENTITY_ENTITY_ID = "ent_user_identity";
+/** The provider of email sign-in: the workspace's Neon Auth. */
+export declare const NEON_AUTH_PROVIDER = "neon-auth";
+/** The provider of SegmentStream (OIDC) sign-in; the issuer tells the issuing deployment apart. */
+export declare const OIDC_PROVIDER = "oidc";
+/** The legacy `user.identity_provider` of an OIDC binding: `oidc:<issuer>`. */
+export declare const LEGACY_OIDC_PREFIX = "oidc:";
+/** Origins of the identities a member signs in with, which the member's user columns mirror. */
+export declare const SIGN_IN_ORIGINS: ReadonlyArray<UserIdentityOrigin>;
+/** Origins of channel accounts, which `_agent_identities` mirrors with the same ids. */
+export declare const CHANNEL_ORIGINS: ReadonlyArray<UserIdentityOrigin>;
+/** `origin IN (…)` of sign-in identities, for SQL on the alias `i`. */
+export declare const SIGN_IN_ORIGIN_SQL: string;
+/** `origin IN (…)` of channel accounts, for SQL on the alias `i`. */
+export declare const CHANNEL_ORIGIN_SQL: string;
+/**
+ * Channel accounts as the runtime reads them: the identity `i`, beside its `_agent_identities` row
+ * `a`, which the dual write keeps with the same id. While earlier SDKs or platforms may still
+ * serve requests, a revocation one of them recorded only in `_agent_identities`, or a row it
+ * deleted there (a preview copy is cleared), ends the identity too; the next migration copies it.
+ */
+export declare const CHANNEL_IDENTITIES_FROM: string;
+/** The `user_identity` record `i` is a live channel account, whatever the legacy store holds. */
+export declare const LIVE_CHANNEL_RECORD: string;
+/** The channel identity `i` (with `a`, see {@link CHANNEL_IDENTITIES_FROM}) is live. */
+export declare const LIVE_CHANNEL_IDENTITY: string;
+/**
+ * When the channel identity `i` (with `a`) stopped working: its own revocation, else the legacy
+ * store's, else, when the legacy row is gone, its last change.
+ */
+export declare const CHANNEL_REVOKED_AT: string;
+/** An external account: the provider, the OIDC issuer for `oidc`, and the id at the provider. */
+export interface IdentityAccount {
+    readonly provider: string;
+    readonly issuer: string | null;
+    readonly subject: string;
+}
+/** The account a legacy `identity_provider` and `identity_subject` name. */
+export declare function accountOfLegacy(identityProvider: string, subject: string): IdentityAccount;
+/** The legacy `identity_provider` of an account: `oidc:<issuer>`, or the provider itself. */
+export declare function legacyProviderOf(account: IdentityAccount): string;
+/** Whether the account can be recorded: a key part never holds whitespace, a subject is set. */
+export declare function isRecordableAccount(account: IdentityAccount): boolean;
+/**
+ * The live account key: `<provider> <subject>`, or `<provider> <issuer> <subject>` for an issuer.
+ * The provider decides whether an issuer is present, and neither holds whitespace, so two accounts
+ * never share a key. {@link accountKeySql} computes the same key in SQL.
+ */
+export declare function accountKey(account: IdentityAccount): string;
+/** The live member key, `<user id> <provider>`, or none for `oidc`, of which a member has several. */
+export declare function memberKey(userId: string, provider: string): string | null;
+/** {@link accountKey} over the columns `provider`, `issuer` and `subject` of the alias given. */
+export declare function accountKeySql(alias: string): string;
+/** {@link memberKey} over the columns `user_id` and `provider` of the alias given. */
+export declare function memberKeySql(alias: string): string;
+/**
+ * Refuses a deploy that drops email sign-in while an active member who signs in by email has no
+ * SegmentStream (OIDC) identity: they would lose access.
+ */
+export declare const SEGMENTSTREAM_LINK_FENCE_SQL: string;
+/**
+ * Refuses a deploy that drops SegmentStream sign-in while an active member with a SegmentStream
+ * identity has no email sign-in: they would lose access.
+ */
+export declare const EMAIL_LINK_FENCE_SQL: string;
+/**
+ * Copies what the legacy stores hold and `user_identity` lacks, idempotently, so that a database
+ * served or migrated by an earlier SDK in between is in step again. Each migration runs it, a no-op
+ * one included, after the entity's table exists. It deletes channel identities whose
+ * `_agent_identities` row is gone (a preview copy clears them), revokes those revoked there, keeps
+ * their username and display current, adds missing channel accounts with their ids, members'
+ * `identity_provider`/`identity_subject` sign-ins and `_user_identities` bindings, and copies
+ * first-contact notices. A row whose key another live identity holds is skipped rather than failing
+ * the deploy. Every change is recorded in history under `user_identity.sync`.
+ */
+export declare const USER_IDENTITY_SYNC_SQL: string;

package/dist/runtime/user-identity-sql.js

@@ -0,0 +1,297 @@
+import { AGENT_IDENTITIES_TABLE, IDENTITY_NOTICES_TABLE, quoteIdentifier, } from "../migrate/storage.js";
+/**
+ * Members' external accounts live in the built-in `user_identity` entity. Until the contract step
+ * removes them, the stores earlier SDKs read stay written beside it in the same transaction: the
+ * member's `user.identity_provider` and `identity_subject`, `_user_identities` for SegmentStream
+ * (OIDC) bindings and `_agent_identities` for channel accounts. See
+ * docs/workspace-user-identities.md. This module holds SQL only, so that the planner can use it.
+ */
+export const USER_IDENTITY_TABLE = "user_identity";
+/** The built-in entity's stable id, by which a manifest includes it. */
+export const USER_IDENTITY_ENTITY_ID = "ent_user_identity";
+/** The provider of email sign-in: the workspace's Neon Auth. */
+export const NEON_AUTH_PROVIDER = "neon-auth";
+/** The provider of SegmentStream (OIDC) sign-in; the issuer tells the issuing deployment apart. */
+export const OIDC_PROVIDER = "oidc";
+/** The legacy `user.identity_provider` of an OIDC binding: `oidc:<issuer>`. */
+export const LEGACY_OIDC_PREFIX = "oidc:";
+/** Origins of the identities a member signs in with, which the member's user columns mirror. */
+export const SIGN_IN_ORIGINS = ["invite", "sign_in", "link"];
+/** Origins of channel accounts, which `_agent_identities` mirrors with the same ids. */
+export const CHANNEL_ORIGINS = ["pairing", "channel"];
+const originList = (origins) => `(${origins.map((origin) => `'${origin}'`).join(", ")})`;
+/** `origin IN (…)` of sign-in identities, for SQL on the alias `i`. */
+export const SIGN_IN_ORIGIN_SQL = originList(SIGN_IN_ORIGINS);
+/** `origin IN (…)` of channel accounts, for SQL on the alias `i`. */
+export const CHANNEL_ORIGIN_SQL = originList(CHANNEL_ORIGINS);
+/**
+ * Channel accounts as the runtime reads them: the identity `i`, beside its `_agent_identities` row
+ * `a`, which the dual write keeps with the same id. While earlier SDKs or platforms may still
+ * serve requests, a revocation one of them recorded only in `_agent_identities`, or a row it
+ * deleted there (a preview copy is cleared), ends the identity too; the next migration copies it.
+ */
+export const CHANNEL_IDENTITIES_FROM = `"${USER_IDENTITY_TABLE}" AS "i" LEFT JOIN "${AGENT_IDENTITIES_TABLE}" AS "a" ` +
+    `ON "a"."id" = "i"."id"`;
+/** The `user_identity` record `i` is a live channel account, whatever the legacy store holds. */
+export const LIVE_CHANNEL_RECORD = `"i"."origin"::text IN ${CHANNEL_ORIGIN_SQL} AND "i"."revoked_at" IS NULL`;
+/** The channel identity `i` (with `a`, see {@link CHANNEL_IDENTITIES_FROM}) is live. */
+export const LIVE_CHANNEL_IDENTITY = `${LIVE_CHANNEL_RECORD} AND "a"."id" IS NOT NULL AND "a"."revoked_at" IS NULL`;
+/**
+ * When the channel identity `i` (with `a`) stopped working: its own revocation, else the legacy
+ * store's, else, when the legacy row is gone, its last change.
+ */
+export const CHANNEL_REVOKED_AT = `COALESCE("i"."revoked_at", "a"."revoked_at", ` +
+    `CASE WHEN "a"."id" IS NULL THEN "i"."updated_at" END)`;
+/** The account a legacy `identity_provider` and `identity_subject` name. */
+export function accountOfLegacy(identityProvider, subject) {
+    return identityProvider.startsWith(LEGACY_OIDC_PREFIX)
+        ? {
+            provider: OIDC_PROVIDER,
+            issuer: identityProvider.slice(LEGACY_OIDC_PREFIX.length),
+            subject,
+        }
+        : { provider: identityProvider, issuer: null, subject };
+}
+/** The legacy `identity_provider` of an account: `oidc:<issuer>`, or the provider itself. */
+export function legacyProviderOf(account) {
+    return account.provider === OIDC_PROVIDER
+        ? `${LEGACY_OIDC_PREFIX}${account.issuer ?? ""}`
+        : account.provider;
+}
+/** Providers and issuers never hold whitespace, so the space-separated keys are unambiguous. */
+function isKeyPart(value) {
+    return value !== "" && !/\s/.test(value);
+}
+function requireKeyPart(value, what) {
+    if (!isKeyPart(value)) {
+        throw new Error(`An identity ${what} must be non-empty and hold no whitespace.`);
+    }
+    return value;
+}
+/** Whether the account can be recorded: a key part never holds whitespace, a subject is set. */
+export function isRecordableAccount(account) {
+    return (isKeyPart(account.provider) &&
+        (account.issuer === null || isKeyPart(account.issuer)) &&
+        account.subject !== "");
+}
+/**
+ * The live account key: `<provider> <subject>`, or `<provider> <issuer> <subject>` for an issuer.
+ * The provider decides whether an issuer is present, and neither holds whitespace, so two accounts
+ * never share a key. {@link accountKeySql} computes the same key in SQL.
+ */
+export function accountKey(account) {
+    const provider = requireKeyPart(account.provider, "provider");
+    return account.issuer === null
+        ? `${provider} ${account.subject}`
+        : `${provider} ${requireKeyPart(account.issuer, "issuer")} ${account.subject}`;
+}
+/** The live member key, `<user id> <provider>`, or none for `oidc`, of which a member has several. */
+export function memberKey(userId, provider) {
+    return provider === OIDC_PROVIDER ? null : `${userId} ${provider}`;
+}
+/** {@link accountKey} over the columns `provider`, `issuer` and `subject` of the alias given. */
+export function accountKeySql(alias) {
+    return (`(${alias}."provider" || ' ' || COALESCE(${alias}."issuer" || ' ', '') || ` +
+        `${alias}."subject")`);
+}
+/** {@link memberKey} over the columns `user_id` and `provider` of the alias given. */
+export function memberKeySql(alias) {
+    return (`(CASE WHEN ${alias}."provider" = '${OIDC_PROVIDER}' THEN NULL ` +
+        `ELSE ${alias}."user_id"::text || ' ' || ${alias}."provider" END)`);
+}
+/** The active member `u` has a live identity of `provider` that `extra` (SQL on `i`) narrows. */
+const HOLDS = (provider, extra = "") => `EXISTS (SELECT 1 FROM "${USER_IDENTITY_TABLE}" i WHERE i.user_id = u.id ` +
+    `AND i.provider = '${provider}' AND i.revoked_at IS NULL${extra})`;
+const ACTIVE_MEMBER = `u.kind::text = 'member' AND u.active = true`;
+/**
+ * Refuses a deploy that drops email sign-in while an active member who signs in by email has no
+ * SegmentStream (OIDC) identity: they would lose access.
+ */
+export const SEGMENTSTREAM_LINK_FENCE_SQL = `DO $$ BEGIN
+  IF EXISTS (SELECT 1 FROM "user" u WHERE ${ACTIVE_MEMBER}
+    AND ${HOLDS(NEON_AUTH_PROVIDER, ` AND i.origin::text IN ${SIGN_IN_ORIGIN_SQL}`)}
+    AND NOT ${HOLDS(OIDC_PROVIDER)})
+  THEN RAISE EXCEPTION 'browser_auth_segmentstream_link_required'; END IF;
+END $$`;
+/**
+ * Refuses a deploy that drops SegmentStream sign-in while an active member with a SegmentStream
+ * identity has no email sign-in: they would lose access.
+ */
+export const EMAIL_LINK_FENCE_SQL = `DO $$ BEGIN
+  IF EXISTS (SELECT 1 FROM "user" u WHERE ${ACTIVE_MEMBER} AND ${HOLDS(OIDC_PROVIDER)}
+    AND NOT ${HOLDS(NEON_AUTH_PROVIDER, ` AND i.origin::text IN ${SIGN_IN_ORIGIN_SQL}`)})
+  THEN RAISE EXCEPTION 'browser_auth_email_link_required'; END IF;
+END $$`;
+const HISTORY = quoteIdentifier(`${USER_IDENTITY_TABLE}_history`);
+const IDENTITIES = quoteIdentifier(USER_IDENTITY_TABLE);
+const NOTICES = quoteIdentifier(IDENTITY_NOTICES_TABLE);
+const AGENT = quoteIdentifier(AGENT_IDENTITIES_TABLE);
+const SYNC_ACTION = `'${USER_IDENTITY_TABLE}.sync'`;
+const INSTANT = (column) => `to_char(${column} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`;
+const CHANGE = (field, before, after) => `CASE WHEN (${before}) IS DISTINCT FROM (${after}) THEN jsonb_build_object('${field}', ` +
+    `jsonb_build_object('before', to_jsonb(${before}), 'after', to_jsonb(${after}))) ` +
+    `ELSE '{}'::jsonb END`;
+/** The history `changes` of a record created from nothing, over the alias `r`. */
+const CREATED = [
+    CHANGE("provider", "NULL::text", "r.provider"),
+    CHANGE("issuer", "NULL::text", "r.issuer"),
+    CHANGE("subject", "NULL::text", "r.subject"),
+    CHANGE("username", "NULL::text", "r.username"),
+    CHANGE("display", "NULL::text", "r.display"),
+    CHANGE("origin", "NULL::text", "r.origin::text"),
+    CHANGE("revoked_at", "NULL::text", INSTANT("r.revoked_at")),
+    CHANGE("account_key", "NULL::text", "r.account_key"),
+    CHANGE("member_key", "NULL::text", "r.member_key"),
+    CHANGE("user_id", "NULL::text", "r.user_id::text"),
+].join(" || ");
+const RECORD_HISTORY = (kind, changes, from) => `INSERT INTO ${HISTORY} ("id", "record_id", "action", "action_id", "kind", "principal_id", ` +
+    `"at", "changes") SELECT gen_random_uuid(), r.id, ${SYNC_ACTION}, sync_action, '${kind}', ` +
+    `NULL, now(), ${changes} FROM ${from} r`;
+const INSERT_COLUMNS = `"id", "created_at", "updated_at", "created_by", "updated_by", "provider", "issuer", ` +
+    `"subject", "username", "display", "origin", "revoked_at", "account_key", "member_key", "user_id"`;
+/** Inserts the rows of `source` (columns as {@link INSERT_COLUMNS}) whose keys are free. */
+const INSERT_FREE = (source) => `WITH source AS (${source}), keyed AS (` +
+    `SELECT s.*, CASE WHEN s.revoked_at IS NULL THEN ${accountKeySql("s")} END AS account_key, ` +
+    `CASE WHEN s.revoked_at IS NULL THEN ${memberKeySql("s")} END AS member_key FROM source s), ` +
+    `free AS (SELECT k.* FROM keyed k ` +
+    `WHERE NOT EXISTS (SELECT 1 FROM ${IDENTITIES} i WHERE i.id = k.id ` +
+    `OR i.account_key = k.account_key OR i.member_key = k.member_key)), ` +
+    `inserted AS (INSERT INTO ${IDENTITIES} (${INSERT_COLUMNS}) ` +
+    `SELECT f.id, f.created_at, now(), NULL, NULL, f.provider, f.issuer, f.subject, f.username, ` +
+    `f.display, f.origin::"${USER_IDENTITY_TABLE}_origin", f.revoked_at, f.account_key, ` +
+    `f.member_key, f.user_id FROM free f RETURNING *) ` +
+    RECORD_HISTORY("create", CREATED, "inserted");
+/**
+ * Whether the member claimed an invitation: as `_channel_users` records it since it exists, or as the
+ * history of `user.invite` does. A statement never names a table the database lacks, even one it
+ * would not read, so each variant is generated on its own.
+ */
+const INVITED = (userId, channelUsers) => `(${channelUsers
+    ? `EXISTS (SELECT 1 FROM "_channel_users" c WHERE c.user_id = ${userId} ` +
+        `AND c.created_via = 'invite') OR `
+    : ""}EXISTS (SELECT 1 FROM "user_history" h WHERE h.record_id = ${userId} ` +
+    `AND h.action = 'user.invite' AND h.kind = 'create'))`;
+/** Members' `identity_provider` and `identity_subject`: `oidc:<issuer>` is an `oidc` account. */
+const MEMBER_SIGN_INS = (channelUsers) => INSERT_FREE(`SELECT gen_random_uuid() AS id, now() AS created_at, l.provider, l.issuer, l.subject,
+      NULL::text AS username, NULL::text AS display,
+      CASE WHEN ${INVITED("l.user_id", channelUsers)} THEN 'invite' ELSE 'sign_in' END AS origin,
+      NULL::timestamptz AS revoked_at, l.user_id
+    FROM (SELECT u.id AS user_id,
+        CASE WHEN u.identity_provider LIKE '${LEGACY_OIDC_PREFIX}%' THEN '${OIDC_PROVIDER}'
+          ELSE u.identity_provider END AS provider,
+        CASE WHEN u.identity_provider LIKE '${LEGACY_OIDC_PREFIX}%'
+          THEN substr(u.identity_provider, ${LEGACY_OIDC_PREFIX.length + 1}) END AS issuer,
+        u.identity_subject AS subject
+      FROM "user" u WHERE u.kind::text = 'member' AND u.identity_provider IS NOT NULL
+        AND u.identity_provider NOT IN ('', '${LEGACY_OIDC_PREFIX}')
+        AND u.identity_provider !~ '\\s' AND COALESCE(u.identity_subject, '') <> '') l
+    WHERE NOT EXISTS (SELECT 1 FROM ${IDENTITIES} i WHERE i.provider = l.provider
+      AND i.issuer IS NOT DISTINCT FROM l.issuer AND i.subject = l.subject)`);
+/**
+ * `_user_identities` bindings. One the member's user columns or their history held is how they
+ * signed in; any other was linked to a signed-in member.
+ */
+const OIDC_BINDINGS = (channelUsers) => INSERT_FREE(`SELECT gen_random_uuid() AS id, now() AS created_at, '${OIDC_PROVIDER}'::text AS provider,
+      b.issuer, b.subject, NULL::text AS username, NULL::text AS display,
+      CASE WHEN NOT EXISTS (SELECT 1 FROM "user_history" h WHERE h.record_id = b.user_id
+          AND h.changes->'identity_provider'->>'after' = '${LEGACY_OIDC_PREFIX}' || b.issuer
+          AND h.changes->'identity_subject'->>'after' = b.subject) THEN 'link'
+        WHEN ${INVITED("b.user_id", channelUsers)} THEN 'invite'
+        ELSE 'sign_in' END AS origin,
+      NULL::timestamptz AS revoked_at, b.user_id
+    FROM "_user_identities" b JOIN "user" u ON u.id = b.user_id
+    WHERE u.kind::text = 'member' AND b.issuer !~ '\\s' AND b.issuer <> ''
+      AND NOT EXISTS (SELECT 1 FROM ${IDENTITIES} i WHERE i.provider = '${OIDC_PROVIDER}'
+        AND i.issuer = b.issuer AND i.subject = b.subject)`);
+/**
+ * Copies what the legacy stores hold and `user_identity` lacks, idempotently, so that a database
+ * served or migrated by an earlier SDK in between is in step again. Each migration runs it, a no-op
+ * one included, after the entity's table exists. It deletes channel identities whose
+ * `_agent_identities` row is gone (a preview copy clears them), revokes those revoked there, keeps
+ * their username and display current, adds missing channel accounts with their ids, members'
+ * `identity_provider`/`identity_subject` sign-ins and `_user_identities` bindings, and copies
+ * first-contact notices. A row whose key another live identity holds is skipped rather than failing
+ * the deploy. Every change is recorded in history under `user_identity.sync`.
+ */
+export const USER_IDENTITY_SYNC_SQL = `DO $sync$
+DECLARE
+  sync_action uuid := gen_random_uuid();
+  channel_users boolean := to_regclass('_channel_users') IS NOT NULL;
+BEGIN
+  IF to_regclass('${USER_IDENTITY_TABLE}') IS NULL OR to_regclass('${USER_IDENTITY_TABLE}_history') IS NULL THEN
+    RETURN;
+  END IF;
+  IF to_regclass('${AGENT_IDENTITIES_TABLE}') IS NOT NULL THEN
+    WITH removed AS (
+      DELETE FROM ${IDENTITIES} i WHERE i.origin::text IN ${CHANNEL_ORIGIN_SQL}
+        AND NOT EXISTS (SELECT 1 FROM ${AGENT} a WHERE a.id = i.id)
+      RETURNING i.*
+    ) ${RECORD_HISTORY("delete", [
+    CHANGE("provider", "r.provider", "NULL::text"),
+    CHANGE("issuer", "r.issuer", "NULL::text"),
+    CHANGE("subject", "r.subject", "NULL::text"),
+    CHANGE("username", "r.username", "NULL::text"),
+    CHANGE("display", "r.display", "NULL::text"),
+    CHANGE("origin", "r.origin::text", "NULL::text"),
+    CHANGE("revoked_at", INSTANT("r.revoked_at"), "NULL::text"),
+    CHANGE("account_key", "r.account_key", "NULL::text"),
+    CHANGE("member_key", "r.member_key", "NULL::text"),
+    CHANGE("user_id", "r.user_id::text", "NULL::text"),
+].join(" || "), "removed")};
+    WITH stale AS (
+      SELECT i.id, i.account_key, i.member_key, a.revoked_at FROM ${IDENTITIES} i
+      JOIN ${AGENT} a ON a.id = i.id
+      WHERE a.revoked_at IS NOT NULL AND i.revoked_at IS NULL
+      FOR UPDATE OF i
+    ), revoked AS (
+      UPDATE ${IDENTITIES} i SET revoked_at = s.revoked_at, account_key = NULL, member_key = NULL,
+        updated_at = now(), updated_by = NULL
+      FROM stale s WHERE i.id = s.id RETURNING i.id
+    ) ${RECORD_HISTORY("update", [
+    CHANGE("revoked_at", "NULL::text", INSTANT("r.revoked_at")),
+    CHANGE("account_key", "r.account_key", "NULL::text"),
+    CHANGE("member_key", "r.member_key", "NULL::text"),
+].join(" || "), "stale")};
+    WITH described AS (
+      SELECT i.id, i.username AS old_username, i.display AS old_display,
+        a.username, a.display FROM ${IDENTITIES} i JOIN ${AGENT} a ON a.id = i.id
+      WHERE i.revoked_at IS NULL AND a.revoked_at IS NULL
+        AND (i.username IS DISTINCT FROM a.username OR i.display IS DISTINCT FROM a.display)
+      FOR UPDATE OF i
+    ), updated AS (
+      UPDATE ${IDENTITIES} i SET username = d.username, display = d.display, updated_at = now(),
+        updated_by = NULL FROM described d WHERE i.id = d.id RETURNING i.id
+    ) ${RECORD_HISTORY("update", [
+    CHANGE("username", "r.old_username", "r.username"),
+    CHANGE("display", "r.old_display", "r.display"),
+].join(" || "), "described")};
+    ${INSERT_FREE(`SELECT a.id, a.created_at, a.provider, NULL::text AS issuer, a.external_id AS subject,
+        a.username, a.display,
+        CASE WHEN a.origin = 'provisioned' THEN 'channel' ELSE 'pairing' END AS origin,
+        a.revoked_at, a.user_id FROM ${AGENT} a`)};
+  END IF;
+  IF channel_users THEN
+    ${MEMBER_SIGN_INS(true)};
+  ELSE
+    ${MEMBER_SIGN_INS(false)};
+  END IF;
+  IF to_regclass('_user_identities') IS NOT NULL THEN
+    IF channel_users THEN
+      ${OIDC_BINDINGS(true)};
+    ELSE
+      ${OIDC_BINDINGS(false)};
+    END IF;
+  END IF;
+  IF to_regclass('${IDENTITY_NOTICES_TABLE}') IS NOT NULL THEN
+    IF to_regclass('${AGENT_IDENTITIES_TABLE}') IS NOT NULL THEN
+      INSERT INTO ${NOTICES} (identity_id, noticed_at, notice_sha256, notice_version)
+      SELECT a.id, a.noticed_at, a.notice_sha256, a.notice_version FROM ${AGENT} a
+      WHERE a.noticed_at IS NOT NULL AND EXISTS (SELECT 1 FROM ${IDENTITIES} i WHERE i.id = a.id)
+      ON CONFLICT (identity_id) DO UPDATE SET noticed_at = EXCLUDED.noticed_at,
+        notice_sha256 = EXCLUDED.notice_sha256, notice_version = EXCLUDED.notice_version
+      WHERE (${NOTICES}.noticed_at, ${NOTICES}.notice_sha256, ${NOTICES}.notice_version)
+        IS DISTINCT FROM (EXCLUDED.noticed_at, EXCLUDED.notice_sha256, EXCLUDED.notice_version);
+    END IF;
+    DELETE FROM ${NOTICES} n WHERE NOT EXISTS (SELECT 1 FROM ${IDENTITIES} i WHERE i.id = n.identity_id);
+  END IF;
+END $sync$`;

package/dist/runtime/user-roles.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The built-in user's `roles`: the roles assigned to the user in `_user_roles`, sorted, without the
+ * `member` every active member holds implicitly. It is the only `list` property, and has no column.
+ */
+export declare const USER_ROLES_PROPERTY = "roles";
+/**
+ * The roles of the user whose id is the SQL expression `userId`, as a JSON array: sorted, without
+ * `member`, `[]` when none. As a subquery of the statement that reads the user, it is consistent
+ * with the row it reads.
+ */
+export declare function userRolesExpression(userId: string): string;
+/**
+ * Whether the user whose id is the SQL expression `userId` is assigned one of the roles, given as
+ * SQL expressions such as parameters. `member` is never listed, so it matches no user.
+ */
+export declare function userHoldsRoleCondition(userId: string, roles: ReadonlyArray<string>): string;

package/dist/runtime/user-roles.js

@@ -0,0 +1,32 @@
+import { USER_ROLES_TABLE, quoteIdentifier, quoteLiteral } from "../migrate/storage.js";
+import { MEMBER_ROLE } from "../names.js";
+/**
+ * The built-in user's `roles`: the roles assigned to the user in `_user_roles`, sorted, without the
+ * `member` every active member holds implicitly. It is the only `list` property, and has no column.
+ */
+export const USER_ROLES_PROPERTY = "roles";
+const ROLES = quoteIdentifier(USER_ROLES_TABLE);
+/** Unlikely to shadow an alias of the enclosing statement, whose aliases are `t0`, `t1`, `j0`… */
+const ASSIGNED = '"_assigned_role"';
+const NOT_MEMBER = `${ASSIGNED}."role" <> ${quoteLiteral(MEMBER_ROLE)}`;
+/**
+ * The roles of the user whose id is the SQL expression `userId`, as a JSON array: sorted, without
+ * `member`, `[]` when none. As a subquery of the statement that reads the user, it is consistent
+ * with the row it reads.
+ */
+export function userRolesExpression(userId) {
+    return (`COALESCE((SELECT json_agg(${ASSIGNED}."role" ORDER BY ${ASSIGNED}."role") ` +
+        `FROM ${ROLES} AS ${ASSIGNED} WHERE ${ASSIGNED}."user_id" = ${userId} AND ${NOT_MEMBER}), ` +
+        `'[]'::json)`);
+}
+/**
+ * Whether the user whose id is the SQL expression `userId` is assigned one of the roles, given as
+ * SQL expressions such as parameters. `member` is never listed, so it matches no user.
+ */
+export function userHoldsRoleCondition(userId, roles) {
+    if (roles.length === 0) {
+        return "FALSE";
+    }
+    return (`EXISTS (SELECT 1 FROM ${ROLES} AS ${ASSIGNED} WHERE ${ASSIGNED}."user_id" = ${userId} ` +
+        `AND ${NOT_MEMBER} AND ${ASSIGNED}."role" IN (${roles.join(", ")}))`);
+}