@captainsafia/burrow 1.2.0 → 1.3.0-preview.4437197

package/dist/api.d.ts

@@ -1,11 +1,46 @@
 // Generated by dts-bundle-generator v9.5.1
 
+export interface TrustedPath {
+	path: string;
+	inode: string;
+	trustedAt: string;
+}
 export interface ResolvedSecret {
 	key: string;
 	value: string;
 	sourcePath: string;
 }
 export type ExportFormat = "shell" | "bash" | "fish" | "powershell" | "cmd" | "dotenv" | "json";
+export interface TrustCheckResult {
+	trusted: boolean;
+	trustedPath?: string;
+	reason?: "not-trusted" | "inode-mismatch" | "path-not-found";
+}
+export interface LoadedSecret {
+	key: string;
+	value: string;
+	sourcePath: string;
+}
+export interface HookState {
+	/** Currently loaded secret keys and their values */
+	secrets: LoadedSecret[];
+	/** The last directory that triggered loading */
+	lastDir: string;
+	/** Timestamp when secrets were loaded */
+	loadedAt: string;
+	/** Keys that were skipped due to conflicts */
+	skippedKeys: string[];
+}
+export interface HookDiff {
+	/** Keys to unset from the environment */
+	unset: string[];
+	/** Secrets to set in the environment */
+	set: LoadedSecret[];
+	/** Keys that already exist in the environment and were skipped */
+	skipped: string[];
+	/** Keys that remain unchanged */
+	unchanged: string[];
+}
 /**
  * Configuration options for creating a BurrowClient instance.
  */
@@ -82,6 +117,88 @@ export interface RemoveOptions {
 	 */
 	path?: string;
 }
+/**
+ * Options for the `trust` method.
+ */
+export interface TrustOptions {
+	/**
+	 * Directory path to trust.
+	 * Defaults to the current working directory.
+	 */
+	path?: string;
+}
+/**
+ * Options for the `untrust` method.
+ */
+export interface UntrustOptions {
+	/**
+	 * Directory path to untrust.
+	 * Defaults to the current working directory.
+	 */
+	path?: string;
+}
+/**
+ * Options for the `isTrusted` method.
+ */
+export interface IsTrustedOptions {
+	/**
+	 * Directory path to check for trust.
+	 * Defaults to the current working directory.
+	 */
+	path?: string;
+}
+/**
+ * Result of the `trust` method.
+ */
+export interface TrustResult {
+	/**
+	 * The canonicalized path that was trusted.
+	 */
+	path: string;
+	/**
+	 * The filesystem inode/file ID for the trusted path.
+	 */
+	inode: string;
+}
+/**
+ * Options for the `hook` method.
+ */
+export interface HookOptions {
+	/**
+	 * The shell to generate hook commands for.
+	 */
+	shell: "bash" | "zsh" | "fish";
+	/**
+	 * Whether to use colored output.
+	 * Defaults to respecting NO_COLOR environment variable.
+	 */
+	useColor?: boolean;
+}
+/**
+ * Result of the `hook` method.
+ */
+export interface HookResult {
+	/**
+	 * Shell commands to execute for environment updates.
+	 */
+	commands: string[];
+	/**
+	 * Optional message to display to the user.
+	 */
+	message?: string;
+	/**
+	 * The diff that was computed.
+	 */
+	diff: HookDiff;
+	/**
+	 * Whether the directory is trusted.
+	 */
+	trusted: boolean;
+	/**
+	 * Reason if directory is not trusted.
+	 */
+	notTrustedReason?: "not-trusted" | "inode-mismatch" | "path-not-found" | "autoload-disabled";
+}
 /**
  * Options for the `export` method.
  */
