Korumalı yönetim paneli

Senaryo

Bir mağazanın yönetim panelini yazacaksınız. Panel:

• E-posta ve parolayla giriş ister. Giriş yapmamış kullanıcı /sign-in'e gider.

• Üç rol tanır: customer panele giremez, editor fiyat günceller, admin ürün arşivler ve rol değiştirir.

• Ürün açıklamasını HTML olarak gösterir ama içindeki script'i temizler.

• Arşivleme bir Route Handler'dır ve başka siteden gelen isteği reddeder.

• Her sayfada nonce'lu CSP ve güvenlik başlıkları vardır.

• Hepsini Playwright testleriyle korur.

Her parçanın hangi dersten geldiği:

Projenin çalışan hali GitHub'da: examples/auth-security/project. Uygulama ve 12 test orada; takıldığınızda karşılaştırın.

Adım 1: Projeyi Kurun

$ pnpm create next-app@latest admin-panel --yes

$ pnpm add better-auth better-sqlite3 isomorphic-dompurify zod server-only

create-next-app, next.config.ts'e cacheComponents: true yazar. Bu projede onu kapatın: nonce'lu CSP, Partial Prerendering ile çalışmaz.¹ Yönetim paneli zaten kişiye özel olduğu için statik kabuktan bir şey kaybetmezsiniz.

// next.config.ts
const nextConfig: NextConfig = {
  cacheComponents: false,
  poweredByHeader: false,
  serverExternalPackages: ["better-sqlite3"],
  experimental: {
    authInterrupts: true,
  },
  async headers() {
    return [{ source: "/:path*", headers: securityHeaders }];
  },
};

securityHeaders dizisi CSRF, CORS ve güvenlik başlıkları dersindeki listenin aynısıdır. authInterrupts, 403 sayfası gösteren forbidden() fonksiyonunu açar; şu an deneyseldir.²

Kök layout'ta await connection() çağırın. Nonce her istekte üretildiği için hiçbir sayfa statik kalmamalı; aksi halde giriş formunun script'leri nonce'suz kalır ve CSP onları engeller.¹ Testte bu satır olmadan /sign-in statik üretildi ve form çalışmadı.

Adım 2: Kullanıcı ve Rol

Rol, kullanıcının kendisinin gönderemeyeceği bir alandır:³

// lib/auth.ts
export const auth = betterAuth({
  database: db,
  emailAndPassword: { enabled: true },
  user: {
    additionalFields: {
      role: { type: "string", defaultValue: "customer", input: false },
    },
  },
  plugins: [nextCookies()],
});

Tabloları npx auth migrate --yes açar. scripts/seed.ts üç kullanıcı ve üç ürün ekler; biri bilerek <img onerror> taşır.

Adım 3: İzinler ve Data Access Layer

İzinler Yetkilendirme ve roller dersindeki gibi tek dosyadadır. customer'ın listesi boştur:

// lib/permissions.ts
const permissions = {
  customer: [],
  editor: ["product:read", "product:update"],
  admin: ["product:read", "product:update", "product:archive", "user:manage"],
} as const satisfies Record<Role, readonly string[]>;

requirePermission artık Error fırlatmak yerine forbidden() çağırır. Next.js 403 durum kodu döner ve app/forbidden.tsx'i gösterir:²

// lib/dal.ts
export async function requirePermission(permission: Permission) {
  const user = await getCurrentUser();

  if (!hasPermission(user.role, permission)) {
    forbidden();
  }

  return user;
}

Her sayfa ilk satırda bunu çağırır: /admin için product:read, /admin/users için user:manage.

Adım 4: Ürünler ve Temiz HTML

Veri katmanı tablo satırını değil, sayfanın ihtiyacı olan alanları döndürür. Açıklama burada, üretildiği yerde temizlenir:⁴⁵

// lib/products.ts
return rows.map((row) => ({
  id: row.id,
  name: row.name,
  price: row.price,
  description: { __html: DOMPurify.sanitize(row.description) },
}));

<td dangerouslySetInnerHTML={product.description} />

Testte <b>4K</b> panel<img src="x" onerror="..."> açıklaması kalın yazıyla ve onerror'sız basıldı.

