@enactprotocol/secrets 2.0.0

package/src/index.ts

@@ -0,0 +1,120 @@
+/**
+ * @enactprotocol/secrets
+ *
+ * OS keyring integration and environment variable management for Enact.
+ * Provides secure secret storage using platform-native keychains.
+ */
+
+export const version = "0.1.0";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type {
+  SecretResolution,
+  SecretNotFound,
+  SecretResolutionResult,
+  SecretMetadata,
+  SecretTrace,
+  SecretTraceEntry,
+  EnvScope,
+  EnvFileLocation,
+  EnvironmentVariable,
+  EnvResolution,
+  ParsedEnvFile,
+  EnvFileLine,
+  DaggerSecretScheme,
+  DaggerSecretUri,
+  GetSecretOptions,
+  SecretObject,
+} from "./types";
+
+export { KEYRING_SERVICE } from "./types";
+
+// ============================================================================
+// Keyring Functions
+// ============================================================================
+
+export {
+  buildAccount,
+  parseAccount,
+  setSecret,
+  getSecret,
+  deleteSecret,
+  listSecrets,
+  listAllSecrets,
+  secretExists,
+  isKeyringAvailable,
+} from "./keyring";
+
+// ============================================================================
+// Secret Resolution
+// ============================================================================
+
+export {
+  getNamespaceChain,
+  resolveSecret,
+  traceSecretResolution,
+  resolveSecrets,
+  checkRequiredSecrets,
+} from "./resolver";
+
+// ============================================================================
+// Environment Variables
+// ============================================================================
+
+export {
+  // Parser
+  parseEnvFile,
+  parseEnvContent,
+  serializeEnvFile,
+  createEnvContent,
+  updateEnvVar,
+  removeEnvVar,
+  // Reader
+  getGlobalEnvPath,
+  getLocalEnvPath,
+  readEnvFile,
+  readEnvVars,
+  loadGlobalEnv,
+  loadLocalEnv,
+  loadGlobalEnvFile,
+  loadLocalEnvFile,
+  globalEnvExists,
+  localEnvExists,
+  // Writer
+  writeEnvFile,
+  writeEnvVars,
+  setEnvVar,
+  deleteEnvVar,
+  setGlobalEnvVar,
+  setLocalEnvVar,
+  deleteGlobalEnvVar,
+  deleteLocalEnvVar,
+  // Manager (high-level API)
+  setEnv,
+  getEnv,
+  getEnvValue,
+  deleteEnv,
+  listEnv,
+  resolveAllEnv,
+  resolveToolEnv,
+  hasLocalEnv,
+  hasGlobalEnv,
+} from "./env";
+
+// ============================================================================
+// Dagger Secret Integration
+// ============================================================================
+
+export {
+  parseSecretUri,
+  resolveSecretUri,
+  isSecretUri,
+  getSupportedSchemes,
+  getSecretObject,
+  getSecretObjects,
+  parseSecretOverride,
+  parseSecretOverrides,
+} from "./dagger";

package/src/keyring.ts

