# auth.md — Agent Authentication & Registration

This document outlines the authentication, agent registration, and discovery protocols for the **Ali Naim Portfolio & Offensive Security Research API**.

## Executive Summary & Agent Audience

- **Service**: Ali Naim Portfolio & Offensive Security Dossier
- **Owner**: Ali Naim (Computer Engineering @ Lebanese American University)
- **Primary Audience**: Autonomous AI Agents, LLMs, Security Scanners, and Automated Research Tools
- **Authentication Model**: **Public Anonymous Access** (Zero-login, open read-only access)

---

## Authentication Model: Anonymous Access

Because this application functions as a public technical portfolio and vulnerability disclosure record, **no human sign-up, user account creation, or OAuth credential grant is required** to interact with the API or inspect portfolio data.

Agents can interact freely with all public resources under the **Anonymous** identity model.

```yaml
# Agent Auth Flow Metadata
identity_types_supported:
  - "anonymous"
anonymous:
  credential_types_supported:
    - "none"
  claim_uri: "https://alinaim.dev/agent/claim"
scopes_supported:
  - "read"
```

---

## Agent Discovery & Metadata Endpoints

To programmatically discover the API structure, authorization metadata, and machine representations:

| Standard / Protocol | Endpoint URL | MIME Type | Description |
|---|---|---|---|
| **Auth.md Protocol** | `https://alinaim.dev/auth.md` | `text/markdown` | This agent authentication and registration specification |
| **OAuth Protected Resource (RFC 9728)** | `https://alinaim.dev/.well-known/oauth-protected-resource` | `application/json` | Protected Resource Metadata (PRM) |
| **OAuth Authorization Server** | `https://alinaim.dev/.well-known/oauth-authorization-server` | `application/json` | Authorization Server Metadata with `agent_auth` block |
| **API Catalog (RFC 9727)** | `https://alinaim.dev/.well-known/api-catalog` | `application/linkset+json` | Machine-readable API catalog linkset |
| **OpenAPI 3.0 Specification** | `https://alinaim.dev/openapi.json` | `application/vnd.oai.openapi+json` | Formal OpenAPI 3.0 API schema |
| **OpenAPI YAML** | `https://alinaim.dev/openapi.yaml` | `application/yaml` | YAML representation of OpenAPI spec |
| **Markdown Dossier** | `https://alinaim.dev/index.md` | `text/markdown` | Full CV, projects, vulnerabilities, and writeups in Markdown |
| **Portfolio JSON Data** | `https://alinaim.dev/api/data` | `application/json` | Raw structured JSON data object |
| **Health Check Endpoint** | `https://alinaim.dev/api/health` | `application/json` | API uptime and platform health status |

---

## Agent Registration Ceremony

Autonomous agents seeking to confirm their session or establish programmatic access may query the registration endpoint:

### Registration Request
```http
POST /agent/register HTTP/1.1
Host: alinaim.dev
Content-Type: application/json
Accept: application/json

{
  "agent_id": "optional-agent-identifier",
  "client_name": "Autonomous-Research-Agent/1.0"
}
```

### Registration Response (HTTP 200 OK)
```json
{
  "status": "success",
  "message": "Anonymous agent registration confirmed. Public read-only access is granted without credentials.",
  "identity_type": "anonymous",
  "credential_type": "none",
  "scopes": ["read"],
  "resources": {
    "api_catalog": "https://alinaim.dev/.well-known/api-catalog",
    "openapi": "https://alinaim.dev/openapi.json",
    "portfolio_data": "https://alinaim.dev/api/data",
    "markdown_dossier": "https://alinaim.dev/index.md"
  }
}
```

---

## How to Access API Resources

### 1. JSON Data
Query `GET /api/data` or `GET /data.json` to retrieve structured portfolio entities:
```bash
curl -s -H "Accept: application/json" "https://alinaim.dev/api/data"
```

### 2. Markdown for Agents
Query the root endpoint `/` with an `Accept: text/markdown` header to automatically receive the clean LLM-optimized Markdown representation:
```bash
curl -s -H "Accept: text/markdown" "https://alinaim.dev/"
```

### 3. API Catalog & Links
Inspect RFC 8288 `Link` headers sent with every root HTTP response:
```bash
curl -I "https://alinaim.dev/"
```
Example header response:
```http
Link: </.well-known/api-catalog>; rel="api-catalog", </openapi.json>; rel="service-desc"; type="application/vnd.oai.openapi+json", </docs>; rel="service-doc"; type="text/html", </auth.md>; rel="describedby"; type="text/markdown", </.well-known/oauth-protected-resource>; rel="describedby"
```

---

## Rate Limits & Good Citizen Policy

- Requests are rate-limited via Cloudflare Edge to prevent denial-of-service.
- Agents are encouraged to respect `robots.txt` and `Content-Signal: ai-train=no, search=yes, ai-input=no`.
- All vulnerability disclosures and security research data are shared responsibly under ethical disclosure guidelines.