@@ -135,6 +252,8 @@ export declare class BurrowClient {
 	private readonly storage;
 	private readonly resolver;
 	private readonly pathOptions;
+	private readonly trustManager;
+	private readonly hookStateManager;
 	/**
 	 * Creates a new BurrowClient instance.
 	 *
@@ -307,6 +426,124 @@ export declare class BurrowClient {
 	 * ```
 	 */
 	resolve(cwd?: string): Promise<Map<string, ResolvedSecret>>;
+	/**
+	 * Trusts a directory for auto-loading secrets.
+	 *
+	 * When a directory is trusted, navigating into it (or its subdirectories)
+	 * will automatically load secrets into the shell environment via the hook.
+	 *
+	 * @param options - Trust options including target path
+	 * @returns The trusted path info with canonicalized path and inode
+	 *
+	 * @example
+	 * ```typescript
+	 * // Trust current directory
+	 * await client.trust();
+	 *
+	 * // Trust specific path
+	 * const result = await client.trust({ path: '/projects/myapp' });
+	 * console.log(`Trusted: ${result.path}`);
+	 * ```
+	 */
+	trust(options?: TrustOptions): Promise<TrustResult>;
+	/**
+	 * Removes trust from a directory.
+	 *
+	 * After untrusting, the directory (and its subdirectories) will no longer
+	 * auto-load secrets. Secrets currently loaded remain until the next directory change.
+	 *
+	 * @param options - Untrust options including target path
+	 * @returns true if the path was trusted and is now untrusted, false if it wasn't trusted
+	 *
+	 * @example
+	 * ```typescript
+	 * const removed = await client.untrust({ path: '/projects/myapp' });
+	 * if (removed) {
+	 *   console.log('Directory is no longer trusted');
+	 * }
+	 * ```
+	 */
+	untrust(options?: UntrustOptions): Promise<boolean>;
+	/**
+	 * Checks if a directory is trusted for auto-loading.
+	 *
+	 * Trust can be inherited from ancestor directories. Also validates that
+	 * the inode matches to detect directory replacements.
+	 *
+	 * @param options - Options including path to check
+	 * @returns Trust check result with status and reason if not trusted
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await client.isTrusted({ path: '/projects/myapp/src' });
+	 * if (result.trusted) {
+	 *   console.log(`Trusted via: ${result.trustedPath}`);
+	 * } else {
+	 *   console.log(`Not trusted: ${result.reason}`);
+	 * }
+	 * ```
+	 */
+	isTrusted(options?: IsTrustedOptions): Promise<TrustCheckResult>;
+	/**
+	 * Lists all trusted directories.
+	 *
+	 * @returns Array of all trusted path entries
+	 *
+	 * @example
+	 * ```typescript
+	 * const trusted = await client.listTrusted();
+	 * for (const entry of trusted) {
+	 *   console.log(`${entry.path} (trusted at ${entry.trustedAt})`);
+	 * }
+	 * ```
+	 */
+	listTrusted(): Promise<TrustedPath[]>;
+	/**
+	 * Gets the current hook state (loaded secrets).
+	 *
+	 * @returns The current hook state or undefined if no secrets are loaded
+	 *
+	 * @example
+	 * ```typescript
+	 * const state = await client.getHookState();
+	 * if (state) {
+	 *   console.log(`${state.secrets.length} secrets loaded from ${state.lastDir}`);
+	 * }
+	 * ```
+	 */
+	getHookState(): Promise<HookState | undefined>;
+	/**
+	 * Clears the hook state (unloads all secrets tracking).
+	 *
+	 * Note: This only clears the state file. The actual environment variables
+	 * remain set until the shell exits or they are explicitly unset.
+	 */
+	clearHookState(): Promise<void>;
+	/**
+	 * Processes a directory change for the shell hook.
+	 *
+	 * This is the main method called by shell hooks on directory change.
+	 * It checks trust, resolves secrets, computes the diff, and returns
+	 * the commands needed to update the environment.
+	 *
+	 * @param cwd - The new working directory
+	 * @param options - Hook options including shell type
+	 * @returns Hook result with commands to execute and optional message
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await client.hook('/projects/myapp', { shell: 'bash' });
+	 * if (result.trusted) {
+	 *   for (const cmd of result.commands) {
+	 *     console.log(cmd); // Execute in shell
+	 *   }
+	 *   if (result.message) {
+	 *     console.error(result.message);
+	 *   }
+	 * }
+	 * ```
+	 */
+	hook(cwd: string, options: HookOptions): Promise<HookResult>;
 	/**
 	 * Closes the database connection and releases resources.
 	 * After calling this method, the client instance should not be used.

package/dist/api.js

@@ -80,6 +80,14 @@ class Storage {
       )
     `);
     this.db.run("CREATE INDEX IF NOT EXISTS idx_secrets_path ON secrets (path)");
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS trusted_paths (
+        path TEXT PRIMARY KEY,
+        inode TEXT NOT NULL,
+        trusted_at TEXT NOT NULL
+      )
+    `);
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_trusted_paths_inode ON trusted_paths (inode)");
     const versionResult = this.db.query("PRAGMA user_version").get();
     const currentVersion = versionResult?.user_version ?? 0;
     if (currentVersion === 0) {
@@ -139,6 +147,61 @@ class Storage {
     db.query("DELETE FROM secrets WHERE path = ? AND key = ?").run(canonicalPath, key);
     return true;
   }
+  async addTrustedPath(canonicalPath, inode) {
+    const db = await this.ensureDb();
+    const trustedAt = new Date().toISOString();
+    db.query(`
+      INSERT INTO trusted_paths (path, inode, trusted_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(path) DO UPDATE SET
+        inode = excluded.inode,
+        trusted_at = excluded.trusted_at
+    `).run(canonicalPath, inode, trustedAt);
+  }
+  async removeTrustedPath(canonicalPath) {
+    const db = await this.ensureDb();
+    const existing = db.query("SELECT path FROM trusted_paths WHERE path = ?").get(canonicalPath);
+    if (!existing) {
+      return false;
+    }
+    db.query("DELETE FROM trusted_paths WHERE path = ?").run(canonicalPath);
+    return true;
+  }
+  async getTrustedPath(canonicalPath) {
+    const db = await this.ensureDb();
+    const row = db.query("SELECT path, inode, trusted_at FROM trusted_paths WHERE path = ?").get(canonicalPath);
+    if (!row) {
+      return;
+    }
+    return {
+      path: row.path,
+      inode: row.inode,
+      trustedAt: row.trusted_at
+    };
+  }
+  async getAllTrustedPaths() {
+    const db = await this.ensureDb();
+    const rows = db.query("SELECT path, inode, trusted_at FROM trusted_paths ORDER BY path").all();
+    return rows.map((row) => ({
+      path: row.path,
+      inode: row.inode,
+      trustedAt: row.trusted_at
+    }));
+  }
+  async getTrustedAncestorPaths(canonicalPath) {
+    const db = await this.ensureDb();
+    let rows;
+    if (isWindows()) {
+      rows = db.query("SELECT path, inode, trusted_at FROM trusted_paths WHERE ? = path OR ? LIKE path || '\\' || '%' OR (length(path) = 3 AND path LIKE '_:\\' AND ? LIKE path || '%')").all(canonicalPath, canonicalPath, canonicalPath);
+    } else {
+      rows = db.query("SELECT path, inode, trusted_at FROM trusted_paths WHERE ? = path OR ? LIKE path || '/' || '%' OR path = '/'").all(canonicalPath, canonicalPath);
+    }
+    return rows.map((row) => ({
+      path: row.path,
+      inode: row.inode,
+      trustedAt: row.trusted_at
+    }));
+  }
   close() {
     if (this.db) {
       this.db.close();
@@ -355,11 +418,213 @@ function format(secrets, fmt, options = {}) {
       throw new Error(`Unknown format: ${fmt}`);
   }
 }
+// src/core/trust.ts
+import { stat } from "node:fs/promises";
+async function getInode(path) {
+  const stats = await stat(path);
+  return stats.ino.toString();
+}
+
+class TrustManager {
+  storage;
+  pathOptions;
+  constructor(options) {
+    this.storage = options.storage;
+    this.pathOptions = {
+      followSymlinks: options.followSymlinks
+    };
+  }
+  async trust(targetPath) {
+    const canonicalPath = await canonicalize(targetPath, this.pathOptions);
+    const inode = await getInode(canonicalPath);
+    await this.storage.addTrustedPath(canonicalPath, inode);
+    return { path: canonicalPath, inode };
+  }
+  async untrust(targetPath) {
+    const canonicalPath = await canonicalize(targetPath, this.pathOptions);
+    return this.storage.removeTrustedPath(canonicalPath);
+  }
+  async isTrusted(targetPath) {
+    let canonicalPath;
+    try {
+      canonicalPath = await canonicalize(targetPath, this.pathOptions);
+    } catch {
+      return { trusted: false, reason: "path-not-found" };
+    }
+    const trustedAncestors = await this.storage.getTrustedAncestorPaths(canonicalPath);
+    if (trustedAncestors.length === 0) {
+      return { trusted: false, reason: "not-trusted" };
+    }
+    trustedAncestors.sort((a, b) => b.path.length - a.path.length);
+    for (const trusted of trustedAncestors) {
+      try {
+        const currentInode = await getInode(trusted.path);
+        if (currentInode === trusted.inode) {
+          return { trusted: true, trustedPath: trusted.path };
+        }
+      } catch {}
+    }
+    return { trusted: false, reason: "inode-mismatch" };
+  }
+  async list() {
+    return this.storage.getAllTrustedPaths();
+  }
+}
+// src/core/hook.ts
+import { readFile, writeFile, rm, mkdir as mkdir2 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+var HOOK_STATE_FILE = "hook-state.json";
+
+class HookStateManager {
+  configDir;
+  stateFilePath;
+  constructor(options = {}) {
+    this.configDir = options.configDir ?? getConfigDir();
+    this.stateFilePath = join3(this.configDir, HOOK_STATE_FILE);
+  }
+  async load() {
+    try {
+      const content = await readFile(this.stateFilePath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return;
+    }
+  }
+  async save(state) {
+    await mkdir2(this.configDir, { recursive: true });
+    await writeFile(this.stateFilePath, JSON.stringify(state, null, 2));
+  }
+  async clear() {
+    try {
+      await rm(this.stateFilePath, { force: true });
+    } catch {}
+  }
+  computeDiff(currentState, newSecrets, env = process.env) {
+    const currentKeys = new Map;
+    if (currentState) {
+      for (const secret of currentState.secrets) {
+        currentKeys.set(secret.key, secret);
+      }
+    }
+    const skippedFromState = new Set(currentState?.skippedKeys ?? []);
+    const unset = [];
+    const set = [];
+    const skipped = [];
+    const unchanged = [];
+    for (const [key] of currentKeys) {
+      if (!newSecrets.has(key)) {
+        unset.push(key);
+      }
+    }
+    for (const [key, secret] of newSecrets) {
+      const loadedSecret = {
+        key: secret.key,
+        value: secret.value,
+        sourcePath: secret.sourcePath
+      };
+      const current = currentKeys.get(key);
+      if (current) {
+        if (current.value === secret.value && current.sourcePath === secret.sourcePath) {
+          unchanged.push(key);
+        } else {
+          set.push(loadedSecret);
+        }
+      } else {
+        const envValue = env[key];
+        if (envValue !== undefined && !skippedFromState.has(key)) {
+          skipped.push(key);
+        } else {
+          set.push(loadedSecret);
+        }
+      }
+    }
+    return { unset, set, skipped, unchanged };
+  }
+  async applyDiff(currentState, diff, newDir) {
+    const secretsMap = new Map;
+    if (currentState) {
+      for (const secret of currentState.secrets) {
+        if (!diff.unset.includes(secret.key)) {
+          secretsMap.set(secret.key, secret);
+        }
+      }
+    }
+    for (const secret of diff.set) {
+      secretsMap.set(secret.key, secret);
+    }
+    const skippedKeys = [...currentState?.skippedKeys ?? []];
+    for (const key of diff.skipped) {
+      if (!skippedKeys.includes(key)) {
+        skippedKeys.push(key);
+      }
+    }
+    const newState = {
+      secrets: Array.from(secretsMap.values()),
+      lastDir: newDir,
+      loadedAt: new Date().toISOString(),
+      skippedKeys
+    };
+    await this.save(newState);
+    return newState;
+  }
+}
+function formatHookMessage(diff, useColor = true) {
+  const loaded = diff.set.length;
+  const unloaded = diff.unset.length;
+  const skippedCount = diff.skipped.length;
+  if (loaded === 0 && unloaded === 0) {
+    return;
+  }
+  const dim = useColor ? "\x1B[2m" : "";
+  const reset = useColor ? "\x1B[0m" : "";
+  let message = `${dim}burrow: `;
+  if (unloaded > 0 && loaded > 0) {
+    message += `unloaded ${unloaded}, loaded ${loaded}`;
+  } else if (loaded > 0) {
+    message += `loaded ${loaded} secret${loaded === 1 ? "" : "s"}`;
+  } else {
+    message += `unloaded ${unloaded} secret${unloaded === 1 ? "" : "s"}`;
+  }
+  if (skippedCount > 0) {
+    message += ` (${skippedCount} skipped)`;
+  }
+  message += reset;
+  return message;
+}
+function generateShellCommands(diff, shell) {
+  const commands = [];
+  for (const key of diff.unset) {
+    if (shell === "fish") {
+      commands.push(`set -e ${key}`);
+    } else {
+      commands.push(`unset ${key}`);
+    }
+  }
+  for (const secret of diff.set) {
+    const escapedValue = escapeShellValue2(secret.value, shell);
+    if (shell === "fish") {
+      commands.push(`set -gx ${secret.key} ${escapedValue}`);
+    } else {
+      commands.push(`export ${secret.key}=${escapedValue}`);
+    }
+  }
+  return commands;
+}
+function escapeShellValue2(value, shell) {
+  if (shell === "fish") {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+  } else {
+    const escaped = value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+    return `$'${escaped}'`;
+  }
+}
 // src/api.ts
 class BurrowClient {
   storage;
   resolver;
   pathOptions;
+  trustManager;
+  hookStateManager;
   constructor(options = {}) {
     this.storage = new Storage({
       configDir: options.configDir,
@@ -372,6 +637,13 @@ class BurrowClient {
     this.pathOptions = {
       followSymlinks: options.followSymlinks
     };
+    this.trustManager = new TrustManager({
+      storage: this.storage,
+      followSymlinks: options.followSymlinks
+    });
+    this.hookStateManager = new HookStateManager({
+      configDir: options.configDir
+    });
   }
   async set(key, value, options = {}) {
     assertValidEnvKey(key);
@@ -407,6 +679,61 @@ class BurrowClient {
   async resolve(cwd) {
     return this.resolver.resolve(cwd);
   }
+  async trust(options = {}) {
+    const targetPath = options.path ?? process.cwd();
+    return this.trustManager.trust(targetPath);
+  }
+  async untrust(options = {}) {
+    const targetPath = options.path ?? process.cwd();
+    return this.trustManager.untrust(targetPath);
+  }
+  async isTrusted(options = {}) {
+    const targetPath = options.path ?? process.cwd();
+    return this.trustManager.isTrusted(targetPath);
+  }
+  async listTrusted() {
+    return this.trustManager.list();
+  }
+  async getHookState() {
+    return this.hookStateManager.load();
+  }
+  async clearHookState() {
+    return this.hookStateManager.clear();
+  }
+  async hook(cwd, options) {
+    if (process.env["BURROW_AUTOLOAD"] === "0") {
+      const emptyDiff = { unset: [], set: [], skipped: [], unchanged: [] };
+      return {
+        commands: [],
+        diff: emptyDiff,
+        trusted: false,
+        notTrustedReason: "autoload-disabled"
+      };
+    }
+    const trustResult = await this.isTrusted({ path: cwd });
+    if (!trustResult.trusted) {
+      const emptyDiff = { unset: [], set: [], skipped: [], unchanged: [] };
+      return {
+        commands: [],
+        diff: emptyDiff,
+        trusted: false,
+        notTrustedReason: trustResult.reason
+      };
+    }
+    const newSecrets = await this.resolve(cwd);
+    const currentState = await this.hookStateManager.load();
+    const diff = this.hookStateManager.computeDiff(currentState, newSecrets);
+    const commands = generateShellCommands(diff, options.shell);
+    await this.hookStateManager.applyDiff(currentState, diff, cwd);
+    const useColor = options.useColor ?? !process.env["NO_COLOR"];
+    const message = formatHookMessage(diff, useColor);
+    return {
+      commands,
+      message,
+      diff,
+      trusted: true
+    };
+  }
   close() {
     this.storage.close();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@captainsafia/burrow",
-  "version": "1.2.0",
+  "version": "1.3.0-preview.4437197",
   "description": "Platform-agnostic, directory-scoped secrets manager",
   "type": "module",
   "main": "dist/api.js",