Skip to content
ContractSpec
Start here
AI index

Domain docs

AuthOS

Identity, roles, permissions, sessions, and tenant-safe access decisions, with one session authority and consistent multi-surface enforcement.

Source packages

Start with packages/domains/identity/module, then use the spec and runtime packages as compatibility boundaries.

  • packages/domains/identity/spec

  • packages/domains/identity/runtime

  • packages/domains/identity/identity-rbac

  • packages/integrations/authos-better-auth

Platform stance

Define the domain once. Render web and mobile with platform-native shells after contract, role, tenant, and policy resolution.

Canonical surfaces

  • Sign-in, sign-up, magic-link, email-OTP, OAuth/OIDC, and session contracts

  • Multi-factor authentication (TOTP) and recovery codes

  • Organization, team, and admin management

  • RoleMorph and identity-rbac role/permission gates

  • Tenant-aware authorization with fail-closed access decisions

  • Web (Next.js) and native mobile (Expo) auth surfaces from one AuthOsAdapter port

Implementation notes

  • better-auth is the credential/session identity provider via the authos-better-auth bridge; keep the provider adapter outside the domain contract.

  • identity-rbac is the live role/permission authority: project the session into a Subject through the authos-runtime SubjectProvider before generated UI or workflow surfaces render.

  • Route every credential and plugin sign-in path through a single session-authority hook so exactly one authoritative session is minted with an active organization (fail-closed on missing membership).

  • Enforce policy.auth consistently across REST, GraphQL, and MCP runtimes (401 unauthenticated, 403 unauthorized); treat a transiently unavailable RBAC store as a retryable 503, never a silent 401.

  • A capability is only marked runtime-backed when a real plugin/adapter implements it, enforced by a build-time spec-to-adapter parity check. Passkeys/WebAuthn, SSO/SAML, SCIM, and audit-log capabilities are explicitly deferred until their providers are wired.