@wtfalch/foundry 0.62.0 → 0.64.0

package/dist/plan/platform-diff.js

@@ -11,6 +11,7 @@ import { legacyAppHostname } from './hostnames.js';
 import { PLATFORM_MAIL_RELAY_KEY, planMailRelay } from './mail-relay.js';
 import { MAIL_DATABASE_SCOPE_KEY, mailStoreIsLegacy, mailStoreSwitchChange, mailStoreSwitchDescription, } from './mail-store.js';
 import { planOikosIngress } from './oikos-ingress.js';
+import { PLATFORM_REGISTRY_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_REGISTRY_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_REGISTRY_KEY, PLATFORM_REGISTRY_LOGINS_APPLIED_SCOPE_KEY, PLATFORM_REGISTRY_LOGINS_KEY, PLATFORM_REGISTRY_PASSWORDS_SET_SCOPE_KEY, PLATFORM_REGISTRY_PASSWORDS_UNDELIVERED_SCOPE_KEY, registryLoginVersion, } from './platform-registry-keys.js';
 import { callsSfuAppliedFingerprint } from './platform-sfu.js';
 import { postLogoutUpdateOwed, postLogoutUrisFor } from './post-logout-uris.js';
 import { archonInAppHost } from './sign-in-archon.js';
@@ -811,6 +812,28 @@ export function appliedAppSettings(recorded, entryKey) {
     const marker = recorded[appSettingsAppliedScopeKey(entryKey)];
     return marker ? JSON.parse(marker) : DEFAULT_APP_SETTINGS;
 }
+/**
+ * The image an entry's app last ran, as `repository@digest` (no secret). `planApp` plans the step again, with a
+ * redeploy, when the entry's `image` differs from it.
+ */
+export function appImageAppliedScopeKey(entryKey) {
+    return `app_image_applied.${entryKey}`;
+}
+/** An entry image as one pull reference. */
+export function entryImageRef(image) {
+    return `${image.repository}@${image.digest}`;
+}
+/**
+ * The two image fields Coolify accepts for an entry image. Its tag rule has no `@` or `:`, so the digest goes in
+ * the name as `<repository>@sha256` and the tag holds the bare 64 hex digits (Coolify pulls `<name>:<tag>`),
+ * the same way `coolifyImageFor` writes a pinned platform image.
+ */
+export function entryImageFields(image) {
+    return {
+        docker_registry_image_name: `${image.repository}@sha256`,
+        docker_registry_image_tag: image.digest.replace(/^sha256:/, ''),
+    };
+}
 /**
  * The URLs `coolifyApp` last put in the entry's Coolify `domains`
  * (`tunnelDomainList`), as a JSON array (`[]` for an internal entry). `planApp`
@@ -1418,6 +1441,12 @@ export function planPlatform(platform, live, options = {}) {
     const hc = planHc(platform, recordedIds, blocked.hc ?? dnsBlocked?.('heartbeat server'));
     if (hc.step)
         plannedSteps.push(hc.step);
+    // The image registry: edge's DNS and tunnel like hc. The login step follows the app step.
+    const registry = planRegistry(platform, recordedIds, blocked.registry ?? dnsBlocked?.('image registry'), drifted.registryLogins ?? false);
+    if (registry.step)
+        plannedSteps.push(registry.step);
+    if (registry.loginsStep)
+        plannedSteps.push(registry.loginsStep);
     // #540: the `authReady` pattern, for hc -- true once hc is either already
     // applied or about to run earlier in this very plan, so the heartbeats
     // reconcile below can be planned in the *same* round hc first comes up,
@@ -1494,6 +1523,7 @@ export function planPlatform(platform, live, options = {}) {
             recorded: recordedIds,
             servers: archonBlueGreen.servers,
             executorBlocked: archonBlueGreen.blocked,
+            ...(archonBlueGreen.guards ? { guards: archonBlueGreen.guards } : {}),
         })
         : { step: null, unmanaged: [] };
     if (archonBg.step) {
@@ -1637,6 +1667,8 @@ export function planPlatform(platform, live, options = {}) {
     }
     if (hc.blocked)
         unmanaged.push({ description: hc.blocked, key: 'hc' });
+    if (registry.blocked)
+        unmanaged.push({ description: registry.blocked, key: 'registry' });
     if (archonOrg.blocked)
         unmanaged.push({ description: archonOrg.blocked, key: 'archon-org' });
     if (archon.blocked)
@@ -2887,6 +2919,70 @@ function planAccessProvider(platform, recordedIds, executorBlocked, ownerSignIn)
  * Blocked, not planned: `executorBlocked`, from `dnsBlocked` (edge neither
  * applied nor planned) or the host building no `hc` dependencies.
  */
