@naswerks/periscope 1.0.0 → 1.0.1

package/src/identity/device-code.ts

@@ -0,0 +1,217 @@
+/**
+ * The device-code fallback — for a box with no browser on it, which for this package is not an edge
+ * case but a deployment target.
+ *
+ * It is off unless explicitly configured, and it is never reached by falling back. Microsoft's
+ * guidance classes device code as a high-risk flow that phishing campaigns exploit and recommends
+ * that organisations block it (the Conditional Access authentication-flows documentation,
+ * https://learn.microsoft.com/entra/identity/conditional-access/concept-authentication-flows#device-code-flow);
+ * it is also exactly what workplace Conditional Access
+ * policies block, so a tenant refusing it outright is an expected outcome rather than a bug. A flow
+ * with that standing must be asked for by name — silently falling back to it when the loopback
+ * listener cannot bind would be the host quietly choosing the riskier option on the operator's
+ * behalf, at the moment they are least able to notice.
+ *
+ * And the trap that is invisible for weeks. A provider that tracks which protocol issued a token
+ * marks a refresh token obtained through device code as such, and a later non-device-code refresh
+ * against it fails with `AADSTS530036`; the provider's guidance is that such a token is unusable
+ * for good and should be deleted.
+ * The failure does not appear at sign-in; it appears the first time the token is refreshed, which
+ * for an unattended host is hours or weeks later and nowhere near the cause. So a device-code
+ * sign-in poisons the cache for any other flow: if this
+ * host ever switches a deployment back to loopback, the cached material must be discarded, not
+ * refreshed. `discardOnProtocolMismatch` is how that is decided rather than discovered.
+ */
+import type { Refusal } from '../core/refusal.js';
+import { refusal } from '../core/refusal.js';
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import type { IdentityConfig } from './config.js';
+import { redactSecrets, secretsIn } from './token.js';
+
+/** Which flow minted the material this host holds. Recorded so the trap above is decidable. */
+export type AuthProtocol = 'loopback' | 'device-code';
+
+/**
+ * The error code the provider returns when a Conditional Access authentication-flows policy
+ * rejects a refresh. Named so a reader can search for it.
+ *
+ * It is not a cross-protocol error, and naming it as one names the wrong cause. `AADSTS530036` is
+ * not "you refreshed device-code material with a different flow". Microsoft's documentation
+ * describes it as a Conditional Access authentication-flows check refusing the refresh token, and
+ * because such a policy applies to every application the token is unusable for good and should be
+ * deleted. The mechanism is protocol tracking: a session established with device code stays marked
+ * through every later refresh, and the tenant's policy then rejects it, so the trigger is an
+ * administrator enabling a policy, not this host being reconfigured. Source:
+ * https://learn.microsoft.com/entra/identity/conditional-access/concept-authentication-flows#device-code-flow
+ *
+ * A cross-protocol name would be dangerous rather than merely inaccurate: it would imply the fix
+ * is to sign in again, which re-runs the same flow into the same policy, forever. And it is the
+ * policy Microsoft actively recommends: allow device code only where a documented case needs it
+ * and block it everywhere else
+ * (https://learn.microsoft.com/entra/identity/conditional-access/policy-block-authentication-flows).
+ * See `host/sign-in.ts` for the recovery
+ * this routes to.
+ */
+export const AUTH_FLOW_BLOCKED_ERROR = 'AADSTS530036';
+
+/**
+ * Every provider code known to mean "a policy has blocked the flow this material was minted by".
+ * One today; a provider that reports the same condition under another code is added here, and
+ * only here: this file is the one place in the package that may know a provider's error codes.
+ */
+export const AUTH_FLOW_BLOCKED_CODES: readonly string[] = [AUTH_FLOW_BLOCKED_ERROR];
+
+export interface DeviceAuthorization {
+  readonly deviceCode: string;
+  readonly userCode: string;
+  readonly verificationUri: string;
+  readonly expiresAt: number;
+  readonly intervalMs: number;
+}
+
+/** The provider's answer to one poll. */
+export type DevicePollOutcome =
+  | { readonly kind: 'pending' }
+  /** The provider asked the caller to back off; the caller widens its interval by this much. */
+  | { readonly kind: 'slow-down'; readonly intervalMs: number }
+  | { readonly kind: 'ready' }
+  | { readonly kind: 'declined'; readonly refusal: Refusal };
+
+/**
+ * Refuse the device-code flow unless it was turned on.
+ *
+ * Exported and total so the refusal is reachable in a test rather than being a branch nobody drives.
+ */
+export function requireDeviceCodeEnabled(config: IdentityConfig): Result<true> {
+  if (!config.deviceCodeEnabled) {
+    return refuse(
+      'device-code-not-enabled',
+      'the device-code flow is not enabled on this host; set PERISCOPE_IDENTITY_DEVICE_CODE=1 to allow it, and expect some tenants to refuse it by policy',
+    );
+  }
+  return ok(true);
+}
+
+export function deviceAuthorizationBody(config: IdentityConfig): string {
+  const body = new URLSearchParams();
+  body.set('client_id', config.clientId);
+  body.set('scope', config.scopes.join(' '));
+  return body.toString();
+}
+
+export function devicePollBody(config: IdentityConfig, deviceCode: string): string {
+  const body = new URLSearchParams();
+  // RFC 8628's grant type, urn-namespaced.
+  body.set('grant_type', 'urn:ietf:params:oauth:grant-type:device_code');
+  body.set('client_id', config.clientId);
+  body.set('device_code', deviceCode);
+  return body.toString();
+}
+
+export function readDeviceAuthorization(
+  status: number,
+  body: unknown,
+  nowMs: number,
+): Result<DeviceAuthorization> {
+  const secrets = secretsIn(body);
+  if (typeof body !== 'object' || body === null) {
+    return refuse(
+      'device-code-declined',
+      `the device authorization endpoint returned HTTP ${status} with no JSON body`,
+    );
+  }
+  const record = body as Record<string, unknown>;
+
+  if (status < 200 || status >= 300) {
+    const error = typeof record['error'] === 'string' ? record['error'] : `HTTP ${status}`;
+    return refuse(
+      'device-code-declined',
+      redactSecrets(
+        `the device authorization endpoint refused: ${error} — some tenants block this flow by policy`,
+        secrets,
+      ),
+    );
+  }
+
+  const deviceCode = record['device_code'];
+  const userCode = record['user_code'];
+  const verificationUri = record['verification_uri'] ?? record['verification_url'];
+  const expiresIn = Number(record['expires_in']);
+  const interval = Number(record['interval']);
+
+  if (typeof deviceCode !== 'string' || typeof userCode !== 'string' || typeof verificationUri !== 'string') {
+    return refuse(
+      'device-code-declined',
+      'the device authorization response is missing device_code, user_code or verification_uri',
+    );
+  }
+  if (!Number.isFinite(expiresIn) || expiresIn <= 0) {
+    return refuse('device-code-declined', 'the device authorization response carries no usable expires_in');
+  }
+
+  return ok({
+    deviceCode,
+    userCode,
+    verificationUri,
+    expiresAt: nowMs + expiresIn * 1000,
+    // RFC 8628 says default to 5 seconds when the provider does not state an interval.
+    intervalMs: (Number.isFinite(interval) && interval > 0 ? interval : 5) * 1000,
+  });
+}
+
+/**
+ * Read one poll response.
+ *
+ * `authorization_pending` and `slow_down` are not failures — they are the protocol working. Mapping
+ * them onto a refusal would end a sign-in that was proceeding normally.
+ */
+export function readDevicePoll(status: number, body: unknown, currentIntervalMs: number): DevicePollOutcome {
+  if (status >= 200 && status < 300) return { kind: 'ready' };
+
+  const record = typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {};
+  const error = typeof record['error'] === 'string' ? record['error'] : `http_${status}`;
+
+  if (error === 'authorization_pending') return { kind: 'pending' };
+  if (error === 'slow_down') return { kind: 'slow-down', intervalMs: currentIntervalMs + 5_000 };
+
+  const description = typeof record['error_description'] === 'string' ? record['error_description'] : null;
+  return {
+    kind: 'declined',
+    refusal: refusal(
+      'device-code-declined',
+      redactSecrets(
+        description === null
+          ? `the device-code sign-in ended: ${error}`
+          : `the device-code sign-in ended: ${error} — ${description}`,
+        secretsIn(body),
+      ),
+    ),
+  };
+}
+
+/**
+ * Must cached material be discarded rather than refreshed, because this host was reconfigured?
+ *
+ * This is not the `AADSTS530036` guard. It detects one real but narrow
+ * case: the cache was minted by one flow and the host is now configured for the other, so a refresh
+ * would fail for a reason nobody would connect to a sign-in that happened weeks ago.
+ *
+ * It cannot fire on the policy case, which is the common one. When a tenant enables the
+ * authentication-flows policy, the host is still configured for device code and the cache was still
+ * minted by device code — `cached === configured`, so this returns `false` and nothing is discarded.
+ * A guard named for an error it is structurally unable to catch is worse than no guard, because it
+ * reads as coverage. The reactive path in `host/sign-in.ts` is what handles the policy case.
+ */
+export function discardOnProtocolMismatch(cached: AuthProtocol, configured: AuthProtocol): boolean {
+  return cached !== configured;
+}
+
+/**
+ * Does this provider error mean a Conditional Access authentication-flows policy has blocked this
+ * material permanently? Microsoft's documentation: "the token will never be usable and should be
+ * deleted."
+ */
+export function isAuthFlowBlocked(errorText: string): boolean {
+  return AUTH_FLOW_BLOCKED_CODES.some((code) => errorText.includes(code));
+}

