@nanogpt/private-mode 0.1.4 → 0.2.1

package/README.md

@@ -2,6 +2,8 @@
 
 OpenAI-compatible localhost proxy for NanoGPT Private Mode with supported TEE models.
 
+Requires Node.js 22 or later.
+
 ```bash
 NANOGPT_API_KEY=sk-your-key npx @nanogpt/private-mode
 ```
@@ -30,6 +32,8 @@ const response = await client.chat.completions.create({
 
 The local proxy verifies TEE attestation, encrypts request bodies with EHBP, sends ciphertext through NanoGPT, decrypts encrypted responses locally, and returns normal OpenAI JSON to the calling app.
 
+After a long idle period (five minutes by default), the proxy re-verifies attestation and creates a fresh encrypted transport before the next request. This makes laptop sleep/resume safe without requiring a proxy restart. Set `NANOGPT_PRIVATE_CLIENT_IDLE_RESET_MS` to a positive millisecond value to adjust the idle threshold.
+
 NanoGPT can see account identity, selected private model, selected TEE target metadata, timing, sizes, status, and usage metadata. NanoGPT cannot read the prompt or completion body for supported private models.
 
 NanoGPT's web app can also use these models without running this local proxy. Select an eligible Private Mode model and use the Private Mode control in the model picker. This package is for API clients, CLIs, agents, and other OpenAI-compatible tools.

package/lib/cacheScope.js

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+
+export function buildPrivateModeCacheScopeProof(cacheScope) {
+  const normalized = String(cacheScope || '').trim();
+  if (!/^[a-f0-9]{64}$/i.test(normalized)) {
+    throw new Error('Cannot prove an invalid Private Mode cache scope.');
+  }
+  return createHash('sha256').update(normalized, 'utf8').digest('hex');
+}

package/lib/originPolicy.js

@@ -28,20 +28,29 @@ function normalizeHostForOrigin(host) {
   return trimmed;
 }
 
+function addAllowedOrigin(allowedOrigins, origin) {
+  const normalizedOrigin = normalizePrivateModeOrigin(origin);
+  if (normalizedOrigin) allowedOrigins.add(normalizedOrigin);
+  return normalizedOrigin;
+}
+
+function addDefaultLoopbackOrigins(allowedOrigins, host, port) {
+  for (const defaultHost of DEFAULT_LOCAL_HOSTS) {
+    allowedOrigins.add(`http://${defaultHost}:${port}`);
+  }
+
+  const normalizedHost = normalizeHostForOrigin(host);
+  if (normalizedHost) {
+    addAllowedOrigin(allowedOrigins, `http://${normalizedHost}:${port}`);
+  }
+}
+
 export function buildPrivateModeOriginPolicy(options = {}) {
   const port = Number.parseInt(String(options.port || '8787'), 10);
   const allowedOrigins = new Set();
 
   if (Number.isFinite(port) && port > 0) {
-    for (const host of DEFAULT_LOCAL_HOSTS) {
-      allowedOrigins.add(`http://${host}:${port}`);
-    }
-
-    const normalizedHost = normalizeHostForOrigin(options.host);
-    if (normalizedHost) {
-      const origin = normalizePrivateModeOrigin(`http://${normalizedHost}:${port}`);
-      if (origin) allowedOrigins.add(origin);
-    }
+    addDefaultLoopbackOrigins(allowedOrigins, options.host, port);
   }
 
   const configuredOrigins = [
@@ -50,11 +59,9 @@ export function buildPrivateModeOriginPolicy(options = {}) {
   ];
 
   for (const configuredOrigin of configuredOrigins) {
-    const origin = normalizePrivateModeOrigin(configuredOrigin);
-    if (!origin) {
+    if (!addAllowedOrigin(allowedOrigins, configuredOrigin)) {
       throw new Error(`Invalid Private Mode browser origin "${configuredOrigin}". Use an http(s) origin, not a wildcard.`);
     }
-    allowedOrigins.add(origin);
   }
 
   return {

package/lib/requestTransforms.js

@@ -6,6 +6,11 @@ const ASSISTANT_REASONING_MESSAGE_FIELDS = [
   'reasoning_content',
   'reasoning_details',
 ];
+const MAX_TOKEN_ALIAS_FIELDS = [
+  'max_completion_tokens',
+  'maxCompletionTokens',
+  'maxTokens',
+];
 const PRIVATE_TINFOIL_CHAT_COMPLETION_BODY_FIELDS = new Set([
   'chat_template_kwargs',
   'frequency_penalty',
@@ -209,34 +214,37 @@ function applyTinfoilCompatibilityMutations(body, model) {
   }
 }
 
-export function applyPrivateModelRequestMutations(body, model) {
-  stripPrivateModeReasoningFromMessages(body);
-
-  if (body.max_tokens === undefined && body.max_completion_tokens !== undefined) {
-    body.max_tokens = body.max_completion_tokens;
-  }
-  if (body.max_tokens === undefined && body.maxCompletionTokens !== undefined) {
-    body.max_tokens = body.maxCompletionTokens;
-  }
-  if (body.max_tokens === undefined && body.maxTokens !== undefined) {
-    body.max_tokens = body.maxTokens;
+function normalizeMaxTokenAliases(body) {
+  for (const key of MAX_TOKEN_ALIAS_FIELDS) {
+    if (body.max_tokens === undefined && body[key] !== undefined) {
+      body.max_tokens = body[key];
+    }
+    delete body[key];
   }
-  delete body.max_completion_tokens;
-  delete body.maxCompletionTokens;
-  delete body.maxTokens;
+}
 
-  body.model = model.upstreamModel;
+function normalizeStreamOptions(body) {
   if (body.stream !== undefined) {
     body.stream = body.stream === true;
   }
+
   if (body.stream === true) {
     body.stream_options = {
       ...(body.stream_options && typeof body.stream_options === 'object' ? body.stream_options : {}),
       include_usage: true,
     };
-  } else {
-    delete body.stream_options;
+    return;
   }
+
+  delete body.stream_options;
+}
+
+export function applyPrivateModelRequestMutations(body, model) {
+  stripPrivateModeReasoningFromMessages(body);
+  normalizeMaxTokenAliases(body);
+
+  body.model = model.upstreamModel;
+  normalizeStreamOptions(body);
   applyTinfoilCompatibilityMutations(body, model);
 
   if (model.thinkingMode === 'gemma') {
@@ -246,14 +254,14 @@ export function applyPrivateModelRequestMutations(body, model) {
     };
     delete body.thinking;
     delete body.reasoning_effort;
-  } else if (model.thinkingMode === 'deepseek-v4-pro' || model.thinkingMode === 'glm-5.2') {
+  } else if (model.thinkingMode === 'kimi-k2.6' || model.thinkingMode === 'glm-5.2') {
     const thinkingEnabled = shouldEnableThinking(body, model);
     body.chat_template_kwargs = {
       ...mergeChatTemplateKwargs(body),
       thinking: thinkingEnabled,
     };
 
-    if (thinkingEnabled) {
+    if (model.thinkingMode === 'glm-5.2' && thinkingEnabled) {
       body.chat_template_kwargs.reasoning_effort =
         normalizeDeepSeekV4ReasoningEffort(body.reasoning_effort);
     } else {

package/lib/secureClientLifecycle.js

@@ -0,0 +1,126 @@
+const DEFAULT_SECURE_CLIENT_IDLE_RESET_MS = 5 * 60 * 1000;
+
+function readSecureClientIdleResetMs() {
+  const parsed = Number(process.env.NANOGPT_PRIVATE_CLIENT_IDLE_RESET_MS || '');
+  if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
+  return DEFAULT_SECURE_CLIENT_IDLE_RESET_MS;
+}
+
+export function createSecureState(apiBase, options = {}) {
+  const idleResetMs = Number.isFinite(options.idleResetMs) && options.idleResetMs > 0
+    ? Math.floor(options.idleResetMs)
+    : readSecureClientIdleResetMs();
+  const loadTinfoil = options.loadTinfoil || (() => import('tinfoil'));
+  const now = options.now || Date.now;
+  let clientState = null;
+  let verificationDocument = null;
+  let verificationError = null;
+
+  async function getClient(userCacheSecret = clientState?.userCacheSecret) {
+    if (!userCacheSecret) {
+      throw new Error('NanoGPT preflight must establish cache isolation before attestation.');
+    }
+    const nowMs = now();
+    const idleMs = clientState ? nowMs - clientState.lastUsedAtMs : 0;
+    if (
+      clientState?.userCacheSecret === userCacheSecret
+      && idleMs >= 0
+      && idleMs < idleResetMs
+    ) {
+      clientState.lastUsedAtMs = nowMs;
+      return clientState.promise;
+    }
+
+    // Re-attest after a long idle period or a wall-clock discontinuity. This
+    // covers laptops resuming after sleep without mutating a client that may
+    // still be finishing an older in-flight request.
+    verificationDocument = null;
+    verificationError = null;
+    const nextState = {
+      client: null,
+      lastUsedAtMs: nowMs,
+      promise: null,
+      userCacheSecret,
+    };
+    const promise = Promise.resolve(loadTinfoil()).then(async ({ SecureClient }) => {
+      const baseURL = `${apiBase}/api/v1/private/tinfoil/`;
+      const client = new SecureClient({
+        baseURL,
+        attestationBundleURL: `${apiBase}/api/v1/private/tinfoil`,
+        transport: 'ehbp',
+        userCacheSecret,
+      });
+      await client.ready();
+      nextState.client = client;
+      verificationDocument = client.getVerificationDocument();
+      verificationError = null;
+      return client;
+    });
+    nextState.promise = promise;
+    clientState = nextState;
+
+    try {
+      return await promise;
+    } catch (error) {
+      if (clientState === nextState) clientState = null;
+      verificationError = error;
+      throw error;
+    }
+  }
+
+  return {
+    getClient,
+    invalidateClient(client) {
+      if (!clientState) return false;
+      if (client && clientState.client !== client) return false;
+      clientState = null;
+      verificationDocument = null;
+      return true;
+    },
+    getVerificationState() {
+      return {
+        verified: verificationDocument?.securityVerified === true,
+        verificationDocument,
+        error: verificationError ? String(verificationError.message || verificationError) : null,
+      };
+    },
+  };
+}
+
+export async function isMissingEncryptedBodyHeaderResponse(response) {
+  if (response?.status !== 400) return false;
+  try {
+    const data = await response.clone().json();
+    return data?.error?.code === 'missing_encrypted_body_header';
+  } catch {
+    return false;
+  }
+}
+
+export async function fetchWithSecureClientRecovery({
+  fetchWithClient,
+  secureState,
+  shouldInvalidateError = () => true,
+  userCacheSecret,
+}) {
+  let client;
+  try {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      client = await secureState.getClient(userCacheSecret);
+      const response = await fetchWithClient(client);
+      if (attempt === 0 && await isMissingEncryptedBodyHeaderResponse(response)) {
+        await response.body?.cancel().catch(() => undefined);
+        secureState.invalidateClient(client);
+        continue;
+      }
+      return response;
+    }
+  } catch (error) {
+    if (client && shouldInvalidateError(error)) {
+      secureState.invalidateClient(client);
+    }
+    throw error;
+  }
+
+  throw new Error('Private Mode secure-client recovery exhausted unexpectedly.');
+}

package/lib/server.js

@@ -1,6 +1,7 @@
 import { createServer } from 'node:http';
 import { readFileSync } from 'node:fs';
 
+import { buildPrivateModeCacheScopeProof } from './cacheScope.js';
 import {
   buildPrivateModeOriginPolicy,
   getCorsHeadersForRequest,
@@ -10,6 +11,10 @@ import {
   normalizePrivateModeUpstreamErrorMessage,
   readErrorMessage,
 } from './serverErrorNormalization.js';
+import {
+  createSecureState,
+  fetchWithSecureClientRecovery,
+} from './secureClientLifecycle.js';
 import { buildPrivateModeStatusContract } from './statusContract.js';
 
 const MODELS = JSON.parse(
@@ -142,54 +147,13 @@ function readBody(req) {
 
 function copyLocalHeaders(req) {
   const headers = {};
-  const teamId = req.headers['x-team-id'];
+  const teamId = req?.headers?.['x-team-id'];
   if (typeof teamId === 'string' && teamId.trim()) {
     headers['x-team-id'] = teamId.trim();
   }
   return headers;
 }
 
-function createSecureState(apiBase) {
-  let clientPromise = null;
-  let verificationDocument = null;
-  let verificationError = null;
-
-  async function getClient() {
-    if (!clientPromise) {
-      clientPromise = import('tinfoil')
-        .then(async ({ SecureClient }) => {
-          const baseURL = `${apiBase}/api/v1/private/tinfoil/`;
-          const client = new SecureClient({
-            baseURL,
-            attestationBundleURL: `${apiBase}/api/v1/private/tinfoil`,
-            transport: 'ehbp',
-          });
-          await client.ready();
-          verificationDocument = client.getVerificationDocument();
-          verificationError = null;
-          return client;
-        })
-        .catch((error) => {
-          clientPromise = null;
-          verificationError = error;
-          throw error;
-        });
-    }
-    return clientPromise;
-  }
-
-  return {
-    getClient,
-    getVerificationState() {
-      return {
-        verified: verificationDocument?.securityVerified === true,
-        verificationDocument,
-        error: verificationError ? String(verificationError.message || verificationError) : null,
-      };
-    },
-  };
-}
-
 async function runPreflight({ apiBase, apiKey, model, req, requestBodyBytes }) {
   const preflightBody = { model: model.id };
   if (Number.isSafeInteger(requestBodyBytes) && requestBodyBytes >= 0) {
@@ -206,7 +170,27 @@ async function runPreflight({ apiBase, apiKey, model, req, requestBodyBytes }) {
     body: JSON.stringify(preflightBody),
   });
 
-  if (response.ok) return { ok: true };
+  if (response.ok) {
+    try {
+      const data = await response.json();
+      const cacheScope = typeof data?.cacheScope === 'string' ? data.cacheScope.trim() : '';
+      if (/^[a-f0-9]{64}$/i.test(cacheScope)) {
+        return { ok: true, cacheScope };
+      }
+    } catch {}
+
+    return {
+      ok: false,
+      status: 502,
+      body: {
+        error: {
+          message: 'NanoGPT preflight did not establish cache isolation.',
+          type: 'api_error',
+          code: 'cache_scope_unavailable',
+        },
+      },
+    };
+  }
 
   let errorBody = null;
   try {
@@ -223,6 +207,22 @@ async function runPreflight({ apiBase, apiKey, model, req, requestBodyBytes }) {
   return { ok: false, status: response.status, body: errorBody };
 }
 
+async function getPreflightedClient({ apiBase, apiKey, secureState, req, model = MODELS[0] }) {
+  const preflight = await runPreflight({
+    apiBase,
+    apiKey,
+    model,
+    req,
+    requestBodyBytes: 0,
+  });
+  if (!preflight.ok) {
+    throw new Error(
+      preflight.body?.error?.message || `NanoGPT preflight failed with HTTP ${preflight.status}`,
+    );
+  }
+  return secureState.getClient(preflight.cacheScope);
+}
+
 async function handleChatCompletion({ apiBase, apiKey, secureState, req, res, corsHeaders }) {
   let rawBody;
   try {
@@ -288,20 +288,25 @@ async function handleChatCompletion({ apiBase, apiKey, secureState, req, res, co
   });
 
   try {
-    const client = await secureState.getClient();
-    response = await client.fetch(`${apiBase}/api/v1/private/tinfoil/v1/chat/completions`, {
-      method: 'POST',
-      headers: {
-        authorization: `Bearer ${apiKey}`,
-        'content-type': 'application/json',
-        accept: privateStreamRequested ? 'text/event-stream' : 'application/json',
-        'x-nanogpt-private-model': model.id,
-        'x-nanogpt-private-stream': privateStreamRequested ? 'true' : 'false',
-        'x-query-source': 'api',
-        ...copyLocalHeaders(req),
-      },
-      body: privateRequestBody,
-      signal: upstreamAbortController.signal,
+    response = await fetchWithSecureClientRecovery({
+      secureState,
+      userCacheSecret: preflight.cacheScope,
+      shouldInvalidateError: () => !upstreamAbortController.signal.aborted,
+      fetchWithClient: (client) => client.fetch(`${apiBase}/api/v1/private/tinfoil/v1/chat/completions`, {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${apiKey}`,
+          'content-type': 'application/json',
+          accept: privateStreamRequested ? 'text/event-stream' : 'application/json',
+          'x-nanogpt-private-model': model.id,
+          'x-nanogpt-private-stream': privateStreamRequested ? 'true' : 'false',
+          'x-nanogpt-private-cache-scope': buildPrivateModeCacheScopeProof(preflight.cacheScope),
+          'x-query-source': 'api',
+          ...copyLocalHeaders(req),
+        },
+        body: privateRequestBody,
+        signal: upstreamAbortController.signal,
+      }),
     });
   } catch (error) {
     responseComplete = true;
@@ -309,7 +314,7 @@ async function handleChatCompletion({ apiBase, apiKey, secureState, req, res, co
     const message = error instanceof Error ? error.message : String(error);
     jsonResponse(res, 502, {
       error: {
-        message: `Private Mode request failed: ${normalizePrivateModeUpstreamErrorMessage(message, message)}`,
+        message: normalizePrivateModeUpstreamErrorMessage(message, 'Private Mode request failed.'),
         type: 'api_error',
         code: 'private_mode_request_failed',
       },
@@ -442,7 +447,12 @@ export async function startPrivateModeProxy(options) {
 
       if (req.method === 'GET' && url.pathname === '/v1/private-mode/attestation') {
         try {
-          await secureState.getClient();
+          await getPreflightedClient({
+            apiBase,
+            apiKey: options.apiKey,
+            secureState,
+            req,
+          });
           jsonResponse(res, 200, secureState.getVerificationState(), corsHeaders);
         } catch (error) {
           jsonResponse(res, 502, {
@@ -508,7 +518,11 @@ The verified TEE target and this local proxy can see plaintext.
   }
 
   if (options.warmAttestation !== false) {
-    secureState.getClient()
+    getPreflightedClient({
+      apiBase,
+      apiKey: options.apiKey,
+      secureState,
+    })
       .then((client) => {
         const doc = client.getVerificationDocument();
         process.stdout.write(`Attestation: verified=${doc.securityVerified === true}; enclave=${doc.enclaveHost || client.getEnclaveURL() || 'unknown'}\n`);

package/lib/serverErrorNormalization.js

@@ -1,45 +1,30 @@
-// Keep upstream error normalization in sync with lib/privateMode/tinfoilBrowserClient.ts.
-const UPSTREAM_OBJECT_SHAPE_ERROR_PATTERN = /object has no attribute ['"]get['"]/i;
+// Keep user-facing upstream error classification in sync with
+// lib/privateMode/tinfoilBrowserClient.ts. Never expose decrypted upstream
+// response bodies or exception text to local proxy clients.
 const MISSING_EHBP_RESPONSE_NONCE_PATTERN = /missing\s+ehbp-response-nonce\s+header/i;
+const PRIVATE_MODE_REFUND_NOTICE = 'Any reserved balance will be released or refunded.';
 
-export function normalizePrivateModeUpstreamErrorMessage(message, fallback) {
-  if (UPSTREAM_OBJECT_SHAPE_ERROR_PATTERN.test(message)) {
-    return 'Private Mode upstream returned an internal error while processing request metadata. Retry or choose another Private Mode model.';
+export function privateModeProviderFailureMessage(status) {
+  if (status === 429) {
+    return `Private Mode is temporarily rate-limited. ${PRIVATE_MODE_REFUND_NOTICE}`;
   }
-  if (MISSING_EHBP_RESPONSE_NONCE_PATTERN.test(message)) {
-    return 'Private Mode did not receive an encrypted response from Tinfoil. The private request may have been rejected before completion.';
+  return `The Private Mode provider temporarily failed. ${PRIVATE_MODE_REFUND_NOTICE}`;
+}
+
+export function normalizePrivateModeUpstreamErrorMessage(message, fallback) {
+  void fallback;
+  if (MISSING_EHBP_RESPONSE_NONCE_PATTERN.test(String(message || ''))) {
+    return `Private Mode could not verify the provider response. ${PRIVATE_MODE_REFUND_NOTICE}`;
   }
-  return message || fallback;
+  return privateModeProviderFailureMessage();
 }
 
 export async function readErrorMessage(response, fallback) {
-  let message = fallback;
+  void fallback;
   try {
-    const data = await response.clone().json();
-    if (data && typeof data === 'object' && !Array.isArray(data)) {
-      const error = data.error && typeof data.error === 'object' && !Array.isArray(data.error)
-        ? data.error
-        : {};
-      message = (
-        typeof error.message === 'string' && error.message.trim()
-          ? error.message
-          : typeof data.message === 'string' && data.message.trim()
-            ? data.message
-            : fallback
-      );
-    } else if (typeof data === 'string' && data.trim()) {
-      message = data;
-    } else if (typeof data === 'number' || typeof data === 'boolean') {
-      message = String(data);
-    }
+    await response?.body?.cancel();
   } catch {
-    try {
-      const text = await response.text();
-      message = text || fallback;
-    } catch {
-      message = fallback;
-    }
+    // The body may already be locked or closed. Its contents remain discarded.
   }
-
-  return normalizePrivateModeUpstreamErrorMessage(message, fallback);
+  return privateModeProviderFailureMessage(response?.status);
 }

package/models/private-tee.json

@@ -5,6 +5,7 @@
     "upstreamModel": "kimi-k2-6",
     "billingModel": "TEE/kimi-k2-6",
     "teeTargetModel": "kimi-k2-6",
+    "thinkingMode": "kimi-k2.6",
     "created": 1764547200,
     "ownedBy": "nanogpt-private-mode",
     "aliases": ["private/kimi-k2.6", "TEE/kimi-k2-6", "TEE/kimi-k2.6"]
@@ -72,27 +73,5 @@
     "created": 1764547200,
     "ownedBy": "nanogpt-private-mode",
     "aliases": ["TEE/gemma4-31b:thinking", "gemma4-31b:thinking"]
-  },
-  {
-    "id": "private/deepseek-v4-pro",
-    "name": "DeepSeek V4 Pro Private",
-    "upstreamModel": "deepseek-v4-pro",
-    "billingModel": "TEE/deepseek-v4-pro",
-    "teeTargetModel": "deepseek-v4-pro",
-    "thinkingMode": "deepseek-v4-pro",
-    "created": 1764547200,
-    "ownedBy": "nanogpt-private-mode",
-    "aliases": ["TEE/deepseek-v4-pro", "deepseek-v4-pro"]
-  },
-  {
-    "id": "private/deepseek-v4-pro:thinking",
-    "name": "DeepSeek V4 Pro Thinking Private",
-    "upstreamModel": "deepseek-v4-pro",
-    "billingModel": "TEE/deepseek-v4-pro:thinking",
-    "teeTargetModel": "deepseek-v4-pro",
-    "thinkingMode": "deepseek-v4-pro",
-    "created": 1764547200,
-    "ownedBy": "nanogpt-private-mode",
-    "aliases": ["TEE/deepseek-v4-pro:thinking", "deepseek-v4-pro:thinking"]
   }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanogpt/private-mode",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "OpenAI-compatible localhost proxy for NanoGPT Private Mode.",
   "type": "module",
   "publishConfig": {
@@ -12,8 +12,10 @@
   },
   "files": [
     "bin",
+    "lib/cacheScope.js",
     "lib/originPolicy.js",
     "lib/requestTransforms.js",
+    "lib/secureClientLifecycle.js",
     "lib/server.js",
     "lib/serverErrorNormalization.js",
     "lib/statusContract.js",
@@ -21,14 +23,15 @@
     "models",
     "README.md"
   ],
-  "scripts": {
-    "start": "node ./bin/nanogpt-private-mode.js"
-  },
   "dependencies": {
-    "tinfoil": "1.1.3"
+    "ai": "6.0.220",
+    "tinfoil": "1.1.12"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "start": "node ./bin/nanogpt-private-mode.js"
+  }
+}