@syncular/server 0.73.0 → 0.75.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.
package/dist/admin.d.ts CHANGED
@@ -478,18 +478,21 @@ export declare class SyncularAdmin {
478
478
  * Trace whether one client receives one row, combining the row's stored
479
479
  * scopes and newest change with the client's units, cursor, the
480
480
  * actor's allowed scopes, and its retained push failures. See
481
- * `AdminTraceVerdict` for the verdict order.
481
+ * `AdminTraceVerdict` for the verdict order. `context` is the
482
+ * authentication context (§1.1) to resolve the actor's scopes under.
482
483
  */
483
484
  traceRow(partition: string, query: {
484
485
  readonly table: string;
485
486
  readonly rowId: string;
486
487
  readonly clientId: string;
488
+ readonly context?: string;
487
489
  }): Promise<AdminRowTrace>;
488
490
  /**
489
491
  * Who has one row and who does not: the trace verdict for every known
490
- * client in the partition, resolving each actor's allowed scopes once.
492
+ * client in the partition, resolving each actor's allowed scopes once
493
+ * under `context` (§1.1).
491
494
  */
492
- rowDelivery(partition: string, table: string, rowId: string): Promise<AdminRowDelivery>;
495
+ rowDelivery(partition: string, table: string, rowId: string, context?: string): Promise<AdminRowDelivery>;
493
496
  /**
494
497
  * The partition's actors with their devices (clients), open sockets,
495
498
  * worst lag, and failures in the last 5 minutes; most recently seen
package/dist/admin.js CHANGED
@@ -322,10 +322,11 @@ export class SyncularAdmin {
322
322
  * Trace whether one client receives one row, combining the row's stored
323
323
  * scopes and newest change with the client's units, cursor, the
324
324
  * actor's allowed scopes, and its retained push failures. See
325
- * `AdminTraceVerdict` for the verdict order.
325
+ * `AdminTraceVerdict` for the verdict order. `context` is the
326
+ * authentication context (§1.1) to resolve the actor's scopes under.
326
327
  */
327
328
  async traceRow(partition, query) {
328
- const { table, rowId, clientId } = query;
329
+ const { table, rowId, clientId, context } = query;
329
330
  const row = await this.inspectRow(partition, table, rowId, {
330
331
  historyLimit: 1,
331
332
  });
@@ -345,7 +346,7 @@ export class SyncularAdmin {
345
346
  if (record === undefined) {
346
347
  return { ...base, verdict: 'client-unknown', units: [] };
347
348
  }
348
- const allowed = await this.#allowedScopes(partition, record);
349
+ const allowed = await this.#allowedScopes(partition, record, context);
349
350
  return {
350
351
  ...base,
351
352
  client: (await this.#clientView(partition))(record),
@@ -355,9 +356,10 @@ export class SyncularAdmin {
355
356
  }
356
357
  /**
357
358
  * Who has one row and who does not: the trace verdict for every known
358
- * client in the partition, resolving each actor's allowed scopes once.
359
+ * client in the partition, resolving each actor's allowed scopes once
360
+ * under `context` (§1.1).
359
361
  */
360
- async rowDelivery(partition, table, rowId) {
362
+ async rowDelivery(partition, table, rowId, context) {
361
363
  const list = required(this.#storage.listClientRecords?.bind(this.#storage), 'storage');
362
364
  const row = await this.inspectRow(partition, table, rowId, {
363
365
  historyLimit: 1,
@@ -370,7 +372,7 @@ export class SyncularAdmin {
370
372
  const clients = [];
371
373
  for (const record of await list(partition)) {
372
374
  if (!allowedByActor.has(record.actorId)) {
373
- allowedByActor.set(record.actorId, await this.#allowedScopes(partition, record));
375
+ allowedByActor.set(record.actorId, await this.#allowedScopes(partition, record, context));
374
376
  }
375
377
  clients.push({
376
378
  client: view(record),
@@ -945,13 +947,14 @@ export class SyncularAdmin {
945
947
  };
946
948
  }
947
949
  /** The actor's allowed scopes from the host resolver, if one is wired. */
948
- async #allowedScopes(partition, record) {
950
+ async #allowedScopes(partition, record, context) {
949
951
  if (this.#resolveScopes === undefined)
950
952
  return undefined;
951
953
  const resolved = await this.#resolveScopes({
952
954
  partition,
953
955
  actorId: record.actorId,
954
956
  clientId: record.clientId,
957
+ ...(context !== undefined ? { context } : {}),
955
958
  });
956
959
  return resolved === RESOLVER_OUTAGE ? 'outage' : resolved;
957
960
  }
@@ -138,6 +138,7 @@ async function downloadBlob(ctx, blobId) {
138
138
  const allowed = await ctx.resolveScopes({
139
139
  partition: ctx.partition,
140
140
  actorId: ctx.actorId,
141
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
141
142
  });
142
143
  // §7.3.3: leases never authorize a blob download — an outage denies.
143
144
  resolved =
@@ -187,6 +188,7 @@ async function downloadBlob(ctx, blobId) {
187
188
  partition: ctx.partition,
188
189
  blobId,
189
190
  nowMs: clockOf(ctx)(),
191
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
190
192
  });
191
193
  return {
192
194
  headers: {
package/dist/context.d.ts CHANGED
@@ -30,6 +30,12 @@ export interface ResolveScopesArgs {
30
30
  * actor + scopes only (§5.5, §5.9.5) and never consult a lease.
31
31
  */
32
32
  readonly clientId?: string;
33
+ /**
34
+ * The authentication context the host's `authenticate` returned for this
35
+ * request (§1.1), passed unchanged on every path that resolves scopes.
36
+ * Absent when the host returned none.
37
+ */
38
+ readonly context?: string;
33
39
  }
34
40
  /**
35
41
  * Sentinel a resolver returns to signal a **live-authorization outage**
@@ -216,6 +222,18 @@ export interface SyncServerConfig {
216
222
  export interface SyncRequestContext extends SyncServerConfig {
217
223
  readonly partition: string;
218
224
  readonly actorId: string;
225
+ /** The host authentication context (§1.1), at most 256 UTF-8 bytes. */
226
+ readonly context?: string;
227
+ }
228
+ /** §1.1: `authenticate` returned a context longer than 256 UTF-8 bytes. */
229
+ export declare class AuthContextTooLargeError extends Error {
230
+ readonly name = "AuthContextTooLargeError";
231
+ readonly code = "sync.auth_context_too_large";
232
+ readonly details: {
233
+ readonly byteLength: number;
234
+ readonly max: 256;
235
+ };
236
+ constructor(byteLength: number);
219
237
  }
220
238
  export declare function clockOf(ctx: SyncServerConfig): () => number;
221
239
  /**
@@ -224,5 +242,9 @@ export declare function clockOf(ctx: SyncServerConfig): () => number;
224
242
  * `inlineSegmentMaxBytes` is a threshold and may be `0` (inline nothing).
225
243
  */
226
244
  export declare function limitsOf(ctx: SyncServerConfig): ServerLimits;
227
- /** Refresh the registry after host authentication and return log continuity. */
245
+ /**
246
+ * Refresh the registry after host authentication and return log continuity.
247
+ * Every authenticated entry point runs this first, so it also refuses an
248
+ * oversized authentication context (§1.1) before any resolver sees it.
249
+ */
228
250
  export declare function touchAuthenticatedPartition(ctx: SyncRequestContext): Promise<PartitionRegistryEntry>;
package/dist/context.js CHANGED
@@ -24,6 +24,16 @@ export const DEFAULT_LIMITS = {
24
24
  // The live section is buffered whole before the first unit section.
25
25
  maxLiveSectionBytes: 16 * 1024 * 1024,
26
26
  };
27
+ /** §1.1: `authenticate` returned a context longer than 256 UTF-8 bytes. */
28
+ export class AuthContextTooLargeError extends Error {
29
+ name = 'AuthContextTooLargeError';
30
+ code = 'sync.auth_context_too_large';
31
+ details;
32
+ constructor(byteLength) {
33
+ super('authentication context exceeds 256 UTF-8 bytes');
34
+ this.details = { byteLength, max: 256 };
35
+ }
36
+ }
27
37
  export function clockOf(ctx) {
28
38
  return ctx.clock ?? Date.now;
29
39
  }
@@ -42,7 +52,16 @@ export function limitsOf(ctx) {
42
52
  }
43
53
  return limits;
44
54
  }
45
- /** Refresh the registry after host authentication and return log continuity. */
46
- export function touchAuthenticatedPartition(ctx) {
55
+ /**
56
+ * Refresh the registry after host authentication and return log continuity.
57
+ * Every authenticated entry point runs this first, so it also refuses an
58
+ * oversized authentication context (§1.1) before any resolver sees it.
59
+ */
60
+ export async function touchAuthenticatedPartition(ctx) {
61
+ if (ctx.context !== undefined) {
62
+ const byteLength = new TextEncoder().encode(ctx.context).length;
63
+ if (byteLength > 256)
64
+ throw new AuthContextTooLargeError(byteLength);
65
+ }
47
66
  return ctx.storage.touchPartition(ctx.partition, clockOf(ctx)(), crypto.randomUUID());
48
67
  }
package/dist/handler.js CHANGED
@@ -47,7 +47,11 @@ async function authorizeFromLease(ctx, clientId, schema) {
47
47
  throw syncError('sync.auth_lease_required', 'live authorization is unavailable and auth leases are not configured (§7.3.3)');
48
48
  }
49
49
  const lease = await leases.store.get(ctx.partition, clientId);
50
- if (lease === undefined || lease.actorId !== ctx.actorId) {
50
+ // A lease binds the actor and the authentication context it was issued
51
+ // under (§7.3.1): another session of the same actor is not its holder.
52
+ if (lease === undefined ||
53
+ lease.actorId !== ctx.actorId ||
54
+ lease.context !== ctx.context) {
51
55
  throw syncError('sync.auth_lease_required', 'no valid auth lease for this client during an authorization outage (§7.3.3)');
52
56
  }
53
57
  if (lease.revoked) {
@@ -66,6 +70,7 @@ async function resolveOnce(ctx, clientId, schema) {
66
70
  partition: ctx.partition,
67
71
  actorId: ctx.actorId,
68
72
  clientId,
73
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
69
74
  });
70
75
  }
71
76
  catch (error) {
@@ -98,7 +103,7 @@ async function resolveOnce(ctx, clientId, schema) {
98
103
  // (sliding window) and emits a LEASE frame — only when configured.
99
104
  let leaseToEmit;
100
105
  if (ctx.leases !== undefined) {
101
- leaseToEmit = await ctx.leases.store.issue(ctx.partition, clientId, ctx.actorId, allowed, clockOf(ctx)(), ctx.leases.ttlMs);
106
+ leaseToEmit = await ctx.leases.store.issue(ctx.partition, clientId, ctx.actorId, allowed, clockOf(ctx)(), ctx.leases.ttlMs, ctx.context);
102
107
  }
103
108
  return { resolved: { ok: true, allowed }, leaseToEmit };
104
109
  }
@@ -17,6 +17,12 @@ import type { ScopeMap } from '@syncular/core';
17
17
  export interface LeaseRecord {
18
18
  readonly leaseId: string;
19
19
  readonly actorId: string;
20
+ /**
21
+ * The authentication context (§1.1) the issuing round resolved scopes
22
+ * under; absent when it had none. A lease never authorizes a request
23
+ * under another context (§7.3.3).
24
+ */
25
+ readonly context?: string;
20
26
  /** The actor's resolved allowed scopes at issuance (§3.2 step 3). */
21
27
  readonly allowedScopes: ScopeMap;
22
28
  readonly issuedAtMs: number;
@@ -31,9 +37,10 @@ export interface LeaseStore {
31
37
  * refresh slides the SAME `leaseId` — implementations MUST reuse the
32
38
  * stored id for the pair unless it is revoked (a revoked handle never
33
39
  * silently resurrects: a fresh id is minted only once the host clears
34
- * the revocation). Returns the stored record.
40
+ * the revocation). A refresh by another actor or under another
41
+ * `context` mints a fresh id. Returns the stored record.
35
42
  */
36
- issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number): Promise<LeaseRecord>;
43
+ issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number, context?: string): Promise<LeaseRecord>;
37
44
  /** Revoke a lease by `leaseId` (§7.3.4); durable, survives refresh. */
38
45
  revoke(partition: string, leaseId: string): Promise<void>;
39
46
  }
@@ -45,6 +52,6 @@ export declare class MemoryLeaseStore implements LeaseStore {
45
52
  readonly leaseId?: LeaseIdFactory;
46
53
  });
47
54
  get(partition: string, clientId: string): Promise<LeaseRecord | undefined>;
48
- issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number): Promise<LeaseRecord>;
55
+ issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number, context?: string): Promise<LeaseRecord>;
49
56
  revoke(partition: string, leaseId: string): Promise<void>;
50
57
  }
Binary file
@@ -131,6 +131,7 @@ export function registerRemoteQuery(descriptor, options) {
131
131
  partition: ctx.partition,
132
132
  actorId: ctx.actorId,
133
133
  clientId,
134
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
134
135
  });
135
136
  if (allowed === RESOLVER_OUTAGE) {
136
137
  throw syncError('operation.forbidden', 'live scope authorization is unavailable for this query');
@@ -345,6 +346,7 @@ export function registerRemoteCommand(descriptor, options) {
345
346
  partition: ctx.partition,
346
347
  actorId: ctx.actorId,
347
348
  clientId,
349
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
348
350
  });
349
351
  if (allowed === RESOLVER_OUTAGE) {
350
352
  throw syncError('operation.forbidden', 'live scope authorization is unavailable for this command');
package/dist/pull.js CHANGED
@@ -176,6 +176,7 @@ async function signedUrlFields(ctx, limits, segmentId, digest, now) {
176
176
  partition: ctx.partition,
177
177
  scopeDigest: digest,
178
178
  nowMs: now,
179
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
179
180
  });
180
181
  }
181
182
  function segmentRefFrame(record, scopeDigest, extra) {
@@ -58,6 +58,12 @@ export interface RealtimeConnectOptions {
58
58
  readonly partition: string;
59
59
  readonly actorId: string;
60
60
  readonly clientId: string;
61
+ /**
62
+ * The authentication context the upgrade authenticated (§1.1, §8.1). The
63
+ * connection resolves scopes under it for its lifetime: registrations,
64
+ * presence grants and socket rounds.
65
+ */
66
+ readonly context?: string;
61
67
  /**
62
68
  * Socket send: JSON control messages as text, tagged binary otherwise
63
69
  * (§8.7). A host MAY return a promise that resolves when the socket
@@ -108,6 +114,7 @@ export declare class RealtimeSession {
108
114
  readonly partition: string;
109
115
  readonly actorId: string;
110
116
  readonly clientId: string;
117
+ readonly context: string | undefined;
111
118
  readonly logEpoch: string;
112
119
  /** Response/delta layout selected by the most recent socket round. */
113
120
  wireVersion: number;
@@ -234,7 +241,12 @@ export declare class RealtimeHub {
234
241
  * Resolve the client record's live units into per-connection
235
242
  * registrations (§8.1 at upgrade; §8.7 at socket-round end).
236
243
  */
237
- loadRegistrations(partition: string, actorId: string, clientId: string, record: ClientRecord | undefined): Promise<Registration[]>;
244
+ loadRegistrations(identity: {
245
+ readonly partition: string;
246
+ readonly actorId: string;
247
+ readonly clientId: string;
248
+ readonly context?: string | undefined;
249
+ }, record: ClientRecord | undefined): Promise<Registration[]>;
238
250
  /**
239
251
  * Build the per-round request context for a socket sync round (§8.7):
240
252
  * the same shape the HTTP adapter builds, so the round drives the
@@ -243,6 +255,7 @@ export declare class RealtimeHub {
243
255
  requestContextFor(identity: {
244
256
  readonly partition: string;
245
257
  readonly actorId: string;
258
+ readonly context?: string | undefined;
246
259
  }): SyncRequestContext;
247
260
  /** The host's error reporter (`SyncServerConfig.onError`), if any. */
248
261
  get onError(): SyncularErrorHandler | undefined;
package/dist/realtime.js CHANGED
@@ -88,6 +88,7 @@ export class RealtimeSession {
88
88
  partition;
89
89
  actorId;
90
90
  clientId;
91
+ context;
91
92
  logEpoch;
92
93
  /** Response/delta layout selected by the most recent socket round. */
93
94
  wireVersion;
@@ -148,6 +149,7 @@ export class RealtimeSession {
148
149
  this.partition = options.partition;
149
150
  this.actorId = options.actorId;
150
151
  this.clientId = options.clientId;
152
+ this.context = options.context;
151
153
  this.logEpoch = logEpoch;
152
154
  this.wireVersion = wireVersion;
153
155
  this.cursor = cursor;
@@ -623,7 +625,7 @@ export class RealtimeSession {
623
625
  const generation = ++this.#registrationGeneration;
624
626
  let registrations;
625
627
  try {
626
- registrations = await this.#hub.loadRegistrations(this.partition, this.actorId, this.clientId, await this.#storage.getClientRecord(this.partition, this.clientId));
628
+ registrations = await this.#hub.loadRegistrations(this, await this.#storage.getClientRecord(this.partition, this.clientId));
627
629
  }
628
630
  catch {
629
631
  if (!failClosed) {
@@ -920,13 +922,15 @@ export class RealtimeHub {
920
922
  * Resolve the client record's live units into per-connection
921
923
  * registrations (§8.1 at upgrade; §8.7 at socket-round end).
922
924
  */
923
- async loadRegistrations(partition, actorId, clientId, record) {
925
+ async loadRegistrations(identity, record) {
926
+ const { partition, actorId, clientId, context } = identity;
924
927
  let resolved;
925
928
  try {
926
929
  const allowed = await this.#config.resolveScopes({
927
930
  partition,
928
931
  actorId,
929
932
  clientId,
933
+ ...(context !== undefined ? { context } : {}),
930
934
  });
931
935
  // §7.3.3: delta-fanout registration needs live scopes — an outage
932
936
  // registers nothing (the client's next socket round, §8.7, is
@@ -1000,6 +1004,7 @@ export class RealtimeHub {
1000
1004
  segments,
1001
1005
  partition: identity.partition,
1002
1006
  actorId: identity.actorId,
1007
+ ...(identity.context !== undefined ? { context: identity.context } : {}),
1003
1008
  realtime: this,
1004
1009
  };
1005
1010
  }
@@ -1045,6 +1050,9 @@ export class RealtimeHub {
1045
1050
  ...this.#config,
1046
1051
  partition: options.partition,
1047
1052
  actorId: options.actorId,
1053
+ ...(options.context !== undefined
1054
+ ? { context: options.context }
1055
+ : {}),
1048
1056
  });
1049
1057
  shared = {
1050
1058
  logEpoch,
@@ -1083,6 +1091,9 @@ export class RealtimeHub {
1083
1091
  ...this.#config,
1084
1092
  partition: options.partition,
1085
1093
  actorId: options.actorId,
1094
+ ...(options.context !== undefined
1095
+ ? { context: options.context }
1096
+ : {}),
1086
1097
  })).logEpoch;
1087
1098
  if (options.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
1088
1099
  throw syncError('sync.invalid_client_id', 'clientId uses a reserved server-command namespace (§1.5)');
@@ -1091,7 +1102,7 @@ export class RealtimeHub {
1091
1102
  if (record !== undefined && record.actorId !== options.actorId) {
1092
1103
  throw syncError('sync.invalid_client_id', 'clientId is bound to a different actor in this partition (§1.5)');
1093
1104
  }
1094
- const registrations = await this.loadRegistrations(options.partition, options.actorId, options.clientId, record);
1105
+ const registrations = await this.loadRegistrations(options, record);
1095
1106
  const latestSeq = restored?.latestSeq ?? (await storage.getMaxCommitSeq(options.partition));
1096
1107
  const cursor = record?.cursor ?? -1;
1097
1108
  const session = new RealtimeSession(this, options, registrations, cursor, latestSeq, clock, this.#config.maxDeltaBytes ?? DEFAULT_MAX_DELTA_BYTES, storage, logEpoch, record !== undefined && isSupportedProtocolWireVersion(record.wireVersion)
@@ -143,6 +143,7 @@ async function authorizePublication(ctx, request, logEpoch, stored) {
143
143
  const allowed = await ctx.resolveScopes({
144
144
  partition: ctx.partition,
145
145
  actorId: ctx.actorId,
146
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
146
147
  });
147
148
  // §7.3.3: leases authorize sync rounds, never downloads — an outage
148
149
  // signal here denies (re-authorization needs live scopes, §5.5).
@@ -23,6 +23,8 @@ export interface SegmentPresignArgs {
23
23
  readonly nowMs: number;
24
24
  /** Resolved TTL (config value or the 900 s default) — already applied. */
25
25
  readonly ttlSeconds: number;
26
+ /** The authentication context (§1.1) the pull resolved scopes under. */
27
+ readonly context?: string;
26
28
  }
27
29
  /**
28
30
  * Delegated presign (§5.4): the provider signs the URL. The callback MUST
@@ -49,6 +51,7 @@ export declare function issueSegmentUrl(config: SegmentUrlConfig, args: {
49
51
  readonly partition: string;
50
52
  readonly scopeDigest: string;
51
53
  readonly nowMs: number;
54
+ readonly context?: string;
52
55
  }): Promise<SegmentUrlIssue>;
53
56
  /**
54
57
  * Delegated presign for BLOB downloads (§5.9.5). The blob twin of
@@ -66,6 +69,8 @@ export interface BlobPresignArgs {
66
69
  readonly nowMs: number;
67
70
  /** Resolved TTL (config value or the 900 s default) — already applied. */
68
71
  readonly ttlSeconds: number;
72
+ /** The authentication context (§1.1) the download was authorized under. */
73
+ readonly context?: string;
69
74
  }
70
75
  export interface BlobPresignConfig {
71
76
  readonly presign: (args: BlobPresignArgs) => SegmentUrlIssue | Promise<SegmentUrlIssue>;
@@ -81,6 +86,7 @@ export declare function issueBlobUrl(config: BlobPresignConfig, args: {
81
86
  readonly partition: string;
82
87
  readonly blobId: string;
83
88
  readonly nowMs: number;
89
+ readonly context?: string;
84
90
  }): Promise<SegmentUrlIssue>;
85
91
  /**
86
92
  * Delegated presign for BLOB UPLOADS (§5.9.3 direct-to-storage). The upload
@@ -124,6 +130,8 @@ export interface SegmentTokenClaims {
124
130
  readonly aud: string;
125
131
  /** Unix seconds — the sole non-millisecond timestamp in the spec. */
126
132
  readonly exp: number;
133
+ /** The issuing pull's authentication context (§1.1); absent without one. */
134
+ readonly ctx?: string;
127
135
  }
128
136
  export declare function signSegmentToken(key: string | Uint8Array, claims: SegmentTokenClaims): Promise<string>;
129
137
  /**
@@ -142,4 +150,11 @@ export declare function verifySegmentToken(key: string | Uint8Array, token: stri
142
150
  readonly audience: string;
143
151
  readonly nowMs: number;
144
152
  readonly skewSeconds?: number;
153
+ /**
154
+ * The authentication context (§1.1) of a download that authenticated.
155
+ * When set, a token minted under another context, or without one, is
156
+ * refused. A headerless signed download (§5.4) passes none: the
157
+ * MAC-bound `seg`, `sd` and `ctx` claims are the grant.
158
+ */
159
+ readonly context?: string;
145
160
  }): Promise<SegmentTokenClaims>;
@@ -5,9 +5,10 @@
5
5
  *
6
6
  * Native: `st = base64url(payloadJson) + "." +
7
7
  * base64url(HMAC-SHA256(key, payloadJson))` with claims
8
- * `{v, seg, sd, aud, exp}`; `exp` is unix seconds. Issuance happens inside
8
+ * `{v, seg, sd, aud, exp, ctx?}`; `exp` is unix seconds and `ctx` the
9
+ * authentication context of the issuing pull (§1.1). Issuance happens inside
9
10
  * the pull immediately after scope resolution; verification checks MAC,
10
- * expiry (≤ 60 s skew), and `seg`/`sd`/`aud` equality. Actual CDN serving
11
+ * expiry (≤ 60 s skew), and `seg`/`sd`/`aud`/`ctx` equality. Actual CDN serving
11
12
  * is out of scope.
12
13
  *
13
14
  * Delegated presign: the provider mints the URL (§5.4 equivalence rule —
@@ -35,6 +36,7 @@ export async function issueSegmentUrl(config, args) {
35
36
  sd: args.scopeDigest,
36
37
  aud: config.audience(args.partition),
37
38
  exp,
39
+ ...(args.context !== undefined ? { ctx: args.context } : {}),
38
40
  });
39
41
  return {
40
42
  url: `${config.baseUrl}/${args.segmentId}?st=${token}`,
@@ -99,6 +101,7 @@ export async function signSegmentToken(key, claims) {
99
101
  sd: claims.sd,
100
102
  aud: claims.aud,
101
103
  exp: claims.exp,
104
+ ...(claims.ctx !== undefined ? { ctx: claims.ctx } : {}),
102
105
  });
103
106
  const payload = encoder.encode(payloadJson);
104
107
  const mac = await hmac(key, payload);
@@ -155,5 +158,7 @@ export async function verifySegmentToken(key, token, expected) {
155
158
  throw forbidden('scope-digest mismatch');
156
159
  if (claims.aud !== expected.audience)
157
160
  throw forbidden('audience mismatch');
161
+ if (expected.context !== undefined && claims.ctx !== expected.context)
162
+ throw forbidden('context mismatch');
158
163
  return claims;
159
164
  }
@@ -11,6 +11,6 @@ export declare class SqliteLeaseStore implements LeaseStore {
11
11
  readonly leaseId?: LeaseIdFactory;
12
12
  });
13
13
  get(partition: string, clientId: string): Promise<LeaseRecord | undefined>;
14
- issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number): Promise<LeaseRecord>;
14
+ issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number, context?: string): Promise<LeaseRecord>;
15
15
  revoke(partition: string, leaseId: string): Promise<void>;
16
16
  }
@@ -17,6 +17,7 @@ export class SqliteLeaseStore {
17
17
  lease_id TEXT NOT NULL, actor_id TEXT NOT NULL,
18
18
  allowed_scopes TEXT NOT NULL,
19
19
  issued_at_ms INTEGER NOT NULL, expires_at_ms INTEGER NOT NULL,
20
+ context TEXT,
20
21
  PRIMARY KEY (partition, client_id)
21
22
  );
22
23
  CREATE TABLE IF NOT EXISTS sync_lease_revocations(
@@ -24,13 +25,21 @@ export class SqliteLeaseStore {
24
25
  PRIMARY KEY (partition, lease_id)
25
26
  );
26
27
  `);
28
+ // §7.3.1: a lease table created before leases recorded their
29
+ // authentication context gains the column; its rows carry none.
30
+ if (!this.db
31
+ .query(`PRAGMA table_info(sync_leases)`)
32
+ .all()
33
+ .some((column) => column.name === 'context')) {
34
+ this.db.exec(`ALTER TABLE sync_leases ADD COLUMN context TEXT`);
35
+ }
27
36
  }
28
37
  async get(partition, clientId) {
29
38
  const row = this.db
30
39
  .query(
31
40
  // §7.3.4: the revocation table is the only record of a revocation, so
32
41
  // a revoked id stays revoked whatever its lease row says.
33
- `SELECT l.lease_id, l.actor_id, l.allowed_scopes, l.issued_at_ms,
42
+ `SELECT l.lease_id, l.actor_id, l.context, l.allowed_scopes, l.issued_at_ms,
34
43
  l.expires_at_ms,
35
44
  EXISTS (SELECT 1 FROM sync_lease_revocations r
36
45
  WHERE r.partition=l.partition
@@ -42,21 +51,24 @@ export class SqliteLeaseStore {
42
51
  return {
43
52
  leaseId: row.lease_id,
44
53
  actorId: row.actor_id,
54
+ ...(row.context !== null ? { context: row.context } : {}),
45
55
  allowedScopes: JSON.parse(row.allowed_scopes),
46
56
  issuedAtMs: row.issued_at_ms,
47
57
  expiresAtMs: row.expires_at_ms,
48
58
  revoked: row.revoked !== 0,
49
59
  };
50
60
  }
51
- async issue(partition, clientId, actorId, allowedScopes, nowMs, ttlMs) {
61
+ async issue(partition, clientId, actorId, allowedScopes, nowMs, ttlMs, context) {
52
62
  const existing = await this.get(partition, clientId);
53
63
  const reuse = existing !== undefined &&
54
64
  existing.actorId === actorId &&
65
+ existing.context === context &&
55
66
  !existing.revoked;
56
67
  const leaseId = reuse ? existing.leaseId : this.#newId();
57
68
  const record = {
58
69
  leaseId,
59
70
  actorId,
71
+ ...(context !== undefined ? { context } : {}),
60
72
  allowedScopes,
61
73
  issuedAtMs: nowMs,
62
74
  expiresAtMs: nowMs + ttlMs,
@@ -65,14 +77,15 @@ export class SqliteLeaseStore {
65
77
  this.db
66
78
  .query(`INSERT INTO sync_leases(
67
79
  partition, client_id, lease_id, actor_id, allowed_scopes,
68
- issued_at_ms, expires_at_ms
69
- ) VALUES (?,?,?,?,?,?,?)
80
+ issued_at_ms, expires_at_ms, context
81
+ ) VALUES (?,?,?,?,?,?,?,?)
70
82
  ON CONFLICT(partition, client_id) DO UPDATE SET
71
83
  lease_id=excluded.lease_id, actor_id=excluded.actor_id,
72
84
  allowed_scopes=excluded.allowed_scopes,
73
85
  issued_at_ms=excluded.issued_at_ms,
74
- expires_at_ms=excluded.expires_at_ms`)
75
- .run(partition, clientId, leaseId, actorId, JSON.stringify(allowedScopes), nowMs, record.expiresAtMs);
86
+ expires_at_ms=excluded.expires_at_ms,
87
+ context=excluded.context`)
88
+ .run(partition, clientId, leaseId, actorId, JSON.stringify(allowedScopes), nowMs, record.expiresAtMs, context ?? null);
76
89
  return record;
77
90
  }
78
91
  async revoke(partition, leaseId) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server",
3
- "version": "0.73.0",
3
+ "version": "0.75.0",
4
4
  "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
68
68
  "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
69
69
  },
70
70
  "dependencies": {
71
- "@syncular/core": "0.73.0"
71
+ "@syncular/core": "0.75.0"
72
72
  },
73
73
  "devDependencies": {
74
74
  "@electric-sql/pglite": "^0.5.4"
package/src/admin.ts CHANGED
@@ -894,7 +894,8 @@ export class SyncularAdmin {
894
894
  * Trace whether one client receives one row, combining the row's stored
895
895
  * scopes and newest change with the client's units, cursor, the
896
896
  * actor's allowed scopes, and its retained push failures. See
897
- * `AdminTraceVerdict` for the verdict order.
897
+ * `AdminTraceVerdict` for the verdict order. `context` is the
898
+ * authentication context (§1.1) to resolve the actor's scopes under.
898
899
  */
899
900
  async traceRow(
900
901
  partition: string,
@@ -902,9 +903,10 @@ export class SyncularAdmin {
902
903
  readonly table: string;
903
904
  readonly rowId: string;
904
905
  readonly clientId: string;
906
+ readonly context?: string;
905
907
  },
906
908
  ): Promise<AdminRowTrace> {
907
- const { table, rowId, clientId } = query;
909
+ const { table, rowId, clientId, context } = query;
908
910
  const row = await this.inspectRow(partition, table, rowId, {
909
911
  historyLimit: 1,
910
912
  });
@@ -927,7 +929,7 @@ export class SyncularAdmin {
927
929
  if (record === undefined) {
928
930
  return { ...base, verdict: 'client-unknown', units: [] };
929
931
  }
930
- const allowed = await this.#allowedScopes(partition, record);
932
+ const allowed = await this.#allowedScopes(partition, record, context);
931
933
  return {
932
934
  ...base,
933
935
  client: (await this.#clientView(partition))(record),
@@ -945,12 +947,14 @@ export class SyncularAdmin {
945
947
 
946
948
  /**
947
949
  * Who has one row and who does not: the trace verdict for every known
948
- * client in the partition, resolving each actor's allowed scopes once.
950
+ * client in the partition, resolving each actor's allowed scopes once
951
+ * under `context` (§1.1).
949
952
  */
950
953
  async rowDelivery(
951
954
  partition: string,
952
955
  table: string,
953
956
  rowId: string,
957
+ context?: string,
954
958
  ): Promise<AdminRowDelivery> {
955
959
  const list = required(
956
960
  this.#storage.listClientRecords?.bind(this.#storage),
@@ -970,7 +974,7 @@ export class SyncularAdmin {
970
974
  if (!allowedByActor.has(record.actorId)) {
971
975
  allowedByActor.set(
972
976
  record.actorId,
973
- await this.#allowedScopes(partition, record),
977
+ await this.#allowedScopes(partition, record, context),
974
978
  );
975
979
  }
976
980
  clients.push({
@@ -1698,12 +1702,14 @@ export class SyncularAdmin {
1698
1702
  async #allowedScopes(
1699
1703
  partition: string,
1700
1704
  record: ClientRecord,
1705
+ context: string | undefined,
1701
1706
  ): Promise<ScopeMap | 'outage' | undefined> {
1702
1707
  if (this.#resolveScopes === undefined) return undefined;
1703
1708
  const resolved = await this.#resolveScopes({
1704
1709
  partition,
1705
1710
  actorId: record.actorId,
1706
1711
  clientId: record.clientId,
1712
+ ...(context !== undefined ? { context } : {}),
1707
1713
  });
1708
1714
  return resolved === RESOLVER_OUTAGE ? 'outage' : resolved;
1709
1715
  }
@@ -215,6 +215,7 @@ async function downloadBlob(
215
215
  const allowed = await ctx.resolveScopes({
216
216
  partition: ctx.partition,
217
217
  actorId: ctx.actorId,
218
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
218
219
  });
219
220
  // §7.3.3: leases never authorize a blob download — an outage denies.
220
221
  resolved =
@@ -267,6 +268,7 @@ async function downloadBlob(
267
268
  partition: ctx.partition,
268
269
  blobId,
269
270
  nowMs: clockOf(ctx)(),
271
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
270
272
  });
271
273
  return {
272
274
  headers: {
package/src/context.ts CHANGED
@@ -42,6 +42,12 @@ export interface ResolveScopesArgs {
42
42
  * actor + scopes only (§5.5, §5.9.5) and never consult a lease.
43
43
  */
44
44
  readonly clientId?: string;
45
+ /**
46
+ * The authentication context the host's `authenticate` returned for this
47
+ * request (§1.1), passed unchanged on every path that resolves scopes.
48
+ * Absent when the host returned none.
49
+ */
50
+ readonly context?: string;
45
51
  }
46
52
 
47
53
  /**
@@ -253,6 +259,20 @@ export interface SyncServerConfig {
253
259
  export interface SyncRequestContext extends SyncServerConfig {
254
260
  readonly partition: string;
255
261
  readonly actorId: string;
262
+ /** The host authentication context (§1.1), at most 256 UTF-8 bytes. */
263
+ readonly context?: string;
264
+ }
265
+
266
+ /** §1.1: `authenticate` returned a context longer than 256 UTF-8 bytes. */
267
+ export class AuthContextTooLargeError extends Error {
268
+ override readonly name = 'AuthContextTooLargeError';
269
+ readonly code = 'sync.auth_context_too_large';
270
+ readonly details: { readonly byteLength: number; readonly max: 256 };
271
+
272
+ constructor(byteLength: number) {
273
+ super('authentication context exceeds 256 UTF-8 bytes');
274
+ this.details = { byteLength, max: 256 };
275
+ }
256
276
  }
257
277
 
258
278
  export function clockOf(ctx: SyncServerConfig): () => number {
@@ -275,10 +295,18 @@ export function limitsOf(ctx: SyncServerConfig): ServerLimits {
275
295
  return limits;
276
296
  }
277
297
 
278
- /** Refresh the registry after host authentication and return log continuity. */
279
- export function touchAuthenticatedPartition(
298
+ /**
299
+ * Refresh the registry after host authentication and return log continuity.
300
+ * Every authenticated entry point runs this first, so it also refuses an
301
+ * oversized authentication context (§1.1) before any resolver sees it.
302
+ */
303
+ export async function touchAuthenticatedPartition(
280
304
  ctx: SyncRequestContext,
281
305
  ): Promise<PartitionRegistryEntry> {
306
+ if (ctx.context !== undefined) {
307
+ const byteLength = new TextEncoder().encode(ctx.context).length;
308
+ if (byteLength > 256) throw new AuthContextTooLargeError(byteLength);
309
+ }
282
310
  return ctx.storage.touchPartition(
283
311
  ctx.partition,
284
312
  clockOf(ctx)(),
package/src/handler.ts CHANGED
@@ -159,7 +159,13 @@ async function authorizeFromLease(
159
159
  );
160
160
  }
161
161
  const lease = await leases.store.get(ctx.partition, clientId);
162
- if (lease === undefined || lease.actorId !== ctx.actorId) {
162
+ // A lease binds the actor and the authentication context it was issued
163
+ // under (§7.3.1): another session of the same actor is not its holder.
164
+ if (
165
+ lease === undefined ||
166
+ lease.actorId !== ctx.actorId ||
167
+ lease.context !== ctx.context
168
+ ) {
163
169
  throw syncError(
164
170
  'sync.auth_lease_required',
165
171
  'no valid auth lease for this client during an authorization outage (§7.3.3)',
@@ -192,6 +198,7 @@ async function resolveOnce(
192
198
  partition: ctx.partition,
193
199
  actorId: ctx.actorId,
194
200
  clientId,
201
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
195
202
  });
196
203
  } catch (error) {
197
204
  if (error instanceof SyncError) throw error;
@@ -231,6 +238,7 @@ async function resolveOnce(
231
238
  allowed,
232
239
  clockOf(ctx)(),
233
240
  ctx.leases.ttlMs,
241
+ ctx.context,
234
242
  );
235
243
  }
236
244
  return { resolved: { ok: true, allowed }, leaseToEmit };
Binary file
package/src/operations.ts CHANGED
@@ -379,6 +379,7 @@ export function registerRemoteQuery<Params>(
379
379
  partition: ctx.partition,
380
380
  actorId: ctx.actorId,
381
381
  clientId,
382
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
382
383
  });
383
384
  if (allowed === RESOLVER_OUTAGE) {
384
385
  throw syncError(
@@ -719,6 +720,7 @@ export function registerRemoteCommand<Input>(
719
720
  partition: ctx.partition,
720
721
  actorId: ctx.actorId,
721
722
  clientId,
723
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
722
724
  });
723
725
  if (allowed === RESOLVER_OUTAGE) {
724
726
  throw syncError(
package/src/pull.ts CHANGED
@@ -280,6 +280,7 @@ async function signedUrlFields(
280
280
  partition: ctx.partition,
281
281
  scopeDigest: digest,
282
282
  nowMs: now,
283
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
283
284
  });
284
285
  }
285
286
 
package/src/realtime.ts CHANGED
@@ -101,6 +101,12 @@ export interface RealtimeConnectOptions {
101
101
  readonly partition: string;
102
102
  readonly actorId: string;
103
103
  readonly clientId: string;
104
+ /**
105
+ * The authentication context the upgrade authenticated (§1.1, §8.1). The
106
+ * connection resolves scopes under it for its lifetime: registrations,
107
+ * presence grants and socket rounds.
108
+ */
109
+ readonly context?: string;
104
110
  /**
105
111
  * Socket send: JSON control messages as text, tagged binary otherwise
106
112
  * (§8.7). A host MAY return a promise that resolves when the socket
@@ -210,6 +216,7 @@ export class RealtimeSession {
210
216
  readonly partition: string;
211
217
  readonly actorId: string;
212
218
  readonly clientId: string;
219
+ readonly context: string | undefined;
213
220
  readonly logEpoch: string;
214
221
  /** Response/delta layout selected by the most recent socket round. */
215
222
  wireVersion: number;
@@ -291,6 +298,7 @@ export class RealtimeSession {
291
298
  this.partition = options.partition;
292
299
  this.actorId = options.actorId;
293
300
  this.clientId = options.clientId;
301
+ this.context = options.context;
294
302
  this.logEpoch = logEpoch;
295
303
  this.wireVersion = wireVersion;
296
304
  this.cursor = cursor;
@@ -825,9 +833,7 @@ export class RealtimeSession {
825
833
  let registrations: Registration[];
826
834
  try {
827
835
  registrations = await this.#hub.loadRegistrations(
828
- this.partition,
829
- this.actorId,
830
- this.clientId,
836
+ this,
831
837
  await this.#storage.getClientRecord(this.partition, this.clientId),
832
838
  );
833
839
  } catch {
@@ -1198,17 +1204,22 @@ export class RealtimeHub {
1198
1204
  * registrations (§8.1 at upgrade; §8.7 at socket-round end).
1199
1205
  */
1200
1206
  async loadRegistrations(
1201
- partition: string,
1202
- actorId: string,
1203
- clientId: string,
1207
+ identity: {
1208
+ readonly partition: string;
1209
+ readonly actorId: string;
1210
+ readonly clientId: string;
1211
+ readonly context?: string | undefined;
1212
+ },
1204
1213
  record: ClientRecord | undefined,
1205
1214
  ): Promise<Registration[]> {
1215
+ const { partition, actorId, clientId, context } = identity;
1206
1216
  let resolved: ResolvedScopes;
1207
1217
  try {
1208
1218
  const allowed = await this.#config.resolveScopes({
1209
1219
  partition,
1210
1220
  actorId,
1211
1221
  clientId,
1222
+ ...(context !== undefined ? { context } : {}),
1212
1223
  });
1213
1224
  // §7.3.3: delta-fanout registration needs live scopes — an outage
1214
1225
  // registers nothing (the client's next socket round, §8.7, is
@@ -1271,6 +1282,7 @@ export class RealtimeHub {
1271
1282
  requestContextFor(identity: {
1272
1283
  readonly partition: string;
1273
1284
  readonly actorId: string;
1285
+ readonly context?: string | undefined;
1274
1286
  }): SyncRequestContext {
1275
1287
  const segments = this.#config.segments;
1276
1288
  if (segments === undefined) {
@@ -1288,6 +1300,7 @@ export class RealtimeHub {
1288
1300
  segments,
1289
1301
  partition: identity.partition,
1290
1302
  actorId: identity.actorId,
1303
+ ...(identity.context !== undefined ? { context: identity.context } : {}),
1291
1304
  realtime: this,
1292
1305
  };
1293
1306
  }
@@ -1345,6 +1358,9 @@ export class RealtimeHub {
1345
1358
  ...this.#config,
1346
1359
  partition: options.partition,
1347
1360
  actorId: options.actorId,
1361
+ ...(options.context !== undefined
1362
+ ? { context: options.context }
1363
+ : {}),
1348
1364
  });
1349
1365
  shared = {
1350
1366
  logEpoch,
@@ -1389,6 +1405,9 @@ export class RealtimeHub {
1389
1405
  ...this.#config,
1390
1406
  partition: options.partition,
1391
1407
  actorId: options.actorId,
1408
+ ...(options.context !== undefined
1409
+ ? { context: options.context }
1410
+ : {}),
1392
1411
  })
1393
1412
  ).logEpoch;
1394
1413
  if (options.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
@@ -1407,12 +1426,7 @@ export class RealtimeHub {
1407
1426
  'clientId is bound to a different actor in this partition (§1.5)',
1408
1427
  );
1409
1428
  }
1410
- const registrations = await this.loadRegistrations(
1411
- options.partition,
1412
- options.actorId,
1413
- options.clientId,
1414
- record,
1415
- );
1429
+ const registrations = await this.loadRegistrations(options, record);
1416
1430
  const latestSeq =
1417
1431
  restored?.latestSeq ?? (await storage.getMaxCommitSeq(options.partition));
1418
1432
  const cursor = record?.cursor ?? -1;
@@ -249,6 +249,7 @@ async function authorizePublication(
249
249
  const allowed = await ctx.resolveScopes({
250
250
  partition: ctx.partition,
251
251
  actorId: ctx.actorId,
252
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
252
253
  });
253
254
  // §7.3.3: leases authorize sync rounds, never downloads — an outage
254
255
  // signal here denies (re-authorization needs live scopes, §5.5).
package/src/signed-url.ts CHANGED
@@ -5,9 +5,10 @@
5
5
  *
6
6
  * Native: `st = base64url(payloadJson) + "." +
7
7
  * base64url(HMAC-SHA256(key, payloadJson))` with claims
8
- * `{v, seg, sd, aud, exp}`; `exp` is unix seconds. Issuance happens inside
8
+ * `{v, seg, sd, aud, exp, ctx?}`; `exp` is unix seconds and `ctx` the
9
+ * authentication context of the issuing pull (§1.1). Issuance happens inside
9
10
  * the pull immediately after scope resolution; verification checks MAC,
10
- * expiry (≤ 60 s skew), and `seg`/`sd`/`aud` equality. Actual CDN serving
11
+ * expiry (≤ 60 s skew), and `seg`/`sd`/`aud`/`ctx` equality. Actual CDN serving
11
12
  * is out of scope.
12
13
  *
13
14
  * Delegated presign: the provider mints the URL (§5.4 equivalence rule —
@@ -45,6 +46,8 @@ export interface SegmentPresignArgs {
45
46
  readonly nowMs: number;
46
47
  /** Resolved TTL (config value or the 900 s default) — already applied. */
47
48
  readonly ttlSeconds: number;
49
+ /** The authentication context (§1.1) the pull resolved scopes under. */
50
+ readonly context?: string;
48
51
  }
49
52
 
50
53
  /**
@@ -78,6 +81,7 @@ export async function issueSegmentUrl(
78
81
  readonly partition: string;
79
82
  readonly scopeDigest: string;
80
83
  readonly nowMs: number;
84
+ readonly context?: string;
81
85
  },
82
86
  ): Promise<SegmentUrlIssue> {
83
87
  const ttlSeconds = config.ttlSeconds ?? 900;
@@ -91,6 +95,7 @@ export async function issueSegmentUrl(
91
95
  sd: args.scopeDigest,
92
96
  aud: config.audience(args.partition),
93
97
  exp,
98
+ ...(args.context !== undefined ? { ctx: args.context } : {}),
94
99
  });
95
100
  return {
96
101
  url: `${config.baseUrl}/${args.segmentId}?st=${token}`,
@@ -114,6 +119,8 @@ export interface BlobPresignArgs {
114
119
  readonly nowMs: number;
115
120
  /** Resolved TTL (config value or the 900 s default) — already applied. */
116
121
  readonly ttlSeconds: number;
122
+ /** The authentication context (§1.1) the download was authorized under. */
123
+ readonly context?: string;
117
124
  }
118
125
 
119
126
  export interface BlobPresignConfig {
@@ -135,6 +142,7 @@ export async function issueBlobUrl(
135
142
  readonly partition: string;
136
143
  readonly blobId: string;
137
144
  readonly nowMs: number;
145
+ readonly context?: string;
138
146
  },
139
147
  ): Promise<SegmentUrlIssue> {
140
148
  const ttlSeconds = config.ttlSeconds ?? 900;
@@ -194,6 +202,8 @@ export interface SegmentTokenClaims {
194
202
  readonly aud: string;
195
203
  /** Unix seconds — the sole non-millisecond timestamp in the spec. */
196
204
  readonly exp: number;
205
+ /** The issuing pull's authentication context (§1.1); absent without one. */
206
+ readonly ctx?: string;
197
207
  }
198
208
 
199
209
  const encoder = new TextEncoder();
@@ -253,6 +263,7 @@ export async function signSegmentToken(
253
263
  sd: claims.sd,
254
264
  aud: claims.aud,
255
265
  exp: claims.exp,
266
+ ...(claims.ctx !== undefined ? { ctx: claims.ctx } : {}),
256
267
  });
257
268
  const payload = encoder.encode(payloadJson);
258
269
  const mac = await hmac(key, payload);
@@ -280,6 +291,13 @@ export async function verifySegmentToken(
280
291
  readonly audience: string;
281
292
  readonly nowMs: number;
282
293
  readonly skewSeconds?: number;
294
+ /**
295
+ * The authentication context (§1.1) of a download that authenticated.
296
+ * When set, a token minted under another context, or without one, is
297
+ * refused. A headerless signed download (§5.4) passes none: the
298
+ * MAC-bound `seg`, `sd` and `ctx` claims are the grant.
299
+ */
300
+ readonly context?: string;
283
301
  },
284
302
  ): Promise<SegmentTokenClaims> {
285
303
  const forbidden = (reason: string) =>
@@ -320,5 +338,7 @@ export async function verifySegmentToken(
320
338
  if (!scopeDigests.includes(claims.sd))
321
339
  throw forbidden('scope-digest mismatch');
322
340
  if (claims.aud !== expected.audience) throw forbidden('audience mismatch');
341
+ if (expected.context !== undefined && claims.ctx !== expected.context)
342
+ throw forbidden('context mismatch');
323
343
  return claims;
324
344
  }
@@ -31,6 +31,7 @@ export class SqliteLeaseStore implements LeaseStore {
31
31
  lease_id TEXT NOT NULL, actor_id TEXT NOT NULL,
32
32
  allowed_scopes TEXT NOT NULL,
33
33
  issued_at_ms INTEGER NOT NULL, expires_at_ms INTEGER NOT NULL,
34
+ context TEXT,
34
35
  PRIMARY KEY (partition, client_id)
35
36
  );
36
37
  CREATE TABLE IF NOT EXISTS sync_lease_revocations(
@@ -38,6 +39,16 @@ export class SqliteLeaseStore implements LeaseStore {
38
39
  PRIMARY KEY (partition, lease_id)
39
40
  );
40
41
  `);
42
+ // §7.3.1: a lease table created before leases recorded their
43
+ // authentication context gains the column; its rows carry none.
44
+ if (
45
+ !this.db
46
+ .query<{ name: string }, []>(`PRAGMA table_info(sync_leases)`)
47
+ .all()
48
+ .some((column) => column.name === 'context')
49
+ ) {
50
+ this.db.exec(`ALTER TABLE sync_leases ADD COLUMN context TEXT`);
51
+ }
41
52
  }
42
53
 
43
54
  async get(
@@ -49,6 +60,7 @@ export class SqliteLeaseStore implements LeaseStore {
49
60
  {
50
61
  lease_id: string;
51
62
  actor_id: string;
63
+ context: string | null;
52
64
  allowed_scopes: string;
53
65
  issued_at_ms: number;
54
66
  expires_at_ms: number;
@@ -58,7 +70,7 @@ export class SqliteLeaseStore implements LeaseStore {
58
70
  >(
59
71
  // §7.3.4: the revocation table is the only record of a revocation, so
60
72
  // a revoked id stays revoked whatever its lease row says.
61
- `SELECT l.lease_id, l.actor_id, l.allowed_scopes, l.issued_at_ms,
73
+ `SELECT l.lease_id, l.actor_id, l.context, l.allowed_scopes, l.issued_at_ms,
62
74
  l.expires_at_ms,
63
75
  EXISTS (SELECT 1 FROM sync_lease_revocations r
64
76
  WHERE r.partition=l.partition
@@ -70,6 +82,7 @@ export class SqliteLeaseStore implements LeaseStore {
70
82
  return {
71
83
  leaseId: row.lease_id,
72
84
  actorId: row.actor_id,
85
+ ...(row.context !== null ? { context: row.context } : {}),
73
86
  allowedScopes: JSON.parse(row.allowed_scopes) as ScopeMap,
74
87
  issuedAtMs: row.issued_at_ms,
75
88
  expiresAtMs: row.expires_at_ms,
@@ -84,16 +97,19 @@ export class SqliteLeaseStore implements LeaseStore {
84
97
  allowedScopes: ScopeMap,
85
98
  nowMs: number,
86
99
  ttlMs: number,
100
+ context?: string,
87
101
  ): Promise<LeaseRecord> {
88
102
  const existing = await this.get(partition, clientId);
89
103
  const reuse =
90
104
  existing !== undefined &&
91
105
  existing.actorId === actorId &&
106
+ existing.context === context &&
92
107
  !existing.revoked;
93
108
  const leaseId = reuse ? existing.leaseId : this.#newId();
94
109
  const record: LeaseRecord = {
95
110
  leaseId,
96
111
  actorId,
112
+ ...(context !== undefined ? { context } : {}),
97
113
  allowedScopes,
98
114
  issuedAtMs: nowMs,
99
115
  expiresAtMs: nowMs + ttlMs,
@@ -103,13 +119,14 @@ export class SqliteLeaseStore implements LeaseStore {
103
119
  .query(
104
120
  `INSERT INTO sync_leases(
105
121
  partition, client_id, lease_id, actor_id, allowed_scopes,
106
- issued_at_ms, expires_at_ms
107
- ) VALUES (?,?,?,?,?,?,?)
122
+ issued_at_ms, expires_at_ms, context
123
+ ) VALUES (?,?,?,?,?,?,?,?)
108
124
  ON CONFLICT(partition, client_id) DO UPDATE SET
109
125
  lease_id=excluded.lease_id, actor_id=excluded.actor_id,
110
126
  allowed_scopes=excluded.allowed_scopes,
111
127
  issued_at_ms=excluded.issued_at_ms,
112
- expires_at_ms=excluded.expires_at_ms`,
128
+ expires_at_ms=excluded.expires_at_ms,
129
+ context=excluded.context`,
113
130
  )
114
131
  .run(
115
132
  partition,
@@ -119,6 +136,7 @@ export class SqliteLeaseStore implements LeaseStore {
119
136
  JSON.stringify(allowedScopes),
120
137
  nowMs,
121
138
  record.expiresAtMs,
139
+ context ?? null,
122
140
  );
123
141
  return record;
124
142
  }