@hilbras/keystone 1.1.0

package/src/services/featureFlags.ts

@@ -0,0 +1,90 @@
+import { eq } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { featureFlags } from "../db/schema.js";
+import { configurationService } from "./configuration.js";
+
+const cache = new Map<string, boolean>();
+let cacheLoaded = false;
+
+async function loadIntoCache() {
+  if (cacheLoaded) return;
+  const rows = await db.select({ key: featureFlags.key, enabled: featureFlags.enabled }).from(featureFlags);
+  for (const row of rows) {
+    cache.set(row.key, row.enabled);
+  }
+  cacheLoaded = true;
+}
+
+export async function isFeatureEnabled(flag: string): Promise<boolean> {
+  await loadIntoCache();
+  if (cache.has(flag)) return cache.get(flag)!;
+  return configurationService.isEnabled(flag);
+}
+
+export async function requireFeatureEnabled(flag: string): Promise<void> {
+  const enabled = await isFeatureEnabled(flag);
+  if (!enabled) {
+    const error = new Error(`Feature '${flag}' is not enabled`) as Error & { statusCode: number };
+    error.statusCode = 403;
+    throw error;
+  }
+}
+
+export async function listFeatureFlags(): Promise<
+  Array<{ key: string; enabled: boolean; description: string | null; source: "database" | "environment" }>
+> {
+  await loadIntoCache();
+  const dbRows = await db.select().from(featureFlags).orderBy(featureFlags.key);
+  const envFlags = configurationService.get().featureFlags;
+
+  const merged = new Map<string, { key: string; enabled: boolean; description: string | null; source: "database" | "environment" }>();
+
+  for (const row of dbRows) {
+    merged.set(row.key, { key: row.key, enabled: row.enabled, description: row.description, source: "database" });
+  }
+
+  for (const [key, enabled] of Object.entries(envFlags)) {
+    if (!merged.has(key)) {
+      merged.set(key, { key, enabled, description: null, source: "environment" });
+    }
+  }
+
+  return Array.from(merged.values()).sort((a, b) => a.key.localeCompare(b.key));
+}
+
+export async function setFeatureFlag(
+  key: string,
+  enabled: boolean,
+  description?: string
+): Promise<{ key: string; enabled: boolean }> {
+  const existing = await db.select().from(featureFlags).where(eq(featureFlags.key, key)).limit(1);
+  if (existing.length > 0) {
+    const [row] = await db
+      .update(featureFlags)
+      .set({ enabled, description: description ?? existing[0].description, updatedAt: new Date() })
+      .where(eq(featureFlags.key, key))
+      .returning();
+    cache.set(row.key, row.enabled);
+    return { key: row.key, enabled: row.enabled };
+  }
+
+  const [row] = await db
+    .insert(featureFlags)
+    .values({ key, enabled, description: description || null })
+    .returning();
+  cache.set(row.key, row.enabled);
+  return { key: row.key, enabled: row.enabled };
+}
+
+export async function deleteFeatureFlag(key: string): Promise<boolean> {
+  const [row] = await db.delete(featureFlags).where(eq(featureFlags.key, key)).returning();
+  if (row) {
+    cache.delete(row.key);
+  }
+  return !!row;
+}
+
+export function clearFeatureFlagCache(): void {
+  cache.clear();
+  cacheLoaded = false;
+}

package/src/services/features.ts

@@ -0,0 +1,22 @@
+import type { ConfigurationService } from "./configuration.js";
+
+export interface FeatureFlagService {
+  isEnabled(flag: string): boolean;
+  requireEnabled(flag: string): void;
+}
+
+export class DefaultFeatureFlagService implements FeatureFlagService {
+  constructor(private readonly config: ConfigurationService) {}
+
+  isEnabled(flag: string): boolean {
+    return this.config.isEnabled(flag);
+  }
+
+  requireEnabled(flag: string): void {
+    if (!this.isEnabled(flag)) {
+      const error = new Error(`Feature '${flag}' is not enabled`) as Error & { statusCode: number };
+      error.statusCode = 403;
+      throw error;
+    }
+  }
+}

package/src/services/federation.ts

