@bom-pi/core 0.1.4 → 0.2.1
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/package.json +8 -3
- package/src/cloud-connector.ts +4 -3
- package/src/cloud-wss-transport.ts +388 -33
- package/src/pairing-storage.ts +6 -1
- package/src/relay-boundary.ts +292 -3
- package/src/relay-mux-wire.ts +105 -0
- package/src/relay-remote-channel.ts +482 -0
- package/src/relay-remote-dispatch.ts +227 -0
- package/src/relay-secure-channel.ts +325 -0
- package/src/relay-secure-target.ts +592 -0
- package/src/session-gateway.ts +129 -12
package/src/session-gateway.ts
CHANGED
|
@@ -30,6 +30,7 @@ const SUBJECT_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
|
|
|
30
30
|
const REQUEST_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
|
|
31
31
|
const AUDIENCE = /^[a-z][a-z0-9:_-]{0,63}$/;
|
|
32
32
|
const MAX_TOKEN_LENGTH = 512;
|
|
33
|
+
const MAX_PIN_ORIGIN = 255;
|
|
33
34
|
|
|
34
35
|
export type SessionRole = "owner" | "guest";
|
|
35
36
|
export type GatewayMethod = "GET" | "POST";
|
|
@@ -89,6 +90,7 @@ export type GatewayFailureReason =
|
|
|
89
90
|
| "core-unavailable"
|
|
90
91
|
| "overloaded"
|
|
91
92
|
| "incompatible-version"
|
|
93
|
+
| "transport-unproved"
|
|
92
94
|
// M4 §11 relay denials: machine-readable names sourced from the central boundary's
|
|
93
95
|
// verdicts (relay-boundary.ts). All static and bounded; no context is echoed back.
|
|
94
96
|
| "relay-authorization-failed"
|
|
@@ -96,7 +98,13 @@ export type GatewayFailureReason =
|
|
|
96
98
|
| "relay-denied-approval-path"
|
|
97
99
|
| "relay-denied-credential-read"
|
|
98
100
|
| "relay-denied-local-approval"
|
|
99
|
-
| "relay-denied-extension-surface"
|
|
101
|
+
| "relay-denied-extension-surface"
|
|
102
|
+
// A domain handler's own bounded 4xx refusal (a named operation's legacy route text,
|
|
103
|
+
// status preserved): added 2026-11-08 by owner-directed remediation so domain refusals
|
|
104
|
+
// stop collapsing into malformed-envelope — an envelope SHAPE error stays
|
|
105
|
+
// malformed-envelope; a domain refusal is this reason, carrying the route's bounded
|
|
106
|
+
// message in `data.error` (never an exception object or stack).
|
|
107
|
+
| "domain-refused";
|
|
100
108
|
|
|
101
109
|
export interface GatewayRequest {
|
|
102
110
|
v: 1;
|
|
@@ -161,23 +169,42 @@ const STATUS_BY_REASON: Record<GatewayFailureReason, number> = {
|
|
|
161
169
|
"core-unavailable": 503,
|
|
162
170
|
overloaded: 503,
|
|
163
171
|
"incompatible-version": 400,
|
|
172
|
+
"transport-unproved": 403,
|
|
164
173
|
"relay-authorization-failed": 403,
|
|
165
174
|
"relay-not-admitted": 403,
|
|
166
175
|
"relay-denied-approval-path": 403,
|
|
167
176
|
"relay-denied-credential-read": 403,
|
|
168
177
|
"relay-denied-local-approval": 403,
|
|
169
178
|
"relay-denied-extension-surface": 403,
|
|
179
|
+
"domain-refused": 400,
|
|
170
180
|
};
|
|
171
181
|
|
|
172
182
|
export class GatewayError extends Error {
|
|
173
183
|
readonly reason: GatewayFailureReason;
|
|
174
184
|
readonly status: number;
|
|
185
|
+
/** A bounded, human-readable refusal detail (the legacy route's own message). Only
|
|
186
|
+
* domain-refused sets it; nothing else echoes error text. */
|
|
187
|
+
readonly detail?: string;
|
|
175
188
|
|
|
176
189
|
constructor(reason: GatewayFailureReason, message?: string) {
|
|
177
190
|
super(message ?? reason);
|
|
178
191
|
this.reason = reason;
|
|
179
192
|
this.status = STATUS_BY_REASON[reason];
|
|
180
193
|
}
|
|
194
|
+
|
|
195
|
+
/** One domain refusal: the legacy route's own status and bounded message. The detail is
|
|
196
|
+
* clamped hard (a route's fixed words are short) so nothing long can ever ride along. */
|
|
197
|
+
static domainRefused(status: number, message: string): GatewayError {
|
|
198
|
+
const error = new GatewayError("domain-refused", message);
|
|
199
|
+
|
|
200
|
+
if (Number.isInteger(status) && status >= 400 && status < 500) {
|
|
201
|
+
(error as { status: number }).status = status;
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
(error as { detail?: string }).detail = message.slice(0, 200);
|
|
205
|
+
|
|
206
|
+
return error;
|
|
207
|
+
}
|
|
181
208
|
}
|
|
182
209
|
|
|
183
210
|
const hashHex = (value: string): string =>
|
|
@@ -190,9 +217,21 @@ const hashBuffersEqual = (hexA: string, hexB: string): boolean => {
|
|
|
190
217
|
return a.length === b.length && timingSafeEqual(a, b);
|
|
191
218
|
};
|
|
192
219
|
|
|
220
|
+
/** One named LOCAL owner operation admitted past the default app-data gate: an exact
|
|
221
|
+
* audience/method pair. Entries are fixed at construction, never at request time. */
|
|
222
|
+
export interface LocalAdmission {
|
|
223
|
+
audience: string;
|
|
224
|
+
method: GatewayMethod;
|
|
225
|
+
}
|
|
226
|
+
|
|
193
227
|
export interface SessionAuthorityOptions {
|
|
194
228
|
/** Trusted local clock; a cloud-provided clock is never used (§20). */
|
|
195
229
|
now?: () => number;
|
|
230
|
+
/** Immutable allowlist of named LOCAL owner app-data operations. Empty/absent (the
|
|
231
|
+
* default) keeps every app-data request denied exactly as before; the list can never be
|
|
232
|
+
* changed after construction and never admits a relayed session, a guest, a non-local
|
|
233
|
+
* subject, or an audience outside `app-data:`. */
|
|
234
|
+
localAdmissions?: readonly LocalAdmission[];
|
|
196
235
|
/** Test-only shortenings of the §20 idle bound; longer values are rejected. */
|
|
197
236
|
idleTimeoutMs?: number;
|
|
198
237
|
/** Test-only shortenings of the §20 absolute bound; longer values are rejected. */
|
|
@@ -210,7 +249,8 @@ export class SessionAuthority {
|
|
|
210
249
|
SessionRole,
|
|
211
250
|
{ idleTimeoutMs: number; absoluteLifetimeMs: number }
|
|
212
251
|
>;
|
|
213
|
-
private readonly
|
|
252
|
+
private readonly localAdmissions: readonly LocalAdmission[];
|
|
253
|
+
private expectedOrigin?: string;
|
|
214
254
|
private epoch = 0;
|
|
215
255
|
|
|
216
256
|
constructor(options: SessionAuthorityOptions = {}) {
|
|
@@ -220,6 +260,7 @@ export class SessionAuthority {
|
|
|
220
260
|
|
|
221
261
|
this.nowFn = now;
|
|
222
262
|
this.expectedOrigin = options.expectedOrigin;
|
|
263
|
+
this.localAdmissions = Object.freeze([...(options.localAdmissions ?? [])]);
|
|
223
264
|
this.caps = {
|
|
224
265
|
owner: {
|
|
225
266
|
idleTimeoutMs: idle,
|
|
@@ -340,11 +381,71 @@ export class SessionAuthority {
|
|
|
340
381
|
};
|
|
341
382
|
}
|
|
342
383
|
|
|
384
|
+
/** The one admission hook past the local app-data gate: an exact audience/method pair
|
|
385
|
+
* from the immutable constructor allowlist, only for a local (never relayed) owner
|
|
386
|
+
* session whose subject is the fixed local owner. Everything else stays denied, and a
|
|
387
|
+
* constructed-without-list authority denies every app-data request as before. */
|
|
388
|
+
admitsLocalAppData(session: SessionView, audience: string, method: GatewayMethod): boolean {
|
|
389
|
+
return (
|
|
390
|
+
!session.relayed &&
|
|
391
|
+
session.role === "owner" &&
|
|
392
|
+
session.subjectId === LOCAL_OWNER_SUBJECT &&
|
|
393
|
+
audience.startsWith(APPLICATION_DATA_AUDIENCE_PREFIX) &&
|
|
394
|
+
this.localAdmissions.some(
|
|
395
|
+
(each) => each.audience === audience && each.method === method,
|
|
396
|
+
)
|
|
397
|
+
);
|
|
398
|
+
}
|
|
399
|
+
|
|
343
400
|
/** §20: logout invalidates the session immediately; unknown handles stay unknown. */
|
|
344
401
|
logout(handle: string): boolean {
|
|
345
402
|
return typeof handle === "string" && this.sessions.delete(hashHex(handle));
|
|
346
403
|
}
|
|
347
404
|
|
|
405
|
+
/** Re-pin the exact browser origin this authority expects — the launcher moving its
|
|
406
|
+
* browser to a tunnel URL, or back to the loopback bind. The re-pin burns every live
|
|
407
|
+
* session and bumps the epoch, which moves the bootstrap generation, so any armed
|
|
408
|
+
* capability minted for the old origin dies with it. Re-pinning to the origin already
|
|
409
|
+
* pinned is a no-op (no churn, no burn). `undefined` removes the pin for a bind whose
|
|
410
|
+
* policy keeps the gateway off; sessions still burn. The immutable local-admission list
|
|
411
|
+
* is never touched by a re-pin. */
|
|
412
|
+
rePinOrigin(origin: string | undefined): void {
|
|
413
|
+
let next: string | undefined;
|
|
414
|
+
|
|
415
|
+
if (origin !== undefined) {
|
|
416
|
+
if (origin.length === 0 || origin.length > MAX_PIN_ORIGIN) {
|
|
417
|
+
throw new GatewayError("malformed-envelope", "Invalid origin pin");
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
try {
|
|
421
|
+
const url = new URL(origin);
|
|
422
|
+
|
|
423
|
+
if (
|
|
424
|
+
(url.protocol !== "http:" && url.protocol !== "https:") ||
|
|
425
|
+
url.origin !== origin
|
|
426
|
+
) {
|
|
427
|
+
throw new GatewayError("malformed-envelope", "Invalid origin pin");
|
|
428
|
+
}
|
|
429
|
+
} catch (error) {
|
|
430
|
+
if (error instanceof GatewayError) {
|
|
431
|
+
throw error;
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
throw new GatewayError("malformed-envelope", "Invalid origin pin");
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
next = origin;
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
if (next === this.expectedOrigin) {
|
|
441
|
+
return;
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
this.expectedOrigin = next;
|
|
445
|
+
this.sessions.clear();
|
|
446
|
+
this.epoch += 1;
|
|
447
|
+
}
|
|
448
|
+
|
|
348
449
|
/** §20: a role change invalidates every live session of that subject; re-auth is forced. */
|
|
349
450
|
revokeSubject(subjectId: string): number {
|
|
350
451
|
let removed = 0;
|
|
@@ -533,12 +634,17 @@ export function parseGatewayRequest(input: unknown): GatewayRequest {
|
|
|
533
634
|
};
|
|
534
635
|
}
|
|
535
636
|
|
|
536
|
-
const failure = <T>(
|
|
637
|
+
const failure = <T>(
|
|
638
|
+
requestId: string,
|
|
639
|
+
reason: GatewayFailureReason,
|
|
640
|
+
error?: GatewayError,
|
|
641
|
+
): GatewayResponse<T> => ({
|
|
537
642
|
v: 1,
|
|
538
643
|
requestId,
|
|
539
644
|
ok: false,
|
|
540
|
-
status: STATUS_BY_REASON[reason],
|
|
645
|
+
status: error instanceof GatewayError ? error.status : STATUS_BY_REASON[reason],
|
|
541
646
|
reason,
|
|
647
|
+
...(error?.detail === undefined ? {} : { data: { error: error.detail } as T }),
|
|
542
648
|
});
|
|
543
649
|
|
|
544
650
|
/** Relay failures carry the named, bounded denial so callers (and tests) can assert exactly
|
|
@@ -648,13 +754,17 @@ export async function processRequest<T>(
|
|
|
648
754
|
|
|
649
755
|
// Admitted: the handler runs below, receiving the relayed session view.
|
|
650
756
|
} else if (request.audience.startsWith(APPLICATION_DATA_AUDIENCE_PREFIX)) {
|
|
651
|
-
// Total access gate for LOCAL sessions
|
|
652
|
-
//
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
757
|
+
// Total access gate for LOCAL sessions: denied unless the authority's immutable
|
|
758
|
+
// allowlist admits exactly this named local-owner operation. A guest is always
|
|
759
|
+
// role-forbidden; without the list the gate is byte-identical to the pre-M4
|
|
760
|
+
// candidate (the local owner gets app-routing-disabled).
|
|
761
|
+
if (!authority.admitsLocalAppData(session, request.audience, request.method)) {
|
|
762
|
+
if (session.role === "guest") {
|
|
763
|
+
return failure<T>(request.requestId, "role-forbidden");
|
|
764
|
+
}
|
|
656
765
|
|
|
657
|
-
|
|
766
|
+
return failure<T>(request.requestId, "app-routing-disabled");
|
|
767
|
+
}
|
|
658
768
|
}
|
|
659
769
|
|
|
660
770
|
if (session.role === "guest") {
|
|
@@ -680,8 +790,15 @@ export async function processRequest<T>(
|
|
|
680
790
|
const data = await handler(session, request);
|
|
681
791
|
|
|
682
792
|
return { v: 1, requestId: request.requestId, ok: true, status: 200, data };
|
|
683
|
-
} catch {
|
|
684
|
-
|
|
793
|
+
} catch (error) {
|
|
794
|
+
// A typed gateway error carries its own bounded reason and status (a handler can
|
|
795
|
+
// reject a bad operation payload with a 4xx); anything else stays handler-failed.
|
|
796
|
+
// Neither path echoes the error text.
|
|
797
|
+
return failure<T>(
|
|
798
|
+
request.requestId,
|
|
799
|
+
error instanceof GatewayError ? error.reason : "handler-failed",
|
|
800
|
+
error instanceof GatewayError ? error : undefined,
|
|
801
|
+
);
|
|
685
802
|
}
|
|
686
803
|
}
|
|
687
804
|
|