up

src/Excititor/StellaOps.Excititor.WebService/Contracts/VexEvidenceContracts.cs

@@ -49,6 +49,36 @@ public sealed record VexEvidenceListItem(
     [property: JsonPropertyName("itemCount")] int ItemCount,
     [property: JsonPropertyName("verified")] bool Verified);
 
+/// <summary>
+/// Evidence Locker manifest reference returned by /evidence/vex/locker/*.
+/// </summary>
+public sealed record VexEvidenceLockerResponse(
+    [property: JsonPropertyName("bundleId")] string BundleId,
+    [property: JsonPropertyName("mirrorGeneration")] string MirrorGeneration,
+    [property: JsonPropertyName("tenant")] string Tenant,
+    [property: JsonPropertyName("publisher")] string Publisher,
+    [property: JsonPropertyName("payloadHash")] string PayloadHash,
+    [property: JsonPropertyName("manifestPath")] string ManifestPath,
+    [property: JsonPropertyName("manifestHash")] string ManifestHash,
+    [property: JsonPropertyName("evidencePath")] string EvidencePath,
+    [property: JsonPropertyName("evidenceHash")] string? EvidenceHash,
+    [property: JsonPropertyName("manifestSizeBytes")] long? ManifestSizeBytes,
+    [property: JsonPropertyName("evidenceSizeBytes")] long? EvidenceSizeBytes,
+    [property: JsonPropertyName("importedAt")] DateTimeOffset ImportedAt,
+    [property: JsonPropertyName("stalenessSeconds")] int? StalenessSeconds,
+    [property: JsonPropertyName("transparencyLog")] string? TransparencyLog,
+    [property: JsonPropertyName("timeline")] IReadOnlyList<VexEvidenceLockerTimelineEntry> Timeline);
+
+/// <summary>
+/// Timeline event for air-gapped imports.
+/// </summary>
+public sealed record VexEvidenceLockerTimelineEntry(
+    [property: JsonPropertyName("eventType")] string EventType,
+    [property: JsonPropertyName("createdAt")] DateTimeOffset CreatedAt,
+    [property: JsonPropertyName("errorCode")] string? ErrorCode,
+    [property: JsonPropertyName("message")] string? Message,
+    [property: JsonPropertyName("stalenessSeconds")] int? StalenessSeconds);
+
 /// <summary>
 /// Response for /evidence/vex/lookup endpoint.
 /// </summary>

src/Excititor/StellaOps.Excititor.WebService/Endpoints/EvidenceEndpoints.cs

@@ -4,6 +4,8 @@ using System.Collections.Immutable;
 using System.Diagnostics;
 using System.Globalization;
 using System.Linq;
+using System.IO;
+using System.Threading.Tasks;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
@@ -17,6 +19,7 @@ using StellaOps.Excititor.Storage.Mongo;
 using StellaOps.Excititor.WebService.Contracts;
 using StellaOps.Excititor.WebService.Services;
 using StellaOps.Excititor.WebService.Telemetry;
+using StellaOps.Excititor.WebService.Options;
 
 namespace StellaOps.Excititor.WebService.Endpoints;
 
@@ -436,6 +439,115 @@ public static class EvidenceEndpoints
 
             return Results.Ok(response);
         }).WithName("GetVexAdvisoryEvidence");
+
+        // GET /evidence/vex/locker/{bundleId}
+        app.MapGet("/evidence/vex/locker/{bundleId}", async (
+            HttpContext context,
+            string bundleId,
+            [FromQuery] string? generation,
+            IOptions<VexMongoStorageOptions> storageOptions,
+            IOptions<AirgapOptions> airgapOptions,
+            [FromServices] IAirgapImportStore airgapImportStore,
+            [FromServices] IVexHashingService hashingService,
+            CancellationToken cancellationToken) =>
+        {
+            var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
+            if (scopeResult is not null)
+            {
+                return scopeResult;
+            }
+
+            if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
+            {
+                return tenantError;
+            }
+
+            if (string.IsNullOrWhiteSpace(bundleId))
+            {
+                return Results.BadRequest(new { error = new { code = "ERR_BUNDLE_ID", message = "bundleId is required" } });
+            }
+
+            var record = await airgapImportStore.FindByBundleIdAsync(tenant, bundleId.Trim(), generation?.Trim(), cancellationToken)
+                .ConfigureAwait(false);
+
+            if (record is null)
+            {
+                return Results.NotFound(new { error = new { code = "ERR_NOT_FOUND", message = "Locker manifest not found" } });
+            }
+
+            // Optional local hash/size computation when locker root is configured
+            long? manifestSize = null;
+            long? evidenceSize = null;
+            string? evidenceHash = null;
+
+            var lockerRoot = airgapOptions.Value.LockerRootPath;
+            if (!string.IsNullOrWhiteSpace(lockerRoot))
+            {
+                TryHashFile(lockerRoot, record.PortableManifestPath, hashingService, out var manifestHash, out manifestSize);
+                if (!string.IsNullOrWhiteSpace(manifestHash))
+                {
+                    record.PortableManifestHash = manifestHash!;
+                }
+
+                TryHashFile(lockerRoot, record.EvidenceLockerPath, hashingService, out evidenceHash, out evidenceSize);
+            }
+
+            var timeline = record.Timeline
+                .OrderBy(entry => entry.CreatedAt)
+                .Select(entry => new VexEvidenceLockerTimelineEntry(
+                    entry.EventType,
+                    entry.CreatedAt,
+                    entry.ErrorCode,
+                    entry.Message,
+                    entry.StalenessSeconds))
+                .ToList();
+
+            var response = new VexEvidenceLockerResponse(
+                record.BundleId,
+                record.MirrorGeneration,
+                record.TenantId,
+                record.Publisher,
+                record.PayloadHash,
+                record.PortableManifestPath,
+                record.PortableManifestHash,
+                record.EvidenceLockerPath,
+                evidenceHash,
+                manifestSize,
+                evidenceSize,
+                record.ImportedAt,
+                record.Timeline.FirstOrDefault()?.StalenessSeconds,
+                record.TransparencyLog,
+                timeline);
+
+            return Results.Ok(response);
+        }).WithName("GetVexEvidenceLockerManifest");
+    }
+
+    private static void TryHashFile(string root, string relativePath, IVexHashingService hashingService, out string? digest, out long? size)
+    {
+        digest = null;
+        size = null;
+        try
+        {
+            if (string.IsNullOrWhiteSpace(relativePath))
+            {
+                return;
+            }
+
+            var fullPath = Path.GetFullPath(Path.Combine(root, relativePath));
+            if (!File.Exists(fullPath))
+            {
+                return;
+            }
+
+            var data = File.ReadAllBytes(fullPath);
+            digest = hashingService.ComputeHash(data, "sha256");
+            size = data.LongLength;
+        }
+        catch
+        {
+            // Ignore I/O errors and continue with stored metadata
+        }
     }
 
     private static bool TryResolveTenant(HttpContext context, VexMongoStorageOptions options, out string tenant, out IResult? problem)

src/Excititor/StellaOps.Excititor.WebService/Options/AirgapOptions.cs

@@ -22,4 +22,12 @@ internal sealed class AirgapOptions
     /// Empty list means allow all.
     /// </summary>
     public List<string> TrustedPublishers { get; } = new();
+
+    /// <summary>
+    /// Optional root path for locally stored locker artefacts (portable manifest, evidence NDJSON).
+    /// When set, /evidence/vex/locker/* endpoints will attempt to read files from this root to
+    /// compute deterministic hashes and sizes; otherwise only stored hashes are returned.
+    /// </summary>
+    public string? LockerRootPath { get; set; }
+        = null;
 }

src/Excititor/__Tests/StellaOps.Excititor.WebService.Tests/EvidenceLockerEndpointTests.cs

@@ -0,0 +1,131 @@
+using System;
+using System.IO;
+using System.Net;
+using System.Net.Http.Json;
+using System.Net.Http.Headers;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using StellaOps.Excititor.Storage.Mongo;
+using StellaOps.Excititor.WebService.Contracts;
+using StellaOps.Excititor.WebService.Options;
+using Xunit;
+
+namespace StellaOps.Excititor.WebService.Tests;
+
+public sealed class EvidenceLockerEndpointTests : IAsyncLifetime
+{
+    private readonly string _tempDir = Path.Combine(Path.GetTempPath(), "excititor-locker-tests-" + Guid.NewGuid());
+    private TestWebApplicationFactory _factory = null!;
+
+    [Fact]
+    public async Task LockerEndpoint_ReturnsHashesFromLocalFiles_WhenLockerRootConfigured()
+    {
+        Directory.CreateDirectory(_tempDir);
+        var manifestRel = Path.Combine("locker", "bundle-1", "g1", "manifest.json");
+        var evidenceRel = Path.Combine("locker", "bundle-1", "g1", "bundle.ndjson");
+        var manifestFull = Path.Combine(_tempDir, manifestRel);
+        var evidenceFull = Path.Combine(_tempDir, evidenceRel);
+        Directory.CreateDirectory(Path.GetDirectoryName(manifestFull)!);
+        await File.WriteAllTextAsync(manifestFull, "{\n  \"id\": \"bundle-1\"\n}\n");
+        await File.WriteAllTextAsync(evidenceFull, "line1\nline2\n");
+
+        var record = new AirgapImportRecord
+        {
+            Id = "bundle-1:g1",
+            TenantId = "test",
+            BundleId = "bundle-1",
+            MirrorGeneration = "g1",
+            Publisher = "test-pub",
+            PayloadHash = "sha256:payload",
+            Signature = "sig",
+            PortableManifestPath = manifestRel,
+            PortableManifestHash = "sha256:old",
+            EvidenceLockerPath = evidenceRel,
+            ImportedAt = DateTimeOffset.UtcNow,
+            SignedAt = DateTimeOffset.UtcNow,
+        };
+
+        var stub = (StubAirgapImportStore)_factory.Services.GetRequiredService<IAirgapImportStore>();
+        await stub.SaveAsync(record, CancellationToken.None);
+
+        using var client = _factory.WithWebHostBuilder(_ => { }).CreateClient();
+
+        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "vex.read");
+
+        var response = await client.GetAsync($"/evidence/vex/locker/{record.BundleId}");
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+
+        var payload = await response.Content.ReadFromJsonAsync<VexEvidenceLockerResponse>();
+        Assert.NotNull(payload);
+        Assert.Equal("test", payload!.Tenant);
+        Assert.Equal(record.BundleId, payload.BundleId);
+        Assert.Equal("sha256:22734ec66c856d27d0023839d8ea11cdeaac379496952e52d204b3265981af66", payload.ManifestHash);
+        Assert.Equal("sha256:2751a3a2f303ad21752038085e2b8c5f98ecff61a2e4ebbd43506a941725be80", payload.EvidenceHash);
+        Assert.Equal(23, payload.ManifestSizeBytes);
+        Assert.Equal(12, payload.EvidenceSizeBytes);
+    }
+
+    public Task InitializeAsync()
+    {
+        _factory = new TestWebApplicationFactory(
+            configureConfiguration: config =>
+            {
+                config.AddInMemoryCollection(new[]
+                {
+                    new KeyValuePair<string, string?>("Excititor:Airgap:LockerRootPath", _tempDir)
+                });
+            },
+            configureServices: services =>
+            {
+                services.RemoveAll<IAirgapImportStore>();
+                services.AddSingleton<IAirgapImportStore>(new StubAirgapImportStore());
+            });
+
+        return Task.CompletedTask;
+    }
+
+    public Task DisposeAsync()
+    {
+        try
+        {
+            Directory.Delete(_tempDir, recursive: true);
+        }
+        catch
+        {
+            // ignore cleanup errors
+        }
+
+        _factory.Dispose();
+        return Task.CompletedTask;
+    }
+
+    private sealed class StubAirgapImportStore : IAirgapImportStore
+    {
+        private AirgapImportRecord? _record;
+
+        public Task SaveAsync(AirgapImportRecord record, CancellationToken cancellationToken)
+        {
+            _record = record;
+            return Task.CompletedTask;
+        }
+
+        public Task<AirgapImportRecord?> FindByBundleIdAsync(string tenantId, string bundleId, string? mirrorGeneration, CancellationToken cancellationToken)
+        {
+            return Task.FromResult(_record);
+        }
+
+        public Task<IReadOnlyList<AirgapImportRecord>> ListAsync(string tenantId, string? publisherFilter, DateTimeOffset? importedAfter, int limit, int offset, CancellationToken cancellationToken)
+        {
+            IReadOnlyList<AirgapImportRecord> list = _record is null ? Array.Empty<AirgapImportRecord>() : new[] { _record };
+            return Task.FromResult(list);
+        }
+
+        public Task<int> CountAsync(string tenantId, string? publisherFilter, DateTimeOffset? importedAfter, CancellationToken cancellationToken)
+        {
+            return Task.FromResult(_record is null ? 0 : 1);
+        }
+    }
+}