@dereekb/dbx-cli 14.2.0 → 14.3.0

package/lint-cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-lint-cache",
-  "version": "14.2.0",
+  "version": "14.3.0",
   "sideEffects": false,
   "private": true,
   "type": "module",
@@ -9,7 +9,7 @@
     "eslint": "10.9.1"
   },
   "peerDependencies": {
-    "@dereekb/util": "14.2.0",
+    "@dereekb/util": "14.3.0",
     "yargs": "^18.0.0"
   }
 }

package/manifest-extract/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "14.2.0",
+  "version": "14.3.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.2.0",
-    "@dereekb/dbx-cli": "14.2.0",
-    "@dereekb/firebase": "14.2.0",
-    "@dereekb/model": "14.2.0",
-    "@dereekb/nestjs": "14.2.0",
-    "@dereekb/rxjs": "14.2.0",
-    "@dereekb/util": "14.2.0",
+    "@dereekb/date": "14.3.0",
+    "@dereekb/dbx-cli": "14.3.0",
+    "@dereekb/firebase": "14.3.0",
+    "@dereekb/model": "14.3.0",
+    "@dereekb/nestjs": "14.3.0",
+    "@dereekb/rxjs": "14.3.0",
+    "@dereekb/util": "14.3.0",
     "ts-morph": "^28.0.0"
   },
   "exports": {

package/model-test/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/dbx-cli/model-test",
-  "version": "14.2.0",
+  "version": "14.3.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/util": "14.2.0",
+    "@dereekb/util": "14.3.0",
     "ts-morph": "^28.0.0"
   },
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "14.2.0",
+  "version": "14.3.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -66,11 +66,11 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "14.2.0",
-    "@dereekb/firebase": "14.2.0",
-    "@dereekb/model": "14.2.0",
-    "@dereekb/nestjs": "14.2.0",
-    "@dereekb/util": "14.2.0",
+    "@dereekb/date": "14.3.0",
+    "@dereekb/firebase": "14.3.0",
+    "@dereekb/model": "14.3.0",
+    "@dereekb/nestjs": "14.3.0",
+    "@dereekb/util": "14.3.0",
     "@nestjs/common": "^12.0.1",
     "arktype": "^2.2.0",
     "firebase": "^12.18.0",

package/route/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/dbx-cli/route",
-  "version": "14.2.0",
+  "version": "14.3.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.2.0",
-    "@dereekb/dbx-cli": "14.2.0",
-    "@dereekb/firebase": "14.2.0",
-    "@dereekb/model": "14.2.0",
-    "@dereekb/nestjs": "14.2.0",
-    "@dereekb/util": "14.2.0"
+    "@dereekb/date": "14.3.0",
+    "@dereekb/dbx-cli": "14.3.0",
+    "@dereekb/firebase": "14.3.0",
+    "@dereekb/model": "14.3.0",
+    "@dereekb/nestjs": "14.3.0",
+    "@dereekb/util": "14.3.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/src/lib/auth/index.d.ts

@@ -1,3 +1,4 @@
 export * from './auth.command.factory';
 export * from './oidc.client';
 export * from './oidc.flow';
+export * from './oidc.loopback';

package/src/lib/auth/oidc.loopback.d.ts

@@ -0,0 +1,127 @@
+import { type Maybe, type PortNumber, type WebsiteUrl } from '@dereekb/util';
+/**
+ * Hostnames RFC 8252 §7.3 treats as the loopback interface, and the exact set `oidc-provider`
+ * recognizes as a loopback redirect host.
+ *
+ * `[::1]` carries its brackets because that is what `URL.hostname` returns for an IPv6 literal —
+ * the brackets are stripped again before the address is handed to `server.listen`.
+ */
+export declare const LOOPBACK_REDIRECT_HOSTNAMES: readonly string[];
+/**
+ * The loopback port the CLI suggests when the configured redirect URI has no bindable port.
+ *
+ * Deliberately outside the 9900-9910 block the Firebase emulators occupy, so a suggested redirect
+ * URI never collides with a running emulator.
+ */
+export declare const SUGGESTED_CLI_LOOPBACK_REDIRECT_PORT: PortNumber;
+/**
+ * Error code raised when the loopback listener cannot bind the redirect URI's port (e.g. the port
+ * is already in use, or is privileged).
+ */
+export declare const LOOPBACK_REDIRECT_LISTEN_FAILED_ERROR_CODE = "AUTH_REDIRECT_LISTEN_FAILED";
+/**
+ * Error code raised when no redirect reached the loopback listener within the allotted time.
+ */
+export declare const LOOPBACK_REDIRECT_TIMEOUT_ERROR_CODE = "AUTH_REDIRECT_TIMEOUT";
+/**
+ * A redirect URI the CLI can bind a local HTTP listener to, decomposed into its parts.
+ */
+export interface LoopbackRedirectTarget {
+    /**
+     * The normalized redirect URI to send as `redirect_uri`. Identical to the configured URI unless a
+     * port override was applied.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * The loopback hostname, as `URL.hostname` reports it (so `[::1]` keeps its brackets).
+     */
+    readonly hostname: string;
+    /**
+     * The port to bind. Always a positive integer — a `0`/absent port is not a capturable target.
+     */
+    readonly port: PortNumber;
+    /**
+     * The path the provider redirects to. Requests to any other path are answered `404` so a stray
+     * `/favicon.ico` cannot be mistaken for the authorization redirect.
+     */
+    readonly pathname: string;
+}
+export interface ParseLoopbackRedirectUriInput {
+    /**
+     * The configured redirect URI.
+     */
+    readonly redirectUri: Maybe<string>;
+    /**
+     * Optional port override, replacing whatever port the redirect URI carries.
+     *
+     * The resulting URI is what gets sent as `redirect_uri`, so it must be registered with the OAuth
+     * client just like the configured one.
+     */
+    readonly port?: Maybe<PortNumber>;
+}
+/**
+ * Decomposes a redirect URI into a {@link LoopbackRedirectTarget} when the CLI can bind a local
+ * listener for it.
+ *
+ * A target is only produced for an `http:` loopback URI carrying a concrete, non-zero port. The
+ * conventional `http://127.0.0.1:0/callback` placeholder is deliberately NOT capturable: binding an
+ * ephemeral port would mean sending a `redirect_uri` that differs from the registered one, which
+ * every OAuth provider rejects unless the client is registered as a native app (where loopback
+ * ports are compared port-insensitively).
+ *
+ * @param input - The parse inputs.
+ * @param input.redirectUri - The configured redirect URI.
+ * @param input.port - Optional port override applied to the parsed URI.
+ * @returns The bindable target, or `undefined` when the URI cannot be captured locally.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function parseLoopbackRedirectUri(input: ParseLoopbackRedirectUriInput): Maybe<LoopbackRedirectTarget>;
+export interface StartLoopbackRedirectCaptureInput {
+    /**
+     * The bindable target, from {@link parseLoopbackRedirectUri}.
+     */
+    readonly target: LoopbackRedirectTarget;
+    /**
+     * Text shown in the browser tab once the redirect is captured.
+     */
+    readonly successMessage?: Maybe<string>;
+}
+export interface LoopbackRedirectCapture {
+    /**
+     * The `redirect_uri` the listener is bound to. Send this value in the authorization request.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * The bound port.
+     */
+    readonly port: PortNumber;
+    /**
+     * Resolves with the full redirect URL (query string included) the browser was sent to.
+     *
+     * A provider error redirect resolves rather than rejects — the returned URL carries the `error`
+     * params, which the shared redirect parser already turns into an `AUTH_PROVIDER_ERROR`.
+     *
+     * @param timeoutMs - Optional milliseconds to wait before rejecting with
+     *   {@link LOOPBACK_REDIRECT_TIMEOUT_ERROR_CODE}. Waits indefinitely when omitted.
+     */
+    readonly waitForRedirect: (timeoutMs?: Maybe<number>) => Promise<WebsiteUrl>;
+    /**
+     * Closes the listener and destroys any open sockets, so the CLI's event loop can drain.
+     */
+    readonly close: () => Promise<void>;
+}
+/**
+ * Binds a local HTTP listener to a loopback redirect URI so the authorization code can be read
+ * straight out of the browser redirect instead of being pasted back by hand.
+ *
+ * The listener answers exactly one path — the redirect URI's own — and serves a short "you can close
+ * this tab" page. Everything else is answered `404`, which is what keeps the browser's automatic
+ * `/favicon.ico` request from being mistaken for the redirect.
+ *
+ * @param input - The capture inputs.
+ * @param input.target - The bindable target, from {@link parseLoopbackRedirectUri}.
+ * @param input.successMessage - Optional override for the browser success page's body line.
+ * @returns The started {@link LoopbackRedirectCapture}.
+ * @throws {CliError} `AUTH_REDIRECT_LISTEN_FAILED` when the port cannot be bound.
+ */
+export declare function startLoopbackRedirectCapture(input: StartLoopbackRedirectCaptureInput): Promise<LoopbackRedirectCapture>;

