# Well-Known Paths

This document is the in-repo governance record for every `/.well-known/*` path published by this repository. It is documentation only. It does not approve path migrations or content changes.

## Scope

- Static source-controlled files live under `site/.well-known/`.
- Generated build artifacts currently include `/.well-known/ai/index.json` and `/.well-known/arp/index.sig`.
- OAuth metadata is served through Vercel rewrites to API handlers, not from static files.
- `/.well-known/ai/*` and `/.well-known/arp/*` are currently unregistered path families. They should migrate in a follow-up PR to `/.well-known/appspecific/...` names that comply with [RFC 8615](https://www.rfc-editor.org/rfc/rfc8615.html).

## Reverse-DNS Choice

This repo should use `org.openagreements` for future `appspecific` migrations.

Why:

- The product-facing host and API origin are `openagreements.org`.
- The repo and published artifacts are branded as OpenAgreements even when operated by UseJunior.
- Internal namespace precedent already uses `org.openagreements.*` in repo-managed identifiers such as `concerto/*.cto` and `scripts/migrate_metadata_to_concerto.mjs`.
- `site/.well-known/ai/entity.json` still names `https://usejunior.com/.well-known/ai/entity.json` as the canonical entity URL and identifies UseJunior as the operator, but that reads as operator ownership, not the stronger reverse-DNS naming convention for the OpenAgreements product namespace.

## Inventory

| Path | Registered? | Current source / generator | Action in this PR |
| --- | --- | --- | --- |
| `/.well-known/oauth-authorization-server` | Yes — [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414.html) | Dynamic handler: `api/auth/well-known-oauth-as.ts` via `vercel.json` rewrite | Document only; do not change |
| `/.well-known/oauth-protected-resource` | Yes — [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728.html) | Dynamic handler: `api/auth/well-known-protected-resource.ts` via `vercel.json` rewrite | Document only; do not change |
| `/.well-known/agent-card.json` | Yes — [IANA Well-Known URIs registry](https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml), [A2A spec](https://a2a-protocol.org/latest/specification/) | Static file: `site/.well-known/agent-card.json` | Document only; do not change |
| `/.well-known/api-catalog` | Yes — [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727.html) | Static file: `site/.well-known/api-catalog` | Document only; do not change |
| `/.well-known/mcp-server-card` | No — track [SEP-1649](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649) only | Static file: `site/.well-known/mcp-server-card` | Document only; no migration in this PR |
| `/.well-known/ai/entity.json` | No | Static file: `site/.well-known/ai/entity.json` | Document current state; migration later |
| `/.well-known/ai/index.json` | No | Generated by `scripts/build-wellknown-ai-index.cjs` into `_site/.well-known/ai/index.json` | Document current state; migration later |
| `/.well-known/arp/pubkey.json` | No | Static file: `site/.well-known/arp/pubkey.json` | Document current state; migration later |
| `/.well-known/arp/index.sig` | No | Generated by `scripts/sign-manifest.cjs` into `_site/.well-known/arp/index.sig` | Document current state; migration later |

## Path Records

### `/.well-known/oauth-authorization-server`

- Path: `/.well-known/oauth-authorization-server`
- Registered?: Yes. Defined and registered by [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414.html).
- Schema: OAuth 2.0 Authorization Server Metadata JSON per RFC 8414.
- Generator: Dynamic response from `api/auth/well-known-oauth-as.ts`, reached through the rewrite in `vercel.json`.
- Header / Content-Type expectations: No `headers` block in `vercel.json`; the API handler sets `Content-Type: application/json`, `Cache-Control: public, max-age=3600`, and `Access-Control-Allow-Origin: *`.
- Expected consumers: OAuth-aware MCP clients and any client discovering the OpenAgreements authorization server.
- Open issues: None in this PR. Do not change the path.

### `/.well-known/oauth-protected-resource`

- Path: `/.well-known/oauth-protected-resource`
- Registered?: Yes. Defined and registered by [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728.html).
- Schema: OAuth 2.0 Protected Resource Metadata JSON per RFC 9728.
- Generator: Dynamic response from `api/auth/well-known-protected-resource.ts`, reached through the rewrite in `vercel.json`.
- Header / Content-Type expectations: No `headers` block in `vercel.json`; the API handler sets `Content-Type: application/json`, `Cache-Control: public, max-age=3600`, and `Access-Control-Allow-Origin: *`.
- Expected consumers: OAuth-aware MCP clients discovering resource metadata for `api/mcp`.
- Open issues: None in this PR. Do not change the path.

### `/.well-known/agent-card.json`

- Path: `/.well-known/agent-card.json`
- Registered?: Yes. Registered in the [IANA Well-Known URIs registry](https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml) with the A2A specification as the reference.
- Schema: A2A Agent Card JSON as defined by the [A2A specification](https://a2a-protocol.org/latest/specification/).
- Generator: None. This is a source-controlled static artifact at `site/.well-known/agent-card.json`.
- Header / Content-Type expectations: No explicit `headers` rule in `vercel.json`; as a static `.json` file it is expected to be served as JSON with platform-default cache and CORS behavior.
- Expected consumers: A2A clients discovering the OpenAgreements agent endpoint at `https://openagreements.org/api/a2a`.
- Open issues: The current card is intentionally unchanged in this PR, but it still has an A2A conformance TODO for missing `preferredTransport`.

### `/.well-known/api-catalog`

- Path: `/.well-known/api-catalog`
- Registered?: Yes. Defined and registered by [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727.html).
- Schema: API Catalog document in the RFC 9727 linkset format. The current file is a Linkset JSON document with `service-desc` links to the MCP and A2A discovery documents.
- Generator: None. This is a source-controlled static artifact at `site/.well-known/api-catalog`.
- Header / Content-Type expectations: `vercel.json` sets `Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"`, `Cache-Control: public, max-age=3600`, `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Methods: GET`, and `Access-Control-Allow-Headers: Content-Type`.
- Expected consumers: Generic API discovery clients, linkset-aware tooling, and crawlers looking for published APIs.
- Open issues: The path itself is correct and must not change in this PR. A separate bug exists in `scripts/build-wellknown-ai-index.cjs`, which incorrectly looks for `.well-known/api-catalog/index.json` instead of the extensionless published file.

### `/.well-known/mcp-server-card`

- Path: `/.well-known/mcp-server-card`
- Registered?: No. There is no IANA registration for this suffix today. The current reference point is [SEP-1649](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649), which proposes `/.well-known/mcp/server-card.json` instead.
- Schema: MCP server card JSON. The current file follows the older static schema URL embedded in the artifact, not the SEP-1649 discovery path.
- Generator: None. This is a source-controlled static artifact at `site/.well-known/mcp-server-card`.
- Header / Content-Type expectations: `vercel.json` sets `Content-Type: application/json`, `Cache-Control: public, max-age=3600`, `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Methods: GET`, and `Access-Control-Allow-Headers: Content-Type`.
- Expected consumers: MCP registries, discovery tools, and clients that probe server metadata before opening `https://openagreements.org/api/mcp`.
- Open issues: No migration in this PR. Follow-up work should move toward the SEP-1649 path `/.well-known/mcp/server-card.json` if and when that draft becomes the project’s chosen target.

### `/.well-known/ai/entity.json`

- Path: `/.well-known/ai/entity.json`
- Registered?: No. This path is currently unregistered.
- Schema: Repo-defined JSON identity document. Today it contains OpenAgreements branding, domains, canonical URL, operator metadata, and related links. There is no external IANA registration or in-repo spec beyond this document.
- Generator: None. This is a source-controlled static artifact at `site/.well-known/ai/entity.json`.
- Header / Content-Type expectations: No explicit `headers` rule in `vercel.json`; as a static `.json` file it is expected to be served as JSON with platform-default cache and CORS behavior.
- Expected consumers: AI discovery systems and any verifier or crawler that starts from the OpenAgreements entity description.
- Open issues: This path is currently unregistered. The RFC 8615 compliant migration target should be `/.well-known/appspecific/org.openagreements.ai.entity.json`. Migration is a separate PR.

### `/.well-known/ai/index.json`

- Path: `/.well-known/ai/index.json`
- Registered?: No. This path is currently unregistered.
- Schema: Repo-defined ARP-style manifest JSON with `version`, `generatedAt`, `lastUpdated`, `description`, `entity`, `pubkey`, and `integrity` fields. There is no external IANA registration or in-repo spec beyond this document.
- Generator: `scripts/build-wellknown-ai-index.cjs`, which writes `_site/.well-known/ai/index.json` after Eleventy passthrough of `site/.well-known/`.
- Header / Content-Type expectations: No explicit `headers` rule in `vercel.json`; as a generated `.json` file it is expected to be served as JSON with platform-default cache and CORS behavior.
- Expected consumers: Clients verifying OpenAgreements identity metadata and integrity bindings across `entity.json`, `pubkey.json`, and other AI-facing discovery artifacts.
- Open issues: This path is currently unregistered. The RFC 8615 compliant migration target should be `/.well-known/appspecific/org.openagreements.ai.index.json`. Migration is a separate PR. Also, `scripts/build-wellknown-ai-index.cjs` currently looks for `.well-known/api-catalog/index.json` and `.well-known/mcp-server-card/index.json`, but the repo publishes extensionless `/.well-known/api-catalog` and `/.well-known/mcp-server-card`. The generator path is wrong, so those integrity hashes are currently skipped.

### `/.well-known/arp/pubkey.json`

- Path: `/.well-known/arp/pubkey.json`
- Registered?: No. This path is currently unregistered.
- Schema: Repo-defined JSON key descriptor containing the active Ed25519 public key, key identifiers, validity windows, and rotation policy text. There is no external IANA registration or in-repo spec beyond this document.
- Generator: None. This is a source-controlled static artifact at `site/.well-known/arp/pubkey.json`.
- Header / Content-Type expectations: No explicit `headers` rule in `vercel.json`; as a static `.json` file it is expected to be served as JSON with platform-default cache and CORS behavior.
- Expected consumers: Verifiers validating detached signatures for the AI manifest.
- Open issues: This path is currently unregistered. The RFC 8615 compliant migration target should be `/.well-known/appspecific/org.openagreements.arp.pubkey.json`. Migration is a separate PR.

### `/.well-known/arp/index.sig`

- Path: `/.well-known/arp/index.sig`
- Registered?: No. This path is currently unregistered.
- Schema: Repo-defined detached signature envelope with `algo`, `kid`, `canonicalization`, `manifest`, `signedAt`, `expiresAt`, and base64 `signature` fields. Despite the `.sig` filename, the current payload is JSON.
- Generator: `scripts/sign-manifest.cjs`, which signs `_site/.well-known/ai/index.json` and writes `_site/.well-known/arp/index.sig`.
- Header / Content-Type expectations: No explicit `headers` rule in `vercel.json`. Because the filename is `.sig` while the payload is JSON, platform-default content-type behavior may not match the actual envelope format.
- Expected consumers: Verifiers checking the detached signature for `/.well-known/ai/index.json`.
- Open issues: This path is currently unregistered. The RFC 8615 compliant migration target should be `/.well-known/appspecific/org.openagreements.arp.index.sig`. Migration is a separate PR. A future cleanup should also decide whether the published filename or content type should better advertise that the payload is JSON.

## Future / referenced but not yet served

The following path is referenced by current rotation policy but is not published by this repository today.

### `/.well-known/arp/pubkey-next.json`

- Path: `/.well-known/arp/pubkey-next.json`
- Status: Not currently served. There is no `site/.well-known/arp/pubkey-next.json` source file, no `vercel.json` rewrite, and no generator that publishes this path today.
- Registered?: No. This path is currently unregistered.
- Schema: Intended to match the repo-defined public-key descriptor schema used by `pubkey.json`.
- Why it is referenced: The `rotationPolicy` field in `site/.well-known/arp/pubkey.json` names this path as the future replacement-key location for planned rotation.
- Header / Content-Type expectations: If published later as a `.json` file, it would inherit platform-default headers unless a future PR adds explicit overrides.
- Expected consumers: Key-rotation verifiers that need the next signing key before cutover.
- Open issues: This path is currently unregistered. The RFC 8615 compliant migration target should be `/.well-known/appspecific/org.openagreements.arp.pubkey-next.json`. The file should be created in separate work when key rotation is implemented.
