@signal58/payload-oidc 0.0.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Signal58
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,359 @@
+# @signal58/payload-oidc
+
+Sign in to the Payload admin with an OpenID Connect provider, and make the provider the source of
+truth for the auth collection's users and roles.
+
+- Users are created at their first sign-in. Email, first name, last name and role are taken from
+  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. 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. 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,
+  up to an absolute cap from sign-in (`sessionMaxHours`). A refresh near the cap gets a token that
+  ends at the cap, not `sessionHours` later.
+
+Payload `^3.91` with the MongoDB adapter, on Node 24. MIT licence.
+
+## Install
+
+```bash
+pnpm add @signal58/payload-oidc
+```
+
+`payload` and `@payloadcms/ui` (`^3.91`, at the same version as each other) and `react` 19 are peer
+dependencies. The package is ESM only.
+
+## Setup
+
+```ts
+import { oidcPlugin } from '@signal58/payload-oidc'
+
+export default buildConfig({
+  serverURL: process.env.SERVER_URL, // or the plugin's serverURL: the redirect URI is built from it
+  plugins: [
+    oidcPlugin({
+      collection: 'users',
+      issuer: process.env.OIDC_ISSUER, // https://idp.example/application/o/my-cms/
+      clientId: process.env.OIDC_CLIENT_ID,
+      clientSecret: process.env.OIDC_CLIENT_SECRET,
+      roles: {
+        field: 'roles',
+        table: {
+          admin: ['cms-admins'],
+          editor: ['cms-editors'],
+        },
+      },
+      buttonLabel: 'Sign in with Example SSO',
+      breakGlassEmail: process.env.BREAK_GLASS_EMAIL,
+      passwordLogin: process.env.PASSWORD_LOGIN === '1',
+    }),
+  ],
+})
+```
+
+Register `${serverURL}${routes.api}/<collection>/oidc/callback` as the client's redirect URI (with
+Payload's default `routes.api`, `https://cms.example/api/users/oidc/callback`), and the same path
+on each of `additionalServerURLs`, with the Authorization Code grant, a confidential client, and an
+RS256 signing key. Request scopes `openid email profile` (the default); the provider must send
+`email_verified: true` and a `groups` claim.
+
+With the issuer, client ID or client secret unset, the plugin is off: it still adds its fields and
+endpoints (which answer 404), so the schema doesn't change, but sign-in works exactly as before.
+That is the rollback. Discovery happens at the first sign-in, never at startup or during a build.
+
+Run `payload generate:importmap` after adding the plugin: the sign-in button is a server
+component, `@signal58/payload-oidc/rsc#OidcLoginButton`, added to `admin.components.beforeLogin`.
+
+## What it adds
+
+Endpoint paths are relative to the collection's REST route, `${routes.api}/<collection>`.
+
+| Addition                      | Purpose                                                                                                   |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `oidcSubject` field           | The provider's `sub`, unique. Unset (never `null`) when unlinked, because the index is sparse.            |
+| `oidcDisabledAt` field        | Set when the user is disabled.                                                                            |
+| `oidcLinkable` field          | Marks pre-existing users that may be linked by email once, before `linkByEmailUntil`.                     |
+| `GET /oidc/authorize`         | Starts sign-in. `?redirect=` is kept only if it is a path under the admin route.                          |
+| `GET /oidc/callback`          | Finishes sign-in and sets the Payload session cookie.                                                     |
+| `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.                                       |
+| Sidebar `oidcRemove` ui field | "Remove user" on a disabled user; hides "Change Password" while password sign-in is closed.               |
+| `loggingLevels.OidcRefusal`   | `info`: refused password operations and ended sessions are expected, not errors.                          |
+| `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
+`create` outside sync, no `delete` except through your own removal path, and no `unlock` (or the
+admin shows a "Force Unlock" the server refuses).
+
+## Sign-in
+
+1. `authorize` creates `state`, `nonce` and a PKCE verifier and seals them, with the return path,
+   in a short-lived, HTTP-only, `SameSite=Lax` cookie scoped to the callback path (AES-256-GCM,
+   key derived from the Payload secret).
+2. `callback` exchanges the code and validates the ID token with `openid-client`, including its
+   signature against the provider's JWKS (non-repudiation checks are on: by default the library
+   relies on TLS for tokens from the token endpoint).
+3. The role comes from the role table. No role: refused, and disabled if the user exists.
+4. The user is found by `oidcSubject`. If there is none and linking is still open, a user with
+   `oidcLinkable` and the same email is linked in one atomic update that also clears its sessions
+   and replaces its password with one nobody knows. Otherwise a new user is created, unless the
+   email already belongs to someone (refused, never taken over).
+5. Email, names and role are written and `oidcDisabledAt` cleared. For an existing user that is
+   one database update of just those paths (never a whole-document write, which could restore
+   sessions a disable just cleared), so **no collection hooks or validation run** for it; a new
+   user is created through Payload with `req.context.oidcSync` set, so hooks do run.
+   The break-glass email is never linked or synced: a provider account with it is refused.
+6. A session is pushed with one conditional update (only while the user isn't disabled and is
+   still linked to that subject), the JWT signed over `getFieldsToSign` with that `sid`, and the
+   cookie set.
+
+Failures redirect to the login page with `?oidc_error=<code>`: `email_not_verified`, `no_role`,
+`account_conflict`, `disabled`, `expired`, `provider`, `unavailable`, `failed`. Provider detail is
+only logged.
+
+**The plugin trusts `email_verified`.** Linking by email (before the cut-off) gives a provider
+account the existing CMS record with that email. That is only safe if users can't change their
+own email at the provider, or the provider marks a changed email unverified.
+
+## Reconcile
+
+```ts
+import { authentikSource, oidcPlugin } from '@signal58/payload-oidc'
+
+oidcPlugin({
+  // …
+  reconcile: authentikSource({
+    url: process.env.OIDC_RECONCILE_URL,
+    token: process.env.OIDC_RECONCILE_TOKEN,
+  }),
+})
+
+// and, because Payload runs schedules only for listed queues:
+jobs: {
+  autoRun: [{ cron: '*/15 * * * *', queue: 'oidc-reconcile' }]
+}
+```
+
+`authentikSource` reads each role-table group (`GET /api/v3/core/groups/?name=…&include_users=true`)
+with a token that only needs object-level `view_group` on those groups; a member's `uid` is the
+OIDC `sub` when the provider's subject mode is the hashed user ID. Any other directory can be a
+source: implement `ReconcileSource.fetchGroupMembers`.
+
+Each run:
+
+- disables linked users whose subject is in no role-table group or only as an inactive member
+  (again, if something restored their role or sessions);
+- updates enabled users whose role changed; a disabled user stays disabled until they sign in;
+- never creates users, and never touches the break-glass account or unlinked users;
+- changes nothing if any group can't be read, and stops without changes if it would disable more
+  than `reconcileMaxDisableShare` of the linked users (default 25%; one is always allowed);
+- 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
+user. Only disabled users: an active one would be created again at their next sign-in, and the
+break-glass account never. The plugin scans the config for relationship and upload fields (in arrays, groups,
+blocks and tabs, polymorphic included, and in versions) that can point at the collection. If none
+refers to the user they are deleted; otherwise their names become "Removed user", their email
+`removed-<id>@removed.invalid`, and every other profile field (photo, links, anything the app
+added; `keepOnRemove` keeps named ones), their subject, password, sessions and reset or lockout
+state go, so bylines still resolve but nothing else identifies them.
+Payload's own bookkeeping (preferences, locks) isn't counted; rich-text links aren't seen.
+
+## Break-glass
+
+With `passwordLogin: true`, the `breakGlassEmail` account may use its password (sign-in, forgotten
+and reset password, and changing its own password), and, until `linkByEmailUntil`, so may
+pre-existing users that haven't linked yet. Nobody may set another user's password. Anyone else
+gets the status and body an unknown address gets (a 401, or a forgotten-password success that
+sends nothing). Timing and lockout still differ (only allowed users' passwords are checked and
+their failures counted), so keep the flag's windows short. Sync never disables the break-glass
+account. On an empty database, the break-glass account can register itself through Payload's
+first-register screen while the flag is on; it can't set the plugin's fields there.
+
+## 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`                            |                                                                                |
+| `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
+
+The plugin owns sign-in, the managed fields and the password refusals. These are the app's:
+
+1. **Provider.** One confidential client per environment, each with its own secret: Authorization
+   Code with PKCE, RS256, and the callback above registered for every origin the environment
+   serves. The ID token must carry `email_verified: true` and a `groups` claim limited to the role
+   table's groups. With Authentik, use the "verified email" scope mapping (it sends `false`
+   otherwise) and pin the subject mode to the hashed user ID, which is what reconcile compares.
+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. 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`
+   denied, and the email, name and role fields updatable only by sync (`syncWriteOnly`). A patch
+   to the role field must keep that rule rather than overwrite it.
+5. **Endpoint allowlists.** If the app limits which REST endpoints a collection exposes, add the
+   plugin's four to the auth collection only.
+6. **Role guards.** A hook that limits role changes (for example, one that protects the last top
+   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. 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 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.
+    Turn `passwordLogin` on only for the linking window and emergencies.
+12. **Tests and scripts.** Tests that expect a password sign-in to work, or a wrong password's
+    401, now meet the refusal. Scripts that grant roles directly drift from the provider: retire
+    them or limit them to the break-glass account. Add an integration test that signs in through
+    `@signal58/payload-oidc/testing` (`startFakeProvider`).
+13. **Monitoring.** Point an uptime check at `${routes.api}/<collection>/oidc/reconcile/health`.
+14. **Rollout.** Deploy with `passwordLogin` on and `linkByEmailUntil` set; existing users link at
+    their first single sign-on. After the window, unset `passwordLogin`, then check that login,
+    forgotten and reset password are refused for everyone.
+
+## Known limits
+
+- MongoDB only: session pushes and disables are conditional, atomic updates.
+- Payload's own `refresh` writes the whole user document. If a disable lands in the same moment,
+  that write can restore the role and sessions; the next disable (sign-in or reconcile) repeats it.
+- The auth collection must keep its REST endpoints (`endpoints: false` is refused).
+- Tested with email login. `loginWithUsername` collections are handled (the user is looked up the
+  way Payload will, per operation) but not yet covered by the end-to-end suites.
+- A Payload write can't clear a linked `oidcSubject` (a `null` or `''` is dropped); code that
+  unlinks a user must `$unset` it directly.
+- Signing out of the CMS doesn't sign out of the provider.
+- "Change Password" is hidden with CSS (Payload has no option for it), and only while password
+  sign-in is closed: with `passwordLogin` on it shows on every account, though the server lets only
+  the break-glass account change its own password.
+
+## Development
+
+```bash
+pnpm install
+pnpm check               # typecheck and lint
+pnpm test                # unit tests
+pnpm test:integration    # end to end: a real Payload on MongoDB and a fake OIDC provider
+pnpm build               # dist/: ESM and declarations
+node scripts/check-dist.mjs  # the built entry points load in plain Node
+pnpm check:package       # publint and arethetypeswrong
+```
+
+The integration suite needs a MongoDB replica set (`PAYLOAD_OIDC_DATABASE_URI`, or a local one on
+`127.0.0.1:27017` by default, named by `PAYLOAD_OIDC_REPLICA_SET` if set) and owns its database: it
+refuses one that holds anything else.
+
+## Releases and security
+
+Versions follow semver, recorded in [CHANGELOG.md](CHANGELOG.md). A `v*` tag publishes to npm from
+GitHub Actions, with provenance. Report vulnerabilities privately, as [SECURITY.md](SECURITY.md)
+describes.

package/dist/before-operation.d.ts

@@ -0,0 +1,35 @@
+import { APIError, type CollectionBeforeOperationHook, type CollectionRefreshHook } from 'payload';
+import { type ResolvedOidcOptions } from './options.js';
+/** `name` of the plugin's refusals, which the plugin logs at `info` (`config.loggingLevels`). */
+export declare const OIDC_REFUSAL_NAME = "OidcRefusal";
+/**
+ * An expected refusal (password sign-in off, session ended): a public 403. Its own `name`, set
+ * explicitly like Payload's errors so minifying can't change it, keeps these out of error logs.
+ */
+export declare class OidcRefusal extends APIError {
+    constructor(message: string);
+}
+/**
+ * Closes password sign-in for the auth collection while the plugin is on. A `beforeOperation`
+ * hook runs for the REST routes, the admin views and the Local API alike; wrapping endpoints
+ * can't, and `disableLocalStrategy` would also break Payload's JWT strategy, refresh and logout.
+ *
+ * - `login`, `forgotPassword`, `resetPassword`: refused while `passwordLogin` is off. While it is
+ *   on, a user who may not use a password gets the status and body an unknown email gets (401,
+ *   or a success that sends no email for a forgotten password). Timing and lockout still differ:
+ *   only allowed users' passwords are hashed and their failed attempts counted.
+ * - `update` with a password: refused, except the break-glass account changing its own password
+ *   while `passwordLogin` is on. Sync never sets passwords this way.
+ * - `unlock`: refused.
+ * - `create`: refused unless the plugin's sync makes it, or the collection is empty and the
+ *   break-glass account registers itself with password sign-in on (first-register), which may
+ *   not set the plugin's fields.
+ * - `refresh`: refused once the session is older than `sessionMaxHours`, or the user is disabled.
+ */
+export declare const createBeforeOperationHook: (options: ResolvedOidcOptions, clock?: () => Date) => CollectionBeforeOperationHook;
+/**
+ * Caps a refreshed token at the session's absolute limit. Payload signs every refreshed token for
+ * the full `tokenExpiration`, and its JWT strategy never reads the session's `expiresAt`, so
+ * without this a refresh just before `sessionMaxHours` would last another `sessionHours`.
+ */
+export declare const createRefreshHook: (options: ResolvedOidcOptions, clock?: () => Date) => CollectionRefreshHook;

package/dist/before-operation.js

@@ -0,0 +1,211 @@
+import { APIError, AuthenticationError, getFieldsToSign, jwtSign, } from 'payload';
+import { canLinkByEmail, isBreakGlassEmail } from './options.js';
+import { authCollectionModel, findSession, OIDC_FIELDS, OIDC_SYNC_CONTEXT, } from './store.js';
+/** `name` of the plugin's refusals, which the plugin logs at `info` (`config.loggingLevels`). */
+export const OIDC_REFUSAL_NAME = 'OidcRefusal';
+/**
+ * An expected refusal (password sign-in off, session ended): a public 403. Its own `name`, set
+ * explicitly like Payload's errors so minifying can't change it, keeps these out of error logs.
+ */
+export class OidcRefusal extends APIError {
+    constructor(message) {
+        super(message, 403, undefined, true);
+        this.name = OIDC_REFUSAL_NAME;
+    }
+}
+const refused = (message) => new OidcRefusal(message);
+const PASSWORD_OFF = 'Password sign-in is turned off. Use the single sign-on button.';
+const SESSION_ENDED = 'Your session has ended. Sign in again.';
+const PASSWORD_FIELDS = { email: 1, [OIDC_FIELDS.linkable]: 1, [OIDC_FIELDS.subject]: 1 };
+/**
+ * Finds a stored user matching any of `alternatives`. `login` reads through Payload's adapter
+ * with `req`, inside the request's transaction, because first-register creates the user and logs
+ * in within one. Other operations read outside it: a read inside forgotPassword's transaction
+ * makes Payload's own update of the same user fail with a write conflict.
+ */
+const findStored = async (req, options, alternatives, inTransaction) => {
+    if (alternatives.length === 0)
+        return null;
+    if (inTransaction) {
+        const where = {
+            or: alternatives.map((filter) => Object.fromEntries(Object.entries(filter).map(([key, value]) => [key, { equals: value }]))),
+        };
+        return (await req.payload.db.findOne({
+            collection: options.collection,
+            req,
+            where: where,
+        }));
+    }
+    return authCollectionModel(req.payload, options.collection)
+        .findOne({ $or: alternatives }, PASSWORD_FIELDS)
+        .lean();
+};
+const normalised = (value) => typeof value === 'string' && value.trim() ? value.trim().toLowerCase() : undefined;
+/**
+ * The stored user a login or forgotten-password request targets, looked up the way Payload will
+ * (`auth/operations/login.js`, `forgotPassword.js`). Without `loginWithUsername` only the email
+ * counts, and a stray `username` is ignored. With it, login matches the username, or either field
+ * when email login is also allowed; a forgotten password prefers the email when that is allowed.
+ */
+const targetUser = async (req, options, operation, data) => {
+    const email = normalised(data?.email);
+    const username = normalised(data?.username);
+    const inTransaction = operation === 'login';
+    if (!options.loginWithUsername) {
+        return email ? findStored(req, options, [{ email }], inTransaction) : null;
+    }
+    const emailAllowed = options.loginWithUsername.allowEmailLogin;
+    if (operation === 'forgotPassword') {
+        if (emailAllowed && email)
+            return findStored(req, options, [{ email }], false);
+        return username ? findStored(req, options, [{ username }], false) : null;
+    }
+    if (username) {
+        return findStored(req, options, emailAllowed ? [{ username }, { email: username }] : [{ username }], true);
+    }
+    return emailAllowed && email ? findStored(req, options, [{ email }], true) : null;
+};
+/**
+ * Whether a user may use a password while `passwordLogin` is on: the break-glass account, or,
+ * until the linking cut-off, a snapshot user who hasn't linked yet.
+ */
+const passwordAllowedFor = (options, user, now) => {
+    if (!options.passwordLogin || !user)
+        return false;
+    if (isBreakGlassEmail(options, user.email))
+        return true;
+    return canLinkByEmail(options, now) && Boolean(user.oidcLinkable && !user.oidcSubject);
+};
+/**
+ * Closes password sign-in for the auth collection while the plugin is on. A `beforeOperation`
+ * hook runs for the REST routes, the admin views and the Local API alike; wrapping endpoints
+ * can't, and `disableLocalStrategy` would also break Payload's JWT strategy, refresh and logout.
+ *
+ * - `login`, `forgotPassword`, `resetPassword`: refused while `passwordLogin` is off. While it is
+ *   on, a user who may not use a password gets the status and body an unknown email gets (401,
+ *   or a success that sends no email for a forgotten password). Timing and lockout still differ:
+ *   only allowed users' passwords are hashed and their failed attempts counted.
+ * - `update` with a password: refused, except the break-glass account changing its own password
+ *   while `passwordLogin` is on. Sync never sets passwords this way.
+ * - `unlock`: refused.
+ * - `create`: refused unless the plugin's sync makes it, or the collection is empty and the
+ *   break-glass account registers itself with password sign-in on (first-register), which may
+ *   not set the plugin's fields.
+ * - `refresh`: refused once the session is older than `sessionMaxHours`, or the user is disabled.
+ */
+export const createBeforeOperationHook = (options, clock = () => new Date()) => async ({ args, operation, req }) => {
+    if (!options.enabled)
+        return args;
+    const now = clock();
+    const data = args.data;
+    const isSync = req.context?.[OIDC_SYNC_CONTEXT] === true;
+    switch (operation) {
+        case 'login':
+        case 'forgotPassword': {
+            if (!options.passwordLogin)
+                throw refused(PASSWORD_OFF);
+            const user = await targetUser(req, options, operation, data);
+            if (passwordAllowedFor(options, user, now))
+                return args;
+            if (operation === 'login')
+                throw new AuthenticationError(req.t);
+            // Payload has already read the address, so answer as usual but send nothing; resetting
+            // with the token it stores is refused below.
+            return { ...args, disableEmail: true };
+        }
+        case 'resetPassword': {
+            if (!options.passwordLogin)
+                throw refused(PASSWORD_OFF);
+            const token = data?.token;
+            const user = typeof token === 'string' && token
+                ? await findStored(req, options, [{ resetPasswordToken: token }], false)
+                : null;
+            if (passwordAllowedFor(options, user, now))
+                return args;
+            throw refused(PASSWORD_OFF);
+        }
+        case 'update': {
+            if (isSync || data?.password === undefined || data.password === null)
+                return args;
+            const self = req.user;
+            const id = args.id;
+            const ownBreakGlass = options.passwordLogin &&
+                id !== undefined &&
+                self?.id !== undefined &&
+                String(self.id) === String(id) &&
+                isBreakGlassEmail(options, self.email);
+            if (ownBreakGlass)
+                return args;
+            throw refused('Passwords are managed by the identity provider.');
+        }
+        case 'unlock':
+            throw refused(PASSWORD_OFF);
+        case 'create': {
+            if (isSync)
+                return args;
+            if (options.passwordLogin && isBreakGlassEmail(options, data?.email)) {
+                const { totalDocs } = await req.payload.count({
+                    collection: options.collection,
+                    overrideAccess: true,
+                });
+                if (totalDocs === 0) {
+                    const { [OIDC_FIELDS.disabledAt]: _disabledAt, [OIDC_FIELDS.linkable]: _linkable, [OIDC_FIELDS.subject]: _subject, ...rest } = data ?? {};
+                    return { ...args, data: rest };
+                }
+            }
+            throw refused('Users are created when they first sign in with single sign-on.');
+        }
+        case 'refresh': {
+            const user = req.user;
+            if (!user?._sid || user.collection !== options.collection)
+                return args;
+            const session = await findSession(req.payload, options, user.id, user._sid);
+            const age = session ? now.getTime() - session.createdAt.getTime() : Number.NaN;
+            // A session without a readable createdAt fails closed (NaN compares false).
+            if (!session || session.disabled || !(age >= 0 && age < options.sessionMaxSeconds * 1000)) {
+                throw refused(SESSION_ENDED);
+            }
+            return args;
+        }
+        default:
+            return args;
+    }
+};
+/**
+ * Caps a refreshed token at the session's absolute limit. Payload signs every refreshed token for
+ * the full `tokenExpiration`, and its JWT strategy never reads the session's `expiresAt`, so
+ * without this a refresh just before `sessionMaxHours` would last another `sessionHours`.
+ */
+export const createRefreshHook = (options, clock = () => new Date()) => async ({ args, user }) => {
+    if (!options.enabled)
+        return undefined;
+    const reqUser = args.req.user;
+    if (!reqUser?._sid)
+        return undefined;
+    const session = await findSession(args.req.payload, options, reqUser.id, reqUser._sid);
+    if (!session)
+        throw refused(SESSION_ENDED);
+    const remaining = Math.floor((session.createdAt.getTime() + options.sessionMaxSeconds * 1000 - clock().getTime()) / 1000);
+    if (!(remaining > 0))
+        throw refused(SESSION_ENDED);
+    if (remaining >= options.sessionSeconds)
+        return undefined;
+    const collectionConfig = args.collection.config;
+    const { exp, token } = await jwtSign({
+        fieldsToSign: getFieldsToSign({
+            collectionConfig,
+            email: user.email ?? '',
+            sid: reqUser._sid,
+            user: args.req.user,
+        }),
+        secret: args.req.payload.secret,
+        tokenExpiration: remaining,
+    });
+    return {
+        exp,
+        refreshedToken: token,
+        setCookie: true,
+        strategy: reqUser._strategy,
+        user,
+    };
+};

package/dist/endpoints.d.ts

@@ -0,0 +1,8 @@
+import type { Endpoint, PayloadRequest } from 'payload';
+import type { ResolvedOidcOptions } from './options.js';
+import { type ProviderClient } from './provider.js';
+/** Query parameter on the login page that carries a refusal code. */
+export declare const SIGN_IN_ERROR_PARAM = "oidc_error";
+/** The redirect URI registered with the provider. */
+export declare const redirectUri: (req: PayloadRequest, options: ResolvedOidcOptions) => string;
+export declare const createEndpoints: (options: ResolvedOidcOptions, client: ProviderClient, clock?: () => Date) => Endpoint[];