@stryke/crypto 0.5.44 → 0.6.0

package/dist/cloudflare.d.cts

@@ -0,0 +1,251 @@
+//#region src/ed25519.d.ts
+/**
+ * Parameters for Ed25519 key generation and signing in Cloudflare Workers. This interface defines the algorithm name and named curve used for Ed25519 operations in the Cloudflare Workers environment. The `name` and `namedCurve` properties are set to "NODE-ED25519" to indicate that these parameters are specific to Cloudflare Workers' implementation of Ed25519, which is not compatible with standard Web Crypto API Ed25519 implementations in other environments.
+ */
+interface Ed25519Params {
+  name: "NODE-ED25519";
+  namedCurve: "NODE-ED25519";
+}
+/**
+ * Represents an Ed25519 key pair with a public key and a private key, both of which are CryptoKey objects. This interface is used to define the structure of the key pair generated by the `generateSigningKeyPair` function, where the `publicKey` is used for signature verification and the `privateKey` is used for signing operations. The keys are generated using Cloudflare Workers' `NODE-ED25519` algorithm parameters, which are specific to Cloudflare Workers' implementation of Ed25519 and are not compatible with standard Web Crypto API Ed25519 implementations in other environments.
+ */
+interface Ed25519KeyPair {
+  publicKey: CryptoKey;
+  privateKey: CryptoKey;
+}
+/**
+ * Generates an Ed25519 key pair using Cloudflare Workers' `NODE-ED25519` algorithm and returns the public key as a base64 string, the private key as a JWK object, and a key ID derived from the public key. The private key is returned as a JWK for compatibility with Web Crypto API operations.
+ *
+ * @remarks
+ * This function uses Cloudflare Workers' `NODE-ED25519` algorithm parameters, which are specific to Cloudflare Workers' implementation of Ed25519. The returned key pair is structured as follows:
+ * - The `publicKey` is returned as a base64url-encoded string of the raw public key bytes (the 'x' parameter from the JWK).
+ * - The `privateKeyJwk` is returned as a JWK object containing the private key parameters, which can be used for signing operations with the Web Crypto API.
+ * - The `keyId` is generated by hashing the raw public key bytes and taking the first 4 bytes of the hash, encoded as a hex string prefixed with "ed25519:". This provides a unique identifier for the key pair based on its public key.
+ *
+ * This function is not compatible with standard Web Crypto API Ed25519 implementations in other environments. The legacy function `generateSigningKeyPairLegacy` is also available for backwards compatibility, which returns the private key as a JSON stringified JWK. However, it is recommended to use this structured version for new code.
+ *
+ * @returns An object containing the `publicKey` as a base64 string, the `privateKeyJwk` as a JWK object, and a `keyId` derived from the public key.
+ * @throws {@link DOMException} If key generation or export fails in the Web Crypto API.
+ */
+declare function generateSigningKeyPair(): Promise<{
+  publicKey: string;
+  privateKeyJwk: JsonWebKey;
+  keyId: string;
+}>;
+/**
+ * Generates an Ed25519 key pair and returns the public key as a base64 string, the private key as a JSON stringified JWK, and a key ID derived from the public key. The private key is returned in a legacy format for compatibility with existing code that expects a JSON string.
+ *
+ * @remarks
+ * Legacy function for backwards compatibility during migration. Returns the old format but with a proper key.
+ *
+ * @deprecated Use `generateSigningKeyPair` instead, which returns a structured key object and separate key ID. This legacy function is retained for backwards compatibility but may be removed in future releases.
+ *
+ * @returns An object containing the `publicKey` as a base64 string, the `privateKey` as a JSON stringified JWK, and a `keyId` derived from the public key.
+ * @throws {@link SyntaxError} If the generated private key cannot be stringified to JSON (should not occur under normal circumstances).
+ */
+declare function generateSigningKeyPairLegacy(): Promise<{
+  publicKey: string;
+  privateKey: string;
+  keyId: string;
+}>;
+/**
+ * Creates and attaches an [Ed25519 signature](https://matrix.org/docs/spec/client_server/latest#signing-json-objects) for a JSON object using [Matrix-style](https://matrix.org/docs/spec/client_server/latest#signing-json-objects) signing rules.
+ *
+ * @see https://matrix.org/docs/spec/client_server/latest#signing-json-objects
+ *
+ * @remarks
+ * - Signature output is encoded as un-padded base64url.
+ * - The original `obj` is not mutated.
+ * - Uses `NODE-ED25519` algorithm parameters for key import/sign operations.
+ *
+ * The function canonicalizes a copy of the input object after removing the `signatures`
+ * and `unsigned` properties, signs that canonical JSON payload with the provided private key,
+ * and returns a new object with the generated signature merged into `obj.signatures`.
+ *
+ * Existing signatures are preserved, including other keys under the same `serverName`.
+ *
+ * @param obj - The JSON object to sign.
+ * @param serverName - The signing entity name used as the top-level key in `signatures`.
+ * @param keyId - The key identifier used under `signatures[serverName]`.
+ * @param privateKeyJwk - The Ed25519 private key as a JWK object, or a JSON stringified JWK (legacy compatibility).
+ * @returns A new object containing all original fields plus an updated `signatures` map with the new signature.
+ * @throws {@link SyntaxError} If `privateKeyJwk` is a string that is not valid JSON.
+ * @throws {@link DOMException} If key import or signing fails in the Web Crypto API.
+ */
+declare function signJson(obj: Record<string, unknown>, serverName: string, keyId: string, privateKeyJwk: JsonWebKey | string): Promise<Record<string, unknown>>;
+/**
+ * Verifies an Ed25519 signature on a JSON object using [Matrix-style signing rules](https://matrix.org/docs/spec/client_server/latest#signing-json-objects). The function extracts the relevant signature from the `signatures` property of the input object, removes the `signatures` and `unsigned` properties to create a canonical JSON payload, and then verifies the signature against the provided public key. The public key is expected to be a base64url-encoded string of the raw public key bytes (the 'x' parameter from the JWK). The function returns `true` if the signature is valid and `false` otherwise. Any errors during the verification process are caught and logged, with a return value of `false` in case of failure.
+ *
+ * @see https://matrix.org/docs/spec/client_server/latest#signing-json-objects
+ *
+ * @remarks
+ * - Signature input is expected to be un-padded base64url.
+ * - The original `obj` is not mutated.
+ * - Uses `NODE-ED25519` algorithm parameters for key import/verify operations.
+ * - The function does not throw on verification failure; it returns `false` instead. Errors during key import or verification are logged to the console for debugging purposes.
+ *
+ * @param obj - The JSON object containing the signature to verify.
+ * @param serverName - The signing entity name used as the top-level key in `signatures`.
+ * @param keyId - The key identifier used under `signatures[serverName]` to locate the specific signature to verify.
+ * @param publicKeyB64 - The Ed25519 public key as a base64url-encoded string of the raw public key bytes (the 'x' parameter from the JWK).
+ * @returns A boolean indicating whether the signature is valid (`true`) or not (`false`). Returns `false` if the signature is missing, invalid, or if any errors occur during the verification process.
+ */
+declare function verifySignature(obj: Record<string, unknown>, serverName: string, keyId: string, publicKeyB64: string): Promise<boolean>;
+//#endregion
+//#region src/base-64.d.ts
+/**
+ * Encodes a Uint8Array into a Base64 encoded Uint8Array.
+ *
+ * @credit https://github.com/hi-ogawa/js-utils
+ *
+ * @param input - The input Uint8Array or string to encode.
+ * @returns The Base64 encoded Uint8Array.
+ */
+declare function encodeBase64(input: Uint8Array | string): string;
+/**
+ * Decodes a Base64 encoded Uint8Array into a Uint8Array.
+ *
+ * @credit https://github.com/hi-ogawa/js-utils
+ *
+ * @param input - The Base64 encoded Uint8Array or string to decode.
+ * @returns The decoded Uint8Array.
+ */
+declare function decodeBase64(input: Uint8Array | string): Uint8Array;
+/**
+ * Converts a Base64 encoded string to a [Base64url](https://datatracker.ietf.org/doc/html/rfc7515#appendix-C) encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7515#appendix-C
+ *
+ * @param base64 - The Base64 encoded string to convert.
+ * @returns The Base64url encoded string.
+ */
+declare function base64UrlEncode(base64: Uint8Array): string;
+/**
+ * Converts a [Base64url](https://datatracker.ietf.org/doc/html/rfc7515#appendix-C) encoded string to a Base64 encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7515#appendix-C
+ *
+ * @param base64url - The Base64url encoded string to convert.
+ * @returns The Base64 encoded string.
+ */
+declare function base64UrlDecode(base64url: string): Uint8Array;
+//#endregion
+//#region src/encryption.d.ts
+/**
+ * Creates a CryptoKey object that can be used to encrypt any string.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey
+ *
+ * @returns A promise that resolves to a CryptoKey object that can be used to encrypt and decrypt strings.
+ */
+declare function createKey(): Promise<CryptoKey>;
+/**
+ * Encodes a CryptoKey to base64 string, so that it can be embedded in JSON / JavaScript
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/exportKey
+ *
+ * @param key - The CryptoKey to encode
+ * @returns A promise that resolves to a base64 string representing the key
+ */
+declare function encodeKey(key: CryptoKey): Promise<string>;
+/**
+ * Decodes a base64 string into bytes and then imports the key.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey
+ *
+ * @param encoded - The base64 encoded key
+ * @returns A promise that resolves to a CryptoKey object that can be used to encrypt and decrypt strings
+ */
+declare function decodeKey(encoded: string): Promise<CryptoKey>;
+/**
+ * Using a CryptoKey, use AES-GCM to encrypt a string into a base64 string.
+ *
+ * @remarks
+ * The initialization vector is randomly generated and prepended to the encrypted string. The IV is required for decryption, so it must be stored alongside the encrypted data.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/encrypt
+ *
+ * @param key - The CryptoKey to use for encryption
+ * @param plaintext - The plaintext string to encrypt
+ * @returns A promise that resolves to a base64 string representing the encrypted data
+ */
+declare function encrypt(key: CryptoKey, plaintext: string): Promise<string>;
+/**
+ * Takes a base64 encoded string, decodes it and returns the AES-GCM decrypted text.
+ *
+ * @remarks
+ * The initialization vector is expected to be prepended to the encrypted string. The IV is required for decryption, so it must be extracted from the start of the string.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/decrypt
+ *
+ * @param key - The CryptoKey to use for decryption
+ * @param encrypted - The encrypted base64 encoded string to decrypt
+ * @returns A promise that resolves to the decrypted string
+ */
+declare function decrypt(key: CryptoKey, encrypted: string): Promise<string>;
+/**
+ * Encrypts a buffer using AES-GCM with a given CryptoKey.
+ *
+ * @remarks
+ * The initialization vector (IV) is randomly generated and prepended to the encrypted data. The resulting data is then encoded as a base64 string for easy storage/transmission.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/encrypt
+ *
+ * @param key - The CryptoKey to use for encryption
+ * @param buffer - The buffer to encrypt
+ * @returns A promise that resolves to a base64 string representing the encrypted data
+ */
+declare function encryptBuffer(key: CryptoKey, buffer: BufferSource): Promise<string>;
+/**
+ * Decrypts a buffer using AES-GCM with a given CryptoKey.
+ *
+ * @remarks
+ * The initialization vector (IV) is expected to be prepended to the encrypted data. The IV is required for decryption, so it must be extracted from the start of the buffer.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/decrypt
+ *
+ * @param key - The CryptoKey to use for decryption
+ * @param encrypted - The encrypted base64 encoded string to decrypt
+ * @returns A promise that resolves to the decrypted string
+ */
+declare function decryptBuffer(key: CryptoKey, encrypted: string): Promise<ArrayBuffer>;
+//#endregion
+//#region src/hex.d.ts
+/**
+ * Encodes a Uint8Array into a hexadecimal string.
+ *
+ * @param input - The input Uint8Array.
+ * @returns The hexadecimal string.
+ */
+declare function encodeHex(input: Uint8Array): string;
+/**
+ * Encodes a Uint8Array into an uppercase hexadecimal string.
+ *
+ * @param input - The input Uint8Array.
+ * @returns The uppercase hexadecimal string.
+ */
+declare function decodeHex(input: string): Uint8Array;
+//#endregion
+//#region src/random.d.ts
+/**
+ * Generate a random byte array of the specified length using the Web Crypto API.
+ *
+ * @param length - The length of the random byte array to generate (default is 32 bytes)
+ * @returns A Uint8Array containing random bytes of the specified length
+ */
+declare function generateRandomBytes(length?: number): Uint8Array;
+/**
+ * Generate a random string of the specified length using characters A-Z, a-z, and 0-9 for CSRF tokens, etc.
+ *
+ * @remarks
+ * This function uses the Web Crypto API's `crypto.getRandomValues` to generate secure random bytes,
+ * and then maps those bytes to characters in the specified character set. It uses rejection sampling
+ * to ensure a uniform distribution of characters without modulo bias.
+ *
+ * @param length - The length of the random string to generate (default is 32 characters)
+ * @returns A random string of the specified length
+ */
+declare function generateRandomString(length?: number): string;
+//#endregion
+export { Ed25519KeyPair, Ed25519Params, base64UrlDecode, base64UrlEncode, createKey, decodeBase64, decodeHex, decodeKey, decrypt, decryptBuffer, encodeBase64, encodeHex, encodeKey, encrypt, encryptBuffer, generateRandomBytes, generateRandomString, generateSigningKeyPair, generateSigningKeyPairLegacy, signJson, verifySignature };
+//# sourceMappingURL=cloudflare.d.cts.map

