@guidekit/server 0.1.0-beta.1

package/README.md

@@ -0,0 +1,68 @@
+# @guidekit/server
+
+Server-side utilities for the GuideKit SDK. Provides secure token generation and validation so API keys never reach the browser.
+
+## Installation
+
+```bash
+npm install @guidekit/server
+```
+
+## Token Generation
+
+Create a token endpoint that the client SDK calls to obtain a short-lived session token.
+
+```typescript
+import { createSessionToken } from '@guidekit/server';
+
+// Next.js App Router example
+export async function POST() {
+  const token = await createSessionToken({
+    signingSecret: process.env.GUIDEKIT_SECRET!,
+    geminiKey: process.env.GEMINI_KEY!,
+    deepgramKey: process.env.DEEPGRAM_KEY,
+    elevenlabsKey: process.env.ELEVENLABS_KEY,
+    expiresIn: '15m',
+  });
+
+  return Response.json(token);
+}
+```
+
+## Token Validation
+
+Validate an incoming token (useful for custom middleware):
+
+```typescript
+import { validateSessionToken } from '@guidekit/server';
+
+const payload = await validateSessionToken({
+  token: bearerToken,
+  signingSecret: process.env.GUIDEKIT_SECRET!,
+});
+```
+
+## Secret Rotation
+
+To rotate your signing secret with zero downtime, temporarily accept both old and new secrets:
+
+```typescript
+const token = await createSessionToken({
+  signingSecret: process.env.GUIDEKIT_SECRET_NEW!,
+  // ...
+});
+```
+
+Generate a new secret via the CLI:
+
+```bash
+npx guidekit generate-secret
+```
+
+## Documentation
+
+Full documentation: [guidekit.dev/docs/server](https://guidekit.dev/docs/server)
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.cjs

@@ -0,0 +1,183 @@
+'use strict';
+
+var jose = require('jose');
+
+// src/index.ts
+var sessionKeyStore = /* @__PURE__ */ new Map();
+function getSessionKeys(sessionId) {
+  return sessionKeyStore.get(sessionId);
+}
+function clearSessionKeys(sessionId) {
+  return sessionKeyStore.delete(sessionId);
+}
+function parseDuration(duration) {
+  if (typeof duration !== "string" || duration.trim().length === 0) {
+    throw new Error('Duration must be a non-empty string (e.g. "15m", "1h", "30s").');
+  }
+  const cleaned = duration.trim().toLowerCase();
+  const regex = /(\d+)\s*(d|h|m|s)/g;
+  let match;
+  let totalSeconds = 0;
+  let matched = false;
+  while ((match = regex.exec(cleaned)) !== null) {
+    matched = true;
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    switch (unit) {
+      case "s":
+        totalSeconds += value;
+        break;
+      case "m":
+        totalSeconds += value * 60;
+        break;
+      case "h":
+        totalSeconds += value * 3600;
+        break;
+      case "d":
+        totalSeconds += value * 86400;
+        break;
+    }
+  }
+  if (!matched) {
+    throw new Error(
+      `Invalid duration format: "${duration}". Expected a string like "15m", "1h", "30s", "7d", or compound "2h30m".`
+    );
+  }
+  if (totalSeconds <= 0) {
+    throw new Error("Duration must resolve to a positive number of seconds.");
+  }
+  return totalSeconds;
+}
+function encodeSecret(secret) {
+  return new TextEncoder().encode(secret);
+}
+function resolveSigningSecret(signingSecret) {
+  if (Array.isArray(signingSecret)) {
+    if (signingSecret.length === 0) {
+      throw new Error("signingSecret array must contain at least one secret.");
+    }
+    return signingSecret[0];
+  }
+  if (typeof signingSecret !== "string" || signingSecret.length === 0) {
+    throw new Error("signingSecret must be a non-empty string or a non-empty array of strings.");
+  }
+  return signingSecret;
+}
+function resolveAllSecrets(signingSecret) {
+  if (Array.isArray(signingSecret)) {
+    if (signingSecret.length === 0) {
+      throw new Error("signingSecret array must contain at least one secret.");
+    }
+    return signingSecret;
+  }
+  if (typeof signingSecret !== "string" || signingSecret.length === 0) {
+    throw new Error("signingSecret must be a non-empty string or a non-empty array of strings.");
+  }
+  return [signingSecret];
+}
+async function createSessionToken(options) {
+  const {
+    signingSecret,
+    deepgramKey,
+    elevenlabsKey,
+    geminiKey,
+    expiresIn = "15m",
+    allowedOrigins,
+    permissions = ["stt", "tts", "llm"],
+    userId,
+    sessionId = crypto.randomUUID(),
+    metadata
+  } = options;
+  const secret = resolveSigningSecret(signingSecret);
+  const lifetimeSeconds = parseDuration(expiresIn);
+  const now = Math.floor(Date.now() / 1e3);
+  const expiresAt = now + lifetimeSeconds;
+  const jwtPayload = {
+    sessionId,
+    permissions
+  };
+  if (userId !== void 0) {
+    jwtPayload.userId = userId;
+  }
+  if (metadata !== void 0 && Object.keys(metadata).length > 0) {
+    jwtPayload.metadata = metadata;
+  }
+  if (allowedOrigins !== void 0 && allowedOrigins.length > 0) {
+    jwtPayload.aud = allowedOrigins;
+  }
+  const token = await new jose.SignJWT(jwtPayload).setProtectedHeader({ alg: "HS256" }).setIssuedAt(now).setExpirationTime(expiresAt).sign(encodeSecret(secret));
+  const providerKeys = {};
+  if (deepgramKey) providerKeys.deepgramKey = deepgramKey;
+  if (elevenlabsKey) providerKeys.elevenlabsKey = elevenlabsKey;
+  if (geminiKey) providerKeys.geminiKey = geminiKey;
+  if (Object.keys(providerKeys).length > 0) {
+    sessionKeyStore.set(sessionId, providerKeys);
+  }
+  return {
+    token,
+    expiresIn: lifetimeSeconds,
+    expiresAt
+  };
+}
+async function validateSessionToken(token, signingSecret, options) {
+  if (typeof token !== "string" || token.trim().length === 0) {
+    return { valid: false, error: "Token must be a non-empty string." };
+  }
+  const secrets = resolveAllSecrets(signingSecret);
+  let lastError;
+  for (const secret of secrets) {
+    try {
+      const verifyOptions = {
+        algorithms: ["HS256"]
+      };
+      if (options?.audience) {
+        verifyOptions.audience = options.audience;
+      }
+      const { payload } = await jose.jwtVerify(token, encodeSecret(secret), verifyOptions);
+      const tokenPayload = {
+        sessionId: payload.sessionId,
+        expiresAt: payload.exp,
+        audience: normalizeAudience(payload.aud),
+        permissions: payload.permissions ?? [],
+        iat: payload.iat
+      };
+      if (payload.userId !== void 0) {
+        tokenPayload.userId = payload.userId;
+      }
+      if (payload.metadata !== void 0) {
+        tokenPayload.metadata = payload.metadata;
+      }
+      return { valid: true, payload: tokenPayload };
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  const message = lastError instanceof Error ? lastError.message : "Token validation failed.";
+  return { valid: false, error: message };
+}
+function normalizeAudience(aud) {
+  if (aud === void 0 || aud === null) return [];
+  if (typeof aud === "string") return [aud];
+  if (Array.isArray(aud)) return aud.filter((a) => typeof a === "string");
+  return [];
+}
+function generateSecret() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+function base64UrlEncode(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+exports.clearSessionKeys = clearSessionKeys;
+exports.createSessionToken = createSessionToken;
+exports.generateSecret = generateSecret;
+exports.getSessionKeys = getSessionKeys;
+exports.validateSessionToken = validateSessionToken;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["SignJWT","jwtVerify"],"mappings":"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","file":"index.cjs","sourcesContent":["import { SignJWT, jwtVerify, type JWTPayload } from 'jose';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface TokenPayload {\n  sessionId: string;\n  expiresAt: number;\n  audience: string[];\n  permissions: string[];\n  userId?: string;\n  metadata?: Record<string, unknown>;\n  iat: number;\n}\n\nexport interface CreateSessionTokenOptions {\n  signingSecret: string | string[];\n  deepgramKey?: string;\n  elevenlabsKey?: string;\n  geminiKey?: string;\n  expiresIn?: string;\n  allowedOrigins?: string[];\n  permissions?: string[];\n  userId?: string;\n  sessionId?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface CreateSessionTokenResult {\n  token: string;\n  expiresIn: number;\n  expiresAt: number;\n}\n\nexport interface ValidateSessionTokenResult {\n  valid: boolean;\n  payload?: TokenPayload;\n  error?: string;\n}\n\nexport interface ValidateSessionTokenOptions {\n  audience?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Server-side provider key store\n// ---------------------------------------------------------------------------\n\ninterface ProviderKeys {\n  deepgramKey?: string;\n  elevenlabsKey?: string;\n  geminiKey?: string;\n}\n\n/**\n * In-memory store mapping sessionId -> provider API keys.\n * Provider keys are NEVER placed in the JWT; they stay server-side only.\n */\nconst sessionKeyStore = new Map<string, ProviderKeys>();\n\n/**\n * Retrieve provider API keys associated with a session.\n * Returns `undefined` if the session is not found.\n */\nexport function getSessionKeys(sessionId: string): ProviderKeys | undefined {\n  return sessionKeyStore.get(sessionId);\n}\n\n/**\n * Remove provider API keys for a session (e.g. on expiry or logout).\n */\nexport function clearSessionKeys(sessionId: string): boolean {\n  return sessionKeyStore.delete(sessionId);\n}\n\n// ---------------------------------------------------------------------------\n// Duration parsing\n// ---------------------------------------------------------------------------\n\n/**\n * Parse a human-readable duration string into seconds.\n *\n * Supported units:\n *  - `s` seconds\n *  - `m` minutes\n *  - `h` hours\n *  - `d` days\n *\n * Compound durations are supported (e.g. `2h30m`, `1d12h`).\n *\n * @throws {Error} If the duration string is empty or contains no valid segments.\n */\nfunction parseDuration(duration: string): number {\n  if (typeof duration !== 'string' || duration.trim().length === 0) {\n    throw new Error('Duration must be a non-empty string (e.g. \"15m\", \"1h\", \"30s\").');\n  }\n\n  const cleaned = duration.trim().toLowerCase();\n  const regex = /(\\d+)\\s*(d|h|m|s)/g;\n  let match: RegExpExecArray | null;\n  let totalSeconds = 0;\n  let matched = false;\n\n  while ((match = regex.exec(cleaned)) !== null) {\n    matched = true;\n    const value = parseInt(match[1]!, 10);\n    const unit = match[2]!;\n\n    switch (unit) {\n      case 's':\n        totalSeconds += value;\n        break;\n      case 'm':\n        totalSeconds += value * 60;\n        break;\n      case 'h':\n        totalSeconds += value * 3600;\n        break;\n      case 'd':\n        totalSeconds += value * 86400;\n        break;\n    }\n  }\n\n  if (!matched) {\n    throw new Error(\n      `Invalid duration format: \"${duration}\". ` +\n        'Expected a string like \"15m\", \"1h\", \"30s\", \"7d\", or compound \"2h30m\".',\n    );\n  }\n\n  if (totalSeconds <= 0) {\n    throw new Error('Duration must resolve to a positive number of seconds.');\n  }\n\n  return totalSeconds;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Encode a signing secret string into a Uint8Array suitable for HMAC operations.\n */\nfunction encodeSecret(secret: string): Uint8Array {\n  return new TextEncoder().encode(secret);\n}\n\n/**\n * Resolve the signing secret to use.\n *\n * - If a single string is provided, it is used directly.\n * - If an array is provided, the **first** element (newest) is used for signing.\n *\n * @throws {Error} If no signing secret is provided or the array is empty.\n */\nfunction resolveSigningSecret(signingSecret: string | string[]): string {\n  if (Array.isArray(signingSecret)) {\n    if (signingSecret.length === 0) {\n      throw new Error('signingSecret array must contain at least one secret.');\n    }\n    return signingSecret[0]!;\n  }\n\n  if (typeof signingSecret !== 'string' || signingSecret.length === 0) {\n    throw new Error('signingSecret must be a non-empty string or a non-empty array of strings.');\n  }\n\n  return signingSecret;\n}\n\n/**\n * Flatten signingSecret into an array for rotation-aware verification.\n */\nfunction resolveAllSecrets(signingSecret: string | string[]): string[] {\n  if (Array.isArray(signingSecret)) {\n    if (signingSecret.length === 0) {\n      throw new Error('signingSecret array must contain at least one secret.');\n    }\n    return signingSecret;\n  }\n\n  if (typeof signingSecret !== 'string' || signingSecret.length === 0) {\n    throw new Error('signingSecret must be a non-empty string or a non-empty array of strings.');\n  }\n\n  return [signingSecret];\n}\n\n// ---------------------------------------------------------------------------\n// createSessionToken\n// ---------------------------------------------------------------------------\n\n/**\n * Create a signed session token (JWT) for use with GuideKit client SDKs.\n *\n * Provider API keys (`deepgramKey`, `elevenlabsKey`, `geminiKey`) are\n * **never** embedded in the JWT. They are stored in a server-side in-memory\n * map keyed by `sessionId` and can be retrieved via {@link getSessionKeys}.\n */\nexport async function createSessionToken(\n  options: CreateSessionTokenOptions,\n): Promise<CreateSessionTokenResult> {\n  const {\n    signingSecret,\n    deepgramKey,\n    elevenlabsKey,\n    geminiKey,\n    expiresIn = '15m',\n    allowedOrigins,\n    permissions = ['stt', 'tts', 'llm'],\n    userId,\n    sessionId = crypto.randomUUID(),\n    metadata,\n  } = options;\n\n  // Resolve the secret to sign with (first / newest).\n  const secret = resolveSigningSecret(signingSecret);\n\n  // Parse the requested lifetime.\n  const lifetimeSeconds = parseDuration(expiresIn);\n\n  // Build the JWT payload — provider keys are intentionally excluded.\n  const now = Math.floor(Date.now() / 1000);\n  const expiresAt = now + lifetimeSeconds;\n\n  const jwtPayload: JWTPayload & {\n    sessionId: string;\n    permissions: string[];\n    userId?: string;\n    metadata?: Record<string, unknown>;\n  } = {\n    sessionId,\n    permissions,\n  };\n\n  if (userId !== undefined) {\n    jwtPayload.userId = userId;\n  }\n\n  if (metadata !== undefined && Object.keys(metadata).length > 0) {\n    jwtPayload.metadata = metadata;\n  }\n\n  if (allowedOrigins !== undefined && allowedOrigins.length > 0) {\n    jwtPayload.aud = allowedOrigins;\n  }\n\n  const token = await new SignJWT(jwtPayload)\n    .setProtectedHeader({ alg: 'HS256' })\n    .setIssuedAt(now)\n    .setExpirationTime(expiresAt)\n    .sign(encodeSecret(secret));\n\n  // Store provider keys server-side, keyed by sessionId.\n  const providerKeys: ProviderKeys = {};\n  if (deepgramKey) providerKeys.deepgramKey = deepgramKey;\n  if (elevenlabsKey) providerKeys.elevenlabsKey = elevenlabsKey;\n  if (geminiKey) providerKeys.geminiKey = geminiKey;\n\n  if (Object.keys(providerKeys).length > 0) {\n    sessionKeyStore.set(sessionId, providerKeys);\n  }\n\n  return {\n    token,\n    expiresIn: lifetimeSeconds,\n    expiresAt,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// validateSessionToken\n// ---------------------------------------------------------------------------\n\n/**\n * Validate and decode a GuideKit session token.\n *\n * When `signingSecret` is an array, the function tries each secret in order\n * to support zero-downtime key rotation. Verification succeeds as soon as\n * any secret produces a valid result.\n */\nexport async function validateSessionToken(\n  token: string,\n  signingSecret: string | string[],\n  options?: ValidateSessionTokenOptions,\n): Promise<ValidateSessionTokenResult> {\n  if (typeof token !== 'string' || token.trim().length === 0) {\n    return { valid: false, error: 'Token must be a non-empty string.' };\n  }\n\n  const secrets = resolveAllSecrets(signingSecret);\n  let lastError: unknown;\n\n  for (const secret of secrets) {\n    try {\n      const verifyOptions: Parameters<typeof jwtVerify>[2] = {\n        algorithms: ['HS256'],\n      };\n\n      if (options?.audience) {\n        verifyOptions.audience = options.audience;\n      }\n\n      const { payload } = await jwtVerify(token, encodeSecret(secret), verifyOptions);\n\n      const tokenPayload: TokenPayload = {\n        sessionId: payload.sessionId as string,\n        expiresAt: payload.exp as number,\n        audience: normalizeAudience(payload.aud),\n        permissions: (payload.permissions as string[]) ?? [],\n        iat: payload.iat as number,\n      };\n\n      if (payload.userId !== undefined) {\n        tokenPayload.userId = payload.userId as string;\n      }\n\n      if (payload.metadata !== undefined) {\n        tokenPayload.metadata = payload.metadata as Record<string, unknown>;\n      }\n\n      return { valid: true, payload: tokenPayload };\n    } catch (err) {\n      lastError = err;\n      // Continue to next secret — it may have been rotated.\n    }\n  }\n\n  // All secrets failed.\n  const message =\n    lastError instanceof Error ? lastError.message : 'Token validation failed.';\n  return { valid: false, error: message };\n}\n\n/**\n * Normalize the JWT `aud` claim into a string array.\n */\nfunction normalizeAudience(aud: unknown): string[] {\n  if (aud === undefined || aud === null) return [];\n  if (typeof aud === 'string') return [aud];\n  if (Array.isArray(aud)) return aud.filter((a): a is string => typeof a === 'string');\n  return [];\n}\n\n// ---------------------------------------------------------------------------\n// generateSecret\n// ---------------------------------------------------------------------------\n\n/**\n * Generate a cryptographically random 256-bit (32-byte) base64url-encoded\n * secret suitable for use as a GuideKit signing secret.\n *\n * Usage: `npx guidekit generate-secret`\n */\nexport function generateSecret(): string {\n  const bytes = new Uint8Array(32);\n  crypto.getRandomValues(bytes);\n  return base64UrlEncode(bytes);\n}\n\n/**\n * Base64url-encode a Uint8Array without padding, per RFC 4648 section 5.\n */\nfunction base64UrlEncode(bytes: Uint8Array): string {\n  let binary = '';\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]!);\n  }\n  return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,73 @@
+interface TokenPayload {
+    sessionId: string;
+    expiresAt: number;
+    audience: string[];
+    permissions: string[];
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    iat: number;
+}
+interface CreateSessionTokenOptions {
+    signingSecret: string | string[];
+    deepgramKey?: string;
+    elevenlabsKey?: string;
+    geminiKey?: string;
+    expiresIn?: string;
+    allowedOrigins?: string[];
+    permissions?: string[];
+    userId?: string;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateSessionTokenResult {
+    token: string;
+    expiresIn: number;
+    expiresAt: number;
+}
+interface ValidateSessionTokenResult {
+    valid: boolean;
+    payload?: TokenPayload;
+    error?: string;
+}
+interface ValidateSessionTokenOptions {
+    audience?: string;
+}
+interface ProviderKeys {
+    deepgramKey?: string;
+    elevenlabsKey?: string;
+    geminiKey?: string;
+}
+/**
+ * Retrieve provider API keys associated with a session.
+ * Returns `undefined` if the session is not found.
+ */
+declare function getSessionKeys(sessionId: string): ProviderKeys | undefined;
+/**
+ * Remove provider API keys for a session (e.g. on expiry or logout).
+ */
+declare function clearSessionKeys(sessionId: string): boolean;
+/**
+ * Create a signed session token (JWT) for use with GuideKit client SDKs.
+ *
+ * Provider API keys (`deepgramKey`, `elevenlabsKey`, `geminiKey`) are
+ * **never** embedded in the JWT. They are stored in a server-side in-memory
+ * map keyed by `sessionId` and can be retrieved via {@link getSessionKeys}.
+ */
+declare function createSessionToken(options: CreateSessionTokenOptions): Promise<CreateSessionTokenResult>;
+/**
+ * Validate and decode a GuideKit session token.
+ *
+ * When `signingSecret` is an array, the function tries each secret in order
+ * to support zero-downtime key rotation. Verification succeeds as soon as
+ * any secret produces a valid result.
+ */
+declare function validateSessionToken(token: string, signingSecret: string | string[], options?: ValidateSessionTokenOptions): Promise<ValidateSessionTokenResult>;
+/**
+ * Generate a cryptographically random 256-bit (32-byte) base64url-encoded
+ * secret suitable for use as a GuideKit signing secret.
+ *
+ * Usage: `npx guidekit generate-secret`
+ */
+declare function generateSecret(): string;
+
+export { type CreateSessionTokenOptions, type CreateSessionTokenResult, type TokenPayload, type ValidateSessionTokenOptions, type ValidateSessionTokenResult, clearSessionKeys, createSessionToken, generateSecret, getSessionKeys, validateSessionToken };

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+interface TokenPayload {
+    sessionId: string;
+    expiresAt: number;
+    audience: string[];
+    permissions: string[];
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    iat: number;
+}
+interface CreateSessionTokenOptions {
+    signingSecret: string | string[];
+    deepgramKey?: string;
+    elevenlabsKey?: string;
+    geminiKey?: string;
+    expiresIn?: string;
+    allowedOrigins?: string[];
+    permissions?: string[];
+    userId?: string;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateSessionTokenResult {
+    token: string;
+    expiresIn: number;
+    expiresAt: number;
+}
+interface ValidateSessionTokenResult {
+    valid: boolean;
+    payload?: TokenPayload;
+    error?: string;
+}
+interface ValidateSessionTokenOptions {
+    audience?: string;
+}
+interface ProviderKeys {
+    deepgramKey?: string;
+    elevenlabsKey?: string;
+    geminiKey?: string;
+}
+/**
+ * Retrieve provider API keys associated with a session.
+ * Returns `undefined` if the session is not found.
+ */
+declare function getSessionKeys(sessionId: string): ProviderKeys | undefined;
+/**
+ * Remove provider API keys for a session (e.g. on expiry or logout).
+ */
+declare function clearSessionKeys(sessionId: string): boolean;
+/**
+ * Create a signed session token (JWT) for use with GuideKit client SDKs.
+ *
+ * Provider API keys (`deepgramKey`, `elevenlabsKey`, `geminiKey`) are
+ * **never** embedded in the JWT. They are stored in a server-side in-memory
+ * map keyed by `sessionId` and can be retrieved via {@link getSessionKeys}.
+ */
+declare function createSessionToken(options: CreateSessionTokenOptions): Promise<CreateSessionTokenResult>;
+/**
+ * Validate and decode a GuideKit session token.
+ *
+ * When `signingSecret` is an array, the function tries each secret in order
+ * to support zero-downtime key rotation. Verification succeeds as soon as
+ * any secret produces a valid result.
+ */
+declare function validateSessionToken(token: string, signingSecret: string | string[], options?: ValidateSessionTokenOptions): Promise<ValidateSessionTokenResult>;
+/**
+ * Generate a cryptographically random 256-bit (32-byte) base64url-encoded
+ * secret suitable for use as a GuideKit signing secret.
+ *
+ * Usage: `npx guidekit generate-secret`
+ */
+declare function generateSecret(): string;
+
+export { type CreateSessionTokenOptions, type CreateSessionTokenResult, type TokenPayload, type ValidateSessionTokenOptions, type ValidateSessionTokenResult, clearSessionKeys, createSessionToken, generateSecret, getSessionKeys, validateSessionToken };

package/dist/index.js

@@ -0,0 +1,177 @@
+import { SignJWT, jwtVerify } from 'jose';
+
+// src/index.ts
+var sessionKeyStore = /* @__PURE__ */ new Map();
+function getSessionKeys(sessionId) {
+  return sessionKeyStore.get(sessionId);
+}
+function clearSessionKeys(sessionId) {
+  return sessionKeyStore.delete(sessionId);
+}
+function parseDuration(duration) {
+  if (typeof duration !== "string" || duration.trim().length === 0) {
+    throw new Error('Duration must be a non-empty string (e.g. "15m", "1h", "30s").');
+  }
+  const cleaned = duration.trim().toLowerCase();
+  const regex = /(\d+)\s*(d|h|m|s)/g;
+  let match;
+  let totalSeconds = 0;
+  let matched = false;
+  while ((match = regex.exec(cleaned)) !== null) {
+    matched = true;
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    switch (unit) {
+      case "s":
+        totalSeconds += value;
+        break;
+      case "m":
+        totalSeconds += value * 60;
+        break;
+      case "h":
+        totalSeconds += value * 3600;
+        break;
+      case "d":
+        totalSeconds += value * 86400;
+        break;
+    }
+  }
+  if (!matched) {
+    throw new Error(
+      `Invalid duration format: "${duration}". Expected a string like "15m", "1h", "30s", "7d", or compound "2h30m".`
+    );
+  }
+  if (totalSeconds <= 0) {
+    throw new Error("Duration must resolve to a positive number of seconds.");
+  }
+  return totalSeconds;
+}
+function encodeSecret(secret) {
+  return new TextEncoder().encode(secret);
+}
+function resolveSigningSecret(signingSecret) {
+  if (Array.isArray(signingSecret)) {
+    if (signingSecret.length === 0) {
+      throw new Error("signingSecret array must contain at least one secret.");
+    }
+    return signingSecret[0];
+  }
+  if (typeof signingSecret !== "string" || signingSecret.length === 0) {
+    throw new Error("signingSecret must be a non-empty string or a non-empty array of strings.");
+  }
+  return signingSecret;
+}
+function resolveAllSecrets(signingSecret) {
+  if (Array.isArray(signingSecret)) {
+    if (signingSecret.length === 0) {
+      throw new Error("signingSecret array must contain at least one secret.");
+    }
+    return signingSecret;
+  }
+  if (typeof signingSecret !== "string" || signingSecret.length === 0) {
+    throw new Error("signingSecret must be a non-empty string or a non-empty array of strings.");
+  }
+  return [signingSecret];
+}
+async function createSessionToken(options) {
+  const {
+    signingSecret,
+    deepgramKey,
+    elevenlabsKey,
+    geminiKey,
+    expiresIn = "15m",
+    allowedOrigins,
+    permissions = ["stt", "tts", "llm"],
+    userId,
+    sessionId = crypto.randomUUID(),
+    metadata
+  } = options;
+  const secret = resolveSigningSecret(signingSecret);
+  const lifetimeSeconds = parseDuration(expiresIn);
+  const now = Math.floor(Date.now() / 1e3);
+  const expiresAt = now + lifetimeSeconds;
+  const jwtPayload = {
+    sessionId,
+    permissions
+  };
+  if (userId !== void 0) {
+    jwtPayload.userId = userId;
+  }
+  if (metadata !== void 0 && Object.keys(metadata).length > 0) {
+    jwtPayload.metadata = metadata;
+  }
+  if (allowedOrigins !== void 0 && allowedOrigins.length > 0) {
+    jwtPayload.aud = allowedOrigins;
+  }
+  const token = await new SignJWT(jwtPayload).setProtectedHeader({ alg: "HS256" }).setIssuedAt(now).setExpirationTime(expiresAt).sign(encodeSecret(secret));
+  const providerKeys = {};
+  if (deepgramKey) providerKeys.deepgramKey = deepgramKey;
+  if (elevenlabsKey) providerKeys.elevenlabsKey = elevenlabsKey;
+  if (geminiKey) providerKeys.geminiKey = geminiKey;
+  if (Object.keys(providerKeys).length > 0) {
+    sessionKeyStore.set(sessionId, providerKeys);
+  }
+  return {
+    token,
+    expiresIn: lifetimeSeconds,
+    expiresAt
+  };
+}
+async function validateSessionToken(token, signingSecret, options) {
+  if (typeof token !== "string" || token.trim().length === 0) {
+    return { valid: false, error: "Token must be a non-empty string." };
+  }
+  const secrets = resolveAllSecrets(signingSecret);
+  let lastError;
+  for (const secret of secrets) {
+    try {
+      const verifyOptions = {
+        algorithms: ["HS256"]
+      };
+      if (options?.audience) {
+        verifyOptions.audience = options.audience;
+      }
+      const { payload } = await jwtVerify(token, encodeSecret(secret), verifyOptions);
+      const tokenPayload = {
+        sessionId: payload.sessionId,
+        expiresAt: payload.exp,
+        audience: normalizeAudience(payload.aud),
+        permissions: payload.permissions ?? [],
+        iat: payload.iat
+      };
+      if (payload.userId !== void 0) {
+        tokenPayload.userId = payload.userId;
+      }
+      if (payload.metadata !== void 0) {
+        tokenPayload.metadata = payload.metadata;
+      }
+      return { valid: true, payload: tokenPayload };
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  const message = lastError instanceof Error ? lastError.message : "Token validation failed.";
+  return { valid: false, error: message };
+}
+function normalizeAudience(aud) {
+  if (aud === void 0 || aud === null) return [];
+  if (typeof aud === "string") return [aud];
+  if (Array.isArray(aud)) return aud.filter((a) => typeof a === "string");
+  return [];
+}
+function generateSecret() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+function base64UrlEncode(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export { clearSessionKeys, createSessionToken, generateSecret, getSessionKeys, validateSessionToken };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { SignJWT, jwtVerify, type JWTPayload } from 'jose';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface TokenPayload {\n  sessionId: string;\n  expiresAt: number;\n  audience: string[];\n  permissions: string[];\n  userId?: string;\n  metadata?: Record<string, unknown>;\n  iat: number;\n}\n\nexport interface CreateSessionTokenOptions {\n  signingSecret: string | string[];\n  deepgramKey?: string;\n  elevenlabsKey?: string;\n  geminiKey?: string;\n  expiresIn?: string;\n  allowedOrigins?: string[];\n  permissions?: string[];\n  userId?: string;\n  sessionId?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface CreateSessionTokenResult {\n  token: string;\n  expiresIn: number;\n  expiresAt: number;\n}\n\nexport interface ValidateSessionTokenResult {\n  valid: boolean;\n  payload?: TokenPayload;\n  error?: string;\n}\n\nexport interface ValidateSessionTokenOptions {\n  audience?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Server-side provider key store\n// ---------------------------------------------------------------------------\n\ninterface ProviderKeys {\n  deepgramKey?: string;\n  elevenlabsKey?: string;\n  geminiKey?: string;\n}\n\n/**\n * In-memory store mapping sessionId -> provider API keys.\n * Provider keys are NEVER placed in the JWT; they stay server-side only.\n */\nconst sessionKeyStore = new Map<string, ProviderKeys>();\n\n/**\n * Retrieve provider API keys associated with a session.\n * Returns `undefined` if the session is not found.\n */\nexport function getSessionKeys(sessionId: string): ProviderKeys | undefined {\n  return sessionKeyStore.get(sessionId);\n}\n\n/**\n * Remove provider API keys for a session (e.g. on expiry or logout).\n */\nexport function clearSessionKeys(sessionId: string): boolean {\n  return sessionKeyStore.delete(sessionId);\n}\n\n// ---------------------------------------------------------------------------\n// Duration parsing\n// ---------------------------------------------------------------------------\n\n/**\n * Parse a human-readable duration string into seconds.\n *\n * Supported units:\n *  - `s` seconds\n *  - `m` minutes\n *  - `h` hours\n *  - `d` days\n *\n * Compound durations are supported (e.g. `2h30m`, `1d12h`).\n *\n * @throws {Error} If the duration string is empty or contains no valid segments.\n */\nfunction parseDuration(duration: string): number {\n  if (typeof duration !== 'string' || duration.trim().length === 0) {\n    throw new Error('Duration must be a non-empty string (e.g. \"15m\", \"1h\", \"30s\").');\n  }\n\n  const cleaned = duration.trim().toLowerCase();\n  const regex = /(\\d+)\\s*(d|h|m|s)/g;\n  let match: RegExpExecArray | null;\n  let totalSeconds = 0;\n  let matched = false;\n\n  while ((match = regex.exec(cleaned)) !== null) {\n    matched = true;\n    const value = parseInt(match[1]!, 10);\n    const unit = match[2]!;\n\n    switch (unit) {\n      case 's':\n        totalSeconds += value;\n        break;\n      case 'm':\n        totalSeconds += value * 60;\n        break;\n      case 'h':\n        totalSeconds += value * 3600;\n        break;\n      case 'd':\n        totalSeconds += value * 86400;\n        break;\n    }\n  }\n\n  if (!matched) {\n    throw new Error(\n      `Invalid duration format: \"${duration}\". ` +\n        'Expected a string like \"15m\", \"1h\", \"30s\", \"7d\", or compound \"2h30m\".',\n    );\n  }\n\n  if (totalSeconds <= 0) {\n    throw new Error('Duration must resolve to a positive number of seconds.');\n  }\n\n  return totalSeconds;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Encode a signing secret string into a Uint8Array suitable for HMAC operations.\n */\nfunction encodeSecret(secret: string): Uint8Array {\n  return new TextEncoder().encode(secret);\n}\n\n/**\n * Resolve the signing secret to use.\n *\n * - If a single string is provided, it is used directly.\n * - If an array is provided, the **first** element (newest) is used for signing.\n *\n * @throws {Error} If no signing secret is provided or the array is empty.\n */\nfunction resolveSigningSecret(signingSecret: string | string[]): string {\n  if (Array.isArray(signingSecret)) {\n    if (signingSecret.length === 0) {\n      throw new Error('signingSecret array must contain at least one secret.');\n    }\n    return signingSecret[0]!;\n  }\n\n  if (typeof signingSecret !== 'string' || signingSecret.length === 0) {\n    throw new Error('signingSecret must be a non-empty string or a non-empty array of strings.');\n  }\n\n  return signingSecret;\n}\n\n/**\n * Flatten signingSecret into an array for rotation-aware verification.\n */\nfunction resolveAllSecrets(signingSecret: string | string[]): string[] {\n  if (Array.isArray(signingSecret)) {\n    if (signingSecret.length === 0) {\n      throw new Error('signingSecret array must contain at least one secret.');\n    }\n    return signingSecret;\n  }\n\n  if (typeof signingSecret !== 'string' || signingSecret.length === 0) {\n    throw new Error('signingSecret must be a non-empty string or a non-empty array of strings.');\n  }\n\n  return [signingSecret];\n}\n\n// ---------------------------------------------------------------------------\n// createSessionToken\n// ---------------------------------------------------------------------------\n\n/**\n * Create a signed session token (JWT) for use with GuideKit client SDKs.\n *\n * Provider API keys (`deepgramKey`, `elevenlabsKey`, `geminiKey`) are\n * **never** embedded in the JWT. They are stored in a server-side in-memory\n * map keyed by `sessionId` and can be retrieved via {@link getSessionKeys}.\n */\nexport async function createSessionToken(\n  options: CreateSessionTokenOptions,\n): Promise<CreateSessionTokenResult> {\n  const {\n    signingSecret,\n    deepgramKey,\n    elevenlabsKey,\n    geminiKey,\n    expiresIn = '15m',\n    allowedOrigins,\n    permissions = ['stt', 'tts', 'llm'],\n    userId,\n    sessionId = crypto.randomUUID(),\n    metadata,\n  } = options;\n\n  // Resolve the secret to sign with (first / newest).\n  const secret = resolveSigningSecret(signingSecret);\n\n  // Parse the requested lifetime.\n  const lifetimeSeconds = parseDuration(expiresIn);\n\n  // Build the JWT payload — provider keys are intentionally excluded.\n  const now = Math.floor(Date.now() / 1000);\n  const expiresAt = now + lifetimeSeconds;\n\n  const jwtPayload: JWTPayload & {\n    sessionId: string;\n    permissions: string[];\n    userId?: string;\n    metadata?: Record<string, unknown>;\n  } = {\n    sessionId,\n    permissions,\n  };\n\n  if (userId !== undefined) {\n    jwtPayload.userId = userId;\n  }\n\n  if (metadata !== undefined && Object.keys(metadata).length > 0) {\n    jwtPayload.metadata = metadata;\n  }\n\n  if (allowedOrigins !== undefined && allowedOrigins.length > 0) {\n    jwtPayload.aud = allowedOrigins;\n  }\n\n  const token = await new SignJWT(jwtPayload)\n    .setProtectedHeader({ alg: 'HS256' })\n    .setIssuedAt(now)\n    .setExpirationTime(expiresAt)\n    .sign(encodeSecret(secret));\n\n  // Store provider keys server-side, keyed by sessionId.\n  const providerKeys: ProviderKeys = {};\n  if (deepgramKey) providerKeys.deepgramKey = deepgramKey;\n  if (elevenlabsKey) providerKeys.elevenlabsKey = elevenlabsKey;\n  if (geminiKey) providerKeys.geminiKey = geminiKey;\n\n  if (Object.keys(providerKeys).length > 0) {\n    sessionKeyStore.set(sessionId, providerKeys);\n  }\n\n  return {\n    token,\n    expiresIn: lifetimeSeconds,\n    expiresAt,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// validateSessionToken\n// ---------------------------------------------------------------------------\n\n/**\n * Validate and decode a GuideKit session token.\n *\n * When `signingSecret` is an array, the function tries each secret in order\n * to support zero-downtime key rotation. Verification succeeds as soon as\n * any secret produces a valid result.\n */\nexport async function validateSessionToken(\n  token: string,\n  signingSecret: string | string[],\n  options?: ValidateSessionTokenOptions,\n): Promise<ValidateSessionTokenResult> {\n  if (typeof token !== 'string' || token.trim().length === 0) {\n    return { valid: false, error: 'Token must be a non-empty string.' };\n  }\n\n  const secrets = resolveAllSecrets(signingSecret);\n  let lastError: unknown;\n\n  for (const secret of secrets) {\n    try {\n      const verifyOptions: Parameters<typeof jwtVerify>[2] = {\n        algorithms: ['HS256'],\n      };\n\n      if (options?.audience) {\n        verifyOptions.audience = options.audience;\n      }\n\n      const { payload } = await jwtVerify(token, encodeSecret(secret), verifyOptions);\n\n      const tokenPayload: TokenPayload = {\n        sessionId: payload.sessionId as string,\n        expiresAt: payload.exp as number,\n        audience: normalizeAudience(payload.aud),\n        permissions: (payload.permissions as string[]) ?? [],\n        iat: payload.iat as number,\n      };\n\n      if (payload.userId !== undefined) {\n        tokenPayload.userId = payload.userId as string;\n      }\n\n      if (payload.metadata !== undefined) {\n        tokenPayload.metadata = payload.metadata as Record<string, unknown>;\n      }\n\n      return { valid: true, payload: tokenPayload };\n    } catch (err) {\n      lastError = err;\n      // Continue to next secret — it may have been rotated.\n    }\n  }\n\n  // All secrets failed.\n  const message =\n    lastError instanceof Error ? lastError.message : 'Token validation failed.';\n  return { valid: false, error: message };\n}\n\n/**\n * Normalize the JWT `aud` claim into a string array.\n */\nfunction normalizeAudience(aud: unknown): string[] {\n  if (aud === undefined || aud === null) return [];\n  if (typeof aud === 'string') return [aud];\n  if (Array.isArray(aud)) return aud.filter((a): a is string => typeof a === 'string');\n  return [];\n}\n\n// ---------------------------------------------------------------------------\n// generateSecret\n// ---------------------------------------------------------------------------\n\n/**\n * Generate a cryptographically random 256-bit (32-byte) base64url-encoded\n * secret suitable for use as a GuideKit signing secret.\n *\n * Usage: `npx guidekit generate-secret`\n */\nexport function generateSecret(): string {\n  const bytes = new Uint8Array(32);\n  crypto.getRandomValues(bytes);\n  return base64UrlEncode(bytes);\n}\n\n/**\n * Base64url-encode a Uint8Array without padding, per RFC 4648 section 5.\n */\nfunction base64UrlEncode(bytes: Uint8Array): string {\n  let binary = '';\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]!);\n  }\n  return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n}\n"]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@guidekit/server",
+  "version": "0.1.0-beta.1",
+  "description": "Server-side utilities for GuideKit SDK — token generation, auth middleware",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "../../LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run --config ../../vitest.config.ts",
+    "test:unit": "vitest run --config ../../vitest.config.ts",
+    "test:watch": "vitest --config ../../vitest.config.ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "jose": "^6.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsup": "^8.4.0",
+    "vitest": "^3.0.0",
+    "@types/node": "^22.0.0"
+  },
+  "sideEffects": false,
+  "license": "MIT"
+}