seqpulse 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Nassir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# seqpulse (Node.js SDK)
+
+SeqPulse SDK for:
+
+- HTTP metrics instrumentation
+- metrics endpoint exposure
+- optional HMAC v2 validation on inbound SeqPulse calls
+
+## Install
+
+```bash
+npm install seqpulse
+# or
+pnpm add seqpulse
+```
+
+## Express usage
+
+```js
+const express = require("express");
+const seqpulse = require("seqpulse");
+
+const app = express();
+
+seqpulse.init({
+  apiKey: process.env.SEQPULSE_API_KEY,
+  endpoint: "/seqpulse-metrics",
+  hmacEnabled: process.env.SEQPULSE_HMAC_ENABLED === "true",
+  hmacSecret: process.env.SEQPULSE_HMAC_SECRET,
+});
+
+app.use(seqpulse.metrics());
+
+app.get("/", (_req, res) => res.send("ok"));
+
+app.listen(3000, () => {
+  console.log("Running on :3000");
+});
+```
+
+## Returned payload
+
+`GET /seqpulse-metrics` returns:
+
+```json
+{
+  "metrics": {
+    "requests_per_sec": 0.25,
+    "latency_p95": 31.221,
+    "error_rate": 0,
+    "cpu_usage": 0.42,
+    "memory_usage": 0.18
+  }
+}
+```
+
+## Notes
+
+- This SDK does not manage CI/CD trigger/finish workflow.
+- `apiKey` is required for config consistency, but not used directly in endpoint responses.
+
+## Local smoke test
+
+```bash
+npm run smoke
+```

package/index.d.ts

@@ -0,0 +1,26 @@
+export type SeqPulseInitConfig = {
+  apiKey: string
+  endpoint?: string
+  windowSeconds?: number
+  hmacEnabled?: boolean
+  hmacSecret?: string
+  maxSkewPastSeconds?: number
+  maxSkewFutureSeconds?: number
+}
+
+export type SeqPulseMetrics = {
+  requests_per_sec: number
+  latency_p95: number
+  error_rate: number
+  cpu_usage: number
+  memory_usage: number
+}
+
+export type SeqPulseInstance = {
+  init(config: SeqPulseInitConfig): void
+  metrics(): (req: any, res: any, next: () => void) => void
+  getMetricsSnapshot(): SeqPulseMetrics
+}
+
+declare const seqpulse: SeqPulseInstance
+export = seqpulse

package/index.js

