@enactprotocol/secrets 2.0.0

package/README.md

@@ -0,0 +1,73 @@
+# @enactprotocol/secrets
+
+OS keyring integration and environment variable management for Enact.
+
+## Overview
+
+This package provides:
+- OS-native keyring storage (macOS Keychain, Windows Credential Manager, Linux Secret Service)
+- Namespace-scoped secret resolution with inheritance
+- `.env` file management (global and local)
+- Dagger secret URI scheme support
+- Secure secret handling with memory-only runtime
+
+## Architecture
+
+### Secret Storage
+
+Secrets are stored in the OS keyring with the service name `enact-cli` and account identifier `{namespace}:{SECRET_NAME}`.
+
+Examples:
+- `alice/api:API_TOKEN`
+- `acme-corp/data:DATABASE_URL`
+
+### Namespace Inheritance
+
+When resolving secrets, Enact walks up the namespace path:
+
+```
+Tool: alice/api/slack/notifier
+Needs: API_TOKEN
+
+Lookup:
+  1. alice/api/slack:API_TOKEN
+  2. alice/api:API_TOKEN ✓ found
+  3. alice:API_TOKEN
+```
+
+First match wins.
+
+### Environment Variables
+
+Non-secret environment variables are stored in `.env` files with priority:
+
+1. **Local project** (`.enact/.env`) - highest priority
+2. **Global user** (`~/.enact/.env`)
+3. **Default values** from tool manifest - lowest priority
+
+## Status
+
+Currently in Phase 1 (scaffolding). Full implementation will be completed in Phase 3.
+
+## Development
+
+```bash
+# Build
+bun run build
+
+# Test
+bun test
+
+# Type check
+bun run typecheck
+```
+
+## Planned Features (Phase 3)
+
+- [ ] Keyring integration (@zowe/secrets-for-zowe-sdk)
+- [ ] setSecret() / getSecret() / listSecrets() / deleteSecret()
+- [ ] Namespace inheritance resolution
+- [ ] .env file reading and writing
+- [ ] Dagger secret URI parsing (env://, file://, cmd://, op://, vault://)
+- [ ] Cross-platform testing
+- [ ] Comprehensive test coverage

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@enactprotocol/secrets",
+  "version": "2.0.0",
+  "description": "OS keyring integration and environment variable management for Enact",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf dist",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zowe/secrets-for-zowe-sdk": "^8.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "keywords": ["keyring", "secrets", "environment", "credentials"],
+  "author": "Enact Protocol",
+  "license": "Apache-2.0"
+}

package/src/dagger/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Dagger secret integration
+ *
+ * Re-exports all dagger-related functions
+ */
+
+export {
+  parseSecretUri,
+  resolveSecretUri,
+  isSecretUri,
+  getSupportedSchemes,
+} from "./uri-parser";
+
+export {
+  getSecretObject,
+  getSecretObjects,
+  parseSecretOverride,
+  parseSecretOverrides,
+} from "./secret-object";

package/src/dagger/secret-object.ts

