@wtfalch/edge 0.13.0 → 0.15.1

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type ClientOptions } from './transport.js';
-import type { AccessProviderView, AccessReadinessResponse, AdoptAccessAppsRequest, AdoptAccessAppsResponse, AdoptRateLimitRulesRequest, AdoptRateLimitRulesResponse, AdoptRecordsRequest, AdoptRecordsResponse, AdoptTunnelsRequest, AdoptTunnelsResponse, AdoptWorkersRequest, AdoptWorkersResponse, AdoptZonesRequest, AdoptZonesResponse, AvailableResponse, ClaimNameRequest, CreatePlatformAccessAppRequest, CreatePlatformAccessPolicyRequest, CreatePlatformGateRequest, CreatePlatformRateLimitRuleRequest, CreatePlatformRecordRequest, CreatePlatformServiceTokenRequest, CreatePlatformServiceTokenResponse, CreatePlatformTunnelRequest, CreatePlatformWorkerRouteRequest, CreatePlatformZoneRequest, EnsureAccessProviderRequest, FindServiceTokenResponse, ListClaimsResponse, ListGatesResponse, ListPlatformAccessAppsRequest, ListPlatformAccessAppsResponse, ListPlatformAccessPoliciesResponse, ListPlatformRateLimitRulesRequest, ListPlatformRateLimitRulesResponse, ListPlatformRecordsRequest, ListPlatformRecordsResponse, ListPlatformTunnelsResponse, ListPlatformWorkerRoutesRequest, ListPlatformWorkerRoutesResponse, ListPlatformWorkerScriptsResponse, ListPlatformZonesRequest, ListPlatformZonesResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OneTimePinProviderView, OrgSettingsRequest, PlatformAccessAppView, PlatformAccessPolicyView, PlatformGateView, PlatformRateLimitRuleView, PlatformRecordView, PlatformTunnelView, PlatformWorkerRouteView, PlatformWorkerScriptView, PlatformZoneView, PutPlatformTunnelConfigRequest, RecordInput, RecordPatch, RecordView, ReplacePlatformGateHostnamesRequest, SetGatePeopleResponse, SetPlatformWorkerSchedulesRequest, SetPlatformWorkerSchedulesResponse, SetPlatformWorkerSecretsRequest, SetPlatformWorkerSecretsResponse, TokenResponse, UpdatePlatformRecordRequest, UploadPlatformWorkerScriptRequest } from './types.js';
+import type { AccessProviderView, AccessReadinessResponse, AdoptAccessAppsRequest, AdoptAccessAppsResponse, AdoptRateLimitRulesRequest, AdoptRateLimitRulesResponse, AdoptRecordsRequest, AdoptRecordsResponse, AdoptTunnelsRequest, AdoptTunnelsResponse, AdoptWorkersRequest, AdoptWorkersResponse, AdoptZonesRequest, AdoptZonesResponse, AvailableResponse, ClaimNameRequest, CreatePlatformAccessAppRequest, CreatePlatformAccessPolicyRequest, CreatePlatformGateRequest, CreatePlatformRateLimitRuleRequest, CreatePlatformRecordRequest, CreatePlatformServiceTokenRequest, CreatePlatformServiceTokenResponse, CreatePlatformTunnelRequest, CreatePlatformWorkerRouteRequest, CreatePlatformZoneRequest, EnsureAccessProviderRequest, EnsurePlatformWorkerContainerRequest, EnsureRequestHeaderStripResponse, FindServiceTokenResponse, ListClaimsResponse, ListGatesResponse, ListPlatformAccessAppsRequest, ListPlatformAccessAppsResponse, ListPlatformAccessPoliciesResponse, ListPlatformRateLimitRulesRequest, ListPlatformRateLimitRulesResponse, ListPlatformRecordsRequest, ListPlatformRecordsResponse, ListPlatformTunnelsResponse, ListPlatformWorkerRoutesRequest, ListPlatformWorkerRoutesResponse, ListPlatformWorkerScriptsResponse, ListPlatformZonesRequest, ListPlatformZonesResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OneTimePinProviderView, OrgSettingsRequest, PlatformAccessAppView, PlatformAccessPolicyView, PlatformGateView, PlatformRateLimitRuleView, PlatformRecordView, PlatformTunnelView, PlatformWorkerContainerView, PlatformWorkerRouteView, PlatformWorkerScriptView, PlatformZoneView, PutPlatformTunnelConfigRequest, RecordInput, RecordPatch, RecordView, RemovePlatformWorkerContainerResponse, RemovePlatformWorkerSecretResponse, ReplacePlatformGateHostnamesRequest, RequestHeaderStripRule, SetGatePeopleResponse, SetPlatformWorkerSchedulesRequest, SetPlatformWorkerSchedulesResponse, SetPlatformWorkerSecretsRequest, SetPlatformWorkerSecretsResponse, TokenResponse, UpdatePlatformRecordRequest, UploadPlatformWorkerScriptRequest } from './types.js';
 export { EdgeApiError, type ClientOptions } from './transport.js';
 /** Called with an entry's key: the key carries its organisation and domain, so
  * no call names either. `setReservedLabels`, `mintKey` and `revokeKey` are
@@ -138,6 +138,16 @@ export declare function createEdgeClient(options: ClientOptions): {
              * Cloudflare, and anything nobody names is left alone. */
             adopt: (input: AdoptRateLimitRulesRequest) => Promise<AdoptRateLimitRulesResponse>;
         };
