@vxil/feature-configs 0.2.0 → 0.3.1

package/README.md

@@ -0,0 +1,58 @@
+# @vxil/feature-configs
+
+The typed config schemas for every Vxil feature — the shapes a `vxil.config.ts`
+is built on, published so your editor and your CI can read the same contract the
+platform validates against.
+
+```bash
+npm i -D @vxil/feature-configs
+```
+
+Most people never import this directly: writing
+[`defineConfig`](https://www.npmjs.com/package/@vxil/config) gives you these
+types automatically. Reach for it when you want to validate a manifest yourself,
+generate config, or type a helper.
+
+## What's in it
+
+- **One schema per feature**, all 19 of them — `NotificationsConfigSchema`,
+  `AuthConfigSchema`, `CmsConfigSchema`, `PaymentsConfigSchema`,
+  `FunctionsConfigSchema`, … — plus the matching `Static<>` types
+  (`NotificationsConfig`, `AuthConfig`, …).
+- **`FEATURE_KEYS`** — the canonical feature list, and **`FEATURE_SCHEMAS`** —
+  the key → schema map.
+- **`validateFeatureConfig(feature, raw)`** — the exact validation the control
+  plane runs, returning `{ ok, errors }` with JSON-pointer-style messages. Use it
+  in a pre-commit hook or a test to fail on a bad config before you push it.
+- **`hooks`** (`@vxil/feature-configs/hooks`) — the CMS lifecycle-hook expression
+  grammar: the same closed, sandboxed parser/validator the server uses, so a
+  malformed `validate` / `derive` expression is caught in your editor.
+
+```ts
+import { validateFeatureConfig, FEATURE_KEYS } from '@vxil/feature-configs';
+
+const result = validateFeatureConfig('notifications', {
+  enabled: true,
+  fromEmail: 'noreply@acme.com',
+});
+if (!result.ok) throw new Error(result.errors.join('\n'));
+```
+
+## Why the schemas are small on purpose
+
+Every feature's config is capped at a fixed number of top-level leaves. A knob
+earns its slot by having a reader; one that nothing reads gets deleted rather
+than left to rot as a promise the product does not keep. That is why the schemas
+here are the whole truth about what a feature can be configured to do — and why
+a version bump may *remove* a knob that was never wired. Removals are listed in
+the feature reference at [vxil.com](https://vxil.com).
+
+## Related
+
+- [`@vxil/config`](https://www.npmjs.com/package/@vxil/config) — `defineConfig()`.
+- [`@vxil/cli`](https://www.npmjs.com/package/@vxil/cli) — the `vxil` command (`plan` / `push` / `gen`).
+- [`@vxil/sdk`](https://www.npmjs.com/package/@vxil/sdk) — the typed runtime client.
+
+Docs: [vxil.com](https://vxil.com) · Dashboard: [vxil.com/dashboard](https://vxil.com/dashboard)
+
+MIT © techmaker.io

package/dist/hooks.d.ts

@@ -10,7 +10,7 @@ export declare const HOOK_LIMITS: {
     readonly maxReadHooksPerCollection: 10;
 };
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (docs/end-user-principals-design.md §5.6) — read-only and
+ *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only and
  *  populated ONLY on the READ path (runReadHooks); on the write path and in
  *  server-caller mode it is null, exactly like `before` on a create. It carries
  *  `caller.endUserId` (the verified session sub, or null) and `caller.principal`

package/dist/hooks.js

@@ -1,4 +1,4 @@
-// CMS lifecycle hooks — the SAFE expression engine (docs/cms-lifecycle-hooks-rung2-design.md, Lane A).
+// CMS lifecycle hooks — the SAFE expression engine (https://vxil.com/docs/guide/07-validation-and-hooks).
 //
 // A "code-based" lifecycle hook is a small EXPRESSION the tenant authors. Three kinds:
 //   - validate: the expression must evaluate truthy or the write is REJECTED (422)
@@ -17,8 +17,8 @@
 // CROSS-ROW AGGREGATION STAYS OUT — BY DESIGN. Read hooks are a pure function
 // of ONE row (+ `now`): there are no new root variables, no array/aggregate
 // functions, no access to sibling rows or other collections. Counts/sums/
-// group-bys across rows are the §5 identity-fork anti-item (docs/features/
-// cms.md §6.7) and must never enter this engine.
+// group-bys across rows are the identity-fork anti-item (function territory:
+// vxil.com/docs/guide/07-validation-and-hooks) and must never enter this engine.
 //
 // SAFETY (the "not malicious" guarantee) is structural, not heuristic:
 //   * No JS is executed. `eval`/`Function`/the host runtime are never touched. The
@@ -61,7 +61,7 @@ export const HOOK_LIMITS = {
 };
 // ── allow-lists ─────────────────────────────────────────────────────────────
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (docs/end-user-principals-design.md §5.6) — read-only and
+ *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only and
  *  populated ONLY on the READ path (runReadHooks); on the write path and in
  *  server-caller mode it is null, exactly like `before` on a create. It carries
  *  `caller.endUserId` (the verified session sub, or null) and `caller.principal`

package/dist/index.d.ts

@@ -5,6 +5,32 @@ export declare const RESERVED_CREDIT_TYPES: ReadonlySet<string>;
 /** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
  *  of which is restricted to internal platform machinery). */
 export declare function isReservedCreditType(creditType: string): boolean;
+export declare const NOTIFICATION_TEMPLATE_PLACEHOLDERS: Readonly<Record<string, readonly string[]>>;
+/** Per-override caps (D4). Bodies are emails, not documents. */
+export declare const NOTIF_OVERRIDE_SUBJECT_MAX = 500;
+export declare const NOTIF_OVERRIDE_BODY_MAX = 20000;
+/** Whole-map caps: keeps one manifest (and the KV row every send reads) small. */
+export declare const NOTIF_OVERRIDE_MAX_LOCALES_PER_TEMPLATE = 20;
+export declare const NOTIF_OVERRIDE_MAX_BYTES: number;
+/**
+ * D4 — validate `templates.overrides` at CONFIG-WRITE time. Returns [] when the
+ * bag is absent or clean. Every rule fails LOUD rather than shipping something
+ * that silently renders wrong in a customer's inbox:
+ *   • overrides present with `allowOverride:false` → rejected (never inert);
+ *   • an unknown template id / locale tag → rejected;
+ *   • an unknown `{{placeholder}}` in subject/html/text → rejected (the class of
+ *     typo that renders as an empty string in a live email);
+ *   • size caps (per-locale count, whole-map bytes) → rejected.
+ * Pure, so it is unit-tested without a control plane.
+ */
+export declare function validateNotificationOverrides(templates: {
+    allowOverride?: boolean;
+    overrides?: Record<string, Record<string, {
+        subject?: string;
+        html?: string;
+        text?: string;
+    }>>;
+} | undefined): string[];
 export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     fromEmail: import("@sinclair/typebox").TString;
@@ -25,9 +51,14 @@ export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObj
         perDay: import("@sinclair/typebox").TInteger;
         perTenantSec: import("@sinclair/typebox").TInteger;
     }>;
-    templates: import("@sinclair/typebox").TObject<{
+    templates: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         allowOverride: import("@sinclair/typebox").TBoolean;
-    }>;
+        overrides: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+            subject: import("@sinclair/typebox").TString;
+            html: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            text: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>>>>;
+    }>>;
     /** in-app inbox channel (send with channel: 'inbox' | 'both') */
     inboxEnabled: import("@sinclair/typebox").TBoolean;
     /** §11b.5 broadcast campaigns channel. Optional bag (= 1 leaf): absent means
@@ -100,16 +131,29 @@ export declare const JobsConfigSchema: import("@sinclair/typebox").TObject<{
     }>;
 }>;
 export type JobsConfig = Static<typeof JobsConfigSchema>;
+declare const OidcProviderSchema: import("@sinclair/typebox").TObject<{
+    issuer: import("@sinclair/typebox").TString;
+    clientId: import("@sinclair/typebox").TString;
+    clientSecretRef: import("@sinclair/typebox").TString;
+    scopes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    claims: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        email: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        roles: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+    allowedDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    autoLink: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
 export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
-    methods: import("@sinclair/typebox").TObject<{
+    methods: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         emailPassword: import("@sinclair/typebox").TBoolean;
         magicLink: import("@sinclair/typebox").TBoolean;
         google: import("@sinclair/typebox").TBoolean;
         github: import("@sinclair/typebox").TBoolean;
         apple: import("@sinclair/typebox").TBoolean;
         facebook: import("@sinclair/typebox").TBoolean;
-    }>;
+    }>>;
     providers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         google: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
             clientIdRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -133,10 +177,24 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
             clientSecretRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             audRefs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
         }>>;
+        oidc: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            issuer: import("@sinclair/typebox").TString;
+            clientId: import("@sinclair/typebox").TString;
+            clientSecretRef: import("@sinclair/typebox").TString;
+            scopes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+            claims: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                email: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                roles: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>;
+            allowedDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+            autoLink: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        }>>;
     }>>;
     session: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         ttlMinutes: import("@sinclair/typebox").TInteger;
         refreshTtlDays: import("@sinclair/typebox").TInteger;
+        maxConcurrent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
     }>>;
     password: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         minLength: import("@sinclair/typebox").TInteger;
@@ -153,6 +211,7 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
         codeTtlMinutes: import("@sinclair/typebox").TInteger;
         maxAttempts: import("@sinclair/typebox").TInteger;
         resendCooldownSec: import("@sinclair/typebox").TInteger;
+        testRecipients: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     }>>;
     anonymous: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         enabled: import("@sinclair/typebox").TBoolean;
@@ -160,7 +219,21 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
     orgClaims: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         enabled: import("@sinclair/typebox").TBoolean;
     }>>;
+    security: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        lockout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            maxFailures: import("@sinclair/typebox").TInteger;
+            windowMinutes: import("@sinclair/typebox").TInteger;
+            lockMinutes: import("@sinclair/typebox").TInteger;
+        }>>;
+        breachedPasswords: import("@sinclair/typebox").TBoolean;
+        captchaSecretRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        allowedRedirectOrigins: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    }>>;
 }>;
+/** The security bag as persisted (present ⇒ leaf defaults applied). */
+export type AuthSecurityConfig = NonNullable<Static<typeof AuthConfigSchema>['security']>;
+/** The RB-2 generic OIDC / SSO issuer block (`providers.oidc`). */
+export type AuthOidcConfig = Static<typeof OidcProviderSchema>;
 export type AuthConfig = Static<typeof AuthConfigSchema>;
 export declare const RateLimitsConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
@@ -172,7 +245,6 @@ export declare const RateLimitsConfigSchema: import("@sinclair/typebox").TObject
 export type RateLimitsConfig = Static<typeof RateLimitsConfigSchema>;
 export declare const FilesConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
-    bucketRef: import("@sinclair/typebox").TString;
     uploadUrlTtl: import("@sinclair/typebox").TInteger;
     downloadUrlTtl: import("@sinclair/typebox").TInteger;
     quotas: import("@sinclair/typebox").TObject<{
@@ -181,10 +253,6 @@ export declare const FilesConfigSchema: import("@sinclair/typebox").TObject<{
         maxObjectCount: import("@sinclair/typebox").TInteger;
     }>;
     allowedContentTypes: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
-    contentScan: import("@sinclair/typebox").TObject<{
-        enabled: import("@sinclair/typebox").TBoolean;
-        quarantineOnFail: import("@sinclair/typebox").TBoolean;
-    }>;
     sharedLinks: import("@sinclair/typebox").TObject<{
         enabled: import("@sinclair/typebox").TBoolean;
         maxTtl: import("@sinclair/typebox").TInteger;
@@ -268,9 +336,6 @@ export declare const McpConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     exposureLevel: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"all">, import("@sinclair/typebox").TLiteral<"read-only">, import("@sinclair/typebox").TLiteral<"custom">]>;
     allowToolList: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
-    scopedKey: import("@sinclair/typebox").TObject<{
-        perAgentKeys: import("@sinclair/typebox").TBoolean;
-    }>;
     rateLimits: import("@sinclair/typebox").TObject<{
         toolCallsPerMin: import("@sinclair/typebox").TInteger;
     }>;
@@ -328,9 +393,6 @@ export declare const ActivityFeedConfigSchema: import("@sinclair/typebox").TObje
         copyLimit: import("@sinclair/typebox").TInteger;
         maxFollowing: import("@sinclair/typebox").TInteger;
     }>;
-    aggregation: import("@sinclair/typebox").TObject<{
-        maxGroupActivities: import("@sinclair/typebox").TInteger;
-    }>;
     realtime: import("@sinclair/typebox").TObject<{
         enabled: import("@sinclair/typebox").TBoolean;
     }>;
@@ -338,9 +400,6 @@ export declare const ActivityFeedConfigSchema: import("@sinclair/typebox").TObje
         enabled: import("@sinclair/typebox").TBoolean;
         digestCadence: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"off">, import("@sinclair/typebox").TLiteral<"hourly">, import("@sinclair/typebox").TLiteral<"daily">]>;
     }>;
-    rateLimit: import("@sinclair/typebox").TObject<{
-        addPerSec: import("@sinclair/typebox").TInteger;
-    }>;
 }>;
 export type ActivityFeedConfig = Static<typeof ActivityFeedConfigSchema>;
 export declare const VectorSearchConfigSchema: import("@sinclair/typebox").TObject<{
@@ -458,6 +517,7 @@ export declare const PaymentsConfigSchema: import("@sinclair/typebox").TObject<{
         publicSdkKey: import("@sinclair/typebox").TString;
         secretApiKeyRef: import("@sinclair/typebox").TString;
         webhookSecretRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        acceptSandbox: import("@sinclair/typebox").TBoolean;
     }>>;
     paypal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         clientIdRef: import("@sinclair/typebox").TString;
@@ -466,9 +526,6 @@ export declare const PaymentsConfigSchema: import("@sinclair/typebox").TObject<{
         sandbox: import("@sinclair/typebox").TBoolean;
     }>>;
     returnUrl: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
-    prices: import("@sinclair/typebox").TObject<{
-        catalogRef: import("@sinclair/typebox").TString;
-    }>;
     defaults: import("@sinclair/typebox").TObject<{
         currency: import("@sinclair/typebox").TString;
         trialDays: import("@sinclair/typebox").TInteger;
@@ -491,19 +548,19 @@ export declare const PaymentsConfigSchema: import("@sinclair/typebox").TObject<{
         }>>;
         priceMap: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
         autoRefundOnJobFailure: import("@sinclair/typebox").TBoolean;
+        grace: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            pastDueDays: import("@sinclair/typebox").TInteger;
+        }>>;
+        enforcePeriodEnd: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            slackHours: import("@sinclair/typebox").TInteger;
+        }>>;
     }>>;
