@enbox/dwn-sdk-js 0.0.1

package/src/utils/secp256k1.ts

@@ -0,0 +1,157 @@
+import type { PrivateJwk, PublicJwk } from '../types/jose-types.js';
+
+import * as secp256k1 from '@noble/secp256k1';
+
+import { Encoder } from '../utils/encoder.js';
+import { sha256 } from 'multiformats/hashes/sha2';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+
+/**
+ * Class containing SECP256K1 related utility methods.
+ */
+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') {
+      throw new DwnError(DwnErrorCode.Secp256k1KeyNotValid, 'Invalid SECP256K1 JWK: `kty` MUST be `EC`. `crv` MUST be `secp256k1`');
+    }
+  }
+
+  /**
+   * Converts a public key in bytes into a JWK.
+   */
+  public static async publicKeyToJwk(publicKeyBytes: Uint8Array): Promise<PublicJwk> {
+  // ensure public key is in uncompressed format so we can convert it into both x and y value
+    let uncompressedPublicKeyBytes;
+    if (publicKeyBytes.byteLength === 33) {
+      // this means given key is compressed
+      const curvePoints = secp256k1.ProjectivePoint.fromHex(publicKeyBytes);
+      uncompressedPublicKeyBytes = curvePoints.toRawBytes(false); // isCompressed = false
+    } else {
+      uncompressedPublicKeyBytes = publicKeyBytes;
+    }
+
+    // the first byte is a header that indicates whether the key is uncompressed (0x04 if uncompressed), we can safely ignore
+    // bytes 1 - 32 represent X
+    // bytes 33 - 64 represent Y
+
+    // skip the first byte because it's used as a header to indicate whether the key is uncompressed
+    const x = Encoder.bytesToBase64Url(uncompressedPublicKeyBytes.subarray(1, 33));
+    const y = Encoder.bytesToBase64Url(uncompressedPublicKeyBytes.subarray(33, 65));
+
+    const publicJwk: PublicJwk = {
+      alg : 'ES256K',
+      kty : 'EC',
+      crv : 'secp256k1',
+      x,
+      y
+    };
+
+    return publicJwk;
+  }
+
+  /**
+   * Converts a private key in bytes into a JWK.
+   */
+  public static async privateKeyToJwk(privateKeyBytes: Uint8Array): Promise<PrivateJwk> {
+    const publicKeyBytes = await Secp256k1.getPublicKey(privateKeyBytes);
+
+    const jwk = await Secp256k1.publicKeyToJwk(publicKeyBytes);
+    (jwk as PrivateJwk).d = Encoder.bytesToBase64Url(privateKeyBytes);
+
+    return jwk as PrivateJwk;
+  }
+
+  /**
+   * 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!);
+
+    return secp256k1.ProjectivePoint.fromAffine({
+      x : secp256k1.etc.bytesToNumberBE(x),
+      y : secp256k1.etc.bytesToNumberBE(y)
+    }).toRawBytes(true);
+  }
+
+  /**
+   * Creates a private key in raw bytes from the given SECP256K1 JWK.
+   */
+  public static privateJwkToBytes(privateJwk: PrivateJwk): Uint8Array {
+    const privateKey = Encoder.base64UrlToBytes(privateJwk.d);
+    return privateKey;
+  }
+
+  /**
+   * Signs the provided content using the provided JWK.
+   */
+  public static async sign(content: Uint8Array, privateJwk: PrivateJwk): Promise<Uint8Array> {
+    Secp256k1.validateKey(privateJwk);
+
+    // the underlying lib expects us to hash the content ourselves:
+    // https://github.com/paulmillr/noble-secp256k1/blob/97aa518b9c12563544ea87eba471b32ecf179916/index.ts#L1160
+    const hashedContent = await sha256.encode(content);
+    const privateKeyBytes = Secp256k1.privateJwkToBytes(privateJwk);
+
+    return (await secp256k1.signAsync(hashedContent, privateKeyBytes)).toCompactRawBytes();
+  }
+
+  /**
+   * 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> {
+    Secp256k1.validateKey(publicJwk);
+
+    const publicKeyBytes = Secp256k1.publicJwkToBytes(publicJwk);
+    const hashedContent = await sha256.encode(content);
+    return secp256k1.verify(signature, hashedContent, publicKeyBytes, { lowS: false });
+  }
+
+  /**
+   * Generates a random key pair in JWK format.
+   */
+  public static async generateKeyPair(): Promise<{publicJwk: PublicJwk, privateJwk: PrivateJwk}> {
+    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 };
+
+    return { publicJwk, privateJwk };
+  }
+
+  /**
+   * Generates key pair in raw bytes, where the `publicKey` is compressed.
+   */
+  public static async generateKeyPairRaw(): Promise<{publicKey: Uint8Array, privateKey: Uint8Array}> {
+    const privateKey = secp256k1.utils.randomPrivateKey();
+    const publicKey = secp256k1.getPublicKey(privateKey, true); // `true` = compressed
+
+    return { publicKey, privateKey };
+  }
+
+  /**
+   * Gets the compressed public key of the given private key.
+   */
+  public static async getPublicKey(privateKey: Uint8Array): Promise<Uint8Array> {
+    const publicKey = secp256k1.getPublicKey(privateKey, true); // `true` = compressed
+    return publicKey;
+  }
+
+  /**
+   * Gets the public JWK of the given private JWK.
+   */
+  public static async getPublicJwk(privateKeyJwk: PrivateJwk): Promise<PublicJwk> {
+    // strip away `d`
+    const { d: _d, ...publicKey } = privateKeyJwk;
+    return publicKey;
+  }
+}
+

