@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.
@@ -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 application-data routing, no owner-token persistence, no plaintext
7
- * fallback and no session-only pair decisions are possible through this module; those stay
8
- * disabled behind the §§11–12 access gates. */
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 are hard-disabled; pair decisions require
486
- * the independent signed envelope verified by the injected authorizer, never the handle. */
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: { decisionAuthorizer?: DecisionAuthorizer } = {},
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
- // Total access gate: application data routing stays disabled for every role.
518
- if (request.audience.startsWith(APPLICATION_DATA_AUDIENCE_PREFIX)) {
519
- return failure(request.requestId, "app-routing-disabled");
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") {