module.auth-os

@lssm-tech/module.auth-os

Reusable AuthOS UI module: a complete atomic-design component library for authentication and identity flows, composable into any host app or bundle. The module ships atoms → molecules → organisms → templates → screens in a single package, backed by the AuthOS contract surface (@lssm-tech/lib.authos-spec) and the AuthObservability port. Production auth execution stays host-owned; the module provides only the UI and composition layer.

The reusable sign-in surface supports email/password, email OTP, email magic link, and config-driven Google, Microsoft, LinkedIn, TikTok, Facebook, and GitHub buttons. Provider discovery and execution remain host-owned. Web and native hosts can also compose the linked-account panels with their adapter's list/link/unlink operations for providers that require an explicit first link.

Atomic Taxonomy (after Waves 1–4)

All public exports flow through src/ui/index.ts.

Adapter Contract Surface (AuthOsAdapter)

Defined in src/ui/hooks/types.ts — landing with Wave 5.

The AuthOsAdapter interface is the boundary between UI hooks and host-supplied auth backends. Hooks accept an adapter instance and delegate all side-effectful auth operations to it. This keeps the module free of any bespoke auth engine.

MFA hosts implement a password-gated lifecycle: enrolMfa returns the authenticator setup URI and one-time recovery codes, confirmMfa verifies the first TOTP, verifyMfaRecovery consumes a recovery code during sign-in, and disableMfa re-authenticates before removal. Recovery values remain hook state; they must never enter logs, observability properties, URLs, or persisted UI preferences.

Waitlist port (WaitlistAdapter)

The waitlist is a separate, independently adoptable port (src/ui/hooks/waitlist-types.ts). ./ui/hooks/http-waitlist-adapter ships createHttpWaitlistAdapter, the public join/status half over the identity host's /api/waitlist and /api/waitlist/status endpoints. The host binds the origin, applicationId, consentTextVersion, source, locale and failure copy; caller input never overrides the product scope, a join without explicit consent or with a blank email is refused before any request, and an unknown status response fails closed. Pair it with useWaitlistJoin + WaitlistJoinForm and useWaitlistStatus + WaitlistStatus. WaitlistJoinForm takes host copy through labels; any label left out, and the hidden honeypot's accessible name, resolve from the authOs.organisms.waitlistJoinForm.* catalog keys for the active locale, also when the mounted LocaleProvider does not carry the auth-os catalog.

Linked accounts port (LinkedAccountsAdapter)

./ui/hooks/useLinkedAccounts ships useLinkedAccounts, its separate LinkedAccountsAdapter port (offered social methods, linked identities, link, unlink) and socialLoginMethods, the projection of an identity host /login-methods body to its social methods. The hook merges methods with linked identities, refreshes after unlink and reports failures as a boolean (provider messages are never surfaced). Web and native hosts bind the port and render AccountLinkedPanel / ProviderIconButton.

Passkey management port (PasskeyManagementAdapter)

./ui/hooks/usePasskeyManagement (usePasskeyManagement + the list/delete PasskeyManagementAdapter port) and ./ui/organisms/PasskeyManagementList (the registered-passkeys section on the authOs.organisms.passkeyManagement.* copy) replace host code that called the Better Auth passkey endpoints directly. Pair them with usePasskeyEnrol + PasskeySetupForm; hosts bind the port.

Invitation acceptance port (InvitationAcceptanceAdapter)

./ui/hooks/useAcceptInvitation (useAcceptInvitation, AcceptInvitationInput, the InvitationAcceptanceAdapter port) and ./ui/organisms/AcceptInvitationForm cover invite-bound account creation: the link must carry an invitation id, code and tenant; the invitee sets a password and optional name (the email stays server-derived); onAccepted runs on success and route error codes are shown. The fields render inside a native form, so Enter in either field submits.

Passport privacy port and copy

