Files
ExecuteR/tests/Backend.Tests/DeviceFileEndpointTests.cs
Alphaeus Mote bcc44038f8 feat(server): device file routes, and browsing and searching S3
files.browse reads and files.manage changes, in device scope and on the audit
trail. Nothing is stored: transfers stream through the node holding the browser's
request. System roles now follow what their version grants, so Operator picks up
new permissions on upgrade.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 04:17:51 -05:00

403 lines
18 KiB
C#

using System.Net;
using System.Net.Http.Json;
using System.Text;
using Backend.Auth;
using Backend.Data;
using Backend.DeviceFiles;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Shared.Contracts.Api;
using Shared.Contracts.Messages;
using Shared.Contracts.Serialization;
using Xunit;
namespace Backend.Tests;
/// <summary>Answers for a device's agent, and remembers what it was asked.</summary>
public sealed class FakeDeviceFileClient : IDeviceFileClient
{
public List<DeviceFileRequest> Requests { get; } = [];
public Func<DeviceFileRequest, DeviceFileReply> Answer { get; set; } = _ => new DeviceFileReply(DeviceFileStatuses.Ok);
public bool Offline { get; set; }
public byte[] Content { get; set; } = [];
public byte[]? Written { get; private set; }
public bool BreakAfterHeaders { get; set; }
private DeviceFileReply Respond(DeviceFileRequest request)
{
if (Offline)
{
throw new DeviceFilesUnavailableException("The device did not answer.");
}
lock (Requests)
{
Requests.Add(request);
}
return Answer(request);
}
public Task<DeviceFileReply> RequestAsync(string clientId, DeviceFileRequest request, TimeSpan timeout, CancellationToken cancellationToken)
=> Task.FromResult(Respond(request));
public Task<IDeviceFileRead> OpenReadAsync(string clientId, DeviceFileRequest request, CancellationToken cancellationToken)
=> Task.FromResult<IDeviceFileRead>(new Read(Respond(request), Content, BreakAfterHeaders));
public async Task<DeviceFileReply> WriteAsync(string clientId, DeviceFileRequest request, Stream content, CancellationToken cancellationToken)
{
var reply = Respond(request);
using var copy = new MemoryStream();
await content.CopyToAsync(copy, cancellationToken);
Written = copy.ToArray();
return reply;
}
private sealed class Read(DeviceFileReply reply, byte[] content, bool fails) : IDeviceFileRead
{
public DeviceFileReply Reply => reply;
public async Task CopyToAsync(Stream target, CancellationToken cancellationToken)
{
await target.WriteAsync(content, cancellationToken);
if (fails)
{
throw new DeviceFileStreamException("The device went away.");
}
}
public ValueTask DisposeAsync() => ValueTask.CompletedTask;
}
}
/// <summary>The file browser's routes: who may do what, what is audited, and how the agent's answers reach the console.</summary>
public class DeviceFileEndpointTests(BackendTestFixture fixture) : IClassFixture<BackendTestFixture>
{
private FakeDeviceFileClient Agent => fixture.DeviceFiles;
private static string Route(string clientId, string leaf) => ApiRoutes.For.DeviceFs(clientId, leaf);
private static StringContent Json(object body) => new(JsonDefaults.Serialize(body), Encoding.UTF8, "application/json");
private Task<List<AuditEventEntity>> AuditAsync(string clientId) => fixture.WithDbAsync(db => db.AuditEvents.AsNoTracking()
.Where(e => e.ClientId == clientId && e.Category == "files")
.OrderBy(e => e.Id)
.ToListAsync());
[Fact]
public async Task ViewersSeeNothing_AndOperatorsCanWork()
{
var device = await fixture.SeedDeviceAsync("FILES-ROLES", online: true);
using var viewer = await fixture.SignedInAsync("files-viewer", "Viewer");
using var operatorClient = await fixture.SignedInAsync("files-operator", "Operator");
Assert.Equal(HttpStatusCode.Forbidden, (await viewer.GetAsync(Route(device, "roots"), TestContext.Current.CancellationToken)).StatusCode);
Assert.Equal(HttpStatusCode.OK, (await operatorClient.GetAsync(Route(device, "roots"), TestContext.Current.CancellationToken)).StatusCode);
Assert.Equal(HttpStatusCode.OK, (await operatorClient.PostAsync(Route(device, "folder"), Json(new { path = "C:\\x" }), TestContext.Current.CancellationToken)).StatusCode);
}
[Fact]
public async Task BrowsingAloneChangesNothing()
{
var device = await fixture.SeedDeviceAsync("FILES-BROWSE", online: true);
var roleId = await fixture.WithDbAsync(async db =>
{
var role = new RoleEntity
{
Id = Guid.NewGuid(),
Name = $"browse-{Guid.NewGuid():N}",
PermissionsJson = JsonDefaults.Serialize(new[] { Permissions.FilesBrowse }),
CreatedUtc = DateTimeOffset.UtcNow,
UpdatedUtc = DateTimeOffset.UtcNow,
};
db.Roles.Add(role);
await db.SaveChangesAsync();
return role.Id;
});
using var browser = await fixture.SignedInAsync("files-browser", roleId: roleId);
var ct = TestContext.Current.CancellationToken;
Assert.Equal(HttpStatusCode.OK, (await browser.GetAsync($"{Route(device, "list")}?path=C%3A%5C", ct)).StatusCode);
Assert.Equal(HttpStatusCode.Forbidden, (await browser.PostAsync(Route(device, "folder"), Json(new { path = "C:\\x" }), ct)).StatusCode);
Assert.Equal(HttpStatusCode.Forbidden, (await browser.PostAsync(Route(device, "delete"), Json(new { paths = new[] { "C:\\x" } }), ct)).StatusCode);
Assert.Equal(HttpStatusCode.Forbidden, (await browser.PostAsync(Route(device, "rename"), Json(new { path = "C:\\x", name = "y" }), ct)).StatusCode);
Assert.Equal(HttpStatusCode.Forbidden, (await browser.PutAsync($"{Route(device, "content")}?path=C%3A%5Cx", new ByteArrayContent([1]), ct)).StatusCode);
Assert.Equal(HttpStatusCode.Forbidden, (await browser.PutAsync(Route(device, "text"), Json(new { path = "C:\\x", text = "", encoding = "utf-8", lineEndings = "lf" }), ct)).StatusCode);
}
[Fact]
public async Task ADeviceOutOfScopeIsNotThere()
{
var mine = await fixture.SeedDeviceAsync("FILES-MINE", online: true);
var theirs = await fixture.SeedDeviceAsync("FILES-THEIRS", online: true);
using var scoped = await fixture.ScopedSignedInAsync("files-scoped", mine);
var ct = TestContext.Current.CancellationToken;
Assert.Equal(HttpStatusCode.OK, (await scoped.GetAsync(Route(mine, "roots"), ct)).StatusCode);
Assert.Equal(HttpStatusCode.NotFound, (await scoped.GetAsync(Route(theirs, "roots"), ct)).StatusCode);
Assert.Equal(HttpStatusCode.NotFound, (await scoped.GetAsync($"{Route(theirs, "text")}?path=x", ct)).StatusCode);
Assert.Equal(HttpStatusCode.NotFound, (await scoped.PutAsync($"{Route(theirs, "content")}?path=x", new ByteArrayContent([1]), ct)).StatusCode);
Assert.Equal(HttpStatusCode.NotFound, (await scoped.PostAsync(Route(theirs, "download"), new FormUrlEncodedContent([new("path", "x")]), ct)).StatusCode);
}
[Theory]
[InlineData(DeviceFileStatuses.NotFound, HttpStatusCode.NotFound)]
[InlineData(DeviceFileStatuses.Denied, HttpStatusCode.Forbidden)]
[InlineData(DeviceFileStatuses.Disabled, HttpStatusCode.Forbidden)]
[InlineData(DeviceFileStatuses.Conflict, HttpStatusCode.Conflict)]
[InlineData(DeviceFileStatuses.Invalid, HttpStatusCode.BadRequest)]
[InlineData(DeviceFileStatuses.Busy, HttpStatusCode.ServiceUnavailable)]
public async Task TheAgentsAnswersKeepTheirMeaning(string status, HttpStatusCode expected)
{
var device = await fixture.SeedDeviceAsync($"FILES-{status}", online: true);
using var admin = await fixture.SignedInAsync("files-admin");
var before = Agent.Answer;
Agent.Answer = _ => new DeviceFileReply(status, "From the device.");
try
{
var response = await admin.GetAsync($"{Route(device, "list")}?path=C%3A%5C", TestContext.Current.CancellationToken);
Assert.Equal(expected, response.StatusCode);
var problem = await response.Content.ReadFromJsonAsync<DeviceFileProblem>(JsonDefaults.Options, TestContext.Current.CancellationToken);
Assert.Equal("From the device.", problem!.Error);
Assert.Equal(status, problem.Status);
}
finally
{
Agent.Answer = before;
}
}
[Fact]
public async Task AnOfflineDeviceSaysSo()
{
var device = await fixture.SeedDeviceAsync("FILES-OFFLINE");
using var admin = await fixture.SignedInAsync("files-admin");
Agent.Offline = true;
try
{
var response = await admin.GetAsync(Route(device, "roots"), TestContext.Current.CancellationToken);
Assert.Equal(HttpStatusCode.ServiceUnavailable, response.StatusCode);
Assert.Contains("did not answer", await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken));
}
finally
{
Agent.Offline = false;
}
}
[Fact]
public async Task ChangesAreAudited_WithTheirPaths_AndListsAreNot()
{
var device = await fixture.SeedDeviceAsync("FILES-AUDIT", online: true);
using var admin = await fixture.SignedInAsync("files-audit-admin");
var ct = TestContext.Current.CancellationToken;
await admin.GetAsync($"{Route(device, "list")}?path=C%3A%5C", ct);
Assert.Empty(await AuditAsync(device));
await admin.PostAsync(Route(device, "folder"), Json(new { path = "C:\\made" }), ct);
await admin.PostAsync(Route(device, "rename"), Json(new { path = "C:\\made", name = "named" }), ct);
await admin.PostAsync(Route(device, "delete"), Json(new { paths = new[] { "C:\\named" }, recursive = true }), ct);
var audit = await AuditAsync(device);
Assert.Equal(["folder-created", "renamed", "deleted-recursive"], audit.Select(a => a.Action));
Assert.Contains("C:\\named", audit[2].Detail);
Assert.All(audit, a => Assert.Equal("files-audit-admin", a.Actor));
}
[Fact]
public async Task ARefusedChangeIsNotAuditedAsDone()
{
var device = await fixture.SeedDeviceAsync("FILES-REFUSED", online: true);
using var admin = await fixture.SignedInAsync("files-admin");
var before = Agent.Answer;
Agent.Answer = _ => new DeviceFileReply(DeviceFileStatuses.Denied);
try
{
await admin.PostAsync(Route(device, "folder"), Json(new { path = "C:\\x" }), TestContext.Current.CancellationToken);
}
finally
{
Agent.Answer = before;
}
Assert.Empty(await AuditAsync(device));
}
[Fact]
public async Task AnUploadPassesThroughWithItsOptions()
{
var device = await fixture.SeedDeviceAsync("FILES-UPLOAD", online: true);
using var admin = await fixture.SignedInAsync("files-admin");
var before = Agent.Answer;
Agent.Answer = _ => new DeviceFileReply(DeviceFileStatuses.Ok, Path: "C:\\a.bin", Length: 3, Sha256: "abc");
try
{
var response = await admin.PutAsync(
$"{Route(device, "content")}?path=C%3A%5Ca.bin&overwrite=true", new ByteArrayContent([1, 2, 3]), TestContext.Current.CancellationToken);
Assert.Equal(HttpStatusCode.OK, response.StatusCode);
Assert.Equal(new byte[] { 1, 2, 3 }, Agent.Written);
lock (Agent.Requests)
{
var asked = Agent.Requests.Last(r => r.Operation == DeviceFileOperations.Write);
Assert.Equal("C:\\a.bin", asked.Path);
Assert.True(asked.Overwrite);
Assert.Equal(3, asked.Length);
}
}
finally
{
Agent.Answer = before;
}
var audit = await AuditAsync(device);
Assert.Equal("uploaded-replacing", Assert.Single(audit).Action);
Assert.Contains("sha256=abc", audit[0].Detail);
}
[Fact]
public async Task ADownloadIsAFormThatCarriesItsCsrfTokenAsAField()
{
var device = await fixture.SeedDeviceAsync("FILES-DOWNLOAD", online: true);
using var admin = await fixture.SignedInAsync("files-admin");
var ct = TestContext.Current.CancellationToken;
var csrf = admin.DefaultRequestHeaders.GetValues(SessionCookies.CsrfHeader).Single();
admin.DefaultRequestHeaders.Remove(SessionCookies.CsrfHeader);
// No token: refused, whichever route.
var refused = await admin.PostAsync(Route(device, "download"), new FormUrlEncodedContent([new("path", "C:\\a.bin")]), ct);
Assert.Equal(HttpStatusCode.Forbidden, refused.StatusCode);
// A token as a field works here and nowhere else.
var elsewhere = await admin.PostAsync(Route(device, "folder"), new FormUrlEncodedContent([new("csrf", csrf), new("path", "C:\\a")]), ct);
Assert.Equal(HttpStatusCode.Forbidden, elsewhere.StatusCode);
var before = Agent.Answer;
Agent.Content = [1, 2, 3, 4];
Agent.Answer = _ => new DeviceFileReply(
DeviceFileStatuses.Ok,
Length: 4,
Entry: new DeviceFileEntry("a b.bin", "C:\\a b.bin", false, 4, null, null, false, false, null));
try
{
var response = await admin.PostAsync(Route(device, "download"), new FormUrlEncodedContent([new("csrf", csrf), new("path", "C:\\a b.bin")]), ct);
Assert.Equal(HttpStatusCode.OK, response.StatusCode);
Assert.Equal("a b.bin", response.Content.Headers.ContentDisposition!.FileName!.Trim('"'));
Assert.Equal(4, response.Content.Headers.ContentLength);
Assert.Equal(new byte[] { 1, 2, 3, 4 }, await response.Content.ReadAsByteArrayAsync(ct));
}
finally
{
Agent.Answer = before;
}
Assert.Equal("downloaded", (await AuditAsync(device)).Single().Action);
}
[Fact]
public async Task SeveralEntriesDownloadAsAZipNamedForTheDevice()
{
var device = await fixture.SeedDeviceAsync("FILES-ZIP", online: true);
using var admin = await fixture.SignedInAsync("files-admin");
Agent.Content = [9];
var response = await admin.PostAsync(
Route(device, "download"),
new FormUrlEncodedContent([new("path", "C:\\one"), new("path", "C:\\two")]),
TestContext.Current.CancellationToken);
Assert.Equal(HttpStatusCode.OK, response.StatusCode);
Assert.Matches(@"^FILES-ZIP\.Files\.\d{4}\.\d{2}\.\d{2}\.\d{6}\.zip$", response.Content.Headers.ContentDisposition!.FileName!.Trim('"'));
}
[Theory]
[InlineData(@"C:\Logs\", "Logs")]
[InlineData(@"C:\", "C")]
[InlineData("/var/log", "log")]
public void AZipIsNamedForTheOneFolderItHolds(string path, string expected)
=> Assert.StartsWith($"HOST.{expected}.", DeviceFileEndpoints.ZipName("HOST", [path]));
[Fact]
public async Task TextComesBackDecoded_AndAConflictSaysWhatIsThereNow()
{
var device = await fixture.SeedDeviceAsync("FILES-TEXT", online: true);
using var admin = await fixture.SignedInAsync("files-admin");
var ct = TestContext.Current.CancellationToken;
var version = new DeviceFileVersion(3, "aaa", DateTimeOffset.UtcNow);
var before = Agent.Answer;
Agent.Content = "héllo"u8.ToArray();
Agent.Answer = request => request.Operation == DeviceFileOperations.ReadText
? new DeviceFileReply(DeviceFileStatuses.Ok, Path: "C:\\a.conf", Encoding: DeviceTextEncodings.Utf16Le, LineEndings: DeviceTextLineEndings.Crlf, Version: version)
: new DeviceFileReply(DeviceFileStatuses.Conflict, "Changed.", Version: version);
try
{
var opened = await admin.GetFromJsonAsync<DeviceFileTextDto>($"{Route(device, "text")}?path=C%3A%5Ca.conf", JsonDefaults.Options, ct);
Assert.Equal("héllo", opened!.Text);
Assert.Equal(DeviceTextEncodings.Utf16Le, opened.Encoding);
var saved = await admin.PutAsync(
Route(device, "text"),
Json(new DeviceFileSaveTextRequest("C:\\a.conf", "x", DeviceTextEncodings.Utf8, DeviceTextLineEndings.Lf, "old")),
ct);
Assert.Equal(HttpStatusCode.Conflict, saved.StatusCode);
var problem = await saved.Content.ReadFromJsonAsync<DeviceFileProblem>(JsonDefaults.Options, ct);
Assert.Equal("aaa", problem!.Version!.Sha256);
lock (Agent.Requests)
{
Assert.Equal("old", Agent.Requests.Last(r => r.Operation == DeviceFileOperations.WriteText).ExpectedSha256);
}
}
finally
{
Agent.Answer = before;
}
// Opening is on the trail, and the text never is; a refused save isn't.
var audit = await AuditAsync(device);
Assert.Equal("text-opened", Assert.Single(audit).Action);
Assert.DoesNotContain("héllo", audit[0].Detail);
}
[Theory]
[InlineData(DeviceFileStatuses.NotText, HttpStatusCode.UnprocessableEntity)]
[InlineData(DeviceFileStatuses.TooLarge, HttpStatusCode.RequestEntityTooLarge)]
public async Task WhatCantOpenAsTextIsSaidSo(string status, HttpStatusCode expected)
{
var device = await fixture.SeedDeviceAsync($"FILES-{status}-T", online: true);
using var admin = await fixture.SignedInAsync("files-admin");
var before = Agent.Answer;
Agent.Answer = _ => new DeviceFileReply(status);
try
{
var response = await admin.GetAsync($"{Route(device, "text")}?path=x", TestContext.Current.CancellationToken);
Assert.Equal(expected, response.StatusCode);
Assert.Contains(status, await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken));
}
finally
{
Agent.Answer = before;
}
}
[Fact]
public async Task ExistingSystemRolesPickUpNewPermissions()
{
await fixture.WithDbAsync(async db =>
{
var role = await db.Roles.SingleAsync(r => r.IsSystem && r.Name == "Operator");
role.PermissionsJson = JsonDefaults.Serialize(new[] { Permissions.DevicesView });
await db.SaveChangesAsync();
await new RoleService(db, fixture.Services.GetRequiredService<RoleCache>())
.EnsureSystemRolesAsync(TestContext.Current.CancellationToken);
var updated = await db.Roles.AsNoTracking().SingleAsync(r => r.Id == role.Id);
Assert.Contains(Permissions.FilesManage, updated.PermissionsJson);
});
}
}