@kb-labs/shared 1.1.0

package/packages/shared-perm-presets/src/combine.ts

@@ -0,0 +1,278 @@
+import type { PermissionSpec, PermissionPreset, PresetBuilder, RuntimePermissionSpec, PlatformPermissions } from './types';
+
+/**
+ * Merge two string arrays, removing duplicates
+ */
+function mergeArrays(a?: string[], b?: string[]): string[] | undefined {
+  if (!a && !b) {return undefined;}
+  const set = new Set([...(a ?? []), ...(b ?? [])]);
+  return set.size > 0 ? [...set] : undefined;
+}
+
+/**
+ * Merge platform permissions
+ */
+function mergePlatformPermissions(
+  base?: PermissionSpec['platform'],
+  next?: PermissionSpec['platform']
+): PermissionSpec['platform'] | undefined {
+  if (!base && !next) {return undefined;}
+  if (!base) {return next;}
+  if (!next) {return base;}
+
+  const result: PermissionSpec['platform'] = {};
+
+  // Merge each platform service (second value wins for booleans, arrays are merged)
+  const keys = new Set([...Object.keys(base), ...Object.keys(next)]) as Set<keyof typeof base>;
+
+  for (const key of keys) {
+    const baseVal = base[key];
+    const nextVal = next[key];
+
+    if (nextVal === undefined) {
+      result[key] = baseVal as any;
+    } else if (Array.isArray(nextVal)) {
+      // Merge arrays (for cache namespaces, storage paths)
+      result[key] = mergeArrays(
+        Array.isArray(baseVal) ? baseVal : undefined,
+        nextVal
+      ) as any;
+    } else if (typeof nextVal === 'object' && nextVal !== null) {
+      // Merge objects (for llm.models, vectorStore.collections, etc.)
+      result[key] = { ...(typeof baseVal === 'object' ? baseVal : {}), ...nextVal } as any;
+    } else {
+      // Boolean or primitive - second value wins
+      result[key] = nextVal as any;
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+/**
+ * Merge two permission specs together
+ * Arrays are merged (union), scalars use the second value
+ */
+function mergeSpecs(base: PermissionSpec, next: PermissionSpec): PermissionSpec {
+  const result: PermissionSpec = {};
+
+  // Merge fs
+  if (base.fs || next.fs) {
+    result.fs = {
+      // readWrite wins over read
+      mode: next.fs?.mode ?? base.fs?.mode,
+      allow: mergeArrays(base.fs?.allow, next.fs?.allow),
+    };
+    // Clean up undefined fields
+    if (result.fs.mode === undefined) {delete result.fs.mode;}
+    if (result.fs.allow === undefined) {delete result.fs.allow;}
+    if (Object.keys(result.fs).length === 0) {delete result.fs;}
+  }
+
+  // Merge env
+  if (base.env || next.env) {
+    result.env = {
+      read: mergeArrays(base.env?.read, next.env?.read),
+    };
+    if (result.env.read === undefined) {delete result.env.read;}
+    if (Object.keys(result.env).length === 0) {delete result.env;}
+  }
+
+  // Merge network
+  if (base.network || next.network) {
+    result.network = {
+      fetch: mergeArrays(base.network?.fetch, next.network?.fetch),
+    };
+    if (result.network.fetch === undefined) {delete result.network.fetch;}
+    if (Object.keys(result.network).length === 0) {delete result.network;}
+  }
+
+  // Merge shell
+  if (base.shell || next.shell) {
+    result.shell = {
+      allow: mergeArrays(base.shell?.allow, next.shell?.allow),
+    };
+    if (result.shell.allow === undefined) {delete result.shell.allow;}
+    if (Object.keys(result.shell).length === 0) {delete result.shell;}
+  }
+
+  // Merge platform
+  result.platform = mergePlatformPermissions(base.platform, next.platform);
+
+  // Merge quotas (second value wins)
+  if (base.quotas || next.quotas) {
+    result.quotas = {
+      timeoutMs: next.quotas?.timeoutMs ?? base.quotas?.timeoutMs,
+      memoryMb: next.quotas?.memoryMb ?? base.quotas?.memoryMb,
+      cpuMs: next.quotas?.cpuMs ?? base.quotas?.cpuMs,
+    };
+    if (result.quotas.timeoutMs === undefined) {delete result.quotas.timeoutMs;}
+    if (result.quotas.memoryMb === undefined) {delete result.quotas.memoryMb;}
+    if (result.quotas.cpuMs === undefined) {delete result.quotas.cpuMs;}
+    if (Object.keys(result.quotas).length === 0) {delete result.quotas;}
+  }
+
+  return result;
+}
+
+/**
+ * Convert declarative PermissionSpec to explicit RuntimePermissionSpec
+ *
+ * Transforms:
+ *   { mode: 'readWrite', allow: ['*.json'] }
+ * Into:
+ *   { read: ['*.json'], write: ['*.json'] }
+ */
+function toRuntimeFormat(spec: PermissionSpec): RuntimePermissionSpec {
+  const result: RuntimePermissionSpec = {};
+
+  // Convert fs: mode + allow → read[] + write[]
+  if (spec.fs) {
+    const { mode, allow } = spec.fs;
+    result.fs = {};
+
+    if (allow && allow.length > 0) {
+      // read is always granted for allowed paths
+      result.fs.read = [...allow];
+
+      // write only if mode is 'readWrite'
+      if (mode === 'readWrite') {
+        result.fs.write = [...allow];
+      }
+    }
+
+    if (Object.keys(result.fs).length === 0) {delete result.fs;}
+  }
+
+  // env, network, shell, platform, quotas pass through unchanged
+  if (spec.env) {
+    result.env = { ...spec.env };
+  }
+
+  if (spec.network) {
+    result.network = { ...spec.network };
+  }
+
+  if (spec.shell) {
+    result.shell = { ...spec.shell };
+  }
+
+  if (spec.platform) {
+    result.platform = { ...spec.platform };
+  }
+
+  if (spec.quotas) {
+    result.quotas = { ...spec.quotas };
+  }
+
+  return result;
+}
+
+/**
+ * Create a builder for combining permission presets
+ *
+ * @example
+ * ```typescript
+ * const permissions = combine()
+ *   .with(presets.gitWorkflow)
+ *   .with(presets.npmPublish)
+ *   .withEnv(['MY_CUSTOM_VAR'])
+ *   .build();
+ * ```
+ */
+export function combine(): PresetBuilder {
+  let accumulated: PermissionSpec = {};
+
+  const builder: PresetBuilder = {
+    with(preset: PermissionPreset | PermissionSpec): PresetBuilder {
+      const spec = 'permissions' in preset ? preset.permissions : preset;
+      accumulated = mergeSpecs(accumulated, spec);
+      return builder;
+    },
+
+    withEnv(vars: string[]): PresetBuilder {
+      accumulated = mergeSpecs(accumulated, { env: { read: vars } });
+      return builder;
+    },
+
+    withFs(fs: PermissionSpec['fs']): PresetBuilder {
+      if (fs) {
+        accumulated = mergeSpecs(accumulated, { fs });
+      }
+      return builder;
+    },
+
+    withNetwork(network: PermissionSpec['network']): PresetBuilder {
+      if (network) {
+        accumulated = mergeSpecs(accumulated, { network });
+      }
+      return builder;
+    },
+
+    withShell(shell: PermissionSpec['shell']): PresetBuilder {
+      if (shell) {
+        accumulated = mergeSpecs(accumulated, { shell });
+      }
+      return builder;
+    },
+
+    withPlatform(platform: PermissionSpec['platform']): PresetBuilder {
+      if (platform) {
+        accumulated = mergeSpecs(accumulated, { platform });
+      }
+      return builder;
+    },
+
+    withQuotas(quotas: PermissionSpec['quotas']): PresetBuilder {
+      if (quotas) {
+        accumulated = mergeSpecs(accumulated, { quotas });
+      }
+      return builder;
+    },
+
+    withStorage(storage: PlatformPermissions['storage']): PresetBuilder {
+      if (storage !== undefined) {
+        accumulated = mergeSpecs(accumulated, {
+          platform: { storage },
+        });
+      }
+      return builder;
+    },
+
+    withDatabase(database: PlatformPermissions['database']): PresetBuilder {
+      if (database !== undefined) {
+        accumulated = mergeSpecs(accumulated, {
+          platform: { database },
+        });
+      }
+      return builder;
+    },
+
+    build(): RuntimePermissionSpec {
+      return toRuntimeFormat(accumulated);
+    },
+  };
+
+  return builder;
+}
+
+/**
+ * Quickly combine multiple presets into a single permission spec
+ *
+ * @example
+ * ```typescript
+ * const permissions = combinePresets(presets.gitWorkflow, presets.npmPublish);
+ * ```
+ */
+export function combinePresets(...presets: (PermissionPreset | PermissionSpec)[]): RuntimePermissionSpec {
+  let builder = combine();
+  for (const preset of presets) {
+    builder = builder.with(preset);
+  }
+  return builder.build();
+}
+
+/**
+ * Export toRuntimeFormat for advanced use cases
+ */
+export { toRuntimeFormat };

package/packages/shared-perm-presets/src/index.ts

@@ -0,0 +1,18 @@
+// Types
+export type { PermissionSpec, PermissionPreset, PresetBuilder, RuntimePermissionSpec } from './types';
+
+// Presets
+export { minimal } from './presets/minimal';
+export { gitWorkflow } from './presets/git-workflow';
+export { npmPublish } from './presets/npm-publish';
+export { fullEnv } from './presets/full-env';
+export { kbPlatform } from './presets/kb-platform';
+export { llmAccess } from './presets/llm-access';
+export { vectorStore } from './presets/vector-store';
+export { ciEnvironment } from './presets/ci-environment';
+
+// Re-export all presets as a namespace
+export * as presets from './presets/index.js';
+
+// Builder
+export { combine, combinePresets, toRuntimeFormat } from './combine';

package/packages/shared-perm-presets/src/presets/ci-environment.ts

@@ -0,0 +1,34 @@
+import type { PermissionPreset } from '../types';
+
+/**
+ * CI Environment preset - for plugins running in CI/CD
+ * Includes GitHub Actions, GitLab CI, and common CI variables
+ */
+export const ciEnvironment: PermissionPreset = {
+  id: 'ci-environment',
+  description: 'CI/CD environment - GitHub Actions, GitLab CI tokens and vars',
+  permissions: {
+    env: {
+      read: [
+        // Common CI
+        'CI',
+        'CI_*',
+        'CONTINUOUS_INTEGRATION',
+        // GitHub Actions
+        'GITHUB_TOKEN',
+        'GITHUB_*',
+        'GH_TOKEN',
+        // GitLab CI
+        'GITLAB_*',
+        'CI_JOB_TOKEN',
+        // Jenkins
+        'JENKINS_*',
+        'BUILD_*',
+        // Generic
+        'BRANCH_NAME',
+        'TAG_NAME',
+        'COMMIT_SHA',
+      ],
+    },
+  },
+};

package/packages/shared-perm-presets/src/presets/full-env.ts

@@ -0,0 +1,16 @@
+import type { PermissionPreset } from '../types';
+
+/**
+ * Full environment preset - access to all environment variables
+ * Use for trusted plugins that need full system access
+ * WARNING: This bypasses env filtering entirely
+ */
+export const fullEnv: PermissionPreset = {
+  id: 'full-env',
+  description: 'Full environment access - all env vars available (trusted plugins only)',
+  permissions: {
+    env: {
+      read: ['*'], // Wildcard - all env vars
+    },
+  },
+};

package/packages/shared-perm-presets/src/presets/git-workflow.ts

@@ -0,0 +1,40 @@
+import type { PermissionPreset } from '../types';
+
+/**
+ * Git workflow preset - for plugins that use git (simple-git, etc.)
+ * Includes HOME for ~/.gitconfig, USER for author info
+ */
+export const gitWorkflow: PermissionPreset = {
+  id: 'git-workflow',
+  description: 'Git operations - includes HOME, USER, and git config access',
+  permissions: {
+    env: {
+      read: [
+        // System (required for git to find config)
+        'HOME',
+        'USER',
+        'PATH',
+        'SHELL',
+        'TERM',
+        'LANG',
+        'LC_ALL',
+        'TZ',
+        'TMPDIR',
+        // Git-specific
+        'GIT_*',           // All git env vars (GIT_AUTHOR_NAME, GIT_DIR, etc.)
+        'SSH_AUTH_SOCK',   // For SSH key auth
+        'SSH_AGENT_PID',
+        // Node
+        'NODE_ENV',
+      ],
+    },
+    fs: {
+      mode: 'readWrite',
+      allow: [
+        '**/.git/**',      // Git directory
+        '**/.gitignore',
+        '**/.gitattributes',
+      ],
+    },
+  },
+};

package/packages/shared-perm-presets/src/presets/index.ts

@@ -0,0 +1,8 @@
+export { minimal } from './minimal';
+export { gitWorkflow } from './git-workflow';
+export { npmPublish } from './npm-publish';
+export { fullEnv } from './full-env';
+export { kbPlatform } from './kb-platform';
+export { llmAccess } from './llm-access';
+export { vectorStore } from './vector-store';
+export { ciEnvironment } from './ci-environment';

package/packages/shared-perm-presets/src/presets/kb-platform.ts

@@ -0,0 +1,30 @@
+import type { PermissionPreset } from '../types';
+
+/**
+ * KB Platform preset - for KB Labs internal plugins
+ * Includes KB_* env vars and .kb/ directory access
+ */
+export const kbPlatform: PermissionPreset = {
+  id: 'kb-platform',
+  description: 'KB Labs platform access - KB_* env vars and .kb/ directory',
+  permissions: {
+    env: {
+      read: [
+        // System basics
+        'HOME',
+        'USER',
+        'PATH',
+        'TMPDIR',
+        'NODE_ENV',
+        // KB Labs specific
+        'KB_*',            // All KB env vars
+      ],
+    },
+    fs: {
+      mode: 'readWrite',
+      allow: [
+        '.kb/**',          // KB Labs config directory
+      ],
+    },
+  },
+};

package/packages/shared-perm-presets/src/presets/llm-access.ts

@@ -0,0 +1,29 @@
+import type { PermissionPreset } from '../types';
+
+/**
+ * LLM Access preset - for plugins that use LLM APIs
+ * Includes OpenAI and Anthropic API keys and network access
+ */
+export const llmAccess: PermissionPreset = {
+  id: 'llm-access',
+  description: 'LLM API access - OpenAI, Anthropic keys and network',
+  permissions: {
+    env: {
+      read: [
+        'OPENAI_API_KEY',
+        'OPENAI_ORG_ID',
+        'OPENAI_BASE_URL',
+        'ANTHROPIC_API_KEY',
+        'AZURE_OPENAI_*',     // Azure OpenAI
+        'LLM_*',              // Generic LLM config
+      ],
+    },
+    network: {
+      fetch: [
+        'api.openai.com',
+        'api.anthropic.com',
+        '*.openai.azure.com', // Azure OpenAI
+      ],
+    },
+  },
+};

package/packages/shared-perm-presets/src/presets/minimal.ts

@@ -0,0 +1,21 @@
+import type { PermissionPreset } from '../types';
+
+/**
+ * Minimal preset - only basic Node.js environment
+ * Use when plugin doesn't need any external access
+ */
+export const minimal: PermissionPreset = {
+  id: 'minimal',
+  description: 'Minimal permissions - basic Node.js environment only',
+  permissions: {
+    env: {
+      read: [
+        'NODE_ENV',
+        'PATH',
+        'LANG',
+        'LC_ALL',
+        'TZ',
+      ],
+    },
+  },
+};

package/packages/shared-perm-presets/src/presets/npm-publish.ts

@@ -0,0 +1,48 @@
+import type { PermissionPreset } from '../types';
+
+/**
+ * NPM publish preset - for plugins that publish to npm
+ * Includes HOME for ~/.npmrc, npm auth tokens
+ */
+export const npmPublish: PermissionPreset = {
+  id: 'npm-publish',
+  description: 'NPM operations - includes HOME, npm tokens, and registry access',
+  permissions: {
+    env: {
+      read: [
+        // System (required for npm to find config)
+        'HOME',
+        'USER',
+        'PATH',
+        'TMPDIR',
+        'LANG',
+        'LC_ALL',
+        'TZ',
+        // NPM-specific
+        'NPM_TOKEN',
+        'NPM_AUTH_TOKEN',
+        'NODE_AUTH_TOKEN',
+        'npm_*',           // All npm env vars
+        // Node
+        'NODE_ENV',
+        'NODE_OPTIONS',
+      ],
+    },
+    fs: {
+      mode: 'readWrite',
+      allow: [
+        '**/package.json',
+        '**/package-lock.json',
+        '**/pnpm-lock.yaml',
+        '**/.npmrc',
+        '**/.npmignore',
+      ],
+    },
+    network: {
+      fetch: [
+        'registry.npmjs.org',
+        'npm.pkg.github.com',
+      ],
+    },
+  },
+};

package/packages/shared-perm-presets/src/presets/vector-store.ts

@@ -0,0 +1,40 @@
+import type { PermissionPreset } from '../types';
+
+/**
+ * Vector Store preset - for plugins that use vector databases
+ * Includes Qdrant, Pinecone, Weaviate access
+ */
+export const vectorStore: PermissionPreset = {
+  id: 'vector-store',
+  description: 'Vector database access - Qdrant, Pinecone, Weaviate',
+  permissions: {
+    env: {
+      read: [
+        // Qdrant
+        'QDRANT_URL',
+        'QDRANT_API_KEY',
+        'QDRANT_*',
+        // Pinecone
+        'PINECONE_API_KEY',
+        'PINECONE_ENVIRONMENT',
+        'PINECONE_*',
+        // Weaviate
+        'WEAVIATE_URL',
+        'WEAVIATE_API_KEY',
+        'WEAVIATE_*',
+        // Generic
+        'VECTOR_STORE_*',
+        'EMBEDDING_*',
+      ],
+    },
+    network: {
+      fetch: [
+        'localhost',
+        '127.0.0.1',
+        '*.qdrant.io',
+        '*.pinecone.io',
+        '*.weaviate.io',
+      ],
+    },
+  },
+};