Reading session API + device bonding

[chocolatkey]

• A new session URL scheme has been added to serve, which allows for retrieval of a Reading Session API document. This is an experimental way of having a JSON object located at a remote URL (http, https) that returns the ebook's real location URL, as well as metadata to override, and rights (limitations) on the session. If you're trying to enforce restrictions seriously, you should use this together with one of the bonding modes below
• Two new modes have been added to serve, jwt-bonding and jwks-bonding. The difference between the two mirrots the jwt and jwks modes. Bonding (which must be combined with the Reading Session API) lets you more strongly tie a reading session (reader URL) to a web browser, through the use of a device cookie and a bonding JWT. Be sure to check out the new params available to tweak settings for sessions/bonding
• The webserver now strives to return problem details in JSON, which should helps clients better understand what the cause of an error is
• A CORS setting (--cors-allowed-origin) is available for serve, for setups requiring CORS
• An HTTP authorization setting (--http-host-authorization) has been added, which will let you add the authorization header to specific hosts you're making requests to. This should help authenticate the reader for the Reading Session API endpoint (or whatever other needs you have like auth for your ebook storage domain)
• H2C (plaintext http2) support has been added to the webserver, for reverse proxies that support it
• HTTP requests made by serve now have a better, more descriptive User-Agent header

[panaC]

Hi Henry, just for my own understanding, do you happen to have any specs or documentation about this? It’s interesting, thank you!

I was looking at the Readium architecture proposals https://readium.org/architecture/proposals/

[chocolatkey]

@panaC There's some docs Hadrien made I'm working off of, in EDRLab's Notion: https://www.notion.so/edrlab/Reading-Session-API-2fba1ca5712f80b5ac32e04a2a9aa593
The JSON schema isn't completely finished IMO

[Copilot]

Pull request overview

This PR adds Reading Session API support and JWT/JWKS device bonding to the publication server, integrating session rights enforcement, session metadata injection, CORS configuration, and problem+json error responses.

Changes:

• Adds reading session document fetching, metadata/link merging, rights enforcement, and cached session handling.
• Refactors auth providers to operate on requests and introduces bonding JWT/device-cookie flows.
• Adds CLI flags for session scheme, bonding configuration, CORS origins, and per-host HTTP authorization.

Reviewed changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pkg/serve/session/session.go	Adds HTTP fetcher for reading session documents.
pkg/serve/session/api.go	Defines reading session document, rights, metadata merge, and rights service injection.
pkg/serve/server.go	Extends server config for session fetcher and CORS origins.
pkg/serve/router.go	Adds CORS middleware and new auth error/problem handling.
pkg/serve/problems/problems.go	Adds RFC 9457 problem response helpers and error mappings.
pkg/serve/client/http_client.go	Updates HTTP client creation to accept host-specific auth map.
pkg/serve/client/http_auth.go	Adds user agent and host-based authorization selection.
pkg/serve/cache/pubcache.go	Stores associated reading session document in cached publications.
pkg/serve/auth/auth.go	Refactors auth provider interface to return updated requests/errors.
pkg/serve/auth/consts.go	Adds auth context keys.
pkg/serve/auth/encoded.go	Updates base64 auth provider to use request context.
pkg/serve/auth/jwt.go	Updates shared-secret JWT auth provider to use request context.
pkg/serve/auth/jwks.go	Updates JWKS auth provider to use request context.
pkg/serve/auth/bonding.go	Adds shared device bonding logic, cookies, bonding JWTs, and bond cache handling.
pkg/serve/auth/jwt_bonding.go	Adds HS256 JWT auth provider with bonding.
pkg/serve/auth/jwks_bonding.go	Adds JWKS-backed JWT auth provider with bonding.
pkg/serve/api.go	Adds session URL resolution, rights refresh, bonding limit enforcement, and problem responses.
internal/cli/serve.go	Adds CLI flags and setup for sessions, bonding, CORS, HTTP auth, and HTTP protocols.
go.mod	Adds new dependencies and updates module/dependency versions.
go.sum	Adds checksums for new and updated dependencies.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[danielweck]

Hello, I noticed the following resolution chain for the blake3 Go dependency:

lukechampine.com/blake3
==>
https://pkg.go.dev/lukechampine.com/blake3
==>
https://github.com/lukechampine/blake3

wouldn't it be safer to skip the "proprietary" domain name (which could expire and become the target of a supply chain attack) and use the GitHub URL directly?

[chocolatkey]

@danielweck I actually did initially attempt to install this using the github path, but as you can see:

go: github.com/lukechampine/blake3@upgrade (v1.4.1) requires github.com/lukechampine/blake3@v1.4.1: parsing go.mod:
        module declares its path as: lukechampine.com/blake3
                but was required as: github.com/lukechampine/blake3

I can't without forking the package. We do at least have the hash in go.sum for "protection" although updates would still need to trust the domain