Tile-Proxy Service Design

Overview

The Tile-Proxy service acts as an intermediary between StellaOps clients and upstream Rekor transparency log APIs. It provides centralized tile caching, request coalescing, and offline support for air-gapped environments.

Offline default (2026-07-12, EVI-3 / sprint SPRINT_20260712_003). The service ships with no upstream (tile_proxy:UpstreamUrl is empty) and the sync job disabled. In that state it serves only the tiles already present in its content-addressed cache and performs zero network egress: a cache miss returns 503 upstream_not_configured (not 502, which means an upstream we do have failed), and GET /_admin/ready reports {"ready": true, "mode": "offline-cache-only"} rather than probing upstream — a readiness probe must not become the thing that dials out.

Choosing an upstream is an explicit operator act. Enabling Sync.Enabled without an upstream is rejected at startup (TileProxyOptionsValidator) — the service never falls back to a hardcoded public log. See “Configuration” below and devops/compose/README.md § Tile Proxy.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  CI/CD Agents   │────►│   Tile Proxy    │────►│   Rekor API     │
│  (StellaOps)    │     │   (StellaOps)   │     │   (Upstream)    │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Tile Cache     │     │  TUF Metadata   │     │  Checkpoint     │
│  (CAS Store)    │     │  (TrustRepo)    │     │  Cache          │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Core Responsibilities

1. Tile Proxying: Forward tile requests to upstream Rekor, caching responses locally
2. Content-Addressed Storage: Store tiles by hash for deduplication and immutability
3. TUF Integration: Optionally validate metadata using TUF trust anchors
4. Request Coalescing: Deduplicate concurrent requests for the same tile
5. Checkpoint Caching: Cache and serve recent checkpoints
6. Offline Mode: Serve from cache when upstream is unavailable

API Surface

Proxy Endpoints (Passthrough)

Admin Endpoints

Caching Strategy

Content-Addressed Tile Storage

Tiles are stored using content-addressed paths based on SHA-256 hash:

{cache_root}/
├── tiles/
│   ├── {origin_hash}/
│   │   ├── {level}/
│   │   │   ├── {index}.tile
│   │   │   └── {index}.meta.json
│   │   └── checkpoints/
│   │       └── {tree_size}.checkpoint
│   └── ...
└── metadata/
    └── cache_stats.json

Tile Metadata

Each tile has associated metadata:

{
  "cachedAt": "2026-01-25T10:00:00Z",
  "treeSize": 1050000,
  "isPartial": false,
  "contentHash": "sha256:abc123...",
  "upstreamUrl": "https://rekor.sigstore.dev"
}

Eviction Policy

1. LRU by Access Time: Least recently accessed tiles evicted first
2. Max Size Limit: Configurable maximum cache size
3. TTL Override: Force re-fetch after configurable time (for checkpoints)
4. Immutability Preservation: Full tiles (width=256) never evicted unless explicitly pruned

Request Coalescing

Concurrent requests for the same tile are coalesced:

// Pseudo-code for request coalescing
var key = $"{origin}/{level}/{index}";
if (_inflightRequests.TryGetValue(key, out var existing))
{
    return await existing; // Wait for in-flight request
}

var tcs = new TaskCompletionSource<byte[]>();
_inflightRequests[key] = tcs.Task;
try
{
    var tile = await FetchFromUpstream(origin, level, index);
    tcs.SetResult(tile);
    return tile;
}
finally
{
    _inflightRequests.Remove(key);
}

TUF Integration Point

When TufValidationEnabled is true:

1. Load service map from TUF to discover Rekor URL
2. Validate Rekor public key from TUF targets
3. Verify checkpoint signatures using TUF-loaded keys
4. Reject tiles if checkpoint signature invalid

Upstream Failover

Support multiple upstream sources with failover:

tile_proxy:
  upstreams:
    - url: https://rekor.sigstore.dev
      priority: 1
      timeout: 30s
    - url: https://rekor-mirror.internal
      priority: 2
      timeout: 10s

Failover behavior:

1. Try primary upstream first
2. On timeout/error, try next upstream
3. Cache successful source for subsequent requests
4. Reset failover state on explicit refresh

Deployment Model

One service, two ways to connect it

The stack runs one tile proxy: attestor-tileproxy (stellaops/attestor-tileproxy), defined in devops/compose/docker-compose.stella-services.yml. It ships with no upstream and a tmpfs cache. There are two ways to connect it to a log:

• Environment only. Set ATTESTOR_TILEPROXY_UPSTREAM_URL, ATTESTOR_TILEPROXY_ORIGIN and ATTESTOR_TILEPROXY_SYNC_ENABLED (empty/false by default). The cache stays in the tmpfs.
• The opt-in overlay devops/compose/docker-compose.tile-proxy.yml. It configures the same attestor-tileproxy service; it does not start a second proxy. It requires TILE_PROXY_UPSTREAM_URL (compose refuses to render without it), replaces the tmpfs with the named volumes tile-cache (/var/cache/stellaops/tiles) and tuf-cache (/var/cache/stellaops/tuf), publishes ${TILE_PROXY_PORT:-8090}:8080, and sets the TUF, cache, sync and request settings from TILE_PROXY_* variables.

TILE_PROXY_UPSTREAM_URL=https://rekor.sigstore.dev TILE_PROXY_ORIGIN='rekor.sigstore.dev - 1985497715' docker compose -f docker-compose.stella-ops.yml -f docker-compose.tile-proxy.yml up -d

Until 2026-09-27 the overlay defined its own tile-proxy service built from the same project, so enabling it ran two copies of one deployable (SPRINT_20260927_002 PCD-72).

Metrics

GET /_admin/metrics returns a JSON snapshot, not a Prometheus exposition: cacheHits, cacheMisses, hitRatePercent, upstreamRequests, upstreamErrors, inflightRequests (Endpoints/TileEndpoints.cs, MetricsResponse). No Prometheus meter is registered by the host.

Configuration

Section tile_proxy; env prefix TILE_PROXY__ (so the env form of tile_proxy:UpstreamUrl is TILE_PROXY__tile_proxy__UpstreamUrl). Keys are PascalCase: the configuration binder matches property names case-insensitively but does not strip underscores, so a snake_case key (upstream_url, max_size_gb, …) binds to nothing and silently leaves the C# default in force.

Shipped defaults (src/Attestor/StellaOps.Attestor.TileProxy/appsettings.json) — offline:

{
  "tile_proxy": {
    "UpstreamUrl": "",                 // no upstream: cache-only, zero egress
    "Origin": "stellaops-tileproxy",   // cache namespace
    "Cache":   { "MaxSizeGb": 10, "EvictionPolicy": "lru", "CheckpointTtlMinutes": 5 },
    "Tuf":     { "Enabled": false, "ValidateCheckpointSignature": true },
    "Sync":    { "Enabled": false, "Schedule": "0 */6 * * *", "Depth": 10000 },
    "Request": { "CoalescingEnabled": true, "CoalescingMaxWaitMs": 5000, "TimeoutSeconds": 30 },
    "Failover":{ "Enabled": false, "RetryCount": 2, "RetryDelayMs": 1000 }
  }
}

Operator opt-in (connected deployment; values are examples, not defaults):

{
  "tile_proxy": {
    "UpstreamUrl": "https://rekor.sigstore.dev",          // or your own Rekor/Tessera
    "Origin": "rekor.sigstore.dev - 1985497715",          // that log's checkpoint origin
    "TileBaseUrl": null,                                  // defaults to {UpstreamUrl}/tile/
    "Tuf":  { "Enabled": true, "Url": "https://trust.internal.example/tuf/" },
    "Sync": { "Enabled": true, "Schedule": "0 */6 * * *", "Depth": 10000 }
  }
}

Startup validation: UpstreamUrl may be empty (offline default) but must be an absolute URI when set; Sync.Enabled requires an UpstreamUrl; Origin is required; Tuf.Url is required when Tuf.Enabled.

Security Considerations

Verified against src/ HEAD, 2026-07-12 (CLO-1). TileProxy wires no authentication or authorization middleware at all (no AddAuthentication/UseAuthorization, no client-cert validation, no rate limiter in Program.cs). The entire /_admin group is anonymous — and it is not read-only: DELETE /_admin/cache/prune deletes cached tiles. Items 2–4 below are aspirational, not implemented. This is acceptable only on a trusted internal network fronted by the router; a direct-exposed deployment must add a network ACL or reverse-proxy auth in front of /_admin.

1. No Authentication (current behaviour, not just a default): intended for internal-network use behind the router; the /_admin group (incl. state-mutating sync/prune) is unauthenticated.
2. Optional mTLS (NOT IMPLEMENTED — future): client-certificate validation is not wired in the TileProxy host.
3. Rate Limiting (NOT IMPLEMENTED — future): no per-client-IP limiter is registered.
4. Audit Logging (NOT IMPLEMENTED — future): cache operations are not emitted to an audit sink.
5. Immutable Tiles: Full tiles are never modified after caching.

Error Handling

Future Enhancements

1. Tile Prefetching: Prefetch tiles for known verification patterns
2. Multi-Log Support: Support multiple transparency logs
3. Replication: Sync cache between proxy instances
4. Compression: Optional tile compression for storage