# atproto-devtool

A multitool for the [atproto](https://atproto.com/) developer ecosystem.

## Installation

| Environment | CLI command |
|-------------|-------------|
| Cargo (Rust 1.85+) | `cargo install atproto-devtool` |

## Usage

### `test labeler`

Runs a conformance suite against a labeler, and produces a structured report
with per-check results plus a summary exit code. The suite has four stages:

- **Identity**: DID document contains the correct entries, and the labeler's PDS
  holds a valid labeler record.
- **HTTP**: Checks the `com.atproto.label.queryLabels` XRPC API.
- **Subscription**: Checks the `com.atproto.label.subscribeLabels` WebSocket.
- **Crypto**: Samples labels and verifies their signatures.

```text
Run the labeler conformance suite against an atproto labeler

Usage: atproto-devtool test labeler [OPTIONS] <TARGET>

Arguments:
  <TARGET>
          Handle (`alice.example`), DID (`did:plc:...` / `did:web:...`), or labeler endpoint URL

Options:
      --did <DID>
          Explicit DID override. Required (and combined with the target URL) when `target` is a raw
          endpoint URL and you want identity/crypto checks to run

      --subscribe-timeout <SUBSCRIBE_TIMEOUT>
          Per-connection time budget for the subscription-layer checks.

          Minimum 1 second; values below 1 second are rejected at parse time.

          [default: 5s]

      --no-color
          Whether to suppress colored output

      --verbose
          Whether to emit verbose diagnostics

  -h, --help
          Print help (see a summary with '-h')
```

#### Examples

Resolve by handle:

```bash
atproto-devtool test labeler moderation.bsky.app
```

Resolve by DID:

```bash
atproto-devtool test labeler did:plc:ar7c4by46qjdydhdevvrndac
```

Point at a raw labeler endpoint and supply the DID separately so identity and
crypto stages still run:

```bash
atproto-devtool test labeler https://mod.bsky.app --did did:plc:ar7c4by46qjdydhdevvrndac
```

Pass `--verbose` to any of the above to emit `DEBUG`-level tracing on stderr
(HTTP requests, WebSocket connect/disconnect and frame counts, PLC audit-log
fetches, per-label verification). `NO_COLOR=1` or `--no-color` disables ANSI
escape sequences in the rendered report.

#### Exit codes

- `0` — all spec-required checks passed (advisories and skipped checks are
  allowed).
- `1` — one or more spec-required checks failed.
- `2` — no spec-required checks failed but one or more network errors occurred.

### `test oauth client`

Runs a conformance suite against an atproto OAuth client, validating DPoP and
scope conformance. The suite has up to four stages:

- **Discovery**: Metadata URL is reachable and returns valid JSON.
- **Metadata**: Client metadata conforms to OAuth 2.0 and DPoP requirements.
- **JWKS**: JSON Web Key Set is present, valid, and keys are properly signed.
- **Interactive** (optional): Fake AS server exercises the client's full auth
  flow including PAR, authorization, token exchange, and refresh-token rotation.

```text
Test an atproto OAuth client

Usage: atproto-devtool test oauth client [OPTIONS] <TARGET> [COMMAND]

Arguments:
  <TARGET>
          The client's `client_id` URL, or a loopback form for development clients.

Options:
      --no-color
          Suppress ANSI color in rendered output

      --verbose
          Emit DEBUG-level tracing

  -h, --help
          Print help

Commands:
  interactive
          Run static checks plus an interactive flow against a fake authorization server
```

#### Static Mode (Default)

Validates the client's metadata and JWKS without driving an interactive flow:

```bash
atproto-devtool test oauth client https://client.example.com/metadata.json
```

#### Interactive Mode

Instantiates a fake atproto authorization server and exercises the client's
OAuth flow (PAR, authorize, token exchange, scope grants, DPoP nonce rotation,
refresh-token rotation):

```bash
# Same-host client (default)
atproto-devtool test oauth client interactive

# Remote client via tunnel
atproto-devtool test oauth client interactive --public-base-url https://tunnel.example.com
```

See [Reachability Workflows](docs/test-oauth-client-reachability.md) for
detailed setup instructions for remote clients.

#### Exit codes

- `0` — all checks pass.
- `1` — one or more spec violations (DPoP, scope, conformance issues).
- `2` — network errors (unreachable metadata, JWKS, or AS endpoint) with no
  spec violations.

## License

Licensed under either of

 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
   http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual licensed as above, without any additional terms or
conditions.