@docsxai/engine 0.2.0

package/dist/auth/cookie-jar.js

@@ -0,0 +1,212 @@
+// Minimal RFC-6265 cookie jar for the pure-HTTP strategies (api-login, test-backdoor).
+//
+// Strategies that log in over plain `fetch` must collect `Set-Cookie` headers across the login's
+// redirect chain themselves (fetch's `redirect: "follow"` drops them). The jar parses the
+// attributes Playwright's `storageState` needs and replays matching cookies on each hop.
+import { AuthStrategyConfigError } from "./types.js";
+function isLoopback(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+/** RFC 6265 §5.1.4 default-path: the request path's directory. */
+function defaultPath(requestUrl) {
+    const p = requestUrl.pathname;
+    if (!p.startsWith("/"))
+        return "/";
+    const lastSlash = p.lastIndexOf("/");
+    return lastSlash <= 0 ? "/" : p.slice(0, lastSlash);
+}
+/**
+ * Parse one `Set-Cookie` header into a {@link StorageStateCookie}.
+ * Domain defaults to the request host (host-only); a `Domain` attribute gets the conventional
+ * leading dot (subdomain-matching, mirroring Playwright's representation). `Max-Age` beats
+ * `Expires`; absent both, the cookie is a session cookie (`expires: -1`).
+ * Returns `null` for an unparsable header.
+ */
+export function parseSetCookie(header, requestUrl, now = Date.now()) {
+    const segments = header.split(";");
+    const nameValue = segments[0] ?? "";
+    const eq = nameValue.indexOf("=");
+    if (eq <= 0)
+        return null;
+    const name = nameValue.slice(0, eq).trim();
+    const value = nameValue.slice(eq + 1).trim();
+    if (!name)
+        return null;
+    let domain = requestUrl.hostname;
+    let path;
+    let expires = -1;
+    let maxAge;
+    let httpOnly = false;
+    let secure = false;
+    let sameSite = "Lax";
+    for (const segment of segments.slice(1)) {
+        const sepIdx = segment.indexOf("=");
+        const key = (sepIdx === -1 ? segment : segment.slice(0, sepIdx)).trim().toLowerCase();
+        const val = sepIdx === -1 ? "" : segment.slice(sepIdx + 1).trim();
+        switch (key) {
+            case "domain":
+                if (val)
+                    domain = "." + val.replace(/^\./, "").toLowerCase();
+                break;
+            case "path":
+                if (val.startsWith("/"))
+                    path = val;
+                break;
+            case "expires": {
+                const t = Date.parse(val);
+                if (!Number.isNaN(t))
+                    expires = Math.floor(t / 1000);
+                break;
+            }
+            case "max-age": {
+                const n = Number(val);
+                if (Number.isFinite(n))
+                    maxAge = n;
+                break;
+            }
+            case "httponly":
+                httpOnly = true;
+                break;
+            case "secure":
+                secure = true;
+                break;
+            case "samesite": {
+                const v = val.toLowerCase();
+                sameSite = v === "strict" ? "Strict" : v === "none" ? "None" : "Lax";
+                break;
+            }
+        }
+    }
+    if (maxAge !== undefined)
+        expires = maxAge <= 0 ? 0 : Math.floor(now / 1000) + maxAge;
+    return {
+        name,
+        value,
+        domain,
+        path: path ?? defaultPath(requestUrl),
+        expires,
+        httpOnly,
+        secure,
+        sameSite,
+    };
+}
+function domainMatches(hostname, cookieDomain) {
+    if (cookieDomain.startsWith(".")) {
+        const bare = cookieDomain.slice(1);
+        return hostname === bare || hostname.endsWith(cookieDomain);
+    }
+    return hostname === cookieDomain;
+}
+function pathMatches(requestPath, cookiePath) {
+    if (requestPath === cookiePath)
+        return true;
+    if (!requestPath.startsWith(cookiePath))
+        return false;
+    return cookiePath.endsWith("/") || requestPath[cookiePath.length] === "/";
+}
+export class CookieJar {
+    store = new Map();
+    key(c) {
+        return `${c.name}\u0000${c.domain}\u0000${c.path}`;
+    }
+    /** Store a cookie; an already-expired one (`Max-Age=0` deletion) removes the match instead. */
+    add(cookie, now = Date.now()) {
+        // `expires: -1` is a session cookie (kept); `0` is the Max-Age<=0 deletion marker.
+        if (cookie.expires >= 0 && cookie.expires * 1000 <= now) {
+            this.store.delete(this.key(cookie));
+            return;
+        }
+        this.store.set(this.key(cookie), cookie);
+    }
+    /** Parse + store every `Set-Cookie` header from one response. */
+    addFromHeaders(setCookieHeaders, requestUrl, now = Date.now()) {
+        for (const header of setCookieHeaders) {
+            const cookie = parseSetCookie(header, requestUrl, now);
+            if (cookie)
+                this.add(cookie, now);
+        }
+    }
+    /** First stored cookie with this name, regardless of domain/path. */
+    get(name) {
+        for (const c of this.store.values())
+            if (c.name === name)
+                return c;
+        return undefined;
+    }
+    has(name) {
+        return this.get(name) !== undefined;
+    }
+    cookies() {
+        return [...this.store.values()];
+    }
+    /** `Cookie:` header value for a request to `url` — domain/path/secure/expiry-matched. Empty string if none apply. */
+    cookieHeaderFor(url, now = Date.now()) {
+        const sendable = this.cookies().filter((c) => {
+            if (c.expires > 0 && c.expires * 1000 <= now)
+                return false;
+            if (c.secure && url.protocol !== "https:" && !isLoopback(url.hostname))
+                return false;
+            return domainMatches(url.hostname, c.domain) && pathMatches(url.pathname || "/", c.path);
+        });
+        return sendable.map((c) => `${c.name}=${c.value}`).join("; ");
+    }
+    toStorageState() {
+        return { cookies: this.cookies(), origins: [] };
+    }
+}
+/**
+ * Fetch with `redirect: "manual"`, following up to `maxRedirects` hops (default 5) while
+ * collecting `Set-Cookie` headers into a {@link CookieJar} and replaying matching cookies on
+ * each hop. 303 — and 301/302 on a non-GET — switch the method to GET and drop the body,
+ * matching browser behaviour.
+ */
+export async function fetchCollectingCookies(url, init = {}, opts = {}) {
+    const maxRedirects = opts.maxRedirects ?? 5;
+    const jar = opts.jar ?? new CookieJar();
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const now = opts.now ?? Date.now;
+    let current = new URL(url);
+    let method = (init.method ?? "GET").toUpperCase();
+    let body = init.body;
+    let headers = { ...(init.headers ?? {}) };
+    for (let hops = 0;; hops++) {
+        const cookieHeader = jar.cookieHeaderFor(current, now());
+        const response = await fetchImpl(current, {
+            method,
+            headers: { ...headers, ...(cookieHeader ? { cookie: cookieHeader } : {}) },
+            ...(body !== undefined ? { body } : {}),
+            redirect: "manual",
+        });
+        jar.addFromHeaders(response.headers.getSetCookie(), current, now());
+        const location = response.headers.get("location");
+        const isRedirect = response.status >= 300 && response.status < 400 && location !== null;
+        if (!isRedirect) {
+            return { jar, status: response.status, url: current.href, body: await response.text(), hops };
+        }
+        await response.body?.cancel();
+        if (hops >= maxRedirects) {
+            throw new AuthStrategyConfigError(`redirect chain from ${new URL(url).href} exceeded ${maxRedirects} hops (stuck at ${current.href})`);
+        }
+        current = new URL(location, current);
+        if (response.status === 303 ||
+            ((response.status === 301 || response.status === 302) && method !== "GET")) {
+            method = "GET";
+            body = undefined;
+            const { ["content-type"]: _dropped, ...rest } = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+            headers = rest;
+        }
+    }
+}
+/**
+ * The expiry a login strategy can credibly report: the named cookie's expiry when the caller
+ * knows which cookie is the session, else — only when the jar has exactly one real-expiry
+ * cookie — that one. Ambiguous jars report `undefined` (the cache's `ttl` takes over).
+ */
+export function jarAuthExpiry(state, preferredCookie) {
+    if (preferredCookie) {
+        const c = state.cookies.find((x) => x.name === preferredCookie && x.expires > 0);
+        return c ? c.expires * 1000 : undefined;
+    }
+    const real = state.cookies.filter((c) => c.expires > 0);
+    return real.length === 1 ? real[0].expires * 1000 : undefined;
+}

package/dist/auth/email-otp.d.ts

@@ -0,0 +1,210 @@
+import { z } from "zod";
+import { type AuthPageLauncher } from "./browser-session.js";
+import { type AuthContext, type AuthResult, type AuthStrategy } from "./types.js";
+export interface InboxMessage {
+    to: string;
+    /** Epoch ms the inbox recorded the message. */
+    receivedAt: number;
+    /** Plain-text body the code is extracted from. */
+    body: string;
+}
+export interface InboxProvider {
+    /** Resolve with the newest message for `to` received at/after `since`; reject after `timeoutMs`. */
+    waitForMessage(query: {
+        to: string;
+        since: number;
+        timeoutMs: number;
+    }): Promise<InboxMessage>;
+}
+export type InboxProviderFactory = (options: Record<string, unknown>) => InboxProvider;
+export declare const HttpJsonInboxOptions: z.ZodObject<{
+    /** Inbox endpoint answering `{ messages: [{ to, received_at, body }] }`. */
+    url: z.ZodString;
+    poll_interval_ms: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    url: string;
+    poll_interval_ms: number;
+}, {
+    url: string;
+    poll_interval_ms?: number | undefined;
+}>;
+export type HttpJsonInboxOptions = z.infer<typeof HttpJsonInboxOptions>;
+/** Built-in provider: poll a Mailpit-style JSON inbox until the code mail shows up. */
+export declare function httpJsonInboxProvider(options: Record<string, unknown>): InboxProvider;
+/** Register (or override) an inbox provider under `name` — the email-otp plugin hook. */
+export declare function registerInboxProvider(name: string, factory: InboxProviderFactory): void;
+/** Remove a registered provider (test/plugin teardown). Removing `http-json` restores the built-in. */
+export declare function unregisterInboxProvider(name: string): void;
+export declare function makeInboxProvider(name: string, options: Record<string, unknown>): InboxProvider;
+export declare const EmailOtpInboxOptions: z.ZodObject<{
+    provider: z.ZodDefault<z.ZodString>;
+    /** Provider-specific options (for `http-json`: `{ url, poll_interval_ms? }`). */
+    options: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Env var *name* holding the inbox address to watch. Default: the role's `username` credential. */
+    to_env: z.ZodOptional<z.ZodString>;
+    /** Code-extraction regex (first capture group, else the whole match). */
+    code_pattern: z.ZodDefault<z.ZodString>;
+    /** How long to wait for the code mail. Default 30000. */
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    options: Record<string, unknown>;
+    timeout_ms: number;
+    provider: string;
+    code_pattern: string;
+    to_env?: string | undefined;
+}, {
+    options?: Record<string, unknown> | undefined;
+    timeout_ms?: number | undefined;
+    provider?: string | undefined;
+    to_env?: string | undefined;
+    code_pattern?: string | undefined;
+}>;
+export type EmailOtpInboxOptions = z.infer<typeof EmailOtpInboxOptions>;
+export declare const EmailOtpOptions: z.ZodEffects<z.ZodObject<{
+    login_url: z.ZodString;
+    username_selector: z.ZodString;
+    password_selector: z.ZodString;
+    submit_selector: z.ZodString;
+    otp_selector: z.ZodString;
+    otp_submit_selector: z.ZodOptional<z.ZodString>;
+    success_selector: z.ZodOptional<z.ZodString>;
+    url_matches: z.ZodOptional<z.ZodString>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+    ignore_https_errors: z.ZodDefault<z.ZodBoolean>;
+    pre_steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        action: z.ZodEnum<["click", "fill"]>;
+        selector: z.ZodString;
+        value_env: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }, {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }>, "many">>;
+    inbox: z.ZodObject<{
+        provider: z.ZodDefault<z.ZodString>;
+        /** Provider-specific options (for `http-json`: `{ url, poll_interval_ms? }`). */
+        options: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        /** Env var *name* holding the inbox address to watch. Default: the role's `username` credential. */
+        to_env: z.ZodOptional<z.ZodString>;
+        /** Code-extraction regex (first capture group, else the whole match). */
+        code_pattern: z.ZodDefault<z.ZodString>;
+        /** How long to wait for the code mail. Default 30000. */
+        timeout_ms: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        options: Record<string, unknown>;
+        timeout_ms: number;
+        provider: string;
+        code_pattern: string;
+        to_env?: string | undefined;
+    }, {
+        options?: Record<string, unknown> | undefined;
+        timeout_ms?: number | undefined;
+        provider?: string | undefined;
+        to_env?: string | undefined;
+        code_pattern?: string | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    timeout_ms: number;
+    login_url: string;
+    ignore_https_errors: boolean;
+    otp_selector: string;
+    submit_selector: string;
+    username_selector: string;
+    password_selector: string;
+    pre_steps: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[];
+    inbox: {
+        options: Record<string, unknown>;
+        timeout_ms: number;
+        provider: string;
+        code_pattern: string;
+        to_env?: string | undefined;
+    };
+    url_matches?: string | undefined;
+    success_selector?: string | undefined;
+    otp_submit_selector?: string | undefined;
+}, {
+    login_url: string;
+    otp_selector: string;
+    submit_selector: string;
+    username_selector: string;
+    password_selector: string;
+    inbox: {
+        options?: Record<string, unknown> | undefined;
+        timeout_ms?: number | undefined;
+        provider?: string | undefined;
+        to_env?: string | undefined;
+        code_pattern?: string | undefined;
+    };
+    timeout_ms?: number | undefined;
+    url_matches?: string | undefined;
+    ignore_https_errors?: boolean | undefined;
+    success_selector?: string | undefined;
+    pre_steps?: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[] | undefined;
+    otp_submit_selector?: string | undefined;
+}>, {
+    timeout_ms: number;
+    login_url: string;
+    ignore_https_errors: boolean;
+    otp_selector: string;
+    submit_selector: string;
+    username_selector: string;
+    password_selector: string;
+    pre_steps: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[];
+    inbox: {
+        options: Record<string, unknown>;
+        timeout_ms: number;
+        provider: string;
+        code_pattern: string;
+        to_env?: string | undefined;
+    };
+    url_matches?: string | undefined;
+    success_selector?: string | undefined;
+    otp_submit_selector?: string | undefined;
+}, {
+    login_url: string;
+    otp_selector: string;
+    submit_selector: string;
+    username_selector: string;
+    password_selector: string;
+    inbox: {
+        options?: Record<string, unknown> | undefined;
+        timeout_ms?: number | undefined;
+        provider?: string | undefined;
+        to_env?: string | undefined;
+        code_pattern?: string | undefined;
+    };
+    timeout_ms?: number | undefined;
+    url_matches?: string | undefined;
+    ignore_https_errors?: boolean | undefined;
+    success_selector?: string | undefined;
+    pre_steps?: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[] | undefined;
+    otp_submit_selector?: string | undefined;
+}>;
+export type EmailOtpOptions = z.infer<typeof EmailOtpOptions>;
+export declare class EmailOtpStrategy implements AuthStrategy {
+    private readonly launcher;
+    private readonly env;
+    readonly name: "email-otp";
+    constructor(launcher?: AuthPageLauncher, env?: NodeJS.ProcessEnv);
+    authenticate(ctx: AuthContext): Promise<AuthResult>;
+}

package/dist/auth/email-otp.js

@@ -0,0 +1,166 @@
+// `email-otp` — a ui-form login whose second factor arrives by email: fill + submit the
+// credential form, wait for the OTP prompt, poll an inbox for the code mail, extract the code
+// with `code_pattern`, submit it, capture storageState.
+//
+// The inbox side is pluggable: an `InboxProvider` answers "the first message for <address>
+// received after <instant>". The built-in `http-json` provider polls a Mailpit-style JSON
+// endpoint; test inboxes with other shapes register theirs via `registerInboxProvider` (the
+// plugins runtime exposes the same hook).
+import { z } from "zod";
+import { launchAuthPage } from "./browser-session.js";
+import { jarAuthExpiry } from "./cookie-jar.js";
+import { PreStep, requireEnvVar, resolvePreStepValues, runPreSteps, waitForLoginSuccess, } from "./ui-form.js";
+import { AuthStrategyConfigError, maskSecret, parseStrategyOptions, } from "./types.js";
+export const HttpJsonInboxOptions = z
+    .object({
+    /** Inbox endpoint answering `{ messages: [{ to, received_at, body }] }`. */
+    url: z.string().min(1),
+    poll_interval_ms: z.number().int().positive().default(250),
+})
+    .strict();
+/** Built-in provider: poll a Mailpit-style JSON inbox until the code mail shows up. */
+export function httpJsonInboxProvider(options) {
+    const opts = parseStrategyOptions("email-otp (inbox http-json)", HttpJsonInboxOptions, options);
+    return {
+        async waitForMessage({ to, since, timeoutMs }) {
+            const deadline = Date.now() + timeoutMs;
+            for (;;) {
+                const res = await fetch(opts.url);
+                if (res.ok) {
+                    const parsed = (await res.json());
+                    const hit = (parsed.messages ?? [])
+                        .filter((m) => m.to === to && Date.parse(m.received_at ?? "") >= since)
+                        .at(-1);
+                    if (hit) {
+                        return { to: hit.to, receivedAt: Date.parse(hit.received_at), body: hit.body ?? "" };
+                    }
+                }
+                if (Date.now() >= deadline) {
+                    throw new AuthStrategyConfigError(`email-otp: no message for the watched address arrived within ${timeoutMs}ms`);
+                }
+                await new Promise((r) => setTimeout(r, opts.poll_interval_ms));
+            }
+        },
+    };
+}
+const inboxProviders = new Map([
+    ["http-json", httpJsonInboxProvider],
+]);
+/** Register (or override) an inbox provider under `name` — the email-otp plugin hook. */
+export function registerInboxProvider(name, factory) {
+    inboxProviders.set(name, factory);
+}
+/** Remove a registered provider (test/plugin teardown). Removing `http-json` restores the built-in. */
+export function unregisterInboxProvider(name) {
+    inboxProviders.delete(name);
+    if (name === "http-json")
+        inboxProviders.set("http-json", httpJsonInboxProvider);
+}
+export function makeInboxProvider(name, options) {
+    const factory = inboxProviders.get(name);
+    if (!factory) {
+        throw new AuthStrategyConfigError(`email-otp: unknown inbox provider "${name}" (known: ${[...inboxProviders.keys()].join(", ")})`);
+    }
+    return factory(options);
+}
+// ---------------------------------------------------------------------------
+// Strategy
+// ---------------------------------------------------------------------------
+export const EmailOtpInboxOptions = z
+    .object({
+    provider: z.string().min(1).default("http-json"),
+    /** Provider-specific options (for `http-json`: `{ url, poll_interval_ms? }`). */
+    options: z.record(z.string(), z.unknown()).default({}),
+    /** Env var *name* holding the inbox address to watch. Default: the role's `username` credential. */
+    to_env: z.string().min(1).optional(),
+    /** Code-extraction regex (first capture group, else the whole match). */
+    code_pattern: z.string().min(1).default("\\b(\\d{6})\\b"),
+    /** How long to wait for the code mail. Default 30000. */
+    timeout_ms: z.number().int().positive().default(30_000),
+})
+    .strict();
+export const EmailOtpOptions = z
+    .object({
+    login_url: z.string().min(1),
+    username_selector: z.string().min(1),
+    password_selector: z.string().min(1),
+    submit_selector: z.string().min(1),
+    otp_selector: z.string().min(1),
+    otp_submit_selector: z.string().min(1).optional(),
+    success_selector: z.string().min(1).optional(),
+    url_matches: z.string().min(1).optional(),
+    timeout_ms: z.number().int().positive().default(15_000),
+    ignore_https_errors: z.boolean().default(false),
+    pre_steps: z.array(PreStep).default([]),
+    inbox: EmailOtpInboxOptions,
+})
+    .strict()
+    .refine((o) => o.success_selector !== undefined || o.url_matches !== undefined, {
+    message: "one of success_selector or url_matches is required",
+});
+export class EmailOtpStrategy {
+    launcher;
+    env;
+    name = "email-otp";
+    constructor(launcher = launchAuthPage, env = process.env) {
+        this.launcher = launcher;
+        this.env = env;
+    }
+    async authenticate(ctx) {
+        const opts = parseStrategyOptions(this.name, EmailOtpOptions, ctx.options);
+        const { username, password } = ctx.creds;
+        if (!username || !password) {
+            throw new AuthStrategyConfigError(`email-otp: creds_env must map "username" (${maskSecret(username)}) and "password" (${maskSecret(password)})`);
+        }
+        const to = opts.inbox.to_env
+            ? requireEnvVar(this.name, "inbox.to_env", opts.inbox.to_env, this.env)
+            : username;
+        let codePattern;
+        try {
+            codePattern = new RegExp(opts.inbox.code_pattern);
+        }
+        catch {
+            throw new AuthStrategyConfigError(`email-otp: inbox.code_pattern /${opts.inbox.code_pattern}/ is not a valid regex`);
+        }
+        const preStepValues = resolvePreStepValues(this.name, opts.pre_steps, this.env);
+        const provider = makeInboxProvider(opts.inbox.provider, opts.inbox.options);
+        const page = await this.launcher({
+            baseURL: ctx.baseURL,
+            ...(opts.ignore_https_errors ? { ignoreHTTPSErrors: true } : {}),
+        });
+        try {
+            await page.goto(new URL(opts.login_url, ctx.baseURL).href);
+            await runPreSteps(page, opts.pre_steps, preStepValues);
+            await page.fill(opts.username_selector, username);
+            await page.fill(opts.password_selector, password);
+            const since = Date.now(); // the code mail is sent in response to this submit
+            await page.click(opts.submit_selector);
+            try {
+                await page.waitForSelector(opts.otp_selector, { timeoutMs: opts.timeout_ms });
+            }
+            catch {
+                throw new AuthStrategyConfigError(`email-otp: the OTP prompt ("${opts.otp_selector}") did not appear within ${opts.timeout_ms}ms — check the credential env vars (values not shown) and the selectors`);
+            }
+            const message = await provider.waitForMessage({
+                to,
+                since,
+                timeoutMs: opts.inbox.timeout_ms,
+            });
+            const match = codePattern.exec(message.body);
+            const code = match ? (match[1] ?? match[0]) : undefined;
+            if (!code) {
+                throw new AuthStrategyConfigError(`email-otp: inbox.code_pattern /${opts.inbox.code_pattern}/ did not match the received message`);
+            }
+            await page.fill(opts.otp_selector, code);
+            if (opts.otp_submit_selector)
+                await page.click(opts.otp_submit_selector);
+            await waitForLoginSuccess(page, opts, this.name);
+            const storageState = await page.storageState();
+            const expiresAt = jarAuthExpiry(storageState);
+            return { storageState, ...(expiresAt !== undefined ? { expiresAt } : {}) };
+        }
+        finally {
+            await page.close();
+        }
+    }
+}

package/dist/auth/http-basic.d.ts

@@ -0,0 +1,5 @@
+import { type AuthContext, type AuthResult, type AuthStrategy } from "./types.js";
+export declare class HttpBasicStrategy implements AuthStrategy {
+    readonly name: "http-basic";
+    authenticate(ctx: AuthContext): Promise<AuthResult>;
+}

package/dist/auth/http-basic.js

@@ -0,0 +1,17 @@
+// `http-basic` — connection-level auth: the browser context answers 401 challenges with the
+// role's credentials. Nothing to capture; the strategy emits `contextOptions.httpCredentials`
+// and an empty storageState.
+import { AuthStrategyConfigError, emptyStorageState, maskSecret, } from "./types.js";
+export class HttpBasicStrategy {
+    name = "http-basic";
+    authenticate(ctx) {
+        const { username, password } = ctx.creds;
+        if (!username || !password) {
+            return Promise.reject(new AuthStrategyConfigError(`http-basic: creds_env must map "username" (${maskSecret(username)}) and "password" (${maskSecret(password)})`));
+        }
+        return Promise.resolve({
+            storageState: emptyStorageState(),
+            contextOptions: { httpCredentials: { username, password } },
+        });
+    }
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,47 @@
+import { AuthStrategyDescriptor, type RoleAuth } from "../doc-pack.js";
+import { type InstrumentedBrowser } from "./manual-capture.js";
+import { type AuthStrategy } from "./types.js";
+export * from "./types.js";
+export * from "./cookie-jar.js";
+export * from "./api-login.js";
+export * from "./browser-session.js";
+export * from "./email-otp.js";
+export * from "./http-basic.js";
+export * from "./jwt-injection.js";
+export * from "./manual-capture.js";
+export * from "./mtls.js";
+export * from "./pat-header.js";
+export * from "./storage-state-cache.js";
+export * from "./test-backdoor.js";
+export * from "./totp.js";
+export * from "./ui-form.js";
+export * from "./webauthn.js";
+/** Parse + validate an `auth/strategy.yaml` descriptor from YAML text. */
+export declare function parseAuthStrategyFile(yamlText: string, source?: string): AuthStrategyDescriptor;
+/** Resolve a role's `creds_env` name map into actual values from an env source (defaults to `process.env`). */
+export declare function resolveCredsEnv(roleAuth: RoleAuth, env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * Like {@link resolveCredsEnv}, with **user-pool** support: any credential env value may be a
+ * comma-separated pool (`user1,user2,user3`); each parallel worker picks `pool[workerIndex % len]`,
+ * consistently across every pooled variable, so worker N always gets user N's username *and* password.
+ */
+export declare function resolveCreds(roleAuth: RoleAuth, opts?: {
+    workerIndex?: number;
+    env?: NodeJS.ProcessEnv;
+}): Record<string, string>;
+export interface StrategyDeps {
+    /** Factory for the instrumented browser `manual-capture` drives. Required if any role uses `manual-capture`. */
+    instrumentedBrowser?: () => InstrumentedBrowser;
+    /** Env source for strategies that read env-var *names* out of options (`token_env`, `totp.secret_env`). Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Register (or override) an auth strategy under `name`. The plugins-runtime hook: registered
+ * strategies are consulted *before* the built-ins, so a plugin can both add new schemes and
+ * replace a built-in for a quirky target.
+ */
+export declare function registerAuthStrategy(name: string, impl: AuthStrategy): void;
+/** Remove a registered strategy (test/plugin teardown). */
+export declare function unregisterAuthStrategy(name: string): void;
+/** Build the {@link AuthStrategy} for a role: registry first, then the built-in catalogue. */
+export declare function makeStrategy(roleAuth: RoleAuth, deps: StrategyDeps): AuthStrategy;