@oxyhq/core 21.0.0 → 21.0.2

package/src/server/__tests__/serviceTokenAttribution.test.ts

@@ -0,0 +1,396 @@
+/**
+ * Canonical request attribution for service tokens (ADR 0007, issue #972 §2.2).
+ *
+ * Two claims are under test, and they are different claims:
+ *
+ *  1. A VERIFIED service token names the whole attribution tuple locally —
+ *     application, credential, owning account, environment and effective
+ *     scopes — so a verifier with no database can say who is responsible.
+ *  2. A delegated `X-Oxy-User-Id` can never become that responsible party. It
+ *     is visible exactly where delegation is meant to be visible
+ *     (`req.userId`, `getOxyDelegatedUserId`) and nowhere else.
+ *
+ * Everything runs through the REAL `oxy.auth()` middleware with a real HMAC
+ * signature, so the assertions are about the shipped lane rather than a
+ * hand-built request object. The one exception is deliberate and marked: the
+ * tampering cases plant fields on an already-authenticated request to prove the
+ * billing resolver does not read them.
+ */
+
+import crypto from 'node:crypto';
+import { OxyServices } from '../../OxyServices';
+import {
+  getOxyBillingPrincipal,
+  getOxyDelegatedUserId,
+  getOxyRequestAttribution,
+  getRequiredOxyBillingPrincipal,
+  getRequiredOxyUserId,
+} from '../auth';
+import type { Request } from 'express';
+
+const SERVICE_SECRET = 'attribution-suite-secret-not-production';
+const OWNER_ACCOUNT = 'account-owning-the-application';
+const DELEGATED_USER = 'end-user-the-service-acts-for';
+
+interface Claims {
+  [key: string]: unknown;
+}
+
+const b64url = (input: Buffer | string): string =>
+  (typeof input === 'string' ? Buffer.from(input, 'utf8') : input)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+/** Sign an HS256 JWT byte-identically to `POST /auth/service-token`. */
+function signServiceToken(claims: Claims = {}, secret = SERVICE_SECRET): string {
+  const now = Math.floor(Date.now() / 1000);
+  const payload: Claims = {
+    iat: now,
+    exp: now + 3600,
+    type: 'service',
+    aud: 'oxy-api',
+    iss: 'oxy-auth',
+    appId: 'app-1',
+    appName: 'relay',
+    credentialId: 'cred-1',
+    ownerAccountId: OWNER_ACCOUNT,
+    environment: 'production',
+    scopes: ['inference:invoke'],
+    ...claims,
+  };
+  const headerB64 = b64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const payloadB64 = b64url(JSON.stringify(payload));
+  const signature = crypto
+    .createHmac('sha256', secret)
+    .update(`${headerB64}.${payloadB64}`)
+    .digest('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+  return `${headerB64}.${payloadB64}.${signature}`;
+}
+
+interface MockReq {
+  method: string;
+  path: string;
+  headers: Record<string, string>;
+  query: Record<string, string>;
+  userId?: string | null;
+  user?: unknown;
+  serviceApp?: unknown;
+  serviceActingAs?: unknown;
+  accessToken?: string;
+}
+
+interface MockRes {
+  statusCode: number;
+  body: unknown;
+  headersSent: boolean;
+  status(code: number): MockRes;
+  json(body: unknown): MockRes;
+}
+
+const makeReq = (headers: Record<string, string> = {}): MockReq => ({
+  method: 'POST',
+  path: '/v1/responses',
+  headers,
+  query: {},
+});
+
+const makeRes = (): MockRes => ({
+  statusCode: 0,
+  body: undefined,
+  headersSent: false,
+  status(code: number) {
+    this.statusCode = code;
+    return this;
+  },
+  json(body: unknown) {
+    this.body = body;
+    this.headersSent = true;
+    return this;
+  },
+});
+
+/** Run `oxy.auth()` over a request and report what the middleware decided. */
+async function authenticate(
+  oxy: OxyServices,
+  headers: Record<string, string>,
+  options: Parameters<OxyServices['auth']>[0] = { jwtSecret: SERVICE_SECRET },
+): Promise<{ req: MockReq; res: MockRes; nextCalled: boolean }> {
+  const req = makeReq(headers);
+  const res = makeRes();
+  const next = jest.fn();
+  const middleware = oxy.auth(options);
+  await middleware(req as unknown as never, res as unknown as never, next as unknown as never);
+  return { req, res, nextCalled: next.mock.calls.length > 0 };
+}
+
+/** `MockReq` is the structural subset the resolvers read; Express's own shape is irrelevant here. */
+const asRequest = (req: MockReq): Request => req as unknown as Request;
+
+let oxy: OxyServices;
+
+beforeEach(() => {
+  oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+});
+
+describe('a verified service token resolves the whole attribution tuple locally', () => {
+  it('names application, credential, owning account, environment and effective scopes', async () => {
+    const { req, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+    });
+
+    expect(nextCalled).toBe(true);
+    expect(getOxyBillingPrincipal(asRequest(req))).toEqual({
+      accountId: OWNER_ACCOUNT,
+      applicationId: 'app-1',
+      credentialId: 'cred-1',
+      environment: 'production',
+      scopes: ['inference:invoke'],
+    });
+  });
+
+  it('reports the effective scopes verbatim — nothing re-intersects them here', async () => {
+    // The mint already intersected credential ∩ application via the API's
+    // `intersectScopes`. If this side narrowed again it would be a second
+    // authority, and the two could disagree.
+    const token = signServiceToken({ scopes: ['inference:invoke', 'inference:models:read'] });
+    const { req } = await authenticate(oxy, { authorization: `Bearer ${token}` });
+
+    expect(getRequiredOxyBillingPrincipal(asRequest(req)).scopes).toEqual([
+      'inference:invoke',
+      'inference:models:read',
+    ]);
+  });
+
+  it('has no principal at all for an unauthenticated request', () => {
+    expect(getOxyBillingPrincipal(asRequest(makeReq()))).toBeNull();
+    expect(() => getRequiredOxyBillingPrincipal(asRequest(makeReq()))).toThrow(
+      'no verified Oxy service principal',
+    );
+  });
+});
+
+describe('a delegated X-Oxy-User-Id is attribution, never the payer', () => {
+  it('leaves the billing account untouched while the delegated user stays visible', async () => {
+    jest
+      .spyOn(oxy, 'verifyServiceActingAs')
+      .mockResolvedValue({ authorized: true, scopes: ['user:read'] });
+
+    const { req, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+      'x-oxy-user-id': DELEGATED_USER,
+    });
+
+    expect(nextCalled).toBe(true);
+
+    // The assertion that matters: who pays does not move.
+    const principal = getRequiredOxyBillingPrincipal(asRequest(req));
+    expect(principal.accountId).toBe(OWNER_ACCOUNT);
+    expect(principal.accountId).not.toBe(DELEGATED_USER);
+
+    // The POSITIVE CONTROL. Without it, a resolver that simply returned a
+    // constant would pass the line above. The delegated id must be visible
+    // exactly where delegation is supposed to be visible.
+    expect(getOxyDelegatedUserId(asRequest(req))).toBe(DELEGATED_USER);
+    expect(getRequiredOxyUserId(asRequest(req))).toBe(DELEGATED_USER);
+    expect(getOxyRequestAttribution(asRequest(req))).toEqual({
+      accountId: OWNER_ACCOUNT,
+      applicationId: 'app-1',
+      credentialId: 'cred-1',
+      environment: 'production',
+      scopes: ['inference:invoke'],
+      delegatedUserId: DELEGATED_USER,
+    });
+  });
+
+  it('resolves the SAME billing account with and without delegation', async () => {
+    jest
+      .spyOn(oxy, 'verifyServiceActingAs')
+      .mockResolvedValue({ authorized: true, scopes: ['user:read'] });
+
+    const withDelegation = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+      'x-oxy-user-id': DELEGATED_USER,
+    });
+    const withoutDelegation = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+    });
+
+    // Restated as ADR 0007 states it: removing `userId` from a request must not
+    // change what any account is charged.
+    expect(getRequiredOxyBillingPrincipal(asRequest(withDelegation.req))).toEqual(
+      getRequiredOxyBillingPrincipal(asRequest(withoutDelegation.req)),
+    );
+    expect(getOxyDelegatedUserId(asRequest(withoutDelegation.req))).toBeNull();
+    expect(withoutDelegation.req.userId).toBeNull();
+  });
+
+  it('ignores a userId planted on an already-authenticated request', async () => {
+    const { req } = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+    });
+
+    // Deliberate tampering AFTER authentication: this is the shape a downstream
+    // middleware bug takes. `getOxyBillingPrincipal` must read `serviceApp` and
+    // nothing else, so none of these can move the answer.
+    req.userId = DELEGATED_USER;
+    req.user = { id: DELEGATED_USER };
+    req.serviceActingAs = { userId: DELEGATED_USER, scopes: [] };
+
+    expect(getRequiredOxyBillingPrincipal(asRequest(req)).accountId).toBe(OWNER_ACCOUNT);
+    // Control: the planted fields ARE readable through the user-identity
+    // accessor, so the assertion above is about the resolver's inputs and not
+    // about the fields being unset.
+    expect(getRequiredOxyUserId(asRequest(req))).toBe(DELEGATED_USER);
+  });
+
+  it('does not put the delegated user anywhere on the service principal', async () => {
+    jest
+      .spyOn(oxy, 'verifyServiceActingAs')
+      .mockResolvedValue({ authorized: true, scopes: ['user:read'] });
+
+    const { req } = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+      'x-oxy-user-id': DELEGATED_USER,
+    });
+
+    // A field-name-agnostic sweep: no value of `req.serviceApp`, at any depth
+    // this object has, may equal the delegated id. A future field called
+    // `userId`/`subject`/`onBehalfOf` would fail here without anyone having to
+    // remember to extend the list above.
+    expect(JSON.stringify(req.serviceApp)).not.toContain(DELEGATED_USER);
+  });
+});
+
+describe('signature verification is mandatory before any claim is trusted', () => {
+  it('refuses a token signed with a different secret (401, no principal)', async () => {
+    const forged = signServiceToken({}, 'a-secret-the-issuer-never-used');
+    const { req, res, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${forged}`,
+    });
+
+    expect(nextCalled).toBe(false);
+    expect(res.statusCode).toBe(401);
+    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
+    expect(req.serviceApp).toBeUndefined();
+    expect(getOxyBillingPrincipal(asRequest(req))).toBeNull();
+  });
+
+  it('refuses a token whose payload was edited after signing', async () => {
+    // The attack the claim set invites: take a real token and rewrite
+    // `ownerAccountId` to somebody else's account. The signature covers the
+    // payload, so the edit must not survive.
+    const token = signServiceToken();
+    const [headerB64, , signatureB64] = token.split('.');
+    const tamperedPayload = b64url(
+      JSON.stringify({
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        type: 'service',
+        aud: 'oxy-api',
+        iss: 'oxy-auth',
+        appId: 'app-1',
+        appName: 'relay',
+        credentialId: 'cred-1',
+        ownerAccountId: 'somebody-elses-account',
+        environment: 'production',
+        scopes: ['inference:invoke'],
+      }),
+    );
+    const { req, res, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${headerB64}.${tamperedPayload}.${signatureB64}`,
+    });
+
+    expect(nextCalled).toBe(false);
+    expect(res.statusCode).toBe(401);
+    expect(req.serviceApp).toBeUndefined();
+  });
+
+  it('refuses an UNSIGNED token (alg: none, empty signature segment)', async () => {
+    const headerB64 = b64url(JSON.stringify({ alg: 'none', typ: 'JWT' }));
+    const payloadB64 = b64url(
+      JSON.stringify({
+        type: 'service',
+        appId: 'app-1',
+        appName: 'relay',
+        credentialId: 'cred-1',
+        ownerAccountId: OWNER_ACCOUNT,
+        environment: 'production',
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        aud: 'oxy-api',
+        iss: 'oxy-auth',
+      }),
+    );
+    const { req, res, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${headerB64}.${payloadB64}.`,
+    });
+
+    expect(nextCalled).toBe(false);
+    expect(res.statusCode).toBe(401);
+    expect(req.serviceApp).toBeUndefined();
+  });
+
+  it('refuses every service token when no verification secret is configured', async () => {
+    // The secure default: without a secret the middleware CANNOT verify, so it
+    // must not fall back to reading the decoded claims.
+    const { req, res, nextCalled } = await authenticate(
+      oxy,
+      { authorization: `Bearer ${signServiceToken()}` },
+      {},
+    );
+
+    expect(nextCalled).toBe(false);
+    expect(res.statusCode).toBe(403);
+    expect(res.body).toMatchObject({ code: 'SERVICE_TOKEN_NOT_CONFIGURED' });
+    expect(req.serviceApp).toBeUndefined();
+    expect(getOxyBillingPrincipal(asRequest(req))).toBeNull();
+  });
+
+  it('attaches no principal on the OPTIONAL lane either', async () => {
+    // `optional: true` degrades to anonymous rather than 401 — the thing that
+    // must not happen is degrading to an UNVERIFIED principal.
+    const forged = signServiceToken({}, 'wrong-secret');
+    const { req, nextCalled } = await authenticate(
+      oxy,
+      { authorization: `Bearer ${forged}` },
+      { jwtSecret: SERVICE_SECRET, optional: true },
+    );
+
+    expect(nextCalled).toBe(true);
+    expect(req.serviceApp).toBeUndefined();
+    expect(req.userId).toBeNull();
+    expect(getOxyBillingPrincipal(asRequest(req))).toBeNull();
+  });
+});
+
+describe('the owning account is a required claim', () => {
+  it.each([
+    ['absent', undefined],
+    ['empty', ''],
+    ['a number', 42],
+    ['null', null],
+  ])('refuses a signature-valid token whose ownerAccountId is %s', async (_label, value) => {
+    const token = signServiceToken({ ownerAccountId: value });
+    const { req, res, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${token}`,
+    });
+
+    expect(nextCalled).toBe(false);
+    expect(res.statusCode).toBe(401);
+    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
+    expect(getOxyBillingPrincipal(asRequest(req))).toBeNull();
+  });
+
+  it('accepts the same token once the claim is present — the control', async () => {
+    const { res, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+    });
+
+    expect(nextCalled).toBe(true);
+    expect(res.statusCode).toBe(0);
+  });
+});

