@dereekb/dbx-cli 13.12.9 → 13.13.0

package/lint-cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-lint-cache",
-  "version": "13.12.9",
+  "version": "13.13.0",
   "private": true,
   "type": "module",
   "devDependencies": {
@@ -8,7 +8,7 @@
     "eslint": "10.4.0"
   },
   "peerDependencies": {
-    "@dereekb/util": "13.12.9",
+    "@dereekb/util": "13.13.0",
     "yargs": "^18.0.0"
   }
 }

package/manifest-extract/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "13.12.9",
+  "version": "13.13.0",
   "sideEffects": false,
   "peerDependencies": {
     "ts-morph": "^21.0.0"
   },
   "devDependencies": {
-    "@dereekb/firebase": "13.12.9"
+    "@dereekb/firebase": "13.13.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "13.12.9",
+  "version": "13.13.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -41,11 +41,11 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.12.9",
-    "@dereekb/firebase": "13.12.9",
-    "@dereekb/model": "13.12.9",
-    "@dereekb/nestjs": "13.12.9",
-    "@dereekb/util": "13.12.9",
+    "@dereekb/date": "13.13.0",
+    "@dereekb/firebase": "13.13.0",
+    "@dereekb/model": "13.13.0",
+    "@dereekb/nestjs": "13.13.0",
+    "@dereekb/util": "13.13.0",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "jiti": "2.6.1",

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

@@ -1,3 +1,4 @@
+import { type Maybe } from '@dereekb/util';
 /**
  * The subset of fields we read from an OIDC discovery document.
  *
@@ -137,3 +138,37 @@ export interface FetchUserInfoInput {
  * @returns The parsed userinfo claims. Throws a {@link CliError} (`USERINFO_FAILED`) on a non-OK response.
  */
 export declare function fetchUserInfo(input: FetchUserInfoInput): Promise<Record<string, unknown>>;
+/**
+ * Session lifetime metadata returned by the `GET /oidc/session` route.
+ */
+export interface OidcSessionInfo {
+    readonly sub?: string;
+    readonly scope?: Maybe<string>;
+    /**
+     * Grant (session) expiry as unix epoch SECONDS, or `null` when the provider could not resolve it.
+     */
+    readonly expiresAt?: Maybe<number>;
+    /**
+     * Whether refresh-token rotation is disabled for this grant (a long-lived service token).
+     */
+    readonly rotationDisabled?: boolean;
+}
+export interface FetchSessionInfoInput {
+    /**
+     * The `GET /oidc/session` endpoint URL (typically `<oidcIssuer>/session`).
+     */
+    readonly sessionEndpoint: string;
+    readonly accessToken: string;
+}
+/**
+ * Fetches the dbx-components `GET /oidc/session` route and returns the parsed session lifetime metadata.
+ *
+ * Mirrors {@link fetchUserInfo}, but reads the access token's baked-in session-lifetime claims
+ * (`dbx_session_expires_at` / `dbx_rotation_disabled`) which userinfo does not echo.
+ *
+ * @param input - The session request.
+ * @param input.sessionEndpoint - The `GET /oidc/session` endpoint URL.
+ * @param input.accessToken - The Bearer access token sent in the `Authorization` header.
+ * @returns The parsed {@link OidcSessionInfo}. Throws a {@link CliError} (`SESSION_INFO_FAILED`) on a non-OK response.
+ */
+export declare function fetchSessionInfo(input: FetchSessionInfoInput): Promise<OidcSessionInfo>;

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

@@ -1,4 +1,5 @@
 import { type Maybe } from '@dereekb/util';
+import { type CliTokenEntry } from './token.cache';
 /**
  * The default OAuth/OIDC scopes requested by the CLI when none are configured.
  */
@@ -17,6 +18,15 @@ export declare const MODEL_WRITE_OIDC_SCOPES: readonly ["model.create", "model.u
  * Opens up to nothing in the browser so the user can copy/paste the resulting token url back into the CLI.
  */
 export declare const DEFAULT_CLI_REDIRECT_URI = "http://127.0.0.1:0/callback";
+/**
+ * The generic OIDC scopes a `--service-token` login adds to the requested set.
+ *
+ * `token.service` triggers the admin-only, long-lived, non-rotating behavior server-side;
+ * `offline_access` is required so a refresh token is issued (the durable credential the server env
+ * consumes). The app's own resource scope (e.g. `demo`) is intentionally NOT included here — it
+ * already lives in the configured `env.scopes`, keeping this generic CLI app-agnostic.
+ */
+export declare const SERVICE_TOKEN_REQUIRED_OIDC_SCOPES: readonly ["token.service", "offline_access"];
 /**
  * Returns the input scope string with the `model.create`, `model.update`, and `model.delete`
  * scopes removed, preserving every other scope (including `model.read` and `model.query`).
@@ -28,6 +38,17 @@ export declare const DEFAULT_CLI_REDIRECT_URI = "http://127.0.0.1:0/callback";
  * @returns The filtered space-separated scope list.
  */
 export declare function filterReadOnlyModelScopes(scopes: Maybe<string>): string;
+/**
+ * Returns the input scope string with the {@link SERVICE_TOKEN_REQUIRED_OIDC_SCOPES} unioned in
+ * (de-duplicated), preserving every other already-requested scope.
+ *
+ * Drives the `auth login --service-token` flag. Combinable with `filterReadOnlyModelScopes` — apply
+ * the read-only filter first, then this, so a service token can still be read-only.
+ *
+ * @param scopes - Space-separated scope list, or `undefined` to augment the default scopes.
+ * @returns The augmented space-separated scope list.
+ */
+export declare function withServiceTokenScopes(scopes: Maybe<string>): string;
 /**
  * A built-in env config preset shipped with a CLI app.
  *
@@ -189,3 +210,27 @@ export declare function applyEnvVarOverrides(input: EnvVarOverrideInput): Maybe<
  * @returns `true` when `apiBaseUrl`, `oidcIssuer`, `clientId`, `clientSecret`, 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;
+/**
+ * Inputs to {@link readEnvTokenEntry}.
+ */
+export interface ReadEnvTokenEntryInput {
+    readonly cliName: string;
+}
+/**
+ * Reads an OAuth token entry from environment variables, for non-interactive server consumption.
+ *
+ * Reads `<PREFIX>_REFRESH_TOKEN` (required) plus the optional `<PREFIX>_ACCESS_TOKEN` and
+ * `<PREFIX>_TOKEN_SCOPE`, where `PREFIX = cliName.replaceAll('-', '_').toUpperCase()` (the existing
+ * env-var prefix convention). The intended credential is a long-lived, non-rotating service token
+ * (see `auth login --service-token`).
+ *
+ * Returns `undefined` when no refresh token is present. When only a refresh token is supplied, the
+ * returned entry has `accessToken: ''` and `expiresAt: 0` so the first use is forced to mint an
+ * access token via a refresh. The entry is flagged `fromEnv: true` so the middleware does not write
+ * it back to the on-disk cache.
+ *
+ * @param input - The lookup inputs.
+ * @param input.cliName - The CLI name used to derive the env-var prefix (e.g. `demo-cli` → `DEMO_CLI`).
+ * @returns The env-sourced {@link CliTokenEntry}, or `undefined` when no refresh token is set.
+ */
+export declare function readEnvTokenEntry(input: ReadEnvTokenEntryInput): Maybe<CliTokenEntry>;

package/src/lib/config/token.cache.d.ts

@@ -12,6 +12,23 @@ export interface CliTokenEntry {
     readonly tokenType?: string;
     readonly scope?: string;
     readonly idToken?: string;
+    /**
+     * Unix epoch SECONDS at which the underlying grant (session) expires, as reported by the OIDC
+     * `GET /oidc/session` route (`dbx_session_expires_at`). Distinct from {@link expiresAt}, which is
+     * the short-lived access token's expiry in milliseconds. Used to surface the session lifetime.
+     */
+    readonly sessionExpiresAt?: number;
+    /**
+     * Whether refresh-token rotation is disabled for this grant (a long-lived service token).
+     * Sourced from the `GET /oidc/session` route (`dbx_rotation_disabled`).
+     */
+    readonly rotationDisabled?: boolean;
+    /**
+     * Transient (never persisted) marker that this entry was sourced from environment variables rather
+     * than the on-disk cache. Env-sourced entries are not written back after a refresh — see the auth
+     * middleware. Set by `readEnvTokenEntry`.
+     */
+    readonly fromEnv?: boolean;
 }
 /**
  * Token cache shape on disk — keyed by env name.

package/test/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "13.12.9",
+  "version": "13.13.0",
   "peerDependencies": {
-    "@dereekb/date": "13.12.9",
-    "@dereekb/dbx-cli": "13.12.9",
-    "@dereekb/firebase": "13.12.9",
-    "@dereekb/firebase-server/test": "13.12.9",
-    "@dereekb/model": "13.12.9",
-    "@dereekb/nestjs": "13.12.9",
-    "@dereekb/rxjs": "13.12.9",
-    "@dereekb/util": "13.12.9",
+    "@dereekb/date": "13.13.0",
+    "@dereekb/dbx-cli": "13.13.0",
+    "@dereekb/firebase": "13.13.0",
+    "@dereekb/firebase-server/test": "13.13.0",
+    "@dereekb/model": "13.13.0",
+    "@dereekb/nestjs": "13.13.0",
+    "@dereekb/rxjs": "13.13.0",
+    "@dereekb/util": "13.13.0",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "vitest": "4.1.5",