@naswerks/periscope 1.0.0

package/dist/host/sign-in.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The assembly: the one place the identity parts become a working sign-in.
+ *
+ * Why this file exists at all: a set of individually correct parts with nothing composing them is a
+ * failure mode (a gate, an observer and a session each proven, with nothing wiring them together,
+ * so a default session runs ungated). Identity has exactly the same shape: a config reader, a PKCE
+ * generator, a listener, a token parser and a cache are five green modules and zero working
+ * sign-ins. This is the sixth thing, and without it the other five are a claim rather than a
+ * capability.
+ *
+ * The transport is injected. `fetch` and the browser-opener are parameters, so the whole flow
+ * (discovery, redemption, refresh, and every failure in them) is exercised against a real local HTTP
+ * server in the tests rather than against a mock of one. What is not exercised is a real identity
+ * provider; that needs an app registration, which is a human act and deliberately not this code's.
+ */
+import type { Result } from '../core/result.js';
+import type { Ticker } from '../core/time.js';
+import type { IdentityConfig, IdentityEndpoints } from '../identity/config.js';
+import type { AuthProtocol } from '../identity/device-code.js';
+import type { CachedTokens, TokenStore } from '../identity/store.js';
+import type { TokenRefresher } from '../identity/credential.js';
+/** The injectable edges. Every one has a real default; the tests replace the transport. */
+export interface SignInDeps {
+    readonly fetch?: typeof globalThis.fetch;
+    /** Told where to send the user. Defaults to printing the URL, which works on a headless box. */
+    readonly present?: (url: string) => void;
+    readonly timeoutMs?: number;
+    readonly nowMs?: Ticker;
+    /** Injected so a device-code poll loop is testable without real waiting. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The endpoints, from configuration or from the provider's discovery document.
+ *
+ * Stated endpoints win and skip the network entirely — an operator who pinned them gets no
+ * surprise round trip, and an air-gapped or proxied deployment can work without discovery at all.
+ */
+export declare function resolveEndpoints(config: IdentityConfig, fetchImpl?: typeof globalThis.fetch): Promise<Result<IdentityEndpoints>>;
+/**
+ * Sign a user in through the loopback redirect, and persist what comes back.
+ *
+ * The listener is opened before the authorization URL is built, because the redirect URI has to
+ * carry the port the OS actually gave. Building the URL first would mean either guessing a port
+ * or fixing one, and a fixed port collides with whatever else is running on a developer's machine.
+ *
+ * And the listener is closed on every path. It is a socket accepting callbacks; leaving it open
+ * after a failed exchange would leave the thing this flow exists to bound still bound.
+ */
+export declare function signIn(config: IdentityConfig, store: TokenStore, deps?: SignInDeps): Promise<Result<CachedTokens>>;
+/** What a device-code sign-in tells the operator to do, before it starts waiting. */
+export interface DeviceCodeInstruction {
+    readonly verificationUri: string;
+    readonly userCode: string;
+}
+/**
+ * Sign in through the device-code flow, for a box with no browser on it.
+ *
+ * It refuses unless it was explicitly enabled, and that check is the first thing here. The
+ * provider calls this a high-risk method and recommends blocking it; a tenant refusing it outright
+ * is an expected outcome. It must be asked for by name, never arrived at by falling back — see
+ * `identity/device-code.ts` for the policy-blocked-flow trap it also carries.
+ *
+ * The poll interval is the provider's, not this package's, and `slow_down` widens it. Polling faster than
+ * asked is how a client gets rate-limited into failing a sign-in that would have worked.
+ */
+export declare function signInWithDeviceCode(config: IdentityConfig, store: TokenStore, instruct: (instruction: DeviceCodeInstruction) => void, deps?: SignInDeps): Promise<Result<CachedTokens>>;
+/**
+ * The refresher `TokenCredential` calls when its cached token has expired.
+ *
+ * An authentication-flows block discards the cache and names the flow to stop using. It does
+ * not say "sign in again".
+ *
+ * Why not: a blocked-flow refusal is the provider's policy refusing the flow (see
+ * `identity/device-code.ts`), so the trigger is a tenant admin enabling a policy, not a
+ * reconfiguration here. A refresher that cleared the cache and told the operator to sign in again
+ * would loop: `protocolFor` derives the flow from static config, so "again" would mean the same
+ * device-code flow, into the same policy. Unattended, that is refresh, blocked, clear, device code,
+ * blocked, repeat, never holding a usable token. A recovery path that returns to the failing state
+ * is not a recovery path.
+ *
+ * So it routes to the flow that is not blocked. The policy targets device code; loopback
+ * authorization-code plus PKCE is implemented here (`identity/authorize.ts`, `identity/pkce.ts`).
+ * When loopback is available the refusal says to use it; when it is not, the refusal refuses by
+ * name and tells the operator which setting to change, rather than inviting a retry that cannot
+ * succeed.
+ */
+export declare function refresherFor(config: IdentityConfig, endpoints: IdentityEndpoints, store: TokenStore, deps?: SignInDeps): TokenRefresher;
+/** Which flow a host configured this way will use. One place, so the cache is stamped consistently. */
+export declare function protocolFor(config: IdentityConfig): AuthProtocol;
+//# sourceMappingURL=sign-in.d.ts.map

package/dist/host/sign-in.js

@@ -0,0 +1,239 @@
+import { ok, refuse } from '../core/result.js';
+import { systemTicker } from '../core/time.js';
+import { discoveryUrl, readDiscoveryDocument } from '../identity/config.js';
+import { buildAuthorizationUrl, readAuthorizationCallback } from '../identity/authorize.js';
+import { createPkce, createState } from '../identity/pkce.js';
+import { deviceAuthorizationBody, devicePollBody, AUTH_FLOW_BLOCKED_ERROR, isAuthFlowBlocked, readDeviceAuthorization, readDevicePoll, requireDeviceCodeEnabled, } from '../identity/device-code.js';
+import { codeExchangeBody, readTokenResponse, refreshBody } from '../identity/token.js';
+import { DEFAULT_SIGN_IN_TIMEOUT_MS, openLoopbackListener } from './loopback.js';
+const FORM = { 'content-type': 'application/x-www-form-urlencoded' };
+/** A `fetch` that never throws: a transport error becomes a named refusal like any other outcome. */
+async function post(fetchImpl, url, body) {
+    let response;
+    try {
+        response = await fetchImpl(url, { method: 'POST', headers: FORM, body });
+    }
+    catch (error) {
+        // A transport failure is an outage, not a refusal by the provider. Reading them as the same
+        // thing is how a network blip gets diagnosed as a bad credential.
+        return refuse('token-request-failed', `the token endpoint could not be reached: ${String(error)}`);
+    }
+    return ok({ status: response.status, body: await readJson(response) });
+}
+/** A body that is not JSON is `null`, and the reader above decides what that means. */
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The endpoints, from configuration or from the provider's discovery document.
+ *
+ * Stated endpoints win and skip the network entirely — an operator who pinned them gets no
+ * surprise round trip, and an air-gapped or proxied deployment can work without discovery at all.
+ */
+export async function resolveEndpoints(config, fetchImpl = globalThis.fetch) {
+    if (config.endpoints !== null)
+        return ok(config.endpoints);
+    let response;
+    try {
+        response = await fetchImpl(discoveryUrl(config.authority));
+    }
+    catch (error) {
+        return refuse('identity-config-invalid', `the provider's discovery document could not be fetched: ${String(error)}`);
+    }
+    if (!response.ok) {
+        return refuse('identity-config-invalid', `the provider's discovery document returned HTTP ${response.status}`);
+    }
+    return readDiscoveryDocument(await readJson(response));
+}
+/**
+ * Sign a user in through the loopback redirect, and persist what comes back.
+ *
+ * The listener is opened before the authorization URL is built, because the redirect URI has to
+ * carry the port the OS actually gave. Building the URL first would mean either guessing a port
+ * or fixing one, and a fixed port collides with whatever else is running on a developer's machine.
+ *
+ * And the listener is closed on every path. It is a socket accepting callbacks; leaving it open
+ * after a failed exchange would leave the thing this flow exists to bound still bound.
+ */
+export async function signIn(config, store, deps = {}) {
+    const fetchImpl = deps.fetch ?? globalThis.fetch;
+    const nowMs = deps.nowMs ?? systemTicker;
+    const present = deps.present ?? ((url) => process.stdout.write(`open this to sign in:\n${url}\n`));
+    const endpoints = await resolveEndpoints(config, fetchImpl);
+    if (!endpoints.ok)
+        return refuse(endpoints.refusal.reason, endpoints.refusal.detail);
+    const opened = await openLoopbackListener(config.redirectPort, deps.timeoutMs ?? DEFAULT_SIGN_IN_TIMEOUT_MS);
+    if (!opened.ok)
+        return refuse(opened.refusal.reason, opened.refusal.detail);
+    const listener = opened.value;
+    try {
+        const pkce = createPkce();
+        const state = createState();
+        const request = buildAuthorizationUrl(config, endpoints.value.authorizationEndpoint, pkce, state, listener.redirectUri);
+        present(request.url);
+        const arrived = await listener.callback;
+        if (!arrived.ok)
+            return refuse(arrived.refusal.reason, arrived.refusal.detail);
+        // The `state` check lives here, in the pure reader, and it runs before the code is touched.
+        const callback = readAuthorizationCallback(arrived.value, state);
+        if (!callback.ok)
+            return refuse(callback.refusal.reason, callback.refusal.detail);
+        const exchanged = await post(fetchImpl, endpoints.value.tokenEndpoint, codeExchangeBody(config, callback.value.code, pkce.verifier, listener.redirectUri));
+        if (!exchanged.ok)
+            return refuse(exchanged.refusal.reason, exchanged.refusal.detail);
+        const tokens = readTokenResponse(exchanged.value.status, exchanged.value.body, nowMs());
+        if (!tokens.ok)
+            return refuse(tokens.refusal.reason, tokens.refusal.detail);
+        const cached = {
+            tokens: tokens.value,
+            protocol: 'loopback',
+            authority: config.authority,
+            clientId: config.clientId,
+        };
+        // A cache that would not write is a failed sign-in, and that is the opposite of the rule in
+        // `credential.ts`. There, a refresh had already succeeded and the token was in hand. Here the
+        // whole point was to persist it: returning success would tell the operator they are signed in
+        // while the next start finds nothing.
+        const written = store.write(cached);
+        if (!written.ok)
+            return refuse(written.refusal.reason, written.refusal.detail);
+        return ok(cached);
+    }
+    finally {
+        listener.close();
+    }
+}
+/**
+ * Sign in through the device-code flow, for a box with no browser on it.
+ *
+ * It refuses unless it was explicitly enabled, and that check is the first thing here. The
+ * provider calls this a high-risk method and recommends blocking it; a tenant refusing it outright
+ * is an expected outcome. It must be asked for by name, never arrived at by falling back — see
+ * `identity/device-code.ts` for the policy-blocked-flow trap it also carries.
+ *
+ * The poll interval is the provider's, not this package's, and `slow_down` widens it. Polling faster than
+ * asked is how a client gets rate-limited into failing a sign-in that would have worked.
+ */
+export async function signInWithDeviceCode(config, store, instruct, deps = {}) {
+    const enabled = requireDeviceCodeEnabled(config);
+    if (!enabled.ok)
+        return refuse(enabled.refusal.reason, enabled.refusal.detail);
+    const fetchImpl = deps.fetch ?? globalThis.fetch;
+    const nowMs = deps.nowMs ?? systemTicker;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const endpoints = await resolveEndpoints(config, fetchImpl);
+    if (!endpoints.ok)
+        return refuse(endpoints.refusal.reason, endpoints.refusal.detail);
+    const deviceEndpoint = endpoints.value.deviceAuthorizationEndpoint;
+    if (deviceEndpoint === null) {
+        return refuse('device-code-declined', 'this provider does not advertise a device authorization endpoint');
+    }
+    const started = await post(fetchImpl, deviceEndpoint, deviceAuthorizationBody(config));
+    if (!started.ok)
+        return refuse(started.refusal.reason, started.refusal.detail);
+    const authorization = readDeviceAuthorization(started.value.status, started.value.body, nowMs());
+    if (!authorization.ok)
+        return refuse(authorization.refusal.reason, authorization.refusal.detail);
+    instruct({ verificationUri: authorization.value.verificationUri, userCode: authorization.value.userCode });
+    let intervalMs = authorization.value.intervalMs;
+    const body = devicePollBody(config, authorization.value.deviceCode);
+    while (nowMs() < authorization.value.expiresAt) {
+        await sleep(intervalMs);
+        const polled = await post(fetchImpl, endpoints.value.tokenEndpoint, body);
+        if (!polled.ok)
+            return refuse(polled.refusal.reason, polled.refusal.detail);
+        const outcome = readDevicePoll(polled.value.status, polled.value.body, intervalMs);
+        if (outcome.kind === 'pending')
+            continue;
+        if (outcome.kind === 'slow-down') {
+            intervalMs = outcome.intervalMs;
+            continue;
+        }
+        if (outcome.kind === 'declined')
+            return refuse(outcome.refusal.reason, outcome.refusal.detail);
+        const tokens = readTokenResponse(polled.value.status, polled.value.body, nowMs());
+        if (!tokens.ok)
+            return refuse(tokens.refusal.reason, tokens.refusal.detail);
+        const cached = {
+            tokens: tokens.value,
+            // Stamped `device-code`, and that stamp is what makes the blocked-flow guard possible. A
+            // cache that does not record which flow minted it cannot be refreshed safely by either.
+            protocol: 'device-code',
+            authority: config.authority,
+            clientId: config.clientId,
+        };
+        const written = store.write(cached);
+        if (!written.ok)
+            return refuse(written.refusal.reason, written.refusal.detail);
+        return ok(cached);
+    }
+    return refuse('device-code-declined', 'the device code expired before the sign-in was completed');
+}
+/**
+ * The refresher `TokenCredential` calls when its cached token has expired.
+ *
+ * An authentication-flows block discards the cache and names the flow to stop using. It does
+ * not say "sign in again".
+ *
+ * Why not: a blocked-flow refusal is the provider's policy refusing the flow (see
+ * `identity/device-code.ts`), so the trigger is a tenant admin enabling a policy, not a
+ * reconfiguration here. A refresher that cleared the cache and told the operator to sign in again
+ * would loop: `protocolFor` derives the flow from static config, so "again" would mean the same
+ * device-code flow, into the same policy. Unattended, that is refresh, blocked, clear, device code,
+ * blocked, repeat, never holding a usable token. A recovery path that returns to the failing state
+ * is not a recovery path.
+ *
+ * So it routes to the flow that is not blocked. The policy targets device code; loopback
+ * authorization-code plus PKCE is implemented here (`identity/authorize.ts`, `identity/pkce.ts`).
+ * When loopback is available the refusal says to use it; when it is not, the refusal refuses by
+ * name and tells the operator which setting to change, rather than inviting a retry that cannot
+ * succeed.
+ */
+export function refresherFor(config, endpoints, store, deps = {}) {
+    const fetchImpl = deps.fetch ?? globalThis.fetch;
+    const nowMs = deps.nowMs ?? systemTicker;
+    return async (cached) => {
+        const refreshToken = cached.tokens.refreshToken;
+        if (refreshToken === null) {
+            return refuse('token-unavailable', 'the cached token has no refresh token, so it cannot be renewed without signing in');
+        }
+        const response = await post(fetchImpl, endpoints.tokenEndpoint, refreshBody(config, refreshToken));
+        if (!response.ok)
+            return refuse(response.refusal.reason, response.refusal.detail);
+        const tokens = readTokenResponse(response.value.status, response.value.body, nowMs());
+        if (!tokens.ok) {
+            if (isAuthFlowBlocked(tokens.refusal.detail)) {
+                // Cleared either way: the provider's own guidance is that such material is unusable for good
+                // and should be deleted. What differs is what the operator is told to do next.
+                store.clear();
+                // The fallback is only a fallback if it is a different flow. Naming loopback while the
+                // host is configured for loopback would be the same loop with a new label.
+                const blockedFlow = protocolFor(config);
+                if (blockedFlow === 'device-code') {
+                    return refuse('token-unavailable', `the identity provider's policy has blocked the DEVICE CODE flow this material was minted by ` +
+                        `(provider code ${AUTH_FLOW_BLOCKED_ERROR}); the token can never be refreshed and the cache has been ` +
+                        `discarded. Do not re-run the device code flow: the same policy will block it, every time. Set ` +
+                        `deviceCodeEnabled: false (for the binary, unset PERISCOPE_IDENTITY_DEVICE_CODE) to use the loopback ` +
+                        `authorization-code (PKCE) flow, which such a policy does not target, or have the provider's ` +
+                        `administrator exempt this application.`);
+                }
+                return refuse('token-unavailable', `the identity provider's policy has blocked this material (provider code ${AUTH_FLOW_BLOCKED_ERROR}) ` +
+                    `and the cache has been discarded. This host is ALREADY configured for the loopback flow, so there is ` +
+                    `no unblocked flow left to fall back to: the policy must be changed by the provider's administrator. ` +
+                    `Retrying will not help.`);
+            }
+            return refuse(tokens.refusal.reason, tokens.refusal.detail);
+        }
+        return tokens;
+    };
+}
+/** Which flow a host configured this way will use. One place, so the cache is stamped consistently. */
+export function protocolFor(config) {
+    return config.deviceCodeEnabled ? 'device-code' : 'loopback';
+}
+//# sourceMappingURL=sign-in.js.map

package/dist/host/telemetry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Lifting cost and rate-limit facts off the agent's own stream.
+ *
+ * In `src/host/` because it names the SDK's message union, the same reason `readInitFacts` is there.
+ * The layer above branches on plain records and never learns the SDK's shapes.
+ *
+ * What is deliberately absent, and it is not an oversight: two facts a dashboard wants,
+ * `getContextUsage()` for the context ring and `accountInfo()` for the account's own limits, are
+ * methods on the query object, and this package does not hand that object out: it is the narrowing
+ * that keeps four mid-session permission mutators unreachable, and it is pinned. Reaching them means
+ * either widening that narrowing or adding a named method beside `prompt` and `interrupt`, and both
+ * are decisions above this file. Everything below arrives on the message stream, which this host
+ * already has, so none of it costs that trade.
+ */
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { RateLimitStanding, TurnSpend } from '../telemetry/usage.js';
+/**
+ * A turn's spend, or null for every message that is not a result.
+ *
+ * Every figure is copied, none computed. No token count is multiplied by anything here; the
+ * agent priced the turn and this carries what it said. That is what makes a mixed-model turn correct
+ * without this package holding a price table that would rot.
+ */
+export declare function readTurnSpend(message: SDKMessage): TurnSpend | null;
+/**
+ * Where a rate limit stands, or null for every other message.
+ *
+ * It arrives in-stream, which is the part worth noticing: no unofficial endpoint has to be polled
+ * to learn this. Nothing here polls anything.
+ */
+export declare function readRateLimit(message: SDKMessage): RateLimitStanding | null;
+/**
+ * A subagent's own usage, off the task notification that reports it.
+ *
+ * This is what makes a subagent's cost attributable: the agent reports per-task usage, and hooks
+ * carry an agent id, so spend has an owner without anything being inferred.
+ */
+export declare function readTaskSpend(message: SDKMessage): {
+    agentId: string;
+    spend: TurnSpend;
+} | null;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/host/telemetry.js

@@ -0,0 +1,74 @@
+/**
+ * A turn's spend, or null for every message that is not a result.
+ *
+ * Every figure is copied, none computed. No token count is multiplied by anything here; the
+ * agent priced the turn and this carries what it said. That is what makes a mixed-model turn correct
+ * without this package holding a price table that would rot.
+ */
+export function readTurnSpend(message) {
+    if (message.type !== 'result')
+        return null;
+    const byModel = Object.entries(message.modelUsage ?? {}).map(([model, usage]) => ({
+        model,
+        costUsd: usage.costUSD,
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        cacheReadInputTokens: usage.cacheReadInputTokens,
+        cacheCreationInputTokens: usage.cacheCreationInputTokens,
+        // Absent is null rather than zero: a zero window reads as a real, tiny limit.
+        contextWindow: usage.contextWindow ?? null,
+        canonicalModel: usage.canonicalModel ?? null,
+        provider: usage.provider ?? null,
+    }));
+    return { totalCostUsd: message.total_cost_usd, byModel };
+}
+/**
+ * Where a rate limit stands, or null for every other message.
+ *
+ * It arrives in-stream, which is the part worth noticing: no unofficial endpoint has to be polled
+ * to learn this. Nothing here polls anything.
+ */
+export function readRateLimit(message) {
+    if (message.type !== 'rate_limit_event')
+        return null;
+    const info = message.rate_limit_info;
+    return {
+        status: info.status,
+        resetsAt: info.resetsAt ?? null,
+        limitType: info.rateLimitType ?? null,
+        utilization: info.utilization ?? null,
+    };
+}
+/**
+ * A subagent's own usage, off the task notification that reports it.
+ *
+ * This is what makes a subagent's cost attributable: the agent reports per-task usage, and hooks
+ * carry an agent id, so spend has an owner without anything being inferred.
+ */
+export function readTaskSpend(message) {
+    if (message.type !== 'system' || message.subtype !== 'task_notification')
+        return null;
+    const usage = message.model_usage;
+    const totalCost = message.total_cost_usd;
+    const agentId = message.agent_id;
+    if (usage === undefined || totalCost === undefined || agentId === undefined)
+        return null;
+    return {
+        agentId,
+        spend: {
+            totalCostUsd: totalCost,
+            byModel: Object.entries(usage).map(([model, one]) => ({
+                model,
+                costUsd: one.costUSD,
+                inputTokens: one.inputTokens,
+                outputTokens: one.outputTokens,
+                cacheReadInputTokens: one.cacheReadInputTokens,
+                cacheCreationInputTokens: one.cacheCreationInputTokens,
+                contextWindow: one.contextWindow ?? null,
+                canonicalModel: one.canonicalModel ?? null,
+                provider: one.provider ?? null,
+            })),
+        },
+    };
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/host/token-cache.d.ts

@@ -0,0 +1,62 @@
+import type { Result } from '../core/result.js';
+import type { CredentialModeOutcome, ModeEnforcement } from '../identity/mode.js';
+import type { CachedTokens, TokenStore } from '../identity/store.js';
+export interface TokenCacheWrite {
+    readonly path: string;
+    readonly mode: CredentialModeOutcome;
+}
+/**
+ * Measure what this filesystem does with a mode.
+ *
+ * Measured rather than listed by platform. A `process.platform === 'win32'` test is a guess that
+ * ages: WSL, a POSIX filesystem mounted under Windows, and a future runtime mapping modes onto ACLs
+ * would each make it wrong in the direction that matters. The probe writes a throwaway file BESIDE
+ * the cache — the same filesystem, which is the thing actually in question.
+ *
+ * It asserts its positive control before it reports the negative, and that ordering is the whole
+ * design. Three measurements, in this order:
+ *
+ *   1. Ask for `0600` and for `0666`. If they read back differently AND `0600` came back as `0600`,
+ *      POSIX modes are honoured. Done.
+ *   2. They did not differ — so privacy is unconfirmable. **Before saying so, prove the instrument
+ *      is alive**: clear the write bit with `0444`. Measured on win32, that DOES read back as
+ *      `444`, because the write bit is the one real bit there. If it changes, this is a genuine
+ *      finding about a filesystem that records only writability.
+ *   3. Even `0444` changed nothing. Then the probe cannot distinguish "this filesystem records
+ *      nothing" from "this probe is broken", and it says exactly that.
+ *
+ * Without step 2, "unenforced" and "the probe never worked" are the same answer — an instrument
+ * with no inconclusive state, which is how a dead check gets read as evidence.
+ *
+ * `0444` is the control, never the target. The cache must stay owner-writable; refreshes are
+ * written to it. The probe restores a writable mode on its own throwaway file before removing it,
+ * because a read-only file is one `rmSync` can fail on.
+ */
+export declare function probeModeEnforcement(directory: string): ModeEnforcement;
+export declare class FileTokenCache implements TokenStore {
+    #private;
+    constructor(path: string);
+    get path(): string;
+    /** Memoised: the filesystem does not change its mind mid-process. */
+    modeEnforcement(): ModeEnforcement;
+    /**
+     * Read the cache.
+     *
+     * A missing file is `token-unavailable` — nobody has signed in — and that is deliberately NOT the
+     * same reason as a file that exists and cannot be parsed, which is a real problem with a real
+     * fix. Collapsing them would make a corrupted cache look like a fresh install forever.
+     */
+    read(): Result<CachedTokens>;
+    /**
+     * Write the cache, then verify what actually landed.
+     *
+     * A file that came out wider than asked is removed, not left and reported. Leaving a
+     * world-readable token on disk while returning a refusal would mean the caller sees a failure and
+     * the credential is exposed anyway — the worst of both. No cache at all is strictly safer than a
+     * readable one, and the sign-in can simply be repeated.
+     */
+    write(cached: CachedTokens): Result<TokenCacheWrite>;
+    /** Remove the cache. Idempotent — clearing a cache that is not there is success, not an error. */
+    clear(): void;
+}
+//# sourceMappingURL=token-cache.d.ts.map