@lssm/lib.authos-spec

Contract-first AuthOS specifications for identity, authentication, account federation, and security-gated account surfaces.

AuthOS V0 deliberately covers a broad identity/auth surface while staying provider-neutral. Runtime execution is delegated to integrations such as Better Auth; this package defines the contracts, fixtures, maturity tags, and semantic validation that other packages must preserve.

Scope

• identities, accounts, profiles, sessions, credentials, devices, and factors;
• organization, team, admin, invitation, and membership references;
• OAuth/OIDC, SSO/SAML, SCIM, email/phone verification, OTP, magic-link, passkey, one-tap, and MFA descriptors;
• Connect with LSSM account-link federation and LSSM-as-IdP descriptors;
• auth events, audit evidence, maturity tags, semantic validation, and agent domain-command authority contracts.
• provider-neutral acquisition handoff through the optional opaque attributionToken on auth.signUp v1.2.0.
• provider-neutral login-method descriptors for email/password, email OTP, email magic link, Google, Microsoft, LinkedIn, TikTok, Facebook, and GitHub, including maturity and account-resolution policy.
• explicit auth.invitation.adminList, auth.invitation.send, auth.invitation.resend, and auth.invitation.revoke operations for tenant-scoped organization administration; resend rotates the acceptance token and all token material remains server-only.
• explicit auth.mfa.enroll, auth.mfa.confirm, auth.mfa.verify, and auth.mfa.disable operations for the complete TOTP and recovery lifecycle. Identity and challenge authority remain server-derived. The shared executor redacts declared transient fields before telemetry; host persistence and evidence adapters must enforce the contract's explicit forbidden-sink obligations.
• ecosystem application and OIDC relying-party registrations, pairwise subject links, coarse product entitlements, product invitation scope, and redacted provisioning receipts. These contracts never contain client secrets, acceptance tokens, or product-local roles.
• provider-client reconciliation requests and receipts carry only an application identifier plus redacted configuration evidence. Client secrets remain host-owned and are forbidden in both input and output contracts.
• pairwise product-membership provisioning handoffs. The central authority sends the RP-specific subject, email, access tier, and idempotent provisioning ID; canonical identity IDs and local membership identifiers never cross that boundary.
• a product-owned sessionAuthorityOrigin for every application. Identity may be shared, but the product creates a host-scoped session and keeps local membership and role authority.
• product-branded connect labels over one declared identityAuthorityOrigin. “Continue with hCircle,” CompanyOS, Pactena, or LSSM changes the disclosure and return context, never the issuer or canonical account.

Referral and affiliate handoff

AuthOS only carries acquisition context through identity creation. It never decodes, logs, or chooses a referral or affiliate winner. A host captures the signed token from a link or cookie, passes it to auth.signUp, and hands it to GrowthOS after the identity is created. GrowthOS remains authoritative for attribution, rewards, reversals, ledger balances, and payouts.

Non-goals

• No bespoke auth engine.
• No Better Auth dependency or provider SDK imports.
• No production LSSM-as-IdP enablement without security-review evidence.
• No credential-secret persistence in fixtures, errors, or events. Security-ceremony operations may carry explicitly declared transient inputs or one-time outputs only when shared telemetry redaction is active and host persistence/evidence adapters enforce the declared forbidden-sink policy.
• No assumption that one AuthOS entitlement replaces product-local membership, role, or permission authority.

Domain-command authority

Agent-facing AuthOS commands are contracts only: they classify read, draft, approval-required, and reserved-human actions without executing identity, session, credential, organization, or IdP mutations. High-impact commands such as session start, factor verification, LSSM account linking, credential rotation, SSO configuration, organization role changes, and LSSM-as-IdP enablement require explicit approval evidence before any host-owned integration may execute them.

Public entrypoints

• @lssm/lib.authos-spec
• @lssm/lib.authos-spec/types
• @lssm/lib.authos-spec/fixtures
• @lssm/lib.authos-spec/validation