@stacksjs/ts-cloud 0.8.2 → 0.9.0

package/dist/cdn/cloudflare-plan.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Turn a `CloudConfig` into a concrete Cloudflare CDN reconcile plan.
+ *
+ * Kept separate from {@link import('./cloudflare').reconcileCloudflareCdn} so
+ * the "what did the operator ask for" question is answerable — and testable —
+ * without a zone, a token, or a network. The reconciler takes explicit values;
+ * this is the only place that reads config and environment.
+ */
+import type { CloudConfig } from '@ts-cloud/core';
+import type { CloudflareCacheRuleSettings } from './cloudflare-rules';
+import type { CloudflareZoneSettings } from './cloudflare-settings';
+import type { CloudflareOriginGuard } from './cloudflare';
+export interface CloudflareCdnPlan {
+    /** Zone apex the records live in. */
+    zone: string;
+    /** Hostnames to front. */
+    hosts: string[];
+    /** API token. */
+    apiToken: string;
+    zoneId?: string;
+    accountId?: string;
+    proxied: boolean;
+    settings: CloudflareZoneSettings;
+    cache?: CloudflareCacheRuleSettings;
+    originGuard?: CloudflareOriginGuard;
+    purge: boolean;
+    skipOriginProbe: boolean;
+}
+export interface ResolveCloudflareCdnPlanResult {
+    /** The plan, or `null` when this config does not ask for a Cloudflare CDN. */
+    plan: CloudflareCdnPlan | null;
+    /**
+     * Reasons a requested CDN could not be planned. Non-empty with a `null` plan
+     * means "you asked for this and it is misconfigured", which is worth surfacing
+     * — as distinct from "you never asked", which yields no plan and no errors.
+     */
+    errors: string[];
+}
+/** Environment lookup, injectable so tests never touch `process.env`. */
+export type EnvLookup = (key: string) => string | undefined;
+/**
+ * Derive the zone apex for a hostname.
+ *
+ * A configured `infrastructure.dns.domain` wins whenever the host sits inside
+ * it, because that is the only input that knows about multi-label suffixes; the
+ * last-two-labels fallback is a guess that is right for `example.com` and wrong
+ * for `example.co.uk`. The provider corrects the guess anyway once it resolves
+ * the zone by id, so this only has to be good enough to route the lookup.
+ */
+export declare function resolveZoneApex(host: string, configuredDomain?: string): string;
+/**
+ * Resolve the Cloudflare CDN plan for a config, or `null` when none applies.
+ *
+ * A plan is produced only when `infrastructure.compute.proxy.cdn.provider` is
+ * `'cloudflare'`. Everything else — hosts, zone, credentials — is filled in from
+ * the config with environment fallbacks, so the common case is a two-line CDN
+ * block plus a token in the environment.
+ */
+export declare function resolveCloudflareCdnPlan(config: CloudConfig, options?: {
+    env?: EnvLookup;
+}): ResolveCloudflareCdnPlanResult;

