@udibo/oauth2 0.14.0 → 0.15.0

package/dist/cli/idp/mod.js

@@ -0,0 +1,175 @@
+/**
+ * The `idp dev` command: runs the development identity provider from a config
+ * file (or the built-in demo config) and prints what it seeded.
+ *
+ * @module
+ */
+import { generateSigningKey, importSigningKeyJwk, } from "../../server/signing-keys.js";
+import { defaultDevIdpConfig, loadDevIdpConfig, } from "./config.js";
+import { ADMIN_TOKEN_HEADER, isLoopbackHostname, startDevIdentityProvider, } from "./server.js";
+const SIGNING_KEY_VARIABLE = "OIDC_SIGNING_KEY";
+const ADMIN_TOKEN_VARIABLE = "IDP_ADMIN_TOKEN";
+const VALUE_FLAGS = [
+    "--config",
+    "--port",
+    "--hostname",
+    "--issuer",
+    "--admin-token",
+];
+const BOOLEAN_FLAGS = ["--unsafe-remote-access"];
+function parseIdpDevArgs(args) {
+    const parsed = {};
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        const separator = argument.indexOf("=");
+        const flag = separator === -1 ? argument : argument.slice(0, separator);
+        if (BOOLEAN_FLAGS.includes(flag) && separator === -1) {
+            parsed.allowRemoteAccess = true;
+            continue;
+        }
+        if (!VALUE_FLAGS.includes(flag)) {
+            throw new Error(`unknown option "${argument}" (expected one of: ${[
+                ...VALUE_FLAGS,
+                ...BOOLEAN_FLAGS,
+            ].join(", ")})`);
+        }
+        const value = separator === -1 ? args[++index] : argument.slice(separator + 1);
+        if (value === undefined || value.length === 0) {
+            throw new Error(`${flag} requires a value`);
+        }
+        if (flag === "--config")
+            parsed.configPath = value;
+        if (flag === "--hostname")
+            parsed.hostname = value;
+        if (flag === "--issuer")
+            parsed.issuer = value;
+        if (flag === "--admin-token")
+            parsed.adminToken = value;
+        if (flag === "--port") {
+            const port = Number(value);
+            if (!Number.isInteger(port) || port < 0 || port > 65535) {
+                throw new Error(`--port must be an integer between 0 and 65535`);
+            }
+            parsed.port = port;
+        }
+    }
+    return parsed;
+}
+function readVariable(name) {
+    return process.env[name] || undefined;
+}
+async function resolveSigningKey(config) {
+    const fromEnvironment = readVariable(SIGNING_KEY_VARIABLE);
+    if (fromEnvironment) {
+        let jwk;
+        try {
+            jwk = JSON.parse(fromEnvironment);
+        }
+        catch {
+            throw new Error(`${SIGNING_KEY_VARIABLE} is not valid JSON`);
+        }
+        return {
+            key: await importSigningKeyJwk(jwk),
+            source: SIGNING_KEY_VARIABLE,
+        };
+    }
+    if (config.signingKey) {
+        return {
+            key: await importSigningKeyJwk(config.signingKey),
+            source: "the config file",
+        };
+    }
+    return { key: await generateSigningKey(), source: "" };
+}
+function describeSeed(config) {
+    const lines = ["Users:"];
+    if (config.users.length === 0)
+        lines.push("  (none)");
+    for (const user of config.users) {
+        lines.push(`  ${user.username}  password: ${user.password}  sub: ${user.id}`);
+    }
+    lines.push("", "Clients:");
+    if (config.clients.length === 0)
+        lines.push("  (none)");
+    for (const client of config.clients) {
+        lines.push(`  ${client.id}  ${client.secret ? `secret: ${client.secret}` : "public client"}`, `    grants: ${client.grants.join(", ")}`, `    redirect URIs: ${client.redirectUris.join(", ") || "(none)"}`);
+    }
+    return lines;
+}
+/**
+ * Runs the development identity provider until the process is stopped.
+ *
+ * Accepts `--config <path>`, `--port <number>`, `--hostname <host>`,
+ * `--issuer <url>`, `--admin-token <token>`, and `--unsafe-remote-access`;
+ * flags win over the config file, which wins over the built-in demo config.
+ * `IDP_ADMIN_TOKEN` supplies the admin token when the flag is absent.
+ *
+ * Aborting `signal` shuts the server down and resolves the returned promise.
+ *
+ * @throws {Error} When an option or the config file is invalid, or when the
+ * bind address is not loopback and `--unsafe-remote-access` was not passed.
+ */
+export async function idpDev(args, signal) {
+    const options = parseIdpDevArgs(args);
+    const config = options.configPath
+        ? await loadDevIdpConfig(options.configPath)
+        : defaultDevIdpConfig();
+    if (options.port !== undefined)
+        config.port = options.port;
+    if (options.hostname !== undefined)
+        config.hostname = options.hostname;
+    if (options.issuer !== undefined)
+        config.issuer = options.issuer;
+    const { key, source } = await resolveSigningKey(config);
+    const idp = await startDevIdentityProvider({
+        config,
+        signingKey: key,
+        adminToken: options.adminToken ?? readVariable(ADMIN_TOKEN_VARIABLE),
+        allowRemoteAccess: options.allowRemoteAccess,
+    });
+    const loopback = isLoopbackHostname(idp.hostname);
+    const stop = () => void idp.shutdown();
+    if (signal?.aborted)
+        stop();
+    else
+        signal?.addEventListener("abort", stop, { once: true });
+    console.log([
+        "@udibo/oauth2 development identity provider",
+        "",
+        "  DEVELOPMENT AND CI ONLY. State is in memory and the /__admin/",
+        "  endpoints mint tokens for any seeded user without their password.",
+        "  Never expose this server to a network you do not control.",
+        "",
+        `Listening on ${idp.url}`,
+        `Reachable from: ${loopback
+            ? "this machine only (loopback)"
+            : `ANY HOST THAT CAN REACH ${idp.hostname}:${idp.port} — remote access was enabled explicitly`}`,
+        `Issuer: ${idp.issuer}${config.issuer
+            ? ""
+            : " (derived from the bind address; pin it with --issuer)"}`,
+        `Discovery: ${idp.url}/.well-known/openid-configuration`,
+        `JWKS: ${idp.url}/jwks`,
+        `Signing key: ${source
+            ? `loaded from ${source} (kid ${key.kid})`
+            : `generated (kid ${key.kid})`}`,
+        `Consent: ${config.consent === "prompt" ? "prompted" : "granted automatically"}`,
+        "",
+        `Admin token: ${idp.adminToken}`,
+        `  Send it as the ${ADMIN_TOKEN_HEADER} header on every /__admin/ request.`,
+        `  Set ${ADMIN_TOKEN_VARIABLE} or --admin-token to choose it yourself.`,
+        "",
+        ...describeSeed(config),
+    ].join("\n"));
+    if (!loopback) {
+        console.error(`\nWARNING: bound to ${idp.hostname}, which is not loopback. Anyone who ` +
+            `can reach this port and read the admin token can mint tokens for any ` +
+            `seeded user. Only do this on a network you control, such as a CI ` +
+            `job's private network.`);
+    }
+    if (!source) {
+        console.error(`\nNo ${SIGNING_KEY_VARIABLE} and no "signingKey" in the config: this ` +
+            `key exists only for this process, so tokens and JWKS change on ` +
+            `every restart. Pin one with "udibo-oauth2 oidc keygen".`);
+    }
+    await idp.finished;
+}

