@oxyhq/core 19.1.2 → 20.1.0

package/src/mixins/index.ts

@@ -17,6 +17,7 @@ import { OxyServicesReputationMixin } from './OxyServices.reputation';
 import { OxyServicesAssetsMixin } from './OxyServices.assets';
 import { OxyServicesAccountsMixin } from './OxyServices.accounts';
 import { OxyServicesConnectedAppsMixin } from './OxyServices.connectedApps';
+import { OxyServicesStoreMixin } from './OxyServices.store';
 import { OxyServicesLocationMixin } from './OxyServices.location';
 import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
 import { OxyServicesDevicesMixin } from './OxyServices.devices';
@@ -28,6 +29,7 @@ import { OxyServicesContactsMixin } from './OxyServices.contacts';
 import { OxyServicesNotificationsMixin } from './OxyServices.notifications';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
+import { OxyServicesChainsMixin } from './OxyServices.chains';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
@@ -55,6 +57,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>>
@@ -65,6 +68,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>>
@@ -123,6 +127,10 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // OAuth-consent surface (public app identity + connected-app grants). Kept
     // separate from account ownership.
     OxyServicesConnectedAppsMixin,
+    // The app store: the public storefront, the reviews on it, and the listing a
+    // publisher edits. A module OVER the platform — turn it off and OAuth still
+    // works — so it is its own surface rather than more of `accounts`.
+    OxyServicesStoreMixin,
     OxyServicesLocationMixin,
     OxyServicesAnalyticsMixin,
     OxyServicesDevicesMixin,
@@ -137,6 +145,7 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesAppDataMixin,
     // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
     OxyServicesCivicMixin,
+    OxyServicesChainsMixin,
     // User nodes / decentralization (Fase 5): register/read/revoke/manage the
     // caller's personal data node + ingest hint.
     OxyServicesNodesMixin,

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

@@ -125,6 +125,53 @@ describe('@oxyhq/core/server rate limiter', () => {
     expect(req.observedKey).toBe('user:validated-user');
   });
 
