@k2b/cloud 0.6.0-rc.0

package/src/server/middleware/auth.ts

@@ -0,0 +1,386 @@
+import type { Context } from "hono";
+import { createMiddleware } from "hono/factory";
+import type { MessageResponse, Role, RoleOrSpecial, User, UserProfile, UserProvider } from "../../contracts/shared";
+import { isAccountExpired } from "../../services/account-model";
+import { isReservedWorkloadApiCredential } from "../../services/identity/workload-auth";
+import { oauthTokens } from "../../services/oauth-tokens";
+import { serviceAccountCredentials } from "../../services/service-account-credentials";
+import type { ServiceAccount } from "../../services/service-accounts";
+import { session } from "../../services/session";
+import { createLoginRedirectUrl } from "../../shared/redirect";
+import type { AccessSubject } from "../services/access";
+
+// ==========================
+// Types
+// ==========================
+
+export type InvocationProvenance = {
+  kind: "invocation";
+  callingAppId: string;
+  credentialKind: "session" | "oauth" | "api_key" | "mandate";
+  invocationId: string;
+  requestId?: string | null;
+  mandateId?: string;
+  mandateRevision?: number;
+  workloadType?: string;
+  workloadId?: string;
+};
+
+export type UserRequestActor = {
+  kind: "user";
+  user: User;
+  delegation?: InvocationProvenance;
+};
+
+export type ServiceAccountRequestActor =
+  | {
+      kind: "service_account";
+      serviceAccount: ServiceAccount;
+      delegatedUser: User;
+      scopes: string[];
+      credentialId?: string | null;
+      credentialExpiresAt?: string | null;
+      delegation?: InvocationProvenance;
+    }
+  | {
+      kind: "service_account";
+      serviceAccount: ServiceAccount;
+      delegatedUser: null;
+      scopes: string[];
+      credentialId?: string | null;
+      credentialExpiresAt?: string | null;
+      delegation?: InvocationProvenance;
+    };
+
+export type RequestActor = UserRequestActor | ServiceAccountRequestActor;
+
+export type RequestCredentialKind = "session" | "oauth" | "api_key" | "invocation";
+
+export type RequestAuthority = {
+  actor: RequestActor;
+  accessSubject: AccessSubject;
+  credentialKind: RequestCredentialKind;
+  scopes: string[];
+};
+
+/** Hono context with authenticated user variables. */
+export type AuthContext = {
+  Variables: {
+    actor: RequestActor;
+    accessSubject: AccessSubject;
+    user: User;
+    sessionToken?: string;
+    /** Credential class resolved once for downstream delegation. */
+    credentialKind?: RequestCredentialKind;
+    /** Constraints carried by OAuth/API credentials; absent sessions are unrestricted by transport scope. */
+    credentialScopes?: string[];
+    /** OAuth scopes for bearer-token requests. Absent for sessions and API credentials. */
+    oauthScopes?: string[];
+  };
+};
+
+// ==========================
+// Role-based Middleware
+// ==========================
+
+type RejectResult = string | Response | { message: string; status: number };
+
+type RoleOptions = {
+  onReject?: (c: Context, reason: "unauthenticated" | "forbidden") => RejectResult | Promise<RejectResult>;
+  /** Require any of these audiences for OAuth bearer tokens. Sessions and API keys are unaffected. */
+  oauthAudience?: string | string[] | (() => string | string[] | Promise<string | string[]>);
+};
+
+type AccountOptions = RoleOptions & {
+  provider?: UserProvider;
+  profile?: UserProfile;
+};
+
+const handleReject = async (c: Context, options: RoleOptions, reason: "unauthenticated" | "forbidden"): Promise<Response> => {
+  if (options.onReject) {
+    const result = await options.onReject(c, reason);
+    if (typeof result === "string") return c.redirect(result);
+    if (result instanceof Response) return result;
+    return c.json({ message: result.message } as MessageResponse, result.status as 400 | 401 | 403 | 404 | 500);
+  }
+  // Default: JSON response
+  if (reason === "unauthenticated") {
+    return c.json({ message: "Authentication required" } as MessageResponse, 401);
+  }
+  return c.json({ message: "Insufficient permissions" } as MessageResponse, 403);
+};
+
+type AuthenticatedActorResult = {
+  token: string | null;
+  user: User | null;
+  actor: RequestActor | null;
+};
+
+const actorResolutionByRequest = new WeakMap<Context, Promise<AuthenticatedActorResult>>();
+
+const loadAuthenticatedActorUncached = async (
+  c: Context<AuthContext>,
+  options: Pick<RoleOptions, "oauthAudience"> = {},
+): Promise<AuthenticatedActorResult> => {
+  const token = session.getToken(c);
+  const authenticatedSession = token ? await session.authenticateRequest(c, token) : null;
+  const user = authenticatedSession?.user ?? null;
+
+  if (user && token) {
+    c.set("actor", { kind: "user", user });
+    c.set("accessSubject", { type: "user", userId: user.id });
+    c.set("user", user);
+    c.set("sessionToken", token);
+    c.set("credentialKind", "session");
+  }
+
+  if (user) return { token, user, actor: { kind: "user", user } };
+
+  const bearer = session.getBearerToken(c);
+  if (bearer && serviceAccountCredentials.isApiToken(bearer)) {
+    const authResult = await serviceAccountCredentials.authenticateApiToken(bearer);
+    if (!authResult) return { token: null, user: null, actor: null };
+    // App workload keys enter only through Core's dedicated broker/authority
+    // handlers, which authenticate their exact app binding directly.
+    if (isReservedWorkloadApiCredential(authResult)) return { token: null, user: null, actor: null };
+    if (authResult.delegatedUser && isAccountExpired(authResult.delegatedUser.accountExpires)) {
+      return { token: null, user: null, actor: null };
+    }
+
+    const actor: RequestActor = {
+      kind: "service_account",
+      serviceAccount: authResult.serviceAccount,
+      delegatedUser: authResult.delegatedUser,
+      scopes: authResult.credential.scopes,
+      credentialId: authResult.credential.id,
+      credentialExpiresAt: authResult.credential.expiresAt,
+    };
+    c.set("actor", actor);
+    c.set("credentialKind", "api_key");
+    c.set("credentialScopes", authResult.credential.scopes);
+    if (authResult.delegatedUser) {
+      c.set("accessSubject", { type: "user", userId: authResult.delegatedUser.id });
+      c.set("user", authResult.delegatedUser);
+    } else {
+      c.set("accessSubject", { type: "service_account", serviceAccountId: authResult.serviceAccount.id });
+    }
+    return { token: null, user: authResult.delegatedUser, actor };
+  }
+
+  if (bearer) {
+    const expectedAudience = typeof options.oauthAudience === "function" ? await options.oauthAudience() : options.oauthAudience;
+    const authResult = await oauthTokens.verifyAccessToken(bearer, expectedAudience);
+    if (!authResult) return { token: null, user: null, actor: null };
+
+    if (authResult.kind === "user") {
+      if (isAccountExpired(authResult.user.accountExpires)) return { token: null, user: null, actor: null };
+      const actor: RequestActor = { kind: "user", user: authResult.user };
+      c.set("actor", actor);
+      c.set("accessSubject", { type: "user", userId: authResult.user.id });
+      c.set("user", authResult.user);
+      c.set("oauthScopes", authResult.scopes);
+      c.set("credentialKind", "oauth");
+      c.set("credentialScopes", authResult.scopes);
+      return { token: null, user: authResult.user, actor };
+    }
+
+    if (authResult.delegatedUser && isAccountExpired(authResult.delegatedUser.accountExpires)) {
+      return { token: null, user: null, actor: null };
+    }
+    const actor: RequestActor = {
+      kind: "service_account",
+      serviceAccount: authResult.serviceAccount,
+      delegatedUser: authResult.delegatedUser,
+      scopes: authResult.scopes,
+      credentialId: null,
+      credentialExpiresAt: typeof authResult.payload.exp === "number" ? new Date(authResult.payload.exp * 1_000).toISOString() : null,
+    };
+    c.set("actor", actor);
+    c.set("oauthScopes", authResult.scopes);
+    c.set("credentialKind", "oauth");
+    c.set("credentialScopes", authResult.scopes);
+    if (authResult.delegatedUser) {
+      c.set("accessSubject", { type: "user", userId: authResult.delegatedUser.id });
+      c.set("user", authResult.delegatedUser);
+    } else {
+      c.set("accessSubject", { type: "service_account", serviceAccountId: authResult.serviceAccount.id });
+    }
+    return { token: null, user: authResult.delegatedUser, actor };
+  }
+
+  return { token: null, user: null, actor: null };
+};
+
+const loadAuthenticatedActor = (
+  c: Context<AuthContext>,
+  options: Pick<RoleOptions, "oauthAudience"> = {},
+): Promise<AuthenticatedActorResult> => {
+  if (options.oauthAudience) return loadAuthenticatedActorUncached(c, options);
+  const existing = actorResolutionByRequest.get(c);
+  if (existing) return existing;
+  const pending = loadAuthenticatedActorUncached(c, options);
+  actorResolutionByRequest.set(c, pending);
+  return pending;
+};
+
+/**
+ * Universal auth middleware. Handles authentication AND authorization.
+ *
+ * @param args - Roles to check (OR logic) + optional RoleOptions at the end. Special roles:
+ *   - "*": No check, always passes (like optionalAuth)
+ *   - "authenticated": Any logged-in user
+ *   - "anonymous": Only non-logged-in users (for login page)
+ *
+ * @example
+ * // API: Only admins (returns JSON 401/403)
+ * .use(requireRole("admin"))
+ *
+ * // API: Admins OR group managers
+ * .use(requireRole("admin", "group-manager"))
+ *
+ * // SSR: Admin area with redirect
+ * .use(requireRole("admin", redirect("/")))
+ *
+ * // SSR: Protected page with login redirect
+ * .use(requireRole("authenticated", redirectToLogin))
+ *
+ * // SSR: Login page (only for non-logged-in users)
+ * .use(requireRole("anonymous", redirect("/")))
+ */
+const requireRole = (...args: (RoleOrSpecial | RoleOptions)[]) => {
+  // Parse args: roles + optional options at the end
+  const lastArg = args[args.length - 1];
+  const hasOptions = typeof lastArg === "object" && lastArg !== null && ("onReject" in lastArg || "oauthAudience" in lastArg);
+  const options: RoleOptions = hasOptions ? (args.pop() as RoleOptions) : {};
+  const roles = args as RoleOrSpecial[];
+
+  return createMiddleware<AuthContext>(async (c, next) => {
+    // "*" = no check at all, pass through (but try to load user)
+    if (roles.includes("*")) {
+      await loadAuthenticatedActor(c, options);
+      return next();
+    }
+
+    const { user, actor } = await loadAuthenticatedActor(c, options);
+
+    // "anonymous" = must NOT be logged in
+    if (roles.includes("anonymous")) {
+      if (actor) {
+        return handleReject(c, options, "forbidden");
+      }
+      return next();
+    }
+
+    // All other roles require authentication
+    if (!actor) {
+      return handleReject(c, options, "unauthenticated");
+    }
+
+    // "authenticated" = any logged-in user
+    if (roles.includes("authenticated")) {
+      return next();
+    }
+
+    if (!user) {
+      return handleReject(c, options, "forbidden");
+    }
+
+    // Check if user has at least one required role
+    const hasRequiredRole = roles.some((role) => user.roles.includes(role as Role));
+    if (!hasRequiredRole) {
+      return handleReject(c, options, "forbidden");
+    }
+
+    return next();
+  });
+};
+
+/**
+ * Require a request that has a user behind it.
+ *
+ * `requireRole("authenticated")` deliberately admits any authenticated
+ * principal, including a resource-bound service account that has no user at
+ * all — that is what lets an API key reach an ordinary app route. It is the one
+ * role branch that does not imply a user, so a route gated with it that then
+ * reaches for roles, ownership or a display name is reaching for something that
+ * may not be there.
+ *
+ * Use this alongside it wherever the handler needs the user itself, so the
+ * caller gets a 403 stating the reason instead of whatever the missing user
+ * turns into further down.
+ */
+const requireUser = (options: RoleOptions = {}) =>
+  createMiddleware<AuthContext>(async (c, next) => {
+    const { user } = await loadAuthenticatedActor(c);
+    if (user) return next();
+    // A caller that reaches here is authenticated but has no user, so the
+    // generic "Insufficient permissions" would send them looking for a missing
+    // role. `onReject` still wins, which is what keeps SSR redirects working.
+    if (options.onReject) return handleReject(c, options, "forbidden");
+    return c.json({ message: "Self-service endpoints require a user-backed actor", code: "FORBIDDEN" }, 403);
+  });
+
+/** Require one OAuth scope when the caller uses OAuth. Sessions and API credentials are unaffected. */
+const requireOAuthScope = (...requiredScopes: string[]) =>
+  createMiddleware<AuthContext>(async (c, next) => {
+    const scopes = c.get("oauthScopes");
+    if (!scopes || requiredScopes.some((scope) => scopes.includes(scope))) return next();
+    return c.json({ code: "FORBIDDEN", message: `OAuth scope ${requiredScopes.join(" or ")} is required` }, 403);
+  });
+
+const getAuthority = (c: Context<AuthContext>): RequestAuthority => {
+  const actor = c.get("actor");
+  const accessSubject = c.get("accessSubject");
+  const credentialKind = c.get("credentialKind");
+  if (!actor || !accessSubject || !credentialKind) throw new Error("Request authority has not been resolved");
+  return {
+    actor,
+    accessSubject,
+    credentialKind,
+    scopes: [...(c.get("credentialScopes") ?? [])],
+  };
+};
+
+/** Preset: Redirect to a fixed URL on rejection */
+const redirect = (url: string): RoleOptions => ({
+  onReject: () => url,
+});
+
+/** Preset: Redirect to login page with returnTo parameter */
+const redirectToLogin: RoleOptions = {
+  onReject: (c) => createLoginRedirectUrl(c.req.url),
+};
+
+const requireAccount = (options: AccountOptions) =>
+  createMiddleware<AuthContext>(async (c, next) => {
+    const { user } = await loadAuthenticatedActor(c);
+
+    if (!user) {
+      return handleReject(c, options, "unauthenticated");
+    }
+
+    if (options.provider && user.provider !== options.provider) {
+      return handleReject(c, options, "forbidden");
+    }
+
+    if (options.profile && user.profile !== options.profile) {
+      return handleReject(c, options, "forbidden");
+    }
+
+    return next();
+  });
+
+// ==========================
+// Export
+// ==========================
+
+export const auth = {
+  session,
+  requireRole,
+  requireUser,
+  requireOAuthScope,
+  getAuthority,
+  requireAccount,
+  redirect,
+  redirectToLogin,
+};

