@hilbras/keystone 1.1.0

package/src/services/smsOtp.ts

@@ -0,0 +1,74 @@
+import crypto from "node:crypto";
+import { eq, and, gt, isNull } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { smsOtpCodes, users, type User } from "../db/schema.js";
+import { smsProvider } from "./sms.js";
+
+const CODE_TTL_SECONDS = 300;
+const CODE_LENGTH = 6;
+
+export function generateSmsCode(): string {
+  return crypto.randomInt(0, 1_000_000).toString().padStart(CODE_LENGTH, "0");
+}
+
+function hashCode(code: string): string {
+  return crypto.createHash("sha256").update(code).digest("hex");
+}
+
+export async function sendSmsOtp(user: User, phoneNumber: string): Promise<string> {
+  const code = generateSmsCode();
+  const expiresAt = new Date(Date.now() + CODE_TTL_SECONDS * 1000);
+
+  await db.insert(smsOtpCodes).values({
+    userId: user.id,
+    phoneNumber,
+    codeHash: hashCode(code),
+    expiresAt,
+  });
+
+  await smsProvider.send({
+    to: phoneNumber,
+    body: `Your Hilbras verification code is: ${code}`,
+  });
+
+  return code;
+}
+
+export async function verifySmsOtp(userId: string, code: string): Promise<boolean> {
+  const codeHash = hashCode(code);
+  const now = new Date();
+
+  const [record] = await db
+    .select()
+    .from(smsOtpCodes)
+    .where(
+      and(
+        eq(smsOtpCodes.userId, userId),
+        eq(smsOtpCodes.codeHash, codeHash),
+        gt(smsOtpCodes.expiresAt, now),
+        isNull(smsOtpCodes.usedAt)
+      )
+    )
+    .limit(1);
+
+  if (!record) return false;
+
+  await db.update(smsOtpCodes).set({ usedAt: now }).where(eq(smsOtpCodes.id, record.id));
+  return true;
+}
+
+export async function hasVerifiedPhone(userId: string): Promise<boolean> {
+  const [user] = await db
+    .select({ phoneVerified: users.phoneVerified })
+    .from(users)
+    .where(eq(users.id, userId))
+    .limit(1);
+  return user?.phoneVerified ?? false;
+}
+
+export async function markPhoneVerified(userId: string, phoneNumber: string): Promise<void> {
+  await db
+    .update(users)
+    .set({ phoneNumber, phoneVerified: true })
+    .where(eq(users.id, userId));
+}

package/src/services/tokens.ts

