Upload 4 files

.env.example

@@ -2,8 +2,7 @@
 # Copy these to your HF Spaces Settings → Variables
 
 # API Key Configuration
-API_KEYS=demo-key-123,production-key-456,client-key-789
-REQUIRE_API_KEY=true
+API_KEY=sk-your-secure-api-key-here
 
 # Performance Settings (Optional)
 NODE_ENV=production
@@ -16,11 +15,17 @@ CPU_THRESHOLD=95
 # Instructions for Hugging Face Spaces:
 # 1. Go to your Space Settings
 # 2. Click on "Variables" tab
-# 3. Add each variable above (one per line, without quotes)
+# 3. Add API_KEY variable with your secure key
 # 4. Space will automatically restart with new configuration
 
-# Example API Keys (Generate your own secure keys):
-# - Use random strings of 20+ characters
-# - Include letters, numbers, and symbols
+# Example API Key Generation:
+# - Use random strings of 32+ characters
+# - Include letters, numbers, and optionally symbols
 # - Keep them secure and don't share publicly
-# - Consider using UUID format: 550e8400-e29b-41d4-a716-446655440000
+# - Consider format: sk-1234567890abcdef...
+# 
+# Generate with Node.js:
+# node -e "console.log('sk-' + require('crypto').randomBytes(32).toString('hex'))"
+#
+# Generate with Python:
+# python -c "import secrets; print('sk-' + secrets.token_hex(32))"

HF_SPACES_ENV_GUIDE.md

@@ -1,184 +1,244 @@
-# Hugging Face Spaces 环境变量设置指南
+# Hugging Face Spaces Environment Variable Setup Guide
 
-## 🔧 在 HF Spaces 中设置环境变量
+## 🔐 API Key Authentication Setup
 
-### 方法一：通过 Web 界面设置
+This Space supports API key authentication through environment variables. Follow these steps to enable secure access:
 
-1. **进入 Space 设置**
-   - 访问你的 Space：`https://huggingface.co/spaces/your-username/your-space-name`
-   - 点击页面顶部的 **"Settings"** 标签
+### 1. Set Environment Variable in Space Settings
 
-2. **添加环境变量**
-   - 在设置页面中找到 **"Variables"** 或 **"Environment Variables"** 部分
-   - 点击 **"Add Variable"** 或 **"New Variable"**
+1. **Go to your Space settings:**
+   - Navigate to your Space on Hugging Face
+   - Click on the "Settings" tab
+   - Scroll down to "Repository secrets" or "Environment variables" section
 
-3. **配置认证相关变量**
+2. **Add the API_KEY variable:**
+   - **Name:** `API_KEY`
+   - **Value:** Your secure API key (e.g., `sk-1234567890abcdef...`)
+   - Click "Add secret" or "Save"
 
-   | Variable Name | Value | Description |
-   |---------------|-------|-------------|
-   | `REQUIRE_API_KEY` | `true` | 启用 API 认证 |
-   | `API_KEYS` | `key1,key2,key3` | 自定义 API 密钥列表 |
-   | `HF_TOKEN` | `hf_your_token` | Hugging Face access token（可选） |
+3. **Restart your Space:**
+   - The Space will automatically restart when you add/modify environment variables
+   - Wait for the Space to rebuild and restart
 
-### 方法二：通过 Space YAML 配置
+### 2. Environment Variable Behavior
 
-在你的 Space 根目录创建或编辑 `README.md` 文件，在顶部添加配置：
+- **If API_KEY is set:** Authentication is required for the `/screenshot` endpoint
+- **If API_KEY is not set:** Open access mode (no authentication required)
 
-```yaml
----
-title: Page Screenshot API
-emoji: 📸
-colorFrom: blue
-colorTo: green
-sdk: docker
-pinned: false
-license: mit
-variables:
-  REQUIRE_API_KEY: "true"
-  API_KEYS: "demo-key-123,production-key-456"
-  NODE_ENV: "production"
----
-```
+### 3. Using the API with Authentication
 
