@signal58/payload-oidc 0.0.0-stage → 0.2.0

package/dist/plugin.js

@@ -0,0 +1,217 @@
+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, 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.
+ */
+const withSyncOnlyUpdate = (fields, names, found) => 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 } };
+    }
+    if (field.type === 'row' || field.type === 'collapsible') {
+        return { ...field, fields: withSyncOnlyUpdate(field.fields, names, found) };
+    }
+    return field;
+});
+/** 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 = withSyncOnlyUpdate(fields, names, found);
+    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: [
+            ...(options.enabled ? lockManagedFields(target, options) : (target.fields ?? [])),
+            ...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,12 @@
+import type { TaskConfig } from 'payload';
+import type { ResolvedOidcOptions } from './options.js';
+export declare const RECONCILE_TASK_SLUG = "payload-oidc-reconcile";
+/**
+ * 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;

package/dist/reconcile-task.js

@@ -0,0 +1,48 @@
+import { reconcileUsers } from './reconcile.js';
+export const RECONCILE_TASK_SLUG = 'payload-oidc-reconcile';
+/**
+ * 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 const createReconcileTask = (options, { clock = () => new Date(), concurrencyControl = false } = {}) => ({
+    slug: RECONCILE_TASK_SLUG,
+    label: 'Reconcile CMS users with the identity provider',
+    // One run at a time where the app enables Payload's concurrency control; otherwise Payload's
+    // scheduler still skips a schedule while a run is queued or running.
+    ...(concurrencyControl ? { concurrency: () => RECONCILE_TASK_SLUG } : {}),
+    inputSchema: [],
+    outputSchema: [
+        { name: 'disabled', type: 'number', required: true },
+        { name: 'roleChanges', type: 'number', required: true },
+        { name: 'users', type: 'number', required: true },
+    ],
+    retries: 0,
+    ...(options.enabled && options.reconcile
+        ? {
+            schedule: [
+                {
+                    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,
+                        }),
+                    },
+                    queue: options.reconcile.queue,
+                },
+            ],
+        }
+        : {}),
+    handler: async ({ req }) => {
+        if (!options.enabled || !options.reconcile) {
+            return { output: { disabled: 0, roleChanges: 0, users: 0 } };
+        }
+        const { disabled, roleChanges, users } = await reconcileUsers(req.payload, options, clock());
+        return { output: { disabled, roleChanges, users } };
+    },
+});

package/dist/reconcile.d.ts

@@ -0,0 +1,32 @@
+import type { Payload } from 'payload';
+import { type ResolvedOidcOptions } from './options.js';
+/** KV key of the last successful reconcile run. */
+export declare const RECONCILE_HEARTBEAT_KEY = "payload-oidc:reconcile";
+export type ReconcileHeartbeat = {
+    disabled: number;
+    finishedAt: string;
+    roleChanges: number;
+    users: number;
+};
+export type ReconcileResult = ReconcileHeartbeat;
+/**
+ * Brings every linked user in line with the provider's groups:
+ *
+ * - A user whose subject is in no role-table group, or only as an inactive member, is disabled
+ *   (again, if a whole-document write restored their role or sessions).
+ * - An enabled user whose role changed gets the new role. A disabled user stays disabled until
+ *   they sign in again.
+ * - Users are never created, and the break-glass account and unlinked users are never touched.
+ *
+ * It changes nothing unless every group was read, and stops without changes if it would disable
+ * more than `maxDisableShare` of the linked users (at least one is always allowed), so a renamed
+ * group or a lost permission can't disable a whole tier. Each successful run records a heartbeat.
+ *
+ * @throws When a group can't be read or a safety stop trips: the job fails and alerts.
+ */
+export declare const reconcileUsers: (payload: Payload, options: ResolvedOidcOptions, now?: Date) => Promise<ReconcileResult>;
+/** Whether the last successful run is recent enough, for a status check such as Gatus. */
+export declare const reconcileHealth: (payload: Payload, options: ResolvedOidcOptions, now?: Date) => Promise<{
+    healthy: boolean;
+    lastSuccessAt: string | null;
+}>;

package/dist/reconcile.js

