@simplewebauthn/server 7.4.0 → 8.0.0-alpha.0

package/esm/helpers/iso/isoCrypto/verify.js

@@ -0,0 +1,28 @@
+import { COSEKEYS, isCOSEPublicKeyEC2, isCOSEPublicKeyOKP, isCOSEPublicKeyRSA, } from '../../cose.js';
+import { verifyEC2 } from './verifyEC2.js';
+import { verifyRSA } from './verifyRSA.js';
+import { verifyOKP } from './verifyOKP.js';
+import { unwrapEC2Signature } from './unwrapEC2Signature.js';
+/**
+ * Verify signatures with their public key. Supports EC2 and RSA public keys.
+ */
+export function verify(opts) {
+    const { cosePublicKey, signature, data, shaHashOverride } = opts;
+    if (isCOSEPublicKeyEC2(cosePublicKey)) {
+        const unwrappedSignature = unwrapEC2Signature(signature);
+        return verifyEC2({
+            cosePublicKey,
+            signature: unwrappedSignature,
+            data,
+            shaHashOverride,
+        });
+    }
+    else if (isCOSEPublicKeyRSA(cosePublicKey)) {
+        return verifyRSA({ cosePublicKey, signature, data, shaHashOverride });
+    }
+    else if (isCOSEPublicKeyOKP(cosePublicKey)) {
+        return verifyOKP({ cosePublicKey, signature, data });
+    }
+    const kty = cosePublicKey.get(COSEKEYS.kty);
+    throw new Error(`Signature verification with public key of kty ${kty} is not supported by this method`);
+}

package/{dist → esm}/helpers/iso/isoCrypto/verifyEC2.d.ts

@@ -1,4 +1,4 @@
-import { COSEALG, COSEPublicKeyEC2 } from '../../cose';
+import { COSEALG, COSEPublicKeyEC2 } from '../../cose.js';
 /**
  * Verify a signature using an EC2 public key
  */

package/esm/helpers/iso/isoCrypto/verifyEC2.js

@@ -0,0 +1,73 @@
+import { COSECRV, COSEKEYS } from '../../cose.js';
+import { mapCoseAlgToWebCryptoAlg } from './mapCoseAlgToWebCryptoAlg.js';
+import { importKey } from './importKey.js';
+import { isoBase64URL } from '../index.js';
+import { getWebCrypto } from './getWebCrypto.js';
+/**
+ * Verify a signature using an EC2 public key
+ */
+export async function verifyEC2(opts) {
+    const { cosePublicKey, signature, data, shaHashOverride } = opts;
+    const WebCrypto = await getWebCrypto();
+    // Import the public key
+    const alg = cosePublicKey.get(COSEKEYS.alg);
+    const crv = cosePublicKey.get(COSEKEYS.crv);
+    const x = cosePublicKey.get(COSEKEYS.x);
+    const y = cosePublicKey.get(COSEKEYS.y);
+    if (!alg) {
+        throw new Error('Public key was missing alg (EC2)');
+    }
+    if (!crv) {
+        throw new Error('Public key was missing crv (EC2)');
+    }
+    if (!x) {
+        throw new Error('Public key was missing x (EC2)');
+    }
+    if (!y) {
+        throw new Error('Public key was missing y (EC2)');
+    }
+    let _crv;
+    if (crv === COSECRV.P256) {
+        _crv = 'P-256';
+    }
+    else if (crv === COSECRV.P384) {
+        _crv = 'P-384';
+    }
+    else if (crv === COSECRV.P521) {
+        _crv = 'P-521';
+    }
+    else {
+        throw new Error(`Unexpected COSE crv value of ${crv} (EC2)`);
+    }
+    const keyData = {
+        kty: 'EC',
+        crv: _crv,
+        x: isoBase64URL.fromBuffer(x),
+        y: isoBase64URL.fromBuffer(y),
+        ext: false,
+    };
+    const keyAlgorithm = {
+        /**
+         * Note to future self: you can't use `mapCoseAlgToWebCryptoKeyAlgName()` here because some
+         * leaf certs from actual devices specified an RSA SHA value for `alg` (e.g. `-257`) which
+         * would then map here to `'RSASSA-PKCS1-v1_5'`. We always want `'ECDSA'` here so we'll
+         * hard-code this.
+         */
+        name: 'ECDSA',
+        namedCurve: _crv,
+    };
+    const key = await importKey({
+        keyData,
+        algorithm: keyAlgorithm,
+    });
+    // Determine which SHA algorithm to use for signature verification
+    let subtleAlg = mapCoseAlgToWebCryptoAlg(alg);
+    if (shaHashOverride) {
+        subtleAlg = mapCoseAlgToWebCryptoAlg(shaHashOverride);
+    }
+    const verifyAlgorithm = {
+        name: 'ECDSA',
+        hash: { name: subtleAlg },
+    };
+    return WebCrypto.subtle.verify(verifyAlgorithm, key, signature, data);
+}

