feat(analytics): download a session's recording under --experimental-auth

[Topherhindman]

Fixes DEVX-799
Depends on livekit/public-api-server#49.

lk analytics session recording SESSION_ID --type audio|chat-history asks the Public API to sign a URL for a session's recording, then downloads it straight from the project's data region. Nothing passes through the API, and the user's session token never reaches the object store.

What changed

• Regenerated client (chore(public)): oapi.gen.go is regenerated from livekit/public-api-server@7f379db, livekit/public-api-server#49's merge commit on main. It picks up GetSessionRecordingURL's response as the server now returns it: the URL's expires_at and the recording's recording_started_at replace created_at. The operation's docs now say a missing recording is NotFound and the expiry is clamped to 15 minutes. Nothing hand-written reads the changed types, so only oapi.gen.go changes.
• Client (feat(public)):
  • GetSessionRecordingURL takes the recording by name, audio or chat-history, and rejects any other before sending a request. It returns the signed URL, its expiry and when the recording started.
  • DownloadRecording fetches the signed URL with no credentials, since the signature is the authorization. It uses its own http.Client, so no cookie jar or transport set elsewhere in the process can add any. A stalled object store times out (30s to answer, 10 minutes for the whole download) instead of hanging lk.
  • No signature in errors: a *url.Error loses the URL's query string, and long query values are hidden where an object store's error page echoes them.
  • Chat history: it's stored gzip-encoded, so a gzip body is decompressed whether or not the transport already did. A refused URL is an error naming the status, never a saved error page.
  • APIError keeps the error envelope's typed details. ObservabilityDisabled reads the dashboard link from the FailedPrecondition the server returns when user data recording is off. IsNotFound recognizes a missing recording.
• Command (feat(analytics)):
  • Files: audio saves as SESSION_ID-audio.ogg, and chat history, decompressed, as SESSION_ID-chat-history.json. A file already at the default name is never replaced: the command refuses before asking for a URL and says to pass -o. A file -o FILE names is replaced, since the user chose it.
  • Atomic save: the download lands in a hidden temporary file that is renamed into place when complete. A failed download leaves no partial file and keeps an existing one.
  • --url-only prints the signed URL on stdout, so it pipes into curl, and its expiry on stderr. --json prints the API's response, or after a download, the saved file, its size and when the recording started.
  • Errors:
    • A missing recording says the session wasn't recorded, has expired, or ended less than a minute ago, or that there's no such session in the project, which it names. The API answers both the same way.
    • With user data recording off, it says so and links the project's observability settings.
    • A permission denial says reading the recording requires being a project admin. sessionAPIError now takes the access a read requires, and the participant list keeps saying the user doesn't have access to the project.
  • Only the Public API signs recording URLs, so the command runs only under --experimental-auth, through sessionRead.

Usage

lk --experimental-auth analytics --experimental session recording SESSION_ID \
    --type audio|chat-history [-o FILE] [--url-only] [--json]

$ lk --experimental-auth analytics --experimental session recording RM_1 --type chat-history
Saved chat history of session RM_1 to RM_1-chat-history.json (2.0 KB)
The recording started 2026-10-07 11:00

With --json:

{"sessionId":"RM_1","recording":"chat-history","file":"RM_1-chat-history.json","bytes":2048,"recordingStartedAt":"2026-10-07T11:00:00Z"}

Since review

• 80ff1a3 fix(analytics): name the project when a recording isn't found

Testing

• go build ./..., go vet ./pkg/... ./cmd/lk/ and go test ./pkg/... ./cmd/lk/ pass on every commit.
• New tests:
  • pkg/public: TestGetSessionRecordingURL, TestGetSessionRecordingURLRejectsUnknownRecording, TestGetSessionRecordingURLMissingURL, TestGetSessionRecordingURLErrors, TestDownloadRecording (gzip handling), TestDownloadRecordingRefused, TestDownloadRecordingSendsNoCredentials and TestDownloadRecordingErrorsHideSignature.
  • pkg/public/render: TestRecordingURL and TestRecordingSaved.
  • cmd/lk: TestSessionRecordingCommand, TestSessionRecordingRequiresExperimentalAuth, TestSessionRecordingOptions, TestFetchSessionRecording, TestFetchSessionRecordingURLOnly, TestFetchSessionRecordingJSON, TestFetchSessionRecordingNothingToDownload, TestFetchSessionRecordingDownloadFails, TestFetchSessionRecordingExistingFile and TestDefaultRecordingFile.
• The command above was run on staging on 2026-10-08, against public-api-server's stack run locally, with a real sign-in and staging data.
• Known issue on staging: an expired recording's signed URL returns 404, so the download fails naming that status. That's on the server side, not in this command.