@pagopa/io-react-native-wallet 0.12.0 → 0.13.0

package/src/credential/issuance/03-start-user-authorization.ts

@@ -1,24 +1,54 @@
-import * as z from "zod";
-import uuid from "react-native-uuid";
-import { AuthorizationDetail, makeParRequest } from "../../utils/par";
 import type { CryptoContext } from "@pagopa/io-react-native-jwt";
-import { getJwtFromFormPost } from "../../utils/decoder";
-import { hasStatus, type Out } from "../../utils/misc";
-import type { StartFlow } from "./01-start-flow";
+import type { ResponseMode } from "./types";
+import {
+  generateRandomAlphaNumericString,
+  type Out,
+} from "../../../src/utils/misc";
+
 import type { EvaluateIssuerTrust } from "./02-evaluate-issuer-trust";
+import type { StartFlow } from "./01-start-flow";
+import { AuthorizationDetail, makeParRequest } from "../../../src/utils/par";
 import { ASSERTION_TYPE } from "./const";
 
+export type StartUserAuthorization = (
+  issuerConf: Out<EvaluateIssuerTrust>["issuerConf"],
+  credentialType: Out<StartFlow>["credentialType"],
+  context: {
+    wiaCryptoContext: CryptoContext;
+    walletInstanceAttestation: string;
+    redirectUri: string;
+    appFetch?: GlobalFetch["fetch"];
+  }
+) => Promise<{
+  issuerRequestUri: string;
+  clientId: string;
+  codeVerifier: string;
+  credentialDefinition: AuthorizationDetail;
+}>;
+
+/**
+ * Ensures that the credential type requested is supported by the issuer and contained in the
+ * issuer configuration.
+ * @param issuerConf The issuer configuration returned by {@link evaluateIssuerTrust}
+ * @param credentialType The type of the credential to be requested returned by {@link startFlow}
+ * @param context.wiaCryptoContext The Wallet Instance's crypto context
+ * @param context.walletInstanceAttestation The Wallet Instance's attestation
+ * @param context.redirectUri The redirect URI which is the custom URL scheme that the Wallet Instance is registered to handle
+ * @param context.appFetch (optional) fetch api implementation. Default: built-in fetch
+ * @returns The credential definition to be used in the request which includes the format and the type and its type
+ */
 const selectCredentialDefinition = (
   issuerConf: Out<EvaluateIssuerTrust>["issuerConf"],
   credentialType: Out<StartFlow>["credentialType"]
 ): AuthorizationDetail => {
-  const { credentials_supported } = issuerConf.openid_credential_issuer;
+  const credential_configurations_supported =
+    issuerConf.openid_credential_issuer.credential_configurations_supported;
 
-  const [result] = credentials_supported
-    .filter((e) => e.credential_definition.type.includes(credentialType))
+  const [result] = Object.keys(credential_configurations_supported)
+    .filter((e) => e.includes(credentialType))
     .map((e) => ({
-      credential_definition: { type: credentialType },
-      format: e.format,
+      credential_configuration_id: credentialType,
+      format: credential_configurations_supported[e]!.format,
       type: "openid_credential" as const,
     }));
 
@@ -28,69 +58,46 @@ const selectCredentialDefinition = (
   return result;
 };
 
-const decodeAuthorizationResponse = async (
-  raw: string
-): Promise<{ request_uri: string }> => {
-  const {
-    decodedJwt: { payload },
-  } = await getJwtFromFormPost(raw);
-
-  /**
-   * FIXME: [SIW-628] This step must not make any difference on the credential
-   * we are authorizing for, being a PID or any other (Q)EAA.
-   *
-   * Currently, PID issuer is implemented to skip the CompleteUserAuthorization step
-   * thus returning a stubbed (code, state) pair.
-   *
-   * This is a workaround to proceeed the flow anyway.
-   * If the response does not map what expected (CorrectShape),
-   * we try parse into (code, state) to check if we are in the PID scenario.
-   * In that case, a stub value is returned (will not be evaluated anyway).
-   *
-   * This workaround will be obsolete once the PID issuer fixes its implementation
-   */
-  const CorrectShape = z.object({ request_uri: z.string() });
-  const WrongShapeForPID = z.object({ code: z.string(), state: z.string() });
+/**
+ * Ensures that the response mode requested is supported by the issuer and contained in the issuer configuration.
+ * @param issuerConf The issuer configuration
+ * @param credentialType The type of the credential to be requested
+ * @returns The response mode to be used in the request, "query" for PersonIdentificationData and "form_post.jwt" for all other types.
+ */
+const selectResponseMode = (
+  issuerConf: Out<EvaluateIssuerTrust>["issuerConf"],
+  credentialType: Out<StartFlow>["credentialType"]
+): ResponseMode => {
+  const responseModeSupported =
+    issuerConf.oauth_authorization_server.response_modes_supported;
 
-  const [correct, wrong] = [
-    CorrectShape.safeParse(payload),
-    WrongShapeForPID.safeParse(payload),
-  ];
+  const responseMode =
+    credentialType === "PersonIdentificationData" ? "query" : "form_post.jwt";
 
-  if (correct.success) {
-    return correct.data;
-  } else if (wrong.success) {
-    return { request_uri: "https://fake-request-uri" };
+  if (!responseModeSupported.includes(responseMode)) {
+    throw new Error(`No response mode support the type '${credentialType}'`);
   }
-  throw correct.error;
-};
 
-export type StartUserAuthorization = (
-  issuerConf: Out<EvaluateIssuerTrust>["issuerConf"],
-  credentialType: Out<StartFlow>["credentialType"],
-  context: {
-    wiaCryptoContext: CryptoContext;
-    walletInstanceAttestation: string;
-    walletProviderBaseUrl: string;
-    additionalParams?: Record<string, string>;
-    appFetch?: GlobalFetch["fetch"];
-  }
-) => Promise<{ requestUri: string; clientId: string }>;
+  return responseMode;
+};
 
 /**
- * Start the User authorization phase.
- * Perform the Pushed Authorization Request as defined in OAuth 2.0 protocol.
- *
- * @param issuerConf The Issuer configuration
- * @param credentialType The type of the credential to be requested
- * @param context.wiaCryptoContext The context to access the key associated with the Wallet Instance Attestation
- * @param context.walletInstanceAttestation The Wallet Instance Attestation token
- * @param context.walletProviderBaseUrl The base url of the Wallet Provider
- * @param context.additionalParams Hash set of parameters to be passed to the authorization endpoint
- * (used as a temporary fix until we have a proper User identity in the PID token provider)
- * TODO: [SIW-630]
- * @param context.appFetch (optional) fetch api implementation. Default: built-in fetch
- * @returns The request uri to continue the authorization to
+ * WARNING: This function must be called after {@link evaluateIssuerTrust} and {@link startFlow}. The next steam is {@link compeUserAuthorizationWithQueryMode} or {@link compeUserAuthorizationWithFormPostJwtMode}
+ * Creates and sends a PAR request to the /as/par endpoint of the authroization server.
+ * This starts the authentication flow to obtain an access token.
+ * This token enables the Wallet Instance to request a digital credential from the Credential Endpoint of the Credential Issuer.
+ * This is an HTTP POST request containing the Wallet Instance identifier (client id), the code challenge and challenge method as specified by PKCE according to RFC 9126
+ * along with the WTE and its proof of possession (WTE-PoP).
+ * Additionally, it includes a request object, which is a signed JWT encapsulating the type of digital credential requested (authorization_details),
+ * the application session identifier on the Wallet Instance side (state),
+ * the method (query or form_post.jwt) by which the Authorization Server
+ * should transmit the Authorization Response containing the authorization code issued upon the end user's authentication (response_mode)
+ * to the Wallet Instance's Token Endpoint to obtain the Access Token, and the redirect_uri of the Wallet Instance where the Authorization Response
+ * should be delivered. The redirect is achived by using a custom URL scheme that the Wallet Instance is registered to handle.
+ * @param issuerConf The issuer configuration
+ * @param credentialType The type of the credential to be requested returned by {@link selectCredentialDefinition}
+ * @param ctx The context object containing the Wallet Instance's cryptographic context, the Wallet Instance's attestation, the redirect URI and the fetch implementation
+ * @returns The URI to which the end user should be redirected to start the authentication flow, along with the client id, the code verifier and the credential definition
  */
 export const startUserAuthorization: StartUserAuthorization = async (
   issuerConf,
@@ -100,39 +107,31 @@ export const startUserAuthorization: StartUserAuthorization = async (
   const {
     wiaCryptoContext,
     walletInstanceAttestation,
-    walletProviderBaseUrl,
-    additionalParams = {},
+    redirectUri,
     appFetch = fetch,
   } = ctx;
+
   const clientId = await wiaCryptoContext.getPublicKey().then((_) => _.kid);
-  const codeVerifier = `${uuid.v4()}`;
-  // Make a PAR request to the credential issuer and return the response url
-  const parUrl =
-    issuerConf.openid_credential_issuer.pushed_authorization_request_endpoint;
+  const codeVerifier = generateRandomAlphaNumericString(64);
+  const parEndpoint =
+    issuerConf.oauth_authorization_server.pushed_authorization_request_endpoint;
+  const credentialDefinition = selectCredentialDefinition(
+    issuerConf,
+    credentialType
+  );
+  const responseMode = selectResponseMode(issuerConf, credentialType);
+
   const getPar = makeParRequest({ wiaCryptoContext, appFetch });
   const issuerRequestUri = await getPar(
     clientId,
     codeVerifier,
-    walletProviderBaseUrl,
-    parUrl,
+    redirectUri,
+    responseMode,
+    parEndpoint,
     walletInstanceAttestation,
-    [selectCredentialDefinition(issuerConf, credentialType)],
+    [credentialDefinition],
     ASSERTION_TYPE
   );
 
-  // Initialize authorization by requesting the authz request uri
-  const authzRequestEndpoint =
-    issuerConf.openid_credential_issuer.authorization_endpoint;
-  const params = new URLSearchParams({
-    client_id: clientId,
-    request_uri: issuerRequestUri,
-    ...additionalParams,
-  });
-
-  const { request_uri } = await appFetch(`${authzRequestEndpoint}?${params}`)
-    .then(hasStatus(200))
-    .then((res) => res.text())
-    .then(decodeAuthorizationResponse);
-
-  return { requestUri: request_uri, clientId };
+  return { issuerRequestUri, clientId, codeVerifier, credentialDefinition };
 };

package/src/credential/issuance/04-complete-user-authorization.ts

@@ -1,17 +1,118 @@
-import type { Out } from "../../utils/misc";
+import {
+  AuthorizationErrorShape,
+  AuthorizationResultShape,
+  type AuthorizationContext,
+  type AuthorizationResult,
+} from "../../../src/utils/auth";
+import { until, type Out } from "../../utils/misc";
 import type { StartUserAuthorization } from "./03-start-user-authorization";
+import parseUrl from "parse-url";
+import { AuthorizationError, AuthorizationIdpError } from "../../utils/errors";
+import type { EvaluateIssuerTrust } from "./02-evaluate-issuer-trust";
+import { Linking } from "react-native";
 
 /**
- * The interface of the phase to complete User authorization.
- * It may be implemented as a Credential presentation
- * or with a strong User identification
- *
- * @param requestUri The url to reach to complete the user authorization.
- * @param cliendId Identifies the current client across all the requests of the issuing flow
- *
- * @returns the access code to use to request the credental
+ * The interface of the phase to complete User authorization via strong identification when the response mode is "query" and the request credential is a PersonIdentificationData.
  */
-export type CompleteUserAuthorization = (
-  requestUri: Out<StartUserAuthorization>["requestUri"],
-  clientId: Out<StartUserAuthorization>["clientId"]
-) => Promise<{ code: string }>;
+export type CompleteUserAuthorizationWithQueryMode = (
+  issuerRequestUri: Out<StartUserAuthorization>["issuerRequestUri"],
+  clientId: Out<StartUserAuthorization>["clientId"],
+  issuerConf: Out<EvaluateIssuerTrust>["issuerConf"],
+  idpHint: string,
+  redirectUri: string,
+  authorizationContext?: AuthorizationContext
+) => Promise<AuthorizationResult>;
+
+/**
+ * WARNING: This function must be called after {@link startUserAuthorization}. The next function to be called is {@link authorizeAccess}.
+ * The interface of the phase to complete User authorization via strong identification when the response mode is "query" and the request credential is a PersonIdentificationData.
+ * It is used to complete the user authorization by catching the redirectSchema from the authorization server which then contains the authorization response.
+ * This function utilizes the authorization context to open an in-app browser capable of catching the redirectSchema to perform a get request to the authorization endpoint.
+ * If the 302 redirect happens and the redirectSchema is caught, the function will return the authorization response after parsing it from the query string.
+ * @param issuerRequestUri the URI of the issuer where the request is sent
+ * @param clientId Identifies the current client across all the requests of the issuing flow returned by {@link startUserAuthorization}
+ * @param issuerConf The issuer configuration returned by {@link evaluateIssuerTrust}
+ * @param authorizationContext The context to identify the user which will be used to start the authorization. It's needed only when requesting a PersonalIdentificationData credential. The implementantion should open an in-app browser capable of catching the redirectSchema.
+ * If not specified, the default browser is used
+ * @param idphint Unique identifier of the SPID IDP selected by the user
+ * @param redirectUri The url to reach to complete the user authorization which is the custom URL scheme that the Wallet Instance is registered to handle, usually a custom URL or deeplink
+ * @throws {AuthorizationError} if an error occurs during the authorization process
+ * @throws {AuthorizationIdpError} if an error occurs during the authorization process and the error is related to the IDP
+ * @returns the authorization response which contains code, state and iss
+ */
+export const completeUserAuthorizationWithQueryMode: CompleteUserAuthorizationWithQueryMode =
+  async (
+    issuerRequestUri,
+    clientId,
+    issuerConf,
+    idpHint,
+    redirectUri,
+    authorizationContext
+  ) => {
+    /**
+     * Starts the authorization flow which dependes on the response mode and the request credential.
+     * If the response mode is "query" the authorization flow is handled differently via the authorization context which opens an in-app browser capable of catching the redirectSchema.
+     * The form_post.jwt mode is not currently supported.
+     */
+    const authzRequestEndpoint =
+      issuerConf.oauth_authorization_server.authorization_endpoint;
+    const params = new URLSearchParams({
+      client_id: clientId,
+      request_uri: issuerRequestUri,
+      idphint: idpHint,
+    });
+    const authUrl = `${authzRequestEndpoint}?${params}`;
+    var authRedirectUrl: string | undefined;
+
+    if (authorizationContext) {
+      const redirectSchema = new URL(redirectUri).protocol.replace(":", "");
+      authRedirectUrl = await authorizationContext
+        .authorize(authUrl, redirectSchema)
+        .catch((e) => {
+          throw new AuthorizationError(e.message);
+        });
+    } else {
+      // handler for redirectUri
+      Linking.addEventListener("url", ({ url }) => {
+        if (url.includes(redirectUri)) {
+          authRedirectUrl = url;
+        }
+      });
+
+      const openAuthUrlInBrowser = Linking.openURL(authUrl);
+
+      /*
+       * Waits for 120 seconds for the identificationRedirectUrl variable to be set
+       * by the custom url handler. If the timeout is exceeded, throw an exception
+       */
+      const unitAuthRedirectIsNotUndefined = until(
+        () => authRedirectUrl !== undefined,
+        120
+      );
+
+      await Promise.all([openAuthUrlInBrowser, unitAuthRedirectIsNotUndefined]);
+
+      if (authRedirectUrl === undefined) {
+        throw new AuthorizationError("Invalid authentication redirect url");
+      }
+    }
+
+    const urlParse = parseUrl(authRedirectUrl);
+    const authRes = AuthorizationResultShape.safeParse(urlParse.query);
+    if (!authRes.success) {
+      const authErr = AuthorizationErrorShape.safeParse(urlParse.query);
+      if (!authErr.success) {
+        throw new AuthorizationError(authRes.error.message); // an error occured while parsing the result and the error
+      }
+      throw new AuthorizationIdpError(
+        authErr.data.error,
+        authErr.data.error_description
+      );
+    }
+    return authRes.data;
+  };
+
+// TODO: SIW-1120 implement generic credential issuance flow
+export const completeUserAuthorizationWithFormPostJwtMode = () => {
+  throw new Error("Not implemented");
+};

package/src/credential/issuance/05-authorize-access.ts

@@ -1,92 +1,117 @@
-import uuid from "react-native-uuid";
-import { withEphemeralKey } from "../../utils/crypto";
-import { createDPopToken } from "../../utils/dpop";
-import type { StartUserAuthorization } from "./03-start-user-authorization";
-import { hasStatus, type Out } from "../../utils/misc";
+import { hasStatus, type Out } from "../../../src/utils/misc";
 import type { EvaluateIssuerTrust } from "./02-evaluate-issuer-trust";
+import type { StartUserAuthorization } from "./03-start-user-authorization";
+import { withEphemeralKey } from "../../../src/utils/crypto";
+import { createDPopToken } from "../../../src/utils/dpop";
+import uuid from "react-native-uuid";
+import { createPopToken } from "../../../src/utils/pop";
+import * as WalletInstanceAttestation from "../../wallet-instance-attestation";
+import type { CryptoContext } from "@pagopa/io-react-native-jwt";
 import { ASSERTION_TYPE } from "./const";
-import type { CompleteUserAuthorization } from "./04-complete-user-authorization";
+import { TokenResponse } from "./types";
+import { ValidationFailed } from "../../../src/utils/errors";
+import type { CompleteUserAuthorizationWithQueryMode } from "./04-complete-user-authorization";
 
 export type AuthorizeAccess = (
   issuerConf: Out<EvaluateIssuerTrust>["issuerConf"],
-  code: Out<CompleteUserAuthorization>["code"],
+  code: Out<CompleteUserAuthorizationWithQueryMode>["code"],
+  redirectUri: string,
   clientId: Out<StartUserAuthorization>["clientId"],
+  codeVerifier: Out<StartUserAuthorization>["codeVerifier"],
   context: {
     walletInstanceAttestation: string;
-    walletProviderBaseUrl: string;
     appFetch?: GlobalFetch["fetch"];
+    wiaCryptoContext: CryptoContext;
   }
-) => Promise<{
-  // The access token to grant access to the credential
-  accessToken: string;
-  // The nonce, to prevent reply attacks
-  nonce: string;
-  // Same as input
-  clientId: string;
-}>;
+) => Promise<{ accessToken: TokenResponse; tokenRequestSignedDPop: string }>;
 
 /**
- * Obtain the access token to finally request the credential
- *
- * @param issuerConf The Issuer configuration
- * @param code The access code from the User authorization phase
- * @param clientId Identifies the current client across all the requests of the issuing flow
- * @param context.walletInstanceAttestation The Wallet Instance Attestation token
- * @param context.walletProviderBaseUrl The base url of the Wallet Provider
+ * Creates and sends the DPoP Proof JWT to be presented with the authorization code to the /token endpoint of the authorization server
+ * for requesting the issuance of an access token bound to the public key of the Wallet Instance contained within the DPoP.
+ * This enables the Wallet Instance to request a digital credential.
+ * The DPoP Proof JWT is generated according to the section 4.3 of the DPoP RFC 9449 specification.
+ * @param issuerConf The issuer configuration returned by {@link evaluateIssuerTrust}
+ * @param code The authorization code returned by {@link completeUserAuthorizationWithQueryMode} or {@link completeUserAuthorizationWithFormPost}
+ * @param redirectUri The redirect URI which is the custom URL scheme that the Wallet Instance is registered to handle
+ * @param clientId The client id returned by {@link startUserAuthorization}
+ * @param codeVerifier The code verifier returned by {@link startUserAuthorization}
+ * @param context.walletInstanceAttestation The Wallet Instance's attestation
+ * @param context.wiaCryptoContext The Wallet Instance's crypto context
  * @param context.appFetch (optional) fetch api implementation. Default: built-in fetch
- * @returns
+ * @throws {ValidationFailed} if an error occurs while parsing the token response
+ * @return The token response containing the access token along with the token request signed with DPoP which has to be used in the {@link obtainCredential} step.
  */
 export const authorizeAccess: AuthorizeAccess = async (
   issuerConf,
   code,
   clientId,
+  redirectUri,
+  codeVerifier,
   context
-): Promise<{ accessToken: string; nonce: string; clientId: string }> => {
+) => {
   const {
     appFetch = fetch,
     walletInstanceAttestation,
-    walletProviderBaseUrl,
+    wiaCryptoContext,
   } = context;
 
-  const tokenUrl = issuerConf.openid_credential_issuer.token_endpoint;
+  const parEndpoint =
+    issuerConf.oauth_authorization_server.pushed_authorization_request_endpoint;
+  const parUrl = new URL(parEndpoint);
+  const aud = `${parUrl.protocol}//${parUrl.hostname}`;
+  const iss = WalletInstanceAttestation.decode(walletInstanceAttestation)
+    .payload.cnf.jwk.kid;
 
+  const tokenUrl = issuerConf.oauth_authorization_server.token_endpoint;
   // Use an ephemeral key to be destroyed after use
-  const signedDPop = await withEphemeralKey((ephemeralContext) =>
-    createDPopToken(
-      {
-        htm: "POST",
-        htu: tokenUrl,
-        jti: `${uuid.v4()}`,
-      },
-      ephemeralContext
-    )
+  const tokenRequestSignedDPop = await withEphemeralKey(
+    async (ephimeralContext) => {
+      return await createDPopToken(
+        {
+          htm: "POST",
+          htu: tokenUrl,
+          jti: `${uuid.v4()}`,
+        },
+        ephimeralContext
+      );
+    }
+  );
+
+  const signedWiaPoP = await createPopToken(
+    {
+      jti: `${uuid.v4()}`,
+      aud,
+      iss,
+    },
+    wiaCryptoContext
   );
 
-  const codeVerifier = `${uuid.v4()}`;
   const requestBody = {
-    grant_type: "authorization code",
+    grant_type: "authorization_code",
     client_id: clientId,
     code,
+    redirect_uri: redirectUri,
     code_verifier: codeVerifier,
     client_assertion_type: ASSERTION_TYPE,
-    client_assertion: walletInstanceAttestation,
-    redirect_uri: walletProviderBaseUrl,
+    client_assertion: walletInstanceAttestation + "~" + signedWiaPoP,
   };
-  var formBody = new URLSearchParams(requestBody);
 
-  return appFetch(tokenUrl, {
+  const authorizationRequestFormBody = new URLSearchParams(requestBody);
+  const tokenRes = await appFetch(tokenUrl, {
     method: "POST",
     headers: {
       "Content-Type": "application/x-www-form-urlencoded",
-      DPoP: signedDPop,
+      DPoP: tokenRequestSignedDPop,
     },
-    body: formBody.toString(),
+    body: authorizationRequestFormBody.toString(),
   })
     .then(hasStatus(200))
     .then((res) => res.json())
-    .then((body) => ({
-      accessToken: body.access_token,
-      nonce: body.c_nonce,
-      clientId,
-    }));
+    .then((body) => TokenResponse.safeParse(body));
+
+  if (!tokenRes.success) {
+    throw new ValidationFailed(tokenRes.error.message);
+  }
+
+  return { accessToken: tokenRes.data, tokenRequestSignedDPop };
 };