Spring Boot Private File Protection: Signed URLs, RBAC, Distributed Rate Limiting

1. Threat Model and Goals

Direct exposure: files placed under static/ or a public CDN prefix can be downloaded by anyone who knows the URL.

URL leakage/replay: shared links remain valid indefinitely; attackers can replay signed URLs.

Cross‑tenant over‑privilege: a user from tenant A can access tenant B files, or a logged‑in user with insufficient role can still download.

Crawler/abuse: malicious IPs or users generate high‑frequency requests, wasting bandwidth, storage, and CPU.

Transport/storage leakage: plaintext transmission, direct disk reads, or log leakage.

Design goals : trusted identity, minimal permissions, revocable links, auditable access, stability under high concurrency, and horizontal scalability.

2. Overall Architecture

Client --> API Gateway (TLS & WAF)
       --> Spring Boot service (AuthN/AuthZ, signature verification, rate limiting)
       --> Storage abstraction (Local/MinIO/S3/OSS)
       --> Redis Cluster (counters/nonce/limiting windows)
       --> Audit/ELK & Metrics (Prometheus/Grafana)

Core request flow :

POST /files/access generates a one‑time signed URL (short‑lived).

GET /files/download/** passes through a Filter/AOP that performs identity → permission → signature → rate‑limit → streaming output.

Optional: CDN caches only public files; private files are served directly from origin or a private CDN with authentication.

3. Signed‑URL Principle (Tamper‑proof & Replay‑proof)

Message format :

canonical = path + "
" + sorted(queryWithoutSign) + "
" + expireEpoch + "
" + nonce

Algorithm : HMAC‑SHA256(secret) produces a 64‑hex string; the server recomputes and compares with HmacUtils.isEqual to prevent timing attacks.

Expiration control : expireEpoch (seconds) plus server‑side time‑offset protection (recommended NTP sync).

Replay protection : nonce stored in Redis with SETNX and TTL equal to the link’s lifetime; first successful validation marks the nonce as used.

Minimal parameters : only path, userId, tenant, nonce, and expire are signed to reduce attack surface.

Core Implementation (production‑grade)

@Component
@RequiredArgsConstructor
@Slf4j
public class SignedUrlService {
    @Value("${file.sign.secret-key}")
    private String secret;
    @Value("${file.sign.expire-seconds:300}")
    private int defaultTtl;
    private final StringRedisTemplate redis;

    public String create(String path, String userId, String tenant, Integer ttlSeconds) {
        long expire = Instant.now().getEpochSecond() + Optional.ofNullable(ttlSeconds).orElse(defaultTtl);
        String nonce = UUID.randomUUID().toString();
        String canonical = canonical(path, userId, tenant, expire, nonce);
        String sign = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, secret).hmacHex(canonical);
        return String.format("/api/v1/files/download/%s?u=%s&t=%s&e=%d&n=%s&s=%s",
                UriUtils.encodePath(path, StandardCharsets.UTF_8), userId, tenant, expire, nonce, sign);
    }

    public Validation validate(String path, Map<String,String> q) {
        long now = Instant.now().getEpochSecond();
        long expire = Long.parseLong(q.getOrDefault("e", "0"));
        if (now > expire) return Validation.fail("签名已过期");
        String canonical = canonical(path, q.get("u"), q.get("t"), expire, q.get("n"));
        String expected = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, secret).hmacHex(canonical);
        if (!HmacUtils.isEqualHex(expected, q.get("s"))) return Validation.fail("签名不匹配");
        String nonceKey = "file:nonce:" + q.get("n");
        Boolean firstSeen = redis.opsForValue().setIfAbsent(nonceKey, "1", Duration.ofSeconds(expire - now));
        if (Boolean.FALSE.equals(firstSeen)) return Validation.fail("签名已被使用");
        return Validation.pass(q.get("u"), q.get("t"));
    }

    private String canonical(String path, String userId, String tenant, long expire, String nonce) {
        return String.join("
", path, userId, tenant, String.valueOf(expire), nonce);
    }

    public static class Validation {
        public final boolean ok;
        public final String userId;
        public final String tenant;
        public final String reason;
        private Validation(boolean ok, String uid, String tenant, String reason) {
            this.ok = ok; this.userId = uid; this.tenant = tenant; this.reason = reason;
        }
        public static Validation pass(String uid, String tenant) { return new Validation(true, uid, tenant, null); }
        public static Validation fail(String reason) { return new Validation(false, null, null, reason); }
    }
}

4. Permission and Multi‑Tenant Model (RBAC + ABAC)

Identity source : JWT / Session / OAuth2 carries userId and tenantId in the Authentication object.

RBAC : role‑based checks via @PreAuthorize("hasAuthority('FILE_READ')").

ABAC : AOP validates file owner, tenant isolation, and business tags (e.g., contract‑order association).

Sharing / delegation : FileShare records target user, permission, and expiry; priority order is super‑admin > owner > shared permission.

AOP Aspect Highlights

@Around("@annotation(fileAccess)")
public Object guard(ProceedingJoinPoint pjp, FileAccess fileAccess) throws Throwable {
    HttpServletRequest req = ((ServletRequestAttributes) RequestContextHolder.currentRequestAttributes()).getRequest();
    String path = extractPath(req);
    Map<String,String> q = requestParams(req);
    SignedUrlService.Validation sig = signedUrlService.validate(path, q);
    if (!sig.ok) throw new InvalidSignatureException(sig.reason);
    UserPrincipal user = auth();
    if (!user.getId().equals(sig.userId()))
        throw new AccessDeniedException("签名用户与当前用户不匹配");
    if (!user.getTenantId().equals(sig.tenant()))
        throw new AccessDeniedException("租户隔离校验失败");
    FileRecord fr = fileRepo.findByPath(path).orElseThrow(() -> new AccessDeniedException("文件不存在"));
    if (fileAccess.checkOwner() && !Objects.equals(fr.getOwnerId(), user.getId()) && !shareService.allow(user, fr)) {
        throw new AccessDeniedException("无权访问文件");
    }
    if (!Arrays.stream(fileAccess.allowedTypes()).anyMatch(t -> t.matches(fr.getMimeType()))) {
        throw new AccessDeniedException("文件类型不被允许");
    }
    return pjp.proceed();
}

Engineering notes :

Aspect priority higher than business logic to prevent controller escape.

Unified validation dependency; use UserPrincipal instead of re‑parsing JWT in controllers.

Tenant ID must be part of the signature string; DB queries filter by tenant.

5. Distributed Rate Limiting (Redis + Lua + Dimensional)

Dimensions : GLOBAL / IP / USER / PATH can be combined.

Algorithm : sliding‑window counter implemented in Lua for atomicity; token‑bucket can be switched on peaks.

Key format : rl:{dim}:{value}:{windowStart} with TTL = window + 1 s.

Back‑origin protection : stricter rate limiting on the signature‑generation endpoint to avoid enumeration attacks.

@Component
@RequiredArgsConstructor
public class RedisRateLimiter {
    private final StringRedisTemplate redis;
    private static final String LUA =
            "local c=redis.call
" +
            "local key=KEYS[1]
" +
            "local limit=tonumber(ARGV[1])
" +
            "local window=tonumber(ARGV[2])
" +
            "local current=c('INCR', key)
" +
            "if current==1 then c('EXPIRE', key, window) end
" +
            "return current<=limit";

    public boolean acquire(String key, int limit, int windowSeconds) {
        Boolean ok = redis.execute((RedisCallback<Boolean>) con ->
                (Boolean) con.scriptingCommands().eval(LUA.getBytes(StandardCharsets.UTF_8), ReturnType.BOOLEAN,
                        1, key.getBytes(StandardCharsets.UTF_8),
                        String.valueOf(limit).getBytes(),
                        String.valueOf(windowSeconds).getBytes()));
        return Boolean.TRUE.equals(ok);
    }
}

High‑Concurrency Optimizations

Use Redis Cluster with hash tags ( {rl}:{dim}) for balanced slots.

Graceful degradation: if Redis is unavailable, allow traffic with warning header X-RateLimit-Warn: degraded and raise alerts.

Interface‑level throttling policies (e.g., 50 req/min/USER for download, 20 req/min/USER for signature generation, 200 req/min/IP for public resources, 10k req/min/GLOBAL for health checks).

6. File Storage and Transfer

Storage abstraction : FileStorage interface with implementations for local filesystem, MinIO/S3, and Alibaba OSS, enabling horizontal scaling and multi‑active deployments.

Directory & permissions : private files never reside under static; they are mounted under /data/files with containers using read‑only root FS.

Transport security : enforce end‑to‑end HTTPS and set Cache‑Control: private, no-store on responses.

Range support : large files served via RandomAccessFile or object‑storage multipart download to enable resumable transfers and reduce per‑request memory usage.

public interface FileStorage {
    InputStream read(String path) throws IOException;
    void save(String path, InputStream in, long size, String contentType) throws IOException;
    FileMeta stat(String path) throws IOException;
}

7. Controller and Response Pattern

Download endpoint returns ResponseEntity<Resource> with Content‑Disposition, Content‑Type, Content‑Length, and Cache‑Control: private, no-store, and disables browser sniffing via X‑Content‑Type‑Options: nosniff.

Stream output using InputStreamResource and StreamUtils.copy to avoid loading the whole file into memory.

Standard HTTP status codes (403/429/404/410) are used for failures to aid CDN/proxy handling.

@GetMapping("/api/v1/files/download/**")
@FileAccess
@RateLimit(maxRequests = 50, window = 60, dimension = RateLimitDimension.USER)
public ResponseEntity<Resource> download(HttpServletRequest req) throws IOException {
    String path = resolvePath(req);
    FileRecord fr = fileService.getFileRecordByPath(path);
    Resource resource = fileService.asResource(path);
    return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION,
                    ContentDisposition.attachment().filename(fr.getFileName(), StandardCharsets.UTF_8).build().toString())
            .header(HttpHeaders.CONTENT_TYPE, fr.getMimeType())
            .header(HttpHeaders.CONTENT_LENGTH, String.valueOf(fr.getFileSize()))
            .header(HttpHeaders.CACHE_CONTROL, "private, no-store")
            .body(resource);
}

8. Production Baseline Configuration

spring:
  data:
    redis:
      host: 10.0.0.5
      cluster.nodes: 10.0.0.5:6379,10.0.0.6:6379
file:
  sign:
    secret-key: ${FILE_SIGN_SECRET}   # 256‑bit random, rotated quarterly
    expire-seconds: 300
  storage:
    type: s3
    base-path: /data/files/private
    bucket: private-bucket
    max-file-size: 200MB
    allowed-types:
      - application/pdf
      - image/jpeg
      - video/mp4
  rate-limit:
    default-requests: 100
    default-window: 60
logging:
  level:
    com.example.fileprotect: INFO
server:
  forward-headers-strategy: framework   # support X‑Forwarded‑For

Runtime parameters : -Duser.timezone=UTC to keep signature timestamps consistent.

JVM flags -Xms512m -Xmx512m with G1 collector to avoid Full GC latency spikes.

9. Observability and Auditing

Metrics (Prometheus) : file_access_total, file_access_denied_total, signature_validation_failed, rate_limit_triggered_total, file_download_bytes_total, storage_latency_ms.

Logging : JSON format, persisted and shipped to ELK, with user identifiers hashed for privacy.

Audit stream : asynchronous emission of userId, tenant, fileId, action, IP, UA, latency, and result to an audit service.

10. High‑Concurrency & Scalability Design

Stateless services: session and rate‑limit state reside entirely in Redis, enabling horizontal scaling; signature verification is pure computation plus Redis SETNX.

Connection & threading: use WebFlux or Servlet + Tomcat NIO; large file transfer employs segmented reads and zero‑copy via ResourceRegion.

Back‑origin pressure control: limit CDN back‑origin bandwidth; prefer S3/OSS pre‑signed direct download for large files.

Degradation strategy: when Redis is down, relax rate limiting and emit warning header X-RateLimit-Warn: degraded; on object‑storage failure, fall back to local copy or delayed retry queue.

Key rotation: support dual keys ( activeKeyId + nextKeyId) so new signatures use the new key while verification accepts both.

Multi‑active deployment: keep signature window 5–10 minutes, inter‑region latency < 200 ms; Redis cross‑AZ bidirectional sync or per‑AZ local verification with global KMS.

11. Production‑Grade Refactoring Recommendations

Centralized configuration via @ConfigurationProperties(prefix="file"); avoid hard‑coded paths and secrets.

Unified error handling with an ErrorCode enum; clients can react based on the code field.

Security headers globally added: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Strict-Transport-Security.

Input sanitization: whitelist characters for download paths (letters, digits, -_./) and validate with Paths.get(base, path).normalize() to prevent directory traversal.

Test coverage: signature (expiry, tampering, tenant mismatch, nonce replay); rate limiting under concurrency; controller tests for permission, tenant, rate‑limit, and type rejection; end‑to‑end integration with MinIO/S3 simulators (localstack/minio).

Performance benchmark: use wrk or hey to stress a single instance at 50 concurrent users downloading 10 MB files, measuring QPS and P99 latency; include object‑storage latency simulation.

12. Release & Operations Checklist

Verify FILE_SIGN_SECRET is injected and not logged.

Ensure Redis cluster health; master‑slave latency < 100 ms.

Object‑storage credentials and KMS permissions follow least‑privilege (read/write only specific bucket prefixes).

Enable HTTPS and HTTP/2; CDN/reverse‑proxy must strip hop‑by‑hop headers but forward X-Forwarded-For.

Canary release: run old and new keys in parallel; make rate‑limit parameters dynamically configurable via config center.

Observability alerts: trigger when signature failure rate, rate‑limit trigger rate, or 4xx/5xx download ratio exceeds thresholds.

13. Key Class Directory Example

com.example.fileprotect
├── config
│   └── FileProtectionProperties.java
├── core
│   └── SignedUrlService.java
├── security
│   ├── FileAccess.java
│   ├── FileAccessAspect.java
│   └── RateLimit.java / RateLimitAspect.java
├── limiter
│   └── RedisRateLimiter.java
├── storage
│   ├── FileStorage.java
│   ├── LocalFileStorage.java
│   └── S3FileStorage.java
├── controller
│   └── FileController.java
└── service
    └── FileService.java

14. Summary

Use signed URLs as the first line of defense, combined with RBAC/ABAC to enforce tenant and owner security.

Employ Redis + Lua for distributed rate limiting and replay protection, achieving linear scalability under high load.

Abstract storage behind an interface, support object storage and encryption, and leverage Range/zero‑copy for efficient large‑file transfer.

Integrate observability, key rotation, and degradation strategies to maintain stability and maintainability in production.