Feat/w3ds file uri

.env.example

@@ -142,6 +142,16 @@ AWARENESS_INGEST_SECRET="replace-with-a-strong-secret"
 AWARENESS_SERVICE_URL="http://localhost:4100"
 # Comma-separated eNames allowed to act as AaaS portal admins
 AAAS_ADMIN_ENAMES=""
+
+# DigitalOcean Spaces object storage (S3-compatible) — used by eVault core to
+# store file blobs and expose public URIs for the w3ds://file URI scheme.
+DO_SPACES_ENDPOINT="https://nyc3.digitaloceanspaces.com"
+DO_SPACES_REGION="nyc3"
+DO_SPACES_KEY="your-spaces-access-key"
+DO_SPACES_SECRET="your-spaces-secret-key"
+DO_SPACES_BUCKET="your-spaces-bucket"
+# Optional public/CDN base URL; defaults to the bucket sub-domain on the endpoint
+DO_SPACES_CDN_URL=""
 # Secret used to sign AaaS portal session JWTs
 AAAS_JWT_SECRET="replace-with-a-strong-secret"
 # Webhook delivery tuning

infrastructure/evault-core/package.json

@@ -16,6 +16,7 @@
         "migration:revert": "npm run typeorm migration:revert -- -d dist/config/database.js"
     },
     "dependencies": {
+        "@aws-sdk/client-s3": "^3.700.0",
         "@fastify/cors": "^8.5.0",
         "@fastify/formbody": "^8.0.2",
         "@fastify/swagger": "^8.14.0",

infrastructure/evault-core/src/core/http/server.ts

@@ -17,6 +17,7 @@ import {
     recordAttempt,
 } from "./passphrase-rate-limiter";
 import { type TypedReply, type TypedRequest, WatcherRequest } from "./types";
+import { FILE_SCHEMA_ID } from "../utils/w3ds-uri";
 
 interface WatcherSignatureRequest {
     w3id: string;
@@ -54,6 +55,10 @@ export async function registerHttpRoutes(
                     name: "provisioning",
                     description: "eVault provisioning endpoints",
                 },
+                {
+                    name: "files",
+                    description: "File dereferencing endpoints",
+                },
             ],
         },
     });
@@ -355,6 +360,117 @@ export async function registerHttpRoutes(
         },
     );
 
+    // Dereference a w3ds://file URI — resolves the File meta-envelope and
+    // redirects to the public object-storage URL of the underlying file.
+    server.get<{ Params: { metaEnvelopeId: string } }>(
+        "/files/:metaEnvelopeId",
+        {
+            schema: {
+                tags: ["files"],
+                description:
+                    "Dereference a file by its meta-envelope ID and redirect to its public URL",
+                headers: {
+                    type: "object",
+                    required: ["X-ENAME"],
+                    properties: {
+                        "X-ENAME": { type: "string" },
+                    },
+                },
+                params: {
+                    type: "object",
+                    required: ["metaEnvelopeId"],
+                    properties: {
+                        metaEnvelopeId: { type: "string" },
+                    },
+                },
+                response: {
+                    302: { type: "null" },
+                    400: {
+                        type: "object",
+                        properties: { error: { type: "string" } },
+                    },
+                    404: {
+                        type: "object",
+                        properties: { error: { type: "string" } },
+                    },
+                },
+            },
+        },
+        async (request, reply) => {
+            const eName =
+                request.headers["x-ename"] || request.headers["X-ENAME"];
+
+            if (!eName || typeof eName !== "string") {
+                return reply
+                    .status(400)
+                    .send({ error: "X-ENAME header is required" });
+            }
+
+            const { metaEnvelopeId } = request.params;
+            if (!metaEnvelopeId || typeof metaEnvelopeId !== "string") {
+                return reply
+                    .status(400)
+                    .send({ error: "A valid meta-envelope ID is required" });
+            }
+
+            if (!dbService) {
+                return reply
+                    .status(500)
+                    .send({ error: "Database service not available" });
+            }
+
+            try {
+                const metaEnvelope = await dbService.findMetaEnvelopeById(
+                    metaEnvelopeId,
+                    eName,
+                );
+
+                if (!metaEnvelope || metaEnvelope.ontology !== FILE_SCHEMA_ID) {
+                    return reply.status(404).send({
+                        error: `No file found for w3ds://file?id=${eName}/${metaEnvelopeId}`,
+                    });
+                }
+
+                const publicUrl = (metaEnvelope.parsed as Record<string, any>)
+                    ?.publicUrl;
+                if (!publicUrl || typeof publicUrl !== "string") {
+                    return reply.status(404).send({
+                        error: "File meta-envelope has no public URL",
+                    });
+                }
+
+                // Only ever redirect to http(s) — guard against a stored URL
+                // with an unsafe scheme (javascript:, data:, file:, …).
+                let parsedUrl: URL;
+                try {
+                    parsedUrl = new URL(publicUrl);
+                } catch {
+                    return reply
+                        .status(404)
+                        .send({ error: "File meta-envelope has an invalid public URL" });
+                }
+                if (
+                    parsedUrl.protocol !== "http:" &&
+                    parsedUrl.protocol !== "https:"
+                ) {
+                    return reply.status(400).send({
+                        error: "File public URL uses an unsupported scheme",
+                    });
+                }
+
+                return reply.redirect(publicUrl);
+            } catch (error) {
+                console.error("Error dereferencing file:", error);
+                return reply.status(500).send({
+                    error:
+                        error instanceof Error
+                            ? error.message
+                            : "Failed to dereference file",
+                });
+            }
+        },
+    );
+
     // Temporary token-gated cross-eVault read by ontology. Intentionally undocumented in Swagger.
     server.get<{ Params: { ontology: string } }>(
         "/metaenvelopes/by-ontology/:ontology",

infrastructure/evault-core/src/core/protocol/graphql-server.ts

@@ -10,6 +10,8 @@ import {
     computeEnvelopeHashForDelete,
 } from "../db/envelope-hash";
 import { exampleQueries } from "./examples/examples";
+import { StorageService } from "../../services/StorageService";
+import { buildFileUri, FILE_SCHEMA_ID } from "../utils/w3ds-uri";
 import { typeDefs } from "./typedefs";
 import { VaultAccessGuard, type VaultContext } from "./vault-access-guard";
 import { MessageNotificationService } from "../../services/MessageNotificationService";
@@ -1145,6 +1147,162 @@ export class GraphQLServer {
                         };
                     },
                 ),
