@heavybit/shared-lib 2.1.0 → 2.7.0

package/README.md

@@ -32,8 +32,8 @@ npx tsc --noEmit
 | Import path | What it holds |
 |---|---|
 | `@heavybit/shared-lib` | Root: `types`, `common`, `identity`, `access`, `validation`, `logging`, `config`, `contracts`, `alerting` (no optional peers) |
-| `@heavybit/shared-lib/express` | `correlationMiddleware`, `correlationId`, `validate`, `asyncHandler`, `errorHandler`, `notFoundHandler`, `ok`, `created`, `okPage`, gateway auth guards, health and security middleware |
-| `@heavybit/shared-lib/http` | SSRF-guarded `safeFetch` |
+| `@heavybit/shared-lib/express` | `correlationMiddleware`, `correlationId`, `validate`, `asyncHandler`, `errorHandler`, `notFoundHandler`, `ok`, `created`, `okPage`, gateway auth guards, `createInternalCallerGuards`, health and security middleware |
+| `@heavybit/shared-lib/http` | SSRF-guarded `safeFetch` (service-to-service calls use root `createInternalClient`) |
 | `@heavybit/shared-lib/messaging` | RabbitMQ connection, publisher, consumer, RPC, outbox, idempotency, topology |
 | `@heavybit/shared-lib/cache` · `/database` · `/knex` · `/rate-limit` · `/socket` · `/security` · `/metrics` · `/scheduling` · `/testing` | As named |
 
