@rehearsal-db/core 0.1.0-beta.14 → 0.1.0-beta.16

package/dist/src/identity/claim_contract.d.mts

@@ -0,0 +1,135 @@
+/** Typed contract shared by identity policy, planning, and execution stages. */
+export declare const SUPPORTED_IDENTITY_PROVIDERS: readonly ["email", "github", "google"];
+export type JsonObject = Record<string, unknown>;
+export type IdentityProvider = (typeof SUPPORTED_IDENTITY_PROVIDERS)[number];
+export type SubjectIdentityProvider = Exclude<IdentityProvider, "email">;
+export type IdentityStrategy = "transfer" | "preserve-audit";
+export type PathValueType = "text" | "jsonb";
+export interface Relation {
+    readonly schema: string;
+    readonly table: string;
+}
+export interface PatternDefaultMatcher {
+    readonly kind: "pattern";
+    readonly pattern: string;
+}
+export interface ExactDefaultMatcher {
+    readonly kind: "exact";
+    readonly value: unknown;
+}
+export type SignupDefaultMatcher = PatternDefaultMatcher | ExactDefaultMatcher;
+export interface VerifiedEmailMatcher {
+    readonly type: "verified-email";
+    readonly providers: readonly IdentityProvider[];
+    readonly emailEnvironmentVariable: string;
+    readonly approvedEmailSha256: string;
+}
+export interface ProviderSubjectMatcher {
+    readonly type: "provider-subject";
+    readonly provider: SubjectIdentityProvider;
+    readonly subjectEnvironmentVariable: string;
+    readonly approvedSubjectSha256: string;
+}
+export type IdentityMatcher = VerifiedEmailMatcher | ProviderSubjectMatcher;
+export interface IdentityReference extends Relation {
+    readonly column: string;
+    readonly required: boolean;
+    readonly strategy: IdentityStrategy;
+}
+export interface JsonIdentityReference extends Relation {
+    readonly column: string;
+    readonly path: readonly string[];
+}
+export interface SignupDefaultDeclaration {
+    readonly table: Relation;
+    readonly identityColumn: string;
+    readonly ignoredColumns: readonly string[];
+    readonly values: Readonly<Record<string, SignupDefaultMatcher>>;
+}
+export interface PathIdentityReference extends Relation {
+    readonly column: string;
+    readonly valueType: PathValueType;
+}
+export interface IdentityAsset {
+    readonly bucket: string;
+    readonly prefix: string;
+    readonly rewritePath: boolean;
+}
+export interface IdentityTokenHook {
+    readonly function: Readonly<{
+        schema: string;
+        name: string;
+    }>;
+    readonly expectedClaims: JsonObject;
+}
+export interface IdentityDeclaration {
+    readonly name: string;
+    readonly matcher: IdentityMatcher;
+    readonly placeholderUserId: string;
+    readonly references: readonly IdentityReference[];
+    readonly jsonReferences: readonly JsonIdentityReference[];
+    readonly signupDefaults: readonly SignupDefaultDeclaration[];
+    readonly pathReferences: readonly PathIdentityReference[];
+    readonly assets: readonly IdentityAsset[];
+    readonly claims: JsonObject;
+    readonly tokenHook: IdentityTokenHook | null;
+}
+export interface IdentityPolicy {
+    readonly identityVersion: 1;
+    readonly identities: readonly IdentityDeclaration[];
+}
+export interface IdentityClaimReview {
+    readonly planVersion: 3;
+    readonly operation: "claim-local-identity";
+    readonly name: string;
+    readonly matcher: IdentityMatcher;
+    readonly placeholderUserId: string;
+    readonly references: readonly IdentityReference[];
+    readonly jsonReferences: readonly JsonIdentityReference[];
+    readonly signupDefaults: readonly Readonly<{
+        table: Relation;
+        identityColumn: string;
+        ignoredColumns: readonly string[];
+        valuesSha256: string;
+    }>[];
+    readonly pathReferences: readonly PathIdentityReference[];
+    readonly assets: readonly IdentityAsset[];
+    readonly claimKeys: readonly string[];
+    readonly claimsSha256: string;
+    readonly tokenHook: Readonly<{
+        function: Readonly<{
+            schema: string;
+            name: string;
+        }>;
+        expectedClaimsSha256: string;
+    }> | null;
+}
+export interface IdentityClaimPlan {
+    readonly identity: IdentityDeclaration;
+    readonly review: Readonly<IdentityClaimReview>;
+    readonly digest: string;
+}
+export interface QueryResult<Row extends JsonObject = JsonObject> {
+    readonly rows: Row[];
+}
+export interface IdentityDatabaseClient {
+    connect?(): Promise<void>;
+    end?(): Promise<void>;
+    query<Row extends JsonObject = JsonObject>(sql: string, parameters?: readonly unknown[]): Promise<QueryResult<Row>>;
+}
+export type IdentityClientFactory = (connectionString: string) => IdentityDatabaseClient | Promise<IdentityDatabaseClient>;
+export interface StorageCopy {
+    readonly bucket: string;
+    readonly source: string;
+    readonly destination: string;
+}
+export interface IdentityClaimResult {
+    readonly name: string;
+    readonly provider: IdentityProvider;
+    readonly claimed: true;
+    readonly removedSignupDefaults: number;
+    readonly tokenHookVerified: boolean;
+    readonly placeholderRetainedForAudit: boolean;
+    readonly storageObjectsTransferred: number;
+    readonly idempotent: boolean;
+}

package/dist/src/identity/claim_contract.mjs

@@ -0,0 +1,6 @@
+/** Typed contract shared by identity policy, planning, and execution stages. */
+export const SUPPORTED_IDENTITY_PROVIDERS = Object.freeze([
+    "email",
+    "github",
+    "google",
+]);

package/dist/src/identity/claim_executor.d.mts

@@ -0,0 +1,10 @@
+/** Execute and verify one confirmed local identity claim transaction. */
+import type { IdentityClaimPlan, IdentityClaimResult, IdentityClientFactory } from "./claim_contract.mjs";
+import type { SupabaseStorageTransfer } from "./storage.mjs";
+export declare const applyIdentityClaim: ({ plan, confirmation, connectionString, clientFactory, storageTransfer, }: {
+    plan: IdentityClaimPlan;
+    confirmation: string;
+    connectionString: string;
+    clientFactory?: IdentityClientFactory;
+    storageTransfer?: SupabaseStorageTransfer;
+}) => Promise<IdentityClaimResult>;

package/dist/src/identity/claim_executor.mjs

@@ -0,0 +1,358 @@
+/** Execute and verify one confirmed local identity claim transaction. */
+import pg from "pg";
+import { IDENTITY_CLAIM_RECEIPT_SQL } from "../runtime/policy.mjs";
+import { countIdentityRows, discoverPublicAuthReferences, findVerifiedLocalIdentity, } from "./claim_identity_lookup.mjs";
+import { getIdentityPlanMatchValue } from "./claim_plan.mjs";
+import { planJsonReferenceTransfer, planPathReferenceCount, planPathReferenceTransfer, planRelationalReferenceTransfer, planRequiredReferenceCheck, planSignupDefaultInspection, planSignupDefaultRemoval, } from "./claim_sql.mjs";
+import { containsJson, inspectDeclaredDefault, valueKind, } from "./claim_verification.mjs";
+const { Client } = pg;
+const IDENTIFIER = /^[a-z][a-z0-9_]{0,62}$/u;
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/iu;
+const groupStorageCopies = (copies) => {
+    const grouped = new Map();
+    for (const copy of copies) {
+        const bucketCopies = grouped.get(copy.bucket);
+        if (bucketCopies)
+            bucketCopies.push(copy);
+        else
+            grouped.set(copy.bucket, [copy]);
+    }
+    return grouped;
+};
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const id = (value, label) => {
+    if (typeof value !== "string" || !IDENTIFIER.test(value))
+        throw new Error(`${label} is not a safe identifier.`);
+    return value;
+};
+const qid = (value) => `"${id(value, "SQL identifier")}"`;
+export const applyIdentityClaim = async ({ plan, confirmation, connectionString, clientFactory, storageTransfer, }) => {
+    if (confirmation !== plan.digest) {
+        throw new Error(`Identity claim confirmation does not match. Expected ${plan.digest}.`);
+    }
+    const matchValue = getIdentityPlanMatchValue(plan);
+    if (!matchValue) {
+        throw new Error("Identity claim plans must be created from the reviewed local matcher environment.");
+    }
+    const target = new URL(connectionString);
+    if (!["127.0.0.1", "::1", "localhost"].includes(target.hostname)) {
+        throw new Error("Identity claims may target only the local Rehearsal database.");
+    }
+    const client = clientFactory
+        ? await clientFactory(connectionString)
+        : new Client({
+            connectionString,
+            application_name: "rehearsal-identity-claim",
+        });
+    await client.connect?.();
+    let removedSignupDefaults = 0;
+    let tokenHookVerified = false;
+    let placeholderRetainedForAudit = false;
+    const stagedStorageCopies = [];
+    let committed = false;
+    let storageObjectsTransferred = 0;
+    try {
+        await client.query("begin");
+        const localIdentity = await findVerifiedLocalIdentity({
+            client,
+            plan,
+            matchValue,
+        });
+        const localUserId = localIdentity.id;
+        if (!UUID.test(localUserId))
+            throw new Error("Matched local identity is invalid.");
+        const placeholderUser = await client.query("select 1 from auth.users where id = $1::uuid limit 1", [plan.identity.placeholderUserId]);
+        const placeholderReferenceCounts = [];
+        if (localUserId !== plan.identity.placeholderUserId) {
+            for (const reference of plan.identity.references) {
+                placeholderReferenceCounts.push(await countIdentityRows({
+                    client,
+                    reference,
+                    userId: plan.identity.placeholderUserId,
+                }));
+            }
+        }
+        const transferReferences = plan.identity.references.filter((reference) => reference.strategy === "transfer");
+        const preservedReferences = plan.identity.references.filter((reference) => reference.strategy === "preserve-audit");
+        const transferPlaceholderCounts = transferReferences.map((reference) => {
+            const index = plan.identity.references.indexOf(reference);
+            return placeholderReferenceCounts[index] ?? 0;
+        });
+        const transferLocalCounts = [];
+        if (localUserId !== plan.identity.placeholderUserId &&
+            preservedReferences.length > 0) {
+            for (const reference of transferReferences) {
+                transferLocalCounts.push(await countIdentityRows({ client, reference, userId: localUserId }));
+            }
+        }
+        const alreadyClaimed = localUserId !== plan.identity.placeholderUserId &&
+            transferPlaceholderCounts.every((count) => count === 0) &&
+            (preservedReferences.length > 0
+                ? transferLocalCounts.some((count) => count > 0)
+                : placeholderUser.rows.length === 0);
+        const publicAuthReferences = localUserId === plan.identity.placeholderUserId
+            ? []
+            : await discoverPublicAuthReferences(client);
+        if (localUserId !== plan.identity.placeholderUserId) {
+            const placeholderIdentity = await client.query("select 1 from auth.identities where user_id = $1::uuid limit 1", [plan.identity.placeholderUserId]);
+            if (placeholderIdentity.rows.length > 0) {
+                throw new Error("The copied placeholder already belongs to a conflicting local identity.");
+            }
+        }
+        for (const reference of alreadyClaimed ? [] : publicAuthReferences) {
+            const declared = plan.identity.references.find((candidate) => candidate.schema === reference.schema &&
+                candidate.table === reference.table &&
+                candidate.column === reference.column);
+            if (declared?.strategy === "preserve-audit")
+                continue;
+            const localRows = await countIdentityRows({
+                client,
+                reference,
+                userId: localUserId,
+            });
+            if (localRows === 0)
+                continue;
+            const declaredDefault = plan.identity.signupDefaults.find((declaration) => declaration.table.schema === reference.schema &&
+                declaration.table.table === reference.table &&
+                declaration.identityColumn === reference.column);
+            if (!declaredDefault) {
+                throw new Error("The local account already contains independent application data; nothing was changed.");
+            }
+        }
+        if (localUserId !== plan.identity.placeholderUserId && !alreadyClaimed) {
+            for (const declaration of plan.identity.signupDefaults) {
+                const rows = await client.query(planSignupDefaultInspection(declaration), [localUserId, plan.identity.placeholderUserId]);
+                const localRows = rows.rows.filter((row) => row.identity === localUserId);
+                const placeholderRows = rows.rows.filter((row) => row.identity === plan.identity.placeholderUserId);
+                if (localRows.length > 1 || placeholderRows.length > 1) {
+                    throw new Error("The declared signup-default relation is ambiguous; nothing was changed.");
+                }
+                if (localRows.length === 1 && placeholderRows.length === 1) {
+                    const localRow = localRows[0];
+                    if (!localRow) {
+                        throw new Error("The declared signup-default relation is ambiguous; nothing was changed.");
+                    }
+                    const defaultInspection = inspectDeclaredDefault({
+                        row: localRow.row,
+                        declaration,
+                    });
+                    if (!defaultInspection.matches) {
+                        const declaredColumns = Object.keys(declaration.values).sort();
+                        const mismatchKinds = defaultInspection.mismatchedColumns.map((column) => `${column}(${valueKind(isObject(localRow.row) ? localRow.row[column] : undefined)}/${declaration.values[column]?.kind === "exact" ? valueKind(declaration.values[column].value) : "pattern"})`);
+                        throw new Error(`The local signup row was edited or does not match its complete declared default; nothing was changed. Declared columns: ${declaredColumns.join(", ")}. Actual columns: ${defaultInspection.actualColumns.join(", ") || "none"}. Mismatched column shapes: ${mismatchKinds.join(", ") || "none"}.`);
+                    }
+                    await client.query(planSignupDefaultRemoval(declaration), [
+                        localUserId,
+                    ]);
+                    removedSignupDefaults += 1;
+                }
+            }
+        }
+        for (const reference of plan.identity.references) {
+            const expectedUserId = reference.strategy === "preserve-audit"
+                ? plan.identity.placeholderUserId
+                : localUserId;
+            if (reference.strategy === "transfer") {
+                await client.query(planRelationalReferenceTransfer(reference), [
+                    localUserId,
+                    plan.identity.placeholderUserId,
+                ]);
+            }
+            if (reference.required) {
+                const required = await client.query(planRequiredReferenceCheck(reference), [expectedUserId]);
+                if (required.rows.length !== 1) {
+                    throw new Error("A required local identity reference is missing; nothing was changed.");
+                }
+            }
+        }
+        for (const reference of plan.identity.jsonReferences) {
+            await client.query(planJsonReferenceTransfer(reference), [
+                localUserId,
+                plan.identity.placeholderUserId,
+                reference.path,
+            ]);
+        }
+        const sourcePathPrefix = `${plan.identity.placeholderUserId}/`;
+        let sourcePathReferenceCount = 0;
+        if (plan.identity.assets.some((asset) => asset.rewritePath)) {
+            for (const reference of plan.identity.pathReferences) {
+                const result = await client.query(planPathReferenceCount(reference), [sourcePathPrefix]);
+                const count = Number(result.rows[0]?.count);
+                if (!Number.isSafeInteger(count) || count < 0) {
+                    throw new Error("A Storage path reference returned an invalid count.");
+                }
+                sourcePathReferenceCount += count;
+            }
+        }
+        for (const asset of plan.identity.assets) {
+            const sourceObjects = await client.query(`select name, owner_id
+         from storage.objects
+         where bucket_id = $1
+           and name like $2::text || '%'
+         order by name`, [asset.bucket, asset.prefix]);
+            if (sourceObjects.rows.some(({ owner_id: ownerId }) => ownerId !== null &&
+                ownerId !== plan.identity.placeholderUserId &&
+                !(alreadyClaimed && ownerId === localUserId))) {
+                throw new Error("A Storage object in the reviewed placeholder path belongs to another identity; nothing was changed.");
+            }
+            if (sourceObjects.rows.length === 0)
+                continue;
+            if (!asset.rewritePath) {
+                await client.query(`update storage.objects
+           set owner_id = $1::text
+           where bucket_id = $2 and name = any($3::text[])`, [
+                    localUserId,
+                    asset.bucket,
+                    sourceObjects.rows.map(({ name }) => name),
+                ]);
+                continue;
+            }
+            if (!storageTransfer) {
+                throw new Error("Storage path transfer requires the local Supabase Storage service; nothing was changed.");
+            }
+            const copies = sourceObjects.rows.map(({ name }) => {
+                if (typeof name !== "string" || !name.startsWith(asset.prefix)) {
+                    throw new Error("A Storage object escaped its reviewed identity scope.");
+                }
+                return {
+                    bucket: asset.bucket,
+                    source: name,
+                    destination: `${localUserId}/${name.slice(asset.prefix.length)}`,
+                };
+            });
+            const collisions = await client.query(`select name
+         from storage.objects
+         where bucket_id = $1 and name = any($2::text[])
+         limit 1`, [asset.bucket, copies.map((copy) => copy.destination)]);
+            if (collisions.rows.length > 0) {
+                throw new Error("A destination Storage path already exists; nothing was changed.");
+            }
+            for (const copy of copies) {
+                await storageTransfer.copyAndVerify(copy);
+                stagedStorageCopies.push(copy);
+            }
+            await client.query(`update storage.objects
+         set owner_id = $1::text
+         where bucket_id = $2 and name = any($3::text[])`, [localUserId, asset.bucket, copies.map((copy) => copy.destination)]);
+            const transferred = await client.query(`select count(*)::integer as count
+         from storage.objects
+         where owner_id = $1::text
+           and bucket_id = $2
+           and name = any($3::text[])`, [localUserId, asset.bucket, copies.map((copy) => copy.destination)]);
+            if (Number(transferred.rows[0]?.count) !== copies.length) {
+                throw new Error("Storage ownership did not match the verified physical copies; nothing was changed.");
+            }
+            storageObjectsTransferred += copies.length;
+        }
+        if (sourcePathReferenceCount > 0 && storageObjectsTransferred === 0) {
+            throw new Error("Copied records reference Storage paths, but no matching objects were available; nothing was changed.");
+        }
+        const targetPathPrefix = `${localUserId}/`;
+        for (const reference of plan.identity.pathReferences) {
+            await client.query(planPathReferenceTransfer(reference), [
+                targetPathPrefix,
+                sourcePathPrefix,
+            ]);
+        }
+        await client.query(`update auth.users
+       set raw_app_meta_data = coalesce(raw_app_meta_data, '{}'::jsonb) || $2::jsonb,
+           updated_at = now()
+       where id = $1::uuid`, [localUserId, JSON.stringify(plan.identity.claims)]);
+        if (plan.identity.tokenHook) {
+            const hook = plan.identity.tokenHook;
+            const tokenResult = await client.query(`select ${qid(hook.function.schema)}.${qid(hook.function.name)}(
+           jsonb_build_object('user_id', $1::text, 'claims', '{}'::jsonb)
+         ) as event`, [localUserId]);
+            const event = tokenResult.rows[0]?.event;
+            const claims = isObject(event) ? event.claims : undefined;
+            if (!containsJson(claims, hook.expectedClaims)) {
+                throw new Error("The configured local token hook did not return the declared claims; nothing was changed.");
+            }
+            tokenHookVerified = true;
+        }
+        await client.query(IDENTITY_CLAIM_RECEIPT_SQL);
+        await client.query(`insert into rehearsal_internal.identity_claims (
+         identity_name, placeholder_user_id, local_user_id
+       ) values ($1, $2::uuid, $3::uuid)
+       on conflict (identity_name) do nothing`, [plan.identity.name, plan.identity.placeholderUserId, localUserId]);
+        const claimReceipt = await client.query(`select 1
+       from rehearsal_internal.identity_claims
+       where identity_name = $1
+         and placeholder_user_id = $2::uuid
+         and local_user_id = $3::uuid`, [plan.identity.name, plan.identity.placeholderUserId, localUserId]);
+        if (claimReceipt.rows.length !== 1) {
+            throw new Error("The local identity claim conflicts with an existing association receipt; nothing was changed.");
+        }
+        if (localUserId !== plan.identity.placeholderUserId) {
+            for (const reference of publicAuthReferences) {
+                const remaining = await countIdentityRows({
+                    client,
+                    reference,
+                    userId: plan.identity.placeholderUserId,
+                });
+                if (remaining === 0)
+                    continue;
+                const declared = preservedReferences.find((candidate) => candidate.schema === reference.schema &&
+                    candidate.table === reference.table &&
+                    candidate.column === reference.column);
+                if (!declared) {
+                    throw new Error("The identity policy omitted a copied application reference; nothing was changed.");
+                }
+                placeholderRetainedForAudit = true;
+            }
+            if (!placeholderRetainedForAudit) {
+                await client.query(`delete from auth.users
+           where id = $1::uuid
+             and not exists (select 1 from auth.identities where user_id = $1::uuid)`, [plan.identity.placeholderUserId]);
+            }
+        }
+        await client.query("commit");
+        committed = true;
+        const copiesByBucket = groupStorageCopies(stagedStorageCopies);
+        for (const [bucket, copies] of copiesByBucket) {
+            if (!storageTransfer) {
+                throw new Error("Storage transfer became unavailable after commit.");
+            }
+            await storageTransfer.remove({
+                bucket,
+                paths: copies.map((copy) => copy.source),
+            });
+        }
+        return {
+            name: plan.identity.name,
+            provider: localIdentity.provider,
+            claimed: true,
+            removedSignupDefaults,
+            tokenHookVerified,
+            placeholderRetainedForAudit,
+            storageObjectsTransferred,
+            idempotent: alreadyClaimed,
+        };
+    }
+    catch (error) {
+        if (committed) {
+            throw new Error("The identity claim committed and the new Storage copies are usable, but old Storage cleanup failed.", { cause: error });
+        }
+        await client.query("rollback").catch(() => undefined);
+        if (stagedStorageCopies.length > 0) {
+            const cleanupErrors = [];
+            if (!storageTransfer)
+                throw error;
+            for (const [bucket, copies] of groupStorageCopies(stagedStorageCopies)) {
+                await storageTransfer
+                    .remove({
+                    bucket,
+                    paths: copies.map((copy) => copy.destination),
+                })
+                    .catch((cleanupError) => cleanupErrors.push(cleanupError));
+            }
+            if (cleanupErrors.length > 0) {
+                throw new AggregateError([error, ...cleanupErrors], "The identity claim rolled back, but copied Storage cleanup needs attention.");
+            }
+        }
+        throw error;
+    }
+    finally {
+        await client.end?.();
+    }
+};

package/dist/src/identity/claim_identity_lookup.d.mts

@@ -0,0 +1,17 @@
+/** Read-only identity discovery and reference inspection. */
+import type { IdentityClaimPlan, IdentityDatabaseClient, IdentityProvider, IdentityReference } from "./claim_contract.mjs";
+export declare const discoverPublicAuthReferences: (client: IdentityDatabaseClient) => Promise<IdentityReference[]>;
+export declare const countIdentityRows: ({ client, reference, userId, }: {
+    client: IdentityDatabaseClient;
+    reference: Pick<IdentityReference, "schema" | "table" | "column">;
+    userId: string;
+}) => Promise<number>;
+export interface VerifiedLocalIdentity {
+    readonly id: string;
+    readonly provider: IdentityProvider;
+}
+export declare const findVerifiedLocalIdentity: ({ client, plan, matchValue, }: {
+    client: IdentityDatabaseClient;
+    plan: IdentityClaimPlan;
+    matchValue: string;
+}) => Promise<VerifiedLocalIdentity>;

package/dist/src/identity/claim_identity_lookup.mjs

@@ -0,0 +1,125 @@
+/** Read-only identity discovery and reference inspection. */
+import { createHash } from "node:crypto";
+const IDENTIFIER = /^[a-z][a-z0-9_]{0,62}$/u;
+const id = (value, label) => {
+    if (typeof value !== "string" || !IDENTIFIER.test(value)) {
+        throw new Error(`${label} is not a safe identifier.`);
+    }
+    return value;
+};
+const qid = (value) => `"${id(value, "SQL identifier")}"`;
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+export const discoverPublicAuthReferences = async (client) => {
+    const result = await client.query(`select distinct
+       source_namespace.nspname as schema,
+       source_table.relname as table,
+       source_column.attname as column
+     from pg_constraint constraint_record
+     join pg_class source_table on source_table.oid = constraint_record.conrelid
+     join pg_namespace source_namespace on source_namespace.oid = source_table.relnamespace
+     join unnest(constraint_record.conkey) with ordinality source_key(attnum, position) on true
+     join unnest(constraint_record.confkey) with ordinality target_key(attnum, position)
+       on target_key.position = source_key.position
+     join pg_attribute source_column
+       on source_column.attrelid = constraint_record.conrelid
+      and source_column.attnum = source_key.attnum
+     join pg_attribute target_column
+       on target_column.attrelid = constraint_record.confrelid
+      and target_column.attnum = target_key.attnum
+     where constraint_record.contype = 'f'
+       and constraint_record.confrelid = 'auth.users'::regclass
+       and target_column.attname = 'id'
+       and source_namespace.nspname = 'public'`);
+    return result.rows.map((reference, index) => ({
+        schema: id(reference.schema, `discoveredReference[${index}].schema`),
+        table: id(reference.table, `discoveredReference[${index}].table`),
+        column: id(reference.column, `discoveredReference[${index}].column`),
+        required: false,
+        strategy: "transfer",
+    }));
+};
+export const countIdentityRows = async ({ client, reference, userId, }) => {
+    const result = await client.query(`select count(*)::integer as count
+     from ${qid(reference.schema)}.${qid(reference.table)}
+     where ${qid(reference.column)} = $1::uuid`, [userId]);
+    const count = Number(result.rows[0]?.count);
+    if (!Number.isSafeInteger(count) || count < 0) {
+        throw new Error("A local identity reference returned an invalid count.");
+    }
+    return count;
+};
+export const findVerifiedLocalIdentity = async ({ client, plan, matchValue, }) => {
+    const matcher = plan.identity.matcher;
+    if (matcher.type === "verified-email") {
+        const match = await client.query(`select u.id::text, i.provider
+       from auth.users u
+       join auth.identities i on i.user_id = u.id
+       where lower(coalesce(i.identity_data->>'email', u.email)) = $1
+         and i.provider = any($2::text[])
+         and (
+           coalesce((i.identity_data->>'email_verified')::boolean, false)
+           or u.email_confirmed_at is not null
+         )
+       for update of u`, [matchValue, matcher.providers]);
+        if (match.rows.length !== 1) {
+            throw new Error(match.rows.length === 0
+                ? "No verified local identity matches the reviewed email and provider allowlist."
+                : "More than one verified local identity matches the reviewed email and provider allowlist.");
+        }
+        const matchedRow = match.rows[0];
+        if (!matchedRow)
+            throw new Error("Matched local identity is invalid.");
+        const matchedProvider = matchedRow.provider ??
+            (matcher.providers.length === 1 ? matcher.providers[0] : null);
+        if (typeof matchedProvider !== "string" ||
+            !matcher.providers.includes(matchedProvider)) {
+            throw new Error("Matched local identity provider is invalid.");
+        }
+        if (typeof matchedRow.id !== "string") {
+            throw new Error("Matched local identity is invalid.");
+        }
+        return {
+            id: matchedRow.id,
+            provider: matchedProvider,
+        };
+    }
+    const candidates = await client.query(`select u.id::text,
+            i.provider,
+            i.provider_id::text,
+            i.identity_data->>'sub' as subject
+     from auth.users u
+     join auth.identities i on i.user_id = u.id
+     where i.provider = $1
+       and (
+         coalesce((i.identity_data->>'email_verified')::boolean, false)
+         or u.email_confirmed_at is not null
+       )
+     for update of u`, [matcher.provider]);
+    const matches = [];
+    for (const candidate of candidates.rows) {
+        const subjects = [candidate.provider_id, candidate.subject]
+            .filter((value) => typeof value === "string" && Boolean(value.trim()))
+            .map((value) => value.trim());
+        const uniqueSubjects = [...new Set(subjects)];
+        if (uniqueSubjects.some((subject) => hash(subject) === matcher.approvedSubjectSha256)) {
+            if (uniqueSubjects.length !== 1) {
+                throw new Error("The matched local provider identity has conflicting stable subjects.");
+            }
+            if (typeof candidate.id !== "string" ||
+                candidate.provider !== matcher.provider) {
+                throw new Error("Matched local identity provider is invalid.");
+            }
+            matches.push({ id: candidate.id, provider: matcher.provider });
+        }
+    }
+    if (matches.length !== 1) {
+        throw new Error(matches.length === 0
+            ? "No verified local identity matches the reviewed provider subject."
+            : "More than one verified local identity matches the reviewed provider subject.");
+    }
+    const match = matches[0];
+    if (!match || match.provider !== matcher.provider) {
+        throw new Error("Matched local identity provider is invalid.");
+    }
+    return match;
+};

package/dist/src/identity/claim_plan.d.mts

@@ -0,0 +1,8 @@
+/** Deterministic identity claim review, digest, and local matcher binding. */
+import type { IdentityClaimPlan } from "./claim_contract.mjs";
+export declare const createIdentityClaimPlan: ({ policy, name, environment, }: {
+    policy: unknown;
+    name: string;
+    environment?: Readonly<Record<string, string | undefined>>;
+}) => IdentityClaimPlan;
+export declare const getIdentityPlanMatchValue: (plan: IdentityClaimPlan) => string | undefined;