Adım 5: Server Action'lar

Her action izin kontrolüyle başlar, sonra girdiyi Zod ile doğrular. Sayfadaki kontrol action'ı korumaz; action doğrudan çağrılabilir:⁶

// app/admin/actions.ts
export async function setRoleAction(formData: FormData) {
  const currentUser = await requirePermission("user:manage");
  const { id, role } = roleSchema.parse(Object.fromEntries(formData));

  if (id === currentUser.id) {
    throw new Error("Kendi rolünüzü değiştiremezsiniz.");
  }

  setRole(id, role);
  revalidatePath("/admin/users");
}

Son yöneticinin kendini customer yapıp paneli sahipsiz bırakmasını bu kontrol engeller.

Adım 6: Arşivleme Route Handler'ı

Arşivleme bir istemci bileşeninden fetch ile çağrılır. Route Handler önce isteğin nereden geldiğine, sonra oturuma, en son izne bakar:

// app/api/admin/products/[id]/archive/route.ts
export async function POST(request: Request, { params }: { params: Promise<{ id: string }> }) {
  if (isCrossSiteRequest(request)) {
    return new Response(null, { status: 403 });
  }

  const session = await auth.api.getSession({ headers: await headers() });

  if (!session) {
    return new Response(null, { status: 401 });
  }

  const role = isRole(session.user.role) ? session.user.role : "customer";

  if (!hasPermission(role, "product:archive")) {
    return new Response(null, { status: 403 });
  }

  const { id } = await params;
  return archiveProduct(id) ? new Response(null, { status: 204 }) : new Response(null, { status: 404 });
}

isCrossSiteRequest, CSRF dersindeki Sec-Fetch-Site kontrolüdür.⁷

Adım 7: Proxy

proxy.ts iki iş yapar. /admin için cookie yoksa /sign-in'e yönlendirir; bu yalnızca iyimser bir kontroldür, asıl kontrol DAL'dadır.⁸ Sonra her sayfa isteğine nonce'lu CSP ekler. CSP kısmı XSS ve CSP dersindeki kodun aynısıdır.

// proxy.ts
export function proxy(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith("/admin") && !getSessionCookie(request)) {
    return NextResponse.redirect(new URL("/sign-in", request.url));
  }

  // ... nonce ve Content-Security-Policy
}

Adım 8: Testler

Playwright'ın önerdiği gibi her rol bir setup projesinde bir kez giriş yapar ve oturumu dosyaya kaydeder. Testler bu dosyayı storageState ile kullanır.⁹

Bunun bir sebebi daha var. Better Auth production'da /sign-in/email isteklerini 10 saniyede 3 istekle sınırlar.¹⁰ Testte her test kendi girişini yapınca dördüncü giriş 429 aldı. Bu sınır kaba kuvvet (brute force) saldırılarına karşı ücretsiz bir korumadır; geliştirme ortamında kapalıdır.

CSRF testi saldırgan sayfayı page.route ile sahte bir alan adında (https://evil.example) üretir. Tarayıcı isteği gerçekten başka bir siteden gönderir.

Adım 9: Son Kontrol

npm run lint
npm run build
npm run test:e2e

Build çıktısında bütün sayfalar ƒ (dinamik) görünmeli. npm audit geliştirme araçlarındaki bir açığı raporladı; npm audit --omit=dev ise sıfır açık gösterdi. Production'a giden paketlerle geliştirme araçlarını ayırarak okuyun.

Kendin Dene

• lib/dal.ts'ten forbidden() satırını silin. Hangi testler kırılıyor?

• setRoleAction'daki "kendi rolünü değiştiremez" kontrolünü silin ve tek admin olarak kendinizi customer yapın. Paneli geri almanın bir yolu var mı?

• Route Handler'daki isCrossSiteRequest satırını silip CSRF testini çalıştırın. Neden yine de 401 aldı? (İpucu: SameSite=Lax.)

• next.config.ts'te cacheComponents: true yapın, build alın ve giriş sayfasını açın. Konsolda ne görüyorsunuz?

• Bir audit_log tablosu ekleyin: fiyat ve rol değişikliklerinde kim, neyi, ne zaman değiştirdi.