You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
How does the server issue and check the signed position URL? #424
How does the server issue and check the signed position URL that lets Cup's Android plugin save the listening position without the page's Supabase session?
The engine decision in Which engine plays the narration track in Cup's Android app? fixes its scope (one listener, one audiobook) and lifetime (the track URL's). Open: which response carries it, its form (a URL with a token like the signed media URL, or a separate token), the route that accepts it and how it relates to today's authenticated position save, what it may write (only a position for that audiobook, last write wins or not), and how it behaves for anonymous and trial listeners who have no account.
Written by @patricktree's agent (Claude Code, Claude Opus 5.5).
Carrier. The audiobook response carries the signed position URL as narrationTrack.positionUrl, next to narrationTrack.url. The server issues it whenever it issues a track URL to an account principal, on every platform, because it doesn't know the client's platform; browsers ignore it. Responses to a trial (grant) principal leave it out.
Form and token. It is a URL to the existing route: PUT /api/audiobooks/{conversionId}/position?token=…. The token has the signed media URL's format, key (MEDIA_URL_SIGNING_KEY), issue time (start of the UTC day) and 48 h expiry, but its payload adds "purpose": "position". Media routes reject any token that carries a purpose, and the position route accepts only position tokens, so a track URL can't write positions and a position URL can't fetch media. Today's media tokens stay byte-identical.
One route, two credentials. The route accepts exactly one of the bearer token or ?token=; a request with both or neither answers 401. The existing browser-mutation check (the X-Create-Audiobook-From-URL-Request header, JSON content type, and an allowed Origin if present) applies to both, so the plugin sends the header and no Origin.
Checks with a token, in order:
Signature, expiry, purpose, and the token's conversionId matching the route's, else 401 position-url-invalid.
The principal is an active account that owns the conversion, answering as the media route does: 404 when it doesn't own the conversion or the conversion was deleted, and the blocked answer when account deletion is scheduled.
The synchronization unit exists, else 400, as today.
The bearer path gains the same ownership check. Today it saves a position for any ready conversion ID.
What it may write. Only that audiobook's listening position for that account. The body is unchanged (synchronizationUnitId + offsetMilliseconds), and saves stay last write wins, with no ordering field or timestamp. Whoever saves converts the track position into a unit and offset with narrationTrack.startMilliseconds. If the plugin saves, load must carry those offsets, which Who saves the listening position in Cup's Android app, and how does the page take over from the native player? decides, together with ordering between the page's and the native saves during a handover.
Revocation. Like the signed media URL, it is a stateless bearer credential for its lifetime. Local sign-out doesn't invalidate it; the plugin drops it on close(). Only scheduling account deletion, losing ownership (deleting the conversion), or rotating the signing key stops it. Workers Logs and traces already redact query strings.
Anonymous and trial listeners. No account means no position URL. Trial audiobooks don't reach the apps (ADR 0017), and no audiobook is public yet. Where an anonymous Android listener's position lives, if such a listener exists with the native engine, is left to the ownership ticket above.
Written by @patricktree's agent (Claude Code, Claude Opus 5.5).
Activity
patricktree commentedon Nov 16, 2026
Resolution
Grilled with the operator on 2026-11-16.
Carrier. The audiobook response carries the signed position URL as
narrationTrack.positionUrl, next tonarrationTrack.url. The server issues it whenever it issues a track URL to an account principal, on every platform, because it doesn't know the client's platform; browsers ignore it. Responses to a trial (grant) principal leave it out.Form and token. It is a URL to the existing route:
PUT /api/audiobooks/{conversionId}/position?token=…. The token has the signed media URL's format, key (MEDIA_URL_SIGNING_KEY), issue time (start of the UTC day) and 48 h expiry, but its payload adds"purpose": "position". Media routes reject any token that carries a purpose, and the position route accepts only position tokens, so a track URL can't write positions and a position URL can't fetch media. Today's media tokens stay byte-identical.One route, two credentials. The route accepts exactly one of the bearer token or
?token=; a request with both or neither answers401. The existing browser-mutation check (theX-Create-Audiobook-From-URL-Requestheader, JSON content type, and an allowedOriginif present) applies to both, so the plugin sends the header and noOrigin.Checks with a token, in order:
conversionIdmatching the route's, else401 position-url-invalid.404when it doesn't own the conversion or the conversion was deleted, and the blocked answer when account deletion is scheduled.400, as today.The bearer path gains the same ownership check. Today it saves a position for any ready conversion ID.
What it may write. Only that audiobook's listening position for that account. The body is unchanged (
synchronizationUnitId+offsetMilliseconds), and saves stay last write wins, with no ordering field or timestamp. Whoever saves converts the track position into a unit and offset withnarrationTrack.startMilliseconds. If the plugin saves,loadmust carry those offsets, which Who saves the listening position in Cup's Android app, and how does the page take over from the native player? decides, together with ordering between the page's and the native saves during a handover.Revocation. Like the signed media URL, it is a stateless bearer credential for its lifetime. Local sign-out doesn't invalidate it; the plugin drops it on
close(). Only scheduling account deletion, losing ownership (deleting the conversion), or rotating the signing key stops it. Workers Logs and traces already redact query strings.Anonymous and trial listeners. No account means no position URL. Trial audiobooks don't reach the apps (ADR 0017), and no audiobook is public yet. Where an anonymous Android listener's position lives, if such a listener exists with the native engine, is left to the ownership ticket above.
Written by @patricktree's agent (Claude Code, Claude Opus 5.5).