@devstroupe/devkit-nest 1.1.16 → 1.2.0-beta.1

package/dist/platform/integrations/external-http.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/platform/integrations/external-http.test.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const external_http_1 = require("./external-http");
+(0, node_test_1.default)('external capability applies correlation, retry and neutral response parsing', async () => {
+    const calls = [];
+    const fetcher = async (_url, init) => {
+        calls.push(init ?? {});
+        if (calls.length === 1)
+            throw new Error('temporary network failure');
+        return new Response(JSON.stringify({ legalName: 'Example Ltd' }), {
+            status: 200, headers: { 'content-type': 'application/json' },
+        });
+    };
+    const metrics = [];
+    const logs = [];
+    const client = new external_http_1.ExternalHttpClient({ timeoutMs: 100, maxAttempts: 2, retryDelayMs: 0 }, { record: (...args) => metrics.push(args) }, fetcher, { record: (entry) => logs.push(entry) });
+    const response = await client.json('company-registry', 'https://provider.invalid/company/1', {}, { correlationId: 'corr-http' });
+    strict_1.default.equal(response.legalName, 'Example Ltd');
+    strict_1.default.equal(calls[1].headers['x-correlation-id'], 'corr-http');
+    strict_1.default.equal(metrics[0][1], 'success');
+    strict_1.default.deepEqual(logs.map(({ outcome }) => outcome), ['retry', 'success']);
+    strict_1.default.equal(logs[0].correlationId, 'corr-http');
+    strict_1.default.equal('url' in logs[0], false);
+    strict_1.default.equal('headers' in logs[0], false);
+});
+(0, node_test_1.default)('telemetry failure does not retry a successful external request', async () => {
+    let calls = 0;
+    const fetcher = async () => {
+        calls += 1;
+        return new Response(JSON.stringify({ ok: true }), { status: 200 });
+    };
+    const client = new external_http_1.ExternalHttpClient({ timeoutMs: 100, maxAttempts: 2, retryDelayMs: 0 }, { record: () => { throw new Error('metrics unavailable'); } }, fetcher, { record: () => { throw new Error('logs unavailable'); } });
+    strict_1.default.deepEqual(await client.json('company-registry', 'https://provider.invalid', {}, {
+        correlationId: 'corr-safe-observability',
+    }), { ok: true });
+    strict_1.default.equal(calls, 1);
+});

package/dist/platform/integrations/index.d.ts

@@ -0,0 +1,3 @@
+export * from './company-registry';
+export * from './external-http';
+export * from './webhook';

package/dist/platform/integrations/index.js

@@ -0,0 +1,19 @@
+"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 });
+__exportStar(require("./company-registry"), exports);
+__exportStar(require("./external-http"), exports);
+__exportStar(require("./webhook"), exports);

package/dist/platform/integrations/webhook.d.ts

@@ -0,0 +1,45 @@
+export interface WebhookRequest {
+    body: Uint8Array;
+    headers: Readonly<Record<string, string | undefined>>;
+    receivedAt: Date;
+    correlationId: string;
+}
+export interface VerifiedWebhook<Payload> {
+    eventId: string;
+    payload: Payload;
+    tenantId?: string;
+    actorId?: string;
+}
+export interface WebhookVerifier<Payload> {
+    verify(request: WebhookRequest): Promise<VerifiedWebhook<Payload>>;
+}
+export interface WebhookIdempotencyStore {
+    /** Atomic: returns false when this event was already accepted. */
+    acquire(eventId: string): Promise<boolean>;
+    release(eventId: string): Promise<void>;
+}
+export type WebhookAuditOutcome = 'processed' | 'duplicate' | 'rejected' | 'failed';
+export interface WebhookAuditRecord {
+    /** Payload, signature and provider secrets are deliberately absent. */
+    eventId?: string;
+    correlationId: string;
+    outcome: WebhookAuditOutcome;
+    occurredAt: Date;
+}
+export interface WebhookAuditSink {
+    record(entry: WebhookAuditRecord): void | Promise<void>;
+}
+export declare class WebhookReplayError extends Error {
+    constructor(message?: string);
+}
+/** Call from a provider verifier after signature validation and before returning its payload. */
+export declare function assertWebhookFresh(providerTimestamp: Date, receivedAt: Date, maxAgeMs: number, allowedFutureSkewMs?: number): void;
+export declare class WebhookProcessor<Payload> {
+    private readonly verifier;
+    private readonly idempotency;
+    private readonly handle;
+    private readonly audit?;
+    constructor(verifier: WebhookVerifier<Payload>, idempotency: WebhookIdempotencyStore, handle: (payload: Payload) => Promise<void>, audit?: WebhookAuditSink | undefined);
+    process(request: WebhookRequest): Promise<'processed' | 'duplicate'>;
+    private record;
+}

