R&D documentation

RQ3 — better-auth 1.7 vs Auth.js v5: feature matrix

Source: ddx-documentation/research/rq3-auth-matrix.md

Previous: RQ2 — Route group or dynamic org slug?Next: RQ4 — Separate databases or separate schemas?Inventory gallery

**Question** (BRIEF.md RQ3): what does "advanced auth V5" need that better-auth or Auth.js v5 cannot give (org plugin, teams, access control, JWT for ddx-api, API keys)? **Answer** (owner Q1, confirmed 2026-10-23): better-auth 1.7 gives every row natively. "Advanced auth V5" means feature parity with the HMS Auth.js v5 setup (credentials + WebAuthn passkey + org in session). Auth.js v5 is the rejected alternative. Decision: [ADR 0002](/en/docs/adr/0002-auth-better-auth). ## Matrix | Need | better-auth 1.7 | Auth.js v5 | Source | |---|---|---|---| | Email + password credentials | built in (`emailAndPassword`) | Credentials provider; no session DB for credentials by default | better-auth docs <https://better-auth.com/docs> (cited, not fetched 2026-10-23); Auth.js docs <https://authjs.dev> (cited, not fetched 2026-10-23) | | Organizations (multi-tenant) | `organization` plugin: orgs, members, invitations, active org on session | none built in; you build tables + callbacks | `~/.claude/ddx-topic-flows/VERSIONS.md` `betterauth1` row; R4 `~/.claude/findings/nextjs-skills-audit/research/R4-auth-org-providers-sse.md` | | Teams inside an org | `organization` plugin `teams` option | none built in | VERSIONS.md `betterauth1` ("organization plugin + teams + access control") | | Access control (roles, permissions) | `createAccessControl` + org roles | none built in; custom callbacks | VERSIONS.md `betterauth1`; R4 | | API keys (service + user scope) | `apiKey` plugin | none built in | better-auth plugin docs <https://better-auth.com/docs/plugins/api-key> (cited, not fetched 2026-10-23) | | Passkey (WebAuthn) | `passkey` plugin | WebAuthn provider (marked experimental) | better-auth <https://better-auth.com/docs/plugins/passkey>; Auth.js WebAuthn guide <https://authjs.dev/getting-started/authentication/webauthn> (cited, not fetched 2026-10-23) | | JWT / JWKS issued by the backend for ddx-api | `jwt` plugin: JWT + JWKS endpoint, verify in ddx-api guard | JWT session strategy in the Next.js app; no JWKS issuer | better-auth <https://better-auth.com/docs/plugins/jwt> (cited, not fetched 2026-10-23) | | Runs inside NestJS (ddx-api owns auth) | framework-agnostic handler; mount in Nest | built for Next.js route handlers first | better-auth docs; Auth.js docs | | Next.js integration | `nextCookies()` plugin (LAST in the list) | native | VERSIONS.md `betterauth1` row | | Harness canon for new projects | yes | legacy (existing HMS repos only) | VERSIONS.md `betterauth1` row; stack-specialist Next.js 16 rule | | Upstream activity | 1.7.11 latest on 2026-10-23 | — | <https://better-auth.com/changelog> (search excerpt 2026-10-23) | ## Gaps - No row needs a library change. API key + JWT in one ddx-api guard chain is RQ9 (a later task). - The plugin option names are from the docs above. The ddx-api scaffold task checks them against the installed `better-auth` types before wiring. ## Source note "Cited, not fetched" = the doc URL is the canonical page for the row, but this run did not open it. The row rests on the harness canon (VERSIONS.md, R4). The ddx-api scaffold task verifies each plugin against the installed package.

All pages (45)