@@ -0,0 +1,207 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const os = require("node:os");
+
+const DEFAULT_WINDOW_SECONDS = 60;
+const DEFAULT_ENDPOINT = "/seqpulse-metrics";
+const DEFAULT_MAX_SKEW_PAST_SECONDS = 300;
+const DEFAULT_MAX_SKEW_FUTURE_SECONDS = 30;
+
+const state = {
+  initialized: false,
+  config: {
+    apiKey: "",
+    endpoint: DEFAULT_ENDPOINT,
+    windowSeconds: DEFAULT_WINDOW_SECONDS,
+    hmacEnabled: false,
+    hmacSecret: "",
+    maxSkewPastSeconds: DEFAULT_MAX_SKEW_PAST_SECONDS,
+    maxSkewFutureSeconds: DEFAULT_MAX_SKEW_FUTURE_SECONDS,
+  },
+  samples: [],
+  nonceSeenAt: new Map(),
+};
+
+function canonicalizePath(path) {
+  if (!path) return "/";
+  let normalized = String(path);
+  if (!normalized.startsWith("/")) normalized = `/${normalized}`;
+  if (normalized !== "/" && normalized.endsWith("/")) normalized = normalized.slice(0, -1);
+  return normalized;
+}
+
+function nowMs() {
+  return Date.now();
+}
+
+function percentile95(values) {
+  if (!values.length) return 0;
+  const sorted = values.slice().sort((a, b) => a - b);
+  const idx = Math.floor(0.95 * (sorted.length - 1));
+  return sorted[idx];
+}
+
+function round(value, digits) {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+
+function cleanupOldSamples() {
+  const cutoff = nowMs() - state.config.windowSeconds * 1000;
+  state.samples = state.samples.filter((item) => item.atMs >= cutoff);
+}
+
+function cleanupOldNonces() {
+  const ttlMs = (state.config.maxSkewPastSeconds + state.config.maxSkewFutureSeconds) * 1000;
+  const cutoff = nowMs() - ttlMs;
+  for (const [nonce, seenAt] of state.nonceSeenAt.entries()) {
+    if (seenAt < cutoff) state.nonceSeenAt.delete(nonce);
+  }
+}
+
+function buildSignature(secret, timestamp, method, path, nonce) {
+  const payload = `${timestamp}|${String(method || "GET").toUpperCase()}|${canonicalizePath(path)}|${nonce}`;
+  const digest = crypto.createHmac("sha256", secret).update(payload).digest("hex");
+  return `sha256=${digest}`;
+}
+
+function rejectHmac(res, message) {
+  res.status(401).json({ error: message || "Unauthorized" });
+}
+
+function validateTimestamp(ts) {
+  if (!ts) throw new Error("Missing timestamp");
+  const sentMs = Date.parse(ts);
+  if (Number.isNaN(sentMs)) throw new Error("Invalid timestamp");
+
+  const deltaSeconds = (nowMs() - sentMs) / 1000;
+  if (deltaSeconds > state.config.maxSkewPastSeconds) throw new Error("Timestamp too old");
+  if (deltaSeconds < -state.config.maxSkewFutureSeconds) throw new Error("Timestamp too far in the future");
+}
+
+function validateHmacRequest(req, res) {
+  if (!state.config.hmacEnabled) return true;
+
+  const timestamp = req.get("X-SeqPulse-Timestamp") || "";
+  const signature = req.get("X-SeqPulse-Signature") || "";
+  const nonce = req.get("X-SeqPulse-Nonce") || "";
+  const version = req.get("X-SeqPulse-Signature-Version") || "";
+  const method = (req.get("X-SeqPulse-Method") || req.method || "GET").toUpperCase();
+  const canonicalPath = canonicalizePath(req.get("X-SeqPulse-Canonical-Path") || req.path || req.url || "/");
+
+  if (!timestamp || !signature || !nonce || version !== "v2") {
+    rejectHmac(res, "Missing or invalid HMAC headers");
+    return false;
+  }
+
+  try {
+    validateTimestamp(timestamp);
+  } catch (error) {
+    rejectHmac(res, error.message);
+    return false;
+  }
+
+  cleanupOldNonces();
+  if (state.nonceSeenAt.has(nonce)) {
+    rejectHmac(res, "Nonce reuse");
+    return false;
+  }
+
+  const expected = buildSignature(state.config.hmacSecret, timestamp, method, canonicalPath, nonce);
+  const expectedBuf = Buffer.from(expected);
+  const providedBuf = Buffer.from(signature);
+  if (expectedBuf.length !== providedBuf.length || !crypto.timingSafeEqual(expectedBuf, providedBuf)) {
+    rejectHmac(res, "Invalid signature");
+    return false;
+  }
+
+  state.nonceSeenAt.set(nonce, nowMs());
+  return true;
+}
+
+function getMetricsSnapshot() {
+  cleanupOldSamples();
+  const sampleCount = state.samples.length;
+  const windowSeconds = state.config.windowSeconds;
+  const totalErrors = state.samples.reduce((acc, item) => acc + (item.isError ? 1 : 0), 0);
+  const latencies = state.samples.map((item) => item.latencyMs);
+
+  const cpuUsageRaw = os.cpus().length > 0 ? os.loadavg()[0] / os.cpus().length : 0;
+  const memoryUsageRaw = os.totalmem() > 0 ? process.memoryUsage().rss / os.totalmem() : 0;
+
+  return {
+    requests_per_sec: round(sampleCount / windowSeconds, 3),
+    latency_p95: round(percentile95(latencies), 3),
+    error_rate: sampleCount > 0 ? round(totalErrors / sampleCount, 6) : 0,
+    cpu_usage: round(Math.min(Math.max(cpuUsageRaw, 0), 1), 6),
+    memory_usage: round(Math.min(Math.max(memoryUsageRaw, 0), 1), 6),
+  };
+}
+
+function init(config) {
+  if (!config || typeof config !== "object") {
+    throw new Error("seqpulse.init(config) requires a config object");
+  }
+  if (!config.apiKey || typeof config.apiKey !== "string") {
+    throw new Error("seqpulse.init requires apiKey");
+  }
+
+  const endpoint = canonicalizePath(config.endpoint || DEFAULT_ENDPOINT);
+  const windowSeconds = Number(config.windowSeconds || DEFAULT_WINDOW_SECONDS);
+  const hmacEnabled = Boolean(config.hmacEnabled);
+  const hmacSecret = String(config.hmacSecret || "");
+
+  if (!Number.isFinite(windowSeconds) || windowSeconds <= 0) {
+    throw new Error("windowSeconds must be a positive number");
+  }
+  if (hmacEnabled && !hmacSecret) {
+    throw new Error("hmacSecret is required when hmacEnabled=true");
+  }
+
+  state.config = {
+    apiKey: config.apiKey,
+    endpoint,
+    windowSeconds,
+    hmacEnabled,
+    hmacSecret,
+    maxSkewPastSeconds: Number(config.maxSkewPastSeconds || DEFAULT_MAX_SKEW_PAST_SECONDS),
+    maxSkewFutureSeconds: Number(config.maxSkewFutureSeconds || DEFAULT_MAX_SKEW_FUTURE_SECONDS),
+  };
+  state.samples = [];
+  state.nonceSeenAt = new Map();
+  state.initialized = true;
+}
+
+function metrics() {
+  return function seqpulseMiddleware(req, res, next) {
+    if (!state.initialized) {
+      throw new Error("seqpulse.init() must be called before seqpulse.metrics()");
+    }
+
+    const path = canonicalizePath(req.path || req.url || "/");
+    if (path === state.config.endpoint && (req.method || "GET").toUpperCase() === "GET") {
+      if (!validateHmacRequest(req, res)) return;
+      res.json({ metrics: getMetricsSnapshot() });
+      return;
+    }
+
+    const startedAt = process.hrtime.bigint();
+    res.on("finish", () => {
+      const latencyMs = Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+      state.samples.push({
+        atMs: nowMs(),
+        latencyMs,
+        isError: res.statusCode >= 500,
+      });
+      cleanupOldSamples();
+    });
+    next();
+  };
+}
+
+module.exports = {
+  init,
+  metrics,
+  getMetricsSnapshot,
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "seqpulse",
+  "version": "0.1.0",
+  "description": "SeqPulse SDK for metrics endpoint instrumentation and HMAC validation",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE",
+    "scripts/smoke.js"
+  ],
+  "scripts": {
+    "smoke": "node scripts/smoke.js"
+  },
+  "keywords": [
+    "seqpulse",
+    "metrics",
+    "hmac",
+    "express"
+  ],
+  "author": "Nassir",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/smoke.js

@@ -0,0 +1,111 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const EventEmitter = require("node:events");
+const sdk = require("../index");
+
+class MockRes extends EventEmitter {
+  constructor() {
+    super();
+    this.statusCode = 200;
+    this.body = null;
+  }
+  status(code) {
+    this.statusCode = code;
+    return this;
+  }
+  json(payload) {
+    this.body = payload;
+    return this;
+  }
+}
+
+function mockReq({ path, method = "GET", headers = {} }) {
+  return {
+    path,
+    url: path,
+    method,
+    get(name) {
+      return headers[name] || headers[name.toLowerCase()] || "";
+    },
+  };
+}
+
+function runMiddleware(mw, req, res) {
+  return new Promise((resolve, reject) => {
+    try {
+      mw(req, res, () => resolve("next"));
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+async function testNoHmac() {
+  sdk.init({ apiKey: "sp_local", endpoint: "/seqpulse-metrics", hmacEnabled: false });
+  const mw = sdk.metrics();
+
+  const req1 = mockReq({ path: "/health" });
+  const res1 = new MockRes();
+  await runMiddleware(mw, req1, res1);
+  res1.statusCode = 200;
+  res1.emit("finish");
+
+  const req2 = mockReq({ path: "/seqpulse-metrics" });
+  const res2 = new MockRes();
+  mw(req2, res2, () => {});
+
+  if (res2.statusCode !== 200 || !res2.body || !res2.body.metrics) {
+    throw new Error("No-HMAC metrics endpoint failed");
+  }
+}
+
+async function testHmac() {
+  const secret = "local_hmac_secret";
+  sdk.init({
+    apiKey: "sp_local",
+    endpoint: "/seqpulse-metrics",
+    hmacEnabled: true,
+    hmacSecret: secret,
+  });
+  const mw = sdk.metrics();
+
+  const ts = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+  const nonce = "nonce-smoke-1";
+  const path = "/seqpulse-metrics";
+  const payload = `${ts}|GET|${path}|${nonce}`;
+  const sig = `sha256=${crypto.createHmac("sha256", secret).update(payload).digest("hex")}`;
+  const headers = {
+    "X-SeqPulse-Timestamp": ts,
+    "X-SeqPulse-Nonce": nonce,
+    "X-SeqPulse-Signature": sig,
+    "X-SeqPulse-Signature-Version": "v2",
+    "X-SeqPulse-Canonical-Path": path,
+    "X-SeqPulse-Method": "GET",
+  };
+
+  const req = mockReq({ path, headers });
+  const res = new MockRes();
+  mw(req, res, () => {});
+  if (res.statusCode !== 200 || !res.body || !res.body.metrics) {
+    throw new Error("HMAC valid request failed");
+  }
+
+  const replayReq = mockReq({ path, headers });
+  const replayRes = new MockRes();
+  mw(replayReq, replayRes, () => {});
+  if (replayRes.statusCode !== 401) {
+    throw new Error("HMAC replay protection failed");
+  }
+}
+
+async function main() {
+  await testNoHmac();
+  await testHmac();
+  console.log("seqpulse node smoke: OK");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});