ox 0.12.2 → 0.12.3

package/core/Cbor.ts

@@ -254,6 +254,9 @@ function getEncodable(value: unknown): Encodable {
       new Uint8Array(value.buffer, value.byteOffset, value.byteLength),
     )
 
+  if (value instanceof Map)
+    return getEncodable.map(value as Map<unknown, unknown>)
+
   if (typeof value === 'object')
     return getEncodable.object(value as Record<string, unknown>)
 
@@ -549,6 +552,67 @@ namespace getEncodable {
       }
     throw new ObjectTooLargeError({ size })
   }
+
+  /** @internal */
+  export function map(value: Map<unknown, unknown>): Encodable {
+    const entries: { key: Encodable; value: Encodable }[] = []
+    for (const [k, v] of value)
+      entries.push({ key: getEncodable(k), value: getEncodable(v) })
+    const bodyLength = entries.reduce(
+      (acc, entry) => acc + entry.key.length + entry.value.length,
+      0,
+    )
+    const size = value.size
+
+    if (size <= 0x17)
+      return {
+        length: 1 + bodyLength,
+        encode(cursor) {
+          cursor.pushUint8(0xa0 + size)
+          for (const entry of entries) {
+            entry.key.encode(cursor)
+            entry.value.encode(cursor)
+          }
+        },
+      }
+    if (size <= 0xff)
+      return {
+        length: 2 + bodyLength,
+        encode(cursor) {
+          cursor.pushUint8(0xb8)
+          cursor.pushUint8(size)
+          for (const entry of entries) {
+            entry.key.encode(cursor)
+            entry.value.encode(cursor)
+          }
+        },
+      }
+    if (size <= 0xffff)
+      return {
+        length: 3 + bodyLength,
+        encode(cursor) {
+          cursor.pushUint8(0xb9)
+          cursor.pushUint16(size)
+          for (const entry of entries) {
+            entry.key.encode(cursor)
+            entry.value.encode(cursor)
+          }
+        },
+      }
+    if (size <= 0xffffffff)
+      return {
+        length: 5 + bodyLength,
+        encode(cursor) {
+          cursor.pushUint8(0xba)
+          cursor.pushUint32(size)
+          for (const entry of entries) {
+            entry.key.encode(cursor)
+            entry.value.encode(cursor)
+          }
+        },
+      }
+    throw new ObjectTooLargeError({ size })
+  }
 }
 
 /** @internal */

package/core/CoseKey.ts

