@signal58/payload-oidc 0.0.0 → 0.3.0

package/dist/reconcile-task.js

@@ -0,0 +1,163 @@
+import { reconcileUsers } from './reconcile.js';
+export const RECONCILE_TASK_SLUG = 'payload-oidc-reconcile';
+/** Payload's jobs collection. */
+const JOBS_COLLECTION = 'payload-jobs';
+/**
+ * Marks reconcile runs on `queue` that are still processing after `olderThanSeconds` as failed,
+ * and returns the IDs it marked.
+ *
+ * Payload's scheduler queues a run only while no scheduled run of the task is waiting or
+ * processing, and its runner only picks up jobs that aren't processing. A run left processing by a
+ * process that stopped mid-run (a container a deploy replaced) would therefore block the queue for
+ * good: Payload never expires it. Payload's own cancel writes its final-failure shape
+ * (`hasError`, `processing: false`, `error.cancelled`), so the dead run stays visible as a failed
+ * job and the scheduler stops counting it.
+ */
+export const releaseStaleRuns = async (payload, { now, olderThanSeconds, queue }) => {
+    const where = {
+        and: [
+            { processing: { equals: true } },
+            { completedAt: { exists: false } },
+            { hasError: { not_equals: true } },
+            { queue: { equals: queue } },
+            { taskSlug: { equals: RECONCILE_TASK_SLUG } },
+            { updatedAt: { less_than: new Date(now.getTime() - olderThanSeconds * 1000).toISOString() } },
+        ],
+    };
+    const select = { createdAt: true, updatedAt: true };
+    const { docs: stale } = (await payload.find({
+        collection: JOBS_COLLECTION,
+        depth: 0,
+        overrideAccess: true,
+        pagination: false,
+        select,
+        where,
+    }));
+    if (stale.length === 0)
+        return [];
+    const ids = stale.map((job) => job.id);
+    // Only those still processing: a run that finished since the find is left alone.
+    await payload.jobs.cancel({
+        overrideAccess: true,
+        where: { and: [{ id: { in: ids } }, { processing: { equals: true } }] },
+    });
+    // Cancel doesn't say which jobs it changed, so read back the ones it marked.
+    const { docs: released } = (await payload.find({
+        collection: JOBS_COLLECTION,
+        depth: 0,
+        overrideAccess: true,
+        pagination: false,
+        select,
+        where: { and: [{ id: { in: ids } }, { 'error.cancelled': { equals: true } }] },
+    }));
+    for (const job of released) {
+        payload.logger.warn({
+            createdAt: job.createdAt,
+            jobId: job.id,
+            lastUpdatedAt: job.updatedAt,
+            msg: `payload-oidc: marked reconcile run ${job.id} failed: still processing after ${olderThanSeconds} seconds`,
+        });
+    }
+    return released.map((job) => job.id);
+};
+/** The share of the stale threshold a run's source may take before the run gives up. */
+const SOURCE_TIME_SHARE = 0.8;
+/**
+ * The options with the reconcile source's answer limited to `limitMs`. Payload doesn't touch a
+ * job while its handler runs, so a run that outlasted the stale threshold would look cut off,
+ * be released, and overlap the new run. Reconcile writes nothing until every group is read, so
+ * stopping at the read changes nothing.
+ */
+const withSourceTimeLimit = (options, limitMs) => {
+    const source = options.reconcile;
+    return {
+        ...options,
+        reconcile: {
+            ...source,
+            fetchGroupMembers: async (groups) => {
+                let timer;
+                const late = new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`payload-oidc: the reconcile source took longer than ${limitMs / 1000} seconds; the run stopped before changing anything, so it can't outlast reconcileStaleAfterMinutes and be taken for a cut-off run.`)), limitMs);
+                });
+                try {
+                    return await Promise.race([source.fetchGroupMembers(groups), late]);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            },
+        },
+    };
+};
+/**
+ * The reconcile job. Payload schedules it only on its own queue, and runs schedules only for
+ * queues listed in `jobs.autoRun`, so the app must add that queue there. A failed run (a group
+ * that can't be read, a safety stop) fails the job and records no heartbeat.
+ */
+export const createReconcileTask = (options, { clock = () => new Date(), concurrencyControl = false } = {}) => ({
+    slug: RECONCILE_TASK_SLUG,
+    label: 'Reconcile CMS users with the identity provider',
+    // One run at a time where the app enables Payload's concurrency control; otherwise Payload's
+    // scheduler still skips a schedule while a run is queued or running.
+    ...(concurrencyControl ? { concurrency: () => RECONCILE_TASK_SLUG } : {}),
+    inputSchema: [],
+    outputSchema: [
+        { name: 'disabled', type: 'number', required: true },
+        { name: 'roleChanges', type: 'number', required: true },
+        { name: 'users', type: 'number', required: true },
+    ],
+    retries: 0,
+    ...(options.enabled && options.reconcile
+        ? {
+            schedule: [
+                {
+                    cron: options.reconcile.cron,
+                    hooks: {
+                        ...options.reconcileScheduleHooks,
+                        beforeSchedule: async (args) => {
+                            // On every tick, not only at startup: with start-first deploys the run a deploy
+                            // cuts off usually belongs to the old process, after this one started.
+                            const olderThanSeconds = options.reconcileStaleAfterSeconds;
+                            if (olderThanSeconds !== undefined) {
+                                try {
+                                    await releaseStaleRuns(args.req.payload, {
+                                        now: clock(),
+                                        olderThanSeconds,
+                                        queue: args.queueable.scheduleConfig.queue,
+                                    });
+                                }
+                                catch (error) {
+                                    // Still make the scheduling decision; the next tick tries again.
+                                    args.req.payload.logger.error({
+                                        err: error,
+                                        msg: 'payload-oidc: could not release stale reconcile runs',
+                                    });
+                                }
+                            }
+                            return {
+                                ...(await (options.reconcileScheduleHooks?.beforeSchedule ?? args.defaultBeforeSchedule)(args)),
+                                // Payload can make a new job wait for the next cron slot. That slot's tick only
+                                // runs the job, as one is still waiting, so reconcile would run on every other
+                                // tick. With no wait, the tick that queues the job also runs it.
+                                waitUntil: undefined,
+                            };
+                        },
+                    },
+                    queue: options.reconcile.queue,
+                },
+            ],
+        }
+        : {}),
+    handler: async ({ req }) => {
+        if (!options.enabled || !options.reconcile) {
+            return { output: { disabled: 0, roleChanges: 0, users: 0 } };
+        }
+        const staleAfterSeconds = options.reconcileStaleAfterSeconds;
+        const { disabled, roleChanges, users } = await reconcileUsers(req.payload, 
+        // While stale runs are released, a live run must end well before it would look stale.
+        staleAfterSeconds === undefined
+            ? options
+            : withSourceTimeLimit(options, staleAfterSeconds * 1000 * SOURCE_TIME_SHARE), clock());
+        return { output: { disabled, roleChanges, users } };
+    },
+});