@@ -98,3 +98,164 @@ await runWithContext({ correlationId: msg.correlationId, service: 'worker' }, ()
   `[REDACTED]` at any depth (except `errorCode`, `statusCode`, `countryCode`, `currencyCode`, `postalCode`,
   `zipCode`); phone numbers are masked to their last 4 digits.
 
+
+### Gateway identity v2 and route guards (`identity`, `express`)
+
+The gateway signs each request's identity; services verify it before trusting anything.
+
+```ts
+import { defineIdentityProtocol, defineStepUpScopes } from '@heavybit/shared-lib';
+import { authenticateFromGateway, createStepUpGuards, requirePermission, requireOtpVerified } from '@heavybit/shared-lib/express';
+
+// App binding (lives in the app's contracts package, not here):
+const protocol = defineIdentityProtocol({
+  domain: 'myapp-gateway-identity:v2',          // domain separator: two apps never verify each other
+  scopeHeaders: { tenant: 'x-tenant-id' },       // → req.user.scopes.tenant
+  attrHeaders: { tenantSlug: 'x-tenant-slug' },  // → req.user.attrs.tenantSlug
+});
+const stepUpScopes = defineStepUpScopes({ 'record-delete': {}, 'secret-rotate': { singleUse: true } });
+const { requireStepUp, declaredStepUpRoutes } = createStepUpGuards({ catalogue: stepUpScopes }); // window 5 min
+
+router.use(authenticateFromGateway({ protocol, logger, onRejected: publishSecurityEvent })); // secret = env GATEWAY_SIGNING_SECRET (≥ 32 chars)
+router.delete('/records/:id', requirePermission('records.delete'), requireStepUp('record-delete', 'DELETE /records/:id'), controller.remove);
+```
+
+- **Signature:** `x-gateway-signature: v2=<hex>` = HMAC-SHA256 over `[domain, METHOD, path (no query), x-gateway-ts, …identity headers]`
+  (JSON-array encoded) in this order: `x-user-id, x-user-email, <mapped scope headers>, <mapped attr headers>,
+  x-user-roles, x-user-permissions, x-is-superadmin, x-otp-verified, x-step-up-at, x-session-id, x-user-scopes, x-user-attrs`.
+  Missing headers sign as empty strings. `x-gateway-ts` and `x-step-up-at` are epoch milliseconds.
+- **Rejected (401 `UNAUTHENTICATED`):** missing signature, wrong version, timestamp > 30 s old or > 5 s ahead,
+  another method/path/secret/domain, any tampered header. No `x-user-id` → anonymous (`optionalAuthFromGateway` continues).
+- **Guards:** `requirePermission(...)` (any), `requireAllPermissions([...])`, `requireRole`, `requireOtpVerified()`
+  → 403 `FORBIDDEN`; a signed super admin passes every permission guard. `requireStepUp(scope)` → 403
+  `STEP_UP_REQUIRED` with `{ scope }` unless `stepUpAt` is within the window. Single-use proofs are consumed by the gateway.
+- **Gateway side:** `stripProtectedHeaders(req.headers, protocol)` on ingress, then `signedIdentityHeaders({ user, method, path, secret, protocol })`.
+- **Tests:** `identityHeaders({ user, secret, protocol, method, path })` from `/testing`.
+
+### Internal service calls (`common`, `express`)
+
+Each service has its own credential; each internal route lists its callers.
+
+```ts
+import { assertInternalServiceAuthConfigured, createInternalClient } from '@heavybit/shared-lib';
+import { createInternalCallerGuards } from '@heavybit/shared-lib/express';
+
+assertInternalServiceAuthConfigured({ calls: true, serves: true }); // throws in staging/production if missing
+
+// Serving side (credentials = env INTERNAL_SERVICE_CREDENTIALS, {"caller-name":"<secret>"}):
+const { requireInternalCaller } = createInternalCallerGuards({ pathPrefix: '/internal', logger });
+router.get('/internal/records/:id', requireInternalCaller(['billing-service']), controller.get);
+
+// Calling side (caller = env INTERNAL_SERVICE_NAME + INTERNAL_SERVICE_CREDENTIAL):
+const records = createInternalClient({ target: 'records-service', baseUrl: env.RECORDS_INTERNAL_URL, logger });
+try {
+  const record = await records.get('/records/01J…', { schema: recordSchema });
+} catch (error) {
+  if (error instanceof records.UnavailableError) { /* down: degrade or 503 */ } else throw error; // 4xx: AppError with remote code
+}
+```
+
+- **Guard:** 401 `UNAUTHENTICATED` (missing/unknown name, wrong secret; constant-time), 403 `FORBIDDEN` (known caller
+  not listed, or any request outside `pathPrefix`). Sets `req.internalCaller`. Logs reason, caller and path only.
+- **Client:** timeout 3 s per attempt; GET retried twice (100 ms, 400 ms) on network errors, timeouts and 502/503/504;
+  breaker opens after 5 unavailable calls for 30 s, then one trial. Network/timeout/5xx/open breaker/unreadable or
+  schema-mismatched body → `{Target}UnavailableError` (503). 4xx → `AppError` with the remote status, code, message, errors.
+- **Headers sent:** `x-internal-service-name`, `x-internal-service-secret`, `x-correlation-id` (from the request
+  context), `idempotency-key` (when given) and `identityHeaders` unchanged. Gateway signatures are bound to method and
+  path, so re-sign the user's identity for the exact internal call with `signedIdentityHeaders`.
+
+### Config, Redis keyspace and rate-limit keys (`config`, `cache`, `rate-limit`)
+
+```ts
+import { z } from 'zod';
+import { loadEnv, createRedisKeyspace, rateLimitKey, sensitivePart } from '@heavybit/shared-lib';
+import { createCache, createRedisClient, setWithTtl } from '@heavybit/shared-lib/cache';
+
+// Base env (NODE_ENV, PORT, SERVICE_NAME, DB_*, REDIS_*, RABBITMQ_*, QUEUE_PREFIX, CACHE_KEY_PREFIX,
+// GATEWAY_SIGNING_SECRET, LOG_LEVEL, INTERNAL_SERVICE_*) + the service's own. Bad config → names on stderr, exit 1.
+export const config = loadEnv(z.object({ UPSTREAM_INTERNAL_URL: z.string().url() }));
+
+const ks = createRedisKeyspace({ app: APP_SLUG, service: config.SERVICE_NAME, env: config.CACHE_KEY_PREFIX });
+const redis = createRedisClient(config, { logger });          // no keyPrefix: the keyspace prefixes
+const cache = createCache({ redis, keyspace: ks, logger });
+await cache.set(ks.key('widget', id), widget, { ttlSec: 300 }); // TTL required, > 0
+await setWithTtl(redis, ks.key('otp', sensitivePart(email)), hash, 600);
+const key = rateLimitKey(ks, { scope: 'sign-in', ip: req.ip, email });
+```
+
+- Keys read `{app}:{env}:{service}:{purpose}:…`; the app slug is the caller's parameter. In staging and
+  production a missing `CACHE_KEY_PREFIX` stops startup (both `loadEnv` and `createRedisKeyspace`).
+- Parts are encoded (`:`, `*`, `?`, `[`, `]` cannot add segments or widen a SCAN). Parts that are long,
+  email-like, phone-like or wrapped in `sensitivePart` are hashed to `h.<sha256>`.
+- No `KEYS`/`FLUSH*` helpers exist; scan with `ks.pattern(purpose)` and `SCAN` if you must.
+- `createLock(redis, prefix)` takes a string prefix: pass `` `${ks.key('lock')}:` `` so its keys stay inside the
+  keyspace. `RedisIdempotencyStore(redis, keyspace)` builds its keys from the keyspace itself.
+
+### Messaging: envelope, outbox, consumers, DLQ (`messaging`)
+
+```ts
+// container.ts — app slug, prefix and service always come from config
+const messaging = createMessaging({ url: amqpUrlFromEnv(config), app: APP_SLUG, prefix: config.QUEUE_PREFIX, service: config.SERVICE_NAME });
+const relay = new OutboxRelay({ db, bus: messaging.publisher, onMetrics: (m) => lagGauge.set(m.lagMs) });
+
+// publish: stage in the same transaction as the change; the relay publishes after commit
+await db.transaction(async (tx) => { await repo.insert(ctx, row, { tx }); await enqueueOutbox(tx, 'thing.created', { tenantId, thingId: row.id }); });
+
+// consume: validated, de-duplicated in the handler's transaction, scope and correlation restored
+await messaging.consumer.subscribe({ queue: 'thing-created', bindings: [{ exchange: 'events', routingKey: 'thing.created' }],
+  schema, dedupe: new ProcessedEventsDeduper(db), scopeFrom: (d) => ({ tenantId: d.tenantId }),
+  handler: async ({ data, tx, scope }) => service.onCreated(scope!, data, tx!) });
+```
+
+- Envelope `{ routingKey, data: { ...payload, eventId, version, actorUserId? }, timestamp }`; AMQP `messageId` =
+  `eventId`, persistent JSON, header `x-correlation-id`.
+- Names: exchanges `{app}.{prefix}.events` (topic) / `.commands` (direct); queues `{prefix}.{service}.{purpose}`;
+  per-service DLX `{app}.{prefix}.{service}.dlx` → `{queue}.dlq`; retry queues `{queue}.retry.{ms}`.
+- Consumer: manual ack; invalid JSON/payload/scope → DLQ at once; handler errors retry after 2, 4, 8, 16 s
+  (`maxAttempts` 5) then DLQ; `NonRetryableError` → DLQ at once. `BaseConsumer` is the class form.
+- Relay: batches of 100 `FOR UPDATE SKIP LOCKED`, marks `published_at` after the broker confirm, keeps unroutable
+  commands pending, backs off exponentially while the broker is down.
+- `publisher.scheduleDelayed(queue, payload, delayMs)` for delayed delivery (bucketed per-message TTL).
+
+### Data access: Drizzle, scopes, pagination, migrations (`database`, `knex`)
+
+**Repositories use Drizzle through these bases; raw scoped queries and Knex in `src/` are forbidden; Knex is
+for migrations and seeds only.**
+
+```ts
+import { createDb, defineScope, definePlatformScope, OwnerScope, ScopedRepository, knexConfig } from '@heavybit/shared-lib/database';
+import { parseCursorQuery } from '@heavybit/shared-lib';
+
+// container.ts — no module-level singleton
+const { db, ping, close } = createDb({ env: config, schema });
+
+// Scope bindings are app parameters (the app's contracts package defines its own)
+const workspaceScope = defineScope({ name: 'workspace', column: 'workspace_id', contextKey: 'workspaceId' });
+const ownerScope = new OwnerScope({ name: 'owner', column: 'user_id' });
+const platformScope = definePlatformScope({ name: 'platform', column: 'workspace_id', predicate: (u: AuthUser) => u.isSuperAdmin });
+
+class NoteRepository extends ScopedRepository<typeof notes, ScopeContext<'workspaceId'>> {
+  findByTitle(ctx: ScopeContext<'workspaceId'>, title: string, tx?: DbExecutor) {
+    return this.executor(tx).select().from(this.table).where(this.scoped(ctx, eq(this.table.title, title)));
+  }
+}
+const notesRepo = new NoteRepository(db, notes, workspaceScope);
+const page = await notesRepo.findPage(ctx, { ...parseCursorQuery(req.query), orderBy: { column: 'created_at' } });
+await db.transaction(async (tx) => notesRepo.insert(ctx, row, { tx }));
+
+// knexfile.js
+module.exports = knexConfig(config); // ./migrations, ./seeds, .cjs only
+```
+
+- `ScopedRepository` methods: `findById` (null when absent or out of scope), `findMany`, `findPage`, `count`,
+  `insert` (stamps the scope column; a row naming another scope → 403 `SCOPE_MISMATCH`), `update` (refuses to
+  change the scope column, `SCOPE_IMMUTABLE`) and `delete`. Every method takes the scope context first and an
+  optional `{ tx }` last. Subclasses build WHERE clauses only with `this.scoped(ctx, ...)`.
+- A missing scope value is 403 `SCOPE_REQUIRED` (`OWNER_REQUIRED` for an owner scope). A platform grant comes only
+  from `platformScope.authorize(identity)` (403 `PLATFORM_SCOPE_DENIED` otherwise); its queries still name the scope
+  column (`IS NOT NULL`) and inserts must carry the scope value.
+- Pagination: `parseCursorQuery` (limit 1–100, default 20), `encodeCursor`/`decodeCursor` (opaque base64url of
+  `{ sortKey, id }`; bad cursors → 422), `buildCursorPage`.
+- Migrations (`/knex`): `outboxColumns(t, knex)` (incl. `exchange`, `correlation_id`), `processedEventsColumns(t, knex)` (unique `consumer` + `event_id`),
+  `schedulerRunsColumns(t, knex)` (unique `job` + `run_key`), `scopedIndex(t, scopeColumn, cols)` (always leads with
+  the scope column). Matching Drizzle tables: `outboxTable`, `processedEventsTable`, `schedulerRunsTable`.

package/dist/cjs/access/index.js

@@ -26,25 +26,33 @@ function grants(granted, required) {
         return true;
     return granted.endsWith('.*') && required.startsWith(granted.slice(0, -1));
 }
-/** True when the user holds at least one of `required`. */
+/** True when the user holds at least one of `required`. A super admin holds every permission. */
 function hasPermission(user, ...required) {
     if (!user)
         return false;
+    if (user.isSuperAdmin)
+        return true;
     return required.some((perm) => user.permissions.some((g) => grants(g, perm)));
 }
+/** True when the user holds every one of `required`. A super admin holds every permission. */
 function hasAllPermissions(user, ...required) {
     if (!user)
         return false;
+    if (user.isSuperAdmin)
+        return true;
     return required.every((perm) => user.permissions.some((g) => grants(g, perm)));
 }
+/** True when the user has at least one of `roles`. Prefer permission checks; roles are coarse. */
 function hasRole(user, ...roles) {
     return !!user && roles.some((role) => user.roles.includes(role));
 }
+/** Returns the user, or throws UnauthorizedError (401) when there is none. */
 function requireUser(user) {
     if (!user)
         throw new errors_js_1.UnauthorizedError();
     return user;
 }
+/** Returns the user when they hold any of `required` (super admin always does); throws 401/403 otherwise. */
 function assertPermission(user, ...required) {
     const u = requireUser(user);
     if (!hasPermission(u, ...required))

package/dist/cjs/access/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/access/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/access/index.ts"],"names":[],"mappings":"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"}

package/dist/cjs/approvals/index.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPROVAL_STATES = void 0;
+exports.canTransition = canTransition;
+exports.assertTransition = assertTransition;
+exports.isTerminalApprovalState = isTerminalApprovalState;
+exports.assertCanDecide = assertCanDecide;
+exports.assertCanCancel = assertCanCancel;
+exports.approvalExpiresAt = approvalExpiresAt;
+exports.createApprovalPolicy = createApprovalPolicy;
+const index_js_1 = require("../access/index.js");
+const errors_js_1 = require("../common/errors.js");
+/**
+ * Two-person approval state machine. A requester asks for a sensitive operation; a different person who
+ * holds both the operation's permission and the app's "decide" permission approves or rejects it; the
+ * approved operation is then executed once (or fails). Pending requests expire after a TTL.
+ *
+ * ```
+ * pending ──► approved ──► executed
+ *    │            └──────► failed
+ *    ├──► rejected
+ *    ├──► cancelled
+ *    └──► expired
+ * ```
+ *
+ * App values (the decide permission and the TTL) are passed in through {@link createApprovalPolicy}.
+ */
+/** Every approval state. */
+exports.APPROVAL_STATES = ['pending', 'approved', 'rejected', 'cancelled', 'expired', 'executed', 'failed'];
+const TRANSITIONS = Object.freeze({
+    pending: ['approved', 'rejected', 'cancelled', 'expired'],
+    approved: ['executed', 'failed'],
+    rejected: [],
+    cancelled: [],
+    expired: [],
+    executed: [],
+    failed: [],
+});
+/**
+ * True when `from → to` is an allowed move.
+ *
+ * @example canTransition('pending', 'approved') // true
+ */
+function canTransition(from, to) {
+    return TRANSITIONS[from]?.includes(to) ?? false;
+}
+/**
+ * Throws unless `from → to` is allowed.
+ *
+ * @throws ConflictError (`APPROVAL_INVALID_TRANSITION`).
+ */
+function assertTransition(from, to) {
+    if (!canTransition(from, to)) {
+        throw new errors_js_1.ConflictError(`This request can no longer move from ${from} to ${to}`, { code: 'APPROVAL_INVALID_TRANSITION' });
+    }
+}
+/** True when the state allows no further moves. */
+function isTerminalApprovalState(state) {
+    return TRANSITIONS[state].length === 0;
+}
+function assertPending(approval, now) {
+    if (approval.state !== 'pending') {
+        throw new errors_js_1.ConflictError('This request has already been decided', { code: 'APPROVAL_NOT_PENDING' });
+    }
+    if (approval.expiresAt && new Date(approval.expiresAt).getTime() <= now.getTime()) {
+        throw new errors_js_1.ConflictError('This request has expired', { code: 'APPROVAL_EXPIRED' });
+    }
+}
+/**
+ * Throws unless `approver` may approve or reject `approval`: it is pending and not expired, the approver
+ * is not the requester (even a super admin cannot approve their own request), and holds both the
+ * operation permission and `decidePermission`.
+ *
+ * @param approval The request.
+ * @param approver The deciding user.
+ * @param decidePermission The app's "may decide approvals" permission.
+ * @param now Clock (tests).
+ * @throws ConflictError (`APPROVAL_NOT_PENDING`, `APPROVAL_EXPIRED`) or ForbiddenError
+ *   (`APPROVAL_SELF_DECISION`, `APPROVAL_FORBIDDEN`).
+ */
+function assertCanDecide(approval, approver, decidePermission, now = new Date()) {
+    assertPending(approval, now);
+    if (approver.id === approval.requesterUserId) {
+        throw new errors_js_1.ForbiddenError('You cannot decide your own request', { code: 'APPROVAL_SELF_DECISION' });
+    }
+    if (!(0, index_js_1.hasAllPermissions)(approver, approval.operationPermission, decidePermission)) {
+        throw new errors_js_1.ForbiddenError('You do not have permission to decide this request', { code: 'APPROVAL_FORBIDDEN' });
+    }
+}
+/**
+ * Throws unless `user` may cancel `approval`: only the requester, and only while it is pending.
+ *
+ * @throws ConflictError (`APPROVAL_NOT_PENDING`) or ForbiddenError (`APPROVAL_NOT_REQUESTER`).
+ */
+function assertCanCancel(approval, user) {
+    if (user.id !== approval.requesterUserId) {
+        throw new errors_js_1.ForbiddenError('Only the person who made this request can cancel it', { code: 'APPROVAL_NOT_REQUESTER' });
+    }
+    if (approval.state !== 'pending') {
+        throw new errors_js_1.ConflictError('This request has already been decided', { code: 'APPROVAL_NOT_PENDING' });
+    }
+}
+/**
+ * When a request made at `from` expires.
+ *
+ * @param ttlSeconds Positive lifetime in seconds.
+ * @param from Creation time (default now).
+ * @returns The expiry instant.
+ * @example approvalExpiresAt(3600, new Date('2026-01-01T00:00:00Z')) // 2026-01-01T01:00:00Z
+ */
+function approvalExpiresAt(ttlSeconds, from = new Date()) {
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)
+        throw new RangeError('Approval TTL must be a positive number of seconds');
+    return new Date(from.getTime() + ttlSeconds * 1000);
+}
+/**
+ * Binds the approval rules to an app's decide permission and TTL.
+ *
+ * @param options Decide permission and TTL.
+ * @returns The bound policy.
+ * @example const approvals = createApprovalPolicy({ decidePermission: 'requests.decide', ttlSeconds: 86_400 });
+ */
+function createApprovalPolicy(options) {
+    if (!options.decidePermission)
+        throw new RangeError('An approval policy needs a decide permission');
+    approvalExpiresAt(options.ttlSeconds); // validates the TTL up front
+    return Object.freeze({
+        decidePermission: options.decidePermission,
+        ttlSeconds: options.ttlSeconds,
+        canTransition,
+        assertTransition,
+        assertCanDecide: (approval, approver, now) => assertCanDecide(approval, approver, options.decidePermission, now),
+        assertCanCancel,
+        expiresAt: (from) => approvalExpiresAt(options.ttlSeconds, from),
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/approvals/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/approvals/index.ts"],"names":[],"mappings":"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"}

package/dist/cjs/audit/index.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAuditEvent = exports.MAX_USER_AGENT_LENGTH = void 0;
+exports.createAuditEventBuilder = createAuditEventBuilder;
+const phone_js_1 = require("../common/phone.js");
+const time_js_1 = require("../common/time.js");
+const redact_js_1 = require("../logging/redact.js");
+/** User-agent strings are cut to this length. */
+exports.MAX_USER_AGENT_LENGTH = 255;
+/** Stable JSON form for deep comparison (object keys sorted; Dates as ISO strings). */
+function canonical(value) {
+    return JSON.stringify(value ?? null, (_key, v) => {
+        if (v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date)) {
+            return Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)));
+        }
+        return v;
+    });
+}
+function diff(before, after, classifier) {
+    const changes = {};
+    const redactedFields = [];
+    const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
+    for (const key of keys) {
+        const was = before[key] ?? null;
+        const now = after[key] ?? null;
+        if (canonical(was) === canonical(now))
+            continue;
+        if (classifier.isSecret(key)) {
+            redactedFields.push(key);
+            continue;
+        }
+        const clean = (value) => classifier.isPhone(key) && (typeof value === 'string' || typeof value === 'number') ? (0, phone_js_1.maskPhone)(String(value)) : (0, redact_js_1.redactValue)(value, classifier);
+        changes[key] = { before: clean(was), after: clean(now) };
+    }
+    return { changes, redactedFields };
+}
+/**
+ * Creates an audit-event builder with the app's extra redaction words.
+ *
+ * @param options Extra redaction words.
+ * @returns `buildAuditEvent` bound to that list.
+ * @example const buildAudit = createAuditEventBuilder({ redactKeys: ['nationalId'] });
+ */
+function createAuditEventBuilder(options = {}) {
+    const classifier = (0, redact_js_1.createKeyClassifier)(options.redactKeys ?? []);
+    return (input) => {
+        if (!input.action || !input.entityType)
+            throw new RangeError('Audit events need an action and an entity type');
+        const { changes, redactedFields } = diff(input.before ?? {}, input.after ?? {}, classifier);
+        return {
+            action: input.action,
+            entityType: input.entityType,
+            entityId: input.entityId,
+            scope: input.scope ? { key: input.scope.key, id: input.scope.id } : null,
+            actorUserId: input.actor?.id ?? null,
+            outcome: input.outcome ?? 'success',
+            occurredAt: (0, time_js_1.toUtcIso)(input.occurredAt ?? new Date()),
+            changes,
+            redactedFields,
+            ip: input.ip ?? null,
+            userAgent: input.userAgent ? input.userAgent.slice(0, exports.MAX_USER_AGENT_LENGTH) : null,
+        };
+    };
+}
+/**
+ * Builds an audit event with the default redaction list: the diff holds only changed fields; secret
+ * fields are dropped (named in `redactedFields`); phone fields are masked to their last 4 digits.
+ *
+ * @param input Action, entity, scope, actor, before/after state and request facts.
+ * @returns The event.
+ * @example buildAuditEvent({ action: 'widget.updated', entityType: 'widget', entityId, scope: { key: 'tenant', id: tenantId }, actor: req.user ?? null, before, after, ip: req.ip, userAgent: req.get('user-agent') })
+ */
+exports.buildAuditEvent = createAuditEventBuilder();
+//# sourceMappingURL=index.js.map