@@ -0,0 +1,93 @@
+import * as Cbor from './Cbor.js'
+import * as Errors from './Errors.js'
+import type * as Hex from './Hex.js'
+import * as PublicKey from './PublicKey.js'
+
+/**
+ * Converts a P256 {@link ox#PublicKey.PublicKey} to a CBOR-encoded COSE_Key.
+ *
+ * The COSE_Key uses integer map keys per [RFC 9053](https://datatracker.ietf.org/doc/html/rfc9053):
+ * - `1` (kty): `2` (EC2)
+ * - `3` (alg): `-7` (ES256)
+ * - `-1` (crv): `1` (P-256)
+ * - `-2` (x): x coordinate bytes
+ * - `-3` (y): y coordinate bytes
+ *
+ * @example
+ * ```ts twoslash
+ * import { CoseKey, P256 } from 'ox'
+ *
+ * const { publicKey } = P256.createKeyPair()
+ *
+ * const coseKey = CoseKey.fromPublicKey(publicKey)
+ * ```
+ *
+ * @param publicKey - The P256 public key to convert.
+ * @returns The CBOR-encoded COSE_Key as a Hex string.
+ */
+export function fromPublicKey(publicKey: PublicKey.PublicKey): Hex.Hex {
+  const pkBytes = PublicKey.toBytes(publicKey)
+  const x = pkBytes.slice(1, 33)
+  const y = pkBytes.slice(33, 65)
+  return Cbor.encode(
+    new Map<number, unknown>([
+      [1, 2], // kty: EC2
+      [3, -7], // alg: ES256
+      [-1, 1], // crv: P-256
+      [-2, x], // x coordinate
+      [-3, y], // y coordinate
+    ]),
+  )
+}
+
+export declare namespace fromPublicKey {
+  type ErrorType =
+    | PublicKey.toBytes.ErrorType
+    | Cbor.encode.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Converts a CBOR-encoded COSE_Key to a P256 {@link ox#PublicKey.PublicKey}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { CoseKey, P256 } from 'ox'
+ *
+ * const { publicKey } = P256.createKeyPair()
+ * const coseKey = CoseKey.fromPublicKey(publicKey)
+ *
+ * const publicKey2 = CoseKey.toPublicKey(coseKey)
+ * ```
+ *
+ * @param coseKey - The CBOR-encoded COSE_Key.
+ * @returns The P256 public key.
+ */
+export function toPublicKey(coseKey: Hex.Hex): PublicKey.PublicKey {
+  const decoded = Cbor.decode<Record<string, unknown>>(coseKey)
+
+  const x = decoded['-2']
+  const y = decoded['-3']
+
+  if (!(x instanceof Uint8Array) || !(y instanceof Uint8Array))
+    throw new InvalidCoseKeyError()
+
+  return PublicKey.from(new Uint8Array([0x04, ...x, ...y]))
+}
+
+export declare namespace toPublicKey {
+  type ErrorType =
+    | Cbor.decode.ErrorType
+    | PublicKey.from.ErrorType
+    | InvalidCoseKeyError
+    | Errors.GlobalErrorType
+}
+
+/** Thrown when a COSE_Key does not contain valid P256 public key coordinates. */
+export class InvalidCoseKeyError extends Errors.BaseError {
+  override readonly name = 'CoseKey.InvalidCoseKeyError'
+
+  constructor() {
+    super('COSE_Key does not contain valid P256 public key coordinates.')
+  }
+}

package/core/WebAuthnP256.ts

@@ -1,5 +1,7 @@
 import * as Base64 from './Base64.js'
 import * as Bytes from './Bytes.js'
+import * as Cbor from './Cbor.js'
+import * as CoseKey from './CoseKey.js'
 import * as Errors from './Errors.js'
 import * as Hash from './Hash.js'
 import * as Hex from './Hex.js'
@@ -128,21 +130,69 @@ export declare namespace createCredential {
  * // @log: "0xa379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce194705000001a4"
  * ```
  *
+ * @example
+ * ### With Attested Credential Data
+ *
+ * Include a credential ID and public key in the authenticator data (for registration responses):
+ *
+ * ```ts twoslash
+ * import { P256, WebAuthnP256 } from 'ox'
+ *
+ * const { publicKey } = P256.createKeyPair()
+ *
+ * const authenticatorData = WebAuthnP256.getAuthenticatorData({
+ *   rpId: 'example.com',
+ *   flag: 0x41, // UP + AT
+ *   credential: {
+ *     id: new Uint8Array(32),
+ *     publicKey,
+ *   },
+ * })
+ * ```
+ *
  * @param options - Options to construct the authenticator data.
  * @returns The authenticator data.
  */
 export function getAuthenticatorData(
   options: getAuthenticatorData.Options = {},
 ): Hex.Hex {
-  const { flag = 5, rpId = window.location.hostname, signCount = 0 } = options
+  const {
+    credential,
+    flag = 5,
+    rpId = window.location.hostname,
+    signCount = 0,
+  } = options
   const rpIdHash = Hash.sha256(Hex.fromString(rpId))
   const flag_bytes = Hex.fromNumber(flag, { size: 1 })
   const signCount_bytes = Hex.fromNumber(signCount, { size: 4 })
-  return Hex.concat(rpIdHash, flag_bytes, signCount_bytes)
+  const base = Hex.concat(rpIdHash, flag_bytes, signCount_bytes)
+
+  if (!credential) return base
+
+  // AAGUID (16 bytes of zeros)
+  const aaguid = Hex.fromBytes(new Uint8Array(16))
+
+  // Credential ID
+  const credentialId = Hex.fromBytes(credential.id)
+  const credIdLen = Hex.fromNumber(credential.id.length, { size: 2 })
+
+  // COSE public key
+  const coseKey = CoseKey.fromPublicKey(credential.publicKey)
+
+  return Hex.concat(base, aaguid, credIdLen, credentialId, coseKey)
 }
 
 export declare namespace getAuthenticatorData {
   type Options = {
+    /** Attested credential data to include (credential ID + public key). When set, the AT flag (0x40) should also be set. */
+    credential?:
+      | {
+          /** The credential ID as raw bytes. */
+          id: Uint8Array
+          /** The P256 public key associated with the credential. */
+          publicKey: PublicKey.PublicKey
+        }
+      | undefined
     /** A bitfield that indicates various attributes that were asserted by the authenticator. [Read more](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API/Authenticator_data#flags) */
     flag?: number | undefined
     /** The [Relying Party ID](https://w3c.github.io/webauthn/#relying-party-identifier) that the credential is scoped to. */
@@ -187,10 +237,11 @@ export function getClientDataJSON(options: getClientDataJSON.Options): string {
     crossOrigin = false,
     extraClientData,
     origin = window.location.origin,
+    type = 'webauthn.get',
   } = options
 
   return JSON.stringify({
-    type: 'webauthn.get',
+    type,
     challenge: Base64.fromHex(challenge, { url: true, pad: false }),
     origin,
     crossOrigin,
@@ -208,11 +259,66 @@ export declare namespace getClientDataJSON {
     extraClientData?: Record<string, unknown> | undefined
     /** The fully qualified origin of the relying party which has been given by the client/browser to the authenticator. */
     origin?: string | undefined
+    /** The WebAuthn ceremony type. @default 'webauthn.get' */
+    type?: 'webauthn.create' | 'webauthn.get' | undefined
   }
 
   type ErrorType = Errors.GlobalErrorType
 }
 
+/**
+ * Constructs a CBOR-encoded attestation object for testing WebAuthn registration
+ * verification. Combines the authenticator data with an attestation statement.
+ *
+ * :::warning
+ *
+ * This function is mainly for testing purposes. In production, the attestation
+ * object is returned by the authenticator during `navigator.credentials.create()`.
+ *
+ * :::
+ *
+ * @example
+ * ```ts twoslash
+ * import { P256, WebAuthnP256 } from 'ox'
+ *
+ * const { publicKey } = P256.createKeyPair()
+ *
+ * const attestationObject = WebAuthnP256.getAttestationObject({
+ *   authData: WebAuthnP256.getAuthenticatorData({
+ *     rpId: 'example.com',
+ *     flag: 0x41,
+ *     credential: { id: new Uint8Array(32), publicKey },
+ *   }),
+ * })
+ * ```
+ *
+ * @param options - Options to construct the attestation object.
+ * @returns The CBOR-encoded attestation object as a Hex string.
+ */
+export function getAttestationObject(
+  options: getAttestationObject.Options,
+): Hex.Hex {
+  const { attStmt = {}, authData, fmt = 'none' } = options
+  return Cbor.encode({
+    fmt,
+    attStmt,
+    authData: Hex.toBytes(authData),
+  })
+}
+
+export declare namespace getAttestationObject {
+  type Options = {
+    /** Attestation statement. */
+    attStmt?: Record<string, unknown> | undefined
+    /** Authenticator data as a Hex string (from {@link ox#WebAuthnP256.(getAuthenticatorData:function)}). */
+    authData: Hex.Hex
+    /** Attestation format. @default 'none' */
+    fmt?: string | undefined
+  }
+
+  type ErrorType = Cbor.encode.ErrorType | Errors.GlobalErrorType
+}
+
 /**
  * Returns the creation options for a P256 WebAuthn Credential to be used with
  * the Web Authentication API.
@@ -716,7 +822,10 @@ export function verify(options: verify.Options): boolean {
   // Check that response is for an authentication assertion (if typeIndex is provided)
   if (typeIndex !== undefined) {
     const type = '"type":"webauthn.get"'
-    if (type !== clientDataJSON.slice(Number(typeIndex), type.length + 1))
+    if (
+      type !==
+      clientDataJSON.slice(Number(typeIndex), Number(typeIndex) + type.length)
+    )
       return false
   }
 

package/index.ts

@@ -1330,7 +1330,6 @@ export * as Caches from './core/Caches.js'
  * @category Data
  */
 export * as Cbor from './core/Cbor.js'
-
 /**
  * Utility functions for computing Contract Addresses.
  *
@@ -1368,6 +1367,38 @@ export * as Cbor from './core/Cbor.js'
  * @category Addresses
  */
 export * as ContractAddress from './core/ContractAddress.js'
+/**
+ * Utility functions for converting between COSE_Key and P256 public keys.
+ *
+ * COSE_Key is the key format used in WebAuthn attestation objects, as defined in
+ * [RFC 9053](https://datatracker.ietf.org/doc/html/rfc9053).
+ *
+ * @example
+ * ### Encoding a Public Key to COSE_Key
+ *
+ * ```ts twoslash
+ * import { CoseKey, P256 } from 'ox'
+ *
+ * const { publicKey } = P256.createKeyPair()
+ *
+ * const coseKey = CoseKey.fromPublicKey(publicKey)
+ * ```
+ *
+ * @example
+ * ### Decoding a COSE_Key to Public Key
+ *
+ * ```ts twoslash
+ * import { CoseKey, P256 } from 'ox'
+ *
+ * const { publicKey } = P256.createKeyPair()
+ * const coseKey = CoseKey.fromPublicKey(publicKey)
+ *
+ * const publicKey2 = CoseKey.toPublicKey(coseKey)
+ * ```
+ *
+ * @category Crypto
+ */
+export * as CoseKey from './core/CoseKey.js'
 
 /**
  * Utilities for working with Ed25519 signatures and key pairs.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ox",
   "description": "Ethereum Standard Library",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",
@@ -178,6 +178,11 @@
       "import": "./_esm/core/ContractAddress.js",
       "default": "./_cjs/core/ContractAddress.js"
     },
+    "./CoseKey": {
+      "types": "./_types/core/CoseKey.d.ts",
+      "import": "./_esm/core/CoseKey.js",
+      "default": "./_cjs/core/CoseKey.js"
+    },
     "./Ed25519": {
       "types": "./_types/core/Ed25519.d.ts",
       "import": "./_esm/core/Ed25519.js",

package/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '0.12.2'
+export const version = '0.12.3'