@astrale-os/adapter-cloudflare 0.5.0-beta.13 → 0.5.0-beta.131

package/dist/deploy/deploy.js

@@ -0,0 +1,221 @@
+import { addressing, assemble } from '@astrale-os/sdk/deployment/release';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { workerName } from '../build/configuration.js';
+import { admitDirectPlacement } from '../build/direct.js';
+import { loadWorkerArtifact } from '../build/worker/index.js';
+import { signingIdentitySecrets } from '../identity/secret.js';
+import { WranglerDeployError } from '../wrangler/deploy.js';
+import { WranglerRolloutError } from '../wrangler/rollout.js';
+const NONE = Object.freeze({ kind: 'none' });
+/** Deploy one stable Worker target and verify its exact serving implementation. */
+export async function deployCloudflare(parameters, context, dependencies) {
+    let secrets;
+    try {
+        const identity = await dependencies.signingIdentity({
+            projectDir: context.projectDir,
+            source: parameters.signingIdentity,
+            origin: context.artifact.build.schema.compiled.root.origin,
+            mode: 'deploy',
+        });
+        secrets = signingIdentitySecrets(context.secrets, identity);
+    }
+    catch (cause) {
+        return failed('prerequisite', progress({}), cause);
+    }
+    let worker;
+    try {
+        worker = loadWorkerArtifact(context.artifact);
+        for (const name of worker.bindings.requiredSecrets) {
+            if (!Object.hasOwn(secrets, name)) {
+                throw new TypeError(`Cloudflare Worker requires secret ${name}.`);
+            }
+        }
+        admitDirectPlacement(context.artifact, worker, parameters, context.environment);
+    }
+    catch (cause) {
+        return failed('prerequisite', progress({}), cause);
+    }
+    const stateDirectory = join(context.projectDir, '.astrale');
+    await mkdir(stateDirectory, { recursive: true });
+    const directory = await mkdtemp(join(stateDirectory, 'deploy-'));
+    try {
+        await dependencies.materialize(directory, context.artifact.files);
+        const name = workerName(parameters, context.artifact.build.schema.compiled.root.origin, context.environment);
+        const configPath = join(directory, 'wrangler.jsonc');
+        let deployed;
+        try {
+            deployed = await dependencies.runWranglerRollout({
+                projectDir: context.projectDir,
+                configPath,
+                workerName: name,
+                verifyCandidate: async (candidate) => {
+                    const selected = observeAddressing(context.artifact, candidate.url, name);
+                    const release = assemble(context.artifact.build, selected);
+                    await dependencies.waitForReadiness(release, context.signal, candidate.deploymentVersion, worker, name);
+                },
+                secrets,
+                ...(parameters.route === undefined ? {} : { route: parameters.route }),
+                signal: context.signal,
+            });
+        }
+        catch (cause) {
+            return failed(cause instanceof WranglerRolloutError ? cause.phase : 'provider', progress({
+                provider: partialProvider(cause, context.artifact),
+                ...(cause instanceof WranglerRolloutError
+                    ? {
+                        configuration: Object.freeze({
+                            kind: 'partial',
+                            evidence: { names: Object.keys(secrets).sort() },
+                        }),
+                    }
+                    : {}),
+            }), cause);
+        }
+        const configuration = Object.freeze({
+            kind: 'applied',
+            evidence: Object.freeze({ names: Object.keys(secrets).sort() }),
+        });
+        const retained = Object.freeze({
+            kind: 'partial',
+            evidence: Object.freeze({
+                provider: 'cloudflare',
+                deployment: deployed.deploymentVersion,
+                artifact: context.artifact.digest,
+            }),
+        });
+        let selected;
+        try {
+            selected = observeAddressing(context.artifact, deployed.url, name);
+        }
+        catch (cause) {
+            return failed('addressing', progress({
+                provider: retained,
+                configuration,
+            }), cause);
+        }
+        let observed;
+        try {
+            observed = await dependencies.runWranglerDeploymentStatus({
+                projectDir: context.projectDir,
+                configPath,
+                workerName: name,
+                signal: context.signal,
+            });
+            requireCurrentDeployment(observed, deployed.deploymentVersion);
+        }
+        catch (cause) {
+            return failed('readiness', progress({
+                provider: retained,
+                configuration,
+            }), cause);
+        }
+        let release;
+        try {
+            release = assemble(context.artifact.build, selected);
+        }
+        catch (cause) {
+            return failed('release', progress({ provider: retained, configuration }), cause);
+        }
+        try {
+            await dependencies.waitForReadiness(release, context.signal, deployed.deploymentVersion, worker);
+        }
+        catch (cause) {
+            return failed('readiness', progress({ provider: retained, configuration }), cause, release);
+        }
+        const provider = Object.freeze({
+            kind: 'applied',
+            evidence: Object.freeze({
+                provider: 'cloudflare',
+                deployment: deployed.deploymentVersion,
+                artifact: context.artifact.digest,
+                issuer: selected.issuer,
+            }),
+        });
+        return Object.freeze({
+            status: 'ready',
+            phase: 'complete',
+            progress: Object.freeze({ ...progress({ configuration }), provider }),
+            release,
+        });
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+function partialProvider(cause, artifact) {
+    if (!(cause instanceof WranglerDeployError) || cause.applied?.deploymentVersion === undefined) {
+        return Object.freeze({ kind: 'unknown' });
+    }
+    let issuer;
+    if (cause.applied.url !== undefined) {
+        try {
+            issuer = addressing(cause.applied.url).issuer;
+        }
+        catch {
+            // The provider effect remains known when its printed URL is not Addressing.
+        }
+    }
+    return Object.freeze({
+        kind: 'partial',
+        evidence: Object.freeze({
+            provider: 'cloudflare',
+            deployment: cause.applied.deploymentVersion,
+            artifact: artifact.digest,
+            ...(issuer === undefined ? {} : { issuer }),
+        }),
+    });
+}
+function requireCurrentDeployment(observed, expectedVersion) {
+    if (observed.versions.length !== 1 ||
+        observed.versions[0].percentage !== 100 ||
+        observed.versions[0].version !== expectedVersion) {
+        throw new TypeError('Cloudflare Worker is not one exact version at 100%.');
+    }
+}
+function observeAddressing(artifact, deployedUrl, expectedWorker) {
+    if (artifact.addressing.kind === 'configured') {
+        if (deployedUrl === undefined)
+            return artifact.addressing.addressing;
+        const observed = addressing(deployedUrl);
+        if (observed.issuer !== artifact.addressing.addressing.issuer) {
+            throw new TypeError('Cloudflare deployed URL differs from configured Addressing.');
+        }
+        return observed;
+    }
+    if (deployedUrl === undefined) {
+        throw new TypeError('Cloudflare did not report provider-assigned Addressing.');
+    }
+    const observed = addressing(deployedUrl);
+    if (artifact.addressing.claim !== expectedWorker) {
+        throw new TypeError('PreparedArtifact worker claim differs from the deployment target.');
+    }
+    const url = new URL(observed.issuer);
+    const labels = url.hostname.split('.');
+    if (url.protocol !== 'https:' ||
+        labels.length < 4 ||
+        labels[0] !== artifact.addressing.claim ||
+        labels.at(-2) !== 'workers' ||
+        labels.at(-1) !== 'dev') {
+        throw new TypeError('Cloudflare workers.dev URL does not satisfy its prepared worker claim.');
+    }
+    return observed;
+}
+function progress(input) {
+    return Object.freeze({
+        prerequisite: input.prerequisite ?? NONE,
+        provider: input.provider ?? NONE,
+        configuration: input.configuration ?? NONE,
+        installation: input.installation ?? NONE,
+    });
+}
+function failed(phase, progressValue, cause, release) {
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    return Object.freeze({
+        status: 'failed',
+        phase,
+        progress: progressValue,
+        error,
+        ...(release === undefined ? {} : { release }),
+    });
+}

package/dist/deploy/index.d.ts

@@ -0,0 +1 @@
+export { deployCloudflare, type CloudflareDeployDependencies } from './deploy.js';

package/dist/deploy/index.js

@@ -0,0 +1 @@
+export { deployCloudflare } from './deploy.js';

package/dist/deploy/output.d.ts

@@ -0,0 +1,2 @@
+export declare function parseDeployUrl(text: string, route?: string): string | undefined;
+export declare function parseDeployVersionId(text: string): string | undefined;

package/dist/deploy/output.js

@@ -0,0 +1,10 @@
+const WORKERS_DEV_RE = /(https:\/\/[^\s]+\.workers\.dev)/iu;
+const VERSION_ID_RE = /(?:Current\s+)?Version ID:\s*([a-z0-9_-]+)/iu;
+export function parseDeployUrl(text, route) {
+    if (route !== undefined)
+        return `https://${route.replace(/\/.*$/u, '')}`;
+    return WORKERS_DEV_RE.exec(text)?.[1];
+}
+export function parseDeployVersionId(text) {
+    return VERSION_ID_RE.exec(text)?.[1];
+}

package/dist/deploy/readiness.d.ts

@@ -0,0 +1,5 @@
+import type { verifyReadiness } from '@astrale-os/sdk/deployment/verify';
+type ReadinessFetch = NonNullable<NonNullable<Parameters<typeof verifyReadiness>[1]>['fetch']>;
+/** Readiness is evidence for the provider version, not just a compatible Publication. */
+export declare function versionReadinessFetch(issuer: string, version: string, fetcher?: typeof fetch, workerName?: string): ReadinessFetch;
+export {};

package/dist/deploy/readiness.js

@@ -0,0 +1,18 @@
+/** Readiness is evidence for the provider version, not just a compatible Publication. */
+export function versionReadinessFetch(issuer, version, fetcher = globalThis.fetch, workerName) {
+    return async (input, init) => {
+        if (new URL(input).origin !== issuer) {
+            throw new TypeError('Cloudflare readiness cannot leave the expected Worker origin.');
+        }
+        const headers = new Headers();
+        if (workerName !== undefined) {
+            headers.set('Cloudflare-Workers-Version-Overrides', `${workerName}="${version}"`);
+        }
+        const response = await fetcher(input, workerName === undefined ? init : { ...init, headers });
+        if (response.headers.get('X-Astrale-Worker-Version') !== version) {
+            await response.body?.cancel();
+            throw new Error('Cloudflare readiness response differs from the deployed Worker version.');
+        }
+        return response;
+    };
+}

package/dist/identity/binding.d.ts

@@ -0,0 +1,2 @@
+/** Adapter-owned Worker secret that carries the Domain signing private JWK. */
+export declare const SIGNING_IDENTITY_BINDING = "ASTRALE_SIGNING_IDENTITY";

package/dist/identity/binding.js

@@ -0,0 +1,2 @@
+/** Adapter-owned Worker secret that carries the Domain signing private JWK. */
+export const SIGNING_IDENTITY_BINDING = 'ASTRALE_SIGNING_IDENTITY';

package/dist/identity/index.d.ts

@@ -0,0 +1,3 @@
+/** Dependency-light custody surface for Cloudflare Domain signing identities. */
+export { signingIdentity } from './source.js';
+export { signingIdentitySecrets } from './secret.js';

package/dist/identity/index.js

@@ -0,0 +1,3 @@
+/** Dependency-light custody surface for Cloudflare Domain signing identities. */
+export { signingIdentity } from './source.js';
+export { signingIdentitySecrets } from './secret.js';

package/dist/identity/material.d.ts

@@ -0,0 +1,7 @@
+import type { JsonWebKey } from '@astrale-os/sdk/auth';
+export type SigningIdentityMaterial = JsonWebKey & {
+    readonly kid: string;
+};
+export declare function createSigningIdentity(): Promise<SigningIdentityMaterial>;
+/** Admit private Ed25519 material and its collision-resistant public identity. */
+export declare function admitSigningIdentity(input: unknown, owner: string, legacyKeyId?: string): Promise<SigningIdentityMaterial>;

package/dist/identity/material.js

@@ -0,0 +1,42 @@
+import { calculateJwkThumbprint, exportJWK, generateKeyPair, importJWK } from 'jose';
+export async function createSigningIdentity() {
+    const { privateKey } = await generateKeyPair('EdDSA', { extractable: true });
+    const exported = await exportJWK(privateKey);
+    return admitSigningIdentity({
+        ...exported,
+        alg: 'EdDSA',
+        kid: await calculateJwkThumbprint(exported),
+    }, 'generated identity');
+}
+/** Admit private Ed25519 material and its collision-resistant public identity. */
+export async function admitSigningIdentity(input, owner, legacyKeyId) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid(owner);
+    const value = input;
+    if (value.kty !== 'OKP' ||
+        value.crv !== 'Ed25519' ||
+        value.alg !== 'EdDSA' ||
+        typeof value.x !== 'string' ||
+        value.x.length === 0 ||
+        typeof value.d !== 'string' ||
+        value.d.length === 0) {
+        invalid(owner);
+    }
+    const thumbprint = await calculateJwkThumbprint(value);
+    const admitted = legacyKeyId !== undefined && (value.kid === undefined || value.kid === legacyKeyId)
+        ? { ...value, kid: thumbprint }
+        : value;
+    if (admitted.kid !== thumbprint) {
+        throw new TypeError(`Cloudflare signing identity '${owner}' must use its JWK thumbprint as kid.`);
+    }
+    try {
+        await importJWK(admitted, 'EdDSA');
+    }
+    catch (cause) {
+        throw invalid(owner, cause);
+    }
+    return admitted;
+}
+function invalid(owner, cause) {
+    throw new TypeError(`Cloudflare signing identity '${owner}' is not a private Ed25519 JWK.`, cause === undefined ? undefined : { cause });
+}

package/dist/identity/secret.d.ts

@@ -0,0 +1,3 @@
+import type { SigningIdentitySource } from './source.js';
+/** Add the adapter-owned identity without allowing a second secret authority. */
+export declare function signingIdentitySecrets(secrets: Readonly<Record<string, string>>, identity: SigningIdentitySource): Readonly<Record<string, string>>;

package/dist/identity/secret.js

@@ -0,0 +1,7 @@
+/** Add the adapter-owned identity without allowing a second secret authority. */
+export function signingIdentitySecrets(secrets, identity) {
+    if (Object.hasOwn(secrets, identity.binding)) {
+        throw new TypeError(`${identity.binding} is adapter-owned; configure 'signingIdentity' instead of declaring that secret.`);
+    }
+    return Object.freeze({ ...secrets, [identity.binding]: identity.secret });
+}

package/dist/identity/source.d.ts

@@ -0,0 +1,26 @@
+import { SIGNING_IDENTITY_BINDING } from './binding.js';
+export interface SigningIdentitySource {
+    readonly binding: typeof SIGNING_IDENTITY_BINDING;
+    readonly path: string;
+    readonly secret: string;
+    readonly keyId: string;
+}
+export interface SigningIdentityInput {
+    readonly projectDir: string;
+    readonly origin: string;
+    readonly source?: string;
+    readonly mode: 'local' | 'deploy';
+}
+/** Resolve one admitted Domain signing identity for local or remote provider custody. */
+export declare function signingIdentity(input: SigningIdentityInput): Promise<SigningIdentitySource>;
+/**
+ * Read an explicitly retained deployment identity. Deployment never generates
+ * one: a missing file is a pre-provider configuration failure, not an implicit
+ * key rotation.
+ */
+export declare function readSigningIdentity(projectDir: string, declaration: string | undefined): Promise<SigningIdentitySource>;
+/**
+ * Resolve local development identity. The default is generated once inside
+ * `.astrale`; an explicit source is always read-only and must already exist.
+ */
+export declare function localSigningIdentity(projectDir: string, declaration: string | undefined, origin: string): Promise<SigningIdentitySource>;

package/dist/identity/source.js

@@ -0,0 +1,127 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { link, mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { SIGNING_IDENTITY_BINDING } from './binding.js';
+import { admitSigningIdentity, createSigningIdentity } from './material.js';
+const DEFAULT_IDENTITY = join('.astrale', 'identity.json');
+/** Resolve one admitted Domain signing identity for local or remote provider custody. */
+export function signingIdentity(input) {
+    return input.mode === 'local'
+        ? localSigningIdentity(input.projectDir, input.source, input.origin)
+        : readSigningIdentity(input.projectDir, input.source);
+}
+/**
+ * Read an explicitly retained deployment identity. Deployment never generates
+ * one: a missing file is a pre-provider configuration failure, not an implicit
+ * key rotation.
+ */
+export async function readSigningIdentity(projectDir, declaration) {
+    if (declaration === undefined || declaration.length === 0) {
+        throw new TypeError("Cloudflare deployment requires 'signingIdentity: <private-jwk-file>'. " +
+            'Run local development once to create .astrale/identity.json, then retain that file in managed secret storage.');
+    }
+    return readSource(pathOf(projectDir, declaration), declaration);
+}
+/**
+ * Resolve local development identity. The default is generated once inside
+ * `.astrale`; an explicit source is always read-only and must already exist.
+ */
+export async function localSigningIdentity(projectDir, declaration, origin) {
+    if (declaration !== undefined)
+        return readSource(pathOf(projectDir, declaration), declaration);
+    const path = join(projectDir, DEFAULT_IDENTITY);
+    if (!existsSync(path)) {
+        const legacy = join(projectDir, '.astrale', 'identity.ts');
+        if (existsSync(legacy))
+            await migrateLegacyIdentity(legacy, path, origin);
+        else
+            await generateIdentity(path);
+    }
+    return readSource(path, DEFAULT_IDENTITY);
+}
+async function generateIdentity(path) {
+    const value = await createSigningIdentity();
+    if (await installIdentity(path, value)) {
+        process.stderr.write(`\x1b[33m!\x1b[0m new signing identity generated at .astrale/identity.json (kid ${value.kid}).\n` +
+            `  Retain it in managed secret storage before deploying; remote deploy fails closed without an explicit identity file.\n`);
+    }
+}
+async function migrateLegacyIdentity(legacy, destination, origin) {
+    const source = await readFile(legacy, 'utf8');
+    const match = /export const PRIVATE_JWK = (\{[\s\S]*\}) as const\n?$/u.exec(source);
+    if (match?.[1] === undefined)
+        throw invalidIdentity(legacy);
+    let decoded;
+    try {
+        decoded = JSON.parse(match[1]);
+    }
+    catch (cause) {
+        throw invalidIdentity(legacy, cause);
+    }
+    const value = await admitSigningIdentity(decoded, legacy, `${origin}-key`);
+    if (await installIdentity(destination, value)) {
+        process.stderr.write(`\x1b[33m!\x1b[0m migrated .astrale/identity.ts to secret-backed .astrale/identity.json (kid ${value.kid}).\n`);
+    }
+}
+/** Publish a complete owner-only identity once; concurrent environments reuse the winner. */
+async function installIdentity(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const staging = `${path}.${process.pid}.${randomUUID()}.next`;
+    const file = await open(staging, 'wx', 0o600);
+    try {
+        await file.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+        await file.sync();
+    }
+    catch (cause) {
+        await file.close();
+        await unlink(staging).catch(() => undefined);
+        throw cause;
+    }
+    await file.close();
+    try {
+        await link(staging, path);
+        return true;
+    }
+    catch (cause) {
+        if (!(cause instanceof Error && 'code' in cause && cause.code === 'EEXIST'))
+            throw cause;
+        return false;
+    }
+    finally {
+        await unlink(staging).catch(() => undefined);
+    }
+}
+async function readSource(path, declaration) {
+    let source;
+    try {
+        source = await readFile(path, 'utf8');
+    }
+    catch (cause) {
+        if (!(cause instanceof Error && 'code' in cause && cause.code === 'ENOENT'))
+            throw cause;
+        throw new TypeError(`Cloudflare signing identity '${declaration}' is missing at ${path}.`, {
+            cause,
+        });
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(source);
+    }
+    catch (cause) {
+        throw invalidIdentity(declaration, cause);
+    }
+    const value = await admitSigningIdentity(decoded, declaration);
+    return Object.freeze({
+        binding: SIGNING_IDENTITY_BINDING,
+        path,
+        secret: JSON.stringify(value),
+        keyId: value.kid,
+    });
+}
+function pathOf(projectDir, declaration) {
+    return isAbsolute(declaration) ? declaration : resolve(projectDir, declaration);
+}
+function invalidIdentity(owner, cause) {
+    return new TypeError(`Cloudflare signing identity '${owner}' is not a private Ed25519 JWK.`, cause === undefined ? undefined : { cause });
+}

package/dist/index.d.ts

@@ -1,21 +1,22 @@
 /**
- * `@astrale-os/adapter-cloudflare` — deploy an Astrale domain as a standalone
- * Cloudflare Worker on YOUR OWN Cloudflare account.
+ * `@astrale-os/adapter-cloudflare` — deploy an Astrale application through
+ * Cloudflare Workers on YOUR OWN Cloudflare account.
  *
  *   import { cloudflare } from '@astrale-os/adapter-cloudflare'
  *
- *   adapter: cloudflare({
- *     dev:  { secrets: '.env.dev' },
- *     prod: { route: 'crm.acme.dev', secrets: '.env.prod' },
- *   })
+ *   environments: {
+ *     development: { deployment: cloudflare({ secrets: '.env.dev' }) },
+ *     production: { deployment: cloudflare({ route: 'crm.acme.dev' }) },
+ *   }
  *
- * `dev` runs `wrangler dev` locally; an env with no `route` ships to
+ * `astrale-domain dev <environment>` remotely deploys each admitted update;
+ * an Environment with no `route` ships to
  * `*.workers.dev`; an env with a `route` ships to that custom domain.
  *
  * Prefer a managed deploy (no Cloudflare account)? Use
  * `@astrale-os/adapter-astrale`, which builds the same bundle via this package's
- * `/build` toolkit and ships it through the Astrale platform.
+ * `/build` toolkit and ships it through the Astrale platform. Generic Project
+ * tooling owns optional Kernel installation after provider readiness.
  */
 export { cloudflare } from './cloudflare.js';
 export type { CloudflareParams } from './params.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,20 +1,21 @@
 /**
- * `@astrale-os/adapter-cloudflare` — deploy an Astrale domain as a standalone
- * Cloudflare Worker on YOUR OWN Cloudflare account.
+ * `@astrale-os/adapter-cloudflare` — deploy an Astrale application through
+ * Cloudflare Workers on YOUR OWN Cloudflare account.
  *
  *   import { cloudflare } from '@astrale-os/adapter-cloudflare'
  *
- *   adapter: cloudflare({
- *     dev:  { secrets: '.env.dev' },
- *     prod: { route: 'crm.acme.dev', secrets: '.env.prod' },
- *   })
+ *   environments: {
+ *     development: { deployment: cloudflare({ secrets: '.env.dev' }) },
+ *     production: { deployment: cloudflare({ route: 'crm.acme.dev' }) },
+ *   }
  *
- * `dev` runs `wrangler dev` locally; an env with no `route` ships to
+ * `astrale-domain dev <environment>` remotely deploys each admitted update;
+ * an Environment with no `route` ships to
  * `*.workers.dev`; an env with a `route` ships to that custom domain.
  *
  * Prefer a managed deploy (no Cloudflare account)? Use
  * `@astrale-os/adapter-astrale`, which builds the same bundle via this package's
- * `/build` toolkit and ships it through the Astrale platform.
+ * `/build` toolkit and ships it through the Astrale platform. Generic Project
+ * tooling owns optional Kernel installation after provider readiness.
  */
 export { cloudflare } from './cloudflare.js';
-//# sourceMappingURL=index.js.map