Skip to content

perf(gateway): hash each account token with PBKDF2 once per process - #264

Merged
Telli merged 2 commits into
mainfrom
perf/cache-verified-account-tokens
Sep 29, 2026
Merged

Telli merged 2 commits into
mainfrom
perf/cache-verified-account-tokens

Conversation

@Telli

@Telli Telli commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

Description

Every request that carries an account token runs OperatorAccountService.TryAuthenticateToken, which:

  • runs PBKDF2 (120,000 iterations, about 18 ms of CPU measured locally);
  • holds the service's global lock while it does, so every account-token request, login, and account change in the gateway queues behind it;
  • then rewrites admin/operator-accounts.json to record lastLoginAtUtc.

That caps account-token throughput for the whole gateway at roughly 50 requests per second on one core, whatever the hardware. #261 removes the second verification per request that #256 added; this PR removes the per-request cost itself.

Summary

  • Verified-token cache. After a token's first successful PBKDF2 check, the service remembers its SHA-256 digest with the account and token ids. Later uses skip PBKDF2. Account tokens are 192-bit random secrets, so a fast digest identifies one safely; PBKDF2 protects low-entropy secrets like passwords, which are unaffected.
  • No invalidation to get wrong. A cached use still looks up the current account and token record and re-checks revocation, expiry, the account's enabled state, and its role. Revoking, disabling, deleting, or demoting takes effect on the next request, as before. A failed re-check drops the entry.
  • Last login throttled. Token use updates lastLoginAtUtc at most once a minute instead of rewriting the accounts file on every request. Password logins and token exchange still record every login.
  • Test seams. The constructor takes an optional TimeProvider and hash function; production passes neither.

Benchmarks

200 sequential verifications of one token on the same machine (temporary benchmark, not committed):

Per verification
Before 18.1 ms
After 0.001 ms

The first use of each token per process still pays for PBKDF2.

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • Tests

Validation

  • dotnet build OpenClaw.Net.slnx --configuration Release: 0 warnings, 0 errors
  • dotnet test OpenClaw.Net.slnx --configuration Release --no-build: OpenClaw.Tests 3,130 passed / 11 skipped / 0 failed; NacosLiveAcceptance 25 passed; LayaService 67 passed
  • dotnet run --project samples/OpenClaw.HelloAgent -c Release --no-build

New tests in OperatorAccountServiceTests:

  • Two failed first for the right reason: the second use hashed the token again, and the second use within a minute rewrote the persisted lastLoginAtUtc.
  • Guards: a cached token is rejected after revoke, expiry, disabling, or deleting the account; a role change is reflected at once; a different token with the same prefix is rejected; last login still advances after the interval.

Review Notes

  • I considered NativeAOT compatibility (no reflection or new serialization)
  • I considered security posture and unsafe defaults. The cache stores digests of already-verified tokens, never the tokens, and re-checks their state on every use. It only changes how verified tokens are recognized, so it needs core maintainer review.
  • I updated docs/tests where needed (CHANGELOG.md)
  • This PR is scoped and does not mix unrelated changes

Commercial or Customer-Driven Contribution Disclosure

Found while reviewing the #256 role checks for AgentQi Mobile, which polls the gateway with an account token. Vendor-neutral gateway performance fix.

Checklist

  • I have read the CONTRIBUTING guidelines
  • My code follows the code style implementation of this project
  • I have added tests that prove my fix is effective or that my feature works
  • All new and existing tests passed locally (dotnet test)
  • I have updated the documentation (README.md, comments) if required
  • I have checked for security implications (input validation, authorization)
  • I have checked the relevant maintainer review checklist
  • I have disclosed whether this directly supports a company or customer use case

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Performance
    • Repeat account-token sign-ins are faster after the first use.
  • Security
    • Tokens are rechecked for revocation and expiry, and accounts for enabled status and current role. Invalid tokens and tokens for disabled or deleted accounts are rejected.
  • Account Activity
    • Token sign-ins update the last-login time no more than once per minute.
  • Documentation
    • Updated the security changelog with account-token verification details.

Every account-token request ran PBKDF2 (120,000 iterations, about 18 ms)
inside OperatorAccountService's global lock and then rewrote the
accounts file, capping gateway-wide account-token throughput.

