---
path: /share/[token]
surface: customer
domain: library
auth: signed-in recipient
source: apps/oshun/web/src/app/share/[token]/page.tsx
status: walked
last_walked:
  '2026-07-16 source and existing real-BFF Playwright coverage reviewed; grant
  and insufficient-permission denial are both automated'
---

# 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

- [x] **Granted** — exposes collection id, resolved tier, and resolution
      channel.
- [x] **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`.
- [x] **Privacy boundary** — recipient local Library collections never render on
      the shared-token page.

## Interactions

- [x] **Open my Library / Return to Library** navigates to `/library` with a
      visible, keyboard-reachable link.
- [x] 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.