Merge pull request 'docs: document using Gitea as the OAuth issuer' (#70) from docs/gitea-oauth-issuer into dev

Reviewed-on: #70

.env.example

@@ -26,10 +26,20 @@ FAMILIAR_HTTP_TOKEN=
 # FAMILIAR_ALLOW_INSECURE_BIND=false
 
 # --- OAuth 2.1 resource server (only when FAMILIAR_AUTH_MODE=oauth) --------- #
+# familiar only validates JWTs; the login/DCR side lives in an external IdP.
 # FAMILIAR_OAUTH_ISSUER=https://idp.example.com/application/o/familiar/
 # FAMILIAR_OAUTH_RESOURCE=https://familiar.example.com   # this server's public URL
 # FAMILIAR_OAUTH_AUDIENCE=https://familiar.example.com   # defaults to RESOURCE
 # FAMILIAR_OAUTH_JWKS_URI=                               # optional; else discovered from issuer
+#
+# Using Gitea as the issuer (RS256 JWTs + JWKS + OIDC discovery — config only,
+# see doc/deployment.md). Register an OAuth2 app in Gitea first; Gitea puts the
+# app's CLIENT ID in the token `aud`, so set AUDIENCE to that, not the resource.
+# NOTE: Gitea has no Dynamic Client Registration — works for clients with a
+# pre-registered client ID/secret, but NOT the claude.ai web connector (needs DCR).
+# FAMILIAR_OAUTH_ISSUER=https://gitea.example.com        # no trailing /login/oauth
+# FAMILIAR_OAUTH_RESOURCE=https://familiar.example.com
+# FAMILIAR_OAUTH_AUDIENCE=<gitea-oauth-app-client-id>
 
 # --- Data / writes --------------------------------------------------------- #
 # Host path holding the encrypted token store (token.enc + key), audit log, and

CLAUDE.md

@@ -22,13 +22,15 @@ uv run familiar login         # browser EVE SSO login (adds a character; run onc
 uv run familiar login --no-browser  # headless login: paste the callback URL on stdin
 uv run familiar status        # list logged-in characters
 uv run familiar writes disable # block write actions (default: enabled on stdio, disabled on HTTP)
+uv run familiar sde download  # download + install the local SDE for offline name/type lookups
+uv run familiar sde status    # is the local SDE present, and where (also: sde path)
 ```
 
 There is no separate build step; `uv build` produces the wheel (CI does this on merge).
 
 ## Architecture
 
-**Server assembly.** [src/familiar/server.py](src/familiar/server.py) creates the single `FastMCP` instance and calls `register(mcp)` on each tool module. Every tool module (market, universe, account, industry, trade, structures, killmails, profile, corp, corp_economy, misc, comms, contacts, fittings, fleet, ui, planets, writes) follows the same shape: **module-level async functions** + a `TOOLS` list + `register(mcp)` that loops `mcp.tool(fn)`. Tools are plain importable functions (so tests call them directly); registration is separate. To add tools: new module → import + register in server.py.
+**Server assembly.** [src/familiar/server.py](src/familiar/server.py) creates the single `FastMCP` instance and calls `register(mcp)` on each tool module. Every tool module (market, universe, account, industry, trade, structures, killmails, profile, corp, corp_economy, misc, comms, contacts, fittings, fleet, ui, planets, sde, writes) follows the same shape: **module-level async functions** + a `TOOLS` list + `register(mcp)` that loops `mcp.tool(fn)`. Tools are plain importable functions (so tests call them directly); registration is separate. To add tools: new module → import + register in server.py.
 
 **Transport (stdio default, opt-in HTTP).** `familiar` (no args) runs `mcp.run()` over **stdio** (how Claude launches it) — local, no auth. `familiar serve` runs `server.serve_http()`: the FastMCP **streamable-HTTP** transport bound to loopback (`FAMILIAR_HTTP_HOST`/`FAMILIAR_HTTP_PORT`/`FAMILIAR_HTTP_PATH`, default `127.0.0.1:8080/mcp`) behind a TLS reverse proxy, for remote MCP clients (Mistral, Claude web/desktop/code, VS Code — see [doc/clients/](doc/clients/)). An unauthenticated `GET /healthz` liveness route (returns only status/server/version) is served for Docker/proxy probes. This transport-level auth is separate from the EVE-SSO/ESI auth in auth.py.
 
@@ -41,6 +43,8 @@ Either mode calls `writes.set_http_context(True)`, flipping the **write default
 
 **ESI access.** [esi.py](src/familiar/esi.py) is a thin async httpx wrapper (`client()` singleton, `get/post/put/delete`, `get_all_pages` for `X-Pages` pagination, Bearer `token=` for authed calls, uniform `EsiError`). Base URL and datasource are env-overridable. [zkill.py](src/familiar/zkill.py) mirrors it for zKillboard. Both expose `set_client()` so tests inject an `httpx.MockTransport`.
 
+**Name resolution & offline SDE.** Callers pass human names ("Tritanium", "Jita"), not numeric IDs. [lookup.py](src/familiar/lookup.py) `resolve_name(name, *categories)` resolves them against ESI's `/universe/ids/`. [hubs.py](src/familiar/hubs.py) hardcodes the major NPC trade hubs (Jita/Amarr/Dodixie/Rens/Hek) with their stable region/system/station IDs so the common "price in Jita" case skips a lookup. [sde.py](src/familiar/sde.py) is an **optional** local SQLite copy of EVE's Static Data Export (path from `FAMILIAR_SDE_PATH`, else `data_dir()/sde.sqlite`) that backs offline name/type resolution; every accessor degrades gracefully — `sde.available()` returns `False` when the file or a needed table is absent, and callers fall back to ESI. `sde` also registers one tool (`sde_status`); the `familiar sde` CLI downloads/installs it.
+
 **Auth is multi-character.** [auth.py](src/familiar/auth.py) does EVE SSO PKCE (no client secret), stores a **dict of characters keyed by id** in one Fernet-encrypted file (`load_store`/`_save_character`/`list_characters`/`remove_character`), and `get_auth(character_id)` returns a valid access token, refreshing via the rotating refresh token when near expiry. The legacy single-character file is migrated on load. Config (client id, callback `localhost:8765`, the 73 read+write scopes split into `READ_SCOPES`/`WRITE_SCOPES`) lives in [config.py](src/familiar/config.py), all env-overridable.
 
 **Per-character / per-corp pattern.** [charutil.py](src/familiar/charutil.py) is the backbone of every authenticated tool. `run_per_character(character, fetch)` runs a fetcher for one named character or **all** logged-in ones (when `character` is None), returning a uniform `{"characters": [...]}`. `run_per_corp` additionally resolves each character's `corporation_id` (corp endpoints need the right corp role or ESI 403s). `one_token` picks a single token for thing-scoped lookups (e.g. a structure). `summarize(items, limit)` gives `{count, sample}`. account.py and all read modules build on these.

README.md

@@ -1,4 +1,4 @@
-# familiar
+ # familiar
 
 > Your familiar across New Eden — an EVE Online MCP server that lets a local AI see your whole account and the universe, and act on your behalf when you ask.
 

doc/clients/claude-web.md

@@ -4,6 +4,8 @@
 
 The claude.ai custom-connector flow speaks **OAuth 2.1 with Dynamic Client Registration (DCR)** and does **not** accept a static bearer token. familiar itself is only a **resource server** — it validates JWTs and advertises where to authenticate, but it is **not** an authorization server and does no DCR. So Claude web needs an external IdP that supports DCR (e.g. **Authentik** or **Keycloak**) sitting in front.
 
+> **Gitea won't work here.** Gitea is a fine OAuth issuer for familiar in general (see [deployment.md → Using Gitea as the OAuth issuer](../deployment.md)), but it has **no** Dynamic Client Registration, which this connector requires. Use it only with clients that take a pre-registered client ID/secret, or put a DCR-capable IdP in front.
+
 > **Simpler alternative:** if you don't want to run an IdP, use the **Claude Desktop** app with a bearer token instead — see [Connect Claude Desktop](claude-desktop.md). Bearer is easier for every client except the claude.ai web connector.
 
 ## 1. Set up the IdP (external)

doc/deployment.md

@@ -20,7 +20,26 @@ Once it's running, see [doc/clients/](clients/) for exact per-client setup.
 `FAMILIAR_AUTH_MODE` picks how the HTTP transport authenticates:
 
 - **`bearer`** (default) — one static token in `FAMILIAR_HTTP_TOKEN`. Simple, and every client below except Claude web supports it. Recommended.
-- **`oauth`** — familiar runs as an OAuth 2.1 **resource server**: it validates incoming JWT access tokens against an external issuer's JWKS and serves `/.well-known/oauth-protected-resource/<path>` so OAuth-only clients can discover the authorization server. familiar is **not** an authorization server and does **no** Dynamic Client Registration — you must run an external IdP that does (Authentik, Keycloak, …). Only needed for the native **Claude web** connector. See [doc/clients/claude-web.md](clients/claude-web.md).
+- **`oauth`** — familiar runs as an OAuth 2.1 **resource server**: it validates incoming JWT access tokens against an external issuer's JWKS and serves `/.well-known/oauth-protected-resource/<path>` so OAuth-only clients can discover the authorization server. familiar is **not** an authorization server and does **no** Dynamic Client Registration (DCR) — the authorization side lives in an external IdP (Authentik, Keycloak, Gitea, …). Only needed for OAuth-only clients such as the native **Claude web** connector. See [doc/clients/claude-web.md](clients/claude-web.md).
+
+### Using Gitea as the OAuth issuer
+
+Gitea can act as the IdP for `oauth` mode — no code change, config only. Gitea is already an OIDC provider: it signs access tokens as **RS256 JWTs** (default), publishes its keys at `https://gitea.example.com/login/oauth/keys`, and serves OIDC discovery at `https://gitea.example.com/.well-known/openid-configuration`, so familiar's `JWTVerifier` can validate its tokens.
+
+1. In Gitea, **Settings → Applications → Create OAuth2 application** (or admin-wide under **Site Administration → Applications**). Set the redirect URI(s) your MCP client needs. Note the generated **client ID** and **secret**.
+2. Point familiar at Gitea:
+
+   ```bash
+   FAMILIAR_AUTH_MODE=oauth
+   FAMILIAR_OAUTH_ISSUER=https://gitea.example.com          # no trailing /login/oauth
+   FAMILIAR_OAUTH_RESOURCE=https://familiar.example.com     # this server's public URL
+   FAMILIAR_OAUTH_AUDIENCE=<gitea-oauth-app-client-id>      # Gitea sets aud to the client ID, not the resource URL
+   # FAMILIAR_OAUTH_JWKS_URI is discovered from the issuer's OIDC metadata; leave unset.
+   ```
+
+   `FAMILIAR_OAUTH_AUDIENCE` matters: Gitea puts the OAuth **application's client ID** in the token's `aud`, which differs from familiar's default (the resource URL). If you get *invalid token / audience mismatch*, decode a real access token (`jwt.io`) and set `FAMILIAR_OAUTH_AUDIENCE` to whatever its `aud` actually is.
+
+> **Caveat — no DCR.** Gitea does **not** support Dynamic Client Registration. Clients that let you paste a pre-registered client ID/secret (Claude Desktop/Code, VS Code, your own scripts) work fine with Gitea. The **claude.ai web** custom connector *requires* DCR, so Gitea alone can't back it — you'd need a DCR-capable IdP (Authentik/Keycloak) or a DCR proxy in front of Gitea. See [doc/clients/claude-web.md](clients/claude-web.md).
 
 ## Environment variables
 

docker-compose.yml

@@ -46,8 +46,8 @@ services:
     cap_drop:
       - ALL
     user: "1000:1000"
-    networks:
-      - proxy
+    # networks:
+    #   - proxy
     healthcheck:
       test:
         [
@@ -63,8 +63,8 @@ services:
     # No proxy labels: Pangolin discovers this service on the shared `proxy`
     # network and forwards to :8080 — configure the route in Pangolin, not here.
 
-networks:
-  # Shared reverse-proxy network (Pangolin). Create once with:
-  #   docker network create proxy
-  proxy:
-    external: true
+# networks:
+#   # Shared reverse-proxy network (Pangolin). Create once with:
+#   #   docker network create proxy
+#   proxy:
+#     external: true