feat: work on the relay — dotfile permissions, relay CLI, JWT mapping

[khaliqgant]

Summary

Foundation for combining relayauth + relayfile into a local agent sandbox where agents operate under granular, permission-checked file access using relay primitives.

• JWT claim mapping: generate-dev-token.sh now emits workspace_id + agent_name so relayfile accepts relayauth-issued tokens
• Dotfile permissions: .agentignore / .agentreadonly with .gitignore syntax — zero config agent sandboxing
• Relay CLI: relay up, down, provision, shell, scan, run, doctor, mount, status
• Zero-config mode: no relay.yaml needed — agent names discovered from dot filenames
• Specs: full architecture spec + RFC for dotfile permissions model
• Workflows: 3 workflows (111, 112, 113) for JWT mapping, dotfiles, and relay run
• Trajectories: 6 decisions + 1 reflection recorded via trail

Key architecture decisions (from trail)

1. FUSE mount for local enforcement (over kernel sandbox, MCP, LD_PRELOAD)
2. Dotfile permissions for 80% case, relay.yaml for power users
3. OSS (free, local) vs Cloud (paid, distributed) split with @relayauth/core bridging both
4. Cloud/relayauth duplication identified — must import from core instead of copying

Related PRs

• feat: FUSE mount for relayfile VFS with permission enforcement relayfile#13 (FUSE mount)

Test plan

• relay up starts both services locally
• relay provision mints scoped tokens via generate-dev-token.sh
• relay scan shows dotfile permissions
• Workflow 111 completed (JWT claim mapping)
• Workflow 112 completed (dotfile parser + prereqs)
• Workflow 113 (relay run with FUSE) — depends on relayfile FUSE merge
• End-to-end: relay run claude in a project with .agentignore

🤖 Generated with Claude Code

---

[devin-ai-integration]

Devin Review found 3 new potential issues.

View 18 additional findings in Devin Review.

[devin-ai-integration]

🟡 E2E test asserts wildcard scope that the compiler never produces

The verify_compiler_contract function asserts that data.scopes contains "relayfile:fs:read:*" (line 364). However, the compiler (dotfile-compiler.ts:38-40) produces path-specific scopes like "relayfile:fs:read:/README.md" — it never emits wildcard scopes. This assertion will always fail, causing the e2e test to report a false failure.

Prompt for agents

In scripts/relay/e2e-dotfiles.sh, line 364-365, replace the wildcard scope assertion with an assertion that checks for a specific path-based scope that the compiler actually produces. For instance, check that data.scopes contains a scope matching the pattern 'relayfile:fs:read:/README.md' (since README.md is a readable file in the test fixture created at line 274). The compiler at dotfile-compiler.ts:38-40 generates scopes in the format relayfile:fs:{action}:/{relativePath}, so the assertion should check for one of those specific scopes rather than a wildcard.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 E2E test asserts allow:scope:* ACL rule that the compiler never produces

The verify_compiler_contract function at lines 367-373 asserts that the root ACL (/) contains both "deny:agent:test-agent" and "allow:scope:relayfile:fs:read:/*". However, the compiler (dotfile-compiler.ts:76-89) only ever generates deny:agent:* rules for ignored files — it never produces allow:scope:* rules. For readonly files, it simply adds a read scope to the token and omits the write scope, rather than creating ACL allow rules. This assertion will always fail.

Prompt for agents

In scripts/relay/e2e-dotfiles.sh lines 367-378, the test expects the root ACL to contain 'allow:scope:relayfile:fs:read:/*' but the compiler in dotfile-compiler.ts never emits allow:scope rules. The compiler handles readonly files by adding a read scope to the token but NOT adding a write scope (lines 82-85), and only producing deny:agent rules for ignored files (line 78). Update this assertion to match the actual compiler behavior: either check that README.md appears in the scopes list as a read scope but NOT as a write scope, or check that the root ACL does not contain deny rules (since README.md is readonly, not ignored, the root ACL may not have any deny rules related to it).

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 Admin-agent override test wrongly assumes empty per-agent dotfiles clear global restrictions

