@anchrd/intel 0.59.0

package/dist/prompts/prompts.types.d.ts

@@ -0,0 +1,71 @@
+import type { NodeDocument } from "../contract/node.js";
+import type { Actor } from "../nodes/nodes.types.js";
+/**
+ * One entry of the slash-command catalogue (#775): a document offered as an instruction, or a
+ * published flow offered as a way to start one.
+ *
+ * ⚠️ `kind` is two values and not `NodeKind`. A flow is not a node, and the five node kinds that
+ * cannot be offered have no business appearing in this union — a widened type here would be a
+ * standing invitation to hand `prompts/list` a folder.
+ */
+export interface PromptEntry {
+    name: string;
+    kind: "document" | "flow";
+    targetId: string;
+    title: string;
+    description: string | null;
+}
+/**
+ * Who holds a name, as much of it as the asking actor is entitled to learn.
+ *
+ * ⚠️ `title` is `null` when the holder exists but this actor may not see it, and that is not the
+ * same as "no holder". ADR-0004 §3 is explicit that a refusal must not become a way of reading the
+ * tree: naming the document that holds `payroll` would tell somebody without access that a document
+ * by that title exists. The caller is told the name is taken — which they must be, or they cannot
+ * proceed — and nothing else.
+ */
+export interface PromptNameHolder {
+    kind: "document" | "flow";
+    title: string | null;
+}
+/**
+ * Who is asking for the catalogue, and which halves of it they are entitled to at all.
+ *
+ * ⚠️ **The capability follows the KIND, exactly as it does for `audit_list`** (#774). A prompt
+ * entry says the same thing its resource says, so listing it asks what reading that resource asks:
+ * `nodes/read` for a document, `flows/read` for a flow. Somebody holding only one of the two gets
+ * the half they hold — not an empty list, and not the other half by accident.
+ *
+ * ⚠️ These are the GATE capabilities and they are the coarse half of the answer. The resource ACL
+ * still runs underneath, per row, in the query itself; a caller with `nodes/read` sees the offered
+ * documents THEY may read and no others.
+ */
+export interface PromptActor extends Actor {
+    canReadNodes: boolean;
+    canReadFlows: boolean;
+}
+export interface PromptRepository {
+    listOffered(actor: PromptActor): Promise<PromptEntry[]>;
+    findOffered(actor: PromptActor, name: string): Promise<PromptEntry | null>;
+}
+export interface PromptsDeps {
+    repository: PromptRepository;
+    /**
+     * One document, as the node service reads it: the same authorization walk, the same content
+     * store. `prompts/get` does not reach into R2 on its own — a second reader would be a second
+     * place for the ACL to be applied, and the one that gets it wrong is the one nobody looks at.
+     *
+     * ⚠️ **The whole document, not a string.** What is stored under a document node is the editor's
+     * payload, and turning that into readable text needs the `mediaType` beside the content. Handing
+     * a string in would put that decision in whatever wired this up — in the Cloudflare shell, which
+     * is the one place in this package that may not hold business behaviour.
+     */
+    readDocument(actor: Actor, nodeId: string): Promise<NodeDocument>;
+}
+export interface Prompts {
+    list(actor: PromptActor): Promise<PromptEntry[]>;
+    get(actor: PromptActor, name: string): Promise<{
+        entry: PromptEntry;
+        text: string;
+    }>;
+}

package/dist/prompts/prompts.types.js

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

package/dist/shared/callers/callers.d.ts

