@beignet/provider-auth-better-auth 0.0.25 → 0.0.27

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @beignet/provider-auth-better-auth
 
+## 0.0.27
+
+### Patch Changes
+
+- f2461a9: Add lazy Next route server loaders and update generated route files and package docs to avoid booting providers during production build imports.
+
+## 0.0.26
+
+### Patch Changes
+
+- 104302c: Refresh package-shipped TanStack Intent skills and add package skills for Drizzle database providers, Better Auth, React Hook Form, and React uploads.
+
 ## 0.0.25
 
 ## 0.0.24

package/README.md

@@ -38,6 +38,14 @@ The provider supports Better Auth `>=1.3.26 <1.7.0`. The standard Beignet
 starter pins Better Auth to `1.6.20` so clean installs do not float into
 untested prerelease adapter versions.
 
+## Agent skills
+
+This package ships a TanStack Intent skill for coding agents:
+`@beignet/provider-auth-better-auth#auth-provider`. Load it when wiring
+Better Auth configuration, auth routes, `AuthPort` typing, deferred auth port
+registration, server context, `createAuthHooks`, user/session helpers,
+policies, devtools auth instrumentation, tests, or auth doctor drift.
+
 ## Setup
 
 ### 1. Configure Better Auth in your app
@@ -171,17 +179,20 @@ export const appContext = defineServerContext<AppContext, AppRuntimePorts>()({
 
 ```ts
 // server/index.ts
-import { createNextServer } from "@beignet/next";
+import { createNextServer, createNextServerLoader } from "@beignet/next";
 import { appPorts } from "@/infra/app-ports";
 import { appContext } from "@/server/context";
 import { routes } from "@/server/routes";
-import { providers } from "./providers";
 
-export const server = await createNextServer({
-  ports: appPorts,
-  providers,
-  context: appContext,
-  routes,
+export const getServer = createNextServerLoader(async () => {
+  const { providers } = await import("./providers");
+
+  return createNextServer({
+    ports: appPorts,
+    providers,
+    context: appContext,
+    routes,
+  });
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/provider-auth-better-auth",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "type": "module",
   "description": "Better Auth provider for Beignet - adds auth port for authentication and session management",
   "main": "./dist/index.js",
@@ -17,6 +17,7 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "!src/**/*.test-d.ts",
+    "skills",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -35,7 +36,8 @@
     "provider",
     "authentication",
     "session",
-    "ports"
+    "ports",
+    "tanstack-intent"
   ],
   "license": "MIT",
   "repository": {

package/skills/auth-provider/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: auth-provider
+description: "Wire Beignet Better Auth integration with @beignet/provider-auth-better-auth: app-owned Better Auth config, auth routes, AuthPort typing, deferred auth port registration, server context, createAuthHooks, requireUser helpers, policies, devtools auth instrumentation, tests, and doctor drift. Use when adding, fixing, or reviewing Better Auth provider setup in a Beignet app."
+---
+
+# Beignet Better Auth Provider
+
+Use this skill when working in an app that depends on
+`@beignet/provider-auth-better-auth`. Read local `AGENTS.md`,
+`lib/better-auth.ts`, auth route files, `ports/`, `infra/app-ports.ts`,
+`server/context.ts`, and `server/providers.ts` before changing auth code.
+
+## Ownership
+
+The provider wraps an app-owned Better Auth server and contributes the shared
+Beignet `AuthPort` at `ctx.ports.auth`.
+
+The app still owns:
+
+- Better Auth configuration, secrets, database adapter, and social providers
+- Better Auth route handlers, usually `app/api/auth/[...all]/route.ts`
+- public `AuthUser`, `AuthSession`, and app context shapes
+- business authorization policies and use-case checks
+- tests and production environment validation
+
+Do not put provider-specific Better Auth details in contracts, domain code,
+use cases, or feature route groups.
+
+## Provider Registration
+
+Create Better Auth in an app-local module, then register the provider in
+`server/providers.ts`.
+
+```ts
+import { createAuthBetterAuthProvider } from "@beignet/provider-auth-better-auth";
+import { auth } from "@/lib/better-auth";
+
+export const providers = [createAuthBetterAuthProvider(auth)] as const;
+```
+
+Add `auth` to `definePorts(...)` as a deferred port because the provider
+contributes it at startup.
+
+```ts
+export const appPorts = definePorts<AppPorts>()({
+  bound: { gate },
+  deferred: ["auth"],
+});
+```
+
+`beignet doctor --strict` checks that installed Better Auth providers are
+registered. Better Auth env vars remain app-owned, so validate them in the
+app's env module rather than expecting this provider to declare them.
+
+## Context
+
+Read the session once in `server/context.ts`, then store the result on
+`ctx.auth` and derive an audit actor.
+
+```ts
+export const appContext = defineServerContext<AppContext, AppRuntimePorts>()({
+  gate: (ports) => ports.gate,
+  request: async ({ req, ports, requestId, trace }) => {
+    const auth = await ports.auth.getSession(req);
+
+    return {
+      actor: auth ? createUserActor(auth.user.id) : createAnonymousActor(),
+      auth,
+      requestId,
+      ...trace,
+      ports,
+    };
+  },
+});
+```
+
+Service contexts for schedules, tasks, outbox drains, jobs, and webhooks should
+use a service or system actor and must not assume a browser session.
+
+## HTTP Auth Hooks
+
+Use `createAuthHooks(...)` for authentication at the HTTP boundary:
+
+```ts
+export const auth = createAuthHooks<AppContext>()({
+  resolve: ({ ctx }) => (ctx.auth ? { user: ctx.auth.user } : null),
+});
+```
+
+Attach `auth.required()` to route groups or route entries. Contract metadata
+may document auth requirements, but use cases should still enforce business
+rules that matter outside HTTP.
+
+## Use Cases And Policies
+
+Use app-owned helpers such as `requireUser(ctx)` or Beignet's
+`requireUser`, `requireUserId`, `requireTenant`, and `requireTenantId`
+helpers from `@beignet/core/ports` inside use cases.
+
+Put authorization in use cases or feature policies. The ability belongs to the
+feature that owns the authorized resource, not the feature initiating the
+action.
+
+## Gotchas
+
+- Better Auth routes are mounted separately from Beignet contract routes. Do
+  not route sign-in/sign-up through `defineRouteGroup(...)`.
+- The provider does not declare Better Auth env vars. Validate secrets,
+  trusted origins, adapter settings, and social credentials in app-owned env
+  code.
+- HTTP auth hooks prove a request is authenticated; they do not replace
+  use-case authorization or feature policies.
+- Service contexts for schedules, tasks, outbox drains, jobs, and webhooks
+  should use service/system actors, not `ctx.auth`.
+- Keep session objects, cookies, bearer tokens, and provider-native auth data
+  out of devtools, audit metadata, and error reports.
+
+## Devtools
+
+When `@beignet/devtools` is registered before this provider, auth checks are
+recorded under the Auth watcher. User and session objects are not recorded.
+Keep extra auth logging redacted and avoid placing raw tokens or cookies in
+devtools, audit metadata, or error reports.
+
+## Testing
+
+Use app-owned fake `AuthPort` implementations in use-case tests and route tests
+that only need authenticated/anonymous branches. Test Better Auth route wiring
+where the app mounts Better Auth handlers.
+
+After auth provider changes, run from the app root:
+
+```bash
+beignet lint
+beignet doctor --strict
+bun run test
+bun run typecheck
+```