@vxil/feature-configs 0.3.1 → 0.4.1

package/src/index.ts

@@ -49,7 +49,20 @@ export const NOTIFICATION_TEMPLATE_PLACEHOLDERS: Readonly<Record<string, readonl
   'magic-link': ['url', 'expires_minutes'],
   'otp-code': ['code', 'expires_minutes'],
   welcome: ['app_name', 'first_name', 'first_name_greeting'],
-  transactional: ['subject', 'paragraph', 'cta_label', 'cta_url'],
+  // `cta` (G-78) is a SLOT, not a data key: an override that writes `{{cta}}`
+  // chooses where the escaped CTA anchor built from cta_label + cta_url lands.
+  // Absent from the built-in bodies (which append it), so the worker parity
+  // suite pins it explicitly — see templates.test.ts.
+  transactional: ['subject', 'paragraph', 'cta_label', 'cta_url', 'cta'],
+};
+
+/** Placeholders that are SLOTS in the BODY parts only — the renderer splits
+ * `html`/`text` on them (templates.ts `CTA_SLOT`) but the subject goes through
+ * the plain interpolator, where the same token is just a data key that does not
+ * exist and renders EMPTY. Rejected in `subject` for exactly the reason the
+ * whole allow-list exists: a silent empty render in a live email. */
+export const NOTIFICATION_TEMPLATE_SLOT_PLACEHOLDERS: Readonly<Record<string, readonly string[]>> = {
+  transactional: ['cta'],
 };
 
 /** Per-override caps (D4). Bodies are emails, not documents. */
@@ -108,13 +121,30 @@ export function validateNotificationOverrides(
         continue;
       }
       const variant = byLocale![locale]!;
