@cosmicdrift/kumiko-framework 0.415.0 → 0.416.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 (64) hide show
  1. package/agents/api/framework-engine.md +37 -5
  2. package/agents/api/framework-ui-types.md +59 -3
  3. package/agents/api/renderer-web.md +7 -1
  4. package/agents/api/types.md +21 -2
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +33 -3
  7. package/agents/examples/embedded.md +24 -1
  8. package/agents/examples/handbook-knowledge.md +129 -0
  9. package/agents/examples/signature.md +186 -0
  10. package/agents/examples/writeform-section.md +1 -0
  11. package/agents/examples.md +2 -0
  12. package/agents/features-index.md +4 -0
  13. package/agents/features.md +14 -0
  14. package/dist/api/server-routes.js +2 -0
  15. package/dist/db/table-builder.js +3 -1
  16. package/dist/engine/boot-validator/boot-phases.js +5 -0
  17. package/dist/engine/boot-validator/boot-rules.d.ts +129 -4
  18. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  19. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  20. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  21. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  22. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +16 -1
  23. package/dist/engine/boot-validator/list-row-guidance-rules.js +16 -1
  24. package/dist/engine/boot-validator/list-row-guidance.d.ts +7 -0
  25. package/dist/engine/boot-validator/list-row-guidance.js +30 -0
  26. package/dist/engine/boot-validator/query-output-columns.js +18 -0
  27. package/dist/engine/boot-validator/query-output-guidance.js +2 -0
  28. package/dist/engine/boot-validator/query-refs.js +4 -1
  29. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  30. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  31. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  32. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  33. package/dist/engine/boot-validator/screens-actions.js +55 -15
  34. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  35. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  36. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  37. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  38. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  39. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  40. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  41. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  42. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  43. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  44. package/dist/engine/boot-validator/screens-forms.js +108 -2
  45. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  46. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  47. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  48. package/dist/engine/boot-validator/screens-kind-projection-detail.js +30 -0
  49. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  50. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  51. package/dist/engine/boot-validator/screens-lists.js +4 -1
  52. package/dist/engine/build-config-feature-schema.js +5 -35
  53. package/dist/engine/config-access-rules.d.ts +3 -0
  54. package/dist/engine/config-access-rules.js +34 -0
  55. package/dist/engine/factories.d.ts +2 -0
  56. package/dist/engine/project-app-schema-for-roles.js +2 -0
  57. package/dist/files/file-routes.d.ts +2 -0
  58. package/dist/files/file-routes.js +85 -22
  59. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  60. package/dist/files/foreign-tenant-file-read.js +64 -0
  61. package/dist/i18n/required-surface-keys.js +26 -6
  62. package/dist/ui-types/index.d.ts +1 -1
  63. package/package.json +3 -3
  64. package/src/changes.json +42 -0
@@ -14,6 +14,11 @@ export const PROJECTION_DETAIL_RULES = {
14
14
  summary: "A projectionDetail with a header sets no recordTitleField.",
15
15
  fix: "Drop recordTitleField; header.title names the record.",
16
16
  },
17
+ initialTabInvalid: {
18
+ id: "projection-detail/initial-tab-invalid",
19
+ summary: "initialTab needs layout.mode tabs and each rule names an existing section id; footerHint needs footerActions.",
20
+ fix: "Use tabs mode and section ids from the layout for initialTab, or declare footerActions next to footerHint.",
21
+ },
17
22
  tabsSectionGroupsAndActions: {
18
23
  id: "projection-detail/tabs-section-groups-and-actions",
19
24
  summary: "A tabs-mode section declares groups or actions, not both.",
@@ -1,6 +1,7 @@
1
1
  import { SELECT_OPTION_TONES } from "@cosmicdrift/kumiko-types/fields";
2
2
  import { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
3
3
  import { bootRuleError } from "./boot-rule.js";
4
+ import { validateRelativeTimeFormat } from "./relative-time-format.js";
4
5
  import { assertWriteHandlerRegistered, resolveRowActionNavigateTarget, validateActionHasIcon, validatePrimaryActionTarget, } from "./screens-actions.js";
5
6
  import { rejectWriteOnlyFormField, validateFieldsXorGroups, validateFormSelectOptions, validateTabSections, } from "./screens-forms.js";
6
7
  import { validateProjectionDetailGuidance } from "./screens-kind-projection-detail-guidance.js";
@@ -51,6 +52,29 @@ function validateProjectionDetailTabs(featureName, screenId, screen) {
51
52
  }
52
53
  }
53
54
  }
