@fabrika/installation-init 0.8.2 → 0.9.0-cloudflare.1

package/types/src/proxy-manifest.d.ts

@@ -0,0 +1,109 @@
+import { type InstallationEndpointTable } from '@fabrika/auth-core';
+import { type InstallationProxyApp } from '@fabrika/proxy-core/manifest';
+/** The platform services an installation's proxy fronts. Each name is a service hostname in the topology. */
+export type PlatformProxyService = 'iam' | 'control' | 'operations';
+/** The public hostname of each platform service, without a scheme and without a port. */
+export type PlatformHosts = Readonly<Record<PlatformProxyService, string>>;
+/** `https://<host>` — the origin a browser, a token's `iss` and a return-origin registry all use. */
+export declare const platformOrigin: (scheme: "http" | "https", host: string) => string;
+/** What one OAuth scope lets a token do: the owning app's actions, resolved by IAM at the token endpoint. */
+export interface PlatformOAuthScopeGrant {
+    readonly scope: string;
+    readonly actions: readonly string[];
+}
+/**
+ * A path an app serves to OAuth clients, protected only on an installation that enables it.
+ *
+ * The resource URI is the app's public origin plus `path`, so the template holds the path and a deploy
+ * binds the origin. Copied from the owning service module by the generator, like `table`.
+ */
+export interface PlatformOAuthResourceTemplate {
+    readonly path: string;
+    readonly scopes: readonly string[];
+    readonly scopeGrants: readonly PlatformOAuthScopeGrant[];
+}
+/**
+ * One fronted app, in the form that is the same on every installation: protected by its service contract (ADR-0022
+ * "Installation entries"), copied in by the generator and never written by hand.
+ */
+export interface PlatformProxyApp {
+    /** The IAM app id. It is the audience of every token the proxy mints for this app's host. */
+    readonly id: string;
+    /** The topology service that answers for it. */
+    readonly service: PlatformProxyService;
+    /**
+     * The proxy's public listener this app answers on.
+     *
+     * On a `zerops-subdomain` installation a port IS a hostname — Zerops mints one generated host per
+     * HTTP port — so this is the only installation-independent half of `hosts`. A custom-domain
+     * installation ignores it: every domain arrives on one listener and the `Host` header decides.
+     */
+    readonly port: number;
+    /** Where the proxy dials it over the project's private network. */
+    readonly upstream: string;
+    /** The service's rows; with an `oauthResource`, the table served when the composition names an authorization server. */
+    readonly table: InstallationEndpointTable;
+    /** Present only on an app that can serve OAuth clients; off unless the composition names an authorization server. */
+    readonly oauthResource?: PlatformOAuthResourceTemplate;
+    /**
+     * Present exactly with `oauthResource`: the service's table when it serves no OAuth client. The service picks the
+     * same one, by the digest the deploy writes beside it (`platformServiceTableDigest`).
+     */
+    readonly tableWithoutOAuth?: InstallationEndpointTable;
+}
+/** Everything about an installation's manifest that does not depend on WHICH installation it is. */
+export interface PlatformProxyManifestTemplate {
+    readonly apps: readonly PlatformProxyApp[];
+}
+/**
+ * The template's entry for one platform service.
+ *
+ * The app IDS live in the template, so a caller that needs one — the deploy's schema reconcile needs
+ * the console's — reads it from there rather than restating a literal that could drift from the
+ * document the proxy is actually configured with.
+ */
+export declare const platformProxyAppFor: (template: PlatformProxyManifestTemplate, service: PlatformProxyService) => PlatformProxyApp;
+/** Where one app answers in a particular composition. */
+export interface PlatformProxyPlacement {
+    /** Public hostnames, without a port — `parseProxyManifest` refuses a `:port` suffix. */
+    readonly hosts: readonly string[];
+    /** Overrides the private dial address. The local composition runs IAM on a port of its own. */
+    readonly upstream?: string;
+}
+/** One composition of the platform: a deployed installation, or the local Docker stack. */
+export interface PlatformProxyComposition {
+    /** The scheme the BROWSER speaks to these apps — configuration, never a header (see `ProxyApp.scheme`). */
+    readonly scheme: 'http' | 'https';
+    readonly placement: Readonly<Record<PlatformProxyService, PlatformProxyPlacement>>;
+    /**
+     * The public IAM origin that issues OAuth tokens. Present only when the installation enables MCP
+     * authoring; absent leaves every `oauthResource` unregistered and serves each service's table without OAuth.
+     */
+    readonly authorizationServer?: string;
+    /** The port browsers reach every app on, when it is not the scheme's default. The local composition's is 18080. */
+    readonly publicPort?: number;
+}
+/**
+ * The RFC 8707 resource URI and RFC 9728 metadata URL of an app's OAuth resource, bound to the app's
+ * FIRST host: the proxy refuses a resource on a host the app does not answer on.
+ */
+export declare const platformOAuthResourceUris: (composition: Pick<PlatformProxyComposition, "scheme" | "publicPort">, hosts: readonly string[], template: PlatformOAuthResourceTemplate) => {
+    readonly resource: string;
+    readonly resourceMetadata: string;
+};
+/**
+ * Bind a template to one composition and get the document the proxy actually parses.
+ *
+ * The result is returned THROUGH `parseProxyManifest`, so a duplicate id, a repeated host or a `:port`
+ * suffix is refused right here instead of at a deployed proxy's next build.
+ */
+export declare const resolvePlatformProxyManifest: (template: PlatformProxyManifestTemplate, composition: PlatformProxyComposition) => PlatformProxyManifest;
+/** The platform proxy's manifest: one installation entry per platform service. */
+export interface PlatformProxyManifest {
+    apps: InstallationProxyApp[];
+}
+/**
+ * `FABRIKA_SERVICE_TABLE_DIGEST` for a service: the digest of the table this manifest publishes for it, which the
+ * service compares with its own and refuses to start under another.
+ */
+export declare const platformServiceTableDigest: (manifest: PlatformProxyManifest, appId: string) => string;

