@hilbras/keystone 1.1.0

package/src/routes/oauth.ts

@@ -0,0 +1,167 @@
+import crypto from "node:crypto";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { config } from "../config.js";
+import { buildConnector, listSupportedProviders } from "../services/connectors/registry.js";
+import { upsertOAuthUser } from "../services/users.js";
+import { createTokenSet } from "../services/tokens.js";
+import { setSessionCookies, clearSessionCookies } from "../plugins/auth.js";
+import { findApplicationByClientId } from "../services/applications.js";
+import type { Application } from "../db/schema.js";
+import { buildOAuthErrorRedirect, buildOAuthErrorResponse } from "../lib/errors.js";
+
+const REDIRECT_TARGET = process.env.AUTH_SUCCESS_REDIRECT || "/chat";
+
+const OAuthStartSchema = {
+  querystring: {
+    type: "object",
+    properties: {
+      client_id: { type: "string" },
+    },
+  },
+};
+
+function isProvider(value: string): boolean {
+  return listSupportedProviders().includes(value);
+}
+
+function randomState(): string {
+  return crypto.randomBytes(24).toString("base64url");
+}
+
+function setOAuthState(reply: FastifyReply, state: string): void {
+  reply.setCookie("oauth_state", state, {
+    path: "/",
+    httpOnly: true,
+    secure: config.COOKIE_SECURE,
+    sameSite: "lax" as const,
+    domain: config.COOKIE_DOMAIN || undefined,
+    maxAge: 600,
+  });
+}
+
+function clearOAuthState(reply: FastifyReply): void {
+  reply.clearCookie("oauth_state", {
+    path: "/",
+    httpOnly: true,
+    secure: config.COOKIE_SECURE,
+    sameSite: "lax" as const,
+    domain: config.COOKIE_DOMAIN || undefined,
+  });
+}
+
+function setOAuthClientId(reply: FastifyReply, clientId?: string): void {
+  if (!clientId) return;
+  reply.setCookie("oauth_client_id", clientId, {
+    path: "/",
+    httpOnly: true,
+    secure: config.COOKIE_SECURE,
+    sameSite: "lax" as const,
+    domain: config.COOKIE_DOMAIN || undefined,
+    maxAge: 600,
+  });
+}
+
+function getOAuthClientId(request: FastifyRequest): string | undefined {
+  return request.cookies.oauth_client_id;
+}
+
+function clearOAuthClientId(reply: FastifyReply): void {
+  reply.clearCookie("oauth_client_id", {
+    path: "/",
+    httpOnly: true,
+    secure: config.COOKIE_SECURE,
+    sameSite: "lax" as const,
+    domain: config.COOKIE_DOMAIN || undefined,
+  });
+}
+
+function publicUrl(): string {
+  return config.AUTH_API_PUBLIC_URL || `http://localhost:${config.PORT}`;
+}
+
+function callbackRedirectUri(provider: string): string {
+  return `${publicUrl()}/auth/callback/${provider}`;
+}
+
+export default async function oauthRoutes(app: FastifyInstance) {
+  app.get("/oauth/:provider", { schema: OAuthStartSchema }, async (request, reply) => {
+    const { provider } = request.params as { provider: string };
+    if (!isProvider(provider)) {
+      return reply.status(400).send({ error: "Unsupported provider" });
+    }
+
+    const query = request.query as { client_id?: string };
+    const state = randomState();
+    setOAuthState(reply, state);
+    setOAuthClientId(reply, query.client_id);
+
+    try {
+      const connector = buildConnector(provider);
+      const url = await connector.getAuthorizeUrl({
+        state,
+        redirectUri: callbackRedirectUri(provider),
+        scopes: ["openid", "profile", "email"],
+      });
+      return reply.redirect(url);
+    } catch (err) {
+      request.log.error({ err }, "OAuth start failed");
+      const { statusCode, body } = buildOAuthErrorResponse(err);
+      return reply.status(statusCode).send(body);
+    }
+  });
+
+  app.get("/callback/:provider", async (request, reply) => {
+    const { provider } = request.params as { provider: string };
+    if (!isProvider(provider)) {
+      return reply.status(400).send({ error: "Unsupported provider" });
+    }
+
+    const { code, state } = request.query as { code?: string; state?: string };
+    const cookieState = request.cookies.oauth_state;
+    const clientId = getOAuthClientId(request);
+
+    if (!code || !state || state !== cookieState) {
+      clearOAuthState(reply);
+      clearOAuthClientId(reply);
+      return reply.redirect(`${redirectTargetUrl(clientId)}?error=${encodeURIComponent("Invalid OAuth state")}`);
+    }
+    clearOAuthState(reply);
+    clearOAuthClientId(reply);
+
+    try {
+      const connector = buildConnector(provider);
+      const identity = await connector.exchangeCode(code, callbackRedirectUri(provider));
+
+      const user = await upsertOAuthUser(identity, provider);
+
+      const app = clientId ? await findApplicationByClientId(clientId) : undefined;
+      const tokens = await createTokenSet(user, request.ip, request.headers["user-agent"], {
+        appId: app?.id,
+        orgId: app?.orgId,
+        clientId: app?.clientId,
+      });
+      setSessionCookies(reply, tokens.accessToken, tokens.refreshToken, app?.clientId);
+
+      await request.audit("oauth_callback", {
+        provider,
+        externalSub: identity.sub,
+        appId: app?.id,
+        orgId: app?.orgId,
+      });
+
+      return reply.redirect(redirectTargetUrl(clientId, app));
+    } catch (err) {
+      request.log.error({ err }, "OAuth callback failed");
+      clearSessionCookies(reply);
+      const url = buildOAuthErrorRedirect(err, redirectTargetUrl(clientId), { state });
+      return reply.redirect(url);
+    }
+  });
+}
+
+function redirectTargetUrl(clientId?: string, app?: Application): string {
+  if (app?.redirectUris?.length) {
+    return app.redirectUris[0];
+  }
+  return process.env.CLIENT_APP_URL || "http://localhost:5173";
+}

package/src/routes/oauth2.ts

@@ -0,0 +1,284 @@
+import { z } from "zod";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { config } from "../config.js";
+import {
+  storeAuthorizationCode,
+  consumeAuthorizationCode,
+  verifyPKCE,
+  hasConsent,
+  grantConsent,
+  revokeConsent,
+  createTokenResponse,
+  findApplicationByClientId,
+  verifyClientSecret,
+} from "../services/oauth2.js";
+import { findUserById } from "../services/users.js";
+import { revokeRefreshToken, createApplicationAccessToken, rotateRefreshToken } from "../services/tokens.js";
+import { fingerprintFromRequest } from "../services/devices.js";
+import { rateLimit } from "../plugins/rateLimit.js";
+
+const AuthorizeQuerySchema = z.object({
+  client_id: z.string(),
+  redirect_uri: z.string().url(),
+  response_type: z.literal("code"),
+  scope: z.string().optional(),
+  state: z.string().optional(),
+  code_challenge: z.string().min(43).max(128),
+  code_challenge_method: z.literal("S256"),
+  nonce: z.string().optional(),
+});
+
+const TokenBodySchema = z.object({
+  grant_type: z.enum(["authorization_code", "refresh_token", "client_credentials"]),
+  code: z.string().optional(),
+  redirect_uri: z.string().url().optional(),
+  code_verifier: z.string().min(43).max(128).optional(),
+  refresh_token: z.string().optional(),
+  client_id: z.string().optional(),
+  client_secret: z.string().optional(),
+  scope: z.string().optional(),
+});
+
+const ConsentBodySchema = z.object({
+  client_id: z.string(),
+  scopes: z.array(z.string()).default([]),
+  grant: z.boolean(),
+});
+
+interface ClientCredentials {
+  clientId?: string;
+  clientSecret?: string;
+}
+
+function extractClientCredentials(request: FastifyRequest, body: ClientCredentials): ClientCredentials {
+  const authHeader = request.headers.authorization;
+  if (authHeader?.toLowerCase().startsWith("basic ")) {
+    try {
+      const decoded = Buffer.from(authHeader.slice(6), "base64").toString("utf8");
+      const [clientId, clientSecret] = decoded.split(":");
+      return { clientId, clientSecret };
+    } catch {
+      return body;
+    }
+  }
+  return body;
+}
+
+export default async function oauth2Routes(app: FastifyInstance) {
+  app.get(
+    "/authorize",
+    {
+      preHandler: [
+        app.authenticate,
+        rateLimit({ keyPrefix: "oauth2_authorize", maxAttempts: 10, windowSeconds: 60 }),
+      ],
+    },
+    async (request: FastifyRequest, reply: FastifyReply) => {
+      const query = AuthorizeQuerySchema.parse(request.query);
+
+      const application = await findApplicationByClientId(query.client_id);
+      if (!application) {
+        return reply.status(400).send({ error: "invalid_client", error_description: "Unknown client" });
+      }
+
+      if (!application.redirectUris.includes(query.redirect_uri)) {
+        return reply
+          .status(400)
+          .send({ error: "invalid_redirect_uri", error_description: "Redirect URI not registered" });
+      }
+
+      const scopes = query.scope ? query.scope.split(" ").filter(Boolean) : [];
+
+      const consent = await hasConsent(request.user!.id, application.id, scopes);
+      if (!consent) {
+        return reply.status(403).send({
+          error: "consent_required",
+          error_description: "User consent required",
+        });
+      }
+
+      const stored = await storeAuthorizationCode({
+        appId: application.id,
+        userId: request.user!.id,
+        challenge: query.code_challenge,
+        challengeMethod: query.code_challenge_method,
+        redirectUri: query.redirect_uri,
+        scopes,
+        nonce: query.nonce,
+      });
+
+      const url = new URL(query.redirect_uri);
+      url.searchParams.set("code", stored.code);
+      if (query.state) url.searchParams.set("state", query.state);
+
+      await request.audit("oauth2_authorize", {
+        appId: application.id,
+        clientId: application.clientId,
+      });
+
+      return reply.redirect(url.toString());
+    }
+  );
+
+  app.post(
+    "/token",
+    {
+      preHandler: [rateLimit({ keyPrefix: "oauth2_token", maxAttempts: 20, windowSeconds: 60 })],
+    },
+    async (request, reply) => {
+      const parsedBody = TokenBodySchema.parse(request.body);
+      const credentials = extractClientCredentials(request, {
+        clientId: parsedBody.client_id,
+        clientSecret: parsedBody.client_secret,
+      });
+      const body = { ...parsedBody, client_id: credentials.clientId, client_secret: credentials.clientSecret };
+
+      if (body.grant_type === "authorization_code") {
+        if (!body.code || !body.client_id || !body.redirect_uri) {
+          return reply
+            .status(400)
+            .send({ error: "invalid_request", error_description: "code, client_id, and redirect_uri are required" });
+        }
+
+        const application = await findApplicationByClientId(body.client_id);
+        if (!application) {
+          return reply.status(400).send({ error: "invalid_client" });
+        }
+
+        const record = await consumeAuthorizationCode(body.code, application.id, body.redirect_uri);
+        if (!record) {
+          return reply.status(400).send({ error: "invalid_grant" });
+        }
+
+        const verifier = body.code_verifier;
+        if (!verifier) {
+          return reply.status(400).send({ error: "invalid_request", error_description: "PKCE verifier required" });
+        }
+
+        if (!verifyPKCE(record.challenge, record.challengeMethod, verifier)) {
+          return reply.status(400).send({ error: "invalid_grant", error_description: "PKCE verification failed" });
+        }
+
+        const user = await findUserById(record.userId);
+        if (!user) {
+          return reply.status(400).send({ error: "invalid_grant" });
+        }
+
+        await request.audit("oauth2_token", {
+          appId: application.id,
+          clientId: application.clientId,
+          grantType: "authorization_code",
+        });
+
+        const fingerprint = fingerprintFromRequest(request);
+        return createTokenResponse(user, application, record.scopes, {
+          ip: request.ip,
+          userAgent: request.headers["user-agent"],
+          deviceFingerprint: fingerprint,
+          nonce: record.nonce ?? undefined,
+        });
+      }
+
+      if (body.grant_type === "refresh_token") {
+        if (!body.refresh_token) {
+          return reply.status(400).send({ error: "invalid_request" });
+        }
+
+        // Lazy import to avoid circular dependency.
+        const tokens = await rotateRefreshToken(body.refresh_token, request.ip, request.headers["user-agent"]);
+        if (!tokens) {
+          return reply.status(400).send({ error: "invalid_grant" });
+        }
+
+        return {
+          access_token: tokens.accessToken,
+          refresh_token: tokens.refreshToken,
+          token_type: "Bearer",
+          expires_in: config.ACCESS_TOKEN_TTL_SECONDS,
+        };
+      }
+
+      if (body.grant_type === "client_credentials") {
+        if (!body.client_id || !body.client_secret) {
+          return reply.status(400).send({ error: "invalid_request", error_description: "client credentials required" });
+        }
+
+        const application = await verifyClientSecret(body.client_id, body.client_secret);
+        if (!application) {
+          return reply.status(401).send({ error: "invalid_client" });
+        }
+
+        const scopes = body.scope ? body.scope.split(" ").filter(Boolean) : [];
+        const accessToken = await createApplicationAccessToken({
+          appId: application.id,
+          orgId: application.orgId,
+          clientId: application.clientId,
+          scopes,
+        });
+
+        await request.audit("oauth2_client_credentials", {
+          appId: application.id,
+          clientId: application.clientId,
+        });
+
+        return {
+          access_token: accessToken,
+          token_type: "Bearer",
+          expires_in: config.ACCESS_TOKEN_TTL_SECONDS,
+          scope: scopes.join(" "),
+        };
+      }
+
+      return reply.status(400).send({ error: "unsupported_grant_type" });
+    }
+  );
+
+  app.get(
+    "/userinfo",
+    { preHandler: [app.authenticate] },
+    async (request: FastifyRequest) => {
+      const user = request.user!;
+      return {
+        sub: user.id,
+        email: user.email,
+        email_verified: user.emailVerified,
+        username: user.username,
+        name: user.name,
+        picture: user.avatarUrl,
+      };
+    }
+  );
+
+  app.post("/revoke", async (request, reply) => {
+    const body = z.object({ token: z.string() }).parse(request.body);
+    await revokeRefreshToken(body.token);
+    await request.audit("oauth2_revoke", {});
+    return { success: true };
+  });
+
+  app.post(
+    "/consent",
+    { preHandler: [app.authenticate] },
+    async (request: FastifyRequest, reply: FastifyReply) => {
+      const body = ConsentBodySchema.parse(request.body);
+      const application = await findApplicationByClientId(body.client_id);
+      if (!application) {
+        return reply.status(400).send({ error: "invalid_client" });
+      }
+
+      if (body.grant) {
+        await grantConsent(request.user!.id, application.id, body.scopes);
+      } else {
+        await revokeConsent(request.user!.id, application.id);
+      }
+
+      await request.audit("oauth2_consent", {
+        appId: application.id,
+        granted: body.grant,
+        scopes: body.scopes,
+      });
+
+      return { success: true };
+    }
+  );
+}

