@brass-build/cli 0.1.0 → 0.3.0

package/src/commands.ts

@@ -109,7 +109,7 @@ export async function publish(ctx: CommandContext, opts: PublishOptions): Promis
   if (opts.visibility !== undefined) {
     await ensureVisibility(ctx, appId, opts.visibility, resolved.detail?.visibility);
   }
-  const hosting = await ensureHosting(ctx, appId, opts.slug);
+  const hosting = await ensureHosting(ctx, appId, opts.slug, opts.requireAccess);
   if (opts.requireAccess !== undefined) {
     await ensureGate(ctx, appId, opts.requireAccess, hosting);
   }
@@ -126,7 +126,12 @@ export async function publish(ctx: CommandContext, opts: PublishOptions): Promis
   // of a couple of reads instead of an upload and a poll loop.
   const unchanged = await activeVersionMatches(ctx, appId, hash);
   if (unchanged !== null) {
-    const status = await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`);
+    const status = await awaitGateSettled(
+      ctx,
+      appId,
+      await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`),
+      opts.sleep ?? realSleep,
+    );
     ctx.log.success(`Already up to date${status.url ? `: ${status.url}` : ''}`);
     // Refreshed here too, so publishing twice says the same thing both times.
     // A publisher acting on a warning re-runs publish to check, and a signal
@@ -164,7 +169,12 @@ export async function publish(ctx: CommandContext, opts: PublishOptions): Promis
   // schema missing `family`) right here instead of silently later.
   const warnings = await refreshCapabilities(ctx, appId);
 
-  const status = await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`);
+  const status = await awaitGateSettled(
+    ctx,
+    appId,
+    await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`),
+    opts.sleep ?? realSleep,
+  );
   if (status.url) ctx.log.success(`Deployed: ${status.url}`);
   return { app_id: appId, version_id: version.version_id, url: status.url, warnings };
 }
@@ -223,14 +233,13 @@ async function ensureVisibility(
 }
 
 // Converge the hosted load gate to `want` (`true` = gated to the audience,
-// `false` = world-loadable). Always PATCH, even when the DDB flag already
-// reads `want`: the PATCH is what reaches the server-side reconcile that
-// repairs a wedged edge marker (a prior toggle whose flag write landed but
-// whose marker write lost every ETag race leaves the flag reading correct
-// while the marker disagrees). Skipping the PATCH on a matching flag would
-// leave such a gate wedged forever, since every later publish would skip it
-// too. `status` is the state `ensureHosting` just observed, used only to word
-// the log line. (`require_access` absent === off.)
+// `false` = world-loadable). Always PATCH, even when the reported state
+// already reads `want`: the PATCH is what asks the platform to re-settle a
+// gate whose reported and served states have drifted apart, which reading the
+// reported one alone cannot detect. Skipping it on a match would leave such an
+// app stuck, since every later publish would skip it too. `status` is the
+// state `ensureHosting` just observed, used only to word the log line.
+// (`require_access` absent === off.)
 async function ensureGate(
   ctx: CommandContext,
   appId: string,
@@ -250,15 +259,22 @@ async function ensureGate(
   }
 }
 
+// Enable hosting when the app is not hosted yet, at the load-gate state the
+// publish wants. Stating the gate here rather than leaving it to the PATCH
+// below settles it in one step: a new slot is gated by default, so a publish
+// that wants a world-loadable one would otherwise turn the gate on and
+// straight back off, doing twice the work to reach one state.
 async function ensureHosting(
   ctx: CommandContext,
   appId: string,
   slug?: string,
+  requireAccess?: boolean,
 ): Promise<HostingStatus> {
   const status = await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`);
   if (status.enabled) return status;
-  const body: { slug?: string } = {};
+  const body: { slug?: string; require_access?: boolean } = {};
   if (slug !== undefined) body.slug = slug;
+  if (requireAccess !== undefined) body.require_access = requireAccess;
   const enabled = await ctx.api.post<HostingStatus>(
     `/apps/${encodeURIComponent(appId)}/hosting`,
     body,
@@ -267,11 +283,42 @@ async function ensureHosting(
   return enabled;
 }
 
-// The currently-served version when it is `ready` and already carries
-// `hash`, else null. A null (no active version, a non-ready active version, or
-// a hash mismatch) means `publish` must upload. A first deploy has no active
-// version, so it always uploads; a version predating content hashing has no
-// recorded hash and so never matches, forcing one re-upload that self-heals.
+// A published bundle is not reachable until the platform has registered the
+// slot to serve it, and that registration can lag or fail on its own. Reading
+// the status is what asks the platform to settle it, so a slot that is not
+// ready yet is re-read a few times before publish gives up. Publishing
+// reports success only once the slot will actually serve, so an unreachable
+// one is a failed publish rather than a URL that answers 404.
+const GATE_SETTLE_ATTEMPTS = 3;
+const GATE_SETTLE_GAP_MS = 2000;
+
+async function awaitGateSettled(
+  ctx: CommandContext,
+  appId: string,
+  status: HostingStatus,
+  sleep: (ms: number) => Promise<void>,
+): Promise<HostingStatus> {
+  // An api that does not report the field tells us nothing to act on.
+  if (status.gate_settled !== false) return status;
+  for (let attempt = 1; attempt < GATE_SETTLE_ATTEMPTS; attempt++) {
+    await sleep(GATE_SETTLE_GAP_MS);
+    const latest = await ctx.api.get<HostingStatus>(`/apps/${encodeURIComponent(appId)}/hosting`);
+    if (latest.gate_settled !== false) return latest;
+  }
+  // Says what is true of the SLOT, because both publish paths end here: the
+  // one that uploaded a new bundle and the one that found the app already
+  // serving this exact bundle and skipped the upload. A message naming an
+  // upload sends the second caller looking for one that never happened.
+  throw new Error(
+    'The hosted slot never registered, so it will not serve. ' +
+      'Run publish again to retry.',
+  );
+}
+
+// The currently-served version when it is `ready` and already carries `hash`,
+// else null. A null (no active version, a non-ready active version, or a hash
+// mismatch) means `publish` must upload. A first deploy has no active version,
+// so it always uploads.
 async function activeVersionMatches(
   ctx: CommandContext,
   appId: string,
@@ -287,8 +334,8 @@ async function activeVersionMatches(
 
 // Poll until the version reaches a KNOWN terminal state (`ready` / `failed`),
 // then return it; time out otherwise. Deliberately loops while the status is
-// anything other than a known terminal — `pending` OR any status this pinned
-// CLI does not recognize — rather than returning on `!== 'pending'`. That way
+// anything other than a known terminal (`pending`, or any status this pinned
+// CLI does not recognize) rather than returning on `!== 'pending'`. That way
 // a future server status (a finer-grained non-terminal like `unpacking`, or a
 // new terminal-failure like `rejected`) is not mistaken for "done": an
 // unrecognized non-terminal keeps polling, and an unrecognized terminal

package/src/config.ts

@@ -53,7 +53,11 @@ export type Profile = string;
 // `BRASS_SERVICE_TOKEN`.
 export interface StoredCredential {
   token?: string;
-  session?: { sid: string };
+  // `authBaseUrl` is the auth origin the session was minted on, so a later
+  // `brass logout` revokes it there even when the invocation's own flags
+  // point elsewhere. Optional: a file an older CLI wrote carries only the
+  // sid, and the logout falls back to the invocation's auth origin.
+  session?: { sid: string; authBaseUrl?: string };
 }
 export interface CredentialsFile {
   version: 1;

package/src/login.ts

@@ -14,7 +14,7 @@
 // place with a fresh one whose code is printed. A caller that has to relay a
 // second code because the first expired is the cost being avoided.
 
-import { deviceAuthorize, pollDeviceTokenOnce, decodeEmail } from './session.js';
+import { deviceAuthorize, pollDeviceTokenOnce, postDeviceCancel, decodeEmail } from './session.js';
 import {
   readPendingLogin,
   writePendingLogin,
@@ -37,6 +37,10 @@ export interface LoginStartOptions {
   // Mint a fresh grant even when a usable one is pending (`--new`), for a
   // human who lost the relayed code.
   force?: boolean;
+  // Set when a wait follows in the same command (`--start --wait`), whose own
+  // terminal result is the one the caller reads. `--json` is one document per
+  // run, so the started state prints to the human stream only.
+  resultFollows?: boolean;
   env?: NodeJS.ProcessEnv;
   now?: () => number;
 }
@@ -52,21 +56,35 @@ export async function loginStart(options: LoginStartOptions): Promise<number> {
   // second code and forgets the first, so an approval the human is part-way
   // through completes a grant the CLI can no longer redeem and they are asked
   // to sign in again.
-  const existing = options.force === true ? null : await readPendingLogin(options.profile, env);
+  const existing = await readPendingLogin(options.profile, env);
   const resumed =
-    existing !== null && existing.expiresAt - now() > MIN_USABLE_REMAINING_MS ? existing : null;
+    options.force !== true &&
+    existing !== null &&
+    existing.expiresAt - now() > MIN_USABLE_REMAINING_MS
+      ? existing
+      : null;
+  // A superseded grant that is still live stays approvable on the server for
+  // the rest of its TTL while this machine forgets the only copy of its
+  // device code, so cancel it before the record is overwritten. Best-effort:
+  // an undelivered cancel leaves a grant nobody can redeem from here, and the
+  // new grant is the one this command is for.
+  if (resumed === null && existing !== null && existing.expiresAt > now()) {
+    await postDeviceCancel(existing.authBaseUrl, existing.deviceCode);
+  }
   const pending = resumed ?? (await mintPendingLogin(options.authBaseUrl, now(), options.profile, env));
   promptFor(options.log, pending, {
     lead: resumed === null ? null : 'A sign-in is already waiting for approval.',
   });
-  options.log.result({
-    state: 'started',
-    resumed: resumed !== null,
-    verification_url: targetUrl(pending),
-    user_code: pending.userCode,
-    expires_at: pending.expiresAt,
-    expires_in_seconds: remainingSeconds(pending, now()),
-  });
+  if (options.resultFollows !== true) {
+    options.log.result({
+      state: 'started',
+      resumed: resumed !== null,
+      verification_url: targetUrl(pending),
+      user_code: pending.userCode,
+      expires_at: pending.expiresAt,
+      expires_in_seconds: remainingSeconds(pending, now()),
+    });
+  }
   return 0;
 }
 
@@ -129,7 +147,7 @@ export async function loginCheck(options: LoginCheckOptions): Promise<number> {
       }
       await writeStoredCredential(
         options.profile,
-        { session: { sid: outcome.tokens.sessionToken } },
+        { session: { sid: outcome.tokens.sessionToken, authBaseUrl: pending.authBaseUrl } },
         env,
       );
       await writePendingLogin(options.profile, null, env);

package/src/project.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile, readdir, stat, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, readdir, stat, mkdir, realpath } from 'node:fs/promises';
 import { join, relative, sep, dirname } from 'node:path';
 import { createHash } from 'node:crypto';
 import { zipSync } from 'fflate';
@@ -123,22 +123,56 @@ export function mergeSchemaIntoManifest(
 // by forward-slash relative path (zip entries never use the OS separator).
 // Symlinks are followed via `stat`; empty directories are omitted (a static
 // bundle has none that matter).
+// The one entry name a zip built from an object map cannot carry. Assigning it
+// on an ordinary object literal runs the prototype setter instead of adding an
+// entry, and both this walk and fflate's own index are such maps, so the file
+// drops out of the archive and the map inherits from the bytes it was handed.
+// fflate then walks that index with `for...in`, reaches the inherited keys, and
+// writes one bogus directory per byte of the file. Only the exact name at the
+// root of the bundle does this: a `__proto__` inside a subdirectory is keyed by
+// its whole relative path, which is an ordinary string.
+const UNPUBLISHABLE_ENTRY_NAME = '__proto__';
+
 export async function collectZipEntries(root: string): Promise<Record<string, Uint8Array>> {
-  const entries: Record<string, Uint8Array> = {};
-  async function walk(dir: string): Promise<void> {
+  // Null-prototype, so the name above lands as an ordinary key and the refusal
+  // below can see it. On a plain literal it is already gone by then.
+  const entries: Record<string, Uint8Array> = Object.create(null) as Record<
+    string,
+    Uint8Array
+  >;
+  // The real paths of the directories on the way down to `dir`, so a symlink
+  // pointing back at one of its own ancestors ends the descent instead of
+  // walking the subtree again at every level. `stat` resolves symlinks, so
+  // without this the walk re-reads the whole subtree until the kernel refuses
+  // the path at its symlink depth and the publish dies on a raw ELOOP naming a
+  // path thousands of characters long. Only an ANCESTOR ends it: two separate
+  // links to one directory are two real places to publish from, and each is
+  // still walked.
+  async function walk(dir: string, ancestors: readonly string[]): Promise<void> {
+    const real = await realpath(dir);
+    if (ancestors.includes(real)) return;
+    const chain = [...ancestors, real];
     const names = await readdir(dir);
     for (const name of names) {
       const abs = join(dir, name);
       const info = await stat(abs);
       if (info.isDirectory()) {
-        await walk(abs);
+        await walk(abs, chain);
       } else if (info.isFile()) {
         const rel = relative(root, abs).split(sep).join('/');
         entries[rel] = new Uint8Array(await readFile(abs));
       }
     }
   }
-  await walk(root);
+  await walk(root, []);
+  if (UNPUBLISHABLE_ENTRY_NAME in entries) {
+    throw new Error(
+      `Cannot publish a file named "${UNPUBLISHABLE_ENTRY_NAME}" at the top ` +
+        `level of ${root}: the archive format keys entries by name, and that ` +
+        `name is an object's prototype rather than an entry. Rename or remove ` +
+        `it.`,
+    );
+  }
   return entries;
 }
 

package/src/session.ts

@@ -4,17 +4,25 @@
 // code prefilled (and prints the URL + code as a fallback for a headless
 // box), then polls until the human approves. Approval mints the same tokens
 // `/refresh` returns, including the opaque `session_token` the CLI stores to
-// keep refreshing. The CLI's OAuth client is the seeded
-// `brass_app_internal_cli`; its redirect allowlist is the loopback wildcards,
-// which the `/refresh` Origin gate checks the CLI's portless 127.0.0.1 origin
-// against on every later token refresh.
+// keep refreshing, which is bound to the CLI's own app id. That app's
+// registered redirect URLs are the loopback wildcards, which is what lets the
+// portless 127.0.0.1 origin below pass the `/refresh` Origin check on every
+// later token refresh.
 
 import { spawn } from 'node:child_process';
-import { BrassApiError } from './api.js';
+import { BrassApiError, networkError } from './api.js';
 import type { AuthProvider } from './auth.js';
 
-// The seeded CLI OAuth client (see infra/lib/api-stack.ts). Stable across
-// environments, so one CLI build signs in against prod or dev.
+// Every auth call carries a few hundred bytes, so a host still silent after
+// this is one that is not going to answer.
+const AUTH_TIMEOUT_MS = 15_000;
+// Signing out on the server is best effort: `runLogout` clears the local
+// credential whatever this returns, so a host that stalls must not be what
+// stops the credential being cleared.
+const SIGN_OUT_TIMEOUT_MS = 5_000;
+
+// The app id the CLI signs in as. Stable across environments, so one CLI
+// build authenticates against whichever stack the origin flags name.
 export const CLI_APP_ID = 'brass_app_internal_cli';
 
 // The Origin the CLI presents on every `/refresh` call (a command refreshing