package/dist/cjs/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/audit/index.ts"],"names":[],"mappings":"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"}

package/dist/cjs/cache/index.js

@@ -1,9 +1,47 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CACHE_TAG_PURPOSE = void 0;
+exports.assertTtl = assertTtl;
 exports.createCache = createCache;
 exports.createRedisClient = createRedisClient;
+exports.setWithTtl = setWithTtl;
 const ioredis_1 = require("ioredis");
-const index_js_1 = require("../logging/index.js");
+const index_js_1 = require("../config/index.js");
+const index_js_2 = require("../logging/index.js");
+__exportStar(require("./keyspace.js"), exports);
+/** Purpose segment for tag index sets: `{prefix}cache-tag:{tag}`. */
+exports.CACHE_TAG_PURPOSE = 'cache-tag';
+/** Lower bound for a tag set's own TTL, so it outlives the keys it lists. */
+const MIN_TAG_TTL_SEC = 86_400;
+/**
+ * Throws unless `ttlSec` is a positive whole number of seconds.
+ *
+ * @param ttlSec Proposed TTL.
+ * @throws ConfigError for ttl ≤ 0, fractions, NaN or Infinity.
+ * @example assertTtl(60)
+ */
+function assertTtl(ttlSec) {
+    if (!Number.isInteger(ttlSec) || ttlSec <= 0)
+        throw new index_js_1.ConfigError(`Redis TTL must be a positive whole number of seconds (got ${String(ttlSec)})`);
+}
+function assertOwned(keyspace, key) {
+    if (!keyspace.owns(key))
+        throw new index_js_1.ConfigError(`Cache key is outside the keyspace ${keyspace.prefix}`);
+}
 const NULL_SENTINEL = '__null__';
 class MemoryStore {
     max;
@@ -37,14 +75,23 @@ class MemoryStore {
  * Redis-backed cache with tag invalidation. If Redis errors, reads fall through to the loader
  * and writes go to a bounded in-memory store, so a cache outage degrades latency rather than
  * availability.
+ *
+ * @param options Redis client (or null for memory only), the service keyspace, memory bound, logger.
+ * @returns The {@link Cache}.
+ * @example
+ * const cache = createCache({ redis, keyspace: ks, logger });
+ * const widget = await cache.wrap(ks.key('widget', id), () => repo.find(id), { ttlSec: 300 });
  */
 function createCache(options) {
-    const logger = options.logger ?? index_js_1.silentLogger;
-    const defaultTtl = options.defaultTtlSec ?? 60;
+    const logger = options.logger ?? index_js_2.silentLogger;
+    const { keyspace } = options;
     const memory = new MemoryStore(options.memoryMaxEntries ?? 5000);
     const inflight = new Map();
-    const k = (key) => `${options.namespace}:${key}`;
-    const tagKey = (tag) => `${options.namespace}:tag:${tag}`;
+    const k = (key) => {
+        assertOwned(keyspace, key);
+        return key;
+    };
+    const tagKey = (tag) => keyspace.key(exports.CACHE_TAG_PURPOSE, tag);
     let warned = false;
     const redisFailed = (error) => {
         if (!warned)
@@ -64,13 +111,14 @@ function createCache(options) {
         }
         return memory.get(k(key));
     };
-    const writeRaw = async (key, raw, opts = {}) => {
-        const ttl = opts.ttlSec ?? defaultTtl;
+    const writeRaw = async (key, raw, opts) => {
+        assertTtl(opts.ttlSec);
+        const ttl = opts.ttlSec;
         if (options.redis) {
             try {
                 const pipeline = options.redis.multi().set(k(key), raw, 'EX', ttl);
                 for (const tag of opts.tags ?? [])
-                    pipeline.sadd(tagKey(tag), k(key)).expire(tagKey(tag), Math.max(ttl, 86_400));
+                    pipeline.sadd(tagKey(tag), k(key)).expire(tagKey(tag), Math.max(ttl, MIN_TAG_TTL_SEC));
                 await pipeline.exec();
                 return;
             }
@@ -96,7 +144,8 @@ function createCache(options) {
             if (options.redis && keys.length)
                 await options.redis.del(...keys.map(k)).catch(redisFailed);
         },
-        async wrap(key, loader, opts = {}) {
+        async wrap(key, loader, opts) {
+            assertTtl(opts.ttlSec);
             const raw = await readRaw(key);
             if (raw !== undefined) {
                 if (raw === NULL_SENTINEL)
@@ -112,7 +161,7 @@ function createCache(options) {
                     if (value !== null && value !== undefined)
                         await writeRaw(key, JSON.stringify(value), opts);
                     else if (opts.cacheNull)
-                        await writeRaw(key, NULL_SENTINEL, { ...opts, ttlSec: Math.min(opts.ttlSec ?? defaultTtl, 30) });
+                        await writeRaw(key, NULL_SENTINEL, { ...opts, ttlSec: Math.min(opts.ttlSec, 30) });
                     return value;
                 }
                 finally {
@@ -142,19 +191,30 @@ function createCache(options) {
     };
     return cache;
 }
-/** ioredis client that never crashes the process on connection errors and retries forever. */
-function createRedisClient(opts) {
-    const logger = opts.logger ?? index_js_1.silentLogger;
+/**
+ * ioredis client that never crashes the process on connection errors and retries forever.
+ * It sets no `keyPrefix`: keys carry their full `{app}:{env}:{service}:` prefix from the keyspace.
+ *
+ * @param env Connection env (`REDIS_URL`, or host/port/password, and `REDIS_DB`).
+ * @param opts Logger and extra ioredis options.
+ * @returns The client.
+ * @example const redis = createRedisClient(config, { logger });
+ */
+function createRedisClient(env, opts = {}) {
+    const logger = opts.logger ?? index_js_2.silentLogger;
     const base = {
-        db: opts.db ?? 0,
-        keyPrefix: opts.keyPrefix || undefined,
+        host: env.REDIS_HOST,
+        port: env.REDIS_PORT,
+        password: env.REDIS_PASSWORD || undefined,
+        db: env.REDIS_DB ?? 0,
         lazyConnect: false,
         enableOfflineQueue: false,
         maxRetriesPerRequest: 1,
         retryStrategy: (times) => Math.min(times * 500, 10_000),
         ...opts.options,
+        keyPrefix: undefined,
     };
-    const client = opts.url ? new ioredis_1.Redis(opts.url, base) : new ioredis_1.Redis(base);
+    const client = env.REDIS_URL ? new ioredis_1.Redis(env.REDIS_URL, base) : new ioredis_1.Redis(base);
     let lastError = '';
     client.on('error', (error) => {
         if (error.message !== lastError)
@@ -164,4 +224,18 @@ function createRedisClient(opts) {
     client.on('ready', () => { lastError = ''; logger.info('Redis connected', { db: base.db }); });
     return client;
 }
+/**
+ * `SET key value EX ttlSec` for a keyspace key; refuses a TTL ≤ 0 so no key lives forever.
+ *
+ * @param redis Client (or anything with a compatible `set`).
+ * @param key Key from the service keyspace.
+ * @param value String value.
+ * @param ttlSec TTL in whole seconds (> 0).
+ * @throws ConfigError for an invalid TTL.
+ * @example await setWithTtl(redis, ks.key('session', id), payload, 900);
+ */
+async function setWithTtl(redis, key, value, ttlSec) {
+    assertTtl(ttlSec);
+    await redis.set(key, value, 'EX', ttlSec);
+}
 //# sourceMappingURL=index.js.map