@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/personal-access-tokens/resolver.ts

@@ -0,0 +1,53 @@
+import type { TokenVerifier } from "@cosmicdrift/kumiko-framework/api";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { isExpiredAt } from "./expiry.js";
+import { hashPatToken } from "./hash.js";
+import { resolvePatRoles } from "./roles.js";
+import { apiTokenTable } from "./schema/api-token.js";
+import { expandScopes, type PatScopeConfig } from "./scopes.js";
+
+// Hot-path resolver — raw-DB like session-callbacks (a dispatcher roundtrip on
+// every request buys nothing here). Hash the bearer token, point-read the row,
+// reject revoked/expired, resolve LIVE roles, expand granted scopes into
+// allowedQns. Any failure returns null so the middleware answers a uniform 401
+// with no oracle about which check failed.
+export function createPatResolver(opts: {
+  readonly db: DbConnection;
+  readonly scopes: PatScopeConfig;
+}): TokenVerifier {
+  const { db, scopes } = opts;
+  return async (rawToken: string): Promise<SessionUser | null> => {
+    const row = await fetchOne<{
+      id: string;
+      userId: string;
+      tenantId: string;
+      scopes: string;
+      revokedAt: unknown;
+      expiresAt: { epochMilliseconds: number } | null;
+    }>(db, apiTokenTable, { tokenHash: hashPatToken(rawToken) });
+    if (!row) return null;
+    if (row.revokedAt !== null) return null;
+    if (isExpiredAt(row.expiresAt)) return null;
+    const roles = await resolvePatRoles(db, row.userId, row.tenantId);
+    if (!roles) return null;
+    const granted = parseScopeNames(row.scopes);
+    return {
+      id: row.userId,
+      // @cast-boundary db-row → branded id: stored from a valid SessionUser.tenantId at create
+      tenantId: row.tenantId as TenantId,
+      roles,
+      pat: { tokenId: row.id, scopes: granted, allowedQns: expandScopes(scopes, granted) },
+    };
+  };
+}
+
+function parseScopeNames(raw: string): string[] {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === "string") : [];
+  } catch {
+    return [];
+  }
+}

package/packages/bundled-features/src/personal-access-tokens/revoke-for-user.ts

