# BoiMix auth.md

> Autonomous AI agent registration, authentication discovery, and authorization specification for BoiMix.

BoiMix is Bangladesh's premier circular book marketplace and exchange network. This document establishes machine-readable and developer-auditable instructions for AI agents, autonomous buyers, and software assistants acting on behalf of users or performing automated discovery.

---

## 1. Discovery (Two-Hop Standard)

BoiMix implements OAuth 2.0 Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)) and Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)).

- **Protected Resource Metadata (PRM):**
  `https://boimix.com/.well-known/oauth-protected-resource`
  _(Provides resource identifier, scopes, bearer methods, and advertised authorization servers)_
- **Authorization Server Metadata:**
  `https://boimix.com/.well-known/oauth-authorization-server`
  _(Provides issuer, token endpoints, registration URIs, and the machine-readable `agent_auth` block)_

---

## 2. Agent Audience & Capabilities

Autonomous agents may interact with BoiMix under three operational levels:

1. **Anonymous Exploration:**
   - Query book catalog, search titles, authors, and ISBNs.
   - Check real-time pricing, condition grades, and inventory availability across 64 districts in Bangladesh.
   - Read community policies, exchange rules, and platform guides.
   - _Requires no registration or credentials._

2. **Personal Assistant / Delegated Actions:**
   - Build cart, check shipping rates, initiate book purchases, and submit book exchange proposals on behalf of a verified member.
   - _Requires bearer credentials acquired via verified email assertion or ID-JAG._

3. **Autonomous Partner Services:**
   - Library aggregators and campus book clubs synchronizing holdings.
   - _Requires signed identity assertions._

---

## 3. Supported Identity & Registration Methods

BoiMix advertises support for the following identity types in the `agent_auth` discovery profile:

### Method A: Anonymous (`anonymous`)

- **Type:** `anonymous`
- **Credential Types:** `api_key`, `bearer_token`
- **Claim URI:** `https://boimix.com/auth/claim`
- **Behavior:** Open read-only access to catalog endpoints. Optional token issuance for session continuity and correspondence tracking.

### Method B: Verified Email (`verified_email`)

- **Assertion Type:** `verified_email`
- **Credential Types:** `bearer_token`, `api_key`
- **Registration URI:** `https://api.boimix.com/api/v1/auth/login`
- **Claim URI:** `https://boimix.com/auth/claim`
- **Behavior:** Allows an agent representing a user with a verified email address to claim an account through an out-of-band verification code or session confirmation.

### Method C: Identity Assertion / ID-JAG (`identity_assertion`)

- **Assertion Type:** `urn:ietf:params:oauth:token-type:id-jag`
- **Credential Types:** `bearer_token`
- **Registration URI:** `https://api.boimix.com/api/v1/auth/login`
- **Revocation URI:** `https://api.boimix.com/api/v1/auth/logout`
- **Behavior:** Cryptographic identity assertion signed by a recognized Identity Provider (IdP) asserting user consent for BoiMix scopes.

---

## 4. Supported Scopes

The resource server recognizes the following OAuth scopes:

| Scope          | Description                                                        |
| -------------- | ------------------------------------------------------------------ |
| `read:books`   | Read public book details, author bios, condition notes, and prices |
| `read:catalog` | Query book categories, taxonomy, and platform collections          |
| `write:cart`   | Create and update shopping carts for book purchases                |
| `write:orders` | Submit orders and initiate book exchange or borrow requests        |

---

## 5. Credential Usage

All authenticated API calls must transmit credentials via standard HTTP Authorization header:

```http
Authorization: Bearer <access_token>
```

Credentials must not be passed via URL query parameters.

---

## 6. Security, Events & Revocation

- **Revocation Endpoint:** `https://api.boimix.com/api/v1/auth/logout`
- **Events Supported:**
  - `urn:ietf:params:oauth:event-type:revocation`
  - `https://schemas.workos.com/events/agent/auth/identity/assertion/revoked`
- **Passive Scanning Note:** Do not execute automated POST registrations during passive audit scans. Public discovery metadata serves as the canonical source of truth.
- **Security Contact:** `support@boimix.com`