@@ -0,0 +1,28 @@
+import type { NamedOrCounted } from "../../contract/contract.js";
+type Callers = {
+    visible: string[];
+    hidden: number;
+};
+/**
+ * ⚠️ Named where the reader may see it, counted where they may not (ADR-0004 §3). A refusal has to
+ * be actionable without becoming a way of reading the tree: whoever holds one grant on one folder
+ * must not learn the titles of flows they are refused directly.
+ *
+ * This is the middle of both refusals that ask the question — narrowing a folder (`nodes.ts`) and
+ * deleting a flow for good (`flows.ts`). ⚠️ **The two SENTENCES around it stay two**, because they
+ * say different things to different people: one is about a folder that is about to lose a grant,
+ * the other about a flow that is about to be gone. Folding them into one parameterised sentence
+ * would buy a shared string and cost the reason each one gives.
+ */
+export declare function callersPhrase(callers: Callers): string;
+/**
+ * The same two facts the sentence is built from, in the shape a grant's own warning already uses
+ * (`UnreadableNodes`, #448). One question — what may you see, and of how much — deserves one answer
+ * shape on every surface, and a screen that has to write the sentence itself needs the facts and
+ * not the sentence.
+ *
+ * ⚠️ It reads the SAME argument the phrase above reads. A surface that recomputed the split would
+ * be deciding what it may not, and a second decision here would be the one that drifts.
+ */
+export declare function namedOrCounted(callers: Callers): NamedOrCounted;
+export {};

package/dist/shared/callers/callers.js

@@ -0,0 +1,30 @@
+/**
+ * ⚠️ Named where the reader may see it, counted where they may not (ADR-0004 §3). A refusal has to
+ * be actionable without becoming a way of reading the tree: whoever holds one grant on one folder
+ * must not learn the titles of flows they are refused directly.
+ *
+ * This is the middle of both refusals that ask the question — narrowing a folder (`nodes.ts`) and
+ * deleting a flow for good (`flows.ts`). ⚠️ **The two SENTENCES around it stay two**, because they
+ * say different things to different people: one is about a folder that is about to lose a grant,
+ * the other about a flow that is about to be gone. Folding them into one parameterised sentence
+ * would buy a shared string and cost the reason each one gives.
+ */
+export function callersPhrase(callers) {
+    const named = callers.visible.map((title) => `“${title}”`).join(", ");
+    const rest = callers.hidden === 0
+        ? ""
+        : `${named ? " and " : ""}${callers.hidden} more flow${callers.hidden === 1 ? "" : "s"} you cannot see`;
+    return `${named}${rest}`;
+}
+/**
+ * The same two facts the sentence is built from, in the shape a grant's own warning already uses
+ * (`UnreadableNodes`, #448). One question — what may you see, and of how much — deserves one answer
+ * shape on every surface, and a screen that has to write the sentence itself needs the facts and
+ * not the sentence.
+ *
+ * ⚠️ It reads the SAME argument the phrase above reads. A surface that recomputed the split would
+ * be deciding what it may not, and a second decision here would be the one that drifts.
+ */
+export function namedOrCounted(callers) {
+    return { titles: callers.visible, hidden: callers.hidden };
+}

package/dist/shared/csv/csv.d.ts

@@ -0,0 +1,13 @@
+export declare function encodeCsvRow(cells: readonly string[]): string;
+export declare function encodeCsv(rows: readonly (readonly string[])[]): string;
+/**
+ * Every row of a CSV body, quoted fields included.
+ *
+ * ⚠️ A quoted field may contain a line break, so this cannot split on `\n` first. A row is closed
+ * by a line break that falls outside quotes and by nothing else — the reason a naive `split` reads
+ * a table with one multi-line cell as two broken rows.
+ *
+ * A trailing newline does not produce an empty final row; an empty line in the middle does produce
+ * a row with one empty cell, because that is what the file says.
+ */
+export declare function parseCsv(text: string): string[][];

package/dist/shared/csv/csv.js

