@enbox/dwn-sdk-js 0.0.1 → 0.0.3

package/src/utils/protocols.ts

@@ -1,10 +1,69 @@
 import type { DerivedPrivateJwk } from '../utils/hd-key.js';
-import type { PrivateJwk } from '../types/jose-types.js';
+import type { EncryptionKeyDeriver } from '../types/encryption-types.js';
+import type { PrivateKeyJwk } from '../types/jose-types.js';
 import type { ProtocolDefinition, ProtocolRuleSet } from '../types/protocols-types.js';
 
 import { Secp256k1 } from './secp256k1.js';
 import { HdKey, KeyDerivationScheme } from '../utils/hd-key.js';
 
+/**
+ * Result of parsing a cross-protocol reference in `alias:path` format.
+ */
+export type CrossProtocolRef = {
+  /** The alias key from the `uses` map. */
+  alias: string;
+  /** The protocol path within the referenced protocol. */
+  protocolPath: string;
+};
+
+/**
+ * Parses a string that may be a cross-protocol reference in `alias:path` format.
+ * Returns `undefined` if the string is a local (non-cross-protocol) reference.
+ *
+ * Examples:
+ * - `"threads:thread"` → `{ alias: "threads", protocolPath: "thread" }`
+ * - `"threads:thread/participant"` → `{ alias: "threads", protocolPath: "thread/participant" }`
+ * - `"thread/comment"` → `undefined` (local reference, no alias)
+ */
+export function parseCrossProtocolRef(ref: string): CrossProtocolRef | undefined {
+  const colonIndex = ref.indexOf(':');
+  if (colonIndex === -1) {
+    return undefined;
+  }
+
+  const alias = ref.substring(0, colonIndex);
+  const protocolPath = ref.substring(colonIndex + 1);
+
+  return { alias, protocolPath };
+}
+
+/**
+ * Returns `true` if the given string contains a `:` indicating a cross-protocol reference.
+ */
+export function isCrossProtocolRef(ref: string): boolean {
+  return ref.includes(':');
+}
+
+/**
+ * Gets the rule set at a given protocol path within a protocol definition's structure tree.
+ * Returns `undefined` if the path does not exist.
+ */
+export function getRuleSetAtPath(protocolPath: string, structure: { [key: string]: ProtocolRuleSet }): ProtocolRuleSet | undefined {
+  const segments = protocolPath.split('/');
+  let current: ProtocolRuleSet | undefined;
+  let currentLevel: { [key: string]: ProtocolRuleSet } = structure;
+
+  for (const segment of segments) {
+    current = currentLevel[segment];
+    if (current === undefined) {
+      return undefined;
+    }
+    currentLevel = current as { [key: string]: ProtocolRuleSet };
+  }
+
+  return current;
+}
+
 /**
  * Class containing Protocol related utility methods.
  */
@@ -13,14 +72,73 @@ export class Protocols {
    * Derives public encryptions keys and inject it in the `$encryption` property for each protocol path segment of the given Protocol definition,
    * then returns the final encryption-enabled protocol definition.
    * NOTE: The original definition passed in is unmodified.
+   *
+   * `$ref` nodes (cross-protocol attachment points) are skipped during `$encryption` injection
+   * because their records belong to the referenced protocol, whose own encryption keys govern them.
+   * Children of `$ref` nodes are still processed because they belong to the composing protocol.
+   *
+   * Overload 1 (callback-based): Accepts an EncryptionKeyDeriver that performs
+   * key derivation internally. The private key never leaves the caller's boundary.
+   */
+  public static async deriveAndInjectPublicEncryptionKeys(
+    protocolDefinition: ProtocolDefinition,
+    keyDeriver: EncryptionKeyDeriver,
+  ): Promise<ProtocolDefinition>;
+
+  /**
+   * Overload 2 (raw-key, existing): Takes rootKeyId and raw PrivateKeyJwk directly.
+   * Preserved for backward compatibility with tests and non-KMS callers.
    */
   public static async deriveAndInjectPublicEncryptionKeys(
     protocolDefinition: ProtocolDefinition,
     rootKeyId: string,
-    privateJwk: PrivateJwk
+    privateJwk: PrivateKeyJwk,
+  ): Promise<ProtocolDefinition>;
+
+  // Implementation dispatches based on argument type
+  public static async deriveAndInjectPublicEncryptionKeys(
+    protocolDefinition: ProtocolDefinition,
+    rootKeyIdOrKeyDeriver: string | EncryptionKeyDeriver,
+    privateJwk?: PrivateKeyJwk,
   ): Promise<ProtocolDefinition> {
     // clone before modify
-    const encryptionEnabledProtocolDefinition = JSON.parse(JSON.stringify(protocolDefinition)) as ProtocolDefinition;
+    const clone = JSON.parse(JSON.stringify(protocolDefinition)) as ProtocolDefinition;
+
+    if (typeof rootKeyIdOrKeyDeriver !== 'string') {
+      // Callback-based path
+      const keyDeriver = rootKeyIdOrKeyDeriver;
+      const basePath = [KeyDerivationScheme.ProtocolPath, protocolDefinition.protocol];
+
+      async function injectKeysViaCallback(
+        ruleSet: ProtocolRuleSet, parentPath: string[],
+      ): Promise<void> {
+        for (const key in ruleSet) {
+          if (!key.startsWith('$')) {
+            const currentPath = [...parentPath, key];
+
+            // Skip $ref nodes — they are governed by the referenced protocol's encryption keys.
+            // Still recurse into children, which belong to the composing protocol.
+            if (ruleSet[key].$ref !== undefined) {
+              await injectKeysViaCallback(ruleSet[key], currentPath);
+              continue;
+            }
+
+            const publicKeyJwk = await keyDeriver.derivePublicKey(currentPath);
+            ruleSet[key].$encryption = {
+              rootKeyId: keyDeriver.rootKeyId,
+              publicKeyJwk,
+            };
+            await injectKeysViaCallback(ruleSet[key], currentPath);
+          }
+        }
+      }
+
+      await injectKeysViaCallback(clone.structure, basePath);
+      return clone;
+    }
+
+    // Raw-key path (existing logic, unchanged)
+    const rootKeyId = rootKeyIdOrKeyDeriver;
 
     // a function that recursively creates and adds `$encryption` property to every rule set
     async function addEncryptionProperty(ruleSet: ProtocolRuleSet, parentKey: DerivedPrivateJwk): Promise<void> {
@@ -28,6 +146,14 @@ export class Protocols {
         // if we encounter a nested rule set (a property name that doesn't begin with '$'), recursively inject the `$encryption` property
         if (!key.startsWith('$')) {
           const derivedPrivateKey = await HdKey.derivePrivateKey(parentKey, [key]);
+
+          // Skip $ref nodes — they are governed by the referenced protocol's encryption keys.
+          // Still recurse into children, which belong to the composing protocol.
+          if (ruleSet[key].$ref !== undefined) {
+            await addEncryptionProperty(ruleSet[key], derivedPrivateKey);
+            continue;
+          }
+
           const publicKeyJwk = await Secp256k1.getPublicJwk(derivedPrivateKey.derivedPrivateKey);
 
           ruleSet[key].$encryption = { rootKeyId, publicKeyJwk };
@@ -39,12 +165,12 @@ export class Protocols {
     // inject encryption property starting from each root level record type
     const rootKey: DerivedPrivateJwk = {
       derivationScheme  : KeyDerivationScheme.ProtocolPath,
-      derivedPrivateKey : privateJwk,
+      derivedPrivateKey : privateJwk!,
       rootKeyId
     };
     const protocolLevelDerivedKey = await HdKey.derivePrivateKey(rootKey, [KeyDerivationScheme.ProtocolPath, protocolDefinition.protocol]);
-    await addEncryptionProperty(encryptionEnabledProtocolDefinition.structure, protocolLevelDerivedKey);
+    await addEncryptionProperty(clone.structure, protocolLevelDerivedKey);
 
-    return encryptionEnabledProtocolDefinition;
+    return clone;
   }
 }

package/src/utils/records.ts

@@ -1,8 +1,8 @@
 import type { DerivedPrivateJwk } from './hd-key.js';
-import type { Readable } from 'readable-stream';
+import type { KeyDecrypter } from '../types/encryption-types.js';
 import type { Filter, KeyValues, StartsWithFilter } from '../types/query-types.js';
-import type { GenericMessage, GenericSignaturePayload } from '../types/message-types.js';
-import type { RecordsDeleteMessage, RecordsFilter, RecordsQueryMessage, RecordsReadMessage, RecordsSubscribeMessage, RecordsWriteDescriptor, RecordsWriteMessage, RecordsWriteTags, RecordsWriteTagsFilter } from '../types/records-types.js';
+import type { GenericMessage, GenericSignaturePayload, MessageSort } from '../types/message-types.js';
+import type { RecordsCountMessage, RecordsDeleteMessage, RecordsFilter, RecordsQueryMessage, RecordsReadMessage, RecordsSubscribeMessage, RecordsWriteDescriptor, RecordsWriteMessage, RecordsWriteTags, RecordsWriteTagsFilter } from '../types/records-types.js';
 
 import { DateSort } from '../types/records-types.js';
 import { Encoder } from './encoder.js';
@@ -13,6 +13,7 @@ import { Message } from '../core/message.js';
 import { PermissionGrant } from '../protocols/permission-grant.js';
 import { removeUndefinedProperties } from './object.js';
 import { Secp256k1 } from './secp256k1.js';
+import { SortDirection } from '../types/query-types.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 import { HdKey, KeyDerivationScheme } from './hd-key.js';
@@ -35,47 +36,96 @@ export class Records {
   }
 
   /**
-   * Decrypts the encrypted data in a message reply using the given ancestor private key.
+   * Decrypts the encrypted data in a message reply.
+   *
+   * Overload 1 (callback-based): Accepts a KeyDecrypter that performs
+   * HKDF derivation + ECIES decryption internally.
+   */
+  public static async decrypt(
+    recordsWrite: RecordsWriteMessage,
+    keyDecrypter: KeyDecrypter,
+    cipherStream: ReadableStream<Uint8Array>,
+  ): Promise<ReadableStream<Uint8Array>>;
+
+  /**
+   * Overload 2 (raw-key, existing): Takes DerivedPrivateJwk directly.
    * @param ancestorPrivateKey Any ancestor private key in the key derivation path.
    */
   public static async decrypt(
     recordsWrite: RecordsWriteMessage,
     ancestorPrivateKey: DerivedPrivateJwk,
-    cipherStream: Readable
-  ): Promise<Readable> {
+    cipherStream: ReadableStream<Uint8Array>,
+  ): Promise<ReadableStream<Uint8Array>>;
+
+  // Implementation dispatches based on argument type
+  public static async decrypt(
+    recordsWrite: RecordsWriteMessage,
+    keyOrDecrypter: DerivedPrivateJwk | KeyDecrypter,
+    cipherStream: ReadableStream<Uint8Array>,
+  ): Promise<ReadableStream<Uint8Array>> {
     const { encryption } = recordsWrite;
+    const isCallback = 'decrypt' in keyOrDecrypter;
 
-    // look for an encrypted symmetric key that is encrypted by the public key corresponding to the given private key
+    // Find matching key encryption entry
     const matchingEncryptedKey = encryption!.keyEncryption.find(key =>
-      key.rootKeyId === ancestorPrivateKey.rootKeyId &&
-      key.derivationScheme === ancestorPrivateKey.derivationScheme
+      key.rootKeyId === keyOrDecrypter.rootKeyId &&
+      key.derivationScheme === keyOrDecrypter.derivationScheme
     );
     if (matchingEncryptedKey === undefined) {
       throw new DwnError(
         DwnErrorCode.RecordsDecryptNoMatchingKeyEncryptedFound,
         `Unable to find a symmetric key encrypted using key \
-        with ID '${ancestorPrivateKey.rootKeyId}' and '${ancestorPrivateKey.derivationScheme}' derivation scheme.`
+        with ID '${keyOrDecrypter.rootKeyId}' and '${keyOrDecrypter.derivationScheme}' derivation scheme.`
       );
     }
 
-    const fullDerivationPath = Records.constructKeyDerivationPath(matchingEncryptedKey.derivationScheme, recordsWrite);
+    // Construct the full derivation path (reused for both paths)
+    const fullDerivationPath = Records.constructKeyDerivationPath(
+      matchingEncryptedKey.derivationScheme, recordsWrite,
+    );
+
+    let dataEncryptionKey: Uint8Array;
 
-    // NOTE: right now only `ECIES-ES256K` algorithm is supported for asymmetric encryption,
-    // so we will assume that's the algorithm without additional switch/if statements
-    const leafPrivateKey = await Records.derivePrivateKey(ancestorPrivateKey, fullDerivationPath);
-    const encryptedKeyBytes = Encoder.base64UrlToBytes(matchingEncryptedKey.encryptedKey);
-    const ephemeralPublicKey = Secp256k1.publicJwkToBytes(matchingEncryptedKey.ephemeralPublicKey);
-    const keyEncryptionInitializationVector = Encoder.base64UrlToBytes(matchingEncryptedKey.initializationVector);
-    const messageAuthenticationCode = Encoder.base64UrlToBytes(matchingEncryptedKey.messageAuthenticationCode);
-    const dataEncryptionKey = await Encryption.eciesSecp256k1Decrypt({
-      ciphertext           : encryptedKeyBytes,
-      ephemeralPublicKey,
-      initializationVector : keyEncryptionInitializationVector,
-      messageAuthenticationCode,
-      privateKey           : leafPrivateKey
-    });
+    if (isCallback) {
+      // Callback-based: delegate HKDF + ECIES to the KeyDecrypter
+      const encryptedKeyBytes = Encoder.base64UrlToBytes(
+        matchingEncryptedKey.encryptedKey,
+      );
+      const ephemeralPublicKeyBytes = Secp256k1.publicJwkToBytes(
+        matchingEncryptedKey.ephemeralPublicKey,
+      );
+      const iv = Encoder.base64UrlToBytes(
+        matchingEncryptedKey.initializationVector,
+      );
+      const mac = Encoder.base64UrlToBytes(
+        matchingEncryptedKey.messageAuthenticationCode,
+      );
 
+      dataEncryptionKey = await keyOrDecrypter.decrypt(fullDerivationPath, {
+        ciphertext                : encryptedKeyBytes,
+        ephemeralPublicKey        : ephemeralPublicKeyBytes,
+        initializationVector      : iv,
+        messageAuthenticationCode : mac,
+      });
+    } else {
+      // Raw-key path (existing logic, unchanged)
+      // NOTE: right now only `ECIES-ES256K` algorithm is supported for asymmetric encryption,
+      // so we will assume that's the algorithm without additional switch/if statements
+      const leafPrivateKey = await Records.derivePrivateKey(keyOrDecrypter, fullDerivationPath);
+      const encryptedKeyBytes = Encoder.base64UrlToBytes(matchingEncryptedKey.encryptedKey);
+      const ephemeralPublicKey = Secp256k1.publicJwkToBytes(matchingEncryptedKey.ephemeralPublicKey);
+      const keyEncryptionInitializationVector = Encoder.base64UrlToBytes(matchingEncryptedKey.initializationVector);
+      const messageAuthenticationCode = Encoder.base64UrlToBytes(matchingEncryptedKey.messageAuthenticationCode);
+      dataEncryptionKey = await Encryption.eciesSecp256k1Decrypt({
+        ciphertext           : encryptedKeyBytes,
+        ephemeralPublicKey,
+        initializationVector : keyEncryptionInitializationVector,
+        messageAuthenticationCode,
+        privateKey           : leafPrivateKey
+      });
+    }
 
+    // AES decrypt data (shared by both paths)
     // NOTE: right now only `A256CTR` algorithm is supported for symmetric encryption,
     // so we will assume that's the algorithm without additional switch/if statements
     const dataEncryptionInitializationVector = Encoder.base64UrlToBytes(encryption!.initializationVector);
@@ -130,6 +180,11 @@ export class Records {
 
   /**
    * Constructs the full key derivation path using `protocolPath` scheme.
+   *
+   * The path is `[scheme, protocol, ...protocolPathSegments]`. Because each record's `protocol`
+   * field always refers to the protocol it was written under, records in composed protocols
+   * naturally derive independent key hierarchies — a `$ref` parent (referenced protocol) and
+   * its children (composing protocol) use different protocol URIs and thus different key trees.
    */
   public static constructKeyDerivationPathUsingProtocolPathScheme(descriptor: RecordsWriteDescriptor): string[] {
     // ensure `protocol` is defined
@@ -153,6 +208,13 @@ export class Records {
 
   /**
    * Constructs the full key derivation path using `protocolContext` scheme.
+   *
+   * NOTE on protocol composition: When a context tree spans two protocols via `$ref` composition,
+   * the root `contextId` segment (the `$ref` parent record's ID) is shared across both protocols.
+   * This means ProtocolContext-encrypted records from the composing protocol and the referenced
+   * protocol derive the same context key. This is by design — it enables multi-party access within
+   * a shared context (e.g., thread participants can decrypt messages from both the threads protocol
+   * and composing protocols that attach to those threads).
    */
   public static constructKeyDerivationPathUsingProtocolContextScheme(contextId: string | undefined): string[] {
     if (contextId === undefined) {
@@ -162,7 +224,7 @@ export class Records {
       );
     }
 
-    // TODO: issue #683 -Extend key derivation support to include the full contextId (https://github.com/TBD54566975/dwn-sdk-js/issues/683)
+    // TODO: issue #683 -Extend key derivation support to include the full contextId (https://github.com/enboxorg/enbox/issues/683)
     const firstContextSegment = contextId.split('/')[0];
 
     const fullDerivationPath = [
@@ -198,10 +260,11 @@ export class Records {
    *       so we will only derive SECP256K1 key without additional conditional checks
    */
   public static async derivePrivateKey(ancestorPrivateKey: DerivedPrivateJwk, fullDescendantDerivationPath: string[]): Promise<Uint8Array> {
-    if (ancestorPrivateKey.derivedPrivateKey.crv !== 'secp256k1') {
+    const crv = 'crv' in ancestorPrivateKey.derivedPrivateKey ? ancestorPrivateKey.derivedPrivateKey.crv : undefined;
+    if (crv !== 'secp256k1') {
       throw new DwnError(
         DwnErrorCode.RecordsDerivePrivateKeyUnSupportedCurve,
-        `Curve ${ancestorPrivateKey.derivedPrivateKey.crv} is not supported.`
+        `Curve ${crv} is not supported.`
       );
     }
 
@@ -388,7 +451,7 @@ export class Records {
    *                              Passed purely as a performance optimization so we don't have to decode the owner signature payload again.
    */
   public static async validateDelegatedGrantReferentialIntegrity(
-    message: RecordsReadMessage | RecordsQueryMessage | RecordsWriteMessage | RecordsDeleteMessage | RecordsSubscribeMessage,
+    message: RecordsCountMessage | RecordsReadMessage | RecordsQueryMessage | RecordsWriteMessage | RecordsDeleteMessage | RecordsSubscribeMessage,
     authorSignaturePayload: GenericSignaturePayload | undefined,
     ownerSignaturePayload?: GenericSignaturePayload | undefined
   ): Promise<void> {
@@ -479,6 +542,32 @@ export class Records {
     }
   }
 
+  /**
+   * Convert a `DateSort` value to a `MessageSort` object accepted by the `MessageStore`.
+   * Defaults to `messageTimestamp` descending (most recently updated first) when no sort is given.
+   *
+   * @param dateSort the optional `DateSort` value.
+   * @returns a `MessageSort` for `MessageStore` sorting.
+   */
+  public static convertDateSort(dateSort?: DateSort): MessageSort {
+    switch (dateSort) {
+    case DateSort.CreatedAscending:
+      return { dateCreated: SortDirection.Ascending };
+    case DateSort.CreatedDescending:
+      return { dateCreated: SortDirection.Descending };
+    case DateSort.PublishedAscending:
+      return { datePublished: SortDirection.Ascending };
+    case DateSort.PublishedDescending:
+      return { datePublished: SortDirection.Descending };
+    case DateSort.UpdatedAscending:
+      return { messageTimestamp: SortDirection.Ascending };
+    case DateSort.UpdatedDescending:
+      return { messageTimestamp: SortDirection.Descending };
+    default:
+      return { messageTimestamp: SortDirection.Descending };
+    }
+  }
+
   /**
    * Determines if signature payload contains a protocolRole and should be authorized as such.
    */

package/src/utils/secp256k1.ts

@@ -1,4 +1,5 @@
-import type { PrivateJwk, PublicJwk } from '../types/jose-types.js';
+import type { JwkParamsEcPrivate, JwkParamsEcPublic } from '@enbox/crypto';
+import type { PrivateKeyJwk, PublicKeyJwk } from '../types/jose-types.js';
 
 import * as secp256k1 from '@noble/secp256k1';
 
@@ -15,8 +16,8 @@ export class Secp256k1 {
    * Validates the given JWK is a SECP256K1 key.
    * @throws {Error} if fails validation.
    */
-  public static validateKey(jwk: PrivateJwk | PublicJwk): void {
-    if (jwk.kty !== 'EC' || jwk.crv !== 'secp256k1') {
+  public static validateKey(jwk: PrivateKeyJwk | PublicKeyJwk): void {
+    if (jwk.kty !== 'EC' || (jwk as JwkParamsEcPublic).crv !== 'secp256k1') {
       throw new DwnError(DwnErrorCode.Secp256k1KeyNotValid, 'Invalid SECP256K1 JWK: `kty` MUST be `EC`. `crv` MUST be `secp256k1`');
     }
   }
@@ -24,7 +25,7 @@ export class Secp256k1 {
   /**
    * Converts a public key in bytes into a JWK.
    */
-  public static async publicKeyToJwk(publicKeyBytes: Uint8Array): Promise<PublicJwk> {
+  public static async publicKeyToJwk(publicKeyBytes: Uint8Array): Promise<PublicKeyJwk> {
   // ensure public key is in uncompressed format so we can convert it into both x and y value
     let uncompressedPublicKeyBytes;
     if (publicKeyBytes.byteLength === 33) {
@@ -43,7 +44,7 @@ export class Secp256k1 {
     const x = Encoder.bytesToBase64Url(uncompressedPublicKeyBytes.subarray(1, 33));
     const y = Encoder.bytesToBase64Url(uncompressedPublicKeyBytes.subarray(33, 65));
 
-    const publicJwk: PublicJwk = {
+    const publicJwk: PublicKeyJwk = {
       alg : 'ES256K',
       kty : 'EC',
       crv : 'secp256k1',
@@ -57,21 +58,22 @@ export class Secp256k1 {
   /**
    * Converts a private key in bytes into a JWK.
    */
-  public static async privateKeyToJwk(privateKeyBytes: Uint8Array): Promise<PrivateJwk> {
+  public static async privateKeyToJwk(privateKeyBytes: Uint8Array): Promise<PrivateKeyJwk> {
     const publicKeyBytes = await Secp256k1.getPublicKey(privateKeyBytes);
 
     const jwk = await Secp256k1.publicKeyToJwk(publicKeyBytes);
-    (jwk as PrivateJwk).d = Encoder.bytesToBase64Url(privateKeyBytes);
+    (jwk as JwkParamsEcPrivate).d = Encoder.bytesToBase64Url(privateKeyBytes);
 
-    return jwk as PrivateJwk;
+    return jwk as PrivateKeyJwk;
   }
 
   /**
    * Creates a compressed key in raw bytes from the given SECP256K1 JWK.
    */
-  public static publicJwkToBytes(publicJwk: PublicJwk): Uint8Array {
-    const x = Encoder.base64UrlToBytes(publicJwk.x);
-    const y = Encoder.base64UrlToBytes(publicJwk.y!);
+  public static publicJwkToBytes(publicJwk: PublicKeyJwk): Uint8Array {
+    const ecJwk = publicJwk as JwkParamsEcPublic;
+    const x = Encoder.base64UrlToBytes(ecJwk.x);
+    const y = Encoder.base64UrlToBytes(ecJwk.y!);
 
     return secp256k1.ProjectivePoint.fromAffine({
       x : secp256k1.etc.bytesToNumberBE(x),
@@ -82,15 +84,15 @@ export class Secp256k1 {
   /**
    * Creates a private key in raw bytes from the given SECP256K1 JWK.
    */
-  public static privateJwkToBytes(privateJwk: PrivateJwk): Uint8Array {
-    const privateKey = Encoder.base64UrlToBytes(privateJwk.d);
+  public static privateJwkToBytes(privateJwk: PrivateKeyJwk): Uint8Array {
+    const privateKey = Encoder.base64UrlToBytes((privateJwk as JwkParamsEcPrivate).d);
     return privateKey;
   }
 
   /**
    * Signs the provided content using the provided JWK.
    */
-  public static async sign(content: Uint8Array, privateJwk: PrivateJwk): Promise<Uint8Array> {
+  public static async sign(content: Uint8Array, privateJwk: PrivateKeyJwk): Promise<Uint8Array> {
     Secp256k1.validateKey(privateJwk);
 
     // the underlying lib expects us to hash the content ourselves:
@@ -105,7 +107,7 @@ export class Secp256k1 {
    * Verifies a signature against the provided payload hash and public key.
    * @returns a boolean indicating whether the signature is valid.
    */
-  public static async verify(content: Uint8Array, signature: Uint8Array, publicJwk: PublicJwk): Promise<boolean> {
+  public static async verify(content: Uint8Array, signature: Uint8Array, publicJwk: PublicKeyJwk): Promise<boolean> {
     Secp256k1.validateKey(publicJwk);
 
     const publicKeyBytes = Secp256k1.publicJwkToBytes(publicJwk);
@@ -116,13 +118,13 @@ export class Secp256k1 {
   /**
    * Generates a random key pair in JWK format.
    */
-  public static async generateKeyPair(): Promise<{publicJwk: PublicJwk, privateJwk: PrivateJwk}> {
+  public static async generateKeyPair(): Promise<{publicJwk: PublicKeyJwk, privateJwk: PrivateKeyJwk}> {
     const privateKeyBytes = secp256k1.utils.randomPrivateKey();
     const publicKeyBytes = secp256k1.getPublicKey(privateKeyBytes, false); // `false` = uncompressed
 
     const d = Encoder.bytesToBase64Url(privateKeyBytes);
-    const publicJwk: PublicJwk = await Secp256k1.publicKeyToJwk(publicKeyBytes);
-    const privateJwk: PrivateJwk = { ...publicJwk, d };
+    const publicJwk: PublicKeyJwk = await Secp256k1.publicKeyToJwk(publicKeyBytes);
+    const privateJwk: PrivateKeyJwk = { ...publicJwk, d };
 
     return { publicJwk, privateJwk };
   }
@@ -148,10 +150,10 @@ export class Secp256k1 {
   /**
    * Gets the public JWK of the given private JWK.
    */
-  public static async getPublicJwk(privateKeyJwk: PrivateJwk): Promise<PublicJwk> {
+  public static async getPublicJwk(privateKeyJwk: PrivateKeyJwk): Promise<PublicKeyJwk> {
     // strip away `d`
-    const { d: _d, ...publicKey } = privateKeyJwk;
-    return publicKey;
+    const { d: _d, ...publicKey } = privateKeyJwk as JwkParamsEcPrivate;
+    return publicKey as PublicKeyJwk;
   }
 }
 

package/src/utils/secp256r1.ts

@@ -1,4 +1,5 @@
-import type { PrivateJwk, PublicJwk } from '../types/jose-types.js';
+import type { JwkParamsEcPrivate, JwkParamsEcPublic } from '@enbox/crypto';
+import type { PrivateKeyJwk, PublicKeyJwk } from '../types/jose-types.js';
 
 import { p256, secp256r1 } from '@noble/curves/p256';
 
@@ -17,8 +18,8 @@ export class Secp256r1 {
    * Validates the given JWK is a SECP256R1 key.
    * @throws {Error} if fails validation.
    */
-  public static validateKey(jwk: PrivateJwk | PublicJwk): void {
-    if (jwk.kty !== 'EC' || jwk.crv !== 'P-256') {
+  public static validateKey(jwk: PrivateKeyJwk | PublicKeyJwk): void {
+    if (jwk.kty !== 'EC' || (jwk as JwkParamsEcPublic).crv !== 'P-256') {
       throw new DwnError(
         DwnErrorCode.Secp256r1KeyNotValid,
         'Invalid SECP256R1 JWK: `kty` MUST be `EC`. `crv` MUST be `P-256`'
@@ -31,7 +32,7 @@ export class Secp256r1 {
    */
   public static async publicKeyToJwk(
     publicKeyBytes: Uint8Array
-  ): Promise<PublicJwk> {
+  ): Promise<PublicKeyJwk> {
     // ensure public key is in uncompressed format so we can convert it into both x and y value
     let uncompressedPublicKeyBytes;
     if (publicKeyBytes.byteLength === 33) {
@@ -54,7 +55,7 @@ export class Secp256r1 {
       uncompressedPublicKeyBytes.subarray(33, 65)
     );
 
-    const publicJwk: PublicJwk = {
+    const publicJwk: PublicKeyJwk = {
       alg : 'ES256',
       kty : 'EC',
       crv : 'P-256',
@@ -68,8 +69,8 @@ export class Secp256r1 {
   /**
    * Creates a private key in raw bytes from the given SECP256R1 JWK.
    */
-  public static privateJwkToBytes(privateJwk: PrivateJwk): Uint8Array {
-    const privateKey = Encoder.base64UrlToBytes(privateJwk.d);
+  public static privateJwkToBytes(privateJwk: PrivateKeyJwk): Uint8Array {
+    const privateKey = Encoder.base64UrlToBytes((privateJwk as JwkParamsEcPrivate).d);
     return privateKey;
   }
 
@@ -79,7 +80,7 @@ export class Secp256r1 {
    */
   public static async sign(
     content: Uint8Array,
-    privateJwk: PrivateJwk
+    privateJwk: PrivateKeyJwk
   ): Promise<Uint8Array> {
     Secp256r1.validateKey(privateJwk);
 
@@ -99,7 +100,7 @@ export class Secp256r1 {
   public static async verify(
     content: Uint8Array,
     signature: Uint8Array,
-    publicJwk: PublicJwk
+    publicJwk: PublicKeyJwk
   ): Promise<boolean> {
     Secp256r1.validateKey(publicJwk);
 
@@ -111,9 +112,10 @@ export class Secp256r1 {
       sig = p256.Signature.fromDER(signature);
     }
     const hashedContent = await sha256.encode(content);
+    const ecJwk = publicJwk as JwkParamsEcPublic;
     const keyBytes = p256.ProjectivePoint.fromAffine({
-      x : Secp256r1.bytesToBigInt(Encoder.base64UrlToBytes(publicJwk.x)),
-      y : Secp256r1.bytesToBigInt(Encoder.base64UrlToBytes(publicJwk.y!)),
+      x : Secp256r1.bytesToBigInt(Encoder.base64UrlToBytes(ecJwk.x)),
+      y : Secp256r1.bytesToBigInt(Encoder.base64UrlToBytes(ecJwk.y!)),
     }).toRawBytes(false);
 
     return p256.verify(sig, hashedContent, keyBytes);
@@ -123,15 +125,15 @@ export class Secp256r1 {
    * Generates a random key pair in JWK format.
    */
   public static async generateKeyPair(): Promise<{
-    publicJwk: PublicJwk;
-    privateJwk: PrivateJwk;
+    publicJwk: PublicKeyJwk;
+    privateJwk: PrivateKeyJwk;
   }> {
     const privateKeyBytes = p256.utils.randomPrivateKey();
     const publicKeyBytes = secp256r1.getPublicKey(privateKeyBytes, false); // `false` = uncompressed
 
     const d = Encoder.bytesToBase64Url(privateKeyBytes);
-    const publicJwk: PublicJwk = await Secp256r1.publicKeyToJwk(publicKeyBytes);
-    const privateJwk: PrivateJwk = { ...publicJwk, d };
+    const publicJwk: PublicKeyJwk = await Secp256r1.publicKeyToJwk(publicKeyBytes);
+    const privateJwk: PrivateKeyJwk = { ...publicJwk, d };
 
     return { publicJwk, privateJwk };
   }

package/src/utils/time.ts

@@ -16,7 +16,7 @@ export class Time {
 
   /**
    * We must sleep for at least 2ms to avoid timestamp collisions during testing.
-   * https://github.com/TBD54566975/dwn-sdk-js/issues/481
+   * https://github.com/enboxorg/enbox/issues/481
    */
   public static async minimalSleep(): Promise<void> {
     await Time.sleep(2);

package/src/utils/url.ts

@@ -51,7 +51,7 @@ function normalizeUrl(url: string): string {
     result.search = '';
     result.hash = '';
     return removeTrailingSlash(result.href);
-  } catch (e) {
+  } catch {
     throw new DwnError(DwnErrorCode.UrlProtocolNotNormalizable, 'Could not normalize protocol URI');
   }
 }