hubmanager/CLAUDE.md

hubmanager — AI Session Context

This file provides context for AI assistants working on this project.

Project Summary

hubmanager is a single-file Bash CLI tool to manage Docker Registry images remotely. It supports both Docker Hub and any self-hosted Docker Registry v2 API, with automatic authentication detection (bearer token or HTTP basic auth).

---

What Changed (Session 2026-03-01b)

Passphrase caching via Linux keyring (v0.3.0)

Added cross-invocation master passphrase caching using the Linux kernel keyring (keyctl from keyutils). keyctl is an optional dependency — if not installed, behaviour is unchanged (prompt every time).

New functions (Encryption helpers section):

Function	Purpose
_keyring_available()	Returns 0 if keyctl is installed
_keyring_get()	Read cached passphrase from user keyring; return 1 if missing/expired
_keyring_set(pass, ttl)	Store passphrase in keyring with TTL
_keyring_clear()	Revoke the cached key

New subcommands:

Command	Purpose
unlock	Prompt for passphrase and cache in keyring (useful before scripting)
lock	Clear cached passphrase from keyring immediately

New global option: --cache-timeout <seconds> (default 300 / 5 min). Also configurable via CACHE_TIMEOUT=<seconds> in hubmanager.conf.

New constants: HM_KEYRING_KEY, HM_KEYRING_DEFAULT_TIMEOUT. New global variable: HM_CACHE_TIMEOUT.

Modified functions:

• _prompt_master_pass() — checks keyring before prompting; stores after prompt
• _prompt_set_master_pass() — stores in keyring after confirmation

Version bump: 0.2.1 → 0.3.0

---

What Changed (Session 2026-03-01)

Bug fixes and improvements (v0.2.1)

1. Global arg parsing fix (parse_global_args): global flags like --user, --registry, --password placed after the subcommand name (e.g. hubmanager login --user ...) were not recognised. The * catch-all used remaining+=("$@"); break which stopped parsing. Changed to remaining+=("$1"); shift so parsing continues through all arguments.

2. Subshell variable fix (raw_http / registry_request): HM_LAST_HTTP_CODE and HM_LAST_HEADERS_FILE were set inside raw_http, but callers used body=$(raw_http ...) which runs in a subshell — variables set inside never propagated back. Fixed by adding two global temp files (HM_HTTP_CODE_FILE, HM_HEADERS_REF_FILE) that raw_http writes to; callers read them back after the subshell returns.

3. Config inline-comment stripping removed (load_config): the parser stripped everything after the first # in config values (value="${value%%#*}"), which could truncate base64 ciphertext containing #. Removed since comment-only lines are already skipped.

4. Decrypt newline fix (_decrypt_value): printf '%s' piped ciphertext to openssl enc -d -a without a trailing newline, causing openssl to fail with "error reading input file". Changed to printf '%s\n'.

5. Config path moved: ~/.hubmanager.conf → ~/.config/hubmanager.conf. login --save now runs mkdir -p on the parent directory before writing.

6. README: added "Cleaning up empty repositories" section explaining the server-side steps needed to remove empty repos (registry v2 API limitation).

New global variables

Variable	Purpose
HM_HTTP_CODE_FILE	Temp file for HTTP code (survives subshells)
HM_HEADERS_REF_FILE	Temp file for headers path (survives subshells)

---

What Changed (Session 2026-02-21)

Encrypted config values (--encrypt)

Added openssl AES-256-CBC encryption for passwords stored in the config file. openssl is an optional dependency — it is only required when enc: prefixed values are present in the config, or when login --encrypt is used.

New functions (Encryption helpers section):

Function	Purpose
_require_openssl()	Die with a clear message if openssl is not installed
_prompt_master_pass()	Prompt once per session via /dev/tty; cache in HM_MASTER_PASS
_prompt_set_master_pass()	Prompt + confirm a new passphrase (used by login --encrypt)
_encrypt_value(plaintext)	AES-256-CBC encrypt → base64 ciphertext (no newlines)
_decrypt_value(ciphertext)	Decrypt base64 ciphertext → plaintext; die on wrong passphrase

Passphrase security: passed to openssl via a mktemp file (-pass file:) to avoid exposure in the process argument list (ps aux). The temp file is registered in HM_TMPFILES and removed on exit.

Config format: encrypted values use an enc: prefix, e.g.:

PASSWORD=enc:U2FsdGVkX1+...base64ciphertext...
REGISTRY_PROD_PASSWORD=enc:U2FsdGVkX1+...

Both load_config() and resolve_registry_alias() detect the prefix and call _decrypt_value transparently.

Version bump: 0.1.0 → 0.2.0

---

What Was Built (Session 2025-02-21)

Primary file

hubmanager — executable Bash script, ~680 lines, no mandatory dependencies beyond curl, jq, Bash 4+. openssl is required only when encrypted config values are used.

Subcommands implemented

Command	Description
login	Test credentials against a registry; --save writes to ~/.config/hubmanager.conf
list	List repositories (_catalog for self-hosted; Hub REST API for Docker Hub)
tags	List tags for an image with pagination
inspect	Show manifest digest, size, OS/arch, layers, labels; multi-arch support
delete	Resolve tag → digest → DELETE; requires confirmation or --yes
copy	Copy/retag within or across registries; blob mount for same-registry retag
prune	Delete outdated tags sorted by image creation date
unlock	Cache master passphrase in kernel keyring (requires keyctl)
lock	Clear cached master passphrase from keyring

Supporting files

• PLAN.md — implementation plan written before coding
• README.md — full user-facing documentation with examples
• tests/fixtures/ — sample JSON responses for testing (token, catalog, tags, manifests, config blob)

---

Architecture

Single-file, section-based layout

#!/usr/bin/env bash
set -euo pipefail
# --- Constants ---
# --- Global state ---
# --- Output / Formatting helpers ---
# --- Dependency check ---
# --- Encryption helpers ---   _encrypt_value(), _decrypt_value(), _prompt_master_pass()
#                              _keyring_get(), _keyring_set(), _keyring_clear()
# --- Config loading ---
# --- HTTP helpers ---         raw_http(), get_response_header()
# --- Authentication ---       probe_registry_auth(), get_bearer_token(), make_auth_header()
# --- Registry request ---     registry_request()  ← main HTTP wrapper
# --- Subcommands ---          cmd_login/unlock/lock/list/tags/inspect/delete/copy/prune
# --- Global arg parsing ---   parse_global_args()
# --- Main dispatcher ---      main()
main "$@"

Key design decisions

1. raw_http METHOD URL [curl-args] — thin curl wrapper. Writes headers to a temp file (HM_LAST_HEADERS_FILE), sets HM_LAST_HTTP_CODE, outputs body to stdout.

2. registry_request METHOD REGISTRY PATH [options] — higher-level wrapper that:

   • Probes auth mode via probe_registry_auth (result cached per registry)
   • Fetches and caches bearer tokens per "registry|scope" key
   • Retries once on 401 using the challenge scope from WWW-Authenticate
   • Calls _handle_http_error on non-2xx (unless --no-die)

3. make_auth_header REGISTRY SCOPE [USER] [PASS] — returns the correct Authorization: header string for either bearer or basic auth.

4. Authentication flow:

   • GET /v2/ → parse WWW-Authenticate → detect bearer or basic
   • Bearer: GET <realm>?scope=S&service=S with -u user:pass → cache .token
   • Basic: construct Authorization: Basic <base64> directly
   • Tokens cached in HM_TOKEN_CACHE["registry|scope"] with epoch expiry

5. Docker Hub differences:

   • list uses hub.docker.com/v2/repositories/<user>/ (not _catalog)
   • delete and prune are blocked (Hub v2 API doesn't support deletion)
   • Hub REST API uses a separate JWT from hub.docker.com/v2/users/login

6. Config file (~/.config/hubmanager.conf):

   • KEY=VALUE format, parsed with while IFS='=' read (not source)
   • Supports named registry aliases: REGISTRY_<ALIAS>_URL/USERNAME/PASSWORD
   • Aliases are resolved in resolve_registry_alias() before any operations

7. Prune logic: fetches all tags → filters by --exclude pattern → inspects each tag's config blob for creation date → sorts oldest-first → deletes oldest (beyond --keep count or before --older-than days). Supports --dry-run.

8. Copy blob transfer:

   • Same registry, different repos → attempt cross-repo blob mount (POST ?mount=)
   • Blob already at destination (HEAD returns 200) → skip
   • Otherwise → download to temp file → POST initiate upload → PUT with digest

9. Encrypted config values (v0.2.0):

   • login --save --encrypt prompts for a master passphrase (with confirmation), encrypts the password with openssl enc -aes-256-cbc -pbkdf2 -a, and writes PASSWORD=enc:<b64>.
   • Passphrase is passed to openssl via a temp file (-pass file:) — never via argv or env.
   • load_config and resolve_registry_alias both check for the enc: prefix and call _decrypt_value, which triggers _prompt_master_pass (once per session, cached in HM_MASTER_PASS).
   • openssl is an optional dependency: not checked at startup, only on first enc: encounter.

10. Passphrase caching (v0.3.0):

    • Uses Linux kernel keyring (keyctl from keyutils) to cache the master passphrase across invocations with a configurable TTL (default 300s / 5 min).
    • _prompt_master_pass() checks keyring before prompting; stores after prompt.
    • keyctl is optional: if not installed, each invocation prompts as before (no errors).
    • unlock pre-caches the passphrase; lock clears it immediately.
    • TTL configurable via --cache-timeout <seconds> flag or CACHE_TIMEOUT config key.

---

Global Variables (key ones)

Variable	Purpose
HM_REGISTRY	Active registry URL (no trailing slash)
HM_USERNAME / HM_PASSWORD	Active credentials
HM_CONFIG_FILE	Path to config file
HM_OPT_JSON/VERBOSE/QUIET/NO_COLOR	Output flags
HM_AUTH_MODE["registry"]	bearer, basic, or none
HM_AUTH_REALM["registry"]	Bearer token endpoint URL
HM_TOKEN_CACHE["registry|scope"]	Cached bearer token
HM_TOKEN_EXPIRY["registry|scope"]	Token expiry (epoch seconds)
HM_MASTER_PASS	Master passphrase for enc: config values (session-cached)
HM_CACHE_TIMEOUT	Keyring cache TTL in seconds (default 300)
HM_LAST_HTTP_CODE	HTTP status of most recent request
HM_LAST_HEADERS_FILE	Temp file path with response headers
HM_TMPFILES	Array of temp files, cleaned up via trap EXIT
MANIFEST_ACCEPT_HEADERS	Array of -H Accept: args for all manifest types

---

Adding a New Subcommand

1. Write a cmd_<name>() function following the same pattern:

   • Parse args with a while case loop; handle --help
   • Set HM_REGISTRY default if empty
   • Use registry_request for API calls
   • Check HM_OPT_JSON and branch for table vs. JSON output

2. Add it to the case block in main():

   newcmd) cmd_newcmd "$@" ;;
   

3. Add it to show_usage().

4. Run shellcheck hubmanager — it must pass with zero warnings.

---

Exit Codes

Code	Meaning
0	Success
1	General / usage error (die)
2	Authentication failure (die_auth)
3	Not found / 404 (die_notfound)
4	Permission denied / 403 (die_permission)
5	Registry server error (die_server)
6	Network error (die_network)
7	Operation not supported (die_notsup)

---

Known Limitations / Future Work

• Garbage collection after delete/prune: the registry only frees disk space after running registry garbage-collect. This tool does not trigger GC; it must be run separately on the registry host.
• Docker Hub rate limits: the inspect-per-tag loop in prune makes one API call per tag, which can hit pull rate limits on Docker Hub (prune is blocked on Hub anyway).
• Token scope granularity: the retry-on-401 flow handles most scope mismatches, but registries that require compound scopes (e.g. pull,push together) may need explicit --scope passing inside registry_request calls.
• No bats tests yet: tests/fixtures/ contains sample API responses. Wire up bats-core tests that mock curl with a shell function and feed fixture data.