@syncular/server 0.1.3 → 0.2.0

package/src/scopes.ts

@@ -0,0 +1,127 @@
+/**
+ * Scope semantics (SPEC.md §3) — requested ∩ allowed intersection,
+ * revocation, stored-scope extraction, write-path authorization, and the
+ * §3.5 scope digest.
+ */
+import {
+  canonicalScopeJson,
+  type RowValue,
+  type ScopeMap,
+} from '@syncular/core';
+import type { CompiledTable } from './schema';
+
+export type StoredScopes = Record<string, string>;
+
+/** Outcome of resolving the host's allowed scopes once per request (§3.4). */
+export type ResolvedScopes =
+  | { readonly ok: true; readonly allowed: ScopeMap }
+  | { readonly ok: false };
+
+export type EffectiveOutcome =
+  | { readonly status: 'active'; readonly effective: ScopeMap }
+  | { readonly status: 'revoked' };
+
+/**
+ * Effective = requested ∩ allowed per §3.2 rules 4–5. Inputs are assumed
+ * key-validated (requested keys declared, no `'*'` requested values).
+ */
+export function computeEffective(
+  requested: ScopeMap,
+  resolved: ResolvedScopes,
+): EffectiveOutcome {
+  if (!resolved.ok) return { status: 'revoked' };
+  const effective: ScopeMap = {};
+  const requestedKeys = Object.keys(requested);
+  for (const key of requestedKeys) {
+    const requestedValues = requested[key] ?? [];
+    const allowedValues = resolved.allowed[key];
+    if (allowedValues === undefined) return { status: 'revoked' };
+    let values: string[];
+    if (allowedValues.includes('*')) {
+      values = [...requestedValues];
+    } else {
+      values = requestedValues.filter((v) => allowedValues.includes(v));
+    }
+    if (values.length === 0) return { status: 'revoked' };
+    effective[key] = values;
+  }
+  if (Object.keys(effective).length === 0) return { status: 'revoked' };
+  return { status: 'active', effective };
+}
+
+/** Render a stored scope column value; `undefined` means missing/empty. */
+export function renderScopeValue(
+  value: RowValue | undefined,
+): string | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (value instanceof Uint8Array) return undefined;
+  const rendered = typeof value === 'string' ? value : String(value);
+  return rendered.length === 0 ? undefined : rendered;
+}
+
+/**
+ * Extract the stored scopes (§3.1) from a decoded row. Returns the missing
+ * variable name when a declared scope column is absent or empty.
+ */
+export function storedScopesForRow(
+  table: CompiledTable,
+  values: readonly RowValue[],
+): { scopes: StoredScopes } | { missing: string } {
+  const scopes: StoredScopes = {};
+  for (const pattern of table.scopePatterns) {
+    const value = renderScopeValue(values[pattern.columnIndex]);
+    if (value === undefined) return { missing: pattern.variable };
+    scopes[pattern.variable] = value;
+  }
+  return { scopes };
+}
+
+/**
+ * Write-path authorization (§3.4 steps 2–3): every declared variable's
+ * stored value must be present and allowed (or the allowed list holds
+ * `'*'`). All declared keys are required — there is no partial pass.
+ */
+export function authorizeWrite(
+  table: CompiledTable,
+  rowScopes: StoredScopes,
+  resolved: ResolvedScopes,
+): boolean {
+  if (!resolved.ok) return false;
+  for (const pattern of table.scopePatterns) {
+    const value = rowScopes[pattern.variable];
+    if (value === undefined || value.length === 0) return false;
+    const allowedValues = resolved.allowed[pattern.variable];
+    if (allowedValues === undefined) return false;
+    if (!allowedValues.includes('*') && !allowedValues.includes(value)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Does a change's stored scopes match the effective scopes (§3.2)? */
+export function matchesEffective(
+  storedScopes: StoredScopes,
+  effective: ScopeMap,
+): boolean {
+  for (const [variable, values] of Object.entries(effective)) {
+    const stored = storedScopes[variable];
+    if (stored === undefined || !values.includes(stored)) return false;
+  }
+  return true;
+}
+
+export async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    bytes.slice().buffer as ArrayBuffer,
+  );
+  return [...new Uint8Array(digest)]
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/** §3.5: SHA-256 over the canonical JSON of the effective-scope map. */
+export async function scopeDigest(effective: ScopeMap): Promise<string> {
+  return sha256Hex(new TextEncoder().encode(canonicalScopeJson(effective)));
+}

package/src/segment-download.ts

@@ -0,0 +1,169 @@
+/**
+ * Direct segment download with re-authorization (SPEC.md §5.5).
+ *
+ * A segment reference is not a bearer capability: every download re-runs
+ * `resolveScopes`, recomputes the effective scopes from the supplied
+ * `X-Syncular-Scopes` requested map, recomputes the scope digest, and
+ * compares it with the segment's stored digest. Mismatch, revoked status,
+ * or resolution failure ⇒ `sync.forbidden`.
+ */
+import type { ScopeMap } from '@syncular/core';
+import type { SyncRequestContext } from './context';
+import { clockOf, RESOLVER_OUTAGE } from './context';
+import { SyncError, syncError } from './errors';
+import { emitEvent } from './events';
+import { compileSchema } from './schema';
+import { computeEffective, type ResolvedScopes, scopeDigest } from './scopes';
+import type { SegmentRecord } from './segment-store';
+
+export interface SegmentDownloadRequest {
+  readonly segmentId: string;
+  /** The `X-Syncular-Scopes` header: canonical JSON of the requested map. */
+  readonly scopesHeader: string;
+}
+
+export interface SegmentDownloadResult {
+  readonly record: SegmentRecord;
+  readonly bytes: Uint8Array;
+  /** Response headers per §5.5. */
+  readonly headers: Record<string, string>;
+}
+
+function parseScopesHeader(header: string): ScopeMap {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(header);
+  } catch {
+    throw syncError('sync.invalid_request', 'X-Syncular-Scopes is not JSON');
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw syncError('sync.invalid_request', 'X-Syncular-Scopes must be a map');
+  }
+  const scopes: ScopeMap = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (
+      !Array.isArray(value) ||
+      value.some((v: unknown) => typeof v !== 'string')
+    ) {
+      throw syncError(
+        'sync.invalid_request',
+        'X-Syncular-Scopes values must be string lists (§0)',
+      );
+    }
+    scopes[key] = value as string[];
+  }
+  return scopes;
+}
+
+export async function handleSegmentDownload(
+  ctx: SyncRequestContext,
+  request: SegmentDownloadRequest,
+): Promise<SegmentDownloadResult> {
+  const events = ctx.events;
+  if (events === undefined) return downloadSegment(ctx, request);
+  const clock = clockOf(ctx);
+  const startedAtMs = clock();
+  try {
+    const result = await downloadSegment(ctx, request);
+    emitEvent(events, {
+      type: 'segment.downloaded',
+      atMs: clock(),
+      partition: ctx.partition,
+      actorId: ctx.actorId,
+      segmentId: request.segmentId,
+      outcome: 'ok',
+      mediaType: result.record.mediaType,
+      bytes: result.bytes.length,
+      durationMs: clock() - startedAtMs,
+    });
+    return result;
+  } catch (error) {
+    emitEvent(events, {
+      type: 'segment.downloaded',
+      atMs: clock(),
+      partition: ctx.partition,
+      actorId: ctx.actorId,
+      segmentId: request.segmentId,
+      outcome: 'error',
+      errorCode: error instanceof SyncError ? error.code : 'internal',
+      durationMs: clock() - startedAtMs,
+    });
+    throw error;
+  }
+}
+
+async function downloadSegment(
+  ctx: SyncRequestContext,
+  request: SegmentDownloadRequest,
+): Promise<SegmentDownloadResult> {
+  const entry = await ctx.segments.get(request.segmentId);
+  if (entry === undefined || entry.record.partition !== ctx.partition) {
+    throw syncError('sync.not_found', 'unknown segment (§5.5)');
+  }
+  if (entry.record.expiresAtMs <= clockOf(ctx)()) {
+    throw syncError(
+      'sync.segment_expired',
+      'segment TTL elapsed — re-pull to mint fresh descriptors (§5.1)',
+    );
+  }
+
+  const schema = compileSchema(ctx.schema);
+  const table = schema.tables.get(entry.record.table);
+  if (table === undefined) {
+    throw syncError('sync.not_found', 'segment table no longer served');
+  }
+  const requested = parseScopesHeader(request.scopesHeader);
+  for (const [key, values] of Object.entries(requested)) {
+    if (!table.declaredVariables.has(key) || values.includes('*')) {
+      throw syncError(
+        'sync.invalid_subscription',
+        'invalid requested scopes (§3.2)',
+      );
+    }
+  }
+
+  let resolved: ResolvedScopes;
+  try {
+    const allowed = await ctx.resolveScopes({
+      partition: ctx.partition,
+      actorId: ctx.actorId,
+    });
+    // §7.3.3: leases authorize sync rounds, never downloads — an outage
+    // signal here denies (re-authorization needs live scopes, §5.5).
+    resolved =
+      allowed === RESOLVER_OUTAGE ? { ok: false } : { ok: true, allowed };
+  } catch (error) {
+    const events = ctx.events;
+    if (events !== undefined) {
+      emitEvent(events, {
+        type: 'scopes.resolve_failed',
+        atMs: clockOf(ctx)(),
+        partition: ctx.partition,
+        actorId: ctx.actorId,
+        phase: 'segment-download',
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+    resolved = { ok: false };
+  }
+  const outcome = computeEffective(requested, resolved);
+  if (outcome.status !== 'active') {
+    throw syncError('sync.forbidden', 'segment scopes not held (§5.5)');
+  }
+  const digest = await scopeDigest(outcome.effective);
+  if (digest !== entry.record.scopeDigest) {
+    throw syncError('sync.forbidden', 'scope digest mismatch (§3.5, §5.5)');
+  }
+
+  return {
+    record: entry.record,
+    bytes: entry.bytes,
+    headers: {
+      'Content-Type': 'application/octet-stream',
+      ETag: `"${entry.record.segmentId}"`,
+      'Cache-Control': 'private, max-age=0',
+      // Accept-Encoding: the body may be served compressed (§5.8).
+      Vary: 'Authorization, X-Syncular-Scopes, Accept-Encoding',
+    },
+  };
+}

package/src/segment-store.ts

@@ -0,0 +1,154 @@
+/**
+ * Content-addressed segment store (SPEC.md §5.1).
+ *
+ * Segments are cache entries, not durable state: identical bytes share one
+ * `segmentId` (`"sha256:" + hex`), entries expire on a TTL (default 24 h),
+ * and `get` returns expired records so the download path can distinguish
+ * `sync.segment_expired` from `sync.not_found` (§5.5).
+ */
+import { sha256Hex } from './scopes';
+
+export const DEFAULT_SEGMENT_TTL_MS = 24 * 60 * 60 * 1000;
+
+export interface SegmentMetadata {
+  readonly partition: string;
+  readonly table: string;
+  readonly schemaVersion: number;
+  readonly mediaType: 'rows' | 'sqlite';
+  readonly scopeDigest: string;
+  readonly asOfCommitSeq: number;
+  readonly rowCount: number;
+  readonly rowCursor: string | null;
+  readonly nextRowCursor: string | null;
+}
+
+export interface SegmentRecord extends SegmentMetadata {
+  readonly segmentId: string;
+  readonly byteLength: number;
+  readonly createdAtMs: number;
+  readonly expiresAtMs: number;
+}
+
+/**
+ * The §5.3 reuse key: sqlite images are not byte-deterministic, so
+ * cross-client dedup is a metadata lookup, not hash convergence — one
+ * stored image per (partition, table, schemaVersion, scope digest, pin).
+ */
+export interface SegmentFindKey {
+  readonly partition: string;
+  readonly table: string;
+  readonly schemaVersion: number;
+  readonly mediaType: 'rows' | 'sqlite';
+  readonly scopeDigest: string;
+  readonly asOfCommitSeq: number;
+}
+
+/**
+ * Coarse store-level counters for the admin/console read surface (TODO
+ * §2.5). Optional — a store that omits `stats()` simply cannot report them.
+ * All counts include expired-but-not-yet-evicted entries (the store's own
+ * bytes on disk), split by media type.
+ */
+export interface SegmentStoreStats {
+  readonly count: number;
+  readonly bytes: number;
+  readonly rowsSegments: number;
+  readonly sqliteSegments: number;
+  /**
+   * ADDITIVE marker — present and `true` only on stores whose counters are
+   * approximate (the S3/R2 store's LIST-free pointer accumulator, which can
+   * drift under concurrent writers or after lifecycle GC). Absent on the
+   * exact in-process stores (memory/sqlite). The admin surface carries it
+   * through so the console can label the numbers honestly.
+   */
+  readonly approximate?: boolean;
+}
+
+export interface SegmentStore {
+  put(
+    metadata: SegmentMetadata,
+    bytes: Uint8Array,
+    nowMs: number,
+  ): Promise<SegmentRecord>;
+  /** Returns expired records too — expiry is the caller's check (§5.5). */
+  get(
+    segmentId: string,
+  ): Promise<{ record: SegmentRecord; bytes: Uint8Array } | undefined>;
+  /**
+   * Unexpired record for the §5.3 reuse key (whole-table segments only:
+   * `rowCursor` null), or undefined. Servers MUST reuse instead of
+   * rebuilding sqlite images while one exists (§5.3).
+   */
+  find(key: SegmentFindKey, nowMs: number): Promise<SegmentRecord | undefined>;
+  /** Admin/console counters (TODO §2.5) — ADDITIVE, optional. */
+  stats?(): Promise<SegmentStoreStats>;
+}
+
+export async function segmentIdFor(bytes: Uint8Array): Promise<string> {
+  return `sha256:${await sha256Hex(bytes)}`;
+}
+
+export class MemorySegmentStore implements SegmentStore {
+  #ttlMs: number;
+  #entries = new Map<string, { record: SegmentRecord; bytes: Uint8Array }>();
+
+  constructor(options?: { ttlMs?: number }) {
+    this.#ttlMs = options?.ttlMs ?? DEFAULT_SEGMENT_TTL_MS;
+  }
+
+  async put(
+    metadata: SegmentMetadata,
+    bytes: Uint8Array,
+    nowMs: number,
+  ): Promise<SegmentRecord> {
+    const segmentId = await segmentIdFor(bytes);
+    const record: SegmentRecord = {
+      ...metadata,
+      segmentId,
+      byteLength: bytes.length,
+      createdAtMs: nowMs,
+      expiresAtMs: nowMs + this.#ttlMs,
+    };
+    this.#entries.set(segmentId, { record, bytes });
+    return record;
+  }
+
+  async get(
+    segmentId: string,
+  ): Promise<{ record: SegmentRecord; bytes: Uint8Array } | undefined> {
+    return this.#entries.get(segmentId);
+  }
+
+  async find(
+    key: SegmentFindKey,
+    nowMs: number,
+  ): Promise<SegmentRecord | undefined> {
+    for (const { record } of this.#entries.values()) {
+      if (
+        record.partition === key.partition &&
+        record.table === key.table &&
+        record.schemaVersion === key.schemaVersion &&
+        record.mediaType === key.mediaType &&
+        record.scopeDigest === key.scopeDigest &&
+        record.asOfCommitSeq === key.asOfCommitSeq &&
+        record.rowCursor === null &&
+        record.expiresAtMs > nowMs
+      ) {
+        return record;
+      }
+    }
+    return undefined;
+  }
+
+  async stats(): Promise<SegmentStoreStats> {
+    let bytes = 0;
+    let rowsSegments = 0;
+    let sqliteSegments = 0;
+    for (const { record } of this.#entries.values()) {
+      bytes += record.byteLength;
+      if (record.mediaType === 'sqlite') sqliteSegments += 1;
+      else rowsSegments += 1;
+    }
+    return { count: this.#entries.size, bytes, rowsSegments, sqliteSegments };
+  }
+}