package/dist/cli/idp/pages.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The development identity provider's HTML: a sign-in page, a consent screen,
+ * and the status page served at `/`.
+ *
+ * Hand-written markup with no client-side JavaScript, so the pages render the
+ * same in a browser and in a `fetch`-driven test. Every control a test needs
+ * carries a stable `id` and `name`.
+ *
+ * @module
+ */
+import type { DevIdpClientConfig, DevIdpUserConfig } from "./config.ts";
+/** Wraps HTML in a `Response` with the headers a browser and a test expect. */
+export declare function htmlResponse(html: string, status?: number): Response;
+/** Options for {@link loginPage}. */
+export interface LoginPageOptions {
+    /** URL to continue to after a successful sign-in, usually the authorize URL. */
+    returnTo: string;
+    /** Seeded users, offered as one-click sign-in buttons. */
+    users: readonly DevIdpUserConfig[];
+    /** Message to show above the form after a failed attempt. */
+    error?: string;
+}
+/**
+ * The sign-in page. Submits to `POST /login` with `username` + `password`, or
+ * with `as=<username>` from a one-click button.
+ */
+export declare function loginPage(options: LoginPageOptions): string;
+/** Options for {@link consentPage}. */
+export interface ConsentPageOptions {
+    /** Client asking for access. */
+    clientId: string;
+    /** Scope being requested, or `undefined` when the request named none. */
+    scope?: string;
+    /** Signed-in user's login name. */
+    username: string;
+    /** Authorize URL to resume once the decision is recorded. */
+    returnTo: string;
+}
+/**
+ * The consent screen shown when the config sets `"consent": "prompt"`.
+ * Submits to `POST /consent` with `decision=approve` or `decision=deny`.
+ */
+export declare function consentPage(options: ConsentPageOptions): string;
+/** Options for {@link statusPage}. */
+export interface StatusPageOptions {
+    /** Issuer as resolved for this request. */
+    issuer: string;
+    /** Seeded users. */
+    users: readonly DevIdpUserConfig[];
+    /** Registered clients. */
+    clients: readonly DevIdpClientConfig[];
+}
+/** The page served at `/`: what is seeded and where the endpoints are. */
+export declare function statusPage(options: StatusPageOptions): string;
+/** A terminal page for a flow that ended without a redirect. */
+export declare function messagePage(title: string, message: string): string;

