pico-server-auth

Embeddable auth server module for the pico-boot ecosystem.

Issues JWT tokens, handles wallet challenge-response login, and exposes JWKS — all compatible with pico-client-auth validation.

Two deployment modes

Embedded — add to any pico-boot app, auth runs in the same process. Auto-discovered — no need to list it in modules=[]:

container = init(modules=["myapp"], config=config)
# pico-server-auth endpoints are available automatically

Standalone — deploy as a separate auth service:

container = init(modules=[], config=config)
app = container.get(FastAPI)
# Other services point pico-client-auth to this service's /api/v1/auth/jwks

Scaffold a new project with pico-initializer — select pico-server-auth in the modules list.

Endpoints

GET  /api/v1/auth/jwks            JWKS public keys (pico-client-auth fetches this)
POST /api/v1/auth/challenge       Request nonce for wallet login
POST /api/v1/auth/sign-in         Verify wallet signature, issue JWT
POST /api/v1/auth/login           Password login (admin bootstrap)
POST /api/v1/auth/fleet/sessions  Mint a fleet session token (X-Fleet-Secret gated)   [v0.1.2]
POST /api/v1/auth/revoke          Revoke a token by jti (operator-gated)               [v0.1.2]
GET  /api/v1/auth/revoked-jtis    jti denylist (polled by pico-client-auth)            [v0.1.2]
GET  /api/v1/auth/mints           Currently-valid long-lived tokens (audit view)       [v0.1.2]

Wallet login flow

Client                    pico-server-auth
  │                            │
  │ POST /api/v1/auth/challenge       │
  │ { address: "0x..." }       │
  │───────────────────────────>│
  │ { challenge: "<nonce>" }   │
  │<───────────────────────────│
  │                            │
  │ sign(nonce) with wallet    │
  │                            │
  │ POST /api/v1/auth/sign-in          │
  │ { address, public_key,     │
  │   signature, challenge,    │
  │   algorithm: "ML-DSA-65" } │
  │───────────────────────────>│
  │ { access_token, address }  │
  │<───────────────────────────│

Supported wallet algorithms

Compatibility with pico-client-auth

Tokens issued by pico-server-auth are standard JWT (RS256). pico-client-auth validates them by fetching JWKS from the /api/v1/auth/jwks endpoint.

Same process: pico-client-auth discovers the JWKS endpoint automatically (same FastAPI app).

Separate processes: configure pico-client-auth to point to the server:

auth_client:
  issuer: "http://auth-server:8100"
  audience: "pico"
  # JWKS fetched from http://auth-server:8100/api/v1/auth/jwks

Challenge store

By default, challenges are stored in memory with TTL expiry. For multi-instance deployments, register a custom ChallengeStore component:

@component
class RedisChallengeStore:
    async def create(self, address: str) -> str: ...
    async def validate(self, address: str, nonce: str) -> bool: ...
    async def cleanup(self) -> int: ...

The in-memory default is replaced automatically via on_missing_selector.

Configuration

server_auth:
  issuer: "http://localhost:8100"
  audience: "pico"
  algorithm: "RS256"
  access_token_expire_minutes: 15
  challenge_ttl_seconds: 60
  supported_wallet_algorithms:
    - "ML-DSA-65"
    - "Ed25519"
    - "secp256k1"

  # ── v0.1.2: agent/fleet, revocation & mint audit ──
  admin_role: "operator"            # role stamped on password-login tokens
  fleet_mint_secret: ""             # set to enable POST /fleet/sessions (X-Fleet-Secret)
  fleet_session_ttl_seconds: 86400  # default fleet session lifetime (24h)
  revocation_store_path: ""         # JSONL path for the jti denylist (empty = in-memory)
  mint_audit_path: ""               # JSONL path for the mint audit log (empty = in-memory)
  mint_audit_min_ttl_seconds: 300   # don't audit mints shorter-lived than this

Stack

• pico-ioc — dependency injection
• pico-boot — auto-discovery
• pico-fastapi — controllers
• pico-client-auth — token validation

Built for AI-assisted development

pico-server-auth is part of an ecosystem designed for humans and coding agents building software together. Every package ships AGENTS.md working conventions, an llms.txt machine-readable docs index and documented behaviour pinned by regression tests; pico-testing gives agents a verification loop for their own changes, and releases are gated by the whole ecosystem booting together against real infrastructure. The full story: Built for AI-assisted development.

Install the agent skills for Claude Code or OpenAI Codex:

curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash

The pico-conventions skill teaches the assistant this module's API surface and invariants; /add-component and /add-tests scaffold components and tests that use it.

License

MIT