@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/api/auth-middleware.ts

@@ -16,6 +16,12 @@ export const AUTH_COOKIE_NAME = "kumiko_auth";
 export const CSRF_COOKIE_NAME = "kumiko_csrf";
 export const CSRF_HEADER_NAME = "X-CSRF-Token";
 
+// Prefix that marks a bearer token as a long-lived Personal Access Token
+// rather than a JWT session. The personal-access-tokens feature mints tokens
+// with this prefix and declares it as its tokenVerifier shape (kind:
+// "prefix") — kept here so both sides import the same literal.
+export const PAT_TOKEN_PREFIX = "kpat_";
+
 // Which wire the current request authenticated over. Downstream
 // csrf-middleware reads this: cookie-auth gets a CSRF-token check, bearer
 // does not (headers aren't set cross-origin by browsers, so there is no
@@ -41,21 +47,39 @@ export type AuthSessionChecker = (
   expectedUserId: string,
 ) => Promise<AuthSessionStatus>;
 
+// Resolves a raw bearer token into a SessionUser, or null when no registered
+// provider claims it (or the claiming provider rejects it as unknown/revoked/
+// expired). Wired generically from the auth-foundation `tokenVerifier`
+// extension-point registry — the middleware has no PAT/JWT-specific
+// knowledge, it just consults whatever the app wired in and short-circuits
+// the JWT path on a hit.
+export type TokenVerifier = (rawToken: string) => Promise<SessionUser | null>;
+
+export type TenantLifecycleStatusResolver = (
+  tenantId: TenantId,
+) => Promise<{ readonly status: string } | null>;
+
 export type AuthMiddlewareOptions = {
   // Called after JWT-verify when the token carries a sid. If the checker
   // reports anything other than "live", the request is rejected with 401.
   // Omit to run in stateless-JWT mode (any valid JWT is accepted).
   readonly sessionChecker?: AuthSessionChecker;
-  // When true, a JWT WITHOUT a sid is rejected. Leave false during rollout
-  // so already-issued stateless JWTs keep working until they expire; flip
-  // to true once the server has been emitting sid for longer than the JWT
-  // TTL. Has no effect when sessionChecker is undefined.
-  readonly strictMode?: boolean;
+  // Called for bearer tokens, BEFORE jwt.verify. On a hit the middleware
+  // sets the returned SessionUser and skips the JWT path entirely; on a
+  // miss (null) falls through to jwt.verify. Wired from the auth-foundation
+  // `tokenVerifier` extension-point registry — generic across providers
+  // (PAT, future JWT-provider, ...), the middleware itself has no
+  // provider-specific knowledge. Omit to disable non-JWT bearer auth.
+  readonly tokenVerifier?: TokenVerifier;
   // Opt-in: when set, requests without a JWT are treated as anonymous
   // callers instead of being rejected with 401. The middleware synthesises
   // a SessionUser with id="anonymous" and roles=["anonymous"], scoped to a
   // tenantId resolved through the chain documented on AnonymousAccessConfig.
-  readonly anonymousAccess?: AnonymousAccessConfig;
+  readonly anonymousAccess?: AnonymousAccessResolved;
+  // Consulted after tenantId is resolved (JWT/PAT/anonymous). Returns 410
+  // when the tenant is in teardown (destroyRequested/destroying/destroyed).
+  // cancel-destruction is exempt while status=destroyRequested.
+  readonly resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver;
 };
 
 // Resolves the tenant for an unauthenticated request. Returns null when no
@@ -72,23 +96,22 @@ export type TenantResolver = (c: Context) => Promise<TenantId | null> | TenantId
 // deployments where a caller could otherwise probe arbitrary ids.
 export type TenantExists = (tenantId: TenantId) => Promise<boolean> | boolean;
 
+// App-facing anonymous-access config (#1374). tenantResolver / tenantExists
+// / resolverTrust come from auth-foundation providers (EXT_TENANT_RESOLVER /
+// EXT_TENANT_EXISTENCE), resolved at boot into AnonymousAccessResolved.
+//
+// Single-tenant shortcut: when defaultTenantId is set, the server runs in
+// **locked** mode (client must agree or get tenant_mismatch).
 export type AnonymousAccessConfig = {
-  // Custom resolver (e.g. subdomain parser). Consulted only when neither
-  // the X-Tenant header nor the kumiko_tenant cookie are present.
-  readonly tenantResolver?: TenantResolver;
-  // Single-tenant shortcut. When set, the server runs in **locked** mode:
-  //   - no client-supplied tenant: defaultTenantId is used.
-  //   - client supplies a matching tenant (header/cookie/resolver): allowed.
-  //   - client supplies a non-matching tenant: 400 tenant_mismatch (the
-  //     server is single-tenant; rejecting protects against confused clients
-  //     who think they're talking to a different deployment).
-  // The framework does NOT verify defaultTenantId against the DB at boot;
-  // the caller is responsible (see sample for the pattern).
   readonly defaultTenantId?: TenantId;
-  // Per-request existence check for header/cookie/resolver-supplied ids.
-  // Skipped for the defaultTenantId path (the caller already vetted that
-  // value when configuring the server).
+};
+
+// Runtime config consumed by authMiddleware after boot merges registry
+// providers onto the app-facing AnonymousAccessConfig.
+export type AnonymousAccessResolved = AnonymousAccessConfig & {
+  readonly tenantResolver?: TenantResolver;
   readonly tenantExists?: TenantExists;
+  readonly resolverTrust?: "authoritative" | "fallback-only";
 };
 
 // Where the candidate tenant came from. Drives the validation policy:
