harbor-net/.codex/skills/design-harbor-device-ecosystem/SKILL.md

name, description

name	description
design-harbor-device-ecosystem	Use when changing or reviewing Harbor companion-device discovery, pairing, trust, presence, routing handoff, or their API and persistence contracts. Not for traffic-only inventory or visual polish.

Design Harbor Device Ecosystem

Keep discovery, trust, application presence, routing, and LAN observation separate. A device is not trusted because mDNS or the neighbor table reports it, and a paired device is not necessarily connected or routed through this Gateway.

Scope and non-goals

• Apply this skill to Gateway integration with Harbor Connect on macOS and future clients, extensions, appliances, or companion services.
• Keep one platform-neutral protocol core. Isolate native DNS-SD and private-key storage behind thin platform adapters, and state whether a new target is desktop, headless, mobile, or browser-bound before choosing an adapter.
• Preserve the existing MAC-based inventory as an observational traffic and policy surface; do not turn it into ecosystem identity.
• Do not introduce a generic event bus, mesh, cloud account, fleet controller, or WAN discovery without a concrete requirement.
• Do not define a new visible pairing flow, badge, layout, wording, or management surface without the exact owner decision required by workpack/DESIGN_OWNER_POLICY.md.
• Do not deploy, SSH, pair live devices, or operate a live Gateway unless the current user request explicitly authorizes that exact operation.

Workflow

1. Start with the selected workpack task when one exists. Read PRODUCT.md and workpack/PRODUCT_PRIORITIES.md for product scope, workpack/DATA_CONSISTENCY_MODEL.md for persistence or projection changes, and workpack/STATUS.md for active roadmap/cutover work. Any visible UI decision requires workpack/DESIGN_OWNER_POLICY.md; reuse an exact owner decision already recorded for this scope.
2. Read device-ecosystem-contract.md before changing discovery, pairing, identity, presence, routing handoff, or the Gateway device projection.
3. Trace the current producer -> transport -> persistence -> canonical snapshot -> UI path. Confirm the owning service and every caller before editing.
4. Classify each proposed field and state as one of: discovery candidate, persisted trust relationship, authenticated presence lease, route state, network observation, or derived binding. Reject fields that mix categories.
5. Reuse standard DNS-SD/mDNS for local discovery and the existing request/response control-plane shape for the first protocol slice. Do not treat the current plaintext HTTP transport as sufficient protection for invitations or credentials; require pinned end-to-end identity and confidentiality. Add push transport only when a concrete feature cannot work with bounded polling or heartbeats.
6. Keep persisted relationship mutations schema-versioned, atomic, revision-safe, and reversible. Keep transient session loss from deleting paired identity.
7. Join ecosystem membership to network inventory in the backend and expose one revisioned projection. Never join independent authoritative lists in React. Also use design-vpn-client-ui for any visible Connect UI work.
8. For runtime, API, dependency, UI, or deployment changes, also use manage-harbor-versions and run its affected-component gate. Skill-only and documentation-only changes need no Harbor version bump.

Non-negotiable decisions

• Advertise Gateway availability through a versioned DNS-SD service on the local link. Treat every advertisement and resolved address as an untrusted candidate until paired identity is cryptographically verified.
• Put no subscription URL, pairing secret, device list, credential, or private identity material in mDNS/DNS-SD records, logs, fixtures, screenshots, or user-visible diagnostics.
• Pair explicitly. Use a short-lived, single-use invitation; bind the stable Gateway identity and client installation identity; persist each side atomically only after confirmation; make cross-device finalization idempotent and recoverable; support revoke and credential rotation.
• Use a high-entropy QR/manual invitation, or a vetted PAKE plus mutual confirmation for a short human code. Never send a low-entropy code as a bearer secret over unauthenticated HTTP.
• Give every Harbor installation a stable cryptographic device identity. Keep it independent of IP, hostname, interface, and randomized MAC.
• Define states precisely: discovered means advertised; paired means a persisted trust relationship; connected means a current authenticated lease; routed means this Gateway is the active route. Never collapse them into one online boolean.
• Derive lease freshness from Gateway receipt time. Do not trust a client-supplied clock, IP address, or MAC address as authoritative.
• Correlate a paired client with the existing neighbor inventory only as a derived, confidence-bearing binding. A missing or ambiguous binding must not erase membership or fabricate traffic attribution.
• Allow a client to pair with multiple Gateways, but keep one explicit active routing target. A discovered or unpaired Gateway must never hijack route selection.
• Preserve legacy subscription-based presence only as a bounded transition path. Never silently convert matching subscription URLs into permanent pairing records.
• Keep capability advertisement versioned and additive. Ignore unknown capabilities; block incompatible protocol versions explicitly. Never authorize a mutation from self-declared capabilities alone.
• Keep the Gateway backend as the source of truth for its paired-device registry and active leases. Preserve revision-safe frontend application and transport freshness separation.

Acceptance pass

Verify the affected contracts below. Protocol, authentication, shared projection, or migration changes require coverage across the impacted lifecycle; a documentation-only correction uses consistency/link checks. Do not operate live devices without the exact authorization described above:

• A supported client can discover more than one Gateway and survives address changes without changing Gateway identity.
• Spoofed discovery cannot create trust, change the active route, or appear as a paired ecosystem member.
• Pairing works without a subscription URL; invitations expire, are single-use, and reject replay.
• The Gateway can distinguish an ordinary LAN neighbor, a paired but disconnected device, a connected Harbor client, and a client currently routed through it.
• A paired Mac remains the same ecosystem device across DHCP, interface, or randomized-MAC changes; only its derived inventory binding changes.
• Discovery loss does not unpair a device; heartbeat loss expires the lease; revocation rejects the next authenticated request immediately.
• Multiple Gateways and multiple clients do not collide. Any aggregate network identity includes Gateway scope.
• Persisted writes are atomic and migrated with rollback; delayed snapshots cannot overwrite newer state.
• Legacy installs retain the documented transition behavior without exposing or copying subscription secrets.
• Automated tests cover discovery deduplication, pairing expiry/replay, authentication, lease expiry, revocation, binding ambiguity, revision ordering, and migration.
• Any visible UI outcome has a separately recorded owner decision and preserves loading, empty, stale, error, keyboard, reduced-motion, and responsive behavior.

Output contract

Report:

• current owner and traced data flow;
• chosen source of truth for identity, trust, presence, route, and inventory binding;
• protocol and persistence changes, including version negotiation;
• migration, compatibility, rollback, and security boundaries;
• exact automated checks and what remains unverified;
• unresolved owner decisions, especially visible UI and short-code pairing treatment.