@oxyhq/core 3.9.0 → 3.10.0

package/dist/types/server/cors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 { RequestHandler } from 'express';
+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;
+}
+/**
+ * Create a strict Oxy CORS middleware. See module docs.
+ *
+ * @example
+ * ```ts
+ * app.use(createOxyCors({ appOrigins: ['https://app.example.com'] }));
+ * ```
+ */
+export declare function createOxyCors(options?: OxyCorsOptions): RequestHandler;

package/dist/types/server/index.d.ts

@@ -18,3 +18,8 @@ export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequir
 export type { OxyActingAsContext, OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, } from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';
+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';
+export { createOxyCors } from './cors';
+export type { OxyCorsOptions } from './cors';
+export { verifySecret } from './verifySecret';

package/dist/types/server/safeFetch.d.ts

@@ -0,0 +1,135 @@
+/**
+ * SSRF-safe upstream HTTP fetch for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Every Oxy backend that contacts a caller-influenced URL — media proxies,
+ * the website MCP image upload/debug tools, federated fetches, link
+ * unfurlers — needs the exact same Server-Side Request Forgery (SSRF)
+ * defence. Apps were re-implementing it (or worse, omitting it), so the
+ * gold-standard primitive (originally `packages/backend/src/utils` in
+ * Mention) lives here ONCE.
+ *
+ * THE CONTRACT
+ * ------------
+ *  - Every URL — including each redirect hop — is validated by
+ *    {@link assertSafePublicUrl}: a real DNS resolution plus a denylist of
+ *    private/reserved/metadata ranges (10/8, 127/8, 169.254.169.254, ::1, …).
+ *  - The TCP connection is PINNED to the validated IP via a custom `lookup`,
+ *    closing the DNS-rebind TOCTOU window — DNS is NOT re-resolved at connect
+ *    time, so the address we validated is exactly the address Node connects to.
+ *  - Redirects are followed manually (bounded) so every hop is re-validated and
+ *    redirect bodies (potentially unbounded) are destroyed, not drained.
+ *
+ * Node-only: this module imports `node:http`/`node:https`/`node:dns` and is
+ * exported solely from `@oxyhq/core/server`. It MUST NOT be reachable from the
+ * browser `@oxyhq/core` entry.
+ */
+import { type IncomingMessage, type IncomingHttpHeaders } from 'node:http';
+/** Maximum accepted length of an input URL (DoS guard). */
+export declare const MAX_URL_LENGTH = 2048;
+/** The only network ports a safe fetch is allowed to reach upstream. */
+export declare const ALLOWED_PORTS: ReadonlySet<number>;
+/** Protocols a safe fetch is allowed to contact. */
+export declare const ALLOWED_PROTOCOLS: ReadonlySet<string>;
+/**
+ * Time-to-first-byte deadline: how long to wait for the upstream to establish
+ * the connection and send its RESPONSE HEADERS before aborting. Enforced via
+ * `req.setTimeout` on the `ClientRequest`; once headers arrive, the caller owns
+ * the (longer) streaming lifetime of the response body.
+ */
+export declare const UPSTREAM_HEADERS_TIMEOUT_MS = 8000;
+/** Maximum number of HTTP redirects to follow; each hop is re-validated. */
+export declare const MAX_REDIRECTS = 5;
+/** Default User-Agent presented to upstreams when the caller does not set one. */
+export declare const DEFAULT_USER_AGENT = "OxyServices/1.0 (+https://oxy.so)";
+/** Hostnames that must never be resolved or contacted, regardless of DNS. */
+export declare const BLOCKED_HOSTNAMES: ReadonlySet<string>;
+export interface SsrfCheckOk {
+    ok: true;
+    /** The validated literal IP the caller MUST connect to. */
+    ip: string;
+    /** IP family of the validated address (4 or 6). */
+    family: 4 | 6;
+}
+export interface SsrfCheckFail {
+    ok: false;
+    /** Human-readable, non-sensitive reason (safe to log; not echoed to clients). */
+    reason: string;
+}
+export type SsrfCheckResult = SsrfCheckOk | SsrfCheckFail;
+/**
+ * Return true if a literal IP address is private/loopback/link-local/reserved/
+ * multicast/metadata and therefore must NOT be contacted.
+ */
+export declare function isBlockedIp(rawIp: string): boolean;
+/**
+ * Validate that a URL is syntactically a public http(s) URL and that its
+ * hostname resolves ONLY to non-blocked, public IP addresses.
+ *
+ * On success, returns the single validated IP (the first allowed record) that
+ * the HTTP client MUST pin its connection to. Every resolved address is checked;
+ * if ANY resolves into a blocked range the URL is rejected (an attacker
+ * controlling a multi-record DNS response cannot smuggle one internal IP past
+ * the check).
+ *
+ * Re-run this on EVERY redirect hop so a public hostname cannot redirect (or
+ * DNS-rebind) into an internal address.
+ */
+export declare function assertSafePublicUrl(rawUrl: string): Promise<SsrfCheckResult>;
+/** Marker error for a blocked SSRF target (map to 403 at the route layer). */
+export declare class SsrfRejection extends Error {
+    constructor(reason: string);
+}
+/** Marker error for a generic upstream failure (map to 502 at the route layer). */
+export declare class UpstreamError extends Error {
+    constructor(reason: string);
+}
+/** Options for {@link safeFetch}. */
+export interface SafeFetchOptions {
+    /** HTTP method. Defaults to `GET`. */
+    method?: string;
+    /** Extra request headers. A `User-Agent` is added if none is provided. */
+    headers?: Record<string, string>;
+    /**
+     * Maximum number of redirects to follow (each re-validated). Defaults to
+     * {@link MAX_REDIRECTS}. Set to `0` to disallow redirects.
+     */
+    maxRedirects?: number;
+    /**
+     * Time-to-first-byte deadline in milliseconds (connect + response headers).
+     * Defaults to {@link UPSTREAM_HEADERS_TIMEOUT_MS}.
+     */
+    headersTimeoutMs?: number;
+    /**
+     * Optional external abort signal. When it fires the in-flight request is
+     * destroyed.
+     */
+    signal?: AbortSignal;
+}
+/** The validated, non-redirect response returned by {@link safeFetch}. */
+export interface SafeFetchResult {
+    /**
+     * The first non-redirect response. The caller OWNS draining/destroying this
+     * stream (stream it to the client, or buffer a bounded prefix, then destroy).
+     */
+    response: IncomingMessage;
+    /** The HTTP status code of the response. */
+    status: number;
+    /** Response headers. */
+    headers: IncomingHttpHeaders;
+    /** The final, post-redirect URL that produced the response. */
+    finalUrl: string;
+}
+/**
+ * SSRF-safe HTTP(S) fetch. Validates the URL (and every redirect hop) against
+ * the private/metadata-range denylist, pins the connection to the validated IP,
+ * follows a bounded number of redirects (destroying redirect bodies), and
+ * returns the first non-redirect response.
+ *
+ * The caller owns the returned response stream — drain or destroy it.
+ *
+ * @throws {SsrfRejection} when any hop targets a blocked address/host/port.
+ * @throws {UpstreamError} on redirect-loop / malformed-redirect / timeout.
+ */
+export declare function safeFetch(rawUrl: string, options?: SafeFetchOptions): Promise<SafeFetchResult>;

