@zedtech/zedkit-server 0.0.0 → 0.1.1

package/README.md

@@ -1,18 +1,32 @@
 # @zedtech/zedkit-server
 
-Server-side helpers with a stable public surface. Original work by the
+[![npm version](https://img.shields.io/npm/v/@zedtech/zedkit-server.svg)](https://www.npmjs.com/package/@zedtech/zedkit-server)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/zedtech-fr/zedkit/blob/main/LICENSE)
+
+Harden any Node server in minutes: in-process rate limiting, secret/PII
+redaction for logs, HKDF crypto and HTTP helpers. Original work by the
 same author. Zero runtime dependencies.
 
+## Install
+
 ```sh
 pnpm add @zedtech/zedkit-server
 ```
 
+## Usage
+
 ```ts
 import { redactValue } from "@zedtech/zedkit-server";
 
 logger.info({ event: "login", user: redactValue(user) });
 ```
 
+## When to use
+
+Reach for this package when you rate-limit, redact logs, sign webhooks,
+or read database error codes on a Node server. For typed errors and IDs
+see `@zedtech/zedkit-core` instead.
+
 ## API
 
 - `MemoryRateLimiter` — fixed-window, in-process rate limiting:

package/dist/backoff.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Retry backoff: 2s x 3^(n-1) with +/-20% jitter, floored at 1s and
+ * capped at 1h. attemptNo is 1-based (the attempt that just failed).
+ * `random` is injectable so tests are deterministic.
+ */
+export declare function computeBackoffMs(attemptNo: number, random?: () => number): number;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,MAAM,MAAoB,GACjC,MAAM,CAUR"}

package/dist/backoff.js

@@ -0,0 +1,18 @@
+// Original work by the same author.
+/**
+ * Retry backoff: 2s x 3^(n-1) with +/-20% jitter, floored at 1s and
+ * capped at 1h. attemptNo is 1-based (the attempt that just failed).
+ * `random` is injectable so tests are deterministic.
+ */
+export function computeBackoffMs(attemptNo, random = Math.random) {
+    if (!Number.isInteger(attemptNo) || attemptNo < 1) {
+        throw new Error(`attempt number must be a positive integer, got ${attemptNo}`);
+    }
+    const base = Math.min(2_000 * 3 ** (attemptNo - 1), 3_600_000);
+    const drawn = random();
+    // A broken custom RNG must not collapse delays into a retry storm.
+    const factor = Number.isFinite(drawn) ? 0.8 + 0.4 * drawn : 1;
+    const jittered = Math.round(base * factor);
+    return Math.max(1_000, Math.min(jittered, 3_600_000));
+}
+//# sourceMappingURL=backoff.js.map

package/dist/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,SAAuB,IAAI,CAAC,MAAM;IAElC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,kDAAkD,SAAS,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC;IACvB,mEAAmE;IACnE,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC;IAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { pgErrorCode } from "./pg-error.js";
+export { MemoryRateLimiter } from "./rate-limit.js";
+export { redactValue } from "./redaction.js";
+export { computeBackoffMs } from "./backoff.js";
+export { verifyWebhookSignatureHeader, type VerifyWebhookOptions, webhookSignatureHeader, } from "./webhook-signature.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,4BAA4B,EAC5B,KAAK,oBAAoB,EACzB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { pgErrorCode } from "./pg-error.js";
+export { MemoryRateLimiter } from "./rate-limit.js";
+export { redactValue } from "./redaction.js";
+export { computeBackoffMs } from "./backoff.js";
+export { verifyWebhookSignatureHeader, webhookSignatureHeader, } from "./webhook-signature.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,4BAA4B,EAE5B,sBAAsB,GACvB,MAAM,wBAAwB,CAAC"}

package/dist/pg-error.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reads the Postgres error code (`23505` unique, `23503` FK, ...) from a
+ * thrown value. Lets callers decide conflict-vs-bug without each
+ * keeping its own shape check.
+ */
+export declare function pgErrorCode(error: unknown): string | null;
+//# sourceMappingURL=pg-error.d.ts.map

package/dist/pg-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-error.d.ts","sourceRoot":"","sources":["../src/pg-error.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAMzD"}

package/dist/pg-error.js

@@ -0,0 +1,14 @@
+// Original work by the same author.
+/**
+ * Reads the Postgres error code (`23505` unique, `23503` FK, ...) from a
+ * thrown value. Lets callers decide conflict-vs-bug without each
+ * keeping its own shape check.
+ */
+export function pgErrorCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return null;
+    }
+    const code = error.code;
+    return typeof code === "string" ? code : null;
+}
+//# sourceMappingURL=pg-error.js.map

