@syncular/server 0.57.0 → 0.59.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/README.md +31 -22
  2. package/dist/admin.js +8 -4
  3. package/dist/blob-handlers.d.ts +25 -31
  4. package/dist/blob-handlers.js +63 -41
  5. package/dist/blob-store.d.ts +42 -24
  6. package/dist/blob-store.js +0 -0
  7. package/dist/bucket-blob-store.d.ts +12 -8
  8. package/dist/bucket-blob-store.js +54 -45
  9. package/dist/bucket-segment-store.js +18 -16
  10. package/dist/content-encoding.d.ts +5 -2
  11. package/dist/content-encoding.js +42 -13
  12. package/dist/context.d.ts +16 -0
  13. package/dist/context.js +21 -1
  14. package/dist/d1-storage.d.ts +14 -98
  15. package/dist/d1-storage.js +223 -1111
  16. package/dist/errors.js +8 -0
  17. package/dist/events.d.ts +1 -1
  18. package/dist/handler.js +135 -103
  19. package/dist/local-authority.d.ts +2 -0
  20. package/dist/local-authority.js +17 -3
  21. package/dist/object-bucket.d.ts +2 -0
  22. package/dist/operations-realtime.js +69 -50
  23. package/dist/pg-executor-pglite.d.ts +5 -6
  24. package/dist/pg-executor-pglite.js +22 -14
  25. package/dist/pg-executor.d.ts +4 -1
  26. package/dist/postgres-storage.d.ts +1 -1
  27. package/dist/postgres-storage.js +182 -105
  28. package/dist/pull.d.ts +28 -20
  29. package/dist/pull.js +85 -87
  30. package/dist/push.js +272 -147
  31. package/dist/realtime.d.ts +68 -28
  32. package/dist/realtime.js +297 -136
  33. package/dist/relational-rows.d.ts +27 -15
  34. package/dist/relational-rows.js +38 -22
  35. package/dist/s3-blob-store.d.ts +11 -12
  36. package/dist/s3-blob-store.js +20 -13
  37. package/dist/s3-object-bucket.d.ts +8 -1
  38. package/dist/s3-object-bucket.js +16 -3
  39. package/dist/schema.d.ts +14 -0
  40. package/dist/schema.js +23 -0
  41. package/dist/scopes.d.ts +6 -2
  42. package/dist/scopes.js +22 -4
  43. package/dist/seed.js +1 -2
  44. package/dist/segment-download.js +18 -4
  45. package/dist/signed-url.d.ts +2 -2
  46. package/dist/signed-url.js +9 -2
  47. package/dist/sigv4.d.ts +8 -2
  48. package/dist/sigv4.js +8 -4
  49. package/dist/sqlite-blob-store.d.ts +1 -1
  50. package/dist/sqlite-blob-store.js +23 -22
  51. package/dist/sqlite-dialect.d.ts +150 -47
  52. package/dist/sqlite-dialect.js +987 -88
  53. package/dist/sqlite-lease-store.js +13 -18
  54. package/dist/sqlite-storage.d.ts +9 -62
  55. package/dist/sqlite-storage.js +293 -1117
  56. package/dist/storage.d.ts +32 -12
  57. package/package.json +2 -2
  58. package/src/admin.ts +16 -2
  59. package/src/blob-handlers.ts +91 -72
  60. package/src/blob-store.ts +0 -0
  61. package/src/bucket-blob-store.ts +75 -48
  62. package/src/bucket-segment-store.ts +20 -15
  63. package/src/content-encoding.ts +48 -16
  64. package/src/context.ts +32 -1
  65. package/src/d1-storage.ts +326 -1692
  66. package/src/errors.ts +8 -0
  67. package/src/events.ts +1 -1
  68. package/src/handler.ts +178 -127
  69. package/src/local-authority.ts +17 -3
  70. package/src/object-bucket.ts +2 -0
  71. package/src/operations-realtime.ts +85 -61
  72. package/src/pg-executor-pglite.ts +27 -23
  73. package/src/pg-executor.ts +5 -1
  74. package/src/postgres-storage.ts +231 -138
  75. package/src/pull.ts +133 -147
  76. package/src/push.ts +356 -205
  77. package/src/realtime.ts +380 -179
  78. package/src/relational-rows.ts +54 -27
  79. package/src/s3-blob-store.ts +23 -13
  80. package/src/s3-object-bucket.ts +20 -2
  81. package/src/schema.ts +31 -0
  82. package/src/scopes.ts +23 -3
  83. package/src/seed.ts +1 -2
  84. package/src/segment-download.ts +25 -4
  85. package/src/signed-url.ts +10 -4
  86. package/src/sigv4.ts +17 -4
  87. package/src/sqlite-blob-store.ts +27 -26
  88. package/src/sqlite-dialect.ts +1607 -114
  89. package/src/sqlite-lease-store.ts +12 -23
  90. package/src/sqlite-storage.ts +360 -1811
  91. package/src/storage.ts +33 -12
@@ -169,13 +169,13 @@ export declare function dropIndexDdl(indexName: string): string;
169
169
  * (JSONB would reject the INSERT — the payload keeps the verbatim value);
170
170
  * - everything else binds naturally (Uint8Array → BLOB/BYTEA).
171
171
  */
