feat: add onboarding

donut-sync/src/sync/dto/sync.dto.ts

@@ -6,17 +6,25 @@ export class StatResponseDto {
   exists: boolean;
   lastModified?: string;
   size?: number;
+  // User-defined S3 object metadata (lowercased keys, no `x-amz-meta-` prefix).
+  // Carries `updated-at` for sync conflict resolution via HEAD (no body GET).
+  metadata?: Record<string, string>;
 }
 
 export class PresignUploadRequestDto {
   key: string;
   contentType?: string;
   expiresIn?: number;
+  // Object metadata to sign into the presigned PUT as `x-amz-meta-*`.
+  metadata?: Record<string, string>;
 }
 
 export class PresignUploadResponseDto {
   url: string;
   expiresAt: string;
+  // Metadata the server actually signed; the client must echo it as
+  // `x-amz-meta-*` headers on the PUT (older clients/servers omit it).
+  metadata?: Record<string, string>;
 }
 
 export class PresignDownloadRequestDto {

donut-sync/src/sync/sync.service.ts

@@ -256,6 +256,10 @@ export class SyncService implements OnModuleInit {
         exists: true,
         lastModified: response.LastModified?.toISOString(),
         size: response.ContentLength,
+        // S3 returns user metadata with lowercased keys and no `x-amz-meta-`
+        // prefix. Clients read `updated-at` from here to resolve sync conflicts
+        // without downloading the object body.
+        metadata: response.Metadata,
       };
     } catch (error: unknown) {
       if (
@@ -289,6 +293,9 @@ export class SyncService implements OnModuleInit {
       Bucket: this.bucket,
       Key: key,
       ContentType: dto.contentType || "application/octet-stream",
+      // Signed into the presigned URL as `x-amz-meta-*`. The client must send
+      // exactly these headers on the PUT, so we echo them in the response.
+      Metadata: dto.metadata,
     });
 
     const url = await getSignedUrl(this.s3Client, command, { expiresIn });