integration.authos-better-auth

@lssm-tech/integration.authos-better-auth

Better Auth bridge for AuthOS Broad V0.

The web bridge preserves legacy signIn.oauth2({ providerId }) and oauth2.link({ providerId }) callers through Better Auth 1.7's supported signIn.social/linkSocial endpoints. It no longer imports the removed genericOAuthClient. Provider callback registration/schema migration remains a separate host rollout requirement.

This package turns AuthOS contracts into Better Auth configuration and maps Better Auth-like user/session/events back to AuthOS contracts. Canonical models stay in @lssm-tech/lib.authos-spec; pure projections and security gates stay in @lssm-tech/lib.authos-runtime.

advanced.cookiePrefix passes the host-selected namespace to Better Auth. Preview hosts can combine a distinct prefix with secure cookies and disabled cross-subdomain cookies. This separates cookie names and host scope; data/secret isolation must still be provisioned and verified independently.

Maturity

• Core email/password, magic link, email OTP, organization/team, admin, OAuth/OIDC client, MFA, and WebAuthn passkeys are runtime-backed through Better Auth (passkeys live-verified on Managed CompanyOS 2026-08-14).
• The bridge can also wire the phoneNumber and oneTap plugins, but no LSSM deployment enables them or has live-verified them: Managed CompanyOS does not list them in companyOsEnabledPlugins, and the generic authOsV0Fixture marks phone OTP/verification and one-tap fixture-backed. Phone OTP also needs a host sendPhoneOtp delivery callback.
• Connect with LSSM / LSSM-as-IdP (@better-auth/oauth-provider) stays contract-only for Managed CompanyOS until enableLssmIdp and a security review reference are configured.
• Built-in social login is typed for Google, Microsoft, LinkedIn, TikTok, Facebook, and GitHub. Hosts may retain genericOAuth for additional providers.
• Generic OIDC hosts can opt into profileNameFallback: "email" for legacy identities without a display name. The bridge reuses the provider email verbatim and never infers a human name.
• Invite-only hosts set disableSignUp; verified-email providers may resolve an existing verified identity, while TikTok and missing-email LinkedIn/Facebook identities require an explicit authenticated account link.
• Passkeys use the matching @better-auth/passkey server and browser plugins. Hosts must apply the provider's passkey table migration before enabling enrollment.
• SSO and SCIM remain declared external plugin capabilities until their production package wiring is separately reviewed.
• LSSM-as-IdP uses the supported @better-auth/oauth-provider OAuth 2.1/OIDC runtime, with dynamic registration disabled, PKCE/S256 provider defaults, pairwise subject derivation, asymmetric JWT/JWKS support, explicit login/consent routes, and resource audiences. It remains contract-only unless securityReviewRef and a server-only pairwise secret are present and production enablement is explicitly gated.
• IdP hosts may supply a product-access policy. Without one, post-login always redirects to the configured access boundary. Reviewed hosts can publish explicit product scopes, bind consent to an entitlement reference, and emit only coarse application/tier/entitlement claims after the host confirms active access.
• Product membership handoffs expose a bounded, bearer-authenticated internal handler. It accepts only an RP-specific pairwise subject and idempotent provisioning scope; canonical identity IDs, local role authority, and secret material are excluded from its contracts and replay evidence.
• ./relying-party-reconciliation prepares the exact catalog-owned Better Auth OAuth client record for an operator-controlled host reconciliation. It hashes the confidential client secret with the provider's SHA-256/base64url format, keeps dynamic registration disabled, and exposes only a secret-free configuration digest and evidence reference.

Referral and affiliate handoff

attribution configuration composes with an existing Better Auth databaseHooks.user.create.after hook. When a host resolves a valid signed acquisition token, the bridge calls onIdentityCreated after email/password or OAuth identity creation. The callback receives the opaque token and classified flow; the bridge does not persist, decode, or emit the token.

Native bearer sessions

./native-session-client exposes a storage-port-driven Better Auth client for Expo, Tauri, and other trusted native shells. Email/password and TOTP flows capture set-auth-token and the bounded set-mfa-authority projection, while the host-supplied vault keeps both values device-only. Credentials are sent only in JSON request bodies to the configured AuthOS origin and never enter URLs, logs, events, or replay evidence.

