@enbox/crypto 0.0.3 → 0.0.5

package/src/cose/eat.ts

@@ -0,0 +1,368 @@
+import type { CoseSign1ProtectedHeader } from './cose-sign1.js';
+import type { Jwk } from '../jose/jwk.js';
+
+import { Cbor } from './cbor.js';
+import { CoseSign1 } from './cose-sign1.js';
+import { CryptoError, CryptoErrorCode } from '../crypto-error.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 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 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 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 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.
+   */
+  public static decode({ token }: EatDecodeParams): EatDecodeResult {
+    // Decode the COSE_Sign1 envelope.
+    const coseSign1 = CoseSign1.decode(token);
+
+    if (coseSign1.payload === null) {
+      throw new CryptoError(
+        CryptoErrorCode.InvalidEat,
+        'Eat: token has detached payload; use verifyAndDecode with the payload provided separately'
+      );
+    }
+
+    // Decode the CBOR payload into claims.
+    const claims = Eat.parseClaims(coseSign1.payload);
+
+    return {
+      protectedHeader: coseSign1.protectedHeader,
+      claims,
+    };
+  }
+
+  /**
+   * 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.
+   */
+  public static async verifyAndDecode(params: EatVerifyParams): Promise<EatDecodeResult> {
+    const { token, key, externalAad } = params;
+
+    // Verify the COSE_Sign1 signature.
+    const isValid = await CoseSign1.verify({
+      coseSign1: token,
+      key,
+      externalAad,
+    });
+
+    if (!isValid) {
+      throw new CryptoError(
+        CryptoErrorCode.InvalidEat,
+        'Eat: signature verification failed'
+      );
+    }
+
+    // Decode and return claims (signature is already verified).
+    return Eat.decode({ token });
+  }
+
+  /**
+   * 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(payload: Uint8Array): EatClaims {
+    let rawClaims: Map<number | string, unknown>;
+
+    try {
+      const decoded = Cbor.decode<unknown>(payload);
+      if (decoded instanceof Map) {
+        rawClaims = decoded as Map<number | string, unknown>;
+      } else if (typeof decoded === 'object' && decoded !== null) {
+        // Some encoders produce plain objects instead of Maps for maps with string keys.
+        rawClaims = new Map(Object.entries(decoded));
+      } else {
+        throw new Error('not a map');
+      }
+    } catch (error) {
+      if (error instanceof CryptoError) {
+        throw error;
+      }
+      throw new CryptoError(
+        CryptoErrorCode.InvalidEat,
+        'Eat: payload is not a valid CBOR map'
+      );
+    }
+
+    const claims: EatClaims = { rawClaims };
+
+    // Extract standard CWT claims.
+    const iss = rawClaims.get(EatClaimKey.Iss);
+    if (iss !== undefined) {
+      claims.iss = iss as string;
+    }
+
+    const sub = rawClaims.get(EatClaimKey.Sub);
+    if (sub !== undefined) {
+      claims.sub = sub as string;
+    }
+
+    const aud = rawClaims.get(EatClaimKey.Aud);
+    if (aud !== undefined) {
+      claims.aud = aud as string;
+    }
+
+    const exp = rawClaims.get(EatClaimKey.Exp);
+    if (exp !== undefined) {
+      claims.exp = exp as number;
+    }
+
+    const nbf = rawClaims.get(EatClaimKey.Nbf);
+    if (nbf !== undefined) {
+      claims.nbf = nbf as number;
+    }
+
+    const iat = rawClaims.get(EatClaimKey.Iat);
+    if (iat !== undefined) {
+      claims.iat = iat as number;
+    }
+
+    const cti = rawClaims.get(EatClaimKey.Cti);
+    if (cti !== undefined) {
+      claims.cti = cti as Uint8Array;
+    }
+
+    // Extract EAT-specific claims.
+    const nonce = rawClaims.get(EatClaimKey.Nonce);
+    if (nonce !== undefined) {
+      claims.nonce = nonce as Uint8Array | Uint8Array[];
+    }
+
+    const ueid = rawClaims.get(EatClaimKey.Ueid);
+    if (ueid !== undefined) {
+      claims.ueid = ueid as Uint8Array;
+    }
+
+    const hwmodel = rawClaims.get(EatClaimKey.Hwmodel);
+    if (hwmodel !== undefined) {
+      claims.hwmodel = hwmodel as Uint8Array;
+    }
+
+    const hwversion = rawClaims.get(EatClaimKey.Hwversion);
+    if (hwversion !== undefined) {
+      claims.hwversion = hwversion;
+    }
+
+    const dbgstat = rawClaims.get(EatClaimKey.Dbgstat);
+    if (dbgstat !== undefined) {
+      claims.dbgstat = dbgstat as EatDebugStatus;
+    }
+
+    const measres = rawClaims.get(EatClaimKey.Measres);
+    if (measres !== undefined) {
+      claims.measres = measres;
+    }
+
+    const submods = rawClaims.get(EatClaimKey.Submods);
+    if (submods !== undefined) {
+      claims.submods = submods as Map<string, unknown>;
+    }
+
+    return claims;
+  }
+}

package/src/crypto-error.ts

@@ -34,6 +34,12 @@ export enum CryptoErrorCode {
   /** 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',
 

package/src/index.ts

@@ -2,12 +2,21 @@ 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';
 export * from './algorithms/crypto-algorithm.js';
 export * from './algorithms/ecdsa.js';
 export * from './algorithms/eddsa.js';
+export * from './algorithms/hkdf.js';
+export * from './algorithms/pbkdf2.js';
 export * from './algorithms/sha-2.js';
+export * from './algorithms/x25519.js';
 
 export * from './jose/jwe.js';
 export * from './jose/jwk.js';
@@ -19,6 +28,7 @@ export * from './primitives/aes-ctr.js';
 export * from './primitives/aes-gcm.js';
 export * from './primitives/aes-kw.js';
 export * from './primitives/concat-kdf.js';
+export * from './primitives/ecies-secp256k1.js';
 export * from './primitives/ed25519.js';
 export * from './primitives/hkdf.js';
 export * from './primitives/secp256r1.js';

package/src/local-key-manager.ts

@@ -2,11 +2,11 @@ import type { KeyValueStore } from '@enbox/common';
 import { MemoryStore } from '@enbox/common';
 
 import type { CryptoAlgorithm } from './algorithms/crypto-algorithm.js';
-import type { CryptoApi } from './types/crypto-api.js';
 import type { Hasher } from './types/hasher.js';
 import type { Jwk } from './jose/jwk.js';
 import type { KeyIdentifier } from './types/identifier.js';
 import type { KeyImporterExporter } from './types/key-io.js';
+import type { KeyManager } from './types/crypto-api.js';
 import type { Signer } from './types/signer.js';
 import type { AsymmetricKeyGenerator, KeyGenerator } from './types/key-generator.js';
 import type { GetPublicKeyParams, SignParams, VerifyParams } from './types/params-direct.js';
@@ -24,6 +24,7 @@ import type {
 import { EcdsaAlgorithm } from './algorithms/ecdsa.js';
 import { EdDsaAlgorithm } from './algorithms/eddsa.js';
 import { Sha2Algorithm } from './algorithms/sha-2.js';
+import { X25519Algorithm } from './algorithms/x25519.js';
 import { computeJwkThumbprint, isPrivateJwk, KEY_URI_PREFIX_JWK } from './jose/jwk.js';
 
 /**
@@ -50,6 +51,10 @@ const supportedAlgorithms = {
   'SHA-256': {
     implementation : Sha2Algorithm,
     names          : ['SHA-256']
+  },
+  'X25519': {
+    implementation : X25519Algorithm,
+    names          : ['X25519']
   }
 } satisfies {
   [key: string]: {
@@ -104,11 +109,11 @@ export interface LocalKeyManagerGenerateKeyParams extends KmsGenerateKeyParams {
    * - `"Ed25519"`
    * - `"secp256k1"`
    */
