browser-automation-skill 0.71.0

package/scripts/browser-baseline.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# scripts/browser-baseline.sh — named-blessed-capture management. Phase 9
+# part 1-v (CLOSES Phase 9).
+#
+# Sub-modes:
+#   save <capture-id> --as NAME      — set is_baseline:true; write baselines.json entry
+#   list                              — emit one baseline_row per entry
+#   remove <NAME>                     — clear is_baseline; splice baselines.json
+#                                       (does NOT delete the capture dir; use
+#                                        history clear for that)
+#
+# Per locked decision B1: thin wrapper over Phase 7's meta.is_baseline:true.
+# capture_prune already honors the skip-rule (landed in 7-1-v as forward-compat
+# for Phase 9). NO new prune logic here.
+
+set -euo pipefail
+IFS=$'\n\t'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPTS_DIR="${SCRIPT_DIR}"
+export SCRIPTS_DIR
+
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/output.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/output.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+readonly BASELINES_FILE="${BROWSER_SKILL_HOME}/baselines.json"
+
+# Lazy-create baselines.json on first save (mode 0600).
+_baseline_init_file() {
+  if [ ! -f "${BASELINES_FILE}" ]; then
+    jq -nc '{schema_version: 1, baselines: []}' > "${BASELINES_FILE}"
+    chmod 600 "${BASELINES_FILE}"
+  fi
+}
+
+sub_mode="${1:-}"
+[ -n "${sub_mode}" ] || die "${EXIT_USAGE_ERROR}" "browser-baseline: missing sub-mode (save / list / remove)"
+shift
+
+case "${sub_mode}" in
+  save)
+    capture_id="${1:-}"
+    [ -n "${capture_id}" ] || die "${EXIT_USAGE_ERROR}" "baseline save: missing <capture-id>"
+    shift
+    name=""
+    while [ "$#" -gt 0 ]; do
+      case "$1" in
+        --as) name="$2"; shift 2 ;;
+        *)    die "${EXIT_USAGE_ERROR}" "baseline save: unknown flag '$1'" ;;
+      esac
+    done
+    [ -n "${name}" ] || die "${EXIT_USAGE_ERROR}" "baseline save: --as NAME is required"
+
+    meta="${CAPTURES_DIR}/${capture_id}/meta.json"
+    [ -f "${meta}" ] || die "${EXIT_USAGE_ERROR}" "baseline save: no such capture '${capture_id}'"
+
+    # Set is_baseline:true on meta.json (Phase 7's prune skip-rule honors this).
+    tmp="${meta}.tmp.$$"
+    jq '.is_baseline = true' "${meta}" > "${tmp}"
+    chmod 600 "${tmp}"
+    mv "${tmp}" "${meta}"
+
+    # Append entry to baselines.json.
+    _baseline_init_file
+    saved_at="$(now_iso)"
+    summary_obj="$(jq -c '{verb, flow_name, step_count}' "${meta}")"
+    tmp="${BASELINES_FILE}.tmp.$$"
+    jq -c \
+      --arg name "${name}" \
+      --arg cid "${capture_id}" \
+      --arg ts "${saved_at}" \
+      --argjson sum "${summary_obj}" \
+      '.baselines += [{name: $name, capture_id: $cid, saved_at: $ts, summary: $sum}]' \
+      "${BASELINES_FILE}" > "${tmp}"
+    chmod 600 "${tmp}"
+    mv "${tmp}" "${BASELINES_FILE}"
+
+    emit_summary verb=baseline tool=none why=save status=ok mode=save \
+      capture_id="${capture_id}" name="${name}"
+    exit 0
+    ;;
+
+  list)
+    _baseline_init_file
+    total=0
+    while IFS= read -r row; do
+      [ -z "${row}" ] && continue
+      printf '%s' "${row}" | jq -c '. + {event: "baseline_row"}'
+      total=$((total + 1))
+    done <<< "$(jq -c '.baselines[]?' "${BASELINES_FILE}")"
+    emit_summary verb=baseline tool=none why=list status=ok mode=list total="${total}"
+    exit 0
+    ;;
+
+  remove)
+    name="${1:-}"
+    [ -n "${name}" ] || die "${EXIT_USAGE_ERROR}" "baseline remove: missing <name>"
+    _baseline_init_file
+    # Find the capture-id for the given name.
+    capture_id="$(jq -r --arg n "${name}" '.baselines[] | select(.name == $n) | .capture_id' "${BASELINES_FILE}")"
+    [ -n "${capture_id}" ] || die "${EXIT_USAGE_ERROR}" "baseline remove: no such baseline '${name}'"
+
+    # Clear is_baseline on meta.json (if capture still exists; fail-soft).
+    meta="${CAPTURES_DIR}/${capture_id}/meta.json"
+    if [ -f "${meta}" ]; then
+      tmp="${meta}.tmp.$$"
+      jq '.is_baseline = false' "${meta}" > "${tmp}"
+      chmod 600 "${tmp}"
+      mv "${tmp}" "${meta}"
+    fi
+
+    # Splice baselines.json.
+    tmp="${BASELINES_FILE}.tmp.$$"
+    jq -c --arg n "${name}" '.baselines |= map(select(.name != $n))' \
+      "${BASELINES_FILE}" > "${tmp}"
+    chmod 600 "${tmp}"
+    mv "${tmp}" "${BASELINES_FILE}"
+
+    emit_summary verb=baseline tool=none why=remove status=ok mode=remove \
+      capture_id="${capture_id}" name="${name}"
+    exit 0
+    ;;
+
+  *)
+    die "${EXIT_USAGE_ERROR}" "browser-baseline: unknown sub-mode '${sub_mode}' (use save / list / remove)"
+    ;;
+esac

