# auth.md — Calm Merge Agent Registration & Authentication

This document describes how AI agents can discover, register, and authenticate to interact with Calm Merge (https://calmmerge.com).

## Audience

This document is for AI agents and automation systems that want to read Calm Merge content or call its public APIs. It is published under the [Auth.md](https://workos.com/auth-md) convention.

## Supported Access

Calm Merge is a free public web application. Most features — guided meditation, breathing exercises, soundscapes, the meditation timer, and all articles — require **no authentication**. Public, anonymous access is the default.

Optional user-scoped features (session journaling, cross-device sync, streaks) use **Google Sign-In** (OAuth 2.0 / OpenID Connect).

## Discovery Metadata

Calm Merge publishes the following discovery documents:

- `/.well-known/oauth-protected-resource` — Protected Resource Metadata (RFC 9728); `authorization_servers: ["https://calmmerge.com"]`.
- `/.well-known/oauth-authorization-server` — OAuth 2.0 Authorization Server Metadata (RFC 8414) with issuer `https://calmmerge.com`; contains the `agent_auth` block below.
- `/.well-known/openid-configuration` — OpenID Connect Discovery for the underlying identity provider.
- `/.well-known/api-catalog` — RFC 9727 API catalog (linkset).

## agent_auth (registration)

The following is the `agent_auth` block published at `/.well-known/oauth-authorization-server`:

```json
{
  "agent_auth": {
    "skill": "https://calmmerge.com/auth.md",
    "register_uri": "https://calmmerge.com/auth.md",
    "claim_uri": "https://calmmerge.com/api/auth/claim",
    "revocation_uri": "https://calmmerge.com/api/auth/revoke",
    "identity_types_supported": ["identity_assertion", "anonymous"],
    "identity_assertion": {
      "assertion_types_supported": [
        "urn:ietf:params:oauth:token-type:id-jag",
        "verified_email"
      ],
      "credential_types_supported": ["jwt", "google-id-token"],
      "claim_uri": "https://calmmerge.com/api/auth/claim"
    },
    "anonymous": {
      "credential_types_supported": ["none"],
      "claim_uri": "https://calmmerge.com/api/auth/claim"
    }
  }
}
```

`register_uri` is the starting point for agent registration. Both `identity_assertion` (verified-email) and `anonymous` registrations use the claim ceremony at `claim_uri`: an agent sends a claim request, the user confirms a code on a Calm Merge page, and the agent polls for the resulting assertion.

## Registration Flow

1. **Discover** — fetch `/.well-known/oauth-protected-resource`, then follow `authorization_servers[0]` to `/.well-known/oauth-authorization-server` and read the `agent_auth` block above.
2. **Pick a method** — `identity_assertion` (ID-JAG or verified email) or `anonymous`.
3. **Register** — POST to `register_uri` (`https://calmmerge.com/auth.md`) with the chosen identity type.
4. **Claim** — for verified-email and anonymous flows, POST to `claim_uri` (`https://calmmerge.com/api/auth/claim`) to start the code-confirmation ceremony; the agent surfaces the returned `user_code` and `verification_uri` to the user, who confirms on a Calm Merge page.
5. **Authenticate** — present the resulting assertion as a bearer token in the `Authorization: Bearer <token>` header on API requests.

## Credential Use

- **Anonymous (recommended):** GET requests to `https://calmmerge.com/*` and `https://calmmerge.com/.well-known/*` need no credentials.
- **Authenticated (user-scoped):** an agent acting on behalf of a human may obtain a Google ID token via the OAuth flow and present it as a bearer token in the `Authorization: Bearer <token>` header. Tokens are verified against the Google JWKS at `https://www.googleapis.com/oauth2/v3/certs`; revocation requests go to `https://calmmerge.com/api/auth/revoke`.

## Contact

- Website: https://calmmerge.com
- Email: hello@calmmerge.com
- AI-readable site documentation: https://calmmerge.com/llms.txt