@@ -0,0 +1,62 @@
+import { transaction, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { append } from "@cosmicdrift/kumiko-framework/event-store";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "temporal-polyfill";
+import {
+  PAT_REVOKED_AGGREGATE_TYPE,
+  PAT_REVOKED_EVENT_QN,
+  patRevokedSchema,
+} from "./pat-revoked-event.js";
+import { apiTokenTable } from "./schema/api-token.js";
+
+// A pool has begin(); a tx/savepoint handle does not and is already atomic.
+function canBeginTransaction(db: DbRunner): boolean {
+  return typeof (db as { begin?: unknown }).begin === "function"; // @cast-boundary driver-handle-probe
+}
+
+// Cross-tenant revoke: password-change and MFA-enable/disable are account-
+// level security events, not scoped to one tenant. Mirrors sessions'
+// sessionMassRevoker (session-callbacks.ts) which passes the boot-time
+// DbConnection directly — not ctx.db, which would be tenant-scoped in a hook.
+export async function revokeAllPatTokensForUser(db: DbRunner, userId: string): Promise<number> {
+  // Update and event commit together: otherwise a failed append leaves the
+  // tokens revoked with no event, and a retry matches no live row.
+  return canBeginTransaction(db)
+    ? transaction(db, (tx) => revokeAndAppend(tx, userId))
+    : revokeAndAppend(db, userId);
+}
+
+async function revokeAndAppend(db: DbRunner, userId: string): Promise<number> {
+  const updated = await updateMany<{ id: string }>(
+    db,
+    apiTokenTable,
+    { revokedAt: Temporal.Now.instant() },
+    { userId, revokedAt: null },
+  );
+
+  // Same reasoning as sessionMassRevoker's append — this raw
+  // callback has no dispatcher ctx to call unsafeAppendEvent from, so it
+  // uses the low-level append() directly, anchored on SYSTEM_TENANT_ID like
+  // sessions' cross-tenant writes. Without it, the access-invalidation
+  // consumer never hears about a password-change/MFA-toggle/forget-subject
+  // PAT revoke and any already-open SSE stream on those tokens survives it.
+  if (updated.length > 0) {
+    const payload = patRevokedSchema.parse({
+      userId,
+      tokenIds: updated.map((row) => row.id),
+    });
+    await append(db, {
+      aggregateId: generateId(),
+      aggregateType: PAT_REVOKED_AGGREGATE_TYPE,
+      tenantId: SYSTEM_TENANT_ID,
+      expectedVersion: 0,
+      type: PAT_REVOKED_EVENT_QN,
+      payload,
+      metadata: { userId },
+    });
+  }
+
+  return updated.length;
+}

package/packages/bundled-features/src/personal-access-tokens/roles.ts

@@ -0,0 +1,37 @@
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { buildSessionRoles } from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+// kumiko-lint-ignore cross-feature-import shared lifecycle-status gate with session auth
+import { isPrincipalBlocked } from "../sessions/index.js";
+import { tenantMembershipsTable } from "../tenant/index.js";
+import { type UserStatus, userTable } from "../user/index.js";
+
+// Live role resolution for a (userId, tenantId), mirroring login.write.ts:
+// global roles (users.roles) ∪ tenant-membership roles (forbidden roles
+// stripped via stripForbiddenMembershipRoles, see engine/membership-roles).
+// Resolved fresh on every PAT request — a snapshot baked at mint
+// time would keep a since-revoked admin role for the token's whole (months-long)
+// life. Returns null when the user has no membership in that tenant: removed
+// from the tenant → the PAT stops authenticating there. Also null when the
+// user's lifecycle status blocks them (fw security-welle2) — collapsed onto
+// the same "no roles" outcome as missing-membership so a blocked user's PAT
+// gets an identical 401 to an unknown token (no status oracle).
+export async function resolvePatRoles(
+  db: DbConnection,
+  userId: string,
+  tenantId: string,
+): Promise<readonly string[] | null> {
+  const memberships = await selectMany<{ roles: string }>(db, tenantMembershipsTable, {
+    userId,
+    tenantId,
+  });
+  const membership = memberships[0];
+  if (!membership) return null;
+  const userRow = await fetchOne<{ roles: string | null; status: UserStatus }>(db, userTable, {
+    id: userId,
+  });
+  if (userRow && isPrincipalBlocked(userRow.status)) return null;
+  const globalRoles = parseRoles(userRow?.roles ?? null);
+  return buildSessionRoles(globalRoles, parseRoles(membership.roles));
+}

package/packages/bundled-features/src/personal-access-tokens/schema/api-token.ts

@@ -0,0 +1,93 @@
+import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createEntity,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { API_TOKEN_ENTITY_NAME } from "../constants.js";
+
+// One row per Personal Access Token. Like store_user_sessions this is a
+// direct-write store (r.unmanagedTable): the create/revoke handlers write it and
+// the resolver point-reads it on the hot auth path. `tokenHash` is the SHA-256
+// of the plaintext (never the plaintext); the unique index on it makes the
+// resolver a single point-read. All columns are privileged-write so no user
+// request can forge ownership/scope/hash by poking a field directly — the
+// handlers mutate them via ctx.db inside the pipeline.
+export const apiTokenEntity = createEntity({
+  table: "store_api_tokens",
+  // No softDelete: revocation is its own lifecycle (revokedAt timestamp), and
+  // we keep revoked rows for the "your tokens" audit list.
+  softDelete: false,
+  fields: {
+    userId: createTextField({
+      required: true,
+      maxLength: 36,
+      access: { write: access.privileged },
+      personal: false,
+      reason: "pseudonymous_fk",
+    }),
+    tenantId: createTextField({
+      required: true,
+      maxLength: 36,
+      access: { write: access.privileged },
+      personal: false,
+      reason: "pseudonymous_fk",
+    }),
+    name: createTextField({
+      required: true,
+      maxLength: 120,
+      access: { write: access.privileged },
+      personal: { of: "userId" },
+      find: "none",
+    }),
+    // SHA-256 hash of the plaintext token — credential material, but kept
+    // Klasse 1 deliberately: resolver.ts point-reads this row with a raw
+    // exact-match `{ tokenHash: hashPatToken(rawToken) }` query on the hot
+    // auth path. A subject annotation here would make encryptForDirectWrite
+    // store ciphertext while the resolver keeps querying for the plaintext
+    // hash — every bearer-token request would 401 once a KMS is active.
+    // Fixing that needs a blind-index-backed lookup (like email's
+    // find:"exact" companion column), a resolver.ts rewrite, so this stays
+    // unencrypted until a blind-index lookup exists.
+    tokenHash: createTextField({
+      required: true,
+      maxLength: 64,
+      access: { write: access.privileged },
+      personal: false,
+      reason: "credential_hash_used_as_exact_lookup_key",
+    }),
+    // Short displayable prefix ("your tokens" list) — not the secret itself,
+    // but still identifies which of the user's tokens this row is. Kept
+    // Klasse 1: list.query.ts returns `r.prefix` straight through with no
+    // decrypt call (unlike `name`, which goes through decryptStoredPii) — a
+    // subject annotation would leak ciphertext to the UI once a KMS is
+    // active.
+    prefix: createTextField({
+      required: true,
+      maxLength: 16,
+      access: { write: access.privileged },
+      personal: false,
+      reason: "credential_prefix_read_without_decrypt",
+    }),
+    // JSON-encoded string[] of granted scope names — mirrors the roles-column
+    // convention (parseRoles-style text); the resolver JSON.parses it.
+    scopes: createTextField({
+      required: true,
+      access: { write: access.privileged },
+      personal: false,
+      reason: "technical_reference",
+    }),
+    createdAt: createTimestampField({ required: true, access: { write: access.privileged } }),
+    expiresAt: createTimestampField({ access: { write: access.privileged } }),
+    revokedAt: createTimestampField({ access: { write: access.privileged } }),
+  },
+  indexes: [{ unique: true, columns: ["tokenHash"], name: "store_api_tokens_hash_unique" }],
+});
+
+// deriveEntityTableMeta (not buildEntityTable): this is a direct-write store, so
+// the table must be a WritableTable (post ES-write-brand #742) — same as
+// sessions' userSessionTable. buildEntityTable is branded executor-only.
+export const apiTokenTable = deriveEntityTableMeta(API_TOKEN_ENTITY_NAME, apiTokenEntity, {
+  source: "unmanaged",
+});

package/packages/bundled-features/src/personal-access-tokens/scopes.ts

@@ -0,0 +1,43 @@
+// @runtime client
+// Pure scope helpers + types — client-marked so the web screen (web/) may import
+// parseGrant without pulling the feature's server runtime barrel.
+//
+// App-declared scopes — two axes, like GitHub fine-grained PATs: WHICH API
+// (the domain, keyed here) × the permission LEVEL (read vs read+write). Each
+// domain declares its read-QN globs and (optionally) its write-QN globs. A
+// domain may span features (e.g. a "miete" domain granting ledger + folders).
+export type PatScopeDef = {
+  readonly label: string;
+  readonly read: readonly string[];
+  // Omit for a read-only domain — the UI then offers only "no access" / "read".
+  readonly write?: readonly string[];
+};
+
+export type PatScopeConfig = Readonly<Record<string, PatScopeDef>>;
+
+export type PatLevel = "read" | "write";
+
+// A granted scope is the string "<domain>:<level>" (e.g. "credit:write"). The
+// domain key never contains a colon, so split on the LAST one.
+export function parseGrant(grant: string): { domain: string; level: string } | null {
+  const idx = grant.lastIndexOf(":");
+  if (idx <= 0) return null;
+  return { domain: grant.slice(0, idx), level: grant.slice(idx + 1) };
+}
+
+// Expand granted "<domain>:<level>" entries into the union of QN globs: read
+// always grants the read QNs; write additionally grants the write QNs. Unknown
+// domains contribute nothing (fail-closed — a scope dropped from config after a
+// token was minted silently loses that capability).
+export function expandScopes(config: PatScopeConfig, granted: readonly string[]): string[] {
+  const out = new Set<string>();
+  for (const grant of granted) {
+    const parsed = parseGrant(grant);
+    if (!parsed) continue;
+    const def = config[parsed.domain];
+    if (!def) continue;
+    for (const q of def.read) out.add(q);
+    if (parsed.level === "write") for (const q of def.write ?? []) out.add(q);
+  }
+  return [...out];
+}

package/packages/bundled-features/src/personal-access-tokens/screens.ts

@@ -0,0 +1,131 @@
+import {
+  i18nKey,
+  MAX_LIST_LIMIT,
+  type ProjectionListScreenDefinition,
+  type SecretMintScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { PAT_MINT_SCREEN_ID, PAT_SCREEN_ID, PatHandlers, PatQueries } from "./constants.js";
+import type { PatScopeConfig } from "./scopes.js";
+
+const PAT_STATUS_OPTION_KEY_PREFIX = "pat.list.status.";
+
+export const patListScreen: ProjectionListScreenDefinition = {
+  id: PAT_SCREEN_ID,
+  type: "projectionList",
+  query: PatQueries.mine,
+  // The `mine` handler honours `limit` only (no offset/total), so a pager would
+  // show page 1 forever: send one max-size request and render no pager.
+  pagination: false,
+  pageSize: MAX_LIST_LIMIT,
+  defaultSort: { field: "createdAt", dir: "desc" },
+  columns: [
+    { field: "name", label: i18nKey("pat.list.col.name") },
+    { field: "prefix", label: i18nKey("pat.list.col.prefix") },
+    { field: "scopes", label: i18nKey("pat.list.col.scopes") },
+    {
+      field: "status",
+      label: i18nKey("pat.list.col.status"),
+      renderer: { format: "enumOption", keyPrefix: PAT_STATUS_OPTION_KEY_PREFIX },
+    },
+    {
+      field: "createdAt",
+      label: i18nKey("pat.list.col.created"),
+      renderer: { format: "timestamp" },
+    },
+    {
+      field: "expiresAt",
+      label: i18nKey("pat.list.col.expires"),
+      renderer: { format: "timestamp" },
+    },
+  ],
+  rowActions: [
+    {
+      kind: "writeHandler",
+      id: "revoke",
+      label: i18nKey("pat.list.revoke"),
+      handler: PatHandlers.revoke,
+      style: "danger",
+      confirm: i18nKey("pat.list.revoke.confirm"),
+      visible: { field: "status", ne: "revoked" },
+    },
+  ],
+  toolbarActions: [
+    {
+      kind: "navigate",
+      id: "create",
+      label: i18nKey("pat.create.title"),
+      screen: PAT_MINT_SCREEN_ID,
+      style: "primary",
+    },
+  ],
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user views only their own personal access tokens, mirroring the list handler",
+    },
+  },
+  // Self-service settings-area screen, placed by the consuming app's own
+  // r.nav() — no nav area to resolve in isolation.
+  dormant: true,
+};
+
+// Grant-string vocabulary for a scope config's multiSelect field — a
+// read-only domain offers only "<domain>:read", one with a non-empty
+// `write` set additionally offers "<domain>:write" (matches expandScopes/
+// parseGrant in scopes.ts).
+export function patGrantOptions(scopes: PatScopeConfig): string[] {
+  const out: string[] = [];
+  for (const [domain, def] of Object.entries(scopes)) {
+    out.push(`${domain}:read`);
+    if (def.write && def.write.length > 0) out.push(`${domain}:write`);
+  }
+  return out;
+}
+
+export function createPatMintScreen(scopes: PatScopeConfig): SecretMintScreenDefinition {
+  return {
+    id: PAT_MINT_SCREEN_ID,
+    type: "secretMint",
+    handler: PatHandlers.create,
+    fields: {
+      name: { type: "text", required: true, maxLength: 120 },
+      scopes: {
+        type: "multiSelect",
+        required: true,
+        display: "checkboxes",
+        options: patGrantOptions(scopes),
+      },
+      expiresInDays: { type: "number", integer: true, min: 1, max: 3650, default: 90 },
+      currentPassword: { type: "text", required: true, format: "password", sensitive: true },
+      mfaCode: { type: "text" },
+    },
+    layout: {
+      sections: [
+        { fields: ["name", "scopes", "expiresInDays"] },
+        // Separate section: create.write requires password (+ MFA code, if
+        // enrolled) even though the request is already session-authed.
+        {
+          title: i18nKey("pat.create.reauth"),
+          fields: ["currentPassword", "mfaCode"],
+        },
+      ],
+    },
+    submitLabel: i18nKey("pat.create.submit"),
+    reveal: {
+      title: i18nKey("pat.created.title"),
+      warning: i18nKey("pat.created.hint"),
+      confirmLabel: i18nKey("pat.created.dismiss"),
+      fields: [
+        { field: "token", label: i18nKey("pat.created.token"), display: "code", copyable: true },
+      ],
+    },
+    redirect: PAT_SCREEN_ID,
+    cancelTarget: PAT_SCREEN_ID,
+    access: {
+      openToAll: {
+        reason:
+          "each signed-in user mints a token for their own account only, mirroring the create handler",
+      },
+    },
+  };
+}

