@syncular/server 0.0.6-96 → 0.1.1

package/src/handlers/types.ts

@@ -1,8 +1,12 @@
 import type {
+  BinarySnapshotColumn,
+  BinarySnapshotRowsEncoder,
   ScopePattern,
   ScopeValues,
   ScopeValuesForKeys,
   StoredScopes,
+  SyncAuthLeaseProvenance,
+  SyncChange,
   SyncOp,
   SyncOperation,
   SyncOperationResult,
@@ -43,6 +47,11 @@ export interface ApplyOperationResult {
   emittedChanges: EmittedChange[];
 }
 
+export interface BatchApplyOperationInput {
+  op: SyncOperation;
+  opIndex: number;
+}
+
 /**
  * Context for server operations.
  */
@@ -74,6 +83,11 @@ export interface ServerSnapshotContext<
   cursor: string | null;
   /** Max rows to return */
   limit: number;
+  /**
+   * Client schema version targeted by this snapshot.
+   * Use this to emit the correct generated client row shape for older clients.
+   */
+  schemaVersion: number;
 }
 
 /**
@@ -94,6 +108,11 @@ export interface ServerApplyOperationContext<
    * Use this to transform payloads from older client versions.
    */
   schemaVersion: number;
+  /**
+   * Auth lease provenance captured when the client queued the commit.
+   * This is audit/replay context only; handlers must still use current auth.
+   */
+  authLease?: SyncAuthLeaseProvenance;
 }
 
 /**
@@ -200,6 +219,35 @@ export interface ServerHandlerOptions<
    */
   snapshotChunkTtlMs?: number;
 
+  /**
+   * Stable binary snapshot column metadata. Generators should provide this for
+   * Rust/native clients so the server does not need to infer column order and
+   * value types from every snapshot chunk at runtime.
+   */
+  snapshotBinaryColumns?: readonly BinarySnapshotColumn[];
+
+  /**
+   * Version-aware binary snapshot column metadata. Returning null intentionally
+   * disables fallback to current metadata.
+   */
+  snapshotBinaryColumnsForVersion?: (
+    schemaVersion: number
+  ) => readonly BinarySnapshotColumn[] | null | undefined;
+
+  /**
+   * Optional generated binary snapshot encoder. When present, binary bootstrap
+   * chunks use this instead of the generic object-row encoder.
+   */
+  snapshotBinaryEncoder?: BinarySnapshotRowsEncoder;
+
+  /**
+   * Version-aware generated binary snapshot encoder. Returning null
+   * intentionally disables fallback to the current encoder.
+   */
+  snapshotBinaryEncoderForVersion?: (
+    schemaVersion: number
+  ) => BinarySnapshotRowsEncoder | null | undefined;
+
   /**
    * Transform client payload → server row on writes.
    */
@@ -245,6 +293,9 @@ export interface ServerTableHandler<
   /** Table name */
   table: string;
 
+  /** Primary key column for row ids and artifact/import metadata. */
+  primaryKeyColumn?: string;
+
   /** Scope patterns used by this handler */
   scopePatterns: ScopePattern[];
 
@@ -258,6 +309,58 @@ export interface ServerTableHandler<
    */
   snapshotChunkTtlMs?: number;
 
+  /**
+   * Stable binary snapshot column metadata used by binary bootstrap chunks.
+   */
+  snapshotBinaryColumns?: readonly BinarySnapshotColumn[];
+
+  /**
+   * Version-aware binary snapshot column metadata. Generated handlers should
+   * use this when old client schema versions can have different row shapes.
+   * Returning null intentionally disables fallback to current metadata.
+   */
+  snapshotBinaryColumnsForVersion?: (
+    schemaVersion: number
+  ) => readonly BinarySnapshotColumn[] | null | undefined;
+
+  /**
+   * Optional generated binary snapshot encoder used by binary bootstrap chunks.
+   */
+  snapshotBinaryEncoder?: BinarySnapshotRowsEncoder;
+
+  /**
+   * Version-aware binary snapshot encoder. Returning null intentionally
+   * disables fallback to the current generated encoder.
+   */
+  snapshotBinaryEncoderForVersion?: (
+    schemaVersion: number
+  ) => BinarySnapshotRowsEncoder | null | undefined;
+
+  /**
+   * Project a persisted incremental change row to the requested client schema
+   * before pull plugins, wire integrity, and response encoding run.
+   *
+   * Generated divergent-schema handlers use this to keep the commit log in the
+   * current client row shape while serving older clients their targeted row
+   * shape.
+   */
+  projectChangeForVersion?: (
+    change: SyncChange,
+    schemaVersion: number
+  ) => SyncChange;
+
+  /**
+   * Hint for push engine savepoint optimization on single-op commits.
+   *
+   * When true, the handler guarantees that a rejected single operation
+   * does not leave durable writes behind before returning the rejection.
+   * This allows pushCommit() to skip SAVEPOINT overhead for single-op
+   * commits on savepoint-capable dialects.
+   *
+   * Omit or set false for custom handlers unless this guarantee holds.
+   */
+  canRejectSingleOperationWithoutSavepoint?: boolean;
+
   /**
    * Resolve allowed scope values for the current actor.
    */
