test(rest): measure what a swallowed execution context reads as at the packages door (#13153)

The packages door swallows a failing execution-context resolution into
`undefined`. The thread carried a wire-level reading of that (401 vs 403)
but not an INTERNAL one, and the three internal readings that response
could reflect are different security postures:

  1. a subject that holds nothing (evaluated, denies),
  2. an evaluation that is skipped,
  3. a fall-through to a default / system subject.

Measured: (1), at both clauses of the gate. `refusePackageRequest` touches
the context through optional chaining only, so `undefined` is the anonymous
subject rather than a branch. On every wire-reachable method the anonymous
floor decides and refuses (401); with that floor isolated, the capability
clause reads the same `undefined` as holding the empty capability set and
refuses again (403). It fails CLOSED — not a permission-adjacent fail-open.

Also measured, and it corrects the reason on record: the wrapper's
`.catch(() => undefined)` is the SECOND net. `computeExecCtx` wraps its
whole body in `try { … } catch { return undefined; }`, so a production
resolve fulfils with `undefined` on a fault instead of rejecting, and the
fault-to-anonymous conversion happens one level below the swallow.

No behaviour change: a new test file, plus a comment block on the wrapper
whose emit is byte-identical under `removeComments` with the instrument
calibrated in both directions.


Claude-Session: https://claude.ai/code/session_01UjujZN219uFzBhSYfMykCd

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-litant

packages/rest/src/package-door-execctx-fault-reading.test.ts

@@ -0,0 +1,399 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#12537, ruling of 2026-08-29 — option B, part 2 (the rider)] What a
+ * SWALLOWED execution-context resolution reads as INSIDE the packages door's
+ * permission decision.
+ *
+ * ## The question this file answers, and the question it does NOT
+ *
+ * The thread already carried a wire-level reading: a resolver that throws
+ * SYNCHRONOUSLY reaches `sendThrownError`, and one that REJECTS is swallowed
+ * and the caller sees the anonymous-deny floor. That is an answer about which
+ * status code comes out. The rider asks something else, and the two are not
+ * the same question: what does an `undefined` execution context MEAN to the
+ * gate — is it
+ *
+ *   (1) a SUBJECT that holds nothing (evaluated, denies),
+ *   (2) an evaluation that is SKIPPED, or
+ *   (3) a fall-through to a DEFAULT / SYSTEM subject?
+ *
+ * ⛔ Those three can produce byte-identical responses. (2) and (3) are
+ * fail-open postures and (1) is not, so "the status code was the same" is not
+ * evidence that the internal reading was the same. Every case below therefore
+ * drives a DISCRIMINATOR — an input on which the three readings disagree —
+ * and every "did not happen" reading is stated next to a same-shaped POSITIVE
+ * CONTROL, because a zero from an instrument that was never shown to produce a
+ * one is a false negative, not a measurement.
+ *
+ * ## Measured answer: (1). The fault is folded onto the ANONYMOUS subject.
+ *
+ * `refusePackageRequest` (`package-routes.ts`) reads the resolved context
+ * through optional chaining only — `ctx?.userId`, `ctx?.isSystem`,
+ * `ctx?.systemPermissions` — so `undefined` is not a branch, it is a subject
+ * whose every field is absent:
+ *
+ *   - `shouldDenyAnonymous({ userId: undefined, isSystem: undefined, ... })`
+ *     returns `true` ⇒ 401 `UNAUTHENTICATED`. The gate is REACHED and it
+ *     DENIES; it is not skipped (section 3) and it does not reach a system
+ *     subject (section 2).
+ *   - When the anonymous floor is not the deciding clause, the capability
+ *     clause evaluates the same `undefined` as a subject holding the EMPTY
+ *     capability set ⇒ 403 `FORBIDDEN` (section 4). `ctx?.isSystem` is
+ *     `undefined`, so the `isSystem` escape hatch is not taken either.
+ *
+ * ⇒ The swallow fails CLOSED at this door. It is NOT a permission-adjacent
+ * fail-open. What it costs is DIAGNOSABILITY, and section 5 measures that
+ * cost exactly: a faulting resolver, an absent resolver, and a genuinely
+ * anonymous caller are ONE answer, indistinguishable on the wire.
+ *
+ * ## ⭐ The swallow at the wrapper is the SECOND net, not the first
+ *
+ * Section 6 measures the production supplier rather than assuming it.
+ * `RestServer.computeExecCtx` wraps its whole body in `try { ... } catch {
+ * return undefined; }`, so the production `resolveExecCtx` RESOLVES WITH
+ * `undefined` on a fault instead of rejecting. The `.catch(() => undefined)`
+ * on the packages-door wrapper `resolvePackageRouteExecutionContext` — and
+ * the second one at `package-routes.ts` — therefore have nothing to catch on
+ * that path. The fault-to-anonymous conversion happens INSIDE
+ * `computeExecCtx`; removing either `.catch` would not by itself surface a
+ * production fault. ⛔ That is measured here, not repaired: un-swallowing is
+ * explicitly NOT ruled on this card.
+ *
+ * ## ⛔ What this file must not become
+ *
+ * Nothing here asserts a status code as an END in itself; every status is
+ * read as the OBSERVABLE of a decision, and the decision is what is pinned.
+ * A future edit that makes the gate read `undefined` as a system or default
+ * subject reds section 2 and section 4 — which is the whole point of writing
+ * the reading down rather than the response.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { ANONYMOUS_DENY_CODE, ANONYMOUS_DENY_STATUS } from '@objectstack/core';
+import type { RouteHandler } from '@objectstack/spec/contracts';
+import { registerPackageRoutes } from './package-routes.js';
+import { RestServer } from './rest-server.js';
+
+const PKGS = '/api/v1/packages';
+
+interface Captured {
+  status: number;
+  body: any;
+}
+
+/** A caller holding every capability these routes gate on. */
+const CLEARS_THE_GATE = async () => ({
+  userId: 'u_pkg',
+  systemPermissions: ['manage_metadata', 'studio.access', 'setup.access'],
+});
+
+function mount(options: Record<string, unknown> = {}): Map<string, RouteHandler> {
+  const routes = new Map<string, RouteHandler>();
+  const server = {
+    get: (p: string, h: RouteHandler) => { routes.set(`GET:${p}`, h); },
+    post: (p: string, h: RouteHandler) => { routes.set(`POST:${p}`, h); },
+    put: (p: string, h: RouteHandler) => { routes.set(`PUT:${p}`, h); },
+    delete: (p: string, h: RouteHandler) => { routes.set(`DELETE:${p}`, h); },
+    patch: () => {},
+    use: () => {},
+    listen: async () => {},
+    close: async () => {},
+  } as any;
+  registerPackageRoutes(server, () => ({ list: async () => [] }) as any, '/api/v1', {
+    resolveExecutionContext: CLEARS_THE_GATE,
+    ...options,
+  } as any);
+  return routes;
+}
+
+async function drive(
+  routes: Map<string, RouteHandler>,
+  method: string,
+  path: string,
+  req: Record<string, any> = {},
+): Promise<Captured> {
+  const handler = routes.get(`${method}:${path}`);
+  if (!handler) throw new Error(`no handler for ${method} ${path}`);
+  const captured: Captured = { status: 0, body: undefined };
+  const res: any = {
+    json(data: any) { captured.body = data; },
+    send() {},
+    status(code: number) { captured.status = code; return res; },
+    header() { return res; },
+  };
+  await handler(
+    { params: {}, query: {}, body: undefined, headers: {}, method, path, ...req } as any,
+    res,
+  );
+  return captured;
+}
+
+/** `GET /packages` under one resolver wiring. `undefined` ⇒ no resolver wired. */
+const listUnder = (resolveExecutionContext: unknown, req: Record<string, any> = {}) =>
+  drive(
+    mount(resolveExecutionContext === undefined ? { resolveExecutionContext: undefined } : { resolveExecutionContext }),
+    'GET',
+    PKGS,
+    req,
+  );
+
+/** The three ways this door can end up holding `undefined`. */
+const REJECTS = async () => { throw new Error('resolver fault'); };
+const RESOLVES_UNDEFINED = async () => undefined;
+
+// ---------------------------------------------------------------------------
+// 1. POSITIVE CONTROLS — this harness can observe an ALLOW, and can observe
+//    each refusal clause separately. Every zero below is read against these.
+// ---------------------------------------------------------------------------
+
+describe('[#12537] controls — the instrument produces a one before any zero is read', () => {
+  it('CONTROL (allow is observable): a fully capable context is served 200', async () => {
+    const captured = await listUnder(CLEARS_THE_GATE);
+    expect(captured.status).toBe(200);
+    expect(captured.body?.success).toBe(true);
+  });
+
+  it('CONTROL (the anonymous clause is observable): a named subject is NOT 401', async () => {
+    const captured = await listUnder(async () => ({ userId: 'u_named', systemPermissions: [] }));
+    expect(captured.status).not.toBe(ANONYMOUS_DENY_STATUS);
+    expect(captured.status).toBe(403);
+    expect(captured.body?.error?.code).toBe('FORBIDDEN');
+  });
+
+  it('CONTROL (the resolver really runs): the door calls it exactly once per request', async () => {
+    const resolver = vi.fn(REJECTS);
+    await listUnder(resolver);
+    expect(resolver.mock.calls.length).toBe(1);
+  });
+
+  it('CONTROL (the rejection really rejects): the injected resolver is a rejecting promise', async () => {
+    await expect(REJECTS()).rejects.toThrow('resolver fault');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. READING (3) FALSIFIED — `undefined` is NOT a default / system subject.
+// ---------------------------------------------------------------------------
+
+describe('[#12537] a swallowed resolution does not fall through to a system subject', () => {
+  it('a rejecting resolver is REFUSED, not served', async () => {
+    const captured = await listUnder(REJECTS);
+    expect(captured.status).toBe(ANONYMOUS_DENY_STATUS);
+    expect(captured.body?.success).toBe(false);
+    expect(captured.body?.error?.code).toBe(ANONYMOUS_DENY_CODE);
+  });
+
+  it('CONTROL: a real system subject IS served — so "refused" above is a decision, not an artefact', async () => {
+    const captured = await listUnder(async () => ({ isSystem: true }));
+    expect(captured.status).toBe(200);
+    expect(captured.body?.success).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. READING (2) FALSIFIED — the gate is not SKIPPED for `undefined`.
+// ---------------------------------------------------------------------------
+
+describe('[#12537] a swallowed resolution does not bypass the gate', () => {
+  it('the service is never reached when the resolver rejects', async () => {
+    const list = vi.fn(async () => []);
+    const routes = new Map<string, RouteHandler>();
+    const server = {
+      get: (p: string, h: RouteHandler) => { routes.set(`GET:${p}`, h); },
+      post: () => {}, put: () => {}, delete: () => {}, patch: () => {},
+      use: () => {}, listen: async () => {}, close: async () => {},
+    } as any;
+    registerPackageRoutes(server, () => ({ list }) as any, '/api/v1', {
+      resolveExecutionContext: REJECTS,
+    } as any);
+    const captured = await drive(routes, 'GET', PKGS);
+    expect(captured.status).toBe(ANONYMOUS_DENY_STATUS);
+    // ⚠️ ZERO. Its control is the next assertion, on the SAME `list` spy shape.
+    expect(list.mock.calls.length).toBe(0);
+  });
+
+  it('CONTROL: the same spy DOES record a call when the gate is cleared', async () => {
+    const list = vi.fn(async () => []);
+    const routes = new Map<string, RouteHandler>();
+    const server = {
+      get: (p: string, h: RouteHandler) => { routes.set(`GET:${p}`, h); },
+      post: () => {}, put: () => {}, delete: () => {}, patch: () => {},
+      use: () => {}, listen: async () => {}, close: async () => {},
+    } as any;
+    registerPackageRoutes(server, () => ({ list }) as any, '/api/v1', {
+      resolveExecutionContext: CLEARS_THE_GATE,
+    } as any);
+    const captured = await drive(routes, 'GET', PKGS);
+    expect(captured.status).toBe(200);
+    expect(list.mock.calls.length).toBe(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. READING (1) CONFIRMED — the CAPABILITY clause evaluates `undefined` as a
+//    subject holding the EMPTY set.
+//
+//    ⚠️ DISCLOSURE, so no reader mistakes this for a wire path: the packages
+//    registrar mounts exactly four routes (POST publish, GET list, GET by id,
+//    DELETE by id) and NO `OPTIONS` route, so a real preflight never reaches
+//    these handlers. `method: 'OPTIONS'` is used here as the one INPUT that
+//    makes the shared `shouldDenyAnonymous` yield without authenticating —
+//    i.e. as an instrument for isolating the capability clause from the
+//    anonymous clause, which otherwise short-circuits ahead of it. That
+//    isolation is the only way to tell "evaluated and holds nothing" apart
+//    from "never evaluated": on a plain GET both readings answer 401.
+// ---------------------------------------------------------------------------
+
+describe('[#12537] the capability clause reads `undefined` as "holds nothing"', () => {
+  it('past the anonymous clause, a swallowed resolution is 403 FORBIDDEN', async () => {
+    const captured = await listUnder(REJECTS, { method: 'OPTIONS' });
+    expect(captured.status).toBe(403);
+    expect(captured.body?.error?.code).toBe('FORBIDDEN');
+    expect(captured.body?.error?.message).toContain('studio.access');
+  });
+
+  it('CONTROL: past the same clause, a CAPABLE context is served 200', async () => {
+    const captured = await listUnder(CLEARS_THE_GATE, { method: 'OPTIONS' });
+    expect(captured.status).toBe(200);
+    expect(captured.body?.success).toBe(true);
+  });
+
+  it('CONTROL: past the same clause, an explicit EMPTY capability set is the same 403', async () => {
+    const captured = await listUnder(
+      async () => ({ userId: 'u_named', systemPermissions: [] }),
+      { method: 'OPTIONS' },
+    );
+    expect(captured.status).toBe(403);
+    expect(captured.body?.error?.code).toBe('FORBIDDEN');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. THE COST — the three origins of `undefined` are ONE answer.
+//    This is the defect the card actually describes: not an over-permission,
+//    a refusal whose stated reason is wrong for two of the three origins.
+// ---------------------------------------------------------------------------
+
+describe('[#12537] a resolver FAULT is indistinguishable from anonymity and from no resolver', () => {
+  it('rejecting resolver, resolver returning undefined, and no resolver agree byte for byte', async () => {
+    const [faulted, anonymous, unwired] = await Promise.all([
+      listUnder(REJECTS),
+      listUnder(RESOLVES_UNDEFINED),
+      listUnder(undefined),
+    ]);
+    expect(faulted.status).toBe(ANONYMOUS_DENY_STATUS);
+    expect(JSON.stringify(faulted)).toBe(JSON.stringify(anonymous));
+    expect(JSON.stringify(faulted)).toBe(JSON.stringify(unwired));
+  });
+
+  it('CONTROL: the same comparison SEPARATES two answers that differ', async () => {
+    const [faulted, capable] = await Promise.all([listUnder(REJECTS), listUnder(CLEARS_THE_GATE)]);
+    expect(JSON.stringify(faulted)).not.toBe(JSON.stringify(capable));
+  });
+
+  it('every state-changing route reads the fault the same way', async () => {
+    const routes = mount({ resolveExecutionContext: REJECTS });
+    const del = await drive(routes, 'DELETE', `${PKGS}/:id`, { params: { id: 'com.acme.crm' } });
+    const pub = await drive(routes, 'POST', `${PKGS}/publish`, {
+      body: { manifest: { id: 'com.acme.crm', version: '1.0.0' } },
+    });
+    expect(del.status).toBe(ANONYMOUS_DENY_STATUS);
+    expect(pub.status).toBe(ANONYMOUS_DENY_STATUS);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. THE PRODUCTION SUPPLIER — the wrapper's `.catch` is the SECOND net.
+// ---------------------------------------------------------------------------
+
+describe('[#12537] the production resolver resolves with `undefined`; it does not reject', () => {
+  const restWith = (authServiceProvider: (environmentId?: string) => Promise<any>) =>
+    new RestServer(
+      { get: () => {}, post: () => {}, put: () => {}, delete: () => {}, patch: () => {}, use: () => {} } as any,
+      {} as any,
+      {} as any,
+      undefined,
+      undefined,
+      undefined,
+      authServiceProvider,
+    );
+
+  /** Fulfilled-or-rejected, as an observable value rather than an assertion. */
+  const settle = async (p: Promise<unknown>): Promise<'fulfilled' | 'rejected'> =>
+    p.then(() => 'fulfilled' as const, () => 'rejected' as const);
+
+  it('CONTROL: the witness distinguishes a rejected promise from a fulfilled one', async () => {
+    expect(await settle(Promise.reject(new Error('control')))).toBe('rejected');
+    expect(await settle(Promise.resolve(1))).toBe('fulfilled');
+  });
+
+  it('a faulting auth-service provider yields a FULFILLED `undefined` from the private resolver', async () => {
+    const rest = restWith(() => { throw new Error('auth service exploded'); });
+    const req = { params: {}, headers: {}, method: 'GET', path: PKGS };
+    // ⭐ The PRIVATE resolver, read BEFORE the wrapper's `.catch` can act —
+    // this is what shows the wrapper is not the thing converting the fault.
+    const inner = (rest as any).resolveExecCtx(undefined, req);
+    expect(await settle(inner)).toBe('fulfilled');
+    expect(await inner).toBeUndefined();
+  });
+
+  it('CONTROL: when the inner resolve DOES reject, the wrapper is what swallows it', async () => {
+    const rest = restWith(async () => undefined);
+    (rest as any).computeExecCtx = async () => { throw new Error('injected inner rejection'); };
+    const req = { params: {}, headers: {}, method: 'GET', path: PKGS };
+    // Same shape as the case above, with the one difference under test — so the
+    // "fulfilled" reading there is a property of `computeExecCtx`, not of the
+    // instrument.
+    expect(await settle((rest as any).resolveExecCtx(undefined, req))).toBe('rejected');
+    expect(await settle(rest.resolvePackageRouteExecutionContext(req))).toBe('fulfilled');
+    expect(await rest.resolvePackageRouteExecutionContext({ ...req })).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 7. ⚠️ A CORRECTION to the reading this card's thread carried.
+//
+//    The thread records "synchronous throw ⇒ 403 PERMISSION_DENIED" beside
+//    "asynchronous rejection ⇒ 401" as if both were facts ABOUT THIS DOOR.
+//    Only the second one is. A synchronous throw does not produce an
+//    `undefined` context at all — it escapes the wrapper (which is NOT
+//    `async`, so there is no promise for either `.catch` to attach to),
+//    lands in the route's own `try`, and is answered by `sendThrownError` →
+//    `resolveThrownHttpError`, which reads the STATUS OFF THE THROWN ERROR.
+//    So the 403 is a property of the error that was injected, not a decision
+//    this gate made: the same seam, thrown a plain `Error`, answers 500.
+//
+//    ⇒ The two limbs are not two readings of one context. One is a refusal
+//    DECIDED by the gate; the other is a status FORWARDED from a producer.
+//    Nothing here re-opens the seam census: a production wrapper still cannot
+//    throw synchronously (`req?.params?.environmentId` is optional-chained and
+//    every downstream call resolves), so this limb remains the declared
+//    test-only injection point.
+// ---------------------------------------------------------------------------
+
+describe('[#12537] a SYNC throw is forwarded from the producer, not decided by the gate', () => {
+  const throwsSync = (error: unknown) => () => { throw error; };
+
+  it('a coded producer error keeps ITS status — the thread\'s 403 is this, not a gate decision', async () => {
+    const captured = await listUnder(
+      throwsSync(Object.assign(new Error('nope'), { code: 'PERMISSION_DENIED', status: 403 })),
+    );
+    expect(captured.status).toBe(403);
+    expect(captured.body?.error?.code).toBe('PERMISSION_DENIED');
+  });
+
+  it('the SAME seam, thrown a plain Error, answers 500 — so the status tracks the error', async () => {
+    const captured = await listUnder(throwsSync(new Error('nope')));
+    expect(captured.status).toBe(500);
+    expect(captured.body?.error?.code).not.toBe('PERMISSION_DENIED');
+  });
+
+  it('and neither of those is the swallowed case: a REJECTION is still the 401 floor', async () => {
+    const captured = await listUnder(
+      async () => { throw Object.assign(new Error('nope'), { code: 'PERMISSION_DENIED', status: 403 }); },
+    );
+    expect(captured.status).toBe(ANONYMOUS_DENY_STATUS);
+    expect(captured.body?.error?.code).toBe(ANONYMOUS_DENY_CODE);
+  });
+});