infra: align Pebble origins with Nebutra platform hosts (docs/api/status/auth/sso)

[TsekaLuk]

Summary

Align Pebble product URLs and ROADMAP “product origin” language with live Nebutra infrastructure. Platform topology is SoT; pebble.nebutra.com / *.pebble.nebutra.com in ROADMAP are aspirational and currently lack DNS.

Index (updated): docs/reference/infra-index.md
(If not yet on main, use the file in-tree.)

Live platform topology

Cloudflare (edge :443)
  → Vercel (Git-native frontend: landing, docs)
  → ECS 106.15.4.31 (origin: app / auth / api / sso / router / forge)

Host	Role	Port
docs.nebutra.com	Docs (Vercel)	443
api.nebutra.com	API (CF → ECS)	443
status.nebutra.com	Status	443
app.nebutra.com	App RP	443
auth.nebutra.com	Login / session	443
sso.nebutra.com	OIDC issuer (no path prefix, do not casually migrate)	443
www.nebutra.com / landing	Brand	443
pebble.nebutra.com	No DNS today; optional later brand CNAME only	—
Staging pebble subdomain	None — use env/secrets/projects	—

Auth constraints (platform)

• Session held on auth.nebutra.com
• app.nebutra.com is RP; unauthenticated → auth…/sign-in?returnTo=…
• AUTH_COOKIE_DOMAIN=.nebutra.com; both ends BETTER_AUTH_SECRET must match
• sso.nebutra.com = OIDC issuer URL only (never add path)

Recommended mapping (Pebble)

Capability	Stop using (drift)	Prefer
Docs / help	https://pebble.nebutra.com/docs	https://docs.nebutra.com/…
Feedback / diagnostics	product-host paths	https://api.nebutra.com/… (same host for token + upload)
Status	status.pebble.nebutra.com	https://status.nebutra.com
Staging	staging.pebble.nebutra.com	env / project isolation, not a host
Optional brand	full pebble origin stack	CNAME pebble.nebutra.com → CF only

Do not build a parallel api.pebble / status.pebble / staging.pebble stack for v1.

API path decision (needs platform pick)

