kampodine 0.2.2 → 0.4.0

package/scripts/deploy.sh

@@ -3,7 +3,7 @@
 #
 #   Mac:  podman build (VITE_BUILD_ID=<sha>) -> podman save (docker-archive)
 #         streamed over SSH -> podman load on the VM
-#   VM:   retag to 127.0.0.1:5000/esellar-api:latest -> rc-service esellar-api
+#   VM:   retag to 127.0.0.1:5000/kampodine-api:latest -> rc-service kampodine-api
 #         restart (the OpenRC supervise-daemon service re-runs the whole
 #         `podman run` against :latest — no pull in the run, so restarts are
 #         offline-safe) -> exec-fetch health probe with served-sha verify ->
@@ -26,12 +26,12 @@
 set -euo pipefail
 
 REPO_ROOT="$(git rev-parse --show-toplevel)"
-ESPELLAR_HOST="${ESPELLAR_HOST:-}"
+KAMPODINE_HOST="${KAMPODINE_HOST:-}"
 PROXY_HOST="${PROXY_HOST:-app.example.com}"
-ENV_FILE_REMOTE="/etc/esellar/env"
-DEPLOYED_SHA_FILE="/etc/esellar/deployed-sha"
+ENV_FILE_REMOTE="/etc/kampodine/env"
+DEPLOYED_SHA_FILE="/etc/kampodine/deployed-sha"
 ENV_CLEAR_KEYS='^(NODE_ENV|PORT|LIBSQL_TENANT_DIR|LIBSQL_API_MOUNT|STATIC_SPA_MOUNT)='
-IMAGE="127.0.0.1:5000/esellar-api"
+IMAGE="127.0.0.1:5000/kampodine-api"
 
 MODE="deploy"
 VERSION=""
@@ -40,8 +40,7 @@ REFRESH_CONFIG=0
 # SSH key resolution — GENERIC, no hardcoded personal paths:
 #   1. --ssh-key flag           (explicit, per-invocation)
 #   2. KAMPODINE_SSH_KEY env    (project-level: direnv / .envrc / export)
-#   3. ESSELLAR_SSH_KEY env     (legacy alias, kept for existing setups)
-#   4. empty → ssh-agent and/or the operator's ~/.ssh/config Host block
+#   3. empty → ssh-agent and/or the operator's ~/.ssh/config Host block
 #      (the POSIX way: per-host IdentityFile belongs in ssh config, not here)
 if [ -n "${KAMPODINE_SSH_KEY:-}" ]; then
     SSH_KEY="$KAMPODINE_SSH_KEY"
@@ -55,11 +54,26 @@ DOCKERFILE="${KAMPODINE_DOCKERFILE:-apps/api/Containerfile}"
 
 say() { printf '\033[1;34m[deploy]\033[0m %s\n' "$*"; }
 die() { printf '\033[1;31m[deploy] FAIL:\033[0m %s\n' "$*" >&2; exit 1; }
-usage() { grep '^#   kampodine deploy' "$0" | sed 's/^#   //'; exit 0; }
+usage() {
+  cat <<'EOF'
+Usage:
+  kampodine deploy [--host root@<ip>] [--version <sha7>] [--rollback [<sha7>]]
+                   [--dockerfile <path>] [--ssh-key <path>] [--skip-smoke] [--refresh-config]
+
+Examples:
+EOF
+  grep '^#   kampodine deploy' "$0" | sed 's/^#   //'
+  cat <<'EOF'
+
+Host/key resolution: --host | KAMPODINE_HOST; --ssh-key | KAMPODINE_SSH_KEY |
+KAMPODINE_SSH_KEY | ssh-agent / ~/.ssh/config.
+EOF
+  exit 0
+}
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --host) ESPELLAR_HOST="$2"; shift 2 ;;
+    --host) KAMPODINE_HOST="$2"; shift 2 ;;
     --ssh-key) SSH_KEY="$2"; shift 2 ;;
     --version) VERSION="$2"; MODE="version"; shift 2 ;;
     --rollback)
