lss-sync 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +104 -3
- package/docs/PROTOCOL.md +144 -0
- package/docs/SECURITY.md +36 -0
- package/package.json +50 -6
- package/src/crypto.js +42 -0
- package/src/encoding.js +74 -0
- package/src/engine.js +333 -0
- package/src/index.d.ts +59 -0
- package/src/index.js +3 -0
- package/src/policy.d.ts +2 -0
- package/src/policy.js +31 -0
- package/src/store.js +101 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Safi Ullah Mirzai
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,104 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# LSS synchronization SDK
|
|
2
|
+
|
|
3
|
+
Reusable encrypted offline synchronization for JavaScript/TypeScript browser applications and Python applications. This local research preview is not yet published on GitHub, npm, or PyPI. Licensed under the MIT License. Copyright (c) 2026 Safi Ullah Mirzai.
|
|
4
|
+
|
|
5
|
+
See [راهنمای دری](docs/README.fa.md), [protocol](docs/PROTOCOL.md), [security boundaries](docs/SECURITY.md), and [release instructions](docs/RELEASING.md).
|
|
6
|
+
|
|
7
|
+
## Install locally
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install /path/to/lss-sync
|
|
11
|
+
python -m pip install /path/to/lss-sync/python
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
The browser package has no runtime JavaScript dependencies and includes TypeScript declarations. Python uses the maintained `cryptography` library and SQLite. Use Python 3.10+ and a current browser supporting Web Crypto, IndexedDB and Web Locks.
|
|
15
|
+
|
|
16
|
+
## Browser integration
|
|
17
|
+
|
|
18
|
+
```javascript
|
|
19
|
+
import { BrowserSyncEngine } from 'lss-sync';
|
|
20
|
+
|
|
21
|
+
const sync = new BrowserSyncEngine({
|
|
22
|
+
dbName: 'my-app-account-123',
|
|
23
|
+
endpoint: '/api/sync',
|
|
24
|
+
token: accessToken
|
|
25
|
+
});
|
|
26
|
+
const { configured } = await sync.init();
|
|
27
|
+
if (configured) await sync.unlock(passphrase);
|
|
28
|
+
else await sync.setup(passphrase);
|
|
29
|
+
await sync.save({ kind: 'inspection', passed: true, quantity: '12.50' });
|
|
30
|
+
sync.addEventListener('change', async () => render(await sync.snapshot()));
|
|
31
|
+
// await sync.close();
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Supply your application's `accessToken`, `passphrase`, and `render` function. Setup/unlock starts the browser scheduler. Serve the app and API on the same HTTPS origin. The package does not install a service worker: the host app must cache its own shell for offline reload. Distinct accounts should use distinct vault names.
|
|
35
|
+
|
|
36
|
+
## Python integration
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
from lss_sync import SyncClient
|
|
40
|
+
|
|
41
|
+
client = SyncClient('account-123.sqlite3', endpoint=endpoint, token=access_token)
|
|
42
|
+
if client.configured:
|
|
43
|
+
client.unlock(passphrase)
|
|
44
|
+
else:
|
|
45
|
+
client.setup(passphrase)
|
|
46
|
+
client.save({'kind': 'inspection', 'passed': True, 'quantity': '12.50'})
|
|
47
|
+
client.start()
|
|
48
|
+
# Keep your application running. On shutdown:
|
|
49
|
+
# client.close()
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
See [Python API details](python/README.md). The Python worker starts explicitly; browser and Python lifecycle APIs differ while sharing the wire protocol and algorithm.
|
|
53
|
+
|
|
54
|
+
## Server integration
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
from lss_sync.backend import ReceiptStore
|
|
58
|
+
|
|
59
|
+
receipts = ReceiptStore('server.sqlite3')
|
|
60
|
+
# Authenticate in your web framework first. Derive account_id on the server.
|
|
61
|
+
result = receipts.apply_batch(request_body_bytes, namespace=account_id)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Return `result` as JSON. Each operation and its receipt commit atomically. The namespace must come from authenticated server context, never from an untrusted payload field. The SDK supplies neither account management nor a production web server.
|
|
65
|
+
|
|
66
|
+
## Supported data and behavior
|
|
67
|
+
|
|
68
|
+
Payloads are generic JSON: objects, arrays, strings, booleans, null and safe integers. Decimal quantities use strings. Both SDKs reject floats, cycles, invalid Unicode and nesting beyond 32 levels. Each complete encoded operation must fit 2 KiB. These restrictions keep serialization deterministic and retries bounded.
|
|
69
|
+
|
|
70
|
+
AES-256-GCM protects persisted payloads. A passphrase-derived key is retained in memory during the unlocked session. Adaptive batches start at 2 KiB, grow after two fast full acknowledgements, and halve after failure or slow transfer, up to 16 KiB. Fixed 2 KiB and 16 KiB policies remain available for comparison. Stable IDs, verified receipts, persistent queues and safe replay handle interruptions.
|
|
71
|
+
|
|
72
|
+
This is an upload-only append-only protocol. No attachments, edits/merging, key recovery or background operation after the application closes are included. The authorized server receives readable payloads over HTTPS. Offline encryption does not hide data from malicious code in an unlocked application.
|
|
73
|
+
|
|
74
|
+
## GitHub installation after publication
|
|
75
|
+
|
|
76
|
+
Install from the GitHub repository (the SDK is in the lss-sync subdirectory):
|
|
77
|
+
|
|
78
|
+
```sh
|
|
79
|
+
git clone https://github.com/Kingsum007/lss.git
|
|
80
|
+
npm install ./lss/lss-sync
|
|
81
|
+
python -m pip install 'git+https://github.com/Kingsum007/lss.git#subdirectory=lss-sync/python'
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The MIT License permits reuse under its terms. Preserve the copyright and license notice in redistributed copies.
|
|
85
|
+
|
|
86
|
+
## Validation
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
npm install
|
|
90
|
+
npm test
|
|
91
|
+
npm run typecheck
|
|
92
|
+
python -m pip install ./python
|
|
93
|
+
python -m unittest discover -s python/tests -v
|
|
94
|
+
npm run test:interop
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
The prior NBCC demo's benchmark results describe that earlier application, not this SDK. Re-run device and network measurements before making performance claims for integrations.
|
|
98
|
+
|
|
99
|
+
## Author and license
|
|
100
|
+
|
|
101
|
+
**Safi Ullah Mirzai**
|
|
102
|
+
MSc Computer Science, Kabul University; Instructor at the National Institute of Management and Administration (NIMA).
|
|
103
|
+
|
|
104
|
+
Copyright (c) 2026 Safi Ullah Mirzai. Licensed under [MIT](LICENSE).
|
package/docs/PROTOCOL.md
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# LSS protocol version 1
|
|
2
|
+
|
|
3
|
+
This specification describes the common behavior of the JavaScript/TypeScript and Python packages. A compatible implementation uses the same wire format, byte limits, encryption parameters, receipt checks, and batch-control rules. Local storage can differ: the browser package uses IndexedDB and Web Crypto; the Python package uses SQLite and `cryptography`.
|
|
4
|
+
|
|
5
|
+
Protocol compatibility means that either client can submit operations to the same compatible server. It does not make an IndexedDB database interchangeable with a SQLite file. Fixed cryptographic fixtures verify byte-level compatibility; they are test data, never production keys or IVs.
|
|
6
|
+
|
|
7
|
+
## Supported application data
|
|
8
|
+
|
|
9
|
+
A payload can contain:
|
|
10
|
+
|
|
11
|
+
- `null`, booleans, or Unicode strings without unpaired surrogates;
|
|
12
|
+
- integers from −9,007,199,254,740,991 through 9,007,199,254,740,991;
|
|
13
|
+
- arrays of supported values;
|
|
14
|
+
- objects with Unicode string keys and supported values.
|
|
15
|
+
|
|
16
|
+
Fractional numbers, Python `float` values, non-finite numbers, binary values, cyclic structures, and nesting deeper than 32 levels are rejected. Represent decimal quantities as strings, such as `"1250.75"`. Dates are application-defined strings, normally an ISO 8601 value. The SDK does not assume construction logs, inventory records, or any other business schema. An optional application validator can restrict what a particular project accepts.
|
|
17
|
+
|
|
18
|
+
Canonical serialization follows these rules:
|
|
19
|
+
|
|
20
|
+
1. Sort object keys by Unicode code-point order, recursively. Array order stays unchanged.
|
|
21
|
+
2. Use compact JSON, without insignificant whitespace.
|
|
22
|
+
3. Preserve Unicode text. Escape quotes, backslashes, and JSON control characters as required.
|
|
23
|
+
4. Do not trim strings or normalize Unicode. Two differently encoded strings remain different payloads.
|
|
24
|
+
5. Encode the result as UTF-8 for hashing and encryption.
|
|
25
|
+
|
|
26
|
+
Use the shared fixtures in `spec/` to check another language port. Matching an example visually is insufficient: serialized bytes, SHA-256 digests, and AES-GCM outputs must agree.
|
|
27
|
+
|
|
28
|
+
## Operation envelope
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
{
|
|
32
|
+
"operations": [
|
|
33
|
+
{
|
|
34
|
+
"id": "b1c64479-d242-426a-b069-2aca0c8e083e",
|
|
35
|
+
"schema": 1,
|
|
36
|
+
"payload": "{\"item\":\"cement\",\"quantity\":24}",
|
|
37
|
+
"digest": "<64 lowercase hexadecimal SHA-256 characters>"
|
|
38
|
+
}
|
|
39
|
+
]
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The example digest is a placeholder. A real client computes SHA-256 over the exact UTF-8 bytes of the `payload` string.
|
|
44
|
+
|
|
45
|
+
| Field | Meaning |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `id` | Stable, lowercase UUID assigned once to an immutable operation |
|
|
48
|
+
| `schema` | Protocol payload schema version, currently the integer `1` |
|
|
49
|
+
| `payload` | Canonical application JSON represented as a JSON **string** |
|
|
50
|
+
| `digest` | SHA-256 of the payload's UTF-8 bytes, in lowercase hexadecimal |
|
|
51
|
+
|
|
52
|
+
Wrapping the payload as a string allows the receiver to compare the exact client serialization without reformatting numbers or strings. The server still parses and validates the contained application JSON.
|
|
53
|
+
|
|
54
|
+
`POST /api/sync` in the examples accepts this envelope and returns JSON. The path and authentication mechanism belong to the host application; production transport must use HTTPS. Do not put credentials or payloads in query strings.
|
|
55
|
+
|
|
56
|
+
The complete encoded request body must fit the active batch limit. That count includes the envelope, IDs, schema fields, digests, JSON punctuation, and escaping of the nested payload string. Every individual operation must fit a 2,048-byte batch before it can be reported as saved. A server accepts at most 16,384 body bytes per batch.
|
|
57
|
+
|
|
58
|
+
## Local encryption and persistence
|
|
59
|
+
|
|
60
|
+
Each vault uses the following parameters:
|
|
61
|
+
|
|
62
|
+
| Parameter | Value |
|
|
63
|
+
|---|---|
|
|
64
|
+
| Cipher | AES-256-GCM |
|
|
65
|
+
| Authentication tag | 128 bits, appended to ciphertext |
|
|
66
|
+
| Record IV | Fresh random 12-byte value |
|
|
67
|
+
| Passphrase derivation | PBKDF2-HMAC-SHA256, 600,000 iterations |
|
|
68
|
+
| Salt | Random 16-byte value created with the vault |
|
|
69
|
+
| Record additional authenticated data | UTF-8 compact JSON `[operationId, 1]` |
|
|
70
|
+
| Key-check plaintext | `LSS vault verification v1` |
|
|
71
|
+
| Key-check additional authenticated data | UTF-8 `LSS key-check v1` |
|
|
72
|
+
|
|
73
|
+
The stored vault configuration includes `version`, `keyVersion`, `iterations`, and base64 values for `salt`, `checkIv`, and `check`. The encrypted key check verifies a derived key at unlock. The passphrase and raw key are not intentionally persisted.
|
|
74
|
+
|
|
75
|
+
Reserve the key-check IV and every record IV in a uniqueness store keyed by `(keyVersion, IV)`. A local save performs encryption first, then commits the IV reservation, ciphertext, and outgoing queue item in one transaction. A conflicting IV requires fresh encryption with a new IV. An aborted transaction must never be reported as a completed save.
|
|
76
|
+
|
|
77
|
+
Only bounded batches are decrypted for synchronization. Decryption failure retains the record as `BLOCKED`; other valid records can proceed. IDs, sizes, queue states, and timing metadata are not covered by the payload-confidentiality claim.
|
|
78
|
+
|
|
79
|
+
## Queue states and recovery
|
|
80
|
+
|
|
81
|
+
| State | Meaning |
|
|
82
|
+
|---|---|
|
|
83
|
+
| `PENDING` | Stored locally and eligible for an attempt when due |
|
|
84
|
+
| `IN_FLIGHT` | Selection committed locally before request dispatch |
|
|
85
|
+
| `ACKNOWLEDGED` | Matching committed receipt verified and the local state update committed |
|
|
86
|
+
| `BLOCKED` | Retained record requiring attention because of corruption or a permanent rejection |
|
|
87
|
+
|
|
88
|
+
Recover unfinished `IN_FLIGHT` items as `PENDING` before a new worker processes the queue. A timeout or missing receipt requeues the same operation IDs. Do not discard a record because a retry count has been exceeded.
|
|
89
|
+
|
|
90
|
+
The browser uses Web Locks to serialize senders sharing a vault. Python uses a local synchronization lock around a step. Other ports must provide equivalent exclusion for their persistence adapter. The network can still deliver the same operation more than once; server idempotency is required.
|
|
91
|
+
|
|
92
|
+
## Receipts and independent server commits
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"receipts": [
|
|
97
|
+
{
|
|
98
|
+
"id": "b1c64479-d242-426a-b069-2aca0c8e083e",
|
|
99
|
+
"digest": "<matching payload digest>",
|
|
100
|
+
"status": "COMMITTED",
|
|
101
|
+
"committedAt": "2026-11-17T00:00:00.000Z"
|
|
102
|
+
}
|
|
103
|
+
],
|
|
104
|
+
"errors": []
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Before acknowledging a record, the client checks that the receipt ID belongs to the attempted batch, its digest matches that operation, and its status is `COMMITTED`. Missing or invalid receipts leave records eligible for replay. A permanent per-operation error has `id`, `code`, and `permanent: true`; the record remains stored as `BLOCKED`.
|
|
109
|
+
|
|
110
|
+
A compatible server applies each operation independently:
|
|
111
|
+
|
|
112
|
+
1. Authenticate the request and derive its namespace from trusted server-side identity.
|
|
113
|
+
2. Validate the envelope, schema, canonical payload, size, and recomputed digest.
|
|
114
|
+
3. Begin a database transaction and look up `(namespace, operationId)`.
|
|
115
|
+
4. If it exists with the same schema, exact payload, and digest, return its stored receipt. If the content differs, reject it as `ID_CONFLICT` without changing the original.
|
|
116
|
+
5. Otherwise insert the entry and its receipt atomically.
|
|
117
|
+
6. Commit before including the receipt in the response.
|
|
118
|
+
|
|
119
|
+
The client does not choose an authoritative namespace in the wire envelope. The host server maps its authenticated account or tenant to that namespace. Namespace separation is not a replacement for authentication or business authorization.
|
|
120
|
+
|
|
121
|
+
Earlier records in a batch may be committed before a later failure. A lost response therefore causes replay under the same IDs. This produces at most one logical entry per retained ID and namespace; it does not promise exactly-once network delivery.
|
|
122
|
+
|
|
123
|
+
## Batch adaptation
|
|
124
|
+
|
|
125
|
+
Let `B` be the maximum encoded request-body bytes, initially 2,048. Let `s` be the count of consecutive full, fast batches in which every selected operation was acknowledged.
|
|
126
|
+
|
|
127
|
+
```text
|
|
128
|
+
if an attempt fails transiently or duration > 8,000 ms:
|
|
129
|
+
B = max(2,048, floor(B / 2))
|
|
130
|
+
s = 0
|
|
131
|
+
else if full and every selected operation was acknowledged:
|
|
132
|
+
s = s + 1
|
|
133
|
+
if s == 2:
|
|
134
|
+
B = min(16,384, B + 2,048)
|
|
135
|
+
s = 0
|
|
136
|
+
else:
|
|
137
|
+
s = 0
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
A batch is full when the next eligible record would not fit. A queue-tail batch is sent immediately and does not cause growth merely because it succeeds. A slow acknowledged operation remains acknowledged; only the next limit shrinks. The fixed comparison modes keep the limit at 2,048 or 16,384 bytes while retaining all other mechanisms.
|
|
141
|
+
|
|
142
|
+
The timeout is 30 seconds. Retry delay uses full jitter with a ceiling of `min(30,000, 1,000 × 2^(retryCount−1))` milliseconds. A scheduled retry may have a small implementation scheduling floor. Prompt connection/resume notifications are debounced; a persisted server `Retry-After` deadline always takes precedence.
|
|
143
|
+
|
|
144
|
+
The browser must remain open and unlocked. The Python sender must remain running and unlocked. Total disconnection cannot carry data: valid queued records remain until a complete exchange becomes possible. Each implementation exposes its lifecycle explicitly so the host application can resume it after startup.
|
package/docs/SECURITY.md
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Security model
|
|
2
|
+
|
|
3
|
+
LSS protects persisted client payloads and coordinates replay-safe delivery. The SDK uses established cryptographic primitives; it is not a new encryption algorithm or a complete account/security system.
|
|
4
|
+
|
|
5
|
+
## What the SDK protects
|
|
6
|
+
|
|
7
|
+
AES-256-GCM encrypts each payload before the local save transaction. The record ID and schema are authenticated additional data. A changed ciphertext, mismatched ID/schema, or incorrect key fails authenticated decryption. Unique IV reservations include the vault key-check IV and commit atomically with record data.
|
|
8
|
+
|
|
9
|
+
A copied locked vault does not intentionally contain its passphrase or raw key. PBKDF2-HMAC-SHA256 derives the key from a passphrase and random salt. Password guessing remains possible against copied encrypted storage; users need a strong passphrase. The fixed initial work factor must be evaluated on target devices.
|
|
10
|
+
|
|
11
|
+
An operation keeps its ID on replay. The server's atomic entry/receipt transaction and exact payload comparison prevent duplicate logical inserts within an authenticated namespace, assuming the server retains its identity records. The SHA-256 digest identifies payload bytes; it is not a substitute for server authentication, TLS, or a cryptographic message signature.
|
|
12
|
+
|
|
13
|
+
## Boundaries
|
|
14
|
+
|
|
15
|
+
The authorized main server receives readable application data over HTTPS. This is client encryption at rest plus encrypted transport, not end-to-end encryption that hides the data from the server. Server storage, access policies, backups, and log handling belong to the host application.
|
|
16
|
+
|
|
17
|
+
Identifiers, record lengths, queue states, and timestamps remain visible local metadata. Malicious JavaScript executing in an unlocked page, a compromised operating system, or an attacker controlling the host process can access readable data. The SDK cannot protect against those conditions.
|
|
18
|
+
|
|
19
|
+
The browser uses a non-extractable Web Crypto key. Python holds key bytes in process memory. Neither JavaScript garbage collection nor ordinary Python objects provide a guarantee that every temporary key/plaintext buffer is immediately erased. Locking releases the SDK's key reference and prevents later dispatch. It cannot recall a request already transmitted; an in-progress Python HTTP request may complete within its timeout. Recovery handles a server commit whose receipt was not saved locally.
|
|
20
|
+
|
|
21
|
+
## Host application responsibilities
|
|
22
|
+
|
|
23
|
+
- Authenticate requests and derive server namespaces from that trusted identity. Never accept an arbitrary client namespace as authorization.
|
|
24
|
+
- Apply project-specific authorization and payload validation before accepting business records. The generic JSON schema validates structure, not permissions or business meaning.
|
|
25
|
+
- Serve the browser application and API over HTTPS. Protect against injected scripts and avoid logging passphrases, bearer tokens, readable payloads, or decrypted snapshots.
|
|
26
|
+
- Define how users handle lost passphrases, browser eviction, disk loss, backups, and acknowledged-record retention. This preview does not provide key recovery or rotation.
|
|
27
|
+
|
|
28
|
+
The browser vault is scoped to its origin and database name. A multi-account app must choose separate vault identities and a clear sign-out policy, while retaining any unsynchronized records that still need delivery. Browser persistence can be cleared or evicted.
|
|
29
|
+
|
|
30
|
+
## Examples and reporting
|
|
31
|
+
|
|
32
|
+
The included loopback server and sample token demonstrate the protocol with synthetic records. They are not a public account service. Keep reference HTTP servers isolated; use a production deployment and abuse controls before accepting public real-world traffic.
|
|
33
|
+
|
|
34
|
+
No project security-contact address is configured yet. Before public release, the maintainer should enable a private vulnerability-reporting channel in the repository and document it here. Reports should include a minimal reproduction and synthetic data; do not publish tokens, real records, or private vaults in an issue.
|
|
35
|
+
|
|
36
|
+
The test suite demonstrates selected failure cases. Passing tests is not a comprehensive security audit or a guarantee of confidentiality on a compromised device.
|
package/package.json
CHANGED
|
@@ -1,6 +1,50 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "lss-sync",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "lss-sync",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Lightweight encrypted offline synchronization SDK for browser applications",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./src/index.js",
|
|
7
|
+
"types": "./src/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./src/index.d.ts",
|
|
11
|
+
"import": "./src/index.js"
|
|
12
|
+
},
|
|
13
|
+
"./policy": {
|
|
14
|
+
"types": "./src/policy.d.ts",
|
|
15
|
+
"import": "./src/policy.js"
|
|
16
|
+
}
|
|
17
|
+
},
|
|
18
|
+
"files": [
|
|
19
|
+
"src",
|
|
20
|
+
"README.md",
|
|
21
|
+
"LICENSE",
|
|
22
|
+
"docs/PROTOCOL.md",
|
|
23
|
+
"docs/SECURITY.md"
|
|
24
|
+
],
|
|
25
|
+
"sideEffects": false,
|
|
26
|
+
"license": "MIT",
|
|
27
|
+
"engines": {
|
|
28
|
+
"node": ">=20.19"
|
|
29
|
+
},
|
|
30
|
+
"scripts": {
|
|
31
|
+
"test": "node --test tests/core.test.mjs",
|
|
32
|
+
"test:browser": "node tests/browser.mjs",
|
|
33
|
+
"test:interop": "node tests/interop.mjs",
|
|
34
|
+
"typecheck": "tsc --noEmit --strict --target es2022 --module nodenext --lib es2022,dom tests/types.ts"
|
|
35
|
+
},
|
|
36
|
+
"devDependencies": {
|
|
37
|
+
"typescript": "~5.9.3",
|
|
38
|
+
"playwright": "^1.56.1"
|
|
39
|
+
},
|
|
40
|
+
"author": "Safi Ullah Mirzai",
|
|
41
|
+
"repository": {
|
|
42
|
+
"type": "git",
|
|
43
|
+
"url": "git+https://github.com/Kingsum007/lss.git",
|
|
44
|
+
"directory": "lss-sync"
|
|
45
|
+
},
|
|
46
|
+
"homepage": "https://github.com/Kingsum007/lss/tree/main/lss-sync",
|
|
47
|
+
"bugs": {
|
|
48
|
+
"url": "https://github.com/Kingsum007/lss/issues"
|
|
49
|
+
}
|
|
50
|
+
}
|
package/src/crypto.js
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { encoder, decoder, base64, unbase64, aad } from './encoding.js';
|
|
2
|
+
|
|
3
|
+
export const ITERATIONS = 600000;
|
|
4
|
+
const CHECK = 'LSS vault verification v1';
|
|
5
|
+
const CHECK_AAD = encoder.encode('LSS key-check v1');
|
|
6
|
+
|
|
7
|
+
export async function deriveKey(passphrase, salt, iterations = ITERATIONS) {
|
|
8
|
+
if (typeof passphrase !== 'string' || !passphrase.isWellFormed() || Array.from(passphrase).length < 12) throw new Error('Use a valid Unicode passphrase of at least 12 characters.');
|
|
9
|
+
const material = await crypto.subtle.importKey('raw', encoder.encode(passphrase), 'PBKDF2', false, ['deriveKey']);
|
|
10
|
+
return crypto.subtle.deriveKey({ name: 'PBKDF2', salt, iterations, hash: 'SHA-256' }, material,
|
|
11
|
+
{ name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export async function createVault(passphrase) {
|
|
15
|
+
const salt = crypto.getRandomValues(new Uint8Array(16));
|
|
16
|
+
const key = await deriveKey(passphrase, salt);
|
|
17
|
+
const iv = crypto.getRandomValues(new Uint8Array(12));
|
|
18
|
+
const check = await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: CHECK_AAD }, key, encoder.encode(CHECK));
|
|
19
|
+
return { key, config: { name: 'vault', version: 1, keyVersion: crypto.randomUUID(), iterations: ITERATIONS,
|
|
20
|
+
salt: base64(salt), checkIv: base64(iv), check: base64(check) } };
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export async function unlockVault(passphrase, config) {
|
|
24
|
+
if (config.version !== 1 || config.iterations !== ITERATIONS) throw new Error('Unsupported vault configuration.');
|
|
25
|
+
try {
|
|
26
|
+
const key = await deriveKey(passphrase, unbase64(config.salt), config.iterations);
|
|
27
|
+
const check = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: unbase64(config.checkIv), additionalData: CHECK_AAD }, key, unbase64(config.check));
|
|
28
|
+
if (decoder.decode(check) !== CHECK) throw new Error();
|
|
29
|
+
return key;
|
|
30
|
+
} catch { throw new Error('Cannot unlock. Check your passphrase; the vault may also be damaged.'); }
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export async function encryptRecord(key, id, payload, schema = 1) {
|
|
34
|
+
const iv = crypto.getRandomValues(new Uint8Array(12));
|
|
35
|
+
const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: aad(id, schema) }, key, encoder.encode(payload));
|
|
36
|
+
return { iv: base64(iv), ciphertext };
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export async function decryptRecord(key, record) {
|
|
40
|
+
const plain = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: unbase64(record.iv), additionalData: aad(record.id, record.schema) }, key, record.ciphertext);
|
|
41
|
+
return decoder.decode(plain);
|
|
42
|
+
}
|
package/src/encoding.js
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
export const encoder = new TextEncoder();
|
|
2
|
+
export const decoder = new TextDecoder('utf-8', { fatal: true });
|
|
3
|
+
export const MIN_BATCH = 2048;
|
|
4
|
+
export const MAX_BATCH = 16384;
|
|
5
|
+
export const SCHEMA = 1;
|
|
6
|
+
|
|
7
|
+
export function byteLength(value) { return encoder.encode(value).byteLength; }
|
|
8
|
+
export function hex(bytes) { return [...new Uint8Array(bytes)].map(b => b.toString(16).padStart(2, '0')).join(''); }
|
|
9
|
+
export function base64(bytes) { return btoa(String.fromCharCode(...new Uint8Array(bytes))); }
|
|
10
|
+
export function unbase64(text) { return Uint8Array.from(atob(text), c => c.charCodeAt(0)); }
|
|
11
|
+
export async function digest(text) { return hex(await crypto.subtle.digest('SHA-256', encoder.encode(text))); }
|
|
12
|
+
export function encodeBatch(operations) { return JSON.stringify({ operations }); }
|
|
13
|
+
export function aad(id, schema = SCHEMA) { return encoder.encode(JSON.stringify([id, schema])); }
|
|
14
|
+
|
|
15
|
+
function compareCodePoints(a, b) {
|
|
16
|
+
const left = Array.from(a), right = Array.from(b);
|
|
17
|
+
for (let i = 0; i < Math.min(left.length, right.length); i++) {
|
|
18
|
+
const delta = left[i].codePointAt(0) - right[i].codePointAt(0);
|
|
19
|
+
if (delta) return delta;
|
|
20
|
+
}
|
|
21
|
+
return left.length - right.length;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
// LSS-JSON/1 is deliberately small and identical across SDKs. It preserves
|
|
25
|
+
// strings, sorts keys by Unicode code point, and accepts only safe integers.
|
|
26
|
+
// Decimal quantities should be strings. This is not a claim of RFC 8785 JCS.
|
|
27
|
+
export function canonicalPayload(input) {
|
|
28
|
+
const active = new Set();
|
|
29
|
+
const encode = (value, depth) => {
|
|
30
|
+
if (depth > 32) throw new TypeError('JSON nesting exceeds 32 levels.');
|
|
31
|
+
if (value === null) return 'null';
|
|
32
|
+
if (typeof value === 'boolean') return value ? 'true' : 'false';
|
|
33
|
+
if (typeof value === 'string') {
|
|
34
|
+
if (!value.isWellFormed()) throw new TypeError('Strings must contain valid Unicode.');
|
|
35
|
+
return JSON.stringify(value);
|
|
36
|
+
}
|
|
37
|
+
if (typeof value === 'number') {
|
|
38
|
+
if (!Number.isSafeInteger(value)) throw new TypeError('Only safe integers are supported. Encode decimal quantities as strings.');
|
|
39
|
+
return String(Object.is(value, -0) ? 0 : value);
|
|
40
|
+
}
|
|
41
|
+
if (typeof value !== 'object') throw new TypeError('Only JSON values are supported.');
|
|
42
|
+
if (active.has(value)) throw new TypeError('Cyclic data cannot be synchronized.');
|
|
43
|
+
if (Object.getOwnPropertySymbols(value).length) throw new TypeError('Symbol properties are not JSON.');
|
|
44
|
+
active.add(value);
|
|
45
|
+
let encoded;
|
|
46
|
+
if (Array.isArray(value)) {
|
|
47
|
+
if (Object.keys(value).length !== value.length) throw new TypeError('Sparse arrays or extra array properties are not supported.');
|
|
48
|
+
encoded = '[' + Array.from(value, item => encode(item, depth + 1)).join(',') + ']';
|
|
49
|
+
} else {
|
|
50
|
+
if (![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new TypeError('Use plain JSON objects.');
|
|
51
|
+
encoded = '{' + Object.keys(value).sort(compareCodePoints).map(key => {
|
|
52
|
+
if (!key.isWellFormed()) throw new TypeError('Object keys must contain valid Unicode.');
|
|
53
|
+
return JSON.stringify(key) + ':' + encode(value[key], depth + 1);
|
|
54
|
+
}).join(',') + '}';
|
|
55
|
+
}
|
|
56
|
+
active.delete(value);
|
|
57
|
+
return encoded;
|
|
58
|
+
};
|
|
59
|
+
return encode(input, 0);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export function assertFits(operation) {
|
|
63
|
+
const bytes = byteLength(encodeBatch([operation]));
|
|
64
|
+
if (bytes > MIN_BATCH) throw new Error('The encoded operation exceeds 2 KiB. Reduce the payload size.');
|
|
65
|
+
return bytes;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export async function createOperation(value, id = crypto.randomUUID()) {
|
|
69
|
+
if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(id)) throw new TypeError('Use a lowercase UUID for the operation ID.');
|
|
70
|
+
const payload = canonicalPayload(value);
|
|
71
|
+
const operation = { id, schema: SCHEMA, payload, digest: await digest(payload) };
|
|
72
|
+
assertFits(operation);
|
|
73
|
+
return operation;
|
|
74
|
+
}
|
package/src/engine.js
ADDED
|
@@ -0,0 +1,333 @@
|
|
|
1
|
+
import { Store } from './store.js';
|
|
2
|
+
import { createVault, unlockVault, encryptRecord, decryptRecord } from './crypto.js';
|
|
3
|
+
import { canonicalPayload, digest, assertFits, byteLength, encodeBatch, SCHEMA } from './encoding.js';
|
|
4
|
+
import { BatchPolicy, retryDelay, retryAfter } from './policy.js';
|
|
5
|
+
|
|
6
|
+
const PERMANENT = new Set(['ID_CONFLICT', 'INVALID_OPERATION', 'INVALID_PAYLOAD', 'INVALID_DIGEST', 'BAD_DIGEST', 'INVALID_ID', 'INVALID_SCHEMA', 'UNSUPPORTED_SCHEMA', 'VALIDATION_ERROR']);
|
|
7
|
+
const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
|
|
8
|
+
|
|
9
|
+
export class SyncEngine extends EventTarget {
|
|
10
|
+
#key = null;
|
|
11
|
+
#epoch = 0;
|
|
12
|
+
#token = '';
|
|
13
|
+
|
|
14
|
+
constructor({ dbName = 'lss-v1', endpoint = '/api/sync', token = '', policy = 'adaptive', transport = globalThis.fetch.bind(globalThis), timeoutMs = 30000, random = Math.random, validator = null } = {}) {
|
|
15
|
+
super();
|
|
16
|
+
this.store = new Store(dbName);
|
|
17
|
+
this.dbName = dbName;
|
|
18
|
+
this.endpoint = new URL(endpoint, location.href);
|
|
19
|
+
if (this.endpoint.origin !== location.origin) throw new Error('Use a same-origin synchronization endpoint.');
|
|
20
|
+
if (this.endpoint.protocol !== 'https:' && !LOOPBACK.has(this.endpoint.hostname)) throw new Error('Synchronization requires HTTPS outside the local demo.');
|
|
21
|
+
this.#token = token;
|
|
22
|
+
this.transport = transport;
|
|
23
|
+
this.timeoutMs = timeoutMs;
|
|
24
|
+
this.random = random;
|
|
25
|
+
if (validator !== null && typeof validator !== 'function') throw new TypeError('validator must be a synchronous function.');
|
|
26
|
+
this.validator = validator;
|
|
27
|
+
this.policy = new BatchPolicy(policy);
|
|
28
|
+
this.phase = 'LOCKED';
|
|
29
|
+
this.lastError = '';
|
|
30
|
+
this.metrics = { attempts: 0, requestBytes: 0, responseBytes: 0, lastDurationMs: 0, unlockMs: 0, lastSaveMs: 0 };
|
|
31
|
+
this._running = false;
|
|
32
|
+
this._busy = false;
|
|
33
|
+
this._recovered = false;
|
|
34
|
+
this._lastAttempt = 0;
|
|
35
|
+
this._authPaused = false;
|
|
36
|
+
this._wake = () => { if (document.visibilityState !== 'hidden') this.kick(); };
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
get unlocked() { return this.#key !== null; }
|
|
40
|
+
_emit() { this.dispatchEvent(new Event('change')); }
|
|
41
|
+
|
|
42
|
+
async init() {
|
|
43
|
+
if (!globalThis.crypto?.subtle || !globalThis.indexedDB || !navigator.locks) throw new Error('Open this application in a current browser on HTTPS or localhost.');
|
|
44
|
+
await this.store.open();
|
|
45
|
+
this.config = await this.store.getConfig();
|
|
46
|
+
this.phase = this.config ? 'LOCKED' : 'SETUP';
|
|
47
|
+
this._emit();
|
|
48
|
+
return { configured: !!this.config };
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
async setup(passphrase) {
|
|
52
|
+
const epoch = ++this.#epoch;
|
|
53
|
+
const started = performance.now();
|
|
54
|
+
const prepared = await createVault(passphrase);
|
|
55
|
+
if (epoch !== this.#epoch) throw new Error('Unlock was cancelled.');
|
|
56
|
+
await this.store.createVault(prepared.config);
|
|
57
|
+
this.config = prepared.config;
|
|
58
|
+
if (epoch !== this.#epoch) throw new Error('The vault was created. Unlock it to continue.');
|
|
59
|
+
this.#key = prepared.key;
|
|
60
|
+
this.metrics.unlockMs = performance.now() - started;
|
|
61
|
+
this._recovered = false;
|
|
62
|
+
this.phase = 'IDLE';
|
|
63
|
+
this.lastError = '';
|
|
64
|
+
this.start(); this._emit();
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
async unlock(passphrase) {
|
|
68
|
+
if (this.unlocked) return;
|
|
69
|
+
const epoch = ++this.#epoch;
|
|
70
|
+
this.config = await this.store.getConfig();
|
|
71
|
+
if (epoch !== this.#epoch) throw new Error('Unlock was cancelled.');
|
|
72
|
+
if (!this.config) throw new Error('Create a local vault first.');
|
|
73
|
+
const started = performance.now();
|
|
74
|
+
const key = await unlockVault(passphrase, this.config);
|
|
75
|
+
if (epoch !== this.#epoch) throw new Error('Unlock was cancelled.');
|
|
76
|
+
this.#key = key;
|
|
77
|
+
this.metrics.unlockMs = performance.now() - started;
|
|
78
|
+
this.policy.setMode(this.policy.mode);
|
|
79
|
+
this._recovered = false;
|
|
80
|
+
this.phase = 'IDLE'; this.lastError = '';
|
|
81
|
+
this.start(); this._emit();
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
lock() {
|
|
85
|
+
++this.#epoch;
|
|
86
|
+
this.#key = null;
|
|
87
|
+
this._controller?.abort();
|
|
88
|
+
clearTimeout(this._timer);
|
|
89
|
+
this.phase = this.config ? 'LOCKED' : 'SETUP';
|
|
90
|
+
this.lastError = '';
|
|
91
|
+
this._emit();
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
setToken(token) { this.#token = String(token); this._authPaused = false; if (this.unlocked) this.kick(); }
|
|
95
|
+
setPolicy(mode) { if (this._busy) throw new Error('Wait for the current transfer before changing policy.'); this.policy.setMode(mode); this._emit(); }
|
|
96
|
+
|
|
97
|
+
async save(input) {
|
|
98
|
+
if (!this.#key) throw new Error('Unlock your local vault before saving.');
|
|
99
|
+
const epoch = this.#epoch;
|
|
100
|
+
const key = this.#key;
|
|
101
|
+
const started = performance.now();
|
|
102
|
+
const payload = canonicalPayload(input);
|
|
103
|
+
this._validate(JSON.parse(payload));
|
|
104
|
+
const id = crypto.randomUUID();
|
|
105
|
+
const operation = { id, schema: SCHEMA, payload, digest: await digest(payload) };
|
|
106
|
+
const bytes = assertFits(operation);
|
|
107
|
+
// A rare IV-index collision causes a fresh encryption. Never reuse the IV,
|
|
108
|
+
// report success before transaction commit, or fall back to plaintext.
|
|
109
|
+
for (let attempt = 0; attempt < 4; attempt++) {
|
|
110
|
+
const encrypted = await encryptRecord(key, id, payload);
|
|
111
|
+
if (epoch !== this.#epoch || !this.#key) throw new Error('The vault was locked before the save completed.');
|
|
112
|
+
try {
|
|
113
|
+
await this.store.save({ id, schema: SCHEMA, keyVersion: this.config.keyVersion, ...encrypted, createdAt: new Date().toISOString() }, bytes);
|
|
114
|
+
this.metrics.lastSaveMs = performance.now() - started;
|
|
115
|
+
this.kick(); this._emit();
|
|
116
|
+
return { id, saveMs: this.metrics.lastSaveMs };
|
|
117
|
+
} catch (error) {
|
|
118
|
+
if (error.name === 'ConstraintError' && attempt < 3) continue;
|
|
119
|
+
this.lastError = 'The record could not be committed locally. Keep the form open and try again.';
|
|
120
|
+
this._emit();
|
|
121
|
+
throw error;
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
throw new Error('Unable to reserve a unique encryption IV.');
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
_validate(value) {
|
|
128
|
+
if (!this.validator) return;
|
|
129
|
+
const result = this.validator(value);
|
|
130
|
+
if (result && typeof result.then === 'function') throw new TypeError('The payload validator must be synchronous.');
|
|
131
|
+
if (result === false) throw new Error('The payload was rejected by the application validator.');
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
start() {
|
|
135
|
+
if (!this._running) {
|
|
136
|
+
this._running = true;
|
|
137
|
+
addEventListener('online', this._wake);
|
|
138
|
+
addEventListener('focus', this._wake);
|
|
139
|
+
document.addEventListener('visibilitychange', this._wake);
|
|
140
|
+
}
|
|
141
|
+
this.kick();
|
|
142
|
+
}
|
|
143
|
+
stop() {
|
|
144
|
+
this._running = false;
|
|
145
|
+
clearTimeout(this._timer);
|
|
146
|
+
this._controller?.abort();
|
|
147
|
+
removeEventListener('online', this._wake);
|
|
148
|
+
removeEventListener('focus', this._wake);
|
|
149
|
+
document.removeEventListener('visibilitychange', this._wake);
|
|
150
|
+
}
|
|
151
|
+
kick() {
|
|
152
|
+
if (!this._running || !this.unlocked || this._authPaused) return;
|
|
153
|
+
this._promptRequested = true;
|
|
154
|
+
this._schedule(Math.max(0, 1000 - (Date.now() - this._lastAttempt)));
|
|
155
|
+
}
|
|
156
|
+
_schedule(delay = 0) {
|
|
157
|
+
clearTimeout(this._timer);
|
|
158
|
+
if (!this._running || !this.unlocked || this._authPaused) return;
|
|
159
|
+
this._timer = setTimeout(() => { void this._loop(); }, Math.min(Math.max(0, delay), 2147483647));
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
async _loop() {
|
|
163
|
+
if (this._busy || !this._running || !this.unlocked || this._authPaused) return;
|
|
164
|
+
this._busy = true;
|
|
165
|
+
let delay = 1000;
|
|
166
|
+
try {
|
|
167
|
+
const acquired = await navigator.locks.request(`lss-sync:${this.dbName}`, { ifAvailable: true }, async lock => {
|
|
168
|
+
if (!lock) return false;
|
|
169
|
+
if (!this.unlocked || !this._running) return true;
|
|
170
|
+
if (!this._recovered) { await this.store.recover(); this._recovered = true; }
|
|
171
|
+
const prompt = !!this._promptRequested;
|
|
172
|
+
this._promptRequested = false;
|
|
173
|
+
delay = await this._step(prompt);
|
|
174
|
+
return true;
|
|
175
|
+
});
|
|
176
|
+
if (!acquired) delay = 1000;
|
|
177
|
+
} catch {
|
|
178
|
+
this._recovered = false;
|
|
179
|
+
if (this.unlocked) {
|
|
180
|
+
this.phase = 'STORAGE_ERROR';
|
|
181
|
+
this.lastError = 'Storage is unavailable. Saved records remain queued; recovery will retry.';
|
|
182
|
+
}
|
|
183
|
+
delay = 5000;
|
|
184
|
+
this._emit();
|
|
185
|
+
} finally {
|
|
186
|
+
this._busy = false;
|
|
187
|
+
if (this._promptRequested) delay = Math.min(delay, Math.max(0, 1000 - (Date.now() - this._lastAttempt)));
|
|
188
|
+
this._schedule(delay);
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
async _select(prompt) {
|
|
193
|
+
const key = this.#key;
|
|
194
|
+
const epoch = this.#epoch;
|
|
195
|
+
const operations = [];
|
|
196
|
+
let seq = 0, full = false;
|
|
197
|
+
while (this.unlocked && epoch === this.#epoch) {
|
|
198
|
+
const item = await this.store.nextDue(seq, prompt ? Number.MAX_SAFE_INTEGER : Date.now());
|
|
199
|
+
if (!item) break;
|
|
200
|
+
seq = item.seq;
|
|
201
|
+
const record = await this.store.getRecord(item.id);
|
|
202
|
+
let operation;
|
|
203
|
+
try {
|
|
204
|
+
if (!record || record.keyVersion !== this.config.keyVersion) throw new Error();
|
|
205
|
+
const payload = await decryptRecord(key, record);
|
|
206
|
+
if (canonicalPayload(JSON.parse(payload)) !== payload) throw new Error();
|
|
207
|
+
this._validate(JSON.parse(payload));
|
|
208
|
+
operation = { id: record.id, schema: record.schema, payload, digest: await digest(payload) };
|
|
209
|
+
assertFits(operation);
|
|
210
|
+
} catch {
|
|
211
|
+
if (epoch !== this.#epoch) break;
|
|
212
|
+
await this.store.transition([item.id], row => ({ ...row, state: 'BLOCKED', error: 'LOCAL_INTEGRITY_ERROR' }));
|
|
213
|
+
this._emit();
|
|
214
|
+
continue;
|
|
215
|
+
}
|
|
216
|
+
if (byteLength(encodeBatch([...operations, operation])) > this.policy.bytes) { full = true; break; }
|
|
217
|
+
operations.push(operation);
|
|
218
|
+
}
|
|
219
|
+
if (epoch !== this.#epoch || !this.unlocked) return { operations: [], full: false };
|
|
220
|
+
return { operations, full };
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
async _step(prompt = false) {
|
|
224
|
+
if (!this.#token) { this.phase = 'AUTH_REQUIRED'; this._authPaused = true; this._emit(); return 30000; }
|
|
225
|
+
const gate = await this.store.getConfig('retryGate');
|
|
226
|
+
if (gate?.until > Date.now()) { this.phase = 'WAITING'; this._emit(); return gate.until - Date.now(); }
|
|
227
|
+
const { operations, full } = await this._select(prompt);
|
|
228
|
+
if (!this.unlocked || !this._running) return 30000;
|
|
229
|
+
if (!operations.length) {
|
|
230
|
+
const due = await this.store.earliestDue();
|
|
231
|
+
this.phase = due === null ? 'IDLE' : 'WAITING'; this._emit();
|
|
232
|
+
return due === null ? 30000 : Math.max(10, due - Date.now());
|
|
233
|
+
}
|
|
234
|
+
const ids = operations.map(o => o.id);
|
|
235
|
+
const expected = new Map(operations.map(o => [o.id, o.digest]));
|
|
236
|
+
const body = encodeBatch(operations);
|
|
237
|
+
await this.store.transition(ids, row => ({ ...row, state: 'IN_FLIGHT' }));
|
|
238
|
+
if (!this.unlocked || !this._running) { await this.store.transition(ids, row => ({ ...row, state: 'PENDING' })); return 30000; }
|
|
239
|
+
this.phase = 'SYNCING'; this.lastError = '';
|
|
240
|
+
this._lastAttempt = Date.now();
|
|
241
|
+
this.metrics.attempts++;
|
|
242
|
+
this.metrics.requestBytes += byteLength(body);
|
|
243
|
+
this._emit();
|
|
244
|
+
const began = performance.now();
|
|
245
|
+
const controller = new AbortController(); this._controller = controller;
|
|
246
|
+
const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
|
|
247
|
+
let reply, status = 0, gateUntil = 0, networkFailure = false;
|
|
248
|
+
try {
|
|
249
|
+
const response = await this.transport(this.endpoint.href, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${this.#token}` },
|
|
250
|
+
body, cache: 'no-store', credentials: 'omit', redirect: 'error', signal: controller.signal });
|
|
251
|
+
status = response.status;
|
|
252
|
+
if ([429, 503].includes(status)) gateUntil = retryAfter(response.headers.get('Retry-After'));
|
|
253
|
+
// Bound the response as well as the outgoing plaintext batch.
|
|
254
|
+
const reader = response.body?.getReader();
|
|
255
|
+
let text = '', size = 0;
|
|
256
|
+
if (reader) {
|
|
257
|
+
const decode = new TextDecoder();
|
|
258
|
+
while (true) {
|
|
259
|
+
const { done, value } = await reader.read();
|
|
260
|
+
if (done) break;
|
|
261
|
+
size += value.byteLength;
|
|
262
|
+
if (size > 65536) { await reader.cancel(); throw new Error('Response too large.'); }
|
|
263
|
+
text += decode.decode(value, { stream: true });
|
|
264
|
+
}
|
|
265
|
+
text += decode.decode();
|
|
266
|
+
}
|
|
267
|
+
this.metrics.responseBytes += size;
|
|
268
|
+
if (response.ok) reply = JSON.parse(text);
|
|
269
|
+
else networkFailure = true;
|
|
270
|
+
} catch { networkFailure = true; }
|
|
271
|
+
finally { clearTimeout(timeout); if (this._controller === controller) this._controller = null; }
|
|
272
|
+
const durationMs = performance.now() - began;
|
|
273
|
+
this.metrics.lastDurationMs = durationMs;
|
|
274
|
+
if (gateUntil) await this.store.putConfig({ name: 'retryGate', until: gateUntil });
|
|
275
|
+
|
|
276
|
+
const acknowledged = new Set(), blocked = new Map();
|
|
277
|
+
if (reply && Array.isArray(reply.receipts) && Array.isArray(reply.errors)) {
|
|
278
|
+
for (const receipt of reply.receipts) {
|
|
279
|
+
if (receipt && receipt.status === 'COMMITTED' && expected.has(receipt.id) && receipt.digest === expected.get(receipt.id)) acknowledged.add(receipt.id);
|
|
280
|
+
}
|
|
281
|
+
for (const error of reply.errors) {
|
|
282
|
+
if (error && expected.has(error.id) && error.permanent === true && PERMANENT.has(error.code) && !acknowledged.has(error.id)) blocked.set(error.id, error.code);
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
if (status >= 400 && status < 500 && ![401, 403, 408, 429].includes(status)) {
|
|
286
|
+
for (const id of ids) blocked.set(id, `HTTP_${status}`);
|
|
287
|
+
}
|
|
288
|
+
const authFailed = status === 401 || status === 403;
|
|
289
|
+
const remaining = ids.filter(id => !acknowledged.has(id) && !blocked.has(id));
|
|
290
|
+
const transientFailure = networkFailure || remaining.length > 0;
|
|
291
|
+
let earliest = Infinity;
|
|
292
|
+
// ACK state is itself transactional. If this commit fails, the next worker
|
|
293
|
+
// recovery replays IN_FLIGHT IDs against the server's existing receipts.
|
|
294
|
+
await this.store.transition(ids, row => {
|
|
295
|
+
if (acknowledged.has(row.id)) return { ...row, state: 'ACKNOWLEDGED', error: undefined, acknowledgedAt: new Date().toISOString() };
|
|
296
|
+
if (blocked.has(row.id)) return { ...row, state: 'BLOCKED', error: blocked.get(row.id) };
|
|
297
|
+
const retries = row.retries + 1;
|
|
298
|
+
const dueTime = Math.max(gateUntil, Date.now() + retryDelay(retries, this.random));
|
|
299
|
+
earliest = Math.min(earliest, dueTime);
|
|
300
|
+
return { ...row, state: 'PENDING', retries, dueTime };
|
|
301
|
+
});
|
|
302
|
+
this.policy.observe({ transientFailure, durationMs, full, allAcknowledged: acknowledged.size === ids.length });
|
|
303
|
+
if (this.unlocked) {
|
|
304
|
+
if (authFailed) { this.phase = 'AUTH_REQUIRED'; this._authPaused = true; this.lastError = 'Server authentication failed. Enter a valid server token to resume.'; }
|
|
305
|
+
else if (transientFailure) { this.phase = 'WAITING'; this.lastError = 'The transfer was not fully confirmed. Saved records will retry automatically.'; }
|
|
306
|
+
else { this.phase = 'IDLE'; this.lastError = ''; }
|
|
307
|
+
}
|
|
308
|
+
this._emit();
|
|
309
|
+
return remaining.length ? Math.max(10, earliest - Date.now()) : 10;
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
async snapshot() {
|
|
313
|
+
const epoch = this.#epoch, key = this.#key;
|
|
314
|
+
const summary = await this.store.summary();
|
|
315
|
+
const records = [];
|
|
316
|
+
for (const row of summary.records) {
|
|
317
|
+
let payload;
|
|
318
|
+
if (key && epoch === this.#epoch) {
|
|
319
|
+
try { const record = await this.store.getRecord(row.id); payload = JSON.parse(await decryptRecord(key, record)); } catch { /* Retain metadata for damaged records. */ }
|
|
320
|
+
}
|
|
321
|
+
records.push({ id: row.id, state: row.state, createdAt: row.createdAt, error: row.error, ...(payload !== undefined ? { payload } : {}) });
|
|
322
|
+
}
|
|
323
|
+
if (epoch !== this.#epoch || !this.unlocked) for (const record of records) delete record.payload;
|
|
324
|
+
return { configured: !!this.config, unlocked: this.unlocked, counts: summary.counts, batchBytes: this.policy.bytes,
|
|
325
|
+
phase: this.phase, lastError: this.lastError, metrics: { ...this.metrics }, records };
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
async close() {
|
|
329
|
+
this.stop(); this.lock();
|
|
330
|
+
while (this._busy) await new Promise(resolve => setTimeout(resolve, 10));
|
|
331
|
+
this.store.close();
|
|
332
|
+
}
|
|
333
|
+
}
|
package/src/index.d.ts
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
|
|
2
|
+
export type PolicyMode = 'adaptive' | 'fixed-small' | 'fixed-large';
|
|
3
|
+
export type QueueState = 'PENDING' | 'IN_FLIGHT' | 'ACKNOWLEDGED' | 'BLOCKED';
|
|
4
|
+
export interface Operation { id: string; schema: 1; payload: string; digest: string; }
|
|
5
|
+
export interface SyncOptions<T extends JsonValue = JsonValue> {
|
|
6
|
+
dbName?: string;
|
|
7
|
+
endpoint?: string;
|
|
8
|
+
token?: string;
|
|
9
|
+
policy?: PolicyMode;
|
|
10
|
+
transport?: typeof fetch;
|
|
11
|
+
timeoutMs?: number;
|
|
12
|
+
random?: () => number;
|
|
13
|
+
validator?: ((payload: T) => boolean | void) | null;
|
|
14
|
+
}
|
|
15
|
+
export interface QueueRecord<T extends JsonValue = JsonValue> {
|
|
16
|
+
id: string; state: QueueState; createdAt: string; error?: string; payload?: T;
|
|
17
|
+
}
|
|
18
|
+
export interface SyncSnapshot<T extends JsonValue = JsonValue> {
|
|
19
|
+
configured: boolean; unlocked: boolean; counts: Record<QueueState, number>;
|
|
20
|
+
batchBytes: number; phase: string; lastError: string;
|
|
21
|
+
metrics: { attempts: number; requestBytes: number; responseBytes: number; lastDurationMs: number; unlockMs: number; lastSaveMs: number };
|
|
22
|
+
records: QueueRecord<T>[];
|
|
23
|
+
}
|
|
24
|
+
/** Browser-only engine. Use HTTPS/localhost with IndexedDB, Web Crypto and Web Locks. */
|
|
25
|
+
export class BrowserSyncEngine<T extends JsonValue = JsonValue> extends EventTarget {
|
|
26
|
+
constructor(options?: SyncOptions<T>);
|
|
27
|
+
readonly unlocked: boolean;
|
|
28
|
+
readonly dbName: string;
|
|
29
|
+
readonly phase: string;
|
|
30
|
+
init(): Promise<{ configured: boolean }>;
|
|
31
|
+
setup(passphrase: string): Promise<void>;
|
|
32
|
+
unlock(passphrase: string): Promise<void>;
|
|
33
|
+
lock(): void;
|
|
34
|
+
save(payload: T): Promise<{ id: string; saveMs: number }>;
|
|
35
|
+
start(): void;
|
|
36
|
+
stop(): void;
|
|
37
|
+
kick(): void;
|
|
38
|
+
setToken(token: string): void;
|
|
39
|
+
setPolicy(mode: PolicyMode): void;
|
|
40
|
+
snapshot(): Promise<SyncSnapshot<T>>;
|
|
41
|
+
close(): Promise<void>;
|
|
42
|
+
}
|
|
43
|
+
export interface BatchObservation { transientFailure?: boolean; durationMs: number; full?: boolean; allAcknowledged?: boolean; }
|
|
44
|
+
export class BatchPolicy {
|
|
45
|
+
constructor(mode?: PolicyMode);
|
|
46
|
+
mode: PolicyMode; bytes: number; successes: number;
|
|
47
|
+
setMode(mode: PolicyMode): void;
|
|
48
|
+
observe(observation: BatchObservation): number;
|
|
49
|
+
}
|
|
50
|
+
export function retryDelay(attempt: number, random?: () => number): number;
|
|
51
|
+
export function retryAfter(value: string | null, now?: number): number;
|
|
52
|
+
export function canonicalPayload(value: JsonValue): string;
|
|
53
|
+
export function createOperation(value: JsonValue, id?: string): Promise<Operation>;
|
|
54
|
+
export function encodeBatch(operations: Operation[]): string;
|
|
55
|
+
export function digest(value: string): Promise<string>;
|
|
56
|
+
export function byteLength(value: string): number;
|
|
57
|
+
export const MIN_BATCH: 2048;
|
|
58
|
+
export const MAX_BATCH: 16384;
|
|
59
|
+
export const SCHEMA: 1;
|
package/src/index.js
ADDED
package/src/policy.d.ts
ADDED
package/src/policy.js
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { MIN_BATCH, MAX_BATCH } from './encoding.js';
|
|
2
|
+
|
|
3
|
+
export class BatchPolicy {
|
|
4
|
+
constructor(mode = 'adaptive') { this.setMode(mode); }
|
|
5
|
+
setMode(mode) {
|
|
6
|
+
if (!['adaptive', 'fixed-small', 'fixed-large'].includes(mode)) throw new Error('Unknown batching policy.');
|
|
7
|
+
this.mode = mode;
|
|
8
|
+
this.bytes = mode === 'fixed-large' ? MAX_BATCH : MIN_BATCH;
|
|
9
|
+
this.successes = 0;
|
|
10
|
+
}
|
|
11
|
+
observe({ transientFailure, durationMs, full, allAcknowledged }) {
|
|
12
|
+
if (this.mode !== 'adaptive') return this.bytes;
|
|
13
|
+
if (transientFailure || durationMs > 8000) {
|
|
14
|
+
this.bytes = Math.max(MIN_BATCH, Math.floor(this.bytes / 2));
|
|
15
|
+
this.successes = 0;
|
|
16
|
+
} else if (full && allAcknowledged) {
|
|
17
|
+
if (++this.successes === 2) { this.bytes = Math.min(MAX_BATCH, this.bytes + MIN_BATCH); this.successes = 0; }
|
|
18
|
+
} else this.successes = 0;
|
|
19
|
+
return this.bytes;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export function retryDelay(attempt, random = Math.random) {
|
|
24
|
+
return Math.floor(Math.min(30000, 1000 * 2 ** Math.min(Math.max(attempt - 1, 0), 15)) * random());
|
|
25
|
+
}
|
|
26
|
+
export function retryAfter(value, now = Date.now()) {
|
|
27
|
+
if (!value) return 0;
|
|
28
|
+
if (/^\d+(?:\.\d+)?$/.test(value.trim())) return now + Number(value) * 1000;
|
|
29
|
+
const date = Date.parse(value);
|
|
30
|
+
return Number.isFinite(date) ? Math.max(now, date) : 0;
|
|
31
|
+
}
|
package/src/store.js
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
function result(request) {
|
|
2
|
+
return new Promise((resolve, reject) => { request.onsuccess = () => resolve(request.result); request.onerror = () => reject(request.error); });
|
|
3
|
+
}
|
|
4
|
+
function completed(tx) {
|
|
5
|
+
return new Promise((resolve, reject) => {
|
|
6
|
+
let cause;
|
|
7
|
+
tx.oncomplete = resolve;
|
|
8
|
+
// The request error bubbles before tx.error is set. Preserve its type and
|
|
9
|
+
// wait for the abort so callers retry only after rollback has completed.
|
|
10
|
+
tx.onerror = event => { cause = event.target.error || tx.error; };
|
|
11
|
+
tx.onabort = () => reject(tx.error || cause || new Error('Storage transaction aborted.'));
|
|
12
|
+
});
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export class Store {
|
|
16
|
+
constructor(name) { this.name = name; }
|
|
17
|
+
async open() {
|
|
18
|
+
const req = indexedDB.open(this.name, 1);
|
|
19
|
+
req.onupgradeneeded = () => {
|
|
20
|
+
const db = req.result;
|
|
21
|
+
db.createObjectStore('config', { keyPath: 'name' });
|
|
22
|
+
db.createObjectStore('records', { keyPath: 'id' });
|
|
23
|
+
db.createObjectStore('nonces', { keyPath: 'key' });
|
|
24
|
+
const queue = db.createObjectStore('outbox', { keyPath: 'seq', autoIncrement: true });
|
|
25
|
+
queue.createIndex('id', 'id', { unique: true });
|
|
26
|
+
queue.createIndex('stateSeq', ['state', 'seq']);
|
|
27
|
+
queue.createIndex('stateDue', ['state', 'dueTime']);
|
|
28
|
+
};
|
|
29
|
+
this.db = await result(req);
|
|
30
|
+
this.db.onversionchange = () => this.db.close();
|
|
31
|
+
return this;
|
|
32
|
+
}
|
|
33
|
+
async getConfig(name = 'vault') {
|
|
34
|
+
return result(this.db.transaction('config').objectStore('config').get(name));
|
|
35
|
+
}
|
|
36
|
+
async putConfig(config) {
|
|
37
|
+
const tx = this.db.transaction('config', 'readwrite'); const done = completed(tx);
|
|
38
|
+
tx.objectStore('config').put(config); await done;
|
|
39
|
+
}
|
|
40
|
+
async createVault(config) {
|
|
41
|
+
const tx = this.db.transaction(['config', 'nonces'], 'readwrite'); const done = completed(tx);
|
|
42
|
+
tx.objectStore('config').add(config);
|
|
43
|
+
tx.objectStore('nonces').add({ key: `${config.keyVersion}:${config.checkIv}` });
|
|
44
|
+
await done;
|
|
45
|
+
}
|
|
46
|
+
async save(record, byteLength) {
|
|
47
|
+
const tx = this.db.transaction(['records', 'outbox', 'nonces'], 'readwrite'); const done = completed(tx);
|
|
48
|
+
tx.objectStore('nonces').add({ key: `${record.keyVersion}:${record.iv}` });
|
|
49
|
+
tx.objectStore('records').add(record);
|
|
50
|
+
tx.objectStore('outbox').add({ id: record.id, state: 'PENDING', retries: 0, dueTime: 0, byteLength, createdAt: record.createdAt });
|
|
51
|
+
await done;
|
|
52
|
+
}
|
|
53
|
+
async getRecord(id) { return result(this.db.transaction('records').objectStore('records').get(id)); }
|
|
54
|
+
async nextDue(afterSeq = 0, now = Date.now()) {
|
|
55
|
+
const tx = this.db.transaction('outbox');
|
|
56
|
+
const range = IDBKeyRange.bound(['PENDING', afterSeq], ['PENDING', Number.MAX_SAFE_INTEGER], true, false);
|
|
57
|
+
return new Promise((resolve, reject) => {
|
|
58
|
+
const req = tx.objectStore('outbox').index('stateSeq').openCursor(range);
|
|
59
|
+
req.onerror = () => reject(req.error);
|
|
60
|
+
req.onsuccess = () => {
|
|
61
|
+
const c = req.result;
|
|
62
|
+
if (!c) return resolve(null);
|
|
63
|
+
if (c.value.dueTime <= now) resolve(c.value); else c.continue();
|
|
64
|
+
};
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
async earliestDue() {
|
|
68
|
+
const range = IDBKeyRange.bound(['PENDING', 0], ['PENDING', Number.MAX_SAFE_INTEGER]);
|
|
69
|
+
const cursor = await result(this.db.transaction('outbox').objectStore('outbox').index('stateDue').openCursor(range));
|
|
70
|
+
return cursor ? cursor.value.dueTime : null;
|
|
71
|
+
}
|
|
72
|
+
async transition(ids, change) {
|
|
73
|
+
if (!ids.length) return;
|
|
74
|
+
const tx = this.db.transaction('outbox', 'readwrite'); const done = completed(tx);
|
|
75
|
+
const store = tx.objectStore('outbox');
|
|
76
|
+
for (const id of ids) {
|
|
77
|
+
const req = store.index('id').get(id);
|
|
78
|
+
req.onsuccess = () => { if (req.result) store.put(change(req.result)); else tx.abort(); };
|
|
79
|
+
}
|
|
80
|
+
await done;
|
|
81
|
+
}
|
|
82
|
+
async recover() {
|
|
83
|
+
const tx = this.db.transaction('outbox', 'readwrite'); const done = completed(tx);
|
|
84
|
+
const req = tx.objectStore('outbox').index('stateSeq').openCursor(IDBKeyRange.bound(['IN_FLIGHT', 0], ['IN_FLIGHT', Number.MAX_SAFE_INTEGER]));
|
|
85
|
+
req.onsuccess = () => { const c = req.result; if (c) { c.update({ ...c.value, state: 'PENDING' }); c.continue(); } };
|
|
86
|
+
await done;
|
|
87
|
+
}
|
|
88
|
+
async summary(limit = 50) {
|
|
89
|
+
const tx = this.db.transaction('outbox');
|
|
90
|
+
const q = tx.objectStore('outbox');
|
|
91
|
+
const states = ['PENDING', 'IN_FLIGHT', 'ACKNOWLEDGED', 'BLOCKED'];
|
|
92
|
+
const counts = await Promise.all(states.map(s => result(q.index('stateSeq').count(IDBKeyRange.bound([s, 0], [s, Number.MAX_SAFE_INTEGER])))));
|
|
93
|
+
const records = await new Promise((resolve, reject) => {
|
|
94
|
+
const rows = []; const r = this.db.transaction('outbox').objectStore('outbox').openCursor(null, 'prev');
|
|
95
|
+
r.onerror = () => reject(r.error);
|
|
96
|
+
r.onsuccess = () => { const c = r.result; if (!c || rows.length === limit) return resolve(rows); rows.push(c.value); c.continue(); };
|
|
97
|
+
});
|
|
98
|
+
return { counts: Object.fromEntries(states.map((s, i) => [s, counts[i]])), records };
|
|
99
|
+
}
|
|
100
|
+
close() { this.db?.close(); }
|
|
101
|
+
}
|