@beignet/provider-auth-better-auth 0.0.42 → 0.0.44

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @beignet/provider-auth-better-auth
 
+## 0.0.44
+
+## 0.0.43
+
+### Patch Changes
+
+- 19b9c52: Add a direct Better Auth port adapter and use typed object options for provider setup.
+
 ## 0.0.42
 
 ## 0.0.41

package/README.md

@@ -17,6 +17,7 @@ schema, and auth routes.
 
 - Wraps a Better Auth instance with a simple, stable API
 - Extends `ports.auth` with `getSession`, `getUser`, and `requireUser` methods
+- Exposes a direct port adapter for custom app wiring
 - Maintains type safety for your custom User type
 - Records auth checks in devtools when devtools is installed
 
@@ -117,7 +118,7 @@ import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
 import { auth } from "@/lib/better-auth";
 
 export const providers = [
-  createBetterAuthProvider(auth),
+  createBetterAuthProvider({ auth }),
   // ...other providers
 ];
 ```
@@ -386,21 +387,53 @@ interface AuthSession<User = unknown, Session = unknown> {
 }
 ```
 
-### `createBetterAuthProvider(auth)`
+### `createBetterAuthProvider({ auth })`
 
 Factory function that creates the provider:
 
 ```ts
 function createBetterAuthProvider<User = unknown, Session = unknown>(
-  auth: BetterAuthServer<User, Session>
-): ServiceProvider
+  options: CreateBetterAuthProviderOptions<User, Session>
+): BetterAuthProvider<User, Session>
 ```
 
 **Parameters:**
-- `auth`: A Better Auth server instance configured in your application
+- `options.auth`: A Better Auth server instance configured in your application
 
 **Returns:** A Beignet provider that can be registered with the server
 
+### `createBetterAuthPort({ auth, instrumentation? })`
+
+Create the shared `AuthPort` directly when an app needs custom provider setup
+around its Better Auth instance:
+
+```ts
+// server/providers.ts
+import { createProvider } from "@beignet/core/providers";
+import { createBetterAuthPort } from "@beignet/provider-auth-better-auth";
+import { auth } from "@/lib/better-auth";
+
+export const appAuthProvider = createProvider({
+  name: "app-auth",
+  setup({ ports }) {
+    return {
+      ports: {
+        auth: createBetterAuthPort({ auth, instrumentation: ports }),
+      },
+    };
+  },
+});
+
+export const providers = [appAuthProvider] as const;
+```
+
+Define and register `appAuthProvider` in `server/providers.ts`, where provider
+audit can recognize the lower-level adapter as valid registration, and keep
+`auth` deferred in `infra/port-wiring.ts`. Outside lifecycle provider wiring,
+pass a Beignet provider instrumentation target explicitly when the adapter
+should emit the same redacted auth events. The adapter does not own or stop the
+Better Auth instance.
+
 ## Advanced usage
 
 ### Route-scoped authentication
@@ -462,8 +495,8 @@ export const requireAuth = async (
 Configure multiple strategies through Better Auth when its plugins cover the
 required session, bearer, or API-key behavior. When an app needs authentication
 outside Better Auth, compose that logic in an app-owned `AuthPort` adapter or
-HTTP auth hook; this package intentionally exports only the Better Auth
-provider.
+HTTP auth hook. Use `createBetterAuthPort(...)` when the app needs direct
+wiring for its existing Better Auth instance.
 
 ## Type safety
 
@@ -476,7 +509,7 @@ type MyUser = {
   role: "admin" | "user";
 };
 
-const authProvider = createBetterAuthProvider<MyUser>(auth);
+const authProvider = createBetterAuthProvider<MyUser>({ auth });
 
 // Later, in your routes:
 const user = await ctx.ports.auth.requireUser(req);
@@ -544,7 +577,7 @@ const auth = betterAuth({ database: db });
 
 const server = await createNextServer({
   ports: initialPorts,
-  providers: [createBetterAuthProvider(auth)],
+  providers: [createBetterAuthProvider({ auth })],
   context: appContext,
   routes,
 });
@@ -568,7 +601,7 @@ const authHook = {
 
 const server = await createNextServer({
   ports: initialPorts,
-  providers: [createBetterAuthProvider(auth)],
+  providers: [createBetterAuthProvider({ auth })],
   hooks: [authHook],
   context: appContext,
   routes,

package/dist/index.d.ts

@@ -1,9 +1,7 @@
 /**
  * @beignet/provider-auth-better-auth
  *
- * Better Auth provider that extends ports with authentication capabilities.
- * This provider wraps an already-configured Better Auth server instance
- * and exposes the shared Beignet AuthPort on ctx.ports.auth.
+ * Better Auth adapters for Beignet's shared authentication port.
  *
  * The provider does NOT own:
  * - Database schema
@@ -15,60 +13,20 @@
  *
  * @example
  * ```ts
- * // 1. Configure Better Auth in your app
+ * // Configure Better Auth in your app.
  * import { betterAuth } from "better-auth";
+ * import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
  * import { db } from "./db";
  *
  * export const auth = betterAuth({
  *   database: db,
- *   // ...other Better Auth config
- * });
- *
- * // Own this shape in your app instead of exporting provider-inferred types.
- * export type AuthUser = {
- *   id: string;
- *   name?: string | null;
- *   email?: string | null;
- *   image?: string | null;
- * };
- *
- * // 2. Define your ports type
- * import type { AuthPort } from "@beignet/core/ports";
- *
- * export type AppPorts = {
- *   auth: AuthPort<AuthUser>;
- *   // ...other ports
- * };
- *
- * // 3. Wire the provider into Beignet
- * import { createNextServer } from "@beignet/next";
- * import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
- *
- * const server = await createNextServer({
- *   ports: basePorts,
- *   providers: [
- *     createBetterAuthProvider(auth),
- *     // ...other providers
- *   ],
- * });
- *
- * // 4. Use the auth port through route-scoped auth hooks
- * import { createAuthHooks } from "@beignet/core/server";
- *
- * const auth = createAuthHooks<AppContext>()({
- *   resolve: ({ ctx }) => {
- *     return ctx.auth ? { user: ctx.auth.user } : null;
- *   },
  * });
  *
- * const server = await createNextServer({
- *   ports: basePorts,
- *   providers: [createBetterAuthProvider(auth)],
- *   context: async ({ ports }) => ({ ports }),
- * });
+ * export const authProvider = createBetterAuthProvider({ auth });
  * ```
  */
-import { type AuthPort, type AuthRequestLike } from "@beignet/core/ports";
+import { type AuthPort } from "@beignet/core/ports";
+import { type AnyProviderConfigSchema, type ProviderInstrumentationTarget, type ServiceProvider } from "@beignet/core/providers";
 /**
  * Minimal type representing a Better Auth server instance.
  * This is the interface we expect from the Better Auth library.
@@ -96,32 +54,59 @@ export type BetterAuthServer<User = unknown, Session = unknown> = {
     };
 };
 /**
- * Create a Beignet provider for Better Auth.
- *
- * This factory accepts an already-configured Better Auth server instance
- * and returns a provider that can be registered with Beignet.
- *
- * The provider extends ports.auth with an AuthPort that wraps the
- * Better Auth instance with a simple, stable API.
+ * Options for adapting an existing Better Auth server to Beignet's auth port.
+ */
+export interface CreateBetterAuthPortOptions<User = unknown, Session = unknown> {
+    /**
+     * Better Auth server instance configured and owned by the application.
+     */
+    auth: BetterAuthServer<User, Session>;
+    /**
+     * Optional provider instrumentation target.
+     */
+    instrumentation?: ProviderInstrumentationTarget;
+}
+/**
+ * Options for installing an existing Better Auth server as a Beignet provider.
+ */
+export interface CreateBetterAuthProviderOptions<User = unknown, Session = unknown> {
+    /**
+     * Better Auth server instance configured and owned by the application.
+     */
+    auth: BetterAuthServer<User, Session>;
+}
+/**
+ * Ports contributed by `createBetterAuthProvider`.
+ */
+export interface BetterAuthProviderPorts<User = unknown, Session = unknown> {
+    /**
+     * Beignet auth port backed by Better Auth.
+     */
+    auth: AuthPort<User, Session>;
+}
+/**
+ * Better Auth lifecycle provider with stable contributed-port typing.
+ */
+export type BetterAuthProvider<User = unknown, Session = unknown> = ServiceProvider<unknown, AnyProviderConfigSchema<void>, Pick<BetterAuthProviderPorts<User, Session>, keyof BetterAuthProviderPorts<User, Session>>>;
+/**
+ * Create a Beignet auth port backed by an existing Better Auth server.
  *
- * @param auth - A Better Auth server instance configured in the application
- * @returns A Beignet provider that extends ports.auth
+ * Use this for custom app wiring. The adapter does not own the Better Auth
+ * instance or add lifecycle hooks.
+ */
+export declare function createBetterAuthPort<User = unknown, Session = unknown>({ auth, instrumentation: instrumentationTarget, }: CreateBetterAuthPortOptions<User, Session>): AuthPort<User, Session>;
+/**
+ * Create a Beignet provider for an existing Better Auth server.
  *
  * @example
  * ```ts
  * import { betterAuth } from "better-auth";
  * import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
- * import { createNextServer } from "@beignet/next";
+ * import { db } from "./db";
  *
  * const auth = betterAuth({ database: db });
- *
- * const server = await createNextServer({
- *   ports: basePorts,
- *   providers: [createBetterAuthProvider(auth)],
- * });
+ * const provider = createBetterAuthProvider({ auth });
  * ```
  */
-export declare function createBetterAuthProvider<User = unknown, Session = unknown>(auth: BetterAuthServer<User, Session>): import("@beignet/core/providers").ServiceProvider<unknown, import("@standard-schema/spec").StandardSchemaV1<void, void>, {
-    auth: AuthPort<User, Session, AuthRequestLike>;
-}, unknown, void>;
+export declare function createBetterAuthProvider<User = unknown, Session = unknown>({ auth, }: CreateBetterAuthProviderOptions<User, Session>): BetterAuthProvider<User, Session>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAEH,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,eAAe,EAErB,MAAM,qBAAqB,CAAC;AAM7B;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI;IAChE;;;OAGG;IACH,GAAG,EAAE;QACH;;;;WAIG;QACH,UAAU,CAAC,OAAO,EAAE;YAClB,OAAO,EAAE,OAAO,CAAC;SAClB,GAAG,OAAO,CAAC;YAAE,IAAI,EAAE,IAAI,CAAC;YAAC,OAAO,EAAE,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC,CAAC;KACtD,CAAC;CACH,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EACxE,IAAI,EAAE,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC;;kBAsItC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,KAAK,QAAQ,EAGd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,uBAAuB,EAG5B,KAAK,6BAA6B,EAClC,KAAK,eAAe,EACrB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI;IAChE;;;OAGG;IACH,GAAG,EAAE;QACH;;;;WAIG;QACH,UAAU,CAAC,OAAO,EAAE;YAClB,OAAO,EAAE,OAAO,CAAC;SAClB,GAAG,OAAO,CAAC;YAAE,IAAI,EAAE,IAAI,CAAC;YAAC,OAAO,EAAE,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC,CAAC;KACtD,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,2BAA2B,CAC1C,IAAI,GAAG,OAAO,EACd,OAAO,GAAG,OAAO;IAEjB;;OAEG;IACH,IAAI,EAAE,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtC;;OAEG;IACH,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B,CAC9C,IAAI,GAAG,OAAO,EACd,OAAO,GAAG,OAAO;IAEjB;;OAEG;IACH,IAAI,EAAE,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACxE;;OAEG;IACH,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,CAC5B,IAAI,GAAG,OAAO,EACd,OAAO,GAAG,OAAO,IACf,eAAe,CACjB,OAAO,EACP,uBAAuB,CAAC,IAAI,CAAC,EAC7B,IAAI,CACF,uBAAuB,CAAC,IAAI,EAAE,OAAO,CAAC,EACtC,MAAM,uBAAuB,CAAC,IAAI,EAAE,OAAO,CAAC,CAC7C,CACF,CAAC;AAMF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,EACtE,IAAI,EACJ,eAAe,EAAE,qBAAqB,GACvC,EAAE,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CA6HtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,EAC1E,IAAI,GACL,EAAE,+BAA+B,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,kBAAkB,CACpE,IAAI,EACJ,OAAO,CACR,CAiBA"}

package/dist/index.js

@@ -1,9 +1,7 @@
 /**
  * @beignet/provider-auth-better-auth
  *
- * Better Auth provider that extends ports with authentication capabilities.
- * This provider wraps an already-configured Better Auth server instance
- * and exposes the shared Beignet AuthPort on ctx.ports.auth.
+ * Better Auth adapters for Beignet's shared authentication port.
  *
  * The provider does NOT own:
  * - Database schema
@@ -15,57 +13,16 @@
  *
  * @example
  * ```ts
- * // 1. Configure Better Auth in your app
+ * // Configure Better Auth in your app.
  * import { betterAuth } from "better-auth";
+ * import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
  * import { db } from "./db";
  *
  * export const auth = betterAuth({
  *   database: db,
- *   // ...other Better Auth config
- * });
- *
- * // Own this shape in your app instead of exporting provider-inferred types.
- * export type AuthUser = {
- *   id: string;
- *   name?: string | null;
- *   email?: string | null;
- *   image?: string | null;
- * };
- *
- * // 2. Define your ports type
- * import type { AuthPort } from "@beignet/core/ports";
- *
- * export type AppPorts = {
- *   auth: AuthPort<AuthUser>;
- *   // ...other ports
- * };
- *
- * // 3. Wire the provider into Beignet
- * import { createNextServer } from "@beignet/next";
- * import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
- *
- * const server = await createNextServer({
- *   ports: basePorts,
- *   providers: [
- *     createBetterAuthProvider(auth),
- *     // ...other providers
- *   ],
- * });
- *
- * // 4. Use the auth port through route-scoped auth hooks
- * import { createAuthHooks } from "@beignet/core/server";
- *
- * const auth = createAuthHooks<AppContext>()({
- *   resolve: ({ ctx }) => {
- *     return ctx.auth ? { user: ctx.auth.user } : null;
- *   },
  * });
  *
- * const server = await createNextServer({
- *   ports: basePorts,
- *   providers: [createBetterAuthProvider(auth)],
- *   context: async ({ ports }) => ({ ports }),
- * });
+ * export const authProvider = createBetterAuthProvider({ auth });
  * ```
  */
 import { AuthUnauthorizedError, } from "@beignet/core/ports";
@@ -74,148 +31,152 @@ function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 /**
- * Create a Beignet provider for Better Auth.
+ * Create a Beignet auth port backed by an existing Better Auth server.
  *
- * This factory accepts an already-configured Better Auth server instance
- * and returns a provider that can be registered with Beignet.
- *
- * The provider extends ports.auth with an AuthPort that wraps the
- * Better Auth instance with a simple, stable API.
- *
- * @param auth - A Better Auth server instance configured in the application
- * @returns A Beignet provider that extends ports.auth
+ * Use this for custom app wiring. The adapter does not own the Better Auth
+ * instance or add lifecycle hooks.
+ */
+export function createBetterAuthPort({ auth, instrumentation: instrumentationTarget, }) {
+    const instrumentation = createProviderInstrumentation(instrumentationTarget, {
+        providerName: "auth-better-auth",
+        watcher: "auth",
+    });
+    async function resolveSession(req) {
+        const session = await auth.api.getSession({
+            headers: req.headers,
+        });
+        if (!session) {
+            return null;
+        }
+        return {
+            user: session.user,
+            session: session.session,
+        };
+    }
+    function recordAuthEvent(event) {
+        instrumentation.custom({
+            name: `auth.${event.operation}`,
+            label: `Auth ${event.operation}`,
+            summary: event.summary,
+            details: {
+                operation: event.operation,
+                authenticated: event.authenticated,
+                durationMs: event.durationMs,
+                ...(event.error ? { error: event.error } : {}),
+            },
+        });
+    }
+    return {
+        async getSession(req) {
+            const startedAt = Date.now();
+            try {
+                const session = await resolveSession(req);
+                recordAuthEvent({
+                    operation: "getSession",
+                    authenticated: session != null,
+                    summary: session ? "Session found" : "No session",
+                    durationMs: Date.now() - startedAt,
+                });
+                return session;
+            }
+            catch (error) {
+                recordAuthEvent({
+                    operation: "getSession.failed",
+                    authenticated: false,
+                    summary: "Session lookup failed",
+                    durationMs: Date.now() - startedAt,
+                    error: errorMessage(error),
+                });
+                throw error;
+            }
+        },
+        async getUser(req) {
+            const startedAt = Date.now();
+            try {
+                const session = await resolveSession(req);
+                recordAuthEvent({
+                    operation: "getUser",
+                    authenticated: session != null,
+                    summary: session ? "User found" : "No user",
+                    durationMs: Date.now() - startedAt,
+                });
+                return session?.user ?? null;
+            }
+            catch (error) {
+                recordAuthEvent({
+                    operation: "getUser.failed",
+                    authenticated: false,
+                    summary: "User lookup failed",
+                    durationMs: Date.now() - startedAt,
+                    error: errorMessage(error),
+                });
+                throw error;
+            }
+        },
+        async requireUser(req) {
+            const startedAt = Date.now();
+            try {
+                const session = await resolveSession(req);
+                if (!session) {
+                    recordAuthEvent({
+                        operation: "requireUser",
+                        authenticated: false,
+                        summary: "Unauthorized",
+                        durationMs: Date.now() - startedAt,
+                    });
+                    throw new AuthUnauthorizedError();
+                }
+                recordAuthEvent({
+                    operation: "requireUser",
+                    authenticated: true,
+                    summary: "Authorized",
+                    durationMs: Date.now() - startedAt,
+                });
+                return session.user;
+            }
+            catch (error) {
+                if (error instanceof AuthUnauthorizedError) {
+                    throw error;
+                }
+                recordAuthEvent({
+                    operation: "requireUser.failed",
+                    authenticated: false,
+                    summary: "Required user lookup failed",
+                    durationMs: Date.now() - startedAt,
+                    error: errorMessage(error),
+                });
+                throw error;
+            }
+        },
+    };
+}
+/**
+ * Create a Beignet provider for an existing Better Auth server.
  *
  * @example
  * ```ts
  * import { betterAuth } from "better-auth";
  * import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
- * import { createNextServer } from "@beignet/next";
+ * import { db } from "./db";
  *
  * const auth = betterAuth({ database: db });
- *
- * const server = await createNextServer({
- *   ports: basePorts,
- *   providers: [createBetterAuthProvider(auth)],
- * });
+ * const provider = createBetterAuthProvider({ auth });
  * ```
  */
-export function createBetterAuthProvider(auth) {
+export function createBetterAuthProvider({ auth, }) {
     return createProvider({
         name: "auth-better-auth",
+        metadata: {
+            packageName: "@beignet/provider-auth-better-auth",
+            ports: ["auth"],
+            watchers: ["auth"],
+        },
         async setup({ ports }) {
-            const instrumentation = createProviderInstrumentation(ports, {
-                providerName: "auth-better-auth",
-                watcher: "auth",
-            });
-            async function resolveSession(req) {
-                const session = await auth.api.getSession({
-                    headers: req.headers,
-                });
-                if (!session) {
-                    return null;
-                }
-                return {
-                    user: session.user,
-                    session: session.session,
-                };
-            }
-            function recordAuthEvent(event) {
-                instrumentation.custom({
-                    name: `auth.${event.operation}`,
-                    label: `Auth ${event.operation}`,
-                    summary: event.summary,
-                    details: {
-                        operation: event.operation,
-                        authenticated: event.authenticated,
-                        durationMs: event.durationMs,
-                        ...(event.error ? { error: event.error } : {}),
-                    },
-                });
-            }
-            const authPort = {
-                async getSession(req) {
-                    const startedAt = Date.now();
-                    try {
-                        const session = await resolveSession(req);
-                        recordAuthEvent({
-                            operation: "getSession",
-                            authenticated: session != null,
-                            summary: session ? "Session found" : "No session",
-                            durationMs: Date.now() - startedAt,
-                        });
-                        return session;
-                    }
-                    catch (error) {
-                        recordAuthEvent({
-                            operation: "getSession.failed",
-                            authenticated: false,
-                            summary: "Session lookup failed",
-                            durationMs: Date.now() - startedAt,
-                            error: errorMessage(error),
-                        });
-                        throw error;
-                    }
-                },
-                async getUser(req) {
-                    const startedAt = Date.now();
-                    try {
-                        const session = await resolveSession(req);
-                        recordAuthEvent({
-                            operation: "getUser",
-                            authenticated: session != null,
-                            summary: session ? "User found" : "No user",
-                            durationMs: Date.now() - startedAt,
-                        });
-                        return session?.user ?? null;
-                    }
-                    catch (error) {
-                        recordAuthEvent({
-                            operation: "getUser.failed",
-                            authenticated: false,
-                            summary: "User lookup failed",
-                            durationMs: Date.now() - startedAt,
-                            error: errorMessage(error),
-                        });
-                        throw error;
-                    }
-                },
-                async requireUser(req) {
-                    const startedAt = Date.now();
-                    try {
-                        const session = await resolveSession(req);
-                        if (!session) {
-                            recordAuthEvent({
-                                operation: "requireUser",
-                                authenticated: false,
-                                summary: "Unauthorized",
-                                durationMs: Date.now() - startedAt,
-                            });
-                            throw new AuthUnauthorizedError();
-                        }
-                        recordAuthEvent({
-                            operation: "requireUser",
-                            authenticated: true,
-                            summary: "Authorized",
-                            durationMs: Date.now() - startedAt,
-                        });
-                        return session.user;
-                    }
-                    catch (error) {
-                        if (error instanceof AuthUnauthorizedError) {
-                            throw error;
-                        }
-                        recordAuthEvent({
-                            operation: "requireUser.failed",
-                            authenticated: false,
-                            summary: "Required user lookup failed",
-                            durationMs: Date.now() - startedAt,
-                            error: errorMessage(error),
-                        });
-                        throw error;
-                    }
+            return {
+                ports: {
+                    auth: createBetterAuthPort({ auth, instrumentation: ports }),
                 },
             };
-            return { ports: { auth: authPort } };
         },
     });
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/provider-auth-better-auth",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "type": "module",
   "description": "Better Auth provider for Beignet - adds auth port for authentication and session management",
   "main": "./dist/index.js",
@@ -86,7 +86,8 @@
       "registration": {
         "required": true,
         "tokens": [
-          "createBetterAuthProvider"
+          "createBetterAuthProvider",
+          "createBetterAuthPort"
         ]
       }
     }

package/skills/auth-provider/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Wire Beignet Better Auth integration with @beignet/provider-auth-better-auth: app-owned Better Auth config, createBetterAuthProvider and createBetterAuthPort wiring, auth routes, AuthPort typing, server context, createAuthHooks, requireUser helpers, policies, devtools auth instrumentation, tests, and doctor drift. Use when adding, fixing, or reviewing Better Auth setup in a Beignet app."
 ---
 
 # Beignet Better Auth Provider
@@ -35,11 +35,39 @@ Create Better Auth in an app-local module, then register the provider in
 import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
 import { auth } from "@/lib/better-auth";
 
-export const providers = [createBetterAuthProvider(auth)] as const;
+export const providers = [createBetterAuthProvider({ auth })] as const;
 ```
 
-Add `auth` to `definePorts(...)` as a deferred port because the provider
-contributes it at startup.
+For custom provider setup, adapt the same caller-owned instance inside an
+app-local provider:
+
+```ts
+// server/providers.ts
+import { createProvider } from "@beignet/core/providers";
+import { createBetterAuthPort } from "@beignet/provider-auth-better-auth";
+import { auth } from "@/lib/better-auth";
+
+export const appAuthProvider = createProvider({
+  name: "app-auth",
+  setup({ ports }) {
+    return {
+      ports: {
+        auth: createBetterAuthPort({ auth, instrumentation: ports }),
+      },
+    };
+  },
+});
+
+export const providers = [appAuthProvider] as const;
+```
+
+Keep `appAuthProvider` in `server/providers.ts` and register it in that file's
+exported provider list. Provider audit recognizes the direct-adapter token, and
+`auth` remains deferred because the app-local provider contributes it during
+startup. Neither factory owns or closes `auth`.
+
+Add `auth` to `definePorts(...)` as a deferred port when either the convenience
+provider or the app-local provider contributes it at startup.
 
 ```ts
 export const initialPorts = definePorts<AppPorts>()({

package/src/index.ts

@@ -1,9 +1,7 @@
 /**
  * @beignet/provider-auth-better-auth
  *
- * Better Auth provider that extends ports with authentication capabilities.
- * This provider wraps an already-configured Better Auth server instance
- * and exposes the shared Beignet AuthPort on ctx.ports.auth.
+ * Better Auth adapters for Beignet's shared authentication port.
  *
  * The provider does NOT own:
  * - Database schema
@@ -15,57 +13,16 @@
  *
  * @example
  * ```ts
- * // 1. Configure Better Auth in your app
+ * // Configure Better Auth in your app.
  * import { betterAuth } from "better-auth";
+ * import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
  * import { db } from "./db";
  *
  * export const auth = betterAuth({
  *   database: db,
- *   // ...other Better Auth config
- * });
- *
- * // Own this shape in your app instead of exporting provider-inferred types.
- * export type AuthUser = {
- *   id: string;
- *   name?: string | null;
- *   email?: string | null;
- *   image?: string | null;
- * };
- *
- * // 2. Define your ports type
- * import type { AuthPort } from "@beignet/core/ports";
- *
- * export type AppPorts = {
- *   auth: AuthPort<AuthUser>;
- *   // ...other ports
- * };
- *
- * // 3. Wire the provider into Beignet
- * import { createNextServer } from "@beignet/next";
- * import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
- *
- * const server = await createNextServer({
- *   ports: basePorts,
- *   providers: [
- *     createBetterAuthProvider(auth),
- *     // ...other providers
- *   ],
- * });
- *
- * // 4. Use the auth port through route-scoped auth hooks
- * import { createAuthHooks } from "@beignet/core/server";
- *
- * const auth = createAuthHooks<AppContext>()({
- *   resolve: ({ ctx }) => {
- *     return ctx.auth ? { user: ctx.auth.user } : null;
- *   },
  * });
  *
- * const server = await createNextServer({
- *   ports: basePorts,
- *   providers: [createBetterAuthProvider(auth)],
- *   context: async ({ ports }) => ({ ports }),
- * });
+ * export const authProvider = createBetterAuthProvider({ auth });
  * ```
  */
 
@@ -75,8 +32,11 @@ import {
   AuthUnauthorizedError,
 } from "@beignet/core/ports";
 import {
+  type AnyProviderConfigSchema,
   createProvider,
   createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+  type ServiceProvider,
 } from "@beignet/core/providers";
 
 /**
@@ -103,169 +63,234 @@ export type BetterAuthServer<User = unknown, Session = unknown> = {
   };
 };
 
+/**
+ * Options for adapting an existing Better Auth server to Beignet's auth port.
+ */
+export interface CreateBetterAuthPortOptions<
+  User = unknown,
+  Session = unknown,
+> {
+  /**
+   * Better Auth server instance configured and owned by the application.
+   */
+  auth: BetterAuthServer<User, Session>;
+  /**
+   * Optional provider instrumentation target.
+   */
+  instrumentation?: ProviderInstrumentationTarget;
+}
+
+/**
+ * Options for installing an existing Better Auth server as a Beignet provider.
+ */
+export interface CreateBetterAuthProviderOptions<
+  User = unknown,
+  Session = unknown,
+> {
+  /**
+   * Better Auth server instance configured and owned by the application.
+   */
+  auth: BetterAuthServer<User, Session>;
+}
+
+/**
+ * Ports contributed by `createBetterAuthProvider`.
+ */
+export interface BetterAuthProviderPorts<User = unknown, Session = unknown> {
+  /**
+   * Beignet auth port backed by Better Auth.
+   */
+  auth: AuthPort<User, Session>;
+}
+
+/**
+ * Better Auth lifecycle provider with stable contributed-port typing.
+ */
+export type BetterAuthProvider<
+  User = unknown,
+  Session = unknown,
+> = ServiceProvider<
+  unknown,
+  AnyProviderConfigSchema<void>,
+  Pick<
+    BetterAuthProviderPorts<User, Session>,
+    keyof BetterAuthProviderPorts<User, Session>
+  >
+>;
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
 /**
- * Create a Beignet provider for Better Auth.
- *
- * This factory accepts an already-configured Better Auth server instance
- * and returns a provider that can be registered with Beignet.
- *
- * The provider extends ports.auth with an AuthPort that wraps the
- * Better Auth instance with a simple, stable API.
- *
- * @param auth - A Better Auth server instance configured in the application
- * @returns A Beignet provider that extends ports.auth
- *
- * @example
- * ```ts
- * import { betterAuth } from "better-auth";
- * import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
- * import { createNextServer } from "@beignet/next";
+ * Create a Beignet auth port backed by an existing Better Auth server.
  *
- * const auth = betterAuth({ database: db });
- *
- * const server = await createNextServer({
- *   ports: basePorts,
- *   providers: [createBetterAuthProvider(auth)],
- * });
- * ```
+ * Use this for custom app wiring. The adapter does not own the Better Auth
+ * instance or add lifecycle hooks.
  */
-export function createBetterAuthProvider<User = unknown, Session = unknown>(
-  auth: BetterAuthServer<User, Session>,
-) {
-  return createProvider({
-    name: "auth-better-auth",
+export function createBetterAuthPort<User = unknown, Session = unknown>({
+  auth,
+  instrumentation: instrumentationTarget,
+}: CreateBetterAuthPortOptions<User, Session>): AuthPort<User, Session> {
+  const instrumentation = createProviderInstrumentation(instrumentationTarget, {
+    providerName: "auth-better-auth",
+    watcher: "auth",
+  });
 
-    async setup({ ports }) {
-      const instrumentation = createProviderInstrumentation(ports, {
-        providerName: "auth-better-auth",
-        watcher: "auth",
-      });
+  async function resolveSession(req: AuthRequestLike) {
+    const session = await auth.api.getSession({
+      headers: req.headers,
+    });
+    if (!session) {
+      return null;
+    }
+
+    return {
+      user: session.user,
+      session: session.session,
+    };
+  }
 
-      async function resolveSession(req: AuthRequestLike) {
-        const session = await auth.api.getSession({
-          headers: req.headers,
+  function recordAuthEvent(event: {
+    operation: string;
+    authenticated: boolean;
+    summary: string;
+    durationMs: number;
+    error?: string;
+  }) {
+    instrumentation.custom({
+      name: `auth.${event.operation}`,
+      label: `Auth ${event.operation}`,
+      summary: event.summary,
+      details: {
+        operation: event.operation,
+        authenticated: event.authenticated,
+        durationMs: event.durationMs,
+        ...(event.error ? { error: event.error } : {}),
+      },
+    });
+  }
+
+  return {
+    async getSession(req) {
+      const startedAt = Date.now();
+      try {
+        const session = await resolveSession(req);
+        recordAuthEvent({
+          operation: "getSession",
+          authenticated: session != null,
+          summary: session ? "Session found" : "No session",
+          durationMs: Date.now() - startedAt,
         });
-        if (!session) {
-          return null;
-        }
 
-        return {
-          user: session.user,
-          session: session.session,
-        };
+        return session;
+      } catch (error) {
+        recordAuthEvent({
+          operation: "getSession.failed",
+          authenticated: false,
+          summary: "Session lookup failed",
+          durationMs: Date.now() - startedAt,
+          error: errorMessage(error),
+        });
+        throw error;
       }
+    },
 
-      function recordAuthEvent(event: {
-        operation: string;
-        authenticated: boolean;
-        summary: string;
-        durationMs: number;
-        error?: string;
-      }) {
-        instrumentation.custom({
-          name: `auth.${event.operation}`,
-          label: `Auth ${event.operation}`,
-          summary: event.summary,
-          details: {
-            operation: event.operation,
-            authenticated: event.authenticated,
-            durationMs: event.durationMs,
-            ...(event.error ? { error: event.error } : {}),
-          },
+    async getUser(req) {
+      const startedAt = Date.now();
+      try {
+        const session = await resolveSession(req);
+        recordAuthEvent({
+          operation: "getUser",
+          authenticated: session != null,
+          summary: session ? "User found" : "No user",
+          durationMs: Date.now() - startedAt,
         });
+        return session?.user ?? null;
+      } catch (error) {
+        recordAuthEvent({
+          operation: "getUser.failed",
+          authenticated: false,
+          summary: "User lookup failed",
+          durationMs: Date.now() - startedAt,
+          error: errorMessage(error),
+        });
+        throw error;
       }
+    },
 
-      const authPort: AuthPort<User, Session> = {
-        async getSession(req) {
-          const startedAt = Date.now();
-          try {
-            const session = await resolveSession(req);
-            recordAuthEvent({
-              operation: "getSession",
-              authenticated: session != null,
-              summary: session ? "Session found" : "No session",
-              durationMs: Date.now() - startedAt,
-            });
-
-            return session;
-          } catch (error) {
-            recordAuthEvent({
-              operation: "getSession.failed",
-              authenticated: false,
-              summary: "Session lookup failed",
-              durationMs: Date.now() - startedAt,
-              error: errorMessage(error),
-            });
-            throw error;
-          }
-        },
+    async requireUser(req) {
+      const startedAt = Date.now();
+      try {
+        const session = await resolveSession(req);
+        if (!session) {
+          recordAuthEvent({
+            operation: "requireUser",
+            authenticated: false,
+            summary: "Unauthorized",
+            durationMs: Date.now() - startedAt,
+          });
+          throw new AuthUnauthorizedError();
+        }
 
-        async getUser(req) {
-          const startedAt = Date.now();
-          try {
-            const session = await resolveSession(req);
-            recordAuthEvent({
-              operation: "getUser",
-              authenticated: session != null,
-              summary: session ? "User found" : "No user",
-              durationMs: Date.now() - startedAt,
-            });
-            return session?.user ?? null;
-          } catch (error) {
-            recordAuthEvent({
-              operation: "getUser.failed",
-              authenticated: false,
-              summary: "User lookup failed",
-              durationMs: Date.now() - startedAt,
-              error: errorMessage(error),
-            });
-            throw error;
-          }
-        },
+        recordAuthEvent({
+          operation: "requireUser",
+          authenticated: true,
+          summary: "Authorized",
+          durationMs: Date.now() - startedAt,
+        });
+        return session.user;
+      } catch (error) {
+        if (error instanceof AuthUnauthorizedError) {
+          throw error;
+        }
 
-        async requireUser(req) {
-          const startedAt = Date.now();
-          try {
-            const session = await resolveSession(req);
-            if (!session) {
-              recordAuthEvent({
-                operation: "requireUser",
-                authenticated: false,
-                summary: "Unauthorized",
-                durationMs: Date.now() - startedAt,
-              });
-              throw new AuthUnauthorizedError();
-            }
+        recordAuthEvent({
+          operation: "requireUser.failed",
+          authenticated: false,
+          summary: "Required user lookup failed",
+          durationMs: Date.now() - startedAt,
+          error: errorMessage(error),
+        });
+        throw error;
+      }
+    },
+  };
+}
 
-            recordAuthEvent({
-              operation: "requireUser",
-              authenticated: true,
-              summary: "Authorized",
-              durationMs: Date.now() - startedAt,
-            });
-            return session.user;
-          } catch (error) {
-            if (error instanceof AuthUnauthorizedError) {
-              throw error;
-            }
+/**
+ * Create a Beignet provider for an existing Better Auth server.
+ *
+ * @example
+ * ```ts
+ * import { betterAuth } from "better-auth";
+ * import { createBetterAuthProvider } from "@beignet/provider-auth-better-auth";
+ * import { db } from "./db";
+ *
+ * const auth = betterAuth({ database: db });
+ * const provider = createBetterAuthProvider({ auth });
+ * ```
+ */
+export function createBetterAuthProvider<User = unknown, Session = unknown>({
+  auth,
+}: CreateBetterAuthProviderOptions<User, Session>): BetterAuthProvider<
+  User,
+  Session
+> {
+  return createProvider({
+    name: "auth-better-auth",
+    metadata: {
+      packageName: "@beignet/provider-auth-better-auth",
+      ports: ["auth"],
+      watchers: ["auth"],
+    },
 
-            recordAuthEvent({
-              operation: "requireUser.failed",
-              authenticated: false,
-              summary: "Required user lookup failed",
-              durationMs: Date.now() - startedAt,
-              error: errorMessage(error),
-            });
-            throw error;
-          }
-        },
+    async setup({ ports }) {
+      return {
+        ports: {
+          auth: createBetterAuthPort({ auth, instrumentation: ports }),
+        } satisfies BetterAuthProviderPorts<User, Session>,
       };
-
-      return { ports: { auth: authPort } };
     },
   });
 }