@grackle-ai/auth 0.72.3

package/dist/session.d.ts

@@ -0,0 +1,36 @@
+/** Name of the session cookie sent to browsers. */
+export declare const SESSION_COOKIE_NAME: string;
+/** Start the periodic session cleanup timer. Call once on server startup. */
+export declare function startSessionCleanup(): void;
+/** Stop the periodic session cleanup timer. */
+export declare function stopSessionCleanup(): void;
+/**
+ * Create a new session and return the Set-Cookie header value.
+ *
+ * The cookie format is `<sessionId>.<signature>` where the signature
+ * is an HMAC-SHA256 of the session ID using the API key as secret.
+ *
+ * When `options.secure` is true the cookie includes the `Secure` flag,
+ * which tells browsers to only send it over HTTPS. This should be
+ * enabled when the server is network-accessible (`--allow-network`)
+ * behind a TLS-terminating reverse proxy.
+ */
+export declare function createSession(apiKey: string, options?: {
+    secure?: boolean;
+}): string;
+/**
+ * Parse a raw Cookie header into key-value pairs.
+ *
+ * Handles the standard `name=value; name2=value2` format.
+ */
+export declare function parseCookies(header: string): Record<string, string>;
+/**
+ * Validate a session cookie from a raw Cookie header string.
+ *
+ * Returns true if the cookie contains a valid, non-expired session
+ * with a correct HMAC signature.
+ */
+export declare function validateSessionCookie(cookieHeader: string, apiKey: string): boolean;
+/** Remove all sessions (useful for testing). */
+export declare function clearSessions(): void;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAEA,mDAAmD;AACnD,eAAO,MAAM,mBAAmB,EAAE,MAA0B,CAAC;AAqB7D,6EAA6E;AAC7E,wBAAgB,mBAAmB,IAAI,IAAI,CAc1C;AAED,+CAA+C;AAC/C,wBAAgB,kBAAkB,IAAI,IAAI,CAKzC;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAwBpF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAenE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAwCnF;AAED,gDAAgD;AAChD,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}

package/dist/session.js

