@korala/auth 1.0.0

package/dist/hmac.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Maximum age of a request signature in seconds (5 minutes)
+ */
+export declare const MAX_TIMESTAMP_AGE_SECONDS = 300;
+/**
+ * Request data needed for signature generation/verification
+ */
+export interface SignatureRequest {
+    method: string;
+    path: string;
+    body?: string;
+}
+/**
+ * Build the payload string used for HMAC signing
+ */
+export declare function buildSignaturePayload(request: SignatureRequest, timestamp: string): string;
+/**
+ * Compute HMAC-SHA256 signature for a payload
+ */
+export declare function computeSignature(payload: string, secret: string): string;
+/**
+ * Verify a signature using timing-safe comparison
+ */
+export declare function verifySignature(provided: string, expected: string): boolean;
+/**
+ * Check if a timestamp is within the allowed age window
+ */
+export declare function isTimestampValid(timestamp: number, maxAgeSeconds?: number): boolean;
+/**
+ * Generate current Unix timestamp in seconds
+ */
+export declare function getTimestamp(): string;
+/**
+ * Hash a secret for storage using SHA-256
+ */
+export declare function hashSecret(secret: string): string;
+/**
+ * Sign a request and return the headers needed for authentication
+ */
+export declare function signRequest(request: SignatureRequest, keyId: string, secret: string): {
+    'x-api-key': string;
+    'x-timestamp': string;
+    'x-signature': string;
+};
+/**
+ * Webhook signature headers
+ */
+export interface WebhookSignatureHeaders {
+    'x-webhook-signature': string;
+    'x-webhook-timestamp': string;
+    'x-webhook-event': string;
+}
+/**
+ * Sign a webhook payload and return the headers
+ */
+export declare function signWebhookPayload(payload: string, secret: string, eventType: string): WebhookSignatureHeaders;
+/**
+ * Verify a webhook signature
+ */
+export declare function verifyWebhookSignature(payload: string, timestamp: string, signature: string, secret: string, maxAgeSeconds?: number): boolean;
+//# sourceMappingURL=hmac.d.ts.map

package/dist/hmac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac.d.ts","sourceRoot":"","sources":["../src/hmac.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,MAAM,GAChB,MAAM,CAMR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAExE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAa3E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,aAAa,GAAE,MAAkC,GAChD,OAAO,CAGT;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAUvE;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,uBAAuB,CAUzB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,aAAa,GAAE,MAAkC,GAChD,OAAO,CAgBT"}