package/packages/bundled-features/src/presets/changes.json

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "0.262.0",
+    "type": "improvement",
+    "title": "securityBaselineFeatures() preset: sessions, crypto-shredding, rate-limiting, audit (fw#2857).",
+    "detail": "`securityBaselineFeatures(opts?: { includeSessions?: boolean })` (`@cosmicdrift/kumiko-bundled-features/presets`) returns `[createSessionsFeature(), createCryptoShreddingFeature(), createRateLimitingFeature(), createAuditFeature()]` in that order — fresh instances per call, mirroring `dsgvoSelfServiceFeatures()`. `includeSessions: false` drops `createSessionsFeature()` from the returned array for apps that already mount `sessions` via `dsgvoSelfServiceFeatures()` (mounting the same feature name twice throws at boot). The host app still needs to mount `user`, `tenant`, and `auth-foundation` itself — `sessions` requires `user`/`auth-foundation`, `audit` requires `tenant`. Pairs with the new boot-validator warning that fires at `NODE_ENV=production` when any of the four feature names (`SECURITY_BASELINE_FEATURE_NAMES`, `@cosmicdrift/kumiko-framework/engine`) is missing from the mounted feature list."
+  }
+]

package/packages/bundled-features/src/presets/dsgvo-self-service.ts

@@ -0,0 +1,33 @@
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createComplianceProfilesFeature } from "../compliance-profiles/index.js";
+import { createDataRetentionFeature } from "../data-retention/index.js";
+import { createSessionsFeature } from "../sessions/index.js";
+import {
+  createUserDataRightsFeature,
+  type UserDataRightsOptions,
+} from "../user-data-rights/index.js";
+import { createUserProfileFeature } from "../user-profile/index.js";
+
+export type DsgvoSelfServiceOptions = {
+  /** Passed through to createUserDataRightsFeature — export/deletion mail
+   *  callbacks + Apex deletion HMAC. Default {} (no-op mail side). */
+  readonly userDataRights?: UserDataRightsOptions;
+};
+
+// DSGVO + account self-service chain every Kumiko SaaS app mounts (privacy
+// center, account deletion Art. 17, export Art. 20, sessions). Order is
+// load-bearing (require-order): user-data-rights needs data-retention +
+// compliance-profiles + sessions, user-profile needs user-data-rights. This
+// exact order used to be hand-copied into every app with an explainer
+// comment. text-content + legal-pages stay out deliberately — legal-pages
+// has an app-specific wrapLayout, text-content is a standalone foundation;
+// both are spread in by the app itself.
+export function dsgvoSelfServiceFeatures(opts: DsgvoSelfServiceOptions = {}): FeatureDefinition[] {
+  return [
+    createDataRetentionFeature(),
+    createComplianceProfilesFeature(),
+    createSessionsFeature(),
+    createUserDataRightsFeature(opts.userDataRights ?? {}),
+    createUserProfileFeature(),
+  ];
+}

