@oxyhq/core 3.4.11 → 3.4.13

package/dist/types/server/auth.d.ts

@@ -0,0 +1,52 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import type { OxyServices } from '../OxyServices';
+export interface OxyRequestUser {
+    id: string;
+    _id?: string;
+    username?: string;
+    email?: string;
+    avatar?: string;
+    [key: string]: unknown;
+}
+export interface OxyActingAsContext {
+    userId: string;
+    role: 'owner' | 'admin' | 'editor';
+}
+export interface OxyServiceAppContext {
+    appId: string;
+    appName: string;
+    scopes: string[];
+    credentialId: string;
+}
+export interface OxyServiceActingAsContext {
+    userId: string;
+    scopes: string[];
+}
+export interface OxyAuthRequest extends Request {
+    userId?: string | null;
+    user?: OxyRequestUser | null;
+    originalUser?: OxyRequestUser | null;
+    actingAs?: OxyActingAsContext;
+    accessToken?: string;
+    sessionId?: string | null;
+    serviceApp?: OxyServiceAppContext;
+    serviceActingAs?: OxyServiceActingAsContext;
+}
+export interface OxyAuthenticatedRequest extends OxyAuthRequest {
+    userId: string;
+    user: OxyRequestUser;
+}
+export interface OxyAuthMiddlewareOptions {
+    /**
+     * Options forwarded to `oxy.auth()`.
+     * `optional` is forced to `true` by the composed helpers so route guards can
+     * produce one consistent 401 shape.
+     */
+    auth?: Parameters<OxyServices['auth']>[0];
+}
+export declare function getOxyUserId(req: Request): string | null;
+export declare function isOxyAuthenticated(req: Request): req is OxyAuthenticatedRequest;
+export declare function getRequiredOxyUserId(req: Request): string;
+export declare function requireOxyAuth(req: Request, res: Response, next: NextFunction): void;
+export declare function createOptionalOxyAuth(oxy: OxyServices, options?: OxyAuthMiddlewareOptions): RequestHandler;
+export declare function createOxyAuthMiddleware(oxy: OxyServices, options?: OxyAuthMiddlewareOptions): RequestHandler;

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

