toolroll 0.5.0

package/dist/names.js

@@ -0,0 +1,102 @@
+/**
+ * The product's internal name, and every older one it still answers to.
+ *
+ * Toolroll was Standing Orders, which was nightorders. A rename must never
+ * orphan an installation: new things use the new name, while a folder,
+ * variable, branch, launchd job or skill that already exists under an older
+ * name keeps being found. Nothing is moved; the old one is used until one
+ * exists under the new name. Strings that feed a hash, a digest or a stored
+ * format id are not names in this sense and stay byte-identical.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export const NAME = "toolroll";
+/** Older names, newest first. */
+export const LEGACY_NAMES = ["standing-orders", "nightorders"];
+export const NAMES = [NAME, ...LEGACY_NAMES];
+/**
+ * A file inside the product's folder under `base` (~/.config, ~/.cache, or a
+ * home dotfolder when `dot` is set). The first name that already holds the
+ * file wins; otherwise the file goes into the folder that holds the database,
+ * else the first folder that exists, else a new-name folder — so one install
+ * keeps one folder, and a fresh one gets ~/.config/toolroll.
+ */
+export function namedPath(base, rest, options = {}) {
+    const names = options.names ?? NAMES;
+    const folder = (name) => join(base, options.dot ? `.${name}` : name);
+    for (const name of names)
+        if (existsSync(join(folder(name), ...rest)))
+            return join(folder(name), ...rest);
+    return join(namedFolder(base, options), ...rest);
+}
+/** The product's folder under `base`: see namedPath. */
+export function namedFolder(base, options = {}) {
+    const names = options.names ?? NAMES;
+    const folder = (name) => join(base, options.dot ? `.${name}` : name);
+    const chosen = names.find(name => existsSync(join(folder(name), "orders.db"))) ?? names.find(name => existsSync(folder(name))) ?? names[0];
+    return folder(chosen);
+}
+/** Every folder under `base` that any name has made, for fencing and cleanup. */
+export function existingFolders(base, options = {}) {
+    return NAMES.map(name => join(base, options.dot ? `.${name}` : name)).filter(path => existsSync(path));
+}
+/** ~/.config (or $XDG_CONFIG_HOME). */
+export function configBase(env, home) {
+    const xdg = env["XDG_CONFIG_HOME"];
+    return xdg !== undefined && xdg !== "" ? xdg : join(home, ".config");
+}
+export const ENV_PREFIX = "TOOLROLL_";
+export const LEGACY_ENV_PREFIX = "STANDING_ORDERS_";
+/**
+ * An environment setting by its suffix ("DB" → TOOLROLL_DB). The new name
+ * wins whenever it is set; the old STANDING_ORDERS_ one is the fallback.
+ */
+export function envValue(env, suffix) {
+    // Empty counts as unset: a blank TOOLROLL_DB must not hide an isolating STANDING_ORDERS_DB.
+    const current = env[ENV_PREFIX + suffix];
+    return current !== undefined && current !== "" ? current : env[LEGACY_ENV_PREFIX + suffix];
+}
+/** The Telegram bot token's variable, and the name it had before the rename: agents never see either.
+ * Kept here, in a module with no imports of its own, so builder.ts can read it at load time. */
+export const TELEGRAM_TOKEN_ENV = `${ENV_PREFIX}TELEGRAM_TOKEN`;
+export const TELEGRAM_TOKEN_ENVS = [TELEGRAM_TOKEN_ENV, `${LEGACY_ENV_PREFIX}TELEGRAM_TOKEN`];
+/** Both names of a setting, for a child the plane starts: older tools read the old one. */
+export function envTwins(suffix, value) {
+    return { [ENV_PREFIX + suffix]: value, [LEGACY_ENV_PREFIX + suffix]: value };
+}
+/** True for a variable of either name ("TOOLROLL_DB", "STANDING_ORDERS_DB"). */
+export function isOwnEnv(key) {
+    return /^(TOOLROLL|STANDING_ORDERS)_/i.test(key);
+}
+/** New task branches are toolroll/<id>; the plane's older ones stay its own. */
+export const BRANCH_PREFIX = `${NAME}/`;
+export const BRANCH_PREFIXES = [BRANCH_PREFIX, "standing-orders/"];
+export function taskBranch(id) {
+    return `${BRANCH_PREFIX}${id}`;
+}
+/** A branch the plane made, under either name. */
+export function isOwnBranch(branch) {
+    return BRANCH_PREFIXES.some(prefix => branch.startsWith(prefix));
+}
+/**
+ * Whether a head branch is inside a publication grant's prefix. A grant made
+ * for the plane's own branches under one name covers the same branches under
+ * the other: a standing-orders/ grant still publishes toolroll/<id> work.
+ */
+export function headWithin(head, prefix) {
+    if (head.startsWith(prefix))
+        return true;
+    const own = BRANCH_PREFIXES.find(one => prefix.startsWith(one));
+    return own !== undefined && BRANCH_PREFIXES.some(one => head.startsWith(one + prefix.slice(own.length)));
+}
+/** Every name a task's own branch may have, newest first. */
+export function taskBranches(id) {
+    return BRANCH_PREFIXES.map(prefix => `${prefix}${id}`);
+}
+/** The first candidate branch that already exists (a retry reuses its branch), else the first — the new name. */
+export async function existingOrFirst(candidates, exists) {
+    for (const candidate of candidates)
+        if (await exists(candidate))
+            return candidate;
+    return candidates[0];
+}

