@docsxai/engine 0.2.0

package/dist/auth/storage-state-cache.js

@@ -0,0 +1,143 @@
+// Local storageState cache (`.auth/<role>.json`) — used by expensive strategies (manual-capture, ui-form, ...).
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+import { BackendStateCache, resolveBackendToken } from "../backend-client.js";
+import { loadWorkspaceConfig, resolveWorkspacePath, resolveWorkspacePathReal, } from "../workspace.js";
+import { AuthStrategyConfigError, cookieExpiryByName, } from "./types.js";
+const CachedStateSchema = z
+    .object({
+    storageState: z.object({ cookies: z.array(z.any()), origins: z.array(z.any()) }),
+    writtenAt: z.number(),
+    expiresAt: z.number(),
+})
+    .passthrough();
+function ttlToMs(ttl) {
+    if (ttl === "session")
+        return "session";
+    if (typeof ttl === "number")
+        return ttl;
+    const m = /^(\d+)(ms|s|m|h)$/.exec(ttl);
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "ms":
+            return n;
+        case "s":
+            return n * 1000;
+        case "m":
+            return n * 60_000;
+        case "h":
+            return n * 3_600_000;
+        default:
+            return n;
+    }
+}
+export class LocalStorageStateCache {
+    dir;
+    /** @param dir the `.auth/` directory (relative paths resolved against cwd). */
+    constructor(dir = ".auth") {
+        this.dir = dir;
+    }
+    fileName(role) {
+        // role names are simple identifiers in practice; still, keep the filename safe.
+        const safe = role.replace(/[^A-Za-z0-9_.-]/g, "_");
+        return `${safe}.json`;
+    }
+    file(role) {
+        return resolveWorkspacePath(this.dir, this.fileName(role));
+    }
+    /** Return the cached state for a role if present and not past its expiry; otherwise `null`. */
+    async load(role, now = Date.now()) {
+        let text;
+        try {
+            text = await fs.readFile(this.file(role), "utf8");
+        }
+        catch {
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = CachedStateSchema.parse(JSON.parse(text));
+        }
+        catch {
+            return null; // corrupt cache → treat as miss
+        }
+        if (parsed.expiresAt <= now)
+            return null;
+        return parsed.storageState;
+    }
+    /**
+     * 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`.
+     */
+    async save(role, result, roleAuth, now = Date.now(), opts = {}) {
+        const authCookieName = opts.authCookie ?? roleAuth.cache.auth_cookie;
+        const fromCookie = authCookieName
+            ? cookieExpiryByName(result.storageState, authCookieName)
+            : undefined;
+        const ttlMs = ttlToMs(roleAuth.cache.ttl);
+        let expiresAt;
+        let source;
+        if (fromCookie !== undefined) {
+            expiresAt = fromCookie;
+            source = `auth-cookie "${authCookieName}"`;
+        }
+        else if (authCookieName) {
+            expiresAt = typeof ttlMs === "number" ? now + ttlMs : now + 3_600_000;
+            source = `ttl (fallback — auth-cookie "${authCookieName}" not in the jar or has no expiry)`;
+        }
+        else if (typeof ttlMs === "number") {
+            expiresAt = now + ttlMs;
+            source = "ttl";
+        }
+        else {
+            const reported = result.expiresAt && result.expiresAt > now + 60_000 ? result.expiresAt : undefined;
+            expiresAt = reported ?? now + 3_600_000;
+            source = reported ? "strategy-reported expiresAt" : "1h default";
+        }
+        if (expiresAt <= now) {
+            throw new AuthStrategyConfigError(`computed cache expiry (${new Date(expiresAt).toISOString()}, from ${source}) is not in the future — refusing to cache a dead session`);
+        }
+        const entry = { storageState: result.storageState, writtenAt: now, expiresAt };
+        await fs.mkdir(resolveWorkspacePath(this.dir), { recursive: true });
+        // Role names are operator-influenced — resolve with the symlink-aware variant before writing.
+        const target = await resolveWorkspacePathReal(this.dir, this.fileName(role));
+        await fs.writeFile(target, JSON.stringify(entry, null, 2) + "\n", "utf8");
+        return { expiresAt, source };
+    }
+    async clear(role) {
+        await fs.rm(this.file(role), { force: true });
+    }
+}
+/**
+ * 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 async function resolveStateCache(roleAuth, workspaceDir) {
+    if (roleAuth.cache.store === "backend") {
+        const cfg = await loadWorkspaceConfig(workspaceDir);
+        if (!cfg?.backend_url || !cfg.backend_workspace_id) {
+            throw new AuthStrategyConfigError("cache.store: backend needs a backend-bound workspace — run `docsxai push` first (backend_url + backend_workspace_id in .docsxai.json)");
+        }
+        const cacheKey = process.env.DOCSX_CACHE_KEY;
+        if (!cacheKey) {
+            throw new AuthStrategyConfigError("cache.store: backend requires DOCSX_CACHE_KEY (base64-encoded 32-byte key)");
+        }
+        const token = await resolveBackendToken({ baseUrl: cfg.backend_url, workspaceDir });
+        return new BackendStateCache({
+            baseUrl: cfg.backend_url,
+            token,
+            workspaceId: cfg.backend_workspace_id,
+            cacheKey,
+        });
+    }
+    return new LocalStorageStateCache(resolveWorkspacePath(workspaceDir, ".auth"));
+}

package/dist/auth/test-backdoor.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { type AuthContext, type AuthResult, type AuthStrategy } from "./types.js";
+export declare const TestBackdoorOptions: z.ZodObject<{
+    /** Backdoor endpoint; resolved against the target's base URL when relative. */
+    url: z.ZodString;
+    /** User to impersonate; sent verbatim in the request body. */
+    user_id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    /** Cookie that proves the backdoor worked. Optional; any Set-Cookie + non-4xx passes without it. */
+    success_cookie: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    url: string;
+    user_id?: string | number | undefined;
+    success_cookie?: string | undefined;
+}, {
+    url: string;
+    user_id?: string | number | undefined;
+    success_cookie?: string | undefined;
+}>;
+export type TestBackdoorOptions = z.infer<typeof TestBackdoorOptions>;
+export declare class TestBackdoorStrategy implements AuthStrategy {
+    private readonly fetchImpl;
+    readonly name: "test-backdoor";
+    constructor(fetchImpl?: typeof fetch);
+    authenticate(ctx: AuthContext): Promise<AuthResult>;
+}

package/dist/auth/test-backdoor.js

@@ -0,0 +1,51 @@
+// `test-backdoor` — POST a shared secret to a test-only login endpoint the target app exposes in
+// non-production builds, and keep the session cookies it sets. The unattended-execution answer
+// when the app team can ship a backdoor route; the secret lives in env, never in the descriptor.
+import { z } from "zod";
+import { fetchCollectingCookies, jarAuthExpiry } from "./cookie-jar.js";
+import { AuthStrategyConfigError, maskSecret, parseStrategyOptions, } from "./types.js";
+export const TestBackdoorOptions = z
+    .object({
+    /** Backdoor endpoint; resolved against the target's base URL when relative. */
+    url: z.string().min(1),
+    /** User to impersonate; sent verbatim in the request body. */
+    user_id: z.union([z.string(), z.number()]).optional(),
+    /** Cookie that proves the backdoor worked. Optional; any Set-Cookie + non-4xx passes without it. */
+    success_cookie: z.string().min(1).optional(),
+})
+    .strict();
+export class TestBackdoorStrategy {
+    fetchImpl;
+    name = "test-backdoor";
+    constructor(fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+    }
+    async authenticate(ctx) {
+        const opts = parseStrategyOptions(this.name, TestBackdoorOptions, ctx.options);
+        const secret = ctx.creds.secret;
+        if (!secret) {
+            throw new AuthStrategyConfigError(`test-backdoor: creds_env must map "secret" to the env var holding the backdoor secret (secret: ${maskSecret(secret)})`);
+        }
+        const url = new URL(opts.url, ctx.baseURL);
+        const result = await fetchCollectingCookies(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                secret,
+                ...(opts.user_id !== undefined ? { user_id: opts.user_id } : {}),
+            }),
+        }, { fetchImpl: this.fetchImpl });
+        if (result.status >= 400) {
+            throw new AuthStrategyConfigError(`test-backdoor: ${url.href} answered ${result.status} (secret: ${maskSecret(secret)} — value not shown)`);
+        }
+        if (opts.success_cookie && !result.jar.has(opts.success_cookie)) {
+            throw new AuthStrategyConfigError(`test-backdoor: expected cookie "${opts.success_cookie}" was not set by ${url.href}`);
+        }
+        if (result.jar.cookies().length === 0) {
+            throw new AuthStrategyConfigError(`test-backdoor: ${url.href} answered ${result.status} but set no cookies — nothing to capture`);
+        }
+        const storageState = result.jar.toStorageState();
+        const expiresAt = jarAuthExpiry(storageState, opts.success_cookie);
+        return { storageState, ...(expiresAt !== undefined ? { expiresAt } : {}) };
+    }
+}

package/dist/auth/totp.d.ts

@@ -0,0 +1,39 @@
+import { type AuthContext, type AuthResult, type AuthStrategy } from "./types.js";
+/** Decode an RFC 4648 base32 string (case-insensitive; `=` padding and inner whitespace tolerated). */
+export declare function base32Decode(encoded: string): Buffer;
+/** Encode bytes as RFC 4648 base32 (no padding). Test/fixture aid; authenticator secrets arrive base32. */
+export declare function base32Encode(data: Uint8Array): string;
+export type TotpAlgorithm = "sha1" | "sha256";
+export interface TotpOptions {
+    /** Wall-clock instant the code is for. Epoch ms (or a `Date`). Default: now. */
+    at?: number | Date;
+    /** Code length: 6 (default) or 8. */
+    digits?: 6 | 8;
+    /** Time-step in seconds. Default 30. */
+    period?: number;
+    /** HMAC algorithm. Default `sha1` (what authenticator apps implement). */
+    algorithm?: TotpAlgorithm;
+}
+/** RFC 4226 HOTP: HMAC the 8-byte big-endian counter, dynamic-truncate, mod 10^digits. */
+export declare function generateHotp(key: Uint8Array, counter: number | bigint, digits?: 6 | 8, algorithm?: TotpAlgorithm): string;
+/** RFC 6238 TOTP for `secret` (base32 string, or raw key bytes). */
+export declare function generateTotp(secret: string | Uint8Array, opts?: TotpOptions): string;
+/**
+ * Codes for the time-steps within ±`window` of `at` (clock-drift tolerance), centre first.
+ * `window: 1` (the common server allowance) yields the current, previous, and next codes.
+ */
+export declare function totpCodesAround(secret: string | Uint8Array, opts?: TotpOptions & {
+    window?: number;
+}): string[];
+/** True when `code` matches any time-step within ±`window` (default 1) of `at`. */
+export declare function verifyTotp(code: string, secret: string | Uint8Array, opts?: TotpOptions & {
+    window?: number;
+}): boolean;
+/**
+ * The standalone `totp` catalogue entry. A TOTP is one field of an interactive login, not a whole
+ * scheme — authenticating with it alone is a config error that points at the composition.
+ */
+export declare class TotpStrategy implements AuthStrategy {
+    readonly name: "totp";
+    authenticate(_ctx: AuthContext): Promise<AuthResult>;
+}

package/dist/auth/totp.js

@@ -0,0 +1,108 @@
+// Dep-free RFC 6238 TOTP (over RFC 4226 HOTP) with `node:crypto`.
+//
+// `totp` is not a standalone login scheme — a one-time code is one *field* of an interactive
+// login — so the catalogue entry composes `ui-form` (set `options.totp` there). The primitives
+// are exported for that hook, for fixture servers, and for future CLI/MCP surfacing.
+import { createHmac } from "node:crypto";
+import { AuthStrategyConfigError, } from "./types.js";
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+/** Decode an RFC 4648 base32 string (case-insensitive; `=` padding and inner whitespace tolerated). */
+export function base32Decode(encoded) {
+    const clean = encoded.replace(/[\s-]/g, "").replace(/=+$/, "").toUpperCase();
+    if (clean.length === 0)
+        return Buffer.alloc(0);
+    let bits = 0;
+    let acc = 0;
+    const out = [];
+    for (const ch of clean) {
+        const idx = BASE32_ALPHABET.indexOf(ch);
+        if (idx === -1) {
+            throw new AuthStrategyConfigError(`base32: invalid character "${ch}"`);
+        }
+        acc = (acc << 5) | idx;
+        bits += 5;
+        if (bits >= 8) {
+            bits -= 8;
+            out.push((acc >> bits) & 0xff);
+        }
+    }
+    return Buffer.from(out);
+}
+/** Encode bytes as RFC 4648 base32 (no padding). Test/fixture aid; authenticator secrets arrive base32. */
+export function base32Encode(data) {
+    let bits = 0;
+    let acc = 0;
+    let out = "";
+    for (const byte of data) {
+        acc = (acc << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            out += BASE32_ALPHABET[(acc >> bits) & 31];
+        }
+    }
+    if (bits > 0)
+        out += BASE32_ALPHABET[(acc << (5 - bits)) & 31];
+    return out;
+}
+/** RFC 4226 HOTP: HMAC the 8-byte big-endian counter, dynamic-truncate, mod 10^digits. */
+export function generateHotp(key, counter, digits = 6, algorithm = "sha1") {
+    const counterBuf = Buffer.alloc(8);
+    counterBuf.writeBigUInt64BE(BigInt(counter));
+    const mac = createHmac(algorithm, key).update(counterBuf).digest();
+    const offset = mac[mac.length - 1] & 0x0f;
+    const binCode = ((mac[offset] & 0x7f) << 24) |
+        (mac[offset + 1] << 16) |
+        (mac[offset + 2] << 8) |
+        mac[offset + 3];
+    return String(binCode % 10 ** digits).padStart(digits, "0");
+}
+function keyOf(secret) {
+    return typeof secret === "string" ? base32Decode(secret) : Buffer.from(secret);
+}
+function counterAt(at, period) {
+    const ms = at instanceof Date ? at.getTime() : (at ?? Date.now());
+    return BigInt(Math.floor(ms / 1000 / period));
+}
+/** RFC 6238 TOTP for `secret` (base32 string, or raw key bytes). */
+export function generateTotp(secret, opts = {}) {
+    const period = opts.period ?? 30;
+    return generateHotp(keyOf(secret), counterAt(opts.at, period), opts.digits ?? 6, opts.algorithm ?? "sha1");
+}
+/**
+ * Codes for the time-steps within ±`window` of `at` (clock-drift tolerance), centre first.
+ * `window: 1` (the common server allowance) yields the current, previous, and next codes.
+ */
+export function totpCodesAround(secret, opts = {}) {
+    const period = opts.period ?? 30;
+    const window = opts.window ?? 1;
+    const key = keyOf(secret);
+    const centre = counterAt(opts.at, period);
+    const codes = [];
+    for (let drift = 0; drift <= window; drift++) {
+        for (const counter of drift === 0
+            ? [centre]
+            : [centre - BigInt(drift), centre + BigInt(drift)]) {
+            if (counter < 0n)
+                continue;
+            codes.push(generateHotp(key, counter, opts.digits ?? 6, opts.algorithm ?? "sha1"));
+        }
+    }
+    return codes;
+}
+/** True when `code` matches any time-step within ±`window` (default 1) of `at`. */
+export function verifyTotp(code, secret, opts = {}) {
+    return totpCodesAround(secret, opts).includes(code);
+}
+/**
+ * The standalone `totp` catalogue entry. A TOTP is one field of an interactive login, not a whole
+ * scheme — authenticating with it alone is a config error that points at the composition.
+ */
+export class TotpStrategy {
+    name = "totp";
+    authenticate(_ctx) {
+        throw new AuthStrategyConfigError("strategy `totp` is not a standalone login — use strategy `ui-form` with " +
+            "options.totp: { secret_env: <ENV-VAR NAME>, otp_selector: <css>, submit_selector?: <css> }; " +
+            "the TOTP primitives (generateTotp / verifyTotp) are exported for direct use");
+    }
+}

