@mnemom/mnemom 0.17.37 → 0.17.38-next.1

package/dist/lib/scan/report-email.js

@@ -1,12 +1,13 @@
 /**
- * The report email: after every successful scan the person who ran it is emailed the report, with no
- * opt-out and at every share level. One call to `POST /v1/orgs/{org_id}/scan/report-email`
- * (mnemom-api#4270). The server resolves the runner's address from the signed-in identity, so the
- * request carries no runner address; `cto_email` is sent only when the user passed --cto-email.
+ * The report email: after every successful scan the full report, with the counts for each repo, is
+ * emailed to the person who ran it, every Org Admin of the org and anyone the runner added (MNE-9634),
+ * with no opt-out and at every share level. One call to `POST /v1/orgs/{org_id}/scan/report-email`.
+ * The server resolves the runner's address from the signed-in identity and the Org Admins from the org,
+ * so the request carries neither; `emails` holds only the extra addresses the runner added.
  *
- * The body is exactly the route's contract and nothing else: `report` (org-scan-report/1: team totals
- * and counts only), `share_level`, `coverage.complete` and the optional `cto_email`. No Record totals,
- * no repo names, no author, title, branch or body text, no credential.
+ * The body is exactly the route's contract and nothing else: `report` (org-scan-report/1: team totals,
+ * counts, and the per-repo counts `by_repo`), `share_level`, `coverage.complete` and the optional
+ * `emails`. No author, title, branch or body text, no credential.
  *
  * Every failure has a fixed name and fixed text. The server's body, the thrown value and the
  * credential never reach the terminal.
@@ -40,6 +41,7 @@ export function buildEmailReport(result, o) {
     // Only a scan that read every merged PR in the period gives an average that means anything.
     const exhaustive = coverage.complete && coverage.prsSkippedLarge === 0 && coverage.prsUnreadable === 0;
     const cost = buildCostPerPr(result.prSizes, o.period ?? { start: coverage.windowStart, end: coverage.windowEnd }, o.costSpend ?? null, exhaustive);
+    const byRepo = repoRows(result);
     return {
         schema_version: REPORT_SCHEMA_VERSION,
         org_id: o.orgId,
@@ -72,14 +74,38 @@ export function buildEmailReport(result, o) {
         },
         estimate: { name: ESTIMATE_NAME, value, unit, method_url: METHOD_URL },
         ...cost,
+        ...(byRepo.length > 0 ? { by_repo: byRepo } : {}),
     };
 }
-export function buildEmailBody(report, level, complete, ctoEmail) {
+const MAX_REPOS = 500;
+const REPO_NAME = /^[A-Za-z0-9._-]{1,100}\/[A-Za-z0-9._-]{1,100}$/;
+/** The per-repo rows for the report: valid names only, each once (any case), busiest first, at most 500. */
+function repoRows(result) {
+    const seen = new Set();
+    return [...result.byRepo]
+        .sort((a, b) => b.prs - a.prs || a.repo.localeCompare(b.repo))
+        .filter((r) => {
+        const k = r.repo.toLowerCase();
+        if (!REPO_NAME.test(r.repo) || seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    })
+        .slice(0, MAX_REPOS)
+        .map((r) => ({
+        repo: r.repo,
+        pr_count: r.prs,
+        revert_count: r.reverts,
+        automatable_count: r.ciGreen,
+        examined_count: r.examined,
+    }));
+}
+export function buildEmailBody(report, level, complete, extraEmails = []) {
     return {
         report,
         share_level: level,
         coverage: { complete },
-        ...(ctoEmail !== undefined ? { cto_email: ctoEmail } : {}),
+        ...(extraEmails.length > 0 ? { emails: extraEmails } : {}),
     };
 }
 const FAILURE_TEXT = {
@@ -89,7 +115,10 @@ const FAILURE_TEXT = {
     not_a_member: "your account is not a member of the org passed to --org.",
     report_rejected: "Mnemom rejected the report as malformed.",
     no_recipients: "the server accepted the report but reported zero recipients.",
-    runner_not_emailed: "the report was not delivered to you (the person who ran the scan); it may have gone only to the CTO. Re-run the scan, and check that your account has a valid email address.",
+    runner_not_emailed: "the report was not delivered to you (the person who ran the scan); it may have gone only to the others. Re-run the scan, and check that your account has a valid email address.",
+    emails_rejected: "an address you added was not accepted. Add up to 10 valid email addresses.",
+    email_domain_not_allowed: "an address you added is not on your organization's email domain. Add addresses on your own domain or mnemom.ai.",
+    admins_not_found: "Mnemom could not look up your org admins, so no email was sent. Try again in a moment.",
     network_error: "Mnemom could not be reached.",
     unexpected_response: "Mnemom answered in an unexpected way.",
 };
@@ -118,11 +147,27 @@ function classifyStatus(status) {
         return "report_rejected";
     return "unexpected_response";
 }
-/** The body without the optional cost figures; the same object when it carries none. */
-function withoutCostFigures(body) {
-    const { cost_per_merged_pr: _a, cost_by_pr_size: _b, ...rest } = body.report;
-    return "cost_per_merged_pr" in body.report || "cost_by_pr_size" in body.report
-        ? { ...body, report: rest }
+/**
+ * The body an API that predates this contract understands: no cost figures, no per-repo rows, and the
+ * share level under its old name (`analytics` was `summary`; the meaning is the same, never upgraded).
+ * The same object when nothing needs changing.
+ */
+function legacyBody(body) {
+    const { cost_per_merged_pr: _a, cost_by_pr_size: _b, by_repo: _c, ...rest } = body.report;
+    const changed = "cost_per_merged_pr" in body.report ||
+        "cost_by_pr_size" in body.report ||
+        "by_repo" in body.report ||
+        body.share_level === "analytics" ||
+        (body.emails?.length ?? 0) > 0;
+    const { emails, ...top } = body;
+    const extra = emails?.[0];
+    return changed
+        ? {
+            ...top,
+            ...(extra ? { cto_email: extra } : {}),
+            report: rest,
+            share_level: body.share_level === "analytics" ? "summary" : body.share_level,
+        }
         : body;
 }
 /** Never throws. The thrown value, the response body and the credential are never surfaced. */
@@ -135,15 +180,23 @@ export async function sendReportEmail(orgId, body, deps = {}) {
     catch (e) {
         if (e instanceof MnemomApiError && e.effectiveStatus === 404)
             return { status: "unavailable" };
-        // An API that predates the cost figures rejects the unknown keys with a 400. The email must still
-        // go out, so retry once with the figures left off; any other failure is classified as below.
+        // An API that predates the cost figures, the per-repo rows or the analytics name rejects them with a 400. The email must still
+        // go out, so retry once in the old shape; any other failure is classified as below.
         if (e instanceof MnemomApiError && e.effectiveStatus === 400) {
-            const bare = withoutCostFigures(body);
-            if (bare !== body)
-                return sendReportEmail(orgId, bare, deps);
+            const bare = legacyBody(body);
+            if (bare !== body && !/email|admin/i.test(e.code ?? "")) {
+                const r = await sendReportEmail(orgId, bare, deps);
+                return r.status === "sent" ? { ...r, limited: true } : r;
+            }
         }
         if (e instanceof MnemomApiError) {
             // A 4xx that names the runner (the API refuses a send that would skip the runner) gets its own text.
+            if (e.code === "email_domain_not_allowed")
+                return { status: "failed", reason: "email_domain_not_allowed" };
+            if (/emails/i.test(e.code ?? ""))
+                return { status: "failed", reason: "emails_rejected" };
+            if (e.code === "admin_lookup_failed")
+                return { status: "failed", reason: "admins_not_found" };
             if (e.effectiveStatus >= 400 && e.effectiveStatus < 500 && /runner/i.test(e.code ?? ""))
                 return { status: "failed", reason: "runner_not_emailed" };
             return { status: "failed", reason: classifyStatus(e.effectiveStatus) };
@@ -158,8 +211,11 @@ export async function sendReportEmail(orgId, body, deps = {}) {
         return { status: "failed", reason: "unexpected_response" };
     if (recipients === 0)
         return { status: "failed", reason: "no_recipients" };
-    // `skipped` lists the roles ("runner", "cto") that got no copy. The runner must always get the report.
+    // `skipped` lists the roles ("runner", "admin", "added", "cto") that got no copy. The runner must always get the report.
     if (Array.isArray(o.skipped) && o.skipped.includes("runner"))
         return { status: "failed", reason: "runner_not_emailed" };
-    return o.status === "dry_run" ? { status: "dry_run" } : { status: "sent", recipients };
+    const adminsMissed = Array.isArray(o.skipped) ? o.skipped.filter((s) => s === "admin").length : 0;
+    return o.status === "dry_run"
+        ? { status: "dry_run" }
+        : { status: "sent", recipients, ...(adminsMissed > 0 ? { adminsMissed } : {}) };
 }

package/dist/lib/scan/scan.d.ts

@@ -43,6 +43,8 @@ export interface RepoTotals {
     prs: number;
     reverts: number;
     ciGreen: number;
+    /** PRs read and counted (not reverts, not skipped); the per-repo base of the CI-green share. */
+    examined: number;
 }
 export interface ScanResult {
     coverage: Coverage;

package/dist/lib/scan/scan.js

@@ -104,7 +104,7 @@ export async function runLocalScan(deps, input) {
         const bucket = (repo) => {
             let b = byRepo.get(repo);
             if (!b)
-                byRepo.set(repo, (b = { repo, prs: 0, reverts: 0, ciGreen: 0 }));
+                byRepo.set(repo, (b = { repo, prs: 0, reverts: 0, ciGreen: 0, examined: 0 }));
             return b;
         };
         const totals = { prs: 0, reverts: 0, ciGreen: 0, examined: 0 };
@@ -142,6 +142,7 @@ export async function runLocalScan(deps, input) {
             }
             totals.prs += 1;
             totals.examined += 1;
+            bucket(repo).examined += 1;
             bucket(repo).prs += 1;
             if (rec.ci === "success") {
                 totals.ciGreen += 1;

package/dist/lib/scan/share.d.ts

@@ -1,20 +1,21 @@
 import type { ScanResult } from "./scan.js";
-export type ShareLevel = "summary" | "full" | "none";
+export type ShareLevel = "full" | "analytics" | "none";
 /** The level preselected at the prompt (Enter picks it). */
 export declare const DEFAULT_SHARE_LEVEL: ShareLevel;
 export declare const SHARE_OPTIONS: ReadonlyArray<{
     level: ShareLevel;
     label: string;
 }>;
-/** Shown just above the share prompt, so pressing Enter is an informed choice. */
+/** Shown just above the prompt. The full report, repo names included, is emailed whatever is chosen here. */
 export declare const SHARE_DISCLOSURE: string;
 /** Asks the user, with Full preselected. Anything but a recognised answer (cancel, EOF, noise) is "none": fail closed. */
 export declare function promptShareLevel(): Promise<ShareLevel>;
+/** `summary` is the old name for `analytics`; the meaning is unchanged. */
 export declare function parseShareLevel(v: string | undefined): ShareLevel | null;
-/** Who receives the report. Sent only with a non-"none" share level. */
+/** Who receives the report. The runner comes from the Mnemom login; the server resolves the Org Admins. */
 export interface ReportRecipients {
-    runner_email: string;
-    cto_email: string;
+    runner_email?: string;
+    extra_emails: string[];
 }
 export interface SharePayload {
     recipients: ReportRecipients;
@@ -30,6 +31,7 @@ export interface SharePayload {
     coverage_complete: boolean;
     /** Absent when no spend line may be shown. */
     spend_line?: string;
+    /** Present at "full" only. */
     repos?: Array<{
         repo: string;
         prs: number;
@@ -37,6 +39,6 @@ export interface SharePayload {
         ci_green: number;
     }>;
 }
-/** Builds only what the level allows. Never includes authors, titles, branches, bodies or tokens. The only person data is the two report recipients. */
+/** Builds only what the level allows. Never includes authors, titles, branches, bodies or tokens. The only person data is the report recipients. */
 export declare function buildSharePayload(level: Exclude<ShareLevel, "none">, r: ScanResult, recipients: ReportRecipients, spendLine?: string | null): SharePayload;
 export declare function buildSharePayload(level: ShareLevel, r: ScanResult, recipients: ReportRecipients, spendLine?: string | null): SharePayload | null;

package/dist/lib/scan/share.js

@@ -1,32 +1,49 @@
 /**
- * Share level: what, if anything, may leave the machine. Asked before any output is built for sharing.
- * Full is the preselected choice (MNE-9619): pressing Enter at the prompt picks it. "none" yields no
- * payload at all, and is what a cancelled, empty-piped or non-interactive prompt resolves to (fail closed).
+ * "What may Mnemom keep on file?" (MNE-9634). This is a retention choice only; it never changes what is emailed. It is asked at
+ * the start, before any scan work. The scan itself is always complete: the full report, with the counts
+ * for each repo, is emailed to the runner, every Org Admin and anyone the runner adds, at every level.
+ *
+ *   full       Mnemom keeps the totals and the counts for each repo, by name, on file (the default).
+ *   analytics  Mnemom keeps the team totals only, with no repo names. `summary` is the old name for this
+ *              and is accepted as an alias; it is never upgraded to full.
+ *   none       Mnemom keeps nothing on file. The report is still emailed.
+ *
+ * "none" is what a cancelled, empty-piped or non-interactive prompt resolves to (fail closed).
+ * Storing the shared payload on Mnemom's side is not built yet; the CLI only prints it.
  */
 import { askSelect } from "../prompt.js";
 /** The level preselected at the prompt (Enter picks it). */
 export const DEFAULT_SHARE_LEVEL = "full";
 export const SHARE_OPTIONS = [
-    { level: "summary", label: "Summary metrics only (counts and one estimate line)" },
-    { level: "full", label: "Full report (summary plus per-repo counts; default)" },
-    { level: "none", label: "Nothing (keep results on this machine)" },
+    {
+        level: "full",
+        label: "Full report (default): Mnemom keeps the totals and the counts for each repo, by name, on file",
+    },
+    {
+        level: "analytics",
+        label: "Analytics: Mnemom keeps the team totals only on file, with no repo names",
+    },
+    { level: "none", label: "Nothing: Mnemom keeps nothing on file" },
 ];
-/** Shown just above the share prompt, so pressing Enter is an informed choice. */
+/** Shown just above the prompt. The full report, repo names included, is emailed whatever is chosen here. */
 export const SHARE_DISCLOSURE = [
-    "Pressing Enter shares the Full report: the whole report, including your repo names and per-repo counts.",
-    "It is emailed to the report recipients. To share less, choose 1 (Summary: counts only, no repo names) or 3 (Nothing).",
+    "Whatever you choose, the full report, including repo names, is emailed to you, your org's admins and any addresses you added.",
+    "The next question is only about what Mnemom keeps on file. Pressing Enter chooses the Full report.",
 ].join("\n");
 /** Asks the user, with Full preselected. Anything but a recognised answer (cancel, EOF, noise) is "none": fail closed. */
 export async function promptShareLevel() {
     // eslint-disable-next-line no-console -- consent text must show on stdout directly above the prompt (askSelect also prints with console.log)
     console.log(SHARE_DISCLOSURE);
-    const answer = await askSelect("What may leave this machine?", SHARE_OPTIONS.map((o) => o.label), SHARE_OPTIONS.findIndex((o) => o.level === DEFAULT_SHARE_LEVEL));
+    const answer = await askSelect("What may Mnemom keep on file?", SHARE_OPTIONS.map((o) => o.label), SHARE_OPTIONS.findIndex((o) => o.level === DEFAULT_SHARE_LEVEL));
     if (answer === null)
         return "none";
     return SHARE_OPTIONS.find((o) => o.label === answer)?.level ?? "none";
 }
+/** `summary` is the old name for `analytics`; the meaning is unchanged. */
 export function parseShareLevel(v) {
-    return v === "summary" || v === "full" || v === "none" ? v : null;
+    if (v === "summary")
+        return "analytics";
+    return v === "analytics" || v === "full" || v === "none" ? v : null;
 }
 export function buildSharePayload(level, r, recipients, 
 /** undefined: the legacy line; null: no spend line; string: that line. */

package/dist/lib/scan/spend/anthropic-usage.d.ts

@@ -1,12 +1,24 @@
 export declare const ANTHROPIC_ADMIN_ORIGIN = "https://api.anthropic.com";
 export declare const ADMIN_KEY_ENV = "ANTHROPIC_ADMIN_KEY";
+/** The only paths a usage credential is ever sent to (design T18: fenced to report endpoints). */
+export declare const REPORT_PATHS: readonly string[];
+/** The fence, as one exported check so it is directly testable. Throws AnthropicUsageError for any other path. */
+export declare function assertReportPath(path: string): void;
+/** The exact auth header to send; same shape as mnemom-api src/org-scan/usage/credential-source.ts. */
+export type AnthropicAuthHeader = {
+    header: "x-api-key";
+    value: string;
+} | {
+    header: "authorization";
+    value: string;
+};
 export declare const DEFAULT_MAX_PAGES = 20;
 /** One shared deadline for a request including its retries (not N x timeout). */
 export declare const DEFAULT_TIMEOUT_MS = 15000;
 export declare const DEFAULT_MAX_RETRIES = 2;
 /** Shape check only; the key is never echoed, even on a mismatch. */
 export declare const isAdminKeyShape: (k: unknown) => k is string;
-export type UsageFailure = "key_invalid" | "key_refused" | "rate_limited" | "timeout" | "network" | "upstream" | "malformed" | "too_large";
+export type UsageFailure = "key_invalid" | "key_refused" | "token_refused" | "rate_limited" | "timeout" | "network" | "upstream" | "malformed" | "too_large";
 /** Fixed sentence for a failure reason. */
 export declare const usageFailureText: (r: UsageFailure) => string;
 /** Carries only a reason tag. Its message is the fixed sentence: nothing upstream can reach it. */
@@ -55,3 +67,10 @@ export declare function fetchMeasuredUsage(key: string | undefined, period: {
     start: string;
     end: string;
 }, deps?: AnthropicUsageDeps): Promise<MeasuredUsage>;
+/** A WIF access token as the bearer for the two report reads. Printable ASCII only, else key_invalid. */
+export declare function bearerAuth(token: string): AnthropicAuthHeader;
+/** The two reads with an already-resolved credential (pasted key or WIF bearer). Throws AnthropicUsageError only. */
+export declare function fetchMeasuredUsageWithAuth(auth: AnthropicAuthHeader, period: {
+    start: string;
+    end: string;
+}, deps?: AnthropicUsageDeps): Promise<MeasuredUsage>;

package/dist/lib/scan/spend/anthropic-usage.js

@@ -1,6 +1,11 @@
 // MNE-9298 Tier 1: the CTO's own Anthropic Admin key, used LOCALLY, to read measured usage. Port of
 // mnemom-api src/org-scan/usage/usage-client.ts (two read-only GETs: usage_report/messages grouped by
-// context_window, and cost_report) with the server-only parts (egress allowlist, WIF) dropped.
+// context_window, and cost_report) with the server-only parts (egress allowlist) dropped.
+//
+// MNE-9706: the reads take either credential, as the server's credential-source.ts does: the pasted Admin
+// key (x-api-key) or a short-lived WIF access token (Authorization: Bearer, see anthropic-wif.ts). Either
+// one is sent ONLY to the two report paths below; walk() refuses any other path (the fence, design T18:
+// Anthropic's WIF scope for these reports is org:admin, so the fence has to live here).
 //
 // The key is held in memory for the length of the two reads. It is never stored, logged, written to disk,
 // echoed, put in argv, a URL or an error message, and is sent only to api.anthropic.com (a constant, not
@@ -11,6 +16,13 @@ export const ADMIN_KEY_ENV = "ANTHROPIC_ADMIN_KEY";
 const ANTHROPIC_VERSION = "2023-06-01";
 const USAGE_PATH = "/v1/organizations/usage_report/messages";
 const COST_PATH = "/v1/organizations/cost_report";
+/** The only paths a usage credential is ever sent to (design T18: fenced to report endpoints). */
+export const REPORT_PATHS = [USAGE_PATH, COST_PATH];
+/** The fence, as one exported check so it is directly testable. Throws AnthropicUsageError for any other path. */
+export function assertReportPath(path) {
+    if (!REPORT_PATHS.includes(path))
+        throw new AnthropicUsageError("malformed");
+}
 export const DEFAULT_MAX_PAGES = 20;
 /** One shared deadline for a request including its retries (not N x timeout). */
 export const DEFAULT_TIMEOUT_MS = 15_000;
@@ -22,6 +34,7 @@ export const isAdminKeyShape = (k) => typeof k === "string" && ADMIN_KEY_RE.test
 const FAILURE_TEXT = {
     key_invalid: "The Anthropic admin key is not an Admin API key (it should start with sk-ant-admin).",
     key_refused: "Anthropic refused the admin key (401/403).",
+    token_refused: "Anthropic refused the workload identity token for the usage reports (401/403). The federation rule needs scope org:admin.",
     rate_limited: "Anthropic rate limit reached.",
     timeout: "Anthropic did not answer in time.",
     network: "Anthropic was unreachable.",
@@ -96,14 +109,14 @@ function retryWait(res, attempt) {
     return Number.isFinite(ra) && ra > 0 ? ra * 1000 : backoff(attempt);
 }
 class Reader {
-    key;
+    auth;
     fetchImpl;
     sleep;
     maxPages;
     timeoutMs;
     maxRetries;
-    constructor(key, deps) {
-        this.key = key;
+    constructor(auth, deps) {
+        this.auth = auth;
         this.fetchImpl = deps.fetchImpl ?? ((...a) => fetch(...a));
         this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
         this.maxPages = deps.maxPages ?? DEFAULT_MAX_PAGES;
@@ -111,6 +124,8 @@ class Reader {
         this.maxRetries = deps.maxRetries ?? DEFAULT_MAX_RETRIES;
     }
     async walk(path, base, parse, callMaxPages) {
+        // The fence: the credential goes to the two report paths and nowhere else.
+        assertReportPath(path);
         const ceiling = typeof callMaxPages === "number" && Number.isFinite(callMaxPages) && callMaxPages >= 1
             ? Math.min(this.maxPages, Math.floor(callMaxPages))
             : this.maxPages;
@@ -154,7 +169,7 @@ class Reader {
                 res = await this.fetchImpl(url, {
                     method: "GET",
                     headers: {
-                        "x-api-key": this.key,
+                        [this.auth.header]: this.auth.value,
                         "anthropic-version": ANTHROPIC_VERSION,
                         accept: "application/json",
                     },
@@ -185,7 +200,7 @@ class Reader {
             }
             await res.body?.cancel().catch(() => { });
             if (res.status === 401 || res.status === 403)
-                throw new AnthropicUsageError("key_refused");
+                throw new AnthropicUsageError(this.auth.header === "x-api-key" ? "key_refused" : "token_refused");
             const retryable = res.status === 429 || res.status >= 500;
             const wait = retryable ? retryWait(res, attempt + 1) : 0;
             if (retryable &&
@@ -209,11 +224,21 @@ export async function fetchMeasuredUsage(key, period, deps = {}) {
     const k = key?.trim();
     if (!k || !isAdminKeyShape(k))
         throw new AnthropicUsageError("key_invalid");
+    return fetchMeasuredUsageWithAuth({ header: "x-api-key", value: k }, period, deps);
+}
+/** A WIF access token as the bearer for the two report reads. Printable ASCII only, else key_invalid. */
+export function bearerAuth(token) {
+    if (!/^[\x21-\x7e]{8,4096}$/.test(token))
+        throw new AnthropicUsageError("key_invalid");
+    return { header: "authorization", value: `Bearer ${token}` };
+}
+/** The two reads with an already-resolved credential (pasted key or WIF bearer). Throws AnthropicUsageError only. */
+export async function fetchMeasuredUsageWithAuth(auth, period, deps = {}) {
     if (!validDay(period.start) || !validDay(period.end))
         throw new AnthropicUsageError("malformed");
     const startingAt = alignStartingAt(`${period.start}T00:00:00Z`);
     const endingAt = new Date(Date.parse(`${period.end}T00:00:00Z`) + DAY_MS).toISOString();
-    const reader = new Reader(k, deps);
+    const reader = new Reader(auth, deps);
     const up = new URLSearchParams({
         starting_at: startingAt,
         ending_at: endingAt,

package/dist/lib/scan/spend/anthropic-wif.d.ts

@@ -0,0 +1,42 @@
+export declare const WIF_EXCHANGE_URL = "https://api.anthropic.com/v1/oauth/token";
+export declare const WIF_ENV: {
+    readonly rule: "ANTHROPIC_FEDERATION_RULE_ID";
+    readonly org: "ANTHROPIC_ORGANIZATION_ID";
+    readonly serviceAccount: "ANTHROPIC_SERVICE_ACCOUNT_ID";
+    readonly workspace: "ANTHROPIC_WORKSPACE_ID";
+};
+/** Same ceiling the server held a WIF token to (credential-source.ts MAX_WIF_TOKEN_LIFETIME_MS). */
+export declare const MAX_WIF_TOKEN_LIFETIME_MS = 300000;
+export interface WifConfig {
+    federationRuleId: string;
+    organizationId: string;
+    serviceAccountId: string;
+    workspaceId?: string;
+}
+export type WifFailure = "config_invalid" | "assertion_unavailable" | "assertion_refused" | "exchange_refused" | "exchange_failed";
+export declare const wifFailureText: (r: WifFailure) => string;
+export declare const WIF_FALLBACK_NOTE = "Falling back to the pasted Anthropic Admin key.";
+/** Carries only a reason tag; its message is the fixed sentence. */
+export declare class WifError extends Error {
+    readonly reason: WifFailure;
+    constructor(reason: WifFailure);
+}
+/**
+ * Reads the WIF ids from env. None of the three required ids set: null (WIF is not set up, no message).
+ * Some set, or any malformed: WifError("config_invalid"), so a half-done setup is said out loud.
+ */
+export declare function readWifConfig(env: NodeJS.ProcessEnv): WifConfig | null;
+export interface WifDeps {
+    /** Step 1 seam: returns the assertion for the org. Defaults to the mnemom-api route with the CLI's auth. */
+    mintAssertion?: (orgId: string) => Promise<unknown>;
+    /** Step 2 seam: the fetch used ONLY for the Anthropic exchange. */
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+export interface WifAccessToken {
+    accessToken: string;
+    /** Epoch ms, clamped to MAX_WIF_TOKEN_LIFETIME_MS from receipt. */
+    expiresAt: number;
+}
+/** Steps 1 and 2. Throws WifError only. */
+export declare function obtainWifAccessToken(orgId: string, cfg: WifConfig, deps?: WifDeps): Promise<WifAccessToken>;

package/dist/lib/scan/spend/anthropic-wif.js

@@ -0,0 +1,153 @@
+// MNE-9706 (S2.6, design T18): read the Anthropic Console through workload identity federation (WIF).
+//
+// Three steps, all from this machine:
+//   1. Ask mnemom-api for a short-lived OIDC identity token (the "assertion") for the org, with the user's
+//      own CLI sign-in: POST /v1/orgs/{org_id}/scan/wif-assertion. Its sub is `mnemom:org:<org_id>`.
+//   2. Exchange it DIRECTLY at Anthropic (POST https://api.anthropic.com/v1/oauth/token, RFC 7523
+//      jwt-bearer) for a short-lived access token. Mnemom never sees that token.
+//   3. Hand the token to the usage reader, which sends it only to the two report paths (the fence).
+//
+// The customer's Console holds the federation issuer, service account and rule. The CLI needs only their
+// non-secret ids, read from Anthropic's own variable names (ANTHROPIC_FEDERATION_RULE_ID,
+// ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, optional ANTHROPIC_WORKSPACE_ID).
+//
+// The assertion and the access token live in memory for one scan and are never logged, stored, printed,
+// put in argv, a URL or an error message. Every failure is a fixed sentence (WifFailure), so the caller can
+// fall back to the pasted Admin key with a clear message.
+import { MnemomApiError, postApi } from "../../api.js";
+import { ANTHROPIC_ADMIN_ORIGIN } from "./anthropic-usage.js";
+export const WIF_EXCHANGE_URL = `${ANTHROPIC_ADMIN_ORIGIN}/v1/oauth/token`;
+export const WIF_ENV = {
+    rule: "ANTHROPIC_FEDERATION_RULE_ID",
+    org: "ANTHROPIC_ORGANIZATION_ID",
+    serviceAccount: "ANTHROPIC_SERVICE_ACCOUNT_ID",
+    workspace: "ANTHROPIC_WORKSPACE_ID",
+};
+/** Same ceiling the server held a WIF token to (credential-source.ts MAX_WIF_TOKEN_LIFETIME_MS). */
+export const MAX_WIF_TOKEN_LIFETIME_MS = 300_000;
+const EXCHANGE_TIMEOUT_MS = 15_000;
+const WIF_TEXT = {
+    config_invalid: "The Anthropic workload identity settings are incomplete or malformed (federation rule, organization and service account ids).",
+    assertion_unavailable: "Mnemom could not issue a workload identity token for this org right now.",
+    assertion_refused: "Mnemom did not issue a workload identity token (sign in as an owner or admin of an org with Org Scan on).",
+    exchange_refused: "Anthropic refused the workload identity token. Check the federation rule in your Anthropic Console (its issuer, subject and scope org:admin).",
+    exchange_failed: "Anthropic's token exchange could not be completed.",
+};
+export const wifFailureText = (r) => WIF_TEXT[r];
+export const WIF_FALLBACK_NOTE = "Falling back to the pasted Anthropic Admin key.";
+/** Carries only a reason tag; its message is the fixed sentence. */
+export class WifError extends Error {
+    reason;
+    constructor(reason) {
+        super(WIF_TEXT[reason]);
+        this.reason = reason;
+        this.name = "WifError";
+    }
+}
+const RULE_RE = /^fdrl_[A-Za-z0-9]{1,128}$/;
+const SVAC_RE = /^svac_[A-Za-z0-9]{1,128}$/;
+const WRKSPC_RE = /^wrkspc_[A-Za-z0-9]{1,128}$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Reads the WIF ids from env. None of the three required ids set: null (WIF is not set up, no message).
+ * Some set, or any malformed: WifError("config_invalid"), so a half-done setup is said out loud.
+ */
+export function readWifConfig(env) {
+    const get = (k) => {
+        const v = env[k]?.trim();
+        return v ? v : undefined;
+    };
+    const rule = get(WIF_ENV.rule);
+    const org = get(WIF_ENV.org);
+    const svac = get(WIF_ENV.serviceAccount);
+    const ws = get(WIF_ENV.workspace);
+    if (!rule && !org && !svac)
+        return null;
+    if (!rule || !org || !svac)
+        throw new WifError("config_invalid");
+    if (!RULE_RE.test(rule) || !UUID_RE.test(org) || !SVAC_RE.test(svac))
+        throw new WifError("config_invalid");
+    if (ws !== undefined && !WRKSPC_RE.test(ws))
+        throw new WifError("config_invalid");
+    return {
+        federationRuleId: rule,
+        organizationId: org,
+        serviceAccountId: svac,
+        ...(ws ? { workspaceId: ws } : {}),
+    };
+}
+const JWT_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+async function defaultMint(orgId) {
+    return postApi(`/v1/orgs/${encodeURIComponent(orgId)}/scan/wif-assertion`, {});
+}
+/** Steps 1 and 2. Throws WifError only. */
+export async function obtainWifAccessToken(orgId, cfg, deps = {}) {
+    const now = deps.now ?? Date.now;
+    let assertion;
+    try {
+        const body = await (deps.mintAssertion ?? defaultMint)(orgId);
+        const a = body && typeof body === "object" ? body.assertion : undefined;
+        if (typeof a !== "string" || a.length > 16_384 || !JWT_RE.test(a))
+            throw new WifError("assertion_unavailable");
+        assertion = a;
+    }
+    catch (e) {
+        if (e instanceof WifError)
+            throw e;
+        const status = e instanceof MnemomApiError ? e.effectiveStatus : 0;
+        // 401/403 is "not you"; 404 is the dark route (Org Scan off for this org). Both: no token for you.
+        throw new WifError(status === 401 || status === 403 || status === 404
+            ? "assertion_refused"
+            : "assertion_unavailable");
+    }
+    const fetchImpl = deps.fetchImpl ?? ((...a) => fetch(...a));
+    let res;
+    try {
+        res = await fetchImpl(WIF_EXCHANGE_URL, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({
+                grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+                assertion,
+                federation_rule_id: cfg.federationRuleId,
+                organization_id: cfg.organizationId,
+                service_account_id: cfg.serviceAccountId,
+                ...(cfg.workspaceId ? { workspace_id: cfg.workspaceId } : {}),
+            }),
+            // A redirect would carry the assertion elsewhere: refuse to follow one.
+            redirect: "error",
+            signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
+        });
+    }
+    catch {
+        // Never surface the thrown value: it can carry the request.
+        throw new WifError("exchange_failed");
+    }
+    if (!res.ok) {
+        await res.body?.cancel().catch(() => { });
+        throw new WifError(res.status === 400 || res.status === 401 || res.status === 403
+            ? "exchange_refused"
+            : "exchange_failed");
+    }
+    let json;
+    try {
+        json = await res.json();
+    }
+    catch {
+        throw new WifError("exchange_failed");
+    }
+    const b = json && typeof json === "object" ? json : {};
+    const token = b.access_token;
+    if (typeof token !== "string" || !/^[\x21-\x7e]{8,4096}$/.test(token))
+        throw new WifError("exchange_failed");
+    if (b.token_type !== undefined && String(b.token_type).toLowerCase() !== "bearer")
+        throw new WifError("exchange_failed");
+    const secs = typeof b.expires_in === "number" && Number.isFinite(b.expires_in) && b.expires_in > 0
+        ? b.expires_in
+        : 300;
+    const t = now();
+    return {
+        accessToken: token,
+        expiresAt: Math.min(t + secs * 1000, t + MAX_WIF_TOKEN_LIFETIME_MS),
+    };
+}