@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/auth-foundation/feature.ts

@@ -0,0 +1,157 @@
+// kumiko-feature-version: 1
+//
+// auth-foundation — declares auth-middleware extension points:
+//   - tokenVerifier (multi, shape-routed)
+//   - sessionStore (single, required when foundation mounts)
+//   - tenantResolver (single, optional)
+//   - tenantExistence (single, optional)
+//
+// Provider-features register via `r.useExtension(EXT_*, "<name>", plugin)`.
+// Middleware / runProdApp resolve providers from the registry at boot
+// (tokenVerifier/sessionStore) or request-time (tokenVerifier shape match).
+
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  validateSessionStoreMultiplicity,
+  validateTenantExistenceMultiplicity,
+  validateTenantResolverMultiplicity,
+  validateTokenVerifierMultiplicity,
+} from "./boot-checks";
+import {
+  type AuthProviderBuildDeps,
+  EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  EXT_TOKEN_VERIFIER,
+  isAuthProviderPlugin,
+  isSessionStoreProvider,
+  isTenantExistenceProvider,
+  isTenantResolverProvider,
+  type SessionStore,
+  type TenantExistsFn,
+  type TenantResolverFn,
+  type TenantResolverTrust,
+  tokenShapeMatches,
+} from "./types";
+
+export {
+  EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  EXT_TOKEN_VERIFIER,
+} from "./types";
+
+const FEATURE_NAME = "auth-foundation";
+
+export const authFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    "Declares auth-middleware extension points: `tokenVerifier` (Bearer), `sessionStore` (revocable JWT sid), optional `tenantResolver` + `tenantExistence` for anonymous multi-tenant. Provider-features register via r.useExtension; mount auth-foundation with the matching provider features.",
+  );
+  r.uiHints({
+    displayLabel: "Auth Provider Foundation",
+    category: "identity",
+    recommended: false,
+  });
+
+  r.extendsRegistrar(EXT_TOKEN_VERIFIER, {
+    onRegister: () => {
+      // No side-effects at register-time — registry stores the usage,
+      // resolveTokenVerifier looks it up at request-time.
+    },
+  });
+  r.bootCheck(({ features }) => validateTokenVerifierMultiplicity(features));
+
+  r.extendsRegistrar(EXT_SESSION_STORE, {
+    onRegister: () => {
+      // No side-effects at register-time — resolveSessionStore at boot/request.
+    },
+  });
+  r.bootCheck(({ features }) => validateSessionStoreMultiplicity(features));
+
+  r.extendsRegistrar(EXT_TENANT_RESOLVER, {
+    onRegister: () => {
+      // Optional — zero providers is fine (single-tenant / header-cookie).
+    },
+  });
+  r.bootCheck(({ features }) => validateTenantResolverMultiplicity(features));
+
+  r.extendsRegistrar(EXT_TENANT_EXISTENCE, {
+    onRegister: () => {
+      // Optional — zero providers skips the existence check.
+    },
+  });
+  r.bootCheck(({ features }) => validateTenantExistenceMultiplicity(features));
+});
+
+/**
+ * Tries every registered tokenVerifier provider's shape against `rawToken`
+ * in registration order and calls the first match's verifier. Returns null
+ * when no provider's shape matches, or when the matching provider's
+ * verifier rejects the token.
+ */
+export async function resolveTokenVerifier(
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+  rawToken: string,
+): Promise<SessionUser | null> {
+  const usages = deps.registry.getExtensionUsages(EXT_TOKEN_VERIFIER);
+  for (const usage of usages) {
+    if (!isAuthProviderPlugin(usage.options)) continue;
+    if (!tokenShapeMatches(usage.options.shape, rawToken)) continue;
+    const verify = await usage.options.build(deps);
+    return verify(rawToken);
+  }
+  return null;
+}
+
+/**
+ * Resolves the single registered sessionStore provider. Assumes
+ * validateSessionStoreMultiplicity already ran at boot — a missing provider
+ * here means the app booted without going through the framework's boot
+ * validator, not a runtime state resolveSessionStore should model.
+ */
+export async function resolveSessionStore(
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+): Promise<SessionStore> {
+  const usage = deps.registry.getExtensionUsages(EXT_SESSION_STORE)[0];
+  if (!usage || !isSessionStoreProvider(usage.options)) {
+    throw new Error(
+      "[auth-foundation] no sessionStore provider registered — did the boot validator run?",
+    );
+  }
+  return usage.options.build(deps);
+}
+
+export type ResolvedTenantResolver = {
+  readonly resolve: TenantResolverFn;
+  readonly trust: TenantResolverTrust;
+};
+
+/** Optional tenantResolver — null when no provider registered. */
+export async function resolveTenantResolver(
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+): Promise<ResolvedTenantResolver | null> {
+  const usage = deps.registry.getExtensionUsages(EXT_TENANT_RESOLVER)[0];
+  if (!usage) return null;
+  if (!isTenantResolverProvider(usage.options)) {
+    throw new Error(
+      "[auth-foundation] tenantResolver provider registered without a valid TenantResolverProvider",
+    );
+  }
+  const resolve = await usage.options.build(deps);
+  return { resolve, trust: usage.options.trust };
+}
+
+/** Optional tenantExistence — null when no provider registered. */
+export async function resolveTenantExistence(
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+): Promise<TenantExistsFn | null> {
+  const usage = deps.registry.getExtensionUsages(EXT_TENANT_EXISTENCE)[0];
+  if (!usage) return null;
+  if (!isTenantExistenceProvider(usage.options)) {
+    throw new Error(
+      "[auth-foundation] tenantExistence provider registered without a valid TenantExistenceProvider",
+    );
+  }
+  return usage.options.build(deps);
+}