./ui/hooks/usePassportPrivacy drives governed privacy shares over the PassportPrivacyAdapter port (generic over the host's share/offer projections): load for the signed-in session, revoke/export/erasure and idempotent grant issuance one at a time, a step_up notice when the host demands a fresh strong authentication, reload after success. ./i18n/passport holds the LSSM Passport identity-screen copy rendered through EcosystemPassportTemplate (phases, account actions, OIDC scope labels, privacy center) in en/fr/es, with {product} interpolation and English fallback.

Personal API key port (ApiKeyAdapter)

./ui/hooks/api-key-types defines ApiKeyAdapter for the auth.apiKey.* contracts (list, options, create, revoke); failures throw ApiKeyAdapterError with a contract code. ./ui/hooks/useApiKeys loads keys and binding options, keeps the one-time secret in memory only until dismissReveal, and refreshes after revocation. ./ui/organisms/api-keys exports ApiKeysPanel (usage against the active-key limit, list with prefix…last4, status, binding, scopes and dates), ApiKeyCreateDialog / ApiKeyCreateForm, ApiKeyRevealDialog / ApiKeyRevealContent (closes only on the explicit acknowledgement), and ApiKeyRevokeDialog. Copy lives in the api-keys i18n area (authOs.apiKeys.*, en/fr/es).

Account security ports (./ui/hooks/security-types)

TrustedDeviceAdapter, LssmLinkAdapter, ProviderReadinessAdapter and PhoneAdapter Back useTrustedDevices, useLssmLink, useProviderReadiness and usePhoneNumber; failures throw SecurityAdapterError with a contract code. ./ui/organisms/security exports TrustedDevicesPanel, ConnectLssmPanel (honest unavailable reasons, confirmed link, step-up disconnect), ProviderReadinessPanel, PhoneNumberSection (renders nothing while SMS is unavailable), StepUpField, and SecurityConfirmDialog. MfaPage accepts trustDevice (remember this device) and sms (with useMfaSms); AuthOsAdapter.verifyMfa takes an optional trustDevice, and sendMfaSms / verifyMfaSms are optional adapter methods. Copy lives in the security i18n area (authOs.security.*, en/fr/es).

Organization SSO port (OrganizationSsoAdapter)

./ui/hooks/sso-types defines OrganizationSsoAdapter for the auth.sso.* / auth.scim.* contracts; failures throw SsoAdapterError with a contract code. Identity provider create/update/delete, updateSettings and SCIM token issue/rotate take an optional step-up password. ./ui/hooks/useOrganizationSso runs one mutation at a time; when the host answers REAUTHENTICATION_REQUIRED / RECENT_SIGN_IN_REQUIRED the mutation waits on state.stepUp until confirmStepUp(password) retries it or cancelStepUp() drops it (the password is never stored). ./ui/organisms/organization-sso exports OrganizationSsoPanel (identity providers, verified domains, sign-in policy including "Require multi-factor authentication from the identity provider" — off means the identity provider is trusted for MFA — SCIM tokens, group roles, provisioning log), SsoStepUpDialog and SsoSignInForm (refusal copy, including SSO_MFA_REQUIRED). Copy lives in the sso i18n area.

Account self-service port (AuthAccountAdapter)

./ui/hooks/account-types defines AuthAccountAdapter, a separate port backing the auth.account.* and auth.emailAddress.* contracts from @lssm-tech/lib.authos-spec (profile read/update, password change, account closure, and the verified email lifecycle). Failures throw AccountAdapterError with a contract error code; the hooks expose codes and the organisms map them to authOs.account.* copy (en/fr/es).

• Hooks: useAccountProfile, useChangePassword (optional sign-out of other sessions), useEmailAddresses (list/add/verify/make primary/remove, plus verifyAndMakePrimary for changing the sign-in email), and useDeleteAccount (exposes the organizations that block a sole owner). useAccountMutation is the shared submit state.
• Organisms (./ui/organisms/account): AccountProfileForm (initials avatar; no media upload), ChangePasswordForm, EmailAddressManager, and DeleteAccountPanel (typed email confirmation plus password, or a fresh session for passwordless identities).
• createAccountFakeAdapter() supports previews and tests.
• SecuritySettings renders Change / Manage / Update only for callbacks the host passes (onChangePassword, onManageEmail, onManageMfa, onUpdatePhone); the phone row appears only when a phone exists or onUpdatePhone is wired. SecurityPage accepts a title rendered as the page h1.

i18n Surface

Target locale set: en / fr / es

The readiness target for auth-os is en/fr/es (Option A, decided 2026-06-09). SUPPORTED_LOCALES = ['en', 'fr', 'es'] in @lssm-tech/lib.contracts-spec/translations.

Atomic catalog structure

Catalogs are split by UI area so parallel workers can fill their own file without conflicts. All area catalogs share the auth-os.messages spec key.

Merged catalogs (enMessages / frMessages / esMessages) collapse all areas into one spec per locale for the runtime registry. The parity gate (__tests__/catalog-parity.test.ts) enforces identical key sets and placeholder signatures across en/fr/es for every area — 15 tests, zero failures.

Factory (canonical)

import { createAuthOsI18n } from '@lssm-tech/module.auth-os/i18n';

const i18n = createAuthOsI18n('fr');
i18n.t('authOs.atoms.authCodeInput.defaultLabel'); // → 'Code d\'authentification'

Legacy resolver (deprecated back-compat shim)

resolveAuthMessage('auth.<surface>.<key>', params?) — falls back to the key verbatim when missing; fires AUTH_I18N_MISSING_KEY via the observability port. New code should use createAuthOsI18n.

German (de) — preserved ungated superset

src/i18n/de.ts is a 297-line legacy monolith retained from before the atomic area structure. It is:

• NOT gated by catalog-parity.test.ts (which only gates en/fr/es).
• NOT using defineTranslation or the atomic area shape.
• Retained because de.test.ts gives regression coverage and the translation investment is preserved.
• Not to be migrated into atoms.de / molecules.de etc. unless German becomes a deliberate market commitment.

Usage (legacy resolver only):

import { de } from '@lssm-tech/module.auth-os/i18n';
import { resolveAuthMessage } from '@lssm-tech/module.auth-os/i18n';
const label = resolveAuthMessage('auth.signIn.submit', {}, { catalog: de });
// → 'Anmelden'

Subpaths

./i18n · ./i18n/en · ./i18n/resolveAuthMessage

Observability

Port interface and event taxonomy live in src/observability/.

Key events (partial list):

AUTH_SIGN_IN_VIEWED / SUBMITTED / SUCCEEDED / FAILED
AUTH_SIGN_UP_VIEWED / SUBMITTED / SUCCEEDED / FAILED
AUTH_MFA_PROMPTED / FACTOR_SELECTED / VERIFIED / FAILED
AUTH_PASSKEY_REGISTERED / FAILED
AUTH_SESSION_LISTED / REVOKED
AUTH_INVITATION_VIEWED / ACCEPTED / DECLINED
AUTH_AUDIT_VIEWED
AUTH_CONSENT_GRANTED / REVOKED

Props schema (AuthEventProps): enum + numeric + hashed-id only — no PII, no raw tokens, no i18n strings. The module never imports a concrete analytics SDK (AC-19).

.web / .native Discipline

Platform variants are colocated with their shared base:

atoms/AuthCodeInput/
├── AuthCodeInput.tsx          # shared base
├── AuthCodeInput.web.tsx      # browser-specific
└── index.ts

• .web.tsx — browser / Next.js surfaces.
• .native.tsx — React Native / Expo surfaces.
• The alias helpers (withPresentationTurbopackAliases / withPresentationMetroAliases) in @lssm-tech/lib.presentation-runtime-core route platform variants at build time.

Bundle Integration

AuthLandingTemplate, PasskeysTemplate, and AccountLockedTemplate from @lssm-tech/bundle.managed-companyos/ui/templates are locked by the adapter-contract test at packages/bundles/managed-companyos/src/__tests__/auth-template-adapter-contract.test.tsx (owned by the composing bundle; this module does not depend on the bundle) via satisfies ComponentProps<typeof T>.

These three templates will be consolidated into the module's own template layer in a follow-up wave; the contract test ensures prop-signature drift is caught at compile time until then.

Status

Automated accessibility qualification

The reusable identity lifecycle now has one automated sweep across all 18 screens: sign-in/up/out, email and magic-link verification, MFA and recovery, passkeys, sessions, security, organization, invitations, and audit. The sweep rejects critical or serious Axe findings, invalid React HTML nesting, and loss of navigation or main landmarks under reduced motion. It is local automated evidence only; manual screen-reader, zoom, contrast, managed-provider, real-device, recovery-drill, and production-canary qualification remain open.

Feature Hub profiles

./hub exposes separate auth-user and auth-admin profiles. The user profile mounts at /auth with self authority; the admin profile mounts at /admin/auth with organization authority. Both share the provider-neutral auth.identity and auth.session ports, while only admin requires auth.authority. Operation refs are selected from AuthOsOperationRegistry. Admin effects additionally re-resolve explicit organization authority and a fresh session for the current tenant/workspace at execution time. A route's admin metadata, installation success, or a general user session never grants administrative execution authority by itself. User routes cover identity, verification, MFA, passkeys, sessions, recovery, security, and profile. Admin routes separately cover organizations, members, invitations, roles, sessions, domains, SSO, SCIM, federation, security, and audit.

MFA enrollment contract

AuthOsAdapter.enrolMfa requires { factorKind, password } so credential accounts re-prove the current password before TOTP setup material is issued. The result may include an otpauth URI and one-time recovery codes. Consumers must keep the password, setup URI, and recovery codes in ceremony-local memory, exclude them from URLs, storage, logs, and telemetry, and call confirmMfa before presenting MFA as active. Account settings must project the provider's server-owned enabled state rather than infer it from a completed client step.

Referral and affiliate acquisition

The sign-up view model, hook, form value, and AuthOsAdapter.signUp accept an optional opaque attributionToken. Hosts may obtain it from GrowthOS URL or cookie acquisition helpers and bind it into the sign-up screen. AuthOS never renders the token and excludes it from observability properties.

The deterministic preview adapter consumes the provider bridge's pure bridge-plan entry point. Preview rendering must not import server authentication initialization or database adapters into React Native bundles. Real authentication remains in the injected client adapter.

Published browser conditions select the emitted browser artifacts alongside existing Node/Bun/type targets. Export keys and source behavior are preserved; this packaging metadata does not activate providers or grant execution authority.