@naswerks/periscope 1.0.0

package/dist/host/workspace-trust.d.ts

@@ -0,0 +1,23 @@
+export type WorkspaceTrust = 
+/** The config records this directory as trusted. */
+'trusted'
+/** The config was read and this directory is either absent from it or recorded as untrusted. */
+ | 'untrusted'
+/** No config, or one that could not be read. NOT the same as untrusted — see below. */
+ | 'unknown';
+export declare function isUntrustedWorkspaceWarning(line: string): boolean;
+/** Where the CLI keeps per-directory trust. Separate from the settings files. */
+export declare function trustConfigPath(homeDir: string): string;
+/**
+ * Read the recorded trust for `cwd`.
+ *
+ * Comparison is normalized and case-insensitive because the recorded keys are whatever absolute
+ * path the CLI was started with — `C:\x` and `c:/x` are the same directory on Windows and would
+ * otherwise read as two.
+ *
+ * `unknown` is a third answer and not a synonym for untrusted. A config that cannot be read
+ * supports no claim, and reporting "untrusted" for it would state a fact about the user's machine
+ * that was never observed.
+ */
+export declare function readWorkspaceTrust(configPath: string, cwd: string): WorkspaceTrust;
+//# sourceMappingURL=workspace-trust.d.ts.map

package/dist/host/workspace-trust.js

@@ -0,0 +1,80 @@
+/**
+ * Whether a working directory is one the agent CLI considers trusted. Read, never written.
+ *
+ * The trap this exists for: in an untrusted workspace the CLI silently voids the permission rules
+ * in `.claude/settings.json` — *"Ignoring 1 permissions.allow entry … this workspace has not been
+ * trusted"* — and that sentence is a STDERR LINE, not an error. Nothing in the SDK's type surface
+ * models trust at all. A host that provisions working directories programmatically will therefore
+ * create untrusted ones by default and never be told.
+ *
+ * Why this module reads and does not write: granting trust
+ * means writing `hasTrustDialogAccepted: true` into the user's own `~/.claude.json`, a file every
+ * running CLI rewrites, so a host that grants is racing them for user-global state it does not own.
+ * It would also remove the SYMPTOM rather than the SILENCE, and silence is the actual failure: a
+ * host that reports the condition works on a machine where granting is impossible — a read-only
+ * home, a container, another user's account — and one that grants does not.
+ *
+ * What replaces it: this package depends on no settings file (`settingSources: []` reads none, so
+ * there are no rules for an untrusted workspace to void), and where a caller opts back in, the
+ * condition is REPORTED. The permission authority is the in-process hook, which the evidence shows
+ * fires regardless of allow rules — depending on the rules instead would mean depending on the one
+ * mechanism proven to be silently voidable.
+ */
+import { readFileSync } from 'node:fs';
+import { normalizePath } from '../core/paths.js';
+/**
+ * The stderr line the CLI emits when it drops rules for this reason, as a matcher.
+ *
+ * Deliberately loose: it matches the stable part of a message whose wording the CLI owns, so a
+ * reworded prefix or a different rule count still trips it. A matcher that is too precise here fails
+ * open, which is the direction that reproduces the original silence.
+ */
+const UNTRUSTED_STDERR = /has not been trusted/i;
+export function isUntrustedWorkspaceWarning(line) {
+    return UNTRUSTED_STDERR.test(line);
+}
+/** Where the CLI keeps per-directory trust. Separate from the settings files. */
+export function trustConfigPath(homeDir) {
+    return `${normalizePath(homeDir)}/.claude.json`;
+}
+/**
+ * Read the recorded trust for `cwd`.
+ *
+ * Comparison is normalized and case-insensitive because the recorded keys are whatever absolute
+ * path the CLI was started with — `C:\x` and `c:/x` are the same directory on Windows and would
+ * otherwise read as two.
+ *
+ * `unknown` is a third answer and not a synonym for untrusted. A config that cannot be read
+ * supports no claim, and reporting "untrusted" for it would state a fact about the user's machine
+ * that was never observed.
+ */
+export function readWorkspaceTrust(configPath, cwd) {
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf8');
+    }
+    catch {
+        return 'unknown';
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return 'unknown';
+    }
+    const projects = parsed.projects;
+    if (typeof projects !== 'object' || projects === null)
+        return 'unknown';
+    const wanted = normalizePath(cwd).toLowerCase();
+    for (const [recordedPath, entry] of Object.entries(projects)) {
+        if (normalizePath(recordedPath).toLowerCase() !== wanted)
+            continue;
+        const accepted = entry.hasTrustDialogAccepted;
+        return accepted === true ? 'trusted' : 'untrusted';
+    }
+    // The file exists and lists projects; this one is simply not among them. That IS an observation:
+    // a directory the CLI has never been trusted in.
+    return 'untrusted';
+}
+//# sourceMappingURL=workspace-trust.js.map

