feat: add basic fpnv

entrypoints.json

@@ -16,6 +16,10 @@
     "typings": "./lib/auth/index.d.ts",
     "dist": "./lib/auth/index.js"
   },
+  "firebase-admin/fpnv": {
+    "typings": "./lib/fpnv/index.d.ts",
+    "dist": "./lib/fpnv/index.js"
+  },
   "firebase-admin/database": {
     "typings": "./lib/database/index.d.ts",
     "dist": "./lib/database/index.js"

etc/firebase-admin.fpnv.api.md

@@ -0,0 +1,37 @@
+## API Report File for "firebase-admin.fpnv"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { Agent } from 'http';
+
+// @public
+export class Fpnv {
+    // Warning: (ae-forgotten-export) The symbol "App" needs to be exported by the entry point index.d.ts
+    get app(): App;
+    // Warning: (ae-forgotten-export) The symbol "FirebasePhoneNumberTokenVerifier" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    protected readonly fpnvVerifier: FirebasePhoneNumberTokenVerifier;
+    // (undocumented)
+    verifyToken(fpnvJwt: string): Promise<FpnvToken>;
+}
+
+// @public
+export interface FpnvToken {
+    [key: string]: any;
+    aud: string[];
+    exp: number;
+    getPhoneNumber(): string;
+    iat: number;
+    iss: string;
+    jti: string;
+    nonce: string;
+    sub: string;
+}
+
+// @public
+export function getFirebasePnv(app?: App): Fpnv;
+
+```

package.json

@@ -73,6 +73,9 @@
       "auth": [
         "lib/auth"
       ],
+      "fpnv": [
+        "lib/fpnv"
+      ],
       "eventarc": [
         "lib/eventarc"
       ],
@@ -134,6 +137,11 @@
       "require": "./lib/auth/index.js",
       "import": "./lib/esm/auth/index.js"
     },
+    "./fpnv": {
+      "types": "./lib/fpnv/index.d.ts",
+      "require": "./lib/fpnv/index.js",
+      "import": "./lib/esm/fpnv/index.js"
+    },
     "./database": {
       "types": "./lib/database/index.d.ts",
       "require": "./lib/database/index.js",

src/fpnv/fpnv-api-client-internal.ts

@@ -0,0 +1,71 @@
+/*!
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { PrefixedFirebaseError } from '../utils/error';
+
+export interface FirebasePhoneNumberTokenInfo {
+  /** Documentation URL. */
+  url: string;
+  /** verify API name. */
+  verifyApiName: string;
+  /** The JWT full name. */
+  jwtName: string;
+  /** The JWT short name. */
+  shortName: string;
+  /** The JWT typ" (Type) */
+  typ: string;
+}
+
+export const CLIENT_CERT_URL = 'https://www.googleapis.com/robot/v1/metadata/x509/[email protected]';
+
+export const PN_TOKEN_INFO: FirebasePhoneNumberTokenInfo = {
+  url: 'https://firebase.google.com/docs/phone-number-verification',
+  verifyApiName: 'verifyToken()',
+  jwtName: 'Firebase Phone Verification token',
+  shortName: 'FPNV token',
+  typ: 'JWT',
+};
+
+export const FPNV_ERROR_CODE_MAPPING = {
+  INVALID_ARGUMENT: 'invalid-argument',
+  INVALID_TOKEN: 'invalid-token',
+  EXPIRED_TOKEN: 'expired-token',
+} satisfies Record<string, FpnvErrorCode>;
+
+export type FpnvErrorCode =
+  | 'invalid-argument'
+  | 'invalid-token'
+  | 'expired-token'
+
+/**
+ * Firebase Phone Number Verification error code structure. This extends `PrefixedFirebaseError`.
+ *
+ * @param code - The error code.
+ * @param message - The error message.
+ * @constructor
+ */
+export class FirebaseFpnvError extends PrefixedFirebaseError {
+  constructor(code: FpnvErrorCode, message: string) {
+    super('fpnv', code, message);
+
+    /* tslint:disable:max-line-length */
+    // Set the prototype explicitly. See the following link for more details:
+    // https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes#extending-built-ins-like-error-array-and-map-may-no-longer-work
+    /* tslint:enable:max-line-length */
+    (this as any).__proto__ = FirebaseFpnvError.prototype;
+  }
+}

src/fpnv/fpnv-api.ts

@@ -0,0 +1,80 @@
+/*!
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+/**
+ * Interface representing a Fpnv token.
+ */
+export interface FpnvToken {
+    /**
+     * The issuer identifier for the issuer of the response.
+     * This value is a URL with the format
+     * `https://firebaseappcheck.googleapis.com/<PROJECT_NUMBER>`, where `<PROJECT_NUMBER>` is the
+     * same project number specified in the {@link FpnvToken.aud} property.
+     */
+    iss: string;
+
+    /**
+     * The audience for which this token is intended.
+     * This value is a JSON array of two strings, the first is the project number of your
+     * Firebase project, and the second is the project ID of the same project.
+     */
+    aud: string[];
+
+    /**
+     * The Fpnv token's expiration time, in seconds since the Unix epoch. That is, the
+     * time at which this Fpnv token expires and should no longer be considered valid.
+     */
+    exp: number;
+
+    /**
+     * The Fpnv token's issued-at time, in seconds since the Unix epoch. That is, the
+     * time at which this Fpnv token was issued and should start to be considered
+     * valid.
+     */
+    iat: number;
+
+    /**
+     * The phone number of User.
+     */
+    sub: string;
+
+    /**
+     * Unique ID.
+     */
+    jti: string;
+
+    /**
+     * Unique ID.
+     */
+    nonce: string;
+
+    /**
+     * The corresponding user's phone number.
+     * This value is not actually one of the JWT token claims. It is added as a
+     * convenience, and is set as the value of the {@link FpnvToken.sub} property.
+     */
+    getPhoneNumber(): string;
+
+    /**
+     * Other arbitrary claims included in the token.
+     */
+    [key: string]: any;
+}
+
+export { FpnvErrorCode, FirebaseFpnvError } from './fpnv-api-client-internal';
+

