ankka-console 0.10.0

package/dist/runtime.d.ts

@@ -0,0 +1,28 @@
+import { Issuer } from "./auth/oidc.ts";
+import { SealedFlash, type SessionStore } from "./session/cookie-store.ts";
+import { SessionTokenSource, type TokenSource } from "./session/token-source.ts";
+import { type FetchLike } from "./server/transport.ts";
+import type { ConsoleOptions } from "./options.ts";
+import type { DeployTokenCreated } from "./client/schemas.ts";
+export interface ConsoleRuntime {
+    options: ConsoleOptions;
+    mount: string;
+    secure: boolean;
+    store: SessionStore;
+    tokens: TokenSource;
+    /** Present when the package runs its own sign-in. */
+    issuer?: () => Promise<Issuer>;
+    sessionTokens?: SessionTokenSource;
+    controlPlaneFetch: FetchLike;
+    /** A deploy token's secret, carried across one redirect and shown once. */
+    tokenFlash: SealedFlash<DeployTokenCreated>;
+    pendingLogin: SealedFlash<{
+        state: string;
+        nonce: string;
+        verifier: string;
+        returnTo: string;
+    }>;
+    log: (line: Record<string, unknown>) => void;
+}
+export declare const normaliseMount: (mount: string | undefined) => string;
+export declare function createRuntime(options: ConsoleOptions): ConsoleRuntime;

package/dist/runtime.js

@@ -0,0 +1,77 @@
+/**
+ * What one console process holds for its whole life, built once from its options: the identity
+ * provider's configuration, the session store, the access token cache, and the transports.
+ */
+import { ControlPlaneClient } from "./client/control-plane.js";
+import { Issuer } from "./auth/oidc.js";
+import { SealedCookieSessionStore, SealedFlash } from "./session/cookie-store.js";
+import { TokenCache } from "./session/token-cache.js";
+import { SessionTokenSource } from "./session/token-source.js";
+import { tlsFetch } from "./server/transport.js";
+export const normaliseMount = (mount) => {
+    const m = (mount ?? "/").trim();
+    const withLead = m.startsWith("/") ? m : `/${m}`;
+    return withLead.endsWith("/") ? withLead : `${withLead}/`;
+};
+export function createRuntime(options) {
+    const secure = options.publicOrigin.startsWith("https:");
+    const secret = options.sessionSecret;
+    if (!secret && (!options.session || !options.tokens)) {
+        throw new Error("sessionSecret is required unless both a session store and a token source are supplied");
+    }
+    const store = options.session ?? new SealedCookieSessionStore({ secret: secret, secure });
+    const controlPlaneFetch = tlsFetch(options.controlPlane.tls);
+    const authFetch = tlsFetch(options.auth.ca ? { ca: options.auth.ca } : undefined);
+    let issuer;
+    let sessionTokens;
+    let tokens;
+    if (options.tokens) {
+        tokens = options.tokens;
+    }
+    else {
+        // The issuer the console trusts is the one the control plane trusts: asked of the control plane
+        // once, unless the host named it.
+        let resolved;
+        issuer = () => {
+            if (!resolved) {
+                resolved = (async () => {
+                    const name = options.auth.issuer ??
+                        (await new ControlPlaneClient({ baseUrl: options.controlPlane.url, bearer: async () => null, transport: controlPlaneFetch }).authDiscovery())
+                            .issuer;
+                    return new Issuer({
+                        issuer: name,
+                        clientId: options.auth.clientId,
+                        clientSecret: options.auth.clientSecret,
+                        backchannelUrl: options.auth.backchannelUrl,
+                        fetch: authFetch,
+                        allowInsecure: options.auth.allowInsecure,
+                    });
+                })().catch((e) => {
+                    resolved = undefined;
+                    throw e;
+                });
+            }
+            return resolved;
+        };
+        const getIssuer = issuer;
+        sessionTokens = new SessionTokenSource({
+            store,
+            cache: new TokenCache(),
+            issuer: { refresh: async (refreshToken) => (await getIssuer()).refresh(refreshToken) },
+        });
+        tokens = sessionTokens;
+    }
+    return {
+        options,
+        mount: normaliseMount(options.mount),
+        secure,
+        store,
+        tokens,
+        issuer,
+        sessionTokens,
+        controlPlaneFetch,
+        tokenFlash: new SealedFlash({ secret: secret ?? "unused", secure, name: "ankka_console_flash", maxAgeSeconds: 60 }),
+        pendingLogin: new SealedFlash({ secret: secret ?? "unused", secure, name: "ankka_console_login", maxAgeSeconds: 600 }),
+        log: options.log ?? ((line) => process.stdout.write(JSON.stringify(line) + "\n")),
+    };
+}

