@wtfalch/foundry 0.43.0 → 0.44.1

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, EntryGate, EntryVolume, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, EnvHeldSecret, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceSchema, ServicesConfig, SignInConfig, VersionPin, VersionPinPart, } from './org.js';
-export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateSignIn, validateVersionPin, validateSite, } from './org.js';
+export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, WorkerAppConfig, EntryGate, EntryVolume, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, EnvHeldSecret, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceSchema, ServicesConfig, SignInConfig, VersionPin, VersionPinPart, } from './org.js';
+export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateCustomers, validateSignIn, validateVersionPin, validateSite, } from './org.js';
 export type { DeclaredPlatform, PlatformService, PlatformServiceKey, PlatformSfuService, HeartbeatsProvider, } from './platform.js';
 export { PLATFORM_SERVICE_KEYS, HEARTBEATS_PROVIDERS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 import { type PinnedVersions } from './bootstrap/versions.js';
 export type { PinnedVersions };
 export declare const PINNED_VERSIONS: Readonly<PinnedVersions>;
-export type { RequestableField, CallsChange, StorageLimitChange, AiLimitChange, DomainChange, MailTierChange, RequestedChangeValue, ChangeClassification, RequestedChangeState, RequestedChange, } from './requested-changes.js';
+export type { RequestableField, CallsChange, CustomersChange, StorageLimitChange, AiLimitChange, DomainChange, MailTierChange, RequestedChangeValue, ChangeClassification, RequestedChangeState, RequestedChange, } from './requested-changes.js';
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export type { SlugRejectionReason, SlugRejection } from './slug.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateSignIn, validateVersionPin, validateSite, } from './org.js';
+export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateCustomers, validateSignIn, validateVersionPin, validateSite, } from './org.js';
 export { PLATFORM_SERVICE_KEYS, HEARTBEATS_PROVIDERS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 // archon#273: the pinned platform service versions the planner deploys, so a
 // host can show declared against running. Readonly: it is the planner's own

package/dist/migrations/0057_org_customers.sql

@@ -0,0 +1,29 @@
+-- @wtfalch/foundry: a company's customers switch (C3). `customers_enabled` gives the company a
+-- `<slug> customers` sign-in organisation and a read-only directory credential for its Boule;
+-- `customers_sign_up` lets people register themselves in it. Both default off.
+-- Mirrors src/store/schema.ts's `declaredOrgs`.
+
+alter table foundry_declared_orgs
+  add column if not exists customers_enabled boolean not null default false,
+  add column if not exists customers_sign_up boolean not null default false;
+
+-- A company that already signs a hosting entry's users in as customers keeps working. Until now
+-- foundry forced self-registration on for every customers organisation, so those companies carry
+-- both switches on: the live state does not change. A company declared after this migration
+-- starts with sign-up off.
+update foundry_declared_orgs
+   set customers_enabled = true,
+       customers_sign_up = true
+ where jsonb_typeof(hosting_entries) = 'array'
+   and exists (
+     select 1
+       from jsonb_array_elements(hosting_entries) as entry
+      where entry -> 'uses' -> 'auth' ->> 'users' = 'customers'
+   );
+
+-- Requested changes may now name `customers`.
+alter table foundry_requested_changes
+  drop constraint if exists foundry_requested_changes_field_check;
+alter table foundry_requested_changes
+  add constraint foundry_requested_changes_field_check
+    check (field in ('calls', 'customers', 'storageLimit', 'aiLimit', 'domain', 'mailTier'));

package/dist/org.d.ts

@@ -1,3 +1,5 @@
+import { type WorkerAppConfig } from './worker-app-config.js';
+export type { WorkerAppConfig } from './worker-app-config.js';
 /**
  * Opaque, minted by foundry when an org is created. Keys the declared org,
  * the applied state, every estate-wide service's id map, and the chat
@@ -355,6 +357,12 @@ export interface HostingEntry {
      * is the org's own domain.
      */
     worker?: WorkerConfig;
+    /**
+     * A Cloudflare Worker with Durable Objects and Containers, hosted by foundry
+     * as an option any org can declare (ADR 0002). Exclusive with `worker` and a
+     * Coolify `repo`; `validateEntryWorkerApp` states the rest.
+     */
+    workerApp?: WorkerAppConfig;
     /**
      * Blue/green releases (docs/adr/0001-blue-green-releases.md). Presence turns it on: foundry runs the app as a
      * blue and a green copy behind a load balancer on every server it manages, and the tunnel routes to the balancer.
@@ -441,7 +449,19 @@ export interface EntryAuth {
     users: 'staff' | 'customers';
     registration: 'open' | 'closed';
     replacesBrokerEntry?: string;
+    /**
+     * The entry is an OAuth resource server for MCP clients (auth ADR 0002): the
+     * broker is the authorization server, ZITADEL signs the person in. `path` is
+     * the MCP endpoint on the entry's host; the resource is
+     * `https://<the entry's host><path>`, derived and never declared. Needs
+     * `users: 'customers'` and `registration: 'open'`.
+     */
+    mcp?: {
+        path: string;
+    };
 }
