@oxyhq/core 20.0.0 → 21.0.0

package/src/mixins/OxyServices.utility.ts

@@ -250,18 +250,41 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * 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
@@ -543,8 +566,10 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             return next();
           }
 
-          const userId = decoded.userId || decoded.id;
-          if (!userId) {
+          // The CLAIMED user id. Never trusted as an identity — it is only ever
+          // compared against the id the validated session resolves to.
+          const claimedUserId = readStringClaim(decoded.userId) ?? readStringClaim(decoded.id);
+          if (!claimedUserId) {
             if (optional) {
               req.userId = null;
               req.user = null;
@@ -580,58 +605,82 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             return res.status(401).json(error);
           }
 
-          // Validate token against the Oxy API for session-based verification
-          // This ensures the session hasn't been revoked server-side
-          if (decoded.sessionId) {
-            try {
-              const validationResult = await oxyInstance.validateSession(decoded.sessionId, {
-                useHeaderValidation: true,
-              });
+          // A server-validated session is MANDATORY for a user token. The JWT
+          // signature is not verified on this path, so a bare decoded token
+          // proves nothing: without the session round-trip a forged token could
+          // claim any user id. Mirrors `authSocket()`, which has always
+          // required this.
+          const sessionId = readStringClaim(decoded.sessionId);
+          if (!sessionId) {
+            if (optional) {
+              req.userId = null;
+              req.user = null;
+              return next();
+            }
 
-              if (!validationResult || !validationResult.valid) {
-                if (optional) {
-                  req.userId = null;
-                  req.user = null;
-                  return next();
-                }
+            const error = {
+              error: 'SESSION_REQUIRED',
+              message: 'Access token is not bound to a session',
+              code: 'SESSION_REQUIRED',
+              status: 401
+            };
+            if (onError) return onError(error);
+            return res.status(401).json(error);
+          }
 
-                const error = {
-                  error: 'INVALID_SESSION',
-                  message: 'Session invalid or expired',
-                  code: 'INVALID_SESSION',
-                  status: 401
-                };
-                if (onError) return onError(error);
-                return res.status(401).json(error);
+          // Validate the token against the Oxy API. This proves the session is
+          // real and unrevoked, AND yields the identity it belongs to.
+          try {
+            const validationResult = await oxyInstance.validateSession(sessionId, {
+              useHeaderValidation: true,
+            });
+
+            if (!validationResult || !validationResult.valid || !validationResult.user) {
+              if (optional) {
+                req.userId = null;
+                req.user = null;
+                return next();
               }
 
-              // Use validated user data from session validation (already has full user)
-              req.userId = userId;
-              req.accessToken = token;
-              req.sessionId = decoded.sessionId;
+              const error = {
+                error: 'INVALID_SESSION',
+                message: 'Session invalid or expired',
+                code: 'INVALID_SESSION',
+                status: 401
+              };
+              if (onError) return onError(error);
+              return res.status(401).json(error);
+            }
 
-              if (loadUser && validationResult.user) {
-                // Session validation already returns full user data
-                req.user = validationResult.user;
-              } else {
-                req.user = { id: userId } as User;
+            // The session — not the token — is the source of truth for identity.
+            const validatedUserId = getUserIdentityId(validationResult.user);
+            if (!validatedUserId) {
+              if (optional) {
+                req.userId = null;
+                req.user = null;
+                return next();
               }
 
-              if (debug) {
-                logger.debug(`[oxy.auth] OK user=${userId} session=${decoded.sessionId}`, {
-                  component: 'auth',
-                  method: 'auth',
-                });
-              }
+              const error = {
+                error: 'INVALID_SESSION',
+                message: 'Session did not resolve to a usable identity',
+                code: 'INVALID_SESSION',
+                status: 401
+              };
+              if (onError) return onError(error);
+              return res.status(401).json(error);
+            }
 
-              return next();
-            } catch (validationError) {
-              if (debug) {
-                logger.debug('[oxy.auth] Session validation failed', {
-                  component: 'auth',
-                  method: 'auth',
-                }, validationError);
-              }
+            if (validatedUserId !== claimedUserId) {
+              // Session-id/claim confusion: the caller presented a live session
+              // that belongs to somebody else. Worth a warning — it has no
+              // benign cause. Ids only; never the token or the payload.
+              logger.warn('[oxy.auth] Token rejected — claimed user does not own the session', {
+                component: 'auth',
+                method: 'auth',
+                claimedUserId,
+                validatedUserId,
+              });
 
               if (optional) {
                 req.userId = null;
@@ -640,58 +689,53 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               }
 
               const error = {
-                error: 'SESSION_VALIDATION_ERROR',
-                message: 'Session validation failed',
-                code: 'SESSION_VALIDATION_ERROR',
+                error: 'SESSION_USER_MISMATCH',
+                message: 'Token user does not match the session',
+                code: 'SESSION_USER_MISMATCH',
                 status: 401
               };
               if (onError) return onError(error);
               return res.status(401).json(error);
             }
-          }
 
-          // Non-session token: use local validation only (userId from JWT)
-          req.userId = userId;
-          req.accessToken = token;
-          req.user = { id: userId } as User;
+            req.userId = validatedUserId;
+            req.accessToken = token;
+            req.sessionId = sessionId;
+            // Session validation already returned the full user, so `loadUser`
+            // costs no extra round-trip.
+            req.user = loadUser ? validationResult.user : ({ id: validatedUserId } as User);
 
-          // If loadUser requested with non-session token, fetch from API
-          if (loadUser) {
-            try {
-              // Temporarily set token to make the API call
-              const prevToken = oxyInstance.getAccessToken();
-              oxyInstance.setTokens(token);
-              const fullUser = await oxyInstance.getCurrentUser();
-              // Restore previous token
-              if (prevToken) {
-                oxyInstance.setTokens(prevToken);
-              } else {
-                oxyInstance.clearTokens();
-              }
+            if (debug) {
+              logger.debug(`[oxy.auth] OK user=${validatedUserId} session=${sessionId}`, {
+                component: 'auth',
+                method: 'auth',
+              });
+            }
 
-              if (fullUser) {
-                req.user = fullUser;
-              }
-            } catch (loadUserError) {
-              // Loading the full user is best-effort here; the basic { id }
-              // object is already attached. Log so misconfigured deployments
-              // can be diagnosed instead of silently failing.
-              logger.warn('[oxy.auth] loadUser fallback — could not fetch full profile', {
+            return next();
+          } catch (validationError) {
+            if (debug) {
+              logger.debug('[oxy.auth] Session validation failed', {
                 component: 'auth',
-                method: 'auth.loadUser',
-                userId,
-              }, loadUserError);
+                method: 'auth',
+              }, validationError);
             }
-          }
 
-          if (debug) {
-            logger.debug(`[oxy.auth] OK user=${userId} (no session)`, {
-              component: 'auth',
-              method: 'auth',
-            });
-          }
+            if (optional) {
+              req.userId = null;
+              req.user = null;
+              return next();
+            }
 
-          next();
+            const error = {
+              error: 'SESSION_VALIDATION_ERROR',
+              message: 'Session validation failed',
+              code: 'SESSION_VALIDATION_ERROR',
+              status: 401
+            };
+            if (onError) return onError(error);
+            return res.status(401).json(error);
+          }
         } catch (error) {
           const handled = oxyInstance.handleError(error) as Error & {
             code?: string;
@@ -768,7 +812,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             return next(new Error('Invalid token'));
           }
 
-          const claimedUserId = decoded.userId || decoded.id;
+          const claimedUserId = readStringClaim(decoded.userId) ?? readStringClaim(decoded.id);
           if (!claimedUserId) {
             return next(new Error('Invalid token payload'));
           }
@@ -781,13 +825,14 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
           // A server-validated session is mandatory. A bare decoded JWT proves
           // nothing — the signature is not verified here, so without a session
           // round-trip a forged token could claim any user id.
-          if (!decoded.sessionId) {
+          const sessionId = readStringClaim(decoded.sessionId);
+          if (!sessionId) {
             return next(new Error('Session required'));
           }
 
           let userId = claimedUserId;
           try {
-            const result = await oxyInstance.validateSession(decoded.sessionId, {
+            const result = await oxyInstance.validateSession(sessionId, {
               useHeaderValidation: true,
             });
             if (!result || !result.valid || !result.user) {
@@ -819,10 +864,10 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
           // reads from `socket.user.id`.
           socket.data = socket.data || {};
           socket.data.userId = userId;
-          socket.data.sessionId = decoded.sessionId || null;
+          socket.data.sessionId = sessionId;
           socket.data.token = token;
 
-          socket.user = { id: userId, userId, sessionId: decoded.sessionId };
+          socket.user = { id: userId, userId, sessionId };
 
           if (debug) {
             logger.debug(`[oxy.authSocket] OK user=${userId}`, {
@@ -978,12 +1023,17 @@ async function verifyServiceTokenSignature(token: string, secret: string): Promi
 }
 
 /**
- * Verify that a decoded service-token payload carries the expected `aud`,
- * `iss`, and `type` claims. Throws `ServiceTokenClaimError` on mismatch.
- * This is the defence against the H4 vulnerability where a recovery / 2FA /
- * access token signed by the same shared secret could be replayed as a
- * service token because no claim binding existed.
+ * Read a JWT claim that is only usable as a non-empty string.
+ *
+ * A decoded payload is attacker-controlled JSON: a claim the type declares as
+ * `string` can arrive as a number, an object, or `null`. Narrowing here keeps
+ * those values out of URL construction and identity comparison, so an
+ * unexpected shape becomes a 401 rather than a stringified surprise.
  */
+function readStringClaim(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
 /**
  * Resolve the canonical user id from a validated session's user object.
  *
@@ -997,6 +1047,13 @@ function getUserIdentityId(user: User): string | null {
   return typeof candidate === 'string' && candidate.length > 0 ? candidate : null;
 }
 
+/**
+ * Verify that a decoded service-token payload carries the expected `aud`,
+ * `iss`, and `type` claims. Throws `ServiceTokenClaimError` on mismatch.
+ * This is the defence against the H4 vulnerability where a recovery / 2FA /
+ * access token signed by the same shared secret could be replayed as a
+ * service token because no claim binding existed.
+ */
 function verifyServiceTokenClaims(
   decoded: JwtPayload,
   expected: { audience: string; issuer: string },
@@ -1062,9 +1119,5 @@ interface OxyAuthInstance {
     user?: User;
     [key: string]: unknown;
   } | null>;
-  getAccessToken(): string | null;
-  setTokens(accessToken: string): void;
-  clearTokens(): void;
-  getCurrentUser(): Promise<User | null>;
   handleError(error: unknown): Error;
 }

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

@@ -0,0 +1,113 @@
+/**
+ * The chains client — what it puts on the wire.
+ *
+ * There is exactly one piece of real logic here and it is the read's query
+ * string: joining two lists, and including `since`/`limit` only when the caller
+ * gave them. Everything else is a pass-through, so these cases pin the part that
+ * can actually be wrong rather than restating the method bodies.
+ *
+ * `makeServiceRequest` is stubbed because it belongs to the auth mixin and has
+ * its own suites; what matters here is the method, path and payload it is handed.
+ */
+
+import { OxyServicesChainsMixin } from '../OxyServices.chains';
+
+type Call = { method: string; url: string; data?: unknown };
+
+/** A minimal host carrying the mixin, with the service transport recorded. */
+function client(): { calls: Call[]; api: any } {
+  const calls: Call[] = [];
+  class Base {
+    makeServiceRequest(method: string, url: string, data?: unknown) {
+      calls.push({ method, url, data });
+      return Promise.resolve({ records: [], nextCursor: null });
+    }
+  }
+  const Mixed = OxyServicesChainsMixin(Base as any);
+  return { calls, api: new (Mixed as any)() };
+}
+
+describe('appendChainRecord', () => {
+  it('POSTs the record to /chains/records untouched', async () => {
+    const { calls, api } = client();
+
+    await api.appendChainRecord({
+      oxyUserId: 'u1',
+      collection: 'app.mention.feed.post',
+      rkey: 'p1',
+      record: { text: 'hi' },
+    });
+
+    expect(calls).toEqual([
+      {
+        method: 'POST',
+        url: '/chains/records',
+        data: {
+          oxyUserId: 'u1',
+          collection: 'app.mention.feed.post',
+          rkey: 'p1',
+          record: { text: 'hi' },
+        },
+      },
+    ]);
+  });
+});
+
+describe('readChainRecords', () => {
+  it('joins authors and collections into one comma-separated query each', async () => {
+    const { calls, api } = client();
+
+    await api.readChainRecords({
+      oxyUserIds: ['u1', 'u2'],
+      collections: ['app.mention.feed.post', 'app.mention.feed.like'],
+    });
+
+    const url = new URL(`http://x${calls[0].url}`);
+    expect(calls[0].method).toBe('GET');
+    expect(url.pathname).toBe('/chains/records');
+    expect(url.searchParams.get('authors')).toBe('u1,u2');
+    expect(url.searchParams.get('collections')).toBe('app.mention.feed.post,app.mention.feed.like');
+  });
+
+  it('omits since and limit when the caller gave neither', async () => {
+    // A `since=` or `limit=` sent as an empty string is not the same request —
+    // the server validates both, so an always-present key would 400 a first page.
+    const { calls, api } = client();
+
+    await api.readChainRecords({ oxyUserIds: ['u1'], collections: ['app.mention.feed.post'] });
+
+    const url = new URL(`http://x${calls[0].url}`);
+    expect(url.searchParams.has('since')).toBe(false);
+    expect(url.searchParams.has('limit')).toBe(false);
+  });
+
+  it('sends since and limit when it did', async () => {
+    const { calls, api } = client();
+
+    await api.readChainRecords({
+      oxyUserIds: ['u1'],
+      collections: ['app.mention.feed.post'],
+      since: 'Y3Vyc29y',
+      limit: 25,
+    });
+
+    const url = new URL(`http://x${calls[0].url}`);
+    expect(url.searchParams.get('since')).toBe('Y3Vyc29y');
+    expect(url.searchParams.get('limit')).toBe('25');
+  });
+
+  it('escapes a cursor that is not URL-safe', async () => {
+    // Cursors are opaque to the caller, so this client must not assume the
+    // encoding the server happens to use today.
+    const { calls, api } = client();
+
+    await api.readChainRecords({
+      oxyUserIds: ['u1'],
+      collections: ['app.mention.feed.post'],
+      since: 'a+b/c=',
+    });
+
+    const url = new URL(`http://x${calls[0].url}`);
+    expect(url.searchParams.get('since')).toBe('a+b/c=');
+  });
+});

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

@@ -158,7 +158,40 @@ describe('pre-session public endpoints use skipAuth', () => {
     });
   });
 
-  it('exchangeOAuthCode rejects a response without deviceSecret', async () => {
+  // A third-party grant is meant to be ISOLATED from the browser's shared
+  // DeviceSession, so the token endpoint must be free to return no device
+  // credential. Core used to require the pair, which made that omission
+  // unshippable: every third-party sign-in through the SDK would have collapsed
+  // into a silent `exchange-failed` (issue #954).
+  it('exchangeOAuthCode accepts a device-less grant and still plants the token', async () => {
+    makeRequest.mockResolvedValueOnce({
+      access_token: 'tok',
+      token_type: 'Bearer',
+      expires_in: 900,
+      session_id: 's1',
+      user: { id: 'u1', username: 'alice' },
+    });
+
+    const result = await oxy.exchangeOAuthCode({
+      code: 'code-1',
+      clientId: 'oxy_dk_test',
+      redirectUri: 'https://app.example/callback',
+      codeVerifier: 'verifier',
+    });
+
+    expect(result).toMatchObject({
+      sessionId: 's1',
+      accessToken: 'tok',
+      user: { id: 'u1', username: 'alice' },
+    });
+    // Absent, not `undefined`-valued: a device-less grant carries no device keys
+    // at all, so nothing downstream can read one and persist an empty credential.
+    expect(result).not.toHaveProperty('deviceId');
+    expect(result).not.toHaveProperty('deviceSecret');
+    expect(oxy.getAccessToken()).toBe('tok');
+  });
+
+  it('exchangeOAuthCode accepts a deviceId with no deviceSecret', async () => {
     makeRequest.mockResolvedValueOnce({
       access_token: 'tok',
       token_type: 'Bearer',
@@ -167,6 +200,26 @@ describe('pre-session public endpoints use skipAuth', () => {
       deviceId: 'd1',
       user: { id: 'u1' },
     });
+
+    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' });
+    expect(result).not.toHaveProperty('deviceSecret');
+  });
+
+  // The device pair left the guard; what identifies the session did NOT. Without
+  // these two the whole guard could be deleted and every test above would stay
+  // green — `sessionId` would silently become `undefined` on the returned session.
+  it.each([
+    ['session_id', { access_token: 'tok', expires_in: 900, user: { id: 'u1' } }],
+    ['user', { access_token: 'tok', expires_in: 900, session_id: 's1' }],
+  ])('exchangeOAuthCode still rejects a response missing %s', async (_field, response) => {
+    makeRequest.mockResolvedValueOnce(response);
     await expect(
       oxy.exchangeOAuthCode({
         code: 'code-1',