@cosmicdrift/kumiko-types 0.256.0 → 0.258.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.256.0",
+  "version": "0.258.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/event-store-executor-types.ts

@@ -6,6 +6,15 @@ import type { EntityId } from "./identifiers";
 import type { SearchAdapter } from "./search-adapter";
 import type { TenantDb } from "./tenant-db-types";
 
+// Read-time gate for join-row entities (EntityDefinition.parentRef): the
+// registered-entity map the SQL clause checks host candidates against.
+// Lives here (not in db/parent-ref-clause.ts) because the Registry only
+// exists at request time — the same extension-point shape as
+// referenceSearch/referenceSort below (fw#2660/fw#2741).
+export type ParentVisibilityOption = {
+  readonly entities: ReadonlyMap<string, EntityDefinition>;
+};
+
 // Runs the caller's preSave hooks against changes not yet persisted, for
 // the executor's create()/update() only — restore/delete/forget have no
 // `changes` to shape. See HandlerContext.runPreSave for how this gets bound
@@ -120,6 +129,9 @@ export type EventStoreExecutor = {
         }>;
         readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
       };
+      // Join-row read-gate (EntityDefinition.parentRef) — same request-time
+      // registry dependency as referenceSearch/referenceSort above.
+      readonly parentVisibility?: ParentVisibilityOption;
     },
   ) => Promise<CursorResult<Record<string, unknown>>>;
 
@@ -127,5 +139,6 @@ export type EventStoreExecutor = {
     payload: { id: EntityId },
     user: SessionUser,
     db: TenantDb,
+    options?: { readonly parentVisibility?: ParentVisibilityOption },
   ) => Promise<Record<string, unknown> | null>;
 };

package/src/fields.ts

