mte-relay-browser-public-client 4.4.5 → 4.5.2

package/dist/types/cache.d.ts

@@ -0,0 +1,96 @@
+/**
+ * This file provides an in-memory caching layer for the MTE Relay client.
+ * It manages origin statuses, client IDs, pair queues, and MTE states to
+ * optimize performance and maintain session information. It also interacts
+ * with the persistent storage interface for durability.
+ */
+import { CACHE_KEYS } from "./constants";
+import type { OriginStatus } from "./types";
+/**
+ * Generates a standardized cache key.
+ * @param {keyof typeof CACHE_KEYS} type The type of cache entry.
+ * @param {string} id The unique identifier for the entry.
+ * @returns {string} The generated cache key.
+ */
+export declare const getCacheKey: (type: keyof typeof CACHE_KEYS, id: string) => string;
+/**
+ * Sets a value in the in-memory cache.
+ * @param {string} key The cache key.
+ * @param {*} value The value to store.
+ */
+export declare function setCacheItem(key: string, value: any): void;
+/**
+ * Gets a value from the in-memory cache.
+ * @param {string} key The cache key.
+ * @returns {T | undefined} The cached value.
+ */
+export declare function getCacheItem<T>(key: string): T | undefined;
+/**
+ * Deletes an item from the in-memory cache.
+ * @param {string} key The cache key.
+ */
+export declare function deleteCacheItem(key: string): void;
+/**
+ * Gets the current status of an origin.
+ * @param {string} origin The origin URL.
+ * @returns {OriginStatus} The current status.
+ */
+export declare function getOriginStatus(origin: string): OriginStatus;
+/**
+ * Sets the status for a given origin.
+ * @param {string} origin The origin URL.
+ * @param {OriginStatus} status The new status.
+ */
+export declare function setOriginStatus(origin: string, status: OriginStatus): void;
+/**
+ * Retrieves the client ID for a given origin, checking cache and persistent storage.
+ * @param {string} origin The origin URL.
+ * @returns {Promise<string | undefined>} The client ID.
+ */
+export declare function getClientId(origin: string): Promise<string | undefined>;
+/**
+ * Sets the client ID for an origin in cache and persistent storage.
+ * @param {string} origin The origin URL.
+ * @param {string} clientId The client ID.
+ */
+export declare function setClientId(origin: string, clientId: string): Promise<void>;
+/**
+ * Deletes the client ID for an origin from cache and persistent storage.
+ * @param {string} origin The origin URL.
+ */
+export declare function deleteClientId(origin: string): Promise<void>;
+/**
+ * Adds a new pair ID to an origin's queue.
+ * @param {string} origin The origin URL.
+ * @param {string} pairId The pair ID to add.
+ */
+export declare function addPairIdToQueue(origin: string, pairId: string): void;
+/**
+ * Gets the next available pair ID from an origin's queue and rotates it.
+ * @param {string} origin The origin URL.
+ * @returns {string} The next pair ID.
+ */
+export declare function getNextPairIdFromQueue(origin: string): string;
+/**
+ * Removes a specific pair ID from an origin's queue.
+ * @param {string} origin The origin URL.
+ * @param {string} pairId The pair ID to remove.
+ */
+export declare function deletePairIdFromQueue(origin: string, pairId: string): void;
+/**
+ * Clears all pair IDs for a given origin.
+ * @param {string} origin The origin URL.
+ */
+export declare function deleteAllPairsFromOrigin(origin: string): void;
+/**
+ * Caches the state of an MTE encoder or decoder.
+ * @param {string} id The unique identifier for the state.
+ * @param {string} state The Base64 encoded state string.
+ */
+export declare function setEncDecState(id: string, state: string): void;
+/**
+ * Retrieves the cached state of an MTE encoder or decoder.
+ * @param {string} id The unique identifier for the state.
+ * @returns {string | undefined} The Base64 encoded state string.
+ */
+export declare function getEncDecState(id: string): string | undefined;

package/dist/types/codec.d.ts

