@syncular/server 0.0.1 → 0.0.2-127

package/src/blobs/adapters/database.ts

@@ -46,15 +46,16 @@ export interface BlobTokenSigner {
  */
 export function createHmacTokenSigner(secret: string): BlobTokenSigner {
   const encoder = new TextEncoder();
+  const keyPromise = crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign', 'verify']
+  );
 
   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 key = await keyPromise;
     const signature = await crypto.subtle.sign(
       'HMAC',
       key,
@@ -63,6 +64,18 @@ export function createHmacTokenSigner(secret: string): BlobTokenSigner {
     return bufferToHex(new Uint8Array(signature));
   }
 
+  async function hmacVerify(
+    data: string,
+    signatureHex: string
+  ): Promise<boolean> {
+    const parsedSignature = hexToBuffer(signatureHex);
+    if (!parsedSignature) return false;
+    const signature = new Uint8Array(parsedSignature.length);
+    signature.set(parsedSignature);
+    const key = await keyPromise;
+    return crypto.subtle.verify('HMAC', key, signature, encoder.encode(data));
+  }
+
   return {
     async sign(payload, _expiresIn) {
       const data = JSON.stringify(payload);
@@ -75,8 +88,8 @@ export function createHmacTokenSigner(secret: string): BlobTokenSigner {
       const [dataB64, sig] = token.split('.');
       if (!dataB64 || !sig) return null;
 
-      const expectedSig = await hmacSign(dataB64);
-      if (sig !== expectedSig) return null;
+      const isValidSig = await hmacVerify(dataB64, sig);
+      if (!isValidSig) return null;
 
       try {
         const data = JSON.parse(atob(dataB64)) as {
@@ -101,6 +114,18 @@ function bufferToHex(buffer: Uint8Array): string {
     .join('');
 }
 
+function hexToBuffer(hex: string): Uint8Array | null {
+  if (hex.length === 0 || hex.length % 2 !== 0) return null;
+  if (!/^[0-9a-f]+$/i.test(hex)) return null;
+
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    const pair = hex.slice(i, i + 2);
+    out[i / 2] = Number.parseInt(pair, 16);
+  }
+  return out;
+}
+
 export interface DatabaseBlobStorageAdapterOptions<
   DB extends SyncBlobsDb = SyncBlobsDb,
 > {

package/src/blobs/adapters/filesystem.test.ts

@@ -0,0 +1,132 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { BlobStorageAdapter } from '@syncular/core';
+import { createHmacTokenSigner } from './database';
+import { createFilesystemBlobStorageAdapter } from './filesystem';
+
+let basePath: string;
+let adapter: BlobStorageAdapter;
+
+beforeEach(async () => {
+  basePath = await mkdtemp(join(tmpdir(), 'syncular-blob-test-'));
+  adapter = createFilesystemBlobStorageAdapter({
+    basePath,
+    baseUrl: 'https://example.com/api/sync',
+    tokenSigner: createHmacTokenSigner('test-secret'),
+  });
+});
+
+afterEach(async () => {
+  await rm(basePath, { recursive: true, force: true });
+});
+
+const testHash =
+  'sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890';
+const testData = new TextEncoder().encode('hello world');
+
+describe('createFilesystemBlobStorageAdapter', () => {
+  test('put + get round-trip', async () => {
+    await adapter.put!(testHash, testData);
+    const result = await adapter.get!(testHash);
+    expect(result).toEqual(testData);
+  });
+
+  test('putStream + getStream round-trip', async () => {
+    const inputStream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(testData);
+        controller.close();
+      },
+    });
+
+    await adapter.putStream!(testHash, inputStream);
+
+    const outputStream = await adapter.getStream!(testHash);
+    expect(outputStream).not.toBeNull();
+
+    const reader = outputStream!.getReader();
+    const chunks: Uint8Array[] = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+    const result = new Uint8Array(chunks.reduce((acc, c) => acc + c.length, 0));
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    expect(result).toEqual(testData);
+  });
+
+  test('get returns null for missing blob', async () => {
+    const result = await adapter.get!(testHash);
+    expect(result).toBeNull();
+  });
+
+  test('getStream returns null for missing blob', async () => {
+    const result = await adapter.getStream!(testHash);
+    expect(result).toBeNull();
+  });
+
+  test('exists returns true after put', async () => {
+    expect(await adapter.exists(testHash)).toBe(false);
+    await adapter.put!(testHash, testData);
+    expect(await adapter.exists(testHash)).toBe(true);
+  });
+
+  test('delete removes the blob', async () => {
+    await adapter.put!(testHash, testData);
+    expect(await adapter.exists(testHash)).toBe(true);
+    await adapter.delete(testHash);
+    expect(await adapter.exists(testHash)).toBe(false);
+  });
+
+  test('delete is idempotent for missing blob', async () => {
+    await adapter.delete(testHash);
+  });
+
+  test('getMetadata returns size', async () => {
+    await adapter.put!(testHash, testData);
+    const meta = await adapter.getMetadata!(testHash);
+    expect(meta).toEqual({ size: testData.length });
+  });
+
+  test('getMetadata returns null for missing blob', async () => {
+    const meta = await adapter.getMetadata!(testHash);
+    expect(meta).toBeNull();
+  });
+
+  test('creates hash-based subdirectories', async () => {
+    await adapter.put!(testHash, testData);
+    // hex = abcdef..., so subdirs should be "ab/cd"
+    const firstLevel = await readdir(basePath);
+    expect(firstLevel).toContain('ab');
+    const secondLevel = await readdir(join(basePath, 'ab'));
+    expect(secondLevel).toContain('cd');
+  });
+
+  test('signUpload returns a token URL', async () => {
+    const result = await adapter.signUpload({
+      hash: testHash,
+      size: 100,
+      mimeType: 'application/octet-stream',
+      expiresIn: 60,
+    });
+    expect(result.url).toContain('/blobs/');
+    expect(result.url).toContain('token=');
+    expect(result.method).toBe('PUT');
+  });
+
+  test('signDownload returns a token URL', async () => {
+    const url = await adapter.signDownload({
+      hash: testHash,
+      expiresIn: 60,
+    });
+    expect(url).toContain('/blobs/');
+    expect(url).toContain('token=');
+  });
+});

package/src/blobs/adapters/filesystem.ts

@@ -0,0 +1,189 @@
+/**
+ * Filesystem blob storage adapter.
+ *
+ * Stores blobs as files on disk with 2-level hash-based subdirectories.
+ * Uploads/downloads go through the server's blob routes using signed tokens
+ * (same pattern as the database adapter).
+ */
+
+import {
+  mkdir,
+  open,
+  readFile,
+  rename,
+  stat,
+  unlink,
+  writeFile,
+} from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import type {
+  BlobSignDownloadOptions,
+  BlobSignedUpload,
+  BlobSignUploadOptions,
+  BlobStorageAdapter,
+} from '@syncular/core';
+import type { BlobTokenSigner } from './database';
+
+export interface FilesystemBlobStorageAdapterOptions {
+  /** Directory root for blob files */
+  basePath: string;
+  /** Server base URL for upload/download routes (e.g. "/api/sync") */
+  baseUrl: string;
+  /** Token signer for authorization */
+  tokenSigner: BlobTokenSigner;
+}
+
+/**
+ * Resolve hash to a 2-level subdirectory path:
+ * `{basePath}/{hex[0..2]}/{hex[2..4]}/{hex}`
+ */
+function hashToFilePath(basePath: string, hash: string): string {
+  const hex = hash.startsWith('sha256:') ? hash.slice(7) : hash;
+  return join(basePath, hex.slice(0, 2), hex.slice(2, 4), hex);
+}
+
+function tmpPath(filePath: string): string {
+  return `${filePath}.${Date.now()}.tmp`;
+}
+
+/**
+ * Create a filesystem blob storage adapter.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createFilesystemBlobStorageAdapter({
+ *   basePath: '/data/blobs',
+ *   baseUrl: 'https://api.example.com/api/sync',
+ *   tokenSigner: createHmacTokenSigner(process.env.BLOB_SECRET!),
+ * });
+ * ```
+ */
+export function createFilesystemBlobStorageAdapter(
+  options: FilesystemBlobStorageAdapterOptions
+): BlobStorageAdapter {
+  const { basePath, tokenSigner } = options;
+  const normalizedBaseUrl = options.baseUrl.replace(/\/$/, '');
+
+  return {
+    name: 'filesystem',
+
+    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
+      );
+
+      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> {
+      try {
+        await stat(hashToFilePath(basePath, hash));
+        return true;
+      } catch {
+        return false;
+      }
+    },
+
+    async delete(hash: string): Promise<void> {
+      try {
+        await unlink(hashToFilePath(basePath, hash));
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+      }
+    },
+
+    async getMetadata(
+      hash: string
+    ): Promise<{ size: number; mimeType?: string } | null> {
+      try {
+        const s = await stat(hashToFilePath(basePath, hash));
+        return { size: s.size };
+      } catch {
+        return null;
+      }
+    },
+
+    async put(hash: string, data: Uint8Array): Promise<void> {
+      const filePath = hashToFilePath(basePath, hash);
+      const tmp = tmpPath(filePath);
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(tmp, data);
+      await rename(tmp, filePath);
+    },
+
+    async putStream(
+      hash: string,
+      stream: ReadableStream<Uint8Array>
+    ): Promise<void> {
+      const filePath = hashToFilePath(basePath, hash);
+      const tmp = tmpPath(filePath);
+      await mkdir(dirname(filePath), { recursive: true });
+
+      const fh = await open(tmp, 'w');
+      try {
+        const reader = stream.getReader();
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          await fh.write(value);
+        }
+      } finally {
+        await fh.close();
+      }
+
+      await rename(tmp, filePath);
+    },
+
+    async get(hash: string): Promise<Uint8Array | null> {
+      try {
+        const buf = await readFile(hashToFilePath(basePath, hash));
+        return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+        throw err;
+      }
+    },
+
+    async getStream(hash: string): Promise<ReadableStream<Uint8Array> | null> {
+      let data: Buffer;
+      try {
+        data = await readFile(hashToFilePath(basePath, hash));
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+        throw err;
+      }
+      const bytes = new Uint8Array(
+        data.buffer,
+        data.byteOffset,
+        data.byteLength
+      );
+      return new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(bytes);
+          controller.close();
+        },
+      });
+    },
+  };
+}