swissoid-back/README.md

# swissoid-back

SwissOID authentication package for Node.js backends. Provides reusable authentication components for integrating SwissOID (OpenID Connect) authentication into Node.js applications.

## Features

- 🔐 Complete OIDC Authorization Code Flow implementation
- 🍪 Secure cookie-based session management
- 🔑 JWT verification with JWKS support
- 📦 Dependency Injection ready (di-why compatible)
- 🚀 TypeScript support with full type definitions
- ⚡ Redis-based session storage

## Installation

```bash
npm install swissoid-back
```

## Usage

### Basic Setup with Dependency Injection

```typescript
import {
  oidcRoutesLDEGen,
  swissoidSessionServiceLDEGen,
  cookieManagerLDEGen,
  swissoidJWTVerifierLDEGen,
  redisClientLDEGen
} from 'swissoid-back';
import DiContainer from 'di-why';

const container = new DiContainer({
  load: {
    // Redis client for session storage
    redisClient: redisClientLDEGen(),

    // Session service
    sessionService: swissoidSessionServiceLDEGen(),

    // Cookie manager
    cookieManager: cookieManagerLDEGen({
      domain: '.example.com',
      sessionName: 'app_session'
    }),

    // JWT verifier
    jwtVerifier: swissoidJWTVerifierLDEGen(),

    // OIDC routes
    oidcRoutes: oidcRoutesLDEGen({
      clientId: 'your-client-id',
      cookieDomain: '.example.com'
    })
  }
});
```

### Express Integration

```typescript
import express from 'express';
import cookieParser from 'cookie-parser';

const app = express();

// Required middleware
app.use(cookieParser());

// Mount OIDC routes
const oidcRoutes = await container.get('oidcRoutes');
app.use(oidcRoutes);

// Routes provided:
// GET  /login           - Initiates OIDC flow
// POST /oidc/callback   - Handles callback from IdP
// GET  /oidc/finalize   - Sets cookies in first-party context
// GET  /auth/status     - Returns authentication status
// GET  /auth/userinfo   - Returns user information
// GET  /auth/logout     - Destroys session
// POST /auth/logout     - Destroys session (JSON response)
```

### Configuration

Required environment variables:

```bash
# SwissOID Configuration
SWISSOID_ISSUER=https://api.swissoid.com
SWISSOID_CLIENT_ID=your-client-id
SWISSOID_CLIENT_SECRET=your-client-secret
SWISSOID_TOKEN_ENDPOINT=https://api.swissoid.com/token
SWISSOID_JWKS_URI=https://api.swissoid.com/.well-known/jwks.json
SWISSOID_AUTHORIZE_ENDPOINT=https://api.swissoid.com/authorize

# RP Configuration
RP_CALLBACK_URL=https://your-app.com/oidc/callback
RP_COOKIE_DOMAIN=.your-app.com
RP_FRONTEND_URL=https://app.your-app.com

# Session Configuration
SESSION_COOKIE_NAME=app_session
SESSION_SECRET=your-session-secret
STATE_SIGNING_SECRET=your-state-signing-secret

# Redis
REDIS_URL=redis://localhost:6379
```

### Manual Usage (without DI)

```typescript
import { createOIDCRoutes, SwissOIDSessionService, CookieManager } from 'swissoid-back';
import Redis from 'ioredis';

// Create Redis client
const redisClient = new Redis('redis://localhost:6379');

// Create session service
const sessionService = new SwissOIDSessionService(redisClient, console);

// Create cookie manager
const cookieManager = new CookieManager({
  domain: '.example.com',
  sessionName: 'app_session',
  secureCookie: true,
  sameSite: 'lax'
});

// Create OIDC routes
const oidcRoutes = createOIDCRoutes({
  logger: console,
  sessionService,
  redisClient,
  issuer: 'https://api.swissoid.com',
  clientId: 'your-client-id',
  // ... other config
});

app.use(oidcRoutes);
```

## API Reference

### Components

- **oidcRoutesLDEGen**: Loader for OIDC route handlers
- **swissoidSessionServiceLDEGen**: Loader for session management service
- **cookieManagerLDEGen**: Loader for cookie operations
- **swissoidJWTVerifierLDEGen**: Loader for JWT verification
- **redisClientLDEGen**: Loader for Redis client

### Types

```typescript
interface OIDCConfig {
  issuer: string;
  clientId: string;
  clientSecret?: string;
  tokenEndpoint: string;
  jwksUri: string;
  authorizeEndpoint: string;
  callbackUrl: string;
  cookieDomain: string;
  frontendUrl: string;
  sessionCookieName: string;
  sessionSecret: string;
  stateSigningSecret: string;
}

interface SessionData {
  sub: string;
  email?: string;
  name?: string;
  iat: number;
  exp: number;
  createdAt?: number;
  lastAccessedAt?: number;
  metadata?: Record<string, any>;
}
```

## License

MIT