Skip to content

feat: developer-entrypoint reads TRENTINA_MCP_TOKEN_FILE - #78

Merged
fatherlinux merged 4 commits into
mainfrom
feat/token-file-77
Nov 18, 2026
Merged

fatherlinux merged 4 commits into
mainfrom
feat/token-file-77

Conversation

@fatherlinux

Copy link
Copy Markdown
Member

Closes #77.

Exedore delivers a seat's secrets as files under /run/srv-secrets/maxN. The entrypoint now reads the gateway token from TRENTINA_MCP_TOKEN_FILE when set (one trailing newline stripped), and the file wins over TRENTINA_MCP_TOKEN.

  • The file is read with the read builtin into TRENTINA_MCP_TOKEN, so the token reaches exactly what the variable always reached (Claude Code's state file, git's include file, gatehouse.env, all 0600) and is unset with it before Claude Code starts. Never in argv or a log.
  • Fail closed: a file that is missing, not a regular readable file, empty, or more than one line (including \r\n) exits 1 with a message naming the variable, never the value, before anything is written.
  • Other secrets read from env: none. TRENTINA_MCP_TOKEN is the only one; the Matrix token is already a file (JOSUI_MATRIX_TOKEN_FILE) read by claude-agent itself.

Tests: file wins over the variable (state file, gitconfig, gatehouse.env), file without the variable, token and variable absent from the agent's env, and refusal for missing / directory / empty / multi-line files. .sdlc/bin/sdlc ci green locally.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R7Y1jg3ZJ6BsAEfhrPWFRh

Exedore delivers a seat's secrets as files under /run/srv-secrets. The
entrypoint now reads the gateway token from TRENTINA_MCP_TOKEN_FILE when
set, stripping one trailing newline, and it wins over TRENTINA_MCP_TOKEN.
It is read into TRENTINA_MCP_TOKEN, so it reaches exactly what the
variable always reached and is unset with it before Claude Code starts.
A missing, unreadable, empty or multi-line file stops the start, naming
the variable and never the value.

Closes #77

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R7Y1jg3ZJ6BsAEfhrPWFRh

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gatehouse found 3 issues (2 high, 1 low)

Full review.

1 finding(s) dropped: their evidence is not in the diff.

1 of 8 agents served by google/gemini-3.5-flash-lite (primary unavailable).

fi
# read is a builtin, so the token is never in a process's arguments.
token_from_file=
IFS= read -r -d '' token_from_file < "$TRENTINA_MCP_TOKEN_FILE" || true

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

HIGH (Bug Hunter): With -d '', Bash reads until the first NUL byte. A file containing a valid token prefix followed by a NUL and additional bytes is therefore accepted as the prefix, without detecting that the file contained extra data. The resulting credential can differ silently from the contents of the token file.

Suggestion: Reject token files containing NUL bytes before reading them, or use a byte-level read and validation method that confirms the entire file was consumed and contains no NULs.

Evidence:

IFS= read -r -d '' token_from_file < "$TRENTINA_MCP_TOKEN_FILE" || true

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 88fbe32

read -d '' -n 4097 now succeeds only when it stops on a NUL or hits the length cap, and the start is refused in that case; reaching EOF is the only way through. Covered by test_a_token_file_with_a_nul_stops_the_start.

fi
# read is a builtin, so the token is never in a process's arguments.
token_from_file=
IFS= read -r -d '' token_from_file < "$TRENTINA_MCP_TOKEN_FILE" || true

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

HIGH (Performance Check): This read consumes the entire file into a shell variable before checking whether it contains multiple lines. An unexpectedly large token file can therefore cause substantial memory use or exhaust the container before the entrypoint rejects it.

Suggestion: Bound the amount read to the maximum acceptable token size plus enough data to detect overflow, and reject files that exceed that limit.

Evidence:

IFS= read -r -d '' token_from_file < "$TRENTINA_MCP_TOKEN_FILE" || true

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 88fbe32

