@gjsify/cli 0.35.0 → 0.37.0

package/lib/utils/npm-oidc.d.ts

@@ -6,14 +6,12 @@ interface OidcExchangeOptions {
     /** Optional verbose logger — receives single-line strings. */
     log?: (msg: string) => void;
     /**
-     * Max retries on a TRANSIENT exchange failure (5xx / 429 / network error).
-     * Default 3. A transient npm-side blip (e.g. a 503 Service Unavailable on a
-     * single package mid-release) used to fall straight through to token auth,
-     * which in OIDC-only CI has no token → a 404 that broke the release while
-     * the workflow stayed green (the `@gjsify/process@0.7.3` v0.7.3 incident).
-     * Retrying the exchange keeps the publish on the OIDC path. Non-transient
-     * statuses (404 "package not found", 401/403 misconfig) are NOT retried —
-     * they're surfaced immediately so `--tolerate-untrusted-new` etc. still work.
+     * Max retries on a TRANSIENT exchange failure (5xx / 429 / network error), default 3. A
+     * single npm-side 503 mid-release used to fall straight through to token auth, which in
+     * OIDC-only CI has no token → a 404 that broke the release while the workflow stayed green
+     * (hit on `@gjsify/process` during v0.7.3). Retrying keeps the publish on the OIDC path.
+     * Non-transient statuses (404 "package not found", 401/403 misconfig) are NOT retried, so
+     * `--tolerate-untrusted-new` and the misconfig hints still fire on the first response.
      */
     maxRetries?: number;
     /** Base backoff in ms for transient retries; doubles each attempt (capped 8s). Default 1000. Tests pass 0. */
@@ -34,55 +32,43 @@ export declare class OidcExchangeError extends Error {
     readonly body: string;
     readonly packageName: string;
     /**
-     * The non-secret claims decoded from the GitHub OIDC JWT that npm
-     * rejected — `repository`, `workflow_ref`, `environment`, … These are
-     * exactly what npm matches a Trusted Publisher config against, so on a
-     * 401/403 they tell you precisely which fields the config must carry.
+     * Non-secret claims decoded from the rejected JWT (`repository`, `workflow_ref`,
+     * `environment`, …) — exactly what npm matches a Trusted Publisher config against, so on
+     * a 401/403 they name which fields the config must carry.
      */
     readonly claims?: Record<string, unknown> | undefined;
     constructor(message: string, status: number, body: string, packageName: string, 
     /**
-     * The non-secret claims decoded from the GitHub OIDC JWT that npm
-     * rejected — `repository`, `workflow_ref`, `environment`, … These are
-     * exactly what npm matches a Trusted Publisher config against, so on a
-     * 401/403 they tell you precisely which fields the config must carry.
+     * Non-secret claims decoded from the rejected JWT (`repository`, `workflow_ref`,
+     * `environment`, …) — exactly what npm matches a Trusted Publisher config against, so on
+     * a 401/403 they name which fields the config must carry.
      */
     claims?: Record<string, unknown> | undefined);
 }
 /**
- * Decode the (non-secret) payload of a JWT — the middle base64url segment.
- * A GitHub OIDC id-token's payload is public metadata about the workflow run
- * (`repository`, `repository_owner`, `workflow_ref`, `job_workflow_ref`,
- * `ref`, `environment`, `sub`, …); the SIGNATURE is what makes it trustworthy.
- * Returns null if the token isn't a well-formed three-part JWT.
+ * Decode the non-secret payload of a JWT — the middle base64url segment. A GitHub OIDC
+ * id-token's payload is public metadata about the workflow run; the SIGNATURE is what makes it
+ * trustworthy. Null when the token isn't a well-formed three-part JWT.
  */
 export declare function decodeJwtPayload(jwt: string): Record<string, unknown> | null;
 /**
- * Probe whether OIDC publishing is available in the current process —
- * cheap env-var check, no network access. Used by `gjsify publish` to
- * decide between OIDC and token-based auth in auto-detect mode.
+ * Whether OIDC publishing is available in this process — a cheap env-var check with no network
+ * access, used by `gjsify publish` to choose between OIDC and token auth in auto-detect mode.
  */
 export declare function hasGithubOidcEnv(): boolean;
 /**
- * Request a GitHub Actions OIDC ID token for the given audience.
- * Throws `OidcUnavailableError` when the required env vars are missing
- * (caller can fall back to token auth) or when GitHub rejects the request.
+ * Request a GitHub Actions OIDC ID token for `audience`. Throws `OidcUnavailableError` when the
+ * env vars are missing (the caller can fall back to token auth) or GitHub rejects the request.
  */
 export declare function fetchGithubOidcToken(audience: string, log?: (msg: string) => void): Promise<string>;
 /**
- * Exchange a GitHub OIDC JWT for a short-lived npm publish token at
- * `/-/npm/v1/oidc/token/exchange/package/<escaped-name>`. The npm
- * registry validates the JWT against the package's Trusted Publisher
- * config — if no Trusted Publisher is configured, or the JWT comes from
- * a repo/workflow that doesn't match, the exchange returns a 4xx with
- * a descriptive body which we propagate as `OidcExchangeError`.
+ * Exchange a GitHub OIDC JWT for a short-lived npm publish token. A missing or non-matching
+ * Trusted Publisher config comes back as a 4xx with a descriptive body, propagated as
+ * `OidcExchangeError`.
  */
 export declare function exchangeOidcForNpmToken(args: OidcExchangeOptions & {
     idToken: string;
 }): Promise<string>;
-/**
- * End-to-end: probe env → fetch id-token → exchange for npm token.
- * One-shot convenience for `gjsify publish` and the verification command.
- */
+/** End-to-end: probe env → fetch id-token → exchange for an npm token. */
 export declare function getNpmTrustedToken(opts: OidcExchangeOptions): Promise<OidcExchangeResult>;
 export {};

package/lib/utils/npm-oidc.js

@@ -2,20 +2,14 @@
 //
 // Two-step flow, mirroring `refs/npm-cli/lib/utils/oidc.js`:
 //
-//   1. Request a GitHub Actions OIDC ID token (JWT) from the runner.
-//      Requires `permissions: id-token: write` in the calling workflow.
-//      GitHub provides `ACTIONS_ID_TOKEN_REQUEST_URL` and
-//      `ACTIONS_ID_TOKEN_REQUEST_TOKEN` env vars; we GET the URL with
-//      the runner-provided audience (`npm:registry.npmjs.org`).
+//   1. GET a GitHub Actions OIDC ID token (JWT) from the runner, at
+//      `ACTIONS_ID_TOKEN_REQUEST_URL` with the audience `npm:registry.npmjs.org`. Requires
+//      `permissions: id-token: write` in the calling workflow.
+//   2. Exchange that JWT at `/-/npm/v1/oidc/token/exchange/package/<name>` for a short-lived
+//      (~5 min) npm publish token; npm verifies it against the package's Trusted Publisher
+//      (repository + workflow filename + optional environment).
 //
-//   2. Exchange that JWT at npm's `/-/npm/v1/oidc/token/exchange/package/<name>`
-//      endpoint for a short-lived (~5 min) npm publish token. npm verifies
-//      the JWT against the package's configured Trusted Publisher
-//      (repository + workflow filename + optional environment) and either
-//      issues a token or rejects with an explanatory error.
-//
-// The token returned by step 2 is used for the publish PUT in the same
-// way the long-lived NPM_TOKEN would have been — drop-in replacement.
+// The resulting token is a drop-in replacement for a long-lived NPM_TOKEN on the publish PUT.
 //
 // Reference: refs/npm-cli/lib/utils/oidc.js
 // Original: Copyright (c) npm contributors. Artistic-2.0.
@@ -37,10 +31,9 @@ export class OidcExchangeError extends Error {
     claims;
     constructor(message, status, body, packageName, 
     /**
-     * The non-secret claims decoded from the GitHub OIDC JWT that npm
-     * rejected — `repository`, `workflow_ref`, `environment`, … These are
-     * exactly what npm matches a Trusted Publisher config against, so on a
-     * 401/403 they tell you precisely which fields the config must carry.
+     * Non-secret claims decoded from the rejected JWT (`repository`, `workflow_ref`,
+     * `environment`, …) — exactly what npm matches a Trusted Publisher config against, so on
+     * a 401/403 they name which fields the config must carry.
      */
     claims) {
         super(message);
@@ -52,11 +45,9 @@ export class OidcExchangeError extends Error {
     }
 }
 /**
- * Decode the (non-secret) payload of a JWT — the middle base64url segment.
- * A GitHub OIDC id-token's payload is public metadata about the workflow run
- * (`repository`, `repository_owner`, `workflow_ref`, `job_workflow_ref`,
- * `ref`, `environment`, `sub`, …); the SIGNATURE is what makes it trustworthy.
- * Returns null if the token isn't a well-formed three-part JWT.
+ * Decode the non-secret payload of a JWT — the middle base64url segment. A GitHub OIDC
+ * id-token's payload is public metadata about the workflow run; the SIGNATURE is what makes it
+ * trustworthy. Null when the token isn't a well-formed three-part JWT.
  */
 export function decodeJwtPayload(jwt) {
     const parts = jwt.split('.');
@@ -72,17 +63,15 @@ export function decodeJwtPayload(jwt) {
     }
 }
 /**
- * Probe whether OIDC publishing is available in the current process —
- * cheap env-var check, no network access. Used by `gjsify publish` to
- * decide between OIDC and token-based auth in auto-detect mode.
+ * Whether OIDC publishing is available in this process — a cheap env-var check with no network
+ * access, used by `gjsify publish` to choose between OIDC and token auth in auto-detect mode.
  */
 export function hasGithubOidcEnv() {
     return Boolean(process.env.ACTIONS_ID_TOKEN_REQUEST_URL && process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN);
 }
 /**
- * Request a GitHub Actions OIDC ID token for the given audience.
- * Throws `OidcUnavailableError` when the required env vars are missing
- * (caller can fall back to token auth) or when GitHub rejects the request.
+ * Request a GitHub Actions OIDC ID token for `audience`. Throws `OidcUnavailableError` when the
+ * env vars are missing (the caller can fall back to token auth) or GitHub rejects the request.
  */
 export async function fetchGithubOidcToken(audience, log) {
     const url = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
@@ -91,15 +80,11 @@ export async function fetchGithubOidcToken(audience, log) {
         throw new OidcUnavailableError('GitHub Actions OIDC env vars (ACTIONS_ID_TOKEN_REQUEST_{URL,TOKEN}) not set. ' +
             'The calling workflow needs `permissions: id-token: write`.', 'no-env');
     }
-    // Append the audience by STRING CONCATENATION, mirroring @actions/core's
-    // getIDToken (`${runtimeUrl}&audience=${encodeURIComponent(aud)}`) and the
-    // raw-curl probe that returns HTTP 201. Do NOT use `URL.searchParams.set` +
-    // `.href`: under GJS that serialization dropped the `audience` query param,
-    // so GitHub issued an id-token with the DEFAULT audience (the repo API URL)
-    // instead of `npm:registry.npmjs.org`. npm then rejected the otherwise-valid
-    // token with 401 "unauthorized" — the JWT's repository/workflow_ref/sub
-    // claims all matched the Trusted Publisher, only `aud` was wrong, which is
-    // exactly the failure we saw (curl from the same workflow → 201).
+    // Append the audience by STRING CONCATENATION, as @actions/core's getIDToken does. Do NOT
+    // use `URL.searchParams.set` + `.href`: under GJS that serialization dropped the `audience`
+    // param, so GitHub issued an id-token with the DEFAULT audience (the repo API URL) and npm
+    // rejected an otherwise-valid token with 401 — repository/workflow_ref/sub all matched the
+    // Trusted Publisher, only `aud` was wrong.
     const sep = url.includes('?') ? '&' : '?';
     const requestUrl = `${url}${sep}audience=${encodeURIComponent(audience)}`;
     log?.(`gjsify oidc: GET ${requestUrl.replace(bearer, '<bearer>')}`);
@@ -121,12 +106,9 @@ export async function fetchGithubOidcToken(audience, log) {
     return json.value;
 }
 /**
- * Exchange a GitHub OIDC JWT for a short-lived npm publish token at
- * `/-/npm/v1/oidc/token/exchange/package/<escaped-name>`. The npm
- * registry validates the JWT against the package's Trusted Publisher
- * config — if no Trusted Publisher is configured, or the JWT comes from
- * a repo/workflow that doesn't match, the exchange returns a 4xx with
- * a descriptive body which we propagate as `OidcExchangeError`.
+ * Exchange a GitHub OIDC JWT for a short-lived npm publish token. A missing or non-matching
+ * Trusted Publisher config comes back as a 4xx with a descriptive body, propagated as
+ * `OidcExchangeError`.
  */
 export async function exchangeOidcForNpmToken(args) {
     const { packageName, registry, idToken, log } = args;
@@ -154,8 +136,7 @@ export async function exchangeOidcForNpmToken(args) {
                     'Content-Type': 'application/json',
                     Accept: 'application/json',
                 },
-                // npm's exchange endpoint accepts an empty JSON body — the JWT
-                // is the proof, no additional claims needed from us.
+                // Empty JSON body: the JWT is the proof, no additional claims are needed.
                 body: '{}',
             });
         }
@@ -171,10 +152,7 @@ export async function exchangeOidcForNpmToken(args) {
         }
         const text = await res.text().catch(() => '');
         if (!res.ok) {
-            // Retry only TRANSIENT npm-side failures; surface everything else
-            // (404/401/403 etc.) immediately so the caller's diagnostics —
-            // `--tolerate-untrusted-new`, Trusted-Publisher misconfig hints —
-            // still fire on the first response.
+            // Only TRANSIENT npm-side failures retry — see `maxRetries`.
             if (TRANSIENT_EXCHANGE_STATUSES.has(res.status) && attempt < maxRetries) {
                 const delay = Math.min(retryBaseMs * 2 ** attempt, 8000);
                 log?.(`gjsify oidc: transient ${res.status} ${res.statusText} for ${packageName} (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms`);
@@ -196,10 +174,7 @@ export async function exchangeOidcForNpmToken(args) {
         return json.token;
     }
 }
-/**
- * End-to-end: probe env → fetch id-token → exchange for npm token.
- * One-shot convenience for `gjsify publish` and the verification command.
- */
+/** End-to-end: probe env → fetch id-token → exchange for an npm token. */
 export async function getNpmTrustedToken(opts) {
     const audience = `npm:${new URL(opts.registry).hostname}`;
     const idToken = await fetchGithubOidcToken(audience, opts.log);

package/lib/utils/npm-otp-cache.d.ts

@@ -14,13 +14,13 @@ export interface OtpCacheOptions {
 /** `true` unless `GJSIFY_NO_OTP_CACHE` is set to a truthy value. */
 export declare function isOtpCacheEnabled(): boolean;
 /**
- * Read the cached code for `registry`, or `undefined` on a miss / expiry /
- * opt-out. An EXPIRED entry is deleted as a side effect.
+ * The cached code for `registry`, or `undefined` on a miss / expiry / opt-out. An EXPIRED entry
+ * is deleted as a side effect.
  */
 export declare function readCachedOtp(registry: string, opts?: OtpCacheOptions): string | undefined;
 /**
- * Persist `otp` for `registry` with a fresh TTL, perms 0600. No-op on opt-out
- * or empty code. Best-effort — a write failure never throws.
+ * Persist `otp` for `registry` with a fresh TTL, perms 0600. No-op on opt-out or an empty code;
+ * a write failure never throws.
  */
 export declare function writeCachedOtp(registry: string, otp: string, opts?: OtpCacheOptions): void;
 /** Drop the cached code for a single registry (invalid/consumed OTP, or logout). */

package/lib/utils/npm-otp-cache.js

@@ -1,22 +1,17 @@
 // Short-lived, CROSS-INVOCATION cache for the npm 2FA one-time code.
 //
-// A TOTP stays valid for its ~30 s window, so a `login → onboard → publish →
-// trust` sequence of SEPARATE `gjsify` processes should reuse ONE typed code
-// instead of prompting per command. The in-process `OtpProvider` cache
-// (utils/npm-otp.ts) only survives a single command; this file is the layer
-// under it that survives across invocations.
+// A TOTP stays valid for its ~30 s window, so a `login → onboard → publish → trust` sequence of
+// SEPARATE `gjsify` processes should reuse ONE typed code instead of prompting per command. The
+// in-process `OtpProvider` cache (utils/npm-otp.ts) survives only a single command; this is the
+// layer under it that survives across invocations.
 //
-// Design:
-//   - Stored in a temp file (under `$XDG_RUNTIME_DIR`, else the OS temp dir —
-//     NEVER the repo), perms 0600, with a stamped absolute `expiresAt`.
-//   - TTL = one TOTP window (30 s), deliberately short. A read past the expiry
-//     ignores AND deletes the file.
-//   - Keyed by the REGISTRY URL, so a code for one registry is never replayed
-//     against another.
-//   - Best-effort: a cache miss/error NEVER breaks the command — a stale or
-//     unreadable entry degrades to "no cached code" (re-prompt).
-//   - Opt-out: `GJSIFY_NO_OTP_CACHE=1` disables it entirely; `gjsify logout`
-//     clears it.
+//   - A temp file under `$XDG_RUNTIME_DIR`, else the OS temp dir — NEVER the repo — perms 0600,
+//     with a stamped absolute `expiresAt`.
+//   - TTL = one TOTP window (30 s), deliberately short; a read past expiry ignores AND deletes.
+//   - Keyed by REGISTRY URL, so a code for one registry is never replayed against another.
+//   - Best-effort: a stale or unreadable entry degrades to "no cached code" (re-prompt), never
+//     an error.
+//   - `GJSIFY_NO_OTP_CACHE=1` disables it entirely; `gjsify logout` clears it.
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -50,8 +45,8 @@ function cacheFileFor(registry, opts) {
     return join(cacheBaseDir(opts), `otp-${safe || 'default'}.json`);
 }
 /**
- * Read the cached code for `registry`, or `undefined` on a miss / expiry /
- * opt-out. An EXPIRED entry is deleted as a side effect.
+ * The cached code for `registry`, or `undefined` on a miss / expiry / opt-out. An EXPIRED entry
+ * is deleted as a side effect.
  */
 export function readCachedOtp(registry, opts) {
     if (!isOtpCacheEnabled())
@@ -70,7 +65,7 @@ export function readCachedOtp(registry, opts) {
         if (entry.registry !== normalizeRegistry(registry))
             return undefined;
         if (now >= entry.expiresAt) {
-            deleteCacheFile(file); // expired → ignore + delete
+            deleteCacheFile(file);
             return undefined;
         }
         return entry.otp.length > 0 ? entry.otp : undefined;
@@ -82,8 +77,8 @@ export function readCachedOtp(registry, opts) {
     }
 }
 /**
- * Persist `otp` for `registry` with a fresh TTL, perms 0600. No-op on opt-out
- * or empty code. Best-effort — a write failure never throws.
+ * Persist `otp` for `registry` with a fresh TTL, perms 0600. No-op on opt-out or an empty code;
+ * a write failure never throws.
  */
 export function writeCachedOtp(registry, otp, opts) {
     if (!isOtpCacheEnabled())
@@ -98,8 +93,8 @@ export function writeCachedOtp(registry, otp, opts) {
         const file = cacheFileFor(registry, opts);
         const entry = { otp, expiresAt: now + ttl, registry: normalizeRegistry(registry) };
         writeFileSync(file, JSON.stringify(entry), { mode: 0o600 });
-        // Enforce 0600 even when the file pre-existed with looser perms (writeFile
-        // only applies `mode` on create) — the code is a live secret.
+        // Enforce 0600 even when the file pre-existed with looser perms — `writeFileSync` applies
+        // `mode` only on create, and the code is a live secret.
         chmodSync(file, 0o600);
     }
     catch {
@@ -116,7 +111,7 @@ export function clearAllCachedOtp(opts) {
         rmSync(cacheBaseDir(opts), { recursive: true, force: true });
     }
     catch {
-        /* ignore */
+        /* best-effort — an unremovable cache dir must not fail a logout */
     }
 }
 /** POSIX file-mode bits of the cache file (test helper); `undefined` if absent. */
@@ -137,6 +132,6 @@ function deleteCacheFile(file) {
             rmSync(file, { force: true });
     }
     catch {
-        /* ignore */
+        /* best-effort — the entry has already been treated as a miss by every caller */
     }
 }

package/lib/utils/npm-otp.d.ts

@@ -3,7 +3,6 @@ export type OtpPromptFn = (question: string) => Promise<string>;
 /**
  * True when a response is an npm OTP / 2FA challenge (401 + a `www-authenticate`
  * header naming `otp`, or a body mentioning a one-time password / `EOTP`).
- * Unifies the detection logic previously inlined in both publish.ts and trust.ts.
  */
 export declare function isOtpChallenge(res: Response): Promise<boolean>;
 /** Options controlling the cross-invocation file cache an {@link OtpProvider} rides on top of. */
@@ -12,9 +11,9 @@ export interface OtpProviderOptions {
      * Registry URL scoping the SHORT-LIVED cross-invocation OTP cache
      * (`utils/npm-otp-cache.ts`). When set, a provider constructed WITHOUT an
      * explicit seed reads the file-cached code first (so a sibling `gjsify`
-     * command's typed OTP is reused within its ~30 s TOTP window), and every
-     * newly typed/seeded code is written back for the next command. Omit → the
-     * provider is in-process-only (the historical behaviour).
+     * command's typed OTP is reused within its ~30 s TOTP window), and every newly
+     * typed/seeded code is written back for the next command. Omit for an
+     * in-process-only provider.
      */
     registry?: string;
 }
@@ -22,12 +21,11 @@ export interface OtpProviderOptions {
  * Holds ONE OTP code across a run and knows how to prompt for a fresh one.
  *
  * `current()` returns the cached code (seeded from `--otp`, the cross-invocation
- * file cache, or the last one the user typed). `refresh()` prompts for a new
- * code and caches it (in-process AND — when a `registry` is set — in the
- * short-lived file cache). A single provider instance shared across many
- * publish + trust operations is what makes `gjsify onboard` need only one OTP
- * entry for the whole sweep; the file cache extends that reuse across SEPARATE
- * `gjsify` invocations (`login → onboard → publish → trust`).
+ * file cache, or the last one typed); `refresh()` prompts for a new one and caches
+ * it in-process AND — when a `registry` is set — in the short-lived file cache. One
+ * shared instance is what makes `gjsify onboard` need a single OTP entry for a whole
+ * sweep; the file cache extends that reuse across SEPARATE invocations
+ * (`login → onboard → publish → trust`).
  */
 export declare class OtpProvider {
     private cached;
@@ -44,15 +42,14 @@ export declare class OtpProvider {
     /** The currently cached OTP code, if any. */
     current(): string | undefined;
     /**
-     * Prompt for a fresh code, cache it (in-process + file cache), and return
-     * it (the trimmed input, or `''` when nothing was entered — the caller
-     * treats empty as "give up").
+     * Prompt for a fresh code, cache it (in-process + file cache), and return the
+     * trimmed input — `''` when nothing was entered, which callers read as "give up".
      */
     refresh(question?: string): Promise<string>;
     /**
-     * Drop the cached code (in-process AND the cross-invocation file entry)
-     * after npm rejects it as invalid/consumed — so the NEXT command re-prompts
-     * instead of replaying a single-use code that the registry already burned.
+     * Drop the cached code (in-process AND the cross-invocation file entry) after npm
+     * rejects it, so the NEXT command re-prompts instead of replaying a single-use
+     * code the registry already burned.
      */
     invalidate(): void;
 }
@@ -72,20 +69,13 @@ export interface OtpRetryOptions {
     question?: string;
 }
 /**
- * Run `doFetch` with cache-first OTP retry against a shared {@link OtpProvider}.
+ * Run `doFetch` with cache-first OTP retry against a shared {@link OtpProvider}:
+ * attempt without an OTP (or with the cached code under `seedFirstAttempt`), retry
+ * with the cached code on a challenge, then prompt for fresh codes up to
+ * `maxPrompts` times. A declined prompt returns the last challenge response for the
+ * caller to handle.
  *
- * Flow:
- *   1. First attempt — without an OTP (or WITH the cached code when
- *      `seedFirstAttempt` is set).
- *   2. On a 2FA challenge, retry with the currently-cached code (unless step 1
- *      already sent it).
- *   3. If still challenged (cache empty/rejected/expired), prompt for a fresh
- *      code — caching it on the provider so the NEXT operation tries it first —
- *      and retry, up to `maxPrompts` times.
- *   4. Return the last response (a challenge the caller must handle) when the
- *      user declines to enter a code.
- *
- * The caller owns the actual fetch + all response interpretation; this only
- * owns the OTP dance.
+ * The caller owns the fetch and all response interpretation; this owns only the OTP
+ * dance.
  */
 export declare function withOtpRetry(doFetch: (otp?: string) => Promise<Response>, provider: OtpProvider, opts?: OtpRetryOptions): Promise<Response>;

package/lib/utils/npm-otp.js

@@ -1,30 +1,22 @@
 // Shared npm 2FA / OTP handling for the auth-aware CLI commands
 // (`gjsify publish`, `gjsify trust`, `gjsify onboard`).
 //
-// npm signals "OTP required" via HTTP 401 + a `www-authenticate` header
-// containing `otp` (or, for malformed responses, a body mentioning
-// "one-time pass" / `EOTP`) — see
-// refs/npm-cli/node_modules/npm-registry-fetch/lib/check-response.js.
+// npm signals "OTP required" via HTTP 401 + a `www-authenticate` header containing
+// `otp` (or, for malformed responses, a body mentioning "one-time pass" / `EOTP`) —
+// see refs/npm-cli/node_modules/npm-registry-fetch/lib/check-response.js.
 //
-// Two pieces were previously duplicated in `publish.ts` and `trust.ts`:
-//   1. detecting the challenge (`isOtpChallenge`);
-//   2. prompting for a code, then retrying the request with it.
-//
-// They are centralised here so a single `OtpProvider` can be injected across
-// MANY operations in one run. `gjsify onboard` sweeps ~110 packages and would
-// otherwise prompt once per package; with one shared provider the user types
-// an OTP once — the cached code is tried first on every subsequent challenge,
-// and a fresh prompt only happens when npm actually rejects/expires it.
-//
-// Standalone `publish`/`trust` keep their existing single-command UX: each
-// still constructs its own provider and prompts on demand.
+// Detection and prompt-then-retry live here so ONE `OtpProvider` can be injected
+// across many operations in a single run: `gjsify onboard` sweeps every publishable
+// package and would otherwise prompt per package, whereas a shared provider tries the cached
+// code first on every subsequent challenge and only re-prompts when npm actually
+// rejects or expires it. Standalone `publish`/`trust` each construct their own
+// provider and prompt on demand.
 import { promptLine } from './prompt.js';
 import { clearCachedOtp, readCachedOtp, writeCachedOtp } from './npm-otp-cache.js';
 const DEFAULT_QUESTION = 'This operation requires a one-time password.\nEnter OTP: ';
 /**
  * True when a response is an npm OTP / 2FA challenge (401 + a `www-authenticate`
  * header naming `otp`, or a body mentioning a one-time password / `EOTP`).
- * Unifies the detection logic previously inlined in both publish.ts and trust.ts.
  */
 export async function isOtpChallenge(res) {
     if (res.status !== 401)
@@ -42,12 +34,11 @@ export async function isOtpChallenge(res) {
  * Holds ONE OTP code across a run and knows how to prompt for a fresh one.
  *
  * `current()` returns the cached code (seeded from `--otp`, the cross-invocation
- * file cache, or the last one the user typed). `refresh()` prompts for a new
- * code and caches it (in-process AND — when a `registry` is set — in the
- * short-lived file cache). A single provider instance shared across many
- * publish + trust operations is what makes `gjsify onboard` need only one OTP
- * entry for the whole sweep; the file cache extends that reuse across SEPARATE
- * `gjsify` invocations (`login → onboard → publish → trust`).
+ * file cache, or the last one typed); `refresh()` prompts for a new one and caches
+ * it in-process AND — when a `registry` is set — in the short-lived file cache. One
+ * shared instance is what makes `gjsify onboard` need a single OTP entry for a whole
+ * sweep; the file cache extends that reuse across SEPARATE invocations
+ * (`login → onboard → publish → trust`).
  */
 export class OtpProvider {
     cached;
@@ -81,9 +72,8 @@ export class OtpProvider {
         return this.cached;
     }
     /**
-     * Prompt for a fresh code, cache it (in-process + file cache), and return
-     * it (the trimmed input, or `''` when nothing was entered — the caller
-     * treats empty as "give up").
+     * Prompt for a fresh code, cache it (in-process + file cache), and return the
+     * trimmed input — `''` when nothing was entered, which callers read as "give up".
      */
     async refresh(question = DEFAULT_QUESTION) {
         const code = (await this.promptFn(question)).trim();
@@ -95,9 +85,9 @@ export class OtpProvider {
         return code;
     }
     /**
-     * Drop the cached code (in-process AND the cross-invocation file entry)
-     * after npm rejects it as invalid/consumed — so the NEXT command re-prompts
-     * instead of replaying a single-use code that the registry already burned.
+     * Drop the cached code (in-process AND the cross-invocation file entry) after npm
+     * rejects it, so the NEXT command re-prompts instead of replaying a single-use
+     * code the registry already burned.
      */
     invalidate() {
         this.cached = undefined;
@@ -106,21 +96,14 @@ export class OtpProvider {
     }
 }
 /**
- * Run `doFetch` with cache-first OTP retry against a shared {@link OtpProvider}.
- *
- * Flow:
- *   1. First attempt — without an OTP (or WITH the cached code when
- *      `seedFirstAttempt` is set).
- *   2. On a 2FA challenge, retry with the currently-cached code (unless step 1
- *      already sent it).
- *   3. If still challenged (cache empty/rejected/expired), prompt for a fresh
- *      code — caching it on the provider so the NEXT operation tries it first —
- *      and retry, up to `maxPrompts` times.
- *   4. Return the last response (a challenge the caller must handle) when the
- *      user declines to enter a code.
+ * Run `doFetch` with cache-first OTP retry against a shared {@link OtpProvider}:
+ * attempt without an OTP (or with the cached code under `seedFirstAttempt`), retry
+ * with the cached code on a challenge, then prompt for fresh codes up to
+ * `maxPrompts` times. A declined prompt returns the last challenge response for the
+ * caller to handle.
  *
- * The caller owns the actual fetch + all response interpretation; this only
- * owns the OTP dance.
+ * The caller owns the fetch and all response interpretation; this owns only the OTP
+ * dance.
  */
 export async function withOtpRetry(doFetch, provider, opts = {}) {
     const maxPrompts = opts.maxPrompts ?? 2;
@@ -130,20 +113,18 @@ export async function withOtpRetry(doFetch, provider, opts = {}) {
     let res = await doFetch(seededFirst ? cached : undefined);
     if (!(await isOtpChallenge(res)))
         return res;
-    // The seeded (`--otp`/file-cached) code was rejected/consumed — drop it so
-    // it is not replayed and the cross-invocation cache entry is cleared.
+    // The seeded code was rejected/consumed — drop it so it is not replayed and the
+    // cross-invocation cache entry is cleared.
     if (seededFirst)
         provider.invalidate();
-    // Try the cached code if we haven't already sent it.
     if (!seededFirst && provider.current() !== undefined) {
         res = await doFetch(provider.current());
         if (!(await isOtpChallenge(res)))
             return res;
-        // Cached code rejected/consumed (stale seed, or a sibling command
-        // already burned the file-cached single-use code) → invalidate.
+        // Stale seed, or a sibling command already burned the file-cached single-use
+        // code.
         provider.invalidate();
     }
-    // Cache empty, rejected, or expired → prompt for a fresh code and retry.
     for (let i = 0; i < maxPrompts; i++) {
         const fresh = await provider.refresh(question);
         if (!fresh)
@@ -151,8 +132,8 @@ export async function withOtpRetry(doFetch, provider, opts = {}) {
         res = await doFetch(fresh);
         if (!(await isOtpChallenge(res)))
             return res;
-        // The freshly-typed code was also rejected — clear it before re-prompting
-        // so a wedged sequence never leaves a burned code in the file cache.
+        // Clear a rejected fresh code before re-prompting, so a wedged sequence never
+        // leaves a burned code in the file cache.
         provider.invalidate();
     }
     return res;