@@ -0,0 +1,126 @@
+/**
+ * Get secret objects for Dagger integration
+ *
+ * Combines keyring secrets with Dagger URI overrides
+ */
+
+import { resolveSecret } from "../resolver";
+import type { GetSecretOptions, SecretObject } from "../types";
+import { isSecretUri, resolveSecretUri } from "./uri-parser";
+
+/**
+ * Get a secret object for Dagger
+ *
+ * If an override URI is provided, resolves that instead of keyring.
+ * Otherwise, resolves from keyring with namespace inheritance.
+ *
+ * @param toolPath - The tool path for namespace resolution
+ * @param secretName - The secret name
+ * @param options - Options including override URI
+ * @returns Secret object with name, value, and source info
+ * @throws Error if secret not found
+ */
+export async function getSecretObject(
+  toolPath: string,
+  secretName: string,
+  options: GetSecretOptions = {}
+): Promise<SecretObject> {
+  const { overrideUri } = options;
+
+  // If override URI is provided, resolve it
+  if (overrideUri) {
+    const value = await resolveSecretUri(overrideUri);
+    return {
+      name: secretName,
+      value,
+      source: "override",
+      overrideUri,
+    };
+  }
+
+  // Otherwise, resolve from keyring
+  const result = await resolveSecret(toolPath, secretName);
+
+  if (!result.found) {
+    throw new Error(
+      `Secret '${secretName}' not found for tool '${toolPath}'. ` +
+        `Searched namespaces: ${result.searchedNamespaces.join(", ")}. ` +
+        `Set with: enact env set ${secretName} --secret --namespace <namespace>`
+    );
+  }
+
+  return {
+    name: secretName,
+    value: result.value,
+    source: "keyring",
+    namespace: result.namespace,
+  };
+}
+
+/**
+ * Get multiple secret objects for a tool
+ *
+ * @param toolPath - The tool path for namespace resolution
+ * @param secrets - Map of secret name to optional override URI
+ * @returns Map of secret name to secret object
+ */
+export async function getSecretObjects(
+  toolPath: string,
+  secrets: Record<string, string | undefined>
+): Promise<Map<string, SecretObject>> {
+  const results = new Map<string, SecretObject>();
+
+  for (const [name, overrideUri] of Object.entries(secrets)) {
+    const obj = await getSecretObject(toolPath, name, overrideUri ? { overrideUri } : {});
+    results.set(name, obj);
+  }
+
+  return results;
+}
+
+/**
+ * Parse a secret override from CLI format
+ *
+ * Format: SECRET_NAME=uri
+ * Example: API_TOKEN=env://MY_API_TOKEN
+ *
+ * @param override - The override string
+ * @returns Parsed name and URI, or null if invalid
+ */
+export function parseSecretOverride(override: string): { name: string; uri: string } | null {
+  const eqIndex = override.indexOf("=");
+  if (eqIndex === -1) {
+    return null;
+  }
+
+  const name = override.slice(0, eqIndex).trim();
+  const uri = override.slice(eqIndex + 1).trim();
+
+  if (!name || !isSecretUri(uri)) {
+    return null;
+  }
+
+  return { name, uri };
+}
+
+/**
+ * Parse multiple secret overrides from CLI
+ *
+ * @param overrides - Array of override strings
+ * @returns Map of secret name to override URI
+ */
+export function parseSecretOverrides(overrides: string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  for (const override of overrides) {
+    const parsed = parseSecretOverride(override);
+    if (parsed) {
+      result[parsed.name] = parsed.uri;
+    }
+  }
+
+  return result;
+}
+
+// Re-export URI functions
+export { parseSecretUri, resolveSecretUri, isSecretUri, getSupportedSchemes } from "./uri-parser";

package/src/dagger/uri-parser.ts

