@nodatachat/sdk 1.0.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/README.md ADDED
@@ -0,0 +1,385 @@
1
+ # @nodatachat/sdk
2
+
3
+ **Your server should never see what it doesn't need to know.**
4
+
5
+ NoData is a blind relay. Data passes through — encrypted, audited, untouched. Your server stores ciphertext. NoData stores nothing. Not the key. Not the plaintext. Not even metadata about what was encrypted.
6
+
7
+ One package. Five lines. Full SOC compliance.
8
+
9
+ ---
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ npm install @nodatachat/sdk
15
+ ```
16
+
17
+ Zero dependencies. Works in Node.js, Bun, Deno, Cloudflare Workers, and any runtime with `fetch`.
18
+
19
+ ---
20
+
21
+ ## Quick start
22
+
23
+ ```ts
24
+ import { NoData } from '@nodatachat/sdk';
25
+
26
+ const nd = new NoData({ apiKey: 'sk_live_...' });
27
+
28
+ // Encrypt a credit card — server-blind
29
+ const { ciphertext } = await nd.encrypt({
30
+ field: 'credit_card',
31
+ value: '4111111111111111',
32
+ });
33
+
34
+ // Store `ciphertext` in YOUR database. NoData stores nothing.
35
+
36
+ // Later — decrypt
37
+ const { value } = await nd.decrypt({
38
+ field: 'credit_card',
39
+ ciphertext,
40
+ requester: 'billing-service',
41
+ });
42
+ ```
43
+
44
+ That's it. AES-256-GCM. Audit trail. Zero plaintext on any server.
45
+
46
+ ---
47
+
48
+ ## What this does
49
+
50
+ | You call | What happens | What NoData stores |
51
+ |----------|-------------|-------------------|
52
+ | `nd.encrypt()` | AES-256-GCM encryption, key material returned to you | Nothing |
53
+ | `nd.decrypt()` | Decryption, audit log entry created | Metadata only (who, when, which field) |
54
+ | `nd.channel.create()` | Encrypted tunnel between two systems | Channel metadata, no content |
55
+ | `nd.deliver.send()` | Burn-after-read secret delivery | Encrypted blob, deleted on read |
56
+ | `nd.evidence.query()` | Returns audit trail for compliance | - |
57
+
58
+ ---
59
+
60
+ ## Batch — 100 fields, one call
61
+
62
+ ```ts
63
+ const result = await nd.batchNative([
64
+ { op: 'encrypt', field: 'phone', value: '0501234567' },
65
+ { op: 'encrypt', field: 'email', value: 'david@company.com' },
66
+ { op: 'encrypt', field: 'id', value: '123456789' },
67
+ { op: 'decrypt', field: 'ssn', ciphertext: 'aes256gcm:v1:...' },
68
+ ]);
69
+ // result.ok === 4, result.failed === 0
70
+ ```
71
+
72
+ Or encrypt an entire object — deep walk, nested fields included:
73
+
74
+ ```ts
75
+ const customer = {
76
+ name: 'David',
77
+ phone: '0501234567',
78
+ email: 'david@company.com',
79
+ address: { street: '123 Main', city: 'Tel Aviv' },
80
+ age: 30,
81
+ };
82
+
83
+ const encrypted = await nd.encryptObject(customer, ['phone', 'email']);
84
+ // { name: 'David', phone: 'aes256gcm:v1:...', email: 'aes256gcm:v1:...', address: {...}, age: 30 }
85
+ ```
86
+
87
+ ---
88
+
89
+ ## Secure channels — system to system
90
+
91
+ Two systems need to exchange sensitive data. Neither trusts the other's infrastructure.
92
+
93
+ ```ts
94
+ // System A — creates a channel
95
+ const ch = await nd.channel.create({
96
+ ttl: '1h',
97
+ requireVerification: true,
98
+ });
99
+ // Share ch.channel_token with System B
100
+ // Share ch.verification_code with the human approver
101
+
102
+ // System B — sends the data
103
+ await nd.channel.send({
104
+ token: ch.channel_token,
105
+ data: { card: '4111111111111111', cvv: '123', exp: '12/28' },
106
+ burnAfterRead: true,
107
+ });
108
+
109
+ // System A — receives
110
+ const result = await nd.channel.receive({
111
+ token: ch.channel_token,
112
+ verificationCode: '482901',
113
+ });
114
+ const card = JSON.parse(result.data);
115
+ ```
116
+
117
+ The server relays encrypted bytes. It never sees the card number.
118
+
119
+ ---
120
+
121
+ ## Burn-after-read delivery
122
+
123
+ Send a secret. Recipient opens the link. Content self-destructs.
124
+
125
+ ```ts
126
+ const d = await nd.deliver.send({
127
+ content: 'DATABASE_PASSWORD=s3cr3t_p@ss!',
128
+ ttl: '30m',
129
+ burn: true,
130
+ maxViews: 1,
131
+ });
132
+
133
+ console.log(d.delivery_url);
134
+ // https://www.nodatachat.com/d/abc123
135
+ // Opened once → gone forever
136
+ ```
137
+
138
+ ---
139
+
140
+ ## Webhooks — encrypted at rest
141
+
142
+ Receive webhooks from Stripe, Twilio, or any service. Payloads encrypted before storage.
143
+
144
+ ```ts
145
+ const wh = await nd.webhook.create({
146
+ label: 'stripe-payments',
147
+ ttl: '30d',
148
+ });
149
+
150
+ // Point Stripe to: wh.ingest_url
151
+ // Store wh.secret — you need it to decrypt
152
+
153
+ // Poll for events
154
+ const events = await nd.webhook.events(wh.channel_token);
155
+ ```
156
+
157
+ ---
158
+
159
+ ## Evidence — SOC audit trail
160
+
161
+ Every encrypt/decrypt is logged. Metadata only — never content.
162
+
163
+ ```ts
164
+ const trail = await nd.evidence.query({
165
+ field: 'credit_card',
166
+ action: 'decrypt',
167
+ from: '2026-03-01',
168
+ to: '2026-03-27',
169
+ });
170
+
171
+ // WHO decrypted WHAT field WHEN — ready for SOC 2 auditor
172
+ ```
173
+
174
+ ---
175
+
176
+ ## Vault — zero-knowledge storage
177
+
178
+ You encrypt client-side. Server stores blindly.
179
+
180
+ ```ts
181
+ const vault = await nd.vault.create({
182
+ label: 'customer-contracts',
183
+ encrypted_blob: myEncrypt(data, myKey),
184
+ iv: myIv,
185
+ metadata: { customer_id: 'cust_123' },
186
+ });
187
+
188
+ const entry = await nd.vault.read(vault.vault_id);
189
+ const data = myDecrypt(entry.encrypted_blob, entry.iv, myKey);
190
+ ```
191
+
192
+ ---
193
+
194
+ ## Express plugin — one line
195
+
196
+ ```ts
197
+ import express from 'express';
198
+ import { nodataExpress } from '@nodatachat/sdk/express';
199
+
200
+ const app = express();
201
+
202
+ app.use('/api/customers', nodataExpress({
203
+ apiKey: 'sk_live_...',
204
+ encryptFields: ['phone', 'email', 'id_number'],
205
+ decryptFields: ['phone', 'email'],
206
+ decryptHeader: 'X-NoData-Decrypt',
207
+ }));
208
+
209
+ app.get('/api/customers', async (req, res) => {
210
+ const rows = await db.query('SELECT * FROM customers');
211
+ res.json(rows);
212
+ // phone, email, id_number → automatically encrypted in response
213
+ });
214
+ ```
215
+
216
+ Also available: `@nodatachat/sdk/fastify`.
217
+
218
+ ---
219
+
220
+ ## Service accounts — scoped M2M keys
221
+
222
+ Your master key creates restricted child keys for each service:
223
+
224
+ ```ts
225
+ // POST /api/v1/service-account
226
+ const svc = await fetch('https://www.nodatachat.com/api/v1/service-account', {
227
+ method: 'POST',
228
+ headers: { Authorization: 'Bearer sk_live_MASTER_KEY' },
229
+ body: JSON.stringify({
230
+ name: 'payment-service',
231
+ scopes: ['encrypt', 'decrypt'],
232
+ rate_limit_per_minute: 500,
233
+ daily_quota: 100000,
234
+ expires_in_days: 90,
235
+ allowed_ips: ['10.0.0.0/8'],
236
+ }),
237
+ });
238
+ // { key: "svc_live_abc123..." } — shown ONCE
239
+ ```
240
+
241
+ | Key prefix | Purpose | Can create child keys |
242
+ |-----------|---------|----------------------|
243
+ | `sk_live_` | Master key | Yes |
244
+ | `svc_live_` | Service account | No |
245
+
246
+ ---
247
+
248
+ ## Configuration
249
+
250
+ ```ts
251
+ const nd = new NoData({
252
+ apiKey: 'sk_live_...',
253
+ baseUrl: 'https://www.nodatachat.com', // default
254
+ timeout: 30000, // ms
255
+ retries: 2, // on 5xx / network error
256
+ headers: { 'X-Custom': 'value' }, // added to every request
257
+
258
+ // Hooks
259
+ onRequest: (url, init) => console.log(`→ ${url}`),
260
+ onResponse: (url, status, ms) => console.log(`← ${status} ${ms}ms`),
261
+ onError: (url, err) => console.error(`! ${url}: ${err.message}`),
262
+ });
263
+ ```
264
+
265
+ ---
266
+
267
+ ## Error handling
268
+
269
+ ```ts
270
+ import { NoData, NoDataError } from '@nodatachat/sdk';
271
+
272
+ try {
273
+ await nd.encrypt({ field: 'ssn', value: '123-45-6789' });
274
+ } catch (err) {
275
+ if (err instanceof NoDataError) {
276
+ console.log(err.status); // 429
277
+ console.log(err.message); // "Rate limit exceeded"
278
+ console.log(err.retryAfter); // 45 (seconds)
279
+ }
280
+ }
281
+ ```
282
+
283
+ Rate limits are handled automatically — the SDK waits and retries on 429.
284
+
285
+ ---
286
+
287
+ ## API reference
288
+
289
+ ### Core
290
+
291
+ | Method | Description |
292
+ |--------|------------|
293
+ | `nd.encrypt(req)` | Encrypt a single field |
294
+ | `nd.decrypt(req)` | Decrypt a single field |
295
+ | `nd.batchEncrypt(fields)` | Parallel encrypt (N HTTP calls) |
296
+ | `nd.batchDecrypt(fields)` | Parallel decrypt (N HTTP calls) |
297
+ | `nd.batchNative(items)` | Single-call batch (1 HTTP call, up to 100 ops) |
298
+ | `nd.encryptObject(obj, fields)` | Deep-walk encrypt matching fields |
299
+ | `nd.decryptObject(obj, fields)` | Deep-walk decrypt matching fields |
300
+ | `nd.ping()` | Health check + latency |
301
+
302
+ ### Channels
303
+
304
+ | Method | Description |
305
+ |--------|------------|
306
+ | `nd.channel.create(opts)` | Create encrypted channel |
307
+ | `nd.channel.send(req)` | Send data through channel |
308
+ | `nd.channel.receive(req)` | Receive data from channel |
309
+ | `nd.channel.verify(token, code)` | Verify recipient |
310
+ | `nd.channel.proof(token)` | Get delivery proof |
311
+
312
+ ### Webhooks
313
+
314
+ | Method | Description |
315
+ |--------|------------|
316
+ | `nd.webhook.create(opts)` | Create webhook channel |
317
+ | `nd.webhook.events(token)` | Poll encrypted events |
318
+ | `nd.webhook.list()` | List all channels |
319
+
320
+ ### Delivery
321
+
322
+ | Method | Description |
323
+ |--------|------------|
324
+ | `nd.deliver.send(req)` | Burn-after-read delivery |
325
+ | `nd.deliver.burn(content)` | Anonymous burn drop |
326
+ | `nd.deliver.read(dropId)` | Read + self-destruct |
327
+
328
+ ### Evidence
329
+
330
+ | Method | Description |
331
+ |--------|------------|
332
+ | `nd.evidence.query(q)` | Query audit trail |
333
+ | `nd.evidence.certificate(id)` | Proof certificate |
334
+ | `nd.evidence.verify(hash)` | Verify proof |
335
+
336
+ ### Vault
337
+
338
+ | Method | Description |
339
+ |--------|------------|
340
+ | `nd.vault.create(req)` | Store encrypted blob |
341
+ | `nd.vault.read(id)` | Retrieve encrypted blob |
342
+ | `nd.vault.delete(id)` | Delete entry |
343
+ | `nd.vault.status()` | Storage stats |
344
+
345
+ ---
346
+
347
+ ## Architecture
348
+
349
+ ```
350
+ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐
351
+ │ Your App │ ──────→ │ NoData API │ ──────→ │ Your DB │
352
+ │ │ │ │ │ │
353
+ │ plaintext │ │ ciphertext │ │ ciphertext │
354
+ │ lives here │ │ passes thru │ │ stored here│
355
+ │ │ │ stores: 0 │ │ │
356
+ └─────────────┘ └──────────────┘ └─────────────┘
357
+ ```
358
+
359
+ **NoData is a relay, not a vault.** Data flows through, gets encrypted, and leaves. The server is blind by design — not by policy, by architecture.
360
+
361
+ ---
362
+
363
+ ## Why
364
+
365
+ Most encryption SDKs ask you to trust their server. We don't.
366
+
367
+ - **No plaintext on our servers** — ever
368
+ - **No key storage** — you hold the keys
369
+ - **No data retention** — we're a relay, not a warehouse
370
+ - **Full audit trail** — every operation logged (metadata only)
371
+ - **SOC 2 ready** — evidence endpoint = auditor-friendly
372
+
373
+ The simplest way to add field-level encryption to any system. Five lines of code. Zero trust required.
374
+
375
+ ---
376
+
377
+ ## Get your API key
378
+
379
+ **[nodatachat.com/developers](https://www.nodatachat.com/developers)**
380
+
381
+ ---
382
+
383
+ <p align="center">
384
+ <strong>NoData</strong> — Your server should never see what it doesn't need to know.
385
+ </p>