open-loam 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc673a0615dde0e5fb30f18d5b3f463fde57a87528e20d26ce8a97455240de5d
-  data.tar.gz: 62413655b212a0fcdd2ded4ae0eafb249e2fa1060b70b96f0d6e66ad1a2f6480
+  metadata.gz: 48bb3940900ff3d8ee4f6a8dc499779b3d00ed9ff37ceeab4849d36662377a47
+  data.tar.gz: 65440f973fc99d793ae2439cb1a1b373cd7f79d41c82398fd8d59c6e4dcba784
 SHA512:
-  metadata.gz: 78bda4ab675f9d4e47c4fafa538cc340c21109c4fa82af6ca203596e41d57091c833d3e8868122640ffef5158f30188ffaf7d305a8f4e72e194525ac0e754e9b
-  data.tar.gz: bb22f492bca6bba9de01bea58c57465a67d0b5f6ef1b92ca8cb8bb6ffadc9c533d8ce3915ca8fe51e3c0278da9d4aa4a48501dd3a4d94dabadc4547a4667efd8
+  metadata.gz: a091472e49805c7fffe3aa95a6ddfd0ffc02fea5c7e8d368443be195854e5bdd87b4b7b7635d4c7024842d4a62015d55e6a63064009d13cce8158fff3b7bb207
+  data.tar.gz: 10546c0bc5b0e6facacf2ede136cd930aa3851c833ae05aa908f990bc60ea02db3efccf1483b5577c0ba4d5cf7136b369c31956a3d1c989444824a1f87836c08

data/CHANGELOG.md

@@ -1,10 +1,150 @@
 # Changelog
 
