Added admin endpoints for admin delete of pins

Author: ehsan6sha

.env.example

@@ -80,6 +80,36 @@ JWT_SECRET=your-secret-key-here-change-in-production
 # OAUTH_ISSUER=https://your-oauth-provider.com
 # OAUTH_AUDIENCE=fula-storage
 
+# ============================================
+# Admin API (Optional)
+# ============================================
+#
+# The Admin API provides endpoints for managing user data, unpinning CIDs,
+# and garbage collection. It uses a SEPARATE JWT secret from user authentication.
+#
+# WARNING: Admin API grants powerful capabilities. Keep the secret secure!
+#
+# To enable:
+# 1. Set FULA_ADMIN_API=true
+# 2. Set ADMIN_JWT_SECRET to a strong, random string (different from JWT_SECRET)
+#
+# Admin tokens must include:
+# - "scope": "admin" (or "*") in the JWT claims
+# - Valid "exp" (expiration) claim
+#
+# Endpoints (when enabled):
+# - GET    /admin/users/{user_id}/buckets  - List user's buckets
+# - DELETE /admin/users/{user_id}          - Delete all user data
+# - DELETE /admin/pins/{cid}               - Unpin a specific CID
+# - POST   /admin/gc                       - Trigger garbage collection scan
+#
+# Enable admin API (default: false)
+FULA_ADMIN_API=false
+
+# Admin JWT secret (MUST be different from JWT_SECRET)
+# Generate with: openssl rand -base64 32
+# ADMIN_JWT_SECRET=your-admin-secret-here-change-in-production
+
 # ============================================
 # Rate Limiting
 # ============================================

crates/fula-cli/src/auth.rs

@@ -340,6 +340,63 @@ pub fn extract_token_from_header(auth_header: &str, headers: &HeaderMap) -> Resu
     ))
 }
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// ADMIN AUTHENTICATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/// Admin JWT claims structure
+#[derive(Debug, Serialize, Deserialize)]
+pub struct AdminClaims {
+    /// Subject (admin user ID)
+    pub sub: String,
+    /// Expiration time (required for admin tokens)
+    pub exp: Option<i64>,
+    /// Issued at
+    pub iat: Option<i64>,
+    /// Scope (must include "admin" or "*")
+    #[serde(default)]
+    pub scope: String,
+}
+
+impl AdminClaims {
+    /// Check if this token has admin privileges
+    pub fn is_valid_admin(&self) -> bool {
+        self.scope
+            .split_whitespace()
+            .any(|s| s == "admin" || s == "*")
+    }
+}
+
+/// Validate an admin JWT token and extract claims
+pub fn validate_admin_token(token: &str, secret: &str) -> Result<AdminClaims, ApiError> {
+    let key = DecodingKey::from_secret(secret.as_bytes());
+    let mut validation = Validation::new(Algorithm::HS256);
+    validation.validate_exp = true; // Admin tokens MUST have valid expiration
+    validation.leeway = 60; // 1 minute leeway for clock skew
+
+    let claims = decode::<AdminClaims>(token, &key, &validation)
+        .map(|data| data.claims)
+        .map_err(|e| {
+            tracing::debug!("Admin token validation failed: {}", e);
+            ApiError::s3(S3ErrorCode::InvalidToken, "Invalid or expired admin token")
+        })?;
+
+    // Verify admin scope
+    if !claims.is_valid_admin() {
+        tracing::warn!(
+            admin_id = %claims.sub,
+            scope = %claims.scope,
+            "Admin token missing required 'admin' scope"
+        );
+        return Err(ApiError::s3(
+            S3ErrorCode::AccessDenied,
+            "Token does not have admin privileges",
+        ));
+    }
+
+    Ok(claims)
+}
+
 /// Hash a user ID for storage (privacy)
 pub fn hash_user_id(user_id: &str) -> String {
     use fula_crypto::hashing::hash;

crates/fula-cli/src/config.rs

@@ -39,6 +39,10 @@ pub struct GatewayConfig {
     pub registry_cid_path: Option<String>,
     /// Storage API URL for balance/quota checking before uploads
     pub storage_api_url: Option<String>,
+    /// Admin JWT secret for admin API authentication (separate from user JWT)
+    pub admin_jwt_secret: Option<String>,
+    /// Enable admin API endpoints
+    pub admin_api_enabled: bool,
 }
 
 impl Default for GatewayConfig {
@@ -61,6 +65,8 @@ impl Default for GatewayConfig {
             cors_origins: vec!["*".to_string()],
             registry_cid_path: Some("/var/lib/fula-gateway/registry.cid".to_string()),
             storage_api_url: None,
+            admin_jwt_secret: None,
+            admin_api_enabled: false,
         }
     }
 }