@signal58/payload-oidc 0.2.0 → 0.3.0

package/README.md

@@ -7,14 +7,16 @@ truth for the auth collection's users and roles.
   the ID token at every sign-in and can't be edited in Payload.
 - Roles come from the provider's `groups` claim through one role table, highest role first.
 - A user whose groups grant no role is refused and disabled: role and sessions cleared,
-  `oidcDisabledAt` set, record kept.
+  `oidcDisabledAt` set, record kept. A disabled user stays editable even if the role field is
+  `required`.
 - Password sign-in is closed for the collection: `login`, `forgotPassword`, `resetPassword`,
   `unlock`, and setting a password through `update`, are refused through REST, the admin and the
   Local API alike. A break-glass account can be let back in with a flag.
 - A reconcile job (optional) reads the provider's role-table groups every 15 minutes and disables
   users who left them, so removal doesn't wait for a sign-in. It changes nothing unless every
   group was read, stops if it would disable too many users at once, and records a heartbeat that
-  an uptime check can watch.
+  an uptime check can watch. A run a deploy cut off is released at the next schedule.
+- A migration helper marks existing users as linkable by email, once, for a linking window.
 - A superadmin (the app decides who) can remove a disabled user: deleted if nothing refers to
   them, anonymised otherwise.
 - Sessions are ordinary Payload sessions: an idle timeout (`sessionHours`) that activity extends,
@@ -38,7 +40,7 @@ dependencies. The package is ESM only.
 import { oidcPlugin } from '@signal58/payload-oidc'
 
 export default buildConfig({
-  serverURL: process.env.SERVER_URL, // required: the redirect URI is built from it
+  serverURL: process.env.SERVER_URL, // or the plugin's serverURL: the redirect URI is built from it
   plugins: [
     oidcPlugin({
       collection: 'users',
@@ -87,6 +89,7 @@ Endpoint paths are relative to the collection's REST route, `${routes.api}/<coll
 | `beforeOperation` hook        | Closes password operations and creation outside sync; refuses `refresh` after the cap.                    |
 | `refresh` hook                | Signs a refreshed token that ends at the absolute cap.                                                    |
 | `beforeChange` hook           | Drops an `oidcSubject` of `null` or `''`, which would collide in the sparse index.                        |
+| Role field `validate`         | No role passes only on a disabled user; anything else goes to the field's own validation (see below).     |
 | `beforeLogin` component       | The sign-in button and error message; hides the password form while it's closed.                          |
 | `POST /oidc/remove/:id`       | Removes a disabled user (`removeAccess`, default nobody); a "Remove user" button in the sidebar calls it. |
 | `unlock` access denied        | Payload then hides "Force Unlock"; the operation is refused anyway.                                       |
@@ -95,6 +98,11 @@ Endpoint paths are relative to the collection's REST route, `${routes.api}/<coll
 | `GET /oidc/reconcile/health`  | 200 while the last successful reconcile is recent, 503 once it isn't; for an uptime check.                |
 | `payload-oidc-reconcile` task | Registered always; scheduled on `reconcile.queue` only when a source is configured.                       |
 
+The role field's validation is wrapped, whether or not sign-in is on: an empty role (an empty
+list, or no single value) passes while `oidcDisabledAt` is set, so a `required` role field doesn't
+stop an admin saving a disabled user. Anything else goes to the field's own `validate`, or to
+Payload's default for its type (`required`, known options).
+
 The managed fields (`email`, first and last name, the role field) get `update` access that only
 the plugin's sync passes (`req.context.oidcSync`). **If your app replaces field or collection
 access after plugins run, keep those rules**: no updates to the managed fields outside sync, no
@@ -166,6 +174,52 @@ Each run:
 - records a heartbeat in Payload's KV store; `GET /oidc/reconcile/health` answers 503 once it is
   older than `reconcileHeartbeatMaxMinutes` (default 45).
 
+A run cut off mid-way, for example by a deploy that replaced the process, would stay marked as
+processing, and Payload's scheduler queues nothing while it does. So before each schedule, the
+plugin marks reconcile runs on the schedule's queue still processing after
+`reconcileStaleAfterMinutes` (default 10, at least 1) as failed, with Payload's own cancel, and the
+same tick queues a new run. The dead run stays in the jobs collection as a failed job.
+
+Payload doesn't touch a job while its handler runs, so a live run that went on past the threshold
+would look the same. To rule that out, a run whose source hasn't answered within 80% of the
+threshold (8 minutes by default; `authentikSource` gives up on a request after 30 seconds) stops
+before changing anything and fails, and the next tick tries again. Cancelling only marks the job:
+a process that was paused rather than stopped, and resumes, finishes its run alongside the new
+one. Reconcile's writes are conditional, so the two don't undo each other, but the cancelled job
+still shows as failed.
+
+`reconcileStaleAfterMinutes: false` turns off both the release and the time limit, as in 0.2.0. A
+`beforeSchedule` in `reconcileScheduleHooks` runs after the release, in place of Payload's default
+rule.
+
+## Existing users
+
+Users who were in the collection before the plugin can be linked to their provider account once,
+by verified email, until `linkByEmailUntil`. Mark them from the app's own migration:
+
+```ts
+import type { MigrateDownArgs, MigrateUpArgs } from '@payloadcms/db-mongodb'
+import { clearLinkingSnapshot, takeLinkingSnapshot } from '@signal58/payload-oidc'
+
+export async function up(args: MigrateUpArgs): Promise<void> {
+  await takeLinkingSnapshot(args) // { collection: 'users' } by default
+}
+
+export async function down(args: MigrateDownArgs): Promise<void> {
+  await clearLinkingSnapshot(args)
+}
+```
+
+`takeLinkingSnapshot` builds the collection's indexes first (among them the sparse unique
+`oidcSubject` index, outside the migration's transaction), refuses a user that stores
+`oidcSubject: null`, then sets `oidcLinkable: true` on every user without an `oidcSubject`. A rerun
+marks nobody new. **Call it 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 an index build that had work to do, its write fails with a write conflict (the error says
+so, and running the migration again passes). An index that fails to build, the plugin's or not,
+fails the migration with the collection named. Users created later, at their first sign-in, are
+never linkable. `clearLinkingSnapshot` removes the marks and keeps links and disables.
+
 ## Removing users
 
 `POST ${routes.api}/<collection>/oidc/remove/:id`, or the sidebar's "Remove user" on a disabled
@@ -191,29 +245,31 @@ first-register screen while the flag is on; it can't set the plugin's fields the
 
 ## Options
 
-| Option                               | Default                         | Notes                                                             |
-| ------------------------------------ | ------------------------------- | ----------------------------------------------------------------- |
-| `collection`                         | `'users'`                       | An auth collection.                                               |
-| `issuer`, `clientId`, `clientSecret` | —                               | All three, or the plugin is off.                                  |
-| `roles.field`                        | —                               | The role field.                                                   |
-| `roles.table`                        | —                               | Role → groups, highest role first.                                |
-| `roles.hasMany`                      | `true`                          | `false` stores a single value.                                    |
-| `fields`                             | `firstName`, `lastName`         | Names of the name fields.                                         |
-| `lastNamePlaceholder`                | `'-'`                           | Used when the provider sends no `family_name`.                    |
-| `sessionHours`                       | `8`                             | Becomes the collection's `tokenExpiration`.                       |
-| `sessionMaxHours`                    | `12`                            | Refresh is refused after this, from sign-in.                      |
-| `passwordLogin`                      | `false`                         | Needs `breakGlassEmail`.                                          |
-| `breakGlassEmail`                    | —                               |                                                                   |
-| `linkByEmailUntil`                   | —                               | ISO date; without it nobody is linked by email.                   |
-| `scopes`                             | `['openid','email','profile']`  |                                                                   |
-| `additionalServerURLs`               | —                               | Other public origins, used when a request arrives on one of them. |
-| `reconcile`                          | —                               | A `ReconcileSource`, such as `authentikSource(...)`.              |
-| `reconcileMaxDisableShare`           | `0.25`                          |                                                                   |
-| `reconcileHeartbeatMaxMinutes`       | `45`                            |                                                                   |
-| `removeAccess`                       | nobody                          | `(req) => boolean`.                                               |
-| `serverURL`                          | Payload's `serverURL`           | The public origin the callback is registered under.               |
-| `buttonLabel`                        | `'Sign in with single sign-on'` |                                                                   |
-| `allowInsecureIssuer`                | `false`                         | Allows an `http:` issuer, never when `NODE_ENV=production`.       |
+| Option                               | Default                         | Notes                                                                          |
+| ------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------ |
+| `collection`                         | `'users'`                       | An auth collection.                                                            |
+| `issuer`, `clientId`, `clientSecret` | —                               | All three, or the plugin is off.                                               |
+| `roles.field`                        | —                               | The role field.                                                                |
+| `roles.table`                        | —                               | Role → groups, highest role first.                                             |
+| `roles.hasMany`                      | `true`                          | `false` stores a single value.                                                 |
+| `fields`                             | `firstName`, `lastName`         | Names of the name fields.                                                      |
+| `lastNamePlaceholder`                | `'-'`                           | Used when the provider sends no `family_name`.                                 |
+| `sessionHours`                       | `8`                             | Becomes the collection's `tokenExpiration`.                                    |
+| `sessionMaxHours`                    | `12`                            | Refresh is refused after this, from sign-in.                                   |
+| `passwordLogin`                      | `false`                         | Needs `breakGlassEmail`.                                                       |
+| `breakGlassEmail`                    | —                               |                                                                                |
+| `linkByEmailUntil`                   | —                               | ISO date; without it nobody is linked by email.                                |
+| `scopes`                             | `['openid','email','profile']`  |                                                                                |
+| `additionalServerURLs`               | —                               | Other public origins, used when a request arrives on one of them.              |
+| `reconcile`                          | —                               | A `ReconcileSource`, such as `authentikSource(...)`.                           |
+| `reconcileMaxDisableShare`           | `0.25`                          |                                                                                |
+| `reconcileHeartbeatMaxMinutes`       | `45`                            |                                                                                |
+| `reconcileStaleAfterMinutes`         | `10`                            | Releases a run still processing after this (at least 1); `false` turns it off. |
+| `reconcileScheduleHooks`             | —                               | Payload schedule hooks for the reconcile task.                                 |
+| `removeAccess`                       | nobody                          | `(req) => boolean`.                                                            |
+| `serverURL`                          | Payload's `serverURL`           | The public origin the callback is registered under.                            |
+| `buttonLabel`                        | `'Sign in with single sign-on'` |                                                                                |
+| `allowInsecureIssuer`                | `false`                         | Allows an `http:` issuer, never when `NODE_ENV=production`.                    |
 
 ## Adopting in an app
 
@@ -227,8 +283,9 @@ The plugin owns sign-in, the managed fields and the password refusals. These are
 2. **Dependency.** Pin an exact version. Check that `pnpm why @payloadcms/ui` shows one version: a
    second copy breaks the admin components' React context.
 3. **`serverURL` in every environment**, Payload's or the plugin's option, because the redirect URI
-   is built from it. A second public origin (a LAN host, say) goes in `additionalServerURLs`, with
-   its own callback registered.
+   is built from it. An app that leaves Payload's unset outside production passes the plugin's
+   instead. A second public origin (a LAN host, say) goes in `additionalServerURLs`, with its own
+   callback registered.
 4. **Access your app sets after plugins run.** If a later step replaces collection or field access,
    keep the plugin's rules there: `create` only for sync writes (`req.context[OIDC_SYNC_CONTEXT]`),
    `delete` denied (removal goes through `removeAccess` and the plugin's endpoint), `unlock`
@@ -240,15 +297,17 @@ The plugin owns sign-in, the managed fields and the password refusals. These are
    admin) must let sync writes through in both directions: the provider is right, and the
    break-glass account remains. Sign-in updates existing users directly in MongoDB without hooks;
    creating a user goes through Payload, so hooks run then.
-7. **Empty roles.** A disabled user has no role. If the role field is `required`, its validation
-   must allow an empty list while `oidcDisabledAt` is set; the plugin doesn't do this yet.
-8. **Existing users.** Write a migration that builds the collection's indexes (the sparse unique
-   `oidcSubject` index, before writing in a transaction) and sets `oidcLinkable: true` on the
-   users who may link by email, skipping any already linked. Set `linkByEmailUntil` to the end of
-   the linking window. Users created later are never linkable.
+7. **Empty roles.** A disabled user has no role. The plugin's validation allows that on a
+   `required` role field (since 0.3.0), and keeps the field's own `validate`. An app-level rule
+   that does the same can go.
+8. **Existing users.** Add a migration that calls `takeLinkingSnapshot` first (since 0.3.0; see
+   [Existing users](#existing-users)), and set `linkByEmailUntil` to the end of the linking window.
 9. **Jobs.** With `reconcile`, add its queue (`oidc-reconcile` for `authentikSource`) to
-   `jobs.autoRun` every 15 minutes. A run cut off by a deploy stays locked and blocks the queue,
-   so release stale runs before each schedule; the plugin doesn't do this yet.
+   `jobs.autoRun` every 15 minutes. A run a deploy cut off is released before the next schedule
+   (since 0.3.0), so an app-level hook that does this for the reconcile task can go. A custom
+   `ReconcileSource` must answer within 80% of `reconcileStaleAfterMinutes`. If the app
+   post-processes its jobs config (locks the jobs-stats global, say), check the reconcile task's
+   schedule still works.
 10. **Generated files.** Run `payload generate:importmap` and `payload generate:types`, and commit
     both.
 11. **Break-glass.** A dedicated account that is never linked, with its password stored safely.

package/dist/index.d.ts

@@ -6,3 +6,4 @@ 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

@@ -5,3 +5,4 @@ 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

@@ -67,8 +67,19 @@ export type OidcPluginOptions = {
     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. */
+    /**
+     * 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: {
@@ -118,6 +129,8 @@ export type ResolvedOidcOptions = {
     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>;

package/dist/options.js

@@ -5,6 +5,13 @@ const positiveHours = (value, fallback, name) => {
     }
     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;
@@ -80,6 +87,10 @@ export const resolveOptions = (options) => {
         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),

package/dist/plugin.d.ts

@@ -1,4 +1,4 @@
-import type { FieldAccess, Plugin } from 'payload';
+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. */

package/dist/plugin.js

@@ -1,3 +1,4 @@
+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';
@@ -61,21 +62,49 @@ const pluginFields = (options) => [
 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, giving each named top-level, row or collapsible data field `update` access
- * that only sync passes. Copies, never edits: a field config the host shares with another
- * collection must not be locked there too.
+ * 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 withSyncOnlyUpdate = (fields, names, found) => fields.map((field) => {
+const mapNamedFields = (fields, names, found, replace) => fields.map((field) => {
     if ('name' in field && names.has(field.name)) {
         found.add(field.name);
-        const access = field.access;
-        return { ...field, access: { ...access, update: syncWriteOnly } };
+        return replace(field);
     }
     if (field.type === 'row' || field.type === 'collapsible') {
-        return { ...field, fields: withSyncOnlyUpdate(field.fields, names, found) };
+        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 ?? [])];
@@ -85,7 +114,7 @@ const lockManagedFields = (collection, options) => {
     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 = withSyncOnlyUpdate(fields, names, found);
+    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.`);
@@ -138,7 +167,9 @@ export const oidcPlugin = (pluginOptions, testing) => (incoming) => {
             : auth,
         endpoints: [...(target.endpoints ?? []), ...createEndpoints(options, client, testing?.clock)],
         fields: [
-            ...(options.enabled ? lockManagedFields(target, options) : (target.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: {

package/dist/reconcile-task.d.ts

@@ -1,6 +1,22 @@
-import type { TaskConfig } from 'payload';
+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

package/dist/reconcile-task.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signal58/payload-oidc",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Sign in to the Payload admin with an OpenID Connect provider, with the provider as the source of truth for users and roles.",
   "keywords": [
     "authentik",