package/src/lib/config/env.d.ts

@@ -1,4 +1,4 @@
-import { type Maybe } from '@dereekb/util';
+import { type Maybe, type OidcClientAuthMethod } from '@dereekb/util';
 import { type CliTokenEntry } from './token.cache';
 /**
  * The default OAuth/OIDC scopes requested by the CLI when none are configured.
@@ -15,7 +15,12 @@ export declare const MODEL_WRITE_OIDC_SCOPES: readonly ["model.create", "model.u
 /**
  * The default redirect URI used by the CLI.
  *
- * Opens up to nothing in the browser so the user can copy/paste the resulting token url back into the CLI.
+ * The `0` port is a placeholder, not a bindable port: the redirect resolves to nothing in the
+ * browser and the user copy/pastes the resulting URL back into the CLI.
+ *
+ * To have `auth login` capture the redirect automatically instead, configure a redirect URI with a
+ * concrete loopback port (e.g. `http://127.0.0.1:8976/callback`) and register that exact URI with
+ * the OAuth client — `auth login` binds it and reads the code straight out of the browser redirect.
  */
 export declare const DEFAULT_CLI_REDIRECT_URI = "http://127.0.0.1:0/callback";
 /**
@@ -193,6 +198,14 @@ export declare function isCliFirebaseConfigComplete(firebase: Maybe<CliFirebaseC
  * @returns `true` when emulators are configured and not explicitly disabled.
  */
 export declare function cliFirebaseEmulatorsInUse(firebase: Maybe<CliFirebaseConfig>): boolean;
+/**
+ * The OAuth client's registered `token_endpoint_auth_method`, as far as the CLI needs to model it.
+ *
+ * Wider than {@link OidcClientAuthMethod} by exactly one member: `'none'`, the public-client case.
+ * That value is meaningless to the protocol layer — a public client sends no credential, so there is
+ * no presentation to choose — but it is precisely what the CLI needs in order to stop asking for one.
+ */
+export type OidcCliTokenEndpointAuthMethod = OidcClientAuthMethod | 'none';
 /**
  * Environment-targeting config for a CLI invocation.
  *
@@ -231,12 +244,30 @@ export interface CliEnvConfig {
     readonly clientId?: string;
     /**
      * The OAuth client secret registered with the target app.
+     *
+     * Absent for a public client — see {@link tokenEndpointAuthMethod}.
      */
     readonly clientSecret?: string;
     /**
-     * The redirect URI registered with the OAuth client. The CLI does not bind a server — it parses
-     * the URL the user pastes back, so this can be any value the OIDC provider accepts as a
-     * registered redirect URI (e.g. `http://127.0.0.1:0/callback` or another loopback/placeholder URL).
+     * How the client authenticates at the token endpoint, mirroring the OAuth client's registered
+     * `token_endpoint_auth_method`.
+     *
+     * `'none'` marks a PUBLIC client: it holds no secret and proves itself with PKCE instead. Recording
+     * it lets `auth setup` skip the client-secret prompt outright rather than asking for a credential
+     * that must not exist — the prompt cannot infer this, since "no secret yet" and "never a secret"
+     * look identical from an empty config.
+     *
+     * Omit to leave it unknown, which keeps the existing prompt-and-accept-empty behaviour.
+     */
+    readonly tokenEndpointAuthMethod?: OidcCliTokenEndpointAuthMethod;
+    /**
+     * The redirect URI registered with the OAuth client.
+     *
+     * When this is an `http:` loopback URI with a concrete, non-zero port (e.g.
+     * `http://127.0.0.1:8976/callback`), `auth login` binds that port and reads the authorization code
+     * straight out of the browser redirect. Any other value — including the
+     * {@link DEFAULT_CLI_REDIRECT_URI} `:0` placeholder and out-of-band URNs — falls back to the user
+     * pasting the redirect URL back into the CLI.
      *
      * Defaults to {@link DEFAULT_CLI_REDIRECT_URI}.
      */
