@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/runtime/principals.js

@@ -0,0 +1,1307 @@
+import { propertyDefinition } from "../property.js";
+import { pbkdf2, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { promisify } from "node:util";
+import { Effect, Schema } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { isSqlError } from "effect/unstable/sql/SqlError";
+import { entity, } from "../entity.js";
+import { AGENT_IDENTITIES_TABLE, CHANNEL_USERS_TABLE, API_KEYS_TABLE, USER_ROLES_TABLE, USER_TABLE, } from "../migrate/storage.js";
+import { MEMBER_ROLE, FEEDBACK_REPORTER_ROLE, toSnakeCase } from "../names.js";
+import { feedbackRoles } from "../feedback-config.js";
+import { buildManifest } from "../manifest.js";
+import { buildOntology } from "../ontology.js";
+import { EXPLICIT_GRANT_ENTITIES, permissionsOf, principalScopes, WILDCARD_ENTITY_VERBS, } from "../permissions.js";
+import { EMAIL_PATTERN } from "../property.js";
+import { role, roleEntries } from "../role.js";
+import { beginReplicationWrite } from "../replication/transaction.js";
+import { User } from "../user.js";
+import { MemberNotFound, PrincipalRejected, UnknownRole } from "./errors.js";
+import { channelUsersAvailable, recordUserCreation, revokeMemberSessions, } from "./member-tables.js";
+import { refuseMember, requireGrantable } from "./member-writes.js";
+import { isRecordId } from "./records.js";
+import { makeOntologyRuntime, makePrincipalUserWriter, } from "./sql-runtime.js";
+import { accountOfLegacy, CHANNEL_IDENTITIES_FROM, liveSignInIdentities, LIVE_CHANNEL_IDENTITY, LIVE_CHANNEL_RECORD, makeIdentityWriter, NEON_AUTH_PROVIDER, OIDC_PROVIDER, SIGN_IN_ORIGIN_SQL, USER_IDENTITY_TABLE, userIdentitiesAvailable, userOfAccount, } from "./user-identities.js";
+import { PIPELINE_WORKER_PROVIDER } from "./workload.js";
+import { WORKFLOW_USER_PROVIDER, workflowSubject } from "./workflow-users.js";
+export { WORKFLOW_USER_PROVIDER, workflowSubject } from "./workflow-users.js";
+export { revokeMemberSessions } from "./member-tables.js";
+/** API keys are `ssk_<key id>.<secret>`. */
+export const API_KEY_PREFIX = "ssk_";
+/**
+ * PBKDF2-SHA256 iterations for a key's secret: about 5 ms per verification on Node. The secret
+ * already carries 256 bits of entropy, so the KDF is not what protects it; it exists so that stored
+ * secrets are handled like any password storage, and it must stay cheap because it runs on every
+ * request authenticated with an API key.
+ */
+export const API_KEY_ITERATIONS = 10_000;
+const KEY_ID_BYTES = 8;
+const SECRET_BYTES = 32;
+const SALT_BYTES = 16;
+const HASH_BYTES = 32;
+/** base64url of 8 and 32 bytes: 11 and 43 characters, none of them a dot. */
+const API_KEY = /^ssk_([A-Za-z0-9_-]{11})\.([A-Za-z0-9_-]{43})$/;
+const pbkdf2Async = promisify(pbkdf2);
+/** A new API key: 8 random bytes of key id and 32 of secret. Show it once; it is not stored. */
+export function generateApiKey() {
+    const keyId = randomBytes(KEY_ID_BYTES).toString("base64url");
+    const secret = randomBytes(SECRET_BYTES).toString("base64url");
+    return `${API_KEY_PREFIX}${keyId}.${secret}`;
+}
+/** The key id and secret of a key, or `undefined` when it is not one. */
+export function parseApiKey(key) {
+    const match = API_KEY.exec(key);
+    return match === null ? undefined : { keyId: match[1], secret: match[2] };
+}
+/** PBKDF2-SHA256 of a secret with its salt, in hex: what `_api_keys.hash` holds. */
+export async function hashApiKeySecret(secret, salt) {
+    const hash = await pbkdf2Async(secret, salt, API_KEY_ITERATIONS, HASH_BYTES, "sha256");
+    return hash.toString("hex");
+}
+/** Compared against when no row matches, so that every rejection costs one KDF. */
+const UNKNOWN_KEY = { salt: randomBytes(SALT_BYTES).toString("hex"), hash: "0".repeat(64) };
+function sameHash(left, right) {
+    const leftBytes = Buffer.from(left, "hex");
+    const rightBytes = Buffer.from(right, "hex");
+    return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+}
+/**
+ * Every request authenticates, so recording each one would write a history row per request. A
+ * returning member's sign-in is recorded once the last one is older than a Neon Auth token's
+ * lifetime: about once per token, which is how often an active member authenticates afresh.
+ */
+export const SIGN_IN_RECORD_INTERVAL_MS = 15 * 60 * 1000;
+/** Whether a returning member's sign-in is recorded: they have none yet, or none this interval. */
+function signInDue(lastSignInAt, now) {
+    if (typeof lastSignInAt !== "string") {
+        return true;
+    }
+    const last = Date.parse(lastSignInAt);
+    return Number.isNaN(last) || now.getTime() - last >= SIGN_IN_RECORD_INTERVAL_MS;
+}
+/** User rows as principal resolution reads them. */
+const UserRow = Schema.Struct({
+    id: Schema.String,
+    kind: Schema.Literals(["member", "service"]),
+    active: Schema.Boolean,
+});
+const decodeUser = Schema.decodeUnknownSync(UserRow);
+/** Writes the platform makes outside any principal's action: history names them, without a principal. */
+function platformRuntime(ontology, sql, action, actionId = randomUUID()) {
+    return makeOntologyRuntime(ontology, sql, { action, actionId, principalId: null });
+}
+/** The history actions of member role changes, as the generated `user` actions name them. */
+export const MEMBER_HISTORY_ACTIONS = {
+    invite: "user.invite",
+    grantRoles: "user.grant_roles",
+    revokeRoles: "user.revoke_roles",
+    deactivate: "user.deactivate",
+    reactivate: "user.reactivate",
+};
+export function rolesOf(ontology, sql, user) {
+    return Effect.gen(function* () {
+        const rows = yield* sql.unsafe(`SELECT "role" FROM "${USER_ROLES_TABLE}" WHERE "user_id" = $1::uuid ORDER BY "role"`, [user.id]);
+        // Ignore forged or historical stored assignments: reporter authority is never persisted.
+        const assigned = rows
+            .map((row) => String(row.role))
+            .filter((role) => toSnakeCase(role) !== FEEDBACK_REPORTER_ROLE);
+        // Every active member holds `member`; a service holds exactly the roles it was given.
+        const roles = user.kind === "member"
+            ? [
+                MEMBER_ROLE,
+                ...assigned.filter((role) => role !== MEMBER_ROLE),
+                ...(ontology.roles.some((role) => role.name === FEEDBACK_REPORTER_ROLE)
+                    ? [FEEDBACK_REPORTER_ROLE]
+                    : []),
+            ]
+            : assigned;
+        // A role the deployed ontology no longer declares grants nothing.
+        return {
+            id: user.id,
+            kind: user.kind,
+            roles,
+            permissions: permissionsOf(ontology.roles, roles),
+            ...principalScopes(ontology.roles, roles),
+        };
+    });
+}
+function activePrincipal(ontology, sql, user) {
+    return Effect.gen(function* () {
+        if (!user.active || (user.kind === "member" && (yield* isMemberBlocked(sql, user.id)))) {
+            return yield* new PrincipalRejected({
+                reason: "inactive_user",
+                message: "The user is inactive.",
+            });
+        }
+        return yield* rolesOf(ontology, sql, user);
+    });
+}
+function userRow(record) {
+    return decodeUser({ id: record.id, kind: record.kind, active: record.active });
+}
+/** Resolve a workspace-owned identity/session by user id, with current activity and roles. */
+export function resolvePrincipalById(ontology, sql, id) {
+    return Effect.gen(function* () {
+        const runtime = makeOntologyRuntime(ontology, sql);
+        const [record] = yield* runtime.find({ entity: "user", options: { where: { id }, limit: 1 } });
+        if (!record || record.kind !== "member") {
+            return yield* new PrincipalRejected({
+                reason: "identity_conflict",
+                message: "Unknown workspace member.",
+            });
+        }
+        return yield* activePrincipal(ontology, sql, userRow(record));
+    });
+}
+/**
+ * Finds the member's user without locking. Links or creates it transactionally when needed. A
+ * user linked to this identity is found; else a member invited with the same email is linked; else
+ * the ontology's sign-in policy decides: `invited` turns the person away, `open` creates a member.
+ */
+function signIn(ontology, sql, claims) {
+    const runtime = makeOntologyRuntime(ontology, sql);
+    const writerActionId = randomUUID();
+    const writer = makePrincipalUserWriter(ontology, sql, {
+        action: "user.sign_in",
+        actionId: writerActionId,
+    });
+    const claimedEmail = claims.email?.trim().toLowerCase();
+    const email = claimedEmail !== undefined && EMAIL_PATTERN.test(claimedEmail) ? claimedEmail : undefined;
+    // The account the token names, as `user_identity` holds it: `oidc:<issuer>` is an oidc account.
+    const account = accountOfLegacy(claims.identityProvider, claims.identitySubject);
+    const sameAccount = (identity) => identity.provider === account.provider &&
+        identity.issuer === account.issuer &&
+        identity.subject === account.subject;
+    // The member's `user_identity` record finds them; their user row is what is locked. Without one,
+    // the user columns still find a member an earlier SDK signed in during a cutover, until the next
+    // migration copies the account, and a service, which is found to be refused.
+    const findLinked = (forUpdate = false) => Effect.gen(function* () {
+        const userId = yield* userOfAccount(sql, account);
+        return yield* runtime.find({
+            entity: "user",
+            options: {
+                where: userId === undefined
+                    ? {
+                        identity_provider: claims.identityProvider,
+                        identity_subject: claims.identitySubject,
+                    }
+                    : { id: userId },
+                limit: 1,
+                forUpdate,
+            },
+        });
+    });
+    // The user columns stay written for SDKs before `user_identity`; the record is written beside.
+    const recordIdentity = (userId, origin) => makeIdentityWriter(ontology, sql, {
+        action: `${USER_IDENTITY_TABLE}.sign_in`,
+        actionId: writerActionId,
+    }).create({ ...account, userId, origin });
+    const member = (record) => record.kind === "member"
+        ? Effect.succeed(userRow(record))
+        : Effect.fail(new PrincipalRejected({
+            reason: "identity_conflict",
+            message: "This identity belongs to a service, not a member.",
+        }));
+    return Effect.gen(function* () {
+        const [known] = yield* findLinked();
+        if (known !== undefined) {
+            const user = yield* member(known);
+            // Ordinary authentication is read-only. Optional bookkeeping must never queue behind a
+            // business transaction holding a User key or row lock; a later request can record it.
+            if (!user.active || !writer.recordsSignIn || !signInDue(known.last_sign_in_at, new Date())) {
+                return user;
+            }
+            return yield* sql.withTransaction(Effect.gen(function* () {
+                const [locked] = yield* sql.unsafe(`SELECT "id" FROM "${USER_TABLE}" WHERE "id" = $1::uuid FOR UPDATE SKIP LOCKED`, [user.id]);
+                if (locked === undefined) {
+                    return user;
+                }
+                const current = yield* runtime.get({ entity: "user", id: user.id });
+                const principal = yield* member(current);
+                const now = new Date();
+                if (principal.active && signInDue(current.last_sign_in_at, now)) {
+                    yield* writer.update(user.id, { last_sign_in_at: now.toISOString() });
+                }
+                return principal;
+            }));
+        }
+        // CLI file commands use trusted SegmentStream app tokens while the browser uses Neon Auth.
+        // Both issuers verify the email. Resolve the existing member without replacing their Neon
+        // subject: browser sessions, pairings and current role assignments must keep the same user.
+        // A different subject of the same provider still conflicts, as do service users and tokens
+        // @legacy app.legacy-segmentstream-sign-in
+        // without a verified email. Only the platform-to-Neon compatibility path uses this lookup.
+        if (claims.identityProvider === "segmentstream" && email !== undefined) {
+            const [neon] = yield* sql.unsafe(`SELECT "u"."id"::text AS "id", "u"."kind"::text AS "kind", "u"."active" AS "active" ` +
+                `FROM "${USER_TABLE}" AS "u" WHERE "u"."email" = $1 AND "u"."kind" = 'member' ` +
+                `AND EXISTS (SELECT 1 FROM "${USER_IDENTITY_TABLE}" AS "i" WHERE "i"."user_id" = "u"."id" ` +
+                `AND "i"."provider" = $2 AND "i"."origin"::text IN ${SIGN_IN_ORIGIN_SQL} ` +
+                `AND "i"."revoked_at" IS NULL) LIMIT 1`, [email, NEON_AUTH_PROVIDER]);
+            if (neon !== undefined) {
+                return decodeUser(neon);
+            }
+        }
+        return yield* sql.withTransaction(Effect.gen(function* () {
+            if (claims.identityProvider === "neon-auth") {
+                yield* sql.unsafe(`SELECT pg_advisory_xact_lock_shared(hashtextextended('segmentstream.ontology.migration', 0))`);
+                const [catalog] = yield* sql.unsafe(`SELECT manifest->'sign_in'->'browser'->'methods' AS methods FROM "_ontology" WHERE id`);
+                if (Array.isArray(catalog?.methods) && !catalog.methods.includes("email")) {
+                    return yield* new PrincipalRejected({
+                        reason: "identity_conflict",
+                        message: "browser_method_disabled",
+                    });
+                }
+            }
+            const now = new Date();
+            const signedIn = writer.recordsSignIn ? { last_sign_in_at: now.toISOString() } : {};
+            const [linked] = yield* findLinked(true);
+            if (linked !== undefined) {
+                return yield* member(linked);
+            }
+            const [invited] = email === undefined
+                ? []
+                : yield* runtime.find({
+                    entity: "user",
+                    options: { where: { email }, limit: 1, forUpdate: true },
+                });
+            if (invited !== undefined) {
+                // A concurrent first sign-in may have linked this invitation while this transaction
+                // waited for its row. Accept the exact identity; another identity still conflicts.
+                const held = invited.kind === "member" ? yield* liveSignInIdentities(sql, String(invited.id)) : [];
+                // An earlier SDK serving the workspace during a cutover writes only the user's columns.
+                // Its sign-in still holds the invitation until the next migration copies it.
+                const legacy = typeof invited.identity_subject === "string" && invited.identity_subject !== ""
+                    ? {
+                        provider: String(invited.identity_provider ?? ""),
+                        subject: invited.identity_subject,
+                    }
+                    : undefined;
+                const legacyIsThisAccount = legacy !== undefined &&
+                    legacy.provider === claims.identityProvider &&
+                    legacy.subject === claims.identitySubject;
+                if (held.some(sameAccount)) {
+                    return yield* member(invited);
+                }
+                if (invited.kind === "member" && held.length === 0 && legacyIsThisAccount) {
+                    yield* recordIdentity(String(invited.id), "invite");
+                    return yield* member(invited);
+                }
+                if (invited.kind !== "member" ||
+                    held.length > 0 ||
+                    legacy !== undefined ||
+                    (account.provider === OIDC_PROVIDER && invited.active !== true)) {
+                    return yield* new PrincipalRejected({
+                        reason: "identity_conflict",
+                        message: "Another user already has this email.",
+                    });
+                }
+                yield* recordUserCreation(sql, String(invited.id), "invite");
+                const linkedUser = yield* writer.update(invited.id, {
+                    identity_provider: claims.identityProvider,
+                    identity_subject: claims.identitySubject,
+                    ...(invited.active === true ? signedIn : {}),
+                });
+                yield* recordIdentity(String(invited.id), "invite");
+                return userRow(linkedUser);
+            }
+            if (ontology.signIn.policy !== "open") {
+                return yield* new PrincipalRejected({
+                    reason: "not_invited",
+                    message: "No member was invited with this identity or email.",
+                });
+            }
+            const created = yield* writer.create({
+                name: claims.name?.trim() || email || claims.identitySubject,
+                email: email ?? null,
+                kind: "member",
+                identity_provider: claims.identityProvider,
+                identity_subject: claims.identitySubject,
+                ...signedIn,
+            });
+            yield* recordUserCreation(sql, String(created.id), "email");
+            yield* recordIdentity(String(created.id), "sign_in");
+            return userRow(created);
+        }));
+    }).pipe(Effect.catchTag("NotFound", (error) => Effect.die(error)));
+}
+/**
+ * The principal of a member signed in with a verified token. On first sign-in the member's `user`
+ * is linked by email when someone invited them; a person nobody invited is rejected as
+ * `not_invited` under the `invited` policy and becomes a member holding only `member` under
+ * `open`. Every sign-in that lets the member in sets `lastSignInAt`, at most once per
+ * {@link SIGN_IN_RECORD_INTERVAL_MS}, so history keeps it. If the User row is busy, recording is
+ * deferred to a later request instead of delaying authentication. Inactive users are rejected.
+ */
+export function resolvePrincipalByIdentity(ontology, claims) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const attempt = signIn(ontology, sql, claims);
+        // Two first sign-ins of one member race to create the user; the loser finds it on retry.
+        const user = yield* attempt.pipe(Effect.catchTag("Conflict", () => attempt), Effect.catchTag("Conflict", () => Effect.fail(new PrincipalRejected({
+            reason: "identity_conflict",
+            message: "The sign-in conflicts with another user.",
+        }))));
+        return yield* activePrincipal(ontology, sql, user);
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/** Resolve the workspace's stable keyless pipeline service, without customer roles or sign-in. */
+export function resolvePipelineWorker(ontology, execution) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const provider = PIPELINE_WORKER_PROVIDER;
+        const subject = `pipeline-workers:${execution.workspaceId}`;
+        const runtime = platformRuntime(ontology, sql, "user.resolve_pipeline_worker");
+        const principal = (user) => user.kind !== "service" || user.active !== true
+            ? Effect.fail(new PrincipalRejected({
+                reason: "inactive_user",
+                message: "The pipeline worker principal is inactive or has an invalid kind.",
+            }))
+            : Effect.succeed({
+                id: user.id,
+                kind: "service",
+                roles: [],
+                permissions: ["*:*"],
+                execution,
+            });
+        const find = (forUpdate) => runtime.find({
+            entity: "user",
+            options: {
+                where: { identity_provider: provider, identity_subject: subject },
+                limit: 1,
+                forUpdate,
+            },
+        });
+        const [known] = yield* find(false);
+        // Returning requests only read the principal; writes revalidate it in their transaction.
+        if (known !== undefined) {
+            return yield* principal(known);
+        }
+        return yield* sql
+            .withTransaction(Effect.gen(function* () {
+            // The replication lock precedes every business lock, including principal initialization.
+            yield* beginReplicationWrite(sql);
+            yield* sql.unsafe("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
+                provider + ":" + subject,
+            ]);
+            const [existing] = yield* find(true);
+            const user = existing ??
+                (yield* runtime.create({
+                    entity: "user",
+                    values: {
+                        name: "Pipeline workers",
+                        kind: "service",
+                        identity_provider: provider,
+                        identity_subject: subject,
+                    },
+                }));
+            return yield* principal(user);
+        }))
+            .pipe(Effect.catchTag("Conflict", (error) => Effect.die(error)), Effect.catchTag(["NotFound", "ScopeViolated"], (error) => Effect.die(error)));
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/** A keyless hook actor with only the workspace's opted-in role; deactivated actors stay inactive. */
+export function resolveHookService(ontology, heldRole) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const configured = ontology.config.hooks?.role;
+        if (configured === undefined ||
+            heldRole === FEEDBACK_REPORTER_ROLE ||
+            toSnakeCase(configured) !== heldRole ||
+            !ontology.roles.some((candidate) => candidate.name === heldRole)) {
+            return yield* new PrincipalRejected({
+                reason: "identity_conflict",
+                message: "Hook service execution is not configured for this role.",
+            });
+        }
+        const provider = "segmentstream-ontology-hook";
+        const subject = heldRole;
+        const runtime = platformRuntime(ontology, sql, "user.resolve_hook_service");
+        const principal = (user) => user.kind !== "service" || user.active !== true
+            ? Effect.fail(new PrincipalRejected({
+                reason: "inactive_user",
+                message: "The hook service principal is inactive or has an invalid kind.",
+            }))
+            : rolesOf(ontology, sql, userRow(user)).pipe(Effect.map((resolved) => {
+                const roles = resolved.roles.includes(heldRole) ? [heldRole] : [];
+                return {
+                    id: resolved.id,
+                    kind: resolved.kind,
+                    roles,
+                    permissions: permissionsOf(ontology.roles, roles),
+                    ...principalScopes(ontology.roles, roles),
+                };
+            }));
+        const find = (forUpdate) => runtime.find({
+            entity: "user",
+            options: {
+                where: { identity_provider: provider, identity_subject: subject },
+                limit: 1,
+                forUpdate,
+            },
+        });
+        const [known] = yield* find(false);
+        if (known !== undefined) {
+            return yield* principal(known);
+        }
+        return yield* sql
+            .withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
+            yield* sql.unsafe("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
+                provider + ":" + subject,
+            ]);
+            const [existing] = yield* find(true);
+            const user = existing ??
+                (yield* runtime.create({
+                    entity: "user",
+                    values: {
+                        name: configured,
+                        kind: "service",
+                        identity_provider: provider,
+                        identity_subject: subject,
+                    },
+                }));
+            if (existing === undefined) {
+                yield* sql.unsafe(`INSERT INTO "${USER_ROLES_TABLE}" ("user_id", "role") VALUES ($1::uuid, $2::text)`, [user.id, heldRole]);
+            }
+            return yield* principal(user);
+        }))
+            .pipe(Effect.catchTag("Conflict", (error) => Effect.die(error)), Effect.catchTag(["NotFound", "ScopeViolated"], (error) => Effect.die(error)));
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/**
+ * A workflow user's permissions: what `member` and the workflow's role grant, as `check` verified.
+ * A `*:*` of member's is spelled out per entity, so that it covers what a named grant covers and
+ * never the pipeline worker's workload wildcard; `check` refuses a workflow role holding `*:*`. An
+ * entity a wildcard covers only some verbs of, the user, is spelled out with those verbs.
+ */
+export function workflowPermissions(ontology, role) {
+    if (toSnakeCase(role) === FEEDBACK_REPORTER_ROLE) {
+        return [];
+    }
+    return permissionsOf(ontology.roles, [MEMBER_ROLE, role]).flatMap((permission) => permission === "*:*"
+        ? ontology.entities
+            .filter((candidate) => !EXPLICIT_GRANT_ENTITIES.has(candidate.name))
+            .flatMap((candidate) => {
+            const verbs = WILDCARD_ENTITY_VERBS.get(candidate.name);
+            return verbs === undefined
+                ? [`${candidate.name}:*`]
+                : [...verbs].map((verb) => `${candidate.name}:${verb}`);
+        })
+        : [permission]);
+}
+/** The roles assigned to a user, sorted. */
+function assignedRoles(sql, userId) {
+    return sql
+        .unsafe(`SELECT "role" FROM "${USER_ROLES_TABLE}" WHERE "user_id" = $1::uuid ORDER BY "role"`, [userId])
+        .pipe(Effect.map((rows) => rows.map((row) => row.role)));
+}
+/** Sets the user's roles to exactly the workflow's role when they differ, with the role writer. */
+function syncWorkflowRole(ontology, sql, userId, role) {
+    return Effect.gen(function* () {
+        const held = yield* assignedRoles(sql, userId);
+        if (held.length !== 1 || held[0] !== role) {
+            // `check` verified the role is declared; an undeclared one here is a defect.
+            yield* writeUserRoles(ontology, sql, { userId, roles: [role] }).pipe(Effect.orDie);
+        }
+    });
+}
+/**
+ * The workflow's user, created if missing, with exactly the workflow's role, inside the caller's
+ * transaction and under the lock every creator of this user takes. It does not change `active`.
+ */
+function ensureWorkflowUser(ontology, sql, runtime, input) {
+    return Effect.gen(function* () {
+        yield* sql.unsafe("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
+            WORKFLOW_USER_PROVIDER + ":" + input.subject,
+        ]);
+        const [existing] = yield* runtime.find({
+            entity: "user",
+            options: {
+                where: { identity_provider: WORKFLOW_USER_PROVIDER, identity_subject: input.subject },
+                limit: 1,
+                forUpdate: true,
+            },
+        });
+        if (existing !== undefined && input.mode === "resolve") {
+            const held = yield* assignedRoles(sql, existing.id);
+            if (held.length !== 1 || held[0] !== input.workflow.role) {
+                return yield* new PrincipalRejected({
+                    reason: "role_mismatch",
+                    message: "The workflow user's roles are not the workflow's declared role; the deploy that " +
+                        "recorded this ontology reconciles them.",
+                });
+            }
+            return existing;
+        }
+        const user = existing ??
+            (yield* runtime
+                .create({
+                entity: "user",
+                values: {
+                    name: input.workflow.name,
+                    kind: "service",
+                    identity_provider: WORKFLOW_USER_PROVIDER,
+                    identity_subject: input.subject,
+                },
+            })
+                .pipe(Effect.orDie));
+        yield* syncWorkflowRole(ontology, sql, user.id, input.workflow.role);
+        return user;
+    });
+}
+/**
+ * Resolve the keyless service user a workflow's runs act as: one per declared workflow, holding
+ * exactly the workflow's role, named by `workflows:<workspace id>:<workflow name>`. Deploy creates
+ * it; a run before that creates it here. It never rewrites roles: a user whose roles are not
+ * exactly the declared role is rejected (`role_mismatch`) until a deploy reconciles it. A workflow
+ * the serving ontology does not declare is rejected, as is an inactive user. Its permissions are
+ * what `member` and its role grant, and every action checks them as for any caller.
+ */
+export function resolveWorkflowUser(ontology, input) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const declared = ontology.workflows.find((candidate) => candidate.name === input.workflow);
+        if (declared === undefined || toSnakeCase(declared.role) === FEEDBACK_REPORTER_ROLE) {
+            return yield* new PrincipalRejected({
+                reason: "unknown_workflow",
+                message: "The serving ontology declares no such workflow.",
+            });
+        }
+        const subject = workflowSubject(input.workspaceId, declared.name);
+        const runtime = platformRuntime(ontology, sql, "user.resolve_workflow_user");
+        const [known] = yield* runtime.find({
+            entity: "user",
+            options: {
+                where: { identity_provider: WORKFLOW_USER_PROVIDER, identity_subject: subject },
+                limit: 1,
+            },
+        });
+        const held = known === undefined ? [] : yield* assignedRoles(sql, known.id);
+        // The deployed database is the authority on roles: deploy sets them, a run never rewrites them.
+        if (known !== undefined && (held.length !== 1 || held[0] !== declared.role)) {
+            return yield* new PrincipalRejected({
+                reason: "role_mismatch",
+                message: "The workflow user's roles are not the workflow's declared role; the deploy that " +
+                    "recorded this ontology reconciles them.",
+            });
+        }
+        // A run of a deployed workflow only reads; a run before its deploy creates the user.
+        const user = known !== undefined
+            ? known
+            : yield* sql.withTransaction(Effect.gen(function* () {
+                // The replication lock precedes every business lock, including principal creation.
+                yield* beginReplicationWrite(sql);
+                return yield* ensureWorkflowUser(ontology, sql, runtime, {
+                    workflow: declared,
+                    subject,
+                    mode: "resolve",
+                });
+            }));
+        if (user.kind !== "service" || user.active !== true) {
+            return yield* new PrincipalRejected({
+                reason: "inactive_user",
+                message: "The workflow user is inactive or has an invalid kind.",
+            });
+        }
+        return {
+            id: user.id,
+            kind: "service",
+            roles: [declared.role],
+            permissions: workflowPermissions(ontology, declared.role),
+            ...principalScopes(ontology.roles, [MEMBER_ROLE, declared.role]),
+            workflow: { name: declared.name, subject },
+        };
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/**
+ * Brings the workflow users of the workspace in line with the ontology's workflows, as deploy does
+ * in the migration's transaction: each declared workflow's user is created if missing, reactivated
+ * and given exactly the workflow's role; a user whose workflow is no longer declared is
+ * deactivated, so its runs are refused and history keeps its name. Repeating it changes nothing.
+ * Database failures, including those of the history writes, fail with their `SqlError`.
+ */
+export function reconcileWorkflowUsers(ontology, input) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const [table] = yield* sql.unsafe(`SELECT to_regclass($1) IS NOT NULL AS "present"`, [`"${USER_TABLE}"`]);
+        if (table?.present !== true) {
+            return;
+        }
+        const rows = yield* sql.unsafe(`SELECT "id"::text AS "id", "identity_subject" AS "subject" FROM "${USER_TABLE}" ` +
+            `WHERE "identity_provider" = $1::text ORDER BY "id"`, [WORKFLOW_USER_PROVIDER]);
+        if (rows.length === 0 && ontology.workflows.length === 0) {
+            return;
+        }
+        const declared = new Map(ontology.workflows.map((candidate) => [
+            workflowSubject(input.workspaceId, candidate.name),
+            candidate,
+        ]));
+        const setActive = (id, active) => Effect.gen(function* () {
+            const runtime = platformRuntime(ontology, sql, active ? "user.reactivate_workflow_user" : "user.deactivate_workflow_user");
+            const user = yield* runtime.get({ entity: "user", id, forUpdate: true });
+            if (user.active !== active) {
+                yield* runtime.update({ entity: "user", id, values: { active } });
+            }
+        });
+        yield* sql.withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
+            // Users of other workspaces' subjects, or of removed workflows, may not act here.
+            for (const row of rows) {
+                if (row.subject === null || !declared.has(row.subject)) {
+                    yield* setActive(row.id, false);
+                }
+            }
+            for (const [subject, workflow] of declared) {
+                const user = yield* ensureWorkflowUser(ontology, sql, platformRuntime(ontology, sql, "user.reconcile_workflow_user"), { workflow, subject, mode: "reconcile" }).pipe(Effect.catchTag("PrincipalRejected", (error) => Effect.die(error)));
+                yield* setActive(user.id, true);
+            }
+        }));
+    }).pipe(Effect.catchTag(["Conflict", "NotFound", "ScopeViolated"], (error) => Effect.die(error)), 
+    // The runtime treats database failures as defects; deploy classifies them as failures.
+    Effect.catchDefect((defect) => (isSqlError(defect) ? Effect.fail(defect) : Effect.die(defect))));
+}
+/**
+ * The principal of an API key, with the permissions its roles have in the ontology. Unknown and
+ * revoked keys and inactive users are rejected.
+ */
+export function resolvePrincipalByApiKey(ontology, key) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const unknownKey = (diagnostic) => new PrincipalRejected({
+            reason: "unknown_api_key",
+            message: "The API key is not valid.",
+            diagnostic,
+        });
+        const parts = parseApiKey(key);
+        if (parts === undefined) {
+            return yield* unknownKey("malformed_api_key");
+        }
+        const [row] = yield* sql.unsafe(`SELECT "u"."id"::text AS "id", "u"."kind"::text AS "kind", "u"."active" AS "active", ` +
+            `"k"."salt" AS "salt", "k"."hash" AS "hash", "k"."revoked_at" IS NOT NULL AS "revoked" ` +
+            `FROM "${API_KEYS_TABLE}" AS "k" JOIN "${USER_TABLE}" AS "u" ON "u"."id" = "k"."user_id" ` +
+            `WHERE "k"."key_id" = $1::text`, [parts.keyId]);
+        // An unknown key id costs one KDF too, so that timing does not tell which key ids exist.
+        const stored = typeof row?.salt === "string" && typeof row.hash === "string"
+            ? { salt: row.salt, hash: row.hash }
+            : UNKNOWN_KEY;
+        const hash = yield* Effect.promise(() => hashApiKeySecret(parts.secret, stored.salt));
+        if (row === undefined) {
+            return yield* unknownKey("missing_api_key");
+        }
+        if (stored === UNKNOWN_KEY) {
+            return yield* unknownKey("invalid_api_key_record");
+        }
+        if (!sameHash(hash, stored.hash)) {
+            return yield* unknownKey("api_key_secret_mismatch");
+        }
+        if (row.revoked === true) {
+            return yield* new PrincipalRejected({
+                reason: "revoked_api_key",
+                message: "The API key was revoked.",
+            });
+        }
+        return yield* activePrincipal(ontology, sql, decodeUser({ id: row.id, kind: row.kind, active: row.active }));
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/**
+ * A member by user id, with the roles they hold now: whom an OAuth grant acts for. `undefined` for
+ * an unknown user, a service and an inactive member.
+ */
+export function resolveMemberById(ontology, userId) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const [row] = yield* sql.unsafe(`SELECT "id"::text AS "id", "kind"::text AS "kind", "active" AS "active" ` +
+            `FROM "${USER_TABLE}" WHERE "id" = $1::uuid`, [userId]);
+        if (row === undefined ||
+            row.kind !== "member" ||
+            row.active !== true ||
+            (yield* isMemberBlocked(sql, userId))) {
+            return undefined;
+        }
+        return yield* rolesOf(ontology, sql, decodeUser(row));
+    }).pipe(Effect.orDie);
+}
+/** Issues an API key for a user. */
+export function createApiKey(input) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const id = randomUUID();
+        const key = generateApiKey();
+        const { keyId, secret } = parseApiKey(key);
+        const salt = randomBytes(SALT_BYTES).toString("hex");
+        const hash = yield* Effect.promise(() => hashApiKeySecret(secret, salt));
+        yield* sql.unsafe(`INSERT INTO "${API_KEYS_TABLE}" ` +
+            `("id", "user_id", "key_id", "salt", "hash", "label", "created_at") ` +
+            "VALUES ($1::uuid, $2::uuid, $3::text, $4::text, $5::text, $6::text, now())", [id, input.userId, keyId, salt, hash, input.label]);
+        return { id, key };
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/** Revokes an API key. Revoking it again changes nothing. */
+export function revokeApiKey(input) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        if (!isRecordId(input.id)) {
+            return;
+        }
+        yield* sql.unsafe(`UPDATE "${API_KEYS_TABLE}" SET "revoked_at" = now() WHERE "id" = $1::uuid AND "revoked_at" IS NULL`, [input.id]);
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/** Replaces a user's roles inside the caller's transaction, failing on a role the ontology lacks. */
+function writeUserRoles(ontology, sql, input) {
+    return Effect.gen(function* () {
+        const known = new Set(ontology.roles.map((candidate) => candidate.name));
+        const unknown = input.roles.find((role) => toSnakeCase(role) === FEEDBACK_REPORTER_ROLE || !known.has(role));
+        if (unknown !== undefined) {
+            return yield* new UnknownRole({
+                role: unknown,
+                message: `${unknown} is not a role of this ontology.`,
+            });
+        }
+        const roles = [...new Set(input.roles)];
+        yield* sql.unsafe(`DELETE FROM "${USER_ROLES_TABLE}" WHERE "user_id" = $1::uuid`, [
+            input.userId,
+        ]);
+        for (const role of roles) {
+            yield* sql.unsafe(`INSERT INTO "${USER_ROLES_TABLE}" ("user_id", "role") VALUES ($1::uuid, $2::text)`, [input.userId, role]);
+        }
+    });
+}
+/** Replaces the roles a user was given. Members hold `member` whatever is assigned. */
+export function setUserRoles(ontology, input) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        yield* sql.withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
+            yield* writeUserRoles(ontology, sql, input);
+        }));
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/**
+ * Creates a service user with roles and a first API key, as the app or the CLI does for the
+ * website's intake key.
+ */
+export function createServiceUser(ontology, input) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const runtime = platformRuntime(ontology, sql, "user.create_service");
+        return yield* sql.withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
+            const user = yield* runtime
+                .create({ entity: "user", values: { name: input.name, kind: "service" } })
+                .pipe(Effect.orDie);
+            yield* setUserRoles(ontology, { userId: user.id, roles: input.roles });
+            const apiKey = yield* createApiKey({ userId: user.id, label: input.keyLabel });
+            return { user, apiKey };
+        }));
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/**
+ * The built-in `User` as the deployed table has it: only the properties the manifest lists, and
+ * @legacy ontology.pre-upgrade-database-tolerance
+ * `roles`, which has no column. A manifest an earlier SDK built lacks the properties added since,
+ * such as `lastSignInAt`, and its table has no column for them until the workspace is deployed with
+ * this SDK.
+ */
+function deployedUser(manifest) {
+    const deployed = manifest.entities?.find((candidate) => candidate.builtIn);
+    if (deployed === undefined) {
+        return User;
+    }
+    const names = new Set(deployed.properties.map((property) => property.name));
+    // A list has no column: the deployed table serves it whatever the manifest lists.
+    const kept = Object.entries(User.definition.properties).filter(([name, property]) => propertyDefinition(property)?.type === "list" ||
+        names.has(toSnakeCase(name)) ||
+        (propertyDefinition(property)?.renamedFrom !== undefined &&
+            names.has(propertyDefinition(property).renamedFrom)));
+    if (kept.length === Object.keys(User.definition.properties).length) {
+        return User;
+    }
+    const definition = {
+        ...User.definition,
+        properties: Object.fromEntries(kept),
+    };
+    return entity(User.name, definition);
+}
+/**
+ * An ontology with only the built-in `User` and the manifest's roles, with their permissions: what
+ * managing principals needs. The platform holds a deployed ontology's manifest, not its code, and
+ * users, roles and API keys live in tables the ontology's own entities do not shape. The roles'
+ * permissions name entities this ontology does not have; they were checked when the manifest was
+ * built, so they are not checked again, and neither are its workflows, which it carries for their
+ * users. The user keeps only the properties the deployed table has.
+ */
+export function principalsOntology(manifest) {
+    const builtIn = manifest.roles.find((candidate) => candidate.builtIn && candidate.name === MEMBER_ROLE);
+    const ontology = buildOntology({
+        entities: [],
+        // Managing an old deployment must not apply new SDK defaults retroactively.
+        feedback: false,
+        roles: manifest.roles
+            .filter((candidate) => !candidate.builtIn)
+            .map((candidate) => role(candidate.name, {
+            description: candidate.description,
+            permissions: roleEntries(candidate.permissions ?? [], candidate.scopes ?? []),
+        })),
+        ...(builtIn?.permissions === undefined
+            ? {}
+            : { member: { permissions: roleEntries(builtIn.permissions, builtIn.scopes ?? []) } }),
+    }, { checkPermissions: false, user: deployedUser(manifest) });
+    // The workflows' roles were checked with the manifest; it carries them for their users.
+    const roles = 
+    // @legacy ontology.feedback-unset-manifests
+    manifest.feedback?.enabled === true
+        ? feedbackRoles({ builders: [] }, manifest.feedback.files, ontology.roles, () => { }).roles
+        : ontology.roles;
+    return {
+        ...ontology,
+        roles,
+        manifest: buildManifest({
+            ...ontology,
+            roles,
+            ...(manifest.feedback === undefined ? {} : { feedback: manifest.feedback }),
+        }),
+        workflows: manifest.workflows ?? [],
+    };
+}
+const ApiKeyRow = Schema.Struct({
+    id: Schema.String,
+    key_id: Schema.String,
+    label: Schema.String,
+    created_at: Schema.String,
+    revoked_at: Schema.NullOr(Schema.String),
+    user_id: Schema.String,
+    user_name: Schema.String,
+    user_active: Schema.Boolean,
+    roles: Schema.Array(Schema.String),
+});
+const decodeApiKeyRow = Schema.decodeUnknownSync(ApiKeyRow);
+function apiKeySummary(raw) {
+    const row = decodeApiKeyRow(raw);
+    return {
+        id: row.id,
+        keyId: row.key_id,
+        label: row.label,
+        createdAt: row.created_at,
+        revokedAt: row.revoked_at ?? undefined,
+        user: { id: row.user_id, name: row.user_name, active: row.user_active },
+        roles: row.roles.filter((assigned) => toSnakeCase(assigned) !== FEEDBACK_REPORTER_ROLE),
+    };
+}
+/** The roles assigned to the user `"u"`, sorted, as one text array. */
+const ROLES_OF_USER = `COALESCE((SELECT array_agg("r"."role" ORDER BY "r"."role") FROM "${USER_ROLES_TABLE}" AS "r" ` +
+    `WHERE "r"."user_id" = "u"."id"), ARRAY[]::text[]) AS "roles"`;
+/** Timestamps and arrays arrive as text so that every driver and database reads the same. */
+const API_KEY_COLUMNS = `"k"."id"::text AS "id", "k"."key_id" AS "key_id", "k"."label" AS "label", ` +
+    `to_char("k"."created_at" AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS "created_at", ` +
+    `to_char("k"."revoked_at" AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS "revoked_at", ` +
+    `"u"."id"::text AS "user_id", "u"."name" AS "user_name", "u"."active" AS "user_active", ` +
+    ROLES_OF_USER;
+const API_KEY_FROM = `FROM "${API_KEYS_TABLE}" AS "k" JOIN "${USER_TABLE}" AS "u" ON "u"."id" = "k"."user_id"`;
+/** Every API key, oldest first, revoked ones included. */
+export function listApiKeys() {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const rows = yield* sql.unsafe(`SELECT ${API_KEY_COLUMNS} ${API_KEY_FROM} ORDER BY "k"."created_at", "k"."id"`);
+        return rows.map(apiKeySummary);
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/** One API key by its id, or undefined. */
+export function findApiKey(input) {
+    return Effect.gen(function* () {
+        if (!isRecordId(input.id)) {
+            return undefined;
+        }
+        const sql = yield* SqlClient.SqlClient;
+        const [row] = yield* sql.unsafe(`SELECT ${API_KEY_COLUMNS} ${API_KEY_FROM} WHERE "k"."id" = $1::uuid`, [input.id]);
+        return row === undefined ? undefined : apiKeySummary(row);
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+const MemberRow = Schema.Struct({
+    id: Schema.String,
+    email: Schema.NullOr(Schema.String),
+    name: Schema.String,
+    active: Schema.Boolean,
+    signed_in: Schema.Boolean,
+    blocked: Schema.optionalKey(Schema.Boolean),
+    identities: Schema.optionalKey(Schema.Array(Schema.Struct({
+        provider: Schema.String,
+        subject: Schema.String,
+        username: Schema.NullOr(Schema.String),
+    }))),
+    roles: Schema.Array(Schema.String),
+    last_sign_in_at: Schema.NullOr(Schema.String),
+});
+const decodeMemberRow = Schema.decodeUnknownSync(MemberRow);
+function memberStatus(row) {
+    if (row.blocked) {
+        return "inactive";
+    }
+    if (!row.active) {
+        return "inactive";
+    }
+    return row.signed_in ? "active" : "invited";
+}
+function memberSummary(raw) {
+    const row = decodeMemberRow(raw);
+    return {
+        id: row.id,
+        email: row.email ?? undefined,
+        name: row.name,
+        active: row.active && !row.blocked,
+        ...(row.blocked ? { blocked: true } : {}),
+        ...(row.identities?.length
+            ? {
+                identities: row.identities.map(({ provider, subject, username }) => ({
+                    provider,
+                    subject,
+                    ...(username === null ? {} : { username }),
+                })),
+            }
+            : {}),
+        status: memberStatus(row),
+        roles: row.roles.filter((assigned) => assigned !== MEMBER_ROLE && toSnakeCase(assigned) !== FEEDBACK_REPORTER_ROLE),
+        lastSignInAt: row.last_sign_in_at ?? undefined,
+    };
+}
+/**
+ * `last_sign_in_at` is read through the row's JSON rather than as a column: the platform lists the
+ * @legacy ontology.pre-upgrade-database-tolerance
+ * members of workspaces deployed with an earlier SDK too, whose `user` table has no such column
+ * until their next deploy, and those members then have no last sign-in instead of failing the list.
+ */
+const LAST_SIGN_IN_AT = `to_char((to_jsonb("u") ->> 'last_sign_in_at')::timestamptz AT TIME ZONE 'UTC', ` +
+    `'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS "last_sign_in_at"`;
+/**
+ * Platform reads also serve databases deployed before channel identities existed, and before
+ * `user_identity` did: those read the legacy stores.
+ */
+function memberColumns(sql) {
+    return Effect.gen(function* () {
+        const [tables] = yield* sql.unsafe(`SELECT to_regclass($1) IS NOT NULL AS "identities"`, [AGENT_IDENTITIES_TABLE]);
+        const recorded = yield* userIdentitiesAvailable(sql);
+        // Revocation removes channel access, but the member has still joined and is no longer invited.
+        const channelMember = tables?.identities
+            ? ` OR EXISTS (SELECT 1 FROM "${AGENT_IDENTITIES_TABLE}" AS "i" WHERE "i"."user_id" = "u"."id")`
+            : "";
+        const signedIn = recorded
+            ? `EXISTS (SELECT 1 FROM "${USER_IDENTITY_TABLE}" AS "i" WHERE "i"."user_id" = "u"."id")`
+            : `("u"."identity_subject" IS NOT NULL${channelMember})`;
+        // The member's live channel accounts; sign-in identities are not listed here.
+        const identities = recorded
+            ? `COALESCE((
+          SELECT jsonb_agg(
+            jsonb_build_object('provider', i."provider", 'subject', i."subject",
+              'username', i."username") ORDER BY i."provider", i."subject"
+          )
+          FROM ${tables?.identities ? CHANNEL_IDENTITIES_FROM : `"${USER_IDENTITY_TABLE}" AS "i"`}
+          WHERE i."user_id" = u."id"
+            AND ${tables?.identities ? LIVE_CHANNEL_IDENTITY : LIVE_CHANNEL_RECORD}
+        ), '[]'::jsonb)`
+            : tables?.identities
+                ? `COALESCE((
+          SELECT jsonb_agg(
+            jsonb_build_object(
+              'provider', i."provider",
+              'subject', i."external_id",
+              'username', to_jsonb(i)->>'username'
+            ) ORDER BY i."provider", i."external_id"
+          )
+          FROM "${AGENT_IDENTITIES_TABLE}" i
+          WHERE i."user_id" = u."id" AND i."revoked_at" IS NULL
+        ), '[]'::jsonb)`
+                : "'[]'::jsonb";
+        const blocked = (yield* channelUsersAvailable(sql))
+            ? `EXISTS (SELECT 1 FROM "${CHANNEL_USERS_TABLE}" c WHERE c."user_id" = u."id" AND c."blocked_at" IS NOT NULL)`
+            : "false";
+        return (`${blocked} AS "blocked", ${identities} AS "identities", ` +
+            `"u"."id"::text AS "id", "u"."email" AS "email", "u"."name" AS "name", ` +
+            `"u"."active" AS "active", ` +
+            `${signedIn} AS "signed_in", ${ROLES_OF_USER}, ` +
+            LAST_SIGN_IN_AT);
+    });
+}
+const MEMBER_FROM = `FROM "${USER_TABLE}" AS "u" WHERE "u"."kind" = 'member'`;
+/** Every member, signed in or not, by email. */
+export function listMembers() {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const columns = yield* memberColumns(sql);
+        const rows = yield* sql.unsafe(`SELECT ${columns} ${MEMBER_FROM} ORDER BY "u"."email" NULLS LAST, "u"."id"`);
+        return rows.map(memberSummary);
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/** Emails are stored lowercased, as sign-in links them. */
+function normalizeEmail(email) {
+    return email.trim().toLowerCase();
+}
+const SignInRow = Schema.Struct({
+    id: Schema.String,
+    active: Schema.Boolean,
+    neon_auth: Schema.Boolean,
+});
+const decodeSignInRow = Schema.decodeUnknownSync(SignInRow);
+/**
+ * Whether a person may sign in with this address, and how; it reads and changes nothing else.
+ * Under `invited`, an active member who signed in with Neon Auth before gets `code`, an active
+ * member who has not gets `link`, and anyone else is not allowed: a deactivated member is answered
+ * like an unknown address. Under `open`, unblocked addresses get `link`.
+ */
+export function checkSignIn(ontology, email) {
+    return Effect.gen(function* () {
+        const address = normalizeEmail(email);
+        if (!EMAIL_PATTERN.test(address)) {
+            return { allowed: false };
+        }
+        const sql = yield* SqlClient.SqlClient;
+        // Neon Auth accounts receive sign-in codes: the member's live email sign-in identity.
+        const neonAuth = (yield* userIdentitiesAvailable(sql))
+            ? `EXISTS (SELECT 1 FROM "${USER_IDENTITY_TABLE}" AS "i" WHERE "i"."user_id" = "u"."id" ` +
+                `AND "i"."provider" = $2 AND "i"."origin"::text IN ${SIGN_IN_ORIGIN_SQL} ` +
+                `AND "i"."revoked_at" IS NULL)`
+            : `("u"."identity_provider" = $2 AND "u"."identity_subject" IS NOT NULL)`;
+        const [row] = yield* sql.unsafe(`SELECT "u"."id"::text AS "id", "u"."active" AS "active", ${neonAuth} AS "neon_auth" ` +
+            `FROM "${USER_TABLE}" AS "u" WHERE "u"."kind" = 'member' AND "u"."email" = $1 LIMIT 1`, [address, NEON_AUTH_PROVIDER]);
+        if (row === undefined) {
+            return ontology.signIn.policy === "open"
+                ? { allowed: true, method: "link" }
+                : { allowed: false };
+        }
+        const member = decodeSignInRow(row);
+        if (yield* isMemberBlocked(sql, member.id)) {
+            return { allowed: false };
+        }
+        if (ontology.signIn.policy === "open") {
+            return { allowed: true, method: "link" };
+        }
+        if (!member.active) {
+            return { allowed: false };
+        }
+        return { allowed: true, method: member.neon_auth ? "code" : "link" };
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+function memberNotFound(key) {
+    const described = "id" in key ? `the id ${key.id}` : `the email ${normalizeEmail(key.email)}`;
+    return new MemberNotFound({ message: `No member has ${described}.` });
+}
+/** The user with this id or email, locked until the transaction ends, members and services alike. */
+function lockUser(runtime, key) {
+    if ("id" in key) {
+        if (!isRecordId(key.id)) {
+            return Effect.succeed(undefined);
+        }
+        return runtime
+            .get({ entity: "user", id: key.id, forUpdate: true })
+            .pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)));
+    }
+    return runtime
+        .find({
+        entity: "user",
+        options: { where: { email: normalizeEmail(key.email) }, limit: 1, forUpdate: true },
+    })
+        .pipe(Effect.map(([user]) => user));
+}
+function readMember(sql, id) {
+    return Effect.gen(function* () {
+        const columns = yield* memberColumns(sql);
+        const [row] = yield* sql.unsafe(`SELECT ${columns} ${MEMBER_FROM} AND "u"."id" = $1::uuid`, [
+            id,
+        ]);
+        if (row === undefined) {
+            return yield* Effect.die(new Error(`Member ${id} was written but cannot be read back.`));
+        }
+        return memberSummary(row);
+    });
+}
+/**
+ * Adds and removes a member's roles in one transaction. Creates a member only for an unknown email
+ * when `grant` is given. Granting a role the member holds, or revoking one they do not, changes
+ * nothing. A member created here is linked to their identity by email on first sign-in. The writes
+ * are the `user` actions' own, as platform writes: history names `user.invite`,
+ * `user.revoke_roles` and `user.grant_roles`, without a principal.
+ */
+export function updateMemberRoles(ontology, change) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const key = "id" in change ? { id: change.id } : { email: normalizeEmail(change.email) };
+        const grant = change.grant === undefined ? undefined : [...new Set(change.grant)];
+        const revoke = change.revoke === "all" ? "all" : [...new Set(change.revoke ?? [])];
+        const declared = ontology.roles.map((candidate) => candidate.name);
+        // Refused before anything is read, whoever the member is.
+        yield* requireGrantable(declared, grant ?? []);
+        yield* refuseMember(revoke === "all" ? [] : revoke);
+        // One call is one platform write: its rows share an action id, each under its own action.
+        const actionId = randomUUID();
+        const runtime = (action) => platformRuntime(ontology, sql, action, actionId);
+        const attempt = sql.withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
+            const found = yield* lockUser(runtime(MEMBER_HISTORY_ACTIONS.invite), key);
+            if (found !== undefined && found.kind !== "member") {
+                return yield* new MemberNotFound({
+                    message: `${"id" in key ? key.id : key.email} belongs to a service, not a member.`,
+                });
+            }
+            // Only the email path creates invitations; an unknown id must never create a user.
+            if (found === undefined) {
+                if ("id" in key || grant === undefined) {
+                    return yield* memberNotFound(key);
+                }
+                const invited = yield* runtime(MEMBER_HISTORY_ACTIONS.invite).members.invite({
+                    email: key.email,
+                    name: change.name,
+                    roles: grant,
+                });
+                return yield* readMember(sql, invited.id);
+            }
+            const userId = found.id;
+            const granted = grant ?? [];
+            // A role in both lists stays assigned: it is not revoked, so it is not granted anew.
+            const held = revoke === "all" ? yield* assignedRoles(sql, userId) : revoke;
+            yield* runtime(MEMBER_HISTORY_ACTIONS.revokeRoles).members.revokeRoles({
+                id: userId,
+                roles: held.filter((role) => !granted.includes(role)),
+            });
+            yield* runtime(MEMBER_HISTORY_ACTIONS.grantRoles).members.grantRoles({
+                id: userId,
+                roles: granted,
+            });
+            return yield* readMember(sql, userId);
+        }));
+        // Two first grants to one email race to create the member; the loser finds it on retry.
+        return yield* attempt.pipe(Effect.catchTag("Conflict", () => attempt), Effect.catchTag(["Conflict", "NotFound"], (error) => Effect.die(error)));
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/**
+ * Grants roles of the ontology to the member with this email, creating the member when no user has
+ * it; their name defaults to the email. Granting a role they hold changes nothing.
+ */
+export function grantMemberRoles(ontology, input) {
+    return updateMemberRoles(ontology, { email: input.email, name: input.name, grant: input.roles });
+}
+/**
+ * Removes roles from the member with this email, or every assigned role. The member stays, so
+ * history keeps their name. Roles the ontology no longer declares can be removed too.
+ */
+export function revokeMemberRoles(ontology, input) {
+    return updateMemberRoles(ontology, { email: input.email, revoke: input.roles });
+}
+/**
+ * Deactivates or reactivates a member, as `user.deactivate` and `user.reactivate` do, as a platform
+ * write. An inactive member keeps their roles and history, and the service rejects their requests.
+ * Deactivation also revokes sessions, including repeated requests.
+ */
+export function setMemberActive(ontology, input) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const action = input.active
+            ? MEMBER_HISTORY_ACTIONS.reactivate
+            : MEMBER_HISTORY_ACTIONS.deactivate;
+        const runtime = platformRuntime(ontology, sql, action);
+        return yield* sql.withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
+            const user = yield* lockUser(runtime, input);
+            if (user === undefined || user.kind !== "member") {
+                return yield* memberNotFound(input);
+            }
+            const id = user.id;
+            yield* runtime.members.setActive({ id, active: input.active });
+            return yield* readMember(sql, id);
+        }));
+    }).pipe(Effect.catchTag("NotFound", (error) => Effect.die(error)), Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+export function isMemberBlocked(sql, userId) {
+    return Effect.gen(function* () {
+        if (!(yield* channelUsersAvailable(sql))) {
+            return false;
+        }
+        const [blocked] = yield* sql.unsafe(`SELECT 1 FROM "${CHANNEL_USERS_TABLE}" WHERE "user_id" = $1::uuid AND "blocked_at" IS NOT NULL`, [userId]);
+        return blocked !== undefined;
+    });
+}
+/** Must run in the issuance transaction; the shared User lock serializes insertion with revocation. */
+export function lockSessionMember(sql, userId) {
+    return Effect.gen(function* () {
+        const [user] = yield* sql.unsafe(`SELECT "kind"::text AS "kind", "active" FROM "${USER_TABLE}"
+       WHERE "id" = $1::uuid FOR SHARE`, [userId]);
+        if (user?.kind !== "member" || !user.active || (yield* isMemberBlocked(sql, userId))) {
+            return yield* Effect.die(new PrincipalRejected({ reason: "inactive_user", message: "inactive_user" }));
+        }
+    });
+}
+/** Sticky blocking is independent of activation and survives unpairing or another identity. */
+export function setMemberBlocked(ontology, input) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const runtime = platformRuntime(ontology, sql, input.blocked ? "user.block" : "user.unblock");
+        return yield* sql.withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
+            const user = yield* lockUser(runtime, { id: input.id });
+            if (user === undefined || user.kind !== "member") {
+                return yield* memberNotFound({ id: input.id });
+            }
+            // A member who never signed in by email or SegmentStream was invited.
+            const signedIn = (yield* userIdentitiesAvailable(sql))
+                ? (yield* liveSignInIdentities(sql, input.id)).length > 0
+                : user.identity_subject !== null;
+            yield* sql.unsafe(`INSERT INTO "${CHANNEL_USERS_TABLE}" ("user_id", "created_via", "blocked_at")
+         VALUES ($1::uuid, $2, CASE WHEN $3 THEN now() ELSE NULL END)
+         ON CONFLICT ("user_id") DO UPDATE SET "blocked_at" = EXCLUDED."blocked_at"`, [input.id, signedIn ? "email" : "invite", input.blocked]);
+            if (input.blocked) {
+                yield* revokeMemberSessions(sql, input.id);
+            }
+            return yield* readMember(sql, input.id);
+        }));
+    }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+}
+/** Active admitted OIDC members who would lose browser access if email were their only method. */
+export function countUsersWithoutEmailIdentity() {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const [table] = yield* sql.unsafe(`SELECT to_regclass('_user_identities') IS NOT NULL AS present,
+       to_regclass('"user"') IS NOT NULL AS "usersPresent"`);
+        if (!table?.usersPresent) {
+            return 0;
+        }
+        if (yield* userIdentitiesAvailable(sql)) {
+            const [row] = yield* sql.unsafe(`SELECT count(*)::int AS count FROM "user" u WHERE u.kind = 'member' AND u.active = true
+          AND ${liveIdentitySql(OIDC_PROVIDER)} AND NOT ${liveIdentitySql(NEON_AUTH_PROVIDER)}`);
+            return row?.count ?? 0;
+        }
+        if (!table.present) {
+            return 0;
+        }
+        const [row] = yield* sql.unsafe(`SELECT count(*)::int AS count FROM "user" u
+      WHERE u.kind = 'member' AND u.active = true
+        AND EXISTS (SELECT 1 FROM "_user_identities" i WHERE i.user_id = u.id)
+        AND (u.identity_provider IS DISTINCT FROM 'neon-auth' OR u.identity_subject IS NULL)`);
+        return row?.count ?? 0;
+    });
+}
+/** The member `u` holds a live sign-in identity of the provider, `$1` its issuer when given. */
+function liveIdentitySql(provider, issuer) {
+    return (`EXISTS (SELECT 1 FROM "${USER_IDENTITY_TABLE}" i WHERE i.user_id = u.id ` +
+        `AND i.provider = '${provider}' AND i.origin::text IN ${SIGN_IN_ORIGIN_SQL} ` +
+        `AND i.revoked_at IS NULL${issuer === undefined ? "" : ` AND i.issuer = ${issuer}`})`);
+}
+/** Established email members who would lose access if SegmentStream became their only method. */
+export function countUsersWithoutSegmentStreamIdentity(issuer) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const [table] = yield* sql.unsafe(`SELECT to_regclass('_user_identities') IS NOT NULL AS present,
+       to_regclass('"user"') IS NOT NULL AS "usersPresent"`);
+        if (!table?.usersPresent) {
+            return 0;
+        }
+        if (yield* userIdentitiesAvailable(sql)) {
+            const [row] = yield* sql.unsafe(`SELECT count(*)::int AS count FROM "user" u WHERE u.kind = 'member' AND u.active = true
+         AND ${liveIdentitySql(NEON_AUTH_PROVIDER)}
+         AND NOT ${liveIdentitySql(OIDC_PROVIDER, issuer === undefined ? undefined : "$1")}`, issuer === undefined ? [] : [issuer]);
+            return row?.count ?? 0;
+        }
+        const missing = table.present
+            ? `AND NOT EXISTS (SELECT 1 FROM "_user_identities" i
+        WHERE i.user_id = u.id ${issuer === undefined ? "" : "AND i.issuer = $1"})`
+            : "";
+        const [row] = yield* sql.unsafe(`SELECT count(*)::int AS count FROM "user" u WHERE u.kind = 'member' AND u.active = true
+       AND u.identity_provider = 'neon-auth' AND u.identity_subject IS NOT NULL ${missing}`, table?.present && issuer !== undefined ? [issuer] : []);
+        return row?.count ?? 0;
+    });
+}