local-lite 0.2.1 → 0.2.2
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/README.md +5 -2
- package/bin/local-lite.mjs +65 -61
- package/dist/auth/local.d.ts +33 -1
- package/dist/auth/local.js +94 -13
- package/package.json +1 -2
- package/skills/local-lite-auth/SKILL.md +67 -27
- package/skills/local-lite-server/SKILL.md +127 -0
- package/docs/.nojekyll +0 -1
- package/docs/README.md +0 -108
- package/docs/_sidebar.md +0 -22
- package/docs/actions-email.md +0 -222
- package/docs/adapters-local.md +0 -272
- package/docs/adapters-remote.md +0 -291
- package/docs/api-keys.md +0 -114
- package/docs/architecture.md +0 -106
- package/docs/auth.md +0 -342
- package/docs/backups.md +0 -214
- package/docs/breaking-changes.md +0 -147
- package/docs/client-api.md +0 -412
- package/docs/configuration.md +0 -228
- package/docs/conflict-resolution.md +0 -78
- package/docs/getting-started.md +0 -190
- package/docs/google-auth.md +0 -234
- package/docs/index.html +0 -166
- package/docs/kv.md +0 -89
- package/docs/maintenance-portability.md +0 -133
- package/docs/react-hooks.md +0 -457
- package/docs/scheduler.md +0 -81
- package/docs/search.md +0 -71
- package/docs/server.md +0 -101
- package/docs/session.md +0 -129
- package/docs/storage.md +0 -265
package/docs/auth.md
DELETED
|
@@ -1,342 +0,0 @@
|
|
|
1
|
-
# 🔑 Authentication (Local SQLite, Google, Microsoft / OneDrive, GitHub & Apple)
|
|
2
|
-
|
|
3
|
-
`local-lite` provides zero-backend, PKCE-secured authentication clients and React hooks out of the box for the four most popular identity providers, plus a **fully local SQLite authentication engine**:
|
|
4
|
-
* **Local SQLite Auth Engine** (`LocalAuthEngine`, `useLocalAuth`) — 100% offline, PBKDF2-SHA512 password crypto, account lockout, tokens, and users table
|
|
5
|
-
* **Google** (`GoogleAuthClient`, `useGoogleAuth`)
|
|
6
|
-
* **Microsoft / OneDrive** (`MicrosoftAuthClient`, `OneDriveAuthClient`, `useMicrosoftAuth`, `useOneDriveAuth`)
|
|
7
|
-
* **GitHub** (`GitHubAuthClient`, `useGitHubAuth`)
|
|
8
|
-
* **Apple** (`AppleAuthClient`, `useAppleAuth`)
|
|
9
|
-
|
|
10
|
-
Built specifically for local-first architectures, these clients allow your Expo, React Native, Web, or Desktop application to authenticate users directly without requiring an intermediate backend auth server.
|
|
11
|
-
|
|
12
|
-
```typescript
|
|
13
|
-
import {
|
|
14
|
-
GoogleAuthClient,
|
|
15
|
-
MicrosoftAuthClient,
|
|
16
|
-
OneDriveAuthClient,
|
|
17
|
-
GitHubAuthClient,
|
|
18
|
-
AppleAuthClient,
|
|
19
|
-
} from 'local-lite/auth';
|
|
20
|
-
|
|
21
|
-
import {
|
|
22
|
-
useGoogleAuth,
|
|
23
|
-
useMicrosoftAuth,
|
|
24
|
-
useOneDriveAuth,
|
|
25
|
-
useGitHubAuth,
|
|
26
|
-
useAppleAuth,
|
|
27
|
-
} from 'local-lite/react';
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
---
|
|
31
|
-
|
|
32
|
-
## 🌟 Common Architecture & Security
|
|
33
|
-
|
|
34
|
-
* **🛡️ PKCE Security (RFC 7636):** Automatic cryptographically secure 32-byte `code_verifier`, SHA-256 (`S256`) code challenge generation, and CSRF state validation.
|
|
35
|
-
* **👤 Direct Profile Fetching:** Retrieves verified user profile (`id`, `name`, `email`, `picture`) directly from the provider's standard UserInfo / Graph / API endpoints.
|
|
36
|
-
* **🔄 Transparent Token Refreshing:** Inspects token expiration and uses `refresh_token` automatically when within 60 seconds of expiry.
|
|
37
|
-
* **💾 Pluggable Storage:** Use in-memory stores by default or pass any key-value storage adapter (AsyncStorage, SQLite kv-store, SecureStore, etc.) to keep sessions across app restarts.
|
|
38
|
-
* **⚛️ Reactive React Hooks:** Hooks provide reactive user state, sign-in, sign-out, and auto-subscriptions.
|
|
39
|
-
|
|
40
|
-
---
|
|
41
|
-
|
|
42
|
-
## 1. Google Authentication
|
|
43
|
-
|
|
44
|
-
### Setup in Expo / React Native:
|
|
45
|
-
```typescript
|
|
46
|
-
import * as WebBrowser from 'expo-web-browser';
|
|
47
|
-
import * as Linking from 'expo-linking';
|
|
48
|
-
import { GoogleAuthClient, createGoogleAuthTokenStore } from 'local-lite/auth';
|
|
49
|
-
|
|
50
|
-
export const googleAuth = new GoogleAuthClient({
|
|
51
|
-
clientId: 'YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com',
|
|
52
|
-
redirectUri: Linking.createURL('oauth'),
|
|
53
|
-
scopes: ['openid', 'email', 'profile'],
|
|
54
|
-
authorize: async ({ authorizationUrl, redirectUri }) => {
|
|
55
|
-
const result = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
|
|
56
|
-
if (result.type !== 'success' || !result.url) return null;
|
|
57
|
-
const url = new URL(result.url);
|
|
58
|
-
return {
|
|
59
|
-
code: url.searchParams.get('code') ?? '',
|
|
60
|
-
state: url.searchParams.get('state') ?? '',
|
|
61
|
-
};
|
|
62
|
-
},
|
|
63
|
-
});
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
---
|
|
67
|
-
|
|
68
|
-
## 2. Microsoft & OneDrive Authentication
|
|
69
|
-
|
|
70
|
-
The Microsoft Identity Platform (v2.0) supports OAuth 2.0 PKCE for public clients without a client secret.
|
|
71
|
-
|
|
72
|
-
### Setup in Expo / React Native:
|
|
73
|
-
```typescript
|
|
74
|
-
import * as WebBrowser from 'expo-web-browser';
|
|
75
|
-
import * as Linking from 'expo-linking';
|
|
76
|
-
import { MicrosoftAuthClient, OneDriveAuthClient } from 'local-lite/auth';
|
|
77
|
-
|
|
78
|
-
export const oneDriveAuth = new OneDriveAuthClient({
|
|
79
|
-
clientId: 'YOUR_AZURE_APPLICATION_CLIENT_ID',
|
|
80
|
-
redirectUri: Linking.createURL('oauth'),
|
|
81
|
-
// 'Files.ReadWrite.AppFolder' grants access to dedicated OneDrive app storage
|
|
82
|
-
scopes: ['openid', 'profile', 'email', 'User.Read', 'Files.ReadWrite.AppFolder'],
|
|
83
|
-
authorize: async ({ authorizationUrl, redirectUri }) => {
|
|
84
|
-
const result = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
|
|
85
|
-
if (result.type !== 'success' || !result.url) return null;
|
|
86
|
-
const url = new URL(result.url);
|
|
87
|
-
return {
|
|
88
|
-
code: url.searchParams.get('code') ?? '',
|
|
89
|
-
state: url.searchParams.get('state') ?? '',
|
|
90
|
-
};
|
|
91
|
-
},
|
|
92
|
-
});
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
### Profile Returned (`MicrosoftUser` / `OneDriveUser`):
|
|
96
|
-
```typescript
|
|
97
|
-
export interface MicrosoftUser {
|
|
98
|
-
id: string;
|
|
99
|
-
email: string;
|
|
100
|
-
name: string;
|
|
101
|
-
givenName?: string;
|
|
102
|
-
familyName?: string;
|
|
103
|
-
picture?: string;
|
|
104
|
-
userPrincipalName?: string;
|
|
105
|
-
}
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
---
|
|
109
|
-
|
|
110
|
-
## 3. GitHub Authentication
|
|
111
|
-
|
|
112
|
-
Authenticates users via GitHub OAuth and automatically fetches the user's profile and primary verified email address (handling private email profiles seamlessly).
|
|
113
|
-
|
|
114
|
-
### Setup in Expo / React Native:
|
|
115
|
-
```typescript
|
|
116
|
-
import * as WebBrowser from 'expo-web-browser';
|
|
117
|
-
import * as Linking from 'expo-linking';
|
|
118
|
-
import { GitHubAuthClient } from 'local-lite/auth';
|
|
119
|
-
|
|
120
|
-
export const gitHubAuth = new GitHubAuthClient({
|
|
121
|
-
clientId: 'YOUR_GITHUB_CLIENT_ID',
|
|
122
|
-
clientSecret: process.env.GITHUB_CLIENT_SECRET, // Optional if using tokenExchangeUrl proxy
|
|
123
|
-
redirectUri: Linking.createURL('oauth'),
|
|
124
|
-
scopes: ['read:user', 'user:email'],
|
|
125
|
-
authorize: async ({ authorizationUrl, redirectUri }) => {
|
|
126
|
-
const result = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
|
|
127
|
-
if (result.type !== 'success' || !result.url) return null;
|
|
128
|
-
const url = new URL(result.url);
|
|
129
|
-
return {
|
|
130
|
-
code: url.searchParams.get('code') ?? '',
|
|
131
|
-
state: url.searchParams.get('state') ?? '',
|
|
132
|
-
};
|
|
133
|
-
},
|
|
134
|
-
});
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
### Profile Returned (`GitHubUser`):
|
|
138
|
-
```typescript
|
|
139
|
-
export interface GitHubUser {
|
|
140
|
-
id: string;
|
|
141
|
-
login: string;
|
|
142
|
-
name: string;
|
|
143
|
-
email: string;
|
|
144
|
-
avatarUrl?: string;
|
|
145
|
-
bio?: string;
|
|
146
|
-
company?: string;
|
|
147
|
-
location?: string;
|
|
148
|
-
}
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
---
|
|
152
|
-
|
|
153
|
-
## ⚛️ React Hooks Usage
|
|
154
|
-
|
|
155
|
-
```tsx
|
|
156
|
-
import React from 'react';
|
|
157
|
-
import { View, Text, Button, Image } from 'react-native';
|
|
158
|
-
import { useGoogleAuth, useMicrosoftAuth, useGitHubAuth } from 'local-lite/react';
|
|
159
|
-
import { googleAuth, oneDriveAuth, gitHubAuth } from './auth';
|
|
160
|
-
|
|
161
|
-
export function LoginButtons() {
|
|
162
|
-
const google = useGoogleAuth(googleAuth);
|
|
163
|
-
const ms = useMicrosoftAuth(oneDriveAuth);
|
|
164
|
-
const github = useGitHubAuth(gitHubAuth);
|
|
165
|
-
|
|
166
|
-
return (
|
|
167
|
-
<View style={{ gap: 10 }}>
|
|
168
|
-
<Button title="Continue with Google" onPress={google.signIn} />
|
|
169
|
-
<Button title="Continue with Microsoft / OneDrive" onPress={ms.signIn} />
|
|
170
|
-
<Button title="Continue with GitHub" onPress={github.signIn} />
|
|
171
|
-
</View>
|
|
172
|
-
);
|
|
173
|
-
}
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
---
|
|
177
|
-
|
|
178
|
-
## 4. Sign in with Apple
|
|
179
|
-
|
|
180
|
-
`AppleAuthClient` supports both native iOS credentials (`expo-apple-authentication` / `ASAuthorizationAppleIDCredential`) and OAuth authorization flows. Because Apple provides full name and email **only on the very first sign-in**, `AppleAuthClient` automatically caches and preserves user details across sessions.
|
|
181
|
-
|
|
182
|
-
### Setup with `expo-apple-authentication`:
|
|
183
|
-
```typescript
|
|
184
|
-
import * as AppleAuthentication from 'expo-apple-authentication';
|
|
185
|
-
import { AppleAuthClient } from 'local-lite/auth';
|
|
186
|
-
|
|
187
|
-
export const appleAuth = new AppleAuthClient({
|
|
188
|
-
clientId: 'com.yourcompany.app',
|
|
189
|
-
nativeSignIn: async () => {
|
|
190
|
-
const cred = await AppleAuthentication.signInAsync({
|
|
191
|
-
requestedScopes: [
|
|
192
|
-
AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
|
|
193
|
-
AppleAuthentication.AppleAuthenticationScope.EMAIL,
|
|
194
|
-
],
|
|
195
|
-
});
|
|
196
|
-
return {
|
|
197
|
-
user: cred.user,
|
|
198
|
-
identityToken: cred.identityToken,
|
|
199
|
-
authorizationCode: cred.authorizationCode,
|
|
200
|
-
email: cred.email,
|
|
201
|
-
fullName: cred.fullName,
|
|
202
|
-
};
|
|
203
|
-
},
|
|
204
|
-
});
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
### React Hook Example:
|
|
208
|
-
```tsx
|
|
209
|
-
import { useAppleAuth } from 'local-lite/react';
|
|
210
|
-
import { appleAuth } from './auth';
|
|
211
|
-
|
|
212
|
-
export function AppleLoginButton() {
|
|
213
|
-
const { user, isSignedIn, signIn, signOut } = useAppleAuth(appleAuth);
|
|
214
|
-
|
|
215
|
-
if (isSignedIn && user) {
|
|
216
|
-
return (
|
|
217
|
-
<View>
|
|
218
|
-
<Text>Welcome {user.name ?? user.email}!</Text>
|
|
219
|
-
<Button title="Sign Out" onPress={signOut} />
|
|
220
|
-
</View>
|
|
221
|
-
);
|
|
222
|
-
}
|
|
223
|
-
|
|
224
|
-
return <Button title="Sign in with Apple" onPress={() => signIn()} />;
|
|
225
|
-
}
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
---
|
|
229
|
-
|
|
230
|
-
## 💾 Session Persistence Adapters
|
|
231
|
-
|
|
232
|
-
All auth clients accept a `storage` option compatible with any key-value store (AsyncStorage, SQLite kv-store, MMKV, or SecureStore):
|
|
233
|
-
|
|
234
|
-
```typescript
|
|
235
|
-
import AsyncStorage from 'expo-sqlite/kv-store';
|
|
236
|
-
import {
|
|
237
|
-
createGoogleAuthTokenStore,
|
|
238
|
-
createMicrosoftAuthTokenStore,
|
|
239
|
-
createGitHubAuthTokenStore,
|
|
240
|
-
createAppleAuthTokenStore,
|
|
241
|
-
} from 'local-lite/auth';
|
|
242
|
-
|
|
243
|
-
const storage = {
|
|
244
|
-
getItem: async (key: string) => {
|
|
245
|
-
const val = await AsyncStorage.getItem(key);
|
|
246
|
-
return val ? JSON.parse(val) : null;
|
|
247
|
-
},
|
|
248
|
-
setItem: async (key: string, value: unknown) => {
|
|
249
|
-
await AsyncStorage.setItem(key, JSON.stringify(value));
|
|
250
|
-
},
|
|
251
|
-
removeItem: async (key: string) => {
|
|
252
|
-
await AsyncStorage.removeItem(key);
|
|
253
|
-
},
|
|
254
|
-
};
|
|
255
|
-
|
|
256
|
-
const googleTokenStore = createGoogleAuthTokenStore(storage);
|
|
257
|
-
const msTokenStore = createMicrosoftAuthTokenStore(storage);
|
|
258
|
-
const ghTokenStore = createGitHubAuthTokenStore(storage);
|
|
259
|
-
const appleTokenStore = createAppleAuthTokenStore(storage);
|
|
260
|
-
```
|
|
261
|
-
|
|
262
|
-
---
|
|
263
|
-
|
|
264
|
-
## 🔒 5. Fully Local Authentication Engine (`auth/local`)
|
|
265
|
-
|
|
266
|
-
For standalone offline-first apps, local-only modes, or self-contained credentials without third-party OAuth, `local-lite` provides a zero-backend **LocalAuthEngine** storing credentials directly in SQLite.
|
|
267
|
-
|
|
268
|
-
```typescript
|
|
269
|
-
import { LocalAuthEngine } from 'local-lite/auth/local';
|
|
270
|
-
// or access client.auth directly on LocalFirstClient:
|
|
271
|
-
import { useLocalAuth } from 'local-lite/react';
|
|
272
|
-
```
|
|
273
|
-
|
|
274
|
-
### Features & Security:
|
|
275
|
-
* **🛡️ High-Level Crypto Credentials:** PBKDF2 with SHA-512 key derivation, 100,000 iterations by default, and distinct cryptographically secure 16-byte random salts.
|
|
276
|
-
* **⏱️ Constant-Time Verification:** Password comparison uses timing-safe XOR operations to defeat side-channel timing attacks.
|
|
277
|
-
* **🚫 Brute-Force & Lockout Protection:** Automatically tracks consecutive failed login attempts and locks accounts temporarily (default: 5 failed attempts locks for 15 minutes).
|
|
278
|
-
* **🔑 Single-Use Password Reset Tokens:** Cryptographically secure 32-byte tokens stored only as SHA-256 hashes with configurable expiry.
|
|
279
|
-
* **👤 SQLite `_local_users` Table:** Stores sanitized user profiles, usernames, case-insensitive emails, roles, JSON metadata, and status (`active`, `suspended`, `locked`).
|
|
280
|
-
* **📱 Integrated Offline Sessions:** Automatically creates and persists sessions in `SessionManager` so users stay logged in offline.
|
|
281
|
-
|
|
282
|
-
### Basic Usage:
|
|
283
|
-
|
|
284
|
-
```typescript
|
|
285
|
-
// Standalone or via client.auth:
|
|
286
|
-
const { user, session } = await client.auth.signUp({
|
|
287
|
-
email: 'alice@example.com',
|
|
288
|
-
username: 'alice',
|
|
289
|
-
password: 'SuperSecretPassword123!',
|
|
290
|
-
displayName: 'Alice Wonderland',
|
|
291
|
-
metadata: { role: 'admin' },
|
|
292
|
-
});
|
|
293
|
-
|
|
294
|
-
// Sign In with email or username:
|
|
295
|
-
const { user, session } = await client.auth.signIn({
|
|
296
|
-
identifier: 'alice@example.com', // or username 'alice'
|
|
297
|
-
password: 'SuperSecretPassword123!',
|
|
298
|
-
});
|
|
299
|
-
|
|
300
|
-
// Password Change:
|
|
301
|
-
await client.auth.changePassword({
|
|
302
|
-
userId: user.id,
|
|
303
|
-
oldPassword: 'SuperSecretPassword123!',
|
|
304
|
-
newPassword: 'BrandNewPassword456!',
|
|
305
|
-
});
|
|
306
|
-
|
|
307
|
-
// Password Reset Flow:
|
|
308
|
-
const { token } = await client.auth.createPasswordResetToken('alice@example.com');
|
|
309
|
-
await client.auth.resetPasswordWithToken(token, 'BrandNewPassword456!');
|
|
310
|
-
|
|
311
|
-
// Sign Out:
|
|
312
|
-
await client.auth.signOut();
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
### React Hook (`useLocalAuth`):
|
|
316
|
-
|
|
317
|
-
```tsx
|
|
318
|
-
import { useLocalAuth } from 'local-lite/react';
|
|
319
|
-
|
|
320
|
-
export function AuthScreen({ client }) {
|
|
321
|
-
const { user, isSignedIn, loading, signIn, signUp, signOut } = useLocalAuth(client.auth);
|
|
322
|
-
|
|
323
|
-
if (loading) return <Text>Loading user state...</Text>;
|
|
324
|
-
|
|
325
|
-
if (isSignedIn) {
|
|
326
|
-
return (
|
|
327
|
-
<View>
|
|
328
|
-
<Text>Welcome back, {user.displayName || user.email}!</Text>
|
|
329
|
-
<Button title="Sign Out" onPress={() => signOut()} />
|
|
330
|
-
</View>
|
|
331
|
-
);
|
|
332
|
-
}
|
|
333
|
-
|
|
334
|
-
return (
|
|
335
|
-
<LoginForm
|
|
336
|
-
onLogin={(email, password) => signIn(email, password)}
|
|
337
|
-
onRegister={(email, password) => signUp({ email, password })}
|
|
338
|
-
/>
|
|
339
|
-
);
|
|
340
|
-
}
|
|
341
|
-
```
|
|
342
|
-
|
package/docs/backups.md
DELETED
|
@@ -1,214 +0,0 @@
|
|
|
1
|
-
# 📦 Cloud Backups & Zero-Knowledge Encryption
|
|
2
|
-
|
|
3
|
-
`local-lite` includes zero-backend cloud backup and client-side zero-knowledge database encryption out of the box.
|
|
4
|
-
|
|
5
|
-
```typescript
|
|
6
|
-
import {
|
|
7
|
-
GoogleDriveBackupClient,
|
|
8
|
-
OneDriveBackupClient,
|
|
9
|
-
performBackup,
|
|
10
|
-
performRestore,
|
|
11
|
-
createDatabaseBackup,
|
|
12
|
-
restoreDatabaseBackup,
|
|
13
|
-
createEncryptedDatabaseBackup,
|
|
14
|
-
restoreEncryptedDatabaseBackup,
|
|
15
|
-
} from 'local-lite/backups';
|
|
16
|
-
|
|
17
|
-
import {
|
|
18
|
-
useCloudBackup,
|
|
19
|
-
useGoogleDriveBackup,
|
|
20
|
-
useOneDriveBackup,
|
|
21
|
-
} from 'local-lite/react';
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
---
|
|
25
|
-
|
|
26
|
-
## ☁️ 1. Supported Cloud Storage Providers
|
|
27
|
-
|
|
28
|
-
SQLite snapshots are exported directly to user personal cloud storage in secure, application-sandboxed directories without requiring full drive access:
|
|
29
|
-
* **Google Drive** (`GoogleDriveBackupClient`, `GoogleDriveBackupStorage` using the sandboxed `appDataFolder`)
|
|
30
|
-
* **Microsoft OneDrive** (`OneDriveBackupClient`, `OneDriveBackupStorage` using the sandboxed `special/approot` directory)
|
|
31
|
-
|
|
32
|
-
---
|
|
33
|
-
|
|
34
|
-
## 🚀 2. Setting Up Backup Clients
|
|
35
|
-
|
|
36
|
-
### Google Drive Client:
|
|
37
|
-
```typescript
|
|
38
|
-
import * as WebBrowser from 'expo-web-browser';
|
|
39
|
-
import * as Linking from 'expo-linking';
|
|
40
|
-
import { GoogleDriveBackupClient, createGoogleDriveTokenStore } from 'local-lite/backups';
|
|
41
|
-
|
|
42
|
-
export const googleDriveBackup = new GoogleDriveBackupClient({
|
|
43
|
-
clientId: process.env.EXPO_PUBLIC_GOOGLE_CLIENT_ID!,
|
|
44
|
-
redirectUri: Linking.createURL('oauth'),
|
|
45
|
-
tokenStore: createGoogleDriveTokenStore(secureStorage),
|
|
46
|
-
authorize: async ({ authorizationUrl, redirectUri }) => {
|
|
47
|
-
const res = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
|
|
48
|
-
if (res.type !== 'success' || !res.url) return null;
|
|
49
|
-
const url = new URL(res.url);
|
|
50
|
-
return {
|
|
51
|
-
code: url.searchParams.get('code') ?? '',
|
|
52
|
-
state: url.searchParams.get('state') ?? '',
|
|
53
|
-
};
|
|
54
|
-
},
|
|
55
|
-
});
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
### OneDrive Client:
|
|
59
|
-
```typescript
|
|
60
|
-
import * as WebBrowser from 'expo-web-browser';
|
|
61
|
-
import * as Linking from 'expo-linking';
|
|
62
|
-
import { OneDriveBackupClient, createOneDriveTokenStore } from 'local-lite/backups';
|
|
63
|
-
|
|
64
|
-
export const oneDriveBackup = new OneDriveBackupClient({
|
|
65
|
-
clientId: process.env.EXPO_PUBLIC_AZURE_CLIENT_ID!,
|
|
66
|
-
redirectUri: Linking.createURL('oauth'),
|
|
67
|
-
tokenStore: createOneDriveTokenStore(secureStorage),
|
|
68
|
-
authorize: async ({ authorizationUrl, redirectUri }) => {
|
|
69
|
-
const res = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
|
|
70
|
-
if (res.type !== 'success' || !res.url) return null;
|
|
71
|
-
const url = new URL(res.url);
|
|
72
|
-
return {
|
|
73
|
-
code: url.searchParams.get('code') ?? '',
|
|
74
|
-
state: url.searchParams.get('state') ?? '',
|
|
75
|
-
};
|
|
76
|
-
},
|
|
77
|
-
});
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
---
|
|
81
|
-
|
|
82
|
-
## 💾 3. Backing Up and Restoring via `client`
|
|
83
|
-
|
|
84
|
-
You can create and restore backups directly through your initialized `LocalFirstClient`:
|
|
85
|
-
|
|
86
|
-
```typescript
|
|
87
|
-
// Connect user session
|
|
88
|
-
await googleDriveBackup.connect();
|
|
89
|
-
|
|
90
|
-
// 1. Create backup snapshot
|
|
91
|
-
const fileName = await client.backup(googleDriveBackup, {
|
|
92
|
-
fileName: 'my-app-backup.db', // optional
|
|
93
|
-
});
|
|
94
|
-
console.log('Backup created:', fileName);
|
|
95
|
-
|
|
96
|
-
// 2. List backups
|
|
97
|
-
const backups = await googleDriveBackup.list();
|
|
98
|
-
|
|
99
|
-
// 3. Restore snapshot
|
|
100
|
-
await client.restore(googleDriveBackup, backups[0].name);
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
---
|
|
104
|
-
|
|
105
|
-
## 🔐 4. Zero-Knowledge Encryption (AES-256-GCM + PBKDF2)
|
|
106
|
-
|
|
107
|
-
For sensitive applications (medical records, finances, personal notes), data can be encrypted on-device before uploading to the cloud. Neither Google, Microsoft, nor anyone intercepting the file can read the snapshot.
|
|
108
|
-
|
|
109
|
-
### Security Specifications:
|
|
110
|
-
* **Key Derivation:** PBKDF2 with SHA-256, 50,000 iterations, and a unique 16-byte cryptographic salt per backup.
|
|
111
|
-
* **Authenticated Encryption:** AES-256-GCM with a unique 12-byte initialization vector (IV) and 16-byte authentication tag preventing tampering.
|
|
112
|
-
* **Header Structure:** Self-describing `LLENC1` magic bytes header packing the salt, IV, and iteration count for automatic decryption validation.
|
|
113
|
-
|
|
114
|
-
### Usage:
|
|
115
|
-
```typescript
|
|
116
|
-
// Create encrypted backup with passphrase:
|
|
117
|
-
const encryptedFileName = await client.backup(googleDriveBackup, {
|
|
118
|
-
passphrase: 'user-chosen-secret-passphrase',
|
|
119
|
-
fileName: 'medical-snapshot.enc.db',
|
|
120
|
-
});
|
|
121
|
-
|
|
122
|
-
// Restore encrypted backup:
|
|
123
|
-
await client.restore(googleDriveBackup, encryptedFileName, {
|
|
124
|
-
passphrase: 'user-chosen-secret-passphrase',
|
|
125
|
-
});
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
If the passphrase is incorrect or the file was modified in transit, decryption immediately rejects with:
|
|
129
|
-
`Backup decryption failed: Incorrect passphrase or corrupted database backup.`
|
|
130
|
-
|
|
131
|
-
---
|
|
132
|
-
|
|
133
|
-
## ⚛️ 5. React Hooks for Cloud Backups
|
|
134
|
-
|
|
135
|
-
Use `useGoogleDriveBackup` or `useOneDriveBackup` to manage cloud backups reactively in your UI:
|
|
136
|
-
|
|
137
|
-
```tsx
|
|
138
|
-
import React from 'react';
|
|
139
|
-
import { View, Text, Button, FlatList, ActivityIndicator } from 'react-native';
|
|
140
|
-
import { useGoogleDriveBackup } from 'local-lite/react';
|
|
141
|
-
import { googleDriveBackup } from './backup';
|
|
142
|
-
|
|
143
|
-
export function CloudBackupScreen({ client }) {
|
|
144
|
-
const {
|
|
145
|
-
isConnected,
|
|
146
|
-
isLoading,
|
|
147
|
-
isBackingUp,
|
|
148
|
-
isRestoring,
|
|
149
|
-
backups,
|
|
150
|
-
connect,
|
|
151
|
-
disconnect,
|
|
152
|
-
backup,
|
|
153
|
-
restore,
|
|
154
|
-
deleteBackup,
|
|
155
|
-
} = useGoogleDriveBackup(googleDriveBackup, client, {
|
|
156
|
-
passphrase: 'optional-user-passphrase',
|
|
157
|
-
autoRefresh: true,
|
|
158
|
-
});
|
|
159
|
-
|
|
160
|
-
if (isLoading) return <ActivityIndicator />;
|
|
161
|
-
|
|
162
|
-
if (!isConnected) {
|
|
163
|
-
return (
|
|
164
|
-
<View>
|
|
165
|
-
<Text>Connect your Google Drive to enable cloud backups.</Text>
|
|
166
|
-
<Button title="Connect Google Drive" onPress={() => connect()} />
|
|
167
|
-
</View>
|
|
168
|
-
);
|
|
169
|
-
}
|
|
170
|
-
|
|
171
|
-
return (
|
|
172
|
-
<View style={{ padding: 16 }}>
|
|
173
|
-
<Button
|
|
174
|
-
title={isBackingUp ? 'Creating Backup...' : 'Create New Backup'}
|
|
175
|
-
disabled={isBackingUp}
|
|
176
|
-
onPress={() => backup()}
|
|
177
|
-
/>
|
|
178
|
-
|
|
179
|
-
<FlatList
|
|
180
|
-
data={backups}
|
|
181
|
-
keyExtractor={(item) => item.id}
|
|
182
|
-
renderItem={({ item }) => (
|
|
183
|
-
<View style={{ flexDirection: 'row', justifyContent: 'space-between', paddingVertical: 8 }}>
|
|
184
|
-
<View>
|
|
185
|
-
<Text style={{ fontWeight: '600' }}>{item.name}</Text>
|
|
186
|
-
<Text style={{ color: '#666' }}>{new Date(item.createdAt).toLocaleString()}</Text>
|
|
187
|
-
</View>
|
|
188
|
-
<View style={{ flexDirection: 'row', gap: 8 }}>
|
|
189
|
-
<Button title="Restore" onPress={() => restore(item.name)} disabled={isRestoring} />
|
|
190
|
-
<Button title="Delete" color="#ef4444" onPress={() => deleteBackup(item.id)} />
|
|
191
|
-
</View>
|
|
192
|
-
</View>
|
|
193
|
-
)}
|
|
194
|
-
/>
|
|
195
|
-
|
|
196
|
-
<Button title="Disconnect" color="#64748b" onPress={() => disconnect()} />
|
|
197
|
-
</View>
|
|
198
|
-
);
|
|
199
|
-
}
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
---
|
|
203
|
-
|
|
204
|
-
## 🗄️ 6. Universal Database Snapshots (`exportDatabase` & `importDatabase`)
|
|
205
|
-
|
|
206
|
-
`LocalFirstClient` includes built-in methods to export and import portable binary snapshots independently of any cloud service (e.g. for local file system saves, air-gapped USB transfers, or diagnostic dumps):
|
|
207
|
-
|
|
208
|
-
```typescript
|
|
209
|
-
// 1. Export entire SQLite state as Uint8Array bytes
|
|
210
|
-
const snapshotBytes = await client.exportDatabase();
|
|
211
|
-
|
|
212
|
-
// 2. Restore database from snapshot bytes
|
|
213
|
-
await client.importDatabase(snapshotBytes);
|
|
214
|
-
```
|
package/docs/breaking-changes.md
DELETED
|
@@ -1,147 +0,0 @@
|
|
|
1
|
-
# Breaking Changes and AI Code-Review Guide
|
|
2
|
-
|
|
3
|
-
This guide records breaking changes introduced in `local-lite` 0.0.30 and gives
|
|
4
|
-
an actionable checklist for reviewing an application or repository update.
|
|
5
|
-
Use it when upgrading to this version or when asking an AI assistant to check
|
|
6
|
-
whether dependent code needs changes.
|
|
7
|
-
|
|
8
|
-
## AI review prompt
|
|
9
|
-
|
|
10
|
-
Copy this prompt into your code-review request:
|
|
11
|
-
|
|
12
|
-
> Review this codebase for required updates against
|
|
13
|
-
> [`docs/breaking-changes.md`](./breaking-changes.md). Search application code,
|
|
14
|
-
> configuration, tests, examples, and custom adapters for every affected API.
|
|
15
|
-
> Report each match with file and line, explain whether it needs a change, and
|
|
16
|
-
> suggest a minimal migration. Do not edit files unless asked. Do not treat
|
|
17
|
-
> unrelated uses of the same words as API usage.
|
|
18
|
-
|
|
19
|
-
This guide ships with the package at
|
|
20
|
-
`node_modules/local-lite/docs/breaking-changes.md`. A ready-made skill is at
|
|
21
|
-
`node_modules/local-lite/skills/local-lite-upgrade/SKILL.md` (setup and custom
|
|
22
|
-
adapter skills live beside it); copy the folders
|
|
23
|
-
into `.github/skills/` (Copilot) or `.claude/skills/` (Claude Code).
|
|
24
|
-
|
|
25
|
-
## Changes in 0.0.30
|
|
26
|
-
|
|
27
|
-
### 1. Repeat-on-initialize `migrations` option removed
|
|
28
|
-
|
|
29
|
-
The `migrations: string[]` option was removed from `LocalLiteConfig` and
|
|
30
|
-
`LocalFirstClientConfig`. Passing it to `createSyncClient()` or the
|
|
31
|
-
`LocalFirstClient` constructor now throws. Use versioned `schemaMigrations`
|
|
32
|
-
instead.
|
|
33
|
-
|
|
34
|
-
```typescript
|
|
35
|
-
schemaMigrations: [
|
|
36
|
-
{
|
|
37
|
-
version: 1,
|
|
38
|
-
up: 'CREATE TABLE notes (id TEXT PRIMARY KEY, title TEXT NOT NULL)',
|
|
39
|
-
},
|
|
40
|
-
{
|
|
41
|
-
version: 2,
|
|
42
|
-
up: 'ALTER TABLE notes ADD COLUMN archived INTEGER NOT NULL DEFAULT 0',
|
|
43
|
-
},
|
|
44
|
-
],
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
**Review checklist**
|
|
48
|
-
|
|
49
|
-
- Find configuration properties named `migrations` and confirm they are the
|
|
50
|
-
removed local-lite option, not another library's setting or a local variable.
|
|
51
|
-
- Convert SQL into consecutive, one-time `schemaMigrations` entries.
|
|
52
|
-
- Preserve the complete migration history in the application so existing
|
|
53
|
-
installations can upgrade. Do not simply rename the array: old statements
|
|
54
|
-
ran on every initialization, while versioned migrations run once.
|
|
55
|
-
- Update config helpers, test fixtures, and migration-related documentation.
|
|
56
|
-
|
|
57
|
-
### 2. Expo legacy FileSystem API removed
|
|
58
|
-
|
|
59
|
-
`ExpoFileDriver` now uses Expo SDK 58+ `File`, `Directory`, and `Paths`.
|
|
60
|
-
The `fileSystem` constructor option and legacy `expo-file-system` methods such
|
|
61
|
-
as `writeAsStringAsync`, `getInfoAsync`, `copyAsync`, and `downloadAsync` are no
|
|
62
|
-
longer supported.
|
|
63
|
-
|
|
64
|
-
```typescript
|
|
65
|
-
import { File, Directory, Paths } from 'expo-file-system';
|
|
66
|
-
import { ExpoFileDriver } from 'local-lite/storage';
|
|
67
|
-
|
|
68
|
-
const driver = new ExpoFileDriver({ File, Directory, Paths });
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
The `baseDir` and `useCache` options remain available.
|
|
72
|
-
|
|
73
|
-
**Review checklist**
|
|
74
|
-
|
|
75
|
-
- Find `new ExpoFileDriver({ fileSystem: ... })` and replace it with the modern
|
|
76
|
-
named API options.
|
|
77
|
-
- Check Expo dependencies and runtime versions; the modern APIs require Expo
|
|
78
|
-
SDK 58 or newer.
|
|
79
|
-
- Replace direct legacy FileSystem calls in integrations with `File` operations
|
|
80
|
-
or `ExpoFileDriver` methods.
|
|
81
|
-
- Review tests and examples for legacy mocks or imports.
|
|
82
|
-
|
|
83
|
-
### 3. Custom realtime adapters must return cleanup
|
|
84
|
-
|
|
85
|
-
`RemoteDBAdapter.subscribeToLiveChanges()` now has the required return type
|
|
86
|
-
`() => void`. Every custom adapter implementation must return a function that
|
|
87
|
-
unsubscribes its listener. If no listener is created, return a no-op function.
|
|
88
|
-
|
|
89
|
-
```typescript
|
|
90
|
-
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): () => void {
|
|
91
|
-
if (!this.canSubscribe()) return () => {};
|
|
92
|
-
|
|
93
|
-
const subscription = this.startSubscription(callback);
|
|
94
|
-
return () => subscription.unsubscribe();
|
|
95
|
-
}
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
**Review checklist**
|
|
99
|
-
|
|
100
|
-
- Find classes and object literals implementing `RemoteDBAdapter`.
|
|
101
|
-
- Confirm all code paths, including missing clients, empty table lists, and
|
|
102
|
-
initialization failures, return a cleanup function.
|
|
103
|
-
- Confirm cleanup is safe to call once and prevents callbacks from a stopped or
|
|
104
|
-
replaced subscription.
|
|
105
|
-
- Update mocks and test adapters to match the required signature.
|
|
106
|
-
|
|
107
|
-
### 4. `_migrations` is no longer an internal table name
|
|
108
|
-
|
|
109
|
-
`isInternalTable('_migrations')` now returns `false`. The name is not treated as
|
|
110
|
-
a local-lite engine table and may consequently appear in APIs that filter
|
|
111
|
-
internal tables, such as `getTables()` and maintenance reports.
|
|
112
|
-
|
|
113
|
-
**Review checklist**
|
|
114
|
-
|
|
115
|
-
- Find uses of `_migrations` as an application table or as a local-lite
|
|
116
|
-
bookkeeping table.
|
|
117
|
-
- If an application uses this name and expects it to be hidden, rename the
|
|
118
|
-
application table or filter it explicitly in the application.
|
|
119
|
-
- Do not rename or delete stored tables as part of an automated upgrade without
|
|
120
|
-
confirming their ownership and contents.
|
|
121
|
-
|
|
122
|
-
### 5. FTS tokenizer errors now propagate
|
|
123
|
-
|
|
124
|
-
FTS table creation no longer retries without the `tokenize` option after a
|
|
125
|
-
tokenizer error. A configured tokenizer that the SQLite build does not support
|
|
126
|
-
causes search initialization to fail instead of silently creating a table with
|
|
127
|
-
different tokenization behavior.
|
|
128
|
-
|
|
129
|
-
**Review checklist**
|
|
130
|
-
|
|
131
|
-
- Find `client.search` configurations that set a custom tokenizer.
|
|
132
|
-
- Verify the target SQLite build supports the configured tokenizer and FTS5.
|
|
133
|
-
- Test search initialization and representative queries on every supported
|
|
134
|
-
platform/build.
|
|
135
|
-
- Resolve an unsupported tokenizer by selecting one supported by the target
|
|
136
|
-
runtime or correcting the SQLite build; do not rely on an implicit tokenizer
|
|
137
|
-
fallback.
|
|
138
|
-
|
|
139
|
-
## Suggested review output
|
|
140
|
-
|
|
141
|
-
For each potential issue, report:
|
|
142
|
-
|
|
143
|
-
1. File and line.
|
|
144
|
-
2. Which change above applies.
|
|
145
|
-
3. Whether a code update is required or the match is unrelated.
|
|
146
|
-
4. The smallest safe migration.
|
|
147
|
-
5. Any behavior or stored-data risk that needs application-owner confirmation.
|