@wtfalch/foundry 0.76.0 → 0.77.0

package/dist/plan/entry-reporting-key.d.ts

@@ -0,0 +1,36 @@
+import type { DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * `uses.reporting` on a server entry: one site key of its own at the company's reporting backend, minted
+ * through `POST /v1/site-keys` with the operator key (site = the entry key, environment `production`; Boule
+ * reads an app's errors with site = the app key) and written as `REPORTING_URL` and `REPORTING_SITE_KEY` to
+ * the entry's env. The backend shows the secret once, so this follows rule 1 of CLAUDE.md "Platform steps":
+ *
+ * 1. the key's id is recorded as `reporting_key_undelivered.<entry>` and persisted before the env is written;
+ * 2. the env write is tried 3 times with the same secret; the id is the main id `reporting:key:<orgId>:<entry>`
+ *    and the applied marker only after it worked, and the undelivered marker is cleared then;
+ * 3. a marker left behind (every try failed) is reported blocked and never minted again.
+ *
+ * A Worker app entry is skipped: Boule installs its keys per copy. The entry's stage gets its own key through
+ * `plan/stage-services.ts` (service `reporting`, environment `stage`), so the two differ. Removing
+ * `uses.reporting` or the entry plans the retire form: revoke the key, take both env names away.
+ */
+export declare const entryReportingUndeliveredScopeKey: (entryKey: string) => string;
+/** The address the entry's env was last written with; a change rewrites the address only. */
+export declare const entryReportingAppliedScopeKey: (entryKey: string) => string;
+/** The id of a key that was revoked, so a stale main id is not revoked again. */
+export declare const entryReportingRetiredScopeKey: (entryKey: string) => string;
+export declare const ENTRY_REPORTING_KEY_DELIVERY_ATTEMPTS = 3;
+/** The name the backend knows the key by. The site is sent as well (the entry key), so it never derives from the name. */
+export declare const entryReportingKeyName: (org: Pick<DeclaredOrg, "slug">, entryKey: string) => string;
+/** The stage copy's key name; its site is the entry key too, and its environment `stage`. */
+export declare const stageReportingKeyName: (org: Pick<DeclaredOrg, "slug">, entryKey: string) => string;
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+export declare function planEntryReportingKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], reportingPort: boolean): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+export {};

package/dist/plan/entry-reporting-key.js

