bhooai-nexus 0.1.2

package/packages/nexus-ai-client/src/types.ts

@@ -0,0 +1,174 @@
+/** Types mirroring contracts/ai-openapi.yaml — the Node↔Python AI boundary. */
+
+export type Provider = 'openai' | 'ollama' | 'auto';
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+
+export interface Message {
+  role: Role;
+  content: string;
+  name?: string;
+}
+
+export interface ChatCompletionRequest {
+  model: string;
+  messages: Message[];
+  stream?: boolean;
+  temperature?: number;
+  max_tokens?: number;
+  provider?: Provider;
+}
+
+export interface Choice {
+  index: number;
+  message: Message;
+  finish_reason: string | null;
+}
+
+export interface Usage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+}
+
+export interface ChatCompletionResponse {
+  id?: string;
+  model: string;
+  provider?: string;
+  choices: Choice[];
+  usage?: Usage;
+}
+
+export interface Delta {
+  role?: Role;
+  content?: string;
+}
+
+export interface ChunkChoice {
+  index: number;
+  delta: Delta;
+  finish_reason: string | null;
+}
+
+export interface ChatCompletionChunk {
+  id?: string;
+  model: string;
+  provider?: string;
+  choices: ChunkChoice[];
+}
+
+export interface EmbeddingRequest {
+  model: string;
+  input: string | string[];
+  provider?: Provider;
+}
+
+export interface EmbeddingData {
+  index: number;
+  embedding: number[];
+}
+
+export interface EmbeddingResponse {
+  model: string;
+  provider?: string;
+  data: EmbeddingData[];
+  usage?: Usage;
+}
+
+export interface ModelInfo {
+  id: string;
+  owned_by?: string;
+}
+
+export interface ModelsResponse {
+  provider?: string;
+  data: ModelInfo[];
+}
+
+export interface AiClientOptions {
+  /** AI server base URL, e.g. http://localhost:8000. */
+  serverUrl: string;
+  /** Request timeout in ms (default 60000). */
+  timeoutMs?: number;
+  /** Max retry attempts on network/5xx errors (default 2). */
+  maxRetries?: number;
+  /** Base delay for exponential backoff in ms (default 500). */
+  retryDelayMs?: number;
+  /** Optional Bearer token sent to the AI server. */
+  authToken?: string;
+}
+
+// ── Image generation (local Stable Diffusion HTTP server) ──────────────────
+// OpenAI-compatible /images/generations surface, plus the agentic loop.
+
+export interface ImageGenRequest {
+  prompt: string;
+  n?: number;
+  size?: string;
+  model?: string;
+  negative_prompt?: string;
+  steps?: number;
+  sampler?: string;
+  seed?: number;
+}
+
+export interface ImageGenData {
+  b64_json?: string;
+  url?: string;
+}
+
+export interface ImageGenMeta {
+  prompt: string;
+  negative_prompt: string;
+  model: string;
+  steps: number;
+  width: number;
+  height: number;
+  sampler: string;
+  seed: number | null;
+  n: number;
+  api: string;
+}
+
+export interface ImageGenResponse {
+  created: number;
+  data: ImageGenData[];
+  meta?: ImageGenMeta;
+}
+
+export interface ImageGenModelsResponse {
+  api: string;
+  data: Array<{ id: string; title: string }>;
+}
+
+// ── Agentic image loop ─────────────────────────────────────────────────────
+
+export interface AgentImageRequest {
+  /** The user's rough idea, e.g. "a cyberpunk fox in neon rain". */
+  idea: string;
+  /** Max agent iterations (default from server config). */
+  max_iterations?: number;
+}
+
+/** SSE event emitted by POST /agent/image. Discriminated by `type`. */
+export type AgentImageEvent =
+  | { type: 'thinking'; content: string; iteration: number }
+  | { type: 'tool'; name: string; args: Record<string, unknown>; iteration: number }
+  | { type: 'tool_error'; name: string; message: string; iteration: number }
+  | { type: 'image'; b64: string; prompt: string; iteration: number }
+  | { type: 'error'; message: string }
+  | AgentImageDoneEvent;
+
+export interface AgentImageDoneEvent {
+  type: 'done';
+  image_b64: string;
+  prompt: string;
+  negative_prompt: string;
+  style?: string | null;
+  aspect_ratio?: string | null;
+  model: string;
+  steps: number;
+  sampler?: string | null;
+  seed?: number | null;
+  iterations: number;
+  critique_log: Array<{ score?: number; feedback?: string; suggestions?: string[] }>;
+}

