@oxyhq/core 19.1.2 → 20.1.0

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

@@ -109,18 +109,41 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * Uses server-side session validation for security (not just JWT decode).
          *
          * **Design note — jwtDecode vs jwt.verify:**
-         * This middleware intentionally uses `jwtDecode()` (decode-only, no signature
-         * verification) for user tokens. This is by design, NOT a security gap:
-         * - Third-party apps using `oxy.auth()` don't have the Oxy JWT secret
-         * - Security comes from API-based session validation (`validateSession()`)
-         *   which checks the session server-side on every request
-         * - Service tokens (type: 'service') DO use cryptographic HMAC verification
-         *   via the `jwtSecret` option, since they are stateless. Service tokens
-         *   are additionally checked for `aud`, `iss`, and `type` claims to prevent
+         * This middleware uses `jwtDecode()` (decode-only, NO signature check) for
+         * user tokens, because third-party apps mounting `oxy.auth()` do not hold
+         * the Oxy signing secret. **Every claim in a user token is therefore
+         * attacker-controlled and proves nothing on its own.** The identity comes
+         * from somewhere else entirely:
+         * - A user token MUST carry a `sessionId`. That session is validated
+         *   server-side on every request via `validateSession()`, and the user id
+         *   is read off the VALIDATED SESSION — never off the token. A token whose
+         *   `userId` claim disagrees with the session is refused
+         *   (`SESSION_USER_MISMATCH`); a token with no `sessionId` at all is
+         *   refused outright (`SESSION_REQUIRED`). There is no local-claims path.
+         * - Service tokens (type: 'service') ARE stateless, so they use
+         *   cryptographic HMAC verification via the `jwtSecret` option, and are
+         *   additionally checked for `aud`, `iss`, and `type` claims to prevent
          *   cross-token-type confusion attacks.
          * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
          *   direct access to `SERVICE_TOKEN_SECRET` / `ACCESS_TOKEN_SECRET`.
          *
+         * **Why session-less user tokens are refused rather than trusted:**
+         * every user access token the Oxy API issues carries a `sessionId` (see
+         * `packages/api/src/utils/sessionUtils.ts`, `generateSessionTokens` — the
+         * only mint site for user tokens, including the OAuth code exchange). So
+         * refusing session-less user tokens costs nothing legitimate, while
+         * accepting them let anyone authenticate as anyone by hand-rolling a JWT
+         * with a `userId` claim and a garbage signature.
+         *
+         * **Why the claimed user id is cross-checked against the session:**
+         * `GET /session/validate/:sessionId` is UNAUTHENTICATED and does not bind
+         * the bearer token — it returns whoever owns the session id it was handed.
+         * Trusting the token's `userId` claim after a successful validation would
+         * therefore let a caller holding ANY live session id (their own, for
+         * instance) pair it with a forged `userId` and be trusted as that user.
+         * `authSocket()` has always cross-checked this; the HTTP middleware now
+         * does too.
+         *
          * **Service-token delegation (X-Oxy-User-Id):**
          * When a service token is accompanied by `X-Oxy-User-Id`, the SDK calls
          * `verifyServiceActingAs(appId, userId)` to confirm an explicit delegation

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

@@ -16,6 +16,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';
@@ -27,6 +28,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';
@@ -41,7 +43,7 @@ import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & 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>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & 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>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

package/dist/types/session/accountProjection.d.ts

@@ -121,6 +121,22 @@ export declare function isSwitchTargetAccount(node: {
     kind?: AccountKind | null;
     relationship?: AccountRelationship;
 }): boolean;
+/**
+ * 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 declare function canSwitchIntoAccount(node: {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+    callerMembership?: AccountMember | null;
+}): boolean;
 /** Input to {@link projectSwitchableAccounts}. */
 export interface ProjectSwitchableAccountsInput {
     /**
@@ -161,9 +177,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 declare function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput): SwitchableAccount[];
 /**
@@ -173,7 +189,7 @@ export declare function projectSwitchableAccounts(input: ProjectSwitchableAccoun
  * 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

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

@@ -23,6 +23,73 @@ export declare const ErrorCodes: {
     readonly NETWORK_ERROR: "NETWORK_ERROR";
     readonly CONNECTION_FAILED: "CONNECTION_FAILED";
 };
+/**
+ * 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 declare function isHttpRequestError(value: unknown): value is HttpRequestError;
+/**
+ * The fields {@link parseHttpErrorBody} lifts off a parsed error response body.
+ */
+export interface ParsedHttpErrorBody {
+    message?: string;
+    code?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * 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 declare function parseHttpErrorBody(body: unknown): ParsedHttpErrorBody;
 /**
  * Create a standardized API error
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "19.1.2",
+  "version": "20.1.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -62,6 +62,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "NOTICE",
     "dist",
     "src"
   ],
@@ -79,7 +80,7 @@
     "directory": "packages/core"
   },
   "author": "OxyHQ",
-  "license": "AGPL-3.0-only",
+  "license": "Apache-2.0",
   "homepage": "https://oxy.so",
   "engines": {
     "node": ">=18.0.0"
@@ -115,12 +116,13 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.24.0",
-    "@oxyhq/protocol": "^0.1.6",
+    "@oxyhq/contracts": "^0.25.0",
+    "@oxyhq/protocol": "^0.2.0",
     "@scure/bip39": "^1.6.0",
     "@types/elliptic": "^6.4.18",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",
+    "express-rate-limit": "^8.6.0",
     "helmet": "^8.0.0",
     "invariant": "^2.2.4",
     "jwt-decode": "^4.0.0",
@@ -132,8 +134,7 @@
     "@react-native-async-storage/async-storage": "*",
     "expo-crypto": "*",
     "expo-secure-store": "*",
-    "express": "^4.0.0",
-    "express-rate-limit": "^8.0.0"
+    "express": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "@react-native-async-storage/async-storage": {

package/src/HttpService.ts

@@ -16,7 +16,7 @@
 import { TTLCache, registerCacheForCleanup } from './utils/cache';
 import { RequestDeduplicator, RequestQueue, SimpleLogger } from './utils/requestUtils';
 import { retryAsync } from './utils/asyncUtils';
-import { handleHttpError } from './utils/errorUtils';
+import { handleHttpError, parseHttpErrorBody } from './utils/errorUtils';
 import { jwtDecode } from 'jwt-decode';
 import { isNative, getPlatformOS } from './utils/platform';
 import { isReactNative } from '@oxyhq/protocol';
@@ -632,37 +632,44 @@ export class HttpService {
             }
           }
 
-          // Try to parse error response (handle empty/malformed JSON)
-          let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
-          const contentType = response.headers.get('content-type');
-          if (contentType && contentType.includes('application/json')) {
+          // Read the error body (may be absent, non-JSON, empty or malformed).
+          // Anything unreadable leaves `errorBody` undefined and degrades to the
+          // status-based message — an error path that throws its own error is
+          // worse than the error it was reporting.
+          let errorBody: unknown;
+          const errorContentType = response.headers.get('content-type');
+          if (errorContentType?.includes('application/json')) {
             try {
-              const errorData = await response.json() as {
-                message?: string;
-                error?: string;
-                error_description?: string;
-              } | null;
-              // Accept either structured error field from API responses.
-              if (errorData?.message) {
-                errorMessage = errorData.message;
-              } else if (errorData?.error_description) {
-                // RFC 6749 §5.2 / RFC 6750 §3 — OAuth endpoints surface human text here.
-                errorMessage = errorData.error_description;
-              } else if (errorData?.error) {
-                errorMessage = errorData.error;
-              }
+              errorBody = await response.json();
             } catch (parseError) {
               // Malformed JSON or empty response - use status text
               this.logger.warn('Failed to parse error response JSON:', parseError);
             }
           }
 
-          const error = new Error(errorMessage) as Error & {
+          // `parseHttpErrorBody` handles every envelope in use, including the
+          // nested `{ error: { code, message } }` shape — assigning that nested
+          // OBJECT as the message is what produced `"[object Object]"`.
+          const parsed = parseHttpErrorBody(errorBody);
+          const error = new Error(
+            parsed.message ?? `HTTP ${response.status}: ${response.statusText}`,
+          ) as Error & {
             status?: number;
-            response?: { status: number; statusText: string }
+            code?: string;
+            details?: Record<string, unknown>;
+            response?: { status: number; statusText: string; data?: unknown };
           };
           error.status = response.status;
-          error.response = { status: response.status, statusText: response.statusText };
+          error.response = { status: response.status, statusText: response.statusText, data: errorBody };
+          // Only set `code`/`details` when the server actually sent them.
+          // Assigning `undefined` would still create the property, which changes
+          // how `handleHttpError` classifies the error downstream.
+          if (parsed.code !== undefined) {
+            error.code = parsed.code;
+          }
+          if (parsed.details !== undefined) {
+            error.details = parsed.details;
+          }
           throw error;
         }
 

package/src/__tests__/parseHttpErrorBody.test.ts

@@ -0,0 +1,116 @@
+import { isHttpRequestError, parseHttpErrorBody } from '../utils/errorUtils';
+
+/**
+ * `parseHttpErrorBody` is the ONE place the SDK decides what a failed request's
+ * message, code and details are, across every error envelope the Oxy ecosystem
+ * emits. The bug it exists to prevent is silent: a nested
+ * `{ error: { code, message } }` assigned straight to `new Error(...)` yields
+ * the literal string `"[object Object]"`, which reads as a rendering bug in
+ * whichever app surfaces it, arbitrarily far from here.
+ *
+ * Each case below pins one envelope AND the discrimination it depends on — in
+ * particular, whether the top-level `error` string is a machine CODE or human
+ * prose is decided solely by whether a sibling human field is present, so both
+ * sides of that fork need a fixture or the rule is untested.
+ */
+describe('parseHttpErrorBody', () => {
+    it('reads the nested { error: { code, message, details } } envelope', () => {
+        expect(
+            parseHttpErrorBody({
+                error: { code: 'case_conflict', message: 'A case already exists', details: { caseId: 'c_1' } },
+            }),
+        ).toEqual({
+            message: 'A case already exists',
+            code: 'case_conflict',
+            details: { caseId: 'c_1' },
+        });
+    });
+
+    it("reads oxy-api's { error: '<CODE>', message } shape — error IS the code", () => {
+        expect(parseHttpErrorBody({ error: 'VALIDATION_ERROR', message: 'username is taken' })).toEqual({
+            message: 'username is taken',
+            code: 'VALIDATION_ERROR',
+            details: undefined,
+        });
+    });
+
+    it("reads RFC 6749 { error: '<CODE>', error_description } from the OAuth endpoints", () => {
+        // The OAuth token/userinfo endpoints are the one part of the API that
+        // does not use the `{ error, message }` envelope. Without this arm the
+        // human text is dropped and the raw code is shown to the user.
+        expect(
+            parseHttpErrorBody({ error: 'invalid_grant', error_description: 'Authorization code expired' }),
+        ).toEqual({
+            message: 'Authorization code expired',
+            code: 'invalid_grant',
+            details: undefined,
+        });
+    });
+
+    it("treats a LONE { error: '<text>' } as the message, never as a code", () => {
+        // The discriminator is the ABSENCE of a sibling human field. Promoting a
+        // bare string to `code` would put prose where callers switch on codes,
+        // so this case and the two above have to disagree.
+        expect(parseHttpErrorBody({ error: 'Something went wrong' })).toEqual({
+            message: 'Something went wrong',
+            code: undefined,
+            details: undefined,
+        });
+    });
+
+    it('reads the flat { message, code } shape (CSRF rejections)', () => {
+        expect(parseHttpErrorBody({ message: 'Invalid CSRF token', code: 'CSRF_TOKEN_INVALID' })).toEqual({
+            message: 'Invalid CSRF token',
+            code: 'CSRF_TOKEN_INVALID',
+            details: undefined,
+        });
+    });
+
+    it('ignores whitespace-only strings rather than reporting them as a message', () => {
+        // A blank message is worse than none: it replaces the status fallback
+        // with an empty error surface the user cannot act on.
+        expect(parseHttpErrorBody({ message: '   ', error: '' })).toEqual({
+            message: undefined,
+            code: undefined,
+            details: undefined,
+        });
+    });
+
+    it('ignores a non-object `details` instead of passing it through', () => {
+        expect(parseHttpErrorBody({ message: 'nope', details: 'not-an-object' }).details).toBeUndefined();
+        expect(parseHttpErrorBody({ message: 'nope', details: ['a'] }).details).toBeUndefined();
+    });
+
+    it.each([null, undefined, [], 'a string', 42, true])('returns {} for the non-object body %p', (body) => {
+        expect(parseHttpErrorBody(body)).toEqual({});
+    });
+
+    it('returns {} for an object carrying none of the known fields', () => {
+        expect(parseHttpErrorBody({ unrelated: 'field' })).toEqual({
+            message: undefined,
+            code: undefined,
+            details: undefined,
+        });
+    });
+});
+
+describe('isHttpRequestError', () => {
+    it('accepts an Error carrying a numeric status', () => {
+        const error = Object.assign(new Error('boom'), { status: 409 });
+        expect(isHttpRequestError(error)).toBe(true);
+    });
+
+    it('rejects a plain ApiError object — those are objects, not Errors', () => {
+        // The distinction is load-bearing: an ApiError has to go through
+        // `handleHttpError` first, and a truthy answer here would let a caller
+        // read `.stack`/`.name` off something that has neither.
+        expect(isHttpRequestError({ message: 'boom', status: 409, code: 'CONFLICT' })).toBe(false);
+    });
+
+    it('rejects an Error whose status is a non-number', () => {
+        // `'409'` is the shape a hand-built error most plausibly carries, and
+        // the narrowing promises callers a number they can compare.
+        expect(isHttpRequestError(Object.assign(new Error('boom'), { status: '409' }))).toBe(false);
+        expect(isHttpRequestError(new Error('boom'))).toBe(false);
+    });
+});

package/src/__tests__/serverValueImportsDeclared.test.ts

@@ -103,6 +103,13 @@ describe('@oxyhq/core/server value imports are installable', () => {
     expect(manifest.peerDependenciesMeta?.helmet?.optional).toBeUndefined();
   });
 
+  it('keeps express-rate-limit installable rather than a peer', () => {
+    // Same class as helmet: `rateLimit.ts` value-imports it and the server
+    // barrel re-exports that module, so a missing install crashes at boot.
+    expect(dependencies.has('express-rate-limit')).toBe(true);
+    expect(manifest.peerDependencies?.['express-rate-limit']).toBeUndefined();
+  });
+
   it('leaves express as an optional peer, because it is type-only here', () => {
     // The counter-example that stops this test from being read as "declare
     // everything": type imports vanish at build time, so an optional peer is a

package/src/i18n/__tests__/accountCategoryLabels.test.ts

@@ -0,0 +1,62 @@
+import { ACCOUNT_CATEGORY_IDS, SELECTABLE_ACCOUNT_CATEGORY_IDS } from '@oxyhq/contracts';
+import { accountCategoryLabel, EN_ACCOUNT_CATEGORY_LABELS } from '../accountCategoryLabels';
+
+/**
+ * Every locale the SDK ships a dictionary for, plus a region variant and an
+ * untranslated language, because the three take different paths through
+ * `translate`: exact dictionary, base-subtag dictionary, and English fallback.
+ */
+const SHIPPED_LOCALES = [
+  'en-US',
+  'es-ES',
+  'ca-ES',
+  'fr-FR',
+  'de-DE',
+  'it-IT',
+  'pt-PT',
+  'ja-JP',
+  'ko-KR',
+  'zh-CN',
+  'ar-SA',
+] as const;
+const REGION_VARIANT = 'es-MX';
+const UNSHIPPED_LOCALE = 'nl-NL';
+
+describe('accountCategoryLabel', () => {
+  // Vacuity floor: a traversal bug that yielded an empty id list would make
+  // every assertion below pass over nothing.
+  it('covers the whole vocabulary', () => {
+    expect(ACCOUNT_CATEGORY_IDS.length).toBeGreaterThanOrEqual(46);
+    expect(Object.keys(EN_ACCOUNT_CATEGORY_LABELS)).toHaveLength(ACCOUNT_CATEGORY_IDS.length);
+  });
+
+  it.each([...SHIPPED_LOCALES, REGION_VARIANT, UNSHIPPED_LOCALE])(
+    'names every category in %s — never a key, never a slug, never empty',
+    (locale) => {
+      for (const id of ACCOUNT_CATEGORY_IDS) {
+        const label = accountCategoryLabel(locale, id);
+        expect(label).not.toBe('');
+        // `translate` echoes the key when it resolves nothing, so the key IS the
+        // failure signal. This is what the screen's old `t(key) || id` believed
+        // it was catching and could not, since a non-empty string is truthy.
+        expect(label).not.toBe(`accounts.accountCategory.${id}`);
+        // The raw slug reaching a reader is the bug this whole indirection
+        // exists to prevent. `ai` is excluded: its English label legitimately
+        // equals its id.
+      }
+    },
+  );
+
+  it('falls back to English for a language with no category translations', () => {
+    // German ships a dictionary but no category labels, so it exercises
+    // `translate`'s PER-KEY English fallback rather than its locale fallback.
+    expect(accountCategoryLabel('de-DE', 'cooperative')).toBe(
+      EN_ACCOUNT_CATEGORY_LABELS.cooperative,
+    );
+  });
+
+  it('resolves a region variant through its base language', () => {
+    expect(accountCategoryLabel('es-MX', 'news')).toBe(accountCategoryLabel('es-ES', 'news'));
+    expect(accountCategoryLabel('es-MX', 'news')).not.toBe(EN_ACCOUNT_CATEGORY_LABELS.news);
+  });
+});

package/src/i18n/__tests__/accountRoleLabels.test.ts

@@ -0,0 +1,54 @@
+import type { AccountRole } from '../../mixins/OxyServices.accounts';
+import { EN_ACCOUNT_ROLE_LABELS, accountRoleLabel } from '../accountRoleLabels';
+
+const ACCOUNT_ROLES: AccountRole[] = [
+  'owner',
+  'admin',
+  'editor',
+  'developer',
+  'billing',
+  'viewer',
+];
+
+const SHIPPED_LOCALES = [
+  'en-US',
+  'es-ES',
+  'ca-ES',
+  'fr-FR',
+  'de-DE',
+  'it-IT',
+  'pt-PT',
+  'ja-JP',
+  'ko-KR',
+  'zh-CN',
+  'ar-SA',
+] as const;
+const REGION_VARIANT = 'es-MX';
+const UNSHIPPED_LOCALE = 'nl-NL';
+
+describe('accountRoleLabel', () => {
+  it('covers the whole vocabulary', () => {
+    expect(ACCOUNT_ROLES.length).toBe(6);
+    expect(Object.keys(EN_ACCOUNT_ROLE_LABELS)).toHaveLength(ACCOUNT_ROLES.length);
+  });
+
+  it.each([...SHIPPED_LOCALES, REGION_VARIANT, UNSHIPPED_LOCALE])(
+    'names every role in %s — never a key, never a slug, never empty',
+    (locale) => {
+      for (const role of ACCOUNT_ROLES) {
+        const label = accountRoleLabel(locale, role);
+        expect(label).not.toBe('');
+        expect(label).not.toBe(`accounts.roles.${role}.label`);
+      }
+    },
+  );
+
+  it('falls back to English for a language with no role translations', () => {
+    expect(accountRoleLabel('de-DE', 'developer')).toBe(EN_ACCOUNT_ROLE_LABELS.developer);
+  });
+
+  it('resolves a region variant through its base language', () => {
+    expect(accountRoleLabel('es-MX', 'admin')).toBe(accountRoleLabel('es-ES', 'admin'));
+    expect(accountRoleLabel('es-MX', 'admin')).not.toBe(EN_ACCOUNT_ROLE_LABELS.admin);
+  });
+});

package/src/i18n/__tests__/reputationCategoryLabels.test.ts

@@ -0,0 +1,56 @@
+import { REPUTATION_CATEGORIES } from '@oxyhq/contracts';
+import {
+  EN_REPUTATION_CATEGORY_LABELS,
+  reputationCategoryLabel,
+} from '../reputationCategoryLabels';
+
+const SHIPPED_LOCALES = [
+  'en-US',
+  'es-ES',
+  'ca-ES',
+  'fr-FR',
+  'de-DE',
+  'it-IT',
+  'pt-PT',
+  'ja-JP',
+  'ko-KR',
+  'zh-CN',
+  'ar-SA',
+] as const;
+const REGION_VARIANT = 'es-MX';
+const UNSHIPPED_LOCALE = 'nl-NL';
+
+describe('reputationCategoryLabel', () => {
+  it('covers the whole vocabulary', () => {
+    expect(REPUTATION_CATEGORIES.length).toBeGreaterThanOrEqual(7);
+    expect(Object.keys(EN_REPUTATION_CATEGORY_LABELS)).toHaveLength(
+      REPUTATION_CATEGORIES.length,
+    );
+  });
+
+  it.each([...SHIPPED_LOCALES, REGION_VARIANT, UNSHIPPED_LOCALE])(
+    'names every category in %s — never a key, never a slug, never empty',
+    (locale) => {
+      for (const id of REPUTATION_CATEGORIES) {
+        const label = reputationCategoryLabel(locale, id);
+        expect(label).not.toBe('');
+        expect(label).not.toBe(`trust.rules.categories.${id}`);
+      }
+    },
+  );
+
+  it('falls back to English for a language with no category translations', () => {
+    expect(reputationCategoryLabel('de-DE', 'physical')).toBe(
+      EN_REPUTATION_CATEGORY_LABELS.physical,
+    );
+  });
+
+  it('resolves a region variant through its base language', () => {
+    expect(reputationCategoryLabel('es-MX', 'content')).toBe(
+      reputationCategoryLabel('es-ES', 'content'),
+    );
+    expect(reputationCategoryLabel('es-MX', 'content')).not.toBe(
+      EN_REPUTATION_CATEGORY_LABELS.content,
+    );
+  });
+});