@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

npm install @ogcio/pii-utils

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

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

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

Quick start (AWS)

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("[email protected]");
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)

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

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():

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("[email protected]");

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

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.

npm run benchmark

See benchmark/README.md for the full benchmark contract and candidate list.

Development

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