@oxyhq/core 12.7.0 → 12.8.0

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -1,5 +1,6 @@
 import type { ApiError, User } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
+import { type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
 /**
  * Result from the service-acting-as verification endpoint.
  * Confirms that a given service app holds an active delegation grant for
@@ -28,6 +29,8 @@ export interface ServiceApp {
     scopes: string[];
     /** The credentialId of the specific service credential that minted this token. */
     credentialId: string;
+    /** Test/live isolation (F2.0): which `ApplicationCredential.environment` minted this token. */
+    environment: OxyServiceEnvironment;
 }
 /**
  * Options for oxyClient.auth() middleware

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

@@ -1,5 +1,8 @@
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import type { OxyServices } from '../OxyServices';
+import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
+export { OXY_SERVICE_ENVIRONMENTS };
+export type { OxyServiceEnvironment };
 export interface OxyRequestUser {
     id: string;
     _id?: string;
@@ -13,6 +16,7 @@ export interface OxyServiceAppContext {
     appName: string;
     scopes: string[];
     credentialId: string;
+    environment: OxyServiceEnvironment;
 }
 export interface OxyServiceActingAsContext {
     userId: string;

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

@@ -14,8 +14,8 @@
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * ```
  */
-export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, } from './auth';
-export type { OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, } from './auth';
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
+export type { OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, OxyServiceEnvironment, } 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';

package/dist/types/utils/oxyServiceEnvironment.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Environment segregation for Oxy service-token JWTs (test/live isolation).
+ * Mirrors `ApplicationCredentialEnvironment` on the API's `ApplicationCredential`
+ * model (`packages/api/src/models/ApplicationCredential.ts`) as an INDEPENDENT
+ * literal union — `@oxyhq/core` has zero dependency on `@oxyhq/api`, so this is
+ * kept in sync by hand, not by import.
+ *
+ * Defined here (not in `server/auth.ts` or `mixins/OxyServices.utility.ts`
+ * directly) because BOTH of those files need it and neither may import from
+ * the other: `server/` types import `express` (Node-only, a peer dependency
+ * `mixins/` deliberately avoids so it stays safe to bundle into RN/browser
+ * consumers — see the "Local request/response/socket typing" comment in
+ * `OxyServices.utility.ts`). This file has zero imports, so both sides can
+ * depend on it without crossing that boundary.
+ */
+export declare const OXY_SERVICE_ENVIRONMENTS: readonly ["development", "staging", "production"];
+export type OxyServiceEnvironment = (typeof OXY_SERVICE_ENVIRONMENTS)[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.7.0",
+  "version": "12.8.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/mixins/OxyServices.utility.ts

@@ -12,6 +12,7 @@ import { loadNodeCrypto } from '@oxyhq/protocol';
 import { buildUrl } from '../utils/apiUtils';
 import { logger } from '../logger';
 import { CACHE_TIMES } from './mixinHelpers';
+import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
 
 interface JwtPayload {
   exp?: number;
@@ -25,6 +26,7 @@ interface JwtPayload {
   scopes?: string[];
   aud?: string | string[];
   iss?: string;
+  environment?: string;
   [key: string]: unknown;
 }
 
@@ -57,6 +59,8 @@ export interface ServiceApp {
   scopes: string[];
   /** The credentialId of the specific service credential that minted this token. */
   credentialId: string;
+  /** Test/live isolation (F2.0): which `ApplicationCredential.environment` minted this token. */
+  environment: OxyServiceEnvironment;
 }
 
 /**
@@ -94,6 +98,13 @@ class ServiceTokenClaimError extends Error {
   }
 }
 
+function isOxyServiceEnvironment(value: unknown): value is OxyServiceEnvironment {
+  return (
+    typeof value === 'string' &&
+    (OXY_SERVICE_ENVIRONMENTS as readonly string[]).includes(value)
+  );
+}
+
 /**
  * Options for oxyClient.auth() middleware
  */
@@ -459,7 +470,13 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             // Validate required service token fields
             const appId = decoded.appId;
             const credentialId = decoded.credentialId;
-            if (!appId || typeof credentialId !== 'string' || credentialId.length === 0) {
+            const environment = decoded.environment;
+            if (
+              !appId ||
+              typeof credentialId !== 'string' ||
+              credentialId.length === 0 ||
+              !isOxyServiceEnvironment(environment)
+            ) {
               if (optional) {
                 req.userId = null;
                 req.user = null;
@@ -513,6 +530,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               appName: decoded.appName || 'unknown',
               credentialId,
               scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
+              environment,
             };
 
             if (debug) {

package/src/mixins/__tests__/serviceAuth.test.ts

@@ -30,6 +30,7 @@ interface ServiceTokenClaims {
   scopes?: string[];
   aud?: string | string[];
   iss?: string;
+  environment?: string;
   exp?: number;
   iat?: number;
   [key: string]: unknown;
@@ -49,6 +50,7 @@ const signServiceToken = (claims: ServiceTokenClaims, secret: string): string =>
     aud: 'oxy-api',
     iss: 'oxy-auth',
     credentialId: 'cred-1',
+    environment: 'production',
     ...claims,
   };
   const headerB64 = b64url(JSON.stringify(header));
@@ -183,6 +185,7 @@ describe('C3: service-token acting-as enforcement', () => {
       appName: 'trusted-service',
       credentialId: 'cred-1',
       scopes: ['user:read'],
+      environment: 'production',
     });
   });
 
@@ -762,3 +765,65 @@ describe('requireScope() middleware', () => {
     expect(() => oxy.requireScope(undefined as unknown as string)).toThrow('requireScope');
   });
 });
+
+// ---------------------------------------------------------------------------
+// service-token environment claim (F2.0 task 1b) — test/live isolation.
+// ---------------------------------------------------------------------------
+
+describe('service-token environment claim (F2.0 task 1b)', () => {
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+  });
+
+  it('populates req.serviceApp.environment from the token claim', async () => {
+    const token = signServiceToken(
+      { appId: 'app-1', appName: 'svc', environment: 'development' },
+      SERVICE_SECRET,
+    );
+    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
+    const res = makeRes();
+    const next = jest.fn();
+
+    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
+    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(req.serviceApp).toMatchObject({ appId: 'app-1', environment: 'development' });
+  });
+
+  it('rejects a service token missing the environment claim (401)', async () => {
+    const token = signServiceToken(
+      { appId: 'app-1', appName: 'svc', environment: undefined },
+      SERVICE_SECRET,
+    );
+    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
+    const res = makeRes();
+    const next = jest.fn();
+
+    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
+    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
+  });
+
+  it('rejects a service token with an environment value outside the known set (401)', async () => {
+    const token = signServiceToken(
+      { appId: 'app-1', appName: 'svc', environment: 'bogus' },
+      SERVICE_SECRET,
+    );
+    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
+    const res = makeRes();
+    const next = jest.fn();
+
+    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
+    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
+  });
+});