@@ -0,0 +1,110 @@
+import { isBreakGlassEmail, roleForGroups, roleTableGroups, } from './options.js';
+import { authCollectionModel, disableUser, OIDC_FIELDS, roleValue } from './store.js';
+/** KV key of the last successful reconcile run. */
+export const RECONCILE_HEARTBEAT_KEY = 'payload-oidc:reconcile';
+/**
+ * Brings every linked user in line with the provider's groups:
+ *
+ * - A user whose subject is in no role-table group, or only as an inactive member, is disabled
+ *   (again, if a whole-document write restored their role or sessions).
+ * - An enabled user whose role changed gets the new role. A disabled user stays disabled until
+ *   they sign in again.
+ * - Users are never created, and the break-glass account and unlinked users are never touched.
+ *
+ * It changes nothing unless every group was read, and stops without changes if it would disable
+ * more than `maxDisableShare` of the linked users (at least one is always allowed), so a renamed
+ * group or a lost permission can't disable a whole tier. Each successful run records a heartbeat.
+ *
+ * @throws When a group can't be read or a safety stop trips: the job fails and alerts.
+ */
+export const reconcileUsers = async (payload, options, now = new Date()) => {
+    const source = options.reconcile;
+    if (!source)
+        throw new Error('payload-oidc: reconcile is not configured.');
+    // Users first, then groups: every write below is conditional on the user being unchanged
+    // since this read, so someone who signs in (and is synced) while the groups are fetched is left
+    // for the next run instead of being judged on a stale snapshot.
+    const model = authCollectionModel(payload, options.collection);
+    const linked = await model.find({ [OIDC_FIELDS.subject]: { $exists: true } }).lean();
+    const groups = roleTableGroups(options.roleTable);
+    const members = await source.fetchGroupMembers(groups);
+    const groupsBySubject = new Map();
+    for (const group of groups) {
+        const list = members.get(group);
+        if (!list)
+            throw new Error(`payload-oidc: reconcile got no answer for group ${group}.`);
+        for (const member of list) {
+            if (!member.active)
+                continue;
+            groupsBySubject.set(member.subject, [...(groupsBySubject.get(member.subject) ?? []), group]);
+        }
+    }
+    const unchanged = (user) => ({
+        _id: user._id,
+        [OIDC_FIELDS.subject]: user[OIDC_FIELDS.subject],
+        updatedAt: user.updatedAt ?? null,
+    });
+    const newlyDisabled = [];
+    const redisabled = [];
+    const toChange = [];
+    let enabled = 0;
+    for (const user of linked) {
+        if (isBreakGlassEmail(options, user.email))
+            continue;
+        const isDisabled = Boolean(user[OIDC_FIELDS.disabledAt]);
+        if (!isDisabled)
+            enabled += 1;
+        const role = roleForGroups(options.roleTable, groupsBySubject.get(String(user[OIDC_FIELDS.subject])));
+        const stored = user[options.roleField];
+        const hasRole = Array.isArray(stored) ? stored.length > 0 : Boolean(stored);
+        const sessions = Array.isArray(user.sessions) ? user.sessions.length : 0;
+        if (!role) {
+            if (!isDisabled)
+                newlyDisabled.push(user);
+            // Disabled already, but a whole-document write restored the role or sessions.
+            else if (hasRole || sessions > 0)
+                redisabled.push(user);
+            continue;
+        }
+        if (isDisabled)
+            continue;
+        if (JSON.stringify(stored) !== JSON.stringify(roleValue(options, role))) {
+            toChange.push({ role, user });
+        }
+    }
+    // The share counts enabled users only: disabled ones that were never removed would otherwise
+    // inflate it until a whole tier fits under the limit.
+    const allowed = Math.max(1, Math.floor(enabled * options.reconcileMaxDisableShare));
+    if (newlyDisabled.length > allowed) {
+        throw new Error(`payload-oidc: reconcile would disable ${newlyDisabled.length} of ${enabled} enabled users (more than ${allowed}); nothing was changed. If that is intended, raise reconcileMaxDisableShare for one run.`);
+    }
+    let disabled = 0;
+    for (const user of [...newlyDisabled, ...redisabled]) {
+        if (await disableUser(payload, options, user._id, now, unchanged(user)))
+            disabled += 1;
+    }
+    let roleChanges = 0;
+    for (const { role, user } of toChange) {
+        // Only while still enabled and unchanged: a disable or a sign-in that landed meanwhile wins.
+        const result = await model.updateOne({ ...unchanged(user), [OIDC_FIELDS.disabledAt]: null }, { $set: { [options.roleField]: roleValue(options, role), updatedAt: now } });
+        if (result.matchedCount > 0)
+            roleChanges += 1;
+    }
+    const heartbeat = {
+        disabled,
+        finishedAt: now.toISOString(),
+        roleChanges,
+        users: linked.length,
+    };
+    await payload.kv.set(RECONCILE_HEARTBEAT_KEY, heartbeat);
+    payload.logger.info({ msg: 'payload-oidc: reconcile finished', ...heartbeat });
+    return heartbeat;
+};
+/** Whether the last successful run is recent enough, for a status check such as Gatus. */
+export const reconcileHealth = async (payload, options, now = new Date()) => {
+    const heartbeat = await payload.kv.get(RECONCILE_HEARTBEAT_KEY);
+    const finishedAt = heartbeat?.finishedAt ? new Date(heartbeat.finishedAt) : undefined;
+    const healthy = Boolean(finishedAt &&
+        now.getTime() - finishedAt.getTime() <= options.reconcileHeartbeatMaxSeconds * 1000);
+    return { healthy, lastSuccessAt: heartbeat?.finishedAt ?? null };
+};

package/dist/remove.d.ts

@@ -0,0 +1,29 @@
+import type { Payload, SanitizedCollectionConfig, SanitizedGlobalConfig } from 'payload';
+import { type ResolvedOidcOptions } from './options.js';
+/** A place a document can point at a user: a collection or global, and a dotted field path. */
+export type UserReference = {
+    entity: 'collection' | 'global';
+    path: string;
+    slug: string;
+    versions: boolean;
+};
+/**
+ * Every field in the config that can refer to a user of `collection`, except Payload's own
+ * bookkeeping (preferences, locks, jobs, migrations), which belongs to the user and goes with it.
+ * Rich-text relationships aren't seen; anything referenced only there is left as a dangling link.
+ */
+export declare const findUserReferences: (collections: SanitizedCollectionConfig[], globals: SanitizedGlobalConfig[], collection: string) => UserReference[];
+export type RemoveOutcome = {
+    kind: 'anonymised' | 'deleted';
+} | {
+    kind: 'refused';
+    reason: 'break_glass' | 'not_disabled' | 'not_found';
+};
+/**
+ * Removes a disabled user. Only disabled users: an active one would be created again at their
+ * next sign-in. If nothing refers to the user they are deleted; otherwise they are anonymised
+ * (names "Removed user", email `removed-<id>@removed.invalid`, every other profile field, the
+ * subject, password and sessions gone) so bylines and audit rows still resolve. Someone added back at the provider later signs
+ * in as a new user.
+ */
+export declare const removeUser: (payload: Payload, options: ResolvedOidcOptions, id: string | number) => Promise<RemoveOutcome>;