@shunt-network/verify 0.0.0-stage → 1.0.0

package/dist/core.d.ts

@@ -0,0 +1,25 @@
+export type VerifyResult = {
+    ok: true;
+    requestId: string;
+} | {
+    ok: false;
+    reason: "missing_headers" | "stale_timestamp" | "bad_signature" | "replay";
+};
+export interface VerifyInput {
+    secret: string | string[];
+    method: string;
+    pathAndQuery: string;
+    rawBody: Buffer | Uint8Array | string;
+    getHeader: (name: string) => string | undefined | null;
+    maxSkewSec?: number;
+    replayCache?: ReplayCache;
+}
+export declare class ReplayCache {
+    private ttlMs;
+    private seen;
+    constructor(ttlMs?: number);
+    /** returns true if the id was already seen */
+    check(id: string): boolean;
+}
+export declare function verifyShunt(i: VerifyInput): VerifyResult;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,eAAe,GAAG,QAAQ,CAAA;CAAE,CAAC;AAE9F,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IACtC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,WAAW;IAEV,OAAO,CAAC,KAAK;IADzB,OAAO,CAAC,IAAI,CAA6B;IACzC,YAAoB,KAAK,SAAc,EAAI;IAC3C,8CAA8C;IAC9C,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAMzB;CACF;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,WAAW,GAAG,YAAY,CA4BxD"}

package/dist/core.js