The verify_admin_override_contract function (lines 381-409) creates empty .admin-agent.agentignore and .admin-agent.agentreadonly files, then asserts that admin-agent has NO ignore/readonly restrictions (lines 388-393). But parseDotfiles (dotfile-parser.ts:51-73) loads global .agentignore patterns first, then layers per-agent patterns on top additively via the ignore library. Empty per-agent files add nothing and do NOT clear the global patterns. So admin-agent will still inherit secrets/ and .env from the global .agentignore and README.md from .agentreadonly. The test will always report a failure at line 396: "admin-agent still inherits global dot-file restrictions".

Prompt for agents

In scripts/relay/e2e-dotfiles.sh lines 381-409, the admin-agent override test is fundamentally incorrect. The parseDotfiles function (dotfile-parser.ts:51-73) adds global patterns first, then per-agent patterns additively. Empty per-agent files do NOT clear global patterns. Either:
1. Change the test to expect that admin-agent STILL inherits global restrictions (the correct behavior given the parser implementation), OR
2. If admin-agent override is a desired feature, update the parser in dotfile-parser.ts to support a convention like a '!' negation line or a special '# clear' directive in per-agent files that clears inherited global patterns, then adjust the test to use that convention.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 19 additional findings in Devin Review.

[devin-ai-integration]

🔴 ACL unit tests completely mismatched with bulk endpoint implementation

The seedAclEntries implementation (packages/core/src/acl.ts:20) sends a single POST to /v1/workspaces/.../fs/bulk with all files, but the test at packages/core/src/__tests__/acl.test.ts was written for a per-entry API that no longer exists. The test asserts calls.length === 2 (line 29), expects pathname /fs/file (line 30), and checks per-entry body structure (line 35-39) — none of which match the bulk implementation. Additionally, the mock returns new Response(null, { status: 200 }) (line 12), but the implementation calls response.json() (packages/core/src/acl.ts:36) on the response, which will throw a JSON parse error on null body, causing the first test to error rather than even reach the assertions. The second test (line 50) expects the regex /failed to seed ACL for \/src: HTTP 500 boom/ but the implementation throws "failed to seed ACLs: HTTP 500 boom" (plural, no path).

Prompt for agents

Rewrite the tests in packages/core/src/__tests__/acl.test.ts to match the bulk endpoint implementation in packages/core/src/acl.ts. The implementation now makes a single POST to /v1/workspaces/{ws}/fs/bulk with body {files: [{path, content, encoding}, ...]}. The mock fetch should return new Response(JSON.stringify({errorCount: 0, errors: []}), {status: 200}) instead of new Response(null, {status: 200}). The first test should assert calls.length === 1, check the pathname is /v1/workspaces/workspace-a/fs/bulk, and verify the body contains a files array with both ACL entries. The second test's regex should match the actual error message 'failed to seed ACLs: HTTP 500 boom' (plural, no per-path info).

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 22 additional findings in Devin Review.

[devin-ai-integration]

🟡 E2E admin-agent compile test asserts wildcard relayfile:fs:write:* scope that compiler never produces

At e2e-dotfiles.sh:405, the test asserts admin-agent scopes contain relayfile:fs:write:*. The compiler (dotfile-compiler.ts:91-92) only adds per-file write scopes like relayfile:fs:write:/src/app.ts, never wildcard relayfile:fs:write:*. This assertion will always fail.

Suggested change

	assert_array_contains "$compile_json" "data.scopes" "relayfile:fs:write:*" \
	"admin-agent retains write scope"
	assert_array_contains "$compile_json" "data.scopes" "relayfile:fs:write:/src/app.ts" \
	"admin-agent retains write scope"

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 3 new potential issues.

View 10 additional findings in Devin Review.

[devin-ai-integration]

🟡 E2E test asserts wildcard scope relayfile:fs:read:* but compiler only produces per-file scopes

