Local Context Tree Structure

.brv/context-tree/
├── authentication/
│   └── context.md        # auto-generated domain overview
├── api-design/
│   └── context.md
└── database/
    └── context.md

.brv/context-tree/
├── authentication/
│   ├── context.md
│   ├── jwt-implementation/
│   │   └── context.md    # auto-generated topic overview
│   ├── oauth-flow/
│   │   └── context.md
│   └── session-management/
│       └── context.md
├── api-design/
│   ├── context.md
│   ├── rest-endpoints/
│   │   └── context.md
│   └── graphql-schema/
│       └── context.md
└── database/
    ├── context.md
    ├── user-models/
    │   └── context.md
    └── migration-strategy/
        └── context.md

.brv/context-tree/
└── authentication/
    ├── context.md
    └── jwt-implementation/
        ├── context.md
        ├── jwt_token_generation.md
        └── refresh-tokens/               # Subtopic
            ├── context.md                # auto-generated subtopic overview
            └── refresh_token_rotation.md

# Domain: authentication

## Purpose
Covers all authentication and authorization patterns used in this project.

## Scope
Included in this domain:
- JWT token generation and validation
- OAuth 2.0 flows
- Session management and refresh tokens

Excluded from this domain:
- API rate limiting (see api-design)
- Database user models (see database)

## Ownership
Backend team

## Usage
Reference when implementing login flows, token handling, or access control.

# Topic: jwt-implementation

## Overview
Patterns and conventions for JSON Web Token generation, validation, and rotation.

## Key Concepts
- Access tokens expire after 24 hours
- Refresh token rotation prevents replay attacks
- Token signing uses RS256 algorithm

## Related Topics
- authentication/oauth-flow
- database/user-models

# Subtopic: refresh-tokens

## Focus
Refresh token rotation strategy and revocation handling.

## Parent Relation
Part of jwt-implementation — covers the token renewal lifecycle.

---
children_hash: "a3f9c2..."
compression_ratio: 0.18
condensation_order: 2
covers:
  - context.md
  - jwt-implementation/_index.md
covers_token_total: 3400
summary_level: d2
token_count: 612
type: summary
---

Summary of this domain's knowledge: authentication covers JWT-based token generation
with RS256 signing, OAuth 2.0 authorization code flows, and session management via
httpOnly refresh tokens. Key conventions: 24-hour access token TTL, single-use refresh
rotation, tokens stored in PostgreSQL for revocation...

authentication/jwt-implementation/old_draft.md
  → _archived/authentication/jwt-implementation/old_draft.stub.md
  → _archived/authentication/jwt-implementation/old_draft.full.md

---
evicted_at: "2025-04-15T10:00:00Z"
evicted_importance: 22.4
original_path: "authentication/jwt-implementation/old_draft.md"
original_token_count: 890
points_to: "_archived/authentication/jwt-implementation/old_draft.full.md"
type: archive_stub
---

Describes an early-draft authentication flow that used symmetric HMAC-SHA256 signing
before the team standardized on RS256. Key entities: jwt_secret, sign(), verify()...

.brv/context-tree/
├── _manifest.json                    # auto-generated manifest
├── _index.md                         # auto-generated root summary
├── authentication/
│   ├── _index.md                     # auto-generated domain summary
│   ├── context.md                    # auto-generated domain overview
│   ├── jwt-implementation/
│   │   ├── _index.md                 # auto-generated topic summary
│   │   ├── context.md                # auto-generated topic overview
│   │   ├── jwt_token_generation.md
│   │   ├── jwt_token_generation.abstract.md   # auto-generated L0 abstract
│   │   ├── jwt_token_generation.overview.md   # auto-generated L1 overview
│   │   └── refresh-tokens/
│   │       ├── _index.md             # auto-generated subtopic summary
│   │       ├── context.md            # auto-generated subtopic overview
│   │       ├── refresh_token_rotation.md
│   │       ├── refresh_token_rotation.abstract.md
│   │       └── refresh_token_rotation.overview.md
└── _archived/
    └── authentication/
        └── jwt-implementation/
            ├── old_draft.stub.md     # searchable ghost cue
            └── old_draft.full.md    # lossless archive (not synced)

---
title: "JWT Token Generation"
summary: "Access and refresh token pair generation with RS256 signing and single-use rotation"
tags: ["auth", "jwt", "security"]
keywords: ["token", "access_token", "refresh_token", "RS256"]
related: ["authentication/session-management", "database/user-models/token-storage"]
createdAt: "2025-03-18T10:00:00Z"
updatedAt: "2025-04-02T14:30:00Z"
---

## Raw Concept

**Task:**
JWT token generation and rotation pattern

**Files:**
- src/auth/jwt.ts
- src/auth/refresh.ts

**Flow:**
Login request → Validate credentials → Generate access token → Generate refresh token → Store refresh in DB → Return token pair

## Narrative

### Structure
Access and refresh tokens are generated as a pair on every login.

### Rules
- Access tokens expire after 24 hours
- Refresh tokens expire after 7 days
- Refresh tokens are single-use with rotation

### Examples
```typescript
function generateTokens(userId: string) {
  const accessToken = jwt.sign(
    { userId, type: 'access' },
    process.env.JWT_SECRET,
    { expiresIn: '24h' }
  );

  const refreshToken = jwt.sign(
    { userId, type: 'refresh' },
    process.env.REFRESH_SECRET,
    { expiresIn: '7d' }
  );

  return { accessToken, refreshToken };
}
```

## Facts
- **jwt_secret**: Access tokens are signed with RS256 algorithm [convention]
- **refresh_token**: Refresh tokens are single-use and rotated on each renewal [convention]
- Token pairs are stored in the database for revocation tracking [project]

                importance ≥ 65            importance ≥ 85
  ┌───────┐ ──────────────────► ┌───────────┐ ──────────────► ┌──────┐
  │ draft │                     │ validated  │                 │ core │
  └───────┘ ◄────────────────── └───────────┘ ◄────────────── └──────┘
                importance < 35            importance < 60

related:
  - "authentication/session-management"
  - "api-design/rest-endpoints"
  - "database/user-models/token-storage"