The read is capped at 4097 characters; a file longer than 4096 bytes is refused without being read further. Covered by test_an_oversized_token_file_stops_the_start and test_a_token_file_at_the_size_limit_is_accepted.

# start, naming the variable and never the value: a seat that came up without
# its gateway would look healthy and do nothing.
if [ -n "${TRENTINA_MCP_TOKEN_FILE:-}" ]; then
if ! [ -f "$TRENTINA_MCP_TOKEN_FILE" ] || ! [ -r "$TRENTINA_MCP_TOKEN_FILE" ]; then

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LOW (Test Coverage): The new unreadable-file failure path is not covered. The tests exercise a missing path and a directory, but neither is a regular file that exists and cannot be read.

Suggestion: Add a test for an unreadable regular token file and verify startup is refused without exposing the token. Ensure the test runs in a context where the file is actually unreadable to the entrypoint.

Evidence:

if ! [ -f "$TRENTINA_MCP_TOKEN_FILE" ] || ! [ -r "$TRENTINA_MCP_TOKEN_FILE" ]; then
  log "TRENTINA_MCP_TOKEN_FILE is set but is not a readable file; not starting"
  exit 1
fi

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 88fbe32

Added test_an_unreadable_token_file_stops_the_start (a 0000 regular file). Root reads through file modes, so it is skipped for root under the same scoped gourmand exception the read-only-checkout test already has.

A NUL cut the token short unnoticed and the whole file was read into
memory. read now stops at a NUL or 4097 characters and succeeds only
then, so reaching EOF is the one way through. Adds tests for an
unreadable, NUL-bearing, oversized and at-limit file; the unreadable one
cannot hold for root, so it gets the same gourmand exception as the
read-only-checkout test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R7Y1jg3ZJ6BsAEfhrPWFRh

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gatehouse found 2 issues (2 medium)

Reviewed 1 commit since e844243 (incremental).

7 finding(s) dropped: their evidence is not in the diff.

# the end of the file is the one way through. So a NUL cannot cut the token
# short unnoticed, and a huge file is not read into memory.
token_from_file=
if IFS= read -r -d '' -n 4097 token_from_file < "$TRENTINA_MCP_TOKEN_FILE"; then

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MEDIUM (Security Scan): Bash read -n counts characters according to the active locale, not bytes. In a multibyte locale, a token file can exceed the documented 4096-byte limit while containing fewer than 4097 characters, so the size check can accept oversized files.

Suggestion: Make the read count bytes, for example by running this builtin with LC_ALL=C, or enforce the byte limit with a bounded byte-oriented read.

Evidence:

if IFS= read -r -d '' -n 4097 token_from_file < "$TRENTINA_MCP_TOKEN_FILE"; then

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 6665633

The read now runs as LC_ALL=C IFS= read -r -d '' -n 4097, so -n counts bytes whatever the seat's locale.

Comment thread tests/test_entrypoint.py
def test_a_token_file_with_a_nul_stops_the_start(self) -> None:
self.assert_refused(self.token_file("file-token\0extra\n"))

def test_an_oversized_token_file_stops_the_start(self) -> None:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MEDIUM (Test Coverage): The oversized-file test uses only ASCII, so it does not check the documented 4096-byte limit when the shell runs in a multibyte locale. Bash read -n counts characters in that case; a file with more than 4096 bytes but fewer than 4097 characters could evade the intended limit.

Suggestion: Add a test using a multibyte value whose byte length exceeds 4096 while its character count is below 4097, and run it with a UTF-8 locale to verify the file is refused.

Evidence:

    def test_an_oversized_token_file_stops_the_start(self) -> None:
        self.assert_refused(self.token_file("x" * 4097))

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 6665633

Added test_the_size_limit_is_in_bytes_in_a_multibyte_locale: 2049 × é (4098 bytes, 2049 characters) under LC_ALL=C.UTF-8. It fails without the fix and passes with it.

read -n counts characters in the locale, so under UTF-8 a file over
4096 bytes passed. The read runs under LC_ALL=C; a multibyte test
covers it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R7Y1jg3ZJ6BsAEfhrPWFRh

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gatehouse found no issues.

