@saws/core 1.0.11 → 2.0.0-beta.11

package/dist/find-service-definition.js

@@ -0,0 +1,25 @@
+export function findServiceDefinition(root, name) {
+    const matches = [];
+    const visited = new Set();
+    const visit = (service) => {
+        if (visited.has(service))
+            return;
+        visited.add(service);
+        if (service.name === name)
+            matches.push(service);
+        for (const dependency of service.dependencies)
+            visit(dependency);
+    };
+    visit(root);
+    if (matches.length === 0) {
+        const available = [...visited]
+            .map((service) => service.name)
+            .sort()
+            .join(", ");
+        throw new Error(`Service "${name}" was not found. Available services: ${available || "(none)"}`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Service name "${name}" is ambiguous. Service names must be unique within a SAWS configuration.`);
+    }
+    return matches[0];
+}

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

@@ -0,0 +1,14 @@
+import { type ServiceDefinition } from "./ServiceDefinition.js";
+export type SawsCreate<TConfig = unknown> = (config: TConfig) => ServiceDefinition | Promise<ServiceDefinition>;
+export type SawsConfigModule = {
+    default: ServiceDefinition;
+    create?: SawsCreate;
+    [name: string]: unknown;
+};
+export type SawsCreateModule<TConfig = unknown> = {
+    create: SawsCreate<TConfig>;
+    [name: string]: unknown;
+};
+export declare function getSawsConfigModule(path?: string): Promise<SawsConfigModule>;
+export declare function getSawsConfig(path?: string): Promise<ServiceDefinition>;
+export declare function createSawsConfig<TConfig>(module: SawsCreateModule<TConfig>, config: TConfig): Promise<ServiceDefinition>;

package/dist/get-saws-config.js

@@ -0,0 +1,20 @@
+import { resolve } from "path";
+export async function getSawsConfigModule(path = "./saws.ts") {
+    const pathToConfig = resolve(path);
+    return (await import(pathToConfig));
+}
+export async function getSawsConfig(path = "./saws.ts") {
+    return (await getSawsConfigModule(path)).default;
+}
+export async function createSawsConfig(module, config) {
+    if (typeof module.create !== "function") {
+        throw new Error('Packaged SAWS applications must export a factory function named "create"');
+    }
+    const serviceDefinition = await module.create(config);
+    if (serviceDefinition == null ||
+        typeof serviceDefinition !== "object" ||
+        typeof serviceDefinition.deploy !== "function") {
+        throw new Error('The SAWS application "create" function must return a ServiceDefinition');
+    }
+    return serviceDefinition;
+}

package/dist/global-hosts.d.ts

@@ -0,0 +1,8 @@
+import { Host, type HostConfig } from "./Host.js";
+import { SecretsManager } from "./secrets-manager.js";
+export type GlobalHostConfig = Omit<HostConfig, "sshPrivateKey" | "dryRun">;
+export declare function getSawsHome(): string;
+export declare function getGlobalHost(name: string): Host;
+export declare function createGlobalHost(config: GlobalHostConfig): Promise<Host>;
+export declare function getGlobalHostSecretsManager(): SecretsManager;
+export declare function getGlobalHostProfilePath(name: string): string;

package/dist/global-hosts.js

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Host, hostSshPrivateKeySecretName } from "./Host.js";
+import { SecretsManager } from "./secrets-manager.js";
+const GLOBAL_HOST_PROFILE_VERSION = 1;
+const managers = new Map();
+export function getSawsHome() {
+    const configuredHome = process.env.SAWS_HOME;
+    if (configuredHome != null && configuredHome.trim().length === 0) {
+        throw new Error("SAWS_HOME cannot be empty");
+    }
+    return path.resolve(configuredHome ?? path.join(os.homedir(), ".saws"));
+}
+export function getGlobalHost(name) {
+    const normalizedName = requireGlobalHostName(name);
+    const profilePath = getGlobalHostProfilePath(normalizedName);
+    let contents;
+    try {
+        contents = fs.readFileSync(profilePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Global host "${normalizedName}" is not configured. Run: saws host create ${normalizedName}`);
+        }
+        throw error;
+    }
+    const profile = parseGlobalHost(contents, profilePath);
+    if (profile.name !== normalizedName) {
+        throw new Error(`Global host profile ${profilePath} declares name "${profile.name}" instead of "${normalizedName}"`);
+    }
+    return createHost(profile);
+}
+export async function createGlobalHost(config) {
+    const host = createHost({
+        ...config,
+        name: requireGlobalHostName(config.name),
+    });
+    const profile = toStoredGlobalHost(host);
+    const profilePath = getGlobalHostProfilePath(host.name);
+    await mkdir(path.dirname(profilePath), { recursive: true });
+    try {
+        await writeFile(profilePath, `${JSON.stringify(profile, null, 2)}\n`, { flag: "wx" });
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw new Error(`Global host "${host.name}" is already configured`);
+        }
+        throw error;
+    }
+    return host;
+}
+export function getGlobalHostSecretsManager() {
+    const sawsHome = getSawsHome();
+    let manager = managers.get(sawsHome);
+    if (manager == null) {
+        manager = new SecretsManager({
+            rootDir: sawsHome,
+            sawsDirectory: sawsHome,
+        });
+        managers.set(sawsHome, manager);
+    }
+    return manager;
+}
+export function getGlobalHostProfilePath(name) {
+    return path.join(getSawsHome(), "hosts", requireGlobalHostName(name), "host.json");
+}
+function createHost(config) {
+    const manager = getGlobalHostSecretsManager();
+    return new Host({
+        ...config,
+        sshPrivateKey: manager.global.reference(hostSshPrivateKeySecretName(config.name)),
+    });
+}
+function toStoredGlobalHost(host) {
+    return {
+        version: GLOBAL_HOST_PROFILE_VERSION,
+        name: host.name,
+        address: host.address,
+        user: host.user,
+        sshPort: host.sshPort,
+        exposure: host.exposure,
+        allowedTcpPorts: host.allowedTcpPorts,
+        ...(host.platform == null ? {} : { platform: host.platform }),
+    };
+}
+function parseGlobalHost(contents, profilePath) {
+    let value;
+    try {
+        value = JSON.parse(contents);
+    }
+    catch {
+        throw new Error(`Global host profile ${profilePath} is not valid JSON`);
+    }
+    if (value == null || typeof value !== "object") {
+        throw new Error(`Global host profile ${profilePath} must contain an object`);
+    }
+    const profile = value;
+    if (profile.version !== GLOBAL_HOST_PROFILE_VERSION) {
+        throw new Error(`Global host profile ${profilePath} has an unsupported version`);
+    }
+    if (typeof profile.name !== "string") {
+        throw new Error(`Global host profile ${profilePath} must contain a name`);
+    }
+    try {
+        const host = createHost(profile);
+        return toStoredGlobalHost(host);
+    }
+    catch (error) {
+        throw new Error(`Global host profile ${profilePath} is invalid: ${error.message}`);
+    }
+}
+function requireGlobalHostName(name) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name)) {
+        throw new Error("Global host name must start with a letter or number and contain only letters, numbers, dots, underscores, or hyphens");
+    }
+    return name;
+}

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

@@ -0,0 +1,7 @@
+export * from "./ServiceDefinition.js";
+export * from "./find-service-definition.js";
+export * from "./get-saws-config.js";
+export * from "./Host.js";
+export * from "./global-hosts.js";
+export * from "./host-readiness.js";
+export * from "./secrets-manager.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./ServiceDefinition.js";
+export * from "./find-service-definition.js";
+export * from "./get-saws-config.js";
+export * from "./Host.js";
+export * from "./global-hosts.js";
+export * from "./host-readiness.js";
+export * from "./secrets-manager.js";

package/dist/secrets-manager.d.ts

@@ -0,0 +1,66 @@
+export interface SecretsManagerConfig {
+    /** Overrides the stage derived from the command's runtime context or STAGE. */
+    stage?: string;
+    rootDir?: string;
+    /** Overrides the directory containing secrets state. Defaults to `<rootDir>/.saws`. */
+    sawsDirectory?: 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;
+    readonly sawsDirectory: 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;
+}