@smounters/kit 2.2.0

package/dist/money/index.d.ts

@@ -0,0 +1,45 @@
+import { Decimal } from "decimal.js";
+/** Money scale: `numeric(20,4)`. Four decimal places cover fiat and keep every posting exact. */
+export declare const MONEY_SCALE = 4;
+/** Ratio scale: `numeric(20,8)` — returns, coverage, shares of a fee. */
+export declare const RATE_SCALE = 8;
+export declare const ZERO_MONEY = "0.0000";
+/**
+ * Rounding is never "whatever the library defaults to" — every quantization must round in the direction
+ * that protects the party who did NOT initiate the action. Pick explicitly at each call site; these are
+ * re-exported so a caller never has to import decimal.js just for a constant.
+ */
+export declare const ROUND_DOWN: 1;
+export declare const ROUND_UP: 0;
+export declare const ROUND_HALF_UP: 4;
+/** Parse a possibly empty/absent amount as Decimal; "" and undefined mean zero. */
+export declare function toDecimal(amount: string | undefined | null): Decimal;
+/**
+ * Normalize to money scale, or return null when the input carries MORE precision than the ledger can
+ * store. The caller must reject rather than persist: the column would round silently, desyncing the
+ * stored row from the scale-4 balance math and potentially un-balancing a posting.
+ */
+export declare function toMoneyAmount(amount: string): string | null;
+/**
+ * Quantize to the decimals of a specific ASSET rather than to the ledger scale.
+ *
+ * Needed whenever an amount has to be reachable on the other side: a token with 6 decimals cannot
+ * transfer a value with 8, so an expected amount quantized to the ledger scale can be impossible to pay
+ * exactly — and a strict comparison then reports an underpayment that the payer could not have avoided.
+ * `rounding` decides who absorbs the residue: ROUND_UP for what someone must pay (they overpay by dust),
+ * ROUND_DOWN for what we pay out.
+ */
+export declare function quantizeToDecimals(amount: string, decimals: number, rounding?: Decimal.Rounding): string;
+export declare function sumAmounts(amounts: readonly string[]): Decimal;
+/** Apply a signed delta to a balance, at money scale. */
+export declare function applyDelta(balance: string, amount: string): string;
+export interface PostingLine {
+    /** Signed decimal string: debit > 0, credit < 0. */
+    amount: string;
+}
+/**
+ * Is this a valid double-entry posting? At least two lines, no zero-amount line, and the signed amounts
+ * sum to EXACTLY zero. This is the invariant that makes a ledger auditable, so it is checked in code
+ * rather than trusted: a posting that does not balance must never reach the database.
+ */
+export declare function isBalanced(lines: readonly PostingLine[]): boolean;

package/dist/money/index.js

@@ -0,0 +1,67 @@
+import { Decimal } from "decimal.js";
+// Money arithmetic. Pure, no infrastructure.
+//
+// Nothing here may use a JS number: a double cannot represent 0.1 exactly, and a ledger that cannot
+// represent its own amounts stops balancing within a day. Amounts travel as decimal STRINGS end to end
+// (numeric in the database, string on the wire) and are only turned into Decimal for the arithmetic.
+// Precision must exceed the widest intermediate we produce (a 20-digit amount divided by an 18-dp rate).
+Decimal.set({ precision: 50, toExpNeg: -50, toExpPos: 50 });
+/** Money scale: `numeric(20,4)`. Four decimal places cover fiat and keep every posting exact. */
+export const MONEY_SCALE = 4;
+/** Ratio scale: `numeric(20,8)` — returns, coverage, shares of a fee. */
+export const RATE_SCALE = 8;
+export const ZERO_MONEY = "0.0000";
+/**
+ * Rounding is never "whatever the library defaults to" — every quantization must round in the direction
+ * that protects the party who did NOT initiate the action. Pick explicitly at each call site; these are
+ * re-exported so a caller never has to import decimal.js just for a constant.
+ */
+export const ROUND_DOWN = Decimal.ROUND_DOWN;
+export const ROUND_UP = Decimal.ROUND_UP;
+export const ROUND_HALF_UP = Decimal.ROUND_HALF_UP;
+/** Parse a possibly empty/absent amount as Decimal; "" and undefined mean zero. */
+export function toDecimal(amount) {
+    return new Decimal(amount != null && amount.length > 0 ? amount : "0");
+}
+/**
+ * Normalize to money scale, or return null when the input carries MORE precision than the ledger can
+ * store. The caller must reject rather than persist: the column would round silently, desyncing the
+ * stored row from the scale-4 balance math and potentially un-balancing a posting.
+ */
+export function toMoneyAmount(amount) {
+    const d = toDecimal(amount);
+    if (d.decimalPlaces() > MONEY_SCALE)
+        return null;
+    return d.toFixed(MONEY_SCALE);
+}
+/**
+ * Quantize to the decimals of a specific ASSET rather than to the ledger scale.
+ *
+ * Needed whenever an amount has to be reachable on the other side: a token with 6 decimals cannot
+ * transfer a value with 8, so an expected amount quantized to the ledger scale can be impossible to pay
+ * exactly — and a strict comparison then reports an underpayment that the payer could not have avoided.
+ * `rounding` decides who absorbs the residue: ROUND_UP for what someone must pay (they overpay by dust),
+ * ROUND_DOWN for what we pay out.
+ */
+export function quantizeToDecimals(amount, decimals, rounding = ROUND_DOWN) {
+    return toDecimal(amount).toFixed(decimals, rounding);
+}
+export function sumAmounts(amounts) {
+    return amounts.reduce((acc, a) => acc.plus(toDecimal(a)), new Decimal(0));
+}
+/** Apply a signed delta to a balance, at money scale. */
+export function applyDelta(balance, amount) {
+    return toDecimal(balance).plus(toDecimal(amount)).toFixed(MONEY_SCALE);
+}
+/**
+ * Is this a valid double-entry posting? At least two lines, no zero-amount line, and the signed amounts
+ * sum to EXACTLY zero. This is the invariant that makes a ledger auditable, so it is checked in code
+ * rather than trusted: a posting that does not balance must never reach the database.
+ */
+export function isBalanced(lines) {
+    if (lines.length < 2)
+        return false;
+    if (lines.some((l) => toDecimal(l.amount).isZero()))
+        return false;
+    return sumAmounts(lines.map((l) => l.amount)).isZero();
+}

package/dist/net/index.d.ts

@@ -0,0 +1,30 @@
+/** Is this IP literal in a private / loopback / link-local / reserved range? Pure, unit-tested. */
+export declare function isPrivateIp(ip: string): boolean;
+/**
+ * Throw unless `rawUrl` is a safe public http(s) target: blocks non-http schemes, internal hostnames,
+ * IP literals in private ranges, and hostnames that DNS-resolve into a private range.
+ *
+ * Known limit: a determined DNS-rebinding attacker can still win the race between this check and the
+ * socket connect. Closing that needs connect-time pinning; this blocks the realistic cases —
+ * misconfiguration and metadata-endpoint grabs.
+ */
+export declare function assertPublicUrl(rawUrl: string): Promise<void>;
+/**
+ * A request was refused as an SSRF risk (private/internal target, bad scheme, or a redirect to one).
+ * Deliberately distinct from transient network/timeout errors: callers should treat it as a PERMANENT
+ * misconfiguration — mark the delivery blocked instead of retrying it forever.
+ */
+export declare class SsrfBlockedError extends Error {
+}
+export interface SafeFetchInit extends RequestInit {
+    /** Abort after this many ms (default 10s). Ignored when an explicit `signal` is supplied. */
+    timeoutMs?: number;
+}
+/**
+ * SSRF-safe outbound fetch. `assertPublicUrl` on its own only validates the FIRST url while `fetch`
+ * defaults to following redirects — so a public host could answer 302 → a private address and the guard
+ * would be bypassed. This follows redirects MANUALLY and re-validates every hop, with a timeout.
+ *
+ * Route every outbound request built from a user- or tenant-supplied URL through here.
+ */
+export declare function safeFetch(url: string, init?: SafeFetchInit): Promise<Response>;