package/dist/reconcile.d.ts

@@ -0,0 +1,32 @@
+import type { Payload } from 'payload';
+import { type ResolvedOidcOptions } from './options.js';
+/** KV key of the last successful reconcile run. */
+export declare const RECONCILE_HEARTBEAT_KEY = "payload-oidc:reconcile";
+export type ReconcileHeartbeat = {
+    disabled: number;
+    finishedAt: string;
+    roleChanges: number;
+    users: number;
+};
+export type ReconcileResult = ReconcileHeartbeat;
+/**
+ * Brings every linked user in line with the provider's groups:
+ *
+ * - A user whose subject is in no role-table group, or only as an inactive member, is disabled
+ *   (again, if a whole-document write restored their role or sessions).
+ * - An enabled user whose role changed gets the new role. A disabled user stays disabled until
+ *   they sign in again.
+ * - Users are never created, and the break-glass account and unlinked users are never touched.
+ *
+ * It changes nothing unless every group was read, and stops without changes if it would disable
+ * more than `maxDisableShare` of the linked users (at least one is always allowed), so a renamed
+ * group or a lost permission can't disable a whole tier. Each successful run records a heartbeat.
+ *
+ * @throws When a group can't be read or a safety stop trips: the job fails and alerts.
+ */
+export declare const reconcileUsers: (payload: Payload, options: ResolvedOidcOptions, now?: Date) => Promise<ReconcileResult>;
+/** Whether the last successful run is recent enough, for a status check such as Gatus. */
+export declare const reconcileHealth: (payload: Payload, options: ResolvedOidcOptions, now?: Date) => Promise<{
+    healthy: boolean;
+    lastSuccessAt: string | null;
+}>;