@@ -0,0 +1,143 @@
+import { randomBytes, createHmac } from "node:crypto";
+/** Name of the session cookie sent to browsers. */
+export const SESSION_COOKIE_NAME = "grackle_session";
+/** Default session lifetime: 24 hours. */
+const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+/** Byte length of the random session identifier. */
+const SESSION_ID_BYTES = 32;
+/** Interval at which expired sessions are cleaned up. */
+const SESSION_CLEANUP_INTERVAL_MS = 60 * 1000;
+/** In-memory session store keyed by session ID. */
+const sessions = new Map();
+let cleanupTimer;
+/** Start the periodic session cleanup timer. Call once on server startup. */
+export function startSessionCleanup() {
+    if (cleanupTimer) {
+        return;
+    }
+    cleanupTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [id, record] of sessions) {
+            if (now > record.expiresAt) {
+                sessions.delete(id);
+            }
+        }
+    }, SESSION_CLEANUP_INTERVAL_MS);
+    // Allow the process to exit even if the timer is still running
+    cleanupTimer.unref();
+}
+/** Stop the periodic session cleanup timer. */
+export function stopSessionCleanup() {
+    if (cleanupTimer) {
+        clearInterval(cleanupTimer);
+        cleanupTimer = undefined;
+    }
+}
+/**
+ * Create an HMAC-SHA256 signature of a value using the given secret.
+ * Returns a hex-encoded string.
+ */
+function sign(value, secret) {
+    return createHmac("sha256", secret).update(value).digest("hex");
+}
+/**
+ * Create a new session and return the Set-Cookie header value.
+ *
+ * The cookie format is `<sessionId>.<signature>` where the signature
+ * is an HMAC-SHA256 of the session ID using the API key as secret.
+ *
+ * When `options.secure` is true the cookie includes the `Secure` flag,
+ * which tells browsers to only send it over HTTPS. This should be
+ * enabled when the server is network-accessible (`--allow-network`)
+ * behind a TLS-terminating reverse proxy.
+ */
+export function createSession(apiKey, options) {
+    const sessionId = randomBytes(SESSION_ID_BYTES).toString("hex");
+    const now = Date.now();
+    sessions.set(sessionId, {
+        createdAt: now,
+        expiresAt: now + SESSION_TTL_MS,
+    });
+    const signature = sign(sessionId, apiKey);
+    const cookieValue = `${sessionId}.${signature}`;
+    const maxAge = Math.floor(SESSION_TTL_MS / 1000);
+    const parts = [
+        `${SESSION_COOKIE_NAME}=${cookieValue}`,
+        "HttpOnly",
+        "SameSite=Lax",
+        "Path=/",
+        `Max-Age=${maxAge}`,
+    ];
+    if (options?.secure) {
+        parts.push("Secure");
+    }
+    return parts.join("; ");
+}
+/**
+ * Parse a raw Cookie header into key-value pairs.
+ *
+ * Handles the standard `name=value; name2=value2` format.
+ */
+export function parseCookies(header) {
+    const result = {};
+    if (!header) {
+        return result;
+    }
+    for (const pair of header.split(";")) {
+        const eqIndex = pair.indexOf("=");
+        if (eqIndex === -1) {
+            continue;
+        }
+        const name = pair.slice(0, eqIndex).trim();
+        const value = pair.slice(eqIndex + 1).trim();
+        result[name] = value;
+    }
+    return result;
+}
+/**
+ * Validate a session cookie from a raw Cookie header string.
+ *
+ * Returns true if the cookie contains a valid, non-expired session
+ * with a correct HMAC signature.
+ */
+export function validateSessionCookie(cookieHeader, apiKey) {
+    const cookies = parseCookies(cookieHeader);
+    const raw = cookies[SESSION_COOKIE_NAME];
+    if (!raw) {
+        return false;
+    }
+    const dotIndex = raw.lastIndexOf(".");
+    if (dotIndex === -1) {
+        return false;
+    }
+    const sessionId = raw.slice(0, dotIndex);
+    const providedSignature = raw.slice(dotIndex + 1);
+    const expectedSignature = sign(sessionId, apiKey);
+    // Constant-time comparison for the signature
+    if (providedSignature.length !== expectedSignature.length) {
+        return false;
+    }
+    let diff = 0;
+    for (let i = 0; i < expectedSignature.length; i++) {
+        // eslint-disable-next-line no-bitwise
+        diff |= providedSignature.charCodeAt(i) ^ expectedSignature.charCodeAt(i);
+    }
+    if (diff !== 0) {
+        return false;
+    }
+    // Check session exists and hasn't expired
+    const record = sessions.get(sessionId);
+    if (!record) {
+        return false;
+    }
+    if (Date.now() > record.expiresAt) {
+        sessions.delete(sessionId);
+        return false;
+    }
+    return true;
+}
+/** Remove all sessions (useful for testing). */
+export function clearSessions() {
+    sessions.clear();
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtD,mDAAmD;AACnD,MAAM,CAAC,MAAM,mBAAmB,GAAW,iBAAiB,CAAC;AAE7D,0CAA0C;AAC1C,MAAM,cAAc,GAAW,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnD,oDAAoD;AACpD,MAAM,gBAAgB,GAAW,EAAE,CAAC;AAEpC,yDAAyD;AACzD,MAAM,2BAA2B,GAAW,EAAE,GAAG,IAAI,CAAC;AAOtD,mDAAmD;AACnD,MAAM,QAAQ,GAA+B,IAAI,GAAG,EAAyB,CAAC;AAE9E,IAAI,YAAwD,CAAC;AAE7D,6EAA6E;AAC7E,MAAM,UAAU,mBAAmB;IACjC,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO;IACT,CAAC;IACD,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACpC,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;gBAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC,EAAE,2BAA2B,CAAC,CAAC;IAChC,+DAA+D;IAC/D,YAAY,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,kBAAkB;IAChC,IAAI,YAAY,EAAE,CAAC;QACjB,aAAa,CAAC,YAAY,CAAC,CAAC;QAC5B,YAAY,GAAG,SAAS,CAAC;IAC3B,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,IAAI,CAAC,KAAa,EAAE,MAAc;IACzC,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,OAA8B;IAC1E,MAAM,SAAS,GAAG,WAAW,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE;QACtB,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,GAAG,GAAG,cAAc;KAChC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,WAAW,GAAG,GAAG,SAAS,IAAI,SAAS,EAAE,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEjD,MAAM,KAAK,GAAG;QACZ,GAAG,mBAAmB,IAAI,WAAW,EAAE;QACvC,UAAU;QACV,cAAc;QACd,QAAQ;QACR,WAAW,MAAM,EAAE;KACpB,CAAC;IACF,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC;YACnB,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7C,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB,EAAE,MAAc;IACxE,MAAM,OAAO,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;QACpB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACzC,MAAM,iBAAiB,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;IAClD,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAElD,6CAA6C;IAC7C,IAAI,iBAAiB,CAAC,MAAM,KAAK,iBAAiB,CAAC,MAAM,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,iBAAiB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,sCAAsC;QACtC,IAAI,IAAI,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;QACf,OAAO,KAAK,CAAC;IACf,CAAC;IAED,0CAA0C;IAC1C,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;QAClC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,aAAa;IAC3B,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.57.7"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@grackle-ai/auth",
+  "version": "0.72.3",
+  "description": "Authentication and authorization primitives for Grackle",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nick-pape/grackle.git",
+    "directory": "packages/auth"
+  },
+  "keywords": [
+    "grackle",
+    "auth",
+    "oauth",
+    "pairing",
+    "security"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "dependencies": {
+    "@grackle-ai/common": "0.72.3"
+  },
+  "devDependencies": {
+    "@rushstack/heft": "1.2.7",
+    "@types/node": "^22.0.0",
+    "vitest": "^3.1.1",
+    "@grackle-ai/heft-rig": "0.0.1"
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "test": "vitest run",
+    "clean": "heft clean",
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "vitest run"
+  }
+}