package/dist/net/index.js

@@ -0,0 +1,122 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+// SSRF guard for outbound requests whose URL is configurable by a user, a tenant admin or a merchant
+// (postback targets, webhook endpoints, avatar imports). Without it such a URL can point at a
+// cluster-internal service or the cloud metadata endpoint (169.254.169.254) and the server will happily
+// fetch it — the request comes from inside the perimeter.
+/** Is this IP literal in a private / loopback / link-local / reserved range? Pure, unit-tested. */
+export function isPrivateIp(ip) {
+    const v = isIP(ip);
+    if (v === 4)
+        return isPrivateV4(ip);
+    if (v === 6)
+        return isPrivateV6(ip.toLowerCase());
+    return false;
+}
+function isPrivateV4(ip) {
+    const p = ip.split(".").map(Number);
+    if (p.length !== 4 || p.some((n) => Number.isNaN(n) || n < 0 || n > 255))
+        return true; // malformed → unsafe
+    const [a, b] = p;
+    if (a === 0 || a === 10 || a === 127)
+        return true; // "this", private, loopback
+    if (a === 169 && b === 254)
+        return true; // link-local (incl. the 169.254.169.254 metadata address)
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // private
+    if (a === 192 && b === 168)
+        return true; // private
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // CGNAT
+    if (a === 192 && b === 0)
+        return true; // 192.0.0.0/24 (IETF) + 192.0.2.0/24 (documentation)
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // benchmarking
+    if (a >= 224)
+        return true; // multicast + reserved + 255.255.255.255
+    return false;
+}
+function isPrivateV6(ip) {
+    if (ip === "::1" || ip === "::")
+        return true; // loopback / unspecified
+    const mapped = /::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(ip); // IPv4-mapped → check the embedded IPv4
+    if (mapped?.[1])
+        return isPrivateV4(mapped[1]);
+    if (ip.startsWith("fc") || ip.startsWith("fd"))
+        return true; // ULA fc00::/7
+    if (ip.startsWith("fe8") || ip.startsWith("fe9") || ip.startsWith("fea") || ip.startsWith("feb"))
+        return true; // link-local
+    return false;
+}
+/**
+ * Throw unless `rawUrl` is a safe public http(s) target: blocks non-http schemes, internal hostnames,
+ * IP literals in private ranges, and hostnames that DNS-resolve into a private range.
+ *
+ * Known limit: a determined DNS-rebinding attacker can still win the race between this check and the
+ * socket connect. Closing that needs connect-time pinning; this blocks the realistic cases —
+ * misconfiguration and metadata-endpoint grabs.
+ */
+export async function assertPublicUrl(rawUrl) {
+    let u;
+    try {
+        u = new URL(rawUrl);
+    }
+    catch {
+        throw new Error("invalid URL");
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:")
+        throw new Error(`scheme ${u.protocol} not allowed`);
+    const host = u.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    if (host === "localhost" || /\.(local|internal|localhost)$/.test(host))
+        throw new Error(`internal host ${host}`);
+    if (isIP(host) !== 0) {
+        if (isPrivateIp(host))
+            throw new Error(`private address ${host}`);
+        return;
+    }
+    const addrs = await lookup(host, { all: true });
+    for (const a of addrs)
+        if (isPrivateIp(a.address))
+            throw new Error(`${host} resolves to private ${a.address}`);
+}
+const MAX_REDIRECTS = 3;
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * A request was refused as an SSRF risk (private/internal target, bad scheme, or a redirect to one).
+ * Deliberately distinct from transient network/timeout errors: callers should treat it as a PERMANENT
+ * misconfiguration — mark the delivery blocked instead of retrying it forever.
+ */
+export class SsrfBlockedError extends Error {
+}
+/**
+ * SSRF-safe outbound fetch. `assertPublicUrl` on its own only validates the FIRST url while `fetch`
+ * defaults to following redirects — so a public host could answer 302 → a private address and the guard
+ * would be bypassed. This follows redirects MANUALLY and re-validates every hop, with a timeout.
+ *
+ * Route every outbound request built from a user- or tenant-supplied URL through here.
+ */
+export async function safeFetch(url, init = {}) {
+    const { timeoutMs = DEFAULT_TIMEOUT_MS, signal, ...rest } = init;
+    let current = url;
+    for (let hop = 0;; hop++) {
+        try {
+            await assertPublicUrl(current); // the initial URL AND every redirect target
+        }
+        catch (err) {
+            throw new SsrfBlockedError(err.message);
+        }
+        const res = await fetch(current, {
+            ...rest,
+            redirect: "manual",
+            signal: signal ?? AbortSignal.timeout(timeoutMs),
+        });
+        if (res.status < 300 || res.status >= 400)
+            return res;
+        const location = res.headers.get("location");
+        if (!location)
+            return res; // 3xx without Location — nothing to follow
+        if (hop >= MAX_REDIRECTS)
+            throw new SsrfBlockedError("too many redirects");
+        current = new URL(location, current).toString(); // relative → absolute; the loop re-validates
+    }
+}

package/dist/redis/index.d.ts

@@ -0,0 +1,66 @@
+import type { OnModuleDestroy, OnModuleInit } from "@smounters/core/core";
+import { LoggerService } from "@smounters/core/services";
+import Redis, { type RedisOptions } from "ioredis";
+export declare const REDIS_CONNECTION: unique symbol;
+export interface RedisConnectionOptions {
+    /** Connection string, e.g. `redis://host:6379/0`. */
+    url: string;
+    /** Passed through to ioredis; the defaults below are chosen for a request-serving process. */
+    options?: RedisOptions;
+    /**
+     * Wait for the connection before the module finishes starting, and FAIL the startup if it errors.
+     *
+     * Two defensible stances, so it is a choice rather than a default: an API that also serves pages
+     * should come up and warn (a cache outage is not an outage of the product), while a worker whose whole
+     * job is queue-driven is better off refusing to start than pretending to work. Default is not to wait.
+     */
+    awaitReady?: boolean;
+}
+/**
+ * Register in the application with the connection supplied as a value provider — the package has no
+ * opinion on where configuration comes from:
+ *
+ * ```ts
+ * @Module({
+ *   providers: [{ provide: REDIS_CONNECTION, useValue: { url: appConfig.REDIS_URL } }, RedisService],
+ *   exports: [RedisService],
+ *   global: true,
+ * })
+ * export class RedisModule {}
+ * ```
+ */
+export declare class RedisService implements OnModuleInit, OnModuleDestroy {
+    private readonly connection;
+    private readonly logger;
+    private client;
+    constructor(connection: RedisConnectionOptions, logger: LoggerService);
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    getClient(): Redis;
+    /** Publish to a pub/sub channel. Returns the number of subscribers that received it. */
+    publish(channel: string, message: string): Promise<number>;
+    /**
+     * A dedicated connection for SUBSCRIBE mode. A subscribing connection cannot run ordinary commands,
+     * which is why this is a separate socket rather than the shared client.
+     */
+    createSubscriber(): Redis;
+    /**
+     * Read-through JSON cache: return the cached value, otherwise run the loader, cache it and return.
+     *
+     * A loader that throws is NOT cached — the next call retries. A null/undefined result is returned but
+     * also NOT cached, so a miss (an unknown token, a deleted row) cannot poison the cache. Invalidate
+     * explicitly from whatever writes the source.
+     */
+    cacheJson<T>(key: string, ttlSec: number, loader: () => Promise<T>): Promise<T>;
+    invalidate(...keys: string[]): Promise<number>;
+    /**
+     * Run `fn` while holding a distributed lock (SET NX EX). Returns null WITHOUT running it when another
+     * instance holds the lock — that is the point: a periodic tick must do its work once per cluster, not
+     * once per replica.
+     *
+     * Release is a Lua compare-and-delete against a random token, so a lock that expired mid-run and was
+     * re-acquired elsewhere is never freed by the previous owner. `ttlSec` must exceed the worst-case
+     * runtime of `fn`, otherwise the lock can expire while the work is still going.
+     */
+    withLock<T>(key: string, ttlSec: number, fn: () => Promise<T>): Promise<T | null>;
+}

package/dist/redis/index.js

@@ -0,0 +1,127 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@smounters/core/decorators";
+import { LoggerService } from "@smounters/core/services";
+import Redis from "ioredis";
+// Redis as one injectable service: connection lifecycle, pub/sub, a read-through cache and a distributed
+// lock. Deliberately free of domain methods — anything that knows what an entity IS belongs to that
+// feature, not here, or every product ends up carrying the others' keys.
+export const REDIS_CONNECTION = Symbol("kit:redis-connection");
+const DEFAULTS = {
+    // A request should fail fast rather than hang while a command is retried forever.
+    maxRetriesPerRequest: 2,
+    enableOfflineQueue: true,
+};
+/**
+ * Register in the application with the connection supplied as a value provider — the package has no
+ * opinion on where configuration comes from:
+ *
+ * ```ts
+ * @Module({
+ *   providers: [{ provide: REDIS_CONNECTION, useValue: { url: appConfig.REDIS_URL } }, RedisService],
+ *   exports: [RedisService],
+ *   global: true,
+ * })
+ * export class RedisModule {}
+ * ```
+ */
+let RedisService = class RedisService {
+    constructor(connection, logger) {
+        this.connection = connection;
+        this.logger = logger;
+    }
+    async onModuleInit() {
+        this.client = new Redis(this.connection.url, { ...DEFAULTS, ...this.connection.options });
+        this.client.on("ready", () => this.logger.info({ type: "redis", event: "ready" }));
+        this.client.on("error", (err) => this.logger.warn({ type: "redis", event: "error", error: err.message }));
+        if (this.connection.awaitReady) {
+            await new Promise((resolve, reject) => {
+                this.client.once("ready", resolve);
+                this.client.once("error", reject);
+            });
+        }
+    }
+    async onModuleDestroy() {
+        try {
+            await this.client.quit();
+        }
+        catch {
+            this.client.disconnect();
+        }
+    }
+    getClient() {
+        return this.client;
+    }
+    /** Publish to a pub/sub channel. Returns the number of subscribers that received it. */
+    publish(channel, message) {
+        return this.client.publish(channel, message);
+    }
+    /**
+     * A dedicated connection for SUBSCRIBE mode. A subscribing connection cannot run ordinary commands,
+     * which is why this is a separate socket rather than the shared client.
+     */
+    createSubscriber() {
+        return this.client.duplicate();
+    }
+    /**
+     * Read-through JSON cache: return the cached value, otherwise run the loader, cache it and return.
+     *
+     * A loader that throws is NOT cached — the next call retries. A null/undefined result is returned but
+     * also NOT cached, so a miss (an unknown token, a deleted row) cannot poison the cache. Invalidate
+     * explicitly from whatever writes the source.
+     */
+    async cacheJson(key, ttlSec, loader) {
+        const hit = await this.client.get(key);
+        if (hit !== null)
+            return JSON.parse(hit);
+        const value = await loader();
+        if (value != null)
+            await this.client.set(key, JSON.stringify(value), "EX", ttlSec);
+        return value;
+    }
+    invalidate(...keys) {
+        return keys.length > 0 ? this.client.del(...keys) : Promise.resolve(0);
+    }
+    /**
+     * Run `fn` while holding a distributed lock (SET NX EX). Returns null WITHOUT running it when another
+     * instance holds the lock — that is the point: a periodic tick must do its work once per cluster, not
+     * once per replica.
+     *
+     * Release is a Lua compare-and-delete against a random token, so a lock that expired mid-run and was
+     * re-acquired elsewhere is never freed by the previous owner. `ttlSec` must exceed the worst-case
+     * runtime of `fn`, otherwise the lock can expire while the work is still going.
+     */
+    async withLock(key, ttlSec, fn) {
+        const token = randomUUID();
+        const acquired = await this.client.set(key, token, "EX", ttlSec, "NX");
+        if (acquired !== "OK")
+            return null;
+        try {
+            return await fn();
+        }
+        finally {
+            await this.client
+                .eval("if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end", 1, key, token)
+                // Releasing is best-effort: the lock expires on its own, and a failure here must not mask
+                // whatever fn returned or threw.
+                .catch(() => undefined);
+        }
+    }
+};
+RedisService = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS_CONNECTION)),
+    __metadata("design:paramtypes", [Object, LoggerService])
+], RedisService);
+export { RedisService };