package/dist/reconcile.js

@@ -0,0 +1,110 @@
+import { isBreakGlassEmail, roleForGroups, roleTableGroups, } from './options.js';
+import { authCollectionModel, disableUser, OIDC_FIELDS, roleValue } from './store.js';
+/** KV key of the last successful reconcile run. */
+export const RECONCILE_HEARTBEAT_KEY = 'payload-oidc:reconcile';
+/**
+ * Brings every linked user in line with the provider's groups:
+ *
+ * - A user whose subject is in no role-table group, or only as an inactive member, is disabled
+ *   (again, if a whole-document write restored their role or sessions).
+ * - An enabled user whose role changed gets the new role. A disabled user stays disabled until
+ *   they sign in again.
+ * - Users are never created, and the break-glass account and unlinked users are never touched.
+ *
+ * It changes nothing unless every group was read, and stops without changes if it would disable
+ * more than `maxDisableShare` of the linked users (at least one is always allowed), so a renamed
+ * group or a lost permission can't disable a whole tier. Each successful run records a heartbeat.
+ *
+ * @throws When a group can't be read or a safety stop trips: the job fails and alerts.
+ */
+export const reconcileUsers = async (payload, options, now = new Date()) => {
+    const source = options.reconcile;
+    if (!source)
+        throw new Error('payload-oidc: reconcile is not configured.');
+    // Users first, then groups: every write below is conditional on the user being unchanged
+    // since this read, so someone who signs in (and is synced) while the groups are fetched is left
+    // for the next run instead of being judged on a stale snapshot.
+    const model = authCollectionModel(payload, options.collection);
+    const linked = await model.find({ [OIDC_FIELDS.subject]: { $exists: true } }).lean();
+    const groups = roleTableGroups(options.roleTable);
+    const members = await source.fetchGroupMembers(groups);
+    const groupsBySubject = new Map();
+    for (const group of groups) {
+        const list = members.get(group);
+        if (!list)
+            throw new Error(`payload-oidc: reconcile got no answer for group ${group}.`);
+        for (const member of list) {
+            if (!member.active)
+                continue;
+            groupsBySubject.set(member.subject, [...(groupsBySubject.get(member.subject) ?? []), group]);
+        }
+    }
+    const unchanged = (user) => ({
+        _id: user._id,
+        [OIDC_FIELDS.subject]: user[OIDC_FIELDS.subject],
+        updatedAt: user.updatedAt ?? null,
+    });
+    const newlyDisabled = [];
+    const redisabled = [];
+    const toChange = [];
+    let enabled = 0;
+    for (const user of linked) {
+        if (isBreakGlassEmail(options, user.email))
+            continue;
+        const isDisabled = Boolean(user[OIDC_FIELDS.disabledAt]);
+        if (!isDisabled)
+            enabled += 1;
+        const role = roleForGroups(options.roleTable, groupsBySubject.get(String(user[OIDC_FIELDS.subject])));
+        const stored = user[options.roleField];
+        const hasRole = Array.isArray(stored) ? stored.length > 0 : Boolean(stored);
+        const sessions = Array.isArray(user.sessions) ? user.sessions.length : 0;
+        if (!role) {
+            if (!isDisabled)
+                newlyDisabled.push(user);
+            // Disabled already, but a whole-document write restored the role or sessions.
+            else if (hasRole || sessions > 0)
+                redisabled.push(user);
+            continue;
+        }
+        if (isDisabled)
+            continue;
+        if (JSON.stringify(stored) !== JSON.stringify(roleValue(options, role))) {
+            toChange.push({ role, user });
+        }
+    }
+    // The share counts enabled users only: disabled ones that were never removed would otherwise
+    // inflate it until a whole tier fits under the limit.
+    const allowed = Math.max(1, Math.floor(enabled * options.reconcileMaxDisableShare));
+    if (newlyDisabled.length > allowed) {
+        throw new Error(`payload-oidc: reconcile would disable ${newlyDisabled.length} of ${enabled} enabled users (more than ${allowed}); nothing was changed. If that is intended, raise reconcileMaxDisableShare for one run.`);
+    }
+    let disabled = 0;
+    for (const user of [...newlyDisabled, ...redisabled]) {
+        if (await disableUser(payload, options, user._id, now, unchanged(user)))
+            disabled += 1;
+    }
+    let roleChanges = 0;
+    for (const { role, user } of toChange) {
+        // Only while still enabled and unchanged: a disable or a sign-in that landed meanwhile wins.
+        const result = await model.updateOne({ ...unchanged(user), [OIDC_FIELDS.disabledAt]: null }, { $set: { [options.roleField]: roleValue(options, role), updatedAt: now } });
+        if (result.matchedCount > 0)
+            roleChanges += 1;
+    }
+    const heartbeat = {
+        disabled,
+        finishedAt: now.toISOString(),
+        roleChanges,
+        users: linked.length,
+    };
+    await payload.kv.set(RECONCILE_HEARTBEAT_KEY, heartbeat);
+    payload.logger.info({ msg: 'payload-oidc: reconcile finished', ...heartbeat });
+    return heartbeat;
+};
+/** Whether the last successful run is recent enough, for a status check such as Gatus. */
+export const reconcileHealth = async (payload, options, now = new Date()) => {
+    const heartbeat = await payload.kv.get(RECONCILE_HEARTBEAT_KEY);
+    const finishedAt = heartbeat?.finishedAt ? new Date(heartbeat.finishedAt) : undefined;
+    const healthy = Boolean(finishedAt &&
+        now.getTime() - finishedAt.getTime() <= options.reconcileHeartbeatMaxSeconds * 1000);
+    return { healthy, lastSuccessAt: heartbeat?.finishedAt ?? null };
+};

