coding-agent-wrapper 0.1.0__py3-none-any.whl

caw/auth/README.md

@@ -0,0 +1,118 @@
+# caw auth — Credential Management for Docker Containers
+
+Coding agents store OAuth credentials in home directory files (e.g., `~/.claude/.credentials.json`). When running agents inside Docker containers, token refresh creates new tokens (OAuth rotation), invalidating the host's tokens.
+
+`caw auth` solves this by making `~/.caw/auth/` the canonical location for all credential files, mounting it read-write into containers, and using symlinks so writes propagate in real-time.
+
+## How it works
+
+```
+HOST:                                         CONTAINER:
+
+~/.claude/.credentials.json                   /home/playground/.claude/.credentials.json
+    ↓ symlink                                     ↑ copy + inotify sync
+~/.caw/auth/claude/credentials.json  ←—RW mount—→  /tmp/caw_auth/claude/credentials.json
+```
+
+On the host, credential files are replaced with symlinks into `~/.caw/auth/`. Inside the container, credentials are copied from the bind mount and kept in sync bidirectionally via an inotify-based guard.
+
+## Usage
+
+```bash
+caw auth setup                        # collect + symlink all detected agents
+caw auth setup --agents claude codex  # specific agents only
+caw auth setup --force                # overwrite existing auth dir and backups
+
+caw auth status                       # symlink state, token expiry, last modified
+
+docker run $(caw auth docker-flags) -v ./project:/work my-image
+
+caw auth teardown                     # restore original files from backups
+caw auth teardown --dry-run           # preview what would be restored
+```
+
+## Commands
+
+### `caw auth setup`
+
+Reads credentials from `~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.config/cursor/`. Writes canonical files to `~/.caw/auth/`, generates `manifest.json` and `setup-container.sh`, then replaces host credential files with symlinks.
+
+- Credential files (tokens, OAuth) are marked `strategy: symlink` — shared read-write
+- Config files (.claude.json, config.toml) are marked `strategy: copy` — cleaned/stripped for containers
+
+### `caw auth teardown`
+
+Restores original credential files from `~/.caw/auth/.backups/`.
+
+### `caw auth status`
+
+Shows a table with symlink state, token expiry, and last modified time for all managed files.
+
+### `caw auth docker-flags`
+
+Outputs the `-v` flag for Docker:
+
+```bash
+$ caw auth docker-flags
+-v /home/user/.caw/auth:/tmp/caw_auth:rw
+```
+
+## Container setup
+
+The generated `setup-container.sh` runs inside the container (called from your entrypoint). It reads `manifest.json`, copies credentials, and starts a bidirectional inotify guard for credential sync.
+
+```bash
+# In your entrypoint.sh:
+if [ -f /tmp/caw_auth/setup-container.sh ]; then
+    /tmp/caw_auth/setup-container.sh /tmp/caw_auth /home/playground playground
+fi
+```
+
+Requires `jq` in the container image. `inotify-tools` is installed automatically if not present.
+
+## Directory structure
+
+```
+~/.caw/auth/
+├── manifest.json              # file map + metadata
+├── setup-container.sh         # POSIX script for container setup
+├── .backups/                  # originals before symlinking
+├── claude/
+│   ├── credentials.json       # credential (symlinked)
+│   └── config.json            # cleaned .claude.json (copied)
+├── codex/
+│   ├── auth.json              # credential (symlinked)
+│   └── config.toml            # cleaned config (copied)
+├── gemini/
+│   ├── oauth_creds.json       # credential (symlinked)
+│   └── ...                    # config files (copied)
+└── cursor/
+    ├── auth.json              # credential (symlinked)
+    └── cli-config.json        # cleaned config (copied)
+```
+
+## Supported agents
+
+| Agent | Credential files | Config files |
+|-------|-----------------|--------------|
+| Claude Code | `.claude/.credentials.json` | `.claude.json` (stripped to essential keys) |
+| Codex | `.codex/auth.json` | `.codex/config.toml` (local trust removed) |
+| Gemini CLI | `.gemini/oauth_creds.json` | `google_accounts.json`, `settings.json`, `installation_id` |
+| Cursor | `.config/cursor/auth.json` | `.cursor/cli-config.json` (stripped) |
+
+## Programmatic API
+
+```python
+from caw.auth import setup, teardown, get_status, get_docker_flags
+
+setup(agents=["claude"])
+statuses = get_status()
+flags = get_docker_flags()
+teardown()
+```
+
+See [`examples/auth.py`](../../examples/auth.py) for a full example.
+
+## Known limitation
+
+OAuth token rotation means a refresh returns a new refresh token, invalidating the old one. If two processes refresh simultaneously, one gets an invalid token. Don't run the same agent identity in two places at once.

