@stacksjs/ts-cloud 0.7.17 → 0.7.19

package/dist/deploy/dashboard-auth.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Identity and authorization for the management dashboard.
+ *
+ * The dashboard hosts sites for more than one party: Stacks owns the box, and
+ * collaborators are invited to individual sites. That makes authorization a
+ * security boundary rather than a convenience — a site collaborator must never
+ * reach another tenant's data, and must never reach the box itself.
+ *
+ * The model has two levels:
+ * - Box role: `admin` (owns the box — everything) or `member` (only what they
+ *   have been granted).
+ * - Site grants: a member holds a {@link SiteRole} per site. `owner` may change
+ *   the site's settings; `collaborator` may view and deploy it.
+ *
+ * Box-level capabilities (shell, terminal, SSH keys, firewall, databases,
+ * cloud-config edits) are **admin-only and never grantable per site**. Each of
+ * them yields root on the box, which would hand a single site's collaborator
+ * control of every other tenant's site. There is deliberately no grant that
+ * unlocks them for a member.
+ *
+ * Authorization is deny-by-default: {@link authorize} answers `false` for any
+ * capability it does not explicitly recognize.
+ */
+/** Box-wide role. `admin` owns the server and everything hosted on it. */
+export type BoxRole = 'admin' | 'member';
+/**
+ * A member's role on one site. `owner` can additionally change that site's
+ * settings; `collaborator` is limited to viewing and deploying it.
+ */
+export type SiteRole = 'owner' | 'collaborator';
+export interface DashboardUser {
+    username: string;
+    /** Encoded scrypt hash — see {@link hashPassword}. Never a plaintext password. */
+    passwordHash: string;
+    role: BoxRole;
+    /** Site name → role. Ignored for admins, who reach every site. */
+    sites: Record<string, SiteRole>;
+    /** Display name shown in the UI. Defaults to the username. */
+    name?: string;
+    createdAt?: string;
+}
+/**
+ * Everything the dashboard can be asked to do.
+ *
+ * `box:*` capabilities are admin-only. `site:*` capabilities are evaluated
+ * against a specific site and may be granted to a member.
+ */
+export type Capability = 'box:read' | 'box:shell' | 'box:ssh' | 'box:firewall' | 'box:database' | 'box:config' | 'box:sites:create' | 'box:sites:delete' | 'box:serverless' | 'box:users' | 'site:read' | 'site:deploy' | 'site:settings';
+/**
+ * Capabilities that are never grantable to a member, for any site. Listed
+ * explicitly so that adding a `site:*` capability can't silently widen a
+ * member's reach into box-level control.
+ */
+export declare function isBoxCapability(capability: Capability): boolean;
+export interface AuthorizeInput {
+    user: Pick<DashboardUser, 'role' | 'sites'>;
+    capability: Capability;
+    /** Required for every `site:*` capability; ignored for `box:*`. */
+    site?: string;
+}
+/**
+ * The single authorization decision point. Deny-by-default: an unrecognized
+ * capability, a missing site, or a site the member holds no grant on all
+ * return `false`.
+ */
+export declare function authorize({ user, capability, site }: AuthorizeInput): boolean;
+/** The sites a user may see. Admins see everything, so pass the full list. */
+export declare function visibleSites(user: Pick<DashboardUser, 'role' | 'sites'>, allSites: string[]): string[];
+/**
+ * Hash a password for storage: `scrypt$N$r$p$salt$hash` (both salt and hash
+ * base64url). The parameters travel with the hash so they can be raised later
+ * without invalidating existing credentials.
+ */
+export declare function hashPassword(password: string): string;
+/**
+ * Verify a password against an encoded hash, in constant time. Returns false
+ * for malformed hashes rather than throwing — a corrupt user record must fail
+ * the login, not crash the server.
+ */
+export declare function verifyPassword(password: string, stored: string): boolean;
+/** A URL-safe generated password, for invites and the bootstrap admin. */
+export declare function generatePassword(): string;

package/dist/deploy/dashboard-auth.test.d.ts

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

package/dist/deploy/dashboard-guard.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The request-time gate: resolve who is calling, then decide whether the
+ * {@link routePolicy} for their request permits it.
+ *
+ * Every dashboard request passes through here before reaching a handler, so
+ * this file and {@link import('./dashboard-policy')} together are the complete
+ * authorization story for the HTTP API.
+ */
+import type { DashboardUser } from './dashboard-auth';
+/**
+ * A synthetic admin used only when auth is explicitly disabled for local
+ * development. It is never persisted and never has a password.
+ */
+export declare const LOCAL_ADMIN: DashboardUser;
+export interface GuardOptions {
+    cwd: string;
+    /** When false, every request is treated as {@link LOCAL_ADMIN}. */
+    enabled: boolean;
+    secret: string;
+}
+export interface GuardDecision {
+    ok: boolean;
+    status?: number;
+    error?: string;
+    /** True when the caller has no valid session at all (vs. lacking a grant). */
+    unauthenticated?: boolean;
+}
+export interface DashboardGuard {
+    enabled: boolean;
+    /** The user for this request, or null when unauthenticated. */
+    resolveUser: (req: Request) => DashboardUser | null;
+    /** Whether `user` may perform `req`. `site` is required for site-scoped routes. */
+    check: (req: Request, pathname: string, user: DashboardUser | null, site?: string) => GuardDecision;
+}
+export declare function createDashboardGuard(options: GuardOptions): DashboardGuard;
+/**
+ * Read the site name a site-scoped route acts on, without consuming the body
+ * the handler will read (the request is cloned).
+ */
+export declare function siteFromRequest(req: Request, pathname: string): Promise<string | undefined>;

package/dist/deploy/dashboard-login-page.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The login page.
+ *
+ * Served directly by the dashboard server rather than built with the rest of
+ * the stx UI: it has to render before there is a session, and the built pages
+ * are scope-specific (see the per-scope UI cache in `local-dashboard-server`).
+ * Keeping it self-contained also means a broken UI build still leaves a way in.
+ *
+ * It mirrors the cockpit's existing design tokens so the two don't read as
+ * different products.
+ */
+/**
+ * The page. `serverless` only picks the post-login landing route, matching the
+ * redirect the server already does for a serverless deployment.
+ */
+export declare function renderLoginPage(serverless?: boolean): string;

package/dist/deploy/dashboard-pages.test.d.ts

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

package/dist/deploy/dashboard-policy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The dashboard's route → capability table.
+ *
+ * This is the whole authorization surface of the HTTP API in one readable
+ * place, so it can be reviewed without tracing handlers. {@link routePolicy}
+ * maps a method and path to the {@link Capability} it needs.
+ *
+ * **Fails closed.** A route with no entry resolves to `box:shell` — the most
+ * privileged capability, admin-only. Adding a route and forgetting to give it a
+ * policy therefore locks members out rather than quietly exposing the route.
+ *
+ * Site-scoped routes take their site from the request body, so their entry sets
+ * `siteFrom: 'body'` and the caller supplies the parsed name.
+ */
+import type { Capability } from './dashboard-auth';
+export interface RoutePolicy {
+    capability: Capability;
+    /** Where the site name comes from, for `site:*` capabilities. */
+    siteFrom?: 'body';
+    /** Any authenticated user may call it, regardless of role. */
+    anyUser?: boolean;
+}
+/**
+ * Routes reachable with no session at all. These necessarily run before there
+ * is a user to authorize, so they are listed here explicitly — the set is
+ * deliberately tiny and should stay that way.
+ *
+ * `/login` (the page) is served by the same public path.
+ */
+export declare const PUBLIC_ROUTES: ReadonlySet<string>;
+export declare function isPublicRoute(method: string, pathname: string): boolean;
+/**
+ * The policy for a request. Unlisted API routes fail closed to admin-only.
+ */
+export declare function routePolicy(method: string, pathname: string): RoutePolicy;
+/** Every policy entry, for tests and documentation. */
+export declare function allRoutePolicies(): Record<string, RoutePolicy>;

package/dist/deploy/dashboard-policy.test.d.ts

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

