@wtfalch/foundry 0.19.1 → 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/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

@@ -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);

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;

package/dist/plan/edge-dns.js

@@ -0,0 +1,227 @@
+import { EdgeApiError } from '@wtfalch/edge';
+/** Edge answers its platform writes from one shared slot of 4 (company-less writes). */
+export 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 function unquoteTxt(content) {
+    const trimmed = content.trim();
+    if (!trimmed.startsWith('"'))
+        return content;
+    const chunks = [...trimmed.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => (m[1] ?? '').replace(/\\(.)/g, '$1'));
+    return chunks.length > 0 ? chunks.join('') : content;
+}
+function summary(record) {
+    return {
+        id: record.id,
+        type: record.type,
+        name: record.name,
+        content: record.type === 'TXT' ? unquoteTxt(record.content) : record.content,
+    };
+}
+export function limiter(max) {
+    let active = 0;
+    const waiting = [];
+    return async (task) => {
+        while (active >= max)
+            await new Promise((resolve) => waiting.push(resolve));
+        active++;
+        try {
+            return await task();
+        }
+        finally {
+            active--;
+            waiting.shift()?.();
+        }
+    };
+}
+const isEdgeNotFound = (error) => error instanceof EdgeApiError && error.code === 'not_found';
+const isEdgeForbidden = (error) => error instanceof EdgeApiError && error.code === 'forbidden';
+/**
+ * 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 const EDGE_DNS_RATE_LIMIT_ATTEMPTS = 5;
+const DEFAULT_RETRY_AFTER_SECONDS = 2;
+const MAX_RETRY_AFTER_SECONDS = 30;
+/**
+ * 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 function rateLimitRetrier(sleepOption) {
+    const sleep = sleepOption ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    return async (task) => {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await task();
+            }
+            catch (error) {
+                if (!(error instanceof EdgeApiError) ||
+                    error.code !== 'rate_limited' ||
+                    attempt >= EDGE_DNS_RATE_LIMIT_ATTEMPTS) {
+                    throw error;
+                }
+                await sleep(Math.min(error.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS, MAX_RETRY_AFTER_SECONDS) * 1000);
+            }
+        }
+    };
+}
+const OWNED_BY_COMPANY = 'owned by the company; foundry will not change it';
+/**
+ * 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 function createEdgeDns(client, options = {}) {
+    const retrying = rateLimitRetrier(options.sleep);
+    /** The SDK client with every call retried on `rate_limited`. */
+    const dns = {
+        list: (input) => retrying(() => client.list(input)),
+        create: (input) => retrying(() => client.create(input)),
+        update: (zone, id, patch) => retrying(() => client.update(zone, id, patch)),
+        remove: (zone, id) => retrying(() => client.remove(zone, id)),
+        adopt: (input) => retrying(() => client.adopt(input)),
+    };
+    const writeSlot = options.writeSlot ?? limiter(EDGE_DNS_WRITE_CONCURRENCY);
+    /** zone -> record id -> a seen live record with no edge row yet. */
+    const unadopted = new Map();
+    /** zone -> record id -> every record seen, to name one in an error. */
+    const seen = new Map();
+    const describe = (zone, recordId) => {
+        const record = seen.get(zone)?.get(recordId);
+        return record ? `${record.type} ${record.name} in ${zone}` : `record ${recordId} in ${zone}`;
+    };
+    const remember = (zone, records) => {
+        const all = seen.get(zone) ?? new Map();
+        for (const record of records)
+            all.set(record.id, record);
+        seen.set(zone, all);
+        const pending = unadopted.get(zone) ?? new Map();
+        for (const record of records) {
+            if (record.owner === null)
+                pending.set(record.id, record);
+            else
+                pending.delete(record.id);
+        }
+        unadopted.set(zone, pending);
+    };
+    const adopt = async (zone, record) => {
+        const result = await writeSlot(() => dns.adopt({
+            zone,
+            records: [
+                {
+                    name: record.name,
+                    type: record.type,
+                    id: record.id,
+                    content: record.content,
+                },
+            ],
+        }));
+        const skipped = result.skipped[0];
+        if (skipped) {
+            throw new Error(skipped.reason === 'organisation'
+                ? `edge dns: ${record.type} ${record.name} in ${zone} is ${OWNED_BY_COMPANY}`
+                : `edge dns: ${record.type} ${record.name} in ${zone} cannot be adopted (${skipped.reason}); remove or fix it by hand`);
+        }
+        unadopted.get(zone)?.delete(record.id);
+    };
+    /** Adopts `recordId` when it was seen without an edge row. */
+    const ensureAdopted = async (zone, recordId) => {
+        const record = unadopted.get(zone)?.get(recordId);
+        if (record)
+            await adopt(zone, record);
+    };
+    /** Runs a write; on `not_found` adopts the live record once and retries. */
+    const writeExisting = async (zone, recordId, write) => {
+        await ensureAdopted(zone, recordId);
+        // `forbidden` also answers a revoked or under-scoped platform key, so the
+        // record is listed again and the company message is used only when its
+        // owner really is an organisation; anything else is the original error.
+        const refuseCompanyRecord = async (error) => {
+            if (!isEdgeForbidden(error))
+                throw error;
+            const known = seen.get(zone)?.get(recordId);
+            let owner;
+            try {
+                const { records } = await dns.list({
+                    zone,
+                    ...(known ? { name: known.name, type: known.type } : {}),
+                });
+                remember(zone, records);
+                owner = records.find((r) => r.id === recordId)?.owner;
+            }
+            catch {
+                throw error;
+            }
+            if (owner !== 'organisation')
+                throw error;
+            throw new Error(`edge dns: ${describe(zone, recordId)} is ${OWNED_BY_COMPANY}`);
+        };
+        try {
+            return await writeSlot(write);
+        }
+        catch (error) {
+            if (!isEdgeNotFound(error))
+                return refuseCompanyRecord(error);
+            const live = (await dns.list({ zone })).records;
+            remember(zone, live);
+            const record = live.find((r) => r.id === recordId);
+            if (!record || record.owner !== null)
+                throw error;
+            await adopt(zone, record);
+            try {
+                return await writeSlot(write);
+            }
+            catch (retryError) {
+                return refuseCompanyRecord(retryError);
+            }
+        }
+    };
+    const body = (rec) => ({
+        content: rec.content,
+        ...(rec.proxied === undefined ? {} : { proxied: rec.proxied }),
+        ...(rec.ttl === undefined ? {} : { ttl: rec.ttl }),
+        ...(rec.priority === undefined ? {} : { priority: rec.priority }),
+    });
+    const list = async (zone, opts) => {
+        const { records } = await dns.list({
+            zone,
+            ...(opts?.name ? { name: opts.name } : {}),
+            ...(opts?.type ? { type: opts.type } : {}),
+        });
+        remember(zone, records);
+        return records.map(summary);
+    };
+    return {
+        findDnsRecord: (zone, name, type) => list(zone, { name, type }),
+        listDnsRecords: list,
+        async createDnsRecord(zone, rec) {
+            const created = await writeSlot(() => dns.create({
+                zone,
+                name: rec.name,
+                type: rec.type,
+                ...body(rec),
+            }));
+            return { id: created.id, name: created.name, content: summary(created).content };
+        },
+        async updateDnsRecord(zone, recordId, rec) {
+            const updated = await writeExisting(zone, recordId, () => dns.update(zone, recordId, body(rec)));
+            return { id: updated.id, name: updated.name, content: summary(updated).content };
+        },
+        async deleteDnsRecord(zone, recordId) {
+            await writeExisting(zone, recordId, () => dns.remove(zone, recordId));
+        },
+    };
+}