Nidhara – Security-First Auth Foundation for a Personal Finance & Growth Platform

Technical Appendix

Nidhara is an npm workspaces monorepo with three workspaces: a NestJS 11 backend using Prisma and PostgreSQL, a Next.js 16 frontend, and a Docusaurus documentation site. This case study covers the authentication and session foundation, which is the part built so far. The finance ledger and personal growth features are planned, not shipped.

Architecture

flowchart TD
    subgraph Mono ["Monorepo (npm workspaces)"]
        FE["frontend (Next.js 16)"]
        DOCS["docs-site (Docusaurus)"]
        BE["backend (NestJS 11)"]
    end

    subgraph Pipeline ["Backend Pipeline"]
        INT["ResponseInterceptor + Pino Logger"]
        AUTHC["AuthController"]
        APPC["AppController"]
        GUARD["JWT Strategy & Guards"]
        INT --> AUTHC
        INT --> APPC
        AUTHC --> GUARD
    end

    subgraph Services ["Application Services"]
        AUTHS["AuthService (Argon2, token rotation)"]
        TOK["AuthTokensService (JWT sign/verify)"]
        USERS["UsersService"]
        AUTHC --> AUTHS
        AUTHS --> TOK
        AUTHS --> USERS
    end

    subgraph Data ["PostgreSQL (Prisma)"]
        MODELS[("6 Models")]
        AUTHS --> MODELS
        USERS --> MODELS
    end

    BE --> Pipeline

Request flow: Client Request → ResponseInterceptor & Pino → Controller (dto/) → Service → PrismaService → PostgreSQL.

Data Model

Refresh Rotation Flow

1. On signin, the server issues a short-lived access token and an httpOnly refresh cookie, and stores a hash of the refresh token on a new AuthSession.
2. The client calls /auth/refresh with the cookie and its csrfToken.
3. The server verifies the refresh hash and the CSRF token against the session record.
4. On success, it issues a new access token and a new refresh token, and replaces the stored hash, so the old token cannot be used again.
5. A replayed token or a logout revokes the session, and a security event is recorded.

Scope & Status

The project is at prototype stage. The backend exposes 5 endpoints across 2 controllers and has one smoke-level test (app.controller.spec.ts). Passkey and security-question authentication, the sudo escalation endpoints, and all finance features are on the roadmap. The SudoSession and UserAccountSecurityState tables exist in the schema, but the flows that use them are not built yet.

By the Numbers