@valentinkolb/cloud 0.3.1 → 0.5.0

package/src/api/announcements.ts

@@ -0,0 +1,131 @@
+import { ok } from "@valentinkolb/stdlib";
+import { Hono } from "hono";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import {
+  ActiveAnnouncementsResponseSchema,
+  AnnouncementEntrySchema,
+  AnnouncementListResponseSchema,
+  CreateAnnouncementSchema,
+  ErrorResponseSchema,
+  MessageResponseSchema,
+  parseAnnouncementCookieHeader,
+  UpdateAnnouncementSchema,
+} from "../contracts";
+import { type AuthContext, auth, jsonResponse, requiresAdmin, requiresAuth, respond, v } from "../server";
+import { announcements } from "../services";
+
+const IdParamSchema = z.object({ id: z.uuid() });
+
+const withMessage = async <T>(operation: Promise<import("@valentinkolb/stdlib").Result<T>>, message: string) => {
+  const result = await operation;
+  if (!result.ok) return result;
+  return ok({ message });
+};
+
+export const announcementRoutes = new Hono<AuthContext>().get(
+  "/active",
+  auth.requireRole("authenticated"),
+  describeRoute({
+    tags: ["Announcements"],
+    summary: "List active user announcements",
+    description: "Returns active banners and unseen announcements for the current request cookie state.",
+    ...requiresAuth,
+    responses: {
+      200: jsonResponse(ActiveAnnouncementsResponseSchema, "Active announcements"),
+      401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+    },
+  }),
+  async (c) => {
+    const state = parseAnnouncementCookieHeader(c.req.header("Cookie"));
+    return respond(c, ok(await announcements.active.forState({ state })));
+  },
+);
+
+export const adminAnnouncementRoutes = new Hono<AuthContext>()
+  .use(auth.requireRole("admin"))
+  .get(
+    "/",
+    describeRoute({
+      tags: ["Admin Announcements"],
+      summary: "List announcements",
+      ...requiresAdmin,
+      responses: {
+        200: jsonResponse(AnnouncementListResponseSchema, "Announcements"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+      },
+    }),
+    v(
+      "query",
+      z.object({
+        kind: z.enum(["announcement", "banner"]).optional(),
+        search: z.string().optional(),
+      }),
+    ),
+    async (c) => {
+      const query = c.req.valid("query");
+      const items = await announcements.admin.list({
+        filter: { kind: query.kind, query: query.search },
+      });
+      return respond(c, ok({ items }));
+    },
+  )
+  .post(
+    "/",
+    describeRoute({
+      tags: ["Admin Announcements"],
+      summary: "Create announcement",
+      ...requiresAdmin,
+      responses: {
+        201: jsonResponse(AnnouncementEntrySchema, "Created announcement"),
+        400: jsonResponse(ErrorResponseSchema, "Validation error"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+      },
+    }),
+    v("json", CreateAnnouncementSchema),
+    async (c) => respond(c, announcements.admin.create({ data: c.req.valid("json"), actorId: c.get("user").id }), 201),
+  )
+  .patch(
+    "/:id",
+    describeRoute({
+      tags: ["Admin Announcements"],
+      summary: "Update announcement",
+      ...requiresAdmin,
+      responses: {
+        200: jsonResponse(AnnouncementEntrySchema, "Updated announcement"),
+        400: jsonResponse(ErrorResponseSchema, "Validation error"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+        404: jsonResponse(ErrorResponseSchema, "Announcement not found"),
+      },
+    }),
+    v("param", IdParamSchema),
+    v("json", UpdateAnnouncementSchema),
+    async (c) =>
+      respond(
+        c,
+        announcements.admin.update({
+          id: c.req.valid("param").id,
+          data: c.req.valid("json"),
+          actorId: c.get("user").id,
+        }),
+      ),
+  )
+  .delete(
+    "/:id",
+    describeRoute({
+      tags: ["Admin Announcements"],
+      summary: "Delete announcement",
+      ...requiresAdmin,
+      responses: {
+        200: jsonResponse(MessageResponseSchema, "Announcement deleted"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+        404: jsonResponse(ErrorResponseSchema, "Announcement not found"),
+      },
+    }),
+    v("param", IdParamSchema),
+    async (c) => respond(c, withMessage(announcements.admin.remove({ id: c.req.valid("param").id }), "Announcement deleted.")),
+  );

package/src/api/auth/schemas.ts

@@ -11,6 +11,7 @@ export const LoginSchema = z.object({
 export const EmailLoginSchema = z.object({
   email: z.email(),
   acceptedAgb: z.literal(true),
+  redirectTo: z.string().max(2048).optional(),
 });
 
 export const VerifyTokenSchema = z.object({
@@ -18,6 +19,24 @@ export const VerifyTokenSchema = z.object({
   acceptedAgb: z.literal(true),
 });
 
+export const PasswordResetRequestSchema = z.object({
+  email: z.email(),
+  acceptedAgb: z.literal(true),
+  redirectTo: z.string().max(2048).optional(),
+});
+
+export const PasswordResetCompleteSchema = z
+  .object({
+    token: z.uuid(),
+    newPassword: z.string().min(8),
+    confirmPassword: z.string().min(1),
+    acceptedAgb: z.literal(true),
+  })
+  .refine((data) => data.newPassword === data.confirmPassword, {
+    message: "Passwords do not match",
+    path: ["confirmPassword"],
+  });
+
 export const AdminLoginSchema = z.object({
   token: z.string().min(1),
 });
@@ -26,3 +45,8 @@ export const AuthResponseSchema = z.object({
   session_token: z.string(),
   user: UserSchema,
 });
+
+export const VerifyPasskeyAuthenticationSchema = z.object({
+  response: z.unknown(),
+  acceptedAgb: z.literal(true),
+});

package/src/api/auth.ts

@@ -1,10 +1,12 @@
 import { Hono, type Context } from "hono";
 import { describeRoute } from "hono-openapi";
+import { z } from "zod";
 import { v } from "../server";
 import { jsonResponse } from "../server";
 import { auth, type AuthContext } from "../server";
 import { rateLimit } from "../server";
-import { authFlows, accounts, getFreeIpaConfig, logger } from "../services";
+import { respond } from "../server";
+import { authFlows, accounts, getFreeIpaConfig, logger, webauthn } from "../services";
 import { sql } from "bun";
 import { env } from "../config";
 import { ChangeExpiredPasswordSchema } from "../contracts";
@@ -14,8 +16,11 @@ import {
   LoginSchema,
   EmailLoginSchema,
   VerifyTokenSchema,
+  PasswordResetRequestSchema,
+  PasswordResetCompleteSchema,
   AdminLoginSchema,
   AuthResponseSchema,
+  VerifyPasskeyAuthenticationSchema,
 } from "./auth/schemas";
 import { ErrorResponseSchema, MessageResponseSchema } from "../contracts";
 
@@ -56,7 +61,7 @@ const app = new Hono<AuthContext>()
       }
 
       // Store minimal session in Redis
-      const sessionToken = await auth.session.create(c, loginResult.userId, loginResult.ipaSession);
+      const sessionToken = await auth.session.create(c, loginResult.userId);
 
       log.info("Login successful", { uid: username });
       return c.json({
@@ -65,13 +70,51 @@ const app = new Hono<AuthContext>()
       });
     },
   )
+  .post(
+    "/passkeys/authentication/start",
+    describeRoute({
+      tags: ["Auth"],
+      summary: "Start passkey login",
+      description: "Create WebAuthn authentication options for passkey sign-in.",
+      responses: {
+        200: jsonResponse(z.unknown(), "Passkey authentication options"),
+        400: jsonResponse(ErrorResponseSchema, "Passkey login is not available"),
+      },
+    }),
+    async (c) => respond(c, webauthn.beginAuthentication()),
+  )
+  .post(
+    "/passkeys/authentication/verify",
+    describeRoute({
+      tags: ["Auth"],
+      summary: "Verify passkey login",
+      description: "Verify a WebAuthn authentication response and create a normal Cloud session.",
+      responses: {
+        200: jsonResponse(AuthResponseSchema, "Passkey login successful"),
+        401: jsonResponse(ErrorResponseSchema, "Passkey verification failed"),
+      },
+    }),
+    v("json", VerifyPasskeyAuthenticationSchema),
+    async (c) => {
+      const result = await webauthn.finishAuthentication({
+        response: c.req.valid("json").response as never,
+      });
+      if (!result.ok) {
+        const status = result.error.status;
+        return c.json({ message: result.error.message, code: result.error.code }, status as 400 | 401 | 403 | 404 | 409 | 500);
+      }
+
+      const sessionToken = await auth.session.create(c, result.data.user.id);
+      log.info("Passkey login successful", { uid: result.data.user.uid });
+      return c.json({ session_token: sessionToken, user: result.data.user });
+    },
+  )
   .post(
     "/logout",
     describeRoute({
       tags: ["Auth"],
       summary: "Logout",
-      description:
-        "Idempotent: clears the session cookie and deletes the session key if present. No authentication required — logout must always succeed.",
+      description: "Idempotent: clears the session cookie and deletes the session key if present. No authentication required — logout must always succeed.",
       responses: {
         200: jsonResponse(MessageResponseSchema, "Session invalidated"),
       },
@@ -116,7 +159,7 @@ const app = new Hono<AuthContext>()
         return jsonError(c, changeResult.message, changeResult.status === 401 ? 401 : 400);
       }
 
-      const sessionToken = await auth.session.create(c, changeResult.userId, changeResult.ipaSession);
+      const sessionToken = await auth.session.create(c, changeResult.userId);
 
       log.info("Password changed via expired flow", { uid: username });
       return c.json({ session_token: sessionToken, user: changeResult.user });
@@ -135,9 +178,12 @@ const app = new Hono<AuthContext>()
     }),
     v("json", EmailLoginSchema),
     async (c) => {
-      const { email } = c.req.valid("json");
+      const { email, redirectTo } = c.req.valid("json");
 
-      const requestResult = await authFlows.magicLink.request({ email });
+      const requestResult = await authFlows.magicLink.request({
+        email,
+        redirectTo,
+      });
       if (!requestResult.ok) {
         return c.json({ message: requestResult.message }, requestResult.status);
       }
@@ -171,15 +217,72 @@ const app = new Hono<AuthContext>()
       }
 
       // Create session (no IPA session for email-only users)
-      const sessionToken = await auth.session.create(c, verifyResult.userId, null);
+      const sessionToken = await auth.session.create(c, verifyResult.userId);
 
       if (verifyResult.createdGuest) {
-        log.info("Guest user created", { email: verifyResult.email, uid: verifyResult.user.uid });
+        log.info("Guest user created", {
+          email: verifyResult.email,
+          uid: verifyResult.user.uid,
+        });
       }
       log.info("Token verified", { email: verifyResult.email });
       return c.json({ session_token: sessionToken, user: verifyResult.user });
     },
   )
+  .post(
+    "/password-reset/request",
+    describeRoute({
+      tags: ["Auth"],
+      summary: "Request password reset",
+      description: "Request a one-time password reset email for an IPA-backed account. The response is always generic to avoid account enumeration.",
+      responses: {
+        200: jsonResponse(MessageResponseSchema, "Request accepted"),
+      },
+    }),
+    v("json", PasswordResetRequestSchema),
+    async (c) => {
+      const { email, redirectTo } = c.req.valid("json");
+
+      const result = await authFlows.passwordReset.request({
+        email,
+        redirectTo,
+      });
+      return c.json({ message: result.message });
+    },
+  )
+  .post(
+    "/password-reset/complete",
+    describeRoute({
+      tags: ["Auth"],
+      summary: "Complete password reset",
+      description: "Set a new password using a one-time reset token. Creates a normal Cloud session only after the password was changed successfully.",
+      responses: {
+        200: jsonResponse(AuthResponseSchema, "Password reset completed and session created"),
+        400: jsonResponse(ErrorResponseSchema, "Password reset failed"),
+        401: jsonResponse(ErrorResponseSchema, "Invalid or expired reset token"),
+      },
+    }),
+    v("json", PasswordResetCompleteSchema),
+    async (c) => {
+      const { token, newPassword } = c.req.valid("json");
+
+      const result = await authFlows.passwordReset.complete({
+        token,
+        newPassword,
+      });
+      if (!result.ok) {
+        if (result.reason === "policy_failed") {
+          return c.json({ message: result.message }, 400);
+        }
+        const status = result.status >= 500 ? 500 : result.status === 401 ? 401 : 400;
+        return jsonError(c, result.message, status);
+      }
+
+      const sessionToken = await auth.session.create(c, result.userId);
+      log.info("Password reset completed", { uid: result.user.uid });
+      return c.json({ user: result.user, session_token: sessionToken });
+    },
+  )
   .post(
     "/admin-login",
     describeRoute({
@@ -221,7 +324,7 @@ const app = new Hono<AuthContext>()
       const user = await accounts.users.get({ uid: "admin" });
       if (!user) return jsonError(c, "Failed to resolve admin user.", 500);
 
-      const sessionToken = await auth.session.create(c, user.id, null);
+      const sessionToken = await auth.session.create(c, user.id);
       log.info("Admin login successful");
       return c.json({ session_token: sessionToken, user });
     },

package/src/api/index.ts

@@ -8,17 +8,19 @@
  * Apps that need a typed client to these routes import from
  * `@valentinkolb/cloud/clients/core`. The client and the routes share their
  * type via `CoreApiType` below.
+ *
+ * The OpenAPI spec for these routes is generated by `defineApp` (driven by
+ * core's `openapi: "/api/openapi.json"` opt-in) — this file no longer mounts
+ * any docs UI; the api-docs aggregator at `/app/api-docs` is the only consumer.
  */
 import { Hono } from "hono";
-import { Scalar } from "@scalar/hono-api-reference";
-import { generateSpecs } from "hono-openapi";
 import { prettyJSON } from "hono/pretty-json";
-import { createMarkdownFromOpenApi } from "@scalar/openapi-to-markdown";
-import { openApiMeta } from "../server";
+import accountsEntitiesRoutes from "./accounts-entities";
+import adminCoreSettingsRoutes from "./admin-core-settings";
+import adminLifecycleRoutes from "./admin-lifecycle";
+import { adminAnnouncementRoutes, announcementRoutes } from "./announcements";
 import authRoutes from "./auth";
 import meRoutes from "./me";
-import adminLifecycleRoutes from "./admin-lifecycle";
-import accountsEntitiesRoutes from "./accounts-entities";
 import { createSearchRoutes } from "./search";
 
 /**
@@ -33,6 +35,9 @@ const buildCoreApi = () => {
     .route("/auth", authRoutes)
     .route("/me", meRoutes)
     .route("/accounts", accountsEntitiesRoutes)
+    .route("/announcements", announcementRoutes)
+    .route("/admin/core/announcements", adminAnnouncementRoutes)
+    .route("/admin/core/settings", adminCoreSettingsRoutes)
     .route("/admin/lifecycle", adminLifecycleRoutes)
     .route("/", searchRoutes);
 };
@@ -41,26 +46,11 @@ const buildCoreApi = () => {
 export type CoreApiType = ReturnType<typeof buildCoreApi>;
 
 /**
- * Build the core router and accompanying OpenAPI assets. The core-app calls
- * this and mounts the returned router under `/api`.
+ * Build the core router. The core-app calls this and mounts the returned
+ * router under `/api`.
  */
-export const createCoreApiRouter = async () => {
+export const createCoreApiRouter = () => {
   const api = buildCoreApi();
-
-  const spec = await generateSpecs(api, openApiMeta);
-  const llmsTxt = await createMarkdownFromOpenApi(JSON.stringify(spec));
-
-  api.get("/openapi.json", (c) => c.json(spec));
-  api.get(
-    "/docs",
-    Scalar({
-      theme: "saturn",
-      url: "/api/openapi.json",
-      hideClientButton: true,
-    }),
-  );
-
   api.all("/*", (c) => c.json({ message: "API route not found" }, 404));
-
-  return { api, llmsTxt };
+  return { api };
 };