humanenv 0.1.0

package/packages/client/src/index.ts

@@ -0,0 +1,31 @@
+import { HumanEnvClient, type ClientConfig } from './ws-manager.js';
+
+export { HumanEnvClient };
+export type { ClientConfig };
+
+let singleton: HumanEnvClient | null = null
+let configSet = false
+
+async function ensure(): Promise<HumanEnvClient> {
+  if (!singleton) throw new Error('humanenv.config() must be called first')
+  return singleton
+}
+
+export default {
+  config(cfg: ClientConfig): void {
+    if (configSet) return
+    configSet = true
+    singleton = new HumanEnvClient(cfg)
+  },
+  async get(keyOrKeys: string | string[]): Promise<string | Record<string, string>> {
+    const client = await ensure()
+    return client.get(keyOrKeys as any)
+  },
+  async set(key: string, value: string): Promise<void> {
+    const client = await ensure()
+    return client.set(key, value)
+  },
+  disconnect(): void {
+    if (singleton) { singleton.disconnect(); singleton = null; configSet = false }
+  },
+}

package/packages/client/src/shared/buffer-shim.d.ts

@@ -0,0 +1,4 @@
+// Suppress @types/node Buffer/Uint8Array incompatibility with TS 5.9+
+declare module 'node:buffer' {
+  interface Buffer extends Uint8Array {}
+}

package/packages/client/src/shared/crypto.ts

@@ -0,0 +1,98 @@
+import * as crypto from 'node:crypto'
+
+const PBKDF2_ITERATIONS = 100_000
+const PK_KEY_LENGTH = 32
+
+// ============================================================
+// Mnemonic helpers (BIP39-compatible wordlist handling)
+// ============================================================
+
+const BIP39_WORDLIST = [
+  'abandon', 'ability', 'able', 'about', 'above', 'absent', 'absorb', 'abstract',
+  'absurd', 'abuse', 'access', 'accident', 'account', 'accuse', 'achieve', 'acid',
+  'acoustic', 'acquire', 'across', 'act', 'action', 'actor', 'actress', 'actual',
+  'adapt', 'add', 'addict', 'address', 'adjust', 'admit', 'adult', 'advance',
+  'advice', 'aerobic', 'affair', 'afford', 'afraid', 'again', 'age', 'agent',
+  'agree', 'ahead', 'aim', 'air', 'airport', 'aisle', 'alarm', 'album',
+  'alcohol', 'alert', 'alien', 'all', 'alley', 'allow', 'almost', 'alone',
+  'alpha', 'already', 'also', 'alter', 'always', 'amateur', 'amazing', 'among',
+  'amount', 'amused', 'analyst', 'anchor', 'ancient', 'anger', 'angle', 'angry',
+  'animal', 'ankle', 'announce', 'annual', 'another', 'answer', 'antenna',
+  'antique', 'anxiety', 'any', 'apart', 'apology', 'appear', 'apple', 'approve',
+  'april', 'arch', 'arctic', 'area', 'arena', 'argue', 'arm', 'armed', 'armor',
+  'army', 'around', 'arrest', 'arrive', 'arrow', 'art', 'artist', 'artwork',
+  'ask', 'aspect', 'assault', 'asset', 'assist', 'assume', 'asthma', 'athlete',
+  'atom', 'attack', 'attend', 'attitude', 'attract', 'auction', 'audit', 'august',
+  'aunt', 'author', 'auto', 'autumn', 'average', 'avocado', 'avoid', 'awake',
+  'aware', 'awesome', 'awful', 'awkward', 'axis', 'baby', 'bachelor', 'bacon',
+  'badge', 'bag', 'balance', 'balcony', 'ball', 'bamboo', 'banana', 'banner',
+  'bar', 'barely', 'bargain', 'barrel', 'base', 'basic', 'basket', 'battle',
+  'beach', 'bean', 'beauty', 'because', 'become', 'beef', 'before', 'begin',
+  'behave', 'behind', 'believe', 'below', 'bench', 'benefit', 'best', 'betray',
+  'better', 'between', 'beyond', 'bicycle', 'bid', 'bike', 'bind', 'biology',
+  'bird', 'birth', 'bitter', 'black', 'blade', 'blame', 'blanket', 'blast'
+]
+
+export function generateMnemonic(): string {
+  const entropy = crypto.randomBytes(16)
+  const words: string[] = []
+  for (let i = 0; i < 32; i++) {
+    words.push(BIP39_WORDLIST[entropy[i]! % BIP39_WORDLIST.length])
+  }
+  return words.slice(0, 12).join(' ')
+}
+
+export function validateMnemonic(mnemonic: string): boolean {
+  const words = mnemonic.trim().toLowerCase().split(/\s+/)
+  if (words.length !== 12) return false
+  return words.every(w => BIP39_WORDLIST.includes(w))
+}
+
+export function derivePkFromMnemonic(mnemonic: string): Buffer {
+  return crypto.pbkdf2Sync(
+    mnemonic.toLowerCase().trim(),
+    'humanenv-server-v1',
+    PBKDF2_ITERATIONS,
+    PK_KEY_LENGTH,
+    'sha256'
+  ) as any
+}
+
+export function hashPkForVerification(pk: Buffer): string {
+  return crypto.createHash('sha256').update(pk as any).digest('hex')
+}
+
+export function encryptWithPk(value: string, pk: Buffer, aad: string): string {
+  const iv = crypto.randomBytes(12)
+  const cipher = crypto.createCipheriv('aes-256-gcm', pk as any, iv as any)
+  cipher.setAAD(crypto.createHash('sha256').update(aad).digest() as any)
+  const encrypted = Buffer.concat([cipher.update(value, 'utf8') as any, cipher.final() as any])
+  const tag = cipher.getAuthTag()
+  return Buffer.concat([iv as any, tag as any, encrypted as any]).toString('base64')
+}
+
+export function decryptWithPk(encryptedBase64: string, pk: Buffer, aad: string): string {
+  const buf = Buffer.from(encryptedBase64, 'base64')
+  const iv = buf.subarray(0, 12) as any
+  const tag = buf.subarray(12, 28) as any
+  const ciphertext = buf.subarray(28) as any
+  const decipher = crypto.createDecipheriv('aes-256-gcm', pk as any, iv as any)
+  decipher.setAAD(crypto.createHash('sha256').update(aad).digest() as any)
+  decipher.setAuthTag(tag)
+  const decrypted = Buffer.concat([decipher.update(ciphertext) as any, decipher.final() as any])
+  return decrypted.toString('utf8')
+}
+
+export function generateFingerprint(): string {
+  const components = [
+    process.env.HOSTNAME || 'unknown-host',
+    process.platform,
+    process.arch,
+    process.version,
+  ]
+  return crypto
+    .createHash('sha256')
+    .update(components.join('|'))
+    .digest('hex')
+    .slice(0, 16)
+}

