@qauth-labs/plugin-sdk 0.0.0 → 0.2.0-rc.1

package/dist/lib/validate.js

@@ -0,0 +1,265 @@
+import { AUTH_METHOD_BINDING_PARAMETER_PATTERN, AUTH_METHOD_CONTRACT, AUTH_METHOD_CONTRACT_NAME, AUTH_METHOD_DISPLAY_NAME_PATTERN, AUTH_METHOD_ICON_MEDIA_TYPES, AUTH_METHOD_ID_PATTERN, AUTH_METHOD_ROUTE_PATH_PATTERN, AUTH_METHOD_STEP_URNS, AUTH_METHOD_TYPE_PATTERN, MAX_AUTH_METHOD_DISPLAY_NAME_LENGTH, MAX_AUTH_METHOD_ICON_BYTES, RESERVED_AUTH_METHOD_TYPES, } from './contract.js';
+import { AuthMethodContractError } from './errors.js';
+/**
+ * The static checks of the AuthMethod contract (#599): what a method must be
+ * before the registry accepts it. The registry runs them at registration, so a
+ * method that fails one fails the boot. The contract test kit runs them too,
+ * then exercises the method.
+ *
+ * @experimental
+ */
+/** The eight bytes every PNG file starts with. */
+const PNG_SIGNATURE = Uint8Array.of(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a);
+/**
+ * Whether `provider` presents itself as an AuthMethod: it has a `contract`
+ * member. A plain `CredentialProvider` has none. The registry then holds it to
+ * the whole contract ({@link assertAuthMethod}), so a provider cannot carry a
+ * `contract` member and skip the checks.
+ *
+ * @experimental
+ */
+export function declaresAuthMethodContract(provider) {
+    return 'contract' in provider;
+}
+/**
+ * A frozen snapshot of a method: each member read once, functions bound to
+ * the method, routes and steps copied. The registry validates and keeps the
+ * snapshot, so the `type` it checked, the routes it mounts and the members the
+ * engine reads cannot change afterwards, whatever getters the method has.
+ * Members that are not what the contract asks are copied as they are, for
+ * the validation to report.
+ *
+ * @experimental
+ */
+export function authMethodSnapshot(method) {
+    const member = method;
+    const bound = (value, self) => typeof value === 'function' ? value.bind(self) : value;
+    const display = member['display'];
+    const steps = member['steps'];
+    const routes = member['routes'];
+    return Object.freeze({
+        contract: member['contract'],
+        type: member['type'],
+        id: member['id'],
+        display: typeof display === 'object' && display !== null ? displaySnapshot(display) : display,
+        configSchema: member['configSchema'],
+        steps: Array.isArray(steps) ? Object.freeze([...steps]) : steps,
+        routes: Array.isArray(routes)
+            ? Object.freeze(routes.map((route) => {
+                if (typeof route !== 'object' || route === null)
+                    return route;
+                const { kind, method: verb, path, handle, bindingParameter, } = route;
+                return Object.freeze({
+                    kind,
+                    method: verb,
+                    path,
+                    handle: bound(handle, route),
+                    ...(bindingParameter === undefined ? {} : { bindingParameter }),
+                });
+            }))
+            : routes,
+        start: bound(member['start'], method),
+        verify: bound(member['verify'], method),
+        extractAttributes: bound(member['extractAttributes'], method),
+    });
+}
+function displaySnapshot(display) {
+    const { name, icon } = display;
+    if (typeof icon !== 'object' || icon === null) {
+        return Object.freeze(icon === undefined ? { name } : { name, icon });
+    }
+    const { mediaType, bytes } = icon;
+    return Object.freeze({
+        name,
+        icon: Object.freeze({
+            mediaType,
+            bytes: bytes instanceof Uint8Array ? new Uint8Array(bytes) : bytes,
+        }),
+    });
+}
+/**
+ * Whether `value` meets the static checks of the contract.
+ *
+ * @experimental
+ */
+export function isAuthMethod(value) {
+    return authMethodProblems(value).length === 0;
+}
+/**
+ * Throw an {@link AuthMethodContractError} listing every problem when `value`
+ * does not meet the static checks of the contract.
+ *
+ * @experimental
+ */
+export function assertAuthMethod(value) {
+    const problems = authMethodProblems(value);
+    if (problems.length > 0) {
+        throw new AuthMethodContractError(describeMethod(value), problems);
+    }
+}
+/**
+ * Every static problem of `value` as an AuthMethod, one sentence each; empty
+ * when there is none.
+ *
+ * @experimental
+ */
+export function authMethodProblems(value) {
+    if (typeof value !== 'object' || value === null)
+        return ['it is not an object'];
+    const method = value;
+    const problems = [];
+    problems.push(...contractProblems(method['contract']));
+    problems.push(...authMethodTypeProblems(method['type']));
+    if (typeof method['id'] !== 'string' || !AUTH_METHOD_ID_PATTERN.test(method['id'])) {
+        problems.push(`id must match ${AUTH_METHOD_ID_PATTERN.source}`);
+    }
+    for (const member of ['verify', 'extractAttributes', 'start']) {
+        if (typeof method[member] !== 'function')
+            problems.push(`${member} must be a function`);
+    }
+    problems.push(...displayProblems(method['display']));
+    const schema = method['configSchema'];
+    if (typeof schema !== 'object' ||
+        schema === null ||
+        typeof schema['safeParse'] !== 'function') {
+        problems.push('configSchema must be a Zod schema');
+    }
+    problems.push(...stepProblems(method['steps']));
+    problems.push(...routeProblems(method['routes']));
+    return problems;
+}
+/**
+ * The problems of a route list; exported for the mount, which checks again.
+ *
+ * @experimental
+ */
+export function routeProblems(routes) {
+    if (!Array.isArray(routes))
+        return ['routes must be a list'];
+    const problems = [];
+    const seen = new Set();
+    let callbacks = 0;
+    routes.forEach((route, index) => {
+        const at = `routes[${index}]`;
+        if (typeof route !== 'object' || route === null) {
+            problems.push(`${at} must be an object`);
+            return;
+        }
+        const entry = route;
+        if (entry['kind'] !== 'callback' && entry['kind'] !== 'bounce') {
+            problems.push(`${at}.kind must be callback or bounce`);
+        }
+        if (entry['kind'] === 'callback')
+            callbacks += 1;
+        if (entry['method'] !== 'GET' && entry['method'] !== 'POST') {
+            problems.push(`${at}.method must be GET or POST`);
+        }
+        const path = entry['path'];
+        if (typeof path !== 'string' || !AUTH_METHOD_ROUTE_PATH_PATTERN.test(path)) {
+            problems.push(`${at}.path must be one to four lower-case segments, such as /callback: a route cannot leave the method's prefix`);
+        }
+        else {
+            const key = `${String(entry['method'])} ${path}`;
+            if (seen.has(key))
+                problems.push(`${at} repeats ${key}`);
+            seen.add(key);
+        }
+        if (typeof entry['handle'] !== 'function')
+            problems.push(`${at}.handle must be a function`);
+        const bindingParameter = entry['bindingParameter'];
+        if (bindingParameter !== undefined &&
+            (entry['kind'] !== 'callback' ||
+                typeof bindingParameter !== 'string' ||
+                !AUTH_METHOD_BINDING_PARAMETER_PATTERN.test(bindingParameter))) {
+            problems.push(`${at}.bindingParameter must be the name of a parameter (${AUTH_METHOD_BINDING_PARAMETER_PATTERN.source}), on a callback route only`);
+        }
+    });
+    if (callbacks === 0) {
+        problems.push('routes must hold at least one callback route: the upstream step returns there');
+    }
+    return problems;
+}
+function contractProblems(contract) {
+    if (contract === AUTH_METHOD_CONTRACT)
+        return [];
+    if (typeof contract === 'string' && contract.startsWith(`${AUTH_METHOD_CONTRACT_NAME}/`)) {
+        return [
+            `it is written against the contract ${contract}, and this server implements ${AUTH_METHOD_CONTRACT}`,
+        ];
+    }
+    return [`contract must be ${AUTH_METHOD_CONTRACT}`];
+}
+/**
+ * The problems of `type` as an AuthMethod's type: its pattern, and not one of
+ * the reserved types.
+ *
+ * @experimental
+ */
+export function authMethodTypeProblems(type) {
+    if (typeof type !== 'string' || !AUTH_METHOD_TYPE_PATTERN.test(type)) {
+        return [`type must match ${AUTH_METHOD_TYPE_PATTERN.source}`];
+    }
+    if (RESERVED_AUTH_METHOD_TYPES.includes(type)) {
+        return [`type ${type} is reserved for QAuth's own credentials`];
+    }
+    return [];
+}
+function displayProblems(display) {
+    if (typeof display !== 'object' || display === null)
+        return ['display must be an object'];
+    const { name, icon } = display;
+    const problems = [];
+    if (typeof name !== 'string' ||
+        name.length > MAX_AUTH_METHOD_DISPLAY_NAME_LENGTH ||
+        !AUTH_METHOD_DISPLAY_NAME_PATTERN.test(name)) {
+        problems.push(`display.name must be at most ${MAX_AUTH_METHOD_DISPLAY_NAME_LENGTH} characters under the display rule: no markup bracket, no control or invisible character, no space at either end`);
+    }
+    if (icon !== undefined)
+        problems.push(...iconProblems(icon));
+    return problems;
+}
+function iconProblems(icon) {
+    if (typeof icon !== 'object' || icon === null)
+        return ['display.icon must be an object'];
+    const { mediaType, bytes } = icon;
+    const problems = [];
+    if (!AUTH_METHOD_ICON_MEDIA_TYPES.includes(mediaType)) {
+        problems.push(`display.icon.mediaType must be ${AUTH_METHOD_ICON_MEDIA_TYPES.join(' or ')}`);
+    }
+    if (!(bytes instanceof Uint8Array)) {
+        problems.push('display.icon.bytes must be a Uint8Array');
+    }
+    else if (bytes.byteLength > MAX_AUTH_METHOD_ICON_BYTES) {
+        problems.push(`display.icon.bytes must be at most ${MAX_AUTH_METHOD_ICON_BYTES} bytes`);
+    }
+    else if (!PNG_SIGNATURE.every((byte, index) => bytes[index] === byte)) {
+        problems.push('display.icon.bytes must be a PNG file');
+    }
+    return problems;
+}
+function stepProblems(steps) {
+    if (!Array.isArray(steps) || steps.length === 0) {
+        return ['steps must list at least one step'];
+    }
+    const problems = [];
+    const seen = new Set();
+    for (const step of steps) {
+        if (seen.has(step))
+            problems.push(`steps repeats ${String(step)}`);
+        seen.add(step);
+        if (AUTH_METHOD_STEP_URNS.includes(step))
+            continue;
+        problems.push(`steps holds ${String(step)}, which is not a step a method may contribute here (${AUTH_METHOD_STEP_URNS.join(', ')})`);
+    }
+    return problems;
+}
+/** How a candidate is named in an error: its type, when it has a usable one. */
+function describeMethod(value) {
+    if (typeof value === 'object' && value !== null) {
+        const type = value['type'];
+        if (typeof type === 'string' && AUTH_METHOD_TYPE_PATTERN.test(type)) {
+            return `The AuthMethod ${type}`;
+        }
+    }
+    return 'An AuthMethod';
+}