@@ -30,7 +38,9 @@ export interface RefreshedTokens {
   idToken: string;
   expiresAt: number;
   // Present only on the initial device-grant token exchange: the opaque
-  // session pointer the CLI persists and echoes on later refreshes.
+  // session pointer the CLI persists and echoes on later refreshes. Bound to
+  // the CLI's app id, so a copy of it authenticates as the CLI and nothing
+  // else.
   sessionToken?: string;
 }
 
@@ -41,6 +51,20 @@ interface RefreshWire {
   session_token?: string;
 }
 
+// The lifetime to stamp a token set with, given whatever `expires_in` the
+// response carried. Every value that is not a positive finite number stamps an
+// `expiresAt` the refresh guard `Date.now() >= expiresAt` reads wrong: a
+// missing or non-numeric one makes it NaN, so every comparison is false and
+// the token is never re-refreshed, and a zero or negative one makes it already
+// past, so every call refreshes again. The SDK's `tokenTtlSeconds` is the same
+// guard on the same field.
+const DEFAULT_TOKEN_TTL_SECONDS = 3600;
+function tokenTtlSeconds(expiresIn: unknown): number {
+  return typeof expiresIn === 'number' && Number.isFinite(expiresIn) && expiresIn > 0
+    ? expiresIn
+    : DEFAULT_TOKEN_TTL_SECONDS;
+}
+
 // Refresh an access token at `/refresh` from the stored session pointer
 // (`sid`). A form-encoded body keeps this a CORS simple request (the auth API
 // serves no preflight); the Origin header is required by the endpoint's