+/**
+ * The platform's image registry (C5): `coolify:app` keyed {@link PLATFORM_REGISTRY_KEY}, then
+ * `coolify:registry-logins` keyed {@link PLATFORM_REGISTRY_LOGINS_KEY}, which logs every Coolify
+ * server in as `pull`. The logins are planned while the host and passwords they last ran with
+ * differ from the current ones, and again when a server has no login (`drifted`).
+ */
+function planRegistry(platform, recordedIds, executorBlocked, loginsDrifted) {
+    const none = { step: null, loginsStep: null, blocked: null };
+    if (!platform.registry.enabled)
+        return none;
+    const { hostname, gitRef } = platform.registry;
+    const undelivered = recordedIds[PLATFORM_REGISTRY_PASSWORDS_UNDELIVERED_SCOPE_KEY];
+    if (undelivered && !recordedIds[PLATFORM_REGISTRY_PASSWORDS_SET_SCOPE_KEY]) {
+        return {
+            ...none,
+            blocked: `the image registry is blocked, not planned: its passwords (${undelivered}) were made but never confirmed delivered and cannot be shown again; remove the recorded id ${PLATFORM_REGISTRY_PASSWORDS_UNDELIVERED_SCOPE_KEY} to make new ones`,
+        };
+    }
+    const applied = Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_REGISTRY_KEY)]) &&
+        Boolean(recordedIds[PLATFORM_REGISTRY_PASSWORDS_SET_SCOPE_KEY]) &&
+        recordedIds[PLATFORM_REGISTRY_APPLIED_HOSTNAME_SCOPE_KEY] === hostname &&
+        recordedIds[PLATFORM_REGISTRY_APPLIED_GIT_REF_SCOPE_KEY] === gitRef;
+    if (executorBlocked && !applied)
+        return { ...none, blocked: executorBlocked };
+    const step = applied
+        ? null
+        : {
+            action: {
+                system: 'coolify',
+                kind: 'app',
+                key: PLATFORM_REGISTRY_KEY,
+                desired: { hostname, gitRef },
+            },
+            step: {
+                description: `provision the image registry at ${hostname}: the build workflow pushes company app images there and the company servers pull them`,
+                destroys: false,
+                migrates: false,
+            },
+        };
+    const loginsCurrent = recordedIds[PLATFORM_REGISTRY_LOGINS_APPLIED_SCOPE_KEY] ===
+        registryLoginVersion(hostname, recordedIds[PLATFORM_REGISTRY_PASSWORDS_SET_SCOPE_KEY]) &&
+        Boolean(recordedIds[PLATFORM_REGISTRY_PASSWORDS_SET_SCOPE_KEY]);
+    const loginsStep = (loginsCurrent && !loginsDrifted) || executorBlocked
+        ? null
+        : {
+            action: {
+                system: 'coolify',
+                kind: 'registry-logins',
+                key: PLATFORM_REGISTRY_LOGINS_KEY,
+                desired: { hostname },
+            },
+            step: {
+                description: `log every Coolify server in to the image registry at ${hostname} so it can pull company app images`,
+                destroys: false,
+                migrates: false,
+            },
+        };
+    const loginsNeeded = !loginsCurrent || loginsDrifted;
+    return {
+        step,
+        loginsStep,
+        blocked: executorBlocked && !step && loginsNeeded ? executorBlocked : null,
+    };
+}
 function planHc(platform, recordedIds, executorBlocked) {
     if (!platform.hc.enabled)
         return { step: null, blocked: null };

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

@@ -373,6 +373,8 @@ export interface PlatformOwnerInput {
     signIn?: OwnerSignIn | null;
     files?: OwnerFiles | null;
     chat?: OwnerChat | null;
+    /** The owner company's owners' emails: who passes the Access gate over Archon's stage. */
+    emails?: readonly string[];
 }
 /**
  * The owner's sign-in from its declared org and the ids its own steps recorded.

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

@@ -12,6 +12,8 @@ import type { TunnelPort } from './edge-tunnels.js';
 import type { ZonePort } from './edge-zones.js';
 import type { CloudflarePort, CoolifyPort, FoundryStepExecutorPorts, ZitadelPort } from './executor.js';
 import { type ReleaseContext, type ReleaseHost } from './release-host.js';
+import { type StageCopyHostConfig } from './stage-copy-host.js';
+import { type ReleasePreviewMembers, type StageProbePort } from './stage-guards.js';
 export { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_KEY_REF, } from './held-key-refs.js';
 import type { LiveResource, PlatformCloudflareReader, PlatformCoolifyReader } from './live.js';
 import { type OikosIngressPorts } from './oikos-ingress.js';
@@ -19,6 +21,7 @@ import { type FilesKeysMinted, type ProjectSource, type ServiceNetwork, type Ser
 import type { PlatformDriftedSteps, PlatformStepExecutionContext, PlatformStepExecutor } from './plan-apply.js';
 import { type BrokerDeployRecord, PLATFORM_ZITADEL_ORG_SCOPE_KEY } from './platform-diff.js';
 import type { PlatformOwnerInput } from './platform-org.js';
+import { type PlatformRegistryDeps } from './platform-registry.js';
 import type { SigninDbBackupPort } from './signin-db-backup.js';
 import { type PlatformZitadelMailBranding } from './signin-mail.js';
 export { PLATFORM_ZITADEL_ORG_SCOPE_KEY };
@@ -100,7 +103,7 @@ export declare function platformRequestHeaders(deps: {
  */
 export type PlatformAccessFactory = (edgeUrl: string) => PlatformAccessPort | Promise<PlatformAccessPort>;
 /** The Access calls a platform step makes. */
-export type PlatformAccessPort = Pick<AccessPort, 'listAccessApps' | 'createAccessApp' | 'ensureOneTimePinProvider' | 'listAccessPolicies' | 'createAccessPolicy' | 'deleteAccessApp'>;
+export type PlatformAccessPort = Pick<AccessPort, 'listAccessApps' | 'createAccessApp' | 'ensureOneTimePinProvider' | 'listAccessPolicies' | 'createAccessPolicy' | 'deleteAccessApp'> & Partial<Pick<AccessPort, 'setGatePeople'>>;
 /**
  * The SMTP call `provisionPlatformAuth` makes on the instance's ZITADEL.
  * `@wtfalch/providers` gains it in 0.7.2; stated here so foundry compiles
@@ -309,6 +312,8 @@ export interface FoundryPlatformStepExecutorOptions {
      * `platform.hc.enabled` without it gets the step reported as blocked.
      */
     hc?: PlatformHcDeps;
+    /** C5: dependencies for the image registry steps; a host that declares `platform.registry.enabled` without it gets them reported as blocked. */
+    registry?: PlatformRegistryDeps;
     /**
      * #540: dependencies for the `heartbeats:reconcile` step -- optional for
      * the same reason as `auth`; `hc` applied with this unset gets the
@@ -354,6 +359,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private readonly archon?;
     private readonly backup?;
     private readonly hc?;
+    private readonly registry?;
     private readonly heartbeats?;
     private readonly uptime?;
     private readonly accessProvider?;
@@ -365,14 +371,32 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private onPlatform;
     /** `deps` with its Coolify port placed on the platform destination, then limited by `profile`. */
     private limitedOnPlatform;
+    /**
+     * Why the image registry cannot be planned, as fixed text, or `undefined`. The held `pull`
+     * password is read only to know it is there; its value goes nowhere.
+     */
+    private registryBlockedReason;
     /** Every Coolify server and why platform-archon's blue/green cannot run here, for the planner. */
     archonBlueGreen(): Promise<{
         servers?: BlueGreenServer[];
         blocked?: string;
     }>;
+    /**
+     * The stage guards that can be made for platform-archon now. The planner puts the names in the applied hash
+     * and the step builds the same guards from the same facts, so a guard that becomes possible later plans the
+     * structure step once more.
+     */
+    archonStageGuardNames(platform: DeclaredPlatform, recorded: Readonly<Record<string, string>>, owner: PlatformOwnerInput): string[];
     /** The release runner's outside calls for platform-archon (`plan/release-host.ts`). The token is only read. */
     releaseHost(platform: DeclaredPlatform, subject: BlueGreenSubject, context: ReleaseContext, renew: () => Promise<void>): ReleaseHost | null;
+    /** Archon's stage gate follows the people holding `releases:preview` (orgId `platform`); the platform's owners stay. */
+    syncStageGateMembers(_platform: DeclaredPlatform, subject: BlueGreenSubject, context: ReleaseContext): Promise<void>;
     private archonBlueGreenStep;
+    /**
+     * Archon's stage guards: the probe port, and the Access gate over the stage host, offered only when the
+     * same facts {@link archonStageGuardNames} counts are all in hand.
+     */
+    private archonStageGuards;
     blockedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>, owner?: PlatformOwnerInput): Promise<{
         auth?: string;
         authExecutorMissing?: boolean;
@@ -389,6 +413,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         oikosIngress?: string;
         backupExecutorMissing?: boolean;
         hc?: string;
+        registry?: string;
         heartbeatsExecutorMissing?: boolean;
         heartbeatsApiKeyMissing?: boolean;
         uptime?: string;
@@ -955,14 +980,24 @@ export declare function ownerInviteBlockedReason(ownerCompany: DeclaredOrg | nul
  */
 export interface PlatformArchonDeps {
     coolify: Pick<CoolifyPort, 'findProjectByName' | 'listEnvironments' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw' | 'bulkUpsertEnvs' | 'listEnvs' | 'deleteEnv' | 'updateApplication' | 'deploy' | 'deployAndWait' | 'getDeployment' | 'listStorages' | 'createPersistentStorage' | 'createFileStorage' | 'updateFileStorage'> & {
+        deleteDatabase?: CoolifyPort['deleteDatabase'];
+        listDatabaseBackups?: CoolifyPort['listDatabaseBackups'];
         listApplicationDeployments?: CoolifyPort['listApplicationDeployments'];
+        listDatabaseBackupExecutions?: CoolifyPort['listDatabaseBackupExecutions'];
     };
+    /**
+     * The stage copy of platform-archon (run by the release tick). Same shape as `FoundryStepExecutorPorts.stageCopy`.
+     * Without it a copy request is refused with `no-copy-port`.
+     */
+    stageCopy?: StageCopyHostConfig;
     /** F4.dns: every DNS record call, through edge at its recorded address (see {@link PlatformDnsFactory}). */
     dns: PlatformDnsFactory;
     /** F4.tunnels: every tunnel call, through edge at its recorded address (see {@link PlatformTunnelsFactory}). */
     tunnels: PlatformTunnelsFactory;
     /** F4.access: every Access app call, through edge at its recorded address (see {@link PlatformAccessFactory}). */
     access: PlatformAccessFactory;
+    /** The people holding `releases:preview` for Archon's own stage (orgId `platform`); see FoundryStepExecutorPorts.releasePreviewMembers. */
+    releasePreviewMembers?: ReleasePreviewMembers;
     cloudflare: Pick<CloudflarePort, 'findZoneByApex'>;
     /** Must target the platform's own ZITADEL instance, or `zitadelForInstance` must be set. */
     zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'findOrCreateProject' | 'createOidcApp' | 'listApps' | 'deleteApp' | 'updateOidcAppIdTokenUserinfoAssertion'> & Partial<Pick<ZitadelPort, 'ensureTrustedDomain' | 'deleteTrustedDomain' | 'updateOidcAppLoginBaseUri' | 'allowPerAppLoginBaseUri' | 'updateOidcAppPostLogoutRedirectUris' | 'getOidcAppRedirectUris' | 'updateOidcAppRedirectUris'>>;
@@ -979,6 +1014,16 @@ export interface PlatformArchonDeps {
      * Access app nobody can pass.
      */
     accessEmails: readonly string[];
+    /**
+     * Archon's stage guards, the same two an entry's stage gets (`plan/stage-guards.ts`): the probe port, and the
+     * Access calls that make the gate over `stage-platform-archon.<apex>`. A missing part leaves that guard
+     * unrecorded ("not run"), so the stage copy stays refused.
+     */
+    stageGuards?: {
+        probes?: StageProbePort;
+        /** Edge's Access calls at its recorded address, like `access`. */
+        gate?: (edgeUrl: string) => Pick<AccessPort, 'createGate'> | Promise<Pick<AccessPort, 'createGate'>>;
+    };
     /**
      * True when the host process runs inside the Coolify app this step
      * redeploys (Archon's console is `platform:archon`). A deploy that waits

package/dist/plan/platform-providers.js

@@ -5,7 +5,7 @@ import { VERSIONS, coolifyImageFor, floatingTagBlocked, pinnedRef } from '../boo
 import { redactSecrets } from '../calls-sfu-deploy-support.js';
 import { ownerMailboxes, ownsServices, sharedSecretRef, } from '../org.js';
 import { applyArchonBlueGreen } from './archon-blue-green.js';
-import { ARCHON_REPO, archonSubject, healthTokenName, pinKeyName, tunnelOriginFor, } from './blue-green.js';
+import { ARCHON_REPO, archonSubject, healthTokenName, parseGuards, pinKeyName, stageGuardInputs, tunnelOriginFor, } from './blue-green.js';
 import { BOULE_BRIDGE_SECRET_ENV, BOULE_PEER_PASSWORD_ENV, BOULE_PEER_ROLE, bouleHostnameFor, } from './boule.js';
 import { recordBuiltCommit } from './build-record.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
@@ -20,8 +20,11 @@ import { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_
 import { LIMITS, limited } from './own-limits.js';
 import { postLogoutAppliedValue, postLogoutUrisFor } from './post-logout-uris.js';
 import { createReleaseHost } from './release-host.js';
+import { buildStageCopyHostPorts } from './stage-copy-host.js';
+import { stageGateKey, stageHostname, syncStageGateMembers, } from './stage-guards.js';
 export { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_KEY_REF, } from './held-key-refs.js';
 import { BROKER_DB_NAME, BROKER_DB_USER, ensureBrokerMcpEnv } from './broker-mcp.js';
+import { withTimeout } from './call-timeout.js';
 import { SIGN_IN_BIND_KEY_ENV, SIGN_IN_BIND_KEY_MIN_LENGTH, SIGN_IN_BIND_KEY_SCOPE_KEY, } from './cookie-domain.js';
 import { coolifyDomains, coolifyTunnelDomains, filesShareHostname } from './hostnames.js';
 import { MAIL_RELAY_BLOCKED, provisionMailRelay } from './mail-relay.js';
@@ -30,6 +33,8 @@ import { OIKOS_INGRESS_BLOCKED, PLATFORM_OIKOS_INGRESS_KEY, oikosIngressApplied,
 import { recordOwnDnsHostname } from './own-dns.js';
 import { platformNetwork, platformTarget, scopeFromPlatform, } from './own-services.js';
 import { AUTH_TUNNEL_ROUTES_VERSION, AUTH_ZITADEL_RUN_OPTIONS, GITHUB_RELEASE_HOOK_DEPS_MISSING, GITHUB_RELEASE_WEBHOOK_SECRET_ENV, JOBS_DEPLOY_PENDING_SCOPE_KEY, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_ACCESS_PROVIDER_APPLIED_AUTH_DOMAIN_SCOPE_KEY, PLATFORM_ACCESS_PROVIDER_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ACCESS_PROVIDER_UNDELIVERED_SCOPE_KEY, PLATFORM_ACCESS_ZITADEL_APP_SCOPE_KEY, PLATFORM_ACCESS_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_TUNNEL_SCOPE_KEY, PLATFORM_ARCHON_ACCESS_PIN_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_AUTH_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_CI_ORG_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_FILES_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_FIRST_OWNER_LINK_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY, PLATFORM_ARCHON_APP_KEY_ORG_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF, PLATFORM_ARCHON_DEPLOYMENT_SCOPE_KEY, PLATFORM_ARCHON_DESKTOP_CALLBACK_APPLIED_SCOPE_KEY, PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_ID_TOKEN_USERINFO_APPLIED_SCOPE_KEY, PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_ARCHON_ORG_DOMAIN_BLOCKED_SCOPE_KEY, PLATFORM_ARCHON_ORG_DOMAIN_SCOPE_KEY, PLATFORM_ARCHON_ORG_POLICY_SCOPE_KEY, PLATFORM_ARCHON_ORG_REGISTRATION_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_ORG_SCOPE_KEY, PLATFORM_ARCHON_OWNER_INVITE_ORG_SCOPE_KEY, PLATFORM_ARCHON_OWNER_INVITE_SCOPE_KEY, PLATFORM_ARCHON_POST_LOGOUT_APPLIED_SCOPE_KEY, PLATFORM_ARCHON_RETIRED_CLIENT_SCOPE_KEY, PLATFORM_ARCHON_UPTIME_TOKEN_SYNCED_SCOPE_KEY, PLATFORM_ARCHON_WEBHOOK_SECRET_DEPLOYED_SCOPE_KEY, PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY, PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_MCP_SCOPE_KEY, PLATFORM_AUTH_OWNER_INVITE_ORG_SCOPE_KEY, PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY, PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY, PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY, PLATFORM_AUTH_SMTP_SCOPE_KEY, PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_EDGE_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_PLATFORM_KEY_SET_SCOPE_KEY, PLATFORM_EDGE_PLATFORM_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_GITHUB_RELEASE_HOOK_KEY, PLATFORM_HC_ACCESS_SCOPE_KEY, PLATFORM_HC_API_KEY_REF, PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_HC_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_HC_KEY, PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY, PLATFORM_HEARTBEATS_HOSTED_API_KEY_REF, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_UNDELIVERED_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_INTEGRATIONS_RUNNER_KEYRING_DEPLOYED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_HOST_PORTS_DIRECT, PLATFORM_MAIL_HOST_PORTS_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_RELAY_KEY, PLATFORM_MAIL_ROLE_CHECK_SCOPE_KEY, PLATFORM_MAIL_ROLE_ENSURED_SCOPE_KEY, PLATFORM_MAIL_ROLE_GRANTED_SCOPE_KEY, PLATFORM_MAIL_ROUTE_SCOPE_KEY, PLATFORM_MAIL_ROUTE_WANTED, PLATFORM_MAIL_USER_ROLE, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_OWNER_ORG_DOMAIN_BLOCKED_SCOPE_KEY, PLATFORM_OWNER_ORG_DOMAIN_SCOPE_KEY, PLATFORM_OWNER_ORG_SCOPE_KEY, PLATFORM_SFU_APPLIED_SCOPE_KEY, PLATFORM_UPTIME_ACCESS_CLIENT_ID_REF, PLATFORM_UPTIME_ACCESS_CLIENT_SECRET_REF, PLATFORM_UPTIME_ACCESS_TOKEN_ID_SCOPE_KEY, PLATFORM_UPTIME_ACCESS_TOKEN_NAME, PLATFORM_UPTIME_ACCESS_UNDELIVERED_SCOPE_KEY, PLATFORM_UPTIME_CHAT_ROOM_ID_SCOPE_KEY, PLATFORM_UPTIME_HEARTBEAT_CHECK_NAME, PLATFORM_UPTIME_KEY, PLATFORM_UPTIME_REMOVED_SCOPE_KEY, PLATFORM_UPTIME_SCRIPT_NAME, PLATFORM_UPTIME_TOKEN_ID_SCOPE_KEY, PLATFORM_UPTIME_TOKEN_REF, PLATFORM_ZITADEL_ORG_SCOPE_KEY, archonFilesMarker, archonFirstOwnerLink, archonOrgDomain, archonOrgName, desiredHeartbeatCheckNames, heartbeatCheckUrlRef, orgDeclaresMcp, parseBrokerDeployRecord, parseLoginClientRecord, platformBackupHeartbeatCheckName, platformMailHostPorts, platformMailMxHost, uptimeAccessTokenConflict, uptimeEffectiveVars, uptimeRecorded, uptimeVarsDigest, } from './platform-diff.js';
+import { PLATFORM_REGISTRY_KEY, PLATFORM_REGISTRY_LOGINS_KEY, PLATFORM_REGISTRY_PASSWORDS_SET_SCOPE_KEY, PLATFORM_REGISTRY_PULL_PASSWORD_REF, registryImageTagBlocked, } from './platform-registry-keys.js';
+import { ensureRegistryLogins, provisionPlatformRegistry, registryLoginsDrifted, } from './platform-registry.js';
 import { PLATFORM_ARCHON_IN_APP_SCOPE_KEY, archonInAppBack, archonInAppBind, archonInAppHost, archonInAppPoint, archonInAppUnbind, } from './sign-in-archon.js';
 import { LOGIN_HOST_BINDINGS_ENV } from './sign-in-bindings.js';
 import { ensureSignInOrg, inviteOwnerWithLink, signInOrgDomain } from './sign-in-org.js';
@@ -143,6 +148,7 @@ export class FoundryPlatformStepExecutor {
     archon;
     backup;
     hc;
+    registry;
     heartbeats;
     uptime;
     accessProvider;
@@ -164,6 +170,7 @@ export class FoundryPlatformStepExecutor {
         this.archon = options.archon;
         this.backup = options.backup;
         this.hc = options.hc;
+        this.registry = options.registry;
         this.heartbeats = options.heartbeats;
         this.uptime = options.uptime;
         this.accessProvider = options.accessProvider;
@@ -184,6 +191,35 @@ export class FoundryPlatformStepExecutor {
     limitedOnPlatform(deps, profile) {
         return { ...deps, coolify: limited(this.onPlatform(deps.coolify), profile) };
     }
+    /**
+     * Why the image registry cannot be planned, as fixed text, or `undefined`. The held `pull`
+     * password is read only to know it is there; its value goes nowhere.
+     */
+    async registryBlockedReason(platform, recordedIds) {
+        if (!this.registry) {
+            return 'the image registry is blocked, not planned: the host built the platform executor without its registry dependencies';
+        }
+        const tagBlocked = registryImageTagBlocked(platform.registry.gitRef);
+        if (tagBlocked)
+            return tagBlocked;
+        const heldKeys = this.registry.heldKeys;
+        if (!heldKeys) {
+            return `the image registry is blocked, not planned: the host cannot read held keys, so the pull password at ${PLATFORM_REGISTRY_PULL_PASSWORD_REF} cannot be read`;
+        }
+        if (recordedIds[PLATFORM_REGISTRY_PASSWORDS_SET_SCOPE_KEY]) {
+            let held = null;
+            try {
+                held = await withTimeout('the registry pull password read', 30_000, () => heldKeys.resolve(PLATFORM_REGISTRY_PULL_PASSWORD_REF));
+            }
+            catch {
+                return `the image registry logins are blocked, not planned: the pull password at ${PLATFORM_REGISTRY_PULL_PASSWORD_REF} could not be read`;
+            }
+            if (!held) {
+                return `the image registry logins are blocked, not planned: no password is held at ${PLATFORM_REGISTRY_PULL_PASSWORD_REF}`;
+            }
+        }
+        return undefined;
+    }
     /** Every Coolify server and why platform-archon's blue/green cannot run here, for the planner. */
     async archonBlueGreen() {
         const archon = this.archon;
@@ -201,6 +237,23 @@ export class FoundryPlatformStepExecutor {
             })),
         };
     }
