@enbox/crypto 0.0.4 → 0.0.5

package/dist/types/cose/eat.d.ts

@@ -0,0 +1,203 @@
+import type { CoseSign1ProtectedHeader } from './cose-sign1.js';
+import type { Jwk } from '../jose/jwk.js';
+/**
+ * EAT (Entity Attestation Token) claim key constants.
+ *
+ * EAT reuses CWT registered claim keys and adds attestation-specific claims.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9711 | RFC 9711 — Entity Attestation Token (EAT)}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8392 | RFC 8392 — CWT (CBOR Web Token)}
+ */
+export declare enum EatClaimKey {
+    /** Issuer (iss) — RFC 8392 */
+    Iss = 1,
+    /** Subject (sub) — RFC 8392 */
+    Sub = 2,
+    /** Audience (aud) — RFC 8392 */
+    Aud = 3,
+    /** Expiration Time (exp) — RFC 8392 */
+    Exp = 4,
+    /** Not Before (nbf) — RFC 8392 */
+    Nbf = 5,
+    /** Issued At (iat) — RFC 8392 */
+    Iat = 6,
+    /** CWT ID (cti) — RFC 8392 */
+    Cti = 7,
+    /** Nonce (eat_nonce) — RFC 9711, Section 4.1 */
+    Nonce = 10,
+    /** UEID (Universal Entity ID) — RFC 9711, Section 4.2.1 */
+    Ueid = 256,
+    /** SUEIDs (Semi-permanent UEIDs) — RFC 9711, Section 4.2.2 */
+    Sueids = 257,
+    /** OEM ID (Hardware OEM Identification) — RFC 9711, Section 4.2.3 */
+    Oemid = 258,
+    /** Hardware Model — RFC 9711, Section 4.2.4 */
+    Hwmodel = 259,
+    /** Hardware Version — RFC 9711, Section 4.2.5 */
+    Hwversion = 260,
+    /** Secure Boot — RFC 9711, Section 4.2.7 */
+    Secboot = 262,
+    /** Debug Status — RFC 9711, Section 4.2.8 */
+    Dbgstat = 263,
+    /** Location — RFC 9711, Section 4.2.9 */
+    Location = 264,
+    /** Profile — RFC 9711, Section 4.2.10 */
+    Profile = 265,
+    /** Submods (Submodules) — RFC 9711, Section 4.2.18 */
+    Submods = 266,
+    /** Measurement Results — RFC 9711, Section 4.2.15 */
+    Measres = 272,
+    /** Intended Use — RFC 9711, Section 4.2.14 */
+    Intuse = 268
+}
+/**
+ * Debug status values for the `dbgstat` claim.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9711#section-4.2.8 | RFC 9711, Section 4.2.8}
+ */
+export declare enum EatDebugStatus {
+    /** Debug is enabled */
+    Enabled = 0,
+    /** Debug is disabled */
+    Disabled = 1,
+    /** Debug is disabled since manufacture */
+    DisabledSinceBoot = 2,
+    /** Debug is disabled permanently */
+    DisabledPermanently = 3,
+    /** Debug is disabled fully and permanently */
+    DisabledFullyAndPermanently = 4
+}
+/**
+ * Security level for the `seclevel` claim.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9711#section-4.2.6 | RFC 9711, Section 4.2.6}
+ */
+export declare enum EatSecurityLevel {
+    /** Unrestricted — no security guarantees */
+    Unrestricted = 1,
+    /** Restricted — some restrictions on environment */
+    Restricted = 2,
+    /** Secure Restricted — hardware-enforced restrictions */
+    SecureRestricted = 3,
+    /** Hardware — hardware-isolated execution environment */
+    Hardware = 4
+}
+/**
+ * Parsed EAT claims, providing typed access to standard and attestation-specific claims.
+ *
+ * All fields are optional because EAT does not mandate any specific claims; the
+ * required set depends on the attestation profile.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9711 | RFC 9711}
+ */
+export interface EatClaims {
+    /** Issuer — identifies the entity that issued the token. */
+    iss?: string;
+    /** Subject — identifies the entity that is the subject of the token. */
+    sub?: string;
+    /** Audience — identifies the intended recipient(s). */
+    aud?: string;
+    /** Expiration time (seconds since epoch). */
+    exp?: number;
+    /** Not Before (seconds since epoch). */
+    nbf?: number;
+    /** Issued At (seconds since epoch). */
+    iat?: number;
+    /** CWT ID — unique token identifier (byte string). */
+    cti?: Uint8Array;
+    /** Nonce — challenge value binding the token to a request. */
+    nonce?: Uint8Array | Uint8Array[];
+    /** Universal Entity ID. */
+    ueid?: Uint8Array;
+    /** Hardware model identifier. */
+    hwmodel?: Uint8Array;
+    /** Hardware version. */
+    hwversion?: unknown;
+    /** Debug status. */
+    dbgstat?: EatDebugStatus;
+    /** Measurement results — software component measurements. */
+    measres?: unknown;
+    /** Submodules — nested EAT tokens or claims from sub-components. */
+    submods?: Map<string, unknown>;
+    /**
+     * All raw claims as a Map for access to non-standard or profile-specific claims.
+     * Integer keys correspond to {@link EatClaimKey} values.
+     */
+    rawClaims: Map<number | string, unknown>;
+}
+/**
+ * Parameters for decoding an EAT token.
+ */
+export interface EatDecodeParams {
+    /** The CBOR-encoded EAT token (COSE_Sign1 envelope). */
+    token: Uint8Array;
+}
+/**
+ * Parameters for verifying and decoding an EAT token.
+ */
+export interface EatVerifyParams {
+    /** The CBOR-encoded EAT token (COSE_Sign1 envelope). */
+    token: Uint8Array;
+    /** The public key for signature verification, in JWK format. */
+    key: Jwk;
+    /** External additional authenticated data. Defaults to empty bytes. */
+    externalAad?: Uint8Array;
+}
+/**
+ * Result of decoding an EAT token.
+ */
+export interface EatDecodeResult {
+    /** The parsed protected header from the COSE_Sign1 envelope. */
+    protectedHeader: CoseSign1ProtectedHeader;
+    /** The parsed EAT claims from the payload. */
+    claims: EatClaims;
+}
+/**
+ * Entity Attestation Token (EAT) implementation per RFC 9711.
+ *
+ * EATs are CBOR-based attestation tokens carried in COSE_Sign1 envelopes.
+ * They are used by TEE platforms (ARM CCA, Intel TDX, AMD SEV-SNP, Nitro Enclaves)
+ * to provide hardware-rooted attestation evidence.
+ *
+ * This implementation focuses on decoding and verification of EAT tokens — the
+ * primary use case for a DWN node that needs to verify TEE attestation from
+ * compute modules.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9711 | RFC 9711 — Entity Attestation Token (EAT)}
+ */
+export declare class Eat {
+    /**
+     * Decodes an EAT token without verifying its signature.
+     *
+     * Use this method only when signature verification is performed separately
+     * (e.g., by a TEE attestation service) or for debugging/inspection.
+     *
+     * @param params - The parameters for decoding.
+     * @returns The decoded protected header and claims.
+     * @throws {CryptoError} If the token is not valid COSE_Sign1 or the payload is not valid CBOR.
+     */
+    static decode({ token }: EatDecodeParams): EatDecodeResult;
+    /**
+     * Verifies the signature of an EAT token and decodes its claims.
+     *
+     * This is the primary method for processing EAT tokens from TEE attestation.
+     * It verifies the COSE_Sign1 signature using the provided public key, then
+     * parses the EAT claims from the payload.
+     *
+     * @param params - The parameters for verification and decoding.
+     * @returns The decoded protected header and claims if verification succeeds.
+     * @throws {CryptoError} If verification fails or the token is malformed.
+     */
+    static verifyAndDecode(params: EatVerifyParams): Promise<EatDecodeResult>;
+    /**
+     * Parses CBOR-encoded EAT claims into a typed {@link EatClaims} object.
+     *
+     * Handles both integer-keyed (CBOR standard) and string-keyed claims.
+     *
+     * @param payload - The CBOR-encoded claims byte string.
+     * @returns The parsed EAT claims.
+     * @throws {CryptoError} If the payload is not valid CBOR or not a map.
+     */
+    private static parseClaims;
+}
+//# sourceMappingURL=eat.d.ts.map

