@void/platform 0.20.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present, Cloudflare, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @void/platform
+
+Public, target-neutral contracts and packaged runtime artifacts for installing a Void company platform in a Cloudflare account.
+
+For a first installation, follow [Install a Void Platform](../../docs/guide/self-hosted-platform.md). It explains how to prepare the Cloudflare account, domain, PostgreSQL database, and credentials before deploying. Void creates the platform resources and database tables.
+
+The CLI provides direct credential setup links in plans and opens missing-credential pages during an approved interactive install. The runtime-token link preselects all required account permissions, including Workers Tail, Hyperdrive, and AI Gateway when needed, with a readable fallback summary. Local credential drafts preserve the final Worker names and OAuth callback before provisioning, with partial secrets encrypted by the existing recovery store. A completed credential-setup marker separates these drafts from database-claimed installation recovery.
+
+Interactive installation lists unfinished installs, including interrupted provisioning, and offers to continue one or start a new platform install. Entering an existing unfinished name asks to resume it; declining returns to name entry. New installs leave previous setup, credentials, and resources untouched. Completed platforms are excluded. Explicit `--resume` skips the choice; non-interactive recovery requires it. Read-only plans do not save drafts.
+
+New platforms use readable resource names such as `void-team-api` and `void-team-routing`, without random suffixes. Choose an installation name that is unused in the selected account. Conflicting resources are never silently adopted, overwritten, or bypassed by choosing random names. Existing installations keep their recorded resource names, including older suffixed names; application/user resource naming is independent.
+
+The packaged API also serves the `void platform` commands for managing users,
+projects, access, and logs. The installer applies the database migration needed
+for administrator sessions and audit records. See
+[Platform Administration](../../docs/guide/platform-administration.md) to operate
+an installed platform from your terminal.
+
+The package contains:
+
+- versioned deployment and installation manifests
+- deterministic resource naming and application-route generation
+- discovery-document and capability contracts
+- Cloudflare Worker configuration generation for the core API, proxy, tail, and dispatch Workers
+- A shared installation-owned traffic-disable protocol used by lifecycle-safe retained Workers
+- integrity-checked, deployable Worker bundles plus a schema-versioned PostgreSQL migration and rollback-compatibility manifest under the `./installer` export
+
+The `void` CLI consumes this package for `void platform install`, `repair`, `upgrade`, `discover`, and `uninstall`. Platform implementation sources remain under `platform/packages/*`; their deployable core output is bundled here so a user installs one normal public `void` package rather than cloning or deploying the repository.
+
+Interactive lifecycle operations authenticate the human operator through Cloudflare browser sign-in with OS-keychain storage. Wrangler browser OAuth has Zone Read, so plans that create a zone or DNS record require an explicit management API token with the corresponding Zone Edit and DNS Edit permissions. A new account must finish Workers onboarding and choose its workers.dev subdomain before planning. The installed control plane receives a separate scoped runtime token. Its core permissions include Hyperdrive: Write at account scope and Cache Purge: Purge on the application zone; SSL and Certificates: Edit is needed only by a custom runtime that enables custom project domains. The installer preflights account and Hyperdrive access and, for an existing zone, verifies cache-purge access with a unique nonexistent URL. Local recovery checkpoints are AES-256-GCM encrypted with a key held in the OS keychain; normal upgrades preserve existing Cloudflare Worker secrets rather than downloading or rewriting them.
+
+Fresh installations require a unique JWT signing secret with at least 32 bytes of random material and a unique, canonical base64-encoded 32-byte project-encryption key from the operator's durable secret manager. The installer never makes an ephemeral workstation or CI registry the only custodian of these installation identity keys. Existing Workers preserve their deployed values during routine lifecycle operations.
+
+Browser OAuth cannot manage AI Gateway. Installation previews mark an inaccessible gateway as requiring inspection; apply rechecks it with the already-required runtime token (AI Gateway: Edit) before provisioning. All other provider operations keep the operator credential. Later OAuth lifecycle operations can reuse that token from encrypted local recovery storage. On another workstation, use a management API token with AI Gateway access or supply the runtime token explicitly for that check.
+
+Runtime and installation manifests record the last usage protocol proven live across the complete Worker set. A protocol transition gates traffic before the first Worker update and opens it only after target health and immutable versions pass; interrupted transitions remain gated and resumable.
+
+Application-addressing contracts preserve schema v1 for existing domain installations. Schema v2 records an optional workers.dev installation identity, retained when a domain is added. Project ingress names include the stable project ID so a deleted project's hostname cannot be inherited by a later project with the same slug.
+
+`void platform install --workers-dev` is the explicit test path; the interactive default recommends a domain. `void platform domain set <domain>` records pending setup separately and publishes the active routing configuration only after DNS, runtime-token permissions, and HTTPS pass. It preserves the API origin and existing test URLs. The test hostnames bypass the additional edge response cache while retaining shared ISR storage; custom-domain traffic keeps the normal cache path.
+
+Maintainers and platform forks can build the same runtime from source with `vp run --filter @void/platform build` and deploy it using `void platform upgrade --runtime packages/platform/dist/runtime`. The custom path does not bypass release safety: its manifest, Worker bundles, migration journal, and SQL files receive the same integrity and compatibility verification as packaged artifacts. Builds from a Git checkout automatically record `HEAD` in the runtime provenance, with a `-dirty` suffix when the checkout has uncommitted files. Build systems can set `VOID_PLATFORM_SOURCE_REVISION` to override automatic detection with another commit or build identifier; source archives without Git metadata leave it unrecorded.
+
+Runtime artifacts include migration SQL, the journal, and compatibility metadata. Drizzle authoring snapshots stay in the source tree and are excluded from the published runtime.
+
+Platform migrations are forward-only. `platform/packages/api/drizzle/compatibility.json` declares exact source-version/schema-digest edges whose old Workers are safe against the target schema. The runtime build validates that each source digest is a prefix of the same PostgreSQL lineage and hashes the journal and every SQL file. When adding a migration, use an expand-compatible change, add only edges verified against the old runtime, and keep destructive contract cleanup for a later release after rollback to the old Workers is no longer possible.
+
+Post-success rollback uses the installed runtime's integrity-checked compatibility manifest and an explicitly supplied earlier runtime. The installation checkpoint records running-runtime provenance separately from the actual forward-only database schema. Rollback never reverses migrations, and it rejects a target whose declared safety protocols are older than the installation or authoritative database state.
+
+See the [self-hosted platform guide](../../docs/guide/self-hosted-platform.md) for the supported core feature set, Cloudflare footprint, and lifecycle commands.
+
+Use the application zone's apex for the simplest certificate setup. Nested app
+domains require an active edge wildcard certificate; planning checks coverage
+before provisioning and explains the required certificate product and read
+permission when coverage is missing.
+
+For local changes, fork CI, and a complete source-runtime example, see
+[Platform Development](../../docs/guide/platform-development.md).