@@ -0,0 +1,288 @@
+import crypto from "node:crypto";
+import {
+  SignJWT,
+  importPKCS8,
+  importSPKI,
+  jwtVerify,
+  decodeProtectedHeader,
+  exportJWK,
+  type JWTPayload,
+  type KeyLike,
+} from "jose";
+import { eq, and, gt, isNull } from "drizzle-orm";
+import { db } from "../db/index.js";
+import {
+  refreshTokens,
+  users,
+  type User,
+  type RefreshToken,
+  type Application,
+} from "../db/schema.js";
+import { config } from "../config.js";
+import type { TokenClaims } from "../types.js";
+import {
+  getActiveSigningKey,
+  listValidSigningKeys,
+  type SigningKeyPair,
+} from "./secrets.js";
+import { SessionRepository } from "../repositories/session.js";
+
+/** Active signing key used to issue new tokens. */
+let activeKey: SigningKeyPair | null = null;
+/** All valid signing keys (active + grace-period keys) used for verification. */
+const validKeys = new Map<string, SigningKeyPair>();
+
+export async function loadSigningKeys(): Promise<void> {
+  if (config.JWT_PRIVATE_KEY && config.JWT_PUBLIC_KEY) {
+    const privateKey = await importPKCS8(config.JWT_PRIVATE_KEY, "RS256");
+    const publicKey = await importSPKI(config.JWT_PUBLIC_KEY, "RS256");
+    activeKey = { keyId: "env", privateKey, publicKey };
+    validKeys.set(activeKey.keyId, activeKey);
+    return;
+  }
+
+  activeKey = await getActiveSigningKey();
+  const keys = await listValidSigningKeys();
+  validKeys.clear();
+  for (const key of keys) {
+    validKeys.set(key.keyId, key);
+  }
+}
+
+/**
+ * Return the public JWK for the active signing key. Kept for backwards
+ * compatibility; new code should prefer `getPublicJwks()`.
+ */
+export async function getPublicJWK() {
+  if (!activeKey) await loadSigningKeys();
+  return exportJWK(activeKey!.publicKey);
+}
+
+/**
+ * Return the JWKS document containing every valid public key, including
+ * recently rotated keys still within the grace period.
+ */
+export async function getPublicJwks() {
+  if (validKeys.size === 0) await loadSigningKeys();
+  const keys = await Promise.all(
+    Array.from(validKeys.values()).map(async (key) => {
+      const jwk = await exportJWK(key.publicKey);
+      return { ...jwk, kid: key.keyId, use: "sig", key_ops: ["verify"] };
+    })
+  );
+  return { keys };
+}
+
+function issuer(): string {
+  return process.env.AUTH_API_PUBLIC_URL || `http://localhost:${config.PORT}`;
+}
+
+export interface AccessTokenOptions {
+  appId?: string;
+  orgId?: string;
+  clientId?: string;
+  deviceFingerprint?: string;
+}
+
+export function createAccessToken(user: User, opts: AccessTokenOptions = {}): Promise<string> {
+  if (!activeKey) throw new Error("JWT signing keys not loaded");
+  const claims: TokenClaims = {
+    sub: user.id,
+    email: user.email,
+    username: user.username,
+    name: user.name ?? undefined,
+    plan: user.plan,
+    role: user.role,
+    provider: user.provider,
+  };
+  if (opts.orgId) claims.org_id = opts.orgId;
+  if (opts.appId) claims.app_id = opts.appId;
+  if (opts.clientId) claims.client_id = opts.clientId;
+  if (opts.deviceFingerprint) claims.device_fingerprint = opts.deviceFingerprint;
+  return new SignJWT(claims as unknown as Record<string, unknown>)
+    .setProtectedHeader({ alg: "RS256", typ: "JWT", kid: activeKey.keyId })
+    .setIssuedAt()
+    .setIssuer(issuer())
+    .setAudience("hilbras")
+    .setExpirationTime(`${config.ACCESS_TOKEN_TTL_SECONDS}s`)
+    .sign(activeKey.privateKey);
+}
+
+export interface ApplicationAccessTokenOptions {
+  appId: string;
+  orgId: string;
+  clientId: string;
+  scopes?: string[];
+}
+
+export function createApplicationAccessToken(
+  opts: ApplicationAccessTokenOptions
+): Promise<string> {
+  if (!activeKey) throw new Error("JWT signing keys not loaded");
+  const claims: Record<string, unknown> = {
+    sub: opts.clientId,
+    client_id: opts.clientId,
+    app_id: opts.appId,
+    org_id: opts.orgId,
+  };
+  if (opts.scopes && opts.scopes.length > 0) {
+    claims.scope = opts.scopes.join(" ");
+  }
+  return new SignJWT(claims)
+    .setProtectedHeader({ alg: "RS256", typ: "JWT", kid: activeKey.keyId })
+    .setIssuedAt()
+    .setIssuer(issuer())
+    .setAudience("hilbras")
+    .setExpirationTime(`${config.ACCESS_TOKEN_TTL_SECONDS}s`)
+    .sign(activeKey.privateKey);
+}
+
+export async function createIdToken(
+  user: User,
+  app: Application,
+  nonce?: string
+): Promise<string> {
+  if (!activeKey) throw new Error("JWT signing keys not loaded");
+  const claims: Record<string, unknown> = {
+    sub: user.id,
+    email: user.email,
+    email_verified: user.emailVerified,
+    username: user.username,
+    name: user.name,
+    picture: user.avatarUrl,
+    aud: app.clientId,
+    azp: app.clientId,
+  };
+  if (nonce) claims.nonce = nonce;
+  return new SignJWT(claims)
+    .setProtectedHeader({ alg: "RS256", typ: "JWT", kid: activeKey.keyId })
+    .setIssuedAt()
+    .setIssuer(issuer())
+    .setExpirationTime(`${config.ACCESS_TOKEN_TTL_SECONDS}s`)
+    .sign(activeKey.privateKey);
+}
+
+export interface TokenSet {
+  accessToken: string;
+  refreshToken: string;
+  refreshTokenHash: string;
+  expiresAt: Date;
+}
+
+export async function createTokenSet(
+  user: User,
+  ip?: string,
+  userAgent?: string,
+  opts: AccessTokenOptions = {},
+  deviceFingerprint?: string
+): Promise<TokenSet> {
+  const accessToken = await createAccessToken(user, opts);
+  const refreshToken = crypto.randomBytes(48).toString("base64url");
+  const refreshTokenHash = hashToken(refreshToken);
+  const expiresAt = new Date(Date.now() + config.REFRESH_TOKEN_TTL_SECONDS * 1000);
+
+  const [inserted] = await db.insert(refreshTokens).values({
+    userId: user.id,
+    appId: opts.appId ?? null,
+    tokenHash: refreshTokenHash,
+    expiresAt,
+    ipAddress: ip ?? null,
+    userAgent: userAgent ?? null,
+    deviceFingerprint: deviceFingerprint ?? null,
+  }).returning();
+
+  try {
+    const sessions = new SessionRepository();
+    await sessions.create({
+      userId: user.id,
+      refreshTokenId: inserted.id,
+      deviceFingerprint,
+      ipAddress: ip,
+      userAgent,
+      expiresAt,
+    });
+  } catch {
+    // Session tracking is best-effort; token creation must not fail because of it.
+  }
+
+  return { accessToken, refreshToken, refreshTokenHash, expiresAt };
+}
+
+export async function verifyAccessToken(token: string): Promise<TokenClaims> {
+  if (!activeKey) await loadSigningKeys();
+
+  const header = decodeProtectedHeader(token);
+  const keyPair = header.kid ? validKeys.get(header.kid) : undefined;
+  const publicKey = keyPair?.publicKey ?? activeKey?.publicKey;
+
+  if (!publicKey) {
+    throw new Error("JWT signing keys not loaded");
+  }
+
+  const { payload } = await jwtVerify(token, publicKey, {
+    issuer: issuer(),
+    audience: "hilbras",
+  });
+  return payload as unknown as TokenClaims;
+}
+
+export async function rotateRefreshToken(
+  token: string,
+  ip?: string,
+  userAgent?: string
+): Promise<TokenSet | null> {
+  const hash = hashToken(token);
+  const now = new Date();
+
+  const [existing] = await db
+    .select()
+    .from(refreshTokens)
+    .where(
+      and(
+        eq(refreshTokens.tokenHash, hash),
+        gt(refreshTokens.expiresAt, now),
+        isNull(refreshTokens.revokedAt)
+      )
+    )
+    .limit(1);
+
+  if (!existing) return null;
+
+  // Revoke old token immediately.
+  await db
+    .update(refreshTokens)
+    .set({ revokedAt: now })
+    .where(eq(refreshTokens.id, existing.id));
+
+  const [user] = await db.select().from(users).where(eq(users.id, existing.userId)).limit(1);
+  if (!user) return null;
+
+  return createTokenSet(
+    user,
+    ip,
+    userAgent,
+    {
+      appId: existing.appId ?? undefined,
+      orgId: undefined,
+      clientId: undefined,
+      deviceFingerprint: existing.deviceFingerprint ?? undefined,
+    },
+    existing.deviceFingerprint ?? undefined
+  );
+}
+
+export async function revokeRefreshToken(token: string): Promise<void> {
+  const hash = hashToken(token);
+  await db.update(refreshTokens).set({ revokedAt: new Date() }).where(eq(refreshTokens.tokenHash, hash));
+}
+
+export async function revokeAllUserRefreshTokens(userId: string): Promise<void> {
+  await db.update(refreshTokens).set({ revokedAt: new Date() }).where(eq(refreshTokens.userId, userId));
+}
+
+function hashToken(token: string): string {
+  return crypto.createHash("sha256").update(token).digest("hex");
+}
+
+// Re-exported from secrets service for backwards compatibility.
+export { hashApiKey, generateApiKey } from "./secrets.js";

