browser-automation-skill 0.71.0

package/scripts/lib/router.sh

@@ -0,0 +1,342 @@
+# shellcheck shell=bash
+# scripts/lib/router.sh — single source of truth for routing precedence.
+# Verb scripts call pick_tool; the router returns "TOOL_NAME\tWHY".
+# Adding a new precedence rule = define a function + append to ROUTING_RULES.
+# Adding a new adapter that's NEVER the default for any verb = ZERO edits here
+# (the adapter is reachable via --tool=<name> but won't be picked otherwise).
+# See: docs/superpowers/specs/2026-04-30-tool-adapter-extension-model-design.md §4
+
+[ -n "${BROWSER_SKILL_ROUTER_LOADED:-}" ] && return 0
+readonly BROWSER_SKILL_ROUTER_LOADED=1
+
+# init_paths must have been called (LIB_TOOL_DIR is set there).
+# common.sh is required (EXIT_* constants, die, _has_flag).
+
+# ROUTING_RULES is an ordered list of rule-function names. The first rule
+# whose function returns 0 (after also passing the capability filter) wins.
+# Rules are appended in priority order. Add a new rule = define _rule_<name>
+# function below + append its NAME to this array.
+# Order matters: top-down, first-match-with-capability-support wins.
+# Adding a tool that's NEVER the default for any verb = ZERO edits to this array.
+ROUTING_RULES=(
+  rule_session_required
+  rule_capture_flags
+  rule_audit_or_perf
+  rule_inspect_default
+  rule_scrape_flag
+  rule_stealth_flag
+  rule_extract_default
+  rule_press_default
+  rule_select_default
+  rule_hover_default
+  rule_wait_default
+  rule_drag_default
+  rule_upload_default
+  rule_route_default
+  rule_tab_list_default
+  rule_tab_switch_default
+  rule_tab_close_default
+  rule_default_navigation
+)
+
+# _has_flag FLAG ARGS... — returns 0 if FLAG appears in ARGS, else 1.
+# Used by rule functions to detect routing-trigger flags in the verb's argv.
+_has_flag() {
+  local needle="$1"
+  shift
+  local arg
+  for arg in "$@"; do
+    [ "${arg}" = "${needle}" ] && return 0
+  done
+  return 1
+}
+
+# _tool_supports TOOL_NAME VERB [FLAGS...] — returns 0 if the adapter declares
+# support for VERB in its tool_capabilities() output, 1 otherwise. Sources the
+# adapter in a subshell to keep verb-dispatch namespace clean.
+#
+# Phase 12 part 2 audit: per-process memo. Worst-case pick_tool walks 18 rules
+# and each rule may probe `_tool_supports`; the un-cached version forked
+# `source + tool_capabilities + jq -e` for every probe. The cache makes each
+# (tool, verb) tuple cost one fork on first probe and zero forks thereafter.
+declare -gA _TOOL_SUPPORTS_CACHE 2>/dev/null || true
+_tool_supports() {
+  local tool="$1" verb="$2"
+  shift 2
+  local key="${tool}\t${verb}"
+  case "${_TOOL_SUPPORTS_CACHE[${key}]:-}" in
+    yes) return 0 ;;
+    no)  return 1 ;;
+  esac
+  [ -f "${LIB_TOOL_DIR}/${tool}.sh" ] || { _TOOL_SUPPORTS_CACHE[${key}]=no; return 1; }
+  if jq -e --arg v "${verb}" '.verbs | has($v)' >/dev/null 2>&1 <<<"$(
+      # shellcheck source=/dev/null
+      source "${LIB_TOOL_DIR}/${tool}.sh"
+      tool_capabilities 2>/dev/null
+    )"; then
+    _TOOL_SUPPORTS_CACHE[${key}]=yes
+    return 0
+  fi
+  _TOOL_SUPPORTS_CACHE[${key}]=no
+  return 1
+}
+
+# --- Precedence rules (in order). Each fn echoes "TOOL\tWHY" if it matches.
+# Add a rule = define a function + append its NAME to ROUTING_RULES above.
+
+# Session-loading required: when verb_helpers.sh::resolve_session_storage_state
+# resolved a storageState file (BROWSER_SKILL_STORAGE_STATE non-empty), prefer
+# playwright-lib — the only adapter declaring session_load: true.
+# Reads env var (not argv) because session resolution happens before pick_tool.
+rule_session_required() {
+  local verb="$1"
+  if [ -n "${BROWSER_SKILL_STORAGE_STATE:-}" ]; then
+    case "${verb}" in
+      open|click|fill|snapshot|login)
+        printf 'playwright-lib\t%s\n' "session loading required (BROWSER_SKILL_STORAGE_STATE set)"
+        ;;
+    esac
+  fi
+}
+
+# Capture flags require the dedicated console + network MCP tools that only
+# chrome-devtools-mcp exposes (per parent spec Appendix B). Triggered by
+# `--capture-console` or `--capture-network` on any verb.
+rule_capture_flags() {
+  local verb="$1"
+  shift
+  if _has_flag --capture-console "$@" || _has_flag --capture-network "$@"; then
+    printf 'chrome-devtools-mcp\t%s\n' "--capture-* requested (only cdt-mcp exposes console/network MCP tools)"
+  fi
+}
+
+# Lighthouse + perf-trace verbs/flags route to chrome-devtools-mcp — only
+# adapter with `lighthouse_audit` and `performance_*` MCP tools (Appendix B).
+rule_audit_or_perf() {
+  local verb="$1"
+  shift
+  case "${verb}" in
+    audit)
+      printf 'chrome-devtools-mcp\t%s\n' "verb=audit (only cdt-mcp has lighthouse/perf)"
+      return 0
+      ;;
+  esac
+  if _has_flag --lighthouse "$@" || _has_flag --perf-trace "$@"; then
+    printf 'chrome-devtools-mcp\t%s\n' "--lighthouse/--perf-trace requested (only cdt-mcp has them)"
+  fi
+}
+
+# Default tool for `inspect` per parent spec Appendix B — chrome-devtools-mcp
+# is the only adapter with dedicated console + network + screenshot MCP tools
+# bundled into a single inspection surface.
+rule_inspect_default() {
+  local verb="$1"
+  case "${verb}" in
+    inspect)
+      printf 'chrome-devtools-mcp\t%s\n' "inspect default per Appendix B"
+      ;;
+  esac
+}
+
+# Phase 8 part 2-i (Path B): --scrape routes to obscura. Higher precedence
+# than rule_extract_default so `extract --scrape` reaches obscura instead of
+# chrome-devtools-mcp. Capability filter rejects mismatched verbs (e.g.
+# `open --scrape` falls through since obscura doesn't declare verb=open).
+rule_scrape_flag() {
+  local verb="$1"
+  shift
+  if _has_flag --scrape "$@"; then
+    printf 'obscura\t%s\n' "--scrape requested (only obscura declares scrape backend)"
+  fi
+}
+
+# Phase 8 part 2-i (Path B): --stealth routes to obscura. Single-URL anti-
+# detect mode. Same precedence reasoning as rule_scrape_flag.
+rule_stealth_flag() {
+  local verb="$1"
+  shift
+  if _has_flag --stealth "$@"; then
+    printf 'obscura\t%s\n' "--stealth requested (only obscura declares stealth backend)"
+  fi
+}
+
+# Default tool for `extract` per parent spec Appendix B — chrome-devtools-mcp
+# pairs `evaluate_script` with `list_network_requests` for selector/eval +
+# multi-URL inspection. `--scrape` / `--stealth` route to obscura via the
+# higher-precedence rule_scrape_flag / rule_stealth_flag rules (Phase 8-2-i).
+rule_extract_default() {
+  local verb="$1"
+  case "${verb}" in
+    extract)
+      printf 'chrome-devtools-mcp\t%s\n' "extract default per Appendix B"
+      ;;
+  esac
+}
+
+# Phase-6 part 1: keyboard press routes to chrome-devtools-mcp. cdt-mcp's
+# `press_key` MCP tool is the canonical input mechanism; playwright-cli/lib
+# don't declare press today (could be added later via their respective
+# `keyboard.press` APIs).
+rule_press_default() {
+  local verb="$1"
+  case "${verb}" in
+    press)
+      printf 'chrome-devtools-mcp\t%s\n' "press default (only cdt-mcp declares press today)"
+      ;;
+  esac
+}
+
+# Phase-6 part 2: <select> option pick routes to chrome-devtools-mcp.
+# Stateful — requires daemon (refMap precondition). MCP `select_option` tool
+# accepts uid + one of value/label/index.
+rule_select_default() {
+  local verb="$1"
+  case "${verb}" in
+    select)
+      printf 'chrome-devtools-mcp\t%s\n' "select default (only cdt-mcp declares select today)"
+      ;;
+  esac
+}
+
+# Phase-6 part 3: pointer hover routes to chrome-devtools-mcp. Stateful —
+# requires daemon (refMap precondition). MCP `hover` tool accepts uid.
+rule_hover_default() {
+  local verb="$1"
+  case "${verb}" in
+    hover)
+      printf 'chrome-devtools-mcp\t%s\n' "hover default (only cdt-mcp declares hover today)"
+      ;;
+  esac
+}
+
+# Phase-6 part 4: explicit wait for an element state. Stateless — no refMap
+# required (selector-based). MCP `wait_for` tool accepts {selector, state,
+# timeout}. Routes one-shot or daemon-routed (parallel to eval/audit).
+rule_wait_default() {
+  local verb="$1"
+  case "${verb}" in
+    wait)
+      printf 'chrome-devtools-mcp\t%s\n' "wait default (only cdt-mcp declares wait today)"
+      ;;
+  esac
+}
+
+# Phase-6 part 5: pointer drag (src → dst by refs). Stateful — requires
+# daemon (refMap precondition for both src + dst). MCP `drag` tool accepts
+# {src_uid, dst_uid}.
+rule_drag_default() {
+  local verb="$1"
+  case "${verb}" in
+    drag)
+      printf 'chrome-devtools-mcp\t%s\n' "drag default (only cdt-mcp declares drag today)"
+      ;;
+  esac
+}
+
+# Phase-6 part 6: file upload (<input type=file>). Stateful — requires
+# daemon (refMap precondition). MCP `upload_file` tool accepts {uid, path}.
+# Bash-side validates path security before reaching the daemon.
+rule_upload_default() {
+  local verb="$1"
+  case "${verb}" in
+    upload)
+      printf 'chrome-devtools-mcp\t%s\n' "upload default (only cdt-mcp declares upload today)"
+      ;;
+  esac
+}
+
+# Phase-6 part 7: network-route rule (request interception/mocking).
+# Daemon-state-mutating (routeRules array). Routes to chrome-devtools-mcp.
+rule_route_default() {
+  local verb="$1"
+  case "${verb}" in
+    route)
+      printf 'chrome-devtools-mcp\t%s\n' "route default (only cdt-mcp declares route today)"
+      ;;
+  esac
+}
+
+# Phase-6 part 8-i: tab enumeration. Read-only; daemon caches tabs[] slot
+# so 8-ii (tab-switch) / 8-iii (tab-close) can reference the same shape.
+rule_tab_list_default() {
+  local verb="$1"
+  case "${verb}" in
+    tab-list)
+      printf 'chrome-devtools-mcp\t%s\n' "tab-list default (only cdt-mcp declares tab-list today)"
+      ;;
+  esac
+}
+
+# Phase-6 part 8-ii: tab switching. First state-mutation on tabs[] (adds
+# currentTab pointer in the daemon). Routes to chrome-devtools-mcp.
+rule_tab_switch_default() {
+  local verb="$1"
+  case "${verb}" in
+    tab-switch)
+      printf 'chrome-devtools-mcp\t%s\n' "tab-switch default (only cdt-mcp declares tab-switch today)"
+      ;;
+  esac
+}
+
+# Phase-6 part 8-iii: tab close. Splice from tabs[] + close upstream page +
+# null currentTab on match. Routes to chrome-devtools-mcp.
+rule_tab_close_default() {
+  local verb="$1"
+  case "${verb}" in
+    tab-close)
+      printf 'chrome-devtools-mcp\t%s\n' "tab-close default (only cdt-mcp declares tab-close today)"
+      ;;
+  esac
+}
+
+# Default for navigation/inspection verbs — playwright-cli is the cheap,
+# stable, multi-browser default per parent spec Appendix B.
+rule_default_navigation() {
+  local verb="$1"
+  case "${verb}" in
+    open|click|fill|snapshot)
+      printf 'playwright-cli\t%s\n' "default for ${verb}"
+      ;;
+  esac
+}
+
+# pick_tool VERB [FLAGS...] — echoes "TOOL_NAME\tWHY" on success.
+# Two-stage:
+#   1. --tool=X (via $ARG_TOOL env var): validate X exists + supports verb.
+#   2. Walk ROUTING_RULES top-down. First matching rule whose tool ALSO
+#      passes the capability filter wins.
+# On exhaustion: dies with EXIT_TOOL_MISSING.
+pick_tool() {
+  local verb="$1"
+  shift
+
+  if [ -n "${ARG_TOOL:-}" ]; then
+    if [ ! -f "${LIB_TOOL_DIR}/${ARG_TOOL}.sh" ]; then
+      die "${EXIT_USAGE_ERROR}" "--tool=${ARG_TOOL}: no such adapter (no ${LIB_TOOL_DIR}/${ARG_TOOL}.sh)"
+    fi
+    if ! _tool_supports "${ARG_TOOL}" "${verb}" "$@"; then
+      die "${EXIT_USAGE_ERROR}" "--tool=${ARG_TOOL} does not support verb=${verb} (per tool_capabilities)"
+    fi
+    printf '%s\t%s\n' "${ARG_TOOL}" "user-specified"
+    return 0
+  fi
+
+  local rule
+  for rule in "${ROUTING_RULES[@]}"; do
+    local rule_out
+    rule_out="$("${rule}" "${verb}" "$@" 2>/dev/null || true)"
+    [ -z "${rule_out}" ] && continue
+
+    local picked_tool picked_why
+    picked_tool="${rule_out%%$'\t'*}"
+    picked_why="${rule_out#*$'\t'}"
+
+    if _tool_supports "${picked_tool}" "${verb}" "$@"; then
+      printf '%s\t%s\n' "${picked_tool}" "${picked_why}"
+      return 0
+    fi
+    warn "router: rule ${rule} picked ${picked_tool} but it doesn't support verb=${verb}; falling through"
+  done
+
+  die "${EXIT_TOOL_MISSING}" "no adapter supports verb=${verb} with flags: $*"
+}