caw/auth/__init__.py

@@ -0,0 +1,23 @@
+"""caw.auth — Credential management for Docker containers."""
+
+from .collector import AUTH_DIR, setup
+from .linker import teardown
+from .manifest import AgentManifest, Manifest, ManifestFile
+from .providers import PROVIDERS, AgentAuthProvider, CollectedFile
+from .status import AuthFileStatus, get_docker_flags, get_status, status
+
+__all__ = [
+    "AUTH_DIR",
+    "AgentAuthProvider",
+    "AgentManifest",
+    "AuthFileStatus",
+    "CollectedFile",
+    "Manifest",
+    "ManifestFile",
+    "PROVIDERS",
+    "get_docker_flags",
+    "get_status",
+    "setup",
+    "status",
+    "teardown",
+]

caw/auth/cli.py

@@ -0,0 +1,68 @@
+"""CLI subcommands for `caw auth`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+
+app = typer.Typer(help="Manage credentials for Docker containers.")
+
+
+@app.command()
+def setup(
+    agents: Annotated[
+        Optional[list[str]],
+        typer.Option("--agents", "-a", help="Agents to include (claude, codex, gemini, cursor, or all)"),
+    ] = None,
+    source_home: Annotated[
+        str,
+        typer.Option("--source-home", help="Source home directory to read credentials from"),
+    ] = str(Path.home()),
+    force: Annotated[bool, typer.Option("--force", "-f", help="Overwrite existing auth dir and backups")] = False,
+):
+    """Collect credentials from host into ~/.caw/auth/ and symlink them."""
+    from .collector import setup as do_setup
+
+    do_setup(agents=agents or ["all"], source_home=source_home, force=force)
+
+
+@app.command()
+def teardown(
+    agents: Annotated[
+        Optional[list[str]],
+        typer.Option("--agents", "-a", help="Agents to restore"),
+    ] = None,
+    dry_run: Annotated[bool, typer.Option("--dry-run", "-n", help="Show what would be done")] = False,
+):
+    """Restore original credential files from backups."""
+    from .linker import teardown as do_teardown
+
+    do_teardown(agents=agents, dry_run=dry_run)
+
+
+@app.command("status")
+def status_cmd(
+    agents: Annotated[
+        Optional[list[str]],
+        typer.Option("--agents", "-a", help="Agents to show"),
+    ] = None,
+):
+    """Show symlink state, token expiry, and last modified time."""
+    from .status import status as do_status
+
+    do_status(agents=agents)
+
+
+@app.command("docker-flags")
+def docker_flags():
+    """Output the -v flag string for docker."""
+    from .status import get_docker_flags as do_get_docker_flags
+
+    try:
+        typer.echo(do_get_docker_flags())
+    except FileNotFoundError:
+        typer.echo("Error: manifest.json not found. Run `caw auth setup` first.", err=True)
+        raise typer.Exit(1)

caw/auth/collector.py

@@ -0,0 +1,324 @@
+"""Set up credentials from host into ~/.caw/auth/ and generate manifest + setup script."""
+
+from __future__ import annotations
+
+import textwrap
+from pathlib import Path
+
+from rich.console import Console
+
+from .manifest import AgentManifest, Manifest
+from .providers import PROVIDERS, AgentAuthProvider, CollectedFile
+
+console = Console()
+
+# Canonical auth directory
+AUTH_DIR = Path.home() / ".caw" / "auth"
+
+
+def _resolve_providers(agent_names: list[str]) -> list[AgentAuthProvider]:
+    """Resolve provider names to provider objects."""
+    if "all" in agent_names:
+        return list(PROVIDERS.values())
+    result = []
+    for name in agent_names:
+        if name not in PROVIDERS:
+            available = ", ".join(PROVIDERS.keys())
+            raise ValueError(f"Unknown agent '{name}'. Available: {available}")
+        result.append(PROVIDERS[name])
+    return result
+
+
+def _validate_providers(
+    providers: list[AgentAuthProvider], src_home: Path
+) -> tuple[list[AgentAuthProvider], list[tuple[AgentAuthProvider, list[str]]]]:
+    """Validate providers, returning (valid, skipped) lists."""
+    valid = []
+    skipped = []
+    for provider in providers:
+        missing = provider.validate(src_home)
+        if missing:
+            skipped.append((provider, missing))
+        else:
+            valid.append(provider)
+    return valid, skipped
+
+
+def _generate_setup_container_sh(manifest: Manifest) -> str:
+    """Generate a standalone POSIX shell script for container-side setup."""
+    return textwrap.dedent("""\
+        #!/bin/sh
+        # setup-container.sh — generated by `caw auth setup`
+        # Sets up credential copies, config copies, and an inotify-based
+        # bidirectional credential sync guard inside a container.
+        # Usage: setup-container.sh <mount_point> <container_home> <username>
+        set -e
+
+        MOUNT_POINT="${1:-/tmp/caw_auth}"
+        CONTAINER_HOME="${2:-/home/playground}"
+        USERNAME="${3:-playground}"
+
+        MANIFEST="$MOUNT_POINT/manifest.json"
+        GUARD_PAIRS="/tmp/_caw_guard_pairs"
+        GUARD_PID_FILE="/tmp/caw_credential_guard.pid"
+
+        if [ ! -f "$MANIFEST" ]; then
+            echo "[setup-container] ERROR: manifest.json not found at $MANIFEST"
+            exit 1
+        fi
+
+        echo "[setup-container] Setting up auth files from $MOUNT_POINT..."
+
+        # Clean up guard pairs file from any previous run
+        rm -f "$GUARD_PAIRS"
+
+        # Parse manifest with jq and process each file
+        jq -r '
+            .agents | to_entries[] | .value.files[] |
+            [.src, .container_target, .strategy, .mode] | @tsv
+        ' "$MANIFEST" | while IFS=$(printf '\\t') read -r src target strategy mode; do
+            target_path="$CONTAINER_HOME/$target"
+            source_path="$MOUNT_POINT/$src"
+
+            # Create parent directory
+            target_dir=$(dirname "$target_path")
+            mkdir -p "$target_dir"
+
+            if [ "$strategy" = "symlink" ]; then
+                # Credential files: copy (not symlink) so container user can read 0600 files.
+                # The bind-mounted source is owned by the host UID and is 0600, but the
+                # setup script runs as root so it can read it.  We copy into the container
+                # user's home and record the pair for the inotify guard.
+                rm -f "$target_path"
+                cp "$source_path" "$target_path"
+                chmod "$mode" "$target_path"
+                chown "$USERNAME:$USERNAME" "$target_dir" 2>/dev/null || true
+                chown "$USERNAME:$USERNAME" "$target_path" 2>/dev/null || true
+                echo "[setup-container]   copy (credential): $target (mode $mode)"
+                # Record source:local pair for the guard
+                echo "$source_path|$target_path|$mode" >> "$GUARD_PAIRS"
+            elif [ "$strategy" = "copy" ]; then
+                cp "$source_path" "$target_path"
+                chmod "$mode" "$target_path"
+                chown "$USERNAME:$USERNAME" "$target_dir" 2>/dev/null || true
+                chown "$USERNAME:$USERNAME" "$target_path" 2>/dev/null || true
+                echo "[setup-container]   copy (config): $target (mode $mode)"
+            fi
+        done
+
+        # -------------------------------------------------------------------
+        # Credential guard — bidirectional sync via inotify
+        # -------------------------------------------------------------------
+
+        _caw_credential_guard() {
+            PAIRS_FILE="$1"
+            OWNER="$2"
+
+            # Build inotifywait watch list: unique directories from both sides
+            WATCH_DIRS=""
+            while IFS='|' read -r src local _mode; do
+                src_dir=$(dirname "$src")
+                local_dir=$(dirname "$local")
+                # Deduplicate by checking if already present
+                case "$WATCH_DIRS" in
+                    *"$src_dir"*) ;;
+                    *) WATCH_DIRS="$WATCH_DIRS $src_dir" ;;
+                esac
+                case "$WATCH_DIRS" in
+                    *"$local_dir"*) ;;
+                    *) WATCH_DIRS="$WATCH_DIRS $local_dir" ;;
+                esac
+            done < "$PAIRS_FILE"
+
+            echo "[credential-guard] Watching directories:$WATCH_DIRS"
+
+            while true; do
+                # shellcheck disable=SC2086
+                inotifywait -m -q -e close_write $WATCH_DIRS 2>/dev/null | while read -r dir event filename; do
+                    # dir has a trailing slash from inotifywait
+                    changed_path="${dir}${filename}"
+
+                    while IFS='|' read -r src local mode; do
+                        if [ "$changed_path" = "$src" ]; then
+                            # Source (bind mount) changed — sync to local copy
+                            src_hash=$(md5sum "$src" 2>/dev/null | cut -d' ' -f1)
+                            local_hash=$(md5sum "$local" 2>/dev/null | cut -d' ' -f1)
+                            if [ "$src_hash" != "$local_hash" ]; then
+                                cp "$src" "$local"
+                                chmod "$mode" "$local"
+                                chown "$OWNER:$OWNER" "$local" 2>/dev/null || true
+                                echo "[credential-guard] synced $src -> $local"
+                            fi
+                        elif [ "$changed_path" = "$local" ]; then
+                            # Local copy changed — sync back to bind mount
+                            src_hash=$(md5sum "$src" 2>/dev/null | cut -d' ' -f1)
+                            local_hash=$(md5sum "$local" 2>/dev/null | cut -d' ' -f1)
+                            if [ "$src_hash" != "$local_hash" ]; then
+                                cp "$local" "$src"
+                                echo "[credential-guard] synced $local -> $src"
+                            fi
+                        fi
+                    done < "$PAIRS_FILE"
+                done
+                echo "[credential-guard] inotifywait exited, restarting in 2s..."
+                sleep 2
+            done
+        }
+
+        # Start the guard if there are credential pairs to watch
+        # Skip credential guard when using Bedrock (no credential sync needed)
+        if [ "${CLAUDE_CODE_USE_BEDROCK:-0}" = "1" ]; then
+            echo "[setup-container] Bedrock mode — skipping credential guard."
+        elif [ -f "$GUARD_PAIRS" ] && [ -s "$GUARD_PAIRS" ]; then
+            # Install inotify-tools if not present
+            if ! command -v inotifywait >/dev/null 2>&1; then
+                echo "[setup-container] Installing inotify-tools..."
+                if apt-get update -qq >/dev/null 2>&1 && apt-get install -y -qq inotify-tools >/dev/null 2>&1; then
+                    echo "[setup-container] inotify-tools installed."
+                else
+                    echo "[setup-container] WARNING: Failed to install inotify-tools. Credential guard will not run."
+                    echo "[setup-container] Auth setup complete (without credential guard)."
+                    exit 0
+                fi
+            fi
+
+            # Kill any previous guard
+            if [ -f "$GUARD_PID_FILE" ]; then
+                old_pid=$(cat "$GUARD_PID_FILE" 2>/dev/null)
+                if [ -n "$old_pid" ] && kill -0 "$old_pid" 2>/dev/null; then
+                    kill "$old_pid" 2>/dev/null || true
+                    echo "[setup-container] Stopped previous credential guard (PID $old_pid)."
+                fi
+                rm -f "$GUARD_PID_FILE"
+            fi
+
+            _caw_credential_guard "$GUARD_PAIRS" "$USERNAME" &
+            echo $! > "$GUARD_PID_FILE"
+            echo "[setup-container] Credential guard started (PID $(cat "$GUARD_PID_FILE"))."
+        fi
+
+        echo "[setup-container] Auth setup complete."
+    """)
+
+
+def setup(
+    agents: list[str] | None = None,
+    source_home: str | None = None,
+    force: bool = False,
+    dest_dir: str | Path | None = None,
+) -> Path:
+    """Collect credentials from host into an auth directory and link them.
+
+    Args:
+        agents: List of agent names, or None / ["all"] for all agents.
+        source_home: Home directory to read credentials from.
+        force: Overwrite existing auth dir without prompting.
+        dest_dir: Custom destination directory. Defaults to ~/.caw/auth/.
+
+    Returns:
+        Path to the auth directory.
+    """
+    src_home = Path(source_home) if source_home else Path.home()
+    auth_dir = Path(dest_dir) if dest_dir else AUTH_DIR
+
+    console.print(f"[bold]Collecting credentials into {auth_dir}/[/bold]\n")
+
+    # Resolve providers
+    selected = _resolve_providers(agents or ["all"])
+
+    # Validate
+    valid_providers, skipped_providers = _validate_providers(selected, src_home)
+
+    if not valid_providers:
+        console.print("[red]Error: No valid agent credentials found.[/red]")
+        for provider, missing in skipped_providers:
+            console.print(f"  [dim]{provider.name}:[/dim] missing {', '.join(missing)}")
+        raise SystemExit(1)
+
+    # Warn about missing agents
+    if skipped_providers:
+        for provider, missing in skipped_providers:
+            console.print(f"[yellow]Warning: {provider.name} credentials not found:[/yellow] {', '.join(missing)}")
+        console.print()
+
+    # Show what we'll process
+    names = [p.name for p in valid_providers]
+    console.print(f"[dim]Agents:[/dim] {', '.join(names)}\n")
+
+    # Describe each provider
+    for provider in valid_providers:
+        desc = provider.describe(src_home)
+        console.print(f"[bold]{provider.name}:[/bold] {desc}")
+    console.print()
+
+    # Collect files from all providers
+    all_files: list[CollectedFile] = []
+    manifest = Manifest.create(host_home=str(src_home))
+
+    for provider in valid_providers:
+        console.print(f"[bold]Collecting {provider.name} files...[/bold]")
+        collected = provider.collect(src_home)
+        all_files.extend(collected)
+
+        # Build manifest entry
+        agent_manifest = AgentManifest(files=[cf.manifest_file for cf in collected])
+        manifest.agents[provider.name] = agent_manifest
+
+    # Write everything
+    if auth_dir.exists():
+        import shutil
+
+        # Preserve .backups directory across re-collections
+        backups = auth_dir / ".backups"
+        backup_tmp = None
+        if backups.exists():
+            backup_tmp = auth_dir.parent / ".backups_tmp"
+            if backup_tmp.exists():
+                shutil.rmtree(backup_tmp)
+            backups.rename(backup_tmp)
+
+        shutil.rmtree(auth_dir)
+        auth_dir.mkdir(parents=True)
+
+        if backup_tmp and backup_tmp.exists():
+            backup_tmp.rename(auth_dir / ".backups")
+    else:
+        auth_dir.mkdir(parents=True)
+
+    # Write collected files
+    for cf in all_files:
+        out_path = auth_dir / cf.manifest_file.src
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_bytes(cf.content)
+        out_path.chmod(int(cf.manifest_file.mode, 8))
+
+    # Write manifest
+    manifest.save(auth_dir / "manifest.json")
+
+    # Write setup-container.sh
+    setup_script = auth_dir / "setup-container.sh"
+    setup_script.write_text(_generate_setup_container_sh(manifest))
+    setup_script.chmod(0o755)
+
+    # Set directory permissions
+    for d in auth_dir.rglob("*"):
+        if d.is_dir():
+            d.chmod(0o755)
+
+    console.print("\n[bold green]Done![/bold green]")
+    console.print(f"Auth files written to: {auth_dir}")
+    console.print("\n[dim]Contents:[/dim]")
+    for cf in all_files:
+        strategy = cf.manifest_file.strategy
+        ftype = cf.manifest_file.type
+        console.print(f"  [dim]{cf.manifest_file.src}[/dim]  ({ftype}, {strategy})")
+    console.print("  [dim]manifest.json[/dim]")
+    console.print("  [dim]setup-container.sh[/dim]")
+
+    # Link credential files
+    console.print()
+    from .linker import link as do_link
+
+    do_link(agents=agents, force=force, auth_dir=auth_dir)
+
+    return auth_dir