172
- export declare function toSqlValue(column: RowColumn, value: RowValue, dialect: RelationalDialect): unknown;
172
+ export declare function toSqlValue(column: RowColumn, value: RowValue, dialect: RelationalDialect): RowValue;
173
173
  /**
174
174
  * Bind values for an upsert, in `tableColumnNames` order. Decodes the
175
175
  * payload once; the typed columns and the verbatim payload land in one
176
176
  * statement, so they cannot drift.
177
177
  */
178
- export declare function upsertValues(table: CompiledTable, partition: string, row: StoredRow, dialect: RelationalDialect): unknown[];
178
+ export declare function upsertValues(table: CompiledTable, partition: string, row: StoredRow, dialect: RelationalDialect): RowValue[];
179
179
  /**
180
180
  * Upsert statement text (bind with `upsertValues`). PostgreSQL takes `rows`
181
181
  * rows in one statement, bound as consecutive `upsertValues` lists; their
@@ -190,14 +190,15 @@ export declare function upsertSql(table: CompiledTable, dialect: RelationalDiale
190
190
  export declare function selectRowSql(table: CompiledTable, dialect: RelationalDialect): string;
191
191
  /**
192
192
  * SELECT many stored rows of one table by primary key in one statement.
193
- * Postgres binds the ids as one `text[]` (`row_id = ANY($2)`), so the
194
- * statement count does not grow with the id count. Params: [partition,
195
- * rowIds]; absent ids contribute no row.
193
+ * The ids bind as one parameter (Postgres `text[]` with `= ANY($2)`, SQLite
194
+ * a JSON array through `json_each`), so the statement count does not grow
195
+ * with the id count. Params: [partition, rowIds]; absent ids contribute no
196
+ * row.
196
197
  */
197
- export declare function selectRowsSql(table: CompiledTable): string;
198
+ export declare function selectRowsSql(table: CompiledTable, dialect: RelationalDialect): string;
198
199
  export interface IndexRowPageStatement {
199
200
  readonly sql: string;
200
- readonly params: readonly unknown[];
201
+ readonly params: readonly RowValue[];
201
202
  }
202
203
  /**
203
204
  * Bounded exact lookup through one declared relational index. Unlike
@@ -222,8 +223,11 @@ export declare function indexRowPageStatement(table: CompiledTable, index: Index
222
223
  * Bind order:
223
224
  * - postgres: [partition, tbl, var, ...values, afterRowId, limit]
224
225
  * (the join reuses `$1` for the partition);
225
- * - sqlite: [partition, tbl, var, ...values, afterRowId, limit,
226
- * partition] (positional `?` — the partition binds again for the join).
226
+ * - sqlite: [partition, tbl, var, values as JSON array text, afterRowId,
227
+ * limit, partition] (positional `?`; the partition binds again for the
228
+ * join). The values expand through `json_each`, so the statement text and
229
+ * parameter count do not depend on `valueCount` and D1's 100-parameter
230
+ * cap is unreachable through scope values.
227
231
  */
228
232
  export declare function scanRowPageSql(table: CompiledTable, valueCount: number, dialect: RelationalDialect): string;
229
233
  /**
@@ -250,9 +254,10 @@ export declare function scanRowPageSql(table: CompiledTable, valueCount: number,
250
254
  * Bind order:
251
255
  * - postgres: [partition, tbl, var, ...values, afterSeq, throughSeq,
252
256
  * limit] (the joins reuse `$1`/`$2`);
253
- * - sqlite: [partition, tbl, var, ...values, afterSeq, throughSeq,
254
- * limit, partition, partition, tbl] (positional `?` — partition/tbl bind
255
- * again for the joins).
257
+ * - sqlite: [partition, tbl, var, values as JSON array text, afterSeq,
258
+ * throughSeq, limit, partition, partition, tbl] (positional `?`;
259
+ * partition/tbl bind again for the joins). The values expand through
260
+ * `json_each` like `scanRowPageSql`.
256
261
  */
257
262
  export declare function commitWindowPageSql(valueCount: number, dialect: RelationalDialect): string;
258
263
  /**
@@ -307,8 +312,15 @@ export declare const LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL = "SELECT max((SELECT m
307
312
  * `{i, tbl, var, vals}` records. Params: [partition, specs (JSON text)].
308
313
  */
309
314
  export declare const LATEST_SCOPED_CHANGE_BATCH_SQL = "SELECT s.i AS sub,\n (SELECT max(latest.seq) FROM (\n SELECT (SELECT max(commit_seq) FROM sync_change_scopes\n WHERE partition=$1 AND tbl=s.tbl AND var=s.var AND value=v.value) AS seq\n FROM jsonb_array_elements_text(s.vals) AS v(value)) AS latest) AS seq\n FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, tbl text, var text, vals jsonb)\n ORDER BY s.i";
310
- /** SELECT a row's version + scope map (admin/blob authz). Params: [partition, rowId]. */
311
- export declare function selectRowScopesSql(table: CompiledTable, dialect: RelationalDialect): string;
315
+ /**
316
+ * SELECT the rows that reference one blob with their stored scope maps, in
317
+ * one statement for any number of references: the by-blob index range
318
+ * (§5.9.4) supplies the candidates and a `CASE` on the candidate's table
319
+ * name looks each scope map up by primary key in that table's own relation.
320
+ * A reference whose table left the schema or whose row is gone has NULL
321
+ * `scopes`. Needs at least one table. Params: [partition, blobId].
322
+ */
323
+ export declare function rowsReferencingBlobSql(tables: Iterable<CompiledTable>, dialect: RelationalDialect): string;
312
324
  /** DELETE one stored row. Params: [partition, rowId]. */
