From e52247a5024cb6ccd53b0bd40e8ea9de600f57a5 Mon Sep 17 00:00:00 2001 From: Jason Date: Sun, 1 Nov 2026 07:19:10 -0500 Subject: [PATCH 1/3] docs: add OpenSpec change for npm cache chown ordering --- .../.openspec.yaml | 2 + .../design.md | 65 +++++++++++++++++++ .../proposal.md | 49 ++++++++++++++ .../dockerfile-npm-cache-ownership/spec.md | 45 +++++++++++++ .../tasks.md | 16 +++++ 5 files changed, 177 insertions(+) create mode 100644 openspec/changes/dockerfile-npm-cache-chown-ordering/.openspec.yaml create mode 100644 openspec/changes/dockerfile-npm-cache-chown-ordering/design.md create mode 100644 openspec/changes/dockerfile-npm-cache-chown-ordering/proposal.md create mode 100644 openspec/changes/dockerfile-npm-cache-chown-ordering/specs/dockerfile-npm-cache-ownership/spec.md create mode 100644 openspec/changes/dockerfile-npm-cache-chown-ordering/tasks.md diff --git a/openspec/changes/dockerfile-npm-cache-chown-ordering/.openspec.yaml b/openspec/changes/dockerfile-npm-cache-chown-ordering/.openspec.yaml new file mode 100644 index 000000000..25002a8e8 --- /dev/null +++ b/openspec/changes/dockerfile-npm-cache-chown-ordering/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-01 diff --git a/openspec/changes/dockerfile-npm-cache-chown-ordering/design.md b/openspec/changes/dockerfile-npm-cache-chown-ordering/design.md new file mode 100644 index 000000000..bf01ef48a --- /dev/null +++ b/openspec/changes/dockerfile-npm-cache-chown-ordering/design.md @@ -0,0 +1,65 @@ +# Design + +## Context + +See proposal.md for motivation. In the final stage of `Dockerfile`, `ENV HOME=/home/madz` +(line 53) makes npm resolve its cache to `/home/madz/.npm`. The global installs +`npm install -g yarn pnpm` (line 67) and `npm install -g @fission-ai/openspec@latest` +(line 70) run as root and populate that cache as root. The earlier +`RUN chown -R madz:node /app /home/madz` (line 57) runs *before* those installs, so it +cannot fix the cache. The result is a root-owned `/home/madz/.npm` and `EACCES` for the +`madz` user at runtime. + +## Goals / Non-Goals + +**Goals:** +- Ensure `/home/madz/.npm` is owned by `madz:node` after all global npm installs. +- Make the fix robust so a future global install cannot silently re-break ownership. +- Fail the build loudly if the cache is not owned by `madz`. + +**Non-Goals:** +- No change to which packages are installed, their versions, or the builder stage. +- No change to `docker-entrypoint.sh` (its ownership logic is already correct). +- No unit test for Dockerfile ownership (no such infrastructure exists). + +## Decisions + +- **Explicit re-chown after the global installs, not merely moving line 57.** + Adding `RUN chown -R madz:node /home/madz/.npm` immediately after the global installs + (after line 70) is the primary fix. + - *Alternative considered:* move the line-57 `chown -R madz:node /app /home/madz` to + after the global installs. Rejected as the sole fix because a future global install + added later would re-break ownership. The explicit re-chown stays authoritative as + long as it remains the last ownership operation on the cache. +- **Pin `ENV NPM_CONFIG_CACHE=/home/madz/.npm`.** Makes the cache path explicit and + stable rather than implicitly derived from `HOME`, so the chown target is unambiguous + and intent is documented. + - *Alternative considered:* rely on `HOME`-derived cache resolution. Rejected — implicit + resolution is the very thing that made the bug subtle. +- **Build-time assertion `RUN test "$(stat -c '%U' /home/madz/.npm)" = madz`.** Fails the + build if the cache is not owned by `madz`, guaranteeing the regression cannot ship. + - *Alternative considered:* a runtime check in `docker-entrypoint.sh`. Rejected — a + runtime check lets a broken image ship; a build-time check is stricter and catches the + problem at build time. +- **`stat -c '%U'` (GNU coreutils).** Present in `node:26-slim` (Debian-based), so the + assertion is portable to the existing base image. No new dependency. + +## Risks / Trade-offs + +- [A future global install added after the re-chown re-breaks ownership] → The build-time + assertion catches it: the build fails until the re-chown is moved after the new install. +- [`stat -c` unavailable on a non-GNU base] → The base is `node:26-slim` (Debian), which + ships GNU coreutils; risk is negligible. If the base ever changes to a non-GNU image, the + assertion would need `stat -f '%Su'` (BSD) — noted for maintainers. +- [Pinning `NPM_CONFIG_CACHE` changes cache location for any tool that reads it] → The + pinned path equals the `HOME`-derived path (`/home/madz/.npm`), so behavior is unchanged; + the pin only makes it explicit. + +## Migration Plan + +- No data migration. The change is a Dockerfile edit; the next image build picks it up. +- Rollback: revert the `Dockerfile` change and rebuild. + +## Open Questions + +- None. diff --git a/openspec/changes/dockerfile-npm-cache-chown-ordering/proposal.md b/openspec/changes/dockerfile-npm-cache-chown-ordering/proposal.md new file mode 100644 index 000000000..d0ead22a8 --- /dev/null +++ b/openspec/changes/dockerfile-npm-cache-chown-ordering/proposal.md @@ -0,0 +1,49 @@ +# Proposal + +## Why + +In the final stage of `Dockerfile`, `RUN chown -R madz:node /app /home/madz` (line 57) +runs *before* the global npm installs `npm install -g yarn pnpm` (line 67) and +`npm install -g @fission-ai/openspec@latest` (line 70). Because `ENV HOME=/home/madz` +(line 53) makes npm resolve its cache to `/home/madz/.npm`, those root-run installs +populate that cache as `root`, and nothing re-chowns it afterward. The `madz` user then +hits `EACCES` on `/home/madz/.npm` at runtime. This change fixes the ordering and makes +the ownership robust and self-verifying. + +## What Changes + +- Add an explicit `RUN chown -R madz:node /home/madz/.npm` immediately after the global + npm installs (after line 70), so the cache is re-owned by `madz:node` after every + global install. +- Pin `ENV NPM_CONFIG_CACHE=/home/madz/.npm` so the cache path is explicit and stable + rather than implicitly derived from `HOME`. +- Add a build-time assertion `RUN test "$(stat -c '%U' /home/madz/.npm)" = madz` that + fails the build if the cache is not owned by `madz`, so the regression cannot ship. +- Leave the existing line-57 `chown -R madz:node /app /home/madz` in place; the new + explicit cache re-chown + assertion is the authoritative ownership check for the cache. + +## Capabilities + +### New Capabilities +- `dockerfile-npm-cache-ownership`: The Dockerfile runtime stage SHALL ensure the npm + cache directory (`/home/madz/.npm`) is owned by `madz:node` after all global npm + installs, SHALL pin the cache path via `NPM_CONFIG_CACHE`, and SHALL fail the build if + the cache is not owned by `madz`. + +### Modified Capabilities +- None. + +## Impact + +- **Code:** `Dockerfile` (final stage, lines 53–70 region). +- **No source-code or test changes.** This is a build/CI tooling fix. There is no + unit-test infrastructure for Dockerfile ownership; the build-time assertion *is* the + regression guard. +- **No new dependencies.** `stat` (GNU coreutils) is present in `node:26-slim`. + +## Non-goals + +- Changing which global packages are installed, their versions, or the builder stage. +- Changing runtime behavior other than correct cache ownership. +- Changing `docker-entrypoint.sh` ownership logic (already correct). +- Adding a unit test for Dockerfile ownership (no such infrastructure exists). diff --git a/openspec/changes/dockerfile-npm-cache-chown-ordering/specs/dockerfile-npm-cache-ownership/spec.md b/openspec/changes/dockerfile-npm-cache-chown-ordering/specs/dockerfile-npm-cache-ownership/spec.md new file mode 100644 index 000000000..a88aba01a --- /dev/null +++ b/openspec/changes/dockerfile-npm-cache-chown-ordering/specs/dockerfile-npm-cache-ownership/spec.md @@ -0,0 +1,45 @@ +# Spec Delta + +## Purpose + +Guarantees that the npm cache directory in the built container image is owned by the +non-root `madz` user, so the `madz` user can read and write the cache without `EACCES`, +and that the build fails loudly if that ownership invariant is ever violated. + +## ADDED Requirements + +### Requirement: npm cache directory is owned by the madz user +The Dockerfile runtime stage SHALL ensure the npm cache directory (`/home/madz/.npm`) is +owned by `madz:node` after all global npm installs complete, so the `madz` user can read +and write the cache without `EACCES`. + +#### Scenario: Global npm installs do not leave the cache root-owned +- **WHEN** the runtime stage runs `npm install -g` commands (e.g. `yarn`, `pnpm`, + `@fission-ai/openspec`) as root +- **THEN** the npm cache directory `/home/madz/.npm` is owned by `madz:node` in the + resulting image + +#### Scenario: madz user can use the cache +- **WHEN** the `madz` user runs an npm command that reads or writes the cache +- **THEN** the command does not fail with `EACCES` on `/home/madz/.npm` + +### Requirement: npm cache path is pinned +The Dockerfile runtime stage SHALL pin the npm cache location via +`ENV NPM_CONFIG_CACHE=/home/madz/.npm` so the cache path is explicit and stable rather +than implicitly derived from `HOME`. + +#### Scenario: Cache path is explicit +- **WHEN** the runtime stage is built +- **THEN** `NPM_CONFIG_CACHE` is set to `/home/madz/.npm` + +### Requirement: Build fails if the cache is not owned by madz +The Dockerfile runtime stage SHALL include a build-time assertion that fails the build if +the npm cache directory is not owned by `madz`, so the ownership regression cannot ship. + +#### Scenario: Assertion passes when ownership is correct +- **WHEN** the runtime stage is built and `/home/madz/.npm` is owned by `madz` +- **THEN** the build-time assertion passes and the build succeeds + +#### Scenario: Assertion fails when ownership is wrong +- **WHEN** the runtime stage is built and `/home/madz/.npm` is not owned by `madz` +- **THEN** the build-time assertion fails and the build is aborted diff --git a/openspec/changes/dockerfile-npm-cache-chown-ordering/tasks.md b/openspec/changes/dockerfile-npm-cache-chown-ordering/tasks.md new file mode 100644 index 000000000..2c67d6b54 --- /dev/null +++ b/openspec/changes/dockerfile-npm-cache-chown-ordering/tasks.md @@ -0,0 +1,16 @@ +# Tasks + +## 1. Fix the npm cache ownership ordering + +- [ ] 1.1 In `Dockerfile`, add `ENV NPM_CONFIG_CACHE=/home/madz/.npm` in the runtime stage so the cache path is explicit and stable (verify the line is present and the path matches the `HOME`-derived cache location). +- [ ] 1.2 In `Dockerfile`, add `RUN chown -R madz:node /home/madz/.npm` immediately after the global npm installs (after the `npm install -g @fission-ai/openspec@latest` line) so the cache is re-owned by `madz:node` after every global install (verify the chown appears after both `npm install -g` lines). +- [ ] 1.3 In `Dockerfile`, add a build-time assertion `RUN test "$(stat -c '%U' /home/madz/.npm)" = madz` after the re-chown so the build fails if the cache is not owned by `madz` (verify the assertion line is present and runs after the re-chown). + +## 2. Verify + +- [ ] 2.1 Build the image (`npm run docker:build`) and assert `stat -c '%U:%G' /home/madz/.npm` returns `madz:node` in the built image; confirm the build-time assertion passes and the build succeeds. If a Docker daemon is unavailable in the build environment, verify the assertion logic by inspecting the Dockerfile ordering and note that the build assertion is the regression guard. + +## Workflow follow-up + +- Archive the change after the project's review requirements are satisfied. +- Verify the archived result. From 848af8b79537ecb66c735739576b622bbef1af0a Mon Sep 17 00:00:00 2001 From: Jason Date: Sun, 1 Nov 2026 07:22:28 -0500 Subject: [PATCH 2/3] fix: chown npm cache after global installs in Dockerfile The global npm installs (yarn, pnpm, @fission-ai/openspec) run as root and populate the npm cache (/home/madz/.npm, derived from ENV HOME) as root, with nothing re-chowning it afterward, so the madz user hits EACCES. Re-chown the cache after the global installs, pin NPM_CONFIG_CACHE, and add a build-time assertion that fails the build if the cache is not owned by madz. Closes #1624 --- Dockerfile | 14 ++++++++++++++ .../dockerfile-npm-cache-chown-ordering/tasks.md | 8 ++++---- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/Dockerfile b/Dockerfile index 7f3306097..e5ebfb4ad 100644 --- a/Dockerfile +++ b/Dockerfile @@ -51,6 +51,9 @@ RUN TF_VER="1.16.3" && \ # Environment ENV HOME=/home/madz +# Pin the npm cache location so the chown target below is explicit and stable +# rather than implicitly derived from HOME. +ENV NPM_CONFIG_CACHE=/home/madz/.npm WORKDIR /app # Permissions @@ -69,6 +72,17 @@ RUN npm install -g yarn pnpm # OpenSpec CLI — global module RUN npm install -g @fission-ai/openspec@latest +# The global npm installs above run as root and populate the npm cache +# (/home/madz/.npm, pinned via NPM_CONFIG_CACHE) as root. Re-chown it so the +# madz user can read/write the cache without EACCES. This re-chown runs after +# every global install, so a future `npm install -g` cannot silently re-break +# ownership as long as it stays the last ownership operation on the cache. +RUN chown -R madz:node /home/madz/.npm + +# Build-time assertion: fail the build if the npm cache is not owned by madz, +# so the ownership regression cannot ship. +RUN test "$(stat -c '%U' /home/madz/.npm)" = madz + COPY --from=builder --chown=madz:node /app/node_modules ./node_modules COPY --from=builder --chown=madz:node /app/package*.json ./ COPY --chown=madz:node LICENSE index.js config.yaml ./ diff --git a/openspec/changes/dockerfile-npm-cache-chown-ordering/tasks.md b/openspec/changes/dockerfile-npm-cache-chown-ordering/tasks.md index 2c67d6b54..2871faeac 100644 --- a/openspec/changes/dockerfile-npm-cache-chown-ordering/tasks.md +++ b/openspec/changes/dockerfile-npm-cache-chown-ordering/tasks.md @@ -2,13 +2,13 @@ ## 1. Fix the npm cache ownership ordering -- [ ] 1.1 In `Dockerfile`, add `ENV NPM_CONFIG_CACHE=/home/madz/.npm` in the runtime stage so the cache path is explicit and stable (verify the line is present and the path matches the `HOME`-derived cache location). -- [ ] 1.2 In `Dockerfile`, add `RUN chown -R madz:node /home/madz/.npm` immediately after the global npm installs (after the `npm install -g @fission-ai/openspec@latest` line) so the cache is re-owned by `madz:node` after every global install (verify the chown appears after both `npm install -g` lines). -- [ ] 1.3 In `Dockerfile`, add a build-time assertion `RUN test "$(stat -c '%U' /home/madz/.npm)" = madz` after the re-chown so the build fails if the cache is not owned by `madz` (verify the assertion line is present and runs after the re-chown). +- [x] 1.1 In `Dockerfile`, add `ENV NPM_CONFIG_CACHE=/home/madz/.npm` in the runtime stage so the cache path is explicit and stable (verify the line is present and the path matches the `HOME`-derived cache location). +- [x] 1.2 In `Dockerfile`, add `RUN chown -R madz:node /home/madz/.npm` immediately after the global npm installs (after the `npm install -g @fission-ai/openspec@latest` line) so the cache is re-owned by `madz:node` after every global install (verify the chown appears after both `npm install -g` lines). +- [x] 1.3 In `Dockerfile`, add a build-time assertion `RUN test "$(stat -c '%U' /home/madz/.npm)" = madz` after the re-chown so the build fails if the cache is not owned by `madz` (verify the assertion line is present and runs after the re-chown). ## 2. Verify -- [ ] 2.1 Build the image (`npm run docker:build`) and assert `stat -c '%U:%G' /home/madz/.npm` returns `madz:node` in the built image; confirm the build-time assertion passes and the build succeeds. If a Docker daemon is unavailable in the build environment, verify the assertion logic by inspecting the Dockerfile ordering and note that the build assertion is the regression guard. +- [x] 2.1 Build the image (`npm run docker:build`) and assert `stat -c '%U:%G' /home/madz/.npm` returns `madz:node` in the built image; confirm the build-time assertion passes and the build succeeds. If a Docker daemon is unavailable in the build environment, verify the assertion logic by inspecting the Dockerfile ordering and note that the build assertion is the regression guard. ## Workflow follow-up From 6fb0306fc5213e280a4e2bf6bee2de227e740acf Mon Sep 17 00:00:00 2001 From: Jason Date: Sun, 1 Nov 2026 07:24:06 -0500 Subject: [PATCH 3/3] chore: archive dockerfile-npm-cache-chown-ordering OpenSpec change Sync the new dockerfile-npm-cache-ownership capability spec into openspec/specs/ and move the change into the archive. --- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../dockerfile-npm-cache-ownership/spec.md | 0 .../tasks.md | 0 .../dockerfile-npm-cache-ownership/spec.md | 44 +++++++++++++++++++ 6 files changed, 44 insertions(+) rename openspec/changes/{dockerfile-npm-cache-chown-ordering => archive/2026-11-01-dockerfile-npm-cache-chown-ordering}/.openspec.yaml (100%) rename openspec/changes/{dockerfile-npm-cache-chown-ordering => archive/2026-11-01-dockerfile-npm-cache-chown-ordering}/design.md (100%) rename openspec/changes/{dockerfile-npm-cache-chown-ordering => archive/2026-11-01-dockerfile-npm-cache-chown-ordering}/proposal.md (100%) rename openspec/changes/{dockerfile-npm-cache-chown-ordering => archive/2026-11-01-dockerfile-npm-cache-chown-ordering}/specs/dockerfile-npm-cache-ownership/spec.md (100%) rename openspec/changes/{dockerfile-npm-cache-chown-ordering => archive/2026-11-01-dockerfile-npm-cache-chown-ordering}/tasks.md (100%) create mode 100644 openspec/specs/dockerfile-npm-cache-ownership/spec.md diff --git a/openspec/changes/dockerfile-npm-cache-chown-ordering/.openspec.yaml b/openspec/changes/archive/2026-11-01-dockerfile-npm-cache-chown-ordering/.openspec.yaml similarity index 100% rename from openspec/changes/dockerfile-npm-cache-chown-ordering/.openspec.yaml rename to openspec/changes/archive/2026-11-01-dockerfile-npm-cache-chown-ordering/.openspec.yaml diff --git a/openspec/changes/dockerfile-npm-cache-chown-ordering/design.md b/openspec/changes/archive/2026-11-01-dockerfile-npm-cache-chown-ordering/design.md similarity index 100% rename from openspec/changes/dockerfile-npm-cache-chown-ordering/design.md rename to openspec/changes/archive/2026-11-01-dockerfile-npm-cache-chown-ordering/design.md diff --git a/openspec/changes/dockerfile-npm-cache-chown-ordering/proposal.md b/openspec/changes/archive/2026-11-01-dockerfile-npm-cache-chown-ordering/proposal.md similarity index 100% rename from openspec/changes/dockerfile-npm-cache-chown-ordering/proposal.md rename to openspec/changes/archive/2026-11-01-dockerfile-npm-cache-chown-ordering/proposal.md diff --git a/openspec/changes/dockerfile-npm-cache-chown-ordering/specs/dockerfile-npm-cache-ownership/spec.md b/openspec/changes/archive/2026-11-01-dockerfile-npm-cache-chown-ordering/specs/dockerfile-npm-cache-ownership/spec.md similarity index 100% rename from openspec/changes/dockerfile-npm-cache-chown-ordering/specs/dockerfile-npm-cache-ownership/spec.md rename to openspec/changes/archive/2026-11-01-dockerfile-npm-cache-chown-ordering/specs/dockerfile-npm-cache-ownership/spec.md diff --git a/openspec/changes/dockerfile-npm-cache-chown-ordering/tasks.md b/openspec/changes/archive/2026-11-01-dockerfile-npm-cache-chown-ordering/tasks.md similarity index 100% rename from openspec/changes/dockerfile-npm-cache-chown-ordering/tasks.md rename to openspec/changes/archive/2026-11-01-dockerfile-npm-cache-chown-ordering/tasks.md diff --git a/openspec/specs/dockerfile-npm-cache-ownership/spec.md b/openspec/specs/dockerfile-npm-cache-ownership/spec.md new file mode 100644 index 000000000..0a579580c --- /dev/null +++ b/openspec/specs/dockerfile-npm-cache-ownership/spec.md @@ -0,0 +1,44 @@ +# dockerfile-npm-cache-ownership Specification + +## Purpose +Guarantees that the npm cache directory in the built container image is owned by the +non-root `madz` user, so the `madz` user can read and write the cache without `EACCES`, +and that the build fails loudly if that ownership invariant is ever violated. + +## Requirements + +### Requirement: npm cache directory is owned by the madz user +The Dockerfile runtime stage SHALL ensure the npm cache directory (`/home/madz/.npm`) is +owned by `madz:node` after all global npm installs complete, so the `madz` user can read +and write the cache without `EACCES`. + +#### Scenario: Global npm installs do not leave the cache root-owned +- **WHEN** the runtime stage runs `npm install -g` commands (e.g. `yarn`, `pnpm`, + `@fission-ai/openspec`) as root +- **THEN** the npm cache directory `/home/madz/.npm` is owned by `madz:node` in the + resulting image + +#### Scenario: madz user can use the cache +- **WHEN** the `madz` user runs an npm command that reads or writes the cache +- **THEN** the command does not fail with `EACCES` on `/home/madz/.npm` + +### Requirement: npm cache path is pinned +The Dockerfile runtime stage SHALL pin the npm cache location via +`ENV NPM_CONFIG_CACHE=/home/madz/.npm` so the cache path is explicit and stable rather +than implicitly derived from `HOME`. + +#### Scenario: Cache path is explicit +- **WHEN** the runtime stage is built +- **THEN** `NPM_CONFIG_CACHE` is set to `/home/madz/.npm` + +### Requirement: Build fails if the cache is not owned by madz +The Dockerfile runtime stage SHALL include a build-time assertion that fails the build if +the npm cache directory is not owned by `madz`, so the ownership regression cannot ship. + +#### Scenario: Assertion passes when ownership is correct +- **WHEN** the runtime stage is built and `/home/madz/.npm` is owned by `madz` +- **THEN** the build-time assertion passes and the build succeeds + +#### Scenario: Assertion fails when ownership is wrong +- **WHEN** the runtime stage is built and `/home/madz/.npm` is not owned by `madz` +- **THEN** the build-time assertion fails and the build is aborted