package/dist/cdn/cloudflare-rules.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Cloudflare Ruleset rules ts-cloud generates: cache rules for a static site and
+ * the request-header transform that carries the origin-lockdown secret.
+ *
+ * Everything here is pure — rules in, rules out — so the expression syntax can
+ * be tested without a zone. Writing them is {@link
+ * import('../dns/cloudflare').CloudflareProvider.putManagedPhaseRules}'s job.
+ */
+import type { CloudflareRule } from '../dns/cloudflare';
+/**
+ * File extensions treated as immutable build output.
+ *
+ * These are the extensions a bundler fingerprints (`app.4f2a9c.js`), so a given
+ * URL's bytes never change and the edge can hold them effectively forever. HTML
+ * is deliberately absent: it carries the references to the fingerprinted files,
+ * so caching it as long would pin visitors to a stale deploy.
+ */
+export declare const DEFAULT_STATIC_ASSET_EXTENSIONS: readonly string[];
+export interface CloudflareCacheRuleSettings {
+    /** Generate cache rules at all. @default true */
+    enabled?: boolean;
+    /** Extensions treated as immutable, fingerprinted assets. */
+    assetExtensions?: readonly string[];
+    /** Edge TTL for those assets, in seconds. @default 2592000 (30 days) */
+    assetEdgeTtl?: number;
+    /** Browser TTL for those assets, in seconds. @default 31536000 (1 year) */
+    assetBrowserTtl?: number;
+    /** Edge TTL for HTML documents, in seconds. @default 3600 (1 hour) */
+    documentEdgeTtl?: number;
+    /**
+     * Browser TTL for HTML documents, in seconds. @default 0
+     *
+     * Zero means the browser revalidates every navigation while the edge still
+     * absorbs the traffic — a deploy then reaches visitors as soon as the edge
+     * cache is purged, without a stale copy pinned in their local cache.
+     */
+    documentBrowserTtl?: number;
+    /**
+     * Path prefixes that must never be cached (`/api`, `/admin`, …). Matched with
+     * `starts_with`, so `/api` also covers `/api/anything`.
+     */
+    bypassPaths?: readonly string[];
+}
+/** `http.host in {…}` for the hosts a rule applies to. */
+export declare function hostCondition(hosts: readonly string[]): string;
+/**
+ * Cache rules for a static site fronted by Cloudflare.
+ *
+ * The three rules are **mutually exclusive by construction** — each carries the
+ * negation of the ones before it — rather than relying on evaluation order.
+ * That is deliberate. Cloudflare applies every matching rule in this phase and
+ * lets a later one override an earlier one's settings, so a plain catch-all for
+ * documents (`http.host eq …`) silently matches `.js` and `.css` too and undoes
+ * the asset rule: fingerprinted files come back with the HTML's short browser
+ * TTL, which is the opposite of the intent and invisible unless you inspect the
+ * response headers.
+ *
+ * Every rule is also scoped to `hosts`. The zone may serve names that have
+ * nothing to do with this site, and a catch-all matching them would quietly
+ * start caching someone else's dynamic responses.
+ */
+export declare function buildStaticSiteCacheRules(hosts: readonly string[], settings?: CloudflareCacheRuleSettings): CloudflareRule[];
+/**
+ * A request-header transform that stamps the origin-lockdown secret onto every
+ * request Cloudflare forwards to the box.
+ *
+ * This is the Cloudflare half of ts-cloud's origin guard: rpx rejects any
+ * request to these hosts that arrives without the header
+ * (`RpxGatewayConfig.originGuard`), so a client that discovers the origin IP
+ * and connects to it directly cannot bypass the edge. Without the pair, the
+ * origin stays openly reachable and the CDN is advisory.
+ *
+ * It goes in the LATE transform phase so the header survives any earlier
+ * rewrite and is not visible to rules the zone owner writes in the normal
+ * transform phase.
+ */
+export declare function buildOriginGuardRule(hosts: readonly string[], header: string, value: string): CloudflareRule[];