@@ -0,0 +1,30 @@
+/**
+ * This file handles the core logic for encoding outgoing requests and decoding
+ * incoming responses. It orchestrates the encryption/decryption of URLs,
+ * headers, and bodies.
+ */
+/**
+ * Encodes a Request object's URL, headers, and body.
+ * @param request The original Request object.
+ * @param options Configuration for the encoding process.
+ * @returns A new, MTE-encoded Request object.
+ */
+export declare function encodeRequest(request: Request, options: {
+    clientId: string;
+    origin: string;
+    pairId: string;
+    type: "MTE" | "MKE";
+    encodeUrl: boolean;
+    encodeHeaders: boolean | string[];
+    useStreaming: boolean;
+    pathPrefix: string;
+}): Promise<Request>;
+/**
+ * Decodes an MTE-encoded Response object's headers and body.
+ * @param response The MTE-encoded Response object.
+ * @param options Configuration for the decoding process.
+ * @returns A new, decoded Response object.
+ */
+export declare function decodeResponse(response: Response, options: {
+    decoderId: string;
+}): Promise<Response>;

package/dist/types/config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * This file manages the global configuration state for the MTE Relay client.
+ * It holds default settings, references to the MTE WASM instance, and other
+ * shared state that is initialized once and used throughout the library's
+ * lifecycle.
+ */
+import { MteWasm } from "mte";
+import type { MteRelayStorage } from "./types";
+export declare const config: {
+    numberOfPairs: number;
+    encodeType: "MTE" | "MKE";
+    encodeUrls: boolean;
+    encodeHeaders: boolean | string[];
+    pathPrefix: string;
+    mtePoolSize: number;
+    mkePoolSize: number;
+    persistentStorage: MteRelayStorage | undefined;
+    customFetch: typeof fetch | undefined;
+};
+export declare let mteWasm: MteWasm;
+export declare let finishEncryptBytes: number;
+export declare let isTrial: boolean;
+export declare let _fetch: typeof fetch;
+/**
+ * Sets the global MTE WASM instance.
+ * @param {MteWasm} wasmInstance The initialized MTE WASM instance.
+ */
+export declare function setMteWasm(wasmInstance: MteWasm): void;
+/**
+ * Sets the number of bytes required for MKE finishEncrypt operation.
+ * @param {number} bytes The number of bytes.
+ */
+export declare function setFinishEncryptBytes(bytes: number): void;
+/**
+ * Sets the flag indicating if the MTE library is a trial version.
+ * @param {boolean} trialStatus The trial status.
+ */
+export declare function setIsTrial(trialStatus: boolean): void;
+/**
+ * Sets the fetch implementation to be used by the client.
+ * @param {typeof fetch} fetchFn The fetch function.
+ */
+export declare function setFetch(fetchFn: typeof fetch): void;

package/dist/types/constants.d.ts

@@ -0,0 +1,27 @@
+/**
+ * This file contains constants used throughout the MTE Relay client.
+ * This includes header names, cache keys, and error message-to-status-code
+ * mappings. Centralizing these values makes configuration and maintenance easier.
+ */
+export declare const MTE_ENCODED_HEADERS_HEADER = "x-mte-relay-eh";
+export declare const MTE_RELAY_HEADER = "x-mte-relay";
+export declare const CACHE_KEYS: {
+    ORIGIN_STATUS: string;
+    CLIENT_ID: string;
+    PAIR_QUEUE: string;
+    MTE_STATE: string;
+    INIT_PROMISE: string;
+};
+export declare const MTE_ERRORS: {
+    readonly "Repair is required.": 559;
+    readonly "State not found.": 560;
+    readonly "Failed to encode.": 561;
+    readonly "Failed to decode.": 562;
+    readonly "Failed to get state from encoder or decoder.": 563;
+    readonly "DRBG reseed is required.": 564;
+    readonly "MTE Status was not successful.": 565;
+    readonly "Invalid Client ID header.": 566;
+    readonly "Failed to save decoder stateId.": 567;
+    readonly "Failed to save encoder stateId.": 568;
+    readonly "Missing required header": 569;
+};

package/dist/types/core.d.ts