-  algorithm: 'Ed25519' | 'secp256k1' | 'secp256r1';
+  algorithm: 'Ed25519' | 'secp256k1' | 'secp256r1' | 'X25519';
 }
 
 export class LocalKeyManager implements
-    CryptoApi,
+    KeyManager,
     KeyImporterExporter<KmsImportKeyParams, KeyIdentifier, KmsExportKeyParams> {
 
   /**
@@ -242,7 +247,7 @@ export class LocalKeyManager implements
    * @remarks
    * This method generates a {@link https://datatracker.ietf.org/doc/html/rfc3986 | URI}
    * (Uniform Resource Identifier) for the given JWK, which uniquely identifies the key across all
-   * `CryptoApi` implementations. The key URI is constructed by appending the
+   * `KeyManager` implementations. The key URI is constructed by appending the
    * {@link https://datatracker.ietf.org/doc/html/rfc7638 | JWK thumbprint} to the prefix
    * `urn:jwk:`. The JWK thumbprint is deterministically computed from the JWK and is consistent
    * regardless of property order or optional property inclusion in the JWK. This ensures that the

package/src/primitives/ecies-secp256k1.ts

@@ -0,0 +1,113 @@
+import { concatBytes } from '@noble/ciphers/utils';
+import { gcm } from '@noble/ciphers/aes';
+import { hkdf } from '@noble/hashes/hkdf';
+import { randomBytes } from '@noble/ciphers/webcrypto';
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { sha256 } from '@noble/hashes/sha256';
+
+/**
+ * AEAD tag length for AES-256-GCM (16 bytes / 128 bits).
+ */
+const AEAD_TAG_LENGTH = 16;
+
+/**
+ * Nonce length for AES-256-GCM encryption.
+ */
+const NONCE_LENGTH = 16;
+
+/**
+ * Output of an ECIES-SECP256K1 encryption operation.
+ */
+export type EciesSecp256k1EncryptionOutput = {
+  /** The AES-GCM initialization vector. */
+  initializationVector: Uint8Array;
+  /** The ephemeral secp256k1 public key (compressed, 33 bytes). */
+  ephemeralPublicKey: Uint8Array;
+  /** The encrypted data. */
+  ciphertext: Uint8Array;
+  /** The AES-GCM authentication tag (16 bytes). */
+  messageAuthenticationCode: Uint8Array;
+};
+
+/**
+ * Input required for ECIES-SECP256K1 decryption.
+ */
+export type EciesSecp256k1EncryptionInput = EciesSecp256k1EncryptionOutput & {
+  /** The recipient's secp256k1 private key (raw 32 bytes). */
+  privateKey: Uint8Array;
+};
+
+/**
+ * Browser-compatible ECIES (Elliptic Curve Integrated Encryption Scheme) using secp256k1.
+ *
+ * Wire-format compatible with `eciesjs` v0.4.x configured with
+ * `isEphemeralKeyCompressed: true, isHkdfKeyCompressed: false` (the default).
+ *
+ * Protocol:
+ *   1. Generate an ephemeral secp256k1 key pair.
+ *   2. ECDH shared secret (uncompressed point).
+ *   3. HKDF-SHA-256 key derivation: `hkdf(sha256, ephemeralPubUncompressed || sharedPointUncompressed)`.
+ *   4. AES-256-GCM encryption with random 16-byte nonce.
+ *
+ * All underlying primitives (`@noble/ciphers`, `@noble/curves`, `@noble/hashes`)
+ * are pure JavaScript and work in Node, Bun, and browsers.
+ */
+export class EciesSecp256k1 {
+  /**
+   * Encrypt plaintext for a given secp256k1 public key.
+   * @param publicKeyBytes - Recipient's public key (compressed 33 bytes or uncompressed 65 bytes).
+   * @param plaintext - The data to encrypt.
+   */
+  public static encrypt(publicKeyBytes: Uint8Array, plaintext: Uint8Array): EciesSecp256k1EncryptionOutput {
+    // Generate ephemeral key pair.
+    const ephemeralPrivateKey = secp256k1.utils.randomPrivateKey();
+    const ephemeralPubCompressed = secp256k1.getPublicKey(ephemeralPrivateKey, true);
+    const ephemeralPubUncompressed = secp256k1.getPublicKey(ephemeralPrivateKey, false);
+
+    // ECDH: shared point (uncompressed).
+    const sharedPointUncompressed = secp256k1.getSharedSecret(ephemeralPrivateKey, publicKeyBytes, false);
+
+    // HKDF-SHA-256: derive 32-byte symmetric key.
+    // eciesjs (isHkdfKeyCompressed=false): master = senderPubUncompressed || sharedPointUncompressed
+    const symmetricKey = hkdf(sha256, concatBytes(ephemeralPubUncompressed, sharedPointUncompressed), undefined, undefined, 32);
+
+    // AES-256-GCM encrypt.
+    const nonce = randomBytes(NONCE_LENGTH);
+    const ciphered = gcm(symmetricKey, nonce).encrypt(plaintext); // ciphertext || tag
+
+    return {
+      ephemeralPublicKey        : ephemeralPubCompressed,
+      initializationVector      : nonce,
+      messageAuthenticationCode : ciphered.subarray(ciphered.length - AEAD_TAG_LENGTH),
+      ciphertext                : ciphered.subarray(0, ciphered.length - AEAD_TAG_LENGTH),
+    };
+  }
+
+  /**
+   * Decrypt ciphertext produced by {@link EciesSecp256k1.encrypt}.
+   * @param input - The encryption output plus the recipient's private key.
+   */
+  public static decrypt(input: EciesSecp256k1EncryptionInput): Uint8Array {
+    const { privateKey, ephemeralPublicKey, initializationVector, messageAuthenticationCode, ciphertext } = input;
+
+    // Decompress ephemeral public key (HKDF needs uncompressed form).
+    const ephemeralPubUncompressed = secp256k1.ProjectivePoint.fromHex(ephemeralPublicKey).toRawBytes(false);
+
+    // ECDH: shared point (uncompressed).
+    const sharedPointUncompressed = secp256k1.getSharedSecret(privateKey, ephemeralPublicKey, false);
+
+    // HKDF-SHA-256: derive 32-byte symmetric key (same derivation as encrypt).
+    const symmetricKey = hkdf(sha256, concatBytes(ephemeralPubUncompressed, sharedPointUncompressed), undefined, undefined, 32);
+
+    // AES-256-GCM decrypt: reconstruct the wire format (ciphertext || tag).
+    const ciphered = concatBytes(ciphertext, messageAuthenticationCode);
+    return gcm(symmetricKey, Uint8Array.from(initializationVector)).decrypt(ciphered);
+  }
+
+  /**
+   * Whether the ephemeral public key is compressed (always true for this implementation).
+   */
+  public static get isEphemeralKeyCompressed(): boolean {
+    return true;
+  }
+}

package/src/primitives/x25519.ts

@@ -345,32 +345,25 @@ export class X25519 {
   }
 
   /**
-   * Computes an RFC6090-compliant Elliptic Curve Diffie-Hellman (ECDH) shared secret
-   * using secp256k1 private and public keys in JSON Web Key (JWK) format.
+   * Computes an X25519 Elliptic Curve Diffie-Hellman (ECDH) shared secret
+   * using X25519 private and public keys in JSON Web Key (JWK) format.
    *
    * @remarks
    * This method facilitates the ECDH key agreement protocol, which is a method of securely
    * deriving a shared secret between two parties based on their private and public keys.
    * It takes the private key of one party (privateKeyA) and the public key of another
-   * party (publicKeyB) to compute a shared secret. The shared secret is derived from the
-   * x-coordinate of the elliptic curve point resulting from the multiplication of the
-   * public key with the private key.
-   *
-   * Note: When performing Elliptic Curve Diffie-Hellman (ECDH) key agreement,
-   * the resulting shared secret is a point on the elliptic curve, which
-   * consists of an x-coordinate and a y-coordinate. With a 256-bit curve like
-   * secp256k1, each of these coordinates is 32 bytes (256 bits) long. However,
-   * in the ECDH process, it's standard practice to use only the x-coordinate
-   * of the shared secret point as the resulting shared key. This is because
-   * the y-coordinate does not add to the entropy of the key, and both parties
-   * can independently compute the x-coordinate.  Consquently, this implementation
-   * omits the y-coordinate for simplicity and standard compliance.
+   * party (publicKeyB) to compute a shared secret. The shared secret is the raw output
+   * of the X25519 function as defined in RFC 7748.
+   *
+   * Note: Unlike Weierstrass curves (e.g., secp256k1), X25519 is a Montgomery curve
+   * where the ECDH output is a single 32-byte scalar value, not an (x, y) point.
+   * The result is used directly as the shared secret.
    *
    * @example
    * ```ts
    * const privateKeyA = { ... }; // A Jwk object for party A
    * const publicKeyB = { ... }; // A PublicKeyJwk object for party B
-   * const sharedSecret = await Secp256k1.sharedSecret({
+   * const sharedSecret = await X25519.sharedSecret({
    *   privateKeyA,
    *   publicKeyB
    * });