@syncular/server 0.1.2 → 0.2.0

package/src/blobs/access.ts

@@ -1,244 +0,0 @@
-import { collectScopeVars, type ScopeValues } from '@syncular/core';
-import { type Kysely, sql } from 'kysely';
-import type { ServerTableHandler, SyncServerAuth } from '../handlers/types';
-import { rowScopesAllowed } from '../helpers/scope-authorization';
-import type { SyncCoreDb } from '../schema';
-
-export type ScopedBlobAccessDecisionReason =
-  | 'allowed'
-  | 'handler_missing'
-  | 'missing_reference'
-  | 'resolve_scopes_failed'
-  | 'scope_denied';
-
-export interface ScopedBlobAccessDecision {
-  actorId: string;
-  partitionId: string;
-  hash: string;
-  allowed: boolean;
-  reason: ScopedBlobAccessDecisionReason;
-  table?: string;
-  column?: string;
-  rowId?: string;
-}
-
-export interface ScopedBlobReferenceTable {
-  table: string;
-  blobColumns: readonly string[];
-  primaryKeyColumn?: string;
-  candidateLimit?: number;
-}
-
-export interface CreateScopedBlobAccessCheckerOptions<
-  DB extends SyncCoreDb = SyncCoreDb,
-  Auth extends SyncServerAuth = SyncServerAuth,
-> {
-  db: Kysely<DB>;
-  handlers: readonly ServerTableHandler<DB, Auth>[];
-  references: readonly ScopedBlobReferenceTable[];
-  candidateLimit?: number;
-  onDecision?: (decision: ScopedBlobAccessDecision) => void;
-}
-
-export interface ScopedBlobAccessRequest<Auth extends SyncServerAuth> {
-  actorId: string;
-  partitionId: string;
-  hash: string;
-  auth?: Auth;
-}
-
-export function createScopedBlobAccessChecker<
-  DB extends SyncCoreDb,
-  Auth extends SyncServerAuth = SyncServerAuth,
->(
-  options: CreateScopedBlobAccessCheckerOptions<DB, Auth>
-): (request: ScopedBlobAccessRequest<Auth>) => Promise<boolean> {
-  const handlersByTable = new Map(
-    options.handlers.map((handler) => [handler.table, handler])
-  );
-  const candidateLimit = options.candidateLimit ?? 100;
-
-  const emit = (decision: ScopedBlobAccessDecision): void => {
-    options.onDecision?.(decision);
-  };
-
-  return async (request) => {
-    let deniedDecision: ScopedBlobAccessDecision | null = null;
-    let configurationDecision: ScopedBlobAccessDecision | null = null;
-
-    for (const reference of options.references) {
-      if (reference.blobColumns.length === 0) continue;
-
-      const rows = await readBlobReferenceCandidateRows({
-        db: options.db,
-        table: reference.table,
-        columns: reference.blobColumns,
-        hash: request.hash,
-        limit: reference.candidateLimit ?? candidateLimit,
-      });
-      if (rows.length === 0) {
-        continue;
-      }
-
-      const handler = handlersByTable.get(reference.table);
-      if (!handler) {
-        configurationDecision ??= {
-          ...request,
-          allowed: false,
-          reason: 'handler_missing',
-          table: reference.table,
-        };
-        continue;
-      }
-
-      const allowedScopes = await resolveBlobAccessScopes({
-        db: options.db,
-        handler,
-        request,
-      });
-      if (!allowedScopes.ok) {
-        configurationDecision ??= {
-          ...request,
-          allowed: false,
-          reason: 'resolve_scopes_failed',
-          table: reference.table,
-        };
-        continue;
-      }
-
-      const requiredScopeKeys = Array.from(
-        collectScopeVars(handler.scopePatterns)
-      );
-      for (const row of rows) {
-        const matchedColumn = reference.blobColumns.find((column) =>
-          blobColumnMatchesHash(row[column], request.hash)
-        );
-        if (!matchedColumn) continue;
-
-        const rowScopes = handler.extractScopes(row);
-        if (
-          !rowScopesAllowed({
-            rowScopes,
-            allowedScopes: allowedScopes.scopes,
-            requiredScopeKeys,
-          })
-        ) {
-          deniedDecision ??= {
-            ...request,
-            allowed: false,
-            reason: 'scope_denied',
-            table: reference.table,
-            column: matchedColumn,
-            rowId: readRowId(
-              row,
-              reference.primaryKeyColumn ?? handler.primaryKeyColumn
-            ),
-          };
-          continue;
-        }
-
-        emit({
-          ...request,
-          allowed: true,
-          reason: 'allowed',
-          table: reference.table,
-          column: matchedColumn,
-          rowId: readRowId(
-            row,
-            reference.primaryKeyColumn ?? handler.primaryKeyColumn
-          ),
-        });
-        return true;
-      }
-    }
-
-    emit(
-      deniedDecision ??
-        configurationDecision ?? {
-          ...request,
-          allowed: false,
-          reason: 'missing_reference',
-        }
-    );
-    return false;
-  };
-}
-
-async function resolveBlobAccessScopes<
-  DB extends SyncCoreDb,
-  Auth extends SyncServerAuth,
->(args: {
-  db: Kysely<DB>;
-  handler: ServerTableHandler<DB, Auth>;
-  request: ScopedBlobAccessRequest<Auth>;
-}): Promise<{ ok: true; scopes: ScopeValues } | { ok: false }> {
-  try {
-    const scopes = await args.handler.resolveScopes({
-      db: args.db,
-      actorId: args.request.actorId,
-      auth:
-        args.request.auth ??
-        ({
-          actorId: args.request.actorId,
-          partitionId: args.request.partitionId,
-        } as Auth),
-    });
-    return { ok: true, scopes };
-  } catch {
-    return { ok: false };
-  }
-}
-
-async function readBlobReferenceCandidateRows<DB extends SyncCoreDb>(args: {
-  db: Kysely<DB>;
-  table: string;
-  columns: readonly string[];
-  hash: string;
-  limit: number;
-}): Promise<Record<string, unknown>[]> {
-  const pattern = `%${args.hash}%`;
-  const predicates = args.columns.map(
-    (column) => sql`${sql.ref(column)} like ${pattern}`
-  );
-  const result = await sql<Record<string, unknown>>`
-    select *
-    from ${sql.table(args.table)}
-    where ${sql.join(predicates, sql` or `)}
-    limit ${args.limit}
-  `.execute(args.db);
-  return result.rows;
-}
-
-function readRowId(
-  row: Record<string, unknown>,
-  primaryKeyColumn: string | undefined
-): string | undefined {
-  const column = primaryKeyColumn ?? 'id';
-  const value = row[column];
-  return value === null || value === undefined ? undefined : String(value);
-}
-
-function blobColumnMatchesHash(value: unknown, hash: string): boolean {
-  const parsed = parseMaybeJson(value);
-  if (isBlobRefHash(parsed, hash)) return true;
-  if (Array.isArray(parsed)) {
-    return parsed.some((entry) => isBlobRefHash(parseMaybeJson(entry), hash));
-  }
-  return false;
-}
-
-function parseMaybeJson(value: unknown): unknown {
-  if (typeof value !== 'string') return value;
-  try {
-    return JSON.parse(value);
-  } catch {
-    return value;
-  }
-}
-
-function isBlobRefHash(value: unknown, hash: string): boolean {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    return false;
-  }
-  return (value as { hash?: unknown }).hash === hash;
-}