package/dist/cloudflare.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.d.cts","names":[],"sources":["../src/ed25519.ts","../src/base-64.ts","../src/encryption.ts","../src/hex.ts","../src/random.ts"],"sourcesContent":[],"mappings":";;AAwBA;AAQA;AAmBsB,UA3BL,aAAA,CA2B2B;EAgDtB,IAAA,EAAA,cAAA;EAsCA,UAAA,EAAQ,cAAA;;;;;AAKpB,UA9GO,cAAA,CA8GP;EAmEY,SAAA,EAhLT,SAgLwB;cA/KvB;;;ACkCd;AAmDA;AAkFA;AAeA;;;;ACrLA;AAmBA;AAcA;AA4BA;AA8BA;AA4BA;AACO,iBFxGe,sBAAA,CAAA,CEwGf,EFxGyC,OEwGzC,CAAA;EACG,SAAA,EAAA,MAAA;EACP,aAAA,EFxGc,UEwGd;EAAO,KAAA,EAAA,MAAA;AA0BV,CAAA,CAAA;;;;;;;;ACrIA;AAeA;;;iBHkCsB,4BAAA,CAAA,GAAgC;EI3EtC,SAAA,EAAA,MAAA;EAeA,UAAA,EAAA,MAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBJkGM,QAAA,MACf,2EAGU,sBACd,QAAQ;;;;;;;;;;;;;;;;;;iBAmEW,eAAA,MACf,mFAIJ;;;;AA9LH;AAQA;AAmBA;AAgDA;AAsCA;;;AAKW,iBC1EK,YAAA,CD0EL,KAAA,EC1EyB,UD0EzB,GAAA,MAAA,CAAA,EAAA,MAAA;;;AAmEX;;;;AC7IA;AAmDA;AAkFgB,iBAlFA,YAAA,CAkFwB,KAAA,EAlFJ,UAkFc,GAAA,MAAA,CAAA,EAlFQ,UAkFR;AAelD;;;;ACrLA;AAmBA;AAcA;AA4BA;AA8BsB,iBD2EN,eAAA,CCxEb,MAAO,EDwE8B,UCxE9B,CAAA,EAAA,MAAA;AAyBV;;;;;AA6BA;;;AAGG,iBD8Ba,eAAA,CC9Bb,SAAA,EAAA,MAAA,CAAA,ED8BiD,UC9BjD;;;;AFlKH;AAQA;AAmBA;AAgDA;AAsCA;;AAIiB,iBE1GK,SAAA,CAAA,CF0GL,EE1GkB,OF0GlB,CE1G0B,SF0G1B,CAAA;;;;AAoEjB;;;;AC7IA;AAmDgB,iBCjEM,SAAA,CDiEc,GAAA,ECjEC,SDiEqB,CAAA,ECjET,ODiEmB,CAAA,MAAA,CAAA;AAkFpE;AAeA;;;;ACrLA;AAmBA;AAcA;AA4BsB,iBA5BA,SAAA,CA6Bf,OAEJ,EAAA,MAAO,CAAA,EA/BwC,OA+BxC,CA/BgD,SA+BhD,CAAA;AA2BV;AA4BA;;;;;AA6BA;;;;;;iBAvFsB,OAAA,MACf,+BAEJ;;ACjDH;AAeA;;;;ACzCA;AAeA;;;;;iBFuFsB,OAAA,MACf,+BAEJ;;;;;;;;;;;;;iBAyBmB,aAAA,MACf,mBACG,eACP;;;;;;;;;;;;;iBA0BmB,aAAA,MACf,+BAEJ,QAAQ;;;;AFlKX;AAQA;AAmBA;AAgDA;AAsCA;AACO,iBGxFS,SAAA,CHwFT,KAAA,EGxF0B,UHwF1B,CAAA,EAAA,MAAA;;;;;AAuEP;;iBGhJgB,SAAA,iBAA0B;;;;AHzC1C;AAQA;AAmBA;AAgDA;AAsCA;AACO,iBIlHS,mBAAA,CJkHT,MAAA,CAAA,EAAA,MAAA,CAAA,EIlHmD,UJkHnD;;;;;AAuEP;;;;AC7IA;AAmDA;AAkFA;AAegB,iBGjLA,oBAAA,CHiL8C,MAAA,CAAA,EAAA,MAAA,CAAA,EAAA,MAAA"}