package/dist/platform/integrations/webhook.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookProcessor = exports.WebhookReplayError = void 0;
+exports.assertWebhookFresh = assertWebhookFresh;
+const context_1 = require("../../context");
+class WebhookReplayError extends Error {
+    constructor(message = 'Webhook timestamp is outside the accepted replay window.') {
+        super(message);
+        this.name = 'WebhookReplayError';
+    }
+}
+exports.WebhookReplayError = WebhookReplayError;
+/** Call from a provider verifier after signature validation and before returning its payload. */
+function assertWebhookFresh(providerTimestamp, receivedAt, maxAgeMs, allowedFutureSkewMs = 30_000) {
+    const age = receivedAt.getTime() - providerTimestamp.getTime();
+    if (!Number.isFinite(age) || age > maxAgeMs || age < -allowedFutureSkewMs) {
+        throw new WebhookReplayError();
+    }
+}
+class WebhookProcessor {
+    verifier;
+    idempotency;
+    handle;
+    audit;
+    constructor(verifier, idempotency, handle, audit) {
+        this.verifier = verifier;
+        this.idempotency = idempotency;
+        this.handle = handle;
+        this.audit = audit;
+    }
+    async process(request) {
+        let verified;
+        try {
+            verified = await this.verifier.verify(request);
+        }
+        catch (error) {
+            await this.record(request, 'rejected');
+            throw error;
+        }
+        if (!await this.idempotency.acquire(verified.eventId)) {
+            await this.record(request, 'duplicate', verified.eventId);
+            return 'duplicate';
+        }
+        try {
+            await context_1.executionContext.run({
+                actorId: verified.actorId,
+                tenantId: verified.tenantId,
+                correlationId: request.correlationId,
+                source: 'event',
+            }, () => this.handle(verified.payload));
+            await this.record(request, 'processed', verified.eventId);
+            return 'processed';
+        }
+        catch (error) {
+            await this.idempotency.release(verified.eventId);
+            await this.record(request, 'failed', verified.eventId);
+            throw error;
+        }
+    }
+    async record(request, outcome, eventId) {
+        try {
+            await this.audit?.record({
+                eventId,
+                correlationId: request.correlationId,
+                outcome,
+                occurredAt: new Date(),
+            });
+        }
+        catch {
+            // Observability must never release idempotency or repeat an accepted effect.
+        }
+    }
+}
+exports.WebhookProcessor = WebhookProcessor;