@@ -0,0 +1,30 @@
+import { buildConnector } from "./connectors/registry.js";
+import { upsertOAuthUser } from "./users.js";
+import { createTokenSet } from "./tokens.js";
+import type { User } from "../db/schema.js";
+import type { IdentityConnector } from "./connectors/types.js";
+
+export function getFederationConnector(providerType: string): IdentityConnector {
+  return buildConnector(providerType);
+}
+
+export async function getFederationAuthorizeUrl(providerType: string, state: string, redirectUri: string): Promise<string> {
+  const connector = getFederationConnector(providerType);
+  return connector.getAuthorizeUrl({
+    state,
+    redirectUri,
+    scopes: ["openid", "profile", "email"],
+  });
+}
+
+export async function completeFederationLogin(
+  providerType: string,
+  code: string,
+  redirectUri: string
+): Promise<{ user: User; tokens: { accessToken: string; refreshToken: string } }> {
+  const connector = getFederationConnector(providerType);
+  const identity = await connector.exchangeCode(code, redirectUri);
+  const user = await upsertOAuthUser(identity, providerType);
+  const tokens = await createTokenSet(user);
+  return { user, tokens: { accessToken: tokens.accessToken, refreshToken: tokens.refreshToken } };
+}

package/src/services/hibp.ts

