viber-channel 0.8.8 → 0.8.9

package/lib/auth.ts

@@ -41,6 +41,11 @@ export interface AuthJson {
  * pull dev behavior into staging. Derived from `VIBER_BASE_URL`, which the
  * launcher always sets per env.
  */
+// #480: this raw `VIBER_BASE_URL` read is DELIBERATE — do not "finish the
+// refactor" by swapping in identityBaseUrl(). This is env CLASSIFICATION, and the
+// `""` default is meaningful: it distinguishes "unset" (⇒ not dev) from a real
+// value, whereas identityBaseUrl() substitutes the production host. It must also
+// never see the API transport host, which carries no "viber-dev" marker.
 export function isDevBackend(
   baseUrl: string = process.env.VIBER_BASE_URL ?? "",
 ): boolean {

package/lib/base_urls.ts

@@ -0,0 +1,250 @@
+/**
+ * base_urls.ts — the TWO base URLs a Viber client deals with (#480).
+ *
+ * Before #480 there was one value, `VIBER_BASE_URL`, playing two incompatible
+ * roles: a network address AND an identity key. #480 points agent REST traffic
+ * at a different host (`viber-api-staging.dgypx.dev`) so it stops going through
+ * the billed Pages Function — which is only safe once the two roles are split.
+ *
+ *   identityBaseUrl  — the LOGICAL backend identity. Feeds the session-file and
+ *                      lock-file hashes (#269), user-facing messages, and the
+ *                      env classification. Must stay stable across the switch.
+ *
+ *   apiBaseUrl       — the host actually contacted over HTTP. May differ from
+ *                      the identity, and may CHANGE at runtime once the server
+ *                      announces `api_base_url`.
+ *                      NOT always normalized: an explicit `VIBER_API_BASE_URL`
+ *                      is, but the FALLBACK returns the identity **verbatim**
+ *                      (normalizing it would break a self-host served under a
+ *                      path prefix, and would make this module's introduction a
+ *                      behaviour change instead of a refactor). So callers must
+ *                      never assume a canonical form — compare ORIGINS, not
+ *                      strings.
+ *
+ * ⚠️ NEVER normalize `identityBaseUrl`.
+ * The session/lock hashes are taken over the RAW string (see `lockFilePath`,
+ * `sessionFilePath`), not over a parsed origin. Trimming a trailing slash or
+ * lower-casing the host would move EVERY hash: live agents would lose their
+ * conversation handles (re-minting a fresh conversation) and release their
+ * locks (re-opening the #311/#293 duplicate window). Normalization belongs to
+ * `apiBaseUrl` alone — hence the two distinct functions below, deliberately not
+ * factored into one.
+ */
+
+/** The canonical public backend, used when nothing is configured. */
+export const DEFAULT_BASE_URL = "https://viber.dgypx.dev";
+
+/**
+ * The logical backend identity — returned VERBATIM, never normalized.
+ *
+ * This is byte-for-byte what the code used before #480
+ * (`process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev"`), so every existing
+ * session-file and lock-file path keeps hashing to the same value.
+ */
+export function identityBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
+  return env.VIBER_BASE_URL ?? DEFAULT_BASE_URL;
+}
+
+/**
+ * Normalize a host meant for HTTP transport: origin only, no trailing slash.
+ *
+ * Applied to `apiBaseUrl` ONLY. Throws on anything that isn't a plain absolute
+ * origin, so a malformed override fails loudly at startup instead of producing
+ * `fetch()` calls against a nonsense address.
+ *
+ * This checks the **form**, and one safety property: `http:` is allowed only on
+ * localhost, mirroring `isTrustedViberOrigin`. Plain-text to an arbitrary host
+ * would expose the bearer tokens the client sends. WHICH hosts are trusted is a
+ * separate decision made by `isTrustedViberOrigin` (step-04) — passing this
+ * function is necessary, never sufficient.
+ */
+export function normalizeApiBaseUrl(raw: string): string {
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    throw new Error(`Invalid API base URL (not an absolute URL): ${raw}`);
+  }
+  const isLocalhost = u.hostname === "localhost" || u.hostname === "127.0.0.1";
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && isLocalhost)) {
+    throw new Error(
+      `Invalid API base URL (must be https, or http on localhost): ${raw}`,
+    );
+  }
+  if (u.username || u.password) {
+    throw new Error(`Invalid API base URL (must not carry credentials): ${raw}`);
+  }
+  if (u.search || u.hash) {
+    throw new Error(`Invalid API base URL (must not carry query or fragment): ${raw}`);
+  }
+  if (u.pathname !== "/" && u.pathname !== "") {
+    throw new Error(`Invalid API base URL (must be an origin, no path): ${raw}`);
+  }
+  return u.origin;
+}
+
+/**
+ * The host to contact over HTTP, at BOOTSTRAP.
+ *
+ * Precedence: `VIBER_API_BASE_URL` (dev / self-host escape hatch) > the identity.
+ * The server-announced value is NOT here — it cannot be: it only arrives with the
+ * first authenticated response. See `ApiBaseUrlResolver`.
+ */
+export function apiBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.VIBER_API_BASE_URL;
+  if (override) return normalizeApiBaseUrl(override);
+  return identityBaseUrl(env);
+}
+
+/** Outcome of offering an announced host to the resolver — for logs and tests. */
+export type AdoptionOutcome =
+  | { adopted: true; value: string }
+  | { adopted: false; reason: string };
+
+/**
+ * The API host as a piece of STATE, not a constant (#480 step-04).
+ *
+ * `api_base_url` is announced by the server, so it is unknown until the first
+ * authenticated response (mint / join / resume) comes back. The first call
+ * therefore ALWAYS goes to the bootstrap host; adoption happens afterwards.
+ * Modelling this as a resolver object rather than a mutable module global keeps
+ * the ownership explicit and makes it testable without touching `process.env`.
+ *
+ * Security rules, deliberately enforced HERE rather than at each call site —
+ * the client sends `project_token`, `instance_token`, `conversation_token` and
+ * (for runners) `runner_token` to whatever host this returns:
+ *
+ *  1. An announced host must pass `isTrustedViberOrigin` BEFORE adoption. That
+ *     allowlist is STATIC — hard-coded hosts plus the LOCAL env overrides. It is
+ *     never fed the announced value: doing so would be circular and the
+ *     allowlist would protect nothing.
+ *  2. A rejected announcement is IGNORED with a warning — never a hard failure.
+ *     The bootstrap host works, so refusing to start would turn a server-side
+ *     misconfiguration into a dead agent (mirror of the server's own choice in
+ *     step-03).
+ *  3. An explicit `VIBER_API_BASE_URL` WINS over any announcement: an operator
+ *     debugging against a specific host must not be silently redirected.
+ */
+export class ApiBaseUrlResolver {
+  private readonly bootstrap: string;
+  private readonly pinnedByEnv: boolean;
+  private adopted: string | null = null;
+
+  constructor(
+    private readonly isTrusted: (origin: string) => boolean,
+    env: NodeJS.ProcessEnv = process.env,
+    private readonly warn: (msg: string) => void = (msg) => process.stderr.write(msg),
+  ) {
+    this.bootstrap = apiBaseUrl(env);
+    this.pinnedByEnv = (env.VIBER_API_BASE_URL ?? "") !== "";
+  }
+
+  /** The host to use right now. */
+  current(): string {
+    return this.adopted ?? this.bootstrap;
+  }
+
+  /**
+   * True once the agent has actually MOVED off its bootstrap host.
+   *
+   * Deliberately not "an announcement was accepted": an announcement equal to the
+   * bootstrap host leaves this false, so the flag can be used as-is to measure
+   * real adoption across the fleet (step-07).
+   */
+  hasAdopted(): boolean {
+    return this.adopted !== null;
+  }
+
+  /**
+   * Offer a server-announced host. Safe to call repeatedly — every response
+   * carries the field, so this runs on a hot-ish path and must be idempotent.
+   */
+  offer(announced: string | undefined | null): AdoptionOutcome {
+    if (announced === undefined || announced === null || announced.trim() === "") {
+      return { adopted: false, reason: "not announced" };
+    }
+    if (this.pinnedByEnv) {
+      return { adopted: false, reason: "pinned by VIBER_API_BASE_URL" };
+    }
+
+    let normalized: string;
+    try {
+      normalized = normalizeApiBaseUrl(announced);
+    } catch (err) {
+      return this.refuse(announced, err instanceof Error ? err.message : String(err));
+    }
+
+    // Rule 1. Note this is the ONLY gate that decides trust; the form check above
+    // is necessary but never sufficient.
+    if (!this.isTrusted(normalized)) {
+      return this.refuse(announced, "origin is not in the static allowlist");
+    }
+
+    // An announcement EQUAL to the host we already use is a no-op, and must not
+    // count as an adoption: step-07 measures the share of the fleet that actually
+    // moved off the web host, and a dev server announcing its own bootstrap host
+    // would otherwise inflate that number with agents that never moved.
+    //
+    // Compare ORIGINS, not strings: the bootstrap value may be un-normalized (see
+    // the module header), so `https://h` vs `https://h/` is the SAME host and a
+    // string comparison would report a spurious move.
+    if (sameOrigin(normalized, this.bootstrap)) {
+      return { adopted: false, reason: "same origin as the bootstrap host" };
+    }
+    // Already on this host: the state is right either way, but re-reporting an
+    // adoption would inflate any COUNT of adoptions — and step-07 counts.
+    if (this.adopted !== null && sameOrigin(normalized, this.adopted)) {
+      return { adopted: false, reason: "already adopted" };
+    }
+
+    this.adopted = normalized;
+    // Logged, not silent: step-06's single-agent test needs an OBSERVABLE proof
+    // that this agent moved. Without this line the discriminant was written but
+    // not executable — `hasAdopted()` existed only in memory and in tests
+    // (found in review). One line per agent per run, at adoption only.
+    this.warn(
+      `[viber-channel] api host adopted: ${normalized} (was ${this.bootstrap}) — #480
+`,
+    );
+    return { adopted: true, value: normalized };
+  }
+
+  private refuse(announced: string, reason: string): AdoptionOutcome {
+    // Rule 2: warn, keep working. Logged once per offer — callers only offer on
+    // a mint/join, not per request.
+    this.warn(
+      `[viber-channel] ignoring announced api_base_url (${reason}): ${announced} — staying on ${this.current()}\n`,
+    );
+    return { adopted: false, reason };
+  }
+}
+
+/**
+ * Make a refused announcement safe to log — mirror of the server's `redactForLog`.
+ *
+ * Keeps the host (so the operator can recognize the offending value) and drops
+ * userinfo. An unparseable value is never echoed: it is not a URL, so it could be
+ * anything, and a length-based cut would still print a short secret in full.
+ */
+export function redactAnnounced(raw: string): string {
+  try {
+    const u = new URL(raw);
+    if (u.username || u.password) {
+      u.username = "";
+      u.password = "";
+      return `${u.toString()} (credentials redacted)`;
+    }
+    return u.toString();
+  } catch {
+    return `<unparseable, ${raw.length} chars>`;
+  }
+}
+
+/** True if both strings denote the same origin. Tolerates un-normalized input. */
+export function sameOrigin(a: string, b: string): boolean {
+  try {
+    return new URL(a).origin === new URL(b).origin;
+  } catch {
+    return false;
+  }
+}