package/dist/identity/authorize.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The authorization request, and the callback that answers it — pure, so the whole decision surface
+ * can be exercised without opening a port or a browser.
+ *
+ * The loopback redirect is what `az`, `gh` and `kubectl` do, and it is the primary flow here for
+ * the reason those tools chose it: the authorization code comes back to a listener only this
+ * machine can reach, and the browser doing the sign-in is the user's real one, with their real
+ * session, their real conditional-access evaluation and their real second factor.
+ *
+ * Nothing in this module puts an authorization code into a refusal. A code is redeemable
+ * credential material for as long as it lives, and a refusal `detail` is written to logs by
+ * definition — that is the exact path by which a credential ends up in a diagnostic. Refusals here
+ * say which field was wrong, never what it contained.
+ */
+import type { Result } from '../core/result.js';
+import type { IdentityConfig } from './config.js';
+import type { Pkce } from './pkce.js';
+/** Everything one sign-in attempt must remember between the request and the callback. */
+export interface AuthorizationRequest {
+    readonly url: string;
+    readonly state: string;
+    readonly pkce: Pkce;
+    readonly redirectUri: string;
+}
+/** The loopback redirect URI for a port the OS has already assigned. */
+export declare function redirectUriFor(port: number): string;
+/**
+ * Build the URL the user's browser is sent to.
+ *
+ * `redirectUri` is passed rather than derived because the port is not known until the listener is
+ * bound — asking the OS for a free port and then telling the provider about it is the ordinary
+ * loopback shape.
+ */
+export declare function buildAuthorizationUrl(config: IdentityConfig, authorizationEndpoint: string, pkce: Pkce, state: string, redirectUri: string): AuthorizationRequest;
+/** What the provider sent back, once it has been proven to answer this host's request. */
+export interface AuthorizationCallback {
+    readonly code: string;
+}
+/**
+ * Read a callback and decide whether it is the answer to this host's request.
+ *
+ * The `state` check runs before the code is even looked at, and that ordering is the point. A
+ * callback carrying a perfectly good authorization code from somebody else's authorization request
+ * is exactly the attack: any local process can reach this host's loopback listener, because the
+ * agent shares this host's OS user. Reading the code first and validating afterwards would work
+ * identically in every test and leave the window open.
+ *
+ * `rawQuery` is the callback request's query string, taken from the listener verbatim.
+ */
+export declare function readAuthorizationCallback(rawQuery: string, expectedState: string): Result<AuthorizationCallback>;
+/**
+ * The page the browser lands on after the callback.
+ *
+ * Deliberately static and self-contained — no script, no external asset, and nothing derived from
+ * the query string. Reflecting any part of the callback into this HTML would be a cross-site
+ * scripting hole in a page that renders in the user's real, signed-in browser.
+ */
+export declare const CALLBACK_PAGE: string;
+//# sourceMappingURL=authorize.d.ts.map

package/dist/identity/authorize.js

