107 lines
2.8 KiB
Markdown
107 lines
2.8 KiB
Markdown
# Phase-7 Public Access Layer
|
|
|
|
## Scope
|
|
- Public discovery endpoint: `GET /v1/agents/public`
|
|
- Entitlements check in gateway before router call
|
|
- Rate limits in gateway for:
|
|
- `user_global`
|
|
- `user_agent`
|
|
- `group_agent`
|
|
|
|
## Data Model
|
|
Migration: `migrations/056_agent_access_policies.sql`
|
|
|
|
Tables:
|
|
- `agent_access_policies`
|
|
- `agent_allowlist`
|
|
|
|
## Gateway Env
|
|
- `GATEWAY_PUBLIC_ACCESS_ENABLED=true`
|
|
- `GATEWAY_ACCESS_POLICY_CACHE_TTL_SECONDS=60`
|
|
- `GATEWAY_ALLOWLIST_CACHE_TTL_SECONDS=30`
|
|
- `GATEWAY_ACCESS_DB_TIMEOUT_MS=40`
|
|
- `GATEWAY_ACCESS_DENY_COOLDOWN_SECONDS=30`
|
|
- `GATEWAY_RL_USER_GLOBAL_LIMIT=60`
|
|
- `GATEWAY_RL_USER_GLOBAL_WINDOW_SECONDS=300`
|
|
- `GATEWAY_RL_USER_AGENT_LIMIT=20`
|
|
- `GATEWAY_RL_USER_AGENT_WINDOW_SECONDS=300`
|
|
- `GATEWAY_RL_GROUP_AGENT_LIMIT=10`
|
|
- `GATEWAY_RL_GROUP_AGENT_WINDOW_SECONDS=300`
|
|
|
|
## Public Discovery
|
|
```bash
|
|
curl -sS http://127.0.0.1:9300/v1/agents/public | jq
|
|
```
|
|
|
|
Expected:
|
|
- `count` includes only `enabled && public_active` agents.
|
|
- planned/internal agents are excluded.
|
|
|
|
## Entitlements Operations
|
|
Add whitelist user:
|
|
```sql
|
|
INSERT INTO agent_allowlist(platform, platform_user_id, agent_id)
|
|
VALUES ('telegram', '123456789', 'helion')
|
|
ON CONFLICT (platform, platform_user_id, agent_id) DO NOTHING;
|
|
```
|
|
|
|
Require whitelist for an agent:
|
|
```sql
|
|
UPDATE agent_access_policies
|
|
SET requires_whitelist = TRUE, updated_at = now()
|
|
WHERE agent_id = 'helion';
|
|
```
|
|
|
|
Disable agent public access:
|
|
```sql
|
|
UPDATE agent_access_policies
|
|
SET enabled = FALSE, public_active = FALSE, updated_at = now()
|
|
WHERE agent_id = 'aistalk';
|
|
```
|
|
|
|
## Rate-Limit Policy Update
|
|
```sql
|
|
UPDATE agent_access_policies
|
|
SET
|
|
user_global_limit = 30,
|
|
user_global_window_seconds = 300,
|
|
user_agent_limit = 10,
|
|
user_agent_window_seconds = 300,
|
|
group_agent_limit = 5,
|
|
group_agent_window_seconds = 300,
|
|
updated_at = now()
|
|
WHERE agent_id = 'agromatrix';
|
|
```
|
|
|
|
## Fixed Smoke
|
|
1. Discovery:
|
|
```bash
|
|
curl -sS http://127.0.0.1:9300/v1/agents/public | jq '.count'
|
|
```
|
|
|
|
2. Whitelist deny:
|
|
- Set `requires_whitelist=true` for test agent.
|
|
- Replay webhook from user not in allowlist.
|
|
- Expected: deny ACK and event reason `access_whitelist_required`.
|
|
|
|
3. Whitelist allow:
|
|
- Insert user to `agent_allowlist`.
|
|
- Replay webhook.
|
|
- Expected: request continues to normal processing path.
|
|
|
|
4. Rate limit:
|
|
- Set low policy (`user_agent_limit=2`, window 60s).
|
|
- Send 3 quick webhooks from same user/agent.
|
|
- Expected: third request is `429`-style deny path and `reason=rate_limit_user_agent`.
|
|
|
|
5. Event invariant:
|
|
- `1 webhook -> 1 gateway event` remains true.
|
|
|
|
## PASS
|
|
- `/v1/agents/public` returns only public enabled agents.
|
|
- Entitlement decisions are deterministic (`allow|deny|rate_limited`).
|
|
- Metrics increment:
|
|
- `gateway_access_decisions_total`
|
|
- `gateway_rate_limited_total`
|
|
- No regression in webhook event finalize behavior.
|