# Feature Specification: m2-gpt identity for M2 Market Web

**Feature Branch**: `003-gpt-identity` · **Created**: 2026-07-02 · **Status**: Draft
**Input**: Operator: "we need a central credential system and ledger" — m2-gpt becomes the
credential authority; market-web stops using the shared fleet passcode.

## Stories
1. (P1) An operator logs into market.machinemachine.ai with their m2-gpt admin
   credentials (email+password). The session is BOUND to their identity (email, role,
   tenant_id) — wallet defaults to their operator identity; no picker for non-admins.
2. (P1) fleet_admin sessions keep the operator picker (fleet oversight).
3. (P2) Transition: FLEET_PASSCODE login stays available behind AUTH_MODE=passcode|gpt|both
   (default both) until the operator retires it.

## Requirements
- FR-201: /api/login accepts {email,password} → backend forwards to m2-gpt
  POST /admin/v1/auth/login (M2GPT_URL env) over TLS; on 200 binds the session cookie to
  {email, role, tenant_id, fleet_admin} from the token response. Credentials are never
  stored; the m2-gpt JWT is kept server-side in the session only if needed for refresh.
- FR-202: operator_id mapping: tenant_id when set, else email local-part; fleet_admin may
  view any wallet (picker), others only their own (403 otherwise).
- FR-203: when M2GPT_INTROSPECTION_KEY env is set, the backend revalidates sessions via
  POST /admin/v1/auth/introspect (the m2-gpt PR in flight) at most once per 10 min.
- FR-204: passcode mode unchanged when enabled; UI shows both forms per AUTH_MODE.
- FR-205: secrets discipline unchanged (SC-103 scan must stay green; no credential or JWT
  in client code/storage beyond the opaque session cookie).

## Success criteria
- SC-201: login with real m2-gpt operator credentials → wallet shows THEIR operator_id
  without a picker; wrong password → 401.
- SC-202: non-admin requesting another wallet → 403.
- SC-203: secrets scan green; AUTH_MODE=passcode still works.

## Assumptions (flagged)
- Ledger wallets keyed by tenant_id going forward; existing ad-hoc wallet ids (m2bd,
  sdjs-operator, chris-operator) remain and are reachable by fleet_admin — a formal
  identity migration is deferred to the ledger-federation proposal (m2-gpt PR step 2/3).
- m2-gpt admin login is reachable from the web container (same coolify network / public).