Skip to main content
The accounts provider contract: user accounts, login flows, sessions.

AccountsAdminServices

tai42_contract.accounts.provider.AccountsAdminServices
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
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

apply_role

tai42_contract.accounts.provider.AccountsAdminServices.apply_role
Copy the named role template into the principal’s enforced policy. Guarded: raises LastAdminError (nothing written) when the principal is the last enabled admin and role is not an allow-all role. Raises KeyError on an unknown role. Parameters

remove_policy

tai42_contract.accounts.provider.AccountsAdminServices.remove_policy
Delete the principal’s enforced policy and row (and revoke keys it owned). Guarded: raises LastAdminError (nothing written) when the principal is the last enabled admin. Raises KeyError when the principal or its policy is absent. Parameters

set_user_disabled

tai42_contract.accounts.provider.AccountsAdminServices.set_user_disabled
Set/clear the disabled marker on the principal. Guarded for disabled=True: raises LastAdminError (nothing written) when the principal is the last enabled admin. Raises KeyError when no principal exists. Parameters

principal_roles

tai42_contract.accounts.provider.AccountsAdminServices.principal_roles
The role each principal holds. The reserved admin role name when its own policy is admin-shaped, else its role pointer, else None (a policy not written from a role template). A user id with no principal is absent from the mapping. Parameters

AccountsProvider

tai42_contract.accounts.provider.AccountsProvider
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
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).

display_name

tai42_contract.accounts.provider.AccountsProvider.display_name
The human-readable name of this provider. Shown wherever the platform must tell this provider’s accounts and actions apart from another provider’s (the Members page labels each page-level action with it). One non-empty line; static, config-derived metadata, cheap and side-effect free (sync by contract, like login_methods). A provider fronting several external identity providers names the one its actions act through.

list_members

tai42_contract.accounts.provider.AccountsProvider.list_members
List the people this provider owns and the invitations it holds. Called by the application’s Members aggregator, which concatenates one MemberListing per registered accounts provider into a single deployment-wide view. Each person is a MemberEntry and each outstanding invitation an InviteEntry; how a provider partitions its accounts between the two lists is its own concern. Reads the provider’s own store, so this is I/O (async). Backend errors raise (the aggregate fails loudly rather than dropping a provider’s accounts silently).

member_actions

tai42_contract.accounts.provider.AccountsProvider.member_actions
Declare this provider’s member-admin actions. Static, config-derived metadata, side-effect free (sync by contract, like login_methods). Each MemberAction names the action’s own id, its label (by template id), where it renders, whether it is destructive, and its input/result models. WHICH of these apply to a given row is a separate, state-dependent decision reported per row by list_members (see actions). A provider with no actions returns [].

invoke_member_action

tai42_contract.accounts.provider.AccountsProvider.invoke_member_action
Perform the action named by this provider’s own action_id. target is the provider’s stable id of the member/invite row the action acts on (None for a page-scoped action). payload is the already-validated instance of the action’s declared input_model. Returns an instance of the action’s declared result_model, which the platform carries opaquely (it reads no field of it). A correctable failure is raised as a member-action error from tai42_contract.accounts.errors — MemberActionError for a rejected input, MemberActionNotFoundError for an unknown target, MemberActionConflictError for a state conflict, MemberActionBadRequestError for a malformed request — so the invoke operation maps it to the matching status without the provider importing the application package. Parameters

revoke_session

tai42_contract.accounts.provider.AccountsProvider.revoke_session
Revoke the session behind token if it is this provider’s. Returns a SessionRevocation when a session was found and revoked (its end_session_url names where the browser goes next, or None); None 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 answer None for foreign tokens instead of raising. Backend errors still raise (fail closed). Parameters

AccountsProviderSettings

tai42_contract.accounts.provider.AccountsProviderSettings
Settings shape handed to an accounts-provider factory. admin is typed loosely (Any) because the contract cannot name the application’s AccountsAdminServices implementation class; it carries that implementation. A provider reads its OWN backing-store handles and key namespaces from its own settings, never off this object, so the contract names no store-specific field here. Attributes

LoginAttachingProvider

