@oxy.so/core 1.0.0

package/src/models/session.ts

@@ -0,0 +1,55 @@
+import type { UserNameResponse } from '@oxy.so/contracts';
+
+export interface ClientSession {
+  sessionId: string;
+  deviceId: string;
+  expiresAt: string;
+  lastActive: string;
+  userId?: string;
+  isCurrent?: boolean;
+  /**
+   * The account's ordinal slot (0..N) within the device's account set
+   * (`SessionAccount.authuser` in `@oxy.so/contracts`), projected from the
+   * device-first `DeviceSessionState` — used purely for stable Google-style
+   * account-chooser ordering, not for any token-refresh mechanism.
+   */
+  authuser?: number;
+  /**
+   * The HUMAN operating this account, when it is a delegated session — the
+   * audit actor behind "The Oxy Collective". Absent when the session belongs to
+   * the account itself.
+   *
+   * The flat wire shape has carried it since the multi-account model shipped and
+   * nothing read it, so an operated org rendered exactly like a directly
+   * signed-in one. `SessionClient.getActiveContext()` is the richer answer
+   * (ADR 0002); this is the same fact on the compatibility lane.
+   */
+  operatedByUserId?: string;
+}
+
+export interface StorageKeys {
+  sessions: string; // Array of ClientSession objects
+  activeSessionId: string; // ID of currently active session
+}
+
+export interface MinimalUserData {
+  id: string;
+  username: string;
+  name: UserNameResponse;
+  avatar?: string; // file id
+}
+
+export interface SessionLoginResponse {
+  sessionId: string;
+  deviceId: string;
+  expiresAt: string;
+  user: MinimalUserData;
+  /** JWT access token for API authentication */
+  accessToken?: string;
+  /**
+   * Rotating zero-cookie device credential minted on sign-in / claim. Persisted
+   * first-party alongside `deviceId` so cold boot can re-mint via
+   * `POST /session/device/token`.
+   */
+  deviceSecret?: string;
+}

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

