# BanglaVerse Cloud auth.md

> Autonomous agent registration, authentication discovery, and authorization metadata for BanglaVerse Cloud.
> Service: https://banglaverse.net
> Contact: mailto:admin@banglaverse.net

## Overview & Audience

This document specifies authentication, identity registration, and discovery protocols for AI agents, autonomous evaluators, and machine clients integrating with **BanglaVerse Cloud** (`https://banglaverse.net`).

BanglaVerse Cloud provides high-performance Minecraft game server hosting in Bangladesh (BDIX connectivity, DDR5 RAM, NVMe SSDs), alongside free public performance analysis and diagnostic tools (Spark Profiler Analyzer, MOTD Generator, Tab Generator, Server Status Checker).

Both the Protected Resource Server and the Authorization Server reside on this origin:
- **Resource Server**: https://banglaverse.net
- **Authorization Server**: https://banglaverse.net

---

## Discovery Documents

Machine clients and agents can discover endpoints through the standard OAuth 2.0 discovery mechanisms:

1. **OAuth 2.0 Protected Resource Metadata (PRM, RFC 9728)**:
   - URL: https://banglaverse.net/.well-known/oauth-protected-resource
   - Identifies the protected resource, trusted authorization servers (`https://banglaverse.net`), supported scopes, and bearer transmission method (`header`).

2. **OAuth 2.0 Authorization Server Metadata (RFC 8414)**:
   - URL: https://banglaverse.net/.well-known/oauth-authorization-server
   - Publishes authorization endpoints, token endpoints, supported grant types, and the **`agent_auth`** block.

3. **API Catalog (RFC 9727)**:
   - URL: https://banglaverse.net/.well-known/api-catalog
   - Content-Type: `application/linkset+json`

4. **OpenAPI Specification with MPP Payment Discovery (mpp.dev)**:
   - URL: https://banglaverse.net/openapi.json
   - Content-Type: `application/json`
   - Features: Standard OpenAPI 3.1.0 document with `x-service-info` categories and `x-payment-info` extensions on payable operations (methods: `tempo`, `stripe`, `lightning`, `card`; intents: `charge`, `session`).

5. **LLM Context & System Architecture**:
   - URL: https://banglaverse.net/llms.txt

6. **Agent Skills Discovery Index (RFC v0.2.0)**:
   - URL: https://banglaverse.net/.well-known/agent-skills/index.json
   - Content-Type: `application/json`

7. **MCP Server Card (SEP-1649)**:
   - URL: https://banglaverse.net/.well-known/mcp/server-card.json
   - Content-Type: `application/json`
   - Transport: Streamable HTTP (`https://banglaverse.net/mcp`)

8. **Web Bot Auth Key Directory (IETF WebBotAuth / RFC 9421)**:
   - URL: https://banglaverse.net/.well-known/http-message-signatures-directory
   - Content-Type: `application/json`
   - Key Types: `Ed25519` (`CUxZgxLRKb_XN6K5jdO6p65MXOH23A_vR41-GHf7sMk`), `RS256` (`banglaverse-2026-01`)
   - Header Directives: `Signature-Agent: "https://banglaverse.net"`, `Signature-Input`, `Signature`

9. **DNS for AI Discovery (DNS-AID / draft-mozleywilliams-dnsop-dnsaid)**:
   - Namespace: `_agents.banglaverse.net`
   - Manifest URL: https://banglaverse.net/.well-known/dns-aid.json
   - DNS Service Bindings (SVCB/HTTPS):
     - `_index._agents.banglaverse.net. 3600 IN HTTPS 1 banglaverse.net. alpn="h3,h2" port=443 mandatory=alpn,port`
     - `_a2a._agents.banglaverse.net.   3600 IN SVCB  1 banglaverse.net. alpn="a2a" port=443 mandatory=alpn,port`
     - `_mcp._agents.banglaverse.net.   3600 IN SVCB  1 banglaverse.net. alpn="mcp" port=443 mandatory=alpn,port`
   - DNSSEC Status: Authenticated & Cryptographically Signed

