tai42-accounts-postgres

The Postgres-backed accounts provider for the TAI ecosystem — an installable plugin that owns human user accounts, password login, sessions, and invites, and ships a Studio users-admin UI. It registers itself as the "accounts-postgres" provider and mints/validates its own tai-sess-… session tokens.

Importing the package registers the provider in tai42-contract's module-level accounts registry (register_accounts_provider("accounts-postgres", ...)), which ALSO lands the factory in the identity registry under the same name — an accounts provider is the token answerer for its own sessions, so one registration keeps sessions both mintable and validatable. No tai42_app handle is involved, so it registers in any process that imports it. A deployment selects it by including accounts-postgres in the access-control auth_providers list.

Its only tai-* dependencies are tai42-contract (the accounts ABC, the injected admin-services and settings Protocols, the login-method metadata models, and the registry it registers through) and tai42-kit (the Postgres and Redis clients and the session/invite hash). It never imports the skeleton — the plugin is contract-facing, and the import is banned by ruff.

The TAI ecosystem

TAI is an open-source runtime for MCP tools, agents, and workflows. An accounts provider owns human sign-in: it authenticates a person, mints the session token their browser carries, and answers that token back as an identity on every later call. This package is one such provider (Postgres-backed accounts with password login, sessions, and invites); any package can back the same contract, so this repo is this provider's own full doc home, and the documentation site covers the platform-level story:

• Accounts concept: https://tai42.ai/concepts/accounts
• Build an accounts provider (author guide): https://tai42.ai/guides/authors/accounts-provider
• Ecosystem catalog: https://tai42.ai/reference/catalog

What it stores

Three plugin-owned tables in the platform database, created by the plugin's own migration chain:

• accounts_users — one row per human user: the opaque, stable user_id (usr-…), the normalized email, the argon2id password hash (NULL until an invite is accepted), the role-template name, and the disabled flag.
• accounts_sessions — one row per live login: the SHA-256 hash of the tai-sess-… token (the raw token is never stored), with sliding-idle (last_seen_at) and absolute (absolute_expires_at) expiry.
• accounts_invites — one pending invite per user: the SHA-256 hash of the tai-inv-… token, its TTL, and its single-use consumption marker.

Rate-limit counters and the shared bootstrap token live in Redis (reached through the injected settings.redis), namespaced per deployment.

The plugin NEVER touches the skeleton's access_control_policies / access_control_routes tables or any ac:* Redis key directly — all policy and role writes go through the injected AccountsAdminServices (apply_role / remove_policy / set_user_disabled).

HTTP surface

