# FundWise auth.md

FundWise supports agent auth discovery for wallet-native Group money workflows. This file is safe to fetch without authentication and describes how agents should register or obtain user-mediated access today.

## Discovery

- OAuth Protected Resource Metadata: https://fundwise.pages.dev/.well-known/oauth-protected-resource
- OAuth Authorization Server metadata: https://fundwise.pages.dev/.well-known/oauth-authorization-server
- Agent Skill Endpoint: https://fundwise.pages.dev/skill.md
- A2A Agent Card: https://fundwise.pages.dev/.well-known/agent-card.json
- API docs: https://fundwise.pages.dev/api/docs
- OpenAPI service description: https://fundwise.pages.dev/api/openapi.json

## Supported registration method

### anonymous public discovery

Public discovery documents do not require registration or credentials. Agents may claim the anonymous discovery method by fetching this document and following the linked API catalog, Agent Skill Endpoint, A2A Agent Card, and OAuth metadata.

Identity type: `anonymous`

Claim URI: `https://fundwise.pages.dev/auth.md`

Credential type: `none`

Scope: `public:discovery`

This method does not authorize protected Group data, Expense data, Settlement data, Receipt data, writes, or money movement.

### wallet_signature

FundWise identity is a Solana wallet public key. Current protected API access uses a human-present wallet signature that creates an HTTP-only same-origin browser session cookie.

1. `POST https://fundwise.pages.dev/api/auth/wallet/challenge` with `{ "wallet": "<solana-pubkey>" }`.
2. Ask the user to sign the returned `message` with the same wallet.
3. `POST https://fundwise.pages.dev/api/auth/wallet/verify` with `{ "wallet": "<solana-pubkey>", "signature": "<base64-signature>" }`.
4. Use the resulting browser session cookie on protected FundWise API calls.
5. `GET https://fundwise.pages.dev/api/auth/wallet/session` to inspect the active session.

Credential type: `http_only_session_cookie`

Claim URI: `https://fundwise.pages.dev/api/auth/wallet/challenge`

Revocation URI: `https://fundwise.pages.dev/api/auth/wallet/session`

Proof type: `solana_sign_message`

User presence: required.

Credential transport: browser cookie. Do not expect a reusable third-party bearer token from this flow.

## Current agent access boundary

Agents may read or draft only after a Member has granted access through a wallet-authenticated flow or, for Fundy, through the Telegram link flow documented in `https://fundwise.pages.dev/api/docs`.

Agents must not move USDC, sign transactions, record Settlements, execute Contributions, or execute Fund Mode Proposal payouts without sending the Member back to the FundWise web app and wallet confirmation.

## Planned registration method

Scoped Agent Access is planned but not generally available in the FundWise web app yet. It will issue Member-granted credentials scoped by wallet, Group, action type, expiry, and revocation. Until that ships, third-party agents should treat the wallet-signature browser session and the public discovery documents as the only supported FundWise auth surface.

## Scopes

- `groups:read`
- `expenses:read`
- `settlements:read`
- `expenses:write`
- `profile:write`
- `settlements:record`
- `proposals:write`

These scopes describe the current API surface and planned Scoped Agent Access grants. Current wallet sessions are enforced by wallet identity, Group membership, ownership checks, and route-specific authorization.

## Revocation

There is no public third-party agent revocation endpoint today because FundWise does not yet issue standalone third-party agent credentials. If a wallet session fails with `401`, restart at discovery and wallet verification. Future Scoped Agent Access credentials will include explicit revocation.

## Safety rules

- Never ask for private keys or seed phrases.
- Never ask users for `FUNDWISE_SERVICE_API_KEY`; that key is only for the hosted Fundy service.
- Never treat natural-language approval as authorization to move funds.
- Never bypass FundWise HTTP APIs by calling Supabase directly.