+        /** Request-header Transform Rules in a zone. */
+        requestHeaders: {
+            /** Keeps one rule, named by `rule.description`, that removes `rule.headers`
+             * from requests matching `rule.expression` (the zone's
+             * `http_request_late_transform` phase). Creates the rule, or rewrites it
+             * when it exists; no other rule in the zone changes. Safe to repeat. Needs
+             * the platform credential. Rejects with `conflict` (reason
+             * `upstream_rejected`) when Cloudflare refuses the rule for good. */
+            ensureRequestHeaderStrip: (zoneId: string, rule: RequestHeaderStripRule) => Promise<EnsureRequestHeaderStripResponse>;
+        };
         /** Cloudflare zones the platform made or adopted. A zone is the root of a
          * company's domain, so there is no delete. A zone's `id` is Cloudflare's zone id. */
         zones: {
@@ -177,8 +187,14 @@ export declare function createEdgeClient(options: ClientOptions): {
              * one is skipped (`changed: false`); a new version sets the value again.
              * Survives `uploadScript` redeploys. Deleting the script removes them. */
             setSecrets: (name: string, input: SetPlatformWorkerSecretsRequest) => Promise<SetPlatformWorkerSecretsResponse>;
+            /** Removes one secret of a script edge owns. Safe to repeat: a secret that is gone counts as removed. Rejects with `not_found` when edge does not own an active script of that name. */
+            removeSecret: (name: string, secret: string, organisationId?: string) => Promise<RemovePlatformWorkerSecretResponse>;
+            /** Creates the container application of the Durable Object class `className` the script exports (201), or brings the one that exists to the image, instance type and cap (200). Safe to repeat, and a repeat finishes a call that failed halfway. Rejects with `not_found` when the script exports no such class. */
+            ensureContainer: (name: string, className: string, input: EnsurePlatformWorkerContainerRequest) => Promise<PlatformWorkerContainerView>;
+            /** Deletes a container application of a script edge owns. One that is gone counts as removed; one that serves no edge script rejects with `not_found`. */
+            removeContainer: (id: string, organisationId?: string) => Promise<RemovePlatformWorkerContainerResponse>;
             /** Deletes the script, its cron triggers and the KV namespaces edge created for it; returns the tombstone. Repeating it rejects with `not_found`. */
-            removeScript: (name: string) => Promise<PlatformWorkerScriptView>;
+            removeScript: (name: string, organisationId?: string) => Promise<PlatformWorkerScriptView>;
             /** Every live route in the zone with its owner (`null`: no row), optionally only one pattern. */
             listRoutes: (filter: ListPlatformWorkerRoutesRequest) => Promise<ListPlatformWorkerRoutesResponse>;
             /** Creates the route, or returns the one edge already made for that
@@ -186,7 +202,7 @@ export declare function createEdgeClient(options: ClientOptions): {
              * holds the pattern that nobody adopted (adopt it instead). */
             createRoute: (input: CreatePlatformWorkerRouteRequest) => Promise<PlatformWorkerRouteView>;
             /** Deletes the route in `zoneId`; returns the tombstone. Repeating it rejects with `not_found`. */
-            removeRoute: (zoneId: string, id: string) => Promise<PlatformWorkerRouteView>;
+            removeRoute: (zoneId: string, id: string, organisationId?: string) => Promise<PlatformWorkerRouteView>;
             /** Writes platform rows for the scripts and routes named. Nothing is
              * deleted or recreated, and anything nobody names is left alone. */
             adopt: (input: AdoptWorkersRequest) => Promise<AdoptWorkersResponse>;

package/dist/client.js

@@ -143,6 +143,21 @@ export function createEdgeClient(options) {
                  * Cloudflare, and anything nobody names is left alone. */
                 adopt: (input) => call('POST', '/v1/platform/ratelimits/adopt', input),
             },
+            /** Request-header Transform Rules in a zone. */
+            requestHeaders: {
+                /** Keeps one rule, named by `rule.description`, that removes `rule.headers`
+                 * from requests matching `rule.expression` (the zone's
+                 * `http_request_late_transform` phase). Creates the rule, or rewrites it
+                 * when it exists; no other rule in the zone changes. Safe to repeat. Needs
+                 * the platform credential. Rejects with `conflict` (reason
+                 * `upstream_rejected`) when Cloudflare refuses the rule for good. */
+                ensureRequestHeaderStrip: (zoneId, rule) => call('PUT', '/v1/platform/transforms/request-headers', {
+                    zoneId,
+                    description: rule.description,
+                    expression: rule.expression,
+                    headers: rule.headers,
+                }),
+            },
             /** Cloudflare zones the platform made or adopted. A zone is the root of a
              * company's domain, so there is no delete. A zone's `id` is Cloudflare's zone id. */
             zones: {
@@ -180,8 +195,14 @@ export function createEdgeClient(options) {
                  * one is skipped (`changed: false`); a new version sets the value again.
                  * Survives `uploadScript` redeploys. Deleting the script removes them. */
                 setSecrets: (name, input) => call('PUT', `/v1/platform/workers/scripts/${encodeURIComponent(name)}/secrets`, input),
+                /** Removes one secret of a script edge owns. Safe to repeat: a secret that is gone counts as removed. Rejects with `not_found` when edge does not own an active script of that name. */
+                removeSecret: (name, secret, organisationId) => call('DELETE', `/v1/platform/workers/scripts/${encodeURIComponent(name)}/secrets/${encodeURIComponent(secret)}${organisationId === undefined ? '' : `?${new URLSearchParams({ organisationId })}`}`),
+                /** Creates the container application of the Durable Object class `className` the script exports (201), or brings the one that exists to the image, instance type and cap (200). Safe to repeat, and a repeat finishes a call that failed halfway. Rejects with `not_found` when the script exports no such class. */
+                ensureContainer: (name, className, input) => call('PUT', `/v1/platform/workers/scripts/${encodeURIComponent(name)}/containers/${encodeURIComponent(className)}`, input),
+                /** Deletes a container application of a script edge owns. One that is gone counts as removed; one that serves no edge script rejects with `not_found`. */
+                removeContainer: (id, organisationId) => call('DELETE', `/v1/platform/workers/containers/${encodeURIComponent(id)}${organisationId === undefined ? '' : `?${new URLSearchParams({ organisationId })}`}`),
                 /** Deletes the script, its cron triggers and the KV namespaces edge created for it; returns the tombstone. Repeating it rejects with `not_found`. */
-                removeScript: (name) => call('DELETE', `/v1/platform/workers/scripts/${encodeURIComponent(name)}`),
+                removeScript: (name, organisationId) => call('DELETE', `/v1/platform/workers/scripts/${encodeURIComponent(name)}${organisationId === undefined ? '' : `?${new URLSearchParams({ organisationId })}`}`),
                 /** Every live route in the zone with its owner (`null`: no row), optionally only one pattern. */
                 listRoutes: (filter) => call('GET', `/v1/platform/workers/routes?${new URLSearchParams(Object.entries(filter).filter((entry) => entry[1] !== undefined))}`),
                 /** Creates the route, or returns the one edge already made for that
@@ -189,7 +210,7 @@ export function createEdgeClient(options) {
                  * holds the pattern that nobody adopted (adopt it instead). */
                 createRoute: (input) => call('POST', '/v1/platform/workers/routes', input),
                 /** Deletes the route in `zoneId`; returns the tombstone. Repeating it rejects with `not_found`. */
-                removeRoute: (zoneId, id) => call('DELETE', `/v1/platform/workers/routes/${encodeURIComponent(id)}?${new URLSearchParams({ zoneId })}`),
+                removeRoute: (zoneId, id, organisationId) => call('DELETE', `/v1/platform/workers/routes/${encodeURIComponent(id)}?${new URLSearchParams({ zoneId, ...(organisationId === undefined ? {} : { organisationId }) })}`),
                 /** Writes platform rows for the scripts and routes named. Nothing is
                  * deleted or recreated, and anything nobody names is left alone. */
                 adopt: (input) => call('POST', '/v1/platform/workers/adopt', input),

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './client.js';
+export * from './worker-app-port.js';
 export type * from './types.js';

package/dist/index.js

@@ -1 +1,2 @@
 export * from './client.js';
+export * from './worker-app-port.js';

package/dist/transport.d.ts

@@ -5,6 +5,8 @@ export interface ClientOptions {
     /** The entry's key (foundry's `EDGE_API_KEY`), or the platform credential. */
     apiKey: string;
     fetch?: typeof fetch;
+    /** Every call is cut off after this long and rejects with `unavailable`. Default 120 s. */
+    timeoutMs?: number;
 }
 /** A typed failure, never a bare `Error`. `status` is the HTTP status; `code`
  * and `message` are the service's own wire error (see `EdgeError`). */

package/dist/transport.js

@@ -59,14 +59,24 @@ function errorFrom(value) {
  * every request. No Node-only imports -- this runs in a browser too. */
 export function createTransport(options) {
     return async (method, path, input) => {
-        const response = await (options.fetch ?? fetch)(new URL(path.replace(/^\//, ''), options.url.endsWith('/') ? options.url : `${options.url}/`), {
-            method,
-            headers: {
-                authorization: `Bearer ${options.apiKey}`,
-                ...(input === undefined ? {} : { 'content-type': 'application/json' }),
-            },
-            body: input === undefined ? undefined : JSON.stringify(input),
-        });
+        let response;
+        try {
+            response = await (options.fetch ?? fetch)(new URL(path.replace(/^\//, ''), options.url.endsWith('/') ? options.url : `${options.url}/`), {
+                method,
+                headers: {
+                    authorization: `Bearer ${options.apiKey}`,
+                    ...(input === undefined ? {} : { 'content-type': 'application/json' }),
+                },
+                body: input === undefined ? undefined : JSON.stringify(input),
+                signal: AbortSignal.timeout(options.timeoutMs ?? 120_000),
+            });
+        }
+        catch (error) {
+            // Only the timeout is typed here; any other failure reaches the caller as it was.
+            if (error instanceof Error && error.name === 'TimeoutError')
+                throw new EdgeApiError(0, 'unavailable', 'Request timed out');
+            throw error;
+        }
         let value;
         try {
             value = response.status === 204 ? undefined : await response.json();

package/dist/types.d.ts

@@ -502,6 +502,8 @@ export interface PlatformWorkerScriptView {
     /** The company the script serves; `'platform'` when none. `null` for a script with no row. */
     organisationId: string | null;
     state: 'pending' | 'active' | 'removing' | 'removed';
+    /** The Durable Object migration tag the live script holds, read from Cloudflare by `listScripts`. Absent when it has none. */
+    migrationTag?: string;
 }
 export interface ListPlatformWorkerScriptsResponse {
     scripts: PlatformWorkerScriptView[];
@@ -531,8 +533,30 @@ export interface WorkerPlainTextBinding {
     name: string;
     text: string;
 }
+/** A Durable Object namespace for a class the script exports. The class must come from a migration (this upload's or an earlier one). */
+export interface WorkerDurableObjectBinding {
+    type: 'durable_object_namespace';
+    name: string;
+    /** The exported class name. */
+    class_name: string;
+}
 /** Everything `uploadScript` accepts in `bindings`. Secrets are not here: see `setSecrets`. */
-export type WorkerBinding = WorkerRateLimitBinding | WorkerKvBinding | WorkerPlainTextBinding;
+export type WorkerBinding = WorkerRateLimitBinding | WorkerKvBinding | WorkerPlainTextBinding | WorkerDurableObjectBinding;
+/** A Durable Object migration applied with the upload. `oldTag` is the tag the
+ * live script holds now (omit for a script with none): Cloudflare refuses the
+ * upload when it is not. Send only the steps not yet applied. */
+export interface WorkerMigrations {
+    oldTag?: string;
+    newTag: string;
+    steps: Array<{
+        newSqliteClasses?: string[];
+        deletedClasses?: string[];
+        renamedClasses?: Array<{
+            from: string;
+            to: string;
+        }>;
+    }>;
+}
 /** Uploads (or redeploys) a script. Edge fetches nothing: the caller sends the
  * script, edge checks its size and sha256, and sends it to Cloudflare. The body
  * is never stored or returned. */
@@ -545,6 +569,10 @@ export interface UploadPlatformWorkerScriptRequest {
     compatibilityDate: string;
     /** The script's bindings, all of them: a redeploy replaces the list. Secrets set by `setSecrets` survive a redeploy. */
     bindings?: WorkerBinding[];
+    /** Runtime flags like `nodejs_compat`, all of them: a redeploy replaces the list. */
+    compatibilityFlags?: string[];
+    /** Durable Object migrations to apply with this upload. */
+    migrations?: WorkerMigrations;
     /** The company the script serves. Omit for a script that serves none. */
     organisationId?: string;
 }
@@ -552,6 +580,8 @@ export interface UploadPlatformWorkerScriptRequest {
 export interface SetPlatformWorkerSchedulesRequest {
     /** Up to 50 expressions of five fields, like `* * * * *`. Duplicates collapse. */
     crons: string[];
+    /** The company the script serves; edge refuses the call when the script serves another. Omit for a script that serves none. */
+    organisationId?: string;
 }
 export interface SetPlatformWorkerSchedulesResponse {
     name: string;
@@ -574,6 +604,8 @@ export interface PlatformWorkerSecretInput {
 export interface SetPlatformWorkerSecretsRequest {
     /** 1 to 50 secrets, names unique. */
     secrets: PlatformWorkerSecretInput[];
+    /** The company the script serves; edge refuses the call when the script serves another. Omit for a script that serves none. */
+    organisationId?: string;
 }
 export interface PlatformWorkerSecretView {
     name: string;
@@ -585,6 +617,39 @@ export interface SetPlatformWorkerSecretsResponse {
     name: string;
     secrets: PlatformWorkerSecretView[];
 }
+export interface RemovePlatformWorkerSecretResponse {
+    name: string;
+    secret: string;
+    removed: true;
+}
+/** The container application of one Durable Object class on a script edge owns. */
+export interface EnsurePlatformWorkerContainerRequest {
+    /** `registry.cloudflare.com/<platform account id>/<repository>@sha256:<digest>`: a digest, never a tag, under the platform account's own path. */
+    image: string;
+    /** `lite`, `basic`, `standard-1`, `standard-2`, `standard-3` or `standard-4`. */
+    instanceType: string;
+    /** 1 to 1000. */
+    maxInstances: number;
+    /** The company the script serves; edge refuses the call when the script serves another. Omit for a script that serves none. */
+    organisationId?: string;
+}
+export interface PlatformWorkerContainerView {
+    /** Cloudflare's application id: what `removeContainer` takes. */
+    id: string;
+    script: string;
+    className: string;
+    image: string;
+    instanceType: string;
+    maxInstances: number;
+    /** True when this call made the application. */
+    created: boolean;
+    /** True when this call started a rollout to a new image or instance type. */
+    rolledOut: boolean;
+}
+export interface RemovePlatformWorkerContainerResponse {
+    id: string;
+    removed: true;
+}
 /** A Workers route seen with the platform credential. `id` is Cloudflare's
  * route id, which every platform route call takes. */
 export interface PlatformWorkerRouteView {
@@ -698,6 +763,19 @@ export interface CreatePlatformRateLimitRuleRequest {
     /** The company the rule serves. Omit for a rule that serves none. */
     organisationId?: string;
 }
+/** A rule that removes request headers from every request its expression matches. */
+export interface RequestHeaderStripRule {
+    /** Names the rule in the zone: the key that makes a repeat safe. 1 to 500 printable characters. */
+    description: string;
+    /** Cloudflare's rule expression, 1 to 4096 printable characters. */
+    expression: string;
+    /** 1 to 20 header names of letters, digits and hyphens. */
+    headers: readonly string[];
+}
+export interface EnsureRequestHeaderStripResponse {
+    /** Cloudflare's rule id. */
+    id: string;
+}
 export interface AdoptRateLimitRuleEntry {
     zoneId: string;
     /** Match the live rule by description, by id, or both. At least one is needed. */

package/dist/worker-app-port.d.ts

@@ -0,0 +1,81 @@
+import type { createEdgeClient } from './client.js';
+import type { WorkerBinding, WorkerMigrations } from './types.js';
+/** The edge SDK's platform Workers client: `createEdgeClient({ ... }).platform.workers`. */
+export type EdgePlatformWorkers = ReturnType<typeof createEdgeClient>['platform']['workers'];
+/** What foundry's `WorkerAppPort.uploadWorkerApp` receives. */
+export interface WorkerAppUploadInput {
+    name: string;
+    artifactUrl: string;
+    /** 64 hex characters. */
+    artifactSha256: string;
+    compatibilityDate: string;
+    compatibilityFlags: string[];
+    bindings: WorkerBinding[];
+    migrations?: WorkerMigrations;
+}
+export interface WorkerAppContainerInput {
+    className: string;
+    /** `<repository>@sha256:<digest>`. */
+    image: string;
+    instanceType: string;
+    maxInstances: number;
+    scriptName: string;
+}
+/**
+ * Foundry's `WorkerAppPort` (packages/foundry/src/plan/worker-app.ts), repeated
+ * structurally so a host passes {@link createWorkerAppPort}'s result straight in.
+ * Every method is idempotent.
+ */
+export interface WorkerAppPort {
+    scriptExists(name: string): Promise<boolean>;
+    findRoute(zoneId: string, pattern: string): Promise<{
+        id: string;
+        script?: string;
+    } | undefined>;
+    createRoute(zoneId: string, pattern: string, script?: string): Promise<{
+        id: string;
+    }>;
+    deleteRoute(zoneId: string, routeId: string): Promise<void>;
+    deleteScript(name: string): Promise<void>;
+    uploadWorkerApp(input: WorkerAppUploadInput): Promise<void>;
+    liveMigrationTag(name: string): Promise<string | undefined>;
+    setSecrets(name: string, secrets: readonly {
+        name: string;
+        value: string;
+        version: string;
+    }[]): Promise<void>;
+    deleteSecret(name: string, secretName: string): Promise<void>;
+    ensureContainerApplication(input: WorkerAppContainerInput): Promise<{
+        id: string;
+    }>;
+    deleteContainerApplication(id: string): Promise<void>;
+}
+export interface WorkerAppPortOptions {
+    /** The company every call acts for. Edge refuses a call on a script, route or container that serves another. */
+    organisationId: string;
+    /** A read-only GitHub token for the artifact repositories. Sent to api.github.com and nowhere else. */
+    githubToken: string;
+    fetch?: typeof fetch;
+    /** The artifact download is cut off after this long. Default 60 s. */
+    artifactTimeoutMs?: number;
+    /** Larger artifacts are refused. Default 10 MB, edge's own cap. */
+    maxArtifactBytes?: number;
+}
+/** The artifact could not be fetched, or is not the artifact declared. Carries no bytes and no credential. */
+export declare class WorkerAppArtifactError extends Error {
+    constructor(message: string);
+}
+/**
+ * Foundry's `WorkerAppPort` over edge's `platform.workers`. The adapter
+ * fetches the module itself (from a private GitHub release, with `githubToken`) and checks its sha256 before anything is sent: a
+ * mismatch throws {@link WorkerAppArtifactError} and edge is never called.
+ * Edge checks the digest again. Secret values go to edge and nowhere else; no
+ * error made here carries one, or the API key.
+ *
+ * A script or route that exists with no edge row is not adopted: the upload
+ * answers `conflict`, and the caller sees it. `not_found` on a delete counts as
+ * gone. Every call is bounded by the client's `timeoutMs`; a failure halfway
+ * (the upload done, the container call refused) throws, and repeating the
+ * port call finishes the rest because every method is idempotent.
+ */
+export declare function createWorkerAppPort(workers: EdgePlatformWorkers, options: WorkerAppPortOptions): WorkerAppPort;

package/dist/worker-app-port.js

@@ -0,0 +1,285 @@
+import { EdgeApiError } from './transport.js';
+/** The artifact could not be fetched, or is not the artifact declared. Carries no bytes and no credential. */
+export class WorkerAppArtifactError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WorkerAppArtifactError';
+    }
+}
+const SHA256 = /^[0-9a-f]{64}$/i;
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const isNotFound = (error) => error instanceof EdgeApiError && error.code === 'not_found';
+const toHex = (buffer) => [...new Uint8Array(buffer)].map((b) => b.toString(16).padStart(2, '0')).join('');
+function toBase64(bytes) {
+    let text = '';
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        text += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(text);
+}
+const GITHUB_OWNER = 'wtfalch';
+const GITHUB_PATH = /^\/wtfalch\/([A-Za-z0-9._-]+)\/releases\/download\/([^/]+)\/([^/]+)$/;
+/** Where GitHub sends a release asset download. Source: GitHub's list of domains for
+ * runners (https://docs.github.com/en/actions/reference/runners/github-hosted-runners).
+ * The asset endpoint answers 302 or streams (https://docs.github.com/en/rest/releases/assets). */
+const ASSET_HOSTS = new Set([
+    'release-assets.githubusercontent.com',
+    'objects.githubusercontent.com',
+    'objects-origin.githubusercontent.com',
+    'github-releases.githubusercontent.com',
+]);
+const MAX_REDIRECTS = 3;
+/** `https://github.com/wtfalch/<repo>/releases/download/<tag>/<file>` and nothing else. */
+function parseArtifactUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new WorkerAppArtifactError('artifactUrl is not a URL');
+    }
+    if (parsed.protocol !== 'https:')
+        throw new WorkerAppArtifactError('artifactUrl must be https');
+    if (parsed.hostname !== 'github.com' ||
+        parsed.port !== '' ||
+        parsed.username !== '' ||
+        parsed.password !== '' ||
+        parsed.search !== '' ||
+        parsed.hash !== '')
+        throw new WorkerAppArtifactError(`artifactUrl must be https://github.com/${GITHUB_OWNER}/<repo>/releases/download/<tag>/<file>`);
+    const match = GITHUB_PATH.exec(parsed.pathname);
+    if (!match)
+        throw new WorkerAppArtifactError(`artifactUrl must be https://github.com/${GITHUB_OWNER}/<repo>/releases/download/<tag>/<file>`);
+    let tag;
+    let file;
+    try {
+        tag = decodeURIComponent(match[2]);
+        file = decodeURIComponent(match[3]);
+    }
+    catch {
+        throw new WorkerAppArtifactError('artifactUrl is not a GitHub release asset URL');
+    }
+    if ([tag, file].some((part) => part === '.' || part === '..' || part.includes('/')))
+        throw new WorkerAppArtifactError('artifactUrl is not a GitHub release asset URL');
+    return { repo: match[1], tag, file };
+}
+/** A redirect target is an https GitHub asset host by name: no port, no userinfo, no address literal. */
+function checkAssetLocation(location, from) {
+    let target;
+    try {
+        target = new URL(location, from);
+    }
+    catch {
+        throw new WorkerAppArtifactError('artifact redirect is not a URL');
+    }
+    if (target.protocol !== 'https:' ||
+        target.port !== '' ||
+        target.username !== '' ||
+        target.password !== '' ||
+        !ASSET_HOSTS.has(target.hostname))
+        throw new WorkerAppArtifactError('artifact redirect to a host that is not GitHub asset storage');
+    return target;
+}
+/** Reads the body, aborting at `max` bytes without buffering the rest. */
+async function readCapped(response, max) {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > max) {
+        await response.body?.cancel();
+        throw new WorkerAppArtifactError(`artifact must be 1 byte to ${max} bytes`);
+    }
+    if (!response.body)
+        throw new WorkerAppArtifactError('artifact fetch failed');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.length;
+        if (total > max) {
+            await reader.cancel();
+            throw new WorkerAppArtifactError(`artifact must be 1 byte to ${max} bytes`);
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return bytes;
+}
+/**
+ * Fetches the release asset through GitHub's API and refuses it unless its
+ * sha256 is the declared one. The token goes to api.github.com only; the
+ * download redirect is followed by hand, to GitHub's asset hosts only, and
+ * without the token.
+ */
+async function fetchVerified(url, sha256, options) {
+    if (!SHA256.test(sha256))
+        throw new WorkerAppArtifactError('artifactSha256 must be 64 hex digits');
+    const { repo, tag, file } = parseArtifactUrl(url);
+    const max = options.maxArtifactBytes ?? DEFAULT_MAX_BYTES;
+    const doFetch = options.fetch ?? fetch;
+    const signal = AbortSignal.timeout(options.artifactTimeoutMs ?? 60_000);
+    const api = (path, accept) => doFetch(`https://api.github.com/repos/${GITHUB_OWNER}/${repo}/${path}`, {
+        redirect: 'manual',
+        signal,
+        headers: {
+            Accept: accept,
+            Authorization: `Bearer ${options.githubToken}`,
+            'X-GitHub-Api-Version': '2022-11-28',
+            'User-Agent': 'edge-worker-app-port',
+        },
+    });
+    let bytes;
+    try {
+        const release = await api(`releases/tags/${encodeURIComponent(tag)}`, 'application/vnd.github+json');
+        if (!release.ok)
+            throw new WorkerAppArtifactError(`artifact release lookup answered status ${release.status}`);
+        const assets = (await release.json())
+            .assets;
+        const asset = assets?.find((a) => a.name === file);
+        if (!asset || typeof asset.id !== 'number' || !Number.isSafeInteger(asset.id))
+            throw new WorkerAppArtifactError('the release has no asset of that name');
+        let response = await api(`releases/assets/${asset.id}`, 'application/octet-stream');
+        let from = new URL(`https://api.github.com/repos/${GITHUB_OWNER}/${repo}/releases/assets/${asset.id}`);
+        for (let hops = 0; response.status >= 300 && response.status < 400; hops++) {
+            const location = response.headers.get('location');
+            await response.body?.cancel();
+            if (!location || hops >= MAX_REDIRECTS)
+                throw new WorkerAppArtifactError('artifact fetch failed');
+            from = checkAssetLocation(location, from);
+            // No Authorization header: the asset host never sees the token.
+            response = await doFetch(from, { redirect: 'manual', signal });
+        }
+        if (!response.ok)
+            throw new WorkerAppArtifactError(`artifact fetch answered status ${response.status}`);
+        bytes = await readCapped(response, max);
+    }
+    catch (error) {
+        if (error instanceof WorkerAppArtifactError)
+            throw error;
+        // The cause is dropped: it can carry a signed download URL.
+        throw new WorkerAppArtifactError(error instanceof Error && error.name === 'TimeoutError'
+            ? 'artifact fetch timed out'
+            : 'artifact fetch failed');
+    }
+    if (bytes.length === 0 || bytes.length > max)
+        throw new WorkerAppArtifactError(`artifact must be 1 byte to ${max} bytes`);
+    const actual = toHex(await crypto.subtle.digest('SHA-256', bytes));
+    if (actual !== sha256.toLowerCase())
+        throw new WorkerAppArtifactError(`artifact sha256 ${actual} is not the declared ${sha256.toLowerCase()}`);
+    return bytes;
+}
+/**
+ * Foundry's `WorkerAppPort` over edge's `platform.workers`. The adapter
+ * fetches the module itself (from a private GitHub release, with `githubToken`) and checks its sha256 before anything is sent: a
+ * mismatch throws {@link WorkerAppArtifactError} and edge is never called.
+ * Edge checks the digest again. Secret values go to edge and nowhere else; no
+ * error made here carries one, or the API key.
+ *
+ * A script or route that exists with no edge row is not adopted: the upload
+ * answers `conflict`, and the caller sees it. `not_found` on a delete counts as
+ * gone. Every call is bounded by the client's `timeoutMs`; a failure halfway
+ * (the upload done, the container call refused) throws, and repeating the
+ * port call finishes the rest because every method is idempotent.
+ */
+export function createWorkerAppPort(workers, options) {
+    const org = options.organisationId;
+    // A script that serves another organisation is not visible: edge would refuse the upload anyway.
+    const liveScript = async (name) => {
+        const { scripts } = await workers.listScripts({ name });
+        return scripts.find((s) => s.name === name &&
+            s.state !== 'removed' &&
+            (s.organisationId === null || s.organisationId === org));
+    };
+    return {
+        async scriptExists(name) {
+            return (await liveScript(name)) !== undefined;
+        },
+        async findRoute(zoneId, pattern) {
+            const { routes } = await workers.listRoutes({ zoneId, pattern });
+            const route = routes.find((r) => r.pattern === pattern &&
+                r.state !== 'removed' &&
+                (r.organisationId === null || r.organisationId === org));
+            return route
+                ? { id: route.id, ...(route.script ? { script: route.script } : {}) }
+                : undefined;
+        },
+        async createRoute(zoneId, pattern, script) {
+            const route = await workers.createRoute({
+                zoneId,
+                pattern,
+                organisationId: org,
+                ...(script ? { script } : {}),
+            });
+            return { id: route.id };
+        },
+        async deleteRoute(zoneId, routeId) {
+            try {
+                await workers.removeRoute(zoneId, routeId, org);
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+            }
+        },
+        async deleteScript(name) {
+            try {
+                await workers.removeScript(name, org);
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+            }
+        },
+        async uploadWorkerApp(input) {
+            const bytes = await fetchVerified(input.artifactUrl, input.artifactSha256, options);
+            await workers.uploadScript(input.name, {
+                script: toBase64(bytes),
+                organisationId: org,
+                artifactSha256: input.artifactSha256.toLowerCase(),
+                compatibilityDate: input.compatibilityDate,
+                ...(input.compatibilityFlags.length
+                    ? { compatibilityFlags: input.compatibilityFlags }
+                    : {}),
+                bindings: input.bindings,
+                ...(input.migrations ? { migrations: input.migrations } : {}),
+            });
+        },
+        async liveMigrationTag(name) {
+            return (await liveScript(name))?.migrationTag;
+        },
+        async setSecrets(name, secrets) {
+            if (secrets.length === 0)
+                return;
+            await workers.setSecrets(name, {
+                organisationId: org,
+                secrets: secrets.map((s) => ({ ...s })),
+            });
+        },
+        async deleteSecret(name, secretName) {
+            try {
+                await workers.removeSecret(name, secretName, org);
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+            }
+        },
+        async ensureContainerApplication(input) {
+            const { id } = await workers.ensureContainer(input.scriptName, input.className, {
+                organisationId: org,
+                image: input.image,
+                instanceType: input.instanceType,
+                maxInstances: input.maxInstances,
+            });
+            return { id };
+        },
+        async deleteContainerApplication(id) {
+            await workers.removeContainer(id, org);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/edge",
-  "version": "0.13.0",
+  "version": "0.15.1",
   "type": "module",
   "license": "MIT",
   "description": "Public client SDK and API types for the edge service.",
@@ -19,7 +19,9 @@
     "dist/transport.d.ts",
     "dist/transport.js",
     "dist/types.d.ts",
-    "dist/types.js"
+    "dist/types.js",
+    "dist/worker-app-port.d.ts",
+    "dist/worker-app-port.js"
   ],
   "exports": {
     ".": {