package/dist/remove.d.ts

@@ -0,0 +1,29 @@
+import type { Payload, SanitizedCollectionConfig, SanitizedGlobalConfig } from 'payload';
+import { type ResolvedOidcOptions } from './options.js';
+/** A place a document can point at a user: a collection or global, and a dotted field path. */
+export type UserReference = {
+    entity: 'collection' | 'global';
+    path: string;
+    slug: string;
+    versions: boolean;
+};
+/**
+ * Every field in the config that can refer to a user of `collection`, except Payload's own
+ * bookkeeping (preferences, locks, jobs, migrations), which belongs to the user and goes with it.
+ * Rich-text relationships aren't seen; anything referenced only there is left as a dangling link.
+ */
+export declare const findUserReferences: (collections: SanitizedCollectionConfig[], globals: SanitizedGlobalConfig[], collection: string) => UserReference[];
+export type RemoveOutcome = {
+    kind: 'anonymised' | 'deleted';
+} | {
+    kind: 'refused';
+    reason: 'break_glass' | 'not_disabled' | 'not_found';
+};
+/**
+ * Removes a disabled user. Only disabled users: an active one would be created again at their
+ * next sign-in. If nothing refers to the user they are deleted; otherwise they are anonymised
+ * (names "Removed user", email `removed-<id>@removed.invalid`, every other profile field, the
+ * subject, password and sessions gone) so bylines and audit rows still resolve. Someone added back at the provider later signs
+ * in as a new user.
+ */
+export declare const removeUser: (payload: Payload, options: ResolvedOidcOptions, id: string | number) => Promise<RemoveOutcome>;