After a token's first successful verification, later uses find it by
SHA-256 digest (the tokens are 192-bit random secrets) and skip PBKDF2.
Each use still re-checks the token's revocation and expiry and the
account's enabled state and role, so none of those needs cache
invalidation. Token use now updates lastLoginAtUtc at most once a
minute instead of on every request.

The service takes an optional TimeProvider and hash function so tests
can control time and count hashes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings September 28, 2026 23:10

Copilot AI 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.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@coderabbitai

coderabbitai Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 0daacc42-ccd3-46a4-9141-34f2b0c70263

📥 Commits

Reviewing files that changed from the base of the PR and between f6bb6c1 and 9e8143f.

📒 Files selected for processing (2)
  • src/OpenClaw.Gateway/OperatorAccountService.cs
  • src/OpenClaw.Tests/OperatorAccountServiceTests.cs

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.


📝 Walkthrough

Walkthrough

The operator account service now supports injected time and secret hashing. It caches verified token digests, rechecks authorization state on each use, and limits last-login persistence to once per minute.

Changes

Operator token authentication

Layer / File(s) Summary
Service dependencies and timestamps
src/OpenClaw.Gateway/OperatorAccountService.cs
The service accepts optional clock and hashing dependencies. Account and token timestamps use the injected clock, and secret hashing uses the injected function.
Cached token verification and login persistence
src/OpenClaw.Gateway/OperatorAccountService.cs, src/OpenClaw.Tests/OperatorAccountServiceTests.cs, CHANGELOG.md
Token authentication caches verified token digests and rechecks account and token usability on each use. It persists last-login time no more than once per minute. Tests cover cache reuse, authorization changes, token expiry and revocation, and login persistence timing.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 9e814

No unresolved issue identified here prevents merging after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 9e814

Cached token checks still consult the current account and token records before granting access. No new authorization bypass was established, but the change reduces the precision of recorded token activity, and some deployment and request-transport details remain unverified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The changed verification behavior affects requests authorized with operator account tokens, including the identity and role passed to gateway operator authorization; it does not make the digest alone an authorization decision.

Trust Boundaries and Controls

  • observed — A request-supplied token reaches the service through the gateway’s token extraction and allowed-mode check. Successful first use requires matching a usable stored token’s secret hash; subsequent uses recheck the referenced account and token.

Resilience and Maintainability Implications

  • observed — Within one service instance, authentication and account mutations use the same lock, ordering a cached check against revocation and account changes. That lock does not establish coordination between separate processes.

Hardening Proposals

  • proposed — If deployments can share an account file across gateway processes or external writers, define single-writer ownership or a reload and coordination mechanism before relying on immediate cross-process revocation visibility.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 8.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 35 functions across 2 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely identifies the primary change: reducing PBKDF2 hashing to once per account token per gateway process.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR

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

Comment @coderabbitai help to get the list of available commands.

Comment thread src/OpenClaw.Tests/OperatorAccountServiceTests.cs
Comment thread src/OpenClaw.Tests/OperatorAccountServiceTests.cs
Comment thread src/OpenClaw.Tests/OperatorAccountServiceTests.cs
… saved

The last-login throttle set the in-memory timestamp before saving. If the
save failed, that request threw, but the next minute of requests saw a
recent timestamp, skipped the write, and authenticated without recording
the login. Restore the previous timestamp when the save fails, so every
request keeps trying, as before the throttle.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@Telli

Telli commented Sep 29, 2026

Copy link
Copy Markdown
Contributor Author

Addressed the retained concern from the CodeRabbit security review in 9e8143f: the last-login timestamp now counts toward the one-minute interval only after it is saved. If the save fails, the previous timestamp is restored, so the next request tries again (and fails the same way) instead of skipping the write. TryAuthenticateToken_WhenLastLoginWriteFails_TriesAgainOnTheNextRequest failed before the change.

Assert.True(accounts.TryAuthenticateToken(token.Token, out _));
_clock.Now = _clock.Now.AddMinutes(2);

var adminDirectory = Path.Combine(_storagePath, "admin");

private static bool DirectoryIsWritable(string directory)
{
var probe = Path.Combine(directory, $".probe-{Guid.NewGuid():N}");
@Telli
Telli merged commit 114ac05 into main Sep 29, 2026
21 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.

2 participants