npm package: @ogcio/pii-utils
Description: Utilities for handling Personally Identifiable Information (PII) in Node.js services.
Latest version: 0.1.0

# @ogcio/pii-utils

Utilities for handling Personally Identifiable Information (PII) in Node.js services.

Each utility is published as a separate subpath export so applications only import what they need.

## Prerequisites

- **Node.js >= 24**
- A pepper service implementation (e.g. the built-in AWS adapter, or a custom one)

## Installation

```bash
npm install @ogcio/pii-utils
```

If using the AWS Secrets Manager adapter, also install the SDK:

```bash
npm install @aws-sdk/client-secrets-manager
```

---

## pii-hasher

A one-way HMAC-SHA256 hasher for PII values. It produces deterministic, non-reversible hashes using a pepper fetched from a pluggable `PepperService`, allowing services to compare PII-derived identifiers without retaining the original plaintext.

### Import

```ts
import {
  createPiiHasher,
  createAwsPepperService,
} from "@ogcio/pii-utils/pii-hasher";
```

### Quick start (AWS)

```ts
import {
  createPiiHasher,
  createAwsPepperService,
} from "@ogcio/pii-utils/pii-hasher";
import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";

const pepperService = createAwsPepperService({
  secretName: "my-app/pii-pepper",
  client: new SecretsManagerClient({ region: "eu-west-1" }),
});

const hasher = createPiiHasher({
  pepperService,
  applicationId: "citizen-portal",
});

const { hash, pepperVersion } = await hasher.hash("user@example.com");
console.log(hash);          // 64-char hex string
console.log(pepperVersion); // e.g. "abc123-def456"

// When shutting down, stop background refresh timers
hasher.dispose();
```

### Quick start (custom provider)

```ts
import { createPiiHasher } from "@ogcio/pii-utils/pii-hasher";
import type { PepperService } from "@ogcio/pii-utils/pii-hasher";

const pepperService: PepperService = {
  async fetch() {
    const pepper = Buffer.from(process.env.PEPPER_KEY!, "base64");
    return { value: pepper, version: "env-v1" };
  },
};

const hasher = createPiiHasher({
  pepperService,
  applicationId: "citizen-portal",
});
```

### Configuration

`createPiiHasher` accepts a `PiiHasherConfig` object:

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `pepperService` | `PepperService` | Yes | — | Pluggable pepper provider (e.g. `createAwsPepperService()`). |
| `applicationId` | `string` | Yes | — | Application identifier mixed into every hash to scope outputs per application. |
| `cacheTtlSec` | `number` | No | `300` (5 min) | How long the pepper is cached locally before re-fetching. Minimum `30`. |

### PepperService interface

```ts
interface PepperService {
  fetch(): Promise<{ value: Buffer; version: string }>;
}
```

Any object implementing `fetch()` can be used. The return value must include the raw pepper bytes (`value`) and a version identifier (`version`).

### AWS adapter

`createAwsPepperService` creates a `PepperService` backed by AWS Secrets Manager:

| Option | Type | Required | Description |
| --- | --- | --- | --- |
| `secretName` | `string` | Yes | AWS Secrets Manager secret name. |
| `client` | `SecretsManagerClient` | Yes | Pre-configured AWS SDK client. |

The secret value should be a **plain base64-encoded string** (not JSON). The adapter decodes it and uses the AWS response `VersionId` as the pepper version.

### How hashing works

Each call to `hasher.hash(value)` performs the following:

1. Retrieves (or uses a cached) pepper via the configured `PepperService`.
2. Computes `HMAC-SHA256(pepper, applicationId + "\0" + value)`.
3. Returns the digest as a 64-character lowercase hex string together with the pepper version.

The null-byte separator prevents ambiguous concatenation between the application ID and the value.

### Warmup

The pepper is fetched lazily on the first `hash()` call. To avoid that initial latency and detect errors early (for example during application startup), call `warmup()`:

```ts
const hasher = createPiiHasher({
  pepperService,
  applicationId: "citizen-portal",
});

await hasher.warmup(); // fetches + caches the pepper, starts the background refresh timer

// first hash() is now served from cache with no network call
const { hash } = await hasher.hash("user@example.com");
```

`warmup()` throws if the pepper cannot be fetched, so any connectivity or permission problems surface immediately at startup rather than on the first user request. It can only be called once per hasher instance — calling it again throws an error.

### Pepper caching

The pepper is cached in memory for the duration of `cacheTtlSec`. A background timer proactively refreshes the cache 10 seconds before expiry so that hot-path calls never block on a network fetch. Background refresh failures are silently suppressed — the existing cached value continues to be used until it expires.

Call `hasher.dispose()` during graceful shutdown to clear the refresh timer and avoid leaked handles.

### Exported types

```ts
import type {
  PiiHasher,
  PiiHasherConfig,
  HashResult,
  PepperService,
  AwsPepperServiceConfig,
} from "@ogcio/pii-utils/pii-hasher";
```

| Type | Description |
| --- | --- |
| `PiiHasher` | Interface returned by `createPiiHasher` with `hash()`, `warmup()`, and `dispose()` methods. |
| `PiiHasherConfig` | Configuration object accepted by `createPiiHasher`. |
| `HashResult` | Object with `hash` (hex string) and `pepperVersion` (string). |
| `PepperService` | Interface for pluggable pepper providers. |
| `AwsPepperServiceConfig` | Configuration object accepted by `createAwsPepperService`. |

---

## Benchmark

A benchmark harness is included under `benchmark/` to compare HMAC and PBKDF2 candidates against the default HMAC-SHA256 implementation. It is not published as part of the package.

```bash
npm run benchmark
```

See [`benchmark/README.md`](benchmark/README.md) for the full benchmark contract and candidate list.

## Development

```bash
npm run build    # Compile TypeScript
npm run test     # Run tests with coverage
```