@playstack/nest-auth

@playstack/nest-auth connects @playstack/auth session validation and its fixed CSRF transport to NestJS guards and decorators.

Install

After confirming preview access, install the package at your application's shared Playstack version:

npm install --save-exact @playstack/nest-auth@0.1.0-beta.1

Check the peer requirements below before choosing a runtime or provider.

Install and compose

PlaystackAuthModule.forRoot({
  sessions,
  allowedOrigins: ['https://app.example'],
})

Use forRootAsync({ imports, inject, useFactory }) when the session strategy depends on other Nest providers.

@UseGuards(PlaystackAuthGuard, PlaystackCsrfGuard)
@Post('/profile')
update(@CurrentSession() session: SessionClaims) {}

@Public()
@Get('/health')
health() {}

Configuration reference

PlaystackAuthGuard accepts the host-only cookie or a strict bearer token and attaches only SessionClaims as request.playstackSession. A validation failure thrown by the strategy, such as a revoked device, is answered with 401; retryable persistence failures keep their original error. PlaystackCsrfGuard validates Origin plus synchronizer token for cookie-authenticated unsafe methods; bearer requests do not use ambient browser credentials and bypass CSRF.

Split-origin cookie routes

When the page and the API are different origins, the page cannot read a CSRF cookie set on the API origin, so the synchronizer-token guards do not apply. PlaystackOriginGuard is the defence for that profile: an unsafe browser request must present an Origin from allowedOrigins and, when the browser sends it, a Sec-Fetch-Site that is not cross-site. A request with no Origin, no Fetch Metadata and no cookie carries no ambient credential and passes, so a CLI, a mobile app or a server can call the same routes with a bearer token or explicit credentials. isBrowserRequest(request) exposes that decision for controllers that choose a transport per client. A refusal answers 403 with { error: 'origin_not_allowed' }.

Registered devices via dependency injection

@playstack/devices is not a dependency of this package. Its service satisfies the DeviceSessionValidator contract from @playstack/auth, so the module accepts it through Nest injection and passes it to a session factory.

import { Module } from '@nestjs/common'
import { databaseSessions } from '@playstack/auth'
import { NEST_DEVICE_SESSION_VALIDATOR, PlaystackAuthModule } from '@playstack/nest-auth'

@Module({
  providers: [{ provide: NEST_DEVICE_SESSION_VALIDATOR, useValue: devices }],
  exports: [NEST_DEVICE_SESSION_VALIDATOR],
})
class DevicesModule {}

PlaystackAuthModule.forRoot({
  imports: [DevicesModule],
  sessions: ({ devices }) =>
    databaseSessions({ persistence, crypto, events, clock, ids, deviceValidator: devices, requireDevice: true }),
  allowedOrigins: ['https://app.example'],
})

With forRootAsync, inject the service and return it as devices, or export the provider from an imported module; either way the sessions factory receives it and NEST_AUTH_OPTIONS exposes the resolved validator. Register sessions.deviceRevocationHandler() for devices.device.revoked on the shared emitter so revoking a device revokes its sessions in the same transaction.

Composing guards

The application composes the guards; the package never installs one on its own. Name a default composition by transport profile and place PlaystackGuardStack where it belongs, install that composition globally with globalGuards: true and opt routes out with @Public(), or list your own layering of package guards, other Playstack bindings and application guards.

PlaystackAuthModule.forRoot({ sessions, allowedOrigins, guards: 'bearer' })

@UseGuards(PlaystackGuardStack)
@Controller('accounts')
export class AccountsController {}

// Your own order, mixing bindings and application guards:
PlaystackAuthModule.forRoot({
  sessions,
  allowedOrigins,
  guards: [PlaystackOriginGuard, TenantGuard, PlaystackAuthGuard, PlaystackAccountGuard],
})

'cookie' is PlaystackCsrfGuard then PlaystackAuthGuard; 'bearer' is PlaystackOriginGuard then PlaystackAuthGuard; playstackGuardStacks exports both for spreading into @UseGuards. The stack resolves each guard once from the application's providers, or constructs it with its dependencies when it is not registered, evaluates them in order, and stops at the first denial. A bad composition fails at bootstrap. Every guard stays exported for individual placement.

Boundary

The underlying SessionStrategy is the replacement seam. The adapter does not own users, accounts, provider normalization, persistence, or authorization, and it never installs a guard the application did not ask for. Applications control guard placement and ordering.

Authorization and credentials are separate surfaces

The package includes optional device-authorization and credential-route integration resources in addition to session/refresh/sign-out composition. Templates are application-owned wiring: configure registration policy, input validation, consent, CSRF/raw transport behavior, rate limits and required transactional adapters before enabling routes. Device and authorization-code success responses are not replayable recovery stores.

API entry points and requirements

Reference snapshot: @playstack/nest-auth@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.