"""Public sign-in guidance. OAuth discovery requires a real authorization server."""

from __future__ import annotations

AUTH_MD_PATH = "/auth.md"


def build_auth_md(
    origin: str,
    *,
    home_url: str = "https://p2hs.com",
    agent_enabled: bool = False,
    mcp_url: str = "https://mcp.p2hs.com/mcp",
    a2a_url: str = "https://dashboard.p2hs.com/a2a",
) -> str:
    """Describe the dashboard session flow without promising machine credentials."""
    public = origin.rstrip("/")
    home = home_url.rstrip("/")
    if agent_enabled:
        return f"""# P2HS auth.md

MCP endpoint: {mcp_url}
A2A endpoint: {a2a_url}
A2A agent card: {public}/.well-known/agent-card.json
Authorization server: {public}/.well-known/oauth-authorization-server

OAuth `resource` must be exactly the endpoint you are calling (the MCP URL
above for MCP, the A2A URL above for A2A) — each is a distinct audience, even
though both draw from the same workspace grant and scopes.

## Connect an assistant

Use OAuth authorization code with S256 PKCE. Register a public client at
{public}/api/agent-access/clients, then open {public}/agents/authorize with
client_id, redirect_uri, response_type=code, code_challenge,
code_challenge_method=S256, resource={mcp_url}, scope, and state.
The user signs in, completes required MFA, and approves one workspace,
permissions, project access, and expiry. Exchange the single-use code at
{public}/api/agent-access/token using an application/x-www-form-urlencoded
body. Include client_id, redirect_uri, code_verifier, and the exact resource.
Use the opaque access token as a Bearer header. Refresh tokens rotate on use;
replaying an old code or refresh token revokes the grant.

## Unattended service accounts

A workspace owner/admin creates an account at {public}/settings/agents.
Store its one-time client_secret securely. Request an access token at the same
token endpoint with grant_type=client_credentials, client_id (account ID),
client_secret, and resource={mcp_url}. Optional scope can reduce permissions.
This flow does not issue refresh tokens. Revocation takes effect on new calls.

## Tools, projects, and billing

Tools are listed according to the grant. Selected projects are the default;
workspace-wide access is optional. Created projects are added to the creating
grant. Builds use the existing subscription and credits. Mutations require a
request_key; reuse it with identical arguments after a network failure and poll
get_operation. Build completion is reported by get_build.

Credit checkout links require credits.checkout. Saved-card purchases require
credits.purchase and owner-approved per-purchase/monthly USD limits. Purchase
requests must supply the catalog amount and currency. Pending/uncertain charges
remain reserved against the cap; a payment needing cardholder action must be
resolved through checkout. No card details or provider secrets are exposed.

Never copy browser session cookies into an assistant. Revoke grants at
{public}/settings/agents. Already accepted work may continue after revocation.
"""
    return f"""# auth.md

P2HS builds websites and apps. This guide is for AI assistants helping a human
operator use their P2HS account. Anonymous agent accounts are not issued.

## Sign in and registration

Open {public}/login for an existing account. Start a new account at
{home}/signup. A person completes email verification, any required MFA,
and billing setup. Do not bypass these steps or access their mailbox.

The dashboard provisions accounts through POST {public}/api/auth/signup
and verifies email links through POST {public}/api/auth/magic/verify.
These are dashboard session endpoints, not OAuth authorization/token endpoints.
The dashboard stores credentials server-side and returns a session bootstrap;
clients must not expect raw access or refresh tokens from email verification.
Registration sends email and may create an account; do not invoke it as a probe.

## Agent connections

Delegated OAuth access, workspace-scoped service accounts, and hosted MCP are
being implemented. They are not available through the existing magic-link
session API. No OAuth issuer, OIDC support, or machine-access scopes are
advertised until the corresponding protocol endpoints are operational.
Do not copy browser cookies or request a human's refresh token for automation.

## Public documentation

- API catalog: {public}/.well-known/api-catalog
- Product facts: {home}/llms.txt
- Support: {home}/contact
- Privacy: {home}/privacy
- Terms: {home}/terms
"""