@arkstack/encryption 0.18.0

package/dist/index.d.ts

@@ -0,0 +1,914 @@
+//#region src/EncryptionKey.d.ts
+/**
+ * A symmetric key, held as raw bytes and convertible to every representation
+ * the rest of the library (and the wire) needs.
+ *
+ * Keys are values: two keys with the same bytes are equal regardless of how
+ * they were produced, and comparison is constant time.
+ */
+declare class EncryptionKey {
+  readonly bytes: Uint8Array;
+  /**
+   * @param bytes Raw key material.
+   */
+  constructor(bytes: Uint8Array);
+  /**
+   * Generate a random key.
+   *
+   * @param length Key length in bytes, defaults to 32 (AES-256).
+   * @returns
+   */
+  static generate(length?: number): EncryptionKey;
+  /**
+   * Derive a key from an arbitrary secret by hashing it with SHA-256.
+   *
+   * This mirrors how Arkstack turns `APP_KEY` into a cipher key, so a value
+   * encrypted on the server with the app key can be decrypted in the browser
+   * from the same secret.
+   *
+   * @param secret
+   * @returns
+   */
+  static fromSecret(secret: string): Promise<EncryptionKey>;
+  /**
+   * Restore a key from its base64url representation.
+   *
+   * @param value
+   * @returns
+   */
+  static fromBase64Url(value: string): EncryptionKey;
+  /**
+   * Restore a key from its hex representation.
+   *
+   * @param value
+   * @returns
+   */
+  static fromHex(value: string): EncryptionKey;
+  /**
+   * Stretch a password into a key using PBKDF2-HMAC-SHA256.
+   *
+   * Prefer this over {@link fromSecret} for anything a human typed; the
+   * returned salt and iteration count must be stored alongside the
+   * ciphertext to reproduce the key later.
+   *
+   * @param password
+   * @param options
+   * @returns
+   */
+  static derive(password: string, options?: DeriveOptions): Promise<DerivedKey>;
+  /**
+   * Expand shared secret material into a key using HKDF-SHA256.
+   *
+   * Used internally by the ECDH channel and sealed box helpers, and exposed
+   * because deriving sub-keys from one root key is a common need.
+   *
+   * @param material
+   * @param salt
+   * @param info
+   * @param length
+   * @returns
+   */
+  static expand(material: Uint8Array, salt: Uint8Array, info: string, length?: number): Promise<EncryptionKey>;
+  /**
+   * Coerce any accepted key representation into an `EncryptionKey`.
+   *
+   * A string of exactly `length` bytes once base64url decoded is treated as
+   * raw key material; anything else is treated as a passphrase and hashed.
+   *
+   * @param input
+   * @param length Expected key length in bytes.
+   * @returns
+   */
+  static resolve(input: KeyInput, length?: number): Promise<EncryptionKey>;
+  /**
+   * Constant time comparison of two keys, in any representation that does not
+   * require asynchronous work.
+   *
+   * @param left
+   * @param right
+   * @returns
+   */
+  static compare(left: EncryptionKey | Uint8Array | string, right: EncryptionKey | Uint8Array | string): boolean;
+  /**
+   * Import this key into Web Crypto for the given algorithm.
+   *
+   * @param algorithm
+   * @param usages
+   * @returns
+   */
+  cryptoKey(algorithm?: AlgorithmIdentifier | AesKeyAlgorithm | HmacImportParams, usages?: KeyUsage[]): Promise<CryptoKey>;
+  /**
+   * A stable, shareable digest of this key. Safe to log or display; it does
+   * not reveal the key itself.
+   *
+   * @param options
+   * @returns
+   */
+  fingerprint(options?: FingerprintOptions): Promise<string>;
+  /**
+   * Constant time comparison against another key.
+   *
+   * @param other
+   * @returns
+   */
+  equals(other: EncryptionKey | Uint8Array | string): boolean;
+  /**
+   * Key length in bytes.
+   *
+   * @returns
+   */
+  get length(): number;
+  /**
+   * Base64url representation, the format used to persist and transport keys.
+   *
+   * @returns
+   */
+  toBase64Url(): string;
+  /**
+   * Hex representation.
+   *
+   * @returns
+   */
+  toHex(): string;
+  /**
+   * Base64url representation.
+   *
+   * @returns
+   */
+  toString(): string;
+  /**
+   * Keep keys out of accidental `JSON.stringify` output of surrounding
+   * objects by requiring an explicit `toBase64Url()` call.
+   *
+   * @returns
+   */
+  toJSON(): string;
+  /**
+   * Reduce a comparable key representation to bytes.
+   *
+   * @param value
+   * @returns
+   */
+  private static materialize;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Anything that can stand in for a symmetric key.
+ *
+ * - `EncryptionKey`: an already materialised key.
+ * - `Uint8Array`: raw key bytes (must match the cipher key length).
+ * - `CryptoKey`: a Web Crypto key, used as-is.
+ * - `string`: a base64url encoded key of the right length, otherwise treated as
+ *   a passphrase and hashed with SHA-256 (matching Arkstack's `APP_KEY` behaviour).
+ */
+type KeyInput = EncryptionKey | Uint8Array | CryptoKey | string;
+/**
+ * A serialised, transport safe key pair. Both halves are base64url strings:
+ * the public key is SPKI DER, the private key is PKCS#8 DER.
+ */
+interface SerializedKeyPair {
+  publicKey: string;
+  privateKey: string;
+}
+/**
+ * Optional per-operation cipher settings.
+ */
+interface CipherOptions {
+  /**
+   * Additional authenticated data. Not encrypted, but bound to the
+   * ciphertext: decryption fails unless the same value is supplied.
+   */
+  aad?: Uint8Array | string;
+}
+/**
+ * Options for password based key derivation (PBKDF2-HMAC-SHA256).
+ */
+interface DeriveOptions {
+  /**
+   * Salt bytes or a base64url encoded salt. Generated when omitted.
+   */
+  salt?: Uint8Array | string;
+  /**
+   * PBKDF2 iteration count. Defaults to 210,000 (OWASP 2023 guidance).
+   */
+  iterations?: number;
+  /**
+   * Derived key length in bytes. Defaults to 32 (AES-256).
+   */
+  length?: number;
+}
+/**
+ * The result of a password based derivation, including the salt needed to
+ * reproduce it.
+ */
+interface DerivedKey {
+  key: EncryptionKey;
+  salt: string;
+  iterations: number;
+}
+/**
+ * Options controlling how a shared secret is stretched into a channel key.
+ */
+interface ChannelOptions {
+  /**
+   * Domain separation string mixed into the HKDF `info` parameter. Two peers
+   * must use the same value to land on the same key.
+   */
+  info?: string;
+}
+/**
+ * Options for rendering a key fingerprint.
+ */
+interface FingerprintOptions {
+  /**
+   * Number of digest bytes to render. Defaults to 32 (the full SHA-256).
+   */
+  length?: number;
+  /**
+   * Output encoding. Defaults to `'hex'`.
+   */
+  encoding?: 'hex' | 'base64url';
+  /**
+   * When set, group the output into blocks of this many characters,
+   * separated by spaces. Makes fingerprints readable for manual comparison.
+   */
+  group?: number;
+}
+//#endregion
+//#region src/Cipher.d.ts
+/**
+ * AES-256-GCM symmetric encryption built on the Web Crypto API.
+ *
+ * Payloads are colon delimited base64url triples — `<iv>:<authTag>:<ciphertext>`
+ * — which is byte for byte the format Arkstack has always written. A value
+ * encrypted by a Node server decrypts in the browser and vice versa, provided
+ * both sides hold the same key.
+ */
+declare class Cipher {
+  readonly key: EncryptionKey;
+  /** Initialisation vector length in bytes. */
+  static readonly ivLength = 12;
+  /** GCM authentication tag length in bytes. */
+  static readonly tagLength = 16;
+  /**
+   * @param key The symmetric key this cipher operates with.
+   */
+  constructor(key: EncryptionKey);
+  /**
+   * Build a cipher from any accepted key representation.
+   *
+   * @param key
+   * @returns
+   */
+  static from(key: KeyInput): Promise<Cipher>;
+  /**
+   * Build a cipher backed by a freshly generated random key.
+   *
+   * @returns
+   */
+  static create(): Cipher;
+  /**
+   * Encrypt a string.
+   *
+   * @param value
+   * @param key
+   * @param options
+   * @returns
+   */
+  static encrypt(value: string, key: KeyInput, options?: CipherOptions): Promise<string>;
+  /**
+   * Decrypt a payload produced by {@link encrypt}.
+   *
+   * @param payload
+   * @param key
+   * @param options
+   * @returns
+   */
+  static decrypt(payload: string, key: KeyInput, options?: CipherOptions): Promise<string>;
+  /**
+   * Whether a string is shaped like a cipher payload. A cheap structural
+   * check, not an authenticity check.
+   *
+   * @param value
+   * @returns
+   */
+  static looksLikePayload(value: unknown): value is string;
+  /**
+   * Encrypt a UTF-8 string.
+   *
+   * @param value
+   * @param options
+   * @returns
+   */
+  encrypt(value: string, options?: CipherOptions): Promise<string>;
+  /**
+   * Decrypt a payload back into a UTF-8 string.
+   *
+   * @param payload
+   * @param options
+   * @returns
+   */
+  decrypt(payload: string, options?: CipherOptions): Promise<string>;
+  /**
+   * Encrypt arbitrary bytes.
+   *
+   * @param bytes
+   * @param options
+   * @returns
+   */
+  encryptBytes(bytes: Uint8Array, options?: CipherOptions): Promise<string>;
+  /**
+   * Decrypt a payload back into raw bytes.
+   *
+   * @param payload
+   * @param options
+   * @returns
+   */
+  decryptBytes(payload: string, options?: CipherOptions): Promise<Uint8Array>;
+  /**
+   * Import the key once per cipher instance.
+   *
+   * @returns
+   */
+  private cryptoKey;
+  /**
+   * Build the AES-GCM parameters for a single operation.
+   *
+   * @param iv
+   * @param options
+   * @returns
+   */
+  private parameters;
+  private imported?;
+}
+//#endregion
+//#region src/KeyPair.d.ts
+/**
+ * An ECDH P-256 key pair — the identity half of end-to-end encryption.
+ *
+ * P-256 is the curve every mainstream Web Crypto implementation supports, so a
+ * key pair generated in Node imports cleanly in the browser and vice versa.
+ * Keys serialise to base64url DER (SPKI for public, PKCS#8 for private), which
+ * survives JSON, headers, query strings and database columns unchanged.
+ */
+declare class KeyPair {
+  readonly publicKey: CryptoKey;
+  readonly privateKey?: CryptoKey | undefined;
+  /**
+   * @param publicKey
+   * @param privateKey Absent for peer key pairs, where only the public half is known.
+   */
+  constructor(publicKey: CryptoKey, privateKey?: CryptoKey | undefined);
+  /**
+   * Generate a new key pair.
+   *
+   * @returns
+   */
+  static generate(): Promise<KeyPair>;
+  /**
+   * Restore a key pair from its serialised form.
+   *
+   * @param serialized
+   * @returns
+   */
+  static import(serialized: SerializedKeyPair): Promise<KeyPair>;
+  /**
+   * Restore a full key pair from the private half alone; the public key is
+   * recovered from the private key's curve point.
+   *
+   * @param privateKey
+   * @returns
+   */
+  static fromPrivateKey(privateKey: string | CryptoKey): Promise<KeyPair>;
+  /**
+   * Wrap a peer's public key. The result can verify fingerprints and receive
+   * sealed messages, but cannot derive shared secrets on its own.
+   *
+   * @param publicKey
+   * @returns
+   */
+  static fromPublicKey(publicKey: string | CryptoKey): Promise<KeyPair>;
+  /**
+   * Import a base64url SPKI public key.
+   *
+   * @param publicKey
+   * @returns
+   */
+  static importPublicKey(publicKey: string): Promise<CryptoKey>;
+  /**
+   * Import a base64url PKCS#8 private key.
+   *
+   * @param privateKey
+   * @returns
+   */
+  static importPrivateKey(privateKey: string): Promise<CryptoKey>;
+  /**
+   * Export a public key to its base64url SPKI form.
+   *
+   * @param publicKey
+   * @returns
+   */
+  static exportPublicKey(publicKey: CryptoKey): Promise<string>;
+  /**
+   * Derive raw ECDH shared bits between a private key and a peer public key.
+   *
+   * The result is the raw curve point and must be stretched with a KDF before
+   * use as a cipher key — {@link SecureChannel} does that for you.
+   *
+   * @param privateKey
+   * @param peerPublicKey
+   * @param length Output length in bits, defaults to the P-256 field size.
+   * @returns
+   */
+  static sharedBits(privateKey: CryptoKey, peerPublicKey: CryptoKey, length?: number): Promise<Uint8Array>;
+  /**
+   * A human comparable digest of a public key. Two peers reading the same
+   * fingerprint aloud are holding the same key.
+   *
+   * @param publicKey
+   * @param options
+   * @returns
+   */
+  static fingerprintOf(publicKey: string | CryptoKey, options?: FingerprintOptions): Promise<string>;
+  /**
+   * The digest of both participants' public keys, ordered deterministically
+   * so each side computes the same value. Rendered as five digit groups in
+   * the style of a messaging app's safety number.
+   *
+   * @param first
+   * @param second
+   * @param groups How many five digit groups to render, defaults to 12.
+   * @returns
+   */
+  static safetyNumber(first: string, second: string, groups?: number): Promise<string>;
+  /**
+   * Order two public keys deterministically so both peers derive identical
+   * salts and safety numbers regardless of who initiated.
+   *
+   * @param first
+   * @param second
+   * @returns
+   */
+  static order(first: string, second: string): [string, string];
+  /**
+   * Whether the private half is available.
+   *
+   * @returns
+   */
+  get isComplete(): boolean;
+  /**
+   * Serialise both halves. Throws when the private key is missing.
+   *
+   * @returns
+   */
+  export(): Promise<SerializedKeyPair>;
+  /**
+   * The base64url SPKI public key, safe to publish.
+   *
+   * @returns
+   */
+  exportPublicKey(): Promise<string>;
+  /**
+   * Derive the raw ECDH shared bits with a peer.
+   *
+   * @param peerPublicKey
+   * @returns
+   */
+  sharedBits(peerPublicKey: string | CryptoKey | KeyPair): Promise<Uint8Array>;
+  /**
+   * A comparable digest of this key pair's public key.
+   *
+   * @param options
+   * @returns
+   */
+  fingerprint(options?: FingerprintOptions): Promise<string>;
+  /**
+   * Normalise anything that can stand in for a public key.
+   *
+   * @param value
+   * @returns
+   */
+  static resolvePublic(value: string | CryptoKey | KeyPair): Promise<CryptoKey>;
+}
+//#endregion
+//#region src/Keys.d.ts
+/**
+ * Key generation and comparison helpers.
+ *
+ * Generating keys is easy to get wrong quietly and comparing them is easy to
+ * get wrong dangerously, so both live here: every comparison in this class runs
+ * in constant time, and every generator draws from the platform CSPRNG.
+ */
+declare class Keys {
+  /**
+   * Generate a random symmetric key.
+   *
+   * @param length Key length in bytes, defaults to 32 (AES-256).
+   * @returns
+   */
+  static generate(length?: number): EncryptionKey;
+  /**
+   * Generate a random symmetric key as a base64url string, ready to store in
+   * an environment variable or a database column.
+   *
+   * @param length
+   * @returns
+   */
+  static generateString(length?: number): string;
+  /**
+   * Generate a random, URL safe token. Not a key — use it for invites,
+   * one-time links and other opaque identifiers.
+   *
+   * @param bytes
+   * @returns
+   */
+  static token(bytes?: number): string;
+  /**
+   * Generate an end-to-end encryption identity: an ECDH key pair whose public
+   * half is published and whose private half never leaves its owner.
+   *
+   * @returns
+   */
+  static generatePair(): Promise<KeyPair>;
+  /**
+   * Generate an identity and return it already serialised for storage or
+   * transport.
+   *
+   * @returns
+   */
+  static generateSerializedPair(): Promise<SerializedKeyPair>;
+  /**
+   * Hash an arbitrary secret into a key with SHA-256, the same way Arkstack
+   * turns `APP_KEY` into a cipher key.
+   *
+   * @param secret
+   * @returns
+   */
+  static fromSecret(secret: string): Promise<EncryptionKey>;
+  /**
+   * Stretch a user supplied password into a key with PBKDF2-HMAC-SHA256.
+   *
+   * @param password
+   * @param options
+   * @returns
+   */
+  static derive(password: string, options?: DeriveOptions): Promise<DerivedKey>;
+  /**
+   * Constant time comparison of two keys already in key form.
+   *
+   * @param left
+   * @param right
+   * @returns
+   */
+  static compare(left: EncryptionKey | Uint8Array | string, right: EncryptionKey | Uint8Array | string): boolean;
+  /**
+   * Constant time comparison that first resolves both sides through the same
+   * rules the ciphers use, so a passphrase can be checked against the key it
+   * produces.
+   *
+   * @param left
+   * @param right
+   * @param length Expected key length in bytes.
+   * @returns
+   */
+  static matches(left: KeyInput, right: KeyInput, length?: number): Promise<boolean>;
+  /**
+   * A displayable digest of a symmetric key.
+   *
+   * @param key
+   * @param options
+   * @returns
+   */
+  static fingerprint(key: KeyInput, options?: FingerprintOptions): Promise<string>;
+  /**
+   * A displayable digest of a public key, for comparing identities.
+   *
+   * @param publicKey
+   * @param options
+   * @returns
+   */
+  static fingerprintPublicKey(publicKey: string | CryptoKey, options?: FingerprintOptions): Promise<string>;
+  /**
+   * The safety number for a conversation between two public keys. Both peers
+   * compute the same string; showing it side by side proves no third party
+   * substituted a key in transit.
+   *
+   * @param first
+   * @param second
+   * @param groups
+   * @returns
+   */
+  static safetyNumber(first: string, second: string, groups?: number): Promise<string>;
+  /**
+   * Confirm a safety number a user read out or scanned, in constant time.
+   *
+   * @param first
+   * @param second
+   * @param expected
+   * @returns
+   */
+  static confirmSafetyNumber(first: string, second: string, expected: string): Promise<boolean>;
+  /**
+   * Whether two public keys refer to the same identity.
+   *
+   * @param left
+   * @param right
+   * @returns
+   */
+  static samePublicKey(left: string | CryptoKey | KeyPair, right: string | CryptoKey | KeyPair): Promise<boolean>;
+}
+//#endregion
+//#region src/SealedBox.d.ts
+/**
+ * Anonymous encryption to a public key.
+ *
+ * The sender needs no identity of their own: a throwaway key pair is generated
+ * per message, agreed with the recipient's public key over ECDH, and its public
+ * half is carried in the payload so the recipient can reproduce the secret.
+ * Only the holder of the matching private key can open the result — including
+ * the sender, who cannot decrypt their own message afterwards.
+ *
+ * Payloads look like `ark1:<ephemeralPublicKey>:<iv>:<authTag>:<ciphertext>`.
+ */
+declare class SealedBox {
+  /** Payload discriminator. */
+  static readonly prefix = "ark1";
+  /**
+   * Encrypt a message to a recipient's public key.
+   *
+   * @param message
+   * @param recipientPublicKey
+   * @param options
+   * @returns
+   */
+  static seal(message: string, recipientPublicKey: string | CryptoKey | KeyPair, options?: CipherOptions): Promise<string>;
+  /**
+   * Open a sealed payload with the recipient's private key.
+   *
+   * @param payload
+   * @param recipientPrivateKey
+   * @param options
+   * @returns
+   */
+  static open(payload: string, recipientPrivateKey: string | CryptoKey | KeyPair, options?: CipherOptions): Promise<string>;
+  /**
+   * Whether a string is shaped like a sealed payload.
+   *
+   * @param value
+   * @returns
+   */
+  static looksLikePayload(value: unknown): value is string;
+  /**
+   * Derive the one-off message key. Both sides feed the same ordered pair of
+   * public keys into the salt, so sender and recipient agree.
+   *
+   * @param owner              The side holding a private key.
+   * @param peer               The other side's public key.
+   * @param ephemeralPublicKey
+   * @param recipientPublicKey
+   * @returns
+   */
+  private static derive;
+}
+//#endregion
+//#region src/SecureChannel.d.ts
+/**
+ * A two party end-to-end encrypted channel.
+ *
+ * Each side combines its own private key with the other side's public key over
+ * ECDH, stretches the result with HKDF-SHA256, and ends up holding the exact
+ * same AES-256-GCM key without that key ever crossing the wire. Messages
+ * encrypted by either peer — in Node or in a browser — decrypt on the other.
+ *
+ * ```ts
+ * const alice = await KeyPair.generate()
+ * const bob = await KeyPair.generate()
+ *
+ * const outbound = await SecureChannel.between(alice, await bob.exportPublicKey())
+ * const inbound = await SecureChannel.between(bob, await alice.exportPublicKey())
+ *
+ * await inbound.decrypt(await outbound.encrypt('hey')) // 'hey'
+ * ```
+ */
+declare class SecureChannel {
+  readonly cipher: Cipher;
+  readonly localPublicKey: string;
+  readonly remotePublicKey: string;
+  /**
+   * @param cipher          The cipher bound to the derived shared key.
+   * @param localPublicKey  This side's public key, base64url.
+   * @param remotePublicKey The peer's public key, base64url.
+   */
+  private constructor();
+  /**
+   * Open a channel between a local key pair (or private key) and a peer's
+   * public key.
+   *
+   * @param local
+   * @param peerPublicKey
+   * @param options
+   * @returns
+   */
+  static between(local: KeyPair | string | CryptoKey, peerPublicKey: KeyPair | string | CryptoKey, options?: ChannelOptions): Promise<SecureChannel>;
+  /**
+   * The HKDF salt for a pair of participants: a digest over both public keys
+   * in a deterministic order, so both sides compute the same value.
+   *
+   * @param first
+   * @param second
+   * @returns
+   */
+  static salt(first: string, second: string): Promise<Uint8Array>;
+  /**
+   * The shared key both peers derived. Persist it only if you intend to skip
+   * the handshake later; it is as sensitive as the messages themselves.
+   *
+   * @returns
+   */
+  get key(): EncryptionKey;
+  /**
+   * Encrypt a message for the peer.
+   *
+   * @param message
+   * @param options
+   * @returns
+   */
+  encrypt(message: string, options?: CipherOptions): Promise<string>;
+  /**
+   * Decrypt a message from the peer.
+   *
+   * @param payload
+   * @param options
+   * @returns
+   */
+  decrypt(payload: string, options?: CipherOptions): Promise<string>;
+  /**
+   * Fingerprint of the derived shared key. Identical on both sides, and the
+   * cheapest way to assert two peers really did agree on the same secret.
+   *
+   * @param options
+   * @returns
+   */
+  fingerprint(options?: FingerprintOptions): Promise<string>;
+  /**
+   * The conversation's safety number: show it to both participants so they
+   * can confirm out of band that nobody is sitting in the middle.
+   *
+   * @param groups
+   * @returns
+   */
+  safetyNumber(groups?: number): Promise<string>;
+}
+//#endregion
+//#region src/support/codec.d.ts
+/**
+ * Runtime agnostic binary/text conversion helpers.
+ *
+ * Everything here is implemented against `Uint8Array`, `TextEncoder` and
+ * `TextDecoder` so the exact same code path runs in Node, Deno, Bun, browsers
+ * and workers. No `Buffer`, no `node:crypto`.
+ */
+declare class Codec {
+  private static readonly encoder;
+  private static readonly decoder;
+  /**
+   * Encode a UTF-8 string to bytes.
+   *
+   * @param value
+   * @returns
+   */
+  static encodeUtf8(value: string): Uint8Array;
+  /**
+   * Decode bytes back to a UTF-8 string.
+   *
+   * @param bytes
+   * @returns
+   */
+  static decodeUtf8(bytes: Uint8Array): string;
+  /**
+   * Encode bytes as standard (padded) base64.
+   *
+   * @param bytes
+   * @returns
+   */
+  static encodeBase64(bytes: Uint8Array): string;
+  /**
+   * Decode standard (padded or unpadded) base64 to bytes.
+   *
+   * @param value
+   * @returns
+   */
+  static decodeBase64(value: string): Uint8Array;
+  /**
+   * Encode bytes as unpadded base64url, the wire format used by every
+   * Arkstack encryption payload.
+   *
+   * @param bytes
+   * @returns
+   */
+  static encodeBase64Url(bytes: Uint8Array): string;
+  /**
+   * Decode a base64url string to bytes.
+   *
+   * @param value
+   * @returns
+   */
+  static decodeBase64Url(value: string): Uint8Array;
+  /**
+   * Encode bytes as lowercase hex.
+   *
+   * @param bytes
+   * @returns
+   */
+  static encodeHex(bytes: Uint8Array): string;
+  /**
+   * Decode a hex string to bytes.
+   *
+   * @param value
+   * @returns
+   */
+  static decodeHex(value: string): Uint8Array;
+  /**
+   * Concatenate byte sequences into a single buffer.
+   *
+   * @param parts
+   * @returns
+   */
+  static concat(...parts: Uint8Array[]): Uint8Array;
+  /**
+   * Compare two byte sequences without leaking their contents through timing.
+   *
+   * The length check is intentionally not constant time; key and digest
+   * lengths are public information.
+   *
+   * @param left
+   * @param right
+   * @returns
+   */
+  static equals(left: Uint8Array, right: Uint8Array): boolean;
+  /**
+   * Normalize a `Uint8Array`, `ArrayBuffer` or `ArrayBufferView` to bytes.
+   *
+   * @param value
+   * @returns
+   */
+  static toBytes(value: ArrayBuffer | ArrayBufferView): Uint8Array;
+  /**
+   * Restore base64 padding stripped by the base64url encoding.
+   *
+   * @param value
+   * @returns
+   */
+  private static pad;
+  /**
+   * Pure JS base64 encoder used when `btoa` is unavailable.
+   *
+   * @param bytes
+   * @returns
+   */
+  private static fallbackEncodeBase64;
+  /**
+   * Pure JS base64 decoder used when `atob` is unavailable.
+   *
+   * @param value
+   * @returns
+   */
+  private static fallbackDecodeBase64;
+}
+//#endregion
+//#region src/support/subtle.d.ts
+/**
+ * Resolve the ambient Web Crypto implementation.
+ *
+ * Node exposes it as `globalThis.crypto` from v19 (and behind
+ * `node:crypto`'s `webcrypto` export from v15), browsers and workers expose it
+ * on `window`/`self`. Secure contexts are required in browsers, hence the
+ * explicit error message.
+ *
+ * @returns
+ */
+declare const webCrypto: () => Crypto;
+/**
+ * Resolve `crypto.subtle`.
+ *
+ * @returns
+ */
+declare const subtle: () => SubtleCrypto;
+/**
+ * Fill a buffer with cryptographically secure random bytes.
+ *
+ * @param length
+ * @returns
+ */
+declare const randomBytes: (length: number) => Uint8Array;
+/**
+ * SHA digest helper returning bytes instead of an `ArrayBuffer`.
+ *
+ * @param data
+ * @param algorithm
+ * @returns
+ */
+declare const digest: (data: Uint8Array, algorithm?: "SHA-256" | "SHA-384" | "SHA-512") => Promise<Uint8Array>;
+//#endregion
+export { ChannelOptions, Cipher, CipherOptions, Codec, DeriveOptions, DerivedKey, EncryptionKey, FingerprintOptions, KeyInput, KeyPair, Keys, SealedBox, SecureChannel, SerializedKeyPair, digest, randomBytes, subtle, webCrypto };