# auth.md - Agent Smith (smiti.pro) Authentication & Agent Registration

> Discovery and authentication specification for autonomous agents, LLM assistants, and crawlers interacting with Agent Smith (smiti.pro).

## 1. Audience

This document describes machine-readable authentication, discovery protocols, and registration workflows for autonomous software agents, AI search engines, and programmatic clients accessing services on **smiti.pro**.

- **Service Name**: Agent Smith (smiti.pro)
- **Primary Domain**: https://smiti.pro
- **Capabilities**: Real Estate Intelligence, Market Analytics, Job Hunter Alerts, Smart Property Search in Georgia.
- **Content Signal**: `ai-train=no, search=yes, ai-input=yes` (Agents are explicitly welcomed to read, query, index, and use this content to answer user questions).

---

## 2. Discovery Endpoints & Standards

Agent Smith adheres to RFC 9727 and OAuth 2.0 Agent Discovery standards:

- **RFC 9727 API Catalog**: [/.well-known/api-catalog](https://smiti.pro/.well-known/api-catalog) (`Content-Type: application/linkset+json`)
- **OAuth Protected Resource Metadata (PRM)**: [/.well-known/oauth-protected-resource](https://smiti.pro/.well-known/oauth-protected-resource)
- **OAuth Authorization Server Metadata**: [/.well-known/oauth-authorization-server](https://smiti.pro/.well-known/oauth-authorization-server)
- **OpenAPI 3.1 Specification**: [/.well-known/openapi.json](https://smiti.pro/.well-known/openapi.json)
- **Robots.txt & Content Signals**: [/robots.txt](https://smiti.pro/robots.txt)
- **LLM Manifest**: [/llms.txt](https://smiti.pro/llms.txt)

---

## 3. Supported Authentication Methods

Agent Smith supports three registration and authentication flows for agents:

### 1. Anonymous Ephemeral Bearer (Recommended for Quick Queries)

- **Identity Type**: `anonymous`
- **Claim URI**: `POST https://smiti.pro/api/agent/anonymous`
- **Credential Type**: `ephemeral_bearer`
- **Scope**: `read search realestate`
- **Usage**:
  ```bash
  curl -X POST https://smiti.pro/api/agent/anonymous
  ```
  Returns:
  ```json
  {
    "access_token": "anon_...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "scope": "read search realestate"
  }
  ```

### 2. Agent Registration (`agent_auth`)

- **Register URI**: `POST https://smiti.pro/api/agent/register`
- **Credential Type**: `bearer`
- **Scopes**: `read search realestate market_analysis`
- **Request**:
  ```bash
  curl -X POST https://smiti.pro/api/agent/register \
    -H "Content-Type: application/json" \
    -d '{"client_id": "my-ai-agent", "identity_type": "anonymous"}'
  ```

### 3. Identity Assertion & Token Exchange (ID-JAG & Verified Email)

- **Assertion Types Supported**:
  - `urn:ietf:params:oauth:token-type:id-jag`
  - `verified_email`
- **Claim URI**: `POST https://smiti.pro/api/agent/claim`
- **Revocation URI**: `POST https://smiti.pro/api/agent/revoke`
- **Supported Events**: `revocation`

---

## 4. Credential Usage

All authenticated API requests should provide the token via standard HTTP Authorization header:

```http
Authorization: Bearer <access_token>
```

Example request:

```bash
curl -X GET https://smiti.pro/api/health \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"
```

---

## 5. Public Read-Only Access & Markdown for Agents

Public endpoints do not require authentication for inspection and reading:

- **Markdown for Agents**: Send `Accept: text/markdown` with any page URL (e.g. `GET https://smiti.pro/realestate`) to receive clean, unbloated Markdown instead of HTML.
- **Health Check**: `GET https://smiti.pro/api/health` returns operational status (`pass`).

---

## 6. Security & Contact

For questions regarding security, crawler rate limits, or integration partnerships:

- **Security Contact**: contact@smiti.pro
- **Website**: https://smiti.pro
