@fabrika/provider-zerops 0.9.0-dev.1 → 0.9.0-dev.2

package/types/src/installation/placement-options.d.ts

@@ -0,0 +1,11 @@
+export declare const parsePlatformScheme: (raw: string | undefined) => "http" | "https";
+export declare const parsePlatformHostname: (raw: string) => string;
+export declare const parsePlatformHosts: (raw: {
+    iam: string | undefined;
+    control: string | undefined;
+    operations: string | undefined;
+}) => {
+    iam: string;
+    control: string;
+    operations: string;
+} | undefined;

package/types/src/installation/platform-archive.d.ts

@@ -0,0 +1,7 @@
+import type { ZeropsSourceDataFile } from '../source/port';
+/**
+ * The prepared platform archive plus the one generated data file (ADR-0045): every entry of the commit is copied
+ * byte for byte, and the file is appended after the last one. A commit that already holds the path, as a file or
+ * as a directory, is refused rather than overridden.
+ */
+export declare const archiveWithDataFile: (compressed: Uint8Array<ArrayBuffer>, file: ZeropsSourceDataFile) => Uint8Array<ArrayBuffer>;

package/types/src/installation/platform-source.d.ts

@@ -0,0 +1,8 @@
+import { type ZeropsArtifactSourceDescriptor } from '../index';
+export interface PreparedPlatformSource {
+    commitSha: string;
+    descriptor: ZeropsArtifactSourceDescriptor;
+    archivePath: string;
+    dispose(): Promise<void>;
+}
+export declare function preparePlatformSource(sourceDir: string, signal: AbortSignal): Promise<PreparedPlatformSource>;

package/types/src/installation/platform-upload.d.ts

@@ -0,0 +1,3 @@
+export type PlatformUploadFetch = (url: string, init: RequestInit) => Promise<Response>;
+export declare const validatePlatformUploadUrl: (value: string) => void;
+export declare const uploadPlatformArchive: (url: string, archive: Blob, signal: AbortSignal, uploadFetch: PlatformUploadFetch) => Promise<void>;

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

@@ -0,0 +1,105 @@
+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';
+/** 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/installation/secrets.d.ts

@@ -0,0 +1,17 @@
+/** Everything one 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/installation/sidecar.d.ts

@@ -0,0 +1,51 @@
+/** Everything the scaffold stages: the CLI-owned trio plus the operator-owned, write-once pin. */
+export declare const SIDECAR_FILES: readonly [".gitignore", "README.md", "fabrika.ref", ".github/workflows/platform.yml"];
+/** The file that pins which published fabrika tag this installation runs. */
+export declare const FABRIKA_REF_FILE = "fabrika.ref";
+/** The generated pipeline. CLI-owned: `init` and `upgrade` both rewrite it. */
+export declare const SIDECAR_WORKFLOW_PATH = ".github/workflows/platform.yml";
+/** What a rendered sidecar repository is named after. */
+export interface SidecarValues {
+    /** The operator's name for this installation. The GitHub Environment is named after it too. */
+    readonly installation: string;
+    /** `<owner>/<name>` of the sidecar repository itself. */
+    readonly repo: string;
+    /** The published fabrika tag to pin, used only when `fabrika.ref` does not exist yet. */
+    readonly fabrikaRef: string;
+}
+/** The pinned ref, or an error naming what was found. A branch is refused, deliberately and loudly. */
+export declare const assertPinnedTag: (ref: string) => string;
+/** The generated pipeline for one installation. Its only placeholder is the installation, which names its GitHub Environment. */
+export declare const renderSidecarWorkflow: (installation: string) => Promise<string>;
+/**
+ * The installation a sidecar's current workflow was rendered for, read back from its GitHub Environment.
+ *
+ * Not from the repository name: `init --repo` accepts any name, and a workflow rendered for the wrong
+ * Environment deploys with no credentials.
+ */
+export declare const readSidecarWorkflowInstallation: (dir: string) => Promise<string>;
+/**
+ * Write the sidecar files into `dir`.
+ *
+ * The workflow, the README and the `.gitignore` are CLI-owned and refreshed on every run, so a fix to
+ * the generated pipeline reaches every installation on its operator's next `init` (and the workflow on
+ * the next `upgrade`). `fabrika.ref` is
+ * written ONLY when absent: bumping it is how an operator rolls the installation forward, and a refresh
+ * that reset it would silently roll them back.
+ *
+ * An existing `fabrika.ref` is validated rather than ignored — a sidecar that has drifted onto a branch
+ * is exactly the case the two gates exist for, and finding it here beats finding it in a failed run.
+ */
+export declare const materializeSidecarScaffold: (dir: string, values: SidecarValues) => Promise<void>;
+/** The pin a checkout carries, for the closing summary. */
+export declare const readPinnedTag: (dir: string) => Promise<string>;
+/**
+ * The default sidecar repository for an installation, following the predecessor's `vozka-platform-<account>`
+ * precedent: named so its relation to the installation is obvious. A parameter, never a constant — one
+ * operator's installations are not another's.
+ */
+export declare const defaultSidecarRepo: (installation: string) => string;
+/** Where the sidecar is checked out locally: `./fabrika-zerops-<installation>` under the cwd. */
+/** The sidecar checkout's directory name when `--checkout` is not given; `init` creates it and `upgrade` reads it. */
+export declare const defaultCheckoutName: (installation: string) => string;
+export declare const defaultCheckoutDir: (installation: string) => string;

package/types/src/installation/source-options.d.ts

@@ -0,0 +1 @@
+export declare const readInstallationSourceDir: (argv: readonly string[], env: Record<string, string | undefined>) => string;

package/types/src/installation/topology/artifacts.d.ts

@@ -0,0 +1,8 @@
+/** One file to write, with a path relative to the repository root. */
+export interface Artifact {
+    /** Repo-relative, POSIX-separated. */
+    path: string;
+    content: string;
+}
+/** Every artifact this package generates, in a stable order. */
+export declare const generatedArtifacts: () => Artifact[];

package/types/src/installation/topology/index.d.ts

@@ -0,0 +1,5 @@
+export { type Artifact, generatedArtifacts } from './artifacts';
+export { assertCorePackageIsExplicit, assertOnlyPublicService, assertZeropsHostnames } from './invariants';
+export { fabrikaZeropsYaml, PROXY_HEALTH_PORT, PROXY_PUBLIC_PORTS } from './setups';
+export { appsTopology, type CompiledDocument, type CompiledTopology, compileTopology, fabrikaTopologies, platformTopology, PROXY_HOSTNAME, } from './topology';
+export { assertArtifactMatchesSchema, parseYaml, validateYaml } from './validate';