feat(auth): add scoped API keys for Astra (#244)

## What type of PR is this?

- [x] feat (new feature)
- [x] 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)
- [x] 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:
matrixorigin/Astra#704
- Website follow-up (login separated from memory sharing and local
testing): matrixorigin/memoria-website#216
- Initial website integration, already merged:
matrixorigin/memoria-website#213

No MatrixOne source changes are included.

Author: loveRhythm1990

docs/per-user-database-architecture.md

@@ -107,6 +107,14 @@ per-user DB 放两类数据：
 
 注意：这些“用户级控制元数据”虽然在用户库里，但它们不是 rollback 的业务恢复目标；它们要保持当前态，否则会出现 branch / snapshot 注册表与底层事实不一致。
 
+### 3.4 鉴权与首次建库的边界
+
+API Key 校验只依赖 shared DB。缓存命中仍须检查 Key 的 `expires_at`（UTC）；缓存 TTL 不能延长 Key 的有效期。无到期时间的 Key 继续遵守正常缓存 TTL。
+
+MCP 的工具权限检查必须先于群组存储访问、工具使用统计和个人调用日志入队。因 scope 不足而拒绝的请求（包括 notification），以及格式错误的请求，不得为了记录拒绝而创建个人记忆库。这些事件保留在运行日志中，并在启用 shared stats reporter 时计入共享汇总统计。
+
+仅有 `identity:read` 的 Key 调用身份或 MCP 元数据接口时，也不写入可能触发建库的个人统计；即使带有 `X-Memoria-Tool` 或 `X-Tool-Name` Header，行为不变。获准的记忆工具调用仍正常记录使用情况，并可按原有流程首次建库。以上边界不需要新增表或数据库迁移。
+
 ---
 
 ## 4. 最终实现选择：global user pool + qualified tables