package/src/utils/secp256r1.ts

@@ -0,0 +1,142 @@
+import type { PrivateJwk, PublicJwk } from '../types/jose-types.js';
+
+import { p256, secp256r1 } from '@noble/curves/p256';
+
+import { Encoder } from './encoder.js';
+import { sha256 } from 'multiformats/hashes/sha2';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { fromString, toString } from 'uint8arrays';
+
+const u8a = { toString, fromString };
+
+/**
+ * Class containing SECP256R1 related utility methods.
+ */
+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') {
+      throw new DwnError(
+        DwnErrorCode.Secp256r1KeyNotValid,
+        'Invalid SECP256R1 JWK: `kty` MUST be `EC`. `crv` MUST be `P-256`'
+      );
+    }
+  }
+
+  /**
+   * Converts a public key in bytes into a JWK.
+   */
+  public static async publicKeyToJwk(
+    publicKeyBytes: Uint8Array
+  ): Promise<PublicJwk> {
+    // ensure public key is in uncompressed format so we can convert it into both x and y value
+    let uncompressedPublicKeyBytes;
+    if (publicKeyBytes.byteLength === 33) {
+      // this means given key is compressed
+      const curvePoints = p256.ProjectivePoint.fromHex(publicKeyBytes);
+      uncompressedPublicKeyBytes = curvePoints.toRawBytes(false); // isCompressed = false
+    } else {
+      uncompressedPublicKeyBytes = publicKeyBytes;
+    }
+
+    // the first byte is a header that indicates whether the key is uncompressed (0x04 if uncompressed), we can safely ignore
+    // bytes 1 - 32 represent X
+    // bytes 33 - 64 represent Y
+
+    // skip the first byte because it's used as a header to indicate whether the key is uncompressed
+    const x = Encoder.bytesToBase64Url(
+      uncompressedPublicKeyBytes.subarray(1, 33)
+    );
+    const y = Encoder.bytesToBase64Url(
+      uncompressedPublicKeyBytes.subarray(33, 65)
+    );
+
+    const publicJwk: PublicJwk = {
+      alg : 'ES256',
+      kty : 'EC',
+      crv : 'P-256',
+      x,
+      y,
+    };
+
+    return publicJwk;
+  }
+
+  /**
+   * Creates a private key in raw bytes from the given SECP256R1 JWK.
+   */
+  public static privateJwkToBytes(privateJwk: PrivateJwk): Uint8Array {
+    const privateKey = Encoder.base64UrlToBytes(privateJwk.d);
+    return privateKey;
+  }
+
+  /**
+   * Signs the provided content using the provided JWK.
+   * Signature that is outputted is JWS format, not DER.
+   */
+  public static async sign(
+    content: Uint8Array,
+    privateJwk: PrivateJwk
+  ): Promise<Uint8Array> {
+    Secp256r1.validateKey(privateJwk);
+
+    const hashedContent = await sha256.encode(content);
+    const privateKeyBytes = Secp256r1.privateJwkToBytes(privateJwk);
+
+    return Promise.resolve(
+      p256.sign(hashedContent, privateKeyBytes).toCompactRawBytes()
+    );
+  }
+
+  /**
+   * Verifies a signature against the provided payload hash and public key.
+   * @param signature - the signature to verify. Can be in either DER or compact format. If using Oracle Cloud KMS, keys will be DER formatted.
+   * @returns a boolean indicating whether the signature is valid.
+   */
+  public static async verify(
+    content: Uint8Array,
+    signature: Uint8Array,
+    publicJwk: PublicJwk
+  ): Promise<boolean> {
+    Secp256r1.validateKey(publicJwk);
+
+    // handle DER vs compact signature formats
+    let sig;
+    if (signature.length === 64) {
+      sig = p256.Signature.fromCompact(signature);
+    } else {
+      sig = p256.Signature.fromDER(signature);
+    }
+    const hashedContent = await sha256.encode(content);
+    const keyBytes = p256.ProjectivePoint.fromAffine({
+      x : Secp256r1.bytesToBigInt(Encoder.base64UrlToBytes(publicJwk.x)),
+      y : Secp256r1.bytesToBigInt(Encoder.base64UrlToBytes(publicJwk.y!)),
+    }).toRawBytes(false);
+
+    return p256.verify(sig, hashedContent, keyBytes);
+  }
+
+  /**
+   * Generates a random key pair in JWK format.
+   */
+  public static async generateKeyPair(): Promise<{
+    publicJwk: PublicJwk;
+    privateJwk: PrivateJwk;
+  }> {
+    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 };
+
+    return { publicJwk, privateJwk };
+  }
+
+  public static bytesToBigInt(b: Uint8Array): bigint {
+    return BigInt(`0x` + u8a.toString(b, 'base16'));
+  }
+}

