@naswerks/periscope 1.0.0 → 1.0.1

package/src/host/index.ts

@@ -0,0 +1,92 @@
+/**
+ * The privileged module: the only place in this package that imports `node:fs`,
+ * `node:fs/promises`, `node:child_process` or `node:os`.
+ *
+ * That is the package's central claim: a reviewer answers "what can this touch on my machine?" by
+ * reading one directory. It is enforced twice — an ESLint rule for editor-time feedback, and a
+ * tree-walking pin test that survives the lint config being changed or deleted.
+ */
+export type { MachineFacts } from './machine.js';
+export { readMachineFacts } from './machine.js';
+
+// The composer: the per-session assembly, and the host that owns a link and a registry. It reaches
+// every other directory in the package, which is exactly what makes it the one place a consumer
+// does not have to reproduce by hand.
+export type {
+  BulkResolver,
+  ComposeSessionOptions,
+  ComposedSession,
+  GateTimings,
+  HostEvent,
+  PeriscopeHostOptions,
+} from './host.js';
+export { PeriscopeHost, composeSession } from './host.js';
+
+export type { BulkPostReceipt, BulkPostRequest } from './bulk-post.js';
+export { postBulk } from './bulk-post.js';
+
+// The discovery door: read-only, jailed enumeration of the agent CLI's own transcripts. The root
+// derivation ships beside the reader so the composition root derives and the module only reads.
+export type { DiscoveredTranscript, TranscriptPage, TranscriptTailAnswer } from './claude-transcripts.js';
+export { TRANSCRIPT_PAGE_SIZE, TRANSCRIPT_WHAT_PREFIX } from '../control/frames.js';
+export { packageVersion } from './package-facts.js';
+export {
+  claudeProjectsRoot,
+  defaultAgentHome,
+  transcriptsRootUnder,
+  claudeTranscriptResolver,
+  isMatchingUserEntry,
+  listTranscripts,
+  resolveTranscriptPath,
+  tailTranscript,
+} from './claude-transcripts.js';
+
+// The repository read: the same read-only, jailed posture over the repository root.
+export type { RepositoryListing, RepositoryText } from './repository-read.js';
+export {
+  BINARY_PROBE_BYTES,
+  listRepositoryDirectory,
+  readRepositoryFile,
+  resolveRepositoryPath,
+} from './repository-read.js';
+
+// The two impure inputs the host's own gate takes at construction, plus the derived location of
+// this host's own credential material — `credentialPaths` covers it BECAUSE both come from here.
+export {
+  credentialPaths,
+  nodePathResolver,
+  pairedCredentialPath,
+  periscopeCredentialDir,
+  tokenCachePath,
+} from './paths.js';
+export type { ConfigFileReading, ConfigKey } from './config-file.js';
+export {
+  CONFIG_KEYS,
+  configFilePath,
+  isConfigKey,
+  readConfigFile,
+  withConfigFallback,
+  writeConfigEntry,
+} from './config-file.js';
+
+// The impure halves of identity: the file the token lives in, and the port the callback arrives on.
+export type { TokenCacheWrite } from './token-cache.js';
+export { FileTokenCache, probeModeEnforcement } from './token-cache.js';
+
+// The paired credential's file half — same directory, same modes, same verify-after-write.
+export type { PairedCredentialWrite } from './paired-credential-store.js';
+export { FilePairedCredential } from './paired-credential-store.js';
+
+export type { DeviceCodeInstruction, SignInDeps } from './sign-in.js';
+export { protocolFor, refresherFor, resolveEndpoints, signIn, signInWithDeviceCode } from './sign-in.js';
+
+export type { LoopbackListener } from './loopback.js';
+export { DEFAULT_SIGN_IN_TIMEOUT_MS, LOOPBACK_HOST, openLoopbackListener } from './loopback.js';
+
+// The local JSONL mirror's effects, and the bridge that presents a transcript store to the SDK.
+// Both are here for the two reasons this directory exists: one names `node:fs`, the other the SDK.
+export { nodeStoreEffects } from './transcript-fs.js';
+export { asSessionStore, readMirrorDrop, toSessionKey, toTranscriptKey } from './session-store.js';
+
+// Cost and rate-limit facts, lifted off the agent's own stream. Nothing here polls anything.
+export { readRateLimit, readTaskSpend, readTurnSpend } from './telemetry.js';