+  it('does not clobber an identity a preceding middleware already resolved', () => {
+    // The limiter mutates the SHARED `req`, so the unconditional
+    // `req.userId = null` that `oxy.auth({ optional: true })` writes for every
+    // request it cannot authenticate is not merely a bucketing detail — it
+    // erases the identity for every handler downstream of the limiter too.
+    // The resolver must therefore skip entirely when a user is already present.
+    // This handler stands in for that erasure.
+    const clobberingAuth = jest.fn(
+      (req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
+        req.userId = null;
+        req.user = null;
+        req.sessionId = null;
+        next();
+      },
+    );
+    const oxy = makeOxy(clobberingAuth as unknown as RequestHandler);
+    const req = makeRequest({
+      userId: 'resolved-by-the-app',
+      user: { id: 'resolved-by-the-app' },
+      sessionId: 'app-session',
+    });
+
+    createOxyRateLimit(oxy)(req, {} as Response, jest.fn());
+
+    expect(req.userId).toBe('resolved-by-the-app');
+    expect(req.user).toEqual({ id: 'resolved-by-the-app' });
+    expect(req.sessionId).toBe('app-session');
+    expect(req.observedKey).toBe('user:resolved-by-the-app');
+    expect(clobberingAuth).not.toHaveBeenCalled();
+  });
+
+  it('still resolves the session when no identity is present yet', () => {
+    const authHandler = jest.fn((req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
+      req.userId = 'resolved-by-oxy';
+      req.user = { id: 'resolved-by-oxy' };
+      req.sessionId = 'oxy-session';
+      next();
+    });
+    const oxy = makeOxy(authHandler as unknown as RequestHandler);
+    const req = makeRequest();
+
+    createOxyRateLimit(oxy)(req, {} as Response, jest.fn());
+
+    expect(authHandler).toHaveBeenCalledTimes(1);
+    expect(req.observedKey).toBe('user:resolved-by-oxy');
+  });
+
   it('continues through the anonymous limiter if optional auth returns an error', () => {
     const oxy = makeOxy((_req: Request, _res: Response, next: NextFunction) => {
       next(new Error('token rejected'));

package/src/server/rateLimit.ts

@@ -3,6 +3,7 @@ import { isIPv4, isIPv6 } from 'node:net';
 import type { Request, RequestHandler } from 'express';
 import rateLimit, { type Store } from 'express-rate-limit';
 import type { OxyServices } from '../OxyServices';
+import { createOptionalOxyAuth } from './auth';
 
 /**
  * Server-only rate limiting for Oxy backends.
@@ -25,8 +26,9 @@ import type { OxyServices } from '../OxyServices';
  * WHAT IT PROVIDES
  * ----------------
  * `createOxyRateLimit(oxy, options)` returns a SINGLE composed middleware that:
- *   1. Resolves the user via `oxy.auth({ optional: true })` (idempotent — it
- *      skips re-verification if a prior middleware already set `req.user`).
+ *   1. Resolves the user via `createOptionalOxyAuth` (idempotent — it skips
+ *      resolution entirely if a prior middleware already resolved a user, so
+ *      the limiter can never erase an identity it did not create).
  *   2. Applies an `express-rate-limit` limiter keyed PER USER when
  *      authenticated, falling back to the (IPv6-safe) IP otherwise, with
  *      generous, media-app-realistic defaults and sensible exemptions.
@@ -203,11 +205,12 @@ function hashAnonymousIp(ip: string): string {
 /**
  * Resolve the trusted authenticated rate-limit key.
  *
- * `oxy.auth({ optional: true })` preserves legacy non-session user tokens by
- * decoding their JWT claims locally. Those claims are not cryptographically
- * verified and therefore MUST NOT influence abuse-control buckets. Only use
- * identities that came from a server-validated session or a verified service
- * token/delegation.
+ * Only identities that came from a server-validated session or a verified
+ * service token/delegation may pick a bucket. `req.sessionId` is the marker
+ * for the former: `oxy.auth()` sets it only after `validateSession()` came
+ * back valid, so requiring it here means an identity written by some OTHER
+ * middleware — which this package cannot vouch for — shares the anonymous
+ * per-IP bucket rather than getting the authenticated quota.
  */
 function resolveTrustedAuthenticatedKey(req: OxyAuthedRequest): string | null {
   const userId = req.userId ?? req.user?.id ?? req.user?._id;
@@ -260,7 +263,14 @@ export function createOxyRateLimit(
 
   // Idempotent optional-auth resolver. Reuses the SAME session resolution as
   // every protected route, so the limiter keys by the real user identity.
-  const resolveSession = oxy.auth({ ...auth, optional: true });
+  //
+  // `createOptionalOxyAuth` — NOT the raw `oxy.auth({ optional: true })` —
+  // because only the former skips resolution when a preceding middleware has
+  // already resolved a user. The raw middleware writes `req.userId = null` on
+  // every request it cannot authenticate, and because it mutates the shared
+  // `req` that erasure is visible to every handler downstream of the limiter,
+  // not just to the bucket calculation.
+  const resolveSession = createOptionalOxyAuth(oxy, { auth });
 
   const skip = (req: Request): boolean =>
     isBuiltInExempt(req) || (exempt ? exempt(req) : false);

package/src/session/__tests__/accountProjection.test.ts

@@ -3,6 +3,7 @@ import { ACCOUNT_KINDS } from '@oxyhq/contracts';
 import type { User } from '../../models/interfaces';
 import type { AccountNode } from '../../mixins/OxyServices.accounts';
 import {
+  canSwitchIntoAccount,
   isSwitchTargetAccount,
   projectSwitchableAccounts,
   switchableAccountIds,
@@ -102,6 +103,71 @@ describe('isSwitchTargetAccount', () => {
   });
 });
 
+describe('canSwitchIntoAccount', () => {
+  it('admits self without membership permissions', () => {
+    expect(canSwitchIntoAccount({ kind: 'personal', relationship: 'self' })).toBe(true);
+  });
+
+  it('admits an owned switch target when membership is absent (owner baseline)', () => {
+    expect(canSwitchIntoAccount({ kind: 'organization', relationship: 'owner' })).toBe(true);
+  });
+
+  it('requires account:act_as for member relationships', () => {
+    expect(
+      canSwitchIntoAccount({
+        kind: 'organization',
+        relationship: 'member',
+        callerMembership: {
+          _id: 'm1',
+          accountId: 'org1',
+          memberUserId: 'u1',
+          role: 'billing',
+          status: 'active',
+          permissions: ['account:read', 'billing:manage'],
+          inherit: true,
+          source: 'direct',
+        },
+      }),
+    ).toBe(false);
+
+    expect(
+      canSwitchIntoAccount({
+        kind: 'organization',
+        relationship: 'member',
+        callerMembership: {
+          _id: 'm2',
+          accountId: 'org1',
+          memberUserId: 'u1',
+          role: 'admin',
+          status: 'active',
+          permissions: ['account:act_as', 'account:read'],
+          inherit: true,
+          source: 'direct',
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it('refuses channels even with act_as permission', () => {
+    expect(
+      canSwitchIntoAccount({
+        kind: 'channel',
+        relationship: 'owner',
+        callerMembership: {
+          _id: 'm3',
+          accountId: 'chan1',
+          memberUserId: 'u1',
+          role: 'owner',
+          status: 'active',
+          permissions: ['account:act_as'],
+          inherit: true,
+          source: 'direct',
+        },
+      }),
+    ).toBe(false);
+  });
+});
+
 describe('projectSwitchableAccounts', () => {
   it('returns [] for null state and empty graph', () => {
     expect(
@@ -235,6 +301,38 @@ describe('projectSwitchableAccounts', () => {
     ]);
   });
 
+  it('omits a graph-only member without account:act_as', () => {
+    const rows = projectSwitchableAccounts({
+      state: state([{ accountId: 'a1', sessionId: 's1' }], 'a1'),
+      graph: [
+        graphNode('org1', { kind: 'organization', relationship: 'member', callerMembership: {
+          _id: 'm1',
+          accountId: 'org1',
+          memberUserId: 'a1',
+          role: 'billing',
+          status: 'active',
+          permissions: ['account:read', 'billing:manage'],
+          inherit: true,
+          source: 'direct',
+        } }),
+        graphNode('org2', { kind: 'organization', relationship: 'member', callerMembership: {
+          _id: 'm2',
+          accountId: 'org2',
+          memberUserId: 'a1',
+          role: 'admin',
+          status: 'active',
+          permissions: ['account:act_as', 'account:read'],
+          inherit: true,
+          source: 'direct',
+        } }),
+      ],
+      profilesById: mapOf(user('a1'), user('org1'), user('org2')),
+      resolveAvatarUrl: noAvatar,
+    });
+
+    expect(rows.map((r) => r.accountId)).toEqual(['a1', 'org2']);
+  });
+
   it('dedups an account present as BOTH device session and graph node into ONE enriched row', () => {
     const rows = projectSwitchableAccounts({
       state: state([{ accountId: 'a1', sessionId: 's1', authuser: 0 }], 'a1'),

package/src/session/accountProjection.ts

@@ -135,6 +135,37 @@ export function isSwitchTargetAccount(
   return node.relationship === 'self' || isActAsEligibleKind(node.kind);
 }
 
+/**
+ * Whether the caller may switch INTO this account — the server-side
+ * `account:act_as` gate plus the structural {@link isSwitchTargetAccount} rule.
+ *
+ * `relationship: 'self'` always passes (returning to the caller's own personal
+ * account). Every other ground requires a switch-eligible kind AND
+ * `account:act_as` in the resolved membership permissions. When permissions are
+ * absent but the relationship is `owner`, the owner baseline is assumed — the
+ * API always resolves effective permissions for owned accounts, but test
+ * fixtures and stale rows may omit the membership blob.
+ */
+export function canSwitchIntoAccount(
+  node: {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+    callerMembership?: AccountMember | null;
+  },
+): boolean {
+  if (node.relationship === 'self') {
+    return true;
+  }
+  if (!isSwitchTargetAccount(node)) {
+    return false;
+  }
+  const permissions = node.callerMembership?.permissions;
+  if (permissions) {
+    return permissions.includes('account:act_as');
+  }
+  return node.relationship === 'owner';
+}
+
 /** Input to {@link projectSwitchableAccounts}. */
 export interface ProjectSwitchableAccountsInput {
   /**
@@ -176,9 +207,9 @@ export interface ProjectSwitchableAccountsInput {
  * and a graph node is deduped into ONE device row enriched with the graph
  * metadata (relationship / kind / parent / membership).
  *
- * Graph nodes that are not switch targets — a `channel`, which nobody may act
- * as — are omitted. {@link isSwitchTargetAccount} is the rule; see the filter
- * below.
+ * Graph nodes the caller cannot switch into — a `channel`, or a managed account
+ * whose membership lacks `account:act_as` — are omitted.
+ * {@link canSwitchIntoAccount} is the rule; see the filter below.
  */
 export function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput): SwitchableAccount[] {
   const { state, graph, profilesById, activeUser, locale, resolveAvatarUrl } = input;
@@ -274,7 +305,7 @@ export function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput)
     // An account already on the device skipped this check via the branch above,
     // and correctly: whatever its kind, the caller is signed into it, so
     // switching is a local activation that asks the server for nothing.
-    if (!isSwitchTargetAccount(node)) {
+    if (!canSwitchIntoAccount(node)) {
       continue;
     }
     remember(toRow(node.account, {
@@ -298,7 +329,7 @@ export function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput)
  * document, but including their ids lets the caller pass one id set and lets the
  * projection prefer freshly-fetched profiles uniformly.
  *
- * Applies the SAME {@link isSwitchTargetAccount} filter as
+ * Applies the SAME {@link canSwitchIntoAccount} filter as
  * {@link projectSwitchableAccounts} to graph nodes, so this never fetches a
  * profile for a row the projection will drop — and, just as importantly, never
  * SKIPS one the projection will keep, which would leave that row unrendered
@@ -315,7 +346,7 @@ export function switchableAccountIds(
     }
   }
   for (const node of graph) {
-    if (node.accountId && isSwitchTargetAccount(node)) {
+    if (node.accountId && canSwitchIntoAccount(node)) {
       ids.add(node.accountId);
     }
   }

package/src/utils/errorUtils.ts

@@ -36,6 +36,110 @@ export const ErrorCodes = {
   CONNECTION_FAILED: 'CONNECTION_FAILED'
 } as const;
 
+/**
+ * The `Error` shape the SDK rejects with when an HTTP request fails.
+ *
+ * `HttpService` throws this for every non-2xx response, and
+ * `OxyServices.handleError` (the wrapper the mixin methods rethrow through)
+ * preserves `message`, `status`, `code` and `details`. `response` only survives
+ * on the raw `HttpService`/`makeRequest` path, so treat it as optional.
+ *
+ * Narrow a caught value with {@link isHttpRequestError} instead of asserting.
+ */
+export interface HttpRequestError extends Error {
+    /** HTTP status of the failed response. */
+    status: number;
+    /** Machine-readable code the server sent, when it sent one. */
+    code?: string;
+    /** Structured error detail the server sent, when it sent an object. */
+    details?: Record<string, unknown>;
+    /**
+     * Present on errors thrown directly by `HttpService`. `data` is the parsed
+     * JSON error body verbatim — the escape hatch for any server field the SDK
+     * does not lift onto `code`/`details`.
+     */
+    response?: {
+        status: number;
+        statusText: string;
+        data?: unknown;
+    };
+}
+
+/**
+ * Narrow a caught value to {@link HttpRequestError}.
+ *
+ * Returns `false` for a plain {@link ApiError} object (those are objects, not
+ * `Error`s) — run an arbitrary thrown value through {@link handleHttpError}
+ * first if you need one normalized.
+ */
+export function isHttpRequestError(value: unknown): value is HttpRequestError {
+    if (!(value instanceof Error)) {
+        return false;
+    }
+    return typeof (value as Partial<HttpRequestError>).status === 'number';
+}
+
+/**
+ * The fields {@link parseHttpErrorBody} lifts off a parsed error response body.
+ */
+export interface ParsedHttpErrorBody {
+    message?: string;
+    code?: string;
+    details?: Record<string, unknown>;
+}
+
+const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const nonEmptyString = (value: unknown): string | undefined =>
+    typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+
+/**
+ * Extract `message` / `code` / `details` from a parsed HTTP error response body.
+ *
+ * Handles every error envelope in use across the Oxy ecosystem:
+ *
+ * - `{ error: { code, message, details? } }` — nested envelope (CrowdSource and
+ *   other Oxy services). Never stringify the nested object: `new Error(obj)`
+ *   yields the literal message `"[object Object]"`.
+ * - `{ error: '<CODE>', message, details? }` — oxy-api's canonical shape
+ *   (`ApiError.toJSON`), where the top-level `error` field IS the code.
+ * - `{ error: '<CODE>', error_description }` — RFC 6749 §5.2 / RFC 6750 §3, the
+ *   OAuth token and userinfo endpoints. `error_description` is the human text
+ *   and `error` is the machine code, so both survive.
+ * - `{ message, code }` — e.g. the API's CSRF rejections.
+ * - `{ error: '<human message>' }` — legacy hand-rolled routes. With no sibling
+ *   `message`/`error_description` the string is the message, not a code: a bare
+ *   `error` string is not machine-readable enough to promote to `code`.
+ *
+ * Anything else — a non-object body (`null`, `[]`, `"str"`, `42`), or an object
+ * carrying none of these fields — yields an empty result, leaving the caller on
+ * its status-based fallback message. Total function: never throws.
+ */
+export function parseHttpErrorBody(body: unknown): ParsedHttpErrorBody {
+    if (!isPlainRecord(body)) {
+        return {};
+    }
+
+    const nested = isPlainRecord(body.error) ? body.error : undefined;
+    const errorString = nonEmptyString(body.error);
+    // A sibling that proves the top-level `error` is a CODE rather than prose.
+    const siblingMessage = nonEmptyString(body.message) ?? nonEmptyString(body.error_description);
+
+    return {
+        message: siblingMessage ?? (nested ? nonEmptyString(nested.message) : errorString),
+        code:
+            (nested ? nonEmptyString(nested.code) : undefined) ??
+            nonEmptyString(body.code) ??
+            (siblingMessage ? errorString : undefined),
+        details: isPlainRecord(body.details)
+            ? body.details
+            : nested && isPlainRecord(nested.details)
+                ? nested.details
+                : undefined,
+    };
+}
+
 /**
  * Create a standardized API error
  */
@@ -98,21 +202,28 @@ export function handleHttpError(error: unknown): ApiError {
 
   // Handle fetch Response errors - check if it has response property with status
   if (error && typeof error === 'object' && 'response' in error) {
-    const fetchError = error as { 
-      response?: { 
-        status: number; 
+    const fetchError = error as {
+      response?: {
+        status: number;
         statusText?: string;
       };
       status?: number;
       message?: string;
+      details?: unknown;
     };
-    
+
     const status = fetchError.response?.status || fetchError.status;
     if (status) {
+      // `details` is carried through when present: a body may ship structured
+      // detail without a machine-readable `code` (which is what routes the
+      // error to the already-an-ApiError branch above), and dropping it here
+      // would make it unreachable to every caller that rethrows via
+      // `OxyServices.handleError`.
       return createApiError(
         fetchError.message || `HTTP ${status} error`,
         getErrorCodeFromStatus(status),
-        status
+        status,
+        isPlainRecord(fetchError.details) ? fetchError.details : undefined
       );
     }
   }