package/src/utils/string.ts

@@ -0,0 +1,13 @@
+/**
+ * Compares two string given in lexicographical order.
+ * @returns 1 if `a` is larger than `b`; -1 if `a` is smaller/older than `b`; 0 otherwise (same message)
+ */
+export function lexicographicalCompare(a: string, b: string): number {
+  if (a > b) {
+    return 1;
+  } else if (a < b) {
+    return -1;
+  } else {
+    return 0;
+  }
+}

package/src/utils/time.ts

@@ -0,0 +1,78 @@
+import { Temporal } from '@js-temporal/polyfill';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+/**
+ * Time related utilities.
+ */
+export class Time {
+  /**
+   * sleeps for the desired duration
+   * @param durationInMillisecond the desired amount of sleep time
+   * @returns when the provided duration has passed
+   */
+  public static async sleep(durationInMillisecond: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, durationInMillisecond));
+  }
+
+  /**
+   * We must sleep for at least 2ms to avoid timestamp collisions during testing.
+   * https://github.com/TBD54566975/dwn-sdk-js/issues/481
+   */
+  public static async minimalSleep(): Promise<void> {
+    await Time.sleep(2);
+  }
+
+  /**
+   * Returns an UTC ISO-8601 timestamp with microsecond precision accepted by DWN.
+   * using @js-temporal/polyfill
+   */
+  public static getCurrentTimestamp(): string {
+    return Temporal.Now.instant().toString({ smallestUnit: 'microseconds' });
+  }
+
+  /**
+   * Creates a UTC ISO-8601 timestamp in microsecond precision accepted by DWN.
+   * @param options - Options for creating the timestamp.
+   * @returns string
+   */
+  public static createTimestamp(options: {
+    year?: number, month?: number, day?: number, hour?: number, minute?: number, second?: number, millisecond?: number, microsecond?: number
+  }): string {
+    const { year, month, day, hour, minute, second, millisecond, microsecond } = options;
+    return Temporal.ZonedDateTime.from({
+      timeZone: 'UTC',
+      year,
+      month,
+      day,
+      hour,
+      minute,
+      second,
+      millisecond,
+      microsecond
+    }).toInstant().toString({ smallestUnit: 'microseconds' });
+  }
+
+  /**
+   * Creates a UTC ISO-8601 timestamp offset from now or given timestamp accepted by DWN.
+   * @param offset Negative number means offset into the past.
+   */
+  public static createOffsetTimestamp(offset: { seconds: number }, timestamp?: string): string {
+    const timestampInstant = timestamp ? Temporal.Instant.from(timestamp) : Temporal.Now.instant();
+    const offsetDuration = Temporal.Duration.from(offset);
+    const offsetInstant = timestampInstant.add(offsetDuration);
+    return offsetInstant.toString({ smallestUnit: 'microseconds' });
+  }
+
+  /**
+   * Validates that the provided timestamp is a valid number
+   * @param timestamp the timestamp to validate
+   * @throws DwnError if timestamp is not a valid number
+   */
+  public static validateTimestamp(timestamp: string): void {
+    try {
+      Temporal.Instant.from(timestamp);
+    } catch {
+      throw new DwnError(DwnErrorCode.TimestampInvalid, `Invalid timestamp: ${timestamp}`);
+    }
+  }
+}

