# swissoid-back

SwissOID authentication backend for Node.js applications. Provides reusable OIDC authentication components for integrating with SwissOID (Swiss eID).

## Features

- 🔐 Full OIDC Authorization Code Flow implementation
- 🍪 Session management with Redis
- 🔑 JWT verification with JWKS
- 🎯 Built for di-why dependency injection
- 📦 Reusable authentication components
- 🔄 Configurable via environment variables or appConfig

## Installation

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

## Requirements

- Node.js >= 18
- Redis server for session storage
- SwissOID client credentials

## Usage

### With express-knifey / graphql-knifey (Recommended)

swissoid-back integrates seamlessly with express-knifey's middleware system:

```typescript
import DiContainer, { mergeLDs } from 'di-why';
import { apolloSubgraphServerModularLDGen } from 'graphql-knifey';
import { swissoidAuthLoadDict } from 'swissoid-back';

// Define middleware configuration including OIDC routes
const middlewareConfig = {
  '/graphql': [
    { name: 'expressCorsMiddleware', priority: 90 },
    { name: 'expressCookieParserMiddleware', priority: 80 },
    { name: 'expressBodyParserMiddleware', priority: 70 },
    { name: 'expressGraphqlMiddleware', required: true, priority: -100 },
  ],
  '*': [
    // Add OIDC routes as global middleware
    { name: 'oidcStandardRoutesMiddleware', priority: 50 },
  ]
};

const diContainer = new DiContainer({
  load: mergeLDs(
    // GraphQL server with middleware config
    apolloSubgraphServerModularLDGen({
      resolvers,
      typeDefs,
      middlewareConfig
    }),

    // SwissOID authentication components
    swissoidAuthLoadDict,

    // Your other loaders...
  )
});
```

### Direct Express Usage

```typescript
import { swissoidAuthLoadDict } from 'swissoid-back';

// Load OIDC routes directly (this will mount them on the express app)
await diContainer.load('oidcStandardRoutes');
```

### AppConfig Integration

swissoid-back provides an appConfigMap that can be merged with your application's configuration:

```typescript
import { swissoidMergeAppConfigMap } from 'swissoid-back';

const merged = swissoidMergeAppConfigMap(yourAppConfigMap);
export type AppConfig = ReturnType<typeof merged>;
```

### Configuration

Create a `.env` file with the required configuration (see `.env.example` for all options):

```env
# 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

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379

# Session Configuration
SESSION_COOKIE_NAME=connect.sid
SESSION_SECRET=your-session-secret

# RP Configuration
RP_FRONTEND_URL=http://localhost:3000
COOKIE_DOMAIN=localhost
OIDC_REDIRECT_BASE_URL=http://localhost:3668
```

## Routes

The package provides the following OIDC routes when loaded:

- `GET /login` - Initiates OIDC authorization flow
- `POST /oidc/callback` - Handles OIDC callback from SwissOID
- `POST /oidc/finalize` - Completes authentication and sets session
- `GET /auth/status` - Returns current authentication status
- `POST /auth/logout` - Logs out the user

## Components

The `swissoidAuthLoadDict` includes:

- **redisClient**: Redis connection for session storage
- **sessionService**: Session management service
- **cookieManager**: Cookie handling utilities
- **oidcStandardRoutes**: Express router with OIDC endpoints
- **oidcStandardRoutesMiddleware**: Middleware-compatible version for express-knifey integration
- **swissoidAppConfigMap**: AppConfig map with priority 60

## Exports

```typescript
// Main LoadDict for di-why
import { swissoidAuthLoadDict } from 'swissoid-back';

// AppConfig utilities
import { swissoidMergeAppConfigMap } from 'swissoid-back';

// Individual loaders if needed
import {
  sessionService,
  cookieManager,
  oidcStandardRoutes,
  oidcStandardRoutesMiddleware
} from 'swissoid-back';
```

## License

MIT