# tested.dev — auth.md

> PR coverage for agents
>
> **Source of truth:** Better Auth `agentAuth` plugin. This file is generated from
> `auth.api.getAgentConfiguration` and `auth.api.listCapabilities`. Do not invent
> alternate registration endpoints.

## Prefer machine discovery

1. `GET https://app.tested.dev/.well-known/agent-configuration`
2. `GET https://app.tested.dev/api/auth/capability/list`
3. Register / approve / execute using **only** URLs in the discovery `endpoints` map.

Protocol: [Better Auth Agent Auth](https://www.better-auth.com/docs/plugins/agent-auth) · [Agent Auth Protocol](https://agentauthprotocol.com/)

## Discovery document (live)

| Field | Value |
|-------|--------|
| version | 1.0-draft |
| provider_name | tested.dev |
| issuer | `https://app.tested.dev/api/auth` |
| default_location (execute) | `https://app.tested.dev/api/auth/capability/execute` |
| algorithms | Ed25519 |
| modes | delegated |
| approval_methods | ciba, device_authorization |

### Endpoints (from Better Auth)

| Key | URL |
|-----|-----|
| capabilities | `https://app.tested.dev/api/auth/capability/list` |
| describe_capability | `https://app.tested.dev/api/auth/capability/describe` |
| execute | `https://app.tested.dev/api/auth/capability/execute` |
| introspect | `https://app.tested.dev/api/auth/agent/introspect` |
| reactivate | `https://app.tested.dev/api/auth/agent/reactivate` |
| register | `https://app.tested.dev/api/auth/agent/register` |
| request_capability | `https://app.tested.dev/api/auth/agent/request-capability` |
| revoke | `https://app.tested.dev/api/auth/agent/revoke` |
| revoke_host | `https://app.tested.dev/api/auth/host/revoke` |
| rotate_host_key | `https://app.tested.dev/api/auth/host/rotate-key` |
| rotate_key | `https://app.tested.dev/api/auth/agent/rotate-key` |
| status | `https://app.tested.dev/api/auth/agent/status` |

## Agent flow (delegated mode)

1. **Discover** — `GET https://app.tested.dev/.well-known/agent-configuration` (also available under issuer as `/agent-configuration`).
2. **Register** — `POST` discovery `endpoints.register` with Ed25519 public key + requested capabilities.
3. **Human approval** — device flow UI at `https://app.tested.dev/device/capabilities` (or CIBA if advertised).
4. **Status** — poll `endpoints.status` until active grants.
5. **Execute** — `POST` `endpoints.execute` (`default_location`) with agent JWT:
   ```http
   Authorization: Bearer <agent_jwt>
   Content-Type: application/json

   { "capability": "<name>", "arguments": { } }
   ```
6. **Rotate / revoke** — use discovery endpoints only (`rotate_key`, `revoke`, …).

Agents act as the **approving user** (same membership / owner-admin rules as the dashboard).

## Capabilities (from `listCapabilities`)

### `get_onboarding_status`

Return first-10-minutes onboarding checklist status for the delegated user.

**Input**

  - _(no input fields)_

### `list_repos`

List repositories the delegated user can access (owner, name, last gate).

**Input**

  - _(no input fields)_

### `create_ingest_token`

Create or rotate the CI ingest token for a repository. Owner/admin only. Returns plaintext once.

**Input**

  - `owner` (string): GitHub owner/org login
  - `name` (string): Repository name

### `get_coverage_summary`

Read the latest coverage summary for a pull request (gate + patch/project %).

**Input**

  - `owner` (string)
  - `name` (string)
  - `prNumber` (integer)



## CI ingest token (not Agent Auth)

Separate from Agent Auth. Humans/CI push coverage with a **repo ingest token**:

- Create/rotate in app UI: repo **Settings**, or capability `create_ingest_token` (owner/admin).
- Env: `TESTED_TOKEN` or `TESTED_TOKEN_FILE` (chmod 600). Never commit. Never log.
- Upload: CLI `tested push` → `POST https://app.tested.dev/api/ingest`.

Setup docs: https://tested.dev/docs/install · https://tested.dev/llms-full.txt

## Human OAuth

Dashboard sign-in is **GitHub OAuth** via Better Auth (`/api/auth/*`). Session cookies are for browsers; agents should use Agent Auth JWTs or scoped API keys, not scraped cookies.

## Also available

- OpenAPI JSON (machine spec): `https://app.tested.dev/api/auth/open-api/generate-schema`
- Device approval page: `https://app.tested.dev/device/capabilities`
- Product docs: https://tested.dev/docs
- This file: `https://app.tested.dev/auth.md`

## Security

- Never print agent private keys, JWTs, or ingest tokens.
- Do not request capabilities you would not grant a CI bot.
- `create_ingest_token` is owner/admin only and returns plaintext **once**.
- Rate limits apply on capability execute (best-effort in-process + edge WAF).