package/dist/rpc/index.d.ts

@@ -0,0 +1,15 @@
+import type { BaseContext, Interceptor, NextFn } from "@smounters/core/core";
+/**
+ * Global protovalidate enforcement: every RPC request is checked against the `buf.validate` rules
+ * declared in its own proto BEFORE the handler runs; a violation becomes `InvalidArgument`.
+ *
+ * Register once as a global interceptor. The point is that validation rules live in the contract and are
+ * enforced by the transport — a handler cannot forget to check, and a rule added to the proto starts
+ * being enforced without touching any service. The Connect handler context carries the method
+ * descriptor, so the input schema is available generically, with no per-service wiring. Compiled rules
+ * are cached inside the validator, which is created once.
+ */
+export declare class ProtoValidateInterceptor implements Interceptor {
+    private readonly validator;
+    intercept(ctx: BaseContext, next: NextFn): Promise<unknown>;
+}

package/dist/rpc/index.js

@@ -0,0 +1,47 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { createValidator } from "@bufbuild/protovalidate";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { Injectable } from "@smounters/core/decorators";
+/**
+ * Global protovalidate enforcement: every RPC request is checked against the `buf.validate` rules
+ * declared in its own proto BEFORE the handler runs; a violation becomes `InvalidArgument`.
+ *
+ * Register once as a global interceptor. The point is that validation rules live in the contract and are
+ * enforced by the transport — a handler cannot forget to check, and a rule added to the proto starts
+ * being enforced without touching any service. The Connect handler context carries the method
+ * descriptor, so the input schema is available generically, with no per-service wiring. Compiled rules
+ * are cached inside the validator, which is created once.
+ */
+let ProtoValidateInterceptor = class ProtoValidateInterceptor {
+    constructor() {
+        this.validator = createValidator();
+    }
+    async intercept(ctx, next) {
+        if (ctx.getType() === "rpc") {
+            const rpc = ctx.switchToRpc();
+            const message = rpc.getData();
+            const handlerCtx = rpc.getContext();
+            const schema = handlerCtx?.method?.input;
+            if (schema && message) {
+                const result = this.validator.validate(schema, message);
+                if (result.kind === "invalid") {
+                    throw new ConnectError(`Validation failed: ${result.violations.map((v) => v.message).join("; ")}`, Code.InvalidArgument);
+                }
+                if (result.kind === "error") {
+                    // A rule failed to compile or evaluate: a server-side contract problem, not the caller's fault.
+                    throw new ConnectError(`Validation rule error: ${result.error.message}`, Code.Internal);
+                }
+            }
+        }
+        return next();
+    }
+};
+ProtoValidateInterceptor = __decorate([
+    Injectable()
+], ProtoValidateInterceptor);
+export { ProtoValidateInterceptor };

