@beyondwork/docx-react-component 1.0.0

package/services/openxml-validator/Program.cs

@@ -0,0 +1,436 @@
+using System.IO.Compression;
+using System.Security.Cryptography;
+using System.Text;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Validation;
+
+const string ServiceName = "openxml-validator";
+const string SdkVersion = "DocumentFormat.OpenXml 3.5.1";
+const string PrivateModeEnvironmentVariable = "VALIDATOR_PRIVATE_MODE";
+const string AuthTokenEnvironmentVariable = "VALIDATOR_AUTH_TOKEN";
+const long MaxRequestBytes = 20L * 1024L * 1024L;
+const string DocxContentType = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.ConfigureHttpJsonOptions(options =>
+{
+    options.SerializerOptions.WriteIndented = true;
+});
+
+var app = builder.Build();
+var privateModeEnabled = string.Equals(
+    Environment.GetEnvironmentVariable(PrivateModeEnvironmentVariable),
+    "enabled",
+    StringComparison.OrdinalIgnoreCase
+);
+var authToken = Environment.GetEnvironmentVariable(AuthTokenEnvironmentVariable)?.Trim();
+var endpointCatalog = new[]
+{
+    new ServiceEndpointDescriptor("GET", "/deploy-health"),
+    new ServiceEndpointDescriptor("GET", "/health"),
+    new ServiceEndpointDescriptor("POST", "/validate")
+};
+
+app.MapGet("/deploy-health", () =>
+{
+    return Results.Json(CreateDeployHealthResponse(privateModeEnabled, !string.IsNullOrWhiteSpace(authToken)));
+});
+
+app.MapGet("/health", (HttpRequest request) =>
+{
+    var health = CreateHealthResponse(
+        privateModeEnabled,
+        !string.IsNullOrWhiteSpace(authToken),
+        endpointCatalog
+    );
+    var statusCode = privateModeEnabled
+        ? StatusCodes.Status200OK
+        : StatusCodes.Status503ServiceUnavailable;
+
+    if (!privateModeEnabled)
+    {
+        return Results.Json(health, statusCode: statusCode);
+    }
+
+    if (!IsRequestAuthorized(authToken, request))
+    {
+        return CreateErrorResult(
+            StatusCodes.Status401Unauthorized,
+            "unauthorized",
+            $"Validator requests must include a valid bearer token when {AuthTokenEnvironmentVariable} is configured."
+        );
+    }
+
+    return Results.Json(health, statusCode: statusCode);
+});
+
+app.MapPost("/validate", async (HttpRequest request, CancellationToken cancellationToken) =>
+{
+    if (!privateModeEnabled)
+    {
+        return CreateErrorResult(
+            StatusCodes.Status503ServiceUnavailable,
+            "service-unavailable",
+            "Validation is disabled until VALIDATOR_PRIVATE_MODE=enabled is set."
+        );
+    }
+
+    if (!IsRequestAuthorized(authToken, request))
+    {
+        return CreateErrorResult(
+            StatusCodes.Status401Unauthorized,
+            "unauthorized",
+            $"Validator requests must include a valid bearer token when {AuthTokenEnvironmentVariable} is configured."
+        );
+    }
+
+    if (request.ContentLength is long contentLength && contentLength > MaxRequestBytes)
+    {
+        return CreateErrorResult(
+            StatusCodes.Status413PayloadTooLarge,
+            "payload-too-large",
+            $"Request body exceeds the {MaxRequestBytes} byte limit."
+        );
+    }
+
+    if (!request.HasFormContentType)
+    {
+        return CreateErrorResult(
+            StatusCodes.Status400BadRequest,
+            "invalid-request",
+            "Expected multipart form data with a file field named 'file'."
+        );
+    }
+
+    var form = await request.ReadFormAsync(cancellationToken);
+    var file = form.Files["file"] ?? form.Files.FirstOrDefault();
+
+    if (file is null || file.Length == 0)
+    {
+        return CreateErrorResult(
+            StatusCodes.Status400BadRequest,
+            "missing-file",
+            "A non-empty .docx file is required."
+        );
+    }
+
+    if (file.Length > MaxRequestBytes)
+    {
+        return CreateErrorResult(
+            StatusCodes.Status413PayloadTooLarge,
+            "payload-too-large",
+            $"Uploaded file exceeds the {MaxRequestBytes} byte limit."
+        );
+    }
+
+    if (!string.Equals(Path.GetExtension(file.FileName), ".docx", StringComparison.OrdinalIgnoreCase))
+    {
+        return CreateErrorResult(
+            StatusCodes.Status400BadRequest,
+            "invalid-file-type",
+            "Only .docx payloads are supported."
+        );
+    }
+
+    await using var input = file.OpenReadStream();
+    await using var buffer = new MemoryStream();
+    await input.CopyToAsync(buffer, cancellationToken);
+
+    var bytes = buffer.ToArray();
+    var packageResult = InspectPackage(bytes);
+    var sdkResult = ValidateWithSdk(bytes);
+    var isValid = packageResult.Findings.Count == 0 && sdkResult.Findings.Count == 0;
+
+    return Results.Ok(new ValidateDocumentResponse(
+        Service: ServiceName,
+        ValidatedAtUtc: DateTimeOffset.UtcNow,
+        Document: new ValidatedDocument(
+            FileName: Path.GetFileName(file.FileName),
+            FileSizeBytes: file.Length,
+            ContentType: file.ContentType
+        ),
+        Summary: new ValidationSummary(
+            IsValid: isValid,
+            PackageFindingCount: packageResult.Findings.Count,
+            SdkFindingCount: sdkResult.Findings.Count
+        ),
+        Package: packageResult,
+        Sdk: sdkResult
+    ));
+});
+
+app.Run();
+
+static DeployHealthResponse CreateDeployHealthResponse(bool privateModeEnabled, bool authTokenConfigured)
+{
+    return new DeployHealthResponse(
+        Service: ServiceName,
+        Status: "ok",
+        ValidatorAccess: privateModeEnabled ? "enabled" : "disabled",
+        Auth: new AuthStatus(
+            Required: authTokenConfigured,
+            EnvironmentVariable: AuthTokenEnvironmentVariable,
+            Scheme: "Bearer"
+        )
+    );
+}
+
+static HealthResponse CreateHealthResponse(
+    bool privateModeEnabled,
+    bool authTokenConfigured,
+    IReadOnlyList<ServiceEndpointDescriptor> endpoints
+)
+{
+    return new HealthResponse(
+        Service: ServiceName,
+        Status: privateModeEnabled ? "ok" : "degraded",
+        Sdk: SdkVersion,
+        PrivateMode: new PrivateModeStatus(
+            Enabled: privateModeEnabled,
+            EnvironmentVariable: PrivateModeEnvironmentVariable,
+            RequiredValue: "enabled"
+        ),
+        Auth: new AuthStatus(
+            Required: authTokenConfigured,
+            EnvironmentVariable: AuthTokenEnvironmentVariable,
+            Scheme: "Bearer"
+        ),
+        Limits: new ValidationLimits(
+            MaxRequestBytes: MaxRequestBytes,
+            AcceptedExtension: ".docx",
+            AcceptedContentType: DocxContentType
+        ),
+        Endpoints: endpoints
+    );
+}
+
+static bool IsRequestAuthorized(string? configuredToken, HttpRequest request)
+{
+    if (string.IsNullOrWhiteSpace(configuredToken))
+    {
+        return true;
+    }
+
+    if (!request.Headers.TryGetValue("Authorization", out var authorizationHeader))
+    {
+        return false;
+    }
+
+    var rawHeader = authorizationHeader.ToString();
+    const string bearerPrefix = "Bearer ";
+    if (!rawHeader.StartsWith(bearerPrefix, StringComparison.OrdinalIgnoreCase))
+    {
+        return false;
+    }
+
+    var providedToken = rawHeader[bearerPrefix.Length..].Trim();
+    return AreTokensEqual(configuredToken, providedToken);
+}
+
+static bool AreTokensEqual(string expectedToken, string providedToken)
+{
+    var expectedBytes = Encoding.UTF8.GetBytes(expectedToken);
+    var providedBytes = Encoding.UTF8.GetBytes(providedToken);
+    return CryptographicOperations.FixedTimeEquals(expectedBytes, providedBytes);
+}
+
+static IResult CreateErrorResult(int statusCode, string error, string detail)
+{
+    return Results.Json(
+        new ValidationErrorResponse(
+            Service: ServiceName,
+            Error: error,
+            Detail: detail,
+            Status: statusCode,
+            Limits: new ValidationLimits(
+                MaxRequestBytes: MaxRequestBytes,
+                AcceptedExtension: ".docx",
+                AcceptedContentType: DocxContentType
+            )
+        ),
+        statusCode: statusCode
+    );
+}
+
+static PackageValidationResult InspectPackage(byte[] bytes)
+{
+    var findings = new List<PackageValidationFinding>();
+    var requiredEntries = new[]
+    {
+        "[Content_Types].xml",
+        "_rels/.rels",
+        "word/document.xml"
+    };
+
+    try
+    {
+        using var stream = new MemoryStream(bytes);
+        using var archive = new ZipArchive(stream, ZipArchiveMode.Read, leaveOpen: false);
+
+        var names = archive.Entries.Select(entry => entry.FullName).ToHashSet(StringComparer.Ordinal);
+
+        foreach (var entry in requiredEntries)
+        {
+            if (!names.Contains(entry))
+            {
+                findings.Add(new PackageValidationFinding(
+                    Code: "missing-required-entry",
+                    Message: $"Missing required package entry: {entry}",
+                    Entry: entry
+                ));
+            }
+        }
+
+        return new PackageValidationResult(
+            EntryCount: archive.Entries.Count,
+            RequiredEntries: requiredEntries,
+            Findings: findings
+        );
+    }
+    catch (Exception ex)
+    {
+        findings.Add(new PackageValidationFinding(
+            Code: "package-open-failed",
+            Message: $"ZIP/package inspection failed: {ex.Message}",
+            Entry: null
+        ));
+
+        return new PackageValidationResult(
+            EntryCount: null,
+            RequiredEntries: requiredEntries,
+            Findings: findings
+        );
+    }
+}
+
+static SdkValidationResult ValidateWithSdk(byte[] bytes)
+{
+    var findings = new List<SdkValidationFinding>();
+
+    try
+    {
+        using var stream = new MemoryStream(bytes);
+        using var document = WordprocessingDocument.Open(stream, false);
+        var validator = new OpenXmlValidator();
+
+        foreach (var error in validator.Validate(document))
+        {
+            findings.Add(new SdkValidationFinding(
+                Code: "schema-validation-error",
+                Message: error.Description,
+                PartUri: error.Part?.Uri?.ToString(),
+                Path: error.Path?.XPath
+            ));
+        }
+
+        return new SdkValidationResult(
+            Findings: findings
+        );
+    }
+    catch (Exception ex)
+    {
+        findings.Add(new SdkValidationFinding(
+            Code: "sdk-open-failed",
+            Message: $"Open XML SDK validation failed: {ex.Message}",
+            PartUri: null,
+            Path: null
+        ));
+
+        return new SdkValidationResult(
+            Findings: findings
+        );
+    }
+}
+
+internal sealed record ValidationErrorResponse(
+    string Service,
+    string Error,
+    string Detail,
+    int Status,
+    ValidationLimits Limits
+);
+
+internal sealed record ValidateDocumentResponse(
+    string Service,
+    DateTimeOffset ValidatedAtUtc,
+    ValidatedDocument Document,
+    ValidationSummary Summary,
+    PackageValidationResult Package,
+    SdkValidationResult Sdk
+);
+
+internal sealed record ValidatedDocument(
+    string FileName,
+    long FileSizeBytes,
+    string ContentType
+);
+
+internal sealed record DeployHealthResponse(
+    string Service,
+    string Status,
+    string ValidatorAccess,
+    AuthStatus Auth
+);
+
+internal sealed record HealthResponse(
+    string Service,
+    string Status,
+    string Sdk,
+    PrivateModeStatus PrivateMode,
+    AuthStatus Auth,
+    ValidationLimits Limits,
+    IReadOnlyList<ServiceEndpointDescriptor> Endpoints
+);
+
+internal sealed record PrivateModeStatus(
+    bool Enabled,
+    string EnvironmentVariable,
+    string RequiredValue
+);
+
+internal sealed record AuthStatus(
+    bool Required,
+    string EnvironmentVariable,
+    string Scheme
+);
+
+internal sealed record ValidationLimits(
+    long MaxRequestBytes,
+    string AcceptedExtension,
+    string AcceptedContentType
+);
+
+internal sealed record ServiceEndpointDescriptor(
+    string Method,
+    string Path
+);
+
+internal sealed record ValidationSummary(
+    bool IsValid,
+    int PackageFindingCount,
+    int SdkFindingCount
+);
+
+internal sealed record PackageValidationResult(
+    int? EntryCount,
+    IReadOnlyList<string> RequiredEntries,
+    IReadOnlyList<PackageValidationFinding> Findings
+);
+
+internal sealed record PackageValidationFinding(
+    string Code,
+    string Message,
+    string? Entry
+);
+
+internal sealed record SdkValidationResult(
+    IReadOnlyList<SdkValidationFinding> Findings
+);
+
+internal sealed record SdkValidationFinding(
+    string Code,
+    string Message,
+    string? PartUri,
+    string? Path
+);

