@bongos/core 1.19.953 → 1.19.955

package/docs/module-api-changelog.md

@@ -2380,5 +2380,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.951 with no explicit bump. run 35686469735. (task 1002620)
   1.19.953 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.952 with no explicit bump. run 35687192774. (task 1002620)
+  1.19.954 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.953 with no explicit bump. run 35687914716. (task 1002620)
+  1.19.955 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.954 with no explicit bump. run 35690089430. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/env-manifest.js

@@ -0,0 +1,215 @@
+// modules/provisioning/env-manifest.js — the project ENV VAR MANIFEST: the NAMES a
+// project's environment variables have and what each one is for (task 1004062,
+// [ADR 0323](../../docs/adr/0323-hosting-is-three-shapes-and-we-are-not-the-landlord.md)
+// decision 6).
+//
+// **THE ONE RULE: THIS FILE NEVER HANDLES A VALUE.** Not stored, not accepted, not
+// logged, not returned, not encrypted-at-rest — there is nothing to encrypt, because a
+// variable NAME is not a secret (it appears in the source that reads it). The values live
+// on the deployment platform the running application reads them from, which already
+// encrypts, audits and rotates them; Bongos keeping a second copy would make this
+// platform the custodian of other companies' credentials in exchange for nothing the
+// manifest does not already deliver.
+//
+// The rule is enforced rather than stated. `rejectsValueField` is the boundary's answer
+// to a caller that sends one — a LOUD 400, never a silent drop — and
+// `../../tests/provisioning_env_manifest.mjs` asserts both that no row shape carries a
+// value field and that sending one is refused. A silent drop would be worse than storing
+// it: the caller would believe the platform had taken custody.
+//
+// What a manifest buys, and why the owner asked for it: "no project or code base works
+// without this". A builder — human or agent — writing code has to know which variables
+// exist and what each is for, or it invents a name the platform has never heard of and
+// the setup document is incomplete in a way nothing detects until deploy.
+//
+// PURE except the four db functions at the bottom, which take the pool as an argument
+// (the module's own convention — see provisioning.js). Reaches core only through
+// src/module-api.js, and requires this module's own siblings, never another module's.
+
+'use strict';
+
+// Where a variable can apply. Fixed and small on purpose: these are the three the
+// deployment platforms in ADR 0323 decision 3 actually name, and an open-ended list
+// would make "which environments does this project have" a second question nobody asked.
+// Mirrors the CHECK in provisioning_023_env_manifest.sql.
+const ENVIRONMENTS = Object.freeze(['production', 'preview', 'development']);
+
+// The conventional POSIX-ish environment variable name: a letter or underscore, then
+// letters, digits and underscores. UPPERCASE is not enforced — `npm_config_*` and
+// `PORT` coexist in real projects, and refusing a lowercase name a project genuinely
+// reads would make the manifest wrong rather than tidy. PURE.
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENV_NAME_MAX = 128;
+
+function isValidEnvName(name) {
+  const s = typeof name === 'string' ? name.trim() : '';
+  if (!s || s.length > ENV_NAME_MAX) return false;
+  return ENV_NAME_RE.test(s);
+}
+
+// Why a name is being refused, in the words a caller can act on. Returns null when the
+// name is fine. Separate from isValidEnvName so the route's message and the predicate
+// cannot drift. PURE.
+function envNameRefusal(name) {
+  if (typeof name !== 'string' || !name.trim()) return 'A variable needs a name.';
+  const s = name.trim();
+  if (s.length > ENV_NAME_MAX) return `That name is ${s.length} characters; the limit is ${ENV_NAME_MAX}.`;
+  if (/\s/.test(s)) return `"${s}" contains a space — an environment variable name cannot.`;
+  if (/^[0-9]/.test(s)) return `"${s}" starts with a digit — an environment variable name cannot.`;
+  if (!ENV_NAME_RE.test(s)) return `"${s}" is not a valid environment variable name: letters, digits and underscores only, not starting with a digit.`;
+  return null;
+}
+
+// Coerce the caller's environment list to the known set. An ABSENT or empty list means
+// "everywhere", which is stored as all three rather than as an empty array: a variable
+// the code reads is read in every environment unless somebody says otherwise, and
+// storing the explicit set means a later reader never has to know that an empty array
+// was a special case. An unknown entry is dropped here and refused by the route — the
+// drop is the backstop, not the answer. PURE.
+function normalizeEnvironments(list) {
+  if (list === undefined || list === null) return [...ENVIRONMENTS];
+  const arr = Array.isArray(list) ? list : [list];
+  const kept = [];
+  for (const raw of arr) {
+    const s = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+    if (ENVIRONMENTS.includes(s) && !kept.includes(s)) kept.push(s);
+  }
+  if (kept.length === 0) return [...ENVIRONMENTS];
+  // Stored in the canonical order, so two callers naming the same set produce equal rows
+  // and a diff of two manifests is about content rather than about ordering.
+  return ENVIRONMENTS.filter((e) => kept.includes(e));
+}
+
+// The environments a caller named that are not environments. The route refuses on this
+// rather than silently keeping the remainder: dropping 'staging' would tell the owner
+// their variable applies somewhere it does not. PURE.
+function unknownEnvironments(list) {
+  if (list === undefined || list === null) return [];
+  const arr = Array.isArray(list) ? list : [list];
+  const bad = [];
+  for (const raw of arr) {
+    const s = typeof raw === 'string' ? raw.trim().toLowerCase() : String(raw);
+    if (!ENVIRONMENTS.includes(s) && !bad.includes(s)) bad.push(s);
+  }
+  return bad;
+}
+
+// The field names that would be a VALUE, in every spelling a caller might reach for.
+// Checked as a group so the refusal can name what was sent.
+const VALUE_FIELDS = Object.freeze(['value', 'values', 'secret', 'secret_value', 'val', 'default_value', 'example_value']);
+
+// Refuse a body that carries a value, LOUDLY. Returns null when clean, else a
+// { code, message } the route fails with.
+//
+// Loud and not a silent strip, and the distinction is the whole point: a caller who
+// POSTs a secret and gets a 201 back has every reason to believe the platform now holds
+// it — they may then delete it from the place that actually stores it. A 400 that says
+// "this platform does not take values" leaves them in no doubt, and nothing is written.
+// PURE.
+function rejectsValueField(body) {
+  if (!body || typeof body !== 'object') return null;
+  const sent = VALUE_FIELDS.filter((f) => Object.prototype.hasOwnProperty.call(body, f));
+  if (sent.length === 0) return null;
+  return {
+    code: 'value_not_accepted',
+    message: `This platform stores variable NAMES, never values — ${sent.join(', ')} ${sent.length === 1 ? 'was' : 'were'} not saved and nothing was recorded. Keep the value where the running application reads it (your deployment platform), and declare the name here so builders know it exists.`,
+  };
+}
+
+// The row shape every reader gets. Built by NAMING each column rather than spreading the
+// row, so a value column that somehow appeared in the table could still never leave
+// through this function. The test asserts the absence on this projection.
+function envVarRow(row) {
+  return {
+    id: String(row.id),
+    instance_id: String(row.instance_id),
+    name: row.name,
+    description: row.description ?? null,
+    environments: Array.isArray(row.environments) ? row.environments : [],
+    required: row.required !== false,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Storage (the pool is an argument — this module's convention)
+// ---------------------------------------------------------------------------
+
+// The declared surface for one project, name-ordered so two reads of an unchanged
+// manifest are byte-identical (a builder session diffs this).
+async function listEnvVars(db, instanceId) {
+  const { rows } = await db.query(
+    `SELECT * FROM provisioning_env_vars WHERE instance_id = $1 ORDER BY name ASC`,
+    [instanceId]
+  );
+  return rows.map(envVarRow);
+}
+
+// Declare a variable, or EDIT the declaration that name already has. The UNIQUE index on
+// (instance_id, name) makes a second POST an update rather than a duplicate: two rows
+// disagreeing about DATABASE_URL is a manifest that cannot be read, and the reader would
+// have no rule for choosing. Returns { row, created }.
+async function declareEnvVar(db, { instanceId, name, description = null, environments, required = true }) {
+  const { rows } = await db.query(
+    `INSERT INTO provisioning_env_vars (instance_id, name, description, environments, required)
+          VALUES ($1, $2, $3, $4, $5)
+     ON CONFLICT (instance_id, name) DO UPDATE
+            SET description = EXCLUDED.description,
+                environments = EXCLUDED.environments,
+                required = EXCLUDED.required,
+                updated_at = now()
+       RETURNING *, (xmax = 0) AS inserted`,
+    [instanceId, String(name).trim(), description, normalizeEnvironments(environments), required !== false]
+  );
+  return { row: envVarRow(rows[0]), created: rows[0].inserted === true };
+}
+
+// Edit one declaration by id, scoped to its project so a guessed id cannot reach another
+// owner's manifest. MERGE-patch: an omitted field is left alone, which is what lets the
+// hall edit a description without restating the environments. Returns the row, or null
+// when the id does not belong to that project.
+async function updateEnvVar(db, instanceId, id, patch = {}) {
+  const sets = ['updated_at = now()'];
+  const params = [instanceId, id];
+  if (Object.prototype.hasOwnProperty.call(patch, 'description')) {
+    params.push(patch.description === null ? null : String(patch.description));
+    sets.push(`description = $${params.length}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(patch, 'environments')) {
+    params.push(normalizeEnvironments(patch.environments));
+    sets.push(`environments = $${params.length}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(patch, 'required')) {
+    params.push(patch.required !== false);
+    sets.push(`required = $${params.length}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(patch, 'name')) {
+    params.push(String(patch.name).trim());
+    sets.push(`name = $${params.length}`);
+  }
+  const { rows } = await db.query(
+    `UPDATE provisioning_env_vars SET ${sets.join(', ')}
+      WHERE instance_id = $1 AND id = $2 RETURNING *`,
+    params
+  );
+  return rows[0] ? envVarRow(rows[0]) : null;
+}
+
+// Remove one declaration, scoped to its project for the same reason. Returns true when a
+// row went, false when the id was not that project's — the route turns both into the
+// same 404, so a guessed id never confirms another project's contents.
+async function removeEnvVar(db, instanceId, id) {
+  const { rowCount } = await db.query(
+    `DELETE FROM provisioning_env_vars WHERE instance_id = $1 AND id = $2`,
+    [instanceId, id]
+  );
+  return rowCount > 0;
+}
+
+module.exports = {
+  ENVIRONMENTS, ENV_NAME_MAX, VALUE_FIELDS,
+  isValidEnvName, envNameRefusal, normalizeEnvironments, unknownEnvironments,
+  rejectsValueField, envVarRow,
+  listEnvVars, declareEnvVar, updateEnvVar, removeEnvVar,
+};

package/modules/provisioning/migrations/provisioning_023_env_manifest.sql

@@ -0,0 +1,67 @@
+-- provisioning_023 — the project ENV VAR MANIFEST (task 1004062, ADR 0323 decision 6).
+--
+-- **THERE IS NO VALUE COLUMN, AND ADDING ONE IS THE THING THIS TABLE EXISTS TO PREVENT.**
+--
+-- A project's environment variables have two halves. The VALUES live on the deployment
+-- platform the running application reads them from — Vercel, Netlify, Render or the
+-- owner's own machine — which already encrypts, audits and rotates them. Bongos storing
+-- them too would make this platform the custodian of other companies' credentials for no
+-- gain, which is the responsibility ADR 0323 spends its entire budget avoiding.
+--
+-- The half Bongos genuinely needs is the SURFACE: which variables exist and what each one
+-- is for, so a builder — human or agent — writing code references the right names and a
+-- setup document is complete. That is a manifest, not a vault, and a manifest is exactly
+-- this: a name, a sentence, where it applies, and whether it is required.
+--
+-- Not encrypted-at-rest either, because there is nothing here to encrypt. A variable NAME
+-- is not a secret: it appears in the source that reads it. Anyone who can read this table
+-- can already read the repository.
+--
+-- For a `byo-host` project there is no platform to ask, so the manifest is simply
+-- unverifiable — which keeps "Bongos holds no values" true everywhere, with no exception
+-- to reason about later (ADR 0323 decision 6's own wording).
+--
+-- Additive + `provisioning_`-namespaced per ADR 0083 §5: CREATE TABLE IF NOT EXISTS only,
+-- no core table touched, so an instance with this module disabled is unaffected.
+
+CREATE TABLE IF NOT EXISTS provisioning_env_vars (
+  id           bigserial PRIMARY KEY,
+
+  -- The project this declaration belongs to. CASCADE because a manifest is meaningless
+  -- without its project, and ADR 0290's disconnect already relies on the row going with
+  -- it (provisioning_instances cascades its intents, events and manifests the same way).
+  instance_id  bigint NOT NULL REFERENCES provisioning_instances(id) ON DELETE CASCADE,
+
+  -- The variable's NAME, as the application reads it (e.g. 'DATABASE_URL'). Shape is
+  -- enforced in code (env-manifest.js's isValidEnvName) so the refusal can name the rule;
+  -- the length cap here is the backstop a bypassed caller still meets.
+  name         text NOT NULL CHECK (length(name) BETWEEN 1 AND 128),
+
+  -- What the variable is FOR, in a sentence. The whole point of the manifest: a name with
+  -- no purpose tells a builder the surface exists but not what to put behind it.
+  description  text,
+
+  -- Where it applies. An array because one variable is usually read in several
+  -- environments, and a row per environment would make "rename this variable" a
+  -- multi-row edit. The CHECK is a containment test (<@), so it admits any subset —
+  -- including the empty array, which env-manifest.js reads as "everywhere" and never
+  -- writes.
+  environments text[] NOT NULL DEFAULT ARRAY['production','preview','development']::text[]
+    CHECK (environments <@ ARRAY['production','preview','development']::text[]),
+
+  -- Required vs optional. Defaults to required: a variable somebody bothered to declare
+  -- is more often one the application cannot start without, and the safe default for a
+  -- setup checklist is the one that makes an omission visible.
+  required     boolean NOT NULL DEFAULT true,
+
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  updated_at   timestamptz NOT NULL DEFAULT now()
+);
+
+-- One declaration per name per project. A second POST for the same name is an EDIT of
+-- the same declaration, not a duplicate row: two rows saying different things about
+-- DATABASE_URL is a manifest that cannot be read, and the reader would have no rule for
+-- picking. Case-sensitive on purpose — environment variables are, and folding the case
+-- here would silently merge `Path` and `PATH`.
+CREATE UNIQUE INDEX IF NOT EXISTS ux_provisioning_env_vars_instance_name
+  ON provisioning_env_vars (instance_id, name);

package/modules/provisioning/module.json

@@ -1,19 +1,34 @@
 {
   "key": "provisioning",
   "title": "Instance provisioning",
-  "description": "Stand up + operate a Cloud Bongos instance's own infrastructure (server, database, domain, DNS, TLS) via the API, so an owner does not manage infra by hand (ADR 0111). Owns the web-tier REQUEST + STATE surface only: it enqueues provisioning intents + reads instance state — it holds NO cloud-provider tokens and calls NO cloud API. A separate control-plane runner (scripts/gds/provision.js, task P3) is the sole token-holder that drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute WORKLOADS.",
+  "description": "Stand up + operate a Cloud Bongos instance's own infrastructure (server, database, domain, DNS, TLS) via the API, so an owner does not manage infra by hand (ADR 0111). Owns the web-tier REQUEST + STATE surface only: it enqueues provisioning intents + reads instance state \u2014 it holds NO cloud-provider tokens and calls NO cloud API. A separate control-plane runner (scripts/gds/provision.js, task P3) is the sole token-holder that drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute WORKLOADS.",
   "coreVersion": "^1.14.0",
   "default": false,
   "author": "Cloud Bongos",
   "origin": "Cloud Bongos core",
   "license": "AGPL-3.0",
   "maintainer": "Cloud Bongos maintainers",
-  "maintenance": { "status": "core-maintained" },
+  "maintenance": {
+    "status": "core-maintained"
+  },
   "contributes": {
-    "routes": ["provisioning", "disconnect", "core-upgrade"],
+    "routes": [
+      "provisioning",
+      "disconnect",
+      "core-upgrade",
+      "env-manifest"
+    ],
     "migrations": true,
-    "pollers": ["liveness-sweep", "catalog-backfill"]
+    "pollers": [
+      "liveness-sweep",
+      "catalog-backfill"
+    ]
   },
-  "provides": ["provisioning.instanceState", "provisioning.projectPlanets", "provisioning.projectOwnedBy", "provisioning.projectPublishIdentity"],
+  "provides": [
+    "provisioning.instanceState",
+    "provisioning.projectPlanets",
+    "provisioning.projectOwnedBy",
+    "provisioning.projectPublishIdentity"
+  ],
   "consumes": []
 }

package/modules/provisioning/routes/env-manifest.js

@@ -0,0 +1,201 @@
+// modules/provisioning/routes/env-manifest.js — the project ENV VAR MANIFEST's HTTP
+// surface (task 1004062, ADR 0323 decision 6).
+//
+//   own-scoped (requireBuilder — the caller's OWN project; archon may read/edit any):
+//     GET    /provisioning/instances/:id/env-manifest          — the declared surface
+//     POST   /provisioning/instances/:id/env-manifest          — declare (or re-declare) one
+//     PATCH  /provisioning/instances/:id/env-manifest/:varId   — edit one
+//     DELETE /provisioning/instances/:id/env-manifest/:varId   — remove one
+//
+// **NO ROUTE HERE ACCEPTS, STORES, LOGS OR RETURNS A VALUE**, and the write routes REFUSE
+// a body that carries one rather than dropping it (../env-manifest.js's
+// `rejectsValueField`, and see that file's header for why loud beats silent). The values
+// live on the deployment platform the running application reads them from.
+//
+// Its own routes file, declared in module.json, because routes/provisioning.js sits at
+// the 1500-line fitness ratchet — the ./disconnect.js and ./core-upgrade.js precedent.
+//
+// A missing or foreign project is 404 for everyone but an archon, the same shape every
+// own-scoped route in this module uses, so another owner's project id is never confirmed.
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { pool, validateOrRespond, parseId } = api;
+const provisioning = require('../provisioning');
+const envManifest = require('../env-manifest');
+
+const log = api.logger('provisioning');
+
+// Resolve the project and decide whether this caller may see it. Returns the instance, or
+// null having already sent the 404 — the same own-or-archon rule as ./disconnect.js.
+async function resolveOwnInstance(req, res) {
+  const id = parseId(req, res); // sends 400 bad_id + returns null on failure
+  if (!id) return null;
+  const inst = await provisioning.getInstanceById(pool, id);
+  const isOwner = !!inst && String(inst.owner_builder_id) === String(req.builder.id);
+  if (!inst || (!isOwner && req.builder.rank !== 'archon')) {
+    res.fail('instance_not_found', 404);
+    return null;
+  }
+  return inst;
+}
+
+// The `:varId` path segment. parseId reads `:id`, which is the PROJECT here, so the
+// declaration's id is parsed separately. A non-numeric id is a 400 naming the field
+// rather than a 404, because it is a malformed request and not a missing row.
+function parseVarId(req, res) {
+  const raw = String(req.params.varId || '');
+  if (!/^[0-9]+$/.test(raw)) {
+    res.fail('bad_id', { status: 400, message: 'varId must be a numeric declaration id.' });
+    return null;
+  }
+  return raw;
+}
+
+// The VALUE refusal, and it runs BEFORE the kernel's strict body validator on purpose.
+//
+// `value` is not in either write route's field list, so `validateOrRespond` already
+// refuses it — correctly, and nothing is stored either way. But it refuses it as a
+// generic `validation_failed` naming an unknown field, and that is the wrong sentence for
+// this particular mistake: a caller who has just sent this platform a credential needs to
+// be told that it stores names and never values, and where the value should live instead.
+// A caller who reads "unknown field: value" is as likely to conclude the field is spelled
+// differently and try again.
+//
+// So this speaks first and the strict validator stays as the backstop behind it. Returns
+// true when it has already failed the response.
+function refusesValue(req, res) {
+  const valueSent = envManifest.rejectsValueField(req.body);
+  if (!valueSent) return false;
+  res.fail(valueSent.code, { status: 400, message: valueSent.message });
+  return true;
+}
+
+// The shared body checks for POST and PATCH, so the two can never disagree about what a
+// valid declaration is. Runs AFTER validateOrRespond (types and lengths are its job) and
+// answers the questions it cannot: is this a legal variable name, and is that a real
+// environment. Returns true when it has already failed the response.
+function badDeclaration(req, res, { nameRequired }) {
+  const hasName = req.body && Object.prototype.hasOwnProperty.call(req.body, 'name');
+  if (nameRequired || hasName) {
+    const refusal = envManifest.envNameRefusal(req.body && req.body.name);
+    if (refusal) {
+      res.fail('bad_env_name', { status: 400, message: refusal });
+      return true;
+    }
+  }
+  const unknown = envManifest.unknownEnvironments(req.body && req.body.environments);
+  if (unknown.length) {
+    // Refused, not quietly filtered: keeping the remainder would tell the owner their
+    // variable applies somewhere it does not.
+    res.fail('bad_environment', { status: 400,
+      message: `Unknown environment ${unknown.map((e) => `"${e}"`).join(', ')} — this platform knows ${envManifest.ENVIRONMENTS.join(', ')}.`,
+      details: { unknown, known: envManifest.ENVIRONMENTS } });
+    return true;
+  }
+  return false;
+}
+
+module.exports = function buildEnvManifestRouter() {
+  const router = express.Router();
+
+  // GET — the declared surface. This is the route a BUILDER SESSION reads to learn which
+  // variables a project has, which is the whole reason the manifest exists.
+  router.get('/provisioning/instances/:id/env-manifest', api.requireBuilder, async (req, res) => {
+    try {
+      const inst = await resolveOwnInstance(req, res);
+      if (!inst) return;
+      const vars = await envManifest.listEnvVars(pool, inst.id);
+      res.json({
+        instance: { id: String(inst.id), slug: inst.slug, hosting_shape: inst.hosting_shape },
+        env_vars: vars,
+        environments: envManifest.ENVIRONMENTS,
+        // Said in the payload, not only in a doc: a reader of this list must not go
+        // looking for a value field and conclude the API is broken when there is none.
+        // For byo-host there is no platform to ask at all (ADR 0323 decision 6).
+        values_held: false,
+        note: 'Names and purposes only — this platform never holds a variable\'s value. Set values where the running application reads them.',
+      });
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/instances/:id/env-manifest', err);
+      res.fail('env_manifest_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST — declare a variable, or re-declare one that exists (an edit, not a duplicate:
+  // see ../env-manifest.js's declareEnvVar).
+  router.post('/provisioning/instances/:id/env-manifest', api.requireBuilder, async (req, res) => {
+    if (refusesValue(req, res)) return;   // before the strict validator — see refusesValue
+    if (validateOrRespond(req, res, {
+      name: { required: true, type: 'string', maxLength: envManifest.ENV_NAME_MAX },
+      description: { type: 'string', maxLength: 2000 },
+      environments: { type: 'array' },
+      required: { type: 'boolean' },
+    })) return;
+    try {
+      const inst = await resolveOwnInstance(req, res);
+      if (!inst) return;
+      if (badDeclaration(req, res, { nameRequired: true })) return;
+      const { row, created } = await envManifest.declareEnvVar(pool, {
+        instanceId: inst.id,
+        name: req.body.name,
+        description: req.body.description ?? null,
+        environments: req.body.environments,
+        required: req.body.required,
+      });
+      res.status(created ? 201 : 200).json({ ok: true, created, env_var: row, values_held: false });
+    } catch (err) {
+      log.error('[provisioning] POST /provisioning/instances/:id/env-manifest', err);
+      res.fail('env_manifest_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH — edit one declaration. Merge-patch: an omitted field is left alone, so the
+  // hall can fix a description without restating the environments.
+  router.patch('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, async (req, res) => {
+    if (refusesValue(req, res)) return;   // before the strict validator — see refusesValue
+    if (validateOrRespond(req, res, {
+      name: { type: 'string', maxLength: envManifest.ENV_NAME_MAX },
+      description: { type: 'string', nullable: true, maxLength: 2000 },
+      environments: { type: 'array' },
+      required: { type: 'boolean' },
+    })) return;
+    try {
+      const inst = await resolveOwnInstance(req, res);
+      if (!inst) return;
+      const varId = parseVarId(req, res);
+      if (!varId) return;
+      if (badDeclaration(req, res, { nameRequired: false })) return;
+      const row = await envManifest.updateEnvVar(pool, inst.id, varId, req.body || {});
+      // Not that project's declaration → the same 404 a missing one gets, so a guessed id
+      // never confirms what another project declares.
+      if (!row) return res.fail('env_var_not_found', 404);
+      res.json({ ok: true, env_var: row, values_held: false });
+    } catch (err) {
+      log.error('[provisioning] PATCH /provisioning/instances/:id/env-manifest/:varId', err);
+      res.fail('env_manifest_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // DELETE — remove one declaration. Nothing outside this table is affected: the value,
+  // wherever it lives, is untouched, and the response says so rather than letting an
+  // owner believe removing the name removed the secret.
+  router.delete('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, async (req, res) => {
+    try {
+      const inst = await resolveOwnInstance(req, res);
+      if (!inst) return;
+      const varId = parseVarId(req, res);
+      if (!varId) return;
+      const removed = await envManifest.removeEnvVar(pool, inst.id, varId);
+      if (!removed) return res.fail('env_var_not_found', 404);
+      res.json({ ok: true, removed: true,
+        message: 'Declaration removed. The variable\'s value, wherever you keep it, is untouched — this platform never had it.' });
+    } catch (err) {
+      log.error('[provisioning] DELETE /provisioning/instances/:id/env-manifest/:varId', err);
+      res.fail('env_manifest_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};