@cosmicdrift/kumiko-framework 0.411.0 → 0.413.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.
Files changed (87) hide show
  1. package/agents/api/framework-db.md +1 -1
  2. package/agents/api/framework-engine.md +48 -1
  3. package/agents/api/framework-errors.md +2 -0
  4. package/agents/api/types.md +8 -0
  5. package/agents/api.md +2 -2
  6. package/agents/boot-rules.md +343 -0
  7. package/agents/examples/api-docs.md +710 -0
  8. package/agents/examples/golden-path.md +11 -11
  9. package/agents/examples/{contact.md → helpdesk.md} +31 -31
  10. package/agents/examples.md +2 -1
  11. package/agents/features-index.md +2 -2
  12. package/agents/features.md +16 -16
  13. package/dist/api/auth-middleware.d.ts +1 -0
  14. package/dist/api/index.d.ts +3 -0
  15. package/dist/api/index.js +3 -0
  16. package/dist/api/pat-auth-reject.d.ts +7 -0
  17. package/dist/api/pat-auth-reject.js +7 -0
  18. package/dist/api/server-middleware.js +2 -1
  19. package/dist/compliance/sub-processors.js +2 -2
  20. package/dist/config/index.d.ts +25 -0
  21. package/dist/config/index.js +28 -1
  22. package/dist/db/event-store-executor-read-paging.d.ts +1 -0
  23. package/dist/db/event-store-executor-read-paging.js +2 -1
  24. package/dist/db/read-gate-clause.js +26 -7
  25. package/dist/db/table-builder.d.ts +1 -2
  26. package/dist/engine/boot-validator/boot-report.d.ts +3 -0
  27. package/dist/engine/boot-validator/boot-report.js +2 -2
  28. package/dist/engine/boot-validator/boot-rules.d.ts +570 -0
  29. package/dist/engine/boot-validator/boot-rules.js +20 -0
  30. package/dist/engine/boot-validator/definition-config-events-jobs-rules.d.ts +77 -0
  31. package/dist/engine/boot-validator/definition-config-events-jobs-rules.js +77 -0
  32. package/dist/engine/boot-validator/definition-events-rules.d.ts +42 -0
  33. package/dist/engine/boot-validator/definition-events-rules.js +42 -0
  34. package/dist/engine/boot-validator/definition-feature-rules.d.ts +42 -0
  35. package/dist/engine/boot-validator/definition-feature-rules.js +42 -0
  36. package/dist/engine/boot-validator/definition-field-factories-rules.d.ts +17 -0
  37. package/dist/engine/boot-validator/definition-field-factories-rules.js +17 -0
  38. package/dist/engine/boot-validator/definition-handlers-rules.d.ts +72 -0
  39. package/dist/engine/boot-validator/definition-handlers-rules.js +72 -0
  40. package/dist/engine/boot-validator/definition-ownership-from-rules.d.ts +27 -0
  41. package/dist/engine/boot-validator/definition-ownership-from-rules.js +27 -0
  42. package/dist/engine/boot-validator/definition-probes-rules.d.ts +47 -0
  43. package/dist/engine/boot-validator/definition-probes-rules.js +47 -0
  44. package/dist/engine/boot-validator/definition-role-assignment-rules.d.ts +27 -0
  45. package/dist/engine/boot-validator/definition-role-assignment-rules.js +27 -0
  46. package/dist/engine/boot-validator/definition-ui-extensions-rules.d.ts +197 -0
  47. package/dist/engine/boot-validator/definition-ui-extensions-rules.js +197 -0
  48. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +32 -0
  49. package/dist/engine/boot-validator/definition-webhook-events-rules.js +32 -0
  50. package/dist/engine/define-feature.js +29 -9
  51. package/dist/engine/define-handler.js +8 -4
  52. package/dist/engine/definition-violations.d.ts +14 -0
  53. package/dist/engine/definition-violations.js +71 -0
  54. package/dist/engine/entity-handlers.js +39 -13
  55. package/dist/engine/entity-list-runtime-options.js +12 -0
  56. package/dist/engine/event-def.js +32 -12
  57. package/dist/engine/factories.d.ts +2 -0
  58. package/dist/engine/factories.js +16 -5
  59. package/dist/engine/feature-builder-state.d.ts +2 -1
  60. package/dist/engine/feature-builder-state.js +1 -0
  61. package/dist/engine/feature-config-events-jobs.js +63 -27
  62. package/dist/engine/feature-entity-handlers.js +15 -6
  63. package/dist/engine/feature-probes.js +29 -9
  64. package/dist/engine/feature-ui-extensions.js +178 -92
  65. package/dist/engine/index.d.ts +5 -2
  66. package/dist/engine/index.js +4 -1
  67. package/dist/engine/object-form.js +8 -2
  68. package/dist/engine/ownership.js +17 -5
  69. package/dist/engine/registry-facade.js +13 -0
  70. package/dist/engine/role-assignment.js +17 -5
  71. package/dist/engine/webhook-contracts.d.ts +12 -0
  72. package/dist/engine/webhook-contracts.js +172 -0
  73. package/dist/engine/webhook-events.d.ts +34 -0
  74. package/dist/engine/webhook-events.js +85 -0
  75. package/dist/errors/docs-url.js +2 -19
  76. package/dist/errors/error-codes.d.ts +20 -0
  77. package/dist/errors/error-codes.js +19 -0
  78. package/dist/errors/index.d.ts +2 -0
  79. package/dist/errors/index.js +1 -0
  80. package/dist/files/file-routes.js +1 -1
  81. package/dist/i18n/required-surface-keys.d.ts +4 -0
  82. package/dist/i18n/required-surface-keys.js +15 -0
  83. package/dist/schema-cli/shared.d.ts +11 -0
  84. package/dist/schema-cli/shared.js +37 -3
  85. package/dist/schema-cli/validate-command.js +10 -3
  86. package/package.json +3 -3
  87. package/src/changes.json +42 -0