@@ -59,9 +83,10 @@ export async function postRefresh(
       method: 'POST',
       headers: { 'content-type': 'application/x-www-form-urlencoded', origin },
       body,
+      signal: AbortSignal.timeout(AUTH_TIMEOUT_MS),
     });
   } catch (cause) {
-    throw new BrassApiError(0, `Network error reaching ${authBaseUrl}: ${String(cause)}`);
+    throw networkError(`reaching ${authBaseUrl}`, cause);
   }
   if (!response.ok) {
     // Carry the status, and name what a 401 means. Every command reaches the
@@ -76,21 +101,79 @@ export async function postRefresh(
         : `Sign-in exchange failed (${response.status}).`,
     );
   }
-  const json = (await response.json()) as RefreshWire;
+  const json = (await response.json().catch(() => ({}))) as Partial<RefreshWire>;
+  // A 200 carrying no tokens is a failed exchange whatever the status said.
+  // Taken here because the fields are read unchecked otherwise: an absent
+  // `access_token` is stored as `undefined` and presented as the literal
+  // header `Bearer undefined`, which comes back 401 and is reported as an
+  // expired sign-in, sending the caller to `brass login` for a session that
+  // was never the problem. `pollDeviceToken` requires both fields already.
+  if (!json.access_token || !json.id_token) {
+    throw new BrassApiError(
+      response.status,
+      `Sign-in exchange returned no tokens (${response.status}).`,
+    );
+  }
   return {
     accessToken: json.access_token,
     idToken: json.id_token,
-    // Default the lifetime when the server omits it: `undefined * 1000` is
-    // `NaN`, which makes `expiresAt` NaN and the `Date.now() >= expiresAt`
-    // refresh guard permanently false, so the in-process token would never
-    // re-refresh. `pollDeviceToken` already guards the same field.
-    expiresAt: now + (json.expires_in ?? 3600) * 1000,
+    expiresAt: now + tokenTtlSeconds(json.expires_in) * 1000,
     ...(json.session_token ? { sessionToken: json.session_token } : {}),
   };
 }
 