@@ -74,13 +88,13 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 [[ "$VERSION" != *..* && "$VERSION" =~ ^[0-9a-f]{4,40}$|^$ ]] || die "--version must be a git sha fragment"
-[ -n "$ESPELLAR_HOST" ] || die "set ESPELLAR_HOST=root@<vm-ip> (or a ~/.ssh/config Host alias via --host)"
+[ -n "$KAMPODINE_HOST" ] || die "set KAMPODINE_HOST=root@<vm-ip> (or a ~/.ssh/config Host alias via --host)"
 
 SSH_ARGS=(-o ConnectTimeout=10 -o BatchMode=yes)
 [[ -n "$SSH_KEY" ]] && SSH_ARGS+=(-i "$SSH_KEY")
 # $1 is a composed remote command — client-side expansion is the design.
 # shellcheck disable=SC2029
-vm() { ssh "${SSH_ARGS[@]}" "$ESPELLAR_HOST" "$1"; }
+vm() { ssh "${SSH_ARGS[@]}" "$KAMPODINE_HOST" "$1"; }
 
 # --- macOS ssh-agent quirk (first deploy from a fresh machine) ---------------
 if [[ "$(uname -s)" == "Darwin" ]]; then
@@ -126,7 +140,7 @@ vm "podman tag $IMAGE:$VER $IMAGE:latest" || die "stream retag failed"
 
 # --- env file from varlock (schema-only from HEAD; secrets from pass) ----------
 say "generating $ENV_FILE_REMOTE from varlock (schema-only from HEAD; secrets resolve from pass — no plaintext secret files)…"
-ENV_TMP="$(mktemp /tmp/esellar-env.XXXXXX)"
+ENV_TMP="$(mktemp /tmp/kampodine-env.XXXXXX)"
 trap 'rm -f "$ENV_TMP"' EXIT
 # Schema-only resolution: extract the COMMITTED schema into a scratch dir
 # inside the repo (plugin resolution needs node_modules; local
@@ -143,20 +157,20 @@ git -C "$REPO_ROOT" archive HEAD apps/api/.env.schema | tar -x -C "$ENV_SCHEMA_D
   | sed -E 's/^([A-Za-z_][A-Za-z0-9_]*)="(.*)"$/\1=\2/' > "$ENV_TMP" \
   || die "varlock env generation failed (pass store unlocked? schema committed?)"
 printf 'API_GIT_SHA=%s\n' "$VER" >> "$ENV_TMP"
-scp -q "${SSH_ARGS[@]}" "$ENV_TMP" "$ESPELLAR_HOST:/etc/esellar/env.tmp"
-vm "mv /etc/esellar/env.tmp $ENV_FILE_REMOTE && chmod 600 $ENV_FILE_REMOTE"
+scp -q "${SSH_ARGS[@]}" "$ENV_TMP" "$KAMPODINE_HOST:/etc/kampodine/env.tmp"
+vm "mv /etc/kampodine/env.tmp $ENV_FILE_REMOTE && chmod 600 $ENV_FILE_REMOTE"
 rm -f "$ENV_TMP"
 rm -rf "$ENV_SCHEMA_DIR"
 
 if [[ $REFRESH_CONFIG -eq 1 ]]; then
   say "ansible container-service refresh (--tags container-service — rc script/config drift repair)…"
   (cd "$REPO_ROOT/infra/alpine-host/ansible" \
-    && ansible-playbook -i "esellar-vm ansible_host=${ESPELLAR_HOST#*@},ansible_user=${ESPELLAR_HOST%%@*}," playbook.yml --tags container-service --private-key "${SSH_KEY:-~/.ssh/id_ed25519}") \
+    && ansible-playbook -i "kampodine-vm ansible_host=${KAMPODINE_HOST#*@},ansible_user=${KAMPODINE_HOST%%@*}," playbook.yml --tags container-service --private-key "${SSH_KEY:-~/.ssh/id_ed25519}") \
     || die "ansible playbook failed"
 fi
 
-say "rc-service esellar-api restart (supervise-daemon: stop-old/start-new podman run on the retagged :latest)…"
-vm "rc-service esellar-api restart" || die "esellar-api restart failed (rc-service esellar-api status)"
+say "rc-service kampodine-api restart (supervise-daemon: stop-old/start-new podman run on the retagged :latest)…"
+vm "rc-service kampodine-api restart" || die "kampodine-api restart failed (rc-service kampodine-api status)"
 
 say "health probe (host-side wget /api/auth/ok + served-sha — works for node AND scratch images)…"
 HEALTH_OK=0
@@ -173,17 +187,17 @@ for _ in $(seq 1 30); do
   sleep 3
 done
 if [[ $HEALTH_OK -ne 1 ]]; then
