better_auth 0.8.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98014e245459f3b5a7de74fbd1e41ac5449ff223e20e5f9c8ef9500e15c55d9f
-  data.tar.gz: 28252ead0ea2f370233bcc73bcc41568604608ff2d4d891a66abf71f49e01497
+  metadata.gz: 7d7cf9a11bc4e929dad460e2d1d72cf12e9a34465f73d14259293267f06e591e
+  data.tar.gz: 06c018ee8a3fad409045a6a6639c851fb596a854707540dc710f8651e87b0d79
 SHA512:
-  metadata.gz: 22e4e6488cebfdc63f77d68747df4283ccf27c82381ab6bb7e372485f0c2d93cb4e37dce4748e75020f6556ff08a675ba42d47cf39a57f90c86f2d4a396c09b4
-  data.tar.gz: a05af007c3dcd034bc035a37e825991ce76ff8af9199ae33f4a3ecf2250718ac848ae52baa84d2d60c7b5eace5d7f2750de2d40dde779b182640184b50d1a765
+  metadata.gz: 7a9cd8c96e722eff39babca55e87e60dffa4c6ee723bf798a3ef4f10cff7b057d7326b39271bfe4ffd07f35937ad3b5697ec273882622d6dc84597ac8fe0315a
+  data.tar.gz: 8c9de78cd3169537c5d9bf9c2c4ade7cf53c6e5f9dbb76d8debf58f0bdedb6f0b4bf7e4a19608801bc269988c93b358271c3aff06a53f1dd4229c07062559f7a

data/CHANGELOG.md

