@munchi_oy/nestjs-auth

Embedded NestJS authentication module for Munchi SDK consumers.

Overview

This package is a backend-only auth module intended to be embedded inside a NestJS consumer service.

It exposes a small Nest-friendly contract:

• AuthModule.register(...)
• AuthService.login(...)
• AuthService.verifyToken(...)
• POST /auth/login
• POST /auth/verify-token

The current implementation uses Clerk behind the scenes through @clerk/backend, but the consumer should code against the package contract instead of Clerk-specific response shapes.

Vision

The package is intentionally narrow.

• Keep the public API small and backend-oriented.
• Let the consumer call one embedded auth module instead of talking to Clerk directly.
• Map provider data into Munchi-owned auth types.
• Avoid building a second session system inside the SDK.
• Allow implementation changes behind the scenes in future versions with minimal consumer churn.

This package is not trying to be:

• a frontend auth SDK
• a redirect/login UI flow manager
• a session store
• a generic multi-provider plugin framework

Current behavior

Today the module does two things:

1. login(email, password) verifies credentials with Clerk and returns the mapped user
2. verifyToken(token) verifies a Clerk token and returns a mapped auth result

Current implementation notes:

• login(...) uses Clerk backend user lookup plus password verification
• verifyToken(...) uses Clerk token verification plus user fetch
• the package does not create or persist its own sessions
• the package does not expose Clerk SDK objects directly

Consumer usage

Module registration

import { Module } from "@nestjs/common";
import { AuthModule } from "@munchi_oy/nestjs-auth";

@Module({
  imports: [
    AuthModule.register({
      auth: {
        apiKey: process.env.AUTH_API_KEY!,
      },
    }),
  ],
})
export class AppModule {}

AUTH_API_KEY currently maps to the Clerk secret key.

Use built-in routes

The module ships its own controller under /auth.

POST /auth/login

{
  "email": "[email protected]",
  "password": "secret-password"
}

Example response:

{
  "user": {
    "id": "user_123",
    "email": "[email protected]",
    "name": "SDK User",
    "roles": ["member"],
    "tenantId": "tenant_456"
  }
}

POST /auth/verify-token

{
  "token": "clerk-token"
}

Example response:

{
  "provider": "auth",
  "tokens": {
    "accessToken": "clerk-token",
    "expiresAt": "2026-12-01T00:00:00.000Z"
  },
  "user": {
    "id": "user_123",
    "email": "[email protected]",
    "name": "SDK User",
    "roles": ["member"],
    "tenantId": "tenant_456"
  }
}

Inject AuthService directly

Consumers can ignore the built-in controller and wrap the service in their own routes.

import { Body, Controller, Post } from "@nestjs/common";
import { AuthService } from "@munchi_oy/nestjs-auth";

@Controller("internal-auth")
export class InternalAuthController {
  public constructor(private readonly authService: AuthService) {}

  @Post("login")
  public async login(
    @Body() body: { email: string; password: string },
  ) {
    return this.authService.login(body);
  }

  @Post("verify-token")
  public async verifyToken(
    @Body() body: { token: string },
  ) {
    return this.authService.verifyToken(body);
  }
}

Public contract

LoginInput

{
  email: string;
  password: string;
}

LoginResult

{
  user: AuthUser;
}

VerifyTokenInput

{
  token: string;
}

AuthenticationResult

{
  provider: "auth";
  tokens: {
    accessToken: string;
    refreshToken?: string;
    expiresAt?: string;
    scopes?: string[];
    idToken?: string;
    metadata?: Record<string, unknown>;
  };
  user: AuthUser;
}

Folder structure

Current source layout:

nestjs-auth/
  src/
    auth/
      auth.constants.ts
      auth.controller.ts
      auth.errors.ts
      auth.module.ts
      auth.service.ts
      auth.types.ts
    clerk/
      clerk.service.ts
    version.ts
  tests/
    auth.service.test.ts

Separation of responsibilities:

• src/auth: Nest module, DTOs, service, controller, errors
• src/clerk: Clerk-specific backend integration
• tests: package tests

How this package fits in the repo

This repository is a pnpm workspace with multiple publishable packages.

For this package:

• source lives in nestjs-auth/
• build output goes to nestjs-auth/dist/
• release commands are driven from the workspace root

Useful root scripts:

• pnpm build
• pnpm test:nestjs-auth
• pnpm release:nestjs-auth:patch
• pnpm release:nestjs-auth:minor
• pnpm release:nestjs-auth:major
• pnpm publish:nestjs-auth

Useful package-local scripts:

• pnpm build
• pnpm test
• pnpm test:watch
• pnpm test:coverage

Versioning

Current package version is defined in package.json.

Version updates are synchronized into src/version.ts during build through scripts/sync-version.mjs.

Recommended versioning intent:

• patch: internal fixes, no intended consumer contract change
• minor: additive API or behavior that should be backward compatible
• major: breaking contract or semantic changes, including provider-behavior changes that can affect consumers

Because the public contract is intentionally small, provider implementation details should be hidden where possible. If the provider behavior changes in a way that changes consumer expectations, prefer a major version bump.

Dependencies

Runtime:

• @clerk/backend

Peer dependencies expected from the consumer:

• @nestjs/common
• @nestjs/core
• reflect-metadata
• rxjs

Testing and verification

Common verification commands inside nestjs-auth:

pnpm dlx @biomejs/[email protected] check --write .
pnpm exec tsc -p tsconfig.build.json --noEmit
pnpm exec jest --config jest.config.js --runInBand

Important limitations

• Current login flow assumes email + password
• Current implementation is Clerk-backed
• Current implementation is backend-only
• No custom session storage is provided
• No frontend redirect/UI flow is managed here

Official Clerk references

• Clerk JavaScript Backend SDK overview
• Clerk verifyToken() reference