-## 🔐 推荐的环境变量配置
-
-### 基础配置（公开 Space）
+#### Option 1: Authorization Header
 ```bash
-# 不设置任何环境变量，或设置：
-REQUIRE_API_KEY=false
+curl -X POST "https://your-space.hf.space/screenshot" \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com"}'
 ```
 
-### 受保护配置（带自定义 API Key）
+#### Option 2: x-api-key Header
 ```bash
-REQUIRE_API_KEY=true
-API_KEYS=your-secret-key-1,your-secret-key-2,backup-key-3
+curl -X POST "https://your-space.hf.space/screenshot" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com"}'
 ```
 
-### 企业配置（多种认证方式）
-```bash
-REQUIRE_API_KEY=true
-API_KEYS=client-key-001,client-key-002,admin-key-999
-NODE_ENV=production
-MAX_CONCURRENT_REQUESTS=5
-CPU_THRESHOLD=90
+#### JavaScript Example
+```javascript
+const response = await fetch('/screenshot', {
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer YOUR_API_KEY',
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    url: 'https://example.com',
+    width: 1280,
+    height: 720
+  })
+});
 ```
 
-## 🚨 重要安全注意事项
+### 4. Security Best Practices
 
-### ✅ 安全的做法
-- **永远不要在代码中硬编码 token**
-- 使用 HF Spaces 的环境变量功能存储敏感信息
-- 为不同的客户端生成不同的 API key
-- 定期轮换 API keys
+- **Generate a strong API key:** Use a cryptographically secure random string
+- **Keep it secret:** Never expose the API key in client-side code or logs
+- **Use HTTPS:** Always access the API over HTTPS in production
+- **Rotate regularly:** Consider rotating the API key periodically
 
-### ❌ 避免的做法
-- 不要在 GitHub 仓库中提交包含 token 的 `.env` 文件
-- 不要在 README.md 的明文部分暴露真实的 API keys
-- 不要使用简单易猜的 API keys
+### 5. Testing Authentication
 
-## 🔄 环境变量的工作原理
+1. **Check authentication status:**
+   ```bash
+   curl https://your-space.hf.space/
+   ```
 
-在你的 Space 中，这些环境变量会被自动注入到运行环境中：
+2. **Test with correct API key:**
+   ```bash
+   curl -X POST "https://your-space.hf.space/screenshot" \
+     -H "Authorization: Bearer YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{"url": "https://example.com"}'
+   ```
 
-```javascript
-// server.js 中的代码会自动读取这些环境变量
-const API_KEYS = process.env.API_KEYS ? 
-  process.env.API_KEYS.split(',').map(key => key.trim()) : [];
-const REQUIRE_API_KEY = process.env.REQUIRE_API_KEY === 'true';
-```
+3. **Test without API key (should fail if authentication is enabled):**
+   ```bash
+   curl -X POST "https://your-space.hf.space/screenshot" \
+     -H "Content-Type: application/json" \
+     -d '{"url": "https://example.com"}'
+   ```
 
-## 📊 不同认证模式的配置示例
+### 6. Error Responses
 
-### 模式 1：完全开放（演示用）
-```bash
-# 不设置任何环境变量
-# 所有人都可以访问 API，有基础速率限制（30次/15分钟）
+#### 401 Unauthorized (Missing or Invalid API Key)
+```json
+{
+  "error": "Unauthorized",
+  "message": "Valid API key required. Please provide API key in Authorization header or x-api-key header.",
+  "hint": "Use \"Authorization: Bearer YOUR_API_KEY\" or \"x-api-key: YOUR_API_KEY\""
+}
 ```
 
