1# tinyclient23`tinyclient` is the relay website. It includes the HTML templates, styles,4JavaScript modules and embedded browser bundles used by the integrated `tiny`5backend. Pages render on the server and remain readable without JavaScript.6Signing, encrypted messages, uploads and live updates use browser enhancements.78## Build and run910Run these commands from the repository root:1112```sh13go build -o tinyclient-server ./cmd/tinyclient14./tinyclient-server \15 -listen 127.0.0.1:8081 \16 -backend http://127.0.0.1:7447 \17 -public-url https://relay.example18```1920The backend must be the combined `tiny` host (`tiny serve`) from this21repository. Set its `--public-url` to the same `https://relay.example` address.22Route that public23origin to tinyclient through your HTTPS reverse proxy, preserving the Host24header. Keep the backend listener on the private network. The frontend renders25pages and assets locally and forwards relay APIs, WebSocket connections,26streams, signed requests and mutations to the backend.2728For a path-based tenant, include the same path in both URLs:2930```sh31./tinyclient-server \32 -backend http://127.0.0.1:7447/r/team \33 -public-url https://relay.example/r/team34```3536Each process serves one tenant. The root path and `/r/<name>` are supported;37arbitrary mount paths and different frontend and backend tenant paths are not.38A root-mounted frontend rejects `/r/<name>` requests before rendering or39forwarding them. A prefixed frontend accepts only its configured tenant path.40The default listener is `127.0.0.1:8081`. Run `tinyclient-server -help` for flags.4142The binary embeds its assets and needs no working directory, SQLite database,43Git installation or relay signing key at runtime. It requires a running backend44for relay data and session validation. Embedded scripts and icons remain available45when the backend is unavailable. Failure to load the relay snapshot46returns HTTP 502 rather than serving cached private data. It is not an offline client or a frontend for47an arbitrary Nostr relay.4849## Authentication5051Keep the relay's public origin and tenant path unchanged when splitting the52processes. NIP-98 signatures bind the exact URL, method and body. Tinyclient does53not re-sign requests, accept a public key as authentication or translate proofs54between origins. Incoming requests for a different public Host are rejected.55Configure the relay's HTTPS public URL even when the private hop uses HTTP so56it verifies the original scheme and issues secure cookies.5758Browser sessions remain owned, checked and revoked by the relay. The frontend59loads the presentation snapshot through the read-only contract at60`/api/tinyclient` using the browser's session cookie. Anonymous method and typed61reads omit that cookie, including public article feeds requested by signed-in62users. Authenticated reads require the requested actor to match the snapshot's63authenticated actor. The relay derives the actor from the session, checks access64on data reads and redacts private relay metadata. Owner-only settings are not65included in anonymous or nonowner snapshots. Signed operations and relay66protocol traffic retain their authorization headers, paths, query strings and67bodies as they pass upstream. Signed page requests are handled by the integrated68backend renderer rather than replaying a signature across several reads.6970Private pages and authenticated no-JavaScript navigation are supported with a71valid browser session. Creating that session still requires a browser signer.72Pointing the frontend at a different public origin is not a supported migration73path for existing sessions or signed URLs.7475## Embed7677Import `github.com/FelineStateMachine/tinyrelay/tinyclient` and call `New` with a78`Backend` and `Options`. Public `Policy`, `Features`, `CustomView` and room types79let another package implement the interfaces without importing relay-internal80types. `DefaultPolicy` supplies the normal feature settings.8182`Backend.Query` owns authorization for method calls. `Options.Actor` resolves83authenticated requests; it must verify a session or proof, never a caller's84claimed public key. Optional `RoomsReader`, `PrivateReader`,85`AccountPreferencesReader`, `CustomViewSource` and `ChatActivityReader`86interfaces provide typed room reads, membership checks and richer page data.87The remote adapter preserves typed room summaries, folded replies, reaction88counts, activity cards and account preferences.8990`App.BackendHandler()` exposes the read contract for an embedded data service.91`App.ServeHTTP` mounts it automatically. `NewRemote` returns the standalone HTTP92handler for use in another executable.9394The `/api/tinyclient` contract is a project-specific, read-only HTTP extension,95not a Nostr NIP. See the [read-adapter specification](../docs/extensions/tinyclient-read-adapter.md)96for request forms, authorization, errors and compatibility. GET without a method returns the authorized presentation97snapshot. `method` and JSON-array `params` select an allowlisted backend read;98`op=rooms|room|thread|activity` selects a typed read with its room, root, cursor99and limit parameters. Every call resolves authentication at the tinyrelay100backend. This adapter introduces no event kinds, signing formats or storage101identifiers. Frontend validation improves feedback; the backend remains the102authority for protocol validation, membership and mutation permissions.103104## Test and rebuild browser bundles105106```sh107go test ./tinyclient ./cmd/tinyclient108go test ./internal/daemon -run TestStandaloneTinyclient109npm ci110npm run test:tinyclient111npm run build:tinyclient112```113114Go builds use the checked-in browser bundles, so Node.js is not required to build115or run the binary. Rebuild the bundles when their JavaScript sources or pinned116dependencies change. Bundle verification compares regenerated bytes with the117checked-in assets.