@dereekb/firebase-server 14.3.0 → 14.5.0

package/oidc/package.json

@@ -1,22 +1,24 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "14.3.0",
+  "version": "14.5.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.3.0",
-    "@dereekb/date": "14.3.0",
-    "@dereekb/firebase": "14.3.0",
-    "@dereekb/firebase-server": "14.3.0",
-    "@dereekb/model": "14.3.0",
-    "@dereekb/nestjs": "14.3.0",
-    "@dereekb/rxjs": "14.3.0",
-    "@dereekb/util": "14.3.0",
-    "@dereekb/zoho": "14.3.0",
+    "@dereekb/analytics": "14.5.0",
+    "@dereekb/date": "14.5.0",
+    "@dereekb/firebase": "14.5.0",
+    "@dereekb/firebase-server": "14.5.0",
+    "@dereekb/model": "14.5.0",
+    "@dereekb/nestjs": "14.5.0",
+    "@dereekb/oauth-resource": "14.5.0",
+    "@dereekb/rxjs": "14.5.0",
+    "@dereekb/util": "14.5.0",
+    "@dereekb/zoho": "14.5.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "express": "^5.2.1",
     "firebase-admin": "^13.10.0",
+    "jose": "^6.2.12",
     "nanoid": "^6.0.1",
     "oidc-provider": "^9.8.2"
   },

package/oidc/src/lib/controller/index.d.ts

@@ -1,3 +1,6 @@
+export * from './oidc.cli-token.config';
+export * from './oidc.cli-token.service';
+export * from './oidc.cli-token.controller';
 export * from './oidc.interaction.controller';
 export * from './oidc.provider.controller';
 export * from './oidc.wellknown.controller';

package/oidc/src/lib/controller/oidc.cli-token.config.d.ts

