@playstack/auth-next

@playstack/auth-next provides explicit Pages and App Router session handoff and protection over an application-owned @playstack/auth service. Both bindings are structural and import no Next.js runtime.

Install and compose

npm install @playstack/auth @playstack/auth-next

import { createAuthNextHelpers } from '@playstack/auth-next/pages'

export const { requireSession, withSession } = createAuthNextHelpers({
  async resolveSession(context) {
    return resolveSafeSessionView(context.req)
  },
})

The resolver receives the original structural Pages Router context and may use the application request/response escape hatches. Its result is validated with auth’s exact AuthSessionView parser before crossing the SSR boundary.

Optional and protected pages

export const getServerSideProps = withSession(async ({ session }) => ({
  props: { title: session ? 'Dashboard' : 'Welcome' },
}))

export const getServerSideProps = requireSession(
  { redirectTo: '/login' },
  async ({ session }) => ({ props: { userId: session.user.id } }),
)

withSession passes AuthSessionView | null to the handler and injects the same value into successful props. requireSession provides a non-null session or a non-permanent same-origin redirect. Redirect and not-found results pass through unchanged.

Configuration and contracts

Handler props may not define their own session key. Absolute, protocol-relative, backslash, and header-injection redirect targets are rejected. The ISO-string-only session projection can initialize PlaystackAuthProvider without an unauthenticated flash.

App Router server boundaries

import { redirect } from 'next/navigation'

import { createAppRouterAuthHelpers } from '@playstack/auth-next/app'

const auth = createAppRouterAuthHelpers({
  resolveSession: () => resolveSessionViewFromCookies(),
})

export default async function AccountPage() {
  const session = await auth.requireSession({
    redirectTo: '/login',
    onUnauthenticated: (destination) => redirect(destination ?? '/login'),
  })

  return <Account userId={session.user.id} />
}

getSession() returns a validated optional session. requireSession() returns an authenticated session or invokes the supplied unauthenticated policy. withSession() and withRequiredSession() wrap route handlers while preserving their original request and route-context arguments, including promised dynamic params.

Without an unauthenticated policy, required access throws the stable playstack/auth-next/unauthenticated error. The application continues to own cookies, redirects, middleware, cache behavior, and authorization within server actions and protected operations.

Boundary

The adapter authenticates nothing by itself and does not replace authorization inside server operations. Its router-specific entrypoints preserve the distinct lifecycle of each router while the application owns request resolution and framework behavior.

API entry points and requirements

Reference snapshot: @playstack/auth-next@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.