@@ -0,0 +1,16 @@
+/**
+ * This file contains the core orchestration logic for the MTE Relay client.
+ * The `sendMteRequest` function acts as the central controller, managing the
+ * entire lifecycle of an MTE-protected request, including validation, pairing,
+ * encoding, decoding, and error handling.
+ */
+import type { MteRequestOptions } from "./types";
+/**
+ * Orchestrates the MTE fetch process, including pairing, encoding, and decoding.
+ * @param url The request URL or Request object.
+ * @param options Standard fetch options.
+ * @param mteOptions MTE-specific options.
+ * @param isRetry A flag to prevent infinite retry loops.
+ * @returns A Promise that resolves to a decoded Response.
+ */
+export declare function sendMteRequest(url: RequestInfo, options?: RequestInit, mteOptions?: Partial<MteRequestOptions>, isRetry?: boolean): Promise<Response>;

package/dist/types/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * This file defines a custom error class, MteRelayError, for handling
+ * specific errors that can occur during MTE Relay operations. It provides
+ * a structured way to manage server-side MTE errors and other client-side
+ * exceptions.
+ */
+import { MTE_ERRORS } from "./constants";
+type ErrorMessages = keyof typeof MTE_ERRORS;
+/**
+ * Custom error class for MTE Relay specific issues.
+ */
+export declare class MteRelayError extends Error {
+    status: number;
+    info?: Record<string, any>;
+    constructor(message: ErrorMessages, info?: Record<string, any>);
+    /**
+     * Checks if a given HTTP status code corresponds to a known MTE Relay error.
+     * @param {number} status The HTTP status code.
+     * @returns {boolean} True if it is a known MTE error status.
+     */
+    static isMteErrorStatus(status: number): boolean;
+    /**
+     * Retrieves the error message associated with a given MTE Relay status code.
+     * @param {number} status The HTTP status code.
+     * @returns {ErrorMessages | undefined} The corresponding error message.
+     */
+    static getStatusErrorMessages(status: number): ErrorMessages | undefined;
+}
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * This file serves as the main entry point for the MTE Relay client library.
+ * It exposes the public API, including the `initMteRelayClient` function for
+ * configuration and the `mteFetch` function for making MTE-protected requests.
+ * It also re-exports key types and classes for external use.
+ */
+import { LocalStorageWrapper, MemoryStorage } from "./storage";
+import type { MteRelayClientOptions, MteRequestOptions } from "./types";
+export { LocalStorageWrapper, MemoryStorage };
+export type { MteRelayStorage } from "./types";
+/**
+ * Initializes the MTE Relay Client. Must be called before `mteFetch`.
+ * @param {MteRelayClientOptions} options Configuration options for the client.
+ */
+export declare function initMteRelayClient(options: MteRelayClientOptions): Promise<void>;
+/**
+ * Sends an MTE-encoded request using a `fetch`-like interface.
+ * @param {RequestInfo} url The request URL or Request object.
+ * @param {RequestInit} [options] Standard fetch options.
+ * @param {Partial<MteRequestOptions>} [mteOptions] MTE-specific options.
+ * @returns {Promise<Response>} A Promise resolving to the decoded Response.
+ */
+export declare function mteFetch(url: RequestInfo, options?: RequestInit, mteOptions?: Partial<MteRequestOptions>): Promise<Response>;

package/dist/types/mte-helpers.d.ts

@@ -0,0 +1,50 @@
+/**
+ * This file contains functions for managing the MTE lifecycle, including WASM
+ * initialization, encoder/decoder instantiation, and object pooling. These
+ * helpers abstract the low-level details of interacting with the MTE Core library.
+ */
+import { MteDec, MteEnc, MteMkeDec, MteMkeEnc } from "mte";
+import type { EncDec } from "./types";
+/**
+ * Initializes the MTE WASM module and validates the license.
+ * @param options License information.
+ */
+export declare function initWasm(options: {
+    licenseKey: string;
+    companyName: string;
+}): Promise<void>;
+/**
+ * Retrieves an encoder or decoder instance from the appropriate pool.
+ * @param type The type of instance ("MTE" or "MKE").
+ * @param role The role of the instance ("encoder" or "decoder").
+ * @returns An MTE instance.
+ */
+export declare function getPoolItem(type: "MTE" | "MKE", role: "encoder"): MteEnc | MteMkeEnc;
+export declare function getPoolItem(type: "MTE" | "MKE", role: "decoder"): MteDec | MteMkeDec;
+/**
+ * Returns an MTE instance to its pool for reuse.
+ * @param {EncDec} item The MTE instance to return.
+ */
+export declare function returnPoolItem(item: EncDec): void;
+/**
+ * Creates and initializes a new MTE encoder instance.
+ * @param options Configuration for the new encoder.
+ */
+export declare function instantiateEncoder(options: {
+    origin: string;
+    pairId: string;
+    entropy: Uint8Array;
+    nonce: string;
+    personalization: string;
+}): Promise<void>;
+/**
+ * Creates and initializes a new MTE decoder instance.
+ * @param options Configuration for the new decoder.
+ */
+export declare function instantiateDecoder(options: {
+    origin: string;
+    pairId: string;
+    entropy: Uint8Array;
+    nonce: string;
+    personalization: string;
+}): Promise<void>;

package/dist/types/mte-state.d.ts

@@ -0,0 +1,18 @@
+/**
+ * This file contains functions for managing the saving and restoring of MTE
+ * encoder and decoder states. This is crucial for stateless operations and
+ * for persisting MTE sessions across requests.
+ */
+import type { EncDec } from "./types";
+/**
+ * Saves the current state of an MTE instance to a Base64 string.
+ * @param {EncDec} encdec The MTE instance.
+ * @returns {string} The Base64 encoded state.
+ */
+export declare function getMteState(encdec: EncDec): string;
+/**
+ * Restores an MTE instance's state from a Base64 string.
+ * @param {EncDec} encdec The MTE instance.
+ * @param {string} state The Base64 encoded state to restore.
+ */
+export declare function restoreMteState(encdec: EncDec, state: string): void;

package/dist/types/pairing.d.ts

@@ -0,0 +1,17 @@
+/**
+ * This file contains the logic for validating and pairing with an MTE Relay server.
+ * It handles the initial handshake to verify the server's identity and then
+ * establishes the encrypted communication channels (pairs) used for subsequent
+ * requests.
+ */
+/**
+ * Validates that a remote origin is an MTE Relay server.
+ * @param {string} origin The origin URL to validate.
+ */
+export declare function validateRemoteIsMteRelay(origin: string): Promise<void>;
+/**
+ * Establishes MTE encoder/decoder pairs with the MTE Relay server.
+ * @param {string} origin The origin URL to pair with.
+ * @param {number} [numberOfPairs] The number of pairs to create.
+ */
+export declare function pairWithOrigin(origin: string, numberOfPairs?: number): Promise<void>;

package/dist/types/storage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * This file provides isomorphic storage solutions for the MTE Relay client.
+ * It defines a standard interface and offers default implementations for
+ * in-memory and browser localStorage, allowing the client to run in various
+ * JavaScript environments.
+ */
+import type { MteRelayStorage } from "./types";
+/**
+ * A default in-memory storage implementation for server-side or environments
+ * without persistent storage.
+ */
+export declare class MemoryStorage implements MteRelayStorage {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * A wrapper for browser's localStorage to be used as persistent storage.
+ */
+export declare class LocalStorageWrapper implements MteRelayStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}

package/dist/types/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * This file contains shared TypeScript types and interfaces used throughout the
+ * MTE Relay client library. Centralizing these types helps maintain consistency
+ * and improves code clarity.
+ */
+import { MteDec, MteEnc, MteMkeDec, MteMkeEnc } from "mte";
+/**
+ * Interface for persistent storage. Allows for custom implementations
+ * in different environments (e.g., localStorage in browser, file system in Node).
+ */
+export interface MteRelayStorage {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+    removeItem(key: string): Promise<void> | void;
+}
+/**
+ * Configuration options for initializing the MTE Relay Client.
+ */
+export interface MteRelayClientOptions {
+    licenseKey: string;
+    licenseCompany: string;
+    numberOfPairs?: number;
+    mtePoolSize?: number;
+    mkePoolSize?: number;
+    encodeType?: "MTE" | "MKE";
+    encodeUrls?: boolean;
+    encodeHeaders?: boolean | string[];
+    pathPrefix?: string;
+    storage?: MteRelayStorage;
+    fetch?: typeof fetch;
+}
+/**
+ * Per-request options to override the default MTE encoding behavior.
+ */
+export interface MteRequestOptions {
+    encodeUrl: boolean;
+    encodeHeaders: boolean | string[];
+    encodeType: "MTE" | "MKE";
+    useStreaming: boolean;
+    pathPrefix: string;
+}
+/**
+ * Represents the parsed data from the x-mte-relay header.
+ */
+export interface MteRelayHeader {
+    clientId: string;
+    pairId: string;
+    type: "MTE" | "MKE";
+    urlIsEncoded: boolean;
+    headersAreEncoded: boolean;
+    bodyIsEncoded: boolean;
+    useStreaming: boolean;
+}
+/**
+ * The possible validation and pairing statuses for a given origin.
+ */
+export type OriginStatus = "paired" | "invalid" | "validate" | "pending";
+/**
+ * A union type representing any of the possible MTE encoder or decoder instances.
+ */
+export type EncDec = MteMkeEnc | MteMkeDec | MteEnc | MteDec;
+/**
+ * A union type representing the two supported encoding types.
+ */
+export type EncDecTypes = "MTE" | "MKE";