@@ -0,0 +1,202 @@
+/**
+ * Dagger Secret URI parser and resolver
+ *
+ * Supports secret URIs:
+ * - env://VAR_NAME - Environment variable
+ * - file://PATH - File contents
+ * - cmd://COMMAND - Command output
+ * - op://VAULT/ITEM/FIELD - 1Password
+ * - vault://PATH - HashiCorp Vault
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { DaggerSecretScheme, DaggerSecretUri } from "../types";
+
+/**
+ * Valid URI schemes
+ */
+const VALID_SCHEMES = new Set<DaggerSecretScheme>(["env", "file", "cmd", "op", "vault"]);
+
+/**
+ * Parse a Dagger secret URI
+ *
+ * @param uri - The URI to parse (e.g., "env://API_KEY")
+ * @returns Parsed URI with scheme and value
+ * @throws Error if URI is invalid
+ */
+export function parseSecretUri(uri: string): DaggerSecretUri {
+  const match = uri.match(/^([a-z]+):\/\/(.+)$/);
+  if (!match || !match[1] || !match[2]) {
+    throw new Error(`Invalid secret URI format: ${uri}. Expected format: scheme://value`);
+  }
+
+  const schemeStr = match[1];
+  const value = match[2];
+  const scheme = schemeStr as DaggerSecretScheme;
+
+  if (!VALID_SCHEMES.has(scheme)) {
+    throw new Error(
+      `Invalid secret URI scheme: ${scheme}. Valid schemes: ${Array.from(VALID_SCHEMES).join(", ")}`
+    );
+  }
+
+  return {
+    scheme,
+    value,
+    original: uri,
+  };
+}
+
+/**
+ * Check if a string is a valid secret URI
+ */
+export function isSecretUri(uri: string): boolean {
+  try {
+    parseSecretUri(uri);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve a secret URI to its actual value
+ *
+ * @param uri - The URI to resolve
+ * @returns The secret value
+ * @throws Error if resolution fails
+ */
+export async function resolveSecretUri(uri: string): Promise<string> {
+  const parsed = parseSecretUri(uri);
+
+  switch (parsed.scheme) {
+    case "env":
+      return resolveEnvUri(parsed.value);
+    case "file":
+      return resolveFileUri(parsed.value);
+    case "cmd":
+      return resolveCmdUri(parsed.value);
+    case "op":
+      return resolveOpUri(parsed.value);
+    case "vault":
+      return resolveVaultUri(parsed.value);
+    default:
+      throw new Error(`Unsupported secret scheme: ${parsed.scheme}`);
+  }
+}
+
+/**
+ * Resolve env:// URI - read from environment variable
+ */
+function resolveEnvUri(varName: string): string {
+  const value = process.env[varName];
+  if (value === undefined) {
+    throw new Error(`Environment variable '${varName}' is not set (from env://${varName})`);
+  }
+  return value;
+}
+
+/**
+ * Resolve file:// URI - read file contents
+ */
+function resolveFileUri(path: string): string {
+  // Handle relative paths
+  const resolvedPath = resolve(path);
+
+  if (!existsSync(resolvedPath)) {
+    throw new Error(`File not found: ${resolvedPath} (from file://${path})`);
+  }
+
+  return readFileSync(resolvedPath, "utf-8").trim();
+}
+
+/**
+ * Resolve cmd:// URI - execute command and capture output
+ */
+function resolveCmdUri(command: string): string {
+  try {
+    const output = execSync(command, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return output.trim();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Command failed: ${command} (from cmd://${command}): ${message}`);
+  }
+}
+
+/**
+ * Resolve op:// URI - 1Password CLI
+ * Format: op://vault/item/field
+ *
+ * Requires 1Password CLI (op) to be installed and authenticated
+ */
+function resolveOpUri(path: string): string {
+  const opUri = `op://${path}`;
+  try {
+    const output = execSync(`op read "${opUri}"`, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return output.trim();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `1Password read failed for ${opUri}. Ensure 'op' CLI is installed and authenticated: ${message}`
+    );
+  }
+}
+
+/**
+ * Resolve vault:// URI - HashiCorp Vault
+ * Format: vault://path/to/secret#field
+ *
+ * Requires Vault CLI and VAULT_ADDR, VAULT_TOKEN environment variables
+ */
+function resolveVaultUri(path: string): string {
+  // Parse path and optional field
+  const [secretPath, field] = path.split("#");
+
+  try {
+    const command = `vault kv get -format=json "${secretPath}"`;
+    const output = execSync(command, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    const data = JSON.parse(output);
+    const secretData = data.data?.data ?? data.data;
+
+    if (field) {
+      if (!(field in secretData)) {
+        throw new Error(`Field '${field}' not found in secret at ${secretPath}`);
+      }
+      return String(secretData[field]);
+    }
+
+    // If no field specified, return first value or JSON
+    const values = Object.values(secretData);
+    if (values.length === 1) {
+      return String(values[0]);
+    }
+    return JSON.stringify(secretData);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(
+        `Failed to parse Vault response for ${path}. Ensure VAULT_ADDR and VAULT_TOKEN are set.`
+      );
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Vault read failed for ${path}: ${message}`);
+  }
+}
+
+/**
+ * Get supported URI schemes
+ */
+export function getSupportedSchemes(): DaggerSecretScheme[] {
+  return Array.from(VALID_SCHEMES);
+}

package/src/env/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Environment variable management
+ *
+ * Re-exports all env-related functions
+ */
+
+// Parser functions
+export {
+  parseEnvFile,
+  parseEnvContent,
+  serializeEnvFile,
+  createEnvContent,
+  updateEnvVar,
+  removeEnvVar,
+} from "./parser";
+
+// Reader functions
+export {
+  getGlobalEnvPath,
+  getLocalEnvPath,
+  readEnvFile,
+  readEnvVars,
+  loadGlobalEnv,
+  loadLocalEnv,
+  loadGlobalEnvFile,
+  loadLocalEnvFile,
+  globalEnvExists,
+  localEnvExists,
+} from "./reader";
+
+// Writer functions
+export {
+  writeEnvFile,
+  writeEnvVars,
+  setEnvVar,
+  deleteEnvVar,
+  setGlobalEnvVar,
+  setLocalEnvVar,
+  deleteGlobalEnvVar,
+  deleteLocalEnvVar,
+} from "./writer";
+
+// Manager functions (high-level API)
+export {
+  setEnv,
+  getEnv,
+  getEnvValue,
+  deleteEnv,
+  listEnv,
+  resolveAllEnv,
+  resolveToolEnv,
+  hasLocalEnv,
+  hasGlobalEnv,
+} from "./manager";