@signal58/payload-oidc 0.0.0 → 0.3.0

package/dist/options.js

@@ -0,0 +1,137 @@
+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 atLeastOneMinute = (value, fallback, name) => {
+    const minutes = value ?? fallback;
+    if (!Number.isFinite(minutes) || minutes < 1) {
+        throw new Error(`payload-oidc: ${name} must be a number of minutes, at least 1.`);
+    }
+    return minutes;
+};
+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,
+        reconcileStaleAfterSeconds: options.reconcileStaleAfterMinutes === false
+            ? undefined
+            : Math.round(atLeastOneMinute(options.reconcileStaleAfterMinutes, 10, 'reconcileStaleAfterMinutes') *
+                60),
+        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, type 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;

package/dist/plugin.js

@@ -0,0 +1,248 @@
+import { validations, } from 'payload';
+import { createBeforeOperationHook, createRefreshHook, OIDC_REFUSAL_NAME } from './before-operation.js';
+import { createEndpoints } from './endpoints.js';
+import { createReconcileTask } from './reconcile-task.js';
+import { resolveOptions } from './options.js';
+import { createProviderClient } from './provider.js';
+import { OIDC_FIELDS, OIDC_SYNC_CONTEXT } from './store.js';
+/** Key under `config.custom` with the plugin's public (non-secret) state, for the login view. */
+export const PUBLIC_STATE_KEY = 'payloadOidc';
+/** Field access that lets only the plugin's sync write a field. */
+export const syncWriteOnly = ({ req }) => req.context?.[OIDC_SYNC_CONTEXT] === true;
+const denyField = () => false;
+const pluginFields = (options) => [
+    {
+        name: OIDC_FIELDS.subject,
+        type: 'text',
+        label: 'Identity provider subject',
+        // Sparse unique index: the field is unset, never null, when there is no link.
+        unique: true,
+        index: true,
+        access: { create: denyField, update: denyField },
+        admin: {
+            description: 'The identity provider subject this account is linked to.',
+            position: 'sidebar',
+            readOnly: true,
+        },
+    },
+    {
+        name: OIDC_FIELDS.disabledAt,
+        type: 'date',
+        label: 'Disabled by identity provider',
+        access: { create: denyField, update: denyField },
+        admin: {
+            date: { pickerAppearance: 'dayAndTime' },
+            description: 'Set when the identity provider removed this account’s role.',
+            position: 'sidebar',
+            readOnly: true,
+        },
+    },
+    {
+        name: OIDC_FIELDS.linkable,
+        type: 'checkbox',
+        access: { create: denyField, update: denyField },
+        admin: { hidden: true },
+    },
+    {
+        // "Remove user" on a disabled user; also hides "Change Password" while passwords are off.
+        // Stores nothing.
+        name: 'oidcRemove',
+        type: 'ui',
+        admin: {
+            components: {
+                Field: {
+                    clientProps: { hidePasswordChange: options.enabled && !options.passwordLogin },
+                    path: '@signal58/payload-oidc/client#RemoveUserButton',
+                },
+            },
+            position: 'sidebar',
+        },
+    },
+];
+const hasField = (fields, name) => fields.some((field) => ('name' in field && field.name === name) ||
+    ((field.type === 'row' || field.type === 'collapsible') && hasField(field.fields, name)));
+/**
+ * Copies the fields, replacing each named top-level, row or collapsible data field with
+ * `replace(field)`. Copies, never edits: a field config the host shares with another collection
+ * must not change there too.
+ */
+const mapNamedFields = (fields, names, found, replace) => fields.map((field) => {
+    if ('name' in field && names.has(field.name)) {
+        found.add(field.name);
+        return replace(field);
+    }
+    if (field.type === 'row' || field.type === 'collapsible') {
+        return { ...field, fields: mapNamedFields(field.fields, names, found, replace) };
+    }
+    return field;
+});
+/** Gives a field `update` access that only sync passes. */
+const syncOnlyUpdate = (field) => {
+    const access = field.access;
+    return { ...field, access: { ...access, update: syncWriteOnly } };
+};
+/** No role: an empty list, or no single value. */
+const isNoRole = (value) => Array.isArray(value) ? value.length === 0 : value === null || value === undefined || value === '';
+/**
+ * Lets a disabled user have no role. Disabling clears the role, so with a `required` role field
+ * every later save of that user, such as an admin editing a profile field, would fail. No role
+ * passes only while `oidcDisabledAt` is set; anything else goes to the field's own `validate`, or
+ * to Payload's default for its type (known options, `required` and so on).
+ */
+const allowNoRoleWhenDisabled = (field) => {
+    const own = field.validate;
+    const fallback = validations[field.type];
+    const validate = (value, args) => {
+        const siblingData = args?.siblingData;
+        if (isNoRole(value) && Boolean(siblingData?.[OIDC_FIELDS.disabledAt]))
+            return true;
+        if (own)
+            return own(value, args);
+        // As Payload applies its default (it does so only to fields without a `validate`).
+        return fallback ? fallback(value, { ...field, ...args }) : true;
+    };
+    return { ...field, validate };
+};
+/** The fields with the role field's validation allowing no role on a disabled user. */
+const withRoleValidation = (fields, options) => mapNamedFields(fields, new Set([options.roleField]), new Set(), allowNoRoleWhenDisabled);
+/** Makes the provider-owned fields updatable only by sync, adding `email` so it can be locked too. */
+const lockManagedFields = (collection, options) => {
+    const fields = [...(collection.fields ?? [])];
+    if (!hasField(fields, 'email'))
+        fields.push({ name: 'email', type: 'email' });
+    const names = new Set(['email', options.firstNameField, options.lastNameField, options.roleField]);
+    const found = new Set();
+    // Only update: creation is already limited to sync (and the break-glass first-register) by
+    // the beforeOperation hook, and first-register needs to write these fields.
+    const locked = mapNamedFields(fields, names, found, syncOnlyUpdate);
+    for (const name of names) {
+        if (!found.has(name))
+            throw new Error(`payload-oidc: ${collection.slug}.${name} not found.`);
+    }
+    return locked;
+};
+/** Never store `oidcSubject: null`: the sparse unique index would make a second one collide. */
+const dropNullSubject = ({ data }) => {
+    if (data && (data[OIDC_FIELDS.subject] === null || data[OIDC_FIELDS.subject] === '')) {
+        delete data[OIDC_FIELDS.subject];
+    }
+    return data;
+};
+/**
+ * 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 const oidcPlugin = (pluginOptions, testing) => (incoming) => {
+    const options = resolveOptions(pluginOptions);
+    const client = testing?.client ?? createProviderClient(options);
+    const collections = incoming.collections ?? [];
+    const target = collections.find(({ slug }) => slug === options.collection);
+    if (!target)
+        throw new Error(`payload-oidc: no "${options.collection}" collection.`);
+    if (!target.auth)
+        throw new Error(`payload-oidc: "${options.collection}" is not an auth collection.`);
+    // `endpoints: false` would be replaced by our list, and Payload would then add back every
+    // auth route, password ones included.
+    if (target.endpoints === false) {
+        throw new Error(`payload-oidc: "${options.collection}" must keep its REST endpoints.`);
+    }
+    options.verify = typeof target.auth === 'object' && Boolean(target.auth.verify);
+    const loginWithUsername = typeof target.auth === 'object' ? target.auth.loginWithUsername : undefined;
+    options.loginWithUsername = loginWithUsername
+        ? {
+            allowEmailLogin: typeof loginWithUsername === 'object' && Boolean(loginWithUsername.allowEmailLogin),
+        }
+        : undefined;
+    const auth = typeof target.auth === 'object' ? target.auth : {};
+    const collection = {
+        ...target,
+        // The admin then hides "Force Unlock"; the unlock operation is refused regardless.
+        access: options.enabled ? { ...target.access, unlock: () => false } : target.access,
+        auth: options.enabled
+            ? { ...auth, tokenExpiration: options.sessionSeconds, useSessions: true }
+            : auth,
+        endpoints: [...(target.endpoints ?? []), ...createEndpoints(options, client, testing?.clock)],
+        fields: [
+            // Role validation whether or not sign-in is on: users disabled before it was turned off
+            // keep no role, and must still be editable.
+            ...withRoleValidation(options.enabled ? lockManagedFields(target, options) : (target.fields ?? []), options),
+            ...pluginFields(options),
+        ],
+        hooks: {
+            ...target.hooks,
+            beforeChange: [...(target.hooks?.beforeChange ?? []), dropNullSubject],
+            beforeOperation: [
+                ...(target.hooks?.beforeOperation ?? []),
+                createBeforeOperationHook(options, testing?.clock),
+            ],
+            // First: Payload stops at the first refresh hook that returns a result, so a host hook
+            // placed before this one could sign an uncapped token.
+            refresh: [createRefreshHook(options, testing?.clock), ...(target.hooks?.refresh ?? [])],
+        },
+    };
+    const apiRoute = incoming.routes?.api ?? '/api';
+    const publicState = {
+        authorizePath: `${apiRoute}/${options.collection}/oidc/authorize`,
+        buttonLabel: options.buttonLabel,
+        enabled: options.enabled,
+        passwordLogin: options.passwordLogin,
+    };
+    const onInit = incoming.onInit;
+    return {
+        ...incoming,
+        // In an app that already has jobs, registered whether or not reconcile is configured, so the
+        // job schema doesn't depend on the environment (it is only scheduled when configured). In an
+        // app without jobs, only with a source, so the plugin never turns jobs on by itself.
+        ...(incoming.jobs?.tasks?.length || options.reconcile
+            ? {
+                jobs: {
+                    ...incoming.jobs,
+                    tasks: [
+                        ...(incoming.jobs?.tasks ?? []),
+                        createReconcileTask(options, {
+                            clock: testing?.clock,
+                            concurrencyControl: Boolean(incoming.jobs?.enableConcurrencyControl),
+                        }),
+                    ],
+                },
+            }
+            : {}),
+        admin: {
+            ...incoming.admin,
+            components: {
+                ...incoming.admin?.components,
+                beforeLogin: [
+                    ...(incoming.admin?.components?.beforeLogin ?? []),
+                    '@signal58/payload-oidc/rsc#OidcLoginButton',
+                ],
+            },
+        },
+        collections: collections.map((candidate) => (candidate === target ? collection : candidate)),
+        // Refused password sign-ins and ended sessions are expected: not errors.
+        loggingLevels: {
+            ...incoming.loggingLevels,
+            [OIDC_REFUSAL_NAME]: 'info',
+        },
+        custom: { ...incoming.custom, [PUBLIC_STATE_KEY]: publicState },
+        onInit: async (payload) => {
+            if (onInit)
+                await onInit(payload);
+            payload.logger.info(options.enabled
+                ? `payload-oidc: single sign-on is on for "${options.collection}"; password sign-in is ${options.passwordLogin ? 'open to the break-glass account' : 'off'}.`
+                : `payload-oidc: off (issuer, client ID or client secret unset); password sign-in is unchanged.`);
+            if (options.enabled) {
+                const table = Object.entries(options.roleTable)
+                    .map(([role, groups]) => `${role} ← ${groups.join(', ')}`)
+                    .join('; ');
+                payload.logger.info(`payload-oidc: role table (highest first): ${table}.`);
+                payload.logger.info(options.reconcile
+                    ? `payload-oidc: reconcile runs on queue "${options.reconcile.queue}" (${options.reconcile.cron}); the app must auto-run that queue.`
+                    : 'payload-oidc: reconcile is off (no source configured); removals apply at the next sign-in only.');
+            }
+        },
+    };
+};

package/dist/provider.d.ts

@@ -0,0 +1,43 @@
+import * as oidc from 'openid-client';
+import type { ResolvedOidcOptions } from './options.js';
+/** The verified claims the plugin uses from a sign-in. */
+export type VerifiedIdentity = {
+    email: string;
+    emailVerified: boolean;
+    familyName?: string;
+    givenName?: string;
+    groups: unknown;
+    name?: string;
+    subject: string;
+};
+export type ProviderClient = {
+    /** Builds the provider's authorization URL, discovering the provider on first use. */
+    authorizationUrl: (input: {
+        codeChallenge: string;
+        nonce: string;
+        redirectUri: string;
+        state: string;
+    }) => Promise<URL>;
+    /**
+     * Exchanges the callback's code and validates the ID token: signature against the provider's
+     * JWKS, issuer, audience, expiry, `nonce`, plus `state` and the PKCE verifier.
+     */
+    exchange: (input: {
+        callbackUrl: URL;
+        nonce: string;
+        state: string;
+        verifier: string;
+    }) => Promise<VerifiedIdentity>;
+};
+/**
+ * Creates the provider client. Discovery runs the first time sign-in needs it, never at startup
+ * or during a build, and a failed discovery isn't cached, so the next sign-in tries again.
+ */
+export declare const createProviderClient: (options: ResolvedOidcOptions, discover?: typeof oidc.discovery) => ProviderClient;
+/** Fresh `state`, `nonce` and PKCE verifier for one sign-in. */
+export declare const randomSignInSecrets: () => Promise<{
+    codeChallenge: string;
+    nonce: string;
+    state: string;
+    verifier: string;
+}>;