package/dist/auth/types.d.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+/** Structural shape of Playwright's `BrowserContext.storageState()` output. We don't import Playwright here. */
+export interface StorageState {
+    cookies: Array<{
+        name: string;
+        value: string;
+        domain: string;
+        path: string;
+        expires: number;
+        httpOnly: boolean;
+        secure: boolean;
+        sameSite: "Strict" | "Lax" | "None";
+    }>;
+    origins: Array<{
+        origin: string;
+        localStorage: Array<{
+            name: string;
+            value: string;
+        }>;
+    }>;
+}
+/** One captured cookie in a {@link StorageState} jar. */
+export type StorageStateCookie = StorageState["cookies"][number];
+/** An empty jar — for strategies whose "auth" is connection-level, not storage-level. */
+export declare function emptyStorageState(): StorageState;
+/**
+ * Connection-level auth a strategy asks the browser context to carry. Produced by strategies whose
+ * scheme isn't reducible to cookies/localStorage (HTTP Basic, PAT headers, mTLS client certs).
+ * The session launcher passes these through to Playwright's `browser.newContext(...)`.
+ */
+export interface AuthContextOptions {
+    httpCredentials?: {
+        username: string;
+        password: string;
+    };
+    clientCertificates?: Array<Record<string, unknown>>;
+    extraHTTPHeaders?: Record<string, string>;
+}
+/** Result of authenticating a role: the captured session, plus an optional hard expiry the strategy knows. */
+export interface AuthResult {
+    storageState: StorageState;
+    /** Epoch ms when the session is known to expire (e.g. from a cookie's `expires`). Optional. */
+    expiresAt?: number;
+    /** Connection-level auth (HTTP Basic / client certs / extra headers) for the browser context. */
+    contextOptions?: AuthContextOptions;
+}
+export interface AuthContext {
+    /** Credential values, resolved from the role's `creds_env` name map. Empty for `manual-capture`. */
+    creds: Record<string, string>;
+    /** Strategy-specific options from the descriptor. */
+    options: Record<string, unknown>;
+    /** The target site's base URL. */
+    baseURL: string;
+    /** Role name (for logging / cache keying). */
+    role: string;
+    /** Workspace root, for strategies that need workspace-rooted IO. Optional. */
+    workspaceDir?: string;
+    /** Parallel-worker index, for credential pools. Default 0. */
+    workerIndex?: number;
+}
+/**
+ * A strategy: given an {@link AuthContext}, produce an {@link AuthResult}. One implementation per
+ * backend type. `name` matches the descriptor's `strategy` value for built-ins; registry-registered
+ * plugin strategies may omit it (the registration name is canonical).
+ */
+export interface AuthStrategy {
+    readonly name?: string;
+    authenticate(ctx: AuthContext): Promise<AuthResult>;
+}
+export declare class NotImplementedStrategyError extends Error {
+    constructor(name: string);
+}
+export declare class AuthStrategyConfigError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Validate a strategy's `options` record against its schema; config errors name the offending key, never values. */
+export declare function parseStrategyOptions<S extends z.ZodTypeAny>(strategy: string, schema: S, options: Record<string, unknown>): z.infer<S>;
+/** Mask a secret for logs / error messages — the value itself must never surface. */
+export declare function maskSecret(value: string | undefined): "<SET>" | "<UNSET>";
+/** Render a `{{key}}` template against a variable map. Unknown keys are left intact. */
+export declare function renderTemplate(template: string, vars: Record<string, string>): string;
+/** The earliest non-session cookie expiry (epoch ms), or `undefined` if all cookies are session cookies. */
+export declare function earliestCookieExpiry(state: StorageState): number | undefined;
+/** Expiry (epoch ms) of the cookie named `name` in `state` — the latest if there are several; `undefined` if absent or a session cookie (`expires <= 0`). */
+export declare function cookieExpiryByName(state: StorageState, name: string): number | undefined;

package/dist/auth/types.js

@@ -0,0 +1,57 @@
+// Shared auth-layer types and StorageState helpers.
+//
+// Every strategy produces a `storageState` (cookies + localStorage + sessionStorage) — the
+// universal artifact every auth scheme reduces to. Execution consumes it via Playwright's
+// `setup`-project + `dependencies` mechanism (auth-agnostic for the rest of the suite).
+/** An empty jar — for strategies whose "auth" is connection-level, not storage-level. */
+export function emptyStorageState() {
+    return { cookies: [], origins: [] };
+}
+export class NotImplementedStrategyError extends Error {
+    constructor(name) {
+        super(`auth strategy "${name}" is not implemented in this build`);
+        this.name = "NotImplementedStrategyError";
+    }
+}
+export class AuthStrategyConfigError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "AuthStrategyConfigError";
+    }
+}
+/** Validate a strategy's `options` record against its schema; config errors name the offending key, never values. */
+export function parseStrategyOptions(strategy, schema, options) {
+    const r = schema.safeParse(options);
+    if (!r.success) {
+        const issues = r.error.issues
+            .map((i) => `  • options.${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("\n");
+        throw new AuthStrategyConfigError(`strategy \`${strategy}\`: invalid options:\n${issues}`);
+    }
+    return r.data;
+}
+/** Mask a secret for logs / error messages — the value itself must never surface. */
+export function maskSecret(value) {
+    return value ? "<SET>" : "<UNSET>";
+}
+/** Render a `{{key}}` template against a variable map. Unknown keys are left intact. */
+export function renderTemplate(template, vars) {
+    return template.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (whole, key) => key in vars ? vars[key] : whole);
+}
+/** The earliest non-session cookie expiry (epoch ms), or `undefined` if all cookies are session cookies. */
+export function earliestCookieExpiry(state) {
+    const expiries = state.cookies
+        .map((c) => c.expires)
+        .filter((e) => typeof e === "number" && e > 0)
+        .map((e) => e * 1000); // Playwright cookie `expires` is seconds since epoch (or -1 for session)
+    return expiries.length ? Math.min(...expiries) : undefined;
+}
+/** Expiry (epoch ms) of the cookie named `name` in `state` — the latest if there are several; `undefined` if absent or a session cookie (`expires <= 0`). */
+export function cookieExpiryByName(state, name) {
+    const expiries = state.cookies
+        .filter((c) => c.name === name && typeof c.expires === "number" && c.expires > 0)
+        .map((c) => c.expires * 1000);
+    return expiries.length ? Math.max(...expiries) : undefined;
+}