@naswerks/periscope 1.0.0 → 1.0.1

package/src/identity/authorize.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 { ok, refuse } from '../core/result.js';
+import type { IdentityConfig } from './config.js';
+import type { Pkce } from './pkce.js';
+import { stateMatches } 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 function redirectUriFor(port: number): string {
+  // 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: IdentityConfig,
+  authorizationEndpoint: string,
+  pkce: Pkce,
+  state: string,
+  redirectUri: string,
+): AuthorizationRequest {
+  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 };
+}
+
+/** 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 function readAuthorizationCallback(
+  rawQuery: string,
+  expectedState: string,
+): Result<AuthorizationCallback> {
+  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('');

package/src/identity/config.ts

@@ -0,0 +1,227 @@
+/**
+ * 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';
+import { ok, refuse } 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 const DEFAULT_SCOPES: readonly string[] = ['openid', 'profile', 'offline_access'];
+
+const REQUIRED = 'PERISCOPE_IDENTITY_AUTHORITY and PERISCOPE_IDENTITY_CLIENT_ID';
+
+function trimmed(env: NodeJS.ProcessEnv, key: string): string | null {
+  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: string): string | null {
+  let parsed: URL;
+  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: NodeJS.ProcessEnv): Result<IdentityEndpoints | null> {
+  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: NodeJS.ProcessEnv): Result<number> {
+  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: NodeJS.ProcessEnv): Result<IdentityConfig> {
+  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',
+  });
+}
+
+/**
+ * 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 function identityPosture(env: NodeJS.ProcessEnv): IdentityPosture {
+  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: string): string {
+  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: unknown): Result<IdentityEndpoints> {
+  if (typeof body !== 'object' || body === null) {
+    return refuse('identity-config-invalid', 'the discovery document is not a JSON object');
+  }
+  const record = body as Record<string, unknown>;
+  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,
+  });
+}

package/src/identity/credential.ts

@@ -0,0 +1,176 @@
+/**
+ * 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 { ok, refuse } from '../core/result.js';
+import type { IdentityConfig } from './config.js';
+import type { AuthProtocol } from './device-code.js';
+import { discardOnProtocolMismatch } from './device-code.js';
+import type { CachedTokens, TokenStore } from './store.js';
+import type { TokenSet } from './token.js';
+import { authorizationValue, isFresh } 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 const AUTHORIZATION_HEADER = 'Authorization';
+
+export class TokenCredential implements ControllerCredential {
+  readonly #options: TokenCredentialOptions;
+
+  constructor(options: TokenCredentialOptions) {
+    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(): Promise<Result<Authorization>> {
+    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(): Promise<Result<{ authorization: Authorization; via: 'cache-hit' | 'refreshed' }>> {
+    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: TokenSet = {
+      ...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: TokenSet): Authorization {
+  return { header: AUTHORIZATION_HEADER, value: authorizationValue(tokens) };
+}