@oxyhq/core 3.9.1 → 3.10.1

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

@@ -0,0 +1,232 @@
+import type { LookupAddress, LookupAllOptions, LookupOneOptions } from 'node:dns';
+import type { LookupFunction } from 'node:net';
+
+// Mock node:dns/promises so the static `import { lookup }` binding in safeFetch
+// is intercepted (spying on the namespace doesn't work — the binding is
+// resolved at module load, and the real `lookup` property is non-configurable).
+const mockDnsLookup = jest.fn();
+jest.mock('node:dns/promises', () => ({
+  lookup: (...args: unknown[]) => mockDnsLookup(...args),
+}));
+
+import {
+  assertSafePublicUrl,
+  isBlockedIp,
+} from '../safeFetch';
+
+beforeEach(() => {
+  mockDnsLookup.mockReset();
+});
+
+describe('@oxyhq/core/server safeFetch — isBlockedIp', () => {
+  it('blocks private / loopback / metadata / reserved IPv4 ranges', () => {
+    const blocked = [
+      '127.0.0.1', // loopback
+      '10.0.0.1', // RFC1918
+      '10.255.255.255',
+      '172.16.0.1', // RFC1918
+      '172.31.255.255',
+      '192.168.1.1', // RFC1918
+      '169.254.169.254', // cloud metadata
+      '169.254.0.1', // link-local
+      '100.64.0.1', // CGNAT
+      '0.0.0.0', // this network
+      '224.0.0.1', // multicast
+      '255.255.255.255', // broadcast
+      '198.18.0.1', // benchmarking
+    ];
+    for (const ip of blocked) {
+      expect(isBlockedIp(ip)).toBe(true);
+    }
+  });
+
+  it('blocks loopback / ULA / link-local IPv6 ranges and IPv4-mapped internals', () => {
+    const blocked = [
+      '::1', // loopback
+      '::', // unspecified
+      'fc00::1', // unique local
+      'fe80::1', // link-local
+      'ff02::1', // multicast
+      '::ffff:127.0.0.1', // IPv4-mapped loopback
+      '::ffff:169.254.169.254', // IPv4-mapped metadata
+    ];
+    for (const ip of blocked) {
+      expect(isBlockedIp(ip)).toBe(true);
+    }
+  });
+
+  it('allows genuine public IPs', () => {
+    expect(isBlockedIp('1.1.1.1')).toBe(false);
+    expect(isBlockedIp('8.8.8.8')).toBe(false);
+    expect(isBlockedIp('93.184.216.34')).toBe(false); // example.com historical
+    expect(isBlockedIp('2606:4700:4700::1111')).toBe(false); // public IPv6
+  });
+
+  it('fails closed for non-IP literals', () => {
+    expect(isBlockedIp('not-an-ip')).toBe(true);
+    expect(isBlockedIp('')).toBe(true);
+  });
+});
+
+describe('@oxyhq/core/server safeFetch — assertSafePublicUrl', () => {
+  it('rejects literal private / metadata IP URLs without any DNS', async () => {
+    const cases: Array<[string, RegExp]> = [
+      ['http://169.254.169.254/latest/meta-data/', /blocked range/],
+      ['http://127.0.0.1/', /blocked range/],
+      ['http://10.0.0.1/', /blocked range/],
+      ['http://192.168.0.1/', /blocked range/],
+      ['http://[::1]/', /blocked range/],
+    ];
+    for (const [url, reason] of cases) {
+      const result = await assertSafePublicUrl(url);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.reason).toMatch(reason);
+    }
+  });
+
+  it('rejects blocked hostnames before resolving', async () => {
+    const result = await assertSafePublicUrl('http://localhost/');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe('blocked hostname');
+  });
+
+  it('rejects ambiguous numeric host forms before touching DNS', async () => {
+    for (const url of [
+      'http://2130706433/', // decimal 127.0.0.1
+      'http://0x7f.1/',
+      'http://0177.0.0.1/',
+      'http://127.1/',
+    ]) {
+      const result = await assertSafePublicUrl(url);
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(['ambiguous numeric host', 'literal ip in blocked range']).toContain(result.reason);
+      }
+    }
+  });
+
+  it('rejects disallowed protocols, ports, credentials, and oversized URLs', async () => {
+    expect((await assertSafePublicUrl('ftp://example.com/')).ok).toBe(false);
+    expect((await assertSafePublicUrl('file:///etc/passwd')).ok).toBe(false);
+    expect((await assertSafePublicUrl('http://example.com:22/')).ok).toBe(false);
+    expect((await assertSafePublicUrl('http://user:pass@example.com/')).ok).toBe(false);
+    expect((await assertSafePublicUrl('not a url')).ok).toBe(false);
+    expect((await assertSafePublicUrl(`http://example.com/${'a'.repeat(3000)}`)).ok).toBe(false);
+    expect((await assertSafePublicUrl('')).ok).toBe(false);
+  });
+
+  it('allows a literal public IP URL and pins the connection IP/family (no DNS)', async () => {
+    const result = await assertSafePublicUrl('https://1.1.1.1/');
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.ip).toBe('1.1.1.1');
+      expect(result.family).toBe(4);
+    }
+    expect(mockDnsLookup).not.toHaveBeenCalled();
+  });
+
+  it('rejects a public hostname that resolves into a blocked range (rebind defence)', async () => {
+    mockDnsLookup.mockResolvedValue([{ address: '10.0.0.5', family: 4 }]);
+    const result = await assertSafePublicUrl('https://attacker.example/');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe('hostname resolves to blocked range');
+    expect(mockDnsLookup).toHaveBeenCalledWith('attacker.example', { all: true });
+  });
+
+  it('rejects when ANY of multiple resolved records is internal', async () => {
+    mockDnsLookup.mockResolvedValue([
+      { address: '93.184.216.34', family: 4 }, // public
+      { address: '169.254.169.254', family: 4 }, // metadata smuggled in
+    ]);
+    const result = await assertSafePublicUrl('https://multi.example/');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe('hostname resolves to blocked range');
+  });
+
+  it('rejects when DNS resolution fails', async () => {
+    mockDnsLookup.mockRejectedValue(new Error('ENOTFOUND'));
+    const result = await assertSafePublicUrl('https://nope.example/');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe('dns resolution failed');
+  });
+
+  it('allows a public hostname resolving to public IPs and pins the first record', async () => {
+    mockDnsLookup.mockResolvedValue([
+      { address: '93.184.216.34', family: 4 },
+      { address: '93.184.216.35', family: 4 },
+    ]);
+    const result = await assertSafePublicUrl('https://example.com/');
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.ip).toBe('93.184.216.34');
+      expect(result.family).toBe(4);
+    }
+  });
+});
+
+/**
+ * Bun {all:true} lookup gotcha — shape assertion.
+ *
+ * The pinned `lookup` in safeFetch MUST return `[{address,family}]` when called
+ * with `{ all: true }` (Bun calls lookup(host,{all:true},cb) then `.sort()`s the
+ * result — a single value makes that internal sort throw "results.sort is not a
+ * function"), and the `(err,address,family)` triple otherwise (Node). We
+ * reconstruct the exact closure shape here and assert both call modes.
+ *
+ * (A full real-https.request verification against Bun was performed out of band;
+ * this unit test guards the array-vs-triple contract under Jest/Node.)
+ */
+describe('@oxyhq/core/server safeFetch — pinned lookup {all:true} contract', () => {
+  function makePinnedLookup(pinnedIp: string, pinnedFamily: 4 | 6): LookupFunction {
+    return ((
+      _hostname: string,
+      options: number | LookupOneOptions | LookupAllOptions,
+      callback: (
+        err: NodeJS.ErrnoException | null,
+        address: string | LookupAddress[],
+        family?: number,
+      ) => void,
+    ): void => {
+      const wantsAll = typeof options === 'object' && options !== null && options.all === true;
+      if (wantsAll) {
+        callback(null, [{ address: pinnedIp, family: pinnedFamily }]);
+      } else {
+        callback(null, pinnedIp, pinnedFamily);
+      }
+    }) as unknown as LookupFunction;
+  }
+
+  it('returns an ARRAY of {address,family} for {all:true} (sortable, no throw)', (done) => {
+    const lookup = makePinnedLookup('93.184.216.34', 4);
+    (lookup as unknown as (
+      h: string,
+      o: LookupAllOptions,
+      cb: (e: NodeJS.ErrnoException | null, a: LookupAddress[]) => void,
+    ) => void)(
+      'example.com',
+      { all: true } as LookupAllOptions,
+      (err, address) => {
+        expect(err).toBeNull();
+        expect(Array.isArray(address)).toBe(true);
+        // The address array is what Bun internally `.sort()`s — must be sortable.
+        expect(() => (address as LookupAddress[]).sort()).not.toThrow();
+        expect(address).toEqual([{ address: '93.184.216.34', family: 4 }]);
+        done();
+      },
+    );
+  });
+
+  it('returns the (address,family) triple for the non-all (Node) form', (done) => {
+    const lookup = makePinnedLookup('93.184.216.34', 4);
+    (lookup as unknown as (
+      h: string,
+      o: LookupOneOptions,
+      cb: (e: NodeJS.ErrnoException | null, a: string, f: number) => void,
+    ) => void)('example.com', {} as LookupOneOptions, (err, address, family) => {
+      expect(err).toBeNull();
+      expect(address).toBe('93.184.216.34');
+      expect(family).toBe(4);
+      done();
+    });
+  });
+});

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

