@huloglobal/vendure-licence-sdk 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -4,7 +4,49 @@ All notable changes to `@huloglobal/vendure-licence-sdk` are documented here. Th
 format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
 this project adheres to [semantic versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] — Unreleased
+## [0.3.0]
+
+### Added
+- `startRetentionSweeper({ ... })` — schedules a recurring
+  `DELETE FROM <table> WHERE createdAt < ?` sweep that prunes rows
+  older than `options.days`. Optional `options.maxRows` adds a hard cap
+  on total rows (oldest pruned first when exceeded). `options.days = 0`
+  or `null` keeps everything (no pruning). Sweeper interval defaults to
+  24h, is `.unref()`d so it doesn't block shutdown, and runs first 60s
+  after start so boot stays snappy.
+- Shared security primitives module (`security.ts`), exported from the
+  package root:
+  - `verifyHmacSha256(body, signature, secret)` — timing-safe HMAC-SHA256
+    verification for webhooks. Tolerates the GitHub-style `sha256=`
+    prefix.
+  - `signValue(value, secret)` / `verifySignedValue(signed, secret)` —
+    HMAC tag a string so we can detect tampering when it round-trips
+    through a cookie or URL parameter. 64-bit tag keeps cookies short.
+  - `RateLimiter` — token-bucket rate limiter with an LRU cap on the
+    keyspace so a flood of keys can't grow memory.
+  - `applySecurityHeaders(res, { strict })` — recommended baseline of
+    security headers (X-Content-Type-Options, X-Frame-Options,
+    Referrer-Policy, Permissions-Policy, Cross-Origin-Resource-Policy).
+    `strict` adds a tight CSP for JSON / API endpoints.
+  - `isUrlOnAllowlist(url, allowedDomains)` — guards click redirectors
+    against being used as an open redirector. Supports wildcard suffixes
+    (`*.example.com`).
+  - `hashIp(ip, salt)` — sha256 IP hashing with a per-install salt.
+  - `randomToken(bytes)` — URL-safe random tokens for secrets / one-shot
+    nonces.
+
+## [0.2.0]
+
+### Added
+- **`UpdateChecker`** — polls the public npm registry every 24h for the
+  package's latest version. Exposes `current`, `latest`, `updateAvailable`,
+  `isMajor`, `lastCheckedAt`, `lastError`. Soft-fails on network errors
+  (keeps the previous cached value in memory). Each consuming plugin
+  surfaces its status via a `/status` endpoint so the admin dashboard
+  can render an "update available" banner.
+- `UpdateStatus` exported type.
+
+## [0.1.0]
 
 ### Added
 - Offline RSA-SHA256 JWT licence verification (`verifyLicence`).

package/dist/index.d.ts

@@ -21,4 +21,7 @@
 export { verifyLicence } from './verify';
 export { LicenceStatus, LicencePayload, VerifyLicenceOptions } from './types';
 export { RevocationChecker } from './revocation';
+export { UpdateChecker, UpdateStatus } from './update-check';
+export { verifyHmacSha256, signValue, verifySignedValue, RateLimiter, RateLimiterOptions, applySecurityHeaders, isUrlOnAllowlist, hashIp, randomToken, } from './security';
+export { startRetentionSweeper, RetentionOptions } from './retention';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EACH,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,MAAM,EACN,WAAW,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -20,9 +20,22 @@
  * tier. The end-user can always upgrade by supplying a valid key.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RevocationChecker = exports.verifyLicence = void 0;
+exports.startRetentionSweeper = exports.randomToken = exports.hashIp = exports.isUrlOnAllowlist = exports.applySecurityHeaders = exports.RateLimiter = exports.verifySignedValue = exports.signValue = exports.verifyHmacSha256 = exports.UpdateChecker = exports.RevocationChecker = exports.verifyLicence = void 0;
 var verify_1 = require("./verify");
 Object.defineProperty(exports, "verifyLicence", { enumerable: true, get: function () { return verify_1.verifyLicence; } });
 var revocation_1 = require("./revocation");
 Object.defineProperty(exports, "RevocationChecker", { enumerable: true, get: function () { return revocation_1.RevocationChecker; } });
