@signal58/payload-oidc 0.0.0-stage → 0.2.0

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;

package/dist/sources/authentik.js

@@ -0,0 +1,60 @@
+/**
+ * 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 const authentikSource = (options) => {
+    const url = options.url?.trim().replace(/\/+$/, '');
+    const token = options.token?.trim();
+    if (!url || !token)
+        return undefined;
+    // The token travels in the Authorization header: never in clear text outside local development.
+    if (new URL(url).protocol !== 'https:') {
+        if (!options.allowInsecure || process.env.NODE_ENV === 'production') {
+            throw new Error('payload-oidc: the Authentik reconcile URL must use https.');
+        }
+    }
+    const request = options.fetch ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const fetchGroup = async (name) => {
+        const query = new URLSearchParams({ include_users: 'true', name, page_size: '2' });
+        const response = await request(`${url}/api/v3/core/groups/?${query}`, {
+            headers: { Accept: 'application/json', Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            throw new Error(`Authentik answered ${response.status} for group ${name}.`);
+        const body = (await response.json());
+        const matches = (body.results ?? []).filter((group) => group.name === name);
+        // A missing group (renamed, or the token lost its permission) is a failure, not an empty one:
+        // otherwise a whole tier would be disabled.
+        if (matches.length !== 1)
+            throw new Error(`Authentik group ${name} not found or not readable.`);
+        const members = matches[0].users_obj;
+        if (!Array.isArray(members))
+            throw new Error(`Authentik returned no members for ${name}.`);
+        return members.map((member) => {
+            if (typeof member.uid !== 'string' || !member.uid) {
+                throw new Error(`Authentik returned a member of ${name} without a uid.`);
+            }
+            return { active: member.is_active === true, subject: member.uid };
+        });
+    };
+    return {
+        cron: options.cron ?? '*/15 * * * *',
+        fetchGroupMembers: async (groups) => {
+            const entries = await Promise.all(groups.map(async (group) => [group, await fetchGroup(group)]));
+            return new Map(entries);
+        },
+        queue: options.queue ?? 'oidc-reconcile',
+    };
+};

package/dist/store.d.ts

@@ -0,0 +1,105 @@
+import { type Payload, type SanitizedCollectionConfig } from 'payload';
+import type { ResolvedOidcOptions } from './options.js';
+/** `req.context` key that marks a write made by the plugin's sync. */
+export declare const OIDC_SYNC_CONTEXT = "oidcSync";
+/** The fields the plugin adds to the auth collection. */
+export declare const OIDC_FIELDS: {
+    readonly disabledAt: 'oidcDisabledAt';
+    readonly linkable: 'oidcLinkable';
+    readonly subject: 'oidcSubject';
+};
+type StoredSession = {
+    createdAt: Date | string;
+    expiresAt: Date | string;
+    id: string;
+};
+/** The stored shape of an auth-collection document, as far as the plugin reads it. */
+export type StoredUser = {
+    _id: unknown;
+    email?: string;
+    oidcDisabledAt?: Date | null;
+    oidcLinkable?: boolean;
+    oidcSubject?: string;
+    sessions?: StoredSession[];
+    [key: string]: unknown;
+};
+type UpdateResult = {
+    matchedCount: number;
+    modifiedCount?: number;
+};
+/** The subset of a Mongoose model the plugin needs for conditional, atomic writes. */
+export type AuthCollectionModel = {
+    find: (filter: Record<string, unknown>) => {
+        lean: () => Promise<StoredUser[]>;
+    };
+    findOne: (filter: Record<string, unknown>, projection?: Record<string, 0 | 1>) => {
+        lean: () => Promise<StoredUser | null>;
+    };
+    updateOne: (filter: Record<string, unknown>, update: Record<string, unknown> | Record<string, unknown>[], options?: Record<string, unknown>) => Promise<UpdateResult>;
+};
+/**
+ * The auth collection's Mongoose model. Session pushes and disables must be conditional, atomic
+ * updates, which Payload's adapter API can't express, so the plugin needs MongoDB.
+ */
+export declare const authCollectionModel: (payload: Payload, slug: string) => AuthCollectionModel;
+/**
+ * The auth collection's sanitized config. Typed loosely on purpose: an app's generated Payload
+ * types narrow collection slugs to its own, which a plugin can't name.
+ */
+export declare const authCollectionConfig: (payload: Payload, slug: string) => SanitizedCollectionConfig;
+/** A password hash and salt that no password matches. */
+export declare const unusablePassword: () => {
+    hash: string;
+    salt: string;
+};
+/** The value the role field stores for `role` (or for no role). */
+export declare const roleValue: (options: ResolvedOidcOptions, role: string | undefined) => string | string[] | null;
+/**
+ * Disables a user: clears the role and every session and sets `oidcDisabledAt`, in one atomic
+ * update. Clearing sessions ends access on the next request, because Payload checks the session
+ * ID on every request. The break-glass account is never matched.
+ *
+ * @returns Whether a user was disabled.
+ */
+export declare const disableUser: (payload: Payload, options: ResolvedOidcOptions, id: unknown, now: Date, 
+/** Further conditions, such as "unchanged since it was read". */
+condition?: Record<string, unknown>) => Promise<boolean>;
+/**
+ * Links an existing, never-linked snapshot user to a provider subject, by email. One atomic,
+ * conditional update sets the subject, clears `oidcLinkable` and every session, and replaces the
+ * password with one nobody knows, so the old password and old sessions stop working.
+ *
+ * @returns Whether a user was linked.
+ */
+export declare const linkByEmail: (payload: Payload, options: ResolvedOidcOptions, email: string, subject: string) => Promise<boolean>;
+/**
+ * Writes the provider-owned fields of a linked user and clears `oidcDisabledAt`, as one update of
+ * just those paths. A Payload update would write back the whole document as it read it, sessions
+ * included, so a disable landing in between would be undone.
+ *
+ * @returns Whether the user (still linked to `subject`) was updated.
+ */
+export declare const writeManagedFields: (payload: Payload, options: ResolvedOidcOptions, id: unknown, subject: string, fields: Record<string, unknown>, now: Date) => Promise<boolean>;
+/** Marks a user Payload created as verified, for collections with `auth.verify`. */
+export declare const markVerified: (payload: Payload, options: ResolvedOidcOptions, id: unknown) => Promise<void>;
+/**
+ * Whether an error is a unique index refusing the write: MongoDB's duplicate-key error from a raw
+ * model write, the `ValidationError` db-mongodb turns it into for a Payload write (with the
+ * unique field as its path, and no cause), or a transaction's write conflict on the same key.
+ */
+export declare const isDuplicateKeyError: (error: unknown, uniqueFields?: readonly string[]) => boolean;
+/**
+ * Adds a session, conditional on the user still being linked to `subject` and not disabled, as one
+ * atomic update. A whole-document write (Payload's `addSessionToUser`) could undo a disable that
+ * landed between the read and the write; this can't. Expired sessions are dropped in the same
+ * update.
+ *
+ * @returns The new session ID, or `undefined` if the user was disabled or relinked meanwhile.
+ */
+export declare const pushSession: (payload: Payload, options: ResolvedOidcOptions, id: unknown, subject: string, now: Date) => Promise<string | undefined>;
+/** One stored session, with the fields the refresh cap needs. */
+export declare const findSession: (payload: Payload, options: ResolvedOidcOptions, id: unknown, sid: string) => Promise<{
+    createdAt: Date;
+    disabled: boolean;
+} | undefined>;
+export {};