package/packages/bundled-features/src/presets/index.ts

@@ -0,0 +1,2 @@
+export { type DsgvoSelfServiceOptions, dsgvoSelfServiceFeatures } from "./dsgvo-self-service.js";
+export { type SecurityBaselineOptions, securityBaselineFeatures } from "./security-baseline.js";

package/packages/bundled-features/src/presets/security-baseline.ts

@@ -0,0 +1,19 @@
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createAuditFeature } from "../audit/index.js";
+import { createCryptoShreddingFeature } from "../crypto-shredding/index.js";
+import { createRateLimitingFeature } from "../rate-limiting/index.js";
+import { createSessionsFeature } from "../sessions/index.js";
+
+export type SecurityBaselineOptions = {
+  readonly includeSessions?: boolean;
+};
+
+// Host app must mount user, tenant, auth-foundation (sessions/audit requires).
+export function securityBaselineFeatures(opts: SecurityBaselineOptions = {}): FeatureDefinition[] {
+  return [
+    ...(opts.includeSessions !== false ? [createSessionsFeature()] : []),
+    createCryptoShreddingFeature(),
+    createRateLimitingFeature(),
+    createAuditFeature(),
+  ];
+}

package/packages/bundled-features/src/rate-limiting/changes.json

@@ -0,0 +1,14 @@
+[
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Rate-limiting error keys have de/en translations"
+  },
+  {
+    "version": "0.291.0",
+    "type": "breaking",
+    "title": "`rate-limiting:query:status` only peeks buckets of the calling tenant (fw#3076)",
+    "detail": "The handler took an arbitrary bucket key and peeked it, so a tenant Admin who knew or guessed another tenant's key could read that bucket's counter. The key is now matched segment-exact against the caller: `tenant:`/`tenant+handler:` must carry the caller's own tenant id, `user:`/`user+handler:` the caller's own user id. Everything else — other tenants, other users, the global `ip:`, `l1:` and `l2:` middleware buckets, malformed keys — is `access_denied` (`bucket_outside_tenant`) unless the caller is SystemAdmin, whose access is unchanged. The check runs before the resolver-wiring check, so a denied caller learns nothing about the mount either.",
+    "migration": "Only affects non-SystemAdmin callers of `rate-limiting:query:status`. A tenant\nAdmin keeps `tenant:<own>`, `tenant+handler:<own>:<handler>`, `user:<self>` and\n`user+handler:<self>:<handler>`. Two reads it had before now need SystemAdmin:\nanother user's bucket inside the same tenant (the tenant is not part of a\n`user:` key, so it cannot be verified without a membership lookup) and the\nglobal `ip:`/`l1:`/`l2:` buckets, which are not tenant-owned. Ops tooling that\npeeks those from a tenant Admin session has to run as SystemAdmin."
+  }
+]

package/packages/bundled-features/src/rate-limiting/constants.ts

@@ -0,0 +1,10 @@
+export const RATE_LIMITING_FEATURE = "rate-limiting" as const;
+
+export const RateLimitQueries = {
+  status: "rate-limiting:query:status",
+} as const;
+
+export const RateLimitErrors = {
+  resolverUnavailable: "rate_limit_resolver_unavailable",
+  bucketOutsideTenant: "bucket_outside_tenant",
+} as const;

package/packages/bundled-features/src/rate-limiting/feature.ts

@@ -0,0 +1,30 @@
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { rateLimitStatus } from "./handlers/status.query.js";
+import { RATE_LIMITING_I18N } from "./i18n.js";
+
+// Opt-in feature. Loading it does NOT install rate-limit middleware —
+// the framework auto-wires the L3 dispatcher hook and the resolver
+// when (a) at least one handler declared a rateLimit option, OR (b) the
+// caller passed `context.rateLimit` explicitly (e.g. for L1/L2 setup).
+//
+// Loading this feature only adds the ops-side status query. Apps that
+// only use L3 (handler-opt-in) and don't need ops introspection can
+// skip this feature entirely — the resolver still runs.
+export function createRateLimitingFeature() {
+  return defineFeature(
+    "rate-limiting",
+    (r) => {
+      r.describe(
+        "Adds an ops-side `rate-limiting:query:status` query handler for inspecting current bucket state; the actual request throttling is wired automatically by the dispatcher when any handler declares a `rateLimit` option (e.g. `{ per: 'user', limit: 3, windowSeconds: 60 }`) or when you pass `context.rateLimit` to `buildServer`. Loading this feature is optional if you only need L3 per-handler rate limits and have no need for ops introspection.",
+      );
+      r.uiHints({
+        displayLabel: "Rate Limiting · Ops Query",
+        category: "operations",
+        recommended: false,
+      });
+      r.queryHandler(rateLimitStatus);
+      r.translations({ keys: RATE_LIMITING_I18N });
+    },
+    { dedupeOptions: {} },
+  );
+}

