If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/grishka/NearDrop shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 7w ago
• 26+ active contributors
• Unlicense licensed
• ⚠ Concentrated ownership — top contributor handles 63% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live grishka/NearDrop repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/grishka/NearDrop.

What it runs against: a local clone of grishka/NearDrop — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in grishka/NearDrop | Confirms the artifact applies here, not a fork | | 2 | License is still Unlicense | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 81 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of grishka/NearDrop. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/grishka/NearDrop.git
#   cd NearDrop
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of grishka/NearDrop and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "grishka/NearDrop(\\.git)?\\b" \\
  && ok "origin remote is grishka/NearDrop" \\
  || miss "origin remote is not grishka/NearDrop (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Unlicense)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Unlicense\"" package.json 2>/dev/null) \\
  && ok "license is Unlicense" \\
  || miss "license drift — was Unlicense at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 81 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~51d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/grishka/NearDrop"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

NearDrop is a macOS implementation of Google's Nearby Share protocol that allows users to send files and links between Android devices and macOS computers over Wi-Fi LAN. It runs as a menu bar application, listens for incoming share requests via the Nearby Share protocol (implemented through Protocol Buffers), and saves received files to the Downloads folder. Single macOS app with two main bundles: NearDrop (main app, Swift-heavy at 706KB) and ShareExtension (Finder integration). The core networking logic lives in NearbyShare/ containing NearbyConnectionManager.swift (orchestrator), InboundNearbyConnection.swift and OutboundNearbyConnection.swift (bi-directional communication), and NearbyConnection.swift (base protocol). Protocol Buffers (Protobuf/ directory) define message structures for device discovery and file transfer.

macOS users who want to receive files from Android devices running Google's Nearby Share/Quick Share without needing a Google account or internet connection. Also relevant to security researchers and developers interested in reverse-engineering Google's proprietary sharing protocols.

Actively maintained but limited in scope — single developer (grishka), appears to have stable recent commits based on the Homebrew formula availability. The project is production-ready for its specific use case (Wi-Fi LAN sharing) but explicitly lacks features like visibility controls and multi-transport support that Google's official implementation provides.

Single-maintainer project with no visible CI/CD setup (.github only contains ISSUE_TEMPLATE.md, no workflows). The protocol implementation depends on manually-generated Protocol Buffer files (Protobuf/ directory) that require regeneration via GenerateProtobuf.sh — any upstream protocol changes could break compatibility. Limited test coverage visible in file structure.

No active PR or milestone data visible in the provided file structure. The repo appears in a stable, maintenance mode — the README mentions Wi-Fi LAN as the only supported transport and explicitly documents limitations around Android visibility detection and Bluetooth support as future work.

Clone the repo: git clone https://github.com/grishka/NearDrop.git && cd NearDrop. Open the Xcode project: open NearDrop.xcodeproj. Build and run using Xcode (Cmd+R) or via xcodebuild -scheme NearDrop from the command line. No additional package manager setup required — dependencies are managed via SPM (Package.resolved visible in xcshareddata).

Daily commands: Xcode: open NearDrop.xcodeproj, select NearDrop scheme, press Cmd+R. Command line: xcodebuild -scheme NearDrop -configuration Release to build, then launch the resulting .app from /Build/Products/Release/. The app will appear as a menu bar icon; accept the macOS security prompt on first run.

• NearbyShare/NearbyConnectionManager.swift: Central orchestrator for discovering devices, initiating/accepting connections, and managing inbound/outbound communication flows
• NearbyShare/InboundNearbyConnection.swift: Handles receiving incoming share requests from Android devices and manages the file writing workflow to Downloads folder
• NearbyShare/OutboundNearbyConnection.swift: Manages sending files from macOS to Android devices; used by ShareExtension for Finder integration
• NearbyShare/Protobuf/device_to_device_messages.pb.swift: Auto-generated message definitions for core Nearby Share protocol — changes here require protocol version bumps
• NearDrop/AppDelegate.swift: Application lifecycle and menu bar icon setup; entry point for understanding how the app launches and stays resident
• NearDrop/MainMenu.xib: Menu bar UI definition including share/settings options and status display
• NearbyShare/GenerateProtobuf.sh: Build script to regenerate Protocol Buffer bindings; must be run after any .proto definition changes

Inbound file handling: edit NearbyShare/InboundNearbyConnection.swift. Protocol message definitions: regenerate Protobuf/ files by running NearbyShare/GenerateProtobuf.sh after editing .proto sources (not in repo, likely in ProtobufSource/). UI changes: NearDrop/MainMenu.xib (menu bar) and Localizable.xcstrings (strings). Connection logic: NearbyShare/NearbyConnectionManager.swift for orchestration, NearbyShare/NearbyConnection.swift for base protocol.

1. Protocol Buffers are pre-generated and committed to the repo (Protobuf/ directory) — modifying .proto definitions requires running GenerateProtobuf.sh with a protoc compiler installed, not obvious from the build process. 2) The app requires Wi-Fi LAN connectivity; testing across different network topologies (VPN, 5GHz bands, mesh networks) may have undocumented behavior. 3) macOS Gatekeeper/notarization requirements mean unsigned builds will trigger security warnings — the README explicitly documents this and suggests right-clicking to bypass. 4) No visible test suite in the file structure means changes to core protocol logic (NearbyConnectionManager, message parsing) have no automated validation.

• Protocol Buffers (protobuf) — NearDrop uses .pb.swift files to serialize/deserialize Nearby Share protocol messages — understanding protobuf encoding is essential for debugging protocol compatibility or adding new message types
• Inbound vs Outbound Connection Duality — The split between InboundNearbyConnection and OutboundNearbyConnection reflects the bi-directional nature of Nearby Share — understanding which class handles which direction is critical for adding features like two-way file sync
• Wi-Fi LAN Discovery and mDNS — NearDrop discovers Android devices on the same Wi-Fi network; mDNS/Bonjour is likely used for device advertisement, relevant for understanding network requirements and limitations
• AppKit Menu Bar Applications — NearDrop lives exclusively in the menu bar (no Dock icon) — AppKit's NSStatusBar and MainMenu.xib define the UI and interaction model, essential for understanding the app lifecycle
• Share Extension Architecture — NearDrop includes a ShareExtension bundle for Finder integration — understanding how macOS Share extensions work is necessary for implementing new share sources (e.g., Safari)
• TLS/Encryption Handshake in Peer-to-Peer Contexts — The Nearby Share protocol likely uses ukey.pb.swift (Ukey2 protocol) for secure key exchange between devices — understanding this prevents Man-in-the-Middle attacks during connection setup
• Bridging Swift and Objective-C — NearDrop-Bridging-Header.h bridges to Objective-C code (NDNotificationCenterHackery.m) for accessing macOS APIs unavailable in Swift — this pattern is needed for lower-level system notifications

• google/nearby — Official Google Nearby Interactions framework and documentation; reference for protocol spec and expected behavior
• grishka/Clink — Another project by the same maintainer exploring macOS networking primitives, likely shares protocol reverse-engineering insights
• yushulx/nearby-share-windows — Windows implementation of Nearby Share following similar reverse-engineering approach; cross-platform reference for protocol correctness
• apple/swift-protobuf — Official Swift Protocol Buffer code generator — required to regenerate Protobuf/ files after .proto changes
• alienator88/Sentinel — macOS code-signing utility mentioned in README for bypassing Gatekeeper; companion tool for testing unsigned builds

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for NearbyShare protobuf message parsing and serialization

The NearbyShare/Protobuf directory contains 7 generated .pb.swift files (device_to_device_messages, offline_wire_formats, securegcm, securemessage, sharing_enums, ukey, wire_format) that handle critical protocol communication. There are no visible test files in the repo. Adding comprehensive unit tests would catch regressions in message encoding/decoding and improve reliability of interoperability with Android devices.

• [ ] Create NearbyShareTests/ directory with test target in project.pbxproj
• [ ] Write tests for NearbyShare/Protobuf/device_to_device_messages.pb.swift message construction and serialization
• [ ] Write tests for NearbyShare/Protobuf/securemessage.pb.swift encryption/decryption flows
• [ ] Write tests for NearbyShare/Protobuf/wire_format.pb.swift packet parsing
• [ ] Add GitHub Actions workflow to run tests on PR (since none exist in .github/workflows)

Add integration tests for NearbyConnectionManager connection lifecycle

NearbyShare/NearbyConnectionManager.swift orchestrates the core functionality (InboundNearbyConnection.swift and OutboundNearbyConnection.swift), but there are no visible integration tests verifying the connection handshake, authentication, and file transfer workflows. Tests would validate Wi-Fi LAN discovery, pairing, and data transmission without requiring live Android devices.

• [ ] Create integration test file: NearbyShareTests/NearbyConnectionManagerTests.swift
• [ ] Mock MDNSDiscovery and socket operations to simulate peer discovery
• [ ] Test InboundNearbyConnection initialization and TLS handshake flow
• [ ] Test OutboundNearbyConnection pairing request/response sequences
• [ ] Test end-to-end file transfer with mocked network I/O

Complete the PROTOCOL.md documentation with concrete examples for Wi-Fi LAN discovery and authentication flow

PROTOCOL.md is referenced in the README but the snippet shows it's incomplete (text cuts off mid-sentence: 'Limited visibility (contacts etc) requires...'). The protocol documentation should include specific mDNS service discovery format, TLS certificate pinning approach, and the full authentication handshake sequence. New contributors need this to understand the codebase architecture and contribute fixes.