package/dist/observations.d.ts

@@ -0,0 +1,40 @@
+import type { Runner } from "./builder.js";
+import type { Store } from "./store.js";
+export declare const OBSERVATION_MAILBOX = "STANDING-ORDERS-OBSERVATIONS.json";
+export declare const OBSERVATION_CAPTURE = "machine focused observations v1";
+export declare const OBSERVATION_FILE = "REVIEW-OBSERVATIONS.json";
+export type ObservationBrief = {
+    kind: "evidence-observation";
+    sourceTask: string;
+    sourceRun: number;
+    sourceScopeDigest: string;
+    head: string;
+    originalBase: string;
+    unresolved: {
+        id: string;
+        statement: string;
+        detail: string[];
+    }[];
+    gateDigest: string;
+};
+export declare function focusedTestCommandSupported(command: string): boolean;
+export type ObservationCase = {
+    criterion: string;
+    at: "base" | "head";
+    testPath: string;
+    testName: string;
+};
+export declare function originalTaskBase(store: Store, taskId: string): string | null;
+/** The existing sealed revision brief identifies this narrower kind of work.
+ * A title, agent-authored mailbox, or handoff can never elect gate reuse. */
+export declare function observationBrief(store: Store, root: string, taskRef: number): ObservationBrief | null;
+export declare function parseObservationCases(raw: string, ids: readonly string[]): ObservationCase[];
+export type ObservationEvidence = {
+    artifact: number;
+    sha256: string;
+    content: string;
+};
+export declare function readObservationEvidence(store: Store, root: string, runId: number): ObservationEvidence | null;
+/** The supplied runner applies the build's existing stop, custody, environment
+ * and approved command timeout. Only fixed argv is constructed here. */
+export declare function collectObservations(store: Store, root: string, runId: number, worktree: string, brief: ObservationBrief, cases: readonly ObservationCase[], execute: Runner, now: () => Date): Promise<void>;

package/dist/observations.js