@@ -0,0 +1,85 @@
+// The one CSV reader and writer in Intel. A table's canonical body is CSV (#40), and every surface
+// that has to look inside one — the grid, the column check, the search index — goes through here so
+// none of them can grow a private opinion about quoting.
+//
+// RFC 4180 with two deliberate narrowings: rows are separated by `\n` when written (a reader
+// accepts `\r\n` too), and a field is quoted only when it has to be. Nothing else is escaped,
+// because CSV has no escapes — a quote inside a quoted field is written twice.
+function needsQuoting(cell) {
+    return (cell.includes(",") ||
+        cell.includes('"') ||
+        cell.includes("\n") ||
+        cell.includes("\r") ||
+        cell !== cell.trim());
+}
+export function encodeCsvRow(cells) {
+    return cells
+        .map((cell) => (needsQuoting(cell) ? `"${cell.replaceAll('"', '""')}"` : cell))
+        .join(",");
+}
+export function encodeCsv(rows) {
+    return rows.length === 0 ? "" : `${rows.map(encodeCsvRow).join("\n")}\n`;
+}
+/**
+ * Every row of a CSV body, quoted fields included.
+ *
+ * ⚠️ A quoted field may contain a line break, so this cannot split on `\n` first. A row is closed
+ * by a line break that falls outside quotes and by nothing else — the reason a naive `split` reads
+ * a table with one multi-line cell as two broken rows.
+ *
+ * A trailing newline does not produce an empty final row; an empty line in the middle does produce
+ * a row with one empty cell, because that is what the file says.
+ */
+export function parseCsv(text) {
+    const rows = [];
+    let row = [];
+    let cell = "";
+    let quoted = false;
+    let started = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const character = text[index];
+        if (quoted) {
+            if (character === '"') {
+                if (text[index + 1] === '"') {
+                    cell += '"';
+                    index += 1;
+                }
+                else {
+                    quoted = false;
+                }
+            }
+            else {
+                cell += character;
+            }
+            continue;
+        }
+        if (character === '"' && cell === "") {
+            quoted = true;
+            started = true;
+            continue;
+        }
+        if (character === ",") {
+            row.push(cell);
+            cell = "";
+            started = true;
+            continue;
+        }
+        if (character === "\n" || character === "\r") {
+            if (character === "\r" && text[index + 1] === "\n")
+                index += 1;
+            row.push(cell);
+            rows.push(row);
+            row = [];
+            cell = "";
+            started = false;
+            continue;
+        }
+        cell += character;
+        started = true;
+    }
+    if (started || cell !== "" || row.length > 0) {
+        row.push(cell);
+        rows.push(row);
+    }
+    return rows;
+}

package/dist/shared/document-text/document-text.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The READABLE text of one stored version, for the two places that need a document as prose rather
+ * than as the editor's own payload.
+ *
+ * ⚠️ **What a document node stores is NOT its text.** The editor writes a BlockNote payload —
+ * `{ blocks, markdown, … }` — and `markdown` beside the blocks is the whole of what anybody outside
+ * the editor can read. `packages/intel/ui/CLAUDE.md` states it for the search: `indexing.ts` pulls that
+ * field and nothing else into full text and vectors, so it is what anyone searching Intel matches
+ * against. A caller who hands the raw content on instead is handing on a JSON blob.
+ *
+ * ⚠️ **Every other media type travels unchanged**, and that is not an oversight: a `text/markdown`
+ * version IS its text, and a table renders its own. Only the editor's payload has a wrapper around
+ * the words.
+ *
+ * ⚠️ **`null` means "this content is not readable as text", not "empty".** Immutable content never
+ * becomes parsable on a retry, so the two callers answer it differently and each is right for its
+ * own surface: the indexer refuses the version permanently rather than requeueing it forever, and
+ * `prompts/get` refuses the call rather than handing a model half a JSON document. Returning `""`
+ * here would collapse both into "there is nothing to say".
+ */
+export declare function documentText(mediaType: string, content: string): string | null;

package/dist/shared/document-text/document-text.js

