@enbox/dwn-sdk-js 0.4.6 → 0.4.8

package/src/utils/hd-key.ts

@@ -1,7 +1,6 @@
 import type { PrivateKeyJwk, PublicKeyJwk } from '../types/jose-types.js';
 
 import { Encoder } from './encoder.js';
-import { getWebcryptoSubtle } from '@noble/ciphers/webcrypto';
 import { X25519 } from '@enbox/crypto';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
@@ -82,7 +81,7 @@ export class HdKey {
   }): Promise<Uint8Array> {
     const { hashAlgorithm, initialKeyMaterial, info, keyLengthInBytes } = params;
 
-    const webCrypto = getWebcryptoSubtle() as SubtleCrypto;
+    const webCrypto = globalThis.crypto.subtle;
 
     // Import the `initialKeyMaterial` into the Web Crypto API to use for the key derivation operation.
     const webCryptoKey = await webCrypto.importKey('raw', initialKeyMaterial as BufferSource, { name: 'HKDF' }, false, ['deriveBits']);

package/src/utils/jws.ts

@@ -3,13 +3,19 @@ import type { MessageSigner } from '../types/signer.js';
 import type { SignatureEntry } from '../types/jws-types.js';
 import type { KeyMaterial, PublicKeyJwk } from '../types/jose-types.js';
 
-import isPlainObject from 'lodash/isPlainObject.js';
-
 import { Encoder } from './encoder.js';
 import { PrivateKeySigner } from './private-key-signer.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { signatureAlgorithms, type SupportedCurve } from '../jose/algorithms/signing/signature-algorithms.js';
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
 
 /**
  * Utility class for JWS related operations.

package/src/utils/memory-cache.ts

@@ -1,31 +1,62 @@
 import type { Cache } from '../types/cache.js';
-import { LRUCache } from 'lru-cache';
+
+type CacheEntry = {
+  expiresAt: number;
+  value: unknown;
+};
 
 /**
  * A cache using local memory.
  */
 export class MemoryCache implements Cache {
-  private readonly cache: LRUCache<string, any>;
+  private static readonly maxEntries = 100_000;
+
+  private readonly cache = new Map<string, CacheEntry>();
 
   /**
    * @param timeToLiveInSeconds time-to-live for every key-value pair set in the cache
    */
-  public constructor (private readonly timeToLiveInSeconds: number) {
-    this.cache = new LRUCache({
-      max : 100_000,
-      ttl : timeToLiveInSeconds * 1000
-    });
+  public constructor(private readonly timeToLiveInSeconds: number) {
   }
 
-  async set(key: string, value: any): Promise<void> {
+  public async set<T = unknown>(key: string, value: T): Promise<void> {
     try {
-      this.cache.set(key, value);
+      const entry = {
+        expiresAt : Date.now() + this.timeToLiveInSeconds * 1000,
+        value     : value,
+      };
+
+      this.cache.delete(key);
+      this.cache.set(key, entry);
+      this.evictOldestEntries();
     } catch {
       // let the code continue as this is a non-fatal error
     }
   }
 
-  async get(key: string): Promise<any | undefined> {
-    return this.cache.get(key);
+  public async get<T = unknown>(key: string): Promise<T | undefined> {
+    const entry = this.cache.get(key);
+    if (entry === undefined) {
+      return undefined;
+    }
+
+    if (Date.now() >= entry.expiresAt) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry.value as T;
+  }
+
+  private evictOldestEntries(): void {
+    while (this.cache.size > MemoryCache.maxEntries) {
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey === undefined) {
+        return;
+      }
+      this.cache.delete(oldestKey);
+    }
   }
 }

package/src/utils/protocols.ts

@@ -52,6 +52,38 @@ export function getTypeName(protocolPath: string): string {
   return protocolPath.split('/').slice(-1)[0];
 }
 
+/**
+ * Computes the role-audience context id for a role path relative to a source record context id.
+ * Root-level role audiences use the empty string; nested role audiences use the ancestor
+ * context prefix at the same depth as the role parent.
+ */
+export function getRoleAudienceContextId(rolePath: string, contextId?: string): string | undefined {
+  const roleParentDepth = rolePath.split('/').length - 1;
+  if (roleParentDepth === 0) {
+    return '';
+  }
+
+  if (contextId === undefined) {
+    return undefined;
+  }
+
+  const contextSegments = contextId.split('/');
+  if (contextSegments.length < roleParentDepth) {
+    return undefined;
+  }
+
+  return contextSegments.slice(0, roleParentDepth).join('/');
+}
+
+/**
+ * Computes the context prefix used when querying for role records. Root-level
+ * role records are queried without a context prefix.
+ */
+export function getRoleContextPrefix(rolePath: string, contextId?: string): string | undefined {
+  const roleAudienceContextId = getRoleAudienceContextId(rolePath, contextId);
+  return roleAudienceContextId === '' ? undefined : roleAudienceContextId;
+}
+
 /**
  * Gets the rule set at a given protocol path within a protocol definition's structure tree.
  * Returns `undefined` if the path does not exist.

package/src/utils/record-limit-occupancy.ts

@@ -37,6 +37,13 @@ type RecordLimitFilterResolution = {
   projectedFilters: Filter[];
 };
 
+type OccupancyProjectionInput<T extends RecordsWriteMessage> = {
+  records: T[];
+  max: number;
+  getScopeKey(record: T): string;
+  compareRecords(left: T, right: T): number;
+};
+
 /**
  * Queries records with bounded `$recordLimit` occupancy projection when every limited filter targets one concrete scope.
  *
@@ -285,11 +292,12 @@ async function findOccupantRecordIds(input: {
     ...boundaryCandidates,
   ];
 
-  return new Set(
-    rankedCandidates
-      .slice(0, input.recordLimit.max)
-      .map((message): string => message.recordId)
-  );
+  return selectOccupantRecordIds({
+    records        : rankedCandidates,
+    max            : input.recordLimit.max,
+    getScopeKey    : (): string => '',
+    compareRecords : compareRecordLimitCandidates,
+  });
 }
 
 function buildRecordLimitScopeFilter(scope: RecordLimitScope): Filter {
@@ -375,3 +383,24 @@ function compareRecordLimitCandidates(left: RecordsWriteMessage, right: RecordsW
 
   return lexicographicalCompare(left.recordId, right.recordId);
 }
+
+export function selectOccupantRecordIds<T extends RecordsWriteMessage>(input: OccupancyProjectionInput<T>): Set<string> {
+  const occupants = new Set<string>();
+  const groups = new Map<string, T[]>();
+
+  for (const record of input.records) {
+    const scopeKey = input.getScopeKey(record);
+    const group = groups.get(scopeKey) ?? [];
+    group.push(record);
+    groups.set(scopeKey, group);
+  }
+
+  for (const group of groups.values()) {
+    group.sort(input.compareRecords);
+    for (const record of group.slice(0, input.max)) {
+      occupants.add(record.recordId);
+    }
+  }
+
+  return occupants;
+}

package/src/utils/records.ts

@@ -1,8 +1,8 @@
 import type { DerivedPrivateJwk } from './hd-key.js';
 import type { Jwk } from '@enbox/crypto';
 import type { KeyDecrypter } from '../types/encryption-types.js';
-import type { KeyEncryption } from './encryption.js';
 import type { PublicKeyJwk } from '../types/jose-types.js';
+import type { X25519KeyEncryption } from './encryption.js';
 import type { Filter, KeyValues, StartsWithFilter } from '../types/query-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';
@@ -21,6 +21,7 @@ import { X25519 } from '@enbox/crypto';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 import { Encryption, ROLE_AUDIENCE_DERIVATION_SCHEME } from './encryption.js';
+import { ENCRYPTION_CONTROL_PATHS, isEncryptionControlPath } from '../core/constants.js';
 import { HdKey, KeyDerivationScheme } from './hd-key.js';
 import { normalizeProtocolUrl, normalizeSchemaUrl } from './url.js';
 
@@ -132,7 +133,7 @@ export class Records {
   private static async findMatchingKeyEncryption(
     recordsWrite: RecordsWriteMessage,
     keyOrDecrypter: DerivedPrivateJwk | KeyDecrypter,
-  ): Promise<{ fullDerivationPath: string[]; leafPrivateKey?: Jwk; matchingKeyEncryption?: KeyEncryption }> {
+  ): Promise<{ fullDerivationPath: string[]; leafPrivateKey?: Jwk; matchingKeyEncryption?: X25519KeyEncryption }> {
     const { encryption } = recordsWrite;
     const fullDerivationPath = Records.constructKeyDerivationPath(keyOrDecrypter.derivationScheme, recordsWrite);
 
@@ -334,6 +335,10 @@ export class Records {
       return;
     }
 
+    if (isEncryptionControlPath(protocolPath)) {
+      return;
+    }
+
     const expectedParentDepth = protocolPath.split('/').length - 1;
     const contextIdSegments = contextId?.split('/');
     if (
@@ -442,6 +447,35 @@ export class Records {
     return filterCopy;
   }
 
+  public static buildUnpublishedControlRecordsFilter(filter: RecordsFilter, dateSort?: DateSort): Filter {
+    return {
+      ...Records.convertFilter(filter, dateSort),
+      interface         : DwnInterfaceName.Records,
+      method            : DwnMethodName.Write,
+      isLatestBaseState : true,
+      published         : false,
+    };
+  }
+
+  public static buildControlRecordsFilters(filters: Filter[]): Filter[] {
+    const controlFilters: Filter[] = [];
+    for (const filter of filters) {
+      const protocolPath = filter.protocolPath;
+      if (typeof protocolPath === 'string') {
+        if (isEncryptionControlPath(protocolPath)) {
+          controlFilters.push(filter);
+        }
+        continue;
+      }
+
+      for (const controlPath of ENCRYPTION_CONTROL_PATHS) {
+        controlFilters.push({ ...filter, protocolPath: controlPath });
+      }
+    }
+
+    return controlFilters;
+  }
+
   /**
    * Validates the referential integrity of both author-delegated grant and owner-delegated grant.
    * @param authorSignaturePayload Decoded payload of the author signature of the message. Pass `undefined` if message is not signed.

package/src/utils/secp256k1.ts

@@ -1,7 +1,8 @@
 import type { JwkParamsEcPrivate, JwkParamsEcPublic } from '@enbox/crypto';
 import type { PrivateKeyJwk, PublicKeyJwk } from '../types/jose-types.js';
 
-import * as secp256k1 from '@noble/secp256k1';
+import { bytesToNumberBE } from '@noble/curves/utils.js';
+import { secp256k1 } from '@noble/curves/secp256k1.js';
 
 import { Encoder } from '../utils/encoder.js';
 import { sha256 } from 'multiformats/hashes/sha2';
@@ -30,8 +31,8 @@ export class Secp256k1 {
     let uncompressedPublicKeyBytes;
     if (publicKeyBytes.byteLength === 33) {
       // this means given key is compressed
-      const curvePoints = secp256k1.ProjectivePoint.fromHex(publicKeyBytes);
-      uncompressedPublicKeyBytes = curvePoints.toRawBytes(false); // isCompressed = false
+      const curvePoints = secp256k1.Point.fromBytes(publicKeyBytes);
+      uncompressedPublicKeyBytes = curvePoints.toBytes(false); // isCompressed = false
     } else {
       uncompressedPublicKeyBytes = publicKeyBytes;
     }
@@ -75,10 +76,10 @@ export class Secp256k1 {
     const x = Encoder.base64UrlToBytes(ecJwk.x);
     const y = Encoder.base64UrlToBytes(ecJwk.y!);
 
-    return secp256k1.ProjectivePoint.fromAffine({
-      x : secp256k1.etc.bytesToNumberBE(x),
-      y : secp256k1.etc.bytesToNumberBE(y)
-    }).toRawBytes(true);
+    return secp256k1.Point.fromAffine({
+      x : bytesToNumberBE(x),
+      y : bytesToNumberBE(y)
+    }).toBytes(true);
   }
 
   /**
@@ -100,7 +101,7 @@ export class Secp256k1 {
     const hashedContent = await sha256.encode(content);
     const privateKeyBytes = Secp256k1.privateJwkToBytes(privateJwk);
 
-    return (await secp256k1.signAsync(hashedContent, privateKeyBytes)).toCompactRawBytes();
+    return secp256k1.sign(hashedContent, privateKeyBytes, { prehash: false });
   }
 
   /**
@@ -112,14 +113,14 @@ export class Secp256k1 {
 
     const publicKeyBytes = Secp256k1.publicJwkToBytes(publicJwk);
     const hashedContent = await sha256.encode(content);
-    return secp256k1.verify(signature, hashedContent, publicKeyBytes, { lowS: false });
+    return secp256k1.verify(signature, hashedContent, publicKeyBytes, { lowS: false, prehash: false });
   }
 
   /**
    * Generates a random key pair in JWK format.
    */
   public static async generateKeyPair(): Promise<{publicJwk: PublicKeyJwk, privateJwk: PrivateKeyJwk}> {
-    const privateKeyBytes = secp256k1.utils.randomPrivateKey();
+    const privateKeyBytes = secp256k1.utils.randomSecretKey();
     const publicKeyBytes = secp256k1.getPublicKey(privateKeyBytes, false); // `false` = uncompressed
 
     const d = Encoder.bytesToBase64Url(privateKeyBytes);
@@ -133,7 +134,7 @@ export class Secp256k1 {
    * 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 privateKey = secp256k1.utils.randomSecretKey();
     const publicKey = secp256k1.getPublicKey(privateKey, true); // `true` = compressed
 
     return { publicKey, privateKey };
@@ -156,4 +157,3 @@ export class Secp256k1 {
     return publicKey as PublicKeyJwk;
   }
 }
-

package/src/utils/secp256r1.ts

@@ -1,14 +1,12 @@
 import type { JwkParamsEcPrivate, JwkParamsEcPublic } from '@enbox/crypto';
 import type { PrivateKeyJwk, PublicKeyJwk } from '../types/jose-types.js';
 
-import { p256, secp256r1 } from '@noble/curves/p256';
+import { bytesToNumberBE } from '@noble/curves/utils.js';
+import { p256 } from '@noble/curves/nist.js';
 
 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.
@@ -37,8 +35,8 @@ export class Secp256r1 {
     let uncompressedPublicKeyBytes;
     if (publicKeyBytes.byteLength === 33) {
       // this means given key is compressed
-      const curvePoints = p256.ProjectivePoint.fromHex(publicKeyBytes);
-      uncompressedPublicKeyBytes = curvePoints.toRawBytes(false); // isCompressed = false
+      const curvePoints = p256.Point.fromBytes(publicKeyBytes);
+      uncompressedPublicKeyBytes = curvePoints.toBytes(false); // isCompressed = false
     } else {
       uncompressedPublicKeyBytes = publicKeyBytes;
     }
@@ -87,9 +85,7 @@ export class Secp256r1 {
     const hashedContent = await sha256.encode(content);
     const privateKeyBytes = Secp256r1.privateJwkToBytes(privateJwk);
 
-    return Promise.resolve(
-      p256.sign(hashedContent, privateKeyBytes).toCompactRawBytes()
-    );
+    return Promise.resolve(p256.sign(hashedContent, privateKeyBytes, { prehash: false }));
   }
 
   /**
@@ -104,21 +100,15 @@ export class Secp256r1 {
   ): 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 signatureFormat = signature.length === 64 ? 'compact' : 'der';
     const hashedContent = await sha256.encode(content);
     const ecJwk = publicJwk as JwkParamsEcPublic;
-    const keyBytes = p256.ProjectivePoint.fromAffine({
+    const keyBytes = p256.Point.fromAffine({
       x : Secp256r1.bytesToBigInt(Encoder.base64UrlToBytes(ecJwk.x)),
       y : Secp256r1.bytesToBigInt(Encoder.base64UrlToBytes(ecJwk.y!)),
-    }).toRawBytes(false);
+    }).toBytes(false);
 
-    return p256.verify(sig, hashedContent, keyBytes);
+    return p256.verify(signature, hashedContent, keyBytes, { format: signatureFormat, lowS: false, prehash: false });
   }
 
   /**
@@ -128,8 +118,8 @@ export class Secp256r1 {
     publicJwk: PublicKeyJwk;
     privateJwk: PrivateKeyJwk;
   }> {
-    const privateKeyBytes = p256.utils.randomPrivateKey();
-    const publicKeyBytes = secp256r1.getPublicKey(privateKeyBytes, false); // `false` = uncompressed
+    const privateKeyBytes = p256.utils.randomSecretKey();
+    const publicKeyBytes = p256.getPublicKey(privateKeyBytes, false); // `false` = uncompressed
 
     const d = Encoder.bytesToBase64Url(privateKeyBytes);
     const publicJwk: PublicKeyJwk = await Secp256r1.publicKeyToJwk(publicKeyBytes);
@@ -139,6 +129,6 @@ export class Secp256r1 {
   }
 
   public static bytesToBigInt(b: Uint8Array): bigint {
-    return BigInt(`0x` + u8a.toString(b, 'base16'));
+    return bytesToNumberBE(b);
   }
 }

package/src/utils/time.ts

@@ -1,7 +1,24 @@
 import { sleep } from '@enbox/common';
-import { Temporal } from '@js-temporal/polyfill';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
+type ParsedTimestamp = {
+  epochMilliseconds: number;
+  microsecond: number;
+};
+
+type TimestampOptions = {
+  year?: number;
+  month?: number;
+  day?: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+  millisecond?: number;
+  microsecond?: number;
+};
+
+const timestampRegex = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})\.(\d{6})Z$/;
+
 /**
  * Time related utilities.
  */
@@ -19,10 +36,9 @@ export class Time {
 
   /**
    * 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' });
+    return Time.formatUtcTimestamp(Date.now(), 0);
   }
 
   /**
@@ -30,21 +46,21 @@ export class Time {
    * @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' });
+  public static createTimestamp(options: TimestampOptions): string {
+    const year = Time.constrainInteger(Time.requireTimestampField(options.year, 'year'), 0, 9999);
+    const month = Time.constrainInteger(Time.requireTimestampField(options.month, 'month'), 1, 12);
+    const day = Time.constrainInteger(Time.requireTimestampField(options.day, 'day'), 1, Time.daysInUtcMonth(year, month));
+    const hour = Time.constrainInteger(options.hour ?? 0, 0, 23);
+    const minute = Time.constrainInteger(options.minute ?? 0, 0, 59);
+    const second = Time.constrainInteger(options.second ?? 0, 0, 59);
+    const millisecond = Time.constrainInteger(options.millisecond ?? 0, 0, 999);
+    const microsecond = Time.constrainInteger(options.microsecond ?? 0, 0, 999);
+    const date = new Date(0);
+    date.setUTCHours(0, 0, 0, 0);
+    date.setUTCFullYear(year, month - 1, day);
+    date.setUTCHours(hour, minute, second, millisecond);
+
+    return Time.formatUtcTimestamp(date.getTime(), microsecond);
   }
 
   /**
@@ -52,22 +68,124 @@ export class Time {
    * @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' });
+    const parsedTimestamp = timestamp === undefined ? { epochMilliseconds: Date.now(), microsecond: 0 } : Time.parseTimestamp(timestamp);
+    if (parsedTimestamp === undefined) {
+      throw new DwnError(DwnErrorCode.TimestampInvalid, `Invalid timestamp: ${timestamp}`);
+    }
+
+    const offsetSeconds = Time.requireWholeNumber(offset.seconds, 'seconds');
+    return Time.formatUtcTimestamp(parsedTimestamp.epochMilliseconds + (offsetSeconds * 1000), parsedTimestamp.microsecond);
   }
 
   /**
-   * Validates that the provided timestamp is a valid number
+   * Validates that the provided timestamp is a DWN-compatible UTC timestamp.
    * @param timestamp the timestamp to validate
-   * @throws DwnError if timestamp is not a valid number
+   * @throws DwnError if timestamp is invalid
    */
   public static validateTimestamp(timestamp: string): void {
-    try {
-      Temporal.Instant.from(timestamp);
-    } catch {
+    if (Time.parseTimestamp(timestamp) === undefined) {
       throw new DwnError(DwnErrorCode.TimestampInvalid, `Invalid timestamp: ${timestamp}`);
     }
   }
+
+  private static constrainInteger(value: number, min: number, max: number): number {
+    if (!Number.isFinite(value)) {
+      throw new RangeError('timestamp field must be finite');
+    }
+
+    const integer = Math.trunc(value);
+    return Math.min(Math.max(integer, min), max);
+  }
+
+  private static daysInUtcMonth(year: number, month: number): number {
+    const date = new Date(0);
+    date.setUTCHours(0, 0, 0, 0);
+    date.setUTCFullYear(year, month, 0);
+
+    return date.getUTCDate();
+  }
+
+  private static formatUtcTimestamp(epochMilliseconds: number, microsecond: number): string {
+    if (!Number.isFinite(epochMilliseconds)) {
+      throw new RangeError('timestamp is outside the supported Date range');
+    }
+
+    const date = new Date(epochMilliseconds);
+    const year = date.getUTCFullYear();
+    if (year < 0 || year > 9999) {
+      throw new RangeError('timestamp year must be between 0000 and 9999');
+    }
+
+    const fraction = String((date.getUTCMilliseconds() * 1000) + microsecond).padStart(6, '0');
+    return `${Time.pad(year, 4)}-${Time.pad(date.getUTCMonth() + 1, 2)}-${Time.pad(date.getUTCDate(), 2)}` +
+      `T${Time.pad(date.getUTCHours(), 2)}:${Time.pad(date.getUTCMinutes(), 2)}:${Time.pad(date.getUTCSeconds(), 2)}.${fraction}Z`;
+  }
+
+  private static pad(value: number, length: number): string {
+    return String(value).padStart(length, '0');
+  }
+
+  private static parseTimestamp(timestamp: string): ParsedTimestamp | undefined {
+    const match = timestampRegex.exec(timestamp);
+    if (match === null) {
+      return undefined;
+    }
+
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    const fraction = match[7];
+    const millisecond = Number(fraction.slice(0, 3));
+    const microsecond = Number(fraction.slice(3));
+    const isLeapSecond = hour === 23 && minute === 59 && second === 60;
+
+    if (
+      month < 1 ||
+      month > 12 ||
+      day < 1 ||
+      day > Time.daysInUtcMonth(year, month) ||
+      hour > 23 ||
+      minute > 59 ||
+      (second > 59 && !isLeapSecond)
+    ) {
+      return undefined;
+    }
+
+    const date = new Date(0);
+    date.setUTCHours(0, 0, 0, 0);
+    date.setUTCFullYear(year, month - 1, day);
+    date.setUTCHours(hour, minute, isLeapSecond ? 59 : second, millisecond);
+
+    if (
+      date.getUTCFullYear() !== year ||
+      date.getUTCMonth() !== month - 1 ||
+      date.getUTCDate() !== day ||
+      date.getUTCHours() !== hour ||
+      date.getUTCMinutes() !== minute ||
+      date.getUTCSeconds() !== (isLeapSecond ? 59 : second)
+    ) {
+      return undefined;
+    }
+
+    return { epochMilliseconds: date.getTime(), microsecond };
+  }
+
+  private static requireTimestampField(value: number | undefined, fieldName: string): number {
+    if (value === undefined) {
+      throw new TypeError(`required property '${fieldName}' missing or undefined`);
+    }
+
+    return value;
+  }
+
+  private static requireWholeNumber(value: number, fieldName: string): number {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+      throw new RangeError(`${fieldName} must be a finite integer`);
+    }
+
+    return value;
+  }
 }