package/types/src/scaffold.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The mechanics of a sidecar repository: ensure `<owner>/<name>` exists on GitHub, materialize the
+ * files the CLI owns, commit and push. Idempotent, and the same on every provider:
+ *   - repo absent  → create a fresh local checkout, commit the scaffold, `gh repo create … --source --push`,
+ *   - repo present → clone it (if not already local), refresh the CLI-owned files, commit + push on drift.
+ *
+ * WHAT the files are is the provider's answer, not this module's — `materialize` writes them and `files`
+ * lists everything the scaffold ever stages. Scaffold commits carry `[skip ci]`, so a push here cannot
+ * deploy anything before `init` has written the GitHub Environment the pipeline reads.
+ *
+ * A freshly created repository is protected before anything else is written to it. An EXISTING one is
+ * only PROBED, never PUT to: its protection is whatever its operator chose, and a blind PUT would replace
+ * stricter rules with ours. Either way the outcome is reported, so an unprotected sidecar is never silent.
+ */
+import { type ProtectionOutcome } from './protection';
+import { type ShellStep } from './shell';
+export declare const INITIAL_SCAFFOLD_COMMIT_MESSAGE = "chore: initial fabrika platform scaffold [skip ci]";
+export declare const REFRESH_SCAFFOLD_COMMIT_MESSAGE = "chore: refresh fabrika platform scaffold [skip ci]";
+export interface SidecarScaffoldInput {
+    /** The sidecar repository, e.g. `contember/fabrika-zerops-test`. */
+    readonly repo: string;
+    /** Local directory to check the repository out into. */
+    readonly dir: string;
+    /** Every path the scaffold stages — CLI-owned files plus any operator-owned, write-once pin. */
+    readonly files: readonly string[];
+    /** Write the scaffold into an existing directory. Called for a fresh creation and for a refresh alike. */
+    materialize(dir: string): Promise<void>;
+}
+/** Result of scaffolding: the local checkout dir + whether the repository was freshly created. */
+export interface SidecarScaffoldResult {
+    readonly dir: string;
+    readonly created: boolean;
+    /** Applied for a repository this run created, probed read-only for one that already existed. */
+    readonly branchProtection?: ProtectionOutcome;
+}
+/** The child processes and GitHub calls the scaffold drives. Replaced wholesale in tests. */
+export interface SidecarScaffoldEffects {
+    hasGhCli(): Promise<boolean>;
+    repositoryExists(repo: string): Promise<boolean>;
+    run(step: ShellStep): Promise<void>;
+    probe(step: ShellStep): Promise<number>;
+    protect(repo: string): Promise<ProtectionOutcome>;
+    probeProtection(repo: string): Promise<ProtectionOutcome>;
+}
+/**
+ * Ensure the sidecar repository exists and carries the current scaffold. Returns the local checkout.
+ * Requires `gh` authenticated with rights to create/administer the repository.
+ */
+export declare function scaffoldSidecarRepository(input: SidecarScaffoldInput, effects?: SidecarScaffoldEffects): Promise<SidecarScaffoldResult>;

package/types/src/secrets-file.d.ts