Public (/api/login/*, always-public prefix):

Authed (/api/auth/users*, reserved prefix, admin-fenced by the seeded role conditions — except PUT /users/me/password, self-service):

Logout is NOT here — the skeleton owns the single POST /api/auth/logout dispatcher; this plugin contributes revoke_session.

Configuration

Behavior config is the plugin's own TAI_ACCOUNTS_* namespace; the Postgres connection resolves through the central database registry on the component's binding (the plugin never reads skeleton config):

First-owner bootstrap gate (secure by default). With neither TAI_ACCOUNTS_BOOTSTRAP_TOKEN nor TAI_ACCOUNTS_BOOTSTRAP_OPEN set, the gate is ON and the effective token is auto-generated ONCE at startup and printed to the server log. It is shared across all processes through Redis (SET NX): the first worker or replica to start wins the write and logs it; every other process reads the same value — so the default gate is deterministic under BOTH multiple uvicorn workers AND multiple replicas, with no explicit token. An explicit TAI_ACCOUNTS_BOOTSTRAP_TOKEN still overrides it. TAI_ACCOUNTS_BOOTSTRAP_OPEN=true is the only ungated configuration and logs a loud open-window warning every boot while no owner exists.

Shared Redis / shared pg_db: two deployments that share one Redis AND one pg_db must set distinct TAI_ACCOUNTS_REDIS_KEY_PREFIX values, or they will cross-read each other's rate-limit counters and bootstrap token.

Proxies: the per-IP throttle reads the direct peer — there is no X-Forwarded-For parsing. A deployment behind a shared proxy must throttle at its ingress, or all callers collapse to one throttled IP.

Schema migrations + startup guard

The plugin ships an ordered SQL migration chain under migrations/ and declares it in tai-plugin.yml (migrations: migrations). The shared migration runner applies it — run by the operator with tai db migrate, or automatically by the marketplace install/upgrade flow once the package lands. Applied migrations are recorded in the per-database tai_schema_history table under the component tai42-accounts-postgres, on the DDL-privileged migrator identity.

tai db migrate     # apply every pending migration across all discovered components
tai db status      # per-component applied / pending / checksum verdicts

The provider's boot healthcheck asserts the chain is fully applied — a pending migration or a checksum mismatch fails startup loudly naming tai db migrate — and fires only when the accounts store is configured (the database bound by TAI_DB_BINDING_TAI42_ACCOUNTS_POSTGRES resolves a non-empty password). It NEVER auto-applies.

The accounts kind requires access control ENABLED. If the routes are mounted while ACCESS_CONTROL_ENABLE=false (so the provider is never instantiated and the admin services are never injected), boot fails loudly rather than serving a broken door.

Deployment wiring

In the deployment manifest:

lifecycle_modules: ["tai42_accounts_postgres"]                 # provider registration
routers_modules: ["tai42_accounts_postgres.routes_login",
                  "tai42_accounts_postgres.routes_users"]       # the HTTP surface
studio_plugins: ["tai42_accounts_postgres"]                    # the users-admin UI

and in access control (example alongside the api-key provider):

ACCESS_CONTROL_ENABLE=true
ACCESS_CONTROL_AUTH_PROVIDERS=["accounts-postgres","redis"]

Security model

• argon2id password hashing (RFC 9106 library defaults).
• Hashed at rest: session and invite tokens are stored only as their SHA-256 hash; the raw token appears exactly once, in the response that mints it.
• Uniform login failure: unknown email and wrong password return a byte-identical generic 401, and BOTH run a real argon2 verify (a dummy-hash verify on unknown email) so timing does not enumerate users.
• Failures-only rate limiting: a correct password is never blocked — only a failed attempt records against the per-account and per-IP counters (the per-IP dimension reads the direct peer; proxied deployments throttle at ingress). The argon2 verify is additionally bounded by a concurrency semaphore that sheds with a 503 under a hash flood. Redis being down fails the throttle CLOSED.
• No-email invites: the plugin returns an origin-relative login_path for the admin to hand over; it never sends email and never fabricates an absolute URL.
• Secure-by-default bootstrap: the first-owner gate is ON by default via an auto-generated one-time token (shared across processes through Redis), compared constant-time; the only open configuration is explicit and logs a loud warning.

Invite and session tokens are shown once — the create/regenerate response is the only place the raw invite link or session token appears.

Requirements

Requires Python 3.13+, a Postgres reachable through the database bound by TAI_DB_BINDING_TAI42_ACCOUNTS_POSTGRES (default TAI_DATABASE_DEFAULT_PG_*), and a Redis reachable through the injected access-control Redis. Apply the schema with tai db migrate before first serve; an out-of-date schema is caught loudly at boot.

The current release line tracks the 10.x contract (tai42-contract>=10.0,<11).

Install

Requires Python 3.13+. Install from PyPI into the environment that runs the server:

uv add tai42-accounts-postgres

Or from source — clone this repo and add it as an editable dependency; the tai42-* dependencies resolve in-tree from the workspace.

git clone https://github.com/tai42ai/tai42   # next to your app checkout
cd /path/to/your/app
uv add --editable ../tai42/plugins/accounts-postgres

Development

Two toolchains, one repo — CI gates both.

Python (from the repo root):

uv venv --python 3.13
uv pip install --no-sources --editable ".[dev]"
uv run --no-sync ruff check .
uv run --no-sync ruff format --check .
uv run --no-sync pyright
uv run --no-sync pytest --cov --cov-report=term-missing

Coverage is gated at 95% (fail_under in pyproject.toml). CI installs with uv sync --locked --python 3.13 --extra dev, so a stale uv.lock fails there.

Studio bundle:

pnpm install --frozen-lockfile
pnpm typecheck
pnpm run format:check
pnpm test
pnpm run build
git diff --exit-code src/tai42_accounts_postgres/studio/

The last line is the freshness gate. After any change under studio-src/ (or the JS toolchain), run pnpm run build and commit the regenerated src/tai42_accounts_postgres/studio/ alongside the source — a stale committed bundle fails CI.

License

Apache-2.0. See LICENSE and NOTICE.