@mccaskie-labs/workbench-config 0.1.18 → 0.1.20

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @mccaskie-labs/workbench-config
 
+## 0.1.20
+
+### Patch Changes
+
+- Vendor settings baseline: sign-in codes (`supabase.auth.email_code_lifetime`) now stay valid for one hour (3600 seconds), Supabase's default, as Robert decided. It was 10 minutes.
+
+## 0.1.19
+
+### Patch Changes
+
+- The vendor settings baseline: `VENDOR_SETTINGS`, the register of settings that live in a vendor's dashboard (id, API field, value, where it is, what breaks if it changes), starting with Supabase sign-in: six-digit email codes, a 10-minute code lifetime, the Send Email hook on, current password to change a password, secure email change. A project changes a row in `vendor-settings.json` (`VENDOR_SETTINGS_FILE`) with a reason; `resolveVendorSettings` applies it and names every problem at once. `SEND_EMAIL_HOOK_PATH` and `SEND_EMAIL_HOOK_SECRET` name the hook's address and the Worker secret. Control applies the baseline with `vendor_settings_apply` and checks it daily.
+
 ## 0.1.18
 
 ### Patch Changes

package/README.md

@@ -28,6 +28,7 @@ const { WORKBENCH_GATEWAY_KEY } = config.parse(env)
 | `redact(value)`, `redactAll(text, secrets)` | `[redacted]` in place of a secret, for logs |
 | `capabilities`, `MANIFEST_VERSION`, `capabilitySchema` | The Workbench capabilities manifests and their schema. The JSON files are also at `@mccaskie-labs/workbench-config/capabilities/<component>.json` |
 | `defineBrand(json)`, `brandSchema`, `resolveBrand`, `BRAND_DEFAULTS`, `BRAND_FILE` | The app's brand file, `brand.json` at the repo root: `name`, `siteUrl` (https), `logo.url` (https PNG, JPEG or SVG; optional `alt`, `width`, `height`), `colours.primary` (`#rrggbb`; `text`, `background`, `muted` default), optional `fonts.heading`/`fonts.body` (`{ family, url? }`, `url` an https stylesheet), `supportEmail` and `footer`. Unknown keys fail. Account emails, PDFs and Supabase's sign-in emails all read it |
+| `VENDOR_SETTINGS`, `resolveVendorSettings(file, env)`, `vendorSettingsFileSchema`, `VENDOR_SETTINGS_FILE`, `SEND_EMAIL_HOOK`, `SEND_EMAIL_HOOK_PATH`, `SEND_EMAIL_HOOK_SECRET` | The vendor settings baseline: settings that live in a vendor dashboard (field, value, where it is, what breaks if it changes). A project changes a row in `vendor-settings.json` at its repo root, with a reason. Control applies it with `vendor_settings_apply` and compares it every day |
 | `DEFAULT_GATEWAY_URL` | `https://gateway.mccaskielabs.dev` |
 
 `npx workbench-config check [dir]` compares the variable names in `.dev.vars` with `.dev.vars.example` and prints names only.

package/capabilities/database.json

@@ -20,7 +20,8 @@
       "sb_migration_rollback",
       "sb_query",
       "sb_project_delete",