@@ -0,0 +1,211 @@
+/** Focused observations are new evidence about an unchanged candidate. They
+ * never replace the original gate or give an agent a new shell authority. */
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { canonicalAcceptance } from "./scope.js";
+import { readVerifiedArtifact, scanForSecrets, storeEvidence } from "./evidence.js";
+export const OBSERVATION_MAILBOX = "STANDING-ORDERS-OBSERVATIONS.json";
+export const OBSERVATION_CAPTURE = "machine focused observations v1";
+export const OBSERVATION_FILE = "REVIEW-OBSERVATIONS.json";
+const sha = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const revision = (value) => typeof value === "string" && /^[0-9a-f]{40,64}$/.test(value);
+const pathOkay = (value) => typeof value === "string" && value.length > 0 && value.length <= 500 &&
+    !value.startsWith("-") && !/[\\\u0000-\u0020\u007f:*?\[\]]/.test(value) && value.split("/").every(p => p !== "" && p !== "." && p !== "..");
+export function focusedTestCommandSupported(command) {
+    const parts = command.trim().split(/\s*&&\s*/);
+    // Only simple argv joined by && can establish this narrower authority.
+    // Quotes, expansion, substitutions, redirects and other shell syntax need
+    // explicit support; text inside an echo/printf argument is not a command.
+    if (parts.some(c => !/^[A-Za-z0-9_./=:-]+(?: +[A-Za-z0-9_./=:-]+)*$/.test(c)))
+        return false;
+    return parts.some(c => /^npm (?:test|run test)(?: -- (?:--run|--reporter=\w+|--no-file-parallelism)(?: (?:--run|--reporter=\w+|--no-file-parallelism))*)?$/.test(c));
+}
+export function originalTaskBase(store, taskId) {
+    const lineage = store.repairLineageOf(taskId);
+    if (lineage.problem)
+        return null;
+    const ref = store.lookupRef(lineage.rootTask);
+    const first = ref && store.runsFor(ref.id).filter(r => r.role === "builder" && r.branch && r.baseRevision).sort((a, b) => a.id - b.id)[0];
+    return first?.branch ? store.firstBuilderBase(first.taskRef, first.branch) ?? first.baseRevision : null;
+}
+/** The existing sealed revision brief identifies this narrower kind of work.
+ * A title, agent-authored mailbox, or handoff can never elect gate reuse. */
+export function observationBrief(store, root, taskRef) {
+    const ref = store.refById(taskRef);
+    const source = store.revisionSourceOf(taskRef);
+    if (!ref || !source)
+        return null;
+    const full = store.lookupRef(ref.externalId);
+    const artifact = full?.revisionBriefArtifact ? store.getArtifact(full.revisionBriefArtifact) : null;
+    if (!artifact)
+        return null;
+    const read = readVerifiedArtifact(root, artifact);
+    if (!read.ok)
+        throw Error("The observation brief no longer verifies.");
+    const brief = JSON.parse(read.content.toString("utf8"));
+    if (brief.kind !== "evidence-observation")
+        return null;
+    const parent = store.getRun(source.sourceRun), parentScope = store.getScope(source.sourceTask), scope = store.getScope(ref.externalId);
+    if (!parent || !parentScope || !scope || brief.sourceRun !== parent.id || brief.sourceTask !== source.sourceTask ||
+        brief.sourceScopeDigest !== parent.scopeDigest || parentScope.digest !== parent.scopeDigest ||
+        !revision(brief.head) || brief.head !== parent.headRevision || !revision(brief.originalBase) ||
+        brief.originalBase !== originalTaskBase(store, source.sourceTask) || !/^[0-9a-f]{64}$/.test(brief.gateDigest) ||
+        JSON.stringify(canonicalAcceptance(scope.acceptance)) !== JSON.stringify(canonicalAcceptance(parentScope.acceptance)) ||
+        !Array.isArray(brief.unresolved) || brief.unresolved.length === 0 ||
+        brief.unresolved.some((row) => !parentScope.acceptance.some(c => c.id === row.id)))
+        throw Error("The observation source, candidate or signed criteria changed.");
+    return brief;
+}
+export function parseObservationCases(raw, ids) {
+    if (Buffer.byteLength(raw) > 16 * 1024)
+        throw Error("The observation request is too large.");
+    const parsed = JSON.parse(raw);
+    if (parsed?.version !== 1 || !Array.isArray(parsed.observations) || parsed.observations.length < 1 || parsed.observations.length > 4 ||
+        Object.keys(parsed).some(k => k !== "version" && k !== "observations"))
+        throw Error("Use one to four focused test observations.");
+    const cases = parsed.observations;
+    for (const item of cases) {
+        if (!item || Object.keys(item).some(k => !["criterion", "at", "testPath", "testName"].includes(k)) || !ids.includes(item.criterion) ||
+            !["base", "head"].includes(item.at) || !pathOkay(item.testPath) || !/\.(test|spec)\.[cm]?[jt]sx?$/.test(item.testPath) ||
+            typeof item.testName !== "string" || item.testName.trim() === "" || item.testName.length > 500 || /[\u0000-\u001f\u007f]/.test(item.testName)) {
+            throw Error("An observation must name a requested criterion, base/head, one test file and one test name. Shell commands are not accepted.");
+        }
+    }
+    if (new Set(cases.map(c => JSON.stringify(c))).size !== cases.length || ids.some(id => !cases.some(c => c.criterion === id)))
+        throw Error("Every requested criterion needs a distinct observation.");
+    return cases;
+}
+function parseTree(text) {
+    if (!text.endsWith("\0") || Buffer.byteLength(text) > 4 * 1024 * 1024)
+        throw Error("The complete source inventory is unavailable.");
+    return text.slice(0, -1).split("\0").map(line => {
+        const m = /^(100644|100755) blob ([0-9a-f]{40})\t(.+)$/.exec(line);
+        if (!m || !pathOkay(m[3]))
+            throw Error("Observation snapshots require regular, normalized source files; links and submodules need separate setup.");
+        return { path: m[3], blob: m[2], executable: m[1] === "100755" };
+    });
+}
+function gitBlob(bytes) { return createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex"); }
+export function readObservationEvidence(store, root, runId) {
+    const found = store.artifactsFor(runId).filter(a => a.kind === "structured-output" && a.capture === OBSERVATION_CAPTURE);
+    if (found.length === 0)
+        return null;
+    const artifact = found[0];
+    if (found.length !== 1 || artifact.truncated || artifact.redacted || artifact.captureStatus !== "ok")
+        throw Error("The focused observation inventory is incomplete.");
+    const read = readVerifiedArtifact(root, artifact);
+    if (!read.ok)
+        throw Error("The focused observations no longer verify.");
+    const receipt = JSON.parse(read.content.toString("utf8")), run = store.getRun(runId), brief = run ? observationBrief(store, root, run.taskRef) : null;
+    if (!run || !brief || receipt.version !== 1 || receipt.run !== runId || receipt.head !== run.headRevision || receipt.head !== brief.head ||
+        receipt.scopeDigest !== run.scopeDigest || receipt.sourceRun !== brief.sourceRun || receipt.originalBase !== brief.originalBase ||
+        !Array.isArray(receipt.observations) || receipt.observations.length < 1 || receipt.observations.length > 4)
+        throw Error("The observations no longer match this exact candidate and scope.");
+    return { artifact: artifact.id, sha256: artifact.sha256, content: read.content.toString("utf8") };
+}
+/** The supplied runner applies the build's existing stop, custody, environment
+ * and approved command timeout. Only fixed argv is constructed here. */
+export async function collectObservations(store, root, runId, worktree, brief, cases, execute, now) {
+    const source = store.getRun(runId), ref = source && store.refById(source.taskRef);
+    const command = ref?.repo ? store.liveVerifyCommand(ref.repo) : null;
+    // This is deliberately a narrow first collector. Approval for npm test
+    // does not authorize arbitrary shell text supplied by an agent or review.
+    if (!source || !command || !focusedTestCommandSupported(command.command)) {
+        throw Error("Focused collection requires an already approved npm test command.");
+    }
+    const call = async (file, args, cwd) => {
+        const result = await execute(file, args, { cwd, timeoutMs: command.timeoutMs, maxBuffer: 4 * 1024 * 1024 });
+        if (result.notFound || result.timedOut || result.code !== 0)
+            throw Error(`Observation preparation failed: ${file} (${result.code}).`);
+        return result.stdout;
+    };
+    const headTree = parseTree(await call("git", ["ls-tree", "-rz", brief.head], worktree));
+    const baseTree = parseTree(await call("git", ["ls-tree", "-rz", brief.originalBase], worktree));
+    const changed = new Set((await call("git", ["diff", "--name-only", "-z", brief.originalBase, brief.head], worktree)).split("\0").filter(Boolean));
+    const packageAt = async (rev) => JSON.parse(await call("git", ["show", `${rev}:package.json`], worktree));
+    for (const rev of [brief.originalBase, brief.head]) {
+        const pkg = await packageAt(rev);
+        if (!/^vitest(?: run)?$/.test(pkg.scripts?.test ?? "") || pkg.scripts?.pretest || pkg.scripts?.posttest)
+            throw Error("This project needs a supported focused test command; only a direct Vitest test script is currently supported.");
+    }
+    const headLock = headTree.find(f => f.path === "package-lock.json"), baseLock = baseTree.find(f => f.path === "package-lock.json");
+    if (!headLock || headLock.blob !== baseLock?.blob || gitBlob(readFileSync(join(worktree, headLock.path))) !== headLock.blob)
+        throw Error("The original and candidate dependency locks must match for this focused comparison.");
+    const dependencyPath = realpathSync(join(worktree, "node_modules"));
+    if (!lstatSync(join(dependencyPath, "vitest", "vitest.mjs")).isFile())
+        throw Error("The project's installed Vitest runner is unavailable.");
+    const parent = join(root, String(runId));
+    mkdirSync(parent, { recursive: true });
+    const scratch = mkdtempSync(join(parent, "observation-"));
+    const observations = [];
+    try {
+        for (const [index, item] of cases.entries()) {
+            const at = item.at === "base" ? brief.originalBase : brief.head, tree = item.at === "base" ? baseTree : headTree;
+            const test = headTree.find(f => f.path === item.testPath);
+            if (!test || (item.at === "base" && !changed.has(item.testPath)))
+                throw Error("The baseline test overlay must be a test in the candidate's whole-task change set.");
+            const snapshot = join(scratch, String(index));
+            mkdirSync(snapshot);
+            const archive = join(scratch, `${index}.tar`);
+            await call("git", ["archive", "--format=tar", `--output=${archive}`, at], worktree);
+            await call("tar", ["-xf", archive, "-C", snapshot], worktree);
+            if (item.at === "base") {
+                const bytes = await call("git", ["show", `${brief.head}:${item.testPath}`], worktree);
+                if (gitBlob(Buffer.from(bytes)) !== test.blob)
+                    throw Error("The complete candidate test bytes are unavailable.");
+                mkdirSync(dirname(join(snapshot, item.testPath)), { recursive: true });
+                writeFileSync(join(snapshot, item.testPath), bytes);
+            }
+            const verifySnapshot = () => {
+                for (const file of tree) {
+                    const path = join(snapshot, file.path), expected = file.path === item.testPath ? test.blob : file.blob;
+                    if (!lstatSync(path).isFile() || gitBlob(readFileSync(path)) !== expected)
+                        throw Error("The observation changed or lost a source file: " + file.path);
+                }
+                if (gitBlob(readFileSync(join(snapshot, item.testPath))) !== test.blob)
+                    throw Error("The observation test changed.");
+            };
+            verifySnapshot();
+            symlinkSync(dependencyPath, join(snapshot, "node_modules"), "junction");
+            // Vitest treats its name filter as a regular expression. The manifest
+            // supplies a literal name; also verify the actual selected identity so
+            // a suffix, duplicate name or another matching file cannot stand in.
+            const pattern = `(?:^| )${item.testName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`;
+            const reportPath = join(scratch, `${index}.json`);
+            const argv = [join(dependencyPath, "vitest", "vitest.mjs"), "run", item.testPath, "--testNamePattern", pattern,
+                "--reporter=verbose", "--reporter=json", `--outputFile.json=${reportPath}`];
+            const startedAt = now().toISOString();
+            const result = await execute(process.execPath, argv, { cwd: snapshot, timeoutMs: command.timeoutMs, maxBuffer: 64 * 1024 });
+            verifySnapshot();
+            if (result.notFound || result.timedOut || result.code < 0 || result.code > 1 || Buffer.byteLength(result.stdout + result.stderr) > 48 * 1024)
+                throw Error("The focused test did not produce complete bounded output.");
+            const summary = stripVTControlCharacters(result.stdout + "\n" + result.stderr);
+            if (!/Tests\s+[1-9]\d* (?:passed|failed)/.test(summary) || /No test files found|No tests found/.test(summary))
+                throw Error("The focused command did not execute a test.");
+            if (!lstatSync(reportPath).isFile() || lstatSync(reportPath).size > 1024 * 1024)
+                throw Error("The focused test identity report is unavailable or too large.");
+            const report = JSON.parse(readFileSync(reportPath, "utf8"));
+            const selected = (report.testResults ?? []).flatMap((file) => (file.assertionResults ?? []).filter(test => test.status === "passed" || test.status === "failed").map(test => ({ path: file.name, title: test.title, fullName: test.fullName, status: test.status })));
+            const selectedTest = selected[0];
+            if (selected.length !== 1 || !selectedTest || realpathSync(selectedTest.path) !== realpathSync(join(snapshot, item.testPath)) ||
+                (selectedTest.title !== item.testName && selectedTest.fullName !== item.testName) ||
+                (selectedTest.status === "passed" ? result.code !== 0 : result.code !== 1))
+                throw Error("The focused command did not execute exactly the requested test.");
+            observations.push({ ...item, revision: at, testBlob: test.blob, testSha256: sha(readFileSync(join(snapshot, item.testPath))),
+                selectedTest: { ...selectedTest, path: item.testPath },
+                overlay: item.at === "base" ? [item.testPath] : [], lockBlob: headLock.blob, command: [process.execPath, ...argv],
+                approvedCommand: { id: command.id, digest: command.digest }, startedAt, finishedAt: now().toISOString(),
+                exitCode: result.code, stdout: result.stdout, stderr: result.stderr, sourceFilesVerified: tree.length });
+        }
+        const bytes = JSON.stringify({ version: 1, run: runId, head: brief.head, originalBase: brief.originalBase,
+            sourceRun: brief.sourceRun, scopeDigest: source.scopeDigest, observations }, null, 1);
+        if (Buffer.byteLength(bytes) > 64 * 1024 || scanForSecrets(bytes).length)
+            throw Error("The observations exceed storage limits or contain sensitive output; no incomplete evidence was accepted.");
+        storeEvidence(store, root, runId, "structured-output", "observations.json", Buffer.from(bytes), OBSERVATION_CAPTURE, now(), { captureStatus: "ok" });
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}

package/dist/oidc.d.ts

@@ -0,0 +1,71 @@
+export type GroupRule = {
+    group: string;
+    role: "operator" | "viewer";
+    projects: "all" | string[];
+};
+export type OidcSettings = {
+    issuer: string;
+    clientId: string;
+    clientSecret: string | null;
+    /** What the sign-in button says: "Okta", "Microsoft", "Google". */
+    label: string;
+    scopes: string;
+    /** The ID token claim that lists a person's groups. */
+    groupsClaim: string;
+    rules: GroupRule[];
+    /** Who may still sign in with a Toolroll password once sign-in with the provider is on. */
+    passwords: "everyone" | "operators";
+};
+export type OidcProvider = {
+    issuer: string;
+    authorize: string;
+    token: string;
+    jwks: string;
+};
+export type OidcClaims = {
+    sub: string;
+    email: string | null;
+    name: string | null;
+    username: string | null;
+    groups: string[];
+    authTime: number | null;
+};
+type Fetch = typeof fetch;
+/** The provider's endpoints, from its discovery document; its issuer must be the one configured. */
+export declare function discoverOidc(issuer: string, fetcher?: Fetch): Promise<{
+    ok: true;
+    provider: OidcProvider;
+} | {
+    ok: false;
+    said: string;
+}>;
+/** The pieces a sign-in needs to come back to: kept by the console, and its state in a cookie on the browser that started it. */
+export type OidcVisit = {
+    state: string;
+    nonce: string;
+    verifier: string;
+};
+export declare function newOidcVisit(): OidcVisit;
+/** Where to send the person to sign in. `reauth` asks the provider to check them again now (a step-up). */
+export declare function oidcAuthorizeUrl(provider: OidcProvider, settings: OidcSettings, visit: OidcVisit, redirectUri: string, reauth?: boolean): string;
+/** The code, traded for the ID token. */
+export declare function exchangeOidcCode(provider: OidcProvider, settings: OidcSettings, code: string, visit: OidcVisit, redirectUri: string, fetcher?: Fetch): Promise<{
+    ok: true;
+    idToken: string;
+} | {
+    ok: false;
+    said: string;
+}>;
+/** Check the ID token: its signature by one of the provider's keys, then who issued it, for whom, until when, and for which sign-in. */
+export declare function verifyIdToken(idToken: string, provider: OidcProvider, settings: OidcSettings, nonce: string, now: Date, fetcher?: Fetch): Promise<{
+    ok: true;
+    claims: OidcClaims;
+} | {
+    ok: false;
+    said: string;
+}>;
+/** A person's role and projects from their groups: the first rule that matches ("*" matches everyone), or none. */
+export declare function accessFromGroups(groups: readonly string[], rules: readonly GroupRule[]): GroupRule | null;
+/** An account name for someone new: from their username or email, in the characters names allow, made unique. */
+export declare function accountNameFor(claims: OidcClaims, taken: (name: string) => boolean): string;
+export {};

package/dist/oidc.js

@@ -0,0 +1,182 @@
+/**
+ * Sign-in with an identity provider (v100): OpenID Connect, the protocol
+ * Okta, Microsoft Entra, Google Workspace, Auth0, Keycloak and JumpCloud all
+ * speak. Discovery finds the provider's endpoints and keys; sign-in is the
+ * authorization-code flow with PKCE, a state and a nonce; the ID token's
+ * signature is checked against the provider's published keys (RS256, PS256,
+ * ES256) along with its issuer, audience, expiry and nonce. Groups from the
+ * token decide a person's role and projects, first matching rule wins.
+ *
+ * Addresses are https, except a provider on this computer (tests and local
+ * development), the same loopback exception OAuth makes.
+ */
+import { createHash, createPublicKey, randomBytes, verify, constants } from "node:crypto";
+const loopback = (value) => { try {
+    const url = new URL(value);
+    return url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
+}
+catch {
+    return false;
+} };
+const secure = (value, issuer) => {
+    if (typeof value !== "string")
+        return false;
+    try {
+        return new URL(value).protocol === "https:" || (loopback(issuer) && loopback(value));
+    }
+    catch {
+        return false;
+    }
+};
+const trim = (url) => url.replace(/\/+$/, "");
+/** The provider's endpoints, from its discovery document; its issuer must be the one configured. */
+export async function discoverOidc(issuer, fetcher = fetch) {
+    if (!secure(issuer, issuer))
+        return { ok: false, said: "The issuer must be an https address." };
+    let document;
+    try {
+        const answer = await fetcher(`${trim(issuer)}/.well-known/openid-configuration`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+        if (!answer.ok)
+            return { ok: false, said: `The provider's discovery document answered ${answer.status}.` };
+        document = await answer.json();
+    }
+    catch {
+        return { ok: false, said: "The provider couldn't be reached." };
+    }
+    if (typeof document["issuer"] !== "string" || trim(document["issuer"]) !== trim(issuer))
+        return { ok: false, said: "The provider names a different issuer than the one set here." };
+    const [authorize, token, jwks] = [document["authorization_endpoint"], document["token_endpoint"], document["jwks_uri"]];
+    if (!secure(authorize, issuer) || !secure(token, issuer) || !secure(jwks, issuer))
+        return { ok: false, said: "The provider's discovery document is missing its endpoints." };
+    return { ok: true, provider: { issuer: document["issuer"], authorize, token, jwks } };
+}
+export function newOidcVisit() {
+    return { state: randomBytes(24).toString("base64url"), nonce: randomBytes(24).toString("base64url"), verifier: randomBytes(32).toString("base64url") };
+}
+/** Where to send the person to sign in. `reauth` asks the provider to check them again now (a step-up). */
+export function oidcAuthorizeUrl(provider, settings, visit, redirectUri, reauth = false) {
+    const url = new URL(provider.authorize);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", settings.clientId);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("scope", settings.scopes);
+    url.searchParams.set("state", visit.state);
+    url.searchParams.set("nonce", visit.nonce);
+    url.searchParams.set("code_challenge", createHash("sha256").update(visit.verifier).digest("base64url"));
+    url.searchParams.set("code_challenge_method", "S256");
+    if (reauth) {
+        url.searchParams.set("prompt", "login");
+        url.searchParams.set("max_age", "0");
+    }
+    return url.toString();
+}
+/** The code, traded for the ID token. */
+export async function exchangeOidcCode(provider, settings, code, visit, redirectUri, fetcher = fetch) {
+    try {
+        const answer = await fetcher(provider.token, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }, signal: AbortSignal.timeout(15_000),
+            body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: settings.clientId, code_verifier: visit.verifier, ...(settings.clientSecret === null ? {} : { client_secret: settings.clientSecret }) }) });
+        const body = await answer.json();
+        if (!answer.ok || typeof body["id_token"] !== "string")
+            return { ok: false, said: `The provider didn't finish the sign-in (${typeof body["error"] === "string" ? body["error"] : `HTTP ${answer.status}`}).` };
+        return { ok: true, idToken: body["id_token"] };
+    }
+    catch {
+        return { ok: false, said: "The provider couldn't be reached to finish the sign-in." };
+    }
+}
+const keyCache = new Map();
+async function providerKeys(jwks, fetcher, fresh) {
+    const held = keyCache.get(jwks);
+    if (!fresh && held !== undefined && Date.now() - held.at < 10 * 60_000)
+        return held.keys;
+    const answer = await fetcher(jwks, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+    const body = await answer.json();
+    const keys = Array.isArray(body.keys) ? body.keys.filter((one) => one !== null && typeof one === "object") : [];
+    keyCache.set(jwks, { at: Date.now(), keys });
+    return keys;
+}
+const ALGORITHMS = {
+    RS256: { hash: "sha256", kty: "RSA" },
+    PS256: { hash: "sha256", padding: constants.RSA_PKCS1_PSS_PADDING, saltLength: 32, kty: "RSA" },
+    ES256: { hash: "sha256", dsaEncoding: "ieee-p1363", kty: "EC" },
+};
+const decode = (part) => {
+    try {
+        const value = JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+        return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** Check the ID token: its signature by one of the provider's keys, then who issued it, for whom, until when, and for which sign-in. */
+export async function verifyIdToken(idToken, provider, settings, nonce, now, fetcher = fetch) {
+    const parts = idToken.split(".");
+    if (parts.length !== 3)
+        return { ok: false, said: "The provider's token isn't a signed token." };
+    const header = decode(parts[0]), claims = decode(parts[1]);
+    if (header === null || claims === null)
+        return { ok: false, said: "The provider's token couldn't be read." };
+    const algorithm = typeof header["alg"] === "string" ? ALGORITHMS[header["alg"]] : undefined;
+    if (algorithm === undefined)
+        return { ok: false, said: `The provider signs with ${String(header["alg"])}, which isn't accepted.` };
+    const kid = typeof header["kid"] === "string" ? header["kid"] : null;
+    const pick = (keys) => keys.filter(key => key.kty === algorithm.kty && (kid === null || key.kid === kid) && (key.use === undefined || key.use === "sig"));
+    let candidates;
+    try {
+        candidates = pick(await providerKeys(provider.jwks, fetcher, false));
+        if (candidates.length === 0)
+            candidates = pick(await providerKeys(provider.jwks, fetcher, true)); // the provider may have rotated its keys
+    }
+    catch {
+        return { ok: false, said: "The provider's keys couldn't be read." };
+    }
+    const signed = Buffer.from(`${parts[0]}.${parts[1]}`), signature = Buffer.from(parts[2], "base64url");
+    const good = candidates.some(jwk => {
+        try {
+            const key = createPublicKey({ key: jwk, format: "jwk" });
+            return verify(algorithm.hash, signed, { key, ...(algorithm.padding === undefined ? {} : { padding: algorithm.padding, saltLength: algorithm.saltLength }), ...(algorithm.dsaEncoding === undefined ? {} : { dsaEncoding: algorithm.dsaEncoding }) }, signature);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!good)
+        return { ok: false, said: "The provider's token isn't signed by the provider." };
+    const seconds = Math.floor(now.getTime() / 1000);
+    const audience = Array.isArray(claims["aud"]) ? claims["aud"] : [claims["aud"]];
+    if (typeof claims["iss"] !== "string" || trim(claims["iss"]) !== trim(provider.issuer))
+        return { ok: false, said: "The token comes from a different issuer." };
+    if (!audience.includes(settings.clientId) || (audience.length > 1 && claims["azp"] !== undefined && claims["azp"] !== settings.clientId))
+        return { ok: false, said: "The token is for a different app." };
+    if (typeof claims["exp"] !== "number" || claims["exp"] < seconds - 60)
+        return { ok: false, said: "The sign-in expired. Try again." };
+    if (typeof claims["iat"] === "number" && claims["iat"] > seconds + 300)
+        return { ok: false, said: "The token's time is in the future. Check this computer's clock." };
+    if (claims["nonce"] !== nonce)
+        return { ok: false, said: "The sign-in didn't match. Try again." };
+    if (typeof claims["sub"] !== "string" || claims["sub"] === "")
+        return { ok: false, said: "The token doesn't say who signed in." };
+    const text = (key) => typeof claims[key] === "string" && claims[key] !== "" ? claims[key] : null;
+    const rawGroups = claims[settings.groupsClaim];
+    const groups = Array.isArray(rawGroups) ? rawGroups.filter((one) => typeof one === "string") : typeof rawGroups === "string" ? [rawGroups] : [];
+    // An address the provider hasn't checked names no one.
+    const email = claims["email_verified"] === false ? null : text("email");
+    return { ok: true, claims: { sub: claims["sub"], email, name: text("name"), username: text("preferred_username"), groups: groups.slice(0, 200), authTime: typeof claims["auth_time"] === "number" ? claims["auth_time"] : null } };
+}
+/** A person's role and projects from their groups: the first rule that matches ("*" matches everyone), or none. */
+export function accessFromGroups(groups, rules) {
+    return rules.find(rule => rule.group === "*" || groups.includes(rule.group)) ?? null;
+}
+/** An account name for someone new: from their username or email, in the characters names allow, made unique. */
+export function accountNameFor(claims, taken) {
+    const source = claims.username ?? claims.email ?? claims.name ?? "person";
+    const local = source.includes("@") ? source.slice(0, source.indexOf("@")) : source;
+    const base = local.normalize("NFKD").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[^A-Za-z0-9]+/, "").replace(/-+$/, "").slice(0, 36) || "person";
+    if (!taken(base))
+        return base;
+    for (let n = 2; n < 1000; n++)
+        if (!taken(`${base}-${n}`))
+            return `${base}-${n}`;
+    return `${base.slice(0, 27)}-${randomBytes(4).toString("hex")}`;
+}