@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/engine/ownership.js

@@ -0,0 +1,339 @@
+// Ownership rules — the declarative bridge between Claims and Access.
+//
+// Every ownership rule answers the same question: "May this user see / write
+// this row (or field in this row)?". The rule is evaluated per-role: a user
+// with multiple roles passes if at least one of their roles has a rule that
+// accepts the row. For writes, the check is stricter — see below.
+//
+// Rule forms:
+//
+//   "all"                                → any user with this role passes
+//   { from: "user:id", column: "..." }   → row[column] === user.id
+//   { from: "claim:<featureQn>",
+//     column?: "..." }                   → row[column ?? claim.shortName] === user.claims[claim.qn]
+//                                         (string[] claim → inArray)
+//   { where: (user, ctx) => SqlFragment } → escape hatch, raw parameterised SQL
+//
+// Construction: use the `from(ref, column?)` helper. It returns a FromRule
+// ready to drop into an access map.
+import { KUMIKO_COLUMNS_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { toSnakeCase } from "../db/table-builder.js";
+import { assertQualifiedWhereFragment, tableColumnSqlNames } from "./where-rule-lint.js";
+// Parse an OwnershipRef into kind + resolved path + default column.
+// Throws on malformed input so the error surfaces at `from()`-call-site (in
+// the feature definition), not at request time.
+export function from(ref, column) {
+    const firstColon = ref.indexOf(":");
+    if (firstColon < 0) {
+        throw new Error(`from("${ref}"): expected "user:<field>" or "claim:<featureName>:<key>" — no colon found.`);
+    }
+    const prefix = ref.slice(0, firstColon);
+    const rest = ref.slice(firstColon + 1);
+    if (prefix === "user") {
+        // "user:id" or "user:tenantId". The rest is the user-property; the
+        // column on the row must be given explicitly (a user.id is rarely
+        // named `id` on a child table — usually `ownerId`, `assigneeId`, ...).
+        if (!column) {
+            throw new Error(`from("${ref}"): user-refs require an explicit column name — e.g. from("user:id", "assigneeId").`);
+        }
+        if (rest !== "id" && rest !== "tenantId") {
+            throw new Error(`from("${ref}"): user-ref supports only "user:id" or "user:tenantId" (got "user:${rest}").`);
+        }
+        return { kind: "from", refKind: "user", refPath: rest, column };
+    }
+    if (prefix === "claim") {
+        // "claim:<feature>:<key>" — rest is the 2-segment claim QN.
+        if (!rest.includes(":")) {
+            throw new Error(`from("${ref}"): claim-ref must be "claim:<featureName>:<shortName>" (got "claim:${rest}").`);
+        }
+        // Default column = claim shortName (second segment).
+        const defaultColumn = rest.slice(rest.indexOf(":") + 1);
+        return {
+            kind: "from",
+            refKind: "claim",
+            refPath: rest, // full QN, matches the key in user.claims
+            column: column ?? defaultColumn,
+        };
+    }
+    throw new Error(`from("${ref}"): unsupported ref prefix "${prefix}". Supported: "user", "claim".`);
+}
+// Evaluate an ownership rule against a concrete row (plain data, no Drizzle).
+// Used by field-level filters on query responses and by field-level
+// write-checks. Entity-level rules that want SQL predicates go through
+// buildOwnershipClause() (separate path, since that produces Drizzle SQL).
+//
+// Null/undefined claim values evaluate to `false` (no match) — safer than
+// letting them match rows where the column happens to be null.
+export function matchesRule(rule, user, row) {
+    if (rule === "all")
+        return true;
+    if (rule.kind === "where") {
+        // `where` rules produce SQL for the DB-side filter and have no in-memory
+        // evaluator — the feature author owns the semantics. Only the read path
+        // reaches SQL (buildOwnershipClause); on write maps the boot-validator
+        // rejects them outright (fw#2626), and the in-memory write helpers below
+        // fail closed rather than calling in here.
+        throw new Error("where-rules can only be evaluated at the SQL layer (buildOwnershipClause); they are rejected on access.write at boot.");
+    }
+    // FromRule — resolve the user-side value, compare to the row's column.
+    const userValue = resolveUserValue(rule, user);
+    if (userValue === undefined)
+        return false;
+    const rowValue = row[rule.column];
+    if (rowValue === undefined || rowValue === null)
+        return false;
+    // Array claim → membership check; scalar claim → equality.
+    if (Array.isArray(userValue)) {
+        return userValue.includes(rowValue);
+    }
+    return userValue === rowValue;
+}
+function resolveUserValue(rule, user) {
+    if (rule.refKind === "user") {
+        if (rule.refPath === "id")
+            return user.id;
+        return user.tenantId;
+    }
+    // claim refPath is the full QN ("feature:shortName") — direct key lookup.
+    return user.claims?.[rule.refPath];
+}
+// Multi-role-atomic passer for field-level READ. The caller supplies the
+// user, the access-map for this field, and the concrete row. Returns true
+// if AT LEAST one of the user's roles is in the map and its rule matches
+// the row. Missing roles skip, "all" always passes.
+export function userCanReadFieldRow(user, accessMap, row) {
+    if (!accessMap || Object.keys(accessMap).length === 0)
+        return true; // public
+    for (const role of user.roles) {
+        const rule = accessMap[role];
+        if (!rule)
+            continue;
+        // where-rules are SQL predicates (buildOwnershipClause); matchesRule
+        // can't evaluate them in-memory and throws. Read maps may legitimately
+        // carry one — it just belongs on the SQL path, so an in-memory read
+        // check denies rather than crashing.
+        // skip: where-rules are SQL-layer only — fail closed instead of throwing.
+        if (rule !== "all" && rule.kind === "where")
+            continue;
+        if (matchesRule(rule, user, row))
+            return true;
+    }
+    return false;
+}
+// Multi-role-atomic check for field-level WRITE with Straddle-prevention.
+// A user passes iff exactly one of their roles has a rule that accepts
+// BOTH the old and the new row. OR-ing over (any-role passes old) and
+// (any-role passes new) is wrong — a user with two roles could split the
+// check: role A validates the old, role B validates the new, yielding
+// row-grabbing by stitching two rules together. See advisor review 2026-04-19.
+export function userCanWriteFieldRow(user, accessMap, oldRow, newRow) {
+    if (!accessMap || Object.keys(accessMap).length === 0)
+        return true; // public
+    for (const role of user.roles) {
+        const rule = accessMap[role];
+        if (!rule)
+            continue;
+        if (rule === "all")
+            return true;
+        // skip: where-rules are SQL-layer only — fail closed instead of throwing.
+        if (rule.kind === "where")
+            continue;
+        if (matchesRule(rule, user, oldRow) && matchesRule(rule, user, newRow))
+            return true;
+    }
+    return false;
+}
+// Normalize legacy `readonly string[]` field-access into the OwnershipMap
+// shape. Each role in the array becomes a key with rule "all" (unrestricted
+// for that role). Undefined stays undefined. This is a migration shim —
+// long-term every feature-definition writes the map shape directly.
+export function normalizeAccessEntry(entry) {
+    if (!entry)
+        return undefined;
+    if (Array.isArray(entry)) {
+        if (entry.length === 0)
+            return undefined;
+        const map = {};
+        for (const role of entry) {
+            map[role] = "all";
+        }
+        return map;
+    }
+    return entry; // @cast-boundary schema-walk
+}
+// Create-case: only the new row exists. Same Straddle protection not
+// applicable (no old row to compare), but we still need per-role atomicity
+// to respect "all"-rules and plain from-rules consistently.
+export function userCanCreateFieldRow(user, accessMap, newRow) {
+    if (!accessMap || Object.keys(accessMap).length === 0)
+        return true;
+    for (const role of user.roles) {
+        const rule = accessMap[role];
+        if (!rule)
+            continue;
+        if (rule === "all")
+            return true;
+        // skip: where-rules are SQL-layer only — fail closed instead of throwing.
+        // Mirrors userCanWriteFieldRow; a create has no row to run SQL against
+        // at all, so the boot-validator rejects the shape on access.write.
+        if (rule.kind === "where")
+            continue;
+        if (matchesRule(rule, user, newRow))
+            return true;
+    }
+    return false;
+}
+const PASS_CLAUSE = { kind: "pass" };
+const EMPTY_CLAUSE = { kind: "empty" };
+function tableNameOf(table) {
+    if (table !== null && typeof table === "object") {
+        const sym = table[KUMIKO_NAME_SYMBOL];
+        if (typeof sym === "string")
+            return sym;
+    }
+    return "<unknown>";
+}
+// Resolve a JS-field name on the table to its underlying SQL column name.
+// Drizzle tables carry the mapping under Symbol.for("kumiko:schema:Columns");
+// we read it without importing drizzle-orm at runtime.
+function columnSqlName(table, field) {
+    if (table === null || typeof table !== "object")
+        return null;
+    const cols = table[KUMIKO_COLUMNS_SYMBOL];
+    if (cols && typeof cols === "object") {
+        const col = cols[field];
+        if (col && typeof col === "object") {
+            const nameVal = col["name"];
+            if (typeof nameVal === "string")
+                return nameVal;
+        }
+    }
+    // Field may already be the SQL column name on plain objects (tests, etc.).
+    if (table[field] !== undefined) {
+        return toSnakeCase(field);
+    }
+    return null;
+}
+function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+// Shift `$N` placeholder numbers in an embedded fragment so they line up
+// with the outer query's param array.
+export function shiftParams(fragment, shift) {
+    if (shift === 0)
+        return fragment;
+    const sqlText = fragment.sqlText.replace(/\$(\d+)/g, (_, num) => `$${Number(num) + shift}`);
+    return { sqlText, params: fragment.params };
+}
+// Build an ownership clause for entity-level READ access. Caller weaves
+// the result into a raw-SQL WHERE (see event-store-executor list/getById).
+//
+// `table` is the (drizzle or compatible) table object; we extract column
+// SQL names via the kumiko:schema:Columns symbol. Unknown column on a from-rule
+// is a boot-time misconfiguration; at request time we treat it as empty
+// (safe default) rather than passing silently.
+//
+// Caller obligations (fw#1700) — this function returns ONLY the ownership
+// fragment, not the full row-access contract. A raw-SQL caller (not going
+// through `ctx.db`, which already applies all three) must additionally:
+//   1. Pass `paramStart` as `params.length + 1` for its own already-bound
+//      params, or `$N` placeholders in the returned fragment silently splice
+//      into the wrong query params.
+//   2. Apply tenant + soft-delete scoping itself (event-store-executor-read.ts
+//      does this outside `buildOwnershipClause`) — this function does not.
+//   3. Treat `kind: "empty"` (see `OwnershipClause`) as a hard DENY, and
+//      `kind: "pass"` as an explicit bypass — not as "no additional filter".
+export function buildOwnershipClause(user, accessMap, table, paramStart = 1) {
+    if (!accessMap || Object.keys(accessMap).length === 0)
+        return PASS_CLAUSE;
+    const clauses = [];
+    let anyRoleMatched = false;
+    let everyRuleCollapsedToEmpty = true;
+    let nextParamIdx = paramStart;
+    for (const role of user.roles) {
+        const rule = accessMap[role];
+        if (!rule)
+            continue;
+        anyRoleMatched = true;
+        if (rule === "all")
+            return PASS_CLAUSE;
+        const resolved = ruleToFragment(rule, user, table, nextParamIdx);
+        if (resolved.kind === "sql") {
+            clauses.push({ sqlText: resolved.sqlText, params: resolved.params });
+            nextParamIdx += resolved.params.length;
+            everyRuleCollapsedToEmpty = false;
+        }
+    }
+    if (!anyRoleMatched)
+        return EMPTY_CLAUSE;
+    if (everyRuleCollapsedToEmpty && clauses.length === 0)
+        return EMPTY_CLAUSE;
+    if (clauses.length === 1) {
+        const only = clauses[0];
+        if (!only)
+            return EMPTY_CLAUSE;
+        return { kind: "sql", sqlText: `(${only.sqlText})`, params: only.params };
+    }
+    const sqlText = clauses.map((c) => `(${c.sqlText})`).join(" OR ");
+    const params = [];
+    for (const c of clauses)
+        for (const p of c.params)
+            params.push(p);
+    return { kind: "sql", sqlText: `(${sqlText})`, params };
+}
+// AND-combine two independently built read clauses. Both are built at
+// paramStart=1; `b`'s placeholders are shifted past `a`'s params so the
+// concatenated fragment binds positionally.
+export function combineClauses(a, b) {
+    if (a.kind === "empty" || b.kind === "empty")
+        return { kind: "empty" };
+    if (a.kind === "pass")
+        return b;
+    if (b.kind === "pass")
+        return a;
+    const shifted = shiftParams({ sqlText: b.sqlText, params: b.params }, a.params.length);
+    return {
+        kind: "sql",
+        sqlText: `(${a.sqlText} AND ${shifted.sqlText})`,
+        params: [...a.params, ...shifted.params],
+    };
+}
+function ruleToFragment(rule, user, table, paramStart) {
+    if (rule === "all") {
+        return { kind: "sql", sqlText: "TRUE", params: [] };
+    }
+    if (rule.kind === "where") {
+        const frag = rule.where(user, {
+            table,
+            tableName: tableNameOf(table),
+            paramStart,
+        });
+        // Runtime backstop for the boot-time probe (boot-validator/ownership.ts):
+        // an unqualified column in a correlated subquery silently turns into a
+        // fail-open tautology (fw#2639) — throw instead of shipping it.
+        assertQualifiedWhereFragment(frag.sqlText, tableColumnSqlNames(table), `ownership where-rule on "${tableNameOf(table)}"`);
+        return { kind: "sql", sqlText: frag.sqlText, params: frag.params };
+    }
+    // FromRule
+    const colName = columnSqlName(table, rule.column);
+    if (!colName)
+        return { kind: "empty" };
+    const value = resolveUserValue(rule, user);
+    if (value === undefined || value === null)
+        return { kind: "empty" };
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return { kind: "empty" };
+        const placeholders = value.map((_, i) => `$${paramStart + i}`).join(", ");
+        return {
+            kind: "sql",
+            sqlText: `${quoteIdent(colName)} IN (${placeholders})`,
+            params: value,
+        };
+    }
+    return {
+        kind: "sql",
+        sqlText: `${quoteIdent(colName)} = $${paramStart}`,
+        params: [value],
+    };
+}