package/src/auth-foundation/index.ts

@@ -0,0 +1,37 @@
+// Public API of the auth-foundation bundled-feature.
+
+export {
+  authFoundationFeature,
+  type ResolvedTenantResolver,
+  resolveSessionStore,
+  resolveTenantExistence,
+  resolveTenantResolver,
+  resolveTokenVerifier,
+} from "./feature";
+export { resolveAnonymousAccessFromRegistry } from "./resolve-anonymous-access";
+export {
+  type AuthProviderBuildDeps,
+  type AuthProviderPlugin,
+  type AuthVerifier,
+  EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  EXT_TOKEN_VERIFIER,
+  isAuthProviderPlugin,
+  isSessionStoreProvider,
+  isTenantExistenceProvider,
+  isTenantResolverProvider,
+  isTenantResolverTrust,
+  isValidTokenShape,
+  type SessionMassRevoker,
+  type SessionStore,
+  type SessionStoreProvider,
+  type TenantExistenceProvider,
+  type TenantExistsFn,
+  type TenantResolverFn,
+  type TenantResolverProvider,
+  type TenantResolverTrust,
+  type TokenShape,
+  tokenShapeKey,
+  tokenShapeMatches,
+} from "./types";

package/src/auth-foundation/resolve-anonymous-access.ts

@@ -0,0 +1,62 @@
+/**
+ * Merge app-facing AnonymousAccessConfig with auth-foundation tenant providers.
+ * Providers win over any leftover callback fields (hard cutover #1374).
+ * Test stacks may still pass Resolved callbacks when no provider is mounted.
+ */
+import type {
+  AnonymousAccessConfig,
+  AnonymousAccessResolved,
+} from "@cosmicdrift/kumiko-framework/api";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { resolveTenantExistence, resolveTenantResolver } from "./feature";
+import type { AuthProviderBuildDeps } from "./types";
+
+export async function resolveAnonymousAccessFromRegistry(
+  base: AnonymousAccessResolved | AnonymousAccessConfig | undefined,
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+): Promise<AnonymousAccessResolved | undefined> {
+  const [tenantResolver, tenantExists] = await Promise.all([
+    resolveTenantResolver(deps),
+    resolveTenantExistence(deps),
+  ]);
+
+  // Anonymous access is app opt-in only: a mounted routing provider
+  // (EXT_TENANT_RESOLVER/EXT_TENANT_EXISTENCE) alone must never make
+  // anonymousAccess become defined for an app that never set it — that
+  // would upgrade every roles:["anonymous"] handler to reachable without
+  // a JWT the moment such a routing feature is mounted (#1452).
+  if (!base) return undefined;
+
+  // Fail-closed (#1374 security): inline tenantResolver without trust is the
+  // old ambiguous config — providers always carry trust; test stacks must too.
+  if (
+    !tenantResolver &&
+    base &&
+    "tenantResolver" in base &&
+    base.tenantResolver !== undefined &&
+    base.resolverTrust === undefined
+  ) {
+    throw new Error(
+      "[auth-foundation] anonymousAccess.tenantResolver is set without resolverTrust — " +
+        'declare "authoritative" or "fallback-only" (or mount an EXT_TENANT_RESOLVER provider).',
+    );
+  }
+
+  // Providers win (#1374). When none are mounted, keep any test-injected
+  // Resolved callbacks so framework middleware suites stay self-contained.
+  return {
+    ...(base ?? {}),
+    ...(tenantResolver
+      ? {
+          // No cast: TenantResolverFn's `(c: unknown) => string | null`
+          // and the framework's TenantResolver `(c: Context) => TenantId
+          // | null` are structurally identical (TenantId is a plain
+          // string alias, no brand) — `unknown` is a supertype of
+          // Context, so this is already sound by parameter contravariance.
+          tenantResolver: tenantResolver.resolve,
+          resolverTrust: tenantResolver.trust,
+        }
+      : {}),
+    ...(tenantExists ? { tenantExists } : {}),
+  };
+}

package/src/auth-foundation/types.ts

@@ -0,0 +1,170 @@
+// kumiko-feature-version: 1
+//
+// Type contracts for auth-foundation's `tokenVerifier` extension point.
+// Provider-features (future: auth-provider-jwt, auth-provider-pat) register
+// an AuthProviderPlugin via `r.useExtension(EXT_TOKEN_VERIFIER, "<name>", plugin)`.
+//
+// **Shape-match routing:** unlike file-foundation/mail-foundation (one active
+// provider per tenant, chosen via a config-key), token verification happens
+// BEFORE the tenant is known — there's nothing to select on. Every registered
+// provider declares a static `shape` (how to recognize its own tokens by
+// looking at the raw bearer value); `resolveTokenVerifier` tries each
+// provider's shape in turn and calls the first match's verifier.
+
+import type {
+  SessionChecker,
+  SessionCreator,
+  SessionMassRevoker,
+  SessionRevoker,
+} from "@cosmicdrift/kumiko-framework/api";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+
+export type { SessionMassRevoker };
+
+export const EXT_TOKEN_VERIFIER = "tokenVerifier";
+
+/**
+ * Deps available to a provider's `build()`. DB access only — a hot-path
+ * resolver (see personal-access-tokens/resolver.ts) needs a raw-DB handle
+ * for a point-read + live-role-resolution, not a per-request ctx (there is
+ * no tenant/session yet at verify-time).
+ */
+export type AuthProviderBuildDeps = {
+  readonly db: DbConnection;
+};
+
+/** How to recognize this provider's tokens by looking at the raw bearer value. */
+export type TokenShape =
+  | { readonly kind: "jwt" }
+  | { readonly kind: "prefix"; readonly prefix: string };
+
+export type AuthVerifier = (rawToken: string) => Promise<SessionUser | null>;
+
+export type AuthProviderPlugin = {
+  readonly shape: TokenShape;
+  readonly build: (deps: AuthProviderBuildDeps) => Promise<AuthVerifier> | AuthVerifier;
+};
+
+export function isValidTokenShape(shape: unknown): shape is TokenShape {
+  if (typeof shape !== "object" || shape === null || !("kind" in shape)) return false;
+  const kind = (shape as { kind: unknown }).kind;
+  if (kind === "jwt") return true;
+  if (kind === "prefix") {
+    const prefix = "prefix" in shape ? (shape as { prefix: unknown }).prefix : undefined;
+    return typeof prefix === "string" && prefix.length > 0;
+  }
+  return false;
+}
+
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind. Mirrors file-foundation's isFileProviderPlugin.
+export function isAuthProviderPlugin(o: unknown): o is AuthProviderPlugin {
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    "build" in o &&
+    typeof (o as { build: unknown }).build === "function" &&
+    "shape" in o &&
+    isValidTokenShape((o as { shape: unknown }).shape)
+  );
+}
+
+export function tokenShapeMatches(shape: TokenShape, rawToken: string): boolean {
+  if (shape.kind === "prefix") return rawToken.startsWith(shape.prefix);
+  return rawToken.split(".").length === 3;
+}
+
+/** Static discriminator used by the multiplicity boot-check to detect two providers claiming the same shape. */
+export function tokenShapeKey(shape: TokenShape): string {
+  return shape.kind === "jwt" ? "jwt" : `prefix:${shape.prefix}`;
+}
+
+// Session-store extension point (#1370). Unlike EXT_TOKEN_VERIFIER, this is
+// single-provider — sessions have no per-provider shape to route on, so
+// exactly one implementation must be registered (boot-fails on 0 or ≥2).
+
+export const EXT_SESSION_STORE = "sessionStore";
+
+/** Keep current sid (if any); revoke every other live session. Used by auth-mfa. */
+export type SessionRevokeAllOthers = (
+  userId: string,
+  currentSid: string | undefined,
+) => Promise<number>;
+
+export type SessionStore = {
+  readonly creator: SessionCreator;
+  readonly revoker: SessionRevoker;
+  readonly checker: SessionChecker;
+  readonly massRevoker: SessionMassRevoker;
+  readonly revokeAllOthers: SessionRevokeAllOthers;
+};
+
+export type SessionStoreProvider = {
+  readonly build: (deps: AuthProviderBuildDeps) => Promise<SessionStore> | SessionStore;
+};
+
+export function isSessionStoreProvider(o: unknown): o is SessionStoreProvider {
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    "build" in o &&
+    typeof (o as { build: unknown }).build === "function"
+  );
+}
+
+// Tenant-resolution extension points (#1373). Both are single-provider and
+// optional — zero registered means today's single-tenant / header-cookie
+// path (no subdomain resolver, no existence check). ≥2 fails boot.
+
+export const EXT_TENANT_RESOLVER = "tenantResolver";
+export const EXT_TENANT_EXISTENCE = "tenantExistence";
+
+/** Trust mode for a registered tenantResolver — mirrors AnonymousAccessConfig.resolverTrust. */
+export type TenantResolverTrust = "authoritative" | "fallback-only";
+
+/**
+ * Resolves the tenant for an unauthenticated request. Return null when no
+ * tenant can be determined — middleware rejects with 400. Throw only on
+ * infrastructure failures.
+ */
+export type TenantResolverFn = (
+  // Hono Context — typed loosely so auth-foundation stays free of a hono dep.
+  // Callers cast at the boundary (same shape as framework TenantResolver).
+  c: unknown,
+) => Promise<string | null> | string | null;
+
+export type TenantExistsFn = (tenantId: string) => Promise<boolean> | boolean;
+
+export type TenantResolverProvider = {
+  readonly trust: TenantResolverTrust;
+  readonly build: (deps: AuthProviderBuildDeps) => Promise<TenantResolverFn> | TenantResolverFn;
+};
+
+export type TenantExistenceProvider = {
+  readonly build: (deps: AuthProviderBuildDeps) => Promise<TenantExistsFn> | TenantExistsFn;
+};
+
+export function isTenantResolverTrust(v: unknown): v is TenantResolverTrust {
+  return v === "authoritative" || v === "fallback-only";
+}
+
+export function isTenantResolverProvider(o: unknown): o is TenantResolverProvider {
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    "build" in o &&
+    typeof (o as { build: unknown }).build === "function" &&
+    "trust" in o &&
+    isTenantResolverTrust((o as { trust: unknown }).trust)
+  );
+}
+
+export function isTenantExistenceProvider(o: unknown): o is TenantExistenceProvider {
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    "build" in o &&
+    typeof (o as { build: unknown }).build === "function"
+  );
+}

package/src/auth-mfa/__tests__/base32.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { base32Decode, base32Encode } from "../base32";
+
+describe("base32 encode/decode", () => {
+  test("round-trips arbitrary bytes", () => {
+    const bytes = Buffer.from("12345678901234567890", "ascii");
+    expect(base32Decode(base32Encode(bytes))).toEqual(bytes);
+  });
+
+  test("decodes lowercase and RFC 4648 '=' padding", () => {
+    const bytes = Buffer.from("12345678901234567890", "ascii");
+    const encoded = base32Encode(bytes);
+    const paddingLength = (8 - (encoded.length % 8)) % 8;
+    const withPadding = encoded + "=".repeat(paddingLength);
+    expect(base32Decode(withPadding.toLowerCase())).toEqual(bytes);
+  });
+
+  test("rejects a non-canonical length with non-zero residual bits", () => {
+    // "AA" decodes to 10 residual bits of all-zero value — canonical (padding
+    // zeros). A single stray char (5 bits, below the byte boundary but not a
+    // clean multiple) with non-zero value must be rejected, not truncated.
+    expect(() => base32Decode("B")).toThrow(/invalid length/);
+  });
+
+  test("throws on a genuinely invalid character", () => {
+    expect(() => base32Decode("01")).toThrow(/invalid character/);
+  });
+});