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

package/dist/lib/engine.js

@@ -0,0 +1,367 @@
+import { timingSafeEqual } from 'node:crypto';
+import { AUTH_METHOD_ATTRIBUTE_KEY_PATTERN, AUTH_METHOD_BINDING_PATTERN, DEFAULT_AUTH_METHOD_BINDING_PARAMETER, MAX_AUTH_METHOD_ATTRIBUTE_VALUE_LENGTH, MAX_AUTH_METHOD_EXTERNAL_SUB_LENGTH, MAX_AUTH_METHOD_RAW_CLAIMS_BYTES, MAX_UPSTREAM_REDIRECT_LENGTH, MAX_UPSTREAM_TRANSACTION_BYTES, UPSTREAM_FAILURE_REASONS, } from './contract.js';
+import { AuthMethodFaultError } from './errors.js';
+/**
+ * The engine's half of the upstream step (#599): what it checks around the
+ * two calls it makes into a method. The engine never acts on an answer that
+ * fails a check; it throws {@link AuthMethodFaultError}, which the sign-in
+ * flow answers with the generic error page and its trace id.
+ *
+ * Pure: the transaction store, the flow cookie and the account decisions
+ * belong to the sign-in flow that calls these (#639).
+ *
+ * @experimental
+ */
+const ASSURANCE_LEVELS = ['low', 'substantial', 'high'];
+/**
+ * A control character an attribute value may not hold: NUL (which Postgres
+ * `text` refuses) and the other C0 controls and DEL, but tab, line feed and
+ * carriage return, which a postal address may hold.
+ */
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const VALUE_CONTROL_CHARACTER = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/;
+/** A C0 or C1 control character, or DEL. */
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/;
+/**
+ * Start an upstream transaction: call `method.start()` and check its answer.
+ * The redirect must be an absolute `https` URL with no credentials and no
+ * fragment, the transaction JSON data within its cap, and the binding 22 to
+ * 512 base64url characters. The returned transaction is a frozen copy; the
+ * host stores it with the binding (a `PendingUpstreamTransaction`).
+ *
+ * A rejection of `start()` (the provider's discovery document cannot be read,
+ * for instance) propagates unchanged.
+ *
+ * @throws AuthMethodFaultError when the answer fails a check
+ * @experimental
+ */
+export async function startUpstreamStep(method, request, context) {
+    const answer = await method.start(request, context);
+    if (typeof answer !== 'object' || answer === null) {
+        throw new AuthMethodFaultError(method.type, 'start() did not answer an object');
+    }
+    const { redirectTo, transaction, binding } = answer;
+    const redirectProblem = upstreamRedirectProblem(redirectTo);
+    if (redirectProblem !== undefined) {
+        throw new AuthMethodFaultError(method.type, `start() answered ${redirectProblem}`);
+    }
+    // An object: the host tells "no transaction" apart by its absence, so a
+    // transaction that is null, a string or a list could read as none.
+    const stored = typeof transaction === 'object' && transaction !== null && !Array.isArray(transaction)
+        ? storableTransaction(transaction)
+        : undefined;
+    if (stored === undefined) {
+        throw new AuthMethodFaultError(method.type, `start() answered a transaction that is not an object of JSON data of at most ${MAX_UPSTREAM_TRANSACTION_BYTES} bytes`);
+    }
+    // The URL as parsed, so what the engine sends is what it checked; parsing
+    // percent-encodes, so the cap is checked again.
+    const href = new URL(redirectTo).href;
+    if (href.length > MAX_UPSTREAM_REDIRECT_LENGTH) {
+        throw new AuthMethodFaultError(method.type, `start() answered a redirect longer than ${MAX_UPSTREAM_REDIRECT_LENGTH} characters`);
+    }
+    if (typeof binding !== 'string' || !AUTH_METHOD_BINDING_PATTERN.test(binding)) {
+        throw new AuthMethodFaultError(method.type, 'start() answered a binding that is not 22 to 512 base64url characters');
+    }
+    return Object.freeze({ redirectTo: href, transaction: stored, binding });
+}
+/**
+ * The binding a request to `route` carries: the single value of the route's
+ * binding parameter (`state` unless the route names another), from the
+ * query of a `GET` route and the form of a `POST` one. `undefined` when the
+ * parameter is missing or repeated, or `route` is not a callback route.
+ *
+ * @experimental
+ */
+export function presentedUpstreamBinding(route, request) {
+    if (route.kind !== 'callback')
+        return undefined;
+    const name = route.bindingParameter ?? DEFAULT_AUTH_METHOD_BINDING_PARAMETER;
+    const parameters = route.method === 'GET' ? request.query : request.form;
+    const value = Object.hasOwn(parameters, name) ? parameters[name] : undefined;
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Whether the binding a callback carried is the pending transaction's, in
+ * constant time (`timingSafeEqual` over the UTF-8 bytes). `false` unless both are strings and
+ * the expected one is a binding: a missing or repeated parameter never
+ * matches, and neither does an empty one.
+ *
+ * The host runs it before it takes the transaction, so a callback from
+ * another site cannot spend or cancel a pending sign-in.
+ *
+ * @experimental
+ */
+export function upstreamBindingMatches(expected, presented) {
+    return (typeof expected === 'string' &&
+        typeof presented === 'string' &&
+        AUTH_METHOD_BINDING_PATTERN.test(expected) &&
+        constantTimeEquals(expected, presented));
+}
+/**
+ * Whether two strings are equal, compared in constant time over their UTF-8
+ * bytes; a length mismatch answers `false` at once (the expected binding's
+ * length is no secret: the pattern fixes its range).
+ */
+function constantTimeEquals(left, right) {
+    const a = Buffer.from(left, 'utf8');
+    const b = Buffer.from(right, 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/**
+ * The lowest assurance level, the ceiling of a method's identity when the
+ * caller names none.
+ *
+ * @experimental
+ */
+export const DEFAULT_UPSTREAM_MAX_ASSURANCE = ASSURANCE_LEVELS[0];
+/**
+ * Turn what a method's callback handed back into the end of the upstream
+ * step. A `result` goes to `method.verify()`; the identity it resolves is
+ * checked and its assurance level lowered to `options.maxAssurance`, then
+ * `method.extractAttributes()` gives its attributes, which are checked too.
+ *
+ * @param outcome - what the callback route's handler returned, unchecked, or
+ *   the {@link AuthMethodFaultError} the route mount made of a handler that
+ *   threw or a context that could not be built
+ * @param options - the assurance ceiling
+ * @throws AuthMethodFaultError when the outcome is a fault or outside the
+ *   closed set, or the identity or an attribute fails a check
+ * @throws TypeError when `options.maxAssurance` is not an assurance level
+ * @experimental
+ */
+export async function completeUpstreamStep(method, outcome, options = {}) {
+    const maxAssurance = options.maxAssurance ?? DEFAULT_UPSTREAM_MAX_ASSURANCE;
+    if (!ASSURANCE_LEVELS.includes(maxAssurance)) {
+        throw new TypeError(`maxAssurance must be one of ${ASSURANCE_LEVELS.join(', ')}`);
+    }
+    // A fault the route mount caught (a handler that threw, a bounce that went
+    // wrong, a context that could not be built) arrives as the outcome, so it
+    // ends the step the way every other fault of the method does.
+    if (outcome instanceof AuthMethodFaultError) {
+        throw outcome.methodType === method.type
+            ? outcome
+            : new AuthMethodFaultError(method.type, 'the callback answered a fault of another method', {
+                cause: outcome,
+            });
+    }
+    if (typeof outcome !== 'object' || outcome === null) {
+        throw new AuthMethodFaultError(method.type, 'the callback did not answer an outcome');
+    }
+    const { kind } = outcome;
+    if (kind === 'declined')
+        return Object.freeze({ kind: 'declined' });
+    if (kind === 'failed') {
+        const { reason } = outcome;
+        if (!UPSTREAM_FAILURE_REASONS.includes(reason)) {
+            throw new AuthMethodFaultError(method.type, `the callback failed with a reason outside ${UPSTREAM_FAILURE_REASONS.join(', ')}`);
+        }
+        return Object.freeze({ kind: 'failed', reason: reason });
+    }
+    if (kind !== 'result' || !('result' in outcome)) {
+        throw new AuthMethodFaultError(method.type, 'the callback answered an outcome outside result, declined and failed');
+    }
+    let identity;
+    try {
+        identity = await method.verify(outcome.result);
+    }
+    catch (cause) {
+        return Object.freeze({ kind: 'failed', reason: 'verification_refused', cause });
+    }
+    const checked = checkedIdentity(method.type, identity, maxAssurance);
+    let attributes;
+    try {
+        attributes = method.extractAttributes(checked);
+    }
+    catch (cause) {
+        throw new AuthMethodFaultError(method.type, 'extractAttributes() threw', { cause });
+    }
+    return Object.freeze({
+        kind: 'identity',
+        identity: checked,
+        attributes: checkedAttributes(method.type, attributes),
+    });
+}
+/**
+ * Why `value` cannot be where an upstream step sends the browser, or
+ * `undefined` when it can.
+ *
+ * @experimental
+ */
+export function upstreamRedirectProblem(value) {
+    if (typeof value !== 'string')
+        return 'a redirect that is not a string';
+    if (value.length > MAX_UPSTREAM_REDIRECT_LENGTH) {
+        return `a redirect longer than ${MAX_UPSTREAM_REDIRECT_LENGTH} characters`;
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return 'a redirect that is not an absolute URL';
+    }
+    if (url.protocol !== 'https:')
+        return 'a redirect that is not https';
+    if (url.username !== '' || url.password !== '')
+        return 'a redirect with credentials';
+    if (value.includes('#'))
+        return 'a redirect with a fragment';
+    return undefined;
+}
+/**
+ * A frozen copy of `value` when it is JSON data within the transaction cap:
+ * plain objects, arrays, strings, finite numbers, booleans and `null`, nested
+ * at most 16 deep. `undefined` otherwise.
+ *
+ * @experimental
+ */
+export function storableTransaction(value) {
+    return frozenJsonCopy(value, MAX_UPSTREAM_TRANSACTION_BYTES);
+}
+/** A frozen copy of `value` when it is JSON data of at most `maxBytes`; `undefined` otherwise. */
+function frozenJsonCopy(value, maxBytes) {
+    if (!isJsonData(value, 0))
+        return undefined;
+    const json = JSON.stringify(value);
+    if (Buffer.byteLength(json, 'utf8') > maxBytes)
+        return undefined;
+    return deepFreeze(JSON.parse(json));
+}
+function isJsonData(value, depth) {
+    if (depth > 16)
+        return false;
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every((item) => isJsonData(item, depth + 1));
+    if (typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return false;
+    if (Object.getOwnPropertySymbols(value).length > 0)
+        return false;
+    return Object.values(value).every((item) => isJsonData(item, depth + 1));
+}
+function deepFreeze(value) {
+    if (typeof value === 'object' && value !== null) {
+        for (const item of Object.values(value))
+            deepFreeze(item);
+        Object.freeze(value);
+    }
+    return value;
+}
+function checkedIdentity(type, identity, maxAssurance) {
+    const fault = (problem) => new AuthMethodFaultError(type, `verify() resolved ${problem}`);
+    if (typeof identity !== 'object' || identity === null)
+        throw fault('something not an object');
+    const { externalSub, assuranceLevel, rawClaims } = identity;
+    if (typeof externalSub !== 'string' ||
+        externalSub.length === 0 ||
+        externalSub.length > MAX_AUTH_METHOD_EXTERNAL_SUB_LENGTH ||
+        CONTROL_CHARACTER.test(externalSub) ||
+        !isWellFormed(externalSub)) {
+        throw fault(`an externalSub that is not 1 to ${MAX_AUTH_METHOD_EXTERNAL_SUB_LENGTH} characters of well-formed text with no control character`);
+    }
+    if (!ASSURANCE_LEVELS.includes(assuranceLevel)) {
+        throw fault(`an assuranceLevel outside ${ASSURANCE_LEVELS.join(', ')}`);
+    }
+    const claims = typeof rawClaims === 'object' && rawClaims !== null && !Array.isArray(rawClaims)
+        ? frozenJsonCopy(rawClaims, MAX_AUTH_METHOD_RAW_CLAIMS_BYTES)
+        : undefined;
+    if (claims === undefined) {
+        throw fault(`rawClaims that are not an object of JSON data of at most ${MAX_AUTH_METHOD_RAW_CLAIMS_BYTES} bytes`);
+    }
+    return Object.freeze({
+        externalSub,
+        assuranceLevel: lowerAssurance(assuranceLevel, maxAssurance),
+        rawClaims: claims,
+    });
+}
+/** The lower of two assurance levels. */
+function lowerAssurance(level, ceiling) {
+    return ASSURANCE_LEVELS.indexOf(level) <= ASSURANCE_LEVELS.indexOf(ceiling) ? level : ceiling;
+}
+function checkedAttributes(type, attributes) {
+    const fault = (problem) => new AuthMethodFaultError(type, `extractAttributes() returned ${problem}`);
+    if (!Array.isArray(attributes))
+        throw fault('something not a list');
+    // An index loop into a fresh array, with the length read once: `map` would
+    // build its result through `attributes.constructor[Symbol.species]`, which
+    // the method controls, so a list whose species hands back other objects
+    // (an attribute under `wallet`, say) would skip every check below.
+    const length = attributes.length;
+    if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0) {
+        throw fault('a list whose length is not a count');
+    }
+    const checked = [];
+    for (let index = 0; index < length; index += 1) {
+        checked[index] = checkedAttribute(type, attributes[index], index, fault);
+    }
+    return Object.freeze(checked);
+}
+function checkedAttribute(type, attribute, index, fault) {
+    if (typeof attribute !== 'object' || attribute === null) {
+        throw fault(`an attribute [${index}] that is not an object`);
+    }
+    const { source, attrKey, attrValue, verified, expiresAt } = attribute;
+    // The source must be the method's own type: a method cannot write
+    // attributes under another source, such as `wallet`, which outranks every
+    // other in claim resolution.
+    if (source !== type)
+        throw fault(`an attribute [${index}] whose source is not ${type}`);
+    if (typeof attrKey !== 'string' || !AUTH_METHOD_ATTRIBUTE_KEY_PATTERN.test(attrKey)) {
+        throw fault(`an attribute [${index}] whose key does not match ${AUTH_METHOD_ATTRIBUTE_KEY_PATTERN.source}`);
+    }
+    if (typeof attrValue !== 'string' ||
+        attrValue.length > MAX_AUTH_METHOD_ATTRIBUTE_VALUE_LENGTH ||
+        VALUE_CONTROL_CHARACTER.test(attrValue) ||
+        !isWellFormed(attrValue)) {
+        throw fault(`an attribute [${index}] whose value is not well-formed text of at most ${MAX_AUTH_METHOD_ATTRIBUTE_VALUE_LENGTH} characters without control characters other than tab and line breaks`);
+    }
+    if (typeof verified !== 'boolean') {
+        throw fault(`an attribute [${index}] whose verified flag is not a boolean`);
+    }
+    // A copy of the time, never the method's Date: a Date stays mutable when
+    // the attribute holding it is frozen.
+    const expiry = expiresAt === undefined ? undefined : dateTime(expiresAt);
+    if (expiry !== undefined && Number.isNaN(expiry)) {
+        throw fault(`an attribute [${index}] whose expiresAt is not a valid Date`);
+    }
+    return Object.freeze({
+        source,
+        attrKey,
+        attrValue,
+        verified,
+        ...(expiry === undefined ? {} : { expiresAt: new Date(expiry) }),
+    });
+}
+/**
+ * The time a Date holds, read from the Date itself rather than through a
+ * `getTime` a subclass may override; `NaN` for anything that is not a Date.
+ */
+function dateTime(value) {
+    if (!(value instanceof Date))
+        return Number.NaN;
+    try {
+        return Date.prototype.getTime.call(value);
+    }
+    catch {
+        // A proxy around a Date passes `instanceof` but holds no time.
+        return Number.NaN;
+    }
+}
+/**
+ * Whether `value` is well-formed UTF-16, with no lone surrogate:
+ * `String.prototype.isWellFormed` (ES2024; the workspace's TypeScript lib is
+ * ES2022). Postgres stores a lone surrogate as U+FFFD, so two different
+ * ill-formed strings could be stored as one: two subjects, one account.
+ */
+function isWellFormed(value) {
+    return String.prototype.isWellFormed.call(value);
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The errors of the AuthMethod contract (#599). None of them reaches the wire
+ * with its details: they name a fault of a method's code or of its config,
+ * for the operator's log. A request that meets one answers with the generic
+ * error page and its trace id.
+ *
+ * @experimental
+ */
+/**
+ * A method does not meet the contract: thrown when it is registered (the boot
+ * fails) and by the contract test kit. `problems` lists every problem found,
+ * one sentence each.
+ *
+ * @experimental
+ */
+export declare class AuthMethodContractError extends Error {
+    /** Every problem found, one sentence each. */
+    readonly problems: readonly string[];
+    constructor(subject: string, problems: readonly string[]);
+}
+/**
+ * A method broke the contract at run time: `start()` answered something the
+ * engine cannot use, a callback handed back an outcome outside the closed set,
+ * or `verify()`/`extractAttributes()` produced an identity or attributes the
+ * engine refuses. The engine never acts on such an answer.
+ *
+ * @experimental
+ */
+export declare class AuthMethodFaultError extends Error {
+    /** The method's `type`. */
+    readonly methodType: string;
+    constructor(methodType: string, problem: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A realm's stored config of a method does not pass the method's
+ * `configSchema`. `issues` names the members, never their values, since a
+ * member may be a secret.
+ *
+ * @experimental
+ */
+export declare class AuthMethodConfigError extends Error {
+    /** The method's `type`. */
+    readonly methodType: string;
+    /** Each failing member's path and the schema's code, never its value. */
+    readonly issues: readonly string[];
+    constructor(methodType: string, issues: readonly string[]);
+}

package/dist/lib/errors.js

@@ -0,0 +1,63 @@
+/**
+ * The errors of the AuthMethod contract (#599). None of them reaches the wire
+ * with its details: they name a fault of a method's code or of its config,
+ * for the operator's log. A request that meets one answers with the generic
+ * error page and its trace id.
+ *
+ * @experimental
+ */
+/**
+ * A method does not meet the contract: thrown when it is registered (the boot
+ * fails) and by the contract test kit. `problems` lists every problem found,
+ * one sentence each.
+ *
+ * @experimental
+ */
+export class AuthMethodContractError extends Error {
+    /** Every problem found, one sentence each. */
+    problems;
+    constructor(subject, problems) {
+        super(`${subject} does not meet the AuthMethod contract:\n- ${problems.join('\n- ')}`);
+        this.name = 'AuthMethodContractError';
+        this.problems = Object.freeze([...problems]);
+        Object.setPrototypeOf(this, AuthMethodContractError.prototype);
+    }
+}
+/**
+ * A method broke the contract at run time: `start()` answered something the
+ * engine cannot use, a callback handed back an outcome outside the closed set,
+ * or `verify()`/`extractAttributes()` produced an identity or attributes the
+ * engine refuses. The engine never acts on such an answer.
+ *
+ * @experimental
+ */
+export class AuthMethodFaultError extends Error {
+    /** The method's `type`. */
+    methodType;
+    constructor(methodType, problem, options) {
+        super(`AuthMethod ${methodType}: ${problem}`, options);
+        this.name = 'AuthMethodFaultError';
+        this.methodType = methodType;
+        Object.setPrototypeOf(this, AuthMethodFaultError.prototype);
+    }
+}
+/**
+ * A realm's stored config of a method does not pass the method's
+ * `configSchema`. `issues` names the members, never their values, since a
+ * member may be a secret.
+ *
+ * @experimental
+ */
+export class AuthMethodConfigError extends Error {
+    /** The method's `type`. */
+    methodType;
+    /** Each failing member's path and the schema's code, never its value. */
+    issues;
+    constructor(methodType, issues) {
+        super(`AuthMethod ${methodType}: the config does not pass the method's schema`);
+        this.name = 'AuthMethodConfigError';
+        this.methodType = methodType;
+        this.issues = Object.freeze([...issues]);
+        Object.setPrototypeOf(this, AuthMethodConfigError.prototype);
+    }
+}

package/dist/lib/parameters.d.ts

@@ -0,0 +1,21 @@
+import type { AuthMethodParameters } from './auth-method.js';
+/**
+ * The parameters a method's route handler sees (#599): the string and
+ * string-list members of a parsed query or form, within the caps, in a
+ * frozen object with no prototype, so a parameter named `__proto__` stays a
+ * parameter. Anything else is dropped: a method that misses a parameter it
+ * needs refuses the request.
+ *
+ * The route mount builds every handler's `query` and `form` with it, and the
+ * contract test kit does the same, so a method meets in its tests exactly the
+ * objects the host hands it.
+ *
+ * - at most {@link MAX_AUTH_METHOD_PARAMETERS} parameters, the first ones;
+ * - a value longer than {@link MAX_AUTH_METHOD_PARAMETER_LENGTH} drops its
+ *   parameter;
+ * - a repeated parameter is a frozen list of at most
+ *   {@link MAX_AUTH_METHOD_PARAMETER_VALUES} values; more drops it.
+ *
+ * @experimental
+ */
+export declare function authMethodParameters(value: unknown): AuthMethodParameters;

package/dist/lib/parameters.js

@@ -0,0 +1,62 @@
+import { MAX_AUTH_METHOD_PARAMETER_LENGTH, MAX_AUTH_METHOD_PARAMETER_VALUES, MAX_AUTH_METHOD_PARAMETERS, } from './contract.js';
+/**
+ * The parameters a method's route handler sees (#599): the string and
+ * string-list members of a parsed query or form, within the caps, in a
+ * frozen object with no prototype, so a parameter named `__proto__` stays a
+ * parameter. Anything else is dropped: a method that misses a parameter it
+ * needs refuses the request.
+ *
+ * The route mount builds every handler's `query` and `form` with it, and the
+ * contract test kit does the same, so a method meets in its tests exactly the
+ * objects the host hands it.
+ *
+ * - at most {@link MAX_AUTH_METHOD_PARAMETERS} parameters, the first ones;
+ * - a value longer than {@link MAX_AUTH_METHOD_PARAMETER_LENGTH} drops its
+ *   parameter;
+ * - a repeated parameter is a frozen list of at most
+ *   {@link MAX_AUTH_METHOD_PARAMETER_VALUES} values; more drops it.
+ *
+ * @experimental
+ */
+export function authMethodParameters(value) {
+    const parameters = Object.create(null);
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        let count = 0;
+        for (const [name, member] of Object.entries(value)) {
+            if (count >= MAX_AUTH_METHOD_PARAMETERS)
+                break;
+            if (typeof member === 'string') {
+                if (member.length > MAX_AUTH_METHOD_PARAMETER_LENGTH)
+                    continue;
+                parameters[name] = member;
+                count += 1;
+            }
+            else if (Array.isArray(member)) {
+                const values = stringList(member);
+                if (values === undefined)
+                    continue;
+                parameters[name] = values;
+                count += 1;
+            }
+        }
+    }
+    return Object.freeze(parameters);
+}
+/** A frozen copy of a list of capped strings, read by index; `undefined` otherwise. */
+function stringList(member) {
+    const length = member.length;
+    if (typeof length !== 'number' ||
+        !Number.isSafeInteger(length) ||
+        length > MAX_AUTH_METHOD_PARAMETER_VALUES) {
+        return undefined;
+    }
+    const values = [];
+    for (let index = 0; index < length; index += 1) {
+        const item = member[index];
+        if (typeof item !== 'string' || item.length > MAX_AUTH_METHOD_PARAMETER_LENGTH) {
+            return undefined;
+        }
+        values[index] = item;
+    }
+    return Object.freeze(values);
+}

package/dist/lib/validate.d.ts

@@ -0,0 +1,55 @@
+import type { AuthMethod } from './auth-method.js';
+import type { CredentialProvider } from './credential-provider.js';
+/**
+ * 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 declare function declaresAuthMethodContract(provider: CredentialProvider): boolean;
+/**
+ * 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 declare function authMethodSnapshot(method: object): unknown;
+/**
+ * Whether `value` meets the static checks of the contract.
+ *
+ * @experimental
+ */
+export declare function isAuthMethod(value: unknown): value is AuthMethod;
+/**
+ * Throw an {@link AuthMethodContractError} listing every problem when `value`
+ * does not meet the static checks of the contract.
+ *
+ * @experimental
+ */
+export declare function assertAuthMethod(value: unknown): asserts value is AuthMethod;
+/**
+ * Every static problem of `value` as an AuthMethod, one sentence each; empty
+ * when there is none.
+ *
+ * @experimental
+ */
+export declare function authMethodProblems(value: unknown): string[];
+/**
+ * The problems of a route list; exported for the mount, which checks again.
+ *
+ * @experimental
+ */
+export declare function routeProblems(routes: unknown): string[];
+/**
+ * The problems of `type` as an AuthMethod's type: its pattern, and not one of
+ * the reserved types.
+ *
+ * @experimental
+ */
+export declare function authMethodTypeProblems(type: unknown): string[];