agent-auth-verify

Conformance test CLI for the Agent Auth Protocol. Points at any server, runs the checks, prints pass/fail.

npx agent-auth-verify https://yourserver.com

What It Checks

| Area | Spec Section | Checks | | -------------------- | ------------ | -------------------------------------------------------------------------------------------- | | Discovery | §5.1 | Endpoint reachable, valid JSON, required fields, endpoints object, issuer URL, Ed25519, modes | | Capabilities | §5.2 | Endpoint responds, returns capabilities array, each entry has name + description | | Agent Registration | §5.3 | Host JWT accepted, 200/201 response, returns agent_id, host_id, status, capability grants | | Revocation | §5.7 | Revocation succeeds, returns status: revoked, revoked agent gets 403 on execute | | Error Format | §5.13 | Missing auth → 401, invalid JWT → 401, error response has machine-readable error field |

Example Output

agent-auth-verify

  Testing: http://localhost:3000

  Discovery (§5.1)
  ✓ Discovery endpoint reachable             PASS
  ✓ Discovery returns valid JSON             PASS
  ✓ Discovery has all required fields        PASS
  ✓ Discovery endpoints object complete      PASS
  ✓ Issuer URL is valid                      PASS
  ✓ Algorithms includes Ed25519              PASS
  ✓ Modes field is valid                     PASS

  Capabilities (§5.2)
  ✓ Capability list endpoint reachable       PASS
  ✓ Capability list has capabilities array   PASS
  ✓ Each capability has name and description PASS

  Agent Registration (§5.3)
  ✓ Can sign host JWT                        PASS
  ✓ Registration returns 200/201             PASS
  ✓ Registration returns agent_id            PASS
  ✓ Registration returns valid status        PASS
  ✓ Registration returns host_id             PASS
  ✓ Registration returns capability grants array PASS

  Revocation (§5.7)
  ✓ Revocation endpoint responds             PASS
  ✓ Revocation returns status: revoked       PASS
  ✓ Revoked agent gets 403 on execute        PASS

  Error Format (§5.13)
  ✓ Missing auth returns 401                 PASS
  ✓ Invalid JWT returns 401                  PASS
  ✓ Error response has 'error' field         PASS

───────────────────────────────────────────────────────
  Results for http://localhost:3000
───────────────────────────────────────────────────────
  22 passed  0 failed  0 warnings  of 22 checks

   CONFORMANT   This server passes the Agent Auth Protocol spec.

Usage

Run against any server:

npx agent-auth-verify https://yourserver.com

JSON output:

npx agent-auth-verify https://yourserver.com --json

From a local clone:

node dist/index.js https://yourserver.com

Dev mode (TypeScript directly):

npx tsx src/index.ts https://yourserver.com

Demo Server

The repo ships a local demo server that implements the full protocol in memory. No real Agent Auth backend needed to try the tool.

# Start the demo server
npm run demo:server

# In another terminal, run the verifier against it
npm run demo:verify

# Or run directly
node dist/index.js http://localhost:3000

The demo server also serves a browser landing page at http://localhost:3000.

CI Usage

Use the --json flag for machine-readable output. The process exits with code 0 when all checks pass and code 1 when any check fails, so it works with standard CI pass/fail gates.

- run: npx agent-auth-verify https://yourserver.com --json

Spec Coverage

The test suite tracks the Agent Auth Protocol v1.0-draft. Coverage will expand as the spec evolves.

Contributing

Open an issue or PR on GitHub. If you're adding a new check, reference the spec section it covers and include a test against the demo server.

Related Links

• Agent Auth Protocol spec
• Official TypeScript implementation
• Public directory