package/src/server/middleware/index.ts

@@ -0,0 +1,28 @@
+export type { AccessSubject } from "../services/access";
+
+export {
+  type AuthContext,
+  auth,
+  type InvocationProvenance,
+  type RequestActor,
+  type RequestAuthority,
+  type RequestCredentialKind,
+  type ServiceAccountRequestActor,
+  type UserRequestActor,
+} from "./auth";
+export { type InvocationExpectation, requireInvocation } from "./invocation";
+export { middleware } from "./middleware";
+export {
+  imageResponse,
+  jsonResponse,
+  openApiMeta,
+  requiresAdmin,
+  requiresAuth,
+  requiresIpa,
+  requiresIpaUser,
+  requiresUser,
+} from "./openapi";
+export { type RateLimitConfig, type RateLimitRouteOverride, rateLimit } from "./rate-limit";
+export { requestLogger } from "./request-logger";
+export { type ValidatorError, type ValidatorErrorResolver, v, validator } from "./validator";
+export { isReservedWorkloadCredential, rejectReservedWorkloadCredential } from "./workload";

package/src/server/middleware/invocation.ts

@@ -0,0 +1,55 @@
+import type { Context, MiddlewareHandler } from "hono";
+import { createMiddleware } from "hono/factory";
+import { type ResolvedInvocationAuthority, resolveInvocationAuthority } from "../../services/identity/invocation-actor";
+import { type CloudInvocationClaims, isInvocationJwtCandidate, verifyInvocationToken } from "../../services/identity/invocation-token";
+import type { AuthContext } from "./auth";
+
+export type InvocationExpectation = {
+  targetAppId: string;
+  operation: string;
+  schemaHash: string | null;
+};
+
+type InvocationMiddlewareDependencies = {
+  verify?: typeof verifyInvocationToken;
+  resolve?: typeof resolveInvocationAuthority;
+};
+
+const bearerToken = (c: Context): string | null => {
+  const header = c.req.header("Authorization");
+  const match = header?.match(/^Bearer\s+(\S+)$/i);
+  return match?.[1] ?? null;
+};
+
+const reject = (c: Context<AuthContext>): Response =>
+  c.json({ code: "UNAUTHORIZED", message: "A valid Cloud invocation is required" }, 401);
+
+const installAuthority = (c: Context<AuthContext>, claims: CloudInvocationClaims, authority: ResolvedInvocationAuthority): void => {
+  c.set("actor", authority.actor);
+  c.set("accessSubject", authority.accessSubject);
+  c.set("credentialKind", "invocation");
+  c.set("credentialScopes", authority.scopes);
+  if (authority.actor.kind === "user") c.set("user", authority.actor.user);
+  else if (authority.actor.delegatedUser) c.set("user", authority.actor.delegatedUser);
+  if (claims.credential_kind === "oauth") c.set("oauthScopes", authority.scopes);
+};
+
+export const requireInvocation = (
+  expected: (c: Context<AuthContext>) => InvocationExpectation | null,
+  dependencies: InvocationMiddlewareDependencies = {},
+): MiddlewareHandler<AuthContext> =>
+  createMiddleware<AuthContext>(async (c, next) => {
+    const token = bearerToken(c);
+    const expectation = expected(c);
+    if (!token || !expectation || !isInvocationJwtCandidate(token)) return reject(c);
+
+    const claims = await (dependencies.verify ?? verifyInvocationToken)(token, expectation, { deferSchemaBinding: true });
+    if (!claims) return reject(c);
+    const authority = await (dependencies.resolve ?? resolveInvocationAuthority)(claims);
+    if (!authority) return reject(c);
+    if (claims.schema_hash !== expectation.schemaHash) {
+      return c.json({ code: "SCHEMA_MISMATCH", message: "The invocation schema no longer matches the target" }, 409);
+    }
+    installAuthority(c, claims, authority);
+    return next();
+  });

