@anchrd/intel 0.59.0

package/dist/auth/auth.js

@@ -0,0 +1,284 @@
+import { calculatePKCECodeChallenge, randomPKCECodeVerifier, randomState } from "openid-client";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+import { reportUnexpectedError } from "../shared/report-unexpected-error/report-unexpected-error.js";
+import { SafeReturnPath } from "../shared/safe-return-path/safe-return-path.js";
+const cookieName = "intel_session";
+// ⚠️ The cookie outlives the handoff on purpose. Ten minutes is right for something carrying a PKCE
+// verifier, but the portal's consent screen can stand open longer — it waits for every server to
+// connect, and a person steps away meanwhile. An expired handoff that is still *readable* tells the
+// callback what was being attempted, where the person wanted to go, and whether their Intel session
+// survived; a cookie that vanished with it leaves nothing but a raw error page (#95). `expiresAt`
+// remains the only authority — a stale verifier is never exchanged, no matter how long it is legible.
+const HandoffValidSeconds = 10 * 60;
+const HandoffCookieSeconds = 60 * 60;
+// What an authorization server answers when `prompt=none` would have worked, but only with somebody
+// looking at a screen. It is the expected answer to a silent attempt, not a broken deployment.
+const InteractionRequired = new Set([
+    "login_required",
+    "interaction_required",
+    "consent_required",
+    "account_selection_required",
+]);
+// Fixed markers, never the portal's own words. `error_description` is a sentence written by the
+// authorization server about somebody else's policy: putting it in the URL would hand whatever
+// renders the page next a string Intel does not control. Which marker matters — a refusal is about
+// access, running out of time is not, and a screen that confuses the two sends the reader hunting
+// in the wrong place (#93).
+function withConnectError(returnTo, code = "portal_sign_in_refused") {
+    const url = new URL(returnTo, "https://intel.invalid");
+    url.searchParams.set("connectError", code);
+    return `${url.pathname}${url.search}`;
+}
+function cookieValue(headers) {
+    const values = headers.get("cookie")?.split(";") ?? [];
+    for (const value of values) {
+        const [name, ...rest] = value.trim().split("=");
+        if (name === cookieName)
+            return rest.join("=") || null;
+    }
+    return null;
+}
+function sessionCookie(value, secure, maxAge) {
+    return `${cookieName}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${Math.max(0, Math.floor(maxAge))}${secure ? "; Secure" : ""}`;
+}
+function redirect(location, cookie) {
+    const headers = new Headers({ location, "cache-control": "no-store" });
+    if (cookie)
+        headers.set("set-cookie", cookie);
+    return new Response(null, { status: 302, headers });
+}
+async function pkce() {
+    for (;;) {
+        const verifier = randomPKCECodeVerifier();
+        const challenge = await calculatePKCECodeChallenge(verifier);
+        if (/^[A-Za-z0-9]/.test(challenge))
+            return { verifier, challenge };
+    }
+}
+export function createBrowserAuth(deps) {
+    const baseUrl = deps.baseUrl.replace(/\/+$/, "");
+    const gateIssuer = deps.gateUrl.replace(/\/+$/, "");
+    const redirectUri = `${baseUrl}/auth/callback`;
+    const secure = new URL(baseUrl).protocol === "https:";
+    async function clientId(issuer, resource, scope) {
+        // ⚠️ The suffix is a registration generation, and it is what makes a fix to the registration
+        // reach an installation that already has one. A stored client is reused forever, so #97 —
+        // clients registered without the `resource` parameter and therefore never given a refresh
+        // token — would have been repaired in code and nowhere else: every existing deployment would
+        // keep handing back the broken registration it made months ago. Raise this whenever the
+        // REGISTRATION changes shape, never for anything else; each raise costs one silent
+        // re-registration per issuer and resource.
+        const registrationKey = `${issuer}#${resource}#r2`;
+        const stored = await deps.clients.get(registrationKey, redirectUri);
+        if (stored)
+            return stored;
+        // A refused registration becomes a named state instead of a bare 500 (#93). The conversion
+        // must not eat the reason: an IntelError is an expected refusal nobody logs, so the library's
+        // own exception is written here — it is the only place that still holds it.
+        const registered = await deps.oauth
+            .register({
+            issuer,
+            redirectUri,
+            clientName: "Intel",
+            resource,
+            ...(scope ? { scope } : {}),
+        })
+            .catch((error) => {
+            reportUnexpectedError(error);
+            throw new IntelError(502, "client_registration_failed", "The authorization server refused the client registration");
+        });
+        return await deps.clients.put({
+            issuer: registrationKey,
+            redirectUri,
+            clientId: registered,
+            createdAt: deps.now().toISOString(),
+        });
+    }
+    // The connection handoff parks the Intel session inside the pending cookie, so every way out of
+    // the callback has to put it back — the portal attempt must never cost somebody their Intel login.
+    async function restore(user, returnTo, location) {
+        const remaining = (user.expiresAt - deps.now().getTime()) / 1_000;
+        if (remaining <= 0) {
+            return redirect(`/auth/login?returnTo=${encodeURIComponent(returnTo)}`, sessionCookie("", secure, 0));
+        }
+        return redirect(location, sessionCookie(await deps.sessions.seal(user), secure, remaining));
+    }
+    async function userSession(client, tokens) {
+        return {
+            version: 1,
+            kind: "user",
+            clientId: client,
+            accessToken: tokens.accessToken,
+            expiresAt: deps.now().getTime() + Math.max(30, tokens.expiresIn) * 1_000,
+        };
+    }
+    return {
+        async login(requestUrl) {
+            const returnTo = SafeReturnPath.catch("/").parse(requestUrl.searchParams.get("returnTo") ?? "/");
+            const client = await clientId(gateIssuer, deps.resource);
+            const { verifier: codeVerifier, challenge: codeChallenge } = await pkce();
+            const state = randomState();
+            const pending = {
+                version: 1,
+                kind: "pending",
+                clientId: client,
+                codeVerifier,
+                state,
+                returnTo,
+                expiresAt: deps.now().getTime() + 10 * 60 * 1_000,
+            };
+            const authorizationUrl = await deps.oauth.authorizationUrl({
+                issuer: gateIssuer,
+                clientId: client,
+                redirectUri,
+                resource: deps.resource,
+                codeChallenge,
+                state,
+                scope: "openid profile email",
+            });
+            return redirect(authorizationUrl.href, sessionCookie(await deps.sessions.seal(pending), secure, 10 * 60));
+        },
+        async connect(requestUrl, headers, userId) {
+            const encoded = cookieValue(headers);
+            const user = encoded ? await deps.sessions.open(encoded) : null;
+            if (user?.kind !== "user" || user.expiresAt <= deps.now().getTime() + 30_000) {
+                throw new IntelError(401, "authentication_required", "Authentication is required");
+            }
+            const returnTo = SafeReturnPath.catch("/tools").parse(requestUrl.searchParams.get("returnTo") ?? "/tools");
+            // Gate is the OIDC provider Cloudflare Access consumes, so whoever holds a valid Intel
+            // session is already the person the portal would ask about. `prompt=none` says exactly that:
+            // answer from the session that exists, and refuse rather than show anybody a login (#60).
+            const silent = requestUrl.searchParams.get("silent") === "1";
+            const resumed = requestUrl.searchParams.get("resumed") === "1";
+            if (!deps.portalUrl) {
+                throw new IntelError(503, "portal_not_configured", "No MCP portal is configured for this deployment");
+            }
+            const discovered = await deps.oauth.discoverResource(deps.portalUrl).catch(() => {
+                throw new IntelError(409, "portal_oauth_unavailable", "The MCP portal does not publish usable OAuth metadata");
+            });
+            const connectionClientId = await clientId(discovered.issuer, discovered.resource, discovered.scope);
+            const { verifier: codeVerifier, challenge: codeChallenge } = await pkce();
+            const state = randomState();
+            const pending = {
+                version: 1,
+                kind: "connection-pending",
+                clientId: connectionClientId,
+                codeVerifier,
+                state,
+                returnTo,
+                issuer: discovered.issuer,
+                resource: discovered.resource,
+                userId,
+                user,
+                silent,
+                resumed,
+                expiresAt: deps.now().getTime() + HandoffValidSeconds * 1_000,
+            };
+            const authorizationUrl = await deps.oauth.authorizationUrl({
+                issuer: discovered.issuer,
+                clientId: connectionClientId,
+                redirectUri,
+                resource: discovered.resource,
+                codeChallenge,
+                state,
+                ...(discovered.scope ? { scope: discovered.scope } : {}),
+                ...(silent ? { prompt: "none" } : {}),
+            });
+            return redirect(authorizationUrl.href, sessionCookie(await deps.sessions.seal(pending), secure, HandoffCookieSeconds));
+        },
+        async callback(requestUrl, headers) {
+            const encoded = cookieValue(headers);
+            const pending = encoded ? await deps.sessions.open(encoded) : null;
+            if (pending?.kind !== "pending" && pending?.kind !== "connection-pending") {
+                throw new IntelError(400, "oauth_session_invalid", "OAuth session is missing or expired");
+            }
+            // A handoff that ran out while somebody was still on the consent screen is not a failure they
+            // caused, and everything needed to carry on is in it: their parked Intel session and where
+            // they were going. `restore` decides which — it sends them back to the Gate login when that
+            // session is gone too, rather than into an attempt that could not finish (#95).
+            if (pending.kind === "connection-pending" && pending.expiresAt <= deps.now().getTime()) {
+                return await restore(pending.user, pending.returnTo, pending.resumed
+                    ? withConnectError(pending.returnTo, "portal_sign_in_expired")
+                    : `/auth/connect?returnTo=${encodeURIComponent(pending.returnTo)}&resumed=1`);
+            }
+            // The Gate login handoff parks nothing, so an expired one has nowhere to return to.
+            if (pending.expiresAt <= deps.now().getTime()) {
+                throw new IntelError(400, "oauth_session_invalid", "OAuth session is missing or expired");
+            }
+            // ⚠️ An authorization server reports a refusal on the redirect URI, not by failing the token
+            // exchange. Reading it here is what keeps a refused silent attempt from surfacing as a raw
+            // OAuth error, and it is the only place that knows whether a visible attempt is still owed.
+            const refusal = requestUrl.searchParams.get("error");
+            if (pending.kind === "connection-pending" && refusal) {
+                // The silent attempt only asked whether the sign-in works without a screen. "Not without
+                // one" is an answer, so the visible flow runs once — and because that one is not silent, a
+                // second refusal ends in the message instead of a third attempt.
+                const visibleAttemptLeft = pending.silent && InteractionRequired.has(refusal);
+                return await restore(pending.user, pending.returnTo, visibleAttemptLeft
+                    ? `/auth/connect?returnTo=${encodeURIComponent(pending.returnTo)}`
+                    : withConnectError(pending.returnTo));
+            }
+            // ⚠️ Everything below runs with the handoff READ, and that is the whole difference between
+            // this catch and the one on the route (#444): here a failure knows where the person was
+            // going, and for a connection handoff it still holds their parked Intel session. The route
+            // can only send somebody to a decided screen, so whatever can be answered here is answered
+            // here — the token exchange, the portal token write and the sealing of the new session all
+            // used to end as a bare 500 in JSON, in the middle of a sign-in.
+            try {
+                const tokens = await deps.oauth.exchange({
+                    issuer: pending.kind === "connection-pending" ? pending.issuer : gateIssuer,
+                    clientId: pending.clientId,
+                    callbackUrl: requestUrl,
+                    redirectUri,
+                    resource: pending.kind === "connection-pending" ? pending.resource : deps.resource,
+                    codeVerifier: pending.codeVerifier,
+                    state: pending.state,
+                });
+                if (pending.kind === "connection-pending") {
+                    await deps.portalTokens.write(pending.userId, {
+                        accessToken: tokens.accessToken,
+                        refreshToken: tokens.refreshToken ?? null,
+                        expiresAt: deps.now().getTime() + Math.max(30, tokens.expiresIn) * 1_000,
+                        issuer: pending.issuer,
+                        clientId: pending.clientId,
+                        resource: pending.resource,
+                    });
+                    return await restore(pending.user, pending.returnTo, pending.returnTo);
+                }
+                const session = await userSession(pending.clientId, tokens);
+                return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(session), secure, (session.expiresAt - deps.now().getTime()) / 1_000));
+            }
+            catch (error) {
+                // The exception is the only thing that still holds the reason: what the reader gets is a
+                // fixed marker, and a marker names a KIND of failure, never its cause (#93).
+                reportUnexpectedError(error);
+                // `portal_sign_in_failed` is the marker `/auth/connect` already writes for exactly this
+                // situation, so nothing new is invented here and no screen has to learn a word. The Tools
+                // screen reads it as "the sign-in is broken", which is true of both handoffs — a Gate login
+                // that could not be exchanged is no more the reader's doing than a portal one.
+                if (pending.kind === "connection-pending") {
+                    // Every other way out of the callback puts the parked Intel session back, and so does
+                    // this one: the portal attempt must never cost somebody their Intel login.
+                    return await restore(pending.user, pending.returnTo, withConnectError(pending.returnTo, "portal_sign_in_failed"));
+                }
+                // A Gate login handoff parks nothing, so there is no session to put back — and the cookie
+                // is spent either way: its verifier belongs to an authorization code that has now been
+                // used. Clearing it is what makes the next attempt start a fresh one instead of replaying
+                // this one.
+                return redirect(withConnectError(pending.returnTo, "portal_sign_in_failed"), sessionCookie("", secure, 0));
+            }
+        },
+        logout() {
+            return redirect("/", sessionCookie("", secure, 0));
+        },
+        async resolve(headers) {
+            const encoded = cookieValue(headers);
+            const session = encoded ? await deps.sessions.open(encoded) : null;
+            if (session?.kind !== "user")
+                return null;
+            return session.expiresAt > deps.now().getTime() + 30_000
+                ? { bearer: session.accessToken }
+                : null;
+        },
+    };
+}

