@saws/core 2.0.0-beta.0 → 2.0.0-beta.3

package/dist/ServiceDefinition.js

@@ -0,0 +1,119 @@
+import { writeStageOutputs } from "./utils/stage-outputs.js";
+import { parameterizedEnvVarName } from "./utils/parameterized-env-var-name.js";
+import { SecretReference } from "./secrets-manager.js";
+export class ServiceDefinition {
+    name;
+    dependencies;
+    environment;
+    outputs = {};
+    deved = false;
+    deployed = false;
+    runtimeLogSink;
+    constructor(config) {
+        this.name = config.name;
+        this.dependencies = config.dependencies ?? [];
+        this.environment = config.environment ?? {};
+    }
+    async init() {
+        return;
+    }
+    async dev() {
+        this.writeRuntimeLog(`Start dev ${this.name}\n`);
+        await this.forEachDependencyAsync(async (dependency) => {
+            if (dependency.deved)
+                return;
+            await dependency.dev();
+            dependency.deved = true;
+        });
+    }
+    async deploy(stage) {
+        console.log("Start deploy", this.name);
+        await this.forEachDependencyAsync(async (dependency) => {
+            if (dependency.deployed)
+                return;
+            await dependency.deploy(stage);
+            dependency.deployed = true;
+        });
+    }
+    setRuntimeLogSink(sink) {
+        this.runtimeLogSink = sink;
+        this.forEachDependency((dependency) => dependency.setRuntimeLogSink(sink));
+    }
+    writeRuntimeLog(chunk, stream = "stdout") {
+        if (this.runtimeLogSink == null) {
+            const output = stream === "stderr" ? process.stderr : process.stdout;
+            output.write(chunk);
+            return;
+        }
+        this.runtimeLogSink({
+            serviceName: this.name,
+            stream,
+            chunk,
+            timestamp: new Date(),
+        });
+    }
+    getRuntimeLogSink() {
+        return this.runtimeLogSink;
+    }
+    getOutputs() {
+        return this.outputs;
+    }
+    async setOutputs(outputs, stage) {
+        this.outputs = {
+            ...this.outputs,
+            ...outputs,
+        };
+        await writeStageOutputs({
+            [this.name]: this.outputs,
+        }, stage);
+    }
+    forEachDependency(callback) {
+        for (const dependency of this.dependencies) {
+            callback(dependency);
+        }
+    }
+    async forEachDependencyAsync(callback) {
+        for (const dependency of this.dependencies) {
+            await callback(dependency);
+        }
+    }
+    getAllDependencies() {
+        const all = [this];
+        for (const dependency of this.dependencies) {
+            all.push(dependency);
+            all.push(...dependency.getAllDependencies());
+        }
+        return all;
+    }
+    // this needs to be recursive down dependencies
+    exit() {
+        this.forEachDependency((dependency) => dependency.exit());
+    }
+    parameterizedEnvVarName(envVarName) {
+        return parameterizedEnvVarName(this.name, envVarName);
+    }
+    // this needs to be recursive down dependencies
+    async getEnvironmentVariables(stage, _target = "container") {
+        return {};
+    }
+    async getDependenciesEnvironmentVariables(stage, target = "container") {
+        const environmentVariables = {};
+        await this.forEachDependencyAsync(async (definition) => {
+            Object.assign(environmentVariables, await definition.getEnvironmentVariables(stage, target));
+        });
+        return environmentVariables;
+    }
+    async getStageEnvironmentVariables(stage) {
+        const environment = this.environment[stage] ?? {};
+        return Object.fromEntries(await Promise.all(Object.entries(environment).map(async ([name, value]) => [
+            name,
+            value instanceof SecretReference ? await value.resolve({ stage }) : value,
+        ])));
+    }
+    getStdOut() {
+        return null;
+    }
+    getStdErr() {
+        return null;
+    }
+}

package/dist/find-service-definition.d.ts

