TAI42 — the OS for AI tools

The accounts provider contract: user accounts, login flows, sessions.

AccountsAdminServices

tai42_contract.accounts.provider.AccountsAdminServices

class AccountsAdminServices(Protocol)

Application-side policy services an accounts provider may invoke. Implemented by the application and INJECTED via AccountsProviderSettings.admin — accounts plugins never import the application package, so this Protocol is the only way plugin code can create a principal, apply a role template, remove a principal’s policy, or flip the disabled marker. Every method mutates application-owned principal and policy state; the plugin never touches that state directly.

Members

create_principal

tai42_contract.accounts.provider.AccountsAdminServices.create_principal

async create_principal(
    self,
    user_id: str,
    *,
    kind: Literal['human', 'service'],
    display_name: str,
    created_by: str | None,
    role: str,
) -> None

Create the principal row and apply its role. A human principal authenticates through an accounts provider; a service principal holds keys only. created_by is the principal id that created this one, or None for the setup door. Raises loudly if the principal already exists or the role is unknown. Parameters

Parameter	Type	Default	Description
`user_id`	`str`	—	—
`kind`	`Literal['human', 'service']`	—	—
`display_name`	`str`	—	—
`created_by`	`str \| None`	—	—
`role`	`str`	—	—

apply_role

tai42_contract.accounts.provider.AccountsAdminServices.apply_role

async apply_role(self, user_id: str, role: str) -> None

Copy the named role template into the principal’s enforced policy. Parameters

Parameter	Type	Default	Description
`user_id`	`str`	—	—
`role`	`str`	—	—

remove_policy

tai42_contract.accounts.provider.AccountsAdminServices.remove_policy

async remove_policy(self, user_id: str) -> None

Delete the principal’s enforced policy and row (and revoke keys it owned). Parameters

Parameter	Type	Default	Description
`user_id`	`str`	—	—

set_user_disabled

tai42_contract.accounts.provider.AccountsAdminServices.set_user_disabled

async set_user_disabled(self, user_id: str, disabled: bool) -> None

Set/clear the disabled marker on the principal. Parameters

Parameter	Type	Default	Description
`user_id`	`str`	—	—
`disabled`	`bool`	—	—

AccountsProvider

tai42_contract.accounts.provider.AccountsProvider

class AccountsProvider(IdentityProvider)

A user-accounts provider: login methods plus session-token validation. An accounts provider owns human accounts and the login flows that mint session tokens for them. It IS an identity provider: the session tokens it mints are validated through the inherited validate_token — the same seam every credential passes through — so installing an accounts provider never adds a second enforcement pathway. Session tokens are opaque strings minted and stored by the provider (recommended prefix tai-sess- to distinguish them from sk- API keys at a glance); the contract never parses token contents. Storage, hashing, and lifetime are provider-owned. Login/lifecycle HTTP routes (submit endpoints, redirect flows) are shipped by the provider plugin as ordinary router modules; the contract carries only the metadata that lets a generic login screen render them.

Members

login_methods

tai42_contract.accounts.provider.AccountsProvider.login_methods

login_methods(self) -> list[LoginMethod]

Declare the login methods this provider offers. Called by the application’s public login-methods aggregator. Must be cheap and side-effect free: this is static, config-derived metadata, not I/O (sync by contract, like readiness_targets).

revoke_session

tai42_contract.accounts.provider.AccountsProvider.revoke_session

async revoke_session(self, token: str) -> bool

Revoke the session behind token if it is this provider’s. Returns True when a session was found and revoked; False when the token is not this provider’s (wrong prefix, unknown). The application’s single logout route dispatches across ALL registered accounts providers, so implementations must answer False for foreign tokens instead of raising. Backend errors still raise (fail closed). Parameters

Parameter	Type	Default	Description
`token`	`str`	—	—

AccountsProviderSettings

tai42_contract.accounts.provider.AccountsProviderSettings

class AccountsProviderSettings(Protocol)

Settings shape handed to an accounts-provider factory. redis and admin are typed loosely for the same reason IdentityProviderSettings.redis is Any: the contract cannot name application or kit types. admin carries the application’s AccountsAdminServices implementation. Attributes

Attribute	Type
`redis`	`Any`
`admin`	`Any`

LoginAttachingProvider

tai42_contract.accounts.provider.LoginAttachingProvider

