Zeroword Docs

Next.js SDK (@auth-platform/next)#

@auth-platform/next は Server SDK (@auth-platform/server) の BFF handler を Next.js App Router に接続する helper である。実装は Web 標準 Request / Response / Headers のみを使い、SDK 自体は next を import しない。Next.js が必要な middleware や Server Component の API はアプリ側から import する。

インストール#

pnpm add @auth-platform/server @auth-platform/next

createServerAuth() と session cookie の設定は Server SDK (@auth-platform/server) を参照する。

App Router の認証 routes#

Next.js Route Handler は Web Request を受け取り Web Response を返す。各 factory の戻り値を route.ts から export する。

// app/auth/login/route.ts
import { createLoginRouteHandler } from "@auth-platform/next";
import { auth } from "@/lib/auth";

export const { GET, POST } = createLoginRouteHandler(auth);

// app/auth/callback/route.ts
import { createCallbackRouteHandler } from "@auth-platform/next";
import { auth } from "@/lib/auth";

export const { GET } = createCallbackRouteHandler(auth);

// app/auth/logout/route.ts
import { createLogoutRouteHandler } from "@auth-platform/next";
import { auth } from "@/lib/auth";

export const { GET, POST } = createLogoutRouteHandler(auth);

createAuthRouteHandlers(auth) は同じ3つの factory をまとめて { login, callback, logout } として返す。login/logout は GET と POST、callback は GET だけを提供する。Origin/Referer、CSRF、state、PKCE の検査は @auth-platform/server handler が行う。

Next middleware で保護#

createAuthMiddleware(auth, options?) は Request handler を返す。protectedPrefixes の path をセッション必須にし、protect(pathname) を渡した場合はその関数が優先される。prefix 判定は文字列の startsWith であるため、segment 単位の判定が必要なら protect を使う。

戻り値は次のいずれかである。

  • { action: "next", setCookie? }: request を通す。session refresh があれば setCookie を返す。
  • { action: "respond", response }: 未認証時の login redirect、または一時的 refresh 障害の 503 を返す。
// middleware.ts
import { NextResponse, type NextRequest } from "next/server";
import { createAuthMiddleware } from "@auth-platform/next";
import { auth } from "@/lib/auth";

const authenticate = createAuthMiddleware(auth, {
  protectedPrefixes: ["/account", "/admin"],
});

export async function middleware(request: NextRequest) {
  const result = await authenticate(request);
  if (result.action === "respond") return result.response;

  const response = NextResponse.next();
  if (result.setCookie !== undefined) {
    response.headers.append("set-cookie", result.setCookie);
  }
  return response;
}

export const config = { matcher: ["/account/:path*", "/admin/:path*"] };

Middleware matcher は Next.js 側の route filtering であり、SDK の protectedPrefixes / protect はその handler に渡された Request の path を判定する。matcher を使わず SDK handler を広く呼んでも、保護対象以外は { action: "next" } となる。

Session helper と App Router#

getSession(auth, source) は GetSessionOutcome を返す。source は Request、Headers、または { headers: Headers } である。requireSession(auth, source, options?) は RequireSessionOutcome を返し、失敗時に返す Response は @auth-platform/server の requireSession() と同じ redirect / problem JSON である。Header-only source の場合、options.returnTo を指定すると未認証時 login の戻り先になる（既定値 /）。

Route Handler では失敗 response をそのまま返し、成功時の session cookie を outgoing response に追加できる。

// app/api/account/route.ts
import { requireSession } from "@auth-platform/next";
import { auth } from "@/lib/auth";

export async function GET(request: Request) {
  const outcome = await requireSession(auth, request, { onUnauthenticated: "json" });
  if (!outcome.ok) return outcome.response;

  const response = Response.json({ sub: outcome.session.user.sub });
  if (outcome.setCookie !== undefined) {
    response.headers.append("set-cookie", outcome.setCookie);
  }
  return response;
}

React Server Component では outgoing Response を返せないため、getSession() の outcome を読み、Next.js の redirect() などで描画を制御する。Header-only source から refresh が起きた場合、outgoing response がないため cookie は自動設定されない。setCookie / clearCookie を適用できる Route Handler、Server Action、または refresh を行う middleware を使う。

// app/account/page.tsx
import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { getSession } from "@auth-platform/next";
import { auth } from "@/lib/auth";

export default async function AccountPage() {
  const outcome = await getSession(auth, await headers());
  if (outcome.status === "unauthenticated") {
    if (outcome.reason === "refresh_unavailable") return <p>Sign-in is temporarily unavailable. Try again.</p>;
    redirect("/auth/login?return_to=%2Faccount");
  }
  return <p>Signed in as {outcome.session.user.sub}</p>;
}

Server Component から login response の 302 を直接返すのではなく、Next.js navigation API を使う。protected route を middleware で守れば、cookie refresh/更新を outgoing response に反映しやすい。

next dependency がない設計#

SDK の公開関数は構造的に Web Request / Response を受け渡すため、next/server や next/headers を実装から import しない。NextRequest は Web Request として、Response は Next.js Route Handler / middleware の戻り値として利用できる。Next.js の NextResponse、headers()、redirect() は必要な場所でアプリ側が import する。

BFF の cookie・CSRF・error・Result 契約は Server SDK (@auth-platform/server)、Hono adapter は Hono SDK (@auth-platform/hono) を参照する。