feat(auth): add scoped API keys for Astra

[loveRhythm1990]

What type of PR is this?

• feat (new feature)
• fix (bug fix)
• docs (documentation)
• style (formatting, no code change)
• refactor (code change that neither fixes a bug nor adds a feature)
• perf (performance improvement)
• test (adding or updating tests)
• chore (maintenance, tooling)
• build / ci (build or CI changes)

Which issue(s) this PR fixes

Related: #245

This reference intentionally does not automatically close the cross-repository issue.

What this PR does / why we need it

Provide reusable, least-privilege credentials for Astra account sign-in and optional memory sharing.

• Add API-key scopes and stable GET /auth/whoami identity metadata.

• Enforce identity/read/write/key-management scopes across REST and MCP.

• Prevent identity-only/read-only/read-write connection keys from administering groups, managing keys, or reaching unclassified authenticated routes.

• Preserve scopes during rotation and maintain explicit compatibility for legacy/default keys.

• Reject unauthorized memory access before per-user memory provisioning.

• Make whoami verify the current database grant rather than trust a warm replica-local cache, so login/refresh observes revocation made through another API replica.

• Decouple MCP authorization from metrics invalidation. Explicitly require memory:write for memory_apply, memory_rebuild_index and memory_tune_params.

• Classify exact dispatch names rather than sanitized tracking labels; reject unclassified tools by default, including with master credentials.

• Apply the same admission to requests and notifications, with real HTTP/database regression coverage.

Verification

Latest MCP review-fix update (58744ff)

• cargo test --locked -p memoria-api --lib: 93 passed.
• cargo test --locked -p memoria-api --test api_e2e test_scoped_ -- --nocapture: 3 passed.
• cargo test --locked -p memoria-api --test api_e2e test_mcp_ -- --nocapture: 16 passed.
• HTTP tests used isolated local MatrixOne databases. The new regression checks all three missed write tools, notification handling, write-authorized positive controls, readable tools, identity-only denial and unknown/malformed names.
• Persisted-state assertions confirm denied requests/notifications do not tune retrieval parameters, while the same write-authorized operation does.
• Targeted Rust formatting and git diff --check: passed.
• No user test data was cleared or local Memoria service replaced.

Previously recorded verification

Local validation before push:

• Memoria API compile checks and targeted auth/MCP scope unit tests passed.
• Real-database scoped-key API tests passed, including group-administration denial and uncached whoami revocation.
• Seven legacy API-key regression tests passed.
• Astra-to-real-Memoria API v1 contract passed for identity-only, read-only, read-write, master-key rejection, stable account identity and revocation.
• Latest upstream main was merged; its intervening changes have no net source-tree delta relative to the tested Memoria implementation.
• git diff --check passed.

Production OAuth and GitOps deployment are not covered by these API tests.

Cross-repository dependencies

• Astra login, scoped credential lifecycle and user models: feat(auth): connect Memoria identity and scoped memory Astra#704
• Website follow-up (login separated from memory sharing and local testing): https://github.com/matrixorigin/memoria-website/pull/216
• Initial website integration, already merged: https://github.com/matrixorigin/memoria-website/pull/213

No MatrixOne source changes are included.

[aptend]

Request changes for two authorization lifecycle issues:

1. [P1] Denied MCP calls still provision per-user storage. The handler records tool usage before evaluating authorization_error, and the denial paths enqueue per-user call-log entries. In multi-DB mode both batchers later call user_sql_store, which provisions a missing personal memory database. An identity-only key can therefore call a forbidden tool such as memory_store, receive -32003, and still cause its memory DB to be created at the next flush or shutdown. The group guard also performs storage work before the authorization error is returned. Please complete scope admission before any per-user instrumentation/storage access, or persist denied-call telemetry in the shared auth store, and add a real-DB assertion that an identity-only denied request leaves no user database/registry row.

2. [P1] Cached keys remain usable after expires_at. Non-whoami validation returns a cached principal before consulting the database, while CachedApiKeyPrincipal does not carry the key expiry and the cache TTL is 300 seconds. A key warmed shortly before expiration can therefore continue reading or writing through REST/MCP for up to five minutes after its database expiry. Please carry/check expires_at on cache hits (or cap cache lifetime to it) and add a regression covering warm cache -> expiry -> REST and MCP authentication failure.

[gouhongshen]

Re-reviewed the latest head. No remaining P0/P1 findings. MCP tool authorization is now explicit and fail-closed, including write tools, and all required checks are green. Approving.

[aptend]

Re-reviewed 40f7dbd. The two previously blocking authorization lifecycle issues are resolved: cached principals now enforce absolute key expiry, and denied or identity-only MCP traffic is admitted before any per-user telemetry or storage provisioning. The new unit and real-database regressions cover REST/MCP expiry, notifications, flush/shutdown behavior, headers, and group storage lookup. Local memoria-api library tests passed (96/96), and the current Check & Clippy, Unit Tests, and DB Tests are green. No remaining P0/P1 findings.