package/dist/cdn/cloudflare-settings.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Cloudflare zone settings: the friendly config shape ts-cloud exposes, and its
+ * translation into the `{ setting_id: value }` pairs the API takes.
+ *
+ * Cloudflare's own ids are terse and inconsistently shaped (`ssl` is an enum
+ * string, `brotli` is `'on'|'off'`, HSTS is a nested object under
+ * `security_header`), so the config speaks in booleans and plain names and this
+ * module owns every mapping. Keeping the translation in one small, pure function
+ * is also what makes it testable without touching the network.
+ */
+/** HSTS (`Strict-Transport-Security`) configuration. */
+export interface CloudflareHstsSettings {
+    enabled: boolean;
+    /** Lifetime in seconds. Cloudflare requires one when enabled. @default 31536000 (1 year) */
+    maxAge?: number;
+    /** Apply to every subdomain. @default false */
+    includeSubdomains?: boolean;
+    /**
+     * Add the zone to the browser preload lists.
+     *
+     * Left off by default on purpose: preloading is effectively irreversible on a
+     * human timescale, so it should be a deliberate choice rather than something a
+     * deploy turns on.
+     * @default false
+     */
+    preload?: boolean;
+    /** Send `X-Content-Type-Options: nosniff`. @default true */
+    noSniff?: boolean;
+}
+/**
+ * Zone-level settings ts-cloud can reconcile.
+ *
+ * Every field is optional and anything left undefined is NOT touched — the zone
+ * may hold settings that have nothing to do with this deploy, and a reconcile
+ * has no business resetting them to a default it invented.
+ */
+export interface CloudflareZoneSettings {
+    /**
+     * How Cloudflare talks to the origin.
+     *
+     * - `strict` — Full (strict): HTTPS to the origin, certificate verified. The
+     *   only mode that actually protects the Cloudflare→origin hop, and the right
+     *   answer whenever the origin holds a real certificate.
+     * - `full` — HTTPS to the origin, certificate NOT verified. Accepts a
+     *   self-signed cert; use only while an origin is still getting its first one.
+     * - `flexible` — plaintext to the origin. Cloudflare serves HTTPS to visitors
+     *   while the origin hop travels unencrypted, and on an origin that redirects
+     *   HTTP to HTTPS it also produces a redirect loop.
+     * - `off` — no HTTPS at all.
+     */
+    ssl?: 'off' | 'flexible' | 'full' | 'strict';
+    /** Redirect every HTTP request to HTTPS at the edge. */
+    alwaysUseHttps?: boolean;
+    /** Rewrite http:// references in HTML to https://. */
+    automaticHttpsRewrites?: boolean;
+    /** Minimum TLS version accepted from visitors. */
+    minTlsVersion?: '1.0' | '1.1' | '1.2' | '1.3';
+    /** Offer TLS 1.3 to visitors. */
+    tls13?: boolean;
+    /** Brotli-compress responses to visitors that accept it. */
+    brotli?: boolean;
+    /** Offer HTTP/3 (QUIC). */
+    http3?: boolean;
+    /** TLS 1.3 0-RTT resumption. */
+    zeroRtt?: boolean;
+    /** Send 103 Early Hints for `Link` headers. */
+    earlyHints?: boolean;
+    /** HSTS. */
+    hsts?: CloudflareHstsSettings;
+    /** Default browser cache TTL in seconds. `0` means "respect the origin". */
+    browserCacheTtl?: number;
+    /** Serve a cached copy when the origin is unreachable. */
+    alwaysOnline?: boolean;
+    /** Proxy WebSocket upgrades. */
+    websockets?: boolean;
+    /**
+     * Raw escape hatch: setting ids passed straight through, merged last.
+     *
+     * The mapped fields above cover what a static site needs; this exists so a
+     * zone-specific toggle doesn't require a ts-cloud release to reach.
+     */
+    raw?: Record<string, unknown>;
+}
+/**
+ * Translate {@link CloudflareZoneSettings} into Cloudflare setting ids.
+ *
+ * Undefined inputs produce no entry at all, which is what keeps a reconcile
+ * additive: the caller only ever writes settings the config actually names.
+ */
+export declare function toCloudflareZoneSettings(settings: CloudflareZoneSettings): Record<string, unknown>;
+/**
+ * Sensible zone settings for a static site served from a ts-cloud box behind
+ * Cloudflare's proxy.
+ *
+ * `ssl: 'strict'` is deliberate: the box terminates TLS with a real Let's
+ * Encrypt certificate (rpx + tlsx), so there is no reason to accept an
+ * unverified origin — and `flexible` would additionally loop, because the
+ * gateway redirects plain HTTP to HTTPS.
+ */
+export declare const STATIC_SITE_ZONE_SETTINGS: CloudflareZoneSettings;