package/scripts/lib/sanitize.sh

@@ -0,0 +1,107 @@
+# scripts/lib/sanitize.sh — capture sanitization (Phase 7 part 1-ii).
+#
+# Two-function API:
+#   sanitize_har     — redact sensitive HAR fields (request/response headers,
+#                      URL params). Reads HAR JSON on stdin; emits redacted
+#                      HAR JSON on stdout.
+#   sanitize_console — redact sensitive console message fields (password,
+#                      secret, token values inline in the message text).
+#                      Reads console-array JSON on stdin; emits redacted
+#                      array on stdout.
+#
+# Per parent spec §8.3:
+# - Header sentinel:  "***REDACTED***" (whole-value replace).
+# - URL/console mask: "***" (param-value or field-value replace; key preserved).
+#
+# Sensitive HEADER name set (case-insensitive, ascii_downcase compared):
+#   request:  authorization | cookie | x-api-key | x-auth-token
+#   response: set-cookie    | authorization
+#
+# Sensitive URL PARAM key set (key=value pairs in the query string):
+#   api_key | token | access_token | client_secret
+#
+# Sensitive CONSOLE FIELD key set (case-insensitive in the message text):
+#   password | secret | token
+#
+# 7-1-ii scope: pure functions, no verb integration. 7-1-iii wires this into
+# `inspect --capture-console --capture-network --capture` so console.json +
+# network.har are sanitized before disk-persist.
+#
+# jq compatibility: avoids named-capture groups (`(?<name>...)`) since older
+# jq builds reject them. Per-key sub() loop is portable across jq 1.6+.
+
+[ -n "${_BROWSER_LIB_SANITIZE_LOADED:-}" ] && return 0
+readonly _BROWSER_LIB_SANITIZE_LOADED=1
+
+# sanitize_har — read HAR JSON from stdin, write redacted HAR to stdout.
+sanitize_har() {
+  jq '
+    def _redact_header_request:
+      if (.name | ascii_downcase) as $n
+         | $n == "authorization" or $n == "cookie"
+           or $n == "x-api-key" or $n == "x-auth-token"
+      then .value = "***REDACTED***" else . end;
+
+    def _redact_header_response:
+      if (.name | ascii_downcase) as $n
+         | $n == "authorization" or $n == "set-cookie"
+      then .value = "***REDACTED***" else . end;
+
+    def _mask_url_params:
+      reduce ("api_key", "token", "access_token", "client_secret") as $k
+        (.; sub("(?<pre>[?&])" + $k + "=[^&]*"; "\(.pre)" + $k + "=***"));
+
+    .log.entries |= map(
+      .request.headers  |= map(_redact_header_request)
+      | .response.headers |= map(_redact_header_response)
+      | .request.url    |= _mask_url_params
+    )
+  '
+}
+
+# sanitize_console — read console-array JSON from stdin, write redacted array.
+# Each entry is {level, text, ...}; text gets per-key field masking.
+sanitize_console() {
+  jq '
+    def _mask_console_text:
+      reduce ("password", "secret", "token") as $k
+        (.; gsub("(?i)(?<pre>\\b" + $k + "\\b\\s*[:=]\\s*)\\S+"; "\(.pre)***"));
+
+    map(
+      if has("text") and (.text | type) == "string"
+      then .text |= _mask_console_text
+      else . end
+    )
+  '
+}
+
+# sanitize_inspect_reply (Phase 7 part 1-iii) — applied to the bridge's
+# combined inspect reply. Sanitizes both .console_messages (via the same
+# rules as sanitize_console) and .network_requests (each request entry is
+# wrapped in a HAR envelope and run through sanitize_har in-memory).
+# Reads inspect-shaped JSON on stdin, emits same shape with sensitive values
+# redacted in place. Non-sensitive fields (verb, tool, why, status, matches,
+# screenshot_path, etc.) pass through untouched. Used by browser-inspect.sh
+# --capture for both stdout-side (agent-visibility) and disk-side (per-aspect
+# files: console.json + network.har) sanitization — single transformation,
+# both sinks.
+sanitize_inspect_reply() {
+  local raw out
+  raw="$(cat)"
+  out="${raw}"
+
+  if printf '%s' "${raw}" | jq -e 'has("console_messages") and (.console_messages | type == "array")' >/dev/null 2>&1; then
+    local sc
+    sc="$(printf '%s' "${raw}" | jq '.console_messages' | sanitize_console)"
+    out="$(printf '%s' "${out}" | jq --argjson sc "${sc}" '.console_messages = $sc')"
+  fi
+
+  if printf '%s' "${raw}" | jq -e 'has("network_requests") and (.network_requests | type == "array")' >/dev/null 2>&1; then
+    local sr_envelope sr
+    sr_envelope="$(printf '%s' "${raw}" | jq '{log: {entries: .network_requests}}' | sanitize_har)"
+    sr="$(printf '%s' "${sr_envelope}" | jq '.log.entries')"
+    out="$(printf '%s' "${out}" | jq --argjson sr "${sr}" '.network_requests = $sr')"
+  fi
+
+  printf '%s' "${out}"
+}