@@ -0,0 +1,18 @@
+/** `--secrets-file`: where the local copy goes. A new file, outside the source checkout. */
+export declare const SECRETS_FILE_FLAG = "--secrets-file";
+export declare const SECRETS_FILE_VARIABLE = "FABRIKA_PLATFORM_SECRETS_FILE";
+/**
+ * Settle the path before anything is contacted.
+ *
+ * Refused when it exists, because overwriting one would destroy another installation's only copy, and
+ * when it is inside the source checkout, where it would dirty the checkout a deploy uploads and could be
+ * committed.
+ */
+export declare const checkedSecretsFilePath: (path: string, sourceDir: string) => string;
+/**
+ * The file's text: comment lines, then shell-sourceable assignments, named as the commands that read
+ * them name them. `header` is the provider's own lines, each written as a `#` comment.
+ */
+export declare const renderSecretsFile: (header: readonly string[], assignments: readonly (readonly [string, string])[]) => string;
+/** Create the file with mode 0600, failing rather than replacing one that appeared since the check. */
+export declare const writeSecretsFile: (path: string, text: string) => Promise<void>;

package/types/src/secrets.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A 256-bit secret in base64url, never starting with `-` or `_`.
+ *
+ * The re-roll is copied from `@fabrika/local-stack`'s `prepare.ts` and it is not superstition: a
+ * credential beginning with `-` reads as a FLAG to anything that later takes it on a command line, no
+ * matter how it is quoted. One rolled password beginning with `-` made `mc alias set` print its usage
+ * and loop forever. It costs nothing and removes a bug that appears about one install in sixteen.
+ */
+export declare const randomSecret: () => string;
+/** The `px_` prefix IAM's own credentials carry, so a key looks like what it is wherever it turns up. */
+export declare const randomPxKey: () => string;
+/** The control plane's vault KEK. base64, NOT base64url: the vault imports these bytes as an AES key. */
+export declare const generateVaultKey: () => string;
+/** IAM's token-signing material: a JSON array with one ES256 private JWK, index 0 the active signer. */
+export declare const generateSigningKeys: () => string;
+/** Everything a container installation is seeded with. Several of these are shared by more than one service. */
+export interface InstallationSecrets {
+    /** IAM's token-signing material: a JSON array of ES256 private JWKs, index 0 active. */
+    readonly signingKeys: string;
+    /** Authenticates IAM's management `/rpc/*` surface. Held by IAM, control and Operations. */
+    readonly rpcKey: string;
+    /** Authenticates IAM's `/auth/mint/*` surface, which the proxy calls on the cold path. */
+    readonly proxyKey: string;
+    /** The `px_` admin bearer IAM admits as a synthetic global admin. `platform init` and `admin` take it. */
+    readonly provisioningKey: string;
+    /** The catalog credential control and Operations share. No `px_` prefix — it is not an IAM credential. */
+    readonly operationsSyncKey: string;
+    /** The control plane's vault KEK: 32 raw bytes at base64. Its loss is unrecoverable by design. */
+    readonly vaultKey: string;
+}
+/** Roll one installation's secrets. Pure entropy in, no I/O, nothing persisted. */
+export declare const generateInstallationSecrets: () => InstallationSecrets;

package/types/src/service-environment.d.ts

