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

package/dist/testing/contract-kit.js

@@ -0,0 +1,526 @@
+import { createHash } from 'node:crypto';
+import { toJSONSchema } from 'zod';
+import { createAuthMethodContext } from '../lib/context.js';
+import { completeUpstreamStep, presentedUpstreamBinding, startUpstreamStep, upstreamBindingMatches, } from '../lib/engine.js';
+import { AuthMethodContractError } from '../lib/errors.js';
+import { authMethodParameters } from '../lib/parameters.js';
+import { authMethodProblems } from '../lib/validate.js';
+import { disableFetch } from './fetch-guard.js';
+/** The kit's realm. */
+const KIT_ORIGIN = 'https://realm.kit.invalid';
+/** Inputs no method's `verify()` may accept: none is a result of its callback. */
+const JUNK_RESULTS = [
+    undefined,
+    null,
+    '',
+    'kit-forged',
+    {},
+    [],
+    { externalSub: 'kit-forged', assuranceLevel: 'high', rawClaims: {} },
+];
+/** Ends a run that cannot go on; the problems so far are reported. */
+class KitStop extends Error {
+}
+/**
+ * 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 async function checkAuthMethod(method, scenario) {
+    if (process.env['NODE_ENV'] === 'production') {
+        throw new Error('checkAuthMethod is a test kit: it does not run with NODE_ENV=production');
+    }
+    const run = {
+        problems: [],
+        checks: [],
+        logLines: [],
+        egressBodies: [],
+        egressCalls: 0,
+        fail(problem) {
+            this.problems.push(problem);
+        },
+        stop(problem) {
+            this.problems.push(problem);
+            throw new KitStop(problem);
+        },
+    };
+    const fetchGuard = disableFetch();
+    let secrets = [];
+    try {
+        await fetchGuard.run(async () => {
+            const staticProblems = authMethodProblems(method);
+            if (staticProblems.length > 0) {
+                run.problems.push(...staticProblems);
+                throw new KitStop('static');
+            }
+            run.checks.push('static');
+            secrets = configSecrets(method, scenario.config, run);
+            run.checks.push('config-schema');
+            const context = kitContext(method, scenario, run);
+            run.checks.push('context');
+            await runChecks(method, scenario, context, run);
+        });
+    }
+    catch (error) {
+        if (!(error instanceof KitStop))
+            run.problems.push(`the run threw: ${describe(error)}`);
+    }
+    finally {
+        fetchGuard.restore();
+    }
+    if (fetchGuard.calls() > 0) {
+        run.problems.push('the method called fetch: its outbound calls go through context.egress');
+    }
+    const forms = secretForms(secrets, configStrings(scenario.config));
+    if (run.logLines.some((line) => forms.some((form) => line.includes(form)))) {
+        run.problems.push('a log line carries the value of a writeOnly config member');
+    }
+    if (run.problems.length > 0) {
+        throw new AuthMethodContractError(`The AuthMethod ${String(method?.type)}`, run.problems);
+    }
+    run.checks.push('egress-only', 'secrets-not-logged');
+    return Object.freeze({ checks: Object.freeze([...run.checks]) });
+}
+async function runChecks(method, scenario, context, run) {
+    const first = await started(method, context, run);
+    const second = await started(method, context, run);
+    if (JSON.stringify(first.start.transaction) === JSON.stringify(second.start.transaction)) {
+        run.fail('two starts answered the same transaction: its state must be fresh for each start');
+    }
+    run.checks.push('start');
+    bindingChecks(first, second, run);
+    run.checks.push('transaction-binding');
+    // The provider signs the person in, for the second start.
+    const signIn = await scenario.callback(new URL(second.start.redirectTo));
+    const bodiesBefore = run.egressBodies.length;
+    const happy = await callback(method, context, signIn, second.start, run);
+    pkceChecks(second, run.egressBodies.slice(bodiesBefore), run);
+    if (happy === HOST_REFUSED) {
+        run.stop("the provider's callback does not carry back the binding start() answered, in the callback route's bindingParameter (state by default): the host answers it as transaction_mismatch before the method runs");
+    }
+    const completion = await completeUpstreamStep(method, happy).catch((error) => run.stop(`the callback's outcome was refused: ${describe(error)}`));
+    if (completion.kind !== 'identity') {
+        run.stop(`the provider's callback ended as ${describeOutcome(completion)}, not in an identity`);
+    }
+    const issuer = completion.identity.rawClaims['iss'];
+    if (typeof issuer !== 'string' || issuer.length === 0) {
+        run.fail('the identity names no issuer (rawClaims.iss): the sign-in flow binds a subject to its issuer, and refuses an identity without one');
+    }
+    const result = happy.result;
+    // The same person, a second time: the same subject.
+    const third = await started(method, context, run);
+    const again = await callback(method, context, await scenario.callback(new URL(third.start.redirectTo)), third.start, run);
+    const repeated = await completeUpstreamStep(method, again).catch(() => undefined);
+    if (repeated?.kind !== 'identity' ||
+        repeated.identity.externalSub !== completion.identity.externalSub) {
+        run.fail('a second sign-in of the same person did not resolve the same externalSub');
+    }
+    run.checks.push('callback', 'pkce');
+    await verifyChecks(method, result, run);
+    run.checks.push('verify-fails-closed');
+    if (scenario.declined !== undefined) {
+        const fourth = await started(method, context, run);
+        const declinedRequest = await scenario.declined(new URL(fourth.start.redirectTo));
+        const declined = await callback(method, context, declinedRequest, fourth.start, run);
+        if (declined.kind !== 'declined') {
+            run.fail(`the declined callback answered ${describeOutcome(declined)}, not declined`);
+        }
+        run.checks.push('declined');
+    }
+}
+/**
+ * The binding `start()` answers is what the host checks a callback against
+ * (the engine has already checked it is 22 to 512 base64url characters, the
+ * length of 128 random bits; the kit cannot measure randomness). Two starts
+ * must answer different bindings, and the start must send its binding to the
+ * provider, in the redirect or in a body the method posted (a pushed
+ * authorization request), or the provider cannot carry it back.
+ */
+function bindingChecks(first, second, run) {
+    if (first.start.binding === second.start.binding) {
+        run.fail('two starts answered the same binding: it must be fresh for each start');
+    }
+    if (!second.values.includes(second.start.binding)) {
+        run.fail('start() did not send its binding to the provider, in the redirect or in a body it posted: the provider cannot carry it back');
+    }
+}
+/** What a PKCE verifier may be (RFC 7636 §4.1): 43 to 128 unreserved characters. */
+const PKCE_VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/;
+/** What an S256 challenge is: the base64url SHA-256 of a verifier, 43 characters. */
+const PKCE_S256_CHALLENGE = /^[A-Za-z0-9_-]{43}$/;
+/**
+ * PKCE with S256, as QAuth requires it of every authorization-code request
+ * (RFC 7636): an authorization request that asks for a code carries
+ * `code_challenge_method=S256` and a challenge, and every token request the
+ * callback made carries the verifier whose S256 is that challenge.
+ */
+function pkceChecks(start, callbackBodies, run) {
+    const codeRequest = start.authorizationRequests.find((parameters) => parameters.get('response_type') === 'code');
+    const challenge = codeRequest?.get('code_challenge') ?? undefined;
+    if (codeRequest !== undefined &&
+        (codeRequest.get('code_challenge_method') !== 'S256' ||
+            challenge === undefined ||
+            !PKCE_S256_CHALLENGE.test(challenge))) {
+        run.fail('the authorization request asks for a code without PKCE: it must carry code_challenge_method=S256 and a code_challenge (RFC 7636)');
+    }
+    const tokenRequests = callbackBodies
+        .map((body) => new URLSearchParams(body))
+        .filter((parameters) => parameters.get('grant_type') === 'authorization_code');
+    for (const tokenRequest of tokenRequests) {
+        const verifier = tokenRequest.get('code_verifier');
+        if (verifier === null ||
+            !PKCE_VERIFIER.test(verifier) ||
+            challenge === undefined ||
+            createHash('sha256').update(verifier, 'ascii').digest('base64url') !== challenge) {
+            run.fail("the token request carries no code_verifier whose S256 is the start's code_challenge (RFC 7636 §4.5)");
+            return;
+        }
+    }
+}
+/** `verify()` rejects anything that is not a fresh result of its own callback. */
+async function verifyChecks(method, result, run) {
+    const accepts = (input) => Promise.resolve()
+        .then(() => method.verify(input))
+        .then(() => true, () => false);
+    for (const junk of JUNK_RESULTS) {
+        if (await accepts(junk)) {
+            run.fail(`verify() resolved for ${JSON.stringify(junk) ?? 'undefined'}, which no callback produced`);
+        }
+    }
+    const copy = plainCopy(result);
+    if (copy !== undefined && (await accepts(copy))) {
+        run.fail("verify() resolved for a copy of a callback's result: it must accept only its own results");
+    }
+    if (await accepts(result)) {
+        run.fail('verify() resolved for a result it had already verified: a result signs one person in once');
+    }
+}
+/** The values of a body the method posted: a form, or the strings of a JSON document. */
+function bodyValues(body) {
+    const values = [...new URLSearchParams(body).values()];
+    try {
+        values.push(...stringLeaves(JSON.parse(body), 0));
+    }
+    catch {
+        // Not JSON: the form reading above is all there is.
+    }
+    return values;
+}
+/** A structural copy of `value`, or `undefined` when it cannot be copied. */
+function plainCopy(value) {
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        try {
+            return JSON.parse(JSON.stringify(value));
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+async function started(method, context, run) {
+    const before = run.egressBodies.length;
+    const start = await startUpstreamStep(method, { uiLocales: ['en'] }, context).catch((error) => run.stop(`start() failed: ${describe(error)}`));
+    const posted = run.egressBodies.slice(before);
+    const values = [
+        ...new URL(start.redirectTo).searchParams.values(),
+        ...posted.flatMap(bodyValues),
+    ];
+    const authorizationRequests = [
+        new URL(start.redirectTo).searchParams,
+        ...posted.map((body) => new URLSearchParams(body)),
+    ];
+    return { start, values, authorizationRequests };
+}
+/** `work()`, with a synchronous throw read as a rejection, as the host's `await` reads it. */
+function settled(work) {
+    return Promise.resolve().then(work);
+}
+/**
+ * What the kit's host answers a callback whose binding does not match, as the
+ * route mount does: before the method runs.
+ */
+const HOST_REFUSED = Object.freeze({ kind: 'failed', reason: 'transaction_mismatch' });
+/**
+ * Run one request through the method's routes as the host would, following a
+ * bounce once: the callback's binding is compared with the start's before
+ * the handler is called, and a mismatch answers {@link HOST_REFUSED}.
+ */
+async function callback(method, context, request, start, run) {
+    let route = findRoute(method.routes, request.method, request.path);
+    if (route === undefined) {
+        return run.stop(`the scenario's callback names ${request.method} ${request.path}, which is not a route of the method`);
+    }
+    // The objects the host hands a handler: frozen, with no prototype, within
+    // the caps (`authMethodParameters`); a GET has an empty form.
+    let query = authMethodParameters(request.query);
+    let form = authMethodParameters(request.method === 'POST' ? request.form : undefined);
+    if (route.kind === 'bounce') {
+        const bounceRoute = route;
+        // A bounce is handed no context, as the host hands it none.
+        const bounce = await settled(() => bounceRoute.handle({ method: bounceRoute.method, query, form })).catch((error) => run.stop(`the bounce route threw: ${describe(error)}`));
+        const { to, query: carried } = (typeof bounce === 'object' && bounce !== null ? bounce : {});
+        const target = method.routes.find((candidate) => candidate.kind === 'callback' && candidate.method === 'GET' && candidate.path === to);
+        if (target === undefined) {
+            return run.stop(`the bounce route sent the browser to ${String(to)}, which is not a GET callback route of the method`);
+        }
+        if (typeof carried !== 'object' ||
+            carried === null ||
+            Array.isArray(carried) ||
+            (Object.getPrototypeOf(carried) !== Object.prototype &&
+                Object.getPrototypeOf(carried) !== null) ||
+            !Object.values(carried).every((value) => typeof value === 'string')) {
+            return run.stop('the bounce route carried a query that is not a plain object of strings');
+        }
+        route = target;
+        // As the browser brings it back: through the URL the host redirects to.
+        query = authMethodParameters(Object.fromEntries(new URLSearchParams(carried)));
+        form = authMethodParameters(undefined);
+    }
+    if (route.kind !== 'callback') {
+        return run.stop(`${route.method} ${route.path} is not a callback route`);
+    }
+    const callbackRoute = route;
+    if (!upstreamBindingMatches(start.binding, presentedUpstreamBinding(callbackRoute, { query, form }))) {
+        return HOST_REFUSED;
+    }
+    const transaction = start.transaction;
+    return settled(() => callbackRoute.handle({ method: callbackRoute.method, query, form, transaction }, context)).catch((error) => run.stop(`the callback route threw: ${describe(error)}`));
+}
+function findRoute(routes, method, path) {
+    return routes.find((route) => route.method === method && route.path === path);
+}
+/** The method's context in the kit's realm, over a fake egress, signer and logger. */
+function kitContext(method, scenario, run) {
+    try {
+        return createAuthMethodContext(method, {
+            config: scenario.config,
+            origin: KIT_ORIGIN,
+            realmName: 'kit',
+            realmId: '00000000-0000-4000-8000-000000000000',
+            providerId: method.type,
+            signerCaller: 'api',
+            egress: {
+                async request(request) {
+                    run.egressCalls += 1;
+                    if (request.body !== undefined) {
+                        run.egressBodies.push(typeof request.body === 'string'
+                            ? request.body
+                            : Buffer.from(request.body).toString('utf8'));
+                    }
+                    if (!/^[a-z][a-z0-9_.:-]{0,63}$/.test(request.purpose)) {
+                        throw new Error('egress refused: purpose must be a fixed label');
+                    }
+                    if (new URL(request.url).protocol !== 'https:') {
+                        throw new Error('egress refused: the URL is not https');
+                    }
+                    if (scenario.egress === undefined) {
+                        throw new Error('egress refused: the scenario answers no outbound call');
+                    }
+                    // The scenario sees the call as the method sent it: no realm, and
+                    // `redirect: 'error'` for the zero redirect cap it asked for.
+                    const { realm: _realm, limits, ...rest } = request;
+                    return scenario.egress(limits?.maxRedirects === 0 ? { ...rest, redirect: 'error' } : rest);
+                },
+            },
+            signer: {
+                async signClientAssertion() {
+                    return 'eyJhbGciOiJSUzI1NiJ9.eyJraXQiOnRydWV9.a2l0';
+                },
+                async getUpstreamJwks() {
+                    return { keys: [] };
+                },
+            },
+            log: kitLogger(run.logLines),
+        });
+    }
+    catch (error) {
+        return run.stop(`the scenario's config does not pass configSchema: ${describe(error)}`);
+    }
+}
+/** Check the config schema renders as an object schema; collect its writeOnly values. */
+function configSecrets(method, config, run) {
+    let schema;
+    try {
+        schema = toJSONSchema(method.configSchema);
+    }
+    catch (error) {
+        run.fail(`configSchema does not render as JSON Schema: ${describe(error)}`);
+        return [];
+    }
+    if (schema.type !== 'object') {
+        run.fail('configSchema must be an object schema');
+    }
+    return writeOnlyValues(schema, schema, config, 0);
+}
+/**
+ * The string values of `config` under the members its schema marks
+ * `writeOnly`: every string leaf of such a member, whatever its shape. The
+ * walk follows `properties`, `additionalProperties`, `items`, the members of
+ * `anyOf`, `oneOf` and `allOf`, and local `$ref`s into `$defs`.
+ */
+function writeOnlyValues(root, schema, config, depth) {
+    if (typeof schema !== 'object' || schema === null || depth > 32)
+        return [];
+    const node = schema;
+    const reference = node['$ref'];
+    if (typeof reference === 'string') {
+        return writeOnlyValues(root, resolveLocalRef(root, reference), config, depth + 1);
+    }
+    if (node['writeOnly'] === true) {
+        // Every one, however short: a short secret is still a secret. A scenario
+        // gives realistic ones, so a short one does not match by accident.
+        return stringLeaves(config, 0);
+    }
+    const found = [];
+    for (const keyword of ['anyOf', 'oneOf', 'allOf']) {
+        const members = node[keyword];
+        if (Array.isArray(members)) {
+            for (const member of members)
+                found.push(...writeOnlyValues(root, member, config, depth + 1));
+        }
+    }
+    if (Array.isArray(config)) {
+        found.push(...config.flatMap((item) => writeOnlyValues(root, node['items'], item, depth + 1)));
+        return found;
+    }
+    if (typeof config !== 'object' || config === null)
+        return found;
+    const properties = (typeof node['properties'] === 'object' && node['properties'] !== null ? node['properties'] : {});
+    for (const [key, value] of Object.entries(config)) {
+        const child = Object.hasOwn(properties, key) ? properties[key] : node['additionalProperties'];
+        found.push(...writeOnlyValues(root, child, value, depth + 1));
+    }
+    return found;
+}
+/** The schema a local `#/...` reference names, or `undefined`. */
+function resolveLocalRef(root, reference) {
+    if (!reference.startsWith('#/'))
+        return undefined;
+    let node = root;
+    for (const segment of reference.slice(2).split('/')) {
+        if (typeof node !== 'object' || node === null)
+            return undefined;
+        node = node[segment.replace(/~1/g, '/').replace(/~0/g, '~')];
+    }
+    return node;
+}
+/** Every string inside `value`, at any depth. */
+function stringLeaves(value, depth) {
+    if (typeof value === 'string')
+        return [value];
+    if (typeof value !== 'object' || value === null || depth > 32)
+        return [];
+    return Object.values(value).flatMap((item) => stringLeaves(item, depth + 1));
+}
+/** Every string of the config, for the forms a secret takes beside another value. */
+function configStrings(config) {
+    return stringLeaves(config, 0);
+}
+/**
+ * The forms a secret can take in a log line: itself, base64 and base64url,
+ * percent-encoded, and the HTTP Basic credentials it makes with any other
+ * string of the config (`client_secret_basic`, RFC 6749 §2.3.1).
+ */
+function secretForms(secrets, strings) {
+    const base64 = (text) => Buffer.from(text, 'utf8').toString('base64');
+    const base64url = (text) => Buffer.from(text, 'utf8').toString('base64url');
+    const forms = new Set();
+    for (const secret of secrets) {
+        forms.add(secret);
+        forms.add(base64(secret));
+        forms.add(base64url(secret));
+        forms.add(encodeURIComponent(secret));
+        for (const other of strings) {
+            if (other === secret)
+                continue;
+            forms.add(base64(`${other}:${secret}`));
+            forms.add(base64(`${encodeURIComponent(other)}:${encodeURIComponent(secret)}`));
+        }
+    }
+    // Only the empty string is left out: it is inside every line.
+    return [...forms].filter((form) => form.length > 0);
+}
+function kitLogger(lines) {
+    const write = (fields, message) => {
+        lines.push(`${String(message)} ${serialised(fields)}`);
+    };
+    return { debug: write, info: write, warn: write, error: write };
+}
+/**
+ * JSON of a log line's fields. An Error is written out with its own fields
+ * (as the server's error serializer copies them), its message, stack and
+ * cause, and an AggregateError's errors.
+ */
+function serialised(value) {
+    const seen = new WeakSet();
+    try {
+        return (JSON.stringify(value, (_key, member) => {
+            if (member instanceof Error) {
+                if (seen.has(member))
+                    return '[cycle]';
+                seen.add(member);
+                return {
+                    ...member,
+                    name: member.name,
+                    message: member.message,
+                    stack: member.stack,
+                    cause: member.cause,
+                    ...(member instanceof AggregateError ? { errors: member.errors } : {}),
+                };
+            }
+            if (typeof member === 'object' && member !== null) {
+                if (seen.has(member))
+                    return '[cycle]';
+                seen.add(member);
+            }
+            return typeof member === 'bigint' ? member.toString() : member;
+        }) ?? '');
+    }
+    catch {
+        return String(value);
+    }
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function describeOutcome(outcome) {
+    if (typeof outcome !== 'object' || outcome === null)
+        return String(outcome);
+    const { kind, reason } = outcome;
+    return reason === undefined ? String(kind) : `${String(kind)} (${String(reason)})`;
+}

package/dist/testing/fetch-guard.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The contract test kit's guard on `fetch` (#599): while the kit runs a
+ * method, the global `fetch` refuses and counts every call, so a method that
+ * calls `fetch` instead of `context.egress` fails the kit. It never sends
+ * anything. It sees only the global `fetch`: a method that imports
+ * `node:https` or `undici`, or kept a `fetch` from before the run, gets past
+ * it, and the `qauth/no-direct-network` lint rule is what refuses those in
+ * QAuth's own code.
+ *
+ * It lives under `src/testing/`, test support served from the
+ * `@qauth-labs/plugin-sdk/testing` entry point only, because it replaces a
+ * global that server code must not touch (`qauth/no-direct-network`).
+ *
+ * @experimental
+ */
+/**
+ * A disabled `fetch`, and the way back.
+ *
+ * @experimental
+ */
+export interface FetchGuard {
+    /** Run `work` as this guard's run: the `fetch` calls it makes count here. */
+    run<T>(work: () => Promise<T>): Promise<T>;
+    /** How many times `fetch` was called by this guard's run. */
+    calls(): number;
+    /** Lower this guard. The original `fetch` comes back with the last guard. */
+    restore(): void;
+}
+/**
+ * Replace the global `fetch` with one that refuses and counts every call.
+ * Guards nest, and overlapping runs each count only their own calls: a call
+ * is counted against the run it was made in, or, when it belongs to none,
+ * against every run that is up. The original `fetch` comes back when the
+ * last guard is lowered.
+ *
+ * @experimental
+ */
+export declare function disableFetch(): FetchGuard;

package/dist/testing/fetch-guard.js

@@ -0,0 +1,49 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** The run a `fetch` call belongs to, across its awaits. */
+const runs = new AsyncLocalStorage();
+/** The guards up now, and the `fetch` the first one replaced. */
+let active = 0;
+let saved;
+const counters = new Set();
+/**
+ * Replace the global `fetch` with one that refuses and counts every call.
+ * Guards nest, and overlapping runs each count only their own calls: a call
+ * is counted against the run it was made in, or, when it belongs to none,
+ * against every run that is up. The original `fetch` comes back when the
+ * last guard is lowered.
+ *
+ * @experimental
+ */
+export function disableFetch() {
+    if (active === 0) {
+        saved = { fetch: globalThis.fetch };
+        globalThis.fetch = (() => {
+            const current = runs.getStore();
+            if (current !== undefined)
+                current.count += 1;
+            else
+                for (const counter of counters)
+                    counter.count += 1;
+            return Promise.reject(new Error('fetch is disabled: send through context.egress'));
+        });
+    }
+    active += 1;
+    const counter = { count: 0 };
+    counters.add(counter);
+    let lowered = false;
+    return {
+        run: (work) => runs.run(counter, work),
+        calls: () => counter.count,
+        restore: () => {
+            if (lowered)
+                return;
+            lowered = true;
+            counters.delete(counter);
+            active -= 1;
+            if (active === 0 && saved !== undefined) {
+                globalThis.fetch = saved.fetch;
+                saved = undefined;
+            }
+        },
+    };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@qauth-labs/plugin-sdk/testing` — test support for authors of AuthMethods
+ * (#599, EXPERIMENTAL): the contract test kit, `checkAuthMethod`, which checks
+ * a method against the contract in any test runner.
+ *
+ * Never imported by the main entry point: while the kit runs, it replaces the
+ * global `fetch`, and it refuses to run with `NODE_ENV=production`.
+ *
+ * @packageDocumentation
+ */
+export type { AuthMethodKitReport, AuthMethodKitRequest, AuthMethodKitScenario, } from './contract-kit.js';
+export { checkAuthMethod } from './contract-kit.js';

package/dist/testing/index.js

@@ -0,0 +1 @@
+export { checkAuthMethod } from './contract-kit.js';