@@ -0,0 +1,44 @@
+import crypto from "node:crypto";
+export class ReplayCache {
+    ttlMs;
+    seen = new Map();
+    constructor(ttlMs = 10 * 60_000) {
+        this.ttlMs = ttlMs;
+    }
+    /** returns true if the id was already seen */
+    check(id) {
+        const now = Date.now();
+        for (const [k, exp] of this.seen)
+            if (exp < now)
+                this.seen.delete(k);
+        if (this.seen.has(id))
+            return true;
+        this.seen.set(id, now + this.ttlMs);
+        return false;
+    }
+}
+export function verifyShunt(i) {
+    const ts = i.getHeader("x-shunt-timestamp");
+    const rid = i.getHeader("x-shunt-request-id");
+    const sig = (i.getHeader("x-shunt-signature") ?? "").replace(/^v1=/, "");
+    if (!ts || !rid || !sig)
+        return { ok: false, reason: "missing_headers" };
+    const skew = Math.abs(Date.now() / 1000 - Number(ts));
+    if (!Number.isFinite(skew) || skew > (i.maxSkewSec ?? 300))
+        return { ok: false, reason: "stale_timestamp" };
+    const bodyHash = crypto.createHash("sha256").update(i.rawBody).digest("hex");
+    const payload = `v1\n${ts}\n${rid}\n${i.method.toUpperCase()}\n${i.pathAndQuery}\n${bodyHash}`;
+    const secrets = Array.isArray(i.secret) ? i.secret : [i.secret];
+    const sigBuf = Buffer.from(sig, "utf8");
+    const valid = secrets.some((s) => {
+        const expected = Buffer.from(crypto.createHmac("sha256", s).update(payload).digest("hex"), "utf8");
+        return expected.length === sigBuf.length && crypto.timingSafeEqual(expected, sigBuf);
+    });
+    if (!valid)
+        return { ok: false, reason: "bad_signature" };
+    // only record the id AFTER the signature is valid, so attackers can't fill the cache
+    if (i.replayCache?.check(rid))
+        return { ok: false, reason: "replay" };
+    return { ok: true, requestId: rid };
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

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

package/dist/express.d.ts

@@ -0,0 +1,7 @@
+/** Pass to express.json({ verify: shuntRawBody }) so the raw bytes are kept. */
+export declare const shuntRawBody: (req: any, _res: any, buf: Buffer) => void;
+export declare function shuntExpress(secret: string | string[], opts?: {
+    maxSkewSec?: number;
+    replayProtection?: boolean;
+}): (req: any, res: any, next: any) => any;
+//# sourceMappingURL=express.d.ts.map

package/dist/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../src/express.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,eAAO,MAAM,YAAY,QAAS,GAAG,QAAQ,GAAG,OAAO,MAAM,SAE5D,CAAC;AAEF,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,EACzB,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,SAGjD,GAAG,OAAO,GAAG,QAAQ,GAAG,SAgBtC"}

package/dist/express.js

@@ -0,0 +1,25 @@
+import { verifyShunt, ReplayCache } from "./core.js";
+/** Pass to express.json({ verify: shuntRawBody }) so the raw bytes are kept. */
+export const shuntRawBody = (req, _res, buf) => {
+    req.rawBody = buf;
+};
+export function shuntExpress(secret, opts = {}) {
+    const replayCache = opts.replayProtection ? new ReplayCache() : undefined;
+    return (req, res, next) => {
+        const r = verifyShunt({
+            secret,
+            method: req.method,
+            pathAndQuery: req.originalUrl,
+            rawBody: req.rawBody ?? Buffer.alloc(0),
+            getHeader: (n) => req.get(n),
+            maxSkewSec: opts.maxSkewSec,
+            replayCache,
+        });
+        if (!r.ok) {
+            return res.status(401).json({ error: "Unauthorized: requests must come via Shunt" });
+        }
+        req.shunt = { requestId: r.requestId, agent: req.get("x-shunt-agent") };
+        next();
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../src/express.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAErD,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAQ,EAAE,IAAS,EAAE,GAAW,EAAE,EAAE;IAC/D,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC;AACpB,CAAC,CAAC;AAEF,MAAM,UAAU,YAAY,CAC1B,MAAyB,EACzB,IAAI,GAAwD,EAAE;IAE9D,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1E,OAAO,CAAC,GAAQ,EAAE,GAAQ,EAAE,IAAS,EAAE,EAAE;QACvC,MAAM,CAAC,GAAG,WAAW,CAAC;YACpB,MAAM;YACN,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,YAAY,EAAE,GAAG,CAAC,WAAW;YAC7B,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACvC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5B,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,WAAW;SACZ,CAAC,CAAC;QACH,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACV,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,4CAA4C,EAAE,CAAC,CAAC;QACvF,CAAC;QACD,GAAG,CAAC,KAAK,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;QACxE,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./core.js";
+export * from "./express.js";
+export * from "./web.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,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./core.js";
+export * from "./express.js";
+export * from "./web.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,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC"}

package/dist/web.d.ts

@@ -0,0 +1,10 @@
+import { ReplayCache } from "./core.js";
+export declare function verifyShuntRequest(req: Request, secret: string | string[], opts?: {
+    maxSkewSec?: number;
+    replayCache?: ReplayCache;
+}): Promise<import("./core.js").VerifyResult>;
+/** Next.js App Router: export const POST = withShunt(secret, async (req) => ...) */
+export declare function withShunt<T extends (req: Request, ...a: any[]) => Promise<Response> | Response>(secret: string | string[], handler: T): T;
+/** Hono: app.use("/paid/*", shuntHono(secret)) */
+export declare const shuntHono: (secret: string | string[]) => (c: any, next: any) => Promise<any>;
+//# sourceMappingURL=web.d.ts.map

package/dist/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,WAAW,EAAE,MAAM,WAAW,CAAC;AAErD,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,EACzB,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,WAAW,CAAA;CAAO,6CAY9D;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,EAC7F,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,EACzB,OAAO,EAAE,CAAC,GACT,CAAC,CAQH;AAED,kDAAkD;AAClD,eAAO,MAAM,SAAS,WAAY,MAAM,GAAG,MAAM,EAAE,SAAe,GAAG,QAAQ,GAAG,iBAI/E,CAAC"}

package/dist/web.js

@@ -0,0 +1,31 @@
+import { verifyShunt } from "./core.js";
+export async function verifyShuntRequest(req, secret, opts = {}) {
+    const url = new URL(req.url);
+    const rawBody = new Uint8Array(await req.clone().arrayBuffer());
+    return verifyShunt({
+        secret,
+        method: req.method,
+        pathAndQuery: url.pathname + url.search,
+        rawBody,
+        getHeader: (n) => req.headers.get(n),
+        ...opts,
+    });
+}
+/** Next.js App Router: export const POST = withShunt(secret, async (req) => ...) */
+export function withShunt(secret, handler) {
+    return (async (req, ...args) => {
+        const r = await verifyShuntRequest(req, secret);
+        if (!r.ok) {
+            return Response.json({ error: "Unauthorized: requests must come via Shunt" }, { status: 401 });
+        }
+        return handler(req, ...args);
+    });
+}
+/** Hono: app.use("/paid/*", shuntHono(secret)) */
+export const shuntHono = (secret) => async (c, next) => {
+    const r = await verifyShuntRequest(c.req.raw, secret);
+    if (!r.ok)
+        return c.json({ error: "Unauthorized: requests must come via Shunt" }, 401);
+    await next();
+};
+//# sourceMappingURL=web.js.map

package/dist/web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.js","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAe,MAAM,WAAW,CAAC;AAErD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,GAAY,EACZ,MAAyB,EACzB,IAAI,GAAuD,EAAE;IAE7D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAChE,OAAO,WAAW,CAAC;QACjB,MAAM;QACN,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,YAAY,EAAE,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM;QACvC,OAAO;QACP,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QACpC,GAAG,IAAI;KACR,CAAC,CAAC;AACL,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,SAAS,CACvB,MAAyB,EACzB,OAAU;IAEV,OAAO,CAAC,KAAK,EAAE,GAAY,EAAE,GAAG,IAAW,EAAE,EAAE;QAC7C,MAAM,CAAC,GAAG,MAAM,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAChD,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACV,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,4CAA4C,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACjG,CAAC;QACD,OAAO,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAM,CAAC;AACV,CAAC;AAED,kDAAkD;AAClD,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAyB,EAAE,EAAE,CAAC,KAAK,EAAE,CAAM,EAAE,IAAS,EAAE,EAAE;IAClF,MAAM,CAAC,GAAG,MAAM,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtD,IAAI,CAAC,CAAC,CAAC,EAAE;QAAE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,4CAA4C,EAAE,EAAE,GAAG,CAAC,CAAC;IACvF,MAAM,IAAI,EAAE,CAAC;AACf,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@shunt-network/verify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "",
+  "license": "ISC",
+  "author": "Aditya Patwa",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.