@captainsafia/burrow 1.2.0 → 1.3.0-preview.319e6c8

package/dist/api.d.ts

@@ -1,11 +1,32 @@
 // 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 HookDiff {
+	/** Keys to unset from the environment */
+	toUnset: string[];
+	/** Secrets to set in the environment */
+	toSet: LoadedSecret[];
+}
 /**
  * Configuration options for creating a BurrowClient instance.
  */
@@ -82,6 +103,97 @@ 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;
+	/**
+	 * Keys that were previously loaded by the hook.
+	 * Used to compute which keys need to be unset.
+	 */
+	previousKeys?: string[];
+}
+/**
+ * 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 secrets that were loaded.
+	 */
+	secrets: LoadedSecret[];
+	/**
+	 * The keys that were unloaded.
+	 */
+	unloadedKeys: string[];
+	/**
+	 * 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 +247,7 @@ export declare class BurrowClient {
 	private readonly storage;
 	private readonly resolver;
 	private readonly pathOptions;
+	private readonly trustManager;
 	/**
 	 * Creates a new BurrowClient instance.
 	 *
@@ -307,6 +420,106 @@ 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[]>;
+	/**
+	 * 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 from previous
+	 * state, and returns the commands needed to update the environment.
+	 *
+	 * @param cwd - The new working directory
+	 * @param options - Hook options including shell type and previous keys
+	 * @returns Hook result with commands to execute and optional message
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await client.hook('/projects/myapp', {
+	 *   shell: 'bash',
+	 *   previousKeys: ['OLD_KEY'] // Keys from last hook call
+	 * });
+	 * 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,135 @@ 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
+function resolveToLoadedSecrets(secrets) {
+  const result = [];
+  for (const [, secret] of secrets) {
+    result.push({
+      key: secret.key,
+      value: secret.value,
+      sourcePath: secret.sourcePath
+    });
+  }
+  return result;
+}
+function computeHookDiff(previousKeys, newSecrets) {
+  const newKeys = new Set(newSecrets.map((s) => s.key));
+  const toUnset = [];
+  for (const key of previousKeys) {
+    if (!newKeys.has(key)) {
+      toUnset.push(key);
+    }
+  }
+  return {
+    toUnset,
+    toSet: newSecrets
+  };
+}
+function formatHookMessage(diff, useColor = true) {
+  const loaded = diff.toSet.length;
+  const unloaded = diff.toUnset.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"}`;
+  }
+  message += reset;
+  return message;
+}
+function generateShellCommands(diff, shell) {
+  const commands = [];
+  for (const key of diff.toUnset) {
+    if (shell === "fish") {
+      commands.push(`set -e ${key}`);
+    } else {
+      commands.push(`unset ${key}`);
+    }
+  }
+  for (const secret of diff.toSet) {
+    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;
   constructor(options = {}) {
     this.storage = new Storage({
       configDir: options.configDir,
@@ -372,6 +559,10 @@ class BurrowClient {
     this.pathOptions = {
       followSymlinks: options.followSymlinks
     };
+    this.trustManager = new TrustManager({
+      storage: this.storage,
+      followSymlinks: options.followSymlinks
+    });
   }
   async set(key, value, options = {}) {
     assertValidEnvKey(key);
@@ -407,6 +598,66 @@ 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 hook(cwd, options) {
+    const previousKeys = new Set(options.previousKeys ?? []);
+    if (process.env["BURROW_AUTOLOAD"] === "0") {
+      const diff2 = computeHookDiff(previousKeys, []);
+      const commands2 = generateShellCommands(diff2, options.shell);
+      const useColor2 = options.useColor ?? !process.env["NO_COLOR"];
+      const message2 = diff2.toUnset.length > 0 ? formatHookMessage(diff2, useColor2) : undefined;
+      return {
+        commands: commands2,
+        message: message2,
+        secrets: [],
+        unloadedKeys: diff2.toUnset,
+        trusted: false,
+        notTrustedReason: "autoload-disabled"
+      };
+    }
+    const trustResult = await this.isTrusted({ path: cwd });
+    if (!trustResult.trusted) {
+      const diff2 = computeHookDiff(previousKeys, []);
+      const commands2 = generateShellCommands(diff2, options.shell);
+      const useColor2 = options.useColor ?? !process.env["NO_COLOR"];
+      const message2 = diff2.toUnset.length > 0 ? formatHookMessage(diff2, useColor2) : undefined;
+      return {
+        commands: commands2,
+        message: message2,
+        secrets: [],
+        unloadedKeys: diff2.toUnset,
+        trusted: false,
+        notTrustedReason: trustResult.reason
+      };
+    }
+    const resolvedSecrets = await this.resolve(cwd);
+    const secrets = resolveToLoadedSecrets(resolvedSecrets);
+    const diff = computeHookDiff(previousKeys, secrets);
+    const commands = generateShellCommands(diff, options.shell);
+    const useColor = options.useColor ?? !process.env["NO_COLOR"];
+    const message = formatHookMessage(diff, useColor);
+    return {
+      commands,
+      message,
+      secrets,
+      unloadedKeys: diff.toUnset,
+      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.319e6c8",
   "description": "Platform-agnostic, directory-scoped secrets manager",
   "type": "module",
   "main": "dist/api.js",