co-maintainer 0.4.0-beta.1

package/dist/src/server/app.js

@@ -0,0 +1,147 @@
+/** `createApp(deps).fetch(request)` — no port, no sockets, so it is testable
+ * with a plain `Request`. */
+import { VERSION } from "../version.js";
+import { errorResponse } from "./errors.js";
+import { hasCsrfHeader, login, logout, readSessionToken, sessionCookieHeader, verifySession, } from "./auth.js";
+import { readConfig } from "../config.js";
+import { listJobs } from "../store/jobs.js";
+import { handleJobsRoute } from "./api/jobs.js";
+import { handleReposRoute } from "./api/repos.js";
+import { handleInstallationsRoute } from "./api/installations.js";
+import { handleSettingsRoute } from "./api/settings.js";
+import { handleActivityRoute } from "./api/activity.js";
+import { handleAnalyticsRoute } from "./api/analytics.js";
+import { handleRemoteTokensRoute } from "./api/remote_tokens.js";
+import { handleRemoteRoute } from "../remote/server/routes.js";
+import { handleWebhookRequest } from "./webhook/index.js";
+import { handlePageRequest } from "./pages/router.js";
+function setupStatus() {
+    const config = readConfig();
+    const ai = Boolean(config.ai && config.ai !== "none" && config.token);
+    const github = Boolean(config.auth === "gh" || (config.auth === "pat" && config.githubPat));
+    const app = Boolean(config.githubAppId && config.githubAppPrivateKey);
+    const missing = [
+        !ai && "ai",
+        !github && "github",
+        !app && "github app",
+    ].filter((item) => Boolean(item));
+    return { setup: { ai, github, app }, missing };
+}
+async function requireSession(request) {
+    const token = readSessionToken(request);
+    if (!token)
+        return undefined;
+    return await verifySession(token);
+}
+async function handleLogin(request, deps, ip) {
+    if (deps.auth?.password === false) {
+        return errorResponse(403, "password_disabled", "password sign-in is disabled");
+    }
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch {
+        return errorResponse(400, "bad_request", "expected a JSON body");
+    }
+    const result = await login(String(body.password ?? ""), deps.password, ip);
+    if (!result)
+        return errorResponse(401, "unauthorized", "wrong password");
+    return Response.json(result, {
+        headers: {
+            "set-cookie": sessionCookieHeader(result.token, Boolean(deps.secureCookie)),
+        },
+    });
+}
+async function handleLogout(request) {
+    const token = readSessionToken(request);
+    if (token)
+        await logout(token);
+    return new Response(null, { status: 204 });
+}
+function health() {
+    let queue = { queued: 0, running: 0 };
+    let db = "ok";
+    try {
+        queue = {
+            queued: listJobs({ status: "queued" }).length,
+            running: listJobs({ status: "running" }).length,
+        };
+    }
+    catch {
+        db = "unavailable";
+    }
+    return Response.json({
+        ok: true,
+        version: VERSION,
+        queue,
+        db,
+    });
+}
+export function createApp(deps) {
+    return {
+        async fetch(request, remoteAddr = "unknown") {
+            const url = new URL(request.url);
+            const mutating = ["POST", "PATCH", "PUT", "DELETE"].includes(request.method);
+            if (url.pathname === "/api/health" && request.method === "GET") {
+                return health();
+            }
+            if (url.pathname === "/github/webhook" && request.method === "POST") {
+                return await handleWebhookRequest(request, deps.webhookSecret);
+            }
+            const page = await handlePageRequest(request, deps, remoteAddr);
+            if (page)
+                return page;
+            if (url.pathname.startsWith("/api/remote/")) {
+                return await handleRemoteRoute(request, url, remoteAddr);
+            }
+            if (url.pathname.startsWith("/api/")) {
+                if (mutating && !hasCsrfHeader(request)) {
+                    return errorResponse(403, "csrf", `every mutating request needs the X-Requested-With header`);
+                }
+                if (url.pathname === "/api/login" && request.method === "POST") {
+                    return await handleLogin(request, deps, remoteAddr);
+                }
+                const session = await requireSession(request);
+                if (!session) {
+                    return errorResponse(401, "unauthorized", "sign in required");
+                }
+                if (deps.inject500 && mutating && url.pathname !== "/api/login") {
+                    return errorResponse(500, "injected", "The request failed.");
+                }
+                if (url.pathname === "/api/logout" && request.method === "POST") {
+                    return await handleLogout(request);
+                }
+                if (url.pathname === "/api/me" && request.method === "GET") {
+                    return Response.json({
+                        username: session.username,
+                        ...setupStatus(),
+                    });
+                }
+                if (url.pathname.startsWith("/api/jobs")) {
+                    return handleJobsRoute(request, url);
+                }
+                if (url.pathname.startsWith("/api/repos")) {
+                    return await handleReposRoute(request, url, deps.githubApp);
+                }
+                if (url.pathname === "/api/installations") {
+                    return await handleInstallationsRoute(request, deps.githubApp);
+                }
+                if (url.pathname.startsWith("/api/settings")) {
+                    return await handleSettingsRoute(request, url, deps.webhookUrl ?? "");
+                }
+                if (url.pathname.startsWith("/api/activity")) {
+                    return handleActivityRoute(request, url);
+                }
+                if (url.pathname === "/api/analytics") {
+                    return handleAnalyticsRoute(request, url);
+                }
+                if (url.pathname.startsWith("/api/remote-tokens")) {
+                    return await handleRemoteTokensRoute(request, url);
+                }
+                return errorResponse(404, "not_found", `no route for ${url.pathname}`);
+            }
+            return errorResponse(404, "not_found", `no route for ${url.pathname}`);
+        },
+    };
+}

