⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
import { randomInt } from 'node:crypto';
import { createWorkspace, db } from '@repo/db';
import { and, eq, gt, isNull, sql, type SQL } from 'drizzle-orm';
import { betterAuth, type BetterAuthPlugin } from 'better-auth';
import { createAuthMiddleware, APIError } from 'better-auth/api';
import { drizzleAdapter } from 'better-auth/adapters/drizzle';
import { passkey } from '@better-auth/passkey';
import { apiKey } from '@better-auth/api-key';
import { mcp } from '@better-auth/mcp';
import {
oauthProviderAuthServerMetadata,
oauthProviderOpenIdConfigMetadata,
} from '@better-auth/oauth-provider';
import { jwt, openAPI, magicLink, username, genericOAuth } from 'better-auth/plugins';
import { createLocalJWKSet, jwtVerify } from 'jose';
import * as schema from '@repo/db/schema';
import {
getAuthSettings,
admittedPastGate,
registrationEmailAllowed,
hasPendingInvite,
hasExpiredInvite,
getGoogleConfig,
isGoogleUsable,
getOidcConfig,
isOidcUsable,
isAccountDeactivated,
} from './instance';
import { emailLocale, sendAuthEmail } from './mail';
import { readAuthExtensions } from './extensions';
import { trustedOrigins } from './origins';
export { trustedOrigins };
export { composeEmail, composeEmailDraft, emailLocale, savedLocaleOf, savedLocales } from './mail';
// Parent domain for a cross-subdomain session cookie (".example.com" from
// "app.example.com"). Returns undefined for localhost, IPs, or apex domains, where
// no cross-subdomain sharing is needed. Used so the SSR web app on one subdomain can
// read the session cookie set by the api on a sibling subdomain.
function parentDomain(origin: string | undefined): string | undefined {
if (!origin) return undefined;
let host: string;
try {
host = new URL(origin).hostname;
} catch {
return undefined;
}
if (host === 'localhost' || /^[\d.]+$/.test(host)) return undefined;
const labels = host.split('.');
if (labels.length < 3) return undefined;
return '.' + labels.slice(1).join('.');
}
function safeUrl(value: string | undefined): URL | undefined {
if (!value) return undefined;
try {
return new URL(value);
} catch {
return undefined;
}
}
// parentDomain() would widen the cookie to sibling subdomains even when web and api
// share a host, where a host-only cookie is enough.
const sameHost = safeUrl(trustedOrigins[0])?.hostname === safeUrl(process.env.API_URL)?.hostname;
// COOKIE_DOMAIN wins (multi-label TLDs, deep subdomains); otherwise host-only when web
// and api share a host, else the parent domain of the frontend.
const cookieDomain =
process.env.COOKIE_DOMAIN || (sameHost ? undefined : parentDomain(trustedOrigins[0]));
// WebAuthn relying-party id: the frontend domain the passkey is bound to (no port,
// no scheme). The WebAuthn ceremony runs in the frontend JS, so the expected origin
// is the frontend origin(s) — the same trustedOrigins list. On localhost this all
// works over http (localhost is a secure context). In prod set PASSKEY_RP_ID to the
// public frontend hostname.
const passkeyRpID = process.env.PASSKEY_RP_ID ?? new URL(trustedOrigins[0]).hostname;
// The client IP keys the rate limit. Unset, better-auth reads X-Forwarded-For and takes
// it only when it holds one address; TRUSTED_PROXIES lets it read a chain.
const clientIpHeader = process.env.CLIENT_IP_HEADER;
const trustedProxies = process.env.TRUSTED_PROXIES?.split(',')
.map((entry) => entry.trim())
.filter(Boolean);
// Public URL of the backend, with the path a subpath proxy adds; the links in auth
// emails and the OAuth redirect URIs are built from it.
const apiPublicUrl = (process.env.API_URL ?? '').replace(/\/+$/, '');
if (!apiPublicUrl) {
throw new Error('API_URL is not set: public URL of the backend.');
}
const apiUrl = safeUrl(apiPublicUrl);
if (!apiUrl) {
throw new Error(`API_URL is not a valid URL: ${apiPublicUrl}`);
}
// A baseURL with a path replaces better-auth's /api/auth basePath and the api's fixed
// mount stops matching, so it only gets the origin.
const baseURL = apiUrl.origin;
const apiHasPath = apiUrl.pathname !== '/';
// Over HTTPS with a host-only cookie the session cookies carry the __Host- prefix:
// the browser then refuses a cookie of that name planted by a sibling subdomain (with
// a Domain, or a narrower Path), which __Secure- does not prevent. better-auth only
// writes __Secure-, so its automatic prefix is turned off and both prefixes are written
// into the names here.
const hostPrefixedCookies = baseURL.startsWith('https://') && !cookieDomain;
const SESSION_COOKIES = ['session_token', 'session_data', 'account_data', 'dont_remember'];
// better-auth builds the links it hands to the mailers from the origin-only baseURL;
// this puts the path back.
function withPublicOrigin(url: string): string {
return url.startsWith(baseURL) ? apiPublicUrl + url.slice(baseURL.length) : url;
}
// The MCP authorization server. Its issuer is the public URL of the api, so the access
// tokens, the authorization responses and the discovery documents name the URL a
// client reaches, behind a path prefix too.
const MCP_ISSUER = apiPublicUrl;
const MCP_RESOURCE = `${apiPublicUrl}/mcp`;
// better-auth accepts a plain-HTTP MCP resource only on a loopback host. Any other
// instance without HTTPS serves MCP to personal API keys only.
const mcpOAuth =
apiUrl.protocol === 'https:' ||
apiUrl.hostname === 'localhost' ||
apiUrl.hostname === '[::1]' ||
apiUrl.hostname.startsWith('127.');
// The discovery documents list endpoints built from the origin-only baseURL; behind a
// path prefix they would land on whatever serves the root of the host.
async function withPublicDiscoveryUrls(response: Response): Promise<Response> {
if (!apiHasPath || !response.ok) return response;
const authBase = `${baseURL}/api/auth`;
const toPublic = (value: unknown) =>
typeof value === 'string' && value.startsWith(authBase) ? withPublicOrigin(value) : value;
const metadata = (await response.json()) as Record<string, unknown>;
for (const [key, value] of Object.entries(metadata)) {
metadata[key] = Array.isArray(value) ? value.map(toPublic) : toPublic(value);
}
return Response.json(metadata, { status: response.status, headers: response.headers });
}
const notFound = () => new Response(null, { status: 404 });
export async function oauthAuthorizationServerMetadata(request: Request): Promise<Response> {
if (!mcpOAuth) return notFound();
return withPublicDiscoveryUrls(await oauthProviderAuthServerMetadata(auth)(request));
}
export async function openIdConfiguration(request: Request): Promise<Response> {
if (!mcpOAuth) return notFound();
return withPublicDiscoveryUrls(await oauthProviderOpenIdConfigMetadata(auth)(request));
}
// The mcp plugin serves this document itself, for a request under its own path.
export async function oauthProtectedResourceMetadata(): Promise<Response> {
if (!mcpOAuth) return notFound();
return auth.handler(new Request(`${baseURL}/.well-known/oauth-protected-resource`));
}
// The answer to an MCP request without a usable credential. The challenge names the
// resource metadata, which is where an MCP client starts the OAuth flow.
export function mcpUnauthorized(): Response {
const headers = new Headers({ 'Content-Type': 'application/json' });
if (mcpOAuth) {
headers.set(
'WWW-Authenticate',
`Bearer resource_metadata="${apiPublicUrl}/.well-known/oauth-protected-resource/mcp"`,
);
}
return new Response(
JSON.stringify({ jsonrpc: '2.0', error: { code: -32000, message: 'Unauthorized' }, id: null }),
{ status: 401, headers },
);
}
// The account an MCP access token was issued to, or null when the token is not valid
// or the account is deactivated. The tokens are JWTs signed with this instance's keys
// and are checked against them in-process: requireMcpAuth fetches the key set over
// HTTP from the public URL, which a container cannot always reach. A JWT stays valid
// until it expires, so the rest is read on every request, as better-auth's own
// introspection does: a token issued in a session ends with it, and so does every
// token of a deactivated account. A DPoP-bound token is valid only with its proof,
// which this check does not take.
export async function verifyMcpAccessToken(token: string): Promise<string | null> {
if (!mcpOAuth) return null;
let claims: { sub?: string; sid?: unknown; cnf?: unknown; client_id?: unknown };
try {
({ payload: claims } = await jwtVerify(token, createLocalJWKSet(await auth.api.getJwks()), {
issuer: MCP_ISSUER,
audience: MCP_RESOURCE,
}));
} catch {
return null;
}
if (claims.cnf || !claims.sub) return null;
const [account] = await db
.select({ active: schema.user.active })
.from(schema.user)
.where(eq(schema.user.id, claims.sub));
if (!account || isAccountDeactivated(account)) return null;
// Disconnecting the application on the account's Security page ends its tokens at once.
if (typeof claims.client_id !== 'string') return null;
if (!(await isClientConnected(claims.sub, claims.client_id))) return null;
if (typeof claims.sid === 'string') {
const [open] = await db
.select({ n: sql`1` })
.from(schema.session)
.where(and(eq(schema.session.id, claims.sid), gt(schema.session.expiresAt, new Date())));
if (!open) return null;
}
return claims.sub;
}
// Connected while the person's consent stands or a refresh token can still mint tokens,
// the same rule the Security page lists applications by.
async function isClientConnected(userId: string, clientId: string): Promise<boolean> {
const [consent] = await db
.select({ n: sql`1` })
.from(schema.oauthConsent)
.where(and(eq(schema.oauthConsent.userId, userId), eq(schema.oauthConsent.clientId, clientId)))
.limit(1);
if (consent) return true;
const [refresh] = await db
.select({ n: sql`1` })
.from(schema.oauthRefreshToken)
.where(
and(
eq(schema.oauthRefreshToken.userId, userId),
eq(schema.oauthRefreshToken.clientId, clientId),
isNull(schema.oauthRefreshToken.revoked),
gt(schema.oauthRefreshToken.expiresAt, new Date()),
),
)
.limit(1);
return Boolean(refresh);
}
// An error better-auth cannot hand back to the page that started the flow lands here.
// Its own /api/auth/error is outside a path prefix and, on the api's own host, sends a
// production browser to the api's root; /login turns ?error= into a message.
const oauthErrorURL = `${trustedOrigins[0]}/login`;
// User roles. "god" is the owner of the instance: the very first registered user
// gets it automatically; everyone after is a plain "user". The role is assigned
// server-side (input: false) so a client cannot request it at sign-up.
export const USER_ROLES = ['god', 'user'] as const;
export type UserRole = (typeof USER_ROLES)[number];
// The exact authorized redirect URI to register in the Google Cloud console;
// god mode shows it for copying.
export const GOOGLE_REDIRECT_URI = `${apiPublicUrl}/api/auth/callback/google`;
// Google OAuth credentials live in the database (god mode), not in env. The provider
// is built once at startup, but it keeps this options object by reference and reads
// clientId / clientSecret off it on every call, so refreshing the object per request
// is what lets the owner change or revoke the credentials without a restart.
// redirectURI is explicit: the one inferred from the origin-only baseURL lacks the path.
const googleOptions = { clientId: '', clientSecret: '', redirectURI: GOOGLE_REDIRECT_URI };
// Loads the stored credentials into that object and reports whether Google sign-in
// can run. A read failure disables the provider rather than failing the request with
// a stale secret.
async function refreshGoogleOptions(): Promise<boolean> {
try {
const config = await getGoogleConfig();
googleOptions.clientId = config.clientId;
googleOptions.clientSecret = config.clientSecret;
return isGoogleUsable(config);
} catch (error) {
console.error('[auth] could not read the Google credentials:', error);
return false;
}
}
// The generic OIDC provider. One per instance, so its id is a constant: it is what
// the `account` rows store.
export const OIDC_PROVIDER_ID = 'oidc';
// The redirect URI to register with the identity provider; god mode shows it for
// copying. better-auth serves the callback at /callback/oidc and the api passes this
// path on to it, so a provider registered with it keeps working.
export const OIDC_REDIRECT_URI = `${apiPublicUrl}/api/auth/oauth2/callback/${OIDC_PROVIDER_ID}`;
type PluginContext = Parameters<NonNullable<BetterAuthPlugin['init']>>[0];
type SocialProvider = PluginContext['socialProviders'][number];
// genericOAuth reads the discovery document once, when the plugin starts, and keeps
// the endpoints it found, while this provider is configured in god mode and changes
// without a restart. So better-auth holds this proxy, and every read on it goes to a
// provider genericOAuth built from the stored settings.
let oidc: { settings: string; provider: SocialProvider } | undefined;
const oidcProvider = new Proxy({ id: OIDC_PROVIDER_ID } as SocialProvider, {
get: (fallback, key) => Reflect.get(oidc?.provider ?? fallback, key),
});
// Rebuilds the provider when the stored settings changed and reports whether OIDC
// sign-in can run. A failed read or discovery disables the provider rather than
// running the request on stale settings.
async function refreshOidcProvider(): Promise<boolean> {
try {
const config = await getOidcConfig();
if (!isOidcUsable(config)) return false;
const settings = JSON.stringify(config);
if (oidc?.settings === settings) return true;
const plugin = genericOAuth({
config: [
{
providerId: OIDC_PROVIDER_ID,
clientId: config.clientId,
clientSecret: config.clientSecret,
discoveryUrl: config.discoveryUrl,
scopes: config.scopes,
pkce: config.pkce,
// redirectURI is explicit for the same reason as in googleOptions.
redirectURI: OIDC_REDIRECT_URI,
// The `account` rows hold the OIDC subject. genericOAuth reads `id` instead
// when the discovery document lists no id_token signing algorithms.
accountSubject: ({ profile }) => String(profile.sub ?? ''),
// Only the standard email_verified claim, true or "true", says the address is
// verified.
mapProfileToUser: (profile) => {
const claim: unknown = profile.email_verified;
return { emailVerified: claim === true || claim === 'true' };
},
// Signing out of the app leaves the session at the identity provider alone.
disableProviderLogout: true,
},
],
});
const built = await plugin.init({ ...pluginContext!, socialProviders: [] });
// genericOAuth skips a provider whose discovery failed, and logs why.
const provider = built?.context?.socialProviders?.[0];
if (!provider) return false;
oidc = { settings, provider };
return true;
} catch (error) {
console.error('[auth] could not load the OIDC provider:', error);
return false;
}
}
// The context genericOAuth builds a provider in; kept from startup, when better-auth
// hands it to the plugin below.
let pluginContext: PluginContext | undefined;
const instanceOidc = (): BetterAuthPlugin => ({
id: 'instance-oidc',
init: (context) => {
pluginContext = context;
return { context: { socialProviders: [oidcProvider, ...context.socialProviders] } };
},
});
// The two conditions better-auth checks before linking an address to an account that
// already has it are read from different places: `trustedProviders` per request,
// through the resolver below, and `requireLocalEmailVerified` off the options object
// at the moment of the decision. The resolver runs first, in the same request, and
// leaves the setting here for the getter to read.
let trustProviderEmails = false;
// The trusted providers for one request. The settings are read where a provider's
// sign-in comes back — an OAuth callback, or a SAML response posted to `/acs/` — only:
// the resolver runs on every request to the auth API, and a session check has no linking
// decision to make.
const PROVIDER_RETURN = /\/(callback|acs)\//;
async function resolveTrustedProviders(request?: Request): Promise<string[]> {
if (!request || !PROVIDER_RETURN.test(new URL(request.url).pathname)) return [];
trustProviderEmails = (await getAuthSettings()).trustProviderEmails;
return trustProviderEmails ? ['google', OIDC_PROVIDER_ID] : [];
}
// Whether a new account has to confirm its address before it gets a session. An
// instance setting, read in `hooks.before` on every password endpoint and served to
// better-auth through the getter on `emailAndPassword` below: sign-up reads the
// option off the options object at the moment it decides whether to open a session,
// so a getter is what lets the stored setting reach a config that is built once.
let verificationRequired = false;
// The endpoints of the email/password form, including the two the magic link uses.
// Turning password authentication off refuses all of them, so a link issued before
// the switch was flipped cannot still be redeemed. Passkey sign-in is not here: a
// passkey is only ever added to an account that already exists, so it cannot be used
// to get around single sign-on.
const PASSWORD_PATHS = new Set([
'/sign-up/email',
'/sign-in/email',
'/sign-in/username',
'/request-password-reset',
'/reset-password',
'/sign-in/magic-link',
'/magic-link/verify',
]);
const REGISTRATION_REFUSALS = {
REGISTRATION_CLOSED: 'Registration is closed on this instance',
INVITE_ONLY: 'This instance is invite-only. Ask a project owner to invite this address.',
INVITE_EXPIRED: 'The invite for this address has expired. Ask for a new one.',
EMAIL_DOMAIN_NOT_ALLOWED: 'This instance does not admit addresses at this domain',
} as const;
function refuseRegistration(code: keyof typeof REGISTRATION_REFUSALS): never {
throw new APIError('FORBIDDEN', { code, message: REGISTRATION_REFUSALS[code] });
}
// The registration gate: who may create an account. Both sign-up paths run it — the
// email form checks it up front (below), and the user create hook catches every other
// path, which is what stops a Google, OIDC or magic-link sign-up on a closed or
// invite-only instance. Telling an expired invite apart reveals that the address was
// invited, so it is said only once the address is proven (a provider or a magic link):
// the email form, open to anyone, gets the plain invite-only refusal. Each refusal
// carries a `code`, which is what the provider callback and the magic link turn into the
// ?error= they redirect with; without one the callback would fail the request instead.
async function assertRegistrationAllowed(
email: string,
{ addressProven }: { addressProven: boolean },
): Promise<void> {
const settings = await getAuthSettings();
if (settings.registration === 'closed') refuseRegistration('REGISTRATION_CLOSED');
if (!(await registrationEmailAllowed(email))) refuseRegistration('EMAIL_DOMAIN_NOT_ALLOWED');
if (settings.registration === 'invite' && !(await hasPendingInvite(email))) {
const expired = addressProven && (await hasExpiredInvite(email));
refuseRegistration(expired ? 'INVITE_EXPIRED' : 'INVITE_ONLY');
}
}
// True when an account matching the sign-in identifier exists and has not confirmed
// its address. Used to hold back sign-in while the instance requires verification. An
// unknown identifier is not "unverified" — it falls through to better-auth's own
// invalid-credentials answer, so this never reveals whether an account exists.
async function isUnverified(where: SQL): Promise<boolean> {
const rows = await db
.select({ emailVerified: schema.user.emailVerified })
.from(schema.user)
.where(where);
return rows[0] ? !rows[0].emailVerified : false;
}
// Username rules. The bounds are the plugin's own defaults, repeated here because the
// generator below has to stay inside them.
const USERNAME_MIN_LENGTH = 3;
const USERNAME_MAX_LENGTH = 30;
const SUFFIX_LENGTH = 3;
// Three digits appended to a name that is taken, or too short to stand on its own.
// Drawn from the crypto source: the digits are not a secret, but this function sits
// in the sign-up path, where a predictable generator is worth nobody's argument.
function randomSuffix(): string {
return String(100 + randomInt(900));
}
// Accounts that need no personal workspace made: they own a workspace, or are an agent's
// bot user. Kept per process, so once an account is known a request costs a lookup here
// and nothing in the database.
const settled = new Set<string>();
// The personal workspace of an account that owns none, named after the person: the
// instance owner's always, anyone else's while personal workspaces are on. Sign-up calls
// it, and apps/api on every request, so an account made before personal workspaces, by
// SCIM, or while they were off gets its own without signing in again. Nothing in the API
// creates a workspace; an edition that lets a person own more mounts a route of its own.
// An agent's bot user is no person.
// ponytail: an account with no workspace while they are off reads the setting on each
// request; cache it with the setting if that ever shows.
export async function ensurePersonalWorkspace(account: {
id: string;
role?: string | null;
}): Promise<void> {
const userId = account.id;
if (settled.has(userId)) return;
if (account.role !== 'god' && !(await getAuthSettings()).personalWorkspaces) return;
await db.transaction(async (tx) => {
// Two sign-ins at once would otherwise both find none.
const [person] = await tx
.select({ name: schema.user.name, email: schema.user.email })
.from(schema.user)
.where(eq(schema.user.id, userId))
.for('update');
if (!person) return;
const [owned] = await tx
.select({ n: sql`1` })
.from(schema.workspaceManager)
.where(
and(eq(schema.workspaceManager.userId, userId), eq(schema.workspaceManager.role, 'owner')),
)
.limit(1);
const [agent] = await tx
.select({ n: sql`1` })
.from(schema.aiAgent)
.where(eq(schema.aiAgent.userId, userId))
.limit(1);
if (owned || agent) return;
const name = (person.name.trim() || person.email.split('@')[0]!).slice(0, 60);
await createWorkspace(tx, name, userId);
});
settled.add(userId);
}
// After an account stops owning a workspace (it deleted or handed over its own), so the
// next request makes it a fresh one while personal workspaces are on.
export function forgetPersonalWorkspace(userId: string): void {
settled.delete(userId);
}
// True when an agent of some project already answers to this handle. A mention is
// resolved against members and agents at once, so the two share one namespace: a
// member cannot take a name an agent uses, and the check for the other direction
// sits where an agent is created. Agent handles are stored as typed, so the
// comparison is case-insensitive.
async function isAgentHandle(handle: string): Promise<boolean> {
const normalized = handle.trim().toLowerCase();
if (!normalized) return false;
const taken = await db.$count(
schema.aiAgent,
eq(sql`lower(${schema.aiAgent.username})`, normalized),
);
return taken > 0;
}
// Nobody is asked for a username at sign-up: it is derived from the address — the
// local part, with everything the plugin's validator rejects removed — and the owner
// changes it later in the profile. A name already in use gets a random suffix, and
// the check repeats until the name is free.
export async function generateUsername(email: string): Promise<string> {
const stem =
email
.split('@')[0]
.toLowerCase()
.replace(/[^a-z0-9_.]/g, '')
.slice(0, USERNAME_MAX_LENGTH - SUFFIX_LENGTH) || 'user';
let candidate = stem.length >= USERNAME_MIN_LENGTH ? stem : stem + randomSuffix();
for (let attempt = 0; attempt < 20; attempt += 1) {
const taken =
(await db.$count(schema.user, eq(schema.user.username, candidate))) > 0 ||
(await isAgentHandle(candidate));
if (!taken) break;
candidate = stem + randomSuffix();
}
return candidate;
}
// Personal API key lifetime. The plugin's option is typed as milliseconds but the
// handler applies it as seconds (the same unit as the `expiresIn` a client sends),
// so it is held in seconds here. The maximum is in days, as the plugin reads it.
const DAY_SEC = 24 * 60 * 60;
export const API_KEY_DEFAULT_EXPIRES_IN_SEC = 90 * DAY_SEC;
export const API_KEY_MAX_EXPIRES_IN_DAYS = 365;
// Created on first use rather than on import, so a build's extendAuth (./extensions) takes
// effect wherever a bundler puts its module, as long as it runs before the first request.
function createAuth() {
const extensions = readAuthExtensions();
return betterAuth({
baseURL,
secret: process.env.BETTER_AUTH_SECRET,
onAPIError: { errorURL: oauthErrorURL },
database: drizzleAdapter(db, {
provider: 'pg',
schema: {
user: schema.user,
session: schema.session,
account: schema.account,
verification: schema.verification,
passkey: schema.passkey,
apikey: schema.apikey,
jwks: schema.jwks,
oauthClient: schema.oauthClient,
oauthResource: schema.oauthResource,
oauthClientResource: schema.oauthClientResource,
oauthRefreshToken: schema.oauthRefreshToken,
oauthAccessToken: schema.oauthAccessToken,
oauthConsent: schema.oauthConsent,
oauthClientAssertion: schema.oauthClientAssertion,
...extensions.schema,
},
}),
emailAndPassword: {
enabled: true,
// While this is true, sign-up answers without a session and a duplicate address
// gets the same answer as a new one; sign-in of an unconfirmed account is
// refused in the hook below before better-auth's own check runs.
get requireEmailVerification() {
return verificationRequired;
},
autoSignIn: true,
// A reset is how a stolen password is dealt with, so every session opened with
// the old one ends with it. The signed-in change-password form sends
// revokeOtherSessions for the same reason.
revokeSessionsOnPasswordReset: true,
password: extensions.password,
sendResetPassword: async ({ user, url }, request) => {
await sendAuthEmail({
to: user.email,
template: 'reset',
locale: await emailLocale(user.email, request),
url: withPublicOrigin(url),
});
},
},
emailVerification: {
// The mail goes out on every sign-up; sendVerificationEmail below drops it when
// the instance does not require verification.
sendOnSignUp: true,
autoSignInAfterVerification: true,
sendVerificationEmail: async ({ user, url }, request) => {
const settings = await getAuthSettings();
if (!settings.requireEmailVerification) return;
await sendAuthEmail({
to: user.email,
template: 'verify',
locale: await emailLocale(user.email, request),
url: withPublicOrigin(url),
});
},
},
// Google sign-in. The provider is always mounted; whether it may run is decided per
// request in the hook below, the same way the magic link is handled. The factory
// runs once, at startup, and returns the shared options object described above.
socialProviders: {
google: async () => {
await refreshGoogleOptions();
return googleOptions;
},
},
// A provider address that already has an account signs into it and gains a linked
// account row, rather than being refused as a duplicate. By default that happens
// only when the provider reported the address as verified and the local account
// confirmed its own — Google always reports a verified address, an OIDC provider
// need not, and an instance with no mail provider has no confirmed accounts at
// all. The instance setting drops both conditions; after a successful link
// better-auth marks the local user confirmed too.
account: {
accountLinking: {
trustedProviders: resolveTrustedProviders,
get requireLocalEmailVerified() {
return !trustProviderEmails;
},
},
// The id_token is stored unencrypted, so this covers only the access and refresh
// tokens.
encryptOAuthTokens: true,
},
// Extra column on the user table. Not client-settable (input: false) — the role
// is decided by the create hook below.
user: {
additionalFields: {
role: {
type: 'string',
required: false,
defaultValue: 'user',
input: false,
},
// Deprovisioning flag, written only over SCIM while it acts on the whole instance.
// Nullable: read it through isAccountDeactivated, which takes only `false`.
active: {
type: 'boolean',
required: false,
defaultValue: true,
input: false,
},
// When the person last used the app by any means (the web, an API key, MCP),
// to the hour; written by the api's auth context, read by god's user list.
lastSeenAt: {
type: 'date',
required: false,
input: false,
returned: false,
},
},
},
// The registration gate and the verification check. Both read instance settings
// per request, so god mode can change them without a restart.
hooks: {
before: createAuthMiddleware(async (ctx) => {
// A key resolves to its owner's session on every endpoint here, and what such a
// session sets up outlives the key: a passkey enrolled with it still signs in
// after the key is deleted and the password reset, and a new key starts a fresh
// lifetime. A key is for the planner API; the account is managed from a signed-in
// session. A server-side call, such as the one issuing an agent's key, carries
// no request and passes.
if (ctx.request?.headers.get('x-api-key')) {
throw new APIError('FORBIDDEN', {
message: 'An API key cannot manage the account. Sign in to do this.',
});
}
// Read here so the two sign-in endpoints, which also go through the
// verification gate below, make one query instead of two.
const passwordSettings = PASSWORD_PATHS.has(ctx.path) ? await getAuthSettings() : null;
if (passwordSettings) verificationRequired = passwordSettings.requireEmailVerification;
// The api will not let the switch be turned off while no OAuth provider is
// configured, so this cannot leave an instance with no way in.
if (passwordSettings && !passwordSettings.emailPassword) {
throw new APIError('FORBIDDEN', {
code: 'PASSWORD_AUTH_DISABLED',
message: 'Password sign-in is disabled on this instance',
});
}
if (ctx.path === '/sign-up/email') {
await assertRegistrationAllowed(
(ctx.body as { email?: string } | undefined)?.email ?? '',
{
addressProven: false,
},
);
return;
}
const provider =
ctx.path === '/sign-in/social' || ctx.path === '/link-social'
? (ctx.body as { provider?: string } | undefined)?.provider
: ctx.path.startsWith('/callback/')
? ctx.path.slice('/callback/'.length)
: undefined;
// No screen links an OIDC identity to the signed-in account, and better-auth
// already attaches a sign-in to a matching confirmed address on its own.
if (ctx.path === '/link-social' && provider === OIDC_PROVIDER_ID) {
throw new APIError('FORBIDDEN', { message: 'Single sign-on cannot be linked' });
}
// Both halves of an OAuth round trip: starting it and coming back from it. This
// is where the stored settings are loaded into the provider, so a request never
// runs on a value the owner has since changed. The OIDC refusal carries a code
// because the callback turns it into the ?error= it redirects with; without one
// the callback fails the request instead.
if (provider === OIDC_PROVIDER_ID) {
if (!(await refreshOidcProvider())) {
throw new APIError('FORBIDDEN', {
code: 'OIDC_DISABLED',
message: 'Single sign-on is disabled on this instance',
});
}
return;
}
if (provider === 'google') {
if (!(await refreshGoogleOptions())) {
throw new APIError('FORBIDDEN', {
message: 'Google sign-in is disabled on this instance',
});
}
return;
}
// Both password endpoints: the sign-in screen sends the one field it has to
// /sign-in/email or /sign-in/username depending on what was typed, and the
// instance gate has to apply either way.
if (ctx.path === '/sign-in/email' || ctx.path === '/sign-in/username') {
const settings = passwordSettings ?? (await getAuthSettings());
if (!settings.requireEmailVerification) return;
const body = ctx.body as { email?: string; username?: string } | undefined;
const identifier =
ctx.path === '/sign-in/email'
? eq(schema.user.email, (body?.email ?? '').trim().toLowerCase())
: eq(schema.user.username, (body?.username ?? '').trim().toLowerCase());
if (await isUnverified(identifier)) {
// The code is better-auth's own for this refusal; the sign-in form tells it
// apart from the other 403s, such as a deactivated account, by it.
throw new APIError('FORBIDDEN', {
code: 'EMAIL_NOT_VERIFIED',
message: 'Confirm your email address before signing in',
});
}
return;
}
// The profile form changes the username here. The plugin only checks it against
// the other accounts, so the agents are checked on this side.
if (ctx.path === '/update-user') {
const handle = (ctx.body as { username?: string } | undefined)?.username;
if (handle && (await isAgentHandle(handle))) {
throw new APIError('BAD_REQUEST', {
message: 'Username is already taken. Please try another.',
});
}
return;
}
// The lifetime of a key is fixed at creation; a longer one is a new key.
if (ctx.path === '/api-key/update') {
const body = ctx.body as { expiresIn?: number | null } | undefined;
if (body && body.expiresIn !== undefined) {
throw new APIError('FORBIDDEN', {
message: 'The expiry of an API key cannot be changed. Create a new key instead.',
});
}
}
}),
},
databaseHooks: {
user: {
create: {
// Every account creation passes here, whichever method made it, so this is
// where the registration gate applies to Google. Agent bot users are written
// with a direct insert and never reach this hook.
//
// Assign the role before the row is inserted: first user ever → "god",
// everyone else → "user".
before: async (user, ctx) => {
// The email form is refused up front unless its invite is valid, so a refusal
// here comes from a provider or a magic link, which prove the address.
if (!(await admittedPastGate(user.email, ctx))) {
await assertRegistrationAllowed(user.email, { addressProven: true });
}
const isFirstUser = (await db.$count(schema.user)) === 0;
// A sign-up that carried its own username has passed the plugin's own
// check against the other accounts by now, but not the one against the
// agents; only an account without one gets a derived name.
const carried = typeof user.username === 'string' ? user.username : null;
if (carried && (await isAgentHandle(carried))) {
throw new APIError('BAD_REQUEST', {
code: 'USERNAME_IS_ALREADY_TAKEN',
message: 'Username is already taken. Please try another.',
});
}
const derived = carried ?? (await generateUsername(user.email));
return {
data: {
...user,
role: isFirstUser ? 'god' : 'user',
username: derived,
displayUsername: user.displayUsername ?? derived,
},
};
},
after: async (user) => {
await ensurePersonalWorkspace(user);
},
},
},
session: {
create: {
// Every sign-in method ends here, so one check covers password, magic link,
// passkey, Google and OIDC. Deactivation arrives over SCIM or from god mode;
// apps/api refuses the sessions that are already open.
before: async (session) => {
const [account] = await db
.select({ active: schema.user.active })
.from(schema.user)
.where(eq(schema.user.id, session.userId));
if (account && isAccountDeactivated(account)) {
throw new APIError('FORBIDDEN', {
code: 'ACCOUNT_DEACTIVATED',
message: 'This account is deactivated',
});
}
},
},
},
},
plugins: [
// WebAuthn passkeys, a second sign-in method alongside email + password. A
// passkey is added to an already signed-in account (passkey.addPasskey) and
// then used to sign in (signIn.passkey). Adds the `passkey` table.
passkey({
rpID: passkeyRpID,
rpName: process.env.PASSKEY_RP_NAME ?? "It's a Plan",
// Expected origin(s) of the WebAuthn ceremony — the frontend origins.
origin: trustedOrigins,
}),
// Personal API keys: a signed-in user creates a named key, sees its value once
// at creation, and can list (value hidden) or delete it. Adds the `apikey` table.
// enableSessionForAPIKeys makes a request carrying an `x-api-key` header resolve
// to the key owner's session, so getSession (and every planner guard built on it)
// accepts API keys without any change in apps/api. Rate limit: 100 requests per
// second per key (timeWindow is in milliseconds). The ceiling is set for the
// heaviest legitimate caller rather than a typical one: an internal AI agent runs
// on its own key and dispatches every tool call through a route, and a model that
// emits a batch of tool calls in one step turns them into a burst of requests.
apiKey({
enableSessionForAPIKeys: true,
// Brand prefix so a leaked key is identifiable by secret scanners and in logs.
// The trailing underscore separates it from the random part (itp_<64 chars>).
defaultPrefix: 'itp_',
// A key is a full-account credential, so one that was forgotten stops working
// on its own. The caller may pick a shorter or longer life up to the maximum;
// an agent's key is the exception, cleared where it is issued in apps/api.
keyExpiration: {
defaultExpiresIn: API_KEY_DEFAULT_EXPIRES_IN_SEC,
maxExpiresIn: API_KEY_MAX_EXPIRES_IN_DAYS,
},
rateLimit: {
enabled: true,
timeWindow: 1000,
maxRequests: 100,
},
}),
// Sign-in by emailed link, offered alongside the password. Whether it is
// available is an instance setting, so the plugin is always mounted and the
// sender refuses when it is off. It reuses the `verification` table — no new
// table, so `auth:generate` output is unchanged.
magicLink({
// Stored plain, an OAuth state also passes as a token (GHSA-965c-763c-88jm).
storeToken: 'hashed',
sendMagicLink: async ({ email, url }, ctx) => {
const settings = await getAuthSettings();
if (!settings.magicLink) {
throw new APIError('FORBIDDEN', {
message: 'Magic links are disabled on this instance',
});
}
await sendAuthEmail({
to: email,
template: 'magic',
locale: await emailLocale(email, ctx?.request),
url: withPublicOrigin(url),
});
},
}),
// The instance's OIDC provider, configured in god mode; see oidcProvider above.
instanceOidc(),
// Usernames: a second identifier next to the address, unique across the
// instance. Adds `username` / `display_username` to the user table and the
// /sign-in/username endpoint the sign-in screen uses when the visitor typed a
// name rather than an address. Nobody is asked for one — the create hook above
// derives it from the address, and the profile page changes it afterwards.
username({
minUsernameLength: USERNAME_MIN_LENGTH,
maxUsernameLength: USERNAME_MAX_LENGTH,
}),
// OAuth 2.1 for Streamable HTTP MCP clients, on top of the existing session. Any
// client registers itself (RFC 7591), as ChatGPT and Claude do. The access tokens
// are JWTs signed by jwt(); no screen reads a session JWT, so it does not put one
// on every session response.
...(mcpOAuth
? [
jwt({ disableSettingJwtHeader: true, jwt: { issuer: MCP_ISSUER } }),
mcp({
resource: MCP_RESOURCE,
loginPage: `${trustedOrigins[0]}/login`,
consentPage: `${trustedOrigins[0]}/oauth/consent`,
// Every token acts for a person; client_credentials would mint one for none.
grantTypes: ['authorization_code', 'refresh_token'],
allowDynamicClientRegistration: true,
allowUnauthenticatedClientRegistration: true,
// Claude Code and Cursor send no application_type; "web" would refuse them.
clientRegistrationDefaultApplicationType: 'infer',
}),
]
: []),
// OpenAPI reference for the better-auth handler. Serves a Scalar UI at
// /api/auth/reference and the raw schema at /api/auth/open-api/generate-schema.
// The schema is built from every active plugin, so the passkey and apiKey
// endpoints are documented automatically. This is docs-only: it adds no table,
// so `auth:generate` is not needed. The planner's own OpenAPI docs stay at /docs.
openAPI(),
// A build's own (./extensions). Typed as none, so the instance's type stays the core's.
...(extensions.plugins as []),
],
// The frontend runs on a different origin (Next :3001) — allow its requests.
trustedOrigins,
// /is-username-available answers for anyone, and a username is derived from the
// address, so it would tell a stranger which addresses are registered. Nothing in
// the app calls it — the profile form learns a name is taken from updateUser's
// error. jwt()'s /token hands out a JWT of the session, which nothing reads.
disabledPaths: ['/is-username-available', '/token', ...extensions.disabledPaths],
advanced: {
// Share the session cookie across subdomains when COOKIE_DOMAIN is the parent
// domain (e.g. ".itsaplan.dev" for app.itsaplan.dev + api.itsaplan.dev). Without
// it the cookie is host-only for the api origin, so the SSR web app on another
// subdomain cannot read the session. Leave COOKIE_DOMAIN unset on localhost
// (single host), where "lax" host-only cookies already work across ports.
...(cookieDomain
? {
crossSubDomainCookies: {
enabled: true,
domain: cookieDomain,
},
}
: {}),
// For a single site (localhost / one domain) "lax" is enough. Subdomains of one
// registrable domain are same-site, so "lax" cookies are still sent between them.
...(hostPrefixedCookies
? {
useSecureCookies: false,
cookiePrefix: '__Secure-better-auth',
cookies: Object.fromEntries(
SESSION_COOKIES.map((name) => [
name,
{ name: `__Host-better-auth.${name}`, attributes: { path: '/', secure: true } },
]),
),
}
: {}),
defaultCookieAttributes: {
sameSite: 'lax',
secure: hostPrefixedCookies || process.env.NODE_ENV === 'production',
},
ipAddress: {
ipAddressHeaders: clientIpHeader ? [clientIpHeader] : undefined,
trustedProxies,
},
},
});
}
let instance: ReturnType<typeof createAuth> | undefined;
const instanceOf = () => (instance ??= createAuth());
export const auth = new Proxy({} as ReturnType<typeof createAuth>, {
get: (_target, key) => Reflect.get(instanceOf(), key),
has: (_target, key) => Reflect.has(instanceOf(), key),
});
export type Auth = typeof auth;
export type Session = Auth['$Infer']['Session'];
// A key the apiKey plugin will not accept — expired, revoked or malformed — makes
// it throw out of getSession instead of returning no session, which a caller can
// only report as a 500. Such a request carries no session, so it is answered as
// one, and a key that reached its expiry is refused like any other unauthenticated
// request. A refusal for another reason, a rate-limited key among them, still
// propagates: it is not the same answer.
export async function getSessionFromHeaders(
headers: Headers,
): Promise<Awaited<ReturnType<typeof auth.api.getSession>>> {
try {
return await auth.api.getSession({ headers });
} catch (error) {
if (error instanceof APIError && (error.statusCode === 401 || error.statusCode === 403)) {
return null;
}
throw error;
}
}
// Instance-wide authentication settings (registration mode, mail provider, invite
// links). Read here by the sign-up gate and the mail senders; managed over HTTP by
// god mode in apps/api.
export {
REGISTRATION_MODES,
getAuthSettings,
setAuthSettings,
emailDomainAllowed,
registrationEmailAllowed,
setRegistrationEmailPolicy,
setRegistrationAdmission,
inviteValidSince,
getEmailSettings,
setEmailSettings,
getEmailTemplateSettings,
setEmailTemplateSettings,
resolveEmailConfig,
getGoogleSettings,
setGoogleSettings,
getGoogleConfig,
hasConfiguredGoogle,
getOidcSettings,
setOidcSettings,
getOidcConfig,
getOidcLabel,
hasConfiguredOidc,
getScimSettings,
setScimSettings,
rotateScimToken,
verifyScimToken,
setWorkspaceScim,
workspaceScim,
workspacesWithOwnScim,
isAccountDeactivated,
accountsManagedByScim,
} from './instance';
export type {
RegistrationMode,
AuthSettings,
InstanceEmailDto,
InstanceEmailPatch,
EmailTemplateSettings,
InstanceGoogleDto,
InstanceGooglePatch,
InstanceGoogleConfig,
InstanceOidcDto,
InstanceOidcPatch,
InstanceOidcConfig,
ScimSettingsDto,
} from './instance';