@private.me/xbind 3.0.1 → 3.0.2
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 +55 -14
- package/dist-standalone/_deps/mldsa-wasm/dist/mldsa.js +1920 -1
- package/dist-standalone/_deps/shared/cjs/errors.js +729 -1
- package/dist-standalone/_deps/shared/cjs/index.js +463 -1
- package/dist-standalone/_deps/shared/cjs/types.js +315 -1
- package/dist-standalone/_deps/shared/errors.js +244 -1
- package/dist-standalone/_deps/shared/index.js +72 -1
- package/dist-standalone/_deps/shared/types.js +86 -1
- package/dist-standalone/_deps/ux-helpers/cjs/errors.js +1 -1
- package/dist-standalone/_deps/ux-helpers/cjs/index.js +1 -1
- package/dist-standalone/_deps/ux-helpers/cjs/pagination.js +1 -1
- package/dist-standalone/_deps/ux-helpers/cjs/progress.js +1 -1
- package/dist-standalone/_deps/ux-helpers/cjs/search.js +1 -1
- package/dist-standalone/_deps/ux-helpers/cjs/types.js +1 -1
- package/dist-standalone/_deps/ux-helpers/errors.js +1 -1
- package/dist-standalone/_deps/ux-helpers/index.js +1 -1
- package/dist-standalone/_deps/ux-helpers/pagination.js +1 -1
- package/dist-standalone/_deps/ux-helpers/progress.js +1 -1
- package/dist-standalone/_deps/ux-helpers/search.js +1 -1
- package/dist-standalone/_deps/xchange/auto-accept.js +1 -1
- package/dist-standalone/_deps/xchange/cjs/auto-accept.js +1 -1
- package/dist-standalone/_deps/xchange/cjs/errors.js +1 -1
- package/dist-standalone/_deps/xchange/cjs/index.js +1 -1
- package/dist-standalone/_deps/xchange/cjs/invite-client.js +1 -1
- package/dist-standalone/_deps/xchange/cjs/lazy-init.js +1 -1
- package/dist-standalone/_deps/xchange/cjs/trust-integration.js +1 -1
- package/dist-standalone/_deps/xchange/cjs/xchange.js +1 -1
- package/dist-standalone/_deps/xchange/errors.js +1 -1
- package/dist-standalone/_deps/xchange/index.js +1 -1
- package/dist-standalone/_deps/xchange/invite-client.js +1 -1
- package/dist-standalone/_deps/xchange/lazy-init.js +1 -1
- package/dist-standalone/_deps/xchange/trust-integration.js +1 -1
- package/dist-standalone/_deps/xchange/xchange.js +1 -1
- package/dist-standalone/_deps/xregistry/cjs/discovery.js +1 -1
- package/dist-standalone/_deps/xregistry/cjs/errors.js +1 -1
- package/dist-standalone/_deps/xregistry/cjs/index.js +1 -1
- package/dist-standalone/_deps/xregistry/cjs/registry.js +1 -1
- package/dist-standalone/_deps/xregistry/cjs/schema.js +1 -1
- package/dist-standalone/_deps/xregistry/cjs/types.js +1 -1
- package/dist-standalone/_deps/xregistry/discovery.js +1 -1
- package/dist-standalone/_deps/xregistry/errors.js +1 -1
- package/dist-standalone/_deps/xregistry/index.js +1 -1
- package/dist-standalone/_deps/xregistry/registry.js +1 -1
- package/dist-standalone/_deps/xregistry/schema.js +1 -1
- package/dist-standalone/_deps/xregistry/types.js +1 -1
- package/dist-standalone/agent-call.js +659 -1
- package/dist-standalone/agent-sdk.js +328 -1
- package/dist-standalone/agent.js +1800 -1
- package/dist-standalone/approval.js +193 -1
- package/dist-standalone/async-iterators.js +382 -1
- package/dist-standalone/auth.js +219 -1
- package/dist-standalone/auto-accept.js +229 -1
- package/dist-standalone/backup-config.js +201 -1
- package/dist-standalone/backup.js +326 -1
- package/dist-standalone/batch-operations.js +388 -1
- package/dist-standalone/cancellation.js +477 -1
- package/dist-standalone/checkpoint.js +186 -1
- package/dist-standalone/circuit-breaker.js +468 -1
- package/dist-standalone/cjs/agent-call.js +701 -1
- package/dist-standalone/cjs/agent-sdk.js +332 -1
- package/dist-standalone/cjs/agent.js +1837 -1
- package/dist-standalone/cjs/approval.js +199 -1
- package/dist-standalone/cjs/async-iterators.js +392 -1
- package/dist-standalone/cjs/auth.js +225 -1
- package/dist-standalone/cjs/auto-accept.js +233 -1
- package/dist-standalone/cjs/backup-config.js +207 -1
- package/dist-standalone/cjs/backup.js +330 -1
- package/dist-standalone/cjs/batch-operations.js +397 -1
- package/dist-standalone/cjs/cancellation.js +490 -1
- package/dist-standalone/cjs/checkpoint.js +193 -1
- package/dist-standalone/cjs/circuit-breaker.js +476 -1
- package/dist-standalone/cjs/cli/init.js +492 -1
- package/dist-standalone/cjs/config-validation.js +522 -1
- package/dist-standalone/cjs/connect.js +312 -1
- package/dist-standalone/cjs/connection-pool.js +506 -1
- package/dist-standalone/cjs/correlation-id.js +339 -1
- package/dist-standalone/cjs/crypto-utils.js +176 -1
- package/dist-standalone/cjs/debug-mode.js +534 -1
- package/dist-standalone/cjs/did-document.js +101 -1
- package/dist-standalone/cjs/did-privateme.js +130 -1
- package/dist-standalone/cjs/did-web.js +201 -1
- package/dist-standalone/cjs/discovery.js +462 -1
- package/dist-standalone/cjs/dual-mode.js +251 -1
- package/dist-standalone/cjs/email-templates.js +313 -1
- package/dist-standalone/cjs/email-transport.js +239 -1
- package/dist-standalone/cjs/envelope.js +538 -1
- package/dist-standalone/cjs/errors.js +913 -1
- package/dist-standalone/cjs/event-emitter.js +461 -1
- package/dist-standalone/cjs/gateway-state.js +55 -1
- package/dist-standalone/cjs/gateway-transport.js +120 -1
- package/dist-standalone/cjs/graceful-degradation.js +403 -1
- package/dist-standalone/cjs/guardrails.js +223 -1
- package/dist-standalone/cjs/health-check.js +336 -1
- package/dist-standalone/cjs/http-compat.js +272 -1
- package/dist-standalone/cjs/http-status-map.js +571 -1
- package/dist-standalone/cjs/identity.js +645 -1
- package/dist-standalone/cjs/index.js +406 -1
- package/dist-standalone/cjs/invitation.js +421 -1
- package/dist-standalone/cjs/invite.js +328 -1
- package/dist-standalone/cjs/key-agreement.js +335 -1
- package/dist-standalone/cjs/lazy-init.js +300 -1
- package/dist-standalone/cjs/logger.js +291 -1
- package/dist-standalone/cjs/mdns-discovery.js +202 -1
- package/dist-standalone/cjs/nonce-store.js +80 -1
- package/dist-standalone/cjs/pairing-manager.js +223 -1
- package/dist-standalone/cjs/plugin-system.js +264 -1
- package/dist-standalone/cjs/plugins/logging.js +168 -1
- package/dist-standalone/cjs/plugins/metrics.js +181 -1
- package/dist-standalone/cjs/plugins/validation.js +302 -1
- package/dist-standalone/cjs/policy.js +320 -1
- package/dist-standalone/cjs/progress-callbacks.js +583 -1
- package/dist-standalone/cjs/redis-nonce-store.js +76 -1
- package/dist-standalone/cjs/registry-middleware.js +50 -1
- package/dist-standalone/cjs/retry-strategies.js +544 -1
- package/dist-standalone/cjs/retry-transport.js +102 -1
- package/dist-standalone/cjs/runtime/browser.js +533 -1
- package/dist-standalone/cjs/runtime/edge.js +526 -1
- package/dist-standalone/cjs/runtime/react-native.js +394 -1
- package/dist-standalone/cjs/security-policy.js +245 -1
- package/dist-standalone/cjs/serialization.js +1040 -1
- package/dist-standalone/cjs/split-channel.js +225 -1
- package/dist-standalone/cjs/subscription-proof.js +230 -1
- package/dist-standalone/cjs/succession.js +148 -1
- package/dist-standalone/cjs/timeouts.js +412 -1
- package/dist-standalone/cjs/trace-context.js +424 -1
- package/dist-standalone/cjs/trace-spans.js +495 -1
- package/dist-standalone/cjs/transport.js +63 -1
- package/dist-standalone/cjs/trust-registry.js +991 -1
- package/dist-standalone/cjs/types/error-response.js +56 -1
- package/dist-standalone/cjs/vault-auth.js +178 -1
- package/dist-standalone/cjs/vault-store-loader.js +194 -1
- package/dist-standalone/cjs/verify.js +25 -1
- package/dist-standalone/cjs/version-info.js +543 -1
- package/dist-standalone/cjs/xfetch.js +340 -1
- package/dist-standalone/cli/init.js +455 -1
- package/dist-standalone/cli/setup.js +514 -1
- package/dist-standalone/cli/types.js +27 -1
- package/dist-standalone/cli/xbind.js +148 -1
- package/dist-standalone/config-validation.js +513 -1
- package/dist-standalone/connect.js +274 -1
- package/dist-standalone/connection-pool.js +500 -1
- package/dist-standalone/correlation-id.js +326 -1
- package/dist-standalone/crypto-utils.js +157 -1
- package/dist-standalone/debug-mode.js +510 -1
- package/dist-standalone/did-document.js +96 -1
- package/dist-standalone/did-privateme.js +121 -1
- package/dist-standalone/did-web.js +196 -1
- package/dist-standalone/discovery.js +458 -1
- package/dist-standalone/dual-mode.js +247 -1
- package/dist-standalone/email-templates.js +309 -1
- package/dist-standalone/email-transport.js +232 -1
- package/dist-standalone/envelope.js +525 -1
- package/dist-standalone/errors.js +896 -1
- package/dist-standalone/event-emitter.js +456 -1
- package/dist-standalone/gateway-state.js +51 -1
- package/dist-standalone/gateway-transport.js +116 -1
- package/dist-standalone/graceful-degradation.js +396 -1
- package/dist-standalone/guardrails.js +216 -1
- package/dist-standalone/health-check.js +332 -1
- package/dist-standalone/http-compat.js +267 -1
- package/dist-standalone/http-status-map.js +561 -1
- package/dist-standalone/identity.js +619 -1
- package/dist-standalone/index.js +78 -1
- package/dist-standalone/invitation.js +415 -1
- package/dist-standalone/invite.js +324 -1
- package/dist-standalone/key-agreement.js +325 -1
- package/dist-standalone/lazy-init.js +295 -1
- package/dist-standalone/logger.js +285 -1
- package/dist-standalone/mdns-discovery.js +195 -1
- package/dist-standalone/nonce-store.js +76 -1
- package/dist-standalone/pairing-manager.js +219 -1
- package/dist-standalone/plugin-system.js +257 -1
- package/dist-standalone/plugins/logging.js +163 -1
- package/dist-standalone/plugins/metrics.js +176 -1
- package/dist-standalone/plugins/validation.js +297 -1
- package/dist-standalone/policy.js +315 -1
- package/dist-standalone/progress-callbacks.js +576 -1
- package/dist-standalone/redis-nonce-store.js +72 -1
- package/dist-standalone/registry-middleware.js +47 -1
- package/dist-standalone/retry-strategies.js +534 -1
- package/dist-standalone/retry-transport.js +98 -1
- package/dist-standalone/runtime/browser.js +516 -1
- package/dist-standalone/runtime/edge.js +511 -1
- package/dist-standalone/runtime/react-native.js +383 -1
- package/dist-standalone/security-policy.js +239 -1
- package/dist-standalone/serialization.js +1031 -1
- package/dist-standalone/split-channel.js +219 -1
- package/dist-standalone/subscription-proof.js +224 -1
- package/dist-standalone/succession.js +142 -1
- package/dist-standalone/timeouts.js +398 -1
- package/dist-standalone/trace-context.js +414 -1
- package/dist-standalone/trace-spans.js +488 -1
- package/dist-standalone/transport.js +59 -1
- package/dist-standalone/trust-registry.js +950 -1
- package/dist-standalone/types/error-response.js +52 -1
- package/dist-standalone/vault-auth.js +174 -1
- package/dist-standalone/vault-store-loader.js +187 -1
- package/dist-standalone/verify.js +16 -1
- package/dist-standalone/version-info.js +530 -1
- package/dist-standalone/xfetch.js +335 -1
- package/package.json +4 -13
- package/share1.dat +0 -0
- package/dist-standalone/_deps/mldsa-wasm/LICENSE +0 -24
- package/dist-standalone/_deps/mldsa-wasm/package.json +0 -46
- package/dist-standalone/_deps/shared/cjs/package.json +0 -1
- package/dist-standalone/_deps/ux-helpers/cjs/package.json +0 -1
- package/dist-standalone/_deps/xchange/cjs/package.json +0 -1
- package/dist-standalone/_deps/xregistry/cjs/package.json +0 -1
- package/dist-standalone/cjs/package.json +0 -3
- package/dist-standalone/package.json +0 -10
|
@@ -1 +1,339 @@
|
|
|
1
|
-
"use strict";
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* @module correlation-id
|
|
4
|
+
* Client-side correlation ID utilities for request tracking
|
|
5
|
+
*
|
|
6
|
+
* Correlation IDs enable distributed tracing across xBind agent operations,
|
|
7
|
+
* making it easier to debug issues, track requests across microservices,
|
|
8
|
+
* and correlate logs between client and server.
|
|
9
|
+
*
|
|
10
|
+
* Format: `req_{timestamp}_{random}`
|
|
11
|
+
* Example: `req_1716234567890_a3f5c9d2`
|
|
12
|
+
*
|
|
13
|
+
* Usage:
|
|
14
|
+
* ```typescript
|
|
15
|
+
* import { generateCorrelationId, attachCorrelationId } from '@private.me/xbind';
|
|
16
|
+
*
|
|
17
|
+
* // Generate a new correlation ID
|
|
18
|
+
* const id = generateCorrelationId();
|
|
19
|
+
*
|
|
20
|
+
* // Attach to request headers
|
|
21
|
+
* const headers = attachCorrelationId(new Headers(), id);
|
|
22
|
+
*
|
|
23
|
+
* // Validate format
|
|
24
|
+
* if (validateCorrelationId(id)) {
|
|
25
|
+
* console.log('Valid correlation ID');
|
|
26
|
+
* }
|
|
27
|
+
* ```
|
|
28
|
+
*/
|
|
29
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
30
|
+
exports.CORRELATION_ID_ALIASES = exports.CORRELATION_ID_HEADER = void 0;
|
|
31
|
+
exports.generateCorrelationId = generateCorrelationId;
|
|
32
|
+
exports.validateCorrelationId = validateCorrelationId;
|
|
33
|
+
exports.parseCorrelationId = parseCorrelationId;
|
|
34
|
+
exports.attachCorrelationId = attachCorrelationId;
|
|
35
|
+
exports.extractCorrelationId = extractCorrelationId;
|
|
36
|
+
exports.getOrCreateCorrelationId = getOrCreateCorrelationId;
|
|
37
|
+
exports.createCorrelationIdFromTimestamp = createCorrelationIdFromTimestamp;
|
|
38
|
+
exports.getCorrelationIdAge = getCorrelationIdAge;
|
|
39
|
+
exports.isCorrelationIdExpired = isCorrelationIdExpired;
|
|
40
|
+
exports.correlationIdMiddleware = correlationIdMiddleware;
|
|
41
|
+
/**
|
|
42
|
+
* Standard header name for correlation ID
|
|
43
|
+
*/
|
|
44
|
+
exports.CORRELATION_ID_HEADER = 'X-Correlation-ID';
|
|
45
|
+
/**
|
|
46
|
+
* Alternative header names for compatibility
|
|
47
|
+
*/
|
|
48
|
+
exports.CORRELATION_ID_ALIASES = [
|
|
49
|
+
'X-Request-ID',
|
|
50
|
+
'X-Trace-ID',
|
|
51
|
+
'X-Transaction-ID',
|
|
52
|
+
];
|
|
53
|
+
/**
|
|
54
|
+
* Regular expression for validating correlation ID format
|
|
55
|
+
*/
|
|
56
|
+
const CORRELATION_ID_PATTERN = /^req_\d{13}_[a-f0-9]{8}$/;
|
|
57
|
+
/**
|
|
58
|
+
* Generate a new correlation ID
|
|
59
|
+
*
|
|
60
|
+
* Format: `req_{timestamp}_{random}`
|
|
61
|
+
* - `req`: Static prefix for identification
|
|
62
|
+
* - `timestamp`: Unix timestamp in milliseconds (13 digits)
|
|
63
|
+
* - `random`: 8-character hex string for uniqueness
|
|
64
|
+
*
|
|
65
|
+
* @returns New correlation ID string
|
|
66
|
+
*
|
|
67
|
+
* @example
|
|
68
|
+
* ```typescript
|
|
69
|
+
* const id = generateCorrelationId();
|
|
70
|
+
* // => "req_1716234567890_a3f5c9d2"
|
|
71
|
+
* ```
|
|
72
|
+
*/
|
|
73
|
+
function generateCorrelationId() {
|
|
74
|
+
const timestamp = Date.now();
|
|
75
|
+
const random = generateRandomHex(8);
|
|
76
|
+
return `req_${timestamp}_${random}`;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Validate correlation ID format
|
|
80
|
+
*
|
|
81
|
+
* Checks if the provided string matches the expected correlation ID format.
|
|
82
|
+
*
|
|
83
|
+
* @param id - String to validate
|
|
84
|
+
* @returns True if valid, false otherwise
|
|
85
|
+
*
|
|
86
|
+
* @example
|
|
87
|
+
* ```typescript
|
|
88
|
+
* validateCorrelationId('req_1716234567890_a3f5c9d2'); // => true
|
|
89
|
+
* validateCorrelationId('invalid'); // => false
|
|
90
|
+
* validateCorrelationId('req_123_abc'); // => false (wrong lengths)
|
|
91
|
+
* ```
|
|
92
|
+
*/
|
|
93
|
+
function validateCorrelationId(id) {
|
|
94
|
+
if (typeof id !== 'string')
|
|
95
|
+
return false;
|
|
96
|
+
return CORRELATION_ID_PATTERN.test(id);
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Parse correlation ID into components
|
|
100
|
+
*
|
|
101
|
+
* Extracts the timestamp and random components from a correlation ID.
|
|
102
|
+
*
|
|
103
|
+
* @param id - Correlation ID to parse
|
|
104
|
+
* @returns Parsed components or null if invalid
|
|
105
|
+
*
|
|
106
|
+
* @example
|
|
107
|
+
* ```typescript
|
|
108
|
+
* const spec = parseCorrelationId('req_1716234567890_a3f5c9d2');
|
|
109
|
+
* // => { prefix: 'req', timestamp: 1716234567890, random: 'a3f5c9d2' }
|
|
110
|
+
* ```
|
|
111
|
+
*/
|
|
112
|
+
function parseCorrelationId(id) {
|
|
113
|
+
if (!validateCorrelationId(id))
|
|
114
|
+
return null;
|
|
115
|
+
const parts = id.split('_');
|
|
116
|
+
return {
|
|
117
|
+
prefix: parts[0] ?? 'req',
|
|
118
|
+
timestamp: parseInt(parts[1] ?? '0', 10),
|
|
119
|
+
random: parts[2] ?? '',
|
|
120
|
+
};
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* Attach correlation ID to request headers
|
|
124
|
+
*
|
|
125
|
+
* Adds the correlation ID to the X-Correlation-ID header.
|
|
126
|
+
* If no ID is provided, generates a new one.
|
|
127
|
+
* Compatible with both Headers API and plain objects.
|
|
128
|
+
*
|
|
129
|
+
* @param headers - Headers object or plain object
|
|
130
|
+
* @param id - Correlation ID (generates new if not provided)
|
|
131
|
+
* @returns Updated headers object
|
|
132
|
+
*
|
|
133
|
+
* @example
|
|
134
|
+
* ```typescript
|
|
135
|
+
* // With Headers API
|
|
136
|
+
* const headers = new Headers();
|
|
137
|
+
* attachCorrelationId(headers);
|
|
138
|
+
*
|
|
139
|
+
* // With plain object
|
|
140
|
+
* const headers = { 'Content-Type': 'application/json' };
|
|
141
|
+
* attachCorrelationId(headers, 'req_1716234567890_a3f5c9d2');
|
|
142
|
+
*
|
|
143
|
+
* // With existing correlation ID
|
|
144
|
+
* const id = generateCorrelationId();
|
|
145
|
+
* attachCorrelationId(headers, id);
|
|
146
|
+
* ```
|
|
147
|
+
*/
|
|
148
|
+
function attachCorrelationId(headers, id) {
|
|
149
|
+
const correlationId = id ?? generateCorrelationId();
|
|
150
|
+
if (!validateCorrelationId(correlationId)) {
|
|
151
|
+
throw new Error(`Invalid correlation ID format: ${correlationId}. Expected format: req_{timestamp}_{random}`);
|
|
152
|
+
}
|
|
153
|
+
if (headers instanceof Headers) {
|
|
154
|
+
headers.set(exports.CORRELATION_ID_HEADER, correlationId);
|
|
155
|
+
}
|
|
156
|
+
else {
|
|
157
|
+
headers[exports.CORRELATION_ID_HEADER] = correlationId;
|
|
158
|
+
}
|
|
159
|
+
return headers;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Extract correlation ID from request headers
|
|
163
|
+
*
|
|
164
|
+
* Checks the standard header and common aliases.
|
|
165
|
+
*
|
|
166
|
+
* @param headers - Headers object or plain object
|
|
167
|
+
* @returns Correlation ID if found, undefined otherwise
|
|
168
|
+
*
|
|
169
|
+
* @example
|
|
170
|
+
* ```typescript
|
|
171
|
+
* const headers = new Headers({
|
|
172
|
+
* 'X-Correlation-ID': 'req_1716234567890_a3f5c9d2'
|
|
173
|
+
* });
|
|
174
|
+
* const id = extractCorrelationId(headers);
|
|
175
|
+
* // => 'req_1716234567890_a3f5c9d2'
|
|
176
|
+
* ```
|
|
177
|
+
*/
|
|
178
|
+
function extractCorrelationId(headers) {
|
|
179
|
+
// Check primary header
|
|
180
|
+
const primary = headers instanceof Headers
|
|
181
|
+
? headers.get(exports.CORRELATION_ID_HEADER)
|
|
182
|
+
: headers[exports.CORRELATION_ID_HEADER];
|
|
183
|
+
if (primary && validateCorrelationId(primary)) {
|
|
184
|
+
return primary;
|
|
185
|
+
}
|
|
186
|
+
// Check aliases
|
|
187
|
+
for (const alias of exports.CORRELATION_ID_ALIASES) {
|
|
188
|
+
const value = headers instanceof Headers ? headers.get(alias) : headers[alias];
|
|
189
|
+
if (value && validateCorrelationId(value)) {
|
|
190
|
+
return value;
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
return undefined;
|
|
194
|
+
}
|
|
195
|
+
/**
|
|
196
|
+
* Get or create correlation ID from headers
|
|
197
|
+
*
|
|
198
|
+
* Returns existing correlation ID from headers, or generates a new one if not found.
|
|
199
|
+
* Does NOT modify the input headers.
|
|
200
|
+
*
|
|
201
|
+
* @param headers - Headers to check
|
|
202
|
+
* @returns Existing or new correlation ID
|
|
203
|
+
*
|
|
204
|
+
* @example
|
|
205
|
+
* ```typescript
|
|
206
|
+
* const headers = new Headers();
|
|
207
|
+
* const id = getOrCreateCorrelationId(headers);
|
|
208
|
+
* // => Generates new ID if not found in headers
|
|
209
|
+
* ```
|
|
210
|
+
*/
|
|
211
|
+
function getOrCreateCorrelationId(headers) {
|
|
212
|
+
if (!headers)
|
|
213
|
+
return generateCorrelationId();
|
|
214
|
+
const existing = extractCorrelationId(headers);
|
|
215
|
+
return existing ?? generateCorrelationId();
|
|
216
|
+
}
|
|
217
|
+
/**
|
|
218
|
+
* Create a correlation ID from a timestamp
|
|
219
|
+
*
|
|
220
|
+
* Useful for testing or when you need deterministic IDs.
|
|
221
|
+
*
|
|
222
|
+
* @param timestamp - Unix timestamp in milliseconds
|
|
223
|
+
* @param random - Optional random component (generates if not provided)
|
|
224
|
+
* @returns Correlation ID
|
|
225
|
+
*
|
|
226
|
+
* @example
|
|
227
|
+
* ```typescript
|
|
228
|
+
* const id = createCorrelationIdFromTimestamp(1716234567890);
|
|
229
|
+
* // => 'req_1716234567890_a3f5c9d2'
|
|
230
|
+
*
|
|
231
|
+
* const deterministicId = createCorrelationIdFromTimestamp(1716234567890, 'aaaaaaaa');
|
|
232
|
+
* // => 'req_1716234567890_aaaaaaaa'
|
|
233
|
+
* ```
|
|
234
|
+
*/
|
|
235
|
+
function createCorrelationIdFromTimestamp(timestamp, random) {
|
|
236
|
+
const randomComponent = random ?? generateRandomHex(8);
|
|
237
|
+
if (!/^[a-f0-9]{8}$/.test(randomComponent)) {
|
|
238
|
+
throw new Error(`Invalid random component: ${randomComponent}. Expected 8 hex characters`);
|
|
239
|
+
}
|
|
240
|
+
return `req_${timestamp}_${randomComponent}`;
|
|
241
|
+
}
|
|
242
|
+
/**
|
|
243
|
+
* Calculate age of correlation ID in milliseconds
|
|
244
|
+
*
|
|
245
|
+
* @param id - Correlation ID
|
|
246
|
+
* @returns Age in milliseconds, or null if invalid
|
|
247
|
+
*
|
|
248
|
+
* @example
|
|
249
|
+
* ```typescript
|
|
250
|
+
* const id = generateCorrelationId();
|
|
251
|
+
* setTimeout(() => {
|
|
252
|
+
* const age = getCorrelationIdAge(id);
|
|
253
|
+
* console.log(`Request age: ${age}ms`);
|
|
254
|
+
* }, 1000);
|
|
255
|
+
* ```
|
|
256
|
+
*/
|
|
257
|
+
function getCorrelationIdAge(id) {
|
|
258
|
+
const spec = parseCorrelationId(id);
|
|
259
|
+
if (!spec)
|
|
260
|
+
return null;
|
|
261
|
+
const now = Date.now();
|
|
262
|
+
return now - spec.timestamp;
|
|
263
|
+
}
|
|
264
|
+
/**
|
|
265
|
+
* Check if correlation ID is expired
|
|
266
|
+
*
|
|
267
|
+
* @param id - Correlation ID
|
|
268
|
+
* @param maxAgeMs - Maximum age in milliseconds (default: 5 minutes)
|
|
269
|
+
* @returns True if expired, false otherwise
|
|
270
|
+
*
|
|
271
|
+
* @example
|
|
272
|
+
* ```typescript
|
|
273
|
+
* const id = generateCorrelationId();
|
|
274
|
+
* if (isCorrelationIdExpired(id, 60000)) {
|
|
275
|
+
* console.log('Request older than 1 minute');
|
|
276
|
+
* }
|
|
277
|
+
* ```
|
|
278
|
+
*/
|
|
279
|
+
function isCorrelationIdExpired(id, maxAgeMs = 5 * 60 * 1000) {
|
|
280
|
+
const age = getCorrelationIdAge(id);
|
|
281
|
+
return age !== null && age > maxAgeMs;
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* Generate random hex string
|
|
285
|
+
*
|
|
286
|
+
* Uses Web Crypto API in browser, Node.js crypto in Node.
|
|
287
|
+
* Falls back to Math.random() if neither available (NOT cryptographically secure).
|
|
288
|
+
*
|
|
289
|
+
* @param length - Number of hex characters to generate
|
|
290
|
+
* @returns Random hex string
|
|
291
|
+
*
|
|
292
|
+
* @internal
|
|
293
|
+
*/
|
|
294
|
+
function generateRandomHex(length) {
|
|
295
|
+
const bytes = Math.ceil(length / 2);
|
|
296
|
+
// Try Web Crypto API (browser)
|
|
297
|
+
if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
|
|
298
|
+
const buffer = new Uint8Array(bytes);
|
|
299
|
+
crypto.getRandomValues(buffer);
|
|
300
|
+
return Array.from(buffer)
|
|
301
|
+
.map((b) => b.toString(16).padStart(2, '0'))
|
|
302
|
+
.join('')
|
|
303
|
+
.substring(0, length);
|
|
304
|
+
}
|
|
305
|
+
// Try Node.js crypto
|
|
306
|
+
try {
|
|
307
|
+
const nodeCrypto = require('node:crypto');
|
|
308
|
+
return nodeCrypto.randomBytes(bytes).toString('hex').substring(0, length);
|
|
309
|
+
}
|
|
310
|
+
catch {
|
|
311
|
+
// SECURITY: Never fall back to Math.random() in production (OWASP violation)
|
|
312
|
+
// Correlation IDs must be cryptographically random to prevent enumeration attacks
|
|
313
|
+
throw new Error('Cryptographic random generation unavailable. ' +
|
|
314
|
+
'Install crypto polyfill or use environment with crypto support.');
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
/**
|
|
318
|
+
* Middleware helper for Express/Koa-style frameworks
|
|
319
|
+
*
|
|
320
|
+
* Automatically attaches correlation ID to incoming requests.
|
|
321
|
+
*
|
|
322
|
+
* @example
|
|
323
|
+
* ```typescript
|
|
324
|
+
* import express from 'express';
|
|
325
|
+
* import { correlationIdMiddleware } from '@private.me/xbind';
|
|
326
|
+
*
|
|
327
|
+
* const app = express();
|
|
328
|
+
* app.use(correlationIdMiddleware());
|
|
329
|
+
* ```
|
|
330
|
+
*/
|
|
331
|
+
function correlationIdMiddleware() {
|
|
332
|
+
return (req, res, next) => {
|
|
333
|
+
const id = getOrCreateCorrelationId(req.headers);
|
|
334
|
+
req.correlationId = id;
|
|
335
|
+
res.setHeader(exports.CORRELATION_ID_HEADER, id);
|
|
336
|
+
if (typeof next === 'function')
|
|
337
|
+
next();
|
|
338
|
+
};
|
|
339
|
+
}
|
|
@@ -1 +1,176 @@
|
|
|
1
|
-
"use strict";
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* @module crypto-utils
|
|
4
|
+
* Local crypto utilities (non-IP, safe for npm distribution).
|
|
5
|
+
*
|
|
6
|
+
* These are NOT proprietary - just standard Web Crypto API wrappers.
|
|
7
|
+
* The proprietary XorIDA algorithm is vault-gated via vault-store-loader.ts.
|
|
8
|
+
*/
|
|
9
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
10
|
+
exports.isCryptoLoaded = exports.getCrypto = exports.loadCryptoPackage = void 0;
|
|
11
|
+
exports.toBase64 = toBase64;
|
|
12
|
+
exports.fromBase64 = fromBase64;
|
|
13
|
+
exports.toBase64Url = toBase64Url;
|
|
14
|
+
exports.fromBase64Url = fromBase64Url;
|
|
15
|
+
exports.generateUUID = generateUUID;
|
|
16
|
+
exports.formatShareHeader = formatShareHeader;
|
|
17
|
+
exports.parseShareHeader = parseShareHeader;
|
|
18
|
+
exports.hasShareHeader = hasShareHeader;
|
|
19
|
+
exports.splitXorIDA = splitXorIDA;
|
|
20
|
+
exports.reconstructXorIDA = reconstructXorIDA;
|
|
21
|
+
exports.nextOddPrime = nextOddPrime;
|
|
22
|
+
exports.pkcs7Pad = pkcs7Pad;
|
|
23
|
+
exports.pkcs7Unpad = pkcs7Unpad;
|
|
24
|
+
exports.generateHMAC = generateHMAC;
|
|
25
|
+
exports.verifyHMAC = verifyHMAC;
|
|
26
|
+
/** Convert Uint8Array to Base64 string */
|
|
27
|
+
function toBase64(data) {
|
|
28
|
+
if (typeof Buffer !== 'undefined') {
|
|
29
|
+
// Node.js
|
|
30
|
+
return Buffer.from(data).toString('base64');
|
|
31
|
+
}
|
|
32
|
+
// Browser
|
|
33
|
+
const binary = String.fromCharCode(...data);
|
|
34
|
+
return btoa(binary);
|
|
35
|
+
}
|
|
36
|
+
/** Convert Base64 string to Uint8Array */
|
|
37
|
+
function fromBase64(base64) {
|
|
38
|
+
if (typeof Buffer !== 'undefined') {
|
|
39
|
+
// Node.js
|
|
40
|
+
return new Uint8Array(Buffer.from(base64, 'base64'));
|
|
41
|
+
}
|
|
42
|
+
// Browser
|
|
43
|
+
const binary = atob(base64);
|
|
44
|
+
const bytes = new Uint8Array(binary.length);
|
|
45
|
+
for (let i = 0; i < binary.length; i++) {
|
|
46
|
+
bytes[i] = binary.charCodeAt(i);
|
|
47
|
+
}
|
|
48
|
+
return bytes;
|
|
49
|
+
}
|
|
50
|
+
/** Convert Uint8Array to Base64URL string (URL-safe) */
|
|
51
|
+
function toBase64Url(data) {
|
|
52
|
+
return toBase64(data).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
|
|
53
|
+
}
|
|
54
|
+
/** Convert Base64URL string to Uint8Array */
|
|
55
|
+
function fromBase64Url(base64url) {
|
|
56
|
+
// Add back padding
|
|
57
|
+
let base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
|
|
58
|
+
while (base64.length % 4) {
|
|
59
|
+
base64 += '=';
|
|
60
|
+
}
|
|
61
|
+
return fromBase64(base64);
|
|
62
|
+
}
|
|
63
|
+
/** Generate a UUID v4 (random) */
|
|
64
|
+
function generateUUID() {
|
|
65
|
+
if (typeof crypto !== 'undefined' && crypto.randomUUID) {
|
|
66
|
+
return crypto.randomUUID();
|
|
67
|
+
}
|
|
68
|
+
// Fallback implementation
|
|
69
|
+
const bytes = new Uint8Array(16);
|
|
70
|
+
crypto.getRandomValues(bytes);
|
|
71
|
+
// Set version (4) and variant (RFC 4122)
|
|
72
|
+
bytes[6] = (bytes[6] & 0x0f) | 0x40;
|
|
73
|
+
bytes[8] = (bytes[8] & 0x3f) | 0x80;
|
|
74
|
+
const hex = Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
|
|
75
|
+
return `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Branded share header — IDA5 copyright layer.
|
|
79
|
+
* Wraps XorIDA share output with patent-locked branded string.
|
|
80
|
+
*
|
|
81
|
+
* Format: Xecret (TM) -> PRIVATE .ME (R) -> IDA5 -> Encrypted:// [data] => Generated by Xecret (TM)
|
|
82
|
+
*/
|
|
83
|
+
const START_MARKER = 'Encrypted://';
|
|
84
|
+
const END_MARKER = '=> Generated by Xecret (TM)';
|
|
85
|
+
const BRAND_PREFIX = 'Xecret (TM) -> PRIVATE .ME (R) -> IDA5 -> ';
|
|
86
|
+
/**
|
|
87
|
+
* Wrap share data with branded IDA5 copyright header.
|
|
88
|
+
* @param data - Base64-encoded share data
|
|
89
|
+
* @returns Branded string with copyright header
|
|
90
|
+
*/
|
|
91
|
+
function formatShareHeader(data) {
|
|
92
|
+
return `${BRAND_PREFIX}${START_MARKER} ${data} ${END_MARKER}`;
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Extract share data from branded IDA5 header.
|
|
96
|
+
* @param input - Branded share string or legacy raw data
|
|
97
|
+
* @returns Extracted share data
|
|
98
|
+
*/
|
|
99
|
+
function parseShareHeader(input) {
|
|
100
|
+
const startIdx = input.indexOf(START_MARKER);
|
|
101
|
+
if (startIdx < 0)
|
|
102
|
+
return input.trim();
|
|
103
|
+
const dataStart = startIdx + START_MARKER.length;
|
|
104
|
+
const endIdx = input.indexOf(END_MARKER, dataStart);
|
|
105
|
+
if (endIdx < 0)
|
|
106
|
+
return input.trim();
|
|
107
|
+
return input.substring(dataStart, endIdx).trim();
|
|
108
|
+
}
|
|
109
|
+
/** Check if string has branded IDA5 share header */
|
|
110
|
+
function hasShareHeader(input) {
|
|
111
|
+
return input.includes(START_MARKER) && input.includes(END_MARKER);
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Vault-gated XorIDA functions (loaded dynamically from payment-gated Vault Store).
|
|
115
|
+
* These are re-exported from vault-store-loader for convenience.
|
|
116
|
+
*/
|
|
117
|
+
const vault_store_loader_js_1 = require("./vault-store-loader.js");
|
|
118
|
+
Object.defineProperty(exports, "getCrypto", { enumerable: true, get: function () { return vault_store_loader_js_1.getCrypto; } });
|
|
119
|
+
Object.defineProperty(exports, "loadCryptoPackage", { enumerable: true, get: function () { return vault_store_loader_js_1.loadCryptoPackage; } });
|
|
120
|
+
Object.defineProperty(exports, "isCryptoLoaded", { enumerable: true, get: function () { return vault_store_loader_js_1.isCryptoLoaded; } });
|
|
121
|
+
/** Split data using XorIDA (vault-gated, requires payment) */
|
|
122
|
+
function splitXorIDA(data, totalShares, requiredShares) {
|
|
123
|
+
const crypto = (0, vault_store_loader_js_1.getCrypto)();
|
|
124
|
+
if (!crypto) {
|
|
125
|
+
throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
|
|
126
|
+
}
|
|
127
|
+
return crypto.splitXorIDA(data, totalShares, requiredShares);
|
|
128
|
+
}
|
|
129
|
+
/** Reconstruct data from XorIDA shares (vault-gated, requires payment) */
|
|
130
|
+
function reconstructXorIDA(shares, indices, requiredShares, totalShares) {
|
|
131
|
+
const crypto = (0, vault_store_loader_js_1.getCrypto)();
|
|
132
|
+
if (!crypto) {
|
|
133
|
+
throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
|
|
134
|
+
}
|
|
135
|
+
return crypto.reconstructXorIDA(shares, indices, requiredShares, totalShares);
|
|
136
|
+
}
|
|
137
|
+
/** Get next odd prime >= n (vault-gated utility) */
|
|
138
|
+
function nextOddPrime(n) {
|
|
139
|
+
const crypto = (0, vault_store_loader_js_1.getCrypto)();
|
|
140
|
+
if (!crypto) {
|
|
141
|
+
throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
|
|
142
|
+
}
|
|
143
|
+
return crypto.nextOddPrime(n);
|
|
144
|
+
}
|
|
145
|
+
/** PKCS7 padding (vault-gated utility) */
|
|
146
|
+
function pkcs7Pad(data, blockSize) {
|
|
147
|
+
const crypto = (0, vault_store_loader_js_1.getCrypto)();
|
|
148
|
+
if (!crypto) {
|
|
149
|
+
throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
|
|
150
|
+
}
|
|
151
|
+
return crypto.pkcs7Pad(data, blockSize);
|
|
152
|
+
}
|
|
153
|
+
/** PKCS7 unpadding (vault-gated utility) */
|
|
154
|
+
function pkcs7Unpad(data, blockSize) {
|
|
155
|
+
const crypto = (0, vault_store_loader_js_1.getCrypto)();
|
|
156
|
+
if (!crypto) {
|
|
157
|
+
throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
|
|
158
|
+
}
|
|
159
|
+
return crypto.pkcs7Unpad(data, blockSize);
|
|
160
|
+
}
|
|
161
|
+
/** Generate HMAC-SHA256 (vault-gated utility) */
|
|
162
|
+
async function generateHMAC(data) {
|
|
163
|
+
const crypto = (0, vault_store_loader_js_1.getCrypto)();
|
|
164
|
+
if (!crypto) {
|
|
165
|
+
throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
|
|
166
|
+
}
|
|
167
|
+
return crypto.generateHMAC(data);
|
|
168
|
+
}
|
|
169
|
+
/** Verify HMAC-SHA256 (vault-gated utility) */
|
|
170
|
+
async function verifyHMAC(key, data, expectedHmac) {
|
|
171
|
+
const crypto = (0, vault_store_loader_js_1.getCrypto)();
|
|
172
|
+
if (!crypto) {
|
|
173
|
+
throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
|
|
174
|
+
}
|
|
175
|
+
return crypto.verifyHMAC(key, data, expectedHmac);
|
|
176
|
+
}
|