@@ -0,0 +1,323 @@
+import { type ISO8601DateString, type Maybe, type PromiseOrValue, type Seconds, type WebsiteUrl } from '@dereekb/util';
+import { type FirebaseAuthUserId, type OidcScope, type OidcScopeTerm } from '@dereekb/firebase';
+import { type FirebaseServerAuthData } from '@dereekb/firebase-server';
+/**
+ * Path (relative to the OIDC issuer) of the CLI-token mint endpoint.
+ *
+ * Under the `oidc` controller prefix the route is `POST /oidc/cli-token`.
+ */
+export declare const CLI_TOKEN_MINT_PATH_PART = "cli-token";
+/**
+ * Path (relative to the OIDC issuer) of the one-time claim redemption endpoint.
+ *
+ * Under the `oidc` controller prefix the route is `POST /oidc/cli-token/claim`.
+ */
+export declare const CLI_TOKEN_CLAIM_PATH_PART = "cli-token/claim";
+/**
+ * Full path of the mint endpoint, as an app must list it in the OIDC module's `protectedPaths`.
+ *
+ * The mint reads `req.auth`, which only the bearer-token middleware populates. Note this is the
+ * MINT path specifically — {@link FIREBASE_SERVER_CLI_TOKEN_CLAIM_PATH} must NOT be protected, since
+ * the claim code IS the credential there and a bearer middleware would 401 the machine redeeming it.
+ *
+ * The OIDC routes are excluded from the global `/api` prefix (see
+ * `FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE`), so the path carries no `/api` prefix.
+ */
+export declare const FIREBASE_SERVER_CLI_TOKEN_API_PROTECTED_PATH = "/oidc/cli-token";
+/**
+ * Full path of the unauthenticated claim endpoint.
+ *
+ * Deliberately a SUFFIX of {@link FIREBASE_SERVER_CLI_TOKEN_API_PROTECTED_PATH}'s prefix, so an app
+ * that protects `/oidc/cli-token` by prefix would also protect this one. The middleware config
+ * therefore has to exclude it — see `OidcAuthMiddlewareConfig.unprotectedPaths`.
+ */
+export declare const FIREBASE_SERVER_CLI_TOKEN_CLAIM_PATH = "/oidc/cli-token/claim";
+/**
+ * Hard ceiling on a minted CLI credential's lifetime, in seconds (one hour).
+ *
+ * NEVER configurable upward: the credential is minted non-interactively by whatever already holds
+ * the session, and the child grant does not cascade-revoke with its parent (see
+ * {@link OidcCliTokenService}), so the short ceiling IS the mitigation.
+ */
+export declare const MAX_CLI_TOKEN_TTL_SECONDS: Seconds;
+/**
+ * Default lifetime requested for a minted CLI credential when the caller asks for none.
+ */
+export declare const DEFAULT_CLI_TOKEN_TTL_SECONDS: Seconds;
+/**
+ * Window a one-time claim code may be redeemed within, in seconds.
+ *
+ * Short by design: the code only has to survive the hop from the minting agent to the machine
+ * running the CLI, which is an immediate copy-paste or an automated follow-up command — not
+ * something a human sits on. The credential it unwraps lives its own (also short) life from the
+ * mint, so this window is purely the exposure of the code in transit and is kept near its floor.
+ */
+export declare const CLI_TOKEN_CLAIM_TTL_SECONDS: Seconds;
+/**
+ * Number of random bytes behind a claim code. 32 bytes base64url-encodes to 43 characters.
+ *
+ * Applies to the opaque-random code form. A JWT-shaped code (see {@link CliTokenMintResult.claimCode})
+ * would size itself from its payload instead, and should spend at least this much entropy on a `jti`.
+ */
+export declare const CLI_TOKEN_CLAIM_CODE_BYTES = 32;
+/**
+ * Scopes a minted CLI credential NEVER inherits, no matter what the minting session holds.
+ *
+ * - `token.cli` — no chaining: a handoff credential must not be able to mint another one.
+ * - `token.service` — no escalation: that scope is the 365-day, non-rotating tier, and a one-hour
+ *   credential must not be able to trade itself up into one.
+ *
+ * Everything else the caller holds (including `session.firestore`) inherits normally — the child is
+ * exactly as privileged as its parent, minus these two.
+ */
+export declare const CLI_TOKEN_DENIED_INHERITED_OIDC_SCOPES: readonly OidcScope[];
+/**
+ * Scope always unioned into a minted credential's grant, so the refresh-token grant is coherent.
+ */
+export declare const CLI_TOKEN_REQUIRED_OIDC_SCOPE: OidcScope;
+/**
+ * The default {@link CliTokenApiModuleConfig.requiredScope}, re-exported for apps that want to widen
+ * it into an OR-group rather than replace it.
+ */
+export declare const DEFAULT_CLI_TOKEN_REQUIRED_OIDC_SCOPE: OidcScopeTerm;
+/**
+ * Signature for the predicate that authorizes a caller to mint a CLI credential.
+ *
+ * Receives the calling request's auth data (`undefined` for an unauthenticated request) and returns
+ * true when that caller may mint. Typically an admin check, e.g.
+ * `(auth) => authRoleClaimsService.toRoles(auth?.token ?? {}).has('admin')`.
+ *
+ * This is the LOAD-BEARING gate — the `token.cli` scope check beside it is defence in depth only,
+ * because a non-OIDC caller carries no `scope` claim and every enforcement site treats that as
+ * "skip". When no predicate is provided the endpoint fails closed for EVERY caller.
+ */
+export type CliTokenAdminPredicate = (auth: Maybe<FirebaseServerAuthData>) => PromiseOrValue<boolean>;
+/**
+ * NestJS injection token for the {@link CliTokenAdminPredicate} provider.
+ */
+export declare const CLI_TOKEN_ADMIN_PREDICATE = "CLI_TOKEN_ADMIN_PREDICATE";
+/**
+ * Resolver form of {@link CliTokenApiModuleConfig.cliClientId}.
+ *
+ * Invoked once per mint rather than read at boot, so an app may discover — or lazily provision — its
+ * CLI client after the DI graph was built. Returning a nullish value leaves the endpoint disabled for
+ * that call, exactly as an empty literal does.
+ *
+ * @returns The CLI client's `client_id`, or nullish when none is available.
+ */
+export type CliTokenClientIdResolver = () => Promise<Maybe<string>> | Maybe<string>;
+/**
+ * Resolves the configured CLI `client_id`, invoking the resolver form when one was supplied.
+ *
+ * Takes the configured VALUE rather than the whole config so it can be exercised — and reused —
+ * without standing up a module config. An empty result is normalized to `undefined`, so a blank
+ * literal disables the endpoint exactly as an absent one does.
+ *
+ * Memoization is deliberately NOT done here: the resolver is invoked once per mint so an app may
+ * provision its CLI client lazily, which means an app that must see a stable id has to memoize its
+ * own resolver (e.g. with `cachedGetter`).
+ *
+ * @param cliClientId - The configured value, in either the literal or the resolver form.
+ * @returns The resolved `client_id`, or `undefined` when the mint is not configured.
+ */
+export declare function resolveCliTokenClientId(cliClientId: Maybe<string | CliTokenClientIdResolver>): Promise<Maybe<string>>;
+/**
+ * Configuration for the CLI-token mint endpoint, supplied by the app via its dependency module.
+ *
+ * Without a config the endpoint is DISABLED: there is no safe default for `cliClientId`, and minting
+ * against the wrong client would hand the CLI a credential its own `client_id` cannot refresh.
+ */
+export declare abstract class CliTokenApiModuleConfig {
+    /**
+     * The registered OAuth `client_id` of the app's CLI client — the same client the CLI's
+     * `auth setup` was configured with.
+     *
+     * REQUIRED. When absent (or unresolvable at the provider) the endpoint is disabled.
+     *
+     * May be a {@link CliTokenClientIdResolver} instead of a literal id, for an app that discovers or
+     * provisions its CLI client at runtime rather than reading a configured value. The resolver is
+     * invoked per mint, so it can return a value that did not exist when the DI graph was built.
+     */
+    readonly cliClientId: string | CliTokenClientIdResolver;
+    /**
+     * OIDC scope term an OIDC caller must hold to mint. Defaults to
+     * {@link DEFAULT_CLI_TOKEN_REQUIRED_OIDC_SCOPE}. Pass `null` to disable scope enforcement entirely
+     * (the admin predicate remains the real gate either way).
+     */
+    readonly requiredScope?: Maybe<Maybe<OidcScopeTerm>>;
+    /**
+     * Lifetime requested for a minted credential when the caller names none. Clamped to
+     * {@link MAX_CLI_TOKEN_TTL_SECONDS}. Defaults to {@link DEFAULT_CLI_TOKEN_TTL_SECONDS}.
+     */
+    readonly defaultTtlSeconds?: Seconds;
+    /**
+     * Whether a claim code may only be redeemed from the same IP that minted it. Defaults to FALSE.
+     *
+     * Defence in depth on top of the code's own controls (unguessable, single-use, short-lived): a code
+     * that leaks out of a transcript is useless from anywhere but the minting host.
+     *
+     * **Off by default because it is incompatible with the feature's primary use case.** A cloud-hosted
+     * agent provisioning a *different* machine mints and redeems from different addresses by
+     * construction, and enforcing a match would make that handoff impossible. Enable it only where the
+     * minting session and the redeeming machine are genuinely the same host.
+     *
+     * Two further limits worth knowing before relying on it. Behind NAT every host on the network shares
+     * one egress address, so the check passes for any of them — it is weakest exactly where several
+     * machines could race for the code. And the claim route is unauthenticated and proxied, so the
+     * observed address is only as trustworthy as the proxy that set `X-Forwarded-For`; where nothing
+     * rewrites that header it is caller-supplied and the binding is decorative.
+     */
+    readonly bindClaimToMintIp?: boolean;
+    /**
+     * The app's API base URL, echoed into the handoff bundle so a machine with no prior `auth setup`
+     * can bootstrap an env from the bundle alone.
+     */
+    readonly apiBaseUrl?: WebsiteUrl;
+    /**
+     * The CLI env name this deployment should be stored under, echoed into the handoff bundle.
+     *
+     * The SERVER is the only party that knows which deployment it is. Without this the redeeming CLI
+     * can only fall back to whatever env is already active locally, which has two bad outcomes: on a
+     * bare machine there is no active env at all and the redeem fails, and on a configured machine a
+     * code minted here can silently repoint an env named for a DIFFERENT deployment at this one.
+     *
+     * Name it after the deployment (`local`, `staging`, `prod`), not after the app.
+     */
+    readonly envName?: string;
+}
+/**
+ * Result of a successful mint. Carries ONLY the one-time claim code — never the refresh token, which
+ * would otherwise land in an MCP transcript and a shell history.
+ */
+export interface CliTokenMintResult {
+    /**
+     * The one-time code to redeem at `POST /oidc/cli-token/claim`.
+     *
+     * OPAQUE to its holder: the CLI passes it back verbatim and reads nothing out of it. Today it is
+     * {@link CLI_TOKEN_CLAIM_CODE_BYTES} random bytes, base64url-encoded — a pointer at the stored
+     * claim, carrying no data of its own.
+     *
+     * It may instead become an encoded (or signed) JWT if the code ever has to carry information the
+     * redeeming machine needs BEFORE it can redeem — an issuer or API base URL it would otherwise have
+     * no way to learn. Nothing downstream assumes the random form: `cliTokenClaimDocumentId` normalizes
+     * the value into a document id, and base64url (which a compact JWS also uses) already satisfies it.
+     *
+     * Two properties must survive such a change. The code has to stay unguessable, so a JWT form must
+     * still carry its own random `jti` rather than being derivable from the mint's inputs; and a failed
+     * redemption must stay undifferentiated, so a self-describing code must not let a caller distinguish
+     * "expired" from "unknown" locally and turn the unauthenticated claim route into an oracle.
+     */
+    readonly claimCode: string;
+    /**
+     * When the CLAIM CODE stops being redeemable.
+     */
+    readonly claimExpiresAt: ISO8601DateString;
+    /**
+     * When the minted CREDENTIAL itself expires — always within {@link MAX_CLI_TOKEN_TTL_SECONDS}.
+     */
+    readonly expiresAt: ISO8601DateString;
+    /**
+     * The space-delimited scopes the minted credential carries.
+     */
+    readonly scope: string;
+}
+/**
+ * The credential bundle handed back by `POST /oidc/cli-token/claim`. Everything a bare machine needs
+ * to create a CLI env and be logged in.
+ */
+export interface CliTokenHandoffBundle {
+    /**
+     * The uid the credential was minted for — the minting caller's own uid.
+     */
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * The OIDC issuer the credential is valid at.
+     */
+    readonly issuer: WebsiteUrl;
+    /**
+     * The app's API base URL, when the app configured one. Lets a machine with no prior `auth setup`
+     * create the env from this bundle alone.
+     */
+    readonly apiBaseUrl?: WebsiteUrl;
+    /**
+     * The CLI env name this deployment should be stored under, when the app configured one via
+     * {@link CliTokenApiModuleConfig.envName}.
+     *
+     * Advisory: an explicit `--env` on the redeeming side still wins. It exists so the rendered
+     * one-line handoff command works on a machine with no config, and so a redeem cannot silently
+     * repoint an env named for another deployment.
+     */
+    readonly envName?: string;
+    /**
+     * The CLI OAuth client the refresh token is bound to. The CLI must present THIS `client_id` when
+     * refreshing — a refresh token is client-bound.
+     */
+    readonly clientId: string;
+    /**
+     * The refresh token itself. The only place it is ever returned.
+     */
+    readonly refreshToken: string;
+    /**
+     * The space-delimited scopes the credential carries.
+     */
+    readonly scope: string;
+    /**
+     * When the credential expires.
+     */
+    readonly expiresAt: ISO8601DateString;
+}
+/**
+ * Inputs to {@link resolveCliTokenScopes}.
+ */
+export interface ResolveCliTokenScopesInput {
+    /**
+     * The scopes the MINTING caller holds. The minted credential can never exceed this set.
+     */
+    readonly callerScopes: Maybe<ReadonlySet<OidcScope>>;
+    /**
+     * An optional subset the caller asked for. May only NARROW `callerScopes` — any scope named here
+     * that the caller does not hold is dropped.
+     */
+    readonly requestedScopes?: Maybe<readonly OidcScope[]>;
+}
+/**
+ * Resolves the scope set a minted CLI credential carries.
+ *
+ * `granted = callerScopes ∩ (requestedSubset ?? callerScopes) − {token.cli, token.service} ∪ {offline_access}`
+ *
+ * The intersection is what makes the mint non-amplifying: the caller may narrow, never widen. The
+ * deny-list is the only asymmetry, and it exists so a one-hour credential cannot manufacture a
+ * longer-lived or further-minting one.
+ *
+ * @param input - The caller's scopes and the optional requested subset.
+ * @returns The space-delimited scope string to grant.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function resolveCliTokenScopes(input: ResolveCliTokenScopesInput): string;
+/**
+ * Inputs to {@link resolveCliTokenTtlSeconds}.
+ */
+export interface ResolveCliTokenTtlSecondsInput {
+    /**
+     * The TTL the caller asked for, if any.
+     */
+    readonly requestedTtlSeconds?: Maybe<Seconds>;
+    /**
+     * The app-configured default, used when the caller asks for none.
+     */
+    readonly defaultTtlSeconds?: Maybe<Seconds>;
+    /**
+     * Seconds of life remaining on the MINTING caller's own grant, when known. A child must never
+     * outlive its parent.
+     */
+    readonly parentRemainingSeconds?: Maybe<Seconds>;
+}
+/**
+ * Resolves a minted credential's lifetime as
+ * `min(requested ?? default, MAX_CLI_TOKEN_TTL_SECONDS, parentRemaining)`, floored at one second.
+ *
+ * @param input - The requested/default TTL and the parent grant's remaining life.
+ * @returns The TTL to mint with, in seconds.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function resolveCliTokenTtlSeconds(input: ResolveCliTokenTtlSecondsInput): Seconds;

package/oidc/src/lib/controller/oidc.cli-token.controller.d.ts

@@ -0,0 +1,45 @@
+import { type Request } from 'express';
+import { type CliTokenHandoffBundle, type CliTokenMintResult } from './oidc.cli-token.config';
+import { type ClaimCliTokenParams, type MintCliTokenParams, OidcCliTokenService } from './oidc.cli-token.service';
+/**
+ * REST controller for the CLI credential handoff.
+ *
+ * Mounted at `oidc`, giving `POST /oidc/cli-token` and `POST /oidc/cli-token/claim`. It lives in
+ * `@dereekb/firebase-server/oidc` rather than beside the session API because minting needs
+ * `OidcService.getProvider()`, which `@dereekb/firebase-server` core does not have.
+ *
+ * **Registration order matters.** `OidcProviderController` also mounts at `oidc` and ends in an
+ * `@All('{*path}')` catch-all that proxies to the oidc-provider callback. Express matches routes in
+ * registration order, so this controller MUST be listed BEFORE `OidcProviderController` in
+ * `oidcModuleMetadata`'s `controllers` array — otherwise both routes are swallowed by the catch-all
+ * and answered by the provider as unknown endpoints.
+ *
+ * Auth on the mint route comes from the global OIDC bearer middleware, so
+ * `FIREBASE_SERVER_CLI_TOKEN_API_PROTECTED_PATH` must be listed in the OIDC module's
+ * `protectedPaths`. The claim route is unauthenticated BY DESIGN — the one-time code is the
+ * credential there — and because protection matches by prefix, the app must also list
+ * `FIREBASE_SERVER_CLI_TOKEN_CLAIM_PATH` in `unprotectedPaths`.
+ */
+export declare class OidcCliTokenController {
+    private readonly cliTokenService;
+    constructor(cliTokenService: OidcCliTokenService);
+    /**
+     * Mints a short-lived CLI credential for the calling user and returns the one-time claim code.
+     *
+     * @param req - The Express request carrying auth credentials on `req.auth`.
+     * @param body - The optional requested scope subset + TTL.
+     * @returns The {@link CliTokenMintResult}. Never the refresh token itself.
+     */
+    mintCliToken(req: Request, body: MintCliTokenParams): Promise<CliTokenMintResult>;
+    /**
+     * Redeems a one-time claim code for the credential bundle it wraps.
+     *
+     * Unauthenticated by design: the machine redeeming the code has no credential yet — obtaining one
+     * is the entire point. Every failure returns the same generic error so the route is not an oracle.
+     *
+     * @param req - The Express request, read only for the caller's address.
+     * @param body - The claim code.
+     * @returns The {@link CliTokenHandoffBundle}.
+     */
+    claimCliToken(req: Request, body: ClaimCliTokenParams): Promise<CliTokenHandoffBundle>;
+}