-Notable changes to Loam. This project follows [semantic versioning](https://semver.org),
+Notable changes to OpenLoam. This project follows [semantic versioning](https://semver.org),
 with the caveat that 0.x releases may break the public surface; the
 [backward-compatibility contract](BACKWARD_COMPATIBILITY.md) names what is
 frozen and what is not.
 
+## 0.3.0 — 2026-09-05
+
+### Security
+
+A full-repo audit found 16 issues. Fifteen are fixed here, each with a regression
+test verified by reverting the fix and confirming the test fails; the sixteenth
+is the demo app's committed `master.key`, which is accepted — the demo holds no
+real data and must never be deployed. **Anyone running 0.2.0 or earlier should
+upgrade**, and the migration below is not optional: three steps change stored
+data.
+
+Worst first:
+
+- **Cross-tenant account takeover through SSO.** A tenant could register a domain
+  it did not own and be handed the matching global account, then select any
+  tenant that account belonged to. A provider now does nothing until an operator
+  confirms ownership out of band (`rake open_loam:sso:verify_domain`), and
+  editing `domain` revokes the confirmation.
+- **The MFA lockout was bypassable** — a password success cleared the TOTP
+  counter, so a 6-digit code could be brute-forced without limit. Each factor now
+  clears only its own attempts.
+- **`readable:` field rules were ignored on most read paths** — the JSON API, the
+  generated admin index/show/form, the custom-fields partial, the CSV export,
+  the history screen and the edit-conflict diff all served restricted values.
+  Sorting by an unreadable column is refused too: ordering leaks a ranking even
+  when the values are hidden. A model with no policy class no longer falls back
+  to the base policy, which answered "any member" to everything.
+- **API tokens were stored in plaintext.** A SHA-256 digest is persisted now and
+  the value is shown once. Offboarding a user ends their machine access, and
+  managers can revoke another member's token — previously nobody could.
+- **SSRF through tenant-supplied URLs** — webhook endpoints and the SSO issuer
+  were both fetched unvalidated. `OpenLoam::OutboundUrl` checks shape at save and
+  pins the resolved address at fetch, so DNS rebinding cannot swap the target
+  after the check. The issuer must now be `https`.
+- **Inbound webhook replay** — the dedupe key came from an unsigned header, so
+  one captured delivery could re-publish its event without limit. `external_id`
+  is now the body hash, the only signed material.
+- **A staged change was applied without checks.** The target must now be a
+  `TenantRecord`, and approval runs the approver's own policy — both the action
+  (`create?`/`update?`/`destroy?`) and the fields the changeset writes.
+- **`security.mfa_required_roles` was advisory** — enrollment was redirected to
+  at login and never checked again. Now enforced on every request.
+- **Master-key rotation was impossible**, despite being the documented answer to
+  key compromise. Set `OPEN_LOAM_PREVIOUS_MASTER_KEY` to the outgoing key and
+  `open_loam:encryption:rotate` works.
+- **The blind-index key ignored table and column**, so one value hashed alike
+  across every searchable encrypted column. It now binds both, like the AAD.
+- **The uploaded import CSV** sat in the clear in the queue backend and the
+  request log. It goes to blob storage now, and the job purges it.
+- **Brakeman never scanned the gem**, only `demo/`. CI now scans both, which
+  surfaced four warnings, all fixed. CI's `GITHUB_TOKEN` is read-only, and the
+  repository has secret scanning, push protection and private vulnerability
+  reporting enabled.
+
+Report vulnerabilities through [private reporting](https://github.com/DeliveristsIO/open-loam/security/advisories/new),
+not a public issue.
+
+#### Migration
+
+- `open_loam_api_tokens`: add `token_digest`, backfill `sha256(token)` per row,
+  drop `token`. Tokens in use keep working. See the demo's
+  `hash_open_loam_api_tokens`.
+- `open_loam_sso_providers`: add `domain_verified_at`, then run
+  `rake open_loam:sso:verify_domain[<id>]` for each provider you actually own.
+  Until you do, SSO will not resolve for it.
+- Searchable encrypted fields: re-index by running
+  `rake open_loam:encryption:rotate[Model,tenant_id]` for each model that has
+  one. The blind-index derivation changed, so existing `<field>_hash` values no
+  longer match.
+- `delivery_id_header` on inbound webhook sources is gone; the column can be
+  dropped.
+
+### Added
+
+- **The event log — `OpenLoam::EventLog` + `OpenLoam::EventRecord`.** Every
+  published event is captured as an append-only, tenant-scoped row, so a
+  tenant's history is queryable and replayable rather than only observable live.
+  `EventLog.read(name_or_prefix, since:, limit:)` and `EventLog.replay(...)` take
+  the same patterns as `Events.subscribe`. `OpenLoam::DurableEvents` had made
+  *delivery* durable; this closes *capture*, which its contract explicitly did
+  not cover.
+
+  Capture is on by default and captures everything except
+  `OpenLoam.uncaptured_events` (default: `["open_loam.progress."]`). It runs
+  inline, so a failed insert propagates into the publishing operation. Retention
+  is `OpenLoam.event_log_retention` (90 days), swept per tenant by
+  `OpenLoam::EventLogPruneJob`. New apps get the table from
+  `rails g open_loam:install`; existing apps need the
+  `create_open_loam_event_records` migration.
+
+- **An authorization-called guard in the generated base controllers** (L-202).
+  `verify_authorized!` fails any admin or API action that finished without
+  calling `authorize!`, `require_role!` or `require_permission!`. Forgetting the
+  check was previously silent — the screen just rendered. Screens authorized
+  structurally declare `skip_authorization! "<reason>"`, and the reason is
+  required, so every exemption is a documented claim.
+
+  It runs *after* the action, so it is a development and test guard, not a
+  runtime access-control layer. It raises `OpenLoam::AuthorizationNotPerformedError`,
+  deliberately not a `NotAuthorizedError` — a developer bug must not render as a
+  polite 403.
+
+  Turning it on found two generated actions that never checked `read?` while
+  their `show`/`deleted` siblings did: the admin and JSON `index`. Both now
+  authorize. Existing apps will see the guard fire on any action of their own
+  that never authorized.
+
+### Changed
+
+- **The four "wrap a proven gem" roadmap items are resolved**, recorded in
+  [ADR 0007](docs/_adr/0007-proven-gem-swaps-resolved.md). Tenancy (L-201) and
+  audit (L-203) stay in-gem for good; the Pundit swap (L-202) is declined, but
+  the gap it exposed — no `verify_authorized`-equivalent guard — is tracked
+  separately. L-204 is the event log above. No public `OpenLoam::` contract
+  changed.
+
+## 0.2.0 — 2026-09-05
+
+### BREAKING
+
+- **Ruby namespace renamed `Loam` → `OpenLoam`**, and every dependent
+  surface with it: the CLI (`rails g open_loam:install`,
+  `rails g open_loam:entity`, `bin/rails open_loam:mcp:serve`, etc.), all
+  `loam_*`-prefixed database tables and columns, `LOAM_*` env vars (now
+  `OPEN_LOAM_*`), and the outbound webhook signature header
+  (`X-Loam-Signature` → `X-OpenLoam-Signature`, tracked in
+  [BACKWARD_COMPATIBILITY.md](BACKWARD_COMPATIBILITY.md)). The RubyGems
+  package name is unaffected — it stays `open-loam`, as it already was.
+- No back-compat shim is provided for any of this. Per 0.1.0/0.1.1 above, no
+  production deployment exists yet, so there is nothing running against the
+  old names to break in place — an app installed from an 0.1.x generator
+  would need its own table/env-var renames to upgrade, which is why this
+  ships as a breaking 0.x release rather than a deprecation cycle.
+- One literal is deliberately **not** renamed, ever: the encryption
+  key-derivation inputs in `lib/open_loam/encryption/key_provider.rb`
+  (the HKDF `SALT` and `info` strings) and the AAD prefix in
+  `lib/open_loam/encryption.rb#aad`. These are inputs to key/tag
+  derivation, not identifiers — changing any of them would silently
+  break decryption of already-encrypted data.
+
 ## 0.1.1 — 2026-09-04
 
 No functional change. The packaged code is byte-identical to 0.1.0 — only CI
@@ -23,14 +163,14 @@ matters.
 
 ## 0.1.0 — 2026-09-04
 
-First public release. Loam is a working, tested prototype: the foundation and
+First public release. OpenLoam is a working, tested prototype: the foundation and
 the agent workflow are complete end to end, but no production deployment has
 used it yet. Evaluate it as a prototype, not as proven infrastructure.
 
 ### The foundation
 
-- **Multi-tenancy** — `Loam::TenantRecord` scopes every query, job and event to
-  the current tenant. A missing tenant context raises `Loam::MissingTenantError`
+- **Multi-tenancy** — `OpenLoam::TenantRecord` scopes every query, job and event to
+  the current tenant. A missing tenant context raises `OpenLoam::MissingTenantError`
   rather than silently widening a query.
 - **Authorization** — roles, policies, field-level write access, and
   deny-by-default wildcard feature permissions (`equipment.*`).
@@ -56,13 +196,13 @@ used it yet. Evaluate it as a prototype, not as proven infrastructure.
 
 - **`AGENTS.md`** — the contract, generated into the host app, telling an agent
   where code belongs and which boundaries it must preserve.
-- **Generators as the interface** — `loam:install` and `loam:entity` are the
+- **Generators as the interface** — `open_loam:install` and `open_loam:entity` are the
   supported way to add a feature, for humans and agents alike.
 - **Structural guardrails** — tests that fail the build on a missing tenant
   scope, a stray `.unscoped`, or an oversized `AGENTS.md`.
-- **A human-approval gate** — `Loam::PendingActions` stages an agent-proposed
+- **A human-approval gate** — `OpenLoam::PendingActions` stages an agent-proposed
   mutation for review before it touches business data.
-- **The golden-tasks benchmark** and `Loam::Eval` scorer. Results, methodology
+- **The golden-tasks benchmark** and `OpenLoam::Eval` scorer. Results, methodology
   and caveats are published at
   <https://deliveristsio.github.io/open-loam/agents/golden-tasks/>; they come
   from a single internal run and are not independently reproduced.
@@ -74,7 +214,7 @@ used it yet. Evaluate it as a prototype, not as proven infrastructure.
   `config.generators` setting, then `bigint`. This covers `create_table`,
   `t.references`, and the polymorphic `*_id` columns that cannot use
   `t.references`.
-- `Loam::GeneratedKey` assigns a UUID before create when the key is not an
+- `OpenLoam::GeneratedKey` assigns a UUID before create when the key is not an
   integer, since a string primary key has no database default. Integer keys are
   still generated by the database.
 

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Grzegorz Smajdor and Loam contributors
+Copyright (c) 2026 Grzegorz Smajdor and OpenLoam contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,6 +1,6 @@
-# Loam 🌱
+# OpenLoam 🌱
 
-**In short:** Loam is a Rails starter kit for business apps — multi-tenancy,
+**In short:** OpenLoam is a Rails starter kit for business apps — multi-tenancy,
 permissions, audit trails, workflows, and an event bus already built in, so you
 skip months of plumbing and start on real features. It's also AI-native:
 convention-driven code that AI coding agents (Claude Code, Codex, etc.) can
@@ -12,7 +12,7 @@ safely extend, with human-approval gates before any agent write takes effect.
 
 ---
 
-## Why Loam exists
+## Why OpenLoam exists
 
 Every serious back-office app — CRM, ERP, ops console, internal tool — re-derives
 the same ~80%: who's the tenant, who's allowed, what changed and when, how do
@@ -24,13 +24,13 @@ write real features — *if* the codebase is legible to them. Sprawling, snowfla
 architectures confuse agents as much as they confuse new hires. Convention is
 what makes a codebase safe for an agent to extend.
 
-Loam fuses the two: **a pre-built business foundation that is deliberately
+OpenLoam fuses the two: **a pre-built business foundation that is deliberately
 agent-legible.** Rails already leans convention-over-configuration — arguably the
-most agent-friendly framework there is. Loam extends that philosophy from "how to
+most agent-friendly framework there is. OpenLoam extends that philosophy from "how to
 structure a controller" up to "how a multi-tenant, permissioned, audited business
 domain is built" — and ships the agent conventions to match.
 
-## Where Loam sits
+## Where OpenLoam sits
 
 The pieces exist in Rails, but scattered — foundation shape in Bullet Train and
 the commerce products, an event backbone in Rails Event Store, custom-entity
@@ -39,7 +39,7 @@ agent-legible business foundation. The closest structural analogs live in other
 stacks: Frappe/ERPNext in Python, and
 **[Open Mercato](https://github.com/open-mercato/open-mercato)** in TypeScript —
 whose module system and convention-first, agent-legible approach directly
-inspired Loam. Loam brings that idea to Rails, the substrate it always suited.
+inspired OpenLoam. OpenLoam brings that idea to Rails, the substrate it always suited.
 
 ---
 
@@ -51,21 +51,21 @@ need to — never a blank page.
 | Pillar | What you get, out of the box |
 |--------|------------------------------|
 | 🏢 **Multi-tenancy** | Tenant isolation baked into every query, background job, and event. New models are tenant-scoped by default; a missing tenant context raises, never silently widens a query. |
-| 🔐 **Permissions & auth** | Password login, roles, policies, and field-level write access — declared, not hand-rolled per controller. Tenant selection limited to a user's memberships. Plus **feature-string permissions** (`Loam::Permissions`): grant a role wildcard capability strings (`equipment.*`) and check `Loam.can?("equipment.edit")` / `require_permission!` — deny-by-default, a finer layer under the coarse role. |
-| 🌾 **Custom fields** | Define fields at runtime (a `custom_fields` JSON column + a `Loam::FieldDefinition` row), so agents and admins extend a model without a migration for every idea. Filtering and sorting on a custom field is **index-backed** at scale via a typed read-model projection (`Loam::CustomFieldIndex`), not a per-row JSON scan — with **coverage accounting** (is the index complete or drifting?), a read-time gap that **falls back to the authoritative source for correctness** and **self-heals** in the background (deduped), and an honest "results may be incomplete" signal while it does. A field can declare `readable_roles`: filtering or sorting on a field a role **may not read** is refused, so a filter can't become an **inference oracle** on a restricted value. |
+| 🔐 **Permissions & auth** | Password login, roles, policies, and field-level write access — declared, not hand-rolled per controller. Tenant selection limited to a user's memberships. Plus **feature-string permissions** (`OpenLoam::Permissions`): grant a role wildcard capability strings (`equipment.*`) and check `OpenLoam.can?("equipment.edit")` / `require_permission!` — deny-by-default, a finer layer under the coarse role. |
+| 🌾 **Custom fields** | Define fields at runtime (a `custom_fields` JSON column + a `OpenLoam::FieldDefinition` row), so agents and admins extend a model without a migration for every idea. Filtering and sorting on a custom field is **index-backed** at scale via a typed read-model projection (`OpenLoam::CustomFieldIndex`), not a per-row JSON scan — with **coverage accounting** (is the index complete or drifting?), a read-time gap that **falls back to the authoritative source for correctness** and **self-heals** in the background (deduped), and an honest "results may be incomplete" signal while it does. A field can declare `readable_roles`: filtering or sorting on a field a role **may not read** is refused, so a filter can't become an **inference oracle** on a restricted value. |
 | 🔀 **Workflow** | Declared states, transitions, and role-gated approvals on any entity; each transition emits an event and is audited. |
-| 📡 **Event backbone** | A first-class domain event bus (`domain.thing.happened`, publish/subscribe) so modules stay decoupled and workflows are legible. Two subscriber tiers with a **formal contract**: *ephemeral* (`Loam::Events.subscribe`, in-process, synchronous, best-effort) for cheap fan-out, and *durable* (`Loam::DurableEvents.register`) which **persists each delivery as a row** in the event's tenant and hands it to a background job — **at-least-once with retry + backoff**, a **dead-letter** view with manual requeue, and a periodic **sweep** that redelivers a lost job (row state, not the queue, is the source of truth). A handler is resolved from a boot-time registry, never constantized from the stored row. |
+| 📡 **Event backbone** | A first-class domain event bus (`domain.thing.happened`, publish/subscribe) so modules stay decoupled and workflows are legible. Two subscriber tiers with a **formal contract**: *ephemeral* (`OpenLoam::Events.subscribe`, in-process, synchronous, best-effort) for cheap fan-out, and *durable* (`OpenLoam::DurableEvents.register`) which **persists each delivery as a row** in the event's tenant and hands it to a background job — **at-least-once with retry + backoff**, a **dead-letter** view with manual requeue, and a periodic **sweep** that redelivers a lost job (row state, not the queue, is the source of truth). A handler is resolved from a boot-time registry, never constantized from the stored row. |
 | 🔔 **Notifications** | Tenant-scoped in-app notifications, created from events, surfaced in the admin. |
 | 🔌 **API & webhooks** | Token-authenticated JSON API per entity (policy-aware) and per-tenant signed **outbound** webhooks on domain events. **Inbound** webhooks too: a public `/webhooks/:token` receiver that HMAC-verifies each call over the raw body, resists replays (a `(source, delivery-id)` idempotency ledger), answers every auth failure with a uniform `401`, and publishes the verified event onto the bus so durable subscribers react. |
 | 🧾 **Audit** | Every change — who, what, when, in which tenant — recorded by default. |
 | ↩️ **Undo / history** | The audit trail is an **undo stack**: each record's History screen reverts a change with one click, and the undo is itself recorded — so undoing an `undo` is redo. Walks back one step at a time (never clobbers a newer edit); **encrypted fields and workflow state are never reverted** here (state changes undo via the reverse transition). |
 | 🗑️ **Soft-delete** | Deleting a record hides it instead of erasing it — excluded from every query by default, still tenant-scoped in the recycle bin, restorable, and recorded in the audit trail. |
 | ⚙️ **Settings** | A key-value settings store with a global default and a per-tenant override — typed values, resolved override → global → default, cached per request, and never leaking between tenants. |
-| 🚩 **Feature flags** | Runtime on/off capabilities per tenant for rollout or kill-switch — a global default plus per-tenant override, a `Loam::Features.on?` guard, and an admin screen. Gates a **capability**, not a person — distinct from roles and policies. |
+| 🚩 **Feature flags** | Runtime on/off capabilities per tenant for rollout or kill-switch — a global default plus per-tenant override, a `OpenLoam::Features.on?` guard, and an admin screen. Gates a **capability**, not a person — distinct from roles and policies. |
 | 🔒 **Encryption at rest** | Mark a field `encrypts` and it is transparently AES-256-GCM encrypted with a **per-tenant** key (HKDF, KMS-pluggable) and decrypted on read — a DB dump leaks nothing and tenant A's key never opens tenant B's data. A keyed blind index keeps an encrypted email/phone findable by exact match; the audit trail records the change, never the value. |
 | 🔑 **MFA & step-up auth** | TOTP second factor for admin login (RFC 6238, no dependency), with single-use recovery codes; the secret is encrypted per-user so it verifies in any tenant. `require_sudo!` re-challenges for sensitive actions within a short window — orthogonal to role. MFA can be required per role. Failed password / TOTP / sudo attempts are **rate-limited and locked out** (per-identifier, configurable), so an online brute-force of a 6-digit code is throttled — and a lockout is enumeration-safe (a locked known and unknown identifier respond identically). |
 | 🚦 **AI approval gate** | An agent running under confirm-mode **stages** a write as a `PendingAction` with a before/after preview instead of committing it; a manager approves (a role-gated workflow transition) and only then does it execute — audited to the approver. The human-in-the-loop primitive for agent writes; encrypted fields never appear in the preview or audit. |
-| 🤖 **MCP server** | An [MCP](https://modelcontextprotocol.io) server (`bin/rails loam:mcp:serve`, stdio) exposes Loam to an AI agent: discover entities/schema/policy, **read** tenant-scoped records (only fields the role may see), and **propose** writes that are *staged for human approval* — never committed. Every gate is a Loam gate reused (tenancy, read-ACL, the approval gate); the agent acts as its API token's user, no more. |
+| 🤖 **MCP server** | An [MCP](https://modelcontextprotocol.io) server (`bin/rails open_loam:mcp:serve`, stdio) exposes OpenLoam to an AI agent: discover entities/schema/policy, **read** tenant-scoped records (only fields the role may see), and **propose** writes that are *staged for human approval* — never committed. Every gate is a OpenLoam gate reused (tenancy, read-ACL, the approval gate); the agent acts as its API token's user, no more. |
 | 👓 **Saved views** | A user names a view of an entity's admin index — filters, sort, columns — and keeps it private, shares it to a role, or makes it the tenant default. Filters only ever touch whitelisted data columns; a stored view is optimistic-locked so shared edits don't clobber. |
 | 🔏 **Concurrent-edit safety** | Optimistic locking (`lock_version`) turns a stale save into a clean "this changed since you opened it" conflict — with a diff and a retry, never a silent clobber — and an advisory `RecordLock` shows "Anna is editing this" with a manager take-over. The version check is the guarantee; the lock is the courtesy. |
 | 📡 **Real-time updates** | A per-tenant Server-Sent-Events stream pushes selected events to the browser — the notification bell increments live, no polling. Opt-in per event pattern (default off, tenant- and audience-filtered), behind a broadcaster seam so Redis/SolidCable drops in for multi-process. |
@@ -74,24 +74,24 @@ need to — never a blank page.
 | 🔎 **Pluggable search** | `searchable_by` and `Model.search(q)` stay put; the strategy behind them is a swappable **driver**. Ships two: a portable substring **LIKE** (default, zero-setup) and a **word-level token index** (order-independent, AND-semantics, still plain SQL — no external service), with the seam ready for Meilisearch/Elasticsearch. Swapping is a one-line initializer change, no call-site edits. Tenant-scoped, and an encrypted field's plaintext is never tokenized. |
 | 🪪 **SSO (OIDC)** | Per-tenant single sign-on: each tenant connects its own identity provider. **Home-realm discovery** routes a user to their IdP by email domain; a verified identity is **just-in-time provisioned** (or linked to an existing account), with IdP group → role mapping. The client secret is encrypted at rest (per-tenant key). An unverified email is refused — no silent account takeover. OIDC ships end-to-end; SAML and SCIM are documented seams behind a protocol interface. |
 | 📚 **Dictionaries** | Per-tenant managed lookup lists — named sets of entries (value/label/color/icon/position/default) an admin curates without a deploy. Usable as a **custom-field type**: a `dictionary` field renders a select of the list's active entries and stores the chosen value, showing its label on read. Tenant-scoped and cached per request. |
-| ⏳ **Task progress** | A long-running job (import, reindex, report) reports percent / counts / ETA to the admin, pushed **live over SSE** — no polling. `Loam::Progress.start`/`advance`/`complete!`; the browser bar moves as the job runs. The broadcast is throttled to once per whole percent, the job supports a cooperative cancel, and a stalled job (dead heartbeat) is flagged. Tenant-scoped; the frame carries only id/percent/status. |
-| 🕰️ **Scheduler** | Per-tenant recurring jobs — cron (`0 7 * * *`) or interval — that enqueue an ActiveJob on schedule. A runner (`loam:scheduler:tick`, wired to system cron) claims due jobs **atomically** (Postgres `SKIP LOCKED`; SQLite a transactional claim), so multiple workers **never double-fire** one. `job_class` is whitelisted to a real ActiveJob (no arbitrary code). Tenant-scope jobs run per tenant; system-scope once. A stdlib cron-next calculator (no gem), timezone-aware. |
+| ⏳ **Task progress** | A long-running job (import, reindex, report) reports percent / counts / ETA to the admin, pushed **live over SSE** — no polling. `OpenLoam::Progress.start`/`advance`/`complete!`; the browser bar moves as the job runs. The broadcast is throttled to once per whole percent, the job supports a cooperative cancel, and a stalled job (dead heartbeat) is flagged. Tenant-scoped; the frame carries only id/percent/status. |
+| 🕰️ **Scheduler** | Per-tenant recurring jobs — cron (`0 7 * * *`) or interval — that enqueue an ActiveJob on schedule. A runner (`open_loam:scheduler:tick`, wired to system cron) claims due jobs **atomically** (Postgres `SKIP LOCKED`; SQLite a transactional claim), so multiple workers **never double-fire** one. `job_class` is whitelisted to a real ActiveJob (no arbitrary code). Tenant-scope jobs run per tenant; system-scope once. A stdlib cron-next calculator (no gem), timezone-aware. |
 | 📥 **Bulk import / export** | CSV **export** of any entity's current filtered view — policy- and encryption-aware (an encrypted field is redacted, never a plaintext dump). CSV **import** with a column-mapping engine: dedupe by a key (update-or-create), per-row validation with a skipped-row error log and a **downloadable error file**, a **dry-run** that commits nothing, and live progress (backgrounded, reported via the task bar). The mapping only targets policy-permitted fields — no crafted column reaches `tenant_id` or a field a role can't write. Plus **datatable bulk actions** (select rows → soft-delete / set-field / export), policy-checked per record and tenant-scoped. |
 | 📊 **Configurable dashboard** | The admin home is a grid of module-provided **widgets** on a registry — a metric or short list each. A manager picks which widgets appear and in what order, per tenant; a widget's `roles:` filter is enforced server-side (a hidden widget's data is never even computed). Widgets query tenant-scoped models (no cross-tenant leak), and a raising widget is isolated into an error tile — the dashboard never breaks. Ships built-ins (recent activity, unread notifications, pending approvals, running tasks). |
-| 📜 **Auto OpenAPI** | The JSON API documents itself. `Loam::OpenApi` introspects the generated per-entity API controllers — columns/types, exposed fields, custom fields, the bearer-token security scheme, and the tenancy guarantee — into an **OpenAPI 3.1** document, with **no hand-written annotations and no external gem**. A server-rendered explorer at `/admin/api_docs` (no Swagger-UI/external JS), a `.json` endpoint for tooling, and `loam:openapi:export` for CI. Request schemas expose only writable fields (never `tenant_id`); encrypted fields are typed as plain strings — the doc describes shape, never data. |
+| 📜 **Auto OpenAPI** | The JSON API documents itself. `OpenLoam::OpenApi` introspects the generated per-entity API controllers — columns/types, exposed fields, custom fields, the bearer-token security scheme, and the tenancy guarantee — into an **OpenAPI 3.1** document, with **no hand-written annotations and no external gem**. A server-rendered explorer at `/admin/api_docs` (no Swagger-UI/external JS), a `.json` endpoint for tooling, and `open_loam:openapi:export` for CI. Request schemas expose only writable fields (never `tenant_id`); encrypted fields are typed as plain strings — the doc describes shape, never data. |
 | 🌐 **Content translations** | Translate the DATA in a record's fields per locale — a product name, a category label — distinct from Rails i18n (developer UI strings, still Rails-native). `translates :name` adds a read-time **overlay**: `record.name` returns the current locale's translation when one exists, else the record's own column (the base value, never lost). Locale is request state (a `/admin` switcher); translations are tenant-scoped, audited, additive rows. An **encrypted field can't be translated** — that would store plaintext, so it's refused at load. |
-| 🧬 **Override registry** | Disable or replace an entry in one of Loam's keyed registries — a built-in dashboard widget, a default broadcast pattern — from an initializer, **without forking or monkeypatching**: `Loam::Overrides.disable(:widgets, "open_progress")` / `.replace(:widgets, "audit_recent") { … }`. The value over a raw monkeypatch: a **stale override** (a key that no longer exists) is warned about at boot, so a typo isn't a silent no-op. Deliberately small — structural pieces (views, controllers, routes) still use standard Rails path-shadowing; this fills the gap for the in-gem registries. |
+| 🧬 **Override registry** | Disable or replace an entry in one of OpenLoam's keyed registries — a built-in dashboard widget, a default broadcast pattern — from an initializer, **without forking or monkeypatching**: `OpenLoam::Overrides.disable(:widgets, "open_progress")` / `.replace(:widgets, "audit_recent") { … }`. The value over a raw monkeypatch: a **stale override** (a key that no longer exists) is warned about at boot, so a typo isn't a silent no-op. Deliberately small — structural pieces (views, controllers, routes) still use standard Rails path-shadowing; this fills the gap for the in-gem registries. |
 | 🖥️ **Admin surface** | An internal console generated from your models — comments, attachments, global search, filtering, pagination — not a second app to maintain. |
 | 🤖 **Agent conventions** | An `AGENTS.md` (byte-budgeted), generators as the one interface, and structural guardrails so an AI agent can add a domain feature **safely** — and a human can read what it did. |
 
-You write the **20% that is your business**. Loam is the 80% that every business
+You write the **20% that is your business**. OpenLoam is the 80% that every business
 app shares.
 
 ---
 
 ## Agent-native by design
 
-Loam treats "an AI agent will extend this" as a first-class constraint:
+OpenLoam treats "an AI agent will extend this" as a first-class constraint:
 
 - **One obvious way** to add an entity, a permission, an event, a screen — so an
   agent's output is predictable and reviewable.
@@ -111,7 +111,7 @@ for an agent or a human.
 
 **Working prototype — every pillar in the table above is built, tested, and
 exercised end to end** by a demo app, a generator harness, and an agent
-benchmark. Some two dozen `Loam::` modules, from tenancy through SSO, each
+benchmark. Some two dozen `OpenLoam::` modules, from tenancy through SSO, each
 added the same way: a small in-gem implementation behind a convention, wired to
 agree with the rest.
 
@@ -119,7 +119,7 @@ agree with the rest.
 
 | Path | What it is |
 |------|-----------|
-| `lib/` | The `loam` gem — every pillar as a small `Loam::` module, plus the `loam:install` and `loam:entity` generators that are the whole interface. |
+| `lib/` | The `open_loam` gem — every pillar as a small `OpenLoam::` module, plus the `open_loam:install` and `open_loam:entity` generators that are the whole interface. |
 | `demo/` | An equipment-rental app built with those generators (454 tests / 1,534 assertions as of 2026-08-22), carrying the generated guardrail tests: tenant isolation, no-context-raises, a lint against `.unscoped` in `app/`, and a 32 KB `AGENTS.md` budget. |
 | `ai/` | The agent benchmark — `golden_tasks.md` and recorded runs. First run: **10/10 tasks, zero isolation or authorization violations**; a vanilla-Rails control under the same prompts enforced isolation in **1/10**. |
 | `docs/_agents/` | Deep-dive conventions (encryption, SSO, scheduler, …) linked from `AGENTS.md`, so the agent contract stays inside its byte budget. |
@@ -136,10 +136,12 @@ whole thesis in miniature.
 **How honest the "prototype" label is** — deliberately, each pillar is a
 *minimal in-gem implementation* rather than a wrapper around
 `acts_as_tenant`/`pundit`/`paper_trail`/Rails Event Store: the smallest surface
-that proves the conventions and the agent flow. Swapping the proven gems back in
-*behind the same `Loam::` conventions* is the roadmap, not a reversal. Custom
+that proves the conventions and the agent flow. Those swaps have since been
+evaluated one at a time and settled — the in-gem versions stay, and the one real
+gap they exposed (event capture) was closed in-gem too, in
+[ADR 0007](docs/_adr/0007-proven-gem-swaps-resolved.md). Custom
 fields use the portable Rails `json` column (not Postgres `jsonb`/GIN) because
-the demo runs on SQLite. See [How Loam works](docs/_foundation/overview.md) for
+the demo runs on SQLite. See [How OpenLoam works](docs/_foundation/overview.md) for
 the pillar-by-pillar breakdown and the decisions behind them.
 
 **Try it**
@@ -161,14 +163,14 @@ showing the real commands and exactly what you *didn't* have to write.
 - [Getting started](https://deliveristsio.github.io/open-loam/getting-started/) — hands-on, install to first feature
 - [Overview](OVERVIEW.md) — plain-language product, use cases, evidence, and risks
 - [Concept & positioning](https://deliveristsio.github.io/open-loam/concept/)
-- [How Loam works](https://deliveristsio.github.io/open-loam/foundation/overview/) — the diagrams above + how every pillar is built
+- [How OpenLoam works](https://deliveristsio.github.io/open-loam/foundation/overview/) — the diagrams above + how every pillar is built
 - [Tenant isolation](https://deliveristsio.github.io/open-loam/foundation/tenant-isolation/) & [Authorization](https://deliveristsio.github.io/open-loam/foundation/authorization/) — the two flagship guarantees, in depth
 - [Agents](https://deliveristsio.github.io/open-loam/agents/) — the agent contract, guardrails, the golden-tasks benchmark, and subsystem deep-dives (encryption, SSO, scheduler, events, inbound webhooks, bulk, confirm-mode)
 - Reference — [configuration](https://deliveristsio.github.io/open-loam/reference/configuration/), [generators](https://deliveristsio.github.io/open-loam/reference/generators/), [backward compatibility](https://deliveristsio.github.io/open-loam/reference/compatibility/)
 - [Roadmap](ROADMAP.md) — ordered backlog, Mercato-informed
 - [Backward-compatibility contract](BACKWARD_COMPATIBILITY.md) — the frozen public surfaces
 - [Architecture decisions](https://deliveristsio.github.io/open-loam/adr/) & [lessons](ai/lessons.md) — why things are the way they are, and the gotchas
-- [Agent pack](.loam/agents/) — everything an AI agent should load to extend a Loam app correctly
+- [Agent pack](.open_loam/agents/) — everything an AI agent should load to extend a OpenLoam app correctly
 - [Manifesto](https://deliveristsio.github.io/open-loam/manifesto/)
 - [Contributing](CONTRIBUTING.md)
 

data/app/jobs/{loam → open_loam}/custom_field_reindex_job.rb

@@ -1,6 +1,6 @@
-module Loam
+module OpenLoam
   # Heals a custom-field index gap in the background: rebuilds one model's
-  # read-model index (Loam::CustomFieldIndex) for one tenant. Enqueued (deduped)
+  # read-model index (OpenLoam::CustomFieldIndex) for one tenant. Enqueued (deduped)
   # by CustomFieldIndex when a filter/order runs over an incomplete index, so a
   # gap self-heals without an operator running a rake task. Inherits
   # ActiveJob::Base, not the app's ApplicationRecord-owned base (the gem must not
@@ -9,14 +9,14 @@ module Loam
     queue_as :default
 
     def perform(tenant_id, model_name)
-      tenant = Loam::Tenant.find_by(id: tenant_id)
+      tenant = OpenLoam::Tenant.find_by(id: tenant_id)
       model = model_name.to_s.safe_constantize
-      return unless tenant && model.is_a?(Class) && model < Loam::TenantRecord
+      return unless tenant && model.is_a?(Class) && model < OpenLoam::TenantRecord
 
-      Loam.as_tenant(tenant) { Loam::CustomFieldIndex.reindex(model) }
+      OpenLoam.as_tenant(tenant) { OpenLoam::CustomFieldIndex.reindex(model) }
     ensure
       # Release the dedup marker so a later real gap can enqueue again.
-      Loam::CustomFieldIndex.clear_pending(tenant_id, model_name.to_s)
+      OpenLoam::CustomFieldIndex.clear_pending(tenant_id, model_name.to_s)
     end
   end
 end

data/app/jobs/{loam → open_loam}/event_delivery_job.rb

@@ -1,25 +1,25 @@
-module Loam
-  # Runs one durable event delivery (Loam::DurableEvents). Inherits
+module OpenLoam
+  # Runs one durable event delivery (OpenLoam::DurableEvents). Inherits
   # ActiveJob::Base rather than the host app's ApplicationJob — the gem must not
   # depend on a class the app owns and may have configured for its own retries —
-  # and carries the tenant explicitly (ActiveJob doesn't serialize Loam::Current).
+  # and carries the tenant explicitly (ActiveJob doesn't serialize OpenLoam::Current).
   #
   # A missing row is an ANSWER, not an error: with an async queue adapter the job
   # can start before the creating transaction commits, so the row isn't visible
   # yet. The job no-ops; the redelivery sweep picks the row up once it commits.
-  # Retry state lives in the ROW (Loam::DurableEvents.deliver), never here.
+  # Retry state lives in the ROW (OpenLoam::DurableEvents.deliver), never here.
   class EventDeliveryJob < ActiveJob::Base
     queue_as :default
 
     def perform(tenant_id, delivery_id)
-      tenant = Loam::Tenant.find_by(id: tenant_id)
+      tenant = OpenLoam::Tenant.find_by(id: tenant_id)
       return if tenant.nil?
 
-      Loam.as_tenant(tenant) do
-        delivery = Loam::EventDelivery.find_by(id: delivery_id)
+      OpenLoam.as_tenant(tenant) do
+        delivery = OpenLoam::EventDelivery.find_by(id: delivery_id)
         return if delivery.nil? # not visible yet (txn race) or gone — the sweep covers it
 
-        Loam::DurableEvents.deliver(delivery)
+        OpenLoam::DurableEvents.deliver(delivery)
       end
     end
   end

data/app/jobs/open_loam/event_log_prune_job.rb

@@ -0,0 +1,15 @@
+module OpenLoam
+  # Enforces the event log's retention window (OpenLoam::EventLog.prune).
+  # Registered per-tenant in OpenLoam::Engine, so it runs inside one tenant and
+  # never deletes across the boundary.
+  class EventLogPruneJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(tenant_id: nil)
+      tenant = OpenLoam::Tenant.find_by(id: tenant_id)
+      return if tenant.nil?
+
+      OpenLoam.as_tenant(tenant) { OpenLoam::EventLog.prune }
+    end
+  end
+end

data/app/jobs/{loam → open_loam}/event_redelivery_sweep_job.rb

@@ -1,10 +1,10 @@
-module Loam
+module OpenLoam
   # Periodic durability sweep: re-enqueues due-but-undelivered event deliveries
   # whose accelerator job was lost (worker crash, dropped message, an async
   # adapter racing the creating transaction). This — not perform_later at publish
   # — is what makes persistent delivery durable.
   #
-  # Registered per-tenant via Loam::Scheduler (see Loam::Engine), so `sync_tenant`
+  # Registered per-tenant via OpenLoam::Scheduler (see OpenLoam::Engine), so `sync_tenant`
   # materializes a schedule row per tenant and the scheduler allowlist already
   # covers the class. Tenant-scoped: the scheduler enqueues it with tenant_id and
   # the sweep runs inside that tenant, so there is no cross-tenant scan.
@@ -12,10 +12,10 @@ module Loam
     queue_as :default
 
     def perform(tenant_id: nil)
-      tenant = Loam::Tenant.find_by(id: tenant_id)
+      tenant = OpenLoam::Tenant.find_by(id: tenant_id)
       return if tenant.nil?
 
-      Loam.as_tenant(tenant) { Loam::DurableEvents.redeliver_stuck }
+      OpenLoam.as_tenant(tenant) { OpenLoam::DurableEvents.redeliver_stuck }
     end
   end
 end

data/app/jobs/{loam → open_loam}/webhook_delivery_job.rb

@@ -1,18 +1,22 @@
 require "net/http"
 require "openssl"
 
-module Loam
+module OpenLoam
   # Delivers one event to one endpoint. Inherits ActiveJob::Base rather than
   # the host app's ApplicationJob: the gem must not depend on a class the app
   # owns and may have configured for its own retries.
   #
   # Signing: the receiver recomputes HMAC-SHA256 of the exact body with the
-  # endpoint's secret and compares it to X-Loam-Signature. Body building and
+  # endpoint's secret and compares it to X-OpenLoam-Signature. Body building and
   # signing are class methods so both sides — and the tests — can call them
   # without a network.
   class WebhookDeliveryJob < ActiveJob::Base
     queue_as :default
 
+    # A URL that points inside the perimeter will never become deliverable by
+    # retrying, and retrying is itself the SSRF attempt repeated.
+    discard_on OpenLoam::OutboundUrl::BlockedError
+
     TIMEOUT_SECONDS = 5
 
     def self.body_for(event_name, payload, tenant_id)
@@ -24,11 +28,11 @@ module Loam
     end
 
     def perform(tenant_id, endpoint_id, event_name, payload)
-      tenant = Loam::Tenant.find_by(id: tenant_id)
+      tenant = OpenLoam::Tenant.find_by(id: tenant_id)
       return if tenant.nil?
 
-      Loam.as_tenant(tenant) do
-        endpoint = Loam::WebhookEndpoint.find_by(id: endpoint_id)
+      OpenLoam.as_tenant(tenant) do
+        endpoint = OpenLoam::WebhookEndpoint.find_by(id: endpoint_id)
         # The endpoint may have been deleted or switched off between enqueue
         # and delivery — that is an answer, not an error.
         next if endpoint.nil? || !endpoint.active?
@@ -40,17 +44,22 @@ module Loam
     private
 
     def deliver(endpoint, body, event_name)
-      uri = URI.parse(endpoint.url)
+      # Re-checked at delivery, not just at save: the URL was validated when the
+      # tenant entered it, but DNS can be repointed at an internal address any
+      # time afterwards. Connecting to the address we just checked closes the
+      # window between the check and the connection.
+      uri, address = OpenLoam::OutboundUrl.resolve!(endpoint.url)
 
       http = Net::HTTP.new(uri.host, uri.port)
+      http.ipaddr = address
       http.use_ssl = uri.scheme == "https"
       http.open_timeout = TIMEOUT_SECONDS
       http.read_timeout = TIMEOUT_SECONDS
 
       request = Net::HTTP::Post.new(uri.request_uri)
       request["Content-Type"] = "application/json"
-      request["X-Loam-Event"] = event_name
-      request["X-Loam-Signature"] = self.class.signature(endpoint.secret, body)
+      request["X-OpenLoam-Event"] = event_name
+      request["X-OpenLoam-Signature"] = self.class.signature(endpoint.secret, body)
       request.body = body
 
       http.request(request)

data/app/models/open_loam/api_token.rb

@@ -0,0 +1,63 @@
+require "openssl"
+
+module OpenLoam
+  # A bearer token that lets a machine act as one user in one tenant. Same
+  # rules as a human session: whatever the token's user may do in that tenant,
+  # no more. Plumbing, so not audited and not evented.
+  #
+  # Only the SHA-256 digest is stored. The plaintext is returned once, from the
+  # instance that generated it, and is unrecoverable afterwards — a dump of this
+  # table is not a set of working credentials. A 24-byte random token needs no
+  # slow KDF; it is not guessable the way a password is.
+  class ApiToken < OpenLoam::TenantRecord
+    self.table_name = "open_loam_api_tokens"
+
+    belongs_to :user
+
+    validates :token_digest, presence: true, uniqueness: true
+
+    # Present only on the instance that just created it — never after a reload.
+    attr_reader :token
+
+    before_validation on: :create do
+      @token ||= SecureRandom.hex(24)
+      self.token_digest = self.class.digest(@token)
+    end
+
+    def self.digest(raw_token)
+      OpenSSL::Digest::SHA256.hexdigest(raw_token.to_s)
+    end
+
+    # THE blessed cross-tenant lookup, and the reason it lives in the gem.
+    #
+    # A bearer token arrives with no tenant context — the token IS how the
+    # request discovers which tenant it belongs to, so this one query must
+    # bypass the tenant scope. That is exactly what host apps are forbidden to
+    # do (`test/open_loam_guardrails_test.rb` fails the build on it), so the escape
+    # hatch is vetted framework code here, used once, at the edge: find the
+    # token, establish OpenLoam::Current, and everything downstream is ordinary
+    # tenant-scoped code again.
+    #
+    # Returns the token, or nil for an unknown/blank one — callers render 401.
+    def self.authenticate(raw_token)
+      return nil if raw_token.blank?
+
+      api_token = unscoped.find_by(token_digest: digest(raw_token))
+      return nil unless api_token
+
+      OpenLoam::Current.tenant = api_token.tenant
+      OpenLoam::Current.actor = api_token.user
+
+      # A token outlives the membership that justified it, so offboarding a user
+      # from a tenant would otherwise leave their machine access intact. Checked
+      # here rather than at revoke time: the membership is the authority.
+      unless OpenLoam::Membership.exists?(user_id: api_token.user_id)
+        OpenLoam::Current.reset
+        return nil
+      end
+
+      api_token.update_column(:last_used_at, Time.current)
+      api_token
+    end
+  end
+end