@@ -0,0 +1,40 @@
+import { verifySecret } from '../verifySecret';
+
+describe('@oxyhq/core/server verifySecret', () => {
+  it('returns true for equal secrets', () => {
+    expect(verifySecret('s3cr3t-token', 's3cr3t-token')).toBe(true);
+    expect(verifySecret('a', 'a')).toBe(true);
+    const long = 'x'.repeat(256);
+    expect(verifySecret(long, long)).toBe(true);
+  });
+
+  it('returns false for unequal same-length secrets', () => {
+    expect(verifySecret('s3cr3t-token', 's3cr3t-tokeN')).toBe(false);
+    expect(verifySecret('abcd', 'abce')).toBe(false);
+  });
+
+  it('returns false on length mismatch without throwing', () => {
+    expect(() => verifySecret('short', 'a-much-longer-secret')).not.toThrow();
+    expect(verifySecret('short', 'a-much-longer-secret')).toBe(false);
+    expect(verifySecret('a-much-longer-secret', 'short')).toBe(false);
+    expect(verifySecret('abc', 'abcd')).toBe(false);
+  });
+
+  it('returns false for empty inputs', () => {
+    expect(verifySecret('', '')).toBe(false);
+    expect(verifySecret('', 'x')).toBe(false);
+    expect(verifySecret('x', '')).toBe(false);
+  });
+
+  it('returns false for non-string inputs without throwing', () => {
+    expect(() => verifySecret(undefined as unknown as string, 'x')).not.toThrow();
+    expect(verifySecret(undefined as unknown as string, 'x')).toBe(false);
+    expect(verifySecret('x', null as unknown as string)).toBe(false);
+    expect(verifySecret(123 as unknown as string, 123 as unknown as string)).toBe(false);
+  });
+
+  it('handles multi-byte UTF-8 content correctly', () => {
+    expect(verifySecret('clé-secrète-🔐', 'clé-secrète-🔐')).toBe(true);
+    expect(verifySecret('clé-secrète-🔐', 'cle-secrete-🔐')).toBe(false);
+  });
+});

