@docsxai/engine 0.2.0

package/dist/auth/index.js

@@ -0,0 +1,137 @@
+// Target-site auth layer.
+//
+// Every strategy produces a `storageState` (cookies + localStorage + sessionStorage) — the
+// universal artifact every auth scheme reduces to — plus, for connection-level schemes
+// (HTTP Basic, PAT headers, mTLS), `contextOptions` the session launcher passes through to
+// the browser context. One module per strategy; this index holds the descriptor parsing,
+// the credential resolution, and the strategy registry.
+import { parse as parseYaml } from "yaml";
+import { AuthStrategyDescriptor } from "../doc-pack.js";
+import { ApiLoginStrategy } from "./api-login.js";
+import { launchAuthPage } from "./browser-session.js";
+import { EmailOtpStrategy } from "./email-otp.js";
+import { HttpBasicStrategy } from "./http-basic.js";
+import { JwtInjectionStrategy } from "./jwt-injection.js";
+import { ManualCaptureStrategy } from "./manual-capture.js";
+import { MtlsStrategy } from "./mtls.js";
+import { PatHeaderStrategy } from "./pat-header.js";
+import { TestBackdoorStrategy } from "./test-backdoor.js";
+import { TotpStrategy } from "./totp.js";
+import { UiFormStrategy } from "./ui-form.js";
+import { WebauthnStrategy } from "./webauthn.js";
+import { AuthStrategyConfigError, NotImplementedStrategyError, } 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";
+// ---------------------------------------------------------------------------
+// Descriptor (`auth/strategy.yaml`)
+// ---------------------------------------------------------------------------
+/** Parse + validate an `auth/strategy.yaml` descriptor from YAML text. */
+export function parseAuthStrategyFile(yamlText, source = "<auth/strategy.yaml>") {
+    let raw;
+    try {
+        raw = parseYaml(yamlText);
+    }
+    catch (e) {
+        throw new AuthStrategyConfigError(`${source}: not valid YAML — ${e.message}`, e);
+    }
+    const r = AuthStrategyDescriptor.safeParse(raw);
+    if (!r.success) {
+        const issues = r.error.issues
+            .map((i) => `  • ${i.path.length ? i.path.join(".") : "(root)"}: ${i.message}`)
+            .join("\n");
+        throw new AuthStrategyConfigError(`${source}: invalid auth-strategy descriptor:\n${issues}`, r.error);
+    }
+    return r.data;
+}
+/** Resolve a role's `creds_env` name map into actual values from an env source (defaults to `process.env`). */
+export function resolveCredsEnv(roleAuth, env = process.env) {
+    const out = {};
+    const missing = [];
+    for (const [key, varName] of Object.entries(roleAuth.creds_env)) {
+        const v = env[varName];
+        if (v === undefined || v === "")
+            missing.push(`${key} → $${varName}`);
+        else
+            out[key] = v;
+    }
+    if (missing.length) {
+        throw new AuthStrategyConfigError(`missing credential env vars:\n${missing.map((m) => `  • ${m}`).join("\n")}`);
+    }
+    return out;
+}
+/**
+ * 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 function resolveCreds(roleAuth, opts = {}) {
+    const workerIndex = opts.workerIndex ?? 0;
+    const raw = resolveCredsEnv(roleAuth, opts.env ?? process.env);
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const pool = value.split(",").map((v) => v.trim());
+        out[key] = pool.length > 1 ? pool[workerIndex % pool.length] : value;
+    }
+    return out;
+}
+const registry = new Map();
+/**
+ * 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 function registerAuthStrategy(name, impl) {
+    registry.set(name, impl);
+}
+/** Remove a registered strategy (test/plugin teardown). */
+export function unregisterAuthStrategy(name) {
+    registry.delete(name);
+}
+/** Build the {@link AuthStrategy} for a role: registry first, then the built-in catalogue. */
+export function makeStrategy(roleAuth, deps) {
+    const registered = registry.get(roleAuth.strategy);
+    if (registered)
+        return registered;
+    switch (roleAuth.strategy) {
+        case "manual-capture":
+            if (!deps.instrumentedBrowser) {
+                throw new AuthStrategyConfigError("strategy `manual-capture` requires an instrumented-browser factory (deps.instrumentedBrowser)");
+            }
+            return new ManualCaptureStrategy(deps.instrumentedBrowser);
+        case "api-login":
+            return new ApiLoginStrategy();
+        case "jwt-injection":
+            return new JwtInjectionStrategy(fetch, deps.env);
+        case "http-basic":
+            return new HttpBasicStrategy();
+        case "pat-header":
+            return new PatHeaderStrategy();
+        case "mtls":
+            return new MtlsStrategy();
+        case "test-backdoor":
+            return new TestBackdoorStrategy();
+        case "totp":
+            return new TotpStrategy();
+        case "ui-form":
+            return new UiFormStrategy(launchAuthPage, deps.env);
+        case "email-otp":
+            return new EmailOtpStrategy(launchAuthPage, deps.env);
+        case "webauthn":
+            return new WebauthnStrategy(launchAuthPage, deps.env);
+        default:
+            throw new NotImplementedStrategyError(roleAuth.strategy);
+    }
+}

package/dist/auth/jwt-injection.d.ts

@@ -0,0 +1,153 @@
+import { z } from "zod";
+import { type AuthContext, type AuthResult, type AuthStrategy } from "./types.js";
+export declare const JwtInjectionOptions: z.ZodEffects<z.ZodObject<{
+    /** Env var *name* holding a static token. Mutually exclusive with `token_url`. */
+    token_env: z.ZodOptional<z.ZodString>;
+    /** OAuth2 token endpoint for a client-credentials grant (creds: `client_id`, `client_secret`). */
+    token_url: z.ZodOptional<z.ZodString>;
+    /** Where the token goes. At least one of `localStorage` / `cookies`. */
+    inject: z.ZodEffects<z.ZodObject<{
+        localStorage: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            /** `{{token}}` template; default `{{token}}`. */
+            value_template: z.ZodDefault<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            key: string;
+            value_template: string;
+        }, {
+            key: string;
+            value_template?: string | undefined;
+        }>, "many">>;
+        cookies: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value_template: z.ZodDefault<z.ZodString>;
+            domain: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            value_template: string;
+            path?: string | undefined;
+            domain?: string | undefined;
+        }, {
+            name: string;
+            path?: string | undefined;
+            domain?: string | undefined;
+            value_template?: string | undefined;
+        }>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        cookies?: {
+            name: string;
+            value_template: string;
+            path?: string | undefined;
+            domain?: string | undefined;
+        }[] | undefined;
+        localStorage?: {
+            key: string;
+            value_template: string;
+        }[] | undefined;
+    }, {
+        cookies?: {
+            name: string;
+            path?: string | undefined;
+            domain?: string | undefined;
+            value_template?: string | undefined;
+        }[] | undefined;
+        localStorage?: {
+            key: string;
+            value_template?: string | undefined;
+        }[] | undefined;
+    }>, {
+        cookies?: {
+            name: string;
+            value_template: string;
+            path?: string | undefined;
+            domain?: string | undefined;
+        }[] | undefined;
+        localStorage?: {
+            key: string;
+            value_template: string;
+        }[] | undefined;
+    }, {
+        cookies?: {
+            name: string;
+            path?: string | undefined;
+            domain?: string | undefined;
+            value_template?: string | undefined;
+        }[] | undefined;
+        localStorage?: {
+            key: string;
+            value_template?: string | undefined;
+        }[] | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    inject: {
+        cookies?: {
+            name: string;
+            value_template: string;
+            path?: string | undefined;
+            domain?: string | undefined;
+        }[] | undefined;
+        localStorage?: {
+            key: string;
+            value_template: string;
+        }[] | undefined;
+    };
+    token_env?: string | undefined;
+    token_url?: string | undefined;
+}, {
+    inject: {
+        cookies?: {
+            name: string;
+            path?: string | undefined;
+            domain?: string | undefined;
+            value_template?: string | undefined;
+        }[] | undefined;
+        localStorage?: {
+            key: string;
+            value_template?: string | undefined;
+        }[] | undefined;
+    };
+    token_env?: string | undefined;
+    token_url?: string | undefined;
+}>, {
+    inject: {
+        cookies?: {
+            name: string;
+            value_template: string;
+            path?: string | undefined;
+            domain?: string | undefined;
+        }[] | undefined;
+        localStorage?: {
+            key: string;
+            value_template: string;
+        }[] | undefined;
+    };
+    token_env?: string | undefined;
+    token_url?: string | undefined;
+}, {
+    inject: {
+        cookies?: {
+            name: string;
+            path?: string | undefined;
+            domain?: string | undefined;
+            value_template?: string | undefined;
+        }[] | undefined;
+        localStorage?: {
+            key: string;
+            value_template?: string | undefined;
+        }[] | undefined;
+    };
+    token_env?: string | undefined;
+    token_url?: string | undefined;
+}>;
+export type JwtInjectionOptions = z.infer<typeof JwtInjectionOptions>;
+/** Decode a JWT's payload (base64url, **no signature verification**) — claims-reading only. */
+export declare function decodeJwtPayload(token: string): Record<string, unknown> | undefined;
+export declare class JwtInjectionStrategy implements AuthStrategy {
+    private readonly fetchImpl;
+    private readonly env;
+    readonly name: "jwt-injection";
+    constructor(fetchImpl?: typeof fetch, env?: NodeJS.ProcessEnv);
+    private obtainToken;
+    authenticate(ctx: AuthContext): Promise<AuthResult>;
+}

package/dist/auth/jwt-injection.js

@@ -0,0 +1,136 @@
+// `jwt-injection` — obtain a bearer token (static env var, or an OAuth2 client-credentials
+// grant) and inject it into the browser's storage the way the target SPA expects it:
+// localStorage keys and/or cookies, rendered from `{{token}}` templates. Pure node, no browser.
+import { z } from "zod";
+import { AuthStrategyConfigError, maskSecret, parseStrategyOptions, renderTemplate, } from "./types.js";
+export const JwtInjectionOptions = z
+    .object({
+    /** Env var *name* holding a static token. Mutually exclusive with `token_url`. */
+    token_env: z.string().min(1).optional(),
+    /** OAuth2 token endpoint for a client-credentials grant (creds: `client_id`, `client_secret`). */
+    token_url: z.string().min(1).optional(),
+    /** Where the token goes. At least one of `localStorage` / `cookies`. */
+    inject: z
+        .object({
+        localStorage: z
+            .array(z
+            .object({
+            key: z.string().min(1),
+            /** `{{token}}` template; default `{{token}}`. */
+            value_template: z.string().min(1).default("{{token}}"),
+        })
+            .strict())
+            .optional(),
+        cookies: z
+            .array(z
+            .object({
+            name: z.string().min(1),
+            value_template: z.string().min(1).default("{{token}}"),
+            domain: z.string().min(1).optional(),
+            path: z.string().min(1).optional(),
+        })
+            .strict())
+            .optional(),
+    })
+        .strict()
+        .refine((i) => (i.localStorage?.length ?? 0) + (i.cookies?.length ?? 0) > 0, {
+        message: "inject needs at least one localStorage or cookies entry",
+    }),
+})
+    .strict()
+    .refine((o) => (o.token_env !== undefined) !== (o.token_url !== undefined), {
+    message: "exactly one of token_env or token_url is required",
+});
+/** Decode a JWT's payload (base64url, **no signature verification**) — claims-reading only. */
+export function decodeJwtPayload(token) {
+    const payload = token.split(".")[1];
+    if (!payload)
+        return undefined;
+    try {
+        const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        return parsed !== null && typeof parsed === "object"
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export class JwtInjectionStrategy {
+    fetchImpl;
+    env;
+    name = "jwt-injection";
+    constructor(fetchImpl = fetch, env = process.env) {
+        this.fetchImpl = fetchImpl;
+        this.env = env;
+    }
+    async obtainToken(opts, ctx) {
+        if (opts.token_env !== undefined) {
+            const token = this.env[opts.token_env];
+            if (!token) {
+                throw new AuthStrategyConfigError(`jwt-injection: token env var $${opts.token_env} is ${maskSecret(token)}`);
+            }
+            return { token, expiresAt: expiryFromJwt(token) };
+        }
+        const { client_id: clientId, client_secret: clientSecret } = ctx.creds;
+        if (!clientId || !clientSecret) {
+            throw new AuthStrategyConfigError(`jwt-injection: token_url needs creds_env mapping client_id (${maskSecret(clientId)}) and client_secret (${maskSecret(clientSecret)})`);
+        }
+        const tokenUrl = new URL(opts.token_url, ctx.baseURL);
+        const response = await this.fetchImpl(tokenUrl, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "client_credentials",
+                client_id: clientId,
+                client_secret: clientSecret,
+            }).toString(),
+        });
+        if (!response.ok) {
+            throw new AuthStrategyConfigError(`jwt-injection: token endpoint ${tokenUrl.href} answered ${response.status} (client_secret: ${maskSecret(clientSecret)} — value not shown)`);
+        }
+        let body;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            throw new AuthStrategyConfigError(`jwt-injection: token endpoint ${tokenUrl.href} did not return JSON`);
+        }
+        if (!body.access_token) {
+            throw new AuthStrategyConfigError(`jwt-injection: token endpoint ${tokenUrl.href} returned no access_token`);
+        }
+        const fromExpiresIn = typeof body.expires_in === "number" ? Date.now() + body.expires_in * 1000 : undefined;
+        const expiresAt = fromExpiresIn ?? expiryFromJwt(body.access_token);
+        return { token: body.access_token, ...(expiresAt !== undefined ? { expiresAt } : {}) };
+    }
+    async authenticate(ctx) {
+        const opts = parseStrategyOptions(this.name, JwtInjectionOptions, ctx.options);
+        const { token, expiresAt } = await this.obtainToken(opts, ctx);
+        const base = new URL(ctx.baseURL);
+        const vars = { token };
+        const storageState = { cookies: [], origins: [] };
+        const entries = (opts.inject.localStorage ?? []).map((e) => ({
+            name: e.key,
+            value: renderTemplate(e.value_template, vars),
+        }));
+        if (entries.length)
+            storageState.origins.push({ origin: base.origin, localStorage: entries });
+        for (const c of opts.inject.cookies ?? []) {
+            storageState.cookies.push({
+                name: c.name,
+                value: renderTemplate(c.value_template, vars),
+                domain: c.domain ?? base.hostname,
+                path: c.path ?? "/",
+                expires: expiresAt !== undefined ? Math.floor(expiresAt / 1000) : -1,
+                httpOnly: false,
+                secure: base.protocol === "https:",
+                sameSite: "Lax",
+            });
+        }
+        return { storageState, ...(expiresAt !== undefined ? { expiresAt } : {}) };
+    }
+}
+function expiryFromJwt(token) {
+    const exp = decodeJwtPayload(token)?.exp;
+    return typeof exp === "number" ? exp * 1000 : undefined;
+}

package/dist/auth/manual-capture.d.ts

@@ -0,0 +1,35 @@
+import { type AuthContext, type AuthResult, type AuthStrategy, type StorageState } from "./types.js";
+export type CaptureTrigger = "console" | "button";
+/**
+ * The browser the engine drives for `manual-capture` — a security-lowered, *instrumented* Chrome.
+ * The Playwright-backed implementation lives in a separate module (so this strategy stays testable);
+ * `--disable-web-security` etc. let the injected capture helper work across SSO-redirect origins.
+ */
+export interface InstrumentedBrowser {
+    /** Launch the browser and open the target site. */
+    open(baseURL: string): Promise<void>;
+    /**
+     * Inject the capture helper (a console function `window.__docsxai.capture()` and/or an on-page button)
+     * and resolve once the human triggers it. The human does the interactive login (SSO / MFA / conditional
+     * access — anything they can click through) before triggering.
+     */
+    waitForCapture(trigger: CaptureTrigger): Promise<void>;
+    /** Snapshot the current `storageState`. */
+    storageState(): Promise<StorageState>;
+    close(): Promise<void>;
+}
+export interface ManualCaptureOptions {
+    /** `console` (default): `window.__docsxai.capture()`. `button`: an injected on-page button. */
+    capture_trigger?: CaptureTrigger;
+}
+/**
+ * `manual-capture` — the plugin spawns a security-lowered, instrumented Chrome; the engineer logs in
+ * interactively; a console command or an injected button snapshots `storageState`. The zero-integration
+ * universal fallback for SSO / MFA / conditional access, at the cost of periodic human re-capture.
+ */
+export declare class ManualCaptureStrategy implements AuthStrategy {
+    private readonly browserFactory;
+    readonly name: "manual-capture";
+    constructor(browserFactory: () => InstrumentedBrowser);
+    authenticate(ctx: AuthContext): Promise<AuthResult>;
+}

package/dist/auth/manual-capture.js