@@ -312,10 +343,15 @@ export declare function applyEnvVarOverrides(input: EnvVarOverrideInput): Maybe<
 /**
  * Returns true when the env has the minimum fields needed to attempt an OAuth login or token refresh.
  *
+ * `clientSecret` is NOT among them. A CLI is a public client in the usual case
+ * (`token_endpoint_auth_method: 'none'`), authenticating with PKCE rather than a secret, so requiring
+ * one here would report a correctly-configured public env as incomplete — and send the caller back to
+ * `auth setup` to supply a credential the provider would then reject.
+ *
  * @param env - The env config to check.
- * @returns `true` when `apiBaseUrl`, `oidcIssuer`, `clientId`, `clientSecret`, and `redirectUri` are all present and non-empty.
+ * @returns `true` when `apiBaseUrl`, `oidcIssuer`, `clientId`, and `redirectUri` are all present and non-empty.
  */
-export declare function isCliEnvConfigComplete(env: Maybe<CliEnvConfig>): env is Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'clientSecret' | 'redirectUri'>> & CliEnvConfig;
+export declare function isCliEnvConfigComplete(env: Maybe<CliEnvConfig>): env is Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'redirectUri'>> & CliEnvConfig;
 /**
  * Inputs to {@link readEnvTokenEntry}.
  */

package/src/lib/config/env.resolve.d.ts

@@ -8,7 +8,7 @@ import { type CliPaths } from './paths';
  * Guarantees that the OIDC client fields are present so callers can pass them through to the
  * OIDC client/token helpers without a non-null assertion or extra runtime check.
  */
-export type CliEnvConfigComplete = Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'clientSecret' | 'redirectUri'>> & CliEnvConfig;
+export type CliEnvConfigComplete = Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'redirectUri'>> & CliEnvConfig;
 /**
  * Builds the conventional `<CLINAME>_ENV` env var name from the CLI binary name.
  *
@@ -71,8 +71,9 @@ export declare function resolveCliEnv(input: ResolveCliEnvInput): Promise<Resolv
 export interface ResolveCliEnvOrThrowInput extends ResolveCliEnvInput {
     /**
      * When `true`, throws `AUTH_ENV_INCOMPLETE` if the resolved env is missing OIDC fields
-     * (apiBaseUrl, oidcIssuer, clientId, clientSecret, redirectUri). The returned env is narrowed
-     * to {@link CliEnvConfigComplete}. Defaults to `false`.
+     * (apiBaseUrl, oidcIssuer, clientId, redirectUri). `clientSecret` is not required — see
+     * {@link isCliEnvConfigComplete}. The returned env is narrowed to {@link CliEnvConfigComplete}.
+     * Defaults to `false`.
      */
     readonly requireComplete?: boolean;
 }

package/src/lib/util/browser.d.ts

