# auth.md — Better2Better Agent & Client Authentication Guide

Better2Better (B2 Technology) exposes public AI discovery, engineering documentation, WebMCP browser tools, RSS feeds, and sitemaps without authentication (`catalog:read`), while client project management and administrative workspaces use authenticated sessions backed by Firebase Authentication / OIDC.

- **Resource Server (Base Origin):** `https://better2better.com.br`
- **Authorization Portal (Interactive):** `https://better2better.com.br/auth`
- **Registration Portal (Human / Assisted):** `https://better2better.com.br/auth?mode=register`

---

## Step 1 — Discover OAuth & Protected Resource Metadata

Agents and automated clients can inspect machine-readable authentication and catalog metadata at standardized well-known endpoints:

1. **Protected Resource Metadata (RFC 9728):** `https://better2better.com.br/.well-known/oauth-protected-resource`
2. **OAuth Authorization Server Metadata (RFC 8414):** `https://better2better.com.br/.well-known/oauth-authorization-server`
3. **OpenID Connect Discovery 1.0:** `https://better2better.com.br/.well-known/openid-configuration`
4. **WebMCP Interactive Browser Tools:** `https://better2better.com.br/.well-known/mcp.json` & `https://better2better.com.br/.well-known/mcp/server-card.json`

---

## Step 2 — Anonymous Public Discovery vs. Client Portal Access

### A. Unauthenticated Public Access (`catalog:read`)
No credentials are required for public documentation, White-Label catalogs, CaaS specifications, Markdown endpoints (`*.md`), blog search feeds (`rss*.xml`), brand verification (`/.well-known/brand-facts.json`), or client-side WebMCP tools.

### B. Client Portal Authentication (`projects:read`, `projects:write`)
Client portal endpoints (`/dashboard`) require a valid Firebase ID token obtained via user authentication at `https://better2better.com.br/auth` (email/password or recovery via `/reset-password`).
Tokens are signed (`RS256`) and verifiable via `https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com`.

### C. WebMCP Declarative Auth Actions
When running inside a WebMCP-enabled browser on `https://better2better.com.br/auth`:
- `authenticate_client_portal`
- `register_client_account`
- `request_password_recovery`

---

## Supported Scopes

- `catalog:read` — Public technical documentation, Markdown endpoints, RSS feeds, and WebMCP read-only tools.
- `openid`, `profile`, `email` — User identity claims in authenticated client portal sessions.
- `projects:read`, `projects:write` — Client project status inspection and change requests inside `/dashboard`.

---

## Support & Governance

- **Terms of Service & SLA:** `https://better2better.com.br/termos`
- **Privacy Policy (LGPD):** `https://better2better.com.br/privacidade`
- **Corporate Registration:** CNPJ `57.498.282/0001-16` — Av. Paulista, 1000, São Paulo/SP, Brazil
- **Security & Agent Support:** `diegooris@better2better.com.br`