package/scripts/lib/secret/keychain.sh

@@ -0,0 +1,91 @@
+# scripts/lib/secret/keychain.sh — macOS Keychain credentials backend.
+#
+# Implements the 4-fn secret backend contract used by lib/credential.sh:
+#   secret_set NAME       (stdin → keychain via `security add-generic-password`)
+#   secret_get NAME       (keychain → stdout via `security find-generic-password -w`)
+#   secret_delete NAME    (idempotent rm via `security delete-generic-password`)
+#   secret_exists NAME    (probe via `security find-generic-password` no -w)
+#
+# All entries share a single keychain service prefix:
+#   ${BROWSER_SKILL_KEYCHAIN_SERVICE:-browser-skill}
+# Per-credential entries use account = NAME.
+#
+# AP-7 documented exception:
+# The macOS `security` CLI takes the password on argv via `-w PASSWORD`. There
+# is no clean stdin-input path in the upstream tool — the only stdin alternative
+# is an interactive TTY prompt which doesn't compose with non-TTY pipelines.
+# Working around this would require either:
+#   - A python+keyring runtime dep (rejected: adds an external dep for one OS)
+#   - A compiled Swift/ObjC helper binary (rejected: adds build step)
+#   - osascript-mediated Keychain Services API (rejected: secrets via osascript
+#     -e are also argv-visible)
+# The skill's own code never puts secrets on argv (`secret_set` reads stdin and
+# constructs the `security` invocation locally). The leak surface is the brief
+# `security` subprocess (~50ms wall-clock). Mitigations:
+#   1. Subprocess is short-lived; ps polling at any practical rate misses it.
+#   2. The -U flag makes the call idempotent (no second invocation needed).
+#   3. Linux libsecret backend (phase-05 part 2c) uses `secret-tool` which IS
+#      stdin-clean — the AP-7 exception stays macOS-specific.
+# This is the "honest documented exception" pattern: AP-7 is the invariant for
+# our code; the upstream tool's argv-only design is an unavoidable upstream
+# constraint we acknowledge in this header + the cheatsheet (when 2d ships)
+# rather than work around with extra runtime deps.
+
+[ -n "${BROWSER_SKILL_SECRET_KEYCHAIN_LOADED:-}" ] && return 0
+readonly BROWSER_SKILL_SECRET_KEYCHAIN_LOADED=1
+
+readonly _KEYCHAIN_SERVICE="${BROWSER_SKILL_KEYCHAIN_SERVICE:-browser-skill}"
+readonly _KEYCHAIN_SECURITY_BIN="${KEYCHAIN_SECURITY_BIN:-security}"
+
+# secret_set NAME — stdin → keychain via `security add-generic-password -w`.
+# The -U flag makes the call idempotent: if an entry already exists for
+# (-s SERVICE -a NAME), it is updated rather than rejected with an error.
+secret_set() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  local secret
+  secret="$(cat)"
+  "${_KEYCHAIN_SECURITY_BIN}" add-generic-password \
+    -s "${_KEYCHAIN_SERVICE}" \
+    -a "${name}" \
+    -w "${secret}" \
+    -U \
+    >/dev/null
+}
+
+# secret_get NAME — echoes the password to stdout via `security find-generic-
+# password -w`. Exits non-zero if entry is not in the keychain (security's
+# native exit-44, "item could not be found").
+secret_get() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  "${_KEYCHAIN_SECURITY_BIN}" find-generic-password \
+    -s "${_KEYCHAIN_SERVICE}" \
+    -a "${name}" \
+    -w \
+    2>/dev/null
+}
+
+# secret_delete NAME — idempotent. `security delete-generic-password` exits
+# non-zero on missing items; the `|| true` swallow makes the contract match
+# the plaintext backend (and what callers expect).
+secret_delete() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  "${_KEYCHAIN_SECURITY_BIN}" delete-generic-password \
+    -s "${_KEYCHAIN_SERVICE}" \
+    -a "${name}" \
+    >/dev/null 2>&1 || true
+}
+
+# secret_exists NAME — returns 0 if entry present in keychain, non-zero if not.
+# Probes via `security find-generic-password` without -w (no payload echo,
+# just existence check).
+secret_exists() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  "${_KEYCHAIN_SECURITY_BIN}" find-generic-password \
+    -s "${_KEYCHAIN_SERVICE}" \
+    -a "${name}" \
+    >/dev/null 2>&1
+}

