@centerforagenticai/pi-multi-account 0.1.1

package/src/coverage-attestation.ts

@@ -0,0 +1,397 @@
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { join, relative } from "node:path";
+import {
+	HISTORY_SCHEMA_VERSION,
+	iterateHistory,
+	type HistoryLogRecord,
+	type HistoryRecordEnvelope,
+	type HistoryGapRecord,
+} from "./history-store.js";
+
+const MAX_ATTESTATION_BYTES = 4096;
+const SUPPORTED_ATTESTATION_VERSION = 1;
+
+// The canonical emitter build identity for history records
+// Must match the buildProvenance field in WindowSample/CostRecord
+const CANONICAL_BUILD_IDENTITY = "pi-multi-account@0.1.0";
+
+export type CoverageState = "unknown" | "partial" | "complete";
+
+export interface CoverageAttestation {
+	readonly attestationVersion: number;
+	readonly historySchemaVersion: number;
+	readonly buildProvenance: string;
+	readonly attestedAtMs: number;
+}
+
+/**
+ * Conjuncts verified for 'complete' coverage state.
+ *
+ * REQ-COVERAGE-STATE defines 'complete' as requiring FIVE conjuncts:
+ * 1. period wholly at/after attestedAtMs (VERIFIED in node 4)
+ * 2. period wholly inside retained history (DEFERRED to node 5)
+ * 3. all records match attested schema (DEFERRED to node 5)
+ * 4. all records match attested build provenance (DEFERRED to node 5)
+ * 5. no known gap in the period (DEFERRED to node 5)
+ *
+ * This type-level marker prevents node 5's integrator from misreading
+ * 'complete' as fully verified when only the period-timing conjunct has
+ * been checked. Node 5 must wire the remaining four and update this field.
+ */
+export type VerifiedConjunct =
+	| "period-timing"
+	| "retained-history"
+	| "schema-match"
+	| "build-match"
+	| "no-gap";
+
+export interface CoverageResult {
+	readonly state: CoverageState;
+	readonly reason?: string;
+	/**
+	 * Which coverage conjuncts were actually verified.
+	 *
+	 * A 'complete' result from node 4 carries ONLY ["period-timing"].
+	 * Node 5 must add the remaining four before emitting a total.
+	 */
+	readonly verifiedConjuncts: readonly VerifiedConjunct[];
+}
+
+export type AttestationRejectionReason =
+	| "symlink"
+	| "not-regular-file"
+	| "insecure-mode"
+	| "wrong-owner"
+	| "outside-base-dir"
+	| "oversize"
+	| "malformed"
+	| "version-mismatch"
+	| "schema-mismatch"
+	| "build-mismatch"
+	| "future-attested-at"
+	| "missing"
+	| "symlinked-base-dir";
+
+export type AttestationResult =
+	| { readonly ok: true; readonly attestation: CoverageAttestation }
+	| { readonly ok: false; readonly reason: AttestationRejectionReason };
+
+/**
+ * Read and validate the fleet-currency attestation file.
+ *
+ * REQ-COVERAGE-STATE: 0013 NEVER creates, modifies, or deletes this file.
+ * This is a READ-ONLY validator.
+ *
+ * Valid ONLY when ALL of these hold:
+ * - a bounded regular file (NOT a symlink)
+ * - owned by the current user
+ * - mode 0600
+ * - beneath the owner-only machine-global extension directory
+ * - contains exactly: a supported attestation version, the current history
+ *   schema version, the current canonical emitter build identity, and a
+ *   finite non-future attestedAtMs
+ *
+ * Missing, malformed, insecure, or mismatched -> rollout currency UNPROVEN.
+ *
+ * SECURITY NOTE: Uses lstatSync (NOT statSync) to detect symlinks without
+ * following them, plus realpathSync containment check. Mirrors the pattern
+ * from history-store.ts validateAppendPath.
+ */
+export function readCoverageAttestation(
+	extensionDir?: string,
+): AttestationResult {
+	// Package storage identity stays decoupled from the logical provider ID.
+	const baseDir =
+		extensionDir ??
+		join(
+			process.env.PI_CODING_AGENT_DIR ??
+				join(process.env.HOME ?? ".", ".pi", "agent"),
+			"pi-multi-account",
+		);
+
+	const attestationPath = join(baseDir, "history-coverage-attestation.json");
+
+	try {
+		// REQ-STORE-PERMISSIONS: Reject symlinked base directory
+		// If baseDir is a symlink pointing at a victim directory, an attacker
+		// could place a valid-looking attestation there and bypass currency checks.
+		const baseDirStats = lstatSync(baseDir);
+		if (baseDirStats.isSymbolicLink()) {
+			return { ok: false, reason: "symlinked-base-dir" };
+		}
+
+		const resolvedBase = realpathSync(baseDir);
+
+		// REQ-COVERAGE-STATE: must be a bounded regular NON-SYMLINK
+		const stats = lstatSync(attestationPath);
+
+		if (stats.isSymbolicLink()) {
+			// Symlink - REJECT without following
+			return { ok: false, reason: "symlink" };
+		}
+
+		if (!stats.isFile()) {
+			return { ok: false, reason: "not-regular-file" };
+		}
+
+		// Bounded size check
+		if (stats.size > MAX_ATTESTATION_BYTES) {
+			return { ok: false, reason: "oversize" };
+		}
+
+		// REQ-COVERAGE-STATE: must be owned by the current user
+		if (stats.uid !== process.getuid?.()) {
+			return { ok: false, reason: "wrong-owner" };
+		}
+
+		// REQ-COVERAGE-STATE: must be mode 0600
+		// biome-ignore lint/suspicious/noMagicNumbers: POSIX permission bits
+		if ((stats.mode & 0o777) !== 0o600) {
+			return { ok: false, reason: "insecure-mode" };
+		}
+
+		// REQ-STORE-PERMISSIONS: containment check - must be within baseDir
+		//
+		// DEFENSE-IN-DEPTH: This guard is unreachable via normal filesystem operations
+		// given the guard ordering above. Since attestationPath is constructed as
+		// join(baseDir, "history-coverage-attestation.json"), and both paths are
+		// resolved through realpathSync:
+		// - If baseDir itself is a symlink → caught by symlinked-base-dir guard
+		// - If attestationPath is a symlink → caught by isSymbolicLink() guard
+		// - If a parent component of baseDir is a symlink → both paths resolve
+		//   through it and remain contained
+		//
+		// This check protects against implementation bugs in realpathSync/relative
+		// or exotic filesystem features, but cannot be triggered through standard
+		// symlink-based directory traversal.
+		const resolvedAttestation = realpathSync(attestationPath);
+		const rel = relative(resolvedBase, resolvedAttestation);
+
+		// Valid if:
+		// - Non-empty (not the base itself)
+		// - Doesn't start with '..' (not outside base)
+		// - Not absolute (different roots)
+		if (
+			!rel ||
+			rel.startsWith("..") ||
+			relative(resolvedBase, resolvedAttestation).startsWith("/")
+		) {
+			return { ok: false, reason: "outside-base-dir" };
+		}
+
+		// Read and parse
+		const raw = readFileSync(attestationPath, "utf8");
+		const parsed: unknown = JSON.parse(raw);
+
+		if (
+			typeof parsed !== "object" ||
+			parsed === null ||
+			Array.isArray(parsed)
+		) {
+			return { ok: false, reason: "malformed" };
+		}
+
+		const record = parsed as Record<string, unknown>;
+
+		// REQ-COVERAGE-STATE: validate required fields
+		if (
+			typeof record.attestationVersion !== "number" ||
+			typeof record.historySchemaVersion !== "number" ||
+			typeof record.buildProvenance !== "string" ||
+			typeof record.attestedAtMs !== "number"
+		) {
+			return { ok: false, reason: "malformed" };
+		}
+
+		// REQ-COVERAGE-STATE: supported attestation version
+		if (record.attestationVersion !== SUPPORTED_ATTESTATION_VERSION) {
+			return { ok: false, reason: "version-mismatch" };
+		}
+
+		// REQ-COVERAGE-STATE: must match current history schema version
+		if (record.historySchemaVersion !== HISTORY_SCHEMA_VERSION) {
+			return { ok: false, reason: "schema-mismatch" };
+		}
+
+		// REQ-COVERAGE-STATE: must match current canonical build identity
+		if (record.buildProvenance !== CANONICAL_BUILD_IDENTITY) {
+			return { ok: false, reason: "build-mismatch" };
+		}
+
+		// REQ-COVERAGE-STATE: finite non-future attestedAtMs
+		if (
+			!Number.isFinite(record.attestedAtMs) ||
+			record.attestedAtMs < 0 ||
+			record.attestedAtMs > Date.now()
+		) {
+			return { ok: false, reason: "future-attested-at" };
+		}
+
+		return {
+			ok: true,
+			attestation: {
+				attestationVersion: record.attestationVersion,
+				historySchemaVersion: record.historySchemaVersion,
+				buildProvenance: record.buildProvenance,
+				attestedAtMs: record.attestedAtMs,
+			},
+		};
+	} catch (err) {
+		// JSON parse errors return malformed; file not found returns missing
+		if (err instanceof SyntaxError) {
+			return { ok: false, reason: "malformed" };
+		}
+		return { ok: false, reason: "missing" };
+	}
+}
+
+/**
+ * Compute coverage state for a requested time period.
+ *
+ * REQ-COVERAGE-STATE coverage states:
+ * - `unknown`: rollout currency or fleet membership unproven (no attestation,
+ *   or attestation invalid/mismatched)
+ * - `partial`: valid attestation exists BUT one or more of the five required
+ *   conjuncts is unverified (period timing, retained history, schema match,
+ *   build match, no gap)
+ * - `complete`: ONLY when the period lies wholly at or after attestedAtMs,
+ *   wholly inside retained history, all records match attested schema and
+ *   build provenance, and no known gap exists
+ *
+ * No unqualified total may be emitted unless coverage is `complete`.
+ *
+ * Implementation verifies ALL FIVE conjuncts:
+ * 1. period-timing: period wholly at/after attestedAtMs
+ * 2. retained-history: period wholly inside retained history
+ * 3. schema-match: all records in period match attested schema
+ * 4. build-match: all records match attested build provenance
+ * 5. no-gap: no recorded gap overlaps the period
+ */
+export function computeCoverageState(
+	periodStartMs: number,
+	periodEndMs: number,
+	extensionDir?: string,
+): CoverageResult {
+	const result = readCoverageAttestation(extensionDir);
+
+	if (!result.ok) {
+		return {
+			state: "unknown",
+			reason: `attestation rejected: ${result.reason}`,
+			verifiedConjuncts: [],
+		};
+	}
+
+	const attestation = result.attestation;
+	const verifiedConjuncts: VerifiedConjunct[] = [];
+
+	// CONJUNCT 1: period-timing - period must be wholly at or after attestedAtMs
+	if (periodStartMs < attestation.attestedAtMs) {
+		return {
+			state: "partial",
+			reason: "period starts before attestedAtMs",
+			verifiedConjuncts: ["period-timing"],
+		};
+	}
+	verifiedConjuncts.push("period-timing");
+
+	// Scan both logs once. Keep only the conjunct evidence needed by this period.
+	const stores: ReadonlyArray<{
+		readonly recordType: "window-sample" | "cost-delta";
+		readonly options: Parameters<typeof iterateHistory>[1];
+	}> = [
+		{
+			recordType: "window-sample",
+			options: extensionDir
+				? { windowHistoryPath: join(extensionDir, "window-history.ndjson") }
+				: undefined,
+		},
+		{
+			recordType: "cost-delta",
+			options: extensionDir
+				? { costHistoryPath: join(extensionDir, "cost-history.ndjson") }
+				: undefined,
+		},
+	];
+	let oldestRecordedAtMs = Number.POSITIVE_INFINITY;
+	let recordFailure: string | undefined;
+	let gapFailure: string | undefined;
+	for (const store of stores) {
+		for (const record of iterateHistory(store.recordType, store.options)) {
+			if (isRecordEnvelope(record)) {
+				if (record.recordedAtMs < oldestRecordedAtMs) {
+					oldestRecordedAtMs = record.recordedAtMs;
+				}
+				if (
+					recordFailure === undefined &&
+					record.recordedAtMs >= periodStartMs &&
+					record.recordedAtMs <= periodEndMs
+				) {
+					if (record.schemaVersion !== attestation.historySchemaVersion) {
+						recordFailure = `record at ${record.recordedAtMs} has schema ${record.schemaVersion}, expected ${attestation.historySchemaVersion}`;
+					} else {
+						const payload = record.payload as { buildProvenance?: unknown };
+						if (typeof payload !== "object" || payload === null) {
+							recordFailure = `record at ${record.recordedAtMs} has invalid payload`;
+						} else if (
+							payload.buildProvenance !== attestation.buildProvenance
+						) {
+							recordFailure = `record at ${record.recordedAtMs} has build ${payload.buildProvenance}, expected ${attestation.buildProvenance}`;
+						}
+					}
+				}
+			} else if (
+				gapFailure === undefined &&
+				isGapRecord(record) &&
+				record.gapStartMs <= periodEndMs &&
+				record.gapEndMs >= periodStartMs
+			) {
+				gapFailure = `gap [${record.gapStartMs}, ${record.gapEndMs}] overlaps period`;
+			}
+		}
+	}
+
+	if (!Number.isFinite(oldestRecordedAtMs)) {
+		return {
+			state: "partial",
+			reason: "no retained history records found",
+			verifiedConjuncts,
+		};
+	}
+	if (periodStartMs < oldestRecordedAtMs) {
+		return {
+			state: "partial",
+			reason: "period starts before oldest retained record",
+			verifiedConjuncts,
+		};
+	}
+	verifiedConjuncts.push("retained-history");
+	if (recordFailure !== undefined) {
+		return { state: "partial", reason: recordFailure, verifiedConjuncts };
+	}
+	verifiedConjuncts.push("schema-match");
+	verifiedConjuncts.push("build-match");
+	if (gapFailure !== undefined) {
+		return { state: "partial", reason: gapFailure, verifiedConjuncts };
+	}
+	verifiedConjuncts.push("no-gap");
+
+	// All five conjuncts verified - coverage is complete
+	return {
+		state: "complete",
+		verifiedConjuncts,
+	};
+}
+
+// Type guards for discriminating HistoryLogRecord
+function isRecordEnvelope(
+	record: HistoryLogRecord,
+): record is HistoryRecordEnvelope {
+	return "recordType" in record && record.recordType !== "gap";
+}
+
+function isGapRecord(record: HistoryLogRecord): record is HistoryGapRecord {
+	return "recordType" in record && record.recordType === "gap";
+}
+
+export const COVERAGE_CANONICAL_BUILD_IDENTITY = CANONICAL_BUILD_IDENTITY;

