# OpenID — Solid identity for AI agents

> OpenID gives each person and agent a WebID, a Solid pod, and a tamper-evident audit trail. The hosted passport at https://identity-p25umfjqo-hewlberns-projects.vercel.app lets you mint short-lived MCP tokens and save Codex / Cursor / Claude / Grok / Gemini Spark traces into `{handle}/conversations/spark/`.

This is not a robot workshop. Do not invent credentials, WebIDs, or tokens.

## Base URL
https://identity-p25umfjqo-hewlberns-projects.vercel.app

## Remote MCP (Cursor / Codex / Claude / Grok / Gemini Spark)

Canonical Streamable HTTP endpoint:

- https://identity-p25umfjqo-hewlberns-projects.vercel.app/mcp
- Alias: https://identity-p25umfjqo-hewlberns-projects.vercel.app/api/mcp

CORS: `*`. Auth: `Authorization: Bearer <TOKEN>` from a copied OpenID / agent prompt (`POST /api/agent/session`) or a 30-day Spark connect token (`POST /api/spark-token`).

### Tools
- `spark_save_conversation` — write the current thread to the caller's pod. Args: title, messages [{role, content|text, timestamp?}], optional source / source_url / text.
- `spark_list_conversations` — list `{handle}/conversations/spark/`.
- `spark_get_conversation` — read one saved conversation by id.
- `spark_share_conversation` — mint a public `/share/c/{token}` snapshot.
- `spark_unshare_conversation` — revoke that snapshot.

A Spark connect token (`aud: spark-mcp`, `scope: spark`) can only call these `spark_*` tools and read/write **your** `{handle}/conversations/` container. It cannot mint more tokens or write another pod.

## Agent prompt APIs

### GET /api/agent/prompt
Current copyable agent instructions. No token is minted. CORS `*`.

### POST /api/agent/session
Signed-in browser only (session Bearer or `solid-session` cookie). Returns `{ prompt, token, expiresAt, tokenKind }`. Dedicated agent JWT (~30m) when `AGENT_JWT_SECRET` (or `OPENID_SPARK_SECRET`) is set; otherwise the session access token. Never a service-role key. The yellow PROMPT dock remints on each copy.

### GET /llms.txt
This document.

## Conversation APIs (owner-only, CORS *)

Send `Authorization: Bearer <TOKEN>` from a copied OpenID prompt, or use the signed-in cookie / session Bearer.

- `GET /api/spark-conversations` — list saved traces
- `POST /api/spark-conversations` — create from `{ title?, messages?, text?, source?, source_url? }`
- `POST /api/spark-conversations/{id}/share`
- `POST /api/spark-conversations/{id}/unshare`
- `GET /share/c/{token}` — public read-only snapshot (logged-out)

Spark tokens are unwrapped to the session Bearer before LDP writes. On 401, ask the owner to copy a new OpenID / agent prompt.

## Spark connect tokens

- `POST /api/spark-token` — session required → 30-day `{ token, expires, jti, mcpUrl, webId }`
- `GET /api/spark-token` — list active grants (no secret)
- `DELETE /api/spark-token` — revoke all, or `?jti=`

Prefer the short-lived agent session for Codex / Cursor. Use the 30-day Spark token for a standing Gemini Spark connection.

## Identity

- `POST /idp/register` — handle + password (creates WebID + pod)
- `POST /idp/login` — handle or email + password
- `GET /api/auth/google` — Continue with Google (start; lands on /app via `/auth/callback`)
- `POST /idp/google` — pod-side Google ID token exchange (Railway)
- `GET /idp/accounts/me` — current account

## Agent recipe

1. `GET https://identity-p25umfjqo-hewlberns-projects.vercel.app/llms.txt` and `GET https://identity-p25umfjqo-hewlberns-projects.vercel.app/api/agent/prompt` if you need fresh instructions.
2. Use the Bearer from the prompt the human copied (do not call `POST /api/agent/session` yourself).
3. `spark_save_conversation` (or `POST /api/spark-conversations`) with the full transcript. Set `source` to the tool you are (codex, cursor, claude, grok, gemini-spark).
4. Sequential single-op commits. Wait for `resourceUrl`.
5. Send the human https://identity-p25umfjqo-hewlberns-projects.vercel.app/app (and a share URL only if they asked).
6. On 401, ask them to remint from /app.

## Human UI

- Passport: https://identity-p25umfjqo-hewlberns-projects.vercel.app/app — signed-in save / list / share, Spark connect, **Open / agent prompt** copy dock
- Landing: https://identity-p25umfjqo-hewlberns-projects.vercel.app/ — claim a handle or Continue with Google
- Records: https://identity-p25umfjqo-hewlberns-projects.vercel.app/records
- Public handle: https://identity-p25umfjqo-hewlberns-projects.vercel.app/i/{handle}
- Solid server console: https://identity-p25umfjqo-hewlberns-projects.vercel.app/dashboard