@@ -0,0 +1,23 @@
+import { type WebsiteUrl } from '@dereekb/util';
+export interface OpenUrlInBrowserInput {
+    /**
+     * The URL to hand to the platform's default handler.
+     */
+    readonly url: WebsiteUrl;
+}
+/**
+ * Opens a URL in the user's default browser.
+ *
+ * Shells out to the platform's URL handler (`open` on macOS, `start` on Windows, `xdg-open`
+ * elsewhere) rather than taking a dependency for what is a single spawn. The child is detached with
+ * its stdio ignored, so the browser neither holds the CLI's event loop open nor interleaves output
+ * into the CLI's own stdout/stderr.
+ *
+ * Never throws or rejects: a headless machine with no handler registered is an ordinary outcome, and
+ * the caller falls back to the printed URL.
+ *
+ * @param input - The open inputs.
+ * @param input.url - The URL to open.
+ * @returns `true` when the handler process was spawned, `false` when it could not be.
+ */
+export declare function openUrlInBrowser(input: OpenUrlInBrowserInput): Promise<boolean>;

package/src/lib/util/index.d.ts

@@ -1,4 +1,5 @@
 export * from './args';
+export * from './browser';
 export * from './context.slot';
 export * from './handler';
 export * from './interactive';

package/src/lib/util/interactive.d.ts

@@ -1,6 +1,14 @@
 export interface PromptInput {
     readonly question: string;
     readonly mask?: boolean;
+    /**
+     * Optional signal that cancels the prompt, rejecting it with {@link PROMPT_CANCELLED_ERROR_CODE}
+     * and releasing stdin.
+     *
+     * Lets a prompt race another source of the same answer — `auth login` offers the paste prompt
+     * while its loopback listener waits, and aborts the prompt the moment the redirect lands.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * Error code thrown by {@link promptLine} when the user cancels a masked prompt with Ctrl-C.
@@ -16,11 +24,12 @@ export declare const PROMPT_CANCELLED_ERROR_CODE = "PROMPT_CANCELLED";
  * pasted redirect URL.
  *
  * Rejects with a {@link CliError} (`code: 'PROMPT_CANCELLED'`) when the user presses Ctrl-C
- * during a masked prompt, instead of forcibly terminating the process.
+ * during a masked prompt, or when `signal` aborts, instead of forcibly terminating the process.
  *
  * @param input - The prompt inputs.
  * @param input.question - The prompt text written to stdout (or stderr when masking).
  * @param input.mask - When `true`, characters are echoed as `*` and Ctrl-C cancels the prompt.
+ * @param input.signal - Optional signal that cancels the prompt and releases stdin.
  * @returns The line entered by the user (without the trailing newline).
  */
 export declare function promptLine(input: PromptInput): Promise<string>;

package/test/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "14.2.0",
+  "version": "14.3.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.2.0",
-    "@dereekb/dbx-cli": "14.2.0",
-    "@dereekb/firebase": "14.2.0",
-    "@dereekb/firebase-server/test": "14.2.0",
-    "@dereekb/model": "14.2.0",
-    "@dereekb/nestjs": "14.2.0",
-    "@dereekb/rxjs": "14.2.0",
-    "@dereekb/util": "14.2.0",
+    "@dereekb/date": "14.3.0",
+    "@dereekb/dbx-cli": "14.3.0",
+    "@dereekb/firebase": "14.3.0",
+    "@dereekb/firebase-server/test": "14.3.0",
+    "@dereekb/model": "14.3.0",
+    "@dereekb/nestjs": "14.3.0",
+    "@dereekb/rxjs": "14.3.0",
+    "@dereekb/util": "14.3.0",
     "@nestjs/common": "^12.0.1",
     "arktype": "^2.2.0",
     "vitest": "4.1.11",

package/validate/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/dbx-cli/validate",
-  "version": "14.2.0",
+  "version": "14.3.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.2.0",
-    "@dereekb/util": "14.2.0",
+    "@dereekb/dbx-cli": "14.3.0",
+    "@dereekb/util": "14.3.0",
     "ts-morph": "^28.0.0"
   }
 }