Reviewed 1 commit since 88fbe32 (incremental).

@fatherlinux

Copy link
Copy Markdown
Member Author

Second-seat review (a270) at 6665633: changes requested. One change, to the gourmand exception. The entrypoint change itself is correct.

Change

  1. gourmand-exceptions.toml:34-41: the EV003 exception is not scoped to the one test. gourmand 0.16.5 matches exceptions by path glob only; its README documents only check / path / justification / classification. So the pattern = "test_an_unreadable_token_file_stops_the_start" line is silently ignored, and the exception hides EV003 for every test in tests/test_entrypoint.py (1,200 lines and growing). I checked this with gourmand check --full in quay.io/crunchtools/sdlc:latest. I appended an unrelated @unittest.skipIf(os.geteuid() == 0, ...) test to the file. With the exception in place EV003 passes. Without it, EV003 reports two violations, :225 test_an_unreadable_token_file_stops_the_start and :1200 test_other. Fix: move that one test into its own file (for example tests/test_entrypoint_unreadable_token.py, reusing the fixture) and point the exception's path at that file. Then the exception covers exactly one test. The pattern = "skipIf" on the test_skills_sync.py exception is ignored in the same way. That one is harmless today, since the file has one skip, but the key misleads, so drop it.

Verified

  • _FILE wins: the block at developer-entrypoint:21-43 overwrites and exports TRENTINA_MCP_TOKEN from the file before anything reads it. test_a_token_file_wins_over_the_variable checks all three sinks.
  • Fail closed: missing file, directory, unreadable, NUL, over 4096 bytes, empty, \n alone, \r\n, two lines. Each exit 1 happens before any state is written. The messages name TRENTINA_MCP_TOKEN_FILE only, with no value and no path. All 16 token tests pass as uid 1000. CI runs as root, so it skips the unreadable case. The read -d '' -n 4097 success-means-refuse logic is sound: only reaching EOF gets through.
  • Byte-exact under LC_ALL=C: I checked this directly on bash 5.3.9. In a C.UTF-8 shell, a 2049×é file (4098 bytes, 2049 characters) is refused with the LC_ALL=C prefix and accepted without it. So the prefix does take effect for the builtin, and test_the_size_limit_is_in_bytes_in_a_multibyte_locale would catch its removal. Bytes such as \xff\xfe, a backslash and a trailing space come through unchanged.
  • Hand-off unchanged: the diff only adds the block above. The token still reaches the gitconfig (built by the printf builtin under umask 077), the state file (python, passed through the environment) and gatehouse.env (mktemp 0600, sent through a heredoc on stdin). In none of them is it in argv. token_from_file and TRENTINA_MCP_TOKEN_FILE are unset right away. TRENTINA_MCP_TOKEN is unset at :244, and gateway_token is never exported. The test asserts that neither the value nor the name is in claude's environment.
  • sdlc ci: lint, mypy, pytest (157 passed, 3 skipped as root), pip-audit, the constitution validator and codeql pass.

Not requested: TRENTINA_MCP_TOKEN_FILE= (set but empty) is treated as unset and falls back to the variable. That's the usual _FILE convention, so it's fine, but a one-line note in the README would remove any doubt.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R7Y1jgC5WYMYiuEavEkLHa

gourmand 0.16.5 matches an exception by path and ignores `pattern`, so
the EV003 exceptions excused every skipIf in test_entrypoint.py and
test_skills_sync.py. The two root-skipped tests move to files of their
own, with the helpers they need in a base class, and each exception now
names only that file. A probe skipIf in test_entrypoint.py is flagged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R7Y1jg3ZJ6BsAEfhrPWFRh

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gatehouse found no issues.

Reviewed 1 commit since 6665633 (incremental).

@fatherlinux
fatherlinux merged commit b28cdb8 into main Nov 18, 2026
12 checks passed
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.

developer-entrypoint: accept TRENTINA_MCP_TOKEN_FILE

1 participant