@dereekb/firebase 13.12.4 → 13.12.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.12.4",
+  "version": "13.12.6",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -24,10 +24,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.12.4",
-    "@dereekb/model": "13.12.4",
-    "@dereekb/rxjs": "13.12.4",
-    "@dereekb/util": "13.12.4",
+    "@dereekb/date": "13.12.6",
+    "@dereekb/model": "13.12.6",
+    "@dereekb/rxjs": "13.12.6",
+    "@dereekb/util": "13.12.6",
     "@firebase/rules-unit-testing": "5.0.0",
     "@marcbachmann/cel-js": "^7.6.1",
     "@typescript-eslint/parser": "8.59.3",

package/src/lib/client/error/error.d.ts

@@ -9,6 +9,12 @@ import { type FirebaseError } from 'firebase/app';
  * @param error - The value to check.
  * @returns `true` if the input matches the shape of a client-side `FirebaseError`
  *
+ * @dbxUtil
+ * @dbxUtilCategory firebase-error
+ * @dbxUtilKind function
+ * @dbxUtilTags firebase, client, error, type-guard, callable
+ * @dbxUtilRelated convert-https-callable-error-to-readable-error, firebase-server-error
+ *
  * @example
  * ```ts
  * try {

package/src/lib/client/function/error.d.ts

@@ -10,6 +10,12 @@ import { type FirebaseError } from 'firebase/app';
  * Typically created via {@link convertHttpsCallableErrorToReadableError} when an `HttpsCallable`
  * invocation fails with a server-side error that includes structured details.
  *
+ * @dbxUtil
+ * @dbxUtilCategory firebase-error
+ * @dbxUtilKind class
+ * @dbxUtilTags firebase, https, callable, error, server-error, client, response, details
+ * @dbxUtilRelated convert-https-callable-error-to-readable-error, is-client-firebase-error
+ *
  * @example
  * ```ts
  * try {

package/src/lib/client/function/function.callable.d.ts

@@ -71,5 +71,11 @@ export declare function directDataHttpsCallable<I, O, C extends HttpsCallable<I,
  *
  * @param error - The caught error from an `HttpsCallable` invocation.
  * @returns A {@link FirebaseServerError} if the error has structured details, or a generic readable error otherwise.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory firebase-error
+ * @dbxUtilKind function
+ * @dbxUtilTags firebase, https, callable, error, decode, convert, readable, client, server
+ * @dbxUtilRelated firebase-server-error, is-client-firebase-error, firebase-auth-error-to-readable-error
  */
 export declare function convertHttpsCallableErrorToReadableError(error: unknown): unknown;

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

@@ -96,6 +96,65 @@ export type FirebaseAuthOobCode = string;
  * Password used for completing setup or resetting a user.
  */
 export type FirebaseAuthSetupPassword = PasswordString;
+/**
+ * Delimiter used when encoding a {@link FirebaseAuthOobCodeDataPair} into a {@link FirebaseAuthOobCode}.
+ *
+ * The encoded form is `${code}-${uid}` and splitting happens on the first delimiter occurrence,
+ * so this only requires that the generated code/password not contain `-`. The uid is unrestricted
+ * and may itself contain `-`.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory firebase-auth
+ * @dbxUtilTags firebase, auth, oob, code, delimiter, constant
+ * @dbxUtilRelated encode-firebase-auth-oob-code, decode-firebase-auth-oob-code
+ */
+export declare const FIREBASE_AUTH_OOB_CODE_DATA_PAIR_DELIMITER = "-";
+/**
+ * Data pair embedded in a {@link FirebaseAuthOobCode} for out-of-band auth flows.
+ *
+ * Pairs the Firebase user uid with the one-time setup/reset code so the server can
+ * identify the user and validate the code in a single round-trip without a
+ * separate lookup step.
+ */
+export interface FirebaseAuthOobCodeDataPair {
+    readonly uid: FirebaseAuthUserId;
+    readonly code: FirebaseAuthSetupPassword;
+}
+/**
+ * Encodes a {@link FirebaseAuthOobCodeDataPair} into a URL-safe {@link FirebaseAuthOobCode}.
+ *
+ * The encoded form is `${code}-${uid}` — code first so that splitting on the first delimiter
+ * still works even when the uid itself contains `-` (Firebase uids occasionally do).
+ *
+ * @dbxUtil
+ * @dbxUtilCategory firebase-auth
+ * @dbxUtilTags firebase, auth, oob, code, encode, uid, password, reset, setup, serialize
+ * @dbxUtilRelated decode-firebase-auth-oob-code, firebase-auth-oob-code-data-pair-delimiter
+ *
+ * @example
+ * ```ts
+ * encodeFirebaseAuthOobCode({ uid: 'abc-123', code: 'xyz789' });  // 'xyz789-abc-123'
+ * ```
+ */
+export declare function encodeFirebaseAuthOobCode(pair: FirebaseAuthOobCodeDataPair): FirebaseAuthOobCode;
+/**
+ * Decodes a {@link FirebaseAuthOobCode} back into its {@link FirebaseAuthOobCodeDataPair}.
+ *
+ * Splits on the first `-` so uids containing additional `-` characters survive the round-trip
+ * intact. Returns null when the input is missing the delimiter or has empty parts.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory firebase-auth
+ * @dbxUtilTags firebase, auth, oob, code, decode, parse, uid, password, reset, setup, deserialize
+ * @dbxUtilRelated encode-firebase-auth-oob-code, firebase-auth-oob-code-data-pair-delimiter
+ *
+ * @example
+ * ```ts
+ * decodeFirebaseAuthOobCode('xyz789-abc-123');  // { uid: 'abc-123', code: 'xyz789' }
+ * decodeFirebaseAuthOobCode('invalid');         // null
+ * ```
+ */
+export declare function decodeFirebaseAuthOobCode(oobCode: FirebaseAuthOobCode): Maybe<FirebaseAuthOobCodeDataPair>;
 export declare const FIREBASE_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY = "setupPassword";
 export declare const FIREBASE_SERVER_AUTH_CLAIMS_SETUP_LAST_COM_DATE_KEY = "setupCommunicationAt";
 /**

package/src/lib/common/auth/auth.error.d.ts

@@ -64,6 +64,12 @@ export declare const FIREBASE_AUTH_QUOTA_EXCEEDED_ERROR = "auth/quota-exceeded";
  * @param inputError - The Firebase Auth error to convert.
  * @returns A {@link ReadableError} with a human-readable message suitable for display.
  *
+ * @dbxUtil
+ * @dbxUtilCategory firebase-auth
+ * @dbxUtilKind function
+ * @dbxUtilTags firebase, auth, error, readable, convert, decode, message, login, signin
+ * @dbxUtilRelated convert-https-callable-error-to-readable-error, firebase-server-error
+ *
  * @example
  * ```ts
  * try {

package/src/lib/model/oidcmodel/oidcmodel.interaction.d.ts

@@ -44,27 +44,114 @@ export type OidcScopeDetails<T extends OidcScope = OidcScope> = LabeledValueWith
  */
 export type OidcRedirectUri = string;
 /**
- * Supported values for `token_endpoint_auth_method` when creating an OIDC client.
+ * The `client_secret_basic` confidential-client auth method (RFC 6749 §2.3.1, the
+ * OAuth 2.0 default): the client sends its `client_id` and `client_secret` in the
+ * `Authorization: Basic` header on token-endpoint requests. Standard pick for
+ * server-side confidential clients.
  *
- * The four `client_secret_*` / `private_key_jwt` methods are for confidential clients.
+ * @example
+ * ```ts
+ * await oidcClientService.createClient({
+ *   token_endpoint_auth_method: CLIENT_SECRET_BASIC_TOKEN_ENDPOINT_AUTH_METHOD,
+ *   // ...
+ * });
+ * ```
+ */
+export declare const CLIENT_SECRET_BASIC_TOKEN_ENDPOINT_AUTH_METHOD = "client_secret_basic";
+/**
+ * The `client_secret_post` confidential-client auth method (RFC 6749 §2.3.1, the
+ * form-body variant): the client sends `client_id` and `client_secret` as form-encoded
+ * parameters in the token-endpoint request body. Equivalent in security to
+ * {@link CLIENT_SECRET_BASIC_TOKEN_ENDPOINT_AUTH_METHOD}; pick it for clients that
+ * cannot set the `Authorization` header (some older HTTP stacks).
  *
- * `'none'` designates a public client: it holds no secret and authenticates the
- * `authorization_code` flow with PKCE alone. This is the canonical pattern for clients
- * that cannot keep a secret (native apps, SPAs, CLIs) and is what the MCP / Claude
- * connector ecosystem (claude.ai connector, Claude Code CLI, mcp-inspector via DCR)
- * expects. oidc-provider enforces PKCE on the `authorization_code` flow for every
- * client regardless of auth method, so all clients get PKCE; `'none'` simply unlocks
- * the secret-less variant.
+ * @example
+ * ```ts
+ * await oidcClientService.createClient({
+ *   token_endpoint_auth_method: CLIENT_SECRET_POST_TOKEN_ENDPOINT_AUTH_METHOD,
+ *   // ...
+ * });
+ * ```
  */
-export type OidcTokenEndpointAuthMethod = 'client_secret_basic' | 'client_secret_post' | 'client_secret_jwt' | 'private_key_jwt' | 'none';
-export declare const PRIVATE_KEY_JWT_TOKEN_ENDPOINT_AUTH_METHOD: OidcTokenEndpointAuthMethod;
+export declare const CLIENT_SECRET_POST_TOKEN_ENDPOINT_AUTH_METHOD = "client_secret_post";
 /**
- * The public-client auth method (`'none'`): no client secret, PKCE-only.
+ * The `client_secret_jwt` confidential-client auth method (OIDC Core §9): the client
+ * signs a JWT client assertion using its `client_secret` as the HMAC key (HS256/HS384/HS512)
+ * and sends it as `client_assertion` on token-endpoint requests. The secret never goes on
+ * the wire — only the signed assertion — which is the upgrade over the plain
+ * `client_secret_*` methods, without requiring asymmetric keys like
+ * {@link PRIVATE_KEY_JWT_TOKEN_ENDPOINT_AUTH_METHOD}.
  *
- * Mirrors {@link PRIVATE_KEY_JWT_TOKEN_ENDPOINT_AUTH_METHOD}. Use this when provisioning
- * public OAuth clients that cannot keep a secret.
+ * @example
+ * ```ts
+ * await oidcClientService.createClient({
+ *   token_endpoint_auth_method: CLIENT_SECRET_JWT_TOKEN_ENDPOINT_AUTH_METHOD,
+ *   // ...
+ * });
+ * ```
+ */
+export declare const CLIENT_SECRET_JWT_TOKEN_ENDPOINT_AUTH_METHOD = "client_secret_jwt";
+/**
+ * The `private_key_jwt` confidential-client auth method (OIDC Core §9): the client signs
+ * a JWT client assertion with its private key (RS256/ES256/PS256) and sends it as
+ * `client_assertion`; the server verifies via the client's published `jwks` / `jwks_uri`.
+ * Strongest of the confidential-client methods — no shared secret is ever held by the
+ * server — and the canonical pick for high-trust server-to-server integrations.
+ *
+ * @example
+ * ```ts
+ * await oidcClientService.createClient({
+ *   token_endpoint_auth_method: PRIVATE_KEY_JWT_TOKEN_ENDPOINT_AUTH_METHOD,
+ *   jwks: { keys: [publicJwk] },
+ *   // ...
+ * });
+ * ```
+ */
+export declare const PRIVATE_KEY_JWT_TOKEN_ENDPOINT_AUTH_METHOD = "private_key_jwt";
+/**
+ * The public-client auth method (`'none'`): no client secret, PKCE-only. The client
+ * authenticates the `authorization_code` flow with PKCE (RFC 7636) alone — there is no
+ * shared secret and no client assertion. Canonical pick for clients that cannot keep a
+ * secret (native apps, SPAs, CLIs) and what the MCP / Claude connector ecosystem
+ * (claude.ai connector, Claude Code CLI, mcp-inspector via DCR) registers as.
+ *
+ * Mirrors {@link PRIVATE_KEY_JWT_TOKEN_ENDPOINT_AUTH_METHOD}. `oidc-provider` still
+ * enforces PKCE on the `authorization_code` flow for every client regardless of auth
+ * method, so `'none'` simply unlocks the secret-less variant rather than disabling any
+ * client authentication.
+ *
+ * @example
+ * ```ts
+ * await oidcClientService.createClient({
+ *   token_endpoint_auth_method: PUBLIC_PKCE_TOKEN_ENDPOINT_AUTH_METHOD,
+ *   // no client_secret — public PKCE client
+ *   // ...
+ * });
+ * ```
+ */
+export declare const PUBLIC_PKCE_TOKEN_ENDPOINT_AUTH_METHOD = "none";
+/**
+ * Supported values for `token_endpoint_auth_method` when creating an OIDC client.
+ * Derived as the union of each `*_TOKEN_ENDPOINT_AUTH_METHOD` literal const so the
+ * type and the constants stay in lock-step — add a new const and it auto-joins
+ * the union.
+ *
+ * The four `client_secret_*` / `private_key_jwt` methods are for confidential clients:
+ * - {@link CLIENT_SECRET_BASIC_TOKEN_ENDPOINT_AUTH_METHOD}
+ * - {@link CLIENT_SECRET_POST_TOKEN_ENDPOINT_AUTH_METHOD}
+ * - {@link CLIENT_SECRET_JWT_TOKEN_ENDPOINT_AUTH_METHOD}
+ * - {@link PRIVATE_KEY_JWT_TOKEN_ENDPOINT_AUTH_METHOD}
+ *
+ * {@link PUBLIC_PKCE_TOKEN_ENDPOINT_AUTH_METHOD} (`'none'`) designates a public
+ * client: it holds no secret and authenticates the `authorization_code` flow with
+ * PKCE alone. This is the canonical pattern for clients that cannot keep a secret
+ * (native apps, SPAs, CLIs) and is what the MCP / Claude connector ecosystem
+ * (claude.ai connector, Claude Code CLI, mcp-inspector via DCR) expects.
+ * oidc-provider enforces PKCE on the `authorization_code` flow for every client
+ * regardless of auth method, so all clients get PKCE; `'none'` simply unlocks
+ * the secret-less variant.
  */
-export declare const PUBLIC_PKCE_TOKEN_ENDPOINT_AUTH_METHOD: OidcTokenEndpointAuthMethod;
+export type OidcTokenEndpointAuthMethod = typeof CLIENT_SECRET_BASIC_TOKEN_ENDPOINT_AUTH_METHOD | typeof CLIENT_SECRET_POST_TOKEN_ENDPOINT_AUTH_METHOD | typeof CLIENT_SECRET_JWT_TOKEN_ENDPOINT_AUTH_METHOD | typeof PRIVATE_KEY_JWT_TOKEN_ENDPOINT_AUTH_METHOD | typeof PUBLIC_PKCE_TOKEN_ENDPOINT_AUTH_METHOD;
 /**
  * All available token endpoint auth method options with display labels.
  */

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.12.4",
+  "version": "13.12.6",
   "peerDependencies": {
-    "@dereekb/date": "13.12.4",
-    "@dereekb/firebase": "13.12.4",
-    "@dereekb/model": "13.12.4",
-    "@dereekb/rxjs": "13.12.4",
-    "@dereekb/util": "13.12.4",
+    "@dereekb/date": "13.12.6",
+    "@dereekb/firebase": "13.12.6",
+    "@dereekb/model": "13.12.6",
+    "@dereekb/rxjs": "13.12.6",
+    "@dereekb/util": "13.12.6",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",