@@ -109,14 +132,15 @@ type MiddlewareRejectCode =
   | "tenant_required"
   | "tenant_not_found"
   | "tenant_mismatch"
-  | "invalid_tenant_format";
+  | "invalid_tenant_format"
+  | "tenant_unavailable";
 
 // @wrapper-known error-helper
 function middlewareReject(
   c: Context,
   opts: {
     code: MiddlewareRejectCode;
-    status: 400 | 401 | 403 | 404;
+    status: 400 | 401 | 403 | 404 | 410;
     message: string;
     i18nKey: string;
     details?: Record<string, unknown>;
@@ -169,7 +193,18 @@ function extractToken(
 }
 
 export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions = {}) {
-  const { sessionChecker, strictMode = false, anonymousAccess } = options;
+  const { sessionChecker, anonymousAccess, tokenVerifier, resolveTenantLifecycleStatus } = options;
+
+  // Fail loud at boot, not silently at request time: a tenantResolver
+  // without a declared resolverTrust is an ambiguous trust decision no
+  // sane default can make on the app's behalf (see AnonymousAccessConfig).
+  if (anonymousAccess?.tenantResolver && anonymousAccess.resolverTrust === undefined) {
+    throw new Error(
+      "authMiddleware: anonymousAccess.tenantResolver is set without resolverTrust — " +
+        'declare "authoritative" (resolver wins over client header/cookie) or ' +
+        '"fallback-only" (client wins, resolver is a last resort).',
+    );
+  }
 
   return async (c: Context, next: Next) => {
     const extracted = extractToken(c);
@@ -201,7 +236,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
             i18nKey: "auth.errors.missingToken",
           });
         }
-        return await handleAnonymous(c, anonymousAccess, next);
+        return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
       }
       return middlewareReject(c, {
         code: "missing_token",
@@ -212,6 +247,19 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     }
     const { token, transport } = extracted;
 
+    // Generic bearer-verifier path: try the wired tokenVerifier (PAT, future
+    // JWT-provider, ...) BEFORE jwt.verify. A hit short-circuits the JWT path
+    // entirely; a miss (null — no provider's shape matched, or the matching
+    // provider rejected the token) falls through to the normal JWT flow below,
+    // which rejects it uniformly as invalid_token. Cookie transport is never
+    // routed here (the browser holds the JWT).
+    if (tokenVerifier && transport === "bearer") {
+      const verifiedUser = await tokenVerifier(token);
+      if (verifiedUser) {
+        return await handleVerifiedBearerUser(c, verifiedUser, next, resolveTenantLifecycleStatus);
+      }
+    }
+
     let payload: Awaited<ReturnType<JwtHelper["verify"]>>;
     try {
       payload = await jwt.verify(token);
@@ -225,15 +273,16 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     }
 
     // Session liveness check — only when both a checker is wired AND the
-    // token carries a sid. strictMode governs the no-sid case below so that
-    // both old JWTs (no sid) and rolling-deploy gaps can be handled.
+    // token carries a sid.
+    // A checker wired without a sid on the token means the token predates
+    // session tracking (or the JWT was forged) — reject.
     if (sessionChecker) {
       if (payload.jti) {
         const status = await sessionChecker(payload.jti, payload.sub);
         if (status !== "live") {
           return sessionInvalid(c, status);
         }
-      } else if (strictMode) {
+      } else {
         return sessionInvalid(c, "no_sid");
       }
     }
@@ -261,6 +310,12 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
       ...(payload.claims ? { claims: payload.claims } : {}),
       ...(payload.jti ? { sid: payload.jti } : {}),
     };
+    const lifecycleReject = await rejectIfTenantTeardown(
+      c,
+      payload.tenantId,
+      resolveTenantLifecycleStatus,
+    );
+    if (lifecycleReject) return lifecycleReject;
     c.set(USER_KEY, user);
     c.set(AUTH_TRANSPORT_KEY, transport);
     await next();
@@ -277,6 +332,42 @@ export function getAuthTransport(c: Context): AuthTransport | undefined {
   return c.get(AUTH_TRANSPORT_KEY) as AuthTransport | undefined;
 }
 
