@vxil/config 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -23,9 +23,34 @@ export interface FieldDef {
      *  cannot reconcile surface as a visible plan warning, never a silent no-op. */
     unique?: boolean;
     /** Per-relation-field delete behavior (cms.md §11): bounded, atomic fan-out
-     *  when the referenced item is deleted. Same carriage + reconcile behavior
-     *  as `unique`. */
-    onDelete?: 'cascade' | 'set_null';
+     *  when the referenced item is deleted — or `restrict` (§11.1), which REFUSES
+     *  the delete with 409 `referenced` while a live reference exists. Same
+     *  carriage + reconcile behavior as `unique`. */
+    onDelete?: 'cascade' | 'set_null' | 'restrict';
+    /** FIELD-LEVEL READ SECURITY (cms.md §18): the end-user ORG ROLE slugs allowed
+     *  to READ this field. Omitted/`[]` = ungated (every caller sees it — today's
+     *  behavior). A non-empty list is FAIL-SAFE: in VERIFIED end-user mode the
+     *  field is OMITTED from every read (get / list / query / `$expand` at any
+     *  depth / the write-response echo / read-hook payloads) unless the session's
+     *  verified `roles` claim intersects the list, it is UNQUERYABLE (a filter /
+     *  sort / group-by naming it is a 422, so it cannot be a value oracle), and it
+     *  is NEVER served on the anonymous public lane. A trusted SERVER caller (an
+     *  API key with no end-user session) still sees every field — this gates END
+     *  USERS, not the tenant. ≤16 entries, each `^[a-z0-9][a-z0-9_-]{0,31}$` (the
+     *  `orgs` role alphabet). The gate
+     *  never affects WRITES. Carried by BOTH push paths and alterable in place. */
+    readRoles?: string[];
+}
+/** One config-declared per-record ACTION button (cms.md §17): exactly ONE
+ *  human-initiated step — pressing it invokes the deployed tenant function `fn`
+ *  with `{ collection, item_id, action, actor, item }` and returns its result.
+ *  No conditions, no chaining, no scheduling. `key` matches
+ *  /^[a-z][a-z0-9_]{0,31}$/, `fn` is a function name (/^[a-z][a-z0-9-]{0,47}$/),
+ *  ≤8 per collection. */
+export interface CmsActionDef {
+    key: string;
+    label: string;
+    fn: string;
 }
 /** The CANONICAL field-attribute name set (config-side spelling), DERIVED from
  *  `FieldDef` itself so it can never drift from the authoring type: it is every
@@ -66,10 +91,24 @@ export interface CollectionDef {
      *  with a regression test on each — an attribute read by no enforcing path ships
      *  inert (the validation.unique / owner_field precedent). */
     public?: boolean;
+    /** Per-record action buttons (cms.md §17): `[{ key, label, fn }]`, stored on
+     *  the collection (model data, not a config leaf). The dashboard renders one
+     *  button per action on each record row; `POST /v1/cms/items/:coll/:id/actions/
+     *  :key` invokes `fn` once. Carried by BOTH push paths (create + reconcile on
+     *  existing collections — config is the source of truth; `[]`/absent clears). */
+    actions?: CmsActionDef[];
 }
+/** The auth lifecycle events an `authHook` binding may subscribe to (F4-30,
+ * auth wave 2026-09-10) — a CLOSED union; ONE event per binding, one audit
+ * event → one function invocation, no branching inside vxil:
+ *   user.created    — auth.user.created  { user_id, method, is_anonymous }
+ *   session.created — auth.session.created { user_id, session_id }
+ *   session.revoked — auth.session.revoked { user_id, session_id, reason }
+ *   signin.failure  — auth.signin.failure { email_hash | user_id, reason } */
+export type AuthHookEvent = 'user.created' | 'session.created' | 'session.revoked' | 'signin.failure';
 /** A function trigger (the §7.3 crossing). cmsHook fires on a CMS write;
- * authHook is the post-signup hook (fires on `auth.user.created`,
- * at-least-once, ~1min fanout latency). */
+ * authHook fires on ONE auth lifecycle event (default `user.created` — the
+ * post-signup hook; at-least-once, ~1min fanout latency). */
 export type FunctionTrigger = {
     kind: 'http';
     path?: string;
@@ -88,7 +127,7 @@ export type FunctionTrigger = {
     event: 'beforeCreate' | 'beforeUpdate' | 'beforeWrite';
 } | {
     kind: 'authHook';
-    event?: 'user.created';
+    event?: AuthHookEvent;
 };
 /** A deployed tenant function — source in functions/, deployed on `vxil push`. */
 export interface FunctionDef {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/config",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "defineConfig() — one typed source of truth for a whole vxil backend (features + CMS schema + functions + secret refs + seed). INTERNAL workspace package: bundled into the published `vxil` package's `vxil/config` subpath, not published separately.",
   "license": "MIT",
   "homepage": "https://vxil.com",
@@ -22,7 +22,7 @@
     "src"
   ],
   "dependencies": {
-    "@vxil/feature-configs": "0.2.0"
+    "@vxil/feature-configs": "0.3.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -42,9 +42,35 @@ export interface FieldDef {
    *  cannot reconcile surface as a visible plan warning, never a silent no-op. */
   unique?: boolean;
   /** Per-relation-field delete behavior (cms.md §11): bounded, atomic fan-out
-   *  when the referenced item is deleted. Same carriage + reconcile behavior
-   *  as `unique`. */
-  onDelete?: 'cascade' | 'set_null';
+   *  when the referenced item is deleted — or `restrict` (§11.1), which REFUSES
+   *  the delete with 409 `referenced` while a live reference exists. Same
+   *  carriage + reconcile behavior as `unique`. */
+  onDelete?: 'cascade' | 'set_null' | 'restrict';
+  /** FIELD-LEVEL READ SECURITY (cms.md §18): the end-user ORG ROLE slugs allowed
+   *  to READ this field. Omitted/`[]` = ungated (every caller sees it — today's
+   *  behavior). A non-empty list is FAIL-SAFE: in VERIFIED end-user mode the
+   *  field is OMITTED from every read (get / list / query / `$expand` at any
+   *  depth / the write-response echo / read-hook payloads) unless the session's
+   *  verified `roles` claim intersects the list, it is UNQUERYABLE (a filter /
+   *  sort / group-by naming it is a 422, so it cannot be a value oracle), and it
+   *  is NEVER served on the anonymous public lane. A trusted SERVER caller (an
+   *  API key with no end-user session) still sees every field — this gates END
+   *  USERS, not the tenant. ≤16 entries, each `^[a-z0-9][a-z0-9_-]{0,31}$` (the
+   *  `orgs` role alphabet). The gate
+   *  never affects WRITES. Carried by BOTH push paths and alterable in place. */
+  readRoles?: string[];
+}
+
+/** One config-declared per-record ACTION button (cms.md §17): exactly ONE
+ *  human-initiated step — pressing it invokes the deployed tenant function `fn`
+ *  with `{ collection, item_id, action, actor, item }` and returns its result.
+ *  No conditions, no chaining, no scheduling. `key` matches
+ *  /^[a-z][a-z0-9_]{0,31}$/, `fn` is a function name (/^[a-z][a-z0-9-]{0,47}$/),
+ *  ≤8 per collection. */
+export interface CmsActionDef {
+  key: string;
+  label: string;
+  fn: string;
 }
 
 /** The CANONICAL field-attribute name set (config-side spelling), DERIVED from
@@ -87,18 +113,33 @@ export interface CollectionDef {
    *  with a regression test on each — an attribute read by no enforcing path ships
    *  inert (the validation.unique / owner_field precedent). */
   public?: boolean;
+  /** Per-record action buttons (cms.md §17): `[{ key, label, fn }]`, stored on
+   *  the collection (model data, not a config leaf). The dashboard renders one
+   *  button per action on each record row; `POST /v1/cms/items/:coll/:id/actions/
+   *  :key` invokes `fn` once. Carried by BOTH push paths (create + reconcile on
+   *  existing collections — config is the source of truth; `[]`/absent clears). */
+  actions?: CmsActionDef[];
 }
 
+/** The auth lifecycle events an `authHook` binding may subscribe to (F4-30,
+ * auth wave 2026-09-10) — a CLOSED union; ONE event per binding, one audit
+ * event → one function invocation, no branching inside vxil:
+ *   user.created    — auth.user.created  { user_id, method, is_anonymous }
+ *   session.created — auth.session.created { user_id, session_id }
+ *   session.revoked — auth.session.revoked { user_id, session_id, reason }
+ *   signin.failure  — auth.signin.failure { email_hash | user_id, reason } */
+export type AuthHookEvent = 'user.created' | 'session.created' | 'session.revoked' | 'signin.failure';
+
 /** A function trigger (the §7.3 crossing). cmsHook fires on a CMS write;
- * authHook is the post-signup hook (fires on `auth.user.created`,
- * at-least-once, ~1min fanout latency). */
+ * authHook fires on ONE auth lifecycle event (default `user.created` — the
+ * post-signup hook; at-least-once, ~1min fanout latency). */
 export type FunctionTrigger =
   | { kind: 'http'; path?: string }
   | { kind: 'cron'; schedule: string }
   | { kind: 'queue'; source: string }
   | { kind: 'webhook'; source: string }
   | { kind: 'cmsHook'; collection: string; event: 'beforeCreate' | 'beforeUpdate' | 'beforeWrite' }
-  | { kind: 'authHook'; event?: 'user.created' };
+  | { kind: 'authHook'; event?: AuthHookEvent };
 
 /** A deployed tenant function — source in functions/, deployed on `vxil push`. */
 export interface FunctionDef {