+    /**
+     * The stage guards that can be made for platform-archon now. The planner puts the names in the applied hash
+     * and the step builds the same guards from the same facts, so a guard that becomes possible later plans the
+     * structure step once more.
+     */
+    archonStageGuardNames(platform, recorded, owner) {
+        const guards = this.archon?.stageGuards;
+        return stageGuardInputs({
+            probesPort: Boolean(guards?.probes),
+            accessPort: Boolean(guards?.gate),
+            providerId: recorded[ACCESS_PROVIDER_RECORD_KEY],
+            domain: platform.apex,
+            claimValue: owner.signIn?.organisationId,
+            emails: owner.emails?.length ?? 0,
+            hostRuled: false,
+        });
+    }
     /** The release runner's outside calls for platform-archon (`plan/release-host.ts`). The token is only read. */
     releaseHost(platform, subject, context, renew) {
         const archon = this.archon;
@@ -223,6 +276,48 @@ export class FoundryPlatformStepExecutor {
             ...(archon.runtime?.fetch ? { fetch: archon.runtime.fetch } : {}),
             renew,
             label: `coolify:release:${subject.id}`,
+            ...(() => {
+                // The copy needs the two database calls the other release calls do not; a fixture without them has no copy.
+                const ready = archon.coolify.deleteDatabase && archon.coolify.listDatabaseBackups;
+                const ports = buildStageCopyHostPorts({
+                    host: ready ? archon.stageCopy : undefined,
+                    coolify: archon.coolify,
+                    context,
+                    org: { slug: 'platform' },
+                    secret: (value) => archon.runtime?.onSecret?.(value),
+                    databaseKey: 'archon',
+                    databaseScopeKey: PLATFORM_ARCHON_DB_SCOPE_KEY,
+                    backupScopeKey: null,
+                    projectScopeKey: PLATFORM_ARCHON_PROJECT_SCOPE_KEY,
+                    serverScopeKey: 'coolify_server',
+                });
+                return ports ? { stageCopy: ports } : {};
+            })(),
+        });
+    }
+    /** Archon's stage gate follows the people holding `releases:preview` (orgId `platform`); the platform's owners stay. */
+    async syncStageGateMembers(_platform, subject, context) {
+        const archon = this.archon;
+        if (!archon)
+            return;
+        await syncStageGateMembers({
+            label: `coolify:stage-gate:${subject.id}`,
+            subjectId: subject.id,
+            orgId: 'platform',
+            owners: archon.accessEmails,
+            read: archon.releasePreviewMembers,
+            recorded: context.recordedIds(),
+            record: (key, value) => context.recordScopeId(key, value),
+            persist: () => context.persist(),
+            setPeople: async (gateId, list) => {
+                const access = await platformAccess(archon, context.recordedIds(), 'platform:archon');
+                if (!access.setGatePeople) {
+                    const error = new Error('the Access port cannot change a gate');
+                    error.name = 'NoGatePeoplePort';
+                    throw error;
+                }
+                await access.setGatePeople(gateId, list);
+            },
         });
     }
     async archonBlueGreenStep(action, context) {
@@ -263,9 +358,43 @@ export class FoundryPlatformStepExecutor {
             sleep: deps.runtime?.sleep ?? defaultSleep,
             logDir: LOG_DIR,
             isRunning: isRunningOrStarting,
+            stageGuards: this.archonStageGuards(platform, subject.id, recorded, context.owner ?? {}, deps),
+            guardInputs: parseGuards(action.desired.guards),
         });
         return undefined;
     }