+var update_check_1 = require("./update-check");
+Object.defineProperty(exports, "UpdateChecker", { enumerable: true, get: function () { return update_check_1.UpdateChecker; } });
+var security_1 = require("./security");
+Object.defineProperty(exports, "verifyHmacSha256", { enumerable: true, get: function () { return security_1.verifyHmacSha256; } });
+Object.defineProperty(exports, "signValue", { enumerable: true, get: function () { return security_1.signValue; } });
+Object.defineProperty(exports, "verifySignedValue", { enumerable: true, get: function () { return security_1.verifySignedValue; } });
+Object.defineProperty(exports, "RateLimiter", { enumerable: true, get: function () { return security_1.RateLimiter; } });
+Object.defineProperty(exports, "applySecurityHeaders", { enumerable: true, get: function () { return security_1.applySecurityHeaders; } });
+Object.defineProperty(exports, "isUrlOnAllowlist", { enumerable: true, get: function () { return security_1.isUrlOnAllowlist; } });
+Object.defineProperty(exports, "hashIp", { enumerable: true, get: function () { return security_1.hashIp; } });
+Object.defineProperty(exports, "randomToken", { enumerable: true, get: function () { return security_1.randomToken; } });
+var retention_1 = require("./retention");
+Object.defineProperty(exports, "startRetentionSweeper", { enumerable: true, get: function () { return retention_1.startRetentionSweeper; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAEH,mCAAyC;AAAhC,uGAAA,aAAa,OAAA;AAEtB,2CAAiD;AAAxC,+GAAA,iBAAiB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAEH,mCAAyC;AAAhC,uGAAA,aAAa,OAAA;AAEtB,2CAAiD;AAAxC,+GAAA,iBAAiB,OAAA;AAC1B,+CAA6D;AAApD,6GAAA,aAAa,OAAA;AACtB,uCAUoB;AAThB,4GAAA,gBAAgB,OAAA;AAChB,qGAAA,SAAS,OAAA;AACT,6GAAA,iBAAiB,OAAA;AACjB,uGAAA,WAAW,OAAA;AAEX,gHAAA,oBAAoB,OAAA;AACpB,4GAAA,gBAAgB,OAAA;AAChB,kGAAA,MAAM,OAAA;AACN,uGAAA,WAAW,OAAA;AAEf,yCAAsE;AAA7D,kHAAA,qBAAqB,OAAA"}

package/dist/retention.d.ts

@@ -0,0 +1,46 @@
+export interface RetentionOptions {
+    /**
+     * Maximum age in days. Rows older than this are deleted by the
+     * scheduled sweeper. `null` or `0` keeps everything (no pruning).
+     */
+    days: number | null;
+    /**
+     * Optional hard cap on total rows. When the table exceeds this,
+     * the oldest rows are pruned regardless of age. `null` disables
+     * this safety valve.
+     */
+    maxRows?: number | null;
+    /**
+     * How often the sweeper runs, in milliseconds. Default 24h. The
+     * sweeper is debounced to one run per process and is `.unref()`d
+     * so it doesn't keep the Node event loop alive.
+     */
+    sweepIntervalMs?: number;
+}
+/**
+ * Schedule a recurring `DELETE FROM <table> WHERE createdAt < ?` sweep
+ * that prunes rows older than `opts.days`. Optionally also caps total
+ * row count by `opts.maxRows`.
+ *
+ *   startRetentionSweeper({
+ *     getQueryRunner: () => connection.rawConnection,
+ *     table: 'email_log',
+ *     dateColumn: 'createdAt',
+ *     options: { days: 180 },
+ *   });
+ *
+ * Returns a stop function so tests can shut the sweeper down.
+ */
+export declare function startRetentionSweeper(input: {
+    /** Run a raw SQL query; returns a Promise of any result. Plugins
+     *  typically pass `() => connection.rawConnection`. */
+    getConnection: () => {
+        query: (sql: string, params?: any[]) => Promise<any>;
+    } | null;
+    table: string;
+    dateColumn?: string;
+    options: RetentionOptions;
+    /** Optional human-readable plugin name used in log lines. */
+    label?: string;
+}): () => void;
+//# sourceMappingURL=retention.d.ts.map

package/dist/retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../src/retention.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC7B;;;OAGG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IACzC;2DACuD;IACvD,aAAa,EAAE,MAAM;QAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IACrF,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,IAAI,CA4Db"}

package/dist/retention.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startRetentionSweeper = startRetentionSweeper;
+const core_1 = require("@vendure/core");
+const loggerCtx = 'LicenceSdk:Retention';
+/**
+ * Schedule a recurring `DELETE FROM <table> WHERE createdAt < ?` sweep
+ * that prunes rows older than `opts.days`. Optionally also caps total
+ * row count by `opts.maxRows`.
+ *
+ *   startRetentionSweeper({
+ *     getQueryRunner: () => connection.rawConnection,
+ *     table: 'email_log',
+ *     dateColumn: 'createdAt',
+ *     options: { days: 180 },
+ *   });
+ *
+ * Returns a stop function so tests can shut the sweeper down.
+ */
+function startRetentionSweeper(input) {
+    var _a;
+    const opts = input.options;
+    const interval = Math.max(60000, (_a = opts.sweepIntervalMs) !== null && _a !== void 0 ? _a : 24 * 60 * 60 * 1000);
+    const dateColumn = input.dateColumn || 'createdAt';
+    const label = input.label || input.table;
+    if ((!opts.days || opts.days <= 0) && !opts.maxRows) {
+        // Nothing to do — caller wants infinite retention.
+        return () => undefined;
+    }
+    let stopped = false;
+    let timer = null;
+    const sweep = async () => {
+        var _a, _b, _c, _d, _e, _f;
+        if (stopped)
+            return;
+        const conn = input.getConnection();
+        if (!conn)
+            return;
+        try {
+            if (opts.days && opts.days > 0) {
+                const res = await conn.query(`DELETE FROM \`${input.table}\` WHERE \`${dateColumn}\` < DATE_SUB(NOW(), INTERVAL ? DAY)`, [opts.days]);
+                const affected = ((_b = (_a = res === null || res === void 0 ? void 0 : res.affectedRows) !== null && _a !== void 0 ? _a : res === null || res === void 0 ? void 0 : res[1]) !== null && _b !== void 0 ? _b : 0);
+                if (affected) {
+                    core_1.Logger.info(`[${label}] pruned ${affected} row(s) older than ${opts.days}d`, loggerCtx);
+                }
+            }
+            if (opts.maxRows && opts.maxRows > 0) {
+                const countRows = await conn.query(`SELECT COUNT(*) AS n FROM \`${input.table}\``);
+                const total = Number((_d = (_c = countRows === null || countRows === void 0 ? void 0 : countRows[0]) === null || _c === void 0 ? void 0 : _c.n) !== null && _d !== void 0 ? _d : 0);
+                const over = total - opts.maxRows;
+                if (over > 0) {
+                    // Delete the `over` oldest rows.
+                    const res = await conn.query(`DELETE FROM \`${input.table}\` ORDER BY \`${dateColumn}\` ASC LIMIT ?`, [over]);
+                    const affected = ((_f = (_e = res === null || res === void 0 ? void 0 : res.affectedRows) !== null && _e !== void 0 ? _e : res === null || res === void 0 ? void 0 : res[1]) !== null && _f !== void 0 ? _f : 0);
+                    core_1.Logger.info(`[${label}] pruned ${affected} oldest row(s) — cap=${opts.maxRows}`, loggerCtx);
+                }
+            }
+        }
+        catch (e) {
+            core_1.Logger.warn(`[${label}] retention sweep failed: ${e === null || e === void 0 ? void 0 : e.message}`, loggerCtx);
+        }
+    };
+    // First sweep 60s after start (don't slow boot), then on the interval.
+    setTimeout(() => { void sweep(); }, 60000);
+    timer = setInterval(() => { void sweep(); }, interval);
+    if (typeof timer.unref === 'function')
+        timer.unref();
+    return () => {
+        stopped = true;
+        if (timer) {
+            clearInterval(timer);
+            timer = null;
+        }
+    };
+}
+//# sourceMappingURL=retention.js.map

package/dist/retention.js.map

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

package/dist/security.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Verify an HMAC-SHA256 hex signature against `body` using `secret`.
+ *
+ *   const ok = verifyHmacSha256(req.rawBody, req.header('x-signature'), secret);
+ *
+ * Constant-time comparison so the signature can't be brute-forced via
+ * timing. Returns `false` on any malformed input.
+ */
+export declare function verifyHmacSha256(body: string | Buffer, providedSignature: string | undefined | null, secret: string): boolean;
+/**
+ * Append a short HMAC tag to a value so we can detect tampering when the
+ * value round-trips through a cookie / URL parameter / form field.
+ *
+ *   const signed = signValue('visitor-abc', SECRET);
+ *   // -> 'visitor-abc.QRwy3...'
+ *
+ * The tag is 16 hex characters (64 bits) — enough to defeat brute-force
+ * for any value we sign here, while keeping cookies short.
+ */
+export declare function signValue(value: string, secret: string): string;
+/**
+ * Verify the tag and return the original value, or `null` if the tag
+ * doesn't match or the format is malformed.
+ */
+export declare function verifySignedValue(signed: string | undefined | null, secret: string): string | null;
+export interface RateLimiterOptions {
+    /** Allowed events per window. */
+    capacity: number;
+    /** Window length in milliseconds. */
+    windowMs: number;
+    /** Maximum tracked keys (LRU-evicted past this). Default 10 000. */
+    maxKeys?: number;
+}
+/**
+ * Token-bucket rate limiter with an LRU cap on the keyspace so we can't
+ * be DoS'd by an attacker pushing keys to grow memory. `allow(key)`
+ * returns `true` if the request fits in the bucket. Keys are arbitrary
+ * strings — typically `${ip}|${route}`.
+ */
+export declare class RateLimiter {
+    private readonly capacity;
+    private readonly windowMs;
+    private readonly maxKeys;
+    /** Map<key, [tokensRemaining, lastRefillEpochMs]>. JS Map preserves
+     *  insertion order, which is good enough LRU for this use. */
+    private readonly buckets;
+    constructor(opts: RateLimiterOptions);
+    allow(key: string, cost?: number): boolean;
+    private touchLru;
+    /** Reset all buckets — useful in tests. */
+    clear(): void;
+}
+/**
+ * Apply a recommended security-headers baseline to an Express response.
+ *
+ *   import { applySecurityHeaders } from '@huloglobal/vendure-licence-sdk';
+ *   applySecurityHeaders(res, { strict: true });
+ *
+ * `strict` adds a tight Content-Security-Policy suitable for JSON / API
+ * endpoints that never embed third-party content. For HTML responses
+ * that need styling / scripts, leave `strict` off and set your own CSP.
+ */
+export declare function applySecurityHeaders(res: {
+    setHeader: (name: string, value: string) => unknown;
+}, opts?: {
+    strict?: boolean;
+}): void;
+/**
+ * Returns `true` only when `url` parses as an http(s) URL and its
+ * hostname matches one of `allowedDomains`. Wildcard suffixes are
+ * supported — `*.example.com` matches `foo.example.com` and
+ * `bar.foo.example.com` but not `example.com`.
+ *
+ * Empty `allowedDomains` means "allow any http(s) URL" — the function
+ * still rejects `javascript:`, `data:`, `file:` and similar.
+ */
+export declare function isUrlOnAllowlist(url: string | undefined | null, allowedDomains: string[]): boolean;
+/**
+ * Hash an IP with a per-install salt so we can store it for unique-visitor
+ * counts without exposing the raw address. 32-char output (128 bits).
+ */
+export declare function hashIp(ip: string | null | undefined, salt: string): string | null;
+/** Generate a URL-safe random token of N bytes (base64url-encoded). */
+export declare function randomToken(bytes?: number): string;
+//# sourceMappingURL=security.d.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAsBA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC5B,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,iBAAiB,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAC5C,MAAM,EAAE,MAAM,GACf,OAAO,CAcT;AAID;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYlG;AAID,MAAM,WAAW,kBAAkB;IAC/B,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC;kEAC8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;gBAEnD,IAAI,EAAE,kBAAkB;IAMpC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO;IA4B7C,OAAO,CAAC,QAAQ;IAShB,2CAA2C;IAC3C,KAAK,IAAI,IAAI;CAChB;AAID;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IAAE,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAA;CAAE,EAAE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,IAAI,CASxI;AAID;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAuBlG;AAID;;;GAGG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGjF;AAID,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,KAAK,GAAE,MAAW,GAAG,MAAM,CAEtD"}

package/dist/security.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+exports.verifyHmacSha256 = verifyHmacSha256;
+exports.signValue = signValue;
+exports.verifySignedValue = verifySignedValue;
+exports.applySecurityHeaders = applySecurityHeaders;
+exports.isUrlOnAllowlist = isUrlOnAllowlist;
+exports.hashIp = hashIp;
+exports.randomToken = randomToken;
+/**
+ * Shared security primitives for HULO Vendure plugins.
+ *
+ *   - HMAC-SHA256 verification (timing-safe) for webhooks
+ *   - Signed-value helpers (sign / verify) — used to seal cookies,
+ *     query parameters and any other untrusted-channel value
+ *   - In-memory token-bucket rate limiter keyed by an arbitrary string
+ *   - Recommended security-headers helper for Express responses
+ *   - URL allowlist verifier — defends the click redirector from being
+ *     used as an open redirector
+ *   - One-shot IP hashing helper (sha256 with a per-install salt)
+ *
+ * All helpers are dependency-free (Node built-ins only) and run in
+ * sub-millisecond time on a modern CPU. They never throw — errors bubble
+ * out as `false` / `null` returns so the calling code never crashes a
+ * request on a hostile input.
+ */
+const crypto_1 = require("crypto");
+const url_1 = require("url");
+// ── HMAC ────────────────────────────────────────────────────────────────
+/**
+ * Verify an HMAC-SHA256 hex signature against `body` using `secret`.
+ *
+ *   const ok = verifyHmacSha256(req.rawBody, req.header('x-signature'), secret);
+ *
+ * Constant-time comparison so the signature can't be brute-forced via
+ * timing. Returns `false` on any malformed input.
+ */
+function verifyHmacSha256(body, providedSignature, secret) {
+    if (!secret || !providedSignature)
+        return false;
+    try {
+        // Tolerate both bare hex and the `sha256=<hex>` GitHub-style prefix.
+        const provided = providedSignature.replace(/^sha256=/, '').trim().toLowerCase();
+        if (!/^[a-f0-9]{64}$/.test(provided))
+            return false;
+        const expected = (0, crypto_1.createHmac)('sha256', secret).update(body).digest('hex');
+        const a = Buffer.from(expected, 'utf8');
+        const b = Buffer.from(provided, 'utf8');
+        if (a.length !== b.length)
+            return false;
+        return (0, crypto_1.timingSafeEqual)(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+// ── Signed values ──────────────────────────────────────────────────────
+/**
+ * Append a short HMAC tag to a value so we can detect tampering when the
+ * value round-trips through a cookie / URL parameter / form field.
+ *
+ *   const signed = signValue('visitor-abc', SECRET);
+ *   // -> 'visitor-abc.QRwy3...'
+ *
+ * The tag is 16 hex characters (64 bits) — enough to defeat brute-force
+ * for any value we sign here, while keeping cookies short.
+ */
+function signValue(value, secret) {
+    const tag = (0, crypto_1.createHmac)('sha256', secret).update(value).digest('hex').slice(0, 16);
+    return `${value}.${tag}`;
+}
+/**
+ * Verify the tag and return the original value, or `null` if the tag
+ * doesn't match or the format is malformed.
+ */
+function verifySignedValue(signed, secret) {
+    if (!signed || typeof signed !== 'string')
+        return null;
+    const lastDot = signed.lastIndexOf('.');
+    if (lastDot <= 0 || lastDot >= signed.length - 1)
+        return null;
+    const value = signed.slice(0, lastDot);
+    const tag = signed.slice(lastDot + 1).toLowerCase();
+    if (!/^[a-f0-9]{16}$/.test(tag))
+        return null;
+    const expected = (0, crypto_1.createHmac)('sha256', secret).update(value).digest('hex').slice(0, 16);
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(tag, 'utf8');
+    if (a.length !== b.length)
+        return null;
+    return (0, crypto_1.timingSafeEqual)(a, b) ? value : null;
+}
+/**
+ * Token-bucket rate limiter with an LRU cap on the keyspace so we can't
+ * be DoS'd by an attacker pushing keys to grow memory. `allow(key)`
+ * returns `true` if the request fits in the bucket. Keys are arbitrary
+ * strings — typically `${ip}|${route}`.
+ */
+class RateLimiter {
+    constructor(opts) {
+        /** Map<key, [tokensRemaining, lastRefillEpochMs]>. JS Map preserves
+         *  insertion order, which is good enough LRU for this use. */
+        this.buckets = new Map();
+        this.capacity = Math.max(1, opts.capacity);
+        this.windowMs = Math.max(1, opts.windowMs);
+        this.maxKeys = Math.max(100, opts.maxKeys || 10000);
+    }
+    allow(key, cost = 1) {
+        if (!key)
+            return true;
+        const now = Date.now();
+        const ratePerMs = this.capacity / this.windowMs;
+        let entry = this.buckets.get(key);
+        if (entry) {
+            const [tokens, last] = entry;
+            const refilled = Math.min(this.capacity, tokens + (now - last) * ratePerMs);
+            if (refilled < cost) {
+                // Update last so timing leaks aren't useful.
+                this.buckets.set(key, [refilled, now]);
+                this.touchLru(key);
+                return false;
+            }
+            this.buckets.set(key, [refilled - cost, now]);
+            this.touchLru(key);
+            return true;
+        }
+        // New key — start with a full bucket minus this request.
+        if (this.buckets.size >= this.maxKeys) {
+            // Drop the oldest entry (Map.keys() is insertion-ordered).
+            const oldest = this.buckets.keys().next().value;
+            if (oldest !== undefined)
+                this.buckets.delete(oldest);
+        }
+        this.buckets.set(key, [this.capacity - cost, now]);
+        return true;
+    }
+    touchLru(key) {
+        // Move to "most recently used" by re-inserting.
+        const entry = this.buckets.get(key);
+        if (entry) {
+            this.buckets.delete(key);
+            this.buckets.set(key, entry);
+        }
+    }
+    /** Reset all buckets — useful in tests. */
+    clear() { this.buckets.clear(); }
+}
+exports.RateLimiter = RateLimiter;
+// ── Security headers ───────────────────────────────────────────────────
+/**
+ * Apply a recommended security-headers baseline to an Express response.
+ *
+ *   import { applySecurityHeaders } from '@huloglobal/vendure-licence-sdk';
+ *   applySecurityHeaders(res, { strict: true });
+ *
+ * `strict` adds a tight Content-Security-Policy suitable for JSON / API
+ * endpoints that never embed third-party content. For HTML responses
+ * that need styling / scripts, leave `strict` off and set your own CSP.
+ */
+function applySecurityHeaders(res, opts = {}) {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', 'DENY');
+    res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+    res.setHeader('Permissions-Policy', 'geolocation=(), camera=(), microphone=(), payment=()');
+    res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
+    if (opts.strict) {
+        res.setHeader('Content-Security-Policy', "default-src 'none'; frame-ancestors 'none'");
+    }
+}
+// ── URL allowlist ──────────────────────────────────────────────────────
+/**
+ * Returns `true` only when `url` parses as an http(s) URL and its
+ * hostname matches one of `allowedDomains`. Wildcard suffixes are
+ * supported — `*.example.com` matches `foo.example.com` and
+ * `bar.foo.example.com` but not `example.com`.
+ *
+ * Empty `allowedDomains` means "allow any http(s) URL" — the function
+ * still rejects `javascript:`, `data:`, `file:` and similar.
+ */
+function isUrlOnAllowlist(url, allowedDomains) {
+    if (!url || typeof url !== 'string')
+        return false;
+    let parsed;
+    try {
+        parsed = new url_1.URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return false;
+    if (!(allowedDomains === null || allowedDomains === void 0 ? void 0 : allowedDomains.length))
+        return true;
+    const host = parsed.hostname.toLowerCase();
+    for (const allowed of allowedDomains) {
+        const norm = allowed.trim().toLowerCase();
+        if (!norm)
+            continue;
+        if (norm.startsWith('*.')) {
+            const suffix = norm.slice(2);
+            if (host === suffix)
+                continue; // *.example.com must NOT match example.com
+            if (host.endsWith('.' + suffix))
+                return true;
+        }
+        else if (host === norm) {
+            return true;
+        }
+    }
+    return false;
+}
+// ── IP hashing ─────────────────────────────────────────────────────────
+/**
+ * Hash an IP with a per-install salt so we can store it for unique-visitor
+ * counts without exposing the raw address. 32-char output (128 bits).
+ */
+function hashIp(ip, salt) {
+    if (!ip)
+        return null;
+    return (0, crypto_1.createHash)('sha256').update(salt + '|' + ip).digest('hex').slice(0, 32);
+}
+// ── Random ─────────────────────────────────────────────────────────────
+/** Generate a URL-safe random token of N bytes (base64url-encoded). */
+function randomToken(bytes = 32) {
+    return (0, crypto_1.randomBytes)(bytes).toString('base64url');
+}
+//# sourceMappingURL=security.js.map

package/dist/security.js.map

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

package/dist/update-check.d.ts

@@ -0,0 +1,40 @@
+export interface UpdateStatus {
+    packageName: string;
+    current: string;
+    latest: string | null;
+    updateAvailable: boolean;
+    /** A "major"-level update is one where the first non-zero version
+     *  component changes (semver-friendly for 0.x packages). */
+    isMajor: boolean;
+    lastCheckedAt: Date | null;
+    lastError: string | null;
+}
+/**
+ * Polls the public npm registry for the latest version of a plugin's
+ * package and exposes a small status object. Each plugin instantiates
+ * one UpdateChecker at boot and surfaces its status via its `/status`
+ * endpoint — the admin UI then shows an "update available" banner.
+ *
+ * Failures (network, 404) keep the previous cached `latest` value in
+ * memory so a brief npm outage doesn't make the dashboard misreport.
+ * The cache is wiped only when a fresh value arrives.
+ */
+export declare class UpdateChecker {
+    private readonly packageName;
+    private readonly currentVersion;
+    private readonly pollMs;
+    private readonly registryUrl;
+    private latest;
+    private timer;
+    private lastCheckedAt;
+    private lastError;
+    constructor(packageName: string, currentVersion: string, pollMs?: number, // 24h
+    registryUrl?: string);
+    /** Start the background poll. Idempotent. */
+    start(): void;
+    stop(): void;
+    /** Force a fresh check. Returns the new status. */
+    refresh(): Promise<UpdateStatus>;
+    getStatus(): UpdateStatus;
+}
+//# sourceMappingURL=update-check.d.ts.map

package/dist/update-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../src/update-check.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB;gEAC4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAa;IAOlB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAThC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,SAAS,CAAuB;gBAGnB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,MAAM,GAAE,MAA4B,EAAE,MAAM;IAC5C,WAAW,GAAE,MAAqC;IAGvE,6CAA6C;IAC7C,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;IAOZ,mDAAmD;IAC7C,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC;IAkCtC,SAAS,IAAI,YAAY;CAe5B"}

package/dist/update-check.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpdateChecker = void 0;
+const core_1 = require("@vendure/core");
+const loggerCtx = 'LicenceSdk:UpdateCheck';
+/**
+ * Polls the public npm registry for the latest version of a plugin's
+ * package and exposes a small status object. Each plugin instantiates
+ * one UpdateChecker at boot and surfaces its status via its `/status`
+ * endpoint — the admin UI then shows an "update available" banner.
+ *
+ * Failures (network, 404) keep the previous cached `latest` value in
+ * memory so a brief npm outage doesn't make the dashboard misreport.
+ * The cache is wiped only when a fresh value arrives.
+ */
+class UpdateChecker {
+    constructor(packageName, currentVersion, pollMs = 24 * 60 * 60 * 1000, // 24h
+    registryUrl = 'https://registry.npmjs.org') {
+        this.packageName = packageName;
+        this.currentVersion = currentVersion;
+        this.pollMs = pollMs;
+        this.registryUrl = registryUrl;
+        this.latest = null;
+        this.timer = null;
+        this.lastCheckedAt = null;
+        this.lastError = null;
+    }
+    /** Start the background poll. Idempotent. */
+    start() {
+        if (this.timer)
+            return;
+        // First check runs 30s after boot so we don't slow down startup.
+        setTimeout(() => this.refresh().catch(() => undefined), 30000);
+        this.timer = setInterval(() => this.refresh().catch(() => undefined), this.pollMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Force a fresh check. Returns the new status. */
+    async refresh() {
+        const controller = new AbortController();
+        const t = setTimeout(() => controller.abort(), 8000);
+        try {
+            // The `latest` endpoint is small (a few hundred bytes) and
+            // cache-friendly — the registry returns a fresh dist-tags
+            // entry without the full package metadata payload.
+            const res = await fetch(`${this.registryUrl}/${encodeURIComponent(this.packageName)}/latest`, { signal: controller.signal, headers: { accept: 'application/json' } });
+            if (!res.ok) {
+                this.lastError = `npm registry ${res.status}`;
+                core_1.Logger.warn(`Update check for ${this.packageName} failed: ${this.lastError}`, loggerCtx);
+                return this.getStatus();
+            }
+            const body = await res.json();
+            const next = String((body === null || body === void 0 ? void 0 : body.version) || '').trim();
+            if (!next) {
+                this.lastError = 'no version in response';
+                return this.getStatus();
+            }
+            this.latest = next;
+            this.lastCheckedAt = new Date();
+            this.lastError = null;
+        }
+        catch (e) {
+            this.lastError = (e === null || e === void 0 ? void 0 : e.message) || 'fetch failed';
+            core_1.Logger.warn(`Update check for ${this.packageName} failed: ${this.lastError}`, loggerCtx);
+        }
+        finally {
+            clearTimeout(t);
+        }
+        return this.getStatus();
+    }
+    getStatus() {
+        const updateAvailable = !!this.latest && compareVersions(this.latest, this.currentVersion) > 0;
+        const isMajor = updateAvailable
+            ? isMajorBump(this.currentVersion, this.latest)
+            : false;
+        return {
+            packageName: this.packageName,
+            current: this.currentVersion,
+            latest: this.latest,
+            updateAvailable,
+            isMajor,
+            lastCheckedAt: this.lastCheckedAt,
+            lastError: this.lastError,
+        };
+    }
+}
+exports.UpdateChecker = UpdateChecker;
+/**
+ * Tiny semver-ish compare. Treats versions as dot-separated number
+ * components; suffix tags (`-rc.1`, `-beta`) sort before the release.
+ * Sufficient for our case — both sides come from npm dist-tags.
+ */
+function compareVersions(a, b) {
+    const [ah, at] = splitTag(a);
+    const [bh, bt] = splitTag(b);
+    const ap = ah.split('.').map(n => parseInt(n, 10) || 0);
+    const bp = bh.split('.').map(n => parseInt(n, 10) || 0);
+    const len = Math.max(ap.length, bp.length);
+    for (let i = 0; i < len; i++) {
+        const av = ap[i] || 0;
+        const bv = bp[i] || 0;
+        if (av !== bv)
+            return av - bv;
+    }
+    // Pre-release sorts BEFORE release (0.2.0-rc.1 < 0.2.0).
+    if (at && !bt)
+        return -1;
+    if (!at && bt)
+        return 1;
+    if (at && bt)
+        return at.localeCompare(bt);
+    return 0;
+}
+function splitTag(v) {
+    const dash = v.indexOf('-');
+    return dash === -1 ? [v, ''] : [v.slice(0, dash), v.slice(dash + 1)];
+}
+/**
+ * "Major bump" for the dashboard banner — uses the first non-zero
+ * version component as the major identifier (so 0.2.x → 0.3.x is major
+ * for 0.x packages, where the user expects breaking changes in 0.y
+ * bumps).
+ */
+function isMajorBump(current, next) {
+    const cp = current.split('.').map(n => parseInt(n, 10) || 0);
+    const np = next.split('.').map(n => parseInt(n, 10) || 0);
+    // Find the first non-zero index of current.
+    let i = 0;
+    while (i < cp.length && cp[i] === 0)
+        i++;
+    return (cp[i] || 0) !== (np[i] || 0);
+}
+//# sourceMappingURL=update-check.js.map

package/dist/update-check.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@huloglobal/vendure-licence-sdk",
-    "version": "0.1.0",
+    "version": "0.3.0",
     "description": "Licence validation helpers for HULO Vendure plugins. JWT verification, revocation polling and an admin status check used by paid HULO plugins to confirm the host installation is licensed.",
     "license": "SEE LICENSE IN LICENSE",
     "author": "Wayne Garrison <wayne@garrison.me.uk>",