10. **Agentic Commerce Protocol (ACP / agenticcommerce.dev)**:
    - URL: https://banglaverse.net/.well-known/acp.json
    - Content-Type: `application/json`
    - Protocol: `acp` (version `2026-01-30`)
    - Services: `checkout`

11. **A2A Agent Card & Agent Payments Protocol (AP2 / ap2-protocol.org)**:
    - URL: https://banglaverse.net/.well-known/agent-card.json
    - Content-Type: `application/json`
    - Protocol: Agent2Agent (A2A v0.3.0) with AP2 Extension (`https://github.com/google-agentic-commerce/AP2/tree/v0.1.0`)
    - AP2 Role: `merchant` (`required: true`)
    - Capabilities: Cryptographically-signed payment mandates, verifiable cart tokens, automated Minecraft server hosting checkout and billing.

12. **Machine Payments Protocol (MPP / mpp.dev)**:
    - Specification: `https://mpp.dev` & `https://paymentauth.org/draft-payment-discovery-00.txt`
    - Discovery Document: https://banglaverse.net/openapi.json
    - Metadata: Root `x-service-info` categories (`game-hosting`, `cloud-infrastructure`, `minecraft`, `developer-tools`, `payments`, `bdix`)
    - Operations:
      - `POST /api/server/provision`: Provisioning (`intent: charge`, `method: tempo`, `amount: 2.30 USD`)
      - `POST /api/server/renew`: Subscription renewal (`intent: charge`, `method: stripe`, `amount: 250 BDT`)
      - `POST /api/domain/register`: Domain registration (`intent: charge`, `method: card`, `amount: 1200 BDT`)
      - `POST /api/spark-analyzer/deep-audit`: Spark AI analysis session (`intent: session`, `method: tempo`, `amount: 0.50 USD`)
    - Supported Rails: `tempo`, `stripe`, `lightning`, `card` with HTTP 402 challenge responses.

13. **Universal Commerce Protocol (UCP / ucp.dev)**:
    - Specification: `https://ucp.dev/specification/overview/`
    - Discovery Profile: https://banglaverse.net/.well-known/ucp
    - Protocol Version: `2026-08-25`
    - Services: `dev.ucp.shopping` (bindings: `rest`, `mcp`, `a2a`)
    - Capabilities:
      - `dev.ucp.shopping.checkout`: Server provisioning checkout sessions
      - `dev.ucp.shopping.order`: Recurring subscription management
      - `dev.ucp.shopping.fulfillment`: Automated game instance provisioning
      - `dev.ucp.common.identity_linking`: OAuth2 identity binding
    - Payment Handlers: `dev.ucp.payment.mpp`, `dev.ucp.payment.ap2`

14. **x402 Payment Protocol (x402.org / Coinbase)**:
    - Specification: `https://x402.org` & `https://docs.x402.org`
    - Reference Implementation: `@x402/next`, `@x402/core`, `@x402/evm`
    - Protected Endpoints: https://banglaverse.net/api, https://banglaverse.net/api/v1
    - Facilitator URL: https://facilitator.xpay.sh
    - Merchant Wallet Address: `0x51cd08733c62a6223f15e5951c1c8b4d6d28be03`
    - Supported Networks: `eip155:8453` (Base), `eip155:56` (BNB Smart Chain), `eip155:84532` (Base Sepolia)
    - Payment Scheme: `exact` (EIP-3009 & Permit2 USDC)
    - Response Protocol: HTTP `402 Payment Required` with base64 `PAYMENT-REQUIRED` header and structured JSON requirements.

---

## Supported Identity Types & Flows

BanglaVerse Cloud supports both unauthenticated access for diagnostic tools and registered identity flows for automated server provisioning:

### 1. Anonymous Access (`anonymous`)
- **Use Case**: Public read-only endpoints, server status checks, MOTD and Tab generation, and public Spark Profiler analysis.
- **Credentials Required**: None (`none` or optional `api_key`).
- **Claim Endpoint**: https://banglaverse.net/agent/auth/claim

### 2. Identity Assertion (`identity_assertion`)
- **Use Case**: Autonomous agent actions, server configuration changes, and billing operations on behalf of verified users or organizations.
- **Supported Assertion Types**:
  - `urn:ietf:params:oauth:token-type:id-jag` (Identity Assertion JWT Authorization Grant)
  - `verified_email` (Cryptographically verified operator email domain)