@@ -0,0 +1,72 @@
+import { ok, refuse } from '../core/result.js';
+import { stateMatches } from './pkce.js';
+/** The loopback redirect URI for a port the OS has already assigned. */
+export function redirectUriFor(port) {
+    // 127.0.0.1, never `localhost`. `localhost` can resolve to ::1 or be redefined in a hosts
+    // file, and the provider matches the redirect URI as a literal string — so the registered value
+    // and the listener must agree on the exact spelling, not on a name that resolves.
+    return `http://127.0.0.1:${port}/callback`;
+}
+/**
+ * Build the URL the user's browser is sent to.
+ *
+ * `redirectUri` is passed rather than derived because the port is not known until the listener is
+ * bound — asking the OS for a free port and then telling the provider about it is the ordinary
+ * loopback shape.
+ */
+export function buildAuthorizationUrl(config, authorizationEndpoint, pkce, state, redirectUri) {
+    const url = new URL(authorizationEndpoint);
+    url.searchParams.set('client_id', config.clientId);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('redirect_uri', redirectUri);
+    url.searchParams.set('scope', config.scopes.join(' '));
+    url.searchParams.set('state', state);
+    url.searchParams.set('code_challenge', pkce.challenge);
+    url.searchParams.set('code_challenge_method', pkce.method);
+    return { url: url.toString(), state, pkce, redirectUri };
+}
+/**
+ * Read a callback and decide whether it is the answer to this host's request.
+ *
+ * The `state` check runs before the code is even looked at, and that ordering is the point. A
+ * callback carrying a perfectly good authorization code from somebody else's authorization request
+ * is exactly the attack: any local process can reach this host's loopback listener, because the
+ * agent shares this host's OS user. Reading the code first and validating afterwards would work
+ * identically in every test and leave the window open.
+ *
+ * `rawQuery` is the callback request's query string, taken from the listener verbatim.
+ */
+export function readAuthorizationCallback(rawQuery, expectedState) {
+    const params = new URLSearchParams(rawQuery);
+    const receivedState = params.get('state');
+    if (receivedState === null || !stateMatches(expectedState, receivedState)) {
+        return refuse('auth-state-mismatch', receivedState === null
+            ? "the callback carried no state value, so it cannot be shown to answer this host's request"
+            : "the callback's state is not the one this host minted — this callback answers somebody else's authorization request and its code is not redeemed");
+    }
+    // Only now is anything else in the callback worth reading.
+    const error = params.get('error');
+    if (error !== null) {
+        const description = params.get('error_description');
+        return refuse('auth-callback-refused', `the provider returned ${error}${description === null ? '' : `: ${description}`}`);
+    }
+    const code = params.get('code');
+    if (code === null || code === '') {
+        return refuse('auth-callback-refused', 'the callback carried neither an authorization code nor an error, so there is nothing to redeem');
+    }
+    return ok({ code });
+}
+/**
+ * The page the browser lands on after the callback.
+ *
+ * Deliberately static and self-contained — no script, no external asset, and nothing derived from
+ * the query string. Reflecting any part of the callback into this HTML would be a cross-site
+ * scripting hole in a page that renders in the user's real, signed-in browser.
+ */
+export const CALLBACK_PAGE = [
+    '<!doctype html><meta charset="utf-8"><title>Signed in</title>',
+    '<body style="font-family:system-ui;padding:2rem">',
+    '<h1>Signed in</h1><p>You can close this tab and return to the terminal.</p>',
+    '</body>',
+].join('');
+//# sourceMappingURL=authorize.js.map

package/dist/identity/config.d.ts

