Shared collection token

Purpose#

Recipient-side resolution page for a tokenized Library collection share. It asks the BFF to resolve the supplied token and permission requirement, then shows a compact grant or denial without mounting the recipient's personal collection state.

Entry points#

• A generated webHref from CollectionShareControls, typically /share/<token>?target=collection&collectionId=<id>.
• Optional requiredPermission=view|comment|copy raises the permission needed for this visit.
• Universal-link and deep-link associations recognize /share/*.

Layout regions#

• Shell: Library-active ShellLayout with Home → Shared collection breadcrumbs.
• Resolution surface: status icon, eyebrow, grant/denial heading, concise explanation, and a two-column fact list that collapses responsively.
• Exit: Open my Library on success; Return to Library on denial.

States#

• Granted — exposes collection id, resolved tier, and resolution channel.
• Insufficient permission — names both the granted and required tiers.
• Invalid target — any non-collection target or missing collection id becomes invalid-share-target.
• Invalid, expired, revoked, or unknown token — reason comes from the share-policy engine and is rendered as readable words.
• BFF unavailable — fails closed with share-resolution-unavailable.
• Privacy boundary — recipient local Library collections never render on the shared-token page.

Interactions#

• Open my Library / Return to Library navigates to /library with a visible, keyboard-reachable link.
• The page performs no client mutation and exposes no share-administration controls to the recipient.

Data & contracts#

• Reads: server-side GET /v1/library/shared/:collectionId with token and optional requiredPermission; forwards the access-token cookie when present.
• Response: { granted: true, collectionId, tier, via } or a denial carrying reason and optional tier / requiredPermission.
• Caching: dynamic = 'force-dynamic', cache: 'no-store'.
• Auth: the BFF resolution route requires a signed-in recipient even though the share token supplies collection permission.

Cross-references#

• Sender controls: apps/oshun/web/src/components/library/CollectionShareControls.tsx
• BFF route: apps/oshun/bff/src/routes/library-sharing.ts
• Policy engine: apps/oshun/bff/src/library/share-policy-store.ts
• Browser coverage: apps/oshun/web/e2e/library-shared-web-view.spec.ts
• Journey: WALKTHROUGH/journeys/library-save-collection-share.md

Open questions / known gaps#

• Add an explicit signed-out handoff message if product policy should permit opening a shared link before authentication and resuming afterward.