@wtfalch/foundry 0.6.0 → 0.8.0

package/dist/migrations/0025_audit_display.sql

@@ -0,0 +1,147 @@
+-- Copied verbatim from @wtfalch/audit 0.6.0's own migrations/ (#232), the
+-- same way that package's own audit-migrations CLI copies them into a host's
+-- drizzle/ directory -- foundry has no drizzle/ journal, so this file is
+-- that copy, hand-placed at the next free number instead. Never edit the
+-- copied SQL below; a fix ships as a new numbered file, same as upstream.
+--
+-- @wtfalch/audit 0.4.0: what the target and the tenant were CALLED.
+--
+-- Mirrors src/tables.ts. Every statement is idempotent. Applied by the host's
+-- own migrate script after the host copies this file into its drizzle/
+-- directory as the next number (audit-migrations); never edited there.
+--
+-- WHY THE NAME LIVES ON THE ROW
+-- -----------------------------
+-- A reader of the trail wants to know what happened to WHAT. Looking the name
+-- up when the page renders answers that exactly until it matters: the file was
+-- deleted, the organisation was closed, the key was revoked -- and those are
+-- the rows a trail exists for. So the name is written with the row and never
+-- read from anywhere else afterwards.
+--
+-- Both columns are nullable and stay nullable: every row written before this
+-- migration has no name, and a writer that holds only an id is not made to
+-- invent one. A reader shows the id when the name is null.
+--
+-- These are NOT a rename of target_id or tenant_id. The ids stay the identity;
+-- the names are what they were called at the time, and a later rename does not
+-- reach back.
+--
+-- ERASURE
+-- -------
+-- A target can be a person: an invitation's invitee, a membership's holder.
+-- Its name is then personal data sitting in a row that outlives the account,
+-- so audit_erase_person pseudonymises target_display exactly as it already
+-- pseudonymises actor_display: on the rows it already erases, and only where
+-- target_id is the subject. Which rows those are is unchanged on purpose. A
+-- row whose target is a person is expected to carry subject_id, which is what
+-- the match already looks at; a row that sets neither subject_id nor an email
+-- in its payload was already outside erasure's reach before this file, and
+-- widening the match here would erase rows 0001 deliberately did not.
+-- tenant_display names an organisation, not a person, and is left alone; it is
+-- therefore added to the guard's immutable list, so nothing can edit it after
+-- the fact the way a correction would.
+
+alter table audit_events add column if not exists target_display text;
+alter table audit_events add column if not exists tenant_display text;
+
+do $$ begin
+  alter table audit_events
+    add constraint audit_events_target_display_check
+    check (target_display is null or length(target_display) between 1 and 256);
+exception when duplicate_object then null; end $$;
+
+do $$ begin
+  alter table audit_events
+    add constraint audit_events_tenant_display_check
+    check (tenant_display is null or length(tenant_display) between 1 and 256);
+exception when duplicate_object then null; end $$;
+
+-- 0001's guard, with tenant_display added to the columns an update may not
+-- change. target_display is absent from the list for the same reason
+-- actor_display is: erasure rewrites it.
+create or replace function audit_events_guard() returns trigger
+language plpgsql as $$
+begin
+  if tg_op = 'DELETE' then
+    raise exception 'audit_events is append-only: delete refused';
+  elsif tg_op = 'TRUNCATE' then
+    raise exception 'audit_events is append-only: truncate refused';
+  elsif tg_op = 'UPDATE' then
+    if new.id is distinct from old.id
+      or new.occurred_at is distinct from old.occurred_at
+      or new.tenant_id is distinct from old.tenant_id
+      or new.tenant_display is distinct from old.tenant_display
+      or new.actor_class is distinct from old.actor_class
+      or new.actor_id is distinct from old.actor_id
+      or new.action is distinct from old.action
+      or new.target_type is distinct from old.target_type
+      or new.target_id is distinct from old.target_id
+      or new.outcome is distinct from old.outcome
+      or new.context is distinct from old.context
+      or new.session_id is distinct from old.session_id
+      or new.reason is distinct from old.reason
+      or new.reference is distinct from old.reference
+      or new.request_id is distinct from old.request_id
+      or new.ip is distinct from old.ip
+      or new.user_agent is distinct from old.user_agent
+      or new.tenant_visible is distinct from old.tenant_visible
+      or new.schema_version is distinct from old.schema_version
+      or new.subject_class is distinct from old.subject_class
+      or new.subject_id is distinct from old.subject_id
+    then
+      raise exception 'audit_events is append-only: only actor_display, target_display, before, after and erased_at may change';
+    end if;
+  end if;
+  return new;
+end
+$$;
+
+-- 0001's erasure function, extended to the target's name. Everything else is
+-- unchanged: same subject match, same pseudonym bounds, same return.
+create or replace function audit_erase_person(subject text, pseudonym text, subject_email text)
+returns integer
+language plpgsql
+security definer
+set search_path from current
+as $$
+declare
+  touched integer;
+begin
+  if subject is null or length(subject) = 0 then
+    raise exception 'audit_erase_person: a subject id is required';
+  end if;
+  if pseudonym is null or length(pseudonym) = 0 or length(pseudonym) > 256 then
+    raise exception 'audit_erase_person: a pseudonym of 1 to 256 characters is required';
+  end if;
+  update audit_events
+     set actor_display = case when actor_id = subject then pseudonym else actor_display end,
+         target_display = case when target_id = subject then pseudonym else target_display end,
+         before = case when before is null then null else '{"erased":true}'::jsonb end,
+         after = case when after is null then null else '{"erased":true}'::jsonb end,
+         erased_at = now()
+   where erased_at is null
+     and (
+       actor_id = subject
+       or subject_id = subject
+       or (
+         subject_email is not null
+         and (before::text like '%' || subject_email || '%' or after::text like '%' || subject_email || '%')
+       )
+     );
+  get diagnostics touched = row_count;
+  return touched;
+end
+$$;
+
+revoke all on function audit_erase_person(text, text, text) from public;
+
+do $$
+declare
+  rt text := current_database() || '_rt';
+begin
+  if exists (select 1 from pg_roles where rolname = rt) then
+    execute format('revoke update, delete, truncate on audit_events from %I', rt);
+    execute format('grant execute on function audit_erase_person(text, text, text) to %I', rt);
+  end if;
+end
+$$;