package/dist/provider.js

@@ -0,0 +1,67 @@
+import * as oidc from 'openid-client';
+const text = (value) => typeof value === 'string' && value.trim() ? value.trim() : undefined;
+/**
+ * Creates the provider client. Discovery runs the first time sign-in needs it, never at startup
+ * or during a build, and a failed discovery isn't cached, so the next sign-in tries again.
+ */
+export const createProviderClient = (options, discover = oidc.discovery) => {
+    let configuration;
+    // openid-client skips the ID token's signature when the token comes straight from the token
+    // endpoint (OIDC Core 3.1.3.7 lets a client rely on TLS); non-repudiation checks verify it
+    // against the provider's JWKS as well.
+    const execute = [
+        oidc.enableNonRepudiationChecks,
+        ...(options.allowInsecureIssuer ? [oidc.allowInsecureRequests] : []),
+    ];
+    const load = () => {
+        configuration ??= discover(new URL(options.issuer), options.clientId, options.clientSecret, undefined, { execute }).catch((error) => {
+            configuration = undefined;
+            throw error;
+        });
+        return configuration;
+    };
+    return {
+        authorizationUrl: async ({ codeChallenge, nonce, redirectUri, state }) => oidc.buildAuthorizationUrl(await load(), {
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+            nonce,
+            redirect_uri: redirectUri,
+            response_type: 'code',
+            scope: options.scopes.join(' '),
+            state,
+        }),
+        exchange: async ({ callbackUrl, nonce, state, verifier }) => {
+            const tokens = await oidc.authorizationCodeGrant(await load(), callbackUrl, {
+                expectedNonce: nonce,
+                expectedState: state,
+                idTokenExpected: true,
+                pkceCodeVerifier: verifier,
+            });
+            const claims = tokens.claims();
+            if (!claims)
+                throw new Error('payload-oidc: the provider returned no ID token.');
+            const email = text(claims.email)?.toLowerCase();
+            if (!email)
+                throw new Error('payload-oidc: the ID token has no email.');
+            return {
+                email,
+                emailVerified: claims.email_verified === true,
+                familyName: text(claims.family_name),
+                givenName: text(claims.given_name),
+                groups: claims.groups,
+                name: text(claims.name),
+                subject: claims.sub,
+            };
+        },
+    };
+};
+/** Fresh `state`, `nonce` and PKCE verifier for one sign-in. */
+export const randomSignInSecrets = async () => {
+    const verifier = oidc.randomPKCECodeVerifier();
+    return {
+        codeChallenge: await oidc.calculatePKCECodeChallenge(verifier),
+        nonce: oidc.randomNonce(),
+        state: oidc.randomState(),
+        verifier,
+    };
+};

package/dist/reconcile-task.d.ts

@@ -0,0 +1,28 @@
+import type { Payload, TaskConfig } from 'payload';
+import type { ResolvedOidcOptions } from './options.js';
+export declare const RECONCILE_TASK_SLUG = "payload-oidc-reconcile";
+/**
+ * Marks reconcile runs on `queue` that are still processing after `olderThanSeconds` as failed,
+ * and returns the IDs it marked.
+ *
+ * Payload's scheduler queues a run only while no scheduled run of the task is waiting or
+ * processing, and its runner only picks up jobs that aren't processing. A run left processing by a
+ * process that stopped mid-run (a container a deploy replaced) would therefore block the queue for
+ * good: Payload never expires it. Payload's own cancel writes its final-failure shape
+ * (`hasError`, `processing: false`, `error.cancelled`), so the dead run stays visible as a failed
+ * job and the scheduler stops counting it.
+ */
+export declare const releaseStaleRuns: (payload: Payload, { now, olderThanSeconds, queue }: {
+    now: Date;
+    olderThanSeconds: number;
+    queue: string;
+}) => Promise<Array<number | string>>;
+/**
+ * The reconcile job. Payload schedules it only on its own queue, and runs schedules only for
+ * queues listed in `jobs.autoRun`, so the app must add that queue there. A failed run (a group
+ * that can't be read, a safety stop) fails the job and records no heartbeat.
+ */
+export declare const createReconcileTask: (options: ResolvedOidcOptions, { clock, concurrencyControl }?: {
+    clock?: (() => Date) | undefined;
+    concurrencyControl?: boolean | undefined;
+}) => TaskConfig;