@docsxai/engine 0.2.0

package/dist/backend-client-oauth-login.js

@@ -0,0 +1,90 @@
+// OAuth 2.1 + PKCE login flow (`docsxai login --oauth`): drives the authorization-code handshake
+// against the backend's minimal authorization server. Re-exported from `./backend-client.js`.
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { BackendClientError, } from "./backend-client-contracts.js";
+/**
+ * Drive the authorization-code + PKCE handshake against the backend's minimal authorization
+ * server: start a loopback listener for the redirect, hand the authorize URL to the caller,
+ * await the code, exchange it (S256 verifier) for tokens.
+ */
+export async function oauthLogin(opts) {
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    const base = opts.backendUrl.replace(/\/+$/, "");
+    const verifier = randomBytes(32).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    const state = randomBytes(16).toString("base64url");
+    let resolveCode;
+    let rejectCode;
+    const codePromise = new Promise((resolve, reject) => {
+        resolveCode = resolve;
+        rejectCode = reject;
+    });
+    const server = createServer((req, res) => {
+        const u = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (u.pathname !== "/callback") {
+            res.writeHead(404).end();
+            return;
+        }
+        const gotCode = u.searchParams.get("code");
+        if (u.searchParams.get("state") !== state || !gotCode) {
+            res.writeHead(400, { "content-type": "text/plain" });
+            res.end("docsxai login: state mismatch or missing code\n");
+            rejectCode(new BackendClientError("OAuth redirect carried a bad state or no code"));
+            return;
+        }
+        res.writeHead(200, { "content-type": "text/plain" });
+        res.end("docsxai login complete — you can close this tab.\n");
+        resolveCode(gotCode);
+    });
+    const port = await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (addr && typeof addr === "object")
+                resolve(addr.port);
+            else
+                reject(new BackendClientError("failed to bind the OAuth callback listener"));
+        });
+    });
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const authorizeUrl = new URL(`${base}/v1/oauth/authorize`);
+    authorizeUrl.searchParams.set("client_id", "docsxai-cli");
+    authorizeUrl.searchParams.set("code_challenge", challenge);
+    authorizeUrl.searchParams.set("code_challenge_method", "S256");
+    authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+    authorizeUrl.searchParams.set("state", state);
+    opts.onAuthorizeUrl(authorizeUrl.toString());
+    const timer = setTimeout(() => {
+        rejectCode(new BackendClientError("OAuth login timed out waiting for the browser redirect"));
+    }, opts.timeoutMs ?? 300_000);
+    timer.unref();
+    let code;
+    try {
+        code = await codePromise;
+    }
+    finally {
+        clearTimeout(timer);
+        server.close();
+    }
+    const res = await doFetch(`${base}/v1/oauth/token`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            code_verifier: verifier,
+            redirect_uri: redirectUri,
+        }).toString(),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new BackendClientError(`token exchange → ${res.status}: ${text.slice(0, 200)}`, res.status);
+    }
+    const tokens = (await res.json());
+    return {
+        access_token: tokens.access_token,
+        refresh_token: tokens.refresh_token,
+        expires_at: Date.now() + tokens.expires_in * 1000,
+    };
+}

package/dist/backend-client-state-cache.d.ts