@@ -0,0 +1,136 @@
+/**
+ * OS Keyring integration for secure secret storage
+ *
+ * Uses the system keychain:
+ * - macOS: Keychain
+ * - Windows: Credential Manager
+ * - Linux: Secret Service (libsecret)
+ *
+ * All secrets are stored with:
+ * - Service: "enact-cli"
+ * - Account: "{namespace}:{SECRET_NAME}"
+ */
+
+import { keyring } from "@zowe/secrets-for-zowe-sdk";
+import { KEYRING_SERVICE, type SecretMetadata } from "./types";
+
+/**
+ * Build the account string for keyring storage
+ * Format: "namespace:SECRET_NAME"
+ */
+export function buildAccount(namespace: string, secretName: string): string {
+  return `${namespace}:${secretName}`;
+}
+
+/**
+ * Parse an account string back to namespace and secret name
+ */
+export function parseAccount(account: string): {
+  namespace: string;
+  secretName: string;
+} {
+  const colonIndex = account.lastIndexOf(":");
+  if (colonIndex === -1) {
+    throw new Error(`Invalid account format: ${account}`);
+  }
+  return {
+    namespace: account.slice(0, colonIndex),
+    secretName: account.slice(colonIndex + 1),
+  };
+}
+
+/**
+ * Store a secret in the OS keyring
+ *
+ * @param namespace - The namespace for the secret (e.g., "alice/api")
+ * @param name - The secret name (e.g., "API_TOKEN")
+ * @param value - The secret value to store
+ */
+export async function setSecret(namespace: string, name: string, value: string): Promise<void> {
+  const account = buildAccount(namespace, name);
+  await keyring.setPassword(KEYRING_SERVICE, account, value);
+}
+
+/**
+ * Retrieve a secret from the OS keyring
+ *
+ * @param namespace - The namespace for the secret
+ * @param name - The secret name
+ * @returns The secret value, or null if not found
+ */
+export async function getSecret(namespace: string, name: string): Promise<string | null> {
+  const account = buildAccount(namespace, name);
+  const value = await keyring.getPassword(KEYRING_SERVICE, account);
+  return value ?? null;
+}
+
+/**
+ * Delete a secret from the OS keyring
+ *
+ * @param namespace - The namespace for the secret
+ * @param name - The secret name
+ * @returns true if deleted, false if not found
+ */
+export async function deleteSecret(namespace: string, name: string): Promise<boolean> {
+  const account = buildAccount(namespace, name);
+  return await keyring.deletePassword(KEYRING_SERVICE, account);
+}
+
+/**
+ * List all secrets for a namespace
+ *
+ * @param namespace - The namespace to list secrets for
+ * @returns Array of secret names in the namespace
+ */
+export async function listSecrets(namespace: string): Promise<string[]> {
+  const credentials = await keyring.findCredentials(KEYRING_SERVICE);
+  const prefix = `${namespace}:`;
+
+  return credentials
+    .filter((cred) => cred.account.startsWith(prefix))
+    .map((cred) => cred.account.slice(prefix.length));
+}
+
+/**
+ * List all secrets across all namespaces
+ *
+ * @returns Array of secret metadata
+ */
+export async function listAllSecrets(): Promise<SecretMetadata[]> {
+  const credentials = await keyring.findCredentials(KEYRING_SERVICE);
+
+  return credentials.map((cred) => {
+    const { namespace, secretName } = parseAccount(cred.account);
+    return {
+      key: secretName,
+      namespace,
+    };
+  });
+}
+
+/**
+ * Check if a secret exists in the keyring
+ *
+ * @param namespace - The namespace for the secret
+ * @param name - The secret name
+ * @returns true if the secret exists
+ */
+export async function secretExists(namespace: string, name: string): Promise<boolean> {
+  const value = await getSecret(namespace, name);
+  return value !== null;
+}
+
+/**
+ * Check if the keyring is available on this system
+ *
+ * @returns true if keyring operations are available
+ */
+export async function isKeyringAvailable(): Promise<boolean> {
+  try {
+    // Try to list credentials - this will fail if keyring is not available
+    await keyring.findCredentials(KEYRING_SERVICE);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/resolver.ts

@@ -0,0 +1,184 @@
+/**
+ * Secret resolution with namespace inheritance
+ *
+ * When a tool requests a secret, we walk 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.
+ */
+
+import { getSecret } from "./keyring";
+import type {
+  SecretResolution,
+  SecretResolutionResult,
+  SecretTrace,
+  SecretTraceEntry,
+} from "./types";
+
+/**
+ * Get the namespace chain for a tool path
+ * Walks up the path segments from most specific to least specific
+ *
+ * @param toolPath - The full tool path (e.g., "alice/api/slack")
+ * @returns Array of namespaces to check in order
+ *
+ * @example
+ * getNamespaceChain("alice/api/slack")
+ * // Returns: ["alice/api/slack", "alice/api", "alice"]
+ */
+export function getNamespaceChain(toolPath: string): string[] {
+  const segments = toolPath.split("/").filter(Boolean);
+  const chain: string[] = [];
+
+  for (let i = segments.length; i > 0; i--) {
+    chain.push(segments.slice(0, i).join("/"));
+  }
+
+  return chain;
+}
+
+/**
+ * Resolve a secret using namespace inheritance
+ *
+ * @param toolPath - The tool path to resolve secrets for
+ * @param secretName - The secret name to find
+ * @returns Resolution result with namespace info, or not-found result
+ */
+export async function resolveSecret(
+  toolPath: string,
+  secretName: string
+): Promise<SecretResolutionResult> {
+  const namespaces = getNamespaceChain(toolPath);
+  const searchedNamespaces: string[] = [];
+
+  for (const namespace of namespaces) {
+    searchedNamespaces.push(namespace);
+    const value = await getSecret(namespace, secretName);
+
+    if (value !== null) {
+      return {
+        namespace,
+        value,
+        key: secretName,
+        found: true,
+      };
+    }
+  }
+
+  return {
+    key: secretName,
+    found: false,
+    searchedNamespaces,
+  };
+}
+
+/**
+ * Trace secret resolution for debugging
+ * Shows which namespaces were checked and where the secret was found
+ *
+ * @param toolPath - The tool path to resolve secrets for
+ * @param secretName - The secret name to find
+ * @returns Full trace with all namespaces checked
+ */
+export async function traceSecretResolution(
+  toolPath: string,
+  secretName: string
+): Promise<SecretTrace> {
+  const namespaces = getNamespaceChain(toolPath);
+  const entries: SecretTraceEntry[] = [];
+  let result: SecretResolutionResult | null = null;
+
+  for (const namespace of namespaces) {
+    const account = `${namespace}:${secretName}`;
+    const value = await getSecret(namespace, secretName);
+    const found = value !== null;
+
+    entries.push({ namespace, account, found });
+
+    if (found && !result) {
+      result = {
+        namespace,
+        value,
+        key: secretName,
+        found: true,
+      };
+    }
+  }
+
+  // If not found anywhere
+  if (!result) {
+    result = {
+      key: secretName,
+      found: false,
+      searchedNamespaces: namespaces,
+    };
+  }
+
+  return {
+    key: secretName,
+    toolPath,
+    entries,
+    result,
+  };
+}
+
+/**
+ * Resolve multiple secrets for a tool
+ *
+ * @param toolPath - The tool path to resolve secrets for
+ * @param secretNames - Array of secret names to resolve
+ * @returns Map of secret name to resolution result
+ */
+export async function resolveSecrets(
+  toolPath: string,
+  secretNames: string[]
+): Promise<Map<string, SecretResolutionResult>> {
+  const results = new Map<string, SecretResolutionResult>();
+
+  for (const name of secretNames) {
+    const result = await resolveSecret(toolPath, name);
+    results.set(name, result);
+  }
+
+  return results;
+}
+
+/**
+ * Check if all required secrets are available for a tool
+ *
+ * @param toolPath - The tool path to check
+ * @param requiredSecrets - Array of required secret names
+ * @returns Object with available and missing secrets
+ */
+export async function checkRequiredSecrets(
+  toolPath: string,
+  requiredSecrets: string[]
+): Promise<{
+  allFound: boolean;
+  found: SecretResolution[];
+  missing: string[];
+}> {
+  const found: SecretResolution[] = [];
+  const missing: string[] = [];
+
+  for (const name of requiredSecrets) {
+    const result = await resolveSecret(toolPath, name);
+    if (result.found) {
+      found.push(result);
+    } else {
+      missing.push(name);
+    }
+  }
+
+  return {
+    allFound: missing.length === 0,
+    found,
+    missing,
+  };
+}

package/src/types.ts

@@ -0,0 +1,194 @@
+/**
+ * Type definitions for secrets and environment management
+ */
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Keyring service name for all Enact secrets */
+export const KEYRING_SERVICE = "enact-cli";
+
+// ============================================================================
+// Secret Types
+// ============================================================================
+
+/**
+ * Result of secret resolution with namespace information
+ */
+export interface SecretResolution {
+  /** The namespace where the secret was found */
+  namespace: string;
+  /** The secret value */
+  value: string;
+  /** The secret key */
+  key: string;
+  /** Whether the secret was found */
+  found: true;
+}
+
+/**
+ * Result when secret is not found
+ */
+export interface SecretNotFound {
+  /** The secret key that was looked for */
+  key: string;
+  /** Whether the secret was found */
+  found: false;
+  /** Namespaces that were searched */
+  searchedNamespaces: string[];
+}
+
+/**
+ * Result of secret resolution (found or not found)
+ */
+export type SecretResolutionResult = SecretResolution | SecretNotFound;
+
+/**
+ * Metadata about a stored secret
+ */
+export interface SecretMetadata {
+  /** Secret key name */
+  key: string;
+  /** Namespace where it's stored */
+  namespace: string;
+  /** When it was created/last modified (if available) */
+  modified?: Date;
+}
+
+/**
+ * Trace entry for debugging secret resolution
+ */
+export interface SecretTraceEntry {
+  /** Namespace that was checked */
+  namespace: string;
+  /** Account string used for lookup */
+  account: string;
+  /** Whether secret was found at this namespace */
+  found: boolean;
+}
+
+/**
+ * Full trace of secret resolution
+ */
+export interface SecretTrace {
+  /** Secret key being resolved */
+  key: string;
+  /** Tool path used for resolution */
+  toolPath: string;
+  /** Each namespace checked in order */
+  entries: SecretTraceEntry[];
+  /** Final result */
+  result: SecretResolutionResult;
+}
+
+// ============================================================================
+// Environment Variable Types
+// ============================================================================
+
+/**
+ * Scope where environment variables can be stored
+ */
+export type EnvScope = "global" | "local" | "default";
+
+/**
+ * Location where environment variables can be stored (files only)
+ */
+export type EnvFileLocation = "global" | "local";
+
+/**
+ * An environment variable with its value and source
+ */
+export interface EnvironmentVariable {
+  /** Variable key */
+  key: string;
+  /** Variable value */
+  value: string;
+  /** Where it was resolved from */
+  source: EnvScope;
+}
+
+/**
+ * Result of environment variable resolution
+ */
+export interface EnvResolution {
+  /** Variable key */
+  key: string;
+  /** Resolved value */
+  value: string;
+  /** Source of the value */
+  source: EnvScope;
+  /** File path if from a file */
+  filePath?: string;
+}
+
+/**
+ * Parsed .env file content
+ */
+export interface ParsedEnvFile {
+  /** Key-value pairs */
+  vars: Record<string, string>;
+  /** Preserved lines (for writing back with comments) */
+  lines: EnvFileLine[];
+}
+
+/**
+ * A line in an .env file (for preserving format)
+ */
+export interface EnvFileLine {
+  /** Type of line */
+  type: "comment" | "empty" | "variable";
+  /** Original line content */
+  raw: string;
+  /** Variable key (if type is 'variable') */
+  key?: string;
+  /** Variable value (if type is 'variable') */
+  value?: string;
+}
+
+// ============================================================================
+// Dagger Secret URI Types
+// ============================================================================
+
+/**
+ * Supported Dagger secret URI schemes
+ */
+export type DaggerSecretScheme = "env" | "file" | "cmd" | "op" | "vault";
+
+/**
+ * Parsed Dagger secret URI
+ */
+export interface DaggerSecretUri {
+  /** The URI scheme */
+  scheme: DaggerSecretScheme;
+  /** The URI value (without scheme://) */
+  value: string;
+  /** Original full URI */
+  original: string;
+}
+
+/**
+ * Options for getting a secret object
+ */
+export interface GetSecretOptions {
+  /** Override URI to use instead of keyring */
+  overrideUri?: string;
+  /** Whether to trace resolution */
+  trace?: boolean;
+}
+
+/**
+ * Result from getSecretObject
+ */
+export interface SecretObject {
+  /** The secret name */
+  name: string;
+  /** The secret value */
+  value: string;
+  /** Source of the secret */
+  source: "keyring" | "override";
+  /** Namespace if from keyring */
+  namespace?: string;
+  /** Override URI if used */
+  overrideUri?: string;
+}