-### 模式 2：混合模式（推荐）
-```bash
-REQUIRE_API_KEY=false
-API_KEYS=vip-key-001,premium-key-002
-# 未认证用户：30次/15分钟
-# 认证用户：100次/15分钟
-# HF token 用户：100次/15分钟（自动支持）
+### 7. Recommended API Key Format
+
+Generate a secure API key using one of these methods:
+
+#### Python
+```python
+import secrets
+import string
+
+def generate_api_key(length=32):
+    alphabet = string.ascii_letters + string.digits
+    return 'sk-' + ''.join(secrets.choice(alphabet) for _ in range(length))
+
+api_key = generate_api_key()
+print(f"Generated API Key: {api_key}")
 ```
 
-### 模式 3：完全保护
-```bash
-REQUIRE_API_KEY=true
-API_KEYS=enterprise-key-001,client-key-002
-# 只有持有有效 API key 或 HF token 的用户才能访问
+#### Node.js
+```javascript
+const crypto = require('crypto');
+
+function generateApiKey(length = 32) {
+    return 'sk-' + crypto.randomBytes(length).toString('hex').slice(0, length);
+}
+
+const apiKey = generateApiKey();
+console.log(`Generated API Key: ${apiKey}`);
 ```
 
-## 🛠️ 实际部署步骤
+#### Online Generator
+You can also use online tools like:
+- `openssl rand -hex 32` (command line)
+- Any secure random string generator
 
-### 1. 设置环境变量
-1. 进入 Space Settings → Variables
-2. 添加必要的环境变量：
-   ```
-   REQUIRE_API_KEY: true
-   API_KEYS: your-generated-key-1,your-generated-key-2
-   ```
+### 8. Demo Page Features
 
-### 2. 生成安全的 API Keys
-```bash
-# 使用 Node.js 生成随机密钥
-node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+The demo page automatically detects whether authentication is enabled:
 
-# 或生成 UUID 格式
-node -e "console.log(require('crypto').randomUUID())"
-```
+- **With API_KEY set:** Shows API key input field
+- **Without API_KEY:** Shows open access message
+- **Dynamic UI:** Adapts based on authentication status
 
-### 3. 验证配置
-部署后访问你的 Space 的健康检查端点：
-```bash
-curl https://your-space.hf.space/
+### 9. Health Check Response Examples
+
+#### Without API_KEY Environment Variable
+```json
+{
+  "message": "Page Screenshot API - Hugging Face Spaces",
+  "version": "1.4.0",
+  "authentication": {
+    "type": "Open Access (No API Key Set)",
+    "required": false,
+    "note": "Set API_KEY environment variable to enable authentication"
+  }
+}
 ```
 
-响应应该显示认证状态：
+#### With API_KEY Environment Variable
 ```json
 {
+  "message": "Page Screenshot API - Hugging Face Spaces",
+  "version": "1.4.0",
   "authentication": {
+    "type": "API Key Required",
     "required": true,
-    "supportedMethods": [
-      "X-API-Key: custom-api-key",
-      "Authorization: Bearer custom-api-key",
-      "Authorization: Bearer hf_token (for private Spaces)"
-    ]
+    "note": "API key required for screenshot endpoint"
   }
 }
 ```
 
-## 🔄 动态配置更新
+---
 
-环境变量更改后：
-1. Space 会自动重启
-2. 新的配置会立即生效
-3. 无需重新部署代码
+## 🚀 Quick Setup Summary
 
-## 📈 监控和管理
+1. Generate a secure API key: `sk-1234567890abcdef...`
+2. Add `API_KEY` environment variable in Space settings
+3. Set the value to your generated API key
+4. Wait for Space to restart
+5. Test with the demo page or API calls
 
-### 检查当前配置
-```bash
-curl https://your-space.hf.space/status
-```
+Your Space is now secure and ready for production use! 🔐
 
-### 测试认证
-```bash
-# 测试自定义 API key
-curl -H "X-API-Key: your-key" https://your-space.hf.space/
+## 🔄 Environment Variable Management
 