package/src/host/link-state-file.ts

@@ -0,0 +1,79 @@
+/**
+ * The link's last transition, kept on disk by `serve` so `periscope status` can answer "is this host
+ * linked, and since when" without a socket: one JSON file beside the credentials, replaced whole on
+ * every transition (written to a sibling, then renamed, so a reader never sees half a record). The
+ * process id rides in it, so a stale record from a host that died can be told from a live one.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import type { LinkCause, LinkState } from '../control/link-state.js';
+import { tokenCachePath } from './paths.js';
+
+export interface LinkStateRecord {
+  readonly state: LinkState;
+  readonly cause: LinkCause;
+  readonly at: string;
+  readonly detail: string | null;
+  /** The version the controller chose at the last accepted handshake; null before one. */
+  readonly negotiatedVersion: number | null;
+  /** The serve process that wrote the record. */
+  readonly pid: number;
+}
+
+/** Beside the token cache and the paired credential; null where there is no home and no config dir. */
+export function linkStatePath(env: NodeJS.ProcessEnv): string | null {
+  const cache = tokenCachePath(env);
+  return cache === null ? null : join(dirname(cache), 'link-state.json');
+}
+
+/** Writes the record whole. Returns the problem, or null. Never throws: the link must not depend on the disk. */
+export function writeLinkState(env: NodeJS.ProcessEnv, record: LinkStateRecord): string | null {
+  const path = linkStatePath(env);
+  if (path === null)
+    return 'there is nowhere to keep the link state (no home directory and no PERISCOPE_CONFIG_DIR)';
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const sibling = `${path}.${record.pid}.tmp`;
+    writeFileSync(sibling, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    renameSync(sibling, path);
+    return null;
+  } catch (error) {
+    return `could not write ${path}: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}
+
+/** The record, or null when there is none or it is unreadable: an absent file is a host that never ran. */
+export function readLinkState(env: NodeJS.ProcessEnv): LinkStateRecord | null {
+  const path = linkStatePath(env);
+  if (path === null) return null;
+  let text: string;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(text) as Partial<LinkStateRecord> | null;
+    if (
+      parsed === null ||
+      typeof parsed !== 'object' ||
+      typeof parsed.state !== 'string' ||
+      typeof parsed.cause !== 'string' ||
+      typeof parsed.at !== 'string' ||
+      typeof parsed.pid !== 'number'
+    ) {
+      return null;
+    }
+    return {
+      state: parsed.state,
+      cause: parsed.cause,
+      at: parsed.at,
+      detail: typeof parsed.detail === 'string' ? parsed.detail : null,
+      negotiatedVersion: typeof parsed.negotiatedVersion === 'number' ? parsed.negotiatedVersion : null,
+      pid: parsed.pid,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/host/loopback.ts

@@ -0,0 +1,177 @@
+/**
+ * The loopback redirect listener: a socket open for one callback, on one interface, for a bounded
+ * time.
+ *
+ * Every constraint here is a consequence of one fact: the agent shares this host's OS user. That
+ * is the premise the whole identity model rests on; it is why an 0600 token file is not a boundary
+ * and why the gate carries a credential-path denial. It also means any local process can connect
+ * to this listener, so the listener is a surface facing the exact actor the identity model
+ * defends against:
+ *
+ *   - **`127.0.0.1` explicitly, never `0.0.0.0`.** The default binds every interface, which would
+ *     put an authorization callback endpoint on the network. Nothing off this machine has any
+ *     business reaching it, and the difference is one argument nobody notices missing.
+ *   - **Exactly one callback, then closed.** A listener that stays open after answering is a
+ *     listener something else can still reach, and there is no second callback to wait for.
+ *   - **It times out.** An abandoned sign-in must not leave a port open indefinitely on a host that
+ *     runs unattended for weeks.
+ *   - **The `state` check is the caller's and it is not optional** — see `identity/authorize.ts`.
+ *     This module returns the query string verbatim; it deliberately does not decide anything about
+ *     whether the callback belongs to this sign-in.
+ */
+import { createServer } from 'node:http';
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import { CALLBACK_PAGE } from '../identity/authorize.js';
+import { redirectUriFor } from '../identity/authorize.js';
+
+/** The one interface this listener will ever bind. */
+export const LOOPBACK_HOST = '127.0.0.1';
+
+/** Long enough for a real sign-in including a second factor; short enough to not be forever. */
+export const DEFAULT_SIGN_IN_TIMEOUT_MS = 300_000;
+
+export interface LoopbackListener {
+  readonly port: number;
+  readonly redirectUri: string;
+  /** Resolves with the callback's raw query string, or a refusal. Settles exactly once. */
+  readonly callback: Promise<Result<string>>;
+  close(): void;
+}
+
+/**
+ * Open the listener.
+ *
+ * `port` 0 asks the OS for a free one, which is the ordinary case — the redirect URI is then built
+ * from what it gave back, which is why the provider registration must allow a loopback redirect with
+ * any port. (Providers treat `http://127.0.0.1` loopback redirects specially for exactly this
+ * reason; a fixed port would collide with whatever else is running.)
+ */
+export function openLoopbackListener(
+  port = 0,
+  timeoutMs = DEFAULT_SIGN_IN_TIMEOUT_MS,
+): Promise<Result<LoopbackListener>> {
+  return openLoopbackListenerWith(createServer, port, timeoutMs);
+}
+
+/**
+ * The one server shape this module asks for — narrower than `createServer`'s overloads on purpose,
+ * so an injected constructor is writable without reproducing them.
+ */
+export type LoopbackServerConstructor = (
+  handler: (request: IncomingMessage, response: ServerResponse) => void,
+) => Server;
+
+/**
+ * The listener over an injected server constructor.
+ *
+ * Injected for the same reason `jail.ts` takes its resolver injected: the server's failure paths
+ * cannot be reached from outside this module — a post-listen `'error'` has no external trigger —
+ * and the only way to exercise them at all is a caller that holds the server it built. This is
+ * package-internal: it is exported from this file for the suite and deliberately NOT re-exported
+ * from either barrel, and the package-shape suite asserts that stays true.
+ */
+export function openLoopbackListenerWith(
+  createServerImpl: LoopbackServerConstructor,
+  port: number,
+  timeoutMs: number,
+): Promise<Result<LoopbackListener>> {
+  return new Promise((resolveListener) => {
+    let settle: (result: Result<string>) => void = () => {};
+    const callback = new Promise<Result<string>>((resolve) => {
+      settle = resolve;
+    });
+
+    let settled = false;
+    const finish = (result: Result<string>): void => {
+      if (settled) return;
+      settled = true;
+      settle(result);
+      close();
+    };
+
+    // Closing settles the wait. A caller that gives up (a shutdown signal, an outer timeout) must
+    // not leave whoever is awaiting the callback pending forever. A promise nobody will ever
+    // resolve is the shape that turns a cancelled sign-in into a hung host.
+    const abandon = (): void =>
+      finish(refuse('auth-callback-refused', 'the sign-in was closed before a callback arrived'));
+
+    const server = createServerImpl((request, response) => {
+      const url = new URL(request.url ?? '/', `http://${LOOPBACK_HOST}`);
+
+      // Anything that is not the redirect path gets a flat 404 and does NOT settle the wait. A
+      // stray probe — a browser prefetch, another process scanning ports — must not be able to end
+      // a sign-in that is still in progress.
+      if (url.pathname !== '/callback') {
+        response.writeHead(404, { 'content-type': 'text/plain' });
+        response.end('not found');
+        return;
+      }
+
+      response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      response.end(CALLBACK_PAGE);
+      finish(ok(url.search.startsWith('?') ? url.search.slice(1) : url.search));
+    });
+
+    const timer = setTimeout(() => {
+      finish(
+        refuse(
+          'auth-callback-refused',
+          `no callback arrived within ${timeoutMs}ms; the sign-in was not completed`,
+        ),
+      );
+    }, timeoutMs);
+    // The host must be able to exit while a sign-in is pending rather than being held open by it.
+    timer.unref?.();
+
+    let closed = false;
+    const close = (): void => {
+      if (closed) return;
+      closed = true;
+      clearTimeout(timer);
+      server.close();
+      // Sockets kept alive by a browser would hold the server open past `close()`.
+      server.closeAllConnections?.();
+    };
+
+    server.once('error', (error) => {
+      // Before `listen` succeeds this settles the OPEN with a refusal. After it, the outer promise
+      // is already resolved and that call is a no-op — the wait that must settle then is the
+      // CALLBACK's, and `finish` is the one route that settles it, closes the server and clears
+      // the deadline in one motion. Skipping `finish` here is what once left `signIn` hanging
+      // forever on a callback that could no longer arrive, with the timeout already disarmed.
+      resolveListener(
+        refuse(
+          'identity-config-invalid',
+          `the loopback listener could not bind ${LOOPBACK_HOST}:${port}: ${String(error)}`,
+        ),
+      );
+      finish(
+        refuse(
+          'auth-callback-refused',
+          `the loopback listener failed (${String(error)}), so no callback can arrive; the sign-in was not completed`,
+        ),
+      );
+    });
+
+    server.listen(port, LOOPBACK_HOST, () => {
+      const address = server.address() as AddressInfo | null;
+      if (address === null) {
+        close();
+        resolveListener(refuse('identity-config-invalid', 'the loopback listener bound no address'));
+        return;
+      }
+      resolveListener(
+        ok({
+          port: address.port,
+          redirectUri: redirectUriFor(address.port),
+          callback,
+          close: abandon,
+        }),
+      );
+    });
+  });
+}

package/src/host/machine.ts

@@ -0,0 +1,27 @@
+/**
+ * Facts about the machine this host runs on.
+ *
+ * Inside `src/host/` because it reaches `node:os`. Everything outward takes these as plain values,
+ * which is what lets the rest of the package run in a test, a browser, or a controller unchanged.
+ */
+import { homedir, hostname, platform, release, tmpdir } from 'node:os';
+
+export interface MachineFacts {
+  readonly hostname: string;
+  readonly platform: NodeJS.Platform;
+  readonly release: string;
+  readonly homeDir: string;
+  readonly tempDir: string;
+}
+
+export function readMachineFacts(): MachineFacts {
+  return {
+    hostname: hostname(),
+    platform: platform(),
+    release: release(),
+    // On Windows this resolves the USERPROFILE family, not HOME. Code keyed on HOME alone finds
+    // nothing there and fails without saying so.
+    homeDir: homedir(),
+    tempDir: tmpdir(),
+  };
+}

package/src/host/mcp-server.ts

@@ -0,0 +1,66 @@
+/**
+ * The one place a tool plan becomes an SDK server.
+ *
+ * It lives here for the import, not for the danger. `createSdkMcpServer` and `tool()` build
+ * in-process objects and start nothing, but the boundary rule is that one directory names
+ * `@anthropic-ai/claude-agent-sdk`, so a reader answering "what can start a process here?" reads
+ * `src/host/` and nowhere else. Carving out an exception for the safe calls in that package is
+ * how a boundary stops meaning anything, so the exception is not taken. All the decisions are in
+ * `mcp/server.ts`; this file adds the SDK call and nothing else.
+ *
+ * In-process removes machinery rather than replacing it: no `.mcp.json` written into the
+ * workspace, no stdio child to spawn, no attach receipt to watch for, no port, no handshake.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
+
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import type { McpServerOptions, ToolPlan } from '../mcp/server.js';
+import { planTools } from '../mcp/server.js';
+
+/**
+ * One tool definition, named through the SDK's own signature rather than by hand.
+ *
+ * `CreateSdkMcpServerOptions` is a `declare type` and not exported, so a consumer cannot name the
+ * argument `createSdkMcpServer` takes. Deriving it from the function's parameter is how this file
+ * stays exactly as wide as the SDK is: if the accepted shape changes, this breaks at build time
+ * rather than after a cast quietly absorbed the difference.
+ */
+type ToolDefinition = NonNullable<Parameters<typeof createSdkMcpServer>[0]['tools']>[number];
+
+/**
+ * Build the in-process server from a controller's descriptors.
+ *
+ * Refuses rather than throwing — registration happens before any session exists, and a controller
+ * that sent an unusable descriptor needs to be told which one and why.
+ */
+export function createToolServer(options: McpServerOptions): Result<McpSdkServerConfigWithInstance> {
+  const planned = planTools(options);
+  if (!planned.ok)
+    return refuse<McpSdkServerConfigWithInstance>(planned.refusal.reason, planned.refusal.detail);
+
+  return ok(
+    createSdkMcpServer({
+      name: options.name,
+      version: options.version ?? '0.0.0',
+      tools: planned.value.map(toDefinition),
+    }),
+  );
+}
+
+/**
+ * A plan, as the SDK's own tool definition. The whole of this module's added value.
+ *
+ * The result is re-built rather than passed through; that is the adaptation this seam exists for.
+ * The SDK's result type carries an index signature (`[x: string]: unknown`), which a declared
+ * interface cannot satisfy — so `mcp/server.ts` states the shape it means in its own terms and the
+ * translation happens here, in the one file allowed to know both. A cast would have compiled and
+ * would have hidden any later divergence between the two shapes.
+ */
+function toDefinition(plan: ToolPlan): ToolDefinition {
+  return tool(plan.name, plan.description, plan.shape, async (args: unknown) => {
+    const result = await plan.handler(args);
+    return { content: result.content, ...(result.isError === true ? { isError: true } : {}) };
+  });
+}

package/src/host/package-facts.ts

@@ -0,0 +1,25 @@
+/**
+ * The package's own version, read from the manifest that ships beside `dist/`.
+ *
+ * Read here rather than baked in at build: `package.json` is the one place the version is stated,
+ * and a constant copied into source would be a second place that can drift. The read is lazy and
+ * memoised, and a manifest that cannot be read reports `unknown` rather than failing a verb that
+ * only wanted to print a line.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+let cached: string | null = null;
+
+/** `<name>@<version>` of the running package, or `unknown` when the manifest cannot be read. */
+export function packageVersion(): string {
+  if (cached !== null) return cached;
+  try {
+    const manifestPath = fileURLToPath(new URL('../../package.json', import.meta.url));
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8')) as { version?: unknown };
+    cached = typeof parsed.version === 'string' && parsed.version !== '' ? parsed.version : 'unknown';
+  } catch {
+    cached = 'unknown';
+  }
+  return cached;
+}

package/src/host/paired-credential-store.ts

@@ -0,0 +1,140 @@
+/**
+ * The file-backed paired-credential store: `token-cache.ts`'s discipline, applied to the second
+ * credential this package persists.
+ *
+ * Same directory, same modes, same verify-after-write, and none of it restated by hand. The file
+ * lives beside the token cache under `periscopeCredentialDir`, which is what puts it inside the
+ * gate's protected set for free: `credentialPaths` names the directory, precisely so anything the
+ * host later keeps beside the token cache is protected by having been put there.
+ *
+ * What 0600 is and is not: see `token-cache.ts`'s header. The agent runs as the same OS user;
+ * what keeps the AGENT away from this file is the gate's credential-path denial, and the
+ * composition test in `identity/paired-credential.test.ts` proves the containment.
+ */
+import { chmodSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import type { CredentialModeOutcome, ModeEnforcement } from '../identity/mode.js';
+import { CREDENTIAL_MODE, classifyCredentialMode } from '../identity/mode.js';
+import type { PairedCredentialFile, PairedCredentialStore } from '../identity/paired-credential.js';
+import { readPairedCredentialFile } from '../identity/paired-credential.js';
+import { probeModeEnforcement } from './token-cache.js';
+
+/** Directories holding credential material are owner-only too — `token-cache.ts`'s constant. */
+const CREDENTIAL_DIR_MODE = 0o700;
+
+export interface PairedCredentialWrite {
+  readonly path: string;
+  readonly mode: CredentialModeOutcome;
+}
+
+export class FilePairedCredential implements PairedCredentialStore {
+  readonly #path: string;
+  readonly #directory: string;
+  #enforcement: ModeEnforcement | null = null;
+
+  constructor(path: string) {
+    this.#path = path;
+    const cut = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+    this.#directory = cut > 0 ? path.slice(0, cut) : path;
+  }
+
+  get path(): string {
+    return this.#path;
+  }
+
+  /** Memoised: the filesystem does not change its mind mid-process. */
+  modeEnforcement(): ModeEnforcement {
+    if (this.#enforcement === null) {
+      try {
+        mkdirSync(this.#directory, { recursive: true, mode: CREDENTIAL_DIR_MODE });
+      } catch {
+        // The write path reports the real failure; a probe must not be the thing that raises it.
+      }
+      this.#enforcement = probeModeEnforcement(this.#directory);
+    }
+    return this.#enforcement;
+  }
+
+  /**
+   * Read the paired credential.
+   *
+   * A missing file is `token-unavailable` — this machine has never been paired, the NORMAL state
+   * every unpaired host is in — and that is deliberately not the same reason as a file that exists
+   * and cannot be parsed. The composition root falls through to the OIDC posture on the first and
+   * refuses to start on the second: a corrupt paired credential silently degrading to a maybe-dead
+   * refresh token would put the host in exactly the ambiguous posture pairing exists to end.
+   */
+  read(): Result<PairedCredentialFile> {
+    let raw: string;
+    try {
+      raw = readFileSync(this.#path, 'utf8');
+    } catch {
+      return refuse('token-unavailable', 'this machine holds no paired credential');
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return refuse(
+        'credential-cache-unreadable',
+        `the paired credential at ${this.#path} exists and is not valid JSON; remove it or run: periscope pair <code>`,
+      );
+    }
+
+    return readPairedCredentialFile(parsed);
+  }
+
+  /**
+   * Write the credential, then verify what actually landed — a file that came out wider than asked
+   * is removed, not left and reported (`token-cache.ts`'s rule, same words, same reason).
+   */
+  write(file: PairedCredentialFile): Result<PairedCredentialWrite> {
+    const enforcement = this.modeEnforcement();
+
+    try {
+      mkdirSync(this.#directory, { recursive: true, mode: CREDENTIAL_DIR_MODE });
+      writeFileSync(this.#path, `${JSON.stringify(file, null, 2)}\n`, { mode: CREDENTIAL_MODE });
+      // `writeFileSync`'s mode applies only when it CREATES the file — re-stating it is what makes
+      // an overwrite (a re-pair) as private as a first write.
+      chmodSync(this.#path, CREDENTIAL_MODE);
+    } catch (error) {
+      return refuse(
+        'credential-cache-write-failed',
+        `the paired credential could not be written to ${this.#path}: ${String(error)}`,
+      );
+    }
+
+    let observed: number;
+    try {
+      observed = statSync(this.#path).mode;
+    } catch (error) {
+      return refuse(
+        'credential-cache-write-failed',
+        `the paired credential was written and could not be read back from ${this.#path}: ${String(error)}`,
+      );
+    }
+
+    const mode = classifyCredentialMode(observed, enforcement);
+    if (mode.kind === 'too-wide') {
+      this.clear();
+      return refuse(
+        mode.refusal.reason,
+        `${mode.refusal.detail}; the file has been removed rather than left readable`,
+      );
+    }
+
+    return ok({ path: this.#path, mode });
+  }
+
+  /** Remove the credential. Idempotent — clearing what is not there is success, not an error. */
+  clear(): void {
+    try {
+      rmSync(this.#path, { force: true });
+    } catch {
+      // Nothing here can act on the failure.
+    }
+  }
+}