slim frontend, add ux-friendly autosource auth using hmac + docs

Author: gildesmarais

.github/copilot-instructions.md

@@ -7,6 +7,31 @@
 - **Principle:** _All features must work without JavaScript._ JS is only progressive enhancement.
 - **Frontend:** Modern Astro-based UI with component architecture, served alongside Ruby backend.
 
+## Documentation website of core dependencies
+
+Search these pages before using them. Find examples, plugins, UI components, and configuration options.
+
+### Roda
+
+1. https://roda.jeremyevans.net/documentation.html
+
+### Astro & Starlight
+
+1. https://docs.astro.build/en/getting-started/
+2. https://starlight.astro.build/getting-started/
+
+### html2rss
+
+1. If available, find source locally in: `../html2rss`.
+2. source code on github: https://github.com/html2rss/html2rss
+
+### Test and Linters
+
+1. https://docs.rubocop.org/rubocop/cops.html
+2. https://docs.rubocop.org/rubocop-rspec/cops_rspec.html
+3. https://rspec.info/features/3-13/rspec-expectations/built-in-matchers/
+4. https://www.betterspecs.org/
+
 ## Core Rules
 
 - ✅ Use **Roda routing with `hash_branch`**. Keep routes small.
@@ -26,6 +51,7 @@
 - ❌ Don't leak stack traces or secrets in responses.
 - ❌ Don't add complex frontend frameworks (React, Vue, etc.). Keep Astro simple.
 - ❌ Don't modify `frontend/dist/` - it's generated by build process.
+- ❌ NEVER expose the auth token a user provides.
 
 ## Project Structure
 

README.md

@@ -10,6 +10,7 @@ This web application scrapes websites to build and deliver RSS 2.0 feeds with a
 - **Feed Gallery**: Browse and discover popular RSS feeds
 - **Auto Source**: Generate feeds from any website automatically
 - **Stable URLs**: Provides stable URLs for feeds generated by automatic sourcing
+- **Public Feed Access**: Secure, token-based public access to RSS feeds without authentication headers
 - **Custom Feeds**: [Create your custom feeds](https://html2rss.github.io/web-application/tutorials/building-feeds)!
 - **Pre-built Configs**: Comes with plenty of [included configs](https://html2rss.github.io/web-application/how-to/use-included-configs)
 - **Performance**: Handles request caching and sets caching-related HTTP headers
@@ -29,42 +30,99 @@ The application can be configured using environment variables. See the [configur
 ### Security Features
 
 - **URL Restrictions**: Public instances can restrict auto source to specific URLs
-- **Authentication**: Basic auth for auto source and health check endpoints  
+- **Authentication**: Token-based authentication for auto source and health check endpoints
+- **Public Feed Access**: Secure, stateless feed tokens for public RSS access
+- **HMAC-SHA256 Signing**: Cryptographically signed tokens prevent tampering
+- **URL Binding**: Feed tokens are bound to specific URLs for security
 - **SSRF Protection**: Built-in protection against Server-Side Request Forgery
 - **Input Validation**: Comprehensive validation of all inputs
+- **XML Sanitization**: Prevents XML injection attacks in RSS output
+- **CSP Headers**: Content Security Policy headers prevent XSS attacks
+
+## Public Feed Access
+
+The application now supports secure public access to RSS feeds without requiring authentication headers. This is perfect for sharing feeds with RSS readers and other applications.
+
+### How It Works
+
+1. **Create a Feed**: Use the auto source feature to generate a feed
+2. **Get Public URL**: The system returns a public URL with an embedded token
+3. **Share the URL**: Anyone can access the feed using this URL
+4. **Secure Access**: The token is cryptographically signed and URL-bound
+
+### Example
+
+```bash
+# Create a feed
+curl -X POST "https://your-domain.com/auto_source/create" \
+  -H "Authorization: Bearer your-token" \
+  -d "url=https://example.com&name=Example Feed"
+
+# Response includes public_url
+{
+  "id": "abc123",
+  "name": "Example Feed", 
+  "url": "https://example.com",
+  "public_url": "/feeds/abc123?token=...&url=https%3A%2F%2Fexample.com"
+}
+
+# Access the feed publicly
+curl "https://your-domain.com/feeds/abc123?token=...&url=https%3A%2F%2Fexample.com"
+```
+
+### Security Features
+
+- **10-Year Expiry**: Tokens are valid for 10 years (perfect for RSS)
+- **URL Binding**: Tokens only work for their specific URL
+- **HMAC Signing**: Tokens cannot be tampered with
+- **No Server Storage**: Stateless validation, no database required
 
 ## Documentation
 
 For full documentation, please see the [html2rss-web documentation](https://html2rss.github.io/web-application/).
 
-## Development
+### Security and Deployment
+
+- [Security Guide](SECURITY.md) - Comprehensive security documentation
+- [Project Website](https://html2rss.github.io/html2rss-web/) - Deployment and usage instructions
 
-### Quick Start with GitHub Codespaces
+## Quick Start
 
-The easiest way to get started is using GitHub Codespaces:
+This application is designed to be used via Docker Compose only.
 
-1. Fork this repository
-2. Click "Code" → "Codespaces" → "Create codespace on [your-username]/html2rss-web"
-3. Wait for the codespace to build (it will automatically run `bundle install`)
-4. The development server will be available at the forwarded port (usually 3000)
+### Prerequisites
 
-### Local Development
+- Docker and Docker Compose installed
+- Git (to clone the repository)
 
-1. **Clone and setup:**
+### Setup and Run
 
+1. **Clone the repository:**
    ```bash
    git clone https://github.com/html2rss/html2rss-web.git
    cd html2rss-web
-   make setup
    ```
 
-2. **Start development server:**
+2. **Generate a secret key:**
+   ```bash
+   openssl rand -hex 32
+   ```
+
+3. **Configure docker-compose.yml:**
    ```bash
-   make dev
+   # Edit the file and replace 'your-generated-secret-key-here' with your actual secret key
+   # The docker-compose.yml file is already included in the repository
+   ```
+
+4. **Start the application:**
+   ```bash
+   docker-compose up
    ```
 
 The application will be available at `http://localhost:3000`.
 
+**⚠️ Important**: The `HTML2RSS_SECRET_KEY` environment variable is required. Without it, the application will not start and will display setup instructions.
+
 ### Frontend Development
 
 The project includes a modern Astro frontend alongside the Ruby backend: