workspaces 0.1.17 → 0.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f662b3baa05bd9cd6a684906e2bf2d75d663dfa493fd684ef1090adb0095276
-  data.tar.gz: 2265a4ddeeae587c04b2eae5e8ed0e8a7f5f64988bb9c22c0f1f4c9202c30b9f
+  metadata.gz: 8a0a1c93490624ea0d8bb2fe77ddb8e7d1ad9bf53fe7700b6eec7245cc2e031a
+  data.tar.gz: 561ec874bbbe8d1c537066b612065c23db82caea34ca8d19cc894b66245be24d
 SHA512:
-  metadata.gz: 3cea009527f192e61a8c14a2f9642e7f67d0d58118e2f13884a28c68d5b10c17ca12c98dfba24af32618ebae87e4f3f34645a10048ce110ec395424be1dda5c0
-  data.tar.gz: 496afa3b947a7c21a58f9e66f9f542b3146ce327fabad2b5633bd58f63d089a3e8ad965420e251e0589213acffc1219845625c9ba8377d42d6b59e9a5c608d8e
+  metadata.gz: 7c9e26c91a93c37d8ea2391a0dd1c6ed3a163ba64c37deb2d73cae6d4688c33a7d5f9573ff98a8510789820d06e3f9af36dd78e86ba66b80a13435b11526ffd4
+  data.tar.gz: d0deac511f060614b66a41e793af6a4e3c7eb64e2150681dccd65c4910f0fffb5b74d213db865f38a3cb748adfc712bcfdf0a268328d4d9aea4d3375e23f2070

data/DESIGN.md

@@ -62,6 +62,7 @@ Restrained tooling UI: dark elevated panels, compact spacing rhythm, clear statu
 - **Disclosure behavior**: the server renders the initial open state and the polling script re-applies it from `presentation.open`, but only when the state changes. A section the user opened or closed is left alone on later polls. Sections that are not meaningful in a state are hidden, never shown disabled.
 - **Per-step re-run controls**: inside each step's accordion, small subtle **Re-run this step** and **Re-run from here** forms aimed at `/workspaces/ID/resume?only=KEY` and `?from=KEY`. The server decides which appear (`presentation.resume.step_modes`), so the page never offers something that would be refused; they are hidden while a run is in progress and are disabled with the other controls while busy.
 - **Sleeping**: a workspace asleep is its own state (`sleeping`), distinct from stopped and failed. The lead reads "Your workspace is asleep", says files and data are kept and that opening the preview wakes it, and offers one **Wake workspace** button. A ready workspace shows one muted line, "Sleeps after N min without preview traffic", or "Kept awake" when exempt. **Keep awake** / **Allow sleep** are subtle workspace controls. A waking workspace is simply busy.
+- **Environment rows**: the settings form is a list of rows, each a name input, a value input and a **Secret** checkbox, with **Add variable** and a per-row **Remove** (both revealed by script; without it the server-rendered rows still save). Rows post as `env[N][name|value|secret]`. A secret row's value is a password field that is never pre-filled; a stored secret shows its name, the placeholder "Stored. Enter a new value to replace it", and a locked checked checkbox (a hidden field carries it), so it can only be replaced or removed, not exposed. Ticking Secret on a new row switches its value to a password field. Presets replace only the visible rows and are matched against visible rows alone. A note under the rows shows why secrets are unavailable when the vault is not usable, and a line explains that secrets are write-only.
 - **Action buttons**: start, prepare/rebuild, restart server, stop server, retry failed step, and refresh
 - **Open workspace**: success-styled link available when the server is ready
 - **Lifecycle controls**: hidden while busy (see state machine); helper text distinguishes rebuilding from server-only restart

data/README.md

@@ -242,6 +242,61 @@ temporarily stashed and restored (including staged state). On a restore conflict
 the stash is retained for manual recovery. Updating the checkout does not run
 setup or restart the already-running backend; use Rebuild & restart afterward.
 
