@signal58/payload-oidc 0.0.0-stage → 0.2.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,8 @@
+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';

package/dist/index.js

@@ -0,0 +1,7 @@
+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';

package/dist/options.d.ts

@@ -0,0 +1,159 @@
+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, such as one that releases jobs a deploy cut off. */
+    reconcileScheduleHooks?: ReconcileScheduleHooks;
+    /** 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;
+    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;

package/dist/options.js

@@ -0,0 +1,126 @@
+const positiveHours = (value, fallback, name) => {
+    const hours = value ?? fallback;
+    if (!Number.isFinite(hours) || hours <= 0) {
+        throw new Error(`payload-oidc: ${name} must be a positive number of hours.`);
+    }
+    return hours;
+};
+const toOrigin = (url, name) => {
+    try {
+        return new URL(url.trim()).origin;
+    }
+    catch {
+        throw new Error(`payload-oidc: ${name} must be absolute URLs.`);
+    }
+};
+const shareBetweenZeroAndOne = (share) => {
+    if (!Number.isFinite(share) || share < 0 || share > 1) {
+        throw new Error('payload-oidc: reconcileMaxDisableShare must be between 0 and 1.');
+    }
+    return share;
+};
+/**
+ * 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 const resolveOptions = (options) => {
+    const issuer = options.issuer?.trim() ?? '';
+    const clientId = options.clientId?.trim() ?? '';
+    const clientSecret = options.clientSecret ?? '';
+    const enabled = Boolean(issuer && clientId && clientSecret);
+    const roleTable = options.roles?.table ?? {};
+    if (!options.roles?.field)
+        throw new Error('payload-oidc: roles.field is required.');
+    if (Object.keys(roleTable).length === 0) {
+        throw new Error('payload-oidc: roles.table needs at least one role.');
+    }
+    for (const [role, groups] of Object.entries(roleTable)) {
+        if (!Array.isArray(groups) || groups.length === 0 || groups.some((group) => !group)) {
+            throw new Error(`payload-oidc: role "${role}" needs at least one group.`);
+        }
+    }
+    const sessionHours = positiveHours(options.sessionHours, 8, 'sessionHours');
+    const sessionMaxHours = positiveHours(options.sessionMaxHours, 12, 'sessionMaxHours');
+    if (sessionMaxHours < sessionHours) {
+        throw new Error('payload-oidc: sessionMaxHours must be at least sessionHours.');
+    }
+    let linkByEmailUntil;
+    if (options.linkByEmailUntil) {
+        linkByEmailUntil = new Date(options.linkByEmailUntil);
+        if (Number.isNaN(linkByEmailUntil.getTime())) {
+            throw new Error('payload-oidc: linkByEmailUntil must be an ISO 8601 date.');
+        }
+    }
+    if (enabled) {
+        const url = new URL(issuer);
+        if (url.protocol !== 'https:') {
+            if (!options.allowInsecureIssuer || process.env.NODE_ENV === 'production') {
+                throw new Error('payload-oidc: the issuer must use https.');
+            }
+        }
+    }
+    const breakGlassEmail = options.breakGlassEmail?.trim().toLowerCase() || undefined;
+    if (enabled && options.passwordLogin && !breakGlassEmail) {
+        throw new Error('payload-oidc: passwordLogin needs breakGlassEmail.');
+    }
+    return {
+        allowInsecureIssuer: Boolean(options.allowInsecureIssuer),
+        breakGlassEmail,
+        buttonLabel: options.buttonLabel ?? 'Sign in with single sign-on',
+        clientId,
+        clientSecret,
+        collection: options.collection ?? 'users',
+        enabled,
+        firstNameField: options.fields?.firstName ?? 'firstName',
+        issuer,
+        lastNameField: options.fields?.lastName ?? 'lastName',
+        lastNamePlaceholder: options.lastNamePlaceholder ?? '-',
+        linkByEmailUntil,
+        passwordLogin: Boolean(options.passwordLogin),
+        reconcile: options.reconcile,
+        keepOnRemove: options.keepOnRemove ?? [],
+        reconcileScheduleHooks: options.reconcileScheduleHooks,
+        reconcileHeartbeatMaxSeconds: Math.round(positiveHours((options.reconcileHeartbeatMaxMinutes ?? 45) / 60, 0.75, 'reconcileHeartbeatMaxMinutes') * 3600),
+        reconcileMaxDisableShare: shareBetweenZeroAndOne(options.reconcileMaxDisableShare ?? 0.25),
+        removeAccess: options.removeAccess ?? (() => false),
+        roleField: options.roles.field,
+        roleHasMany: options.roles.hasMany ?? true,
+        roleTable,
+        scopes: options.scopes ?? ['openid', 'email', 'profile'],
+        sessionMaxSeconds: Math.round(sessionMaxHours * 3600),
+        sessionSeconds: Math.round(sessionHours * 3600),
+        serverURL: options.serverURL ? toOrigin(options.serverURL, 'serverURL') : undefined,
+        additionalServerURLs: (options.additionalServerURLs ?? [])
+            .map((url) => url.trim())
+            .filter(Boolean)
+            .map((url) => toOrigin(url, 'additionalServerURLs')),
+        verify: false,
+    };
+};
+/**
+ * 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 const roleForGroups = (table, groups) => {
+    if (!Array.isArray(groups))
+        return undefined;
+    const names = new Set(groups.filter((group) => typeof group === 'string'));
+    for (const [role, roleGroups] of Object.entries(table)) {
+        if (roleGroups.some((group) => names.has(group)))
+            return role;
+    }
+    return undefined;
+};
+/** Every group named in the role table, once. */
+export const roleTableGroups = (table) => [
+    ...new Set(Object.values(table).flat()),
+];
+/** Whether an email is the break-glass account's. */
+export const isBreakGlassEmail = (options, email) => Boolean(options.breakGlassEmail &&
+    typeof email === 'string' &&
+    email.trim().toLowerCase() === options.breakGlassEmail);
+/** Whether linking by email is still allowed at `now`. */
+export const canLinkByEmail = (options, now) => Boolean(options.linkByEmailUntil && now < options.linkByEmailUntil);

package/dist/plugin.d.ts

@@ -0,0 +1,25 @@
+import type { FieldAccess, Plugin } from 'payload';
+import { type OidcPluginOptions } from './options.js';
+import { type ProviderClient } from './provider.js';
+/** Key under `config.custom` with the plugin's public (non-secret) state, for the login view. */
+export declare const PUBLIC_STATE_KEY = "payloadOidc";
+export type OidcPublicState = {
+    authorizePath: string;
+    buttonLabel: string;
+    enabled: boolean;
+    passwordLogin: boolean;
+};
+/** Field access that lets only the plugin's sync write a field. */
+export declare const syncWriteOnly: FieldAccess;
+/**
+ * Signs staff in to the Payload admin through an OpenID Connect provider, which becomes the source
+ * of truth for the auth collection's users and roles.
+ *
+ * With the issuer, client ID or client secret unset, the plugin adds its fields and inert
+ * endpoints so the schema stays the same, and changes nothing else: password sign-in works as
+ * before.
+ */
+export declare const oidcPlugin: (pluginOptions: OidcPluginOptions, testing?: {
+    client?: ProviderClient;
+    clock?: () => Date;
+}) => Plugin;