@oxyhq/core 16.0.0 → 17.0.0

package/src/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/src/index.ts

@@ -49,7 +49,7 @@ export type {
     CommonsDeliveryPlatform,
     CommonsDeliveryRoute,
 } from './utils/commonsDelivery';
-export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
+export type { ServiceTokenResponse, OAuthUserInfoResponse } from './mixins/OxyServices.auth';
 // "Sign in with Oxy" — handoff (Workstream C)
 export type {
     CommonsSignInHandle,
@@ -479,6 +479,8 @@ export {
     EMAIL_REGEX,
     USERNAME_REGEX,
     PASSWORD_REGEX,
+    MAX_DISPLAY_NAME_LENGTH,
+    DISPLAY_NAME_INVALID_MESSAGE,
     isValidEmail,
     isValidUsername,
     isValidPassword,
@@ -486,6 +488,7 @@ export {
     DISPLAY_NAME_ALLOWED_SCRIPTS,
     DISPLAY_NAME_DISALLOWED_SOURCE,
     DISPLAY_NAME_ORPHANED_MARK_SOURCE,
+    DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE,
     isRequiredString,
     isRequiredNumber,
     isRequiredBoolean,

package/src/mixins/OxyServices.auth.ts

@@ -32,6 +32,13 @@ import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/use
  */
 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;
+
 export interface ChallengeResponse {
   challenge: string;
   expiresAt: string;
@@ -59,6 +66,14 @@ export interface PublicKeyCheckResponse {
   message: string;
 }
 
+/** OpenID Connect userinfo claims returned by `GET /auth/oauth/userinfo`. */
+export interface OAuthUserInfoResponse {
+  sub: string;
+  preferred_username?: string;
+  name?: string;
+  picture?: string;
+}
+
 // ===========================================================================
 // "Sign in with Oxy" — cross-device QR / app-to-app handoff (Workstream C)
 // ===========================================================================
@@ -1677,6 +1692,13 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * 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: {
       code: string;
@@ -1685,38 +1707,39 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       codeVerifier: string;
     }): Promise<LoginSessionResult> {
       try {
-        const res = await this.makeRequest<unknown>('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 as { data?: Record<string, unknown> }).data ??
-          (res as Record<string, unknown>);
-        if (!payload || typeof payload !== 'object') {
+          redirect_uri: params.redirectUri,
+          client_id: params.clientId,
+          code_verifier: params.codeVerifier,
+        });
+        const res = await this.makeRequest<unknown>(
+          '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 as Record<string, unknown>;
-        const accessToken = (record.access_token ?? record.accessToken) as string | undefined;
-        const sessionId = (record.session_id ?? record.sessionId) as string | undefined;
-        const deviceId = (record.deviceId ?? record.device_id) as string | undefined;
-        const deviceSecret = (record.deviceSecret ?? record.device_secret) as string | undefined;
+        // RFC 6749 §5.1: every member sits at the TOP LEVEL of the document.
+        const record = res as Record<string, unknown>;
+        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 as Record<string, unknown>;
-        const userId = userObj.id as string | undefined;
+        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;
+          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);
@@ -1737,5 +1760,38 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         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(): Promise<OAuthUserInfoResponse> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          '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 as Record<string, unknown>;
+        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/src/mixins/__tests__/preSessionSkipAuth.test.ts

@@ -124,12 +124,14 @@ describe('pre-session public endpoints use skipAuth', () => {
     );
   });
 
-  it('exchangeOAuthCode skips auth preflight', async () => {
+  it('exchangeOAuthCode skips auth preflight and sends an RFC 6749 form request', async () => {
     makeRequest.mockResolvedValueOnce({
-      sessionId: 's1',
+      access_token: 'tok',
+      token_type: 'Bearer',
+      expires_in: 900,
+      session_id: 's1',
       deviceId: 'd1',
       deviceSecret: 'ds_secret',
-      accessToken: 'tok',
       user: { id: 'u1' },
     });
     await oxy.exchangeOAuthCode({
@@ -141,21 +143,28 @@ describe('pre-session public endpoints use skipAuth', () => {
     expect(makeRequest).toHaveBeenCalledWith(
       'POST',
       '/auth/oauth/token',
-      {
-        code: 'code-1',
-        clientId: 'oxy_dk_test',
-        redirectUri: 'https://app.example/callback',
-        codeVerifier: 'verifier',
-      },
+      expect.any(URLSearchParams),
       expect.objectContaining({ skipAuth: true }),
     );
+    // The body is the standard §4.1.3 request: snake_case names, an explicit
+    // grant type, and nothing camelCase that only Oxy's old endpoint understood.
+    const body = makeRequest.mock.calls[0][2] as URLSearchParams;
+    expect(Object.fromEntries(body.entries())).toEqual({
+      grant_type: 'authorization_code',
+      code: 'code-1',
+      redirect_uri: 'https://app.example/callback',
+      client_id: 'oxy_dk_test',
+      code_verifier: 'verifier',
+    });
   });
 
   it('exchangeOAuthCode rejects a response without deviceSecret', async () => {
     makeRequest.mockResolvedValueOnce({
-      sessionId: 's1',
+      access_token: 'tok',
+      token_type: 'Bearer',
+      expires_in: 900,
+      session_id: 's1',
       deviceId: 'd1',
-      accessToken: 'tok',
       user: { id: 'u1' },
     });
     await expect(
@@ -167,4 +176,56 @@ describe('pre-session public endpoints use skipAuth', () => {
       }),
     ).rejects.toThrow(/incomplete session payload/i);
   });
+
+  it('exchangeOAuthCode reads the FLAT RFC 6749 §5.1 response', async () => {
+    makeRequest.mockResolvedValueOnce({
+      access_token: 'tok',
+      token_type: 'Bearer',
+      expires_in: 900,
+      scope: 'profile:read',
+      session_id: 's1',
+      deviceId: 'd1',
+      deviceSecret: 'ds_secret',
+      user: { id: 'u1', username: 'alice', avatar: 'file-1' },
+    });
+
+    const result = await oxy.exchangeOAuthCode({
+      code: 'code-1',
+      clientId: 'oxy_dk_test',
+      redirectUri: 'https://app.example/callback',
+      codeVerifier: 'verifier',
+    });
+
+    expect(result).toMatchObject({
+      sessionId: 's1',
+      deviceId: 'd1',
+      deviceSecret: 'ds_secret',
+      accessToken: 'tok',
+      user: { id: 'u1', username: 'alice', avatar: 'file-1' },
+    });
+  });
+
+  it('getOAuthUserInfo reads the flat OIDC userinfo response', async () => {
+    makeRequest.mockResolvedValueOnce({
+      sub: '507f1f77bcf86cd799439011',
+      preferred_username: 'alice',
+      name: 'Alice Example',
+      picture: 'https://api.oxy.so/assets/file-1/stream',
+    });
+
+    const result = await oxy.getOAuthUserInfo();
+
+    expect(makeRequest).toHaveBeenCalledWith(
+      'GET',
+      '/auth/oauth/userinfo',
+      undefined,
+      expect.objectContaining({ cache: false }),
+    );
+    expect(result).toEqual({
+      sub: '507f1f77bcf86cd799439011',
+      preferred_username: 'alice',
+      name: 'Alice Example',
+      picture: 'https://api.oxy.so/assets/file-1/stream',
+    });
+  });
 });

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

@@ -0,0 +1,208 @@
+import { OXY_USER_INVALIDATION_CHANNEL } from '@oxyhq/contracts';
+
+import {
+  createOxyUserInvalidationHandler,
+  evictOxyIdentityCache,
+  publishOxyUserInvalidation,
+  type OxyIdentityCacheEvictor,
+} from '../userInvalidation';
+
+function makePublisher() {
+  const calls: Array<{ channel: string; message: string }> = [];
+  return {
+    calls,
+    publish(channel: string, message: string) {
+      calls.push({ channel, message });
+      return Promise.resolve(1);
+    },
+  };
+}
+
+function makeEvictor() {
+  const entries: string[] = [];
+  const prefixes: string[] = [];
+  const evictor: OxyIdentityCacheEvictor = {
+    clearCacheEntry: (key) => {
+      entries.push(key);
+    },
+    clearCacheByPrefix: (prefix) => {
+      prefixes.push(prefix);
+      return 0;
+    },
+  };
+  return { evictor, entries, prefixes };
+}
+
+describe('@oxyhq/core/server publishOxyUserInvalidation', () => {
+  it('publishes a profile change on the contract channel', () => {
+    const publisher = makePublisher();
+    const published = publishOxyUserInvalidation(publisher, 'user-1', 'profile');
+
+    expect(published).toBe(true);
+    expect(publisher.calls).toHaveLength(1);
+    expect(publisher.calls[0].channel).toBe(OXY_USER_INVALIDATION_CHANNEL);
+
+    const payload = JSON.parse(publisher.calls[0].message);
+    expect(payload.userId).toBe('user-1');
+    expect(payload.reason).toBe('profile');
+    expect(typeof payload.at).toBe('number');
+  });
+
+  it('puts NOTHING on the wire for graph churn', () => {
+    // The whole point of the suppression: not a message subscribers discard,
+    // but no message at all. Bulk follow moves up to 200 edges per call.
+    const publisher = makePublisher();
+    const published = publishOxyUserInvalidation(publisher, 'user-1', 'graph');
+
+    expect(published).toBe(false);
+    expect(publisher.calls).toHaveLength(0);
+  });
+
+  it('publishes nothing for an empty user id', () => {
+    const publisher = makePublisher();
+    expect(publishOxyUserInvalidation(publisher, '', 'profile')).toBe(false);
+    expect(publisher.calls).toHaveLength(0);
+  });
+
+  it('never throws when the client throws synchronously', () => {
+    const boom = new Error('redis down');
+    const publisher = {
+      publish() {
+        throw boom;
+      },
+    };
+    const onError = jest.fn();
+
+    expect(() => publishOxyUserInvalidation(publisher, 'user-1', 'profile', onError)).not.toThrow();
+    expect(publishOxyUserInvalidation(publisher, 'user-1', 'profile', onError)).toBe(false);
+    expect(onError).toHaveBeenCalledWith(boom);
+  });
+
+  it('never surfaces a rejected publish as an unhandled rejection', async () => {
+    const boom = new Error('publish rejected');
+    const publisher = {
+      publish: () => Promise.reject(boom),
+    };
+    const onError = jest.fn();
+
+    // Returns true — the message was handed to the client; the failure is async.
+    expect(publishOxyUserInvalidation(publisher, 'user-1', 'profile', onError)).toBe(true);
+    await Promise.resolve();
+    expect(onError).toHaveBeenCalledWith(boom);
+  });
+
+  it('tolerates a client whose publish returns a non-promise', () => {
+    const calls: string[] = [];
+    const publisher = {
+      publish: (_channel: string, message: string) => {
+        calls.push(message);
+        return 1;
+      },
+    };
+    expect(publishOxyUserInvalidation(publisher, 'user-1', 'profile')).toBe(true);
+    expect(calls).toHaveLength(1);
+  });
+});
+
+describe('@oxyhq/core/server createOxyUserInvalidationHandler', () => {
+  const validMessage = JSON.stringify({ userId: 'user-1', reason: 'profile', at: 1 });
+
+  it('sweeps the SDK identity cache for the invalidated user', () => {
+    const { evictor, entries, prefixes } = makeEvictor();
+    createOxyUserInvalidationHandler({ oxy: evictor })(validMessage);
+
+    expect(entries).toEqual(['GET:/users/user-1']);
+    expect(prefixes).toEqual(['GET:/profiles/username/', 'GET:/profiles/resolve']);
+  });
+
+  it('hands the parsed event to app-specific eviction', () => {
+    const onInvalidate = jest.fn();
+    createOxyUserInvalidationHandler({ onInvalidate })(validMessage);
+
+    expect(onInvalidate).toHaveBeenCalledWith({ userId: 'user-1', reason: 'profile', at: 1 });
+  });
+
+  it('drops an unparseable message without throwing', () => {
+    const onInvalidate = jest.fn();
+    const onError = jest.fn();
+    const handle = createOxyUserInvalidationHandler({ onInvalidate, onError });
+
+    expect(() => handle('not json at all')).not.toThrow();
+    expect(onInvalidate).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalled();
+  });
+
+  it('drops a message that fails the contract schema', () => {
+    const onInvalidate = jest.fn();
+    const onError = jest.fn();
+    const handle = createOxyUserInvalidationHandler({ onInvalidate, onError });
+
+    handle(JSON.stringify({ userId: 'user-1', reason: 'graph', at: 1 }));
+    handle(JSON.stringify({ reason: 'profile', at: 1 }));
+
+    expect(onInvalidate).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledTimes(2);
+  });
+
+  it('never throws when app eviction throws', () => {
+    // The handler runs inside the Redis client's message dispatch. An escape
+    // there kills the subscription — silently and permanently — which is far
+    // worse than losing the one message that caused it.
+    const boom = new Error('app eviction failed');
+    const onError = jest.fn();
+    const handle = createOxyUserInvalidationHandler({
+      onInvalidate: () => {
+        throw boom;
+      },
+      onError,
+    });
+
+    expect(() => handle(validMessage)).not.toThrow();
+    expect(onError).toHaveBeenCalledWith(boom, validMessage);
+  });
+
+  it('never throws when app eviction rejects', async () => {
+    const boom = new Error('async eviction failed');
+    const onError = jest.fn();
+    const handle = createOxyUserInvalidationHandler({
+      onInvalidate: () => Promise.reject(boom),
+      onError,
+    });
+
+    expect(() => handle(validMessage)).not.toThrow();
+    await Promise.resolve();
+    expect(onError).toHaveBeenCalledWith(boom, validMessage);
+  });
+
+  it('still runs app eviction when the SDK sweep throws', () => {
+    const onInvalidate = jest.fn();
+    const onError = jest.fn();
+    const evictor: OxyIdentityCacheEvictor = {
+      clearCacheEntry: () => {
+        throw new Error('sweep failed');
+      },
+      clearCacheByPrefix: () => 0,
+    };
+
+    createOxyUserInvalidationHandler({ oxy: evictor, onInvalidate, onError })(validMessage);
+
+    expect(onInvalidate).toHaveBeenCalled();
+    expect(onError).toHaveBeenCalled();
+  });
+
+  it('is a no-op with no options configured', () => {
+    expect(() => createOxyUserInvalidationHandler()(validMessage)).not.toThrow();
+  });
+});
+
+describe('@oxyhq/core/server evictOxyIdentityCache', () => {
+  it('clears the exact by-id entry and the handle-keyed prefixes', () => {
+    // The by-id key is exact. The handle-keyed ones cannot be derived from an
+    // id without the lookup being invalidated, so they are swept by prefix.
+    const { evictor, entries, prefixes } = makeEvictor();
+    evictOxyIdentityCache(evictor, 'abc123');
+
+    expect(entries).toEqual(['GET:/users/abc123']);
+    expect(prefixes).toEqual(['GET:/profiles/username/', 'GET:/profiles/resolve']);
+  });
+});

package/src/server/index.ts

@@ -82,6 +82,19 @@ export type {
 // Constant-time secret comparison.
 export { verifySecret } from './verifySecret';
 
+// 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';
+export type {
+  OxyIdentityCacheEvictor,
+  OxyInvalidationPublisher,
+  OxyUserInvalidationHandlerOptions,
+} from './userInvalidation';
+
 // 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