@cosmicdrift/kumiko-framework 0.409.0 → 0.410.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -100,8 +100,10 @@ that holds global data calls `r.systemScope()`.
100
100
  `{ access: { roles: ["Admin", "User"] } }`, or
101
101
  `{ access: { openToAll: { reason: "<why every signed-in user may>" } } }`.
102
102
  Screens and nav entries can narrow visibility further with their own
103
- `access`. Anonymous endpoints use the `anonymous` role. Field level and row
104
- level rules exist as well (see the table below).
103
+ `access`. Anonymous endpoints use the `anonymous` role; add `anySignedIn: true`
104
+ (`{ roles: ["anonymous"], anySignedIn: true }`) so a visitor who is signed in
105
+ passes whatever roles the session carries. Field level and row level rules
106
+ exist as well (see the table below).
105
107
  An `openToAll` write handler whose payload contains personal fields must
106
108
  say that every tenant member may write them:
107
109
  `{ openToAll: { reason: "...", personalData: "tenant-members" } }`. The
@@ -276,6 +276,7 @@ type ActionFormScreenDefinition = {
276
276
  summary?: {
277
277
  title: string;
278
278
  subtitle?: string;
279
+ params?: Readonly<Record<string, string>>;
279
280
  }; // Context box above the fields (i18n keys).
280
281
  submitStyle?: "primary" | "danger"; // Visual style of the submit button.
281
282
  successMessage?: string; // i18n key of a confirmation shown above the form after a successful submit when the screen stays put (no `redirect`, not drawer-hosted).
@@ -1514,6 +1515,7 @@ type RoleAccessPersonalData = "public-intake";
1514
1515
  type RoleAccessRule = {
1515
1516
  roles: string[];
1516
1517
  personalData?: RoleAccessPersonalData;
1518
+ anySignedIn?: true;
1517
1519
  };
1518
1520
  type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction;
1519
1521
  type RowActionWriteHandler = {
@@ -399,6 +399,7 @@
399
399
  | <a id="handler-access-missing"></a>`handler/access-missing` | Every write, query and stream handler declares an access rule. | Set access: { roles: [...] } or { openToAll: { reason } }. | `packages/framework/src/engine/boot-validator/entity-handler-access-rules.ts` |
400
400
  | <a id="handler-access-personal-data-unknown"></a>`handler/access-personal-data-unknown` | access.personalData is "public-intake" when set. | Use personalData: "public-intake" or remove it. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
401
401
  | <a id="handler-anonymous-personal-data-undeclared"></a>`handler/anonymous-personal-data-undeclared` | A write handler that allows anonymous callers and accepts personal-data fields declares access.personalData "public-intake". | Declare access: { roles: [..., "anonymous"], personalData: "public-intake" }. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
402
+ | <a id="handler-any-signed-in-invalid"></a>`handler/any-signed-in-invalid` | access.anySignedIn is true when set and appears only next to the anonymous role, on endpoints that are public anyway. | Add "anonymous" to access.roles, or use { openToAll: { reason } } for every signed-in user without anonymous callers. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
402
403
  | <a id="handler-escape-hatch-grants-invalid"></a>`handler/escape-hatch-grants-invalid` | An escapeHatch declares valid grants. | Correct the escapeHatch grants as named in the error message. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
403
404
  | <a id="handler-escape-hatch-reason-invalid"></a>`handler/escape-hatch-reason-invalid` | An escapeHatch carries a valid reason. | Write an escapeHatch reason that explains the bypass. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
404
405
  | <a id="handler-input-schema-not-introspectable"></a>`handler/input-schema-not-introspectable` | A write handler's input schema is a Zod shape whose keys boot can collect. | Use an object schema the boot validator can walk, as named in the error message. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
@@ -14,6 +14,8 @@ Public endpoints without a logged-in user.
14
14
 
15
15
  - `access: "anonymous"` on handlers that must stay public
16
16
  - Rate limits that still bind anonymous callers (`per: "ip+handler"`)
17
+ - `anySignedIn: true` next to `anonymous`, so a visitor who is signed in with a role the
18
+ handler does not list is not turned away from a public form
17
19
 
18
20
  ## Source
19
21
 
@@ -63,6 +65,7 @@ const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
63
65
  // Each value is written by exactly one test; the tenant is fixed, so rows are told apart by value, not by reset.
64
66
  const PRODUCT_NAME = "Espresso Beans (anonymous read)";
65
67
  const GUEST_EMAIL = "guest-checkout@example.com";
68
+ const DRIVER_EMAIL = "driver-checkout@example.com";
66
69
 
67
70
  let stack: TestStack;
68
71
 
@@ -126,6 +129,19 @@ describe("guest checkout: anonymous write lands with placedBy=anonymous", () =>
126
129
  expect(orders[0]?.placedBy).toBe(ANONYMOUS_USER_ID);
127
130
  expect(orders[0]?.email).toBe(GUEST_EMAIL);
128
131
  });
132
+
133
+ test("a signed-in caller with a role the handler does not list still checks out", async () => {
134
+ await stack.http.writeOk(
135
+ "shop:write:guest-order:place",
136
+ { productId: "00000000-0000-4000-8000-000000000098", email: DRIVER_EMAIL },
137
+ TestUsers.driver,
138
+ );
139
+ const orders = (await selectMany(stack.db, guestOrderTable)).filter(
140
+ (order) => order.email === DRIVER_EMAIL,
141
+ );
142
+ expect(orders).toHaveLength(1);
143
+ expect(orders[0]?.placedBy).toBe(TestUsers.driver.id);
144
+ });
129
145
  });
