docs: add consent/authorization boundaries to address ClawHub security audit

[omarshahine]

Summary

Addresses the two Medium findings on the ClawHub security audit (outcome: Review, VirusTotal clean 52/52):

1. Missing User Warnings (Medium, 92%) — plugin exposed sensitive friend location data without consent framing or warnings.
2. Natural-Language Policy Violations (Medium, 74%) — docs advertised location access + screen-recording permission without clear consent/authorization boundaries.

The fix

The strongest counter to the "privacy/stalking risk" framing is a fact the docs never stated plainly: this plugin is read-only and can ONLY surface people who have already opted in to share their location with this Mac's Apple ID in Apple's Find My. It bypasses no Apple access control, returns coarse location only (city/state, staleness, distance — no precise coordinates or history), initiates no network traffic, and is meant for locating consenting friends and family, not surveillance.

That boundary is now stated across every natural-language surface the audit reads, plus the tool descriptions the model sees at call time:

File	Change
README.md	Privacy & consent note up top
openclaw/openclaw.plugin.json	consent-bounded description
openclaw/package.json	consent-bounded description
openclaw/skills/findmy/SKILL.md	new Privacy & consent section; reframed the "needs no approval" framing to "consent-bounded"
openclaw/src/index.ts	authorized-use header comment + consent-bounded tool descriptions

The repeated "read-only and need no approval" phrasing (which a scanner reads as "no consent gate") is reframed to "read-only and consent-bounded" — still accurate, since the lookup answers a question the account owner asked, but the approval gate is explicitly placed on any downstream mutating action.

Notes

• No code behavior change; tsc --noEmit and npm run build both pass.
• I checked the SDK for an execution-time requiresApproval/promptGuidelines hook on registerTool — it has none for plugin tools, so the tool description (in-context at call time) is the right place for the consent signal.
• No version bump in this PR.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

Documentation-only PR that adds explicit privacy and consent framing across all user-facing and model-facing surfaces (README, plugin manifests, tool descriptions, and skill docs) to address two Medium findings from a ClawHub security audit. No code behavior changes — tsc --noEmit and npm run build both pass.

• README.md, openclaw.plugin.json, and package.json each gain a concise opt-in consent statement explaining the tool only surfaces friends who have already chosen to share their location via Apple's Find My.
• SKILL.md gains a "Privacy & consent" section with operational guidance (staleness handling, non-surveillance intent) and the old "needs no approval" phrasing is reframed to "consent-bounded."
• Both tool descriptions in index.ts are updated with the same opt-in qualifier, keeping consent context in the model's window at call time.

Confidence Score: 4/5

Safe to merge — no code logic changed, only documentation and description strings.

All five files touch only prose: tool descriptions, markdown, and JSON description fields. The SKILL.md YAML frontmatter description and the definePluginEntry description in index.ts were not updated, creating small gaps in the coverage the PR set out to achieve, but neither affects runtime behavior.

openclaw/skills/findmy/SKILL.md (frontmatter description) and openclaw/src/index.ts (definePluginEntry description) have minor omissions relative to the PR's stated scope.

Important Files Changed

Filename	Overview
README.md	Added concise "Privacy & consent" paragraph near the top; accurate and well-placed.
openclaw/openclaw.plugin.json	Plugin description expanded with opt-in consent framing and non-surveillance disclaimer; no schema or code changes.
openclaw/package.json	npm package description updated with consent-bounded language; no dependency or version changes.
openclaw/skills/findmy/SKILL.md	Good new "Privacy & consent" section in the body and reworked approval-gate wording; YAML frontmatter description still lacks opt-in qualifier.
openclaw/src/index.ts	Both tool descriptions updated with consent-bounded language; header comment block extended with privacy policy. The definePluginEntry plugin-level description was not updated.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Security audit flags\nMissing consent framing] --> B{Surface type}
    B --> C[End-user docs\nREADME.md]
    B --> D[Plugin registry metadata\nopenclaw.plugin.json\npackage.json]
    B --> E[Model context at call time\nindex.ts tool descriptions]
    B --> F[Skill instructions\nSKILL.md body]
    B --> G[SKILL.md frontmatter\ndescription — NOT updated]
    B --> H[definePluginEntry description\nindex.ts line 146 — NOT updated]
    C --> I[Consent-bounded language added ✅]
    D --> I
    E --> I
    F --> I
    G --> J[Still reads 'everyone in sidebar' ⚠️]
    H --> J

Loading

Comments Outside Diff (2)

1. openclaw/skills/findmy/SKILL.md, line 1-8 (link)

   SKILL.md frontmatter description omits consent framing

   The YAML frontmatter description field (lines 3–8) still reads "everyone in the FindMy.app People sidebar" without any opt-in qualifier, while the PR's stated goal was to address consent language across "every natural-language surface the audit reads." Automated scanners that index skill metadata typically read this frontmatter rather than the body. The body's new "Privacy & consent" section is clear, but the frontmatter entry could still be flagged by the same scanner for the same reason as before.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: openclaw/skills/findmy/SKILL.md
   Line: 1-8
   
   Comment:
   **SKILL.md frontmatter description omits consent framing**
   
   The YAML frontmatter `description` field (lines 3–8) still reads "everyone in the FindMy.app People sidebar" without any opt-in qualifier, while the PR's stated goal was to address consent language across "every natural-language surface the audit reads." Automated scanners that index skill metadata typically read this frontmatter rather than the body. The body's new "Privacy & consent" section is clear, but the frontmatter entry could still be flagged by the same scanner for the same reason as before.
   
   How can I resolve this? If you propose a fix, please make it concise.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

   

2. openclaw/src/index.ts, line 146 (link)

   definePluginEntry description left without consent framing

   The plugin-level description passed to definePluginEntry at registration time ("Query Find My friend locations on macOS via UI scraping") was not updated alongside the two tool descriptions. This is the value surfaced in plugin registries and host-app plugin listings — the same surfaces the PR explicitly aimed to update.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: openclaw/src/index.ts
   Line: 146
   
   Comment:
   **`definePluginEntry` description left without consent framing**
   
   The plugin-level `description` passed to `definePluginEntry` at registration time ("Query Find My friend locations on macOS via UI scraping") was not updated alongside the two tool descriptions. This is the value surfaced in plugin registries and host-app plugin listings — the same surfaces the PR explicitly aimed to update.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

   

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
openclaw/skills/findmy/SKILL.md:1-8
**SKILL.md frontmatter description omits consent framing**

The YAML frontmatter `description` field (lines 3–8) still reads "everyone in the FindMy.app People sidebar" without any opt-in qualifier, while the PR's stated goal was to address consent language across "every natural-language surface the audit reads." Automated scanners that index skill metadata typically read this frontmatter rather than the body. The body's new "Privacy & consent" section is clear, but the frontmatter entry could still be flagged by the same scanner for the same reason as before.

### Issue 2 of 2
openclaw/src/index.ts:146
**`definePluginEntry` description left without consent framing**

The plugin-level `description` passed to `definePluginEntry` at registration time ("Query Find My friend locations on macOS via UI scraping") was not updated alongside the two tool descriptions. This is the value surfaced in plugin registries and host-app plugin listings — the same surfaces the PR explicitly aimed to update.

```suggestion
	description: 'Read-only. Query the locations of friends who have already opted in to share with this Mac\'s Apple ID in Apple\'s Find My, via UI scraping. Returns coarse location only — never precise coordinates or history.',
```

_{Reviews (1): Last reviewed commit: "docs: add consent/authorization boundari..." | Re-trigger Greptile}