# Own Your GPU auth.md — Agent Authentication & Token Protocols

Welcome to the authentication and agent registration specification for **Own Your GPU** (DGX Spark Lease-to-Own in Burbank–LA metro).

This document serves as the discovery specification for autonomous AI agents, machine clients, and client applications.

---

## 1. Agent Audience & Architecture

- **Audience:** Autonomous AI agents, automated orchestration pipelines, cluster provisioners, and authorized customer clients.
- **Resource Server:** `https://ownyourgpu.com`
- **Authorization Server:** `https://ownyourgpu.com`
- **Discovery Endpoints:**
  - OAuth Protected Resource Metadata (RFC 9728): [`/.well-known/oauth-protected-resource`](https://ownyourgpu.com/.well-known/oauth-protected-resource)
  - OAuth Authorization Server Metadata (RFC 8414): [`/.well-known/oauth-authorization-server`](https://ownyourgpu.com/.well-known/oauth-authorization-server)
  - OpenID Connect Configuration: [`/.well-known/openid-configuration`](https://ownyourgpu.com/.well-known/openid-configuration)
  - Public JWKS: [`/.well-known/jwks.json`](https://ownyourgpu.com/.well-known/jwks.json)

---

## 2. Cryptographic One-Time Tokens (OTT) & Session Tokens

Own Your GPU provides a native cryptographic token service featuring high-entropy, time-bounded, single-use tokens alongside standard session tokens.

### A. Issue Cryptographic Tokens (`POST /api/auth/token`)
Generate a secure, single-use or session token backed by high-entropy random generation and Cloudflare KV with TTL enforcement:

```http
POST https://ownyourgpu.com/api/auth/token
Content-Type: application/json

{
  "token_type": "one_time",
  "expires_in": 900,
  "scope": "intent:register"
}
```

**Response:**
```json
{
  "token": "OTT-8F2B-9C1D-4A7E-3160-BD52-9E81-A24C",
  "token_type": "one_time",
  "expires_in": 900,
  "expires_at": "2026-09-12T19:45:00.000Z",
  "scope": "intent:register",
  "message": "Cryptographic one-time token issued. Expires in 900 seconds. Single-use only."
}
```

### B. Verify & Burn Tokens (`POST /api/auth/verify`)
Verifies token validity against cryptographic store. If `token_type` is `one_time`, the token is **immediately burned** upon verification so it can never be reused:

```http
POST https://ownyourgpu.com/api/auth/verify
Content-Type: application/json

{
  "token": "OTT-8F2B-9C1D-4A7E-3160-BD52-9E81-A24C"
}
```

**Response:**
```json
{
  "valid": true,
  "consumed": true,
  "token_type": "one_time",
  "scope": "intent:register",
  "message": "Token verified and burned (single-use constraint satisfied)."
}
```

### C. Revoke Tokens (`POST /api/auth/revoke` or `POST /oauth/revoke`)
```http
POST https://ownyourgpu.com/api/auth/revoke
Content-Type: application/json

{
  "token": "OTT-8F2B-9C1D-4A7E-3160-BD52-9E81-A24C"
}
```

---

## 3. OAuth 2.0 & Session Management

- **Token Endpoint:** `POST https://ownyourgpu.com/oauth/token`
- **Grant Types Supported:**
  - `client_credentials`: Machine-to-machine authentication.
  - `one_time_token`: Exchange a valid cryptographic OTT for a session Bearer token.
  - `authorization_code`: User-consented web delegation.
  - `refresh_token`: Session extension.
- **Bearer Methods:** Sent via HTTP header: `Authorization: Bearer <token>`.
- **Supported Scopes:**
  - `intent:register`: Register allocation intent in Phase 1 queue.
  - `node:provision`: (Phase 2) Programmatic node cluster provisioning.
  - `shell:connect`: (Phase 2) Dedicated SSH shell tunnel and container orchestration.
  - `read`: General resource reading.
  - `write`: General resource writing.
  - `lease:read`: Read lease status, hardware assignment, balance, and fees for the authenticated account.
  - `account:read`: Read notifications and profile status for the authenticated account.

---

## 4. Authenticated Account & Lease Endpoints

The following endpoints require valid Bearer token authentication and are strictly scoped to the authenticated account:

- **Account Notifications (`GET https://ownyourgpu.com/api/notifications` or `/api/account/notifications`):**
  - Scope required: `account:read` or `read`
  - Headers: `Authorization: Bearer <token>`
  - Returns alerts, payment confirmations, and cluster provisioning updates scoped to the authenticated account.

- **Lease Allocation & Hardware Status (`GET https://ownyourgpu.com/api/lease/status` or `/api/account/lease`):**
  - Scope required: `lease:read` or `read`
  - Headers: `Authorization: Bearer <token>`
  - Returns assigned DGX Spark node, Burbank datacenter rack placement, term elapsed, and SSH provisioning readiness.

- **Remaining Balance & Equity Tracking (`GET https://ownyourgpu.com/api/lease/balance` or `/api/account/balance`):**
  - Scope required: `lease:read` or `read`
  - Headers: `Authorization: Bearer <token>`
  - Returns total lease commitment, accrued ownership equity %, remaining principal balance until $1 title transfer, and next scheduled installment.

- **Late Fees & Standing Inquiries (`GET https://ownyourgpu.com/api/lease/fees` or `/api/account/fees`):**
  - Scope required: `lease:read` or `read`
  - Headers: `Authorization: Bearer <token>` or Cookie: `session=<token>`
  - Returns late fee balance ($0.00 in good standing), grace periods, and payment method status.

- **User Lease & Operations Dashboard (`GET https://ownyourgpu.com/api/account/dashboard` or `/api/dashboard`):**
  - Scope required: `account:read` or `read`
  - Headers: `Authorization: Bearer <token>` or Cookie: `session=<token>`
  - Returns comprehensive dashboard telemetry including account details, lease allocation, financial breakdown, billing standing, colocation telemetry, and SSH provisioning endpoints.

- **Account Creation & Registration (`POST https://ownyourgpu.com/api/auth/register`):**
  - Payload: `{ "name": "...", "email": "...", "password": "...", "company": "..." }`
  - Creates an account, hashes password with PBKDF2-HMAC-SHA256 (100k iterations), issues session token, and sets secure `session` HTTP cookie.

- **Account Login (`POST https://ownyourgpu.com/api/auth/login`):**
  - Payload: `{ "email": "...", "password": "..." }`
  - Verifies credentials, issues session token, and sets secure HTTP-only session cookie.

- **Account Logout (`POST https://ownyourgpu.com/api/auth/logout`):**
  - Revokes active session token and clears the `session` cookie.

- **OAuth Providers & Exchange (`GET /api/auth/providers`, `/api/auth/oauth/google`, `/api/auth/oauth/github`, `POST /api/auth/oauth/exchange`):**
  - Discovers supported OAuth providers, handles authorization callbacks, and allows programmatic identity exchange.

---

## 5. Agent Registration & Discovery Flows

Agents can discover registration capabilities dynamically via metadata or directly interact with the registration endpoint:

- **Agent Registration URI:** `https://ownyourgpu.com/agent/auth`
- **Supported Registration Methods:**

### 1. ID-JAG (Identity Assertion Grant)
- **Identity Types:** `identity_assertion`
- **Assertion Types:** `urn:ietf:params:oauth:token-type:id-jag`
- **Credential Types:** `bearer_token`, `api_key`
- **Revocation URI:** `https://ownyourgpu.com/oauth/revoke`
- **Events Supported:** `https://schemas.openid.net/secevent/oauth/event-type/token-revoked`

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

### 3. Anonymous Registration
- **Identity Types:** `anonymous`
- **Credential Types:** `bearer_token`, `one_time_token`
- **Claim URI:** `https://ownyourgpu.com/agent/claim`

---

## 6. Security & Zero Backend Exposure Commitment

- **Strict Account Isolation:** Authenticated endpoints only reveal records bound to the authenticated principal's account. No cross-tenant access is permitted.
- **No Public Read Access to Leads:** No external party or agent is permitted to query, dump, or inspect the backend leads database.
- **Privacy Self-Service:** Registrations issue a unique 128-bit cryptographic key (`REM-...`) that permanently deletes stored data via `POST /api/remove`.
- **Phase Roadmap:** The API currently restricts client actions to registering allocation intent (`POST /api/interest`). Hardware allocation terms, node certificates, and SSH shell automation extensions will be issued prior to physical hardware provisioning.