@@ -0,0 +1,98 @@
+/**
+ * What this host needs to know before it can sign anyone in — and the named refusal when it does
+ * not know it.
+ *
+ * The authority is config, never a constant. That is the one thing this module exists to
+ * guarantee. A hardcoded issuer would make the package work for exactly one tenant and look like it
+ * worked for everyone, and it is the difference between something a stranger can point at their own
+ * provider and something only its authors can run. `pins/identity-generic.test.ts` scans the source
+ * for an embedded authority host, so this cannot regress quietly.
+ *
+ * Absence is a refusal with a name, not a default. There is no fallback issuer, no implicit
+ * tenant, and no "unauthenticated mode" — a host that cannot prove who it is does not connect. The
+ * two unset/invalid reasons are kept apart because they are different people's problems: nothing
+ * configured is a setup step nobody has done, and a bad value is a setup step done wrong.
+ */
+import type { Result } from '../core/result.js';
+/**
+ * The endpoints an OAuth 2.0 authorization-code exchange needs.
+ *
+ * Separate from the config because there are two honest ways to get them — the operator states
+ * them, or they are read from the provider's discovery document — and the flow should not care
+ * which happened.
+ */
+export interface IdentityEndpoints {
+    readonly authorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    /** Null when the provider does not advertise the device-code grant. */
+    readonly deviceAuthorizationEndpoint: string | null;
+}
+export interface IdentityConfig {
+    /**
+     * The issuer this host authenticates against.
+     *
+     * A consumer-identity (CIAM) authority is typically single-tenant — so a workplace's employees
+     * cannot sign in to it. The answer to that is a registration in the workplace's own tenant
+     * pointed at by this value, which costs no code precisely because this is a setting. See the
+     * README's deployment note.
+     */
+    readonly authority: string;
+    readonly clientId: string;
+    readonly scopes: readonly string[];
+    /** Explicitly stated endpoints; null means "read the discovery document". */
+    readonly endpoints: IdentityEndpoints | null;
+    /** Loopback redirect port. 0 asks the OS for a free one, which is the ordinary case. */
+    readonly redirectPort: number;
+    /**
+     * Off unless the operator turns it on. The device-code grant is never reached by falling back
+     * to it — see `device-code.ts` for why the provider itself recommends blocking it.
+     */
+    readonly deviceCodeEnabled: boolean;
+}
+/**
+ * `offline_access` is in the default set deliberately: without a refresh token every access token
+ * expiring means an interactive sign-in, and this host is meant to run unattended.
+ */
+export declare const DEFAULT_SCOPES: readonly string[];
+/**
+ * Read the identity configuration, or say precisely what is missing.
+ *
+ * The environment is passed in rather than read, matching the rest of the package: the composition
+ * root supplies the environment, helpers only default to `process.env` when called bare, and every
+ * module below the root is testable without a process.
+ */
+export declare function readIdentityConfig(env: NodeJS.ProcessEnv): Result<IdentityConfig>;
+/**
+ * What the composition root should do about identity, decided here so `bin/` stays a wiring file.
+ *
+ * The three-way split is the point, and the middle one is the easy mistake. "Configured wrong"
+ * must not degrade to "not configured": an operator who set an authority and mistyped it has stated
+ * an intention, and silently starting without identity would honour the typo instead of the
+ * intention — the host would come up looking healthy and authenticate as nobody.
+ *
+ *   configured    — build the real credential.
+ *   absent        — nothing was set. Start without identity; the existing credential refuses by
+ *                   name, which is exactly what this host did before identity existed.
+ *   invalid       — something was set and cannot be used. Refuse to start.
+ */
+export type IdentityPosture = {
+    readonly kind: 'configured';
+    readonly config: IdentityConfig;
+} | {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'invalid';
+    readonly detail: string;
+};
+export declare function identityPosture(env: NodeJS.ProcessEnv): IdentityPosture;
+/**
+ * The provider's discovery document URL.
+ *
+ * OpenID Connect Discovery, so this works for any conforming provider rather than one vendor's URL
+ * shape. The trailing-slash handling matters: `new URL('.well-known/…', 'https://x/tenant')` would
+ * drop `tenant`.
+ */
+export declare function discoveryUrl(authority: string): string;
+/** Parse a discovery document into the endpoints, refusing anything that is not usable. */
+export declare function readDiscoveryDocument(body: unknown): Result<IdentityEndpoints>;
+//# sourceMappingURL=config.d.ts.map

package/dist/identity/config.js