src/fpnv/fpnv.ts

@@ -0,0 +1,58 @@
+/*!
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { App } from '../app';
+import { FpnvToken } from './fpnv-api';
+import { FirebasePhoneNumberTokenVerifier } from './token-verifier';
+import { CLIENT_CERT_URL, PN_TOKEN_INFO } from './fpnv-api-client-internal';
+
+/**
+ * Fpnv service bound to the provided app.
+ */
+export class Fpnv {
+  private readonly appInternal: App;
+  protected readonly fpnvVerifier: FirebasePhoneNumberTokenVerifier;
+
+  /**
+   * @param app - The app for this `Fpnv` service.
+   * @constructor
+   * @internal
+   */
+  constructor(app: App) {
+
+    this.appInternal = app;
+    this.fpnvVerifier = new FirebasePhoneNumberTokenVerifier(
+      CLIENT_CERT_URL,
+      'https://fpnv.googleapis.com/projects/',
+      PN_TOKEN_INFO,
+      app
+    );
+  }
+
+  /**
+   * Returns the app associated with this `Fpnv` instance.
+   *
+   * @returns The app associated with this `Fpnv` instance.
+   */
+  get app(): App {
+    return this.appInternal;
+  }
+
+  public async verifyToken(fpnvJwt: string): Promise<FpnvToken> {
+    return await this.fpnvVerifier.verifyJWT(fpnvJwt);
+  }
+}

src/fpnv/index.ts

@@ -0,0 +1,64 @@
+/**
+ * Firebase Phone Number Verification.
+ *
+ * @packageDocumentation
+ */
+
+/*!
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { App, getApp } from '../app';
+import { FirebaseApp } from '../app/firebase-app';
+import { Fpnv } from './fpnv';
+
+export {
+  Fpnv
+} from './fpnv';
+
+export {
+  FpnvToken,
+} from './fpnv-api'
+
+/**
+ * Gets the {@link Fpnv} service for the default app or a
+ * given app.
+ *
+ * `getFirebasePnv()` can be called with no arguments to access the default app's
+ * {@link Fpnv} service or as `getFirebasePnv(app)` to access the
+ * {@link Fpnv} service associated with a specific app.
+ *
+ * @example
+ * ```javascript
+ * // Get the Fpnv service for the default app
+ * const defaultFpnv = getFirebasePnv();
+ * ```
+ *
+ * @example
+ * ```javascript
+ * // Get the Fpnv service for a given app
+ * const otherFpnv = getFirebasePnv(otherApp);
+ * ```
+ *
+ */
+export function getFirebasePnv(app?: App): Fpnv {
+  if (typeof app === 'undefined') {
+    app = getApp();
+  }
+
+  const firebaseApp: FirebaseApp = app as FirebaseApp;
+  return firebaseApp.getOrInitService('fpnv', (app) => new Fpnv(app));
+}