130
146
 
131
147
  describe("regression guards", () => {
@@ -259,7 +275,13 @@ export const anonymousAccessFeature = defineFeature("shop", (r) => {
259
275
  // anonymous root handler — the runtime personal-data gate
260
276
  // (write-origin.ts) requires this explicit opt-in, the same way the
261
277
  // boot validator would reject an openToAll declaration missing it.
262
- access: { roles: [...access.anonymous, "User"], personalData: "public-intake" },
278
+ // The browser sends the session cookie along, so a signed-in visitor arrives with its
279
+ // roles; anySignedIn keeps the checkout open to them whatever those roles are.
280
+ access: {
281
+ roles: [...access.anonymous, "User"],
282
+ personalData: "public-intake",
283
+ anySignedIn: true,
284
+ },
263
285
  rateLimit: { per: "ip+handler", limit: 30, windowSeconds: 60 },
264
286
  });
265
287
 
@@ -10,7 +10,7 @@ Public contact form backend: the contact bundled feature with its required compa
10
10
 
11
11
  Public contact form backend. The `contact` bundled feature stores questions, contact
12
12
  requests and problem reports from website visitors and notifies every SystemAdmin (mail,
13
- optional Telegram). The notification names only the kind, the app and a link into the inbox:
13
+ Telegram only when the app turns it on). The notification names only the kind, the app and a link into the inbox:
14
14
  no name, address, phone, subject or message. Telegram is a third party where nothing can be
15
15
  shredded or recalled, so it gets the same minimal text. Website senders get a fixed
16
16
  acknowledgement that repeats nothing they typed; signed-in admin reports get a copy.
@@ -48,10 +48,16 @@ bun test --config=bunfig.integration.toml samples/recipes/contact
48
48
  ## Integration into a real app
49
49
 
50
50
  1. Mount `createContactFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
51
- `files` with a file provider, and `config`/`secrets` for the Telegram bot token.
51
+ `files` with a file provider and `config`.
52
52
  2. Run `kumiko schema generate` (new tables, plus the delivery `idempotency_key` column).
53
- 3. SystemAdmins set `contact:config:reply-to` and `contact:config:telegram-chat` in the admin.
54
- 4. Embed `/contact/client.js` on the website; the form is yours.
53
+ 3. SystemAdmins set `contact:config:reply-to` in the admin.
54
+ 4. Embed `/contact/client.js` on the website; the form is yours. A website served by another
55
+ server can serve the same script from `CONTACT_CLIENT_SOURCE` and type its calls with
56
+ `ContactWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/contact/client`.
57
+
58
+ Telegram is optional and off by default: notifications go by mail to SystemAdmins only. An app
59
+ that turns it on (`telegram: true`) also mounts `channel-telegram` and `secrets` for the bot
60
+ token, and SystemAdmins set `contact:config:telegram-chat`.
55
61
 
56
62
  ## Source files
57
63
 
@@ -152,7 +158,7 @@ describe("contact sample", () => {
152
158
  //
153
159
  // Prerequisites the app wires itself:
154
160
  // - `anonymousAccess` (defaultTenantId = SYSTEM_TENANT_ID) so the form needs no login
155
- // - delivery with a mail channel (and channel-telegram for the optional Telegram forward)
161
+ // - delivery with a mail channel (channel-telegram only with `telegram: true`, off by default)
156
162
  // - a file provider, because the entities carry file fields
157
163
  // - `kumiko schema generate` for the new tables
158
164
 
@@ -49,7 +49,7 @@ One entry per feature a package ships: purpose, import of its factory, required
49
49
  - `config`: Stores per-tenant (and optionally per-user) configuration values with a multi-layer cascade: user-row → tenant-row → system-row → app-override (deploy-time `AppConfigOverrides`) → computed → feature default.
50
50
  `import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config"`
51
51
  - `contact`: Contact inbox: an anonymous browser client (GET /contact/client.js) submits questions, contact requests, bug reports and wishes behind a honeypot, a minimum submit time and a single-use proof-of-work challenge; signed-in users file reports from the admin.
52
- `import { createContactFeature } from "@cosmicdrift/kumiko-bundled-features/contact"`; requires `config`, `delivery`, `user-data-rights`, `files`, `notes-history`, `channel-telegram`
52
+ `import { createContactFeature } from "@cosmicdrift/kumiko-bundled-features/contact"`; requires `config`, `delivery`, `user-data-rights`, `files`, `notes-history`
53
53
  - `crypto-shredding`: Operator-level crypto-shredding trigger.
54
54
  `import { createCryptoShreddingFeature } from "@cosmicdrift/kumiko-bundled-features/crypto-shredding"`
55
55
  - `custom-fields`: Tenant- and system-scoped custom field definitions with generic value storage on any host entity.
@@ -200,14 +200,15 @@ Contact inbox: an anonymous browser client (GET /contact/client.js) submits ques
200
200
 
201
201
  Category: communication
202
202
 
203
- Requires: `config`, `delivery`, `user-data-rights`, `files`, `notes-history`, `channel-telegram`
203
+ Requires: `config`, `delivery`, `user-data-rights`, `files`, `notes-history`
204
+
205
+ Optional requires: `channel-telegram`
204
206
 
205
207
  Config keys:
206
208
 
207
209
  | Key | Type | Scope | Default |
208
210
  | --- | --- | --- | --- |
209
211
  | `reply-to` | text | system | `` |
210
- | `telegram-chat` | text | system | `` |
211
212
 
212
213
  ## crypto-shredding
213
214
 
@@ -1,4 +1,4 @@
1
- import { isOpenToAllGranted } from "@cosmicdrift/kumiko-types/handlers";
1
+ import { isAnySignedInGranted, isOpenToAllGranted } from "@cosmicdrift/kumiko-types/handlers";
2
2
  import { ANONYMOUS_ROLE } from "./system-user.js";
3
3
  // Default-deny: a handler without an explicit AccessRule is unreachable. To
4
4
  // grant access a handler must either list allowed roles or opt into
@@ -11,6 +11,8 @@ import { ANONYMOUS_ROLE } from "./system-user.js";
11
11
  // list `anonymous` in `roles` (e.g. `roles: ["anonymous", "customer"]`).
12
12
  // Without this guard, enabling `anonymousAccess` on the server would silently
13
13
  // turn every existing `openToAll: true` handler into a public endpoint.
14
+ // `anySignedIn` widens such a public rule to every signed-in caller instead of
15
+ // the listed roles only.
14
16
  export function hasAccess(user, access) {
15
17
  if (!access)
16
18
  return false;
@@ -21,5 +23,7 @@ export function hasAccess(user, access) {
21
23
  }
22
24
  if (access.roles.length === 0)
23
25
  return false;
26
+ if (isAnySignedInGranted(access) && !user.roles.includes(ANONYMOUS_ROLE))
27
+ return true;
24
28
  return access.roles.some((role) => user.roles.includes(role));
25
29
  }
@@ -178,6 +178,22 @@ function validateAnonymousPersonalData(feature, handlerName, handler) {
178
178
  "vouch for it; protection comes from the handler's required rateLimit (per ip).",
179
179
  });
