@syncular/server 0.1.2 → 0.2.0

package/src/signed-url.ts

@@ -0,0 +1,308 @@
+/**
+ * Signed-URL segment delivery (SPEC.md §5.4): the native HMAC token
+ * scheme, plus the delegated-presign alternative (S3/R2/GCS) behind one
+ * issuance seam.
+ *
+ * Native: `st = base64url(payloadJson) + "." +
+ * base64url(HMAC-SHA256(key, payloadJson))` with claims
+ * `{v, seg, sd, aud, exp}`; `exp` is unix seconds. Issuance happens inside
+ * the pull immediately after scope resolution; verification checks MAC,
+ * expiry (≤ 60 s skew), and `seg`/`sd`/`aud` equality. Actual CDN serving
+ * is out of scope.
+ *
+ * Delegated presign: the provider mints the URL (§5.4 equivalence rule —
+ * the signed object key embeds the `segmentId`, the expiry obeys the same
+ * TTL guidance); `issueSegmentUrl` routes to whichever config the host
+ * supplied. Both paths issue only after scope resolution, so a URL is
+ * never minted for scopes the actor did not hold at that moment.
+ */
+import { syncError } from './errors';
+
+export interface SignedUrlConfig {
+  /** HMAC key (raw bytes or UTF-8 string). */
+  readonly key: string | Uint8Array;
+  /** URL prefix; the segment URL is `${baseUrl}/${segmentId}?st=${token}`. */
+  readonly baseUrl: string;
+  /** Token TTL; SHOULD be ≤ 15 minutes (§5.4). Default 900. */
+  readonly ttlSeconds?: number;
+  /**
+   * Opaque per-partition audience (§5.4): stable per partition, MUST NOT
+   * disclose the internal partition id.
+   */
+  readonly audience: (partition: string) => string;
+}
+
+/** What descriptor emission needs: the §5.4 `url`/`urlExpiresAtMs` pair. */
+export interface SegmentUrlIssue {
+  readonly url: string;
+  readonly urlExpiresAtMs: number;
+}
+
+export interface SegmentPresignArgs {
+  readonly segmentId: string;
+  readonly partition: string;
+  readonly scopeDigest: string;
+  readonly nowMs: number;
+  /** Resolved TTL (config value or the 900 s default) — already applied. */
+  readonly ttlSeconds: number;
+}
+
+/**
+ * Delegated presign (§5.4): the provider signs the URL. The callback MUST
+ * satisfy the equivalence rule — the signed object key embeds exactly one
+ * `segmentId`, and `urlExpiresAtMs` reflects the real provider expiry.
+ * `S3SegmentStore.presignSegmentGet` (via `s3PresignedUrls`) is the
+ * in-tree implementation.
+ */
+export interface DelegatedPresignConfig {
+  readonly presign: (
+    args: SegmentPresignArgs,
+  ) => SegmentUrlIssue | Promise<SegmentUrlIssue>;
+  /** URL TTL; SHOULD be ≤ 15 minutes (§5.4). Default 900. */
+  readonly ttlSeconds?: number;
+}
+
+/** Either §5.4 scheme; the pull emits descriptors identically for both. */
+export type SegmentUrlConfig = SignedUrlConfig | DelegatedPresignConfig;
+
+/**
+ * Issue the §5.4 `url`/`urlExpiresAtMs` pair for one segment descriptor,
+ * routing to the native HMAC token or the delegated presigner. Callers
+ * (the pull) invoke this only after scope resolution and only when the
+ * client advertised accept bit 3.
+ */
+export async function issueSegmentUrl(
+  config: SegmentUrlConfig,
+  args: {
+    readonly segmentId: string;
+    readonly partition: string;
+    readonly scopeDigest: string;
+    readonly nowMs: number;
+  },
+): Promise<SegmentUrlIssue> {
+  const ttlSeconds = config.ttlSeconds ?? 900;
+  if ('presign' in config) {
+    return config.presign({ ...args, ttlSeconds });
+  }
+  const exp = Math.floor(args.nowMs / 1000) + ttlSeconds;
+  const token = await signSegmentToken(config.key, {
+    v: 1,
+    seg: args.segmentId,
+    sd: args.scopeDigest,
+    aud: config.audience(args.partition),
+    exp,
+  });
+  return {
+    url: `${config.baseUrl}/${args.segmentId}?st=${token}`,
+    urlExpiresAtMs: exp * 1000,
+  };
+}
+
+/**
+ * Delegated presign for BLOB downloads (§5.9.5). The blob twin of
+ * `DelegatedPresignConfig`: the provider signs the URL and the signed object
+ * key embeds the `blobId`. Issuance happens ONLY after the §5.9.5
+ * row-derived authorization check (never before), so the URL is a short-TTL
+ * bearer grant to exactly those immutable bytes — the SPEC's "authorization
+ * was resolved against the referencing rows at issuance". Unlike segments,
+ * there is no native-HMAC blob token scheme wired this rung; presign is the
+ * shipped path (`S3BlobStore.presignBlobGet` via `s3PresignedBlobUrls`).
+ */
+export interface BlobPresignArgs {
+  readonly partition: string;
+  readonly blobId: string;
+  readonly nowMs: number;
+  /** Resolved TTL (config value or the 900 s default) — already applied. */
+  readonly ttlSeconds: number;
+}
+
+export interface BlobPresignConfig {
+  readonly presign: (
+    args: BlobPresignArgs,
+  ) => SegmentUrlIssue | Promise<SegmentUrlIssue>;
+  /** URL TTL; SHOULD be ≤ 15 minutes (§5.9.5). Default 900. */
+  readonly ttlSeconds?: number;
+}
+
+/**
+ * Issue the §5.9.5 `url`/`urlExpiresAtMs` pair for one blob download. The
+ * caller (blob-handlers `downloadBlob`) invokes this only after the
+ * row-derived authorization check passes.
+ */
+export async function issueBlobUrl(
+  config: BlobPresignConfig,
+  args: {
+    readonly partition: string;
+    readonly blobId: string;
+    readonly nowMs: number;
+  },
+): Promise<SegmentUrlIssue> {
+  const ttlSeconds = config.ttlSeconds ?? 900;
+  return config.presign({ ...args, ttlSeconds });
+}
+
+/**
+ * Delegated presign for BLOB UPLOADS (§5.9.3 direct-to-storage). The upload
+ * twin of `BlobPresignConfig`: the provider signs a single PUT whose object
+ * key embeds the `blobId`. Issuance happens ONLY after host authentication in
+ * the upload-grant handler (uploading is host-auth-only, not scope-bearing —
+ * §5.9.3). The `byteLength` rides through so a provider MAY bind
+ * `Content-Length` (S3 conditional) to the granted size. Never a multipart or
+ * chunk protocol — single PUT only, this rung and the next (§5.9.3 non-goal).
+ * `S3BlobStore.presignBlobPut` (via `s3PresignedBlobUploads`) is the in-tree
+ * implementation.
+ */
+export interface BlobUploadPresignArgs {
+  readonly partition: string;
+  readonly blobId: string;
+  readonly byteLength: number;
+  readonly nowMs: number;
+  /** Resolved TTL (config value or the 900 s default) — already applied. */
+  readonly ttlSeconds: number;
+}
+
+export interface BlobUploadPresignConfig {
+  readonly presign: (
+    args: BlobUploadPresignArgs,
+  ) => SegmentUrlIssue | Promise<SegmentUrlIssue>;
+  /** URL TTL; SHOULD be ≤ 15 minutes (§5.9.3). Default 900. */
+  readonly ttlSeconds?: number;
+}
+
+/**
+ * Issue the §5.9.3 `url`/`urlExpiresAtMs` pair for one presigned blob upload.
+ * The caller (blob-handlers `handleBlobUploadGrant`) invokes this only after
+ * host authentication and the size-cap check against the declared byteLength.
+ */
+export async function issueBlobUploadUrl(
+  config: BlobUploadPresignConfig,
+  args: {
+    readonly partition: string;
+    readonly blobId: string;
+    readonly byteLength: number;
+    readonly nowMs: number;
+  },
+): Promise<SegmentUrlIssue> {
+  const ttlSeconds = config.ttlSeconds ?? 900;
+  return config.presign({ ...args, ttlSeconds });
+}
+
+export interface SegmentTokenClaims {
+  readonly v: 1;
+  readonly seg: string;
+  readonly sd: string;
+  readonly aud: string;
+  /** Unix seconds — the sole non-millisecond timestamp in the spec. */
+  readonly exp: number;
+}
+
+const encoder = new TextEncoder();
+
+// Runtime-neutral base64url (no `Buffer` — Workers/Deno/browser safe; TODO
+// §4.2): `btoa`/`atob` operate on binary strings, present in every runtime.
+function base64url(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/=+$/, '');
+}
+
+function fromBase64url(text: string): Uint8Array {
+  const binary = atob(text.replaceAll('-', '+').replaceAll('_', '/'));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+async function hmac(
+  key: string | Uint8Array,
+  payload: Uint8Array,
+): Promise<Uint8Array> {
+  const keyBytes = typeof key === 'string' ? encoder.encode(key) : key;
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    keyBytes.slice().buffer as ArrayBuffer,
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  const mac = await crypto.subtle.sign(
+    'HMAC',
+    cryptoKey,
+    payload.slice().buffer as ArrayBuffer,
+  );
+  return new Uint8Array(mac);
+}
+
+function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  return diff === 0;
+}
+
+export async function signSegmentToken(
+  key: string | Uint8Array,
+  claims: SegmentTokenClaims,
+): Promise<string> {
+  const payloadJson = JSON.stringify({
+    v: claims.v,
+    seg: claims.seg,
+    sd: claims.sd,
+    aud: claims.aud,
+    exp: claims.exp,
+  });
+  const payload = encoder.encode(payloadJson);
+  const mac = await hmac(key, payload);
+  return `${base64url(payload)}.${base64url(mac)}`;
+}
+
+const DEFAULT_SKEW_SECONDS = 60;
+
+/**
+ * Verify a segment token per §5.4. Throws `SyncError sync.forbidden` on any
+ * failure (MAC, expiry, or claim mismatch).
+ */
+export async function verifySegmentToken(
+  key: string | Uint8Array,
+  token: string,
+  expected: {
+    readonly segmentId: string;
+    readonly scopeDigest: string;
+    readonly audience: string;
+    readonly nowMs: number;
+    readonly skewSeconds?: number;
+  },
+): Promise<SegmentTokenClaims> {
+  const forbidden = (reason: string) =>
+    syncError('sync.forbidden', `segment token rejected: ${reason}`);
+  const dot = token.indexOf('.');
+  if (dot < 0) throw forbidden('malformed token');
+  const payload = fromBase64url(token.slice(0, dot));
+  const mac = fromBase64url(token.slice(dot + 1));
+  const computed = await hmac(key, payload);
+  if (!constantTimeEqual(mac, computed)) throw forbidden('bad MAC');
+  let claims: SegmentTokenClaims;
+  try {
+    claims = JSON.parse(
+      new TextDecoder().decode(payload),
+    ) as SegmentTokenClaims;
+  } catch {
+    throw forbidden('unparseable claims');
+  }
+  if (claims.v !== 1) throw forbidden('unsupported token version');
+  const skew = expected.skewSeconds ?? DEFAULT_SKEW_SECONDS;
+  if (
+    typeof claims.exp !== 'number' ||
+    claims.exp < expected.nowMs / 1000 - skew
+  ) {
+    throw forbidden('token expired');
+  }
+  if (claims.seg !== expected.segmentId) throw forbidden('segment mismatch');
+  if (claims.sd !== expected.scopeDigest)
+    throw forbidden('scope-digest mismatch');
+  if (claims.aud !== expected.audience) throw forbidden('audience mismatch');
+  return claims;
+}