package/src/identity/index.ts

@@ -0,0 +1,84 @@
+/**
+ * Identity — signing a real user in, holding what that produced, and presenting it.
+ *
+ * Every module behind this barrel is pure. The two impure halves live in `host/`
+ * (`token-cache.ts` writes the file, `loopback.ts` opens the port), which is where this package
+ * confines anything that touches the machine. That split is the same one the gate uses, and it is
+ * what makes the awkward branches — a malformed cache, a callback with the wrong `state`, a
+ * filesystem that ignores modes — drivable without a machine in that state.
+ *
+ * Nothing here names a provider. The authority, client and endpoints are configuration, and the
+ * flows are RFC 6749 / 7636 / 8628 as written. Any one commercial provider is a configuration of
+ * this, not the shape of it — which is what lets somebody point this at their own provider and
+ * have it work.
+ */
+export type { IdentityConfig, IdentityEndpoints, IdentityPosture } from './config.js';
+export {
+  DEFAULT_SCOPES,
+  discoveryUrl,
+  identityPosture,
+  readDiscoveryDocument,
+  readIdentityConfig,
+} from './config.js';
+
+export type { Pkce } from './pkce.js';
+export {
+  CODE_CHALLENGE_METHOD,
+  challengeFor,
+  createPkce,
+  createState,
+  randomUrlSafe,
+  requireS256,
+  stateMatches,
+} from './pkce.js';
+
+export type { AuthorizationCallback, AuthorizationRequest } from './authorize.js';
+export {
+  CALLBACK_PAGE,
+  buildAuthorizationUrl,
+  readAuthorizationCallback,
+  redirectUriFor,
+} from './authorize.js';
+
+export type { TokenSet } from './token.js';
+export {
+  EXPIRY_SKEW_MS,
+  authorizationValue,
+  codeExchangeBody,
+  isFresh,
+  readTokenResponse,
+  redactSecrets,
+  refreshBody,
+  secretsIn,
+} from './token.js';
+
+export type { CredentialModeOutcome, ModeEnforcement } from './mode.js';
+export {
+  CREDENTIAL_MODE,
+  classifyCredentialMode,
+  classifyProbeReadings,
+  isWiderThan,
+  toOctal,
+} from './mode.js';
+
+export type { AuthProtocol, DeviceAuthorization, DevicePollOutcome } from './device-code.js';
+export {
+  AUTH_FLOW_BLOCKED_CODES,
+  AUTH_FLOW_BLOCKED_ERROR,
+  deviceAuthorizationBody,
+  devicePollBody,
+  discardOnProtocolMismatch,
+  isAuthFlowBlocked,
+  readDeviceAuthorization,
+  readDevicePoll,
+  requireDeviceCodeEnabled,
+} from './device-code.js';
+
+export type { CachedTokens, TokenStore } from './store.js';
+export { readCachedTokens } from './store.js';
+
+export type { TokenCredentialOptions, TokenRefresher } from './credential.js';
+export { AUTHORIZATION_HEADER, TokenCredential } from './credential.js';
+
+export type { PairedCredentialFile, PairedCredentialStore } from './paired-credential.js';
+export { PairedHostCredential, readPairedCredentialFile } from './paired-credential.js';