package/{dist → esm}/helpers/iso/isoCrypto/verifyOKP.d.ts

@@ -1,4 +1,4 @@
-import { COSEPublicKeyOKP } from '../../cose';
+import { COSEPublicKeyOKP } from '../../cose.js';
 export declare function verifyOKP(opts: {
     cosePublicKey: COSEPublicKeyOKP;
     signature: Uint8Array;

package/esm/helpers/iso/isoCrypto/verifyOKP.js

@@ -0,0 +1,51 @@
+import { COSECRV, COSEKEYS, isCOSEAlg } from '../../cose.js';
+import { isoBase64URL } from '../../index.js';
+import { importKey } from './importKey.js';
+import { getWebCrypto } from './getWebCrypto.js';
+export async function verifyOKP(opts) {
+    const { cosePublicKey, signature, data } = opts;
+    const WebCrypto = await getWebCrypto();
+    const alg = cosePublicKey.get(COSEKEYS.alg);
+    const crv = cosePublicKey.get(COSEKEYS.crv);
+    const x = cosePublicKey.get(COSEKEYS.x);
+    if (!alg) {
+        throw new Error('Public key was missing alg (OKP)');
+    }
+    if (!isCOSEAlg(alg)) {
+        throw new Error(`Public key had invalid alg ${alg} (OKP)`);
+    }
+    if (!crv) {
+        throw new Error('Public key was missing crv (OKP)');
+    }
+    if (!x) {
+        throw new Error('Public key was missing x (OKP)');
+    }
+    // Pulled key import steps from here:
+    // https://wicg.github.io/webcrypto-secure-curves/#ed25519-operations
+    let _crv;
+    if (crv === COSECRV.ED25519) {
+        _crv = 'Ed25519';
+    }
+    else {
+        throw new Error(`Unexpected COSE crv value of ${crv} (OKP)`);
+    }
+    const keyData = {
+        kty: 'OKP',
+        crv: _crv,
+        alg: 'EdDSA',
+        x: isoBase64URL.fromBuffer(x),
+        ext: false,
+    };
+    const keyAlgorithm = {
+        name: _crv,
+        namedCurve: _crv,
+    };
+    const key = await importKey({
+        keyData,
+        algorithm: keyAlgorithm,
+    });
+    const verifyAlgorithm = {
+        name: _crv,
+    };
+    return WebCrypto.subtle.verify(verifyAlgorithm, key, signature, data);
+}

package/{dist → esm}/helpers/iso/isoCrypto/verifyRSA.d.ts

@@ -1,4 +1,4 @@
-import { COSEALG, COSEPublicKeyRSA } from '../../cose';
+import { COSEALG, COSEPublicKeyRSA } from '../../cose.js';
 /**
  * Verify a signature using an RSA public key
  */

package/esm/helpers/iso/isoCrypto/verifyRSA.js

@@ -0,0 +1,91 @@
+import { COSEKEYS, isCOSEAlg } from '../../cose.js';
+import { mapCoseAlgToWebCryptoAlg } from './mapCoseAlgToWebCryptoAlg.js';
+import { importKey } from './importKey.js';
+import { isoBase64URL } from '../index.js';
+import { mapCoseAlgToWebCryptoKeyAlgName } from './mapCoseAlgToWebCryptoKeyAlgName.js';
+import { getWebCrypto } from './getWebCrypto.js';
+/**
+ * Verify a signature using an RSA public key
+ */
+export async function verifyRSA(opts) {
+    const { cosePublicKey, signature, data, shaHashOverride } = opts;
+    const WebCrypto = await getWebCrypto();
+    const alg = cosePublicKey.get(COSEKEYS.alg);
+    const n = cosePublicKey.get(COSEKEYS.n);
+    const e = cosePublicKey.get(COSEKEYS.e);
+    if (!alg) {
+        throw new Error('Public key was missing alg (RSA)');
+    }
+    if (!isCOSEAlg(alg)) {
+        throw new Error(`Public key had invalid alg ${alg} (RSA)`);
+    }
+    if (!n) {
+        throw new Error('Public key was missing n (RSA)');
+    }
+    if (!e) {
+        throw new Error('Public key was missing e (RSA)');
+    }
+    const keyData = {
+        kty: 'RSA',
+        alg: '',
+        n: isoBase64URL.fromBuffer(n),
+        e: isoBase64URL.fromBuffer(e),
+        ext: false,
+    };
+    const keyAlgorithm = {
+        name: mapCoseAlgToWebCryptoKeyAlgName(alg),
+        hash: { name: mapCoseAlgToWebCryptoAlg(alg) },
+    };
+    const verifyAlgorithm = {
+        name: mapCoseAlgToWebCryptoKeyAlgName(alg),
+    };
+    if (shaHashOverride) {
+        keyAlgorithm.hash.name = mapCoseAlgToWebCryptoAlg(shaHashOverride);
+    }
+    if (keyAlgorithm.name === 'RSASSA-PKCS1-v1_5') {
+        if (keyAlgorithm.hash.name === 'SHA-256') {
+            keyData.alg = 'RS256';
+        }
+        else if (keyAlgorithm.hash.name === 'SHA-384') {
+            keyData.alg = 'RS384';
+        }
+        else if (keyAlgorithm.hash.name === 'SHA-512') {
+            keyData.alg = 'RS512';
+        }
+        else if (keyAlgorithm.hash.name === 'SHA-1') {
+            keyData.alg = 'RS1';
+        }
+    }
+    else if (keyAlgorithm.name === 'RSA-PSS') {
+        /**
+         * salt length. The default value is 20 but the convention is to use hLen, the length of the
+         * output of the hash function in bytes. A salt length of zero is permitted and will result in
+         * a deterministic signature value. The actual salt length used can be determined from the
+         * signature value.
+         *
+         * From https://www.cryptosys.net/pki/manpki/pki_rsaschemes.html
+         */
+        let saltLength = 0;
+        if (keyAlgorithm.hash.name === 'SHA-256') {
+            keyData.alg = 'PS256';
+            saltLength = 32; // 256 bits => 32 bytes
+        }
+        else if (keyAlgorithm.hash.name === 'SHA-384') {
+            keyData.alg = 'PS384';
+            saltLength = 48; // 384 bits => 48 bytes
+        }
+        else if (keyAlgorithm.hash.name === 'SHA-512') {
+            keyData.alg = 'PS512';
+            saltLength = 64; // 512 bits => 64 bytes
+        }
+        verifyAlgorithm.saltLength = saltLength;
+    }
+    else {
+        throw new Error(`Unexpected RSA key algorithm ${alg} (${keyAlgorithm.name})`);
+    }
+    const key = await importKey({
+        keyData,
+        algorithm: keyAlgorithm,
+    });
+    return WebCrypto.subtle.verify(verifyAlgorithm, key, signature, data);
+}

package/esm/helpers/iso/isoUint8Array.js

@@ -0,0 +1,75 @@
+/**
+ * Make sure two Uint8Arrays are deeply equivalent
+ */
+export function areEqual(array1, array2) {
+    if (array1.length != array2.length) {
+        return false;
+    }
+    return array1.every((val, i) => val === array2[i]);
+}
+/**
+ * Convert a Uint8Array to Hexadecimal.
+ *
+ * A replacement for `Buffer.toString('hex')`
+ */
+export function toHex(array) {
+    const hexParts = Array.from(array, (i) => i.toString(16).padStart(2, '0'));
+    // adce000235bcc60a648b0b25f1f05503
+    return hexParts.join('');
+}
+/**
+ * Convert a hexadecimal string to isoUint8Array.
+ *
+ * A replacement for `Buffer.from('...', 'hex')`
+ */
+export function fromHex(hex) {
+    if (!hex) {
+        return Uint8Array.from([]);
+    }
+    const isValid = hex.length !== 0 && hex.length % 2 === 0 &&
+        !/[^a-fA-F0-9]/u.test(hex);
+    if (!isValid) {
+        throw new Error('Invalid hex string');
+    }
+    const byteStrings = hex.match(/.{1,2}/g) ?? [];
+    return Uint8Array.from(byteStrings.map((byte) => parseInt(byte, 16)));
+}
+/**
+ * Combine multiple Uint8Arrays into a single Uint8Array
+ */
+export function concat(arrays) {
+    let pointer = 0;
+    const totalLength = arrays.reduce((prev, curr) => prev + curr.length, 0);
+    const toReturn = new Uint8Array(totalLength);
+    arrays.forEach((arr) => {
+        toReturn.set(arr, pointer);
+        pointer += arr.length;
+    });
+    return toReturn;
+}
+/**
+ * Convert bytes into a UTF-8 string
+ */
+export function toUTF8String(array) {
+    const decoder = new globalThis.TextDecoder('utf-8');
+    return decoder.decode(array);
+}
+/**
+ * Convert a UTF-8 string back into bytes
+ */
+export function fromUTF8String(utf8String) {
+    const encoder = new globalThis.TextEncoder();
+    return encoder.encode(utf8String);
+}
+/**
+ * Convert an ASCII string to Uint8Array
+ */
+export function fromASCIIString(value) {
+    return Uint8Array.from(value.split('').map((x) => x.charCodeAt(0)));
+}
+/**
+ * Prepare a DataView we can slice our way around in as we parse the bytes in a Uint8Array
+ */
+export function toDataView(array) {
+    return new DataView(array.buffer, array.byteOffset, array.length);
+}

package/{dist → esm}/helpers/logging.d.ts

@@ -1,4 +1,4 @@
-import { Debugger } from 'debug';
+import { Debugger } from '../deps.js';
 /**
  * Generate an instance of a `debug` logger that extends off of the "simplewebauthn" namespace for
  * consistent naming.

package/esm/helpers/logging.js

@@ -0,0 +1,19 @@
+import { debug } from '../deps.js';
+const defaultLogger = debug('SimpleWebAuthn');
+/**
+ * Generate an instance of a `debug` logger that extends off of the "simplewebauthn" namespace for
+ * consistent naming.
+ *
+ * See https://www.npmjs.com/package/debug for information on how to control logging output when
+ * using @simplewebauthn/server
+ *
+ * Example:
+ *
+ * ```
+ * const log = getLogger('mds');
+ * log('hello'); // simplewebauthn:mds hello +0ms
+ * ```
+ */
+export function getLogger(name) {
+    return defaultLogger.extend(name);
+}

package/{dist → esm}/helpers/mapX509SignatureAlgToCOSEAlg.d.ts

@@ -1,4 +1,4 @@
-import { COSEALG } from './cose';
+import { COSEALG } from './cose.js';
 /**
  * Map X.509 signature algorithm OIDs to COSE algorithm IDs
  *

package/esm/helpers/mapX509SignatureAlgToCOSEAlg.js

@@ -0,0 +1,35 @@
+import { COSEALG } from './cose.js';
+/**
+ * Map X.509 signature algorithm OIDs to COSE algorithm IDs
+ *
+ * - EC2 OIDs: https://oidref.com/1.2.840.10045.4.3
+ * - RSA OIDs: https://oidref.com/1.2.840.113549.1.1
+ */
+export function mapX509SignatureAlgToCOSEAlg(signatureAlgorithm) {
+    let alg;
+    if (signatureAlgorithm === '1.2.840.10045.4.3.2') {
+        alg = COSEALG.ES256;
+    }
+    else if (signatureAlgorithm === '1.2.840.10045.4.3.3') {
+        alg = COSEALG.ES384;
+    }
+    else if (signatureAlgorithm === '1.2.840.10045.4.3.4') {
+        alg = COSEALG.ES512;
+    }
+    else if (signatureAlgorithm === '1.2.840.113549.1.1.11') {
+        alg = COSEALG.RS256;
+    }
+    else if (signatureAlgorithm === '1.2.840.113549.1.1.12') {
+        alg = COSEALG.RS384;
+    }
+    else if (signatureAlgorithm === '1.2.840.113549.1.1.13') {
+        alg = COSEALG.RS512;
+    }
+    else if (signatureAlgorithm === '1.2.840.113549.1.1.5') {
+        alg = COSEALG.RS1;
+    }
+    else {
+        throw new Error(`Unable to map X.509 signature algorithm ${signatureAlgorithm} to a COSE algorithm`);
+    }
+    return alg;
+}

package/esm/helpers/matchExpectedRPID.js

@@ -0,0 +1,41 @@
+import { toHash } from './toHash.js';
+import { isoUint8Array } from './iso/index.js';
+/**
+ * Go through each expected RP ID and try to find one that matches. Returns the unhashed RP ID
+ * that matched the hash in the response.
+ *
+ * Raises an `UnexpectedRPIDHash` error if no match is found
+ */
+export async function matchExpectedRPID(rpIDHash, expectedRPIDs) {
+    try {
+        const matchedRPID = await Promise.any(expectedRPIDs.map((expected) => {
+            return new Promise((resolve, reject) => {
+                toHash(isoUint8Array.fromASCIIString(expected)).then((expectedRPIDHash) => {
+                    if (isoUint8Array.areEqual(rpIDHash, expectedRPIDHash)) {
+                        resolve(expected);
+                    }
+                    else {
+                        reject();
+                    }
+                });
+            });
+        }));
+        return matchedRPID;
+    }
+    catch (err) {
+        const _err = err;
+        // This means no matches were found
+        if (_err.name === 'AggregateError') {
+            throw new UnexpectedRPIDHash();
+        }
+        // An unexpected error occurred
+        throw err;
+    }
+}
+class UnexpectedRPIDHash extends Error {
+    constructor() {
+        const message = 'Unexpected RP ID hash';
+        super(message);
+        this.name = 'UnexpectedRPIDHash';
+    }
+}

package/{dist → esm}/helpers/parseAuthenticatorData.d.ts

@@ -1,4 +1,4 @@
-import { AuthenticationExtensionsAuthenticatorOutputs } from './decodeAuthenticatorExtensions';
+import { AuthenticationExtensionsAuthenticatorOutputs } from './decodeAuthenticatorExtensions.js';
 /**
  * Make sense of the authData buffer contained in an Attestation
  */
@@ -23,3 +23,6 @@ export type ParsedAuthenticatorData = {
     extensionsData?: AuthenticationExtensionsAuthenticatorOutputs;
     extensionsDataBuffer?: Uint8Array;
 };
+export declare const _parseAuthenticatorDataInternals: {
+    stubThis: (value: ParsedAuthenticatorData) => ParsedAuthenticatorData;
+};

package/esm/helpers/parseAuthenticatorData.js

@@ -0,0 +1,71 @@
+import { decodeAuthenticatorExtensions, } from './decodeAuthenticatorExtensions.js';
+import { isoCBOR, isoUint8Array } from './iso/index.js';
+/**
+ * Make sense of the authData buffer contained in an Attestation
+ */
+export function parseAuthenticatorData(authData) {
+    if (authData.byteLength < 37) {
+        throw new Error(`Authenticator data was ${authData.byteLength} bytes, expected at least 37 bytes`);
+    }
+    let pointer = 0;
+    const dataView = isoUint8Array.toDataView(authData);
+    const rpIdHash = authData.slice(pointer, pointer += 32);
+    const flagsBuf = authData.slice(pointer, pointer += 1);
+    const flagsInt = flagsBuf[0];
+    // Bit positions can be referenced here:
+    // https://www.w3.org/TR/webauthn-2/#flags
+    const flags = {
+        up: !!(flagsInt & (1 << 0)),
+        uv: !!(flagsInt & (1 << 2)),
+        be: !!(flagsInt & (1 << 3)),
+        bs: !!(flagsInt & (1 << 4)),
+        at: !!(flagsInt & (1 << 6)),
+        ed: !!(flagsInt & (1 << 7)),
+        flagsInt,
+    };
+    const counterBuf = authData.slice(pointer, pointer + 4);
+    const counter = dataView.getUint32(pointer, false);
+    pointer += 4;
+    let aaguid = undefined;
+    let credentialID = undefined;
+    let credentialPublicKey = undefined;
+    if (flags.at) {
+        aaguid = authData.slice(pointer, pointer += 16);
+        const credIDLen = dataView.getUint16(pointer);
+        pointer += 2;
+        credentialID = authData.slice(pointer, pointer += credIDLen);
+        // Decode the next CBOR item in the buffer, then re-encode it back to a Buffer
+        const firstDecoded = isoCBOR.decodeFirst(authData.slice(pointer));
+        const firstEncoded = Uint8Array.from(isoCBOR.encode(firstDecoded));
+        credentialPublicKey = firstEncoded;
+        pointer += firstEncoded.byteLength;
+    }
+    let extensionsData = undefined;
+    let extensionsDataBuffer = undefined;
+    if (flags.ed) {
+        const firstDecoded = isoCBOR.decodeFirst(authData.slice(pointer));
+        extensionsDataBuffer = Uint8Array.from(isoCBOR.encode(firstDecoded));
+        extensionsData = decodeAuthenticatorExtensions(extensionsDataBuffer);
+        pointer += extensionsDataBuffer.byteLength;
+    }
+    // Pointer should be at the end of the authenticator data, otherwise too much data was sent
+    if (authData.byteLength > pointer) {
+        throw new Error('Leftover bytes detected while parsing authenticator data');
+    }
+    return _parseAuthenticatorDataInternals.stubThis({
+        rpIdHash,
+        flagsBuf,
+        flags,
+        counter,
+        counterBuf,
+        aaguid,
+        credentialID,
+        credentialPublicKey,
+        extensionsData,
+        extensionsDataBuffer,
+    });
+}
+// Make it possible to stub the return value during testing
+export const _parseAuthenticatorDataInternals = {
+    stubThis: (value) => value,
+};

package/{dist → esm}/helpers/parseBackupFlags.d.ts

@@ -1,4 +1,4 @@
-import { CredentialDeviceType } from '@simplewebauthn/typescript-types';
+import type { CredentialDeviceType } from '../deps.js';
 /**
  * Make sense of Bits 3 and 4 in authenticator indicating:
  *
@@ -14,3 +14,6 @@ export declare function parseBackupFlags({ be, bs }: {
     credentialDeviceType: CredentialDeviceType;
     credentialBackedUp: boolean;
 };
+export declare class InvalidBackupFlags extends Error {
+    constructor(message: string);
+}

package/esm/helpers/parseBackupFlags.js

@@ -0,0 +1,25 @@
+/**
+ * Make sense of Bits 3 and 4 in authenticator indicating:
+ *
+ * - Whether the credential can be used on multiple devices
+ * - Whether the credential is backed up or not
+ *
+ * Invalid configurations will raise an `Error`
+ */
+export function parseBackupFlags({ be, bs }) {
+    const credentialBackedUp = bs;
+    let credentialDeviceType = 'singleDevice';
+    if (be) {
+        credentialDeviceType = 'multiDevice';
+    }
+    if (credentialDeviceType === 'singleDevice' && credentialBackedUp) {
+        throw new InvalidBackupFlags('Single-device credential indicated that it was backed up, which should be impossible.');
+    }
+    return { credentialDeviceType, credentialBackedUp };
+}
+export class InvalidBackupFlags extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidBackupFlags';
+    }
+}

package/{dist → esm}/helpers/toHash.d.ts

@@ -1,4 +1,4 @@
-import { COSEALG } from './cose';
+import { COSEALG } from './cose.js';
 /**
  * Returns hash digest of the given data, using the given algorithm when provided. Defaults to using
  * SHA-256.

package/esm/helpers/toHash.js

@@ -0,0 +1,12 @@
+import { isoCrypto, isoUint8Array } from './iso/index.js';
+/**
+ * Returns hash digest of the given data, using the given algorithm when provided. Defaults to using
+ * SHA-256.
+ */
+export function toHash(data, algorithm = -7) {
+    if (typeof data === 'string') {
+        data = isoUint8Array.fromUTF8String(data);
+    }
+    const digest = isoCrypto.digest(data, algorithm);
+    return digest;
+}