package/dist/types/utils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * This file contains utility functions for cryptography, data encoding,
+ * header manipulation, and MTE status validation. These helpers are used
+ * across different modules to perform common tasks.
+ */
+import { MteBase, MteStatus } from "mte";
+import type { EncDec, MteRelayHeader } from "./types";
+/**
+ * Creates a Kyber initiator instance for PQC key exchange.
+ * @returns An object with the public key and a function to decrypt the secret.
+ */
+export declare function getKyberInitiator(): {
+    publicKey: string;
+    decryptSecret: (encryptedSecretB64: string) => Uint8Array;
+};
+/**
+ * Generates a cryptographically random 16-byte hex string.
+ * @returns {string} A random hex string.
+ */
+export declare function getRandomStr(): string;
+/**
+ * Converts a Uint8Array to a Base64 string.
+ * @param {Uint8Array} bytes The byte array to convert.
+ * @returns {string} The Base64 encoded string.
+ */
+export declare function u8ToB64(bytes: Uint8Array): string;
+/**
+ * Converts a Base64 string to a Uint8Array.
+ * @param {string} base64 The Base64 string to convert.
+ * @returns {Uint8Array} The decoded byte array.
+ */
+export declare function b64ToU8(base64: string): Uint8Array;
+/**
+ * Formats the MTE Relay header object into a comma-separated string.
+ * @param {MteRelayHeader} options The header data.
+ * @returns {string} The formatted header string.
+ */
+export declare function formatMteRelayHeader(options: MteRelayHeader): string;
+/**
+ * Parses a comma-separated MTE Relay header string into an object.
+ * @param {string} header The header string.
+ * @returns {MteRelayHeader} The parsed header data.
+ */
+export declare function parseMteRelayHeader(header: string): MteRelayHeader;
+/**
+ * Validates that an MTE operation status is successful, throwing an error if not.
+ * @param {MteStatus} status The status returned from an MTE operation.
+ * @param {MteBase} mteBase The MTE instance used, for error reporting.
+ */
+export declare function validateStatusIsSuccess(status: MteStatus, mteBase: MteBase): void;
+export declare function drbgReseedCheck(encdec: EncDec): void;

package/package.json

@@ -1,16 +1,31 @@
-{
-  "name": "mte-relay-browser-public-client",
-  "version": "4.4.5",
-  "main": "./src/mte-relay-browser.js",
-  "scripts": {},
-  "author": "Eclypses Inc.",
-  "license": "ISC",
-  "description": "MTE Relay Browser is the Javascript client library for MTE Relay Server. See more at https://public-docs.eclypses.com/docs/mte-relay-server.",
-  "dependencies": {},
-  "exports": {
-    ".": {
-      "import": "./src/mte-relay-browser.mjs",
-      "require": "./src/mte-relay-browser.js"
-    }
-  }
-}
+{
+  "name": "mte-relay-browser-public-client",
+  "version": "4.5.2",
+  "main": "./src/index.ts",
+  "scripts": {
+    "build": "tsc && vite build"
+  },
+  "author": "Eclypses Inc.",
+  "license": "ISC",
+  "description": "MTE Relay Browser is the Javascript client library for MTE Relay Server. See more at https://public-docs.eclypses.com/docs/mte-relay-server.",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.1.4",
+    "mte": "npm:@eclypses/eclypses-inc-aws-client-aws-config-with-kyber@^4.2.0",
+    "mte-relay-browser": "^4.4.2",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.4"
+  }
+}