package/src/utils/url.ts

@@ -0,0 +1,65 @@
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+export function validateProtocolUrlNormalized(url: string): void {
+  let normalized: string | undefined;
+  try {
+    normalized = normalizeProtocolUrl(url);
+  } catch {
+    normalized = undefined;
+  }
+
+  if (url !== normalized) {
+    throw new DwnError(DwnErrorCode.UrlProtocolNotNormalized, `Protocol URI ${url} must be normalized.`);
+  }
+}
+
+export function normalizeProtocolUrl(url: string): string {
+  // Keeping protocol normalization as a separate function in case
+  // protocol and schema normalization diverge in the future
+  return normalizeUrl(url);
+}
+
+export function validateSchemaUrlNormalized(url: string): void {
+  let normalized: string | undefined;
+  try {
+    normalized = normalizeSchemaUrl(url);
+  } catch {
+    normalized = undefined;
+  }
+
+  if (url !== normalized) {
+    throw new DwnError(DwnErrorCode.UrlSchemaNotNormalized, `Schema URI ${url} must be normalized.`);
+  }
+}
+
+export function normalizeSchemaUrl(url: string): string {
+  // Keeping schema normalization as a separate function in case
+  // protocol and schema normalization diverge in the future
+  return normalizeUrl(url);
+}
+
+function normalizeUrl(url: string): string {
+  let fullUrl: string;
+  if (/^[^:]+:(\/{2})?[^\/].*/.test(url)) {
+    fullUrl = url;
+  } else {
+    fullUrl = `http://${url}`;
+  }
+
+  try {
+    const result = new URL(fullUrl);
+    result.search = '';
+    result.hash = '';
+    return removeTrailingSlash(result.href);
+  } catch (e) {
+    throw new DwnError(DwnErrorCode.UrlProtocolNotNormalizable, 'Could not normalize protocol URI');
+  }
+}
+
+function removeTrailingSlash(str: string): string {
+  if (str.endsWith('/')) {
+    return str.slice(0, -1);
+  } else {
+    return str;
+  }
+}