-  vm "podman logs --tail 30 esellar-api 2>&1" || true
-  vm "rc-service esellar-api status 2>&1" || true
+  vm "podman logs --tail 30 kampodine-api 2>&1" || true
+  vm "rc-service kampodine-api status 2>&1" || true
   PREV_HINT="$(vm "test -f $DEPLOYED_SHA_FILE && cat $DEPLOYED_SHA_FILE" 2>/dev/null || true)"
   die "container never became healthy — rollback: kampodine deploy --rollback${PREV_HINT:+ $PREV_HINT}"
 fi
-CANARY="$(vm "podman logs esellar-api 2>&1 | grep -c ENV_IMPORT_SUSPECT || true")"
+CANARY="$(vm "podman logs kampodine-api 2>&1 | grep -c ENV_IMPORT_SUSPECT || true")"
 say "container healthy, env-canary hits: $CANARY"
 
 say "kamal-proxy re-point (podman exec — same invocation kamal used)…"
 if vm "podman ps --format '{{.Names}}' | grep -qx kamal-proxy"; then
-  vm "podman exec kamal-proxy kamal-proxy deploy esellar-api --host=$PROXY_HOST --target=esellar-api:8080 --tls --health-check-path=/api/auth/ok" \
+  vm "podman exec kamal-proxy kamal-proxy deploy kampodine-api --host=$PROXY_HOST --target=kampodine-api:8080 --tls --health-check-path=/api/auth/ok" \
     || die "proxy re-point failed (podman logs kamal-proxy)"
 else
   say "  kamal-proxy not running — skipping re-point"

package/scripts/dns.sh

