lib.authos-spec
Contract-first AuthOS specifications for identity, authentication, federation, and security-gated account surfaces.
@lssm-tech/lib.authos-specbun add @lssm-tech/lib.authos-specManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
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
attributionTokenonauth.signUpv1.2.0. - provider-neutral login-method descriptors for email/password, email OTP, email magic link, and all sixteen declared social providers, including maturity and account-resolution policy. Declarations and credential readiness are not production callback evidence.
- explicit
auth.invitation.adminList,auth.invitation.send,auth.invitation.resend, andauth.invitation.revokeoperations 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, andauth.mfa.disableoperations 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
sessionAuthorityOriginfor 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, Tendframe, or LSSM changes the disclosure and return context, never the issuer or canonical account. - ecosystem origin routes (
AUTH_OS_ECOSYSTEM_ORIGIN_ROUTES, D-127c): canonical marketing/app origins, 308 alias hosts, and per-routeappPathPrefixes.listAuthOsEcosystemAppPathRuleskeys every marketing-role host (canonicalwww, apex, alternate apex/www) to its app origin; app and legacy hosts are never keys.matchesAuthOsEcosystemAppPathis the donor segment-boundary match and never matches/api. Career brands carryAUTH_OS_ECOSYSTEM_APP_PATH_PREFIXES; Fairelio carries none.authOsEcosystemSingleOriginRoutebuilds the single-origin form (one exacthttps://<hostname>marketing and app origin, noappPathPrefixes, checked byassertAuthOsEcosystemSingleOriginRoute); a canonical host is never a redirect source.app_taketideuses it forhttps://taketide.app(D-164a). Pure data and helpers only: hosts perform the redirect. - governed exchange bindings (
AUTH_OS_GOVERNED_EXCHANGE_BINDINGS, D-027, D-122):{ entry, role, applicationId }producer/consumer rows over thedata-ownership.v1projections, plus the pureresolveAuthOsGovernedExchangeBinding(admits onlyactiveapplications; refusesunknown-entry,unknown-application,unbound,application-not-active). The Tellshift, Patio, GTM Learning Loop, Taketide and Sarla application rows aredraft. Only Taketide, whose single host origin is decided, has a relying party (rp_taketide_web, clienttaketide-web, invite-only, production-disabled, scopehttps://lssm.co/scopes/app_taketide) and an origin route; the other four have no relying party, scope, callback or origin route. A row is not a grant or consent.
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.
Central identity operations
The existing root and operations entrypoints export the additive central operation groups and their strict Zod IO schemas; no new package subpath is required.
auth.registration.*declares public availability and browser-bound pending OAuth registration. The existingauth.signUpoperation owns email/password signup. Pending proof remains HTTP-only, expires, and is single-use; an existing email needs the authenticated owner and explicit fresh-session link confirmation.auth.centralAdmin.*owns global identity operations under an explicit central operator resolver. Global reporting roles and organization administrator roles grant no product or operator authority.auth.centralOrganization.*owns organization and team lifecycle independently of CompanyOS context or product entitlement, retaining canonical role and last-owner rules.auth.centralApiKey.*declares scoped user/organization keys separately from existing CompanyOSauth.apiKey.*andcos_pk_credentials. Secrets appear once on creation/rotation and are forbidden in evidence. Verification reads authentication headers, never a public key body.auth.agent.*declares official-protocol agent enrollment, capability approval, grants, revocation and execution. Both modes require scoped current authority and Connect; legacyAgentAuthOsCommandremains a separate read/draft governance model.auth.multiSession.*selects accounts already authenticated in the browser. Projected IDs are not bearer credentials; switching rechecks MFA and product authority.auth.application.*supports operator-approved confidential web clients, version-bound review and rotation, exact HTTPS redirects, pairwise subjects, and independent public/entitlement admission policies. Anonymous dynamic registration remains disabled.auth.connection.*owns explicit API consent, connection lifecycle and registered read execution separately from social identity login. Provider credentials stay behind server-only vault references.
All new operations are experimental contract declarations. Their existence does not claim a production-wired plugin, approved provider application, or completed live canary. Hosts supply runtime maturity and source/deployment-bound qualification evidence.
Tendframe domain compatibility
The existing app_pactena application is presented as Tendframe, with https://app.tendframe.me as its canonical app and https://api.tendframe.me as its session authority. Its stable application ID, pactena-web client ID, pairwise subject configuration, exact product scope and production admission gate are unchanged. The catalog retains the legacy callback and adds the exact new Tendframe callback and post-logout URL. Reconcile the deployed identity client before switching product origins; a source registration is not evidence of successful production authentication.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
3 declarations
@lssm-tech/lib.contracts-spec-coreworkspace:^
Read the package manual ↗@lssm-tech/lib.schemaworkspace:^
Read the package manual ↗zodcatalog:
Declared capabilities
Contract-first AuthOS specifications for identity, authentication, federation, and security-gated account surfaces.
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolintbun lint:fixlint:fixnode ../../../../scripts/biome.cjs check --write .lint:checknode ../../../../scripts/biome.cjs check .testbun testprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit