@timqi/pier 0.0.1 → 0.0.2

package/dist/web/provider-flows.js

@@ -0,0 +1,249 @@
+// Relay one Pi provider-owned login interaction through short-lived in-memory state.
+import { randomUUID } from "node:crypto";
+import { logger } from "../log.js";
+const log = logger("web.providers");
+const FLOW_TTL_MS = 10 * 60_000;
+const TERMINAL_TTL_MS = 60_000;
+const MAX_EVENTS = 100;
+const MAX_TEXT = 4_096;
+const text = (value, max = MAX_TEXT) => typeof value === "string" ? value.slice(0, max) : "";
+const scrub = (value, secrets, max = MAX_TEXT) => {
+    let visible = typeof value === "string" ? value : "";
+    for (const secret of secrets)
+        if (secret)
+            visible = visible.replaceAll(secret, "[redacted]");
+    return visible.slice(0, max);
+};
+function visibleEvent(event, secrets) {
+    if (event.type === "info") {
+        const message = scrub(event.message, secrets);
+        if (!message)
+            return null;
+        const links = event.links?.slice(0, 20).flatMap((link) => {
+            const url = scrub(link.url, secrets, 4_096);
+            return url ? [{ url, ...(link.label ? { label: scrub(link.label, secrets, 500) } : {}) }] : [];
+        });
+        return { type: "info", message, ...(links?.length ? { links } : {}) };
+    }
+    if (event.type === "auth_url") {
+        const url = scrub(event.url, secrets, 4_096);
+        return url ? {
+            type: "auth_url",
+            url,
+            ...(event.instructions ? { instructions: scrub(event.instructions, secrets) } : {}),
+        } : null;
+    }
+    if (event.type === "device_code") {
+        const userCode = scrub(event.userCode, secrets, 500);
+        const verificationUri = scrub(event.verificationUri, secrets, 4_096);
+        return userCode && verificationUri ? {
+            type: "device_code",
+            userCode,
+            verificationUri,
+            ...(typeof event.intervalSeconds === "number" ? { intervalSeconds: event.intervalSeconds } : {}),
+            ...(typeof event.expiresInSeconds === "number" ? { expiresInSeconds: event.expiresInSeconds } : {}),
+        } : null;
+    }
+    const message = scrub(event.message, secrets);
+    return message ? { type: "progress", message } : null;
+}
+function visiblePrompt(prompt) {
+    const message = text(prompt.message);
+    if (!message)
+        throw new Error("provider returned an invalid prompt");
+    if (prompt.type === "select") {
+        const options = prompt.options.slice(0, 100).flatMap((option) => {
+            const id = text(option.id, 500);
+            const label = text(option.label, 500);
+            return id && label
+                ? [{ id, label, ...(option.description ? { description: text(option.description, 1_000) } : {}) }]
+                : [];
+        });
+        if (!options.length)
+            throw new Error("provider returned an invalid select prompt");
+        return { type: "select", message, options };
+    }
+    return {
+        type: prompt.type,
+        message,
+        ...(prompt.placeholder ? { placeholder: text(prompt.placeholder, 500) } : {}),
+    };
+}
+const snapshot = ({ controller: _controller, pending: _pending, redactions: _redactions, committing: _committing, run: _run, expires: _expires, ...flow }) => flow;
+export class ProviderFlows {
+    providers;
+    #flows = new Map();
+    constructor(providers) {
+        this.providers = providers;
+    }
+    async start(providerId, type, prepare = () => Promise.resolve(), complete = () => Promise.resolve()) {
+        if ([...this.#flows.values()].some((flow) => flow.providerId === providerId && flow.state === "running")) {
+            throw new Error(`authentication already running for ${providerId}`);
+        }
+        const flow = {
+            id: randomUUID(),
+            providerId,
+            type,
+            state: "running",
+            events: [],
+            controller: new AbortController(),
+            redactions: [],
+            committing: false,
+        };
+        flow.expires = setTimeout(() => this.#expire(flow), FLOW_TTL_MS);
+        flow.expires.unref();
+        this.#flows.set(flow.id, flow);
+        try {
+            await prepare();
+        }
+        catch (err) {
+            clearTimeout(flow.expires);
+            this.#flows.delete(flow.id);
+            throw err;
+        }
+        if (!this.#flows.has(flow.id))
+            throw new Error("authentication flow expired during setup");
+        flow.run = this.#run(flow, complete);
+        return snapshot(flow);
+    }
+    get(id) {
+        const flow = this.#flows.get(id);
+        return flow ? snapshot(flow) : undefined;
+    }
+    respond(id, promptId, value) {
+        const flow = this.#require(id);
+        if (flow.state !== "running" || !flow.pending || flow.pending.id !== promptId) {
+            throw new Error("prompt is no longer waiting for a response");
+        }
+        const pending = flow.pending;
+        flow.pending = undefined;
+        flow.prompt = undefined;
+        pending.cleanup();
+        if (value && pending.redact)
+            flow.redactions.push(value.slice(0, 64 * 1024));
+        pending.resolve(value);
+    }
+    async cancel(id) {
+        const flow = this.#require(id);
+        if (flow.state !== "running")
+            return snapshot(flow);
+        if (flow.committing)
+            return null;
+        flow.controller.abort();
+        this.#settlePrompt(flow, new Error("Login cancelled"));
+        // A provider that ignores its abort signal must not park this request —
+        // the flow then settles (or expires) in the background instead.
+        await Promise.race([flow.run, new Promise((r) => setTimeout(r, 2_000).unref())]);
+        return snapshot(flow);
+    }
+    async #run(flow, complete) {
+        let rollback;
+        try {
+            rollback = await this.providers.login(flow.providerId, flow.type, {
+                signal: flow.controller.signal,
+                prompt: (prompt) => this.#prompt(flow, prompt),
+                notify: (event) => {
+                    const visible = visibleEvent(event, flow.redactions);
+                    if (!visible)
+                        return;
+                    flow.events.push(visible);
+                    if (flow.events.length > MAX_EVENTS)
+                        flow.events.shift();
+                },
+            });
+            flow.controller.signal.throwIfAborted();
+            flow.committing = true;
+            await complete();
+            flow.committing = false;
+            this.#finish(flow, "succeeded");
+        }
+        catch (err) {
+            flow.committing = false;
+            let failure = err;
+            if (rollback) {
+                try {
+                    await rollback();
+                }
+                catch (rollbackError) {
+                    failure = new AggregateError([err, rollbackError], "provider login rollback failed");
+                }
+            }
+            if (flow.state !== "running")
+                return;
+            if (flow.controller.signal.aborted && failure === err)
+                this.#finish(flow, "cancelled");
+            else {
+                const error = this.#safeError(flow, failure);
+                log.warn(`provider login failed for ${flow.providerId}: ${error}`);
+                this.#finish(flow, "failed", error);
+            }
+        }
+    }
+    #prompt(flow, prompt) {
+        if (flow.controller.signal.aborted)
+            return Promise.reject(new Error("Login cancelled"));
+        if (flow.pending)
+            return Promise.reject(new Error("provider requested overlapping prompts"));
+        const visible = visiblePrompt(prompt);
+        const { signal } = prompt;
+        const id = randomUUID();
+        flow.prompt = { ...visible, id };
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                if (flow.pending?.id !== id)
+                    return;
+                flow.pending = undefined;
+                flow.prompt = undefined;
+                reject(new Error("Prompt cancelled"));
+            };
+            const cleanup = () => signal?.removeEventListener("abort", onAbort);
+            flow.pending = { id, redact: visible.type !== "select", resolve, reject, cleanup };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
+        });
+    }
+    #settlePrompt(flow, error) {
+        const pending = flow.pending;
+        flow.pending = undefined;
+        flow.prompt = undefined;
+        pending?.cleanup();
+        pending?.reject(error);
+    }
+    #finish(flow, state, error) {
+        if (flow.state !== "running")
+            return;
+        clearTimeout(flow.expires);
+        this.#settlePrompt(flow, new Error("Login finished"));
+        flow.state = state;
+        flow.error = error;
+        flow.events = [];
+        flow.redactions = [];
+        flow.expires = setTimeout(() => this.#flows.delete(flow.id), TERMINAL_TTL_MS);
+        flow.expires.unref();
+    }
+    #safeError(flow, err) {
+        return scrub(String(err), flow.redactions);
+    }
+    #require(id) {
+        const flow = this.#flows.get(id);
+        if (!flow)
+            throw new Error("unknown authentication flow");
+        return flow;
+    }
+    #expire(flow) {
+        if (flow.committing) {
+            flow.expires = setTimeout(() => this.#expire(flow), 1_000);
+            flow.expires.unref();
+            return;
+        }
+        if (flow.state === "running") {
+            flow.controller.abort();
+            this.#settlePrompt(flow, new Error("Login expired"));
+            flow.state = "cancelled";
+        }
+        flow.events = [];
+        flow.redactions = [];
+        this.#flows.delete(flow.id);
+    }
+}

package/dist/web/providers.js

@@ -0,0 +1,129 @@
+// HTTP boundary for provider configuration.
+import { isProviderApi, validateProviderSetup } from "../core/types.js";
+import { ProviderFlows } from "./provider-flows.js";
+/** Unknown JSON into a trimmed, validated ProviderSetup. Shape lives here;
+ *  the rules (id charset, endpoint safety, model limits) are the shared
+ *  validateProviderSetup in core — web/ cannot import agent/ to reuse its
+ *  copy, and must not re-implement them. */
+function setupFrom(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const input = raw;
+    const id = typeof input.id === "string" ? input.id.trim() : "";
+    const name = typeof input.name === "string" ? input.name.trim() : "";
+    const endpoint = typeof input.endpoint === "string" ? input.endpoint.trim() : "";
+    if (!id)
+        return null;
+    if (input.kind === "builtin")
+        return { kind: "builtin", id, ...(endpoint ? { endpoint } : {}) };
+    if (input.kind !== "custom" || !isProviderApi(input.api) || !Array.isArray(input.models))
+        return null;
+    const models = [];
+    for (const model of input.models) {
+        const modelId = typeof model === "object" && model !== null &&
+            typeof model.id === "string"
+            ? model.id.trim()
+            : "";
+        if (!modelId)
+            return null;
+        models.push({ id: modelId, reasoning: model.reasoning === true });
+    }
+    return {
+        kind: "custom",
+        id,
+        ...(name ? { name } : {}),
+        endpoint,
+        api: input.api,
+        models,
+    };
+}
+export function registerProviderRoutes(app, providers) {
+    const flows = new ProviderFlows(providers);
+    const configure = async (setup) => {
+        await providers.setup(setup);
+        const provider = (await providers.providers()).find((candidate) => candidate.id === setup.id);
+        if (!provider)
+            throw new Error(`provider did not load: ${setup.id}`);
+        return provider;
+    };
+    const requireMethod = (provider, type) => {
+        if (!provider.methods.some((method) => method.type === type)) {
+            throw new Error(`${type} login is not available for ${provider.id}`);
+        }
+    };
+    app.get("/api/providers", async (c) => {
+        c.header("cache-control", "no-store");
+        return c.json(await providers.providers());
+    });
+    app.post("/api/providers/setup", async (c) => {
+        const body = await c.req.json().catch(() => null);
+        const setup = setupFrom(body?.setup);
+        const authType = body?.authType;
+        if (!setup || (authType !== null && authType !== "api_key" && authType !== "oauth")) {
+            return c.json({ error: "valid setup and authType required" }, 400);
+        }
+        try {
+            validateProviderSetup(setup); // before any flow starts — the throw is the 400
+            if (setup.kind === "custom" && authType === "oauth") {
+                return c.json({ error: "custom providers support API-key authentication" }, 400);
+            }
+            if (authType === null)
+                return c.json({ ok: true, provider: await configure(setup) });
+            const before = (await providers.providers()).find((candidate) => candidate.id === setup.id);
+            if (setup.kind === "builtin" && !before?.builtin) {
+                return c.json({ error: "unknown built-in provider" }, 400);
+            }
+            if (before)
+                requireMethod(before, authType);
+            const flow = await flows.start(setup.id, authType, async () => {
+                if (!before)
+                    requireMethod(await configure(setup), authType);
+            }, async () => {
+                if (before)
+                    await configure(setup);
+            });
+            return c.json(flow, 202);
+        }
+        catch (err) {
+            return c.json({ error: String(err) }, 400);
+        }
+    });
+    app.get("/api/providers/flows/:id", (c) => {
+        c.header("cache-control", "no-store");
+        const flow = flows.get(c.req.param("id"));
+        return flow ? c.json(flow) : c.json({ error: "unknown authentication flow" }, 404);
+    });
+    app.post("/api/providers/flows/:id/respond", async (c) => {
+        const body = await c.req.json().catch(() => null);
+        if (typeof body?.promptId !== "string" || typeof body?.value !== "string" ||
+            body.value.length > 64 * 1024)
+            return c.json({ error: "promptId and value required (64 KiB maximum)" }, 400);
+        try {
+            flows.respond(c.req.param("id"), body.promptId, body.value);
+            return c.body(null, 204);
+        }
+        catch (err) {
+            return c.json({ error: String(err) }, 409);
+        }
+    });
+    app.post("/api/providers/flows/:id/cancel", async (c) => {
+        try {
+            const flow = await flows.cancel(c.req.param("id"));
+            if (!flow)
+                return c.json({ error: "authentication is finishing" }, 409);
+            return flow.state === "failed" ? c.json(flow, 409) : c.json(flow);
+        }
+        catch (err) {
+            return c.json({ error: String(err) }, 404);
+        }
+    });
+    app.post("/api/providers/:provider/logout", async (c) => {
+        try {
+            await providers.logout(c.req.param("provider"));
+            return c.json({ ok: true });
+        }
+        catch (err) {
+            return c.json({ error: String(err) }, 400);
+        }
+    });
+}