Skip to content
ContractSpec
Start here

Package manual · domains

·Identity, access and subject context

lib.authos-spec

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

domainslibraryv2.0.4experimentalservernode
@lssm-tech/lib.authos-spec
bun add @lssm-tech/lib.authos-spec
Package source ↗Manifest ↗

Manifest 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 attributionToken on auth.signUp v1.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, 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, 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-route appPathPrefixes. listAuthOsEcosystemAppPathRules keys every marketing-role host (canonical www, apex, alternate apex/www) to its app origin; app and legacy hosts are never keys. matchesAuthOsEcosystemAppPath is the donor segment-boundary match and never matches /api. Career brands carry AUTH_OS_ECOSYSTEM_APP_PATH_PREFIXES; Fairelio carries none. authOsEcosystemSingleOriginRoute builds the single-origin form (one exact https://<hostname> marketing and app origin, no appPathPrefixes, checked by assertAuthOsEcosystemSingleOriginRoute); a canonical host is never a redirect source. app_taketide uses it for https://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 the data-ownership.v1 projections, plus the pure resolveAuthOsGovernedExchangeBinding (admits only active applications; refuses unknown-entry, unknown-application, unbound, application-not-active). The Tellshift, Patio, GTM Learning Loop, Taketide and Sarla application rows are draft. Only Taketide, whose single host origin is decided, has a relying party (rp_taketide_web, client taketide-web, invite-only, production-disabled, scope https://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 existing auth.signUp operation 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 CompanyOS auth.apiKey.* and cos_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; legacy AgentAuthOsCommand remains 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

THIS PACKAGElib.authos-spec63 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

3 declarations

Declared capabilities

Lib Authos Spec

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

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun lint:fix
  • lint:fixnode ../../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../../scripts/biome.cjs check .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit