env_bro 0.1.0

data/app/views/env_bro/reviews/show.html.erb

@@ -0,0 +1,134 @@
+<% content_for :title, "Review · #{@environment.name}" %>
+<% can_reveal = env_bro_can?(:reveal) %>
+<% meta = @differ.proposed_metadata %>
+<% changes = @differ.changes %>
+<% unchanged = @differ.entries.reject(&:changed?) %>
+
+<div class="page-head">
+  <div>
+    <h1>Proposed changes to <%= @environment.name %></h1>
+    <p class="muted">Compared against the <%= @base_enc ? "uploaded base file" : "file deployed on this server" %>
+      (<code><%= env_bro_short_digest(@base_digest) %></code>).</p>
+  </div>
+  <%= link_to "Review another file", new_review_path, class: "btn" %>
+</div>
+
+<% case @base_status %>
+<% when :current %>
+  <div class="alert alert-ok">Built on the same version it is compared against. The diff below is exactly what this PR changes.</div>
+<% when :stale %>
+  <div class="alert alert-warn">
+    <strong>Outdated base.</strong> This file was built on version <code><%= env_bro_short_digest(meta["base_digest"]) %></code>,
+    not <code><%= env_bro_short_digest(@base_digest) %></code>. Changes made since then may be reverted by this PR. Look for unexpected removals or changes,
+    and ask the author to rebuild the file if in doubt.
+  </div>
+<% else %>
+  <div class="alert alert-warn">
+    <strong>Not built with EnvBro.</strong> The file has no EnvBro metadata, so it may have been edited by hand or be an older copy of the file.
+    Check every change below carefully.
+  </div>
+<% end %>
+
+<div class="split">
+  <div>
+    <%= form_with url: reveal_review_path, method: :post, local: true, data: { turbo: false } do %>
+      <%= hidden_field_tag :proposed_enc, @proposed_enc %>
+      <%= hidden_field_tag :base_enc, @base_enc %>
+
+      <div class="panel">
+        <div class="toolbar">
+          <h2>Changed keys</h2>
+          <% if can_reveal && changes.any? %>
+            <button type="submit" name="reveal_key" value="*" class="btn btn-small">Reveal all values</button>
+          <% end %>
+        </div>
+
+        <div class="summary">
+          <% %i[added changed removed].each do |status| %>
+            <span class="badge badge-<%= status %>"><%= @differ.counts[status] || 0 %> <%= status %></span>
+          <% end %>
+          <span class="badge badge-unchanged"><%= unchanged.size %> unchanged</span>
+        </div>
+
+        <% if changes.empty? %>
+          <p class="empty">No key or value differs from the base file.</p>
+        <% else %>
+          <table>
+            <thead>
+              <tr><th>Key</th><th>Status</th><th>Before</th><th>After</th><% if can_reveal %><th></th><% end %></tr>
+            </thead>
+            <tbody>
+              <% changes.each do |entry| %>
+                <% revealed = @revealed.include?(entry.key) %>
+                <tr class="row-<%= entry.status %>">
+                  <td class="key"><%= entry.key %></td>
+                  <td class="nowrap"><%= env_bro_status_badge(entry.status) %></td>
+                  <td><%= revealed ? env_bro_value(entry.old_value) : env_bro_masked(entry.old_value) %></td>
+                  <td><%= revealed ? env_bro_value(entry.new_value) : env_bro_masked(entry.new_value) %></td>
+                  <% if can_reveal %>
+                    <td class="nowrap">
+                      <% unless revealed %>
+                        <button type="submit" name="reveal_key" value="<%= entry.key %>" class="btn-link">reveal</button>
+                      <% end %>
+                    </td>
+                  <% end %>
+                </tr>
+              <% end %>
+            </tbody>
+          </table>
+          <% if can_reveal %>
+            <p class="hint mt-12">Revealing values is recorded in the audit log.</p>
+          <% end %>
+        <% end %>
+      </div>
+
+      <% if unchanged.any? %>
+        <div class="panel">
+          <details>
+            <summary><%= unchanged.size %> unchanged keys</summary>
+            <table class="mt-12">
+              <tbody>
+                <% unchanged.each do |entry| %>
+                  <tr class="row-unchanged"><td class="key"><%= entry.key %></td></tr>
+                <% end %>
+              </tbody>
+            </table>
+          </details>
+        </div>
+      <% end %>
+    <% end %>
+  </div>
+
+  <div>
+    <div class="panel">
+      <h2>Proposal</h2>
+      <% if meta %>
+        <dl class="meta">
+          <dt>Author</dt><dd><%= meta["proposed_by"].presence || "unknown" %></dd>
+          <dt>Built at</dt><dd><%= meta["proposed_at"] %></dd>
+          <dt>Built on</dt><dd><code><%= env_bro_short_digest(meta["base_digest"]) %></code></dd>
+          <% if @proposal_event %>
+            <dt>Status</dt><dd><%= env_bro_deployment_badge(@proposal_event, EnvBro::AuditEvent.live_proposal) %></dd>
+          <% end %>
+        </dl>
+        <% if Array(meta["changes"]).any? %>
+          <p class="muted small mt-12">Changes declared by the author:</p>
+          <ul class="steps">
+            <% Array(meta["changes"]).each do |c| %><li><code><%= c %></code></li><% end %>
+          </ul>
+        <% end %>
+      <% else %>
+        <p class="muted">No EnvBro metadata in this file.</p>
+      <% end %>
+    </div>
+
+    <div class="panel">
+      <h2>Before merging</h2>
+      <ol class="steps">
+        <li>Every changed key is expected and matches the PR description.</li>
+        <li>No unexpected removals (a sign of an outdated or replaced file).</li>
+        <li>The PR changes only <code><%= @environment.filename %></code>, nothing else.</li>
+      </ol>
+    </div>
+  </div>
+</div>

data/app/views/env_bro/shared/_script.html.erb

@@ -0,0 +1,113 @@
+<script nonce="<%= content_security_policy_nonce %>">
+(function () {
+  "use strict";
+
+  var nextIndex = 1000;
+  var each = function (selector, fn, root) { Array.prototype.forEach.call((root || document).querySelectorAll(selector), fn); };
+
+  function autogrow(textarea) {
+    textarea.style.height = "auto";
+    textarea.style.height = textarea.scrollHeight + 2 + "px";
+  }
+
+  // Highlights edited/removed keys and summarizes what the download will contain.
+  function refresh() {
+    var changed = 0, removed = 0, added = 0;
+
+    each("[data-leaf]", function (line) {
+      var value = line.querySelector("textarea");
+      var remove = line.querySelector("[data-remove-toggle]");
+      var isRemoved = remove.checked;
+      var isChanged = !isRemoved && value.value.trim() !== "";
+      value.disabled = isRemoved;
+      line.classList.toggle("is-removed", isRemoved);
+      line.classList.toggle("is-changed", isChanged);
+      if (isRemoved) removed++;
+      if (isChanged) changed++;
+    });
+
+    each("[data-new-key-row]", function (row) {
+      if (row.querySelector("input").value.trim() !== "") added++;
+    });
+
+    var summary = document.querySelector("[data-summary]");
+    var submit = document.querySelector("[data-submit]");
+    if (!summary) return;
+    var parts = [];
+    if (added) parts.push(added + " new");
+    if (changed) parts.push(changed + " changed");
+    if (removed) parts.push(removed + " removed");
+    summary.textContent = parts.length ? parts.join(" · ") : "No changes yet";
+    summary.classList.toggle("has-changes", parts.length > 0);
+    if (submit) submit.disabled = parts.length === 0;
+  }
+
+  function addNewKey() {
+    var template = document.getElementById("new-key-template");
+    var list = document.querySelector("[data-new-keys]");
+    if (!template || !list) return;
+    var holder = document.createElement("div");
+    holder.innerHTML = template.innerHTML.replace(/__INDEX__/g, String(nextIndex++)).trim();
+    var row = holder.firstElementChild;
+    list.appendChild(row);
+    row.querySelector("input").focus();
+  }
+
+  function filter(query) {
+    query = query.toLowerCase();
+    var visible = [];
+    each("[data-leaf]", function (line) {
+      var path = line.getAttribute("data-leaf");
+      var show = path.toLowerCase().indexOf(query) !== -1;
+      line.classList.toggle("hidden", !show);
+      if (show) visible.push(path);
+    });
+    each("[data-group]", function (group) {
+      var prefix = group.getAttribute("data-group") + ".";
+      group.classList.toggle("hidden", !visible.some(function (p) { return p.indexOf(prefix) === 0; }));
+    });
+    each("[data-filter-empty]", function (el) { el.classList.toggle("hidden", visible.length > 0); });
+  }
+
+  document.addEventListener("click", function (event) {
+    var el = event.target.closest("[data-add-new-key], [data-remove-new-key]");
+    if (!el) return;
+    event.preventDefault();
+
+    if (el.hasAttribute("data-add-new-key")) {
+      addNewKey();
+    } else {
+      var row = el.closest("[data-new-key-row]");
+      if (document.querySelectorAll("[data-new-key-row]").length > 1) {
+        row.remove();
+      } else {
+        each("input, textarea", function (i) { i.value = ""; }, row);
+      }
+    }
+    refresh();
+  });
+
+  document.addEventListener("input", function (event) {
+    var target = event.target;
+    if (target.matches("[data-filter]")) filter(target.value);
+    if (target.matches("[data-autogrow]")) autogrow(target);
+    if (target.matches("[data-track]")) refresh();
+  });
+
+  document.addEventListener("change", function (event) {
+    if (!event.target.matches("[data-remove-toggle]")) return;
+    refresh();
+    if (!event.target.checked) event.target.closest("[data-leaf]").querySelector("textarea").focus();
+  });
+
+  // The proposal form answers with a file download, so the page itself does not change.
+  document.addEventListener("submit", function (event) {
+    if (!event.target.matches("[data-proposal-form]")) return;
+    var notice = document.getElementById("download-notice");
+    if (notice) setTimeout(function () { notice.hidden = false; notice.scrollIntoView({ behavior: "smooth", block: "nearest" }); }, 400);
+  });
+
+  each("[data-autogrow]", autogrow);
+  refresh();
+})();
+</script>

data/app/views/env_bro/shared/_styles.html.erb

@@ -0,0 +1,151 @@
+<style nonce="<%= content_security_policy_nonce %>">
+  :root {
+    --bg: #f6f7f9; --panel: #ffffff; --text: #1d2330; --muted: #6b7385; --border: #e1e4ea;
+    --accent: #3b5bdb; --accent-text: #ffffff; --danger: #c92a2a; --warn-bg: #fff4e0; --warn: #9a5b00;
+    --ok-bg: #e6f6ec; --ok: #1f7a3f; --code-bg: #f1f3f6;
+    --added: #1f7a3f; --added-bg: #e6f6ec; --removed: #c92a2a; --removed-bg: #fdecec;
+    --changed: #9a5b00; --changed-bg: #fff4e0;
+    --radius: 8px;
+    --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #12151b; --panel: #1b1f27; --text: #e4e7ee; --muted: #8d95a7; --border: #2c323d;
+      --accent: #6d8bff; --accent-text: #0d1020; --danger: #ff6b6b; --warn-bg: #3a2c12; --warn: #ffc566;
+      --ok-bg: #143122; --ok: #6fdc98; --code-bg: #232833;
+      --added: #6fdc98; --added-bg: #143122; --removed: #ff8787; --removed-bg: #3a1a1a;
+      --changed: #ffc566; --changed-bg: #3a2c12;
+    }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--text);
+    font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; }
+  a { color: var(--accent); text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  h1 { font-size: 1.5rem; margin: 0 0 4px; }
+  h2 { font-size: 1.1rem; margin: 0 0 12px; }
+  p { margin: 0 0 12px; }
+  code, .mono { font-family: var(--mono); font-size: .9em; }
+  .wrap { max-width: 1040px; margin: 0 auto; padding: 0 16px; }
+  main.wrap { padding-top: 24px; padding-bottom: 64px; }
+
+  .topbar { background: var(--panel); border-bottom: 1px solid var(--border); }
+  .topbar-inner { display: flex; align-items: center; gap: 24px; height: 56px; }
+  .brand { font-weight: 700; color: var(--text); font-size: 1.05rem; }
+  .brand:hover { text-decoration: none; }
+  .nav { display: flex; gap: 16px; flex: 1; }
+  .nav a { color: var(--muted); }
+  .nav a:hover { color: var(--text); text-decoration: none; }
+
+  .page-head { display: flex; justify-content: space-between; align-items: flex-end; gap: 16px; margin-bottom: 20px; flex-wrap: wrap; }
+  .muted { color: var(--muted); }
+  .small { font-size: .85rem; }
+
+  .panel { background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius); padding: 20px; margin-bottom: 20px; }
+  .split { display: grid; grid-template-columns: 1fr 320px; gap: 20px; align-items: start; }
+  @media (max-width: 820px) { .split { grid-template-columns: 1fr; } }
+
+
+  .btn { display: inline-flex; align-items: center; gap: 6px; padding: 8px 14px; border-radius: 6px;
+    border: 1px solid var(--border); background: var(--panel); color: var(--text); font: inherit; font-size: .9rem;
+    cursor: pointer; line-height: 1.2; }
+  .btn:hover { text-decoration: none; border-color: var(--muted); }
+  .btn-primary { background: var(--accent); color: var(--accent-text); border-color: var(--accent); font-weight: 600; }
+  .btn-primary:hover { filter: brightness(1.08); border-color: var(--accent); }
+  .btn-small { padding: 3px 8px; font-size: .8rem; }
+  .btn-link { background: none; border: none; color: var(--accent); padding: 0; cursor: pointer; font: inherit; font-size: .85rem; }
+  .btn-danger { color: var(--danger); }
+  .btn[disabled] { opacity: .5; cursor: not-allowed; }
+
+  label { display: block; font-weight: 600; font-size: .85rem; margin-bottom: 4px; }
+  input[type=text], input[type=search], select, textarea {
+    width: 100%; padding: 8px 10px; border: 1px solid var(--border); border-radius: 6px;
+    background: var(--bg); color: var(--text); font: inherit; }
+  textarea { font-family: var(--mono); font-size: .85rem; min-height: 38px; resize: vertical; }
+  input:focus, select:focus, textarea:focus { outline: 2px solid var(--accent); outline-offset: -1px; }
+  input[type=file] { font: inherit; font-size: .9rem; }
+  .field { margin-bottom: 16px; }
+  .hint { font-size: .8rem; color: var(--muted); margin-top: 4px; font-weight: normal; }
+
+  .alert { padding: 12px 14px; border-radius: 6px; margin-bottom: 16px; font-size: .9rem; }
+  .alert-error { background: var(--removed-bg); color: var(--removed); }
+  .alert-warn { background: var(--warn-bg); color: var(--warn); }
+  .alert-ok { background: var(--ok-bg); color: var(--ok); }
+
+  table { width: 100%; border-collapse: collapse; font-size: .9rem; }
+  th, td { text-align: left; padding: 8px 10px; border-bottom: 1px solid var(--border); vertical-align: top; }
+  th { font-size: .75rem; text-transform: uppercase; letter-spacing: .04em; color: var(--muted); font-weight: 600; }
+  tr:last-child td { border-bottom: none; }
+  td.key { font-family: var(--mono); font-size: .85rem; overflow-wrap: anywhere; min-width: 180px; }
+  td.nowrap, th.nowrap { white-space: nowrap; }
+  .row-added td.key { color: var(--added); }
+  .row-removed td.key { color: var(--removed); }
+  .row-changed td.key { color: var(--changed); }
+  .row-unchanged { color: var(--muted); }
+
+  .badge { display: inline-block; padding: 1px 8px; border-radius: 999px; font-size: .75rem; font-weight: 600; }
+  .badge-added { background: var(--added-bg); color: var(--added); }
+  .badge-removed { background: var(--removed-bg); color: var(--removed); }
+  .badge-changed { background: var(--changed-bg); color: var(--changed); }
+  .badge-unchanged, .badge-neutral { background: var(--code-bg); color: var(--muted); }
+  .badge-ok { background: var(--ok-bg); color: var(--ok); }
+  .badge-danger { background: var(--removed-bg); color: var(--removed); }
+
+  .mask { letter-spacing: 2px; color: var(--muted); }
+  code.value { display: inline-block; background: var(--code-bg); padding: 2px 6px; border-radius: 4px;
+    white-space: pre-wrap; word-break: break-all; max-width: 100%; }
+
+  .panel-flush { padding: 0; overflow: hidden; }
+  .panel-pad { padding: 16px 20px 0; }
+  .filter { max-width: 240px; padding: 6px 10px; font-size: .85rem; }
+  .hidden { display: none !important; }
+  .icon-btn { background: none; border: none; color: var(--muted); cursor: pointer; font-size: 1rem; padding: 6px; border-radius: 4px; }
+  .icon-btn:hover { color: var(--danger); background: var(--removed-bg); }
+
+  .newkey-row { display: grid; grid-template-columns: minmax(180px, 2fr) 3fr 32px; gap: 8px; margin-bottom: 8px; align-items: start; }
+  @media (max-width: 640px) { .newkey-row { grid-template-columns: 1fr 32px; } .newkey-row textarea { grid-column: 1; } }
+
+  /* Existing keys, laid out like the YAML file. */
+  .yaml { font-family: var(--mono); font-size: .875rem; border-top: 1px solid var(--border); margin-top: 16px; }
+  .yaml-line { display: grid; grid-template-columns: minmax(200px, 38%) 1fr auto; gap: 12px; align-items: center;
+    padding: 4px 20px; border-left: 3px solid transparent; }
+  .yaml-line:hover { background: var(--code-bg); }
+  .yaml-group { padding-top: 10px; padding-bottom: 2px; }
+  .yaml-group:hover { background: none; }
+  .yaml-group .yaml-key { color: var(--muted); font-weight: 600; }
+  .yaml-key { font-weight: normal; font-size: inherit; margin: 0; overflow-wrap: anywhere; cursor: text; }
+  .depth-1 { padding-left: 20px; } .depth-2 { padding-left: 40px; } .depth-3 { padding-left: 60px; }
+  .depth-4 { padding-left: 80px; } .depth-5 { padding-left: 100px; } .depth-6 { padding-left: 120px; }
+  .yaml-line textarea, .newkey-row textarea { resize: none; overflow: hidden; }
+  .yaml-line textarea { min-height: 32px; padding: 5px 10px; background: transparent; border-color: transparent; }
+  .yaml-line:hover textarea, .yaml-line textarea:focus { background: var(--bg); border-color: var(--border); }
+  .yaml-line textarea::placeholder { color: var(--muted); letter-spacing: 1px; }
+  .yaml-line.is-changed { border-left-color: var(--changed); background: var(--changed-bg); }
+  .yaml-line.is-changed .yaml-key { color: var(--changed); }
+  .yaml-line.is-changed textarea { background: var(--bg); border-color: var(--border); }
+  .yaml-line.is-removed { border-left-color: var(--removed); background: var(--removed-bg); }
+  .yaml-line.is-removed .yaml-key { color: var(--removed); text-decoration: line-through; }
+  .yaml-line.is-removed textarea { visibility: hidden; }
+  .remove-toggle { display: flex; align-items: center; gap: 4px; margin: 0; font: inherit; font-size: .8rem; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    font-weight: normal; color: var(--muted); cursor: pointer; white-space: nowrap; }
+  .yaml-line.is-removed .remove-toggle { color: var(--removed); }
+  .yaml .empty { font-family: inherit; }
+
+  .submitbar { position: sticky; bottom: 0; z-index: 5; display: flex; justify-content: space-between; align-items: center; gap: 16px;
+    background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius); padding: 12px 20px; margin-bottom: 16px;
+    box-shadow: 0 -4px 16px rgba(0, 0, 0, .08); }
+  .submitbar [data-summary].has-changes { color: var(--text); font-weight: 600; }
+
+  .steps { margin: 0; padding-left: 20px; font-size: .9rem; }
+  .steps li { margin-bottom: 6px; overflow-wrap: anywhere; }
+  .meta { display: grid; grid-template-columns: max-content 1fr; gap: 4px 16px; font-size: .9rem; margin: 0; }
+  .meta dt { color: var(--muted); }
+  .meta dd { margin: 0; }
+  .summary { display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 12px; }
+  .empty { text-align: center; padding: 32px; color: var(--muted); }
+  .toolbar { display: flex; justify-content: space-between; align-items: center; gap: 12px; margin-bottom: 12px; flex-wrap: wrap; }
+  .toolbar h2 { margin: 0; }
+  .mt-12 { margin-top: 12px; }
+  .mt-16 { margin-top: 16px; margin-bottom: 0; }
+  details summary { cursor: pointer; color: var(--muted); font-size: .9rem; }
+</style>

data/app/views/env_bro/shared/forbidden.html.erb

@@ -0,0 +1,5 @@
+<% content_for :title, "Not allowed" %>
+<div class="panel empty">
+  <h1>Not allowed</h1>
+  <p>You don't have permission to use this part of EnvBro. Ask an admin if you need access.</p>
+</div>

data/app/views/env_bro/shared/not_ready.html.erb

@@ -0,0 +1,13 @@
+<% content_for :title, "Not available" %>
+<% status = @environment.status %>
+<div class="panel">
+  <h1><%= @environment.name %> credentials <%= env_bro_environment_badge(status) %></h1>
+  <% case status
+     when :missing_file %>
+    <p>There is no credentials file at <code><%= env_bro_display_path(@environment.content_path) %></code> on this server.</p>
+  <% when :missing_key %>
+    <p>This server has no key for <code><%= @environment.filename %></code>. Set <code><%= @environment.env_key %></code> or add <code><%= env_bro_display_path(@environment.key_path) %></code>.</p>
+  <% else %>
+    <p>The key on this server (<code><%= @environment.env_key %></code> or <code><%= env_bro_display_path(@environment.key_path) %></code>) cannot decrypt <code><%= @environment.filename %></code>.</p>
+  <% end %>
+</div>

data/app/views/layouts/env_bro/application.html.erb

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="robots" content="noindex, nofollow">
+  <title><%= content_for?(:title) ? "#{yield(:title)} · EnvBro" : "EnvBro" %></title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+  <%= render "env_bro/shared/styles" %>
+</head>
+<body>
+  <header class="topbar">
+    <div class="wrap topbar-inner">
+      <%= link_to root_path, class: "brand" do %>
+        <span class="brand-mark">🔐</span> EnvBro
+      <% end %>
+      <span class="badge badge-neutral"><%= @environment.name %></span>
+      <nav class="nav">
+        <% if env_bro_can?(:propose) %><%= link_to "Propose", new_proposal_path %><% end %>
+        <% if env_bro_can?(:review) %>
+          <%= link_to "Review", new_review_path %>
+          <%= link_to "Audit log", audit_path %>
+        <% end %>
+      </nav>
+      <% if env_bro_user %>
+        <span class="whoami muted small"><%= EnvBro.config.user_label.call(env_bro_user) %></span>
+      <% end %>
+    </div>
+  </header>
+
+  <main class="wrap">
+    <%= yield %>
+  </main>
+
+  <%= render "env_bro/shared/script" %>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,11 @@
+EnvBro::Engine.routes.draw do
+  root "home#index"
+
+  get "proposal/new" => "proposals#new", as: :new_proposal
+  post "proposal" => "proposals#create", as: :proposal
+  get "review/new" => "reviews#new", as: :new_review
+  post "review" => "reviews#create", as: :review
+  post "review/reveal" => "reviews#reveal", as: :reveal_review
+
+  get "audit" => "audit#index", as: :audit
+end