package/dist/platform/integrations/webhook.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/platform/integrations/webhook.test.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const context_1 = require("../../context");
+const webhook_1 = require("./webhook");
+(0, node_test_1.default)('webhook verification runs before application effects and duplicates are ignored', async () => {
+    const accepted = new Set();
+    let effects = 0;
+    const verifier = {
+        async verify(request) {
+            if (request.headers.signature !== 'valid')
+                throw new Error('invalid signature');
+            return { eventId: 'provider-event-1', payload: { invoiceId: 1 } };
+        },
+    };
+    const store = {
+        async acquire(id) { if (accepted.has(id))
+            return false; accepted.add(id); return true; },
+        async release(id) { accepted.delete(id); },
+    };
+    const audit = [];
+    const processor = new webhook_1.WebhookProcessor(verifier, store, async () => {
+        effects += 1;
+        strict_1.default.equal(context_1.executionContext.requireCurrent().source, 'event');
+        strict_1.default.equal(context_1.executionContext.requireCurrent().correlationId, 'corr-webhook');
+    }, { record: (entry) => { audit.push(entry); } });
+    const request = {
+        body: new Uint8Array(), headers: { signature: 'valid' },
+        receivedAt: new Date(), correlationId: 'corr-webhook',
+    };
+    strict_1.default.equal(await processor.process(request), 'processed');
+    strict_1.default.equal(await processor.process(request), 'duplicate');
+    strict_1.default.equal(effects, 1);
+    await strict_1.default.rejects(() => processor.process({ ...request, headers: {} }), /invalid signature/);
+    strict_1.default.equal(effects, 1);
+    strict_1.default.deepEqual(audit.map(({ outcome }) => outcome), ['processed', 'duplicate', 'rejected']);
+    strict_1.default.equal('body' in audit[0], false);
+    strict_1.default.equal('headers' in audit[0], false);
+});
+(0, node_test_1.default)('webhook replay protection rejects stale and excessively future timestamps', () => {
+    const receivedAt = new Date('2026-07-14T12:00:00.000Z');
+    strict_1.default.doesNotThrow(() => (0, webhook_1.assertWebhookFresh)(new Date('2026-07-14T11:59:30.000Z'), receivedAt, 60_000));
+    strict_1.default.throws(() => (0, webhook_1.assertWebhookFresh)(new Date('2026-07-14T11:58:00.000Z'), receivedAt, 60_000), webhook_1.WebhookReplayError);
+    strict_1.default.throws(() => (0, webhook_1.assertWebhookFresh)(new Date('2026-07-14T12:01:00.000Z'), receivedAt, 60_000, 30_000), webhook_1.WebhookReplayError);
+});
+(0, node_test_1.default)('webhook audit failure cannot release idempotency and duplicate an effect', async () => {
+    let effects = 0;
+    let releases = 0;
+    const accepted = new Set();
+    const processor = new webhook_1.WebhookProcessor({ verify: async () => ({ eventId: 'event-safe', payload: {} }) }, {
+        acquire: async (id) => { if (accepted.has(id))
+            return false; accepted.add(id); return true; },
+        release: async () => { releases += 1; },
+    }, async () => { effects += 1; }, { record: () => { throw new Error('audit unavailable'); } });
+    const request = {
+        body: new Uint8Array(), headers: {}, receivedAt: new Date(), correlationId: 'corr-audit',
+    };
+    strict_1.default.equal(await processor.process(request), 'processed');
+    strict_1.default.equal(await processor.process(request), 'duplicate');
+    strict_1.default.equal(effects, 1);
+    strict_1.default.equal(releases, 0);
+});

package/dist/platform/messaging/index.d.ts

@@ -0,0 +1 @@
+export * from './outbox';

package/dist/platform/messaging/index.js

@@ -0,0 +1,17 @@
+"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 });
+__exportStar(require("./outbox"), exports);

package/dist/platform/messaging/outbox.d.ts

@@ -0,0 +1,56 @@
+import type { EntityManager, EntityTarget, ObjectLiteral } from 'typeorm';
+import type { AppExecutionContext } from '../../context';
+export interface IntegrationEvent<Payload = unknown> {
+    id: string;
+    type: string;
+    occurredAt: string;
+    payload: Payload;
+    tenantId?: string;
+    correlationId: string;
+}
+export interface OutboxRecord {
+    id: string;
+    eventType: string;
+    payload: unknown;
+    tenantId?: string;
+    correlationId: string;
+    occurredAt: Date;
+    publishedAt?: Date;
+    attempts: number;
+    lastError?: string;
+}
+export declare function integrationEvent<Payload>(type: string, payload: Payload, context: Pick<AppExecutionContext, 'tenantId' | 'correlationId'>): IntegrationEvent<Payload>;
+/** Must receive the same transactional manager used for the business write. */
+export declare class TypeOrmOutboxWriter {
+    private readonly recordTarget;
+    constructor(recordTarget: EntityTarget<ObjectLiteral>);
+    append(manager: EntityManager, event: IntegrationEvent): Promise<void>;
+}
+export interface OutboxStore {
+    pending(limit: number): Promise<OutboxRecord[]>;
+    markPublished(id: string, publishedAt: Date): Promise<void>;
+    markFailed(id: string, error: string): Promise<void>;
+}
+export interface IntegrationEventBroker {
+    /** The event ID is the consumer idempotency key. */
+    publish(event: IntegrationEvent): Promise<void>;
+}
+export interface InboxIdempotencyStore {
+    acquire(eventId: string): Promise<boolean>;
+    release(eventId: string): Promise<void>;
+}
+export declare class IdempotentEventConsumer {
+    private readonly inbox;
+    constructor(inbox: InboxIdempotencyStore);
+    consume(event: IntegrationEvent, effect: (event: IntegrationEvent) => Promise<void>): Promise<'processed' | 'duplicate'>;
+}
+export declare class OutboxPublisher {
+    private readonly store;
+    private readonly broker;
+    private readonly batchSize;
+    constructor(store: OutboxStore, broker: IntegrationEventBroker, batchSize?: number);
+    publishPending(): Promise<{
+        published: number;
+        failed: number;
+    }>;
+}