+/** The MCP endpoint path: absolute, plain characters, no dot segments, no query. */
+export declare const MCP_PATH: RegExp;
 /**
  * AI for one entry: a key below the org's own ai key, the `AI_*` env and,
  * with `webhookPath`, the ai webhook. `offerings` is what the app may call,
@@ -562,6 +582,8 @@ export declare const heldEnvRef: (orgId: string, entryKey: string, name: string)
 export declare function validateHosting(hosting: HostingConfig, names?: {
     domain: string | null;
     locked: ReadonlySet<string>;
+    slug?: string;
+    siteOwnsApex?: boolean;
 }): string | null;
 /** `blueGreen`: steps ascending, each a whole number 1..100, the last 100; a hold of 1..1440 minutes. */
 export declare function validateBlueGreen(value: unknown, at: string): string | null;
@@ -664,6 +686,24 @@ export interface SignInConfig {
  * own sign-in stack gets the second login app.
  */
 export declare function validateSignIn(org: Pick<DeclaredOrg, 'signIn' | 'domain' | 'issuer' | 'services'>): string | null;
+/**
+ * A company's customers: people outside the company who sign in to its apps (C3, campaign
+ * 2026-10-15). `enabled` gives the company a `<slug> customers` ZITADEL organisation and a
+ * read-only directory credential for its Boule. `signUp` lets people register themselves in
+ * that organisation; it needs `enabled` and is off by default. Both are requestable (`customers`).
+ */
+export interface CustomersConfig {
+    enabled: boolean;
+    signUp: boolean;
+}
+/**
+ * `null` when `customers` is valid: both switches are booleans, sign-up needs customers on, and
+ * an entry with `registration: 'open'` needs both, because open registration signs people up into
+ * the customers organisation.
+ */
+export declare function validateCustomers(org: Pick<DeclaredOrg, 'customers'> & {
+    hosting: Pick<HostingConfig, 'entries'>;
+}): string | null;
 /** The only reader of `services.own`. Every company runs its own services, the platform's owner company too; a company without a domain runs them on oikos.host. */
 export declare function ownsServices(org: Pick<DeclaredOrg, 'services'>): boolean;
 /** The pure part of the `services` rules; that no two orgs share an `sfuSlot` is the store's check. */
@@ -946,6 +986,8 @@ export interface DeclaredOrg {
     services?: ServicesConfig;
     /** Absent means `{ inApp: false }`. Optional so every existing literal and fixture compiles unchanged. */
     signIn?: SignInConfig;
+    /** Absent means `{ enabled: false, signUp: false }`. Optional so every existing literal and fixture compiles unchanged. */
+    customers?: CustomersConfig;
     /** Parts of this company held on their own version. Absent or null follows the platform. Ignored for the owner company. */
     versionPin?: VersionPin | null;
     sso: SsoConfig;

package/dist/org.js

@@ -1,4 +1,5 @@
 import { floatingRefBlocked, floatingTagBlocked } from './bootstrap/versions.js';
+import { entryHasDatabase, validateArtifact, validateEntryWorkerApp, } from './worker-app-config.js';
 /** {@link MailConfig.mailApps} when the org declares none of its own (#34, decided 2026-09-30). */
 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). */
@@ -10,6 +11,8 @@ export const DEFAULT_GATE_LIMIT = 3;
 export const APP_ENTRY_KEY = 'app';
 /** The most volumes one entry may declare. */
 export const MAX_ENTRY_VOLUMES = 8;
+/** The MCP endpoint path: absolute, plain characters, no dot segments, no query. */
+export const MCP_PATH = /^\/[A-Za-z0-9_~-]+(\/[A-Za-z0-9_~-]+)*$|^\/$/;
 /** What an entry's ai key may hold: the most the org's own key holds. */
 export const AI_ENTRY_PERMISSIONS = ['ai.offerings:invoke', 'ai.runs:create'];
 /** The env names `uses.ai` writes; `env` may not name them. */
@@ -159,6 +162,9 @@ export function validateHosting(hosting, names) {
         const invalidWorker = validateEntryWorker(entry, hosting, names?.domain);
         if (invalidWorker)
             return invalidWorker;
+        const invalidWorkerApp = validateEntryWorkerApp(entry, hosting, names);
+        if (invalidWorkerApp)
+            return invalidWorkerApp;
         const invalidEdgeUse = validateEntryEdge(entry, hosting, names?.domain);
         if (invalidEdgeUse)
             return invalidEdgeUse;
@@ -183,7 +189,7 @@ export function validateHosting(hosting, names) {
     const invalidNames = validateEntryHostnames(hosting, names);
     if (invalidNames)
         return invalidNames;
-    if (hosting.entries.filter((entry) => entry.database).length > 1) {
+    if (hosting.entries.filter(entryHasDatabase).length > 1) {
         return 'at most one hosting entry may set database: the one runtime database role cannot serve two apps';
     }
     const invalidGates = validateGates(hosting, names?.domain, names?.locked);
@@ -308,7 +314,10 @@ function validateEntryHostnames(hosting, names) {
             return `${at} hostnames need hosting.usesDomain: without it only the '${APP_ENTRY_KEY}' entry is served, at its own address`;
         }
         const reads = hosting.usesDomain && names?.domain;
-        if (reads && entry.key === APP_ENTRY_KEY && !entry.hostnames.some((n) => n !== '*')) {
+        if (reads &&
+            entry.key === APP_ENTRY_KEY &&
+            !entry.workerApp &&
+            !entry.hostnames.some((n) => n !== '*')) {
             return `${at} needs a hostname ('@' or a label) while hosting.usesDomain is on: '*' alone names nothing, and the app would fall back to the bare domain`;
         }
         for (const name of entry.hostnames) {
@@ -538,6 +547,16 @@ function validateEntryAuth(entry, hosting, domain) {
     if (!hasExactHostname(entry, hosting, domain)) {
         return `${at} needs an exact hostname to sign in at`;
     }
+    if (auth.mcp !== undefined) {
+        if (auth.users !== 'customers' || auth.registration !== 'open') {
+            return `${at} mcp needs users 'customers' and registration 'open': an MCP client signs the customer in, and only customers register themselves`;
+        }
+        if (typeof auth.mcp?.path !== 'string' ||
+            !MCP_PATH.test(auth.mcp.path) ||
+            auth.mcp.path.length > 200) {
+            return `${at} mcp.path must be an absolute path of letters, digits, '_', '~' and '-' segments, such as '/mcp'`;
+        }
+    }
     if (entry.key === 'agora' ||
         entry.key === 'boule' ||
         entry.key === 'cms' ||
@@ -548,6 +567,8 @@ function validateEntryAuth(entry, hosting, domain) {
 }
 /** With no domain the hostnames are not read (`entryHostnames`). */
 function hasExactHostname(entry, hosting, domain) {
+    if (entry.workerApp)
+        return true; // Its host is workerApp.host, or <slug>[-<key>].oikos.host.
     return hosting.usesDomain && domain !== null
         ? entry.hostnames.some((name) => name !== '*')
         : entry.key === APP_ENTRY_KEY;
@@ -638,7 +659,6 @@ function workerRouteZone(route) {
     return host.startsWith('*.') ? host.slice(2) : host;
 }
 const WORKER_ROUTE = /^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+\/.*$/;
-const WORKER_SHA256 = /^[0-9a-f]{64}$/;
 /**
  * Restated, not shared, from `plan/worker.ts`'s `WORKER_ORG_HASH_LENGTH`/
  * `WORKER_NAME_MAX_LENGTH` -- importing them here would import that
@@ -672,29 +692,9 @@ function validateEntryWorker(entry, hosting, domain) {
     if (entry.key.length > WORKER_NAME_MAX_LENGTH - WORKER_NAME_FIXED_LENGTH) {
         return `${at} entry key is too long: the deployed Worker's name (an 8-character org hash, the key, and "-edge") must fit Cloudflare's ${WORKER_NAME_MAX_LENGTH}-character limit`;
     }
-    let artifactUrl;
-    try {
-        artifactUrl = new URL(worker.artifactUrl);
-    }
-    catch {
-        return `${at} artifactUrl must be an absolute URL, not a bare path or relative file`;
-    }
-    if (artifactUrl.protocol !== 'https:') {
-        return `${at} artifactUrl must be an https:// URL`;
-    }
-    if (artifactUrl.username || artifactUrl.password) {
-        return `${at} artifactUrl must not carry userinfo (a signed or credentialed URL ends up stored verbatim in recorded scope ids)`;
-    }
-    if (artifactUrl.search) {
-        return `${at} artifactUrl must not carry a query string (a signed or credentialed URL ends up stored verbatim in recorded scope ids)`;
-    }
-    // `URL.hash` is '' for a bare trailing `#`, so the raw string is checked.
-    if (worker.artifactUrl.includes('#')) {
-        return `${at} artifactUrl must not carry a fragment (refused for the same reason as a query string)`;
-    }
-    if (!WORKER_SHA256.test(worker.artifactSha256)) {
-        return `${at} artifactSha256 must be 64 lowercase hex characters`;
-    }
+    const invalidArtifact = validateArtifact(at, worker.artifactUrl, worker.artifactSha256, entry.repo);
+    if (invalidArtifact)
+        return invalidArtifact;
     if (!WORKER_ROUTE.test(worker.route)) {
         return `${at} route must be a hostname (an optional leading '*.' label, then at least two more labels) and a path, joined by '/'`;
     }
@@ -955,6 +955,32 @@ export function validateSignIn(org) {
     }
     return null;
 }
+/**
+ * `null` when `customers` is valid: both switches are booleans, sign-up needs customers on, and
+ * an entry with `registration: 'open'` needs both, because open registration signs people up into
+ * the customers organisation.
+ */
+export function validateCustomers(org) {
+    const customers = org.customers;
+    if (customers !== undefined) {
+        const value = customers;
+        if (typeof customers !== 'object' ||
+            customers === null ||
+            Array.isArray(customers) ||
+            typeof value?.enabled !== 'boolean' ||
+            typeof value?.signUp !== 'boolean' ||
+            Object.keys(customers).some((key) => key !== 'enabled' && key !== 'signUp')) {
+            return 'customers must be { enabled: boolean, signUp: boolean }';
+        }
+        if (value.signUp && !value.enabled)
+            return 'customers.signUp needs customers.enabled';
+    }
+    const open = org.hosting.entries.find((entry) => entry.uses?.auth?.registration === 'open');
+    if (open && !(org.customers?.enabled && org.customers.signUp)) {
+        return `hosting.entries '${open.key}' uses.auth registration 'open' needs customers.enabled and customers.signUp`;
+    }
+    return null;
+}
 /** The only reader of `services.own`. Every company runs its own services, the platform's owner company too; a company without a domain runs them on oikos.host. */
 export function ownsServices(org) {
     return org.services?.own === true;

package/dist/plan/boule.d.ts

@@ -79,8 +79,44 @@ export declare const BOULE_PEER_PASSWORD_ENV = "AUTHZ_PEER_PASSWORD_OPERATOR";
 export declare const BOULE_BRIDGE_SECRET_ENV = "ARCHON_BRIDGE_SECRET";
 /** The role Boule creates from {@link BOULE_PEER_PASSWORD_ENV}, with grants on schema `authz` only. */
 export declare const BOULE_PEER_ROLE = "authz_operator_rt";
+/** The org's Archon id and the credential Boule reaches Archon with (C3). The id is the org's own; the credential is a secret. */
+export declare const BOULE_ARCHON_ORG_ID_ENV = "ARCHON_ORG_ID";
+export declare const BOULE_ARCHON_CREDENTIAL_ENV = "ARCHON_CREDENTIAL";
+/** The company's customers organisation in the sign-in service, and the read-only credential that lists its people (C3). */
+export declare const BOULE_CUSTOMERS_ORG_ENV = "CUSTOMERS_ORGANISATION_ID";
+export declare const BOULE_CUSTOMERS_CREDENTIAL_ENV = "CUSTOMERS_DIRECTORY_CREDENTIAL";
+/**
+ * When the Archon credential was last minted and held (ISO date-time). No secret. Archon's mint rotates
+ * on every call and the credential lives 365 days, so foundry mints only when none was pushed or the
+ * push is {@link ARCHON_CREDENTIAL_RENEW_AFTER_MS} old.
+ */
+export declare const BOULE_ARCHON_PUSHED_AT_SCOPE_KEY = "boule_archon_pushed_at";
+export declare const ARCHON_CREDENTIAL_RENEW_AFTER_MS: number;
+/** True when no push is recorded, it is unreadable, or it is at least 335 days old. */
+export declare function archonCredentialRenewDue(recorded: Readonly<Record<string, string>>, nowMs: number): boolean;
+/** The ZITADEL machine user that reads the customers organisation. No secret. */
+export declare const CUSTOMERS_DIRECTORY_USER_SCOPE_KEY = "customers_directory_user";
+/** `1` or `0`: the sign-up switch last written to the customers organisation's login policy. */
+export declare const CUSTOMERS_SIGN_UP_SCOPE_KEY = "zitadel_customers_signup";
+/** Where the held-key store keeps the Archon credential of an org's Boule. */
+export declare const bouleArchonCredentialRef: (orgId: string) => string;
+/** Where the held-key store keeps the directory credential of an org's customers. */
+export declare const customersDirectoryRef: (orgId: string) => string;
+/** The customers organisation id `zitadel:customers` recorded. */
+export declare const customersOrgIdOf: (org: Pick<DeclaredOrg, "id">, recorded: Readonly<Record<string, string>>) => string | undefined;
+/**
+ * What the host can deliver to an org's Boule beyond its sign-in env: the Archon credential
+ * (`mintBouleArchonCredential`) and the customers directory credential (`mintOrgDirectoryReader`).
+ * Each needs a held-key store that can put. The plan decides once and carries the answer in the step.
+ */
+export interface BouleCredentialWants {
+    archonCredential?: boolean;
+    customersDirectory?: boolean;
+    /** The recorded Archon credential is missing or 335 days old: the step mints it again. */
+    archonRenewDue?: boolean;
+}
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
-export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "AUTHZ_FIRST_OWNER", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN", "AUTHZ_PEER_PASSWORD_OPERATOR", "ARCHON_BRIDGE_SECRET", "SIGNIN_UPSTREAM"];
+export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "AUTHZ_FIRST_OWNER", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN", "AUTHZ_PEER_PASSWORD_OPERATOR", "ARCHON_BRIDGE_SECRET", "ARCHON_ORG_ID", "ARCHON_CREDENTIAL", "CUSTOMERS_ORGANISATION_ID", "CUSTOMERS_DIRECTORY_CREDENTIAL", "SIGNIN_UPSTREAM"];
 /**
  * The env vars an org's Boule app should carry, and every input still missing
  * to build them. Callers that write must refuse on a non-empty `missing`: a
@@ -106,7 +142,7 @@ export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER",
  * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
  * (generated once, never rotated).
  */
-export declare function desiredBouleEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, issuer: string | null, archonUrl: string | null, mailWanted?: boolean): {
+export declare function desiredBouleEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, issuer: string | null, archonUrl: string | null, mailWanted?: boolean, wants?: BouleCredentialWants): {
     env: Record<string, string>;
     missing: string[];
 };
@@ -129,3 +165,8 @@ export declare function wantedBouleBrokerEntry(org: DeclaredOrg, recorded: Reado
  * except `SIGNIN_UPSTREAM`: the switch turned off must take it away, so a live one that is not desired is drift.
  */
 export declare function bouleEnvDrift(desired: Readonly<Record<string, string>>, live: Readonly<Record<string, string>>): string[];
+/**
+ * The customers env a live Boule still holds after the company switched customers off. A host that merely
+ * cannot deliver the credential keeps what it has: only an explicit off removes it.
+ */
+export declare function staleCustomersEnv(org: Pick<DeclaredOrg, 'customers'>, live: Readonly<Record<string, string>>): string[];

package/dist/plan/boule.js

@@ -90,6 +90,34 @@ export const BOULE_PEER_PASSWORD_ENV = 'AUTHZ_PEER_PASSWORD_OPERATOR';
 export const BOULE_BRIDGE_SECRET_ENV = 'ARCHON_BRIDGE_SECRET';
 /** The role Boule creates from {@link BOULE_PEER_PASSWORD_ENV}, with grants on schema `authz` only. */
 export const BOULE_PEER_ROLE = 'authz_operator_rt';
+/** The org's Archon id and the credential Boule reaches Archon with (C3). The id is the org's own; the credential is a secret. */
+export const BOULE_ARCHON_ORG_ID_ENV = 'ARCHON_ORG_ID';
+export const BOULE_ARCHON_CREDENTIAL_ENV = 'ARCHON_CREDENTIAL';
+/** The company's customers organisation in the sign-in service, and the read-only credential that lists its people (C3). */
+export const BOULE_CUSTOMERS_ORG_ENV = 'CUSTOMERS_ORGANISATION_ID';
+export const BOULE_CUSTOMERS_CREDENTIAL_ENV = 'CUSTOMERS_DIRECTORY_CREDENTIAL';
+/**
+ * When the Archon credential was last minted and held (ISO date-time). No secret. Archon's mint rotates
+ * on every call and the credential lives 365 days, so foundry mints only when none was pushed or the
+ * push is {@link ARCHON_CREDENTIAL_RENEW_AFTER_MS} old.
+ */
+export const BOULE_ARCHON_PUSHED_AT_SCOPE_KEY = 'boule_archon_pushed_at';
+export const ARCHON_CREDENTIAL_RENEW_AFTER_MS = 335 * 24 * 60 * 60 * 1000;
+/** True when no push is recorded, it is unreadable, or it is at least 335 days old. */
+export function archonCredentialRenewDue(recorded, nowMs) {
+    const at = Date.parse(recorded[BOULE_ARCHON_PUSHED_AT_SCOPE_KEY] ?? '');
+    return Number.isNaN(at) || nowMs - at >= ARCHON_CREDENTIAL_RENEW_AFTER_MS;
+}
+/** The ZITADEL machine user that reads the customers organisation. No secret. */
+export const CUSTOMERS_DIRECTORY_USER_SCOPE_KEY = 'customers_directory_user';
+/** `1` or `0`: the sign-up switch last written to the customers organisation's login policy. */
+export const CUSTOMERS_SIGN_UP_SCOPE_KEY = 'zitadel_customers_signup';
+/** Where the held-key store keeps the Archon credential of an org's Boule. */
+export const bouleArchonCredentialRef = (orgId) => `foundry:boule-archon:${orgId}`;
+/** Where the held-key store keeps the directory credential of an org's customers. */
+export const customersDirectoryRef = (orgId) => `foundry:customers-directory:${orgId}`;
+/** The customers organisation id `zitadel:customers` recorded. */
+export const customersOrgIdOf = (org, recorded) => recorded[`zitadel:customers:${org.id}`] || undefined;
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
 export const BOULE_MANAGED_ENV_KEYS = [
     'APP_URL',
@@ -104,6 +132,10 @@ export const BOULE_MANAGED_ENV_KEYS = [
     BOULE_MAIL_TOKEN_ENV,
     BOULE_PEER_PASSWORD_ENV,
     BOULE_BRIDGE_SECRET_ENV,
+    BOULE_ARCHON_ORG_ID_ENV,
+    BOULE_ARCHON_CREDENTIAL_ENV,
+    BOULE_CUSTOMERS_ORG_ENV,
+    BOULE_CUSTOMERS_CREDENTIAL_ENV,
     SIGN_IN_UPSTREAM_ENV,
 ];
 /**
@@ -131,7 +163,7 @@ export const BOULE_MANAGED_ENV_KEYS = [
  * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
  * (generated once, never rotated).
  */
-export function desiredBouleEnv(org, recorded, issuer, archonUrl, mailWanted = false) {
+export function desiredBouleEnv(org, recorded, issuer, archonUrl, mailWanted = false, wants = {}) {
     const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
     const clientId = recorded[BOULE_CLIENT_ID_SCOPE_KEY];
     const missing = [];
@@ -153,6 +185,12 @@ export function desiredBouleEnv(org, recorded, issuer, archonUrl, mailWanted = f
         env.AUTH_CLIENT_ID = clientId;
     if (archonUrl)
         env.ARCHON_URL = archonUrl;
+    if (wants.archonCredential)
+        env[BOULE_ARCHON_ORG_ID_ENV] = org.id;
+    // The id is not missing while unrecorded: the customers step records it, and the plan plans Boule again then.
+    const customersOrgId = wants.customersDirectory ? customersOrgIdOf(org, recorded) : undefined;
+    if (customersOrgId)
+        env[BOULE_CUSTOMERS_ORG_ENV] = customersOrgId;
     const owner = org.owners[0];
     const ownerUserId = owner
         ? recorded[`zitadel:owner:${org.id}:${owner.email.toLowerCase()}`]
@@ -219,3 +257,12 @@ export function bouleEnvDrift(desired, live) {
         drift.push(SIGN_IN_UPSTREAM_ENV);
     return drift;
 }
+/**
+ * The customers env a live Boule still holds after the company switched customers off. A host that merely
+ * cannot deliver the credential keeps what it has: only an explicit off removes it.
+ */
+export function staleCustomersEnv(org, live) {
+    if (org.customers?.enabled)
+        return [];
+    return [BOULE_CUSTOMERS_ORG_ENV, BOULE_CUSTOMERS_CREDENTIAL_ENV].filter((key) => live[key] !== undefined);
+}

package/dist/plan/broker-entries.d.ts

@@ -19,6 +19,28 @@ export declare function brokerEntryName(org: DeclaredOrg, entry: HostingEntry):
 export declare function brokerEntryAppliedScopeKey(entryKey: string): string;
 /** The foreign entries the last write found invalid, as a JSON array of names. */
 export declare function brokerEntryWarningsScopeKey(entryKey: string): string;
+/** The ZITADEL project id that is an MCP entry's token audience, recorded by `zitadel:mcp-project`. */
+export declare const entryMcpProjectScopeKey: (entryKey: string) => string;
+/** The marker for the entry's app having JWT access tokens and the MCP callback (`zitadel:mcp-access`). */
+export declare const entryMcpAccessAppliedScopeKey: (entryKey: string) => string;
+/** The instance access-token lifetime the MCP flow wants, in seconds (auth ADR 0002, 4). */
+export declare const MCP_ACCESS_TOKEN_LIFETIME_SECONDS = 3600;
+/** Records the lifetime foundry last set; the value is {@link MCP_ACCESS_TOKEN_LIFETIME_SECONDS}. */
+export declare const ACCESS_TOKEN_LIFETIME_APPLIED_SCOPE_KEY = "access_token_lifetime_applied";
+/** The broker's callback on the org's login host. It joins the entry app's redirect URIs. */
+export declare const mcpCallbackUri: (org: DeclaredOrg) => string;
+/**
+ * What an entry's MCP resource is, from the one recorded project id. The
+ * broker entry (`wantedBrokerEntry`) and the app's env (`entryAuthEnv`) both
+ * read it here, so the audience the broker checks and the audience the app
+ * compares are the same value. `null` without `mcp`, or until the project
+ * exists.
+ */
+export declare function entryMcp(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): {
+    resource: string;
+    projectId: string;
+    loginHost: string;
+} | null;
 /** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
 export declare function entryAuthEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, issuer: string | null): Record<string, string>;
 /** The marker `pushAppEnv` records for an entry's sign-in env; the planner compares against it. */
@@ -32,6 +54,12 @@ export interface BrokerEntryWant {
     from: string;
     registration: boolean;
     replaces: string | null;
+    /** Present only for an entry with `uses.auth.mcp`: what the broker needs to be its authorization server. */
+    mcp?: {
+        resource: string;
+        projectId: string;
+        loginHost: string;
+    };
 }
 /**
  * Each value a broker entry needs and the step that records it, so the

package/dist/plan/broker-entries.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { isFoundryOwnedBrokerEntryName, } from '../org.js';
 import { entryClientIdScopeKey } from './agora.js';
 import { entryHostnames } from './hostnames.js';
+import { loginHostnameFor } from './login-host.js';
 import { PLATFORM_ARCHON_ORG_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, parseBrokerDeployRecord, } from './platform-diff.js';
 import { archonOrgConflicts, brokerDeployNeeded, brokerDeployRecordValue, missingBrokerInputs, validateBrokerAppEntry, } from './platform-providers.js';
 /**
@@ -28,6 +29,31 @@ export function brokerEntryAppliedScopeKey(entryKey) {
 export function brokerEntryWarningsScopeKey(entryKey) {
     return `broker_entry_warnings.${entryKey}`;
 }
+/** The ZITADEL project id that is an MCP entry's token audience, recorded by `zitadel:mcp-project`. */
+export const entryMcpProjectScopeKey = (entryKey) => `mcp_project_id.${entryKey}`;
+/** The marker for the entry's app having JWT access tokens and the MCP callback (`zitadel:mcp-access`). */
+export const entryMcpAccessAppliedScopeKey = (entryKey) => `mcp_access_applied.${entryKey}`;
+/** The instance access-token lifetime the MCP flow wants, in seconds (auth ADR 0002, 4). */
+export const MCP_ACCESS_TOKEN_LIFETIME_SECONDS = 3600;
+/** Records the lifetime foundry last set; the value is {@link MCP_ACCESS_TOKEN_LIFETIME_SECONDS}. */
+export const ACCESS_TOKEN_LIFETIME_APPLIED_SCOPE_KEY = 'access_token_lifetime_applied';
+/** The broker's callback on the org's login host. It joins the entry app's redirect URIs. */
+export const mcpCallbackUri = (org) => `https://${loginHostnameFor(org)}/mcp-oauth/callback`;
+/**
+ * What an entry's MCP resource is, from the one recorded project id. The
+ * broker entry (`wantedBrokerEntry`) and the app's env (`entryAuthEnv`) both
+ * read it here, so the audience the broker checks and the audience the app
+ * compares are the same value. `null` without `mcp`, or until the project
+ * exists.
+ */
+export function entryMcp(org, entry, recorded) {
+    const mcp = entry.uses?.auth?.mcp;
+    const projectId = recorded[entryMcpProjectScopeKey(entry.key)];
+    const host = entryHostnames(org, entry)[0];
+    if (!mcp || !projectId || !host)
+        return null;
+    return { resource: `https://${host}${mcp.path}`, projectId, loginHost: loginHostnameFor(org) };
+}
 /** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
 export function entryAuthEnv(org, entry, recorded, issuer) {
     const auth = entry.uses?.auth;
@@ -39,6 +65,15 @@ export function entryAuthEnv(org, entry, recorded, issuer) {
         AUTH_CLIENT_ID: recorded[entryClientIdScopeKey(entry.key)],
         AUTH_ISSUER: issuer ?? undefined,
     };
+    const mcp = entryMcp(org, entry, recorded);
+    const mcpValues = mcp
+        ? {
+            MCP_AUDIENCE: mcp.projectId,
+            MCP_RESOURCE: mcp.resource,
+            MCP_ISSUER: `https://${mcp.loginHost}`,
+        }
+        : {};
+    Object.assign(values, mcpValues);
     return Object.fromEntries(Object.entries(values).filter(([, value]) => Boolean(value)));
 }
 /** The marker `pushAppEnv` records for an entry's sign-in env; the planner compares against it. */
@@ -60,7 +95,11 @@ export function wantedBrokerEntry(org, entry, recorded) {
         missing.push({ what: 'its sign-in client id', producedBy: ['zitadel', 'app'] });
     if (!mailDomain)
         missing.push({ what: 'the org mail domain', producedBy: ['coolify', 'mail'] });
-    if (!organizationId || !clientId || !mailDomain)
+    const mcp = entryMcp(org, entry, recorded);
+    if (auth.mcp && !mcp) {
+        missing.push({ what: 'its MCP audience project id', producedBy: ['zitadel', 'mcp-project'] });
+    }
+    if (!organizationId || !clientId || !mailDomain || (auth.mcp && !mcp))
         return { missing };
     return {
         want: {
@@ -71,6 +110,7 @@ export function wantedBrokerEntry(org, entry, recorded) {
             from: `${org.mail.noReplyLocalPart || 'noreply'}@${mailDomain}`,
             registration: auth.registration === 'open',
             replaces: auth.replacesBrokerEntry ?? null,
+            ...(mcp ? { mcp } : {}),
         },
     };
 }
@@ -182,6 +222,11 @@ export async function writeBrokerEntry(broker, input) {
         from: want.from,
         registration: want.registration,
     };
+    // The previous write's `mcp` goes when the entry no longer declares it.
+    if (want.mcp)
+        entry.mcp = want.mcp;
+    else
+        entry.mcp = undefined;
     try {
         validateBrokerAppEntry(entry, brokerAppId, 0);
     }

package/dist/plan/diff.d.ts

@@ -53,6 +53,8 @@ export interface PlanOrgOptions {
     loginHostServesDiscovery?: boolean;
     /** The executor's ZITADEL client has `updateOidcAppIdTokenUserinfoAssertion`; without it `planIdTokenUserinfo` plans nothing. */
     zitadelIdTokenUserinfo?: boolean;
+    /** The executor's ZITADEL client has `ensureOidcAppMcpAccess` and `ensureAccessTokenLifetime`; without them `planMcp` is blocked. */
+    zitadelMcp?: boolean;
     /** F5: the executor was built with a `broker` port. */
     broker?: boolean;
     /** #161: the slugs of the other declared orgs, so a Boule whose hostname another org's slug would take is blocked. */
@@ -63,6 +65,14 @@ export interface PlanOrgOptions {
     archonUrl?: string | null;
     /** #318: the executor was built with a `WorkersPort`, read by `planWorkers`. */
     edgeWorkers?: boolean;
+    /** ADR 0002: the executor was built with a `WorkerAppPort`, read by `planWorkerApps`. */
+    workerApps?: boolean;
+    /** ADR 0002: the keys service address, when the executor has a keys port. */
+    workerAppKeysUrl?: string;
+    /** C2: true when the executor was built with a `WorkerAppDatabasePort`; a `workerApp.database` is blocked without it. */
+    workerAppDatabase?: boolean;
+    /** ADR 0002: the platform's Cloudflare account id; a container image must live in its registry. */
+    workerAppRegistryAccountId?: string;
     /** The executor was built with an `ownerInviteMail` port; without it each owner's invite is blocked. */
     ownerInviteMail?: boolean;
     /** The platform's own service hostnames: `edgeReservedLabels` reserves them under the org's domain, and a wildcard Worker route (`planWorkers`) keeps them out. */
@@ -73,6 +83,10 @@ export interface PlanOrgOptions {
     ownMailKeyHeld?: boolean;
     /** The executor can mint an own org's Lettermint key (`FoundryStepExecutor.ownMailKeyMintable`). */
     ownMailKeyMintable?: boolean;
+    /** C3: the executor can mint a customers directory credential (`ZitadelPort.mintOrgDirectoryReader`). */
+    customersDirectory?: boolean;
+    /** C3: the executor can mint Boule's Archon credential (`FoundryStepExecutorPorts.mintBouleArchonCredential`). */
+    bouleArchonCredential?: boolean;
     /** The executor can store the sign-in database's CA and certificate (`FoundryStepExecutor.ownSigninDbKeysPuttable`). Absent: true. */
     ownSigninDbKeysPuttable?: boolean;
     /** The host supplies the backup bucket the sign-in database dumps into (`FoundryStepExecutor.ownSigninDbBackupConfigured`). Absent: true. */