@oxy.so/core 7.22.0 → 7.23.0

package/README.md

@@ -31,7 +31,7 @@ The package exposes two public entry points:
 - `@oxy.so/core/session` — `SessionClient`, the account dialog controller, auth-state stores, cold boot
 - `@oxy.so/core/crypto` — `KeyManager`, `SignatureService`, `RecoveryPhraseService` and the primitives under them
 - `@oxy.so/core/civic`, `@oxy.so/core/inference`, `@oxy.so/core/logger`
-- `@oxy.so/core/server` — `OxyServer` (workload service tokens, `middleware.*`, `withUser` / `asUser`, `appPermissionsFor`, `accountAccessFor`, `applicationAccessFor`) and the Express helpers (`createOxyRateLimit`, `createOxyAuthMiddleware`, `getOxyUserId`, `getRequiredOxyUserId`, `createOxyCors`, `createOxySocketCors`, `createOxySecurityHeaders`, `buildOxyCspDirectives`, `safeFetch`, `verifySecret`, and request types)
+- `@oxy.so/core/server` — `OxyServer` (workload service tokens, `middleware.*`, `withUser` / `asUser`, `isFirstPartyServiceUrl`, `appPermissionsFor`, `accountAccessFor`, `applicationAccessFor`) and the Express helpers (`createOxyRateLimit`, `createOxyAuthMiddleware`, `getOxyUserId`, `getRequiredOxyUserId`, `createOxyCors`, `createOxySocketCors`, `createOxySecurityHeaders`, `buildOxyCspDirectives`, `safeFetch`, `verifySecret`, and request types)
 
 Heavy pieces have their own entries so an app ships only what it uses; React Native and browser bundles never import Express. The full API map is [docs/api.mdx](./docs/api.mdx).
 

package/dist/cjs/server/OxyServer.js

@@ -49,6 +49,7 @@ const OxyServices_1 = require("../OxyServices");
 const HttpService_1 = require("../HttpService");
 const authenticatedFetch_1 = require("../authenticatedFetch");
 const requestSignal_1 = require("../utils/requestSignal");
+const officialOrigins_1 = require("../utils/officialOrigins");
 const errorUtils_1 = require("../utils/errorUtils");
 const logger_1 = require("../logger");
 const workloadIdentity_1 = require("./workloadIdentity");
@@ -193,6 +194,34 @@ class OxyServer extends OxyServices_1.OxyServices {
             applicationAccessFor: (req, applicationId, options) => this.applicationAccessFor(req, applicationId, options),
         });
     }
+    /**
+     * Whether `url` names Oxy's own API — the first-party service this server is
+     * configured for (`baseURL`), when that origin is an official Oxy origin.
+     *
+     * For a URL a caller chose (a customer webhook endpoint, say) that may name
+     * Oxy itself: `true` sends it through this server
+     * (`createServiceClient({ baseURL: oxy.baseURL, audience: 'oxy-api' }).fetch`),
+     * `false` through `safeFetch`. Inside the VPC `api.oxy.so` resolves to a
+     * private address, which `safeFetch` refuses by design.
+     *
+     * The comparison is by exact origin (scheme, host and port): a look-alike
+     * (`api.oxy.so.evil.com`), another official host, a credential-carrying URL
+     * or anything unparseable is `false`, and so goes on to `safeFetch`'s
+     * checks. Never decide first-party by hostname suffix or branding.
+     */
+    isFirstPartyServiceUrl(url) {
+        let target;
+        try {
+            target = new URL(String(url));
+        }
+        catch {
+            return false;
+        }
+        if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password)
+            return false;
+        const own = new URL(this.baseURL).origin;
+        return target.origin === own && (0, officialOrigins_1.isOfficialWebOrigin)(own);
+    }
     /** A product SDK transport authenticated only by this process's workload. */
     createServiceClient(options) {
         const origin = new URL(options.baseURL);

package/dist/esm/server/OxyServer.js

@@ -46,6 +46,7 @@ import { OxyServices } from '../OxyServices.js';
 import { HttpService } from '../HttpService.js';
 import { createAuthenticatedFetch } from '../authenticatedFetch.js';
 import { awaitRequestSignal } from '../utils/requestSignal.js';
+import { isOfficialWebOrigin } from '../utils/officialOrigins.js';
 import { createCancelledError, extractErrorStatus } from '../utils/errorUtils.js';
 import { logger } from '../logger/index.js';
 import { canAttestWorkloadIdentity, requestWorkloadServiceToken, } from './workloadIdentity.js';
@@ -189,6 +190,34 @@ export class OxyServer extends OxyServices {
             applicationAccessFor: (req, applicationId, options) => this.applicationAccessFor(req, applicationId, options),
         });
     }
+    /**
+     * Whether `url` names Oxy's own API — the first-party service this server is
+     * configured for (`baseURL`), when that origin is an official Oxy origin.
+     *
+     * For a URL a caller chose (a customer webhook endpoint, say) that may name
+     * Oxy itself: `true` sends it through this server
+     * (`createServiceClient({ baseURL: oxy.baseURL, audience: 'oxy-api' }).fetch`),
+     * `false` through `safeFetch`. Inside the VPC `api.oxy.so` resolves to a
+     * private address, which `safeFetch` refuses by design.
+     *
+     * The comparison is by exact origin (scheme, host and port): a look-alike
+     * (`api.oxy.so.evil.com`), another official host, a credential-carrying URL
+     * or anything unparseable is `false`, and so goes on to `safeFetch`'s
+     * checks. Never decide first-party by hostname suffix or branding.
+     */
+    isFirstPartyServiceUrl(url) {
+        let target;
+        try {
+            target = new URL(String(url));
+        }
+        catch {
+            return false;
+        }
+        if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password)
+            return false;
+        const own = new URL(this.baseURL).origin;
+        return target.origin === own && isOfficialWebOrigin(own);
+    }
     /** A product SDK transport authenticated only by this process's workload. */
     createServiceClient(options) {
         const origin = new URL(options.baseURL);

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

@@ -196,6 +196,22 @@ export declare class OxyServer extends OxyServices {
      */
     readonly middleware: OxyMiddleware;
     constructor(config: OxyServerConfig);
+    /**
+     * Whether `url` names Oxy's own API — the first-party service this server is
+     * configured for (`baseURL`), when that origin is an official Oxy origin.
+     *
+     * For a URL a caller chose (a customer webhook endpoint, say) that may name
+     * Oxy itself: `true` sends it through this server
+     * (`createServiceClient({ baseURL: oxy.baseURL, audience: 'oxy-api' }).fetch`),
+     * `false` through `safeFetch`. Inside the VPC `api.oxy.so` resolves to a
+     * private address, which `safeFetch` refuses by design.
+     *
+     * The comparison is by exact origin (scheme, host and port): a look-alike
+     * (`api.oxy.so.evil.com`), another official host, a credential-carrying URL
+     * or anything unparseable is `false`, and so goes on to `safeFetch`'s
+     * checks. Never decide first-party by hostname suffix or branding.
+     */
+    isFirstPartyServiceUrl(url: string | URL): boolean;
     /** A product SDK transport authenticated only by this process's workload. */
     createServiceClient(options: ServiceClientOptions): ServiceHttpClient;
     /** Live service authority; human sessions and keys have a separate resource contract. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.22.0",
+  "version": "7.23.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/server/OxyServer.ts

@@ -66,6 +66,7 @@ import { OxyServices, type OxyConfig } from '../OxyServices';
 import { HttpService } from '../HttpService';
 import { createAuthenticatedFetch } from '../authenticatedFetch';
 import { awaitRequestSignal } from '../utils/requestSignal';
+import { isOfficialWebOrigin } from '../utils/officialOrigins';
 import { createCancelledError, extractErrorStatus } from '../utils/errorUtils';
 import type { HttpMethod, ServiceLane } from '../client/context';
 import type { RequestOptions, ResponsePayload } from '../HttpService';
@@ -410,6 +411,34 @@ export class OxyServer extends OxyServices {
     });
   }
 
+  /**
+   * Whether `url` names Oxy's own API — the first-party service this server is
+   * configured for (`baseURL`), when that origin is an official Oxy origin.
+   *
+   * For a URL a caller chose (a customer webhook endpoint, say) that may name
+   * Oxy itself: `true` sends it through this server
+   * (`createServiceClient({ baseURL: oxy.baseURL, audience: 'oxy-api' }).fetch`),
+   * `false` through `safeFetch`. Inside the VPC `api.oxy.so` resolves to a
+   * private address, which `safeFetch` refuses by design.
+   *
+   * The comparison is by exact origin (scheme, host and port): a look-alike
+   * (`api.oxy.so.evil.com`), another official host, a credential-carrying URL
+   * or anything unparseable is `false`, and so goes on to `safeFetch`'s
+   * checks. Never decide first-party by hostname suffix or branding.
+   */
+  isFirstPartyServiceUrl(url: string | URL): boolean {
+    let target: URL;
+    try {
+      target = new URL(String(url));
+    } catch {
+      return false;
+    }
+    if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password)
+      return false;
+    const own = new URL(this.baseURL).origin;
+    return target.origin === own && isOfficialWebOrigin(own);
+  }
+
   /** A product SDK transport authenticated only by this process's workload. */
   createServiceClient(options: ServiceClientOptions): ServiceHttpClient {
     const origin = new URL(options.baseURL);