-# 测试 HF token（如果 Space 是私有的）
-curl -H "Authorization: Bearer hf_your_token" https://your-space.hf.space/
-```
+- **Add Variable:** Space Settings → Environment Variables → Add `API_KEY`
+- **Update Variable:** Modify the value and save (Space will restart)
+- **Remove Variable:** Delete the variable to disable authentication
+- **View Status:** Check `/` or `/status` endpoints for current auth status
 
-## 💡 最佳实践建议
+## 📱 Integration Examples
 
-1. **开发阶段**：���用开放模式进行测试
-2. **生产部署**：启用认证保护
-3. **密钥管理**：定期轮换 API keys
-4. **访问控制**：为不同用户组分配不同的 keys
-5. **监控使用**：定期检查 API 使用情况
+### Frontend JavaScript
+```javascript
+// Store API key securely (never in source code)
+const API_KEY = localStorage.getItem('screenshot_api_key');
+
+async function takeScreenshot(url) {
+  const response = await fetch('/screenshot', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${API_KEY}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({ url })
+  });
+  
+  if (response.ok) {
+    return await response.blob();
+  } else {
+    const error = await response.json();
+    throw new Error(error.message);
+  }
+}
+```
 
-通过以上配置，你可以完全通过 Hugging Face Spaces 的界面管理所有认证相关的环境变量，无需在代码中硬编码任何敏感信息！
+### Backend Integration
+```javascript
+// Express.js middleware for API key validation
+const SCREENSHOT_API_KEY = process.env.SCREENSHOT_API_KEY;
+
+async function screenshotMiddleware(req, res, next) {
+  try {
+    const response = await fetch('https://your-space.hf.space/screenshot', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${SCREENSHOT_API_KEY}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(req.body)
+    });
+    
+    if (response.ok) {
+      const screenshot = await response.buffer();
+      res.set('Content-Type', 'image/jpeg');
+      res.send(screenshot);
+    } else {
+      res.status(response.status).json(await response.json());
+    }
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+}
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-screenshot-api",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Professional web page screenshot API service for Hugging Face Spaces",
   "main": "server.js",
   "scripts": {
@@ -24,8 +24,5 @@
   },
   "engines": {
     "node": ">=18.0.0"
-  },
-  "puppeteer": {
-    "skipDownload": "true"
   }
 }

server.js

@@ -6,6 +6,7 @@ const rateLimit = require('express-rate-limit');
 
 const app = express();
 const PORT = process.env.PORT || 7860;