@@ -0,0 +1,130 @@
+import { ok, refuse } from '../core/result.js';
+/**
+ * `offline_access` is in the default set deliberately: without a refresh token every access token
+ * expiring means an interactive sign-in, and this host is meant to run unattended.
+ */
+export const DEFAULT_SCOPES = ['openid', 'profile', 'offline_access'];
+const REQUIRED = 'PERISCOPE_IDENTITY_AUTHORITY and PERISCOPE_IDENTITY_CLIENT_ID';
+function trimmed(env, key) {
+    const value = env[key];
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+}
+/**
+ * Is this a usable issuer URL?
+ *
+ * HTTPS is required and `localhost` is not exempted. A plaintext authority would put the
+ * authorization code and then the token itself on the wire in clear, and "it is only the test
+ * environment" is how that reaches production. A provider being tested locally is reached through
+ * its real https endpoint like any other.
+ */
+function invalidAuthority(authority) {
+    let parsed;
+    try {
+        parsed = new URL(authority);
+    }
+    catch {
+        return `PERISCOPE_IDENTITY_AUTHORITY is not a URL: ${authority}`;
+    }
+    if (parsed.protocol !== 'https:') {
+        return `PERISCOPE_IDENTITY_AUTHORITY must be https, got ${parsed.protocol}//`;
+    }
+    return null;
+}
+/** Endpoints are all-or-nothing: a half-stated set is a config error, never a partial default. */
+function readEndpoints(env) {
+    const authorizationEndpoint = trimmed(env, 'PERISCOPE_IDENTITY_AUTHORIZE_URL');
+    const tokenEndpoint = trimmed(env, 'PERISCOPE_IDENTITY_TOKEN_URL');
+    const deviceAuthorizationEndpoint = trimmed(env, 'PERISCOPE_IDENTITY_DEVICE_CODE_URL');
+    if (authorizationEndpoint === null && tokenEndpoint === null) {
+        // Neither stated: discovery will supply both. The device endpoint alone is not enough to act on.
+        return ok(null);
+    }
+    if (authorizationEndpoint === null || tokenEndpoint === null) {
+        return refuse('identity-config-invalid', 'PERISCOPE_IDENTITY_AUTHORIZE_URL and PERISCOPE_IDENTITY_TOKEN_URL must be set together or not at all — a half-stated endpoint set would silently discover the other half and mix two providers');
+    }
+    return ok({ authorizationEndpoint, tokenEndpoint, deviceAuthorizationEndpoint });
+}
+function readPort(env) {
+    const raw = trimmed(env, 'PERISCOPE_IDENTITY_REDIRECT_PORT');
+    if (raw === null)
+        return ok(0);
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        return refuse('identity-config-invalid', `PERISCOPE_IDENTITY_REDIRECT_PORT must be an integer 0-65535, got ${raw}`);
+    }
+    return ok(port);
+}
+/**
+ * Read the identity configuration, or say precisely what is missing.
+ *
+ * The environment is passed in rather than read, matching the rest of the package: the composition
+ * root supplies the environment, helpers only default to `process.env` when called bare, and every
+ * module below the root is testable without a process.
+ */
+export function readIdentityConfig(env) {
+    const authority = trimmed(env, 'PERISCOPE_IDENTITY_AUTHORITY');
+    const clientId = trimmed(env, 'PERISCOPE_IDENTITY_CLIENT_ID');
+    if (authority === null || clientId === null) {
+        return refuse('identity-not-configured', `${REQUIRED} must both be set; this host does not authenticate without them and has no default issuer`);
+    }
+    const badAuthority = invalidAuthority(authority);
+    if (badAuthority !== null)
+        return refuse('identity-config-invalid', badAuthority);
+    const endpoints = readEndpoints(env);
+    if (!endpoints.ok)
+        return refuse(endpoints.refusal.reason, endpoints.refusal.detail);
+    const port = readPort(env);
+    if (!port.ok)
+        return refuse(port.refusal.reason, port.refusal.detail);
+    const rawScopes = trimmed(env, 'PERISCOPE_IDENTITY_SCOPES');
+    const scopes = rawScopes === null ? DEFAULT_SCOPES : rawScopes.split(/[\s,]+/).filter((scope) => scope !== '');
+    if (scopes.length === 0) {
+        return refuse('identity-config-invalid', 'PERISCOPE_IDENTITY_SCOPES was set but lists no scope');
+    }
+    return ok({
+        authority,
+        clientId,
+        scopes,
+        endpoints: endpoints.value,
+        redirectPort: port.value,
+        deviceCodeEnabled: trimmed(env, 'PERISCOPE_IDENTITY_DEVICE_CODE') === '1',
+    });
+}
+export function identityPosture(env) {
+    const result = readIdentityConfig(env);
+    if (result.ok)
+        return { kind: 'configured', config: result.value };
+    if (result.refusal.reason === 'identity-not-configured')
+        return { kind: 'absent' };
+    return { kind: 'invalid', detail: result.refusal.detail };
+}
+/**
+ * The provider's discovery document URL.
+ *
+ * OpenID Connect Discovery, so this works for any conforming provider rather than one vendor's URL
+ * shape. The trailing-slash handling matters: `new URL('.well-known/…', 'https://x/tenant')` would
+ * drop `tenant`.
+ */
+export function discoveryUrl(authority) {
+    const base = authority.endsWith('/') ? authority : `${authority}/`;
+    return new URL('.well-known/openid-configuration', base).toString();
+}
+/** Parse a discovery document into the endpoints, refusing anything that is not usable. */
+export function readDiscoveryDocument(body) {
+    if (typeof body !== 'object' || body === null) {
+        return refuse('identity-config-invalid', 'the discovery document is not a JSON object');
+    }
+    const record = body;
+    const authorizationEndpoint = record['authorization_endpoint'];
+    const tokenEndpoint = record['token_endpoint'];
+    const deviceAuthorizationEndpoint = record['device_authorization_endpoint'];
+    if (typeof authorizationEndpoint !== 'string' || typeof tokenEndpoint !== 'string') {
+        return refuse('identity-config-invalid', 'the discovery document does not advertise both authorization_endpoint and token_endpoint');
+    }
+    return ok({
+        authorizationEndpoint,
+        tokenEndpoint,
+        deviceAuthorizationEndpoint: typeof deviceAuthorizationEndpoint === 'string' ? deviceAuthorizationEndpoint : null,
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/identity/credential.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Presenting the user's own token to the controller.
+ *
+ * What this replaces: a host reaching its controller with a shared secret that authenticates it as
+ * any user, which every agent on the box can read. What it presents instead is one user's own
+ * access token: scoped to them, expiring by itself, and revocable from the identity provider
+ * without anyone touching this machine. That is a different order of exposure, not a smaller
+ * amount of the same one.
+ *
+ * `authorize()` never starts an interactive sign-in. It reads what is cached, refreshes silently
+ * when it can, and otherwise refuses by name. Opening a browser from inside a reconnect would mean
+ * an unattended host at 3am trying to render a login page nobody is looking at, retrying forever —
+ * and on a headless box it would simply hang. Signing in is a deliberate act somebody performs;
+ * this is the part that runs on its own.
+ *
+ * And it never reads `apiKeySource` to decide anything. That field names which key source an
+ * agent session used, and it reads `none` on a session that is fully authenticated and billing real
+ * money — ambient and subscription auth are not keys. It looks exactly like an "is this
+ * authenticated" answer and is not one. Authentication state here comes from the cache and the
+ * token's own expiry; for an agent session, a completed turn is the proof.
+ */
+import type { Authorization, ControllerCredential } from '../control/credential.js';
+import type { Ticker } from '../core/time.js';
+import type { RefusalReason } from '../core/refusal.js';
+import type { Result } from '../core/result.js';
+import type { IdentityConfig } from './config.js';
+import type { AuthProtocol } from './device-code.js';
+import type { CachedTokens, TokenStore } from './store.js';
+import type { TokenSet } from './token.js';
+/**
+ * Exchanges a refresh token for a fresh set.
+ *
+ * Injected so the credential's whole decision surface is testable without a network, and so the
+ * transport stays in one place.
+ */
+export type TokenRefresher = (cached: CachedTokens) => Promise<Result<TokenSet>>;
+/**
+ * Which of the three things `authorize()` did — because from the outside they are identical.
+ *
+ * Nothing under `identity/` emits anything, and `control/link.ts` swallows a credential refusal
+ * and connects with no header rather than pretending to hold a scheme — which is deliberate.
+ * Without a report, a cache hit, a silent refresh and "nobody has ever signed in on this machine"
+ * produce byte-identical output, and the first thing that distinguishes them is a 401 arriving
+ * from the controller minutes later. On a binary running on the user's own laptop that reads as a
+ * server problem, and the user is never told the one thing they can act on.
+ *
+ * It carries no token material, and that is a contract rather than an oversight — an outcome name,
+ * a refusal reason and the refusal's own already-human detail. Pinned by this package's own suite.
+ */
+export type CredentialOutcome = {
+    readonly kind: 'cache-hit';
+} | {
+    readonly kind: 'refreshed';
+} | {
+    readonly kind: 'refused';
+    readonly reason: RefusalReason;
+    readonly detail: string;
+};
+/**
+ * Where an outcome is reported.
+ *
+ * Data, not a log line. `identity/` returns `Result`s and formats nothing, on the same split every
+ * other seam in this package uses: the embedder decides what a line looks like and where it goes.
+ */
+export type CredentialReporter = (outcome: CredentialOutcome) => void;
+export interface TokenCredentialOptions {
+    readonly store: TokenStore;
+    readonly config: IdentityConfig;
+    /** Which flow this host is configured to use — the protocol-mismatch guard compares against it. */
+    readonly protocol: AuthProtocol;
+    /** The package's own millisecond ticker, injected like every other clock here. */
+    readonly nowMs: Ticker;
+    /** Omit to refuse rather than refresh — useful for a host that only ever reads. */
+    readonly refresh?: TokenRefresher;
+    /** Omit for a credential that decides in silence, which is what this was before it could say. */
+    readonly report?: CredentialReporter;
+}
+/** The header the controller link puts on its connect request. */
+export declare const AUTHORIZATION_HEADER = "Authorization";
+export declare class TokenCredential implements ControllerCredential {
+    #private;
+    constructor(options: TokenCredentialOptions);
+    /**
+     * One report, at one place, derived from the decision rather than repeated alongside it.
+     *
+     * `#decide` holds every branch and this holds the only call to `report`, so a path added later
+     * cannot forget to say what it did — which is precisely how a silent path arises.
+     */
+    authorize(): Promise<Result<Authorization>>;
+}
+//# sourceMappingURL=credential.d.ts.map

package/dist/identity/credential.js

@@ -0,0 +1,76 @@
+import { ok, refuse } from '../core/result.js';
+import { discardOnProtocolMismatch } from './device-code.js';
+import { authorizationValue, isFresh } from './token.js';
+/** The header the controller link puts on its connect request. */
+export const AUTHORIZATION_HEADER = 'Authorization';
+export class TokenCredential {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    /**
+     * One report, at one place, derived from the decision rather than repeated alongside it.
+     *
+     * `#decide` holds every branch and this holds the only call to `report`, so a path added later
+     * cannot forget to say what it did — which is precisely how a silent path arises.
+     */
+    async authorize() {
+        const decided = await this.#decide();
+        const report = this.#options.report;
+        if (report !== undefined) {
+            report(decided.ok
+                ? { kind: decided.value.via }
+                : { kind: 'refused', reason: decided.refusal.reason, detail: decided.refusal.detail });
+        }
+        if (!decided.ok)
+            return refuse(decided.refusal.reason, decided.refusal.detail);
+        return ok(decided.value.authorization);
+    }
+    async #decide() {
+        const { store, config, protocol, nowMs, refresh } = this.#options;
+        const cached = store.read();
+        if (!cached.ok)
+            return refuse(cached.refusal.reason, cached.refusal.detail);
+        // A cache minted for a different provider or client is not a token this host may present. It is
+        // discarded rather than kept, because leaving it means every later read re-derives the same
+        // refusal from material that will never become valid.
+        if (cached.value.authority !== config.authority || cached.value.clientId !== config.clientId) {
+            store.clear();
+            return refuse('token-unavailable', 'the cached token was minted for a different authority or client than this host is now configured for; it has been discarded — sign in again');
+        }
+        // The protocol-mismatch guard. Material minted by one flow is discarded when the host is now
+        // configured for the other: a refresh across flows fails for a reason nobody would connect to a
+        // sign-in weeks earlier. Discarding now turns an unexplainable future failure into one sign-in
+        // today. This is not the blocked-flow policy case — see `device-code.ts` for that one.
+        if (discardOnProtocolMismatch(cached.value.protocol, protocol)) {
+            store.clear();
+            return refuse('token-unavailable', `the cached token was obtained by the ${cached.value.protocol} flow and this host is configured for ${protocol}; it cannot be refreshed across flows and has been discarded — sign in again`);
+        }
+        if (isFresh(cached.value.tokens, nowMs())) {
+            return ok({ authorization: present(cached.value.tokens), via: 'cache-hit' });
+        }
+        if (cached.value.tokens.refreshToken === null || refresh === undefined) {
+            return refuse('token-unavailable', 'the cached token has expired and there is no refresh token to renew it with — sign in again');
+        }
+        const refreshed = await refresh(cached.value);
+        if (!refreshed.ok)
+            return refuse(refreshed.refusal.reason, refreshed.refusal.detail);
+        // A provider that issues no new refresh token on a refresh means the old one keeps working;
+        // dropping it would turn the next expiry into an interactive sign-in for no reason.
+        const tokens = {
+            ...refreshed.value,
+            refreshToken: refreshed.value.refreshToken ?? cached.value.tokens.refreshToken,
+        };
+        const written = store.write({ ...cached.value, tokens });
+        // A cache that could not be written is not a reason to refuse a token already held. The
+        // refresh succeeded; failing here would take a working host down over a disk problem, and the
+        // only cost of continuing is signing in again after a restart. The refusal is still surfaced by
+        // the write path's own return value for anyone who wants it.
+        void written;
+        return ok({ authorization: present(tokens), via: 'refreshed' });
+    }
+}
+function present(tokens) {
+    return { header: AUTHORIZATION_HEADER, value: authorizationValue(tokens) };
+}
+//# sourceMappingURL=credential.js.map