The verify_compiler_contract function asserts that data.scopes contains relayfile:fs:read:*, but the compileDotfiles function in scripts/relay/dotfile-compiler.ts:38-41 generates per-file scopes (e.g., relayfile:fs:read:/README.md) via the addScope helper — it never produces wildcard scopes. This causes the assertion to always fail, reporting a false test failure. The same incorrect assertion is repeated at line 405 for admin-agent in verify_admin_override_contract.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🔴 e2e-dotfiles.sh asserts root ACL contains allow:scope rule but compiler never generates allow rules

At line 367-378, the verify_compiler_contract() function checks that root ACL (/) contains both deny:agent:test-agent and allow:scope:relayfile:fs:read:/*. But the compiler at scripts/relay/dotfile-compiler.ts:99-106 only generates deny:agent:X rules for directories where ALL files are ignored. For the root directory /, .env is ignored but other files (like README.md, src/app.ts) are not, so it's a "mixed" directory and gets no ACL rules at all. The compiler never generates allow:scope:* rules anywhere. This assertion will always fail.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 13 additional findings in Devin Review.

[devin-ai-integration]

🔴 Publish workflow publishes @relayauth/core before its dependency @relayauth/sdk

The publish matrix order is ["types","core","sdk","cli"] with max-parallel: 1, so packages publish sequentially as types → core → sdk → cli. However, @relayauth/core declares @relayauth/sdk as a hard dependency (packages/core/package.json:19). When core is published before sdk, any consumer installing @relayauth/core will fail to resolve @relayauth/sdk because it doesn't exist on npm yet. On the very first publish this is guaranteed to fail since no prior version of @relayauth/sdk exists. The correct order should be types,sdk,core,cli.

Suggested change

	echo "list=types,core,sdk,cli" >> "$GITHUB_OUTPUT"
	echo 'matrix=["types","core","sdk","cli"]' >> "$GITHUB_OUTPUT"
	echo "list=types,sdk,core,cli" >> "$GITHUB_OUTPUT"
	echo 'matrix=["types","sdk","core","cli"]' >> "$GITHUB_OUTPUT"

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 18 additional findings in Devin Review.

[devin-ai-integration]

🔴 generate-dev-token.sh missing workspace_id and agent_name JWT claims despite relay.sh setting RELAYAUTH_AGENT_NAME

The relay.sh provisioning flow sets RELAYAUTH_AGENT_NAME at line 662 when calling generate-dev-token.sh, but the token script never reads this env var and never includes workspace_id or agent_name in the JWT payload (line 17). The design doc (docs/auth-changes-plan.md) explicitly specifies these fields should be added, and test-helpers.ts:127-128 correctly includes them. As a result, tokens generated by the relay CLI for actual agent provisioning are missing these claims, which relayfile's auth.go expects for agent identification. This breaks the core cross-service compatibility that this PR is designed to establish.

Prompt for agents

In scripts/generate-dev-token.sh, add an agent_name variable after the workspace variable (around line 10), reading from RELAYAUTH_AGENT_NAME env var with a default of the subject:

  agent_name="${RELAYAUTH_AGENT_NAME:-${subject}}"

Then on line 17, update the payload JSON string to include workspace_id and agent_name claims. Insert after the wks field:

  "workspace_id":"${workspace}","agent_name":"${agent_name}",

The final payload line should look like:
  payload="{\"sub\":\"${subject}\",\"org\":\"${org}\",\"wks\":\"${workspace}\",\"workspace_id\":\"${workspace}\",\"agent_name\":\"${agent_name}\",\"scopes\":${scopes_json},\"sponsorId\":\"${sponsor}\",\"sponsorChain\":[\"${sponsor}\"],\"token_type\":\"${token_type}\",\"iss\":\"${issuer}\",\"aud\":${audience_json},\"iat\":${now},\"exp\":${exp},\"jti\":\"${jti}\"}"

---

Was this helpful? React with 👍 or 👎 to provide feedback.