Entry points: server and client

• ./server is the server-only surface: createBetterAuthInstance, buildBetterAuthOptions, database hooks, OAuth provider discovery, resource-token policy and the development registration helpers. Its source file uses the .server.ts suffix, so the package boundary check fails any client ('use client' / .client.ts) graph that reaches it.
• ./client (createAuthClient, createBetterAuthBridgeClient) and ./native-session-client are the browser and native clients; ./bridge-plan and ./edge-cookie are pure and safe in any runtime.
• The root entry stays a compatibility barrel that re-exports ./server plus both clients. Server hosts may keep importing it; client code must use the explicit client entries.

Verification

bun run lint:check
bun run typecheck
bun run test
bun run build

Pure bridge-plan inspection

Utiliser @lssm-tech/integration.authos-better-auth/bridge-plan for browser/native inspection of provider plugin plans. It retains buildBetterAuthBridgePlan behavior without importing Better Auth server initialization, database adapters or Next.js cookie integration. The existing root/config exports remain compatible for server consumers. Native preview imports must use this pure entry point; a build-boundary test guards against server code re-entering the graph.

Better Auth 1.7 client compatibility

The shared bridge no longer imports the removed genericOAuthClient plugin. Existing signIn.oauth2({ providerId, ...options }) and oauth2.link({ providerId, ...options }) bridge calls are retained as adapters to Better Auth's supported signIn.social and linkSocial methods. They translate providerId to provider, preserve request options and return provider errors. Other dynamic client methods retain their original behavior.

This client repair does not migrate provider registrations, callback forwarding routes, native clients built directly on Better Auth, or account identity data. Review those separately using the Better Auth 1.7 upgrade guide before qualifying live OAuth. No production identity records were changed.

Server-side bearer session reads

createBetterAuthBearerSessionReader resolves a bearer through the configured AuthOS /api/auth/get-session?disableCookieCache=true endpoint and maps it to the canonical AuthOsSession. It requires HTTPS except loopback development, forbids redirects, bounds time/body size, and rejects expired, banned or mismatched user sessions. Tokens, email and role strings are not returned. This is authentication only: callers must separately resolve current tenant-scoped permissions and must not infer fleet-management access from the identity or provider role.

Proposed reviewed development resource authority

Both development registration recipes require the same canonical reviewed-profile verifier as the optional resource-token factory. Missing/non-function verification or any result other than literal true rejects before store, provider, resource-link or secret-manager calls. Actual canonical registry, admin/lifecycle serialization and resumable cleanup adapters remain required and unqualified.

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.

The proposed development composition adds a current canonical reviewed-profile registry verifier and serialized workload registration journal recipe. The recipe resumes persisted safe phases, verifies actual native client/resource configuration and quarantines orphan clients. It requires a genuine privileged provider/store adapter, secret manager, serialized durable journal and atomic canonical registration completion. These source helpers do not approve a security review, create trust or enable the issuer. Adoption and runtime admission remain required.

Pure binding checks for host adapters ship through ./server (and the root barrel), still PROPOSED_NOT_ADMITTED and side-effect free: assertNativeAccessTokenClaimsBindingV1/nativeIssuanceNotBeforeV1 (single lane resource, scope subset, unchanged identity, exact workload metadata, one safe DB clock row); the dev-registration-binding checks behind SerializedDevRegistrationAdminV1 (client_credentials-only creation, resource and lookup binding, the 4096-client inventory bound, exact native client and current reviewed resource/link); and admitApprovedDevSecurityReviewV1 with the database-system and installer-window assertions (canonical JSON that rejects rather than omits non-JSON content, approved SHA-256 and profile digest binding). Hosts keep the SQL, locks, roles and DB clock reads.

The app custody adapter can complete a fresh registration after checking immutable GCP-version bytes against the genuine one-time native client secret. Persisted resume currently quarantines: a nonempty version alone cannot prove the native credential still matches. A genuine provider verification context is required before enabling recovery. Native policy/key callbacks commit their read transactions before issuance completes, so actual issuance/revocation concurrency remains an explicit qualification requirement.

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.