package/dist/cloudflare.d.mts

@@ -0,0 +1,251 @@
+//#region src/ed25519.d.ts
+/**
+ * Parameters for Ed25519 key generation and signing in Cloudflare Workers. This interface defines the algorithm name and named curve used for Ed25519 operations in the Cloudflare Workers environment. The `name` and `namedCurve` properties are set to "NODE-ED25519" to indicate that these parameters are specific to Cloudflare Workers' implementation of Ed25519, which is not compatible with standard Web Crypto API Ed25519 implementations in other environments.
+ */
+interface Ed25519Params {
+  name: "NODE-ED25519";
+  namedCurve: "NODE-ED25519";
+}
+/**
+ * Represents an Ed25519 key pair with a public key and a private key, both of which are CryptoKey objects. This interface is used to define the structure of the key pair generated by the `generateSigningKeyPair` function, where the `publicKey` is used for signature verification and the `privateKey` is used for signing operations. The keys are generated using Cloudflare Workers' `NODE-ED25519` algorithm parameters, which are specific to Cloudflare Workers' implementation of Ed25519 and are not compatible with standard Web Crypto API Ed25519 implementations in other environments.
+ */
+interface Ed25519KeyPair {
+  publicKey: CryptoKey;
+  privateKey: CryptoKey;
+}
+/**
+ * Generates an Ed25519 key pair using Cloudflare Workers' `NODE-ED25519` algorithm and returns the public key as a base64 string, the private key as a JWK object, and a key ID derived from the public key. The private key is returned as a JWK for compatibility with Web Crypto API operations.
+ *
+ * @remarks
+ * This function uses Cloudflare Workers' `NODE-ED25519` algorithm parameters, which are specific to Cloudflare Workers' implementation of Ed25519. The returned key pair is structured as follows:
+ * - The `publicKey` is returned as a base64url-encoded string of the raw public key bytes (the 'x' parameter from the JWK).
+ * - The `privateKeyJwk` is returned as a JWK object containing the private key parameters, which can be used for signing operations with the Web Crypto API.
+ * - The `keyId` is generated by hashing the raw public key bytes and taking the first 4 bytes of the hash, encoded as a hex string prefixed with "ed25519:". This provides a unique identifier for the key pair based on its public key.
+ *
+ * This function is not compatible with standard Web Crypto API Ed25519 implementations in other environments. The legacy function `generateSigningKeyPairLegacy` is also available for backwards compatibility, which returns the private key as a JSON stringified JWK. However, it is recommended to use this structured version for new code.
+ *
+ * @returns An object containing the `publicKey` as a base64 string, the `privateKeyJwk` as a JWK object, and a `keyId` derived from the public key.
+ * @throws {@link DOMException} If key generation or export fails in the Web Crypto API.
+ */
+declare function generateSigningKeyPair(): Promise<{
+  publicKey: string;
+  privateKeyJwk: JsonWebKey;
+  keyId: string;
+}>;
+/**
+ * Generates an Ed25519 key pair and returns the public key as a base64 string, the private key as a JSON stringified JWK, and a key ID derived from the public key. The private key is returned in a legacy format for compatibility with existing code that expects a JSON string.
+ *
+ * @remarks
+ * Legacy function for backwards compatibility during migration. Returns the old format but with a proper key.
+ *
+ * @deprecated Use `generateSigningKeyPair` instead, which returns a structured key object and separate key ID. This legacy function is retained for backwards compatibility but may be removed in future releases.
+ *
+ * @returns An object containing the `publicKey` as a base64 string, the `privateKey` as a JSON stringified JWK, and a `keyId` derived from the public key.
+ * @throws {@link SyntaxError} If the generated private key cannot be stringified to JSON (should not occur under normal circumstances).
+ */
+declare function generateSigningKeyPairLegacy(): Promise<{
+  publicKey: string;
+  privateKey: string;
+  keyId: string;
+}>;
+/**
+ * Creates and attaches an [Ed25519 signature](https://matrix.org/docs/spec/client_server/latest#signing-json-objects) for a JSON object using [Matrix-style](https://matrix.org/docs/spec/client_server/latest#signing-json-objects) signing rules.
+ *
+ * @see https://matrix.org/docs/spec/client_server/latest#signing-json-objects
+ *
+ * @remarks
+ * - Signature output is encoded as un-padded base64url.
+ * - The original `obj` is not mutated.
+ * - Uses `NODE-ED25519` algorithm parameters for key import/sign operations.
+ *
+ * The function canonicalizes a copy of the input object after removing the `signatures`
+ * and `unsigned` properties, signs that canonical JSON payload with the provided private key,
+ * and returns a new object with the generated signature merged into `obj.signatures`.
+ *
+ * Existing signatures are preserved, including other keys under the same `serverName`.
+ *
+ * @param obj - The JSON object to sign.
+ * @param serverName - The signing entity name used as the top-level key in `signatures`.
+ * @param keyId - The key identifier used under `signatures[serverName]`.
+ * @param privateKeyJwk - The Ed25519 private key as a JWK object, or a JSON stringified JWK (legacy compatibility).
+ * @returns A new object containing all original fields plus an updated `signatures` map with the new signature.
+ * @throws {@link SyntaxError} If `privateKeyJwk` is a string that is not valid JSON.
+ * @throws {@link DOMException} If key import or signing fails in the Web Crypto API.
+ */
+declare function signJson(obj: Record<string, unknown>, serverName: string, keyId: string, privateKeyJwk: JsonWebKey | string): Promise<Record<string, unknown>>;
+/**
+ * Verifies an Ed25519 signature on a JSON object using [Matrix-style signing rules](https://matrix.org/docs/spec/client_server/latest#signing-json-objects). The function extracts the relevant signature from the `signatures` property of the input object, removes the `signatures` and `unsigned` properties to create a canonical JSON payload, and then verifies the signature against the provided public key. The public key is expected to be a base64url-encoded string of the raw public key bytes (the 'x' parameter from the JWK). The function returns `true` if the signature is valid and `false` otherwise. Any errors during the verification process are caught and logged, with a return value of `false` in case of failure.
+ *
+ * @see https://matrix.org/docs/spec/client_server/latest#signing-json-objects
+ *
+ * @remarks
+ * - Signature input is expected to be un-padded base64url.
+ * - The original `obj` is not mutated.
+ * - Uses `NODE-ED25519` algorithm parameters for key import/verify operations.
+ * - The function does not throw on verification failure; it returns `false` instead. Errors during key import or verification are logged to the console for debugging purposes.
+ *
+ * @param obj - The JSON object containing the signature to verify.
+ * @param serverName - The signing entity name used as the top-level key in `signatures`.
+ * @param keyId - The key identifier used under `signatures[serverName]` to locate the specific signature to verify.
+ * @param publicKeyB64 - The Ed25519 public key as a base64url-encoded string of the raw public key bytes (the 'x' parameter from the JWK).
+ * @returns A boolean indicating whether the signature is valid (`true`) or not (`false`). Returns `false` if the signature is missing, invalid, or if any errors occur during the verification process.
+ */
+declare function verifySignature(obj: Record<string, unknown>, serverName: string, keyId: string, publicKeyB64: string): Promise<boolean>;
+//#endregion
+//#region src/base-64.d.ts
+/**
+ * Encodes a Uint8Array into a Base64 encoded Uint8Array.
+ *
+ * @credit https://github.com/hi-ogawa/js-utils
+ *
+ * @param input - The input Uint8Array or string to encode.
+ * @returns The Base64 encoded Uint8Array.
+ */
+declare function encodeBase64(input: Uint8Array | string): string;
+/**
+ * Decodes a Base64 encoded Uint8Array into a Uint8Array.
+ *
+ * @credit https://github.com/hi-ogawa/js-utils
+ *
+ * @param input - The Base64 encoded Uint8Array or string to decode.
+ * @returns The decoded Uint8Array.
+ */
+declare function decodeBase64(input: Uint8Array | string): Uint8Array;
+/**
+ * Converts a Base64 encoded string to a [Base64url](https://datatracker.ietf.org/doc/html/rfc7515#appendix-C) encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7515#appendix-C
+ *
+ * @param base64 - The Base64 encoded string to convert.
+ * @returns The Base64url encoded string.
+ */
+declare function base64UrlEncode(base64: Uint8Array): string;
+/**
+ * Converts a [Base64url](https://datatracker.ietf.org/doc/html/rfc7515#appendix-C) encoded string to a Base64 encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7515#appendix-C
+ *
+ * @param base64url - The Base64url encoded string to convert.
+ * @returns The Base64 encoded string.
+ */
+declare function base64UrlDecode(base64url: string): Uint8Array;
+//#endregion
+//#region src/encryption.d.ts
+/**
+ * Creates a CryptoKey object that can be used to encrypt any string.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey
+ *
+ * @returns A promise that resolves to a CryptoKey object that can be used to encrypt and decrypt strings.
+ */
+declare function createKey(): Promise<CryptoKey>;
+/**
+ * Encodes a CryptoKey to base64 string, so that it can be embedded in JSON / JavaScript
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/exportKey
+ *
+ * @param key - The CryptoKey to encode
+ * @returns A promise that resolves to a base64 string representing the key
+ */
+declare function encodeKey(key: CryptoKey): Promise<string>;
+/**
+ * Decodes a base64 string into bytes and then imports the key.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey
+ *
+ * @param encoded - The base64 encoded key
+ * @returns A promise that resolves to a CryptoKey object that can be used to encrypt and decrypt strings
+ */
+declare function decodeKey(encoded: string): Promise<CryptoKey>;
+/**
+ * Using a CryptoKey, use AES-GCM to encrypt a string into a base64 string.
+ *
+ * @remarks
+ * The initialization vector is randomly generated and prepended to the encrypted string. The IV is required for decryption, so it must be stored alongside the encrypted data.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/encrypt
+ *
+ * @param key - The CryptoKey to use for encryption
+ * @param plaintext - The plaintext string to encrypt
+ * @returns A promise that resolves to a base64 string representing the encrypted data
+ */
+declare function encrypt(key: CryptoKey, plaintext: string): Promise<string>;
+/**
+ * Takes a base64 encoded string, decodes it and returns the AES-GCM decrypted text.
+ *
+ * @remarks
+ * The initialization vector is expected to be prepended to the encrypted string. The IV is required for decryption, so it must be extracted from the start of the string.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/decrypt
+ *
+ * @param key - The CryptoKey to use for decryption
+ * @param encrypted - The encrypted base64 encoded string to decrypt
+ * @returns A promise that resolves to the decrypted string
+ */
+declare function decrypt(key: CryptoKey, encrypted: string): Promise<string>;
+/**
+ * Encrypts a buffer using AES-GCM with a given CryptoKey.
+ *
+ * @remarks
+ * The initialization vector (IV) is randomly generated and prepended to the encrypted data. The resulting data is then encoded as a base64 string for easy storage/transmission.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/encrypt
+ *
+ * @param key - The CryptoKey to use for encryption
+ * @param buffer - The buffer to encrypt
+ * @returns A promise that resolves to a base64 string representing the encrypted data
+ */
+declare function encryptBuffer(key: CryptoKey, buffer: BufferSource): Promise<string>;
+/**
+ * Decrypts a buffer using AES-GCM with a given CryptoKey.
+ *
+ * @remarks
+ * The initialization vector (IV) is expected to be prepended to the encrypted data. The IV is required for decryption, so it must be extracted from the start of the buffer.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/decrypt
+ *
+ * @param key - The CryptoKey to use for decryption
+ * @param encrypted - The encrypted base64 encoded string to decrypt
+ * @returns A promise that resolves to the decrypted string
+ */
+declare function decryptBuffer(key: CryptoKey, encrypted: string): Promise<ArrayBuffer>;
+//#endregion
+//#region src/hex.d.ts
+/**
+ * Encodes a Uint8Array into a hexadecimal string.
+ *
+ * @param input - The input Uint8Array.
+ * @returns The hexadecimal string.
+ */
+declare function encodeHex(input: Uint8Array): string;
+/**
+ * Encodes a Uint8Array into an uppercase hexadecimal string.
+ *
+ * @param input - The input Uint8Array.
+ * @returns The uppercase hexadecimal string.
+ */
+declare function decodeHex(input: string): Uint8Array;
+//#endregion
+//#region src/random.d.ts
+/**
+ * Generate a random byte array of the specified length using the Web Crypto API.
+ *
+ * @param length - The length of the random byte array to generate (default is 32 bytes)
+ * @returns A Uint8Array containing random bytes of the specified length
+ */
+declare function generateRandomBytes(length?: number): Uint8Array;
+/**
+ * Generate a random string of the specified length using characters A-Z, a-z, and 0-9 for CSRF tokens, etc.
+ *
+ * @remarks
+ * This function uses the Web Crypto API's `crypto.getRandomValues` to generate secure random bytes,
+ * and then maps those bytes to characters in the specified character set. It uses rejection sampling
+ * to ensure a uniform distribution of characters without modulo bias.
+ *
+ * @param length - The length of the random string to generate (default is 32 characters)
+ * @returns A random string of the specified length
+ */
+declare function generateRandomString(length?: number): string;
+//#endregion
+export { Ed25519KeyPair, Ed25519Params, base64UrlDecode, base64UrlEncode, createKey, decodeBase64, decodeHex, decodeKey, decrypt, decryptBuffer, encodeBase64, encodeHex, encodeKey, encrypt, encryptBuffer, generateRandomBytes, generateRandomString, generateSigningKeyPair, generateSigningKeyPairLegacy, signJson, verifySignature };
+//# sourceMappingURL=cloudflare.d.mts.map