@@ -0,0 +1,30 @@
+// `manual-capture` — the zero-integration universal fallback for SSO / MFA / conditional access.
+/**
+ * `manual-capture` — the plugin spawns a security-lowered, instrumented Chrome; the engineer logs in
+ * interactively; a console command or an injected button snapshots `storageState`. The zero-integration
+ * universal fallback for SSO / MFA / conditional access, at the cost of periodic human re-capture.
+ */
+export class ManualCaptureStrategy {
+    browserFactory;
+    name = "manual-capture";
+    constructor(browserFactory) {
+        this.browserFactory = browserFactory;
+    }
+    async authenticate(ctx) {
+        const opts = ctx.options;
+        const trigger = opts.capture_trigger ?? "console";
+        const browser = this.browserFactory();
+        try {
+            await browser.open(ctx.baseURL);
+            await browser.waitForCapture(trigger);
+            const storageState = await browser.storageState();
+            // Deliberately *not* reporting an `expiresAt`: an interactive SSO login drops ephemeral IdP scratch
+            // cookies whose expiry is seconds out, so `min(cookie.expires)` ≈ now and would make the cached
+            // session born expired. How long a manually-captured session is trusted is the `cache.ttl` contract.
+            return { storageState };
+        }
+        finally {
+            await browser.close();
+        }
+    }
+}

package/dist/auth/mtls.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { type AuthContext, type AuthResult, type AuthStrategy } from "./types.js";
+export declare const MtlsOptions: z.ZodObject<{
+    /** Origin the certificate applies to. Default: the target's baseURL origin. */
+    origin: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    origin?: string | undefined;
+}, {
+    origin?: string | undefined;
+}>;
+export type MtlsOptions = z.infer<typeof MtlsOptions>;
+export declare class MtlsStrategy implements AuthStrategy {
+    readonly name: "mtls";
+    authenticate(ctx: AuthContext): Promise<AuthResult>;
+}

package/dist/auth/mtls.js