@@ -0,0 +1,78 @@
+import type { NextFunction, Request, Response } from 'express';
+import type { OxyServices } from '../../OxyServices';
+import {
+  createOxyAuthMiddleware,
+  getOxyUserId,
+  getRequiredOxyUserId,
+  requireOxyAuth,
+  type OxyAuthRequest,
+} from '../auth';
+
+function makeResponse(): Response {
+  return {
+    status: jest.fn().mockReturnThis(),
+    json: jest.fn().mockReturnThis(),
+  } as unknown as Response;
+}
+
+function makeNext(): NextFunction {
+  return jest.fn() as unknown as NextFunction;
+}
+
+describe('@oxy.so/core/server auth helpers', () => {
+  it('reads the current user id from userId, user.id, or user._id', () => {
+    expect(getOxyUserId({ userId: 'user-from-request' } as OxyAuthRequest)).toBe('user-from-request');
+    expect(getOxyUserId({ user: { id: 'user-from-id' } } as OxyAuthRequest)).toBe('user-from-id');
+    expect(getOxyUserId({ user: { id: '', _id: 'user-from-mongo-id' } } as OxyAuthRequest)).toBe('user-from-mongo-id');
+    expect(getOxyUserId({ user: { id: '' } } as OxyAuthRequest)).toBeNull();
+  });
+
+  it('throws when a required user id is missing', () => {
+    expect(() => getRequiredOxyUserId({} as Request)).toThrow('User not authenticated');
+  });
+
+  it('returns a consistent 401 when auth is missing', () => {
+    const req = {} as Request;
+    const res = makeResponse();
+    const next = makeNext();
+
+    requireOxyAuth(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'Unauthorized',
+      message: 'Authentication required',
+    });
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('normalizes an authenticated request before continuing', () => {
+    const req = { user: { id: '', _id: 'mongo-user-id' } } as OxyAuthRequest;
+    const res = makeResponse();
+    const next = makeNext();
+
+    requireOxyAuth(req, res, next);
+
+    expect(req.userId).toBe('mongo-user-id');
+    expect(req.user?.id).toBe('mongo-user-id');
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('can resolve and require auth as one middleware', () => {
+    const oxy = {
+      auth: jest.fn(() => (req: OxyAuthRequest, _res: Response, next: NextFunction) => {
+        req.user = { id: 'resolved-user' };
+        next();
+      }),
+    } as unknown as OxyServices;
+    const req = {} as OxyAuthRequest;
+    const res = makeResponse();
+    const next = makeNext();
+
+    createOxyAuthMiddleware(oxy)(req, res, next);
+
+    expect(oxy.auth).toHaveBeenCalledWith({ optional: true });
+    expect(req.userId).toBe('resolved-user');
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -0,0 +1,111 @@
+import type { CapabilityTicketClaims } from '@oxy.so/contracts';
+import { generateKeyPairSync } from 'node:crypto';
+import type { CapabilityTicketError } from '../capabilityTicket';
+import {
+  inputSatisfiesCapabilityLimits,
+  issueCapabilityTicket,
+  readCapabilityAuthorization,
+  verifyCapabilityTicket,
+} from '../capabilityTicket';
+
+const NOW = new Date('2026-09-01T10:00:00.000Z');
+const KEY_PAIR = generateKeyPairSync('ed25519');
+const KEY_ID = 'capability-test-1';
+
+const claims: Omit<CapabilityTicketClaims, 'iss' | 'iat' | 'exp' | 'jti'> = {
+  aud: 'inbox-api',
+  sub: 'agent-1',
+  runId: 'run-1',
+  executionAuthorization: { kind: 'direct_request', id: 'authorization-1' },
+  coordinator: { applicationId: 'alia-app', credentialId: 'alia-credential' },
+  requesterAccountId: 'owner-1',
+  ownerAccountId: 'owner-1',
+  actor: { type: 'agent', accountId: 'agent-1' },
+  resource: {
+    appId: 'inbox',
+    effectiveAccountId: 'business-1',
+    resourceType: 'mailbox',
+    resourceId: 'mailbox-1',
+  },
+  tool: 'sendEmail',
+  capabilities: ['email.send'],
+  limits: [],
+  autonomy: 'execute_on_request',
+};
+
+describe('capability tickets', () => {
+  it('parses the Capability HTTP authentication scheme case-insensitively', () => {
+    expect(readCapabilityAuthorization('Capability signed-ticket')).toBe('signed-ticket');
+    expect(readCapabilityAuthorization('capability signed-ticket')).toBe('signed-ticket');
+    expect(readCapabilityAuthorization('Bearer signed-ticket')).toBeNull();
+    expect(readCapabilityAuthorization('Capability signed-ticket extra')).toBeNull();
+  });
+
+  it('round-trips exact actor, effective account, resource and run claims', () => {
+    const token = issueCapabilityTicket(claims, {
+      issuer: 'https://api.oxy.so',
+      privateKey: KEY_PAIR.privateKey,
+      keyId: KEY_ID,
+      now: NOW,
+      jti: 'ticket-1',
+      ttlSeconds: 60,
+    });
+    const verified = verifyCapabilityTicket(token, {
+      audience: 'inbox-api',
+      issuer: 'https://api.oxy.so',
+      resolvePublicKey: (keyId) => keyId === KEY_ID ? KEY_PAIR.publicKey : undefined,
+      now: new Date('2026-09-01T10:00:30.000Z'),
+    });
+
+    expect(verified.actor).toEqual({ type: 'agent', accountId: 'agent-1' });
+    expect(verified.resource.effectiveAccountId).toBe('business-1');
+    expect(verified.resource.resourceId).toBe('mailbox-1');
+    expect(verified.runId).toBe('run-1');
+  });
+
+  it('rejects cross-app replay even when the signature is valid', () => {
+    const token = issueCapabilityTicket(claims, {
+      issuer: 'https://api.oxy.so', privateKey: KEY_PAIR.privateKey, keyId: KEY_ID, now: NOW,
+    });
+
+    expect(() => verifyCapabilityTicket(token, {
+      audience: 'mention-api', resolvePublicKey: () => KEY_PAIR.publicKey, now: NOW,
+    })).toThrow(expect.objectContaining<Partial<CapabilityTicketError>>({ code: 'wrong_audience' }));
+    expect(() => verifyCapabilityTicket(token, {
+      audience: 'inbox-api', resolvePublicKey: () => undefined, now: NOW,
+    })).toThrow(expect.objectContaining<Partial<CapabilityTicketError>>({ code: 'unknown_key' }));
+  });
+
+  it('rejects expired, tampered and overlong tickets', () => {
+    const token = issueCapabilityTicket(claims, {
+      issuer: 'https://api.oxy.so', privateKey: KEY_PAIR.privateKey, keyId: KEY_ID, now: NOW, ttlSeconds: 60,
+    });
+    expect(() => verifyCapabilityTicket(token, {
+      audience: 'inbox-api', resolvePublicKey: () => KEY_PAIR.publicKey, now: new Date('2026-09-01T10:01:00.000Z'),
+    })).toThrow(expect.objectContaining<Partial<CapabilityTicketError>>({ code: 'expired' }));
+
+    const [header, payload, signature] = token.split('.');
+    expect(() => verifyCapabilityTicket(`${header}.${payload}x.${signature}`, {
+      audience: 'inbox-api', resolvePublicKey: () => KEY_PAIR.publicKey, now: NOW,
+    })).toThrow(expect.objectContaining<Partial<CapabilityTicketError>>({ code: 'invalid_signature' }));
+
+    expect(() => issueCapabilityTicket(claims, {
+      issuer: 'https://api.oxy.so', privateKey: KEY_PAIR.privateKey, keyId: KEY_ID, now: NOW, ttlSeconds: 301,
+    })).toThrow(expect.objectContaining<Partial<CapabilityTicketError>>({ code: 'ttl_exceeded' }));
+  });
+
+  it('enforces numeric and boolean limits carried by a ticket', () => {
+    const limits = [
+      { tool: 'sendPayment', key: 'amount', value: 100 },
+      { tool: 'sendPayment', key: 'confirmed', value: true },
+    ];
+    expect(inputSatisfiesCapabilityLimits('sendPayment', { amount: 75, confirmed: true }, limits)).toBe(true);
+    expect(inputSatisfiesCapabilityLimits('sendPayment', { amount: 101, confirmed: true }, limits)).toBe(false);
+    expect(inputSatisfiesCapabilityLimits('sendPayment', { amount: 75, confirmed: false }, limits)).toBe(false);
+    expect(inputSatisfiesCapabilityLimits('sendPayment', { amount: 75 }, limits)).toBe(false);
+    expect(inputSatisfiesCapabilityLimits('otherTool', { amount: 75, confirmed: true }, limits)).toBe(false);
+    expect(inputSatisfiesCapabilityLimits('updateFlags', {
+      flags: { seen: true },
+    }, [{ tool: 'updateFlags', key: 'flags.seen', value: true }])).toBe(true);
+  });
+});

package/src/server/__tests__/cors.socket.test.ts

@@ -0,0 +1,225 @@
+/**
+ * `createOxyCors` over a REAL socket, plus the two halves of the opaque-origin
+ * guard.
+ *
+ * `cors.test.ts` drives the middleware with a fake `Request`/`Response` pair,
+ * which is fine for header bookkeeping but cannot answer the question this
+ * suite exists for: what a client actually receives. These tests start an
+ * Express app on an ephemeral port and read the response headers off the wire.
+ *
+ * `node:http` rather than `fetch`: `Origin` is a forbidden header name for
+ * `fetch`, so the request under test has to be built by hand.
+ */
+
+import http from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { configureLogger, resetLoggerConfig } from '../../logger';
+import type { LogEntry } from '../../logger';
+import { createOxyCors, matchesAllowedOrigin, normalizeAppOrigins } from '../cors';
+import type { OxyCorsOptions } from '../cors';
+
+interface CorsResponse {
+  status: number;
+  allowOrigin: string | undefined;
+  allowCredentials: string | undefined;
+}
+
+/** Start an Express app carrying `createOxyCors(options)` on an ephemeral port. */
+async function startServer(options: OxyCorsOptions): Promise<http.Server> {
+  const app = express();
+  app.use(createOxyCors(options));
+  app.get('/catalogue', (_req, res) => {
+    res.json({ ok: true });
+  });
+  const server = http.createServer(app);
+  await new Promise<void>((resolve) => {
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  return server;
+}
+
+async function stopServer(server: http.Server): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()));
+  });
+}
+
+/** Issue a real request carrying `Origin` and read the CORS headers back. */
+function requestWithOrigin(
+  server: http.Server,
+  method: 'GET' | 'OPTIONS',
+  origin: string,
+): Promise<CorsResponse> {
+  const { port } = server.address() as AddressInfo;
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      {
+        host: '127.0.0.1',
+        port,
+        method,
+        path: '/catalogue',
+        headers: { Origin: origin, 'Access-Control-Request-Method': 'GET' },
+      },
+      (res) => {
+        res.resume();
+        res.on('end', () => {
+          resolve({
+            status: res.statusCode ?? 0,
+            allowOrigin: res.headers['access-control-allow-origin'],
+            allowCredentials: res.headers['access-control-allow-credentials'],
+          });
+        });
+        res.on('error', reject);
+      },
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+/**
+ * The exact shape that was live: one custom-scheme entry alongside ordinary
+ * ones. Every origin below normalizes to the opaque origin, so before the fix
+ * the `exp://` entry admitted all of them.
+ */
+const CONFIGURED_WITH_OPAQUE_ENTRY = ['https://app.example.com', 'exp://localhost:8150'];
+const OTHER_OPAQUE_SCHEME_ORIGINS = [
+  'vscode-webview://abc123',
+  'capacitor://localhost',
+  'chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+  'file://',
+];
+
+describe('createOxyCors over a real socket', () => {
+  let server: http.Server;
+
+  beforeAll(async () => {
+    // The dropped entry logs at error level by design; that log is asserted in
+    // the configure-side suite below. Swallow it here so this suite's output
+    // carries only its own failures.
+    configureLogger({ sink: () => undefined });
+    server = await startServer({ appOrigins: CONFIGURED_WITH_OPAQUE_ENTRY });
+    resetLoggerConfig();
+  });
+
+  afterAll(async () => {
+    await stopServer(server);
+  });
+
+  it('POSITIVE CONTROL: a configured https origin gets its headers over the wire', async () => {
+    for (const method of ['GET', 'OPTIONS'] as const) {
+      const res = await requestWithOrigin(server, method, 'https://app.example.com');
+      expect(res.allowOrigin).toBe('https://app.example.com');
+      expect(res.allowCredentials).toBe('true');
+    }
+  });
+
+  it('POSITIVE CONTROL: the built-in Oxy apex family still gets its headers', async () => {
+    const res = await requestWithOrigin(server, 'GET', 'https://auth.oxy.so');
+    expect(res.allowOrigin).toBe('https://auth.oxy.so');
+    expect(res.allowCredentials).toBe('true');
+  });
+
+  it('a custom-scheme origin is NOT admitted by a custom-scheme allowlist entry', async () => {
+    for (const origin of OTHER_OPAQUE_SCHEME_ORIGINS) {
+      for (const method of ['GET', 'OPTIONS'] as const) {
+        const res = await requestWithOrigin(server, method, origin);
+        expect(res.allowOrigin).toBeUndefined();
+        expect(res.allowCredentials).toBeUndefined();
+      }
+    }
+  });
+
+  it('the opaque-origin entry does not admit even ITSELF', async () => {
+    const res = await requestWithOrigin(server, 'GET', 'exp://localhost:8150');
+    expect(res.allowOrigin).toBeUndefined();
+    expect(res.allowCredentials).toBeUndefined();
+  });
+
+  it('NEGATIVE CONTROL: a literal `Origin: null` is refused, as it always was', async () => {
+    const res = await requestWithOrigin(server, 'GET', 'null');
+    expect(res.allowOrigin).toBeUndefined();
+    expect(res.allowCredentials).toBeUndefined();
+  });
+
+  it('NEGATIVE CONTROL: an unrelated https origin is refused', async () => {
+    const res = await requestWithOrigin(server, 'GET', 'https://evil.example.com');
+    expect(res.allowOrigin).toBeUndefined();
+    expect(res.allowCredentials).toBeUndefined();
+  });
+});
+
+/**
+ * The CONFIGURE-SIDE half. Its behavioural effect is masked by the match-side
+ * half — with both in place, deleting this one changes no response — so what
+ * this suite asserts is the observable the drop-rather-than-throw decision
+ * rests on: the entry is named in an error log, and nothing else stops.
+ */
+describe('normalizeAppOrigins (configure side)', () => {
+  let entries: LogEntry[];
+
+  beforeEach(() => {
+    entries = [];
+    configureLogger({ sink: (entry) => entries.push(entry) });
+  });
+
+  afterEach(() => {
+    resetLoggerConfig();
+  });
+
+  it('drops an opaque-origin entry from the set and names it in an error log', () => {
+    const explicit = normalizeAppOrigins(CONFIGURED_WITH_OPAQUE_ENTRY);
+
+    expect([...explicit]).toEqual(['https://app.example.com']);
+    expect(explicit.has('null')).toBe(false);
+
+    const dropped = entries.filter((entry) => entry.level === 'error');
+    expect(dropped).toHaveLength(1);
+    expect(dropped[0]?.context?.entry).toBe('exp://localhost:8150');
+    expect(dropped[0]?.message).toContain('no origin to match against');
+  });
+
+  it('drops an entry that is not a URL at all, separately named', () => {
+    const explicit = normalizeAppOrigins(['not a url', 'https://app.example.com']);
+
+    expect([...explicit]).toEqual(['https://app.example.com']);
+    const dropped = entries.filter((entry) => entry.level === 'error');
+    expect(dropped).toHaveLength(1);
+    expect(dropped[0]?.context?.entry).toBe('not a url');
+    expect(dropped[0]?.message).toContain('not a URL');
+  });
+
+  it('VACUITY FLOOR: a wholly valid list is dropped from silently', () => {
+    const explicit = normalizeAppOrigins(['https://app.example.com', 'http://localhost:3000']);
+
+    expect([...explicit].sort()).toEqual(['http://localhost:3000', 'https://app.example.com']);
+    expect(entries.filter((entry) => entry.level === 'error')).toHaveLength(0);
+  });
+});
+
+/**
+ * The MATCH-SIDE half, driven with the hostile precondition the configure side
+ * prevents: a set that already contains the opaque origin. This is the only
+ * way to observe this half — through `createOxyCors` it is unreachable, so a
+ * test there would measure `normalizeAppOrigins` and report on this.
+ */
+describe('matchesAllowedOrigin (match side)', () => {
+  const poisoned: ReadonlySet<string> = new Set(['null', 'https://app.example.com']);
+
+  it('refuses every opaque-scheme origin even against a set containing "null"', () => {
+    for (const origin of [...OTHER_OPAQUE_SCHEME_ORIGINS, 'exp://localhost:8150']) {
+      expect(matchesAllowedOrigin(poisoned, origin)).toBe(false);
+    }
+  });
+
+  it('POSITIVE CONTROL: the same poisoned set still matches its real entry', () => {
+    expect(matchesAllowedOrigin(poisoned, 'https://app.example.com')).toBe(true);
+    expect(matchesAllowedOrigin(poisoned, 'https://auth.oxy.so')).toBe(true);
+    expect(matchesAllowedOrigin(poisoned, 'https://evil.example.com')).toBe(false);
+  });
+
+  it('NEGATIVE CONTROL: a literal `null` never reaches the set lookup either', () => {
+    expect(matchesAllowedOrigin(poisoned, 'null')).toBe(false);
+  });
+});

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

@@ -0,0 +1,158 @@
+import type { NextFunction, Request, Response } from 'express';
+import { createOxyCors } from '../cors';
+
+interface FakeResponse extends Response {
+  __headers: Record<string, string>;
+  __statusSent: number | null;
+}
+
+function makeRequest(method: string, origin?: string, acrHeaders?: string): Request {
+  const headers: Record<string, string> = {};
+  if (origin !== undefined) headers.origin = origin;
+  if (acrHeaders !== undefined) headers['access-control-request-headers'] = acrHeaders;
+  return { method, headers } as unknown as Request;
+}
+
+function makeResponse(): FakeResponse {
+  const res = {
+    __headers: {},
+    __statusSent: null,
+  } as FakeResponse;
+  res.setHeader = jest.fn((name: string, value: string | number | readonly string[]) => {
+    res.__headers[name] = String(value);
+    return res;
+  }) as unknown as Response['setHeader'];
+  res.sendStatus = jest.fn((code: number) => {
+    res.__statusSent = code;
+    return res;
+  }) as unknown as Response['sendStatus'];
+  return res;
+}
+
+function makeNext(): NextFunction & jest.Mock {
+  return jest.fn() as unknown as NextFunction & jest.Mock;
+}
+
+describe('@oxy.so/core/server createOxyCors', () => {
+  it('allows the HTTPS Oxy apex family (apex + one-level subdomains) and echoes the exact origin', () => {
+    const mw = createOxyCors();
+    for (const origin of [
+      'https://oxy.so',
+      'https://auth.oxy.so',
+      'https://api.oxy.so',
+      'https://accounts.oxy.so',
+      'https://console.oxy.so',
+      'https://inbox.oxy.so',
+    ]) {
+      const req = makeRequest('GET', origin);
+      const res = makeResponse();
+      const next = makeNext();
+      mw(req, res, next);
+      expect(res.__headers['Access-Control-Allow-Origin']).toBe(origin);
+      expect(res.__headers['Access-Control-Allow-Credentials']).toBe('true');
+      expect(res.__headers.Vary).toBe('Origin');
+      expect(next).toHaveBeenCalledTimes(1);
+    }
+  });
+
+  it('allows explicit appOrigins', () => {
+    const mw = createOxyCors({ appOrigins: ['https://app.example.com', 'http://localhost:3000'] });
+    for (const origin of ['https://app.example.com', 'http://localhost:3000']) {
+      const req = makeRequest('GET', origin);
+      const res = makeResponse();
+      const next = makeNext();
+      mw(req, res, next);
+      expect(res.__headers['Access-Control-Allow-Origin']).toBe(origin);
+      expect(next).toHaveBeenCalledTimes(1);
+    }
+  });
+
+  it('DENIES other origins — never reflects them, never wildcards', () => {
+    const mw = createOxyCors({ appOrigins: ['https://app.example.com'] });
+    for (const origin of [
+      'https://evil.com',
+      'https://oxy.so.evil.com', // suffix attack
+      'https://notoxy.so', // different apex
+      'https://example.com',
+      'http://oxy.so',
+      'http://auth.oxy.so',
+      'https://deep.attacker-controlled.oxy.so',
+      'https://api.oxy.so:8443',
+    ]) {
+      const req = makeRequest('GET', origin);
+      const res = makeResponse();
+      const next = makeNext();
+      mw(req, res, next);
+      expect(res.__headers['Access-Control-Allow-Origin']).toBeUndefined();
+      expect(res.__headers['Access-Control-Allow-Origin']).not.toBe('*');
+      expect(res.__headers['Access-Control-Allow-Origin']).not.toBe(origin);
+      // request still passes to the app; the browser enforces the missing ACAO.
+      expect(next).toHaveBeenCalledTimes(1);
+    }
+  });
+
+  it('NEVER emits wildcard ACAO together with credentials', () => {
+    const mw = createOxyCors({ allowCredentials: true });
+    // Even an allowed origin gets the exact origin, never '*'.
+    const req = makeRequest('GET', 'https://auth.oxy.so');
+    const res = makeResponse();
+    mw(req, res, makeNext());
+    expect(res.__headers['Access-Control-Allow-Origin']).toBe('https://auth.oxy.so');
+    expect(res.__headers['Access-Control-Allow-Origin']).not.toBe('*');
+    expect(res.__headers['Access-Control-Allow-Credentials']).toBe('true');
+  });
+
+  it('answers preflight (OPTIONS) for an allowed origin with 204 + method/header allows', () => {
+    const mw = createOxyCors({ appOrigins: ['https://app.example.com'] });
+    const req = makeRequest('OPTIONS', 'https://app.example.com', 'content-type, authorization');
+    const res = makeResponse();
+    const next = makeNext();
+    mw(req, res, next);
+    expect(res.__headers['Access-Control-Allow-Origin']).toBe('https://app.example.com');
+    expect(res.__headers['Access-Control-Allow-Methods']).toContain('GET');
+    expect(res.__headers['Access-Control-Allow-Headers']).toBe('content-type, authorization');
+    expect(res.__headers['Access-Control-Max-Age']).toBeDefined();
+    expect(res.__statusSent).toBe(204);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('includes anonymous activity metadata in the default preflight headers', () => {
+    const mw = createOxyCors({ appOrigins: ['https://app.example.com'] });
+    const req = makeRequest('OPTIONS', 'https://app.example.com');
+    const res = makeResponse();
+    mw(req, res, makeNext());
+
+    expect(res.__headers['Access-Control-Allow-Headers']).toContain('X-Oxy-Edge-Region');
+    expect(res.__headers['Access-Control-Allow-Headers']).toContain('X-Oxy-Activity-Id');
+  });
+
+  it('answers preflight for a DENIED origin with 204 and NO CORS headers', () => {
+    const mw = createOxyCors();
+    const req = makeRequest('OPTIONS', 'https://evil.com');
+    const res = makeResponse();
+    const next = makeNext();
+    mw(req, res, next);
+    expect(res.__headers['Access-Control-Allow-Origin']).toBeUndefined();
+    expect(res.__statusSent).toBe(204);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('passes through same-origin / non-browser requests (no Origin header) without ACAO', () => {
+    const mw = createOxyCors();
+    const req = makeRequest('GET');
+    const res = makeResponse();
+    const next = makeNext();
+    mw(req, res, next);
+    expect(res.__headers['Access-Control-Allow-Origin']).toBeUndefined();
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('can disable credentials and still never wildcards', () => {
+    const mw = createOxyCors({ allowCredentials: false });
+    const req = makeRequest('GET', 'https://api.oxy.so');
+    const res = makeResponse();
+    mw(req, res, makeNext());
+    expect(res.__headers['Access-Control-Allow-Origin']).toBe('https://api.oxy.so');
+    expect(res.__headers['Access-Control-Allow-Credentials']).toBeUndefined();
+  });
+});