- **Credential Types**:
  - `api_key`
  - `bearer_token`
- **Claim Endpoint**: https://banglaverse.net/agent/auth/claim
- **Revocation Endpoint**: https://banglaverse.net/agent/auth/revoke
- **Events Supported**: `revocation`

---

## Scopes Supported

| Scope | Description |
| :--- | :--- |
| `read:server-status` | Query Minecraft server latency, TPS, and player count |
| `read:spark-analyzer` | Parse and optimize Spark profiler performance reports |
| `read:domain-pricing` | Query real-time TLD and .bd domain pricing |
| `manage:minecraft-servers` | Provision, configure, and scale game server instances |

---

## Endpoints

### 1. Agent Registration
- **Endpoint**: https://banglaverse.net/agent/auth/register
- **Methods**: `GET`, `HEAD`, `POST`, `OPTIONS`
- **Description**: Allows agents to register their identity, declare software capabilities, and request API credentials.
- **Required Fields**:
  - `agent_identifier`: Unique agent URI or name
  - `software_name`: Framework / runtime software name
  - `operator_legal_entity`: Name of operator or organization
  - `purpose`: Reason for integration (monitoring, management, optimization)
  - `expected_request_rate_per_hour`: Projected traffic volume
  - `public_contact`: Contact email or URL

### 2. Identifier Claim
- **Endpoint**: https://banglaverse.net/agent/auth/claim
- **Methods**: `GET`, `HEAD`, `POST`, `OPTIONS`
- **Description**: Proves control of an agent identifier or domain ownership via DNS TXT, email token, or signed assertion.
- **Required Fields**:
  - `agent_identifier`: The identifier being claimed
  - `proof_of_control`: DNS record or signed assertion

### 3. Grant & Credential Revocation
- **Endpoint**: https://banglaverse.net/agent/auth/revoke
- **Methods**: `GET`, `HEAD`, `POST`, `OPTIONS`
- **Description**: Immediately invalidates issued tokens, API keys, or agent registrations.
- **Required Fields**:
  - `agent_identifier`: The registered identifier
  - `reason`: Reason for revocation

---

## Credential Usage in Requests

When invoking protected APIs, transmit credentials in standard HTTP headers:

```http
GET /api/minecraft/servers HTTP/1.1
Host: banglaverse.net
Authorization: Bearer <access_token>
```

Or using an API key:

```http
GET /api/minecraft/servers HTTP/1.1
Host: banglaverse.net
Authorization: ApiKey <api_key>
```

---

## Machine-Readable Agent Auth Metadata

For automated parsers, the exact `agent_auth` configuration is:

```json
{
  "skill": "https://banglaverse.net/auth.md",
  "documentation_uri": "https://banglaverse.net/auth.md",
  "register_uri": "https://banglaverse.net/agent/auth/register",
  "claim_uri": "https://banglaverse.net/agent/auth/claim",
  "revocation_uri": "https://banglaverse.net/agent/auth/revoke",
  "identity_endpoint": "https://banglaverse.net/agent/auth/register",
  "claim_endpoint": "https://banglaverse.net/agent/auth/claim",
  "events_endpoint": "https://banglaverse.net/agent/auth/revoke",
  "events_supported": [
    "revocation"
  ],
  "contact": "support@banglaverse.net",
  "identity_types_supported": [
    "anonymous",
    "identity_assertion"
  ],
  "anonymous": {
    "credential_types_supported": [
      "none",
      "api_key"
    ],
    "claim_uri": "https://banglaverse.net/agent/auth/claim"
  },
  "identity_assertion": {
    "assertion_types_supported": [
      "urn:ietf:params:oauth:token-type:id-jag",
      "verified_email"
    ],
    "credential_types_supported": [
      "api_key",
      "bearer_token"
    ],
    "claim_uri": "https://banglaverse.net/agent/auth/claim",
    "revocation_uri": "https://banglaverse.net/agent/auth/revoke"
  }
}
```