package/dist/engine/parse-ref-target.d.ts

@@ -0,0 +1,6 @@
+export type ParsedRefTarget = {
+    readonly featureName: string;
+    readonly entityName: string;
+};
+export declare function parseRefTarget(raw: string, currentFeature: string): ParsedRefTarget;
+export declare function parseRefTargetEntityName(raw: string): string;

package/dist/engine/parse-ref-target.js

@@ -0,0 +1,21 @@
+// Tier 2.7e Cross-Feature: ReferenceFieldDef.entity-String-Parser.
+//
+// Akzeptiert beide Formen:
+//   - "user"        → same-feature ref (featureName = currentFeature)
+//   - "users:user"  → cross-feature ref (qualifiziert)
+//
+// Lebt im framework-Package damit Server-Validator + Renderer (über
+// Re-Export aus @cosmicdrift/kumiko-headless) denselben Parser nutzen — die
+// Convention darf nicht zweimal implementiert werden.
+export function parseRefTarget(raw, currentFeature) {
+    const idx = raw.indexOf(":");
+    if (idx < 0) {
+        return { featureName: currentFeature, entityName: raw };
+    }
+    return { featureName: raw.slice(0, idx), entityName: raw.slice(idx + 1) };
+}
+// Entity names are globally unique in the registry, so callers that only
+// need the entity (not its owning feature) can drop the currentFeature arg.
+export function parseRefTargetEntityName(raw) {
+    return parseRefTarget(raw, "").entityName;
+}