@@ -0,0 +1,31 @@
+import { BlockNoteDocument, BlockNoteMediaType } from "../../contract/node.js";
+/**
+ * The READABLE text of one stored version, for the two places that need a document as prose rather
+ * than as the editor's own payload.
+ *
+ * ⚠️ **What a document node stores is NOT its text.** The editor writes a BlockNote payload —
+ * `{ blocks, markdown, … }` — and `markdown` beside the blocks is the whole of what anybody outside
+ * the editor can read. `packages/intel/ui/CLAUDE.md` states it for the search: `indexing.ts` pulls that
+ * field and nothing else into full text and vectors, so it is what anyone searching Intel matches
+ * against. A caller who hands the raw content on instead is handing on a JSON blob.
+ *
+ * ⚠️ **Every other media type travels unchanged**, and that is not an oversight: a `text/markdown`
+ * version IS its text, and a table renders its own. Only the editor's payload has a wrapper around
+ * the words.
+ *
+ * ⚠️ **`null` means "this content is not readable as text", not "empty".** Immutable content never
+ * becomes parsable on a retry, so the two callers answer it differently and each is right for its
+ * own surface: the indexer refuses the version permanently rather than requeueing it forever, and
+ * `prompts/get` refuses the call rather than handing a model half a JSON document. Returning `""`
+ * here would collapse both into "there is nothing to say".
+ */
+export function documentText(mediaType, content) {
+    if (mediaType !== BlockNoteMediaType)
+        return content;
+    try {
+        return BlockNoteDocument.parse(JSON.parse(content)).markdown;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/shared/gate-authorization/gate-authorization.d.ts

@@ -0,0 +1,5 @@
+import type { Authorized, GateClient } from "@anchrd/gate-sdk";
+export declare function bearer(headers: Headers): string | null;
+export declare function authorize(gate: Pick<GateClient, "authorize">, headers: Headers, resource: string): Promise<Authorized | null>;
+export declare function permits(authorization: Pick<Authorized, "can">, handle: string, fn: string): boolean;
+export declare function authorizeBearer(gate: Pick<GateClient, "authorize">, token: string, resource: string): Promise<Authorized | null>;

package/dist/shared/gate-authorization/gate-authorization.js

@@ -0,0 +1,26 @@
+export function bearer(headers) {
+    const value = headers.get("authorization");
+    // RFC 9110 defines the auth scheme as case-insensitive, so a client sending "bearer" must not be
+    // turned away as unauthenticated.
+    if (!value || !/^bearer /i.test(value))
+        return null;
+    const token = value.slice(7);
+    return token.length > 0 ? token : null;
+}
+export async function authorize(gate, headers, resource) {
+    const token = bearer(headers);
+    if (!token)
+        return null;
+    return await authorizeBearer(gate, token, resource);
+}
+// `intel/admin` opens every door, and it has to: `share` inherits downwards only, so without a way
+// in that needs no grant, a fresh instance has nobody who can set the first one (ADR-0004 §6). Gate
+// learned the same lesson at three separate doors — a guard written per route is a list that goes
+// quietly incomplete at the next one, so both surfaces ask this one function instead.
+export function permits(authorization, handle, fn) {
+    return authorization.can(handle, fn) || authorization.can("intel", "admin");
+}
+export async function authorizeBearer(gate, token, resource) {
+    const result = await gate.authorize(token);
+    return result.ok && result.resource === resource ? result : null;
+}

package/dist/shared/grant-expiry/grant-expiry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ⚠️ A grant whose expiry has already passed is refused, never written (#442).
+ *
+ * It would otherwise be created, answered with a `201`, and listed — while reaching nobody. The
+ * sharer reads the row as done; the grantee gets no notification and finds out days later, if at
+ * all. That is the failure mode this repository keeps meeting: something that looks like success,
+ * and the only feedback is the wrong one.
+ *
+ * ⚠️ The check cannot live in the Zod schema. That boundary knows nothing about `deps.now()`, and
+ * the rule is decided by the very clock that evaluates the grant afterwards — so it belongs in the
+ * application layer, where every surface passes through it. The `.describe()` on `expiresAt`
+ * documents the rule; this refuses it.
+ *
+ * ⚠️ Equal to `now` is refused too: a grant that expires this instant is spent before the answer
+ * reaches the caller.
+ *
+ * `null` is untouched and stays what it always meant — a grant that does not expire on its own.
+ */
+export declare function requireFutureExpiry(expiresAt: string | null, now: Date): void;

package/dist/shared/grant-expiry/grant-expiry.js

@@ -0,0 +1,26 @@
+import { IntelError } from "../intel-error/intel-error.js";
+/**
+ * ⚠️ A grant whose expiry has already passed is refused, never written (#442).
+ *
+ * It would otherwise be created, answered with a `201`, and listed — while reaching nobody. The
+ * sharer reads the row as done; the grantee gets no notification and finds out days later, if at
+ * all. That is the failure mode this repository keeps meeting: something that looks like success,
+ * and the only feedback is the wrong one.
+ *
+ * ⚠️ The check cannot live in the Zod schema. That boundary knows nothing about `deps.now()`, and
+ * the rule is decided by the very clock that evaluates the grant afterwards — so it belongs in the
+ * application layer, where every surface passes through it. The `.describe()` on `expiresAt`
+ * documents the rule; this refuses it.
+ *
+ * ⚠️ Equal to `now` is refused too: a grant that expires this instant is spent before the answer
+ * reaches the caller.
+ *
+ * `null` is untouched and stays what it always meant — a grant that does not expire on its own.
+ */
+export function requireFutureExpiry(expiresAt, now) {
+    if (expiresAt === null)
+        return;
+    if (Date.parse(expiresAt) > now.getTime())
+        return;
+    throw new IntelError(400, "grant_already_expired", "A grant's expiry has to lie in the future; pass null for one that does not expire on its own");
+}

package/dist/shared/intel-error/intel-error.d.ts

@@ -0,0 +1,22 @@
+import type { NamedOrCounted } from "../../contract/contract.js";
+export declare class IntelError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly callers?: NamedOrCounted | undefined;
+    /**
+     * ⚠️ `callers` is what a refusal that NAMES flows carries beside its sentence — today
+     * `folder_execute_in_use` (#448) and `flow_in_use_by_flow` (#593). It rides on the error rather
+     * than on the route because the split it belongs to is an application-layer one: who may be named
+     * and who may only be counted is an authorization answer, and it must be the same over HTTP, over
+     * MCP and in the browser. A route that assembled it would be a second place for that rule to live.
+     *
+     * `message` still carries the finished English sentence — a reader that only takes text must lose
+     * nothing — and the field is what lets a screen say it in its own language instead.
+     *
+     * ⚠️ **Setting this field is only half of reaching MCP.** The SDK formats a thrown error through
+     * `createToolError`, which keeps `message` and drops everything else, so a tool whose handler is
+     * not wrapped in `refusing()` (`mcp/mcp.ts`) answers prose and nothing more (#597). Whoever
+     * attaches `callers` to a new refusal wraps that tool's handler in the same change.
+     */
+    constructor(status: number, code: string, message: string, callers?: NamedOrCounted | undefined);
+}

package/dist/shared/intel-error/intel-error.js

@@ -0,0 +1,27 @@
+export class IntelError extends Error {
+    status;
+    code;
+    callers;
+    /**
+     * ⚠️ `callers` is what a refusal that NAMES flows carries beside its sentence — today
+     * `folder_execute_in_use` (#448) and `flow_in_use_by_flow` (#593). It rides on the error rather
+     * than on the route because the split it belongs to is an application-layer one: who may be named
+     * and who may only be counted is an authorization answer, and it must be the same over HTTP, over
+     * MCP and in the browser. A route that assembled it would be a second place for that rule to live.
+     *
+     * `message` still carries the finished English sentence — a reader that only takes text must lose
+     * nothing — and the field is what lets a screen say it in its own language instead.
+     *
+     * ⚠️ **Setting this field is only half of reaching MCP.** The SDK formats a thrown error through
+     * `createToolError`, which keeps `message` and drops everything else, so a tool whose handler is
+     * not wrapped in `refusing()` (`mcp/mcp.ts`) answers prose and nothing more (#597). Whoever
+     * attaches `callers` to a new refusal wraps that tool's handler in the same change.
+     */
+    constructor(status, code, message, callers) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.callers = callers;
+        this.name = "IntelError";
+    }
+}

package/dist/shared/plain-title/plain-title.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ⚠️ A title is plain text, and an HTML entity in one is never what somebody meant.
+ *
+ * Intel escapes nothing, anywhere — the entity arrives already in the value (#202). The chain that
+ * carries a title to a write can HTML-escape what it hands to a model: the GitHub MCP server, for
+ * one, returns every string with `&` as `&` and `"` as `"`, so a model that copies a name
+ * out of one tool result into the next call writes the entity, not the character. Refusing the
+ * write would be the louder answer and the wrong one — the model reads the same escaped value
+ * again on its retry and cannot get past it. So the write boundary accepts it and stores what was
+ * meant.
+ *
+ * Repeated until it stops changing rather than once, because that is the failure the ticket names:
+ * a title read back escaped and written again is escaped twice, and a single round would leave
+ * `&` as `&` — still an entity, still spreading.
+ */
+export declare function plainTitle(title: string): string;

package/dist/shared/plain-title/plain-title.js

@@ -0,0 +1,45 @@
+// Exactly what an HTML escaper emits, and nothing else. `"` and `'` are Go's
+// `html.EscapeString` spelling of the quotes — the fingerprint of the tool that produced the
+// titles this exists for. A general entity table is deliberately not here: ` ` or `ä` in
+// a title is a person's choice, an escaped `&` never is.
+const Escapes = [
+    [/&lt;/g, "<"],
+    [/&gt;/g, ">"],
+    [/&quot;/g, '"'],
+    [/&#0*34;/g, '"'],
+    [/&apos;/g, "'"],
+    [/&#0*39;/g, "'"],
+    // Last in the pass, so one round of unescaping is the exact inverse of one round of escaping:
+    // `&amp;lt;` becomes `&lt;` here and only the NEXT round turns it into `<`.
+    [/&amp;/g, "&"],
+];
+// A title that survived one more escaping than any writer intended. Eight is far past anything a
+// real chain produces and stops a crafted title from spinning here.
+const MaxRounds = 8;
+/**
+ * ⚠️ A title is plain text, and an HTML entity in one is never what somebody meant.
+ *
+ * Intel escapes nothing, anywhere — the entity arrives already in the value (#202). The chain that
+ * carries a title to a write can HTML-escape what it hands to a model: the GitHub MCP server, for
+ * one, returns every string with `&` as `&amp;` and `"` as `&#34;`, so a model that copies a name
+ * out of one tool result into the next call writes the entity, not the character. Refusing the
+ * write would be the louder answer and the wrong one — the model reads the same escaped value
+ * again on its retry and cannot get past it. So the write boundary accepts it and stores what was
+ * meant.
+ *
+ * Repeated until it stops changing rather than once, because that is the failure the ticket names:
+ * a title read back escaped and written again is escaped twice, and a single round would leave
+ * `&amp;amp;` as `&amp;` — still an entity, still spreading.
+ */
+export function plainTitle(title) {
+    let current = title;
+    for (let round = 0; round < MaxRounds; round += 1) {
+        let next = current;
+        for (const [pattern, character] of Escapes)
+            next = next.replace(pattern, character);
+        if (next === current)
+            break;
+        current = next;
+    }
+    return current;
+}

package/dist/shared/problem-details/problem-details.d.ts

@@ -0,0 +1,30 @@
+import type { IntelError } from "../intel-error/intel-error.js";
+export declare function problemDetails(status: number, code: string, title: string, detail?: string): {
+    type: string;
+    status: number;
+    title: string;
+    detail?: string | undefined;
+    instance?: string | undefined;
+    code?: string | undefined;
+    callers?: {
+        titles: string[];
+        hidden: number;
+    } | undefined;
+};
+/**
+ * One refusal, one document — written here rather than at each `onError`, because two apps turn an
+ * `IntelError` into a body and an extension member added at one of them would silently be missing
+ * from the other (#448). Whatever the application layer decided to say travels with it.
+ */
+export declare function intelProblem(error: IntelError): {
+    type: string;
+    status: number;
+    title: string;
+    detail?: string | undefined;
+    instance?: string | undefined;
+    code?: string | undefined;
+    callers?: {
+        titles: string[];
+        hidden: number;
+    } | undefined;
+};

package/dist/shared/problem-details/problem-details.js

@@ -0,0 +1,18 @@
+import { ProblemDetails } from "../../contract/contract.js";
+export function problemDetails(status, code, title, detail) {
+    return ProblemDetails.parse({ type: "about:blank", status, code, title, detail });
+}
+/**
+ * One refusal, one document — written here rather than at each `onError`, because two apps turn an
+ * `IntelError` into a body and an extension member added at one of them would silently be missing
+ * from the other (#448). Whatever the application layer decided to say travels with it.
+ */
+export function intelProblem(error) {
+    return ProblemDetails.parse({
+        type: "about:blank",
+        status: error.status,
+        code: error.code,
+        title: error.message,
+        callers: error.callers,
+    });
+}

package/dist/shared/report-unexpected-error/report-unexpected-error.d.ts

@@ -0,0 +1 @@
+export declare function reportUnexpectedError(error: unknown): void;

package/dist/shared/report-unexpected-error/report-unexpected-error.js

@@ -0,0 +1,37 @@
+// A library error can quote whatever the peer sent — an echoed Authorization header, a token in a
+// URL, a response body. The log must show the failure and never the credential, so everything
+// shaped like one is cut before the line is written. The patterns match shapes, not sources: a JWT
+// is recognizable on its own, and other tokens only ever appear behind their label.
+function redact(text) {
+    // ⚠️ The order is load-bearing: "Authorization: Bearer x" must hit the bearer rule first — a
+    // combined alternation would let the label rule win the leftmost match, swallow the word
+    // "Bearer" as the value, and leave the token itself standing.
+    return text
+        .replace(/\beyJ[\w-]{4,}\.[\w-]+\.[\w-]*/g, "[redacted]")
+        .replace(/\b(bearer\s+)[\w.~+/-]+=*/gi, "$1[redacted]")
+        .replace(/\b((?:access_token|refresh_token|id_token|client_secret|api_key|authorization)"?\s*[:=]\s*"?)[\w.~+/-]+=*/gi, "$1[redacted]");
+}
+function describe(error) {
+    if (error instanceof Error)
+        return error.stack ?? `${error.name}: ${error.message}`;
+    if (typeof error === "string")
+        return error;
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+// openid-client wraps the informative part — the HTTP response, the OAuth error body — into
+// `cause`, so a log line without the cause chain would name the wrapper and hide the reason (#93).
+const MaxCauseDepth = 5;
+export function reportUnexpectedError(error) {
+    const parts = [];
+    let current = error;
+    for (let depth = 0; depth < MaxCauseDepth && current !== undefined; depth += 1) {
+        parts.push(describe(current));
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    console.error(redact(parts.join("\ncaused by: ")));
+}

package/dist/shared/safe-return-path/safe-return-path.d.ts

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export declare const SafeReturnPath: z.ZodString;

package/dist/shared/safe-return-path/safe-return-path.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+export const SafeReturnPath = z
+    .string()
+    .startsWith("/")
+    .refine((value) => !value.startsWith("//") &&
+    !value.startsWith("/\\") &&
+    !value.includes("\\") &&
+    ![...value].some((character) => {
+        const code = character.charCodeAt(0);
+        return code < 32 || code === 127;
+    }), "Return path must be a local absolute path");

package/dist/shared/sha256/sha256.d.ts

@@ -0,0 +1,2 @@
+export declare function hexDigest(digest: ArrayBuffer): string;
+export declare function sha256Hex(crypto: Crypto, content: string | ArrayBuffer | Uint8Array): Promise<string>;

package/dist/shared/sha256/sha256.js

@@ -0,0 +1,14 @@
+// The one place a digest becomes text. Both doors for an attachment write a `contentHash`: the
+// base64 one hashes a buffer it already holds, the streaming one takes its digest as the bytes pass
+// (#821). Two spellings of the same digest would make the two versions of one file look different.
+export function hexDigest(digest) {
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export async function sha256Hex(crypto, content) {
+    const source = typeof content === "string"
+        ? new TextEncoder().encode(content).buffer
+        : content instanceof Uint8Array
+            ? Uint8Array.from(content).buffer
+            : content;
+    return hexDigest(await crypto.subtle.digest("SHA-256", source));
+}