fix(docs): #10 rename JWT terminology — phase 1 (3 wiki files) by hanwencheng · Pull Request #23 · litentry/agentKeys

hanwencheng · 2026-04-14T06:20:39Z

Summary

Partial fix for #10 (docs-only rename). Covers 3 highest-traffic wiki files that consistently described the 30-day AgentKeys auth bearer as a "JWT" — misleading because it implies disposable/short-lived when in fact it's a long-lived high-security credential.

Reductions

File	Before	After
`wiki/data-classification.md`	15	5
`wiki/key-security.md`	8	3
`wiki/blockchain-tee-architecture.md`	36	16

Remaining occurrences are legitimate JWT-format references ("signed JWT", "JWT claims", etc.) where the format itself is being discussed, not the product-level bearer name.

Remaining work (follow-up PR)

wiki/session-token.md (14 occurrences): already has a dedicated "Why we don't call it JWT" section — most occurrences are intentional for rhetorical contrast. Will be reviewed separately.
docs/spec/ files (13 total): spec-level, less load-bearing; separate PR to keep this one focused.
Heima-side rename (coordinate with Kai) — not in agentkeys scope.

Test plan

No code changes; cargo check --workspace unaffected.
Docs still render correctly (markdown tables + code fences preserved).
Claude reviewer / Codex: docs-only; deferred to PR review.

Issue

Partially closes #10 (3/10 files). Remaining 7 files tracked as a follow-up.

🤖 Generated with Claude Code

Codex reviewer: approved (4 rounds — accepted human policy override: 30-day TTL uniformly across master + sandbox per wiki/session-token.md)

Codex review (2026-04-14, 4 rounds): Accepted human policy override — 30-day TTL uniformly across master + sandbox/agent per wiki/session-token.md:17.

v1 → codex suggested split (master 30d, sandbox 1-24h); v2 applied split.
Human override → keep 30d for both (shortening agent TTL is a future D-in-D tweak, out of scope here).
v3 (commit afd253f) reverted split + aligned mock-server TTL constants + docs/spec/1-step-analysis.md + wiki/session-token.md default.
v4 (commit 1e30804) aligned the last 2 let ttl = 3600u64 in approve_auth_request (Pair + Recover branches) to 30 days.

51+ tests green. Codex re-review: 30-day policy is now enforced consistently.

Partial fix for #10. Covers the 3 highest-traffic wiki files: - wiki/data-classification.md: 15 → 5 JWT mentions (remaining are legit JWT-format references with context). - wiki/key-security.md: 8 → 3. - wiki/blockchain-tee-architecture.md: 36 → 16. Remaining work tracked as follow-up: - wiki/session-token.md (14 mentions, mostly in the existing "why we don't call it JWT" section — keep as-is for rhetorical contrast). - docs/contradictions.md §1.2 (terminology contradiction): already marked RESOLVED in earlier commit (TTL/storage/terminology/pair-transport pass). - docs/spec/1-step-analysis.md (5), tech-brief.md (2), heima-open-questions.md (1), heima-cli-exploration.md (1), aiosandbox/agent-infra-sandbox-analysis.md (4): these are spec-level and mostly internal; separate PR. No code changes. Heima-side rename (coordinate with Kai) still separate. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

hanwencheng · 2026-04-14T07:46:10Z

Codex review (via gstack /codex skill, GPT-5.4 codex-high/medium reasoning against origin/main)

Verdict

I found one documentation accuracy issue: the edited threat-model row now applies the 30-day master-token TTL to the combined laptop/sandbox compromise case, even though sandbox child sessions are documented and implemented as shorter-lived. Aside from that docs inconsistency, the patch does not appear to break code or tests.

Review comment:

[P2] Split sandbox compromise TTL from 30-day master token — wiki/data-classification.md:214-214
When the compromised client is a sandbox daemon rather than the master CLI, the ~30 days blast radius here is inaccurate: the repo still models agent/child sessions as short-lived (3600u64 in crates/agentkeys-mock-server/src/handlers/session.rs, and docs/spec/1-step-analysis.md says 4h default/up to 24h). Because this row explicitly covers laptop/sandbox, readers will conclude an agent compromise yields 30-day access, which conflicts with the rest of the threat model; please either split master vs sandbox cases or qualify that the 30-day TTL only applies to the master bearer token.

— codex review --base main. Docs-only phase-1 rename.

Codex P2: threat-model row covering 'laptop/sandbox' client compromise claimed ~30-day impersonation window. That's only correct for the master CLI bearer; sandbox daemon agent/child sessions are short-lived (1–24h, 4h default). Row now splits TTL by client type. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

hanwencheng · 2026-04-14T08:16:06Z

Codex re-review v2 — ✅ APPROVED

The patch only updates documentation terminology from JWT/auth-token wording to session-token wording and the changes appear internally consistent. I did not find a discrete, actionable correctness issue that would warrant blocking or follow-up.

The 30-day TTL qualification landed in commit 449ee90 resolved the prior P2 finding.

…ion-token.md User directive: keep 30-day TTL consistently across the project (shortening agent sessions is a possible future defense-in-depth tweak, but for now uniform with master per the canonical policy in wiki/session-token.md). Reverts the split-by-client-type threat-model row from v2 — now 30 days applies to both master and sandbox/agent cases, matching the wiki declaration. Code alignment (mock server): - handlers/session.rs: introduce DEFAULT_SESSION_TTL_SECONDS const (30 days); replace 3 × 86400u64 + 1 × 3600u64 magic numbers. - test_client.rs: 3 × 86400/3600 → 2_592_000 (30 days). Doc alignment: - wiki/session-token.md:244 — mock default 86400s → 2_592_000s (30 days). - docs/spec/1-step-analysis.md:124 — master auth token "15 min – 24 h" → 30-day canonical policy. - docs/spec/1-step-analysis.md:784 — master session TTL same. - docs/spec/1-step-analysis.md:787 — agent session TTL "4h default, up to 24h" → 30 days (same as master). - wiki/data-classification.md:214 — threat-model row restored to single ~30-day TTL claim. 51 tests across cli + mock-server crates all pass. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

hanwencheng · 2026-04-14T09:26:22Z

Correction after human review — TTL policy: 30 days everywhere

Codex v1 suggested splitting master (~30d) from sandbox/agent (~1-24h) TTLs. On human review we're keeping 30 days consistently across master CLI and agent/sandbox sessions per the canonical policy in wiki/session-token.md:17: "A bearer token ... issued to a client (master CLI or agent daemon) upon successful authentication. AgentKeys policy: 30-day TTL."

Shortening agent session TTLs is a valid future defense-in-depth tweak but is out of scope for this rename PR.

New commit afd253f reverts the v2 threat-model split and aligns the rest of the project to the 30-day policy:

Code (mock server): new DEFAULT_SESSION_TTL_SECONDS const = 30 days; replaces 4 × magic 86400u64 / 3600u64 in handlers/session.rs; test_client.rs defaults bumped from 86400/3600 → 2_592_000.
Docs: docs/spec/1-step-analysis.md (3 rows), wiki/session-token.md:244, wiki/data-classification.md:214 — all now claim 30 days uniformly.

51 tests (cli + mock-server) green.

Re-review fired.

…0 days too Codex v3 caught one more TTL inconsistency: approve_auth_request mints child sessions with ttl = 3600u64 (1 hour) on both the Pair and Recover branches. That contradicts the 30-day canonical policy now documented throughout the project. Both `let ttl = 3600u64` sites bumped to 2_592_000 (30 days) with inline comment referencing wiki/session-token.md. 37 mock-server tests green. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Rebase of fix/issue-12 onto current main (post-PR #18 #19 #21 #23 merges) surfaced two concrete integration issues, fixed in this patch: **1. Expose session_store helpers for test reuse** - Make `agentkeys_core::session_store::fallback_path(session_id)` public so CLI tests can assert on the on-disk path layout. - Re-export `agentkeys_core::session_store` at `agentkeys_cli::session_store` so existing test imports (`use agentkeys_cli::session_store;`) keep working after the old cli-local `session_store.rs` was deleted upstream. **2. cmd_revoke clear_session calls (post-PR #18 self-revoke merge)** PR #18 added `session_store::clear_session()` calls on self-revoke paths. The new signature takes `session_id`, not 0 args. Pass `&ctx.session_id` so the revoke wipes the correct namespace for any future multi-session CLI caller. **3. Integration tests: seed identity_links for Recover** PR #21 tightened `resolve_identity_typed` to require the identity to exist in `identity_links` before resolution. Two pair_tests (`recover_full_loop`, `recover_credentials_intact`) opened Recover requests with aliases that were never linked, so they now 404. Added `InProcessBackend::link_identity_for_tests(identity_type, identity_value, wallet)` that inserts directly into the mock DB's `identity_links` table. The two failing tests now seed the alias link before the Recover flow. Test: cargo test -p agentkeys-core -p agentkeys-daemon -p agentkeys-cli -p agentkeys-mock-server -- --test-threads=1 core: 21; daemon: 13 + 15; cli: 30; mock-server: 56 — all passing Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

hanwencheng mentioned this pull request Apr 14, 2026

fix(docs): #10 phase 2 — complete JWT rename in remaining spec files #28

Closed

1 task

hanwencheng merged commit 47edb0b into main Apr 14, 2026

This was referenced Apr 15, 2026

fix(daemon): #14 --parent flag to bind pair requests to a specific master #22

Merged

fix(cli): #15 part 3 (fix-15b) — agentkeys scope command #29

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(docs): #10 rename JWT terminology — phase 1 (3 wiki files)#23

fix(docs): #10 rename JWT terminology — phase 1 (3 wiki files)#23
hanwencheng merged 4 commits into
mainfrom
fix/issue-10

hanwencheng commented Apr 14, 2026 •

edited

Loading

Uh oh!

hanwencheng commented Apr 14, 2026

Uh oh!

hanwencheng commented Apr 14, 2026

Uh oh!

hanwencheng commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

hanwencheng commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Reductions

Remaining work (follow-up PR)

Test plan

Issue

Uh oh!

hanwencheng commented Apr 14, 2026

Verdict

Uh oh!

hanwencheng commented Apr 14, 2026

Uh oh!

hanwencheng commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

hanwencheng commented Apr 14, 2026 •

edited

Loading