- [ddx-documentation — dudoxx-web-boot](/en/docs) **adr/** - [ADR 0001 — Scaffold route: dudoxx-sandbox-creator with 163XX overrides](/en/docs/adr/0001-scaffold-route) - [ADR 0002 — Auth: better-auth 1.7 in ddx-api](/en/docs/adr/0002-auth-better-auth) - [ADR 0003 — Route shape: org slug, role, `[entity]/[id]`, `?view=`](/en/docs/adr/0003-route-shape) - [ADR 0004 — Database split: one Postgres 18 instance, six databases](/en/docs/adr/0004-database-split) - [ADR 0005 — Frameworks and the approved dependency table](/en/docs/adr/0005-frameworks) - [ADR 0006 — API clients come from one factory](/en/docs/adr/0006-factory) - [ADR 0007 — Typed service container (DI / IoC)](/en/docs/adr/0007-di-container) - [ADR 0008 — Singleton scope: what may live at module level](/en/docs/adr/0008-singleton-scope) - [ADR 0009 — One variant API for every inventory component](/en/docs/adr/0009-variant-api) - [ADR 0010 — Media path: presigned URLs from ddx-api after the org check](/en/docs/adr/0010-media-path) - [ADR 0011 — Media proxy: MinIO only through ddx-api](/en/docs/adr/0011-media-proxy) - [ADR 0012 — Density names: compact | cosy | large](/en/docs/adr/0012-density-names) - [ADR 0013 — Platform super-admin acts as org-admin of the target org](/en/docs/adr/0013-super-admin-platform-role) - [ADR 0014 — Unified settings: one registry, three tiers, one resolve in ddx-api](/en/docs/adr/0014-unified-settings) - [ADR 0015 — Entity kernel: one descriptor, one access seam, one projection, one proof chain](/en/docs/adr/0015-entity-kernel) - [ADR 0016 — SSE Bus: Redis Streams log, Redis pub/sub fan-out, BullMQ outbound queue](/en/docs/adr/0016-sse-bus) - [ADR 0017 — Layered BFF: one route table, route classes, read models](/en/docs/adr/0017-bff-layered) - [ADR 0018 — Cluster node registry, node identity, hot plug](/en/docs/adr/0018-cluster-node-registry) - [ADR 0019 — Tenant branding: settings keys, vendored palettes, public platform read](/en/docs/adr/0019-tenant-branding) - [Debug overlay](/en/docs/debug-overlay) **deploy/** - [Deploy runbook — dudoxx-web-boot](/en/docs/deploy/README) - [Entity kernel — guide](/en/docs/entity-kernel) - [Feature map — what each role can do](/en/docs/features) - [Component inventory](/en/docs/inventory) - [Naming constitution — dudoxx-web-boot](/en/docs/naming-constitution) - [Observability — one log layout, one key set](/en/docs/observability) - [Pattern reference — P1-P23 and groups A-K](/en/docs/patterns) - [Port map — dudoxx-web-boot](/en/docs/ports) **research/** - [RQ1 — Which release is "latest", and does it differ from the canon?](/en/docs/research/rq1-versions) - [RQ10 — SSE through the Next.js BFF route handler (desk half)](/en/docs/research/rq10-sse-through-bff) - [RQ11 — Dev latency baseline: cold compile per route + next-server RSS](/en/docs/research/rq11-dev-latency) - [RQ2 — Route group or dynamic org slug?](/en/docs/research/rq2-route-shape) - [**RQ3 — better-auth 1.7 vs Auth.js v5: feature matrix**](/en/docs/research/rq3-auth-matrix) - [RQ4 — Separate databases or separate schemas?](/en/docs/research/rq4-db-split) - [RQ5 — Which frameworks beyond shadcn earn a place?](/en/docs/research/rq5-frameworks) - [RQ6 — How do DI, IoC and Singleton behave across RSC, client bundles and NestJS?](/en/docs/research/rq6-di-scope) - [RQ7 — Which data uses the server cache, which uses TanStack Query, how is each invalidated?](/en/docs/research/rq7-cache-classes) - [RQ8 — Media path: presigned URLs vs streaming through the BFF](/en/docs/research/rq8-media-path) - [Template triage — create-nextjs code in ddx-web](/en/docs/research/template-triage) - [Settings — guide](/en/docs/settings) - [Local setup — dudoxx-web-boot](/en/docs/setup) - [Shell tree — SiteShell and PortalShell](/en/docs/shell-tree) - [SSE event catalog](/en/docs/sse-events) - [Version pins — dudoxx-web-boot](/en/docs/versions)

R&D documentation

RQ3 — better-auth 1.7 vs Auth.js v5: feature matrix

Source: ddx-documentation/research/rq3-auth-matrix.md

Previous: RQ2 — Route group or dynamic org slug?Next: RQ4 — Separate databases or separate schemas?Inventory gallery

Question (BRIEF.md RQ3): what does "advanced auth V5" need that better-auth or Auth.js v5 cannot give (org plugin, teams, access control, JWT for ddx-api, API keys)?

Answer (owner Q1, confirmed 2026-10-23): better-auth 1.7 gives every row natively. "Advanced auth V5" means feature parity with the HMS Auth.js v5 setup (credentials + WebAuthn passkey + org in session). Auth.js v5 is the rejected alternative. Decision: .

Matrix

Need	better-auth 1.7	Auth.js v5	Source
Email + password credentials	built in (`emailAndPassword`)	Credentials provider; no session DB for credentials by default	better-auth docs (cited, not fetched 2026-10-23); Auth.js docs (cited, not fetched 2026-10-23)
Organizations (multi-tenant)	`organization` plugin: orgs, members, invitations, active org on session	none built in; you build tables + callbacks	`~/.claude/ddx-topic-flows/VERSIONS.md` `betterauth1` row; R4 `~/.claude/findings/nextjs-skills-audit/research/R4-auth-org-providers-sse.md`
Teams inside an org	`organization` plugin `teams` option	none built in	VERSIONS.md `betterauth1` ("organization plugin + teams + access control")
Access control (roles, permissions)	`createAccessControl` + org roles	none built in; custom callbacks	VERSIONS.md `betterauth1`; R4
API keys (service + user scope)	`apiKey` plugin	none built in	better-auth plugin docs (cited, not fetched 2026-10-23)
Passkey (WebAuthn)	`passkey` plugin	WebAuthn provider (marked experimental)	better-auth ; Auth.js WebAuthn guide (cited, not fetched 2026-10-23)
JWT / JWKS issued by the backend for ddx-api	`jwt` plugin: JWT + JWKS endpoint, verify in ddx-api guard	JWT session strategy in the Next.js app; no JWKS issuer	better-auth (cited, not fetched 2026-10-23)
Runs inside NestJS (ddx-api owns auth)	framework-agnostic handler; mount in Nest	built for Next.js route handlers first	better-auth docs; Auth.js docs
Next.js integration	`nextCookies()` plugin (LAST in the list)	native	VERSIONS.md `betterauth1` row
Harness canon for new projects	yes	legacy (existing HMS repos only)	VERSIONS.md `betterauth1` row; stack-specialist Next.js 16 rule
Upstream activity	1.7.11 latest on 2026-10-23	—	(search excerpt 2026-10-23)

Gaps

No row needs a library change. API key + JWT in one ddx-api guard chain is RQ9 (a later task).
The plugin option names are from the docs above. The ddx-api scaffold task checks them against the installed better-auth types before wiring.

Source note

"Cited, not fetched" = the doc URL is the canonical page for the row, but this run did not open it. The row rests on the harness canon (VERSIONS.md, R4). The ddx-api scaffold task verifies each plugin against the installed package.