data/db/migrate/20261029000000_create_env_bro_audit_events.rb

@@ -0,0 +1,24 @@
+class CreateEnvBroAuditEvents < ActiveRecord::Migration[7.1]
+  def change
+    create_table :env_bro_audit_events do |t|
+      t.string :event, null: false
+      t.string :user_label
+      t.string :environment, null: false
+      t.json :details, null: false, default: {}
+
+      # proposal_created: the id embedded in the file's metadata and the SHA-256 of the file handed out.
+      # proposal_deployed: the SHA-256 of the file found running.
+      t.string :proposal_token
+      t.string :file_digest
+
+      # proposal_deployed: the proposal that went live.
+      t.references :proposal, foreign_key: { to_table: :env_bro_audit_events }, index: { unique: true }
+
+      t.datetime :created_at, null: false
+    end
+
+    add_index :env_bro_audit_events, :created_at
+    add_index :env_bro_audit_events, :proposal_token
+    add_index :env_bro_audit_events, :file_digest
+  end
+end

data/lib/env_bro/audit.rb

@@ -0,0 +1,17 @@
+module EnvBro
+  # Records who did what in EnvBro::AuditEvent. Never records secret values, only key names.
+  module Audit
+    module_function
+
+    # columns: extra AuditEvent attributes (proposal_token, file_digest, proposal).
+    def record(event, user:, columns: {}, **details)
+      EnvBro::AuditEvent.create!(
+        event: event.to_s,
+        user_label: user.is_a?(String) ? user : EnvBro.config.user_label.call(user).to_s,
+        environment: Rails.env.to_s,
+        details: details.deep_stringify_keys,
+        **columns
+      )
+    end
+  end
+end