package/packages/nexus-auth/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@bhooai/nexus-auth",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0",
+    "bcryptjs": "^2.4.3",
+    "jose": "^5.9.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/packages/nexus-auth/src/auth.ts

@@ -0,0 +1,116 @@
+import { randomBytes } from 'node:crypto';
+import { signAccessToken, verifyToken, type JwtOptions, type TokenPayload } from './jwt.js';
+import type { SessionStore, Session } from './session.js';
+import { AuthenticationError } from '../../nexus-core/src/index.js';
+
+export interface TokenPair {
+  accessToken: string;
+  refreshToken: string;
+  sessionId: string;
+  /** Refresh-token expiry (ms epoch). */
+  refreshExpiresAt: number;
+}
+
+export interface LoginInput {
+  userId: string;
+  roles: string[];
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * High-level auth orchestrator. The app verifies credentials (via
+ * `verifyPassword` + its user store) and calls `login()` to mint a session and
+ * token pair. Refresh tokens are rotated on every refresh and bound to a
+ * session family, so reuse of a previously-rotated token revokes the whole
+ * family (refresh-token theft detection).
+ */
+export class AuthService {
+  constructor(
+    private jwt: JwtOptions,
+    private sessions: SessionStore,
+  ) {}
+
+  /** Create a session and return an access + refresh token pair. */
+  async login(input: LoginInput): Promise<TokenPair> {
+    const session = await this.sessions.create(input.userId, input.roles, input.meta);
+    return this.mintPair(session);
+  }
+
+  /**
+   * Verify a refresh token, rotate it (new jti), and return a fresh pair.
+   * If the presented refresh token's jti no longer matches the session's
+   * current jti, the token has been reused after rotation → revoke the family.
+   */
+  async refresh(refreshToken: string): Promise<TokenPair> {
+    let payload: TokenPayload;
+    try {
+      payload = await verifyToken(refreshToken, this.jwt);
+    } catch {
+      throw new AuthenticationError('Invalid refresh token');
+    }
+    if (payload.kind !== 'refresh' || !payload.sid) {
+      throw new AuthenticationError('Not a refresh token');
+    }
+    const session = await this.sessions.get(payload.sid);
+    if (!session) throw new AuthenticationError('Session expired');
+
+    // Reuse detection: the jti on the session must match the presented token.
+    if (session.currentJti && payload.jti && session.currentJti !== payload.jti) {
+      await this.sessions.destroyFamily(session.familyId);
+      throw new AuthenticationError('Refresh token reuse detected; session revoked');
+    }
+
+    return this.mintPair(session);
+  }
+
+  /** End a single session (logout). */
+  async logout(sessionId: string): Promise<void> {
+    await this.sessions.destroy(sessionId);
+  }
+
+  /** End every session for a user (logout everywhere). */
+  async logoutAll(userId: string): Promise<void> {
+    await this.sessions.destroyAllForUser(userId);
+  }
+
+  /** Verify an access token and return its payload (for the auth middleware). */
+  async verifyAccessToken(accessToken: string): Promise<TokenPayload> {
+    try {
+      const payload = await verifyToken(accessToken, this.jwt);
+      if (payload.kind && payload.kind !== 'access') {
+        throw new AuthenticationError('Not an access token');
+      }
+      return payload;
+    } catch (e) {
+      if (e instanceof AuthenticationError) throw e;
+      throw new AuthenticationError('Invalid access token');
+    }
+  }
+
+  private async mintPair(session: Session): Promise<TokenPair> {
+    const jti = randomBytes(12).toString('base64url');
+    // Record the issued refresh jti on the session for reuse detection.
+    await this.sessions.update(session.id, { currentJti: jti });
+    const access = await signAccessToken(session.userId, session.roles, this.jwt, session.id);
+    const refresh = await this.signRefreshWithJti(session, jti);
+    const refreshExpiresAt = Date.now() + (this.jwt.refreshTtl ?? 60 * 60 * 24 * 7) * 1000;
+    return { accessToken: access, refreshToken: refresh, sessionId: session.id, refreshExpiresAt };
+  }
+
+  private async signRefreshWithJti(session: Session, jti: string): Promise<string> {
+    // Re-use the jose SignJWT path by importing here to inject jti.
+    const { SignJWT } = await import('jose');
+    const ttl = this.jwt.refreshTtl ?? 60 * 60 * 24 * 7;
+    const secret =
+      typeof this.jwt.secret === 'string' ? new TextEncoder().encode(this.jwt.secret) : this.jwt.secret;
+    const builder = new SignJWT({ kind: 'refresh', roles: session.roles, sid: session.id })
+      .setProtectedHeader({ alg: this.jwt.algorithm ?? 'HS256' })
+      .setSubject(session.userId)
+      .setJti(jti)
+      .setIssuedAt()
+      .setExpirationTime(`${ttl}s`);
+    if (this.jwt.issuer) builder.setIssuer(this.jwt.issuer);
+    if (this.jwt.audience) builder.setAudience(this.jwt.audience);
+    return builder.sign(secret);
+  }
+}

package/packages/nexus-auth/src/bcryptjs.d.ts

@@ -0,0 +1,10 @@
+declare module 'bcryptjs' {
+  interface Bcrypt {
+    genSalt(rounds: number): Promise<string>;
+    hash(plaintext: string, salt: string): Promise<string>;
+    compare(plaintext: string, hash: string): Promise<boolean>;
+  }
+
+  const bcrypt: Bcrypt;
+  export default bcrypt;
+}

package/packages/nexus-auth/src/cors.ts

@@ -0,0 +1,91 @@
+import type { Middleware } from '../../nexus-core/src/http/index.js';
+
+export interface CorsOptions {
+  /** Allowed origin(s): a string, an array, or true to reflect any origin. */
+  origin?: string | string[] | boolean;
+  /** Allowed methods. */
+  methods?: string[];
+  /** Allowed request headers. */
+  allowedHeaders?: string[];
+  /** Headers exposed to the browser. */
+  exposedHeaders?: string[];
+  /** Allow cookies / credentials. When true, origin cannot be "*". */
+  credentials?: boolean;
+  /** Preflight cache max age in seconds. */
+  maxAge?: number;
+}
+
+const DEFAULT_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'];
+
+/**
+ * Inbuilt CORS middleware. Owns the OPTIONS preflight path entirely, sets
+ * `Vary: Origin` for correct cache behavior, and enforces the credentialed
+ * rule (no wildcard origin when credentials are enabled).
+ */
+export function cors(options: CorsOptions = {}): Middleware {
+  const opts = {
+    origin: options.origin ?? true,
+    methods: options.methods ?? DEFAULT_METHODS,
+    allowedHeaders: options.allowedHeaders,
+    exposedHeaders: options.exposedHeaders,
+    credentials: options.credentials ?? false,
+    maxAge: options.maxAge ?? 600,
+  };
+
+  return async (ctx, next) => {
+    const reqOrigin = (ctx.headers['origin'] as string) ?? '';
+    const allowedOrigin = resolveOrigin(opts.origin, reqOrigin, opts.credentials);
+
+    // Always vary by origin so caches don't leak the wrong CORS headers.
+    appendVary(ctx, 'Origin');
+
+    if (allowedOrigin) {
+      ctx.setHeader('access-control-allow-origin', allowedOrigin);
+      if (opts.credentials) ctx.setHeader('access-control-allow-credentials', 'true');
+      if (opts.exposedHeaders?.length) {
+        ctx.setHeader('access-control-expose-headers', opts.exposedHeaders.join(', '));
+      }
+    }
+
+    if (ctx.method === 'OPTIONS' && ctx.headers['access-control-request-method']) {
+      // Preflight: short-circuit
+      ctx.setHeader('access-control-allow-methods', opts.methods.join(', '));
+      const reqHeaders = (ctx.headers['access-control-request-headers'] as string) ?? '';
+      ctx.setHeader('access-control-allow-headers', (opts.allowedHeaders ?? reqHeaders) || '*');
+      ctx.setHeader('access-control-max-age', String(opts.maxAge));
+      ctx.status(204);
+      return;
+    }
+
+    await next();
+  };
+}
+
+function resolveOrigin(
+  config: string | string[] | boolean,
+  requestOrigin: string,
+  credentials: boolean,
+): string | undefined {
+  if (config === true) {
+    // Reflect the request origin (works with credentials); no "*" when credentialed.
+    return requestOrigin || (credentials ? undefined : '*');
+  }
+  if (typeof config === 'string') {
+    if (config === '*') return credentials ? requestOrigin || undefined : '*';
+    return config === requestOrigin ? config : undefined;
+  }
+  if (Array.isArray(config)) {
+    return config.includes(requestOrigin) ? requestOrigin : undefined;
+  }
+  return undefined;
+}
+
+function appendVary(ctx: Parameters<Middleware>[0], value: string): void {
+  const existing = ctx.res.getHeader('vary');
+  if (existing === undefined) {
+    ctx.setHeader('vary', value);
+  } else {
+    const merged = `${existing}, ${value}`;
+    ctx.setHeader('vary', merged);
+  }
+}

package/packages/nexus-auth/src/csrf.ts

@@ -0,0 +1,158 @@
+import { randomBytes } from 'node:crypto';
+import type { Middleware, RequestContext } from '../../nexus-core/src/http/index.js';
+import { AuthenticationError } from '../../nexus-core/src/index.js';
+
+export interface CsrfOptions {
+  /** Cookie name holding the double-submit token. */
+  cookieName?: string;
+  /** Header / body field name carrying the token on unsafe requests. */
+  tokenName?: string;
+  /** Trusted origin hosts (for the origin/referer check). If omitted, origin check is skipped. */
+  trustedOrigins?: string[];
+  /** Methods exempt from CSRF (safe methods). */
+  safeMethods?: string[];
+  /** Cookie attributes. */
+  cookie?: { path?: string; secure?: boolean; sameSite?: 'strict' | 'lax' | 'none'; domain?: string };
+}
+
+const SAFE = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE']);
+
+/**
+ * Inbuilt CSRF protection using the double-submit cookie pattern plus an
+ * origin/referer check on unsafe requests. Safe methods are exempt.
+ *
+ * On a safe request, a token cookie is set (rotated each request) and exposed
+ * via `ctx.state.csrfToken` so handlers can return it to clients. On unsafe
+ * requests, the header token must equal the cookie token.
+ */
+export function csrf(options: CsrfOptions = {}): Middleware {
+  const cookieName = options.cookieName ?? 'nexus_csrf';
+  const tokenName = options.tokenName ?? 'x-csrf-token';
+  const trusted = options.trustedOrigins ?? [];
+  const safeMethods = new Set(options.safeMethods ?? [...SAFE]);
+  const cookieOpts = options.cookie ?? { path: '/', sameSite: 'lax', secure: false };
+
+  return async (ctx, next) => {
+    if (safeMethods.has(ctx.method)) {
+      // Reuse an existing cookie token so concurrent safe requests (e.g. the
+      // 5-second cluster overview poll) don't rotate the token out from under
+      // a pending unsafe request — that race produced "Unauthorized" on POSTs.
+      const existing = readCookie(ctx, cookieName);
+      if (existing) {
+        ctx.state.csrfToken = existing;
+      } else {
+        ctx.state.csrfToken = issueToken(ctx, cookieName, cookieOpts);
+      }
+      await next();
+      return;
+    }
+
+    // Unsafe method: validate origin/referer first.
+    checkOrigin(ctx, trusted);
+
+    // Then double-submit: header token must match cookie token.
+    const cookieToken = readCookie(ctx, cookieName);
+    const sentToken =
+      (ctx.headers[tokenName] as string) ??
+      (ctx.body && typeof ctx.body === 'object' ? (ctx.body as Record<string, unknown>)[tokenName] as string : undefined);
+
+    if (!cookieToken || !sentToken || !timingSafeEqual(cookieToken, sentToken)) {
+      throw new AuthenticationError('Invalid CSRF token');
+    }
+    await next();
+  };
+}
+
+/** Helper for handlers/endpoints to mint a token (e.g. a /csrf-token route). */
+export function issueCsrfToken(ctx: RequestContext, options: CsrfOptions = {}): string {
+  return issueToken(ctx, options.cookieName ?? 'nexus_csrf', options.cookie ?? { path: '/', sameSite: 'lax', secure: false });
+}
+
+/** CSRF + origin check for the WebSocket upgrade request (no CORS preflight). */
+export function checkWsUpgrade(headers: Record<string, string | string[] | undefined>, options: CsrfOptions = {}): void {
+  const trusted = options.trustedOrigins ?? [];
+  if (trusted.length) {
+    const origin = (headers['origin'] as string) ?? '';
+    if (!origin || !isTrustedOrigin(origin, trusted)) {
+      throw new AuthenticationError('Untrusted WebSocket origin');
+    }
+  }
+  const cookieToken = readCookieFromHeader((headers['cookie'] as string) ?? '', options.cookieName ?? 'nexus_csrf');
+  const queryToken = (headers['sec-websocket-protocol'] as string)?.split(',').map((s) => s.trim())[0];
+  if (!cookieToken || !queryToken || !timingSafeEqual(cookieToken, queryToken)) {
+    throw new AuthenticationError('Invalid WebSocket CSRF token');
+  }
+}
+
+function issueToken(
+  ctx: RequestContext,
+  cookieName: string,
+  opts: NonNullable<CsrfOptions['cookie']>,
+): string {
+  const token = randomBytes(24).toString('base64url');
+  const parts = [
+    `${cookieName}=${token}`,
+    `Path=${opts.path ?? '/'}`,
+    `SameSite=${opts.sameSite ?? 'lax'}`,
+    opts.secure ? 'Secure' : '',
+    opts.domain ? `Domain=${opts.domain}` : '',
+    'HttpOnly',
+  ].filter(Boolean);
+  ctx.setHeader('set-cookie', parts.join('; '));
+  return token;
+}
+
+function readCookie(ctx: RequestContext, name: string): string | undefined {
+  return readCookieFromHeader((ctx.headers['cookie'] as string) ?? '', name);
+}
+
+function readCookieFromHeader(header: string, name: string): string | undefined {
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=');
+    const k = part.slice(0, eq).trim();
+    if (k === name) return part.slice(eq + 1).trim();
+  }
+  return undefined;
+}
+
+function checkOrigin(ctx: RequestContext, trusted: string[]): void {
+  if (trusted.length === 0) return;
+  const origin = (ctx.headers['origin'] as string) ?? (ctx.headers['referer'] as string) ?? '';
+  if (!origin || !isTrustedOrigin(origin, trusted)) {
+    throw new AuthenticationError('Untrusted request origin');
+  }
+}
+
+function isTrustedOrigin(origin: string, trusted: string[]): boolean {
+  let hostname: string;
+  let host: string;
+  try {
+    const u = new URL(origin);
+    hostname = u.hostname;
+    host = u.host;
+  } catch {
+    return false;
+  }
+  // Loopback origins (localhost/127.0.0.1) are safe from cross-site forgery
+  // regardless of port — Docker / port-forwarding commonly remaps host ports
+  // (e.g. container :3001 published on the host as :3011), so a strict
+  // host:port match would wrongly reject the admin/frontend dev servers.
+  if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1') {
+    return trusted.some((t) => {
+      try {
+        const tu = new URL(t);
+        return tu.hostname === 'localhost' || tu.hostname === '127.0.0.1' || tu.hostname === '::1';
+      } catch {
+        return false;
+      }
+    });
+  }
+  return trusted.some((t) => t === host || t === origin || origin.startsWith(t));
+}
+
+function timingSafeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) return false;
+  return ab.equals(bb);
+}