+### Environment variables and secrets
+
+A workspace's settings are rows of **name** and **value**, with a **Secret**
+checkbox on each. Add and remove rows as needed; **Save & restart** applies them.
+
+A *secret* is an environment variable that is write-only. Its value goes to a
+vault, is handed to the workspace's setup steps and server as an ordinary
+environment variable, and is never shown again: not in the dashboard, the status
+API, the logs (any output that contains it is filtered) or error messages. A saved
+secret appears as its name with an empty, password-style field that says a value is
+stored. Leave that field blank to keep the stored value, type a new one to replace
+it, or remove the row to delete the secret. A stored secret cannot be turned back
+into a visible variable. Names that look like secrets (`*_TOKEN`, `*_SECRET`,
+`*_PASSWORD`, `*_API_KEY`, ...) cannot be saved as visible variables; tick **Secret**.
+Presets only ever change visible variables.
+
+Which vault is used is set where `serve` runs, with `WORKSPACES_VAULT` (default
+`file`). The built-in `file` vault keeps one AES-256-GCM encrypted file per workspace
+in `$WORKSPACES_HOME/vault/`, with a key derived per workspace from a master key you
+provide:
+
+```sh
+export WORKSPACES_MASTER_KEY="$(openssl rand -base64 32)"   # keep this; it cannot be recovered
+bin/workspaces serve --secure
+```
+
+Without `WORKSPACES_MASTER_KEY` the settings page says secrets are turned off, and
+everything else works as before. With the wrong key a run fails with a plain reason
+rather than starting without its secrets, and saving is refused so stored secrets are
+never overwritten. The master key is read only by the front door: it is removed from
+the environment of every step, server and `exec` command.
+
+Removing a workspace (`remove`, or the dashboard's Remove button) deletes its secrets
+too. The file vault is always asked to delete its own files, even if `WORKSPACES_VAULT`
+has since been changed. A secret that cannot be deleted is reported rather than hidden:
+`remove` exits non-zero and lists it under `secrets_left`, and the dashboard says the
+workspace was removed but its secrets were not. Secrets live outside the workspace's
+checkout, in `$WORKSPACES_HOME/vault/<workspace-id>.enc`, with no other record of the
+link, so a workspace deleted some other way (by hand, or `git worktree remove`) leaves
+its file behind. Clean those up with:
+
+```sh
+bin/workspaces purge-secrets --dry-run   # list secrets whose workspace no longer exists
+bin/workspaces purge-secrets             # delete them
+```
+
+It refuses to run if the workspaces directory cannot be read, so an unmounted volume is
+never mistaken for "every workspace is gone".
+
+Another store can be added behind the same small interface (`available?`/`problem`,
+`read(scope)`, `write(scope, entries)`, `purge(scope)`, and optionally `scopes` to
+list what it holds so `purge-secrets` can find orphans): subclass
+`Workspaces::Vault::Provider` and call `Workspaces::Vault.register('name', YourClass)`
+from a file loaded with `serve --require`, then set `WORKSPACES_VAULT=name`.
+
 ### Editable environment presets
 
 Recipes can define editable environment defaults and named presets in
@@ -258,20 +313,20 @@ environment_presets:
     DEMO_MODE: "false"
 ```
 
-Each preset maps editable variable names to values. In the workspace editor,
-choosing a preset fills the draft and replaces its custom editor lines rather
-than merging with them. Selection does not save or restart the workspace; choose
-**Save & restart** to apply the draft. Presets are not applied automatically,
+Each preset maps editable variable names to values. In the workspace settings,
+choosing a preset replaces the visible variable rows rather than merging with
+them (secret rows are left alone). Selection does not save or restart the
+workspace; choose **Save & restart** to apply the draft. Presets are not applied automatically,
 and defining them requires no JavaScript edits. Preset keys must be declared in
 `default_editable_env`; recipes reject undeclared keys and secret-like values.
-Hidden environment values are never exposed in the editor or preset choices.
+Hidden environment values are never exposed in the settings or preset choices.
 
 Use `create --branch main --preset Demo` to save a preset for a new, still-idle
 workspace. `start ID --preset Demo` applies it before preparing a stopped
 workspace; `restart ID --preset 'Demo off'` switches a running workspace and
 restarts its server. `prepare ID --preset Demo` switches and rebuilds. An
 unknown name is rejected without changing saved settings. Selecting a preset
-replaces the editable settings (including custom editor lines) but preserves
+replaces the editable settings (including custom rows) but preserves
 hidden legacy overrides. A running workspace requires `restart --preset` or
 `prepare --preset`, not `start --preset`.
 

data/lib/workspaces/child_env.rb

@@ -2,6 +2,10 @@ module Workspaces
   module ChildEnv
     module_function
 
+    # Held by the front door alone. Anything a step, the server or `exec` starts must never see the
+    # key that opens the secret vault, however it was set.
+    WITHHELD = %w(WORKSPACES_MASTER_KEY).freeze
+
     def for_workspace(workspace_path:, extra_env: {}, parent_env: ENV.to_h)
       env = parent_env.to_h.transform_keys(&:to_s).dup
       if defined?(::Bundler)
@@ -10,7 +14,7 @@ module Workspaces
           clean.key?(name) ? env[name] = clean[name] : env.delete(name)
         end
       end
-      env.delete_if { |key, _| bundler_key?(key) }
+      env.delete_if { |key, _| bundler_key?(key) || WITHHELD.include?(key) }
 
       gemfile = File.join(workspace_path.to_s, 'Gemfile')
       env['BUNDLE_GEMFILE'] = gemfile
@@ -18,7 +22,7 @@ module Workspaces
 
       extra_env.to_h.each do |name, value|
         key = name.to_s
-        next if bundler_key?(key)
+        next if bundler_key?(key) || WITHHELD.include?(key)
 
         if value.nil?
           env.delete(key)

data/lib/workspaces/cli.rb

@@ -17,7 +17,7 @@ module Workspaces
     COMMANDS = {
       'serve' => :serve, 'create' => :create, 'list' => :list, 'show' => :show,
       'start' => :lifecycle, 'prepare' => :lifecycle, 'restart' => :lifecycle,
-      'stop' => :stop, 'remove' => :remove, 'resume' => :resume, 'keep-awake' => :keep_awake, 'help' => :help
+      'stop' => :stop, 'remove' => :remove, 'purge-secrets' => :purge_secrets, 'resume' => :resume, 'keep-awake' => :keep_awake, 'help' => :help
     }.freeze
     def self.run(argv)
       new.run(argv.dup)
@@ -88,6 +88,7 @@ module Workspaces
       parser.on('--from REF') { |value| options[:from] = value }
       parser.on('--json') { options[:json] = true }
       parser.on('--force') { options[:force] = true }
+      parser.on('--dry-run') { options[:dry_run] = true }
       parser.on('--off') { options[:off] = true }
     end
 
@@ -207,8 +208,21 @@ module Workspaces
     end
 
     def remove(id, options)
-      registry.remove(id, force: options[:force])
-      emit({ 'id' => id, 'removed' => true, 'branch_preserved' => true }, options)
+      leftover = registry.remove(id, force: options[:force])
+      leftover = [] unless leftover.is_a?(Array)
+      emit({ 'id' => id, 'removed' => true, 'branch_preserved' => true, 'secrets_left' => leftover }, options)
+      return if leftover.empty?
+
+      warn "The workspace was removed, but its secrets could not be: #{leftover.join('; ')}. " \
+           'Fix that, then run `workspaces purge-secrets`.'
+      raise ArgumentError, 'Secrets were left behind'
+    end
+
+    # Deletes stored secrets whose workspace no longer exists. `--dry-run` lists them without deleting.
+    def purge_secrets(_id, options)
+      result = registry.sweep_orphaned_secrets(dry_run: options[:dry_run])
+      emit(result.merge('dry_run' => !!options[:dry_run]), options)
+      raise ArgumentError, "Could not remove: #{result['problems'].join('; ')}" unless result['problems'].empty?
     end
 
     def execute(argv)
@@ -243,7 +257,7 @@ module Workspaces
       'Usage: bin/workspaces serve [--require FILE] | create (--branch REF | --pr NUMBER | --new-branch NAME [--from REF]) [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
         'list [--pr NUMBER] [--json] | show/start/prepare/restart ID [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
         'resume ID [--from STEP | --only STEP] [--json] | stop ID | keep-awake ID [--off] | ' \
-        'exec ID -- COMMAND... | remove ID [--force]'
+        'exec ID -- COMMAND... | remove ID [--force] | purge-secrets [--dry-run]'
     end
 
     def help(*)

data/lib/workspaces/coordinator.rb

@@ -63,6 +63,17 @@ module Workspaces
                  })
     end
 
+    # Saves the settings form (rows of name / value / secret) and starts the workspace, restarting it
+    # if it is already up. See EnvironmentOverrides#replace_rows.
+    def replace_environment_rows(id, rows:)
+      restart = Backend.new(id).running? || sleeping?(id)
+      launch(id, restart: restart, force: true,
+                 prelaunch: lambda { |_workspace|
+                   defaults = Recipe.new.default_editable_env
+                   EnvironmentOverrides.new(id).replace_rows(rows, defaults: defaults)
+                 })
+    end
+
     def replace_editable_environment(id, text:)
       restart = Backend.new(id).running? || sleeping?(id)
       launch(id, restart: restart, force: true,
@@ -259,6 +270,8 @@ module Workspaces
         'log_tail' => include_log ? log_tail(id, log) : '', 'log_source' => log, 'port' => entry['port'],
         'environment_keys' => environment_keys(id),
         'editable_environment' => editable_environment(id),
+        'secret_names' => secret_names(id),
+        'vault' => Vault.status,
         'environment_presets' => environment_presets
       }
     end
@@ -475,6 +488,13 @@ module Workspaces
       []
     end
 
+    # Names only. A secret's value is never part of a snapshot, a status response or a page.
+    def secret_names(id)
+      EnvironmentOverrides.new(id).secret_names
+    rescue EnvironmentOverrides::Invalid
+      []
+    end
+
     def editable_environment(id)
       EnvironmentOverrides.new(id).editable_values(Recipe.new.default_editable_env)
     rescue Recipe::Invalid, EnvironmentOverrides::Invalid

data/lib/workspaces/dashboard/environment.js

@@ -5,14 +5,17 @@
   const status = document.getElementById('environment-status');
   const fieldset = form.querySelector('[data-environment-fieldset]');
   const submit = form.querySelector('[data-env-submit]');
-  const editor = document.getElementById('editable-env');
+  const rowsContainer = document.getElementById('env-rows');
+  const rowTemplate = document.getElementById('env-row-template');
+  const addButton = form.querySelector('[data-env-add-row]');
   const presetButtons = Array.from(form.querySelectorAll('[data-environment-preset]'));
   const presetGroup = form.querySelector('[data-preset-controls]');
-  const initialDraft = editor ? editor.value : '';
   let lastAnnounced = '';
   let activeBusy = document.getElementById('workspace').dataset.busy === 'true';
   let presets = {};
   let selectedPreset = null;
+  let nextIndex = 0;
+  let initialSignature = '';
 
   try {
     presets = JSON.parse(form.dataset.environmentPresets || '{}');
@@ -22,17 +25,60 @@
   const hasPresets = Object.keys(presets).length > 0;
   if (presetGroup && hasPresets) presetGroup.hidden = false;
 
-  function normalize(value) {
-    return (value || '')
-      .replace(/\r\n?/g, '\n')
-      .trimEnd();
+  // A preset is a list of { name, value }. A row's state is what the person typed. Secret rows are
+  // never part of any comparison, so a preset can match while secrets are present.
+  function rowElements() {
+    return rowsContainer ? Array.from(rowsContainer.querySelectorAll('[data-env-row]')) : [];
   }
 
-  function matchingPresetNameForDraft(value) {
-    const normalizedValue = normalize(value);
-    return Object.keys(presets).find(
-      (name) => normalize(presets[name]) === normalizedValue
-    ) || null;
+  // The value input is missing on a stored secret until Replace is clicked, so it can be null.
+  function fieldsOf(row) {
+    return {
+      name: row.querySelector('.env-row__name'),
+      value: row.querySelector('[data-env-value]'),
+      secret: row.querySelector('[data-env-secret]'),
+      remove: row.querySelector('[data-env-remove-row]'),
+      stored: row.querySelector('[data-env-stored]'),
+      replace: row.querySelector('[data-env-replace]')
+    };
+  }
+
+  const valueOf = (fields) => (fields.value ? fields.value.value || '' : '');
+
+  // Keeps password managers out of every input this script creates: autocomplete is ignored on
+  // password fields, so each manager's own opt-out goes with it.
+  function noAutofill(input) {
+    input.autocomplete = 'off';
+    input.setAttribute('autocomplete', 'off');
+    input.setAttribute('data-1p-ignore', '');
+    input.setAttribute('data-lpignore', 'true');
+    input.setAttribute('data-bwignore', '');
+  }
+
+  function visibleEntries() {
+    return rowElements()
+      .map((row) => {
+        const fields = fieldsOf(row);
+        return {
+          name: (fields.name.value || '').trim(),
+          value: valueOf(fields),
+          secret: !!(fields.secret && fields.secret.checked)
+        };
+      })
+      .filter((entry) => !entry.secret && (entry.name || entry.value));
+  }
+
+  function signatureOf(entries) {
+    return JSON.stringify(
+      entries
+        .map((entry) => [entry.name, entry.value])
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    );
+  }
+
+  function matchingPresetName() {
+    const current = signatureOf(visibleEntries());
+    return Object.keys(presets).find((name) => signatureOf(presets[name]) === current) || null;
   }
 
   function updatePresetButtons(nextSelected) {
@@ -69,15 +115,13 @@
     if (fieldset) fieldset.disabled = activeBusy;
     if (submit) submit.disabled = activeBusy;
     presetButtons.forEach((button) => {
-      button.disabled = activeBusy;
+      button.disabled = activeBusy || !hasPresets;
     });
   }
 
   function updateStatus(busy) {
     if (busy)
-      setStatus(
-        'Workspace is busy. Environment updates are temporarily disabled.'
-      );
+      setStatus('Workspace is busy. Environment updates are temporarily disabled.');
     else if (status.textContent === 'Workspace is busy. Environment updates are temporarily disabled.') {
       status.textContent = '';
       lastAnnounced = '';
@@ -86,75 +130,173 @@
 
   function announceUnsaved(message) {
     if (activeBusy) return;
-    const nextMessage = message || 'Draft updated locally and not saved yet. Use ' + submitLabel() + ' to apply changes.';
+    const nextMessage =
+      message || 'Draft updated locally and not saved yet. Use ' + submitLabel() + ' to apply changes.';
     status.textContent = nextMessage;
     lastAnnounced = nextMessage;
   }
 
-  function replaceDraft(value, message) {
-    if (!editor) return;
-    editor.value = value || '';
-    updatePresetButtons(matchingPresetNameForDraft(editor.value));
-    announceUnsaved(message);
-  }
-
   function clearStatus() {
     if (activeBusy) return;
     status.textContent = '';
     lastAnnounced = '';
   }
 
+  // The checkbox of a secret that is already stored is disabled (and a hidden field carries it), so a
+  // saved secret cannot be turned back into a visible variable. Ticking Secret on a new row switches
+  // its value to a password field; the value is write-only from then on.
+  function syncRow(row) {
+    const fields = fieldsOf(row);
+    const secret = !!(fields.secret && fields.secret.checked);
+    if (secret) row.setAttribute('data-secret', 'true');
+    else row.removeAttribute('data-secret');
+    if (!fields.value) return;
+    fields.value.type = secret ? 'password' : 'text';
+    noAutofill(fields.value);
+    if (row.hasAttribute('data-stored')) fields.value.placeholder = 'New value (leave blank to keep)';
+    else fields.value.placeholder = secret ? 'Value' : 'value';
+  }
+
+  // Replace adds the value input to a stored secret. Until then the page has no password field for
+  // it at all.
+  function revealReplaceInput(row) {
+    const fields = fieldsOf(row);
+    if (fields.value || !fields.stored) return;
+    const input = document.createElement('input');
+    input.className = 'env-row__value';
+    input.name = (fields.name.name || '').replace(/\[name\]$/, '[value]');
+    input.type = 'password';
+    input.value = '';
+    input.placeholder = 'New value (leave blank to keep)';
+    input.setAttribute('aria-label', 'New value');
+    input.setAttribute('spellcheck', 'false');
+    input.setAttribute('autocapitalize', 'off');
+    input.setAttribute('data-env-value', '');
+    noAutofill(input);
+    fields.stored.parentNode.insertBefore(input, fields.stored);
+    fields.stored.parentNode.removeChild(fields.stored);
+    input.focus();
+  }
+
+  function bindRow(row) {
+    const fields = fieldsOf(row);
+    if (fields.remove) {
+      fields.remove.hidden = false;
+      fields.remove.addEventListener('click', () => {
+        if (activeBusy) return;
+        row.parentNode.removeChild(row);
+        draftChanged();
+      });
+    }
+    if (fields.replace) {
+      fields.replace.hidden = false;
+      fields.replace.addEventListener('click', () => {
+        if (activeBusy) return;
+        revealReplaceInput(row);
+      });
+    }
+    ['input', 'change'].forEach((type) => {
+      row.addEventListener(type, (event) => {
+        if (event && event.target && event.target.matches && event.target.matches('[data-env-secret]'))
+          syncRow(row);
+        draftChanged();
+      });
+    });
+    syncRow(row);
+  }
+
+  function addRow(entry) {
+    if (!rowTemplate || !rowsContainer) return null;
+    const holder = document.createElement('div');
+    holder.innerHTML = rowTemplate.innerHTML.split('__INDEX__').join(String(nextIndex++));
+    const row = holder.querySelector('[data-env-row]');
+    if (!row) return null;
+    rowsContainer.append(row);
+    const fields = fieldsOf(row);
+    if (entry) {
+      fields.name.value = entry.name || '';
+      if (fields.value) fields.value.value = entry.value || '';
+    }
+    bindRow(row);
+    return row;
+  }
+
+  function draftChanged() {
+    updatePresetButtons(matchingPresetName());
+    const unchanged = rowElements().length === 0 ? false : currentSignature() === initialSignature;
+    if (unchanged) clearStatus();
+    else announceUnsaved();
+  }
+
+  function currentSignature() {
+    return JSON.stringify(
+      rowElements().map((row) => {
+        const fields = fieldsOf(row);
+        const secret = !!(fields.secret && fields.secret.checked);
+        // A secret's value is kept out of the signature, but whether one has been typed is not: a
+        // pending replacement is an unsaved change.
+        return [fields.name.value, secret ? '' : valueOf(fields), secret, secret && valueOf(fields) !== ''];
+      })
+    );
+  }
+
+  // Loading a preset replaces the visible variables only. Secrets are never touched by a preset.
+  function loadPreset(name) {
+    const entries = presets[name] || [];
+    rowElements().forEach((row) => {
+      const fields = fieldsOf(row);
+      const isSecret = !!(fields.secret && fields.secret.checked);
+      if (!isSecret) row.parentNode.removeChild(row);
+    });
+    entries.forEach((entry) => addRow(entry));
+    updatePresetButtons(name);
+    announceUnsaved('Preset loaded into draft only. Use ' + submitLabel() + ' to apply changes.');
+  }
+
   form.addEventListener('submit', () => {
     setStatus('Submitting environment settings…');
   });
 
-  if (editor)
-    editor.addEventListener('input', () => {
-      if (editor.value === initialDraft) {
-        updatePresetButtons(matchingPresetNameForDraft(initialDraft));
-        clearStatus();
-        return;
-      }
-      updatePresetButtons(matchingPresetNameForDraft(editor.value));
-      announceUnsaved();
-    });
-
   presetButtons.forEach((button) => {
     button.addEventListener('click', () => {
       if (activeBusy) return;
       const nextValue = button.dataset.environmentPreset;
       if (!nextValue) return;
       if (!Object.prototype.hasOwnProperty.call(presets, nextValue)) return;
-      replaceDraft(
-        presets[nextValue],
-        'Preset loaded into draft only. Use ' + submitLabel() + ' to apply changes.'
-      );
+      loadPreset(nextValue);
+    });
+  });
+
+  if (addButton) {
+    addButton.hidden = false;
+    addButton.addEventListener('click', () => {
+      if (activeBusy) return;
+      const row = addRow(null);
+      if (row) fieldsOf(row).name.focus();
     });
+  }
+
+  // Rows the server rendered already carry numbered names; new rows continue after the highest.
+  rowElements().forEach((row) => {
+    const match = /env\[(\d+)\]/.exec(fieldsOf(row).name.name || '');
+    if (match) nextIndex = Math.max(nextIndex, Number(match[1]) + 1);
+    bindRow(row);
   });
+  initialSignature = currentSignature();
 
   window.WorkspaceEnvironment = {
     toggleBusy,
     updateStatus,
     setStatus,
     setSubmitLabel,
+    // The rows are server-rendered and the person may be editing them, so a poll never rewrites
+    // them; it only keeps the selected preset in step when nothing has been touched.
     syncFromSnapshot(snapshot) {
-      if (!snapshot || presetButtons.length === 0 || !editor) return;
-      const rendered = snapshot.editable_environment;
-      if (!rendered || typeof rendered !== 'object') return;
-      const expected = Object.keys(rendered)
-        .sort()
-        .map((name) => name + '=' + rendered[name])
-        .join('\n');
-      if (editor === document.activeElement) return;
-      if (editor.value !== expected) return;
-      updatePresetButtons(matchingPresetNameForDraft(expected));
+      if (!snapshot || presetButtons.length === 0) return;
+      if (rowsContainer && rowsContainer.contains(document.activeElement)) return;
+      updatePresetButtons(matchingPresetName());
     }
   };
-  updatePresetButtons(matchingPresetNameForDraft(initialDraft));
-  if (!hasPresets) {
-    presetButtons.forEach((button) => {
-      button.disabled = true;
-    });
-  }
+  updatePresetButtons(matchingPresetName());
   toggleBusy(activeBusy);
 })();

data/lib/workspaces/dashboard/styles.css

@@ -386,6 +386,38 @@ h1 {
   overflow: auto;
 }
 
+.env-rows { display: grid; gap: var(--space-2); }
+
+.env-row {
+  display: grid;
+  grid-template-columns: minmax(8rem, 1fr) minmax(8rem, 2fr) auto auto;
+  gap: var(--space-2);
+  align-items: center;
+}
+
+.env-row input[type='text'],
+.env-row input[type='password'],
+.env-row .env-row__name {
+  min-inline-size: 0;
+  padding: var(--space-2) var(--space-3);
+  color: var(--text);
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--space-1);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}
+
+.env-row[data-secret] .env-row__value { border-style: dashed; }
+.env-row__stored { display: inline-flex; align-items: center; gap: var(--space-2); font-size: 13px; }
+.env-row__secret { display: inline-flex; align-items: center; gap: var(--space-1); font-size: 13px; white-space: nowrap; }
+.env-row-actions { display: flex; gap: var(--space-2); }
+.env-vault-note { color: var(--warning); }
+
+@media (max-width: 560px) {
+  .env-row { grid-template-columns: 1fr 1fr; }
+  .env-row .env-row__name, .env-row .env-row__value { grid-column: 1 / -1; }
+}
+
 .env-actions {
   display: flex;
   flex-wrap: wrap;

data/lib/workspaces/dashboard/template.html.erb

@@ -44,9 +44,21 @@
             </div>
           <% end %>
           <div class="stack stack--tight">
-            <label class="env-input-label" for="editable-env">Environment variables</label>
-            <textarea id="editable-env" name="editable_env" rows="8" spellcheck="false" autocomplete="off" autocapitalize="off"><%= escape(editable_environment_text) %></textarea>
+            <p class="env-input-label" id="env-rows-label">Environment variables</p>
+            <div class="env-rows" id="env-rows" role="group" aria-labelledby="env-rows-label" data-env-rows>
+              <% environment_rows.each_with_index do |row, index| %>
+                <%= env_row_html(index, row) %>
+              <% end %>
+            </div>
+            <div class="env-row-actions">
+              <button type="button" class="button button--subtle button--small" data-env-add-row hidden>Add variable</button>
+            </div>
+            <% unless vault_status['available'] %>
+              <p class="muted env-vault-note" id="env-vault-note"><%= escape(vault_status['problem'] || 'Secrets are not available.') %></p>
+            <% end %>
+            <p class="muted env-secret-help">Secrets are write-only: once saved their values are never shown again. Leave a secret's value blank to keep what is stored.</p>
           </div>
+          <template id="env-row-template"><%= env_row_html('__INDEX__', { 'name' => '', 'value' => '', 'secret' => false }) %></template>
         </fieldset>
         <div class="env-actions">
           <button class="button button--primary" data-env-submit <%= 'disabled' if @presentation['busy'] %>><%= escape(@presentation['environment_submit']) %></button>

data/lib/workspaces/dashboard_view.rb

@@ -138,28 +138,86 @@ module Workspaces
       keys.map(&:to_s).sort
     end
 
-    def editable_environment_text
+    # The rows the settings form starts with: visible variables with their values, then secrets by
+    # name only. A secret row never carries a value, so there is nothing to leak into the page.
+    def environment_rows
       values = @snapshot['editable_environment']
-      return '' unless values.is_a?(Hash)
+      plain = values.is_a?(Hash) ? values.sort.map { |name, value| { 'name' => name.to_s, 'value' => value.to_s, 'secret' => false } } : []
+      names = @snapshot['secret_names']
+      secrets = names.is_a?(Array) ? names.map(&:to_s).sort.map { |name| { 'name' => name, 'value' => '', 'secret' => true } } : []
+      plain + secrets
+    end
 
-      values.sort.map { |name, value| "#{name}=#{value}" }.join("\n")
+    # What a preset loads: its rows in the same shape. Secrets are untouched by presets.
+    def environment_preset_rows
+      environment_presets_raw.transform_values do |entries|
+        entries.sort.map { |name, value| { 'name' => name.to_s, 'value' => value.to_s } }
+      end
     end
 
-    def environment_presets
+    # One row of the settings form. Plain rows show their value. Secret rows have a password field,
+    # never pre-filled, with a placeholder saying a value is stored. The secret checkbox is the only
+    # thing that decides which store a row goes to, and it is disabled for a stored secret so a
+    # saved secret cannot be quietly turned into a visible variable.
+    # Keeps password managers from offering to fill, save or generate anything for these inputs. No
+    # single attribute does it: `autocomplete="off"` is ignored on password fields, so each manager's
+    # own opt-out goes alongside it (1Password, LastPass, Bitwarden).
+    NO_AUTOFILL = 'autocomplete="off" data-1p-ignore data-lpignore="true" data-bwignore'
+
+    # One row of the settings form.
+    #
+    # A stored secret has no value input at all: just its name, a note, and a Replace button that
+    # adds the input when it is clicked. So the page holds no password field for a password manager
+    # to find until someone asks to replace one. (Without script, the input sits inside <noscript> so
+    # a secret can still be replaced.) A row posted with no value keeps what is stored.
+    #
+    # The secret checkbox is disabled for a stored secret, with a hidden field carrying it, so a
+    # saved secret cannot be quietly turned into a visible variable.
+    def env_row_html(index, row)
+      secret = row['secret']
+      stored = secret && !row['name'].to_s.empty?
+      <<~HTML.delete("\n")
+        <div class="env-row" data-env-row#{secret ? ' data-secret="true"' : ''}#{stored ? ' data-stored="true"' : ''}>
+        <input class="env-row__name" name="env[#{index}][name]" value="#{escape(row['name'])}" placeholder="NAME" aria-label="Variable name" spellcheck="false" #{NO_AUTOFILL} autocapitalize="off">
+        #{stored ? stored_value_html(index) : value_input_html(index, row)}
+        <label class="env-row__secret"><input type="checkbox" name="env[#{index}][secret]" value="1" data-env-secret#{secret ? ' checked' : ''}#{stored ? ' disabled' : ''}> Secret</label>
+        #{stored ? "<input type=\"hidden\" name=\"env[#{index}][secret]\" value=\"1\">" : ''}
+        <button type="button" class="button button--subtle button--small" data-env-remove-row aria-label="Remove variable" hidden>Remove</button>
+        </div>
+      HTML
+    end
+
+    def value_input_html(index, row, placeholder: nil)
+      secret = row['secret']
+      placeholder ||= secret ? 'Value' : 'value'
+      %(<input class="env-row__value" name="env[#{index}][value]" type="#{secret ? 'password' : 'text'}" value="#{secret ? '' : escape(row['value'])}" placeholder="#{escape(placeholder)}" aria-label="Value" spellcheck="false" #{NO_AUTOFILL} autocapitalize="off" data-env-value>)
+    end
+
+    def stored_value_html(index)
+      '<span class="env-row__stored" data-env-stored><span class="muted">Stored. Write-only.</span> ' \
+        '<button type="button" class="button button--subtle button--small" data-env-replace hidden>Replace</button></span>' \
+        "<noscript>#{value_input_html(index, { 'secret' => true }, placeholder: 'New value (leave blank to keep)')}</noscript>"
+    end
+
+    def environment_presets_raw
       presets = @snapshot['environment_presets']
       return {} unless presets.is_a?(Hash)
 
-      presets.each_with_object({}) do |(name, entries), memo|
-        next unless name.respond_to?(:to_s)
-        next unless entries.is_a?(Hash)
+      presets.select { |name, entries| name.respond_to?(:to_s) && entries.is_a?(Hash) }.transform_keys(&:to_s)
+    end
 
-        lines = entries.sort.map { |entry_name, value| "#{entry_name}=#{value}" }.join("\n")
-        memo[name.to_s] = lines
-      end
+    def vault_status
+      vault = @snapshot['vault']
+      vault.is_a?(Hash) ? vault : { 'available' => false, 'problem' => nil }
+    end
+
+    # The preset names and values the buttons are built from.
+    def environment_presets
+      environment_presets_raw
     end
 
     def environment_presets_json
-      JSON.generate(environment_presets)
+      JSON.generate(environment_preset_rows)
     end
 
     # The lead's primary action. `open` is rendered separately as a link (it needs the

data/lib/workspaces/environment_overrides.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'securerandom'
+require_relative 'vault'
 
 module Workspaces
   class EnvironmentOverrides
@@ -13,6 +14,7 @@ module Workspaces
     MAX_ENTRIES = 100
     MAX_VALUE_BYTES = 8192
     MAX_BODY_BYTES = 128 * 1024
+    MAX_ROWS = 200
 
     def self.validate_entries!(entries)
       raise Invalid, 'Environment overrides must be a mapping' unless entries.is_a?(Hash)
@@ -45,12 +47,26 @@ module Workspaces
       @home = home
     end
 
+    # Everything a step should see: saved variables and secrets. Raises Vault::Error when secrets
+    # exist but cannot be read, so a run fails with a reason instead of starting without them.
     def load
+      load_plain.merge(secret_values)
+    end
+
+    # The variables that are safe to show. No secrets, and no vault access.
+    def load_plain
       load_file(file_path).merge(load_file(editable_file_path))
     end
 
     def keys
-      load.keys.sort
+      (load_plain.keys + secret_names).uniq.sort
+    end
+
+    # Names only, never values. Empty when the vault cannot be opened.
+    def secret_names
+      secret_values.keys.sort
+    rescue Vault::Error
+      []
     end
 
     def editable_values(defaults)
@@ -72,7 +88,28 @@ module Workspaces
         raise Invalid, 'Secret-like environment names cannot be stored in the visible editor'
       end
       persist_editable(entries, updated, defaults)
-      load
+      load_plain
+    end
+
+    # Saves the settings form: a list of rows, each { 'name', 'value', 'secret' }. Plain rows are
+    # stored as editable settings. Secret rows go to the vault and are write-only: a secret row
+    # with no value keeps the value already stored, and a secret that is no longer listed is removed.
+    #
+    # Nothing is changed unless every row is valid and the vault can be used. Messages name
+    # variables, never values.
+    def replace_rows(rows, defaults:)
+      raise Invalid, 'Environment rows must be a list' unless rows.is_a?(Array)
+      raise Invalid, "Environment rows are limited to #{MAX_ROWS}" if rows.length > MAX_ROWS
+
+      self.class.validate_entries!(defaults)
+      plain, secrets = split_rows(rows)
+      self.class.validate_entries!(plain)
+      self.class.validate_entries!(secrets.compact)
+      raise Invalid, 'Environment overrides are limited to 100 entries' if plain.length + secrets.length > MAX_ENTRIES
+
+      write_secrets(secrets)
+      persist_editable(plain, plain.reject { |name, value| defaults[name] == value }, defaults)
+      load_plain
     end
 
     def apply_preset(name, recipe: Recipe.new)
@@ -111,9 +148,12 @@ module Workspaces
       updated
     end
 
+    # Removes saved variables and secrets. Returns the secrets that could not be removed (see
+    # Vault.purge_everywhere), empty when everything went.
     def clear!
       delete_file!
       delete_file!(editable_file_path)
+      Vault.purge_everywhere(workspace_id)
     end
 
     def scrub(value)
@@ -261,10 +301,69 @@ module Workspaces
       raise Invalid, 'Environment storage does not allow symlinks' if path.symlink?
     end
 
+    # Filtering still hides every secret that can be read, even when something else is wrong.
     def scrub_values
-      load.values.reject(&:empty?).uniq.sort_by { |value| -value.bytesize }
-    rescue Invalid
+      values = [safely { load_plain.values }, safely { secret_values.values }].flatten
+      values.reject(&:empty?).uniq.sort_by { |value| -value.bytesize }
+    end
+
+    def safely
+      yield
+    rescue Invalid, Vault::Error
       []
     end
+
+    def secret_values
+      Vault.provider.read(workspace_id)
+    end
+
+    def split_rows(rows)
+      plain = {}
+      secrets = {}
+      rows.each do |row|
+        raise Invalid, 'Each environment row needs a name and a value' unless row.is_a?(Hash)
+
+        name = row['name'].to_s.strip
+        value = row['value'].to_s
+        next if name.empty? && value.empty?
+
+        raise Invalid, 'Every variable needs a name' if name.empty?
+        raise Invalid, "#{name} is listed more than once" if plain.key?(name) || secrets.key?(name)
+
+        if [true, '1', 'true', 'on'].include?(row['secret'])
+          validate_name!(name)
+          secrets[name] = value.empty? ? nil : value
+        else
+          validate_plain_row!(name, value)
+          plain[name] = value
+        end
+      end
+      [plain, secrets]
+    end
+
+    def validate_plain_row!(name, value)
+      validate_name!(name)
+      validate_value!(value)
+      raise Invalid, "#{name} looks like a secret: tick Secret so it is stored write-only" if sensitive_name?(name)
+      raise Invalid, "#{name}: values must be a single line" if value.match?(/[\r\n]/)
+    end
+
+    # `submitted` maps each secret's name to its new value, or nil when the row was left blank. A blank
+    # row keeps the stored value. Existing secrets are never replaced blindly: if the vault cannot be
+    # read (wrong or missing key) an edit is refused rather than overwriting what is stored.
+    def write_secrets(submitted)
+      vault = Vault.provider
+      unless vault.available?
+        raise Vault::Unavailable, vault.problem unless submitted.empty?
+
+        return
+      end
+
+      stored = vault.read(workspace_id)
+      result = submitted.to_h do |name, value|
+        [name, value || stored.fetch(name) { raise Invalid, "#{name} is a new secret and needs a value" }]
+      end
+      vault.write(workspace_id, result) unless result == stored
+    end
   end
 end

data/lib/workspaces/front_door.rb

@@ -148,7 +148,9 @@ module Workspaces
       return response(403, 'Actions require the configured dashboard origin') unless same_origin?(request)
 
       params = environment_params(request)
-      updated = if params.key?('editable_env')
+      updated = if params.key?('env')
+                  @coordinator.replace_environment_rows(id, rows: parse_environment_rows(params))
+                elsif params.key?('editable_env')
                   @coordinator.replace_editable_environment(id, text: parse_editable_environment(params))
                 else
                   @coordinator.update_environment(id, **parse_environment_changes(params))
@@ -158,6 +160,8 @@ module Workspaces
       redirect(Config.dashboard_url(id))
     rescue EnvironmentOverrides::Invalid => e
       response(422, e.message)
+    rescue Vault::Error => e
+      response(422, e.message)
     end
 
     def remove(request, id)
@@ -167,9 +171,13 @@ module Workspaces
       return response(413, 'Deletion confirmation is too large') if request.content_length.to_i > 512
       return response(422, 'Type the exact workspace ID to confirm deletion') unless request.POST['confirm_id'] == id
 
-      @registry.remove(id, force: true)
+      leftover = @registry.remove(id, force: true)
       @tracker.forget(id)
-      redirect("#{Config.public_origin}/workspaces")
+      return redirect("#{Config.public_origin}/workspaces") if !leftover.is_a?(Array) || leftover.empty?
+
+      # The workspace is gone, but its secrets are not, and saying "removed" would be untrue.
+      response(500, "The workspace was removed, but its stored secrets could not be: #{leftover.join('; ')}. " \
+                    'Fix that, then run `workspaces purge-secrets`.')
     rescue ArgumentError, Worktree::CommandFailedError, SystemCallError
       response(409, 'Workspace was not removed. Check the server logs and retry when safe.')
     end
@@ -204,6 +212,24 @@ module Workspaces
       { set: normalize_set(params['set']), remove: normalize_remove(params['remove']) }
     end
 
+    # The form posts env[0][name], env[0][value] and env[0][secret] for each row. Rows are taken in
+    # the order of their numbers; anything that is not a mapping of strings is refused.
+    def parse_environment_rows(params)
+      rows = params['env']
+      raise EnvironmentOverrides::Invalid, 'Environment rows must be a numbered list' unless rows.is_a?(Hash)
+      unless rows.keys.all? { |key| key.to_s.match?(/\A\d{1,4}\z/) }
+        raise EnvironmentOverrides::Invalid, 'Environment rows must be a numbered list'
+      end
+
+      rows.sort_by { |key, _| key.to_i }.map do |_, row|
+        unless row.is_a?(Hash) && row.values.all?(String)
+          raise EnvironmentOverrides::Invalid, 'Each environment row needs a name and a value'
+        end
+
+        row.slice('name', 'value', 'secret')
+      end
+    end
+
     def parse_editable_environment(params)
       unless params['editable_env'].is_a?(String)
         raise EnvironmentOverrides::Invalid, 'Environment editor requires one editable_env field'

data/lib/workspaces/registry.rb

@@ -41,6 +41,8 @@ module Workspaces
       end
     end
 
+    # Removes the workspace and its saved settings and secrets. Returns the secrets that could not be
+    # removed (empty when all went), so callers can say so rather than report a clean removal.
     def remove(id, force: false)
       with_lock(id) do |workspace|
         raise ArgumentError, 'Workspace has uncommitted/untracked work' if !force && workspace.dirty?
@@ -48,9 +50,33 @@ module Workspaces
         Backend.new(id).stop!
         workspace.remove!(force: force)
         StateStore.new(Config.state_file).delete(id)
+        EnvironmentOverrides.new(id).clear!
       end
     end
 
+    # Deletes stored secrets whose workspace no longer exists: removed by hand, with `git worktree
+    # remove`, or by a purge that failed. Returns { 'removed' => [...], 'kept' => [...],
+    # 'problems' => [...] }.
+    #
+    # It decides a workspace is gone only from the managed directory, and refuses to guess when that
+    # directory cannot be read, so a missing or unmounted volume is never mistaken for "everything
+    # was deleted". With dry_run it reports what it would remove and changes nothing.
+    def sweep_orphaned_secrets(dry_run: false)
+      root = Config.worktrees_dir(create: false)
+      unless root.directory? && !root.symlink?
+        raise ArgumentError, 'The workspaces directory cannot be read, so nothing was removed'
+      end
+
+      live = root.children.select { |path| path.directory? && !path.symlink? }.map { |path| path.basename.to_s }
+      orphans = Vault.scopes - live
+      result = { 'removed' => [], 'kept' => live & Vault.scopes, 'problems' => [] }
+      orphans.each do |id|
+        problems = dry_run ? [] : Vault.purge_everywhere(id)
+        problems.empty? ? result['removed'] << id : result['problems'].concat(problems.map { |problem| "#{id}: #{problem}" })
+      end
+      result
+    end
+
     def update_pr(id)
       with_lock(id) do |workspace|
         result = workspace.update_from_pr!

data/lib/workspaces/vault/file_vault.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'json'
+require 'securerandom'
+require_relative '../config'
+
+module Workspaces
+  module Vault
+    # An encrypted file per workspace under $WORKSPACES_HOME/vault, readable only with the master key
+    # in WORKSPACES_MASTER_KEY (32 random bytes, base64 encoded: `openssl rand -base64 32`).
+    #
+    # Each workspace gets its own AES-256-GCM key, derived from the master key with HKDF, and its id is
+    # bound into the ciphertext, so a file copied to another workspace's name does not decrypt. Names
+    # are encrypted along with values. The master key lives only in the environment of the process
+    # that runs `serve`; ChildEnv keeps it out of everything that process starts.
+    class FileVault < Provider
+      KEY_ENV = 'WORKSPACES_MASTER_KEY'
+      FORMAT_VERSION = 1
+      HKDF_SALT = 'workspaces-vault-v1'
+      GENERATE_HINT = 'openssl rand -base64 32'
+
+      def initialize(home: Config.home, env: ENV)
+        super()
+        @home = home
+        @env = env
+      end
+
+      def name
+        'file'
+      end
+
+      def problem
+        text = @env.fetch(KEY_ENV, '').to_s.strip
+        if text.empty?
+          return "Secrets are turned off. Set #{KEY_ENV} where `workspaces serve` runs " \
+                 "(generate one with: #{GENERATE_HINT})."
+        end
+        return nil if master_key
+
+        "#{KEY_ENV} must be 32 random bytes, base64 encoded (generate one with: #{GENERATE_HINT})."
+      end
+
+      def read(scope)
+        path = file_for(scope)
+        return {} unless path.exist?
+
+        require_usable!
+        decrypt(scope, path.binread)
+      end
+
+      def write(scope, entries)
+        path = file_for(scope)
+        return purge(scope) if entries.empty?
+
+        require_usable!
+        ensure_directory!
+        store(path, encrypt(scope, entries))
+      end
+
+      def purge(scope)
+        path = file_for(scope)
+        File.unlink(path) if path.exist? || path.symlink?
+      end
+
+      # The workspace ids that have a file here, found by name alone (no key needed). A symlinked
+      # or missing directory has none that can be trusted, so it lists nothing.
+      def scopes
+        return [] if directory.symlink? || !directory.directory?
+
+        directory.children.filter_map do |path|
+          next unless path.extname == '.enc' && !path.symlink? && path.file?
+
+          id = path.basename('.enc').to_s
+          id if id.match?(/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/) && id.length <= 48
+        end.sort
+      end
+
+      private
+
+      def require_usable!
+        reason = problem
+        raise Unavailable, reason if reason
+      end
+
+      def master_key
+        decoded = decode64(@env.fetch(KEY_ENV, '').to_s.strip)
+        decoded.bytesize == 32 ? decoded : nil
+      rescue ArgumentError
+        nil
+      end
+
+      # Strict base64 without the base64 gem, which is no longer a default gem from Ruby 3.4.
+      def encode64(bytes)
+        [bytes].pack('m0')
+      end
+
+      def decode64(text)
+        text.unpack1('m0')
+      end
+
+      def key_for(scope)
+        OpenSSL::KDF.hkdf(master_key, salt: HKDF_SALT, info: "workspace:#{scope}", length: 32, hash: 'SHA256')
+      end
+
+      def encrypt(scope, entries)
+        cipher = OpenSSL::Cipher.new('aes-256-gcm').encrypt
+        cipher.key = key_for(scope)
+        iv = cipher.random_iv
+        cipher.auth_data = scope
+        ciphertext = cipher.update(JSON.generate(entries)) + cipher.final
+        JSON.generate('v' => FORMAT_VERSION, 'iv' => encode64(iv),
+                      'tag' => encode64(cipher.auth_tag), 'data' => encode64(ciphertext))
+      end
+
+      def decrypt(scope, document)
+        parsed = JSON.parse(document)
+        raise Unavailable, 'The stored secrets use an unknown format' unless parsed['v'] == FORMAT_VERSION
+
+        cipher = OpenSSL::Cipher.new('aes-256-gcm').decrypt
+        cipher.key = key_for(scope)
+        cipher.iv = decode64(parsed.fetch('iv'))
+        cipher.auth_tag = decode64(parsed.fetch('tag'))
+        cipher.auth_data = scope
+        entries = JSON.parse(cipher.update(decode64(parsed.fetch('data'))) + cipher.final)
+        raise Unavailable, 'The stored secrets are damaged' unless entries.is_a?(Hash)
+
+        entries
+      rescue OpenSSL::Cipher::CipherError, JSON::ParserError, KeyError, ArgumentError, TypeError
+        raise Unavailable, "The stored secrets could not be decrypted: wrong #{KEY_ENV}, or the file is damaged"
+      end
+
+      def directory
+        @home.join('vault')
+      end
+
+      def file_for(scope)
+        Config.validate_id!(scope.to_s)
+        reject_symlink!(directory)
+        path = directory.join("#{scope}.enc")
+        reject_symlink!(path)
+        path
+      end
+
+      def ensure_directory!
+        directory.mkpath unless directory.exist?
+        raise Unavailable, 'The secret vault path is not a directory' unless directory.directory?
+
+        File.chmod(0o700, directory)
+      end
+
+      def store(path, document)
+        temp = directory.join(".#{path.basename}.#{Process.pid}.#{SecureRandom.hex(6)}.tmp")
+        begin
+          File.open(temp, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+            file.write(document)
+            file.flush
+            file.fsync
+          end
+          File.rename(temp, path)
+          File.chmod(0o600, path)
+        ensure
+          File.unlink(temp) if temp.exist?
+        end
+      end
+
+      def reject_symlink!(path)
+        raise Unavailable, 'The secret vault does not allow symlinks' if path.symlink?
+      end
+    end
+
+    register('file', FileVault)
+  end
+end

data/lib/workspaces/vault.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Workspaces
+  # Where write-only secrets live. The dashboard can put a secret in and a workspace's steps can read it
+  # back out, but nothing here ever hands a value to the interface.
+  #
+  # A provider stores one set of name => value strings per scope (a workspace id) and is chosen with
+  # WORKSPACES_VAULT (default "file"). Register another with Vault.register(name, ProviderClass). The
+  # contract is small on purpose so that a remote store fits behind it:
+  #
+  #   available?  / problem   whether it can be used, and if not, a plain-language reason that never
+  #                           contains key material
+  #   read(scope)             the whole set, {} when there is none; raises Unavailable when a set exists
+  #                           but cannot be read
+  #   write(scope, entries)   replaces the whole set; an empty hash removes it
+  #   purge(scope)            removes the set (used when a workspace is removed)
+  module Vault
+    class Error < StandardError; end
+    class Unavailable < Error; end
+
+    DEFAULT_PROVIDER = 'file'
+
+    # The shape every provider follows. Providers inherit it so a missing method fails loudly.
+    class Provider
+      def name
+        raise NotImplementedError, "#{self.class} must name itself"
+      end
+
+      def problem
+        nil
+      end
+
+      def available?
+        problem.nil?
+      end
+
+      def read(_scope)
+        raise NotImplementedError, "#{self.class} must implement read"
+      end
+
+      def write(_scope, _entries)
+        raise NotImplementedError, "#{self.class} must implement write"
+      end
+
+      def purge(_scope)
+        raise NotImplementedError, "#{self.class} must implement purge"
+      end
+
+      # Every scope this provider holds secrets for. Used to find the ones whose workspace is gone, so
+      # a provider that cannot list its scopes returns nil and is simply never swept.
+      def scopes
+        nil
+      end
+
+      def status
+        { 'provider' => name, 'available' => available?, 'problem' => problem }
+      end
+    end
+
+    # Stands in for a provider name nobody registered, so a typo shows up as a clear message in the
+    # dashboard rather than an exception while rendering it.
+    class Unknown < Provider
+      def initialize(requested)
+        super()
+        @requested = requested.to_s[0, 40]
+      end
+
+      def name
+        @requested
+      end
+
+      def problem
+        "Unknown secret vault provider #{@requested.inspect}"
+      end
+
+      # Nothing can be stored under an unknown provider, so there is nothing to read or remove; a typo
+      # in WORKSPACES_VAULT must not stop workspaces that have no secrets from running.
+      def read(_scope)
+        {}
+      end
+
+      def write(_scope, _entries)
+        raise Unavailable, problem
+      end
+
+      def purge(_scope)
+        nil
+      end
+
+      def scopes
+        nil
+      end
+    end
+
+    @providers = {}
+
+    class << self
+      def register(name, provider_class)
+        @providers[name.to_s] = provider_class
+      end
+
+      def provider(name = ENV.fetch('WORKSPACES_VAULT', nil))
+        requested = name.to_s.strip
+        requested = DEFAULT_PROVIDER if requested.empty?
+        klass = @providers[requested]
+        klass ? klass.new : Unknown.new(requested)
+      end
+
+      def status
+        provider.status
+      end
+
+      # Removes a workspace's secrets, whatever WORKSPACES_VAULT says now. The built-in file vault is
+      # always asked, because its files stay on disk when the setting is changed or mistyped; the
+      # configured provider is asked as well when it is a different one. Returns the problems it
+      # could not clear, as plain sentences with no key material, so a caller can say so instead of
+      # reporting a removal that left secrets behind.
+      # Scopes held by the built-in file vault and the configured provider, for finding orphans.
+      def scopes
+        [@providers.fetch(DEFAULT_PROVIDER).new, provider].uniq(&:name).flat_map { |vault| vault.scopes || [] }.uniq.sort
+      rescue StandardError
+        []
+      end
+
+      def purge_everywhere(scope)
+        providers = [@providers.fetch(DEFAULT_PROVIDER).new, provider]
+        providers.uniq(&:name).each_with_object([]) do |vault, problems|
+          vault.purge(scope)
+        rescue StandardError => e
+          problems << "#{vault.name}: #{e.message}"
+        end
+      end
+    end
+  end
+end
+
+require_relative 'vault/file_vault'

data/lib/workspaces/version.rb

@@ -1,3 +1,3 @@
 module Workspaces
-  VERSION = '0.1.17'
+  VERSION = '0.1.18'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.17
+  version: 0.1.18
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -102,6 +102,8 @@ files:
 - lib/workspaces/step_log.rb
 - lib/workspaces/tee_log.rb
 - lib/workspaces/tls.rb
+- lib/workspaces/vault.rb
+- lib/workspaces/vault/file_vault.rb
 - lib/workspaces/version.rb
 - lib/workspaces/workflow.rb
 - lib/workspaces/worktree.rb