package/dist/testing/contract-kit.d.ts

@@ -0,0 +1,116 @@
+import type { AuthMethod, AuthMethodEgressRequest, AuthMethodEgressResponse, AuthMethodParameters } from '../lib/auth-method.js';
+/**
+ * The contract test kit (#599): one function a method's author calls, in any
+ * test runner, to check the method against the AuthMethod contract. It is
+ * test support, served from the `@qauth-labs/plugin-sdk/testing` entry point,
+ * never from the main one, and it refuses to run under `NODE_ENV=production`: while it runs, it
+ * replaces the global `fetch`.
+ *
+ * ```ts
+ * import { checkAuthMethod } from '@qauth-labs/plugin-sdk/testing';
+ *
+ * it('meets the AuthMethod contract', async () => {
+ *   await checkAuthMethod(myMethod, {
+ *     config: { clientId: 'kit', clientSecret: 'kit-secret' },
+ *     egress: (request) => myFakeProvider.answer(request),
+ *     callback: (authorizationRequest) => myFakeProvider.signIn(authorizationRequest),
+ *   });
+ * });
+ * ```
+ *
+ * It resolves with the checks it ran, and rejects with an
+ * {@link AuthMethodContractError} that lists every check the method failed.
+ *
+ * EXPERIMENTAL, like the contract it checks.
+ *
+ * @experimental
+ */
+/**
+ * A request the provider sends the browser back with, to one of the method's
+ * routes.
+ *
+ * @experimental
+ */
+export interface AuthMethodKitRequest {
+    /** The route's path below the method's prefix: `/callback`. */
+    readonly path: string;
+    readonly method: 'GET' | 'POST';
+    readonly query?: AuthMethodParameters;
+    readonly form?: AuthMethodParameters;
+}
+/**
+ * How the provider behaves in the kit's run: the method's author plays it.
+ *
+ * @experimental
+ */
+export interface AuthMethodKitScenario {
+    /**
+     * A config for one realm, which the method's `configSchema` accepts. Give
+     * its `writeOnly` members realistic secrets (a dozen characters or more):
+     * the kit looks for every one of them, however short, in every log line,
+     * and a secret such as `abc` matches text that is no leak.
+     */
+    readonly config: unknown;
+    /**
+     * Answer the method's outbound calls as the provider would. Without it,
+     * every call the method makes is refused.
+     */
+    egress?(request: AuthMethodEgressRequest): AuthMethodEgressResponse | Promise<AuthMethodEgressResponse>;
+    /**
+     * The request the browser comes back with once the person signed in at the
+     * provider, for the authorization request `start()` sent it to. Each call
+     * signs the same person in.
+     */
+    callback(authorizationRequest: URL): AuthMethodKitRequest | Promise<AuthMethodKitRequest>;
+    /**
+     * The request the browser comes back with when the person declines at the
+     * provider (`error=access_denied`). Checked when given.
+     */
+    declined?(authorizationRequest: URL): AuthMethodKitRequest | Promise<AuthMethodKitRequest>;
+}
+/**
+ * What a passing run checked, in order.
+ *
+ * @experimental
+ */
+export interface AuthMethodKitReport {
+    readonly checks: readonly string[];
+}
+/**
+ * Check `method` against the AuthMethod contract.
+ *
+ * Static checks first: the contract version, `type`, `id`, the display data,
+ * the config schema (a Zod object schema that renders as JSON Schema and
+ * accepts `scenario.config`), the steps and the routes (each inside the
+ * method's prefix). Then a run against a fake realm, with the global `fetch`
+ * disabled:
+ *
+ * 1. `start()` answers an `https` redirect with no credentials and no fragment,
+ *    a transaction of JSON data within its cap and a binding of 22 to 512
+ *    base64url characters; two starts answer different transactions.
+ * 2. Two starts answer different bindings, and each sends its binding to the
+ *    provider, in the redirect or in a body it posted.
+ * 3. The provider's callback carries the binding back in the callback
+ *    route's `bindingParameter` (`state` by default): the kit, like the host,
+ *    hands the handler the transaction only when it does. It ends in an
+ *    identity whose `rawClaims.iss` names its issuer and whose attributes
+ *    carry the method's `type`; a second sign-in of the same person resolves
+ *    the same `externalSub`.
+ * 4. When the authorization request asks for a code (`response_type=code`,
+ *    in the redirect or a body the method posted), it carries
+ *    `code_challenge_method=S256` and a `code_challenge` (RFC 7636; QAuth
+ *    requires PKCE with S256), and every token request the callback makes
+ *    (`grant_type=authorization_code`) carries the `code_verifier` whose S256
+ *    is that challenge.
+ * 5. `verify()` rejects inputs that no callback produced, a well-formed
+ *    identity, a copy of a real result and a result already used among them.
+ * 6. When the scenario gives one, the declined callback ends as `declined`.
+ * 7. The method called the global `fetch` nowhere, and no log line carries
+ *    the value of a config member marked `writeOnly` (a secret), in a field,
+ *    a message or an error.
+ *
+ * @throws AuthMethodContractError listing every failed check
+ * @throws Error when `NODE_ENV` is `production`
+ * @experimental
+ */
+export declare function checkAuthMethod(method: AuthMethod, scenario: AuthMethodKitScenario): Promise<AuthMethodKitReport>;