feat: add permission-bound Agent Keys for Google APIs

[ctkm-aelf]

Summary

Google OAuth grants are too broad to express permissions such as “read files only inside this Drive folder” or “update only these spreadsheet cells.” This backend pilot adds permission-bound Agent Keys that enforce an immutable NyxID policy before forwarding a request with the owner's Google credential.

• Add a shared nyxid-permissions evaluator, dedicated native REST/MCP execution, and first-party key creation/read/pause/revoke endpoints. Keys retain the opaque nyxid_ag_ format and bind one personal connection, credential identity/epoch, execution configuration, expiry, and live policy revision. Ordinary proxy/MCP, credential overrides, key scope updates, and rotation cannot bypass the policy.
• Provide a Drive folder adapter with fresh ancestry checks and declarative Google REST operation rules: exact origins, methods, resource IDs, query constraints, and closed nested JSON body schemas. Examples cover all six Workspace products plus Cloud Resource Manager, YouTube, and Gemini. Before/after hooks, live pause/revocation, and existing approvals, billing, rate limits, and audit apply to execution.
• Add a standalone Drive POC, deterministic fixtures, backend integration tests, documentation, a required Google Permissions CI job, and workspace/Docker build inputs. Preserve the current proxy resolution/execution split and upstream organization-agent safeguards when integrating with main.

Scope and rollout

This is an experimental backend API; there is no policy editor UI or dedicated CLI command. One Workspace connection can cover Drive, Gmail, Calendar, Docs, Sheets, and Slides. Independent account/service connections need separate keys. Additional Google REST APIs require configured catalog connections, suitable credentials, and explicit rules; this does not automatically expand Google OAuth consent or catalog access.

Generic policies constrain request inputs and JSON response format. Drive folder ancestry is a separate boundary; generic rules do not automatically implement Gmail label-membership checks or equivalent containment for other services. Streaming, gRPC, multipart/binary generic calls, nodes, platform/master credentials, pools, and organization connections are outside the pilot. Google can move a file between ancestry verification and dispatch. Hooks can withhold a completed write's response but cannot undo the write, and uncertain writes are never automatically replayed.

Upgrade all backend replicas before issuing permission_bound keys or generic Google policies; older replicas cannot deserialize the new purpose/resource type. No deployment or live Google trial is included.

Docs: Google API permissions, native key lifecycle, Drive POC.

Test Plan

Validated on PR head c5f854bb after integrating main at 53318994. Full CI run, CodeQL, and release planning passed. The focused native/authentication test counts below were also verified locally on the earlier integration head ab95d64f:

• Shared evaluator: 52 tests covering Drive ancestry, Google rules, hooks, transport pinning, and REST/MCP parity.
• Native permission tests: 12 passed against a MongoDB 8 replica set.
• Existing authentication tests: 112 passed; billing route coverage smoke passed.
• Standalone Drive executable: all 21 checks passed with in-memory resources.
• Formatting, Clippy for backend/shared crate with warnings denied, and PR diff whitespace checks passed.
• Reusable workflow permission check, CI resource helper tests, and Docker embed guard self-test passed.
• Full repository CI: backend and CLI tests, frontend/mobile/SDK checks, all KMS feature builds, coverage, CodeQL, and release plan/integrity manifest passed.
• Production backend release build and Docker input validation passed. Machine Container E2E passed sandbox/isolation, saved-login/desktop, updater migration/rollback, and read-only production updater checks.
• Fixed the updater Dockerfile to stage the new permissions workspace member. Local Cargo metadata succeeds with the staged inputs; removing the added COPY reproduces the original CI failure. All four Rust image builders stage every workspace manifest.
• Live Google account trial: not performed; service examples are deterministic fixtures.

Checklist

• Code follows the handler/service/model architecture.
• No real secrets or credentials added; tests use synthetic credentials.
• Permission errors and audit records do not expose credential material.
• Documentation covers API usage, support boundaries, hooks, limits, and rollout.

[github-actions]

📊 Code coverage

Component	Lines	Threshold	Status	Δ vs base
Backend (nyxid)	87.02%	73%	✅	🔻 -0.04
CLI (nyxid-cli)	69.26%	64%	✅	— 0.00
Frontend (vitest)	72.20%	15%	✅	🔻 -0.01

Gate: line coverage must stay at or above the threshold. Ratchet plan (W21): Backend → 55%, CLI → 50%, Frontend → 30% by quarter end.