npm package: @origins-digital/nestjs-shared-key
Description: Origins Digital NestJS Shared Key
Author: Origins Digital
Latest version: 3.1.4

# @origins-digital/nestjs-shared-key

A NestJS module for managing shared keys and JWT authentication using AWS Systems Manager Parameter Store.

> **Zod compatibility**: Shared key DTOs and validation are compatible with **Zod v4.x**.

## Installation

```bash
npm install @origins-digital/nestjs-shared-key
```

## Features

- Secure key management using AWS Systems Manager Parameter Store
- Caching of keys for improved performance
- Support for multiple JWT audiences (user, api, refresh)
- Type-safe key retrieval with Zod validation
- Environment-based configuration
- Internal JWT authentication support

## Usage

### Basic Setup

```typescript
import { Module } from '@nestjs/common';
import { SharedKeyModule } from '@origins-digital/nestjs-shared-key';
import { AWSSystemManagerModule } from '@origins-digital/nestjs-aws-ssm';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [ConfigModule, AWSSystemManagerModule, SharedKeyModule],
})
export class AppModule {}
```

### Using SharedKeyService

```typescript
import { Injectable } from '@nestjs/common';
import {
  SharedKeyService,
  JWTAudience,
} from '@origins-digital/nesjts-shared-key';

@Injectable()
export class AuthService {
  constructor(private readonly sharedKeyService: SharedKeyService) {}

  async validateToken(token: string, audience: JWTAudience) {
    const publicKey = await this.sharedKeyService.getPublicKey(audience);
    // Use the public key to validate the token
  }

  async getInternalAuthToken() {
    const jwt = await this.sharedKeyService.getInternalAuthJWT();
    // Use the internal JWT for authentication
  }
}
```

### Environment Configuration

The package expects the following environment variables:

```env
APP_ENV=development
AWS_REGION=us-east-1
```

### AWS Parameter Store Configuration

The package expects the following parameters in AWS Systems Manager Parameter Store:

- `${APP_ENV}_origins_backoffice_service_auth_sign_user_public_key`
- `${APP_ENV}_origins_backoffice_service_auth_sign_api_public_key`
- `${APP_ENV}_origins_backoffice_service_auth_sign_refresh_private_key`
- `${APP_ENV}_origins_internal_auth_jwt`

## API Reference

### SharedKeyService

```typescript
@Injectable()
export class SharedKeyService {
  constructor(
    private configService: ConfigService,
    private awsSystemManager: AWSSystemManagerService,
  ) {}

  @Cacheable({
    key: (args: any[]) => `auth:sig:${args[0]}:public:key`,
    ttlSeconds: 86400,
  })
  async getPublicKey(audience: JWTAudience): Promise<SharedKey | null>;

  @Cacheable({
    key: `origins:internal:auth:jwt`,
    ttlSeconds: 86400,
  })
  async getInternalAuthJWT(): Promise<SharedKey | null>;
}
```

### Types

```typescript
type JWTAudience = 'user' | 'api' | 'refresh';

interface SharedKey {
  kid?: string; // UUID
  key: string;
}
```

## Caching

The package uses `@origins-digital/cacheable` to cache keys:

- Public keys are cached for 24 hours (86400 seconds)
- Internal JWT is cached for 24 hours (86400 seconds)
- Cache keys are prefixed with `auth:sig:` for public keys and `origins:internal:auth:jwt` for internal JWT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.