55
+ function validateProjectionDetailInitialTab(featureName, screenId, screen) {
56
+ const where = `[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`;
57
+ if (screen.footerHint !== undefined && (screen.footerActions ?? []).length === 0) {
58
+ throw bootRuleError(PROJECTION_DETAIL_RULES.initialTabInvalid, {
59
+ message: `${where} sets footerHint without footerActions — the footer bar only exists with footer actions.`,
60
+ });
61
+ }
62
+ // skip: the first tab opens first
63
+ if (screen.initialTab === undefined)
64
+ return;
65
+ if (screen.layout.mode !== "tabs") {
66
+ throw bootRuleError(PROJECTION_DETAIL_RULES.initialTabInvalid, {
67
+ message: `${where} sets initialTab without layout.mode "tabs".`,
68
+ });
69
+ }
70
+ for (const rule of screen.initialTab) {
71
+ if (!screen.layout.sections.some((section) => section.id === rule.tab)) {
72
+ throw bootRuleError(PROJECTION_DETAIL_RULES.initialTabInvalid, {
73
+ message: `${where} initialTab names tab "${rule.tab}", which is not a section id on this screen.`,
74
+ });
75
+ }
76
+ }
77
+ }
54
78
  function validateProjectionDetailMetricNavigate(ctx, screenId, screen, field, navigate) {
55
79
  const featureName = ctx.feature.name;
56
80
  if (navigate.screen === undefined && navigate.entity === undefined) {
@@ -77,6 +101,7 @@ function validateProjectionDetailMetric(ctx, screenId, screen, metric) {
77
101
  `there is no fallback to the raw column name.`,
78
102
  });
79
103
  }
104
+ validateRelativeTimeFormat(`[Feature ${ctx.feature.name}] Screen "${screenId}" (projectionDetail)`, `metric "${metric.field}"`, metric.format);
80
105
  if (metric.navigate !== undefined) {
81
106
  validateProjectionDetailMetricNavigate(ctx, screenId, screen, metric.field, metric.navigate);
82
107
  }
