infra: htpasswd write mode 600 → 644 (spec-v6 D16 follow-up) — nginx worker (uid 101) opens auth_basic_user_file per request; 600 answered 13: Permission denied on /api/content/

This commit is contained in:
dong.nguyen committed 2026-10-28 12:15:03 +07:00
1 parent a5ff55bacf
commit eee662a62d
4 files changed
+23 -10

No files matched your search

+6 -3
View File
@@ -97,8 +97,11 @@ jobs:
# bcrypt hash is riddled with `$` and appleboy's `envs:` mechanism exports # bcrypt hash is riddled with `$` and appleboy's `envs:` mechanism exports
# values unquoted, so the remote shell would expand `$2y…` away. Written # values unquoted, so the remote shell would expand `$2y…` away. Written
# BEFORE the test step: nginx -t opens auth_basic_user_file, so its mount # BEFORE the test step: nginx -t opens auth_basic_user_file, so its mount
# needs a real file. chmod 600 keeps the credential readable only by the # needs a real file. chmod 644, NOT 600: nginx verifies Basic auth in the
# stack owner. Needs the HTPASSWD_CONTENT secret on Gitea too. # worker process (the image's nginx user, uid 101) and opens
# auth_basic_user_file per request — a 600 file owned by the deploy user
# is unreadable there (13: Permission denied on /api/content/, 2026-10-28).
# Needs the HTPASSWD_CONTENT secret on Gitea too.
- name: Write deploy/htpasswd from the secret - name: Write deploy/htpasswd from the secret
uses: appleboy/ssh-action@v1.2.0 uses: appleboy/ssh-action@v1.2.0
with: with:
@@ -115,7 +118,7 @@ jobs:
fi fi
mkdir -p deploy mkdir -p deploy
printf '%s\n' "$HTPASSWD" > deploy/htpasswd printf '%s\n' "$HTPASSWD" > deploy/htpasswd
chmod 600 deploy/htpasswd chmod 644 deploy/htpasswd
# Test-before-touch (D3): the throwaway container runs the same entrypoint # Test-before-touch (D3): the throwaway container runs the same entrypoint
# render pipeline as production, with placeholder values — nginx -t checks # render pipeline as production, with placeholder values — nginx -t checks
+10 -2
View File
@@ -99,7 +99,15 @@ jobs:
# away; the htpasswd character set (user name + bcrypt base64) contains no # away; the htpasswd character set (user name + bcrypt base64) contains no
# single quote, so this quoting is exact. Written BEFORE the test step: # single quote, so this quoting is exact. Written BEFORE the test step:
# nginx -t opens auth_basic_user_file, so its mount needs a real file. # nginx -t opens auth_basic_user_file, so its mount needs a real file.
# chmod 600 keeps the credential readable only by the stack owner. # chmod 644, NOT 600: nginx verifies Basic auth in the worker process —
# the image's unprivileged nginx user (uid 101) — and opens
# auth_basic_user_file per request, so the file must be readable by a uid
# other than the deploy user's. A 600 file made the live site answer
# open() … 13: Permission denied on /api/content/ (2026-10-28): nginx -t
# and the wget probe run as root, which ignores DAC permissions, and / has
# no auth — only a real Basic-auth request reads the file as uid 101. The
# file holds a bcrypt hash only; 644 is the mode production ran with while
# it was rsynced from the repository.
- name: Write deploy/htpasswd from the secret - name: Write deploy/htpasswd from the secret
uses: appleboy/ssh-action@v1.2.0 uses: appleboy/ssh-action@v1.2.0
with: with:
@@ -116,7 +124,7 @@ jobs:
fi fi
mkdir -p deploy mkdir -p deploy
printf '%s\n' "$HTPASSWD" > deploy/htpasswd printf '%s\n' "$HTPASSWD" > deploy/htpasswd
chmod 600 deploy/htpasswd chmod 644 deploy/htpasswd
# Test-before-touch (D3): the throwaway container runs the same entrypoint # Test-before-touch (D3): the throwaway container runs the same entrypoint
# render pipeline as production, with placeholder values — nginx -t checks # render pipeline as production, with placeholder values — nginx -t checks
+1 -1
View File
@@ -148,7 +148,7 @@ Then create GitHub Actions **secrets** — Settings → Secrets and variables
| `DEPLOY_SSH_PORT` | SSH port | | `DEPLOY_SSH_PORT` | SSH port |
| `DEPLOY_USER` | `gitea-deployer` | | `DEPLOY_USER` | `gitea-deployer` |
| `DEPLOY_SSH_PRIVATE_KEY` | the private key content | | `DEPLOY_SSH_PRIVATE_KEY` | the private key content |
| `HTPASSWD_CONTENT` | the one htpasswd line — output of `htpasswd -nbB <user> '<pass>'` (user + bcrypt hash). The infra job writes it to `${STACK_DIR}/deploy/htpasswd` (chmod 600); the credential never appears in the repository (spec-v6 D16) | | `HTPASSWD_CONTENT` | the one htpasswd line — output of `htpasswd -nbB <user> '<pass>'` (user + bcrypt hash). The infra job writes it to `${STACK_DIR}/deploy/htpasswd` (chmod 644 — the nginx worker, uid 101, opens the file per request; see spec-v6 D16 §7.1 follow-up); the credential never appears in the repository |
**3. VPS stack config** — in the stack directory `/opt/stacks/dong-site/`, create `secrets/site_config` (chmod 600, exactly the two `KEY=value` lines shown in step 5 above). The token should be a dedicated GitHub **fine-grained PAT** (`site-contents-write`: this repository only, `Contents: Read and write`, with an expiry). The pipeline never rsyncs `secrets/`, so it can never touch this file; it never appears in `docker inspect` or the Dockge env tab. **3. VPS stack config** — in the stack directory `/opt/stacks/dong-site/`, create `secrets/site_config` (chmod 600, exactly the two `KEY=value` lines shown in step 5 above). The token should be a dedicated GitHub **fine-grained PAT** (`site-contents-write`: this repository only, `Contents: Read and write`, with an expiry). The pipeline never rsyncs `secrets/`, so it can never touch this file; it never appears in `docker inspect` or the Dockge env tab.
@@ -1,7 +1,7 @@
# Spec v6 — GitHub Actions # Spec v6 — GitHub Actions
> **Parent:** `specs/v4/spec-v4-deploy-infra.md` (the pipeline design this one keeps), `specs/v4/spec-v4-live-edit.md` (the write path this one re-targets) > **Parent:** `specs/v4/spec-v4-deploy-infra.md` (the pipeline design this one keeps), `specs/v4/spec-v4-live-edit.md` (the write path this one re-targets)
> **Status:** rev.1 — repo side implemented 2026-10-26 (§7), automated checks pass (§8); the owner-side setup and the first verified run are open (§6). rev.2 2026-10-28 — D16: the Basic-auth file leaves the repository (§7.1); repo side implemented, owner-side secret creation open (§6). > **Status:** rev.1 — repo side implemented 2026-10-26 (§7), automated checks pass (§8); the owner-side setup and the first verified run are open (§6). rev.2 2026-10-28 — D16: the Basic-auth file leaves the repository (§7.1); repo side implemented, owner-side secret creation open (§6). rev.2 follow-up 2026-10-28 — the write step's mode corrected 600 → 644 after the first dispatch made the worker-side read visible (§7.1).
> **Supersedes:** the CI-host legs of `spec-v4-deploy-infra.md` — the `vars.` env surface (§3 "Env surface"), D5's "not added to Gitea Actions secrets", D14's Gitea-only host claim — and the Contents-API status codes recorded in `spec-v4-live-edit.md` §6.1. Everything else in those specs (D1–D4, D6–D9, D11–D13, the token-safety rules, the Dockge-safety argument) stands unchanged. > **Supersedes:** the CI-host legs of `spec-v4-deploy-infra.md` — the `vars.` env surface (§3 "Env surface"), D5's "not added to Gitea Actions secrets", D14's Gitea-only host claim — and the Contents-API status codes recorded in `spec-v4-live-edit.md` §6.1. Everything else in those specs (D1–D4, D6–D9, D11–D13, the token-safety rules, the Dockge-safety argument) stands unchanged.
--- ---
@@ -30,7 +30,7 @@ What does change is one thing the pipeline was never separate from: the reposito
| D8 | GitHub-hosted runners, **public** repository. | GitHub Actions usage is free for public repositories on standard runners and free for self-hosted runners; a private repository would bill minutes against a monthly quota for a pipeline that installs pnpm twice and renders two PDFs. Accepted consequence: the content JSON and the commit history are public. | | D8 | GitHub-hosted runners, **public** repository. | GitHub Actions usage is free for public repositories on standard runners and free for self-hosted runners; a private repository would bill minutes against a monthly quota for a pipeline that installs pnpm twice and renders two PDFs. Accepted consequence: the content JSON and the commit history are public. |
| D9 | `.gitea/workflows/` is kept until the first GitHub run is verified, then deleted. | Owner's call: see the pipelines run green on GitHub before cutting the old ones. This is a scheduled deletion recorded as an open item (§8), not a compatibility shim — nothing reads them once GitHub is the primary. | | D9 | `.gitea/workflows/` is kept until the first GitHub run is verified, then deleted. | Owner's call: see the pipelines run green on GitHub before cutting the old ones. This is a scheduled deletion recorded as an open item (§8), not a compatibility shim — nothing reads them once GitHub is the primary. |
| D15 | The two server-side layout values the workflows hard-coded — the stack directory (5 call sites) and the service/container name `dong-site` (4 call sites) — become the **repository variables** `STACK_DIR` and `CONTAINER_NAME`; the job that uses each refuses a bad value in its first step. | Both describe the server's deployment layout, not repository content — the same class of value as `SITE_URL`: public, therefore a variable and not a secret. As literals they made a stack rename a multi-file YAML edit plus a docs sweep, and a typo would have rsynced `dist/` into the wrong directory or probed the wrong container. `CONTAINER_NAME` is checked against `compose.yaml` in the same step, because that one string is used twice over — as a compose service argument and as the `docker exec` / `docker logs` target — while the file declaring both lives in this repository. Guarding it first means a bad value fails the way the site-identity check fails: at once, naming the variable and where to set it. Recorded sequence: the owner asked for the path first and the name in the same session, so the name moved too rather than staying a literal. | | D15 | The two server-side layout values the workflows hard-coded — the stack directory (5 call sites) and the service/container name `dong-site` (4 call sites) — become the **repository variables** `STACK_DIR` and `CONTAINER_NAME`; the job that uses each refuses a bad value in its first step. | Both describe the server's deployment layout, not repository content — the same class of value as `SITE_URL`: public, therefore a variable and not a secret. As literals they made a stack rename a multi-file YAML edit plus a docs sweep, and a typo would have rsynced `dist/` into the wrong directory or probed the wrong container. `CONTAINER_NAME` is checked against `compose.yaml` in the same step, because that one string is used twice over — as a compose service argument and as the `docker exec` / `docker logs` target — while the file declaring both lives in this repository. Guarding it first means a bad value fails the way the site-identity check fails: at once, naming the variable and where to set it. Recorded sequence: the owner asked for the path first and the name in the same session, so the name moved too rather than staying a literal. |
| D16 | **2026-10-28 (rev.2):** the Basic-auth file leaves the repository. `deploy/htpasswd` is untracked and gitignored; `deploy-infra.yml` writes it into the stack directory (`chmod 600`) from the **repository secret** `HTPASSWD_CONTENT`, before the test step; the file's `paths:` trigger is dropped. Credential rotation is: regenerate the line (`htpasswd -nbB`), overwrite the secret, `workflow_dispatch` — no commit. | The repository is public (D8), and the htpasswd line is a user name plus a bcrypt hash — offline-bruteforceable from any clone, forever. A hash is not the plaintext, but it does not have to live in the public archive either; the file has exactly two consumers (the production container's `auth_basic_user_file` mount and the throwaway test container's mount), both reading it from the stack directory, which the job now guarantees before testing. The containment mirrors the write token's rules (§4): one home, never in the repository, never in the bundle. The value is inlined into a **single-quoted** shell literal in the ssh script: bcrypt's `$2y$…` must not reach the remote shell unquoted, and appleboy's `envs:` mechanism exports values unquoted — so `envs:` is not used; the htpasswd character set (user name + bcrypt base64) carries no single quote, which makes the quoting exact. The empty-secret case fails the step with a named error rather than writing an empty file nginx would accept. | | D16 | **2026-10-28 (rev.2):** the Basic-auth file leaves the repository. `deploy/htpasswd` is untracked and gitignored; `deploy-infra.yml` writes it into the stack directory (`chmod 644`, corrected from 600 — see the §7.1 follow-up) from the **repository secret** `HTPASSWD_CONTENT`, before the test step; the file's `paths:` trigger is dropped. Credential rotation is: regenerate the line (`htpasswd -nbB`), overwrite the secret, `workflow_dispatch` — no commit. | The repository is public (D8), and the htpasswd line is a user name plus a bcrypt hash — offline-bruteforceable from any clone, forever. A hash is not the plaintext, but it does not have to live in the public archive either; the file has exactly two consumers (the production container's `auth_basic_user_file` mount and the throwaway test container's mount), both reading it from the stack directory, which the job now guarantees before testing. The containment mirrors the write token's rules (§4): one home, never in the repository, never in the bundle. The value is inlined into a **single-quoted** shell literal in the ssh script: bcrypt's `$2y$…` must not reach the remote shell unquoted, and appleboy's `envs:` mechanism exports values unquoted — so `envs:` is not used; the htpasswd character set (user name + bcrypt base64) carries no single quote, which makes the quoting exact. The empty-secret case fails the step with a named error rather than writing an empty file nginx would accept. |
## 3. Facts verified during the review (method recorded) ## 3. Facts verified during the review (method recorded)
@@ -56,7 +56,7 @@ What does change is one thing the pipeline was never separate from: the reposito
| `STACK_DIR` | GitHub **repository variables** (`vars.`) — the absolute stack directory as the deploy user sees it, **no trailing slash** | the `deploy` job's `remote_path`, the infra job's two `remote_path`s and its three `appleboy/ssh-action` scripts; the guard step in each job | | `STACK_DIR` | GitHub **repository variables** (`vars.`) — the absolute stack directory as the deploy user sees it, **no trailing slash** | the `deploy` job's `remote_path`, the infra job's two `remote_path`s and its three `appleboy/ssh-action` scripts; the guard step in each job |
| `CONTAINER_NAME` | GitHub **repository variables** (`vars.`) — the compose service name and the container name, which `compose.yaml` declares as one and the same | the infra job's `docker compose up -d --force-recreate`, `docker exec` ×2 and `docker logs`; the guard step, which greps `compose.yaml` for both declarations | | `CONTAINER_NAME` | GitHub **repository variables** (`vars.`) — the compose service name and the container name, which `compose.yaml` declares as one and the same | the infra job's `docker compose up -d --force-recreate`, `docker exec` ×2 and `docker logs`; the guard step, which greps `compose.yaml` for both declarations |
| `DEPLOY_HOST`, `DEPLOY_SSH_PORT`, `DEPLOY_USER`, `DEPLOY_SSH_PRIVATE_KEY` | GitHub **secrets** | the rsync steps, the `appleboy/ssh-action` steps | | `DEPLOY_HOST`, `DEPLOY_SSH_PORT`, `DEPLOY_USER`, `DEPLOY_SSH_PRIVATE_KEY` | GitHub **secrets** | the rsync steps, the `appleboy/ssh-action` steps |
| `HTPASSWD_CONTENT` | GitHub **secret** (D16) — the one htpasswd line, user + bcrypt hash | the infra job's "Write deploy/htpasswd from the secret" step, which writes `${STACK_DIR}/deploy/htpasswd` (chmod 600) before the test container mounts it; the nginx container then serves it as `auth_basic_user_file`. Locally: an untracked `deploy/htpasswd` copy, needed by the compose mount | | `HTPASSWD_CONTENT` | GitHub **secret** (D16) — the one htpasswd line, user + bcrypt hash | the infra job's "Write deploy/htpasswd from the secret" step, which writes `${STACK_DIR}/deploy/htpasswd` (chmod 644 — the nginx worker, uid 101, opens `auth_basic_user_file` per request, so the file must be world-readable; 600 failed on the first dispatch, §7.1 follow-up) before the test container mounts it; the nginx container then serves it as `auth_basic_user_file`. Locally: an untracked `deploy/htpasswd` copy, needed by the compose mount |
| `CONTENT_API_TOKEN`, `CONTENT_API_BASE` | the stack's single config file `secrets/site_config` (chmod 600, server-side, never committed, never in CI) | the nginx container's envsubst template step; locally the uncommitted `.env`, read by `vite.config.ts` | | `CONTENT_API_TOKEN`, `CONTENT_API_BASE` | the stack's single config file `secrets/site_config` (chmod 600, server-side, never committed, never in CI) | the nginx container's envsubst template step; locally the uncommitted `.env`, read by `vite.config.ts` |
| `NGINX_ENVSUBST_FILTER=CONTENT_API_TOKEN\|CONTENT_API_BASE` | `compose.yaml` | the official entrypoint's template renderer (a regex over variable **names**; alternatives separated with `\|`) | | `NGINX_ENVSUBST_FILTER=CONTENT_API_TOKEN\|CONTENT_API_BASE` | `compose.yaml` | the official entrypoint's template renderer (a regex over variable **names**; alternatives separated with `\|`) |
@@ -116,7 +116,7 @@ The token's rules are unchanged from `spec-v4-deploy-infra.md` §5: single home,
|---|---| |---|---|
| `deploy/htpasswd` | `git rm --cached` — untracked, still on disk locally (the local compose mount needs it); its content moves to the `HTPASSWD_CONTENT` secret | | `deploy/htpasswd` | `git rm --cached` — untracked, still on disk locally (the local compose mount needs it); its content moves to the `HTPASSWD_CONTENT` secret |
| `.gitignore` | `+ /deploy/htpasswd`, in the deployment/runtime-config block beside `.env` and `secrets/` | | `.gitignore` | `+ /deploy/htpasswd`, in the deployment/runtime-config block beside `.env` and `secrets/` |
| `.github/workflows/deploy-infra.yml` | `paths:` drops `deploy/htpasswd`; the "Sync deploy/htpasswd" rsync step is replaced by "Write deploy/htpasswd from the secret" (appleboy/ssh-action: `mkdir -p deploy`, single-quoted secret literal → `printf` → `chmod 600`, empty secret refused with a named error), placed before the test step whose container mounts the file | | `.github/workflows/deploy-infra.yml` | `paths:` drops `deploy/htpasswd`; the "Sync deploy/htpasswd" rsync step is replaced by "Write deploy/htpasswd from the secret" (appleboy/ssh-action: `mkdir -p deploy`, single-quoted secret literal → `printf` → `chmod 644`, empty secret refused with a named error), placed before the test step whose container mounts the file |
| `.gitea/workflows/deploy-infra.yml` | same D16 change as the GitHub file | | `.gitea/workflows/deploy-infra.yml` | same D16 change as the GitHub file |
| `.gitea/workflows/deploy.yml` + `.gitea/workflows/deploy-infra.yml` | **full parity with the GitHub workflows (owner decision 2026-10-28):** `permissions: contents: read` on every job; the "Check stack directory" / "Check stack variables" guard steps added; the literals `/opt/stacks/dong-site` (9 call sites) and `dong-site` (4) replaced by `${{ vars.STACK_DIR }}` / `${{ vars.CONTAINER_NAME }}`. The only intentional differences left: the header comments naming the mirror, and the guard error text pointing at Gitea's settings path (Settings → Actions → Secrets and Variables → Variables). Owner-side consequence: Gitea must now carry `STACK_DIR`, `CONTAINER_NAME` (variables) and `HTPASSWD_CONTENT` (secret) exactly like GitHub, or the guard steps refuse the run — that was previously avoided by the literals (§7's rev.1 note, superseded) | | `.gitea/workflows/deploy.yml` + `.gitea/workflows/deploy-infra.yml` | **full parity with the GitHub workflows (owner decision 2026-10-28):** `permissions: contents: read` on every job; the "Check stack directory" / "Check stack variables" guard steps added; the literals `/opt/stacks/dong-site` (9 call sites) and `dong-site` (4) replaced by `${{ vars.STACK_DIR }}` / `${{ vars.CONTAINER_NAME }}`. The only intentional differences left: the header comments naming the mirror, and the guard error text pointing at Gitea's settings path (Settings → Actions → Secrets and Variables → Variables). Owner-side consequence: Gitea must now carry `STACK_DIR`, `CONTAINER_NAME` (variables) and `HTPASSWD_CONTENT` (secret) exactly like GitHub, or the guard steps refuse the run — that was previously avoided by the literals (§7's rev.1 note, superseded) |
| `compose.yaml`, `nginx.conf` | untouched — the mount and `auth_basic_user_file` names are unchanged; only the file's origin moved | | `compose.yaml`, `nginx.conf` | untouched — the mount and `auth_basic_user_file` names are unchanged; only the file's origin moved |
@@ -124,6 +124,8 @@ The token's rules are unchanged from `spec-v4-deploy-infra.md` §5: single home,
Repo-side verification 2026-10-28: YAML of both workflows parses; the write step's shell contract was exercised locally (a sample `user:$2y$…` line through the exact single-quoted `printf` form round-trips byte-identical, and a line containing `$` survives the remote shell unexpanded); `git status` shows `deploy/htpasswd` staged as removed while the file stays on disk. Owner-side: create the secret (§6), then the next infra run proves the write → test → recreate chain. Repo-side verification 2026-10-28: YAML of both workflows parses; the write step's shell contract was exercised locally (a sample `user:$2y$…` line through the exact single-quoted `printf` form round-trips byte-identical, and a line containing `$` survives the remote shell unexpanded); `git status` shows `deploy/htpasswd` staged as removed while the file stays on disk. Owner-side: create the secret (§6), then the next infra run proves the write → test → recreate chain.
**Follow-up 2026-10-28 (first dispatch): `chmod 600` → `644`.** The first `workflow_dispatch` after the secret existed wrote the file at 600; editing then failed in the nginx error log: `open() "/etc/nginx/htpasswd" failed (13: Permission denied)`. Mechanism: nginx's Basic-auth check runs in the access phase **in the worker process** — `nginx:alpine` workers run as the unprivileged `nginx` user (uid 101), not root — and `auth_basic_user_file` is opened per request, so the file must be readable by a uid other than the deploy user's. The pipeline could not catch it: `nginx -t` in both containers and the wget probe run as root, which ignores DAC permissions, and `/` carries no auth — only a real Basic-auth request reads the file as uid 101. The pre-D16 file reached the VPS via rsync from a git checkout at 644, which is why the same mount had always worked. Fix: both workflows write `chmod 644` — the file holds only a bcrypt hash, and 644 is the mode production ran with for the mount's whole life. `secrets/site_config` stays 600: its only reader is the root-run entrypoint. A stricter `640` + `chgrp 101` was considered and rejected: it hard-couples the host file to the image's internal uid. Server-side unblock was `chmod 644` on the live file (effective on the next request — a per-request open needs no reload); the next dispatch proves the corrected write.
## 8. Accepted risks ## 8. Accepted risks
- **Public repository.** Every content document and the whole commit history are public. The Basic-auth proxy still gates *writes*. - **Public repository.** Every content document and the whole commit history are public. The Basic-auth proxy still gates *writes*.