package/dist/remove.js

@@ -0,0 +1,161 @@
+import { isBreakGlassEmail } from './options.js';
+import { authCollectionModel, OIDC_FIELDS, OIDC_SYNC_CONTEXT, unusablePassword } from './store.js';
+const pointsAt = (relationTo, collection) => Array.isArray(relationTo) ? relationTo.includes(collection) : relationTo === collection;
+/** Every relationship or upload field under `fields` that can point at `collection`. */
+const referencePaths = (fields, collection, prefix = '') => fields.flatMap((field) => {
+    const named = 'name' in field && field.name ? `${prefix}${field.name}` : undefined;
+    if ((field.type === 'relationship' || field.type === 'upload') && named) {
+        if (!pointsAt(field.relationTo, collection))
+            return [];
+        // A polymorphic relationship stores `{ relationTo, value }`.
+        return [Array.isArray(field.relationTo) ? `${named}.value` : named];
+    }
+    if (field.type === 'array' || field.type === 'group') {
+        return referencePaths(field.fields, collection, named ? `${named}.` : prefix);
+    }
+    if (field.type === 'blocks' && named) {
+        return field.blocks.flatMap((block) => referencePaths(typeof block === 'string' ? [] : block.fields, collection, `${named}.`));
+    }
+    if (field.type === 'tabs') {
+        return field.tabs.flatMap((tab) => referencePaths(tab.fields, collection, 'name' in tab && tab.name ? `${prefix}${tab.name}.` : prefix));
+    }
+    if ((field.type === 'row' || field.type === 'collapsible') && 'fields' in field) {
+        return referencePaths(field.fields, collection, prefix);
+    }
+    return [];
+});
+/**
+ * Every field in the config that can refer to a user of `collection`, except Payload's own
+ * bookkeeping (preferences, locks, jobs, migrations), which belongs to the user and goes with it.
+ * Rich-text relationships aren't seen; anything referenced only there is left as a dangling link.
+ */
+export const findUserReferences = (collections, globals, collection) => [
+    ...collections
+        .filter(({ slug }) => !slug.startsWith('payload-'))
+        .flatMap((config) => referencePaths(config.fields, collection).map((path) => ({
+        entity: 'collection',
+        path,
+        slug: config.slug,
+        versions: Boolean(config.versions),
+    }))),
+    ...globals.flatMap((config) => referencePaths(config.fields, collection).map((path) => ({
+        entity: 'global',
+        path,
+        slug: config.slug,
+        versions: Boolean(config.versions),
+    }))),
+];
+const isReferenced = async (payload, references, id) => {
+    for (const reference of references) {
+        if (reference.entity === 'global') {
+            const global = (await payload.findGlobal({
+                depth: 0,
+                overrideAccess: true,
+                slug: reference.slug,
+            }));
+            if (JSON.stringify(global).includes(JSON.stringify(String(id))))
+                return true;
+            continue;
+        }
+        const where = { [reference.path]: { equals: id } };
+        const { totalDocs } = await payload.count({
+            collection: reference.slug,
+            overrideAccess: true,
+            where,
+        });
+        if (totalDocs > 0)
+            return true;
+        if (reference.versions) {
+            const versions = await payload.countVersions({
+                collection: reference.slug,
+                overrideAccess: true,
+                where: { [`version.${reference.path}`]: { equals: id } },
+            });
+            if (versions.totalDocs > 0)
+                return true;
+        }
+    }
+    return false;
+};
+/** Payload's auth bookkeeping that names or can act for the person. */
+const AUTH_FIELDS_TO_CLEAR = [
+    '_verificationToken',
+    'lockUntil',
+    'loginAttempts',
+    'resetPasswordExpiration',
+    'resetPasswordRequestedAt',
+    'resetPasswordToken',
+];
+/**
+ * Everything an anonymised user loses: every top-level data field of the collection (photo,
+ * social links, anything an app added) except the ones anonymising sets or keeps, plus Payload's
+ * auth bookkeeping. `keepOnRemove` names fields an app wants kept.
+ */
+const fieldsToClear = (payload, options) => {
+    const keep = new Set([
+        'createdAt',
+        'email',
+        'hash',
+        'id',
+        'salt',
+        'sessions',
+        'updatedAt',
+        OIDC_FIELDS.disabledAt,
+        options.firstNameField,
+        options.lastNameField,
+        options.roleField,
+        ...options.keepOnRemove,
+    ]);
+    const config = payload.collections[options.collection];
+    const dataFields = config.config.flattenedFields
+        .filter((field) => 'name' in field && field.type !== 'join')
+        .map((field) => field.name);
+    return [...new Set([...dataFields, ...AUTH_FIELDS_TO_CLEAR])].filter((name) => !keep.has(name));
+};
+/**
+ * Removes a disabled user. Only disabled users: an active one would be created again at their
+ * next sign-in. If nothing refers to the user they are deleted; otherwise they are anonymised
+ * (names "Removed user", email `removed-<id>@removed.invalid`, every other profile field, the
+ * subject, password and sessions gone) so bylines and audit rows still resolve. Someone added back at the provider later signs
+ * in as a new user.
+ */
+export const removeUser = async (payload, options, id) => {
+    const model = authCollectionModel(payload, options.collection);
+    const user = await model.findOne({ _id: id }, { email: 1, [OIDC_FIELDS.disabledAt]: 1 }).lean();
+    if (!user)
+        return { kind: 'refused', reason: 'not_found' };
+    if (isBreakGlassEmail(options, user.email))
+        return { kind: 'refused', reason: 'break_glass' };
+    if (!user.oidcDisabledAt)
+        return { kind: 'refused', reason: 'not_disabled' };
+    const references = findUserReferences(payload.config.collections, payload.config.globals, options.collection);
+    if (!(await isReferenced(payload, references, id))) {
+        // Re-checked in the delete itself: a user who signed in again since the read above is no
+        // longer disabled and is kept.
+        const { docs } = await payload.delete({
+            collection: options.collection,
+            context: { [OIDC_SYNC_CONTEXT]: true },
+            overrideAccess: true,
+            where: {
+                and: [{ id: { equals: id } }, { [OIDC_FIELDS.disabledAt]: { exists: true } }],
+            },
+        });
+        return docs.length > 0 ? { kind: 'deleted' } : { kind: 'refused', reason: 'not_disabled' };
+    }
+    const clear = fieldsToClear(payload, options);
+    const result = await model.updateOne({ _id: id, [OIDC_FIELDS.disabledAt]: { $ne: null } }, {
+        $set: {
+            // A valid address (Payload's email check needs a dotted domain), unique per user, and
+            // under a reserved TLD so it can never receive mail.
+            email: `removed-${String(id)}@removed.invalid`,
+            [options.firstNameField]: 'Removed',
+            [options.lastNameField]: 'user',
+            sessions: [],
+            ...unusablePassword(),
+        },
+        $unset: Object.fromEntries([OIDC_FIELDS.linkable, OIDC_FIELDS.subject, ...clear].map((field) => [field, ''])),
+    });
+    return result.matchedCount > 0
+        ? { kind: 'anonymised' }
+        : { kind: 'refused', reason: 'not_disabled' };
+};

