arcway 0.4.5 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",
@@ -46,6 +46,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.987.0",
+    "@aws-sdk/s3-request-presigner": "3.990.0",
     "@babel/core": "^7.29.0",
     "@base-ui/react": "^1.2.0",
     "@modelcontextprotocol/sdk": "^1.26.0",

package/server/files/drivers/local.js

@@ -65,6 +65,35 @@ class LocalFileDriver {
       return false;
     }
   }
+  async head(namespace, filePath) {
+    const resolved = this.resolvePath(namespace, filePath);
+    try {
+      const stat = await fs.stat(resolved);
+      if (!stat.isFile()) return null;
+      return {
+        bytes: stat.size,
+        contentType: null,
+        checksum: null,
+        etag: null,
+        modifiedAt: stat.mtime,
+      };
+    } catch (err) {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    }
+  }
+  async authorizeUpload() {
+    throw new Error('Direct uploads require the S3 file driver');
+  }
+  async authorizeMultipartUpload() {
+    throw new Error('Direct uploads require the S3 file driver');
+  }
+  async completeMultipartUpload() {
+    throw new Error('Direct uploads require the S3 file driver');
+  }
+  async abortMultipartUpload() {
+    throw new Error('Direct uploads require the S3 file driver');
+  }
   async walkDir(dir) {
     const results = [];
     const entries = await fs.readdir(dir, { withFileTypes: true });

package/server/files/drivers/s3.js

@@ -5,7 +5,12 @@ import {
   DeleteObjectCommand,
   ListObjectsV2Command,
   HeadObjectCommand,
+  CreateMultipartUploadCommand,
+  UploadPartCommand,
+  CompleteMultipartUploadCommand,
+  AbortMultipartUploadCommand,
 } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 class S3FileDriver {
   client;
   bucket;
@@ -15,6 +20,7 @@ class S3FileDriver {
       region: config.region ?? 'us-east-1',
       ...(config.endpoint ? { endpoint: config.endpoint } : {}),
       ...(config.forcePathStyle ? { forcePathStyle: true } : {}),
+      ...(config.credentials ? { credentials: config.credentials } : {}),
     });
   }
   async init() {}
@@ -109,5 +115,119 @@ class S3FileDriver {
       throw err;
     }
   }
+  async head(namespace, filePath) {
+    try {
+      const response = await this.client.send(
+        new HeadObjectCommand({
+          Bucket: this.bucket,
+          Key: this.key(namespace, filePath),
+          ChecksumMode: 'ENABLED',
+        }),
+      );
+      return {
+        bytes: response.ContentLength,
+        contentType: response.ContentType ?? null,
+        checksum: response.ChecksumSHA256 ?? null,
+        etag: response.ETag ?? null,
+        modifiedAt: response.LastModified ?? null,
+      };
+    } catch (err) {
+      if (
+        err.name === 'NotFound' ||
+        err.name === 'NoSuchKey' ||
+        err.$metadata?.httpStatusCode === 404
+      ) {
+        return null;
+      }
+      throw err;
+    }
+  }
+  async authorizeUpload(namespace, filePath, options) {
+    const expiresIn = options.expiresIn ?? 900;
+    const headers = {
+      'Content-Type': options.contentType,
+      'Content-Length': String(options.bytes),
+      ...(options.checksum ? { 'x-amz-checksum-sha256': options.checksum } : {}),
+    };
+    const command = new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: this.key(namespace, filePath),
+      ContentType: options.contentType,
+      ContentLength: options.bytes,
+      ...(options.checksum ? { ChecksumSHA256: options.checksum } : {}),
+    });
+    return {
+      method: 'PUT',
+      url: await getSignedUrl(this.client, command, { expiresIn }),
+      headers,
+      expiresAt: new Date(Date.now() + expiresIn * 1000).toISOString(),
+    };
+  }
+  async authorizeMultipartUpload(namespace, filePath, options) {
+    const key = this.key(namespace, filePath);
+    const expiresIn = options.expiresIn ?? 900;
+    const created = await this.client.send(
+      new CreateMultipartUploadCommand({
+        Bucket: this.bucket,
+        Key: key,
+        ContentType: options.contentType,
+      }),
+    );
+    if (!created.UploadId) throw new Error('Storage provider did not return an upload ID');
+    try {
+      const parts = await Promise.all(
+        options.parts.map(async (part) => ({
+          partNumber: part.partNumber,
+          bytes: part.bytes,
+          method: 'PUT',
+          url: await getSignedUrl(
+            this.client,
+            new UploadPartCommand({
+              Bucket: this.bucket,
+              Key: key,
+              UploadId: created.UploadId,
+              PartNumber: part.partNumber,
+              ContentLength: part.bytes,
+            }),
+            { expiresIn },
+          ),
+          headers: { 'Content-Length': String(part.bytes) },
+        })),
+      );
+      return {
+        uploadId: created.UploadId,
+        parts,
+        expiresAt: new Date(Date.now() + expiresIn * 1000).toISOString(),
+      };
+    } catch (error) {
+      await this.abortMultipartUpload(namespace, filePath, created.UploadId);
+      throw error;
+    }
+  }
+  async completeMultipartUpload(namespace, filePath, uploadId, parts) {
+    await this.client.send(
+      new CompleteMultipartUploadCommand({
+        Bucket: this.bucket,
+        Key: this.key(namespace, filePath),
+        UploadId: uploadId,
+        MultipartUpload: {
+          Parts: parts.map((part) => ({ ETag: part.etag, PartNumber: part.partNumber })),
+        },
+      }),
+    );
+  }
+  async abortMultipartUpload(namespace, filePath, uploadId) {
+    try {
+      await this.client.send(
+        new AbortMultipartUploadCommand({
+          Bucket: this.bucket,
+          Key: this.key(namespace, filePath),
+          UploadId: uploadId,
+        }),
+      );
+    } catch (err) {
+      if (err.name !== 'NoSuchUpload' && err.$metadata?.httpStatusCode !== 404) throw err;
+    }
+  }
 }
 export default S3FileDriver;

package/server/files/index.js

@@ -44,6 +44,49 @@ class Files {
     return this._driver.exists(this._namespace, filePath);
   }
 
+  async head(filePath) {
+    return this._driver.head(this._namespace, filePath);
+  }
+
+  async authorizeUpload(filePath, options) {
+    validateUploadOptions(options);
+    return this._driver.authorizeUpload(this._namespace, filePath, options);
+  }
+
+  async authorizeMultipartUpload(filePath, options) {
+    validateUploadOptions(options);
+    if (options.checksum !== undefined) {
+      throw new Error('Whole-file checksums are not supported for multipart authorization');
+    }
+    if (!Array.isArray(options.parts) || options.parts.length < 2 || options.parts.length > 10000) {
+      throw new Error('Multipart uploads require between 2 and 10000 parts');
+    }
+    options.parts.forEach((part, index) => {
+      if (part.partNumber !== index + 1 || !Number.isSafeInteger(part.bytes) || part.bytes < 1) {
+        throw new Error('Multipart upload parts must be sequential and have a positive byte size');
+      }
+    });
+    if (options.parts.reduce((total, part) => total + part.bytes, 0) !== options.bytes) {
+      throw new Error('Multipart upload part sizes must equal the total upload byte size');
+    }
+    return this._driver.authorizeMultipartUpload(this._namespace, filePath, options);
+  }
+
+  async completeUpload(filePath, expected) {
+    return verifyMetadata(await this.head(filePath), expected);
+  }
+
+  async completeMultipartUpload(filePath, uploadId, parts, expected) {
+    validateMultipartCompletion(uploadId, parts);
+    await this._driver.completeMultipartUpload(this._namespace, filePath, uploadId, parts);
+    return this.completeUpload(filePath, expected);
+  }
+
+  async abortMultipartUpload(filePath, uploadId) {
+    if (typeof uploadId !== 'string' || !uploadId) throw new Error('Upload ID is required');
+    await this._driver.abortMultipartUpload(this._namespace, filePath, uploadId);
+  }
+
   /** Return a namespaced child that shares the same driver. */
   withNamespace(namespace) {
     const child = Object.create(Files.prototype);
@@ -54,4 +97,60 @@ class Files {
   }
 }
 
+function validateUploadOptions(options) {
+  if (!options || typeof options !== 'object') throw new Error('Upload options are required');
+  if (
+    typeof options.contentType !== 'string' ||
+    !options.contentType ||
+    /[\r\n]/.test(options.contentType)
+  ) {
+    throw new Error('A valid upload content type is required');
+  }
+  if (!Number.isSafeInteger(options.bytes) || options.bytes < 1) {
+    throw new Error('Upload byte size must be a positive safe integer');
+  }
+  if (
+    options.expiresIn !== undefined &&
+    (!Number.isSafeInteger(options.expiresIn) ||
+      options.expiresIn < 1 ||
+      options.expiresIn > 604800)
+  ) {
+    throw new Error('Upload expiry must be between 1 and 604800 seconds');
+  }
+  if (options.checksum !== undefined && !/^[A-Za-z0-9+/]{43}=$/.test(options.checksum)) {
+    throw new Error('Upload checksum must be a base64 SHA-256 digest');
+  }
+}
+
+function validateMultipartCompletion(uploadId, parts) {
+  if (typeof uploadId !== 'string' || !uploadId) throw new Error('Upload ID is required');
+  if (!Array.isArray(parts) || parts.length < 2 || parts.length > 10000) {
+    throw new Error('Multipart completion requires between 2 and 10000 parts');
+  }
+  parts.forEach((part, index) => {
+    if (
+      part.partNumber !== index + 1 ||
+      typeof part.etag !== 'string' ||
+      !part.etag ||
+      /[\r\n]/.test(part.etag)
+    ) {
+      throw new Error('Multipart completion parts must be sequential and include an ETag');
+    }
+  });
+}
+
+function verifyMetadata(metadata, expected = {}) {
+  if (!metadata) throw new Error('Uploaded object not found');
+  if (expected.bytes !== undefined && metadata.bytes !== expected.bytes) {
+    throw new Error('Uploaded object size does not match');
+  }
+  if (expected.contentType !== undefined && metadata.contentType !== expected.contentType) {
+    throw new Error('Uploaded object content type does not match');
+  }
+  if (expected.checksum !== undefined && metadata.checksum !== expected.checksum) {
+    throw new Error('Uploaded object checksum does not match');
+  }
+  return metadata;
+}
+
 export default Files;

package/server/lib/vault/ids.js

@@ -1,13 +1,15 @@
 import { randomUUID } from 'node:crypto';
-import { customAlphabet, nanoid } from 'nanoid';
+import { customAlphabet } from 'nanoid';
 
+const ALPHANUMERIC_ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
 const LOWERCASE_BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+const alphanumericNanoId = customAlphabet(ALPHANUMERIC_ALPHABET);
 const lowercaseBase32 = customAlphabet(LOWERCASE_BASE32_ALPHABET);
 function generateUUID() {
   return randomUUID();
 }
 function generateNanoId(size) {
-  return nanoid(size);
+  return alphanumericNanoId(size);
 }
 function generateBase32Id(size = 16) {
   return lowercaseBase32(size);