package/services/openxml-validator/README.md

@@ -0,0 +1,152 @@
+# Open XML Validator Service
+
+This service is the internal validator used by CI and the Railway harness.
+
+## Purpose
+
+The service should accept exported `.docx` artifacts and return structured diagnostics from:
+
+- package integrity checks
+- required-part checks
+- Microsoft Open XML SDK validation
+
+It is not part of the shipped browser component.
+It remains validation-only and must not repair, mutate, or normalize uploaded packages.
+
+## Endpoints
+
+- `GET /deploy-health`
+- `GET /health`
+- `POST /validate`
+
+`POST /validate` expects multipart form data with a `file` field containing a `.docx` payload.
+
+## Response Contract
+
+`GET /deploy-health` returns a minimal deploy-readiness payload for Railway:
+
+- `service`
+- `status`
+- `validatorAccess`
+- `auth.required`
+- `auth.environmentVariable`
+- `auth.scheme`
+
+`GET /health` returns a readiness payload with:
+
+- `service`
+- `status`
+- `sdk`
+- `privateMode.enabled`
+- `privateMode.environmentVariable`
+- `privateMode.requiredValue`
+- `auth.required`
+- `auth.environmentVariable`
+- `auth.scheme`
+- `limits.maxRequestBytes`
+- `limits.acceptedExtension`
+- `limits.acceptedContentType`
+- `endpoints[]`
+
+When `VALIDATOR_PRIVATE_MODE` is not set to `enabled`, the endpoint returns `503` with the same
+structured payload and `status: degraded`. This makes readiness failures explicit without exposing
+any repair or transformation surface.
+
+When `VALIDATOR_AUTH_TOKEN` is set, both `GET /health` and `POST /validate` require
+`Authorization: Bearer <token>`. This is the supported fallback when Railway private networking is
+unavailable and the harness must call the validator over a public domain.
+
+`POST /validate` returns:
+
+- `service`
+- `validatedAtUtc`
+- `document`
+- `summary`
+- `package`
+- `sdk`
+
+The `package.findings` and `sdk.findings` collections are distinct machine-readable arrays. Callers should use `summary.isValid`, `summary.packageFindingCount`, and `summary.sdkFindingCount` for gating, then inspect the per-surface findings for details.
+
+Bad requests return:
+
+- `service`
+- `error`
+- `detail`
+- `status`
+- `limits`
+
+The service uses structured JSON for both `400` and `413` validation failures, and for the
+private-mode `503` response on `POST /validate`.
+
+Authentication failures return `401` with the same structured error envelope.
+
+## Implementation Notes
+
+- target runtime: `.NET 8`
+- Open XML SDK package: `DocumentFormat.OpenXml` `3.5.1`
+- deploy target: Railway private service
+- intended caller: `services/react-word-editor`
+- private-mode gate: `VALIDATOR_PRIVATE_MODE=enabled`
+- optional public-domain auth gate: `VALIDATOR_AUTH_TOKEN`
+- request cap: `20 MiB`
+- accepted upload type: `.docx` multipart file payloads only
+
+## Local Note
+
+The service now builds and runs locally in this repo with `.NET 8`. Use:
+
+```bash
+dotnet build services/openxml-validator/OpenXmlValidator.Api.csproj
+dotnet run --project services/openxml-validator/OpenXmlValidator.Api.csproj --urls http://127.0.0.1:5080
+```
+
+Smoke check:
+
+```bash
+curl -s http://127.0.0.1:5080/deploy-health
+curl -s http://127.0.0.1:5080/health
+curl -s -F "file=@/absolute/path/to/document.docx" http://127.0.0.1:5080/validate
+```
+
+Public-domain smoke check with bearer auth:
+
+```bash
+curl -s -H "Authorization: Bearer $VALIDATOR_AUTH_TOKEN" https://<validator-domain>/health
+curl -s -H "Authorization: Bearer $VALIDATOR_AUTH_TOKEN" \
+  -F "file=@/absolute/path/to/document.docx" \
+  https://<validator-domain>/validate
+```
+
+## Wave 0 Landed Scaffold
+
+The repo now contains:
+
+- a .NET 8 web service project
+- `GET /health` for readiness checks
+- `POST /validate` multipart intake for `.docx` payloads
+- distinct package and SDK finding collections in the validation response
+- package integrity checks for required DOCX entries
+- Open XML SDK validation wiring
+- Docker packaging for service deployment
+
+Wave 3 raises the service to a `baseline-proved` internal contract with local smoke artifacts under `.tmp/wave-3-validator/`. It is not yet a proof of Railway deployment or CI wiring.
+
+Wave 8 private-service pilot proof is currently blocked pending a fresh private-mode Railway redeploy. Do not treat the older public early-access ingress as the current validator closure line.
+
+The validator remains an internal proof surface for later compatibility waves. It is not the editor's primary transformation engine and must stay outside the shipped React runtime.
+
+## Fleet-Ready Gaps
+
+Wave 10 hardens the service contract enough for QA and integration proof, but it is not yet a
+fleet-ready general validation plane.
+
+Current assumptions and blockers:
+
+- private-mode admission is a single environment-variable guard; there is no service-to-service
+  auth or identity layer yet
+- diagnostics are request-scoped JSON only; there is no durable validator-side audit store,
+  retention policy, or operator dashboard
+- the validator stays intentionally validation-only and does not attempt repair, normalization, or
+  canonical import/export work
+- Railway proof still depends on a fresh private deploy capture rather than a persistent
+  environment-managed health SLO bundle

package/services/openxml-validator/railway.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "DOCKERFILE",
+    "dockerfilePath": "/services/openxml-validator/Dockerfile",
+    "watchPatterns": [
+      "/services/openxml-validator/**"
+    ]
+  },
+  "deploy": {
+    "healthcheckPath": "/deploy-health",
+    "healthcheckTimeout": 60,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 10
+  }
+}