package/dist/src/server/assets.d.ts

@@ -0,0 +1,3 @@
+export declare function handleStyles(): Promise<Response>;
+export declare function handleLogo(): Promise<Response>;
+export declare function handleClient(): Promise<Response>;

package/dist/src/server/assets.js

@@ -0,0 +1,21 @@
+import { client } from "./pages/client.js";
+import { logo } from "./logo.js";
+import { styles } from "./pages/styles.js";
+export async function handleStyles() {
+    return new Response(styles, {
+        headers: { "content-type": "text/css; charset=utf-8" },
+    });
+}
+export async function handleLogo() {
+    return new Response(logo, {
+        headers: {
+            "content-type": "image/png",
+            "cache-control": "public, max-age=86400",
+        },
+    });
+}
+export async function handleClient() {
+    return new Response(client, {
+        headers: { "content-type": "text/javascript; charset=utf-8" },
+    });
+}

package/dist/src/server/auth.d.ts

@@ -0,0 +1,44 @@
+export declare const USERNAME = "admin";
+export declare const CSRF_HEADER = "x-requested-with";
+export declare const CSRF_VALUE = "co-maintainer";
+export declare const SESSION_COOKIE = "cm";
+export declare const OAUTH_STATE_COOKIE = "cm_oauth_state";
+/** Which sign-in methods a running `serve` accepts. Resolved once at
+ * startup (CLI flag, falling back to config) and threaded through
+ * `AppDeps`/`PageDeps` — every route reads the same resolved value. */
+export type AuthMethods = {
+    password: boolean;
+    github: boolean;
+};
+export declare function randomToken(): string;
+export declare function recordAuthFailure(ip: string): void;
+export declare function isLockedOut(ip: string): boolean;
+export declare function hasCsrfHeader(request: Request): boolean;
+export type LoginResult = {
+    token: string;
+    username: string;
+    expiresAt: string;
+};
+/** A locked-out attempt is indistinguishable from a wrong password to the
+ * caller — both return `undefined` — so a probe gains nothing either way. */
+export declare function login(password: string, expected: string, ip: string): Promise<LoginResult | undefined>;
+/** Issues a session for the one dashboard identity, bypassing the password
+ * check — used after GitHub OAuth has already verified the caller. */
+export declare function createSession(): Promise<LoginResult>;
+export declare function verifySession(token: string): Promise<{
+    username: string;
+} | undefined>;
+export declare function logout(token: string): Promise<void>;
+export declare function readBearerToken(request: Request): string | undefined;
+export declare function readSessionToken(request: Request): string | undefined;
+export declare function sessionCookieHeader(token: string, secure: boolean): string;
+export declare function clearSessionCookieHeader(secure: boolean): string;
+/** The GitHub OAuth `state` param, plus the post-login `next` path,
+ * round-tripped through an HttpOnly cookie instead of server memory — one
+ * admin, one in-flight login at a time, so a cookie is all this needs. */
+export declare function readOauthState(request: Request): {
+    state: string;
+    next: string;
+} | undefined;
+export declare function oauthStateCookieHeader(state: string, next: string, secure: boolean): string;
+export declare function clearOauthStateCookieHeader(secure: boolean): string;

package/dist/src/server/auth.js

@@ -0,0 +1,188 @@
+/** Only a token's hash ever reaches `store/sessions.ts`; the raw token is
+ * handed back once, at login, and never stored. */
+import { deleteSession, getSession, insertSession } from "../store/sessions.js";
+const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const LOCKOUT_THRESHOLD = 5;
+const LOCKOUT_WINDOW_MS = 10 * 60 * 1000;
+const LOCKOUT_DURATION_MS = 10 * 60 * 1000;
+export const USERNAME = "admin";
+export const CSRF_HEADER = "x-requested-with";
+export const CSRF_VALUE = "co-maintainer";
+export const SESSION_COOKIE = "cm";
+export const OAUTH_STATE_COOKIE = "cm_oauth_state";
+const SESSION_TTL_SEC = 7 * 24 * 60 * 60;
+const OAUTH_STATE_TTL_SEC = 600;
+async function sha256Hex(value) {
+    const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    return [...new Uint8Array(bytes)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+/** Hashing both sides to a fixed-length digest before comparing means the
+ * XOR loop's timing depends on neither the password's length nor content,
+ * closing the timing side-channel a plain `!==` leaves open. */
+async function constantTimeEqual(a, b) {
+    const [ah, bh] = await Promise.all([sha256Hex(a), sha256Hex(b)]);
+    let diff = 0;
+    for (let index = 0; index < ah.length; index++) {
+        diff |= ah.charCodeAt(index) ^ bh.charCodeAt(index);
+    }
+    return diff === 0;
+}
+export function randomToken() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+// ponytail: an in-memory Map, one entry per distinct IP that has ever failed
+// a login. Fine for a single self-hosted admin; add eviction if this ever
+// needs to survive a hostile flood of spoofed source IPs.
+const attempts = new Map();
+export function recordAuthFailure(ip) {
+    recordFailure(ip);
+}
+export function isLockedOut(ip) {
+    const attempt = attempts.get(ip);
+    if (!attempt?.lockedUntil)
+        return false;
+    if (Date.now() >= attempt.lockedUntil) {
+        attempts.delete(ip);
+        return false;
+    }
+    return true;
+}
+function recordFailure(ip) {
+    const now = Date.now();
+    const attempt = attempts.get(ip);
+    if (!attempt || now - attempt.firstFailureAt > LOCKOUT_WINDOW_MS) {
+        attempts.set(ip, { failures: 1, firstFailureAt: now });
+        return;
+    }
+    attempt.failures++;
+    if (attempt.failures >= LOCKOUT_THRESHOLD) {
+        attempt.lockedUntil = now + LOCKOUT_DURATION_MS;
+    }
+}
+function recordSuccess(ip) {
+    attempts.delete(ip);
+}
+export function hasCsrfHeader(request) {
+    return request.headers.get(CSRF_HEADER) === CSRF_VALUE;
+}
+/** A locked-out attempt is indistinguishable from a wrong password to the
+ * caller — both return `undefined` — so a probe gains nothing either way. */
+export async function login(password, expected, ip) {
+    if (isLockedOut(ip) || !(await constantTimeEqual(password, expected))) {
+        recordFailure(ip);
+        return undefined;
+    }
+    recordSuccess(ip);
+    return await createSession();
+}
+/** Issues a session for the one dashboard identity, bypassing the password
+ * check — used after GitHub OAuth has already verified the caller. */
+export async function createSession() {
+    const token = randomToken();
+    const expiresAt = new Date(Date.now() + SESSION_TTL_MS).toISOString();
+    insertSession(await sha256Hex(token), USERNAME, expiresAt);
+    return { token, username: USERNAME, expiresAt };
+}
+export async function verifySession(token) {
+    const session = getSession(await sha256Hex(token));
+    return session ? { username: session.username } : undefined;
+}
+export async function logout(token) {
+    deleteSession(await sha256Hex(token));
+}
+function readCookie(request, name) {
+    const cookie = request.headers.get("cookie") ?? "";
+    for (const part of cookie.split(";")) {
+        const trimmed = part.trim();
+        const eq = trimmed.indexOf("=");
+        if (eq === -1)
+            continue;
+        if (trimmed.slice(0, eq) === name)
+            return trimmed.slice(eq + 1);
+    }
+}
+export function readBearerToken(request) {
+    const header = request.headers.get("authorization") ?? "";
+    if (!header.startsWith("Bearer "))
+        return undefined;
+    const token = header.slice("Bearer ".length).trim();
+    return token || undefined;
+}
+export function readSessionToken(request) {
+    const bearer = readBearerToken(request);
+    if (bearer)
+        return bearer;
+    return readCookie(request, SESSION_COOKIE);
+}
+export function sessionCookieHeader(token, secure) {
+    const flags = [
+        `${SESSION_COOKIE}=${token}`,
+        "HttpOnly",
+        "SameSite=Lax",
+        "Path=/",
+        `Max-Age=${SESSION_TTL_SEC}`,
+    ];
+    if (secure)
+        flags.push("Secure");
+    return flags.join("; ");
+}
+export function clearSessionCookieHeader(secure) {
+    const flags = [
+        `${SESSION_COOKIE}=`,
+        "HttpOnly",
+        "SameSite=Lax",
+        "Path=/",
+        "Max-Age=0",
+    ];
+    if (secure)
+        flags.push("Secure");
+    return flags.join("; ");
+}
+/** The GitHub OAuth `state` param, plus the post-login `next` path,
+ * round-tripped through an HttpOnly cookie instead of server memory — one
+ * admin, one in-flight login at a time, so a cookie is all this needs. */
+export function readOauthState(request) {
+    const value = readCookie(request, OAUTH_STATE_COOKIE);
+    if (!value)
+        return undefined;
+    const sep = value.indexOf(":");
+    if (sep === -1)
+        return { state: value, next: "/" };
+    try {
+        return {
+            state: value.slice(0, sep),
+            next: decodeURIComponent(value.slice(sep + 1)),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function oauthStateCookieHeader(state, next, secure) {
+    const flags = [
+        `${OAUTH_STATE_COOKIE}=${state}:${encodeURIComponent(next)}`,
+        "HttpOnly",
+        "SameSite=Lax",
+        "Path=/",
+        `Max-Age=${OAUTH_STATE_TTL_SEC}`,
+    ];
+    if (secure)
+        flags.push("Secure");
+    return flags.join("; ");
+}
+export function clearOauthStateCookieHeader(secure) {
+    const flags = [
+        `${OAUTH_STATE_COOKIE}=`,
+        "HttpOnly",
+        "SameSite=Lax",
+        "Path=/",
+        "Max-Age=0",
+    ];
+    if (secure)
+        flags.push("Secure");
+    return flags.join("; ");
+}

package/dist/src/server/errors.d.ts

@@ -0,0 +1,8 @@
+/** The one error shape every `/api/*` response uses — see PLAN.md Section 7. */
+export type ApiError = {
+    code: string;
+    message: string;
+    detail?: unknown;
+    requestId: string;
+};
+export declare function errorResponse(status: number, code: string, message: string, detail?: unknown): Response;

package/dist/src/server/errors.js

@@ -0,0 +1,10 @@
+export function errorResponse(status, code, message, detail) {
+    const requestId = crypto.randomUUID();
+    const error = detail === undefined
+        ? { code, message, requestId }
+        : { code, message, detail, requestId };
+    return new Response(JSON.stringify({ error }), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}

package/dist/src/server/http.d.ts

@@ -0,0 +1,8 @@
+export type FetchApp = (request: Request, remoteAddr?: string) => Promise<Response> | Response;
+export type HttpServer = {
+    port: number;
+    shutdown: () => Promise<void>;
+    finished: Promise<void>;
+};
+/** Starts an HTTP server that hands each request to `app`. */
+export declare function serveHttp(app: FetchApp, port: number): HttpServer;

package/dist/src/server/http.js

@@ -0,0 +1,117 @@
+/** A manual `node:http` ↔ `fetch` bridge (plan §2 HTTP).
+ *
+ * The app is written against the Web `Request`/`Response` types, which Deno
+ * served natively. Node has both types but no server that speaks them
+ * directly, so this translates per request and streams responses — including
+ * the SSE job feed — instead of buffering them. */
+import { createServer, } from "node:http";
+import { Readable } from "node:stream";
+function requestHeaders(req) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value))
+            for (const item of value)
+                headers.append(name, item);
+        else
+            headers.set(name, value);
+    }
+    return headers;
+}
+/** Node's `IncomingMessage` is a Node stream; `fetch` wants a Web body. A
+ * GET/HEAD has none, and passing `undefined` is required there — a body on a
+ * GET makes undici throw. */
+function requestBody(req, method) {
+    if (method === "GET" || method === "HEAD")
+        return undefined;
+    return Readable.toWeb(req);
+}
+function toFetchRequest(req, secure) {
+    const method = req.method ?? "GET";
+    const host = req.headers.host ?? "localhost";
+    const url = new URL(req.url ?? "/", `${secure ? "https" : "http"}://${host}`);
+    return new Request(url, {
+        method,
+        headers: requestHeaders(req),
+        body: requestBody(req, method),
+        // Required by undici whenever a stream body is attached.
+        duplex: "half",
+    });
+}
+async function writeResponse(res, response) {
+    res.statusCode = response.status;
+    for (const [name, value] of response.headers) {
+        // `set-cookie` repeats, and Node needs each as its own array entry.
+        if (name === "set-cookie")
+            res.appendHeader(name, value);
+        else
+            res.setHeader(name, value);
+    }
+    if (!response.body) {
+        res.end();
+        return;
+    }
+    const reader = response.body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            // Backpressure: pause until the socket drains before reading more, so
+            // a slow client cannot balloon memory (matters for SSE).
+            if (!res.write(value)) {
+                await new Promise((resolve) => res.once("drain", resolve));
+            }
+        }
+        res.end();
+    }
+    catch {
+        res.destroy();
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/** Starts an HTTP server that hands each request to `app`. */
+export function serveHttp(app, port) {
+    let resolveFinished;
+    const finished = new Promise((resolve) => {
+        resolveFinished = resolve;
+    });
+    const server = createServer((req, res) => {
+        const remoteAddr = req.socket.remoteAddress;
+        void (async () => {
+            try {
+                const request = toFetchRequest(req, false);
+                const response = await app(request, remoteAddr);
+                await writeResponse(res, response);
+            }
+            catch (error) {
+                if (!res.headersSent) {
+                    res.statusCode = 500;
+                    res.setHeader("content-type", "text/plain");
+                    res.end(`Internal Server Error: ${String(error)}`);
+                }
+                else {
+                    res.destroy();
+                }
+            }
+        })();
+    });
+    server.listen(port);
+    return {
+        port,
+        shutdown: () => new Promise((resolve) => {
+            // SSE streams never end on their own, so `close()` alone would wait
+            // forever. Tear the connections down, then wait for the close event
+            // so the listening socket is actually released before we return.
+            server.closeAllConnections();
+            server.close(() => {
+                resolveFinished();
+                resolve();
+            });
+        }),
+        finished,
+    };
+}

package/dist/src/server/logo.d.ts

@@ -0,0 +1 @@
+export declare const logo: Uint8Array<ArrayBuffer>;