@wtfalch/foundry 0.5.0 → 0.6.0

package/dist/plan/platform-providers.d.ts

@@ -18,7 +18,7 @@ export interface PlatformAuthDeps {
     /** #197: fetches the tunnel's connector token for {@link ensureCloudflaredConnector}. */
      | 'getTunnelToken'>;
     /** Must target the platform's own new instance (its issuer), or `zitadelForInstance` must be set. */
-    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser'>;
+    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats'>;
     /**
      * Builds the ZITADEL port for the new instance from its issuer URL
      * (`https://<auth.hostname>`). When set it is used instead of
@@ -134,6 +134,9 @@ export interface FoundryPlatformStepExecutorOptions {
  * optional: an existing host that constructs this executor for the zone step
  * alone keeps compiling, and a plan that includes an `sfu:livekit` step
  * without it configured refuses clearly rather than silently doing nothing.
+ * #152: the step mints one LiveKit key per org with calls enabled rather
+ * than one shared pair, so it also needs `declaredOrgStore.list()` -- the
+ * same store this class already takes for `findOrgIdForZone`.
  *
  * #168 adds `coolify:app` keyed {@link PLATFORM_AUTH_KEY}, the platform's own
  * sign-in ({@link provisionPlatformAuth}), once a host passes
@@ -169,23 +172,41 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private readonly files?;
     private readonly ai?;
     private readonly archon?;
-    constructor(cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'createZone'>, declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone'>, options?: FoundryPlatformStepExecutorOptions);
+    constructor(cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'createZone'>, declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone' | 'list'>, options?: FoundryPlatformStepExecutorOptions);
     blockedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
         auth?: string;
+        authExecutorMissing?: boolean;
+        authOtherInputsMissing?: string[];
         files?: string;
         integrations?: string;
         ai?: string;
         archon?: string;
         mail?: string;
     }>;
-    /** Whether Archon's live Access policy lets through anyone but the declared emails. */
+    /**
+     * Whether Archon's live Access policy lets through anyone but the declared
+     * emails, or (#211 round 4) the broker it last registered with no longer
+     * carries its entry; or (#216 round 4) the platform's recorded
+     * login-client token is no longer the sole live PAT on its ZITADEL machine
+     * user.
+     */
     driftedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
         archon?: boolean;
+        auth?: boolean;
     }>;
     execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
         resourceId?: string;
     } | undefined>;
     private cloudflareZone;
+    /**
+     * #152: the platform `sfu` step owns the shared LiveKit config, so it
+     * lists every org with calls enabled itself -- `DeclaredOrgStore.list()`,
+     * filtered the same way an org's own `calls.enabled` flag gates its
+     * `coolify:calls-service` step (`executor.ts`'s `coolifyCallsService`) --
+     * rather than taking the list as an argument nothing else would supply.
+     * Sorted by slug so a re-run with the same set of enabled orgs is a no-op
+     * even before `applyCallsSfuPlatformStep`'s own sort (its doc comment).
+     */
     private executeSfu;
     private coolifyJobs;
 }