package/packages/client/src/shared/errors.ts

@@ -0,0 +1,32 @@
+export enum ErrorCode {
+  SERVER_PK_NOT_AVAILABLE = 'SERVER_PK_NOT_AVAILABLE',
+  CLIENT_AUTH_INVALID_PROJECT_NAME = 'CLIENT_AUTH_INVALID_PROJECT_NAME',
+  CLIENT_AUTH_NOT_WHITELISTED = 'CLIENT_AUTH_NOT_WHITELISTED',
+  CLIENT_AUTH_INVALID_API_KEY = 'CLIENT_AUTH_INVALID_API_KEY',
+  CLIENT_CONN_MAX_RETRIES_EXCEEDED = 'CLIENT_CONN_MAX_RETRIES_EXCEEDED',
+  ENV_API_MODE_ONLY = 'ENV_API_MODE_ONLY',
+  SERVER_INTERNAL_ERROR = 'SERVER_INTERNAL_ERROR',
+  WS_CONNECTION_FAILED = 'WS_CONNECTION_FAILED',
+  DB_OPERATION_FAILED = 'DB_OPERATION_FAILED',
+}
+
+export const ErrorMessages: Record<ErrorCode, string> = {
+  SERVER_PK_NOT_AVAILABLE: 'Server private key is not available. Restart pending.',
+  CLIENT_AUTH_INVALID_PROJECT_NAME: 'Invalid or unknown project name.',
+  CLIENT_AUTH_NOT_WHITELISTED: 'Client fingerprint is not whitelisted for this project.',
+  CLIENT_AUTH_INVALID_API_KEY: 'Invalid or expired API key.',
+  CLIENT_CONN_MAX_RETRIES_EXCEEDED: 'Maximum WS connection retries exceeded.',
+  ENV_API_MODE_ONLY: 'This env is API-mode only and cannot be accessed via CLI.',
+  SERVER_INTERNAL_ERROR: 'An internal server error occurred.',
+  WS_CONNECTION_FAILED: 'Failed to establish WebSocket connection.',
+  DB_OPERATION_FAILED: 'Database operation failed.',
+}
+
+export class HumanEnvError extends Error {
+  public readonly code: ErrorCode
+  constructor(code: ErrorCode, message?: string) {
+    super(message ?? ErrorMessages[code])
+    this.name = 'HumanEnvError'
+    this.code = code
+  }
+}

package/packages/client/src/shared/index.ts

@@ -0,0 +1,3 @@
+export * from './errors'
+export * from './types'
+export * from './crypto'

package/packages/client/src/shared/types.ts

@@ -0,0 +1,118 @@
+// ============================================================
+// Domain models
+// ============================================================
+
+export interface Project {
+  id: string
+  name: string
+  createdAt: number
+}
+
+export interface Env {
+  id: string
+  projectId: string
+  key: string
+  encryptedValue: string
+  apiModeOnly: boolean
+  createdAt: number
+}
+
+export interface ApiKey {
+  id: string
+  projectId: string
+  encryptedValue: string
+  ttl?: number
+  expiresAt?: number
+  createdAt: number
+}
+
+export interface WhitelistEntry {
+  id: string
+  projectId: string
+  fingerprint: string
+  status: 'pending' | 'approved' | 'rejected'
+  createdAt: number
+}
+
+// ============================================================
+// WebSocket message types
+// ============================================================
+
+export type WsMessage =
+  | { type: 'auth'; payload: AuthPayload }
+  | { type: 'auth_response'; payload: AuthResponse }
+  | { type: 'get'; payload: { key: string } }
+  | { type: 'get_response'; payload: { key: string; value: string } | { error: string; code: string } }
+  | { type: 'set'; payload: { key: string; value: string } }
+  | { type: 'set_response'; payload: { success: boolean } | { error: string; code: string } }
+  | { type: 'generate_api_key'; payload: { projectName: string } }
+  | { type: 'apikey_request'; payload: { clientFingerprint: string; projectName: string } }
+  | { type: 'apikey_response'; payload: { success: boolean; apiKey?: string } | { error: string; code: string } }
+  | { type: 'whitelist_request'; payload: { fingerprint: string; projectName: string } }
+  | { type: 'whitelist_response'; payload: { fingerprint: string; approved: boolean } }
+  | { type: 'disconnect'; payload?: never }
+  | { type: 'ping'; payload?: never }
+  | { type: 'pong'; payload?: never }
+
+export interface AuthPayload {
+  projectName: string
+  apiKey: string
+  fingerprint: string
+}
+
+export interface AuthResponse {
+  success: boolean
+  whitelisted: boolean
+  error?: string
+  code?: string
+}
+
+// ============================================================
+// Client library config
+// ============================================================
+
+export interface ClientConfig {
+  serverUrl: string
+  projectName: string
+  projectApiKey?: string
+  maxRetries?: number
+}
+
+export interface ServerConfig {
+  port: number
+  basicAuth?: { username: string; password: string }
+  dataDir: string
+  dbUri?: string
+}
+
+export type CredentialStore = {
+  projectName: string
+  serverUrl: string
+  apiKey?: string
+}
+
+export interface SkillMetadata {
+  name: string
+  description: string
+  category?: string
+}
+
+export const SKILL_CONTENT = `---
+name: humanenv-usage
+description: Use humanenv to retrieve sensitives/envs. Never log/read sensitives from humanenv. They are envs for humans only.
+---
+
+## How to retrieve sensitives
+
+### JavaScript API
+Use \`humanenv.get('key')\` inside your application. The returned value must be used immediately and then set to \`null\` to prevent memory leaks.
+
+### CLI (non-TTY mode)
+Only non-API-mode envs are accessible. Do not attempt to use this to log or dump all envs.
+
+## Rules
+1. NEVER log env values retrieved from humanenv
+2. NEVER dump or export multiple values at once
+3. ALWAYS null variables after use
+4. NEVER write sensitives to files
+5. Do not generate scripts that use humanenv in loops or to exfiltrate data`

package/packages/client/src/ws-manager.ts