+// Verified-bearer request flow. `user` was already resolved by the wired
+// tokenVerifier (PAT today, future JWT-provider). Apply the same
+// X-Tenant-mismatch guard as the JWT path before continuing. Structured like
+// handleAnonymous so authMiddleware stays flat.
+async function handleVerifiedBearerUser(
+  c: Context,
+  user: SessionUser,
+  next: Next,
+  resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver,
+): Promise<Response | undefined> {
+  // The token carries its own tenant; an X-Tenant header pointing elsewhere is
+  // a confused client — reject loudly, same stance as the JWT path.
+  const headerTenant = c.req.header(TENANT_HEADER_NAME);
+  if (headerTenant !== undefined && headerTenant !== user.tenantId) {
+    return middlewareReject(c, {
+      code: "tenant_mismatch",
+      status: 400,
+      message: "token tenantId and X-Tenant header disagree",
+      i18nKey: "auth.errors.tenantMismatch",
+      details: { tokenTenantId: user.tenantId, headerTenantId: headerTenant },
+    });
+  }
+  c.set(USER_KEY, user);
+  c.set(AUTH_TRANSPORT_KEY, "bearer");
+  const lifecycleReject = await rejectIfTenantTeardown(
+    c,
+    user.tenantId,
+    resolveTenantLifecycleStatus,
+  );
+  if (lifecycleReject) return lifecycleReject;
+  await next();
+  // skip: verified-bearer path completed — next() ran; explicit return keeps
+  // the Response|undefined union honest (same as handleAnonymous).
+  return;
+}
+
 // Anonymous request flow. Steps:
 //   1. Read raw client-supplied tenant from X-Tenant header / cookie.
 //   2. Validate format (UUID-shape) — junk strings get 400 right here.
@@ -291,8 +382,9 @@ export function getAuthTransport(c: Context): AuthTransport | undefined {
 //      no CSRF vector to defend against).
 async function handleAnonymous(
   c: Context,
-  config: AnonymousAccessConfig,
+  config: AnonymousAccessResolved,
   next: Next,
+  resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver,
 ): Promise<Response | undefined> {
   // Step 1+2: parse client-supplied tenant. Reject malformed values before
   // they touch any downstream consumer (DB, cache, audit row).
@@ -330,6 +422,12 @@ async function handleAnonymous(
   }
 
   // Step 5: synthesise + continue.
+  const lifecycleReject = await rejectIfTenantTeardown(
+    c,
+    resolved.tenantId,
+    resolveTenantLifecycleStatus,
+  );
+  if (lifecycleReject) return lifecycleReject;
   c.set(USER_KEY, createAnonymousUser(resolved.tenantId));
   await next();
   // skip: anonymous path completed — Hono middleware contract returns void
@@ -370,38 +468,93 @@ type ResolveError = { error: RejectArgs };
 // clients that think they're talking to a different installation.
 async function resolveTenant(
   c: Context,
-  config: AnonymousAccessConfig,
+  config: AnonymousAccessResolved,
   clientTenant: { id: TenantId; source: "header" | "cookie" } | null,
 ): Promise<ResolvedTenant | ResolveError> {
   if (config.defaultTenantId !== undefined) {
-    if (clientTenant && clientTenant.id !== config.defaultTenantId) {
+    return resolveAgainstDefault(config.defaultTenantId, clientTenant);
+  }
+  if (config.tenantResolver && config.resolverTrust === "authoritative") {
+    return await resolveWithAuthoritativeResolver(c, config.tenantResolver, clientTenant);
+  }
+  return await resolveWithClientPrecedence(c, config.tenantResolver, clientTenant);
+}
+
+// Locked single-tenant mode: the client either agrees with the default or
+// gets tenant_mismatch — defending the deployment from confused clients
+// that think they're talking to a different installation.
+function resolveAgainstDefault(
+  defaultTenantId: TenantId,
+  clientTenant: { id: TenantId; source: "header" | "cookie" } | null,
+): ResolvedTenant | ResolveError {
+  if (clientTenant && clientTenant.id !== defaultTenantId) {
+    return {
+      error: {
+        code: "tenant_mismatch",
+        status: 400,
+        message: `${clientTenant.source} tenant disagrees with server default`,
+        i18nKey: "auth.errors.tenantMismatch",
+        details: { clientTenantId: clientTenant.id, defaultTenantId },
+      },
+    };
+  }
+  return { tenantId: defaultTenantId, source: "default" };
+}
+
+// resolverTrust: "authoritative" — the resolver is trusted over the client.
+// A client-supplied tenant that disagrees is rejected, never used to
+// override the resolver's answer. Falls back to the client tenant only
+// when the resolver itself has no opinion (unrecognised host).
+async function resolveWithAuthoritativeResolver(
+  c: Context,
+  tenantResolver: TenantResolver,
+  clientTenant: { id: TenantId; source: "header" | "cookie" } | null,
+): Promise<ResolvedTenant | ResolveError> {
+  const resolved = await tenantResolver(c);
+  if (resolved !== null && resolved !== undefined) {
+    if (clientTenant && clientTenant.id !== resolved) {
       return {
         error: {
           code: "tenant_mismatch",
           status: 400,
-          message: `${clientTenant.source} tenant disagrees with server default`,
+          message: `${clientTenant.source} tenant disagrees with resolved tenant`,
           i18nKey: "auth.errors.tenantMismatch",
-          details: {
-            clientTenantId: clientTenant.id,
-            defaultTenantId: config.defaultTenantId,
-          },
+          details: { clientTenantId: clientTenant.id, resolvedTenantId: resolved },
         },
       };
     }
-    return { tenantId: config.defaultTenantId, source: "default" };
+    return { tenantId: resolved, source: "resolver" };
   }
+  // Resolver had no opinion (unrecognised host) — do NOT fall back to the
+  // client-supplied tenant here. That would let an unrecognised-host
+  // request pick its own tenant via X-Tenant, the exact override this mode
+  // exists to prevent; it's just reached through "unknown host" instead of
+  // "known host, disagreeing header". Authoritative means the resolver's
+  // silence is final, not a delegation back to the client.
+  return tenantRequiredError();
+}
 
+// resolverTrust: "fallback-only" (or no resolver at all) — client tenant
+// wins outright; the resolver only runs as a last resort when neither
+// header nor cookie supplied a value.
+async function resolveWithClientPrecedence(
+  c: Context,
+  tenantResolver: TenantResolver | undefined,
+  clientTenant: { id: TenantId; source: "header" | "cookie" } | null,
+): Promise<ResolvedTenant | ResolveError> {
   if (clientTenant) {
     return { tenantId: clientTenant.id, source: clientTenant.source };
   }
-
-  if (config.tenantResolver) {
-    const resolved = await config.tenantResolver(c);
+  if (tenantResolver) {
+    const resolved = await tenantResolver(c);
     if (resolved !== null && resolved !== undefined) {
       return { tenantId: resolved, source: "resolver" };
     }
   }
+  return tenantRequiredError();
+}
 
+function tenantRequiredError(): ResolveError {
   return {
     error: {
       code: "tenant_required",
@@ -415,8 +568,63 @@ async function resolveTenant(
 
 type RejectArgs = {
   code: MiddlewareRejectCode;
-  status: 400 | 401 | 403 | 404;
+  status: 400 | 401 | 403 | 404 | 410;
   message: string;
   i18nKey: string;
   details?: Record<string, unknown>;
 };
+
+const TENANT_LIFECYCLE_BLOCKED = new Set([
+  "destroyRequested",
+  "destroying",
+  "destroyFailed",
+  "destroyed",
+]);
+const TENANT_LIFECYCLE_CANCEL_QN = "tenant-lifecycle:write:cancel-destruction";
+
+async function requestsCancelDestruction(c: Context): Promise<boolean> {
+  if (c.req.method !== "POST") return false;
+  try {
+    const path = c.req.path;
+    const body = (await c.req.raw.clone().json()) as {
+      type?: string;
+      commands?: Array<{ type?: string }>;
+    };
+    if (path === "/api/write") {
+      return body.type === TENANT_LIFECYCLE_CANCEL_QN;
+    }
+    if (path === "/api/batch") {
+      // every(), not some(): a batch mixing the cancel command with other
+      // writes must NOT wave the whole batch through the teardown gate —
+      // only a batch consisting solely of cancel-destruction is exempt.
+      return (
+        Array.isArray(body.commands) &&
+        body.commands.length > 0 &&
+        body.commands.every((command) => command.type === TENANT_LIFECYCLE_CANCEL_QN)
+      );
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+async function rejectIfTenantTeardown(
+  c: Context,
+  tenantId: TenantId,
+  resolveTenantLifecycleStatus: TenantLifecycleStatusResolver | undefined,
+): Promise<Response | undefined> {
+  if (!resolveTenantLifecycleStatus) return undefined;
+  const lifecycle = await resolveTenantLifecycleStatus(tenantId);
+  if (!lifecycle || !TENANT_LIFECYCLE_BLOCKED.has(lifecycle.status)) return undefined;
+  if (lifecycle.status === "destroyRequested" && (await requestsCancelDestruction(c))) {
+    return undefined;
+  }
+  return middlewareReject(c, {
+    code: "tenant_unavailable",
+    status: 410,
+    message: `tenant "${tenantId}" is unavailable (${lifecycle.status})`,
+    i18nKey: "auth.errors.tenantUnavailable",
+    details: { tenantId, status: lifecycle.status },
+  });
+}