package/dist/platform/messaging/outbox.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboxPublisher = exports.IdempotentEventConsumer = exports.TypeOrmOutboxWriter = void 0;
+exports.integrationEvent = integrationEvent;
+const node_crypto_1 = require("node:crypto");
+const context_1 = require("../../context");
+function integrationEvent(type, payload, context) {
+    return {
+        id: (0, node_crypto_1.randomUUID)(), type, payload, tenantId: context.tenantId,
+        correlationId: context.correlationId, occurredAt: new Date().toISOString(),
+    };
+}
+/** Must receive the same transactional manager used for the business write. */
+class TypeOrmOutboxWriter {
+    recordTarget;
+    constructor(recordTarget) {
+        this.recordTarget = recordTarget;
+    }
+    async append(manager, event) {
+        const record = {
+            id: event.id,
+            eventType: event.type,
+            payload: event.payload,
+            tenantId: event.tenantId,
+            correlationId: event.correlationId,
+            occurredAt: new Date(event.occurredAt),
+            attempts: 0,
+        };
+        await manager.insert(this.recordTarget, record);
+    }
+}
+exports.TypeOrmOutboxWriter = TypeOrmOutboxWriter;
+class IdempotentEventConsumer {
+    inbox;
+    constructor(inbox) {
+        this.inbox = inbox;
+    }
+    async consume(event, effect) {
+        if (!await this.inbox.acquire(event.id))
+            return 'duplicate';
+        try {
+            await context_1.executionContext.run({
+                tenantId: event.tenantId,
+                correlationId: event.correlationId,
+                source: 'event',
+            }, () => effect(event));
+            return 'processed';
+        }
+        catch (error) {
+            await this.inbox.release(event.id);
+            throw error;
+        }
+    }
+}
+exports.IdempotentEventConsumer = IdempotentEventConsumer;
+class OutboxPublisher {
+    store;
+    broker;
+    batchSize;
+    constructor(store, broker, batchSize = 50) {
+        this.store = store;
+        this.broker = broker;
+        this.batchSize = batchSize;
+    }
+    async publishPending() {
+        const records = await this.store.pending(this.batchSize);
+        let published = 0;
+        let failed = 0;
+        for (const record of records) {
+            try {
+                await this.broker.publish({
+                    id: record.id,
+                    type: record.eventType,
+                    payload: record.payload,
+                    tenantId: record.tenantId,
+                    correlationId: record.correlationId,
+                    occurredAt: record.occurredAt.toISOString(),
+                });
+                await this.store.markPublished(record.id, new Date());
+                published += 1;
+            }
+            catch (error) {
+                await this.store.markFailed(record.id, error instanceof Error ? error.message : String(error));
+                failed += 1;
+            }
+        }
+        return { published, failed };
+    }
+}
+exports.OutboxPublisher = OutboxPublisher;