313
325
  export declare function deleteRowSql(table: CompiledTable, dialect: RelationalDialect): string;
314
326
  /**
@@ -385,7 +397,7 @@ export declare function selectRowsForRewriteSql(table: CompiledTable, dialect: R
385
397
  */
386
398
  export declare function rewriteRowSql(table: CompiledTable): string;
387
399
  /** Bind values for `rewriteRowSql` from the (already migrated) payload. */
388
- export declare function rewriteValues(table: CompiledTable, partition: string, rowId: string, payload: Uint8Array, dialect: RelationalDialect): unknown[];
400
+ export declare function rewriteValues(table: CompiledTable, partition: string, rowId: string, payload: Uint8Array, dialect: RelationalDialect): RowValue[];
389
401
  /**
390
402
  * What the migration rewrite phase must do for one table, derived from the
391
403
  * persisted layouts + the physical columns present before this run.
@@ -493,12 +493,16 @@ export function selectRowSql(table, dialect) {
493
493
  }
494
494
  /**
495
495
  * SELECT many stored rows of one table by primary key in one statement.
496
- * Postgres binds the ids as one `text[]` (`row_id = ANY($2)`), so the
497
- * statement count does not grow with the id count. Params: [partition,
498
- * rowIds]; absent ids contribute no row.
496
+ * The ids bind as one parameter (Postgres `text[]` with `= ANY($2)`, SQLite
497
+ * a JSON array through `json_each`), so the statement count does not grow
498
+ * with the id count. Params: [partition, rowIds]; absent ids contribute no
499
+ * row.
499
500
  */
