@wtfalch/foundry 0.19.0 → 0.20.0

package/dist/bootstrap/declare.js

@@ -23,12 +23,13 @@ export const DEFAULT_GIT_REF = 'main';
  */
 export const DEFAULT_MAIL_IMAGE_TAG = VERSIONS.stalwart;
 /**
- * Every platform service except `sfu` and `edge` is enabled, like the other
- * steps: a service whose dependencies the host did not supply is reported
- * blocked, not planned. `sfu` stays off because it needs a held SSH key and
- * host fingerprint, a separate human step (issue 170). `edge` stays off
- * because the edge service (N1) does not exist yet -- a human deploys it
- * and sets its hostname before enabling it (#317's own "Human steps").
+ * Every platform service except `sfu` is enabled, like the other steps: a
+ * service whose dependencies the host did not supply is reported blocked,
+ * not planned. `sfu` stays off because it needs a held SSH key and host
+ * fingerprint, a separate human step (issue 170). `edge` is on because every
+ * platform DNS record is written through it (F4.dns); its own Cloudflare API
+ * token is a held key (`cloudflare:edge:apiToken`), and until a human holds
+ * it the planner reports edge blocked, and auth, mail and archon with it.
  */
 const SERVICES_ENABLED_BY_DEFAULT = new Set([
     'auth',
@@ -38,6 +39,7 @@ const SERVICES_ENABLED_BY_DEFAULT = new Set([
     'jobs',
     'integrations',
     'archon',
+    'edge',
 ]);
 /**
  * The owner as `OwnerIdentity`, trimmed. Throws a plain error naming the

package/dist/index.d.ts

@@ -20,7 +20,9 @@ export type { FoundryStoreDb } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type AppliedVersionRow, type NewAppliedVersionRow, type DeclaredPlatformRow, type NewDeclaredPlatformRow, type RequestedChangeRow, type NewRequestedChangeRow, } from './store/schema.js';
 export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, StepAction, PlannedStep, StepSystem, PlanDetail, PlatformPlanDetail, AdoptCandidate, AdoptInput, AdoptPlan, AdoptSnapshot, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan/index.js';
 export { AdoptRefusedError } from './plan/index.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { createEdgeAccess, createEdgeDns, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';
+export type { AccessAppSummary, AccessDecision, AccessPolicyRule, AccessPort, DnsPort, EdgePlatformAccess, EdgePlatformDns, EdgePlatformRateLimits, EdgePlatformWorkers, EdgePlatformZones, EdgeZonesOptions, ZonePort, EdgeRateLimitsOptions, RateLimitPort, RateLimitRuleInput, EdgeWorkersOptions, EdgePlatformTunnels, TunnelPort, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export type { PlatformOrgClientFactories } from './plan/index.js';
@@ -29,7 +31,7 @@ export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedu
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
 export type { ScopeResolver, RecordedIds } from './plan/index.js';
-export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
+export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
 export type { ZitadelListAppsRawApp } from './plan/index.js';
 export { adaptZitadelListApps } from './plan/index.js';
 export type { MailIdentityApp, MailIdentityAudienceCheck } from './plan/index.js';
@@ -37,7 +39,7 @@ export { checkMailIdentityAudience } from './plan/index.js';
 export type { MailAllowlistApp } from './plan/index.js';
 export { checkMailAppsAllowlist } from './plan/index.js';
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, createZitadelAdminMinter, createZitadelProjectRoles, PLATFORM_AUTH_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './plan/index.js';
-export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, PlatformEdgeDeps, PlatformEdgeRuntime, } from './plan/index.js';
+export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, PlatformEdgeDeps, PlatformDnsFactory, PlatformAccessFactory, PlatformAccessPort, PlatformTunnelsFactory, PlatformEdgeRuntime, } from './plan/index.js';
 export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './plan/index.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './plan/index.js';
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './plan/index.js';

package/dist/index.js

@@ -12,12 +12,13 @@ export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, cre
 export { createPostgresAuditLog } from './store/audit.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
 export { AdoptRefusedError } from './plan/index.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { createEdgeAccess, createEdgeDns, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
-export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
+export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
 export { adaptZitadelListApps } from './plan/index.js';
 export { checkMailIdentityAudience } from './plan/index.js';
 export { checkMailAppsAllowlist } from './plan/index.js';

package/dist/plan/agora.d.ts

@@ -151,6 +151,17 @@ export declare const CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY = "coolify_calls_service_
  */
 export declare const CALLS_INTROSPECTION_SCOPE_KEY = "zitadel_calls_introspection_app";
 export declare const CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY = "zitadel_calls_introspection_undelivered";
+/**
+ * The introspection API app minted for the org's chat service (once), in the
+ * messaging project, and the undelivered key recorded before its secret
+ * leaves the executor (platform rule 1). The first doubles as the marker
+ * `planChat` reads: recorded after the service's env carries the client. No
+ * `:` in either.
+ */
+export declare const CHAT_INTROSPECTION_SCOPE_KEY = "zitadel_chat_introspection_app";
+export declare const CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY = "zitadel_chat_introspection_undelivered";
+/** The chat service's introspection API app name; one per org, exact match only. */
+export declare function chatIntrospectionAppName(org: DeclaredOrg): string;
 /** What the plan hands the calls service step: the two host values the token env needs. */
 export interface CallsTokenHost {
     issuer: string;

package/dist/plan/agora.js

@@ -163,6 +163,19 @@ export const CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY = 'coolify_calls_service_token_en
  */
 export const CALLS_INTROSPECTION_SCOPE_KEY = 'zitadel_calls_introspection_app';
 export const CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY = 'zitadel_calls_introspection_undelivered';
+/**
+ * The introspection API app minted for the org's chat service (once), in the
+ * messaging project, and the undelivered key recorded before its secret
+ * leaves the executor (platform rule 1). The first doubles as the marker
+ * `planChat` reads: recorded after the service's env carries the client. No
+ * `:` in either.
+ */
+export const CHAT_INTROSPECTION_SCOPE_KEY = 'zitadel_chat_introspection_app';
+export const CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY = 'zitadel_chat_introspection_undelivered';
+/** The chat service's introspection API app name; one per org, exact match only. */
+export function chatIntrospectionAppName(org) {
+    return `chat-introspection-${org.slug}`;
+}
 /**
  * The token env's inputs, or null while any is missing: the host's issuer and
  * messaging project id (`AgoraHostValues`) and the org's recorded ZITADEL org

package/dist/plan/chat-matrix.d.ts

@@ -90,6 +90,9 @@ export interface ChatServiceEnvInput {
     agoraHost: string;
     masClientId: string;
     masClientSecret: string;
+    /** The ZITADEL API app the service introspects Agora's opaque tokens as. */
+    introspectionClientId: string;
+    introspectionClientSecret: string;
 }
 /** Every variable `chat/apps/chat-service/src/config.ts` requires, plus the internal Synapse address and port. */
 export declare function chatServiceEnvs(input: ChatServiceEnvInput): Array<{

package/dist/plan/chat-matrix.js

@@ -195,6 +195,8 @@ export function chatServiceEnvs(input) {
         { key: 'MAS_URL', value: upstreams.mas },
         { key: 'MAS_CLIENT_ID', value: input.masClientId },
         { key: 'MAS_CLIENT_SECRET', value: input.masClientSecret },
+        { key: 'CHAT_INTROSPECTION_CLIENT_ID', value: input.introspectionClientId },
+        { key: 'CHAT_INTROSPECTION_CLIENT_SECRET', value: input.introspectionClientSecret },
         // DATABASE_URL_OWNER/DATABASE_URL are pushed by executor.ts's
         // pushDatabaseUrl instead, not here (the same split coolifyApp and
         // cmsSite follow, #239) -- that call mints a distinct <dbName>_rt

package/dist/plan/cloudflared-connector.d.ts

@@ -1,4 +1,5 @@
-import type { CloudflarePort, CoolifyPort } from './executor.js';
+import type { TunnelPort } from './edge-tunnels.js';
+import type { CoolifyPort } from './executor.js';
 /**
  * #197: the pinned `cloudflared` image, the same release tag as
  * `scripts/shared-ingress.mjs`'s and `calls-sfu.ts`'s own
@@ -24,7 +25,7 @@ export declare function cloudflaredDockerfile(): string;
  */
 export interface EnsureCloudflaredConnectorInput {
     coolify: Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'createDockerfileApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy'>;
-    cloudflare: Pick<CloudflarePort, 'getTunnelToken'>;
+    tunnels: Pick<TunnelPort, 'getTunnelToken'>;
     /** The Cloudflare tunnel this connector dials into (already created and configured by the caller). */
     tunnelId: string;
     /** Fixed name, found before created -- so a second apply reuses this app rather than making a second one. */

package/dist/plan/cloudflared-connector.js

@@ -32,7 +32,7 @@ export function cloudflaredDockerfile() {
  * with no cause, because a Coolify error can echo the request body.
  */
 export async function ensureCloudflaredConnector(input) {
-    const { coolify, cloudflare } = input;
+    const { coolify, tunnels } = input;
     const liveStatus = async (uuid) => {
         try {
             return { found: true, status: (await coolify.getApplication(uuid)).status };
@@ -82,7 +82,7 @@ export async function ensureCloudflaredConnector(input) {
     }
     if (appId !== input.recordedConnectorAppId)
         await input.recordAppId(appId);
-    const token = await cloudflare.getTunnelToken(input.tunnelId);
+    const token = await tunnels.getTunnelToken(input.tunnelId);
     const tokenChanged = justCreated || (await tunnelTokenDiffers(coolify, appId, token));
     if (tokenChanged) {
         try {

package/dist/plan/diff.js

@@ -1,6 +1,6 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.js';
-import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
+import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
 import { BOULE_BROKER_ENTRY_KEY, bouleEnvDrift, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
@@ -214,10 +214,6 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const edgeReservedLabels = planEdgeReservedLabels(org, recordedIds, platformReadiness, options.platformHostnames ?? []);
     if (edgeReservedLabels.step)
         plannedSteps.push(edgeReservedLabels.step);
-    // After the apps -- a edge key needs the entry's app recorded, the same
-    // dependency `planEntryAiKeys`/`planFilesKeys` have.
-    const entryEdgeKeys = planEntryEdgeKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
-    plannedSteps.push(...entryEdgeKeys.steps);
     const tunnel = planTunnel(org, byKey, claimed, recordedIds);
     // #238: a tunnel that is being provisioned waits for an active zone; parking
     // one never does.
@@ -264,6 +260,10 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null);
     if (boule.step)
         plannedSteps.push(boule.step);
+    // After the apps and Boule -- an edge key needs its app recorded or planned,
+    // the same dependency `planEntryAiKeys`/`planFilesKeys` have.
+    const entryEdgeKeys = planEntryEdgeKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
+    plannedSteps.push(...entryEdgeKeys.steps);
     // Boule's own broker entry, after its app: the entry needs the AUTH_APP_KEY
     // that step puts in the app's env.
     const bouleBroker = planBouleBrokerEntry(org, recordedIds, plannedSteps, options.broker ?? false);
@@ -964,6 +964,27 @@ function planChat(org, byKey, claimed, recordedIds, reading, issuerPlanned) {
                 blocked: null,
             };
         }
+        // A live chat made before its service had an introspection client
+        // answers every Agora sign-in with `token_invalid`. The marker is the
+        // client's app id, recorded after the service's env carries it.
+        if (!recordedIds[CHAT_INTROSPECTION_SCOPE_KEY]) {
+            return {
+                step: {
+                    action: {
+                        system: 'coolify',
+                        kind: 'chat',
+                        key: org.id,
+                        desired: { usesDomain: liveUsesDomain, refreshIntrospection: true },
+                    },
+                    step: {
+                        description: `give ${org.slug}'s chat service its token introspection client and redeploy it`,
+                        destroys: false,
+                        migrates: false,
+                    },
+                },
+                blocked: null,
+            };
+        }
         return none;
     }
     const domain = org.domain ?? 'its domain';

package/dist/plan/edge-access.d.ts

@@ -0,0 +1,68 @@
+import type { AccessDecision, createEdgeClient } from '@wtfalch/edge';
+import { type WriteSlot } from './edge-dns.js';
+/** The edge SDK's platform Access client: `createEdgeClient({ ... }).platform.access`. */
+export type EdgePlatformAccess = ReturnType<typeof createEdgeClient>['platform']['access'];
+export type { AccessDecision };
+/** One Access rule in Cloudflare's own shape: `{ email: { email } }`, `{ everyone: {} }`, `{ service_token: { token_id } }`. */
+export type AccessPolicyRule = Record<string, unknown>;
+export interface AccessAppSummary {
+    /** Cloudflare's app id: what every edge Access call takes. */
+    id: string;
+    name: string;
+    domain: string;
+}
+/**
+ * Foundry's Cloudflare Access calls. Every Access call in foundry goes through
+ * this; the one implementation is {@link createEdgeAccess}, which speaks to the
+ * edge service with the platform credential.
+ */
+export interface AccessPort {
+    /** Every live Access app foundry may use: the platform's own, and ones nobody adopted yet. */
+    listAccessApps(): Promise<AccessAppSummary[]>;
+    createAccessApp(app: {
+        name: string;
+        domain: string;
+        type: 'self_hosted';
+    }): Promise<{
+        id: string;
+    }>;
+    listAccessPolicies(appId: string): Promise<Array<{
+        id: string;
+        name: string;
+        include?: AccessPolicyRule[];
+    }>>;
+    createAccessPolicy(appId: string, policy: {
+        name: string;
+        decision: AccessDecision;
+        include: AccessPolicyRule[];
+    }): Promise<{
+        id: string;
+    }>;
+    /**
+     * A service token's id by exact name -- the token itself is a live
+     * Cloudflare resource foundry never mints and whose secret it never reads.
+     * `undefined` when no token has that name; throws when more than one does.
+     */
+    findServiceTokenByName(name: string): Promise<{
+        id: string;
+    } | undefined>;
+    deleteAccessApp(appId: string): Promise<void>;
+}
+/**
+ * Edge answers a policy, delete or create call for a live Access app with no
+ * edge row `not_found` or 409 `exists` ("create or adopt it first"). So the
+ * adapter adopts an app the moment it is about to be used: an app it saw in a
+ * list (or that a create refused with `exists`) whose owner edge reported as
+ * `null` is remembered, and adopted just before the first call on it. An app
+ * foundry recorded in an earlier apply and now names by id only is looked up
+ * on `not_found`, adopted if unowned, and the call retried once, so a destroy
+ * deletes it instead of finding "nothing there". Adopt is idempotent and the
+ * list reports the owner afterwards, so nothing is recorded in the plan. An
+ * app with an owner is never adopted or changed. An adopt that edge skips
+ * (`taken`, `unsupported_type`) is an error. A `rate_limited` answer is
+ * retried with edge's hint, up to 5 tries.
+ */
+export declare function createEdgeAccess(client: EdgePlatformAccess, options?: {
+    sleep?: (ms: number) => Promise<void>;
+    writeSlot?: WriteSlot;
+}): AccessPort;

package/dist/plan/edge-access.js

@@ -0,0 +1,123 @@
+import { EdgeApiError } from '@wtfalch/edge';
+import { EDGE_DNS_WRITE_CONCURRENCY, limiter, rateLimitRetrier, } from './edge-dns.js';
+const isNotFound = (error) => error instanceof EdgeApiError && error.code === 'not_found';
+/** Edge's 409 for a live app on the domain with no edge row. */
+const isExists = (error) => error instanceof EdgeApiError && error.code === 'conflict' && error.reason === 'exists';
+/**
+ * Edge answers a policy, delete or create call for a live Access app with no
+ * edge row `not_found` or 409 `exists` ("create or adopt it first"). So the
+ * adapter adopts an app the moment it is about to be used: an app it saw in a
+ * list (or that a create refused with `exists`) whose owner edge reported as
+ * `null` is remembered, and adopted just before the first call on it. An app
+ * foundry recorded in an earlier apply and now names by id only is looked up
+ * on `not_found`, adopted if unowned, and the call retried once, so a destroy
+ * deletes it instead of finding "nothing there". Adopt is idempotent and the
+ * list reports the owner afterwards, so nothing is recorded in the plan. An
+ * app with an owner is never adopted or changed. An adopt that edge skips
+ * (`taken`, `unsupported_type`) is an error. A `rate_limited` answer is
+ * retried with edge's hint, up to 5 tries.
+ */
+export function createEdgeAccess(client, options = {}) {
+    const retrying = rateLimitRetrier(options.sleep);
+    const access = {
+        list: (filter) => retrying(() => client.list(filter)),
+        create: (input) => retrying(() => client.create(input)),
+        remove: (id) => retrying(() => client.remove(id)),
+        listPolicies: (appId) => retrying(() => client.listPolicies(appId)),
+        createPolicy: (appId, input) => retrying(() => client.createPolicy(appId, input)),
+        findServiceToken: (name) => retrying(() => client.findServiceToken(name)),
+        adopt: (input) => retrying(() => client.adopt(input)),
+    };
+    const writeSlot = options.writeSlot ?? limiter(EDGE_DNS_WRITE_CONCURRENCY);
+    /** app id -> a seen live app with no edge row yet. */
+    const unadopted = new Map();
+    const remember = (views) => {
+        for (const view of views) {
+            if (view.owner === null)
+                unadopted.set(view.id, view);
+            else
+                unadopted.delete(view.id);
+        }
+    };
+    const adopt = async (view) => {
+        const result = await writeSlot(() => access.adopt({ apps: [{ name: view.name, domain: view.domain, id: view.id }] }));
+        const skipped = result.skipped[0];
+        if (skipped) {
+            throw new Error(`edge access: ${view.name} (${view.domain}) cannot be adopted (${skipped.reason}); remove or fix it by hand`);
+        }
+        if (result.notFound.length > 0) {
+            throw new EdgeApiError(404, 'not_found', `edge access: ${view.name} is no longer live`);
+        }
+        unadopted.delete(view.id);
+    };
+    /** Runs a call on an app; adopts it first when seen unowned, and once more on `not_found`. */
+    const onApp = async (appId, call) => {
+        const seen = unadopted.get(appId);
+        if (seen)
+            await adopt(seen);
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+            const live = (await access.list()).apps;
+            remember(live);
+            const view = live.find((a) => a.id === appId);
+            if (!view || view.owner !== null)
+                throw error;
+            await adopt(view);
+            return call();
+        }
+    };
+    const listAccessApps = async () => {
+        const { apps } = await access.list();
+        remember(apps);
+        return apps.map((a) => ({ id: a.id, name: a.name, domain: a.domain }));
+    };
+    return {
+        listAccessApps,
+        async createAccessApp(app) {
+            try {
+                const created = await writeSlot(() => access.create({ name: app.name, domain: app.domain, type: app.type }));
+                return { id: created.id };
+            }
+            catch (error) {
+                // A live app holds the domain with no edge row. The one of this name
+                // and domain is foundry's own from before edge owned Access: use it,
+                // adopting it before its first policy call. Any other app is refused.
+                if (!isExists(error))
+                    throw error;
+                const { apps } = await access.list({ domain: app.domain });
+                remember(apps);
+                const same = apps.find((a) => a.name === app.name && a.owner === null);
+                if (!same)
+                    throw error;
+                return { id: same.id };
+            }
+        },
+        async listAccessPolicies(appId) {
+            const { policies } = await onApp(appId, () => access.listPolicies(appId));
+            return policies.map((p) => ({ id: p.id, name: p.name, include: p.include }));
+        },
+        async createAccessPolicy(appId, policy) {
+            const created = await onApp(appId, () => writeSlot(() => access.createPolicy(appId, policy)));
+            return { id: created.id };
+        },
+        async findServiceTokenByName(name) {
+            try {
+                const { token } = await access.findServiceToken(name);
+                return token ? { id: token.id } : undefined;
+            }
+            catch (error) {
+                if (error instanceof EdgeApiError && error.code === 'conflict') {
+                    throw new Error(`edge access: more than one Cloudflare Access service token is named '${name}'; rename or remove the extras`);
+                }
+                throw error;
+            }
+        },
+        async deleteAccessApp(appId) {
+            await onApp(appId, () => writeSlot(() => access.remove(appId)));
+        },
+    };
+}

package/dist/plan/edge-dns.d.ts

@@ -0,0 +1,89 @@
+import type { createEdgeClient } from '@wtfalch/edge';
+/** The edge SDK's platform DNS client: `createEdgeClient({ ... }).platform.dns`. */
+export type EdgePlatformDns = ReturnType<typeof createEdgeClient>['platform']['dns'];
+export interface DnsRecordSummary {
+    id: string;
+    type: string;
+    content: string;
+    name: string;
+}
+export interface DnsRecordInput {
+    type: string;
+    name: string;
+    content: string;
+    proxied?: boolean;
+    ttl?: number;
+    /** Required for an `MX` record. */
+    priority?: number;
+}
+/**
+ * Foundry's DNS calls. Every record call in foundry goes through this; the one
+ * implementation is {@link createEdgeDns}, which speaks to the edge service
+ * with the platform credential. `zone` is the zone's own domain (what
+ * `ZonePort.findZoneByApex` returns as `name`), not a Cloudflare zone
+ * id: edge addresses a zone by its domain.
+ */
+export interface DnsPort {
+    /** An exact name + type match, so a stale record of a different type is never mistaken for a match. */
+    findDnsRecord(zone: string, name: string, type?: string): Promise<DnsRecordSummary[]>;
+    /**
+     * Every record of a type in the zone, for a domain recorded before
+     * `CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY` existed and so with no
+     * hostname list to look up instead.
+     */
+    listDnsRecords(zone: string, opts?: {
+        type?: string;
+        name?: string;
+    }): Promise<DnsRecordSummary[]>;
+    createDnsRecord(zone: string, rec: DnsRecordInput): Promise<{
+        id: string;
+        name: string;
+        content: string;
+    }>;
+    updateDnsRecord(zone: string, recordId: string, rec: DnsRecordInput): Promise<{
+        id: string;
+        name: string;
+        content: string;
+    }>;
+    deleteDnsRecord(zone: string, recordId: string): Promise<void>;
+}
+/** Edge answers its platform writes from one shared slot of 4 (company-less writes). */
+export declare const EDGE_DNS_WRITE_CONCURRENCY = 4;
+/**
+ * Edge lists a TXT record raw, quoted (`"v=spf1 ..."`, long values in several
+ * quoted chunks), but returns it unquoted from a create or update. Everything
+ * foundry compares sees the unquoted form.
+ */
+export declare function unquoteTxt(content: string): string;
+export type WriteSlot = <T>(task: () => Promise<T>) => Promise<T>;
+export declare function limiter(max: number): WriteSlot;
+/**
+ * Edge's company-less platform calls share one per-org slot of 4 and answer a
+ * full slot with `rate_limited` and a retry hint, without queueing. The SDK
+ * does not retry, so every call here waits the hint out, up to this many tries.
+ */
+export declare const EDGE_DNS_RATE_LIMIT_ATTEMPTS = 5;
+/**
+ * Retries a call edge answered `rate_limited`, waiting out its hint (capped at
+ * 30 s), up to {@link EDGE_DNS_RATE_LIMIT_ATTEMPTS} tries. Shared by every
+ * edge adapter, since all platform calls draw on the one slot.
+ */
+export declare function rateLimitRetrier(sleepOption?: (ms: number) => Promise<void>): <T>(task: () => Promise<T>) => Promise<T>;
+/**
+ * Edge answers an update or delete of a live record with no edge row
+ * `not_found` ("adopt it first"). So the adapter adopts a record the moment it
+ * is about to be changed or removed: every record it has returned that the
+ * list reported with `owner: null` is remembered, and adopted just before the
+ * first write that names it. Adopt is idempotent and the list reports the
+ * owner once adopted, so nothing is recorded in the plan and a later apply
+ * adopts nothing. A record foundry only reads (a foreign record it refuses to
+ * overwrite) is never adopted. An `unsupported_type`, `taken` or `organisation`
+ * skip is an error; an `unclaimed` record is left alone. A company's own record
+ * (edge answers `forbidden`) is never changed: the error names zone, name and
+ * type. A `rate_limited` answer is retried with edge's hint, up to 5 tries.
+ */
+export declare function createEdgeDns(client: EdgePlatformDns, options?: {
+    sleep?: (ms: number) => Promise<void>;
+    /** Share one slot of {@link EDGE_DNS_WRITE_CONCURRENCY} with the tunnel adapter: edge counts both. */
+    writeSlot?: WriteSlot;
+}): DnsPort;