@bom-pi/core 0.1.4 → 0.2.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.
@@ -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 expectedOrigin?: string;
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>(requestId: string, reason: GatewayFailureReason): GatewayResponse<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, 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
- }
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
- return failure<T>(request.requestId, "app-routing-disabled");
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
- return failure(request.requestId, "handler-failed");
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