@cosmicdrift/kumiko-bundled-features 0.290.0 → 0.292.0

package/src/jobs/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "Tenant-visible job failures: `r.job({ tenantVisibleFailure })` plus `jobs:query:failures` (fw#3079)",
+    "detail": "A fire-and-forget job that fails left the tenant's screen on a spinner that never ends — `jobs:query:list` is SystemAdmin and reads cross-tenant over `systemDb.unsafeRaw`, so a tenant could not see its own job failing. Apps worked around it with their own failure entity written in the job's catch.\nA job now opts in declaratively: `r.job(\"generateTexts\", { trigger: …, tenantVisibleFailure: { messageKey: \"app:errors.generationFailed\", subjectFields: [\"campaignId\"] } }, handler)`. When its last attempt fails, the run-logger records one row per tenant, job and subject in the new `store_tenant_job_failures` table, and the tenant reads it back through `jobs:query:failures` (every membership rank, own tenant only).\nOnly a translation key travels to the tenant: the thrown error's own `i18nKey` when it carries one, otherwise the declared `messageKey`. The provider's message stays on `store_job_runs.error` and in the run log, both SystemAdmin-only. Records are scoped to the run's tenant — a tenant-less run (cron, `SYSTEM_TENANT_ID`) records nothing.\nLifetime and retries: a record lives until the next successful run of the same job and subject deletes it; there is no acknowledgement step (tenant job administration stays out of scope). Only the final attempt records, so a job with `retries` that succeeds on a later attempt never shows the tenant a failure. The daily `retention-cleanup` job purges leftovers past `retentionDays`.\n`jobs:query:list`, `jobs:query:details` and `jobs:query:retry` are unchanged. `JobRunnerOptions.onJobComplete`/`onJobFailed` gained an optional fifth `outcome` argument — existing four-argument callbacks keep working.",
+    "migration": "New store table. Run `kumiko migrate generate` and apply the migration — `store_tenant_job_failures` is created empty and stays empty until a job declares `tenantVisibleFailure`. No change needed for apps that do not opt in."
+  },
   {
     "version": "0.241.0",
     "type": "breaking",

package/src/jobs/constants.ts

@@ -13,6 +13,7 @@ export const JobQueries = {
   list: "jobs:query:list",
   details: "jobs:query:details",
   catalog: "jobs:query:catalog",
+  failures: "jobs:query:failures",
 } as const;
 
 // Error codes

package/src/jobs/db/queries/retention.ts

@@ -13,12 +13,14 @@
 import { deleteManyBatched } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { jobRunLogsTable, jobRunsTable } from "../../job-run-table";
+import { tenantJobFailuresTable } from "../../tenant-job-failure-table";
 
 const RETENTION_DELETE_BATCH_SIZE = 500;
 
 export type JobRunRetentionResult = {
   readonly runsDeleted: number;
   readonly logsDeleted: number;
+  readonly tenantFailuresDeleted: number;
 };
 
 export async function deleteStaleJobRuns(
@@ -40,5 +42,19 @@ export async function deleteStaleJobRuns(
     { limit: RETENTION_DELETE_BATCH_SIZE },
   );
 
-  return { runsDeleted: runsResult.deleted, logsDeleted: logsResult.deleted };
+  // Same window for the tenant-visible failure records (fw#3079): the run
+  // they point at is gone by now, and a job whose subject never ran again
+  // would otherwise keep its record forever.
+  const tenantFailuresResult = await deleteManyBatched(
+    db,
+    tenantJobFailuresTable,
+    { failedAt: { lt: cutoff } },
+    { limit: RETENTION_DELETE_BATCH_SIZE },
+  );
+
+  return {
+    runsDeleted: runsResult.deleted,
+    logsDeleted: logsResult.deleted,
+    tenantFailuresDeleted: tenantFailuresResult.deleted,
+  };
 }

package/src/jobs/feature.ts

@@ -21,9 +21,11 @@ import {
   createStaleRunSweepJob,
   DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS,
 } from "./handlers/stale-run-sweep.job";
+import { tenantFailuresQuery } from "./handlers/tenant-failures.query";
 import { triggerWrite } from "./handlers/trigger.write";
 import { JOBS_I18N } from "./i18n";
 import { jobRunLogsTableMeta, jobRunsTableMeta } from "./job-run-table";
+import { tenantJobFailuresTableMeta } from "./tenant-job-failure-table";
 
 export type JobsFeatureOptions = {
   // How long a job run (and its logs) stays in store_job_runs/
@@ -42,7 +44,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
   const staleRunTimeoutHours = options.staleRunTimeoutHours ?? DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS;
   return defineFeature("jobs", (r) => {
     r.describe(
-      "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI.",
+      "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI. A job that declares `tenantVisibleFailure` also records its last failed attempt per tenant and subject in `store_tenant_job_failures`, which the tenant itself reads through `jobs:query:failures` — a translation key only, never the provider's message (fw#3079).",
     );
     r.uiHints({
       displayLabel: "Jobs · Audit & Operator UI",
@@ -61,6 +63,9 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
     r.storeTable(jobRunLogsTableMeta, {
       reason: "read_side.job_run_logs",
     });
+    r.storeTable(tenantJobFailuresTableMeta, {
+      reason: "direct_write.tenant_job_failures",
+    });
 
     // Framework-provided rebuild job — available whenever `jobs` is composed; enqueueProjectionRebuild dispatches it.
     r.job(
@@ -112,6 +117,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
       list: r.queryHandler(listQuery),
       detail: r.queryHandler(detailQuery),
       catalog: r.queryHandler(catalogQuery),
+      failures: r.queryHandler(tenantFailuresQuery),
     };
 
     const systemAdminAccess = { roles: ["SystemAdmin"] as const };

package/src/jobs/handlers/tenant-failures.query.ts

@@ -0,0 +1,82 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import { z } from "zod";
+import { tenantJobFailuresTable } from "../tenant-job-failure-table";
+
+type TenantJobFailureRow = {
+  readonly tenantId: string;
+  readonly jobName: string;
+  readonly subject: string | null;
+  readonly messageKey: string;
+  readonly failedAt: Temporal.Instant;
+};
+
+const DEFAULT_LIMIT = 50;
+
+// Mirrors job-runner.ts's jobSubjectKey: sorted field names, so a caller that
+// passes the same subject values gets the same string the writer stored.
+function subjectKey(subject: Record<string, string | number | boolean | null>): string {
+  return JSON.stringify(
+    Object.keys(subject)
+      .sort()
+      .map((field) => [field, subject[field] ?? null]),
+  );
+}
+
+function isSubjectEntry(value: unknown): value is [string, unknown] {
+  return Array.isArray(value) && typeof value[0] === "string";
+}
+
+function parseSubject(stored: string | null): Record<string, unknown> | null {
+  if (stored === null) return null;
+  // A corrupt subject must not fail the whole list — the record still tells
+  // the tenant which job failed and why. parseJsonSafe only survives a
+  // SyntaxError, so the shape needs its own check.
+  const parsed = parseJsonSafe<unknown>(stored, null);
+  if (!Array.isArray(parsed)) return null;
+  return Object.fromEntries(parsed.filter(isSubjectEntry));
+}
+
+export const tenantFailuresQuery = defineQueryHandler({
+  name: "failures",
+  description:
+    "Lists the calling tenant's own failed jobs — one record per job and subject, newest first, each carrying a translation key for the reason, never the provider's own error message; use it to tell a tenant that their asynchronous job failed instead of leaving the screen waiting.",
+  schema: z.object({
+    jobName: z.string().optional(),
+    subject: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+    limit: z.number().min(1).max(200).optional(),
+  }),
+  // Every membership rank: a failure record carries a job name and a
+  // translation key, nothing a team member of the tenant may not see.
+  access: { roles: access.roles("User", "Editor", ...access.admin) },
+  handler: async (query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "jobs:query:failures requires ctx.systemDb (feature must declare r.systemScope())",
+      });
+    }
+    // assertTenantMatch is a self-check on the caller and returns the same
+    // unfiltered system-mode db (tenant-db.ts) — the explicit tenantId below
+    // is the filter, assertRowsTenant the second net. There is no
+    // cross-tenant mode here: SystemAdmin reads runs via jobs:query:list.
+    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+    const where: Record<string, unknown> = { tenantId: [query.user.tenantId] };
+    if (query.payload.jobName) where["jobName"] = query.payload.jobName;
+    if (query.payload.subject) where["subject"] = subjectKey(query.payload.subject);
+    const rows = await selectMany<TenantJobFailureRow>(db, tenantJobFailuresTable, where, {
+      orderBy: { col: "failedAt", direction: "desc" },
+      limit: query.payload.limit ?? DEFAULT_LIMIT,
+    });
+    return {
+      rows: ctx.systemDb.assertRowsTenant(rows, "tenantId").map((row) => ({
+        jobName: row.jobName,
+        subject: parseSubject(row.subject),
+        messageKey: row.messageKey,
+        failedAt: row.failedAt,
+      })),
+      nextCursor: null,
+    };
+  },
+});

package/src/jobs/index.ts

@@ -4,3 +4,4 @@ export type { JobRunLoggerCallbacks } from "./job-run-logger";
 export { createJobRunLogger } from "./job-run-logger";
 export type { JobLogLevel, JobRunStatus } from "./job-run-table";
 export { jobRunLogsTable, jobRunsTable } from "./job-run-table";
+export { tenantJobFailuresTable } from "./tenant-job-failure-table";

package/src/jobs/job-run-logger.ts

@@ -1,4 +1,10 @@
-import { fetchOne, insertMany, insertOne, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  deleteMany,
+  fetchOne,
+  insertMany,
+  insertOne,
+  updateMany,
+} from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configuredPiiSubjectKms,
   encryptPiiValueForSubject,
@@ -8,12 +14,18 @@ import {
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { type Registry, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
-import type { JobLogEntry, JobMeta, JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
+import type {
+  JobLogEntry,
+  JobMeta,
+  JobOutcomeMeta,
+  JobRunnerOptions,
+} from "@cosmicdrift/kumiko-framework/jobs";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { mapWithConcurrency } from "../shared";
 import { runCompletedSchema, runFailedSchema, runStartedSchema } from "./events";
 import { parseJobInstant } from "./job-instant";
 import { jobRunLogsTable, jobRunsTable } from "./job-run-table";
+import { tenantJobFailuresTable } from "./tenant-job-failure-table";
 
 // Matches PgKmsAdapter's default pool size (see tenant/handlers/*.query.ts) —
 // bounds concurrent getOrCreateDek calls so a large log batch doesn't claim
@@ -138,6 +150,54 @@ async function encryptStartedPayload(
   return encryptOrSentinel(kms, triggeredById, payload, "payload");
 }
 
+// fw#3079 — which row the tenant-visible failure record lives in: one per
+// (tenant, job, subject), so the next outcome of the same work replaces or
+// clears it. `subject` is null for a job that declares no subjectFields.
+// Null target = nothing to write or clear: the job did not opt in, the run
+// was tenant-less (cron resolves to SYSTEM_TENANT_ID, where no tenant-scoped
+// query could ever read the row), or the caller predates fw#3079 and passes
+// no outcome at all.
+function tenantJobFailureTarget(
+  jobName: string,
+  outcome: JobOutcomeMeta | undefined,
+): Record<string, unknown> | null {
+  if (!outcome?.tenantVisible || outcome.tenantId === SYSTEM_TENANT_ID) return null;
+  return { tenantId: outcome.tenantId, jobName, subject: outcome.tenantVisible.subject };
+}
+
+async function recordTenantJobFailure(
+  db: DbConnection,
+  jobName: string,
+  outcome: JobOutcomeMeta | undefined,
+): Promise<void> {
+  const where = tenantJobFailureTarget(jobName, outcome);
+  const messageKey = outcome?.tenantVisible?.messageKey;
+  // skip: no tenant-visible target, or an attempt BullMQ may still retry — a
+  // non-final failure must not show the tenant a failure the next attempt
+  // may still resolve.
+  if (!where || !messageKey || outcome?.finalAttempt !== true) return;
+  // ponytail: delete-then-insert instead of an upsert — two runs of the same
+  // key finishing at once can leave two rows, and the query returns the
+  // newest. Add a unique index + ON CONFLICT if that ever matters.
+  await deleteMany(db, tenantJobFailuresTable, where);
+  await insertOne(db, tenantJobFailuresTable, {
+    ...where,
+    messageKey,
+    failedAt: Temporal.Now.instant(),
+  });
+}
+
+async function clearTenantJobFailure(
+  db: DbConnection,
+  jobName: string,
+  outcome: JobOutcomeMeta | undefined,
+): Promise<void> {
+  const where = tenantJobFailureTarget(jobName, outcome);
+  // skip: no tenant-visible target — nothing was ever recorded
+  if (!where) return;
+  await deleteMany(db, tenantJobFailuresTable, where);
+}
+
 export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallbacks {
   const { db } = opts;
 
@@ -241,11 +301,16 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
     },
 
     onJobComplete: async (
-      _jobName: string,
+      jobName: string,
       bullJobId: string,
       duration: number,
       logs: JobLogEntry[],
+      outcome?: JobOutcomeMeta,
     ) => {
+      // Before the run-row write and independent of it: a successful run
+      // clears the tenant's failure record even when the run row itself is
+      // unreachable (the state-loss return below).
+      await clearTenantJobFailure(db, jobName, outcome);
       const resolved = await resolveRun(bullJobId);
       // skip: state loss between start + complete (worker restart, cache
       // evicted AND DB has no matching bull_job_id). Rare edge case; we
@@ -297,11 +362,15 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
     },
 
     onJobFailed: async (
-      _jobName: string,
+      jobName: string,
       bullJobId: string,
       error: string,
       logs: JobLogEntry[],
+      outcome?: JobOutcomeMeta,
     ) => {
+      // Mirror of onJobComplete: recorded independently of the run row, so a
+      // tenant still learns their job failed if the row is unreachable.
+      await recordTenantJobFailure(db, jobName, outcome);
       const resolved = await resolveRun(bullJobId);
       // skip: same rare state-loss case as in onJobComplete — drop the
       // failure write rather than forge a run row from scratch.

package/src/jobs/tenant-job-failure-table.ts

@@ -0,0 +1,39 @@
+import { asEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  type EntityTableMeta,
+  instant,
+  table as pgTable,
+  serial,
+  sql,
+  text,
+  uuid,
+} from "@cosmicdrift/kumiko-framework/db";
+
+// The tenant's own view of a failed job (fw#3079). Direct-write store like
+// store_job_runs: job-run-logger.ts writes it from the BullMQ callbacks,
+// outside any dispatcher transaction.
+//
+// Deliberately holds no error text. `message_key` is a translation key
+// (the thrown KumikoError's i18nKey or the one declared at the job), so a
+// provider message can never reach the tenant through this table — it stays
+// on store_job_runs.error and in store_job_run_logs, both SystemAdmin-only.
+//
+// One row per (tenant, job, subject): a later final-attempt failure replaces
+// it, a later successful run of the same key deletes it. `subject` is the
+// canonical JSON of the job's declared subjectFields, or NULL for a job that
+// declares none — stored in clear, so a job must not declare a PII field
+// as its subject.
+export const tenantJobFailuresTable = pgTable("store_tenant_job_failures", {
+  id: serial("id").primaryKey(),
+  tenantId: uuid("tenant_id").notNull(),
+  jobName: text("job_name").notNull(),
+  subject: text("subject"),
+  messageKey: text("message_key").notNull(),
+  failedAt: instant("failed_at").default(sql`now()`).notNull(),
+});
+
+const derivedTenantJobFailuresTableMeta = asEntityTableMeta(tenantJobFailuresTable);
+if (!derivedTenantJobFailuresTableMeta) {
+  throw new Error("tenantJobFailuresTable: table carries no EntityTableMeta — built via table()?");
+}
+export const tenantJobFailuresTableMeta: EntityTableMeta = derivedTenantJobFailuresTableMeta;

package/src/rate-limiting/__tests__/rate-limiting.integration.test.ts

@@ -7,7 +7,12 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import { setupTestStack, type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
 import { z } from "zod";
 import { createRateLimitingFeature } from "../feature";
 
@@ -93,3 +98,66 @@ describe("rate-limiting feature — status query", () => {
     expect(res.status).toBe(403);
   });
 });
+
+// The bucket key is caller-supplied, so the tenant boundary has to be drawn
+// on it server-side. i18nKey is asserted alongside the code because a plain
+// 403 could also come from tenant resolution and would pass either way.
+const OUTSIDE_TENANT_KEY = "rateLimiting.errors.bucketOutsideTenant";
+
+describe("rate-limiting feature — bucket tenant scope", () => {
+  test("denies an admin the bucket of another tenant", async () => {
+    const err = await stack.http.queryErr(
+      "rate-limiting:query:status",
+      { bucket: `tenant:${testTenantId(2)}`, limit: 5, windowSeconds: 60 },
+      admin,
+    );
+    expect(err.code).toBe("access_denied");
+    expect(err.i18nKey).toBe(OUTSIDE_TENANT_KEY);
+    expect(err.httpStatus).toBe(403);
+  });
+
+  test("denies a key that only starts with the caller's tenant id", async () => {
+    const err = await stack.http.queryErr(
+      "rate-limiting:query:status",
+      { bucket: `tenant:${admin.tenantId}-other`, limit: 5, windowSeconds: 60 },
+      admin,
+    );
+    expect(err.i18nKey).toBe(OUTSIDE_TENANT_KEY);
+  });
+
+  test("denies another user's bucket and the global IP buckets", async () => {
+    for (const bucket of [`user:${TestUsers.user.id}`, "l1:203.0.113.5", "ip:203.0.113.5"]) {
+      const err = await stack.http.queryErr(
+        "rate-limiting:query:status",
+        { bucket, limit: 5, windowSeconds: 60 },
+        admin,
+      );
+      expect(err.i18nKey).toBe(OUTSIDE_TENANT_KEY);
+    }
+  });
+
+  test("allows the caller's own tenant and handler-scoped buckets", async () => {
+    for (const bucket of [
+      `tenant:${admin.tenantId}`,
+      `tenant+handler:${admin.tenantId}:rl-probe:query:ping`,
+      `user+handler:${admin.id}:rl-probe:query:ping`,
+    ]) {
+      const status = await stack.http.queryOk<{ bucket: string; remaining: number }>(
+        "rate-limiting:query:status",
+        { bucket, limit: 5, windowSeconds: 60 },
+        admin,
+      );
+      expect(status.bucket).toBe(bucket);
+      expect(status.remaining).toBe(5);
+    }
+  });
+
+  test("leaves SystemAdmin access to foreign buckets untouched", async () => {
+    const status = await stack.http.queryOk<{ bucket: string }>(
+      "rate-limiting:query:status",
+      { bucket: `tenant:${testTenantId(2)}`, limit: 5, windowSeconds: 60 },
+      TestUsers.systemAdmin,
+    );
+    expect(status.bucket).toBe(`tenant:${testTenantId(2)}`);
+  });
+});

package/src/rate-limiting/changes.json

@@ -1 +1,9 @@
-[]
+[
+  {
+    "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/src/rate-limiting/constants.ts

@@ -6,4 +6,5 @@ export const RateLimitQueries = {
 
 export const RateLimitErrors = {
   resolverUnavailable: "rate_limit_resolver_unavailable",
+  bucketOutsideTenant: "bucket_outside_tenant",
 } as const;

package/src/rate-limiting/handlers/bucket-access.ts

@@ -0,0 +1,39 @@
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
+import { RateLimitErrors } from "../constants";
+
+// 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 = {
+  readonly id: string;
+  readonly tenantId: string;
+  readonly roles: readonly string[];
+};
+
+function ownsBucket(bucket: string, caller: BucketCaller): boolean {
+  const [dimension, subject, ...handler] = bucket.split(":");
+  if (dimension === undefined) return false;
+  const owner =
+    dimension === "tenant" || dimension === "tenant+handler"
+      ? caller.tenantId
+      : dimension === "user" || dimension === "user+handler"
+        ? caller.id
+        : undefined;
+  if (owner === undefined) return false;
+  // 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("SystemAdmin")) return undefined;
+  if (ownsBucket(bucket, caller)) return undefined;
+  return new AccessDeniedError({
+    i18nKey: "rateLimiting.errors.bucketOutsideTenant",
+    details: { reason: RateLimitErrors.bucketOutsideTenant },
+  });
+}

package/src/rate-limiting/handlers/status.query.ts

@@ -2,6 +2,7 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { RateLimitErrors } from "../constants";
+import { bucketAccessDenied } from "./bucket-access";
 
 // 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
@@ -16,14 +17,15 @@ import { RateLimitErrors } from "../constants";
 // 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.
+// 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.",
+    "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(),
@@ -31,6 +33,10 @@ export const rateLimitStatus = defineQueryHandler({
   }),
   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",