@capybara-hq/testing 0.0.0-stage → 0.1.0-rc.0

package/dist/fake-npm-registry.js

@@ -0,0 +1,174 @@
+import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+const sri = (bytes) => `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
+/**
+ * An attestations answer in the shape npm serves (`{ attestations: [...] }`): the npm publish
+ * attestation and the SLSA v1 provenance, each a sigstore bundle with a DSSE envelope whose payload
+ * is a base64 in-toto statement about `pkg:npm/<name>@<version>` (subject digest = the tgz's sha512,
+ * or `subjectSha512` to make it about another tarball). The signatures are placeholders (the kernel
+ * does not verify them). `predicate` replaces the SLSA predicate (to test missing fields).
+ */
+export function npmProvenanceAttestations(o) {
+    const purl = `pkg:npm/${o.name.replace(/^@/, "%40")}@${o.version}`;
+    const subject = [
+        {
+            name: purl,
+            digest: { sha512: o.subjectSha512 ?? createHash("sha512").update(o.tgz).digest("hex") },
+        },
+    ];
+    const ref = o.ref ?? "refs/heads/main";
+    const predicate = o.predicate ?? {
+        buildDefinition: {
+            buildType: "https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1",
+            externalParameters: {
+                workflow: {
+                    ref,
+                    repository: o.repository,
+                    path: o.workflow ?? ".github/workflows/release.yml",
+                },
+            },
+            internalParameters: {
+                github: { event_name: "push", repository_id: "1", repository_owner_id: "2" },
+            },
+            resolvedDependencies: [
+                { uri: `git+${o.repository}@${ref}`, digest: { gitCommit: o.commit } },
+            ],
+        },
+        runDetails: {
+            builder: { id: "https://github.com/actions/runner/github-hosted" },
+            metadata: { invocationId: `${o.repository}/actions/runs/1/attempts/1` },
+        },
+    };
+    const bundle = (predicateType, pred) => ({
+        mediaType: "application/vnd.dev.sigstore.bundle+json;version=0.2",
+        verificationMaterial: { tlogEntries: [], x509CertificateChain: { certificates: [] } },
+        dsseEnvelope: {
+            payload: Buffer.from(JSON.stringify({
+                _type: "https://in-toto.io/Statement/v1",
+                subject,
+                predicateType,
+                predicate: pred,
+            })).toString("base64"),
+            payloadType: "application/vnd.in-toto+json",
+            signatures: [{ sig: "MEUCIQ-placeholder", keyid: "" }],
+        },
+    });
+    const publish = "https://github.com/npm/attestation/tree/main/specs/publish/v0.1";
+    return {
+        attestations: [
+            {
+                predicateType: publish,
+                bundle: bundle(publish, {
+                    name: o.name,
+                    version: o.version,
+                    registry: "https://registry.npmjs.org",
+                }),
+            },
+            {
+                predicateType: "https://slsa.dev/provenance/v1",
+                bundle: bundle("https://slsa.dev/provenance/v1", predicate),
+            },
+        ],
+    };
+}
+const tarballName = (p) => `${p.name.replace(/^@[^/]+\//, "")}-${p.version}.tgz`;
+/**
+ * A fake npm registry: `GET /<name>` (a scoped package written as npm does, `@scope%2fname`; an
+ * unencoded `/` is accepted too) returns the packument (`versions[v].dist.{tarball, integrity}` and
+ * `dist-tags`), `GET /<name>/-/<file>.tgz` returns the tarball, and
+ * `GET /-/npm/v1/attestations/<name>@<version>` returns that version's `attestations` (404 when it
+ * has none). Unknown packages are 404.
+ */
+export async function startFakeNpmRegistry(opts) {
+    const requests = [];
+    const authorizations = [];
+    const accepts = [];
+    let base = "";
+    const server = createServer((req, res) => {
+        const path = req.url ?? "/";
+        requests.push(path);
+        authorizations.push(req.headers.authorization);
+        accepts.push(req.headers.accept);
+        if (req.method !== "GET") {
+            res.writeHead(405).end();
+            return;
+        }
+        const decoded = decodeURIComponent(path.split("?")[0]).slice(1);
+        const ATT = "-/npm/v1/attestations/";
+        if (decoded.startsWith(ATT)) {
+            const spec = decoded.slice(ATT.length);
+            const at = spec.lastIndexOf("@");
+            const p = opts.packages.find((x) => at > 0 && x.name === spec.slice(0, at) && x.version === spec.slice(at + 1));
+            if (p?.attestations === undefined) {
+                res.writeHead(404, { "content-type": "application/json" }).end('{"error":"Not found"}');
+                return;
+            }
+            res
+                .writeHead(200, { "content-type": "application/json" })
+                .end(JSON.stringify(p.attestations));
+            return;
+        }
+        const tarAt = decoded.indexOf("/-/");
+        if (tarAt >= 0) {
+            const name = decoded.slice(0, tarAt);
+            const rest = decoded.slice(tarAt + 3);
+            const redirect = rest.startsWith("r/");
+            const file = redirect ? rest.slice(2) : rest;
+            const p = opts.packages.find((x) => x.name === name && tarballName(x) === file);
+            if (!p) {
+                res.writeHead(404).end();
+                return;
+            }
+            if (redirect) {
+                res.writeHead(302, { location: `${base}/${name}/-/${file}` }).end();
+                return;
+            }
+            res
+                .writeHead(200, {
+                "content-type": "application/octet-stream",
+                "content-length": String(p.tgz.byteLength),
+            })
+                .end(Buffer.from(p.tgz));
+            return;
+        }
+        const versions = opts.packages.filter((x) => x.name === decoded);
+        if (versions.length === 0) {
+            res.writeHead(404, { "content-type": "application/json" }).end('{"error":"Not found"}');
+            return;
+        }
+        const distTags = {};
+        for (const v of versions)
+            for (const t of v.tags ?? [])
+                distTags[t] = v.version;
+        distTags.latest ??= versions.at(-1).version;
+        const doc = {
+            name: decoded,
+            "dist-tags": distTags,
+            versions: Object.fromEntries(versions.map((v) => [
+                v.version,
+                {
+                    name: v.name,
+                    version: v.version,
+                    dist: {
+                        tarball: v.tarballUrl ??
+                            `${base}/${v.name}/-/${v.redirectTarball ? "r/" : ""}${tarballName(v)}`,
+                        integrity: v.integrity ?? sri(v.tgz),
+                    },
+                },
+            ])),
+        };
+        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(doc));
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    base = `http://127.0.0.1:${server.address().port}`;
+    return {
+        url: base,
+        requests,
+        authorizations,
+        accepts,
+        stop: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }),
+    };
+}

package/dist/fake-oauth-server.d.ts

@@ -0,0 +1,63 @@
+/** 预注册的客户端（client_credentials 与「手填 client」用）。 */
+export interface FakeOAuthClient {
+    clientId: string;
+    /** 不给 = 公开客户端（只能走授权码 + PKCE）。 */
+    clientSecret?: string;
+    /** 允许的回调地址；不给 = 任意。 */
+    redirectUris?: string[];
+}
+export interface FakeOAuthServerOptions {
+    /** 暴露 DCR（RFC 7591）注册端点；默认 true，运行中可用 `setDcr` 切换。 */
+    dcr?: boolean;
+    /** 授权服务器元数据的位置：RFC 8414（默认）或只有 OpenID 发现文档。 */
+    metadata?: "oauth" | "openid";
+    /** access token 有效期（秒），默认 3600；0 = 令牌响应不带 expires_in。 */
+    accessTokenTtl?: number;
+    clients?: FakeOAuthClient[];
+    /** 令牌端点每次响应前等待的毫秒数（放大并发刷新的竞态窗口）。 */
+    tokenDelayMs?: number;
+    scopesSupported?: string[];
+    /** 元数据里的 `code_challenge_methods_supported`；null = 不声明。默认 `["S256"]`。 */
+    pkceMethods?: string[] | null;
+}
+/** 令牌端点收到的一次请求（不含任何密钥）。 */
+export interface FakeTokenRequest {
+    grantType: string;
+    clientId: string | undefined;
+    resource: string | undefined;
+    scope: string | undefined;
+    /** 客户端认证方式：Basic 头、表单里的 client_secret、或只有 client_id。 */
+    clientAuth: "basic" | "post" | "none";
+    /** 本次响应的 HTTP 状态。 */
+    status: number;
+}
+export interface FakeOAuthServer {
+    /** issuer（`http://127.0.0.1:<port>`），也是各端点的基址。 */
+    issuer: string;
+    tokenRequests: FakeTokenRequest[];
+    /** DCR 注册请求体。 */
+    registrations: Record<string, unknown>[];
+    /** 授权端点收到的查询参数。 */
+    authorizeRequests: URLSearchParams[];
+    /** 该 access token 当前有效（存在、未过期、未作废）。 */
+    verify(accessToken: string): boolean;
+    /** 已签发的全部 access / refresh token 与客户端密钥（断言「不出现在日志 / 事件」用）。 */
+    issuedSecrets(): string[];
+    /** 作废全部 access token（refresh token 仍有效）：资源服务随之返回 401。 */
+    revokeAccessTokens(): void;
+    /** 作废全部 refresh token：之后的刷新返回 `invalid_grant`。 */
+    revokeRefreshTokens(): void;
+    /** 下一次授权请求以该 OAuth 错误回跳。 */
+    denyNext(error: string, description?: string): void;
+    setDcr(enabled: boolean): void;
+    /** 接下来 n 次令牌请求直接以该状态与正文响应（模拟限流 429、WAF 403、临时错误等）。 */
+    failTokenRequests(n: number, status: number, body?: unknown): void;
+    /** 下一次授权回跳的 RFC 9207 `iss` 改为该值（默认回跳带真实 issuer）。 */
+    forgeIssNext(iss: string): void;
+    stop(): Promise<void>;
+}
+/**
+ * 本地假 OAuth 授权服务器（127.0.0.1 随机端口）：元数据（RFC 8414 或 OpenID 发现）、授权端点（不出页面、自动
+ * 批准，强制 PKCE S256）、令牌端点（授权码 + PKCE 校验、refresh 轮换、client_credentials）、可开关的 DCR 端点。
+ */
+export declare function startFakeOAuthServer(opts?: FakeOAuthServerOptions): Promise<FakeOAuthServer>;

package/dist/fake-oauth-server.js

@@ -0,0 +1,284 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+const b64url = (b) => b.toString("base64url");
+const rand = (prefix) => `${prefix}${b64url(randomBytes(18))}`;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const readBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+});
+const json = (res, status, body) => {
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+};
+/**
+ * 本地假 OAuth 授权服务器（127.0.0.1 随机端口）：元数据（RFC 8414 或 OpenID 发现）、授权端点（不出页面、自动
+ * 批准，强制 PKCE S256）、令牌端点（授权码 + PKCE 校验、refresh 轮换、client_credentials）、可开关的 DCR 端点。
+ */
+export async function startFakeOAuthServer(opts = {}) {
+    let dcr = opts.dcr ?? true;
+    const ttl = opts.accessTokenTtl ?? 3600;
+    const clients = new Map((opts.clients ?? []).map((c) => [
+        c.clientId,
+        { clientId: c.clientId, clientSecret: c.clientSecret, redirectUris: c.redirectUris },
+    ]));
+    const codes = new Map();
+    const access = new Map();
+    const refresh = new Map();
+    const secrets = new Set();
+    const tokenRequests = [];
+    const registrations = [];
+    const authorizeRequests = [];
+    let deny;
+    let tokenFailures;
+    let forgedIss;
+    let issuer = "";
+    const metadata = () => ({
+        issuer,
+        authorization_endpoint: `${issuer}/authorize`,
+        token_endpoint: `${issuer}/token`,
+        ...(dcr && { registration_endpoint: `${issuer}/register` }),
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code", "refresh_token", "client_credentials"],
+        ...(opts.pkceMethods !== null && {
+            code_challenge_methods_supported: opts.pkceMethods ?? ["S256"],
+        }),
+        authorization_response_iss_parameter_supported: true,
+        token_endpoint_auth_methods_supported: ["client_secret_basic", "client_secret_post", "none"],
+        ...(opts.scopesSupported !== undefined && { scopes_supported: opts.scopesSupported }),
+    });
+    const issue = (clientId, scope, withRefresh) => {
+        const accessToken = rand("at_");
+        access.set(accessToken, { expiresAt: ttl > 0 ? Date.now() + ttl * 1000 : null });
+        secrets.add(accessToken);
+        const body = { access_token: accessToken, token_type: "Bearer" };
+        if (ttl > 0)
+            body.expires_in = ttl;
+        if (scope !== undefined)
+            body.scope = scope;
+        if (withRefresh) {
+            const refreshToken = rand("rt_");
+            refresh.set(refreshToken, { clientId, scope });
+            secrets.add(refreshToken);
+            body.refresh_token = refreshToken;
+        }
+        return body;
+    };
+    /** 客户端认证：Basic 头或表单里的 client_id / client_secret；公开客户端只带 client_id。 */
+    const authenticate = (req, form) => {
+        let id = form.get("client_id") ?? undefined;
+        let secret = form.get("client_secret") ?? undefined;
+        const h = req.headers.authorization;
+        if (h?.startsWith("Basic ")) {
+            const decoded = Buffer.from(h.slice(6), "base64").toString("utf8");
+            const i = decoded.indexOf(":");
+            id = decodeURIComponent(decoded.slice(0, i));
+            secret = decodeURIComponent(decoded.slice(i + 1));
+        }
+        const c = id === undefined ? undefined : clients.get(id);
+        if (!c)
+            return undefined;
+        if (c.clientSecret !== undefined && c.clientSecret !== secret)
+            return undefined;
+        return c;
+    };
+    const token = async (req, res) => {
+        const form = new URLSearchParams(await readBody(req));
+        if (opts.tokenDelayMs)
+            await sleep(opts.tokenDelayMs);
+        const grantType = form.get("grant_type") ?? "";
+        const entry = {
+            grantType,
+            clientId: undefined,
+            resource: form.get("resource") ?? undefined,
+            scope: form.get("scope") ?? undefined,
+            clientAuth: req.headers.authorization?.startsWith("Basic ")
+                ? "basic"
+                : form.has("client_secret")
+                    ? "post"
+                    : "none",
+            status: 200,
+        };
+        tokenRequests.push(entry);
+        if (tokenFailures && tokenFailures.left > 0) {
+            tokenFailures.left--;
+            entry.status = tokenFailures.status;
+            return json(res, tokenFailures.status, tokenFailures.body ?? { message: "fake failure" });
+        }
+        const fail = (status, error) => {
+            entry.status = status;
+            json(res, status, { error, error_description: `fake: ${error}` });
+        };
+        const client = authenticate(req, form);
+        if (!client)
+            return fail(401, "invalid_client");
+        entry.clientId = client.clientId;
+        if (grantType === "authorization_code") {
+            const code = form.get("code") ?? "";
+            const grant = codes.get(code);
+            codes.delete(code);
+            if (!grant || grant.clientId !== client.clientId)
+                return fail(400, "invalid_grant");
+            if (form.get("redirect_uri") !== grant.redirectUri)
+                return fail(400, "invalid_grant");
+            const verifier = form.get("code_verifier") ?? "";
+            if (b64url(createHash("sha256").update(verifier).digest()) !== grant.challenge) {
+                return fail(400, "invalid_grant");
+            }
+            if (grant.resource !== undefined && form.get("resource") !== grant.resource) {
+                return fail(400, "invalid_target");
+            }
+            return json(res, 200, issue(client.clientId, grant.scope, true));
+        }
+        if (grantType === "refresh_token") {
+            const rt = form.get("refresh_token") ?? "";
+            const r = refresh.get(rt);
+            if (!r || r.clientId !== client.clientId)
+                return fail(400, "invalid_grant");
+            // 轮换：旧 refresh token 立即作废
+            refresh.delete(rt);
+            return json(res, 200, issue(client.clientId, r.scope, true));
+        }
+        if (grantType === "client_credentials") {
+            if (client.clientSecret === undefined)
+                return fail(401, "invalid_client");
+            return json(res, 200, issue(client.clientId, form.get("scope") ?? undefined, false));
+        }
+        return fail(400, "unsupported_grant_type");
+    };
+    const authorize = (url, res) => {
+        const q = url.searchParams;
+        authorizeRequests.push(new URLSearchParams(q));
+        const client = clients.get(q.get("client_id") ?? "");
+        const redirectUri = q.get("redirect_uri") ?? "";
+        if (!client || (client.redirectUris && !client.redirectUris.includes(redirectUri))) {
+            res.writeHead(400, { "content-type": "text/plain" });
+            return res.end("invalid client or redirect_uri");
+        }
+        const back = new URL(redirectUri);
+        const state = q.get("state");
+        if (state !== null)
+            back.searchParams.set("state", state);
+        back.searchParams.set("iss", forgedIss ?? issuer);
+        forgedIss = undefined;
+        const challenge = q.get("code_challenge");
+        if (deny) {
+            back.searchParams.set("error", deny.error);
+            if (deny.description !== undefined)
+                back.searchParams.set("error_description", deny.description);
+            deny = undefined;
+        }
+        else if (q.get("response_type") !== "code") {
+            back.searchParams.set("error", "unsupported_response_type");
+        }
+        else if (!challenge || q.get("code_challenge_method") !== "S256") {
+            back.searchParams.set("error", "invalid_request");
+            back.searchParams.set("error_description", "PKCE S256 is required");
+        }
+        else {
+            const code = rand("code_");
+            codes.set(code, {
+                clientId: client.clientId,
+                redirectUri,
+                challenge,
+                scope: q.get("scope") ?? undefined,
+                resource: q.get("resource") ?? undefined,
+            });
+            back.searchParams.set("code", code);
+        }
+        res.writeHead(302, { location: back.toString() });
+        res.end();
+    };
+    const register = async (req, res) => {
+        const body = JSON.parse((await readBody(req)) || "{}");
+        registrations.push(body);
+        const uris = body.redirect_uris;
+        if (!Array.isArray(uris) || uris.length === 0) {
+            return json(res, 400, { error: "invalid_redirect_uri" });
+        }
+        const method = typeof body.token_endpoint_auth_method === "string"
+            ? body.token_endpoint_auth_method
+            : "client_secret_basic";
+        const clientId = rand("client_");
+        const clientSecret = method === "none" ? undefined : rand("secret_");
+        if (clientSecret)
+            secrets.add(clientSecret);
+        clients.set(clientId, { clientId, clientSecret, redirectUris: uris });
+        json(res, 201, {
+            ...body,
+            client_id: clientId,
+            ...(clientSecret !== undefined && {
+                client_secret: clientSecret,
+                client_secret_expires_at: 0,
+            }),
+            client_id_issued_at: Math.floor(Date.now() / 1000),
+            token_endpoint_auth_method: method,
+        });
+    };
+    const handle = async (req, res) => {
+        const url = new URL(req.url ?? "/", issuer);
+        const path = url.pathname;
+        if (req.method === "GET" && path === "/.well-known/oauth-authorization-server") {
+            if ((opts.metadata ?? "oauth") !== "oauth")
+                return json(res, 404, { error: "not_found" });
+            return json(res, 200, metadata());
+        }
+        if (req.method === "GET" && path === "/.well-known/openid-configuration") {
+            if (opts.metadata !== "openid")
+                return json(res, 404, { error: "not_found" });
+            return json(res, 200, { ...metadata(), subject_types_supported: ["public"] });
+        }
+        if (req.method === "GET" && path === "/authorize")
+            return authorize(url, res);
+        if (req.method === "POST" && path === "/token")
+            return token(req, res);
+        if (req.method === "POST" && path === "/register") {
+            if (!dcr)
+                return json(res, 404, { error: "not_found" });
+            return register(req, res);
+        }
+        json(res, 404, { error: "not_found" });
+    };
+    const http = createServer((req, res) => {
+        handle(req, res).catch((e) => {
+            if (!res.headersSent)
+                json(res, 500, { error: "server_error", detail: String(e) });
+            else
+                res.end();
+        });
+    });
+    await new Promise((resolve) => http.listen(0, "127.0.0.1", resolve));
+    const { port } = http.address();
+    issuer = `http://127.0.0.1:${port}`;
+    return {
+        issuer,
+        tokenRequests,
+        registrations,
+        authorizeRequests,
+        verify: (t) => {
+            const a = access.get(t);
+            return a !== undefined && (a.expiresAt === null || a.expiresAt > Date.now());
+        },
+        issuedSecrets: () => [...secrets],
+        revokeAccessTokens: () => access.clear(),
+        revokeRefreshTokens: () => refresh.clear(),
+        failTokenRequests: (n, status, body) => {
+            tokenFailures = { left: n, status, body };
+        },
+        forgeIssNext: (iss) => {
+            forgedIss = iss;
+        },
+        denyNext: (error, description) => {
+            deny = { error, description };
+        },
+        setDcr: (enabled) => {
+            dcr = enabled;
+        },
+        stop: () => new Promise((resolve, reject) => {
+            http.closeAllConnections();
+            http.close((err) => (err ? reject(err) : resolve()));
+        }),
+    };
+}

