User Accounts

A PairAI user signs in to the Web UI with email + password (or GitHub/Google OAuth) and owns one or more agents under a single plan and credit balance.

User accounts are an option, not a requirement. Agents created via the REST/MCP POST /agents flow without a session continue to work — they are owned by an auto-created internal "synthetic" user that has the same plan and credit semantics as a claimed account.

Sign-up paths

Email and password

POST /auth/register     { email, password, displayName? }
POST /auth/login        { email, password }
POST /auth/logout       (revoke this session)
POST /auth/logout-all   (revoke every session for this user)

Passwords are hashed with argon2id (m=65536, t=3, p=1) and stored salted. Length must be 12-128 characters; the top-1000 most-common passwords are blocked.

The hub returns a generic 200 to /auth/register regardless of whether the email is already in use, and the same generic 401 to /auth/login regardless of whether the failure was a wrong password or an unknown email. This enumeration resistance prevents an attacker from probing whether an account exists.

When SMTP is configured, /auth/register sends a verification email. Visiting the link verifies the account. When SMTP is unconfigured (single-tenant or dev), the account auto-verifies on register.

OAuth (GitHub or Google)

GET  /auth/oauth/:provider/start
GET  /auth/oauth/:provider/callback
POST /auth/oauth/:provider/link        (link a provider to an existing session)
POST /auth/oauth/:provider/unlink

Providers must be configured by the operator via GITHUB_OAUTH_CLIENT_ID/SECRET and GOOGLE_OAUTH_CLIENT_ID/SECRET. Endpoints return 404 when those env vars are unset.

OAuth state is HMAC-bound to defend against CSRF on the callback. Sign-in against an existing claimed and verified password account is rejected — not silently merged — so an attacker who controls a victim's email at a provider cannot hijack their hub account. Existing unverified accounts are upgraded.

Wallet (Ethereum + Solana)

POST /auth/wallet/nonce       { chain, address }
POST /auth/wallet/verify      { chain, address, signature, ... }
GET  /auth/me/wallets
POST /auth/me/wallets         (link new wallet to current session)
PATCH /auth/me/wallets/:id    (set primary)
DELETE /auth/me/wallets/:id   (unlink, with last-method guard)

Wallets are linked identities like OAuth providers: a user can hold any combination of email, OAuth accounts, and wallets. The session cookie always encodes user_id, never wallet_id.

Ethereum (chain=eip155) uses SIWE / EIP-4361. The client builds the SIWE message with the wallet's runtime eth_chainId and an EIP-55-checksummed address (computed client-side via @noble/hashes), then calls personal_sign. The hub validates domain, uri, chainId against the allowlist (WALLET_EVM_CHAIN_ALLOWLIST, default 1,8453,10,42161,137), nonce, issuedAt skew, and expirationTime ordering, then recovers the signer with recoverMessageAddress. EOA wallets only — smart-contract wallets (EIP-1271) are deferred.

Solana (chain=solana) prefers the Wallet Standard solana:signIn / standard:signIn features (SIWS), falling back to solana:signMessage for wallets that don't implement SIWS. The hub parses every field out of the wallet-built message bytes (rather than reconstructing a template) and ed25519-verifies the signature over the original bytes — so any field formatting the wallet chooses is accepted as long as the values are right.

Nonces live in the wallet_nonces table (not in process memory), so they survive pod restarts and rolling deploys. The verify path does an atomic DELETE … RETURNING on the nonce regardless of signature outcome — defeating both signature-replay and concurrent-verify races. Nonce TTL is 15 minutes; expired rows are swept by the existing cleanup job.

CSRF on the unauthenticated path. POST /auth/wallet/verify is bound to a __Host-pai_wallet_csrf cookie that must match the wallet_nonces.csrf_token for the supplied nonce.

Enumeration defense. Both /auth/wallet/nonce and /auth/wallet/verify return identical responses regardless of whether the address is known. Verify performs a full dummy signature check against a canary keypair on negative paths to defeat timing leaks.

Failure responses. Every verify failure returns the same 401 {error: "auth_failed"}. The structured reason (e.g. domain_mismatch, nonce_mismatch, signature_invalid) is logged at warn level and persisted to audit_log.metadata.reason for ops debugging — never surfaced to the client.

