Defines private-origin CDN delivery with authorization-aware URL issuance, immutable asset versions, safe caching keys, revocation behavior, range requests, and response security headers.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Keep the object origin private. Serve immutable public assets through content-versioned URLs; serve protected assets through short-lived signed requests whose cache key includes the authorization partition and excludes reusable credentials.
Scope
- Origin access, URL forms, signing, cache key, headers, invalidation, range requests, downloads, logging, and abuse controls.
- Public immutable assets and protected user files as distinct delivery classes.
- Cache and origin observability.
Outside this block
- Application authorization policy itself.
- Assuming URL secrecy is sufficient for indefinitely shareable sensitive files.
Contract
- CDN identity, not the public internet, is allowed to read the private origin.
- Public immutable objects use versioned keys and long cache lifetimes; changing bytes creates a new URL.
- Protected delivery checks application authorization before issuing a bounded token or signed URL.
- The protected cache key includes tenant/visibility partition and object version while excluding signature and irrelevant query noise.
- Responses set an explicit media type, disposition, cache policy, content sniffing protection, and safe filename encoding.
- Revocation objectives state whether expiry alone is sufficient or an application/CDN deny mechanism is required.
Implementation guidance
- Use separate hostnames or behaviors for public assets and protected downloads.
- Sign a canonical path, object version, expiry, audience or policy ID, and allowed method.
- Validate range requests and cap amplification; preserve digest or ETag for immutable objects.
- Log stable object identifiers, cache status, bytes, and policy outcome while minimizing sensitive names and tokens.
Failure handling and safeguards
- If token validation or authorization issuance is unavailable, fail protected delivery rather than falling back to public origin.
- If a cached protected response lacks the required partition, purge it and disable that behavior.
- If content metadata is unsafe or absent, force download with a generic safe name.
Verification and operations
- Measure cache hit ratio and origin bytes by delivery class, signing failures, authorization denials, stale-version requests, range amplification, and revocation time.
- Test cache-poisoning inputs and cross-tenant requests against the actual CDN configuration.
- Review origin policy and cache-key configuration as deployable, versioned artifacts.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.