@@ -0,0 +1,266 @@
+#!/usr/bin/env bash
+# dns.sh — OCI DNS record management: the single surface for the coming DNS
+# era (today the stack is raw IP + sslip.io; when real zones land, records
+# are managed here, never by hand in the console).
+#
+# AUTH RULE (hard): the `oci` CLI's own auth ONLY — its config file
+# (~/.oci/config, selected via --profile) or instance principal. kampodine
+# NEVER accepts, stores, or logs credential material: no key flags, no
+# credential env vars, nothing token-shaped in args or output. The OCI config
+# file stays the single credential store.
+#
+# Types are pinned to A | AAAA | CNAME. `add` merges into the existing RRSet
+# (round-robin records survive); `rm` filters it; both are idempotence-aware.
+#
+# Zone/compartment: OCI_PROFILE (default: "default"), OCI_COMPARTMENT (required)
+# (required). Zone defaults to the compartment's ONLY zone; pass
+# --zone <id-or-name> when several exist.
+#
+# Usage:
+#   kampodine dns records [--zone <id-or-name>]                  # list records: domain / type / ttl / value
+#   kampodine dns add --name <label> --type A|AAAA|CNAME --value <target> [--ttl 300]
+#   kampodine dns rm --name <label> --type <A|AAAA|CNAME> --value <target>
+#   (all: optional --zone <id-or-name>; --instance-principal for instance auth)
+set -euo pipefail
+
+PROFILE="${OCI_PROFILE:-default}"
+COMPARTMENT_NAME="${OCI_COMPARTMENT:-kampodine}"
+AUTH_ARGS=()
+
+say() { printf '\033[1;34m[dns]\033[0m %s\n' "$*"; }
+die() { printf '\033[1;31m[dns] FAIL:\033[0m %s\n' "$*" >&2; exit 1; }
+usage() {
+  local code="${1:-0}"
+  printf 'Usage:\n'
+  grep '^#   kampodine dns' "$0" | sed 's/^#   //'
+  cat <<'EOF'
+
+Auth is the oci CLI's own — its config file (--profile) or instance
+principal. kampodine never accepts, stores, or logs credential material.
+Zone/compartment: OCI_PROFILE (default: "default"), OCI_COMPARTMENT (default
+kampodine). Types are pinned to A | AAAA | CNAME; ttl range 60..172800.
+
+Examples:
+  kampodine dns records
+  kampodine dns records --zone kampodine.example.com
+  kampodine dns add --name app --type A --value 203.0.113.10 --zone kampodine.example.com
+  kampodine dns add --name www --type CNAME --value app.example.com --ttl 3600
+  kampodine dns rm --name app --type A --value 203.0.113.10
+EOF
+  exit "$code"
+}
+
+# --- pure validators (no side effects, run before any provider call) ----------
+is_ipv4() {
+  local ip="$1" i octet
+  [[ "$ip" =~ ^([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})$ ]] || return 1
+  for i in 1 2 3 4; do
+    octet="${BASH_REMATCH[i]}"
+    [[ $((10#$octet)) -le 255 ]] || return 1
+  done
+  return 0
+}
+
+is_ipv6() {
+  local ip="$1" colons
+  [[ "$ip" =~ ^[0-9A-Fa-f:]+$ ]] || return 1
+  [[ -n "${ip//:/}" ]] || return 1        # at least one hex digit
+  [[ "$ip" != *":::"* ]] || return 1      # no triple colons
+  colons="${ip//[0-9A-Fa-f]/}"
+  [[ ${#colons} -le 7 ]] || return 1      # at most 8 groups
+  [[ "${ip/::/}" != *"::"* ]] || return 1 # at most one "::"
+  return 0
+}
+
+is_hostname() {
+  [[ "$1" =~ ^([A-Za-z0-9_]([A-Za-z0-9_-]{0,61}[A-Za-z0-9_])?\.)+[A-Za-z0-9_]([A-Za-z0-9_-]{0,61}[A-Za-z0-9_])?\.?$ ]]
+}
+
+# --- dispatch -----------------------------------------------------------------
+CMD="${1:-}"
+case "$CMD" in
+  records|add|rm) shift ;;
+  -h|--help|help) usage 0 ;;
+  "") usage 2 ;;
+  *)
+    printf 'kampodine dns: unknown subcommand: %s\n\n' "$CMD" >&2
+    usage 2
+    ;;
+esac
+
+ZONE_ARG=""
+NAME=""
+RTYPE=""
+VALUE=""
+TTL="300"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --zone) ZONE_ARG="$2"; shift 2 ;;
+    --name) NAME="$2"; shift 2 ;;
+    --type) RTYPE="$2"; shift 2 ;;
+    --value) VALUE="$2"; shift 2 ;;
+    --ttl) TTL="$2"; shift 2 ;;
+    --instance-principal) AUTH_ARGS=(--auth instance_principal); shift ;;
+    -h|--help) usage 0 ;;
+    *) die "unknown argument: $1 (--help)" ;;
+  esac
+done
+
+need_provider() {
+  command -v oci >/dev/null 2>&1 \
+    || die "oci CLI not found — brew install oci-cli (https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm), then: oci setup config"
+  command -v jq >/dev/null 2>&1 \
+    || die "jq not found — brew install jq (dns.sh uses it for RRSet surgery)"
+  [[ -n "${OCI_COMPARTMENT:-}" ]] \
+    || die "set OCI_COMPARTMENT=<compartment name or ocid> — no default: compartments are account-specific"
+}
+
+compartment_ocid() {
+  local ocid
+  ocid="$(oci iam compartment list --all --profile "$PROFILE" ${AUTH_ARGS[@]+"${AUTH_ARGS[@]}"} \
+    --query "data[?name=='$COMPARTMENT_NAME'].id | [0]" --raw-output 2>/dev/null || true)"
+  [[ "$ocid" == ocid1.compartment* ]] || die "compartment '$COMPARTMENT_NAME' not found (profile $PROFILE)"
+  printf '%s' "$ocid"
+}
+
+# resolve_zone -> ZONE_NAME + ZONE_ID (explicit --zone wins; otherwise the
+# compartment must hold exactly one zone — never guess between several).
+resolve_zone() {
+  local zj zl count
+  COMPARTMENT_OCID="$(compartment_ocid)"
+  if [[ -n "$ZONE_ARG" ]]; then
+    if [[ "$ZONE_ARG" == ocid1.dns-zone* ]]; then
+      zj="$(oci dns zone get --zone-name-or-id "$ZONE_ARG" -c "$COMPARTMENT_OCID" --profile "$PROFILE" ${AUTH_ARGS[@]+"${AUTH_ARGS[@]}"} 2>/dev/null)" \
+        || die "zone not found: $ZONE_ARG"
+      ZONE_NAME="$(jq -r '.data.name' <<<"$zj")"
+      ZONE_ID="$ZONE_ARG"
+    else
+      ZONE_NAME="${ZONE_ARG%.}"
+      ZONE_ID="$ZONE_ARG"
+    fi
+    return 0
+  fi
+  zl="$(oci dns zone list --all -c "$COMPARTMENT_OCID" --profile "$PROFILE" ${AUTH_ARGS[@]+"${AUTH_ARGS[@]}"} 2>/dev/null)" \
+    || die "zone list failed (profile $PROFILE, compartment $COMPARTMENT_NAME)"
+  count="$(jq '.data.items | length' <<<"$zl")"
+  if [[ "$count" -eq 0 ]]; then
+    die "no DNS zones in compartment '$COMPARTMENT_NAME' — create one in the OCI console first (or pass --zone <id-or-name>)"
+  fi
+  if [[ "$count" -gt 1 ]]; then
+    printf '\033[1;31m[dns] FAIL:\033[0m multiple zones in %s — pass --zone with one of:\n' "$COMPARTMENT_NAME" >&2
+    jq -r '.data.items[].name' <<<"$zl" | sed 's/^/  /' >&2
+    exit 1
+  fi
+  ZONE_NAME="$(jq -r '.data.items[0].name' <<<"$zl")"
+  ZONE_ID="$(jq -r '.data.items[0].id' <<<"$zl")"
+}
+
+# turn --name into the record domain: plain label -> label.zone; fqdn must
+# live inside the zone (never write into someone else's zone by accident).
+validate_name_shape() {
+  [[ -n "$NAME" ]] || die "--name is required (--help)"
+  [[ "$NAME" =~ ^[A-Za-z0-9_-]{1,63}$ ]] && return 0
+  is_hostname "$NAME" || die "invalid --name '$NAME' — use a DNS label (app) or an fqdn inside the zone (app.example.com)"
+}
+
+resolve_domain() {
+  if [[ "$NAME" =~ ^[A-Za-z0-9_-]{1,63}$ ]]; then
+    DOMAIN="$NAME.$ZONE_NAME"
+    return 0
+  fi
+  DOMAIN="${NAME%.}"
+  [[ "$DOMAIN" == *".$ZONE_NAME" || "$DOMAIN" == "$ZONE_NAME" ]] \
+    || die "--name '$NAME' is outside zone '$ZONE_NAME' — pass --zone <that-zone> explicitly if intended"
+}
+
+validate_type() {
+  case "$RTYPE" in
+    A|AAAA|CNAME) return 0 ;;
+    "") die "--type is required: A, AAAA, or CNAME (--help)" ;;
+    *) die "--type must be one of: A, AAAA, CNAME (got: $RTYPE)" ;;
+  esac
+}
+
+validate_value() {
+  [[ -n "$VALUE" ]] || die "--value is required (--help)"
+  case "$VALUE" in *[\"\\]*) die "invalid --value — quotes/backslashes are never valid in a record value" ;; esac
+  case "$RTYPE" in
+    A) is_ipv4 "$VALUE" || die "invalid --value '$VALUE' for A — need dotted-quad IPv4 (203.0.113.10)" ;;
+    AAAA) is_ipv6 "$VALUE" || die "invalid --value '$VALUE' for AAAA — need an IPv6 literal (fd00::1)" ;;
+    CNAME) is_hostname "$VALUE" || die "invalid --value '$VALUE' for CNAME — need a hostname (app.example.com)" ;;
+  esac
+}
+
+validate_ttl() {
+  [[ "$TTL" =~ ^[0-9]+$ ]] || die "invalid --ttl '$TTL' — seconds (60..172800)"
+  [[ "$TTL" -ge 60 && "$TTL" -le 172800 ]] || die "invalid --ttl $TTL — OCI allows 60..172800 seconds"
+}
+
+# fetch_rrset -> ITEMS (canonical JSON array of {domain,rtype,ttl,rdata};
+# a missing RRSet reads as empty — first add must not 404).
+fetch_rrset() {
+  local rj
+  rj="$(oci dns record rrset get -c "$COMPARTMENT_OCID" --zone-name-or-id "$ZONE_ID" --domain "$DOMAIN" --rtype "$RTYPE" --profile "$PROFILE" ${AUTH_ARGS[@]+"${AUTH_ARGS[@]}"} 2>/dev/null || true)"
+  if [[ -n "$rj" ]]; then
+    ITEMS="$(jq -c '.data.items | map({domain, rtype, ttl, rdata})' <<<"$rj")" || ITEMS="[]"
+  else
+    ITEMS="[]"
+  fi
+}
+
+case "$CMD" in
+  records)
+    need_provider
+    resolve_zone
+    say "DNS records — zone $ZONE_NAME ($ZONE_ID), profile $PROFILE:"
+    oci dns record zone get -c "$COMPARTMENT_OCID" --zone-name-or-id "$ZONE_ID" --profile "$PROFILE" ${AUTH_ARGS[@]+"${AUTH_ARGS[@]}"} --all \
+      | jq -r '.data.items[] | [.domain, .rtype, (.ttl|tostring), .rdata] | @tsv'
+    ;;
+
+  add)
+    [[ -n "$NAME" ]] || die "--name is required (--help)"
+    validate_type
+    validate_value
+    validate_ttl
+    validate_name_shape
+    need_provider
+    resolve_zone
+    resolve_domain
+    fetch_rrset
+    norm_value="${VALUE%.}"
+    present="$(jq -r --arg v "$norm_value" 'any(.[]; (.rdata | sub("\\.$"; "")) == $v)' <<<"$ITEMS")"
+    if [[ "$present" == "true" ]]; then
+      say "already present: $DOMAIN $RTYPE $VALUE — nothing to do"
+      exit 0
+    fi
+    new_items="$(jq -c --arg d "$DOMAIN" --arg t "$RTYPE" --arg v "$VALUE" --argjson ttl "$TTL" \
+      '. + [{domain: $d, rtype: $t, ttl: $ttl, rdata: $v}]' <<<"$ITEMS")"
+    # NOTE: --profile stays ON the first line (script-gates static scan reads it there)
+    oci dns record rrset update --profile "$PROFILE" -c "$COMPARTMENT_OCID" --zone-name-or-id "$ZONE_ID" \
+      --domain "$DOMAIN" --rtype "$RTYPE" --items "$new_items" --force ${AUTH_ARGS[@]+"${AUTH_ARGS[@]}"} >/dev/null \
+      || die "RRSet update failed for $DOMAIN $RTYPE (zone $ZONE_NAME)"
+    say "added: $DOMAIN $RTYPE $VALUE (ttl $TTL)"
+    ;;
+
+  rm)
+    [[ -n "$NAME" ]] || die "--name is required (--help)"
+    validate_type
+    validate_value
+    validate_name_shape
+    need_provider
+    resolve_zone
+    resolve_domain
+    fetch_rrset
+    [[ "$ITEMS" == "[]" ]] && die "no matching record: $DOMAIN $RTYPE $VALUE (see: kampodine dns records)"
+    norm_value="${VALUE%.}"
+    remaining="$(jq -c --arg v "$norm_value" '[.[] | select((.rdata | sub("\\.$"; "")) != $v)]' <<<"$ITEMS")"
+    [[ "$(jq 'length' <<<"$remaining")" -eq "$(jq 'length' <<<"$ITEMS")" ]] \
+      && die "no matching record: $DOMAIN $RTYPE $VALUE (see: kampodine dns records)"
+    # an emptied RRSet is legal: --items '[]' removes it entirely
+    # NOTE: --profile stays ON the first line (script-gates static scan reads it there)
+    oci dns record rrset update --profile "$PROFILE" -c "$COMPARTMENT_OCID" --zone-name-or-id "$ZONE_ID" \
+      --domain "$DOMAIN" --rtype "$RTYPE" --items "$remaining" --force ${AUTH_ARGS[@]+"${AUTH_ARGS[@]}"} >/dev/null \
+      || die "RRSet update failed for $DOMAIN $RTYPE (zone $ZONE_NAME)"
+    say "removed: $DOMAIN $RTYPE $VALUE"
+    ;;
+esac

