@bhooai/nexus-auth 0.1.0

package/src/oauth.ts

@@ -0,0 +1,199 @@
+import { createHash, randomBytes } from 'node:crypto';
+
+/** Normalized profile returned by every provider. */
+export interface OAuthProfile {
+  provider: 'google' | 'facebook';
+  /** Stable per-provider user id (the provider's own subject id). */
+  providerUserId: string;
+  email?: string;
+  emailVerified?: boolean;
+  name?: string;
+  givenName?: string;
+  familyName?: string;
+  avatarUrl?: string;
+  raw: Record<string, unknown>;
+}
+
+export interface GoogleOAuthConfig {
+  clientId: string;
+  clientSecret: string;
+  /** Redirect URI registered in the Google console. */
+  redirectUri: string;
+  /** OAuth scopes (default: openid email profile). */
+  scope?: string[];
+}
+
+export interface FacebookOAuthConfig {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  scope?: string[];
+  /** Graph API version. */
+  apiVersion?: string;
+}
+
+const GOOGLE_AUTH = 'https://accounts.google.com/o/oauth2/v2/auth';
+const GOOGLE_TOKEN = 'https://oauth2.googleapis.com/token';
+const GOOGLE_PROFILE = 'https://openidconnect.googleapis.com/v1/userinfo';
+
+// ── PKCE / state helpers ─────────────────────────────────────────────────────
+
+/** Random URL-safe string for the OAuth `state` param (CSRF for the redirect). */
+export function generateState(): string {
+  return randomBytes(24).toString('base64url');
+}
+
+/** Generate a PKCE code_verifier (43-128 chars, unreserved chars). */
+export function generatePkceVerifier(): string {
+  return randomBytes(48).toString('base64url');
+}
+
+/** S256 code_challenge for a verifier. */
+export function computePkceChallenge(verifier: string): string {
+  return createHash('sha256').update(verifier).digest('base64url');
+}
+
+/**
+ * Short-lived store mapping `state` → flow context (verifier, redirect target).
+ * The default in-memory impl is fine for a single process; a Redis-backed impl
+ * is wired in Phase 7 for multi-instance deployments.
+ */
+export interface OAuthStateStore {
+  set(state: string, data: Record<string, unknown>, ttlMs: number): Promise<void>;
+  consume(state: string): Promise<Record<string, unknown> | null>;
+}
+
+export class MemoryOAuthStateStore implements OAuthStateStore {
+  private map = new Map<string, { data: Record<string, unknown>; expiresAt: number }>();
+  async set(state: string, data: Record<string, unknown>, ttlMs: number): Promise<void> {
+    this.map.set(state, { data, expiresAt: Date.now() + ttlMs });
+  }
+  async consume(state: string): Promise<Record<string, unknown> | null> {
+    const entry = this.map.get(state);
+    if (!entry) return null;
+    this.map.delete(state);
+    if (entry.expiresAt < Date.now()) return null;
+    return entry.data;
+  }
+}
+
+// ── Google ───────────────────────────────────────────────────────────────────
+
+export function buildGoogleAuthUrl(
+  config: GoogleOAuthConfig,
+  opts: { state: string; verifier: string },
+): string {
+  const scope = (config.scope ?? ['openid', 'email', 'profile']).join(' ');
+  const params = new URLSearchParams({
+    client_id: config.clientId,
+    redirect_uri: config.redirectUri,
+    response_type: 'code',
+    scope,
+    state: opts.state,
+    code_challenge: computePkceChallenge(opts.verifier),
+    code_challenge_method: 'S256',
+    access_type: 'offline',
+    prompt: 'consent',
+  });
+  return `${GOOGLE_AUTH}?${params.toString()}`;
+}
+
+export async function exchangeGoogleCode(
+  code: string,
+  config: GoogleOAuthConfig,
+  verifier: string,
+): Promise<{ accessToken: string; refreshToken?: string; idToken?: string; expiresAt: number }> {
+  const body = new URLSearchParams({
+    code,
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    redirect_uri: config.redirectUri,
+    grant_type: 'authorization_code',
+    code_verifier: verifier,
+  });
+  const res = await fetch(GOOGLE_TOKEN, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+  if (!res.ok) throw new Error(`Google token exchange failed: ${res.status} ${await res.text()}`);
+  const json = (await res.json()) as Record<string, unknown>;
+  const expiresIn = Number(json.expires_in ?? 3600);
+  return {
+    accessToken: String(json.access_token),
+    refreshToken: json.refresh_token ? String(json.refresh_token) : undefined,
+    idToken: json.id_token ? String(json.id_token) : undefined,
+    expiresAt: Date.now() + expiresIn * 1000,
+  };
+}
+
+export async function fetchGoogleProfile(accessToken: string): Promise<OAuthProfile> {
+  const res = await fetch(GOOGLE_PROFILE, { headers: { authorization: `Bearer ${accessToken}` } });
+  if (!res.ok) throw new Error(`Google profile fetch failed: ${res.status}`);
+  const raw = (await res.json()) as Record<string, unknown>;
+  return {
+    provider: 'google',
+    providerUserId: String(raw.sub),
+    email: raw.email ? String(raw.email) : undefined,
+    emailVerified: raw.email_verified === true || raw.email_verified === 'true',
+    name: raw.name ? String(raw.name) : undefined,
+    givenName: raw.given_name ? String(raw.given_name) : undefined,
+    familyName: raw.family_name ? String(raw.family_name) : undefined,
+    avatarUrl: raw.picture ? String(raw.picture) : undefined,
+    raw,
+  };
+}
+
+// ── Facebook ─────────────────────────────────────────────────────────────────
+
+export function buildFacebookAuthUrl(config: FacebookOAuthConfig, state: string): string {
+  const version = config.apiVersion ?? 'v19.0';
+  const scope = (config.scope ?? ['email']).join(',');
+  const params = new URLSearchParams({
+    client_id: config.clientId,
+    redirect_uri: config.redirectUri,
+    response_type: 'code',
+    scope,
+    state,
+  });
+  return `https://www.facebook.com/${version}/dialog/oauth?${params.toString()}`;
+}
+
+export async function exchangeFacebookCode(
+  code: string,
+  config: FacebookOAuthConfig,
+): Promise<{ accessToken: string; expiresAt: number }> {
+  const version = config.apiVersion ?? 'v19.0';
+  const params = new URLSearchParams({
+    code,
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    redirect_uri: config.redirectUri,
+  });
+  const res = await fetch(`https://graph.facebook.com/${version}/oauth/access_token?${params.toString()}`);
+  if (!res.ok) throw new Error(`Facebook token exchange failed: ${res.status} ${await res.text()}`);
+  const json = (await res.json()) as Record<string, unknown>;
+  const expiresIn = Number(json.expires_in ?? 3600);
+  return { accessToken: String(json.access_token), expiresAt: Date.now() + expiresIn * 1000 };
+}
+
+export async function fetchFacebookProfile(accessToken: string, apiVersion = 'v19.0'): Promise<OAuthProfile> {
+  const fields = 'id,name,email,first_name,last_name,picture';
+  const res = await fetch(`https://graph.facebook.com/${apiVersion}/me?fields=${fields}&access_token=${accessToken}`);
+  if (!res.ok) throw new Error(`Facebook profile fetch failed: ${res.status}`);
+  const raw = (await res.json()) as Record<string, unknown>;
+  return {
+    provider: 'facebook',
+    providerUserId: String(raw.id),
+    email: raw.email ? String(raw.email) : undefined,
+    emailVerified: !!raw.email, // Facebook marks email-verified accounts; treat presence as verified.
+    name: raw.name ? String(raw.name) : undefined,
+    givenName: raw.first_name ? String(raw.first_name) : undefined,
+    familyName: raw.last_name ? String(raw.last_name) : undefined,
+    avatarUrl:
+      raw.picture && typeof raw.picture === 'object'
+         ? String((raw.picture as { data?: { url?: string } }).data?.url ?? '')
+        : undefined,
+    raw,
+  };
+}

package/src/password.ts

@@ -0,0 +1,33 @@
+/// <reference path="./bcryptjs.d.ts" />
+
+import bcrypt from 'bcryptjs';
+
+/**
+ * Password hashing using `bcryptjs` (pure-JavaScript, API-compatible with the
+ * native `bcrypt` binding). The pure-JS implementation is chosen deliberately
+ * so the framework builds on Windows without node-gyp / native toolchains;
+ * the cost parameter below keeps it within practical latency budgets.
+ */
+const DEFAULT_ROUNDS = 12;
+
+/** Hash a plaintext password with a salt cost of `rounds`. */
+export async function hashPassword(plaintext: string, rounds = DEFAULT_ROUNDS): Promise<string> {
+  if (!plaintext || typeof plaintext !== 'string') throw new Error('Password must be a non-empty string.');
+  const salt = await bcrypt.genSalt(rounds);
+  return bcrypt.hash(plaintext, salt);
+}
+
+/** Verify a plaintext password against a previously-hashed value. */
+export async function verifyPassword(plaintext: string, hash: string): Promise<boolean> {
+  if (!plaintext || !hash) return false;
+  try {
+    return await bcrypt.compare(plaintext, hash);
+  } catch {
+    return false;
+  }
+}
+
+/** True if `hash` looks like a bcrypt hash (so we can detect legacy / plaintext). */
+export function isBcryptHash(hash: string): boolean {
+  return /^\$2[abxy]\$\d{2}\$/.test(hash);
+}

package/src/rateLimit.ts

@@ -0,0 +1,59 @@
+import type { Middleware } from '../../nexus-core/src/http/index.js';
+import { AuthenticationError } from '../../nexus-core/src/index.js';
+
+export interface RateLimitOptions {
+  /** Time window in ms. */
+  windowMs: number;
+  /** Maximum requests per window per key. */
+  max: number;
+  /** Function to derive the rate-limit key (default: client IP). */
+  keyGenerator?: (ctx: import('../../nexus-core/src/http/index.js').RequestContext) => string;
+  /** Message returned when limited. */
+  message?: string;
+}
+
+/** Pluggable store — default is in-memory; Redis backend added in Phase 7. */
+export interface RateLimitStore {
+  hit(key: string, windowMs: number): Promise<{ count: number; resetAt: number }>;
+}
+
+export function memoryStore(): RateLimitStore {
+  const buckets = new Map<string, { count: number; resetAt: number }>();
+  return {
+    async hit(key, windowMs) {
+      const now = Date.now();
+      let entry = buckets.get(key);
+      if (!entry || entry.resetAt <= now) {
+        entry = { count: 0, resetAt: now + windowMs };
+        buckets.set(key, entry);
+      }
+      entry.count++;
+      return { count: entry.count, resetAt: entry.resetAt };
+    },
+  };
+}
+
+/**
+ * Inbuilt rate limiter (fixed window). In-memory by default; pass a Redis-backed
+ * store for horizontal scaling. Sets standard `rate-limit-*` headers.
+ */
+export function rateLimit(options: RateLimitOptions): Middleware {
+  const store = options.keyGenerator ? memoryStore() : memoryStore();
+  const keyGenerator =
+    options.keyGenerator ??
+    ((ctx) => (ctx.headers['x-forwarded-for'] as string)?.split(',')[0]?.trim() ?? ctx.req.socket.remoteAddress ?? 'unknown');
+
+  return async (ctx, next) => {
+    const key = keyGenerator(ctx);
+    const { count, resetAt } = await store.hit(key, options.windowMs);
+    const remaining = Math.max(0, options.max - count);
+    ctx.setHeader('rate-limit-limit', String(options.max));
+    ctx.setHeader('rate-limit-remaining', String(remaining));
+    ctx.setHeader('rate-limit-reset', String(Math.ceil((resetAt - Date.now()) / 1000)));
+    if (count > options.max) {
+      ctx.setHeader('retry-after', String(Math.ceil((resetAt - Date.now()) / 1000)));
+      throw new AuthenticationError(options.message ?? 'Too many requests');
+    }
+    await next();
+  };
+}

package/src/rbac.ts

@@ -0,0 +1,94 @@
+import type { Middleware, RequestContext } from '../../nexus-core/src/http/index.js';
+import { AuthorizationError, AuthenticationError } from '../../nexus-core/src/index.js';
+
+/**
+ * Role-based access control. A `RoleRegistry` maps role names to the set of
+ * permissions they grant; roles can inherit from other roles via the
+ * `inherits` option. The `can(role, permission)` check resolves the full
+ * transitive permission set.
+ */
+export interface RoleDefinition {
+  permissions?: string[];
+  /** Other roles whose permissions are inherited. */
+  inherits?: string[];
+}
+
+export class RoleRegistry {
+  private roles = new Map<string, RoleDefinition>();
+
+  define(name: string, def: RoleDefinition): this {
+    this.roles.set(name, def);
+    return this;
+  }
+
+  defineAll(map: Record<string, RoleDefinition>): this {
+    for (const [name, def] of Object.entries(map)) this.define(name, def);
+    return this;
+  }
+
+  /** Resolve the full transitive permission set for a role. */
+  permissionsFor(role: string, seen = new Set<string>()): Set<string> {
+    if (seen.has(role)) return new Set();
+    seen.add(role);
+    const def = this.roles.get(role);
+    if (!def) return new Set();
+    const out = new Set(def.permissions ?? []);
+    for (const parent of def.inherits ?? []) {
+      for (const p of this.permissionsFor(parent, seen)) out.add(p);
+    }
+    return out;
+  }
+
+  can(role: string, permission: string): boolean {
+    return this.permissionsFor(role).has(permission);
+  }
+
+  /** True if ANY of the user's roles grant the permission. */
+  canAny(roles: string[], permission: string): boolean {
+    return roles.some((r) => this.can(r, permission));
+  }
+}
+
+/** The shape of an authenticated principal stored on `ctx.state.user`. */
+export interface AuthUser {
+  id: string;
+  roles: string[];
+  [key: string]: unknown;
+}
+
+/** Read the authenticated user from ctx.state, throwing 401 if absent. */
+export function getUser(ctx: RequestContext): AuthUser {
+  const user = ctx.state.user as AuthUser | undefined;
+  if (!user) throw new AuthenticationError();
+  return user;
+}
+
+/** Middleware that requires an authenticated user (sets nothing; pairs with `authToken`). */
+export function requireAuth(): Middleware {
+  return async (ctx, next) => {
+    getUser(ctx);
+    await next();
+  };
+}
+
+/** Middleware that requires the user to hold one of the given roles. */
+export function requireRole(...roles: string[]): Middleware {
+  return async (ctx, next) => {
+    const user = getUser(ctx);
+    if (!roles.some((r) => user.roles.includes(r))) {
+      throw new AuthorizationError(`Requires one of roles: ${roles.join(', ')}`);
+    }
+    await next();
+  };
+}
+
+/** Middleware that requires a specific permission, checked against a registry. */
+export function requirePermission(registry: RoleRegistry, permission: string): Middleware {
+  return async (ctx, next) => {
+    const user = getUser(ctx);
+    if (!registry.canAny(user.roles, permission)) {
+      throw new AuthorizationError(`Missing permission: ${permission}`);
+    }
+    await next();
+  };
+}

package/src/session.ts

@@ -0,0 +1,91 @@
+import { randomBytes } from 'node:crypto';
+
+export interface Session {
+  id: string;
+  /** User id this session belongs to. */
+  userId: string;
+  /** Roles snapshot at session creation (for quick auth without a DB hit). */
+  roles: string[];
+  /** Refresh-token family id — used to detect reuse after rotation. */
+  familyId: string;
+  /** The current refresh token's jti (so a reused/old refresh token is detectable). */
+  currentJti?: string;
+  /** Creation timestamp (ms). */
+  createdAt: number;
+  /** Last-seen timestamp (ms). */
+  updatedAt: number;
+  /** Optional metadata (ip, userAgent). */
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Session store abstraction. The default `MemorySessionStore` is used in tests
+ * and single-process deployments; a Redis-backed implementation is wired in
+ * Phase 7 (`nexus-cache`) for horizontal scaling. Refresh-token rotation uses
+ * the `familyId` so that a stolen, already-rotated refresh token revokes the
+ * entire family on reuse detection.
+ */
+export interface SessionStore {
+  create(userId: string, roles: string[], meta?: Record<string, unknown>): Promise<Session>;
+  get(id: string): Promise<Session | null>;
+  update(id: string, patch: Partial<Session>): Promise<void>;
+  destroy(id: string): Promise<void>;
+  /** Destroy every session in a refresh family (reuse detection / logout-all). */
+  destroyFamily(familyId: string): Promise<void>;
+  /** Destroy all sessions for a user (logout everywhere). */
+  destroyAllForUser(userId: string): Promise<void>;
+}
+
+export class MemorySessionStore implements SessionStore {
+  private sessions = new Map<string, Session>();
+  private byFamily = new Map<string, Set<string>>();
+  private byUser = new Map<string, Set<string>>();
+
+  async create(userId: string, roles: string[], meta?: Record<string, unknown>): Promise<Session> {
+    const id = randomBytes(18).toString('base64url');
+    const familyId = randomBytes(18).toString('base64url');
+    const now = Date.now();
+    const session: Session = { id, userId, roles, familyId, createdAt: now, updatedAt: now, meta };
+    this.sessions.set(id, session);
+    this.byFamily.set(familyId, new Set([id]));
+    let userSet = this.byUser.get(userId);
+    if (!userSet) {
+      userSet = new Set<string>();
+      this.byUser.set(userId, userSet);
+    }
+    userSet.add(id);
+    return session;
+  }
+
+  async get(id: string): Promise<Session | null> {
+    return this.sessions.get(id) ?? null;
+  }
+
+  async update(id: string, patch: Partial<Session>): Promise<void> {
+    const s = this.sessions.get(id);
+    if (!s) return;
+    Object.assign(s, patch, { updatedAt: Date.now() });
+  }
+
+  async destroy(id: string): Promise<void> {
+    const s = this.sessions.get(id);
+    if (!s) return;
+    this.sessions.delete(id);
+    this.byFamily.get(s.familyId)?.delete(id);
+    this.byUser.get(s.userId)?.delete(id);
+  }
+
+  async destroyFamily(familyId: string): Promise<void> {
+    const ids = this.byFamily.get(familyId);
+    if (!ids) return;
+    for (const id of ids) this.destroy(id);
+    this.byFamily.delete(familyId);
+  }
+
+  async destroyAllForUser(userId: string): Promise<void> {
+    const ids = this.byUser.get(userId);
+    if (!ids) return;
+    for (const id of ids) this.destroy(id);
+    this.byUser.delete(userId);
+  }
+}