@signal58/payload-oidc 0.0.0 → 0.3.0

package/dist/sources/authentik.js

@@ -0,0 +1,60 @@
+/**
+ * A reconcile source that reads the role-table groups' members from Authentik's API.
+ *
+ * The token needs only object-level `view_group` on those groups: reading a group returns its
+ * direct members with their `uid`, which equals the OIDC `sub` when the provider's subject mode
+ * is "based on the user's hashed ID". Every group must exist and be readable, or the fetch throws
+ * and reconcile changes nothing.
+ *
+ * @param options.url - Authentik's base URL, such as `https://auth.example.com`.
+ * @param options.token - An API token for a service account with `view_group` on the groups.
+ * @param options.queue - The Payload jobs queue the reconcile task runs on.
+ * @param options.cron - How often it runs (default every 15 minutes).
+ * @param options.fetch - For tests.
+ */
+export const authentikSource = (options) => {
+    const url = options.url?.trim().replace(/\/+$/, '');
+    const token = options.token?.trim();
+    if (!url || !token)
+        return undefined;
+    // The token travels in the Authorization header: never in clear text outside local development.
+    if (new URL(url).protocol !== 'https:') {
+        if (!options.allowInsecure || process.env.NODE_ENV === 'production') {
+            throw new Error('payload-oidc: the Authentik reconcile URL must use https.');
+        }
+    }
+    const request = options.fetch ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const fetchGroup = async (name) => {
+        const query = new URLSearchParams({ include_users: 'true', name, page_size: '2' });
+        const response = await request(`${url}/api/v3/core/groups/?${query}`, {
+            headers: { Accept: 'application/json', Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            throw new Error(`Authentik answered ${response.status} for group ${name}.`);
+        const body = (await response.json());
+        const matches = (body.results ?? []).filter((group) => group.name === name);
+        // A missing group (renamed, or the token lost its permission) is a failure, not an empty one:
+        // otherwise a whole tier would be disabled.
+        if (matches.length !== 1)
+            throw new Error(`Authentik group ${name} not found or not readable.`);
+        const members = matches[0].users_obj;
+        if (!Array.isArray(members))
+            throw new Error(`Authentik returned no members for ${name}.`);
+        return members.map((member) => {
+            if (typeof member.uid !== 'string' || !member.uid) {
+                throw new Error(`Authentik returned a member of ${name} without a uid.`);
+            }
+            return { active: member.is_active === true, subject: member.uid };
+        });
+    };
+    return {
+        cron: options.cron ?? '*/15 * * * *',
+        fetchGroupMembers: async (groups) => {
+            const entries = await Promise.all(groups.map(async (group) => [group, await fetchGroup(group)]));
+            return new Map(entries);
+        },
+        queue: options.queue ?? 'oidc-reconcile',
+    };
+};

package/dist/store.d.ts

@@ -0,0 +1,105 @@
+import { type Payload, type SanitizedCollectionConfig } from 'payload';
+import type { ResolvedOidcOptions } from './options.js';
+/** `req.context` key that marks a write made by the plugin's sync. */
+export declare const OIDC_SYNC_CONTEXT = "oidcSync";
+/** The fields the plugin adds to the auth collection. */
+export declare const OIDC_FIELDS: {
+    readonly disabledAt: 'oidcDisabledAt';
+    readonly linkable: 'oidcLinkable';
+    readonly subject: 'oidcSubject';
+};
+type StoredSession = {
+    createdAt: Date | string;
+    expiresAt: Date | string;
+    id: string;
+};
+/** The stored shape of an auth-collection document, as far as the plugin reads it. */
+export type StoredUser = {
+    _id: unknown;
+    email?: string;
+    oidcDisabledAt?: Date | null;
+    oidcLinkable?: boolean;
+    oidcSubject?: string;
+    sessions?: StoredSession[];
+    [key: string]: unknown;
+};
+type UpdateResult = {
+    matchedCount: number;
+    modifiedCount?: number;
+};
+/** The subset of a Mongoose model the plugin needs for conditional, atomic writes. */
+export type AuthCollectionModel = {
+    find: (filter: Record<string, unknown>) => {
+        lean: () => Promise<StoredUser[]>;
+    };
+    findOne: (filter: Record<string, unknown>, projection?: Record<string, 0 | 1>) => {
+        lean: () => Promise<StoredUser | null>;
+    };
+    updateOne: (filter: Record<string, unknown>, update: Record<string, unknown> | Record<string, unknown>[], options?: Record<string, unknown>) => Promise<UpdateResult>;
+};
+/**
+ * The auth collection's Mongoose model. Session pushes and disables must be conditional, atomic
+ * updates, which Payload's adapter API can't express, so the plugin needs MongoDB.
+ */
+export declare const authCollectionModel: (payload: Payload, slug: string) => AuthCollectionModel;
+/**
+ * The auth collection's sanitized config. Typed loosely on purpose: an app's generated Payload
+ * types narrow collection slugs to its own, which a plugin can't name.
+ */
+export declare const authCollectionConfig: (payload: Payload, slug: string) => SanitizedCollectionConfig;
+/** A password hash and salt that no password matches. */
+export declare const unusablePassword: () => {
+    hash: string;
+    salt: string;
+};
+/** The value the role field stores for `role` (or for no role). */
+export declare const roleValue: (options: ResolvedOidcOptions, role: string | undefined) => string | string[] | null;
+/**
+ * Disables a user: clears the role and every session and sets `oidcDisabledAt`, in one atomic
+ * update. Clearing sessions ends access on the next request, because Payload checks the session
+ * ID on every request. The break-glass account is never matched.
+ *
+ * @returns Whether a user was disabled.
+ */
+export declare const disableUser: (payload: Payload, options: ResolvedOidcOptions, id: unknown, now: Date, 
+/** Further conditions, such as "unchanged since it was read". */
+condition?: Record<string, unknown>) => Promise<boolean>;
+/**
+ * Links an existing, never-linked snapshot user to a provider subject, by email. One atomic,
+ * conditional update sets the subject, clears `oidcLinkable` and every session, and replaces the
+ * password with one nobody knows, so the old password and old sessions stop working.
+ *
+ * @returns Whether a user was linked.
+ */
+export declare const linkByEmail: (payload: Payload, options: ResolvedOidcOptions, email: string, subject: string) => Promise<boolean>;
+/**
+ * Writes the provider-owned fields of a linked user and clears `oidcDisabledAt`, as one update of
+ * just those paths. A Payload update would write back the whole document as it read it, sessions
+ * included, so a disable landing in between would be undone.
+ *
+ * @returns Whether the user (still linked to `subject`) was updated.
+ */
+export declare const writeManagedFields: (payload: Payload, options: ResolvedOidcOptions, id: unknown, subject: string, fields: Record<string, unknown>, now: Date) => Promise<boolean>;
+/** Marks a user Payload created as verified, for collections with `auth.verify`. */
+export declare const markVerified: (payload: Payload, options: ResolvedOidcOptions, id: unknown) => Promise<void>;
+/**
+ * Whether an error is a unique index refusing the write: MongoDB's duplicate-key error from a raw
+ * model write, the `ValidationError` db-mongodb turns it into for a Payload write (with the
+ * unique field as its path, and no cause), or a transaction's write conflict on the same key.
+ */
+export declare const isDuplicateKeyError: (error: unknown, uniqueFields?: readonly string[]) => boolean;
+/**
+ * Adds a session, conditional on the user still being linked to `subject` and not disabled, as one
+ * atomic update. A whole-document write (Payload's `addSessionToUser`) could undo a disable that
+ * landed between the read and the write; this can't. Expired sessions are dropped in the same
+ * update.
+ *
+ * @returns The new session ID, or `undefined` if the user was disabled or relinked meanwhile.
+ */
+export declare const pushSession: (payload: Payload, options: ResolvedOidcOptions, id: unknown, subject: string, now: Date) => Promise<string | undefined>;
+/** One stored session, with the fields the refresh cap needs. */
+export declare const findSession: (payload: Payload, options: ResolvedOidcOptions, id: unknown, sid: string) => Promise<{
+    createdAt: Date;
+    disabled: boolean;
+} | undefined>;
+export {};

package/dist/store.js

@@ -0,0 +1,161 @@
+import crypto from 'node:crypto';
+import { ValidationError } from 'payload';
+/** `req.context` key that marks a write made by the plugin's sync. */
+export const OIDC_SYNC_CONTEXT = 'oidcSync';
+/** The fields the plugin adds to the auth collection. */
+export const OIDC_FIELDS = {
+    disabledAt: 'oidcDisabledAt',
+    linkable: 'oidcLinkable',
+    subject: 'oidcSubject',
+};
+/**
+ * The auth collection's Mongoose model. Session pushes and disables must be conditional, atomic
+ * updates, which Payload's adapter API can't express, so the plugin needs MongoDB.
+ */
+export const authCollectionModel = (payload, slug) => {
+    const model = payload.db
+        .collections?.[slug];
+    if (!model) {
+        throw new Error(`payload-oidc needs the MongoDB adapter (no model for "${slug}").`);
+    }
+    return model;
+};
+/**
+ * The auth collection's sanitized config. Typed loosely on purpose: an app's generated Payload
+ * types narrow collection slugs to its own, which a plugin can't name.
+ */
+export const authCollectionConfig = (payload, slug) => payload.collections[slug]
+    .config;
+/** A password hash and salt that no password matches. */
+export const unusablePassword = () => ({
+    hash: crypto.randomBytes(64).toString('hex'),
+    salt: crypto.randomBytes(32).toString('hex'),
+});
+/** The value the role field stores for `role` (or for no role). */
+export const roleValue = (options, role) => options.roleHasMany ? (role ? [role] : []) : (role ?? null);
+/**
+ * Disables a user: clears the role and every session and sets `oidcDisabledAt`, in one atomic
+ * update. Clearing sessions ends access on the next request, because Payload checks the session
+ * ID on every request. The break-glass account is never matched.
+ *
+ * @returns Whether a user was disabled.
+ */
+export const disableUser = async (payload, options, id, now, 
+/** Further conditions, such as "unchanged since it was read". */
+condition = {}) => {
+    const filter = { ...condition, _id: id };
+    if (options.breakGlassEmail)
+        filter.email = { $ne: options.breakGlassEmail };
+    const result = await authCollectionModel(payload, options.collection).updateOne(filter, {
+        $set: {
+            [OIDC_FIELDS.disabledAt]: now,
+            [options.roleField]: roleValue(options, undefined),
+            sessions: [],
+        },
+    });
+    return result.matchedCount > 0;
+};
+/**
+ * Links an existing, never-linked snapshot user to a provider subject, by email. One atomic,
+ * conditional update sets the subject, clears `oidcLinkable` and every session, and replaces the
+ * password with one nobody knows, so the old password and old sessions stop working.
+ *
+ * @returns Whether a user was linked.
+ */
+export const linkByEmail = async (payload, options, email, subject) => {
+    // The break-glass account keeps its password: it is never linked, even if the migration marked it.
+    if (options.breakGlassEmail && email === options.breakGlassEmail)
+        return false;
+    const result = await authCollectionModel(payload, options.collection).updateOne({
+        email,
+        [OIDC_FIELDS.linkable]: true,
+        [OIDC_FIELDS.subject]: { $exists: false },
+    }, {
+        $set: {
+            [OIDC_FIELDS.subject]: subject,
+            sessions: [],
+            ...unusablePassword(),
+            ...(options.verify ? { _verified: true } : {}),
+        },
+        $unset: { [OIDC_FIELDS.linkable]: '' },
+    });
+    return result.matchedCount > 0;
+};
+/**
+ * Writes the provider-owned fields of a linked user and clears `oidcDisabledAt`, as one update of
+ * just those paths. A Payload update would write back the whole document as it read it, sessions
+ * included, so a disable landing in between would be undone.
+ *
+ * @returns Whether the user (still linked to `subject`) was updated.
+ */
+export const writeManagedFields = async (payload, options, id, subject, fields, now) => {
+    const result = await authCollectionModel(payload, options.collection).updateOne({ _id: id, [OIDC_FIELDS.subject]: subject }, { $set: { ...fields, [OIDC_FIELDS.disabledAt]: null, updatedAt: now } });
+    return result.matchedCount > 0;
+};
+/** Marks a user Payload created as verified, for collections with `auth.verify`. */
+export const markVerified = async (payload, options, id) => {
+    if (!options.verify)
+        return;
+    await authCollectionModel(payload, options.collection).updateOne({ _id: id }, { $set: { _verified: true }, $unset: { _verificationToken: '' } });
+};
+/**
+ * Whether an error is a unique index refusing the write: MongoDB's duplicate-key error from a raw
+ * model write, the `ValidationError` db-mongodb turns it into for a Payload write (with the
+ * unique field as its path, and no cause), or a transaction's write conflict on the same key.
+ */
+export const isDuplicateKeyError = (error, uniqueFields = []) => {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const candidate = error;
+    if (candidate.code === 11000 || candidate.cause?.code === 11000)
+        return true;
+    // Inside a replica-set transaction a concurrent insert of the same key is a write conflict.
+    if (candidate.code === 112 || candidate.cause?.code === 112)
+        return true;
+    return Boolean(error instanceof ValidationError &&
+        candidate.data?.errors?.some((entry) => uniqueFields.includes(String(entry.path))));
+};
+/**
+ * Adds a session, conditional on the user still being linked to `subject` and not disabled, as one
+ * atomic update. A whole-document write (Payload's `addSessionToUser`) could undo a disable that
+ * landed between the read and the write; this can't. Expired sessions are dropped in the same
+ * update.
+ *
+ * @returns The new session ID, or `undefined` if the user was disabled or relinked meanwhile.
+ */
+export const pushSession = async (payload, options, id, subject, now) => {
+    const sid = crypto.randomUUID();
+    const session = {
+        createdAt: now,
+        expiresAt: new Date(now.getTime() + options.sessionSeconds * 1000),
+        id: sid,
+    };
+    const result = await authCollectionModel(payload, options.collection).updateOne({ _id: id, [OIDC_FIELDS.disabledAt]: null, [OIDC_FIELDS.subject]: subject }, [
+        {
+            $set: {
+                sessions: {
+                    $concatArrays: [
+                        {
+                            $filter: {
+                                cond: { $gt: ['$$this.expiresAt', now] },
+                                input: { $ifNull: ['$sessions', []] },
+                            },
+                        },
+                        [session],
+                    ],
+                },
+            },
+        },
+    ]);
+    return result.matchedCount > 0 ? sid : undefined;
+};
+/** One stored session, with the fields the refresh cap needs. */
+export const findSession = async (payload, options, id, sid) => {
+    const user = await authCollectionModel(payload, options.collection)
+        .findOne({ _id: id }, { [OIDC_FIELDS.disabledAt]: 1, sessions: 1 })
+        .lean();
+    const session = user?.sessions?.find((candidate) => candidate.id === sid);
+    if (!user || !session)
+        return undefined;
+    return { createdAt: new Date(session.createdAt), disabled: Boolean(user.oidcDisabledAt) };
+};

package/dist/test/fake-provider.d.ts

@@ -0,0 +1,27 @@
+/** The claims the fake provider puts in the next ID token. */
+export type FakeUser = {
+    email: string;
+    email_verified?: boolean;
+    family_name?: string;
+    given_name?: string;
+    groups?: string[];
+    name?: string;
+    sub: string;
+};
+/**
+ * A minimal OpenID Connect provider on 127.0.0.1 for tests: discovery, JWKS, an authorization
+ * endpoint that signs in `nextUser` at once, and a token endpoint that checks the client secret,
+ * the code, the redirect URI and the PKCE verifier, then issues an RS256 ID token.
+ */
+export declare const startFakeProvider: (client: {
+    id: string;
+    secret: string;
+}) => Promise<{
+    close: () => Promise<void>;
+    state: {
+        /** Signs the ID token with a key the JWKS doesn't publish. */
+        forgeSignature: boolean;
+        issuer: string;
+        nextUser: FakeUser | undefined;
+    };
+}>;

package/dist/test/fake-provider.js

@@ -0,0 +1,103 @@
+import crypto from 'node:crypto';
+import http from 'node:http';
+import { exportJWK, generateKeyPair, SignJWT } from 'jose';
+/**
+ * A minimal OpenID Connect provider on 127.0.0.1 for tests: discovery, JWKS, an authorization
+ * endpoint that signs in `nextUser` at once, and a token endpoint that checks the client secret,
+ * the code, the redirect URI and the PKCE verifier, then issues an RS256 ID token.
+ */
+export const startFakeProvider = async (client) => {
+    const { privateKey, publicKey } = await generateKeyPair('RS256');
+    const jwk = { ...(await exportJWK(publicKey)), alg: 'RS256', kid: 'test-key', use: 'sig' };
+    const codes = new Map();
+    const state = {
+        /** Signs the ID token with a key the JWKS doesn't publish. */
+        forgeSignature: false,
+        issuer: '',
+        nextUser: undefined,
+    };
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', state.issuer);
+        const json = (status, body) => {
+            res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(body));
+        };
+        if (url.pathname === '/.well-known/openid-configuration') {
+            return json(200, {
+                authorization_endpoint: `${state.issuer}/authorize`,
+                code_challenge_methods_supported: ['S256'],
+                id_token_signing_alg_values_supported: ['RS256'],
+                issuer: state.issuer,
+                jwks_uri: `${state.issuer}/jwks`,
+                response_types_supported: ['code'],
+                subject_types_supported: ['public'],
+                token_endpoint: `${state.issuer}/token`,
+                token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post'],
+            });
+        }
+        if (url.pathname === '/jwks')
+            return json(200, { keys: [jwk] });
+        if (url.pathname === '/authorize') {
+            const params = url.searchParams;
+            if (!state.nextUser || params.get('client_id') !== client.id)
+                return json(400, {});
+            const code = crypto.randomBytes(16).toString('hex');
+            codes.set(code, {
+                challenge: params.get('code_challenge') ?? '',
+                clientId: client.id,
+                nonce: params.get('nonce') ?? '',
+                redirectUri: params.get('redirect_uri') ?? '',
+                user: state.nextUser,
+            });
+            const back = new URL(params.get('redirect_uri') ?? '');
+            back.searchParams.set('code', code);
+            back.searchParams.set('state', params.get('state') ?? '');
+            back.searchParams.set('iss', state.issuer);
+            res.writeHead(302, { location: back.href }).end();
+            return;
+        }
+        if (url.pathname === '/token' && req.method === 'POST') {
+            const body = new URLSearchParams(await new Promise((resolve) => {
+                let data = '';
+                req.on('data', (chunk) => (data += chunk));
+                req.on('end', () => resolve(data));
+            }));
+            const basic = Buffer.from(`${encodeURIComponent(client.id)}:${encodeURIComponent(client.secret)}`).toString('base64');
+            const posted = body.get('client_id') === client.id && body.get('client_secret') === client.secret;
+            if (req.headers.authorization !== `Basic ${basic}` && !posted) {
+                return json(401, { error: 'invalid_client' });
+            }
+            const pending = codes.get(body.get('code') ?? '');
+            codes.delete(body.get('code') ?? '');
+            const verifier = body.get('code_verifier') ?? '';
+            const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+            if (!pending ||
+                pending.redirectUri !== body.get('redirect_uri') ||
+                pending.challenge !== challenge) {
+                return json(400, { error: 'invalid_grant' });
+            }
+            const signingKey = state.forgeSignature
+                ? (await generateKeyPair('RS256')).privateKey
+                : privateKey;
+            const idToken = await new SignJWT({ ...pending.user, nonce: pending.nonce })
+                .setProtectedHeader({ alg: 'RS256', kid: 'test-key' })
+                .setIssuer(state.issuer)
+                .setAudience(client.id)
+                .setIssuedAt()
+                .setExpirationTime('5m')
+                .sign(signingKey);
+            return json(200, {
+                access_token: 'unused',
+                expires_in: 300,
+                id_token: idToken,
+                token_type: 'Bearer',
+            });
+        }
+        json(404, {});
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    state.issuer = `http://127.0.0.1:${server.address().port}`;
+    return {
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+        state,
+    };
+};

package/dist/transaction.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The sign-in transaction: what `authorize` hands to `callback` through the browser. It is sealed
+ * with AES-256-GCM under a key derived from the Payload secret, so the browser can neither read
+ * the PKCE verifier and nonce nor change the return path.
+ */
+export type SignInTransaction = {
+    /** When the transaction was created, in milliseconds since the epoch. */
+    createdAt: number;
+    nonce: string;
+    returnTo: string;
+    state: string;
+    verifier: string;
+};
+/** How long the provider round trip may take. */
+export declare const TRANSACTION_MAX_AGE_SECONDS = 600;
+/** Seals a transaction for the cookie. */
+export declare const sealTransaction: (secret: string, transaction: SignInTransaction) => string;
+/**
+ * Opens a sealed transaction.
+ *
+ * @returns The transaction, or `undefined` if it was tampered with, sealed under another secret,
+ *   malformed, or older than {@link TRANSACTION_MAX_AGE_SECONDS}.
+ */
+export declare const openTransaction: (secret: string, sealed: string | undefined, now: Date) => SignInTransaction | undefined;
+/**
+ * The path to return to after sign-in: only paths under the admin route.
+ *
+ * Rejects absolute and scheme-relative URLs (`//host`, `/\host`), backslashes, control
+ * characters, and anything that doesn't stay under `adminRoute` once normalised.
+ *
+ * @param requested - The `redirect` the admin passed, if any.
+ * @param adminRoute - The admin route, such as `/admin`.
+ * @returns A safe same-origin path.
+ */
+export declare const safeReturnPath: (requested: unknown, adminRoute: string) => string;

package/dist/transaction.js

@@ -0,0 +1,89 @@
+import crypto from 'node:crypto';
+/** How long the provider round trip may take. */
+export const TRANSACTION_MAX_AGE_SECONDS = 600;
+const KEY_INFO = 'payload-oidc sign-in transaction v1';
+const transactionKey = (secret) => Buffer.from(crypto.hkdfSync('sha256', secret, Buffer.alloc(0), KEY_INFO, 32));
+/** Seals a transaction for the cookie. */
+export const sealTransaction = (secret, transaction) => {
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', transactionKey(secret), iv);
+    const body = Buffer.concat([cipher.update(JSON.stringify(transaction), 'utf8'), cipher.final()]);
+    return [iv, body, cipher.getAuthTag()].map((part) => part.toString('base64url')).join('.');
+};
+const isTransaction = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return (typeof record.createdAt === 'number' &&
+        ['nonce', 'returnTo', 'state', 'verifier'].every((key) => typeof record[key] === 'string'));
+};
+/**
+ * Opens a sealed transaction.
+ *
+ * @returns The transaction, or `undefined` if it was tampered with, sealed under another secret,
+ *   malformed, or older than {@link TRANSACTION_MAX_AGE_SECONDS}.
+ */
+export const openTransaction = (secret, sealed, now) => {
+    if (!sealed)
+        return undefined;
+    const parts = sealed.split('.');
+    if (parts.length !== 3)
+        return undefined;
+    try {
+        const [iv, body, tag] = parts.map((part) => Buffer.from(part, 'base64url'));
+        // A full 16-byte tag only: GCM would otherwise accept a truncated one.
+        if (iv.length !== 12 || tag.length !== 16)
+            return undefined;
+        const decipher = crypto.createDecipheriv('aes-256-gcm', transactionKey(secret), iv, {
+            authTagLength: 16,
+        });
+        decipher.setAuthTag(tag);
+        const json = Buffer.concat([decipher.update(body), decipher.final()]).toString('utf8');
+        const transaction = JSON.parse(json);
+        if (!isTransaction(transaction))
+            return undefined;
+        const age = now.getTime() - transaction.createdAt;
+        if (age < 0 || age > TRANSACTION_MAX_AGE_SECONDS * 1000)
+            return undefined;
+        return transaction;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The path to return to after sign-in: only paths under the admin route.
+ *
+ * Rejects absolute and scheme-relative URLs (`//host`, `/\host`), backslashes, control
+ * characters, and anything that doesn't stay under `adminRoute` once normalised.
+ *
+ * @param requested - The `redirect` the admin passed, if any.
+ * @param adminRoute - The admin route, such as `/admin`.
+ * @returns A safe same-origin path.
+ */
+export const safeReturnPath = (requested, adminRoute) => {
+    const fallback = adminRoute || '/';
+    if (typeof requested !== 'string' || requested.length === 0 || requested.length > 2048) {
+        return fallback;
+    }
+    // Raw input checks first: a backslash or control character is never needed in an admin path.
+    // oxlint-disable-next-line no-control-regex
+    if (!requested.startsWith('/') || /[\\\u0000-\u001f\u007f]/.test(requested))
+        return fallback;
+    if (requested.startsWith('//'))
+        return fallback;
+    let parsed;
+    try {
+        parsed = new URL(requested, 'http://payload-oidc.invalid');
+    }
+    catch {
+        return fallback;
+    }
+    if (parsed.origin !== 'http://payload-oidc.invalid')
+        return fallback;
+    const path = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+    const root = adminRoute.replace(/\/+$/, '');
+    if (root && parsed.pathname !== root && !parsed.pathname.startsWith(`${root}/`))
+        return fallback;
+    return path;
+};

package/package.json

@@ -1 +1,92 @@
-{"name":"@signal58/payload-oidc","version":"0.0.0","description":"Placeholder; the first release is 0.2.0.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/Signal-58/payload-oidc.git"}}
+{
+  "name": "@signal58/payload-oidc",
+  "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",
+    "oidc",
+    "openid-connect",
+    "payload",
+    "payload-plugin",
+    "payloadcms",
+    "sso"
+  ],
+  "homepage": "https://github.com/Signal-58/payload-oidc#readme",
+  "bugs": "https://github.com/Signal-58/payload-oidc/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Signal-58/payload-oidc.git"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./rsc": {
+      "types": "./dist/exports/rsc.d.ts",
+      "default": "./dist/exports/rsc.js"
+    },
+    "./testing": {
+      "types": "./dist/test/fake-provider.d.ts",
+      "default": "./dist/test/fake-provider.js"
+    },
+    "./client": {
+      "types": "./dist/exports/client.d.ts",
+      "default": "./dist/exports/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "check": "tsc --noEmit && oxlint",
+    "check:package": "publint --strict && attw --pack . --profile esm-only",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint",
+    "prepack": "node scripts/build.mjs",
+    "test": "vitest run",
+    "test:integration": "node scripts/test-integration.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "jose": "^6.2.12",
+    "openid-client": "6.8.8"
+  },
+  "peerDependencies": {
+    "@payloadcms/ui": "^3.91.0",
+    "payload": "^3.91.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@payloadcms/db-mongodb": "3.92.1",
+    "@payloadcms/ui": "3.92.1",
+    "@types/node": "22.18.0",
+    "@types/react": "19.2.14",
+    "mongodb": "6.20.0",
+    "next": "16.4.3",
+    "oxfmt": "0.53.0",
+    "oxlint": "1.77.0",
+    "payload": "3.92.1",
+    "publint": "0.3.25",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@11.20.0"
+}