@syncular/server 0.74.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 +6 -3
- package/dist/admin.js +10 -7
- package/dist/blob-handlers.js +2 -0
- package/dist/context.d.ts +23 -1
- package/dist/context.js +21 -2
- package/dist/handler.js +7 -2
- package/dist/lease-store.d.ts +10 -3
- package/dist/lease-store.js +0 -0
- package/dist/operations.js +2 -0
- package/dist/pull.js +1 -0
- package/dist/realtime.d.ts +14 -1
- package/dist/realtime.js +14 -3
- package/dist/segment-download.js +1 -0
- package/dist/signed-url.d.ts +15 -0
- package/dist/signed-url.js +7 -2
- package/dist/sqlite-lease-store.d.ts +1 -1
- package/dist/sqlite-lease-store.js +19 -6
- package/package.json +2 -2
- package/src/admin.ts +11 -5
- package/src/blob-handlers.ts +2 -0
- package/src/context.ts +30 -2
- package/src/handler.ts +9 -1
- package/src/lease-store.ts +0 -0
- package/src/operations.ts +2 -0
- package/src/pull.ts +1 -0
- package/src/realtime.ts +26 -12
- package/src/segment-download.ts +1 -0
- package/src/signed-url.ts +22 -2
- package/src/sqlite-lease-store.ts +22 -4
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
|
}
|
package/dist/blob-handlers.js
CHANGED
|
@@ -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
|
-
/**
|
|
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
|
-
/**
|
|
46
|
-
|
|
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
|
-
|
|
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
|
}
|
package/dist/lease-store.d.ts
CHANGED
|
@@ -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).
|
|
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
|
}
|
package/dist/lease-store.js
CHANGED
|
Binary file
|
package/dist/operations.js
CHANGED
|
@@ -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) {
|
package/dist/realtime.d.ts
CHANGED
|
@@ -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(
|
|
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
|
|
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(
|
|
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
|
|
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)
|
package/dist/segment-download.js
CHANGED
|
@@ -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).
|
package/dist/signed-url.d.ts
CHANGED
|
@@ -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>;
|
package/dist/signed-url.js
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
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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
|
}
|
package/src/blob-handlers.ts
CHANGED
|
@@ -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
|
-
/**
|
|
279
|
-
|
|
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
|
-
|
|
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 };
|
package/src/lease-store.ts
CHANGED
|
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
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
|
|
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
|
-
|
|
1202
|
-
|
|
1203
|
-
|
|
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;
|
package/src/segment-download.ts
CHANGED
|
@@ -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
|
|
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
|
}
|