@@ -0,0 +1,53 @@
+// `mtls` — connection-level auth: the browser context presents a client certificate during the
+// TLS handshake. The creds env vars hold *paths* to the PEM files (cert/key stay on disk; the
+// strategy validates they exist and look like PEM but never reads them into logs or errors).
+// An optional `passphrase` cred decrypts an encrypted key. Empty storageState;
+// `contextOptions.clientCertificates` carries the paths through to Playwright.
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+import { AuthStrategyConfigError, emptyStorageState, maskSecret, parseStrategyOptions, } from "./types.js";
+export const MtlsOptions = z
+    .object({
+    /** Origin the certificate applies to. Default: the target's baseURL origin. */
+    origin: z.string().min(1).optional(),
+})
+    .strict();
+async function assertPemFile(role, filePath) {
+    let head;
+    try {
+        const handle = await fs.open(filePath, "r");
+        try {
+            const buf = Buffer.alloc(64);
+            const { bytesRead } = await handle.read(buf, 0, 64, 0);
+            head = buf.subarray(0, bytesRead).toString("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        throw new AuthStrategyConfigError(`mtls: ${role} file not readable: ${filePath}`);
+    }
+    if (!head.includes("-----BEGIN ")) {
+        throw new AuthStrategyConfigError(`mtls: ${role} file does not look like PEM (expected a "-----BEGIN …-----" header): ${filePath}`);
+    }
+}
+export class MtlsStrategy {
+    name = "mtls";
+    async authenticate(ctx) {
+        const opts = parseStrategyOptions(this.name, MtlsOptions, ctx.options);
+        const { cert: certPath, key: keyPath, passphrase } = ctx.creds;
+        if (!certPath || !keyPath) {
+            throw new AuthStrategyConfigError(`mtls: creds_env must map "cert" (${maskSecret(certPath)}) and "key" (${maskSecret(keyPath)}) to env vars holding PEM file *paths*`);
+        }
+        await assertPemFile("cert", certPath);
+        await assertPemFile("key", keyPath);
+        const origin = opts.origin ?? new URL(ctx.baseURL).origin;
+        return {
+            storageState: emptyStorageState(),
+            contextOptions: {
+                clientCertificates: [{ origin, certPath, keyPath, ...(passphrase ? { passphrase } : {}) }],
+            },
+        };
+    }
+}

package/dist/auth/pat-header.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { type AuthContext, type AuthResult, type AuthStrategy } from "./types.js";
+export declare const PatHeaderOptions: z.ZodObject<{
+    /** Header name. Default `Authorization`. */
+    header: z.ZodDefault<z.ZodString>;
+    /** `{{token}}` template for the header value. Default `Bearer {{token}}`. */
+    value_template: z.ZodDefault<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    value_template: string;
+    header: string;
+}, {
+    value_template?: string | undefined;
+    header?: string | undefined;
+}>;
+export type PatHeaderOptions = z.infer<typeof PatHeaderOptions>;
+export declare class PatHeaderStrategy implements AuthStrategy {
+    readonly name: "pat-header";
+    authenticate(ctx: AuthContext): Promise<AuthResult>;
+}

package/dist/auth/pat-header.js

@@ -0,0 +1,34 @@
+// `pat-header` — connection-level auth: every request the browser context makes carries a
+// personal-access-token header (`Authorization: Bearer <token>` by default). Empty storageState;
+// the strategy emits `contextOptions.extraHTTPHeaders`.
+import { z } from "zod";
+import { AuthStrategyConfigError, emptyStorageState, maskSecret, parseStrategyOptions, renderTemplate, } from "./types.js";
+export const PatHeaderOptions = z
+    .object({
+    /** Header name. Default `Authorization`. */
+    header: z.string().min(1).default("Authorization"),
+    /** `{{token}}` template for the header value. Default `Bearer {{token}}`. */
+    value_template: z.string().min(1).default("Bearer {{token}}"),
+})
+    .strict();
+export class PatHeaderStrategy {
+    name = "pat-header";
+    authenticate(ctx) {
+        try {
+            const opts = parseStrategyOptions(this.name, PatHeaderOptions, ctx.options);
+            const token = ctx.creds.token;
+            if (!token) {
+                throw new AuthStrategyConfigError(`pat-header: creds_env must map "token" to the env var holding the access token (token: ${maskSecret(token)})`);
+            }
+            return Promise.resolve({
+                storageState: emptyStorageState(),
+                contextOptions: {
+                    extraHTTPHeaders: { [opts.header]: renderTemplate(opts.value_template, { token }) },
+                },
+            });
+        }
+        catch (e) {
+            return Promise.reject(e instanceof Error ? e : new Error(String(e)));
+        }
+    }
+}

package/dist/auth/storage-state-cache.d.ts

@@ -0,0 +1,38 @@
+import { type RoleAuth } from "../doc-pack.js";
+import { type AuthResult, type StorageState } from "./types.js";
+export declare class LocalStorageStateCache {
+    private readonly dir;
+    /** @param dir the `.auth/` directory (relative paths resolved against cwd). */
+    constructor(dir?: string);
+    private fileName;
+    private file;
+    /** Return the cached state for a role if present and not past its expiry; otherwise `null`. */
+    load(role: string, now?: number): Promise<StorageState | null>;
+    /**
+     * Persist a captured session and compute its expiry, in priority order:
+     *   1. **The app's auth cookie** — if `auth_cookie` (descriptor or override) names a cookie that's in the
+     *      captured jar with a real (non-session) expiry, that expiry *is* the bound. This is the right answer;
+     *      the host agent identifies which cookie it is (it's on the app's domain, long-lived — not an ephemeral
+     *      IdP scratch cookie). Why not just `min(cookie.expires)`? An interactive SSO login drops scratch cookies
+     *      that expire seconds out, so the min ≈ now and the session would be born expired.
+     *   2. **`ttl`** — a duration (`1h`, `30m`, ms) → `now + ttl`. The fallback when no `auth_cookie` is set/found.
+     *   3. **`session` / default** — the strategy's reported `expiresAt` if plausibly in the future, else +1h.
+     * Returns the computed `expiresAt` and a human-readable `source`.
+     */
+    save(role: string, result: AuthResult, roleAuth: RoleAuth, now?: number, opts?: {
+        authCookie?: string;
+    }): Promise<{
+        expiresAt: number;
+        source: string;
+    }>;
+    clear(role: string): Promise<void>;
+}
+/** The cache surface both stores satisfy — `load` / `save` / `clear` per role. */
+export type StorageStateCache = Pick<LocalStorageStateCache, "load" | "save" | "clear">;
+/**
+ * Pick the state cache for a role. `store: local` (the default) caches under `<workspace>/.auth/`.
+ * `store: backend` relays AES-256-GCM envelopes through the backend (encrypted client-side; the
+ * backend never sees plaintext) — it needs a workspace that has been pushed (`backend_url` +
+ * `backend_workspace_id` in `.docsxai.json`) and `DOCSX_CACHE_KEY`.
+ */
+export declare function resolveStateCache(roleAuth: RoleAuth, workspaceDir: string): Promise<StorageStateCache>;