package/src/server/middleware/middleware.ts

@@ -0,0 +1,65 @@
+/**
+ * The `middleware` namespace bundles the request-lifecycle primitives
+ * that every cloud app composes into its own router. Apps register
+ * what they need; the framework no longer injects anything implicitly.
+ *
+ *   import { middleware, auth } from "@k2b/cloud/server"
+ *
+ *   const router = new Hono<AuthContext>()
+ *     .use("*", middleware.logger())
+ *     .use("*", middleware.runtime())     // for Layout / Sidebar / dashboard / search
+ *     .use("*", middleware.settings())    // for c.get("settings")
+ *     .use("*", middleware.ratelimit())
+ *     .use(auth.requireRole("user"))
+ *     .post(
+ *       "/",
+ *       middleware.validator("json", Schema),
+ *       middleware.openapi({ tags: ["foo"], summary: "Create" }),
+ *       handler,
+ *     )
+ *
+ * `auth` lives separately because it has its own surface
+ * (requireRole, redirectToLogin, session.*) and is conceptually
+ * orthogonal to the request lifecycle.
+ */
+import { describeRoute } from "hono-openapi";
+import { rateLimit } from "./rate-limit";
+import { requestLogger } from "./request-logger";
+import { routeTemplate } from "./route-template";
+import { runtime } from "./runtime";
+import { settings } from "./settings";
+import { validator } from "./validator";
+
+export const middleware = {
+  /**
+   * Live cluster registry on `c.get("runtime")`. Required for Layout/Sidebar.
+   * Also reports the matched route template to gateway telemetry — you do not
+   * need `observability()` on top of this.
+   */
+  runtime,
+  /** Frozen per-request settings snapshot on `c.get("settings")`. */
+  settings,
+  /**
+   * Reports the matched Hono route template to gateway telemetry, so the
+   * admin telemetry page can break an app down per endpoint instead of
+   * lumping every request under one registry prefix.
+   *
+   * **Only use this if you do NOT already use `middleware.runtime()`** —
+   * `runtime()` does the same thing, and installing both just runs it twice.
+   * Practically every app renders `<Layout>` and therefore needs `runtime()`
+   * anyway; this exists for the rare app that serves an API surface only.
+   *
+   * ```ts
+   * new Hono().use("*", middleware.observability())   // no runtime() here
+   * ```
+   */
+  observability: () => routeTemplate,
+  /** HTTP request logger (logs 5xx as error, 429 as warn, 401/403 as info). */
+  logger: () => requestLogger,
+  /** Sliding-window rate limiter, keyed by user id (auto fallback to IP). */
+  ratelimit: rateLimit,
+  /** Zod input validator. `c.req.valid(target)` is fully typed afterward. */
+  validator,
+  /** OpenAPI route metadata — re-export of hono-openapi's `describeRoute`. */
+  openapi: describeRoute,
+} as const;