@@ -290,9 +311,31 @@ export interface PlatformArchonDeps {
      * value it returns goes straight to `bulkUpsertEnvs` and nowhere else.
      * Optional so a host without it still compiles; while a service is enabled
      * without it (or without a key it holds) Archon is blocked, not skipped.
+     *
+     * `put` (#213) writes a value under `ref`, once -- see
+     * {@link putArchonMasterKeys}. Also optional, and also blocking: while
+     * {@link masterKeys} is given but this cannot put, Archon is blocked, not
+     * skipped, the same rule.
      */
     heldKeys?: {
         resolve(ref: string): Promise<string | null>;
+        put?(ref: string, value: string): Promise<void>;
+    };
+    /**
+     * #213: the credentials Archon's own onboarding reads back as held keys
+     * before it can start (archon#101 round 3, archon#104) -- the Coolify URL
+     * and token this package already deploys with, and a Cloudflare parent
+     * token with "API Tokens Write" a human creates by hand (#213 "Human
+     * steps"), so Archon can mint its own scoped child token from it. Put
+     * once, under tenant `platform`, before Archon's app deploys
+     * ({@link putArchonMasterKeys}); optional so a host without it still
+     * compiles, and Archon is blocked, not skipped, while it (or
+     * {@link heldKeys}'s `put`) is missing.
+     */
+    masterKeys?: {
+        coolifyUrl: string;
+        coolifyToken: string;
+        cloudflareParentToken: string;
     };
 }
 /**
@@ -306,24 +349,28 @@ export declare const PLATFORM_ZITADEL_ORG_SCOPE_KEY = "zitadel_platform_org";
 /** Archon's OIDC client id: public, not a secret, so a plain scope id. */
 export declare const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = "zitadel_platform_archon_client_id";
 /**
- * #172: mints foundry's AI management key -- the plain bearer key
+ * #172/#201: mints Archon's own AI management key -- the plain bearer key
  * (`wtfk_...`) `AiOrganisationPort` (`executor.ts`) authenticates with,
  * holding {@link PLATFORM_AI_MANAGEMENT_PERMISSIONS} in ai's platform
- * (operator) tenant. The secret comes back once; {@link provisionPlatformAi}
- * hands it to `deliverSecret` and records only the credential id.
+ * (operator) tenant, named `archon` (the key is Archon's; foundry only mints
+ * it while provisioning -- see {@link provisionPlatformAi}). The secret comes
+ * back once; {@link provisionPlatformAi} hands it to `deliverSecret` and
+ * records only the credential id.
  *
- * No implementation ships with this package, because none can be built from
- * it today: see {@link provisionPlatformAi}'s "Known gaps". A host that has
- * a way to run ai's `keys:issue-archon` (or a future HTTP bootstrap route)
- * supplies one; without it the planner reports the step as blocked
- * ({@link PLATFORM_AI_MINTER_BLOCKED}) and plans nothing.
+ * {@link createAiManagementKeyMinter} is the real implementation
+ * {@link provisionPlatformAi} builds by default, signing with the Ed25519
+ * pair it mints and pins on the runner and calling ai's own
+ * `POST /v1/platform/keys` (github.com/wtfalch/ai/issues/141). That route is
+ * idempotent by name: a repeat call with the same permissions and expiry
+ * returns the live key's id with no secret rather than a second key, so
+ * `mintManagementKey` throws {@link AiManagementKeyExistsError} for that
+ * case -- {@link provisionPlatformAi} only ever calls it once there is no
+ * delivered record, so a 200 here means an earlier mint's secret was lost,
+ * never a fresh one to hand back.
  *
- * Requirement: before issuing anything, a minter must look up an existing
- * management key named `foundry` in the platform tenant and return that one
- * instead of issuing a new one. A crash after `mintManagementKey` returns and
- * before the caller records the credential id leaves a live key nobody knows
- * about; only the minter can find it again, so without this lookup the next
- * apply mints a second key.
+ * A test may still inject a different {@link AiManagementKeyMinter} in
+ * {@link PlatformAiDeps.managementKeyMinter}, which skips building the
+ * default one and its signing-key machinery entirely.
  */
 export interface AiManagementKeyMinter {
     mintManagementKey(input: {
@@ -338,12 +385,55 @@ export interface AiManagementKeyMinter {
         secret: string;
     }>;
 }
+/**
+ * Thrown by {@link createAiManagementKeyMinter} (never by a test's own
+ * injected minter, unless it chooses to) when ai's `POST /v1/platform/keys`
+ * answers 200: a live `archon` key already exists and no secret comes back.
+ * See {@link PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY}.
+ */
+export declare class AiManagementKeyExistsError extends Error {
+    readonly credentialId: string;
+    readonly organisationId: string;
+    constructor(credentialId: string, organisationId: string);
+}
+/**
+ * Thrown by {@link createAiManagementKeyMinter} on a 409: a live `archon` key
+ * already exists with different permissions or expiry than this request
+ * asked for. ai never overwrites it, so this is never retried under another
+ * name -- an operator revokes the live key in ai first.
+ */
+export declare class AiManagementKeyConflictError extends Error {
+    constructor();
+}
+/**
+ * Thrown by {@link createAiManagementKeyMinter} on a 401 or 403: ai does not
+ * trust foundry's signing key yet for this request. Most likely the runner
+ * has not redeployed since {@link AI_SIGNING_KEY_REF}'s public half was
+ * pinned as `MANAGEMENT_PUBLIC_KEYS`/`MANAGEMENT_ISSUER` -- a Coolify env
+ * change reaches the container only on its next deploy.
+ */
+export declare class AiManagementKeyUntrustedError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
 /** #172: everything {@link provisionPlatformAi} needs beyond {@link PlatformStepExecutionContext}. */
 export interface PlatformAiDeps {
     coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'raw'>;
     deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
-    /** Optional: see {@link AiManagementKeyMinter}. Absent, the planner blocks the step until the key is delivered. */
+    /**
+     * Reads back a secret this step delivered on an earlier apply -- needed
+     * only to re-sign a mint request when the signing pair was pinned on a
+     * run that crashed before the management key itself was minted and
+     * delivered (#201). Not needed on the common path, where both happen in
+     * the same run.
+     */
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null>;
+    };
+    /** Injected for tests. Absent, {@link provisionPlatformAi} builds the real {@link createAiManagementKeyMinter} from the signing key it mints. */
     managementKeyMinter?: AiManagementKeyMinter;
+    /** Injected for tests, e.g. against a fake ai host. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
     runtime?: PlatformAiRuntime;
 }
 export interface PlatformAiRuntime {
@@ -353,19 +443,43 @@ export interface PlatformAiRuntime {
     migrateTimeoutMs?: number;
     /** Pause between migrate-job status polls (default 5 seconds). */
     migrateIntervalMs?: number;
-    /** Tries at handing the management key to the host (default 3). */
+    /** Tries at handing a secret to the host (default 3): the management key and the signing key both use this. */
     deliverAttempts?: number;
 }
 /** The ref the AI management key is delivered under; the host's `AiOrganisationPort` adapter reads it back. */
 export declare const PLATFORM_AI_MANAGEMENT_KEY_REF = "ai:platform:managementKey";
 /**
- * What foundry's management key may do: exactly the grants `ai`'s README
- * ("Archon's first key", by-hand form) gives archon's key, which are the
- * ones `ai:organisation`, `ai:budget`, `ai:key` and the org destroy call.
+ * What Archon's management key may do in ai: exactly `ai`'s own
+ * `ARCHON_AI_PERMISSIONS` (`apps/host/scripts/authz/bootstrap-archon.ts`) --
+ * configuration only (offerings, provisioning, offers, budgets, usage, cost)
+ * plus deleting (archiving) an organisation, never connections, runs or
+ * webhooks. ai's `/v1/platform/keys` route refuses any permission outside
+ * this same list, so a request for more than this is a 403, not a wider key.
  */
 export declare const PLATFORM_AI_MANAGEMENT_PERMISSIONS: readonly string[];
-/** The message {@link provisionPlatformAi} throws when no {@link AiManagementKeyMinter} was supplied. */
-export declare const PLATFORM_AI_MINTER_MISSING = "platform:ai: the AI host is deployed but foundry's AI management key cannot be minted: no AiManagementKeyMinter was supplied (PlatformAiDeps.managementKeyMinter). ai mints its first platform credential only through its keys:issue-archon script run against the database (apps/host/scripts/authz/bootstrap-archon.ts); it has no HTTP route for that, and CoolifyPort cannot run a command inside a container (#172)";
+/** The ref the AI signing key's private half (PKCS#8 PEM) is delivered under -- the {@link INTEGRATIONS_MANAGEMENT_KEY_REF} pattern, for ai instead of integrations. */
+export declare const AI_SIGNING_KEY_REF = "ai:platform:signingPrivateKey";
+/** `MANAGEMENT_ISSUER` on the ai runner: whoever signs with the delivered key signs as this issuer. */
+export declare const AI_MANAGEMENT_ISSUER = "foundry";
+/** The key id the public half is pinned under in `MANAGEMENT_PUBLIC_KEYS` (ai's keyring allows `^[A-Za-z0-9_-]{1,100}$`). Fixed, since there is one key until rotation is built. */
+export declare const AI_MANAGEMENT_KEY_ID = "foundry-1";
+/**
+ * The real {@link AiManagementKeyMinter}: signs a management assertion with
+ * `privateKeyPem` (the PKCS#8 PEM {@link provisionPlatformAi} delivers under
+ * {@link AI_SIGNING_KEY_REF} and pins on the runner under `keyId`) and calls
+ * ai's `POST /v1/platform/keys`. `audience` must be the exact origin ai's own
+ * `APP_URL` resolves to (`https://<platform.ai.hostname>`), since ai checks
+ * the claim against that env var, not against the internal address the
+ * request itself is sent to.
+ */
+export declare function createAiManagementKeyMinter(options: {
+    privateKeyPem: string;
+    keyId: string;
+    issuer: string;
+    audience: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}): AiManagementKeyMinter;
 /**
  * #171: everything {@link provisionPlatformFiles} needs beyond
  * {@link PlatformStepExecutionContext}, bundled for the same reason as