package/dist/platform/messaging/outbox.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/platform/messaging/outbox.test.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const context_1 = require("../../context");
+const outbox_1 = require("./outbox");
+(0, node_test_1.default)('outbox writer uses the caller transactional manager and carries tenant/correlation', async () => {
+    const inserted = [];
+    const manager = { insert: async (...args) => { inserted.push(args); } };
+    const event = (0, outbox_1.integrationEvent)('invoice.created', { invoiceId: 1 }, {
+        tenantId: 'tenant-1', correlationId: 'corr-1',
+    });
+    await new outbox_1.TypeOrmOutboxWriter('outbox').append(manager, event);
+    strict_1.default.equal(inserted.length, 1);
+    strict_1.default.equal(inserted[0][1].tenantId, 'tenant-1');
+    strict_1.default.equal(inserted[0][1].correlationId, 'corr-1');
+    strict_1.default.equal(inserted[0][1].id, event.id);
+});
+(0, node_test_1.default)('outbox keeps a failed event pending and publishes it idempotently on retry', async () => {
+    const record = {
+        id: 'event-1', eventType: 'invoice.created', payload: { invoiceId: 1 },
+        correlationId: 'corr-1', tenantId: 'tenant-1', occurredAt: new Date(), attempts: 0,
+    };
+    let pending = true;
+    let brokerCalls = 0;
+    const store = {
+        async pending() { return pending ? [record] : []; },
+        async markPublished() { pending = false; },
+        async markFailed() { record.attempts += 1; },
+    };
+    const broker = {
+        async publish(event) {
+            brokerCalls += 1;
+            strict_1.default.equal(event.id, 'event-1');
+            if (brokerCalls === 1)
+                throw new Error('broker unavailable');
+        },
+    };
+    const publisher = new outbox_1.OutboxPublisher(store, broker);
+    strict_1.default.deepEqual(await publisher.publishPending(), { published: 0, failed: 1 });
+    strict_1.default.deepEqual(await publisher.publishPending(), { published: 1, failed: 0 });
+    strict_1.default.deepEqual(await publisher.publishPending(), { published: 0, failed: 0 });
+    strict_1.default.equal(brokerCalls, 2);
+});
+(0, node_test_1.default)('consumer inbox prevents a redelivered event from duplicating its effect', async () => {
+    const accepted = new Set();
+    const inbox = {
+        async acquire(id) { if (accepted.has(id))
+            return false; accepted.add(id); return true; },
+        async release(id) { accepted.delete(id); },
+    };
+    const consumer = new outbox_1.IdempotentEventConsumer(inbox);
+    const event = (0, outbox_1.integrationEvent)('payment.confirmed', { paymentId: 1 }, { correlationId: 'corr-2' });
+    let effects = 0;
+    strict_1.default.equal(await consumer.consume(event, async () => {
+        effects += 1;
+        strict_1.default.equal(context_1.executionContext.requireCurrent().source, 'event');
+        strict_1.default.equal(context_1.executionContext.requireCurrent().correlationId, 'corr-2');
+    }), 'processed');
+    strict_1.default.equal(await consumer.consume(event, async () => { effects += 1; }), 'duplicate');
+    strict_1.default.equal(effects, 1);
+});

package/dist/platform/security/index.d.ts

@@ -0,0 +1,2 @@
+export * from './password-hasher';
+export * from './token';

package/dist/platform/security/index.js

@@ -0,0 +1,18 @@
+"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 });
+__exportStar(require("./password-hasher"), exports);
+__exportStar(require("./token"), exports);

package/dist/platform/security/password-hasher.d.ts

@@ -0,0 +1,14 @@
+export interface PasswordHasher {
+    hash(plainText: string): Promise<string>;
+    verify(plainText: string, encodedHash: string): Promise<boolean>;
+}
+export declare class BcryptPasswordHasher implements PasswordHasher {
+    private readonly rounds;
+    constructor(rounds?: number);
+    hash(plainText: string): Promise<string>;
+    verify(plainText: string, encodedHash: string): Promise<boolean>;
+}
+export declare class InMemoryPasswordHasher implements PasswordHasher {
+    hash(plainText: string): Promise<string>;
+    verify(plainText: string, encodedHash: string): Promise<boolean>;
+}

package/dist/platform/security/password-hasher.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryPasswordHasher = exports.BcryptPasswordHasher = void 0;
+const bcryptjs_1 = require("bcryptjs");
+class BcryptPasswordHasher {
+    rounds;
+    constructor(rounds = 12) {
+        this.rounds = rounds;
+        if (rounds < 10)
+            throw new Error('Bcrypt cost must be at least 10.');
+    }
+    hash(plainText) { return (0, bcryptjs_1.hash)(plainText, this.rounds); }
+    verify(plainText, encodedHash) { return (0, bcryptjs_1.compare)(plainText, encodedHash); }
+}
+exports.BcryptPasswordHasher = BcryptPasswordHasher;
+class InMemoryPasswordHasher {
+    hash(plainText) { return Promise.resolve(`test:${plainText}`); }
+    verify(plainText, encodedHash) { return Promise.resolve(encodedHash === `test:${plainText}`); }
+}
+exports.InMemoryPasswordHasher = InMemoryPasswordHasher;