tai42_contract.accounts.provider.LoginAttachingProvider
An accounts provider that holds an interactive credential it can set for a principal. A provider mixes this in when it owns an interactive credential it can attach to a principal (a password, or a one-time invite link). The setup door and the login-methods door isinstance-check for it: a provider whose login lives at an external issuer does not implement it, and the caller reports the login as not attached. The credential’s own disabled state lives with the provider, so the principals door also routes a DISABLE of a principal it claims (has_login) to the provider’s member actions, never the principals door.

Members

attach_login

tai42_contract.accounts.provider.LoginAttachingProvider.attach_login
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

LoginOwningProvider

tai42_contract.accounts.provider.LoginOwningProvider
An accounts provider that keeps a login record for principals. A provider mixes this in when it keeps its own record of a principal’s login — a record that must never outlive the principal. The principals door asks every registered owning provider has_login before it DELETES a principal: a principal some provider claims is removed through that provider’s member actions, which remove the principal and the record together, never through the principals door.

Members

has_login

tai42_contract.accounts.provider.LoginOwningProvider.has_login
Whether this provider keeps a login record for the principal user_id. The principals door reads this before a delete: a True means the provider’s member actions remove the principal; a False means the provider keeps nothing for it (a service principal, a principal provisioned by hand, the keys-only owner), and the principals door removes it directly. A backend error raises (fail closed), never a silent False. Parameters Data models for the accounts plugin kind. An accounts provider declares HOW a human can sign in as data; the Studio login shell renders that data. Exactly two login-method shapes exist: a credentials form posted to a provider route, and a button linking to a provider redirect flow. The provider supplies every piece of content (titles, labels, icons, paths); the renderer supplies only the two shapes. The same module carries the credential shapes a provider attaches to a principal and the membership shapes it lists — the people it owns and the invitations it holds — so a generic Members view can render every provider’s accounts without hard-coding any of them; the only provider name it shows is the one each provider declares for itself.

ButtonMethod

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

FormField

tai42_contract.accounts.models.FormField
One input of a form-shaped login method. Attributes

FormMethod

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

InviteCredential

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

InviteEntry

tai42_contract.accounts.models.InviteEntry
One outstanding invitation an accounts provider holds. id is the provider’s stable handle for the invited person — the id its own actions act on. email is the invited address; role names the platform role the person will hold (only the name — the role’s definition is read from the role listing; None — the policy is not written from a role template). created_at and expires_at are timezone-aware (UTC). actions are the provider’s OWN member-action ids applicable to this row. An invitation holds no principal yet, so it carries no principal_ids. Attributes

InviteRow

tai42_contract.accounts.models.InviteRow
An invite row in the aggregated directory the Members door returns. Display fields plus the opaque routing tokens. An invitation holds no principal, so it carries no principal state, and role is provider-sourced; None — the policy is not written from a role template. provider_name is the display name the owning provider declares (never the platform’s registry name) — the caller shows it on the row so rows of different providers read apart. Attributes

InvokeMemberActionRequest

tai42_contract.accounts.models.InvokeMemberActionRequest
The invoke-door envelope: which action, which row, and the per-action input. action_key is the opaque catalog key; target_handle is the row handle an action acts on (None for a page-scoped action); input is an open mapping the operation hands to the declared input_model for ordinary validation, so the platform’s static envelope never needs to know the per-action fields. Unknown top-level keys are ignored (pydantic’s default extra behaviour). Attributes

InvokeMemberActionResult

tai42_contract.accounts.models.InvokeMemberActionResult
The invoke-door result: the provider’s result-model dump, carried opaquely. result is the model_dump(mode="json") of the action’s declared result_model instance; the platform reads no field of it. Attributes

LoginAttachment

tai42_contract.accounts.models.LoginAttachment
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

LoginCredential

tai42_contract.accounts.models.LoginCredential
The closed union of login credentials a provider can attach to a principal.

LoginCredentialKind

tai42_contract.accounts.models.LoginCredentialKind
The kind tags of LoginCredential, one per credential variant.

LoginMethod

tai42_contract.accounts.models.LoginMethod
The closed union of renderable login-method shapes.

MemberAction