package/src/server/cors.ts

@@ -0,0 +1,195 @@
+/**
+ * Strict CORS allowlist for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * App backends kept hand-rolling CORS, and the unsafe patterns recurred:
+ *   - `Access-Control-Allow-Origin: *` together with credentials (which is
+ *     spec-invalid AND a credential-leak vector), or
+ *   - a "reflect whatever Origin the request carried" fallback (effectively
+ *     `*` for credentialed requests — the Allo wildcard-fallback class).
+ *
+ * `createOxyCors` returns a self-contained Express middleware (no `cors`
+ * package dependency) that:
+ *   - allows the Oxy apex origin family (anything under `*.${CENTRAL_IDP_APEX}`,
+ *     i.e. `oxy.so` — covering `auth.oxy.so`, `api.oxy.so`, `accounts.oxy.so`,
+ *     `console.oxy.so`, `inbox.oxy.so`, the marketing site, …) reusing the
+ *     central-origin constants already in core, NOT a fresh hardcoded list,
+ *   - allows the caller's explicit `appOrigins`,
+ *   - 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,
+ *   - answers CORS preflight (`OPTIONS`) with `204`.
+ *
+ * Node/Express-only: exported solely from `@oxyhq/core/server`.
+ */
+
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import { CENTRAL_IDP_APEX } from '../utils/authWebUrl';
+import { registrableApex } from '../utils/fapiAutoDetect';
+
+/** Default HTTP methods allowed across origins. */
+const DEFAULT_ALLOWED_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS'];
+
+/** Default request headers a browser may send on a credentialed cross-origin call. */
+const DEFAULT_ALLOWED_HEADERS = [
+  'Content-Type',
+  'Authorization',
+  'X-Requested-With',
+  'X-Oxy-User-Id',
+  'X-Oxy-Internal',
+  'X-CSRF-Token',
+];
+
+/** How long (seconds) a browser may cache a successful preflight. */
+const DEFAULT_MAX_AGE_SECONDS = 86_400;
+
+export interface OxyCorsOptions {
+  /**
+   * Explicit additional allowed origins (exact-origin match, e.g.
+   * `https://app.example.com`, `http://localhost:3000`). These are allowed IN
+   * ADDITION TO the Oxy apex origin family. Each is normalized via `new URL().origin`.
+   */
+  appOrigins?: string[];
+  /**
+   * Whether to emit `Access-Control-Allow-Credentials: true`. Default `true`
+   * (the Oxy ecosystem uses cookie/bearer credentials). Even when `true`, the
+   * helper NEVER emits a wildcard origin — only an exact matched origin.
+   */
+  allowCredentials?: boolean;
+  /** HTTP methods to allow. Defaults to the full standard set. */
+  methods?: string[];
+  /** Request headers to allow. Defaults to the common Oxy set. */
+  allowedHeaders?: string[];
+  /** Response headers to expose to the browser. Defaults to none. */
+  exposedHeaders?: string[];
+  /** Preflight cache lifetime in seconds. Default 86400 (24h). */
+  maxAgeSeconds?: number;
+}
+
+/**
+ * Whether `candidate` belongs to the Oxy apex origin family — i.e. its
+ * registrable apex equals {@link CENTRAL_IDP_APEX} (`oxy.so`). This matches the
+ * apex itself (`https://oxy.so`) and any subdomain (`https://auth.oxy.so`,
+ * `https://api.oxy.so`, …) over http or https, ports allowed. Returns false on
+ * any parse failure (fail closed).
+ */
+function isOxyFamilyOrigin(candidate: string): boolean {
+  let hostname: string;
+  let protocol: string;
+  try {
+    const url = new URL(candidate);
+    hostname = url.hostname.toLowerCase();
+    protocol = url.protocol;
+  } catch {
+    return false;
+  }
+  if (protocol !== 'https:' && protocol !== 'http:') return false;
+  if (hostname === CENTRAL_IDP_APEX) return true;
+  return registrableApex(hostname) === CENTRAL_IDP_APEX;
+}
+
+/** Normalize a raw origin string to its canonical `scheme://host[:port]` form. */
+function normalizeOrigin(raw: string): string | null {
+  try {
+    return new URL(raw).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the origin-matching predicate: true iff `origin` is in the Oxy apex
+ * family OR exactly matches one of the configured app origins.
+ */
+function buildOriginAllowed(appOrigins: string[]): (origin: string) => boolean {
+  const explicit = new Set<string>();
+  for (const raw of appOrigins) {
+    const normalized = normalizeOrigin(raw);
+    if (normalized) 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);
+  };
+}
+
+/**
+ * Create a strict Oxy CORS middleware. See module docs.
+ *
+ * @example
+ * ```ts
+ * app.use(createOxyCors({ appOrigins: ['https://app.example.com'] }));
+ * ```
+ */
+export function createOxyCors(options: OxyCorsOptions = {}): RequestHandler {
+  const {
+    appOrigins = [],
+    allowCredentials = true,
+    methods = DEFAULT_ALLOWED_METHODS,
+    allowedHeaders = DEFAULT_ALLOWED_HEADERS,
+    exposedHeaders = [],
+    maxAgeSeconds = DEFAULT_MAX_AGE_SECONDS,
+  } = options;
+
+  const isOriginAllowed = buildOriginAllowed(appOrigins);
+  const methodsHeader = methods.join(', ');
+  const allowedHeadersHeader = allowedHeaders.join(', ');
+  const exposedHeadersHeader = exposedHeaders.join(', ');
+
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const origin = req.headers.origin;
+
+    // Same-origin or non-browser requests carry no Origin header — pass through
+    // untouched (no ACAO header is emitted, which is correct for them).
+    if (typeof origin !== 'string' || origin.length === 0) {
+      if (req.method === 'OPTIONS') {
+        res.sendStatus(204);
+        return;
+      }
+      next();
+      return;
+    }
+
+    // Origin is present. Caching correctness: this response varies by Origin.
+    res.setHeader('Vary', 'Origin');
+
+    if (!isOriginAllowed(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).
+      if (req.method === 'OPTIONS') {
+        res.sendStatus(204);
+        return;
+      }
+      next();
+      return;
+    }
+
+    // ALLOW: echo the EXACT matched origin — never `*`, even without credentials.
+    res.setHeader('Access-Control-Allow-Origin', origin);
+    if (allowCredentials) {
+      res.setHeader('Access-Control-Allow-Credentials', 'true');
+    }
+    if (exposedHeadersHeader) {
+      res.setHeader('Access-Control-Expose-Headers', exposedHeadersHeader);
+    }
+
+    if (req.method === 'OPTIONS') {
+      res.setHeader('Access-Control-Allow-Methods', methodsHeader);
+      // Honour the browser's requested headers when present, else the default set.
+      const requested = req.headers['access-control-request-headers'];
+      res.setHeader(
+        'Access-Control-Allow-Headers',
+        typeof requested === 'string' && requested.length > 0 ? requested : allowedHeadersHeader,
+      );
+      res.setHeader('Access-Control-Max-Age', String(maxAgeSeconds));
+      res.sendStatus(204);
+      return;
+    }
+
+    next();
+  };
+}

package/src/server/index.ts

@@ -34,3 +34,33 @@ export type {
 } from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';
+
+// SSRF-safe upstream fetch + URL validation (Node-only).
+export {
+  assertSafePublicUrl,
+  isBlockedIp,
+  safeFetch,
+  SsrfRejection,
+  UpstreamError,
+  ALLOWED_PORTS,
+  ALLOWED_PROTOCOLS,
+  BLOCKED_HOSTNAMES,
+  DEFAULT_USER_AGENT,
+  MAX_REDIRECTS,
+  MAX_URL_LENGTH,
+  UPSTREAM_HEADERS_TIMEOUT_MS,
+} from './safeFetch';
+export type {
+  SafeFetchOptions,
+  SafeFetchResult,
+  SsrfCheckFail,
+  SsrfCheckOk,
+  SsrfCheckResult,
+} from './safeFetch';
+
+// Strict CORS allowlist (Oxy apex family + explicit app origins).
+export { createOxyCors } from './cors';
+export type { OxyCorsOptions } from './cors';
+
+// Constant-time secret comparison.
+export { verifySecret } from './verifySecret';