@@ -0,0 +1,78 @@
+import type { InstallationEmail } from './email';
+import type { IamOAuthConfig } from './mcp';
+import { type PlatformHosts } from './proxy-manifest';
+import type { InstallationSecrets } from './secrets';
+/** The four services an installation configures. Each is a service of the platform's own topology. */
+export type PlatformService = 'iam' | 'operations' | 'control' | 'proxy';
+/** Each service's variables, in the order they are written. */
+export type PlatformServiceEnvironment = Readonly<Record<PlatformService, ReadonlyMap<string, string>>>;
+/** IAM's OAuth configuration for MCP clients (ADR-0049): written only when the installation enables MCP authoring. */
+export declare const IAM_OAUTH_CONFIG_VARIABLE = "FABRIKA_IAM_OAUTH_CONFIG";
+/** An object store's coordinates, in the provider's own spelling (values or references to them). */
+export interface PlatformStorage {
+    readonly bucket: string;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly endpoint: string;
+}
+/** Where each service's data lives. */
+export interface PlatformData {
+    readonly iamDatabase: string;
+    readonly controlDatabase: string;
+    readonly operationsDatabase: string;
+    /** Control's run logs. */
+    readonly runLogs: PlatformStorage;
+    /** Operations' artifacts and source maps. */
+    readonly operationsBlobs: PlatformStorage;
+}
+/** Where the installation answers. Both the bring-up and every deploy derive their variables from these. */
+export interface PlatformPlacementInput {
+    readonly environment: string;
+    readonly scheme: 'http' | 'https';
+    readonly hosts: PlatformHosts;
+    /** The private address the platform proxy dials IAM at, which owns the session (`host:port`). */
+    readonly iamUpstream: string;
+}
+/** What `installationServiceEnvironment` needs. Everything in it is settled before the first write. */
+export interface InstallationServiceInput extends PlatformPlacementInput {
+    readonly secrets: InstallationSecrets;
+    readonly data: PlatformData;
+    /** IAM sends its own mail with it, and Control hands it to applications whose job declares `mailer: 'installation'`. */
+    readonly email: InstallationEmail;
+}
+/**
+ * EVERY fabrika variable a bring-up places, per service.
+ *
+ * The proxy manifest is deliberately absent: the deploy owns it, in the same run as the code it
+ * describes (ADR-0027).
+ */
+export declare const installationServiceEnvironment: (input: InstallationServiceInput) => PlatformServiceEnvironment;
+/**
+ * The fabrika variables whose VALUE a bring-up generates, per service.
+ *
+ * Their presence on a live service is what "this project already holds an installation" means, and they
+ * are written as credentials. A provider adds the names of its own that carry a generated value.
+ */
+export declare const INSTALLATION_SECRET_VARIABLES: Readonly<Record<PlatformService, readonly string[]>>;
+/**
+ * The secret the platform proxy sends IAM's route, so IAM honours the client address and request id only from the proxy
+ * (ADR-0022 rule 5). Derived from the provisioning key, which every deploy holds, so each deploy writes the same value
+ * and nothing stores or reads one back. Never from the proxy key: namespace proxies hold that one.
+ */
+export declare const deriveIamProxySecret: (provisioningKey: string) => string;
+/** What a deploy derives the service environment from. */
+export interface DeployedServiceInput extends PlatformPlacementInput {
+    /** `FABRIKA_IAM_PROVISIONING_KEY`, which the IAM proxy secret is derived from. */
+    readonly provisioningKey: string;
+    /** The digest of the console table the deploy's manifest publishes (`platformServiceTableDigest`). */
+    readonly controlTableDigest: string;
+    /** Present only when the installation enables MCP authoring. */
+    readonly oauthConfig?: IamOAuthConfig;
+}
+/**
+ * The per-installation configuration a deploy writes, derived from where the installation answers.
+ *
+ * IAM's OAuth configuration is present only when MCP authoring is enabled; without it the variable is left
+ * as it is, and the manifest — whose `/mcp` row then admits no OAuth token — is what turns MCP off.
+ */
+export declare const deployedServiceEnvironment: (input: DeployedServiceInput) => PlatformServiceEnvironment;

package/types/src/shell.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shell-out helpers for the CLI, over `Bun.spawn`. Every orchestrated step (git, gh, the deploy
+ * trigger) goes through here so the rules are enforced in ONE place:
+ *   - argv is passed verbatim (no shell) — nothing interpolated can be a metacharacter,
+ *   - the child gets ONLY `process.env` + the explicit `env` the step needs,
+ *   - on a non-zero exit we throw a SHORT message naming the command — never the child env, never a
+ *     secret value, never the raw error object (which could carry a token-bearing URL).
+ */
+/** A child step to run: the command + args, its cwd, and the extra env it needs (merged over process.env). */
+export interface ShellStep {
+    command: string;
+    args: string[];
+    cwd: string;
+    /** Extra env vars for this child only. Secret VALUES live here and nowhere else. */
+    env?: Record<string, string>;
+    /** Optional stdin written to the child (used for `gh secret set`, which reads the value from stdin). */
+    stdin?: string;
+}
+/**
+ * What a streaming child gets on stdin.
+ *
+ * A TTY child may INHERIT it — `git` and `gh` prompt on their own, and a terminal is shared by turns.
+ * Without a terminal nobody can answer a child's question, so it gets none and fails instead of waiting.
+ */
+export declare const childStdin: (step: ShellStep, isTty?: boolean) => Uint8Array | "inherit" | "ignore";
+/**
+ * Run a step, STREAMING its stdout/stderr to this terminal so the operator watches the underlying
+ * tool live (git/gh print progress). Throws on a non-zero exit. The thrown message names the command
+ * + exit code only.
+ */
+export declare function run(step: ShellStep): Promise<void>;
+/**
+ * Run a step and CAPTURE its stdout (returned), while streaming stderr to this terminal. Used when we
+ * need to parse a tool's output (e.g. `gh repo view`). Throws on a non-zero exit; the captured stdout
+ * is NOT echoed by this helper.
+ */
+export declare function capture(step: ShellStep): Promise<string>;
+/** Run a step quietly: no stdout/stderr to the terminal, returns the exit code. For existence probes. */
+export declare function probe(step: ShellStep): Promise<number>;
+/** What a step that is allowed to fail reported: its exit code plus everything it wrote. */
+export interface ShellAttempt {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Run a step WITHOUT throwing, capturing both pipes. For a call whose failure is an ANSWER rather than
+ * an error — a `gh api` PUT that GitHub refuses because the plan does not offer the feature.
+ */
+export declare function attempt(step: ShellStep): Promise<ShellAttempt>;