Connect Discover: define the public listing contract and open read API

[robinbraemer]

Human need

Every Connect discovery surface needs the same stable, open answer to “which owner-published endpoints match this player?” Third parties should not need to scrape the website or obtain endpoint credentials.

Outcome

Define and ship a versioned, unauthenticated, read-only public directory API and canonical listing schema for published Connect endpoints.

Primary implementation areas: minekube/website for the product read model/API, minekube/moxy for timestamped reachability input, and minekube/connect for public documentation.

Contract

• Ordinary HTTPS JSON with a published OpenAPI contract; generated clients are optional conveniences.
• Stable opaque public listing IDs and owner-selected slugs that are not internal database IDs.
• Cursor pagination with deterministic ordering.
• Search plus fixed facets for category, language, edition, Minecraft version, vanilla/modded, loader/modpack compatibility, and online/freshness state.
• Detail lookup, taxonomy discovery, and capability/version negotiation.
• ETag, Last-Modified, Cache-Control, conditional requests, CORS, bounded anonymous rate limits, and documented error envelopes.
• A clear additive-change, deprecation, and API-version policy.

Privacy boundary

Responses must be derived from explicit publication state, never directly from active connector registration. Do not expose tokens, private endpoints, organizations, internal IDs, IPs, connector/libp2p topology, sessions, player identities, friend presence, raw votes, or precise historical activity.

Acceptance criteria

• A contract fixture and threat model exist before implementation.
• Search, detail, facets, pagination, filtering, sorting, caching, rate limiting, and error behavior are covered by executable contract tests.
• Public reads work without an account, cookie, API key, endpoint token, or Minekube-specific SDK.
• Published records contain verified addresses, compatibility, and timestamped coarse status from authoritative sources.
• Unpublished and moderation-removed records return the documented non-enumerable response and disappear from every page/cache/feed within the stated bound.
• Identifier guessing, malformed filters, oversized pages, cache poisoning, scraping bursts, and stale status are tested.
• OpenAPI documentation and minimal curl, Java/Kotlin, Go, and TypeScript examples are public.
• A version skew test proves an older supported client ignores additive fields and receives an actionable response for unsupported breaking versions.
• SLOs cover API availability, p95 latency, cache freshness, status freshness, and delisting propagation.

Non-goals

• Endpoint management or token-bearing operations in the anonymous API.
• Direct access to Moxy's internal registry or database.
• Publishing all active endpoints.

[robinbraemer]

Kickoff: contract-first slice selected

#122 is the highest-leverage first deliverable from #121. The directory, website, mod, Browser Hub, and third-party clients must not invent separate listing shapes or privacy rules.

Authoritative ownership

• The OpenAPI source, public read model, fixtures, and executable API contract tests should land in minekube/website, which owns the product database and public API.
• Moxy should contribute only timestamped, coarse authoritative reachability input; its active connector registry must never become the public listing source.
• minekube/connect, Connect Share, Browser Hub, and third parties consume the published contract and fixtures. They must not scrape dashboard pages or receive token-bearing management access.

First implementation PR

Land the smallest independently reviewable foundation before creating any searchable records:

1. openapi/connect-discover-v1.yaml with search, detail, facets, cursor pagination, conditional reads, version negotiation, and one documented error envelope.
2. Canonical JSON fixtures for a published online Java listing, a published stale/offline cross-edition listing, additive future fields, and non-enumerable unpublished/moderated cases.
3. A threat model proving responses are derived from explicit owner publication state and cannot expose endpoint tokens, internal/private addresses, organization/database identifiers, connector or libp2p topology, sessions, players, friend presence, raw votes, or precise activity history.
4. Executable schema/fixture tests plus negative tests for identifier guessing, oversized pages, malformed filters, unsupported versions, cache variance, and unpublished removal.
5. A decision record for stable opaque IDs, owner slugs, cursor encoding, coarse status/freshness states, cache/delisting bounds, and the additive-change policy.

Definition of ready for downstream consumers

No first-party discovery UI should begin until the fixture suite proves that public reads require no account or credential, unpublished records are non-enumerable, status carries freshness, pagination is deterministic, and older supported clients ignore additive fields safely.

Connect Share PR #94 remains deliberately separate and unmerged while its release gates finish. Share's consented friend presence must never be repurposed as Discover publication state.