@@ -5,8 +5,100 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.0](https://github.com/salasebas/better-auth-rb/compare/better_auth-v0.10.0...better_auth/v0.11.0) (2026-07-23)
+
+
+### ⚠ BREAKING CHANGES
+
+* **release:** OpenAuth alias gems, the openauth executable, and the better_auth_rails alias gem and require path are removed.
+* **oauth-provider:** unify OAuth/OIDC/MCP under oauth_provider gem
+
+### Features
+
+* **adapters:** add atomic storage primitives ([8d715c9](https://github.com/salasebas/better-auth-rb/commit/8d715c92ba2dbd4aa4b167a3319a9ac94c629519))
+* **auth:** complete API catalog parity ([234fd77](https://github.com/salasebas/better-auth-rb/commit/234fd77983866dbdcb6be8a3d1b2604a7fd0ce60))
+* **auth:** improve OAuth provider parity ([3c1c3c3](https://github.com/salasebas/better-auth-rb/commit/3c1c3c3466dd4782732c988555fe80bc43a1abbd))
+* **better_auth:** lazy-load in-core plugins on demand ([66c3002](https://github.com/salasebas/better-auth-rb/commit/66c300212e6f72bf41284b73ac7207a9b2886af9))
+* **cli:** add config discovery, secret, and info diagnostics ([e522cf6](https://github.com/salasebas/better-auth-rb/commit/e522cf6755512b465dbf2f2589eb2335db6f1af4))
+* **core:** add i18n plugin ([ab6a2f3](https://github.com/salasebas/better-auth-rb/commit/ab6a2f38750c3be141dba21c039c84ec603b2a68))
+* **email-otp:** remove deprecated password reset alias ([bc4614a](https://github.com/salasebas/better-auth-rb/commit/bc4614a23bbd7464e56455777b6b980f20d7e012))
+* **oauth-provider:** align protocol behavior with upstream ([9217273](https://github.com/salasebas/better-auth-rb/commit/9217273069ffa2c18d256a8c1d9d5487a8d316c1))
+* **oauth-provider:** unify OAuth/OIDC/MCP under oauth_provider gem ([7d16def](https://github.com/salasebas/better-auth-rb/commit/7d16def22ea26f753e520e95522568261eca2090))
+* **organization:** align membership limits and lifecycle hooks ([81ab81e](https://github.com/salasebas/better-auth-rb/commit/81ab81ef80aa6d35a6f4bf8a4e54be910fd07aa6))
+* **schema:** align migration plugin schema parity ([c0261dc](https://github.com/salasebas/better-auth-rb/commit/c0261dc1e5fd649557cd8a57b92c0609620c3767))
+* **schema:** honor plugin migration controls ([#48](https://github.com/salasebas/better-auth-rb/issues/48)) ([c67e8bf](https://github.com/salasebas/better-auth-rb/commit/c67e8bf216a2b5f8ad52f53cb9f56e6cfbfa39bb))
+
+
+### Bug Fixes
+
+* **adapters:** fail closed on singular updates ([c7cf07f](https://github.com/salasebas/better-auth-rb/commit/c7cf07fe19887d682eb94956617532d840beb018))
+* **adapters:** preserve joined records with projected queries ([#47](https://github.com/salasebas/better-auth-rb/issues/47)) ([acd9197](https://github.com/salasebas/better-auth-rb/commit/acd919746715c15a752f0b2861322d09a4f49f20))
+* **auth:** consume single-use state atomically ([07bedc1](https://github.com/salasebas/better-auth-rb/commit/07bedc1c114189e0039a63f2a0cf377658fe457c))
+* **auth:** harden email change verification ([#45](https://github.com/salasebas/better-auth-rb/issues/45)) ([56f631a](https://github.com/salasebas/better-auth-rb/commit/56f631ac9ead26bf7f5719b07ade5ebbac7f3a0a))
+* **auth:** harden token link base URLs ([#36](https://github.com/salasebas/better-auth-rb/issues/36)) ([22d714c](https://github.com/salasebas/better-auth-rb/commit/22d714ce6183b51b555424ebb7e3d2ca0dd36967))
+* **auth:** prevent unverified account takeover ([caae231](https://github.com/salasebas/better-auth-rb/commit/caae23154600a19f637c247466b55404839a2f7a))
+* **auth:** use secure magic-link tokens ([#46](https://github.com/salasebas/better-auth-rb/issues/46)) ([20fcc0b](https://github.com/salasebas/better-auth-rb/commit/20fcc0bbe44371332c2f11187b34d70b3c57e2ce))
+* **auth:** validate social provider identities ([2028af8](https://github.com/salasebas/better-auth-rb/commit/2028af879e4ac61ebc30b3cbc0a4aa32b2d497fe))
+* **ci:** resolve Ruby 3.4 lint, plugin loading, and upstream parity ([ecf5edd](https://github.com/salasebas/better-auth-rb/commit/ecf5edd032eb3695e94456754779656fe017cd7b))
+* **core:** clear session cookies when signed session token is invalid ([d7c2702](https://github.com/salasebas/better-auth-rb/commit/d7c2702529bb6aa0e6fbdc54d1ca5f610c46effb))
+* **core:** harden plugin security and parity ([1cb70f9](https://github.com/salasebas/better-auth-rb/commit/1cb70f940aca6186b39cd2e3f438fe197fbb5495))
+* **core:** prefer adapter execute over Kernel#exec in SQL migrations ([fe99b4f](https://github.com/salasebas/better-auth-rb/commit/fe99b4f4bf6bb20e138691b9e777d64620f8cde4))
+* **core:** restore access-control factory and MSSQL execute signature ([040f583](https://github.com/salasebas/better-auth-rb/commit/040f5839ebe788448cbc39dd403b9ba6a19e50eb))
+* **email-otp:** keep OTP helpers server-only ([#42](https://github.com/salasebas/better-auth-rb/issues/42)) ([99d2469](https://github.com/salasebas/better-auth-rb/commit/99d2469029d6e5b0f439c1b5ed868c544da443f2))
+* harden client IP rate-limit keys ([#39](https://github.com/salasebas/better-auth-rb/issues/39)) ([cb2fefd](https://github.com/salasebas/better-auth-rb/commit/cb2fefd543ef92f8c2c10fedef7f3bd659a90196))
+* load external plugin gems without stub recursion ([4926bae](https://github.com/salasebas/better-auth-rb/commit/4926bae7520c17438de25e99cb2155839c177493))
+* **organization:** enforce membership limit on member creation ([8f7796a](https://github.com/salasebas/better-auth-rb/commit/8f7796aa093c98239914492e66b62e4f1364896b))
+* **organization:** protect creator role updates ([#44](https://github.com/salasebas/better-auth-rb/issues/44)) ([acf03a4](https://github.com/salasebas/better-auth-rb/commit/acf03a4a97d6f4e2a8e4aea88e1fb79cb5197fca))
+* **plugins:** enforce organization and device ownership ([1177216](https://github.com/salasebas/better-auth-rb/commit/117721660a4323926456c5c8b0461c77ff5e651f))
+* **rate-limit:** enforce atomic request limits ([3d7b145](https://github.com/salasebas/better-auth-rb/commit/3d7b145034880459ca7582061ebc4744e12f20a8))
+* **saml:** fail closed without response parser ([#35](https://github.com/salasebas/better-auth-rb/issues/35)) ([0f9a7a4](https://github.com/salasebas/better-auth-rb/commit/0f9a7a4fb841153951b5f00ce42f01eee41b3112))
+* **saml:** verify signed SLO XML messages ([#43](https://github.com/salasebas/better-auth-rb/issues/43)) ([e7730cf](https://github.com/salasebas/better-auth-rb/commit/e7730cf01a683a4b24f1506fd52fda624f4ef028))
+* **scim:** harden provisioning lifecycle ([da956cd](https://github.com/salasebas/better-auth-rb/commit/da956cd117f991f3632ce22611e32b97b1bd1e24))
+* separate canonical and serving origins ([#37](https://github.com/salasebas/better-auth-rb/issues/37)) ([c1bd12e](https://github.com/salasebas/better-auth-rb/commit/c1bd12e81a1cb21a8d0ba186cefd554753e565f6))
+* **session:** enforce authoritative session checks ([0eebb9b](https://github.com/salasebas/better-auth-rb/commit/0eebb9b1a10f9cceaaa05401084fb0d07065c1e3))
+* **siwe:** add get-nonce compatibility alias ([#49](https://github.com/salasebas/better-auth-rb/issues/49)) ([543478d](https://github.com/salasebas/better-auth-rb/commit/543478d2423b4411c68c2069d633ef268a1010a5))
+* **sso:** harden OIDC endpoint fetching ([#38](https://github.com/salasebas/better-auth-rb/issues/38)) ([177bf8b](https://github.com/salasebas/better-auth-rb/commit/177bf8b847ba4e2a8478d82338b3e4cc7b91932d))
+* **two-factor:** enforce verification attempt limits ([f0a8bf4](https://github.com/salasebas/better-auth-rb/commit/f0a8bf4789e9105191e951452879ab09589f5592))
+* unblock SAML/OIDC CI and release workflows ([9d7ed4e](https://github.com/salasebas/better-auth-rb/commit/9d7ed4eb9097a8bf05863bf90f9ba00ae5f2ec76))
+
+
+### Miscellaneous Chores
+
+* **release:** retire aliases and refresh parity tooling ([e099464](https://github.com/salasebas/better-auth-rb/commit/e0994643694267508a3c4d9be020bb1fd0e2e5a3))
+
 ## [Unreleased]
 
+### Added
+
+- Added the experimental `oauth_popup` server plugin with built-in and Generic
+  OAuth state validation, strict opener-origin checks, callback cookie
+  preservation, and optional Bearer integration.
+
+### Fixed
+
+- Hardened existing-identity linking, authoritative session checks, single-use
+  state consumption, and rate-limit behavior with regression coverage.
+- Made verification state atomic where the configured adapter supports the
+  required primitives, while retaining documented adapter compatibility paths.
+- Aligned OAuth Popup state confidentiality and single-use callback behavior,
+  duplicate session-cookie handling, and hidden endpoint metadata with upstream
+  v1.6.23.
+
+### Changed
+
+- Added a checked upstream server-test inventory for the pinned v1.6.23
+  reference; it distinguishes covered, adapted, not-applicable, and planned
+  behavior rather than asserting blanket version parity.
+
+## [0.10.0] - 2026-05-21
+
+### Fixed
+
+- Fixed organization owner counting to page through adapter results instead of
+  relying on a single uncapped `find_many` call.
+- Improved SQL, memory, cookie, rate-limit, plugin schema, social login, and
+  auth response edge cases for more consistent behavior across adapters.
+
 ## [0.7.0] - 2026-05-05
 
 ### Added

data/LICENSE.md

@@ -1,5 +1,5 @@
 The MIT License (MIT)
-Copyright (c) 2024 - present, Bereket Engida
+Copyright (c) 2024 - present
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

data/README.md

@@ -13,11 +13,11 @@
     ·
     <a href="https://better-auth.com">Website</a>
     ·
-    <a href="https://github.com/sebasxsala/better-auth/issues">Issues</a>
+    <a href="https://github.com/sebasxsala/better-auth-rb/issues">Issues</a>
   </p>
 
 [![Gem](https://img.shields.io/gem/v/better_auth?style=flat&colorA=000000&colorB=000000)](https://rubygems.org/gems/better_auth)
-[![GitHub stars](https://img.shields.io/github/stars/sebasxsala/better-auth?style=flat&colorA=000000&colorB=000000)](https://github.com/sebasxsala/better-auth/stargazers)
+[![GitHub stars](https://img.shields.io/github/stars/sebasxsala/better-auth?style=flat&colorA=000000&colorB=000000)](https://github.com/sebasxsala/better-auth-rb/stargazers)
 </p>
 
 ## About the Project
@@ -61,11 +61,20 @@ gem install better_auth
 require 'better_auth'
 
 auth = BetterAuth.auth(
+  base_url: ENV.fetch("BETTER_AUTH_URL"),
   secret: ENV.fetch("BETTER_AUTH_SECRET"),
   database: :memory
 )
 ```
 
+In production, token-bearing email links require either a static `base_url`
+(including `BETTER_AUTH_URL`) or a dynamic `base_url` with `allowed_hosts`.
+Request-host inference remains available for other routes and in development.
+Legacy deployments can opt out with
+`advanced: { allow_unsafe_token_link_base_url_inference: true }`, but doing so
+allows request headers to select the origin used in security-token links and is
+not recommended.
+
 ### Secret Rotation
 
 Better Auth Ruby supports upstream-style non-destructive rotation for encrypted data through versioned secrets. The first entry is used for new encrypted payloads; older entries remain available for decrypting existing data.
@@ -143,6 +152,21 @@ auth = BetterAuth.auth(
 )
 ```
 
+Custom adapters must implement
+`create_if_absent(model:, data:, conflict_field: "id", force_allow_id: true)`
+as a targeted first-writer-wins insert returning a boolean,
+`consume_one(model:, where:)` as an atomic
+delete-and-return of at most one row, and
+`increment_one(model:, where:, increment:, set: nil)` as an atomic guarded
+numeric update returning the resulting row or `nil`. Concurrent consumers of
+one row must have exactly one winner; increments must apply every signed delta
+without lost updates. `transaction` must open a real transaction and reuse its
+active adapter for nested calls. The base class's compatibility yield is
+explicitly non-atomic and must not back either primitive.
+Only mutable schema fields declared with `type: "number"` may be incremented;
+IDs and string, boolean, date, array, immutable, or unknown fields are rejected.
+The base adapter intentionally has no check-then-create fallback.
+
 ### Social Providers
 
 ```ruby
@@ -163,6 +187,55 @@ auth = BetterAuth.auth(
 )
 ```
 
+### i18n
+
+Translate server error messages by locale. This plugin is server-side only: clients receive translated error JSON from the existing HTTP routes, and there is no Ruby browser client plugin.
+
+```ruby
+auth = BetterAuth.auth(
+  secret: ENV.fetch("BETTER_AUTH_SECRET"),
+  database: :memory,
+  plugins: [
+    BetterAuth::Plugins.i18n(
+      translations: {
+        "fr" => {
+          "INVALID_EMAIL_OR_PASSWORD" => "Identifiants invalides"
+        }
+      },
+      detection: ["cookie", "header"],
+      locale_cookie: "lang"
+    )
+  ]
+)
+```
+
+### Organizations
+
+The organization plugin supports upstream-style organizations, members,
+invitations, teams, roles, membership limits, and organization lifecycle hooks.
+Ruby option and hook names use snake_case.
+
+```ruby
+auth = BetterAuth.auth(
+  secret: ENV.fetch("BETTER_AUTH_SECRET"),
+  database: :memory,
+  plugins: [
+    BetterAuth::Plugins.organization(
+      membership_limit: 25,
+      disable_organization_deletion: true,
+      organization_hooks: {
+        before_update_organization: ->(data, _ctx) { { data: { name: data[:organization][:name].strip } } },
+        after_add_member: ->(data, _ctx) { Audit.log("member added", data[:member]) }
+      }
+    )
+  ]
+)
+```
+
+Direct member adds and invitation acceptance enforce `membership_limit`.
+Deleting or leaving the active organization clears the active organization and
+team session fields.
+
 ### JavaScript Client
 
 Ruby Better Auth exposes the same HTTP route surface. Frontend apps should use the upstream Better Auth JavaScript client and point it at the Ruby server:
@@ -176,6 +249,25 @@ export const authClient = createAuthClient({
 });
 ```
 
+For experimental popup-based OAuth in an embedded application, register the
+server plugin with Bearer and configure the opener as a trusted origin:
+
+```ruby
+auth = BetterAuth.auth(
+  base_url: "https://auth.example.com",
+  secret: ENV.fetch("BETTER_AUTH_SECRET"),
+  trusted_origins: ["https://app.example.com"],
+  plugins: [
+    BetterAuth::Plugins.oauth_popup,
+    BetterAuth::Plugins.bearer
+  ]
+)
+```
+
+Use the upstream JavaScript `oauthPopupClient` against this Ruby server. The
+Ruby package provides the server route and callback handling, not a browser
+client. Prefer the ordinary redirect flow for top-level applications.
+
 ### Rails Integration
 
 Add to your Gemfile:
@@ -206,13 +298,13 @@ end
 
 ## Development
 
-Full documentation is being adapted in the root [`docs/`](/Users/sebastiansala/projects/better-auth/docs/README.md) app. Start with the Ruby-first installation, basic usage, Rack, Rails, PostgreSQL, and MySQL pages there; pages with a Ruby port warning still contain upstream TypeScript examples for reference.
+Full documentation is being adapted in the root [`docs-site/`](../../docs-site/README.md) app. Start with the Ruby-first installation, basic usage, Rack, Rails, PostgreSQL, and MySQL pages there; pages with a Ruby port warning still contain upstream TypeScript examples for reference.
 
 ### Quick Start
 
 ```bash
 # 1. Clone the repository
-git clone https://github.com/sebasxsala/better-auth.git
+git clone https://github.com/sebasxsala/better-auth-rb.git
 cd better-auth/packages/better_auth
 
 # 2. Install dependencies
@@ -249,106 +341,37 @@ make db-down         # Stop containers
 
 ### Branch Workflow
 
-This project uses a branch model similar to the upstream:
-
-**Main Branches:**
-
-- **`main`**: Stable code, ready for production
-- **`canary`**: Development/integration branch (like "development" but specific name)
-  - "Canary" comes from "canary in a coal mine" - where changes are tested before production
-  - Feature PRs go to `canary`
-  - When `canary` is stable, merge to `main` for release
-
-**Typical workflow:**
+Development happens on `main`. Create feature branches from `main` and open PRs
+back to `main`.
 
 ```bash
-# 1. Create your feature branch from canary
-git checkout canary
-git pull origin canary
+git checkout main
+git pull origin main
 git checkout -b feat/new-feature
-
-# 2. Make your changes and commits
-# ... code ...
-git add .
-git commit -m "feat(core): add support for X"
-
-# 3. Push and create PR towards canary
+# ... work ...
 git push origin feat/new-feature
-# Create PR on GitHub towards canary
-
-# 4. Once merged to canary and tested,
-#    merge canary → main for release
 ```
 
-**Why canary instead of development?**
-
-- Common name in projects with frequent releases
-- Suggests it's an "experimental" version that might break
-- Allows multiple levels: feature → canary → main
-
 ### How CI/CD Works
 
 **Pull Requests:**
 - Each PR runs: lint + tests on Ruby 3.2 and 3.3
 - Everything must pass before merging
 
-**Automatic Release (GitHub Actions):**
+**Synchronized releases:**
 
-Release is triggered by package-prefixed tags so each gem can ship independently.
+Release Please maintains one combined version/changelog PR for the 19 linked
+Better Auth gems. After that PR merges, Release Please creates `<gem>/vX.Y.Z`
+tags and GitHub Releases. An environment-approved job validates every tag and
+builds every artifact before configuring RubyGems Trusted Publishing. It then
+publishes in dependency order, skipping an existing immutable gem only when its
+SHA-256 checksum matches. See the repository-root `RELEASING.md` for setup,
+recovery, and operations.
 
-```bash
-# STEP 1: Update the target package version file
-# Example: VERSION = "0.1.1"
-
-# STEP 2: Commit and push to main
-git add lib/better_auth/version.rb
-git commit -m "chore: bump version to 0.1.1"
-git push origin main
-
-# STEP 3: Create the tag for the gem you want to publish
-git tag better_auth-v0.1.1
-git push origin better_auth-v0.1.1
-
-# STEP 4: GitHub Actions automatically:
-# - Runs tests
-# - Builds the gem
-# - Publishes to RubyGems (if version is new)
-# - Creates GitHub Release
-```
-
-Use `better_auth-vX.Y.Z` for the core gem, `better_auth-rails-vX.Y.Z` for Rails, `better_auth-sinatra-vX.Y.Z` for Sinatra, and `better_auth-hanami-vX.Y.Z` for Hanami.
-
-**Required GitHub Configuration:**
-
-1. In RubyGems, configure Trusted Publishing for each gem that should publish from CI.
-2. Use this repository and workflow file: `.github/workflows/release.yml`.
-3. The workflow exchanges GitHub's OIDC token for short-lived RubyGems credentials when the matching package tag is pushed.
-
-**Dry-run options:**
+**Local packaging dry-run:**
 
 ```bash
-# Local packaging dry-run
 make release-check
-
-# CI dry-run from GitHub Actions
-# Actions -> Release -> Run workflow -> dry_run=true
-```
-
-### Manual Release (without GitHub Actions)
-
-Only if you need to do a manual release:
-
-```bash
-# 1. Update version.rb
-# 2. Build the gem
-gem build better_auth.gemspec
-
-# 3. Publish (you need to be logged into RubyGems)
-gem push better_auth-*.gem
-
-# 4. Create and push the tag
-git tag -a better_auth-v0.1.1 -m "Release better_auth v0.1.1"
-git push origin better_auth-v0.1.1
 ```
 
 ### Project Structure
@@ -370,7 +393,7 @@ test/                       # Core tests (Minitest)
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/sebasxsala/better-auth. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/sebasxsala/better-auth/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/sebasxsala/better-auth-rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/sebasxsala/better-auth-rb/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -378,15 +401,39 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Security
 
+### Canonical and serving origins
+
+`base_url` (or `BETTER_AUTH_URL`) is required and defines the stable canonical
+identity of the auth server. RubyAuth never infers that identity from request
+headers. For an approved multi-domain deployment, configure full origin
+patterns separately:
+
+```ruby
+BetterAuth.auth(
+  secret: ENV.fetch("BETTER_AUTH_SECRET"),
+  base_url: "https://auth.example.com",
+  serving_origins: ["https://tenant.example.com", "https://*.preview.example.com"],
+  trusted_origins: ["https://frontend.example.com"]
+)
+```
+
+`serving_origins` may select the request-facing URL used by verification,
+password-reset, deletion, and magic-link capabilities. Unknown hosts fall back
+to the canonical URL. Serving origins are trusted for CSRF and redirect checks,
+but the reverse is intentionally false: a `trusted_origins` entry cannot become
+a serving origin or control token-bearing links.
+
+`X-Forwarded-Host` and `X-Forwarded-Proto` are considered only when
+`advanced.trusted_proxy_headers` is explicitly `true`, and the resulting origin
+must still match `serving_origins`. The former hash/dynamic form of `base_url`
+is unsupported; migrate its fallback to `base_url` and its allowlist to full
+`serving_origins` patterns.
+
 ### Trusted origins
 
-`trusted_origins` is merged with the resolved application origin and deployment
-configuration rather than acting as an adapter-local CORS switch. Upstream
-Better Auth also incorporates environment-driven origins and dynamic
-configuration, so an explicit empty array should not be assumed to mean "reject
-every browser origin" unless the deployed core configuration documents that full
-merge contract. Configure concrete origins for each environment and keep browser
-CORS headers in the host Rack stack or reverse proxy. See
+`trusted_origins` is merged with the canonical and serving origins rather than
+acting as an adapter-local CORS switch. Configure concrete origins for each
+environment and keep browser CORS headers in the host Rack stack or reverse proxy. See
 [`host-app-responsibilities.md`](../../.docs/features/host-app-responsibilities.md)
 for the boundary between origin validation, CORS, and CSRF ownership.
 

data/lib/better_auth/adapters/base.rb

@@ -5,14 +5,23 @@ module BetterAuth
     class Base
       attr_reader :options
 
-      def initialize(options)
+      TRANSACTION_CONTEXT_KEY = :better_auth_adapter_transaction_context
+
+      def initialize(options, transaction_context_key: nil)
         @options = options
+        @transaction_context_key = transaction_context_key || Object.new
       end
 
       def create(**)
         raise NotImplementedError
       end
 
+      # Atomically insert a row unless +conflict_field+ already exists. Adapter
+      # implementations must not emulate this with a check followed by create.
+      def create_if_absent(model:, data:, conflict_field: "id", force_allow_id: true)
+        raise NotImplementedError
+      end
+
       def find_one(**)
         raise NotImplementedError
       end
@@ -41,9 +50,63 @@ module BetterAuth
         raise NotImplementedError
       end
 
+      # Atomically delete and return at most one matching row. Concurrent
+      # consumers of the same row must produce exactly one non-nil result.
+      def consume_one(**)
+        raise NotImplementedError
+      end
+
+      # Atomically apply signed numeric deltas, with +where+ acting as the
+      # selector and guard, and return the resulting row or nil on a miss.
+      # Server-managed schema fields remain protected unless a trusted plugin
+      # or runtime caller opts in explicitly with +allow_server_managed+.
+      # Never derive privileged field names from user-controlled input.
+      def increment_one(model:, where:, increment:, set: nil, allow_server_managed: false)
+        raise NotImplementedError
+      end
+
       def transaction
         yield self
       end
+
+      # The base yield preserves compatibility for non-atomic batch work. It
+      # must never be used as proof that a check-then-act fallback is atomic.
+      def atomic_transactions?
+        false
+      end
+
+      private
+
+      attr_reader :transaction_context_key
+
+      def active_transaction_adapter
+        Thread.current[TRANSACTION_CONTEXT_KEY]&.fetch(transaction_context_key, nil)
+      end
+
+      def with_transaction_context(transaction_adapter)
+        context = Thread.current[TRANSACTION_CONTEXT_KEY] ||= {}
+        had_previous = context.key?(transaction_context_key)
+        previous = context[transaction_context_key]
+        context[transaction_context_key] = transaction_adapter
+        yield
+      ensure
+        if had_previous
+          context[transaction_context_key] = previous
+        else
+          context&.delete(transaction_context_key)
+          Thread.current[TRANSACTION_CONTEXT_KEY] = nil if context && context.empty?
+        end
+      end
+
+      def grouped_where_clauses(where)
+        Array(where).partition { |clause| fetch_key(clause, :connector).to_s.upcase != "OR" }
+      end
+
+      def fetch_key(hash, key)
+        return hash[key] if hash.key?(key)
+
+        hash[key.to_s]
+      end
     end
   end
 end