tai42_contract.accounts.models.MemberAction
One member-admin action an accounts provider declares. An IN-PROCESS declaration returned by member_actions. The platform serializes a wire MemberActionDescriptor from it and validates an invoke’s input by calling input_model.model_validate(input) (plain pydantic). input_model and result_model are OPAQUE to the platform: it reads no field of either, it only renders their JSON schema and runs the ordinary model validation and dump. id is the provider’s OWN action id — the platform maps it to an opaque wire key and never parses or branches on it. label is a TemplatedText reference (a stored template id or inline content), so the wording is localizable through the platform’s existing resource manager and never held as a literal here. Not serialized to the wire (it carries class references), so arbitrary_types_allowed is safe. Attributes

MemberActionCatalog

tai42_contract.accounts.models.MemberActionCatalog
Every declared member action across the registered accounts providers. Attributes

MemberActionDescriptor

tai42_contract.accounts.models.MemberActionDescriptor
One declared member action, serialized for the catalog wire. key is the opaque catalog key the platform mints for (provider, action) — a caller joins and echoes it, never parses it. label is the resolved wording (the declaration’s TemplatedText rendered at the door). provider_name is the display name the owning provider declares (never the platform’s registry name) — the caller shows it next to the label so actions of different providers read apart. input_schema and result_schema are the declared models’ model_json_schema() — a caller renders a form and a read-only result view from them generically, with no provider field name known to the platform. Attributes

MemberActionScope

tai42_contract.accounts.models.MemberActionScope
Where a declared member action renders: a page-level button, a member-row menu item, or an invite-row menu item. A provider classifies each of its own actions into one of these three places; the platform never reads the provider’s meaning behind it.

MemberDirectory

tai42_contract.accounts.models.MemberDirectory
The aggregated, platform-joined membership the Members door returns. The wire shape of the deployment-wide Members view: every provider’s people and invitations as MemberRow / InviteRow, each carrying opaque routing tokens and (for a member) the platform-joined principal state. The provider’s raw action ids and principal ids never reach this wire. Attributes

MemberEntry

tai42_contract.accounts.models.MemberEntry
One person an accounts provider owns: an account the operator manages. id is the provider’s stable handle for the person — the id its own actions act on. email is the sign-in identity the provider holds for them. created_at is timezone-aware (UTC). principal_ids are the platform principal id(s) this person holds (at least one — a person with none is an invitation, not a member); the Members operation joins them against the platform’s own records to resolve each principal’s access-control disabled state and the role it holds. Neither is a provider fact, so neither rides here. actions are the provider’s OWN member-action ids applicable to this row. Attributes

MemberListing

tai42_contract.accounts.models.MemberListing
An accounts provider’s membership: the people it owns and the invitations it holds. Returned by list_members. The application’s Members aggregation concatenates one of these per registered accounts provider into a single deployment-wide view, so a provider’s people and outstanding invitations appear without the platform naming the provider. Attributes

MemberPrincipalState

tai42_contract.accounts.models.MemberPrincipalState
One platform principal a member holds, with its access-control state joined in. user_id is the platform principal id; disabled is taken from that principal’s own record (the store the principals listing reads) and role is the role it holds, joined from its own policy record — both never from a provider. role is None when the principal’s policy was not written from a role template. Attributes

MemberRow

tai42_contract.accounts.models.MemberRow
A member row in the aggregated directory the Members door returns. Display fields plus the platform-joined principal state and opaque routing tokens. handle routes an invoke back to the producing provider and pins this row; action_keys are the opaque catalog keys of the actions applicable to it — a caller joins and echoes both, never parses them. principals carries each principal’s joined state; disabled is derived True only when EVERY principal is disabled, so a person with any enabled principal still reads active while the per-principal truth stays visible. role is derived too: the one name every principal holds, None when there is no single name — every principal’s policy was set directly, or the principals hold different roles; principals[].role carries each principal’s own. provider_name is the display name the owning provider declares (never the platform’s registry name) — the caller shows it on the row so rows of different providers read apart. Attributes

PasswordCredential

tai42_contract.accounts.models.PasswordCredential
A login credential that sets the principal’s password now. Attributes