package/dist/util/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ULID (Universally Unique Lexicographically Sortable Identifier), spec-compliant: 26 chars of
+ * Crockford base32 = 48-bit millisecond timestamp (10 chars) + 80-bit randomness (16 chars).
+ *
+ * Time-ordered like UUIDv7 but a compact, URL-safe, opaque string — good for ids that travel to third
+ * parties (a webhook id a consumer dedups on, a public reference in a receipt). A fresh random suffix
+ * per call is enough at our volumes; there is no monotonicity guarantee inside one millisecond.
+ */
+export declare function ulid(nowMs?: number): string;
+/**
+ * Strip credentials before a payload is written somewhere long-lived (a delivery log row, an audit
+ * record, a support attachment). Two passes: token-like URL query params inside any string (a verify
+ * link in a mail body, a callback URL carrying a signing token) and object KEYS that name a credential.
+ *
+ * Structure is preserved so a stored payload can still be re-sent or diffed — only the secret VALUE is
+ * replaced. Returns a copy; the input is not mutated.
+ */
+export declare function redactSecrets<T>(value: T): T;

package/dist/util/index.js

@@ -0,0 +1,57 @@
+import { randomBytes } from "node:crypto";
+// Dependency-free helpers with no infrastructure of their own.
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; // excludes I, L, O, U
+function encodeTime(nowMs, len) {
+    let out = "";
+    let n = nowMs;
+    for (let i = len - 1; i >= 0; i--) {
+        const mod = n % 32;
+        out = CROCKFORD[mod] + out;
+        n = (n - mod) / 32;
+    }
+    return out;
+}
+function encodeRandom(len) {
+    let out = "";
+    for (const b of randomBytes(len))
+        out += CROCKFORD[b % 32];
+    return out;
+}
+/**
+ * ULID (Universally Unique Lexicographically Sortable Identifier), spec-compliant: 26 chars of
+ * Crockford base32 = 48-bit millisecond timestamp (10 chars) + 80-bit randomness (16 chars).
+ *
+ * Time-ordered like UUIDv7 but a compact, URL-safe, opaque string — good for ids that travel to third
+ * parties (a webhook id a consumer dedups on, a public reference in a receipt). A fresh random suffix
+ * per call is enough at our volumes; there is no monotonicity guarantee inside one millisecond.
+ */
+export function ulid(nowMs = Date.now()) {
+    return encodeTime(nowMs, 10) + encodeRandom(16);
+}
+const SECRET_QUERY_PARAM = /([?&](?:token|code|secret|key|otp|hmac|signature|password|apikey|api_key)=)[^&"'\s)]+/gi;
+const SECRET_KEY = /^(?:token|secret|password|apikey|api_key|authorization|hmac|secret_token|x-api-key|sm-api-key|sm-signature|sm-internal-token)$/i;
+const REDACTED = "[redacted]";
+/**
+ * Strip credentials before a payload is written somewhere long-lived (a delivery log row, an audit
+ * record, a support attachment). Two passes: token-like URL query params inside any string (a verify
+ * link in a mail body, a callback URL carrying a signing token) and object KEYS that name a credential.
+ *
+ * Structure is preserved so a stored payload can still be re-sent or diffed — only the secret VALUE is
+ * replaced. Returns a copy; the input is not mutated.
+ */
+export function redactSecrets(value) {
+    if (value == null)
+        return value;
+    if (typeof value === "string")
+        return value.replace(SECRET_QUERY_PARAM, `$1${REDACTED}`);
+    if (Array.isArray(value))
+        return value.map((v) => redactSecrets(v));
+    if (typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = SECRET_KEY.test(k) ? REDACTED : redactSecrets(v);
+        }
+        return out;
+    }
+    return value;
+}