package/dist/store.js

@@ -0,0 +1,161 @@
+import crypto from 'node:crypto';
+import { ValidationError } from 'payload';
+/** `req.context` key that marks a write made by the plugin's sync. */
+export const OIDC_SYNC_CONTEXT = 'oidcSync';
+/** The fields the plugin adds to the auth collection. */
+export const OIDC_FIELDS = {
+    disabledAt: 'oidcDisabledAt',
+    linkable: 'oidcLinkable',
+    subject: 'oidcSubject',
+};
+/**
+ * The auth collection's Mongoose model. Session pushes and disables must be conditional, atomic
+ * updates, which Payload's adapter API can't express, so the plugin needs MongoDB.
+ */
+export const authCollectionModel = (payload, slug) => {
+    const model = payload.db
+        .collections?.[slug];
+    if (!model) {
+        throw new Error(`payload-oidc needs the MongoDB adapter (no model for "${slug}").`);
+    }
+    return model;
+};
+/**
+ * The auth collection's sanitized config. Typed loosely on purpose: an app's generated Payload
+ * types narrow collection slugs to its own, which a plugin can't name.
+ */
+export const authCollectionConfig = (payload, slug) => payload.collections[slug]
+    .config;
+/** A password hash and salt that no password matches. */
+export const unusablePassword = () => ({
+    hash: crypto.randomBytes(64).toString('hex'),
+    salt: crypto.randomBytes(32).toString('hex'),
+});
+/** The value the role field stores for `role` (or for no role). */
+export const roleValue = (options, role) => options.roleHasMany ? (role ? [role] : []) : (role ?? null);
+/**
+ * Disables a user: clears the role and every session and sets `oidcDisabledAt`, in one atomic
+ * update. Clearing sessions ends access on the next request, because Payload checks the session
+ * ID on every request. The break-glass account is never matched.
+ *
+ * @returns Whether a user was disabled.
+ */
+export const disableUser = async (payload, options, id, now, 
+/** Further conditions, such as "unchanged since it was read". */
+condition = {}) => {
+    const filter = { ...condition, _id: id };
+    if (options.breakGlassEmail)
+        filter.email = { $ne: options.breakGlassEmail };
+    const result = await authCollectionModel(payload, options.collection).updateOne(filter, {
+        $set: {
+            [OIDC_FIELDS.disabledAt]: now,
+            [options.roleField]: roleValue(options, undefined),
+            sessions: [],
+        },
+    });
+    return result.matchedCount > 0;
+};
+/**
+ * Links an existing, never-linked snapshot user to a provider subject, by email. One atomic,
+ * conditional update sets the subject, clears `oidcLinkable` and every session, and replaces the
+ * password with one nobody knows, so the old password and old sessions stop working.
+ *
+ * @returns Whether a user was linked.
+ */
+export const linkByEmail = async (payload, options, email, subject) => {
+    // The break-glass account keeps its password: it is never linked, even if the migration marked it.
+    if (options.breakGlassEmail && email === options.breakGlassEmail)
+        return false;
+    const result = await authCollectionModel(payload, options.collection).updateOne({
+        email,
+        [OIDC_FIELDS.linkable]: true,
+        [OIDC_FIELDS.subject]: { $exists: false },
+    }, {
+        $set: {
+            [OIDC_FIELDS.subject]: subject,
+            sessions: [],
+            ...unusablePassword(),
+            ...(options.verify ? { _verified: true } : {}),
+        },
+        $unset: { [OIDC_FIELDS.linkable]: '' },
+    });
+    return result.matchedCount > 0;
+};
+/**
+ * Writes the provider-owned fields of a linked user and clears `oidcDisabledAt`, as one update of
+ * just those paths. A Payload update would write back the whole document as it read it, sessions
+ * included, so a disable landing in between would be undone.
+ *
+ * @returns Whether the user (still linked to `subject`) was updated.
+ */
+export const writeManagedFields = async (payload, options, id, subject, fields, now) => {
+    const result = await authCollectionModel(payload, options.collection).updateOne({ _id: id, [OIDC_FIELDS.subject]: subject }, { $set: { ...fields, [OIDC_FIELDS.disabledAt]: null, updatedAt: now } });
+    return result.matchedCount > 0;
+};
+/** Marks a user Payload created as verified, for collections with `auth.verify`. */
+export const markVerified = async (payload, options, id) => {
+    if (!options.verify)
+        return;
+    await authCollectionModel(payload, options.collection).updateOne({ _id: id }, { $set: { _verified: true }, $unset: { _verificationToken: '' } });
+};
+/**
+ * Whether an error is a unique index refusing the write: MongoDB's duplicate-key error from a raw
+ * model write, the `ValidationError` db-mongodb turns it into for a Payload write (with the
+ * unique field as its path, and no cause), or a transaction's write conflict on the same key.
+ */
+export const isDuplicateKeyError = (error, uniqueFields = []) => {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const candidate = error;
+    if (candidate.code === 11000 || candidate.cause?.code === 11000)
+        return true;
+    // Inside a replica-set transaction a concurrent insert of the same key is a write conflict.
+    if (candidate.code === 112 || candidate.cause?.code === 112)
+        return true;
+    return Boolean(error instanceof ValidationError &&
+        candidate.data?.errors?.some((entry) => uniqueFields.includes(String(entry.path))));
+};
+/**
+ * Adds a session, conditional on the user still being linked to `subject` and not disabled, as one
+ * atomic update. A whole-document write (Payload's `addSessionToUser`) could undo a disable that
+ * landed between the read and the write; this can't. Expired sessions are dropped in the same
+ * update.
+ *
+ * @returns The new session ID, or `undefined` if the user was disabled or relinked meanwhile.
+ */
+export const pushSession = async (payload, options, id, subject, now) => {
+    const sid = crypto.randomUUID();
+    const session = {
+        createdAt: now,
+        expiresAt: new Date(now.getTime() + options.sessionSeconds * 1000),
+        id: sid,
+    };
+    const result = await authCollectionModel(payload, options.collection).updateOne({ _id: id, [OIDC_FIELDS.disabledAt]: null, [OIDC_FIELDS.subject]: subject }, [
+        {
+            $set: {
+                sessions: {
+                    $concatArrays: [
+                        {
+                            $filter: {
+                                cond: { $gt: ['$$this.expiresAt', now] },
+                                input: { $ifNull: ['$sessions', []] },
+                            },
+                        },
+                        [session],
+                    ],
+                },
+            },
+        },
+    ]);
+    return result.matchedCount > 0 ? sid : undefined;
+};
+/** One stored session, with the fields the refresh cap needs. */
+export const findSession = async (payload, options, id, sid) => {
+    const user = await authCollectionModel(payload, options.collection)
+        .findOne({ _id: id }, { [OIDC_FIELDS.disabledAt]: 1, sessions: 1 })
+        .lean();
+    const session = user?.sessions?.find((candidate) => candidate.id === sid);
+    if (!user || !session)
+        return undefined;
+    return { createdAt: new Date(session.createdAt), disabled: Boolean(user.oidcDisabledAt) };
+};