package/src/routes/oidcEnterprise.ts

@@ -0,0 +1,166 @@
+import crypto from "node:crypto";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import { provisionEnterpriseUser, defaultRoleForOrg } from "../services/enterpriseSso.js";
+import { createTokenSet } from "../services/tokens.js";
+import { setSessionCookies, clearSessionCookies } from "../plugins/auth.js";
+import { fingerprintFromRequest, recordDevice } from "../services/devices.js";
+import { toPublicUser } from "../types.js";
+import { buildOAuthErrorResponse } from "../lib/errors.js";
+
+const OIDC_STATE_COOKIE = "keystone_oidc_enterprise_state";
+
+function publicUrl(): string {
+  return process.env.AUTH_API_PUBLIC_URL || "http://localhost:4001";
+}
+
+function setStateCookie(reply: FastifyReply, state: string): void {
+  reply.setCookie(OIDC_STATE_COOKIE, state, {
+    path: "/",
+    httpOnly: true,
+    secure: process.env.COOKIE_SECURE === "true",
+    sameSite: "lax",
+    maxAge: 600,
+  });
+}
+
+function getStateCookie(request: FastifyRequest): string | undefined {
+  return request.cookies[OIDC_STATE_COOKIE];
+}
+
+function clearStateCookie(reply: FastifyReply): void {
+  reply.clearCookie(OIDC_STATE_COOKIE, { path: "/" });
+}
+
+export default async function oidcEnterpriseRoutes(app: FastifyInstance) {
+  app.get("/sso/oidc/:connectionId", async (request: FastifyRequest, reply: FastifyReply) => {
+    const { connectionId } = request.params as { connectionId: string };
+    const connection = await app.container.oidcConnectionRepository.findActiveById(connectionId);
+
+    if (!connection) {
+      return reply.status(404).send({ error: "OIDC connection not found" });
+    }
+
+    const state = crypto.randomBytes(24).toString("base64url");
+    setStateCookie(reply, `${state}:${connectionId}`);
+
+    const redirectUri = `${publicUrl()}/sso/oidc/${connectionId}/callback`;
+    const url = new URL(connection.authorizationEndpoint);
+    url.searchParams.set("client_id", connection.clientId);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", connection.scopes.join(" "));
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("state", state);
+
+    return reply.redirect(url.toString());
+  });
+
+  app.get("/sso/oidc/:connectionId/callback", async (request: FastifyRequest, reply: FastifyReply) => {
+    const { connectionId } = request.params as { connectionId: string };
+    const query = request.query as { code?: string; state?: string; error?: string; error_description?: string };
+
+    if (query.error) {
+      clearSessionCookies(reply);
+      const idpError = new Error(
+        `Identity provider error: ${query.error}${query.error_description ? ` - ${query.error_description}` : ""}`
+      );
+      const { statusCode, body } = buildOAuthErrorResponse(idpError);
+      return reply.status(statusCode).send(body);
+    }
+
+    const cookieState = getStateCookie(request);
+    clearStateCookie(reply);
+
+    if (!query.code || !query.state || !cookieState || !cookieState.startsWith(`${query.state}:`)) {
+      return reply.status(400).send({ error: "Invalid OIDC state" });
+    }
+
+    const connection = await app.container.oidcConnectionRepository.findActiveById(connectionId);
+
+    if (!connection) {
+      return reply.status(400).send({ error: "OIDC connection not found" });
+    }
+
+    const redirectUri = `${publicUrl()}/sso/oidc/${connectionId}/callback`;
+
+    try {
+      const tokenRes = await fetch(connection.tokenEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          client_id: connection.clientId,
+          client_secret: connection.clientSecret,
+          code: query.code,
+          redirect_uri: redirectUri,
+        }).toString(),
+      });
+
+      if (!tokenRes.ok) {
+        const text = await tokenRes.text();
+        throw new Error(`Token exchange failed: ${tokenRes.status} ${text}`);
+      }
+
+      const tokenData = (await tokenRes.json()) as { access_token: string; id_token?: string };
+
+      const userinfoRes = await fetch(
+        connection.userinfoEndpoint ||
+          connection.scopes.includes("openid")
+          ? `${connection.issuer}/oauth/v2/userinfo`
+          : `${connection.issuer}/userinfo`,
+        {
+          headers: { Authorization: `Bearer ${tokenData.access_token}` },
+        }
+      );
+
+      if (!userinfoRes.ok) {
+        throw new Error(`Userinfo request failed: ${userinfoRes.status}`);
+      }
+
+      const userinfo = (await userinfoRes.json()) as {
+        email?: string;
+        name?: string;
+        preferred_username?: string;
+      };
+
+      if (!userinfo.email) {
+        throw new Error("OIDC provider did not return an email");
+      }
+
+      const org = await app.container.organizationRepository.findById(connection.orgId);
+
+      const user = await provisionEnterpriseUser(
+        connection.orgId,
+        {
+          email: userinfo.email,
+          name: userinfo.name,
+          username: userinfo.preferred_username,
+        },
+        org ? defaultRoleForOrg(org) : "member"
+      );
+
+      const fingerprint = fingerprintFromRequest(request);
+      await recordDevice(user.id, fingerprint, request.ip, request.headers["user-agent"]);
+      const tokens = await createTokenSet(
+        user,
+        request.ip,
+        request.headers["user-agent"],
+        { orgId: connection.orgId },
+        fingerprint
+      );
+      setSessionCookies(reply, tokens.accessToken, tokens.refreshToken);
+
+      await request.audit("oidc_enterprise_login", {
+        orgId: connection.orgId,
+        connectionId: connection.id,
+        userId: user.id,
+      });
+
+      return { user: toPublicUser(user) };
+    } catch (err) {
+      request.log.error({ err }, "OIDC enterprise callback failed");
+      clearSessionCookies(reply);
+      const { statusCode, body } = buildOAuthErrorResponse(err);
+      return reply.status(statusCode).send(body);
+    }
+  });
+}

package/src/routes/password.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import type { FastifyInstance, FastifyReply } from "fastify";
+import { getSdk } from "../sdk/index.js";
+import { isZitadelConfigured } from "../config.js";
+import { requestPasswordReset, setPassword } from "../services/zitadel.js";
+import { findUserByEmail } from "../services/users.js";
+import { emailProvider } from "../services/email.js";
+import { sendResultError } from "./helpers.js";
+import { rateLimit } from "../plugins/rateLimit.js";
+
+const ForgotSchema = z.object({
+  email: z.string().email(),
+});
+
+const ResetSchema = z.object({
+  token: z.string().min(1),
+  newPassword: z.string().min(8).max(128),
+});
+
+function resetUrl(token: string): string {
+  const base = process.env.RESET_PASSWORD_URL || `${process.env.CLIENT_APP_URL || "http://localhost:5173"}/reset-password`;
+  const separator = base.includes("?") ? "&" : "?";
+  return `${base}${separator}token=${encodeURIComponent(token)}`;
+}
+
+export default async function passwordRoutes(app: FastifyInstance) {
+  const sdk = getSdk();
+
+  app.post("/forgot-password", {
+    preHandler: [
+      rateLimit({
+        keyPrefix: "forgot-password",
+        maxAttempts: 5,
+        windowSeconds: 900,
+      }),
+    ],
+  }, async (request, reply) => {
+    const body = ForgotSchema.parse(request.body);
+    const user = await findUserByEmail(body.email);
+
+    // Always return success to avoid email enumeration.
+    if (!user) {
+      await request.audit("password_reset_requested", { found: false });
+      return { success: true };
+    }
+
+    // If Zitadel is configured and the user has a Zitadel mirror, prefer Zitadel's flow.
+    if (isZitadelConfigured() && user.zitadelUserId) {
+      try {
+        const redirectUrl = process.env.RESET_PASSWORD_URL || `${process.env.CLIENT_APP_URL || "http://localhost:5173"}/reset-password`;
+        await requestPasswordReset(user.zitadelUserId, redirectUrl);
+        await request.audit("password_reset_requested", {
+          found: true,
+          userId: user.id,
+          zitadelUserId: user.zitadelUserId,
+        });
+      } catch (err) {
+        request.log.error({ err }, "Zitadel password reset request failed");
+      }
+      return { success: true };
+    }
+
+    // Local token-based reset flow.
+    const result = await sdk.authentication.createPasswordResetToken(body.email);
+    if (!result.success) return sendResultError(reply, result);
+
+    if (result.data) {
+      try {
+        await emailProvider.send({
+          to: user.email,
+          subject: "Reset your Hilbras Keystone password",
+          text: `Click the link to reset your password:\n\n${resetUrl(result.data.token)}\n\nThis link expires in 1 hour.`,
+          html: `<p>Click <a href="${resetUrl(result.data.token)}">here</a> to reset your password.</p><p>This link expires in 1 hour.</p>`,
+        });
+      } catch (err) {
+        request.log.error({ err }, "Failed to send password reset email");
+      }
+    }
+
+    return { success: true };
+  });
+
+  app.post("/reset-password", async (request, reply) => {
+    const body = ResetSchema.parse(request.body);
+    const result = await sdk.authentication.resetPasswordWithToken(body.token, body.newPassword);
+    if (!result.success) return sendResultError(reply, result);
+    await request.audit("password_reset_completed", { userId: result.data.id });
+    return { success: true };
+  });
+}