@@ -0,0 +1,136 @@
+import { appStepKey } from './platform-diff.js';
+import { reportingUrlFor } from './reporting.js';
+/**
+ * `uses.reporting` on a server entry: one site key of its own at the company's reporting backend, minted
+ * through `POST /v1/site-keys` with the operator key (site = the entry key, environment `production`; Boule
+ * reads an app's errors with site = the app key) and written as `REPORTING_URL` and `REPORTING_SITE_KEY` to
+ * the entry's env. The backend shows the secret once, so this follows rule 1 of CLAUDE.md "Platform steps":
+ *
+ * 1. the key's id is recorded as `reporting_key_undelivered.<entry>` and persisted before the env is written;
+ * 2. the env write is tried 3 times with the same secret; the id is the main id `reporting:key:<orgId>:<entry>`
+ *    and the applied marker only after it worked, and the undelivered marker is cleared then;
+ * 3. a marker left behind (every try failed) is reported blocked and never minted again.
+ *
+ * A Worker app entry is skipped: Boule installs its keys per copy. The entry's stage gets its own key through
+ * `plan/stage-services.ts` (service `reporting`, environment `stage`), so the two differ. Removing
+ * `uses.reporting` or the entry plans the retire form: revoke the key, take both env names away.
+ */
+export const entryReportingUndeliveredScopeKey = (entryKey) => `reporting_key_undelivered.${entryKey}`;
+/** The address the entry's env was last written with; a change rewrites the address only. */
+export const entryReportingAppliedScopeKey = (entryKey) => `reporting_key_applied.${entryKey}`;
+/** The id of a key that was revoked, so a stale main id is not revoked again. */
+export const entryReportingRetiredScopeKey = (entryKey) => `reporting_key_retired.${entryKey}`;
+export const ENTRY_REPORTING_KEY_DELIVERY_ATTEMPTS = 3;
+/** The name the backend knows the key by. The site is sent as well (the entry key), so it never derives from the name. */
+export const entryReportingKeyName = (org, entryKey) => `${org.slug}-${entryKey}-reporting`;
+/** The stage copy's key name; its site is the entry key too, and its environment `stage`. */
+export const stageReportingKeyName = (org, entryKey) => `${org.slug}-${entryKey}-stage-reporting`;
+const servesKey = (entry) => entry.uses?.reporting === true && !entry.workerApp && entry.live !== false;
+export function planEntryReportingKeys(org, recordedIds, plannedSteps, reportingPort) {
+    const steps = [];
+    const blocked = [];
+    if (!org.hosting.enabled)
+        return { steps, blocked };
+    const planned = (system, kind, key) => plannedSteps.some((p) => p.action.system === system && p.action.kind === kind && p.action.key === key);
+    const wanted = new Map(org.hosting.entries.filter(servesKey).map((e) => [e.key, e]));
+    const mainPrefix = `reporting:key:${org.id}:`;
+    // Keys whose entry stopped using reporting or is gone: a delivered key (main id) or one minted and never
+    // delivered (undelivered marker), so the retire clears the marker and the entry can mint again later.
+    const undeliveredPrefix = entryReportingUndeliveredScopeKey('');
+    const retiring = new Set();
+    for (const [name, id] of Object.entries(recordedIds)) {
+        if (!id)
+            continue;
+        const prefix = name.startsWith(mainPrefix)
+            ? mainPrefix
+            : name.startsWith(undeliveredPrefix)
+                ? undeliveredPrefix
+                : null;
+        if (!prefix)
+            continue;
+        const entryKey = name.slice(prefix.length);
+        if (wanted.has(entryKey) ||
+            retiring.has(entryKey) ||
+            recordedIds[entryReportingRetiredScopeKey(entryKey)] === id) {
+            continue;
+        }
+        retiring.add(entryKey);
+        const key = `${mainPrefix}${entryKey}`;
+        if (!reportingPort) {
+            blocked.push({
+                description: `${org.slug}'s ${entryKey} reporting key is not revoked, not planned: the host supplies no reporting port`,
+                key,
+            });
+        }
+        else if (!recordedIds[`coolify:reporting:${org.id}`]) {
+            blocked.push({
+                description: `${org.slug}'s ${entryKey} reporting key is not revoked, not planned: the reporting backend is not recorded`,
+                key,
+            });
+        }
+        else {
+            steps.push({
+                action: {
+                    system: 'reporting',
+                    kind: 'key',
+                    key: `${org.id}:${entryKey}`,
+                    desired: { mode: 'retire' },
+                },
+                step: {
+                    description: `revoke ${org.slug}'s ${entryKey} reporting key and take REPORTING_* out of its env: the entry no longer uses reporting`,
+                    destroys: true,
+                    migrates: false,
+                },
+            });
+        }
+    }
+    for (const entry of wanted.values()) {
+        const stepKey = appStepKey(org, entry.key);
+        const key = `reporting:key:${stepKey}`;
+        const at = `${org.slug}'s ${entry.key} reporting key`;
+        const block = (why) => blocked.push({ description: `${at} is blocked: ${why}`, key });
+        const url = reportingUrlFor(org);
+        const undelivered = recordedIds[entryReportingUndeliveredScopeKey(entry.key)];
+        if (undelivered) {
+            block(`key ${undelivered} was minted but never written to the app, and the backend shows a key once; remove the recorded id ${entryReportingUndeliveredScopeKey(entry.key)} to mint a new key, which replaces that one`);
+            continue;
+        }
+        const live = recordedIds[key] &&
+            recordedIds[entryReportingRetiredScopeKey(entry.key)] !== recordedIds[key];
+        if (live && recordedIds[entryReportingAppliedScopeKey(entry.key)] === url)
+            continue;
+        if (!reportingPort) {
+            block('the host supplies no reporting port');
+            continue;
+        }
+        if (!recordedIds[`coolify:reporting:${org.id}`] && !planned('coolify', 'reporting', org.id)) {
+            block("the company's reporting backend is not recorded or planned yet");
+            continue;
+        }
+        if (!recordedIds[`coolify:app:${stepKey}`] && !planned('coolify', 'app', stepKey)) {
+            block("the entry's app is not recorded yet");
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'reporting',
+                kind: 'key',
+                key: stepKey,
+                desired: {
+                    mode: live ? 'url' : 'mint',
+                    name: entryReportingKeyName(org, entry.key),
+                    site: entry.key,
+                    reportingUrl: url,
+                },
+            },
+            step: {
+                description: live
+                    ? `write the reporting address to ${org.slug}'s ${entry.key} env`
+                    : `mint ${at}, write REPORTING_URL and REPORTING_SITE_KEY to its env, restart the app`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}

package/dist/plan/executor.d.ts

@@ -22,7 +22,9 @@ import { type OwnServicesPort } from './own-services.js';
 import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
 import type { EdgePortName } from './platform-org.js';
 import type { RequestHeaderPort } from './platform-providers.js';
+import { type RegistrarApiPort } from './registered-app.js';
 import { type ReleaseContext, type ReleaseHost } from './release-host.js';
+import { type ReportingPort } from './reporting.js';
 import { type StageCopyHostConfig } from './stage-copy-host.js';
 import { type ReleasePreviewMembers, type StageProbePort } from './stage-guards.js';
 import type { WorkerAppDatabasePort } from './worker-app-database.js';
@@ -1547,6 +1549,15 @@ export interface AiOrganisationPort {
         name: string;
         expiresDays: number;
         permissions: string[];
+        /**
+         * foundry#1122 (ai#190 `MintKey.app`): the app and copy the key's runs belong to, fixed for the key's life.
+         * An entry's key passes its entry key and `live`; Boule's key passes none. A host adapter passes it on to
+         * `POST /v1/keys` as `app`.
+         */
+        app?: {
+            key: string;
+            copy: 'live' | 'work';
+        };
     }): Promise<{
         organisationId: string;
         id: string;
@@ -1709,6 +1720,20 @@ export interface JobsSchedulerPort {
      * stage's own project (`<org>-stage`); a port without it leaves that project, which destroy then reports as blocked.
      */
     deleteProject?(name: string): Promise<void>;
+    /**
+     * foundry#1119: mints a key for one project (`POST /admin/projects/<name>/keys` with `{ principal, scopes }`,
+     * jobs#79), shown once with its id. Optional: a host without it (and without `revokeProjectKey`) leaves
+     * `FoundryPlanApplyOptions.jobsProjectKeys` false, and each entry's Boule key is reported blocked.
+     */
+    mintProjectKey?(project: string, grant: {
+        principal: string;
+        scopes: readonly string[];
+    }): Promise<{
+        id: string;
+        key: string;
+    }>;
+    /** Revokes one project key (`DELETE /admin/projects/<name>/keys/<id>`); an unknown key throws with `status: 404`. */
+    revokeProjectKey?(project: string, keyId: string): Promise<void>;
 }
 /**
  * #177: where the org steps' files, AI and jobs ports come from when the host
@@ -1865,6 +1890,12 @@ export interface FoundryStepExecutorPorts {
      * `FoundryPlanApplyOptions.broker`).
      */
     broker?: BrokerPort;
+    /**
+     * ADR 0003: the company's registrar at the sign-in broker, through which an entry whose customers and team
+     * both sign in is registered (`coolify:registered-app`). Optional: without it (and
+     * `FoundryPlanApplyOptions.registrarApi`) such an entry is reported blocked. `httpRegistrarApi()` is the real one.
+     */
+    registrarApi?: RegistrarApiPort;
     /**
      * #318: deploys and routes an entry's `worker` Worker -- see
      * {@link WorkersPort}'s own doc comment. Optional the same way `broker` is:
@@ -1885,6 +1916,8 @@ export interface FoundryStepExecutorPorts {
     keysRegistrar?: KeysRegistrarPort;
     /** The company's analytics backend operator API: mints and revokes site keys. Without it the plan reports each `uses.analytics` key blocked (the host also sets `FoundryPlanApplyOptions.analyticsPort`). */
     analytics?: AnalyticsPort;
+    /** The company's reporting backend operator API: mints and revokes site keys. Without it the plan reports each `uses.reporting` key blocked (the host also sets `FoundryPlanApplyOptions.reportingPort`). */
+    reporting?: ReportingPort;
     /**
      * C3: mints the credential an org's Boule reaches Archon with (org-scoped; `orgs:request` and
      * `orgs:read` for that org). Archon implements it. Every call rotates the credential (the old secret
@@ -2068,6 +2101,13 @@ export declare const KOSMOS_PORT = 3000;
 export declare const ANALYTICS_REPO = "wtfalch/analytics";
 export declare const ANALYTICS_APP_DOCKERFILE = "/Dockerfile";
 export declare const ANALYTICS_PORT = 3000;
+/**
+ * The company's reporting backend (https://github.com/wtfalch/reporting, `apps/host`): root Dockerfile, serves
+ * on 3000 and answers `/api/health`, migrates in its own start script, as the analytics host does.
+ */
+export declare const REPORTING_REPO = "wtfalch/reporting";
+export declare const REPORTING_APP_DOCKERFILE = "/Dockerfile";
+export declare const REPORTING_PORT = 3000;
 export declare const LOG_DIR = "/app/logs";
 /** The company's Coolify destination (its Docker network `co-<slug>`), recorded when its first resource is created. */
 export declare const COOLIFY_DESTINATION_SCOPE_KEY = "coolify_destination";
@@ -2606,6 +2646,16 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * key. It never reads or writes the live entry. Records what it wrote, never a key.
      */
     private coolifyWorkspaceBrokerEntry;
+    /**
+     * `coolify:registered-app` (`plan/registered-app.ts`, ADR 0003): one copy of an entry whose customers and team
+     * both sign in, registered at the sign-in broker through the company's registrar with
+     * `users: ['customers', 'staff']`. The answer (the customers' and the team's clients, both organisations and a
+     * new `AUTH_APP_KEY`) goes to the copy's app (the entry's app, or the workspace's stage), which restarts. The
+     * ids are recorded after the env is written, the want last, so a failure anywhere registers again on the next
+     * apply (the broker keeps the key it replaced valid for a window). The registrar key and the app key are
+     * registered for redaction and never recorded; errors name the copy and a status at most.
+     */
+    private coolifyRegisteredApp;
     /**
      * `coolify:workspaces-database` (`plan/broker-workspaces-database.ts`): the broker's workspaces database, made
      * beside the broker (the platform's project and network, or the company's own for an org that owns its services)
@@ -2807,6 +2857,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * provisioned, where this one is unconditional (#239).
      */
     private pushAppEnv;
+    /**
+     * #1116: takes a module setting's env name (`MAIL_REPLY_TO`, ...) out of the app's env once the setting is
+     * unset or its module is off. Only a name the last applied env wrote (the recorded marker) and the entry's
+     * own `env` does not declare, so a value the company set by hand stays.
+     */
+    private dropUnsetSettingsEnv;
     /** Takes `AUTH_EVENTS_SECRET` out of the app's env once the entry stops declaring events. The held value stays: the held store has no delete. */
     private dropAuthEventsEnv;
     /**
@@ -3516,7 +3572,9 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      *
      * `ANALYTICS_OPERATOR_KEY` is made once here (`mintIfAbsent`) and written only to this app's env. No outside
      * service shows it once, so no undelivered marker is needed: a failed write leaves nothing live to mint twice.
-     * Steps that call the backend's operator API read it back from this env.
+     * Steps that call the backend's operator API read it back from this env. `ANALYTICS_PERSON_KEY` (64 hex
+     * characters, analytics#109: the per-site key that counts a signed-in person once) is made the same way and
+     * never rotated: a value already in the env, made here or by hand, is kept.
      *
      * A brand new app is deployed once ({@link ANALYTICS_DEPLOYED_SCOPE_KEY}), as for Boule (#504).
      */
@@ -3536,6 +3594,35 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * env names. The operator key is read from the backend's env and never recorded.
      */
     private analyticsEntryKey;
+    /**
+     * `plan/diff.ts`'s `planReportingBackend`: the company's reporting backend as one more Coolify application
+     * from https://github.com/wtfalch/reporting's root Dockerfile ({@link REPORTING_REPO}), with a database of its
+     * own, a copy of {@link coolifyAnalytics}. Its start script migrates as the owner role and then serves as the
+     * runtime role, so `pushDatabaseUrl` gives it both URLs. It needs no sign-in client: it reads only
+     * `AUTH_ORGANIZATION_ID` (the tenant id derives from it), `APP_URL` and the operator key.
+     *
+     * `REPORTING_OPERATOR_KEY` is made once here (`mintIfAbsent`) and written only to this app's env. No outside
+     * service shows it once, so no undelivered marker is needed: a failed write leaves nothing live to mint twice.
+     * Steps that call the backend's operator API read it back from this env.
+     *
+     * A brand new app is deployed once ({@link REPORTING_DEPLOYED_SCOPE_KEY}), as for Boule (#504).
+     */
+    private coolifyReporting;
+    /** The backend's operator key, read from its own env. Fixed text when the backend or the key is not there. */
+    private reportingOperatorKey;
+    /**
+     * `coolify:reporting-boule` (`plan/reporting-boule.ts`): the backend's address and operator key into
+     * Boule's env, then Boule restarts. `reporting_boule_applied` is recorded last. Retire takes both names away.
+     */
+    private reportingBoule;
+    /**
+     * `plan/entry-reporting-key.ts`: one server entry's site key (CLAUDE.md "Platform steps" rule 1). Mint: the
+     * key's id is recorded as undelivered and persisted before anything is written; the env write is tried 3
+     * times with the same secret; the applied address and the cleared marker come last; every try failing leaves
+     * the marker, and the error names the id only. `url` rewrites the address. Retire revokes the key and the
+     * env names. The operator key is read from the backend's env and never recorded.
+     */
+    private reportingEntryKey;
     /**
      * `plan/diff.ts`'s `planKosmos`: provisions the org's own kosmos
      * (https://github.com/wtfalch/kosmos) as one more Coolify application, from
@@ -3629,6 +3716,9 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * Boule's env. Returns whether Boule's token changed, so the caller
      * restarts a running Boule, unless `restarted`: the shared rule then already
      * restarted it (`running`), before it deleted the old project.
+     *
+     * The company's reporting backend (foundry#1128) takes its token the same
+     * way, as `role: 'reporting'`. The token is registered for redaction.
      */
     private ensureBouleMail;
     /**
@@ -3758,6 +3848,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * retried. Errors name the project and the refs, never a credential.
      */
     private jobsProject;
+    /**
+     * foundry#1119, `plan/entry-jobs-boule-key.ts`: Boule's key for one entry's jobs project, minted under rule 1,
+     * held, and written to Boule's `JOBS_PROJECTS`; or, in the retire form, revoked and taken out. See
+     * `entry-jobs-boule-key-apply.ts`.
+     */
+    private jobsBouleKey;
     /** `plan/entry-audit.ts`: makes the platform signer if none exists and registers one entry's ledger for sealing. */
     private auditLedger;
     /** F12, `plan/entry-repo-key.ts`: makes or removes one entry's deploy key. See `entry-repo-key-apply.ts`. */
@@ -4145,6 +4241,11 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * errors name ids, never the cause, which can echo one.
      */
     private aiEntryKey;
+    /**
+     * foundry#1122, `plan/ai-boule-key.ts`: Boule's ai key, minted below the org's own ai key under rule 1, held,
+     * and written to Boule's `AI_URL`, `AI_ORGANISATION_ID` and `AI_API_KEY`. See `ai-boule-key-apply.ts`.
+     */
+    private aiBouleKey;
     /**
      * REVOKE SEAM (ai#157): revokes through `revokeKey` when the port has one.
      * Without it, or when it fails, the id joins the entry's list of keys left
@@ -4208,6 +4309,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * minting nothing. A secret reaches `bulkUpsertEnvs` and nothing else.
      */
     private filesEntryKey;
+    /**
+     * foundry#1121, `plan/files-boule-key.ts`: Boule's files key, minted below the org's own files key under rule
+     * 1, held, and written to Boule's `FILES_BOULE_KEYS`; or, in the retire form, revoked and taken out. See
+     * `files-boule-key-apply.ts`.
+     */
+    private filesBouleKey;
     /**
      * Revokes one entry key. When the call fails the id joins the entry's list
      * of keys left live, which the plan shows, and the step goes on: the app