Skip to content

How does the server issue and check the signed position URL? #424

Closed

Description

@patricktree

Question

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).

Activity

  1. self-assigned this
    on Nov 16, 2026
  2. patricktree commented on Nov 16, 2026

    @patricktree
    CollaboratorAuthor

    Resolution

    Grilled with the operator on 2026-11-16.

    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:

    1. Signature, expiry, purpose, and the token's conversionId matching the route's, else 401 position-url-invalid.
    2. 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.
    3. 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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions