Managing multiple docker hub accounts using docker-use

Isolating Docker Credentials: A Multi-Profile Architecture for Secure Workflows

Current Situation Analysis

Modern development workflows rarely operate within a single identity boundary. Engineers frequently toggle between organizational registries for production deployments, personal namespaces for open-source contributions, and temporary tokens for CI/CD validation. The friction of managing these identities creates a tangible drag on productivity and introduces security risks.

The standard Docker workflow assumes a single active identity. Switching accounts traditionally requires docker logout followed by docker login. This approach is inefficient because it forces a network round-trip for authentication on every switch, invalidates active sessions, and increases the cognitive load of remembering which namespace is currently active. A mis-push to the wrong namespace can result in intellectual property leakage or broken deployment pipelines.

While Docker provides the DOCKER_CONFIG environment variable to specify an alternative configuration directory, leveraging this variable manually is cumbersome. Developers must manage directory paths, ensure credential helpers are preserved, and integrate the variable into their shell environment. Consequently, many teams accept the inefficiency of single-account workflows or resort to fragile workarounds, leaving the robust isolation capabilities of Docker's configuration model underutilized.

WOW Moment: Key Findings

Implementing a multi-profile architecture based on isolated configuration directories fundamentally changes the risk and performance profile of Docker authentication. By decoupling identities into distinct filesystem paths and managing them via environment variables, teams can achieve near-instant switching with cryptographic isolation.

Strategy	Switch Latency	Namespace Safety	Credential Persistence	Automation Compatibility
Manual Login/Logout	High (Network RTT + Auth)	Low (Human error prone)	Lost on logout	Poor (Breaks sessions)
Single Config + Token Rotation	Medium	Medium (Shared state)	Good	Moderate (Complex scripting)
Isolated Profiles	Near-zero (Env var swap)	High (Strict isolation)	Preserved per profile	Excellent (Deterministic state)

This comparison highlights that isolated profiles eliminate the network overhead of re-authentication while providing strict boundaries that prevent accidental cross-namespace operations. The architecture enables scripts and shells to maintain independent authentication states simultaneously, a capability impossible with the default single-config model.

Core Solution

The solution relies on a three-component architecture: a directory-per-identity model, a type-safe CLI for profile management, and a secure shell wrapper that mutates the parent environment without evaluation risks.

1. Directory Structure and Isolation

Each profile maps to a dedicated directory containing a config.json. This file holds the authentication tokens and registry settings for that specific identity.

~/.dock-profiles/
├── acme-corp/
│   └── config.json
├── personal-dev/
│   └── config.json
└── ci-runner/
    └── config.json

2. TypeScript CLI Implementation

We implement a CLI tool, dock-profile, in TypeScript. This tool handles profile creation, validation, and path resolution. The CLI outputs the absolute path of the target configuration directory, which the shell wrapper consumes.

// src/dock-profile.ts
import * as fs from 'fs';
import * as path from 'path';
import { execSync } from 'child_process';

const PROFILES_ROOT = path.join(process.env.HOME || '', '.dock-profiles');
const ALIAS_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;

function validateAlias(alias: string): void {
  if (!ALIAS_REGEX.test(alias)) {
    throw new Error(`Invalid alias: '${alias}'. Must match pattern: ${ALIAS_REGEX.source}`);
  }
}

function ensureProfilesRoot(): void {
  if (!fs.existsSync(PROFILES_ROOT)) {
    fs.mkdirSync(PROFILES_ROOT, { recursive: true });
  }
}

function addProfile(alias: string): string {
  validateAlias(alias);
  ensureProfilesRoot();
  
  const profileDir = path.join(PROFILES_ROOT, alias);
  if (fs.existsSync(profileDir)) {
    throw new Error(`Profile '${alias}' already exists.`);
  }

  fs.mkdirSync(profileDir, { recursive: true });
  
  // Execute docker login within the isolated directory context
  // We temporarily set DOCKER_CONFIG for the child process
  const env = { ...process.env, DOCKER_CONFIG: profileDir };
  try {
    execSync('docker login', { stdio: 'inherit', env });
    
    // Post-login: Preserve credential helpers
    // Docker login may write a config that overwrites helper settings.
    // We must ensure the credential store reference is retained.
    const configPath = path.join(profileDir, 'config.json');
    if (fs.existsSync(configPath)) {
      const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
      // If the user has a global credential helper, ensure it's referenced
      // or merge with existing helper config if migrating.
      // For a fresh profile, docker login usually handles this,
      // but we validate the structure here.
      if (!config.credsStore && !config.credHelpers) {
        console.warn('Warning: No credential helper detected. Tokens stored in plaintext.');
      }
    }
  } catch (error) {
    // Cleanup on failure
    fs.rmSync(profileDir, { recursive: true, force: true });
    throw error;
  }

  return profileDir;
}

function resolveProfile(alias: string): string {
  validateAlias(alias);
  const profileDir = path.join(PROFILES_ROOT, alias);
  
  if (!fs.existsSync(profileDir)) {
    throw new Error(`Profile '${alias}' not found.`);
  }
  
  return profileDir;
}

// CLI Entry Point Logic
const command = process.argv[2];
const alias = process.argv[3];

try {
  let outputPath: string;
  if (command === 'add' && alias) {
    outputPath = addProfile(alias);
  } else if (command === 'switch' && alias) {
    outputPath = resolveProfile(alias);
  } else {
    throw new Error('Usage: dock-profile <add|switch> <alias>');
  }
  
  // Output path for shell wrapper consumption
  console.log(outputPath);
} catch (err) {
  console.error(err.message);
  process.exit(1);
}

3. Secure Shell Wrapper

A child process cannot modify the environment variables of its parent shell. Therefore, the CLI cannot set DOCKER_CONFIG directly. Instead, we use a shell function that captures the CLI's stdout and assigns the variable.

Critical Security Decision: We use direct assignment rather than eval. Using eval on CLI output introduces injection vulnerabilities if the output contains shell metacharacters. Direct assignment is safe because the path is treated as a string literal.

# ~/.dock-profile-wrapper.sh
_dock_profile_wrapper() {
    local config_path
    # Capture stdout from the binary
    config_path=$(command dock-profile "$@" 2>/dev/null)
    
    if [[ $? -eq 0 && -n "$config_path" ]]; then
        # Direct assignment prevents injection attacks
        export DOCKER_CONFIG="$config_path"
        echo "✓ Docker profile active: $(basename "$config_path")"
    else
        return 1
    fi
}

# Create the user-facing command
alias dock-profile='_dock_profile_wrapper'

4. Architecture Rationale

• Why TypeScript? Provides compile-time safety for path manipulation and regex validation. The strict typing reduces runtime errors in directory resolution.
• Why Regex Validation? Prevents directory traversal attacks. An alias like ../etc could allow an attacker to overwrite system files if passed unchecked to filesystem operations.
• Why Credential Helper Preservation? Docker Desktop and Linux distributions often use osxkeychain or secretservice to store tokens securely. If a profile management tool overwrites config.json without retaining the credsStore field, Docker falls back to plaintext token storage or prompts for passwords, breaking automation and reducing security.

Pitfall Guide

Pitfall	Explanation	Fix
Directory Traversal	Allowing aliases like ../../tmp can cause the tool to read/write outside the intended directory, potentially overwriting sensitive files.	Enforce strict regex validation on all aliases before any filesystem interaction. Reject characters that could escape the directory hierarchy.
Shell Injection via Eval	Using eval $(dock-profile switch) allows the CLI output to execute arbitrary commands if it contains malicious payloads.	Use direct variable assignment (export VAR=$(...)). Never eval output from binaries.
Credential Helper Loss	Overwriting config.json during profile creation can strip the credsStore field, causing Docker to lose keychain integration.	After docker login, read the generated config and ensure credsStore or credHelpers fields are preserved or merged correctly.
Stale Token Assumption	Assuming tokens in a profile are always valid. Tokens can expire or be revoked.	Implement a dock-profile verify command that runs a lightweight registry check and prompts for re-authentication if the token is invalid.
Context vs. Profile Confusion	Developers may confuse Docker Contexts (which manage daemon endpoints) with Profiles (which manage registry auth).	Document clearly that profiles isolate config.json for registry authentication, while contexts manage host, tls, and machine settings. They can be used together but solve different problems.
Race Conditions in Shared Environments	In multi-user systems, profiles stored in a shared directory could be accessed by other users.	Store profiles in user-owned directories (~/.dock-profiles) with restrictive permissions (chmod 700). Do not use global paths for sensitive credentials.
CI/CD Profile Leakage	Using profile tools in CI scripts without cleanup can leave credentials in the build environment.	In CI, avoid profile tools. Use injected secrets directly into a temporary DOCKER_CONFIG directory and wipe it in the finally block.

Production Bundle

Action Checklist

• Initialize Directory Structure: Create the root profiles directory with restrictive permissions (mkdir -p ~/.dock-profiles && chmod 700 ~/.dock-profiles).
• Implement Validation: Ensure the CLI enforces a regex pattern that prevents path traversal and special characters in aliases.
• Deploy Shell Wrapper: Source the wrapper script in your shell RC file. Verify that dock-profile is a function, not a binary alias.
• Preserve Credential Helpers: Test that adding a profile retains the credsStore configuration. Verify docker push does not prompt for passwords.
• Verify Isolation: Switch between profiles and run docker info or docker whoami to confirm the active identity changes without restarting the daemon.
• Audit Permissions: Ensure profile directories are not world-readable. Credentials are sensitive assets.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Local Multi-Account Dev	Isolated Profiles	Fast switching, strict namespace isolation, preserves local keychain.	Low (Setup time only)
CI/CD Pipeline	Injected Secrets	Profiles add complexity; CI should use ephemeral tokens injected directly into a temp config dir.	None (Standard practice)
Remote Daemon Management	Docker Contexts	Contexts handle host/TLS settings. Profiles handle registry auth. Use Contexts for daemon switching.	None
Team Shared Workstation	Per-User Profiles	Profiles must be user-scoped to prevent credential leakage between users.	Low

Configuration Template

Example of a secure config.json within a profile directory, demonstrating the preservation of credential helpers:

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "dXNlcm5hbWU6cGFzc3dvcmQ="
    }
  },
  "credsStore": "osxkeychain",
  "credHelpers": {
    "gcr.io": "gcloud"
  }
}

Note: The auth field may be empty if using a credential store. The presence of credsStore is critical for security and usability.

Quick Start Guide

1. Install the CLI: Build or install the dock-profile binary and ensure it is in your PATH.
2. Source the Wrapper: Add source ~/.dock-profile-wrapper.sh to your ~/.zshrc or ~/.bashrc.
3. Add a Profile: Run dock-profile add work. Complete the docker login prompt. The tool creates ~/.dock-profiles/work/ and preserves your credential helper.
4. Switch Context: Run dock-profile work. The shell wrapper sets DOCKER_CONFIG to the work profile directory.
5. Verify: Run docker push work-namespace/my-image:latest. The push uses the work credentials. Switch to dock-profile personal to push to your personal namespace instantly.