package/dist/sign-in.d.ts

@@ -0,0 +1,27 @@
+import { type Payload } from 'payload';
+import { type ResolvedOidcOptions } from './options.js';
+import type { VerifiedIdentity } from './provider.js';
+/**
+ * Why a sign-in was refused. The login page shows a short message per code; provider detail is
+ * only logged.
+ */
+export type SignInRefusal = 'account_conflict' | 'failed' | 'disabled' | 'email_not_verified' | 'no_role' | 'provider' | 'expired' | 'unavailable';
+export type SignInOutcome = {
+    kind: 'refused';
+    reason: SignInRefusal;
+} | {
+    expiresAt: Date;
+    kind: 'success';
+    token: string;
+    userId: string | number;
+};
+/** First and last name from the claims; `lastName` is required, so it falls back to a placeholder. */
+export declare const namesFromIdentity: (options: ResolvedOidcOptions, identity: VerifiedIdentity) => {
+    firstName: string;
+    lastName: string;
+};
+/**
+ * Finishes a sign-in after the ID token has been validated: decides the role, finds, links or
+ * creates the user, writes the provider-owned fields, and issues a Payload session.
+ */
+export declare const completeSignIn: (payload: Payload, options: ResolvedOidcOptions, identity: VerifiedIdentity, now: Date) => Promise<SignInOutcome>;