package/packages/bundled-features/src/rate-limiting/handlers/bucket-access.ts

@@ -0,0 +1,45 @@
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import type { RateLimitPer, SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
+import { RateLimitErrors } from "../constants.js";
+
+// Bucket keys are `<dimension>:<subject>[:<handler>]` (framework
+// rate-limit/bucket.ts) — only `tenant*` and `user*` carry a subject the
+// caller can own. `l1:`/`l2:` (middleware.ts) and every `ip*` bucket are
+// global, so they stay SystemAdmin-only.
+type BucketCaller = Pick<SessionUser, "id" | "tenantId" | "roles">;
+
+// Typed against RateLimitPer so a renamed dimension in bucket.ts
+// breaks the typecheck instead of silently denying access.
+const BUCKET_OWNER_KIND: Partial<Record<RateLimitPer, "tenant" | "user">> = {
+  tenant: "tenant",
+  "tenant+handler": "tenant",
+  user: "user",
+  "user+handler": "user",
+};
+
+function isOwnableDimension(dimension: string): dimension is keyof typeof BUCKET_OWNER_KIND {
+  return Object.hasOwn(BUCKET_OWNER_KIND, dimension);
+}
+
+function ownsBucket(bucket: string, caller: BucketCaller): boolean {
+  const [dimension, subject, ...handler] = bucket.split(":");
+  if (dimension === undefined) return false;
+  if (!isOwnableDimension(dimension)) return false;
+  const owner = BUCKET_OWNER_KIND[dimension] === "tenant" ? caller.tenantId : caller.id;
+  // Segment-exact: a startsWith check would pass `tenant:<own-id>-other`.
+  if (subject !== owner) return false;
+  return dimension.endsWith("+handler") ? handler.length > 0 : handler.length === 0;
+}
+
+export function bucketAccessDenied(
+  bucket: string,
+  caller: BucketCaller,
+): AccessDeniedError | undefined {
+  if (caller.roles.includes(ROLES.SystemAdmin)) return undefined;
+  if (ownsBucket(bucket, caller)) return undefined;
+  return new AccessDeniedError({
+    i18nKey: "rateLimiting.errors.bucketOutsideTenant",
+    details: { reason: RateLimitErrors.bucketOutsideTenant },
+  });
+}

package/packages/bundled-features/src/rate-limiting/handlers/status.query.ts

@@ -0,0 +1,60 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { RateLimitErrors } from "../constants.js";
+import { bucketAccessDenied } from "./bucket-access.js";
+
+// Ops-side bucket inspection. Pass the bucket key (e.g. "user:42",
+// "user+handler:42:orders:write:order:create") plus the limit/window the bucket
+// was configured with, and get back the current state. Backed by
+// resolver.peek() — purely read-only, no token deduction and no
+// refill-timestamp update, so dashboards can poll without nudging the
+// bucket state ahead of the next real request.
+//
+// Use cases: ops-CLI ("kumiko rl status user:42"), support agent debugging
+// "why is this user blocked", dashboard tile.
+//
+// Bucket key format is owned by the framework (see rate-limit/bucket.ts);
+// callers pass the constructed key directly. We don't synthesize from
+// (per, user, handler) here — peeking is a low-level op, the lookup
+// surface stays small. Because the key is caller-supplied, bucket-access.ts
+// restricts it to the caller's own tenant/user unless they are SystemAdmin.
+export const rateLimitStatus = defineQueryHandler({
+  // Short name — the registry qualifies this to `rate-limiting:query:status`
+  // when the feature is registered. Passing the qualified form here would
+  // double-prefix it and the handler wouldn't be reachable.
+  name: "status",
+  description:
+    "Peeks at one rate-limit bucket and returns its remaining tokens, window and next reset without consuming a token; use it to explain why a caller is being throttled. Non-SystemAdmin callers may only peek their own tenant's buckets (`tenant:`/`tenant+handler:`) and their own user buckets (`user:`/`user+handler:`); every other key, including the global `ip:`/`l1:`/`l2:` buckets, requires SystemAdmin.",
+  schema: z.object({
+    bucket: z.string().min(1),
+    limit: z.number().int().positive(),
+    windowSeconds: z.number().int().positive(),
+  }),
+  access: { roles: ["Admin", "SystemAdmin"] },
+  handler: async (query, ctx) => {
+    // Before the resolver check, so a foreign-tenant caller learns nothing
+    // about the wiring either.
+    const denied = bucketAccessDenied(query.payload.bucket, ctx.user);
+    if (denied) throw denied;
+    if (!ctx.rateLimit) {
+      throw new UnprocessableError(RateLimitErrors.resolverUnavailable, {
+        i18nKey: "rateLimiting.errors.resolverUnavailable",
+      });
+    }
+    const decision = await ctx.rateLimit.peek(query.payload.bucket, {
+      limit: query.payload.limit,
+      windowSeconds: query.payload.windowSeconds,
+    });
+    return {
+      bucket: query.payload.bucket,
+      limit: decision.limit,
+      remaining: decision.remaining,
+      windowSeconds: decision.windowSeconds,
+      // resetAt is meaningful only if the bucket is currently exhausted;
+      // we still return it so dashboards can show "next refill" uniformly.
+      resetAt: decision.resetAt.toString(),
+      retryAfterSeconds: decision.retryAfterSeconds,
+    };
+  },
+});