基于 Better Auth + Drizzle 的安全登录:邮箱/密码、GitHub/Google、双重验证、限流与 CSRF 防护
代码6 个文件上下文约 812 个 tokenMCP better-auth扫描通过
安装
$
genpm add @yohangel/auth你将获得
- 源代码位于 src/lib/auth/,共 6 个文件。 (15.5 kB)
- AI 规则位于 src/lib/auth/AGENTS.md,另附 IDE 规则文件。
- 添加到 .env.example 的环境变量:BETTER_AUTH_SECRET, BETTER_AUTH_URL, DATABASE_URL。
README
此包没有 README。
约 812 个 token→ src/lib/auth/AGENTS.md→ .cursor/rules/genpm-yohangel-auth.mdc
这正是你的 AI 在 src/lib/auth 中工作时读取的内容。不会向其上下文添加其他任何内容。
@yohangel/auth — rules for AI agents
Purpose
Server-side authentication core built on Better Auth + Drizzle (Postgres): email/password, GitHub/Google OAuth, TOTP 2FA, database-backed rate limiting and CSRF protection. Framework-agnostic: pair it with @yohangel/auth-next, auth-express or auth-nest (server) and @yohangel/auth-react (UI). It does not send emails by itself and has no UI.
Module map
index.ts— public API. Import only from here.auth.ts—createAuth(opts)(secure defaults),getAuth(),getSession(headers),socialProviders().schema.ts— Drizzle tables:users,sessions,accounts,verifications,two_factors,rate_limits.db.ts—setAuthDb(db)/getAuthDb(); defaults to postgres-js fromDATABASE_URL.
Integration (do this after installing)
- Set env vars (add them to
.env.example, never commit real values):BETTER_AUTH_SECRET— 32+ random chars (openssl rand -base64 32). Startup throws in production if shorter.BETTER_AUTH_URL— public base URL of the server, e.g.https://app.example.com.DATABASE_URL— Postgres. If the app already has a Drizzle client, pass it:createAuth({ db }).- Optional:
GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET,GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET(a provider is enabled only when both are set; callback URL is<BETTER_AUTH_URL>/api/auth/callback/<provider>),APP_NAME(2FA issuer),AUTH_TRUSTED_ORIGINS(comma-separated extra origins, e.g. a separate SPA),AUTH_IP_HEADER(e.g.cf-connecting-ipbehind Cloudflare, so rate limits see the real client IP).
- Add the tables to the app's migrations: include
src/lib/auth/schema.tsindrizzle.config.tsschema, thennpx drizzle-kit generate && npx drizzle-kit migrate. - Wire emails:
createAuth({ sendEmail: async ({ kind, to, url, subject, text }) => … })using the app's mailer. WithsendEmailset, email verification is required to sign in and password reset is enabled. Without it, links are printed to the console in development only. - Create the instance through the framework adapter package (it calls
createAuthwith the right plugins). UsegetSession(headers)anywhere else on the server.
Conventions
- One instance per app. Extra Better Auth plugins go in
createAuth({ plugins: [...] })— e.g.organization(),admin(),passkey()— then regenerate/extendschema.tswith the tables those plugins document. - Always authorize on the server with
getSession(); client-side checks are only for UX. - Prefer
overridesonly for options not covered here, and keep the security defaults below.
Don't
- Don't lower
minPasswordLength(12), disablerateLimitin production, or setadvanced.disableCSRFCheck/disableOriginChecktotrue. - Don't log, return or store passwords, session tokens, OAuth tokens or
BETTER_AUTH_SECRET. - Don't add origins to
AUTH_TRUSTED_ORIGINSwith wildcards you do not control. - Don't read
accounts.passwordor compare passwords yourself; use Better Auth's API. - Don't build redirects from user input without checking they are internal paths.
Docs: the Better Auth MCP server (better-auth) is configured by GenPM; ask it about plugins and options.
# @yohangel/auth — rules for AI agents
## Purpose
Server-side authentication core built on Better Auth + Drizzle (Postgres): email/password, GitHub/Google OAuth, TOTP 2FA, database-backed rate limiting and CSRF protection. Framework-agnostic: pair it with `@yohangel/auth-next`, `auth-express` or `auth-nest` (server) and `@yohangel/auth-react` (UI). It does not send emails by itself and has no UI.
## Module map
- `index.ts` — public API. Import only from here.
- `auth.ts` — `createAuth(opts)` (secure defaults), `getAuth()`, `getSession(headers)`, `socialProviders()`.
- `schema.ts` — Drizzle tables: `users`, `sessions`, `accounts`, `verifications`, `two_factors`, `rate_limits`.
- `db.ts` — `setAuthDb(db)` / `getAuthDb()`; defaults to postgres-js from `DATABASE_URL`.
## Integration (do this after installing)
1. Set env vars (add them to `.env.example`, never commit real values):
- `BETTER_AUTH_SECRET` — 32+ random chars (`openssl rand -base64 32`). Startup throws in production if shorter.
- `BETTER_AUTH_URL` — public base URL of the server, e.g. `https://app.example.com`.
- `DATABASE_URL` — Postgres. If the app already has a Drizzle client, pass it: `createAuth({ db })`.
- Optional: `GITHUB_CLIENT_ID`/`GITHUB_CLIENT_SECRET`, `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET` (a provider is enabled only when both are set; callback URL is `<BETTER_AUTH_URL>/api/auth/callback/<provider>`), `APP_NAME` (2FA issuer), `AUTH_TRUSTED_ORIGINS` (comma-separated extra origins, e.g. a separate SPA), `AUTH_IP_HEADER` (e.g. `cf-connecting-ip` behind Cloudflare, so rate limits see the real client IP).
2. Add the tables to the app's migrations: include `src/lib/auth/schema.ts` in `drizzle.config.ts` `schema`, then `npx drizzle-kit generate && npx drizzle-kit migrate`.
3. Wire emails: `createAuth({ sendEmail: async ({ kind, to, url, subject, text }) => … })` using the app's mailer. With `sendEmail` set, email verification is required to sign in and password reset is enabled. Without it, links are printed to the console in development only.
4. Create the instance through the framework adapter package (it calls `createAuth` with the right plugins). Use `getSession(headers)` anywhere else on the server.
## Conventions
- One instance per app. Extra Better Auth plugins go in `createAuth({ plugins: [...] })` — e.g. `organization()`, `admin()`, `passkey()` — then regenerate/extend `schema.ts` with the tables those plugins document.
- Always authorize on the server with `getSession()`; client-side checks are only for UX.
- Prefer `overrides` only for options not covered here, and keep the security defaults below.
## Don't
- Don't lower `minPasswordLength` (12), disable `rateLimit` in production, or set `advanced.disableCSRFCheck` / `disableOriginCheck` to `true`.
- Don't log, return or store passwords, session tokens, OAuth tokens or `BETTER_AUTH_SECRET`.
- Don't add origins to `AUTH_TRUSTED_ORIGINS` with wildcards you do not control.
- Don't read `accounts.password` or compare passwords yourself; use Better Auth's API.
- Don't build redirects from user input without checking they are internal paths.
Docs: the Better Auth MCP server (`better-auth`) is configured by GenPM; ask it about plugins and options.
应用 .genpmignore 后将被注入的确切目录树。固定于
// Instancia de Better Auth con valores seguros por defecto. Los adaptadores de framework (auth-next, auth-express,
// auth-nest) llaman a `createAuth()` con sus plugins; el resto del código usa `getAuth()` / `getSession()`.
import { drizzleAdapter } from '@better-auth/drizzle-adapter';
import { type BetterAuthOptions, type BetterAuthPlugin, betterAuth } from 'better-auth';
import { twoFactor } from 'better-auth/plugins';
import { type AuthDb, getAuthDb, setAuthDb } from './db.js';
import { authSchema } from './schema.js';
/** Correo que Better Auth necesita enviar. `subject` y `text` son un texto por defecto en inglés; usa `kind` y `url`
* para tus propias plantillas (p. ej. Resend o tu mailer). */
export type AuthEmail = {
kind: 'verify-email' | 'reset-password';
to: string;
url: string;
subject: string;
text: string;
};
export type CreateAuthOptions = {
/** Tu cliente Drizzle (Postgres). Por defecto, uno creado desde DATABASE_URL. */
db?: AuthDb;
/** Plugins extra de Better Auth (organization, passkey, magicLink…). `nextCookies()` siempre el último. */
plugins?: BetterAuthPlugin[];
/** Envío de correos de verificación y de restablecer contraseña. Sin él: en desarrollo se imprimen los enlaces
* en consola; en producción no se exige verificar el email y restablecer contraseña queda desactivado. */
sendEmail?: (email: AuthEmail) => Promise<void>;
/** Sobrescribe cualquier opción de Better Auth (se aplica al final; úsalo con cuidado). */
overrides?: Partial<BetterAuthOptions>;
};
const isProd = () => process.env.NODE_ENV === 'production';
const list = (v: string | undefined) =>
(v ?? '')
.split(',')
.map((s) => s.trim())
.filter(Boolean);
function checkSecret(): void {
const secret = process.env.BETTER_AUTH_SECRET ?? '';
if (isProd() && secret.length < 32)
throw new Error('BETTER_AUTH_SECRET must be at least 32 characters (openssl rand -base64 32)');
}
/** Proveedores OAuth activos: solo los que tienen client id y secret en el entorno. */
export function socialProviders(): NonNullable<BetterAuthOptions['socialProviders']> {
const out: NonNullable<BetterAuthOptions['socialProviders']> = {};
const e = process.env;
if (e.GITHUB_CLIENT_ID && e.GITHUB_CLIENT_SECRET)
out.github = { clientId: e.GITHUB_CLIENT_ID, clientSecret: e.GITHUB_CLIENT_SECRET };
if (e.GOOGLE_CLIENT_ID && e.GOOGLE_CLIENT_SECRET)
out.google = { clientId: e.GOOGLE_CLIENT_ID, clientSecret: e.GOOGLE_CLIENT_SECRET };
return out;
}
export function createAuth(opts: CreateAuthOptions = {}) {
checkSecret();
if (opts.db) setAuthDb(opts.db);
const appName = process.env.APP_NAME ?? 'App';
const send =
opts.sendEmail ??
(isProd()
? null
: async (m: AuthEmail) => {
console.info(`[auth] ${m.kind} for ${m.to}: ${m.url}`);
});
const ipHeader = process.env.AUTH_IP_HEADER;
const options = {
appName,
database: drizzleAdapter(getAuthDb(), { provider: 'pg', schema: authSchema }),
trustedOrigins: list(process.env.AUTH_TRUSTED_ORIGINS),
emailAndPassword: {
enabled: true,
// NIST 800-63B: mínimo largo antes que reglas de composición. Hash scrypt (por defecto en Better Auth).
minPasswordLength: 12,
maxPasswordLength: 128,
requireEmailVerification: !!opts.sendEmail,
revokeSessionsOnPasswordReset: true,
...(send
? {
sendResetPassword: async ({ user, url }: { user: { email: string }; url: string }) =>
send({
kind: 'reset-password',
to: user.email,
url,
subject: `Reset your ${appName} password`,
text: `Open this link to choose a new password (valid for 1 hour): ${url}\n\nIf you did not ask for it, ignore this email.`,
}),
}
: {}),
},
...(send
? {
emailVerification: {
sendOnSignUp: true,
autoSignInAfterVerification: true,
sendVerificationEmail: async ({ user, url }: { user: { email: string }; url: string }) =>
send({
kind: 'verify-email',
to: user.email,
url,
subject: `Verify your ${appName} email`,
text: `Confirm your email address: ${url}`,
}),
},
}
: {}),
socialProviders: socialProviders(),
session: {
expiresIn: 60 * 60 * 24 * 30,
updateAge: 60 * 60 * 24,
// Caché firmada en cookie: menos lecturas de BD; una sesión revocada deja de valer en ≤ 5 min.
cookieCache: { enabled: true, maxAge: 5 * 60 },
},
rateLimit: {
enabled: isProd() || process.env.AUTH_RATE_LIMIT === '1',
storage: 'database',
window: 60,
max: 100,
customRules: {
'/sign-in/email': { window: 60, max: 5 },
'/sign-up/email': { window: 60, max: 3 },
'/request-password-reset': { window: 300, max: 3 },
'/two-factor/*': { window: 60, max: 5 },
},
},
advanced: {
// Explícitos: Better Auth los desactiva solo si NODE_ENV=test; aquí la protección CSRF nunca depende del entorno.
disableCSRFCheck: false,
disableOriginCheck: false,
...(ipHeader ? { ipAddress: { ipAddressHeaders: [ipHeader] } } : {}),
},
plugins: [twoFactor({ issuer: appName }), ...(opts.plugins ?? [])],
...opts.overrides,
} satisfies BetterAuthOptions;
const instance = betterAuth(options);
current = instance as unknown as Auth;
return instance;
}
export type Auth = ReturnType<typeof createAuth>;
let current: Auth | null = null;
/** La instancia de la app (la última creada con `createAuth`, o una por defecto sin plugins extra). */
export function getAuth(): Auth {
current ??= createAuth();
return current;
}
export type AuthSession = NonNullable<Awaited<ReturnType<Auth['api']['getSession']>>>;
/** Sesión y usuario de una petición a partir de sus cabeceras (null si no hay sesión válida). */
export async function getSession(headers: Headers): Promise<AuthSession | null> {
return getAuth().api.getSession({ headers });
}
- 服务器
- better-auth
- 命令
- https://mcp.better-auth.com/mcp
| 版本 | 提交 | 发布时间 | 扫描 |
|---|---|---|---|
| 1.0.0 | 7145b9d | 3小时前 | ✔ 扫描通过 |
- genpm
- 无
- 建议
- GenPM 会给出 npm 命令建议,只有你同意时才会运行。
- 扫描
- 扫描通过 · 0 个问题
- 提交
- auth@1.0.0 → 7145b9d58055b5145085782c958b7577f1d65276 · 获取后已校验
- 脚本
- 无。GenPM 从不运行包中的代码。
- 许可证
- MIT
- 举报
- 发现问题了吗?