package/dist/cdn/cloudflare.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Put Cloudflare's proxy CDN in front of a ts-cloud origin.
+ *
+ * Cloudflare's CDN is not a separate resource you point at an origin the way
+ * CloudFront is — it *is* the DNS record. A proxied ("orange cloud") A/AAAA
+ * record makes the public answer a Cloudflare anycast address, and Cloudflare
+ * forwards to the address stored in the record. Two consequences shape this
+ * module:
+ *
+ *  - there is no origin hostname to invent. CloudFront needs a dedicated
+ *    `origin.example.com` because a distribution whose origin is one of its own
+ *    aliases resolves back into itself; Cloudflare reads the origin address out
+ *    of the record it is proxying, so the apex fronts itself without looping.
+ *  - the CDN and the DNS record cannot drift apart, because they are one object.
+ *    That is why proxy state has to be preserved across upserts rather than
+ *    re-derived (see `CloudflareProvider.upsertRecord`).
+ *
+ * The reconcile is ordered so it is safe to run on a zone that has never been
+ * touched AND on one already serving traffic: addresses first (so the origin is
+ * reachable), then zone settings, then rules, then a purge — never the reverse,
+ * which would briefly enforce `Full (strict)` against an origin the deploy has
+ * not yet pointed anywhere.
+ */
+import type { CloudflareProvider } from '../dns/cloudflare';
+import type { CloudflareCacheRuleSettings } from './cloudflare-rules';
+import type { CloudflareZoneSettings } from './cloudflare-settings';
+export interface CloudflareOriginGuard {
+    /** Header Cloudflare stamps on the origin hop. */
+    header: string;
+    /** Shared secret value; rpx rejects fronted hosts that arrive without it. */
+    value: string;
+}
+export interface ReconcileCloudflareCdnOptions {
+    provider: CloudflareProvider;
+    /** Zone apex (`example.com`). */
+    zone: string;
+    /** Public hostnames served through the proxy. */
+    hosts: string[];
+    /** Origin IPv4 the proxied records point at. */
+    ipv4: string;
+    /** Origin IPv6, when the box has one. */
+    ipv6?: string;
+    /**
+     * Serve these hosts through Cloudflare's proxy. @default true
+     *
+     * Set `false` for a DNS-only zone — records still reconcile, the CDN-specific
+     * work (settings, cache rules, purge) is skipped.
+     */
+    proxied?: boolean;
+    /** Zone settings to apply. Defaults to {@link STATIC_SITE_ZONE_SETTINGS}. */
+    settings?: CloudflareZoneSettings;
+    /** Cache-rule tuning. */
+    cache?: CloudflareCacheRuleSettings;
+    /** Origin lockdown. Omit to leave the origin reachable directly. */
+    originGuard?: CloudflareOriginGuard;
+    /** Purge the edge cache once everything else is in place. @default true */
+    purge?: boolean;
+    /** Record TTL for unproxied records, in seconds. @default 300 */
+    ttl?: number;
+    /**
+     * Skip the origin TLS probe and proxy immediately.
+     *
+     * The probe only exists to avoid stranding a box that has no certificate yet;
+     * a caller that knows the origin is ready can skip the round trip.
+     * @default false
+     */
+    skipOriginProbe?: boolean;
+}
+export interface CloudflareCdnReport {
+    /** Records confirmed written, with the proxy state each ended up in. */
+    records: Array<{
+        host: string;
+        type: 'A' | 'AAAA';
+        content: string;
+        proxied: boolean;
+    }>;
+    /** Zone settings actually changed. */
+    settingsChanged: Array<{
+        id: string;
+        from: unknown;
+        to: unknown;
+    }>;
+    /** Cache rules written. */
+    cacheRules: number;
+    /** Whether the origin-guard transform rule was written. */
+    originGuard: boolean;
+    /** Whether the edge cache was purged. */
+    purged: boolean;
+    /**
+     * Hosts published DNS-only because the origin could not yet serve a trusted
+     * certificate for them. Re-run the deploy once the certificate is issued.
+     */
+    deferredProxy: Array<{
+        host: string;
+        reason: string;
+    }>;
+    warnings: string[];
+}
+/**
+ * Reconcile a Cloudflare zone so `hosts` are served from the edge and forwarded
+ * to a ts-cloud origin.
+ *
+ * Warnings are collected rather than thrown throughout. This runs at the tail of
+ * a deploy that has already shipped code to a box: a plan-gated zone setting or
+ * a rules permission the token lacks is worth reporting loudly, but it is not
+ * worth reporting as "the deploy failed" when the site is up and serving.
+ */
+export declare function reconcileCloudflareCdn(options: ReconcileCloudflareCdnOptions): Promise<CloudflareCdnReport>;