package/src/blobs/adapters/database.ts

@@ -1,397 +0,0 @@
-/**
- * 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 { resolveUrlFromBase } 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 {
-  /**
-   * Token payload for upload/download authorization.
-   * Upload tokens are bound to hash + expected byte size.
-   */
-  sign(
-    payload:
-      | {
-          hash: string;
-          partitionId: string;
-          action: 'upload';
-          size: number;
-          expiresAt: number;
-        }
-      | {
-          hash: string;
-          partitionId: string;
-          action: 'download';
-          expiresAt: number;
-        },
-    expiresIn: number
-  ): Promise<string>;
-
-  /**
-   * 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
-   */
-  verify(token: string): Promise<
-    | {
-        hash: string;
-        partitionId: string;
-        action: 'upload';
-        size: number;
-        expiresAt: number;
-      }
-    | {
-        hash: string;
-        partitionId: string;
-        action: 'download';
-        expiresAt: number;
-      }
-    | null
-  >;
-}
-
-/**
- * Create a simple HMAC-based token signer.
- */
-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 keyPromise;
-    const signature = await crypto.subtle.sign(
-      'HMAC',
-      key,
-      encoder.encode(data)
-    );
-    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);
-      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 isValidSig = await hmacVerify(dataB64, sig);
-      if (!isValidSig) return null;
-
-      try {
-        const parsed = JSON.parse(atob(dataB64)) as Record<string, unknown>;
-        if (typeof parsed.hash !== 'string') return null;
-        if (typeof parsed.partitionId !== 'string') return null;
-        if (typeof parsed.expiresAt !== 'number') return null;
-        if (Date.now() > parsed.expiresAt) return null;
-
-        if (parsed.action === 'download') {
-          return {
-            hash: parsed.hash,
-            partitionId: parsed.partitionId,
-            action: 'download',
-            expiresAt: parsed.expiresAt,
-          };
-        }
-
-        if (
-          parsed.action === 'upload' &&
-          typeof parsed.size === 'number' &&
-          Number.isFinite(parsed.size) &&
-          parsed.size >= 0
-        ) {
-          return {
-            hash: parsed.hash,
-            partitionId: parsed.partitionId,
-            action: 'upload',
-            size: parsed.size,
-            expiresAt: parsed.expiresAt,
-          };
-        }
-
-        return null;
-      } catch {
-        return null;
-      }
-    },
-  };
-}
-
-function bufferToHex(buffer: Uint8Array): string {
-  return Array.from(buffer)
-    .map((b) => b.toString(16).padStart(2, '0'))
-    .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,
-> {
-  /** 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;
-  const resolvePartitionId = (partitionId?: string): string =>
-    partitionId ?? 'default';
-  const normalizeBlobSizeValue = (value: number | string): number =>
-    typeof value === 'number' ? value : Number(value);
-
-  return {
-    name: 'database',
-
-    async signUpload(opts: BlobSignUploadOptions): Promise<BlobSignedUpload> {
-      const partitionId = resolvePartitionId(opts.partitionId);
-      const expiresAt = Date.now() + opts.expiresIn * 1000;
-      const token = await tokenSigner.sign(
-        {
-          hash: opts.hash,
-          partitionId,
-          action: 'upload',
-          size: opts.size,
-          expiresAt,
-        },
-        opts.expiresIn
-      );
-
-      // URL points to server's blob upload endpoint
-      const uploadPath = `/blobs/${encodeURIComponent(opts.hash)}/upload?token=${encodeURIComponent(token)}`;
-      const url = resolveUrlFromBase(baseUrl, uploadPath);
-
-      return {
-        url,
-        method: 'PUT',
-        headers: {
-          'Content-Type': opts.mimeType,
-          'Content-Length': String(opts.size),
-        },
-      };
-    },
-
-    async signDownload(opts: BlobSignDownloadOptions): Promise<string> {
-      const partitionId = resolvePartitionId(opts.partitionId);
-      const expiresAt = Date.now() + opts.expiresIn * 1000;
-      const token = await tokenSigner.sign(
-        { hash: opts.hash, partitionId, action: 'download', expiresAt },
-        opts.expiresIn
-      );
-
-      return resolveUrlFromBase(
-        baseUrl,
-        `/blobs/${encodeURIComponent(opts.hash)}/download?token=${encodeURIComponent(token)}`
-      );
-    },
-
-    async exists(
-      hash: string,
-      options?: { partitionId?: string }
-    ): Promise<boolean> {
-      const partitionId = resolvePartitionId(options?.partitionId);
-      const rowResult = await sql<{ hash: string }>`
-        select hash
-        from ${sql.table('sync_blobs')}
-        where partition_id = ${partitionId} and hash = ${hash}
-        limit 1
-      `.execute(db);
-      return rowResult.rows.length > 0;
-    },
-
-    async delete(
-      hash: string,
-      options?: { partitionId?: string }
-    ): Promise<void> {
-      const partitionId = resolvePartitionId(options?.partitionId);
-      await sql`
-        delete from ${sql.table('sync_blobs')}
-        where partition_id = ${partitionId} and hash = ${hash}
-      `.execute(db);
-    },
-
-    async getMetadata(
-      hash: string,
-      options?: { partitionId?: string }
-    ): Promise<{ size: number; mimeType?: string } | null> {
-      const partitionId = resolvePartitionId(options?.partitionId);
-      const rowResult = await sql<{ size: number | string; mime_type: string }>`
-        select size, mime_type
-        from ${sql.table('sync_blobs')}
-        where partition_id = ${partitionId} and hash = ${hash}
-        limit 1
-      `.execute(db);
-      const row = rowResult.rows[0];
-
-      if (!row) return null;
-
-      return {
-        size: normalizeBlobSizeValue(row.size),
-        mimeType: row.mime_type,
-      };
-    },
-
-    async put(
-      hash: string,
-      data: Uint8Array,
-      metadata?: Record<string, unknown>,
-      options?: { partitionId?: string }
-    ): Promise<void> {
-      const partitionId = resolvePartitionId(options?.partitionId);
-      const mimeType =
-        typeof metadata?.mimeType === 'string'
-          ? metadata.mimeType
-          : 'application/octet-stream';
-      await storeBlobInDatabase(db, {
-        partitionId,
-        hash,
-        size: data.length,
-        mimeType,
-        body: data,
-      });
-    },
-
-    async get(
-      hash: string,
-      options?: { partitionId?: string }
-    ): Promise<Uint8Array | null> {
-      const partitionId = resolvePartitionId(options?.partitionId);
-      const result = await readBlobFromDatabase(db, hash, { partitionId });
-      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: {
-    partitionId: string;
-    hash: string;
-    size: number;
-    mimeType: string;
-    body: Uint8Array;
-  }
-): Promise<void> {
-  await sql`
-    insert into ${sql.table('sync_blobs')} (
-      partition_id,
-      hash,
-      size,
-      mime_type,
-      body,
-      created_at
-    )
-    values (
-      ${args.partitionId},
-      ${args.hash},
-      ${args.size},
-      ${args.mimeType},
-      ${args.body},
-      ${new Date().toISOString()}
-    )
-    on conflict (partition_id, 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,
-  options?: { partitionId?: string }
-): Promise<{ body: Uint8Array; mimeType: string; size: number } | null> {
-  const partitionId = options?.partitionId ?? 'default';
-  const rowResult = await sql<{
-    body: Uint8Array;
-    mime_type: string;
-    size: number | string;
-  }>`
-    select body, mime_type, size
-    from ${sql.table('sync_blobs')}
-    where partition_id = ${partitionId} and hash = ${hash}
-    limit 1
-  `.execute(db);
-  const row = rowResult.rows[0];
-
-  if (!row) return null;
-
-  return {
-    body: row.body,
-    mimeType: row.mime_type,
-    size: typeof row.size === 'number' ? row.size : Number(row.size),
-  };
-}

package/src/blobs/index.ts

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