package/dist/deploy/dashboard-scope.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Narrow resolved dashboard data to what a user is allowed to see.
+ *
+ * This runs server-side, before serialization: a member is *sent* less, not
+ * merely shown less. Hiding a panel in the UI would leave every other tenant's
+ * deploy history and log lines one devtools tab away.
+ *
+ * Admins get the payload untouched. For a member we keep only their sites and
+ * the observability derived from them, and drop the box-level surface
+ * (host metrics, services, SSH keys, firewall, backups) outright — none of it
+ * is theirs, and some of it (open ports, auth events) is a map of the box.
+ */
+import type { DashboardUser } from './dashboard-auth';
+export interface ScopeOptions {
+    user: Pick<DashboardUser, 'role' | 'sites'>;
+    /** Project slug, used to match a site to its systemd units. */
+    slug: string;
+}
+/**
+ * Return a copy of `data` containing only what `user` may see.
+ */
+export declare function scopeDashboardData(data: Record<string, any>, options: ScopeOptions): Record<string, any>;
+/** Narrow the sanitized cloud config the same way. */
+export declare function scopeCloudConfig(config: Record<string, any>, user: Pick<DashboardUser, 'role' | 'sites'>): Record<string, any>;

package/dist/deploy/dashboard-scope.test.d.ts

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

package/dist/deploy/dashboard-session.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Cookie-backed sessions for the management dashboard.
+ *
+ * Sessions are stateless signed tokens (`payload.signature`, HMAC-SHA256) so
+ * they survive a dashboard restart without a session store. The payload carries
+ * only the username and an expiry; every request re-loads the user from the
+ * store, so a revoked or downgraded grant takes effect immediately rather than
+ * lingering until the token expires.
+ *
+ * The signing secret is resolved from `TS_CLOUD_DASHBOARD_SECRET`, else
+ * generated once and persisted to `.ts-cloud/dashboard-secret`. Rotating it
+ * invalidates every outstanding session.
+ */
+export declare const SESSION_COOKIE = "ts_cloud_session";
+export declare const SECRET_FILE: string;
+/** Eight hours: long enough to work through a deploy, short enough to expire. */
+export declare const SESSION_TTL_MS: number;
+export interface SessionPayload {
+    /** Username the session belongs to. */
+    u: string;
+    /** Expiry, epoch milliseconds. */
+    exp: number;
+}
+/**
+ * Resolve the HMAC signing secret, generating and persisting one on first use.
+ * The file is written 0600 — it is equivalent to every dashboard credential.
+ */
+export declare function resolveSessionSecret(cwd: string): string;
+/** Issue a signed session token for `username`. */
+export declare function createSessionToken(username: string, secret: string, ttlMs?: number): string;
+/**
+ * Verify a token and return its payload, or null when the signature is invalid,
+ * the token is malformed, or it has expired. Signature is compared before the
+ * payload is trusted for anything.
+ */
+export declare function verifySessionToken(token: string | undefined, secret: string): SessionPayload | null;
+/** Read one cookie from a request's `Cookie` header. */
+export declare function readCookie(header: string | null, name: string): string | undefined;
+/**
+ * Serialize the session cookie. `HttpOnly` keeps it away from page scripts,
+ * `SameSite=Lax` blocks cross-site POSTs from carrying it (the dashboard's CSRF
+ * defense), and `Secure` is set whenever the dashboard is not on loopback —
+ * in production it is always behind TLS.
+ */
+export declare function serializeSessionCookie(token: string, options?: {
+    secure: boolean;
+    maxAgeMs?: number;
+}): string;
+/** Cookie that clears the session (logout). */
+export declare function clearSessionCookie(options?: {
+    secure: boolean;
+}): string;

package/dist/deploy/dashboard-users.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The dashboard's user store: a JSON file of {@link DashboardUser} records at
+ * `.ts-cloud/dashboard-users.json` (0600), holding scrypt hashes and site
+ * grants. Small on purpose — a box hosts a handful of collaborators, not a
+ * directory service.
+ *
+ * On first use the store bootstraps a single admin so a freshly provisioned
+ * dashboard is never reachable without credentials. The generated password is
+ * returned to the caller to print once; only its hash is ever written.
+ */
+import type { DashboardUser, SiteRole } from './dashboard-auth';
+export declare const USERS_FILE: string;
+/** Usernames are used in URLs and shell-free contexts; keep them boring. */
+export declare function isValidUsername(value: string): boolean;
+export declare function parseUsersFile(text: string): DashboardUser[];
+export declare function usersFilePath(cwd: string): string;
+export declare function loadUsers(cwd: string): DashboardUser[];
+export declare function saveUsers(cwd: string, users: DashboardUser[]): void;
+export declare function findUser(users: DashboardUser[], username: string): DashboardUser | undefined;
+export interface BootstrapResult {
+    users: DashboardUser[];
+    /** Set only when an admin was just created — print it once, then it's gone. */
+    generated?: {
+        username: string;
+        password: string;
+    };
+}
+/**
+ * Ensure at least one admin exists. When the store is empty, create an admin
+ * using `TS_CLOUD_UI_PASSWORD` if set, else a generated password that is
+ * returned for one-time display.
+ */
+export declare function ensureAdminUser(cwd: string, username?: string): BootstrapResult;
+export interface UpsertMemberInput {
+    username: string;
+    password?: string;
+    name?: string;
+    sites: Record<string, SiteRole>;
+}
+/**
+ * Create or update a member and their site grants. Returns the generated
+ * password when one was minted (a new user without an explicit password).
+ *
+ * Members are created through this path only — it cannot produce an admin, so
+ * an invite flow can never escalate someone to box-wide control.
+ */
+export declare function upsertMember(cwd: string, input: UpsertMemberInput): {
+    user: DashboardUser;
+    password?: string;
+};
+/**
+ * Remove a user. The last admin cannot be removed — that would lock everyone
+ * out of the box with no way back in short of editing the file by hand.
+ */
+export declare function removeUser(cwd: string, username: string): {
+    ok: boolean;
+    error?: string;
+};
+/** Public shape for the UI — never leaks the password hash. */
+export declare function describeUser(user: DashboardUser): Record<string, any>;

package/dist/deploy/index.js

@@ -12,7 +12,7 @@ import {
   sanitizeCloudConfig,
   setMaintenance,
   startLocalDashboardServer
-} from "../chunk-pr3g0b0t.js";
+} from "../chunk-nt2hrnva.js";
 import {
   buildAndPushServerlessImage
 } from "../chunk-qgnyzfmx.js";