@@ -0,0 +1,73 @@
+export interface CachedStorageState {
+    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;
+        }>;
+    }>;
+}
+export interface CachedAuthResult {
+    storageState: CachedStorageState;
+    /** Epoch ms when the session is known to expire (e.g. from a cookie's `expires`). Optional. */
+    expiresAt?: number;
+}
+export interface CacheRoleConfig {
+    cache: {
+        /** `"session"`, a duration string (`30m`, `1h`, `500ms`), or ms as a number. */
+        ttl: string | number;
+        auth_cookie?: string;
+    };
+}
+export declare class BackendStateCacheError extends Error {
+    constructor(message: string);
+}
+export interface BackendStateCacheOptions {
+    baseUrl: string;
+    token: string;
+    workspaceId: string;
+    /** Base64-encoded 32-byte AES key — the resolved value of `DOCSX_CACHE_KEY`. */
+    cacheKey: string;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Backend-relayed storage-state cache. Same `load` / `save` / `clear` contract as the local
+ * `.auth/<role>.json` cache (incl. the expiry-priority rules), but the entry lives on the backend
+ * as a client-side-encrypted envelope — usable by a team sharing one backend, opaque to the server.
+ */
+export declare class BackendStateCache {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly workspaceId;
+    private readonly key;
+    private readonly doFetch;
+    constructor(opts: BackendStateCacheOptions);
+    /** Return the cached state for a role if present and not past its expiry; otherwise `null`. */
+    load(role: string, now?: number): Promise<CachedStorageState | null>;
+    /**
+     * Encrypt + store a captured session, computing its expiry exactly like the local cache:
+     * auth-cookie expiry when available, else `ttl`, else the strategy-reported `expiresAt`
+     * (if plausibly in the future), else +1h. Refuses to cache an already-dead session.
+     */
+    save(role: string, result: CachedAuthResult, roleAuth: CacheRoleConfig, now?: number, opts?: {
+        authCookie?: string;
+    }): Promise<{
+        expiresAt: number;
+        source: string;
+    }>;
+    clear(role: string): Promise<void>;
+    private url;
+    private headers;
+    private encrypt;
+    private decrypt;
+}

package/dist/backend-client-state-cache.js

@@ -0,0 +1,185 @@
+// Encrypted storage-state cache relay (`BackendStateCache`). Re-exported from `./backend-client.js`.
+//
+// Client-side encryption: the backend stores an opaque AES-256-GCM envelope and never sees the
+// plaintext session. The shapes below are structural mirrors of the engine's auth layer
+// (`StorageState` / `AuthResult` / `RoleAuth.cache`) — deliberately not imported from auth.ts so
+// the modules stay decoupled; the auth layer satisfies them structurally.
+//
+// NOTE: the ttl-to-ms / cookie-expiry math here is the same shape that also lives in
+// `auth/storage-state-cache.ts` and `auth/types.ts`. The two helpers below are file-private (a
+// single copy for the backend-client surface); the auth/* copies are left untouched here, so the
+// shape exists in three places but each is small and within the jscpd budget.
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { API_VERSION, API_VERSION_HEADER, BackendClientError } from "./backend-client-contracts.js";
+export class BackendStateCacheError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BackendStateCacheError";
+    }
+}
+/** Parse a `ttl` (number ms, duration string `30m`/`1h`/`500ms`, or anything else) to ms or `"session"`. */
+function ttlToMs(ttl) {
+    if (typeof ttl === "number")
+        return ttl;
+    const m = /^(\d+)(ms|s|m|h)$/.exec(ttl);
+    if (!m)
+        return "session";
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "ms":
+            return n;
+        case "s":
+            return n * 1000;
+        case "m":
+            return n * 60_000;
+        default:
+            return n * 3_600_000;
+    }
+}
+/** Expiry (epoch ms) of the cookie named `name` — the latest if several; `undefined` if absent or session-only. */
+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;
+}
+/**
+ * Backend-relayed storage-state cache. Same `load` / `save` / `clear` contract as the local
+ * `.auth/<role>.json` cache (incl. the expiry-priority rules), but the entry lives on the backend
+ * as a client-side-encrypted envelope — usable by a team sharing one backend, opaque to the server.
+ */
+export class BackendStateCache {
+    baseUrl;
+    token;
+    workspaceId;
+    key;
+    doFetch;
+    constructor(opts) {
+        if (!opts.cacheKey) {
+            throw new BackendStateCacheError("missing cache key — set DOCSX_CACHE_KEY to a base64-encoded 32-byte key");
+        }
+        const key = Buffer.from(opts.cacheKey, "base64");
+        if (key.length !== 32) {
+            throw new BackendStateCacheError(`malformed cache key — DOCSX_CACHE_KEY must decode to exactly 32 bytes (got ${key.length})`);
+        }
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.token = opts.token;
+        this.workspaceId = opts.workspaceId;
+        this.key = key;
+        this.doFetch = opts.fetch ?? globalThis.fetch;
+    }
+    /** Return the cached state for a role if present and not past its expiry; otherwise `null`. */
+    async load(role, now = Date.now()) {
+        const res = await this.doFetch(this.url(role), { headers: this.headers() });
+        if (res.status === 404)
+            return null;
+        if (!res.ok) {
+            throw new BackendClientError(`GET auth-cache(${role}) → ${res.status}`, res.status);
+        }
+        const envelope = (await res.json());
+        const plain = this.decrypt(envelope);
+        let entry;
+        try {
+            entry = JSON.parse(plain);
+        }
+        catch {
+            return null; // corrupt entry → treat as miss (mirrors the local cache)
+        }
+        if (!entry.storageState || typeof entry.expiresAt !== "number" || entry.expiresAt <= now) {
+            return null;
+        }
+        return entry.storageState;
+    }
+    /**
+     * Encrypt + store a captured session, computing its expiry exactly like the local cache:
+     * auth-cookie expiry when available, else `ttl`, else the strategy-reported `expiresAt`
+     * (if plausibly in the future), else +1h. Refuses to cache an already-dead session.
+     */
+    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 BackendStateCacheError(`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 };
+        const envelope = {
+            ...this.encrypt(JSON.stringify(entry)),
+            expires_at: expiresAt,
+        };
+        const res = await this.doFetch(this.url(role), {
+            method: "PUT",
+            headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify(envelope),
+        });
+        if (!res.ok) {
+            throw new BackendClientError(`PUT auth-cache(${role}) → ${res.status}`, res.status);
+        }
+        return { expiresAt, source };
+    }
+    async clear(role) {
+        const res = await this.doFetch(this.url(role), {
+            method: "DELETE",
+            headers: this.headers(),
+        });
+        if (!res.ok && res.status !== 404) {
+            throw new BackendClientError(`DELETE auth-cache(${role}) → ${res.status}`, res.status);
+        }
+    }
+    url(role) {
+        return `${this.baseUrl}/v1/workspaces/${encodeURIComponent(this.workspaceId)}/auth-cache/${encodeURIComponent(role)}`;
+    }
+    headers(extra) {
+        return {
+            authorization: `Bearer ${this.token}`,
+            [API_VERSION_HEADER]: API_VERSION,
+            ...(extra ?? {}),
+        };
+    }
+    encrypt(plain) {
+        const iv = randomBytes(12);
+        const cipher = createCipheriv("aes-256-gcm", this.key, iv);
+        const ciphertext = Buffer.concat([cipher.update(plain, "utf8"), cipher.final()]);
+        return {
+            schema: "docsxai/auth-cache@1",
+            alg: "aes-256-gcm",
+            iv: iv.toString("base64"),
+            ciphertext: ciphertext.toString("base64"),
+            tag: cipher.getAuthTag().toString("base64"),
+        };
+    }
+    decrypt(envelope) {
+        try {
+            const decipher = createDecipheriv("aes-256-gcm", this.key, Buffer.from(envelope.iv, "base64"));
+            decipher.setAuthTag(Buffer.from(envelope.tag, "base64"));
+            return Buffer.concat([
+                decipher.update(Buffer.from(envelope.ciphertext, "base64")),
+                decipher.final(),
+            ]).toString("utf8");
+        }
+        catch {
+            throw new BackendStateCacheError("auth-cache decryption failed — wrong DOCSX_CACHE_KEY or tampered ciphertext");
+        }
+    }
+}

package/dist/backend-client-token.d.ts

@@ -0,0 +1,18 @@
+import { type BackendTokenFile } from "./backend-client-contracts.js";
+export declare function loadBackendTokenFile(workspaceDir: string): Promise<BackendTokenFile | null>;
+/** Persist OAuth tokens under the workspace's `.auth/` (operator-local; gitignored), mode 0600. */
+export declare function saveBackendTokenFile(workspaceDir: string, tokens: BackendTokenFile): Promise<string>;
+/**
+ * Resolve the bearer token for a backend call, in priority order:
+ *   1. the explicit `token` option,
+ *   2. the `DOCSX_TOKEN` env var (the CI path),
+ *   3. the workspace's stored OAuth tokens (`.auth/backend-token.json`), refreshing them against
+ *      the backend when expired (rotated tokens are written back to the file).
+ */
+export declare function resolveBackendToken(opts: {
+    baseUrl: string;
+    token?: string;
+    workspaceDir?: string;
+    fetch?: typeof globalThis.fetch;
+    now?: number;
+}): Promise<string>;

package/dist/backend-client-token.js

@@ -0,0 +1,94 @@
+// Bearer-token resolution for backend calls: the stored OAuth token file (`.auth/backend-token.json`),
+// the resolution precedence (explicit → `DOCSX_TOKEN` → stored, with refresh-rotation), and the
+// load/save helpers. Re-exported from `./backend-client.js`.
+import { promises as fs } from "node:fs";
+import { resolveWorkspacePath, resolveWorkspacePathReal } from "./workspace.js";
+import { BackendClientError } from "./backend-client-contracts.js";
+const BACKEND_TOKEN_FILE = "backend-token.json";
+export async function loadBackendTokenFile(workspaceDir) {
+    let text;
+    try {
+        text = await fs.readFile(resolveWorkspacePath(workspaceDir, ".auth", BACKEND_TOKEN_FILE), "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.access_token === "string" &&
+            typeof parsed.refresh_token === "string" &&
+            typeof parsed.expires_at === "number") {
+            return {
+                access_token: parsed.access_token,
+                refresh_token: parsed.refresh_token,
+                expires_at: parsed.expires_at,
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist OAuth tokens under the workspace's `.auth/` (operator-local; gitignored), mode 0600. */
+export async function saveBackendTokenFile(workspaceDir, tokens) {
+    await fs.mkdir(resolveWorkspacePath(workspaceDir, ".auth"), { recursive: true });
+    const target = await resolveWorkspacePathReal(workspaceDir, ".auth", BACKEND_TOKEN_FILE);
+    await fs.writeFile(target, JSON.stringify(tokens, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    await fs.chmod(target, 0o600);
+    return target;
+}
+/**
+ * Resolve the bearer token for a backend call, in priority order:
+ *   1. the explicit `token` option,
+ *   2. the `DOCSX_TOKEN` env var (the CI path),
+ *   3. the workspace's stored OAuth tokens (`.auth/backend-token.json`), refreshing them against
+ *      the backend when expired (rotated tokens are written back to the file).
+ */
+export async function resolveBackendToken(opts) {
+    if (opts.token)
+        return opts.token;
+    if (process.env.DOCSX_TOKEN)
+        return process.env.DOCSX_TOKEN;
+    const reloginHint = `set DOCSX_TOKEN or run \`docsxai login --backend-url ${opts.baseUrl} --oauth <workspace-dir>\``;
+    if (!opts.workspaceDir) {
+        throw new BackendClientError(`no bearer token — ${reloginHint}`);
+    }
+    const stored = await loadBackendTokenFile(opts.workspaceDir);
+    if (!stored) {
+        throw new BackendClientError(`no bearer token — ${reloginHint}`);
+    }
+    const now = opts.now ?? Date.now();
+    if (stored.expires_at > now + 30_000)
+        return stored.access_token;
+    // Expired (or about to) — attempt a refresh-token rotation.
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    const base = opts.baseUrl.replace(/\/+$/, "");
+    let refreshed;
+    try {
+        const res = await doFetch(`${base}/v1/oauth/token`, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: stored.refresh_token,
+            }).toString(),
+        });
+        if (!res.ok)
+            throw new BackendClientError(`token refresh → ${res.status}`, res.status);
+        refreshed = (await res.json());
+    }
+    catch (e) {
+        throw new BackendClientError(`stored backend token expired and the refresh failed (${e.message}) — ${reloginHint}`);
+    }
+    const tokens = {
+        access_token: refreshed.access_token,
+        refresh_token: refreshed.refresh_token,
+        expires_at: now + refreshed.expires_in * 1000,
+    };
+    await saveBackendTokenFile(opts.workspaceDir, tokens);
+    return tokens.access_token;
+}