package/dist/platform/security/security.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/platform/security/security.test.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const password_hasher_1 = require("./password-hasher");
+const token_1 = require("./token");
+(0, node_test_1.default)('password hashing is replaceable and bcrypt never stores plain text', async () => {
+    const bcrypt = new password_hasher_1.BcryptPasswordHasher(10);
+    const encoded = await bcrypt.hash('secret-value');
+    strict_1.default.notEqual(encoded, 'secret-value');
+    strict_1.default.equal(await bcrypt.verify('secret-value', encoded), true);
+    strict_1.default.equal(await new password_hasher_1.InMemoryPasswordHasher().verify('secret-value', 'test:secret-value'), true);
+});
+(0, node_test_1.default)('token issuing and verification are separate capabilities', async () => {
+    const secret = 'a-development-secret-with-at-least-32-characters';
+    const issuer = new token_1.JwtTokenIssuer(secret, { algorithm: 'HS256', expiresIn: '1m' });
+    const verifier = new token_1.JwtTokenVerifier((0, token_1.staticVerificationKey)(secret), ['HS256']);
+    const token = await issuer.issue({ sub: 'user-1' });
+    strict_1.default.equal((await verifier.verify(token)).sub, 'user-1');
+    strict_1.default.equal('issue' in verifier, false);
+});

package/dist/platform/security/token.d.ts

@@ -0,0 +1,22 @@
+import { Algorithm, JwtHeader, JwtPayload, SignOptions } from 'jsonwebtoken';
+export interface TokenIssuer<Claims extends object = Record<string, unknown>> {
+    issue(claims: Claims): Promise<string>;
+}
+export interface TokenVerifier<Claims extends object = Record<string, unknown>> {
+    verify(token: string): Promise<Claims & JwtPayload>;
+}
+export type VerificationKeyResolver = (header: JwtHeader) => Promise<string | Buffer>;
+export declare class JwtTokenIssuer<Claims extends object = Record<string, unknown>> implements TokenIssuer<Claims> {
+    private readonly privateKey;
+    private readonly options;
+    constructor(privateKey: string | Buffer, options?: SignOptions);
+    issue(claims: Claims): Promise<string>;
+}
+/** Consumers receive only this verifier and a public/JWKS key resolver. */
+export declare class JwtTokenVerifier<Claims extends object = Record<string, unknown>> implements TokenVerifier<Claims> {
+    private readonly resolveKey;
+    private readonly algorithms;
+    constructor(resolveKey: VerificationKeyResolver, algorithms?: Algorithm[]);
+    verify(token: string): Promise<Claims & JwtPayload>;
+}
+export declare function staticVerificationKey(key: string | Buffer): VerificationKeyResolver;

package/dist/platform/security/token.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwtTokenVerifier = exports.JwtTokenIssuer = void 0;
+exports.staticVerificationKey = staticVerificationKey;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+class JwtTokenIssuer {
+    privateKey;
+    options;
+    constructor(privateKey, options = { algorithm: 'RS256', expiresIn: '15m' }) {
+        this.privateKey = privateKey;
+        this.options = options;
+    }
+    issue(claims) {
+        return Promise.resolve(jsonwebtoken_1.default.sign(claims, this.privateKey, this.options));
+    }
+}
+exports.JwtTokenIssuer = JwtTokenIssuer;
+/** Consumers receive only this verifier and a public/JWKS key resolver. */
+class JwtTokenVerifier {
+    resolveKey;
+    algorithms;
+    constructor(resolveKey, algorithms = ['RS256']) {
+        this.resolveKey = resolveKey;
+        this.algorithms = algorithms;
+    }
+    verify(token) {
+        return new Promise((resolve, reject) => {
+            jsonwebtoken_1.default.verify(token, (header, done) => this.resolveKey(header).then((key) => done(null, key), done), { algorithms: this.algorithms }, (error, decoded) => {
+                if (error)
+                    return reject(error);
+                if (!decoded || typeof decoded === 'string')
+                    return reject(new Error('Token claims are invalid.'));
+                resolve(decoded);
+            });
+        });
+    }
+}
+exports.JwtTokenVerifier = JwtTokenVerifier;
+function staticVerificationKey(key) {
+    return async () => key;
+}