@@ -252,6 +277,10 @@ function validateProjectionDetailSection(ctx, screenId, screen, section) {
252
277
  else if (isWriteFormEditSection(section)) {
253
278
  validateProjectionDetailWriteForm(ctx, screenId, screen, section);
254
279
  }
280
+ else if (section.kind === "stepList") {
281
+ // field existence is checked against the outputSchema in query-output-columns
282
+ return;
283
+ }
255
284
  else {
256
285
  validateProjectionDetailFieldsSection(ctx, screenId, section);
257
286
  }
@@ -283,6 +312,7 @@ export function validateProjectionDetailScreen(ctx, screenId, screen) {
283
312
  validateProjectionDetailFlags(featureName, screenId, screen);
284
313
  rejectEmptySections(featureName, screenId, "projectionDetail", screen.layout.sections.length);
285
314
  validateProjectionDetailTabs(featureName, screenId, screen);
315
+ validateProjectionDetailInitialTab(featureName, screenId, screen);
286
316
  for (const metric of screen.metrics ?? []) {
287
317
  validateProjectionDetailMetric(ctx, screenId, screen, metric);
288
318
  }
@@ -44,6 +44,11 @@ export declare const LIST_SCREEN_RULES: {
44
44
  readonly summary: "A column renderer's react.__component is a non-empty string.";
45
45
  readonly fix: "Set react.__component to the name of a client columnRenderers entry.";
46
46
  };
47
+ readonly relativeTimeOptionsInvalid: {
48
+ readonly id: "list/relative-time-options-invalid";
49
+ readonly summary: "relativeTime format options (style, absoluteAfterDays, withTime, timeZone) are valid.";
50
+ readonly fix: "Use style long, short or narrow, an integer absoluteAfterDays of at least 1 and a boolean withTime and an IANA timeZone.";
51
+ };
47
52
  readonly enumOptionTonesInvalid: {
48
53
  readonly id: "list/enum-option-tones-invalid";
49
54
  readonly summary: "enumOption column tones are known select option tones.";
@@ -44,6 +44,11 @@ export const LIST_SCREEN_RULES = {
44
44
  summary: "A column renderer's react.__component is a non-empty string.",
45
45
  fix: "Set react.__component to the name of a client columnRenderers entry.",
46
46
  },
47
+ relativeTimeOptionsInvalid: {
48
+ id: "list/relative-time-options-invalid",
49
+ summary: "relativeTime format options (style, absoluteAfterDays, withTime, timeZone) are valid.",
50
+ fix: "Use style long, short or narrow, an integer absoluteAfterDays of at least 1 and a boolean withTime and an IANA timeZone.",
51
+ },
47
52
  enumOptionTonesInvalid: {
48
53
  id: "list/enum-option-tones-invalid",
49
54
  summary: "enumOption column tones are known select option tones.",
@@ -7,11 +7,12 @@ import { explicitListScreenId, normalizeListColumn, resolveNavParentScreen, scre
7
7
  import { bootRuleError } from "./boot-rule.js";
8
8
  import { ENTITY_LIST_RULES } from "./entity-list-screens-rules.js";
9
9
  import { validateListBulkActions } from "./list-bulk-actions.js";
10
- import { validateListRowGuidance } from "./list-row-guidance.js";
10
+ import { validateListRowGuidance, validatePhotoGrid } from "./list-row-guidance.js";
11
11
  import { LIST_ROW_GUIDANCE_RULES } from "./list-row-guidance-rules.js";
12
12
  import { rejectSummaryRowOnRelatedList } from "./list-sort-summary.js";
13
13
  import { validateListTableOptions } from "./list-table-options.js";
14
14
  import { validateRelatedListGroupingRules } from "./related-list-table-rules.js";
15
+ import { validateRelativeTimeFormat } from "./relative-time-format.js";
15
16
  import { assertWriteHandlerRegistered, isRowClickAction, rejectRedirectOnListRowAction, resolveRowActionNavigateTarget, validateClientActionName, validateDrawerTargetAction, validateRowActionNavigateParams, } from "./screens-actions.js";
16
17
  import { SCREEN_ACTION_RULES } from "./screens-actions-rules.js";
17
18
  import { SCREEN_KIND_RULES } from "./screens-kind-rules.js";
@@ -94,6 +95,7 @@ function validateRelatedListTableAndBulk(args) {
94
95
  // swallow a summaryRow with a less specific message.
95
96
  rejectSummaryRowOnRelatedList(`[Feature ${featureName}] ${where}`, section.table);
96
97
  validateRelatedListGroupingRules(`[Feature ${featureName}] ${where}`, section, args.screenType === "entityList expandableRow");
98
+ validatePhotoGrid(`[Feature ${featureName}] ${where}`, section);
97
99
  validateListTableOptions(`[Feature ${featureName}] ${where}`, section.table, section.columns);
98
100
  if (section.rowActions !== undefined)
99
101
  validateRelatedListRowActions(args, section.rowActions);
@@ -278,6 +280,7 @@ export function rejectInertColumnSortable(featureName, screenId, screenType, col
278
280
  // failure.
279
281
  export function validateColumnRendererForm(featureName, screenId, column) {
280
282
  validateEnumOptionTones(`[Feature ${featureName}] Screen "${screenId}"`, column);
283
+ validateRelativeTimeFormat(`[Feature ${featureName}] Screen "${screenId}"`, `column "${column.field}"`, column.renderer);
281
284
  if (column.linkParamsField !== undefined && column.linkScreenField === undefined) {
282
285
  throw bootRuleError(LIST_ROW_GUIDANCE_RULES.linkParamsWithoutScreenField, {
283
286
  message: `[Feature ${featureName}] Screen "${screenId}" column "${column.field}" sets linkParamsField ` +
@@ -16,12 +16,12 @@
16
16
  // refs (buildNavRegistrySliceForApp qualifies them itself).
17
17
  import { isOptionsQueryFieldRef } from "@cosmicdrift/kumiko-types/fields";
18
18
  import { CONFIG_EDIT_ENTITY, fieldLabelKey } from "../i18n/required-surface-keys.js";
19
+ import { rolesToAccess, unionAccessRules } from "./config-access-rules.js";
19
20
  import { isEncryptedAtRest } from "./config-helpers.js";
20
21
  import { EXTENSION_SELECTOR_HINT_KEY, isSelectableInSettings, settingsSelectablePluginIds, } from "./extension-selector-plugins.js";
21
22
  import { createBooleanField, createNumberField, createSelectField, createTextField, } from "./factories.js";
22
23
  import { isKebabSegment, toKebab } from "./qualified-name.js";
23
24
  import { isFieldsEditSection, sectionFieldSpecs, } from "./screen-helpers.js";
24
- import { isOpenToAllGranted } from "./types/handlers.js";
25
25
  // Namespace under which buildAppSchema attaches the generated screens/navs
26
26
  // (find-or-create FeatureSchema). It MUST match CONFIG_FEATURE from the config
27
27
  // bundled feature. The framework cannot import that constant because of the
@@ -681,7 +681,7 @@ function buildScreen(shortId, scope, feature, keys, access, hub, options = {}) {
681
681
  if (k.def.required === true)
682
682
  requiredFields.push(id);
683
683
  }
684
- const { section, screenDescription } = buildSettingsSection(feature, scope, keys.map(fieldId), hub, options);
684
+ const { section, screenDescription } = buildSettingsSection(feature, scope, keys.map((k) => k.def.mask?.readOnly === true ? { field: fieldId(k), readOnly: true } : fieldId(k)), hub, options);
685
685
  return {
686
686
  id: shortId,
687
687
  type: "configEdit",
@@ -809,6 +809,9 @@ function collectMaskedKeys(registry) {
809
809
  if (def.group !== undefined && !isKebabSegment(def.group)) {
810
810
  throw new Error(`[Feature ${ownerFeature}] config key "${qn.slice(sep + ":config:".length)}" has invalid group "${def.group}" — must be kebab-case.`);
811
811
  }
812
+ if (def.mask?.readOnly === true && def.required === true) {
813
+ throw new Error(`[Feature ${ownerFeature}] config key "${qn.slice(sep + ":config:".length)}" is mask.readOnly and required — nobody could fill it.`);
814
+ }
812
815
  // computed keys derive their value — there is no row to set, so a
813
816
  // configEdit screen could not write them. Skip even when masked.
814
817
  if (def.mask === undefined || def.computed !== undefined)
@@ -835,36 +838,3 @@ function maskOrder(k) {
835
838
  function minMaskOrder(keys) {
836
839
  return Math.min(...keys.map(maskOrder));
837
840
  }
838
- // The hub is for editing: anyone allowed to WRITE at least one key in the group
839
- // sees the Settings entry (write, not read). This keeps system-scope (write
840
- // default `["system"]`) hidden from humans until the author opts in with
841
- // write: SystemAdmin, while user-scope (write `all`) is shown to everyone.
842
- // `all` can only be represented as openToAll in AccessRule; writes remain
843
- // gated per key on the server.
844
- // Access rules for navs are unioned: an openToAll nav opens the whole gate;
845
- // otherwise roles are combined. Navs without access rules contribute nothing.
846
- function unionAccessRules(rules) {
847
- const roles = [];
848
- for (const rule of rules) {
849
- if (rule === undefined)
850
- continue;
851
- if ("openToAll" in rule) {
852
- if (isOpenToAllGranted(rule))
853
- return rule;
854
- continue;
855
- }
856
- roles.push(...rule.roles);
857
- }
858
- return rolesToAccess(roles);
859
- }
860
- // `all` can only be represented as openToAll in AccessRule; writes remain gated
861
- // per key on the server.
862
- function rolesToAccess(roles) {
863
- if (roles.includes("all"))
864
- return {
865
- openToAll: {
866
- reason: 'config key declares the "all" role, so every signed-in user of the tenant may read/write it',
867
- },
868
- };
869
- return { roles: [...new Set(roles)] };
870
- }
@@ -0,0 +1,3 @@
1
+ import type { AccessRule } from "./types/handlers.ts";
2
+ export declare function unionAccessRules(rules: readonly (AccessRule | undefined)[]): AccessRule;
3
+ export declare function rolesToAccess(roles: readonly string[]): AccessRule;
@@ -0,0 +1,34 @@
1
+ import { isOpenToAllGranted } from "./types/handlers.js";
2
+ // The hub is for editing: anyone allowed to WRITE at least one key in the group
3
+ // sees the Settings entry (write, not read). This keeps system-scope (write
4
+ // default `["system"]`) hidden from humans until the author opts in with
5
+ // write: SystemAdmin, while user-scope (write `all`) is shown to everyone.
6
+ // `all` can only be represented as openToAll in AccessRule; writes remain
7
+ // gated per key on the server.
8
+ // Access rules for navs are unioned: an openToAll nav opens the whole gate;
9
+ // otherwise roles are combined. Navs without access rules contribute nothing.
10
+ export function unionAccessRules(rules) {
11
+ const roles = [];
12
+ for (const rule of rules) {
13
+ if (rule === undefined)
14
+ continue;
15
+ if ("openToAll" in rule) {
16
+ if (isOpenToAllGranted(rule))
17
+ return rule;
18
+ continue;
19
+ }
20
+ roles.push(...rule.roles);
21
+ }
22
+ return rolesToAccess(roles);
23
+ }
24
+ // `all` can only be represented as openToAll in AccessRule; writes remain gated
25
+ // per key on the server.
26
+ export function rolesToAccess(roles) {
27
+ if (roles.includes("all"))
28
+ return {
29
+ openToAll: {
30
+ reason: 'config key declares the "all" role, so every signed-in user of the tenant may read/write it',
31
+ },
32
+ };
33
+ return { roles: [...new Set(roles)] };
34
+ }
@@ -219,4 +219,6 @@ export declare function createEntity<const F, const T extends EntityTenancy = "t
219
219
  readonly transferable?: boolean;
220
220
  /** See EntityDefinition.attachedFileAccess. */
221
221
  readonly attachedFileAccess?: EntityDefinition["attachedFileAccess"];
222
+ /** See EntityDefinition.crossTenantFileRead. */
223
+ readonly crossTenantFileRead?: EntityDefinition["crossTenantFileRead"];
222
224
  }): F extends FieldsMap ? EntityDefinition<F, T> : never;
@@ -324,6 +324,8 @@ function projectEditSection(section, feature, indices, keptScreenQns) {
324
324
  switch (section.kind) {
325
325
  case "relatedList":
326
326
  return projectRelatedListSection(section, feature, indices, keptScreenQns);
327
+ case "stepList":
328
+ return section;
327
329
  case "extension": {
328
330
  const { actions, ...rest } = section;
329
331
  const kept = projectActionArray(actions, feature, indices, keptScreenQns);
@@ -4,6 +4,7 @@ import { Hono } from "hono";
4
4
  import { type ClientIpResolver } from "../api/client-ip.ts";
5
5
  import type { DbConnection } from "../db/connection.ts";
6
6
  import { type Registry, type SessionUser, type TenantId } from "../engine/types/index.ts";
7
+ import { type ForeignTenantFileReadCheck } from "./foreign-tenant-file-read.ts";
7
8
  import type { FileProviderResolver } from "./provider-resolver.ts";
8
9
  import type { RecordReadCheck } from "./record-read-check.ts";
9
10
  import { type RecordWriteCheck } from "./record-write-check.ts";
@@ -41,6 +42,7 @@ export type FileRoutesOptions = {
41
42
  readonly unclaimedUploadReaders?: readonly string[];
42
43
  readonly accessGuard?: FileAccessGuard;
43
44
  readonly canReadRecord?: RecordReadCheck;
45
+ readonly canReadForeignTenantFile?: ForeignTenantFileReadCheck;
44
46
  readonly canWriteRecord?: RecordWriteCheck;
45
47
  };
46
48
  export declare const ANONYMOUS_UPLOADS_PER_WINDOW = 20;
@@ -25,6 +25,7 @@ import { isFileSubField } from "./file-field-slots.js";
25
25
  import { createFileContext, createTenantFileContext } from "./file-handle.js";
26
26
  import { fileRefEntity } from "./file-ref-entity.js";
27
27
  import { fileRefsTable } from "./file-ref-table.js";
28
+ import { collectCrossTenantFileReadQueries, foreignTenantFileReadDb, } from "./foreign-tenant-file-read.js";
28
29
  import { collectRecordOnlyFileEntityTypes } from "./record-only-file-entity-types.js";
29
30
  import { isStoredRecordLocked, RecordWriteDecisions, } from "./record-write-check.js";
30
31
  import { neutralFileNameForMimeType } from "./resolve-content-type.js";
@@ -117,6 +118,10 @@ export function createFileRoutes(options) {
117
118
  // Anonymous visitors share one user id and own no file by it; the check precedes an app's
118
119
  // accessGuard so a custom guard cannot reopen reads or deletes between visitors.
119
120
  const guard = (args) => isAnonymousSessionUser(args.user) ? "deny" : configuredGuard(args);
121
+ const crossTenantFileReadQueries = options.registry
122
+ ? collectCrossTenantFileReadQueries(options.registry)
123
+ : new Map();
124
+ const canReadForeignTenantFile = crossTenantFileReadQueries.size > 0 ? options.canReadForeignTenantFile : undefined;
120
125
  const executor = getFileRefExecutor();
121
126
  const piiSubjectFields = collectPiiSubjectFields(fileRefEntity);
122
127
  const api = new Hono();
@@ -365,10 +370,11 @@ export function createFileRoutes(options) {
365
370
  api.get("/files/:id", async (c) => {
366
371
  const user = getUser(c);
367
372
  const id = c.req.param("id");
368
- const fileRef = await loadReadableFileRef(id, user);
369
- if (!fileRef)
373
+ const readable = await loadReadableFile(id, user);
374
+ if (!readable)
370
375
  return c.json({ error: "not_found" }, 404);
371
- const decision = await guard({ fileRef, user, operation: "read" });
376
+ const { fileRef } = readable;
377
+ const decision = await readDecisionFor(readable, user);
372
378
  if (decision === "deny") {
373
379
  // 404 rather than 403 so the existence of the file isn't confirmed to
374
380
  // an unauthorised caller — matches the tenant-miss response.
@@ -400,10 +406,11 @@ export function createFileRoutes(options) {
400
406
  const user = getUser(c);
401
407
  const id = c.req.param("id");
402
408
  const name = c.req.param("name");
403
- const fileRef = await loadFileForTenant(id, user.tenantId);
404
- if (!fileRef)
409
+ const readable = await loadOwnOrForeignFile(id, user);
410
+ if (!readable)
405
411
  return c.json({ error: "not_found" }, 404);
406
- const decision = await guard({ fileRef, user, operation: "read" });
412
+ const { fileRef } = readable;
413
+ const decision = await readDecisionFor(readable, user);
407
414
  if (decision === "deny")
408
415
  return c.json({ error: "not_found" }, 404);
409
416
  // An unknown name and a denied file answer alike, so the route never
@@ -425,12 +432,12 @@ export function createFileRoutes(options) {
425
432
  }
426
433
  // Built per request: createFileContext caches the resolved provider, so
427
434
  // one shared across requests would serve tenant A's store to tenant B.
428
- const files = createFileContext(() => options.resolveProvider(user.tenantId), user.tenantId);
435
+ const files = createFileContext(() => options.resolveProvider(fileRef.tenantId), fileRef.tenantId);
429
436
  const derivatives = createDerivativesContext({
430
437
  files,
431
438
  registry,
432
- db,
433
- tenantId: user.tenantId,
439
+ db: readable.foreign ? foreignTenantFileReadDb(db) : db,
440
+ tenantId: fileRef.tenantId,
434
441
  });
435
442
  const result = await derivatives.variant(id, spec, name);
436
443
  const data = await files.refFromFileRef(result).read();
@@ -493,10 +500,11 @@ export function createFileRoutes(options) {
493
500
  api.get("/files/:id/download-url", async (c) => {
494
501
  const user = getUser(c);
495
502
  const id = c.req.param("id");
496
- const fileRef = await loadReadableFileRef(id, user);
497
- if (!fileRef)
503
+ const readable = await loadReadableFile(id, user);
504
+ if (!readable)
498
505
  return c.json({ error: "not_found" }, 404);
499
- const decision = await guard({ fileRef, user, operation: "read" });
506
+ const { fileRef } = readable;
507
+ const decision = await readDecisionFor(readable, user);
500
508
  if (decision === "deny")
501
509
  return c.json({ error: "not_found" }, 404);
502
510
  // Resolve after access-check: tenant-scoped provider, and capability
@@ -538,8 +546,8 @@ export function createFileRoutes(options) {
538
546
  ? await executor.detail({ id }, user, tenantDbFor(SYSTEM_TENANT_ID))
539
547
  : null);
540
548
  if (!row)
541
- return null;
542
- const fileRef = row; // @cast-boundary db-row (decrypted via executor.detail)
549
+ return loadForeignFileMeta(id, user);
550
+ const fileRef = fileRefOfRow(row);
543
551
  // detail()'s "pass"-ownership read widens to tenantId IN (self, SYSTEM),
544
552
  // narrower in loadFileForTenant's selectMany. Restore that here so meta
545
553
  // doesn't leak reference-tenant rows.
@@ -549,6 +557,21 @@ export function createFileRoutes(options) {
549
557
  const decision = await guard({ fileRef, user, operation: "read" });
550
558
  if (decision === "deny")
551
559
  return null;
560
+ return metaOf(fileRef);
561
+ }
562
+ // The foreign file is located and authorized first; only then is it decrypted through detail()
563
+ // in the file's own tenant.
564
+ async function loadForeignFileMeta(id, user) {
565
+ const readable = await loadForeignFile(id, user);
566
+ if (!readable || (await readDecisionFor(readable, user)) === "deny")
567
+ return null;
568
+ const row = await executor.detail({ id }, user, tenantDbFor(readable.fileRef.tenantId));
569
+ return row ? metaOf(fileRefOfRow(row)) : null;
570
+ }
571
+ function fileRefOfRow(row) {
572
+ return row; // @cast-boundary db-row (file_refs rows, decrypted where read via executor.detail)
573
+ }
574
+ function metaOf(fileRef) {
552
575
  return {
553
576
  id: fileRef.id,
554
577
  fileName: fileRef.fileName,
@@ -563,14 +586,54 @@ export function createFileRoutes(options) {
563
586
  const meta = await loadReadableFileMeta(c.req.param("id"), getUser(c));
564
587
  return meta ? c.json(meta) : c.json({ error: "not_found" }, 404);
565
588
  });
566
- // Read-only crossing: SYSTEM_TENANT_ID files (e.g. helpdesk attachments) are
567
- // visible to a SystemAdmin whose session sits in another tenant. Delete,
568
- // variant and upload keep using loadFileForTenant and stay tenant-equal.
569
- async function loadReadableFileRef(id, user) {
589
+ // Read-only crossings: SYSTEM_TENANT_ID files (e.g. helpdesk attachments) are visible to a
590
+ // SystemAdmin whose session sits in another tenant, and files of entities that declare
591
+ // crossTenantFileRead to users their query admits. Delete and upload keep using
592
+ // loadFileForTenant and stay tenant-equal.
593
+ async function loadReadableFile(id, user) {
570
594
  const own = await loadFileForTenant(id, user.tenantId);
571
- if (own || !canReadSystemTenantFile(user, SYSTEM_TENANT_ID))
572
- return own;
573
- return loadFileForTenant(id, SYSTEM_TENANT_ID, systemTenantReadDb(db));
595
+ if (own)
596
+ return { fileRef: own, foreign: false };
597
+ if (canReadSystemTenantFile(user, SYSTEM_TENANT_ID)) {
598
+ const system = await loadFileForTenant(id, SYSTEM_TENANT_ID, systemTenantReadDb(db));
599
+ if (system)
600
+ return { fileRef: system, foreign: false };
601
+ }
602
+ return loadForeignFile(id, user);
603
+ }
604
+ async function loadOwnOrForeignFile(id, user) {
605
+ const own = await loadFileForTenant(id, user.tenantId);
606
+ return own ? { fileRef: own, foreign: false } : loadForeignFile(id, user);
607
+ }
608
+ // Located across tenants only for declared entity types; whether the user may read it is decided
609
+ // by readDecisionFor, so a caller that skips it must not hand the file out.
610
+ async function loadForeignFile(id, user) {
611
+ if (canReadForeignTenantFile === undefined || isAnonymousSessionUser(user))
612
+ return null;
613
+ if (!isUuid(id))
614
+ return null;
615
+ const [row] = await selectMany(foreignTenantFileReadDb(db), fileRefsTable, {
616
+ id,
617
+ isDeleted: false,
618
+ });
619
+ const fileRef = row === undefined ? undefined : fileRefOfRow(row);
620
+ if (fileRef === undefined ||
621
+ fileRef.tenantId === user.tenantId ||
622
+ fileRef.entityType === null ||
623
+ fileRef.entityId === null ||
624
+ !crossTenantFileReadQueries.has(fileRef.entityType)) {
625
+ return null;
626
+ }
627
+ return { fileRef, foreign: true };
628
+ }
629
+ // A foreign tenant's file is decided by the declared query alone: the guard's privilegedRoles
630
+ // would otherwise hand it to any admin of any tenant.
631
+ async function readDecisionFor({ fileRef, foreign }, user) {
632
+ if (!foreign)
633
+ return guard({ fileRef, user, operation: "read" });
634
+ if (canReadForeignTenantFile === undefined || isAnonymousSessionUser(user))
635
+ return "deny";
636
+ return (await canReadForeignTenantFile({ fileRef, user })) ? "allow" : "deny";
574
637
  }
575
638
  async function loadFileForTenant(id, tenantId, readDb = db) {
576
639
  // fileRefsTable.id is a UUID column — a malformed id must fail here, not
@@ -582,7 +645,7 @@ export function createFileRoutes(options) {
582
645
  // isDeleted:false — soft-deleted (trashed) rows stay recoverable but must
583
646
  // never surface to reads/guards.
584
647
  const [row] = await selectMany(readDb, fileRefsTable, { id, tenantId, isDeleted: false });
585
- return row ?? null; // @cast-boundary db-row
648
+ return row === undefined ? null : fileRefOfRow(row);
586
649
  }
587
650
  return api;
588
651
  }
@@ -0,0 +1,13 @@
1
+ import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
2
+ import type { DbConnection } from "../db/connection.ts";
3
+ import type { Registry, SessionUser } from "../engine/types/index.ts";
4
+ import type { FileRef } from "./file-routes.ts";
5
+ export type ForeignTenantFileReadCheck = (args: {
6
+ readonly fileRef: FileRef;
7
+ readonly user: SessionUser;
8
+ }) => Promise<boolean>;
9
+ type QueryAsUser = (type: string, payload: unknown, user: SessionUser) => Promise<unknown>;
10
+ export declare function collectCrossTenantFileReadQueries(registry: Registry): ReadonlyMap<string, string>;
11
+ export declare function createForeignTenantFileReadCheck(registry: Registry, query: QueryAsUser): ForeignTenantFileReadCheck;
12
+ export declare function foreignTenantFileReadDb(db: DbConnection): TenantDb;
13
+ export {};
@@ -0,0 +1,64 @@
1
+ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
2
+ import { createTenantDb } from "../db/tenant-db.js";
3
+ import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
4
+ import { isKumikoError } from "../errors/index.js";
5
+ import { createFallbackLogger } from "../logging/index.js";
6
+ const log = createFallbackLogger("files");
7
+ const cache = new WeakMap();
8
+ // Event-sourced read models (projection entities) are not in getAllEntities, so both sources count.
9
+ export function collectCrossTenantFileReadQueries(registry) {
10
+ const cached = cache.get(registry);
11
+ if (cached)
12
+ return cached;
13
+ const queryByEntityType = new Map();
14
+ for (const [name, entity] of registry.getAllEntities()) {
15
+ if (entity.crossTenantFileRead)
16
+ queryByEntityType.set(name, entity.crossTenantFileRead.query);
17
+ }
18
+ for (const projection of registry.getAllProjections().values()) {
19
+ const name = projection.source;
20
+ if (typeof name !== "string")
21
+ continue;
22
+ const declaration = registry.getReadModelEntity(name)?.crossTenantFileRead;
23
+ if (declaration)
24
+ queryByEntityType.set(name, declaration.query);
25
+ }
26
+ cache.set(registry, queryByEntityType);
27
+ return queryByEntityType;
28
+ }
29
+ // The declared query runs as the requesting user, so its own access and visibility rules decide.
30
+ // Only a record carrying the requested id counts; null, other shapes and access errors mean no; the caller's own guard never applies to a foreign tenant's file.
31
+ export function createForeignTenantFileReadCheck(registry, query) {
32
+ return async ({ fileRef, user }) => {
33
+ const { entityType, entityId } = fileRef;
34
+ if (entityType === null || entityId === null)
35
+ return false;
36
+ const queryQn = collectCrossTenantFileReadQueries(registry).get(entityType);
37
+ if (queryQn === undefined)
38
+ return false;
39
+ try {
40
+ const record = await query(queryQn, { id: entityId }, user);
41
+ return propertyOf(record, "id") === entityId;
42
+ }
43
+ catch (error) {
44
+ if (!isKumikoError(error) || error.httpStatus >= 500) {
45
+ log.error("cross-tenant file read check failed; file access denied", {
46
+ entityType,
47
+ queryQn,
48
+ error: error instanceof Error ? error.message : String(error),
49
+ });
50
+ }
51
+ return false;
52
+ }
53
+ };
54
+ }
55
+ // Reads file_refs rows of every tenant, never writes; callers narrow to declared entity types.
56
+ export function foreignTenantFileReadDb(db) {
57
+ return createTenantDb({
58
+ db,
59
+ tenantId: SYSTEM_TENANT_ID,
60
+ mode: "system",
61
+ reason: "cross-tenant file read of entities that declare crossTenantFileRead",
62
+ grants: { writesDeniedReason: "on the cross-tenant file read handle" },
63
+ });
64
+ }
@@ -73,6 +73,9 @@ function pushEditFieldTextKeys(out, spec, treatAsKey = false) {
73
73
  pushKey(out, affix, treatAsKey);
74
74
  }
75
75
  pushKey(out, spec.fillAction?.label, treatAsKey);
76
+ for (const chip of spec.aiAssist?.chips ?? [])
77
+ pushKey(out, chip.label, treatAsKey);
78
+ pushKey(out, spec.aiAssist?.prompt?.placeholder, treatAsKey);
76
79
  }
77
80
  // Group titles are translated exactly like the section title (computeEditViewModel).
78
81
  function pushSectionTitles(out, section, treatAsKey = false) {
@@ -91,7 +94,7 @@ function pushActionFormShapedKeys(out, featureName, step) {
91
94
  pushKey(out, section.title);
92
95
  continue;
93
96
  }
94
- if (section.kind === "relatedList")
97
+ if (section.kind === "relatedList" || section.kind === "stepList")
95
98
  continue; // rejected at boot, unreachable here
96
99
  pushSectionTitles(out, section);
97
100
  for (const f of sectionFieldSpecs(section)) {
@@ -108,8 +111,9 @@ function pushRowActionKeys(out, action) {
108
111
  pushKey(out, action.confirm);
109
112
  pushKey(out, action.confirmLabel);
110
113
  }
111
- if (action.kind === "clientAction")
114
+ if (action.kind === "clientAction" && action.successMessage !== false) {
112
115
  pushKey(out, action.successMessage);
116
+ }
113
117
  if (action.kind === "drawer") {
114
118
  pushKey(out, action.title);
115
119
  pushKey(out, action.subtitle);
@@ -251,10 +255,13 @@ function pushExpandableRowKeys(out, section) {
251
255
  pushRowActionKeys(out, section.emptyState.action);
252
256
  }
253
257
  }
258
+ function fieldTextRefKey(ref) {
259
+ return typeof ref === "string" ? ref : ref.key;
260
+ }
254
261
  function pushFieldLabelOrOverrideKey(ctx, labelEntity, fieldName, fieldLabels, treatAsKey = false) {
255
262
  const override = fieldLabels?.[fieldName];
256
263
  if (override !== undefined)
257
- pushKey(ctx.out, override, treatAsKey);
264
+ pushKey(ctx.out, fieldTextRefKey(override), treatAsKey);
258
265
  else
259
266
  ctx.out.add(fieldLabelKey(ctx.featureName, labelEntity, fieldName));
260
267
  }
@@ -304,7 +311,7 @@ function pushEditLayoutSectionKeys(ctx, sections, labelEntity, fieldLabels) {
304
311
  pushKey(ctx.out, section.title);
305
312
  continue;
306
313
  }
307
- if (section.kind === "relatedList")
314
+ if (section.kind === "relatedList" || section.kind === "stepList")
308
315
  continue; // rejected at boot, unreachable here
309
316
  pushSectionTitles(ctx.out, section);
310
317
  for (const f of sectionFieldSpecs(section)) {
@@ -324,6 +331,12 @@ function collectActionFormKeys(ctx, form) {
324
331
  pushKey(ctx.out, form.summary?.subtitle);
325
332
  for (const action of form.footerActions ?? [])
326
333
  pushKey(ctx.out, action.label);
334
+ for (const ref of Object.values(form.fieldDescriptions ?? {})) {
335
+ pushKey(ctx.out, fieldTextRefKey(ref));
336
+ }
337
+ pushKey(ctx.out, form.infoBand);
338
+ for (const badge of Object.values(form.fieldBadges ?? {}))
339
+ pushKey(ctx.out, badge.label);
327
340
  for (const link of form.successLinks ?? [])
328
341
  pushKey(ctx.out, link.label);
329
342
  for (const fact of form.successFacts ?? [])
@@ -358,7 +371,7 @@ function pushConfigEditSectionKeys(ctx, config) {
358
371
  pushKey(out, section.title);
359
372
  continue;
360
373
  }
361
- if (section.kind === "relatedList")
374
+ if (section.kind === "relatedList" || section.kind === "stepList")
362
375
  continue; // rejected at boot, unreachable here
363
376
  pushSectionTitles(out, section, treatDotFormAsKey);
364
377
  pushKey(out, section.description, treatDotFormAsKey);
@@ -414,6 +427,10 @@ function collectProjectionDetailKeys(ctx, detail) {
414
427
  pushKey(ctx.out, bulk.confirm);
415
428
  continue;
416
429
  }
430
+ if (section.kind === "stepList") {
431
+ pushKey(ctx.out, section.title);
432
+ continue;
433
+ }
417
434
  if (isWriteFormEditSection(section)) {
418
435
  pushWriteFormSectionKeys(ctx, section);
419
436
  continue;
@@ -679,8 +696,11 @@ export function fieldValueTranslationKeysFromFeature(feature) {
679
696
  if (!entity)
680
697
  continue;
681
698
  for (const section of screen.layout.sections) {
682
- if (isExtensionEditSection(section) || section.kind === "relatedList")
699
+ if (isExtensionEditSection(section) ||
700
+ section.kind === "relatedList" ||
701
+ section.kind === "stepList") {
683
702
  continue;
703
+ }
684
704
  for (const spec of sectionFieldSpecs(section)) {
685
705
  const field = editFieldName(spec);
686
706
  const def = entity.fields[field];