500
- export function selectRowsSql(table) {
501
- return `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=$1 AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=ANY($2::text[])`;
501
+ export function selectRowsSql(table, dialect) {
502
+ const [partition, rowIds] = dialect === 'sqlite'
503
+ ? ['?', 'IN (SELECT value FROM json_each(?))']
504
+ : ['$1', '=ANY($2::text[])'];
505
+ return `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${partition} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}${rowIds}`;
502
506
  }
503
507
  /**
504
508
  * Bounded exact lookup through one declared relational index. Unlike
@@ -546,20 +550,23 @@ export function indexRowPageStatement(table, index, values, partition, afterRowI
546
550
  * Bind order:
547
551
  * - postgres: [partition, tbl, var, ...values, afterRowId, limit]
548
552
  * (the join reuses `$1` for the partition);
549
- * - sqlite: [partition, tbl, var, ...values, afterRowId, limit,
550
- * partition] (positional `?` — the partition binds again for the join).
553
+ * - sqlite: [partition, tbl, var, values as JSON array text, afterRowId,
554
+ * limit, partition] (positional `?`; the partition binds again for the
555
+ * join). The values expand through `json_each`, so the statement text and
556
+ * parameter count do not depend on `valueCount` and D1's 100-parameter
557
+ * cap is unreachable through scope values.
551
558
  */
552
559
  export function scanRowPageSql(table, valueCount, dialect) {
553
560
  const p = (n) => (dialect === 'sqlite' ? '?' : `$${n}`);
554
- const values = [];
555
- for (let i = 0; i < valueCount; i++)
556
- values.push(p(4 + i));
561
+ const values = dialect === 'sqlite'
562
+ ? 'SELECT value FROM json_each(?)'
563
+ : Array.from({ length: valueCount }, (_, i) => p(4 + i)).join(',');
557
564
  const after = p(4 + valueCount);
558
565
  const limit = p(5 + valueCount);
559
566
  const joinPartition = dialect === 'sqlite' ? '?' : '$1';
560
567
  return `SELECT c.row_id AS row_id, r.${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, r.${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, r.${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, r.${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions
561
568
  FROM (SELECT DISTINCT row_id FROM sync_row_scopes
562
- WHERE partition=${p(1)} AND tbl=${p(2)} AND var=${p(3)} AND value IN (${values.join(',')})
569
+ WHERE partition=${p(1)} AND tbl=${p(2)} AND var=${p(3)} AND value IN (${values})
563
570
  AND row_id>${after}
564
571
  ORDER BY row_id LIMIT ${limit}) c
565
572
  LEFT JOIN ${quoteIdent(table.name)} r
@@ -590,15 +597,16 @@ export function scanRowPageSql(table, valueCount, dialect) {
590
597
  * Bind order:
591
598
  * - postgres: [partition, tbl, var, ...values, afterSeq, throughSeq,
592
599
  * limit] (the joins reuse `$1`/`$2`);
593
- * - sqlite: [partition, tbl, var, ...values, afterSeq, throughSeq,
594
- * limit, partition, partition, tbl] (positional `?` — partition/tbl bind
595
- * again for the joins).
600
+ * - sqlite: [partition, tbl, var, values as JSON array text, afterSeq,
601
+ * throughSeq, limit, partition, partition, tbl] (positional `?`;
602
+ * partition/tbl bind again for the joins). The values expand through
603
+ * `json_each` like `scanRowPageSql`.
596
604
  */
597
605
  export function commitWindowPageSql(valueCount, dialect) {
598
606
  const p = (n) => (dialect === 'sqlite' ? '?' : `$${n}`);
599
- const values = [];
600
- for (let i = 0; i < valueCount; i++)
601
- values.push(p(4 + i));
607
+ const values = dialect === 'sqlite'
608
+ ? 'SELECT value FROM json_each(?)'
609
+ : Array.from({ length: valueCount }, (_, i) => p(4 + i)).join(',');
602
610
  const after = p(4 + valueCount);
603
611
  const through = p(5 + valueCount);
604
612
  const limit = p(6 + valueCount);
@@ -607,7 +615,7 @@ export function commitWindowPageSql(valueCount, dialect) {
607
615
  return `SELECT c.commit_seq AS commit_seq, m.actor_id AS actor_id, m.created_at_ms AS created_at_ms,
608
616
  ch.tbl AS tbl, ch.row_id AS row_id, ch.op AS op, ch.row_version AS row_version, ch.scopes AS scopes, ch.payload AS payload
609
617
  FROM (SELECT DISTINCT commit_seq FROM sync_change_scopes
610
- WHERE partition=${p(1)} AND tbl=${p(2)} AND var=${p(3)} AND value IN (${values.join(',')})
618
+ WHERE partition=${p(1)} AND tbl=${p(2)} AND var=${p(3)} AND value IN (${values})
611
619
  AND commit_seq>${after} AND commit_seq<=${through}
612
620
  ORDER BY commit_seq LIMIT ${limit}) c
613
621
  LEFT JOIN sync_commits m
@@ -690,7 +698,7 @@ export function prefetchRowsBatchSql(tables, params = {
690
698
  const projection = tables
691
699
  .map((table) => {
692
700
  const quoted = quoteIdent(table.name);
693
- return `SELECT ids.tbl AS tbl, ids.id AS lookup_id, r.${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, r.${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, r.${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, r.${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, r.${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions, t.commit_seq AS tombstone_seq
701
+ return `SELECT ids.tbl AS tbl, ids.id AS lookup_id, r.${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, r.${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, r.${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, r.${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, r.${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions, t.commit_seq AS tombstone_seq, t.server_version AS tombstone_version, t.scopes AS tombstone_scopes
694
702
  FROM ids
695
703
  LEFT JOIN ${quoted} r
696
704
  ON r.${quoteIdent(SYNC_PARTITION_COLUMN)}=${params.partition} AND r.${quoteIdent(SYNC_ROW_ID_COLUMN)}=ids.id
@@ -730,10 +738,18 @@ export const LATEST_SCOPED_CHANGE_BATCH_SQL = `SELECT s.i AS sub,
730
738
  FROM jsonb_array_elements_text(s.vals) AS v(value)) AS latest) AS seq
731
739
  FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, tbl text, var text, vals jsonb)
732
740
  ORDER BY s.i`;
733
- /** SELECT a row's version + scope map (admin/blob authz). Params: [partition, rowId]. */
734
- export function selectRowScopesSql(table, dialect) {
741
+ /**
742
+ * SELECT the rows that reference one blob with their stored scope maps, in
743
+ * one statement for any number of references: the by-blob index range
744
+ * (§5.9.4) supplies the candidates and a `CASE` on the candidate's table
745
+ * name looks each scope map up by primary key in that table's own relation.
746
+ * A reference whose table left the schema or whose row is gone has NULL
747
+ * `scopes`. Needs at least one table. Params: [partition, blobId].
748
+ */
749
+ export function rowsReferencingBlobSql(tables, dialect) {
735
750
  const p = dialect === 'sqlite' ? ['?', '?'] : ['$1', '$2'];
736
- return `SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${p[0]} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${p[1]}`;
751
+ const branches = [...tables].map((table) => `WHEN '${table.name.replaceAll("'", "''")}' THEN (SELECT t.${quoteIdent(SYNC_SCOPES_COLUMN)} FROM ${quoteIdent(table.name)} t WHERE t.${quoteIdent(SYNC_PARTITION_COLUMN)}=r.partition AND t.${quoteIdent(SYNC_ROW_ID_COLUMN)}=r.row_id)`);
752
+ return `SELECT r.tbl AS tbl, r.row_id AS row_id, CASE r.tbl ${branches.join(' ')} END AS scopes FROM sync_blob_refs r WHERE r.partition=${p[0]} AND r.blob_id=${p[1]}`;
737
753
  }
738
754
  /** DELETE one stored row. Params: [partition, rowId]. */
739
755
  export function deleteRowSql(table, dialect) {
@@ -48,17 +48,16 @@ export declare class S3BlobStore extends BucketBlobStore {
48
48
  }): Promise<SegmentUrlIssue>;
49
49
  /**
50
50
  * SigV4 presigned PUT for a blob object (§5.9.3 direct-to-storage upload).
51
- * The blob twin of `presignBlobGet`: the signed key embeds the `blobId`, so
52
- * the grant places bytes at exactly the content-addressed key. The store
53
- * does NOT recompute the SHA-256 (it is the object store, not the sync
54
- * server); integrity is enforced at REFERENCE time — the §5.9.6 push
55
- * existence check verifies the object exists (`has`) and every consumer
56
- * re-verifies the content address over the received bytes (§5.9.5/§5.1). A
57
- * client PUTting bytes that do not hash to `{blobId}` poisons only its own
58
- * upload; no honest reference resolves to it. Issued by the upload-grant
59
- * handler after host authentication; TTL SHOULD be ≤ 15 min (default 900).
51
+ * The signed key embeds the `blobId`, and the signature binds
52
+ * `content-length` to the granted `byteLength` and `x-amz-checksum-sha256`
53
+ * to the `blobId` digest (the same SHA-256, re-encoded from lowercase hex to
54
+ * the base64 of its 32 raw bytes). The object store therefore rejects a PUT
55
+ * of any other size (signature mismatch) or any other bytes (`BadDigest`),
56
+ * so a grant can only place the content-addressed bytes at their key.
57
+ * Issued by the upload-grant handler after host authentication and the
58
+ * size-cap check; TTL SHOULD be ≤ 15 min (default 900).
60
59
  */
61
- presignBlobPut(partition: string, blobId: string, options?: {
60
+ presignBlobPut(partition: string, blobId: string, byteLength: number, options?: {
62
61
  readonly ttlSeconds?: number;
63
62
  readonly nowMs?: number;
64
63
  }): Promise<SegmentUrlIssue>;
@@ -79,8 +78,8 @@ export declare function s3PresignedBlobUrls(store: S3BlobStore, options?: {
79
78
  * `blobUploadUrls: s3PresignedBlobUploads(blobStore, { ttlSeconds: 900 })`.
80
79
  * The upload-grant handler issues the presigned PUT only after host
81
80
  * authentication + the size-cap check; the client PUTs bytes straight to the
82
- * object store with no host auth (§5.9.3). Integrity stays the content-address
83
- * check at reference/download time — never a store-side hash recompute.
81
+ * object store with no host auth, and the store verifies the signed
82
+ * `content-length` and `x-amz-checksum-sha256` (§5.9.3).
84
83
  */
85
84
  export declare function s3PresignedBlobUploads(store: S3BlobStore, options?: {
86
85
  readonly ttlSeconds?: number;
@@ -60,22 +60,22 @@ export class S3BlobStore extends BucketBlobStore {
60
60
  }
61
61
  /**
62
62
  * SigV4 presigned PUT for a blob object (§5.9.3 direct-to-storage upload).
63
- * The blob twin of `presignBlobGet`: the signed key embeds the `blobId`, so
64
- * the grant places bytes at exactly the content-addressed key. The store
65
- * does NOT recompute the SHA-256 (it is the object store, not the sync
66
- * server); integrity is enforced at REFERENCE time — the §5.9.6 push
67
- * existence check verifies the object exists (`has`) and every consumer
68
- * re-verifies the content address over the received bytes (§5.9.5/§5.1). A
69
- * client PUTting bytes that do not hash to `{blobId}` poisons only its own
70
- * upload; no honest reference resolves to it. Issued by the upload-grant
71
- * handler after host authentication; TTL SHOULD be ≤ 15 min (default 900).
63
+ * The signed key embeds the `blobId`, and the signature binds
64
+ * `content-length` to the granted `byteLength` and `x-amz-checksum-sha256`
65
+ * to the `blobId` digest (the same SHA-256, re-encoded from lowercase hex to
66
+ * the base64 of its 32 raw bytes). The object store therefore rejects a PUT
67
+ * of any other size (signature mismatch) or any other bytes (`BadDigest`),
68
+ * so a grant can only place the content-addressed bytes at their key.
69
+ * Issued by the upload-grant handler after host authentication and the
70
+ * size-cap check; TTL SHOULD be ≤ 15 min (default 900).
72
71
  */
73
- async presignBlobPut(partition, blobId, options) {
72
+ async presignBlobPut(partition, blobId, byteLength, options) {
74
73
  if (!BLOB_ID_PATTERN.test(blobId)) {
75
74
  throw new Error(`S3BlobStore: malformed blobId ${blobId}`);
76
75
  }
77
76
  const ttlSeconds = options?.ttlSeconds ?? 900;
78
77
  const nowMs = options?.nowMs ?? Date.now();
78
+ const digest = (blobId.slice('sha256:'.length).match(/../g) ?? []).map((hex) => Number.parseInt(hex, 16));
79
79
  const url = await presignUrl({
80
80
  method: 'PUT',
81
81
  url: this.#bucket.urlFor(this.objectKeyFor(partition, blobId)),
@@ -83,6 +83,10 @@ export class S3BlobStore extends BucketBlobStore {
83
83
  credentials: this.#credentials,
84
84
  nowMs,
85
85
  expiresSeconds: ttlSeconds,
86
+ headers: {
87
+ 'content-length': String(byteLength),
88
+ 'x-amz-checksum-sha256': btoa(String.fromCharCode(...digest)),
89
+ },
86
90
  });
87
91
  return {
88
92
  url: url.toString(),
@@ -111,14 +115,17 @@ export function s3PresignedBlobUrls(store, options) {
111
115
  * `blobUploadUrls: s3PresignedBlobUploads(blobStore, { ttlSeconds: 900 })`.
112
116
  * The upload-grant handler issues the presigned PUT only after host
113
117
  * authentication + the size-cap check; the client PUTs bytes straight to the
114
- * object store with no host auth (§5.9.3). Integrity stays the content-address
115
- * check at reference/download time — never a store-side hash recompute.
118
+ * object store with no host auth, and the store verifies the signed
119
+ * `content-length` and `x-amz-checksum-sha256` (§5.9.3).
116
120
  */
117
121
  export function s3PresignedBlobUploads(store, options) {
118
122
  return {
119
123
  ...(options?.ttlSeconds !== undefined
120
124
  ? { ttlSeconds: options.ttlSeconds }
121
125
  : {}),
122
- presign: ({ partition, blobId, ttlSeconds, nowMs }) => store.presignBlobPut(partition, blobId, { ttlSeconds, nowMs }),
126
+ presign: ({ partition, blobId, byteLength, ttlSeconds, nowMs }) => store.presignBlobPut(partition, blobId, byteLength, {
127
+ ttlSeconds,
128
+ nowMs,
129
+ }),
123
130
  };
124
131
  }
@@ -29,7 +29,14 @@ export interface S3ObjectBucketConfig {
29
29
  export declare class S3ObjectBucket implements ObjectBucket {
30
30
  #private;
31
31
  constructor(config: S3ObjectBucketConfig);
32
- /** The object URL the presign helpers sign (`{endpoint}/{bucket}/{key}`). */
32
+ /**
33
+ * The object URL the presign helpers sign (`{endpoint}/{bucket}/{key}`).
34
+ * Every `/`-separated key segment is URI-encoded the way SigV4
35
+ * canonicalizes an S3 path (RFC 3986 unreserved characters stay raw), so a
36
+ * partition id holding `#`, `?`, `%` or `:` stays inside its own key and the
37
+ * pathname is already the canonical path. A `.` or `..` segment has no URL
38
+ * form (the URL parser and S3 clients collapse it), so it is refused.
39
+ */
33
40
  urlFor(key: string): URL;
34
41
  get(key: string): Promise<BucketObject | undefined>;
35
42
  head(key: string): Promise<BucketObjectHead | undefined>;
@@ -1,4 +1,4 @@
1
- import { EMPTY_PAYLOAD_SHA256, sha256Hex, signRequest, } from './sigv4.js';
1
+ import { EMPTY_PAYLOAD_SHA256, sha256Hex, signRequest, uriEncode, } from './sigv4.js';
2
2
  const META_HEADER_PREFIX = 'x-amz-meta-';
3
3
  /** User metadata carried as `x-amz-meta-*` headers (lowercased by `Headers`). */
4
4
  function metadataOf(headers) {
@@ -56,10 +56,21 @@ export class S3ObjectBucket {
56
56
  : {}),
57
57
  };
58
58
  }
59
- /** The object URL the presign helpers sign (`{endpoint}/{bucket}/{key}`). */
59
+ /**
60
+ * The object URL the presign helpers sign (`{endpoint}/{bucket}/{key}`).
61
+ * Every `/`-separated key segment is URI-encoded the way SigV4
62
+ * canonicalizes an S3 path (RFC 3986 unreserved characters stay raw), so a
63
+ * partition id holding `#`, `?`, `%` or `:` stays inside its own key and the
64
+ * pathname is already the canonical path. A `.` or `..` segment has no URL
65
+ * form (the URL parser and S3 clients collapse it), so it is refused.
66
+ */
60
67
  urlFor(key) {
61
68
  const endpoint = this.#config.endpoint.replace(/\/+$/, '');
62
- return new URL(`${endpoint}/${this.#config.bucket}/${key}`);
69
+ const segments = key.split('/');
70
+ if (segments.some((segment) => segment === '.' || segment === '..')) {
71
+ throw new Error('S3ObjectBucket: object key has a dot segment');
72
+ }
73
+ return new URL(`${endpoint}/${this.#config.bucket}/${segments.map((segment) => uriEncode(segment, true)).join('/')}`);
63
74
  }
64
75
  async #request(method, key, options) {
65
76
  const url = this.urlFor(key);
@@ -113,9 +124,11 @@ export class S3ObjectBucket {
113
124
  if (response === undefined)
114
125
  return undefined;
115
126
  await response.arrayBuffer();
127
+ const lastModified = Date.parse(response.headers.get('last-modified') ?? '');
116
128
  return {
117
129
  etag: response.headers.get('etag') ?? undefined,
118
130
  size: sizeOf(response.headers),
131
+ lastModifiedMs: Number.isNaN(lastModified) ? undefined : lastModified,
119
132
  metadata: metadataOf(response.headers),
120
133
  };
121
134
  }
package/dist/schema.d.ts CHANGED
@@ -146,4 +146,18 @@ export interface CompiledSchema {
146
146
  /** Union of scope variables declared by any table (§3.2 resolver check). */
147
147
  readonly declaredVariables: ReadonlySet<string>;
148
148
  }
149
+ /** A scope column has a type other than string or integer (§3.1). */
150
+ export declare class ScopeColumnTypeError extends Error {
151
+ readonly details: {
152
+ readonly table: string;
153
+ readonly column: string;
154
+ readonly type: string;
155
+ };
156
+ readonly code = "schema.scope_column_type";
157
+ constructor(details: {
158
+ readonly table: string;
159
+ readonly column: string;
160
+ readonly type: string;
161
+ });
162
+ }
149
163
  export declare function compileSchema(schema: ServerSchema): CompiledSchema;
package/dist/schema.js CHANGED
@@ -7,6 +7,16 @@
7
7
  */
8
8
  import { validatePortableRelationalIdentifier, } from '@syncular/core';
9
9
  const PATTERN_RE = /^([^{}]+):\{([^{}:]+)\}$/;
10
+ /** A scope column has a type other than string or integer (§3.1). */
11
+ export class ScopeColumnTypeError extends Error {
12
+ details;
13
+ code = 'schema.scope_column_type';
14
+ constructor(details) {
15
+ super('a scope column must have type string or integer (§3.1)');
16
+ this.details = details;
17
+ this.name = 'ScopeColumnTypeError';
18
+ }
19
+ }
10
20
  /**
11
21
  * Compile one `prefix:{variable}` scope pattern against the table's column
12
22
  * list, resolving the scope column's positional index for row extraction.
@@ -24,6 +34,14 @@ function compilePattern(table, spec, columnIndex) {
24
34
  if (index === undefined) {
25
35
  throw new Error(`table ${table.name}: scope pattern ${JSON.stringify(pattern)} names unknown column ${JSON.stringify(column)}`);
26
36
  }
37
+ const type = table.columns[index]?.type;
38
+ if (type !== 'string' && type !== 'integer') {
39
+ throw new ScopeColumnTypeError({
40
+ table: table.name,
41
+ column,
42
+ type: type ?? 'undefined',
43
+ });
44
+ }
27
45
  return { variable, prefix, column, columnIndex: index };
28
46
  }
29
47
  const compiledCache = new WeakMap();
@@ -190,6 +208,11 @@ export function compileSchema(schema) {
190
208
  if (parent === undefined) {
191
209
  throw new Error(`table ${child.name}: reference column ${JSON.stringify(reference.column)} names unknown table ${JSON.stringify(reference.parentTable)}`);
192
210
  }
211
+ if (!child.materialize) {
212
+ // Enforcement reaches children through `scanRowsByIndex`, which reads
213
+ // the materialized columns.
214
+ throw new Error('a declared reference requires a materialized child table (§6.11)');
215
+ }
193
216
  const childColumn = child.columns[reference.columnIndex];
194
217
  const parentKey = parent.columns[parent.primaryKeyIndex];
195
218
  if (childColumn === undefined || parentKey === undefined) {
package/dist/scopes.d.ts CHANGED
@@ -20,10 +20,14 @@ export type EffectiveOutcome = {
20
20
  readonly status: 'revoked';
21
21
  };
22
22
  /**
23
- * Effective = requested ∩ allowed per §3.2 rules 4–5. Inputs are assumed
23
+ * Effective = requested ∩ allowed per §3.2 rules 4–6. Inputs are assumed
24
24
  * key-validated (requested keys declared, no `'*'` requested values).
25
+ * `declared` is the table's declared variables: when a requested key passes
26
+ * through an allowed `'*'`, every declared variable the request omits and
27
+ * the actor holds a non-wildcard list for joins effective with that list
28
+ * (rule 4), so the wildcard never lifts the actor's other fences.
25
29
  */
26
- export declare function computeEffective(requested: ScopeMap, resolved: ResolvedScopes): EffectiveOutcome;
30
+ export declare function computeEffective(declared: ReadonlySet<string>, requested: ScopeMap, resolved: ResolvedScopes): EffectiveOutcome;
27
31
  /** Render a stored scope column value; `undefined` means missing/empty. */
28
32
  export declare function renderScopeValue(value: RowValue | undefined): string | undefined;
29
33
  /**
package/dist/scopes.js CHANGED
@@ -5,21 +5,26 @@
5
5
  */
6
6
  import { canonicalScopeJson, } from '@syncular/core';
7
7
  /**
8
- * Effective = requested ∩ allowed per §3.2 rules 4–5. Inputs are assumed
8
+ * Effective = requested ∩ allowed per §3.2 rules 4–6. Inputs are assumed
9
9
  * key-validated (requested keys declared, no `'*'` requested values).
10
+ * `declared` is the table's declared variables: when a requested key passes
11
+ * through an allowed `'*'`, every declared variable the request omits and
12
+ * the actor holds a non-wildcard list for joins effective with that list
13
+ * (rule 4), so the wildcard never lifts the actor's other fences.
10
14
  */
11
- export function computeEffective(requested, resolved) {
15
+ export function computeEffective(declared, requested, resolved) {
12
16
  if (!resolved.ok)
13
17
  return { status: 'revoked' };
14
18
  const effective = {};
15
- const requestedKeys = Object.keys(requested);
16
- for (const key of requestedKeys) {
19
+ let wildcard = false;
20
+ for (const key of Object.keys(requested)) {
17
21
  const requestedValues = requested[key] ?? [];
18
22
  const allowedValues = resolved.allowed[key];
19
23
  if (allowedValues === undefined)
20
24
  return { status: 'revoked' };
21
25
  let values;
22
26
  if (allowedValues.includes('*')) {
27
+ wildcard = true;
23
28
  values = [...requestedValues];
24
29
  }
25
30
  else {
@@ -31,6 +36,19 @@ export function computeEffective(requested, resolved) {
31
36
  }
32
37
  if (Object.keys(effective).length === 0)
33
38
  return { status: 'revoked' };
39
+ if (wildcard) {
40
+ for (const variable of declared) {
41
+ const allowedValues = resolved.allowed[variable];
42
+ if (Object.hasOwn(requested, variable) ||
43
+ allowedValues === undefined ||
44
+ allowedValues.includes('*')) {
45
+ continue;
46
+ }
47
+ if (allowedValues.length === 0)
48
+ return { status: 'revoked' };
49
+ effective[variable] = [...allowedValues];
50
+ }
51
+ }
34
52
  return { status: 'active', effective };
35
53
  }
36
54
  /** Render a stored scope column value; `undefined` means missing/empty. */
package/dist/seed.js CHANGED
@@ -131,8 +131,7 @@ export async function seedMutations(config, target, mutations) {
131
131
  }), requestContext));
132
132
  const acquisitionHeader = acquisition.frames[0];
133
133
  if (acquisition.msgKind !== 'response' ||
134
- acquisitionHeader?.type !== 'RESP_HEADER' ||
135
- acquisitionHeader.logEpoch === undefined) {
134
+ acquisitionHeader?.type !== 'RESP_HEADER') {
136
135
  throw new SyncError('sync.invalid_request', 'seedMutations: epoch acquisition returned an invalid response');
137
136
  }
138
137
  const frames = [
@@ -161,14 +161,28 @@ async function authorizePublication(ctx, request, logEpoch, stored) {
161
161
  }
162
162
  resolved = { ok: false };
163
163
  }
164
- const outcome = computeEffective(requested, resolved);
165
- if (outcome.status !== 'active') {
164
+ // §3.2: the effective scopes, and so the digest, depend on the declared
165
+ // variables of the publication's table (the wildcard fence).
166
+ const digests = new Map();
167
+ for (const publication of inContext) {
168
+ const key = `${publication.schemaVersion}\u0000${publication.table}`;
169
+ if (digests.has(key))
170
+ continue;
171
+ const table = schemaWindowOf(ctx.schema, ctx.schemaWindow)
172
+ .find((candidate) => candidate.version === publication.schemaVersion)
173
+ ?.tables.get(publication.table);
174
+ const outcome = computeEffective(table?.declaredVariables ?? new Set(), requested, resolved);
175
+ digests.set(key, outcome.status === 'active'
176
+ ? await scopeDigest(outcome.effective)
177
+ : undefined);
178
+ }
179
+ if ([...digests.values()].every((digest) => digest === undefined)) {
166
180
  throw syncError('sync.forbidden', 'segment scopes not held (§5.5)');
167
181
  }
168
- const digest = await scopeDigest(outcome.effective);
169
182
  // The digest is the grant, but only inside the caller's partition and live
170
183
  // epoch: identical bytes published elsewhere never authorize this caller.
171
- const forDigest = inContext.filter((publication) => publication.scopeDigest === digest);
184
+ const forDigest = inContext.filter((publication) => digests.get(`${publication.schemaVersion}\u0000${publication.table}`) ===
185
+ publication.scopeDigest);
172
186
  if (forDigest.length === 0) {
173
187
  throw syncError('sync.forbidden', 'scope digest mismatch (§3.5, §5.5)');
174
188
  }
@@ -87,8 +87,8 @@ export declare function issueBlobUrl(config: BlobPresignConfig, args: {
87
87
  * twin of `BlobPresignConfig`: the provider signs a single PUT whose object
88
88
  * key embeds the `blobId`. Issuance happens ONLY after host authentication in
89
89
  * the upload-grant handler (uploading is host-auth-only, not scope-bearing —
90
- * §5.9.3). The `byteLength` rides through so a provider MAY bind
91
- * `Content-Length` (S3 conditional) to the granted size. Never a multipart or
90
+ * §5.9.3). The provider MUST bind the PUT to the granted `byteLength` and to
91
+ * the content address, so the object store rejects other bytes. Never a multipart or
92
92
  * chunk protocol — single PUT only, this rung and the next (§5.9.3 non-goal).
93
93
  * `S3BlobStore.presignBlobPut` (via `s3PresignedBlobUploads`) is the in-tree
94
94
  * implementation.
@@ -120,8 +120,15 @@ export async function verifySegmentToken(key, token, expected) {
120
120
  const dot = token.indexOf('.');
121
121
  if (dot < 0)
122
122
  throw forbidden('malformed token');
123
- const payload = fromBase64url(token.slice(0, dot));
124
- const mac = fromBase64url(token.slice(dot + 1));
123
+ let payload;
124
+ let mac;
125
+ try {
126
+ payload = fromBase64url(token.slice(0, dot));
127
+ mac = fromBase64url(token.slice(dot + 1));
128
+ }
129
+ catch {
130
+ throw forbidden('malformed token');
131
+ }
125
132
  const computed = await hmac(key, payload);
126
133
  if (!constantTimeEqual(mac, computed))
127
134
  throw forbidden('bad MAC');
package/dist/sigv4.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Minimal AWS Signature Version 4 — exactly the subset the S3 segment
3
- * store needs (header-signed requests and presigned GET URLs), hand-rolled
3
+ * and blob stores need (header-signed requests and presigned URLs), hand-rolled
4
4
  * per the dependency-light doctrine: SigV4 is small and
5
5
  * well-specified, so no SDK.
6
6
  *
@@ -90,6 +90,12 @@ export interface PresignArgs {
90
90
  readonly credentials: SigV4Credentials;
91
91
  readonly nowMs: number;
92
92
  readonly expiresSeconds: number;
93
+ /**
94
+ * Headers the request must carry with exactly these values, signed beside
95
+ * `host` (a presigned PUT binds `content-length` and
96
+ * `x-amz-checksum-sha256`, so the store rejects other bytes).
97
+ */
98
+ readonly headers?: Readonly<Record<string, string>>;
93
99
  }
94
- /** Query-authenticated (presigned) URL; only the `host` header is signed. */
100
+ /** Query-authenticated (presigned) URL over `host` plus `headers`. */
95
101
  export declare function presignUrl(args: PresignArgs): Promise<URL>;