Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 ./
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-01
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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).
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Tasks

## 1. Fix the npm cache ownership ordering

- [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

- [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

- Archive the change after the project's review requirements are satisfied.
- Verify the archived result.
44 changes: 44 additions & 0 deletions openspec/specs/dockerfile-npm-cache-ownership/spec.md
Original file line number Diff line number Diff line change
@@ -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
Loading