import type { RuntimeContext } from "alchemy";
import { Random } from "alchemy";
import type { HttpEffect } from "alchemy/Http";
import { makeExecutionMemo } from "alchemy/Runtime/ExecutionMemo";
import { betterAuth, type Auth, type BetterAuthOptions } from "better-auth";
import * as Effect from "effect/Effect";
import * as HttpServerRequest from "effect/http/HttpServerRequest";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import * as Option from "effect/Option";
import * as Redacted from "effect/Redacted";
import { makeApiProxy, type BetterAuthApi } from "./ApiProxy.ts";
import { Database } from "./Database.ts";
import type { BetterAuthApiError } from "./Errors.ts";
import { SecondaryStorage, toPromiseStorage } from "./SecondaryStorage.ts";
/**
* Better Auth options, minus the fields alchemy owns:
*
* - `database` comes from the {@link Database} platform layer
* (`Cloudflare.D1`, `Postgres`, `Memory`, ...)
* - `secondaryStorage` comes from the optional {@link SecondaryStorage}
* layer (`Cloudflare.KV`)
* - `secret` is widened to accept `Redacted` values and Effects (resource
* outputs), and defaults to an auto-provisioned stable random secret
*
* plus alchemy extensions (`id`, `migrate`).
*/
export interface BetterAuthProps extends Omit<
BetterAuthOptions,
"database" | "secondaryStorage" | "secret"
> {
/**
* Distinguishes multiple BetterAuth instances in one namespace — suffixes
* the auto-provisioned secret resource and the migration action logical
* ids.
*
* @default "BetterAuth"
*/
readonly id?: string;
/**
* Deploy-time automatic schema migration. Runs as an internal alchemy
* Action during `alchemy deploy` (never at plan, never inside the
* deployed runtime) and re-runs only when the auth schema (plugins,
* additional fields, indexes) or the target database changes.
*
* `false` opts out. `true` on a Database layer without migration support
* (Memory, Drizzle) fails the deploy with a descriptive error.
*
* @default true when the Database layer supports migration
*/
readonly migrate?: boolean;
/**
* The Better Auth signing secret. Accepts a literal string, a `Redacted`
* value, or an Effect resolving to one (e.g. another resource's output
* accessor).
*
* @default an auto-provisioned `Alchemy.Random` secret (`${id}Secret`),
* generated once and stable across deploys
*/
readonly secret?:
| string
| Redacted.Redacted<string>
| Effect.Effect<Redacted.Redacted<string>, never, RuntimeContext>;
}
/**
* The Better Auth options type seen by `Auth<Options>` — the user's literal
* options with the alchemy extension fields stripped, so plugin/session/user
* type inference flows through untouched.
*/
export type AuthOptions<O extends BetterAuthProps> =
Omit<O, "id" | "migrate" | "secret"> extends infer T extends BetterAuthOptions
? T
: BetterAuthOptions;
/** The inferred `{ session, user }` shape for a given options type. */
export type Session<O extends BetterAuthProps> = Auth<AuthOptions<O>>["$Infer"]["Session"];
export interface BetterAuthInstance<O extends BetterAuthProps> {
/**
* The per-execution Better Auth instance (memoized on the execution
* scope). Escape hatch for anything the effectified surface doesn't
* cover (`$context`, `asResponse`/`returnHeaders` call forms, ...).
*/
readonly auth: Effect.Effect<Auth<AuthOptions<O>>, never, RuntimeContext>;
/**
* Every `auth.api.*` endpoint mirrored as an Effect with a typed
* {@link BetterAuthApiError} failure.
*/
readonly api: BetterAuthApi<Auth<AuthOptions<O>>["api"]>;
/**
* HTTP handler for the Better Auth routes — mount it under your
* `basePath` (default `/api/auth`):
*
* ```typescript
* fetch: Effect.gen(function* () {
* const request = yield* HttpServerRequest;
* if (request.url.startsWith("/api/auth")) {
* return yield* auth.fetch;
* }
* // ...
* })
* ```
*/
readonly fetch: HttpEffect<RuntimeContext>;
/**
* Look up the session for the ambient request (or explicit `Headers`).
* Resolves `null` for anonymous requests — failures are real errors, not
* missing sessions.
*/
readonly getSession: {
(): Effect.Effect<
Session<O> | null,
BetterAuthApiError,
RuntimeContext | HttpServerRequest.HttpServerRequest
>;
(headers: Headers): Effect.Effect<Session<O> | null, BetterAuthApiError, RuntimeContext>;
};
/** Type-level mirror of `auth.$Infer` (phantom — no runtime value). */
readonly Infer: Auth<AuthOptions<O>>["$Infer"];
}
/**
* Create a Better Auth instance wired to alchemy.
*
* The database comes from a {@link Database} platform layer provided on
* the surrounding Worker/Function impl effect; the signing secret defaults
* to a stable auto-provisioned random secret; schema migrations run
* automatically at deploy time.
*
* ```typescript
* Effect.gen(function* () {
* const auth = yield* BetterAuth({
* basePath: "/api/auth",
* emailAndPassword: { enabled: true },
* });
* return { fetch: ... };
* }).pipe(Effect.provide(CloudflareD1(Db)))
* ```
*/
export const BetterAuth = <const O extends BetterAuthProps>(
options: O,
): Effect.Effect<BetterAuthInstance<O>, never, Database> =>
Effect.gen(function* () {
const { id = "BetterAuth", migrate, secret, ...userOptions } = options as BetterAuthProps;
const authOptions = userOptions as BetterAuthOptions;
const db = yield* Database;
const secondary = yield* Effect.serviceOption(SecondaryStorage);
// Resolve the signing secret to an Effect usable at runtime. The
// default is a Random resource whose Output accessor binds the value
// into the host environment at deploy and reads it back at runtime.
let secretAccessor: Effect.Effect<Redacted.Redacted<string>>;
if (secret === undefined) {
const resource = yield* Random(`${id}Secret`);
secretAccessor = yield* resource.text;
} else if (typeof secret === "string") {
secretAccessor = Effect.succeed(Redacted.make(secret));
} else if (Effect.isEffect(secret)) {
// oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- RuntimeContext is satisfied by the host at runtime
secretAccessor = secret as Effect.Effect<Redacted.Redacted<string>>;
} else {
secretAccessor = Effect.succeed(secret);
}
// Deploy-time migration registration. The whole block — including the
// Migrate module with its better-auth/db + kysely imports — is
// unreachable at runtime and dead-code-eliminated from bundles.
if (!globalThis.__ALCHEMY_RUNTIME__) {
const { registerMigration } = yield* Effect.promise(() => import("./Migrate.ts"));
yield* registerMigration({ id, options: authOptions, db, migrate });
}
// One Better Auth instance per execution (Worker event, DO call,
// Lambda invoke): the database input may hold sockets (pg/mysql
// pools), which are IoContext-pinned on workerd — they are acquired
// on the execution scope and released when the event settles.
const makeAuth = yield* makeExecutionMemo(
Effect.gen(function* () {
const database = yield* db.runtime;
const secretValue = Redacted.value(yield* secretAccessor);
// Background tasks (better-auth's internal fire-and-forget work)
// are awaited by a finalizer on the execution scope — the bridges
// register it with `ctx.waitUntil` on workerd and settle it
// inline on Lambda.
const pending: Promise<unknown>[] = [];
yield* Effect.addFinalizer(() => Effect.promise(() => Promise.allSettled(pending)));
const context = yield* Effect.context<RuntimeContext>();
const runPromise = <A, E>(effect: Effect.Effect<A, E, RuntimeContext>): Promise<A> =>
Effect.runPromiseWith(context)(effect);
return betterAuth({
...authOptions,
database,
secret: secretValue,
...(Option.isSome(secondary)
? {
secondaryStorage: toPromiseStorage(secondary.value, runPromise),
}
: {}),
advanced: {
...authOptions.advanced,
backgroundTasks: authOptions.advanced?.backgroundTasks ?? {
handler: (promise) => {
pending.push(promise);
},
},
},
}) as unknown as Auth<AuthOptions<O>>;
}),
);
const api = makeApiProxy<Auth<AuthOptions<O>>>(makeAuth);
const fetch: HttpEffect<RuntimeContext> = Effect.gen(function* () {
const request = yield* HttpServerRequest.HttpServerRequest;
const webRequest = yield* HttpServerRequest.toWeb(request).pipe(Effect.orDie);
const auth = yield* makeAuth;
// `auth.handler` never rejects for API errors — they come back as
// error Responses, exactly what a pass-through route wants.
const response = yield* Effect.promise(() => auth.handler(webRequest));
return HttpServerResponse.fromWeb(response);
});
const apiAny = api as Record<
string,
(input: unknown) => Effect.Effect<unknown, BetterAuthApiError, RuntimeContext>
>;
const getSession = ((headers?: Headers) =>
headers === undefined
? Effect.gen(function* () {
const request = yield* HttpServerRequest.HttpServerRequest;
const webRequest = yield* HttpServerRequest.toWeb(request).pipe(Effect.orDie);
return yield* apiAny.getSession!({ headers: webRequest.headers });
})
: apiAny.getSession!({
headers,
})) as BetterAuthInstance<O>["getSession"];
return {
auth: makeAuth,
api,
fetch,
getSession,
Infer: undefined as unknown as BetterAuthInstance<O>["Infer"],
} satisfies BetterAuthInstance<O>;
}).pipe(
(effect) =>
// Deploy-only requirements picked up by the init effect — the Random
// provider during stack evaluation, RuntimeContext for Output binds,
// Stack for migration Action registration — are provided ambiently by
// stack evaluation at deploy and by the bridge at runtime. They are
// erased from the public type (same doctrine as `makeExecutionMemo`
// erasing `Scope`); the one requirement the CALLER owns is `Database`.
effect as unknown as Effect.Effect<BetterAuthInstance<O>, never, Database>,
);