@@ -0,0 +1,263 @@
+import { generateFingerprint, ErrorCode, HumanEnvError } from './shared'
+import WebSocket from 'ws'
+
+export type ClientConfig = {
+  serverUrl: string
+  projectName: string
+  projectApiKey?: string
+  maxRetries?: number
+}
+
+type PendingOp = {
+  resolve: (v: any) => void
+  reject: (e: Error) => void
+  timeout: ReturnType<typeof setTimeout>
+}
+
+export class HumanEnvClient {
+  private ws: WebSocket | null = null
+  private connected = false
+  private authenticated = false
+  private _whitelistStatus: 'approved' | 'pending' | 'rejected' | null = null
+  private attempts = 0
+  private pending = new Map<string, PendingOp>()
+  private config: Required<ClientConfig>
+  private retryTimer: ReturnType<typeof setTimeout> | null = null
+  private pingTimer: ReturnType<typeof setInterval> | null = null
+  private reconnecting = false
+  private disconnecting = false
+  private _authResolve: (() => void) | null = null
+  private _authReject: ((e: Error) => void) | null = null
+
+  get whitelistStatus(): 'approved' | 'pending' | 'rejected' | null {
+    return this._whitelistStatus
+  }
+
+  constructor(config: ClientConfig) {
+    this.config = {
+      serverUrl: config.serverUrl,
+      projectName: config.projectName,
+      projectApiKey: config.projectApiKey || '',
+      maxRetries: config.maxRetries ?? 10,
+    }
+  }
+
+  private getFingerprint(): string {
+    return generateFingerprint()
+  }
+
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.doConnect(resolve, reject)
+    })
+  }
+
+  private doConnect(resolve: () => void, reject: (e: Error) => void): void {
+    const proto = this.config.serverUrl.startsWith('https') ? 'wss' : 'ws'
+    const host = this.config.serverUrl.replace(/^https?:\/\//, '').replace(/\/+$/, '')
+    const url = `${proto}://${host}/ws`
+
+    this.ws = new WebSocket(url)
+
+    this.ws.on('open', () => {
+      this.connected = true
+      this.attempts = 0
+      this.reconnecting = false
+      this.startPing()
+      this.sendAuth(resolve, reject)
+    })
+
+    this.ws.on('message', (raw: Buffer) => {
+      try {
+        const msg = JSON.parse(raw.toString())
+        this.handleMessage(msg)
+      } catch { /* ignore */ }
+    })
+
+    this.ws.on('close', () => {
+      this.connected = false
+      this.authenticated = false
+      this.stopPing()
+      if (!this.disconnecting && !this.reconnecting) this.scheduleReconnect(reject)
+    })
+
+    this.ws.on('error', () => { /* handled via close */ })
+  }
+
+  private sendAuth(resolve: () => void, reject: (e: Error) => void): void {
+    this._authResolve = resolve
+    this._authReject = reject
+    this.ws?.send(JSON.stringify({
+      type: 'auth',
+      payload: {
+        projectName: this.config.projectName,
+        apiKey: this.config.projectApiKey,
+        fingerprint: this.getFingerprint(),
+      }
+    }))
+  }
+
+  private handleMessage(msg: any): void {
+    if (msg.type === 'auth_response') {
+      if (msg.payload.success) {
+        this.authenticated = true
+        this._whitelistStatus = msg.payload.status || (msg.payload.whitelisted ? 'approved' : 'pending')
+        this._authResolve?.()
+      } else {
+        this._authReject?.(new HumanEnvError(msg.payload.code as ErrorCode, msg.payload.error))
+      }
+      this._authResolve = null
+      this._authReject = null
+      return
+    }
+
+    if (msg.type === 'get_response') {
+      this._resolvePending('get', msg.payload)
+      return
+    }
+
+    if (msg.type === 'set_response') {
+      this._resolvePending('set', msg.payload)
+      return
+    }
+
+    if (msg.type === 'pong') { /* keep-alive */ }
+  }
+
+  private _resolvePending(kind: 'get' | 'set', payload: any): void {
+    for (const [id, op] of this.pending) {
+      clearTimeout(op.timeout)
+      this.pending.delete(id)
+      if (payload.error) {
+        op.reject(new HumanEnvError(payload.code as ErrorCode, payload.error))
+      } else {
+        op.resolve(payload)
+      }
+      return
+    }
+  }
+
+  async get(key: string): Promise<string>
+  async get(keys: string[]): Promise<Record<string, string>>
+  async get(keyOrKeys: string | string[]): Promise<string | Record<string, string>> {
+    if (!this.connected || !this.authenticated) throw new HumanEnvError(ErrorCode.CLIENT_AUTH_INVALID_API_KEY)
+
+    if (Array.isArray(keyOrKeys)) {
+      const result: Record<string, string> = {}
+      await Promise.all(keyOrKeys.map(async (key) => {
+        result[key] = await this._getSingle(key)
+      }))
+      return result
+    }
+    return this._getSingle(keyOrKeys)
+  }
+
+  private _getSingle(key: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const msgId = `${key}-${Date.now()}`
+      const timeout = setTimeout(() => {
+        this.pending.delete(msgId)
+        reject(new Error(`Timeout getting env: ${key}`))
+      }, 8000)
+      this.pending.set(msgId, { resolve: (v: any) => resolve(v.value), reject, timeout })
+      this.ws?.send(JSON.stringify({ type: 'get', payload: { key } }))
+    })
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    if (!this.connected || !this.authenticated) throw new HumanEnvError(ErrorCode.CLIENT_AUTH_INVALID_API_KEY)
+    const msgId = `set-${Date.now()}`
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(msgId)
+        reject(new Error(`Timeout setting env: ${key}`))
+      }, 8000)
+      this.pending.set(msgId, { resolve, reject, timeout })
+      this.ws?.send(JSON.stringify({ type: 'set', payload: { key, value } }))
+    })
+  }
+
+  private scheduleReconnect(reject: (e: Error) => void): void {
+    if (this.attempts >= this.config.maxRetries) {
+      reject(new HumanEnvError(ErrorCode.CLIENT_CONN_MAX_RETRIES_EXCEEDED))
+      return
+    }
+    this.reconnecting = true
+    this.attempts++
+    const delay = Math.min(1000 * Math.pow(2, this.attempts - 1), 30000)
+    if (process.stdout.isTTY) {
+      console.error(`[humanenv] Reconnecting in ${delay}ms (attempt ${this.attempts}/${this.config.maxRetries})...`)
+    }
+    this.retryTimer = setTimeout(() => {
+      this.doConnect(() => {}, reject)
+    }, delay)
+  }
+
+  private startPing(): void {
+    this.stopPing()
+    this.pingTimer = setInterval(() => {
+      if (this.ws?.readyState === WebSocket.OPEN) {
+        this.ws.send(JSON.stringify({ type: 'ping' }))
+      }
+    }, 30000)
+  }
+
+  private stopPing(): void {
+    if (this.pingTimer) { clearInterval(this.pingTimer); this.pingTimer = null }
+  }
+
+  /** Send a generate_api_key request to the server */
+  async generateApiKey(): Promise<string> {
+    if (!this.connected || !this.authenticated) throw new Error('Client not authenticated')
+    return new Promise((resolve, reject) => {
+      const msgId = `genkey-${Date.now()}`
+      const timeout = setTimeout(() => {
+        this.pending.delete(msgId)
+        reject(new Error('Timeout waiting for API key generation'))
+      }, 60000)
+      this.pending.set(msgId, { resolve: (v: any) => resolve(v.apiKey), reject, timeout })
+      this.ws?.send(JSON.stringify({ type: 'generate_api_key', payload: { projectName: this.config.projectName } }))
+    })
+  }
+
+  /** Connect (creates fresh WS) and waits for auth response up to `timeoutMs`. Resolves silently on timeout. */
+  async connectAndWaitForAuth(timeoutMs: number): Promise<void> {
+    return new Promise((resolve) => {
+      // If already connected and authenticated, resolve immediately
+      if (this.connected && this.authenticated) { resolve(); return }
+
+      const deadline = Date.now() + timeoutMs
+      const checkInterval = setInterval(() => {
+        if (this.connected && this.authenticated) {
+          clearInterval(checkInterval)
+          resolve()
+          return
+        }
+        if (Date.now() >= deadline) {
+          clearInterval(checkInterval)
+          resolve()
+          return
+        }
+      }, 200)
+
+      // If not connected, establish connection
+      if (!this.connected) {
+        this.attempts = 0
+        this.doConnect(() => {
+          // connected, now waiting for auth
+        }, () => {
+          clearInterval(checkInterval)
+          resolve()
+        })
+      }
+    })
+  }
+
+  disconnect(): void {
+    this.stopPing()
+    if (this.retryTimer) { clearTimeout(this.retryTimer); this.retryTimer = null }
+    this.disconnecting = true
+    this.reconnecting = false
+    this.ws?.close()
+  }
+}

package/packages/server/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "humanenv-server",
+  "version": "0.1.0",
+  "private": true,
+  "main": "./src/index.ts",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "humanenv-shared": "file:../shared",
+    "express": "^4.21.0",
+    "ws": "^8.18.0",
+    "better-sqlite3": "^11.6.0",
+    "mongodb": "^6.11.0",
+    "ejs": "^3.1.10",
+    "basic-auth": "^2.0.1",
+    "tsx": "^4.19.0"
+  }
+}

package/packages/server/src/auth.ts

@@ -0,0 +1,13 @@
+import express from 'express'
+import basicAuth from 'basic-auth'
+
+export function createBasicAuthMiddleware(username: string, password: string): express.RequestHandler {
+  return (req, res, next) => {
+    const credentials = basicAuth(req)
+    if (!credentials || credentials.name !== username || credentials.pass !== password) {
+      res.set('WWW-Authenticate', 'Basic realm="HumanEnv Admin"')
+      return res.status(401).send('Authentication required')
+    }
+    next()
+  }
+}

package/packages/server/src/db/index.ts

@@ -0,0 +1,19 @@
+import { IDatabaseProvider } from './interface'
+import { SqliteProvider } from './sqlite'
+import { MongoProvider } from './mongo'
+
+export async function createDatabase(dataDir: string, mongoUri?: string): Promise<{ provider: IDatabaseProvider; active: 'sqlite' | 'mongodb' }> {
+  if (mongoUri) {
+    try {
+      const mongo = new MongoProvider(mongoUri)
+      await mongo.connect()
+      return { provider: mongo, active: 'mongodb' }
+    } catch (e) {
+      console.warn('WARN:', (e as Error).message + '\nFalling back to SQLite.')
+    }
+  }
+
+  const sqlite = new SqliteProvider(dataDir)
+  await sqlite.connect()
+  return { provider: sqlite, active: 'sqlite' }
+}

package/packages/server/src/db/interface.ts

@@ -0,0 +1,33 @@
+export interface IDatabaseProvider {
+  connect(): Promise<void>
+  disconnect(): Promise<void>
+  
+  // Project CRUD
+  createProject(name: string): Promise<{ id: string }>
+  getProject(name: string): Promise<{ id: string; name: string; createdAt: number } | null>
+  listProjects(): Promise<Array<{ id: string; name: string; createdAt: number }>>
+  deleteProject(id: string): Promise<void>
+  
+  // Env CRUD
+  createEnv(projectId: string, key: string, encryptedValue: string, apiModeOnly: boolean): Promise<{ id: string }>
+  getEnv(projectId: string, key: string): Promise<{ encryptedValue: string; apiModeOnly: boolean } | null>
+  listEnvs(projectId: string): Promise<Array<{ id: string; key: string; apiModeOnly: boolean; createdAt: number }>>
+  updateEnv(projectId: string, key: string, encryptedValue: string, apiModeOnly: boolean): Promise<void>
+  deleteEnv(projectId: string, key: string): Promise<void>
+  
+  // API Key CRUD
+  createApiKey(projectId: string, encryptedValue: string, plainValue: string, ttl?: number): Promise<{ id: string }>
+  getApiKey(projectId: string, plainValue: string): Promise<{ id: string; expiresAt?: number } | null>
+  listApiKeys(projectId: string): Promise<Array<{ id: string; maskedPreview: string; ttl?: number; expiresAt?: number; createdAt: number }>>
+  revokeApiKey(projectId: string, id: string): Promise<void>
+  
+  // Whitelist CRUD
+  createWhitelistEntry(projectId: string, fingerprint: string, status: 'pending' | 'approved' | 'rejected'): Promise<{ id: string }>
+  getWhitelistEntry(projectId: string, fingerprint: string): Promise<{ id: string; status: 'pending' | 'approved' | 'rejected' } | null>
+  listWhitelistEntries(projectId: string): Promise<Array<{ id: string; fingerprint: string; status: 'pending' | 'approved' | 'rejected'; createdAt: number }>>
+  updateWhitelistStatus(id: string, status: 'approved' | 'rejected'): Promise<void>
+  
+  // PK verification (stores hash only)
+  storePkHash(hash: string): Promise<void>
+  getPkHash(): Promise<string | null>
+}