feat: add FPNV

pom.xml

@@ -446,6 +446,11 @@
             <artifactId>httpclient5</artifactId>
             <version>5.3.1</version>
         </dependency>
+        <dependency>
+            <groupId>com.nimbusds</groupId>
+            <artifactId>nimbus-jose-jwt</artifactId>
+            <version>10.6</version>
+        </dependency>
 
         <!-- Test Dependencies -->
         <dependency>

src/main/java/com/google/firebase/fpnv/FirebasePnv.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2026 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.
+ */
+
+package com.google.firebase.fpnv;
+
+import com.google.firebase.FirebaseApp;
+import com.google.firebase.ImplFirebaseTrampolines;
+import com.google.firebase.fpnv.internal.FirebasePnvTokenVerifier;
+import com.google.firebase.internal.FirebaseService;
+
+/**
+ * This class is the entry point for the Firebase Phone Number Verification (FPNV) service.
+ *
+ * <p>You can get an instance of {@link FirebasePnv} via {@link #getInstance()},
+ * or {@link #getInstance(FirebaseApp)} and then use it.
+ */
+public final class FirebasePnv {
+  private static final String SERVICE_ID = FirebasePnv.class.getName();
+  private final FirebasePnvTokenVerifier tokenVerifier;
+
+  private FirebasePnv(FirebaseApp app) {
+    this.tokenVerifier = new FirebasePnvTokenVerifier(app);
+  }
+
+  /**
+   * Gets the {@link FirebasePnv} instance for the default {@link FirebaseApp}.
+   *
+   * @return The {@link FirebasePnv} instance for the default {@link FirebaseApp}.
+   */
+  public static FirebasePnv getInstance() {
+    return getInstance(FirebaseApp.getInstance());
+  }
+
+  /**
+   * Gets the {@link FirebasePnv} instance for the specified {@link FirebaseApp}.
+   *
+   * @return The {@link FirebasePnv} instance for the specified {@link FirebaseApp}.
+   */
+  public static synchronized FirebasePnv getInstance(FirebaseApp app) {
+    FirebaseFpnvService service = ImplFirebaseTrampolines.getService(app, SERVICE_ID,
+        FirebaseFpnvService.class);
+    if (service == null) {
+      service = ImplFirebaseTrampolines.addService(app, new FirebaseFpnvService(app));
+    }
+    return service.getInstance();
+  }
+
+  /**
+   * Verifies a Firebase Phone Number Verification token (FPNV JWT).
+   *
+   * @param fpnvJwt The FPNV JWT string to verify.
+   * @return A verified {@link FirebasePnvToken}.
+   * @throws FirebasePnvException If verification fails.
+   */
+  public FirebasePnvToken verifyToken(String fpnvJwt) throws FirebasePnvException {
+    return this.tokenVerifier.verifyToken(fpnvJwt);
+  }
+
+  private static class FirebaseFpnvService extends FirebaseService<FirebasePnv> {
+    FirebaseFpnvService(FirebaseApp app) {
+      super(SERVICE_ID, new FirebasePnv(app));
+    }
+  }
+}
+
+
+
+
+

src/main/java/com/google/firebase/fpnv/FirebasePnvErrorCode.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2026 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.
+ */
+
+package com.google.firebase.fpnv;
+
+/**
+ * Error codes that are used in {@link FirebasePnv}.
+ */
+public enum FirebasePnvErrorCode {
+  INVALID_ARGUMENT,
+  INVALID_TOKEN,
+  TOKEN_EXPIRED,
+  INTERNAL_ERROR,
+  SERVICE_ERROR,
+}