package/oidc/src/lib/controller/oidc.cli-token.service.d.ts

@@ -0,0 +1,138 @@
+import { type Maybe, type Seconds } from '@dereekb/util';
+import { type OidcScope } from '@dereekb/firebase';
+import { type FirebaseServerAuthData } from '@dereekb/firebase-server';
+import { OidcModuleConfig } from '../oidc.config';
+import { OidcService } from '../service/oidc.service';
+import { OidcEncryptionService } from '../service/oidc.encryption.service';
+import { OidcServerFirestoreCollections } from '../model/model';
+import { type CliTokenAdminPredicate, CliTokenApiModuleConfig, type CliTokenHandoffBundle, type CliTokenMintResult } from './oidc.cli-token.config';
+/**
+ * Error code thrown when the caller is not authorized to mint a CLI credential.
+ */
+export declare const CLI_TOKEN_FORBIDDEN_ERROR_CODE = "CLI_TOKEN_FORBIDDEN_ERROR";
+/**
+ * Error code thrown when the app did not configure a usable CLI client, so minting is disabled.
+ */
+export declare const CLI_TOKEN_DISABLED_ERROR_CODE = "CLI_TOKEN_DISABLED_ERROR";
+/**
+ * Error code returned for EVERY failed claim redemption — not found, expired, and already-consumed
+ * alike. Deliberately undifferentiated so the unauthenticated claim endpoint is not an oracle a
+ * caller can probe for valid codes.
+ */
+export declare const CLI_TOKEN_CLAIM_INVALID_ERROR_CODE = "CLI_TOKEN_CLAIM_INVALID_ERROR";
+/**
+ * Body of `POST /oidc/cli-token`.
+ */
+export interface MintCliTokenParams {
+    /**
+     * An optional subset of the caller's own scopes to grant. May only NARROW — a scope the caller
+     * does not hold is ignored.
+     */
+    readonly scopes?: Maybe<readonly OidcScope[]>;
+    /**
+     * An optional requested lifetime in seconds. Clamped to one hour and to the remaining life of the
+     * caller's own grant.
+     */
+    readonly ttlSeconds?: Maybe<Seconds>;
+}
+/**
+ * Body of `POST /oidc/cli-token/claim`.
+ */
+export interface ClaimCliTokenParams {
+    readonly code: string;
+}
+/**
+ * Per-request context for a mint or claim, carrying what the transport layer observed.
+ */
+export interface CliTokenRequestContext {
+    /**
+     * The calling client's address, as resolved by the controller.
+     */
+    readonly requestIp?: Maybe<string>;
+}
+/**
+ * Mints a short-lived CLI login credential for the caller, and redeems the one-time claim code that
+ * carries it.
+ *
+ * ## Security
+ *
+ * Gates apply in this order, mirroring `FirestoreSessionApiService`:
+ *
+ * 1. `auth?.uid` present, else unauthenticated.
+ * 2. The app-supplied {@link CliTokenAdminPredicate} — the load-bearing check. **Fails closed** when
+ *    the app provides no predicate.
+ * 3. The `token.cli` OIDC scope — defence in depth only. It cannot stand alone: a non-OIDC caller
+ *    carries no `scope` claim and every enforcement site treats that as "skip".
+ * 4. A configured, provider-resolvable CLI `client_id`, else the endpoint is disabled.
+ *
+ * The minted credential is never MORE privileged than the session that minted it: its scopes are the
+ * caller's own, minus `token.cli` / `token.service` (see {@link resolveCliTokenScopes}), and its TTL
+ * is capped at one hour AND at the remaining life of the caller's own grant.
+ *
+ * ## Accepted limitation — no revocation cascade
+ *
+ * A refresh token is CLIENT-BOUND: oidc-provider's `validateGrant` requires
+ * `grant.clientId === client.clientId`, so the parent grant (owned by the MCP client) cannot be
+ * reused for the CLI client and a **separate** Grant must be created. Revoking the parent session
+ * therefore does NOT cascade to the minted credential. The ≤1h cap is the mitigation; `auth logout
+ * --revoke` and the `deleteOidcToken` callModel action are the manual kill switches.
+ *
+ * Rotation is deliberately left ON (the scope is NOT added to `nonRotatingScopes`): the CLI client is
+ * a public PKCE client, so oidc-provider rotates the refresh token on every exchange and its reuse
+ * detection kills the whole grant if a stolen copy is replayed. That is why the credential must land
+ * in the CLI's PERSISTED token cache rather than the non-persisting `fromEnv` path.
+ */
+export declare class OidcCliTokenService {
+    private readonly oidcService;
+    private readonly oidcModuleConfig;
+    private readonly encryptionService;
+    private readonly collections;
+    private readonly config?;
+    private readonly adminPredicate?;
+    private readonly _logger;
+    constructor(oidcService: OidcService, oidcModuleConfig: OidcModuleConfig, encryptionService: OidcEncryptionService, collections: OidcServerFirestoreCollections, config?: CliTokenApiModuleConfig | undefined, adminPredicate?: CliTokenAdminPredicate | undefined);
+    /**
+     * Mints a CLI credential for the calling user and returns the one-time claim code that unwraps it.
+     *
+     * @param auth - The authenticated request's auth data (`req.auth`).
+     * @param params - The optional requested scope subset + TTL.
+     * @returns The claim code and the minted credential's metadata. The refresh token itself is NOT returned.
+     * @throws {HttpsError} `401` with no uid, `403` when a gate rejects the caller, `400` when minting is disabled.
+     */
+    mintCliToken(auth: Maybe<FirebaseServerAuthData>, params: MintCliTokenParams, context?: CliTokenRequestContext): Promise<CliTokenMintResult>;
+    /**
+     * Redeems a one-time claim code, consuming it inside a Firestore transaction so a double-redeem
+     * loses the race rather than handing out the same credential twice.
+     *
+     * @param params - The claim code to redeem.
+     * @returns The handoff bundle: everything a bare machine needs to be logged in.
+     * @throws {HttpsError} A `404` with the SAME generic error for a missing, expired, or already-consumed code.
+     */
+    claimCliToken(params: ClaimCliTokenParams, context?: CliTokenRequestContext): Promise<CliTokenHandoffBundle>;
+    private _storeClaim;
+    private _claimInvalidError;
+}
+/**
+ * Generates a high-entropy, URL-safe one-time claim code.
+ *
+ * @returns A base64url-encoded random string of {@link CLI_TOKEN_CLAIM_CODE_BYTES} bytes.
+ */
+export declare function generateCliTokenClaimCode(): string;
+/**
+ * Prefix of the `oidcEntry` document id a pending CLI-token claim is stored under.
+ *
+ * Namespaced so a claim can never collide with an oidc-provider adapter entry, which keys documents
+ * by the provider's own token/grant ids.
+ */
+export declare const CLI_TOKEN_CLAIM_DOCUMENT_ID_PREFIX = "cli-token-claim-";
+/**
+ * Builds the `oidcEntry` document id for a claim code.
+ *
+ * The code IS the lookup key — there is no query — so a redeem is a single point read and a wrong
+ * code is indistinguishable from an expired one.
+ *
+ * @param code - The one-time claim code.
+ * @returns The namespaced document id.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliTokenClaimDocumentId(code: string): string;

package/oidc/src/lib/controller/oidc.interaction.controller.d.ts

@@ -69,6 +69,36 @@ export declare class OidcInteractionController {
      */
     private _verifyIdToken;
 }