package/dist/cdn/cloudflare.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cdn/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CDN integrations that sit in front of a ts-cloud origin.
+ *
+ * AWS/CloudFront fronting lives with the AWS stack (see
+ * `drivers/shared/cloudfront-origin`); this module holds the Cloudflare path,
+ * where the CDN and the DNS record are the same object.
+ */
+export type { CloudflareCdnReport, CloudflareOriginGuard, ReconcileCloudflareCdnOptions, } from './cloudflare';
+export { reconcileCloudflareCdn } from './cloudflare';
+export type { CloudflareCdnPlan, EnvLookup, ResolveCloudflareCdnPlanResult, } from './cloudflare-plan';
+export { resolveCloudflareCdnPlan, resolveZoneApex } from './cloudflare-plan';
+export type { CloudflareCacheRuleSettings } from './cloudflare-rules';
+export { buildOriginGuardRule, buildStaticSiteCacheRules, DEFAULT_STATIC_ASSET_EXTENSIONS, hostCondition, } from './cloudflare-rules';
+export type { CloudflareHstsSettings, CloudflareZoneSettings } from './cloudflare-settings';
+export { STATIC_SITE_ZONE_SETTINGS, toCloudflareZoneSettings } from './cloudflare-settings';
+export type { OriginTlsProbeResult, ProbeOriginTlsOptions } from './origin-tls';
+export { probeOriginTls } from './origin-tls';

package/dist/cdn/origin-tls.d.ts

@@ -0,0 +1,36 @@
+export interface OriginTlsProbeResult {
+    /** A TLS handshake completed at all. */
+    reachable: boolean;
+    /**
+     * The certificate is valid for this hostname and chains to a public root —
+     * i.e. `Full (strict)` will work.
+     */
+    trusted: boolean;
+    /** Why the probe is not `trusted`, when it isn't. */
+    reason?: string;
+}
+export interface ProbeOriginTlsOptions {
+    /** Origin address to connect to (IPv4 or IPv6). */
+    address: string;
+    /** Hostname to present as SNI and verify the certificate against. */
+    serverName: string;
+    /** @default 443 */
+    port?: number;
+    /** @default 5000 */
+    timeoutMs?: number;
+}
+/**
+ * Connect to `address:port` with `serverName` as SNI and report what the origin
+ * presents.
+ *
+ * Verification is deliberately not enforced at the socket (`rejectUnauthorized:
+ * false`) so an untrusted certificate produces a *description* rather than a
+ * thrown error — "reachable but the cert doesn't cover this name" and "nothing
+ * is listening" call for different advice, and collapsing them into one failure
+ * loses that. Node still performs the checks and reports them through
+ * `authorized` / `authorizationError`.
+ *
+ * Never throws: a probe is a hint used to pick a safe ordering, and a probe
+ * that fails for its own reasons must not fail a deploy.
+ */
+export declare function probeOriginTls(options: ProbeOriginTlsOptions): Promise<OriginTlsProbeResult>;

package/dist/{chunk-v0vpamnf.js → chunk-5nr95wpj.js}

@@ -7,7 +7,7 @@ import {
   Route53Provider,
   UnifiedDnsValidator,
   createDnsProvider
-} from "./chunk-gttvakpv.js";
+} from "./chunk-atbgd8wz.js";
 import {
   Route53Client
 } from "./chunk-32e7ya18.js";
@@ -815,7 +815,7 @@ async function deployStaticSiteWithExternalDnsFull(config) {
     }
   }
   onProgress?.("upload", "Uploading files to S3...");
-  const { uploadStaticFiles } = await import("./chunk-kpeb5rcs.js");
+  const { uploadStaticFiles } = await import("./chunk-ws47smxr.js");
   const uploadResult = await uploadStaticFiles({
     sourceDir,
     bucket: infraResult.bucket,
@@ -835,7 +835,7 @@ async function deployStaticSiteWithExternalDnsFull(config) {
   }
   if (infraResult.distributionId && uploadResult.uploaded > 0) {
     onProgress?.("invalidate", "Invalidating CloudFront cache...");
-    const { invalidateCache } = await import("./chunk-kpeb5rcs.js");
+    const { invalidateCache } = await import("./chunk-ws47smxr.js");
     await invalidateCache(infraResult.distributionId);
   }
   onProgress?.("complete", "Deployment complete!");