package/src/server/auth.ts

@@ -19,6 +19,12 @@ export interface OxyServiceAppContext {
   appName: string;
   scopes: string[];
   credentialId: string;
+  /**
+   * The Oxy account that owns `appId` and is financially responsible for it.
+   * Read off the VERIFIED service-token claim set — never a user id, and never
+   * the delegated `X-Oxy-User-Id` (ADR 0007).
+   */
+  ownerAccountId: string;
   environment: OxyServiceEnvironment;
 }
 
@@ -84,6 +90,118 @@ export function isOxyAuthenticated(req: Request): req is OxyAuthenticatedRequest
   return getOxyUserId(req) !== null;
 }
 
+/**
+ * The principal a request is CHARGED to, and the identifiers a receipt needs.
+ *
+ * Every field is read from the verified service-token claim set. It is an
+ * OBJECT, not a string, and that is the point: `getOxyUserId` returns a
+ * `string | null`, so a delegated end-user id cannot be passed anywhere an
+ * `OxyBillingPrincipal` is expected. The confusion ADR 0007 forbids —
+ * attributing spend to the person a service is acting for rather than to the
+ * service's own account — stops being a code-review question and becomes a
+ * compile error.
+ *
+ * `scopes` are the effective scopes minted into the token (credential ∩
+ * application). Nothing re-intersects them here.
+ */
+export interface OxyBillingPrincipal {
+  /** `applications.owner_account_id` — the financially responsible account. */
+  readonly accountId: string;
+  readonly applicationId: string;
+  readonly credentialId: string;
+  readonly environment: OxyServiceEnvironment;
+  readonly scopes: readonly string[];
+}
+
+/**
+ * The full canonical attribution of ADR 0007 for a request: the billing
+ * principal PLUS the optional delegated end user.
+ *
+ * `delegatedUserId` is named for what it is. It answers "on whose behalf" and
+ * is absent for a machine credential acting for itself — its absence is normal,
+ * and nothing may synthesize one. If removing it would change what any account
+ * is charged, the code reading it is wrong.
+ */
+export interface OxyRequestAttribution extends OxyBillingPrincipal {
+  readonly delegatedUserId: string | null;
+}
+
+/**
+ * The billing principal of a request, or `null` when the request carries no
+ * verified service principal (an ordinary user session is not a billable
+ * machine principal — its account is resolved from the account graph, not from
+ * a token claim).
+ *
+ * Reads `req.serviceApp` and NOTHING else: not `req.userId`, not `req.user`,
+ * not `req.serviceActingAs`. That exclusivity is the invariant this function
+ * exists to hold, and `serviceTokenAttribution.test.ts` mutation-tests it.
+ *
+ * **It answers for the SERVICE-TOKEN lane only.** The API's machine-credential
+ * lane (`oxy_sk_*`, issue #972 §2.3) resolves the same five facts into its own
+ * `req.machineCredential`, deliberately never `req.serviceApp` — populating the
+ * latter would hand a self-serve third-party credential the lane that only
+ * platform-trusted applications may enter. So a machine-credential request has
+ * no billing principal HERE and resolves `null`, which fails closed: the caller
+ * must handle it, and `getRequiredOxyBillingPrincipal` throws rather than
+ * charging anyone. One accessor answering for both lanes belongs to the public
+ * inference edge that has to admit both, and it needs the machine principal's
+ * shape to move into this package first.
+ */
+export function getOxyBillingPrincipal(req: Request): OxyBillingPrincipal | null {
+  const serviceApp = (req as OxyAuthRequest).serviceApp;
+  if (!serviceApp) {
+    return null;
+  }
+  const accountId = normalizeId(serviceApp.ownerAccountId);
+  const applicationId = normalizeId(serviceApp.appId);
+  const credentialId = normalizeId(serviceApp.credentialId);
+  if (!accountId || !applicationId || !credentialId) {
+    return null;
+  }
+  return {
+    accountId,
+    applicationId,
+    credentialId,
+    environment: serviceApp.environment,
+    scopes: serviceApp.scopes,
+  };
+}
+
+/**
+ * {@link getOxyBillingPrincipal}, throwing when the request has none. Use on
+ * routes that have already required a service token.
+ */
+export function getRequiredOxyBillingPrincipal(req: Request): OxyBillingPrincipal {
+  const principal = getOxyBillingPrincipal(req);
+  if (!principal) {
+    throw new Error('Request has no verified Oxy service principal');
+  }
+  return principal;
+}
+
+/**
+ * The delegated end user of a service request, or `null`.
+ *
+ * Deliberately reads `req.serviceActingAs` — the grant-verified delegation —
+ * and not `req.userId`, which on a non-service request is the caller's own
+ * session identity and is not a delegation at all.
+ */
+export function getOxyDelegatedUserId(req: Request): string | null {
+  return normalizeId((req as OxyAuthRequest).serviceActingAs?.userId);
+}
+
+/**
+ * The whole attribution tuple for a service request: who pays, which
+ * application and credential, and optionally on whose behalf.
+ */
+export function getOxyRequestAttribution(req: Request): OxyRequestAttribution | null {
+  const principal = getOxyBillingPrincipal(req);
+  if (!principal) {
+    return null;
+  }
+  return { ...principal, delegatedUserId: getOxyDelegatedUserId(req) };
+}
+
 export function getRequiredOxyUserId(req: Request): string {
   const userId = getOxyUserId(req);
   if (!userId) {

package/src/server/cors.ts

@@ -15,6 +15,7 @@
  *     one-label subdomains such as `auth.oxy.so`, `api.oxy.so`,
  *     `accounts.oxy.so`, `console.oxy.so`, and `inbox.oxy.so`,
  *   - allows the caller's explicit `appOrigins`,
+ *   - REFUSES the opaque origin on both sides (see `OPAQUE_ORIGIN`),
  *   - DENIES everything else (no reflection, never a wildcard with credentials),
  *   - echoes back the EXACT matched origin (so credentialed requests work) and
  *     sets `Vary: Origin` for correct caching,
@@ -24,8 +25,11 @@
  */
 
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import { createLogger } from '../logger';
 import { CENTRAL_IDP_APEX } from '../utils/authWebUrl';
 
+const log = createLogger('OxyCors');
+
 /** Default HTTP methods allowed across origins. */
 const DEFAULT_ALLOWED_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS'];
 
@@ -52,6 +56,11 @@ export interface OxyCorsOptions {
    * `https://app.example.com`, `http://localhost:3000`). These are allowed IN
    * ADDITION TO the built-in HTTPS Oxy apex origin family. Each is normalized
    * via `new URL().origin`.
+   *
+   * An entry that is not a URL, or whose origin is the opaque origin
+   * (`exp://…`, `capacitor://…`, `chrome-extension://…`, `file:`, `data:`), is
+   * DROPPED with an error log rather than admitted — see `OPAQUE_ORIGIN` for
+   * why one such entry would otherwise admit every other one.
    */
   appOrigins?: string[];
   /**
@@ -94,6 +103,30 @@ function isOxyFamilyOrigin(candidate: string): boolean {
   }
 }
 
+/**
+ * The URL standard's serialization of an OPAQUE origin: the literal string
+ * `"null"`, which `new URL(x).origin` returns for every scheme that has no
+ * origin to speak of — `exp:`, `capacitor:`, `chrome-extension:`,
+ * `vscode-webview:`, and also `file:`, `data:` and `about:`.
+ *
+ * This value is why an allowlist may never store it. Every such scheme
+ * normalizes to the SAME `"null"`, so a set built by normalization cannot tell
+ * them apart: ONE opaque entry admits ALL of them. With credentials on and the
+ * raw header echoed back, a single `myapp://` in `appOrigins` turned this
+ * helper into "allow any custom-scheme browsing context" — measured live, an
+ * `exp://localhost:8150` entry answered `Origin: vscode-webview://…` with
+ * `access-control-allow-origin: vscode-webview://…` and
+ * `access-control-allow-credentials: true`.
+ *
+ * There is deliberately no escape hatch that matches such an origin by raw
+ * string instead. Admitting a custom-scheme browsing context to a CREDENTIALED
+ * allowlist is a distinct decision with its own threat model, and it must not
+ * arrive as a side effect of someone adding one line to `appOrigins`. Note
+ * also that a native client is not subject to CORS at all — React Native sends
+ * no `Origin` header — so a mobile app never needs an entry here.
+ */
+const OPAQUE_ORIGIN = 'null';
+
 /** Normalize a raw origin string to its canonical `scheme://host[:port]` form. */
 function normalizeOrigin(raw: string): string | null {
   try {
@@ -104,21 +137,63 @@ function normalizeOrigin(raw: string): string | null {
 }
 
 /**
- * Build the origin-matching predicate: true iff `origin` is in the built-in
- * HTTPS Oxy apex family OR exactly matches one of the configured app origins.
+ * Normalize the configured `appOrigins` into the exact-match set — the
+ * CONFIGURE-SIDE half of the opaque-origin guard.
+ *
+ * An entry that is not a URL, or whose origin is opaque, is dropped and named
+ * in an error log. Dropped rather than thrown on because `appOrigins` is
+ * deployment configuration — at least one Oxy backend reads it from the
+ * environment — and a typo there must cost that one origin its CORS headers,
+ * never the whole service its boot. Both failure modes are equally SAFE (the
+ * entry is absent from the set either way), so the choice is purely about
+ * blast radius, and dropping keeps it to one origin whose requests then fail
+ * visibly in the browser.
+ *
+ * Exported for `__tests__/cors.socket.test.ts` and NOT re-exported from
+ * `server/index.ts`, so it is not part of the package's public surface. The
+ * two halves of the guard are separately exported because they are separately
+ * testable only that way: with this half in place the match-side half is
+ * unreachable through `createOxyCors`, so a test driving the public API alone
+ * would measure this function twice and the other one never.
  */
-function buildOriginAllowed(appOrigins: string[]): (origin: string) => boolean {
+export function normalizeAppOrigins(appOrigins: string[]): Set<string> {
   const explicit = new Set<string>();
   for (const raw of appOrigins) {
     const normalized = normalizeOrigin(raw);
-    if (normalized) explicit.add(normalized);
+    if (normalized === null) {
+      log.error('CORS allowlist entry ignored: it is not a URL', undefined, { entry: raw });
+      continue;
+    }
+    if (normalized === OPAQUE_ORIGIN) {
+      log.error('CORS allowlist entry ignored: it has no origin to match against', undefined, {
+        entry: raw,
+      });
+      continue;
+    }
+    explicit.add(normalized);
   }
-  return (origin: string): boolean => {
-    const normalized = normalizeOrigin(origin);
-    if (normalized === null) return false;
-    if (explicit.has(normalized)) return true;
-    return isOxyFamilyOrigin(normalized);
-  };
+  return explicit;
+}
+
+/**
+ * Whether `origin` may be echoed back: it is in the built-in HTTPS Oxy apex
+ * family, or it exactly matches one of the configured app origins.
+ *
+ * The opaque-origin refusal here is the MATCH-SIDE half of the guard, and it
+ * is what makes the property hold regardless of how `explicit` was built — a
+ * set that somehow contains `"null"` still matches nothing, because no
+ * incoming origin ever normalizes past this line. `normalizeAppOrigins` is
+ * what stops such a set existing today; this is what stops it mattering.
+ *
+ * Exported for the same reason as `normalizeAppOrigins`, and likewise absent
+ * from `server/index.ts`.
+ */
+export function matchesAllowedOrigin(explicit: ReadonlySet<string>, origin: string): boolean {
+  const normalized = normalizeOrigin(origin);
+  if (normalized === null) return false;
+  if (normalized === OPAQUE_ORIGIN) return false;
+  if (explicit.has(normalized)) return true;
+  return isOxyFamilyOrigin(normalized);
 }
 
 /**
@@ -139,7 +214,7 @@ export function createOxyCors(options: OxyCorsOptions = {}): RequestHandler {
     maxAgeSeconds = DEFAULT_MAX_AGE_SECONDS,
   } = options;
 
-  const isOriginAllowed = buildOriginAllowed(appOrigins);
+  const explicitOrigins = normalizeAppOrigins(appOrigins);
   const methodsHeader = methods.join(', ');
   const allowedHeadersHeader = allowedHeaders.join(', ');
   const exposedHeadersHeader = exposedHeaders.join(', ');
@@ -161,7 +236,7 @@ export function createOxyCors(options: OxyCorsOptions = {}): RequestHandler {
     // Origin is present. Caching correctness: this response varies by Origin.
     res.setHeader('Vary', 'Origin');
 
-    if (!isOriginAllowed(origin)) {
+    if (!matchesAllowedOrigin(explicitOrigins, origin)) {
       // DENY: do NOT reflect the origin, do NOT emit a wildcard. The browser
       // will block the cross-origin read. Preflights for denied origins get a
       // 204 with no CORS headers (the actual request then fails CORS).