package/dist/pg-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-error.js","sourceRoot":"","sources":["../src/pg-error.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAI,KAA2B,CAAC,IAAI,CAAC;IAC/C,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC"}

package/dist/rate-limit.d.ts

@@ -0,0 +1,7 @@
+export declare class MemoryRateLimiter {
+    private readonly windows;
+    private lastGc;
+    allow(key: string, limitPerMinute: number): boolean;
+    private maybeGc;
+}
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AASA,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuD;IAC/E,OAAO,CAAC,MAAM,CAAK;IAEnB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO;IAiBnD,OAAO,CAAC,OAAO;CAQhB"}

package/dist/rate-limit.js

@@ -0,0 +1,42 @@
+// Original work by the same author.
+/**
+ * Fixed-window rate limiter, in-process. Correct for single-instance
+ * deployments; multi-instance enforcement needs a shared store behind the
+ * same allow() shape.
+ */
+const WINDOW_MS = 60_000;
+const MAX_KEYS_BEFORE_GC = 10_000;
+export class MemoryRateLimiter {
+    windows = new Map();
+    lastGc = 0;
+    allow(key, limitPerMinute) {
+        // Fail closed on misconfiguration: a non-positive limit denies.
+        if (!(limitPerMinute >= 1))
+            return false;
+        const now = Date.now();
+        const current = this.windows.get(key);
+        if (!current || now - current.start >= WINDOW_MS) {
+            this.maybeGc(now);
+            this.windows.set(key, { start: now, count: 1 });
+            return true;
+        }
+        if (current.count >= limitPerMinute)
+            return false;
+        current.count += 1;
+        return true;
+    }
+    // Drops expired windows, but at most once per window: past the key
+    // cap, every insert would otherwise pay a full-map scan.
+    maybeGc(now) {
+        if (this.windows.size <= MAX_KEYS_BEFORE_GC)
+            return;
+        if (now - this.lastGc < WINDOW_MS)
+            return;
+        this.lastGc = now;
+        for (const [k, v] of this.windows) {
+            if (now - v.start >= WINDOW_MS)
+                this.windows.delete(k);
+        }
+    }
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC;;;;GAIG;AACH,MAAM,SAAS,GAAG,MAAM,CAAC;AACzB,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC,MAAM,OAAO,iBAAiB;IACX,OAAO,GAAG,IAAI,GAAG,EAA4C,CAAC;IACvE,MAAM,GAAG,CAAC,CAAC;IAEnB,KAAK,CAAC,GAAW,EAAE,cAAsB;QACvC,gEAAgE;QAChE,IAAI,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO,IAAI,GAAG,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,EAAE,CAAC;YACjD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAClB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YAChD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,OAAO,CAAC,KAAK,IAAI,cAAc;YAAE,OAAO,KAAK,CAAC;QAClD,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,mEAAmE;IACnE,yDAAyD;IACjD,OAAO,CAAC,GAAW;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,kBAAkB;YAAE,OAAO;QACpD,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,SAAS;YAAE,OAAO;QAC1C,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;QAClB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,GAAG,GAAG,CAAC,CAAC,KAAK,IAAI,SAAS;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;CACF"}

package/dist/redaction.d.ts

@@ -0,0 +1,2 @@
+export declare function redactValue(value: unknown, key?: string): unknown;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AAkCA,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAEjE"}

package/dist/redaction.js

@@ -0,0 +1,69 @@
+// Original work by the same author. Generalized from a logger helper: the
+// private key-material pattern was dropped; only generic secret shapes
+// (secret-like keys, bearer/basic tokens) and long-value truncation remain.
+/**
+ * Recursively replace credential-looking material with placeholders, so a
+ * structure is safe to log. Objects keep their shape and prototype; values
+ * under secret-like keys become "[redacted]", bearer/basic tokens become
+ * "<scheme> [redacted]", and cyclic references become "[circular]".
+ * Scrubbing applies to every field; truncation is volume control only (a
+ * cut secret still leaks its head), so human-text fields (`msg`,
+ * `message`, `stack`) are never truncated and everything else is bounded
+ * at 512 code points. Dates and regexes pass through untouched; Maps,
+ * Sets, and symbol keys are preserved.
+ */
+const SECRET_KEY_PATTERN = /(api[_-]?key|secret|token|password|passwd|signature|authorization|cookie|set-cookie|private[_-]?key|credentials)/i;
+const AUTH_TOKEN_PATTERN = /\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi;
+const HUMAN_TEXT_KEYS = new Set(["msg", "message", "stack"]);
+const LONG_VALUE_MAX = 512;
+function redactString(value, key) {
+    const scrubbed = value.replace(AUTH_TOKEN_PATTERN, (match) => `${match.split(/\s/, 1)[0]} [redacted]`);
+    if (key !== undefined && HUMAN_TEXT_KEYS.has(key.toLowerCase()))
+        return scrubbed;
+    // Count in code points so truncation never splits a surrogate pair.
+    const chars = Array.from(scrubbed);
+    if (chars.length > LONG_VALUE_MAX) {
+        return `${chars.slice(0, LONG_VALUE_MAX).join("")}…`;
+    }
+    return scrubbed;
+}
+export function redactValue(value, key) {
+    return redactInner(value, key, new Set());
+}
+function redactInner(value, key, seen) {
+    if (key !== undefined && SECRET_KEY_PATTERN.test(key)) {
+        return "[redacted]";
+    }
+    if (typeof value === "string") {
+        return redactString(value, key);
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (seen.has(value)) {
+        return "[circular]";
+    }
+    seen.add(value);
+    if (value instanceof Date || value instanceof RegExp) {
+        return value;
+    }
+    if (value instanceof Map) {
+        return new Map([...value].map(([k, v]) => [
+            k,
+            redactInner(v, typeof k === "string" ? k : undefined, seen),
+        ]));
+    }
+    if (value instanceof Set) {
+        return new Set([...value].map((v) => redactInner(v, undefined, seen)));
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => redactInner(v, undefined, seen));
+    }
+    const source = value;
+    const out = Object.create(Object.getPrototypeOf(value));
+    for (const k of Reflect.ownKeys(source)) {
+        out[k] = redactInner(source[k], typeof k === "string" ? k : undefined, seen);
+    }
+    return out;
+}
+//# sourceMappingURL=redaction.js.map

package/dist/redaction.js.map

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

package/dist/webhook-signature.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Stripe-style signature header binding timestamp and exact body bytes:
+ * `t=<unix-seconds>,v1=<hex hmac-sha256(secret, "<ts>.<body>")>`.
+ * Receivers recompute over the raw bytes they received. Bring your own
+ * secret (32+ random bytes); version rotation stays in the consumer.
+ */
+export declare function webhookSignatureHeader(secret: Buffer, body: Buffer, timestamp: string): string;
+export interface VerifyWebhookOptions {
+    /**
+     * Reject signatures older than this, in seconds. Omit for no freshness
+     * check. Fold clock skew into the value; future timestamps are rejected.
+     */
+    maxAgeSeconds?: number;
+    /** Clock for the freshness check (injectable for tests). Defaults to Date.now. */
+    now?: () => number;
+}
+/** Recompute the header over the received bytes and compare timing-safely. */
+export declare function verifyWebhookSignatureHeader(secret: Buffer, body: Buffer, header: string | null | undefined, options?: VerifyWebhookOptions): boolean;
+//# sourceMappingURL=webhook-signature.d.ts.map

package/dist/webhook-signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-signature.d.ts","sourceRoot":"","sources":["../src/webhook-signature.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,CAMR;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,8EAA8E;AAC9E,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAwBT"}

package/dist/webhook-signature.js

@@ -0,0 +1,48 @@
+// Sign ported from production delivery code; verify mirrors it with a
+// timing-safe compare. Original work by the same author.
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Stripe-style signature header binding timestamp and exact body bytes:
+ * `t=<unix-seconds>,v1=<hex hmac-sha256(secret, "<ts>.<body>")>`.
+ * Receivers recompute over the raw bytes they received. Bring your own
+ * secret (32+ random bytes); version rotation stays in the consumer.
+ */
+export function webhookSignatureHeader(secret, body, timestamp) {
+    const mac = createHmac("sha256", secret)
+        .update(`${timestamp}.`, "utf8")
+        .update(body)
+        .digest("hex");
+    return `t=${timestamp},v1=${mac}`;
+}
+/** Recompute the header over the received bytes and compare timing-safely. */
+export function verifyWebhookSignatureHeader(secret, body, header, options = {}) {
+    if (!header)
+        return false;
+    if (secret == null || body == null)
+        return false;
+    const match = /^t=(\d+),v1=([0-9a-f]+)$/.exec(header);
+    if (!match)
+        return false;
+    const timestamp = match[1];
+    if (timestamp === undefined)
+        return false;
+    const expected = webhookSignatureHeader(secret, body, timestamp);
+    const a = Buffer.from(header, "utf8");
+    const b = Buffer.from(expected, "utf8");
+    if (a.length !== b.length || !timingSafeEqual(a, b))
+        return false;
+    if (options.maxAgeSeconds !== undefined) {
+        // A NaN or negative maxAge (e.g. from config parsing) must fail closed,
+        // never silently disable replay protection.
+        if (!Number.isFinite(options.maxAgeSeconds) || options.maxAgeSeconds < 0) {
+            return false;
+        }
+        const now = options.now ? options.now() : Date.now();
+        const ageMs = now - Number(timestamp) * 1000;
+        if (!Number.isFinite(ageMs) || ageMs < 0 || ageMs > options.maxAgeSeconds * 1000) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=webhook-signature.js.map

package/dist/webhook-signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-signature.js","sourceRoot":"","sources":["../src/webhook-signature.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,yDAAyD;AACzD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAc,EACd,IAAY,EACZ,SAAiB;IAEjB,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;SACrC,MAAM,CAAC,GAAG,SAAS,GAAG,EAAE,MAAM,CAAC;SAC/B,MAAM,CAAC,IAAI,CAAC;SACZ,MAAM,CAAC,KAAK,CAAC,CAAC;IACjB,OAAO,KAAK,SAAS,OAAO,GAAG,EAAE,CAAC;AACpC,CAAC;AAYD,8EAA8E;AAC9E,MAAM,UAAU,4BAA4B,CAC1C,MAAc,EACd,IAAY,EACZ,MAAiC,EACjC,UAAgC,EAAE;IAElC,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,IAAI,MAAM,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IACjD,MAAM,KAAK,GAAG,0BAA0B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC1C,MAAM,QAAQ,GAAG,sBAAsB,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACjE,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAClE,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACxC,wEAAwE;QACxE,4CAA4C;QAC5C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,aAAa,GAAG,CAAC,EAAE,CAAC;YACzE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACrD,MAAM,KAAK,GAAG,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;QAC7C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,EAAE,CAAC;YACjF,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,11 +1,29 @@
 {
   "name": "@zedtech/zedkit-server",
-  "version": "0.0.0",
+  "version": "0.1.1",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "description": "Server helpers: in-process rate limiting, secret redaction. Original work by the same author.",
+  "description": "Harden any Node server in minutes: in-process rate limiting, secret/PII redaction for logs, HKDF crypto and HTTP helpers. Original work by the same author.",
+  "keywords": [
+    "nodejs",
+    "server",
+    "rate-limit",
+    "rate-limiting",
+    "redaction",
+    "pii",
+    "secrets",
+    "logging",
+    "hkdf",
+    "crypto",
+    "http",
+    "zero-dependency"
+  ],
+  "homepage": "https://github.com/zedtech-fr/zedkit/tree/main/packages/server",
+  "bugs": {
+    "url": "https://github.com/zedtech-fr/zedkit/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",