mrpc-js

A lightweight, zero-dependency JavaScript reference implementation and serializer for the mRPC (Minimal Remote Procedure Call) protocol.

mrpc-js provides standard encoding, decoding, payload validation, and Web Crypto HMAC-SHA256 signing for secure, decoupled backend-frontend application stacks.

1. Specification (v1.0)

mRPC is a transport-agnostic JSON payload standard designed for high-concurrency, low-overhead communication. It mandates cryptographic payload signing, UTC millisecond timing windows, and unique nonce tracking to ensure transport integrity and prevent replay attacks.

Request Envelope Geometry

Outgoing request packets sent to the server MUST adhere to the following top-level JSON structure:

| Field | Type | Description | |---------------|-----------|----------------------------------------------------------| | user_id | integer | Authenticated user ID. Use 0 if guest/unauthenticated. | | version | string | API version string (e.g., "1.0.0"). | | request_tag | string | Client-generated string to pair asynchronous responses. | | timestamp | integer | UTC timestamp in milliseconds (Date.now()). | | seed | string | High-entropy 64-character random nonce. | | data | object | Domain-specific payload params ({} if empty). | | auth | string | Hex-encoded HMAC-SHA256 signature string. |

Request Example

{
  "user_id": 42,
  "version": "1.0.0",
  "request_tag": "46588f3a1b9c",
  "timestamp": 1724185200000,
  "seed": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "data": {
    "account_id": 108
  },
  "auth": "a2c8f...91e3"
}

Response Envelope Geometry

Incoming response packets returned by the server MUST adhere to the following structure:

| Field | Type | Description | |---------------|---------|----------------------------------------------------------------------| | success | boolean | true if the request succeeded; false on failure. | | action | string | Optional client directive (e.g., "refresh_token", "logout", "none"). | | request_tag | string | Identical string mirrored directly from the incoming request. | | timestamp | integer | Server UTC timestamp in milliseconds. | | seed | string | High-entropy 64-character random nonce generated by the server. | | data | object | Server response payload (or error metadata on failure). | | auth | string | Hex-encoded HMAC-SHA256 signature returned by the server. |

Response Example

{
  "success": true,
  "action": "none",
  "request_tag": "46588f3a1b9c",
  "timestamp": 1724185200150,
  "seed": "f4c8996fb92427ae41e4649b934ca495991b7852b855e3b0c44298fc1c149afb",
  "data": {
    "status": "active",
    "balance": 250.00
  },
  "auth": "b4e9a...32f1"
}

2. HMAC-SHA256 Signature Rules

To guarantee cryptographic non-repudiation across languages, signatures MUST be generated by running HMAC-SHA256 on the concatenated payload string using the shared secret key.

Message_Payload = serialize(data) + seed
Signature = HMAC-SHA256(Message_Payload, shared_secret)

• Browser Standard: Generated via globalThis.crypto.subtle (importKey + sign with algorithm "HMAC" / "SHA-256").

• PHP Boundary (mouse-php): Verified using hash_hmac('sha256', $serializedData . $seed, $secret).

• Zero Dependencies: Uses standard native platform crypto routines without external libraries.

3. Usage & Examples

Installing

npm install mrpc-js

Encoding & Signing a Request

import { create_mRPC } from 'mrpc-js';

const data = {
    // Domain-specific payload params
  account_id: 108,
};

// Create a new mRPC packet with the following params:
// - user_id:
// - shared secret key:
// - version:
// - data:
// The rest of the fields are automatically generated by the library.
const packet = create_mRPC(42, "your-shared-secret-key", "1.0.0", data);

// Transmit `packet` over HTTP, WebSockets, or custom transport

Decoding & Verifying a Response

import { validate_mRPC_response } from 'mrpc-js';

// To verify a response packet is valid and not replayed:
// Call `validate_mRPC_response` with the following parameters:
// - response_packet: The raw response packet received from the server.
// - request_tag: The `request_tag` value from the original request packet.
// - shared_secret: The shared secret key used to sign the request.
// - window: Allowable time drift window in seconds (defaults to 300 seconds if omitted).
const valid = validate_mRPC_response(response_packet, request_tag, shared_secret, window);

// Returns true if the packet is valid and untampered, otherwise false.

4. Routing & URI Convention

Unlike standard REST endpoints that rely on diverse HTTP verbs (PUT, DELETE, PATCH) across dozens of URLs, mRPC is transport-agnostic and relies on single, action-focused controller endpoints (typically via POST).

Because API versioning is handled directly within the signed version field of the payload envelope, URIs remain flat and clean.

• Single Controller Mapping: A URI directly targets a server-side controller or handler method (e.g., POST /api/user/login), or a specific route tied directly to that resource (e.g., /api/login).
• Payload-Driven Actions: The specific operation parameters, domain context, and API version are defined inside the signed request envelope.
• Unified Transport: This keeps URL structures clean, simplifies reverse-proxy configuration (Nginx/Apache), and lets mouse-php dispatch requests through its high-speed Guard Pipe without route-parsing overhead.