@@ -14,5 +14,7 @@
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * ```
  */
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, } from './auth';
+export type { OxyActingAsContext, OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, } from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.4.11",
+  "version": "3.4.13",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/__tests__/httpServiceCsrf.test.ts

@@ -2,7 +2,7 @@ import { HttpService } from '../HttpService';
 
 interface FetchCall {
   url: string;
-  init: RequestInit;
+  init: RequestInit | undefined;
 }
 
 function createJwt(payload: Record<string, unknown>): string {
@@ -41,11 +41,11 @@ describe('HttpService CSRF behavior', () => {
 
   it('does not fetch csrf-token before bearer-authenticated writes', async () => {
     const calls: FetchCall[] = [];
-    const fetchMock = jest.fn(async (url: string, init: RequestInit) => {
+    globalThis.fetch = async (input, init) => {
+      const url = String(input);
       calls.push({ url, init });
       return jsonResponse({ ok: true });
-    });
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    };
 
     const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
     const accessToken = createJwt({
@@ -65,7 +65,8 @@ describe('HttpService CSRF behavior', () => {
 
   it('still fetches csrf-token for cookie-authenticated writes without bearer', async () => {
     const calls: FetchCall[] = [];
-    const fetchMock = jest.fn(async (url: string, init: RequestInit) => {
+    globalThis.fetch = async (input, init) => {
+      const url = String(input);
       calls.push({ url, init });
       if (url.endsWith('/csrf-token')) {
         return new Response(JSON.stringify({ csrfToken: 'csrf_1' }), {
@@ -74,8 +75,7 @@ describe('HttpService CSRF behavior', () => {
         });
       }
       return jsonResponse({ ok: true });
-    });
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    };
 
     const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
 

package/src/__tests__/userIdentity.test.ts

@@ -3,7 +3,7 @@ import { getNormalizedUserId, normalizeUserIdentity } from '../utils/userIdentit
 
 interface FetchCall {
   url: string;
-  init: RequestInit;
+  init: RequestInit | undefined;
 }
 
 function jsonResponse(data: unknown): Response {
@@ -37,11 +37,11 @@ describe('user identity normalization', () => {
 
   it('normalizes getCurrentUser responses before exposing them to apps', async () => {
     const calls: FetchCall[] = [];
-    const fetchMock = jest.fn(async (url: string, init: RequestInit) => {
+    globalThis.fetch = async (input, init) => {
+      const url = String(input);
       calls.push({ url, init });
       return jsonResponse({ _id: 'user_1', username: 'nate', publicKey: 'pub_1' });
-    });
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    };
 
     const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
     oxy.setTokens(createJwt({
@@ -56,15 +56,13 @@ describe('user identity normalization', () => {
   });
 
   it('normalizes validateSession users before services stores them', async () => {
-    const fetchMock = jest.fn(async () =>
+    globalThis.fetch = async () =>
       jsonResponse({
         valid: true,
         expiresAt: '2099-01-01T00:00:00.000Z',
         lastActivity: '2026-06-18T00:00:00.000Z',
         user: { _id: 'user_1', username: 'nate', publicKey: 'pub_1' },
-      }),
-    );
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+      });
 
     const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
     const validation = await oxy.validateSession('session_1', { useHeaderValidation: true });

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

@@ -0,0 +1,78 @@
+import type { NextFunction, Request, Response } from 'express';
+import type { OxyServices } from '../../OxyServices';
+import {
+  createOxyAuthMiddleware,
+  getOxyUserId,
+  getRequiredOxyUserId,
+  requireOxyAuth,
+  type OxyAuthRequest,
+} from '../auth';
+
+function makeResponse(): Response {
+  return {
+    status: jest.fn().mockReturnThis(),
+    json: jest.fn().mockReturnThis(),
+  } as unknown as Response;
+}
+
+function makeNext(): NextFunction {
+  return jest.fn() as unknown as NextFunction;
+}
+
+describe('@oxyhq/core/server auth helpers', () => {
+  it('reads the current user id from userId, user.id, or user._id', () => {
+    expect(getOxyUserId({ userId: 'user-from-request' } as OxyAuthRequest)).toBe('user-from-request');
+    expect(getOxyUserId({ user: { id: 'user-from-id' } } as OxyAuthRequest)).toBe('user-from-id');
+    expect(getOxyUserId({ user: { id: '', _id: 'user-from-mongo-id' } } as OxyAuthRequest)).toBe('user-from-mongo-id');
+    expect(getOxyUserId({ user: { id: '' } } as OxyAuthRequest)).toBeNull();
+  });
+
+  it('throws when a required user id is missing', () => {
+    expect(() => getRequiredOxyUserId({} as Request)).toThrow('User not authenticated');
+  });
+
+  it('returns a consistent 401 when auth is missing', () => {
+    const req = {} as Request;
+    const res = makeResponse();
+    const next = makeNext();
+
+    requireOxyAuth(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'Unauthorized',
+      message: 'Authentication required',
+    });
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('normalizes an authenticated request before continuing', () => {
+    const req = { user: { id: '', _id: 'mongo-user-id' } } as OxyAuthRequest;
+    const res = makeResponse();
+    const next = makeNext();
+
+    requireOxyAuth(req, res, next);
+
+    expect(req.userId).toBe('mongo-user-id');
+    expect(req.user?.id).toBe('mongo-user-id');
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('can resolve and require auth as one middleware', () => {
+    const oxy = {
+      auth: jest.fn(() => (req: OxyAuthRequest, _res: Response, next: NextFunction) => {
+        req.user = { id: 'resolved-user' };
+        next();
+      }),
+    } as unknown as OxyServices;
+    const req = {} as OxyAuthRequest;
+    const res = makeResponse();
+    const next = makeNext();
+
+    createOxyAuthMiddleware(oxy)(req, res, next);
+
+    expect(oxy.auth).toHaveBeenCalledWith({ optional: true });
+    expect(req.userId).toBe('resolved-user');
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});

package/src/server/auth.ts

@@ -0,0 +1,155 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import type { OxyServices } from '../OxyServices';
+
+export interface OxyRequestUser {
+  id: string;
+  _id?: string;
+  username?: string;
+  email?: string;
+  avatar?: string;
+  [key: string]: unknown;
+}
+
+export interface OxyActingAsContext {
+  userId: string;
+  role: 'owner' | 'admin' | 'editor';
+}
+
+export interface OxyServiceAppContext {
+  appId: string;
+  appName: string;
+  scopes: string[];
+  credentialId: string;
+}
+
+export interface OxyServiceActingAsContext {
+  userId: string;
+  scopes: string[];
+}
+
+export interface OxyAuthRequest extends Request {
+  userId?: string | null;
+  user?: OxyRequestUser | null;
+  originalUser?: OxyRequestUser | null;
+  actingAs?: OxyActingAsContext;
+  accessToken?: string;
+  sessionId?: string | null;
+  serviceApp?: OxyServiceAppContext;
+  serviceActingAs?: OxyServiceActingAsContext;
+}
+
+export interface OxyAuthenticatedRequest extends OxyAuthRequest {
+  userId: string;
+  user: OxyRequestUser;
+}
+
+export interface OxyAuthMiddlewareOptions {
+  /**
+   * Options forwarded to `oxy.auth()`.
+   * `optional` is forced to `true` by the composed helpers so route guards can
+   * produce one consistent 401 shape.
+   */
+  auth?: Parameters<OxyServices['auth']>[0];
+}
+
+function normalizeId(value: string | null | undefined): string | null {
+  const normalized = value?.trim();
+  return normalized && normalized.length > 0 ? normalized : null;
+}
+
+function ensureUser(req: OxyAuthRequest, userId: string): OxyRequestUser {
+  const existing = req.user;
+  if (existing) {
+    const user = {
+      ...existing,
+      id: normalizeId(existing.id) ?? normalizeId(existing._id) ?? userId,
+    };
+    req.user = user;
+    return user;
+  }
+
+  const user = { id: userId };
+  req.user = user;
+  return user;
+}
+
+export function getOxyUserId(req: Request): string | null {
+  const authReq = req as OxyAuthRequest;
+  return (
+    normalizeId(authReq.userId) ??
+    normalizeId(authReq.user?.id) ??
+    normalizeId(authReq.user?._id)
+  );
+}
+
+export function isOxyAuthenticated(req: Request): req is OxyAuthenticatedRequest {
+  return getOxyUserId(req) !== null;
+}
+
+export function getRequiredOxyUserId(req: Request): string {
+  const userId = getOxyUserId(req);
+  if (!userId) {
+    throw new Error('User not authenticated');
+  }
+  return userId;
+}
+
+export function requireOxyAuth(req: Request, res: Response, next: NextFunction): void {
+  const userId = getOxyUserId(req);
+  if (!userId) {
+    res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Authentication required',
+    });
+    return;
+  }
+
+  const authReq = req as OxyAuthRequest;
+  authReq.userId = userId;
+  ensureUser(authReq, userId);
+  next();
+}
+
+export function createOptionalOxyAuth(
+  oxy: OxyServices,
+  options: OxyAuthMiddlewareOptions = {},
+): RequestHandler {
+  const resolveSession = oxy.auth({ ...options.auth, optional: true });
+
+  return (req, res, next) => {
+    if (getOxyUserId(req)) {
+      next();
+      return;
+    }
+
+    resolveSession(req, res, (error?: unknown) => {
+      if (error) {
+        next(error);
+        return;
+      }
+      next();
+    });
+  };
+}
+
+export function createOxyAuthMiddleware(
+  oxy: OxyServices,
+  options: OxyAuthMiddlewareOptions = {},
+): RequestHandler {
+  const resolveSession = createOptionalOxyAuth(oxy, options);
+
+  return (req, res, next) => {
+    if (getOxyUserId(req)) {
+      requireOxyAuth(req, res, next);
+      return;
+    }
+
+    resolveSession(req, res, (error?: unknown) => {
+      if (error) {
+        next(error);
+        return;
+      }
+      requireOxyAuth(req, res, next);
+    });
+  };
+}

package/src/server/index.ts

@@ -15,5 +15,22 @@
  * ```
  */
 
+export {
+  createOptionalOxyAuth,
+  createOxyAuthMiddleware,
+  getOxyUserId,
+  getRequiredOxyUserId,
+  isOxyAuthenticated,
+  requireOxyAuth,
+} from './auth';
+export type {
+  OxyActingAsContext,
+  OxyAuthenticatedRequest,
+  OxyAuthMiddlewareOptions,
+  OxyAuthRequest,
+  OxyRequestUser,
+  OxyServiceActingAsContext,
+  OxyServiceAppContext,
+} from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';