@naswerks/periscope 1.0.0 → 1.0.1

package/src/bin/login.ts

@@ -0,0 +1,149 @@
+/**
+ * `periscope login` — acquire a token interactively and write it to the cache the daemon reads.
+ *
+ * Why this is a command rather than something the daemon does: `bin/serve.ts` presents a
+ * token that is already there; there is no interactive flow in the shipped daemon, deliberately,
+ * because a host meant to run unattended must not block on a browser at start-up. So the
+ * interactive half is a separate act, run once by a person, and the daemon is unchanged by this
+ * file existing.
+ *
+ * It writes the same cache the daemon reads, derived from the same call. `tokenCachePath(env)` is
+ * the one source for the location, and `credentialPaths(env)`, which the gate uses to build its
+ * protected set, derives from it too. Nothing here may compute a path of its own, or the thing the
+ * gate refuses to let an agent read and the thing this writes could drift apart.
+ *
+ * The flow is derived from config, never chosen here. `protocolFor(config)` picks loopback or
+ * device-code, and the daemon's credential calls the same function to decide what it expects, so a
+ * cache written under one protocol can never be read under the other. (`TokenCredential` discards a
+ * cache whose protocol does not match, so getting this wrong would look like "signing in did
+ * nothing".) Setting `PERISCOPE_IDENTITY_DEVICE_CODE=1` moves both ends together, which is the
+ * property that makes it safe to expose as one environment variable.
+ */
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import type { CachedTokens, TokenStore } from '../identity/index.js';
+import { isAuthFlowBlocked, readIdentityConfig } from '../identity/index.js';
+import type { DeviceCodeInstruction } from '../host/index.js';
+import {
+  FilePairedCredential,
+  FileTokenCache,
+  pairedCredentialPath,
+  protocolFor,
+  signIn,
+  signInWithDeviceCode,
+  tokenCachePath,
+} from '../host/index.js';
+
+/** The edges, injected so the whole command is testable without a browser, a socket or a clock. */
+export interface LoginDeps {
+  /** Where operator-facing instructions go. Defaults to stdout. */
+  readonly write?: (line: string) => void;
+  /** Replaced in tests; the real ones talk to the provider. */
+  readonly signIn?: typeof signIn;
+  readonly signInWithDeviceCode?: typeof signInWithDeviceCode;
+  /** Replaced in tests so nothing touches the real cache path. Defaults to the file cache at `path`. */
+  readonly store?: (path: string) => TokenStore;
+  /**
+   * Whether a paired credential is present at `path`. Replaced in tests. The daemon prefers a
+   * paired credential over the token this verb writes, so a signed-in operator on a paired box is
+   * told the token will not be the one presented.
+   */
+  readonly pairedCredentialPresent?: (path: string) => boolean;
+}
+
+/**
+ * Run the login command.
+ *
+ * Returns a `Result` rather than exiting, so the caller owns the process and this stays callable
+ * from a test. Every failure is a named refusal, the same posture the rest of the package holds.
+ */
+export async function runLogin(env: NodeJS.ProcessEnv, deps: LoginDeps = {}): Promise<Result<CachedTokens>> {
+  const write = deps.write ?? ((line: string) => process.stdout.write(`${line}\n`));
+  // Said once, on success: the daemon prefers a paired credential over the token this verb writes,
+  // so an operator signing in on a paired box is told the token will not be the one presented.
+  const pairedPath = pairedCredentialPath(env);
+  const pairedPresent =
+    deps.pairedCredentialPresent ?? ((path: string) => new FilePairedCredential(path).read().ok);
+  const pairedNotice =
+    pairedPath !== null && pairedPresent(pairedPath)
+      ? `note: this machine holds a paired credential at ${pairedPath}, and the daemon presents that on ` +
+        'every dial in preference to this token'
+      : null;
+
+  // The config module's own read and its own refusal, restated nowhere.
+  //
+  // Two reasons, and the second is enforced. (1) "Configured" must mean the identical thing here and
+  // in the daemon; an operator who can sign in but whose host then refuses to start is the worst
+  // outcome available. (2) `pins/identity-generic.test.ts` asserts that exactly one shipped file
+  // names the authority environment variable, because a second mention is a second answer to "which
+  // provider is this host talking to". Naming those variables here, even in a comment or a message
+  // string, since the pin reads source text, trips it, and it is right to: the fix is to carry the
+  // one refusal that already exists rather than write a second copy that can drift.
+  //
+  // Not a default, a refusal. There is no fallback issuer and no implicit tenant: signing in
+  // "somewhere" would mint a token this controller cannot validate, and the failure would surface
+  // much later as a 401 on the upgrade with nothing naming the cause.
+  const read = readIdentityConfig(env);
+  if (!read.ok) return refuse(read.refusal.reason, read.refusal.detail);
+
+  const config = read.value;
+
+  const cachePath = tokenCachePath(env);
+  if (cachePath === null) {
+    return refuse(
+      'identity-config-invalid',
+      'identity is configured but there is nowhere to keep the token cache — set PERISCOPE_CONFIG_DIR',
+    );
+  }
+
+  const store = (deps.store ?? ((path: string) => new FileTokenCache(path)))(cachePath);
+  const protocol = protocolFor(config);
+
+  if (protocol === 'device-code') {
+    // The headless flow, and it must stay reachable without a redirect port. This is the flow for
+    // a box with no browser, such as a server or a container. It takes no listener and binds
+    // nothing.
+    const run = deps.signInWithDeviceCode ?? signInWithDeviceCode;
+    const result = await run(config, store, (instruction: DeviceCodeInstruction) => {
+      write(`open ${instruction.verificationUri} and enter the code: ${instruction.userCode}`);
+    });
+    return finish(result, cachePath, write, pairedNotice);
+  }
+
+  // Loopback + PKCE: the primary flow. `signIn` binds an ephemeral port and closes it on every path;
+  // its default `present` prints the URL, which is what works over SSH.
+  const run = deps.signIn ?? signIn;
+  const result = await run(config, store, {
+    present: (url: string) => write(`open this to sign in:\n${url}`),
+  });
+  return finish(result, cachePath, write, pairedNotice);
+}
+
+/**
+ * Report the outcome once, in the operator's words.
+ *
+ * A policy-blocked flow is surfaced with its do-not-retry rule attached. A provider policy blocking
+ * the device-code flow refuses identically every time, so an operator who reads a bare failure will
+ * re-run it, and the second attempt costs the same and fails the same way.
+ */
+function finish(
+  result: Result<CachedTokens>,
+  cachePath: string,
+  write: (line: string) => void,
+  pairedNotice: string | null,
+): Result<CachedTokens> {
+  if (!result.ok) {
+    write(`sign-in failed: ${result.refusal.reason} — ${result.refusal.detail}`);
+    if (isAuthFlowBlocked(result.refusal.detail)) {
+      write(
+        'do not re-run the device code flow: the same policy will block it, every time. ' +
+          'Use the loopback flow (unset PERISCOPE_IDENTITY_DEVICE_CODE) or have the policy changed.',
+      );
+    }
+    return result;
+  }
+
+  write(`signed in; token cache written to ${cachePath}`);
+  if (pairedNotice !== null) write(pairedNotice);
+  return ok(result.value);
+}

package/src/bin/main.ts

@@ -0,0 +1,204 @@
+/**
+ * The composition root, and the only place this package reads the environment.
+ *
+ * Everything below takes its configuration as arguments. That is what makes the rest of the
+ * package testable without a process, and it is why "where does this value come from?" has one
+ * answer instead of one per module. `main` itself takes the environment and the process edges as
+ * arguments for the same reason; `bin/periscope.ts` is the one line that hands it the real ones.
+ */
+import { readConfigFile, withConfigFallback } from '../host/config-file.js';
+import { packageVersion } from '../host/package-facts.js';
+import { USAGE, readCommand } from './command.js';
+import { runConfig } from './config.js';
+import { runLogin } from './login.js';
+import { runPair } from './pair.js';
+import type { ServeOutcome, ServeViews } from './serve.js';
+import { runServe } from './serve.js';
+import { runStatus } from './status.js';
+
+/** The process edges. `processIo()` is the real set; a test supplies recording ones. */
+export interface Io {
+  /** One stdout line, without its newline. */
+  readonly stdout: (line: string) => void;
+  /** One stderr line, without its newline. */
+  readonly stderr: (line: string) => void;
+  readonly setExitCode: (code: number) => void;
+  /** The verbs, replaceable so the dispatch is testable without a provider, a controller or a host. */
+  readonly runLogin?: typeof runLogin;
+  readonly runPair?: typeof runPair;
+  readonly runConfig?: typeof runConfig;
+  readonly serve?: (views: ServeViews) => ServeOutcome;
+  readonly runStatus?: typeof runStatus;
+  /** The package version, replaceable so the dispatch test does not read the manifest. */
+  readonly version?: () => string;
+}
+
+/** The real process edges: stdout, stderr and the exit code. The verbs take their defaults. */
+export function processIo(): Io {
+  return {
+    stdout: (line) => {
+      process.stdout.write(`${line}\n`);
+    },
+    stderr: (line) => {
+      process.stderr.write(`${line}\n`);
+    },
+    setExitCode: (code) => {
+      process.exitCode = code;
+    },
+  };
+}
+
+/**
+ * The config file fills absences, and only absences, for every verb that consumes configuration
+ * (`serve`, `login`, `pair`), which is what makes USAGE's unconditional env-first-then-file
+ * sentence true. The merged view is consulted for the closed key set only, so a deployment that
+ * sets env vars is configured by them alone, and nothing outside that set (identity configuration,
+ * the config dir itself) can arrive from a file. A file that exists and cannot be used is fatal
+ * rather than silently empty: a corrupt file must not impersonate a deliberate absence (the paired
+ * credential takes the same posture, for the same reason).
+ *
+ * `pair` belongs on that list: `PERISCOPE_DECISION_URL` is a legal config key and is exactly what
+ * `redemptionUrl` derives the redemption door from, so a config-file-only machine handed raw env
+ * would answer "nowhere to redeem the code" at the first step of the very flow the config verb was
+ * built for. `login` reads no config key today; it rides the merged view so the help text's claim
+ * is true by wiring rather than by coincidence.
+ */
+function environmentWithConfigFile(raw: NodeJS.ProcessEnv): NodeJS.ProcessEnv | string {
+  const fileConfig = readConfigFile(raw);
+  if (fileConfig.problem !== null) return fileConfig.problem;
+  return withConfigFallback(raw, fileConfig.values);
+}
+
+/** `error` as one line, for a verb that threw instead of returning. */
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * The command dispatch.
+ *
+ * `serve` runs synchronously, which is the path every supervisor takes. `login` and `pair` are the
+ * asynchronous verbs; each returns its own promise so a caller can await the outcome, and nothing
+ * about the daemon's start-up ordering depends on them. `raw` is the process environment as
+ * received; the merged view, where the config file fills absences, is derived per verb.
+ */
+export function main(argv: readonly string[], raw: NodeJS.ProcessEnv, io: Io): Promise<void> | void {
+  const command = readCommand(argv);
+
+  if (command.kind === 'help') {
+    io.stdout(USAGE);
+    return;
+  }
+
+  if (command.kind === 'version') {
+    io.stdout((io.version ?? packageVersion)());
+    return;
+  }
+
+  if (command.kind === 'unknown') {
+    // Named rather than defaulted to `serve` (see `readCommand`): a typo that silently starts a host
+    // is discovered much later, as an empty token cache.
+    io.stderr(`periscope: unknown command '${command.name}'\n\n${USAGE}`);
+    io.setExitCode(1);
+    return;
+  }
+
+  if (command.kind === 'login') {
+    const env = environmentWithConfigFile(raw);
+    if (typeof env === 'string') {
+      io.stderr(`periscope: ${env}`);
+      io.setExitCode(1);
+      return;
+    }
+    // The interactive half is a separate act by design; the daemon never signs anyone in.
+    return (io.runLogin ?? runLogin)(env).then(
+      (result) => {
+        if (!result.ok) {
+          io.stderr(`periscope: login failed - ${result.refusal.reason} - ${result.refusal.detail}`);
+          io.setExitCode(1);
+        }
+      },
+      // `runLogin` returns refusals rather than throwing, so this branch is for the failure it did
+      // not model. Without it a throw here would be an unhandled rejection followed by exit 0: a
+      // sign-in that crashed reporting success to whoever scripted it.
+      (error: unknown) => {
+        io.stderr(`periscope: login failed - ${describe(error)}`);
+        io.setExitCode(1);
+      },
+    );
+  }
+
+  if (command.kind === 'status') {
+    const outcome = (io.runStatus ?? runStatus)({ raw, merged: environmentWithConfigFile(raw) });
+    const sink = outcome.ok ? io.stdout : io.stderr;
+    for (const line of outcome.lines) sink(outcome.ok ? line : `periscope: ${line}`);
+    if (!outcome.ok) io.setExitCode(1);
+    return;
+  }
+  if (command.kind === 'config') {
+    // Synchronous by nature: one file read or one file write, no network, no process.
+    //
+    // Raw env, deliberately. This is the one verb that must never see the merged view, twice over:
+    // its "currently overridden by the environment" marker exists to distinguish env from file,
+    // and a merged env would mark every file value as overridden by itself; and this verb is the
+    // escape hatch that makes fatal-on-corrupt safe everywhere else. A corrupt file must still
+    // leave `periscope config` able to say which file is broken and why, rather than refusing
+    // before the verb runs.
+    const outcome = (io.runConfig ?? runConfig)(command.key, command.value, raw, command.unset);
+    const sink = outcome.ok ? io.stdout : io.stderr;
+    for (const line of outcome.lines) sink(line);
+    if (!outcome.ok) io.setExitCode(1);
+    return;
+  }
+
+  if (command.kind === 'pair') {
+    if (command.problem !== null) {
+      io.stderr(
+        `periscope: ${command.problem} - usage: periscope pair <code> [--controller <origin>] [--label <name>]`,
+      );
+      io.setExitCode(1);
+      return;
+    }
+    const env = environmentWithConfigFile(raw);
+    if (typeof env === 'string') {
+      io.stderr(`periscope: ${env}`);
+      io.setExitCode(1);
+      return;
+    }
+    // The same shape as `login`, for the same reasons, including the rejection branch, because a
+    // pairing that crashed must not report success to whoever scripted it.
+    return (io.runPair ?? runPair)(command.code, env, undefined, {
+      controller: command.controller,
+      label: command.label,
+    }).then(
+      (result) => {
+        if (!result.ok) {
+          io.stderr(`periscope: pair failed - ${result.detail}`);
+          io.setExitCode(1);
+        }
+      },
+      (error: unknown) => {
+        io.stderr(`periscope: pair failed - ${describe(error)}`);
+        io.setExitCode(1);
+      },
+    );
+  }
+
+  // The daemon reads two views: configuration from the merged one, credentials and the session
+  // environment from the raw one. `runServe` says which reads which, and reports its own refusals.
+  const serve = io.serve ?? ((views: ServeViews) => runServe(views, processServeDeps(io)));
+  serve({ raw, merged: environmentWithConfigFile(raw) });
+}
+
+/** The daemon's edges over a caller-supplied `io`, with the process itself behind exit and signals. */
+function processServeDeps(io: Io): Parameters<typeof runServe>[1] {
+  return {
+    log: io.stdout,
+    stderr: io.stderr,
+    setExitCode: io.setExitCode,
+    exit: (code) => process.exit(code),
+    onSignal: (signal, handler) => {
+      process.on(signal, handler);
+    },
+  };
+}

package/src/bin/pair.ts

@@ -0,0 +1,246 @@
+/**
+ * `periscope pair <code> [--controller <origin>] [--label <name>]` — trade a short-lived pair code
+ * for this machine's durable credential, and learn where the controller is from its answer.
+ *
+ * Why this is a command rather than something the daemon does: the same reason `login` is. The
+ * code is single-use and expires in minutes (it is a deliberate act a person performs once) and
+ * the daemon must never block on anything interactive. After this succeeds, the daemon reads the
+ * written file forever; after the controller revokes it, the daemon's next dial dies loudly and
+ * the fix is to run this again with a fresh code.
+ *
+ * It writes the same protected directory the daemon reads, derived from the same call:
+ * `pairedCredentialPath(env)`, beside the token cache, inside the gate's protected set. Nothing
+ * here computes a path of its own.
+ *
+ * Where the redemption door is: `--controller`'s origin when given; else `PERISCOPE_PAIR_URL` when
+ * set; otherwise derived from `PERISCOPE_DECISION_URL`'s origin (the one controller URL every
+ * configured host already has) plus the controller's published redemption route. The derivation is
+ * stated here once so a controller that moves the route has one line to argue with.
+ *
+ * What the controller answers with, beyond the credential: the URLs this host should dial
+ * (`controllerUrl`, `decisionUrl`). The controller names its own routes; this command hardcodes only
+ * the pair route above. When both arrive they are written to the config file beside the credential,
+ * so a machine paired with one command needs nothing else before `serve`. The environment still
+ * wins per key, and the write says so when it is shadowed.
+ */
+import { certificateRemedy, describeFailure, isCertificateRefusal } from '../core/failure.js';
+import { writeConfigEntries } from '../host/config-file.js';
+import { readMachineFacts } from '../host/machine.js';
+import { pairedCredentialPath } from '../host/paths.js';
+import { FilePairedCredential } from '../host/paired-credential-store.js';
+import type { PairedCredentialStore } from '../identity/paired-credential.js';
+
+const REDEMPTION_ROUTE = '/api/periscope/pair';
+
+/** The two flags: null means "not given", and the environment path applies. */
+export interface PairAsk {
+  readonly controller?: string | null;
+  readonly label?: string | null;
+}
+
+/** The verb's outcome: plain, CLI-local, and deliberately not the wire's refusal vocabulary.
+ * Nothing here crosses the link, so nothing here may widen it. */
+export type PairOutcome =
+  | { readonly ok: true; readonly hostId: string; readonly path: string }
+  | { readonly ok: false; readonly detail: string };
+
+/** The edges, injected so the whole verb is testable without a controller or a disk. */
+export interface PairDeps {
+  /** Where operator-facing lines go. Defaults to stdout. */
+  readonly write?: (line: string) => void;
+  /** The HTTP edge. Defaults to global fetch. */
+  readonly transport?: typeof fetch;
+  /** Replaced in tests so nothing touches the real credential path. */
+  readonly store?: (path: string) => PairedCredentialStore;
+}
+
+/** Run the pair command. Returns rather than exits, so the caller owns the process. */
+export async function runPair(
+  code: string | null,
+  env: NodeJS.ProcessEnv,
+  deps: PairDeps = {},
+  asked: PairAsk = {},
+): Promise<PairOutcome> {
+  const write = deps.write ?? ((line: string) => process.stdout.write(`${line}\n`));
+
+  if (code === null) {
+    return {
+      ok: false,
+      detail: 'no code given - usage: periscope pair <code> [--controller <origin>] [--label <name>]',
+    };
+  }
+
+  const url = redemptionUrl(env, asked.controller ?? null);
+  if (url === null) {
+    return {
+      ok: false,
+      detail:
+        asked.controller === undefined || asked.controller === null
+          ? 'nowhere to redeem the code - pass --controller <origin>, or set PERISCOPE_PAIR_URL or PERISCOPE_DECISION_URL (whose origin names the controller)'
+          : `--controller '${asked.controller}' is not an http(s) URL`,
+    };
+  }
+
+  const path = pairedCredentialPath(env);
+  if (path === null) {
+    return {
+      ok: false,
+      detail:
+        'nowhere to keep the credential - set PERISCOPE_CONFIG_DIR or run as a user with a home directory',
+    };
+  }
+
+  // The label the operator will recognize this machine by in every listing. Overridable because a
+  // hostname like `DESKTOP-4F7Q2` recognizes nobody.
+  const machineLabel = asked.label ?? env['PERISCOPE_MACHINE_LABEL'] ?? readMachineFacts().hostname;
+
+  const transport = deps.transport ?? fetch;
+  let response: Response;
+  try {
+    response = await transport(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ code, machineLabel }),
+    });
+  } catch (error) {
+    // The cause, not the wrapper: `fetch failed` over a refused certificate is not "unreachable", and
+    // a reader told the controller is down will not look at the certificate.
+    const why = describeFailure(error);
+    return {
+      ok: false,
+      detail: isCertificateRefusal(error)
+        ? `the controller at ${url} presented a certificate Node refused (${why}). ${certificateRemedy('the controller')}`
+        : `the controller at ${url} could not be reached - ${why}`,
+    };
+  }
+
+  if (response.status === 404 || response.status === 405) {
+    // Nothing at this route is a wrong door, not a refused code: the origin is not a controller,
+    // or its pair route is elsewhere. Saying "mint a fresh code" here sends the reader to the
+    // wrong fix.
+    return {
+      ok: false,
+      detail:
+        `nothing answers the pair route at ${url} (HTTP ${response.status}). Check --controller (an ` +
+        'http(s) origin) or PERISCOPE_PAIR_URL; a controller redeems codes at its own pair route.',
+    };
+  }
+  if (!response.ok) {
+    // The door's one refusal is deliberate (unknown, expired and consumed answer identically);
+    // the honest instruction is therefore always the same: mint a fresh code.
+    const body = await response.text().catch(() => '');
+    return {
+      ok: false,
+      detail:
+        `the controller refused this code (HTTP ${response.status}${body === '' ? '' : ` - ${body}`}). ` +
+        'Codes are single-use and expire in minutes; mint a fresh one and try again.',
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = await response.json();
+  } catch {
+    return {
+      ok: false,
+      detail: 'the controller answered success with an unreadable body - nothing was written',
+    };
+  }
+
+  const record = (typeof parsed === 'object' && parsed !== null ? parsed : {}) as Record<string, unknown>;
+  const hostId = record['hostId'];
+  const credential = record['hostCredential'];
+  if (typeof hostId !== 'string' || hostId === '' || typeof credential !== 'string' || credential === '') {
+    return {
+      ok: false,
+      detail: 'the controller answered success without a credential - nothing was written',
+    };
+  }
+  // The shape is the contract: `serve` reads the host id out of the credential and refuses a file
+  // whose two copies disagree, so a credential that would be refused at the next start is refused
+  // here, where the fix (the controller's answer) is nameable.
+  if (!credential.startsWith(`p1.${hostId}.`) || credential.length <= `p1.${hostId}.`.length) {
+    return {
+      ok: false,
+      detail:
+        `the controller answered a credential that does not have the shape p1.<hostId>.<secret> for ` +
+        `host ${hostId} - nothing was written. A paired credential embeds the host id it speaks for.`,
+    };
+  }
+
+  const store = (deps.store ?? ((p: string) => new FilePairedCredential(p)))(path);
+  const written = store.write({ hostId, credential });
+  if (!written.ok) {
+    return { ok: false, detail: `${written.refusal.reason} - ${written.refusal.detail}` };
+  }
+
+  write(`paired as ${hostId}; credential written to ${path}`);
+  write('this host now dials with the paired credential - the sign-in token expiry no longer applies to it');
+
+  // The controller names where this host should dial. Written after the credential, never instead
+  // of it: the credential is the scarce thing, and a config write that fails is reported, not a
+  // reason to lose what was just minted.
+  const controllerUrl = record['controllerUrl'];
+  const decisionUrl = record['decisionUrl'];
+  if (
+    typeof controllerUrl === 'string' &&
+    controllerUrl !== '' &&
+    typeof decisionUrl === 'string' &&
+    decisionUrl !== ''
+  ) {
+    const problem = writeConfigEntries(env, [
+      { key: 'PERISCOPE_CONTROLLER_URL', value: controllerUrl },
+      { key: 'PERISCOPE_DECISION_URL', value: decisionUrl },
+    ]);
+    if (problem !== null) {
+      write(`the controller's addresses were not written to the config file - ${problem}`);
+    } else {
+      write(
+        `PERISCOPE_CONTROLLER_URL and PERISCOPE_DECISION_URL written to the config file - serve needs nothing else`,
+      );
+      for (const key of ['PERISCOPE_CONTROLLER_URL', 'PERISCOPE_DECISION_URL'] as const) {
+        const fromEnv = env[key];
+        if (fromEnv !== undefined && fromEnv !== '') {
+          write(
+            `note: ${key} is set in the environment, and the environment wins - the file value is a fallback`,
+          );
+        }
+      }
+    }
+  } else {
+    write(
+      'the controller did not name its link and decision URLs - set PERISCOPE_CONTROLLER_URL and PERISCOPE_DECISION_URL before serve',
+    );
+  }
+  return { ok: true, hostId, path };
+}
+
+/**
+ * The redemption door's address. `PERISCOPE_PAIR_URL` verbatim when set; otherwise the decision
+ * URL's origin + the controller's published route. The decision URL is required configuration for
+ * every serving host, so a machine being paired on the box it will serve from has nothing extra to
+ * set.
+ */
+function redemptionUrl(env: NodeJS.ProcessEnv, controller: string | null): string | null {
+  if (controller !== null) {
+    try {
+      const parsed = new URL(controller);
+      if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+      return `${parsed.origin}${REDEMPTION_ROUTE}`;
+    } catch {
+      return null;
+    }
+  }
+
+  const explicit = env['PERISCOPE_PAIR_URL'];
+  if (explicit !== undefined && explicit !== '') return explicit;
+
+  const decision = env['PERISCOPE_DECISION_URL'];
+  if (decision === undefined || decision === '') return null;
+
+  try {
+    return `${new URL(decision).origin}${REDEMPTION_ROUTE}`;
+  } catch {
+    return null;
+  }
+}

package/src/bin/periscope.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main, processIo } from './main.js';
+void main(process.argv.slice(2), process.env, processIo());