package/scripts/lib/secret/libsecret.sh

@@ -0,0 +1,74 @@
+# scripts/lib/secret/libsecret.sh — Linux libsecret credentials backend.
+#
+# Implements the 4-fn secret backend contract used by lib/credential.sh:
+#   secret_set NAME       (stdin → libsecret via `secret-tool store`)
+#   secret_get NAME       (libsecret → stdout via `secret-tool lookup`)
+#   secret_delete NAME    (idempotent rm via `secret-tool clear`)
+#   secret_exists NAME    (probe via `secret-tool lookup` to /dev/null)
+#
+# All entries share a single service attribute:
+#   ${BROWSER_SKILL_LIBSECRET_SERVICE:-browser-skill}
+# Per-credential entries use account = NAME.
+#
+# AP-7 status: CLEAN — no documented exception. The upstream `secret-tool`
+# CLI reads the password from stdin natively (via the `store` subcommand).
+# `secret_set` reads stdin and pipes directly into `secret-tool store`;
+# the password never appears in argv. Contrast with the macOS keychain
+# backend (`scripts/lib/secret/keychain.sh`) which has a documented AP-7
+# exception because the upstream `security` CLI is argv-only.
+#
+# Stdin verbatim: `secret-tool store` reads the password from stdin without
+# trailing-newline strip — what you pipe in is what gets stored. Tests
+# assert byte-exact roundtrip. If you `printf 'pw\n' | secret_set foo`,
+# the stored value is `pw\n` (with newline). For most callers,
+# `printf 'pw' | secret_set foo` (no trailing newline) is the right idiom.
+
+[ -n "${BROWSER_SKILL_SECRET_LIBSECRET_LOADED:-}" ] && return 0
+readonly BROWSER_SKILL_SECRET_LIBSECRET_LOADED=1
+
+readonly _LIBSECRET_SERVICE="${BROWSER_SKILL_LIBSECRET_SERVICE:-browser-skill}"
+readonly _LIBSECRET_TOOL_BIN="${LIBSECRET_TOOL_BIN:-secret-tool}"
+
+# secret_set NAME — stdin → libsecret via `secret-tool store`. AP-7 clean.
+# Idempotency: clear-then-store. `clear` exits non-zero on missing item;
+# the swallow keeps the contract.
+secret_set() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  "${_LIBSECRET_TOOL_BIN}" clear \
+    service "${_LIBSECRET_SERVICE}" account "${name}" \
+    >/dev/null 2>&1 || true
+  "${_LIBSECRET_TOOL_BIN}" store \
+    --label "browser-skill: ${name}" \
+    service "${_LIBSECRET_SERVICE}" account "${name}"
+}
+
+# secret_get NAME — echoes the password to stdout. Exits non-zero (1) if
+# entry not in libsecret.
+secret_get() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  "${_LIBSECRET_TOOL_BIN}" lookup \
+    service "${_LIBSECRET_SERVICE}" account "${name}"
+}
+
+# secret_delete NAME — idempotent. `secret-tool clear` exits non-zero on
+# missing items; the `|| true` swallow makes the contract match the
+# plaintext + keychain backends.
+secret_delete() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  "${_LIBSECRET_TOOL_BIN}" clear \
+    service "${_LIBSECRET_SERVICE}" account "${name}" \
+    >/dev/null 2>&1 || true
+}
+
+# secret_exists NAME — returns 0 if entry present in libsecret, non-zero
+# if not. Probes via `secret-tool lookup` discarding the password.
+secret_exists() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  "${_LIBSECRET_TOOL_BIN}" lookup \
+    service "${_LIBSECRET_SERVICE}" account "${name}" \
+    >/dev/null 2>&1
+}