+    /**
+     * Archon's stage guards: the probe port, and the Access gate over the stage host, offered only when the
+     * same facts {@link archonStageGuardNames} counts are all in hand.
+     */
+    archonStageGuards(platform, id, recorded, owner, deps) {
+        const configured = deps.stageGuards;
+        const guards = configured?.probes ? { probes: configured.probes } : {};
+        const gateFor = configured?.gate;
+        const providerId = recorded[ACCESS_PROVIDER_RECORD_KEY];
+        const claimValue = owner.signIn?.organisationId;
+        const emails = owner.emails ?? [];
+        if (!gateFor || !providerId || !claimValue || emails.length === 0)
+            return guards;
+        const hostname = stageHostname(platform.apex, id);
+        guards.gate = {
+            hostname,
+            create: async () => {
+                const access = await platformAccess({ access: gateFor }, recorded, 'coolify:archon-bluegreen');
+                return access.createGate({
+                    organisationId: platform.ownerOrgId,
+                    key: stageGateKey(id),
+                    entry: id,
+                    hostnames: [hostname],
+                    providerId,
+                    claimName: GATE_CLAIM_NAME,
+                    claimValue,
+                    emails: [...emails],
+                });
+            },
+        };
+        return guards;
+    }
     async blockedSteps(platform, recordedIds = {}, owner = {}) {
         const blocked = {};
         if (platform.auth.enabled && !this.auth) {
@@ -449,6 +578,11 @@ export class FoundryPlatformStepExecutor {
                     'the heartbeat server is blocked, not planned: the host names no email the Cloudflare Access app in front of it may let through';
             }
         }
+        if (platform.registry.enabled) {
+            const registryBlocked = await this.registryBlockedReason(platform, recordedIds);
+            if (registryBlocked)
+                blocked.registry = registryBlocked;
+        }
         // foundry#544: `'hosted'` needs none of `hc`'s own applied state -- only
         // the self-hosted provider's standing note depends on `hc` being
         // recorded applied at all. `planHeartbeats` itself already withholds the
@@ -668,6 +802,11 @@ export class FoundryPlatformStepExecutor {
      */
     async driftedSteps(platform, recordedIds = {}, owner = {}) {
         const result = {};
+        if (platform.registry.enabled && this.registry) {
+            if (await registryLoginsDrifted(this.registry, platform, recordedIds)) {
+                result.registryLogins = true;
+            }
+        }
         if (platform.archon.enabled &&
             this.archon &&
             recordedIds[`coolify:app:${PLATFORM_ARCHON_KEY}`]) {
@@ -899,6 +1038,22 @@ export class FoundryPlatformStepExecutor {
             }
             return provisionPlatformMailRelay(action, context, this.limitedOnPlatform(this.mail, LIMITS.platformMailRelay));
         }
+        if (action.system === 'coolify' &&
+            action.kind === 'app' &&
+            action.key === PLATFORM_REGISTRY_KEY) {
+            if (!this.registry) {
+                throw new Error('platform:registry needs FoundryPlatformStepExecutor to be constructed with its registry dependencies');
+            }
+            return provisionPlatformRegistry(context, this.limitedOnPlatform(this.registry, LIMITS.platformRegistry));
+        }
+        if (action.system === 'coolify' &&
+            action.kind === 'registry-logins' &&
+            action.key === PLATFORM_REGISTRY_LOGINS_KEY) {
+            if (!this.registry) {
+                throw new Error('platform:registry-logins needs FoundryPlatformStepExecutor to be constructed with its registry dependencies');
+            }
+            return ensureRegistryLogins(context, this.registry);
+        }
         if (action.system === 'coolify' && action.kind === 'app' && action.key === PLATFORM_HC_KEY) {
             if (!this.hc) {
                 throw new Error('platform:hc needs FoundryPlatformStepExecutor to be constructed with its hc dependencies (#540)');

package/dist/plan/platform-registry-keys.d.ts

@@ -0,0 +1,58 @@
+import type { DeclaredPlatform } from '../platform.js';
+/**
+ * C5 of the Lokes Smie through Boule campaign: the platform's own image registry. The build
+ * workflow (`wtfalch/build`) pushes company app images here; the Coolify servers pull them.
+ * Docker's `registry:3` (`distribution`) on the platform server, behind the platform tunnel at
+ * `platform.registry.hostname`, with htpasswd sign-in and two users, `push` and `pull`. Their
+ * passwords are made here, held through `deliverSecret` and never leave it (CLAUDE.md, platform
+ * steps, rule 6).
+ *
+ * htpasswd tells users apart only by who they are, not by what they may do: `pull` can push too.
+ * What keeps one company's server from putting an image under another company's name is that
+ * the app is deployed by digest (`build.json`), and `REGISTRY_STORAGE_DELETE_ENABLED` is off, so a
+ * pushed digest never changes. Read-only `pull` needs token auth and is not part of C5.
+ */
+/** The step keys `planRegistry` plans under and the executor dispatches on. */
+export declare const PLATFORM_REGISTRY_KEY = "platform:registry";
+export declare const PLATFORM_REGISTRY_LOGINS_KEY = "platform:registry-logins";
+/** The two htpasswd users. */
+export declare const PLATFORM_REGISTRY_PUSH_USER = "push";
+export declare const PLATFORM_REGISTRY_PULL_USER = "pull";
+/**
+ * The held-key refs (`deliverSecret`'s `<service>:<scope>:<name>` convention) of the two
+ * passwords. Archon reads `PLATFORM_REGISTRY_PUSH_PASSWORD_REF` to put the push credential into
+ * `wtfalch/build`'s repo secrets; foundry never writes to GitHub.
+ */
+export declare const PLATFORM_REGISTRY_PUSH_PASSWORD_REF = "registry:platform:pushPassword";
+export declare const PLATFORM_REGISTRY_PULL_PASSWORD_REF = "registry:platform:pullPassword";
+/**
+ * What a consumer needs to push to the registry: the host (the `REGISTRY_HOST` secret), the user
+ * (`REGISTRY_PUSH_USER`) and the held ref the password (`REGISTRY_PUSH_PASSWORD`) is read from.
+ * Names only, never the password.
+ */
+export declare function platformRegistryPushCredential(platform: DeclaredPlatform): {
+    host: string;
+    user: string;
+    passwordRef: string;
+};
+/** Scope ids (colon-free, CLAUDE.md platform steps rule 1). */
+export declare const PLATFORM_REGISTRY_PASSWORDS_UNDELIVERED_SCOPE_KEY = "registry_passwords_undelivered";
+/** sha256 of both passwords, recorded after delivery. Never the passwords. Also the login version. */
+export declare const PLATFORM_REGISTRY_PASSWORDS_SET_SCOPE_KEY = "registry_passwords_set";
+export declare const PLATFORM_REGISTRY_APPLIED_HOSTNAME_SCOPE_KEY = "registry_applied_hostname";
+export declare const PLATFORM_REGISTRY_APPLIED_GIT_REF_SCOPE_KEY = "registry_applied_git_ref";
+export declare const PLATFORM_REGISTRY_INTERNAL_URL_SCOPE_KEY = "platform_registry_internal_url";
+/** `<hostname>|<passwords set>` once every reachable server is logged in to that host with that `pull` password. */
+export declare const PLATFORM_REGISTRY_LOGINS_APPLIED_SCOPE_KEY = "registry_logins_applied";
+/** The servers the last login run left out because Coolify could not reach them. */
+export declare const PLATFORM_REGISTRY_LOGINS_SKIPPED_SCOPE_KEY = "registry_logins_skipped";
+export declare const PLATFORM_REGISTRY_PROJECT_SCOPE_KEY = "coolify_project_platform_registry";
+export declare const PLATFORM_REGISTRY_APP_SCOPE_KEY = "coolify_platform_registry_app";
+export declare const PLATFORM_REGISTRY_TUNNEL_SCOPE_KEY = "cloudflare_platform_registry_tunnel";
+export declare const PLATFORM_REGISTRY_CONNECTOR_APP_SCOPE_KEY = "coolify_platform_registry_connector_app";
+/** The scope id that records one server's login. Its value is the same as {@link registryLoginVersion}. */
+export declare function registryServerLoginScopeKey(serverUuid: string): string;
+/** What a finished login to `hostname` with the passwords in `set` is recorded as. */
+export declare function registryLoginVersion(hostname: string, set: string | undefined): string;
+/** Why the registry image tag cannot be used, as plan text, or `null`. */
+export declare function registryImageTagBlocked(tag: string): string | null;

package/dist/plan/platform-registry-keys.js

@@ -0,0 +1,69 @@
+import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
+/**
+ * C5 of the Lokes Smie through Boule campaign: the platform's own image registry. The build
+ * workflow (`wtfalch/build`) pushes company app images here; the Coolify servers pull them.
+ * Docker's `registry:3` (`distribution`) on the platform server, behind the platform tunnel at
+ * `platform.registry.hostname`, with htpasswd sign-in and two users, `push` and `pull`. Their
+ * passwords are made here, held through `deliverSecret` and never leave it (CLAUDE.md, platform
+ * steps, rule 6).
+ *
+ * htpasswd tells users apart only by who they are, not by what they may do: `pull` can push too.
+ * What keeps one company's server from putting an image under another company's name is that
+ * the app is deployed by digest (`build.json`), and `REGISTRY_STORAGE_DELETE_ENABLED` is off, so a
+ * pushed digest never changes. Read-only `pull` needs token auth and is not part of C5.
+ */
+/** The step keys `planRegistry` plans under and the executor dispatches on. */
+export const PLATFORM_REGISTRY_KEY = 'platform:registry';
+export const PLATFORM_REGISTRY_LOGINS_KEY = 'platform:registry-logins';
+/** The two htpasswd users. */
+export const PLATFORM_REGISTRY_PUSH_USER = 'push';
+export const PLATFORM_REGISTRY_PULL_USER = 'pull';
+/**
+ * The held-key refs (`deliverSecret`'s `<service>:<scope>:<name>` convention) of the two
+ * passwords. Archon reads `PLATFORM_REGISTRY_PUSH_PASSWORD_REF` to put the push credential into
+ * `wtfalch/build`'s repo secrets; foundry never writes to GitHub.
+ */
+export const PLATFORM_REGISTRY_PUSH_PASSWORD_REF = 'registry:platform:pushPassword';
+export const PLATFORM_REGISTRY_PULL_PASSWORD_REF = 'registry:platform:pullPassword';
+/**
+ * What a consumer needs to push to the registry: the host (the `REGISTRY_HOST` secret), the user
+ * (`REGISTRY_PUSH_USER`) and the held ref the password (`REGISTRY_PUSH_PASSWORD`) is read from.
+ * Names only, never the password.
+ */
+export function platformRegistryPushCredential(platform) {
+    return {
+        host: platform.registry.hostname,
+        user: PLATFORM_REGISTRY_PUSH_USER,
+        passwordRef: PLATFORM_REGISTRY_PUSH_PASSWORD_REF,
+    };
+}
+/** Scope ids (colon-free, CLAUDE.md platform steps rule 1). */
+export const PLATFORM_REGISTRY_PASSWORDS_UNDELIVERED_SCOPE_KEY = 'registry_passwords_undelivered';
+/** sha256 of both passwords, recorded after delivery. Never the passwords. Also the login version. */
+export const PLATFORM_REGISTRY_PASSWORDS_SET_SCOPE_KEY = 'registry_passwords_set';
+export const PLATFORM_REGISTRY_APPLIED_HOSTNAME_SCOPE_KEY = 'registry_applied_hostname';
+export const PLATFORM_REGISTRY_APPLIED_GIT_REF_SCOPE_KEY = 'registry_applied_git_ref';
+export const PLATFORM_REGISTRY_INTERNAL_URL_SCOPE_KEY = 'platform_registry_internal_url';
+/** `<hostname>|<passwords set>` once every reachable server is logged in to that host with that `pull` password. */
+export const PLATFORM_REGISTRY_LOGINS_APPLIED_SCOPE_KEY = 'registry_logins_applied';
+/** The servers the last login run left out because Coolify could not reach them. */
+export const PLATFORM_REGISTRY_LOGINS_SKIPPED_SCOPE_KEY = 'registry_logins_skipped';
+export const PLATFORM_REGISTRY_PROJECT_SCOPE_KEY = 'coolify_project_platform_registry';
+export const PLATFORM_REGISTRY_APP_SCOPE_KEY = 'coolify_platform_registry_app';
+export const PLATFORM_REGISTRY_TUNNEL_SCOPE_KEY = 'cloudflare_platform_registry_tunnel';
+export const PLATFORM_REGISTRY_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_registry_connector_app';
+/** The scope id that records one server's login. Its value is the same as {@link registryLoginVersion}. */
+export function registryServerLoginScopeKey(serverUuid) {
+    return `registry_login_${serverUuid}`;
+}
+/** What a finished login to `hostname` with the passwords in `set` is recorded as. */
+export function registryLoginVersion(hostname, set) {
+    return `${hostname}|${set ?? ''}`;
+}
+/** Why the registry image tag cannot be used, as plan text, or `null`. */
+export function registryImageTagBlocked(tag) {
+    const reason = floatingTagBlocked('registry', tag, VERSIONS.registry);
+    return reason
+        ? `the image registry is blocked, not planned: ${reason} as the registry gitRef`
+        : null;
+}