package/scripts/env.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# env.sh — manage the remote app env file (/etc/kampodine/env, 0600 root).
+#
+# SECRETS NEVER PRINT. `env list`, `env push`, and the `env pull` summaries
+# surface FINGERPRINTS ONLY: KEY + value length + first 2 characters. Raw
+# values move exactly twice — push uploads the local file over ssh stdin,
+# pull streams the remote file to stdout (payload) or --out (0600). Nothing
+# secret ever lands in terminal output, logs, or process args.
+#
+# Host/key resolution is IDENTICAL to deploy.sh:
+#   --host root@<ip> | KAMPODINE_HOST | ~/.ssh/config Host alias
+#   --ssh-key <path> | KAMPODINE_SSH_KEY |
+#   ssh-agent (the POSIX default; per-host IdentityFile belongs in ssh config)
+#
+# Usage:
+#   kampodine env list [--host <user@ip>]              # KEY + fingerprint table (NEVER values)
+#   kampodine env push --file <local-env-file> [...]   # upload: 0600 temp + atomic mv + restart hint
+#   kampodine env pull [--out <file>] [...]            # raw payload to stdout/--out (0600); masked summary follows it
+#   kampodine env fingerprint [--file <f>]             # preview the masking for a LOCAL file / stdin (never values)
+#
+# push sends the file VERBATIM (what you push is what lands). deploy's env
+# step additionally drops rc-script-owned CLEAR keys — keep those out of the
+# file you push unless you mean to own them here.
+set -euo pipefail
+
+ENV_FILE_REMOTE="${KAMPODINE_ENV_REMOTE:-/etc/kampodine/env}"
+ENV_TMP_BASE="$(dirname "$ENV_FILE_REMOTE")"
+
+KAMPODINE_HOST="${KAMPODINE_HOST:-}"
+# SSH key resolution — same ladder as deploy.sh:
+#   1. --ssh-key flag           (explicit, per-invocation)
+#   2. KAMPODINE_SSH_KEY env    (project-level: direnv / .envrc / export)
+#   3. KAMPODINE_SSH_KEY env     (legacy alias, kept for existing setups)
+#   4. empty → ssh-agent and/or the operator's ~/.ssh/config Host block
+if [ -n "${KAMPODINE_SSH_KEY:-}" ]; then
+    SSH_KEY="$KAMPODINE_SSH_KEY"
+else
+    SSH_KEY=""
+fi
+
+say() { printf '\033[1;36m[env]\033[0m %s\n' "$*"; }
+die() { printf '\033[1;31m[env] FAIL:\033[0m %s\n' "$*" >&2; exit 1; }
+usage() {
+  printf 'Usage:\n'
+  grep '^#   kampodine env' "$0" | sed 's/^#   //'
+  cat <<'EOF'
+
+Fingerprints NEVER leak values: every line is KEY + value length + first 2 chars.
+Raw values move only in push's upload stream and pull's stdout/--out payload.
+Host/key resolution matches deploy.sh: --host | KAMPODINE_HOST; --ssh-key |
+KAMPODINE_SSH_KEY | ssh-agent / ~/.ssh/config.
+
+Examples:
+  kampodine env list --host root@203.0.113.10
+  kampodine env push --file ./ops/env.production --host root@203.0.113.10
+  kampodine env pull --out ./env.snapshot --host root@203.0.113.10   # written 0600
+  kampodine env pull --host root@203.0.113.10 | wc -l                # raw payload on stdout, summary on stderr
+  kampodine env fingerprint --file ./.env.local                      # preview masking, values never leave stdin
+EOF
+  exit 0
+}
+
+SUB="${1:-}"
+[[ -n "$SUB" ]] || usage
+case "$SUB" in
+  list|push|pull|fingerprint) shift ;;
+  -h|--help|help) usage ;;
+  *) die "unknown env subcommand: $SUB (--help)" ;;
+esac
+
+FILE=""
+OUT=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --host) KAMPODINE_HOST="$2"; shift 2 ;;
+    --ssh-key) SSH_KEY="$2"; shift 2 ;;
+    --file) FILE="$2"; shift 2 ;;
+    --out) OUT="$2"; shift 2 ;;
+    -h|--help) usage ;;
+    *) die "unknown argument: $1 (--help)" ;;
+  esac
+done
+
+SSH_ARGS=(-o ConnectTimeout=10 -o BatchMode=yes)
+[[ -n "$SSH_KEY" ]] && SSH_ARGS+=(-i "$SSH_KEY")
+# $1 is a composed remote command — client-side expansion is the design.
+# shellcheck disable=SC2029
+vm() { ssh "${SSH_ARGS[@]}" "$KAMPODINE_HOST" "$1"; }
+
+# --- macOS ssh-agent quirk (first run from a fresh machine) -------------------
+if [[ "$(uname -s)" == "Darwin" ]]; then
+  SSH_AUTH_SOCK="$(launchctl getenv SSH_AUTH_SOCK 2>/dev/null || true)"
+  export SSH_AUTH_SOCK
+fi
+
+require_host() {
+  [[ -n "$KAMPODINE_HOST" ]] || die "target required: --host root@<ip> or KAMPODINE_HOST=root@<ip> (resolution matches deploy.sh)"
+}
+
+# env_fp_lines — env content on stdin -> fingerprint table on stdout.
+# THE masking contract lives here: KEY + value length + first 2 chars.
+# $value is never printed; only ${value:0:2} and its length are.
+env_fp_lines() {
+  local line key value len
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    case "$line" in ''|'#'*) continue ;; esac
+    [[ "$line" == *=* ]] || continue
+    key="${line%%=*}"
+    [[ "$key" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
+    value="${line#*=}"
+    # one pair of matching surrounding quotes is formatting, not content
+    # (podman --env-file does not unquote — the deploy pipeline strips them)
+    if [[ ${#value} -ge 2 ]]; then
+      case "$value" in
+        \"*\") value="${value#\"}"; value="${value%\"}" ;;
+        \'*\') value="${value#\'}"; value="${value%\'}" ;;
+      esac
+    fi
+    len="${#value}"
+    if [[ "$len" -eq 0 ]]; then
+      printf '%-32s len=0      (empty)\n' "$key"
+    else
+      printf '%-32s len=%-7s %s…\n' "$key" "$len" "${value:0:2}"
+    fi
+  done
+}
+
+fetch_remote_env() {
+  vm "cat $ENV_FILE_REMOTE" || die "cannot read $ENV_FILE_REMOTE on $KAMPODINE_HOST (no env file yet? run: kampodine env push --file <env>, or kampodine deploy)"
+}
+
+case "$SUB" in
+  list)
+    require_host
+    raw="$(fetch_remote_env)"
+    env_fp_lines <<<"$raw"
+    ;;
+
+  push)
+    [[ -n "$FILE" ]] || die "push requires --file <local-env-file> (--help)"
+    [[ -f "$FILE" ]] || die "no such file: $FILE"
+    require_host
+    count="$(grep -cE '^[A-Za-z_][A-Za-z0-9_]*=' "$FILE" || true)"
+    [[ "${count:-0}" -gt 0 ]] || die "no KEY=VALUE lines in $FILE — nothing to push"
+    say "pushing $FILE -> $KAMPODINE_HOST:$ENV_FILE_REMOTE (fingerprint summary below; values are NEVER printed)"
+    env_fp_lines < "$FILE"
+    tmp_remote="$ENV_TMP_BASE/env.tmp.$$"
+    # 0600 FROM CREATION: umask 077 + ssh stdin pipe — the temp is never
+    # world-readable, not even for an instant; `mv` within the same
+    # directory is atomic (busybox-safe: umask/cat/mv/chmod only).
+    vm "umask 077; cat > $tmp_remote" < "$FILE" || die "upload failed"
+    vm "chmod 600 $tmp_remote && mv -f $tmp_remote $ENV_FILE_REMOTE" \
+      || die "atomic install failed (remote temp left at: $tmp_remote)"
+    say "installed $ENV_FILE_REMOTE (0600) on $KAMPODINE_HOST"
+    say "restart to apply: ssh $KAMPODINE_HOST 'rc-service kampodine-api restart'   # or: kampodine deploy"
+    ;;
+
+  pull)
+    require_host
+    raw="$(fetch_remote_env)"
+    if [[ -n "$OUT" ]]; then
+      ( umask 077; printf '%s\n' "$raw" > "$OUT" ) || die "cannot write $OUT"
+      chmod 600 "$OUT"
+      say "wrote $OUT (0600) — fingerprint summary below (payload went to the file, stdout is free):"
+      env_fp_lines <<<"$raw"
+    else
+      # stdout IS the payload (pipe into whatever needs the values);
+      # the human-readable summary goes to stderr, masked.
+      printf '%s\n' "$raw"
+      say "fingerprint summary for $ENV_FILE_REMOTE on $KAMPODINE_HOST (payload above on stdout):" >&2
+      env_fp_lines <<<"$raw" >&2
+    fi
+    ;;
+
+  fingerprint)
+    if [[ -n "$FILE" ]]; then
+      [[ -f "$FILE" ]] || die "no such file: $FILE"
+      env_fp_lines < "$FILE"
+    else
+      env_fp_lines
+    fi
+    ;;
+esac