class LoginAttachingProvider(AccountsProvider)

An accounts provider that can attach an interactive login to an existing principal. A provider mixes this in when it owns an interactive credential it can set for a principal (a password, or a one-time invite link). The setup door and the invite flow isinstance-check for it: a provider whose login lives at an external issuer (OIDC) does not implement it, and the caller reports the login as not attached. Ownership of a principal’s disable/delete follows the login: the principals door asks every registered attaching provider has_login, and a principal some provider claims is managed through that provider’s users door (which cleans its login row and runs its own guard), never the principals door.

Members

has_login

tai42_contract.accounts.provider.LoginAttachingProvider.has_login

async has_login(self, user_id: str) -> bool

Whether this provider holds a login for the principal user_id. The principals door reads this to decide who owns a principal’s disable/delete: a True means the provider holds the credential, so the principal is managed through that provider’s users door; a False means it does not (a service principal, an OIDC-provisioned human whose login lives at the issuer, the keys-only owner), and the principals door manages it directly. A backend error raises (fail closed), never a silent False. Parameters

Parameter	Type	Default	Description
`user_id`	`str`	—	—

attach_login

tai42_contract.accounts.provider.LoginAttachingProvider.attach_login

async attach_login(self, user_id: str, *, credential: LoginCredential) -> LoginAttachment

Attach credential to the existing principal user_id. A PasswordCredential sets the password now; an InviteCredential mints a one-time link returned on the LoginAttachment. A correctable-input failure (a too-short password) raises LoginAttachError; a login already existing for the principal or a taken email raises LoginConflictError. The state is unchanged on either, so the caller surfaces the failure and stays retriable. Parameters

Parameter	Type	Default	Description
`user_id`	`str`	—	—
`credential`	`LoginCredential`	—	—

ButtonMethod

tai42_contract.accounts.models.ButtonMethod

class ButtonMethod(BaseModel)

A redirect button: the renderer draws a button that navigates to href (e.g. an OIDC authorize route). Attributes

Attribute	Type
`model_config`	—
`shape`	`Literal['button']`
`id`	`str`
`label`	`str`
`icon`	`str \| None`
`href`	`str`

FormField

tai42_contract.accounts.models.FormField

class FormField(BaseModel)

One input of a form-shaped login method. Attributes

Attribute	Type
`model_config`	—
`name`	`str`
`label`	`str`
`secret`	`bool`
`autocomplete`	`str \| None`

FormMethod

tai42_contract.accounts.models.FormMethod

class FormMethod(BaseModel)

A credentials form: the renderer draws the fields and POSTs them as JSON to submit_path. Attributes

Attribute	Type
`model_config`	—
`shape`	`Literal['form']`
`id`	`str`
`title`	`str`
`purpose`	`Literal['login', 'invite']`
`fields`	`list[FormField]`
`submit_path`	`str`

InviteCredential

tai42_contract.accounts.models.InviteCredential

class InviteCredential(BaseModel)

A login credential that mints a one-time invite link instead of setting a password now. Attributes

Attribute	Type
`model_config`	—
`kind`	`Literal['invite']`
`email`	`str`

LoginAttachment

tai42_contract.accounts.models.LoginAttachment

class LoginAttachment(BaseModel)

The outcome of attaching a login to a principal. attached is whether an interactive login was attached. invite_token and login_path are set only for an invite credential — the one-time link the operator follows to set the password later. Attributes

Attribute	Type
`model_config`	—
`attached`	`bool`
`invite_token`	`str \| None`
`login_path`	`str \| None`

LoginCredential

tai42_contract.accounts.models.LoginCredential

LoginCredential = Annotated[PasswordCredential | InviteCredential, Field(discriminator='kind')]

The closed union of login credentials a provider can attach to a principal.

LoginMethod

tai42_contract.accounts.models.LoginMethod

LoginMethod = Annotated[FormMethod | ButtonMethod, Field(discriminator='shape')]

The closed union of renderable login-method shapes.

PasswordCredential

tai42_contract.accounts.models.PasswordCredential

class PasswordCredential(BaseModel)

A login credential that sets the principal’s password now. Attributes

Attribute	Type
`model_config`	—
`kind`	`Literal['password']`
`email`	`str`
`password`	`str`

abort_staging

tai42_contract.accounts.registry.abort_staging

abort_staging() -> None

Drop the staged generation on a failed build.

begin_staging

tai42_contract.accounts.registry.begin_staging

begin_staging() -> None

Open a fresh staged generation the epoch build registers into.

commit_staging

tai42_contract.accounts.registry.commit_staging

commit_staging() -> None

Promote the staged generation to committed in one reference assignment.

get_accounts_provider_factory

tai42_contract.accounts.registry.get_accounts_provider_factory

get_accounts_provider_factory(name: str) -> Callable[..., AccountsProvider]

Return the factory registered under name in the COMMITTED generation. Unknown names raise KeyError. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—

iter_accounts_provider_factories

tai42_contract.accounts.registry.iter_accounts_provider_factories

iter_accounts_provider_factories() -> list[tuple[str, Callable[..., AccountsProvider]]]

Name-sorted snapshot of the COMMITTED factories. Returns a new list: callers may iterate freely without touching registry state. Sorted for deterministic aggregator output.

iter_accounts_provider_factories_staged

tai42_contract.accounts.registry.iter_accounts_provider_factories_staged

iter_accounts_provider_factories_staged() -> list[tuple[str, Callable[..., AccountsProvider]]]

Name-sorted snapshot of the STAGED generation if a build is staging, else the committed one. The build’s own accessor (the configured-providers boot check, kind status).

register_accounts_provider

tai42_contract.accounts.registry.register_accounts_provider

register_accounts_provider(name: str, factory: Callable[..., AccountsProvider]) -> None

Register a named accounts-provider factory in BOTH registries. Registers factory here and — because an accounts provider is the identity answerer for its own session tokens — into the identity registry under the same name. Both registries stage together, so a staged accounts registration lands beside its staged identity twin. RELOAD-SAFE: re-registering the SAME factory (by same_factory) under a name it already holds is a quiet no-op in BOTH registries, so the hot-reload primitive re-executing this plugin’s module body does not raise. A DIFFERENT factory under an already-registered name still raises loudly, in either registry. The accounts no-op returns before touching the identity registry, and the identity registry is only written when this name is new here, so the two registries never drift. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—
`factory`	`Callable[..., AccountsProvider]`	—	—

reset_registry

tai42_contract.accounts.registry.reset_registry

reset_registry() -> None

Clear the write-target accounts registrations — staged generation while staging, else committed. The write target is the STAGED generation while a build is staging (never the committed one), else the committed map (boot, test isolation). Clears only this registry: the identity registry has its own lifecycle.

HTTP API

CLI

Settings

Capability map

Conversation bridge

Python SDK

Studio SDK

Accounts (tai42_contract.accounts)

AccountsAdminServices

Members

create_principal

apply_role

remove_policy

set_user_disabled

AccountsProvider

Members

login_methods

revoke_session

AccountsProviderSettings

LoginAttachingProvider

Members

has_login

attach_login

ButtonMethod

FormField

FormMethod

InviteCredential

LoginAttachment

LoginCredential

LoginMethod

PasswordCredential

abort_staging

begin_staging

commit_staging

get_accounts_provider_factory

iter_accounts_provider_factories

iter_accounts_provider_factories_staged

register_accounts_provider

reset_registry

​AccountsAdminServices

​Members

​create_principal

​apply_role

​remove_policy

​set_user_disabled

​AccountsProvider

​Members

​login_methods

​revoke_session

​AccountsProviderSettings

​LoginAttachingProvider

​Members

​has_login

​attach_login

​ButtonMethod

​FormField

​FormMethod

​InviteCredential

​LoginAttachment

​LoginCredential

​LoginMethod

​PasswordCredential

​abort_staging

​begin_staging

​commit_staging

​get_accounts_provider_factory

​iter_accounts_provider_factories

​iter_accounts_provider_factories_staged

​register_accounts_provider

​reset_registry

AccountsAdminServices

Members

create_principal

apply_role

remove_policy

set_user_disabled

AccountsProvider

Members

login_methods

revoke_session

AccountsProviderSettings

LoginAttachingProvider

Members

has_login

attach_login

ButtonMethod

FormField

FormMethod

InviteCredential

LoginAttachment

LoginCredential

LoginMethod

PasswordCredential

abort_staging

begin_staging

commit_staging

get_accounts_provider_factory

iter_accounts_provider_factories

iter_accounts_provider_factories_staged

register_accounts_provider

reset_registry