package/src/services/totp.ts

@@ -0,0 +1,113 @@
+import crypto from "node:crypto";
+import { eq, and, isNull } from "drizzle-orm";
+import { Secret, TOTP } from "otpauth";
+import { config } from "../config.js";
+import { db } from "../db/index.js";
+import { totpBackupCodes } from "../db/schema.js";
+
+const ALGORITHM = "aes-256-cbc";
+const IV_LENGTH = 16;
+
+function getEncryptionKey(): Buffer {
+  const raw = config.TOTP_ENCRYPTION_KEY || config.INTERNAL_API_KEY;
+  if (raw && raw.length >= 32) {
+    return Buffer.from(raw.slice(0, 32));
+  }
+  return crypto.createHash("sha256").update(raw || "keystone-totp-default").digest();
+}
+
+export function generateSecret(): string {
+  return new Secret({ size: 20 }).base32;
+}
+
+export function buildProvisioningUri(input: { secret: string; email: string; issuer?: string }): string {
+  const issuer = input.issuer || config.TOTP_ISSUER;
+  const totp = new TOTP({
+    issuer,
+    label: input.email,
+    algorithm: "SHA1",
+    digits: 6,
+    period: 30,
+    secret: Secret.fromBase32(input.secret),
+  });
+  return totp.toString();
+}
+
+export function verifyTOTP(secret: string, code: string, window = 1): boolean {
+  try {
+    const totp = new TOTP({
+      algorithm: "SHA1",
+      digits: 6,
+      period: 30,
+      secret: Secret.fromBase32(secret),
+    });
+    const delta = totp.validate({ token: code, window });
+    return delta !== null;
+  } catch {
+    return false;
+  }
+}
+
+export function encryptSecret(secret: string): string {
+  const key = getEncryptionKey();
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([cipher.update(secret, "utf8"), cipher.final()]);
+  return `${iv.toString("base64url")}:${encrypted.toString("base64url")}`;
+}
+
+export function decryptSecret(encrypted: string): string {
+  const [ivBase64, dataBase64] = encrypted.split(":");
+  if (!ivBase64 || !dataBase64) throw new Error("Invalid encrypted secret format");
+  const key = getEncryptionKey();
+  const iv = Buffer.from(ivBase64, "base64url");
+  const encryptedData = Buffer.from(dataBase64, "base64url");
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+  const decrypted = Buffer.concat([decipher.update(encryptedData), decipher.final()]);
+  return decrypted.toString("utf8");
+}
+
+export function generateBackupCodes(): { codes: string[]; hashes: string[] } {
+  const codes: string[] = [];
+  const hashes: string[] = [];
+  for (let i = 0; i < 10; i++) {
+    const code = crypto.randomBytes(4).toString("hex").toLowerCase();
+    codes.push(code);
+    hashes.push(crypto.createHash("sha256").update(code).digest("hex"));
+  }
+  return { codes, hashes };
+}
+
+export async function storeBackupCodes(userId: string, codeHashes: string[]): Promise<void> {
+  if (codeHashes.length === 0) return;
+  await db.delete(totpBackupCodes).where(eq(totpBackupCodes.userId, userId));
+  await db.insert(totpBackupCodes).values(
+    codeHashes.map((hash) => ({ userId, codeHash: hash }))
+  );
+}
+
+export async function verifyBackupCode(userId: string, code: string): Promise<boolean> {
+  const codeHash = crypto.createHash("sha256").update(code).digest("hex");
+  const now = new Date();
+
+  const [record] = await db
+    .select()
+    .from(totpBackupCodes)
+    .where(
+      and(
+        eq(totpBackupCodes.userId, userId),
+        eq(totpBackupCodes.codeHash, codeHash),
+        isNull(totpBackupCodes.usedAt)
+      )
+    )
+    .limit(1);
+
+  if (!record) return false;
+
+  await db
+    .update(totpBackupCodes)
+    .set({ usedAt: now })
+    .where(eq(totpBackupCodes.id, record.id));
+
+  return true;
+}