package/scripts/lib/secret/plaintext.sh

@@ -0,0 +1,75 @@
+# scripts/lib/secret/plaintext.sh — plaintext credentials backend.
+#
+# Implements the 4-fn secret backend contract used by lib/credential.sh:
+#   secret_set NAME       (stdin → ${CREDENTIALS_DIR}/<name>.secret mode 0600)
+#   secret_get NAME       (file → stdout)
+#   secret_delete NAME    (rm -f, idempotent)
+#   secret_exists NAME    (returns 0 if present, 1 if not)
+#
+# Backends are dumb I/O — they DO NOT enforce any flow logic (typed-phrase
+# confirmation, --reveal masking, etc). All flow concerns live in
+# lib/credential.sh and the verb scripts (Phase 5 part 2d).
+#
+# AP-7: secrets MUST flow via stdin pipes only. NEVER as positional argv.
+# tests/secret_plaintext.bats greps this file for the anti-pattern.
+#
+# Sibling backends (deferred):
+#   - scripts/lib/secret/keychain.sh (macOS Security framework) — phase-05 part 2b
+#   - scripts/lib/secret/libsecret.sh (Linux Secret Service)    — phase-05 part 2c
+#
+# Plaintext threat model: file mode 0600 + ${BROWSER_SKILL_HOME} mode 0700 +
+# disk encryption (FileVault on macOS / LUKS on Linux — doctor advises). A
+# user without disk encryption is warned by `doctor` (Phase 1). The verb
+# layer (part 2d's `creds add`) requires a typed-phrase confirmation on
+# first plaintext use. None of that policy lives here.
+
+[ -n "${BROWSER_SKILL_SECRET_PLAINTEXT_LOADED:-}" ] && return 0
+readonly BROWSER_SKILL_SECRET_PLAINTEXT_LOADED=1
+
+_secret_plaintext_path() {
+  printf '%s/%s.secret' "${CREDENTIALS_DIR}" "$1"
+}
+
+# secret_set NAME — reads stdin, writes ${CREDENTIALS_DIR}/<name>.secret 0600.
+# Atomically: writes to a tmp file then renames. Overwrites existing payload.
+secret_set() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+
+  mkdir -p "${CREDENTIALS_DIR}"
+  chmod 700 "${CREDENTIALS_DIR}"
+
+  local path tmp
+  path="$(_secret_plaintext_path "${name}")"
+  tmp="${path}.tmp.$$"
+
+  ( umask 077; cat > "${tmp}" )
+  chmod 600 "${tmp}"
+  mv "${tmp}" "${path}"
+}
+
+# secret_get NAME — echoes the payload to stdout. Exits non-zero on missing.
+secret_get() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  local path
+  path="$(_secret_plaintext_path "${name}")"
+  if [ ! -f "${path}" ]; then
+    die "${EXIT_USAGE_ERROR}" "secret not found: ${name}"
+  fi
+  cat "${path}"
+}
+
+# secret_delete NAME — idempotent rm -f.
+secret_delete() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  rm -f "$(_secret_plaintext_path "${name}")"
+}
+
+# secret_exists NAME — returns 0 if present, 1 if not.
+secret_exists() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  [ -f "$(_secret_plaintext_path "${name}")" ]
+}