-      "cf_worker_secret_put"
+      "cf_worker_secret_put",
+      "vendor_settings_apply"
     ]
   },
   "config": [
@@ -91,6 +92,12 @@
       "gate": "two_step_when",
       "when": "source supabase_secret, or replacing a secret that exists",
       "ships": "4"
+    },
+    {
+      "tool": "vendor_settings_apply",
+      "gate": "two_step_when",
+      "when": "production, after the first successful apply on that database; staging and check_only are free",
+      "ships": "5"
     }
   ],
   "rules": [
@@ -128,6 +135,13 @@
       "text": "Ship code that names a table, column or function production's database lacks; check with npx workbench-supabase check:prod-schema.",
       "enforced_by": "review",
       "probe": "database.prod-schema-check"
+    },
+    {
+      "id": "database.vendor-settings-baseline",
+      "kind": "must",
+      "text": "Keep Supabase's sign-in settings at the Workbench baseline (workbench-config VENDOR_SETTINGS), or record a project's change in vendor-settings.json with a reason. Control applies it with vendor_settings_apply and checks it every day.",
+      "enforced_by": "control",
+      "probe": "database.vendor-settings"
     }
   ],
   "examples": [
@@ -181,6 +195,13 @@
       "two_step": true,
       "cost_hint_usd": 0,
       "note": "sb_query on production with a write returns a confirmation, not a result"
+    },
+    {
+      "id": "database.vendor-settings",
+      "half": "drill",
+      "expect": "pass",
+      "cost_hint_usd": 0,
+      "note": "vendor_settings_apply check_only reports that both databases match the baseline, the Send Email hook included"
     }
   ]
 }

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "d0231144218c";
+export declare const MANIFEST_VERSION: "71462ff7fe4c";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -421,7 +421,7 @@ export declare const capabilities: {
         readonly summary: "Each project has its own Supabase projects, <id>-staging and <id>-production. Apps use them natively through workbench-supabase; Control creates them, writes their URL and keys onto the Workers, and applies migrations read from the repo.";
         readonly status: "built";
         readonly surfaces: {
-            readonly tools: readonly ["sb_project_create", "sb_migration_apply", "sb_migration_rollback", "sb_query", "sb_project_delete", "cf_worker_secret_put"];
+            readonly tools: readonly ["sb_project_create", "sb_migration_apply", "sb_migration_rollback", "sb_query", "sb_project_delete", "cf_worker_secret_put", "vendor_settings_apply"];
             readonly package: readonly ["supabaseConfig", "createBrowserClient", "createServerClient", "createUserClient", "createServiceClient", "WorkbenchSupabaseError"];
         };
         readonly config: readonly [{
@@ -471,6 +471,11 @@ export declare const capabilities: {
             readonly gate: "two_step_when";
             readonly when: "source supabase_secret, or replacing a secret that exists";
             readonly ships: "4";
+        }, {
+            readonly tool: "vendor_settings_apply";
+            readonly gate: "two_step_when";
+            readonly when: "production, after the first successful apply on that database; staging and check_only are free";
+            readonly ships: "5";
         }];
         readonly rules: readonly [{
             readonly id: "database.rls-isolates-users";
@@ -502,6 +507,12 @@ export declare const capabilities: {
             readonly text: "Ship code that names a table, column or function production's database lacks; check with npx workbench-supabase check:prod-schema.";
             readonly enforced_by: "review";
             readonly probe: "database.prod-schema-check";
+        }, {
+            readonly id: "database.vendor-settings-baseline";
+            readonly kind: "must";
+            readonly text: "Keep Supabase's sign-in settings at the Workbench baseline (workbench-config VENDOR_SETTINGS), or record a project's change in vendor-settings.json with a reason. Control applies it with vendor_settings_apply and checks it every day.";
+            readonly enforced_by: "control";
+            readonly probe: "database.vendor-settings";
         }];
         readonly examples: readonly [{
             readonly id: "database.example.user-client";
@@ -546,6 +557,12 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly two_step: true;
             readonly note: "sb_query on production with a write returns a confirmation, not a result";
+        }, {
+            readonly id: "database.vendor-settings";
+            readonly half: "drill";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+            readonly note: "vendor_settings_apply check_only reports that both databases match the baseline, the Send Email hook included";
         }];
     };
     readonly email: {

package/dist/capabilities.gen.js

@@ -1,6 +1,6 @@
 // Generated by `npm run capabilities:build` from capabilities/*.json. Do not edit.
 // check:capabilities fails in Checks when this file is stale.
-export const MANIFEST_VERSION = "d0231144218c";
+export const MANIFEST_VERSION = "71462ff7fe4c";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -620,7 +620,8 @@ export const capabilities = {
                 "sb_migration_rollback",
                 "sb_query",
                 "sb_project_delete",
-                "cf_worker_secret_put"
+                "cf_worker_secret_put",
+                "vendor_settings_apply"
             ],
             "package": [
                 "supabaseConfig",
@@ -699,6 +700,12 @@ export const capabilities = {
                 "gate": "two_step_when",
                 "when": "source supabase_secret, or replacing a secret that exists",
                 "ships": "4"
+            },
+            {
+                "tool": "vendor_settings_apply",
+                "gate": "two_step_when",
+                "when": "production, after the first successful apply on that database; staging and check_only are free",
+                "ships": "5"
             }
         ],
         "rules": [
@@ -736,6 +743,13 @@ export const capabilities = {
                 "text": "Ship code that names a table, column or function production's database lacks; check with npx workbench-supabase check:prod-schema.",
                 "enforced_by": "review",
                 "probe": "database.prod-schema-check"
+            },
+            {
+                "id": "database.vendor-settings-baseline",
+                "kind": "must",
+                "text": "Keep Supabase's sign-in settings at the Workbench baseline (workbench-config VENDOR_SETTINGS), or record a project's change in vendor-settings.json with a reason. Control applies it with vendor_settings_apply and checks it every day.",
+                "enforced_by": "control",
+                "probe": "database.vendor-settings"
             }
         ],
         "examples": [
@@ -789,6 +803,13 @@ export const capabilities = {
                 "cost_hint_usd": 0,
                 "two_step": true,
                 "note": "sb_query on production with a write returns a confirmation, not a result"
+            },
+            {
+                "id": "database.vendor-settings",
+                "half": "drill",
+                "expect": "pass",
+                "cost_hint_usd": 0,
+                "note": "vendor_settings_apply check_only reports that both databases match the baseline, the Send Email hook included"
             }
         ]
     },

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, type Capa
 export { capabilities, MANIFEST_VERSION, type Alias, type GatewayScope } from "./capabilities.gen.ts";
 export { compareDevVars, parseDevVarNames } from "./dev-vars.ts";
 export { brandSchema, defineBrand, BRAND_FILE, resolveBrand, BRAND_DEFAULTS, type Brand, type ResolvedBrand } from "./brand.ts";
+export { VENDOR_SETTINGS, VENDOR_SETTINGS_FILE, SEND_EMAIL_HOOK, SEND_EMAIL_HOOK_PATH, SEND_EMAIL_HOOK_SECRET, vendorSettingsFileSchema, resolveVendorSettings, type VendorSetting, type VendorSettingEnv, type VendorSettingsFile, type ResolvedVendorSetting, } from "./vendor-settings.ts";

package/dist/index.js

@@ -6,3 +6,4 @@ export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, } from ".
 export { capabilities, MANIFEST_VERSION } from "./capabilities.gen.js";
 export { compareDevVars, parseDevVarNames } from "./dev-vars.js";
 export { brandSchema, defineBrand, BRAND_FILE, resolveBrand, BRAND_DEFAULTS } from "./brand.js";
+export { VENDOR_SETTINGS, VENDOR_SETTINGS_FILE, SEND_EMAIL_HOOK, SEND_EMAIL_HOOK_PATH, SEND_EMAIL_HOOK_SECRET, vendorSettingsFileSchema, resolveVendorSettings, } from "./vendor-settings.js";

package/dist/vendor-settings.d.ts

@@ -0,0 +1,97 @@
+import { z } from "zod";
+/**
+ * The vendor settings baseline (docs/spec.md §10, 11 November 2026, "Four
+ * shared tools from Robert's project standards", item 3). Settings that live
+ * in a vendor's dashboard, where no migration, test or review can see them.
+ * The standards' answer is a register re-applied by hand on every new
+ * project; Workbench keeps the register here and Control applies it
+ * (`vendor_settings_apply`) and compares it with the live values every day.
+ *
+ * Each row says the setting, its value, where it lives and what breaks if it
+ * changes. A project changes a row in `vendor-settings.json` at the root of
+ * its repo, with a reason, and Control reads that file from `main`:
+ *
+ *   { "overrides": [
+ *       { "id": "supabase.auth.email_code_length", "value": 8,
+ *         "reason": "The bank's audit asks for eight digits" } ] }
+ */
+/** Where a project's overrides sit in its repo. */
+export declare const VENDOR_SETTINGS_FILE = "vendor-settings.json";
+export type VendorSettingEnv = "staging" | "production";
+interface Row {
+    /** Permanent name: `<vendor>.<area>.<setting>`. Overrides name it. */
+    id: string;
+    vendor: "supabase";
+    area: "auth";
+    /** The field in the vendor's API (Supabase: PATCH /v1/projects/{ref}/config/auth). */
+    field: string;
+    /** Where a person finds it in the dashboard. */
+    where: string;
+    /** What breaks if it changes. */
+    breaks: string;
+}
+interface BooleanSetting extends Row {
+    type: "boolean";
+    value: boolean;
+}
+interface IntegerSetting extends Row {
+    type: "integer";
+    value: number;
+    min: number;
+    max: number;
+    unit?: string;
+}
+export type VendorSetting = BooleanSetting | IntegerSetting;
+/**
+ * The Send Email hook row. On means Supabase makes the code and calls the
+ * app's own endpoint, which sends the email through workbench-email and the
+ * Gateway (decided 11 November 2026: one sender, one set of words). Control
+ * also sets the hook's address and its signing secret, which it puts on the
+ * project's Worker as SEND_EMAIL_HOOK_SECRET; neither is a row of its own.
+ */
+export declare const SEND_EMAIL_HOOK = "supabase.auth.send_email_hook";
+/** The path on the app's own hostname that Supabase calls. Agreed with the sign-in kit (createSendEmailHook in workbench-email, PR #173). */
+export declare const SEND_EMAIL_HOOK_PATH = "/auth/send-email";
+/** The Worker secret that holds the hook's signing secret (v1,whsec_…). */
+export declare const SEND_EMAIL_HOOK_SECRET = "SEND_EMAIL_HOOK_SECRET";
+/** The baseline. Order is the order Control reports in. */
+export declare const VENDOR_SETTINGS: readonly VendorSetting[];
+/** The shape of `vendor-settings.json`. */
+export declare const vendorSettingsFileSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    overrides: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>;
+        reason: z.ZodString;
+        env: z.ZodOptional<z.ZodEnum<{
+            production: "production";
+            staging: "staging";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type VendorSettingsFile = z.infer<typeof vendorSettingsFileSchema>;
+/** A row with the value that applies to one project and environment. */
+export type ResolvedVendorSetting = VendorSetting & {
+    /** "default" from the baseline, or "override" from the project's file. */
+    source: "default" | "override";
+    /** The override's reason. */
+    reason?: string;
+    /** The baseline's value, when an override changed it. */
+    default?: boolean | number;
+};
+export type ResolveResult = {
+    ok: true;
+    settings: ResolvedVendorSetting[];
+} | {
+    ok: false;
+    problems: string[];
+};
+/**
+ * The settings for one environment: the baseline with the project's overrides
+ * applied. `file` is the parsed JSON of `vendor-settings.json`, or null when
+ * the repo has none. Returns every problem at once (an unknown id, a value of
+ * the wrong type or out of range, a row overridden twice) and no settings, so
+ * a bad file never half-applies.
+ */
+export declare function resolveVendorSettings(file: unknown, env: VendorSettingEnv): ResolveResult;
+export {};

package/dist/vendor-settings.js

@@ -0,0 +1,163 @@
+import { z } from "zod";
+/**
+ * The vendor settings baseline (docs/spec.md §10, 11 November 2026, "Four
+ * shared tools from Robert's project standards", item 3). Settings that live
+ * in a vendor's dashboard, where no migration, test or review can see them.
+ * The standards' answer is a register re-applied by hand on every new
+ * project; Workbench keeps the register here and Control applies it
+ * (`vendor_settings_apply`) and compares it with the live values every day.
+ *
+ * Each row says the setting, its value, where it lives and what breaks if it
+ * changes. A project changes a row in `vendor-settings.json` at the root of
+ * its repo, with a reason, and Control reads that file from `main`:
+ *
+ *   { "overrides": [
+ *       { "id": "supabase.auth.email_code_length", "value": 8,
+ *         "reason": "The bank's audit asks for eight digits" } ] }
+ */
+/** Where a project's overrides sit in its repo. */
+export const VENDOR_SETTINGS_FILE = "vendor-settings.json";
+/**
+ * The Send Email hook row. On means Supabase makes the code and calls the
+ * app's own endpoint, which sends the email through workbench-email and the
+ * Gateway (decided 11 November 2026: one sender, one set of words). Control
+ * also sets the hook's address and its signing secret, which it puts on the
+ * project's Worker as SEND_EMAIL_HOOK_SECRET; neither is a row of its own.
+ */
+export const SEND_EMAIL_HOOK = "supabase.auth.send_email_hook";
+/** The path on the app's own hostname that Supabase calls. Agreed with the sign-in kit (createSendEmailHook in workbench-email, PR #173). */
+export const SEND_EMAIL_HOOK_PATH = "/auth/send-email";
+/** The Worker secret that holds the hook's signing secret (v1,whsec_…). */
+export const SEND_EMAIL_HOOK_SECRET = "SEND_EMAIL_HOOK_SECRET";
+/** The baseline. Order is the order Control reports in. */
+export const VENDOR_SETTINGS = Object.freeze([
+    {
+        id: "supabase.auth.email_code_length",
+        vendor: "supabase",
+        area: "auth",
+        field: "mailer_otp_length",
+        type: "integer",
+        value: 6,
+        min: 6,
+        max: 10,
+        unit: "digits",
+        where: "Supabase: Authentication, Sign In / Providers, Email, Email OTP Length",
+        breaks: "Emails carry a code of a different length from the one the app's screens, words and tests expect. It once shipped as eight digits while every document said six.",
+    },
+    {
+        id: "supabase.auth.email_code_lifetime",
+        vendor: "supabase",
+        area: "auth",
+        field: "mailer_otp_exp",
+        type: "integer",
+        value: 3_600,
+        min: 60,
+        max: 86_400,
+        unit: "seconds",
+        where: "Supabase: Authentication, Sign In / Providers, Email, Email OTP Expiration",
+        breaks: "Shorter: people with slow mail are told their code is wrong. Longer: a leaked code works for longer.",
+    },
+    {
+        id: SEND_EMAIL_HOOK,
+        vendor: "supabase",
+        area: "auth",
+        field: "hook_send_email_enabled",
+        type: "boolean",
+        value: true,
+        where: "Supabase: Authentication, Auth Hooks, Send Email hook",
+        breaks: "Off: Supabase sends its own sign-in emails from its own sender, with its own words, outside the catalogue and its tests. On with no handler in the app: every sign-in email fails, loudly.",
+    },
+    {
+        id: "supabase.auth.password_change_needs_current",
+        vendor: "supabase",
+        area: "auth",
+        field: "security_update_password_require_current_password",
+        type: "boolean",
+        value: true,
+        where: "Supabase: Authentication, Sign In / Providers, Email, Require current password when updating",
+        breaks: "Off: anyone holding a signed-in session (a borrowed phone, a sign-in code) can change the password and keep the account.",
+    },
+    {
+        id: "supabase.auth.email_change_confirms_both",
+        vendor: "supabase",
+        area: "auth",
+        field: "mailer_secure_email_change_enabled",
+        type: "boolean",
+        value: true,
+        where: "Supabase: Authentication, Sign In / Providers, Email, Secure email change",
+        breaks: "Off: an address change is confirmed from the new address only, so the owner of the old one never hears of it.",
+    },
+]);
+const override = z.strictObject({
+    id: z.string().min(1).max(100),
+    value: z.union([z.boolean(), z.number()]),
+    /** Why this project differs. Shown on every report. */
+    reason: z.string().trim().min(10).max(300),
+    /** Only this environment. Default both. */
+    env: z.enum(["staging", "production"]).optional(),
+});
+/** The shape of `vendor-settings.json`. */
+export const vendorSettingsFileSchema = z.strictObject({
+    $schema: z.string().optional(),
+    overrides: z.array(override).max(100),
+});
+/**
+ * The settings for one environment: the baseline with the project's overrides
+ * applied. `file` is the parsed JSON of `vendor-settings.json`, or null when
+ * the repo has none. Returns every problem at once (an unknown id, a value of
+ * the wrong type or out of range, a row overridden twice) and no settings, so
+ * a bad file never half-applies.
+ */
+export function resolveVendorSettings(file, env) {
+    if (file === null || file === undefined)
+        return { ok: true, settings: VENDOR_SETTINGS.map((s) => ({ ...s, source: "default" })) };
+    const parsed = vendorSettingsFileSchema.safeParse(file);
+    if (!parsed.success) {
+        return { ok: false, problems: parsed.error.issues.map((i) => `${VENDOR_SETTINGS_FILE} ${i.path.join(".") || "(file)"}: ${i.message}`) };
+    }
+    const problems = [];
+    const byId = new Map(VENDOR_SETTINGS.map((s) => [s.id, s]));
+    const seen = new Set();
+    const chosen = new Map();
+    for (const [i, o] of parsed.data.overrides.entries()) {
+        const at = `${VENDOR_SETTINGS_FILE} overrides.${i}`;
+        const row = byId.get(o.id);
+        if (!row) {
+            problems.push(`${at}: no setting "${o.id}". Known: ${[...byId.keys()].join(", ")}.`);
+            continue;
+        }
+        for (const e of o.env ? [o.env] : ["staging", "production"]) {
+            const key = `${o.id}@${e}`;
+            if (seen.has(key))
+                problems.push(`${at}: ${o.id} is overridden twice for ${e}.`);
+            seen.add(key);
+        }
+        const p = valueProblem(row, o.value);
+        if (p) {
+            problems.push(`${at}: ${p}`);
+            continue;
+        }
+        if (o.env === undefined || o.env === env)
+            chosen.set(o.id, { value: o.value, reason: o.reason });
+    }
+    if (problems.length > 0)
+        return { ok: false, problems };
+    return {
+        ok: true,
+        settings: VENDOR_SETTINGS.map((s) => {
+            const c = chosen.get(s.id);
+            if (!c)
+                return { ...s, source: "default" };
+            return { ...s, value: c.value, source: "override", reason: c.reason, default: s.value };
+        }),
+    };
+}
+function valueProblem(row, value) {
+    if (row.type === "boolean")
+        return typeof value === "boolean" ? null : `${row.id} takes true or false.`;
+    if (typeof value !== "number" || !Number.isInteger(value))
+        return `${row.id} takes a whole number.`;
+    if (value < row.min || value > row.max)
+        return `${row.id} must be from ${row.min} to ${row.max}${row.unit ? ` ${row.unit}` : ""}.`;
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Workbench app configuration: WORKBENCH_ENV, typed variables that fail by name, secrets that are never printed, and the capabilities manifest.",
   "license": "UNLICENSED",
   "type": "module",