@@ -1,9 +1,2 @@
-import type { ServiceDefinition } from "./service-definition.js";
-/**
- * Finds one configured service by name in a dependency graph.
- *
- * Service names are CLI identifiers, so a name must resolve to exactly one
- * service instance. Reusing the same instance in multiple branches is allowed.
- */
+import type { ServiceDefinition } from "./ServiceDefinition.js";
 export declare function findServiceDefinition(root: ServiceDefinition, name: string): ServiceDefinition;
-//# sourceMappingURL=find-service-definition.d.ts.map

package/dist/find-service-definition.js

@@ -1,9 +1,3 @@
-/**
- * Finds one configured service by name in a dependency graph.
- *
- * Service names are CLI identifiers, so a name must resolve to exactly one
- * service instance. Reusing the same instance in multiple branches is allowed.
- */
 export function findServiceDefinition(root, name) {
     const matches = [];
     const visited = new Set();

package/dist/get-saws-config.d.ts

@@ -1,3 +1,7 @@
-import type { ServiceDefinition } from "./service-definition.js";
-export declare function getSawsConfig(configPath?: string): Promise<ServiceDefinition>;
-//# sourceMappingURL=get-saws-config.d.ts.map
+import { type ServiceDefinition } from "./ServiceDefinition.js";
+export type SawsConfigModule = {
+    default: ServiceDefinition;
+    [name: string]: unknown;
+};
+export declare function getSawsConfigModule(path?: string): Promise<SawsConfigModule>;
+export declare function getSawsConfig(path?: string): Promise<ServiceDefinition>;

package/dist/get-saws-config.js

@@ -1,58 +1,8 @@
-import { pathToFileURL } from "node:url";
-import path from "node:path";
-import { access, rm, writeFile } from "node:fs/promises";
-import ts from "typescript";
-export async function getSawsConfig(configPath) {
-    const resolvedPath = await resolveConfigPath(configPath);
-    const importPath = resolvedPath.endsWith(".ts")
-        ? await transpileConfig(resolvedPath)
-        : resolvedPath;
-    try {
-        const moduleUrl = pathToFileURL(importPath).href;
-        const imported = await import(`${moduleUrl}?t=${Date.now()}`);
-        const serviceDefinition = imported.default ?? imported;
-        if (serviceDefinition == null || typeof serviceDefinition.deploy !== "function") {
-            throw new Error(`Expected ${resolvedPath} to export a ServiceDefinition as the default export`);
-        }
-        return serviceDefinition;
-    }
-    finally {
-        if (importPath !== resolvedPath) {
-            await rm(importPath, { force: true });
-        }
-    }
+import { resolve } from "path";
+export async function getSawsConfigModule(path = "./saws.ts") {
+    const pathToConfig = resolve(path);
+    return (await import(pathToConfig));
 }
-async function resolveConfigPath(configPath) {
-    if (configPath != null)
-        return path.resolve(configPath);
-    for (const candidate of ["./saws.ts", "./saws.js"]) {
-        const resolved = path.resolve(candidate);
-        try {
-            await access(resolved);
-            return resolved;
-        }
-        catch (error) {
-            if (error.code !== "ENOENT")
-                throw error;
-        }
-    }
-    return path.resolve("./saws.ts");
-}
-async function transpileConfig(configPath) {
-    const outputPath = path.join(path.dirname(configPath), `.saws-${path.basename(configPath, ".ts")}-${process.pid}-${Date.now()}.mjs`);
-    const source = await ts.sys.readFile(configPath);
-    if (source == null) {
-        throw new Error(`Unable to read ${configPath}`);
-    }
-    const transpiled = ts.transpileModule(source, {
-        compilerOptions: {
-            target: ts.ScriptTarget.ES2022,
-            module: ts.ModuleKind.ES2022,
-            moduleResolution: ts.ModuleResolutionKind.NodeNext,
-            esModuleInterop: true,
-        },
-        fileName: configPath,
-    });
-    await writeFile(outputPath, transpiled.outputText);
-    return outputPath;
+export async function getSawsConfig(path = "./saws.ts") {
+    return (await getSawsConfigModule(path)).default;
 }

package/dist/host-readiness.d.ts

@@ -0,0 +1,12 @@
+export type HostExposure = "tunnel" | "public";
+export interface HostReadinessConfig {
+    name: string;
+    deploymentUser: string;
+    deploymentPublicKey: string;
+    exposure: HostExposure;
+    sshPort: number;
+    allowedTcpPorts: number[];
+}
+export declare function getReadinessHash(config: HostReadinessConfig): string;
+export declare function readinessCheckScript(config: HostReadinessConfig): string;
+export declare function readinessConfigureScript(config: HostReadinessConfig): string;

package/dist/host-readiness.js

@@ -0,0 +1,230 @@
+import { createHash } from "node:crypto";
+import { shellQuote } from "./utils/shell-quote.js";
+const READINESS_VERSION = 4;
+const READINESS_DIRECTORY = "/etc/saws";
+const READINESS_FILE = `${READINESS_DIRECTORY}/host-readiness`;
+const DEFAULT_APP_DIRECTORY = "/opt/saws";
+export function getReadinessHash(config) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        version: READINESS_VERSION,
+        deploymentUser: config.deploymentUser,
+        deploymentPublicKeyHash: createHash("sha256")
+            .update(config.deploymentPublicKey)
+            .digest("hex"),
+        exposure: config.exposure,
+        sshPort: config.sshPort,
+        allowedTcpPorts: config.allowedTcpPorts,
+    }))
+        .digest("hex");
+}
+export function readinessCheckScript(config) {
+    const hash = getReadinessHash(config);
+    const configureCommand = `saws host configure ${config.name}`;
+    return `expected=${shellQuote(hash)}
+actual=$(cat ${shellQuote(READINESS_FILE)} 2>/dev/null || true)
+if [ "$actual" != "$expected" ]; then
+  echo ${shellQuote(`Host "${config.name}" is not configured for this deployment. Run: ${configureCommand}`)} >&2
+  exit 78
+fi
+deployment_user=${shellQuote(config.deploymentUser)}
+deployment_public_key=${shellQuote(config.deploymentPublicKey)}
+deployment_home=$(getent passwd "$deployment_user" | cut -d: -f6)
+if [ -z "$deployment_home" ] ||
+   ! grep -Fqx -- "$deployment_public_key" "$deployment_home/.ssh/authorized_keys" 2>/dev/null; then
+  echo ${shellQuote(`Deployment SSH access has drifted on host "${config.name}". Run: ${configureCommand}`)} >&2
+  exit 78
+fi
+if [ ! -d ${shellQuote(DEFAULT_APP_DIRECTORY)} ] || [ ! -w ${shellQuote(DEFAULT_APP_DIRECTORY)} ]; then
+  echo ${shellQuote(`Deployment directory ${DEFAULT_APP_DIRECTORY} is not writable on host "${config.name}". Run: ${configureCommand}`)} >&2
+  exit 78
+fi
+if ! command -v docker >/dev/null 2>&1 || ! docker info >/dev/null 2>&1; then
+  echo ${shellQuote(`Docker is not ready on host "${config.name}". Run: ${configureCommand}`)} >&2
+  exit 78
+fi
+if ! systemctl is-active --quiet docker ||
+   ! systemctl is-active --quiet fail2ban ||
+   ! systemctl is-active --quiet ufw ||
+   ! systemctl is-active --quiet saws-docker-firewall ||
+   [ ! -r /etc/ssh/sshd_config.d/00-saws-hardening.conf ] ||
+   [ ! -r /etc/sysctl.d/60-saws-hardening.conf ] ||
+   [ ! -r /etc/apt/apt.conf.d/20auto-upgrades ] ||
+   [ ! -x /usr/local/sbin/saws-docker-firewall ]; then
+  echo ${shellQuote(`Host "${config.name}" has drifted from the required security baseline. Run: ${configureCommand}`)} >&2
+  exit 78
+fi`;
+}
+export function readinessConfigureScript(config) {
+    const applicationPorts = config.allowedTcpPorts.join(" ");
+    const firewallPorts = [config.sshPort, ...config.allowedTcpPorts]
+        .filter((port, index, ports) => ports.indexOf(port) === index)
+        .join(" ");
+    const hash = getReadinessHash(config);
+    return `export DEBIAN_FRONTEND=noninteractive
+deployment_user=${shellQuote(config.deploymentUser)}
+deployment_public_key=${shellQuote(config.deploymentPublicKey)}
+if [ -z "$deployment_user" ] || [ -z "$deployment_public_key" ]; then
+  echo "Deployment user and public key are required" >&2
+  exit 1
+fi
+if [ "$(uname -s)" != "Linux" ] || [ ! -r /etc/os-release ]; then
+  echo "SAWS host configuration supports Debian and Ubuntu Linux only" >&2
+  exit 1
+fi
+. /etc/os-release
+case "\${ID:-}" in
+  debian|ubuntu) ;;
+  *)
+    echo "SAWS host configuration does not support \${PRETTY_NAME:-this operating system}" >&2
+    exit 1
+    ;;
+esac
+
+apt-get update
+apt-get install -y ca-certificates fail2ban ufw unattended-upgrades
+if ! command -v docker >/dev/null 2>&1; then
+  apt-get install -y docker.io
+fi
+systemctl enable --now docker
+docker info >/dev/null
+
+if ! id "$deployment_user" >/dev/null 2>&1; then
+  useradd --create-home --shell /bin/bash "$deployment_user"
+fi
+if [ "$deployment_user" != root ]; then
+  usermod -aG docker "$deployment_user"
+fi
+
+deployment_home=$(getent passwd "$deployment_user" | cut -d: -f6)
+deployment_group=$(id -gn "$deployment_user")
+if [ -z "$deployment_home" ] || [ ! -d "$deployment_home" ]; then
+  echo "Deployment user $deployment_user does not have a usable home directory" >&2
+  exit 1
+fi
+chown "$deployment_user:$deployment_group" "$deployment_home"
+install -d -m 0700 -o "$deployment_user" -g "$deployment_group" "$deployment_home/.ssh"
+install -d -m 0755 -o "$deployment_user" -g "$deployment_group" ${shellQuote(DEFAULT_APP_DIRECTORY)}
+authorized_keys="$deployment_home/.ssh/authorized_keys"
+touch "$authorized_keys"
+chown "$deployment_user:$deployment_group" "$authorized_keys"
+chmod 0600 "$authorized_keys"
+if ! grep -Fqx -- "$deployment_public_key" "$authorized_keys"; then
+  printf '%s\\n' "$deployment_public_key" >> "$authorized_keys"
+fi
+if ! grep -Fqx -- "$deployment_public_key" "$authorized_keys"; then
+  echo "Refusing to disable SSH passwords: deployment public key installation failed" >&2
+  exit 1
+fi
+
+install -d -m 0755 /etc/ssh/sshd_config.d
+rm -f /etc/ssh/sshd_config.d/60-saws-hardening.conf
+cat > /etc/ssh/sshd_config.d/00-saws-hardening.conf <<'EOF'
+PasswordAuthentication no
+KbdInteractiveAuthentication no
+PermitEmptyPasswords no
+PermitRootLogin prohibit-password
+PubkeyAuthentication yes
+X11Forwarding no
+MaxAuthTries 3
+EOF
+sshd -t
+sshd -T | grep -qx 'passwordauthentication no'
+sshd -T | grep -qx 'kbdinteractiveauthentication no'
+sshd -T | grep -qx 'pubkeyauthentication yes'
+
+cat > /etc/sysctl.d/60-saws-hardening.conf <<'EOF'
+net.ipv4.conf.all.accept_redirects=0
+net.ipv4.conf.default.accept_redirects=0
+net.ipv4.conf.all.send_redirects=0
+net.ipv4.conf.default.send_redirects=0
+net.ipv4.conf.all.rp_filter=1
+net.ipv4.conf.default.rp_filter=1
+net.ipv4.tcp_syncookies=1
+net.ipv6.conf.all.accept_redirects=0
+net.ipv6.conf.default.accept_redirects=0
+EOF
+sysctl --system >/dev/null
+
+cat > /etc/apt/apt.conf.d/20auto-upgrades <<'EOF'
+APT::Periodic::Update-Package-Lists "1";
+APT::Periodic::Unattended-Upgrade "1";
+EOF
+install -d -m 0755 /etc/fail2ban/jail.d
+cat > /etc/fail2ban/jail.d/saws.conf <<EOF
+[sshd]
+enabled = true
+port = ${config.sshPort}
+EOF
+systemctl enable --now fail2ban
+systemctl restart fail2ban
+
+ufw --force reset
+ufw default deny incoming
+ufw default allow outgoing
+for port in ${firewallPorts}; do
+  ufw allow "$port/tcp"
+done
+ufw --force enable
+
+cat > /usr/local/sbin/saws-docker-firewall <<EOF
+#!/bin/sh
+set -eu
+application_ports="${applicationPorts}"
+
+external_interface=\\$(ip -4 route list default | awk 'NR == 1 { print \\$5 }')
+if [ -z "\\$external_interface" ]; then
+  echo "Could not determine the host's external network interface" >&2
+  exit 1
+fi
+iptables -N DOCKER-USER 2>/dev/null || true
+iptables -N SAWS-DOCKER 2>/dev/null || true
+iptables -F SAWS-DOCKER
+iptables -A SAWS-DOCKER -i "\\$external_interface" -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
+for port in \\$application_ports; do
+  iptables -A SAWS-DOCKER -i "\\$external_interface" -p tcp -m conntrack --ctorigdstport "\\$port" -j ACCEPT
+done
+iptables -A SAWS-DOCKER -i "\\$external_interface" -j DROP
+iptables -A SAWS-DOCKER -j RETURN
+iptables -C DOCKER-USER -j SAWS-DOCKER 2>/dev/null || iptables -I DOCKER-USER 1 -j SAWS-DOCKER
+
+if ip6tables -nL DOCKER-USER >/dev/null 2>&1; then
+  external_interface6=\\$(ip -6 route list default | awk 'NR == 1 { print \\$5 }')
+  if [ -n "\\$external_interface6" ]; then
+    ip6tables -N SAWS-DOCKER 2>/dev/null || true
+    ip6tables -F SAWS-DOCKER
+    ip6tables -A SAWS-DOCKER -i "\\$external_interface6" -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
+    for port in \\$application_ports; do
+      ip6tables -A SAWS-DOCKER -i "\\$external_interface6" -p tcp -m conntrack --ctorigdstport "\\$port" -j ACCEPT
+    done
+    ip6tables -A SAWS-DOCKER -i "\\$external_interface6" -j DROP
+    ip6tables -A SAWS-DOCKER -j RETURN
+    ip6tables -C DOCKER-USER -j SAWS-DOCKER 2>/dev/null || ip6tables -I DOCKER-USER 1 -j SAWS-DOCKER
+  fi
+fi
+EOF
+chmod 0755 /usr/local/sbin/saws-docker-firewall
+cat > /etc/systemd/system/saws-docker-firewall.service <<'EOF'
+[Unit]
+Description=SAWS Docker firewall rules
+After=network-online.target docker.service ufw.service
+Wants=network-online.target docker.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/usr/local/sbin/saws-docker-firewall
+
+[Install]
+WantedBy=multi-user.target
+EOF
+systemctl daemon-reload
+systemctl enable saws-docker-firewall
+systemctl restart saws-docker-firewall
+
+systemctl reload ssh 2>/dev/null || systemctl reload sshd
+install -d -m 0755 ${shellQuote(READINESS_DIRECTORY)}
+printf '%s\\n' ${shellQuote(hash)} > ${shellQuote(READINESS_FILE)}
+chmod 0644 ${shellQuote(READINESS_FILE)}
+echo "SAWS host configuration complete"`;
+}

