Merge pull request #1678 from PR0M3TH3AN/update-readme-storage-docs-11053884227444764200

Update README and Storage Docs

README.md

@@ -2,7 +2,7 @@
 
 # bitvid - Decentralized Video Sharing
 
-**bitvid** is a decentralized platform where users can share videos and follow creators with privacy and freedom. Built with a static site architecture, it’s lightweight, efficient, and fully decentralized, making it ideal for hosting or local deployment.
+**bitvid** is a decentralized platform where users can share videos and follow creators with privacy and freedom. Built with a static site architecture, it operates entirely as a **static client**—it does not run a backend server, hold custody of user keys, or sign requests on behalf of users. All signing and state management happen client-side or via a connected Nostr signer.
 
 ---
 
@@ -12,7 +12,7 @@
 - **Channel profile pages**: The [channel view](views/channel-profile.html) and `js/channelProfile.js` render banners, playlists, links, and follow stats so every creator has a branded landing page.
 - **Audience flags**: The [Upload](components/upload-modal.html) and [Edit Video](components/edit-video-modal.html) modals expose **NSFW** and **For Kids** toggles that map straight to note metadata for safer discovery.
 - **Richer metadata repeaters**: Configure variants, captions, segments, participants, references, and hashtags directly in the Upload modal so posts ship with structured context.
-- **Cloudflare R2 Uploads**: Publish through the modal’s Cloudflare flow with progress tracking and credential helpers.
+- **Flexible S3 Uploads**: Publish using browser-held keys, manual uploads, or presigned manifests.
 - **Encrypted Watch History**: Sync viewing activity privately through the NIP-04 encrypted pipeline with local fallbacks.
 - **Live View Counters**: Subscribe to view events and see totals update in real time on video cards and the video modal.
 - **Lightning Zaps**: Tip creators with Lightning payments via the Zap controls in the video modal.
@@ -38,12 +38,20 @@ Open the **Upload** modal from the header toolbar and start by selecting the NIP
 
 Both upload modes expose metadata repeaters for **variants** and **hashtags**, while the [Edit Video](components/edit-video-modal.html) modal offers the full suite (including **captions/text tracks**, **segments**, **participants**, and **references**). Use these when you have multiple playback qualities (variants), accessibility tracks (captions), multipart drops (segments), discoverability tags (hashtags), credited collaborators (participants), or cross-posts/threads (references). Skip any repeater you don’t need—the base schema stays valid without them.
 
-Pick the flow that matches your source material:
+Pick the flow that matches your source material. Supported S3 upload modes include:
 
-- **External Link (hosted URL or magnet)**: Provide a title plus an HTTPS video URL and/or a WebTorrent magnet. The form requires at least one transport, validates `ws=`/`xs=` hints, keeps magnets raw by decoding them with `safeDecodeMagnet()` before publish, and applies whatever metadata repeaters you configured. If you submit a magnet without a hosted URL, the modal warns that availability depends on peers seeding the torrent.
-- **Upload File (direct R2 upload)**: Enter your Cloudflare credentials in the guided form, optionally expand the **Advanced options** accordion to override pathing or access controls, then drop media files for bitvid to upload through the R2 API. The modal tracks progress, applies your metadata selections, auto-fills the primary `imeta` variant once the upload completes, and publishes the resulting R2 URL back into the note automatically.
+1.  **Browser-held S3 keys (trusted operator only):** Enter your S3 credentials in the Storage tab to upload directly from the browser.
+    > **Security Warning:** This mode requires storing encrypted credentials in the browser's IndexedDB. While keys are encrypted at rest, they are decrypted in memory during use. Use this mode only on self-hosted, trusted deployments where you control the environment. Do not enter high-value credentials on public or untrusted instances.
+2.  **Manual upload via provider console:** Upload your file to your storage provider (e.g., R2, S3) manually, then paste the public URL into the upload form.
+3.  **Operator-provided presigned manifests:** Use a presigned JSON manifest prepared externally to authorize the upload without exposing long-lived credentials to the browser.
 
-Hosted URLs remain the preferred playback path, and you can still add a magnet or supplemental web seeds when using either mode. Use the **Private** toggle to keep the resulting card visible only to you, and lean on the repeaters whenever you want to surface richer context or alternate assets as outlined in the event schema reference.
+**Upload File (direct S3 upload)**:
+If you are using **Mode 1** (Browser-held keys), enter your credentials in the guided form or Storage tab. Optionally expand the **Advanced options** accordion to override pathing or access controls, then drop media files for bitvid to upload through the S3 API. The modal tracks progress, applies your metadata selections, auto-fills the primary `imeta` variant once the upload completes, and publishes the resulting URL back into the note automatically.
+
+**External Link (hosted URL or magnet)**:
+For **Mode 2** (Manual upload) or external content, provide a title plus an HTTPS video URL and/or a WebTorrent magnet. The form requires at least one transport, validates `ws=`/`xs=` hints, keeps magnets raw by decoding them with `safeDecodeMagnet()` before publish, and applies whatever metadata repeaters you configured. If you submit a magnet without a hosted URL, the modal warns that availability depends on peers seeding the torrent.
+
+Hosted URLs remain the preferred playback path, and you can still add a magnet or supplemental web seeds when using any mode. Use the **Private** toggle to keep the resulting card visible only to you, and lean on the repeaters whenever you want to surface richer context or alternate assets as outlined in the event schema reference.
 
 ### How playback works
 

docs/storage-r2.md

@@ -2,7 +2,11 @@
 
 ## Purpose and scope
 
-`js/services/r2Service.js` is the specialized provider handler for Cloudflare R2 uploads. While the new **Storage Tab** (powered by `StorageService`) manages the secure storage of credentials, `r2Service` is responsible for:
+`js/services/r2Service.js` is the specialized provider handler for Cloudflare R2 uploads. It implements one of the supported **S3 Upload Modes** (specifically Mode 1: Browser-held keys).
+
+> **Security Note:** This integration requires storing encrypted credentials in the browser. See [`README.md`](../README.md) and [`docs/storage-tab-design.md`](./storage-tab-design.md) for security warnings and alternative upload modes for untrusted environments.
+
+While the new **Storage Tab** (powered by `StorageService`) manages the secure storage of credentials, `r2Service` is responsible for:
 
 - Uploading the selected video/HLS asset via multipart S3 uploads.
 - Verifying public access via the configured Public Bucket URL.

docs/storage-tab-design.md

@@ -4,6 +4,17 @@ This document describes the design and architecture of the **Storage Tab** (mana
 
 The system allows users to securely store and manage multiple cloud storage connections (Providers) for video hosting. The architecture prioritizes security (encryption at rest), extensibility (adapter pattern), and provider flexibility (Generic S3 vs. specific implementations like Cloudflare R2).
 
+## Supported Upload Modes
+
+The storage system supports three primary modes for handling video uploads:
+
+1.  **Browser-held S3 keys (trusted operator only):**
+    The user enters S3 credentials (Access Key/Secret Key) into the Storage Tab. These keys are encrypted and stored in the browser's IndexedDB. This mode offers the smoothest UX but carries higher risk.
+2.  **Manual upload via provider console:**
+    The user uploads the file manually to their provider (e.g., R2 dashboard) and simply provides the public URL. This bypasses the need for the browser to hold write credentials.
+3.  **Operator-provided presigned manifests:**
+    The user provides a JSON manifest generated externally (e.g., by a CLI tool or backend service). This manifest contains presigned URLs for uploading parts, allowing the browser to upload without ever seeing the long-lived credentials.
+
 ## 1. Core Architecture: `StorageService`
 
 The `StorageService` (`js/services/storageService.js`) acts as the secure vault for connection secrets. It sits between the UI and the actual storage providers.
@@ -99,7 +110,8 @@ A specialized profile of S3 with specific constraints to improve UX.
 
 ### Local Storage & XSS
 *   **Risk:** The encrypted data resides in the browser's **IndexedDB**. While encrypted at rest, a malicious script (XSS attack) running in the context of the application could potentially request the signer to decrypt the Master Key or read the decrypted key from memory if the session is active.
-*   **Mitigation:** The application must maintain strict Content Security Policy (CSP) and dependency hygiene to prevent XSS.
+*   **Warning:** Because of this risk, **Mode 1 (Browser-held keys)** should only be used on **self-hosted, trusted deployments** where the operator controls the environment. Do not enter high-value credentials on public, untrusted, or shared instances.
+*   **Mitigation:** The application must maintain strict Content Security Policy (CSP) and dependency hygiene to prevent XSS. Use Mode 2 or 3 for higher security assurance in untrusted environments.
 
 ### Ephemeral Key Derivation (Kind 22242)
 To consistently derive or verify keys without publishing sensitive data, the system uses a **Storage Challenge Event**.

scripts/check-hex.js

@@ -28,7 +28,8 @@ const IGNORED_GLOBS = [
   '!config/validate-config.js',
   '!js/embed.js',
   '!tests/unit/embed-accent.test.mjs',
-  '!tests/visual/embed-layout.spec.ts'
+  '!tests/visual/embed-layout.spec.ts',
+  '!ai/**'
 ];
 
 const rgArgs = [