+/**
+ * Inputs to {@link withheldGatedScopesForClient}.
+ */
+export interface WithheldGatedScopesForClientInput {
+    /**
+     * Every scope the authorization request named.
+     */
+    readonly requestedScopes: ReadonlySet<string>;
+    /**
+     * Every scope referenced by ANY provider profile — the "gated" set.
+     */
+    readonly profileGatedScopes: ReadonlySet<string>;
+    /**
+     * The scopes THIS client's resolved profiles unlock.
+     */
+    readonly clientUnlockedScopes: ReadonlySet<string>;
+}
+/**
+ * The requested scopes that are provider-profile gated and NOT unlocked by this client's profiles —
+ * the set a consent must withhold from the user and drop from the grant.
+ *
+ * A gated scope is not necessarily unavailable: one unlocked by a DEFAULT profile is reachable by
+ * every client, which `clientUnlockedScopes` already accounts for (it is resolved through
+ * `oidcClientProviderProfileScopes`, whose fallback is the registry's default profiles).
+ *
+ * @param input - The requested, gated, and client-unlocked scope sets.
+ * @returns The requested scopes to withhold, in request order.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function withheldGatedScopesForClient(input: WithheldGatedScopesForClientInput): string[];
 /**
  * Inputs for {@link resolveEffectiveSubset}.
  */
@@ -91,6 +121,12 @@ export interface ResolveEffectiveSubsetInput {
      * `reconsiderRejectedValues` — or it can never be granted on that Grant.
      */
     readonly alreadyEncountered?: readonly string[];
+    /**
+     * Entries to withhold from the grant no matter what else applies. Subtracted LAST, so a withheld
+     * entry lands in `rejected` even when the caller explicitly named it or an `alwaysGranted` rule
+     * would otherwise have added it. Withholding can only ever subtract, never widen a grant.
+     */
+    readonly withheld?: readonly string[];
 }
 /**
  * Resolves the effective set to grant — and the complementary set to
@@ -107,6 +143,8 @@ export interface ResolveEffectiveSubsetInput {
  *   entry so oidc-provider does not re-prompt for them. Values in `alreadyEncountered` pass validation but
  *   are not re-applied to the grant (no-op).
  * - Always-granted entries are union'd into `granted` (clamped to `missing`).
+ * - Withheld entries are subtracted last, so they end up in `rejected` even when the caller named
+ *   them or an always-granted rule would otherwise have added them.
  *
  * @param input - Missing entries plus optional subset, always-granted, and already-encountered lists.
  * @returns `granted` to add to the grant and `rejected` to record on the grant.

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

@@ -3,5 +3,6 @@ export * from './model';
 export * from './oidc.config';
 export * from './controller';
 export * from './oidc.module';
+export * from './oidc.resource-server';
 export * from './profile';
 export * from './service';

package/oidc/src/lib/middleware/oauth-auth.module.d.ts

@@ -33,6 +33,14 @@ export declare abstract class OidcAuthMiddlewareConfig {
      * since those are protected by AppCheck.
      */
     readonly protectedPaths: SlashPath[];
+    /**
+     * Path prefixes excluded from verification, checked BEFORE {@link protectedPaths}.
+     *
+     * Needed because protection matches by prefix: a deliberately-public sub-route of a protected
+     * prefix (e.g. `/oidc/cli-token/claim` under `/oidc/cli-token`) would otherwise be 401'd for
+     * exactly the callers it exists for.
+     */
+    readonly unprotectedPaths?: SlashPath[];
     /**
      * Absolute URL of the OAuth 2.0 Protected Resource Metadata document
      * (RFC 9728). When set, included as the `resource_metadata` parameter
@@ -52,6 +60,9 @@ export declare abstract class OidcAuthMiddlewareConfig {
  * included as the RFC 9728 `resource_metadata` hint so clients can locate the
  * discovery doc directly instead of relying on origin-rooted path-walkback.
  *
+ * Delegates to `@dereekb/oauth-resource`'s builder so the challenge an off-box resource server
+ * emits and the one this API emits are produced by the same code.
+ *
  * @param error - The RFC 6750 `error` token (e.g. `invalid_token`, `invalid_request`).
  * @param resourceMetadataUrl - Optional protected-resource metadata URL.
  * @returns Header value, e.g. `Bearer resource_metadata="…", error="invalid_token"`.

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

@@ -367,6 +367,15 @@ export declare abstract class OidcModuleConfig {
      * since those are typically protected by AppCheck.
      */
     readonly protectedPaths?: SlashPath[];
+    /**
+     * Path prefixes EXCLUDED from bearer verification, checked before {@link protectedPaths}.
+     *
+     * Protection matches by prefix, so a public sub-route of a protected prefix is otherwise
+     * unreachable: `POST /oidc/cli-token/claim` is deliberately unauthenticated (the one-time claim
+     * code IS the credential there), yet it sits under the protected `/oidc/cli-token` prefix. Listing
+     * it here is what keeps it reachable.
+     */
+    readonly unprotectedPaths?: SlashPath[];
     /**
      * Map of recognized OAuth resource indicator URLs (RFC 8707) to their
      * {@link OidcResourceServerInfo}. When non-empty, oidc-provider's