package/dist/sign-in.js

@@ -0,0 +1,122 @@
+import crypto from 'node:crypto';
+import { getFieldsToSign, jwtSign } from 'payload';
+import { canLinkByEmail, isBreakGlassEmail, roleForGroups, } from './options.js';
+import { authCollectionConfig, disableUser, isDuplicateKeyError, linkByEmail, markVerified, OIDC_FIELDS, OIDC_SYNC_CONTEXT, pushSession, roleValue, writeManagedFields, } from './store.js';
+const syncContext = { [OIDC_SYNC_CONTEXT]: true };
+const findOne = async (payload, collection, where) => {
+    const { docs } = await payload.find({
+        collection: collection,
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        pagination: false,
+        where: where,
+    });
+    return docs[0];
+};
+/** First and last name from the claims; `lastName` is required, so it falls back to a placeholder. */
+export const namesFromIdentity = (options, identity) => {
+    const firstName = identity.givenName ?? identity.name?.split(/\s+/)[0] ?? identity.email.split('@')[0];
+    return { firstName, lastName: identity.familyName ?? options.lastNamePlaceholder };
+};
+/**
+ * Finishes a sign-in after the ID token has been validated: decides the role, finds, links or
+ * creates the user, writes the provider-owned fields, and issues a Payload session.
+ */
+export const completeSignIn = async (payload, options, identity, now) => {
+    const refuse = (reason) => ({ kind: 'refused', reason });
+    if (!identity.emailVerified)
+        return refuse('email_not_verified');
+    // The break-glass account signs in with its password only. A provider account with its email
+    // must never link to it (which would rotate its password away) or sync it.
+    if (isBreakGlassEmail(options, identity.email))
+        return refuse('account_conflict');
+    const collection = options.collection;
+    const bySubject = { [OIDC_FIELDS.subject]: { equals: identity.subject } };
+    const role = roleForGroups(options.roleTable, identity.groups);
+    let user = await findOne(payload, collection, bySubject);
+    if (!role) {
+        if (user && !isBreakGlassEmail(options, user.email)) {
+            await disableUser(payload, options, user.id, now);
+        }
+        return refuse('no_role');
+    }
+    if (!user &&
+        canLinkByEmail(options, now) &&
+        (await linkByEmail(payload, options, identity.email, identity.subject))) {
+        user = await findOne(payload, collection, bySubject);
+    }
+    const names = namesFromIdentity(options, identity);
+    const managed = {
+        email: identity.email,
+        [options.firstNameField]: names.firstName,
+        [options.lastNameField]: names.lastName,
+        [options.roleField]: roleValue(options, role),
+    };
+    if (!user) {
+        // Someone else's email (a user who isn't linkable, or is linked to another subject): never
+        // take the account over and never create a duplicate.
+        if (await findOne(payload, collection, { email: { equals: identity.email } })) {
+            return refuse('account_conflict');
+        }
+        try {
+            const created = (await payload.create({
+                collection: collection,
+                context: syncContext,
+                data: {
+                    ...managed,
+                    [OIDC_FIELDS.subject]: identity.subject,
+                    // Required by local auth; nobody knows it, and password sign-in is closed anyway.
+                    password: crypto.randomBytes(48).toString('base64url'),
+                },
+                depth: 0,
+                disableVerificationEmail: true,
+                overrideAccess: true,
+            }));
+            await markVerified(payload, options, created.id);
+            user = created;
+        }
+        catch (error) {
+            if (!isDuplicateKeyError(error, [OIDC_FIELDS.subject, 'email']))
+                throw error;
+            // A second first sign-in for the same subject won the race (it may not have committed
+            // yet), or the email was just taken.
+            for (let attempt = 0; !user && attempt < 5; attempt += 1) {
+                if (attempt > 0)
+                    await new Promise((resolve) => setTimeout(resolve, 100));
+                user = await findOne(payload, collection, bySubject);
+            }
+            if (!user)
+                return refuse('account_conflict');
+        }
+    }
+    else {
+        try {
+            if (!(await writeManagedFields(payload, options, user.id, identity.subject, managed, now))) {
+                return refuse('disabled');
+            }
+        }
+        catch (error) {
+            // The provider's email now belongs to another CMS user.
+            if (isDuplicateKeyError(error))
+                return refuse('account_conflict');
+            throw error;
+        }
+        user = (await findOne(payload, collection, bySubject)) ?? user;
+    }
+    const sid = await pushSession(payload, options, user.id, identity.subject, now);
+    if (!sid)
+        return refuse('disabled');
+    const collectionConfig = authCollectionConfig(payload, collection);
+    const { exp, token } = await jwtSign({
+        fieldsToSign: getFieldsToSign({
+            collectionConfig,
+            email: identity.email,
+            sid,
+            user: { ...user, collection },
+        }),
+        secret: payload.secret,
+        tokenExpiration: options.sessionSeconds,
+    });
+    return { expiresAt: new Date(exp * 1000), kind: 'success', token, userId: user.id };
+};