-    webhooks: import("@sinclair/typebox").TObject<{
-        forwardToTenantUrl: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
-    }>;
 }>;
 export type PaymentsConfig = Static<typeof PaymentsConfigSchema>;
 export declare const FunctionsConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
-    runtime: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"isolate">, import("@sinclair/typebox").TLiteral<"container">]>;
     defaultLimits: import("@sinclair/typebox").TObject<{
         cpuMs: import("@sinclair/typebox").TInteger;
-        timeoutMs: import("@sinclair/typebox").TInteger;
-        memoryMb: import("@sinclair/typebox").TInteger;
     }>;
     metering: import("@sinclair/typebox").TObject<{
         enabled: import("@sinclair/typebox").TBoolean;
@@ -567,14 +624,8 @@ export declare const CopilotConfigSchema: import("@sinclair/typebox").TObject<{
             guestToolAllow: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
         }>>;
     }>>;
-    escalation: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-        enabled: import("@sinclair/typebox").TBoolean;
-        handler: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"comments">, import("@sinclair/typebox").TLiteral<"notifications">]>;
-        notifyTemplate: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
-    }>>;
     limits: import("@sinclair/typebox").TObject<{
         consumeCredits: import("@sinclair/typebox").TBoolean;
-        tokensPerUserPerDay: import("@sinclair/typebox").TInteger;
     }>;
     widget: import("@sinclair/typebox").TObject<{
         enabled: import("@sinclair/typebox").TBoolean;
@@ -590,6 +641,21 @@ export declare const CONFIG_FLAG_CAP = 15;
  * Per features/auth.md §4: an OPTIONAL object (e.g. a provider credential
  * block) counts as ONE flag — the tenant's decision is "configure it or
  * not", not each inner ref. */
+/** The auth lifecycle events an `authHook` binding may name (F4-30) — the
+ * closed union `packages/config` types as AuthHookEvent; the control-plane
+ * reconciler maps each to its `auth.<event>` audit-event prefix. */
+export declare const AUTH_HOOK_EVENTS: readonly ["user.created", "session.created", "session.revoked", "signin.failure"];
+export type AuthHookEvent = (typeof AUTH_HOOK_EVENTS)[number];
+/** F4-29 test-recipient entry grammar (shared by the validator and auth-v1's
+ * matcher): an exact email, a `*@domain` glob, or a +E.164 phone number. */
+export declare const TEST_RECIPIENT_EMAIL_RE: RegExp;
+export declare const TEST_RECIPIENT_GLOB_RE: RegExp;
+export declare const TEST_RECIPIENT_E164_RE: RegExp;
+export declare function isTestRecipientPattern(entry: string): boolean;
+/** True iff `identifier` (an email today) matches one configured entry:
+ * exact (case-insensitive) or the `*@domain` glob. +E.164 entries never match
+ * an email. */
+export declare function matchesTestRecipient(identifier: string, entries: readonly string[] | undefined): boolean;
 export declare function countLeaves(schema: TSchema): number;
 export interface ConfigValidation {
     ok: boolean;