# auth.md

## Mentensor AI Agent Authentication & Registration Specification

> Operational guidance and identity protocols for automated AI agents, bots, and tools interacting with MENTENSOR Edge APIs.
> Service: Mentensor (Mariusz Ruski // AI Product Engineer & Design Technologist)
> Service Root: https://mentensor.eu
> RFC 9728 Protected Resource: https://mentensor.eu/.well-known/oauth-protected-resource
> RFC 8414 Authorization Server: https://mentensor.eu/.well-known/oauth-authorization-server

---

## 1. Audience & Scope

This document specifies how external autonomous AI agents, multi-agent frameworks (A2A), and model context clients (MCP) discover, register, and authenticate against MENTENSOR edge infrastructure.

MENTENSOR exposes public discovery endpoints, semantic inquiry rails, and live telemetry for technical evaluation.

---

## 2. Discovery Endpoints

- **OAuth Protected Resource Metadata (PRM)**: https://mentensor.eu/.well-known/oauth-protected-resource
- **OAuth Authorization Server Metadata**: https://mentensor.eu/.well-known/oauth-authorization-server
- **OpenID Connect Discovery**: https://mentensor.eu/.well-known/openid-configuration
- **API Catalog (RFC 9727)**: https://mentensor.eu/.well-known/api-catalog
- **Model Context Protocol Card**: https://mentensor.eu/.well-known/mcp/server-card.json
- **A2A Agent Card**: https://mentensor.eu/.well-known/agent-card.json
- **Web Bot Auth Key Directory**: https://mentensor.eu/.well-known/http-message-signatures-directory

---

## 3. Supported Authentication & Identity Methods

External agents may access endpoints according to their trust tier:

### Method A: Anonymous Read & Zero-Friction Inquiry (Default)
Agents acting on behalf of founders or prospective clients can query public case studies and submit project discovery briefs without pre-provisioned credentials.
- `identity_types_supported`: `["anonymous"]`
- `anonymous.credential_types_supported`: `["ephemeral_agent_token", "session_fingerprint"]`
- `claim_uri`: `https://mentensor.eu/api/inquiry`
- `registration_method`: Self-service invocation via `POST /api/inquiry`

### Method B: Verified Human & Agency Principal Assertion
When an agent submits an inquiry on behalf of a human principal (Founder, CTO, Procurement Lead), it should assert a verified contact email.
- `identity_types_supported`: `["identity_assertion"]`
- `identity_assertion.assertion_types_supported`: `["verified_email"]`
- `credential_types`: `["email_receipt_hash", "client_assertion_jwt"]`
- `claim_uri`: `https://mentensor.eu/api/inquiry`

### Method C: ID-JAG (Identity Assertion for Joint Agent Governance)
For enterprise federated agents and multi-agent procurement networks:
- `identity_types_supported`: `["identity_assertion"]`
- `identity_assertion.assertion_types_supported`: `["urn:ietf:params:oauth:token-type:id-jag"]`
- `credential_types`: `["private_key_jwt", "urn:ietf:params:oauth:token-type:jwt"]`
- `revocation_uri`: `https://mentensor.eu/oauth/revoke`
- `events_supported`: `["urn:ietf:params:oauth:event:token-revocation"]`

---

## 4. OAuth 2.0 Protected Resource Metadata Summary

```json
{
  "resource": "https://mentensor.eu/api",
  "authorization_servers": [
    "https://mentensor.eu"
  ],
  "scopes_supported": [
    "read:cases",
    "write:inquiry",
    "read:telemetry",
    "tools:mcp"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "resource_documentation": "https://mentensor.eu/llms-full.txt"
}
```

---

## 5. Agent Registration Protocol (`agent_auth`)

```json
{
  "agent_auth": {
    "skill": "mentensor-agent-auth",
    "register_uri": "https://mentensor.eu/api/inquiry",
    "grant_types_supported": [
      "client_credentials",
      "urn:ietf:params:oauth:grant-type:token-exchange"
    ],
    "methods": [
      {
        "type": "anonymous_inquiry",
        "endpoint": "https://mentensor.eu/api/inquiry",
        "description": "Submit structured project specifications directly to Mariusz Ruski's edge terminal."
      },
      {
        "type": "verified_email",
        "endpoint": "https://mentensor.eu/api/inquiry",
        "description": "Verified client email with automated receipt dispatch."
      }
    ]
  }
}
```

---

## 6. Rate Limiting & Ethical Use Policy

- Public endpoints are governed by Cloudflare Rate Limiting rules.
- Aggressive token scraping without semantic caching will be throttled.
- For high-volume automated reviews, include `Signature-Agent: MentensorAgentClient/1.0` header.