package/dist/engine/pattern-library/index.d.ts

@@ -0,0 +1,2 @@
+export { getPatternSchema, groupByCategory, PATTERN_LIBRARY } from "./library.js";
+export type { BooleanField, CodeBlockField, DiscriminatedUnionField, EntityFieldsEditorField, EntityRefField, FormFieldLabel, FormFieldSpec, FormInputType, JsonReadonlyField, KeyValueMapField, NumberField, PatternCategory, PatternFormSchema, SelectField, SelectOption, StringListField, TextareaField, TextField, } from "./types.js";

package/dist/engine/pattern-library/index.js

@@ -0,0 +1,3 @@
+// Public API of the pattern-library — Designer (C5/C6), AI-Builder (L2),
+// MCP-Server (L9) consume from here.
+export { getPatternSchema, groupByCategory, PATTERN_LIBRARY } from "./library.js";

package/dist/engine/pattern-library/library.d.ts

@@ -0,0 +1,14 @@
+import type { FeaturePatternKind } from "../feature-ast/patterns.js";
+import type { PatternCategory, PatternFormSchema } from "./types.js";
+export declare const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSchema>>;
+/**
+ * Lookup helper — convenience over `PATTERN_LIBRARY[kind]`. Throws when
+ * the kind is missing from the catalogue, which is a programming error
+ * the exhaustiveness test should catch at CI time.
+ */
+export declare function getPatternSchema(kind: FeaturePatternKind): PatternFormSchema;
+/**
+ * Group the library by category — helper for the Designer's "add new
+ * pattern" panel.
+ */
+export declare function groupByCategory(): Readonly<Record<PatternCategory, readonly PatternFormSchema[]>>;