@@ -0,0 +1,28 @@
+import crypto from "node:crypto";
+
+export async function isPasswordBreached(password: string): Promise<boolean> {
+  const hash = crypto.createHash("sha1").update(password).digest("hex").toUpperCase();
+  const prefix = hash.slice(0, 5);
+  const suffix = hash.slice(5);
+
+  try {
+    const response = await fetch(`https://api.pwnedpasswords.com/range/${prefix}`, {
+      headers: { "Add-Padding": "true" },
+    });
+    if (!response.ok) {
+      return false;
+    }
+    const text = await response.text();
+    const lines = text.split("\r\n");
+    for (const line of lines) {
+      const [lineSuffix, countStr] = line.split(":");
+      if (!lineSuffix || !countStr) continue;
+      if (lineSuffix === suffix && Number(countStr) > 0) {
+        return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}

package/src/services/ipControls.ts

@@ -0,0 +1,99 @@
+import { db } from "../db/index.js";
+import { applications } from "../db/schema.js";
+import { eq } from "drizzle-orm";
+
+/**
+ * Per-application IP allow/block lists.
+ *
+ * Entries may be exact IPs ("203.0.113.10") or CIDR ranges
+ * ("203.0.113.0/24", "2001:db8::/32"). When `allowedIps` is non-empty only
+ * matching IPs may authenticate; `blockedIps` always wins.
+ */
+
+function ipToBigInt(ip: string): { value: bigint; bits: number } | null {
+  if (ip.includes(".")) {
+    const parts = ip.split(".");
+    if (parts.length !== 4) return null;
+    let value = 0n;
+    for (const part of parts) {
+      const n = Number(part);
+      if (!Number.isInteger(n) || n < 0 || n > 255) return null;
+      value = (value << 8n) | BigInt(n);
+    }
+    return { value, bits: 32 };
+  }
+
+  if (ip.includes(":")) {
+    // Expand :: shorthand and parse 8 hextets.
+    const [head, tail] = ip.split("::");
+    let hextets: string[];
+    if (tail !== undefined) {
+      const headParts = head ? head.split(":") : [];
+      const tailParts = tail ? tail.split(":") : [];
+      const missing = 8 - headParts.length - tailParts.length;
+      if (missing < 0) return null;
+      hextets = [...headParts, ...Array(missing).fill("0"), ...tailParts];
+    } else {
+      hextets = ip.split(":");
+    }
+    if (hextets.length !== 8) return null;
+    let value = 0n;
+    for (const hex of hextets) {
+      const n = parseInt(hex || "0", 16);
+      if (Number.isNaN(n) || n < 0 || n > 0xffff) return null;
+      value = (value << 16n) | BigInt(n);
+    }
+    return { value, bits: 128 };
+  }
+
+  return null;
+}
+
+export function ipMatchesEntry(ip: string, entry: string): boolean {
+  const target = ipToBigInt(ip);
+  if (!target) return false;
+
+  const [networkIp, prefixStr] = entry.split("/");
+  const network = ipToBigInt(networkIp.trim());
+  if (!network || network.bits !== target.bits) return false;
+
+  if (prefixStr === undefined) {
+    return target.value === network.value;
+  }
+
+  const prefix = Number(prefixStr);
+  if (!Number.isInteger(prefix) || prefix < 0 || prefix > network.bits) return false;
+  if (prefix === 0) return true;
+
+  const shift = BigInt(network.bits - prefix);
+  return target.value >> shift === network.value >> shift;
+}
+
+export interface IpCheckResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+export async function checkIpAllowed(clientId: string | undefined, ip: string | undefined): Promise<IpCheckResult> {
+  if (!clientId || !ip) return { allowed: true };
+
+  const [app] = await db
+    .select({ allowedIps: applications.allowedIps, blockedIps: applications.blockedIps })
+    .from(applications)
+    .where(eq(applications.clientId, clientId))
+    .limit(1);
+
+  if (!app) return { allowed: true };
+
+  const blocked = app.blockedIps || [];
+  if (blocked.some((entry) => ipMatchesEntry(ip, entry))) {
+    return { allowed: false, reason: "Your IP address is blocked for this application." };
+  }
+
+  const allowed = app.allowedIps || [];
+  if (allowed.length > 0 && !allowed.some((entry) => ipMatchesEntry(ip, entry))) {
+    return { allowed: false, reason: "Your IP address is not allowed for this application." };
+  }
+
+  return { allowed: true };
+}

package/src/services/magicLinks.ts

@@ -0,0 +1,51 @@
+import crypto from "node:crypto";
+import { eq, and, gt, isNull } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { magicLinks, users, type User } from "../db/schema.js";
+import { config } from "../config.js";
+
+export function generateMagicLink(): { token: string; tokenHash: string } {
+  const token = crypto.randomBytes(48).toString("base64url");
+  const tokenHash = crypto.createHash("sha256").update(token).digest("hex");
+  return { token, tokenHash };
+}
+
+export async function storeMagicLink(userId: string, tokenHash: string, expiresAt: Date) {
+  const [record] = await db
+    .insert(magicLinks)
+    .values({
+      userId,
+      tokenHash,
+      expiresAt,
+    })
+    .returning();
+  return record;
+}
+
+export async function consumeMagicLink(token: string): Promise<User | undefined> {
+  const tokenHash = crypto.createHash("sha256").update(token).digest("hex");
+  const now = new Date();
+
+  const [record] = await db
+    .select()
+    .from(magicLinks)
+    .where(
+      and(
+        eq(magicLinks.tokenHash, tokenHash),
+        gt(magicLinks.expiresAt, now),
+        isNull(magicLinks.usedAt)
+      )
+    )
+    .limit(1);
+
+  if (!record) return undefined;
+
+  await db.update(magicLinks).set({ usedAt: now }).where(eq(magicLinks.id, record.id));
+
+  const [user] = await db.select().from(users).where(eq(users.id, record.userId)).limit(1);
+  return user;
+}
+
+export function magicLinkExpiresAt(): Date {
+  return new Date(Date.now() + config.MAGIC_LINK_TTL_SECONDS * 1000);
+}

package/src/services/oauth2.ts

@@ -0,0 +1,216 @@
+import crypto from "node:crypto";
+import { eq, and, gt, isNull, inArray } from "drizzle-orm";
+import { db } from "../db/index.js";
+import {
+  oauth2AuthorizationCodes,
+  oauth2Consents,
+  applications,
+  users,
+  type User,
+  type Application,
+} from "../db/schema.js";
+import { config } from "../config.js";
+import { createTokenSet, createIdToken, type AccessTokenOptions } from "./tokens.js";
+
+export interface AuthorizationCodeInput {
+  appId: string;
+  userId: string;
+  challenge?: string;
+  challengeMethod?: string;
+  redirectUri?: string;
+  scopes?: string[];
+  nonce?: string;
+}
+
+export function generateAuthorizationCode(): { code: string; codeHash: string } {
+  const code = crypto.randomBytes(48).toString("base64url");
+  const codeHash = crypto.createHash("sha256").update(code).digest("hex");
+  return { code, codeHash };
+}
+
+export async function storeAuthorizationCode(input: AuthorizationCodeInput) {
+  const { code, codeHash } = generateAuthorizationCode();
+  const expiresAt = new Date(Date.now() + config.OAUTH_CODE_TTL_SECONDS * 1000);
+
+  const [record] = await db
+    .insert(oauth2AuthorizationCodes)
+    .values({
+      appId: input.appId,
+      userId: input.userId,
+      codeHash,
+      challenge: input.challenge ?? null,
+      challengeMethod: input.challengeMethod ?? null,
+      redirectUri: input.redirectUri ?? null,
+      scopes: input.scopes ?? [],
+      nonce: input.nonce ?? null,
+      expiresAt,
+    })
+    .returning();
+
+  return { ...record, code };
+}
+
+export async function consumeAuthorizationCode(
+  code: string,
+  appId: string,
+  redirectUri?: string
+): Promise<typeof oauth2AuthorizationCodes.$inferSelect | undefined> {
+  const codeHash = crypto.createHash("sha256").update(code).digest("hex");
+  const now = new Date();
+
+  const [record] = await db
+    .select()
+    .from(oauth2AuthorizationCodes)
+    .where(
+      and(
+        eq(oauth2AuthorizationCodes.codeHash, codeHash),
+        eq(oauth2AuthorizationCodes.appId, appId),
+        gt(oauth2AuthorizationCodes.expiresAt, now),
+        isNull(oauth2AuthorizationCodes.usedAt)
+      )
+    )
+    .limit(1);
+
+  if (!record) return undefined;
+  if (redirectUri && record.redirectUri && record.redirectUri !== redirectUri) {
+    return undefined;
+  }
+
+  await db
+    .update(oauth2AuthorizationCodes)
+    .set({ usedAt: now })
+    .where(eq(oauth2AuthorizationCodes.id, record.id));
+
+  return record;
+}
+
+export function verifyPKCE(
+  challenge: string | null | undefined,
+  method: string | null | undefined,
+  verifier: string
+): boolean {
+  if (!challenge) return true;
+  if (method?.toLowerCase() !== "s256") return false;
+  const hash = crypto.createHash("sha256").update(verifier).digest("base64url");
+  return hash === challenge;
+}
+
+export async function hasConsent(
+  userId: string,
+  appId: string,
+  requestedScopes: string[]
+): Promise<boolean> {
+  if (requestedScopes.length === 0) return true;
+
+  const [consent] = await db
+    .select()
+    .from(oauth2Consents)
+    .where(
+      and(
+        eq(oauth2Consents.appId, appId),
+        eq(oauth2Consents.userId, userId),
+        isNull(oauth2Consents.revokedAt)
+      )
+    )
+    .limit(1);
+
+  if (!consent) return false;
+  const granted = new Set(consent.scopes);
+  return requestedScopes.every((scope) => granted.has(scope));
+}
+
+export async function grantConsent(userId: string, appId: string, scopes: string[]) {
+  const now = new Date();
+  const [record] = await db
+    .insert(oauth2Consents)
+    .values({
+      appId,
+      userId,
+      scopes,
+      grantedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: [oauth2Consents.appId, oauth2Consents.userId],
+      set: {
+        scopes,
+        grantedAt: now,
+        revokedAt: null,
+      },
+    })
+    .returning();
+  return record;
+}
+
+export async function revokeConsent(userId: string, appId: string): Promise<void> {
+  await db
+    .update(oauth2Consents)
+    .set({ revokedAt: new Date() })
+    .where(and(eq(oauth2Consents.appId, appId), eq(oauth2Consents.userId, userId)));
+}
+
+export async function listConsentsByAppId(appId: string) {
+  return db
+    .select()
+    .from(oauth2Consents)
+    .where(and(eq(oauth2Consents.appId, appId), isNull(oauth2Consents.revokedAt)));
+}
+
+export async function createTokenResponse(
+  user: User,
+  app: Application,
+  scopes: string[],
+  opts: { ip?: string; userAgent?: string; deviceFingerprint?: string; nonce?: string } = {}
+) {
+  const tokenOpts: AccessTokenOptions = {
+    appId: app.id,
+    orgId: app.orgId,
+    clientId: app.clientId,
+  };
+
+  const tokenSet = await createTokenSet(
+    user,
+    opts.ip,
+    opts.userAgent,
+    tokenOpts,
+    opts.deviceFingerprint
+  );
+
+  const response: Record<string, unknown> = {
+    access_token: tokenSet.accessToken,
+    refresh_token: tokenSet.refreshToken,
+    token_type: "Bearer",
+    expires_in: config.ACCESS_TOKEN_TTL_SECONDS,
+    scope: scopes.join(" "),
+  };
+
+  if (scopes.includes("openid")) {
+    response.id_token = await createIdToken(user, app, opts.nonce);
+  }
+
+  return response;
+}
+
+export async function findApplicationByClientId(clientId: string): Promise<Application | undefined> {
+  const [app] = await db
+    .select()
+    .from(applications)
+    .where(and(eq(applications.clientId, clientId), eq(applications.isActive, true)))
+    .limit(1);
+  return app;
+}
+
+export async function verifyClientSecret(
+  clientId: string,
+  secret: string
+): Promise<Application | undefined> {
+  const [app] = await db
+    .select()
+    .from(applications)
+    .where(and(eq(applications.clientId, clientId), eq(applications.isActive, true)))
+    .limit(1);
+
+  if (!app) return undefined;
+  const hash = crypto.createHash("sha256").update(secret).digest("hex");
+  if (app.clientSecretHash !== hash) return undefined;
+  return app;
+}