Document OAuth plugin DOX
Alessandro committed
Jun 1, 2026 at 14:56 UTC
57bd9481cc098e88bb354733b619c1b2503d818a
1 file changed
+59
plugins/_oauth/AGENTS.md
new
+59
@@ -0,0 +1,59 @@
1
+# OAuth Plugin DOX
2
+
3
+## Purpose
4
+
5
+- Own account-backed OAuth model-provider connections for Agent Zero.
6
+- Provide local OpenAI-compatible proxy endpoints for connectable account providers.
7
+- Keep provider-specific OAuth behavior inside this plugin, not in core model code.
8
+- Preserve Codex/ChatGPT compatibility while allowing additional providers through the provider registry.
9
+
10
+## Ownership
11
+
12
+- `plugin.yaml`, `default_config.yaml`, and `README.md` own the plugin manifest, settings defaults, and user-facing connection notes.
13
+- `conf/model_providers.yaml` owns OAuth-backed model provider definitions and their `api_key_mode: oauth` metadata.
14
+- `api/` owns provider-aware settings modal endpoints such as status, login start, polling, manual callback, models, and disconnect.
15
+- `helpers/providers/` owns provider implementations, provider metadata, registry wiring, token storage helpers, and provider-specific endpoint validation.
16
+- `helpers/routes.py` owns local OAuth callback and OpenAI-compatible proxy routes mounted by the route bootstrap extension.
17
+- `webui/config.html` and `webui/oauth-config-store.js` own the OAuth Connections settings UI.
18
+- `extensions/python/_functions/models/get_api_key/end/` owns the dummy API-key extension used by OAuth model providers.
19
+- `tests/test_oauth_*.py` own provider contract, security, static UI, and compatibility regressions.
20
+
21
+## Local Contracts
22
+
23
+- Core model code such as `models.py` must stay provider-agnostic. Do not add Codex, GitHub Copilot, Gemini, xAI, or other OAuth provider knowledge outside plugin-owned config or plugin hooks.
24
+- Add OAuth model providers in `_oauth/conf/model_providers.yaml`, not `_model_config/provider_metadata.yaml`.
25
+- Provider cards and model slot actions must be driven by backend provider status. Do not reintroduce hardcoded frontend provider lists or fallback provider catalogs.
26
+- `helpers/providers/registry.py` is the source of truth for connectable OAuth providers.
27
+- Usage-plan metadata belongs only to connectable providers. Do not add metadata-only subscription families for providers this plugin cannot connect.
28
+- API handlers should remain provider-aware. Missing or blank `provider_id` defaults to Codex only for existing backward compatibility; falsey non-string IDs must not silently default.
29
+- Codex success contracts must preserve legacy fields such as `account_id` while allowing newer fields such as `account_label`.
30
+- Do not modify Codex chat-to-responses multimodal conversion without preserving the image/text regression coverage in `tests/test_oauth_codex.py`.
31
+- Token files are password-equivalent credentials. Store them under plugin-owned `usr/plugins/_oauth/<provider>/auth.json` paths with private permissions, and do not share rotating refresh-token files with external CLIs.
32
+- Stored upstream base URLs and OAuth token endpoints must be validated against provider-owned allowlists before sending bearer or refresh tokens.
33
+- Browser callback providers must support manual callback paste when the browser cannot reach the local callback route.
34
+- Local proxy routes must remain loopback or token protected and must not add broad CORS access.
35
+
36
+## Work Guidance
37
+
38
+- When adding a connectable provider, add the provider class, registry entry, model-provider config, default settings, route registration, UI support when needed, tests, and README/DOX updates together.
39
+- Keep provider classes explicit about their auth endpoints, scopes, refresh behavior, and safe API hosts.
40
+- Use shared helpers only for duplicated mechanics such as callback parsing, attempt lookup, model-list parsing, and JSON/error helpers.
41
+- Keep provider policy visible in each provider module; avoid abstracting away endpoint validation or billing/quota caveats.
42
+- Prefer plugin-local imports such as `plugins._oauth.helpers...` for bundled plugin code.
43
+- Keep `_oauth` account providers separate from API-key providers in core configuration.
44
+- Treat Gemini API OAuth as a Google Cloud OAuth-client flow. Do not conflate it with Antigravity, Gemini Code Assist, Gemini CLI, Google AI Pro, or Google AI Ultra subscription quota.
45
+- Treat Claude Code subscription auth and Antigravity product auth as non-connectable unless their vendors provide an explicit third-party provider contract.
46
+- Keep user-facing errors safe: report setup or tier restrictions without exposing tokens, callback secrets, or raw auth payloads.
47
+
48
+## Verification
49
+
50
+- Run `pytest tests/test_oauth_*.py` after backend provider, route, token, or UI contract changes.
51
+- Run `pytest tests/test_plugin_scan_prompt.py` after plugin structure, extension, or docs changes.
52
+- Run onboarding or model-config tests when provider metadata, `api_key_mode`, or model-provider config changes.
53
+- Run `git diff --check` before committing.
54
+- For security-sensitive changes, include regressions that prove bearer tokens are not sent to malicious stored endpoints.
55
+- For Codex changes, include `tests/test_oauth_codex.py` and preserve `account_id` and multimodal image bridge regressions.
56
+
57
+## Child DOX Index
58
+
59
+No child DOX files.