@oxyhq/core 16.1.0 → 17.0.2

package/dist/esm/HttpService.js

@@ -235,10 +235,9 @@ export class HttpService {
      *
      * Why we explicitly reject `URLSearchParams`:
      *  - `URLSearchParams` ALSO exposes `append` / `get` / `has`, so the
-     *    duck-type fallback below would have misidentified it as FormData.
-     *  - We want urlencoded payloads to take the JSON-stringify path so the
-     *    server receives them as `application/x-www-form-urlencoded` instead
-     *    of an empty multipart body.
+     *    duck-type fallback below would have misidentified it as FormData and
+     *    sent an empty multipart body.
+     *  - It has its own encoding path instead — see {@link isUrlSearchParams}.
      */
     isFormData(data) {
         if (!data || typeof data !== 'object') {
@@ -272,6 +271,18 @@ export class HttpService {
             typeof candidate.getAll === 'function' &&
             typeof candidate.delete === 'function');
     }
+    /**
+     * True for an `application/x-www-form-urlencoded` payload.
+     *
+     * Needed because a handful of endpoints are defined by a standard that fixes
+     * their request encoding rather than by our own JSON conventions — today
+     * `POST /auth/oauth/token`, whose encoding RFC 6749 §4.1.3 mandates. Passing
+     * a `URLSearchParams` as `data` selects that encoding; everything else is
+     * still JSON.
+     */
+    isUrlSearchParams(data) {
+        return typeof URLSearchParams !== 'undefined' && data instanceof URLSearchParams;
+    }
     /**
      * Main request method - handles everything in one place
      */
@@ -319,6 +330,7 @@ export class HttpService {
                 const fullUrl = this.buildURL(url, params);
                 // Determine if data is FormData using robust detection
                 const isFormData = this.isFormData(data);
+                const isUrlEncoded = this.isUrlSearchParams(data);
                 // Make fetch request
                 const controller = new AbortController();
                 const timeoutId = timeout ? setTimeout(() => controller.abort(), timeout) : null;
@@ -330,7 +342,10 @@ export class HttpService {
                     'Accept': 'application/json',
                 };
                 // Only set Content-Type for non-FormData requests (FormData sets it automatically with boundary)
-                if (!isFormData) {
+                if (isUrlEncoded) {
+                    headers['Content-Type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
+                }
+                else if (!isFormData) {
                     headers['Content-Type'] = 'application/json';
                 }
                 // Add authorization header if available
@@ -372,8 +387,11 @@ export class HttpService {
                         headers[key] = value;
                     });
                 }
+                // `URLSearchParams` is serialised explicitly rather than handed to
+                // `fetch` as-is: RN's fetch does not consistently encode it, and doing
+                // it here keeps the body identical across every platform.
                 const bodyValue = method !== 'GET' && data
-                    ? (isFormData ? data : JSON.stringify(data))
+                    ? (isFormData ? data : isUrlEncoded ? data.toString() : JSON.stringify(data))
                     : undefined;
                 // React Native FormData workaround:
                 // Expo SDK 56's "winter fetch" rejects RN file descriptors `{uri, type, name}`
@@ -439,6 +457,10 @@ export class HttpService {
                             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;
                             }

package/dist/esm/i18n/locales/en-US.json

@@ -678,7 +678,7 @@
                 "firstNamePlaceholder": "Enter first name",
                 "lastName": "Last Name",
                 "lastNamePlaceholder": "Enter last name (optional)",
-                "invalidChars": "Use letters and spaces only"
+                "invalidChars": "Use letters, spaces, apostrophes, and name separators only"
             },
             "username": {
                 "title": "Username",
@@ -1752,7 +1752,8 @@
             "title": "Create account",
             "subtitle": "Create an account you control. It will have its own profile, members, and apps.",
             "displayName": {
-                "label": "Display name"
+                "label": "Display name",
+                "invalidChars": "Use letters, spaces, apostrophes, and name separators only"
             },
             "bio": {
                 "label": "Bio (optional)"
@@ -1829,7 +1830,8 @@
             "subtitle": "Manage this account’s profile, members, and access.",
             "save": "Save changes",
             "displayName": {
-                "label": "Display name"
+                "label": "Display name",
+                "invalidChars": "Use letters, spaces, apostrophes, and name separators only"
             },
             "bio": {
                 "label": "Bio (optional)"

package/dist/esm/i18n/locales/es-ES.json

@@ -203,7 +203,7 @@
                 "firstNamePlaceholder": "Introduce tu nombre",
                 "lastName": "Apellido",
                 "lastNamePlaceholder": "Introduce tu apellido (opcional)",
-                "invalidChars": "Usa solo letras y espacios"
+                "invalidChars": "Usa solo letras, espacios, apóstrofos y separadores de nombre"
             },
             "username": {
                 "title": "Usuario",
@@ -1752,7 +1752,8 @@
             "title": "Crear cuenta",
             "subtitle": "Crea una cuenta que tú controlas. Tendrá su propio perfil, miembros y aplicaciones.",
             "displayName": {
-                "label": "Nombre visible"
+                "label": "Nombre visible",
+                "invalidChars": "Usa solo letras, espacios, apóstrofos y separadores de nombre"
             },
             "bio": {
                 "label": "Biografía (opcional)"
@@ -1829,7 +1830,8 @@
             "subtitle": "Gestiona el perfil, los miembros y el acceso de esta cuenta.",
             "save": "Guardar cambios",
             "displayName": {
-                "label": "Nombre visible"
+                "label": "Nombre visible",
+                "invalidChars": "Usa solo letras, espacios, apóstrofos y separadores de nombre"
             },
             "bio": {
                 "label": "Biografía (opcional)"

package/dist/esm/i18n/locales/locales/en-US.json

@@ -678,7 +678,7 @@
         "firstNamePlaceholder": "Enter first name",
         "lastName": "Last Name",
         "lastNamePlaceholder": "Enter last name (optional)",
-        "invalidChars": "Use letters and spaces only"
+        "invalidChars": "Use letters, spaces, apostrophes, and name separators only"
       },
       "username": {
         "title": "Username",
@@ -1752,7 +1752,8 @@
       "title": "Create account",
       "subtitle": "Create an account you control. It will have its own profile, members, and apps.",
       "displayName": {
-        "label": "Display name"
+        "label": "Display name",
+        "invalidChars": "Use letters, spaces, apostrophes, and name separators only"
       },
       "bio": {
         "label": "Bio (optional)"
@@ -1829,7 +1830,8 @@
       "subtitle": "Manage this account’s profile, members, and access.",
       "save": "Save changes",
       "displayName": {
-        "label": "Display name"
+        "label": "Display name",
+        "invalidChars": "Use letters, spaces, apostrophes, and name separators only"
       },
       "bio": {
         "label": "Bio (optional)"

package/dist/esm/i18n/locales/locales/es-ES.json

@@ -203,7 +203,7 @@
         "firstNamePlaceholder": "Introduce tu nombre",
         "lastName": "Apellido",
         "lastNamePlaceholder": "Introduce tu apellido (opcional)",
-        "invalidChars": "Usa solo letras y espacios"
+        "invalidChars": "Usa solo letras, espacios, apóstrofos y separadores de nombre"
       },
       "username": {
         "title": "Usuario",
@@ -1752,7 +1752,8 @@
       "title": "Crear cuenta",
       "subtitle": "Crea una cuenta que tú controlas. Tendrá su propio perfil, miembros y aplicaciones.",
       "displayName": {
-        "label": "Nombre visible"
+        "label": "Nombre visible",
+        "invalidChars": "Usa solo letras, espacios, apóstrofos y separadores de nombre"
       },
       "bio": {
         "label": "Biografía (opcional)"
@@ -1829,7 +1830,8 @@
       "subtitle": "Gestiona el perfil, los miembros y el acceso de esta cuenta.",
       "save": "Guardar cambios",
       "displayName": {
-        "label": "Nombre visible"
+        "label": "Nombre visible",
+        "invalidChars": "Usa solo letras, espacios, apóstrofos y separadores de nombre"
       },
       "bio": {
         "label": "Biografía (opcional)"

package/dist/esm/index.js

@@ -119,7 +119,7 @@ export { retryAsync } from './utils/asyncUtils.js';
 // ---------------------------------------------------------------------------
 // Validation
 // ---------------------------------------------------------------------------
-export { EMAIL_REGEX, USERNAME_REGEX, PASSWORD_REGEX, MAX_DISPLAY_NAME_LENGTH, isValidEmail, isValidUsername, isValidPassword, isValidDisplayName, DISPLAY_NAME_ALLOWED_SCRIPTS, DISPLAY_NAME_DISALLOWED_SOURCE, DISPLAY_NAME_ORPHANED_MARK_SOURCE, DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE, isRequiredString, isRequiredNumber, isRequiredBoolean, isValidArray, isValidObject, isValidUUID, isValidURL, isValidDate, isValidFileSize, isValidFileType, sanitizeString, sanitizeHTML, isValidObjectId, validateAndSanitizeUserInput, } from './utils/validationUtils.js';
+export { EMAIL_REGEX, USERNAME_REGEX, PASSWORD_REGEX, MAX_DISPLAY_NAME_LENGTH, DISPLAY_NAME_INVALID_MESSAGE, isValidEmail, isValidUsername, isValidPassword, isValidDisplayName, DISPLAY_NAME_ALLOWED_SCRIPTS, DISPLAY_NAME_DISALLOWED_SOURCE, DISPLAY_NAME_ORPHANED_MARK_SOURCE, DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE, isRequiredString, isRequiredNumber, isRequiredBoolean, isValidArray, isValidObject, isValidUUID, isValidURL, isValidDate, isValidFileSize, isValidFileType, sanitizeString, sanitizeHTML, isValidObjectId, validateAndSanitizeUserInput, } from './utils/validationUtils.js';
 // ---------------------------------------------------------------------------
 // Text normalization
 // ---------------------------------------------------------------------------

package/dist/esm/mixins/OxyServices.auth.js

@@ -12,6 +12,12 @@ import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/use
  * returned `expiresAt` is authoritative; this is only the client-proposed value.
  */
 const COMMONS_SIGN_IN_EXPIRY_MS = 5 * 60 * 1000;
+/**
+ * Fallback access-token lifetime used only if the token endpoint ever omits the
+ * RFC 6749 `expires_in` member. Matches the server's current 15-minute access
+ * token; the server's value always wins when present.
+ */
+const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 15 * 60;
 /**
  * @internal Narrow an untrusted `requesterLabel` from the approve-info response.
  *
@@ -1127,39 +1133,43 @@ export function OxyServicesAuthMixin(Base) {
          * after sign-in at auth.oxy.so) for a device-first session.
          * Public first-party clients use PKCE (`codeVerifier`); the access token is
          * planted immediately on success.
+         *
+         * Speaks the standard RFC 6749 §4.1.3 token request — a form-urlencoded
+         * body with snake_case parameters and `grant_type=authorization_code` — and
+         * reads the flat §5.1 response. The camelCase JSON request and `{ data }`
+         * response this method used before were an Oxy invention no OAuth library
+         * could interoperate with; the endpoint no longer accepts them. The method's
+         * OWN signature is unchanged, so callers are unaffected.
          */
         async exchangeOAuthCode(params) {
             try {
-                const res = await this.makeRequest('POST', '/auth/oauth/token', {
+                const form = new URLSearchParams({
+                    grant_type: 'authorization_code',
                     code: params.code,
-                    clientId: params.clientId,
-                    redirectUri: params.redirectUri,
-                    codeVerifier: params.codeVerifier,
-                }, { cache: false, skipAuth: true });
-                const payload = res.data ??
-                    res;
-                if (!payload || typeof payload !== 'object') {
+                    redirect_uri: params.redirectUri,
+                    client_id: params.clientId,
+                    code_verifier: params.codeVerifier,
+                });
+                const res = await this.makeRequest('POST', '/auth/oauth/token', form, { cache: false, skipAuth: true });
+                if (!res || typeof res !== 'object') {
                     throw new Error('auth/oauth/token returned an unexpected response shape');
                 }
-                const record = payload;
-                const accessToken = (record.access_token ?? record.accessToken);
-                const sessionId = (record.session_id ?? record.sessionId);
-                const deviceId = (record.deviceId ?? record.device_id);
-                const deviceSecret = (record.deviceSecret ?? record.device_secret);
+                // RFC 6749 §5.1: every member sits at the TOP LEVEL of the document.
+                const record = res;
+                const accessToken = typeof record.access_token === 'string' ? record.access_token : undefined;
+                const sessionId = typeof record.session_id === 'string' ? record.session_id : undefined;
+                const deviceId = typeof record.deviceId === 'string' ? record.deviceId : undefined;
+                const deviceSecret = typeof record.deviceSecret === 'string' ? record.deviceSecret : undefined;
                 const userRaw = record.user;
                 if (!sessionId || !deviceId || !deviceSecret || !userRaw || typeof userRaw !== 'object') {
                     throw new Error('auth/oauth/token returned an incomplete session payload');
                 }
                 const userObj = userRaw;
-                const userId = userObj.id;
+                const userId = typeof userObj.id === 'string' ? userObj.id : undefined;
                 if (!userId) {
                     throw new Error('auth/oauth/token returned a session without user.id');
                 }
-                const expiresInSec = typeof record.expires_in === 'number'
-                    ? record.expires_in
-                    : typeof record.expiresIn === 'number'
-                        ? record.expiresIn
-                        : 15 * 60;
+                const expiresInSec = typeof record.expires_in === 'number' ? record.expires_in : DEFAULT_ACCESS_TOKEN_TTL_SECONDS;
                 const expiresAt = new Date(Date.now() + expiresInSec * 1000).toISOString();
                 if (accessToken) {
                     this.setTokens(accessToken);
@@ -1181,5 +1191,33 @@ export function OxyServicesAuthMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * Fetch OpenID Connect userinfo for the current bearer (`GET /auth/oauth/userinfo`).
+         * The response is a flat JSON document — no `{ data }` wrapper.
+         */
+        async getOAuthUserInfo() {
+            try {
+                const res = await this.makeRequest('GET', '/auth/oauth/userinfo', undefined, { cache: false });
+                if (!res || typeof res !== 'object') {
+                    throw new Error('auth/oauth/userinfo returned an unexpected response shape');
+                }
+                const record = res;
+                const sub = typeof record.sub === 'string' ? record.sub : undefined;
+                if (!sub) {
+                    throw new Error('auth/oauth/userinfo returned a response without sub');
+                }
+                return {
+                    sub,
+                    ...(typeof record.preferred_username === 'string'
+                        ? { preferred_username: record.preferred_username }
+                        : {}),
+                    ...(typeof record.name === 'string' ? { name: record.name } : {}),
+                    ...(typeof record.picture === 'string' ? { picture: record.picture } : {}),
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
     };
 }

package/dist/esm/server/index.js

@@ -25,6 +25,9 @@ export { createOxyCors } from './cors.js';
 export { buildOxyCspDirectives, buildOxyPagesHeaders, createOxySecurityHeaders, formatOxyCspPolicy, OXY_CSP_BASELINE, } from './securityHeaders.js';
 // Constant-time secret comparison.
 export { verifySecret } from './verifySecret.js';
+// Cross-service user-invalidation signal: oxy-api publishes when identity
+// changes, every consuming backend sweeps its caches instead of waiting out a TTL.
+export { createOxyUserInvalidationHandler, evictOxyIdentityCache, publishOxyUserInvalidation, } from './userInvalidation.js';
 // Registrable-apex (eTLD+1) derivation via the Public Suffix List — the SINGLE
 // SOURCE OF TRUTH shared with the IdP worker and the client FAPI auto-detect.
 // Pure host handling (no browser deps), so it is safe on the server subpath and

package/dist/esm/server/userInvalidation.js

@@ -0,0 +1,173 @@
+/**
+ * Oxy user-invalidation publish/consume helpers for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Every Oxy backend caches Oxy identity, and none of them find out when it
+ * changes. The `OxyServices` GET response cache holds `GET /users/:id` and
+ * `GET /profiles/username/:name` for five minutes; it is swept when THIS process
+ * writes the profile (see the `clearCacheEntry` calls in the user mixin) and
+ * never when somebody else does — which is the normal case, since profiles are
+ * edited in Oxy's own apps. So an avatar or display-name change is invisible to
+ * every consuming backend for up to five minutes, per process.
+ *
+ * oxy-api broadcasts {@link OXY_USER_INVALIDATION_CHANNEL} on the shared Valkey
+ * when a user's identity changes. This module is the consumer half: it parses
+ * and validates the event, sweeps the SDK's own cache, and hands the event to
+ * app-specific eviction. Wiring it is two lines and every backend that does so
+ * stops serving stale identity.
+ *
+ * WHY THE TRANSPORT IS THE CALLER'S JOB
+ * -------------------------------------
+ * This module deliberately does NOT take a Redis client. ioredis and node-redis
+ * disagree about how to subscribe — node-redis passes the listener to
+ * `subscribe(channel, listener)`, ioredis takes `subscribe(channel)` and then
+ * emits `'message'` on the client — and a helper that accepted "a client" would
+ * have to sniff which library it was handed. That kind of detection is exactly
+ * what breaks silently when a consumer upgrades a client library.
+ *
+ * So the split is: this module owns parsing, validation, dispatch and the
+ * never-throw guarantee (the parts that are easy to get wrong and identical
+ * everywhere), and the caller owns its own client's two-line subscribe idiom
+ * (trivial, but library-specific).
+ *
+ *     // node-redis
+ *     await subscriber.subscribe(
+ *       OXY_USER_INVALIDATION_CHANNEL,
+ *       createOxyUserInvalidationHandler({ oxy: oxyClient }),
+ *     );
+ *
+ *     // ioredis
+ *     const handle = createOxyUserInvalidationHandler({ oxy: oxyClient });
+ *     await subscriber.subscribe(OXY_USER_INVALIDATION_CHANNEL);
+ *     subscriber.on('message', (_channel, raw) => handle(raw));
+ *
+ * Subscribe on EVERY task, not just an elected leader. The SDK cache this sweeps
+ * is per-process in-memory, so a leader-only subscriber would leave every other
+ * task stale — and leader-gating would add a failure mode (leader down means no
+ * invalidation anywhere) to a signal whose whole point is that losing it is
+ * merely slow, never wrong.
+ *
+ * Node-only; exported solely from `@oxyhq/core/server`.
+ */
+import { OXY_USER_INVALIDATION_CHANNEL, isPublishedOxyUserChangeReason, oxyUserInvalidationEventSchema, } from '@oxyhq/contracts';
+/**
+ * Broadcast that an Oxy user's record changed.
+ *
+ * Returns `true` when a message was put on the wire and `false` when the reason
+ * is not a broadcast one ({@link isPublishedOxyUserChangeReason}) — the latter is
+ * a deliberate no-op, not a failure. Suppressing at the publisher rather than
+ * letting every subscriber discard matters at bulk-follow scale, where a single
+ * call moves up to 200 edges.
+ *
+ * NEVER THROWS AND NEVER RETURNS A REJECTED PROMISE. This is called from inside
+ * cache invalidation, which itself runs after a successful database write on the
+ * request path: a publish failure must not turn a completed profile update into
+ * a 500. A dropped message costs a consumer its TTL and nothing more.
+ *
+ * @param publisher - A connected Redis client. Must NOT be a client currently in
+ *                    subscriber mode — Redis forbids `PUBLISH` on a subscribed
+ *                    connection, so pass the publisher half of a pub/sub pair.
+ * @param userId    - The Oxy user whose record changed.
+ * @param reason    - How the record changed. See {@link OxyUserChangeReason}.
+ * @param onError   - Optional diagnostic sink for a failed publish.
+ */
+export function publishOxyUserInvalidation(publisher, userId, reason, onError) {
+    if (!userId || !isPublishedOxyUserChangeReason(reason)) {
+        return false;
+    }
+    const event = { userId, reason, at: Date.now() };
+    try {
+        const result = publisher.publish(OXY_USER_INVALIDATION_CHANNEL, JSON.stringify(event));
+        // node-redis returns a promise; ioredis returns a promise too, but a mocked
+        // or synchronous client may return anything. Only attach a rejection handler
+        // when there is actually something thenable to reject.
+        if (isPromiseLike(result)) {
+            Promise.resolve(result).catch((error) => onError?.(error));
+        }
+        return true;
+    }
+    catch (error) {
+        onError?.(error);
+        return false;
+    }
+}
+function isPromiseLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.then === 'function');
+}
+/**
+ * Build the message handler for {@link OXY_USER_INVALIDATION_CHANNEL}.
+ *
+ * The returned function NEVER THROWS and never returns a rejected promise. It
+ * runs inside the Redis client's message dispatch, where an exception either
+ * takes down the subscriber connection or surfaces as an unhandled rejection —
+ * and losing the subscription is strictly worse than losing one message, because
+ * it is silent and permanent.
+ *
+ * A message that fails schema validation is dropped, not retried: the payload is
+ * produced by a contract both sides compile against, so a malformed one means a
+ * version skew or an unrelated publisher on the channel, neither of which a retry
+ * fixes.
+ */
+export function createOxyUserInvalidationHandler(options = {}) {
+    const { oxy, onInvalidate, onError } = options;
+    return (raw) => {
+        let event;
+        try {
+            const parsed = oxyUserInvalidationEventSchema.safeParse(JSON.parse(raw));
+            if (!parsed.success) {
+                onError?.(parsed.error, raw);
+                return;
+            }
+            event = parsed.data;
+        }
+        catch (error) {
+            onError?.(error, raw);
+            return;
+        }
+        if (oxy) {
+            try {
+                evictOxyIdentityCache(oxy, event.userId);
+            }
+            catch (error) {
+                // A cache sweep must never cost us the app-specific eviction below.
+                onError?.(error, raw);
+            }
+        }
+        if (!onInvalidate)
+            return;
+        try {
+            const result = onInvalidate(event);
+            if (isPromiseLike(result)) {
+                Promise.resolve(result).catch((error) => onError?.(error, raw));
+            }
+        }
+        catch (error) {
+            onError?.(error, raw);
+        }
+    };
+}
+/**
+ * Sweep an `OxyServices` GET response cache of everything that could carry the
+ * given user's identity.
+ *
+ * The by-id entry is exact. The by-username and resolve entries are keyed by
+ * HANDLE, which cannot be derived from an id without the very lookup we are
+ * invalidating, so those are swept by prefix — the same imprecision the SDK
+ * already accepts when it sweeps its own cache after a local profile write, and
+ * bounded by the fact that over-eviction costs a refetch and can never serve
+ * wrong data.
+ */
+export function evictOxyIdentityCache(oxy, userId) {
+    // Match the sweep the user mixin runs after a local profile write — session-
+    // bound and /users/me entries are keyed without the user id, so they must be
+    // prefix-swept on cross-service invalidation too.
+    oxy.clearCacheByPrefix('GET:/session/user/');
+    oxy.clearCacheByPrefix('GET:/users/me');
+    oxy.clearCacheByPrefix('GET:/auth/lookup/');
+    oxy.clearCacheEntry(`GET:/users/${userId}`);
+    oxy.clearCacheByPrefix('GET:/profiles/username/');
+    oxy.clearCacheByPrefix('GET:/profiles/resolve');
+}

package/dist/esm/utils/validationUtils.js

@@ -7,6 +7,8 @@ import { DISPLAY_NAME_ALLOWED_SCRIPTS_RANGES, DISPLAY_NAME_COMBINING_MARKS_RANGE
  * Shared by the API write path and client input surfaces.
  */
 export const MAX_DISPLAY_NAME_LENGTH = 80;
+/** Shared 400 / inline-validation copy for native display-name policy rejections. */
+export const DISPLAY_NAME_INVALID_MESSAGE = 'Name may only contain letters, spaces, apostrophes, and name separators (·, ־, ་, ・).';
 /**
  * Email validation regex
  */