fix(security): notify-only update check + interactive upgrade flow

[Nowhitestar]

Summary

Hardens the AgentKey skill's security posture so ClawHub's Suspicious flags can be cleared, and rebuilds the update UX into a two-tier design modeled after gstack:

• Tier 1 (check-update.sh): scanner-safe, notify-only detection. Single GET https://api.github.com/..., prints UP_TO_DATE / UPGRADE_AVAILABLE <old> <new> / silent. No git, no execve, no in-place writes outside ${TMPDIR} cache.
• Tier 2 (SKILL.md Step 0): interactive upgrade flow. Agent surfaces AskUserQuestion with Yes / Always / Not now / Never and runs the actual update via npx skills update only after explicit consent (or a previously persisted opt-in).

What's in the PR

1. check-update.sh — notify-only with snooze + disable

Replaces the previous self-applying git fetch + git checkout with a pure detection script. New behavior:

• Issues a single GET to api.github.com, validates the response with a regex, compares against local version.txt.
• Two-tier cache TTL (60 min for UP_TO_DATE, 12 h for UPGRADE_AVAILABLE).
• Honors ~/.config/agentkey/update-disabled (silent if present).
• Honors ~/.config/agentkey/update-snoozed (escalating 24h / 48h / 7d backoff per <version> <level> <epoch> format; new remote version invalidates the snooze).
• Cache invalidates automatically when local moves past cached <old> (handles the user-updated-manually case).

2. SKILL.md Step 0 — interactive upgrade flow

When check-update.sh outputs UPGRADE_AVAILABLE <old> <new>, the agent now:

1. Checks AGENTKEY_AUTO_UPGRADE=1 env var or ~/.config/agentkey/auto-upgrade file. If either is set: announce "Auto-upgrading…" and run the upgrade silently.
2. Otherwise, surface AskUserQuestion:
   • Yes, upgrade now → run npx skills update chainbase-labs/agentkey
   • Always keep me up to date → touch ~/.config/agentkey/auto-upgrade, then upgrade
   • Not now → write ~/.config/agentkey/update-snoozed with escalating level
   • Never ask again → touch ~/.config/agentkey/update-disabled

3. check-mcp.sh — shell-injection hardening

Replace shell-interpolated '$HOME/.claude.json' inside the python3 -c block with os.path.expanduser('~/.claude.json'). Removes a latent injection vector when $HOME contains quote characters. Also tighten except: → except Exception:.

4. SECURITY.md — Security Posture + scanner notes

• Documents what each script reads/writes, byte-precise
• Lists the three new config files under ~/.config/agentkey/ and which side reads/writes each
• Network egress (one GET to api.github.com from the script; npx to npm registry only via user-consented agent action)
• Credential handling (key never leaves the machine except as Authorization header to AgentKey's own API)
• Scanner false-positive notes explaining why check-update.sh (notify-only GitHub call) and check-mcp.sh (credential-pattern read for status check) may match heuristics, and why both patterns are intentional and bounded

Threat-model framing

Scanners scanning the repo source see:

• check-update.sh — pure detection. One outbound GET. No git, no execve. No "remote-controlled binary update" pattern any more.
• check-mcp.sh — local read of two known config paths to verify the API key is configured. Output is a status code; key value discarded. No exfiltration path.
• SKILL.md — text instructions for the agent (not executable code) describing the interactive flow.

The actual npx skills update invocation lives in the agent's runtime, gated by either explicit user consent (AskUserQuestion) or a previously persisted opt-in flag the user set themselves. This is the same threat model as gstack and any other Claude Code skill that performs interactive operations.

What is NOT in this PR (and why)

• Pinning @agentkey/mcp@^1 in manual-install JSON — drafted and reverted. ^1 only blocks major-version supply-chain attacks; minor/patch attacks within 1.x still go through, and the doc-snippet pin doesn't reach the --auth-login writer (lives in the server repo). Cost (manual installers must re-edit JSON for patches) outweighed the marginal protection.

Test plan

• bash -n passes on both shell scripts
• check-update.sh end-to-end tested:
  • UP_TO_DATE when versions match
  • UPGRADE_AVAILABLE 0.9.0 1.2.0 when local lags
  • Cache hit replays, then auto-invalidates when local moves past cached old
  • Snoozed within window → silent
  • Snooze expired (>24h) → re-emits
  • Snoozed for old remote version → re-emits (new version invalidates snooze)
  • update-disabled present → silent regardless
• Snooze escalation logic (level 1 → 2 → 3 → 3 capped) tested standalone
• Auto-upgrade detection (env var, config file, neither) tested standalone
• Python os.path.expanduser block runs cleanly against an existing ~/.claude.json
• After merge + release-please tag, run clawhub skill publish so the new SECURITY.md and scripts ship in the published bundle, then clawhub skill rescan agentkey
• If ClawScan / VirusTotal still flag after rescan, file an appeal at openclaw/clawhub linking to SECURITY.md

🤖 Generated with Claude Code

[lxcong]

@claude review