@core / auth

1.0.0 ▾

1.0.0

verificadoMIT

GitHub

Sesiones + OAuth (GitHub, Google) con Drizzle, para Hono y Next.js

Código9 archivosContexto~670 tokensescaneo superado

~670 tokens→ src/lib/auth/AGENTS.md→ .cursor/rules/genpm-core-auth.mdc

Esto es exactamente lo que lee tu IA cuando trabaja en src/lib/auth. No se añade nada más a su contexto.

@core/auth — rules for AI agents

Purpose

Cookie sessions (random token, only its SHA-256 stored, 30-day sliding expiry, rotation) and OAuth login with GitHub and Google via arctic. Tables: users, auth_sessions, oauth_accounts. No roles or permissions (out of scope: build them in your app on top of users.id). No passwords.

Map

index.ts — public API: getUserFromCookieHeader, signOut, startOAuth, finishOAuth, session functions, User.
adapters/hono.ts — sessionMiddleware, requireUser, authRoutes().
adapters/next.ts — loginRoute, callbackRoute, logoutRoute, getUser(cookies).
schema.ts — Drizzle tables. Depends on ../db (@core/db).

Integration

Env: AUTH_SECRET (≥ 32 random chars, e.g. openssl rand -base64 32), GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET. Optional Google: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET. Providers without both vars are disabled.
OAuth app callback URL: <origin>/auth/callback/github (and /auth/callback/google).
Generate and apply migrations (see src/lib/db/AGENTS.md).
Hono:
```
import { authRoutes, requireUser, sessionMiddleware } from './lib/auth/adapters/hono.js';
app.use(sessionMiddleware);
app.route('/auth', authRoutes());
app.get('/api/me', requireUser, (c) => c.json(c.get('user')));
```
Next.js (App Router): create app/auth/login/[provider]/route.ts with export { loginRoute as GET } from '@/lib/auth/adapters/next', the same for callback/[provider] (callbackRoute) and app/auth/logout/route.ts (logoutRoute as POST). In Server Components: const user = await getUser(await cookies()). Delete the adapter of the framework you don't use (adapters/hono.ts imports hono).
Login link: <a href="/auth/login/github?returnTo=/dashboard">. Logout: POST /auth/logout.
Verify: open /auth/login/github, finish the flow, then GET /api/me returns the user.

Conventions

Read the current user only through sessionMiddleware/getUser; never parse the cookie yourself.
Other modules reference users.id (text, usr_…) with onDelete: 'cascade' or set null.
Call rotateSession after a privilege change and invalidateUserSessions when an account is compromised.
If you installed @core/db with --dest, fix the ../db/index.js imports here.

Don't

Don't store or log session tokens, OAuth codes or AUTH_SECRET.
Don't link accounts by unverified email; upsertOAuthUser already enforces it.
Don't accept absolute returnTo URLs (open redirect); use safeReturnTo.
Don't make GET requests log users out, and don't disable HttpOnly/SameSite on the cookie.

# @core/auth — rules for AI agents

## Purpose
Cookie sessions (random token, only its SHA-256 stored, 30-day sliding expiry, rotation) and OAuth login with GitHub
and Google via `arctic`. Tables: `users`, `auth_sessions`, `oauth_accounts`. No roles or permissions (out of scope:
build them in your app on top of `users.id`). No passwords.

## Map
- `index.ts` — public API: `getUserFromCookieHeader`, `signOut`, `startOAuth`, `finishOAuth`, session functions, `User`.
- `adapters/hono.ts` — `sessionMiddleware`, `requireUser`, `authRoutes()`.
- `adapters/next.ts` — `loginRoute`, `callbackRoute`, `logoutRoute`, `getUser(cookies)`.
- `schema.ts` — Drizzle tables. Depends on `../db` (@core/db).

## Integration
1. Env: `AUTH_SECRET` (≥ 32 random chars, e.g. `openssl rand -base64 32`), `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`.
   Optional Google: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`. Providers without both vars are disabled.
2. OAuth app callback URL: `<origin>/auth/callback/github` (and `/auth/callback/google`).
3. Generate and apply migrations (see `src/lib/db/AGENTS.md`).
4. Hono:
   ```ts
   import { authRoutes, requireUser, sessionMiddleware } from './lib/auth/adapters/hono.js';
   app.use(sessionMiddleware);
   app.route('/auth', authRoutes());
   app.get('/api/me', requireUser, (c) => c.json(c.get('user')));
   ```
   Next.js (App Router): create `app/auth/login/[provider]/route.ts` with `export { loginRoute as GET } from '@/lib/auth/adapters/next'`,
   the same for `callback/[provider]` (`callbackRoute`) and `app/auth/logout/route.ts` (`logoutRoute as POST`).
   In Server Components: `const user = await getUser(await cookies())`.
   Delete the adapter of the framework you don't use (`adapters/hono.ts` imports `hono`).
5. Login link: `<a href="/auth/login/github?returnTo=/dashboard">`. Logout: `POST /auth/logout`.
6. Verify: open `/auth/login/github`, finish the flow, then `GET /api/me` returns the user.

## Conventions
- Read the current user only through `sessionMiddleware`/`getUser`; never parse the cookie yourself.
- Other modules reference `users.id` (text, `usr_…`) with `onDelete: 'cascade'` or `set null`.
- Call `rotateSession` after a privilege change and `invalidateUserSessions` when an account is compromised.
- If you installed `@core/db` with `--dest`, fix the `../db/index.js` imports here.

## Don't
- Don't store or log session tokens, OAuth codes or `AUTH_SECRET`.
- Don't link accounts by unverified email; `upsertOAuthUser` already enforces it.
- Don't accept absolute `returnTo` URLs (open redirect); use `safeReturnTo`.
- Don't make GET requests log users out, and don't disable `HttpOnly`/`SameSite` on the cookie.

El árbol exacto que se inyectará, tras aplicar .genpmignore. Anclado a

src/lib/auth/cookies.tssolo lectura · 12c4918

// Cookies de sesión y de estado OAuth, sin dependencias de framework (devuelven cabeceras Set-Cookie).
import { SESSION_TTL_MS } from './session.js';

export const SESSION_COOKIE = 'session';

const secure = () => process.env.NODE_ENV === 'production';

export function serializeCookie(name: string, value: string, maxAgeSeconds: number): string {
  const parts = [`${name}=${encodeURIComponent(value)}`, 'Path=/', 'HttpOnly', 'SameSite=Lax', `Max-Age=${maxAgeSeconds}`];
  if (secure()) parts.push('Secure');
  return parts.join('; ');
}

export function parseCookies(header: string | null | undefined): Record<string, string> {
  const out: Record<string, string> = {};
  for (const part of (header ?? '').split(';')) {
    const i = part.indexOf('=');
    if (i < 1) continue;
    try {
      out[part.slice(0, i).trim()] = decodeURIComponent(part.slice(i + 1).trim());
    } catch {
      // cookie mal codificada: se ignora
    }
  }
  return out;
}

export const sessionCookie = (token: string) => serializeCookie(SESSION_COOKIE, token, SESSION_TTL_MS / 1000);
export const clearSessionCookie = () => serializeCookie(SESSION_COOKIE, '', 0);