mrpc-js 0.1.2 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +135 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# mrpc-js
|
|
2
|
+
|
|
3
|
+
A lightweight, zero-dependency JavaScript reference implementation and serializer for the **mRPC (Minimal Remote Procedure Call)** protocol.
|
|
4
|
+
|
|
5
|
+
`mrpc-js` provides standard encoding, decoding, payload validation, and Web Crypto HMAC-SHA256 signing for secure, decoupled backend-frontend application stacks.
|
|
6
|
+
|
|
7
|
+
## 1. Specification (v1.0)
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
### Request Envelope Geometry
|
|
12
|
+
|
|
13
|
+
Outgoing request packets sent to the server MUST adhere to the following top-level JSON structure:
|
|
14
|
+
|
|
15
|
+
| Field | Type | Description |
|
|
16
|
+
|---------------|-----------|----------------------------------------------------------|
|
|
17
|
+
| `user_id` | `integer` | Authenticated user ID. Use `0` if guest/unauthenticated. |
|
|
18
|
+
| `version` | `string` | API version string (e.g., `"1.0.0"`). |
|
|
19
|
+
| `request_tag` | `string` | Client-generated string to pair asynchronous responses. |
|
|
20
|
+
| `timestamp` | `integer` | UTC timestamp in milliseconds (`Date.now()`). |
|
|
21
|
+
| `seed` | `string` | High-entropy 64-character random nonce. |
|
|
22
|
+
| `data` | `object` | Domain-specific payload params (`{}` if empty). |
|
|
23
|
+
| `auth` | `string` | Hex-encoded HMAC-SHA256 signature string. |
|
|
24
|
+
|
|
25
|
+
### Request Example
|
|
26
|
+
```JSON
|
|
27
|
+
{
|
|
28
|
+
"user_id": 42,
|
|
29
|
+
"version": "1.0.0",
|
|
30
|
+
"request_tag": "46588f3a1b9c",
|
|
31
|
+
"timestamp": 1724185200000,
|
|
32
|
+
"seed": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
|
|
33
|
+
"data": {
|
|
34
|
+
"account_id": 108
|
|
35
|
+
},
|
|
36
|
+
"auth": "a2c8f...91e3"
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### Response Envelope Geometry
|
|
41
|
+
|
|
42
|
+
Incoming response packets returned by the server MUST adhere to the following structure:
|
|
43
|
+
|
|
44
|
+
| Field | Type | Description |
|
|
45
|
+
|---------------|---------|----------------------------------------------------------------------|
|
|
46
|
+
| `success` | boolean | true if the request succeeded; false on failure. |
|
|
47
|
+
| `action` | string | Optional client directive (e.g., "refresh_token", "logout", "none"). |
|
|
48
|
+
| `request_tag` | string | Identical string mirrored directly from the incoming request. |
|
|
49
|
+
| `timestamp` | integer | Server UTC timestamp in milliseconds. |
|
|
50
|
+
| `seed` | string | High-entropy 64-character random nonce generated by the server. |
|
|
51
|
+
| `data` | object | Server response payload (or error metadata on failure). |
|
|
52
|
+
| `auth` | string | Hex-encoded HMAC-SHA256 signature returned by the server. |
|
|
53
|
+
|
|
54
|
+
### Response Example
|
|
55
|
+
```JSON
|
|
56
|
+
{
|
|
57
|
+
"success": true,
|
|
58
|
+
"action": "none",
|
|
59
|
+
"request_tag": "46588f3a1b9c",
|
|
60
|
+
"timestamp": 1724185200150,
|
|
61
|
+
"seed": "f4c8996fb92427ae41e4649b934ca495991b7852b855e3b0c44298fc1c149afb",
|
|
62
|
+
"data": {
|
|
63
|
+
"status": "active",
|
|
64
|
+
"balance": 250.00
|
|
65
|
+
},
|
|
66
|
+
"auth": "b4e9a...32f1"
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## 2. HMAC-SHA256 Signature Rules
|
|
71
|
+
|
|
72
|
+
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.
|
|
73
|
+
|
|
74
|
+
```
|
|
75
|
+
Message_Payload = serialize(data) + seed
|
|
76
|
+
Signature = HMAC-SHA256(Message_Payload, shared_secret)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
* **Browser Standard:** Generated via `globalThis.crypto.subtle` (`importKey` + `sign` with algorithm `"HMAC"` / `"SHA-256"`).
|
|
80
|
+
|
|
81
|
+
* **PHP Boundary (`mouse-php`):** Verified using `hash_hmac('sha256', $serializedData . $seed, $secret)`.
|
|
82
|
+
|
|
83
|
+
* **Zero Dependencies:** Uses standard native platform crypto routines without external libraries.
|
|
84
|
+
|
|
85
|
+
## 3. Usage & Examples
|
|
86
|
+
|
|
87
|
+
### Installing
|
|
88
|
+
```Bash
|
|
89
|
+
npm install mrpc-js
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Encoding & Signing a Request
|
|
93
|
+
```JavaScript
|
|
94
|
+
import { create_mRPC } from 'mrpc-js';
|
|
95
|
+
|
|
96
|
+
const data = {
|
|
97
|
+
// Domain-specific payload params
|
|
98
|
+
account_id: 108,
|
|
99
|
+
};
|
|
100
|
+
|
|
101
|
+
// Create a new mRPC packet with the following params:
|
|
102
|
+
// - user_id:
|
|
103
|
+
// - shared secret key:
|
|
104
|
+
// - version:
|
|
105
|
+
// - data:
|
|
106
|
+
// The rest of the fields are automatically generated by the library.
|
|
107
|
+
const packet = create_mRPC(42, "your-shared-secret-key", "1.0.0", data);
|
|
108
|
+
|
|
109
|
+
// Transmit `packet` over HTTP, WebSockets, or custom transport
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Decoding & Verifying a Response
|
|
113
|
+
```JavaScript
|
|
114
|
+
import { validate_mRPC_response } from 'mrpc-js';
|
|
115
|
+
|
|
116
|
+
// To verify a response packet is valid and not replayed:
|
|
117
|
+
// Call `validate_mRPC_response` with the following parameters:
|
|
118
|
+
// - response_packet: The raw response packet received from the server.
|
|
119
|
+
// - request_tag: The `request_tag` value from the original request packet.
|
|
120
|
+
// - shared_secret: The shared secret key used to sign the request.
|
|
121
|
+
// - window: Allowable time drift window in seconds (defaults to 300 seconds if omitted).
|
|
122
|
+
const valid = validate_mRPC_response(response_packet, request_tag, shared_secret, window);
|
|
123
|
+
|
|
124
|
+
// Returns true if the packet is valid and untampered, otherwise false.
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## 4. Routing & URI Convention
|
|
128
|
+
|
|
129
|
+
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`).
|
|
130
|
+
|
|
131
|
+
Because API versioning is handled directly within the signed `version` field of the payload envelope, URIs remain flat and clean.
|
|
132
|
+
|
|
133
|
+
* **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`).
|
|
134
|
+
* **Payload-Driven Actions:** The specific operation parameters, domain context, and API version are defined inside the signed request envelope.
|
|
135
|
+
* **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.
|