package/dist/auth/auth.types.d.ts

@@ -0,0 +1,108 @@
+import type { PortalTokenStore } from "../tools/tools.types.js";
+export interface OAuthTokens {
+    accessToken: string;
+    expiresIn: number;
+    refreshToken?: string;
+}
+export interface OAuthPort {
+    discoverResource(resourceUrl: string): Promise<{
+        resource: string;
+        issuer: string;
+        scope?: string;
+    }>;
+    register(input: {
+        issuer: string;
+        redirectUri: string;
+        clientName: string;
+        resource: string;
+        scope?: string;
+    }): Promise<string>;
+    authorizationUrl(input: {
+        issuer: string;
+        clientId: string;
+        redirectUri: string;
+        resource: string;
+        codeChallenge: string;
+        state: string;
+        scope?: string;
+        prompt?: "none";
+    }): Promise<URL>;
+    exchange(input: {
+        issuer: string;
+        clientId: string;
+        callbackUrl: URL;
+        redirectUri: string;
+        resource: string;
+        codeVerifier: string;
+        state: string;
+    }): Promise<OAuthTokens>;
+    refresh(input: {
+        issuer: string;
+        clientId: string;
+        resource: string;
+        refreshToken: string;
+    }): Promise<OAuthTokens>;
+}
+export interface OAuthClientStore {
+    get(issuer: string, redirectUri: string): Promise<string | null>;
+    put(input: {
+        issuer: string;
+        redirectUri: string;
+        clientId: string;
+        createdAt: string;
+    }): Promise<string>;
+}
+export interface UserAuthSession {
+    version: 1;
+    kind: "user";
+    clientId: string;
+    accessToken: string;
+    expiresAt: number;
+}
+export type AuthSession = {
+    version: 1;
+    kind: "pending";
+    clientId: string;
+    codeVerifier: string;
+    state: string;
+    returnTo: string;
+    expiresAt: number;
+} | {
+    version: 1;
+    kind: "connection-pending";
+    clientId: string;
+    codeVerifier: string;
+    state: string;
+    returnTo: string;
+    issuer: string;
+    resource: string;
+    userId: string;
+    user: UserAuthSession;
+    silent: boolean;
+    resumed: boolean;
+    expiresAt: number;
+} | UserAuthSession;
+export interface SessionCodec {
+    seal(session: AuthSession): Promise<string>;
+    open(value: string): Promise<AuthSession | null>;
+}
+export interface BrowserAuthDeps {
+    baseUrl: string;
+    gateUrl: string;
+    resource: string;
+    oauth: OAuthPort;
+    clients: OAuthClientStore;
+    sessions: SessionCodec;
+    portalUrl: string | null;
+    portalTokens: Pick<PortalTokenStore, "write">;
+    now(): Date;
+}
+export interface BrowserAuth {
+    login(requestUrl: URL): Promise<Response>;
+    connect(requestUrl: URL, headers: Headers, userId: string): Promise<Response>;
+    callback(requestUrl: URL, headers: Headers): Promise<Response>;
+    logout(): Response;
+    resolve(headers: Headers): Promise<{
+        bearer: string;
+    } | null>;
+}

