@pagopa/io-react-native-jwt 0.4.1

package/src/sign.ts

@@ -0,0 +1,180 @@
+import { JOSENotSupported, JWSInvalid, JWTInvalid } from './utils/errors';
+import type {
+  CompactJWSHeaderParameters,
+  JWTDecodeResult,
+  JWTPayload,
+} from './types';
+import { ProduceJWT } from './produce';
+import { decodeBase64, encodeBase64, removePadding } from './utils/base64';
+import { isAlgSupported } from './algorithms';
+
+import { derToJose } from './utils/asn1';
+
+/**
+ * The SignJWT class is used to build and sign Compact JWS formatted JSON Web Tokens.
+ *
+ * @example Usage with a given signature
+ *
+ * ```js
+ * const alg = 'RS256'
+ * const signature = 'Axy0....'
+ *
+ * const jwt = new SignJWT({ 'urn:example:claim': true })
+ *   .setProtectedHeader({ alg })
+ *   .setIssuedAt()
+ *   .setIssuer('urn:example:issuer')
+ *   .setAudience('urn:example:audience')
+ *   .setExpirationTime('2h')
+ *   .sign(signature)
+ *
+ * console.log(jwt)
+ * ```
+ */
+export class SignJWT extends ProduceJWT {
+  private _protectedHeader!: CompactJWSHeaderParameters;
+
+  /**
+   * Sets the JWS Protected Header on the SignJWT object.
+   *
+   * @param protectedHeader JWS Protected Header. Must contain an "alg" (JWS Algorithm) property.
+   */
+  setProtectedHeader(protectedHeader: CompactJWSHeaderParameters) {
+    if (protectedHeader.alg && isAlgSupported(protectedHeader.alg)) {
+      this._protectedHeader = protectedHeader;
+      return this;
+    }
+    throw new JOSENotSupported('Unsupported "alg" value');
+  }
+
+  /**
+   * Return a JWT without signature (`header.payload`) to sign.
+   *
+   */
+  toSign(): string {
+    if (!this._protectedHeader || !this._protectedHeader.alg) {
+      throw new JWSInvalid(
+        'Missing signature algorithm. Specify the `alg` field'
+      );
+    }
+    const protectedHeader = encodeBase64(JSON.stringify(this._protectedHeader));
+    const payload = encodeBase64(JSON.stringify(this._payload));
+    if (payload && protectedHeader) {
+      return `${protectedHeader}.${payload}`;
+    } else {
+      throw new JWSInvalid();
+    }
+  }
+
+  /**
+   * Append signature to unsigned JWT.
+   * For an ECDSA signature it is required that this is in ASN.1/DER encoded format.
+   * The same format used by the TEE. Conversion to JWS is handled automatically.
+   *
+   * @param jwtWithoutSignature
+   * @param signature
+   */
+  static async appendSignature(
+    jwtWithoutSignature: string,
+    signature: string
+  ): Promise<string> {
+    if (
+      typeof jwtWithoutSignature !== 'string' ||
+      typeof signature !== 'string'
+    ) {
+      throw new JWTInvalid('JWS must be a string');
+    }
+    if (signature === '') throw new JWSInvalid('Invalid signature');
+
+    const jwtDecoded = SignJWT.decodeJwtWithoutSignature(jwtWithoutSignature);
+    const alg = jwtDecoded.header.alg;
+    try {
+      const encodedJws = await derToJose(signature, alg);
+      return `${jwtWithoutSignature}.${encodedJws}`;
+    } catch {
+      const encodedJws = removePadding(signature);
+      return `${jwtWithoutSignature}.${encodedJws}`;
+    }
+  }
+
+  /**
+   * Decodes a JWT without signature
+   *
+   * @param jwtWithoutSignature JWT to sign that needs to be decoded.
+   */
+  static decodeJwtWithoutSignature(jwtWithoutSignature: string): {
+    payload: JWTPayload;
+    header: CompactJWSHeaderParameters;
+  } {
+    if (typeof jwtWithoutSignature !== 'string') {
+      throw new JWTInvalid('JWT must be a string');
+    }
+    const {
+      0: encodedHeader,
+      1: encodedPayload,
+      length,
+    } = jwtWithoutSignature.split('.');
+
+    let header: CompactJWSHeaderParameters;
+    try {
+      let decoded = decodeBase64(encodedHeader!);
+      header = JSON.parse(decoded);
+      if (!header.alg || !isAlgSupported(header.alg)) {
+        throw new JOSENotSupported('Unsupported "alg" value');
+      }
+    } catch {
+      throw new JWTInvalid('Unable to decode JWT header');
+    }
+
+    if (length !== 2 || encodedPayload === '') {
+      throw new JWTInvalid('Invalid JWT to sign');
+    }
+
+    let decodedPayload = decodeBase64(encodedPayload!);
+    const payload = JSON.parse(decodedPayload);
+
+    return {
+      payload,
+      header,
+    };
+  }
+
+  /**
+   * Decodes a JWT without signature
+   *
+   * @param jwtWithoutSignature JWT to sign that needs to be decoded.
+   */
+  static decode(jwt: string): JWTDecodeResult {
+    if (typeof jwt !== 'string') {
+      throw new JWTInvalid('JWT must be a string');
+    }
+    const {
+      0: encodedHeader,
+      1: encodedPayload,
+      2: signature,
+      length,
+    } = jwt.split('.');
+
+    let protectedHeader: CompactJWSHeaderParameters;
+    try {
+      let decoded = decodeBase64(encodedHeader!);
+      protectedHeader = JSON.parse(decoded);
+      if (!protectedHeader.alg || !isAlgSupported(protectedHeader.alg)) {
+        throw new JOSENotSupported('Unsupported "alg" value');
+      }
+    } catch {
+      throw new JWTInvalid('Unable to decode JWT header');
+    }
+
+    if (length !== 3 || encodedPayload === '' || signature === '') {
+      throw new JWTInvalid('Invalid JWT');
+    }
+
+    let decodedPayload = decodeBase64(encodedPayload!);
+    const payload = JSON.parse(decodedPayload);
+
+    return {
+      payload,
+      protectedHeader,
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,203 @@
+export interface JWTDecodeResult {
+  /** JWT Claims Set. */
+  payload: JWTPayload;
+
+  /** JWS Protected Header. */
+  protectedHeader: JWSHeaderParameters;
+}
+
+/**
+ * JSON Web Key ({@link https://www.rfc-editor.org/rfc/rfc7517 JWK}). "RSA", "EC", "OKP", and "oct"
+ * key types are supported.
+ */
+export interface JWK {
+  /** JWK "alg" (Algorithm) Parameter. */
+  'alg'?: string;
+  'crv'?: string;
+  'd'?: string;
+  'dp'?: string;
+  'dq'?: string;
+  'e'?: string;
+  /** JWK "ext" (Extractable) Parameter. */
+  'ext'?: boolean;
+  'k'?: string;
+  /** JWK "key_ops" (Key Operations) Parameter. */
+  'key_ops'?: string[];
+  /** JWK "kid" (Key ID) Parameter. */
+  'kid'?: string;
+  /** JWK "kty" (Key Type) Parameter.
+   * This attribute is required to discriminate the
+   * type of EC/RSA algorithm */
+  'kty': string;
+  'n'?: string;
+  'oth'?: Array<{
+    d?: string;
+    r?: string;
+    t?: string;
+  }>;
+  'p'?: string;
+  'q'?: string;
+  'qi'?: string;
+  /** JWK "use" (Public Key Use) Parameter. */
+  'use'?: string;
+  'x'?: string;
+  'y'?: string;
+  /** JWK "x5c" (X.509 Certificate Chain) Parameter. */
+  'x5c'?: string[];
+  /** JWK "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter. */
+  'x5t'?: string;
+  /** "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Parameter. */
+  'x5t#S256'?: string;
+  /** JWK "x5u" (X.509 URL) Parameter. */
+  'x5u'?: string;
+
+  [propName: string]: unknown;
+}
+
+export interface JoseHeaderParameters {
+  /** "kid" (Key ID) Header Parameter. */
+  kid?: string;
+
+  /** "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter. */
+  x5t?: string;
+
+  /** "x5c" (X.509 Certificate Chain) Header Parameter. */
+  x5c?: string[];
+
+  /** "x5u" (X.509 URL) Header Parameter. */
+  x5u?: string;
+
+  /** "jku" (JWK Set URL) Header Parameter. */
+  jku?: string;
+
+  /** "jwk" (JSON Web Key) Header Parameter. */
+  jwk?: Pick<JWK, 'kty' | 'crv' | 'x' | 'y' | 'e' | 'n'>;
+
+  /** "typ" (Type) Header Parameter. */
+  typ?: string;
+
+  /** "cty" (Content Type) Header Parameter. */
+  cty?: string;
+}
+
+/** Recognized JWS Header Parameters, any other Header Members may also be present. */
+export interface JWSHeaderParameters extends JoseHeaderParameters {
+  /** JWS "alg" (Algorithm) Header Parameter. */
+  alg?: string;
+
+  /**
+   * This JWS Extension Header Parameter modifies the JWS Payload representation and the JWS Signing
+   * Input computation as per {@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}.
+   */
+  b64?: boolean;
+
+  /** JWS "crit" (Critical) Header Parameter. */
+  crit?: string[];
+
+  /** Any other JWS Header member. */
+  [propName: string]: unknown;
+}
+
+/** Recognized Compact JWS Header Parameters, any other Header Members may also be present. */
+export interface CompactJWSHeaderParameters extends JWSHeaderParameters {
+  alg: string;
+}
+
+/** Recognized JWT Claims Set members, any other members may also be present. */
+export interface JWTPayload {
+  /**
+   * JWT Issuer
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1 RFC7519#section-4.1.1}
+   */
+  iss?: string;
+
+  /**
+   * JWT Subject
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2 RFC7519#section-4.1.2}
+   */
+  sub?: string;
+
+  /**
+   * JWT Audience
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3 RFC7519#section-4.1.3}
+   */
+  aud?: string | string[];
+
+  /**
+   * JWT ID
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7 RFC7519#section-4.1.7}
+   */
+  jti?: string;
+
+  /**
+   * JWT Not Before
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5 RFC7519#section-4.1.5}
+   */
+  nbf?: number;
+
+  /**
+   * JWT Expiration Time
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4 RFC7519#section-4.1.4}
+   */
+  exp?: number;
+
+  /**
+   * JWT Issued At
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6 RFC7519#section-4.1.6}
+   */
+  iat?: number;
+
+  /** Any other JWT Claim Set member. */
+  [propName: string]: unknown;
+}
+
+/** JWT Claims Set verification options. */
+export interface JWTClaimVerificationOptions {
+  /** Expected JWT "aud" (Audience) Claim value(s). */
+  audience?: string | string[];
+
+  /**
+   * Expected clock tolerance
+   *
+   * - In seconds when number (e.g. 5)
+   * - Parsed as seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
+   */
+  clockTolerance?: string | number;
+
+  /** Expected JWT "iss" (Issuer) Claim value(s). */
+  issuer?: string | string[];
+
+  /**
+   * Maximum time elapsed (in seconds) from the JWT "iat" (Issued At) Claim value.
+   *
+   * - In seconds when number (e.g. 5)
+   * - Parsed as seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
+   */
+  maxTokenAge?: string | number;
+
+  /** Expected JWT "sub" (Subject) Claim value. */
+  subject?: string;
+
+  /** Expected JWT "typ" (Type) Header Parameter value. */
+  typ?: string;
+
+  /** Date to use when comparing NumericDate claims, defaults to `new Date()`. */
+  currentDate?: Date;
+
+  /**
+   * Array of required Claim Names that must be present in the JWT Claims Set. Default is that: if
+   * the {@link JWTClaimVerificationOptions.issuer issuer option} is set, then "iss" must be present;
+   * if the {@link JWTClaimVerificationOptions.audience audience option} is set, then "aud" must be
+   * present; if the {@link JWTClaimVerificationOptions.subject subject option} is set, then "sub"
+   * must be present; if the {@link JWTClaimVerificationOptions.maxTokenAge maxTokenAge option} is
+   * set, then "iat" must be present.
+   */
+  requiredClaims?: string[];
+}

package/src/unsecured.ts

@@ -0,0 +1,127 @@
+import type {
+  JWSHeaderParameters,
+  JWTClaimVerificationOptions,
+  JWTPayload,
+} from './types';
+
+import { JWTInvalid } from './utils/errors';
+import jwtPayload from './jwt_claims_set';
+import { ProduceJWT } from './produce';
+import { decodeBase64, encodeBase64 } from './utils/base64';
+
+export interface UnsecuredResult {
+  payload: JWTPayload;
+  header: JWSHeaderParameters;
+}
+
+/**
+ * The UnsecuredJWT class is a utility for dealing with `{ "alg": "none" }` Unsecured JWTs.
+ *
+ * @example Encoding
+ *
+ * ```js
+ * const unsecuredJwt = new UnsecuredJWT({ 'urn:example:claim': true })
+ *   .setIssuedAt()
+ *   .setIssuer('urn:example:issuer')
+ *   .setAudience('urn:example:audience')
+ *   .setExpirationTime('2h')
+ *   .encode()
+ *
+ * console.log(unsecuredJwt)
+ * ```
+ *
+ * @example Decoding
+ *
+ * ```js
+ * const payload = UnsecuredJWT.decode(jwt, {
+ *   issuer: 'urn:example:issuer',
+ *   audience: 'urn:example:audience',
+ * })
+ *
+ * console.log(payload)
+ * ```
+ *  * @example JWT content ToSign
+ *
+ * ```js
+ * const jwtToSign = new UnsecuredJWT({ 'urn:example:claim': true })
+ *   .setIssuedAt()
+ *   .setIssuer('urn:example:issuer')
+ *   .setAudience('urn:example:audience')
+ *   .setExpirationTime('2h')
+ *   .toSign()
+ *
+ * console.log(jwtToSign)
+ * ```
+ */
+export class UnsecuredJWT extends ProduceJWT {
+  /** Encodes the Unsecured JWT. */
+  encode(): string {
+    const header = encodeBase64(JSON.stringify({ alg: 'none' }));
+    const payload = encodeBase64(JSON.stringify(this._payload));
+
+    return `${header}.${payload}.`;
+  }
+
+  /**
+   * Decodes an unsecured JWT.
+   *
+   * @param jwt Unsecured JWT to decode the payload of.
+   * @param options JWT Claims Set validation options.
+   */
+  static decode(
+    jwt: string,
+    options?: JWTClaimVerificationOptions
+  ): UnsecuredResult {
+    if (typeof jwt !== 'string') {
+      throw new JWTInvalid('Unsecured JWT must be a string');
+    }
+    const {
+      0: encodedHeader,
+      1: encodedPayload,
+      2: signature,
+      length,
+    } = jwt.split('.');
+
+    if (length !== 3 || signature !== '' || !encodedPayload) {
+      throw new JWTInvalid('Invalid Unsecured JWT');
+    }
+
+    let header: JWSHeaderParameters;
+    try {
+      let decoded = decodeBase64(encodedHeader!);
+      header = JSON.parse(decoded);
+      if (header.alg !== 'none') throw new Error();
+    } catch {
+      throw new JWTInvalid('Invalid Unsecured JWT');
+    }
+
+    let payload = UnsecuredJWT.decodePayload(encodedPayload, options);
+
+    return { payload, header };
+  }
+
+  /**
+   * Decodes an unsecured JWT payload.
+   *
+   * @param jwt Unsecured JWT payload to decode.
+   * @param options JWT Claims Set validation options.
+   */
+  static decodePayload(
+    jwt: string,
+    options?: JWTClaimVerificationOptions
+  ): JWTPayload {
+    if (typeof jwt !== 'string') {
+      throw new JWTInvalid('Unsecured JWT must be a string');
+    }
+    const { 0: encodedPayload, length } = jwt.split('.');
+
+    if (length !== 1 || encodedPayload === '') {
+      throw new JWTInvalid('Invalid Unsecured JWT');
+    }
+
+    let decodedPayload = decodeBase64(encodedPayload!);
+    const payload = jwtPayload({}, JSON.parse(decodedPayload), options);
+
+    return payload;
+  }
+}

package/src/utils/asn1.ts

@@ -0,0 +1,36 @@
+import { getCoordinateOctetLength, getKtyFromAlg } from '../algorithms';
+import { IoReactNativeJwt } from './proxy';
+import { removePadding } from './base64';
+import { JOSENotSupported } from './errors';
+
+/*
+ * Transcodes the JCA ASN.1/DER-encoded signature into the concatenated R + S format expected by ECDSA JWS.
+ * Returns a base64 url encoded String.
+ *
+ * @example Usage with an ASN.1/DER-encoded
+ *
+ * ```js
+ * const asn1Signature = 'Yw1xTT....'
+ * const plainSignature = await derToJose(asn1Signature, "ECDSA256")
+ *
+ * ```
+ *
+ * @param asn1Signature ASN.1/DER-encoded signature
+ * @param alg Algorithm used to sign
+ */
+export const derToJose = async (
+  asn1Signature: string,
+  alg: string
+): Promise<string> => {
+  const kty = getKtyFromAlg(alg);
+  if (kty === 'EC') {
+    const unpackedJws = await IoReactNativeJwt.unpackBerEncodedASN1(
+      asn1Signature,
+      getCoordinateOctetLength(alg)
+    );
+    const encodedJws = removePadding(unpackedJws);
+    return encodedJws;
+  } else {
+    throw new JOSENotSupported('Unsupported "alg" value');
+  }
+};

package/src/utils/base64.ts

@@ -0,0 +1,37 @@
+import { btoa, atob } from 'abab';
+import { JOSEError } from './errors';
+
+/*
+ * In Base64 encoding, the length of an output-encoded String
+ * must be a multiple of four. If necessary, the encoder adds
+ * one or two padding characters (=) at the end of the output
+ * as needed in order to meet this requirement.
+ *
+ * JWTs make use of the base64url encoding as defined in RFC 4648.
+ * As allowed by Section 3.2 of the RFC, this specification mandates
+ * that base64url encoding when used with JWTs MUST NOT use padding.
+ * The reason for this restriction is that the padding character
+ * ('=') is not URL safe.
+ */
+export function encodeBase64(value: string): string {
+  let encoded = btoa(value);
+  if (encoded) {
+    return removePadding(encoded);
+  } else {
+    throw new JOSEError('Unable to encode string to base64');
+  }
+}
+
+export function decodeBase64(value: string): string {
+  let decoded = atob(value);
+  if (decoded) {
+    return decoded;
+  } else {
+    throw new JOSEError('Unable to decode base64 string');
+  }
+}
+
+export function removePadding(encoded: string): string {
+  // eslint-disable-next-line no-div-regex
+  return encoded.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}