• [ ] Document the mDNS service name and discovery mechanism (reference NearbyConnectionManager.swift implementation)
• [ ] Add section: 'Wi-Fi LAN Discovery' with TXT record format and service type
• [ ] Add section: 'TLS Handshake and Certificate Pinning' referencing securemessage.pb.swift
• [ ] Add section: 'Authentication Flow' with message sequence diagram (device_to_device_messages.pb.swift messages)
• [ ] Add code examples showing actual protobuf message structures from the generated .pb.swift files
• [ ] Document known Google protocol quirks and macOS-specific limitations mentioned in Limitations section

• Add unit tests for NearbyShare/Data+Extensions.swift parsing logic — the file exists but has no corresponding test file, and Protocol Buffer message parsing is error-prone
• Document the protobuf generation workflow in a CONTRIBUTING.md file with exact command line steps for regenerating after editing NearbyShare/ProtobufSource/ files
• Add localization strings for common error scenarios (network unreachable, permission denied, file write failed) — Localizable.xcstrings exists but may be incomplete for all connection failure states in InboundNearbyConnection.swift

• High · Objective-C Bridge with Potential Runtime Risks — NearDrop/NDNotificationCenterHackery.h, NearDrop/NDNotificationCenterHackery.m. The codebase uses Objective-C bridging (NDNotificationCenterHackery.h/m) to access private APIs. This approach bypasses Apple's public API restrictions and may introduce security vulnerabilities through undocumented behavior changes across macOS versions. The 'hackery' naming suggests awareness of the unconventional nature. Fix: Replace private API usage with public macOS APIs. If unavoidable, implement robust version checking and graceful fallbacks for each macOS version.
• High · Network Visibility Without Authentication — NearbyShare/NearbyConnectionManager.swift, NearbyShare/OutboundNearbyConnection.swift. According to the README, the app is 'Visible to everyone on your network at all times while the app is running' and the protocol documentation mentions limited visibility requires Google server communication. This means the service broadcasts presence without proper access controls, allowing network enumeration and potential MITM attacks from any network participant. Fix: Implement optional PIN-based or password-based authentication before accepting connections. Add optional network access control lists (ACLs) or contact whitelisting. Consider implementing mDNS service discovery with TXT records for capability negotiation.
• High · Wi-Fi Direct Not Supported - Network-Only Vulnerability — README.md, NearbyShare/NearbyConnection.swift. The app is limited to Wi-Fi LAN only, meaning it relies on network availability detection without support for direct device pairing. This creates a vulnerability window where an attacker on the same LAN can intercept, spoof, or perform MITM attacks on the Nearby Share protocol without establishing a direct encrypted tunnel first. Fix: Implement device-to-device encryption using certificate pinning before any file transfer. Use DTLS or similar transport-level encryption. Consider adding optional Bluetooth verification as a secondary channel for authentication.
• Medium · Protobuf-Generated Code Security — NearbyShare/Protobuf/ (all .pb.swift files), NearbyShare/GenerateProtobuf.sh. The codebase auto-generates protobuf Swift files (Protobuf/*.pb.swift) from source proto files. Generated protobuf parsers can be vulnerable to DoS attacks through malformed messages if input validation is insufficient. No visible input sanitization or size limits in the generated code. Fix: Implement message size limits before parsing. Add length validation for repeated fields and string fields. Consider using a safer protobuf runtime or implementing custom validation wrappers around protobuf deserialization.
• Medium · Missing Input Validation on File Operations — NearDrop/AppDelegate.swift, NearbyShare/InboundNearbyConnection.swift. Files are saved directly to the downloads folder without apparent validation of file paths or names. This could allow directory traversal attacks through specially crafted filenames in the Nearby Share protocol, potentially writing files outside the intended downloads directory. Fix: Implement strict path validation using URL(fileURLWithPath:) and verify that all downloaded files remain within the designated downloads directory. Sanitize filenames to remove path traversal sequences like ../ and symbolic links.
• Medium · Share Extension Entitlements Not Verified — ShareExtension/ShareExtension.entitlements, ShareExtension/ShareViewController.swift. The app includes a share extension with its own entitlements file (ShareExtension/ShareExtension.entitlements). Without viewing the contents, there's a risk that the extension may have overly permissive entitlements or may not properly validate content before sharing. Fix: Review entitlements to follow principle of least privilege. Implement content validation before processing shared files. Ensure the extension properly validates sender identity and implements rate limiting.
• Medium · Hardcoded or Default Configuration Values — NearDrop.xcodeproj/xcshareddata/xcschemes/. Xcode build schemes (NearDrop.xcscheme, ShareExtension.xcscheme) and entitlements files may contain hardcoded configuration. Without viewing these files, there's potential for embedded URLs, API endpoints, or default credentials. Fix: Audit all .xcscheme files for hardcoded values. Move any configuration to environment-specific

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.