package/dist/index.d.ts

@@ -1,7 +1,6 @@
-export * from "./context.js";
+export * from "./ServiceDefinition.js";
 export * from "./find-service-definition.js";
 export * from "./get-saws-config.js";
-export * from "./service-commands.js";
-export * from "./service-definition.js";
-export * from "./service-types.js";
-//# sourceMappingURL=index.d.ts.map
+export * from "./Host.js";
+export * from "./host-readiness.js";
+export * from "./secrets-manager.js";

package/dist/index.js

@@ -1,6 +1,6 @@
-export * from "./context.js";
+export * from "./ServiceDefinition.js";
 export * from "./find-service-definition.js";
 export * from "./get-saws-config.js";
-export * from "./service-commands.js";
-export * from "./service-definition.js";
-export * from "./service-types.js";
+export * from "./Host.js";
+export * from "./host-readiness.js";
+export * from "./secrets-manager.js";

package/dist/secrets-manager.d.ts

@@ -0,0 +1,63 @@
+export interface SecretsManagerConfig {
+    /** Overrides the stage derived from the command's runtime context or STAGE. */
+    stage?: string;
+    rootDir?: string;
+    /** Overrides SAWS_SECRETS_PASSCODE and the project-root .env file. */
+    passcode?: string;
+}
+export type SecretScope = "stage" | "global";
+export interface SecretResolutionContext {
+    stage: string;
+    rootDir?: string;
+}
+export declare class ParameterNotFoundError extends Error {
+    constructor(name: string);
+}
+export declare class SecretsDecryptionError extends Error {
+    constructor();
+}
+/**
+ * A lazy reference to either a stage-aware or global secret.
+ *
+ * References can safely be created while saws.ts is loaded, before the CLI
+ * knows which runtime stage will consume a stage-aware secret.
+ */
+export declare class SecretReference {
+    readonly name: string;
+    readonly scope: SecretScope;
+    private readonly manager;
+    constructor(manager: SecretsManager, name: string, scope: SecretScope);
+    resolve(context?: SecretResolutionContext): Promise<string>;
+    /** @internal */
+    isManagedBy(manager: SecretsManager): boolean;
+}
+export declare class GlobalSecrets {
+    private readonly manager;
+    constructor(manager: SecretsManager);
+    reference(name: string): SecretReference;
+    get(name: string): Promise<string>;
+    set(name: string, value: string): Promise<void>;
+    get secretsFilePath(): string;
+}
+export declare class SecretsManager {
+    readonly global: GlobalSecrets;
+    readonly rootDir: string;
+    private readonly configuredStage?;
+    private readonly configuredPasscode?;
+    constructor(config?: SecretsManagerConfig);
+    get stage(): string;
+    reference(name: string): SecretReference;
+    get(name: string): Promise<string>;
+    set(name: string, value: string): Promise<void>;
+    get secretsFilePath(): string;
+    /** @internal */
+    getFromScope(name: string, scope: SecretScope, resolutionStage?: string): Promise<string>;
+    /** @internal */
+    setInScope(name: string, value: string, scope: SecretScope, resolutionStage?: string): Promise<void>;
+    /** @internal */
+    getSecretsFilePath(scope: SecretScope, resolutionStage?: string): string;
+    private resolveStage;
+    private readSecrets;
+    private writeSecrets;
+    private getPasscode;
+}