Skip to content

fix(config): define portable project config filesystem policy - #425

Open
GazzyLee wants to merge 2 commits into
DigiNodes:mainfrom
GazzyLee:security/config-file-filesystem-policy
Open

GazzyLee wants to merge 2 commits into
DigiNodes:mainfrom
GazzyLee:security/config-file-filesystem-policy

Conversation

@GazzyLee

@GazzyLee GazzyLee commented Nov 19, 2026 •

Copy link
Copy Markdown

Summary

Defines and enforces a portable filesystem policy for stellarforge.config.json and closes the remaining ambiguity around permissive file modes, ownership, symlinks, and unreadable files.

The config file is non-secret by design (schema version, network, identity alias), so permissive POSIX modes and unusual ownership are intentionally accepted rather than rejected or warned about. The loader instead guarantees that only an inspected regular file inside the project root is ever read.

Workstream: WS-CONFIG (dependencies: SW-077, SW-082).

Policy decision

  • stellarforge.config.json must be the exact root-level filename and a regular file.
  • Symlinks are rejected explicitly, including links whose target is inside the project.
  • POSIX mode bits and ownership are ignored on every supported platform, including Windows where those bits are synthetic.
  • The CLI never calls chmod/chown, changes permissions, or attempts privilege escalation.
  • Unreadable files fail closed with a content-free validation error.

Changes

src/config/project.ts

  • Opens the config with O_NOFOLLOW where the platform exposes it, verifies the opened descriptor with fstatSync, and re-checks the path after opening before reading.
  • Reads bytes only from the verified descriptor, so a symlink substituted between inspection and read cannot redirect the read outside the project root.
  • Keeps UTF-8/BOM decoding and the existing 64 KiB limit, with content-free diagnostics: no paths, OS error text, or file contents in validation messages.
  • Extracts shared regular-file and size assertions for consistent behavior.

Tests

Added deterministic coverage in tests/config-filesystem-boundaries.test.ts for:

  • unreadable files at both the open and read stages (EACCES);
  • ELOOP from a symlink introduced during open;
  • a path becoming a symlink after the file is opened;
  • symlinks targeting files outside the project root;
  • permissive modes and foreign ownership under stubbed Windows and POSIX platforms;
  • verification that the loader never invokes chmod.

Also made the existing symlink test in tests/configuration.test.ts capability-aware so it skips only when the host cannot create symlinks (for example an unprivileged Windows runner), instead of failing.

Documentation and release note

  • docs/reference/configuration.md — documents the non-secret permission policy, symlink behavior, unreadable-file error, and no-auto-chmod guarantee.
  • docs/reference/troubleshooting.md — adds remediation guidance for unreadable config files and the cancellation exit code.
  • docs/reference/platform-support.md — notes that POSIX permission bits are not used as config trust signals.
  • Added a patch changeset.

Testing

All checks below were run against the merged branch (including current upstream/main at 07bb0a3):

  • npm ci --ignore-scripts — pass.
  • npm run typecheck — pass.
  • npm run lint — pass.
  • npm run format:check — pass.
  • npm run audit:workflow-permissions — pass.
  • npm test — 91 files passed; 2105 tests passed, 5 skipped.
  • npm run build — pass.
  • npm run test:e2e — pass (linked CLI and packed-tarball consumer smoke).
  • Generated-project smoke for basic-app, api-service, and full-stack: npm install, npm run check, and npm test all pass.
  • Focused config suites (config-filesystem-boundaries, configuration, config-malformed-json, UTF-8/BOM) pass.
  • actionlint was not run locally because the Go toolchain is unavailable in this environment; the repository's workflow static checks (workflow-security, workflow-permissions, release-workflow) pass.

The merge also repaired broken cancellation/exit-code APIs, lint/format drift, and missing workflow-permission fixtures inherited from upstream/main, so the required CI jobs are green on this branch.

Security

  • Only a verified regular file inside the project root is read; symlinks are rejected and reads use the verified descriptor rather than the path, closing inspection-to-read swaps.
  • Unreadable files fail with a content-free validation message; no paths, OS error strings, file contents, secrets, or identity values are reflected.
  • No chmod, chown, permission mutation, or privilege escalation is performed; POSIX mode and ownership bits are ignored on all platforms.
  • No new runtime dependencies, no configuration schema or precedence changes, and no changes to CLI exit-code categories beyond restoring the documented cancellation code 130.
  • Mainnet deployment, hosted services, credentials, and contributor PR ownership are untouched.
  • The Stellar Wave label was not applied by this PR; activation remains an explicit maintainer decision. The linked issue already carries the label.

Closes #340

Read the config through an inspected regular-file descriptor, reject symlinks explicitly (including link swaps), ignore POSIX mode/ownership on all platforms, and keep unreadable-file errors content-free. Add deterministic regression coverage and document the non-secret permission policy.
@GazzyLee
GazzyLee requested a review from dDevAhmed as a code owner November 19, 2026 16:56
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: ddd60a26-2c05-45e8-a8e4-80b7661b3167
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

…e-filesystem-policy

# Conflicts:
#	docs/reference/troubleshooting.md
#	src/config/project.ts
@GazzyLee

Copy link
Copy Markdown
Author

Update: branch is now merged with current \upstream/main\ (\

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SW-159 — Validate project config file permissions and ownership assumptions

1 participant