+                // Upload a file to object storage and create a File meta-envelope
+                uploadFile: this.accessGuard.middleware(
+                    async (
+                        _: any,
+                        {
+                            input,
+                        }: {
+                            input: {
+                                filename: string;
+                                contentType: string;
+                                content: string;
+                                acl: string[];
+                            };
+                        },
+                        context: VaultContext,
+                    ) => {
+                        if (!context.eName) {
+                            return {
+                                errors: [
+                                    {
+                                        message: "X-ENAME header is required",
+                                        code: "MISSING_ENAME",
+                                    },
+                                ],
+                            };
+                        }
+
+                        if (!StorageService.isConfigured()) {
+                            return {
+                                errors: [
+                                    {
+                                        message:
+                                            "Object storage is not configured on this eVault",
+                                        code: "STORAGE_NOT_CONFIGURED",
+                                    },
+                                ],
+                            };
+                        }
+
+                        // Accept either raw base64 or a data: URI
+                        const base64 = input.content.includes(",")
+                            ? input.content.slice(
+                                  input.content.indexOf(",") + 1,
+                              )
+                            : input.content;
+
+                        // Strictly validate base64 before decoding — Buffer.from
+                        // silently drops invalid characters, so malformed input
+                        // must be rejected up-front. Padding ('=') is allowed
+                        // only as the last 1-2 characters.
+                        const isValidBase64 =
+                            base64.length > 0 &&
+                            base64.length % 4 === 0 &&
+                            /^[A-Za-z0-9+/]+={0,2}$/.test(base64);
+                        if (!isValidBase64) {
+                            return {
+                                errors: [
+                                    {
+                                        field: "content",
+                                        message: "File content is empty or not valid base64",
+                                        code: "INVALID_CONTENT",
+                                    },
+                                ],
+                            };
+                        }
+
+                        const buffer = Buffer.from(base64, "base64");
+
+                        const MAX_FILE_BYTES = 50 * 1024 * 1024; // 50 MB
+                        if (buffer.length > MAX_FILE_BYTES) {
+                            return {
+                                errors: [
+                                    {
+                                        field: "content",
+                                        message: "File exceeds the 50 MB upload limit",
+                                        code: "FILE_TOO_LARGE",
+                                    },
+                                ],
+                            };
+                        }
+
+                        // Track the uploaded object so a failed DB write can be
+                        // compensated by deleting the now-orphaned blob.
+                        let uploadedKey: string | null = null;
+                        let storage: StorageService | null = null;
+                        try {
+                            const objectId = require("uuid").v4();
+                            const key = StorageService.buildKey(
+                                context.eName,
+                                input.filename,
+                                objectId,
+                            );
+                            storage = new StorageService();
+                            const publicUrl = await storage.uploadObject({
+                                buffer,
+                                contentType: input.contentType,
+                                key,
+                            });
+                            uploadedKey = key;
+
+                            const payload = {
+                                filename: input.filename,
+                                contentType: input.contentType,
+                                size: buffer.length,
+                                blobKey: key,
+                                publicUrl,
+                                uploadedAt: new Date().toISOString(),
+                            };
+
+                            const result = await this.db.storeMetaEnvelope(
+                                {
+                                    ontology: FILE_SCHEMA_ID,
+                                    payload,
+                                    acl: input.acl,
+                                },
+                                input.acl,
+                                context.eName,
+                            );
+
+                            return {
+                                uri: buildFileUri(
+                                    context.eName,
+                                    result.metaEnvelope.id,
+                                ),
+                                metaEnvelopeId: result.metaEnvelope.id,
+                                publicUrl,
+                            };
+                        } catch (error) {
+                            console.error("uploadFile failed:", error);
+                            // Compensating cleanup: if the blob was uploaded but
+                            // a later step (DB write) failed, delete the now
+                            // orphaned object so storage does not leak.
+                            if (uploadedKey && storage) {
+                                try {
+                                    await storage.deleteObject(uploadedKey);
+                                } catch (cleanupError) {
+                                    console.error(
+                                        "uploadFile cleanup (delete orphaned object) failed:",
+                                        cleanupError,
+                                    );
+                                }
+                            }
+                            return {
+                                errors: [
+                                    {
+                                        message:
+                                            error instanceof Error
+                                                ? error.message
+                                                : "Failed to upload file",
+                                        code: "UPLOAD_FAILED",
+                                    },
+                                ],
+                            };
+                        }
+                    },
+                ),
                 updateMetaEnvelopeById: this.accessGuard.middleware(
                     async (
                         _: any,

infrastructure/evault-core/src/core/protocol/typedefs.ts

@@ -137,6 +137,33 @@ export const typeDefs = /* GraphQL */ `
         errors: [UserError!]
     }
 
+    # ============================================================================
+    # File Upload Types
+    # ============================================================================
+
+    "Input for uploading a file to eVault object storage"
+    input UploadFileInput {
+        "Original file name"
+        filename: String!
+        "MIME type of the file"
+        contentType: String!
+        "Base64-encoded file content (raw base64 or a data: URI)"
+        content: String!
+        "Access control list for the created File meta-envelope"
+        acl: [String!]!
+    }
+
+    type UploadFilePayload {
+        "The w3ds://file URI addressing the uploaded file, null if errors occurred"
+        uri: String
+        "The ID of the File meta-envelope describing the upload"
+        metaEnvelopeId: String
+        "The public object-storage URL of the file"
+        publicUrl: String
+        "List of errors that occurred during the upload"
+        errors: [UserError!]
+    }
+
     # ============================================================================
     # Binding Document Types
     # ============================================================================
@@ -291,6 +318,9 @@ export const typeDefs = /* GraphQL */ `
             skipWebhooks: Boolean = false
         ): BulkCreateMetaEnvelopesPayload!
 
+        "Upload a file to object storage and create an addressable File meta-envelope"
+        uploadFile(input: UploadFileInput!): UploadFilePayload!
+
         # --- Binding Document Mutations ---
         "Create a new binding document"
         createBindingDocument(input: CreateBindingDocumentInput!): CreateBindingDocumentPayload!