# Biblioteca Secreta - auth.md

Guía y especificación de autenticación, registro y consumo de API para Agentes Autónomos e Inteligencia Artificial (Agent Readiness Discovery per Auth.md Standard & RFC 9727).

---

## 1. Audiencia y Propósito

Este documento describe cómo los agentes de IA, herramientas autónomas (LLM Tool Calling), rastreadores y sistemas automatizados pueden interactuar, autenticarse y registrarse para utilizar las APIs de **Biblioteca Secreta**.

- **Sitio web:** [https://biblioteca-secreta.com](https://biblioteca-secreta.com)
- **Especificación OpenAPI 3.1:** [https://biblioteca-secreta.com/api/openapi.json](https://biblioteca-secreta.com/api/openapi.json)
- **Documentación:** [https://biblioteca-secreta.com/api/docs](https://biblioteca-secreta.com/api/docs)
- **Catálogo de API (RFC 9727):** [https://biblioteca-secreta.com/.well-known/api-catalog](https://biblioteca-secreta.com/.well-known/api-catalog)

---

## 2. Niveles de Acceso y Métodos Soportados

Biblioteca Secreta admite tres modalidades de acceso:

### A. Acceso Público y Anónimo (Sin Autenticación)
Los agentes pueden consultar los siguientes endpoints sin credenciales previas:
- `GET /api/search?q={query}&engine={all|archive|drive|maravillosos}&format={all|pdf|epub}&page={1}`
- `GET /api/by-slug/{slug}`
- `GET /api/suggestions`
- `GET /api/recent-searches?limit={5}`
- `GET /api/ai-summary?title={title}&author={author}`
- `GET /api/health`

### B. Registro Anónimo de Agentes (`anonymous`)
Los agentes que deseen identificarse para obtener mayores límites de tasa (rate-limits) pueden solicitar un token de sesión de agente a través del endpoint de registro.
- **Tipo de identidad:** `anonymous`
- **Tipo de credencial:** `bearer_token`
- **Claim URI:** `https://biblioteca-secreta.com/agent/claim`

### C. Afirmación de Identidad e ID-JAG (`identity_assertion`)
Para agentes delegados por usuarios o plataformas empresariales que presentan aserciones firmadas:
- **Assertion Types:** `urn:ietf:params:oauth:token-type:id-jag`, `verified_email`
- **Tipos de credenciales:** `bearer_token`, `api_key`
- **Claim URI:** `https://biblioteca-secreta.com/agent/claim`
- **Revocation URI:** `https://biblioteca-secreta.com/agent/revoke`

---

## 3. Endpoints de Registro y Provisión de Agentes

### Registro de Agente (`POST /agent/auth`)
Permite a un agente registrarse y obtener credenciales de sesión.

```http
POST /agent/auth HTTP/1.1
Host: biblioteca-secreta.com
Content-Type: application/json

{
  "agent_name": "MySearchBot/1.0",
  "identity_type": "anonymous"
}
```

**Respuesta exitosa (`200 OK`):**
```json
{
  "status": "registered",
  "token_type": "Bearer",
  "access_token": "bs_agent_token_anon_demo",
  "expires_in": 86400,
  "scopes": ["search:books", "read:books", "ai:summary"]
}
```

### Validación de Reclamaciones (`POST /agent/claim`)
Endpoint para vincular o verificar una identidad de agente (por ejemplo, correo verificado o aserción ID-JAG).

```http
POST /agent/claim HTTP/1.1
Host: biblioteca-secreta.com
Content-Type: application/json

{
  "assertion_type": "verified_email",
  "email": "agent-operator@example.com"
}
```

### Revocación de Credenciales (`POST /agent/revoke`)
Permite anular de forma inmediata un token o sesión emitidos.

```http
POST /agent/revoke HTTP/1.1
Host: biblioteca-secreta.com
Content-Type: application/json

{
  "token": "bs_agent_token_..."
}
```

---

## 4. Uso de Credenciales en Peticiones API

Los agentes con credenciales registradas deben enviar su token mediante la cabecera HTTP estándar `Authorization`:

```http
GET /api/search?q=Cien+anos+de+soledad HTTP/1.1
Host: biblioteca-secreta.com
Authorization: Bearer <access_token>
```

---

## 5. Metadatos de Descubrimiento OAuth y PRM

- **OAuth Protected Resource Metadata (RFC 9470):**
  `https://biblioteca-secreta.com/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata (RFC 8414):**
  `https://biblioteca-secreta.com/.well-known/oauth-authorization-server`