package/dist/auth/auth.types.js

@@ -0,0 +1 @@
+export {};

package/dist/boards/boards.d.ts

@@ -0,0 +1,44 @@
+import type { BoardDeps, BoardService } from "./boards.types.js";
+/**
+ * What a board with no configuration answers with. A board is usable the moment it is created, and
+ * nothing asks whoever made it to define columns before filing the first card.
+ *
+ * ⚠️ **This is the FALLBACK, not what a board made through the application gets.** Columns are
+ * shared data: two people on one board must read the same names, and the settings dialog edits one
+ * list. So the application writes them at creation, in the language of whoever created it (#675),
+ * and from then on they are data anybody can rename. This list only answers for a board nobody
+ * configured — one made over MCP, or one whose seeding did not land.
+ */
+/**
+ * ⚠️ **The four start coloured, and the colours mean something** (Jack's decision 2026-08-22): grey
+ * for what is only lying there, yellow for what is ready, orange for what is being worked on, green
+ * for what is done. That order is the one people already read without a legend, which is the whole
+ * reason a default is worth having — a board that starts grey teaches nothing, and one that starts
+ * in arbitrary colours teaches something false.
+ *
+ * They are a suggestion, not a setting: every one of them can be overwritten, and a board that has
+ * been recoloured keeps its own values.
+ */
+export declare const DEFAULT_COLUMNS: readonly [{
+    readonly id: "backlog";
+    readonly title: "Backlog";
+    readonly terminal: false;
+    readonly color: "#9ca3af";
+}, {
+    readonly id: "todo";
+    readonly title: "Offen";
+    readonly terminal: false;
+    readonly color: "#eab308";
+}, {
+    readonly id: "doing";
+    readonly title: "Läuft";
+    readonly terminal: false;
+    readonly color: "#f97316";
+}, {
+    readonly id: "done";
+    readonly title: "Fertig";
+    readonly terminal: true;
+    readonly color: "#22c55e";
+}];
+export declare const FIRST_DEFAULT_COLUMN: "backlog";
+export declare function createBoards(deps: BoardDeps): BoardService;