From f49080558b2bd194620cbf88cd44cda338fb4b55 Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Thu, 23 Jul 2026 21:31:57 -0400 Subject: [PATCH] docs: add BitUnlock permission layer plan --- docs/BITUNLOCK_PERMISSION_LAYER_PLAN.md | 522 ++++++++++++++++++++++++ 1 file changed, 522 insertions(+) create mode 100644 docs/BITUNLOCK_PERMISSION_LAYER_PLAN.md diff --git a/docs/BITUNLOCK_PERMISSION_LAYER_PLAN.md b/docs/BITUNLOCK_PERMISSION_LAYER_PLAN.md new file mode 100644 index 00000000..076043a3 --- /dev/null +++ b/docs/BITUNLOCK_PERMISSION_LAYER_PLAN.md @@ -0,0 +1,522 @@ +# BitVid BitUnlock permission-layer plan + +Status: proposed application architecture and implementation plan, 2026-07-23. + +BitVid should evolve from a public Nostr video client into a creator-controlled media platform that +supports public media, purchases, rentals, creator memberships, platform subscriptions, bundles, and +pay-per-view access. BitUnlock is the reusable payment-verification and permission layer beneath those +features. + +The architectural rule is: + +> **BitVid owns media behavior. BitUnlock owns payment-backed permission.** + +Related projects and documents: + +- BitUnlock `docs/STREAMING_SUBSCRIPTION_ACCESS_PROFILE.md` — generic entitlement and streaming-access profile. +- BitUnlock `docs/GATED_ACCESS_PLATFORM_PLAN.md` — renewable/revocable entitlements and relying-party verification. +- BitUnlock `docs/ACCESS_GRANTS_PLAN_V2.md` — bring-your-own-storage capability patterns. +- BitUnlock `docs/SECURITY_AUDIT_AND_RESILIENCE_PLAN.md` — security, migration, backup, and recovery gates. +- BitVid [`nostr-event-schemas.md`](./nostr-event-schemas.md) — current NIP-71 event behavior. +- BitVid [`playback-fallback.md`](./playback-fallback.md) — current URL/WebTorrent playback behavior. + +## 1. Product direction + +BitVid remains a Nostr-native, creator-controlled video application, but its access model expands from +"public or hidden" into a general policy system. + +BitVid should support: + +- public videos; +- login-only videos; +- permanent individual purchases; +- time-limited rentals; +- creator memberships; +- platform-wide subscription catalogs; +- bundles, seasons, courses, and collection passes; +- pay-per-view premieres and livestreams; +- patron/supporter tiers; +- free previews and delayed public release; +- future prepaid or metered viewing where economically appropriate. + +A single video may accept several routes. For example, a viewer may qualify through an individual +purchase, an active rental, a creator membership, or a platform subscription. + +## 2. Responsibility boundary + +### BitVid owns + +- NIP-71 publishing and compatibility; +- channels, catalogs, playlists, seasons, bundles, and collections; +- search, discovery, feeds, recommendations, and moderation; +- profiles, watch history, favorites, and parental controls; +- access-policy authoring and resource-to-product mapping; +- checkout presentation inside the BitVid UI; +- playback-session creation and renewal; +- HLS/DASH manifests, MP4 range behavior, WebTorrent policy, storage, CDN, and origin integration; +- devices, concurrent streams, household rules, and application sessions; +- creator dashboards, pricing presentation, support, refunds, and catalog management. + +### BitUnlock owns + +- product registration and policy discovery; +- Lightning/NWC payment-plan creation; +- authoritative settlement verification; +- partial-payment recovery, retries, and idempotency; +- fulfillment and buyer-bound signed entitlement issuance; +- perpetual and term access semantics; +- renewal, expiration, revocation, and buyer recovery; +- generic relying-party verification; +- optional storage-capability issuance for static sellers; +- SDK, schemas, vectors, sandbox, and normalized errors. + +### BitRoad's role + +BitRoad may list and sell the same products, but BitRoad is not a runtime dependency for playback. +Purchases made through BitRoad and purchases initiated inside BitVid should produce compatible +BitUnlock entitlements that any compatible BitVid client can verify. + +## 3. Access modes + +### 3.1 Public + +The video is playable by any NIP-71 client. No BitUnlock product is required. + +### 3.2 Login-only + +The video remains free, but BitVid requires a proven Nostr identity before playback. This can support +private communities or account features without payment. + +### 3.3 Permanent purchase + +The viewer buys a video or catalog item once and receives a perpetual BitUnlock entitlement. BitVid +may issue short-lived playback sessions each time, but the entitlement itself does not expire. + +### 3.4 Rental + +The viewer buys a term entitlement. The first MVP should use purchase-relative expiry because that is +already supported by BitUnlock. A future first-play-relative rental requires a separate activation +record and must not be inferred from payment alone. + +### 3.5 Creator membership + +A creator defines one or more membership products. BitVid maps each membership tier to a changing set +of videos and benefits. + +Example tiers: + +- Supporter — early access and badge; +- Member — premium catalog; +- Producer — premium catalog, downloads, and private livestreams. + +BitUnlock verifies the tier entitlement; BitVid owns the current benefit mapping. + +### 3.6 Platform subscription + +BitVid defines platform-wide plans such as Basic, Premium, Family, Sports, or Annual. The active plan +entitlement grants access to application-defined catalog tiers. + +BitUnlock does not need to know which videos are in each tier. BitVid resolves the catalog policy. + +### 3.7 Bundle or catalog pass + +One entitlement may unlock a season, trilogy, course, conference archive, creator bundle, or topical +collection. + +### 3.8 Pay-per-view and livestream admission + +A term entitlement may authorize a premiere, live event, conference, or limited screening, with an +optional replay window. + +### 3.9 Delayed public release + +A video may initially require an entitlement and become public at a specified time. BitVid evaluates +the release timestamp before invoking paid-access checks. + +### 3.10 Metered viewing + +Pay-per-minute or pay-per-stream is deferred until BitUnlock supports an appropriate prepaid rail and +batched fee accounting. BitVid should not create a Lightning invoice or minimum service fee for every +small playback action. + +## 4. Resource access policy + +BitVid should represent access as an application-owned OR-of-routes policy. + +Conceptual shape: + +```json +{ + "version": "bitvid-access-policy-v1", + "mode": "any", + "routes": [ + { + "kind": "public-after", + "at": 1798761600 + }, + { + "kind": "bitunlock-entitlement", + "servicePubkey": "", + "productCoordinate": "" + }, + { + "kind": "bitunlock-entitlement", + "servicePubkey": "", + "productCoordinate": "", + "requireCurrentStatus": true + }, + { + "kind": "bitunlock-entitlement", + "servicePubkey": "", + "productCoordinate": "", + "requireCurrentStatus": true + } + ] +} +``` + +The exact wire format must be reviewed before implementation. The policy must support: + +- multiple acceptable entitlement products; +- public or login-only fallback; +- local release times; +- perpetual versus term expectations; +- mandatory online revocation checks where needed; +- future AND conditions for add-ons or region/catalog constraints; +- explicit service-pubkey pinning and versioning. + +## 5. NIP-71 compatibility + +BitVid must preserve ordinary NIP-71 interoperability. + +Recommended approach: + +1. Keep the standard NIP-71 video event valid and useful to other clients. +2. Add an optional reference to a separate replaceable BitVid access-policy event, or a minimal + extension tag pointing to that policy. +3. Do not publish permanent private storage URLs, decryption keys, playback tokens, buyer identities, + or subscription state in the public video event. +4. Clients that do not understand the access extension may show metadata and a locked state rather + than receiving a false public playback URL. +5. Public videos continue to carry normal public playback sources. + +A separate access-policy event is preferable to embedding a large mutable catalog rule directly in +every video event. It allows membership/catalog mappings to evolve without republishing media +metadata. + +## 6. Viewer flow + +### 6.1 Discovery + +BitVid loads the NIP-71 event and associated access policy. It can render the card, title, creator, and +preview metadata without revealing protected media capabilities. + +### 6.2 Authentication + +The viewer signs in through BitLogin, NIP-07, or another supported Nostr signer. BitVid treats the +proven pubkey as the account identity. + +### 6.3 Entitlement recovery + +BitVid loads buyer-held entitlements from: + +- local encrypted storage; +- the buyer's relay/vault recovery path; +- BitUnlock's authenticated buyer-recovery endpoint. + +The client should cache receipts but re-evaluate expiry and required revocation status before granting +new playback. + +### 6.4 Policy evaluation + +BitVid checks local routes first, then verifies candidate BitUnlock receipts against: + +- pinned BitUnlock service pubkey; +- authenticated buyer pubkey; +- expected product coordinate; +- supported schema and policy versions; +- entitlement term and expiry; +- current revocation status where required. + +### 6.5 Checkout + +When no route succeeds, BitVid presents applicable purchase choices inside the video UI: + +- buy permanently; +- rent; +- join creator membership; +- subscribe to BitVid plan; +- buy event pass. + +The BitUnlock SDK manages quote creation, wallet interaction, partial-payment recovery, bounded +polling, unlock, and entitlement validation. + +### 6.6 Playback authorization + +After a route succeeds, a trusted BitVid backend or media-origin component issues a short-lived +resource-scoped playback capability. The video bytes flow from the storage/CDN/origin to the viewer, +not through BitUnlock. + +## 7. Playback architecture + +### 7.1 MVP private-origin path + +Use a small BitVid authorization service or edge function: + +1. Receive authenticated viewer proof and buyer-presented entitlement. +2. Verify the entitlement with the BitUnlock SDK. +3. Evaluate the BitVid resource policy. +4. Create a short-lived playback session. +5. Return a signed manifest URL, signed cookie, or presigned MP4/object URL. +6. Refresh the session during long playback without requiring a new payment. + +### 7.2 Capability properties + +The playback capability should bind: + +- buyer or delegated device identity; +- video/resource ID; +- accepted policy route and entitlement ID; +- origin/audience; +- issue and expiry time; +- session revision or nonce; +- plan quality/download permissions where applicable. + +The capability should normally last minutes, even when the subscription lasts a month. + +### 7.3 HLS/DASH + +The design must account for: + +- manifest authorization; +- segment requests after the original URL expires; +- session renewal during long playback; +- seeking and bitrate switching; +- CDN caching without making protected manifests public; +- signed cookies versus per-segment query tokens; +- CORS and CSP among BitVid, the authorization service, and the media origin. + +### 7.4 MP4 + +For MP4 playback, preserve byte-range support and ensure session renewal does not break seeking. A +short-lived signed cookie or origin session may work better than a one-time URL with an expiry shorter +than the video. + +### 7.5 WebTorrent + +Public WebTorrent distribution is naturally incompatible with revocable private subscription access +once plaintext media is shared to peers. BitVid should: + +- keep WebTorrent for public media; +- allow encrypted torrent payloads for permanent purchases where the buyer receives a decryption key; +- not claim that private subscription streams remain revocable after distributing a reusable + decryption key or plaintext torrent. + +## 8. Subscription MVP + +The first subscription release should intentionally avoid automatic charging and household complexity. + +MVP capabilities: + +- one creator monthly membership product; +- one BitVid platform monthly plan; +- manual Lightning renewal; +- current plan and expiry display; +- renewal checkout against the same product; +- immutable new entitlement for each period; +- expiration and seller revocation; +- catalog-tier mapping; +- recovery on a new device; +- one active viewer session policy; +- short-lived playback session against a private test origin. + +The MVP is complete when a buyer can subscribe, recover the entitlement elsewhere, play an included +video, fail after expiry/revocation, renew, and play again without mutating the old receipt. + +## 9. Automatic renewal + +Automatic renewal is a later phase requiring an explicit, constrained buyer NWC authorization. + +Requirements include: + +- merchant and product binding; +- maximum amount; +- minimum billing interval; +- period and cumulative spending limits; +- cancellation and revocation; +- duplicate-charge and replay protection; +- notifications and failed-renewal behavior; +- no seller ability to broaden permission silently. + +BitVid must not market subscriptions as automatically recurring until this separate authorization flow +has been implemented and reviewed. + +## 10. Devices, profiles, and household access + +The root Nostr key should not be copied to every television. + +Later phases should introduce: + +- buyer-authorized device keys or application sessions; +- device list and remote sign-out; +- delegated scope limited to BitVid; +- maximum devices per plan; +- concurrent stream limits; +- profile records and parental controls; +- household-member authorization without sharing the root key; +- revocation and recovery. + +Profiles and household rules remain BitVid application state. BitUnlock only verifies the underlying +subscription entitlement unless a future generic delegated-capability feature is intentionally added. + +## 11. Creator and operator experience + +Creators should be able to: + +- register BitUnlock-backed purchase, rental, membership, and event products; +- connect those products to videos, playlists, or catalog groups; +- define accepted access routes; +- preview the locked viewer experience; +- revoke a term entitlement where policy permits; +- see aggregate commerce state without receiving buyer private keys or sensitive credentials; +- use BitRoad as an optional storefront while keeping BitVid-native checkout available. + +Operators should be able to: + +- configure the accepted BitUnlock service identity; +- configure a private media origin/CDN; +- control playback-session TTLs and concurrent-session policy; +- suspend new paid access safely during incidents; +- audit authorization failures without logging receipts or playback tokens. + +## 12. Privacy and security + +- Buyer receipts should remain private and buyer-presented. +- BitVid must not expose a public API allowing arbitrary enumeration of buyer purchases. +- Playback tokens, signed URLs, entitlements, NWC URIs, and storage credentials must not enter logs. +- Client-side verification may improve UX but cannot be the sole control for a private media origin. +- Copied receipts must fail for a different authenticated pubkey. +- Valid receipts for unaccepted products must fail. +- Expired and revoked subscriptions must not mint new sessions. +- Cross-video and cross-channel capability substitution must fail. +- BitUnlock's service identity and accepted schema versions must be pinned. +- BitUnlock must never proxy video bytes. +- Private storage/CDN credentials must remain application-side or narrowly scoped and encrypted. + +## 13. Implementation phases + +### Phase 0 — Architecture and protocol decisions + +- [ ] Freeze the BitVid responsibility boundary with BitUnlock and BitRoad. +- [ ] Define `bitvid-access-policy-v1` and negative vectors. +- [ ] Decide the NIP-71 extension/reference format without breaking ordinary clients. +- [ ] Define resource IDs, catalog groups, product coordinates, and policy versioning. +- [ ] Define public, login-only, permanent, rental, membership, subscription, bundle, event, and + delayed-public routes. +- [ ] Threat-model buyer receipt privacy, copied receipts, cross-resource substitution, and playback + capability leakage. + +### Phase 1 — BitUnlock SDK and identity integration + +- [ ] Pin BitUnlock service policy and service pubkey. +- [ ] Add BitLogin/Nostr authenticated buyer context where not already available. +- [ ] Integrate entitlement recovery. +- [ ] Integrate `verifyEntitlement()` and revocation/status checks. +- [ ] Add typed access-decision results and normalized user-facing errors. +- [ ] Add unit tests for wrong buyer, wrong product, bad signature, expiry, and revocation. + +### Phase 2 — Locked media UX and checkout + +- [ ] Render locked cards and video pages without exposing protected playback URLs. +- [ ] Show accepted purchase/rental/subscription choices. +- [ ] Integrate BitUnlock checkout, partial-payment recovery, and completed-purchase recovery. +- [ ] Display current entitlement route, expiry, and renewal state. +- [ ] Accept entitlements produced by BitRoad purchases. +- [ ] Add sandbox fixtures for each access mode. + +### Phase 3 — Playback authorization service + +- [ ] Create a minimal trusted BitVid authorization service/edge function. +- [ ] Verify buyer authentication and presented entitlements server-side. +- [ ] Evaluate `bitvid-access-policy-v1`. +- [ ] Issue short-lived resource-scoped playback sessions. +- [ ] Integrate a private test origin with signed URL/cookie support. +- [ ] Add renewal during long playback and safe error recovery. +- [ ] Test cross-video, replay, expiry, and token-leak scenarios. + +### Phase 4 — Subscription MVP + +- [ ] Register one creator membership and one platform subscription product. +- [ ] Map subscription products to catalog groups. +- [ ] Add manual renewal UX. +- [ ] Demonstrate expiry, revocation, renewal, and new-device recovery. +- [ ] Add a subscription-management view. +- [ ] Enforce an initial concurrent-session policy. +- [ ] Complete a real mainnet end-to-end subscription and playback test after sandbox proof. + +### Phase 5 — Purchases, rentals, bundles, and events + +- [ ] Permanent individual video purchase. +- [ ] Purchase-relative rental. +- [ ] Bundle/season/course pass. +- [ ] Pay-per-view and replay window. +- [ ] Delayed public release. +- [ ] Creator tier benefits beyond playback. + +### Phase 6 — Production streaming + +- [ ] Choose HLS/DASH/CDN architecture. +- [ ] Implement manifest and segment authorization. +- [ ] Preserve MP4 range and seek behavior. +- [ ] Define CORS, CSP, cache, and origin rules. +- [ ] Add playback-session observability without leaking viewing details. +- [ ] Load-test authorization and renewal paths. +- [ ] Add incident suspension and recovery procedures. + +### Phase 7 — Devices and households + +- [ ] Delegated device keys or application sessions. +- [ ] Device list, revocation, and remote sign-out. +- [ ] Concurrent-stream limits by plan. +- [ ] Profiles and parental controls. +- [ ] Household-member authorization. +- [ ] Recovery without copying the root Nostr private key. + +### Phase 8 — Advanced billing + +- [ ] Design and audit restricted automatic NWC renewal. +- [ ] Trials, promotions, upgrades, downgrades, and plan transitions. +- [ ] Cashu/prepaid or batched metered viewing after BitUnlock fee accrual is ready. +- [ ] Creator revenue and platform-fee reporting without making BitVid custodial. + +## 14. Acceptance criteria + +The first complete reference implementation must demonstrate: + +1. A standard public NIP-71 video still works in ordinary clients. +2. A protected video reveals no permanent private-media URL publicly. +3. A buyer purchases a monthly BitUnlock subscription inside BitVid. +4. An independently versioned BitVid authorization component verifies the entitlement. +5. The component issues a five-minute capability for the correct video. +6. The media origin serves bytes directly without BitUnlock proxying them. +7. A copied entitlement fails for another pubkey. +8. A valid but unrelated entitlement fails. +9. Expiry and revocation prevent new playback sessions. +10. Manual renewal creates a new entitlement period and restores access. +11. The buyer recovers access on a new device without repaying. +12. An individual permanent purchase is accepted as an alternate route to the same video. +13. A BitRoad-originated purchase works without BitRoad being present during playback. +14. Logs and analytics contain no entitlement plaintext, NWC secrets, storage credentials, or + playback bearer tokens. + +## 15. Explicit non-goals for the first release + +- Automatic recurring charges. +- Full Netflix-style household detection. +- Strong DRM guarantees against screen capture or authorized-user copying. +- Private plaintext WebTorrent subscription streaming. +- Pay-per-minute billing. +- Geographic licensing enforcement. +- Recommendation-system redesign. +- Building BitUnlock-specific payment or entitlement logic directly into BitVid instead of using the + public SDK and generic contracts.