@@ -255,7 +255,8 @@ export type TextFieldDef = {
   readonly filterable?: boolean;
   readonly encrypted?: boolean;
   readonly sensitive?: boolean;
-  readonly format?: "email" | "url" | "phone";
+  /** "password" is a pure render hint (masked input) — no storage semantics. */
+  readonly format?: "email" | "url" | "phone" | "password";
   readonly default?: string;
   readonly access?: FieldAccess;
   /** Mehrzeiliger Text — DefaultInput rendert dann ein <textarea> statt
@@ -903,6 +904,16 @@ export type EntityIndexDef = {
 
 export type FieldsMap = Readonly<Record<string, FieldDefinition>>;
 
+export type ParentRefDef = {
+  /** Field holding the name of the host entity this row hangs off. */
+  readonly entityTypeField: string;
+  /** Field holding the host row's id. */
+  readonly entityIdField: string;
+  /** Narrow which registered entities may act as host. Omitted means every
+   *  registered entity is a candidate, which also widens the read-gate's SQL. */
+  readonly allowedTypes?: readonly string[];
+};
+
 export type EntityDefinition<F extends FieldsMap = FieldsMap> = {
   readonly table?: string;
   readonly fields: F;
@@ -943,6 +954,15 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap> = {
     readonly read?: OwnershipMap;
     readonly write?: OwnershipMap;
   };
+  /**
+   * Join-row carrier reference. Rows of this entity hang off a host row named
+   * by two of the entity's own fields. Both paths derive one visibility gate
+   * from this single declaration: write handlers deny with NotFoundError, and
+   * list/detail filter in SQL against the host entity's own read path (tenant
+   * scope, soft-delete, `access.read` ownership). A host type that names no
+   * registered entity is denied.
+   */
+  readonly parentRef?: ParentRefDef;
   /**
    * Default-Retention-Policy fuer diese Entity. Tenant-Admin kann via
    * Compliance-Profile + Tenant-Override (Sprint 2) uebersteuern.

package/src/handlers.ts

@@ -1011,10 +1011,20 @@ export type WriteHandlerDef = {
   readonly perform?: import("./step").PipelineDef;
 };
 
+// Marker set by defineEntityQueryHandler on both of its verbs. A string, not
+// a Symbol(), for the same reason as PAGED_QUERY_HANDLER_BRAND: a symlinked
+// workspace can evaluate a module twice, and two Symbol() calls would not
+// compare equal across those instances.
+export const ENTITY_CONVENTION_QUERY_BRAND = "__kumikoEntityConventionQuery";
+
 export type QueryHandlerDef = {
   readonly name: string;
   readonly schema: ZodType;
   readonly handler: QueryHandlerFn;
+  /** Set only by defineEntityQueryHandler, which wires the parent-ref
+   *  read-gate. The boot-validator requires it on a `parentRef` entity's
+   *  list/detail handler — see boot-validator/parent-ref.ts. */
+  readonly [ENTITY_CONVENTION_QUERY_BRAND]?: true;
   readonly access?: AccessRule;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;

package/src/identifiers.ts

@@ -13,7 +13,11 @@ export type TenantId = string;
 // already holds a TenantId from a trusted source (JWT payload, server
 // config) skips this — the helper is for **untrusted input** crossing
 // the system boundary.
-const TENANT_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+//
+// Exported so SQL-side checks (a Postgres `~` regex match) can share the
+// exact same shape instead of growing a second copy that drifts.
+export const UUID_SHAPE_PATTERN = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";
+const TENANT_ID_REGEX = new RegExp(UUID_SHAPE_PATTERN);
 
 // Shared shape check for any UUID-formatted identifier crossing an
 // untrusted boundary (fileRefId, entity ids, ...) — same loose,

package/src/nav-icon.ts

@@ -86,7 +86,9 @@ export type NavIconKey =
   | "info"
   | "check-circle"
   | "x-circle"
-  | "loader";
+  | "loader"
+  | "mic"
+  | "circle-stop";
 
 // Alias kept because the union stopped being nav-only — actions and fields
 // (added on this branch) also key their icons against it.

package/src/screen.ts

@@ -1129,6 +1129,85 @@ export type ActionFormRedirect = {
   readonly idFrom: string;
 };
 
+/** Author-declared field shown once after a mint-form submit — API token,
+ *  recovery codes, similar one-time secrets. */
+export type SecretRevealField = {
+  /** Flat field name in the handler's success payload. */
+  readonly field: string;
+  /** i18n key for this value's label. */
+  readonly label: string;
+  /** "code" (default) renders one monospaced value; "list" renders a
+   *  string-array payload one value per line (recovery codes); "qr" renders
+   *  the value as a scannable QR code (otpauth://-style enrollment URI) —
+   *  platforms without a QR-capable SecretReveal primitive fall back to the
+   *  monospaced text display. */
+  readonly display?: "code" | "list" | "qr";
+  /** Default true — offer a copy-to-clipboard control next to the value. */
+  readonly copyable?: boolean;
+};
+
+/** Post-reveal proof-of-receipt step. A mint whose effect is only armed once
+ *  the user proves they received the secret (TOTP enrollment: scan the code,
+ *  then enter one) declares it here — the reveal card renders this form in
+ *  place of the bare acknowledge button. */
+export type SecretMintConfirmStep = {
+  /** Write-handler QN dispatched when the confirm form is submitted. */
+  readonly handler: string;
+  readonly fields: Readonly<Record<string, FieldDefinition>>;
+  readonly layout: EditLayout;
+  /** Mint success-payload fields merged into the confirm payload (e.g. a
+   *  short-lived setup token). Held in component state only — never rendered,
+   *  never in the URL, a query cache, nav or a persisted draft. */
+  readonly carry?: readonly string[];
+  readonly submitLabel?: string;
+  /** i18n key for the banner shown after a successful confirm when the screen
+   *  declares no `redirect`. Default "kumiko.secretMint.done". */
+  readonly doneMessage?: string;
+};
+
+export type SecretReveal = {
+  readonly fields: readonly SecretRevealField[];
+  /** i18n key. Default "kumiko.secretMint.title". */
+  readonly title?: string;
+  /** i18n key for the "this is the only time you see it" warning.
+   *  Default "kumiko.secretMint.warning". */
+  readonly warning?: string;
+  /** i18n key for the acknowledge button. Default "kumiko.secretMint.confirm". */
+  readonly confirmLabel?: string;
+};
+
+/** Mint form → one-time reveal → explicit confirm. The secret (API token,
+ *  recovery codes) lives only in the write-handler's own success payload —
+ *  no stored value backs it, so no query can redisplay it later. That gap
+ *  is why this needs its own screen type instead of a flag on `actionForm`,
+ *  which discards the success payload after extracting the navigation id. */
+export type SecretMintScreenDefinition = {
+  readonly id: string;
+  readonly type: "secretMint";
+  readonly nav?: ScreenNavSugar;
+  readonly detailFor?: string;
+  readonly description?: string;
+  readonly agent?: AgentHandlerHints;
+  /** Write-handler QN dispatched on submit. */
+  readonly handler: string;
+  readonly fields: Readonly<Record<string, FieldDefinition>>;
+  readonly layout: EditLayout;
+  /** Navigate here after the reveal is confirmed. Short id (same-feature) or
+   *  a fully-qualified cross-feature screen QN — no result-id navigation
+   *  form exists here (unlike `ActionFormScreenDefinition.redirect`), since
+   *  the confirmed screen carries no entity id to thread through. */
+  readonly redirect?: string;
+  readonly cancelTarget?: string | false;
+  readonly listScreenId?: string;
+  readonly access?: AccessRule;
+  readonly reveal: SecretReveal;
+  /** i18n-key for the mint button. Default: renderer's own default. */
+  readonly submitLabel?: string;
+  /** Proof-of-receipt step rendered on the reveal card in place of the bare
+   *  acknowledge button — see `SecretMintConfirmStep` doc. */
+  readonly confirm?: SecretMintConfirmStep;
+};
+
 // --- custom ---
 
 // Sub-route declared by a custom screen (Expo Router / URL-routing use).
@@ -1307,4 +1386,5 @@ export type ScreenDefinition =
   | ActionFormScreenDefinition
   | ConfigEditScreenDefinition
   | SecretsEditScreenDefinition
+  | SecretMintScreenDefinition
   | CustomScreenDefinition;