package/src/identity/mode.ts

@@ -0,0 +1,161 @@
+/**
+ * Whether the token file on disk is actually as private as requested — decided here, purely, so
+ * every branch can be driven on any platform.
+ *
+ * The defect, observed on win32 rather than reasoned. On win32, `node` accepts a `0o600` mode and
+ * does nothing with it: writing with `{mode: 0o600}` and then `chmod`ing to `0o600` both leave
+ * `statSync().mode & 0o777` reading `0o666`, and a deliberately world-readable `0o666` file reads
+ * exactly the same. So on Windows a restricted token file and an unrestricted one are
+ * indistinguishable through the only API available.
+ *
+ * That makes the obvious implementation wrong in both directions, which is why this is a module and
+ * not an `if`:
+ *
+ *   - Verify literally (`observed === 0o600`) and the host refuses every write on Windows — it
+ *     would be unusable there.
+ *   - Relax it to "not world-writable" and the check passes vacuously on Windows while proving
+ *     nothing at all — a green that reads as evidence.
+ *
+ * So the third answer is the only honest one: where modes are enforced, verify and refuse if the
+ * file came out wider than asked. Where they are not, say so by name as a degrade. A degrade is
+ * a named outcome, never a silent pass — and "this could not be confirmed" is a fact an operator
+ * can act on, while a checkmark that means nothing is not.
+ *
+ * Enforcement is measured, not assumed from `process.platform`. The caller probes it (see
+ * `host/token-cache.ts`) and passes the answer in. A platform list would be a guess that ages;
+ * WSL, a POSIX filesystem mounted on Windows, or a future runtime that maps modes onto ACLs would
+ * each make the guess wrong in the direction that matters.
+ *
+ * And the measurement has an inconclusive state, which is why this is a three-way enum and not a
+ * boolean. A probe that reports "not enforced" is only worth anything if it could have reported
+ * something else. On win32, `chmod 0444` does read back as `444`, so the write bit is real even
+ * though the read/group/other bits are fabricated as `6`. That gives the probe a positive control
+ * — it can demonstrate it observes something before it claims it cannot observe privacy.
+ * Without that, "unenforced" and "my probe is broken" are the same answer, and an instrument with
+ * no inconclusive state reports confidence it has not earned.
+ */
+import type { Refusal } from '../core/refusal.js';
+import { refusal } from '../core/refusal.js';
+
+/** The mode credential material is written with, everywhere. */
+export const CREDENTIAL_MODE = 0o600;
+
+const PERMISSION_BITS = 0o777;
+
+/** What the filesystem was measured to do with a mode. */
+export type ModeEnforcement =
+  /** POSIX modes are honoured: what was asked for is what came back, and wide differs from narrow. */
+  | 'enforced'
+  /**
+   * Measured, and the answer is that only the write bit survives — the win32 shape. `0600` and
+   * `0666` are indistinguishable, so privacy cannot be confirmed; but `0444` reads back as `444`,
+   * so the instrument is live and this is a real finding rather than a dead probe.
+   */
+  | 'write-bit-only'
+  /**
+   * Inconclusive. No mode change was observable at all, not even clearing the write bit. The
+   * probe cannot distinguish "this filesystem records nothing" from "this probe is broken", and
+   * saying so is the only honest option.
+   */
+  | 'unobservable';
+
+export type CredentialModeOutcome =
+  /** Modes are enforced here and the file is exactly as private as requested. */
+  | { readonly kind: 'verified'; readonly observed: number }
+  /** Modes are enforced here and the file is readable or writable by more than its owner. */
+  | { readonly kind: 'too-wide'; readonly observed: number; readonly refusal: Refusal }
+  /** Not a failure: privacy is unconfirmable here, and that was measured rather than assumed. */
+  | { readonly kind: 'unenforced'; readonly observed: number; readonly refusal: Refusal }
+  /** Not even a measurement: the instrument could observe nothing. Worth investigating. */
+  | { readonly kind: 'unobservable'; readonly observed: number; readonly refusal: Refusal };
+
+/** Is any permission bit set that was not requested? */
+export function isWiderThan(observed: number, requested: number): boolean {
+  return (observed & ~requested & PERMISSION_BITS) !== 0;
+}
+
+/**
+ * Decide what three probe readings mean. Pure, so the shapes this machine cannot produce are still
+ * drivable.
+ *
+ * This function exists because the obvious control is vacuous. Without the `0444` reading, on
+ * win32 a probe that runs the control and a probe that merely assumes its answer both report
+ * `write-bit-only`, so nothing on that machine can tell them apart. What is uniquely lost is the
+ * ability to distinguish a filesystem that records only the write bit from one that records
+ * nothing — and that difference only shows up on a filesystem a win32 machine cannot produce on
+ * demand. Stating the readings as data is what makes it testable at all.
+ *
+ *   narrow    what `stat` reported after asking for `requested` (0600)
+ *   wide      what it reported after asking for 0666
+ *   readOnly  what it reported after clearing the write bit (0444) — the positive control
+ */
+export function classifyProbeReadings(
+  narrow: number,
+  wide: number,
+  readOnly: number,
+  requested: number = CREDENTIAL_MODE,
+): ModeEnforcement {
+  const n = narrow & PERMISSION_BITS;
+  const w = wide & PERMISSION_BITS;
+  const r = readOnly & PERMISSION_BITS;
+
+  // Full POSIX: what was asked for came back, and asking for something wider changed the answer.
+  if (n === (requested & PERMISSION_BITS) && n !== w) return 'enforced';
+
+  // Privacy is unconfirmable. Before saying so, the instrument must have shown it observes
+  // something — otherwise "unenforced" is indistinguishable from a dead probe.
+  return r !== w ? 'write-bit-only' : 'unobservable';
+}
+
+/**
+ * Classify what a verify-after-write actually found.
+ *
+ * `enforcement` is the measured answer to "what does this filesystem do with a mode at all".
+ */
+export function classifyCredentialMode(
+  observed: number,
+  enforcement: ModeEnforcement,
+  requested: number = CREDENTIAL_MODE,
+): CredentialModeOutcome {
+  const bits = observed & PERMISSION_BITS;
+
+  if (enforcement === 'unobservable') {
+    return {
+      kind: 'unobservable',
+      observed: bits,
+      refusal: refusal(
+        'credential-mode-unobservable',
+        `mode ${toOctal(requested)} was requested and this filesystem reported no observable mode change of any kind — not even clearing the write bit — so nothing at all can be said about the token file's permissions here; this is an inconclusive instrument rather than a finding about privacy`,
+      ),
+    };
+  }
+
+  if (enforcement === 'write-bit-only') {
+    return {
+      kind: 'unenforced',
+      observed: bits,
+      refusal: refusal(
+        'credential-mode-unenforced',
+        `mode ${toOctal(requested)} was requested and this filesystem records only the write bit (it reports ${toOctal(bits)} here, and cannot distinguish owner-only from world-readable), so the token file's privacy cannot be confirmed — it is protected by the gate's credential-path denial and by the OS account, not by this mode. The probe did observe a mode change when the write bit was cleared, so this is a measurement rather than a dead check`,
+      ),
+    };
+  }
+
+  if (isWiderThan(bits, requested)) {
+    return {
+      kind: 'too-wide',
+      observed: bits,
+      refusal: refusal(
+        'credential-mode-too-wide',
+        `the token file was written with mode ${toOctal(bits)} after ${toOctal(requested)} was requested, so it is readable or writable by more than its owner`,
+      ),
+    };
+  }
+
+  return { kind: 'verified', observed: bits };
+}
+
+/** `0o600`, for a message a human reads. */
+export function toOctal(mode: number): string {
+  return `0${(mode & PERMISSION_BITS).toString(8)}`;
+}

package/src/identity/paired-credential.ts

@@ -0,0 +1,89 @@
+/**
+ * The paired-host credential — the durable identity a machine holds after `periscope pair`.
+ *
+ * The shape and its validation live here, not with the filesystem — the same split `store.ts`
+ * states for the token cache, for the same reason: `host/` may import this, and this may never
+ * import `host/`.
+ *
+ * This is not the OIDC token and not the RFC 8628 `device-code` flow, and the noun is chosen to
+ * keep the three apart. A paired credential is an opaque controller-minted bearer
+ * (`p1.<hostId>.<secret>`): it never expires on a clock, never refreshes, and dies only when the
+ * controller revokes it — at which point the upgrade answers 401 and the host's terminal path
+ * names it. That is what makes it survive the idle window after which a provider may let an OIDC
+ * refresh token lapse.
+ *
+ * It carries no user, and cannot. The controller derives the acting user from its own registry
+ * row; a host presenting this credential asserts nothing about who it acts for, which is the whole
+ * design — nothing in this file could smuggle an identity claim even by mistake, because there is
+ * no field to put one in.
+ */
+import type { Authorization, ControllerCredential } from '../control/credential.js';
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import { AUTHORIZATION_HEADER } from './credential.js';
+
+/** The persisted record — what `periscope pair` writes and the daemon reads. */
+export interface PairedCredentialFile {
+  /** The host id the credential names. The daemon announces this id in `link_hello` — the
+   * controller refuses a hello naming anything else, so the file's copy is load-bearing. */
+  readonly hostId: string;
+  /** The full opaque credential, exactly as the controller minted it. */
+  readonly credential: string;
+}
+
+/** The port the pair verb writes through and the daemon reads through — an interface for the same
+ * reason `TokenStore` is one: every malformed-file branch is drivable without a disk. */
+export interface PairedCredentialStore {
+  read(): Result<PairedCredentialFile>;
+  write(file: PairedCredentialFile): Result<unknown>;
+}
+
+/** Validate a parsed file into the shape the daemon relies on. */
+export function readPairedCredentialFile(parsed: unknown): Result<PairedCredentialFile> {
+  if (typeof parsed !== 'object' || parsed === null) {
+    return refuse('credential-cache-unreadable', 'the paired credential file is not a JSON object');
+  }
+  const record = parsed as Record<string, unknown>;
+  const hostId = record['hostId'];
+  const credential = record['credential'];
+
+  if (typeof hostId !== 'string' || hostId === '') {
+    return refuse('credential-cache-unreadable', 'the paired credential file names no hostId');
+  }
+  if (typeof credential !== 'string' || credential === '') {
+    return refuse('credential-cache-unreadable', 'the paired credential file carries no credential');
+  }
+
+  // The credential embeds the host id it speaks for; a file whose two copies disagree would make
+  // this host announce one identity and authenticate as another — the exact mismatch the
+  // controller's hello binding exists to refuse. Caught here, where the fix (re-pair) is printable.
+  if (!credential.startsWith(`p1.${hostId}.`)) {
+    return refuse(
+      'credential-cache-unreadable',
+      'the paired credential does not match the hostId beside it — the file is corrupt; run: periscope pair <code>',
+    );
+  }
+
+  return ok({ hostId, credential });
+}
+
+/**
+ * The `ControllerCredential` a paired host presents — on the link, the decision POST and the bulk
+ * POST alike, through the one spread point in the composition root.
+ *
+ * No refresh, no expiry, no reporter, and each absence is the design: the credential is a stable
+ * secret whose validity lives server-side, so there is exactly one outcome here and nothing to
+ * distinguish. Revocation surfaces as the controller's 401, which the link already classifies as
+ * terminal `link-unauthorized` — this class cannot see it coming and must not pretend to.
+ */
+export class PairedHostCredential implements ControllerCredential {
+  readonly #value: string;
+
+  constructor(file: PairedCredentialFile) {
+    this.#value = `Bearer ${file.credential}`;
+  }
+
+  authorize(): Promise<Result<Authorization>> {
+    return Promise.resolve(ok({ header: AUTHORIZATION_HEADER, value: this.#value }));
+  }
+}

package/src/identity/pkce.ts

@@ -0,0 +1,113 @@
+/**
+ * PKCE (RFC 7636) and the callback's `state` — the two random values that make an authorization-code
+ * exchange safe to run on a machine somebody else is also running code on.
+ *
+ * They defend different things and neither substitutes for the other. This is the sentence worth
+ * reading twice, because "it does PKCE" is routinely taken to mean the whole callback is covered:
+ *
+ *   - The code verifier proves that whoever redeems the authorization code is the same party
+ *     that requested it. It protects the code exchange.
+ *   - The state proves that the callback this host received is the answer to the request this
+ *     host made. It protects the callback itself.
+ *
+ * Why that matters acutely here, rather than as boilerplate. This host's whole premise is that
+ * the agent runs as the same OS user as the host — it is why an 0600 token file is not a boundary
+ * and why the gate has a credential-path denial. That same fact means any local process can
+ * connect to the loopback listener this flow opens. Without `state`, such a process could hand this
+ * host an authorization code of its own obtaining and have the host redeem it and cache the
+ * resulting token. `state` is what makes that a named refusal instead of a silent substitution.
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+
+/**
+ * The only challenge method this host will use.
+ *
+ * RFC 7636 also defines `plain`, where the challenge is the verifier. This host refuses it rather
+ * than merely not offering it — an unused branch is one a later reader restores on a compatibility
+ * report, and `plain` gives away the whole property to anyone who can observe the authorization
+ * request.
+ */
+export const CODE_CHALLENGE_METHOD = 'S256';
+
+/** 32 bytes, which is 43 base64url characters — the RFC's floor is 43 and its ceiling is 128. */
+const ENTROPY_BYTES = 32;
+
+export interface Pkce {
+  readonly verifier: string;
+  readonly challenge: string;
+  readonly method: typeof CODE_CHALLENGE_METHOD;
+}
+
+/**
+ * base64url, per RFC 4648 §5 — no padding, URL-safe alphabet.
+ *
+ * Hand-rolled from base64 rather than reached for by name: `Buffer`'s `base64url` encoding is
+ * equivalent, but the transform is one line and stating it keeps this readable next to the RFC.
+ */
+function base64Url(bytes: Buffer): string {
+  return bytes.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * A cryptographically random, URL-safe string.
+ *
+ * `randomBytes`, never `Math.random`. `Math.random` is seeded, predictable and explicitly not for
+ * this; a predictable verifier or state defeats the property entirely while looking identical in
+ * every test.
+ */
+export function randomUrlSafe(bytes: number = ENTROPY_BYTES): string {
+  return base64Url(randomBytes(bytes));
+}
+
+/** A fresh verifier and its S256 challenge. */
+export function createPkce(): Pkce {
+  const verifier = randomUrlSafe();
+  return { verifier, challenge: challengeFor(verifier), method: CODE_CHALLENGE_METHOD };
+}
+
+/** The S256 challenge for a verifier: base64url(SHA-256(ascii(verifier))). */
+export function challengeFor(verifier: string): string {
+  return base64Url(createHash('sha256').update(verifier, 'ascii').digest());
+}
+
+/**
+ * The `state` value for one authorization request.
+ *
+ * Same entropy source as the verifier and deliberately a separate value — reusing the verifier as
+ * state would put it in a URL the browser and the provider both log, and the verifier is the one
+ * that must never leave this process until the token exchange.
+ */
+export function createState(): string {
+  return randomUrlSafe();
+}
+
+/**
+ * Refuse a challenge method this host will not use.
+ *
+ * Exported so the refusal is reachable and testable, rather than being an `if` nobody can drive.
+ */
+export function requireS256(method: string): Result<typeof CODE_CHALLENGE_METHOD> {
+  if (method !== CODE_CHALLENGE_METHOD) {
+    return refuse(
+      'pkce-method-unsupported',
+      `code challenge method ${method} is refused; this host uses ${CODE_CHALLENGE_METHOD} only, and "plain" would put the verifier itself in the authorization request`,
+    );
+  }
+  return ok(CODE_CHALLENGE_METHOD);
+}
+
+/**
+ * Compare two `state` values without leaking their contents through timing.
+ *
+ * The length check is separate and deliberate: `timingSafeEqual` throws on unequal lengths, so
+ * comparing lengths first is required rather than an optimisation. It leaks the length and nothing
+ * else, which is the standard accepted residual.
+ */
+export function stateMatches(expected: string, received: string): boolean {
+  const a = Buffer.from(expected, 'utf8');
+  const b = Buffer.from(received, 'utf8');
+  return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
+}