package/dist/fake-openapi-server.d.ts

@@ -0,0 +1,50 @@
+export interface FakeOpenApiServerOptions {
+    /** 设了就要求每个 API 请求带这个 API key（不符 → 401）；不设 = 无需认证。 */
+    apiKey?: string;
+    /** API key 的位置：请求头 `X-API-Key`（默认）或 query 参数 `api_key`。 */
+    apiKeyIn?: "header" | "query";
+    /** 错误正文（401 / 404 / 500）回显收到的 API key（测试内核打码用）。 */
+    echoKey?: boolean;
+    /** 规范地址（`/openapi.json`）以 302 重定向到别处，而不是给出文档。 */
+    specRedirect?: boolean;
+    /** 覆盖默认文档：参数为服务基址 `http://127.0.0.1:<port>`。 */
+    spec?: (base: string) => unknown;
+}
+/** 服务收到的一次 API 请求（规范地址的请求也记录）。 */
+export interface FakeOpenApiRequest {
+    method: string;
+    /** 路径（不含 query）。 */
+    path: string;
+    /** 原始 query 串（不含 `?`）。 */
+    query: string;
+    headers: Record<string, string | string[] | undefined>;
+    body: string;
+}
+export interface FakePet {
+    id: number;
+    name: string;
+    tag?: string;
+}
+export interface FakeOpenApiServer {
+    /** 服务基址 `http://127.0.0.1:<port>`。 */
+    url: string;
+    /** 规范地址 `<url>/openapi.json`。 */
+    specUrl: string;
+    /** 当前提供的文档（JSON）。 */
+    spec: () => unknown;
+    /** 运行中替换文档（漂移测试用）。 */
+    setSpec: (spec: unknown) => void;
+    requests: FakeOpenApiRequest[];
+    pets: () => FakePet[];
+    stop(): Promise<void>;
+}
+/**
+ * 默认文档（OpenAPI 3.0.3）：宠物 CRUD + 几个用于测试的操作。servers 用服务器变量给出端口（测试默认值替换），
+ * 参数与模式用内部 `$ref`，认证为 API key。
+ */
+export declare function defaultFakeOpenApiSpec(base: string, apiKeyIn?: "header" | "query"): Record<string, unknown>;
+/**
+ * 本地假 OpenAPI 服务（127.0.0.1 随机端口）：`/openapi.json` 给出文档（或按选项 302），`/v1/*` 实现文档里的
+ * 宠物 CRUD（内存）、回显、纯文本、二进制、500 与 302 操作；可要求 API key（请求头或 query）。
+ */
+export declare function startFakeOpenApiServer(opts?: FakeOpenApiServerOptions): Promise<FakeOpenApiServer>;