# auth.md - SendShield Files Agent Registration & Auth Discovery

This document explains authentication, agent registration, and machine access mechanisms for AI agents, automated systems, and developers interacting with SendShield Files (`https://sendshieldfiles.com`).

## Agent Audience
This specification and its associated registration mechanisms are intended for:
- Autonomous AI agents (e.g., Anthropic Claude, OpenAI GPT, LangChain, AutoGPT, CrewAI).
- Model Context Protocol (MCP) clients and A2A (Agent-to-Agent) systems.
- Automated API integrations, CLI sync tools, and background encryption workers.

## Registration & Provisioning Endpoints
- **Register Endpoint**: `POST https://sendshieldfiles.com/api/agent/auth` (Alias: `POST https://sendshieldfiles.com/api/agent/register`)
- **Claim Endpoint**: `POST https://sendshieldfiles.com/api/agent/claim`
- **Revocation Endpoint**: `POST https://sendshieldfiles.com/api/agent/revoke`

> **Note on Passive Scans**: Do not probe `POST /api/agent/auth` or `POST /agent/auth` during passive scans. Registration can provision accounts, issue credentials, or trigger security notifications. Public discovery documents are the safe source of truth.

## Supported Flow Methods & Flow Metadata

### 1. ID-JAG (Identity Assertion JWT Authorization Grant)
- **Identity Type**: `identity_assertion`
- **Assertion Type**: `urn:ietf:params:oauth:token-type:id-jag`
- **Credential Types**: `bearer`, `api_key`
- **Revocation URI**: `https://sendshieldfiles.com/api/agent/revoke`
- **Events Supported**: `https://schemas.workos.com/events/agent/auth/identity/assertion/revoked`, `revocation`

### 2. Verified Email Assertion
- **Identity Type**: `identity_assertion`
- **Assertion Type**: `verified_email`
- **Credential Types**: `bearer`, `api_key`
- **Claim URI**: `https://sendshieldfiles.com/api/agent/claim`

### 3. Anonymous / Ephemeral Agent Flow
- **Identity Type**: `anonymous`
- **Credential Types**: `bearer`, `ephemeral_token`
- **Claim URI**: `https://sendshieldfiles.com/api/agent/claim`

## Credential Usage & Bearer Authentication
Once an agent receives credentials, pass the bearer token in the HTTP Authorization header:
```http
Authorization: Bearer <TOKEN>
```

Supported scopes:
- `transfers:read`: Download and read encrypted transfer payloads.
- `transfers:write`: Initialize and upload encrypted transfer ciphertext.
- `requests:write`: Create and manage secure file drop requests.

## Public & Agent Endpoints (No Credentials Required)
- **Status Check**: `GET /api/status` returns current platform mode (`live`, `maintenance`, `coming_soon`).
- **Health Probe**: `GET /api/health` returns database connectivity status.
- **PoW Challenge**: `GET /api/pow/challenge` generates an anti-bot memory-hard puzzle.
- **Abuse Reporting**: `POST /api/abuse/report` allows machine-signed reports of abusive transfers.

## Architecture & Zero-Knowledge Contract
SendShield Files operates on a zero-knowledge cryptographic model:
1. All files and sensitive headers are encrypted client-side using **AES-256-GCM**.
2. The decryption key is passed exclusively in the URL anchor/hash fragment (`#key=...`). Servers never see or store the decryption key.
3. Automated agents interacting with SendShield Files must respect client-side key generation and must not transmit plaintext keys to public logs or third parties.

## Machine Discovery & Protocols
- **Protected Resource Metadata (PRM)**: `https://sendshieldfiles.com/.well-known/oauth-protected-resource`
- **Authorization Server Metadata**: `https://sendshieldfiles.com/.well-known/oauth-authorization-server`
- **OpenID Configuration**: `https://sendshieldfiles.com/.well-known/openid-configuration`
- **API Catalog (RFC 9727)**: `https://sendshieldfiles.com/.well-known/api-catalog`
- **Model Context Protocol (MCP)**: `https://sendshieldfiles.com/.well-known/mcp.json`
- **Agent-to-Agent (A2A)**: `https://sendshieldfiles.com/.well-known/agent-card.json`
- **Skills Directory**: `https://sendshieldfiles.com/.well-known/skills/index.json`
- **Commerce & Micropayments (x402)**: `https://sendshieldfiles.com/.well-known/commerce.json`