@syncular/server 0.0.1-60

package/src/blobs/adapters/database.ts

@@ -0,0 +1,290 @@
+/**
+ * Database blob storage adapter.
+ *
+ * Stores blobs directly in the database. Useful for development and small deployments.
+ * Since there's no external service, this adapter generates signed tokens that allow
+ * uploads/downloads through the server's blob routes.
+ */
+
+import type {
+  BlobSignDownloadOptions,
+  BlobSignedUpload,
+  BlobSignUploadOptions,
+  BlobStorageAdapter,
+} from '@syncular/core';
+import { type Kysely, sql } from 'kysely';
+import type { SyncBlobsDb } from '../types';
+
+/**
+ * Token signer interface for creating/verifying upload/download tokens.
+ */
+export interface BlobTokenSigner {
+  /**
+   * Sign a token for blob upload/download authorization.
+   * @param payload The data to sign
+   * @param expiresIn Expiration time in seconds
+   * @returns A signed token string
+   */
+  sign(
+    payload: { hash: string; action: 'upload' | 'download'; expiresAt: number },
+    expiresIn: number
+  ): Promise<string>;
+
+  /**
+   * Verify and decode a signed token.
+   * @returns The payload if valid, null if invalid/expired
+   */
+  verify(token: string): Promise<{
+    hash: string;
+    action: 'upload' | 'download';
+    expiresAt: number;
+  } | null>;
+}
+
+/**
+ * Create a simple HMAC-based token signer.
+ */
+export function createHmacTokenSigner(secret: string): BlobTokenSigner {
+  const encoder = new TextEncoder();
+
+  async function hmacSign(data: string): Promise<string> {
+    const key = await crypto.subtle.importKey(
+      'raw',
+      encoder.encode(secret),
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign']
+    );
+    const signature = await crypto.subtle.sign(
+      'HMAC',
+      key,
+      encoder.encode(data)
+    );
+    return bufferToHex(new Uint8Array(signature));
+  }
+
+  return {
+    async sign(payload, _expiresIn) {
+      const data = JSON.stringify(payload);
+      const dataB64 = btoa(data);
+      const sig = await hmacSign(dataB64);
+      return `${dataB64}.${sig}`;
+    },
+
+    async verify(token) {
+      const [dataB64, sig] = token.split('.');
+      if (!dataB64 || !sig) return null;
+
+      const expectedSig = await hmacSign(dataB64);
+      if (sig !== expectedSig) return null;
+
+      try {
+        const data = JSON.parse(atob(dataB64)) as {
+          hash: string;
+          action: 'upload' | 'download';
+          expiresAt: number;
+        };
+
+        if (Date.now() > data.expiresAt) return null;
+
+        return data;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+function bufferToHex(buffer: Uint8Array): string {
+  return Array.from(buffer)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+export interface DatabaseBlobStorageAdapterOptions<
+  DB extends SyncBlobsDb = SyncBlobsDb,
+> {
+  /** Kysely database instance */
+  db: Kysely<DB>;
+  /** Base URL for the blob routes (e.g., "https://api.example.com/api/sync") */
+  baseUrl: string;
+  /** Token signer for authorization */
+  tokenSigner: BlobTokenSigner;
+}
+
+/**
+ * Create a database blob storage adapter.
+ *
+ * This adapter stores blobs directly in the database and generates signed URLs
+ * that point back to the server for upload/download.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createDatabaseBlobStorageAdapter({
+ *   db: kysely,
+ *   baseUrl: 'https://api.example.com/api/sync',
+ *   tokenSigner: createHmacTokenSigner(process.env.BLOB_SECRET),
+ * });
+ * ```
+ */
+export function createDatabaseBlobStorageAdapter<DB extends SyncBlobsDb>(
+  options: DatabaseBlobStorageAdapterOptions<DB>
+): BlobStorageAdapter {
+  const { db, baseUrl, tokenSigner } = options;
+
+  // Normalize base URL (remove trailing slash)
+  const normalizedBaseUrl = baseUrl.replace(/\/$/, '');
+
+  return {
+    name: 'database',
+
+    async signUpload(opts: BlobSignUploadOptions): Promise<BlobSignedUpload> {
+      const expiresAt = Date.now() + opts.expiresIn * 1000;
+      const token = await tokenSigner.sign(
+        { hash: opts.hash, action: 'upload', expiresAt },
+        opts.expiresIn
+      );
+
+      // URL points to server's blob upload endpoint
+      const url = `${normalizedBaseUrl}/blobs/${encodeURIComponent(opts.hash)}/upload?token=${encodeURIComponent(token)}`;
+
+      return {
+        url,
+        method: 'PUT',
+        headers: {
+          'Content-Type': opts.mimeType,
+          'Content-Length': String(opts.size),
+        },
+      };
+    },
+
+    async signDownload(opts: BlobSignDownloadOptions): Promise<string> {
+      const expiresAt = Date.now() + opts.expiresIn * 1000;
+      const token = await tokenSigner.sign(
+        { hash: opts.hash, action: 'download', expiresAt },
+        opts.expiresIn
+      );
+
+      return `${normalizedBaseUrl}/blobs/${encodeURIComponent(opts.hash)}/download?token=${encodeURIComponent(token)}`;
+    },
+
+    async exists(hash: string): Promise<boolean> {
+      const rowResult = await sql<{ hash: string }>`
+        select hash
+        from ${sql.table('sync_blobs')}
+        where hash = ${hash}
+        limit 1
+      `.execute(db);
+      return rowResult.rows.length > 0;
+    },
+
+    async delete(hash: string): Promise<void> {
+      await sql`
+        delete from ${sql.table('sync_blobs')}
+        where hash = ${hash}
+      `.execute(db);
+    },
+
+    async getMetadata(
+      hash: string
+    ): Promise<{ size: number; mimeType?: string } | null> {
+      const rowResult = await sql<{ size: number; mime_type: string }>`
+        select size, mime_type
+        from ${sql.table('sync_blobs')}
+        where hash = ${hash}
+        limit 1
+      `.execute(db);
+      const row = rowResult.rows[0];
+
+      if (!row) return null;
+
+      return {
+        size: row.size,
+        mimeType: row.mime_type,
+      };
+    },
+
+    async put(
+      hash: string,
+      data: Uint8Array,
+      metadata?: Record<string, unknown>
+    ): Promise<void> {
+      const mimeType =
+        typeof metadata?.mimeType === 'string'
+          ? metadata.mimeType
+          : 'application/octet-stream';
+      await storeBlobInDatabase(db, {
+        hash,
+        size: data.length,
+        mimeType,
+        body: data,
+      });
+    },
+
+    async get(hash: string): Promise<Uint8Array | null> {
+      const result = await readBlobFromDatabase(db, hash);
+      return result?.body ?? null;
+    },
+  };
+}
+
+/**
+ * Store a blob in the database.
+ * Called by the server routes when handling direct uploads.
+ */
+export async function storeBlobInDatabase<DB extends SyncBlobsDb>(
+  db: Kysely<DB>,
+  args: {
+    hash: string;
+    size: number;
+    mimeType: string;
+    body: Uint8Array;
+  }
+): Promise<void> {
+  await sql`
+    insert into ${sql.table('sync_blobs')} (
+      hash,
+      size,
+      mime_type,
+      body,
+      created_at
+    )
+    values (
+      ${args.hash},
+      ${args.size},
+      ${args.mimeType},
+      ${args.body},
+      ${new Date().toISOString()}
+    )
+    on conflict (hash) do nothing
+  `.execute(db);
+}
+
+/**
+ * Read a blob from the database.
+ * Called by the server routes when handling direct downloads.
+ */
+export async function readBlobFromDatabase<DB extends SyncBlobsDb>(
+  db: Kysely<DB>,
+  hash: string
+): Promise<{ body: Uint8Array; mimeType: string; size: number } | null> {
+  const rowResult = await sql<{
+    body: Uint8Array;
+    mime_type: string;
+    size: number;
+  }>`
+    select body, mime_type, size
+    from ${sql.table('sync_blobs')}
+    where hash = ${hash}
+    limit 1
+  `.execute(db);
+  const row = rowResult.rows[0];
+
+  if (!row) return null;
+
+  return {
+    body: row.body,
+    mimeType: row.mime_type,
+    size: row.size,
+  };
+}

package/src/blobs/adapters/s3.ts

@@ -0,0 +1,271 @@
+/**
+ * S3-compatible blob storage adapter.
+ *
+ * Works with AWS S3, Cloudflare R2, MinIO, and other S3-compatible services.
+ * Requires @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner as peer dependencies.
+ */
+
+import type {
+  BlobSignDownloadOptions,
+  BlobSignedUpload,
+  BlobSignUploadOptions,
+  BlobStorageAdapter,
+} from '@syncular/core';
+
+/**
+ * S3 client interface (minimal subset of @aws-sdk/client-s3).
+ * This allows users to pass in their own configured S3 client.
+ */
+export interface S3ClientLike {
+  send(command: unknown): Promise<unknown>;
+}
+
+/**
+ * Function to create presigned URLs.
+ * This should be getSignedUrl from @aws-sdk/s3-request-presigner.
+ */
+export type GetSignedUrlFn = (
+  client: S3ClientLike,
+  command: unknown,
+  options: { expiresIn: number }
+) => Promise<string>;
+
+/**
+ * S3 command constructors.
+ * These should be imported from @aws-sdk/client-s3.
+ */
+export interface S3Commands {
+  PutObjectCommand: new (input: {
+    Bucket: string;
+    Key: string;
+    ContentLength: number;
+    ContentType: string;
+    ChecksumSHA256?: string;
+  }) => unknown;
+  GetObjectCommand: new (input: { Bucket: string; Key: string }) => unknown;
+  HeadObjectCommand: new (input: { Bucket: string; Key: string }) => unknown;
+  DeleteObjectCommand: new (input: { Bucket: string; Key: string }) => unknown;
+}
+
+export interface S3BlobStorageAdapterOptions {
+  /** S3 client instance */
+  client: S3ClientLike;
+  /** S3 bucket name */
+  bucket: string;
+  /** Optional key prefix for all blobs */
+  keyPrefix?: string;
+  /** S3 command constructors */
+  commands: S3Commands;
+  /** getSignedUrl function from @aws-sdk/s3-request-presigner */
+  getSignedUrl: GetSignedUrlFn;
+  /**
+   * Whether to require SHA-256 checksum validation on upload.
+   * Supported by S3 and R2. Default: true.
+   */
+  requireChecksum?: boolean;
+}
+
+/**
+ * Create an S3-compatible blob storage adapter.
+ *
+ * @example
+ * ```typescript
+ * import { S3Client, PutObjectCommand, GetObjectCommand, HeadObjectCommand, DeleteObjectCommand } from '@aws-sdk/client-s3';
+ * import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+ *
+ * const adapter = createS3BlobStorageAdapter({
+ *   client: new S3Client({ region: 'us-east-1' }),
+ *   bucket: 'my-bucket',
+ *   keyPrefix: 'blobs/',
+ *   commands: { PutObjectCommand, GetObjectCommand, HeadObjectCommand, DeleteObjectCommand },
+ *   getSignedUrl,
+ * });
+ * ```
+ */
+export function createS3BlobStorageAdapter(
+  options: S3BlobStorageAdapterOptions
+): BlobStorageAdapter {
+  const {
+    client,
+    bucket,
+    keyPrefix = '',
+    commands,
+    getSignedUrl,
+    requireChecksum = true,
+  } = options;
+
+  function getKey(hash: string): string {
+    // Remove "sha256:" prefix and use hex as key
+    const hex = hash.startsWith('sha256:') ? hash.slice(7) : hash;
+    return `${keyPrefix}${hex}`;
+  }
+
+  return {
+    name: 's3',
+
+    async signUpload(opts: BlobSignUploadOptions): Promise<BlobSignedUpload> {
+      const key = getKey(opts.hash);
+
+      // Extract hex hash for checksum (S3 expects base64-encoded SHA-256)
+      const hexHash = opts.hash.startsWith('sha256:')
+        ? opts.hash.slice(7)
+        : opts.hash;
+
+      // Convert hex to base64 for S3 checksum header
+      const checksumBase64 = hexToBase64(hexHash);
+
+      const commandInput: {
+        Bucket: string;
+        Key: string;
+        ContentLength: number;
+        ContentType: string;
+        ChecksumSHA256?: string;
+      } = {
+        Bucket: bucket,
+        Key: key,
+        ContentLength: opts.size,
+        ContentType: opts.mimeType,
+      };
+
+      if (requireChecksum) {
+        commandInput.ChecksumSHA256 = checksumBase64;
+      }
+
+      const command = new commands.PutObjectCommand(commandInput);
+      const url = await getSignedUrl(client, command, {
+        expiresIn: opts.expiresIn,
+      });
+
+      const headers: Record<string, string> = {
+        'Content-Type': opts.mimeType,
+        'Content-Length': String(opts.size),
+      };
+
+      if (requireChecksum) {
+        headers['x-amz-checksum-sha256'] = checksumBase64;
+      }
+
+      return {
+        url,
+        method: 'PUT',
+        headers,
+      };
+    },
+
+    async signDownload(opts: BlobSignDownloadOptions): Promise<string> {
+      const key = getKey(opts.hash);
+      const command = new commands.GetObjectCommand({
+        Bucket: bucket,
+        Key: key,
+      });
+      return getSignedUrl(client, command, { expiresIn: opts.expiresIn });
+    },
+
+    async exists(hash: string): Promise<boolean> {
+      const key = getKey(hash);
+      try {
+        const command = new commands.HeadObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        });
+        await client.send(command);
+        return true;
+      } catch (err) {
+        // Check for NotFound error
+        if (isNotFoundError(err)) {
+          return false;
+        }
+        throw err;
+      }
+    },
+
+    async delete(hash: string): Promise<void> {
+      const key = getKey(hash);
+      const command = new commands.DeleteObjectCommand({
+        Bucket: bucket,
+        Key: key,
+      });
+      await client.send(command);
+    },
+
+    async getMetadata(
+      hash: string
+    ): Promise<{ size: number; mimeType?: string } | null> {
+      const key = getKey(hash);
+      try {
+        const command = new commands.HeadObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        });
+        const response = (await client.send(command)) as {
+          ContentLength?: number;
+          ContentType?: string;
+        };
+        return {
+          size: response.ContentLength ?? 0,
+          mimeType: response.ContentType,
+        };
+      } catch (err) {
+        if (isNotFoundError(err)) {
+          return null;
+        }
+        throw err;
+      }
+    },
+  };
+}
+
+function isNotFoundError(err: unknown): boolean {
+  if (typeof err !== 'object' || err === null) return false;
+  const e = err as { name?: string; $metadata?: { httpStatusCode?: number } };
+  return (
+    e.name === 'NotFound' ||
+    e.name === 'NoSuchKey' ||
+    e.$metadata?.httpStatusCode === 404
+  );
+}
+
+function hexToBase64(hex: string): string {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+
+  // Use Buffer if available (Node/Bun), otherwise manual base64
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64');
+  }
+
+  // Manual base64 encoding
+  const chars =
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  let result = '';
+  const len = bytes.length;
+  const remainder = len % 3;
+
+  for (let i = 0; i < len - remainder; i += 3) {
+    const a = bytes[i]!;
+    const b = bytes[i + 1]!;
+    const c = bytes[i + 2]!;
+    result +=
+      chars.charAt((a >> 2) & 0x3f) +
+      chars.charAt(((a << 4) | (b >> 4)) & 0x3f) +
+      chars.charAt(((b << 2) | (c >> 6)) & 0x3f) +
+      chars.charAt(c & 0x3f);
+  }
+
+  if (remainder === 1) {
+    const a = bytes[len - 1]!;
+    result += `${chars.charAt((a >> 2) & 0x3f) + chars.charAt((a << 4) & 0x3f)}==`;
+  } else if (remainder === 2) {
+    const a = bytes[len - 2]!;
+    const b = bytes[len - 1]!;
+    result +=
+      chars.charAt((a >> 2) & 0x3f) +
+      chars.charAt(((a << 4) | (b >> 4)) & 0x3f) +
+      chars.charAt((b << 2) & 0x3f) +
+      '=';
+  }
+
+  return result;
+}

package/src/blobs/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @syncular/server - Blob storage exports
+ */
+
+export * from './adapters/database';
+export * from './adapters/s3';
+export * from './manager';
+export * from './migrate';
+export * from './types';