@bom-pi/core 0.1.2 → 0.1.4
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 +20 -19
- package/src/cloud-connector.ts +190 -5
- package/src/cloud-wss-transport.ts +309 -4
- package/src/device-ceremony.ts +232 -8
- package/src/pairing-storage.ts +233 -21
- package/src/relay-boundary.ts +499 -0
- package/src/secure-transport.ts +116 -11
- package/src/session-gateway.ts +151 -13
package/src/session-gateway.ts
CHANGED
|
@@ -3,11 +3,15 @@
|
|
|
3
3
|
* web forwards only the handle, a request ID and bounded origin/CSRF context, and can never
|
|
4
4
|
* mint a local-user assertion or label a request `owner`. Handles are hashed at rest and held
|
|
5
5
|
* only in memory: a core restart revokes every session until secure persistence is separately
|
|
6
|
-
* tested (§19). No
|
|
7
|
-
*
|
|
8
|
-
*
|
|
6
|
+
* tested (§19). No owner-token persistence, no plaintext fallback and no session-only pair
|
|
7
|
+
* decisions are possible through this module. Application-data audiences stay hard-disabled
|
|
8
|
+
* for LOCAL sessions (byte-identical to the pre-M4 candidate); a RELAYED owner-role principal
|
|
9
|
+
* (§5: a distinct remote principal, never a token sign-in and never a guest downgrade) reaches
|
|
10
|
+
* only the v1 surface admitted by the injected central §11 boundary, with every denial named
|
|
11
|
+
* and approvals staying A-local (§13). */
|
|
9
12
|
|
|
10
13
|
import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
|
|
14
|
+
import type { RelayRequestVerdict } from "./relay-boundary.ts";
|
|
11
15
|
|
|
12
16
|
/** §20 proposed v1 session profile: owner idle timeout 15 minutes, absolute lifetime 8 hours.
|
|
13
17
|
* Test overrides may only shorten these bounds, never extend them. */
|
|
@@ -36,6 +40,10 @@ export interface SessionView {
|
|
|
36
40
|
subjectId: string;
|
|
37
41
|
createdAt: number;
|
|
38
42
|
expiresAt: number;
|
|
43
|
+
/** §5/§11: true ONLY for a relayed remote principal's owner-equivalent session — a
|
|
44
|
+
* distinct principal that never touches local audiences and is boundary-checked per
|
|
45
|
+
* request. Local owner and guest sessions are always false. */
|
|
46
|
+
relayed: boolean;
|
|
39
47
|
}
|
|
40
48
|
|
|
41
49
|
export interface IssuedCookie {
|
|
@@ -59,6 +67,7 @@ export interface IssuedSession {
|
|
|
59
67
|
interface SessionRecord {
|
|
60
68
|
role: SessionRole;
|
|
61
69
|
subjectId: string;
|
|
70
|
+
relayed: boolean;
|
|
62
71
|
handleHash: string;
|
|
63
72
|
csrfTokenHash: string;
|
|
64
73
|
createdAt: number;
|
|
@@ -79,7 +88,15 @@ export type GatewayFailureReason =
|
|
|
79
88
|
| "handler-failed"
|
|
80
89
|
| "core-unavailable"
|
|
81
90
|
| "overloaded"
|
|
82
|
-
| "incompatible-version"
|
|
91
|
+
| "incompatible-version"
|
|
92
|
+
// M4 §11 relay denials: machine-readable names sourced from the central boundary's
|
|
93
|
+
// verdicts (relay-boundary.ts). All static and bounded; no context is echoed back.
|
|
94
|
+
| "relay-authorization-failed"
|
|
95
|
+
| "relay-not-admitted"
|
|
96
|
+
| "relay-denied-approval-path"
|
|
97
|
+
| "relay-denied-credential-read"
|
|
98
|
+
| "relay-denied-local-approval"
|
|
99
|
+
| "relay-denied-extension-surface";
|
|
83
100
|
|
|
84
101
|
export interface GatewayRequest {
|
|
85
102
|
v: 1;
|
|
@@ -109,6 +126,28 @@ export type DecisionAuthorizer = (input: {
|
|
|
109
126
|
session: SessionView;
|
|
110
127
|
}) => { verified: boolean } | Promise<{ verified: boolean }>;
|
|
111
128
|
|
|
129
|
+
/** The per-request check A's central boundary exposes for one bound relayed session
|
|
130
|
+
* (relay-boundary.ts `RelayChannelAuthority.checkRequest`). */
|
|
131
|
+
export type RelayedRequestCheck = (request: {
|
|
132
|
+
audience: string;
|
|
133
|
+
method: GatewayMethod;
|
|
134
|
+
}) => RelayRequestVerdict | Promise<RelayRequestVerdict>;
|
|
135
|
+
|
|
136
|
+
/** M4 §11 wiring: resolves a RELAYED session to its channel's central-boundary check. The
|
|
137
|
+
* daemon closes this over the `RelayChannelAuthority` it admitted at relay-open. Returning
|
|
138
|
+
* null (or not wiring the resolver at all) denies fail-closed — a relayed session without a
|
|
139
|
+
* boundary must never fall through to any local path. */
|
|
140
|
+
export type RelayedBoundaryResolver = (session: SessionView) => RelayedRequestCheck | null;
|
|
141
|
+
|
|
142
|
+
/** Maps a boundary verdict's denial name to the machine-readable gateway reason. */
|
|
143
|
+
const RELAY_DENIAL_REASONS: Record<string, GatewayFailureReason> = {
|
|
144
|
+
"approval-path": "relay-denied-approval-path",
|
|
145
|
+
"credential-read": "relay-denied-credential-read",
|
|
146
|
+
"local-approval-route": "relay-denied-local-approval",
|
|
147
|
+
"extension-surface": "relay-denied-extension-surface",
|
|
148
|
+
"not-admitted": "relay-not-admitted",
|
|
149
|
+
};
|
|
150
|
+
|
|
112
151
|
const STATUS_BY_REASON: Record<GatewayFailureReason, number> = {
|
|
113
152
|
"malformed-envelope": 400,
|
|
114
153
|
"invalid-session": 401,
|
|
@@ -122,6 +161,12 @@ const STATUS_BY_REASON: Record<GatewayFailureReason, number> = {
|
|
|
122
161
|
"core-unavailable": 503,
|
|
123
162
|
overloaded: 503,
|
|
124
163
|
"incompatible-version": 400,
|
|
164
|
+
"relay-authorization-failed": 403,
|
|
165
|
+
"relay-not-admitted": 403,
|
|
166
|
+
"relay-denied-approval-path": 403,
|
|
167
|
+
"relay-denied-credential-read": 403,
|
|
168
|
+
"relay-denied-local-approval": 403,
|
|
169
|
+
"relay-denied-extension-surface": 403,
|
|
125
170
|
};
|
|
126
171
|
|
|
127
172
|
export class GatewayError extends Error {
|
|
@@ -190,7 +235,7 @@ export class SessionAuthority {
|
|
|
190
235
|
/** §20: owner sessions are issued only by core, after the one-time legacy-token
|
|
191
236
|
* verification of §19's migration exception or an equivalent owner authentication. */
|
|
192
237
|
issueOwner(subjectId = "local-owner"): IssuedSession {
|
|
193
|
-
return this.issue("owner", subjectId);
|
|
238
|
+
return this.issue("owner", subjectId, false);
|
|
194
239
|
}
|
|
195
240
|
|
|
196
241
|
issueGuest(subjectId: string): IssuedSession {
|
|
@@ -198,7 +243,20 @@ export class SessionAuthority {
|
|
|
198
243
|
throw new GatewayError("malformed-envelope", "Invalid guest subject");
|
|
199
244
|
}
|
|
200
245
|
|
|
201
|
-
return this.issue("guest", subjectId);
|
|
246
|
+
return this.issue("guest", subjectId, false);
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** §5/§11: mints the owner-equivalent session for a RELAYED remote principal — a distinct
|
|
250
|
+
* principal bound by its fingerprint, never a sign-in with A's reusable owner token and
|
|
251
|
+
* never a guest/viewer downgrade. The session reaches only the app-data surface admitted
|
|
252
|
+
* by the injected central §11 boundary: no local browser audience and no pair-decision
|
|
253
|
+
* audience is reachable from it, and `revokeSubject` ends it when the relation is lost. */
|
|
254
|
+
issueRelayed(subjectId: string): IssuedSession {
|
|
255
|
+
if (!SUBJECT_ID.test(subjectId)) {
|
|
256
|
+
throw new GatewayError("malformed-envelope", "Invalid relayed subject");
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
return this.issue("owner", subjectId, true);
|
|
202
260
|
}
|
|
203
261
|
|
|
204
262
|
/** §19 migration exception, once per redemption: core verifies the legacy browser
|
|
@@ -275,6 +333,7 @@ export class SessionAuthority {
|
|
|
275
333
|
session: {
|
|
276
334
|
role: record.role,
|
|
277
335
|
subjectId: record.subjectId,
|
|
336
|
+
relayed: record.relayed,
|
|
278
337
|
createdAt: record.createdAt,
|
|
279
338
|
expiresAt: record.expiresAt,
|
|
280
339
|
},
|
|
@@ -328,7 +387,7 @@ export class SessionAuthority {
|
|
|
328
387
|
return { persisted: false, restartInvalidatesAllSessions: true };
|
|
329
388
|
}
|
|
330
389
|
|
|
331
|
-
private issue(role: SessionRole, subjectId: string): IssuedSession {
|
|
390
|
+
private issue(role: SessionRole, subjectId: string, relayed: boolean): IssuedSession {
|
|
332
391
|
if (role === "owner" && !SUBJECT_ID.test(subjectId)) {
|
|
333
392
|
throw new GatewayError("malformed-envelope", "Invalid subject");
|
|
334
393
|
}
|
|
@@ -340,6 +399,7 @@ export class SessionAuthority {
|
|
|
340
399
|
const record: SessionRecord = {
|
|
341
400
|
role,
|
|
342
401
|
subjectId,
|
|
402
|
+
relayed,
|
|
343
403
|
handleHash: hashHex(handle),
|
|
344
404
|
csrfTokenHash: hashHex(csrfToken),
|
|
345
405
|
createdAt: now,
|
|
@@ -365,6 +425,7 @@ export class SessionAuthority {
|
|
|
365
425
|
view: {
|
|
366
426
|
role,
|
|
367
427
|
subjectId,
|
|
428
|
+
relayed,
|
|
368
429
|
createdAt: record.createdAt,
|
|
369
430
|
expiresAt: record.expiresAt,
|
|
370
431
|
},
|
|
@@ -480,15 +541,37 @@ const failure = <T>(requestId: string, reason: GatewayFailureReason): GatewayRes
|
|
|
480
541
|
reason,
|
|
481
542
|
});
|
|
482
543
|
|
|
544
|
+
/** Relay failures carry the named, bounded denial so callers (and tests) can assert exactly
|
|
545
|
+
* which §11 rule fired; the payload is diagnostic only and never contains secrets. */
|
|
546
|
+
const relayFailure = <T>(
|
|
547
|
+
requestId: string,
|
|
548
|
+
reason: GatewayFailureReason,
|
|
549
|
+
denial: string,
|
|
550
|
+
): GatewayResponse<T> => ({
|
|
551
|
+
v: 1,
|
|
552
|
+
requestId,
|
|
553
|
+
ok: false,
|
|
554
|
+
status: STATUS_BY_REASON[reason],
|
|
555
|
+
reason,
|
|
556
|
+
data: { denial } as T,
|
|
557
|
+
});
|
|
558
|
+
|
|
483
559
|
/** §19: core resolves the handle, checks expiry/revocation and current owner/guest session
|
|
484
560
|
* rights, validates audience/method and CSRF policy, then — and only then — runs the
|
|
485
|
-
* operation handler. Application-data audiences
|
|
486
|
-
*
|
|
561
|
+
* operation handler. Application-data audiences stay hard-disabled for LOCAL sessions
|
|
562
|
+
* (byte-identical to the pre-M4 candidate: the local owner gets `app-routing-disabled`, a
|
|
563
|
+
* guest is role-forbidden). A RELAYED owner-role principal (§5/§11) reaches ONLY the v1
|
|
564
|
+
* surface through the injected central boundary: every request is boundary-verified per call,
|
|
565
|
+
* every denial carries its named category, pair decisions stay A-local (§13), and nothing
|
|
566
|
+
* outside the app-data audiences is reachable. */
|
|
487
567
|
export async function processRequest<T>(
|
|
488
568
|
authority: SessionAuthority,
|
|
489
569
|
input: unknown,
|
|
490
570
|
handler: (session: SessionView, request: GatewayRequest) => T | Promise<T>,
|
|
491
|
-
options: {
|
|
571
|
+
options: {
|
|
572
|
+
decisionAuthorizer?: DecisionAuthorizer;
|
|
573
|
+
relayedBoundary?: RelayedBoundaryResolver;
|
|
574
|
+
} = {},
|
|
492
575
|
): Promise<GatewayResponse<T>> {
|
|
493
576
|
let request: GatewayRequest;
|
|
494
577
|
|
|
@@ -514,9 +597,64 @@ export async function processRequest<T>(
|
|
|
514
597
|
|
|
515
598
|
const { session } = outcome;
|
|
516
599
|
|
|
517
|
-
//
|
|
518
|
-
|
|
519
|
-
|
|
600
|
+
// §5/§11: a relayed remote principal never touches local surfaces. The pair-decision
|
|
601
|
+
// audience is the A-local approval route (§13): named denial BEFORE any authorizer runs.
|
|
602
|
+
// Local browser audiences are simply not admitted — no broad owner equivalence. The
|
|
603
|
+
// admitted v1 app-data surface is decided ONLY by the central boundary, per request.
|
|
604
|
+
if (session.relayed) {
|
|
605
|
+
if (request.audience === PAIR_DECISION_AUDIENCE) {
|
|
606
|
+
return relayFailure<T>(
|
|
607
|
+
request.requestId,
|
|
608
|
+
"relay-denied-local-approval",
|
|
609
|
+
"local-approval-route",
|
|
610
|
+
);
|
|
611
|
+
}
|
|
612
|
+
|
|
613
|
+
if (!request.audience.startsWith(APPLICATION_DATA_AUDIENCE_PREFIX)) {
|
|
614
|
+
return relayFailure<T>(request.requestId, "relay-not-admitted", "not-admitted");
|
|
615
|
+
}
|
|
616
|
+
|
|
617
|
+
const check = options.relayedBoundary?.(session) ?? null;
|
|
618
|
+
|
|
619
|
+
if (check === null) {
|
|
620
|
+
return relayFailure<T>(
|
|
621
|
+
request.requestId,
|
|
622
|
+
"relay-authorization-failed",
|
|
623
|
+
"boundary-unavailable",
|
|
624
|
+
);
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
let verdict: RelayRequestVerdict;
|
|
628
|
+
|
|
629
|
+
try {
|
|
630
|
+
verdict = await check({ audience: request.audience, method: request.method });
|
|
631
|
+
} catch {
|
|
632
|
+
// A boundary failure denies; the error text is never echoed (static, bounded).
|
|
633
|
+
return relayFailure<T>(
|
|
634
|
+
request.requestId,
|
|
635
|
+
"relay-authorization-failed",
|
|
636
|
+
"boundary-unavailable",
|
|
637
|
+
);
|
|
638
|
+
}
|
|
639
|
+
|
|
640
|
+
if (verdict.admitted !== true) {
|
|
641
|
+
const reason =
|
|
642
|
+
verdict.stage === "authorization"
|
|
643
|
+
? "relay-authorization-failed"
|
|
644
|
+
: (RELAY_DENIAL_REASONS[verdict.denial] ?? "relay-not-admitted");
|
|
645
|
+
|
|
646
|
+
return relayFailure<T>(request.requestId, reason, verdict.denial);
|
|
647
|
+
}
|
|
648
|
+
|
|
649
|
+
// Admitted: the handler runs below, receiving the relayed session view.
|
|
650
|
+
} else if (request.audience.startsWith(APPLICATION_DATA_AUDIENCE_PREFIX)) {
|
|
651
|
+
// Total access gate for LOCAL sessions, byte-identical in effect to the pre-M4
|
|
652
|
+
// candidate: the local owner gets app-routing-disabled; a guest is role-forbidden.
|
|
653
|
+
if (session.role === "guest") {
|
|
654
|
+
return failure<T>(request.requestId, "role-forbidden");
|
|
655
|
+
}
|
|
656
|
+
|
|
657
|
+
return failure<T>(request.requestId, "app-routing-disabled");
|
|
520
658
|
}
|
|
521
659
|
|
|
522
660
|
if (session.role === "guest") {
|