package/dist/types/cose/eat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eat.d.ts","sourceRoot":"","sources":["../../../src/cose/eat.ts"],"names":[],"mappings":"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"}

package/dist/types/crypto-error.d.ts

@@ -19,6 +19,10 @@ export declare enum CryptoErrorCode {
     AlgorithmNotSupported = "algorithmNotSupported",
     /** The encoding operation (either encoding or decoding) failed. */
     EncodingError = "encodingError",
+    /** The COSE_Sign1 message does not conform to valid structure. */
+    InvalidCoseSign1 = "invalidCoseSign1",
+    /** The EAT (Entity Attestation Token) is malformed or failed verification. */
+    InvalidEat = "invalidEat",
     /** The JWE supplied does not conform to valid syntax. */
     InvalidJwe = "invalidJwe",
     /** The JWK supplied does not conform to valid syntax. */

package/dist/types/crypto-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto-error.d.ts","sourceRoot":"","sources":["../../src/crypto-error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAOjB,IAAI,EAAE,eAAe;IANxC;;;;;OAKG;gBACgB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAc1D;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,gFAAgF;IAChF,qBAAqB,0BAA0B;IAE/C,mEAAmE;IACnE,aAAa,kBAAkB;IAE/B,yDAAyD;IACzD,UAAU,eAAe;IAEzB,yDAAyD;IACzD,UAAU,eAAe;IAEzB,sEAAsE;IACtE,qBAAqB,0BAA0B;CAChD"}
+{"version":3,"file":"crypto-error.d.ts","sourceRoot":"","sources":["../../src/crypto-error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAOjB,IAAI,EAAE,eAAe;IANxC;;;;;OAKG;gBACgB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAc1D;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,gFAAgF;IAChF,qBAAqB,0BAA0B;IAE/C,mEAAmE;IACnE,aAAa,kBAAkB;IAE/B,kEAAkE;IAClE,gBAAgB,qBAAqB;IAErC,8EAA8E;IAC9E,UAAU,eAAe;IAEzB,yDAAyD;IACzD,UAAU,eAAe;IAEzB,yDAAyD;IACzD,UAAU,eAAe;IAEzB,sEAAsE;IACtE,qBAAqB,0BAA0B;CAChD"}

package/dist/types/index.d.ts

@@ -1,6 +1,10 @@
 export * from './crypto-error.js';
 export * from './local-key-manager.js';
 export * from './utils.js';
+export * from './cose/cbor.js';
+export * from './cose/cose-key.js';
+export * from './cose/cose-sign1.js';
+export * from './cose/eat.js';
 export * from './algorithms/aes-ctr.js';
 export * from './algorithms/aes-gcm.js';
 export * from './algorithms/aes-kw.js';

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,YAAY,CAAC;AAE3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC;AACjD,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAEhC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AAEnD,mBAAmB,mBAAmB,CAAC;AACvC,mBAAmB,uBAAuB,CAAC;AAC3C,mBAAmB,mBAAmB,CAAC;AACvC,mBAAmB,uBAAuB,CAAC;AAC3C,mBAAmB,2BAA2B,CAAC;AAC/C,mBAAmB,0BAA0B,CAAC;AAC9C,mBAAmB,wBAAwB,CAAC;AAC5C,mBAAmB,0BAA0B,CAAC;AAC9C,mBAAmB,mBAAmB,CAAC;AACvC,mBAAmB,wBAAwB,CAAC;AAC5C,mBAAmB,0BAA0B,CAAC;AAC9C,mBAAmB,4BAA4B,CAAC;AAChD,mBAAmB,uBAAuB,CAAC;AAC3C,mBAAmB,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,YAAY,CAAC;AAE3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAE9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC;AACjD,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAEhC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AAEnD,mBAAmB,mBAAmB,CAAC;AACvC,mBAAmB,uBAAuB,CAAC;AAC3C,mBAAmB,mBAAmB,CAAC;AACvC,mBAAmB,uBAAuB,CAAC;AAC3C,mBAAmB,2BAA2B,CAAC;AAC/C,mBAAmB,0BAA0B,CAAC;AAC9C,mBAAmB,wBAAwB,CAAC;AAC5C,mBAAmB,0BAA0B,CAAC;AAC9C,mBAAmB,mBAAmB,CAAC;AACvC,mBAAmB,wBAAwB,CAAC;AAC5C,mBAAmB,0BAA0B,CAAC;AAC9C,mBAAmB,4BAA4B,CAAC;AAChD,mBAAmB,uBAAuB,CAAC;AAC3C,mBAAmB,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/crypto",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Web5 cryptographic library",
   "type": "module",
   "main": "./dist/esm/index.js",
@@ -16,7 +16,7 @@
     "test:node": "bun test .test.ts",
     "test:node:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage .test.ts",
     "test:browser": "bunx --bun vitest --config vitest.browser.config.ts --run",
-    "test:browser:coverage": "bunx --bun vitest --config vitest.browser.config.ts --run --coverage --coverage.provider=istanbul --coverage.reportsDirectory=./coverage-browser"
+    "test:browser:coverage": "bunx --bun vitest --config vitest.browser.config.ts --run --coverage --coverage.provider=istanbul"
   },
   "homepage": "https://github.com/enboxorg/enbox/tree/main/packages/crypto#readme",
   "bugs": "https://github.com/enboxorg/enbox/issues",
@@ -68,10 +68,11 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
+    "@enbox/common": "0.0.4",
     "@noble/ciphers": "0.5.3",
     "@noble/curves": "1.3.0",
     "@noble/hashes": "1.4.0",
-    "@enbox/common": "0.0.3"
+    "cborg": "^4.5.8"
   },
   "devDependencies": {
     "@types/node": "20.14.8",

package/src/cose/cbor.ts

@@ -0,0 +1,36 @@
+import { decode as cborDecode, encode as cborEncode } from 'cborg';
+
+/**
+ * CBOR (Concise Binary Object Representation) encoding and decoding utilities.
+ *
+ * Provides a thin wrapper around the `cborg` library, exposing `encode` and `decode`
+ * operations for use by COSE and EAT implementations.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8949 | RFC 8949 — CBOR}
+ */
+export class Cbor {
+  /**
+   * Encodes a JavaScript value to a CBOR byte string.
+   *
+   * @param value - The value to encode. Supports objects, arrays, strings, numbers,
+   *   booleans, null, undefined, Uint8Array (encoded as CBOR byte string), and Map.
+   * @returns The CBOR-encoded bytes.
+   */
+  public static encode(value: unknown): Uint8Array {
+    return cborEncode(value);
+  }
+
+  /**
+   * Decodes a CBOR byte string to a JavaScript value.
+   *
+   * CBOR maps are decoded as JavaScript `Map` instances to support integer keys,
+   * which is required by COSE (RFC 9052) and EAT (RFC 9711).
+   *
+   * @param data - The CBOR-encoded bytes to decode.
+   * @returns The decoded JavaScript value.
+   * @throws If the input is not valid CBOR.
+   */
+  public static decode<T = unknown>(data: Uint8Array): T {
+    return cborDecode(data, { useMaps: true }) as T;
+  }
+}

package/src/cose/cose-key.ts

@@ -0,0 +1,344 @@
+import type { Jwk } from '../jose/jwk.js';
+
+import { Convert } from '@enbox/common';
+
+import { CryptoError, CryptoErrorCode } from '../crypto-error.js';
+
+/**
+ * COSE Key Type values (RFC 9052, Section 7).
+ *
+ * @see {@link https://www.iana.org/assignments/cose/cose.xhtml#key-type | IANA COSE Key Types}
+ */
+export enum CoseKeyType {
+  /** Octet Key Pair (e.g., Ed25519, X25519) */
+  OKP = 1,
+  /** Elliptic Curve (e.g., P-256, P-384, P-521) */
+  EC2 = 2,
+  /** Symmetric key */
+  Symmetric = 4,
+}
+
+/**
+ * COSE Elliptic Curve identifiers (RFC 9053, Section 7.1).
+ *
+ * @see {@link https://www.iana.org/assignments/cose/cose.xhtml#elliptic-curves | IANA COSE Elliptic Curves}
+ */
+export enum CoseEllipticCurve {
+  /** NIST P-256 (secp256r1) */
+  P256 = 1,
+  /** NIST P-384 (secp384r1) */
+  P384 = 2,
+  /** NIST P-521 (secp521r1) */
+  P521 = 3,
+  /** X25519 for ECDH */
+  X25519 = 4,
+  /** X448 for ECDH */
+  X448 = 5,
+  /** Ed25519 for EdDSA */
+  Ed25519 = 6,
+  /** Ed448 for EdDSA */
+  Ed448 = 7,
+  /** secp256k1 */
+  Secp256k1 = 8,
+}
+
+/**
+ * COSE Algorithm identifiers (RFC 9053).
+ *
+ * Only includes algorithms relevant to Enbox confidential compute.
+ *
+ * @see {@link https://www.iana.org/assignments/cose/cose.xhtml#algorithms | IANA COSE Algorithms}
+ */
+export enum CoseAlgorithm {
+  /** EdDSA (Ed25519 or Ed448) */
+  EdDSA = -8,
+  /** ECDSA with SHA-256 (P-256) */
+  ES256 = -7,
+  /** ECDSA with SHA-384 (P-384) */
+  ES384 = -35,
+  /** ECDSA with SHA-512 (P-521) */
+  ES512 = -36,
+  /** ECDSA with SHA-256 (secp256k1) */
+  ES256K = -47,
+}
+
+/**
+ * COSE Key common parameter labels (RFC 9052, Section 7.1).
+ */
+enum CoseKeyLabel {
+  /** Key Type (kty) */
+  Kty = 1,
+  /** Key ID (kid) */
+  Kid = 2,
+  /** Algorithm */
+  Alg = 3,
+  /** Key Operations */
+  KeyOps = 4,
+  /** Base IV */
+  BaseIv = 5,
+}
+
+/**
+ * COSE Key type-specific parameter labels.
+ *
+ * For OKP and EC2 keys, the curve and coordinate labels share the same
+ * negative-integer label space (RFC 9053, Section 7.1-7.2).
+ */
+enum CoseKeyParamLabel {
+  /** Curve identifier (OKP and EC2) */
+  Crv = -1,
+  /** X coordinate (OKP public key or EC2 x-coordinate) */
+  X = -2,
+  /** Y coordinate (EC2 only) */
+  Y = -3,
+  /** Private key (OKP d value or EC2 d value) */
+  D = -4,
+}
+
+/**
+ * Maps JWK curve names to COSE elliptic curve identifiers.
+ */
+const jwkCrvToCose: Record<string, CoseEllipticCurve> = {
+  'P-256'     : CoseEllipticCurve.P256,
+  'P-384'     : CoseEllipticCurve.P384,
+  'P-521'     : CoseEllipticCurve.P521,
+  'X25519'    : CoseEllipticCurve.X25519,
+  'Ed25519'   : CoseEllipticCurve.Ed25519,
+  'Ed448'     : CoseEllipticCurve.Ed448,
+  'secp256k1' : CoseEllipticCurve.Secp256k1,
+};
+
+/**
+ * Maps COSE elliptic curve identifiers to JWK curve names.
+ */
+const coseCrvToJwk: Record<number, string> = {
+  [CoseEllipticCurve.P256]      : 'P-256',
+  [CoseEllipticCurve.P384]      : 'P-384',
+  [CoseEllipticCurve.P521]      : 'P-521',
+  [CoseEllipticCurve.X25519]    : 'X25519',
+  [CoseEllipticCurve.Ed25519]   : 'Ed25519',
+  [CoseEllipticCurve.Ed448]     : 'Ed448',
+  [CoseEllipticCurve.Secp256k1] : 'secp256k1',
+};
+
+/**
+ * Maps JWK algorithm names to COSE algorithm identifiers.
+ */
+const jwkAlgToCose: Record<string, CoseAlgorithm> = {
+  'EdDSA'  : CoseAlgorithm.EdDSA,
+  'ES256'  : CoseAlgorithm.ES256,
+  'ES384'  : CoseAlgorithm.ES384,
+  'ES512'  : CoseAlgorithm.ES512,
+  'ES256K' : CoseAlgorithm.ES256K,
+};
+
+/**
+ * Maps COSE algorithm identifiers to JWK algorithm names.
+ */
+const coseAlgToJwk: Record<number, string> = {
+  [CoseAlgorithm.EdDSA]  : 'EdDSA',
+  [CoseAlgorithm.ES256]  : 'ES256',
+  [CoseAlgorithm.ES384]  : 'ES384',
+  [CoseAlgorithm.ES512]  : 'ES512',
+  [CoseAlgorithm.ES256K] : 'ES256K',
+};
+
+/**
+ * Utilities for converting between JWK and COSE key representations.
+ *
+ * COSE keys use integer labels and CBOR encoding, while JWK uses string
+ * property names and JSON. This class provides bidirectional conversion.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9052#section-7 | RFC 9052, Section 7}
+ */
+export class CoseKey {
+  /**
+   * Converts a JWK to a COSE key represented as a Map.
+   *
+   * @param jwk - The JWK to convert.
+   * @returns A Map with integer labels as keys, suitable for CBOR encoding.
+   * @throws {CryptoError} If the JWK key type or curve is not supported.
+   */
+  public static fromJwk(jwk: Jwk): Map<number, unknown> {
+    const coseKey = new Map<number, unknown>();
+
+    if (jwk.kty === 'OKP') {
+      coseKey.set(CoseKeyLabel.Kty, CoseKeyType.OKP);
+
+      const crv = jwk.crv;
+      if (crv === undefined || !(crv in jwkCrvToCose)) {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `CoseKey: unsupported OKP curve '${crv}'`);
+      }
+      coseKey.set(CoseKeyParamLabel.Crv, jwkCrvToCose[crv]);
+
+      if (jwk.x !== undefined) {
+        coseKey.set(CoseKeyParamLabel.X, Convert.base64Url(jwk.x as string).toUint8Array());
+      }
+      if (jwk.d !== undefined) {
+        coseKey.set(CoseKeyParamLabel.D, Convert.base64Url(jwk.d as string).toUint8Array());
+      }
+    } else if (jwk.kty === 'EC') {
+      coseKey.set(CoseKeyLabel.Kty, CoseKeyType.EC2);
+
+      const crv = jwk.crv;
+      if (crv === undefined || !(crv in jwkCrvToCose)) {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `CoseKey: unsupported EC curve '${crv}'`);
+      }
+      coseKey.set(CoseKeyParamLabel.Crv, jwkCrvToCose[crv]);
+
+      if (jwk.x !== undefined) {
+        coseKey.set(CoseKeyParamLabel.X, Convert.base64Url(jwk.x as string).toUint8Array());
+      }
+      if (jwk.y !== undefined) {
+        coseKey.set(CoseKeyParamLabel.Y, Convert.base64Url(jwk.y as string).toUint8Array());
+      }
+      if (jwk.d !== undefined) {
+        coseKey.set(CoseKeyParamLabel.D, Convert.base64Url(jwk.d as string).toUint8Array());
+      }
+    } else {
+      throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `CoseKey: unsupported key type '${jwk.kty}'`);
+    }
+
+    if (jwk.kid !== undefined) {
+      coseKey.set(CoseKeyLabel.Kid, Convert.string(jwk.kid).toUint8Array());
+    }
+
+    if (jwk.alg !== undefined && jwk.alg in jwkAlgToCose) {
+      coseKey.set(CoseKeyLabel.Alg, jwkAlgToCose[jwk.alg]);
+    }
+
+    return coseKey;
+  }
+
+  /**
+   * Converts a COSE key Map to a JWK.
+   *
+   * @param coseKey - A Map with integer labels as keys (from CBOR decoding).
+   * @returns The equivalent JWK.
+   * @throws {CryptoError} If the COSE key type or curve is not supported.
+   */
+  public static toJwk(coseKey: Map<number, unknown>): Jwk {
+    const kty = coseKey.get(CoseKeyLabel.Kty) as number;
+
+    if (kty === CoseKeyType.OKP) {
+      const crv = coseKey.get(CoseKeyParamLabel.Crv) as number;
+      if (!(crv in coseCrvToJwk)) {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `CoseKey: unsupported COSE OKP curve ${crv}`);
+      }
+
+      const jwk: Jwk = {
+        kty : 'OKP',
+        crv : coseCrvToJwk[crv],
+      };
+
+      const x = coseKey.get(CoseKeyParamLabel.X) as Uint8Array | undefined;
+      if (x !== undefined) {
+        jwk.x = Convert.uint8Array(x).toBase64Url();
+      }
+
+      const d = coseKey.get(CoseKeyParamLabel.D) as Uint8Array | undefined;
+      if (d !== undefined) {
+        jwk.d = Convert.uint8Array(d).toBase64Url();
+      }
+
+      CoseKey.applyCommonFields(coseKey, jwk);
+      return jwk;
+
+    } else if (kty === CoseKeyType.EC2) {
+      const crv = coseKey.get(CoseKeyParamLabel.Crv) as number;
+      if (!(crv in coseCrvToJwk)) {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `CoseKey: unsupported COSE EC2 curve ${crv}`);
+      }
+
+      const jwk: Jwk = {
+        kty : 'EC',
+        crv : coseCrvToJwk[crv],
+      };
+
+      const x = coseKey.get(CoseKeyParamLabel.X) as Uint8Array | undefined;
+      if (x !== undefined) {
+        jwk.x = Convert.uint8Array(x).toBase64Url();
+      }
+
+      const y = coseKey.get(CoseKeyParamLabel.Y) as Uint8Array | undefined;
+      if (y !== undefined) {
+        jwk.y = Convert.uint8Array(y).toBase64Url();
+      }
+
+      const d = coseKey.get(CoseKeyParamLabel.D) as Uint8Array | undefined;
+      if (d !== undefined) {
+        jwk.d = Convert.uint8Array(d).toBase64Url();
+      }
+
+      CoseKey.applyCommonFields(coseKey, jwk);
+      return jwk;
+
+    } else {
+      throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `CoseKey: unsupported COSE key type ${kty}`);
+    }
+  }
+
+  /**
+   * Infers the COSE algorithm identifier from a JWK.
+   *
+   * If the JWK has an `alg` field, it is used directly. Otherwise, the algorithm
+   * is inferred from the key type and curve.
+   *
+   * @param jwk - The JWK to infer the algorithm from.
+   * @returns The COSE algorithm identifier.
+   * @throws {CryptoError} If the algorithm cannot be determined.
+   */
+  public static algorithmFromJwk(jwk: Jwk): CoseAlgorithm {
+    if (jwk.alg !== undefined && jwk.alg in jwkAlgToCose) {
+      return jwkAlgToCose[jwk.alg];
+    }
+
+    // Infer from key type and curve.
+    if (jwk.kty === 'OKP') {
+      if (jwk.crv === 'Ed25519' || jwk.crv === 'Ed448') {
+        return CoseAlgorithm.EdDSA;
+      }
+    } else if (jwk.kty === 'EC') {
+      switch (jwk.crv) {
+        case 'P-256': return CoseAlgorithm.ES256;
+        case 'P-384': return CoseAlgorithm.ES384;
+        case 'P-521': return CoseAlgorithm.ES512;
+        case 'secp256k1': return CoseAlgorithm.ES256K;
+      }
+    }
+
+    throw new CryptoError(
+      CryptoErrorCode.AlgorithmNotSupported,
+      `CoseKey: cannot determine COSE algorithm for key type '${jwk.kty}' curve '${jwk.crv}'`
+    );
+  }
+
+  /**
+   * Maps a COSE algorithm identifier to a JWK algorithm name.
+   *
+   * @param alg - The COSE algorithm identifier.
+   * @returns The JWK algorithm name.
+   * @throws {CryptoError} If the algorithm is not supported.
+   */
+  public static algorithmToJwk(alg: CoseAlgorithm): string {
+    if (alg in coseAlgToJwk) {
+      return coseAlgToJwk[alg];
+    }
+    throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `CoseKey: unsupported COSE algorithm ${alg}`);
+  }
+
+  /**
+   * Applies common COSE key fields (kid, alg) to a JWK.
+   */
+  private static applyCommonFields(coseKey: Map<number, unknown>, jwk: Jwk): void {
+    const kid = coseKey.get(CoseKeyLabel.Kid) as Uint8Array | undefined;
+    if (kid !== undefined) {
+      jwk.kid = Convert.uint8Array(kid).toString();
+    }
+
+    const alg = coseKey.get(CoseKeyLabel.Alg) as number | undefined;
+    if (alg !== undefined && alg in coseAlgToJwk) {
+      jwk.alg = coseAlgToJwk[alg];
+    }
+  }
+}