feat(skills): basic_auth_setup helper for nginx + htpasswd demo gate #129

Closed

mik-tf wants to merge 1 commit from development_mik_basic_auth into development

mik-tf commented

2026-04-25 16:48:36 +00:00

Owner

Closes deploy-side of home#182 (basic mode). Codifies §12.1 of DEPLOYMENT_NU_HERO_OS.md so the manual apt install nginx-light apache2-utils + htpasswd + sites-available block becomes one basic_auth_setup call.

Module

New: tools/modules/installers/auth.nu
Re-exported from: tools/modules/installers/mod.nu

basic_auth_setup [
    --user <str>          # env HERO_AUTH_BASIC_USER, default "admin"
    --pass <str>          # env HERO_AUTH_BASIC_PASS — required
    --listen-addr <ip>    # env HERO_AUTH_LISTEN_ADDR, default 10.1.2.2
    --listen-port <int>   # env HERO_AUTH_LISTEN_PORT, default 9988
    --upstream-addr <ip>  # env HERO_AUTH_UPSTREAM_ADDR, default 10.1.2.2
    --upstream-port <int> # env HERO_AUTH_UPSTREAM_PORT, default 9990
    --server-name <str>   # env HERO_PUBLIC_HOSTNAME, default "_"
]

Behaviour

Generates the same nginx config §12.1 documents:

listen on $listen_addr:$listen_port
auth_basic gate everywhere except ^/hero_*/rpc(/|$) (programmatic JSON-RPC bypasses auth so already-authenticated WASM islands and iframes can call back without re-auth)
proxy_pass to http://$upstream_addr:$upstream_port (where hero_router is bound when HERO_ROUTER_ADDRESS / HERO_ROUTER_UI_PORT are set in env.sh — see service_router env wiring on PR #127)
client_max_body_size 100M, WebSocket upgrade map, sane proxy timeouts

Tries systemctl reload nginx first; falls back to pkill -HUP nginx or nohup nginx for TF Grid VMs (no systemd).

Quick path with auth

# In env.sh:
export HERO_AUTH_BASIC_PASS="$(openssl rand -hex 16)"
export HERO_PUBLIC_HOSTNAME="herodemo.gent01.grid.tf"
export HERO_ROUTER_ADDRESS=10.1.2.2
export HERO_ROUTER_UI_PORT=9990

# After service_complete runs:
sudo nu -c 'use ~/code/hero_skills/tools/modules/installers *; basic_auth_setup'

Validation

Parses under nu -c "use tools/modules/installers *". Runtime test requires nginx + a host where 9988 is bindable.

Tracker

home#185.

Signed-off-by: mik-tf

Closes deploy-side of [home#182](https://forge.ourworld.tf/lhumina_code/home/issues/182) (basic mode). Codifies §12.1 of [DEPLOYMENT_NU_HERO_OS.md](https://forge.ourworld.tf/lhumina_code/hero_demo/src/branch/development/docs/ops/DEPLOYMENT_NU_HERO_OS.md) so the manual `apt install nginx-light apache2-utils` + `htpasswd` + sites-available block becomes one `basic_auth_setup` call. ## Module New: `tools/modules/installers/auth.nu` Re-exported from: `tools/modules/installers/mod.nu` ```nu basic_auth_setup [ --user <str> # env HERO_AUTH_BASIC_USER, default "admin" --pass <str> # env HERO_AUTH_BASIC_PASS — required --listen-addr <ip> # env HERO_AUTH_LISTEN_ADDR, default 10.1.2.2 --listen-port <int> # env HERO_AUTH_LISTEN_PORT, default 9988 --upstream-addr <ip> # env HERO_AUTH_UPSTREAM_ADDR, default 10.1.2.2 --upstream-port <int> # env HERO_AUTH_UPSTREAM_PORT, default 9990 --server-name <str> # env HERO_PUBLIC_HOSTNAME, default "_" ] ``` ## Behaviour Generates the same nginx config §12.1 documents: - listen on `$listen_addr:$listen_port` - `auth_basic` gate everywhere **except** `^/hero_*/rpc(/|$)` (programmatic JSON-RPC bypasses auth so already-authenticated WASM islands and iframes can call back without re-auth) - `proxy_pass` to `http://$upstream_addr:$upstream_port` (where hero_router is bound when `HERO_ROUTER_ADDRESS` / `HERO_ROUTER_UI_PORT` are set in `env.sh` — see service_router env wiring on [PR #127](https://forge.ourworld.tf/lhumina_code/hero_skills/pulls/127)) - `client_max_body_size 100M`, WebSocket upgrade map, sane proxy timeouts Tries `systemctl reload nginx` first; falls back to `pkill -HUP nginx` or `nohup nginx` for TF Grid VMs (no systemd). ## Quick path with auth ```bash # In env.sh: export HERO_AUTH_BASIC_PASS="$(openssl rand -hex 16)" export HERO_PUBLIC_HOSTNAME="herodemo.gent01.grid.tf" export HERO_ROUTER_ADDRESS=10.1.2.2 export HERO_ROUTER_UI_PORT=9990 # After service_complete runs: sudo nu -c 'use ~/code/hero_skills/tools/modules/installers *; basic_auth_setup' ``` ## Validation Parses under `nu -c "use tools/modules/installers *"`. Runtime test requires nginx + a host where 9988 is bindable. ## Tracker [home#185](https://forge.ourworld.tf/lhumina_code/home/issues/185). Signed-off-by: mik-tf

mik-tf added 1 commit

2026-04-25 16:48:36 +00:00

feat(skills): basic_auth_setup helper for nginx + htpasswd demo gate 864029747b

Closes deploy-side of lhumina_code/home#182
(basic mode).  Codifies §12.1 of DEPLOYMENT_NU_HERO_OS.md so the manual
nginx-light + apache2-utils install + htpasswd + sites-available config
write becomes a single nu invocation.

Module: tools/modules/installers/auth.nu
Public API: tools/modules/installers/mod.nu re-exports basic_auth_setup.

basic_auth_setup [
    --user <str>          (env HERO_AUTH_BASIC_USER, default "admin")
    --pass <str>          (env HERO_AUTH_BASIC_PASS — required)
    --listen-addr <ip>    (env HERO_AUTH_LISTEN_ADDR, default 10.1.2.2)
    --listen-port <int>   (env HERO_AUTH_LISTEN_PORT, default 9988)
    --upstream-addr <ip>  (env HERO_AUTH_UPSTREAM_ADDR, default 10.1.2.2)
    --upstream-port <int> (env HERO_AUTH_UPSTREAM_PORT, default 9990)
    --server-name <str>   (env HERO_PUBLIC_HOSTNAME, default wildcard)
]

Generates the same nginx config the runbook §12.1 documents:
- listen on $listen_addr:$listen_port
- auth_basic gate everywhere except `^/hero_*/rpc(/|$)` (programmatic
  JSON-RPC bypasses auth so already-authenticated WASM islands and
  iframes can call back without re-auth)
- proxy_pass to http://$upstream_addr:$upstream_port (where hero_router
  is bound when HERO_ROUTER_ADDRESS / HERO_ROUTER_UI_PORT are set in
  env.sh — see service_router env wiring on
  #127)

Tries `systemctl reload nginx` first; falls back to `pkill -HUP nginx`
or `nohup nginx` for TF Grid VMs (no systemd).

Validation: parses under `nu -c "use tools/modules/installers *"`.
Runtime test requires nginx + a host where 9988 is bindable.

Tracker: lhumina_code/home#185

Signed-off-by: mik-tf