@@ -30,7 +30,7 @@ import {
   resolveUiSource,
   siteInstallBase,
   validateDeploymentConfig
-} from "../chunk-qergre5a.js";
+} from "../chunk-xgnxz5dz.js";
 import"../chunk-49nmy775.js";
 import"../chunk-93hjhs78.js";
 import {

package/dist/deploy/local-dashboard-server.d.ts

@@ -28,4 +28,5 @@ export interface DashboardAction {
 export declare function sanitizeCloudConfig(config: CloudConfig): Record<string, any>;
 export declare function dashboardActions(environment: EnvironmentType): DashboardAction[];
 export declare function resolveDashboardAction(id: string, environment: EnvironmentType): DashboardAction | undefined;
+export declare function isBoxOnlyPage(pathname: string): boolean;
 export declare function startLocalDashboardServer(options?: LocalDashboardServerOptions): Promise<LocalDashboardServer>;

package/dist/drivers/hetzner/client.d.ts

@@ -2,6 +2,7 @@
  * Hetzner Cloud API client
  * @see https://docs.hetzner.cloud/
  */
+import type { CloudConfig } from '@ts-cloud/core';
 export interface HetznerApiErrorBody {
     error?: {
         code?: string;
@@ -183,7 +184,14 @@ export declare class HetznerClient {
         maxWaitMs?: number;
     }): Promise<HetznerServer>;
 }
-export declare function resolveHetznerApiToken(configToken?: string): string;
+/**
+ * The Hetzner API token, or a clear error when none is configured.
+ *
+ * Resolution itself lives in {@link import('./config').resolveHetznerApiToken}
+ * so the driver, the client and the dashboard cannot drift apart on where a
+ * setting comes from.
+ */
+export declare function resolveHetznerApiToken(configToken?: string, config?: CloudConfig): string;
 /**
  * Normalize an OpenSSH public key to its `<type> <base64>` body, dropping the
  * trailing comment. Lets us match a local key against keys already registered

package/dist/drivers/hetzner/config.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The single place Hetzner settings are resolved.
+ *
+ * Every Hetzner value can come from several sources, and they used to be
+ * resolved ad-hoc wherever they were needed: the driver, the API client and the
+ * dashboard each had their own chain, with defaults duplicated at call sites.
+ * That drifted — the dashboard honored `HETZNER_LOCATION` while the driver did
+ * not, so a box provisioned in `fsn1` was reported as being somewhere else.
+ *
+ * One precedence, applied everywhere:
+ *
+ *   1. an explicit argument (a driver option — the caller means it)
+ *   2. `cloud.config.ts` → `hetzner.*` (checked into the repo, reviewable)
+ *   3. environment (`HCLOUD_*`, with the `HETZNER_*` alias) — for secrets and
+ *      per-machine overrides
+ *   4. the documented default in {@link HETZNER_DEFAULTS}
+ *
+ * Config beats environment deliberately, for every field without exception: a
+ * value written in `cloud.config.ts` is the reviewed intent for the project,
+ * and a stray shell export should not silently redirect a deploy to another
+ * datacenter or another account. One rule, no special cases to remember.
+ *
+ * In practice the token is simply left out of `cloud.config.ts` (it is a
+ * secret), so it comes from `HCLOUD_TOKEN` — but that is a convention, not a
+ * different precedence.
+ */
+import type { CloudConfig } from '@ts-cloud/core';
+/** The documented defaults. These are the only place a Hetzner default lives. */
+export declare const HETZNER_DEFAULTS: {
+    /** Falkenstein, Germany. */
+    readonly location: 'fsn1';
+    readonly image: 'ubuntu-24.04';
+    readonly sshUser: 'root';
+    readonly sshPrivateKeyPath: '~/.ssh/id_ed25519';
+};
+/** `~/…` → an absolute path. Hetzner key paths are user-supplied and often use `~`. */
+export declare function expandHome(path: string): string;
+/**
+ * The Hetzner API token, or undefined when none is set.
+ *
+ * Never defaulted: a missing token must fail loudly at the call site rather
+ * than silently targeting the wrong account. Callers that need one should use
+ * `requireHetznerApiToken`.
+ */
+export declare function resolveHetznerApiToken(explicit?: string, config?: CloudConfig): string | undefined;
+/** Datacenter location slug, e.g. `fsn1`, `nbg1`, `hel1`. */
+export declare function resolveHetznerLocation(config?: CloudConfig, explicit?: string): string;
+/**
+ * Server image slug.
+ *
+ * `infrastructure.compute.image` wins over `hetzner.image`: it is the
+ * provider-agnostic way to pin an image (and is what a golden-image bake sets),
+ * so it is the more specific statement of intent.
+ */
+export declare function resolveHetznerImage(config?: CloudConfig, explicit?: string): string;
+/** SSH user for deploy commands. */
+export declare function resolveHetznerSshUser(config?: CloudConfig, explicit?: string): string;
+/** Absolute path to the SSH private key used for deploy commands. */
+export declare function resolveHetznerSshPrivateKeyPath(config?: CloudConfig, explicit?: string): string;
+/**
+ * Absolute path to the SSH public key uploaded to Hetzner. Defaults to the
+ * private key's path with `.pub`, which is where `ssh-keygen` puts it.
+ */
+export declare function resolveHetznerSshPublicKeyPath(config?: CloudConfig, explicit?: string, privateKeyPath?: string): string;
+/** Every resolved Hetzner setting, for a driver or a diagnostic to read at once. */
+export interface ResolvedHetznerSettings {
+    apiToken?: string;
+    location: string;
+    image: string;
+    sshUser: string;
+    sshPrivateKeyPath: string;
+    sshPublicKeyPath: string;
+}
+export interface HetznerOverrides {
+    apiToken?: string;
+    location?: string;
+    image?: string;
+    sshUser?: string;
+    sshPrivateKeyPath?: string;
+    sshPublicKeyPath?: string;
+}
+/** Resolve the full Hetzner settings for `config`, applying `overrides` first. */
+export declare function resolveHetznerSettings(config?: CloudConfig, overrides?: HetznerOverrides): ResolvedHetznerSettings;

package/dist/drivers/hetzner/config.test.d.ts

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

package/dist/drivers/hetzner/factory-wiring.test.d.ts

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

package/dist/drivers/index.js

@@ -48,7 +48,7 @@ import {
   waitForCloudInit,
   waitForSsh,
   wrapCloudInitUserData
-} from "../chunk-qergre5a.js";
+} from "../chunk-xgnxz5dz.js";
 import"../chunk-49nmy775.js";
 import"../chunk-93hjhs78.js";
 import"../chunk-qpj3edwz.js";

package/dist/drivers/shared/rpx-gateway.d.ts

@@ -48,8 +48,20 @@ export interface RpxRoute {
      * with automatic health-check failover (see rpx's `ProxyFrom`/`UpstreamTarget`).
      */
     from?: string | string[];
-    /** Absolute directory served for a `server-static` route (`/var/www/<name>`). */
-    static?: string;
+    /**
+     * Static serving for a `server-static` route. rpx reads `spa` and
+     * `pathRewriteStyle` ONLY from the object form (`{ dir, spa, pathRewriteStyle }`);
+     * a bare string disables both (rpx forces `spa: false`, `pathRewriteStyle:
+     * 'directory'`). So SPA fallback + flat-URL sites MUST use the object form —
+     * see `buildRpxConfig`. The string shorthand remains valid for a plain
+     * directory served with the route-level `cleanUrls`.
+     */
+    static?: string | {
+        dir: string;
+        spa?: boolean;
+        pathRewriteStyle?: 'directory' | 'flat';
+        maxAge?: number;
+    };
     /**
      * Redirect target for a `redirect` site — the gateway answers `to` (the host)
      * with an HTTP redirect here instead of proxying/serving. The request path +
@@ -197,6 +209,21 @@ export declare function buildRpxLbConfig(sites: Record<string, SiteConfig | unde
  * resolves its own config from its install dir, not an arbitrary path.
  */
 export declare function renderRpxLauncher(config: RpxGatewayConfig): string;
+/**
+ * True when this compute is fronted by the rpx gateway — either explicitly
+ * (`webServer: 'rpx'`) or implicitly by opting into the rpx proxy engine
+ * (`proxy.engine: 'rpx'`). Setting `proxy.engine: 'rpx'` alone provisions and
+ * runs the gateway on :80/:443, so the deploy MUST NOT also stand up nginx +
+ * certbot for a site — that races the gateway for :80 and the certbot HTTP-01
+ * challenge fails with "Address already in use". Treating either signal as
+ * "rpx mode" keeps the nginx/SSL path and the gateway path from contradicting.
+ */
+export declare function usesRpxProxy(compute?: {
+    webServer?: string;
+    proxy?: {
+        engine?: string;
+    };
+}): boolean;
 /** Default install location for the gateway launcher + config on the box. */
 export declare const RPX_DIR = "/etc/rpx";
 export declare const RPX_INSTALL_DIR = "/opt/rpx-gateway";

package/dist/index.js

@@ -55,7 +55,7 @@ import {
   sanitizeCloudConfig,
   setMaintenance,
   startLocalDashboardServer
-} from "./chunk-pr3g0b0t.js";
+} from "./chunk-nt2hrnva.js";
 import {
   buildAndPushServerlessImage
 } from "./chunk-qgnyzfmx.js";
@@ -105,7 +105,7 @@ import {
   waitForCloudInit,
   waitForSsh,
   wrapCloudInitUserData
-} from "./chunk-qergre5a.js";
+} from "./chunk-xgnxz5dz.js";
 import {
   ABTestManager,
   AI,