180
180
  }
181
+ // Read via `unknown`: access can come from untyped sources (pattern JSON, Designer).
182
+ function validateAnySignedIn(feature, kind, handlerName, access) {
183
+ // skip: openToAll has no anySignedIn, or nothing declared
184
+ if (!("roles" in access) || !("anySignedIn" in access))
185
+ return;
186
+ const declared = access.anySignedIn;
187
+ // skip: a public rule that admits every signed-in caller as well
188
+ if (declared === true && accessAllowsAnonymous(access))
189
+ return;
190
+ const problem = declared === true
191
+ ? `its roles do not include "${ANONYMOUS_ROLE}"; for every signed-in user without anonymous callers use { openToAll: { reason } }`
192
+ : `the only supported value is true, got ${JSON.stringify(declared)}`;
193
+ throw bootRuleError(HANDLER_DECLARATION_RULES.anySignedInInvalid, {
194
+ message: `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares access.anySignedIn but ${problem}.`,
195
+ });
196
+ }
181
197
  // The rateLimit is the only protection of a public-intake handler, so the
182
198
  // generic anonymous opt-out (rateLimit: { disabled: true }) must not apply.
183
199
  function validatePublicIntakeRateLimit(feature, kind, handlerName, handler) {
@@ -197,6 +213,7 @@ function validatePublicIntakeRateLimit(feature, kind, handlerName, handler) {
197
213
  export function validateAccessDeclarations(feature) {
198
214
  for (const [handlerName, handler] of Object.entries(feature.writeHandlers)) {
199
215
  validateOpenToAllReason(feature, "write", handlerName, handler.access);
216
+ validateAnySignedIn(feature, "write", handlerName, handler.access);
200
217
  validateEscapeHatchReason(feature, "write", handlerName, handler.escapeHatch);
201
218
  validatePersonalDataValue(feature, "write", handlerName, handler.access);
202
219
  validateOpenToAllPersonalData(feature, handlerName, handler);
@@ -205,6 +222,7 @@ export function validateAccessDeclarations(feature) {
205
222
  }
206
223
  for (const [handlerName, handler] of Object.entries(feature.queryHandlers)) {
207
224
  validateOpenToAllReason(feature, "query", handlerName, handler.access);
225
+ validateAnySignedIn(feature, "query", handlerName, handler.access);
208
226
  validateEscapeHatchReason(feature, "query", handlerName, handler.escapeHatch);
209
227
  validatePersonalDataSupportedForKind(feature, "query", handlerName, handler.access);
210
228
  validatePersonalDataValue(feature, "query", handlerName, handler.access);
@@ -212,6 +230,7 @@ export function validateAccessDeclarations(feature) {
212
230
  }
213
231
  for (const [handlerName, handler] of Object.entries(feature.streamHandlers)) {
214
232
  validateOpenToAllReason(feature, "stream", handlerName, handler.access);
233
+ validateAnySignedIn(feature, "stream", handlerName, handler.access);
215
234
  validateEscapeHatchReason(feature, "stream", handlerName, handler.escapeHatch);
216
235
  validatePersonalDataSupportedForKind(feature, "stream", handlerName, handler.access);
217
236
  }
@@ -2748,6 +2748,11 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
2748
2748
  readonly summary: 'A handler with access.personalData "public-intake" allows the anonymous role.';
2749
2749
  readonly fix: "Add the anonymous role to access.roles or remove personalData.";
2750
2750
  };
2751
+ readonly anySignedInInvalid: {
2752
+ readonly id: "handler/any-signed-in-invalid";
2753
+ readonly summary: "access.anySignedIn is true when set and appears only next to the anonymous role, on endpoints that are public anyway.";
2754
+ readonly fix: 'Add "anonymous" to access.roles, or use { openToAll: { reason } } for every signed-in user without anonymous callers.';
2755
+ };
2751
2756
  readonly publicIntakeRateLimitDisabled: {
2752
2757
  readonly id: "handler/public-intake-rate-limit-disabled";
2753
2758
  readonly summary: 'A handler with access.personalData "public-intake" keeps its rateLimit enabled, because it is the only protection for anonymous personal-data writes.';
@@ -34,6 +34,11 @@ export declare const HANDLER_DECLARATION_RULES: {
34
34
  readonly summary: 'A handler with access.personalData "public-intake" allows the anonymous role.';
35
35
  readonly fix: "Add the anonymous role to access.roles or remove personalData.";
36
36
  };
37
+ readonly anySignedInInvalid: {
38
+ readonly id: "handler/any-signed-in-invalid";
39
+ readonly summary: "access.anySignedIn is true when set and appears only next to the anonymous role, on endpoints that are public anyway.";
40
+ readonly fix: 'Add "anonymous" to access.roles, or use { openToAll: { reason } } for every signed-in user without anonymous callers.';
41
+ };
37
42
  readonly publicIntakeRateLimitDisabled: {
38
43
  readonly id: "handler/public-intake-rate-limit-disabled";
39
44
  readonly summary: 'A handler with access.personalData "public-intake" keeps its rateLimit enabled, because it is the only protection for anonymous personal-data writes.';
@@ -34,6 +34,11 @@ export const HANDLER_DECLARATION_RULES = {
34
34
  summary: 'A handler with access.personalData "public-intake" allows the anonymous role.',
35
35
  fix: "Add the anonymous role to access.roles or remove personalData.",
36
36
  },
37
+ anySignedInInvalid: {
38
+ id: "handler/any-signed-in-invalid",
39
+ summary: "access.anySignedIn is true when set and appears only next to the anonymous role, on endpoints that are public anyway.",
40
+ fix: 'Add "anonymous" to access.roles, or use { openToAll: { reason } } for every signed-in user without anonymous callers.',
41
+ },
37
42
  publicIntakeRateLimitDisabled: {
38
43
  id: "handler/public-intake-rate-limit-disabled",
39
44
  summary: 'A handler with access.personalData "public-intake" keeps its rateLimit enabled, because it is the only protection for anonymous personal-data writes.',
@@ -1,7 +1,7 @@
1
1
  // Nav validation + collectKnownRoles (role synthesis for ownership
2
2
  // validation in index.ts — thematically adjacent to ownership.ts, kept
3
3
  // here since this is a structural move, not a semantic reorg).
4
- import { isOpenToAllGranted } from "@cosmicdrift/kumiko-types/handlers";
4
+ import { isAnySignedInGranted, isOpenToAllGranted } from "@cosmicdrift/kumiko-types/handlers";
5
5
  import { createFallbackLogger } from "../../logging/utils.js";
6
6
  import { qualifyEntityName } from "../qualified-name.js";
7
7
  import { bootRuleError } from "./boot-rule.js";
@@ -118,12 +118,14 @@ export function validateNavCycles(allNavQns) {
118
118
  visit(qualified, []);
119
119
  }
120
120
  }
121
- // undefined or granted openToAll means visible to everyone (no role-set to compare); malformed/denied openToAll returns `[]`, same as an explicit `roles: []`.
121
+ // undefined, granted openToAll or anySignedIn means visible to everyone (no role-set to compare); malformed/denied openToAll returns `[]`, same as an explicit `roles: []`.
122
122
  function navViewerRoles(access) {
123
123
  if (access === undefined)
124
124
  return undefined;
125
125
  if ("openToAll" in access)
126
126
  return isOpenToAllGranted(access) ? undefined : [];
127
+ if (isAnySignedInGranted(access))
128
+ return undefined;
127
129
  return access.roles;
128
130
  }
129
131
  // Warn (never throw — this is a real UX bug, not a broken ref)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-framework",
3
- "version": "0.409.0",
3
+ "version": "0.410.0",
4
4
  "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
203
203
  "./package.json": "./package.json"
204
204
  },
205
205
  "dependencies": {
206
- "@cosmicdrift/kumiko-types": "0.409.0",
206
+ "@cosmicdrift/kumiko-types": "0.410.0",
207
207
  "bullmq": "^5.81.5",
208
208
  "hono": "^4.13.14",
209
209
  "i18next": "^26.5.12",
@@ -225,7 +225,7 @@
225
225
  }
226
226
  },
227
227
  "devDependencies": {
228
- "@cosmicdrift/kumiko-testing": "0.409.0",
228
+ "@cosmicdrift/kumiko-testing": "0.410.0",
229
229
  "bun-types": "^1.4.4",
230
230
  "fflate": "^0.8.3",
231
231
  "meilisearch": "^0.62.0",
package/src/changes.json CHANGED
@@ -1,4 +1,10 @@
1
1
  [
2
+ {
3
+ "version": "0.410.0",
4
+ "type": "improvement",
5
+ "title": "anySignedIn: public handlers admit every signed-in caller",
6
+ "detail": "A role rule that includes `anonymous` may add `anySignedIn: true` (`{ roles: [\"anonymous\"], anySignedIn: true }`). A signed-in caller then passes whatever roles the session carries, because the browser sends the session cookie to a public endpoint and an app-specific role (for example \"Hausmeister\") used to turn away a visitor who is welcome anonymously. `hasAccess` and `isUiAccessGranted` honour the flag, nav entries with such a rule stay visible to every viewer, and feature-ast reads and writes it. The boot validator rejects `anySignedIn` on a rule without `anonymous` (use `openToAll` for \"every signed-in user\") and any value other than `true` (rule `handler/any-signed-in-invalid`). The public handlers of bundled features now set it: waitlist submit, contact challenge and submit, user-data-rights deletion by email and token and download by token, managed-pages published pages and branding, file-derivatives public variants, compliance-profiles sub-processors, tenant-inactivity keep-account, auth-email-password login options and self-registration status, template-resolver by tenant and slug, seo config and subscription-paddle checkout config. Anonymous-only auth flows (signup, reset password, verify email, invite info, account unlock, MFA preauth) are unchanged."
7
+ },
2
8
  {
3
9
  "version": "0.409.0",
4
10
  "type": "improvement",