package/dist/backend-client-transport.d.ts

@@ -0,0 +1,66 @@
+import { type RevisionKind } from "./doc-pack.js";
+import { type BackendClientOptions, type BlobRef, type Project, type Revision, type RevisionArtifact, type RunRecord, type Workspace } from "./backend-client-contracts.js";
+export declare class BackendClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly doFetch;
+    constructor(opts: BackendClientOptions);
+    private headers;
+    private req;
+    health(): Promise<{
+        ok: boolean;
+    }>;
+    listWorkspaces(): Promise<Workspace[]>;
+    createWorkspace(name: string): Promise<Workspace>;
+    getWorkspace(id: string): Promise<Workspace>;
+    listProjects(wsId: string): Promise<Project[]>;
+    createProject(wsId: string, name: string): Promise<Project>;
+    getProject(wsId: string, projectId: string): Promise<Project>;
+    listRevisions(wsId: string, projectId: string): Promise<Revision[]>;
+    createRevision(wsId: string, projectId: string, body: {
+        kind: RevisionKind;
+        author: string;
+    }): Promise<Revision>;
+    getRevision(wsId: string, projectId: string, rev: string): Promise<Revision>;
+    /** Finalize a revision (idempotent). Artifact PUTs afterwards are rejected with 409. */
+    finalizeRevision(wsId: string, projectId: string, rev: string): Promise<Revision>;
+    /** PUT an artifact's payload on a revision. The backend treats the payload as opaque JSON. */
+    putArtifact(wsId: string, projectId: string, rev: string, artifact: RevisionArtifact, payload: unknown): Promise<void>;
+    getArtifact<T = unknown>(wsId: string, projectId: string, rev: string, artifact: RevisionArtifact): Promise<T>;
+    appendRun(wsId: string, projectId: string, rec: {
+        rev: string;
+        ok: boolean;
+        duration_ms: number;
+        summary: string;
+    }): Promise<RunRecord>;
+    listRuns(wsId: string, projectId: string): Promise<RunRecord[]>;
+    /** Upload raw bytes; the backend stores them under their sha256. Idempotent. */
+    putBlob(data: Uint8Array): Promise<BlobRef>;
+    /** HEAD-probe a blob — true when the backend already has these bytes. */
+    hasBlob(sha256: string): Promise<boolean>;
+    getBlob(sha256: string): Promise<Uint8Array>;
+}
+/** Build a {@link BackendClient} with the token resolved via {@link resolveBackendToken}. */
+export declare function createBackendClient(opts: BackendClientOptions & {
+    workspaceDir?: string;
+}): Promise<BackendClient>;
+/**
+ * Append an execution-run record for a backend-bound workspace. A no-op when the workspace config
+ * lacks the backend binding; never throws — `docsxai run` must stay offline-tolerant, so failures
+ * come back as a warning string for the caller to surface.
+ */
+export declare function recordRunHistory(opts: {
+    workspaceDir: string;
+    config: {
+        backend_url?: string;
+        backend_workspace_id?: string;
+        backend_project_id?: string;
+    };
+    ok: boolean;
+    durationMs: number;
+    summary: string;
+    fetch?: typeof globalThis.fetch;
+}): Promise<{
+    recorded: boolean;
+    warning?: string;
+}>;