package/dist/types/server/verifySecret.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Constant-time secret comparison for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Backends kept comparing secrets with `provided !== EXPECTED`. A plain `===`/
+ * `!==` short-circuits on the first differing byte, leaking timing information
+ * an attacker can use to recover a secret byte-by-byte. This helper performs a
+ * constant-time comparison via `crypto.timingSafeEqual`, guarded by a length
+ * check, and never throws — replacing the `token !== SECRET` pattern (Alia
+ * docker-host / integrations webhook secrets, internal webhook bearers, etc.).
+ *
+ * Node-only (`node:crypto`); exported solely from `@oxyhq/core/server`.
+ */
+/**
+ * Compare two secrets in constant time.
+ *
+ * Returns `true` iff both are non-empty strings of equal byte length with
+ * identical contents. Returns `false` — without throwing — when either value is
+ * not a string, when lengths differ, or when contents differ.
+ *
+ * The length-equality guard is required because `crypto.timingSafeEqual` throws
+ * on unequal-length buffers; comparing lengths first leaks only the LENGTH of
+ * the expected secret (already low-value / often public), never its bytes.
+ *
+ * @param provided - The untrusted, caller-supplied value (e.g. a request token).
+ * @param expected - The trusted secret to compare against.
+ */
+export declare function verifySecret(provided: string, expected: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -80,6 +80,7 @@
     "typescript": "tsc --noEmit",
     "test": "jest --passWithNoTests",
     "lint": "biome lint --error-on-warnings ./src",
+    "prepublishOnly": "bun run clean && bun run build",
     "release": "rm -rf dist && bun run build && release-it"
   },
   "release-it": {
@@ -97,7 +98,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.2.0",
+    "@oxyhq/contracts": "^0.2.1",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",

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

@@ -0,0 +1,144 @@
+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('@oxyhq/core/server createOxyCors', () => {
+  it('allows the Oxy apex family (apex + any subdomain) 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',
+    ]) {
+      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('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();
+  });
+});

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);
+  });
+});