package/packages/nexus-auth/src/headers.ts

@@ -0,0 +1,55 @@
+import type { Middleware } from '../../nexus-core/src/http/index.js';
+
+export interface SecurityHeadersOptions {
+  /** HSTS max age in seconds (0 to disable). */
+  hstsMaxAge?: number;
+  /** Include subdomains in HSTS. */
+  hstsIncludeSubdomains?: boolean;
+  /** Enable HSTS preload. */
+  hstsPreload?: boolean;
+  /** Content-Security-Policy directive string. */
+  csp?: string;
+  /** Referrer-Policy. */
+  referrerPolicy?: string;
+  /** X-Content-Type-Options. */
+  noSniff?: boolean;
+  /** X-Frame-Options (DENY/SAMEORIGIN) — superseded by CSP frame-ancestors when present. */
+  frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+  /** Cross-Origin-Opener-Policy. */
+  coop?: string;
+  /** Cross-Origin-Resource-Policy. */
+  corp?: string;
+}
+
+/** Helmet-equivalent security headers, applied to every response. */
+export function securityHeaders(options: SecurityHeadersOptions = {}): Middleware {
+  const opts = {
+    hstsMaxAge: options.hstsMaxAge ?? 15552000, // 180 days
+    hstsIncludeSubdomains: options.hstsIncludeSubdomains ?? true,
+    hstsPreload: options.hstsPreload ?? false,
+    csp: options.csp ?? "default-src 'self'",
+    referrerPolicy: options.referrerPolicy ?? 'no-referrer',
+    noSniff: options.noSniff ?? true,
+    frameOptions: options.frameOptions ?? 'SAMEORIGIN',
+    coop: options.coop ?? 'same-origin',
+    corp: options.corp ?? 'same-origin',
+  };
+
+  return async (ctx, next) => {
+    // Apply headers early; they persist through the response.
+    if (opts.hstsMaxAge > 0) {
+      let hsts = `max-age=${opts.hstsMaxAge}`;
+      if (opts.hstsIncludeSubdomains) hsts += '; includeSubDomains';
+      if (opts.hstsPreload) hsts += '; preload';
+      ctx.setHeader('strict-transport-security', hsts);
+    }
+    if (opts.csp) ctx.setHeader('content-security-policy', opts.csp);
+    if (opts.referrerPolicy) ctx.setHeader('referrer-policy', opts.referrerPolicy);
+    if (opts.noSniff) ctx.setHeader('x-content-type-options', 'nosniff');
+    if (opts.frameOptions) ctx.setHeader('x-frame-options', opts.frameOptions);
+    if (opts.coop) ctx.setHeader('cross-origin-opener-policy', opts.coop);
+    if (opts.corp) ctx.setHeader('cross-origin-resource-policy', opts.corp);
+    ctx.setHeader('x-xss-protection', '0'); // disabled in favor of CSP
+    await next();
+  };
+}

package/packages/nexus-auth/src/index.ts

@@ -0,0 +1,11 @@
+export * from './cors.js';
+export * from './csrf.js';
+export * from './headers.js';
+export * from './rateLimit.js';
+export * from './password.js';
+export * from './jwt.js';
+export * from './session.js';
+export * from './rbac.js';
+export * from './oauth.js';
+export * from './auth.js';
+export * from './middleware.js';