package/dist/cloudflare.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.d.mts","names":[],"sources":["../src/ed25519.ts","../src/base-64.ts","../src/encryption.ts","../src/hex.ts","../src/random.ts"],"sourcesContent":[],"mappings":";;AAwBA;AAQA;AAmBsB,UA3BL,aAAA,CA2B2B;EAgDtB,IAAA,EAAA,cAAA;EAsCA,UAAA,EAAQ,cAAA;;;;;AAKpB,UA9GO,cAAA,CA8GP;EAmEY,SAAA,EAhLT,SAgLwB;cA/KvB;;;ACkCd;AAmDA;AAkFA;AAeA;;;;ACrLA;AAmBA;AAcA;AA4BA;AA8BA;AA4BA;AACO,iBFxGe,sBAAA,CAAA,CEwGf,EFxGyC,OEwGzC,CAAA;EACG,SAAA,EAAA,MAAA;EACP,aAAA,EFxGc,UEwGd;EAAO,KAAA,EAAA,MAAA;AA0BV,CAAA,CAAA;;;;;;;;ACrIA;AAeA;;;iBHkCsB,4BAAA,CAAA,GAAgC;EI3EtC,SAAA,EAAA,MAAA;EAeA,UAAA,EAAA,MAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBJkGM,QAAA,MACf,2EAGU,sBACd,QAAQ;;;;;;;;;;;;;;;;;;iBAmEW,eAAA,MACf,mFAIJ;;;;AA9LH;AAQA;AAmBA;AAgDA;AAsCA;;;AAKW,iBC1EK,YAAA,CD0EL,KAAA,EC1EyB,UD0EzB,GAAA,MAAA,CAAA,EAAA,MAAA;;;AAmEX;;;;AC7IA;AAmDA;AAkFgB,iBAlFA,YAAA,CAkFwB,KAAA,EAlFJ,UAkFc,GAAA,MAAA,CAAA,EAlFQ,UAkFR;AAelD;;;;ACrLA;AAmBA;AAcA;AA4BA;AA8BsB,iBD2EN,eAAA,CCxEb,MAAO,EDwE8B,UCxE9B,CAAA,EAAA,MAAA;AAyBV;;;;;AA6BA;;;AAGG,iBD8Ba,eAAA,CC9Bb,SAAA,EAAA,MAAA,CAAA,ED8BiD,UC9BjD;;;;AFlKH;AAQA;AAmBA;AAgDA;AAsCA;;AAIiB,iBE1GK,SAAA,CAAA,CF0GL,EE1GkB,OF0GlB,CE1G0B,SF0G1B,CAAA;;;;AAoEjB;;;;AC7IA;AAmDgB,iBCjEM,SAAA,CDiEc,GAAA,ECjEC,SDiEqB,CAAA,ECjET,ODiEmB,CAAA,MAAA,CAAA;AAkFpE;AAeA;;;;ACrLA;AAmBA;AAcA;AA4BsB,iBA5BA,SAAA,CA6Bf,OAEJ,EAAA,MAAO,CAAA,EA/BwC,OA+BxC,CA/BgD,SA+BhD,CAAA;AA2BV;AA4BA;;;;;AA6BA;;;;;;iBAvFsB,OAAA,MACf,+BAEJ;;ACjDH;AAeA;;;;ACzCA;AAeA;;;;;iBFuFsB,OAAA,MACf,+BAEJ;;;;;;;;;;;;;iBAyBmB,aAAA,MACf,mBACG,eACP;;;;;;;;;;;;;iBA0BmB,aAAA,MACf,+BAEJ,QAAQ;;;;AFlKX;AAQA;AAmBA;AAgDA;AAsCA;AACO,iBGxFS,SAAA,CHwFT,KAAA,EGxF0B,UHwF1B,CAAA,EAAA,MAAA;;;;;AAuEP;;iBGhJgB,SAAA,iBAA0B;;;;AHzC1C;AAQA;AAmBA;AAgDA;AAsCA;AACO,iBIlHS,mBAAA,CJkHT,MAAA,CAAA,EAAA,MAAA,CAAA,EIlHmD,UJkHnD;;;;;AAuEP;;;;AC7IA;AAmDA;AAkFA;AAegB,iBGjLA,oBAAA,CHiL8C,MAAA,CAAA,EAAA,MAAA,CAAA,EAAA,MAAA"}