sec(infra): non-root container + capability drop (ADR-0003)

Container ran as root until now; PR #2 acknowledged this in
scripts/entrypoint.sh which still writes to /root/.claude/...  The
collab feature gives any participant a PTY inside the container, so
"running as root" means a participant could cat /root/.local/share/opencode/*.sqlite
and read every other user's GitHub OAuth token, or env-print
SESSION_SECRET and the OAuth client secret.

Add a non-root user (uid 10001) and hand the runtime tree over to it.

  Dockerfile
    + useradd opencode uid 10001 with /home/opencode as $HOME
    + chown -R 10001:10001 /app /home/opencode /var/opencode
      /usr/local/bin/opencode-entrypoint
    + USER opencode + ENV HOME=/home/opencode at the very end so build
      stages stay as root (faster, no permission gymnastics during build)
    + runtime dirs moved from /root/{.local,.config,.cache,.claude}
      to /home/opencode/{.local,.config,.cache,.claude}
    + plugin cache copied from /root path so the existing
      opencode-claude-auth pre-install is preserved across the move

  scripts/entrypoint.sh
    + $HOME_DIR derived from $HOME (set by the Dockerfile) — writes
      $CLAUDE_CREDENTIALS_JSON to $HOME_DIR/.claude/.credentials.json,
      not the hard-coded /root path

  docker-compose.yml
    + Volume mounts and bind-mount target moved to /home/opencode/...
    + Healthcheck switched to GET /healthz (ADR-0008) — finer-grained
      than GET / which only fails on a fully-dead Bun process

  DEPLOYMENT.md
    + ECS task definition gets "user": "10001:10001",
      "linuxParameters.capabilities.drop: [ALL]", healthcheck on /healthz
    + EFS volumes wired via Access Points (posixUser 10001/10001) with
      transitEncryption=ENABLED
    + One-time chown migration documented (aws ecs run-task with an
      entrypoint override) — operator step, not workflow plumbing,
      because it runs once per environment lifetime
    + EFS Access Point creation commands + the IAM perms the task role
      needs (ClientMount + ClientWrite on the AP ARNs)

Local docker-compose continues to work: named volumes inherit their
uid from the container that first writes to them, so a fresh
"docker compose up -d --build" creates opencode-data as uid 10001 and
the bind-mount of ~/.claude/.credentials.json is read-only.

Author: hblanken

DEPLOYMENT.md

@@ -139,10 +139,13 @@ Two file systems (or one with two access points) so the SQLite DB stays separate
 aws efs create-file-system --creation-token opencode-data       --region $REGION
 aws efs create-file-system --creation-token collab-workspaces   --region $REGION
 # Create mount targets in each subnet your ECS service runs in.
-# Create access points (uid/gid 0, root path "/data" each) so the task can mount
-# them at /root/.local/share/opencode and /var/opencode/workspaces respectively.
 ```
 
+Access points use **uid/gid 10001** (ADR-0003 — the `opencode` user).
+The exact `create-access-point` commands and the one-time chown of
+existing data live in "One-time EFS migration to uid 10001" inside
+Step 5 below.
+
 Lower-spend alternative for early days: a single EC2 instance with EBS works fine — workspace dirs rarely exceed a few GB unless you clone monorepos.
 
 ### Step 4 — AWS Secrets Manager entries
@@ -191,11 +194,16 @@ Fargate, 2 vCPU / 4 GB.  Replace `<…>` placeholders with the ARNs and IDs you
       { "name": "SESSION_SECRET",             "valueFrom": "<arn of opencode/session_secret>" }
     ],
     "mountPoints": [
-      { "sourceVolume": "opencode-data",      "containerPath": "/root/.local/share/opencode" },
+      { "sourceVolume": "opencode-data",      "containerPath": "/home/opencode/.local/share/opencode" },
       { "sourceVolume": "collab-workspaces",  "containerPath": "/var/opencode/workspaces" }
     ],
+    "linuxParameters": {
+      "capabilities": { "drop": ["ALL"] }
+    },
+    "readonlyRootFilesystem": false,
+    "user": "10001:10001",
     "healthCheck": {
-      "command": ["CMD-SHELL", "node -e \"require('http').get('http://localhost:4096/',r=>process.exit(r.statusCode<500?0:1)).on('error',()=>process.exit(1))\""],
+      "command": ["CMD-SHELL", "node -e \"require('http').get('http://localhost:4096/healthz',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))\""],
       "interval": 15, "timeout": 5, "retries": 5, "startPeriod": 30
     },
     "logConfiguration": {
@@ -208,12 +216,95 @@ Fargate, 2 vCPU / 4 GB.  Replace `<…>` placeholders with the ARNs and IDs you
     }
   }],
   "volumes": [
-    { "name": "opencode-data",     "efsVolumeConfiguration": { "fileSystemId": "<fs-id>", "rootDirectory": "/opencode-data"     } },
-    { "name": "collab-workspaces", "efsVolumeConfiguration": { "fileSystemId": "<fs-id>", "rootDirectory": "/collab-workspaces" } }
+    {
+      "name": "opencode-data",
+      "efsVolumeConfiguration": {
+        "fileSystemId": "<fs-id>",
+        "transitEncryption": "ENABLED",
+        "authorizationConfig": { "accessPointId": "<fsap-id-data>", "iam": "ENABLED" }
+      }
+    },
+    {
+      "name": "collab-workspaces",
+      "efsVolumeConfiguration": {
+        "fileSystemId": "<fs-id>",
+        "transitEncryption": "ENABLED",
+        "authorizationConfig": { "accessPointId": "<fsap-id-workspaces>", "iam": "ENABLED" }
+      }
+    }
   ]
 }
 ```
 
+#### One-time EFS migration to uid 10001 (ADR-0003)
+
+Existing deployments wrote EFS files as uid 0.  Before the new task
+definition above is deployed, the on-disk data has to be chowned —
+otherwise the new container (uid 10001) can't read its own SQLite file
+or write to workspace clones.
+
+**Step 1 — chown the existing data** with the *current* image (still
+root), using an entrypoint override on a one-off ECS task:
+
+```bash
+aws ecs run-task --cluster <cluster> \
+  --task-definition <current-revision> \
+  --launch-type FARGATE \
+  --network-configuration 'awsvpcConfiguration={subnets=[...],securityGroups=[...]}' \
+  --overrides '{
+    "containerOverrides":[{
+      "name":"opencode",
+      "command":["chown","-R","10001:10001",
+                 "/var/opencode/workspaces",
+                 "/root/.local/share/opencode"]
+    }]
+  }'
+
+# Wait for it to finish
+aws ecs wait tasks-stopped --cluster <cluster> --tasks <task-arn-from-above>
+```
+
+This runs once, typically completes in under a minute.
+
+**Step 2 — create EFS Access Points** so future writes are forced to
+uid 10001 regardless of in-container uid drift:
+
+```bash
+aws efs create-access-point \
+  --file-system-id <fs-id-data> \
+  --posix-user 'Uid=10001,Gid=10001' \
+  --root-directory 'Path=/,CreationInfo={OwnerUid=10001,OwnerGid=10001,Permissions=0755}' \
+  --tags 'Key=Name,Value=opencode-data-ap'
+
+aws efs create-access-point \
+  --file-system-id <fs-id-workspaces> \
+  --posix-user 'Uid=10001,Gid=10001' \
+  --root-directory 'Path=/,CreationInfo={OwnerUid=10001,OwnerGid=10001,Permissions=0755}' \
+  --tags 'Key=Name,Value=collab-workspaces-ap'
+```
+
+**Step 3 — IAM** — the task role needs EFS client perms on the AP ARNs:
+
+```jsonc
+{
+  "Effect": "Allow",
+  "Action": ["elasticfilesystem:ClientMount", "elasticfilesystem:ClientWrite"],
+  "Resource": ["<arn of fsap-data>", "<arn of fsap-workspaces>"]
+}
+```
+
+`ClientRootAccess` is NOT needed after step 1; the chown is the only
+operation that requires it.
+
+**Step 4 — deploy the new task definition** (the one with `"user": "10001:10001"`).
+ECS rolls it in.  If the chown was successful, the container starts;
+if not, you'll see "Permission denied" errors on the SQLite open and
+the task crashes — re-run step 1.
+
+> Local docker-compose is unaffected: named volumes inherit their uid
+> from the container that first writes to them; a fresh
+> `docker compose up -d --build` creates `opencode-data` as uid 10001.
+
 Key points vs. the local `docker-compose.yml`:
 
 - `ANTHROPIC_API_KEY` is now a real API key (was `dummy` locally).  This bypasses the `opencode-claude-auth` plugin entirely — opencode sees a non-empty key and uses it directly.

Dockerfile

@@ -72,8 +72,16 @@ RUN --mount=type=cache,target=/root/.npm \
     echo "WARNING: opencode-claude-auth pre-install failed; will install lazily at runtime"
 
 # Pre-create directories that opencode and the collab workspace need at runtime.
-RUN mkdir -p /var/opencode/workspaces /root/.local/share/opencode /root/.config/opencode && \
-    printf '{"plugin":["opencode-claude-auth@latest"]}\n' > /root/.config/opencode/opencode.json
+# Paths live under /home/opencode (ADR-0003) — the opencode user owns them and
+# they're created here so the final-stage chown is one shallow walk.
+RUN mkdir -p /var/opencode/workspaces \
+             /home/opencode/.local/share/opencode \
+             /home/opencode/.config/opencode \
+             /home/opencode/.cache/opencode/packages \
+             /home/opencode/.claude && \
+    printf '{"plugin":["opencode-claude-auth@latest"]}\n' > /home/opencode/.config/opencode/opencode.json && \
+    # Carry the pre-installed plugin tree across from /root.
+    cp -r /root/.cache/opencode/packages/. /home/opencode/.cache/opencode/packages/ 2>/dev/null || true
 
 # Bring in ONLY manifests, then install workspace deps.
 # Cache mount on /root/.bun/install/cache keeps the bun package store between builds.
@@ -104,7 +112,23 @@ RUN --mount=type=cache,target=/app/packages/app/node_modules/.vite \
 COPY scripts/entrypoint.sh /usr/local/bin/opencode-entrypoint
 RUN chmod +x /usr/local/bin/opencode-entrypoint
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Non-root user (ADR-0003).
+#
+# Until this stage everything ran as root for build speed.  Now we create the
+# `opencode` user (uid 10001) and hand the runtime tree over to it.  The
+# container's working set after this point — /app, /home/opencode, and the
+# data mount at /var/opencode — is owned by uid 10001.  Drops the
+# blast-radius of any future RCE / PTY abuse from "read every secret" to
+# "stuff the unprivileged user can see".
+# ─────────────────────────────────────────────────────────────────────────────
+RUN useradd --uid 10001 --create-home --shell /bin/bash --home-dir /home/opencode opencode 2>/dev/null || true && \
+    chown -R 10001:10001 /app /home/opencode /var/opencode /usr/local/bin/opencode-entrypoint
+
 ENV NODE_ENV=production
+ENV HOME=/home/opencode
 EXPOSE 4096
 
+USER opencode
+
 ENTRYPOINT ["/usr/local/bin/opencode-entrypoint"]

docker-compose.yml

@@ -43,16 +43,18 @@ services:
       - OPENAI_API_KEY=${OPENAI_API_KEY:-}
 
     volumes:
-      # Persistent SQLite database
-      - opencode-data:/root/.local/share/opencode
+      # Persistent SQLite database — owned by uid 10001 (ADR-0003).
+      - opencode-data:/home/opencode/.local/share/opencode
       # Persistent server-side repo workspaces
       - collab-workspaces:/var/opencode/workspaces
       # Claude Code credentials for opencode-claude-auth plugin (bind-mount from host)
       # To populate: security find-generic-password -s "Claude Code-credentials" -w > ~/.claude/.credentials.json
-      - ${HOME}/.claude/.credentials.json:/root/.claude/.credentials.json:ro
+      - ${HOME}/.claude/.credentials.json:/home/opencode/.claude/.credentials.json:ro
     restart: unless-stopped
     healthcheck:
-      test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:4096/',r=>process.exit(r.statusCode<500?0:1)).on('error',()=>process.exit(1))\""]
+      # /healthz returns 503 when SQLite is unreachable — finer-grained than
+      # GET / (which only fails on a fully-dead Bun process).  See ADR-0008.
+      test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:4096/healthz',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))\""]
       interval: 15s
       timeout: 5s
       retries: 5

scripts/entrypoint.sh

@@ -17,10 +17,17 @@
 
 set -eu
 
+# Resolve the home dir from $HOME (set by the Dockerfile to /home/opencode
+# under ADR-0003).  Falls back to /home/opencode if unset, which is the
+# only correct path post-ADR.  /root/... would mean we're still root —
+# entrypoint logs would show a chown error and the credential write would
+# 500 the auth plugin until ECS replaces the task.
+HOME_DIR="${HOME:-/home/opencode}"
+
 if [ -n "${CLAUDE_CREDENTIALS_JSON:-}" ]; then
-  mkdir -p /root/.claude
-  printf '%s' "$CLAUDE_CREDENTIALS_JSON" > /root/.claude/.credentials.json
-  chmod 0600 /root/.claude/.credentials.json
+  mkdir -p "$HOME_DIR/.claude"
+  printf '%s' "$CLAUDE_CREDENTIALS_JSON" > "$HOME_DIR/.claude/.credentials.json"
+  chmod 0600 "$HOME_DIR/.claude/.credentials.json"
 fi
 
 # Hand off to the real server.  $@ propagates whatever args ECS / CMD passed.