package/scripts/browser-click.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# scripts/browser-click.sh — click an element by --ref eN or --selector CSS.
+# Usage: bash scripts/browser-click.sh [--site NAME] [--tool NAME] [--dry-run]
+#                                      [--raw] (--ref eN | --selector CSS)
+
+set -euo pipefail
+IFS=$'\n\t'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/output.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/output.sh"
+# shellcheck source=lib/router.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/router.sh"
+# shellcheck source=lib/verb_helpers.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/verb_helpers.sh"
+# shellcheck source=lib/stats.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/stats.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+parse_verb_globals "$@"
+
+# Resolve site/session → BROWSER_SKILL_STORAGE_STATE (no-op if neither set).
+# Router's rule_session_required reads the env var to prefer playwright-lib.
+resolve_session_storage_state
+
+ref="" selector=""
+verb_argv=()
+i=0
+while [ "${i}" -lt "${#REMAINING_ARGV[@]}" ]; do
+  case "${REMAINING_ARGV[i]}" in
+    --ref)
+      ref="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${ref}" ] || die "${EXIT_USAGE_ERROR}" "--ref requires a value"
+      verb_argv+=(--ref "${ref}")
+      i=$((i + 2))
+      ;;
+    --selector)
+      selector="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${selector}" ] || die "${EXIT_USAGE_ERROR}" "--selector requires a value"
+      verb_argv+=(--selector "${selector}")
+      i=$((i + 2))
+      ;;
+    *)
+      verb_argv+=("${REMAINING_ARGV[i]}")
+      i=$((i + 1))
+      ;;
+  esac
+done
+
+if [ -n "${ref}" ] && [ -n "${selector}" ]; then
+  die "${EXIT_USAGE_ERROR}" "--ref and --selector are mutually exclusive"
+fi
+if [ -z "${ref}" ] && [ -z "${selector}" ]; then
+  die "${EXIT_USAGE_ERROR}" "click requires --ref eN or --selector CSS"
+fi
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  ok "dry-run: would click ${ref:-${selector}}"
+  emit_summary verb=click tool=none why=dry-run status=ok ref="${ref}" selector="${selector}" dry_run=true
+  exit 0
+fi
+
+picked="$(pick_tool click "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+stats_t0="$(now_ms)"
+set +e
+adapter_out="$(invoke_with_retry click "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+# Phase 12 part 1: per-action telemetry. No natural observed value for click;
+# observed=adapter_out so element_value post-conditions can match against any
+# response payload the adapter emits.
+BROWSER_STATS_OBSERVED="${adapter_out}" \
+  stats_run_adapter_emit \
+    "click" "${tool_name}" "${stats_t0}" "${adapter_rc}" "${adapter_out}" "" \
+    -- "${verb_argv[@]}" || true
+
+[ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  emit_summary verb=click tool="${tool_name}" why="${why}" status=ok ref="${ref}" selector="${selector}"
+  exit 0
+fi
+emit_summary verb=click tool="${tool_name}" why="${why}" status=error ref="${ref}" selector="${selector}"
+exit "${adapter_rc}"

package/scripts/browser-creds-add.sh

@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+# creds-add — register a credential. Smart per-OS backend select; AP-7 strict
+# (password ALWAYS via stdin, never argv). Metadata in ${CREDENTIALS_DIR}/
+# <name>.json mode 0600; secret payload via backend (plaintext: same dir,
+# <name>.secret mode 0600; keychain/libsecret: OS vault).
+set -euo pipefail
+IFS=$'\n\t'
+umask 077
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/site.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/site.sh"
+# shellcheck source=lib/credential.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/credential.sh"
+# shellcheck source=lib/secret_backend_select.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/secret_backend_select.sh"
+init_paths
+
+site=""
+as=""
+account=""
+backend=""
+auto_relogin="true"
+auth_flow="single-step-username-password"
+enable_totp=0
+yes_totp=0
+totp_secret_stdin=0
+read_stdin=0
+dry_run=0
+yes_plaintext=0
+
+usage() {
+  cat <<'USAGE'
+Usage: creds-add --site SITE --as CRED_NAME --password-stdin [options]
+
+  --site SITE              site profile name (must exist)
+  --as CRED_NAME           credential name (filename, must be safe)
+  --account ACCOUNT        account/email value (default: "<site>@example.com")
+  --backend BACKEND        keychain | libsecret | plaintext
+                            (default: smart auto-detect per OS — keychain on
+                             Darwin, libsecret on Linux when secret-tool is
+                             reachable, plaintext fallback otherwise)
+  --auto-relogin BOOL      true | false (default: true; relogin via login --auto
+                            requires auth_flow=single-step-username-password)
+  --auth-flow FLOW         single-step-username-password | multi-step-username-
+                            password | username-only | custom (default:
+                            single-step-username-password). Only single-step is
+                            supported by login --auto today; others persist
+                            metadata for documentation but require --interactive
+                            for relogin.
+  --enable-totp            mark this credential as TOTP-enabled (phase-5 part
+                            4-i: plumbing only — codegen/replay/rotation land
+                            in parts 4-ii/iii/iv). Requires --yes-i-know-totp
+                            (typed-phrase ack) and forbids --backend plaintext
+                            (TOTP shared secrets MUST go through OS keychain /
+                            libsecret per parent spec §1).
+  --yes-i-know-totp        acknowledgment for --enable-totp.
+  --totp-secret-stdin      read base32 TOTP shared secret from stdin AFTER
+                            the password (separated by NUL byte). Stored at
+                            the <name>:totp backend slot. Requires
+                            --enable-totp. Phase-5 part 4-ii.
+  --password-stdin         REQUIRED — read password from stdin (one line);
+                            this is the ONLY password-input path. AP-7
+                            forbids accepting the password as an argv arg.
+  --yes-i-know-plaintext   acknowledge that the plaintext backend stores
+                            the secret on disk. Required on the FIRST
+                            plaintext credential add; subsequent adds skip
+                            (a marker file at ${CREDENTIALS_DIR}/.plaintext-
+                            acknowledged tracks acknowledgment).
+  --dry-run                print planned action; write nothing
+  -h, --help               this message
+
+Examples:
+  printf 'mypass' | creds-add --site prod --as prod--admin --password-stdin
+  printf 'mypass' | creds-add --site prod --as prod--admin --backend keychain --password-stdin
+USAGE
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --site)            site="$2";          shift 2 ;;
+    --as)              as="$2";            shift 2 ;;
+    --account)         account="$2";       shift 2 ;;
+    --backend)         backend="$2";       shift 2 ;;
+    --auto-relogin)    auto_relogin="$2";  shift 2 ;;
+    --auth-flow)       auth_flow="$2";     shift 2 ;;
+    --enable-totp)     enable_totp=1;      shift ;;
+    --yes-i-know-totp) yes_totp=1;         shift ;;
+    --totp-secret-stdin) totp_secret_stdin=1; shift ;;
+    --password-stdin)  read_stdin=1;       shift ;;
+    --yes-i-know-plaintext) yes_plaintext=1; shift ;;
+    --dry-run)         dry_run=1;          shift ;;
+    -h|--help)         usage; exit 0 ;;
+    *)                 die "${EXIT_USAGE_ERROR}" "unknown flag: $1" ;;
+  esac
+done
+
+[ -n "${site}" ]        || { usage; die "${EXIT_USAGE_ERROR}" "--site is required"; }
+[ -n "${as}" ]          || { usage; die "${EXIT_USAGE_ERROR}" "--as is required"; }
+[ "${read_stdin}" = "1" ] || { usage; die "${EXIT_USAGE_ERROR}" "--password-stdin is required (passwords MUST come via stdin per AP-7)"; }
+
+case "${auto_relogin}" in
+  true|false) ;;
+  *) die "${EXIT_USAGE_ERROR}" "--auto-relogin must be 'true' or 'false' (got: ${auto_relogin})" ;;
+esac
+
+case "${auth_flow}" in
+  single-step-username-password|multi-step-username-password|username-only|custom) ;;
+  *) die "${EXIT_USAGE_ERROR}" "--auth-flow must be one of {single-step-username-password, multi-step-username-password, username-only, custom} (got: ${auth_flow})" ;;
+esac
+
+# Phase 5 part 4-i: --enable-totp requires explicit ack + forbids plaintext.
+# Per parent spec §1, TOTP shared secrets are even more sensitive than
+# passwords (they generate codes for the lifetime of the secret).
+if [ "${enable_totp}" = "1" ] && [ "${yes_totp}" = "0" ]; then
+  die "${EXIT_USAGE_ERROR}" "--enable-totp requires --yes-i-know-totp (TOTP shared secrets are highly sensitive)"
+fi
+if [ "${totp_secret_stdin}" = "1" ] && [ "${enable_totp}" = "0" ]; then
+  die "${EXIT_USAGE_ERROR}" "--totp-secret-stdin requires --enable-totp"
+fi
+
+assert_safe_name "${as}" "credential-name"
+
+# Phase 5 part 4-ii: prevent collisions with internal TOTP slot names.
+# Internal slots use `<as>__totp` suffix; if a user picks a cred name ending
+# in `__totp`, that user's password slot would alias another cred's TOTP slot.
+case "${as}" in
+  *__totp) die "${EXIT_USAGE_ERROR}" "credential name '${as}' reserved suffix '__totp' (collides with TOTP slot of cred '${as%__totp}')" ;;
+esac
+[ -z "${account}" ] && account="${site}@example.com"
+
+if ! site_exists "${site}"; then
+  die "${EXIT_SITE_NOT_FOUND}" "site '${site}' not registered (try: add-site --name ${site} --url ...)"
+fi
+
+if credential_exists "${as}"; then
+  die "${EXIT_USAGE_ERROR}" "credential '${as}' already exists (run: creds-remove --as ${as} first)"
+fi
+
+# Resolve backend.
+if [ -z "${backend}" ]; then
+  backend="$(detect_backend)"
+fi
+case "${backend}" in
+  keychain|libsecret|plaintext) ;;
+  *) die "${EXIT_USAGE_ERROR}" "--backend must be one of {keychain, libsecret, plaintext} (got: ${backend})" ;;
+esac
+
+# Phase 5 part 4-i: TOTP-enabled creds MUST go through OS keychain / libsecret.
+# plaintext on-disk storage of a TOTP shared secret means anyone with read
+# access to the file can generate auth codes forever — that's worse than
+# plaintext password (passwords expire/rotate; TOTP secrets typically don't).
+if [ "${enable_totp}" = "1" ] && [ "${backend}" = "plaintext" ]; then
+  die "${EXIT_USAGE_ERROR}" "--enable-totp forbids --backend plaintext (TOTP secrets must go through keychain or libsecret)"
+fi
+
+# First-use plaintext gate (per parent spec §1: plaintext is paper security
+# without disk encryption — gate the first add behind an explicit ack).
+# Marker file at ${CREDENTIALS_DIR}/.plaintext-acknowledged (mode 0600)
+# tracks the user's acknowledgment; subsequent adds skip the gate silently.
+if [ "${backend}" = "plaintext" ]; then
+  plaintext_marker="${CREDENTIALS_DIR}/.plaintext-acknowledged"
+  if [ ! -f "${plaintext_marker}" ]; then
+    if [ "${yes_plaintext}" -ne 1 ]; then
+      die "${EXIT_USAGE_ERROR}" \
+        "first plaintext credential requires --yes-i-know-plaintext (or pre-create ${plaintext_marker}); plaintext stores the secret on disk and is paper security without disk encryption — see 'doctor' for FileVault/LUKS status"
+    fi
+    mkdir -p "${CREDENTIALS_DIR}"
+    chmod 700 "${CREDENTIALS_DIR}"
+    ( umask 077; : > "${plaintext_marker}" )
+    chmod 600 "${plaintext_marker}"
+  fi
+fi
+
+# Read stdin. When --totp-secret-stdin is set, stdin is `password\0totp_secret`
+# (NUL-separated, AP-7: secrets never on argv); otherwise it's just the password.
+# Bash `$(cat)` strips embedded NULs ("warning: ignored null byte"), so use
+# `read -r -d ''` which reads up to a NUL delimiter without losing bytes.
+totp_secret=""
+if [ "${totp_secret_stdin}" = "1" ]; then
+  IFS= read -r -d '' password || \
+    die "${EXIT_USAGE_ERROR}" "--totp-secret-stdin: stdin must be 'password\\0totp_secret' (no NUL found)"
+  # Second chunk: EOF-terminated (no trailing NUL required); `read` returns
+  # non-zero on EOF-before-delim but still populates the variable.
+  IFS= read -r -d '' totp_secret || true
+  if [ -z "${totp_secret}" ]; then
+    die "${EXIT_USAGE_ERROR}" "--totp-secret-stdin: stdin must be 'password\\0totp_secret' (got only one chunk)"
+  fi
+else
+  password="$(cat)"
+fi
+
+started_at_ms="$(now_ms)"
+
+if [ "${dry_run}" -eq 1 ]; then
+  ok "dry-run: would write ${CREDENTIALS_DIR}/${as}.{json,secret} via backend=${backend}"
+  duration_ms=$(( $(now_ms) - started_at_ms ))
+  summary_json verb=creds-add tool=none why=dry-run status=ok would_run=true \
+               credential="${as}" site="${site}" backend="${backend}" \
+               duration_ms="${duration_ms}"
+  exit "${EXIT_OK}"
+fi
+
+now_ts="$(now_iso)"
+totp_json="$([ "${enable_totp}" = "1" ] && printf 'true' || printf 'false')"
+meta_json="$(jq -nc \
+  --arg n "${as}" \
+  --arg s "${site}" \
+  --arg a "${account}" \
+  --arg b "${backend}" \
+  --argjson ar "${auto_relogin}" \
+  --arg af "${auth_flow}" \
+  --argjson tt "${totp_json}" \
+  --arg now "${now_ts}" \
+  '{
+    schema_version: 1,
+    name: $n,
+    site: $s,
+    account: $a,
+    backend: $b,
+    auth_flow: $af,
+    auto_relogin: $ar,
+    totp_enabled: $tt,
+    created_at: $now
+  }')"
+
+credential_save "${as}" "${meta_json}"
+
+# Pipe the password into the backend via stdin (AP-7 — never argv).
+printf '%s' "${password}" | credential_set_secret "${as}"
+
+# Phase 5 part 4-ii: store TOTP shared secret in the same backend at the
+# `<as>:totp` slot when --totp-secret-stdin was provided.
+if [ -n "${totp_secret}" ]; then
+  printf '%s' "${totp_secret}" | credential_set_totp_secret "${as}"
+fi
+
+if [ "${backend}" = "plaintext" ]; then
+  warn "credential '${as}' stored via plaintext backend at ${CREDENTIALS_DIR}/${as}.secret (mode 0600)"
+  warn "  ensure disk encryption is enabled (FileVault/LUKS) — see 'doctor'"
+fi
+
+ok "credential added: ${as} (site=${site}, backend=${backend})"
+
+duration_ms=$(( $(now_ms) - started_at_ms ))
+summary_json verb=creds-add tool=none why=register-credential status=ok \
+             credential="${as}" site="${site}" backend="${backend}" \
+             duration_ms="${duration_ms}"

package/scripts/browser-creds-list.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# creds-list — list registered credentials. Optional --site filter mirrors
+# list-sessions. Emits ONLY metadata (NEVER secret values; backend payloads
+# stay in their respective vaults).
+
+set -euo pipefail
+IFS=$'\n\t'
+umask 077
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/credential.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/credential.sh"
+init_paths
+
+site_filter=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --site)
+      site_filter="$2"; shift 2
+      ;;
+    -h|--help)
+      cat <<'USAGE'
+Usage: creds-list [--site NAME]
+
+  --site NAME    show only credentials bound to this site
+USAGE
+      exit 0
+      ;;
+    *) die "${EXIT_USAGE_ERROR}" "unknown flag: $1" ;;
+  esac
+done
+
+started_at_ms="$(now_ms)"
+
+rows='[]'
+count=0
+for name in $(credential_list_names); do
+  meta="$(credential_load "${name}" 2>/dev/null)" || continue
+  cred_site="$(printf '%s' "${meta}" | jq -r '.site // ""')"
+  if [ -n "${site_filter}" ] && [ "${cred_site}" != "${site_filter}" ]; then
+    continue
+  fi
+  rows="$(jq --arg n "${name}" --argjson m "${meta}" '
+    . + [{
+      credential:   $n,
+      site:         ($m.site // null),
+      account:      ($m.account // null),
+      backend:      ($m.backend // null),
+      auto_relogin: ($m.auto_relogin // null),
+      totp_enabled: ($m.totp_enabled // null),
+      created_at:   ($m.created_at // null)
+    }]' <<< "${rows}")"
+  count=$((count + 1))
+done
+
+duration_ms=$(( $(now_ms) - started_at_ms ))
+jq -cn --argjson r "${rows}" --argjson c "${count}" --argjson d "${duration_ms}" \
+  --arg sf "${site_filter}" \
+  '{verb: "creds-list", tool: "none",
+    why: (if $sf == "" then "list-all" else "list-by-site" end),
+    status: (if $c == 0 then "empty" else "ok" end),
+    site_filter: ($sf | if . == "" then null else . end),
+    count: $c, credentials: $r, duration_ms: $d}'

package/scripts/browser-creds-migrate.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# creds-migrate — move a credential from one backend to another. Fail-safe
+# ordering: writes to new backend BEFORE deleting from old, so a failed
+# new-backend write leaves the original credential intact.
+#
+# Inherits the first-use plaintext gate from creds-add: migrating TO plaintext
+# requires --yes-i-know-plaintext (or a pre-existing acknowledgment marker)
+# so users can't bypass the gate by going via creds-migrate.
+#
+# Privacy invariant: summary JSON NEVER contains the secret value.
+set -euo pipefail
+IFS=$'\n\t'
+umask 077
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/credential.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/credential.sh"
+init_paths
+
+name=""; to_backend=""; yes=0; yes_plaintext=0; dry_run=0
+
+usage() {
+  cat <<'USAGE'
+Usage: creds-migrate --as CRED_NAME --to BACKEND [options]
+
+  --as CRED_NAME            credential to migrate (required)
+  --to BACKEND              target: keychain | libsecret | plaintext (required)
+  --yes-i-know              skip the typed-name confirmation
+  --yes-i-know-plaintext    acknowledge plaintext storage; required when
+                            --to plaintext on a fresh box without the
+                            ${CREDENTIALS_DIR}/.plaintext-acknowledged marker
+  --dry-run                 print planned action; migrate nothing
+  -h, --help                this message
+
+Fail-safe: if the new-backend write fails (e.g. keychain unavailable), the
+original credential is left intact. If the old-backend delete fails AFTER a
+successful new-backend write, both backends transiently hold the secret —
+verb logs a warning, doesn't crash; you can manually clean via creds-remove
+on the old backend OR re-run creds-migrate to consolidate.
+USAGE
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --as)                   name="$2"; shift 2 ;;
+    --to)                   to_backend="$2"; shift 2 ;;
+    --yes-i-know)           yes=1; shift ;;
+    --yes-i-know-plaintext) yes_plaintext=1; shift ;;
+    --dry-run)              dry_run=1; shift ;;
+    -h|--help)              usage; exit 0 ;;
+    *)                      die "${EXIT_USAGE_ERROR}" "unknown flag: $1" ;;
+  esac
+done
+
+[ -n "${name}" ]       || { usage; die "${EXIT_USAGE_ERROR}" "--as is required"; }
+[ -n "${to_backend}" ] || { usage; die "${EXIT_USAGE_ERROR}" "--to is required"; }
+assert_safe_name "${name}" "credential-name"
+
+case "${to_backend}" in
+  keychain|libsecret|plaintext) ;;
+  *) die "${EXIT_USAGE_ERROR}" "--to must be one of {keychain, libsecret, plaintext} (got: ${to_backend})" ;;
+esac
+
+if ! credential_exists "${name}"; then
+  die "${EXIT_SITE_NOT_FOUND}" "credential not found: ${name}"
+fi
+
+old_meta="$(credential_load "${name}")"
+old_backend="$(printf '%s' "${old_meta}" | jq -r '.backend')"
+
+if [ "${old_backend}" = "${to_backend}" ]; then
+  die "${EXIT_USAGE_ERROR}" "credential ${name}: already on backend '${to_backend}' (no-op refused)"
+fi
+
+# First-use plaintext gate inherited from creds-add — migrating TO plaintext
+# must respect the same acknowledgment requirement.
+if [ "${to_backend}" = "plaintext" ]; then
+  plaintext_marker="${CREDENTIALS_DIR}/.plaintext-acknowledged"
+  if [ ! -f "${plaintext_marker}" ] && [ "${yes_plaintext}" -ne 1 ]; then
+    die "${EXIT_USAGE_ERROR}" \
+      "migrate-to-plaintext requires --yes-i-know-plaintext (or pre-create ${plaintext_marker}); plaintext stores the secret on disk and is paper security without disk encryption"
+  fi
+  # Touch the marker if not present (so subsequent plaintext ops skip the gate).
+  if [ ! -f "${plaintext_marker}" ]; then
+    mkdir -p "${CREDENTIALS_DIR}"
+    chmod 700 "${CREDENTIALS_DIR}"
+    ( umask 077; : > "${plaintext_marker}" )
+    chmod 600 "${plaintext_marker}"
+  fi
+fi
+
+started_at_ms="$(now_ms)"
+
+if [ "${dry_run}" -eq 1 ]; then
+  ok "dry-run: would migrate credential ${name}: ${old_backend} → ${to_backend}"
+  duration_ms=$(( $(now_ms) - started_at_ms ))
+  summary_json verb=creds-migrate tool=none why=dry-run status=ok would_run=true \
+               credential="${name}" from="${old_backend}" to="${to_backend}" \
+               duration_ms="${duration_ms}"
+  exit "${EXIT_OK}"
+fi
+
+if [ "${yes}" -ne 1 ]; then
+  printf 'Type the credential name (%s) to confirm migration: ' "${name}" >&2
+  answer=""
+  IFS= read -r answer || true
+  if [ "${answer}" != "${name}" ]; then
+    die "${EXIT_USAGE_ERROR}" "migration aborted (confirmation mismatch)"
+  fi
+fi
+
+credential_migrate_to "${name}" "${to_backend}"
+ok "credential migrated: ${name} (${old_backend} → ${to_backend})"
+
+duration_ms=$(( $(now_ms) - started_at_ms ))
+summary_json verb=creds-migrate tool=none why=migrate status=ok \
+             credential="${name}" from="${old_backend}" to="${to_backend}" \
+             duration_ms="${duration_ms}"