package/dist/index.d.mts

@@ -0,0 +1,264 @@
+//#region src/application.d.ts
+/** Public application addressing, independent of the platform API's origin. */
+type PlatformApplication = Readonly<{
+  baseDomain: string;
+  dedicatedZone: boolean;
+  /** Empty only for an explicitly selected workers.dev installation. */
+  zoneName: string;
+  zoneId?: string;
+  /** Retained after adding a domain so existing test URLs keep working. */
+  workersDev?: Readonly<{
+    subdomain: string;
+    installationId: string;
+  }>;
+}>;
+type PlatformApplicationProject = Readonly<{
+  id: string;
+  slug: string;
+}>;
+/** Minimal public-origin adapter; request policy remains in the service-bound dispatcher. */
+export declare const PLATFORM_PROJECT_INGRESS_SOURCE: string;
+export declare function readPlatformApplication(env: Readonly<{
+  PLATFORM_APPLICATION?: string;
+  SITE_DOMAIN?: string;
+  BASE_HOSTNAME?: string;
+}>): PlatformApplication;
+export declare function platformWorkersDevAliasKey(hostname: string): string;
+export declare const PLATFORM_APPLICATION_KEY = "__void/platform/application/v1";
+export declare function resolvePlatformApplicationEnvironment<T extends {
+  PLATFORM_APPLICATION?: string;
+  ROUTING: {
+    get(key: string): Promise<string | null>;
+  };
+}>(env: T): Promise<T>;
+export declare function platformProjectIngressName(project: PlatformApplicationProject, workersDev: NonNullable<PlatformApplication["workersDev"]>): string;
+export declare function platformProjectWorkersDevHostname(project: PlatformApplicationProject, workersDev: NonNullable<PlatformApplication["workersDev"]>): string;
+export declare function platformProjectHostname(project: PlatformApplicationProject, application: PlatformApplication): string;
+export declare function platformProjectHostnames(project: PlatformApplicationProject, application: PlatformApplication): ReadonlyArray<string>;
+//#endregion
+//#region src/manifest.d.ts
+export declare const PLATFORM_DEPLOYMENT_SCHEMA_VERSION: 1;
+type PlatformCapabilities = Readonly<{
+  ai: boolean;
+  customDomains: boolean;
+  email: boolean;
+  githubActions: boolean;
+  githubOAuth: boolean;
+  googleOAuth: boolean;
+  managedBuilds: boolean;
+  sandbox: boolean;
+}>;
+type PlatformControlPlane = Readonly<{
+  apiHostname: string | null;
+  dashboardHostname: string | null;
+  proxyHostname: string | null;
+}>;
+type PlatformResourceNames = Readonly<{
+  aiGateway: string;
+  apiWorker: string;
+  assetsBucket: string;
+  cronQueue: string;
+  dashboardWorker: string;
+  dispatchNamespace: string;
+  dispatchWorker: string;
+  hyperdrive: string;
+  isrCacheKv: string;
+  legacyAssetsKv: string;
+  logsDataset: string;
+  proxyWorker: string;
+  requestsDataset: string;
+  routingKv: string;
+  tailWorker: string;
+  usageQueue: string;
+}>;
+type PlatformDeploymentManifest = Readonly<{
+  application: PlatformApplication;
+  authentication: Readonly<{
+    providers: ReadonlyArray<"github" | "google">;
+  }>;
+  capabilities: PlatformCapabilities;
+  controlPlane: PlatformControlPlane;
+  displayName: string;
+  installationSlug: string;
+  resources: PlatformResourceNames;
+  schemaVersion: typeof PLATFORM_DEPLOYMENT_SCHEMA_VERSION | 2;
+}>;
+type PlatformDeploymentManifestInput = Readonly<{
+  application: Readonly<{
+    baseDomain: string;
+    dedicatedZone?: boolean;
+    zoneName: string;
+    workersDev?: PlatformApplication["workersDev"];
+    zoneId?: string;
+  }>;
+  authentication?: Readonly<{
+    providers?: ReadonlyArray<"github" | "google">;
+  }>;
+  capabilities?: Partial<PlatformCapabilities>;
+  controlPlane?: Partial<PlatformControlPlane>;
+  displayName: string;
+  installationSlug: string;
+  resources?: Partial<PlatformResourceNames>;
+}>;
+type PlatformApplicationRoute = Readonly<{
+  pattern: string;
+  zoneName: string;
+}>;
+export declare function normalizeInstallationSlug(value: string): string;
+export declare function normalizeApplicationDomain(value: string): string;
+export declare function createPlatformResourceNames(installationSlug: string): PlatformResourceNames;
+export declare function createApplicationRoutes(application: PlatformDeploymentManifest["application"]): ReadonlyArray<PlatformApplicationRoute>;
+export declare function createPlatformDeploymentManifest(input: PlatformDeploymentManifestInput): PlatformDeploymentManifest;
+export declare function parsePlatformDeploymentManifest(value: unknown): PlatformDeploymentManifest;
+//#endregion
+//#region src/installation.d.ts
+export declare const PLATFORM_INSTALLATION_SCHEMA_VERSION: 1;
+export declare const PLATFORM_DISABLED_KEY = "__void/platform/disabled/v1";
+export declare const PLATFORM_DISABLED_VALUE = "disabled";
+export declare const PLATFORM_REMOTE_INSTALLATION_MANIFEST_KEY = "__void/platform/installation/v1";
+export declare const PLATFORM_SANDBOX_DRAIN_KEY = "__void/platform/sandbox-drain/v1";
+export declare const PLATFORM_R2_OWNERSHIP_MARKER_KEY = "__void/platform/ownership/v1";
+export declare const PLATFORM_RESOURCE_OWNERSHIP_SCHEMA_VERSION: 1;
+export declare const PLATFORM_USAGE_PROTOCOL_VERSION: 1;
+type InstallationStatus = "draft" | "planned" | "provisioning" | "waiting-for-dns" | "waiting-for-oauth" | "deploying" | "verifying" | "installed" | "disabling" | "disabled" | "uninstalling" | "uninstalled" | "failed";
+type ResourceOwnership = "created" | "adopted" | "external";
+type InstallationResourceKind = "ai-gateway" | "analytics-dataset" | "dispatch-namespace" | "dns-record" | "hyperdrive" | "kv-namespace" | "queue" | "r2-bucket" | "worker" | "worker-custom-domain" | "worker-route" | "zone";
+type InstallationResource = Readonly<{
+  configHash: string;
+  id: string;
+  key: string;
+  kind: InstallationResourceKind;
+  name: string;
+  ownership: ResourceOwnership;
+  state: "ready" | "retained" | "deleted";
+}>;
+type InstallationStep = Readonly<{
+  completedAt: string;
+  key: string;
+  resultHash: string;
+}>;
+type PlatformInstallationEndpoints = Readonly<{
+  apiUrl: string | null;
+  dashboardUrl: string | null;
+  proxyUrl: string | null;
+}>;
+type PlatformRuntimeProvenance = Readonly<{
+  manifestSha256: string;
+  source: "custom" | "package";
+  sourceRevision: string | null;
+}>;
+type PlatformInstallationManifest = Readonly<{
+  account: Readonly<{
+    id: string;
+    name: string;
+  }>;
+  createdAt: string;
+  /** Actual forward-only PostgreSQL schema, independent of the running runtime. */
+  databaseSchemaDigest: string | null;
+  deployment: PlatformDeploymentManifest;
+  /** Desired domain while DNS/TLS activation is pending; current addressing remains live. */
+  pendingDomain?: PlatformDeploymentManifest["application"];
+  desiredState: "enabled" | "disabled";
+  endpoints: PlatformInstallationEndpoints;
+  id: string;
+  ownershipNonce: string;
+  platformVersion: string;
+  resources: ReadonlyArray<InstallationResource>;
+  runtime: PlatformRuntimeProvenance | null;
+  safetyProtocols: Readonly<{
+    sandboxDrain: 0 | 1 | 2;
+  }>;
+  schemaVersion: typeof PLATFORM_INSTALLATION_SCHEMA_VERSION;
+  status: InstallationStatus;
+  steps: ReadonlyArray<InstallationStep>;
+  updatedAt: string;
+  /** Last usage protocol proven live across the installed Worker set. */
+  usageProtocolVersion: 0 | 1;
+}>;
+type PlatformResourceOwnershipMarker = Readonly<{
+  accountId: string;
+  installationId: string;
+  ownershipNonce: string;
+  resourceId: string;
+  resourceKey: string;
+  resourceKind: InstallationResourceKind;
+  resourceName: string;
+  schemaVersion: typeof PLATFORM_RESOURCE_OWNERSHIP_SCHEMA_VERSION;
+}>;
+export declare function createPlatformResourceOwnershipMarker(input: {
+  accountId: string;
+  installationId: string;
+  ownershipNonce: string;
+  resourceId: string;
+  resourceKey: string;
+  resourceKind: InstallationResourceKind;
+  resourceName: string;
+}): PlatformResourceOwnershipMarker;
+export declare function parsePlatformResourceOwnershipMarker(value: unknown): PlatformResourceOwnershipMarker;
+export declare function createPlatformInstallationManifest(input: {
+  account: {
+    id: string;
+    name: string;
+  };
+  createdAt: string;
+  deployment: PlatformDeploymentManifest;
+  id: string;
+  ownershipNonce: string;
+  platformVersion: string;
+  safetyProtocols?: Readonly<{
+    sandboxDrain: 0 | 1 | 2;
+  }>;
+  usageProtocolVersion?: 0 | 1;
+}): PlatformInstallationManifest;
+export declare function setInstallationDesiredState(manifest: PlatformInstallationManifest, desiredState: PlatformInstallationManifest["desiredState"], updatedAt: string): PlatformInstallationManifest;
+export declare function setInstallationEndpoints(manifest: PlatformInstallationManifest, endpoints: PlatformInstallationEndpoints, updatedAt: string): PlatformInstallationManifest;
+export declare function transitionInstallation(manifest: PlatformInstallationManifest, status: InstallationStatus, updatedAt: string): PlatformInstallationManifest;
+export declare function recordInstallationResource(manifest: PlatformInstallationManifest, resource: InstallationResource, updatedAt: string): PlatformInstallationManifest;
+export declare function recordInstallationStep(manifest: PlatformInstallationManifest, step: InstallationStep, updatedAt: string): PlatformInstallationManifest;
+export declare function parsePlatformInstallationManifest(value: unknown): PlatformInstallationManifest;
+//#endregion
+//#region src/discovery.d.ts
+export declare const PLATFORM_DISCOVERY_SCHEMA_VERSION: 1;
+type PlatformDiscoveryDocument = Readonly<{
+  apiUrl: string;
+  applicationDomain: string;
+  applicationRouting?: PlatformApplication;
+  authenticationProviders: ReadonlyArray<"github" | "google">;
+  capabilities: PlatformCapabilities;
+  displayName: string;
+  installationId: string | null;
+  platformVersion: string;
+  proxyUrl: string;
+  schemaVersion: typeof PLATFORM_DISCOVERY_SCHEMA_VERSION | 2;
+  usageProtocolVersion: 0 | 1;
+}>;
+export declare function createPlatformDiscoveryDocument(input: Omit<PlatformDiscoveryDocument, "schemaVersion" | "usageProtocolVersion"> & {
+  usageProtocolVersion?: 0 | 1;
+}): PlatformDiscoveryDocument;
+export declare function parsePlatformDiscoveryDocument(value: unknown): PlatformDiscoveryDocument;
+//#endregion
+//#region src/worker-config.d.ts
+type PlatformProvisionedResourceIds = Readonly<{
+  hyperdrive: string;
+  isrCacheKv: string;
+  legacyAssetsKv: string;
+  routingKv: string;
+  zone: string;
+}>;
+type PlatformWorkerConfigSet = Readonly<Record<"api" | "dispatch" | "proxy" | "tail", Record<string, unknown>>>;
+export declare function createPlatformWorkerConfigs(input: {
+  accountId: string;
+  apiUrl: string;
+  deployment: PlatformDeploymentManifest;
+  healthProbeToken: string;
+  installationId: string;
+  ownershipNonce: string;
+  platformVersion: string;
+  publicEndpoints?: boolean;
+  proxyUrl: string;
+  resources: PlatformProvisionedResourceIds;
+  runtimeEntrypoints: Readonly<Record<"api" | "dispatch" | "proxy" | "tail", string>>;
+  trafficState?: "enabled" | "sandbox-drain" | "staging";
+}): PlatformWorkerConfigSet;
+//#endregion
+export type { InstallationResource, InstallationResourceKind, InstallationStatus, InstallationStep, PlatformApplication, PlatformApplicationProject, PlatformApplicationRoute, PlatformCapabilities, PlatformControlPlane, PlatformDeploymentManifest, PlatformDeploymentManifestInput, PlatformDiscoveryDocument, PlatformInstallationEndpoints, PlatformInstallationManifest, PlatformProvisionedResourceIds, PlatformResourceNames, PlatformResourceOwnershipMarker, PlatformRuntimeProvenance, PlatformWorkerConfigSet, ResourceOwnership };