-// Decode the email claim from a Cognito id token, best-effort (used only for
-// the "Signed in as ..." confirmation; never for authorization).
+// End this machine's sign-in on the server, not only in the local
+// credentials file. The stored pointer keeps minting access tokens for the
+// rest of the session's life, so forgetting it locally leaves a working
+// credential behind wherever a copy of the file went.
+//
+// Reports whether the server confirmed it. The stored pointer is the caller's
+// only handle on the session, so what the caller does with the record follows
+// from this: an undelivered revoke keeps it for the retry.
+export async function postSignOut(
+  authBaseUrl: string,
+  sid: string,
+  origin: string = REFRESH_ORIGIN,
+): Promise<boolean> {
+  const url = `${authBaseUrl}/sign-out-of-app?${new URLSearchParams({ app_id: CLI_APP_ID }).toString()}`;
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', origin },
+      body: new URLSearchParams({ sid }),
+      signal: AbortSignal.timeout(SIGN_OUT_TIMEOUT_MS),
+    });
+    // A 401 means the pointer no longer resolves, which is the state the
+    // caller wanted: there is nothing left to revoke.
+    return response.ok || response.status === 401;
+  } catch {
+    return false;
+  }
+}
+
+// Abandon a sign-in this machine started and never redeemed, so the code it
+// relayed to a human stops being redeemable. Reports whether the server took
+// it, like `postSignOut`: the record naming the grant is the caller's only
+// handle on it, so what the caller does with the record follows from this.
+export async function postDeviceCancel(
+  authBaseUrl: string,
+  deviceCode: string,
+): Promise<boolean> {
+  try {
+    const response = await fetch(`${authBaseUrl}/device/cancel`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ device_code: deviceCode, app_id: CLI_APP_ID }),
+      signal: AbortSignal.timeout(SIGN_OUT_TIMEOUT_MS),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+// Decode the email claim from an id token, best-effort (used only for the
+// "Signed in as ..." confirmation; never for authorization).
 export function decodeEmail(idToken: string): string | undefined {
   const part = idToken.split('.')[1];
   if (part === undefined) return undefined;
@@ -144,6 +227,7 @@ export async function deviceAuthorize(
       method: 'POST',
       headers: { 'content-type': 'application/x-www-form-urlencoded' },
       body,
+      signal: AbortSignal.timeout(AUTH_TIMEOUT_MS),
     });
   } catch (cause) {
     throw new Error(`Network error reaching ${authBaseUrl}: ${String(cause)}`);
@@ -190,6 +274,7 @@ export async function pollDeviceTokenOnce(
       method: 'POST',
       headers: { 'content-type': 'application/x-www-form-urlencoded' },
       body,
+      signal: AbortSignal.timeout(AUTH_TIMEOUT_MS),
     });
   } catch {
     // A transient network error mid-poll: the device grant is still valid
@@ -207,7 +292,7 @@ export async function pollDeviceTokenOnce(
       tokens: {
         accessToken: json.access_token,
         idToken: json.id_token,
-        expiresAt: now + (json.expires_in ?? 3600) * 1000,
+        expiresAt: now + tokenTtlSeconds(json.expires_in) * 1000,
         ...(json.session_token ? { sessionToken: json.session_token } : {}),
       },
     };
@@ -216,9 +301,9 @@ export async function pollDeviceTokenOnce(
   if (json.error === 'access_denied') return { state: 'denied' };
   // RFC 8628 §3.5: polling too fast. The caller backs off.
   if (json.error === 'slow_down') return { state: 'slow_down' };
-  // Everything else — `authorization_pending`, a transient non-2xx (5xx/429),
-  // a non-JSON body, or an error code this pinned CLI does not recognize — is
-  // "keep waiting". The caller's deadline check is the single terminal bound,
+  // Everything else is "keep waiting": `authorization_pending`, a transient
+  // non-2xx (5xx/429), a non-JSON body, or an error code this pinned CLI does
+  // not recognize. The caller's deadline check is the single terminal bound,
   // so an unknown error or a server blip does not abort a sign-in the user is
   // one poll away from completing; a genuinely expired grant simply ends
   // there as a clean timeout.

package/src/version.ts

@@ -3,6 +3,6 @@
 // free here, unlike the SDK's query-param channel). Lets the platform
 // measure the CLI version distribution, in particular pinned CI copies.
 // A unit test pins this to package.json's version.
-export const VERSION = '0.1.0';
+export const VERSION = '0.3.0';
 
 export const CLI_CLIENT_ID = `cli/${VERSION}`;