package/dist/cli/idp/pages.js

@@ -0,0 +1,190 @@
+/**
+ * The development identity provider's HTML: a sign-in page, a consent screen,
+ * and the status page served at `/`.
+ *
+ * Hand-written markup with no client-side JavaScript, so the pages render the
+ * same in a browser and in a `fetch`-driven test. Every control a test needs
+ * carries a stable `id` and `name`.
+ *
+ * @module
+ */
+const STYLE = `
+  :root { color-scheme: light dark; }
+  body {
+    font: 16px/1.5 system-ui, sans-serif;
+    margin: 0 auto; padding: 2rem 1.25rem; max-width: 40rem;
+  }
+  h1 { font-size: 1.5rem; margin: 0 0 0.25rem; }
+  h2 { font-size: 1.05rem; margin: 1.75rem 0 0.5rem; }
+  .banner {
+    border: 1px solid currentColor; border-radius: 6px;
+    padding: 0.5rem 0.75rem; margin-bottom: 1.5rem;
+    font-size: 0.85rem; font-weight: 600; letter-spacing: 0.02em;
+  }
+  label { display: block; margin: 0.75rem 0 0.25rem; font-size: 0.9rem; }
+  input {
+    width: 100%; padding: 0.5rem; font: inherit;
+    border: 1px solid currentColor; border-radius: 4px; background: transparent;
+  }
+  button {
+    font: inherit; padding: 0.5rem 1rem; margin: 1rem 0.5rem 0 0;
+    border: 1px solid currentColor; border-radius: 4px;
+    background: transparent; cursor: pointer;
+  }
+  .error { font-weight: 600; margin-top: 1rem; }
+  ul { padding-left: 1.25rem; }
+  li { margin: 0.25rem 0; }
+  code, .mono { font-family: ui-monospace, monospace; font-size: 0.9em; }
+  .quick { display: flex; flex-wrap: wrap; gap: 0.5rem; }
+  .quick button { margin: 0; }
+  footer { margin-top: 2rem; font-size: 0.85rem; opacity: 0.75; }
+`;
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function layout(title, body) {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${escapeHtml(title)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<p class="banner" id="dev-only-banner">Development identity provider — never
+expose this to a network you do not control.</p>
+${body}
+<footer>@udibo/oauth2 <code>idp dev</code> · in-memory, no persistence</footer>
+</body>
+</html>
+`;
+}
+/** Wraps HTML in a `Response` with the headers a browser and a test expect. */
+export function htmlResponse(html, status = 200) {
+    return new Response(html, {
+        status,
+        headers: {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+        },
+    });
+}
+/**
+ * The sign-in page. Submits to `POST /login` with `username` + `password`, or
+ * with `as=<username>` from a one-click button.
+ */
+export function loginPage(options) {
+    const { returnTo, users, error } = options;
+    const quickSignIn = users.length === 0
+        ? ""
+        : `
+<h2>Seeded users</h2>
+<div class="quick">
+${users
+            .map((user) => `  <button type="submit" name="as" value="${escapeHtml(user.username)}" form="sign-in-form">Sign in as ${escapeHtml(user.username)}</button>`)
+            .join("\n")}
+</div>
+<p class="mono">Passwords are printed in the startup banner.</p>`;
+    return layout("Sign in", `
+<h1>Sign in</h1>
+${error ? `<p class="error" id="sign-in-error">${escapeHtml(error)}</p>` : ""}
+<form method="post" action="/login" id="sign-in-form">
+  <input type="hidden" name="return_to" value="${escapeHtml(returnTo)}">
+  <label for="username">Username</label>
+  <input id="username" name="username" autocomplete="username" autofocus>
+  <label for="password">Password</label>
+  <input id="password" name="password" type="password"
+    autocomplete="current-password">
+  <button type="submit" id="sign-in">Sign in</button>
+</form>
+${quickSignIn}
+`);
+}
+/**
+ * The consent screen shown when the config sets `"consent": "prompt"`.
+ * Submits to `POST /consent` with `decision=approve` or `decision=deny`.
+ */
+export function consentPage(options) {
+    const { clientId, scope, username, returnTo } = options;
+    return layout("Authorize application", `
+<h1>Authorize application</h1>
+<p><span class="mono">${escapeHtml(clientId)}</span> wants to access your
+account as <span class="mono">${escapeHtml(username)}</span>.</p>
+<h2>Requested scope</h2>
+<p class="mono" id="requested-scope">${scope ? escapeHtml(scope) : "(no scope requested)"}</p>
+<form method="post" action="/consent" id="consent-form">
+  <input type="hidden" name="return_to" value="${escapeHtml(returnTo)}">
+  <button type="submit" name="decision" value="approve" id="approve">
+    Approve
+  </button>
+  <button type="submit" name="decision" value="deny" id="deny">Deny</button>
+</form>
+`);
+}
+/** The page served at `/`: what is seeded and where the endpoints are. */
+export function statusPage(options) {
+    const { issuer, users, clients } = options;
+    const userList = users
+        .map((user) => `  <li><span class="mono">${escapeHtml(user.username)}</span> · password
+    <span class="mono">${escapeHtml(user.password)}</span> · sub
+    <span class="mono">${escapeHtml(user.id)}</span></li>`)
+        .join("\n");
+    const clientList = clients
+        .map((client) => `  <li><span class="mono">${escapeHtml(client.id)}</span>${client.secret
+        ? ` · secret <span class="mono">${escapeHtml(client.secret)}</span>`
+        : " · public client"}<br>redirect URIs: <span class="mono">${client.redirectUris.map(escapeHtml).join(", ") || "(none)"}</span><br>grants: <span class="mono">${client.grants
+        .map(escapeHtml)
+        .join(", ")}</span></li>`)
+        .join("\n");
+    return layout("Development identity provider", `
+<h1>Development identity provider</h1>
+<p>Issuer <span class="mono">${escapeHtml(issuer)}</span></p>
+<h2>Endpoints</h2>
+<ul>
+  <li><a href="/.well-known/openid-configuration">
+    /.well-known/openid-configuration</a></li>
+  <li><a href="/jwks">/jwks</a></li>
+  <li><span class="mono">/authorize</span>,
+    <span class="mono">/token</span>,
+    <span class="mono">/userinfo</span>,
+    <span class="mono">/revoke</span>,
+    <span class="mono">/introspect</span></li>
+  <li><span class="mono">/login</span>,
+    <span class="mono">/logout</span></li>
+</ul>
+<h2>Users</h2>
+<ul>
+${userList || "  <li>(none seeded)</li>"}
+</ul>
+<h2>Clients</h2>
+<ul>
+${clientList || "  <li>(none registered)</li>"}
+</ul>
+<h2>Test control surface</h2>
+<ul>
+  <li><span class="mono">POST /__admin/reset</span> — drop every session,
+    code, and token</li>
+  <li><span class="mono">POST /__admin/session</span> — sign a user in
+    without the form</li>
+  <li><span class="mono">POST /__admin/tokens</span> — mint tokens without
+    the browser</li>
+  <li><span class="mono">GET /__admin/state</span> — what is seeded right
+    now</li>
+</ul>
+`);
+}
+/** A terminal page for a flow that ended without a redirect. */
+export function messagePage(title, message) {
+    return layout(title, `
+<h1>${escapeHtml(title)}</h1>
+<p id="message">${escapeHtml(message)}</p>
+<p><a href="/">Back to the status page</a></p>
+`);
+}

package/dist/cli/idp/server.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The development identity provider itself: a real {@link AuthorizationServer}
+ * over the in-memory services, served on a socket with a sign-in page, an
+ * optional consent screen, and a test-control surface under `/__admin/`.
+ *
+ * Everything here is packaging — the protocol behavior is the same code an
+ * application runs in production. What makes it a development tool is the
+ * storage (memory, dropped on exit) and the admin endpoints, which mint tokens
+ * for any seeded user without their password.
+ *
+ * Three guardrails are enforced rather than documented: the admin endpoints
+ * require a startup token in a custom header (so a browser must preflight, and
+ * a drive-by page cannot), a non-loopback bind needs an explicit opt-in, and
+ * the issuer is pinned at startup instead of read from the request's `Host`.
+ *
+ * @module
+ */
+import { type SigningKey } from "../../server/signing-keys.ts";
+import type { DevIdpConfig } from "./config.ts";
+/** Header the admin endpoints require, carrying the token printed at startup. */
+export declare const ADMIN_TOKEN_HEADER = "x-admin-token";
+/**
+ * Whether a bind address only accepts connections from this machine. A
+ * non-loopback bind exposes the admin endpoints to the network, so it needs an
+ * explicit opt-in.
+ */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/** A running development identity provider. */
+export interface DevIdentityProvider {
+    /** Base URL the server is reachable at. */
+    url: string;
+    /** Issuer pinned at startup and stamped into every token and metadata document. */
+    issuer: string;
+    /** Token the `/__admin/` endpoints require in {@link ADMIN_TOKEN_HEADER}. */
+    adminToken: string;
+    /** Port the server bound. Resolved when the config asked for port `0`. */
+    port: number;
+    /** Hostname the server bound. */
+    hostname: string;
+    /** Resolves once the server has finished shutting down. */
+    finished: Promise<void>;
+    /** Stops accepting connections and drains in-flight requests. */
+    shutdown(): Promise<void>;
+}
+/** Options for {@link startDevIdentityProvider}. */
+export interface StartDevIdentityProviderOptions {
+    /** Resolved configuration, as returned by the config parser. */
+    config: DevIdpConfig;
+    /** Key the server signs id_tokens with and publishes at `/jwks`. */
+    signingKey: SigningKey;
+    /**
+     * Token the admin endpoints require. Generated when omitted; supply one so a
+     * CI job can hold it before the server starts.
+     */
+    adminToken?: string;
+    /**
+     * Permits binding a non-loopback address, which exposes the admin endpoints
+     * to the network. Refused unless this is explicitly set.
+     */
+    allowRemoteAccess?: boolean;
+}
+/**
+ * Starts the development identity provider on a socket and resolves once it is
+ * accepting connections.
+ *
+ * The caller owns the lifetime: keep the returned {@link DevIdentityProvider}
+ * and call `shutdown()` (a test's `finally`, a CI teardown step). Nothing is
+ * written to disk and no state survives the process.
+ *
+ * **This server is for development and CI only.** Its `/__admin/` endpoints
+ * mint tokens for any seeded user without their password; they are gated by
+ * {@link DevIdentityProvider.adminToken}, not by anything stronger.
+ *
+ * @throws {Error} When the config binds a non-loopback address without
+ * `allowRemoteAccess`.
+ *
+ * @example
+ * ```ts
+ * const idp = await startDevIdentityProvider({
+ *   config: defaultDevIdpConfig(),
+ *   signingKey: await generateSigningKey(),
+ * });
+ * try {
+ *   const discovery = await fetch(
+ *     `${idp.url}/.well-known/openid-configuration`,
+ *   );
+ *   // ...point the app under test at the discovered endpoints.
+ * } finally {
+ *   await idp.shutdown();
+ * }
+ * ```
+ */
+export declare function startDevIdentityProvider(options: StartDevIdentityProviderOptions): Promise<DevIdentityProvider>;