@oxy.so/core 7.21.1 → 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/api/billing.js

@@ -20,8 +20,9 @@ class BillingApi {
     constructor(ctx) {
         this.ctx = ctx;
     }
-    async renewProductSubscription(request) {
-        return (0, client_1.parseContract)(client_1.personalPlanCheckoutResultCheck, await this.ctx.request('POST', '/billing/product-subscriptions/renew', (0, client_1.parseContract)(client_1.productSubscriptionRenewalRequestCheck, request), { cache: false }));
+    /** The payment provider's customer portal for one named source the caller pays for. */
+    async openProductSubscriptionPortal(request) {
+        return (0, client_1.parseContract)(client_1.productSubscriptionPortalResponseCheck, await this.ctx.request('POST', '/billing/product-subscriptions/portal', (0, client_1.parseContract)(client_1.productSubscriptionPortalRequestCheck, request), { cache: false }));
     }
     async startProductPlanCheckout(request) {
         return (0, client_1.parseContract)(client_1.personalPlanCheckoutResultCheck, await this.ctx.request('POST', '/billing/checkout/product-plan', (0, client_1.parseContract)(client_1.productPlanCheckoutRequestCheck, request), { cache: false }));

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/api/billing.js

@@ -9,7 +9,7 @@
  * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
  * arrive as ISO-8601 strings.
  */
-import { cancelProductSubscriptionCheck, parseContract, personalPlanCatalogueCheck, personalPlanCheckoutRequestCheck, personalPlanCheckoutResultCheck, productPlanCatalogueCheck, productPlanCheckoutRequestCheck, productSubscriptionCancellationResultCheck, productSubscriptionRenewalRequestCheck, productSubscriptionsResponseCheck, subjectProductAccessCheck, subjectProductAccessQueryCheck, subscriptionCreditGrantsResponseCheck, } from '@oxy.so/contracts/client';
+import { cancelProductSubscriptionCheck, parseContract, personalPlanCatalogueCheck, personalPlanCheckoutRequestCheck, personalPlanCheckoutResultCheck, productPlanCatalogueCheck, productPlanCheckoutRequestCheck, productSubscriptionCancellationResultCheck, productSubscriptionPortalRequestCheck, productSubscriptionPortalResponseCheck, productSubscriptionsResponseCheck, subjectProductAccessCheck, subjectProductAccessQueryCheck, subscriptionCreditGrantsResponseCheck, } from '@oxy.so/contracts/client';
 const enc = encodeURIComponent;
 const SUBSCRIPTION_TTL = 2 * 60 * 1000;
 const WALLET_TTL = 60 * 1000;
@@ -17,8 +17,9 @@ export class BillingApi {
     constructor(ctx) {
         this.ctx = ctx;
     }
-    async renewProductSubscription(request) {
-        return parseContract(personalPlanCheckoutResultCheck, await this.ctx.request('POST', '/billing/product-subscriptions/renew', parseContract(productSubscriptionRenewalRequestCheck, request), { cache: false }));
+    /** The payment provider's customer portal for one named source the caller pays for. */
+    async openProductSubscriptionPortal(request) {
+        return parseContract(productSubscriptionPortalResponseCheck, await this.ctx.request('POST', '/billing/product-subscriptions/portal', parseContract(productSubscriptionPortalRequestCheck, request), { cache: false }));
     }
     async startProductPlanCheckout(request) {
         return parseContract(personalPlanCheckoutResultCheck, await this.ctx.request('POST', '/billing/checkout/product-plan', parseContract(productPlanCheckoutRequestCheck, request), { cache: false }));

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/api/billing.d.ts

@@ -9,7 +9,7 @@
  * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
  * arrive as ISO-8601 strings.
  */
-import type { PersonalPlanCatalogue, PersonalPlanCheckoutRequest, PersonalPlanCheckoutResult, ProductPlanCatalogue, ProductPlanCheckoutRequest, ProductSubscriptionCancellationResult, ProductSubscriptionRenewalRequest, ProductSubscriptionSummary, SubjectProductAccess, SubjectProductAccessQuery, SubscriptionCreditGrant } from '@oxy.so/contracts';
+import type { PersonalPlanCatalogue, PersonalPlanCheckoutRequest, PersonalPlanCheckoutResult, ProductPlanCatalogue, ProductPlanCheckoutRequest, ProductSubscriptionCancellationResult, ProductSubscriptionPortalRequest, ProductSubscriptionPortalResponse, ProductSubscriptionSummary, SubjectProductAccess, SubjectProductAccessQuery, SubscriptionCreditGrant } from '@oxy.so/contracts';
 import type { OxyContext } from '../client/context';
 /** Subscription tier. */
 export type SubscriptionPlan = 'basic' | 'pro' | 'business';
@@ -98,7 +98,8 @@ export interface WalletTransactionsPage {
 export declare class BillingApi {
     protected readonly ctx: OxyContext;
     constructor(ctx: OxyContext);
-    renewProductSubscription(request: ProductSubscriptionRenewalRequest): Promise<PersonalPlanCheckoutResult>;
+    /** The payment provider's customer portal for one named source the caller pays for. */
+    openProductSubscriptionPortal(request: ProductSubscriptionPortalRequest): Promise<ProductSubscriptionPortalResponse>;
     startProductPlanCheckout(request: ProductPlanCheckoutRequest): Promise<PersonalPlanCheckoutResult>;
     productPlans(productId: string): Promise<ProductPlanCatalogue>;
     startPersonalPlanCheckout(request: PersonalPlanCheckoutRequest): Promise<PersonalPlanCheckoutResult>;

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.21.1",
+  "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",
@@ -181,7 +181,7 @@
   "dependencies": {
     "@noble/ciphers": "^2.4.0",
     "@noble/hashes": "^2.4.0",
-    "@oxy.so/contracts": "6.8.0",
+    "@oxy.so/contracts": "6.9.0",
     "@oxy.so/protocol": "^1.6.1",
     "@oxy.so/telemetry": "^2.1.0",
     "@scure/bip39": "^2.4.0",

package/src/api/billing.ts

@@ -17,7 +17,8 @@ import type {
   ProductPlanCatalogue,
   ProductPlanCheckoutRequest,
   ProductSubscriptionCancellationResult,
-  ProductSubscriptionRenewalRequest,
+  ProductSubscriptionPortalRequest,
+  ProductSubscriptionPortalResponse,
   ProductSubscriptionSummary,
   SubjectProductAccess,
   SubjectProductAccessQuery,
@@ -32,7 +33,8 @@ import {
   productPlanCatalogueCheck,
   productPlanCheckoutRequestCheck,
   productSubscriptionCancellationResultCheck,
-  productSubscriptionRenewalRequestCheck,
+  productSubscriptionPortalRequestCheck,
+  productSubscriptionPortalResponseCheck,
   productSubscriptionsResponseCheck,
   subjectProductAccessCheck,
   subjectProductAccessQueryCheck,
@@ -136,15 +138,16 @@ export interface WalletTransactionsPage {
 export class BillingApi {
   constructor(protected readonly ctx: OxyContext) {}
 
-  async renewProductSubscription(
-    request: ProductSubscriptionRenewalRequest,
-  ): Promise<PersonalPlanCheckoutResult> {
+  /** The payment provider's customer portal for one named source the caller pays for. */
+  async openProductSubscriptionPortal(
+    request: ProductSubscriptionPortalRequest,
+  ): Promise<ProductSubscriptionPortalResponse> {
     return parseContract(
-      personalPlanCheckoutResultCheck,
+      productSubscriptionPortalResponseCheck,
       await this.ctx.request<unknown>(
         'POST',
-        '/billing/product-subscriptions/renew',
-        parseContract(productSubscriptionRenewalRequestCheck, request),
+        '/billing/product-subscriptions/portal',
+        parseContract(productSubscriptionPortalRequestCheck, request),
         { cache: false },
       ),
     );

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