@@ -45,7 +45,7 @@ src/__tests__/feature.integration.test.ts write → read back, access, not fou
45
45
  import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
46
46
  import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
47
47
  import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
48
- import { helpdeskFeature } from "../feature";
48
+ import { ticketingFeature } from "../feature";
49
49
 
50
50
  type TicketRow = { id: string; title: string; isClosed: boolean };
51
51
 
@@ -55,7 +55,7 @@ let admin = createTestUser({ roles: ["Admin"], tenantId: testTenantId(nextTenant
55
55
  let agent = createTestUser({ id: 2, roles: ["User"], tenantId: testTenantId(nextTenant) });
56
56
 
57
57
  beforeAll(async () => {
58
- stack = await setupTestStack({ features: [helpdeskFeature], systemHooks: [] });
58
+ stack = await setupTestStack({ features: [ticketingFeature], systemHooks: [] });
59
59
  });
60
60
 
61
61
  afterAll(async () => {
@@ -71,7 +71,7 @@ beforeEach(() => {
71
71
 
72
72
  async function openTicket(title: string): Promise<string> {
73
73
  const created = await stack.http.writeOk<{ id: string }>(
74
- "helpdesk:write:ticket:create",
74
+ "ticketing:write:ticket:create",
75
75
  { title },
76
76
  agent,
77
77
  );
@@ -79,7 +79,7 @@ async function openTicket(title: string): Promise<string> {
79
79
  }
80
80
 
81
81
  async function readTicket(id: string): Promise<TicketRow> {
82
- return stack.http.queryOk<TicketRow>("helpdesk:query:ticket:detail", { id }, agent);
82
+ return stack.http.queryOk<TicketRow>("ticketing:query:ticket:detail", { id }, agent);
83
83
  }
84
84
 
85
85
  describe("golden path: ticket", () => {
@@ -93,14 +93,14 @@ describe("golden path: ticket", () => {
93
93
  const id = await openTicket("Login fails");
94
94
 
95
95
  await stack.http.writeOk(
96
- "helpdesk:write:ticket:close",
96
+ "ticketing:write:ticket:close",
97
97
  { id, resolution: "Password reset" },
98
98
  admin,
99
99
  );
100
100
 
101
101
  expect(await readTicket(id)).toMatchObject({ title: "Login fails", isClosed: true });
102
102
  const list = await stack.http.queryOk<{ rows: TicketRow[] }>(
103
- "helpdesk:query:ticket:list",
103
+ "ticketing:query:ticket:list",
104
104
  { filter: { field: "isClosed", op: "eq", value: true } },
105
105
  agent,
106
106
  );
@@ -110,9 +110,9 @@ describe("golden path: ticket", () => {
110
110
  test("closing an already closed ticket is rejected with 422", async () => {
111
111
  const id = await openTicket("Duplicate close");
112
112
  const close = { id, resolution: "Fixed" };
113
- await stack.http.writeOk("helpdesk:write:ticket:close", close, admin);
113
+ await stack.http.writeOk("ticketing:write:ticket:close", close, admin);
114
114
 
115
- const again = await stack.http.writeErr("helpdesk:write:ticket:close", close, admin);
115
+ const again = await stack.http.writeErr("ticketing:write:ticket:close", close, admin);
116
116
 
117
117
  expect(again.httpStatus).toBe(422);
118
118
  expect(again.details).toEqual({ reason: "ticket_already_closed" });
@@ -122,7 +122,7 @@ describe("golden path: ticket", () => {
122
122
  const id = await openTicket("Slow wifi");
123
123
 
124
124
  const denied = await stack.http.writeErr(
125
- "helpdesk:write:ticket:close",
125
+ "ticketing:write:ticket:close",
126
126
  { id, resolution: "Moved the router" },
127
127
  agent,
128
128
  );
@@ -133,7 +133,7 @@ describe("golden path: ticket", () => {
133
133
 
134
134
  test("closing an unknown ticket fails with not_found", async () => {
135
135
  const missing = await stack.http.writeErr(
136
- "helpdesk:write:ticket:close",
136
+ "ticketing:write:ticket:close",
137
137
  { id: "99999999-9999-4999-8999-999999999999", resolution: "n/a" },
138
138
  admin,
139
139
  );
@@ -166,7 +166,7 @@ export const ticketEntity = createEntity({
166
166
  },
167
167
  });
168
168
 
169
- export const helpdeskFeature = defineFeature("helpdesk", (r) => {
169
+ export const ticketingFeature = defineFeature("ticketing", (r) => {
170
170
  const { table: ticketTable, executor: ticketExecutor } = createEntityExecutor(
171
171
  "ticket",
172
172
  ticketEntity,
@@ -1,14 +1,14 @@
1
- <!-- Generated by `bun run gen:agent-docs` from samples/recipes/contact. Do not edit. -->
1
+ <!-- Generated by `bun run gen:agent-docs` from samples/recipes/helpdesk. Do not edit. -->
2
2
 
3
- # contact
3
+ # helpdesk
4
4
 
5
- Public contact form backend: the contact bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client.
5
+ Public contact form backend: the helpdesk bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client.
6
6
 
7
7
  ## README
8
8
 
9
- # Recipe: contact
9
+ # Recipe: helpdesk
10
10
 
11
- Public contact form backend. The `contact` bundled feature stores questions, contact
11
+ Public contact form backend. The `helpdesk` bundled feature stores questions, contact
12
12
  requests and problem reports from website visitors and notifies every SystemAdmin (mail,
13
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
@@ -18,46 +18,46 @@ SystemAdmins reply from the admin. Phone is off and Telegram is not mounted unle
18
18
  turns them on (`fields.phone`, `telegram: true`).
19
19
 
20
20
  **What the recipe demonstrates:**
21
- - Mounting `createContactFeature` with its companions (delivery, user-data-rights, files)
22
- - The anonymous flow: `contact:query:challenge` hands out a proof-of-work challenge,
23
- `contact:write:submit` verifies it; spam gets the same 200 body and stores nothing
24
- - The browser client at `GET /contact/client.js` (`window.KumikoContact.load()` / `submit()`)
21
+ - Mounting `createHelpdeskFeature` with its companions (delivery, user-data-rights, files)
22
+ - The anonymous flow: `helpdesk:query:challenge` hands out a proof-of-work challenge,
23
+ `helpdesk:write:submit` verifies it; spam gets the same 200 body and stores nothing
24
+ - The browser client at `GET /helpdesk/client.js` (`window.KumikoHelpdesk.load()` / `submit()`)
25
25
 
26
26
  ## Layout
27
27
 
28
28
  ```
29
- samples/recipes/contact/
29
+ samples/recipes/helpdesk/
30
30
  ├── package.json
31
31
  ├── README.md
32
32
  └── src/
33
- ├── feature.ts # createContactFeature options
33
+ ├── feature.ts # createHelpdeskFeature options
34
34
  └── __tests__/
35
35
  └── feature.integration.test.ts # challenge query + client route
36
36
  ```
37
37
 
38
38
  The behavior (submit, silent drops, replies, Telegram, GDPR export and erasure, retention) is
39
39
  covered by the integration tests next to the feature in
40
- `packages/bundled-features/src/contact/__tests__/`.
40
+ `packages/bundled-features/src/helpdesk/__tests__/`.
41
41
 
42
42
  ## Run tests
43
43
 
44
44
  ```bash
45
- bun test --config=bunfig.integration.toml samples/recipes/contact
45
+ bun test --config=bunfig.integration.toml samples/recipes/helpdesk
46
46
  ```
47
47
 
48
48
  ## Integration into a real app
49
49
 
50
- 1. Mount `createContactFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
50
+ 1. Mount `createHelpdeskFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
51
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` 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`.
53
+ 3. SystemAdmins set `helpdesk:config:reply-to` in the admin.
54
+ 4. Embed `/helpdesk/client.js` on the website; the form is yours. A website served by another
55
+ server can serve the same script from `HELPDESK_CLIENT_SOURCE` and type its calls with
56
+ `HelpdeskWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/helpdesk/client`.
57
57
 
58
58
  Telegram is optional and off by default: notifications go by mail to SystemAdmins only. An app
59
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`.
60
+ token, and SystemAdmins set `helpdesk:config:telegram-chat`.
61
61
 
62
62
  ## Source files
63
63
 
@@ -84,7 +84,7 @@ import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
84
84
  import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
85
85
  import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
86
86
  import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
87
- import { contactFeature } from "../feature";
87
+ import { helpdeskFeature } from "../feature";
88
88
 
89
89
  let stack: TestStack;
90
90
 
@@ -108,7 +108,7 @@ beforeAll(async () => {
108
108
  createSessionsFeature(),
109
109
  createUserDataRightsFeature(),
110
110
  createNotesHistoryFeature(),
111
- contactFeature,
111
+ helpdeskFeature,
112
112
  ],
113
113
  anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
114
114
  });
@@ -118,10 +118,10 @@ afterAll(async () => {
118
118
  await stack.cleanup();
119
119
  });
120
120
 
121
- describe("contact sample", () => {
121
+ describe("helpdesk sample", () => {
122
122
  test("an anonymous visitor gets a proof-of-work challenge and the form options", async () => {
123
123
  const res = await stack.http.raw("POST", "/api/query", {
124
- type: "contact:query:challenge",
124
+ type: "helpdesk:query:challenge",
125
125
  payload: {},
126
126
  });
127
127
  expect(res.status).toBe(200);
@@ -132,10 +132,10 @@ describe("contact sample", () => {
132
132
  });
133
133
 
134
134
  test("the browser client is served as JavaScript", async () => {
135
- const res = await stack.http.raw("GET", "/contact/client.js");
135
+ const res = await stack.http.raw("GET", "/helpdesk/client.js");
136
136
  expect(res.status).toBe(200);
137
137
  expect(res.headers.get("content-type")).toContain("application/javascript");
138
- expect(await res.text()).toContain("KumikoContact");
138
+ expect(await res.text()).toContain("KumikoHelpdesk");
139
139
  });
140
140
  });
141
141
  ```
@@ -143,7 +143,7 @@ describe("contact sample", () => {
143
143
  ### src/feature.ts
144
144
 
145
145
  ```ts
146
- // Contact sample
146
+ // Helpdesk sample
147
147
  //
148
148
  // A public website form (question, contact request, problem report) that lands with the
149
149
  // SystemAdmins: mail, optional Telegram, a copy to the sender. Spam is handled without a
@@ -151,9 +151,9 @@ describe("contact sample", () => {
151
151
  // and per-email rate limits. Rejected submits answer 200 with the normal body.
152
152
  //
153
153
  // The website embeds the anonymous client the feature serves itself:
154
- // <script src="https://api.example.com/contact/client.js"></script>
155
- // const { kinds, phone } = await window.KumikoContact.load();
156
- // const result = await window.KumikoContact.submit({ kind, name, email, message, locale });
154
+ // <script src="https://api.example.com/helpdesk/client.js"></script>
155
+ // const { kinds, phone } = await window.KumikoHelpdesk.load();
156
+ // const result = await window.KumikoHelpdesk.submit({ kind, name, email, message, locale });
157
157
  // // result.kind: "sent" | "rate-limited" (retryAfterSeconds) | "failed"
158
158
  //
159
159
  // Prerequisites the app wires itself:
@@ -162,9 +162,9 @@ describe("contact sample", () => {
162
162
  // - a file provider, because the entities carry file fields
163
163
  // - `kumiko schema generate` for the new tables
164
164
 
165
- import { createContactFeature } from "@cosmicdrift/kumiko-bundled-features/contact";
165
+ import { createHelpdeskFeature } from "@cosmicdrift/kumiko-bundled-features/helpdesk";
166
166
 
167
- export const contactFeature = createContactFeature({
167
+ export const helpdeskFeature = createHelpdeskFeature({
168
168
  appName: "Sample App",
169
169
  fields: { phone: "optional" },
170
170
  // Lowered only to keep the sample test fast; the default (19 bits, 3 seconds) suits production.
@@ -9,6 +9,7 @@
9
9
  | `anonymous-access-multitenant` | Subdomain-based tenant resolution for anonymous-access — SaaS shop / CMS pattern with per-tenant public surface. | `examples/anonymous-access-multitenant.md` |
10
10
  | `apex-landing` | Apex landing page composed from other features — hero copy from template-resolver, prices and caps from tier-engine — rendered to one static HTML string. | `examples/apex-landing.md` |
11
11
  | `apex-surface-auth` | Apex-Surface: öffentliche Account-Flows (Login/Register/PW/Löschen) via createPublicSurface + AuthShell, inkl. anonymem email-verifiziertem Deletion-Flow. | `examples/apex-surface-auth.md` |
12
+ | `api-docs` | API documentation for personal access tokens: recorded examples, kumiko api-docs and a committed golden. | `examples/api-docs.md` |
12
13
  | `api-worker-split` | Split deploy topology: API process (runSingleInstance:false, enqueue-only) + worker process (consumes worker-lane jobs, applies multiStreamProjections, writes results back through the worker dispatcher). | `examples/api-worker-split.md` |
13
14
  | `app-config` | kumiko.config.ts with defineAppConfig: the one feature list, client entries and ports the tooling reads. | `examples/app-config.md` |
14
15
  | `auth-claims` | r.authClaims() — features contribute identity facts into the JWT at login time with auto-prefixed keys. | `examples/auth-claims.md` |
@@ -19,7 +20,6 @@
19
20
  | `chat-channels` | Chat channels. Delivery notifications to Slack, minus the browser tab. | `examples/chat-channels.md` |
20
21
  | `compliance-profiles-demo` | Two-tenant demo: EU + Swiss compliance profiles deliver different authority contacts, languages, and grace periods through the same App-code. | `examples/compliance-profiles-demo.md` |
21
22
  | `compose-stacks` | compose*Stack helpers for auth, security, GDPR and SaaS billing, and the runProdApp check that names a stack whose boot option is missing. | `examples/compose-stacks.md` |
22
- | `contact` | Public contact form backend: the contact bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client. | `examples/contact.md` |
23
23
  | `cross-feature-events` | Feature appends a typed domain event via ctx.events.append; a r.multiStreamProjection reacts asynchronously. | `examples/cross-feature-events.md` |
24
24
  | `crypto-shredding-hr` | Crypto-shredding: PII fields encrypted per subject key; forgetting the subject erases the key and every field it protected. | `examples/crypto-shredding-hr.md` |
25
25
  | `currencies-global` | Shared money fields across tenants. Commas still matter. | `examples/currencies-global.md` |
@@ -42,6 +42,7 @@
42
42
  | `field-access` | Field-level access control. When entity-level roles aren't granular enough. | `examples/field-access.md` |
43
43
  | `files-post-processing` | The three ways to generate an image variant: declarative field variants, imperative ctx.services.derivatives.variant() with region-blur, and the public route behind a default-deny predicate. | `examples/files-post-processing.md` |
44
44
  | `golden-path` | The smallest complete feature: entity, write handler, event, projection, screen and an integration test. | `examples/golden-path.md` |
45
+ | `helpdesk` | Public contact form backend: the helpdesk bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client. | `examples/helpdesk.md` |
45
46
  | `host-routing` | createHostRoutingFeature + createHostDispatch — tenant per subdomain, per-host HTML and CSP, locale redirect, shared by runProdApp and the dev server. | `examples/host-routing.md` |
46
47
  | `i18n` | Feature-scoped translations. 'Hallo' and 'Hello' in the same app. | `examples/i18n.md` |
47
48
  | `idempotency` | Same request, same result. Dedupes on request ID. | `examples/idempotency.md` |
@@ -48,8 +48,6 @@ One entry per feature a package ships: purpose, import of its factory, required
48
48
  `import { createComplianceProfilesOpsFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles-ops"`; requires `compliance-profiles`, `tenant`
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
- - `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`
53
51
  - `crypto-shredding`: Operator-level crypto-shredding trigger.
54
52
  `import { createCryptoShreddingFeature } from "@cosmicdrift/kumiko-bundled-features/crypto-shredding"`
55
53
  - `custom-fields`: Tenant- and system-scoped custom field definitions with generic value storage on any host entity.
@@ -90,6 +88,8 @@ One entry per feature a package ships: purpose, import of its factory, required
90
88
  `import { createFormDraftFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft"`
91
89
  - `form-draft-user-data`: GDPR (Art.
92
90
  `import { createFormDraftUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft-user-data"`; requires `user-data-rights`
91
+ - `helpdesk`: Helpdesk inbox: an anonymous browser client (GET /helpdesk/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.
92
+ `import { createHelpdeskFeature } from "@cosmicdrift/kumiko-bundled-features/helpdesk"`; requires `config`, `delivery`, `user-data-rights`, `files`, `notes-history`
93
93
  - `host-routing`: Host- and path-based tenant routing: an authoritative tenant resolver from the subdomain (tenantBy host), a tenant existence check against enabled, active tenants, and the tenant-key query behind createHostDispatch, which picks the HTML file, CSP, locale redirect or 404 per host for runProdApp's hostDispatch.
94
94
  `import { createHostRoutingFeature } from "@cosmicdrift/kumiko-bundled-features/host-routing"`; requires `auth-foundation`, `tenant`
95
95
  - `inbound-mail-foundation`: Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push) and send.
@@ -194,22 +194,6 @@ Stores per-tenant (and optionally per-user) configuration values with a multi-la
194
194
 
195
195
  Category: infrastructure
196
196
 
197
- ## contact
198
-
199
- 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. Every request is stored platform-wide and every SystemAdmin is notified by mail, optionally also in a Telegram chat (option `telegram`, off by default); the notification names only the kind, the app and a link, never name, address, phone, subject or message, because mail and Telegram cannot be shredded. SystemAdmins reply by mail (Reply-To set, attachments, quoting the original) and mark requests done; a website sender gets a fixed acknowledgement, a signed-in reporter a copy and an in-app note. Personal data is crypto-shredding-ready and the EXT_USER_DATA hooks export and erase a user's requests.
200
-
201
- Category: communication
202
-
203
- Requires: `config`, `delivery`, `user-data-rights`, `files`, `notes-history`
204
-
205
- Optional requires: `channel-telegram`
206
-
207
- Config keys:
208
-
209
- | Key | Type | Scope | Default |
210
- | --- | --- | --- | --- |
211
- | `reply-to` | text | system | `` |
212
-
213
197
  ## crypto-shredding
214
198
 
215
199
  Operator-level crypto-shredding trigger. `forget-subject` erases a user or tenant subject key in the configured KMS adapter, making every PII field encrypted under it permanently unreadable (reads render the `[[erased]]` sentinel), and appends a `subject-forgotten` audit event. Requires a KMS adapter (`runProdApp({ kms })`). The automated Art.-17 deletion pipeline in `user-data-rights` erases keys itself; this command covers manual forgets (authority requests, operator recovery, tenant destroy).
@@ -397,6 +381,22 @@ Requires: `user-data-rights`
397
381
 
398
382
  Optional requires: `form-draft`
399
383
 
384
+ ## helpdesk
385
+
386
+ Helpdesk inbox: an anonymous browser client (GET /helpdesk/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. Every request is stored platform-wide and every SystemAdmin is notified by mail, optionally also in a Telegram chat (option `telegram`, off by default); the notification names only the kind, the app and a link, never name, address, phone, subject or message, because mail and Telegram cannot be shredded. SystemAdmins reply by mail (Reply-To set, attachments, quoting the original) and mark requests done; a website sender gets a fixed acknowledgement, a signed-in reporter a copy and an in-app note. Personal data is crypto-shredding-ready and the EXT_USER_DATA hooks export and erase a user's requests.
387
+
388
+ Category: communication
389
+
390
+ Requires: `config`, `delivery`, `user-data-rights`, `files`, `notes-history`
391
+
392
+ Optional requires: `channel-telegram`
393
+
394
+ Config keys:
395
+
396
+ | Key | Type | Scope | Default |
397
+ | --- | --- | --- | --- |
398
+ | `reply-to` | text | system | `` |
399
+
400
400
  ## host-routing
401
401
 
402
402
  Host- and path-based tenant routing: an authoritative tenant resolver from the subdomain (tenantBy host), a tenant existence check against enabled, active tenants, and the tenant-key query behind createHostDispatch, which picks the HTML file, CSP, locale redirect or 404 per host for runProdApp's hostDispatch.
@@ -33,6 +33,7 @@ export type AnonymousAccessResolved = AnonymousAccessConfig & {
33
33
  readonly tenantExists?: TenantExists;
34
34
  readonly resolverTrust?: "authoritative" | "fallback-only";
35
35
  };
36
+ export type MiddlewareRejectCode = "missing_token" | "invalid_token" | "ambiguous_auth" | "session_invalid" | "tenant_required" | "tenant_not_found" | "tenant_mismatch" | "invalid_tenant_format" | "tenant_unavailable";
36
37
  export declare function identifyOptionalSession(c: Context, jwt: JwtHelper): Promise<void>;
37
38
  export declare function authMiddleware(jwt: JwtHelper, options?: AuthMiddlewareOptions): (c: Context, next: Next) => Promise<Response | undefined>;
38
39
  export declare function getUser(c: Context): SessionUser;
@@ -17,6 +17,8 @@ export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongE
17
17
  export type { JwtHelper } from "./jwt.ts";
18
18
  export { loadJwtSecretOrKeyring } from "./jwt.ts";
19
19
  export { publicOriginOf } from "./origin-middleware.ts";
20
+ export { PAT_RATE_LIMITED_CODE, patAuthRejectHttpStatus } from "./pat-auth-reject.ts";
21
+ export { patAllows, qnMatches } from "./pat-scope.ts";
20
22
  export type { PostAuthLandingArgs, PostAuthLandingResolver, } from "./post-auth-landing.ts";
21
23
  export type { RedisSseBroker } from "./redis-sse-broker.ts";
22
24
  export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.ts";
@@ -24,6 +26,7 @@ export { readonlyRequestContext as requestContext } from "./request-context-scop
24
26
  export { buildRequestContextDataFromRequest } from "./request-id-middleware.ts";
25
27
  export type { MetricsRouteOptions } from "./route-registrars.ts";
26
28
  export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.ts";
29
+ export { MAX_PAYLOAD_DEPTH } from "./routes.ts";
27
30
  export type { ServerOptions } from "./server.ts";
28
31
  export { buildServer } from "./server.ts";
29
32
  export { resolveBaseDbAndSearchAdapter } from "./server-event-dispatcher.ts";
package/dist/api/index.js CHANGED
@@ -10,10 +10,13 @@ export { ExtraRouteRejection, signatureRoute } from "./extra-route.js";
10
10
  export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongEtag, computeWeakEtag, etagMatches, } from "./http-cache.js";
11
11
  export { loadJwtSecretOrKeyring } from "./jwt.js";
12
12
  export { publicOriginOf } from "./origin-middleware.js";
13
+ export { PAT_RATE_LIMITED_CODE, patAuthRejectHttpStatus } from "./pat-auth-reject.js";
14
+ export { patAllows, qnMatches } from "./pat-scope.js";
13
15
  export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
14
16
  export { readonlyRequestContext as requestContext } from "./request-context-scopes.js";
15
17
  export { buildRequestContextDataFromRequest } from "./request-id-middleware.js";
16
18
  export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
19
+ export { MAX_PAYLOAD_DEPTH } from "./routes.js";
17
20
  export { buildServer } from "./server.js";
18
21
  export { resolveBaseDbAndSearchAdapter } from "./server-event-dispatcher.js";
19
22
  export { makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, } from "./server-extra-routes.js";
@@ -0,0 +1,7 @@
1
+ export declare const PAT_RATE_LIMITED_CODE = "pat_rate_limited";
2
+ export declare const patAuthRejectHttpStatus: {
3
+ readonly missing_token: 401;
4
+ readonly invalid_token: 401;
5
+ readonly ambiguous_auth: 400;
6
+ readonly pat_rate_limited: 429;
7
+ };
@@ -0,0 +1,7 @@
1
+ export const PAT_RATE_LIMITED_CODE = "pat_rate_limited";
2
+ export const patAuthRejectHttpStatus = {
3
+ missing_token: 401,
4
+ invalid_token: 401,
5
+ ambiguous_auth: 400,
6
+ [PAT_RATE_LIMITED_CODE]: 429,
7
+ };
@@ -6,6 +6,7 @@ import { assertSessionCallbacksPaired } from "./auth-routes.js";
6
6
  import { csrfMiddleware } from "./csrf-middleware.js";
7
7
  import { observabilityMiddleware } from "./observability-middleware.js";
8
8
  import { assertOriginGuardConfig, normalizeOrigin, resolveOriginGuard, } from "./origin-middleware.js";
9
+ import { PAT_RATE_LIMITED_CODE } from "./pat-auth-reject.js";
9
10
  import { patRouteGuard } from "./pat-route-guard.js";
10
11
  import { piiCiphertextResponseGuard } from "./pii-leak-guard.js";
11
12
  import { requestIdMiddleware } from "./request-id-middleware.js";
@@ -189,7 +190,7 @@ function buildPatRateLimitGuard(patRateLimiter) {
189
190
  if (pat && !(await patRateLimiter.check(pat.tokenId))) {
190
191
  return c.json({
191
192
  error: {
192
- code: "pat_rate_limited",
193
+ code: PAT_RATE_LIMITED_CODE,
193
194
  httpStatus: 429,
194
195
  message: "personal access token rate limit exceeded",
195
196
  i18nKey: "auth.errors.patRateLimited",
@@ -87,9 +87,9 @@ export const KUMIKO_SUB_PROCESSORS = [
87
87
  purpose: "Platform key custody (Key Manager) and Transactional Email Delivery",
88
88
  region: "EU (France)",
89
89
  dpa: "https://www.scaleway.com/en/contracts/",
90
- addedAt: "2026-09-18",
90
+ addedAt: "2026-11-01",
91
91
  appliesTo: ["all-tiers"],
92
- status: "planned",
92
+ status: "active",
93
93
  },
94
94
  ];
95
95
  /**
@@ -21,6 +21,28 @@ export type AppPorts = {
21
21
  };
22
22
  /** The boot-validator options an app owns; `env` and the cipher are injected by the runners. */
23
23
  export type AppValidateBootOptions = Pick<ValidateBootOptions, "navAllowlist" | "navAllowlistExempt" | "requiredLocales" | "requireFieldValueTranslations" | "warnOnUniqueAccessRoles">;
24
+ /** Settings of `kumiko api-docs`, the generator for the HTTP API developer docs. */
25
+ export type AppApiDocsConfig = {
26
+ /** Locales of the generated pages; default en. */
27
+ readonly locales?: readonly string[];
28
+ readonly outDir?: string;
29
+ /** Host that the curl examples and the OpenAPI `servers` entry point to. */
30
+ readonly baseUrl?: string;
31
+ readonly appName?: string;
32
+ /** One paragraph per locale, appended to the tokens page (plan or tier limits). */
33
+ readonly planNote?: Readonly<Record<string, string>>;
34
+ /** One text per locale for the delivery section of the events page: signature, timeouts, retries. Required for every requested locale once an event is public. */
35
+ readonly webhookDelivery?: Readonly<Record<string, string>>;
36
+ /** Writes triggered by screens that are deliberately not reachable with an API token. `pattern` is a QN or a glob ending in `*`. */
37
+ readonly uiOnlyWrites?: readonly {
38
+ readonly pattern: string;
39
+ readonly reason: string;
40
+ }[];
41
+ /** Paragraph overrides per locale and text key; the page structure stays fixed. */
42
+ readonly texts?: Readonly<Record<string, Readonly<Record<string, string>>>>;
43
+ /** Directory of recorded request/response examples; default `api-examples`. */
44
+ readonly examplesDir?: string;
45
+ };
24
46
  export type AppConfig = {
25
47
  /** Features mounted in every environment: dev, tests, prod. */
26
48
  readonly features: readonly FeatureDefinition[];
@@ -38,6 +60,7 @@ export type AppConfig = {
38
60
  readonly bundledLists?: BundledListsOptions;
39
61
  /** "on" enforces tenant isolation in Postgres via row level security; schema tooling and every runner read this one value. Default "on". */
40
62
  readonly rowLevelSecurity?: RowLevelSecurityMode;
63
+ readonly apiDocs?: AppApiDocsConfig;
41
64
  };
42
65
  export declare const APP_CONFIG_FILE = "kumiko.config.ts";
43
66
  declare const INFRA_PORT_NAMES: readonly ["postgres", "redis", "meilisearch", "s3"];
@@ -46,6 +69,8 @@ export type AppPortRole = "dev" | "e2e" | (typeof INFRA_PORT_NAMES)[number];
46
69
  export declare function listAppPorts(ports: AppPorts): readonly AppPortEntry[];
47
70
  /** Problems with the declared ports: out of range or claimed twice by this app. */
48
71
  export declare function findAppPortProblems(ports: AppPorts): readonly string[];
72
+ /** Problems with the declared `apiDocs` block: empty or duplicate locales, a `uiOnlyWrites` entry without reason. */
73
+ export declare function findApiDocsConfigProblems(apiDocs: AppApiDocsConfig): readonly string[];
49
74
  export declare function defineAppConfig(config: AppConfig): AppConfig;
50
75
  /**
51
76
  * Raw `features` plus `prodFeatures`, without the bundled foundation: the runners compose it,
@@ -46,8 +46,35 @@ export function findAppPortProblems(ports) {
46
46
  // Entries end up in the server's bundle list and in generated files, so only
47
47
  // plain relative paths inside the app are accepted.
48
48
  const CLIENT_ENTRY_RE = /^(?!\/)(?!.*\.\.)[A-Za-z0-9_./-]+\.(ts|tsx)$/;
49
+ /** Problems with the declared `apiDocs` block: empty or duplicate locales, a `uiOnlyWrites` entry without reason. */
50
+ export function findApiDocsConfigProblems(apiDocs) {
51
+ const problems = [];
52
+ const { locales, uiOnlyWrites } = apiDocs;
53
+ if (locales !== undefined) {
54
+ if (locales.length === 0)
55
+ problems.push("apiDocs.locales must not be empty");
56
+ if (new Set(locales).size !== locales.length) {
57
+ problems.push("apiDocs.locales must not contain duplicates");
58
+ }
59
+ }
60
+ for (const [locale, text] of Object.entries(apiDocs.webhookDelivery ?? {})) {
61
+ if (text.trim() === "")
62
+ problems.push(`apiDocs.webhookDelivery: "${locale}" text must not be empty`);
63
+ }
64
+ for (const entry of uiOnlyWrites ?? []) {
65
+ if (entry.pattern.trim() === "")
66
+ problems.push("apiDocs.uiOnlyWrites: pattern must not be empty");
67
+ if (entry.reason.trim() === "") {
68
+ problems.push(`apiDocs.uiOnlyWrites: "${entry.pattern}" needs a non-empty reason`);
69
+ }
70
+ }
71
+ return problems;
72
+ }
49
73
  export function defineAppConfig(config) {
50
- const problems = [...findAppPortProblems(config.ports)];
74
+ const problems = [
75
+ ...findAppPortProblems(config.ports),
76
+ ...(config.apiDocs ? findApiDocsConfigProblems(config.apiDocs) : []),
77
+ ];
51
78
  if (config.client.entries.length === 0)
52
79
  problems.push("client.entries must name at least one entry");
53
80
  for (const entry of config.client.entries) {
@@ -2,6 +2,7 @@ import type { DbRunner } from "./connection.ts";
2
2
  import type { Table } from "./event-store-executor-context.ts";
3
3
  import type { ListWhere } from "./event-store-executor-read-filter.ts";
4
4
  import { type ListSort } from "./event-store-executor-read-sort.ts";
5
+ export declare const DEFAULT_LIST_LIMIT = 50;
5
6
  export declare function resolveListPagination(payload: {
6
7
  readonly limit?: unknown;
7
8
  readonly offset?: unknown;
@@ -8,8 +8,9 @@ import { physicalColumnName } from "./table-builder.js";
8
8
  // handlers that pass their payload straight through — a non-integer limit
9
9
  // would otherwise be interpolated raw into `LIMIT ${limit}` SQL text.
10
10
  const MAX_LIST_LIMIT = 200; // keep in sync with engine/entity-handlers.ts MAX_LIST_LIMIT
11
+ export const DEFAULT_LIST_LIMIT = 50;
11
12
  export function resolveListPagination(payload) {
12
- const limit = payload.limit ?? 50;
13
+ const limit = payload.limit ?? DEFAULT_LIST_LIMIT;
13
14
  const offset = payload.offset ?? 0;
14
15
  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 0) {
15
16
  throw new UnprocessableError("invalid_list_limit", {
@@ -77,12 +77,25 @@ function linkClause(input, link, mode) {
77
77
  }
78
78
  return { kind: "sql", sqlText, params: sql.params };
79
79
  }
80
- // Every registered entity with a file field can own a file. Join rows and gated entities
81
- // are left out: their readability is not resolvable without recursion.
80
+ function hasRowReadRule(entity) {
81
+ return Object.keys(entity.access?.read ?? {}).length > 0;
82
+ }
83
+ // A read model is served by hand-written queries that filter rows themselves; only its own
84
+ // access.read can be reproduced here, so without one every role of its detail query would read every row.
85
+ function ownerSources(option) {
86
+ const sources = [...option.entities].map(([name, entity]) => ({ name, entity }));
87
+ for (const [name, { entity, table }] of option.readModelEntities ?? []) {
88
+ if (!option.entities.has(name) && hasRowReadRule(entity)) {
89
+ sources.push({ name, entity, projectionTable: table });
90
+ }
91
+ }
92
+ return sources;
93
+ }
94
+ // Join rows and gated entities are left out: their readability is not resolvable without recursion.
82
95
  function ownerCandidates(input, selfName) {
83
96
  const { option } = input;
84
97
  const owners = [];
85
- for (const [name, entity] of option.entities) {
98
+ for (const { name, entity, projectionTable } of ownerSources(option)) {
86
99
  if (name === FILE_REF_ENTITY_NAME || name === selfName)
87
100
  continue;
88
101
  if (entity.parentRef !== undefined || entity.readGate !== undefined)
@@ -94,14 +107,20 @@ function ownerCandidates(input, selfName) {
94
107
  const fileFields = Object.entries(entity.fields)
95
108
  .filter(([, field]) => isFileField(field))
96
109
  .map(([fieldName]) => fieldName);
97
- if (fileFields.length > 0)
98
- owners.push({ name, entity, fileFields });
110
+ if (fileFields.length === 0)
111
+ continue;
112
+ owners.push({
113
+ name,
114
+ entity,
115
+ table: projectionTable ?? tableOf(option, name, entity),
116
+ fileFields,
117
+ });
99
118
  }
100
119
  return owners;
101
120
  }
102
121
  function ownerBranch(input, owner, refTable, sql) {
103
- const { option, user, db } = input;
104
- const ownerTable = tableOf(option, owner.name, owner.entity);
122
+ const { user, db } = input;
123
+ const ownerTable = owner.table;
105
124
  const ownerTableName = String(schemaTableName(ownerTable));
106
125
  const ownership = buildOwnershipClause(user, owner.entity.access?.read, ownerTable, 1, ownerTableName);
107
126
  if (ownership.kind === "empty")
@@ -2,13 +2,12 @@
2
2
  import type { EntityDefinition, FieldDefinition, FieldsMap } from "@cosmicdrift/kumiko-types/fields";
3
3
  import type { EntityRelations } from "@cosmicdrift/kumiko-types/relations";
4
4
  import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
5
- import type { Table } from "./event-store-executor-context.ts";
6
5
  import type { LocatedTimestampRead } from "./located-timestamp.ts";
7
6
  import type { MoneyRead } from "./money.ts";
8
7
  export { toSnakeCase } from "../utils/case.ts";
9
8
  import { type ColumnBuilder, type ColumnHandle, type SchemaTable, type TableColumns } from "./dialect.ts";
10
9
  export { SOFT_DELETE_LIVE_ROW_PREDICATE } from "./entity-table-indexes.ts";
11
- export declare function physicalColumnName(table: Table, field: string): string;
10
+ export declare function physicalColumnName(table: unknown, field: string): string;
12
11
  export type AnyPgColumn = ColumnHandle;
13
12
  export declare const READ_MODEL_PREFIX = "read_";
14
13
  export declare function toTableName(entityName: string): string;
@@ -1,3 +1,6 @@
1
+ import { type BootViolation } from "./boot-rule.ts";
2
+ export declare function isRuntimeCrash(thrown: unknown): boolean;
3
+ export declare function violationsOf(failure: Error, checkName: string, feature: string | undefined): readonly BootViolation[];
1
4
  export type BootReport = {
2
5
  check(checkName: string, feature: string | undefined, fn: () => unknown): boolean;
3
6
  endPhase(): void;
@@ -1,7 +1,7 @@
1
1
  import { BootRuleFailures, BootRuleViolation, BootValidationError, } from "./boot-rule.js";
2
2
  // A runtime crash is a bug in a validator (or in the input it assumed), not a
3
3
  // rule violation: it must surface as itself instead of masquerading as a finding.
4
- function isRuntimeCrash(thrown) {
4
+ export function isRuntimeCrash(thrown) {
5
5
  return (!(thrown instanceof Error) ||
6
6
  thrown instanceof TypeError ||
7
7
  thrown instanceof RangeError ||
@@ -10,7 +10,7 @@ function isRuntimeCrash(thrown) {
10
10
  thrown instanceof EvalError ||
11
11
  thrown instanceof URIError);
12
12
  }
13
- function violationsOf(failure, checkName, feature) {
13
+ export function violationsOf(failure, checkName, feature) {
14
14
  if (failure instanceof BootRuleFailures) {
15
15
  return failure.failures.flatMap((nested) => violationsOf(nested, checkName, feature));
16
16
  }