package/dist/migrations/0026_audit_erase_email_guard.sql

@@ -0,0 +1,78 @@
+-- Copied verbatim from @wtfalch/audit 0.6.0's own migrations/ (#232), the
+-- same way that package's own audit-migrations CLI copies them into a host's
+-- drizzle/ directory -- foundry has no drizzle/ journal, so this file is
+-- that copy, hand-placed at the next free number instead. Never edit the
+-- copied SQL below; a fix ships as a new numbered file, same as upstream.
+--
+-- @wtfalch/audit: restore audit_erase_person's empty-email guard.
+--
+-- Mirrors src/ledger.ts's erase(). Every statement is idempotent. Applied by
+-- the host's own migrate script after the host copies this file into its
+-- drizzle/ directory as the next number (audit-migrations); never edited
+-- there.
+--
+-- REGRESSION
+-- ----------
+-- 0002_display.sql's audit_erase_person dropped two things 0001_audit.sql
+-- had: the `length(subject_email) > 0` guard and the lower() case-fold on
+-- both the column and the match value. Without the length guard, an empty
+-- string reaches the SQL LIKE match as `like '%%'`, which matches every
+-- row's before/after text -- on every tenant, not just the subject's. This
+-- file cannot edit 0002 (shipped migrations don't change); it re-defines
+-- the function, which `create or replace` makes safe to apply on top.
+--
+-- Everything else about the function is unchanged from 0002: same subject
+-- and subject_id match, same pseudonym bounds, same target_display and
+-- actor_display pseudonymisation, same return.
+
+create or replace function audit_erase_person(subject text, pseudonym text, subject_email text)
+returns integer
+language plpgsql
+security definer
+set search_path from current
+as $$
+declare
+  touched integer;
+begin
+  if subject is null or length(subject) = 0 then
+    raise exception 'audit_erase_person: a subject id is required';
+  end if;
+  if pseudonym is null or length(pseudonym) = 0 or length(pseudonym) > 256 then
+    raise exception 'audit_erase_person: a pseudonym of 1 to 256 characters is required';
+  end if;
+  update audit_events
+     set actor_display = case when actor_id = subject then pseudonym else actor_display end,
+         target_display = case when target_id = subject then pseudonym else target_display end,
+         before = case when before is null then null else '{"erased":true}'::jsonb end,
+         after = case when after is null then null else '{"erased":true}'::jsonb end,
+         erased_at = now()
+   where erased_at is null
+     and (
+       actor_id = subject
+       or subject_id = subject
+       or (
+         subject_email is not null
+         and length(subject_email) > 0
+         and (
+           lower(coalesce(before::text, '')) like '%' || lower(subject_email) || '%'
+           or lower(coalesce(after::text, '')) like '%' || lower(subject_email) || '%'
+         )
+       )
+     );
+  get diagnostics touched = row_count;
+  return touched;
+end
+$$;
+
+revoke all on function audit_erase_person(text, text, text) from public;
+
+do $$
+declare
+  rt text := current_database() || '_rt';
+begin
+  if exists (select 1 from pg_roles where rolname = rt) then
+    execute format('revoke update, delete, truncate on audit_events from %I', rt);
+    execute format('grant execute on function audit_erase_person(text, text, text) to %I', rt);
+  end if;
+end
+$$;

package/dist/migrations/0027_audit_chain.sql

@@ -0,0 +1,170 @@
+-- Copied verbatim from @wtfalch/audit 0.6.0's own migrations/ (#232), the
+-- same way that package's own audit-migrations CLI copies them into a host's
+-- drizzle/ directory -- foundry has no drizzle/ journal, so this file is
+-- that copy, hand-placed at the next free number instead. Never edit the
+-- copied SQL below; a fix ships as a new numbered file, same as upstream.
+--
+-- @wtfalch/audit: hash chaining, opt in.
+--
+-- Mirrors src/chain.ts and src/tables.ts. Every statement is idempotent.
+-- Applied by the host's own migrate script after the host copies this file
+-- into its drizzle/ directory as the next number (audit-migrations); never
+-- edited there.
+--
+-- Nothing here forces chaining. Five nullable columns, computed and
+-- verified entirely in TypeScript (src/chain.ts), the same design
+-- `@wtfalch/authz`'s audit-chain.ts already shipped: no pgcrypto, no
+-- trigger, because PGlite -- this package's own default test database --
+-- has no pgcrypto, and a trigger cannot see the previous row's hash without
+-- a race between concurrent inserts that only a lock (below) closes.
+--
+--   prev_hash     -- the previous row's row_hash, in whatever order rows
+--                     were sealed at write time. null for the chain's first
+--                     row, and forever on a row nothing ever sealed.
+--   row_hash      -- sha256 over this row's own fields (chain.ts's
+--                     ROW_HASH_KEYS) plus prev_hash and content_hash. Never
+--                     changes once set; the append-only guard below still
+--                     refuses to.
+--   content_hash  -- sha256 over the row's erasable content (actor_display,
+--                     target_display, before, after), salted.
+--   content_salt  -- the salt content_hash was taken over. Set at seal
+--                     time, nulled by erasure: once it is gone nobody --
+--                     including this package -- can reproduce content_hash
+--                     from a guessed payload, which is what erasure means
+--                     here. Unlike row_hash, an erasure IS allowed to null
+--                     this, so the guard's allowed list grows to include it.
+--   erasure_hash  -- set only once content_salt is nulled: sha256 over
+--                     { row_hash, erased_at }, so the fact and the instant
+--                     of erasure stay checkable forever even though the
+--                     erased content no longer is.
+--
+-- A row written before this migration applies has row_hash null forever --
+-- nothing recorded its hash at write time, so computing one now would only
+-- hash what the row happens to contain today, proving nothing about
+-- whether it changed since. verifyChain reports it 'unsealed', not
+-- verified, the same stance 0002's target_display took on the rows before
+-- it and worker_log_chain took on the rows before T255.
+--
+-- audit_seal_erasure(row_id, erasure_hash_value): the runtime role has no
+-- UPDATE on audit_events at all (0001's revoke), so ledger.erase()'s
+-- pending-erasure sweep -- setting content_salt to null and erasure_hash
+-- once a chain-sealed row has been erased -- needs its own security
+-- definer door back in, the same shape as audit_erase_person's.
+
+alter table audit_events add column if not exists prev_hash text;
+alter table audit_events add column if not exists row_hash text;
+alter table audit_events add column if not exists content_hash text;
+alter table audit_events add column if not exists content_salt text;
+alter table audit_events add column if not exists erasure_hash text;
+
+do $$ begin
+  alter table audit_events
+    add constraint audit_events_prev_hash_check
+    check (prev_hash is null or prev_hash ~ '^[0-9a-f]{64}$');
+exception when duplicate_object then null; end $$;
+
+do $$ begin
+  alter table audit_events
+    add constraint audit_events_row_hash_check
+    check (row_hash is null or row_hash ~ '^[0-9a-f]{64}$');
+exception when duplicate_object then null; end $$;
+
+do $$ begin
+  alter table audit_events
+    add constraint audit_events_content_hash_check
+    check (content_hash is null or content_hash ~ '^[0-9a-f]{64}$');
+exception when duplicate_object then null; end $$;
+
+do $$ begin
+  alter table audit_events
+    add constraint audit_events_erasure_hash_check
+    check (erasure_hash is null or erasure_hash ~ '^[0-9a-f]{64}$');
+exception when duplicate_object then null; end $$;
+
+-- A chain-sealed row not yet erased, so ledger.erase()'s pending-erasure
+-- sweep finds it in an index scan rather than a table scan. Empty on a
+-- host that never turns chaining on.
+create index if not exists audit_events_chain_pending_idx
+  on audit_events (id)
+  where row_hash is not null and erased_at is not null and erasure_hash is null;
+
+-- 0002's guard, with content_salt and erasure_hash added to the columns an
+-- update may change: erasure nulls the first and sets the second, on a row
+-- that was already erased by the same audit_erase_person call this
+-- migration does not touch. prev_hash, row_hash and content_hash are
+-- absent from the list on purpose -- once set, never.
+create or replace function audit_events_guard() returns trigger
+language plpgsql as $$
+begin
+  if tg_op = 'DELETE' then
+    raise exception 'audit_events is append-only: delete refused';
+  elsif tg_op = 'TRUNCATE' then
+    raise exception 'audit_events is append-only: truncate refused';
+  elsif tg_op = 'UPDATE' then
+    if new.id is distinct from old.id
+      or new.occurred_at is distinct from old.occurred_at
+      or new.tenant_id is distinct from old.tenant_id
+      or new.tenant_display is distinct from old.tenant_display
+      or new.actor_class is distinct from old.actor_class
+      or new.actor_id is distinct from old.actor_id
+      or new.action is distinct from old.action
+      or new.target_type is distinct from old.target_type
+      or new.target_id is distinct from old.target_id
+      or new.outcome is distinct from old.outcome
+      or new.context is distinct from old.context
+      or new.session_id is distinct from old.session_id
+      or new.reason is distinct from old.reason
+      or new.reference is distinct from old.reference
+      or new.request_id is distinct from old.request_id
+      or new.ip is distinct from old.ip
+      or new.user_agent is distinct from old.user_agent
+      or new.tenant_visible is distinct from old.tenant_visible
+      or new.schema_version is distinct from old.schema_version
+      or new.subject_class is distinct from old.subject_class
+      or new.subject_id is distinct from old.subject_id
+      or new.prev_hash is distinct from old.prev_hash
+      or new.row_hash is distinct from old.row_hash
+      or new.content_hash is distinct from old.content_hash
+    then
+      raise exception 'audit_events is append-only: only actor_display, target_display, before, after, erased_at, content_salt and erasure_hash may change';
+    end if;
+  end if;
+  return new;
+end
+$$;
+
+-- 0001's revoke took update off the runtime role entirely, on purpose:
+-- audit_erase_person (security definer) is the one door back in. This is
+-- the second one, for exactly one thing: chain-sealing a row
+-- audit_erase_person already erased. It never computes a hash itself --
+-- the caller does, in TypeScript (chain.ts's computeErasureHash), the same
+-- design choice audit_erase_person's own absence of a hash column made
+-- before this file existed -- it only writes the value it is given, and
+-- only onto a row that is erased, chain-sealed, and not already sealed.
+create or replace function audit_seal_erasure(row_id bigint, erasure_hash_value text)
+returns void
+language plpgsql
+security definer
+set search_path from current
+as $$
+begin
+  update audit_events
+     set content_salt = null,
+         erasure_hash = erasure_hash_value
+   where id = row_id
+     and row_hash is not null
+     and erased_at is not null
+     and erasure_hash is null;
+end
+$$;
+revoke all on function audit_seal_erasure(bigint, text) from public;
+
+do $$
+declare
+  rt text := current_database() || '_rt';
+begin
+  if exists (select 1 from pg_roles where rolname = rt) then
+    execute format('grant execute on function audit_seal_erasure(bigint, text) to %I', rt);
+  end if;
+end
+$$;

package/dist/migrations/0028_audit_rls.sql

@@ -0,0 +1,111 @@
+-- Copied verbatim from @wtfalch/audit 0.6.0's own migrations/ (#232), the
+-- same way that package's own audit-migrations CLI copies them into a host's
+-- drizzle/ directory -- foundry has no drizzle/ journal, so this file is
+-- that copy, hand-placed at the next free number instead. Never edit the
+-- copied SQL below; a fix ships as a new numbered file, same as upstream.
+--
+-- @wtfalch/audit: row-level security on audit_events.
+--
+-- Mirrors src/ledger.ts (scopeAuditTenant). Every statement is idempotent.
+-- Applied by the host's own migrate script after the host copies this file
+-- into its drizzle/ directory as the next number (audit-migrations); never
+-- edited there.
+--
+-- Until this file, tenant isolation was only the `tenantId` a caller
+-- remembered to pass to ledger.page(). One missed predicate showed a
+-- customer another company's trail. With RLS on, the database holds the
+-- line for every role that is not the table's owner -- the runtime role
+-- <database>_rt, and any read-only role a host adds:
+--
+--   audit.tenant_id       -- set per transaction by the host
+--                            (scopeAuditTenant, or
+--                            set_config('audit.tenant_id', $1, true)).
+--                            While set, a SELECT sees that tenant's rows and
+--                            nothing else -- not another tenant's, and not
+--                            the estate's own tenant_id-null rows.
+--   audit.require_tenant  -- 'on' makes an unscoped SELECT see nothing
+--                            instead of everything. Set it on a role, once:
+--                              alter role <database>_rt set audit.require_tenant = 'on';
+--                            That is the setting that survives a forgotten
+--                            scope. It is not set here because an operator
+--                            surface reads across tenants on purpose, and
+--                            which role does that is the host's decision.
+--
+-- Unset and not required, a SELECT sees every row, exactly as before this
+-- file: applying it changes nothing for a host until the host scopes.
+--
+-- INSERT is not restricted: a request scoped to one tenant may still record
+-- an estate-level (tenant_id null) event, and the ledger's own vocabulary
+-- checks already decide what may be written. UPDATE and DELETE have no
+-- policy, so they stay refused for the runtime role -- which 0001's revoke
+-- already did.
+--
+-- Not FORCE: the owner, and the security definer functions it owns
+-- (audit_erase_person, audit_seal_erasure, and the two below), bypass RLS.
+-- Erasure is by subject, across tenants, by design.
+
+alter table audit_events enable row level security;
+
+drop policy if exists audit_events_read on audit_events;
+create policy audit_events_read on audit_events
+  for select
+  using (
+    case
+      when coalesce(current_setting('audit.tenant_id', true), '') <> ''
+        then tenant_id is not null
+         and tenant_id = current_setting('audit.tenant_id', true)::uuid
+      when coalesce(current_setting('audit.require_tenant', true), '') = 'on'
+        then false
+      else true
+    end
+  );
+
+drop policy if exists audit_events_append on audit_events;
+create policy audit_events_append on audit_events
+  for insert
+  with check (true);
+
+-- The hash chain is one chain across every tenant. Under a tenant scope the
+-- runtime role can no longer see the true tail, so ledger.sign() with
+-- hashChain on would chain onto that tenant's last row and fork the chain.
+-- This reads the tail as the owner. It returns a hash, never content.
+create or replace function audit_chain_tail()
+returns text
+language sql
+stable
+security definer
+set search_path from current
+as $$
+  select row_hash from audit_events order by id desc limit 1
+$$;
+revoke all on function audit_chain_tail() from public;
+
+-- The same for ledger.erase()'s pending-erasure sweep, which must find
+-- every tenant's pending rows, scoped or not. Ids, hashes and erasure
+-- instants only.
+create or replace function audit_pending_erasures()
+returns table (id bigint, row_hash text, erased_at timestamptz)
+language sql
+stable
+security definer
+set search_path from current
+as $$
+  select e.id, e.row_hash, e.erased_at
+    from audit_events e
+   where e.row_hash is not null
+     and e.erased_at is not null
+     and e.erasure_hash is null
+   order by e.id
+$$;
+revoke all on function audit_pending_erasures() from public;
+
+do $$
+declare
+  rt text := current_database() || '_rt';
+begin
+  if exists (select 1 from pg_roles where rolname = rt) then
+    execute format('grant execute on function audit_chain_tail() to %I', rt);
+    execute format('grant execute on function audit_pending_erasures() to %I', rt);
+  end if;
+end
+$$;

package/dist/migrations-dir.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Absolute path of the directory holding this package's numbered `.sql`
+ * migrations. The host passes it to `runMigrationSources` as
+ * `{ name: 'foundry', dir: migrationsDir }`.
+ *
+ * Its own subpath (`@wtfalch/foundry/migrations-dir`) and no other imports: a
+ * migration image imports this without the rest of the package.
+ */
+export declare const migrationsDir: string;

package/dist/migrations-dir.js

@@ -0,0 +1,10 @@
+import { fileURLToPath } from 'node:url';
+/**
+ * Absolute path of the directory holding this package's numbered `.sql`
+ * migrations. The host passes it to `runMigrationSources` as
+ * `{ name: 'foundry', dir: migrationsDir }`.
+ *
+ * Its own subpath (`@wtfalch/foundry/migrations-dir`) and no other imports: a
+ * migration image imports this without the rest of the package.
+ */
+export const migrationsDir = fileURLToPath(new URL('./migrations/', import.meta.url));

package/dist/org.d.ts

@@ -99,6 +99,12 @@ export declare const DEFAULT_NO_REPLY_LOCAL_PART = "no-reply";
  * Never fired by `domain` alone (#7 amendment 1).
  */
 export interface ChatConfig {
+    /**
+     * Chat is not in v1 (decided 2026-10-01): off by default for every org.
+     * While off, `apply` plans no chat step and leaves a live chat resource
+     * alone, listed in `unmanaged`; Agora hides all chat and call UI.
+     */
+    enabled: boolean;
     usesDomain: boolean;
 }
 /**
@@ -214,7 +220,25 @@ export interface HostingConfig {
      * means no Access gate. Requires `enabled`.
      */
     accessEmails: string[];
+    /**
+     * Maps the app's own env var name to one of `AppEnvSource`'s values --
+     * each a value the plan already mints for this org (Files, AI, mail) but
+     * never used to push an app's own env (#243). Each bespoke app names these
+     * differently (lokessmie uses `STORAGE_*`/`AI_*`); this is how an org
+     * declares its own app's names for them. `{}` means the app names none of
+     * them, so `pushAppEnv` pushes nothing from this map.
+     */
+    appEnv: Record<string, AppEnvSource>;
 }
+/**
+ * The closed set of values the plan already mints that `HostingConfig.appEnv`
+ * may map an app's env var name to (#243): the org's own Files organisation
+ * id, its AI organisation id, and the mail domain its Lettermint project
+ * sends from. Each is read from `StepExecutionContext.recordedIds()` in
+ * `executor.ts`'s `pushAppEnv`, never minted again there.
+ */
+export type AppEnvSource = 'filesOrganisationId' | 'aiOrganisationId' | 'mailDomain';
+export declare const APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
 /**
  * `null` when `hosting` is valid; otherwise the reason it is not (#71), same
  * shape as `validateBuyerIdentity` below.

package/dist/org.js

@@ -2,6 +2,11 @@
 export const DEFAULT_MAIL_APPS = ['agora', 'webmail'];
 /** {@link MailConfig.noReplyLocalPart}'s own default, restated wherever it is read rather than imported (this file's `LOG_DIR`-style convention, named in `plan/executor.ts`'s own doc comments). */
 export const DEFAULT_NO_REPLY_LOCAL_PART = 'no-reply';
+export const APP_ENV_SOURCES = new Set([
+    'filesOrganisationId',
+    'aiOrganisationId',
+    'mailDomain',
+]);
 const ISSUER_APP_KINDS = new Set(['web', 'native', 'api']);
 const HOSTING_BUILD_PACKS = new Set([
     'dockerfile',
@@ -62,6 +67,14 @@ export function validateHosting(hosting) {
             return `issuerApps '${app.name}' is reserved for the always-on Agora client every org gets`;
         }
     }
+    for (const [envName, source] of Object.entries(hosting.appEnv)) {
+        if (!envName) {
+            return 'every appEnv key needs a non-empty env var name';
+        }
+        if (!APP_ENV_SOURCES.has(source)) {
+            return `appEnv '${envName}' has an unknown source '${source}'`;
+        }
+    }
     return null;
 }
 /**

package/dist/plan/agora.d.ts

@@ -13,6 +13,27 @@ import type { DeclaredOrg, OrgId } from '../org.js';
  */
 export declare const ZITADEL_ORG_SCOPE_KEY = "zitadel_org";
 export declare const AGORA_CLIENT_ID_SCOPE_KEY = "agora_client_id";
+/**
+ * The recorded OIDC app's `clientId` (level-1 app-env campaign, gap P2) —
+ * not a `system:kind:key` resource id (that slot already holds the app's
+ * `appId`, `zitadelApp`'s own `resourceId`) and not a secret (`deliverSecret`
+ * is for that), so a flat scope id like `zitadel_org`/`zitadel_project`
+ * above. A level-1 org declares exactly one web `issuerApps` entry for its
+ * one standard app, so one flat key is enough; an org with more than one web
+ * app would need a richer key, not built here (Finding, this campaign's
+ * report).
+ */
+export declare const APP_CLIENT_ID_SCOPE_KEY = "zitadel_app_client_id";
+/**
+ * #139: the `cms` app's own ZITADEL web client's `clientId`, recorded
+ * separately from {@link APP_CLIENT_ID_SCOPE_KEY} -- that key belongs to the
+ * org's own hosted app (`diff.ts`'s `planIssuerApps`), a different
+ * `zitadel:app` step from the fixed `cms` client `diff.ts`'s `planCmsClient`
+ * plans. `cmsSite` reads this key to push `AUTH_CLIENT_ID` onto the cms app,
+ * the same way `pushAppEnv` reads `APP_CLIENT_ID_SCOPE_KEY` for the hosted
+ * app.
+ */
+export declare const CMS_CLIENT_ID_SCOPE_KEY = "cms_client_id";
 /**
  * The accent every org's Agora wears until orgs choose their own: the house
  * theme's `--accent` (`@wtfalch/house`, `HOUSE_THEMES['good-company']` in

package/dist/plan/agora.js

@@ -12,6 +12,27 @@
  */
 export const ZITADEL_ORG_SCOPE_KEY = 'zitadel_org';
 export const AGORA_CLIENT_ID_SCOPE_KEY = 'agora_client_id';
+/**
+ * The recorded OIDC app's `clientId` (level-1 app-env campaign, gap P2) —
+ * not a `system:kind:key` resource id (that slot already holds the app's
+ * `appId`, `zitadelApp`'s own `resourceId`) and not a secret (`deliverSecret`
+ * is for that), so a flat scope id like `zitadel_org`/`zitadel_project`
+ * above. A level-1 org declares exactly one web `issuerApps` entry for its
+ * one standard app, so one flat key is enough; an org with more than one web
+ * app would need a richer key, not built here (Finding, this campaign's
+ * report).
+ */
+export const APP_CLIENT_ID_SCOPE_KEY = 'zitadel_app_client_id';
+/**
+ * #139: the `cms` app's own ZITADEL web client's `clientId`, recorded
+ * separately from {@link APP_CLIENT_ID_SCOPE_KEY} -- that key belongs to the
+ * org's own hosted app (`diff.ts`'s `planIssuerApps`), a different
+ * `zitadel:app` step from the fixed `cms` client `diff.ts`'s `planCmsClient`
+ * plans. `cmsSite` reads this key to push `AUTH_CLIENT_ID` onto the cms app,
+ * the same way `pushAppEnv` reads `APP_CLIENT_ID_SCOPE_KEY` for the hosted
+ * app.
+ */
+export const CMS_CLIENT_ID_SCOPE_KEY = 'cms_client_id';
 /**
  * The accent every org's Agora wears until orgs choose their own: the house
  * theme's `--accent` (`@wtfalch/house`, `HOUSE_THEMES['good-company']` in
@@ -85,6 +106,8 @@ export function desiredAgoraEnv(org, recorded, host) {
             organisationId: zitadelOrgId,
             mailProjectId: host.mailProjectId,
             messagingProjectId: host.messagingProjectId,
+            // Chat is not in v1: Agora hides all chat UI unless this is true.
+            chat: { enabled: org.chat.enabled },
         });
     }
     if (org.mail.mode !== 'off' && host.mailUpstream) {

package/dist/plan/calls-matrix.d.ts

@@ -45,8 +45,10 @@
  * (`executor.ts`'s `callsHostnameFor`).
  */
 export declare const SYNAPSE_IMAGE = "ghcr.io/element-hq/synapse";
-export declare const SYNAPSE_TAG = "v1.161.0";
-export declare const MAS_IMAGE = "ghcr.io/element-hq/matrix-authentication-service:1.24.0";
+export declare const SYNAPSE_TAG: string;
+export declare const MAS_IMAGE: string;
+/** #251: the version baked into {@link MAS_IMAGE}'s `FROM` line, named on its own so a version-change line can read it without re-parsing the image string. */
+export declare const MAS_TAG: string;
 /**
  * Never resolved by DNS and never federates (`callsSynapseHomeserverYaml`'s
  * `federation_domain_whitelist: []`) -- purely a logical identifier MAS and