@@ -284,4 +387,17 @@ export interface ServerTableHandler<
     op: SyncOperation,
     opIndex: number
   ): Promise<ApplyOperationResult>;
+
+  /**
+   * Apply multiple operations in order.
+   *
+   * Implementations may internally batch writes but must preserve the same
+   * observable semantics as sequential applyOperation calls:
+   * - results are returned in operation order
+   * - processing stops at the first non-applied result
+   */
+  applyOperationBatch?(
+    ctx: ServerApplyOperationContext<DB, Auth>,
+    operations: BatchApplyOperationInput[]
+  ): Promise<ApplyOperationResult[]>;
 }

package/src/helpers/index.ts

@@ -7,4 +7,6 @@
 export * from './conflict';
 export * from './emitted-change';
 export * from './paginate';
+export * from './scope-authorization';
+export * from './scope-commit-index';
 export * from './scope-strings';

package/src/helpers/scope-authorization.ts

@@ -0,0 +1,27 @@
+import type { ScopeValues, StoredScopes } from '@syncular/core';
+
+function scopeValueAllows(
+  allowed: ScopeValues[string] | undefined,
+  rowValue: string
+): boolean {
+  if (allowed === undefined) return false;
+  const allowedValues = Array.isArray(allowed) ? allowed : [allowed];
+  return allowedValues.includes('*') || allowedValues.includes(rowValue);
+}
+
+export function rowScopesAllowed(args: {
+  rowScopes: StoredScopes;
+  allowedScopes: ScopeValues;
+  requiredScopeKeys: readonly string[];
+}): boolean {
+  for (const key of args.requiredScopeKeys) {
+    const rowValue = args.rowScopes[key];
+    if (typeof rowValue !== 'string' || rowValue.length === 0) {
+      return false;
+    }
+    if (!scopeValueAllows(args.allowedScopes[key], rowValue)) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/helpers/scope-commit-index.ts

@@ -0,0 +1,52 @@
+import type { ScopeValues, StoredScopes } from '@syncular/core';
+
+export interface ScopeCommitIndexChange {
+  table: string;
+  scopes: ScopeValues | StoredScopes;
+}
+
+export interface ScopeCommitIndexEntry {
+  table: string;
+  scopeKey: string;
+}
+
+export function scopeKeysFromScopeValues(
+  scopes: ScopeValues | StoredScopes | null | undefined
+): string[] {
+  if (!scopes || typeof scopes !== 'object') return [];
+  const keys = new Set<string>();
+
+  for (const [key, rawValue] of Object.entries(scopes)) {
+    const prefix = key.replace(/_id$/, '');
+    const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+    for (const value of values) {
+      if (typeof value === 'string') {
+        if (value.length > 0) keys.add(`${prefix}:${value}`);
+        continue;
+      }
+      if (typeof value === 'number' || typeof value === 'bigint') {
+        keys.add(`${prefix}:${String(value)}`);
+      }
+    }
+  }
+
+  return Array.from(keys);
+}
+
+export function createScopeCommitIndexEntries(
+  changes: readonly ScopeCommitIndexChange[]
+): ScopeCommitIndexEntry[] {
+  const entries = new Map<string, ScopeCommitIndexEntry>();
+
+  for (const change of changes) {
+    if (!change.table) continue;
+    for (const scopeKey of scopeKeysFromScopeValues(change.scopes)) {
+      const key = `${change.table}\u0000${scopeKey}`;
+      if (!entries.has(key)) {
+        entries.set(key, { table: change.table, scopeKey });
+      }
+    }
+  }
+
+  return Array.from(entries.values());
+}

package/src/hono/api-key-auth.ts

@@ -0,0 +1,177 @@
+/**
+ * @syncular/server/hono - API Key Authentication Helper
+ *
+ * Provides utilities for validating API keys in relay/proxy routes.
+ */
+
+import { sha256Hex } from '@syncular/core';
+import type { ServerSyncDialect } from '@syncular/server';
+import type { Context } from 'hono';
+import { type Kysely, sql } from 'kysely';
+import { type ApiKeyType, ApiKeyTypeSchema } from './console/schemas';
+import { syncError } from './errors';
+
+interface SyncApiKeysTable {
+  key_id: string;
+  key_hash: string;
+  key_prefix: string;
+  name: string;
+  key_type: string;
+  scope_keys: unknown | null;
+  actor_id: string | null;
+  created_at: string;
+  expires_at: string | null;
+  last_used_at: string | null;
+  revoked_at: string | null;
+}
+
+type ApiKeyDb = {
+  sync_api_keys: SyncApiKeysTable;
+};
+
+interface ValidateApiKeyResult {
+  keyId: string;
+  keyType: ApiKeyType;
+  actorId: string | null;
+  scopeKeys: string[];
+}
+
+/**
+ * Validates an API key from Authorization header.
+ * Updates last_used_at on successful validation.
+ */
+export async function validateApiKey<DB extends ApiKeyDb>(
+  db: Kysely<DB>,
+  dialect: ServerSyncDialect,
+  authHeader: string | undefined
+): Promise<ValidateApiKeyResult | null> {
+  if (!authHeader?.startsWith('Bearer ')) {
+    return null;
+  }
+
+  const secretKey = authHeader.slice(7);
+  if (!secretKey?.startsWith('sk_')) {
+    return null;
+  }
+
+  // Hash the provided key
+  const keyHash = await hashApiKey(secretKey);
+
+  // Look up key by hash
+  const rowResult = await sql<{
+    key_id: string;
+    key_type: string;
+    actor_id: string | null;
+    scope_keys: unknown | null;
+    expires_at: string | null;
+    revoked_at: string | null;
+  }>`
+    select key_id, key_type, actor_id, scope_keys, expires_at, revoked_at
+    from ${sql.table('sync_api_keys')}
+    where key_hash = ${keyHash}
+    limit 1
+  `.execute(db);
+  const row = rowResult.rows[0];
+
+  if (!row) {
+    return null;
+  }
+
+  const parsedKeyType = ApiKeyTypeSchema.safeParse(row.key_type);
+  if (!parsedKeyType.success) return null;
+
+  // Check if revoked
+  if (row.revoked_at) {
+    return null;
+  }
+
+  // Check if expired
+  if (row.expires_at) {
+    const expiresAt = new Date(row.expires_at);
+    if (expiresAt < new Date()) {
+      return null;
+    }
+  }
+
+  // Update last_used_at
+  const now = new Date().toISOString();
+  await sql`
+    update ${sql.table('sync_api_keys')}
+    set last_used_at = ${now}
+    where key_id = ${row.key_id}
+  `.execute(db);
+
+  // Parse scopes
+  const scopeKeys = dialect.dbToArray(row.scope_keys);
+
+  return {
+    keyId: row.key_id,
+    keyType: parsedKeyType.data,
+    actorId: row.actor_id,
+    scopeKeys,
+  };
+}
+
+/**
+ * Creates an authenticator for relay/proxy routes.
+ * Returns actorId from the API key if valid and allowed.
+ */
+export function createApiKeyAuthenticator<DB extends ApiKeyDb>(
+  db: Kysely<DB>,
+  dialect: ServerSyncDialect,
+  allowedTypes: ApiKeyType[]
+): (c: Context) => Promise<{ actorId: string } | null> {
+  return async (c: Context) => {
+    const authHeader = c.req.header('Authorization');
+    const result = await validateApiKey(db, dialect, authHeader);
+
+    if (!result) {
+      return null;
+    }
+
+    // Check if key type is allowed
+    if (!allowedTypes.includes(result.keyType)) {
+      return null;
+    }
+
+    // Return actorId (use key's actorId if set, otherwise use a default)
+    return {
+      actorId: result.actorId ?? `api-key:${result.keyId}`,
+    };
+  };
+}
+
+/**
+ * Middleware that validates API key and attaches result to context.
+ */
+export function apiKeyAuthMiddleware<DB extends ApiKeyDb>(
+  db: Kysely<DB>,
+  dialect: ServerSyncDialect,
+  allowedTypes: ApiKeyType[]
+) {
+  return async (
+    c: Context,
+    next: () => Promise<void>
+  ): Promise<Response | undefined> => {
+    const authHeader = c.req.header('Authorization');
+    const result = await validateApiKey(db, dialect, authHeader);
+
+    if (!result) {
+      return syncError(c, 401, 'sync.auth_required');
+    }
+
+    if (!allowedTypes.includes(result.keyType)) {
+      return syncError(c, 403, 'sync.forbidden', 'Invalid key type');
+    }
+
+    // Attach to context for downstream handlers
+    c.set('apiKey', result);
+
+    await next();
+  };
+}
+
+// Hash function (same as in routes.ts)
+async function hashApiKey(secretKey: string): Promise<string> {
+  return sha256Hex(secretKey);
+}

package/src/hono/audit-redaction.ts

@@ -0,0 +1,135 @@
+import {
+  parseJsonValue,
+  SYNC_CRDT_CHECKPOINTS_TABLE,
+  SYNC_CRDT_UPDATES_TABLE,
+} from '@syncular/server';
+
+type AuditChangeKind =
+  | 'app_row'
+  | 'delete'
+  | 'blob_reference'
+  | 'encrypted_field_envelope'
+  | 'encrypted_crdt_update'
+  | 'encrypted_crdt_checkpoint';
+
+interface AuditChangeRedaction {
+  payload: 'omitted';
+  reason: 'audit_redacted_by_default';
+}
+
+interface AuditChangeSummary {
+  changeKind: AuditChangeKind;
+  fields: string[];
+  scopeFields: string[];
+  sensitiveFields: string[];
+  redaction: AuditChangeRedaction;
+}
+
+export function summarizeAuditChange(args: {
+  table: string;
+  op: 'upsert' | 'delete';
+  rowJson: unknown | null;
+  scopes: unknown;
+}): AuditChangeSummary {
+  const row = parseJsonRecord(args.rowJson);
+  const fields = Object.keys(row).sort();
+  const sensitiveFields = detectSensitiveFields(row);
+
+  return {
+    changeKind: classifyAuditChange({
+      table: args.table,
+      op: args.op,
+      row,
+      sensitiveFields,
+    }),
+    fields,
+    scopeFields: Object.keys(parseJsonRecord(args.scopes)).sort(),
+    sensitiveFields,
+    redaction: {
+      payload: 'omitted',
+      reason: 'audit_redacted_by_default',
+    },
+  };
+}
+
+function classifyAuditChange(args: {
+  table: string;
+  op: 'upsert' | 'delete';
+  row: Record<string, unknown>;
+  sensitiveFields: string[];
+}): AuditChangeKind {
+  if (args.table === SYNC_CRDT_UPDATES_TABLE) {
+    return 'encrypted_crdt_update';
+  }
+  if (args.table === SYNC_CRDT_CHECKPOINTS_TABLE) {
+    return 'encrypted_crdt_checkpoint';
+  }
+  if (args.op === 'delete') {
+    return 'delete';
+  }
+  if (args.sensitiveFields.some((field) => isEncryptedFieldName(field))) {
+    return 'encrypted_field_envelope';
+  }
+  if (args.sensitiveFields.length > 0) {
+    return 'blob_reference';
+  }
+  return 'app_row';
+}
+
+function detectSensitiveFields(row: Record<string, unknown>): string[] {
+  const sensitive = new Set<string>();
+
+  for (const [field, value] of Object.entries(row)) {
+    const parsed = parseJsonValue(value);
+    if (isEncryptedFieldName(field) || isEncryptedEnvelope(parsed)) {
+      sensitive.add(field);
+      continue;
+    }
+    if (isBlobRef(parsed)) {
+      sensitive.add(field);
+    }
+  }
+
+  return Array.from(sensitive).sort();
+}
+
+function parseJsonRecord(value: unknown): Record<string, unknown> {
+  const parsed = parseJsonValue(value);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {};
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function isBlobRef(value: unknown): boolean {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.hash === 'string' &&
+    record.hash.length > 0 &&
+    (typeof record.size === 'number' || typeof record.size === 'bigint')
+  );
+}
+
+function isEncryptedEnvelope(value: unknown): boolean {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.ciphertext === 'string' &&
+    (typeof record.key_id === 'string' || typeof record.keyId === 'string')
+  );
+}
+
+function isEncryptedFieldName(field: string): boolean {
+  return (
+    field === 'ciphertext' ||
+    field === 'key_id' ||
+    field === 'keyId' ||
+    field.endsWith('_encrypted') ||
+    field.endsWith('_ciphertext')
+  );
+}