src/main/java/com/google/firebase/fpnv/FirebasePnvException.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2026 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.
+ */
+
+package com.google.firebase.fpnv;
+
+import com.google.firebase.ErrorCode;
+import com.google.firebase.FirebaseException;
+
+/**
+ * Generic exception related to Firebase Phone Number Verification.
+ * Check the error code and message for more
+ * details.
+ */
+public class FirebasePnvException extends FirebaseException {
+  private final FirebasePnvErrorCode errorCode;
+
+  /**
+   * Exception that created from {@link FirebasePnvErrorCode},
+   * {@link String} message and {@link Throwable} cause.
+   *
+   * @param errorCode {@link FirebasePnvErrorCode}
+   * @param message {@link String}
+   * @param cause {@link Throwable}
+   */
+  public FirebasePnvException(
+      FirebasePnvErrorCode errorCode,
+      String message,
+      Throwable cause
+  ) {
+    super(mapToFirebaseError(errorCode), message, cause);
+    this.errorCode = errorCode;
+  }
+
+  /**
+   * Exception that created from {@link FirebasePnvErrorCode} and {@link String} message.
+   *
+   * @param errorCode {@link FirebasePnvErrorCode}
+   * @param message {@link String}
+   */
+  public FirebasePnvException(
+      FirebasePnvErrorCode errorCode,
+      String message
+  ) {
+    this(errorCode, message, null);
+  }
+
+  public FirebasePnvErrorCode getFpnvErrorCode() {
+    return errorCode;
+  }
+
+  private static ErrorCode mapToFirebaseError(FirebasePnvErrorCode code) {
+    if (code == null) {
+      return ErrorCode.INTERNAL;
+    }
+    switch (code) {
+      case INVALID_ARGUMENT:
+        return ErrorCode.INVALID_ARGUMENT;
+      case TOKEN_EXPIRED:
+      case INVALID_TOKEN:
+        return ErrorCode.UNAUTHENTICATED;
+      case SERVICE_ERROR:
+        return ErrorCode.UNAVAILABLE;
+      case INTERNAL_ERROR:
+      default:
+        return ErrorCode.INTERNAL;
+    }
+  }
+}
+

src/main/java/com/google/firebase/fpnv/FirebasePnvToken.java

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2026 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.
+ */
+
+package com.google.firebase.fpnv;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableMap;
+import com.nimbusds.jwt.JWTClaimsSet;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Represents a verified Firebase Phone Number Verification token.
+ */
+public class FirebasePnvToken {
+  private final Map<String, Object> claims;
+
+  /**
+   * Create an instance of {@link FirebasePnvToken} from a map of JWT claims.
+   *
+   * @param claims A map of JWT claims.
+   */
+  public FirebasePnvToken(Map<String, Object> claims) {
+    checkArgument(claims != null && claims.containsKey("sub"),
+        "Claims map must at least contain sub");
+    this.claims = ImmutableMap.copyOf(claims);
+  }
+
+  /**
+   * Returns the issuer identifier for the issuer of the response.
+   */
+  public String getIssuer() {
+    return (String) claims.get("iss");
+  }
+
+  /**
+   * Returns the phone number of the user.
+   * This corresponds to the 'sub' claim in the JWT.
+   */
+  public String getPhoneNumber() {
+    return (String) claims.get("sub");
+  }
+
+  /**
+   * Returns the audience for which this token is intended.
+   */
+  public List<String> getAudience() {
+    Object audience = claims.get("aud");
+    if (audience instanceof String) {
+      return ImmutableList.of((String) audience);
+    } else if (audience instanceof List) {
+      // The nimbus-jose-jwt library should provide a List<String>, but we copy it
+      // to an immutable list for safety and to prevent modification.
+      @SuppressWarnings("unchecked")
+      List<String> audienceList = (List<String>) audience;
+      return ImmutableList.copyOf(audienceList);
+    }
+    return ImmutableList.of();
+  }
+
+  /**
+   * Returns the expiration time in seconds since the Unix epoch.
+   */
+  public long getExpirationTime() {
+    return ((java.util.Date) claims.get("exp")).getTime() / 1000L;
+  }
+
+  /**
+   * Returns the issued-at time in seconds since the Unix epoch.
+   */
+  public long getIssuedAt() {
+    return ((java.util.Date) claims.get("iat")).getTime() / 1000L;
+  }
+
+  /**
+   * Returns the entire map of claims.
+   */
+  public Map<String, Object> getClaims() {
+    return claims;
+  }
+}