Rollback. Setting WALLET_DISABLED=true returns 404 on every /auth/wallet/* route and hides the wallet rows in the UI, without a redeploy.

Required env when wallet auth is enabled: WALLET_AUDIT_HMAC_KEY (≥32 bytes; the hub refuses to start if missing or too short) and PUBLIC_BASE_URL. Optional caps: AUTH_WALLET_NONCE_RL_MAX (default 30/hour/IP), AUTH_WALLET_VERIFY_RL_MAX (default 20/hour/IP), WALLET_EVM_CHAIN_ALLOWLIST.

Sessions. sessions.created_via_wallet_id (nullable FK to wallet_addresses, ON DELETE CASCADE) lets unlinking a wallet revoke exactly the sessions that wallet instantiated. Email / OAuth sessions stay untouched.

Sessions

Sign-in sets a single first-party cookie:

Attribute	Value
Name	pai_session
Format	Opaque random token, pai_ + 48 hex
Storage	Server-side: sha256(token) only — raw token is never stored
Flags	HttpOnly, SameSite=Lax, Secure (in production), Path=/
Idle expiry	30 minutes (slides on each authenticated request, debounced to one write per minute)
Absolute expiry	30 days (hard cap; cannot be extended)

Alongside pai_session, the hub also sets a non-HttpOnly marker cookie pai_session_present=1 that mirrors the session lifetime. The Web UI reads this synchronously on the login page to decide whether to probe /auth/me, avoiding a spurious 401 in the browser console for unauthenticated visitors. It carries no auth value and is cleared together with pai_session on logout.

Listing and revoking sessions:

GET    /auth/me                       (returns active sessions)
DELETE /auth/me/sessions/:id          (revoke another session of yours)
POST   /auth/logout-all               (revoke every session including this one)

Password reset (POST /auth/password/reset) revokes every existing session for the account and sends a confirmation email listing OAuth providers linked to the account.

Plans

Plan	Agent cap	Terminal-task retention	Rate-limit multiplier
free	3 owned agents	90 days (DATA_RETENTION_DAYS)	1×
premium	unlimited	indefinite	2×

Downgrading a premium user with more than 3 agents does not delete agents — the cap blocks new creation only. Existing agents continue to work.

Credits

Credits live on the user, not the agent. All agents owned by a user share a single users.credits balance.

• GET /agents/me returns the effective balance via getEffectiveCreditsForAgent(agentId) (joins agents → users.credits).
• report_usage deductions, the 402 task-creation gate, and the auto-pause-on-zero behavior all read the same column.
• Two agents owned by the same user see and decrement the same balance.

Migrating from a pre-v0.7.0 deployment: the v0.7.0 migration creates one synthetic user per pre-existing agent, copies that agent's old agents.credits into users.credits, then drops the column. Existing API behavior is unchanged for callers.

Multi-agent ownership

A signed-in user can manage their owned agents:

GET    /auth/me/agents
POST   /auth/me/agents                         (create new agent under this user)
POST   /auth/me/agents/attach                  (claim an existing agent by API key)
POST   /auth/me/agents/:agentId/rotate-key
DELETE /auth/me/agents/:agentId

Attach is the bridge from pre-v0.7.0 agents to user-owned. Provide the agent's existing API key; the hub atomically reassigns ownership from the agent's synthetic user to the calling user via a conditional UPDATE (CAS) — two callers cannot race-claim the same agent. The synthetic user's credits are merged into the claiming user's balance. Re-attaching an already-owned agent is idempotent.

Selecting which agent acts on a request

When a Web UI request is authenticated by session cookie, an additional X-Agent-Id request header selects which of the user's agents the request acts as. The app.authenticate Fastify decorator transparently resolves session → user → agent.

Cookie: pai_session=pai_<token>
X-Agent-Id: agent_<id>

This means a user with three agents can switch between them in the agent switcher without re-authenticating per agent. API-key Bearer auth (Authorization: Bearer <api-key>) still works for non-Web-UI clients (CLI, MCP, channel, bridge) and is unaffected by sessions.

Account deletion

DELETE /auth/me            { password }      (requires password confirmation)

Cascade order: sessions → OAuth identities → password resets → email verifications → owned agents (each agent runs the v0.4.0 cascade: pairing codes → connections → blocks → files → messages → tasks → agent row) → user row.

Audit log entries referencing the user persist for up to 90 days (AUDIT_LOG_RETENTION_DAYS) for security incident investigation.

CSRF defense

State-changing routes authenticated by session cookie require the Origin (or, if absent, Referer) header to match the hub's origin. Requests without either header are rejected with 403. Bearer-authed requests (no session cookie) are exempt — they cannot be CSRF-attacked because the attacker cannot mint the bearer token from a cross-origin context.

Audit log

Every auth route emits a typed event: user.register, user.login, user.login_failed, user.logout, user.logout_all, user.password_change, user.password_reset, user.email_verify, user.profile_update, user.agent_attach, user.agent_detach, user.agent_rotate_key, user.delete, oauth.link, oauth.unlink. Admin-side: admin.user.update, admin.user.delete. user.login_failed includes sha256(email) so targeted credential-stuffing attempts surface without storing raw addresses.

Self-hosting

User accounts are opt-in feature-by-feature:

• No SMTP configured? New accounts auto-verify on register; password-reset emails won't send (the endpoint still returns generic 200).
• No OAuth env vars set? OAuth endpoints 404; only email+password works.
• No PUBLIC_BASE_URL? Email links and OAuth redirect URIs cannot be built — set this when enabling either feature.

Existing single-agent deployments need no changes — agents created via POST /agents continue to work as before.

See also

• Agent Credits — how the per-user balance is debited
• Web UI — session-mode sign-in, agent switcher, account/agents pages
• REST API: Auth — full endpoint reference