feat(export): server-rendered artifacts behind one signed download URL (#160)

The finished-game export (GCG + a new PNG of the final position) is one
signed, short-lived relative URL (game.export_url; HMAC-SHA256, 10-min
TTL, BACKEND_EXPORT_SIGN_KEY) resolved against the client's own origin
and delivered by the best affordance each platform has (five on-device
review rounds):

- TG Android/desktop: native showPopup chooser -> native downloadFile
  dialog (bridge-only chain, activation-safe).
- TG iOS: app-modal chooser -> OS share sheet with the fetched file
  (a popup callback cannot supply the activation the sheet needs).
- VK iOS: VKWebAppDownloadFile for both formats.
- VK Android: the PNG opens in VK's native image viewer, the GCG copies
  to the clipboard (the VK Android downloader hangs on any download,
  Content-Length/Range notwithstanding).
- VK desktop iframe / desktop browsers: plain anchor downloads.
- Mobile browsers: the OS share sheet (fetch-then-share).
- Legacy TG (< Bot API 8.0): app modal + GCG clipboard, no image option.

The PNG is rasterized on demand by the new internal `renderer` sidecar
(node:22-slim + skia-canvas + baked Liberation/Noto Color Emoji fonts)
executing the SAME ui/src/lib/gameimage.ts the ui project unit-tests;
the backend rebuilds the render payload from the journal +
engine.AlphabetTable, and the device date locale, IANA time zone and
localized non-play labels ride the signed URL. Nothing is stored — the
artifact re-derives from the immutable journal on each GET. The gateway
forwards /dl/* (caddy @gateway matcher extended) behind the per-IP
public rate limiter and serves bytes via http.ServeContent.

Deploy: renderer service in compose + prod overlay + rolling order +
prod push list; TEST_/PROD_EXPORT_SIGN_KEY secrets; the sidecar smoke
runs in the ui CI job. Docs: ARCHITECTURE, FUNCTIONAL(+_ru), UI_DESIGN,
TESTING, deploy/README, renderer/README.

gateway/internal/backendclient/api_social.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"net/http"
 	"net/url"
+	"strings"
 )
 
 // The response structs and client methods mirror the backend's social,
@@ -347,3 +348,28 @@ func (c *Client) ExportGCG(ctx context.Context, userID, gameID string) (GcgResp,
 	err := c.do(ctx, http.MethodGet, c.gamePath(gameID, "/gcg"), userID, "", nil, &out)
 	return out, err
 }
+
+// ExportURLResp is the minted signed download link for an export artifact.
+type ExportURLResp struct {
+	Path     string `json:"path"`
+	Filename string `json:"filename"`
+}
+
+// ExportURL mints a signed download URL for a finished game's artifact (kind
+// "png" or "gcg"). dateLocale and the localized non-play labels ride the URL so
+// the server render matches the player's presentation.
+func (c *Client) ExportURL(ctx context.Context, userID, gameID, kind, dateLocale, timeZone string, labels []string) (ExportURLResp, error) {
+	q := url.Values{"kind": {kind}}
+	if dateLocale != "" {
+		q.Set("dl", dateLocale)
+	}
+	if timeZone != "" {
+		q.Set("tz", timeZone)
+	}
+	if len(labels) > 0 {
+		q.Set("t", strings.Join(labels, ","))
+	}
+	var out ExportURLResp
+	err := c.do(ctx, http.MethodGet, c.gamePath(gameID, "/export-url")+"?"+q.Encode(), userID, "", nil, &out)
+	return out, err
+}

gateway/internal/backendclient/client.go

@@ -39,10 +39,18 @@ const backendMaxIdleConns = 512
 type Client struct {
 	baseURL string
 	http    *http.Client
-	conn    *grpc.ClientConn
-	push    pushv1.PushClient
+	// dl serves the export downloads: the backend may wait on the render sidecar
+	// for several seconds, so these calls get their own, longer deadline than the
+	// ordinary REST budget.
+	dl   *http.Client
+	conn *grpc.ClientConn
+	push pushv1.PushClient
 }
 
+// exportDownloadTimeout bounds one export-download fetch end to end (the backend's
+// own sidecar budget is 15s).
+const exportDownloadTimeout = 30 * time.Second
+
 // New dials the backend push gRPC endpoint and prepares the REST client. The
 // backend lives on a trusted network segment, so the gRPC connection uses
 // insecure (plaintext) transport credentials (ARCHITECTURE.md §12).
@@ -62,11 +70,39 @@ func New(httpURL, grpcAddr string, timeout time.Duration) (*Client, error) {
 	return &Client{
 		baseURL: strings.TrimRight(httpURL, "/"),
 		http:    &http.Client{Timeout: timeout, Transport: transport},
+		dl:      &http.Client{Timeout: exportDownloadTimeout, Transport: transport},
 		conn:    conn,
 		push:    pushv1.NewPushClient(conn),
 	}, nil
 }
 
+// ExportDownload fetches a signed finished-game export artifact from the backend's
+// public group, forwarding the caller's public Host for the image footer. It returns
+// the bytes with the backend's Content-Type and Content-Disposition. rest is the
+// public path suffix after /dl (e.g. "/<game>/<kind>?e=…&s=…").
+func (c *Client) ExportDownload(ctx context.Context, rest, publicHost string) ([]byte, string, string, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/api/v1/public/dl"+rest, nil)
+	if err != nil {
+		return nil, "", "", fmt.Errorf("backendclient: new request: %w", err)
+	}
+	if publicHost != "" {
+		req.Header.Set("X-Public-Host", publicHost)
+	}
+	resp, err := c.dl.Do(req)
+	if err != nil {
+		return nil, "", "", fmt.Errorf("backendclient: GET export: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	data, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, "", "", fmt.Errorf("backendclient: read export: %w", err)
+	}
+	if resp.StatusCode >= http.StatusMultipleChoices {
+		return nil, "", "", parseAPIError(resp.StatusCode, data)
+	}
+	return data, resp.Header.Get("Content-Type"), resp.Header.Get("Content-Disposition"), nil
+}
+
 // Close releases the gRPC connection.
 func (c *Client) Close() error { return c.conn.Close() }
 

gateway/internal/connectsrv/server.go

@@ -7,6 +7,7 @@
 package connectsrv
 
 import (
+	"bytes"
 	"context"
 	"crypto/subtle"
 	"encoding/json"
@@ -193,6 +194,7 @@ func (s *Server) HTTPHandler() http.Handler {
 	// The client-side local move preview pulls each game's pinned dictionary blob
 	// through this session-gated route (not public); see dictBytesHandler.
 	mux.Handle("/dict/", s.dictBytesHandler())
+	mux.Handle("/dl/", s.exportDownloadHandler())
 	// The client posts its local-move-preview adoption telemetry here (session-gated).
 	mux.Handle("/metrics/local-eval", s.localEvalMetricsHandler())
 	// The embedded UI: the game SPA under /app/ (web), /telegram/ (the Telegram Mini
@@ -415,6 +417,63 @@ func (s *Server) limitAdmin(next http.Handler) http.Handler {
 // user-class limiter, and forwards the backend's immutable Cache-Control so the
 // browser caches the blob hard. Only GET is allowed; the path is
 // /dict/{variant}/{version}.
+// exportDownloadHandler serves the signed finished-game export downloads (/dl/*).
+// It is the gateway's only unauthenticated data route: the platforms' native
+// download calls (Telegram downloadFile, VKWebAppDownloadFile, a plain anchor)
+// carry no session, so the URL's HMAC — verified by the backend — is the whole
+// grant. The gateway only rate-limits by IP and forwards, passing the public Host
+// along for the image footer.
+func (s *Server) exportDownloadHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if s.backend == nil {
+			http.NotFound(w, r)
+			return
+		}
+		if r.Method != http.MethodGet {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		ip := peerIP(r.RemoteAddr, r.Header)
+		if !s.limiter.Allow("public:"+ip, s.publicPolicy) {
+			s.noteRateLimited(r.Context(), classPublic, ip, "export-dl")
+			http.Error(w, "rate limited", http.StatusTooManyRequests)
+			return
+		}
+		rest := strings.TrimPrefix(r.URL.Path, "/dl")
+		if rest == "" || rest == "/" {
+			http.NotFound(w, r)
+			return
+		}
+		if r.URL.RawQuery != "" {
+			rest += "?" + r.URL.RawQuery
+		}
+		data, contentType, disposition, err := s.backend.ExportDownload(r.Context(), rest, r.Host)
+		if err != nil {
+			var apiErr *backendclient.APIError
+			if errors.As(err, &apiErr) && apiErr.Status < http.StatusInternalServerError {
+				http.NotFound(w, r) // invalid, expired or unknown link
+				return
+			}
+			s.log.Warn("export download failed", zap.Error(err))
+			http.Error(w, "bad gateway", http.StatusBadGateway)
+			return
+		}
+		if contentType != "" {
+			w.Header().Set("Content-Type", contentType)
+		}
+		if disposition != "" {
+			w.Header().Set("Content-Disposition", disposition)
+		}
+		w.Header().Set("X-Content-Type-Options", "nosniff")
+		w.Header().Set("Cache-Control", "private, max-age=0")
+		// ServeContent (not a bare Write): the platforms' native downloaders are picky —
+		// Android's system DownloadManager (the VKWebAppDownloadFile executor) hangs on a
+		// chunked body of unknown length and may probe with Range. ServeContent emits
+		// Content-Length, honours Range/If-* and answers 206s from the buffered artifact.
+		http.ServeContent(w, r, "", time.Time{}, bytes.NewReader(data))
+	})
+}
+
 func (s *Server) dictBytesHandler() http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if s.backend == nil {

gateway/internal/transcode/encode_social.go

@@ -251,6 +251,18 @@ func encodeInvitationList(r backendclient.InvitationListResp) []byte {
 	return b.FinishedBytes()
 }
 
+// encodeExportURL builds an ExportUrl payload.
+func encodeExportURL(r backendclient.ExportURLResp) []byte {
+	b := flatbuffers.NewBuilder(256)
+	path := b.CreateString(r.Path)
+	fn := b.CreateString(r.Filename)
+	fb.ExportUrlStart(b)
+	fb.ExportUrlAddPath(b, path)
+	fb.ExportUrlAddFilename(b, fn)
+	b.Finish(fb.ExportUrlEnd(b))
+	return b.FinishedBytes()
+}
+
 // encodeGcg builds a GcgExport payload.
 func encodeGcg(r backendclient.GcgResp) []byte {
 	b := flatbuffers.NewBuilder(1024)

gateway/internal/transcode/transcode_social.go

@@ -31,6 +31,7 @@ const (
 	MsgProfileUpdate     = "profile.update"
 	MsgStatsGet          = "stats.get"
 	MsgGameGCG           = "game.gcg"
+	MsgGameExportURL     = "game.export_url"
 )
 
 // registerSocialOps adds the social, account and history operations to the
@@ -56,6 +57,7 @@ func registerSocialOps(r *Registry, backend *backendclient.Client) {
 	r.ops[MsgProfileUpdate] = Op{Handler: profileUpdateHandler(backend), Auth: true}
 	r.ops[MsgStatsGet] = Op{Handler: statsHandler(backend), Auth: true}
 	r.ops[MsgGameGCG] = Op{Handler: gcgHandler(backend), Auth: true}
+	r.ops[MsgGameExportURL] = Op{Handler: exportURLHandler(backend), Auth: true}
 }
 
 // --- friends ---
@@ -290,6 +292,21 @@ func gcgHandler(backend *backendclient.Client) Handler {
 	}
 }
 
+func exportURLHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsExportUrlRequest(req.Payload, 0)
+		labels := make([]string, 0, in.ActionLabelsLength())
+		for i := range in.ActionLabelsLength() {
+			labels = append(labels, string(in.ActionLabels(i)))
+		}
+		res, err := backend.ExportURL(ctx, req.UserID, string(in.GameId()), string(in.Kind()), string(in.DateLocale()), string(in.TimeZone()), labels)
+		if err != nil {
+			return nil, err
+		}
+		return encodeExportURL(res), nil
+	}
+}
+
 // decodeInviteeIDs reads the invitee id vector from a CreateInvitationRequest.
 func decodeInviteeIDs(in *fb.CreateInvitationRequest) []string {
 	n := in.InviteeIdsLength()

gateway/internal/transcode/transcode_social_test.go

@@ -263,6 +263,54 @@ func TestGcgRoundTrip(t *testing.T) {
 	}
 }
 
+func TestExportURLRoundTrip(t *testing.T) {
+	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/v1/user/games/g-1/export-url" {
+			t.Errorf("unexpected path %q", r.URL.Path)
+		}
+		q := r.URL.Query()
+		if q.Get("kind") != "png" || q.Get("dl") != "ru-RU" || q.Get("tz") != "Europe/Moscow" || q.Get("t") != "пас,обмен,сдался,таймаут" {
+			t.Errorf("unexpected query %q", r.URL.RawQuery)
+		}
+		_, _ = w.Write([]byte(`{"path":"/dl/g-1/png?e=1&s=x","filename":"game-g-1.png"}`))
+	})
+	defer cleanup()
+
+	reg := transcode.NewRegistry(backend, nil)
+	op, _ := reg.Lookup(transcode.MsgGameExportURL)
+
+	b := flatbuffers.NewBuilder(256)
+	gid := b.CreateString("g-1")
+	kind := b.CreateString("png")
+	dl := b.CreateString("ru-RU")
+	tz := b.CreateString("Europe/Moscow")
+	labels := make([]flatbuffers.UOffsetT, 0, 4)
+	for _, s := range []string{"пас", "обмен", "сдался", "таймаут"} {
+		labels = append(labels, b.CreateString(s))
+	}
+	fb.ExportUrlRequestStartActionLabelsVector(b, len(labels))
+	for i := len(labels) - 1; i >= 0; i-- {
+		b.PrependUOffsetT(labels[i])
+	}
+	vec := b.EndVector(len(labels))
+	fb.ExportUrlRequestStart(b)
+	fb.ExportUrlRequestAddGameId(b, gid)
+	fb.ExportUrlRequestAddKind(b, kind)
+	fb.ExportUrlRequestAddDateLocale(b, dl)
+	fb.ExportUrlRequestAddActionLabels(b, vec)
+	fb.ExportUrlRequestAddTimeZone(b, tz)
+	b.Finish(fb.ExportUrlRequestEnd(b))
+
+	payload, err := op.Handler(context.Background(), transcode.Request{UserID: "u-1", Payload: b.FinishedBytes()})
+	if err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+	res := fb.GetRootAsExportUrl(payload, 0)
+	if string(res.Path()) != "/dl/g-1/png?e=1&s=x" || string(res.Filename()) != "game-g-1.png" {
+		t.Fatalf("export url decoded wrong: path=%q filename=%q", res.Path(), res.Filename())
+	}
+}
+
 func TestProfileUpdateRoundTripAway(t *testing.T) {
 	var gotBody map[string]any
 	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {