@signal58/payload-oidc 0.0.0 → 0.2.0

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.2.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"
+}