@simplewebauthn/server 9.0.3 → 10.0.1

package/script/registration/generateRegistrationOptions.d.ts

@@ -1,14 +1,17 @@
-import type { AttestationConveyancePreference, AuthenticationExtensionsClientInputs, AuthenticatorSelectionCriteria, COSEAlgorithmIdentifier, PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialDescriptorFuture } from '../deps.js';
+import type { AttestationConveyancePreference, AuthenticationExtensionsClientInputs, AuthenticatorSelectionCriteria, AuthenticatorTransportFuture, Base64URLString, COSEAlgorithmIdentifier, PublicKeyCredentialCreationOptionsJSON } from '../deps.js';
 export type GenerateRegistrationOptionsOpts = {
     rpName: string;
     rpID: string;
-    userID: string;
     userName: string;
+    userID?: Uint8Array;
     challenge?: string | Uint8Array;
     userDisplayName?: string;
     timeout?: number;
     attestationType?: AttestationConveyancePreference;
-    excludeCredentials?: PublicKeyCredentialDescriptorFuture[];
+    excludeCredentials?: {
+        id: Base64URLString;
+        transports?: AuthenticatorTransportFuture[];
+    }[];
     authenticatorSelection?: AuthenticatorSelectionCriteria;
     extensions?: AuthenticationExtensionsClientInputs;
     supportedAlgorithmIDs?: COSEAlgorithmIdentifier[];
@@ -20,24 +23,21 @@ export type GenerateRegistrationOptionsOpts = {
  */
 export declare const supportedCOSEAlgorithmIdentifiers: COSEAlgorithmIdentifier[];
 /**
- * Prepare a value to pass into navigator.credentials.create(...) for authenticator "registration"
+ * Prepare a value to pass into navigator.credentials.create(...) for authenticator registration
  *
  * **Options:**
  *
- * @param rpName User-visible, "friendly" website/service name
- * @param rpID Valid domain name (after `https://`)
- * @param userID User's website-specific unique ID
- * @param userName User's website-specific username (email, etc...)
- * @param challenge Random value the authenticator needs to sign and pass back
- * @param userDisplayName User's actual name
- * @param timeout How long (in ms) the user can take to complete attestation
- * @param attestationType Specific attestation statement
- * @param excludeCredentials Authenticators registered by the user so the user can't register the
- * same credential multiple times
- * @param authenticatorSelection Advanced criteria for restricting the types of authenticators that
- * may be used
- * @param extensions Additional plugins the authenticator or browser should use during attestation
- * @param supportedAlgorithmIDs Array of numeric COSE algorithm identifiers supported for
- * attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms
+ * @param rpName - User-visible, "friendly" website/service name
+ * @param rpID - Valid domain name (after `https://`)
+ * @param userName - User's website-specific username (email, etc...)
+ * @param userID **(Optional)** - User's website-specific unique ID. Defaults to generating a random identifier
+ * @param challenge **(Optional)** - Random value the authenticator needs to sign and pass back. Defaults to generating a random value
+ * @param userDisplayName **(Optional)** - User's actual name. Defaults to `""`
+ * @param timeout **(Optional)** - How long (in ms) the user can take to complete attestation. Defaults to `60000`
+ * @param attestationType **(Optional)** - Specific attestation statement. Defaults to `"none"`
+ * @param excludeCredentials **(Optional)** - Authenticators registered by the user so the user can't register the same credential multiple times. Defaults to `[]`
+ * @param authenticatorSelection **(Optional)** - Advanced criteria for restricting the types of authenticators that may be used. Defaults to `{ residentKey: 'preferred', userVerification: 'preferred' }`
+ * @param extensions **(Optional)** - Additional plugins the authenticator or browser should use during attestation
+ * @param supportedAlgorithmIDs **(Optional)** - Array of numeric COSE algorithm identifiers supported for attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms. Defaults to `[-8, -7, -257]`
  */
 export declare function generateRegistrationOptions(options: GenerateRegistrationOptionsOpts): Promise<PublicKeyCredentialCreationOptionsJSON>;

package/script/registration/generateRegistrationOptions.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateRegistrationOptions = exports.supportedCOSEAlgorithmIdentifiers = void 0;
 const generateChallenge_js_1 = require("../helpers/generateChallenge.js");
+const generateUserID_js_1 = require("../helpers/generateUserID.js");
 const index_js_1 = require("../helpers/iso/index.js");
 /**
  * Supported crypto algo identifiers
@@ -49,28 +50,25 @@ const defaultAuthenticatorSelection = {
  */
 const defaultSupportedAlgorithmIDs = [-8, -7, -257];
 /**
- * Prepare a value to pass into navigator.credentials.create(...) for authenticator "registration"
+ * Prepare a value to pass into navigator.credentials.create(...) for authenticator registration
  *
  * **Options:**
  *
- * @param rpName User-visible, "friendly" website/service name
- * @param rpID Valid domain name (after `https://`)
- * @param userID User's website-specific unique ID
- * @param userName User's website-specific username (email, etc...)
- * @param challenge Random value the authenticator needs to sign and pass back
- * @param userDisplayName User's actual name
- * @param timeout How long (in ms) the user can take to complete attestation
- * @param attestationType Specific attestation statement
- * @param excludeCredentials Authenticators registered by the user so the user can't register the
- * same credential multiple times
- * @param authenticatorSelection Advanced criteria for restricting the types of authenticators that
- * may be used
- * @param extensions Additional plugins the authenticator or browser should use during attestation
- * @param supportedAlgorithmIDs Array of numeric COSE algorithm identifiers supported for
- * attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms
+ * @param rpName - User-visible, "friendly" website/service name
+ * @param rpID - Valid domain name (after `https://`)
+ * @param userName - User's website-specific username (email, etc...)
+ * @param userID **(Optional)** - User's website-specific unique ID. Defaults to generating a random identifier
+ * @param challenge **(Optional)** - Random value the authenticator needs to sign and pass back. Defaults to generating a random value
+ * @param userDisplayName **(Optional)** - User's actual name. Defaults to `""`
+ * @param timeout **(Optional)** - How long (in ms) the user can take to complete attestation. Defaults to `60000`
+ * @param attestationType **(Optional)** - Specific attestation statement. Defaults to `"none"`
+ * @param excludeCredentials **(Optional)** - Authenticators registered by the user so the user can't register the same credential multiple times. Defaults to `[]`
+ * @param authenticatorSelection **(Optional)** - Advanced criteria for restricting the types of authenticators that may be used. Defaults to `{ residentKey: 'preferred', userVerification: 'preferred' }`
+ * @param extensions **(Optional)** - Additional plugins the authenticator or browser should use during attestation
+ * @param supportedAlgorithmIDs **(Optional)** - Array of numeric COSE algorithm identifiers supported for attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms. Defaults to `[-8, -7, -257]`
  */
 async function generateRegistrationOptions(options) {
-    const { rpName, rpID, userID, userName, challenge = await (0, generateChallenge_js_1.generateChallenge)(), userDisplayName = userName, timeout = 60000, attestationType = 'none', excludeCredentials = [], authenticatorSelection = defaultAuthenticatorSelection, extensions, supportedAlgorithmIDs = defaultSupportedAlgorithmIDs, } = options;
+    const { rpName, rpID, userName, userID, challenge = await (0, generateChallenge_js_1.generateChallenge)(), userDisplayName = '', timeout = 60000, attestationType = 'none', excludeCredentials = [], authenticatorSelection = defaultAuthenticatorSelection, extensions, supportedAlgorithmIDs = defaultSupportedAlgorithmIDs, } = options;
     /**
      * Prepare pubKeyCredParams from the array of algorithm ID's
      */
@@ -118,6 +116,20 @@ async function generateRegistrationOptions(options) {
     if (typeof _challenge === 'string') {
         _challenge = index_js_1.isoUint8Array.fromUTF8String(_challenge);
     }
+    /**
+     * Explicitly disallow use of strings for userID anymore because `isoBase64URL.fromBuffer()` below
+     * will return an empty string if one gets through!
+     */
+    if (typeof userID === 'string') {
+        throw new Error(`String values for \`userID\` are no longer supported. See https://simplewebauthn.dev/docs/advanced/server/custom-user-ids`);
+    }
+    /**
+     * Generate a user ID if one is not provided
+     */
+    let _userID = userID;
+    if (!_userID) {
+        _userID = await (0, generateUserID_js_1.generateUserID)();
+    }
     return {
         challenge: index_js_1.isoBase64URL.fromBuffer(_challenge),
         rp: {
@@ -125,17 +137,23 @@ async function generateRegistrationOptions(options) {
             id: rpID,
         },
         user: {
-            id: userID,
+            id: index_js_1.isoBase64URL.fromBuffer(_userID),
             name: userName,
             displayName: userDisplayName,
         },
         pubKeyCredParams,
         timeout,
         attestation: attestationType,
-        excludeCredentials: excludeCredentials.map((cred) => ({
-            ...cred,
-            id: index_js_1.isoBase64URL.fromBuffer(cred.id),
-        })),
+        excludeCredentials: excludeCredentials.map((cred) => {
+            if (!index_js_1.isoBase64URL.isBase64URL(cred.id)) {
+                throw new Error(`excludeCredential id "${cred.id}" is not a valid base64url string`);
+            }
+            return {
+                ...cred,
+                id: index_js_1.isoBase64URL.trimPadding(cred.id),
+                type: 'public-key',
+            };
+        }),
         authenticatorSelection,
         extensions: {
             ...extensions,

package/script/registration/verifications/verifyAttestationAndroidSafetyNet.js

@@ -26,8 +26,8 @@ async function verifyAttestationAndroidSafetyNet(options) {
     // Prepare to verify a JWT
     const jwt = index_js_1.isoUint8Array.toUTF8String(response);
     const jwtParts = jwt.split('.');
-    const HEADER = JSON.parse(index_js_1.isoBase64URL.toString(jwtParts[0]));
-    const PAYLOAD = JSON.parse(index_js_1.isoBase64URL.toString(jwtParts[1]));
+    const HEADER = JSON.parse(index_js_1.isoBase64URL.toUTF8String(jwtParts[0]));
+    const PAYLOAD = JSON.parse(index_js_1.isoBase64URL.toUTF8String(jwtParts[1]));
     const SIGNATURE = jwtParts[2];
     /**
      * START Verify PAYLOAD

package/script/registration/verifyRegistrationResponse.d.ts

@@ -1,4 +1,4 @@
-import type { COSEAlgorithmIdentifier, CredentialDeviceType, RegistrationResponseJSON } from '../deps.js';
+import type { Base64URLString, COSEAlgorithmIdentifier, CredentialDeviceType, RegistrationResponseJSON } from '../deps.js';
 import { AttestationFormat, AttestationStatement } from '../helpers/decodeAttestationObject.js';
 import { AuthenticationExtensionsAuthenticatorOutputs } from '../helpers/decodeAuthenticatorExtensions.js';
 export type VerifyRegistrationResponseOpts = {
@@ -15,16 +15,13 @@ export type VerifyRegistrationResponseOpts = {
  *
  * **Options:**
  *
- * @param response Response returned by **@simplewebauthn/browser**'s `startAuthentication()`
- * @param expectedChallenge The base64url-encoded `options.challenge` returned by
- * `generateRegistrationOptions()`
- * @param expectedOrigin Website URL (or array of URLs) that the registration should have occurred on
- * @param expectedRPID RP ID (or array of IDs) that was specified in the registration options
- * @param expectedType (Optional) The response type expected ('webauthn.create')
- * @param requireUserVerification (Optional) Enforce user verification by the authenticator
- * (via PIN, fingerprint, etc...)
- * @param supportedAlgorithmIDs Array of numeric COSE algorithm identifiers supported for
- * attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms
+ * @param response - Response returned by **@simplewebauthn/browser**'s `startAuthentication()`
+ * @param expectedChallenge - The base64url-encoded `options.challenge` returned by `generateRegistrationOptions()`
+ * @param expectedOrigin - Website URL (or array of URLs) that the registration should have occurred on
+ * @param expectedRPID - RP ID (or array of IDs) that was specified in the registration options
+ * @param expectedType **(Optional)** - The response type expected ('webauthn.create')
+ * @param requireUserVerification **(Optional)** - Enforce user verification by the authenticator (via PIN, fingerprint, etc...) Defaults to `true`
+ * @param supportedAlgorithmIDs **(Optional)** - Array of numeric COSE algorithm identifiers supported for attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms. Defaults to all supported algorithm IDs
  */
 export declare function verifyRegistrationResponse(options: VerifyRegistrationResponseOpts): Promise<VerifiedRegistrationResponse>;
 /**
@@ -59,7 +56,7 @@ export type VerifiedRegistrationResponse = {
         fmt: AttestationFormat;
         counter: number;
         aaguid: string;
-        credentialID: Uint8Array;
+        credentialID: Base64URLString;
         credentialPublicKey: Uint8Array;
         credentialType: 'public-key';
         attestationObject: Uint8Array;

package/script/registration/verifyRegistrationResponse.js

@@ -24,16 +24,13 @@ const verifyAttestationApple_js_1 = require("./verifications/verifyAttestationAp
  *
  * **Options:**
  *
- * @param response Response returned by **@simplewebauthn/browser**'s `startAuthentication()`
- * @param expectedChallenge The base64url-encoded `options.challenge` returned by
- * `generateRegistrationOptions()`
- * @param expectedOrigin Website URL (or array of URLs) that the registration should have occurred on
- * @param expectedRPID RP ID (or array of IDs) that was specified in the registration options
- * @param expectedType (Optional) The response type expected ('webauthn.create')
- * @param requireUserVerification (Optional) Enforce user verification by the authenticator
- * (via PIN, fingerprint, etc...)
- * @param supportedAlgorithmIDs Array of numeric COSE algorithm identifiers supported for
- * attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms
+ * @param response - Response returned by **@simplewebauthn/browser**'s `startAuthentication()`
+ * @param expectedChallenge - The base64url-encoded `options.challenge` returned by `generateRegistrationOptions()`
+ * @param expectedOrigin - Website URL (or array of URLs) that the registration should have occurred on
+ * @param expectedRPID - RP ID (or array of IDs) that was specified in the registration options
+ * @param expectedType **(Optional)** - The response type expected ('webauthn.create')
+ * @param requireUserVerification **(Optional)** - Enforce user verification by the authenticator (via PIN, fingerprint, etc...) Defaults to `true`
+ * @param supportedAlgorithmIDs **(Optional)** - Array of numeric COSE algorithm identifiers supported for attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms. Defaults to all supported algorithm IDs
  */
 async function verifyRegistrationResponse(options) {
     const { response, expectedChallenge, expectedOrigin, expectedRPID, expectedType, requireUserVerification = true, supportedAlgorithmIDs = generateRegistrationOptions_js_1.supportedCOSEAlgorithmIdentifiers, } = options;
@@ -197,7 +194,7 @@ async function verifyRegistrationResponse(options) {
             fmt,
             counter,
             aaguid: (0, convertAAGUIDToString_js_1.convertAAGUIDToString)(aaguid),
-            credentialID,
+            credentialID: index_js_1.isoBase64URL.fromBuffer(credentialID),
             credentialPublicKey,
             credentialType,
             attestationObject,