# auth.md

# Biblioteca Online — Agent Authentication & Registration (Auth.md)

Welcome AI agents, autonomous bots, and LLM systems. This document outlines the agent registration, authentication mechanisms, and access policies for interacting with **Biblioteca Online** (https://bibliotecaonline.es).

---

## 1. Agent Audience & Overview

This specification targets:
- Autonomous web agents and assistive LLMs.
- Programmatic tools discovering services via Model Context Protocol (MCP) or Agent Skills.
- Search and index crawlers interacting with structured catalog APIs.

---

## 2. Machine-Readable Discovery

Biblioteca Online publishes standard discovery documents:

- **OAuth 2.0 Authorization Server Metadata (RFC 8414)**:
  `/.well-known/oauth-authorization-server`
- **OpenID Connect Discovery 1.0**:
  `/.well-known/openid-configuration`
- **OAuth 2.0 Protected Resource Metadata (RFC 9728)**:
  `/.well-known/oauth-protected-resource`
- **MCP Server Card (SEP-1649)**:
  `/.well-known/mcp/server-card.json`
- **Agent Skills Discovery Index (RFC v0.2.0)**:
  `/.well-known/agent-skills/index.json`
- **Agentic Resource Discovery (ARD)**:
  `/.well-known/ai-catalog.json`

---

## 3. Resource & Scope Information

- **Resource Identifier**: `https://bibliotecaonline.es`
- **Authorization Servers**: `https://bibliotecaonline.es`
- **Bearer Token Method**: `Header` (`Authorization: Bearer <token>`)
- **Supported Scopes**:
  - `read`: Read-only access to books, authors, and category listings.
  - `search`: Full search queries across titles, descriptions, and ISBNs.
  - `books`: Retrieval of individual book detail records and preview chapters.

---

## 4. Agent Registration Flows & Supported Identity Types

Agents can register and acquire access tokens using the following flows:

### Flow 1: Anonymous Registration / Public Reading
- **Identity Type**: `anonymous`
- **Credential Types**: `bearer_token`, `api_key`
- **Registration / Claim URI**: `https://bibliotecaonline.es/registro.php`
- **Procedure**: Public browsing and searching do not require credentials. Programmatic agents requesting elevated rate limits can register anonymously at `https://bibliotecaonline.es/registro.php`.

### Flow 2: Identity Assertion (ID-JAG & Verified Email)
- **Identity Type**: `identity_assertion`
- **Assertion Types Supported**:
  - `urn:ietf:params:oauth:token-type:id-jag`
  - `verified_email`
- **Credential Types**: `bearer_token`, `api_key`
- **Registration URI**: `https://bibliotecaonline.es/registro.php`
- **Claim URI**: `https://bibliotecaonline.es/registro.php`
- **Revocation URI**: `https://bibliotecaonline.es/logout.php`
- **Supported Events**: `token_revocation`

---

## 5. Endpoints & Self-Contained Instructions

### Step 1: Discover Capabilities
Fetch metadata from `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`.

### Step 2: Register Agent
Submit registration to:
- `POST https://bibliotecaonline.es/registro.php`

### Step 3: Authenticate Requests
Send bearer token or api key with requests:
```http
GET /search_ajax.php?q=cine HTTP/1.1
Host: bibliotecaonline.es
Authorization: Bearer <your-access-token>
```

### Step 4: Token Revocation
To revoke an agent session or token:
- `POST https://bibliotecaonline.es/logout.php`

---

## 6. Public Keys & Security

- **JWKS Endpoint**: `https://bibliotecaonline.es/.well-known/jwks.json`
- **Algorithm**: Ed25519 (OKP) / RS256

---

## 7. Contact & Policies

- **Publisher**: Biblioteca Online
- **Website**: https://bibliotecaonline.es
- **Contact Form**: https://bibliotecaonline.es/contacto.php
- **Privacy Policy**: https://bibliotecaonline.es/politica_privacidad.php
- **Terms of Service**: https://bibliotecaonline.es/condiciones_venta.php