package/dist/server/create-console-server.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The console's process: the app on one port and readiness on another.
+ *
+ * In a cluster (`ANKKA_CONSOLE_TLS_DIR` set) the app port is TLS with the certificate cert-manager
+ * issued for the console, re-read when it is renewed, and it serves only a client presenting a
+ * certificate from the same authority that names the gateway, `ankka://gateway`: nothing reaches the
+ * console except through the installation's front door. Readiness is plain HTTP on its own port,
+ * because the kubelet holds no certificate, and says yes only once the certificate is loaded, the
+ * app port is bound and the control plane has answered. Locally it is plain HTTP on one port.
+ */
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { ServerBuild } from "react-router";
+export declare const GatewayUri = "ankka://gateway";
+export interface ConsoleServerOptions {
+    build?: ServerBuild | (() => Promise<ServerBuild>);
+    /** In place of `build`: any request listener. The server's own tests use it. */
+    requestListener?: (req: IncomingMessage, res: ServerResponse) => void;
+    /** The client build: `build/client/` beside the server build. */
+    clientDir: string | URL;
+    env?: Record<string, string | undefined>;
+    /** How long to wait for the control plane at startup before refusing to start. */
+    startupTimeoutMs?: number;
+}
+export interface ConsoleServer {
+    app: Server;
+    probe?: Server;
+    url: string;
+    ready(): boolean;
+    close(): Promise<void>;
+}
+export declare function createConsoleServer(options: ConsoleServerOptions): Promise<ConsoleServer>;
+/** Runs the server until SIGTERM or SIGINT, then drains it and exits. */
+export declare function runConsoleServer(options: ConsoleServerOptions): Promise<void>;

package/dist/server/create-console-server.js