• Flat: api.nebutra.com/v1/feedback, /diagnostics/*, or
• Prefixed: api.nebutra.com/pebble/v1/…

Local / SSH ports (unchanged)

Service	Port
Local pebble-runtime	17777 (127.0.0.1)
pebble serve / pairing	6768
SSH	22
Public product surface	443 (80 → 443)

ssh -L 17777:127.0.0.1:17777 user@host
ssh -L 6768:127.0.0.1:6768 user@host

Client hardcodes to replace

• feature-wall-tiles.ts / feature-wall-workflows.ts → docs base
• telemetry.ts → privacy URL
• SidebarSettingsHelpMenu.tsx → docs URL
• updater-changelog-selection.ts → changelog host
• package.json homepage

Prefer build-time config: DOCS_ORIGIN, API_ORIGIN, STATUS_ORIGIN.

Acceptance

• docs/reference/infra-index.md reflects platform SoT (topology, auth, ports, mapping)
• ROADMAP product-origin section points at infra-index for live alignment
• Platform freezes API path style (flat vs /pebble)
• Pebble client defaults to live hosts (or configurable origins)
• feedback/diagnostics work on api.nebutra.com without POST redirects
• No requirement for pebble-specific staging subdomain

Non-goals

• Redesigning Better Auth / OIDC issuer URL
• Exposing ECS origin IP publicly
• Orca pairing / LAN (separate product issue)

[TsekaLuk]

Drift fix applied (docs + this issue body).

• Platform SoT: CF → Vercel(landing/docs) + ECS(app/auth/api/sso/router/forge @ 106.15.4.31)
• Live hosts: docs / api / status / app / auth / sso @ *.nebutra.com:443
• No pebble staging subdomain; no live pebble.nebutra.com DNS
• Optimal path: map Pebble onto platform hosts; optional brand CNAME later — see docs/reference/infra-index.md
• ROADMAP product-origin section now has an alignment callout

[TsekaLuk]

Implemented in 77004f5 (this repo) and d7cfb0d2 + 9084a304 in Nebutra/Nebutra-Sailor.

Platform decisions (frozen 2026-07-27)

API path style: prefixed. api.nebutra.com is shared across every Nebutra product, so /v1/* stays unclaimed and each product owns /<product>/v1/*. Routing, rate-limit buckets, and per-product metering stay separable without a later namespace split.

POST api.nebutra.com/pebble/v1/feedback
POST api.nebutra.com/pebble/diagnostics/{token,upload,delete/:ticketId}

pebble.nebutra.com stays, as a brand front only — landing, download, and a docs redirect, with no backend of its own. It is now registered in the platform brand SSOT (brand.domains.pebble) and documented in docs/DOMAINS.md. dns:render previously could only emit ECS surfaces plus a bespoke docs CNAME, so a Vercel-hosted brand front had no way to appear in the zone; it now has a general vercel_surfaces list rather than another one-off field.

Acceptance

• docs/reference/infra-index.md reflects platform SoT — topology, host mapping, auth constraints, ports, client origin config. It declares itself authoritative over ROADMAP.md wherever the two disagree.
• ROADMAP product-origin section has an alignment callout, and the contradicting parts are corrected: the status.pebble / staging.pebble deployment requirement and the five reserved subdomains are gone, and the canonical-route table points at the platform hosts.
• Platform froze the API path style (prefixed — see above).
• Client defaults to live hosts, configurably. All origins now come from packages/product-core/shared/product-origins.ts, which follows the same compile-time-constant idiom as PEBBLE_BUILD_IDENTITY: ambient declarations in build-constants.d.ts, Vite define substitution, production defaults when unset. A fork, self-host, or staging build retargets by exporting PEBBLE_DOCS_ORIGIN / PEBBLE_API_ORIGIN / PEBBLE_STATUS_ORIGIN / PEBBLE_PRODUCT_ORIGIN instead of editing call sites. process.env was not usable here — the renderer bundle has no process.
• feedback/diagnostics working on api.nebutra.com — not done. See below.
• No pebble-specific staging subdomain. Staging is env / secrets / project isolation.

Hardcodes replaced

Beyond the five named in the issue, the sweep also caught the release pipeline and three test surfaces that pinned the old origin:

• feature-wall-tiles.ts, feature-wall-workflows.ts — docs base
• telemetry.ts — PRIVACY_URL
• SidebarSettingsHelpMenu.tsx — docs URL (+ its test expectation)
• updater-changelog-selection.ts — changelog host, now via PRODUCT_HOST
• .github/workflows/tauri-desktop-release.yml — PEBBLE_DIAGNOSTICS_TOKEN_URL
• config/scripts/verify-tauri-mainline.mjs, tauri-release-workflow.test.mjs — the assertions that pinned it
• apps/desktop/src-tauri/src/commands/diagnostics.rs — validate_upload_url tests
• apps/mobile/app/settings.tsx — privacy link (mobile is a separate workspace and cannot read the desktop build constants, so it keeps a literal with a comment saying why)

package.json homepage is unchanged — pebble.nebutra.com is still correct under this decision.

The mainline verifier's changelog gate asserted the literal 'pebble.nebutra.com' inside updater-changelog-selection.ts, which is exactly what the SSOT move removes. It now asserts the wiring (import { PRODUCT_HOST } from './product-origins'), and a new gate pins the actual host defaults and the /pebble namespace in product-origins.ts.

Verification

tsc --noEmit clean; 34 affected test files / 269 tests pass; verify-tauri-mainline.mjs passes every check it applies to this change.

One pre-existing failure is untouched: the legacy-brand-identifier scan flags 15 files (pairing, deep-link, runtime, and now DiffCommentCard.tsx from 8d5b2d6). All are unrelated to origins and none were modified here.

Not done — gateway handlers

The gateway has no feedback or diagnostics routes today, so acceptance item 5 is open. Landing it means a real build, not a path rename: bearer-token issuance, multipart upload (@nebutra/uploads is the natural substrate), delete-by-ticketId, retention policy, and the privacy handling the ROADMAP already specifies. That needs a storage-backend and retention decision first and is better tracked as its own issue.

[TsekaLuk]

Acceptance item 5 is now done — Nebutra/Nebutra-Sailor@d39b1136.

POST /pebble/v1/feedback and POST /pebble/diagnostics/{token,upload,delete/:ticketId} are served directly on api.nebutra.com, no redirects on any machine route.

Shape

Unauthenticated by design — Pebble users have no platform account, and requiring one would mean nobody could report a crash. Abuse is bounded by per-IP limits, exact-size body caps, and single-use tokens rather than identity:

• A token is bound to one ticket and one byte count, so it cannot be replayed against a larger body or a different ticket.
• Content-Length is checked before the body is read, so an oversized upload is refused without buffering it.
• The store transition is guarded on PENDING_UPLOAD, so two concurrent uploads cannot both claim a ticket.
• The upload_url is derived from the request that served the token, which makes it same-host by construction. The client's cross-host check should never be what catches a config mistake.

Privacy

Object keys carry a random component, so nothing is addressable by ticket id alone. Everything the gateway logs passes through a redactor that strips secrets, emails, and local paths — log lines record that a submission happened and how big it was, never what it said. The tables are deliberately not tenant-scoped and not under RLS (there is no signed-in tenant at submission time); access is service-role only, through the repository seam.

Baseline policy, all enforced

10-minute token lifetime · 4 MiB request and stored-object cap · 30-day retention, swept hourly by a pebble-diagnostics-retention job that deletes the object and tombstones the row. Deletion is idempotent and tombstones the row before removing the object — the reverse order could leave a live row pointing at deleted bytes, which reads to a support agent as "still stored". The sweep also collects the two ways a ticket can leak storage: a token issued but never used, and the loser of two concurrent uploads.

Config

PEBBLE_DIAGNOSTICS_TOKEN_SECRET (falls back to SERVICE_SECRET, so a deployment never signs with a known value) and PEBBLE_DIAGNOSTICS_BUCKET (defaults to nebutra-pebble-diagnostics). Migration 20260727000000_add_pebble_support_intake.

Verification

Gateway tsc --noEmit clean; 13 route tests covering the happy path, missing token, oversized body, wrong content type, token replay, idempotent delete, and unknown ticket; architecture and governance gates green.

Two gates needed adjusting rather than working around. The global body limit is 1 MiB, below the 4 MiB contract — rather than raise it for every endpoint in the gateway, the one upload route got its own ceiling. The API-versioning gate expects /api/vN/; Pebble mounts product-first per the frozen decision, and the shipped client pins those exact paths, so /pebble is recorded as intentionally product-versioned.

All six acceptance boxes are now checked.