+const API_KEY = process.env.API_KEY; // 从环境变量获取API密钥
 
 // 安全中间件
 app.use(helmet({
@@ -45,19 +46,41 @@ function getCpuUsage() {
   return Math.round((total / 1000000) % 100); // 简化的CPU使用率
 }
 
+// API鉴权中间件
+function authenticate(req, res, next) {
+  // 如果没有设置API_KEY环境变量，跳过鉴权（开发模式）
+  if (!API_KEY) {
+    return next();
+  }
+
+  const authHeader = req.headers.authorization;
+  const apiKey = req.headers['x-api-key'] || (authHeader && authHeader.startsWith('Bearer ') ? authHeader.slice(7) : null);
+
+  if (!apiKey || apiKey !== API_KEY) {
+    return res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Valid API key required. Please provide API key in Authorization header or x-api-key header.',
+      hint: 'Use "Authorization: Bearer YOUR_API_KEY" or "x-api-key: YOUR_API_KEY"'
+    });
+  }
+
+  next();
+}
+
 // 健康检查
 app.get('/', (req, res) => {
   res.json({
     message: 'Page Screenshot API - Hugging Face Spaces',
-    version: '1.3.0',
+    version: '1.4.0',
     status: 'running',
     platform: 'HuggingFace Spaces',
     authentication: {
-      type: 'HuggingFace System Level',
-      note: 'Authentication is handled by HuggingFace platform for private Spaces'
+      type: API_KEY ? 'API Key Required' : 'Open Access (No API Key Set)',
+      required: !!API_KEY,
+      note: API_KEY ? 'API key required for screenshot endpoint' : 'Set API_KEY environment variable to enable authentication'
     },
     endpoints: {
-      screenshot: 'POST /screenshot',
+      screenshot: 'POST /screenshot (requires API key if configured)',
       demo: 'GET /demo',
       health: 'GET /',
       status: 'GET /status'
@@ -84,8 +107,9 @@ app.get('/status', (req, res) => {
       maxConcurrent: MAX_CONCURRENT
     },
     authentication: {
-      type: 'HuggingFace System Level',
-      note: 'No application-level authentication required'
+      enabled: !!API_KEY,
+      type: API_KEY ? 'Environment Variable API Key' : 'Disabled',
+      note: API_KEY ? 'API key authentication is active' : 'Set API_KEY environment variable to enable authentication'
     }
   });
 });
@@ -109,12 +133,32 @@ app.get('/demo', (req, res) => {
         .loading { color: #666; font-style: italic; }
         .error { color: #dc3545; }
         .success { color: #28a745; }
+        .auth-section { background: #f8f9fa; padding: 15px; border-radius: 6px; margin-bottom: 20px; }
+        .auth-info { color: #6c757d; font-size: 14px; margin-top: 10px; }
     </style>
 </head>
 <body>
     <h1>📸 Page Screenshot API Demo</h1>
     <p>Test the screenshot API with global font support</p>
     
+    ${API_KEY ? `
+    <div class="auth-section">
+        <h3>🔐 API Authentication Required</h3>
+        <label>API Key:</label><br>
+        <input type="password" id="apiKey" placeholder="Enter your API key" style="width: 400px;">
+        <div class="auth-info">
+            ℹ️ API key is required for this Space. Contact the Space owner for access.
+        </div>
+    </div>
+    ` : `
+    <div class="auth-section">
+        <h3>🔓 Open Access Mode</h3>
+        <div class="auth-info">
+            ℹ️ No API key required - authentication is disabled for this Space.
+        </div>
+    </div>
+    `}
+    
     <div class="form-group">
         <label>URL to screenshot:</label><br>
         <input type="text" id="url" value="https://www.baidu.com" placeholder="Enter website URL">
@@ -151,20 +195,36 @@ app.get('/demo', (req, res) => {
             const width = parseInt(document.getElementById('width').value);
             const height = parseInt(document.getElementById('height').value);
             const quality = parseInt(document.getElementById('quality').value);
+            const apiKey = document.getElementById('apiKey') ? document.getElementById('apiKey').value : '';
             
             if (!url) {
                 alert('Please enter a URL');
                 return;
             }
             
+            ${API_KEY ? `
+            if (!apiKey) {
+                alert('Please enter your API key');
+                return;
+            }
+            ` : ''}
+            
             document.getElementById('result').innerHTML = '<p class="loading">📸 Taking screenshot...</p>';
             
             try {
+                const headers = {
+                    'Content-Type': 'application/json',
+                };
+                
+                ${API_KEY ? `
+                if (apiKey) {
+                    headers['Authorization'] = 'Bearer ' + apiKey;
+                }
+                ` : ''}
+                
                 const response = await fetch('/screenshot', {
                     method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                    },
+                    headers: headers,
                     body: JSON.stringify({ url, width, height, quality })
                 });
                 
@@ -195,7 +255,7 @@ app.get('/demo', (req, res) => {
 });
 
 // 截图端点
-app.post('/screenshot', async (req, res) => {
+app.post('/screenshot', authenticate, async (req, res) => {
   const { url, width = 1280, height = 720, quality = 75 } = req.body;
 
   // 验证参数
@@ -306,6 +366,7 @@ app.listen(PORT, () => {
   console.log(`🚀 Page Screenshot API running on port ${PORT}`);
   console.log(`📸 Demo: http://localhost:${PORT}/demo`);
   console.log(`🔍 Health: http://localhost:${PORT}/`);
+  console.log(`🔐 Authentication: ${API_KEY ? 'ENABLED' : 'DISABLED'}`);
 });
 
 module.exports = app;