@signal58/payload-oidc 0.0.0 → 0.3.0

package/dist/endpoints.js

@@ -0,0 +1,193 @@
+import { generatePayloadCookie, parseCookies } from 'payload/shared';
+import { reconcileHealth } from './reconcile.js';
+import { removeUser } from './remove.js';
+import { authCollectionConfig } from './store.js';
+import { randomSignInSecrets } from './provider.js';
+import { completeSignIn } from './sign-in.js';
+import { openTransaction, safeReturnPath, sealTransaction, TRANSACTION_MAX_AGE_SECONDS, } from './transaction.js';
+/** Query parameter on the login page that carries a refusal code. */
+export const SIGN_IN_ERROR_PARAM = 'oidc_error';
+const noStore = { 'Cache-Control': 'private, no-store' };
+const notConfigured = () => Response.json({ error: { code: 'not_found', message: 'Single sign-on is not configured.' } }, { headers: noStore, status: 404 });
+const firstHeader = (req, name) => req.headers.get(name)?.split(',')[0]?.trim() || undefined;
+/**
+ * The public origin this sign-in runs on: the request's own origin when it is one of the allowed
+ * ones, so the transaction cookie and the callback stay on one host, otherwise the configured
+ * `serverURL`. Headers can only choose among allowed origins, never add one.
+ */
+const serverUrl = (req, options) => {
+    const configured = options.serverURL ?? req.payload.config.serverURL;
+    if (!configured) {
+        throw new Error('payload-oidc needs its serverURL option or serverURL in the Payload config.');
+    }
+    const fallback = new URL(configured).origin;
+    if (options.additionalServerURLs.length === 0)
+        return fallback;
+    const url = new URL(req.url ?? fallback, fallback);
+    const host = firstHeader(req, 'x-forwarded-host') ?? firstHeader(req, 'host') ?? url.host;
+    const protocol = firstHeader(req, 'x-forwarded-proto') ?? url.protocol.replace(/:$/, '');
+    const candidate = `${protocol}://${host}`.toLowerCase();
+    return ([fallback, ...options.additionalServerURLs].find((origin) => origin === candidate) ?? fallback);
+};
+const callbackPath = (req, options) => `${req.payload.config.routes.api}/${options.collection}/oidc/callback`;
+/** The redirect URI registered with the provider. */
+export const redirectUri = (req, options) => `${serverUrl(req, options)}${callbackPath(req, options)}`;
+const transactionCookieName = (req) => `${req.payload.config.cookiePrefix}-oidc`;
+const transactionCookie = (req, options, value, maxAge) => [
+    `${transactionCookieName(req)}=${value}`,
+    `Path=${callbackPath(req, options)}`,
+    `Max-Age=${maxAge}`,
+    'HttpOnly',
+    // Lax, not Strict: the provider's redirect back is a cross-site navigation, and Strict would
+    // drop the cookie on exactly that request.
+    'SameSite=Lax',
+    ...(serverUrl(req, options).startsWith('https:') ? ['Secure'] : []),
+].join('; ');
+const loginPath = (req) => {
+    const { admin, routes } = req.payload.config;
+    return `${routes.admin.replace(/\/+$/, '')}${admin.routes.login}`;
+};
+const redirect = (location, cookies = []) => {
+    const headers = new Headers({ ...noStore, Location: location });
+    for (const cookie of cookies)
+        headers.append('Set-Cookie', cookie);
+    return new Response(null, { headers, status: 302 });
+};
+const toLogin = (req, reason, cookies = []) => redirect(`${loginPath(req)}?${SIGN_IN_ERROR_PARAM}=${reason}`, cookies);
+export const createEndpoints = (options, client, clock = () => new Date()) => [
+    {
+        handler: async (req) => {
+            if (!options.enabled)
+                return notConfigured();
+            const requested = new URL(req.url ?? '', 'http://payload-oidc.invalid').searchParams.get('redirect');
+            const returnTo = safeReturnPath(requested, req.payload.config.routes.admin);
+            const secrets = await randomSignInSecrets();
+            let callback;
+            try {
+                callback = redirectUri(req, options);
+            }
+            catch (error) {
+                req.payload.logger.error({ err: error, msg: 'payload-oidc: no public origin configured' });
+                return toLogin(req, 'failed');
+            }
+            let location;
+            try {
+                location = await client.authorizationUrl({
+                    codeChallenge: secrets.codeChallenge,
+                    nonce: secrets.nonce,
+                    redirectUri: callback,
+                    state: secrets.state,
+                });
+            }
+            catch (error) {
+                req.payload.logger.error({ err: error, msg: 'payload-oidc: provider discovery failed' });
+                return toLogin(req, 'unavailable');
+            }
+            const sealed = sealTransaction(req.payload.secret, {
+                createdAt: clock().getTime(),
+                nonce: secrets.nonce,
+                returnTo,
+                state: secrets.state,
+                verifier: secrets.verifier,
+            });
+            return redirect(location.href, [
+                transactionCookie(req, options, sealed, TRANSACTION_MAX_AGE_SECONDS),
+            ]);
+        },
+        method: 'get',
+        path: '/oidc/authorize',
+    },
+    {
+        handler: async (req) => {
+            if (!options.enabled)
+                return notConfigured();
+            const clear = transactionCookie(req, options, '', 0);
+            const now = clock();
+            const transaction = openTransaction(req.payload.secret, parseCookies(req.headers).get(transactionCookieName(req)), now);
+            if (!transaction)
+                return toLogin(req, 'expired', [clear]);
+            // The registered redirect URI with the provider's parameters: behind a proxy, req.url
+            // carries the internal origin, which the token endpoint would reject.
+            const callbackUrl = new URL(redirectUri(req, options));
+            callbackUrl.search = new URL(req.url ?? '', 'http://payload-oidc.invalid').search;
+            let identity;
+            try {
+                identity = await client.exchange({
+                    callbackUrl,
+                    nonce: transaction.nonce,
+                    state: transaction.state,
+                    verifier: transaction.verifier,
+                });
+            }
+            catch (error) {
+                req.payload.logger.warn({ err: error, msg: 'payload-oidc: sign-in failed at the provider' });
+                return toLogin(req, 'provider', [clear]);
+            }
+            let outcome;
+            try {
+                outcome = await completeSignIn(req.payload, options, identity, now);
+            }
+            catch (error) {
+                req.payload.logger.error({ err: error, msg: 'payload-oidc: sign-in failed in the CMS' });
+                return toLogin(req, 'failed', [clear]);
+            }
+            if (outcome.kind === 'refused') {
+                req.payload.logger.info({ msg: 'payload-oidc: sign-in refused', reason: outcome.reason });
+                return toLogin(req, outcome.reason, [clear]);
+            }
+            const authConfig = authCollectionConfig(req.payload, options.collection).auth;
+            const sessionCookie = generatePayloadCookie({
+                collectionAuthConfig: authConfig,
+                cookiePrefix: req.payload.config.cookiePrefix,
+                token: outcome.token,
+            });
+            return redirect(transaction.returnTo, [clear, sessionCookie]);
+        },
+        method: 'get',
+        path: '/oidc/callback',
+    },
+    {
+        // Removes a disabled user: deleted if nothing refers to them, otherwise anonymised. POST
+        // only, and the app decides who may (`removeAccess`, default nobody).
+        handler: async (req) => {
+            if (!options.enabled)
+                return notConfigured();
+            if (!req.user || !(await options.removeAccess(req))) {
+                return Response.json({ error: { code: 'forbidden', message: 'You may not remove users.' } }, { headers: noStore, status: req.user ? 403 : 401 });
+            }
+            const id = req.routeParams?.id;
+            if (typeof id !== 'string' && typeof id !== 'number')
+                return notConfigured();
+            const outcome = await removeUser(req.payload, options, id);
+            if (outcome.kind === 'refused') {
+                const messages = {
+                    break_glass: 'The break-glass account is never removed.',
+                    not_disabled: 'Only a disabled user can be removed: remove them at the identity provider first.',
+                    not_found: 'No such user.',
+                };
+                return Response.json({ error: { code: outcome.reason, message: messages[outcome.reason] } }, { headers: noStore, status: outcome.reason === 'not_found' ? 404 : 409 });
+            }
+            req.payload.logger.info({
+                by: req.user.id,
+                id,
+                msg: `payload-oidc: user ${outcome.kind}`,
+            });
+            return Response.json({ result: outcome.kind }, { headers: noStore });
+        },
+        method: 'post',
+        path: '/oidc/remove/:id',
+    },
+    {
+        // For an uptime check (Gatus): 200 while the last successful reconcile is recent, 503 once it
+        // isn't, so a failing reconcile (an expired token, a renamed group) alerts instead of silently
+        // stopping removals. It says nothing about users.
+        handler: async (req) => {
+            if (!options.enabled || !options.reconcile)
+                return notConfigured();
+            const health = await reconcileHealth(req.payload, options, clock());
+            return Response.json(health, { headers: noStore, status: health.healthy ? 200 : 503 });
+        },
+        method: 'get',
+        path: '/oidc/reconcile/health',
+    },
+];

package/dist/exports/client.d.ts

@@ -0,0 +1,8 @@
+/**
+ * "Remove user" in the sidebar of a disabled user. The endpoint decides who may (the app's
+ * `removeAccess`) and whether the user is deleted or anonymised. With `hidePasswordChange`
+ * (single sign-on on, password sign-in off) it also hides "Change Password" on every user.
+ */
+export declare const RemoveUserButton: ({ hidePasswordChange, }: {
+    hidePasswordChange?: boolean;
+}) => import("react/jsx-runtime").JSX.Element | null;

package/dist/exports/client.js

@@ -0,0 +1,45 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, toast, useConfig, useDocumentInfo, useFormFields } from '@payloadcms/ui';
+import { useState } from 'react';
+/**
+ * Payload shows "Change Password" to anyone who may update the user, and has no option to hide
+ * it; the server refuses the change regardless (`beforeOperation`).
+ */
+const HIDE_PASSWORD_CHANGE = '#change-password { display: none; }';
+/**
+ * "Remove user" in the sidebar of a disabled user. The endpoint decides who may (the app's
+ * `removeAccess`) and whether the user is deleted or anonymised. With `hidePasswordChange`
+ * (single sign-on on, password sign-in off) it also hides "Change Password" on every user.
+ */
+export const RemoveUserButton = ({ hidePasswordChange = false, }) => {
+    const { collectionSlug, id } = useDocumentInfo();
+    const disabledAt = useFormFields(([fields]) => fields.oidcDisabledAt?.value);
+    const { config: { routes }, } = useConfig();
+    const [busy, setBusy] = useState(false);
+    const hide = hidePasswordChange ? _jsx("style", { children: HIDE_PASSWORD_CHANGE }) : null;
+    if (!id || !collectionSlug || !disabledAt)
+        return hide;
+    const remove = async () => {
+        const confirmed = window.confirm('Remove this disabled user? If nothing refers to them they are deleted; otherwise their name and email are replaced so bylines still resolve. This can’t be undone.');
+        if (!confirmed)
+            return;
+        setBusy(true);
+        try {
+            const response = await fetch(
+            // Relative, like Payload's own admin calls: the session cookie belongs to this host.
+            `${routes.api}/${collectionSlug}/oidc/remove/${encodeURIComponent(String(id))}`, { credentials: 'include', method: 'POST' });
+            const body = (await response.json().catch(() => ({})));
+            if (!response.ok) {
+                toast.error(body.error?.message ?? 'The user could not be removed.');
+                return;
+            }
+            toast.success(body.result === 'deleted' ? 'User deleted.' : 'User anonymised.');
+            window.location.assign(`${routes.admin}/collections/${collectionSlug}`);
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    return (_jsxs("div", { className: "field-type payload-oidc-remove", style: { marginBottom: 'var(--base)' }, children: [hide, _jsx(Button, { buttonStyle: "secondary", disabled: busy, onClick: remove, size: "medium", children: "Remove user" })] }));
+};

package/dist/exports/rsc.d.ts

@@ -0,0 +1,9 @@
+import type { Payload } from 'payload';
+/**
+ * The single sign-on button above the login form. While password sign-in is off it also hides
+ * the password form; the server refuses password operations regardless (`beforeOperation`).
+ */
+export declare const OidcLoginButton: ({ payload, searchParams, }: {
+    payload: Payload;
+    searchParams?: Record<string, string | string[] | undefined>;
+}) => import("react/jsx-runtime").JSX.Element | null;

package/dist/exports/rsc.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { SIGN_IN_ERROR_PARAM } from '../endpoints.js';
+import { PUBLIC_STATE_KEY } from '../plugin.js';
+const MESSAGES = {
+    account_conflict: 'An account with this email already exists and can’t be linked. Ask an administrator.',
+    disabled: 'This account is disabled. Ask an administrator.',
+    email_not_verified: 'Your email address isn’t verified with the identity provider.',
+    expired: 'The sign-in took too long or was started in another window. Try again.',
+    failed: 'The CMS couldn’t complete the sign-in. Try again, or ask an administrator.',
+    no_role: 'Your account has no access to this CMS. Ask an administrator.',
+    provider: 'The identity provider didn’t complete the sign-in. Try again.',
+    unavailable: 'The identity provider can’t be reached right now. Try again shortly.',
+};
+const firstValue = (value) => typeof value === 'string' ? value : Array.isArray(value) ? firstValue(value[0]) : undefined;
+/**
+ * The single sign-on button above the login form. While password sign-in is off it also hides
+ * the password form; the server refuses password operations regardless (`beforeOperation`).
+ */
+export const OidcLoginButton = ({ payload, searchParams, }) => {
+    const state = payload.config.custom?.[PUBLIC_STATE_KEY];
+    if (!state?.enabled)
+        return null;
+    const error = firstValue(searchParams?.[SIGN_IN_ERROR_PARAM]);
+    const message = error && Object.hasOwn(MESSAGES, error) ? MESSAGES[error] : undefined;
+    const redirect = firstValue(searchParams?.redirect);
+    const href = redirect
+        ? `${state.authorizePath}?redirect=${encodeURIComponent(redirect)}`
+        : state.authorizePath;
+    return (_jsxs("div", { className: "payload-oidc", style: { marginBottom: 'var(--base)' }, children: [message ? (_jsx("p", { className: "payload-oidc__error", role: "alert", style: { color: 'var(--theme-error-500)' }, children: message })) : null, _jsx("a", { className: "btn btn--style-primary btn--size-large", href: href, style: { display: 'block', textAlign: 'center', width: '100%' }, children: state.buttonLabel }), state.passwordLogin ? null : _jsx("style", { children: '.login__form { display: none; }' })] }));
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { oidcPlugin, PUBLIC_STATE_KEY, syncWriteOnly, type OidcPublicState } from './plugin.js';
+export { roleForGroups, roleTableGroups, type OidcPluginOptions, type ReconcileMember, type ReconcileSource, type RoleTable, } from './options.js';
+export { OIDC_FIELDS, OIDC_SYNC_CONTEXT } from './store.js';
+export type { SignInRefusal } from './sign-in.js';
+export { authentikSource } from './sources/authentik.js';
+export { reconcileUsers, RECONCILE_HEARTBEAT_KEY } from './reconcile.js';
+export { RECONCILE_TASK_SLUG } from './reconcile-task.js';
+export { findUserReferences, removeUser } from './remove.js';
+export { clearLinkingSnapshot, takeLinkingSnapshot, type OidcMigrationArgs, type OidcMigrationOptions, } from './migration.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { oidcPlugin, PUBLIC_STATE_KEY, syncWriteOnly } from './plugin.js';
+export { roleForGroups, roleTableGroups, } from './options.js';
+export { OIDC_FIELDS, OIDC_SYNC_CONTEXT } from './store.js';
+export { authentikSource } from './sources/authentik.js';
+export { reconcileUsers, RECONCILE_HEARTBEAT_KEY } from './reconcile.js';
+export { RECONCILE_TASK_SLUG } from './reconcile-task.js';
+export { findUserReferences, removeUser } from './remove.js';
+export { clearLinkingSnapshot, takeLinkingSnapshot, } from './migration.js';

package/dist/migration.d.ts

@@ -0,0 +1,47 @@
+import type { Payload } from 'payload';
+/**
+ * What the helpers need from a migration's arguments (`MigrateUpArgs` or `MigrateDownArgs` from
+ * `@payloadcms/db-mongodb`): pass those straight through.
+ */
+export type OidcMigrationArgs = {
+    payload: Payload;
+    /** The migration's MongoDB session, when `payload migrate` runs it in a transaction. */
+    session?: unknown;
+};
+export type OidcMigrationOptions = {
+    /** The auth collection the plugin is on. */
+    collection?: string;
+};
+/**
+ * For an app's migration, before sign-in is turned on: marks every existing user that isn't
+ * linked yet `oidcLinkable`, so each can be linked once, by verified email, until
+ * `linkByEmailUntil`. Users created later (at their first sign-in) are never linkable, so a new
+ * provider account can never claim one of them by email.
+ *
+ * It builds the collection's indexes first, among them the sparse unique `oidcSubject` index:
+ * Mongoose starts that build in the background when `payload migrate` boots, and writing in the
+ * migration's transaction while it runs fails with a transient catalog-change error. The build is
+ * idempotent and runs outside the transaction. **Call this first in the migration**, before any
+ * other operation in its transaction, on any collection: a transaction reads from the moment of
+ * its first operation, so after a build that had work to do its write to the collection fails
+ * (a write conflict, and a rerun of the migration then passes). It refuses, before any change, a
+ * user that stores `oidcSubject: null`, which the sparse index would still index (and collide
+ * on). A user with an `oidcSubject` is already linked and left alone, so a rerun is a no-op.
+ *
+ * ```ts
+ * export async function up(args: MigrateUpArgs): Promise<void> {
+ *   await takeLinkingSnapshot(args)
+ * }
+ * ```
+ *
+ * @returns How many users were marked.
+ */
+export declare const takeLinkingSnapshot: ({ payload, session }: OidcMigrationArgs, { collection: slug }?: OidcMigrationOptions) => Promise<number>;
+/**
+ * The `down` of {@link takeLinkingSnapshot}: clears every `oidcLinkable` mark. Links already made
+ * (`oidcSubject`) and disables (`oidcDisabledAt`) stay: they are the provider's record of who
+ * these users are, and with the plugin off they do nothing.
+ *
+ * @returns How many marks were cleared.
+ */
+export declare const clearLinkingSnapshot: ({ payload, session }: OidcMigrationArgs, { collection: slug }?: OidcMigrationOptions) => Promise<number>;

package/dist/migration.js

@@ -0,0 +1,89 @@
+import { OIDC_FIELDS } from './store.js';
+/** The collection's MongoDB collection, written directly, and its compiled model. */
+const usersCollection = (payload, slug) => {
+    const db = payload.db;
+    const model = db.collections?.[slug];
+    const name = model?.collection?.name;
+    const database = db.connection?.db;
+    if (!model || !name || !database) {
+        throw new Error(`payload-oidc: the migration needs the MongoDB adapter (no model for "${slug}").`);
+    }
+    const config = payload.collections[slug]?.config;
+    const hasPluginFields = config?.fields.some((field) => field.name === OIDC_FIELDS.subject);
+    if (!hasPluginFields) {
+        throw new Error(`payload-oidc: "${slug}" has no ${OIDC_FIELDS.subject} field; add the plugin to the config before this migration runs.`);
+    }
+    // Direct writes: through the model, Mongoose would also stamp `updatedAt` on every user.
+    return { collection: database.collection(name), model };
+};
+/** MongoDB's write conflict, which a transaction gets when the collection changed under it. */
+const isWriteConflict = (error) => {
+    const candidate = error;
+    return candidate?.code === 112 || candidate?.hasErrorLabel?.('TransientTransactionError') === true;
+};
+/**
+ * For an app's migration, before sign-in is turned on: marks every existing user that isn't
+ * linked yet `oidcLinkable`, so each can be linked once, by verified email, until
+ * `linkByEmailUntil`. Users created later (at their first sign-in) are never linkable, so a new
+ * provider account can never claim one of them by email.
+ *
+ * It builds the collection's indexes first, among them the sparse unique `oidcSubject` index:
+ * Mongoose starts that build in the background when `payload migrate` boots, and writing in the
+ * migration's transaction while it runs fails with a transient catalog-change error. The build is
+ * idempotent and runs outside the transaction. **Call this first in the migration**, before any
+ * other operation in its transaction, on any collection: a transaction reads from the moment of
+ * its first operation, so after a build that had work to do its write to the collection fails
+ * (a write conflict, and a rerun of the migration then passes). It refuses, before any change, a
+ * user that stores `oidcSubject: null`, which the sparse index would still index (and collide
+ * on). A user with an `oidcSubject` is already linked and left alone, so a rerun is a no-op.
+ *
+ * ```ts
+ * export async function up(args: MigrateUpArgs): Promise<void> {
+ *   await takeLinkingSnapshot(args)
+ * }
+ * ```
+ *
+ * @returns How many users were marked.
+ */
+export const takeLinkingSnapshot = async ({ payload, session }, { collection: slug = 'users' } = {}) => {
+    const { collection, model } = usersCollection(payload, slug);
+    // Outside the transaction, like the build: a read in it would hold the collection until commit.
+    const nullSubjects = await collection.countDocuments({ [OIDC_FIELDS.subject]: { $type: 'null' } }, {});
+    if (nullSubjects > 0) {
+        throw new Error(`payload-oidc: a user of "${slug}" stores ${OIDC_FIELDS.subject} as null.`);
+    }
+    try {
+        await model.createIndexes();
+    }
+    catch (error) {
+        // Every index on the collection is built here, not only the plugin's.
+        throw new Error(`payload-oidc: building the indexes of "${slug}" failed: ${String(error)}`, {
+            cause: error,
+        });
+    }
+    let modifiedCount;
+    try {
+        ;
+        ({ modifiedCount } = await collection.updateMany({ [OIDC_FIELDS.linkable]: { $exists: false }, [OIDC_FIELDS.subject]: { $exists: false } }, { $set: { [OIDC_FIELDS.linkable]: true } }, { session }));
+    }
+    catch (error) {
+        if (!isWriteConflict(error))
+            throw error;
+        throw new Error(`payload-oidc: the linking snapshot conflicted with the index build on "${slug}". Call takeLinkingSnapshot before any other operation in the migration, or run the migration again.`, { cause: error });
+    }
+    payload.logger.info(`payload-oidc: marked ${modifiedCount} users of "${slug}" linkable.`);
+    return modifiedCount;
+};
+/**
+ * The `down` of {@link takeLinkingSnapshot}: clears every `oidcLinkable` mark. Links already made
+ * (`oidcSubject`) and disables (`oidcDisabledAt`) stay: they are the provider's record of who
+ * these users are, and with the plugin off they do nothing.
+ *
+ * @returns How many marks were cleared.
+ */
+export const clearLinkingSnapshot = async ({ payload, session }, { collection: slug = 'users' } = {}) => {
+    const { collection } = usersCollection(payload, slug);
+    const { modifiedCount } = await collection.updateMany({ [OIDC_FIELDS.linkable]: { $exists: true } }, { $unset: { [OIDC_FIELDS.linkable]: '' } }, { session });
+    payload.logger.info(`payload-oidc: cleared ${modifiedCount} linkable marks on "${slug}".`);
+    return modifiedCount;
+};

package/dist/options.d.ts

@@ -0,0 +1,172 @@
+import type { PayloadRequest, TaskConfig } from 'payload';
+/**
+ * Role name → the provider groups that grant it, **highest role first**. A user in groups for
+ * several roles gets the first one listed, and a user in none of them gets no role.
+ */
+export type RoleTable = Readonly<Record<string, readonly string[]>>;
+/** Hooks for the reconcile task's schedule (Payload's `ScheduleConfig['hooks']`). */
+export type ReconcileScheduleHooks = NonNullable<NonNullable<NonNullable<TaskConfig['schedule']>[number]['hooks']>>;
+/** One member of a role-table group, as the provider's directory reports it. */
+export type ReconcileMember = {
+    /** Whether the provider still lets this user sign in. Inactive members count as removed. */
+    active: boolean;
+    /** The same value as the ID token's `sub` for this user. */
+    subject: string;
+};
+/** Reads the current members of every role-table group from the provider. */
+export type ReconcileSource = {
+    /**
+     * Returns the members of each group. Must throw if any group can't be read: reconcile only acts
+     * on a complete answer.
+     */
+    fetchGroupMembers: (groups: readonly string[]) => Promise<Map<string, ReconcileMember[]>>;
+    /** How often reconcile runs, as a cron expression. */
+    cron: string;
+    /** The Payload jobs queue the reconcile task runs on. The app must auto-run this queue. */
+    queue: string;
+};
+export type OidcPluginOptions = {
+    /**
+     * Reopens password sign-in, for the `breakGlassEmail` account and, until `linkByEmailUntil`,
+     * for users the migration marked `oidcLinkable` who haven't linked yet.
+     */
+    passwordLogin?: boolean;
+    /** Text of the admin sign-in button. */
+    buttonLabel?: string;
+    /**
+     * The one account that may use a password while `passwordLogin` is on, and that sync and
+     * reconcile never disable. Compared case-insensitively.
+     */
+    breakGlassEmail?: string;
+    clientId?: string;
+    clientSecret?: string;
+    /** The auth collection staff sign in to. */
+    collection?: string;
+    /** Names of the profile fields the provider owns. */
+    fields?: {
+        firstName?: string;
+        lastName?: string;
+    };
+    /**
+     * The provider's issuer URL. With it, `clientId` or `clientSecret` unset, the plugin is off:
+     * nothing changes and password sign-in works as before.
+     */
+    issuer?: string;
+    /** Written to `lastName` when the provider sends no `family_name`. */
+    lastNamePlaceholder?: string;
+    /**
+     * Until this date (ISO 8601), a first sign-in may link an existing user that the app's
+     * migration marked `oidcLinkable`, by verified email. After it, linking stops.
+     */
+    linkByEmailUntil?: string;
+    /** Reconcile source (optional). Without one, removal applies at the next sign-in only. */
+    reconcile?: ReconcileSource;
+    /** The largest share of linked users one reconcile run may disable (at least one always may). */
+    reconcileMaxDisableShare?: number;
+    /** How old the last successful reconcile may be before the health endpoint reports it, in minutes. */
+    reconcileHeartbeatMaxMinutes?: number;
+    /** Fields an anonymised user keeps (by default every profile field is cleared). */
+    keepOnRemove?: string[];
+    /**
+     * Hooks for the reconcile schedule. A `beforeSchedule` hook runs after stale runs are released
+     * (`reconcileStaleAfterMinutes`), in place of Payload's default rule.
+     */
+    reconcileScheduleHooks?: ReconcileScheduleHooks;
+    /**
+     * A reconcile run still processing after this many minutes was cut off, for example by a deploy
+     * that replaced the process mid-run, and would block the queue for good. Before each schedule,
+     * such runs are marked failed with Payload's own cancel, so a new one can be queued. A live run
+     * therefore stops, before changing anything, if the source hasn't answered within 80% of this.
+     * `false` turns both off. At least 1.
+     */
+    reconcileStaleAfterMinutes?: number | false;
+    /** Who may remove a disabled user. Defaults to nobody, so an app must decide. */
+    removeAccess?: (req: PayloadRequest) => boolean | Promise<boolean>;
+    roles: {
+        /** The role field on the auth collection. */
+        field: string;
+        /** Whether the role field stores a list (a `hasMany` select) or a single value. */
+        hasMany?: boolean;
+        table: RoleTable;
+    };
+    /**
+     * The public origin the callback is registered under (`<origin>/api/<collection>/oidc/callback`).
+     * Defaults to Payload's `serverURL`; set it when that is unset, as some apps do in development.
+     */
+    serverURL?: string;
+    /**
+     * Further public origins the app is also served from (each registered with the provider as a
+     * callback too). Sign-in uses the request's own origin when it is one of these, so its cookie and
+     * callback stay on one host; any other origin falls back to `serverURL`.
+     */
+    additionalServerURLs?: string[];
+    /** Scopes requested at sign-in. */
+    scopes?: string[];
+    /** Idle timeout: the collection's `tokenExpiration`, in hours. */
+    sessionHours?: number;
+    /** Absolute cap on a session from sign-in, in hours. Refresh is refused after it. */
+    sessionMaxHours?: number;
+    /**
+     * Allows an `http:` issuer. Only for a provider on the local machine in development or tests;
+     * refused when `NODE_ENV` is `production`.
+     */
+    allowInsecureIssuer?: boolean;
+};
+export type ResolvedOidcOptions = {
+    allowInsecureIssuer: boolean;
+    breakGlassEmail?: string;
+    buttonLabel: string;
+    clientId: string;
+    clientSecret: string;
+    collection: string;
+    enabled: boolean;
+    firstNameField: string;
+    issuer: string;
+    lastNameField: string;
+    lastNamePlaceholder: string;
+    linkByEmailUntil?: Date;
+    passwordLogin: boolean;
+    reconcile?: ReconcileSource;
+    keepOnRemove: string[];
+    reconcileScheduleHooks?: ReconcileScheduleHooks;
+    /** Unset when releasing stale reconcile runs is off. */
+    reconcileStaleAfterSeconds?: number;
+    reconcileHeartbeatMaxSeconds: number;
+    reconcileMaxDisableShare: number;
+    removeAccess: (req: PayloadRequest) => boolean | Promise<boolean>;
+    roleField: string;
+    roleHasMany: boolean;
+    roleTable: RoleTable;
+    scopes: string[];
+    sessionMaxSeconds: number;
+    sessionSeconds: number;
+    /** The public origin the callback is registered under, if not Payload's `serverURL`. */
+    serverURL?: string;
+    /** Further allowed public origins, normalised. */
+    additionalServerURLs: string[];
+    /** Whether the collection uses `auth.verify`; set by the plugin from the collection config. */
+    verify: boolean;
+    /** The collection's `loginWithUsername` setting; set by the plugin from the collection config. */
+    loginWithUsername?: {
+        allowEmailLogin: boolean;
+    };
+};
+/**
+ * Validates the options and fills in defaults. Throws for a configuration that can't be safe,
+ * so a mistake fails at startup rather than at someone's first sign-in.
+ */
+export declare const resolveOptions: (options: OidcPluginOptions) => ResolvedOidcOptions;
+/**
+ * The role a user's groups grant: the first role in the table with a matching group.
+ *
+ * @param table - The role table, highest role first.
+ * @param groups - The `groups` claim (or a reconcile member's groups); anything else is no role.
+ * @returns The role, or `undefined` for none.
+ */
+export declare const roleForGroups: (table: RoleTable, groups: unknown) => string | undefined;
+/** Every group named in the role table, once. */
+export declare const roleTableGroups: (table: RoleTable) => string[];
+/** Whether an email is the break-glass account's. */
+export declare const isBreakGlassEmail: (options: ResolvedOidcOptions, email: unknown) => boolean;
+/** Whether linking by email is still allowed at `now`. */
+export declare const canLinkByEmail: (options: ResolvedOidcOptions, now: Date) => boolean;