+      if (typeof variant !== 'object' || variant === null) {
+        errs.push(`/templates/overrides/${templateId}/${locale}: must be an object with at least one of subject, html, text`);
+        continue;
+      }
+      // G-78 — every part is OPTIONAL (a body-only translation inherits the
+      // built-in subject), but an ALL-EMPTY variant is the new "inert config"
+      // and fails LOUD rather than silently rendering the built-in.
+      const nonEmpty = (['subject', 'html', 'text'] as const)
+        .filter((p) => typeof variant[p] === 'string' && variant[p] !== '');
+      if (nonEmpty.length === 0) {
+        errs.push(`/templates/overrides/${templateId}/${locale}: set at least one of subject, html, text`);
+        continue;
+      }
+      // body-only SLOTS are not subject placeholders (see the map's doc comment)
+      const slots = NOTIFICATION_TEMPLATE_SLOT_PLACEHOLDERS[templateId] ?? [];
+      const subjectAllowed = allowed.filter((k) => !slots.includes(k));
       for (const part of ['subject', 'html', 'text'] as const) {
         const body = variant[part];
         if (typeof body !== 'string') continue;
+        const ok = part === 'subject' ? subjectAllowed : allowed;
         for (const m of body.matchAll(NOTIF_PLACEHOLDER_RE)) {
           const key = m[1]!;
-          if (!allowed.includes(key)) {
-            errs.push(`/templates/overrides/${templateId}/${locale}/${part}: unknown placeholder '{{${key}}}' (allowed: ${allowed.join(', ')})`);
+          if (!ok.includes(key)) {
+            errs.push(`/templates/overrides/${templateId}/${locale}/${part}: unknown placeholder '{{${key}}}' (allowed: ${ok.join(', ')})`);
           }
         }
       }
@@ -183,7 +213,7 @@ export const NotificationsConfigSchema = Type.Object({
       allowOverride: Type.Boolean({ default: false }),
       // D4 (2026-09-10) — TENANT-AUTHORED PER-LOCALE OVERRIDES of the SHIPPED
       // template ids, as config DATA (a Record = 1 leaf, catalog size never
-      // moves the count). Shape: { [templateId]: { [locale]: { subject,
+      // moves the count). Shape: { [templateId]: { [locale]: { subject?,
       // html?, text? } } }. Same escaped `{{placeholder}}` grammar as the
       // built-ins — the worker reuses ONE renderer, so escaping/URL-scheme
       // sanitisation are identical and there is no raw-output syntax.
@@ -192,8 +222,15 @@ export const NotificationsConfigSchema = Type.Object({
       // LOUD, never silently inert) overrides present with allowOverride:false.
       overrides: Type.Optional(Type.Record(
         Type.String(),
+        // G-78: `subject` is OPTIONAL like html/text — a PARTIAL override
+        // inherits each omitted part from the built-in, so a body-only
+        // translation no longer forces you to restate the subject (and a
+        // subject-only 'ar' override no longer pairs an Arabic subject with the
+        // English built-in body). A strict widening: every config valid before
+        // this change is still valid. validateNotificationOverrides rejects the
+        // one shape this opens up — a variant with NO non-empty part.
         Type.Record(Type.String(), Type.Object({
-          subject: Type.String({ minLength: 1, maxLength: NOTIF_OVERRIDE_SUBJECT_MAX }),
+          subject: Type.Optional(Type.String({ minLength: 1, maxLength: NOTIF_OVERRIDE_SUBJECT_MAX })),
           html: Type.Optional(Type.String({ maxLength: NOTIF_OVERRIDE_BODY_MAX })),
           text: Type.Optional(Type.String({ maxLength: NOTIF_OVERRIDE_BODY_MAX })),
         })),
@@ -445,10 +482,38 @@ export const AuthConfigSchema = Type.Object({
     { required: Type.Boolean({ default: false }) },
     { default: {} },
   ),
-  magicLink: Type.Object(
-    { tokenTtlMinutes: Type.Integer({ default: 15, minimum: 5, maximum: 60 }) },
+  // P1-16 (2026-09-18): magicLink is now an OPTIONAL bag (= ONE leaf however
+  // many knobs it holds — the methods/session/password precedent) so the
+  // request cooldown could land without spending a second leaf. It KEEPS
+  // `default: {}`, so Value.Default still materializes
+  // `magicLink.tokenTtlMinutes` exactly as before — every persisted manifest
+  // folds byte-identically.
+  magicLink: Type.Optional(Type.Object(
+    {
+      tokenTtlMinutes: Type.Integer({ default: 15, minimum: 5, maximum: 60 }),
+      // P1-16: the per-(tenant, identifier) magic-link REQUEST cooldown — the
+      // `otp.resendCooldownSec` twin, same bounds so the two knobs read the
+      // same. A second request for the same address inside the window is a 429
+      // `magic_link_rate_limited` with a Retry-After header. Type.Optional with
+      // NO default (the `otp.testRecipients` precedent below) so existing
+      // manifests fold byte-identically; the 60s fallback is applied by the
+      // auth feature at read time. 0 disables the cooldown.
+      resendCooldownSec: Type.Optional(Type.Integer({ minimum: 0, maximum: 600 })),
+    },
     { default: {} },
-  ),
+  )),
+  // P1-5 identity continuity (2026-09-18) — OPT-IN registry adoption. When
+  // true, a sign-in by a method that PROVES control of the address — magic
+  // link, email OTP, or OAuth with a provider-verified address — reuses the id
+  // of the one matching pre-registered end-user (POST /v1/users) that has no
+  // account yet, instead of minting a fresh `user_<ulid>` and leaving the
+  // tenant with two records for one person. Password SIGN-UP never adopts: it
+  // proves nothing about the address (auth.md §8.1 PROVEN_ADOPT_METHODS).
+  // OFF by default, and Type.Optional with NO default: adoption means whoever
+  // proves control of a pre-registered address becomes that record — a change
+  // of security semantics for a tenant that bulk-imports contacts, whose
+  // addresses vxil never verified.
+  registryAdopt: Type.Optional(Type.Boolean()),
   // Email OTP sign-in (roadmap Tier-0) + the knobs step-up re-auth shares.
   // OPTIONAL bag = 1 leaf; absent ⇒ disabled (the worker gates on
   // otp?.enabled === true).
@@ -524,11 +589,12 @@ export type AuthOidcConfig = Static<typeof OidcProviderSchema>;
 // Leaves (auth wave 2026-09-10, D3): enabled(1) + methods(1, optional bag —
 // was 6) + providers(1, optional bag holding the four google/github/apple/
 // facebook credential blocks + the RB-2 `oidc` issuer block) + session(1, optional bag) + password(1,
-// optional bag) + emailVerification(1) + magicLink(1) + otp(1, optional bag)
+// optional bag) + emailVerification(1) + magicLink(1, optional bag) + otp(1, optional bag)
 // + anonymous(1, optional bag) + orgClaims(1, optional bag) + security(1,
-// optional bag) = 11. Cap = 15 — 4 leaves of headroom. Knobs added inside an
-// existing bag (session.maxConcurrent, otp.testRecipients, the security
-// sub-bags) never move the count.
+// optional bag) + registryAdopt(1, P1-5) = 12. Cap = 15 — 3 leaves of
+// headroom. Knobs added inside an existing bag (session.maxConcurrent,
+// otp.testRecipients, magicLink.resendCooldownSec, the security sub-bags)
+// never move the count.
 
 export type AuthConfig = Static<typeof AuthConfigSchema>;
 
@@ -620,8 +686,29 @@ export const WebhooksConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
   maxSubscriptions: Type.Integer({ default: 20, minimum: 1, maximum: 200 }),
   maxSources: Type.Integer({ default: 20, minimum: 1, maximum: 200 }),
+  // FAILURE-ALERT DIGEST (P0-2). Outbound subscriptions are the real-time
+  // channel; this is the "nobody is consuming them yet" fallback — a periodic
+  // e-mail summary of the tenant's FAILURE-class audit events (the level:
+  // 'failure' rows of the generated event catalog). Read by
+  // workers/control-plane/src/alertDigest.ts on the minute cron.
+  //
+  // RECIPIENTS ARE DELIBERATELY NOT CONFIGURABLE, and this deviation is
+  // journaled here the way RateLimitsConfigSchema journals its own: an
+  // arbitrary `to` would turn vxil's own sending identity into a relay for
+  // tenant-authored content and open a PII egress path out of the audit trail.
+  // The digest goes to the OWNER-role dashboard accounts of the project (cap
+  // 3), who already receive platform mail (invites, magic links, resets), so no
+  // new consent surface is created. An arbitrary recipient is a separate
+  // decision with its own abuse review.
+  //
+  // An Optional object bag counts as ONE leaf (the countLeaves rule).
+  alerts: Type.Optional(Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    minLevel: Type.Union([Type.Literal('warn'), Type.Literal('error')], { default: 'error' }),
+    digestMinutes: Type.Integer({ default: 15, minimum: 5, maximum: 1440 }),
+  })),
 });
-// Leaves: 3. Cap = 15.
+// Leaves: 3 + alerts(1, optional bag) = 4. Cap = 15.
 
 export type WebhooksConfig = Static<typeof WebhooksConfigSchema>;
 
@@ -1086,7 +1173,7 @@ export const AiConfigSchema = Type.Object({
   cache: Type.Object({ ttlSeconds: Type.Integer({ default: 0, minimum: 0 }) }, { default: {} }), // 0 = off
   limits: Type.Object({
     tokensPerUserPerDay: Type.Integer({ default: 0, minimum: 0 }), // 0 = unlimited
-    consumeCredits: Type.Boolean({ default: false }),              // reserve→settle (STUB until payments)
+    consumeCredits: Type.Boolean({ default: false }),              // LIVE: reserve→settle against the payments credit ledger (a job-routed generation reserves pre-generation and 402s insufficient_credits)
   }, { default: {} }),
   streaming: Type.Object({
     enabled: Type.Boolean({ default: true }),
@@ -1204,10 +1291,16 @@ export const PaymentsConfigSchema = Type.Object({
     projectId: Type.String(),
     publicSdkKey: Type.String(),
     secretApiKeyRef: Type.String(),
-    // Optional per-tenant webhook secret ref (public.tenant_secrets). When set,
-    // inbound RevenueCat webhooks are verified with THIS tenant's secret instead
-    // of the platform PROVIDER_WEBHOOK_SECRET — closes the multi-tenant RC
-    // webhook-forgery vector (mirrors stripe/paddle webhookSecretRef).
+    // Per-tenant webhook secret ref (public.tenant_secrets). Inbound RevenueCat
+    // webhooks are verified against THIS ref and nothing else: there is no
+    // platform-wide PROVIDER_WEBHOOK_SECRET fallback for a real payment provider
+    // (that fallback WAS the multi-tenant RC webhook-forgery vector; it is now
+    // frozen out by tests/ci/src/provider-webhook-secret-fallback.test.ts, which
+    // permits `secrets.webhookSecret` only in makeProvider's mock/default arm).
+    // Optional at the SCHEMA level only — leaving it unset does not disable
+    // verification, it fails CLOSED: every delivery is 401 bad_signature with a
+    // `sig_failed` row that can never be reprocessed. Mirrors stripe/paddle
+    // webhookSecretRef.
     webhookSecretRef: Type.Optional(Type.String()),
     // Environment integrity (money-path wave F1-4/D5). RevenueCat posts SANDBOX
     // and PRODUCTION events to the SAME webhook with the same auth header, so a
@@ -1276,7 +1369,7 @@ export const PaymentsConfigSchema = Type.Object({
     // Opt-in period-end enforcement (money-path operations wave, decision D2
     // option a). ABSENT (the default) = today's behaviour: a subscription whose
     // current_period_end passed with no provider event stays entitled forever
-    // (the provider is the only clock). PRESENT = the hourly reconcile sweep
+    // (the provider is the only clock). PRESENT = the nightly reconcile sweep
     // flips an `active`/`trialing` row whose current_period_end + slackHours
     // has passed with no renewal to status 'lapsed' (+ refold, +
     // payments.subscription.lapsed); a later provider renewal event revives it
@@ -1285,6 +1378,29 @@ export const PaymentsConfigSchema = Type.Object({
     enforcePeriodEnd: Type.Optional(Type.Object({
       slackHours: Type.Integer({ default: 72, minimum: 0, maximum: 720 }),
     })),
+    // (2026-09 P2) What to do with a one-off purchase whose `product_id` is NOT
+    // in productMap. 'error' (the DEFAULT and today's behaviour) stamps the
+    // delivery outcome `error`, emits payments.webhook_event.failed and lands a
+    // `stranded_webhook` reconcile finding. 'ignore' stamps it `ignored`, with
+    // no failure event and no stranded finding.
+    //
+    // WHY IT EXISTS: the trigger is `event.productId && !grantRule`, and Paddle
+    // carries items[0].price.product_id on EVERY transaction.completed —
+    // INCLUDING subscription-renewal transactions, whose money folds through the
+    // subscription.* events instead. A Paddle tenant that drives everything
+    // through tierMap/priceMap therefore got one `error` row + one failure event
+    // + one stranded finding PER RENEWAL, forever. 'ignore' is the one-line
+    // answer. The charge row is still recorded either way — only the ledger
+    // grant is declined — and an `ignored` row stays REPROCESSABLE, so mapping
+    // the product later and re-running the delivery folds it.
+    //
+    // NO SCHEMA DEFAULT ON PURPOSE: the config-write pipeline runs
+    // Value.Default, which MATERIALIZES an Optional-with-default into every
+    // persisted manifest — that would rewrite every payments manifest carrying a
+    // `ledger` bag and make `vxil push --dry-run` / `vxil diff` report drift for
+    // every payments tenant. The READER owns the default
+    // (`config.ledger?.unmappedProduct ?? 'error'`), which is the one definition.
+    unmappedProduct: Type.Optional(Type.Union([Type.Literal('error'), Type.Literal('ignore')])),
   })),
   // NB (money-path wave F3-19): the former `webhooks.forwardToTenantUrl` leaf
   // was DELETED — it had zero readers (never forwarded anything). Outbound
@@ -1377,11 +1493,46 @@ export const FunctionsConfigSchema = Type.Object({
         scopes: Type.Optional(Type.Array(Type.String())), // clamped via DENY_FUNCTION_SCOPES at deploy (admin/*/features:write/functions:write/secrets:write)
         secrets: Type.Optional(Type.Array(Type.String())), // names of tenant secrets injected at invoke time
         egressAllow: Type.Optional(Type.Array(Type.String())), // Outbound Worker allowlist hosts
+        // Per-function resource declarations. BOTH members are OPTIONAL (the bag
+        // used to REQUIRE all three, a latent 422 the moment anything sent it —
+        // nothing ever did, because the CLI never carried it) and BOTH are
+        // UNBOUNDED here on purpose: `deployFunction` validates the WHOLE merged
+        // manifest, `Value.Clean` strips unknown keys but never clamps
+        // out-of-range ones, so a min/max here would let ONE legacy entry 422
+        // every future deploy for that tenant. The bounds (cpuMs 5..300000,
+        // timeoutMs 1000..120000) are enforced at the ONE write path,
+        // `normalizeLimits` in the deploy handler, which also sanitizes pre-existing
+        // entries on merge.
+        //   cpuMs     — TIGHTENS the per-dispatch isolate CPU cap (never widens
+        //               FN_MAX_CPU_MS) and RAISES (never lowers) the metering
+        //               reserve, whose floor stays defaultLimits.cpuMs. THE
+        //               CONSEQUENCE, stated because the knob's name hides it:
+        //               the reserve is the payments HOLD, and the pro-rated
+        //               settle clamps the measured wall-ms into [floor, reserve]
+        //               — it can never commit more than it holds — so raising
+        //               the reserve raises the settle CEILING. An invoke whose
+        //               wall time exceeds defaultLimits.cpuMs (50) then settles
+        //               at its measured wall-ms instead of being capped at 50:
+        //               on a METERED tenant, declaring cpuMs raises the bill for
+        //               long-running functions (cpuMs: 1000 turns an 800 ms
+        //               invoke from 50 into 800). It does NOT move anyone's
+        //               availability — the ACCOUNT-global daily capacity budget
+        //               counts the platform's own estimate, never this value
+        //               (functions-v1 capacity.ts `capacityReserveCpuMs`).
+        //   timeoutMs — the wall budget for ONE outbound fetch, delivered to the
+        //               egress guard as an outbound parameter. NOT an invocation
+        //               budget: the INVOCATION is bounded by the platform's own
+        //               FN_MAX_INVOKE_MS deadline (default >= 5 min), which a
+        //               bigger per-fetch budget widens with you (audit FN-3).
+        // (F8-54's standing "strip the twins" note is DISCHARGED here: `memoryMb`
+        // is deleted — memory is fixed by the managed runtime and is not a
+        // per-dispatch option; the WfP dispatch bag takes { cpuMs, subRequests }.
+        // Value.Clean strips it from an old config, so such a config still loads
+        // and `vxil plan --explain` marks the key DROPPED.)
         limits: Type.Optional(
           Type.Object({
-            cpuMs: Type.Integer(),
-            timeoutMs: Type.Integer(),
-            memoryMb: Type.Integer(),
+            cpuMs: Type.Optional(Type.Integer()),
+            timeoutMs: Type.Optional(Type.Integer()),
           }),
         ),
         enabled: Type.Optional(Type.Boolean()),