ankka-console 0.10.0

package/dist/session/seal.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Authenticated encryption for values a browser carries but must not read or alter: AES-256-GCM
+ * with a random 96-bit nonce, the cookie's name as additional data (so a value sealed for one cookie
+ * cannot be replayed as another), base64url on the wire. The key is derived from the installation's
+ * secret with HKDF-SHA256, so the secret itself may be any length and is never used directly.
+ */
+import { webcrypto } from "node:crypto";
+export type SealKey = webcrypto.CryptoKey;
+export declare function deriveKey(secret: string, info: string): Promise<SealKey>;
+export declare function seal(value: unknown, key: SealKey, aad: string): Promise<string>;
+/** The sealed value, or `null` for anything tampered with, truncated, or sealed under another key or name. */
+export declare function unseal<T = unknown>(text: string, key: SealKey, aad: string): Promise<T | null>;

package/dist/session/seal.js

@@ -0,0 +1,38 @@
+/**
+ * Authenticated encryption for values a browser carries but must not read or alter: AES-256-GCM
+ * with a random 96-bit nonce, the cookie's name as additional data (so a value sealed for one cookie
+ * cannot be replayed as another), base64url on the wire. The key is derived from the installation's
+ * secret with HKDF-SHA256, so the secret itself may be any length and is never used directly.
+ */
+import { webcrypto } from "node:crypto";
+const subtle = webcrypto.subtle;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export async function deriveKey(secret, info) {
+    if (secret.length === 0)
+        throw new Error("the session secret must not be empty");
+    const material = await subtle.importKey("raw", encoder.encode(secret), "HKDF", false, ["deriveKey"]);
+    return subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(0), info: encoder.encode(info) }, material, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
+export async function seal(value, key, aad) {
+    const iv = webcrypto.getRandomValues(new Uint8Array(12));
+    const plain = encoder.encode(JSON.stringify(value));
+    const cipher = new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv, additionalData: encoder.encode(aad) }, key, plain));
+    const out = new Uint8Array(iv.length + cipher.length);
+    out.set(iv, 0);
+    out.set(cipher, iv.length);
+    return Buffer.from(out).toString("base64url");
+}
+/** The sealed value, or `null` for anything tampered with, truncated, or sealed under another key or name. */
+export async function unseal(text, key, aad) {
+    try {
+        const bytes = Buffer.from(text, "base64url");
+        if (bytes.length < 12 + 16)
+            return null;
+        const plain = await subtle.decrypt({ name: "AES-GCM", iv: bytes.subarray(0, 12), additionalData: encoder.encode(aad) }, key, bytes.subarray(12));
+        return JSON.parse(decoder.decode(plain));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/session/token-cache.d.ts

@@ -0,0 +1,21 @@
+export interface AccessTokenEntry {
+    accessToken: string;
+    /** Epoch milliseconds, already less the skew. */
+    expiresAt: number;
+    /** The newest refresh token for this session: equal to the key's when the provider did not rotate it. */
+    refreshToken: string;
+}
+export declare const digest: (refreshToken: string) => string;
+export declare class TokenCache {
+    #private;
+    constructor(options?: {
+        capacity?: number;
+        skewSeconds?: number;
+    });
+    /** The entry for this refresh token if its access token has not expired. */
+    get(refreshToken: string, now?: number): AccessTokenEntry | undefined;
+    /** Stores an access token that expires in `expiresInSeconds`, under every refresh token given. */
+    put(refreshTokens: string[], entry: Omit<AccessTokenEntry, "expiresAt">, expiresInSeconds: number, now?: number): void;
+    forget(refreshToken: string): void;
+    get size(): number;
+}

package/dist/session/token-cache.js

@@ -0,0 +1,47 @@
+/**
+ * Access tokens, in this instance's memory, keyed by a digest of the refresh token that obtained
+ * them. Nothing depends on an entry being here: a miss costs one refresh. Bounded, least recently
+ * used first out, so a busy instance's memory does not grow with the number of browsers it has seen.
+ */
+import { createHash } from "node:crypto";
+export const digest = (refreshToken) => createHash("sha256").update(refreshToken).digest("base64url");
+export class TokenCache {
+    #entries = new Map();
+    #capacity;
+    #skewMs;
+    constructor(options = {}) {
+        this.#capacity = options.capacity ?? 10_000;
+        this.#skewMs = (options.skewSeconds ?? 30) * 1000;
+    }
+    /** The entry for this refresh token if its access token has not expired. */
+    get(refreshToken, now = Date.now()) {
+        const key = digest(refreshToken);
+        const entry = this.#entries.get(key);
+        if (!entry)
+            return undefined;
+        this.#entries.delete(key);
+        if (entry.expiresAt <= now)
+            return undefined;
+        this.#entries.set(key, entry);
+        return entry;
+    }
+    /** Stores an access token that expires in `expiresInSeconds`, under every refresh token given. */
+    put(refreshTokens, entry, expiresInSeconds, now = Date.now()) {
+        const stored = { ...entry, expiresAt: now + expiresInSeconds * 1000 - this.#skewMs };
+        for (const rt of new Set(refreshTokens)) {
+            const key = digest(rt);
+            this.#entries.delete(key);
+            this.#entries.set(key, stored);
+        }
+        while (this.#entries.size > this.#capacity) {
+            const oldest = this.#entries.keys().next().value;
+            this.#entries.delete(oldest);
+        }
+    }
+    forget(refreshToken) {
+        this.#entries.delete(digest(refreshToken));
+    }
+    get size() {
+        return this.#entries.size;
+    }
+}

package/dist/session/token-source.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The signed-in person's access token for this request. The only thing a page's data ever needs
+ * from a session, and the seam a host with its own sign-in replaces.
+ */
+import type { Tokens } from "../auth/oidc.ts";
+/** The one thing a token source asks of the identity provider. */
+export interface Refresher {
+    refresh(refreshToken: string): Promise<Tokens>;
+}
+import type { SessionStore } from "./cookie-store.ts";
+import { type TokenCache } from "./token-cache.ts";
+export interface TokenSource {
+    /**
+     * The bearer for this request, obtaining a fresh one when `refresh` is set or none is held;
+     * `null` means nobody is signed in and the person is to be sent to sign in. `headers` is where a
+     * session that changed on the way — a rotated refresh token, a cleared cookie — is written.
+     */
+    accessToken(request: Request, headers: Headers, options?: {
+        refresh?: boolean;
+    }): Promise<string | null>;
+}
+/**
+ * Tokens from the package's own sign-in: the refresh token from the session store, access tokens
+ * cached in this instance's memory, a refresh when there is none. A refresh that rotates the
+ * refresh token caches under both and writes the new one back, so a request still carrying the old
+ * cookie — on this instance or another — keeps working until the old token's own expiry.
+ */
+export declare class SessionTokenSource implements TokenSource {
+    #private;
+    constructor(options: {
+        store: SessionStore;
+        cache: TokenCache;
+        issuer: Refresher;
+    });
+    accessToken(request: Request, headers: Headers, options?: {
+        refresh?: boolean;
+    }): Promise<string | null>;
+    /** Remembers a freshly signed-in session's access token, so its first page needs no refresh. */
+    remember(tokens: Tokens): void;
+    forget(refreshToken: string): void;
+}

package/dist/session/token-source.js

@@ -0,0 +1,63 @@
+import { SessionEnded } from "../auth/oidc.js";
+import { digest } from "./token-cache.js";
+/**
+ * Tokens from the package's own sign-in: the refresh token from the session store, access tokens
+ * cached in this instance's memory, a refresh when there is none. A refresh that rotates the
+ * refresh token caches under both and writes the new one back, so a request still carrying the old
+ * cookie — on this instance or another — keeps working until the old token's own expiry.
+ */
+export class SessionTokenSource {
+    #store;
+    #cache;
+    #issuer;
+    #inFlight = new Map();
+    constructor(options) {
+        this.#store = options.store;
+        this.#cache = options.cache;
+        this.#issuer = options.issuer;
+    }
+    async accessToken(request, headers, options = {}) {
+        const session = await this.#store.read(request);
+        if (!session)
+            return null;
+        const cached = this.#cache.get(session.refreshToken);
+        if (cached && !options.refresh)
+            return cached.accessToken;
+        // The newest refresh token this instance knows for the session: the cookie may be one rotation behind.
+        const latest = cached?.refreshToken ?? session.refreshToken;
+        let tokens;
+        try {
+            tokens = await this.#refreshOnce(latest);
+        }
+        catch (e) {
+            if (e instanceof SessionEnded) {
+                this.#cache.forget(session.refreshToken);
+                await this.#store.clear(headers);
+                return null;
+            }
+            throw e;
+        }
+        this.#cache.put([session.refreshToken, latest, tokens.refreshToken], { accessToken: tokens.accessToken, refreshToken: tokens.refreshToken }, tokens.expiresIn);
+        if (tokens.refreshToken !== session.refreshToken) {
+            await this.#store.write({ refreshToken: tokens.refreshToken, issuedAt: Math.floor(Date.now() / 1000) }, headers);
+        }
+        return tokens.accessToken;
+    }
+    /** Remembers a freshly signed-in session's access token, so its first page needs no refresh. */
+    remember(tokens) {
+        this.#cache.put([tokens.refreshToken], { accessToken: tokens.accessToken, refreshToken: tokens.refreshToken }, tokens.expiresIn);
+    }
+    forget(refreshToken) {
+        this.#cache.forget(refreshToken);
+    }
+    /** Two requests from one browser arriving together refresh once, not twice. */
+    #refreshOnce(refreshToken) {
+        const key = digest(refreshToken);
+        const existing = this.#inFlight.get(key);
+        if (existing)
+            return existing;
+        const pending = this.#issuer.refresh(refreshToken).finally(() => this.#inFlight.delete(key));
+        this.#inFlight.set(key, pending);
+        return pending;
+    }
+}

package/dist/stream/log-follow.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Following a log that can only be re-read, never resumed: the control plane answers an instance's
+ * recent output as text, with no cursor and no line identity. Each read covers a window that overlaps
+ * the last; the lines already sent are found as the longest run at the end of what was sent that
+ * matches the start of the new window, and only what follows it is new.
+ *
+ * The one thing this cannot see is a line repeated identically inside one overlap: it may be dropped
+ * or sent twice. A service that timestamps its own log lines makes following exact.
+ */
+export declare class LogFollower {
+    #private;
+    constructor(keep?: number);
+    /** The lines of `window` not yet sent for `instance`, remembered as sent. */
+    next(instance: string, window: string[]): string[];
+    /** How many lines at the start of `window` are the last lines of `sent`. */
+    static overlap(sent: string[], window: string[]): number;
+}
+export declare const lines: (output: string) => string[];

package/dist/stream/log-follow.js

@@ -0,0 +1,40 @@
+/**
+ * Following a log that can only be re-read, never resumed: the control plane answers an instance's
+ * recent output as text, with no cursor and no line identity. Each read covers a window that overlaps
+ * the last; the lines already sent are found as the longest run at the end of what was sent that
+ * matches the start of the new window, and only what follows it is new.
+ *
+ * The one thing this cannot see is a line repeated identically inside one overlap: it may be dropped
+ * or sent twice. A service that timestamps its own log lines makes following exact.
+ */
+export class LogFollower {
+    #keep;
+    #sent = new Map();
+    constructor(keep = 200) {
+        this.#keep = keep;
+    }
+    /** The lines of `window` not yet sent for `instance`, remembered as sent. */
+    next(instance, window) {
+        const sent = this.#sent.get(instance) ?? [];
+        const overlap = LogFollower.overlap(sent, window);
+        const fresh = window.slice(overlap);
+        this.#sent.set(instance, [...sent, ...fresh].slice(-this.#keep));
+        return fresh;
+    }
+    /** How many lines at the start of `window` are the last lines of `sent`. */
+    static overlap(sent, window) {
+        for (let n = Math.min(sent.length, window.length); n > 0; n--) {
+            let match = true;
+            for (let i = 0; i < n; i++) {
+                if (sent[sent.length - n + i] !== window[i]) {
+                    match = false;
+                    break;
+                }
+            }
+            if (match)
+                return n;
+        }
+        return 0;
+    }
+}
+export const lines = (output) => output.split("\n").filter((l, i, all) => l.length > 0 || i < all.length - 1);

package/dist/stream/registry.d.ts

@@ -0,0 +1,6 @@
+type Closer = () => void;
+export declare function registerStream(close: Closer): () => void;
+/** Tells every open stream the server is closing; returns how many there were. */
+export declare function closeAllStreams(): number;
+export declare function openStreamCount(): number;
+export {};

package/dist/stream/registry.js

@@ -0,0 +1,34 @@
+/**
+ * Every open update stream in this process, so shutdown can tell each one to reconnect elsewhere.
+ *
+ * Kept on `globalThis` under a registered symbol rather than in module state: the host's server and
+ * its app bundle each hold their own copy of this package, and both must see the same set.
+ */
+const key = Symbol.for("ankka-console.open-streams");
+function registry() {
+    const g = globalThis;
+    return (g[key] ??= new Set());
+}
+export function registerStream(close) {
+    const set = registry();
+    set.add(close);
+    return () => set.delete(close);
+}
+/** Tells every open stream the server is closing; returns how many there were. */
+export function closeAllStreams() {
+    const set = registry();
+    const n = set.size;
+    for (const close of [...set]) {
+        try {
+            close();
+        }
+        catch {
+            // A stream whose client already left has nothing to be told.
+        }
+    }
+    set.clear();
+    return n;
+}
+export function openStreamCount() {
+    return registry().size;
+}

package/dist/stream/sse.d.ts

@@ -0,0 +1,14 @@
+export interface EventSink {
+    send(event: string, data: unknown): void;
+    /** Ends the stream after sending `event`, if given. */
+    end(event?: string, data?: unknown): void;
+    readonly closed: boolean;
+}
+export interface PollingStreamOptions {
+    signal: AbortSignal;
+    intervalMs?: number;
+    keepaliveMs?: number;
+    /** Called at once and then every interval until the stream ends. */
+    tick(sink: EventSink): Promise<void>;
+}
+export declare function pollingStream(options: PollingStreamOptions): Response;

package/dist/stream/sse.js

@@ -0,0 +1,87 @@
+/**
+ * A server-sent event stream fed by polling: every interval, `tick` reads what the page shows and
+ * sends what changed. Every event's data is one JSON document on one line — raw text would lose a
+ * leading space to the protocol and split on a newline. A comment every fifteen seconds keeps
+ * proxies from closing a quiet stream. Shutdown tells the browser to reconnect, which lands it on an
+ * instance that is staying.
+ */
+import { registerStream } from "./registry.js";
+const encoder = new TextEncoder();
+export function pollingStream(options) {
+    const interval = options.intervalMs ?? 2_000;
+    const keepalive = options.keepaliveMs ?? 15_000;
+    let timer;
+    let alive;
+    let unregister = () => undefined;
+    let closed = false;
+    const body = new ReadableStream({
+        start(controller) {
+            const write = (chunk) => {
+                if (closed)
+                    return;
+                try {
+                    controller.enqueue(encoder.encode(chunk));
+                }
+                catch {
+                    stop();
+                }
+            };
+            const stop = () => {
+                if (closed)
+                    return;
+                closed = true;
+                clearTimeout(timer);
+                clearInterval(alive);
+                unregister();
+                try {
+                    controller.close();
+                }
+                catch {
+                    // already closed by the client leaving
+                }
+            };
+            const sink = {
+                send: (event, data) => write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`),
+                end: (event, data) => {
+                    if (event)
+                        sink.send(event, data ?? {});
+                    stop();
+                },
+                get closed() {
+                    return closed;
+                },
+            };
+            unregister = registerStream(() => sink.end("server-closing", {}));
+            options.signal.addEventListener("abort", stop, { once: true });
+            alive = setInterval(() => write(": keepalive\n\n"), keepalive);
+            write("retry: 2000\n\n");
+            const loop = async () => {
+                if (closed)
+                    return;
+                try {
+                    await options.tick(sink);
+                }
+                catch {
+                    // A read that failed this time is tried again next time; a stream never dies of one.
+                }
+                if (!closed)
+                    timer = setTimeout(loop, interval);
+            };
+            void loop();
+        },
+        cancel() {
+            closed = true;
+            clearTimeout(timer);
+            clearInterval(alive);
+            unregister();
+        },
+    });
+    return new Response(body, {
+        headers: {
+            "content-type": "text/event-stream; charset=utf-8",
+            "cache-control": "no-store",
+            connection: "keep-alive",
+            "x-accel-buffering": "no",
+        },
+    });
+}