package/src/credential-lifecycle.ts

@@ -0,0 +1,169 @@
+/**
+ * Credential lifecycle integrity.
+ *
+ * Three defects surfaced by reading the Sarrius reference implementation
+ * (`.scratch/reference/code/pi/pi-multi-account-sarrius`), whose doc comments
+ * record the production failures each one caused. They share a root cause:
+ * treating a credential as if it were the account. A credential is a rotating
+ * artifact; the account behind it is what routing decisions actually care
+ * about.
+ *
+ * Nothing here reads from a store, persists, or logs a credential value. The
+ * pure merge helper only reassembles fields. The Antigravity projector copies
+ * its reviewed named fields into a short-lived callback input and drops every
+ * unknown field; neither helper retains or emits credential material. Every
+ * other helper takes bounded metadata (expiry, token presence).
+ */
+
+import type { OAuthCredentials } from "@earendil-works/pi-ai";
+
+/** Named credential fields reviewed for the upstream Antigravity OAuth boundary. */
+export interface AntigravityOAuthCredential extends OAuthCredentials {
+	readonly projectId?: string;
+	readonly email?: string;
+}
+
+/**
+ * Copies only fields used by the selected Antigravity auth primitives.
+ * Unknown AuthStorage fields must not cross into login, refresh, or request auth.
+ */
+export function projectAntigravityOAuthCredential(
+	credential: OAuthCredentials,
+): AntigravityOAuthCredential {
+	const projectId = credential["projectId"];
+	const email = credential["email"];
+	return {
+		access: credential.access,
+		refresh: credential.refresh,
+		expires: credential.expires,
+		...(typeof projectId === "string" ? { projectId } : {}),
+		...(typeof email === "string" ? { email } : {}),
+	};
+}
+
+/**
+ * Bounded, value-free description of a stored credential, sufficient to decide
+ * whether an account can serve a request. Deliberately not the credential:
+ * callers pass presence and expiry, never secrets.
+ */
+export interface CredentialUsability {
+	/** Epoch ms when the credential expires, when the store reports one. */
+	readonly expiresAtMs?: number | undefined;
+	/** Whether a refresh token exists, i.e. whether expiry is recoverable. */
+	readonly hasRefreshToken: boolean;
+}
+
+/**
+ * Merges a refreshed OAuth credential onto the stored one.
+ *
+ * Spreading the refreshed fields last is the entire point: it carries the NEW
+ * access token and expiry onto the credential the host uses next. Returning the
+ * provider's response raw instead — which is what our Codex bridge did — loses
+ * any field the response omits. The refresh token is the dangerous one: many
+ * providers mint a new access token while returning no replacement refresh
+ * token, so a raw return silently drops the only means of future recovery.
+ *
+ * Sarrius documents shipping exactly this bug: the dropped merge made every
+ * post-refresh call reuse a stale access token and 401 forever, after which
+ * their consecutive-401 guard concluded the account was dead and killed a slot
+ * that was in fact healthy. A refresh that destroys the refresh token converts
+ * a recoverable credential into an unrecoverable one.
+ *
+ * Preserves the stored refresh token when the response carries none, and is
+ * conservative about what counts as "carries one" — a blank or whitespace-only
+ * value is treated as absent rather than allowed to overwrite a working token.
+ */
+export function mergeRefreshedCredentials<
+	TStored extends Record<string, unknown>,
+	TRefreshed extends Record<string, unknown>,
+>(stored: TStored, refreshed: TRefreshed): TStored & TRefreshed {
+	const refreshedPresent = Object.fromEntries(
+		Object.entries(refreshed).filter(
+			([, value]) => value !== undefined && value !== null,
+		),
+	) as TRefreshed;
+	const merged = { ...stored, ...refreshedPresent } as TStored & TRefreshed;
+	const mintedRefresh = refreshed["refresh"];
+	const hasMintedRefresh =
+		typeof mintedRefresh === "string" && mintedRefresh.trim().length > 0;
+	if (hasMintedRefresh) return merged;
+	const storedRefresh = stored["refresh"];
+	if (typeof storedRefresh !== "string" || storedRefresh.length === 0) {
+		return merged;
+	}
+	return { ...merged, refresh: storedRefresh };
+}
+
+/**
+ * Whether a credential can still serve a request.
+ *
+ * Unusable means provably dead, not merely stale: the credential has expired
+ * AND carries no refresh token, so no code path can revive it. Such an account
+ * must leave the routing pool, because every dispatch to it is a guaranteed
+ * failure that consumes a turn and can trip failure heuristics against an
+ * account whose only problem is that nobody has logged in.
+ *
+ * A credential that is expired but refreshable stays usable — refreshing is the
+ * normal path and happens transparently. A credential with unknown expiry also
+ * stays usable: absent evidence, the routing pool is the safer default, and a
+ * real failure will still be classified reactively.
+ */
+export function isCredentialUsable(
+	credential: CredentialUsability,
+	nowMs: number,
+): boolean {
+	const { expiresAtMs, hasRefreshToken } = credential;
+	if (hasRefreshToken) return true;
+	if (expiresAtMs === undefined || !Number.isFinite(expiresAtMs)) return true;
+	return expiresAtMs > nowMs;
+}
+
+/** How an account's identity compares to the one previously observed. */
+export type AccountIdentityChange =
+	/** No prior observation; nothing can be concluded yet. */
+	| "first-observation"
+	/** Same real account. A token may have rotated; the account did not. */
+	| "unchanged"
+	/** The slot now holds a genuinely different real account. */
+	| "changed"
+	/** Identity is not derivable, so no change can be proven. */
+	| "indeterminate";
+
+/**
+ * Classifies an account identity transition for a slot.
+ *
+ * Routing state — rate-limit cooldowns and failure records — belongs to the
+ * ACCOUNT, not to the credential that happens to represent it. A routine OAuth
+ * refresh rotates the access token while the account behind it is unchanged, so
+ * discarding that state on every rotation is wrong twice over: a server-side
+ * rate limit is not lifted by minting a new token, and an agent that forgets
+ * the cooldown will route straight back into the limit it just hit.
+ *
+ * When identity cannot be derived — Anthropic issues opaque tokens carrying no
+ * account claim — the answer is `indeterminate`, never a guess. Callers must
+ * treat that as "cannot prove a change" and retain existing state. Erring
+ * toward keeping a cooldown costs at most some delay against one account;
+ * erring toward clearing it sends real traffic into a known-limited account.
+ */
+export function classifyAccountIdentity(
+	previous: string | undefined,
+	next: string | undefined,
+): AccountIdentityChange {
+	if (previous === undefined && next === undefined) return "indeterminate";
+	if (next === undefined) return "indeterminate";
+	if (previous === undefined) return "first-observation";
+	return previous === next ? "unchanged" : "changed";
+}
+
+/**
+ * Whether a slot's accumulated routing state may be discarded.
+ *
+ * True only for a proven account substitution. Every other case — same account,
+ * first sighting, or underivable identity — retains state, because none of them
+ * is evidence that the server-side condition which created it has cleared.
+ */
+export function shouldClearAccountState(
+	change: AccountIdentityChange,
+): boolean {
+	return change === "changed";
+}