@lssm-tech/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.
Périmètre
- 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-tech/lib.authos-spec@lssm-tech/lib.authos-spec/types@lssm-tech/lib.authos-spec/fixtures@lssm-tech/lib.authos-spec/validation@lssm-tech/lib.authos-spec/operations/api-keys@lssm-tech/lib.authos-spec/operations/security@lssm-tech/lib.authos-spec/operations/roles@lssm-tech/lib.authos-spec/operations/sso
Personal API keys
operations/api-keys owns auth.apiKey.list, auth.apiKey.options, auth.apiKey.create, and auth.apiKey.revoke, the auth.apiKey.created / auth.apiKey.revoked events, and the policy hosts must enforce (AuthApiKeyPolicyDocBlock): cos_pk_ secrets stored only as SHA-256 hashes and returned once, 90-day default and 365-day maximum expiry, 60 requests per minute per key, at most 10 active keys per person, one organization (optionally one workspace) per key, and the read-only scope catalog AUTH_API_KEY_SCOPES (companyos.workspace.read, companyos.evidence.read, opa.daily.read). Each scope lists the exact GET routes it grants and the organization-grant permission it needs; hosts derive their route allowlist from that list and re-check the owner's grant on every request. Use-time failures are API_KEY_INVALID, API_KEY_SCOPE_DENIED, API_KEY_GRANT_REVOKED, and API_KEY_RATE_LIMITED.
Account security
operations/security owns auth.trustedDevice.{list,revoke}, auth.connectLssm.{status,initiate,unlink}, auth.provider.readiness, auth.phone.{status,sendCode,verify,enableMfa,remove}, auth.mfa.sendSms, and the recent-authentication policy (AUTH_RECENT_AUTHENTICATION_SECONDS, AUTH_RECENT_AUTHENTICATION_ERRORS, isRecentAuthentication, AuthRecentAuthenticationDocBlock). Hosts gating any sensitive action (API keys, LSSM unlink, SSO identity providers, SSO settings, SCIM token issue/rotate) apply the same 10-minute window or current-password rule and declare REAUTHENTICATION_REQUIRED / RECENT_SIGN_IN_REQUIRED. AUTH_PHONE_E164_PATTERN validates phone numbers; phone numbers are verification and second-factor data only, never a sign-in identifier.
Enterprise SSO and SCIM
operations/sso owns auth.sso.* (overview, discovery, settings, connections, domains) and auth.scim.* (tokens, group mappings, SCIM 2.0 users/groups), their events and named errors, and pure rules: domain normalization and verification records, the sign-in decision with owner break-glass (evaluateSsoSignIn), SCIM group precedence (resolveScimMemberRole) and identity-provider MFA evidence (ssoClaimsAssertMfa). AuthSsoPolicyDocBlock states the posture. MFA after SSO: by default (requireIdpMfa: false) the identity provider is trusted for MFA and hosts never prompt for their own second factor; with requireIdpMfa: true an SSO sign-in without MFA evidence (amr/acr claims or an authentication-methods SAML attribute) is refused with SSO_MFA_REQUIRED. Identity provider create/update/delete, auth.sso.settings.update and SCIM token issue/rotate require recent authentication (transient password). auth.role.delete 1.1.0 adds ROLE_IN_USE_BY_SSO for roles that are the SSO default or a SCIM group's role.
Proposed reviewed development resource authority
PROPOSED_NOT_ADMITTED private development resource authority: optional canonical AuthOS resource JWT/workload profiles; exact <=300-second TTL and registered resource/claim validation; durable scoped OSINT receipts preserve SAME active decisionRef and terminal expiry/revocation. Existing defaults and production RP catalog remain unchanged. Real adoption, security review, TLS/registration, canonical lifecycle/obligation/evidence adapters, migration admission and runtime qualification are required before enablement. Product entitlement is not an OSINT effect grant. No issuer, key, token, grant or database has been created or verified by this source preparation.
Proposed development security review records bind the actual database, profile content, security evidence, asymmetric algorithm, native token type, allowed signing key IDs and native resource policy versions. AuthOsDevProfileReviewV1Schema is an additive root export. Records are installed only by the independently admitted security owner; runtime cannot approve itself. Native user access-JWT sub remains the canonical user ID. OSINT's specialized principal verifier maps that verified identity through the actual registered RP pairwise link. This preparation is PROPOSED_NOT_ADMITTED; generic provider behavior and production RP catalog stay unchanged.
Proposed local disposable custody
Local disposable custody successor: an additive V2 whole-review arm admits only the genuine Windows DPAPI CurrentUser provider, exact owner SID/owner-only ACL, local namespace/root and immutable pairwise/issuer ciphertext digests. V1 review syntax and generic SecretProvider interface remain unchanged. Only explicit local-disposable host composition admits the factory-branded provider; native signing, reserved claims, canonical SQL locks/policies and revocation remain. This source proposal is unapproved and unqualified. Source/runtime/security admission, actual DB/TLS/native key installation and mandatory real issuance, revocation/custody/cleanup acceptance remain required. No cloud backend is impersonated, production admission introduced, keys generated or review installed.