package/src/sigv4.ts

@@ -0,0 +1,267 @@
+/**
+ * Minimal AWS Signature Version 4 — exactly the subset the S3 segment
+ * store needs (header-signed requests and presigned GET URLs), hand-rolled
+ * per the dependency-light doctrine (REVISE): SigV4 is small and
+ * well-specified, so no SDK.
+ *
+ * Runtime-neutral (TODO §4.2): the crypto primitives are Web Crypto
+ * (`crypto.subtle`), not `node:crypto`, so this module runs unchanged on
+ * Cloudflare Workers / Deno / browsers as well as Bun/Node. `crypto.subtle`
+ * is async, so signing is async throughout; the `S3SegmentStore` consumers
+ * are already async, and the `DelegatedPresignConfig.presign` seam already
+ * accepts a `Promise<SegmentUrlIssue>`.
+ *
+ * Pinned by the published AWS SigV4 example vectors in
+ * `test/sigv4.test.ts`; the hermetic S3 stub re-derives every signature
+ * from the incoming request, so an asymmetric signing bug fails tests.
+ */
+
+export interface SigV4Credentials {
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+  /** Optional STS session token (signed as `x-amz-security-token`). */
+  readonly sessionToken?: string;
+}
+
+/** Hex SHA-256 of an empty body — the payload hash for GET/HEAD/DELETE. */
+export const EMPTY_PAYLOAD_SHA256 =
+  'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
+
+/** The presigned-URL payload sentinel (S3 presigns never hash the body). */
+export const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
+
+const textEncoder = new TextEncoder();
+
+function toBytes(data: Uint8Array | string): Uint8Array {
+  return typeof data === 'string' ? textEncoder.encode(data) : data;
+}
+
+function toHex(bytes: Uint8Array): string {
+  let out = '';
+  for (const b of bytes) out += b.toString(16).padStart(2, '0');
+  return out;
+}
+
+/** Web Crypto wants an `ArrayBuffer`; slice() gives an owned, exact-length one. */
+function bufferOf(bytes: Uint8Array): ArrayBuffer {
+  return bytes.slice().buffer as ArrayBuffer;
+}
+
+export async function sha256Hex(data: Uint8Array | string): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', bufferOf(toBytes(data)));
+  return toHex(new Uint8Array(digest));
+}
+
+async function hmacSha256(
+  key: Uint8Array | string,
+  data: string,
+): Promise<Uint8Array> {
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    bufferOf(toBytes(key)),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  const mac = await crypto.subtle.sign(
+    'HMAC',
+    cryptoKey,
+    bufferOf(toBytes(data)),
+  );
+  return new Uint8Array(mac);
+}
+
+/**
+ * AWS canonical URI-encoding: RFC 3986 unreserved characters only —
+ * stricter than `encodeURIComponent` (which leaves `!'()*` alone).
+ */
+export function uriEncode(value: string, encodeSlash: boolean): string {
+  const encoded = encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+  return encodeSlash ? encoded : encoded.replaceAll('%2F', '/');
+}
+
+/** `YYYYMMDD'T'HHMMSS'Z'` plus its date-only prefix, from epoch ms. */
+export function amzTimestamps(nowMs: number): {
+  amzDate: string;
+  dateStamp: string;
+} {
+  const iso = new Date(nowMs).toISOString();
+  const amzDate = `${iso.slice(0, 4)}${iso.slice(5, 7)}${iso.slice(8, 10)}T${iso.slice(11, 13)}${iso.slice(14, 16)}${iso.slice(17, 19)}Z`;
+  return { amzDate, dateStamp: amzDate.slice(0, 8) };
+}
+
+/** Sorted, fully re-encoded canonical query string from *decoded* pairs. */
+export function canonicalQuery(
+  params: Iterable<readonly [string, string]>,
+): string {
+  return [...params]
+    .map(([k, v]) => [uriEncode(k, true), uriEncode(v, true)] as const)
+    .sort(([ak, av], [bk, bv]) =>
+      ak < bk ? -1 : ak > bk ? 1 : av < bv ? -1 : av > bv ? 1 : 0,
+    )
+    .map(([k, v]) => `${k}=${v}`)
+    .join('&');
+}
+
+export interface CanonicalRequestArgs {
+  readonly method: string;
+  /** The URI-encoded absolute path exactly as sent on the request line. */
+  readonly canonicalPath: string;
+  /** Decoded query pairs; `X-Amz-Signature` must already be excluded. */
+  readonly query: Iterable<readonly [string, string]>;
+  /** Only the headers being signed (name → raw value). */
+  readonly headers: Readonly<Record<string, string>>;
+  readonly payloadHash: string;
+}
+
+export function canonicalRequest(args: CanonicalRequestArgs): {
+  text: string;
+  signedHeaders: string;
+} {
+  const entries = Object.entries(args.headers)
+    .map(
+      ([name, value]) =>
+        [name.toLowerCase(), value.trim().replace(/\s+/g, ' ')] as const,
+    )
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const signedHeaders = entries.map(([name]) => name).join(';');
+  const text = [
+    args.method.toUpperCase(),
+    args.canonicalPath,
+    canonicalQuery(args.query),
+    ...entries.map(([name, value]) => `${name}:${value}`),
+    '',
+    signedHeaders,
+    args.payloadHash,
+  ].join('\n');
+  return { text, signedHeaders };
+}
+
+export async function stringToSign(
+  amzDate: string,
+  scope: string,
+  canonicalRequestText: string,
+): Promise<string> {
+  return `AWS4-HMAC-SHA256\n${amzDate}\n${scope}\n${await sha256Hex(canonicalRequestText)}`;
+}
+
+export async function sigV4Signature(args: {
+  readonly secretAccessKey: string;
+  readonly dateStamp: string;
+  readonly region: string;
+  readonly service: string;
+  readonly stringToSign: string;
+}): Promise<string> {
+  const kDate = await hmacSha256(`AWS4${args.secretAccessKey}`, args.dateStamp);
+  const kRegion = await hmacSha256(kDate, args.region);
+  const kService = await hmacSha256(kRegion, args.service);
+  const kSigning = await hmacSha256(kService, 'aws4_request');
+  return toHex(await hmacSha256(kSigning, args.stringToSign));
+}
+
+export interface SignRequestArgs {
+  readonly method: string;
+  /** Full request URL (host is taken from here and always signed). */
+  readonly url: URL;
+  readonly region: string;
+  /** Defaults to `s3`. */
+  readonly service?: string;
+  readonly credentials: SigV4Credentials;
+  readonly nowMs: number;
+  /** Hex SHA-256 of the request body (`EMPTY_PAYLOAD_SHA256` if none). */
+  readonly payloadHash: string;
+  /** Extra headers to send *and* sign (e.g. content-type, x-amz-meta-*). */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Headers for a header-authenticated request: the caller's headers plus
+ * `x-amz-date`, `x-amz-content-sha256`, optional `x-amz-security-token`,
+ * and `authorization`. `host` is signed but not returned — fetch derives
+ * it from the URL.
+ */
+export async function signRequest(
+  args: SignRequestArgs,
+): Promise<Record<string, string>> {
+  const service = args.service ?? 's3';
+  const { amzDate, dateStamp } = amzTimestamps(args.nowMs);
+  const added: Record<string, string> = {
+    'x-amz-content-sha256': args.payloadHash,
+    'x-amz-date': amzDate,
+    ...(args.credentials.sessionToken !== undefined
+      ? { 'x-amz-security-token': args.credentials.sessionToken }
+      : {}),
+  };
+  const { text, signedHeaders } = canonicalRequest({
+    method: args.method,
+    canonicalPath: args.url.pathname,
+    query: args.url.searchParams,
+    headers: { ...args.headers, ...added, host: args.url.host },
+    payloadHash: args.payloadHash,
+  });
+  const scope = `${dateStamp}/${args.region}/${service}/aws4_request`;
+  const signature = await sigV4Signature({
+    secretAccessKey: args.credentials.secretAccessKey,
+    dateStamp,
+    region: args.region,
+    service,
+    stringToSign: await stringToSign(amzDate, scope, text),
+  });
+  return {
+    ...args.headers,
+    ...added,
+    authorization: `AWS4-HMAC-SHA256 Credential=${args.credentials.accessKeyId}/${scope},SignedHeaders=${signedHeaders},Signature=${signature}`,
+  };
+}
+
+export interface PresignArgs {
+  /** Defaults to `GET`. */
+  readonly method?: string;
+  /** Object URL without any `X-Amz-*` query parameters. */
+  readonly url: URL;
+  readonly region: string;
+  /** Defaults to `s3`. */
+  readonly service?: string;
+  readonly credentials: SigV4Credentials;
+  readonly nowMs: number;
+  readonly expiresSeconds: number;
+}
+
+/** Query-authenticated (presigned) URL; only the `host` header is signed. */
+export async function presignUrl(args: PresignArgs): Promise<URL> {
+  const service = args.service ?? 's3';
+  const method = args.method ?? 'GET';
+  const { amzDate, dateStamp } = amzTimestamps(args.nowMs);
+  const scope = `${dateStamp}/${args.region}/${service}/aws4_request`;
+  const url = new URL(args.url);
+  url.searchParams.set('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+  url.searchParams.set(
+    'X-Amz-Credential',
+    `${args.credentials.accessKeyId}/${scope}`,
+  );
+  url.searchParams.set('X-Amz-Date', amzDate);
+  url.searchParams.set('X-Amz-Expires', String(args.expiresSeconds));
+  url.searchParams.set('X-Amz-SignedHeaders', 'host');
+  if (args.credentials.sessionToken !== undefined) {
+    url.searchParams.set('X-Amz-Security-Token', args.credentials.sessionToken);
+  }
+  const { text } = canonicalRequest({
+    method,
+    canonicalPath: url.pathname,
+    query: url.searchParams,
+    headers: { host: url.host },
+    payloadHash: UNSIGNED_PAYLOAD,
+  });
+  const signature = await sigV4Signature({
+    secretAccessKey: args.credentials.secretAccessKey,
+    dateStamp,
+    region: args.region,
+    service,
+    stringToSign: await stringToSign(amzDate, scope, text),
+  });
+  url.searchParams.set('X-Amz-Signature', signature);
+  return url;
+}

package/src/sqlite-blob-store.ts

@@ -0,0 +1,125 @@
+/**
+ * SQLite-backed blob store via `bun:sqlite` (dev/bench convenience,
+ * dependency-free). Bun-specific by design (top-level `bun:sqlite` import),
+ * so it lives in its own module — the runtime-neutral `BlobStore` interface,
+ * `MemoryBlobStore`, `blobIdFor`, and `isBlobId` stay in `blob-store.ts` for
+ * the Workers/edge core (TODO §4.2 neutrality discipline; enforced by
+ * `test/runtime-neutrality.test.ts`).
+ */
+import { Database } from 'bun:sqlite';
+import type { BlobRecord, BlobStore, BlobStoreStats } from './blob-store';
+
+export class SqliteBlobStore implements BlobStore {
+  readonly db: Database;
+
+  constructor(db: Database | string = ':memory:') {
+    this.db = typeof db === 'string' ? new Database(db) : db;
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sync_blobs(
+        partition TEXT NOT NULL, blob_id TEXT NOT NULL,
+        byte_length INTEGER NOT NULL, media_type TEXT,
+        created_at_ms INTEGER NOT NULL, bytes BLOB NOT NULL,
+        PRIMARY KEY (partition, blob_id)
+      );
+    `);
+  }
+
+  async put(
+    partition: string,
+    blobId: string,
+    bytes: Uint8Array,
+    nowMs: number,
+    mediaType?: string,
+  ): Promise<BlobRecord> {
+    const existing = await this.get(partition, blobId);
+    if (existing !== undefined) return existing.record;
+    const record: BlobRecord = {
+      blobId,
+      partition,
+      byteLength: bytes.length,
+      ...(mediaType !== undefined ? { mediaType } : {}),
+      createdAtMs: nowMs,
+    };
+    this.db
+      .query(
+        `INSERT OR IGNORE INTO sync_blobs(
+          partition, blob_id, byte_length, media_type, created_at_ms, bytes
+        ) VALUES (?,?,?,?,?,?)`,
+      )
+      .run(partition, blobId, bytes.length, mediaType ?? null, nowMs, bytes);
+    return record;
+  }
+
+  async has(partition: string, blobId: string): Promise<boolean> {
+    const row = this.db
+      .query<{ n: number }, [string, string]>(
+        'SELECT 1 AS n FROM sync_blobs WHERE partition=? AND blob_id=?',
+      )
+      .get(partition, blobId);
+    return row !== null;
+  }
+
+  async get(
+    partition: string,
+    blobId: string,
+  ): Promise<{ record: BlobRecord; bytes: Uint8Array } | undefined> {
+    const row = this.db
+      .query<
+        {
+          byte_length: number;
+          media_type: string | null;
+          created_at_ms: number;
+          bytes: Uint8Array;
+        },
+        [string, string]
+      >(
+        `SELECT byte_length, media_type, created_at_ms, bytes
+         FROM sync_blobs WHERE partition=? AND blob_id=?`,
+      )
+      .get(partition, blobId);
+    if (row === null) return undefined;
+    return {
+      record: {
+        blobId,
+        partition,
+        byteLength: row.byte_length,
+        ...(row.media_type !== null ? { mediaType: row.media_type } : {}),
+        createdAtMs: row.created_at_ms,
+      },
+      bytes: new Uint8Array(row.bytes),
+    };
+  }
+
+  async sweepOrphans(
+    partition: string,
+    olderThanMs: number,
+    referencedBlobIds: ReadonlySet<string>,
+  ): Promise<string[]> {
+    const candidates = this.db
+      .query<{ blob_id: string }, [string, number]>(
+        `SELECT blob_id FROM sync_blobs
+         WHERE partition=? AND created_at_ms < ?`,
+      )
+      .all(partition, olderThanMs);
+    const swept: string[] = [];
+    const del = this.db.query(
+      'DELETE FROM sync_blobs WHERE partition=? AND blob_id=?',
+    );
+    for (const { blob_id } of candidates) {
+      if (!referencedBlobIds.has(blob_id)) {
+        del.run(partition, blob_id);
+        swept.push(blob_id);
+      }
+    }
+    return swept;
+  }
+
+  async stats(partition: string): Promise<BlobStoreStats> {
+    const row = this.db
+      .query<{ count: number; bytes: number | null }, [string]>(
+        'SELECT count(*) AS count, sum(byte_length) AS bytes FROM sync_blobs WHERE partition=?',
+      )
+      .get(partition);
+    return { count: row?.count ?? 0, bytes: row?.bytes ?? 0 };
+  }
+}