@@ -0,0 +1,203 @@
+/**
+ * The console's process: the app on one port and readiness on another.
+ *
+ * In a cluster (`ANKKA_CONSOLE_TLS_DIR` set) the app port is TLS with the certificate cert-manager
+ * issued for the console, re-read when it is renewed, and it serves only a client presenting a
+ * certificate from the same authority that names the gateway, `ankka://gateway`: nothing reaches the
+ * console except through the installation's front door. Readiness is plain HTTP on its own port,
+ * because the kubelet holds no certificate, and says yes only once the certificate is loaded, the
+ * app port is bound and the control plane has answered. Locally it is plain HTTP on one port.
+ */
+import { createServer as createHttpServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
+import { createReadStream, statSync } from "node:fs";
+import { extname, normalize, resolve, sep } from "node:path";
+import { createSecureContext } from "node:tls";
+import { fileURLToPath } from "node:url";
+import { createRequestListener } from "@react-router/node";
+import { ControlPlaneClient } from "../client/control-plane.js";
+import { closeAllStreams } from "../stream/registry.js";
+import { RotatingFiles, tlsFetch } from "./transport.js";
+export const GatewayUri = "ankka://gateway";
+const types = {
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".json": "application/json",
+    ".woff2": "font/woff2",
+    ".txt": "text/plain; charset=utf-8",
+};
+/** Serves a file from the client build, or answers `false` for the app to handle the request. */
+function staticFile(root, req, res) {
+    if (req.method !== "GET" && req.method !== "HEAD")
+        return false;
+    const path = decodeURIComponent(new URL(req.url ?? "/", "http://x").pathname);
+    if (path === "/" || path.endsWith("/"))
+        return false;
+    const file = resolve(root, "." + normalize(path));
+    if (!file.startsWith(root + sep))
+        return false;
+    let size;
+    try {
+        const stat = statSync(file);
+        if (!stat.isFile())
+            return false;
+        size = stat.size;
+    }
+    catch {
+        return false;
+    }
+    res.writeHead(200, {
+        "content-type": types[extname(file)] ?? "application/octet-stream",
+        "content-length": size,
+        // Fingerprinted by the build: they never change under the same name.
+        "cache-control": path.startsWith("/assets/") ? "public, max-age=31536000, immutable" : "public, max-age=300",
+    });
+    if (req.method === "HEAD")
+        res.end();
+    else
+        createReadStream(file).pipe(res);
+    return true;
+}
+function peerNamesGateway(req) {
+    const socket = req.socket;
+    if (typeof socket.getPeerCertificate !== "function")
+        return false;
+    const names = socket.getPeerCertificate()?.subjectaltname ?? "";
+    return names.split(",").map((n) => n.trim()).includes(`URI:${GatewayUri}`);
+}
+async function waitForControlPlane(url, fetchImpl, timeoutMs) {
+    const client = new ControlPlaneClient({ baseUrl: url, bearer: async () => null, transport: fetchImpl });
+    const deadline = Date.now() + timeoutMs;
+    let last;
+    while (Date.now() < deadline) {
+        try {
+            await client.authDiscovery();
+            return;
+        }
+        catch (e) {
+            last = e;
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+    }
+    throw new Error(`the control plane did not answer GET ${url}/auth: ${last instanceof Error ? last.message : String(last)}`);
+}
+export async function createConsoleServer(options) {
+    const env = options.env ?? process.env;
+    const tlsDir = env.ANKKA_CONSOLE_TLS_DIR?.trim();
+    const port = Number(env.ANKKA_CONSOLE_PORT ?? (tlsDir ? 9000 : 3000));
+    const probePort = env.ANKKA_CONSOLE_PROBE_PORT ? Number(env.ANKKA_CONSOLE_PROBE_PORT) : undefined;
+    const host = env.ANKKA_CONSOLE_HOST ?? (tlsDir ? "0.0.0.0" : "127.0.0.1");
+    const clientRoot = resolve(typeof options.clientDir === "string" ? options.clientDir : fileURLToPath(options.clientDir));
+    const cpUrl = env.ANKKA_CONSOLE_CONTROL_PLANE_URL ?? "http://localhost:9000";
+    const files = tlsDir ? { ca: `${tlsDir}/ca.crt`, cert: `${tlsDir}/tls.crt`, key: `${tlsDir}/tls.key` } : undefined;
+    if (tlsDir && !env.ANKKA_CONSOLE_AUTHORITY?.trim() && !options.requestListener) {
+        throw new Error("ANKKA_CONSOLE_AUTHORITY is not set: in a cluster the console must be told its own address");
+    }
+    let bound = false;
+    let controlPlaneAnswered = false;
+    let closing = false;
+    if (!options.build && !options.requestListener)
+        throw new Error("createConsoleServer needs the host's server build");
+    const listener = options.requestListener ??
+        createRequestListener({ build: options.build, mode: env.NODE_ENV === "development" ? "development" : "production" });
+    const handle = (req, res) => {
+        if (tlsDir && !peerNamesGateway(req)) {
+            res.writeHead(403, { "content-type": "text/plain" }).end("only the installation's gateway may call the console\n");
+            return;
+        }
+        if (staticFile(clientRoot, req, res))
+            return;
+        void listener(req, res);
+    };
+    let app;
+    let rotation;
+    if (files) {
+        const rotating = new RotatingFiles(files, 30_000);
+        const contextOf = () => {
+            const m = rotating.current();
+            return { version: m.version, context: createSecureContext({ key: m.key, cert: m.cert, ca: m.ca }) };
+        };
+        let current = contextOf();
+        const server = createHttpsServer({
+            key: rotating.current().key,
+            cert: rotating.current().cert,
+            ca: rotating.current().ca,
+            requestCert: true,
+            rejectUnauthorized: true,
+            minVersion: "TLSv1.2",
+        }, handle);
+        rotation = setInterval(() => {
+            const next = contextOf();
+            if (next.version !== current.version) {
+                current = next;
+                const m = rotating.current();
+                server.setSecureContext({ key: m.key, cert: m.cert, ca: m.ca, requestCert: true, rejectUnauthorized: true });
+            }
+        }, 30_000);
+        rotation.unref();
+        app = server;
+    }
+    else {
+        app = createHttpServer(handle);
+    }
+    // Streams send keepalives well inside this; a request that says nothing for longer is gone.
+    app.keepAliveTimeout = 65_000;
+    app.headersTimeout = 66_000;
+    await waitForControlPlane(cpUrl, tlsFetch(files), options.startupTimeoutMs ?? 60_000);
+    controlPlaneAnswered = true;
+    await new Promise((resolveListen, reject) => {
+        app.once("error", reject);
+        app.listen(port, host, () => {
+            bound = true;
+            resolveListen();
+        });
+    });
+    const ready = () => bound && controlPlaneAnswered && !closing;
+    let probe;
+    if (probePort !== undefined) {
+        probe = createHttpServer((req, res) => {
+            if (req.url === "/ready" || req.url === "/healthz") {
+                const ok = req.url === "/healthz" ? !closing : ready();
+                res.writeHead(ok ? 200 : 503, { "content-type": "text/plain" }).end(ok ? "ok\n" : "not ready\n");
+            }
+            else {
+                res.writeHead(404).end();
+            }
+        });
+        await new Promise((r) => probe.listen(probePort, host, r));
+    }
+    const address = app.address();
+    const actualPort = typeof address === "object" && address ? address.port : port;
+    const url = `${tlsDir ? "https" : "http"}://${host === "0.0.0.0" ? "localhost" : host}:${actualPort}`;
+    const close = async () => {
+        if (closing)
+            return;
+        closing = true;
+        if (rotation)
+            clearInterval(rotation);
+        // Streams are told first, so browsers reconnect to an instance that is staying.
+        closeAllStreams();
+        const closed = new Promise((r) => app.close(() => r()));
+        app.closeIdleConnections();
+        const deadline = new Promise((r) => setTimeout(() => (app.closeAllConnections(), r()), 10_000).unref());
+        await Promise.race([closed, deadline]);
+        if (probe)
+            await new Promise((r) => probe.close(() => r()));
+    };
+    return { app, probe, url, ready, close };
+}
+/** Runs the server until SIGTERM or SIGINT, then drains it and exits. */
+export async function runConsoleServer(options) {
+    const server = await createConsoleServer(options);
+    process.stdout.write(JSON.stringify({ at: new Date().toISOString(), event: "listening", url: server.url }) + "\n");
+    const stop = async (signal) => {
+        process.stdout.write(JSON.stringify({ at: new Date().toISOString(), event: "stopping", signal }) + "\n");
+        await server.close();
+        process.exit(0);
+    };
+    process.once("SIGTERM", () => void stop("SIGTERM"));
+    process.once("SIGINT", () => void stop("SIGINT"));
+}

package/dist/server/index.d.ts

@@ -0,0 +1,15 @@
+export { consoleRoutes } from "../routes.ts";
+export type { ConsoleRoutesOptions, RouteConfigEntry } from "../routes.ts";
+export { consoleMiddleware } from "../middleware.ts";
+export { consoleOptionsFromEnv } from "../options.ts";
+export type { ConsoleOptions } from "../options.ts";
+export { consoleContext, useConsoleContext } from "../context.ts";
+export type { ConsoleContext } from "../context.ts";
+export { SealedCookieSessionStore } from "../session/cookie-store.ts";
+export type { Session, SessionStore } from "../session/cookie-store.ts";
+export { SessionTokenSource } from "../session/token-source.ts";
+export type { TokenSource } from "../session/token-source.ts";
+export { createConsoleServer, runConsoleServer, GatewayUri } from "./create-console-server.ts";
+export type { ConsoleServer, ConsoleServerOptions } from "./create-console-server.ts";
+export { tlsFetch, RotatingFiles } from "./transport.ts";
+export type { FetchLike, TlsFiles } from "./transport.ts";

package/dist/server/index.js

@@ -0,0 +1,13 @@
+// The server-side entry point: mounting the console in a host, and running it.
+// The routes table, for the host's `app/routes.ts`.
+export { consoleRoutes } from "../routes.js";
+// The middleware and its options, for the host's root route.
+export { consoleMiddleware } from "../middleware.js";
+export { consoleOptionsFromEnv } from "../options.js";
+export { consoleContext, useConsoleContext } from "../context.js";
+// Keeping sessions another way.
+export { SealedCookieSessionStore } from "../session/cookie-store.js";
+export { SessionTokenSource } from "../session/token-source.js";
+// The process.
+export { createConsoleServer, runConsoleServer, GatewayUri } from "./create-console-server.js";
+export { tlsFetch, RotatingFiles } from "./transport.js";

package/dist/server/transport.d.ts

@@ -0,0 +1,25 @@
+export interface TlsFiles {
+    /** The authority to trust; none means the system's roots. */
+    ca?: string;
+    /** The certificate and key to present as a client. */
+    cert?: string;
+    key?: string;
+}
+/** Reads a set of PEM files, and reads them again when any has changed since, at most once every `pollMs`. */
+export declare class RotatingFiles {
+    #private;
+    constructor(files: TlsFiles, pollMs?: number);
+    /** The current contents, and a number that changes whenever they do. */
+    current(): {
+        ca?: Buffer;
+        cert?: Buffer;
+        key?: Buffer;
+        version: number;
+    };
+}
+export type FetchLike = (url: string | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * `fetch`, over TLS material that is re-read on rotation. With no files it is the platform's own
+ * `fetch`. Bodies are buffered on the way out; every call this is used for is small JSON or a form.
+ */
+export declare function tlsFetch(files: TlsFiles | undefined, pollMs?: number): FetchLike;

package/dist/server/transport.js

@@ -0,0 +1,97 @@
+/**
+ * A `fetch` for the console's outbound calls, over `node:https` so it can trust one authority and
+ * present one certificate — the control plane requires the console's own certificate in a cluster,
+ * and the identity provider's in-cluster address is verified against the installation's service
+ * authority. The certificate files are re-read when cert-manager rewrites them.
+ */
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { readFileSync, statSync } from "node:fs";
+import { Readable } from "node:stream";
+/** Reads a set of PEM files, and reads them again when any has changed since, at most once every `pollMs`. */
+export class RotatingFiles {
+    #files;
+    #pollMs;
+    #checkedAt = 0;
+    #stamp = "";
+    #loaded = {};
+    #version = 0;
+    constructor(files, pollMs = 30_000) {
+        this.#files = files;
+        this.#pollMs = pollMs;
+    }
+    /** The current contents, and a number that changes whenever they do. */
+    current() {
+        const now = Date.now();
+        if (now - this.#checkedAt >= this.#pollMs || this.#version === 0) {
+            this.#checkedAt = now;
+            const paths = [this.#files.ca, this.#files.cert, this.#files.key].filter((p) => !!p);
+            const stamp = paths.map((p) => `${p}:${statSync(p).mtimeMs}`).join("|");
+            if (stamp !== this.#stamp) {
+                this.#loaded = {
+                    ca: this.#files.ca ? readFileSync(this.#files.ca) : undefined,
+                    cert: this.#files.cert ? readFileSync(this.#files.cert) : undefined,
+                    key: this.#files.key ? readFileSync(this.#files.key) : undefined,
+                };
+                this.#stamp = stamp;
+                this.#version += 1;
+            }
+        }
+        return { ...this.#loaded, version: this.#version };
+    }
+}
+/**
+ * `fetch`, over TLS material that is re-read on rotation. With no files it is the platform's own
+ * `fetch`. Bodies are buffered on the way out; every call this is used for is small JSON or a form.
+ */
+export function tlsFetch(files, pollMs) {
+    if (!files || (!files.ca && !files.cert))
+        return (url, init) => fetch(url, init);
+    const rotating = new RotatingFiles(files, pollMs);
+    return async (input, init = {}) => {
+        const url = new URL(String(input));
+        const material = rotating.current();
+        const headers = new Headers(init.headers);
+        let body;
+        if (init.body !== undefined && init.body !== null) {
+            body = Buffer.from(await new Response(init.body).arrayBuffer());
+            headers.set("content-length", String(body.length));
+        }
+        const options = {
+            method: init.method ?? "GET",
+            host: url.hostname,
+            port: url.port,
+            path: url.pathname + url.search,
+            headers: Object.fromEntries(headers.entries()),
+            ca: material.ca,
+            cert: material.cert,
+            key: material.key,
+            servername: url.hostname,
+            signal: init.signal ?? undefined,
+        };
+        const send = url.protocol === "https:" ? httpsRequest : httpRequest;
+        return new Promise((resolve, reject) => {
+            const req = send(options, (res) => {
+                const out = new Headers();
+                for (const [k, v] of Object.entries(res.headers)) {
+                    if (Array.isArray(v))
+                        v.forEach((x) => out.append(k, x));
+                    else if (v !== undefined)
+                        out.set(k, v);
+                }
+                const status = res.statusCode ?? 502;
+                const nullBody = status === 204 || status === 304 || options.method === "HEAD";
+                resolve(new Response(nullBody ? null : Readable.toWeb(res), {
+                    status,
+                    statusText: res.statusMessage,
+                    headers: out,
+                }));
+            });
+            req.on("error", reject);
+            if (body)
+                req.end(body);
+            else
+                req.end();
+        });
+    };
+}

package/dist/session/cookie-store.d.ts

@@ -0,0 +1,51 @@
+/** What a session is to the console: enough to obtain a fresh access token, and nothing more. */
+export interface Session {
+    refreshToken: string;
+    /** When this value was written, in epoch seconds. */
+    issuedAt: number;
+}
+/** Where sessions are kept. The sealed cookie is the default; a host with a database may keep them there. */
+export interface SessionStore {
+    read(request: Request): Promise<Session | null>;
+    /** Appends whatever the response needs — a `Set-Cookie`, typically — to `headers`. */
+    write(session: Session, headers: Headers): Promise<void>;
+    clear(headers: Headers): Promise<void>;
+}
+export interface SealedCookieSessionStoreOptions {
+    secret: string;
+    /** `true` in a cluster: the cookie is `__Host-`-prefixed and `Secure`. */
+    secure: boolean;
+    /** The realm's longest SSO session, in seconds; a cookie older than this is not opened. Default 36000. */
+    maxAgeSeconds?: number;
+    name?: string;
+}
+export declare class SealedCookieSessionStore implements SessionStore {
+    #private;
+    readonly name: string;
+    constructor(options: SealedCookieSessionStoreOptions);
+    read(request: Request): Promise<Session | null>;
+    write(session: Session, headers: Headers): Promise<void>;
+    clear(headers: Headers): Promise<void>;
+}
+/** A sign-in in progress: what the callback needs to finish it, sealed into a short-lived cookie. */
+export interface PendingLogin {
+    state: string;
+    nonce: string;
+    verifier: string;
+    returnTo: string;
+    iat: number;
+}
+/** A value shown on exactly one page after a redirect — a deploy token's secret, say. */
+export declare class SealedFlash<T> {
+    #private;
+    readonly name: string;
+    constructor(options: {
+        secret: string;
+        secure: boolean;
+        name: string;
+        maxAgeSeconds: number;
+    });
+    write(value: T, headers: Headers): Promise<void>;
+    /** The value, if one was written and has not expired; the cookie is cleared either way. */
+    take(request: Request, headers: Headers): Promise<T | null>;
+}

package/dist/session/cookie-store.js

@@ -0,0 +1,66 @@
+/**
+ * Sessions as sealed cookies. The console keeps no session store of its own: a session is the
+ * refresh token the identity provider issued, sealed into a cookie script cannot read, plus what the
+ * identity provider holds. Any instance can open any cookie, so any instance serves any session.
+ */
+import { cookieName, readCookie, serializeCookie } from "./cookies.js";
+import { deriveKey, seal, unseal } from "./seal.js";
+export class SealedCookieSessionStore {
+    name;
+    #secure;
+    #maxAge;
+    #key;
+    constructor(options) {
+        this.name = cookieName(options.name ?? "ankka_console", options.secure);
+        this.#secure = options.secure;
+        this.#maxAge = options.maxAgeSeconds ?? 36_000;
+        this.#key = deriveKey(options.secret, "ankka-console session v1");
+    }
+    async read(request) {
+        const raw = readCookie(request, this.name);
+        if (!raw)
+            return null;
+        const value = await unseal(raw, await this.#key, this.name);
+        if (!value || value.v !== 1 || typeof value.rt !== "string")
+            return null;
+        if (Date.now() / 1000 - value.iat > this.#maxAge)
+            return null;
+        return { refreshToken: value.rt, issuedAt: value.iat };
+    }
+    async write(session, headers) {
+        const value = { v: 1, rt: session.refreshToken, iat: session.issuedAt };
+        const sealed = await seal(value, await this.#key, this.name);
+        headers.append("set-cookie", serializeCookie(this.name, sealed, { maxAge: this.#maxAge, secure: this.#secure }));
+    }
+    async clear(headers) {
+        headers.append("set-cookie", serializeCookie(this.name, "", { maxAge: 0, secure: this.#secure }));
+    }
+}
+/** A value shown on exactly one page after a redirect — a deploy token's secret, say. */
+export class SealedFlash {
+    name;
+    #secure;
+    #maxAge;
+    #key;
+    constructor(options) {
+        this.name = cookieName(options.name, options.secure);
+        this.#secure = options.secure;
+        this.#maxAge = options.maxAgeSeconds;
+        this.#key = deriveKey(options.secret, `ankka-console ${options.name} v1`);
+    }
+    async write(value, headers) {
+        const sealed = await seal({ value, iat: Math.floor(Date.now() / 1000) }, await this.#key, this.name);
+        headers.append("set-cookie", serializeCookie(this.name, sealed, { maxAge: this.#maxAge, secure: this.#secure }));
+    }
+    /** The value, if one was written and has not expired; the cookie is cleared either way. */
+    async take(request, headers) {
+        const raw = readCookie(request, this.name);
+        if (!raw)
+            return null;
+        headers.append("set-cookie", serializeCookie(this.name, "", { maxAge: 0, secure: this.#secure }));
+        const opened = await unseal(raw, await this.#key, this.name);
+        if (!opened || Date.now() / 1000 - opened.iat > this.#maxAge)
+            return null;
+        return opened.value;
+    }
+}

package/dist/session/cookies.d.ts

@@ -0,0 +1,15 @@
+/** Reading and writing cookies on web `Request`/`Headers`, with the attributes the console needs. */
+export declare function readCookie(request: Request, name: string): string | undefined;
+export interface CookieAttributes {
+    maxAge: number;
+    secure: boolean;
+    /** `Lax` for the session: sent on top-level navigation to the console, never on a cross-site POST. */
+    sameSite?: "Lax" | "Strict";
+    path?: string;
+}
+export declare function serializeCookie(name: string, value: string, attributes: CookieAttributes): string;
+/**
+ * The name a cookie gets. `__Host-` over HTTPS binds it to exactly this origin — no `Domain`, path
+ * `/`, `Secure` — which browsers enforce; a plain-HTTP development console cannot use the prefix.
+ */
+export declare function cookieName(base: string, secure: boolean): string;

package/dist/session/cookies.js

@@ -0,0 +1,33 @@
+/** Reading and writing cookies on web `Request`/`Headers`, with the attributes the console needs. */
+export function readCookie(request, name) {
+    const header = request.headers.get("cookie");
+    if (!header)
+        return undefined;
+    for (const part of header.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            continue;
+        if (part.slice(0, eq).trim() === name)
+            return part.slice(eq + 1).trim();
+    }
+    return undefined;
+}
+export function serializeCookie(name, value, attributes) {
+    const parts = [
+        `${name}=${value}`,
+        `Path=${attributes.path ?? "/"}`,
+        `Max-Age=${Math.max(0, Math.floor(attributes.maxAge))}`,
+        "HttpOnly",
+        `SameSite=${attributes.sameSite ?? "Lax"}`,
+    ];
+    if (attributes.secure)
+        parts.push("Secure");
+    return parts.join("; ");
+}
+/**
+ * The name a cookie gets. `__Host-` over HTTPS binds it to exactly this origin — no `Domain`, path
+ * `/`, `Secure` — which browsers enforce; a plain-HTTP development console cannot use the prefix.
+ */
+export function cookieName(base, secure) {
+    return secure ? `__Host-${base}` : base;
+}