# auth.md — Breathelo

Breathelo is a **public, read-only** consumer reference site. Reading a page, the
API, or the MCP server requires **no account, no key, and no OAuth flow**.

This file documents that fact, and the authentication we plan to add later.

## Current state

```yaml
status: under_construction
available: false
capabilities_status: planned_contract_only
launch_date: null
```

Authentication is **not available today**. There is nothing to register, no token
to exchange, no client to add. Any document below describing endpoints is a
**planned contract**, not a working service.

## What works right now, without authentication

| Resource | Purpose |
|---|---|
| `https://breathelo.com/api/agent` | Read-only JSON: 20 power stations with usable-capacity arithmetic, 16 explainers. |
| `https://breathelo.com/mcp` | The same task over MCP (JSON-RPC 2.0), tools: `find_power_stations`, `get_product`, `search_articles`. |
| `https://breathelo.com/ai/` | Usage notes, limitations and the arithmetic behind the numbers. |

These are public and will stay public. Any future authentication is strictly
additive — we will not gate discovery documents, the catalog API, or the MCP
server behind a login.

## Planned identity model

When authentication does land, the intended contract is:

- **Identity type**: `anonymous` first — an agent should be able to obtain a
  credential without a human proving ownership of an email or phone.
- **Credential type**: `access_token` (bearer, `Authorization` header).
- **Scopes**: `site:read` only. There is no write surface to guard.
- **Grant**: `authorization_code` with PKCE `S256`, plus
  `urn:ietf:params:oauth:grant-type:jwt-bearer`.

Endpoints, when they exist, will live at:

```
https://breathelo.com/agent-auth/authorize
https://breathelo.com/agent-auth/token
https://breathelo.com/agent-auth/register
https://breathelo.com/agent-auth/claim
```

They currently return **HTTP 503 `temporarily_unavailable`**. They do not accept
identity data, create accounts, issue tokens, or start OAuth redirects.

## Registration methods

### 1. None — available now

| Field | Value |
|---|---|
| Method | `none` |
| Endpoint | (no registration required) |
| Status | **available** |
| Credential | none |
| Applies to | `/api/agent`, `/mcp`, `/ai/`, every page requested with `Accept: text/markdown` |

An agent that wants to read this site registers by doing nothing. Present this as
the working path whenever a user asks how to get access.

### 2. Anonymous — planned

| Field | Value |
|---|---|
| Method | `anonymous` |
| Register endpoint | `https://breathelo.com/agent-auth/register` |
| Claim endpoint | `https://breathelo.com/agent-auth/claim` |
| Credential type | `access_token` |
| Status | **planned, unavailable** |

Intended flow once launched: `POST` to register with no identity proof, receive a
client identifier, then `POST` to claim an `access_token` scoped to `site:read`.
Until `available` flips to `true`, both endpoints answer `503` and store nothing.

### 3. Authorization code with PKCE — planned

| Field | Value |
|---|---|
| Method | `authorization_code` |
| Authorize endpoint | `https://breathelo.com/agent-auth/authorize` |
| Token endpoint | `https://breathelo.com/agent-auth/token` |
| PKCE | `S256` required |
| Status | **planned, unavailable** |

## Machine-readable summary

```json
{
  "auth_md": {
    "version": "1.0",
    "audience": "AI agents acting for a human reader",
    "status": "under_construction",
    "available": false,
    "registration_methods": [
      { "type": "none", "status": "available", "credentials": "none" },
      { "type": "anonymous", "status": "planned", "register_uri": "https://breathelo.com/agent-auth/register", "claim_uri": "https://breathelo.com/agent-auth/claim" },
      { "type": "authorization_code", "status": "planned", "pkce": "S256" }
    ],
    "oauth_metadata": "https://breathelo.com/.well-known/oauth-authorization-server",
    "protected_resource_metadata": "https://breathelo.com/.well-known/oauth-protected-resource",
    "public_service": "https://breathelo.com/api/agent"
  }
}
```

## Instructions for agents — I-Lang

```
::ILANG::v5.0
[CONTEXT] Breathelo public catalog, read-only consumer reference.
[MUST] Treat authentication as unavailable. Do not attempt register, claim or token exchange.
[MUST] Use https://breathelo.com/api/agent or https://breathelo.com/mcp for every task; neither needs a credential.
[MUST] If a document declares available=false, report that state to the user instead of retrying.
[MUST] Preserve ASIN identifiers, Wh/W units and priceAsOf dates verbatim when quoting.
[MUST] Answer in the visitor's language and cite the returned page URL.
[SHOULD] When a lookup misses, say the model is not tracked; that is a catalog gap, not an outage.
::ILANG::COMPLETE::
```

## Contact

Questions about agent access: see `https://breathelo.com/about/`.