package/src/server/middleware/openapi.ts

@@ -0,0 +1,126 @@
+import { type GenerateSpecOptions, resolver } from "hono-openapi";
+import type { ZodType } from "zod";
+
+// ==========================
+// Response Helpers
+// ==========================
+
+/**
+ * Helper to define JSON response schema for OpenAPI documentation.
+ *
+ * @param schema - Zod schema for the response body
+ * @param description - Human-readable description of the response
+ * @returns OpenAPI response object with application/json content type
+ */
+export const jsonResponse = <T extends ZodType>(schema: T, description: string) => ({
+  description,
+  content: {
+    "application/json": {
+      schema: resolver(schema),
+    },
+  },
+});
+
+/**
+ * Helper to define image response for OpenAPI documentation.
+ *
+ * @param description - Human-readable description of the response
+ * @returns OpenAPI response object with image/webp content type
+ */
+export const imageResponse = (description: string) => ({
+  description,
+  content: {
+    "image/webp": {
+      schema: { type: "string" as const, format: "binary" },
+    },
+  },
+});
+
+// ==========================
+// OpenAPI Specification
+// ==========================
+
+/**
+ * OpenAPI spec metadata for the API documentation.
+ * Includes info, tags, and security schemes.
+ */
+export const openApiMeta: Partial<GenerateSpecOptions> = {
+  documentation: {
+    info: {
+      // Hardcoded — the OpenAPI spec is generated at module-load and
+      // settings reads are async. The dynamic per-deployment app name
+      // appears elsewhere (Layout header, page titles).
+      title: "Cloud API",
+      version: "0.0.1",
+      description: "IPA Management Tool API",
+    },
+    servers: [{ url: "/api", description: "API Server" }],
+    tags: [
+      {
+        name: "Auth",
+        description: "Authentication endpoints (login, logout, refresh)",
+      },
+      { name: "Users", description: "User listing and search (admin)" },
+      { name: "Groups", description: "Group listing and search (admin)" },
+    ],
+    components: {
+      securitySchemes: {
+        cookieAuth: {
+          type: "apiKey",
+          in: "cookie",
+          name: "session_token",
+          description: "Session cookie (automatically set after login)",
+        },
+        bearerAuth: {
+          type: "http",
+          scheme: "bearer",
+          description: "Bearer token in Authorization header",
+        },
+      },
+    },
+  },
+};
+
+// ==========================
+// Security Requirements
+// ==========================
+
+/**
+ * Security requirement for routes that need authentication.
+ * Accepts either cookie or bearer token.
+ */
+export const requiresAuth = {
+  security: [{ cookieAuth: [] as string[], bearerAuth: [] as string[] }],
+};
+
+/**
+ * Security requirement for routes that need admin role.
+ * Accepts either cookie or bearer token.
+ */
+export const requiresAdmin = {
+  security: [{ cookieAuth: [] as string[], bearerAuth: [] as string[] }],
+};
+
+/**
+ * Security requirement for routes that need any authenticated user.
+ * Accepts either cookie or bearer token.
+ */
+export const requiresIpa = {
+  security: [{ cookieAuth: [] as string[], bearerAuth: [] as string[] }],
+};
+
+/**
+ * Security requirement for routes that need a full user profile.
+ * Accepts either cookie or bearer token.
+ */
+export const requiresUser = {
+  security: [{ cookieAuth: [] as string[], bearerAuth: [] as string[] }],
+};
+
+/**
+ * Security requirement for routes that need an IPA-backed full user.
+ * Accepts either cookie or bearer token.
+ */
+export const requiresIpaUser = {
+  security: [{ cookieAuth: [] as string[], bearerAuth: [] as string[] }],
+};