package/src/server/auth.ts

@@ -1,5 +1,9 @@
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import type { OxyServices } from '../OxyServices';
+import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
+
+export { OXY_SERVICE_ENVIRONMENTS };
+export type { OxyServiceEnvironment };
 
 export interface OxyRequestUser {
   id: string;
@@ -15,6 +19,7 @@ export interface OxyServiceAppContext {
   appName: string;
   scopes: string[];
   credentialId: string;
+  environment: OxyServiceEnvironment;
 }
 
 export interface OxyServiceActingAsContext {

package/src/server/index.ts

@@ -22,6 +22,7 @@ export {
   getRequiredOxyUserId,
   isOxyAuthenticated,
   requireOxyAuth,
+  OXY_SERVICE_ENVIRONMENTS,
 } from './auth';
 export type {
   OxyAuthenticatedRequest,
@@ -30,6 +31,7 @@ export type {
   OxyRequestUser,
   OxyServiceActingAsContext,
   OxyServiceAppContext,
+  OxyServiceEnvironment,
 } from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';

package/src/utils/__tests__/oxyServiceEnvironment.test.ts

@@ -0,0 +1,7 @@
+import { OXY_SERVICE_ENVIRONMENTS } from '../oxyServiceEnvironment';
+
+describe('OXY_SERVICE_ENVIRONMENTS', () => {
+  it('lists exactly development, staging, production, in that order', () => {
+    expect(OXY_SERVICE_ENVIRONMENTS).toEqual(['development', 'staging', 'production']);
+  });
+});

package/src/utils/oxyServiceEnvironment.ts

@@ -0,0 +1,17 @@
+/**
+ * Environment segregation for Oxy service-token JWTs (test/live isolation).
+ * Mirrors `ApplicationCredentialEnvironment` on the API's `ApplicationCredential`
+ * model (`packages/api/src/models/ApplicationCredential.ts`) as an INDEPENDENT
+ * literal union — `@oxyhq/core` has zero dependency on `@oxyhq/api`, so this is
+ * kept in sync by hand, not by import.
+ *
+ * Defined here (not in `server/auth.ts` or `mixins/OxyServices.utility.ts`
+ * directly) because BOTH of those files need it and neither may import from
+ * the other: `server/` types import `express` (Node-only, a peer dependency
+ * `mixins/` deliberately avoids so it stays safe to bundle into RN/browser
+ * consumers — see the "Local request/response/socket typing" comment in
+ * `OxyServices.utility.ts`). This file has zero imports, so both sides can
+ * depend on it without crossing that boundary.
+ */
+export const OXY_SERVICE_ENVIRONMENTS = ['development', 'staging', 'production'] as const;
+export type OxyServiceEnvironment = (typeof OXY_SERVICE_ENVIRONMENTS)[number];