@guidekit/server 0.1.0-beta.1 → 0.1.0-beta.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 GuideKit
+
+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

@@ -19,9 +19,9 @@ import { createSessionToken } from '@guidekit/server';
 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,
+    llmApiKey: process.env.LLM_API_KEY!,
+    sttApiKey: process.env.STT_API_KEY,
+    ttsApiKey: process.env.TTS_API_KEY,
     expiresIn: '15m',
   });
 
@@ -36,10 +36,14 @@ 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!,
-});
+const result = await validateSessionToken(
+  bearerToken,
+  process.env.GUIDEKIT_SECRET!,
+);
+
+if (result.valid) {
+  console.log(result.payload);
+}
 ```
 
 ## Secret Rotation

package/dist/index.cjs

@@ -78,9 +78,9 @@ function resolveAllSecrets(signingSecret) {
 async function createSessionToken(options) {
   const {
     signingSecret,
-    deepgramKey,
-    elevenlabsKey,
-    geminiKey,
+    sttApiKey,
+    ttsApiKey,
+    llmApiKey,
     expiresIn = "15m",
     allowedOrigins,
     permissions = ["stt", "tts", "llm"],
@@ -107,9 +107,9 @@ async function createSessionToken(options) {
   }
   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 (sttApiKey) providerKeys.sttApiKey = sttApiKey;
+  if (ttsApiKey) providerKeys.ttsApiKey = ttsApiKey;
+  if (llmApiKey) providerKeys.llmApiKey = llmApiKey;
   if (Object.keys(providerKeys).length > 0) {
     sessionKeyStore.set(sessionId, providerKeys);
   }

package/dist/index.cjs.map

@@ -1 +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"]}
+{"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  sttApiKey?: string;\n  ttsApiKey?: string;\n  llmApiKey?: 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  sttApiKey?: string;\n  ttsApiKey?: string;\n  llmApiKey?: 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 (`sttApiKey`, `ttsApiKey`, `llmApiKey`) 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    sttApiKey,\n    ttsApiKey,\n    llmApiKey,\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 (sttApiKey) providerKeys.sttApiKey = sttApiKey;\n  if (ttsApiKey) providerKeys.ttsApiKey = ttsApiKey;\n  if (llmApiKey) providerKeys.llmApiKey = llmApiKey;\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

@@ -9,9 +9,9 @@ interface TokenPayload {
 }
 interface CreateSessionTokenOptions {
     signingSecret: string | string[];
-    deepgramKey?: string;
-    elevenlabsKey?: string;
-    geminiKey?: string;
+    sttApiKey?: string;
+    ttsApiKey?: string;
+    llmApiKey?: string;
     expiresIn?: string;
     allowedOrigins?: string[];
     permissions?: string[];
@@ -33,9 +33,9 @@ interface ValidateSessionTokenOptions {
     audience?: string;
 }
 interface ProviderKeys {
-    deepgramKey?: string;
-    elevenlabsKey?: string;
-    geminiKey?: string;
+    sttApiKey?: string;
+    ttsApiKey?: string;
+    llmApiKey?: string;
 }
 /**
  * Retrieve provider API keys associated with a session.
@@ -49,7 +49,7 @@ 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
+ * Provider API keys (`sttApiKey`, `ttsApiKey`, `llmApiKey`) 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}.
  */

package/dist/index.d.ts

@@ -9,9 +9,9 @@ interface TokenPayload {
 }
 interface CreateSessionTokenOptions {
     signingSecret: string | string[];
-    deepgramKey?: string;
-    elevenlabsKey?: string;
-    geminiKey?: string;
+    sttApiKey?: string;
+    ttsApiKey?: string;
+    llmApiKey?: string;
     expiresIn?: string;
     allowedOrigins?: string[];
     permissions?: string[];
@@ -33,9 +33,9 @@ interface ValidateSessionTokenOptions {
     audience?: string;
 }
 interface ProviderKeys {
-    deepgramKey?: string;
-    elevenlabsKey?: string;
-    geminiKey?: string;
+    sttApiKey?: string;
+    ttsApiKey?: string;
+    llmApiKey?: string;
 }
 /**
  * Retrieve provider API keys associated with a session.
@@ -49,7 +49,7 @@ 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
+ * Provider API keys (`sttApiKey`, `ttsApiKey`, `llmApiKey`) 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}.
  */

package/dist/index.js

@@ -76,9 +76,9 @@ function resolveAllSecrets(signingSecret) {
 async function createSessionToken(options) {
   const {
     signingSecret,
-    deepgramKey,
-    elevenlabsKey,
-    geminiKey,
+    sttApiKey,
+    ttsApiKey,
+    llmApiKey,
     expiresIn = "15m",
     allowedOrigins,
     permissions = ["stt", "tts", "llm"],
@@ -105,9 +105,9 @@ async function createSessionToken(options) {
   }
   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 (sttApiKey) providerKeys.sttApiKey = sttApiKey;
+  if (ttsApiKey) providerKeys.ttsApiKey = ttsApiKey;
+  if (llmApiKey) providerKeys.llmApiKey = llmApiKey;
   if (Object.keys(providerKeys).length > 0) {
     sessionKeyStore.set(sessionId, providerKeys);
   }

package/dist/index.js.map

@@ -1 +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"]}
+{"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  sttApiKey?: string;\n  ttsApiKey?: string;\n  llmApiKey?: 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  sttApiKey?: string;\n  ttsApiKey?: string;\n  llmApiKey?: 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 (`sttApiKey`, `ttsApiKey`, `llmApiKey`) 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    sttApiKey,\n    ttsApiKey,\n    llmApiKey,\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 (sttApiKey) providerKeys.sttApiKey = sttApiKey;\n  if (ttsApiKey) providerKeys.ttsApiKey = ttsApiKey;\n  if (llmApiKey) providerKeys.llmApiKey = llmApiKey;\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

@@ -1,6 +1,6 @@
 {
   "name": "@guidekit/server",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "description": "Server-side utilities for GuideKit SDK — token generation, auth middleware",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -15,18 +15,9 @@
   },
   "files": [
     "dist",
-    "../../LICENSE",
+    "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"
   },
@@ -37,5 +28,36 @@
     "@types/node": "^22.0.0"
   },
   "sideEffects": false,
-  "license": "MIT"
-}
+  "license": "MIT",
+  "author": "Riazul Islam",
+  "keywords": [
+    "guidekit",
+    "server",
+    "sdk",
+    "ai",
+    "auth",
+    "jwt",
+    "middleware"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/riaz37/guidekit.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/riaz37/guidekit#readme",
+  "bugs": {
+    "url": "https://github.com/riaz37/guidekit/issues"
+  },
+  "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"
+  }
+}