package/dist/sources/authentik.d.ts

@@ -0,0 +1,26 @@
+import type { ReconcileSource } from '../options.js';
+/**
+ * A reconcile source that reads the role-table groups' members from Authentik's API.
+ *
+ * The token needs only object-level `view_group` on those groups: reading a group returns its
+ * direct members with their `uid`, which equals the OIDC `sub` when the provider's subject mode
+ * is "based on the user's hashed ID". Every group must exist and be readable, or the fetch throws
+ * and reconcile changes nothing.
+ *
+ * @param options.url - Authentik's base URL, such as `https://auth.example.com`.
+ * @param options.token - An API token for a service account with `view_group` on the groups.
+ * @param options.queue - The Payload jobs queue the reconcile task runs on.
+ * @param options.cron - How often it runs (default every 15 minutes).
+ * @param options.fetch - For tests.
+ */
+export declare const authentikSource: (options: {
+    /** Allows an `http:` URL, for a local Authentik; refused when `NODE_ENV` is `production`. */
+    allowInsecure?: boolean;
+    cron?: string;
+    fetch?: typeof fetch;
+    queue?: string;
+    /** Per request, in milliseconds (default 30 seconds). */
+    timeoutMs?: number;
+    token?: string;
+    url?: string;
+}) => ReconcileSource | undefined;