data/lib/env_bro/configuration.rb

@@ -0,0 +1,44 @@
+module EnvBro
+  class Configuration
+    # Controller the engine controllers inherit from. Inheriting from the host's
+    # ApplicationController gives access to its authentication (current_user etc).
+    attr_accessor :parent_controller
+
+    # ->(controller) { ... } returning the signed in user, or nil.
+    attr_accessor :current_user
+
+    # ->(user) { ... } returning a short label for the audit log and file metadata.
+    attr_accessor :user_label
+
+    # Permission checks, each ->(user) { true/false }.
+    #   can_propose - see key names, build a new encrypted file with changes
+    #   can_review  - upload a proposed file and see which keys changed (values masked)
+    #   can_reveal  - reveal the actual values in a review diff (every reveal is audited)
+    attr_accessor :can_propose, :can_review, :can_reveal
+
+    # Reject plain HTTP requests (secret values travel through the browser).
+    attr_accessor :require_ssl
+
+    # Top-level credentials key where EnvBro stores proposal metadata
+    # (base file digest, author, time). Set to nil to disable.
+    attr_accessor :metadata_key
+
+    attr_accessor :max_upload_bytes
+
+    # On boot, record when the running credentials file came from an EnvBro proposal.
+    attr_accessor :track_deployments
+
+    def initialize
+      @parent_controller = "::ApplicationController"
+      @current_user = ->(controller) { controller.respond_to?(:current_user, true) ? controller.send(:current_user) : nil }
+      @user_label = ->(user) { user.respond_to?(:email) ? user.email : user.to_s }
+      @can_propose = ->(_user) { false }
+      @can_review = ->(_user) { false }
+      @can_reveal = ->(_user) { false }
+      @require_ssl = defined?(Rails) && Rails.env.production?
+      @metadata_key = "env_bro"
+      @max_upload_bytes = 1024 * 1024
+      @track_deployments = true
+    end
+  end
+end