package/src/services/users.ts

@@ -0,0 +1,239 @@
+import { eq, sql } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { users, userIdentities, identityProviders, orgMemberships, type User } from "../db/schema.js";
+
+export interface OAuthClaims {
+  sub: string;
+  email: string;
+  username?: string;
+  name?: string;
+  picture?: string;
+  email_verified?: boolean;
+}
+
+export async function findUserByEmail(email: string): Promise<User | undefined> {
+  const [user] = await db.select().from(users).where(eq(users.email, email.toLowerCase())).limit(1);
+  return user;
+}
+
+export async function findUserById(id: string): Promise<User | undefined> {
+  const [user] = await db.select().from(users).where(eq(users.id, id)).limit(1);
+  return user;
+}
+
+export async function findUserByZitadelId(zitadelUserId: string): Promise<User | undefined> {
+  const [user] = await db.select().from(users).where(eq(users.zitadelUserId, zitadelUserId)).limit(1);
+  return user;
+}
+
+export async function createPasswordUser(input: {
+  zitadelUserId?: string;
+  passwordHash?: string;
+  username: string;
+  email: string;
+  name: string;
+  emailVerified?: boolean;
+}): Promise<User> {
+  const [user] = await db
+    .insert(users)
+    .values({
+      zitadelUserId: input.zitadelUserId ?? null,
+      passwordHash: input.passwordHash ?? null,
+      username: slugifyUsername(input.username),
+      email: input.email.toLowerCase().trim(),
+      name: input.name.trim() || input.username,
+      provider: "password",
+      emailVerified: input.emailVerified ?? true,
+    })
+    .returning();
+  return user;
+}
+
+export async function upsertOAuthUser(
+  claims: OAuthClaims,
+  providerType: string,
+  providerId?: string
+): Promise<User> {
+  const username = slugifyUsername(claims.username || claims.name || claims.email.split("@")[0]);
+  const email = claims.email.toLowerCase().trim();
+
+  // Prefer linking by external identity when a provider record is available.
+  if (providerId) {
+    const [existingLink] = await db
+      .select({ user: users })
+      .from(userIdentities)
+      .where(eq(userIdentities.externalSub, claims.sub))
+      .innerJoin(users, eq(userIdentities.userId, users.id))
+      .limit(1);
+
+    if (existingLink) {
+      const existing = existingLink.user;
+      const [updated] = await db
+        .update(users)
+        .set({
+          email,
+          username: await ensureUniqueUsername(username, existing.id),
+          name: claims.name || existing.name,
+          avatarUrl: claims.picture || existing.avatarUrl,
+          emailVerified: claims.email_verified ?? existing.emailVerified ?? true,
+          provider: providerType,
+          updatedAt: sql`now()`,
+        })
+        .where(eq(users.id, existing.id))
+        .returning();
+      return updated;
+    }
+  }
+
+  // Fall back to email-based matching.
+  const existing = await findUserByEmail(email);
+  if (existing) {
+    const [updated] = await db
+      .update(users)
+      .set({
+        email,
+        username: await ensureUniqueUsername(username, existing.id),
+        name: claims.name || existing.name,
+        avatarUrl: claims.picture || existing.avatarUrl,
+        emailVerified: claims.email_verified ?? existing.emailVerified ?? true,
+        provider: providerType,
+        updatedAt: sql`now()`,
+      })
+      .where(eq(users.id, existing.id))
+      .returning();
+    return updated;
+  }
+
+  const [user] = await db
+    .insert(users)
+    .values({
+      email,
+      username: await ensureUniqueUsername(username),
+      name: claims.name || username,
+      avatarUrl: claims.picture,
+      emailVerified: claims.email_verified ?? true,
+      provider: providerType,
+    })
+    .returning();
+
+  if (providerId) {
+    await db.insert(userIdentities).values({
+      userId: user.id,
+      providerId,
+      providerType,
+      externalSub: claims.sub,
+      email,
+      profile: { name: claims.name, picture: claims.picture, username: claims.username },
+    });
+  }
+
+  return user;
+}
+
+export async function linkUserIdentity(
+  userId: string,
+  providerId: string,
+  providerType: string,
+  externalSub: string,
+  email?: string,
+  profile?: Record<string, unknown>
+): Promise<void> {
+  const [provider] = await db.select().from(identityProviders).where(eq(identityProviders.id, providerId)).limit(1);
+  if (!provider) throw new Error("Identity provider not found");
+  await db
+    .insert(userIdentities)
+    .values({
+      userId,
+      providerId,
+      providerType,
+      externalSub,
+      email,
+      profile: profile ?? {},
+    })
+    .onConflictDoNothing({ target: [userIdentities.providerId, userIdentities.externalSub] });
+}
+
+export async function updateUserLastSeen(id: string): Promise<void> {
+  await db.update(users).set({ updatedAt: sql`now()` }).where(eq(users.id, id));
+}
+
+export async function findOrCreateUserByEmail(input: {
+  email: string;
+  name?: string;
+  username?: string;
+}): Promise<User> {
+  const existing = await findUserByEmail(input.email);
+  if (existing) return existing;
+
+  const baseUsername = input.username || input.email.split("@")[0];
+  const username = await ensureUniqueUsername(slugifyUsername(baseUsername));
+
+  const [user] = await db
+    .insert(users)
+    .values({
+      email: input.email.toLowerCase().trim(),
+      username,
+      name: input.name || username,
+      provider: "password",
+      emailVerified: false,
+    })
+    .returning();
+  return user;
+}
+
+export async function listUsersByOrg(orgId: string): Promise<User[]> {
+  const rows = await db
+    .select({ user: users })
+    .from(users)
+    .innerJoin(orgMemberships, eq(users.id, orgMemberships.userId))
+    .where(eq(orgMemberships.orgId, orgId));
+  return rows.map((r) => r.user);
+}
+
+export async function updateUser(
+  userId: string,
+  updates: Partial<{
+    name: string;
+    username: string;
+    role: string;
+    emailVerified: boolean;
+  }>
+): Promise<User | undefined> {
+  const [updated] = await db
+    .update(users)
+    .set({ ...updates, updatedAt: sql`now()` })
+    .where(eq(users.id, userId))
+    .returning();
+  return updated;
+}
+
+export async function deactivateUser(userId: string): Promise<void> {
+  await db.update(users).set({ emailVerified: false, updatedAt: sql`now()` }).where(eq(users.id, userId));
+}
+
+export function slugifyUsername(input: string): string {
+  return input
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32);
+}
+
+export async function ensureUniqueUsername(base: string, excludeId?: string): Promise<string> {
+  let username = base || "user";
+  let counter = 2;
+  while (true) {
+    const existing = await db
+      .select({ id: users.id })
+      .from(users)
+      .where(eq(users.username, username))
+      .limit(1);
+    if (existing.length === 0 || existing[0].id === excludeId) {
+      return username;
+    }
+    username = `${base}-${counter}`;
+    counter++;
+  }
+}
+