@wtfalch/foundry 0.76.0 → 0.77.0

package/dist/plan/reporting.js

@@ -0,0 +1,135 @@
+import { appsOn } from '../org.js';
+import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
+import { bouleMailFrom } from './boule.js';
+import { signinMailName } from './signin-mail.js';
+/**
+ * A company's own reporting backend (https://github.com/wtfalch/reporting, ADR 0002, `docs/plans/backend.md`
+ * slice 5): one Coolify app and one database per company, built from that repo's root Dockerfile, the same shape
+ * as the analytics backend (`plan/analytics.ts`). It is planned only while something uses it: a hosting entry
+ * declares `uses.reporting`, or the company's Boule runs apps (`org.boule.apps`).
+ *
+ * What the host (`apps/host`) reads to start: `DATABASE_URL` and `DATABASE_URL_OWNER` (written by
+ * `pushDatabaseUrl`), `REPORTING_OPERATOR_KEY` (generated once here), `AUTH_ORGANIZATION_ID` (the company's
+ * sign-in organisation; the tenant id of every key and row derives from it, and without it minting answers 503)
+ * and `APP_URL`. It reads no other `AUTH_*` name yet, so no sign-in client is made for it. When its screens need
+ * `AUTH_ISSUER` and `AUTH_CLIENT_ID`, add the client then.
+ */
+/** True while some entry declares `uses.reporting`, or Boule runs apps: the backend is wanted. */
+export const reportingWanted = (org) => appsOn(org) || org.hosting.entries.some((e) => e.uses?.reporting === true);
+/** `reporting.<domain>`, or `<slug>-reporting.oikos.host` for a company without a domain. */
+export function reportingHostnameFor(org) {
+    return org.domain ? `reporting.${org.domain}` : `${org.slug}-reporting.oikos.host`;
+}
+/** The public address apps and Boule send to, `REPORTING_URL`. */
+export const reportingUrlFor = (org) => `https://${reportingHostnameFor(org)}`;
+/** The backend's database uuid, recorded beside the app's own id. */
+export const REPORTING_DATABASE_SCOPE_KEY = 'coolify_reporting_database';
+/** Recorded once the app was deployed, as `coolify_boule_deployed` is for Boule. */
+export const REPORTING_DEPLOYED_SCOPE_KEY = 'coolify_reporting_deployed';
+/** The env name the backend reads its operator key from; also Boule's name for it. */
+export const REPORTING_OPERATOR_KEY_ENV = 'REPORTING_OPERATOR_KEY';
+/** The env names `desiredReportingEnv` writes, so the live reader knows which to read back. */
+export const REPORTING_MANAGED_ENV_KEYS = ['APP_URL', 'AUTH_ORGANIZATION_ID', 'MAIL_FROM'];
+/**
+ * The Lettermint token the backend sends error alerts with (reporting#103): the company's `<slug>-app` token,
+ * joined as a consumer like a `uses.mail` entry. A secret: the executor writes it, the live reader says only
+ * whether it is there (`config.mailTokenHeld`), and no plan carries its value.
+ */
+export const REPORTING_MAIL_TOKEN_ENV = 'LETTERMINT_API_TOKEN';
+/**
+ * The backend's sender, `Name <address>`: the company's display name and the same no-reply address the main
+ * app and Boule send from. The name is one line, and quoted when it holds a character an address header
+ * gives a meaning to.
+ */
+export function reportingMailFrom(org, mailDomain) {
+    const address = bouleMailFrom(org, mailDomain);
+    const name = signinMailName(org.displayName)
+        .replace(/["\\<>]/g, '')
+        .trim();
+    if (!name)
+        return address;
+    return /[()[\]:;@,.]/.test(name) ? `"${name}" <${address}>` : `${name} <${address}>`;
+}
+/**
+ * The `REPORTING_*` names foundry's reporting steps write: an entry's address and site key, and Boule's
+ * address and operator key. Every other `REPORTING_*` name on a blue/green color is the color's own
+ * (`REPORTING_COLOR`, `REPORTING_RELEASE`, `REPORTING_HEALTH_TOKEN`), so these are the ones a color copies from
+ * blue like any other env.
+ */
+export const REPORTING_SHARED_ENV_NAMES = [
+    'REPORTING_URL',
+    'REPORTING_SITE_KEY',
+    REPORTING_OPERATOR_KEY_ENV,
+];
+/** Whether a `REPORTING_*` name belongs to one blue/green color and is never copied or removed by the copy. */
+export const isColorReportingEnv = (key) => key.startsWith('REPORTING_') && !REPORTING_SHARED_ENV_NAMES.includes(key);
+/**
+ * What the backend's env must hold. `mailDomain` (the company's recorded mail domain, given only while its
+ * mail is on and not blocked) adds `MAIL_FROM`; the token is never here.
+ */
+export function desiredReportingEnv(org, recorded, mailDomain = null) {
+    const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
+    const env = { APP_URL: reportingUrlFor(org) };
+    if (zitadelOrgId)
+        env.AUTH_ORGANIZATION_ID = zitadelOrgId;
+    if (mailDomain)
+        env.MAIL_FROM = reportingMailFrom(org, mailDomain);
+    return { env, missing: zitadelOrgId ? [] : ['zitadelOrgId'] };
+}
+export function reportingEnvDrift(desired, live) {
+    return Object.entries(desired)
+        .filter(([key, value]) => live[key] !== value)
+        .map(([key]) => key);
+}
+const CALL_TIMEOUT_MS = 20_000;
+/**
+ * The real {@link ReportingPort}: `POST <baseUrl>/v1/site-keys` with `{ name, site, environment }` answers 201
+ * `{ id, secret, site, environment }`; `DELETE <baseUrl>/v1/site-keys/<id>` answers 204. A 201 that binds the
+ * key to another site or environment than asked is refused, so a key never reports where Boule does not read.
+ * Errors carry the status only, never a body, the key or the secret.
+ */
+export function httpReporting(options = {}) {
+    const fetchImpl = options.fetch ?? fetch;
+    const call = async (url, init, what) => {
+        try {
+            return await fetchImpl(url, {
+                ...init,
+                redirect: 'error',
+                signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+            });
+        }
+        catch {
+            throw new Error(`the reporting backend did not answer when asked to ${what}`);
+        }
+    };
+    return {
+        async mintSiteKey({ baseUrl, operatorKey, name, site, environment }) {
+            const response = await call(`${baseUrl}/v1/site-keys`, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${operatorKey}`, 'content-type': 'application/json' },
+                body: JSON.stringify({ name, site, environment }),
+            }, 'mint a site key');
+            if (response.status !== 201) {
+                throw Object.assign(new Error(`the reporting backend refused to mint a site key (status ${response.status})`), { status: response.status });
+            }
+            const body = await response.json().catch(() => undefined);
+            const fields = typeof body === 'object' && body !== null ? body : {};
+            if (typeof fields.id !== 'string' ||
+                !fields.id ||
+                typeof fields.secret !== 'string' ||
+                !fields.secret) {
+                throw new Error('the reporting backend answered 201 but sent no key id and secret');
+            }
+            if (fields.site !== site || fields.environment !== environment) {
+                throw new Error(`the reporting backend answered 201 with key ${fields.id} bound to another site or environment than asked`);
+            }
+            return { id: fields.id, secret: fields.secret };
+        },
+        async revokeSiteKey({ baseUrl, operatorKey, keyId }) {
+            const response = await call(`${baseUrl}/v1/site-keys/${encodeURIComponent(keyId)}`, { method: 'DELETE', headers: { authorization: `Bearer ${operatorKey}` } }, 'revoke a site key');
+            if (response.status !== 204) {
+                throw Object.assign(new Error(`the reporting backend refused to revoke a site key (status ${response.status})`), { status: response.status });
+            }
+        },
+    };
+}

package/dist/plan/stage-env.js

@@ -5,6 +5,7 @@ const WAITS_FOR_STAGE_SERVICE = new Set([
     'AI_URL',
     'JOBS_SCHEDULER_URL',
     'ANALYTICS_URL',
+    'REPORTING_URL',
     'WORKSPACES_URL',
     'MCP_ISSUER',
 ]);

package/dist/plan/stage-isolation.d.ts

@@ -42,6 +42,8 @@ export interface LiveSignIn {
     customersOrgId?: string;
     /** The live app's client ids. */
     clientIds: readonly string[];
+    /** The team clients of the live apps whose customers and team both sign in (ADR 0003). */
+    teamClientIds?: readonly string[];
     /** The live workspaces keys. */
     workspacesKeys: readonly string[];
     /** The live apps' MCP audiences (the ZITADEL project ids). */
@@ -72,7 +74,7 @@ export interface StageIsolationInput {
  *    {@link SHARED_WITH_PROD} differs from production's), `live_mode_key`.
  *  - A4 names: `resource_shared`, `host_is_prod_internal`.
  *  - A5 mail: `mail_not_sink`, `mail_token`.
- *  - A6 sign-in (with `signIn`): `live_customers_org`, `live_client_id`, `live_workspaces_key`,
+ *  - A6 sign-in (with `signIn`): `live_customers_org`, `live_client_id`, `live_team_client_id`, `live_workspaces_key`,
  *    `live_mcp_audience`, `live_mcp_resource` when stage holds the live customers organisation id, a live client
  *    id, the live workspaces key, or a live MCP audience or resource.
  */

package/dist/plan/stage-isolation.js

@@ -17,7 +17,11 @@ function globMatches(pattern, name) {
     return pattern.endsWith('*') ? name.startsWith(pattern.slice(0, -1)) : pattern === name;
 }
 const matchesAny = (patterns, name) => patterns.some((p) => globMatches(p, name));
-const MAIL_NAME = /^(MAIL_|LETTERMINT_|SMTP_)/;
+/**
+ * The mail names A5 holds to the sink's wiring. `MAIL_APP_KEY` is left out: it only tags a send with the app's
+ * key (`<key>-work` on stage, never production's), so it is checked as any other allowed name.
+ */
+const MAIL_NAME = /^(MAIL_(?!APP_KEY$)|LETTERMINT_|SMTP_)/;
 /** Env names (or `PREFIX_*`) each kind of stage app may hold. A name not here is refused. */
 export const STAGE_ALLOWLIST = {
     boule: [
@@ -75,6 +79,8 @@ export const STAGE_ALLOWLIST = {
         'AUTH_CLIENT_ID',
         'AUTH_APP_KEY',
         'AUTH_COOKIE_SECRET',
+        'AUTH_TEAM_CLIENT_ID',
+        'AUTH_TEAM_ORGANIZATION_ID',
         'FILES_URL',
         'FILES_ORGANISATION_ID',
         'FILES_API_KEY',
@@ -87,12 +93,15 @@ export const STAGE_ALLOWLIST = {
         'JOBS_SYNC_KEY',
         'ANALYTICS_URL',
         'ANALYTICS_SITE_KEY',
+        'REPORTING_URL',
+        'REPORTING_SITE_KEY',
         'WORKSPACES_URL',
         'WORKSPACES_API_KEY',
         'AUTH_EVENTS_SECRET',
         'MCP_AUDIENCE',
         'MCP_RESOURCE',
         'MCP_ISSUER',
+        'MAIL_APP_KEY',
     ],
 };
 /** Names no stage holds, whatever the app. */
@@ -121,6 +130,9 @@ const DENY_COMMON = [
     'ARCHON_SETUP_CODE',
     'ARCHON_FIRST_OWNER_LINK',
     'MAINTENANCE_BYPASS_TOKEN',
+    // foundry#1137: the analytics backend's person key lives in that backend's own env only. No stage or
+    // workspace copy of the backend exists; a stage that ever holds the name is refused, whatever its value.
+    'ANALYTICS_PERSON_KEY',
 ];
 const DENY_BY_KIND = {
     boule: ['JOBS_*', 'EDGE_*'],
@@ -155,6 +167,7 @@ export function isAllowed(kind, name) {
 export const SHARED_WITH_PROD = {
     AUTH_ISSUER: 'stage signs in through the same issuer by decision; it holds no ZITADEL management token, and an OIDC client cannot write users',
     AUTH_ORGANIZATION_ID: 'same issuer organisation as AUTH_ISSUER; an id, not a credential',
+    AUTH_TEAM_ORGANIZATION_ID: "the company's own organisation, where the team signs in on stage too, with a client of stage's own; an id, not a credential",
     CI_ORGANIZATION_ID: 'an id of the same issuer organisation; not a credential',
     CUSTOMERS_ORGANISATION_ID: 'an id of the customers organisation in the same issuer; not a credential',
     BOULE_ORG_NAME: 'a display name',
@@ -165,6 +178,7 @@ export const SHARED_WITH_PROD = {
     AI_URL: 'the ai service is shared; stage reaches it only with its own organisation and key',
     JOBS_SCHEDULER_URL: 'the jobs service is shared; stage reaches it only with its own project and signing secret',
     ANALYTICS_URL: 'the analytics collector is shared; stage reports under its own site key',
+    REPORTING_URL: "the company's reporting backend is shared; stage sends under its own site key, environment stage",
     MCP_ISSUER: 'the sign-in service is shared by decision; the issuer is a public address, not a credential',
     WORKSPACES_URL: "the broker is shared; stage's own workspaces key opens its own product tenant, which holds no live customers' workspaces",
 };
@@ -233,7 +247,7 @@ function agoraConfigViolations(value, prodByName, prodHosts) {
  *    {@link SHARED_WITH_PROD} differs from production's), `live_mode_key`.
  *  - A4 names: `resource_shared`, `host_is_prod_internal`.
  *  - A5 mail: `mail_not_sink`, `mail_token`.
- *  - A6 sign-in (with `signIn`): `live_customers_org`, `live_client_id`, `live_workspaces_key`,
+ *  - A6 sign-in (with `signIn`): `live_customers_org`, `live_client_id`, `live_team_client_id`, `live_workspaces_key`,
  *    `live_mcp_audience`, `live_mcp_resource` when stage holds the live customers organisation id, a live client
  *    id, the live workspaces key, or a live MCP audience or resource.
  */
@@ -281,6 +295,10 @@ export function assertStageIsolated(input) {
             if (name === 'AUTH_CLIENT_ID' && live.clientIds.includes(item.value)) {
                 out.add(`live_client_id:${name}`);
             }
+            if (name === 'AUTH_TEAM_CLIENT_ID' &&
+                (live.teamClientIds?.includes(item.value) || live.clientIds.includes(item.value))) {
+                out.add(`live_team_client_id:${name}`);
+            }
             if (name === 'WORKSPACES_API_KEY' && live.workspacesKeys.includes(item.value)) {
                 out.add(`live_workspaces_key:${name}`);
             }

package/dist/plan/stage-services.d.ts

@@ -5,7 +5,7 @@ import { type StageKind } from './stage-isolation.js';
  * minted for it only. A stage key is worthless on production, and production's key never reaches stage. Nothing
  * here returns, logs or throws a secret: errors carry fixed text, ids and refs (CLAUDE.md, Platform steps).
  */
-export type StageService = 'files' | 'ai' | 'jobs' | 'analytics';
+export type StageService = 'files' | 'ai' | 'jobs' | 'analytics' | 'reporting';
 export declare const STAGE_SERVICES: readonly StageService[];
 /** One credential a service shows once: the env name stage holds it under, and its value. */
 export interface StageSecret {
@@ -46,6 +46,8 @@ export interface StageServicesPort {
     jobs?: StageServicePort;
     /** The company's analytics backend: stage's own site key (environment `stage`), shown once with the mint. */
     analytics?: StageServicePort;
+    /** The company's reporting backend: stage's own site key (site = the entry key, environment `stage`), shown once with the mint. */
+    reporting?: StageServicePort;
     /** The id of production's jobs project, so stage's jobs key can be tried against it. */
     prodJobsProjectId?: string;
 }

package/dist/plan/stage-services.js

@@ -1,7 +1,13 @@
 import { createHash } from 'node:crypto';
 import { bgKey } from './blue-green.js';
 import { isAllowed } from './stage-isolation.js';
-export const STAGE_SERVICES = ['files', 'ai', 'jobs', 'analytics'];
+export const STAGE_SERVICES = [
+    'files',
+    'ai',
+    'jobs',
+    'analytics',
+    'reporting',
+];
 /** Fixed text and ids only: safe to log, record and return. */
 export class StageServiceError extends Error {
     name = 'StageServiceError';
@@ -15,6 +21,7 @@ const SERVICE_ENV = {
         url: 'JOBS_SCHEDULER_URL',
     },
     analytics: { evidence: ['ANALYTICS_URL', 'ANALYTICS_SITE_KEY'], url: 'ANALYTICS_URL' },
+    reporting: { evidence: ['REPORTING_URL', 'REPORTING_SITE_KEY'], url: 'REPORTING_URL' },
 };
 /** The fixed reasons a used service is recorded absent. */
 export const STAGE_SERVICE_ABSENT = {

package/dist/plan/stage-sink.d.ts

@@ -19,9 +19,9 @@ export declare const STAGE_SINK_APPLIED_SCOPE_KEY = "stage_sink_applied";
 export declare const STAGE_SINK_APP_SCOPE_KEY = "stage_sink_app";
 /**
  * Part of the structure hash of a primary server. Raise it when the sink wiring changes, so an applied
- * structure runs once more.
+ * structure runs once more. 2: a stage of an entry that sends mail also gets `MAIL_APP_KEY` (`<key>-work`).
  */
-export declare const STAGE_SINK_VERSION = 1;
+export declare const STAGE_SINK_VERSION = 2;
 type SinkOrg = Pick<DeclaredOrg, 'slug'>;
 export declare const stageSinkAppName: (org: SinkOrg) => string;
 /** The sink's HTTP address on the company's Docker network. */

package/dist/plan/stage-sink.js

@@ -18,9 +18,9 @@ export const STAGE_SINK_APPLIED_SCOPE_KEY = 'stage_sink_applied';
 export const STAGE_SINK_APP_SCOPE_KEY = 'stage_sink_app';
 /**
  * Part of the structure hash of a primary server. Raise it when the sink wiring changes, so an applied
- * structure runs once more.
+ * structure runs once more. 2: a stage of an entry that sends mail also gets `MAIL_APP_KEY` (`<key>-work`).
  */
-export const STAGE_SINK_VERSION = 1;
+export const STAGE_SINK_VERSION = 2;
 export const stageSinkAppName = (org) => `${org.slug}-stage-sink`;
 /** The sink's HTTP address on the company's Docker network. */
 export const stageSinkInternalUrl = (org) => `http://${stageSinkAppName(org)}:${STAGE_SINK_HTTP_PORT}`;

package/dist/plan/workspace-client.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, HostingEntry } from '../org.js';
+import { type DeclaredOrg, type HostingEntry } from '../org.js';
 /** The name of an entry's workspace client and of the key its workspace broker entry is held under. */
 export declare const workspaceClientKey: (entryKey: string) => string;
 /** The company's ZITADEL organisation for the customers of its workspaces. The space keeps it apart from every slug. */

package/dist/plan/workspace-client.js

@@ -1,3 +1,4 @@
+import { signsInCustomers } from '../org.js';
 import { workspaceHost } from './hostnames.js';
 /**
  * What the sign-in of a server workspace is called, shared by the planners that must agree on it. A workspace of
@@ -27,7 +28,7 @@ export function workspaceAuthEntries(org) {
 /** The entry whose workspace client is named `clientKey`, or `undefined`. */
 export const workspaceAuthEntryOf = (org, clientKey) => workspaceAuthEntries(org).find((entry) => workspaceClientKey(entry.key) === clientKey);
 /** The entries whose workspace signs in the test customers organisation. */
-export const testCustomersEntries = (org) => workspaceAuthEntries(org).filter((entry) => entry.uses?.auth?.users === 'customers');
+export const testCustomersEntries = (org) => workspaceAuthEntries(org).filter((entry) => signsInCustomers(entry.uses?.auth));
 /** The addresses a workspace client signs in at: the workspace host. */
 export const workspaceClientHosts = (org, entry) => [
     workspaceHost(org.slug, entry.key),

package/dist/plan/workspace-sign-in.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, HostingEntry } from '../org.js';
+import { type DeclaredOrg, type HostingEntry } from '../org.js';
 import type { UnmanagedItem } from '../plan.js';
 import { type BrokerEntryInput, type BrokerEntryMcp, type BrokerEntryWant } from './broker-entries.js';
 import type { DraftStep } from './diff.js';

package/dist/plan/workspace-sign-in.js

@@ -1,3 +1,4 @@
+import { signsInBoth, signsInCustomers } from '../org.js';
 import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, entryClientIdScopeKey, } from './agora.js';
 import { BOULE_CLIENT_ID_SCOPE_KEY } from './boule.js';
 import { brokerEntryAppliedScopeKey, entryMcpProjectScopeKey, } from './broker-entries.js';
@@ -5,6 +6,7 @@ import { BROKER_WORKSPACES_DATABASE_ENV, workspacesDatabaseRef, workspacesUrl, }
 import { workspaceHost } from './hostnames.js';
 import { loginHostnameFor } from './login-host.js';
 import { appStepKey } from './platform-diff.js';
+import { liveRegisteredClientIds, registeredAppEnv } from './registered-app-env.js';
 import { TEST_CUSTOMERS_SIGN_IN_SCOPE_KEY, TEST_CUSTOMERS_SIGN_UP_SCOPE_KEY, testCustomersEntries, testCustomersOrgKey, workspaceAuthEntries, workspaceClientKey, } from './workspace-client.js';
 /**
  * The sign-in of a server workspace (`HostingEntry.workspace` with `uses.auth`), so the team and invited testers
@@ -49,7 +51,27 @@ export function workspaceAuthEnv(org, entry, recorded, issuer) {
     const auth = entry.uses?.auth;
     if (!auth)
         return null;
-    const organizationId = auth.users === 'customers' ? recorded[testCustomersOrgKey(org.id)] : recorded.zitadel_org;
+    const organizationId = signsInCustomers(auth)
+        ? recorded[testCustomersOrgKey(org.id)]
+        : recorded.zitadel_org;
+    if (signsInBoth(auth)) {
+        // ADR 0003: the broker makes the workspace's two clients when it is registered, after the stage exists, so the
+        // stage first runs with the organisation and the issuer alone; the registration step adds the rest.
+        if (!organizationId || !issuer)
+            return null;
+        const registered = registeredAppEnv(recorded, workspaceClientKey(entry.key));
+        return {
+            AUTH_ORGANIZATION_ID: organizationId,
+            ...(registered ? { AUTH_CLIENT_ID: registered.AUTH_CLIENT_ID } : {}),
+            AUTH_ISSUER: issuer,
+            ...(registered
+                ? {
+                    AUTH_TEAM_CLIENT_ID: registered.AUTH_TEAM_CLIENT_ID,
+                    AUTH_TEAM_ORGANIZATION_ID: registered.AUTH_TEAM_ORGANIZATION_ID,
+                }
+                : {}),
+        };
+    }
     const clientId = recorded[entryClientIdScopeKey(workspaceClientKey(entry.key))];
     if (!organizationId || !clientId || !issuer)
         return null;
@@ -82,12 +104,16 @@ const SHARED_CLIENT_KEYS = new Set([
  */
 export function liveClientIds(org, recorded) {
     const own = new Set(workspaceAuthEntries(org).map((e) => entryClientIdScopeKey(workspaceClientKey(e.key))));
-    return Object.entries(recorded)
+    const recordedIds = Object.entries(recorded)
         .filter(([key, id]) => Boolean(id) &&
         (SHARED_CLIENT_KEYS.has(key) ||
             (key.startsWith(ENTRY_CLIENT_ID_SCOPE_PREFIX) && !own.has(key))))
-        .map(([, id]) => id)
-        .sort();
+        .map(([, id]) => id);
+    // The clients the broker made for the live copies of the entries both sign in to (ADR 0003).
+    const registered = liveRegisteredClientIds(org, recorded);
+    return [
+        ...new Set([...recordedIds, ...registered.clientIds, ...registered.teamClientIds]),
+    ].sort();
 }
 /** What `ws.<key>.signin` records: the sign-in env above as JSON, or `null` while it is not all known. */
 export function workspaceSignInMarker(org, entry, recorded, issuer) {
@@ -154,6 +180,9 @@ export function planTestCustomers(org, live, claimed, recordedIds, metadataWired
 export function planWorkspaceClients(org, byKey, claimed) {
     const steps = [];
     for (const entry of workspaceAuthEntries(org)) {
+        // The broker makes the clients of a workspace both sign in to (ADR 0003).
+        if (signsInBoth(entry.uses?.auth))
+            continue;
         const client = workspaceClientKey(entry.key);
         const key = resourceKey('zitadel', 'app', client);
         if (byKey.has(key)) {
@@ -177,12 +206,14 @@ export function wantedWorkspaceBrokerEntry(org, entry, recorded) {
     if (!auth)
         return { missing: [] };
     const client = workspaceClientKey(entry.key);
-    const organizationId = auth.users === 'customers' ? recorded[testCustomersOrgKey(org.id)] : recorded.zitadel_org;
+    const organizationId = signsInCustomers(auth)
+        ? recorded[testCustomersOrgKey(org.id)]
+        : recorded.zitadel_org;
     const clientId = recorded[entryClientIdScopeKey(client)];
     const mailDomain = recorded.mail_domain;
     const missing = [];
     if (!organizationId) {
-        missing.push(auth.users === 'customers'
+        missing.push(signsInCustomers(auth)
             ? { what: 'the test customers organisation id', producedBy: ['zitadel', 'customers-test'] }
             : { what: "the org's ZITADEL org id", producedBy: ['zitadel', 'issuer'] });
     }
@@ -228,7 +259,8 @@ export function planWorkspaceBrokerEntries(org, recordedIds, plannedSteps, broke
     const blocked = [];
     for (const entry of workspaceAuthEntries(org)) {
         const auth = entry.uses?.auth;
-        if (!auth)
+        // A workspace both sign in to is registered (`registered-app.ts`), not an `AUTH_APPS` entry.
+        if (!auth || signsInBoth(auth))
             continue;
         const at = `${org.slug}'s ${entry.key} workspace broker entry`;
         const key = `coolify:workspace-broker-entry:${entry.key}`;

package/dist/platform.d.ts

@@ -87,6 +87,29 @@ export interface PlatformUsageTailWorker {
 }
 /** Where edge publishes the Worker script for `tag` (the host's `fetchArtifact` fetches it). */
 export declare function usageTailArtifactUrl(tag: string): string;
+/**
+ * foundry#1133: the app-layer canary, a tiny Worker app on the layer every
+ * company's managed app runs on (`canary.companyincluded.app`, edge's Worker
+ * routes in the platform zone). Archon's uptime Worker probes `GET /` on the
+ * hostname foundry records (`platform_app_canary_hostname`, archon#812). The
+ * source ships in this package (`app-canary-worker.ts`); the same
+ * `tag`/`sha256` pin {@link PlatformUsageTailWorker} uses, and both empty
+ * means nothing is pinned yet, so the planner reports that instead of
+ * planning the step. Absent is off.
+ */
+export interface PlatformAppCanary {
+    enabled: boolean;
+    /** A tag such as `appCanaryShippedPin().tag`, `v0-<12 hex>`. */
+    tag: string;
+    /** Lower-case hex SHA-256 of `app-canary-worker.js` (`APP_CANARY_WORKER_SHA256`). */
+    sha256: string;
+}
+/**
+ * The URL the canary's pin names at the `fetchArtifact(url, sha256)` boundary.
+ * Nothing is published there: a host serves the bytes from the package with
+ * `fetchAppCanaryArtifact`, the way Archon serves its uptime Worker from its image.
+ */
+export declare function appCanaryArtifactUrl(tag: string): string;
 /**
  * The shared services a declared platform names, decided in #165, plus
  * `edge` (#317, F7): the service that mints an entry's own edge key and
@@ -160,6 +183,8 @@ export interface DeclaredPlatform {
     uptime: PlatformUptimeWorker;
     /** foundry#1024: the usage tail Worker; see {@link PlatformUsageTailWorker}. */
     usageTail: PlatformUsageTailWorker;
+    /** foundry#1133: the app-layer canary; see {@link PlatformAppCanary}. Absent is off. */
+    appCanary?: PlatformAppCanary;
     /**
      * foundry#544: which Healthchecks instance manages the heartbeat checks
      * for every piece of scheduled work foundry sets up (the uptime Worker,

package/dist/platform.js

@@ -8,6 +8,14 @@ export function uptimeArtifactUrl(tag) {
 export function usageTailArtifactUrl(tag) {
     return `https://github.com/wtfalch/edge/releases/download/${tag}/usage-tail-worker.js`;
 }
+/**
+ * The URL the canary's pin names at the `fetchArtifact(url, sha256)` boundary.
+ * Nothing is published there: a host serves the bytes from the package with
+ * `fetchAppCanaryArtifact`, the way Archon serves its uptime Worker from its image.
+ */
+export function appCanaryArtifactUrl(tag) {
+    return `https://github.com/wtfalch/foundry/releases/download/${tag}/app-canary-worker.js`;
+}
 export const PLATFORM_SERVICE_KEYS = [
     'auth',
     'mail',
@@ -101,6 +109,18 @@ export function validatePlatform(platform) {
     if (usageTail.sha256 && !/^[0-9a-f]{64}$/.test(usageTail.sha256)) {
         return 'usageTail.sha256 must be 64 lower-case hex characters';
     }
+    if (platform.appCanary) {
+        const { appCanary } = platform;
+        if (Boolean(appCanary.tag.trim()) !== Boolean(appCanary.sha256.trim())) {
+            return 'appCanary.tag and appCanary.sha256 must be set together: a pin is both';
+        }
+        if (appCanary.tag && !/^v[0-9A-Za-z][0-9A-Za-z.+_-]*$/.test(appCanary.tag)) {
+            return `appCanary.tag '${appCanary.tag}' must be a release tag such as v1.2.3`;
+        }
+        if (appCanary.sha256 && !/^[0-9a-f]{64}$/.test(appCanary.sha256)) {
+            return 'appCanary.sha256 must be 64 lower-case hex characters';
+        }
+    }
     // #491: declared, never discovered -- a present-but-blank id is refused the
     // same way `serverIpv4`'s blank string is, rather than being read as unset.
     if (platform.mail.lettermintProjectId != null && !platform.mail.lettermintProjectId.trim()) {

package/dist/service-labels.d.ts

@@ -2,3 +2,11 @@
 export declare const OWN_SERVICE_LABELS: readonly ["auth", "mail", "files", "sfu"];
 /** The first label of every name foundry itself serves for a company: its own services, Agora, Boule, the cms studio, calls, the sign-in host and file shares. */
 export declare const FOUNDRY_SERVICE_LABELS: ReadonlySet<string>;
+/**
+ * foundry#1133: first labels the platform serves on the apps zone
+ * (`<label>.companyincluded.app`) itself, so no company may take one as an app
+ * address: the app-layer canary Archon's uptime probes (`canary`) and its
+ * Worker's name (`uptime-canary`). Kept equal to `PLATFORM_APP_CANARY_LABEL`
+ * and `PLATFORM_APP_CANARY_SCRIPT_NAME` by `app-canary.test.ts`.
+ */
+export declare const PLATFORM_APP_LABELS: ReadonlySet<string>;

package/dist/service-labels.js

@@ -9,3 +9,11 @@ export const FOUNDRY_SERVICE_LABELS = new Set([
     'calls',
     'share',
 ]);
+/**
+ * foundry#1133: first labels the platform serves on the apps zone
+ * (`<label>.companyincluded.app`) itself, so no company may take one as an app
+ * address: the app-layer canary Archon's uptime probes (`canary`) and its
+ * Worker's name (`uptime-canary`). Kept equal to `PLATFORM_APP_CANARY_LABEL`
+ * and `PLATFORM_APP_CANARY_SCRIPT_NAME` by `app-canary.test.ts`.
+ */
+export const PLATFORM_APP_LABELS = new Set(['canary', 'uptime-canary']);

package/dist/slug.d.ts

@@ -2,7 +2,7 @@
 export declare const RESERVED_SLUGS: ReadonlySet<string>;
 /** Every platform app, tunnel, project and database name starts `platform-`, so no company slug may. */
 export declare const RESERVED_SLUG_PREFIX = "platform-";
-/** Whether `label` ends in a suffix reserved for another org's own hostname (`-stage`, `-pr-<n>`, `-calls`, `-agora`, `-boule`, `-kosmos`, `-analytics`, `-auth`, `-mail`, `-files`, `-sfu`, `-cms`). */
+/** Whether `label` ends in a suffix reserved for another org's own hostname (`-stage`, `-pr-<n>`, `-calls`, `-agora`, `-boule`, `-kosmos`, `-analytics`, `-reporting`, `-auth`, `-mail`, `-files`, `-sfu`, `-cms`). */
 export declare function hasBarredSlugSuffix(label: string): boolean;
 /**
  * Why {@link validateSlug} refused a candidate slug, by name so a caller —

package/dist/slug.js

@@ -148,6 +148,8 @@ const BOULE_SUFFIX = /-boule$/;
 const KOSMOS_SUFFIX = /-kosmos$/;
 /** `<something>-analytics` — a level-1 org's own analytics backend hostname (`<slug>-analytics.oikos.host`, foundry#724). Reserved always, so a company that turns analytics on later never finds the name taken. */
 const ANALYTICS_SUFFIX = /-analytics$/;
+/** `<something>-reporting` — a level-1 org's own reporting backend hostname (`<slug>-reporting.oikos.host`, wtfalch/reporting ADR 0002). Reserved always, as {@link ANALYTICS_SUFFIX} is. */
+const REPORTING_SUFFIX = /-reporting$/;
 /** `<something>-auth|-mail|-files|-sfu|-cms` — an own company's service hostnames on oikos.host (`plan/own-hostnames.ts`). */
 const OWN_SERVICE_SUFFIX = /-(auth|mail|files|sfu|cms)$/;
 /**
@@ -161,7 +163,7 @@ const OWN_SERVICE_SUFFIX = /-(auth|mail|files|sfu|cms)$/;
  * `names-`.
  */
 const NAMES_PREFIX = /^names(-|$)/;
-/** Whether `label` ends in a suffix reserved for another org's own hostname (`-stage`, `-pr-<n>`, `-calls`, `-agora`, `-boule`, `-kosmos`, `-analytics`, `-auth`, `-mail`, `-files`, `-sfu`, `-cms`). */
+/** Whether `label` ends in a suffix reserved for another org's own hostname (`-stage`, `-pr-<n>`, `-calls`, `-agora`, `-boule`, `-kosmos`, `-analytics`, `-reporting`, `-auth`, `-mail`, `-files`, `-sfu`, `-cms`). */
 export function hasBarredSlugSuffix(label) {
     return (STAGE_SUFFIX.test(label) ||
         PR_SUFFIX.test(label) ||
@@ -170,6 +172,7 @@ export function hasBarredSlugSuffix(label) {
         BOULE_SUFFIX.test(label) ||
         KOSMOS_SUFFIX.test(label) ||
         ANALYTICS_SUFFIX.test(label) ||
+        REPORTING_SUFFIX.test(label) ||
         OWN_SERVICE_SUFFIX.test(label));
 }
 /**
@@ -201,7 +204,7 @@ export function validateSlug(slug) {
     if (hasBarredSlugSuffix(slug)) {
         return {
             reason: 'environment-suffix',
-            message: `slug '${slug}' ends with an environment suffix ('-stage', '-pr-<digits>', '-calls', '-agora', '-boule', '-kosmos', '-analytics', '-auth', '-mail', '-files', '-sfu' or '-cms') reserved for another org's own hostname (#28, #145, #164, #161, #949) — 'acme-calls' is only legal as acme's calls hostname, 'acme-agora' only as acme's Agora hostname, 'acme-boule' only as acme's Boule hostname, 'acme-kosmos' only as acme's kosmos hostname, never as an org slug in its own right`,
+            message: `slug '${slug}' ends with an environment suffix ('-stage', '-pr-<digits>', '-calls', '-agora', '-boule', '-kosmos', '-analytics', '-reporting', '-auth', '-mail', '-files', '-sfu' or '-cms') reserved for another org's own hostname (#28, #145, #164, #161, #949) — 'acme-calls' is only legal as acme's calls hostname, 'acme-agora' only as acme's Agora hostname, 'acme-boule' only as acme's Boule hostname, 'acme-kosmos' only as acme's kosmos hostname, never as an org slug in its own right`,
         };
     }
     return null;

package/dist/store/postgres.js

@@ -820,6 +820,16 @@ function rowToPlatform(row) {
             tag: row.usageTailTag,
             sha256: row.usageTailSha256,
         },
+        // Absent while off and unpinned, the way an older platform was declared.
+        ...(row.appCanaryEnabled || row.appCanaryTag || row.appCanarySha256
+            ? {
+                appCanary: {
+                    enabled: row.appCanaryEnabled,
+                    tag: row.appCanaryTag,
+                    sha256: row.appCanarySha256,
+                },
+            }
+            : {}),
         heartbeatsProvider: row.heartbeatsProvider,
     };
 }
@@ -875,6 +885,9 @@ function platformToRow(platform) {
         usageTailEnabled: platform.usageTail.enabled,
         usageTailTag: platform.usageTail.tag,
         usageTailSha256: platform.usageTail.sha256,
+        appCanaryEnabled: platform.appCanary?.enabled ?? false,
+        appCanaryTag: platform.appCanary?.tag ?? '',
+        appCanarySha256: platform.appCanary?.sha256 ?? '',
         heartbeatsProvider: platform.heartbeatsProvider,
     };
 }