package/dist/hmac.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TIMESTAMP_AGE_SECONDS = void 0;
+exports.buildSignaturePayload = buildSignaturePayload;
+exports.computeSignature = computeSignature;
+exports.verifySignature = verifySignature;
+exports.isTimestampValid = isTimestampValid;
+exports.getTimestamp = getTimestamp;
+exports.hashSecret = hashSecret;
+exports.signRequest = signRequest;
+exports.signWebhookPayload = signWebhookPayload;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+const crypto_1 = require("crypto");
+/**
+ * Maximum age of a request signature in seconds (5 minutes)
+ */
+exports.MAX_TIMESTAMP_AGE_SECONDS = 300;
+/**
+ * Build the payload string used for HMAC signing
+ */
+function buildSignaturePayload(request, timestamp) {
+    const method = request.method.toUpperCase();
+    const path = request.path;
+    const body = request.body ?? '';
+    return `${timestamp}.${method}.${path}.${body}`;
+}
+/**
+ * Compute HMAC-SHA256 signature for a payload
+ */
+function computeSignature(payload, secret) {
+    return (0, crypto_1.createHmac)('sha256', secret).update(payload).digest('hex');
+}
+/**
+ * Verify a signature using timing-safe comparison
+ */
+function verifySignature(provided, expected) {
+    try {
+        const providedBuffer = Buffer.from(provided, 'hex');
+        const expectedBuffer = Buffer.from(expected, 'hex');
+        if (providedBuffer.length !== expectedBuffer.length) {
+            return false;
+        }
+        return (0, crypto_1.timingSafeEqual)(providedBuffer, expectedBuffer);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a timestamp is within the allowed age window
+ */
+function isTimestampValid(timestamp, maxAgeSeconds = exports.MAX_TIMESTAMP_AGE_SECONDS) {
+    const now = Math.floor(Date.now() / 1000);
+    return Math.abs(now - timestamp) <= maxAgeSeconds;
+}
+/**
+ * Generate current Unix timestamp in seconds
+ */
+function getTimestamp() {
+    return Math.floor(Date.now() / 1000).toString();
+}
+/**
+ * Hash a secret for storage using SHA-256
+ */
+function hashSecret(secret) {
+    return (0, crypto_1.createHash)('sha256').update(secret).digest('hex');
+}
+/**
+ * Sign a request and return the headers needed for authentication
+ */
+function signRequest(request, keyId, secret) {
+    const timestamp = getTimestamp();
+    const payload = buildSignaturePayload(request, timestamp);
+    const signature = computeSignature(payload, secret);
+    return {
+        'x-api-key': keyId,
+        'x-timestamp': timestamp,
+        'x-signature': signature,
+    };
+}
+/**
+ * Sign a webhook payload and return the headers
+ */
+function signWebhookPayload(payload, secret, eventType) {
+    const timestamp = getTimestamp();
+    const signaturePayload = `${timestamp}.${payload}`;
+    const signature = computeSignature(signaturePayload, secret);
+    return {
+        'x-webhook-signature': signature,
+        'x-webhook-timestamp': timestamp,
+        'x-webhook-event': eventType,
+    };
+}
+/**
+ * Verify a webhook signature
+ */
+function verifyWebhookSignature(payload, timestamp, signature, secret, maxAgeSeconds = exports.MAX_TIMESTAMP_AGE_SECONDS) {
+    // Check timestamp is valid
+    const timestampNum = Number.parseInt(timestamp, 10);
+    if (Number.isNaN(timestampNum) ||
+        !isTimestampValid(timestampNum, maxAgeSeconds)) {
+        return false;
+    }
+    // Compute expected signature
+    const signaturePayload = `${timestamp}.${payload}`;
+    const expectedSignature = computeSignature(signaturePayload, secret);
+    // Timing-safe comparison
+    return verifySignature(signature, expectedSignature);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { buildSignaturePayload, computeSignature, getTimestamp, isTimestampValid, MAX_TIMESTAMP_AGE_SECONDS, type SignatureRequest, signRequest, signWebhookPayload, verifySignature, verifyWebhookSignature, type WebhookSignatureHeaders, } from './hmac.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,EACL,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,yBAAyB,EACzB,KAAK,gBAAgB,EACrB,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhookSignature = exports.verifySignature = exports.signWebhookPayload = exports.signRequest = exports.MAX_TIMESTAMP_AGE_SECONDS = exports.isTimestampValid = exports.getTimestamp = exports.computeSignature = exports.buildSignaturePayload = void 0;
+var hmac_js_1 = require("./hmac.js");
+Object.defineProperty(exports, "buildSignaturePayload", { enumerable: true, get: function () { return hmac_js_1.buildSignaturePayload; } });
+Object.defineProperty(exports, "computeSignature", { enumerable: true, get: function () { return hmac_js_1.computeSignature; } });
+Object.defineProperty(exports, "getTimestamp", { enumerable: true, get: function () { return hmac_js_1.getTimestamp; } });
+Object.defineProperty(exports, "isTimestampValid", { enumerable: true, get: function () { return hmac_js_1.isTimestampValid; } });
+Object.defineProperty(exports, "MAX_TIMESTAMP_AGE_SECONDS", { enumerable: true, get: function () { return hmac_js_1.MAX_TIMESTAMP_AGE_SECONDS; } });
+Object.defineProperty(exports, "signRequest", { enumerable: true, get: function () { return hmac_js_1.signRequest; } });
+Object.defineProperty(exports, "signWebhookPayload", { enumerable: true, get: function () { return hmac_js_1.signWebhookPayload; } });
+Object.defineProperty(exports, "verifySignature", { enumerable: true, get: function () { return hmac_js_1.verifySignature; } });
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return hmac_js_1.verifyWebhookSignature; } });

package/dist/internal.d.ts

@@ -0,0 +1,2 @@
+export { hashSecret } from './hmac.js';
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/internal.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashSecret = void 0;
+var hmac_js_1 = require("./hmac.js");
+Object.defineProperty(exports, "hashSecret", { enumerable: true, get: function () { return hmac_js_1.hashSecret; } });

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@korala/auth",
+  "version": "1.0.0",
+  "description": "HMAC authentication utilities for the Korala document signing API",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/korala-ai/korala.git",
+    "directory": "packages/auth"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js",
+      "default": "./dist/internal.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "internal": [
+        "./dist/internal.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0"
+  },
+  "keywords": [
+    "korala",
+    "hmac",
+    "authentication",
+    "api-signing",
+    "webhook-verification"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "check": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}