@krizaka/api-keys
API keys created, rotated, revoked and authenticated; shown once, only a hash kept.
Install
npm install @krizaka/api-keysAlso published as subpath exports: @krizaka/api-keys/testkit.
API keys for every Krizaka product. A key is <prefix>_<publicId>_<random>: the public id finds the record, only a SHA-256 of the random
part is stored, the whole key is shown once (when it is created or rotated), scopes and rules are data, a key must end, a rotated key
keeps working for a grace period, a revoked one stops at once, and every refusal has a stable code.
import { createApiKeys, pgApiKeyStore, apiKeysMigration } from "@krizaka/api-keys";
await db.query(apiKeysMigration("accounts")); // once, in your migrations
const keys = createApiKeys({ store: pgApiKeyStore(query), clock: { now: () => new Date() }, rules: { prefix: "yzk", scopes: ["checks:write", "reports:read"], secretBytes: 24, maxExpiryDays: 365, rotationGraceHours: 24, lastUsedEveryMinutes: 5 } });
const { key } = await keys.create(owner, { name: "Mon ERP", scopes: ["checks:write"], expiresInDays: 90 }, { maxActive: 5 });
const auth = await keys.authenticate(request.headers.get("authorization"), "checks:write"); // { ok: true, key } | { ok: false, code }What a product decides stays in the product: its scopes, how many keys a plan holds (maxActive), its rate limit, its audit trail, its HTTP answers.
Any store runs the contract kit: apiKeyStoreContract from @krizaka/api-keys/testkit.
Exports
The 17 names the package exports, read from its types.
| Name | Kind | What it is |
|---|---|---|
API_KEY_CODE | constant | |
ApiKeyCode | type | |
ApiKeyError | class | |
ApiKeyRecord | type | |
ApiKeyRules | type | The API-KEY ports (ADR-0011). |
ApiKeys | type | |
apiKeysMigration | function | The table of API keys. |
ApiKeyStore | type | |
ApiKeyView | type | What a person sees of a key: never the hash, never the secret. |
Authenticated | type | |
Clock | type | |
createApiKeys | function | API keys: created, authenticated, rotated, revoked. |
Created | type | |
memoryApiKeyStore | function | An in-memory store: the tests' adapter, and the reference the contract is written against. |
NewKey | type | |
pgApiKeyStore | function | PostgreSQL adapter (table api_keys, migration 0021). |
Query | type | The SQL runner this adapter needs: the app passes its own (no import from the app here). |
@krizaka/api-keys/testkit
| Name | Kind | What it is |
|---|---|---|
apiKeyStoreContract | function | What every ApiKeyStore adapter must do: the same behaviour behind the same port. |
Package
| Version on npm | 0.1.0 (npm) |
| Licence | Apache-2.0 |
| Node.js | >=22 |
| Dependencies | date-fns ^4.4.0 |
| Peer dependencies | vitest >=4 |
| Source | api-keys |
Changelog
0.1.0
Minor changes
- First release, extracted from Yomizaka: create, rotate (with a grace period), revoke and authenticate API keys behind a store port; memory and PostgreSQL stores, the migration, and the store contract kit.