package/dist/engine/pattern-library/library.js

@@ -0,0 +1,92 @@
+// Pattern-Library — concrete FormSchema entries for every FeaturePattern
+// kind. Centralised here so the Designer (C5/C6), the AI-Builder (L2),
+// and the MCP-Server (L9) share one source-of-truth for "how does this
+// pattern look as a form?".
+//
+// **Updating contract:** when a new pattern-kind gets a parser/renderer
+// extension, add a matching entry here. The exhaustiveness test
+// (pattern-library.test.ts) catches missing kinds at CI time.
+//
+// **Path stability:** every `path` references a property of the parsed
+// FeaturePattern shape. When the pattern type changes (new field added
+// to e.g. EntityPattern.definition), update both the renderer in
+// render.ts AND the library here — paths are part of the public API
+// the Designer/LLM relies on.
+import { aiClassifySchema, aiExtractSchema, aiGenerateSchema, authClaimsSchema, defineEventSchema, hookSchema, httpRouteSchema, jobSchema, multiStreamProjectionSchema, notificationSchema, projectionSchema, queryHandlerSchema, screenSchema, streamHandlerSchema, writeHandlerSchema, } from "./mixed-schemas.js";
+import { envSchemaSchema, exposesApiSchema, extendsRegistrarSchema, treeActionsSchema, unknownSchema, usesApiSchema, } from "./opaque-schemas.js";
+import { claimKeySchema, configSchema, describeSchema, entitySchema, metricSchema, navSchema, optionalRequiresSchema, readsConfigSchema, referenceDataSchema, relationSchema, requiresSchema, secretSchema, systemScopeSchema, toggleableSchema, translationsSchema, uiHintsSchema, useExtensionSchema, workspaceSchema, } from "./static-schemas.js";
+export const PATTERN_LIBRARY = {
+    requires: requiresSchema,
+    optionalRequires: optionalRequiresSchema,
+    readsConfig: readsConfigSchema,
+    systemScope: systemScopeSchema,
+    toggleable: toggleableSchema,
+    describe: describeSchema,
+    uiHints: uiHintsSchema,
+    entity: entitySchema,
+    relation: relationSchema,
+    nav: navSchema,
+    workspace: workspaceSchema,
+    config: configSchema,
+    translations: translationsSchema,
+    metric: metricSchema,
+    secret: secretSchema,
+    claimKey: claimKeySchema,
+    referenceData: referenceDataSchema,
+    useExtension: useExtensionSchema,
+    screen: screenSchema,
+    writeHandler: writeHandlerSchema,
+    queryHandler: queryHandlerSchema,
+    streamHandler: streamHandlerSchema,
+    hook: hookSchema,
+    job: jobSchema,
+    notification: notificationSchema,
+    authClaims: authClaimsSchema,
+    httpRoute: httpRouteSchema,
+    projection: projectionSchema,
+    multiStreamProjection: multiStreamProjectionSchema,
+    defineEvent: defineEventSchema,
+    extendsRegistrar: extendsRegistrarSchema,
+    usesApi: usesApiSchema,
+    exposesApi: exposesApiSchema,
+    treeActions: treeActionsSchema,
+    envSchema: envSchemaSchema,
+    "ai.generate": aiGenerateSchema,
+    "ai.extract": aiExtractSchema,
+    "ai.classify": aiClassifySchema,
+    unknown: unknownSchema,
+};
+/**
+ * Lookup helper — convenience over `PATTERN_LIBRARY[kind]`. Throws when
+ * the kind is missing from the catalogue, which is a programming error
+ * the exhaustiveness test should catch at CI time.
+ */
+export function getPatternSchema(kind) {
+    const schema = PATTERN_LIBRARY[kind];
+    if (!schema) {
+        throw new Error(`pattern-library: no schema for kind "${kind}"`);
+    }
+    return schema;
+}
+/**
+ * Group the library by category — helper for the Designer's "add new
+ * pattern" panel.
+ */
+export function groupByCategory() {
+    const groups = {
+        data: [],
+        behaviour: [],
+        ui: [],
+        meta: [],
+        background: [],
+        "cross-cutting": [],
+        advanced: [],
+    };
+    for (const schema of Object.values(PATTERN_LIBRARY)) {
+        groups[schema.category].push(schema);
+    }
+    for (const list of Object.values(groups)) {
+        list.sort((a, b) => a.label.en.localeCompare(b.label.en));
+    }
+    return groups;
+}

package/dist/engine/pattern-library/mixed-schemas.d.ts

@@ -0,0 +1,16 @@
+import type { PatternFormSchema } from "./types.js";
+export declare const screenSchema: PatternFormSchema;
+export declare const writeHandlerSchema: PatternFormSchema;
+export declare const queryHandlerSchema: PatternFormSchema;
+export declare const streamHandlerSchema: PatternFormSchema;
+export declare const hookSchema: PatternFormSchema;
+export declare const jobSchema: PatternFormSchema;
+export declare const aiGenerateSchema: PatternFormSchema;
+export declare const aiExtractSchema: PatternFormSchema;
+export declare const aiClassifySchema: PatternFormSchema;
+export declare const notificationSchema: PatternFormSchema;
+export declare const authClaimsSchema: PatternFormSchema;
+export declare const httpRouteSchema: PatternFormSchema;
+export declare const projectionSchema: PatternFormSchema;
+export declare const multiStreamProjectionSchema: PatternFormSchema;
+export declare const defineEventSchema: PatternFormSchema;