@capsara/sdk 1.0.1
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 +74 -0
- package/README.md +230 -0
- package/dist/builder/capsa-builder.d.ts +167 -0
- package/dist/builder/capsa-builder.d.ts.map +1 -0
- package/dist/builder/capsa-builder.js +489 -0
- package/dist/builder/capsa-builder.js.map +1 -0
- package/dist/client/capsara-client.d.ts +96 -0
- package/dist/client/capsara-client.d.ts.map +1 -0
- package/dist/client/capsara-client.js +266 -0
- package/dist/client/capsara-client.js.map +1 -0
- package/dist/errors/account-error.d.ts +73 -0
- package/dist/errors/account-error.d.ts.map +1 -0
- package/dist/errors/account-error.js +155 -0
- package/dist/errors/account-error.js.map +1 -0
- package/dist/errors/audit-error.d.ts +34 -0
- package/dist/errors/audit-error.d.ts.map +1 -0
- package/dist/errors/audit-error.js +93 -0
- package/dist/errors/audit-error.js.map +1 -0
- package/dist/errors/auth-error.d.ts +38 -0
- package/dist/errors/auth-error.d.ts.map +1 -0
- package/dist/errors/auth-error.js +87 -0
- package/dist/errors/auth-error.js.map +1 -0
- package/dist/errors/capsa-error.d.ts +64 -0
- package/dist/errors/capsa-error.d.ts.map +1 -0
- package/dist/errors/capsa-error.js +172 -0
- package/dist/errors/capsa-error.js.map +1 -0
- package/dist/errors/capsara-error.d.ts +52 -0
- package/dist/errors/capsara-error.d.ts.map +1 -0
- package/dist/errors/capsara-error.js +83 -0
- package/dist/errors/capsara-error.js.map +1 -0
- package/dist/errors/index.d.ts +8 -0
- package/dist/errors/index.d.ts.map +1 -0
- package/dist/errors/index.js +7 -0
- package/dist/errors/index.js.map +1 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/internal/capsa-cache.d.ts +49 -0
- package/dist/internal/capsa-cache.d.ts.map +1 -0
- package/dist/internal/capsa-cache.js +118 -0
- package/dist/internal/capsa-cache.js.map +1 -0
- package/dist/internal/config/http-client.d.ts +37 -0
- package/dist/internal/config/http-client.d.ts.map +1 -0
- package/dist/internal/config/http-client.js +63 -0
- package/dist/internal/config/http-client.js.map +1 -0
- package/dist/internal/config/retry-interceptor.d.ts +18 -0
- package/dist/internal/config/retry-interceptor.d.ts.map +1 -0
- package/dist/internal/config/retry-interceptor.js +103 -0
- package/dist/internal/config/retry-interceptor.js.map +1 -0
- package/dist/internal/crypto/compression.d.ts +15 -0
- package/dist/internal/crypto/compression.d.ts.map +1 -0
- package/dist/internal/crypto/compression.js +34 -0
- package/dist/internal/crypto/compression.js.map +1 -0
- package/dist/internal/crypto/key-generator.d.ts +23 -0
- package/dist/internal/crypto/key-generator.d.ts.map +1 -0
- package/dist/internal/crypto/key-generator.js +65 -0
- package/dist/internal/crypto/key-generator.js.map +1 -0
- package/dist/internal/crypto/primitives.d.ts +67 -0
- package/dist/internal/crypto/primitives.d.ts.map +1 -0
- package/dist/internal/crypto/primitives.js +230 -0
- package/dist/internal/crypto/primitives.js.map +1 -0
- package/dist/internal/crypto/signatures.d.ts +30 -0
- package/dist/internal/crypto/signatures.d.ts.map +1 -0
- package/dist/internal/crypto/signatures.js +153 -0
- package/dist/internal/crypto/signatures.js.map +1 -0
- package/dist/internal/decryptor/capsa-decryptor.d.ts +89 -0
- package/dist/internal/decryptor/capsa-decryptor.d.ts.map +1 -0
- package/dist/internal/decryptor/capsa-decryptor.js +263 -0
- package/dist/internal/decryptor/capsa-decryptor.js.map +1 -0
- package/dist/internal/http-factory.d.ts +78 -0
- package/dist/internal/http-factory.d.ts.map +1 -0
- package/dist/internal/http-factory.js +201 -0
- package/dist/internal/http-factory.js.map +1 -0
- package/dist/internal/index.d.ts +5 -0
- package/dist/internal/index.d.ts.map +1 -0
- package/dist/internal/index.js +5 -0
- package/dist/internal/index.js.map +1 -0
- package/dist/internal/retry-executor.d.ts +74 -0
- package/dist/internal/retry-executor.d.ts.map +1 -0
- package/dist/internal/retry-executor.js +204 -0
- package/dist/internal/retry-executor.js.map +1 -0
- package/dist/internal/services/account-service.d.ts +56 -0
- package/dist/internal/services/account-service.d.ts.map +1 -0
- package/dist/internal/services/account-service.js +114 -0
- package/dist/internal/services/account-service.js.map +1 -0
- package/dist/internal/services/audit-service.d.ts +25 -0
- package/dist/internal/services/audit-service.d.ts.map +1 -0
- package/dist/internal/services/audit-service.js +43 -0
- package/dist/internal/services/audit-service.js.map +1 -0
- package/dist/internal/services/auth-service.d.ts +44 -0
- package/dist/internal/services/auth-service.d.ts.map +1 -0
- package/dist/internal/services/auth-service.js +170 -0
- package/dist/internal/services/auth-service.js.map +1 -0
- package/dist/internal/services/capsa-service.d.ts +40 -0
- package/dist/internal/services/capsa-service.d.ts.map +1 -0
- package/dist/internal/services/capsa-service.js +82 -0
- package/dist/internal/services/capsa-service.js.map +1 -0
- package/dist/internal/services/download-service.d.ts +62 -0
- package/dist/internal/services/download-service.d.ts.map +1 -0
- package/dist/internal/services/download-service.js +114 -0
- package/dist/internal/services/download-service.js.map +1 -0
- package/dist/internal/services/key-service.d.ts +28 -0
- package/dist/internal/services/key-service.d.ts.map +1 -0
- package/dist/internal/services/key-service.js +45 -0
- package/dist/internal/services/key-service.js.map +1 -0
- package/dist/internal/services/limits-service.d.ts +30 -0
- package/dist/internal/services/limits-service.d.ts.map +1 -0
- package/dist/internal/services/limits-service.js +73 -0
- package/dist/internal/services/limits-service.js.map +1 -0
- package/dist/internal/services/upload-service.d.ts +61 -0
- package/dist/internal/services/upload-service.d.ts.map +1 -0
- package/dist/internal/services/upload-service.js +258 -0
- package/dist/internal/services/upload-service.js.map +1 -0
- package/dist/internal/types.d.ts +74 -0
- package/dist/internal/types.d.ts.map +1 -0
- package/dist/internal/types.js +3 -0
- package/dist/internal/types.js.map +1 -0
- package/dist/internal/upload/multipart-builder.d.ts +57 -0
- package/dist/internal/upload/multipart-builder.d.ts.map +1 -0
- package/dist/internal/upload/multipart-builder.js +139 -0
- package/dist/internal/upload/multipart-builder.js.map +1 -0
- package/dist/internal/utils/id-generator.d.ts +8 -0
- package/dist/internal/utils/id-generator.d.ts.map +1 -0
- package/dist/internal/utils/id-generator.js +20 -0
- package/dist/internal/utils/id-generator.js.map +1 -0
- package/dist/internal/utils/mimetype-lookup.d.ts +8 -0
- package/dist/internal/utils/mimetype-lookup.d.ts.map +1 -0
- package/dist/internal/utils/mimetype-lookup.js +118 -0
- package/dist/internal/utils/mimetype-lookup.js.map +1 -0
- package/dist/internal/version.d.ts +20 -0
- package/dist/internal/version.d.ts.map +1 -0
- package/dist/internal/version.js +25 -0
- package/dist/internal/version.js.map +1 -0
- package/dist/types/index.d.ts +143 -0
- package/dist/types/index.d.ts.map +1 -0
- package/dist/types/index.js +20 -0
- package/dist/types/index.js.map +1 -0
- package/package.json +61 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
Capsara SDK License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024-2026 Tessarai, LLC and Laird Rixford (the "License Holders"). All rights reserved.
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS
|
|
6
|
+
|
|
7
|
+
1. GRANT OF LICENSE
|
|
8
|
+
|
|
9
|
+
Subject to the terms and conditions of this License, Tessarai, LLC
|
|
10
|
+
("Licensor") grants you a limited, non-exclusive, non-transferable,
|
|
11
|
+
non-sublicensable, revocable license to use the Capsara SDK ("Software")
|
|
12
|
+
solely in connection with the Capsara platform and services provided by
|
|
13
|
+
Licensor.
|
|
14
|
+
|
|
15
|
+
2. RESTRICTIONS
|
|
16
|
+
|
|
17
|
+
You may NOT:
|
|
18
|
+
|
|
19
|
+
a. Redistribute, sublicense, sell, lease, or otherwise transfer the
|
|
20
|
+
Software or any portion thereof to any third party;
|
|
21
|
+
b. Modify, adapt, translate, reverse engineer, decompile, disassemble,
|
|
22
|
+
or create derivative works based on the Software;
|
|
23
|
+
c. Use the Software to build, support, or operate any product or service
|
|
24
|
+
that competes with the Capsara platform;
|
|
25
|
+
d. Use the Software independently of or outside the Capsara platform;
|
|
26
|
+
e. Remove, alter, or obscure any copyright, trademark, or other
|
|
27
|
+
proprietary notices in the Software.
|
|
28
|
+
|
|
29
|
+
3. PLATFORM BINDING
|
|
30
|
+
|
|
31
|
+
This license is valid only for use with the Capsara platform. Any use of
|
|
32
|
+
the Software outside the Capsara platform, including but not limited to
|
|
33
|
+
integration with competing or unrelated services, is strictly prohibited.
|
|
34
|
+
|
|
35
|
+
4. INTELLECTUAL PROPERTY
|
|
36
|
+
|
|
37
|
+
The Software and all copies thereof are proprietary to and the property
|
|
38
|
+
of the License Holders. All right, title, and interest in and to the
|
|
39
|
+
Software, including all intellectual property rights therein, remain
|
|
40
|
+
exclusively with the License Holders. No rights are
|
|
41
|
+
granted to you other than as expressly set forth in this License.
|
|
42
|
+
|
|
43
|
+
5. TERMINATION
|
|
44
|
+
|
|
45
|
+
This License is effective until terminated. Licensor may terminate this
|
|
46
|
+
License at any time, with or without cause, upon written notice. This
|
|
47
|
+
License will terminate automatically if you fail to comply with any term
|
|
48
|
+
or condition of this License. Upon termination, you must cease all use
|
|
49
|
+
of the Software and destroy all copies in your possession or control.
|
|
50
|
+
|
|
51
|
+
6. GOVERNING TERMS
|
|
52
|
+
|
|
53
|
+
Use of the Software is governed by the Capsara Terms of Service, which
|
|
54
|
+
are incorporated herein by reference. In the event of any conflict
|
|
55
|
+
between this License and the Terms of Service, the Terms of Service
|
|
56
|
+
shall prevail.
|
|
57
|
+
|
|
58
|
+
7. DISCLAIMER OF WARRANTIES
|
|
59
|
+
|
|
60
|
+
THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
61
|
+
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
62
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
|
|
63
|
+
IN NO EVENT SHALL THE LICENSE HOLDERS OR ANY CONTRIBUTORS BE
|
|
64
|
+
LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
65
|
+
OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
|
|
66
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
67
|
+
|
|
68
|
+
8. LIMITATION OF LIABILITY
|
|
69
|
+
|
|
70
|
+
IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
|
|
71
|
+
SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS OR
|
|
72
|
+
REVENUE, WHETHER INCURRED DIRECTLY OR INDIRECTLY, OR ANY LOSS OF DATA,
|
|
73
|
+
USE, GOODWILL, OR OTHER INTANGIBLE LOSSES, RESULTING FROM YOUR USE OF
|
|
74
|
+
OR INABILITY TO USE THE SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
# Capsara SDK — TypeScript
|
|
2
|
+
|
|
3
|
+
Zero-knowledge encrypted messaging and file sharing for multi-party collaboration.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **AES-256-GCM** encryption with unique keys per capsa
|
|
8
|
+
- **RSA-4096-OAEP** key encryption for multi-party access
|
|
9
|
+
- **Compression** — gzip before encryption
|
|
10
|
+
- **Digital signatures** — RSA-SHA256 sender authenticity
|
|
11
|
+
- **Encrypted subject, body, and structured data**
|
|
12
|
+
- **Batch sending** with automatic chunking
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm install @capsara/sdk
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Initialize the Client
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
import { CapsaraClient } from '@capsara/sdk';
|
|
24
|
+
|
|
25
|
+
const client = new CapsaraClient('https://api.capsara.com');
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Authentication
|
|
29
|
+
|
|
30
|
+
Authentication requires two steps: login with your credentials, then set your private key for cryptographic operations.
|
|
31
|
+
|
|
32
|
+
### Login
|
|
33
|
+
|
|
34
|
+
```typescript
|
|
35
|
+
await client.login({
|
|
36
|
+
email: 'you@example.com',
|
|
37
|
+
password: '...'
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Set Private Key
|
|
42
|
+
|
|
43
|
+
After logging in, set your private key for signing and decryption. Generate and register your keypair using `generateKeyPair()` and `addPublicKey()`, then store the private key securely.
|
|
44
|
+
|
|
45
|
+
```typescript
|
|
46
|
+
// Load your private key from secure storage (key vault, HSM, etc.)
|
|
47
|
+
const privateKey = loadPrivateKeyFromSecureStorage();
|
|
48
|
+
|
|
49
|
+
client.setPrivateKey(privateKey);
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Sending Capsas
|
|
53
|
+
|
|
54
|
+
Use the `CapsaBuilder` to create capsas with recipients and files. Always use `sendCapsas()` even for a single capsa — it handles encryption and batching efficiently.
|
|
55
|
+
|
|
56
|
+
```typescript
|
|
57
|
+
import { CapsaraClient, CapsaraError, FileInput } from '@capsara/sdk';
|
|
58
|
+
|
|
59
|
+
try {
|
|
60
|
+
// Create a builder for each capsa you want to send
|
|
61
|
+
const builder = await client.createCapsaBuilder();
|
|
62
|
+
|
|
63
|
+
// Add recipients — can add multiple
|
|
64
|
+
builder.addRecipient('party_recipient1');
|
|
65
|
+
builder.addRecipient('party_recipient2');
|
|
66
|
+
|
|
67
|
+
// Add files from path or buffer
|
|
68
|
+
builder.addFile(FileInput.fromPath('./documents/policy.pdf'));
|
|
69
|
+
builder.addFile(FileInput.fromBuffer(
|
|
70
|
+
Buffer.from('Policy data here'),
|
|
71
|
+
'policy-data.txt'
|
|
72
|
+
));
|
|
73
|
+
|
|
74
|
+
// Add optional metadata
|
|
75
|
+
builder.withSubject('Policy Documents — Q1 2025');
|
|
76
|
+
builder.withBody('Please review the attached policy documents.');
|
|
77
|
+
builder.withStructured({
|
|
78
|
+
policyNumber: 'POL-12345',
|
|
79
|
+
effectiveDate: '2025-01-01'
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
// Set expiration
|
|
83
|
+
builder.withExpiration(new Date(Date.now() + 90 * 24 * 60 * 60 * 1000));
|
|
84
|
+
|
|
85
|
+
// Send
|
|
86
|
+
const result = await client.sendCapsas([builder]);
|
|
87
|
+
console.log(`Sent ${result.successful} capsa(s)`);
|
|
88
|
+
|
|
89
|
+
if (result.failed > 0) {
|
|
90
|
+
console.error(`${result.failed} capsas failed to send`);
|
|
91
|
+
}
|
|
92
|
+
} catch (error) {
|
|
93
|
+
if (error instanceof CapsaraError) {
|
|
94
|
+
console.error('Failed to send:', error.message);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
A **capsa** maps one-to-one with a *matter* — a unique combination of sender, recipient, client, and action. Send multiple capsas in one call:
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
const matter1 = await client.createCapsaBuilder();
|
|
103
|
+
matter1
|
|
104
|
+
.addRecipient('party_org_b')
|
|
105
|
+
.withSubject('Client 1 — New Home Policy')
|
|
106
|
+
.addFile(FileInput.fromPath('./policy.pdf'));
|
|
107
|
+
|
|
108
|
+
const matter2 = await client.createCapsaBuilder();
|
|
109
|
+
matter2
|
|
110
|
+
.addRecipient('party_org_b')
|
|
111
|
+
.withSubject('Client 1 — Auto Endorsement')
|
|
112
|
+
.withBody('Endorsement effective 3/1. No documents required.');
|
|
113
|
+
|
|
114
|
+
await client.sendCapsas([matter1, matter2]);
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
The SDK automatically splits large batches to stay within server limits.
|
|
118
|
+
|
|
119
|
+
## Receiving Capsas
|
|
120
|
+
|
|
121
|
+
### List Capsas
|
|
122
|
+
|
|
123
|
+
```typescript
|
|
124
|
+
const response = await client.listCapsas({
|
|
125
|
+
status: 'active',
|
|
126
|
+
limit: 50
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
console.log(`Found ${response.capsas.length} capsas`);
|
|
130
|
+
|
|
131
|
+
for (const capsa of response.capsas) {
|
|
132
|
+
console.log(`- ${capsa.id}: ${capsa.fileCount} files`);
|
|
133
|
+
console.log(` Created: ${capsa.createdAt}`);
|
|
134
|
+
console.log(` From: ${capsa.creatorId}`);
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
// Pagination
|
|
138
|
+
if (response.pagination.hasMore) {
|
|
139
|
+
const nextPage = await client.listCapsas({
|
|
140
|
+
after: response.pagination.nextCursor
|
|
141
|
+
});
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Get Capsa and Download Files
|
|
146
|
+
|
|
147
|
+
```typescript
|
|
148
|
+
import fs from 'node:fs';
|
|
149
|
+
|
|
150
|
+
const capsa = await client.getCapsa('cap_abc123');
|
|
151
|
+
|
|
152
|
+
console.log('Subject:', capsa.subject);
|
|
153
|
+
console.log('Body:', capsa.body);
|
|
154
|
+
console.log('Structured data:', capsa.structured);
|
|
155
|
+
|
|
156
|
+
// Download each file
|
|
157
|
+
for (const file of capsa.files) {
|
|
158
|
+
const { data, filename } = await client.downloadFile(capsa.packageId, file.id);
|
|
159
|
+
fs.writeFileSync(`./downloads/${filename}`, data);
|
|
160
|
+
}
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Delegation
|
|
164
|
+
|
|
165
|
+
Capsara supports delegation for scenarios where a system acts on behalf of a party — for example, an agency management system (AMS) processing capsas on behalf of the agencies it serves. When a capsa is sent to a delegated recipient, the delegate receives its own RSA-encrypted copy of the master key. If the recipient also has a public key registered in the system, they receive their own encrypted copy as well; otherwise, only the delegate can decrypt on their behalf.
|
|
166
|
+
|
|
167
|
+
If you're a delegate, the flow is identical to receiving. List your capsas and check the `actingFor` field on each one to see which party it belongs to. This lets you route the data to the correct recipient in your system.
|
|
168
|
+
|
|
169
|
+
```typescript
|
|
170
|
+
// Authenticate as the delegate (e.g., an AMS)
|
|
171
|
+
const client = new CapsaraClient('https://api.capsara.com');
|
|
172
|
+
await client.login({ email: 'ams@example.com', password: '...' });
|
|
173
|
+
client.setPrivateKey(loadPrivateKeyFromSecureStorage());
|
|
174
|
+
|
|
175
|
+
// List capsas — includes capsas for all parties you represent
|
|
176
|
+
const response = await client.listCapsas();
|
|
177
|
+
|
|
178
|
+
for (const summary of response.capsas) {
|
|
179
|
+
const capsa = await client.getCapsa(summary.id);
|
|
180
|
+
|
|
181
|
+
// Check who this capsa is for
|
|
182
|
+
if (capsa.actingFor) {
|
|
183
|
+
console.log(`Capsa ${summary.id} is for agency ${capsa.actingFor}`);
|
|
184
|
+
routeToAgency(capsa.actingFor, capsa);
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
// Download and process files
|
|
188
|
+
for (const file of capsa.files) {
|
|
189
|
+
const { data, filename } = await client.downloadFile(summary.id, file.id);
|
|
190
|
+
processFile(capsa.actingFor, filename, data);
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
## Encryption
|
|
196
|
+
|
|
197
|
+
Every capsa is protected by a unique AES-256-GCM symmetric key (the "master key") generated at send time. Files and metadata — subject, body, and structured data — are each encrypted with this master key using a fresh random IV, producing authenticated ciphertext that guarantees both confidentiality and tamper detection. The master key itself is then encrypted once per authorized party and any authorized delegates using their RSA-4096 public key with OAEP-SHA256 padding, so only the holder of the corresponding private key can recover it. Each file is independently hashed with SHA-256 before encryption, and these hashes — along with all IVs — are bound into a canonical string that the sender signs using RS256 (RSA-SHA256 in JWS format). Recipients and the server validate this signature against the sender's public key before trusting any content, ensuring both authenticity and integrity of the entire capsa. Key fingerprints are SHA-256 hashes of the public key PEM, providing a compact identifier for key verification. Files are gzip-compressed before encryption by default to reduce storage and transfer costs. All encryption, decryption, signing, and verification happen locally in the SDK — Capsara's servers only ever store ciphertext and cannot read your files, your metadata, or your keys.
|
|
198
|
+
|
|
199
|
+
## Private Key Security
|
|
200
|
+
|
|
201
|
+
Your private key is the sole point of access to every capsa encrypted for you. Capsara uses zero-knowledge encryption — your private key never leaves your environment, is never transmitted to Capsara's servers, and is never stored by Capsara. There is no recovery mechanism, no master backdoor, and no support override. If your private key is lost, every capsa encrypted for your party becomes permanently inaccessible. No one — not Capsara, not the sender, not an administrator — can recover your data without your private key.
|
|
202
|
+
|
|
203
|
+
You are fully responsible for your private key's lifecycle: generation, secure storage, and backup. Store it in a cloud key vault (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault), a hardware security module, or at minimum an encrypted secrets manager — never in source code, configuration files, or logs. Back it up to a secondary secure location so that a single infrastructure failure does not result in permanent data loss.
|
|
204
|
+
|
|
205
|
+
The SDK provides a `rotateKey()` method that generates a new RSA-4096 key pair and registers the new public key with Capsara. New capsas sent to you will be encrypted with your new key. However, capsas are immutable once created — their keychain and encrypted contents never change. Existing capsas remain accessible only with the private key that was active when they were created. Keep prior private keys available for as long as you need access to capsas encrypted under them.
|
|
206
|
+
|
|
207
|
+
## API Reference
|
|
208
|
+
|
|
209
|
+
| Method | Description |
|
|
210
|
+
|--------|-------------|
|
|
211
|
+
| `CapsaraClient.generateKeyPair()` | Generate an RSA-4096 key pair (static) |
|
|
212
|
+
| `login(credentials)` | Authenticate with email and password |
|
|
213
|
+
| `logout()` | Log out and clear cached data |
|
|
214
|
+
| `setPrivateKey(privateKey)` | Set the private key for signing and decryption |
|
|
215
|
+
| `createCapsaBuilder()` | Create a `CapsaBuilder` pre-loaded with server limits |
|
|
216
|
+
| `sendCapsas(builders)` | Encrypt and send one or more capsas |
|
|
217
|
+
| `getCapsa(capsaId)` | Fetch and decrypt a capsa |
|
|
218
|
+
| `listCapsas(filters?)` | List capsas with optional filters |
|
|
219
|
+
| `deleteCapsa(capsaId)` | Soft-delete a capsa |
|
|
220
|
+
| `downloadFile(capsaId, fileId)` | Download and decrypt a file |
|
|
221
|
+
| `getAuditEntries(capsaId)` | Get audit trail entries |
|
|
222
|
+
| `addPublicKey(key, fingerprint)` | Register a new public key |
|
|
223
|
+
| `rotateKey()` | Generate and register a new key pair |
|
|
224
|
+
| `getKeyHistory()` | Get previous public keys |
|
|
225
|
+
| `getLimits()` | Get server-enforced limits |
|
|
226
|
+
| `destroy()` | Release resources and clear keys |
|
|
227
|
+
|
|
228
|
+
## License
|
|
229
|
+
|
|
230
|
+
Capsara SDK License — see [LICENSE](./LICENSE) for details.
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
/** Fluent capsa builder for creating encrypted capsas. */
|
|
2
|
+
import type { FileInput, PartyKey, SystemLimits } from '../types/index.js';
|
|
3
|
+
import type { CapsaMetadata, KeychainEntry, EncryptedFile } from '../internal/types.js';
|
|
4
|
+
/** Capsa metadata for upload */
|
|
5
|
+
export interface CapsaUploadData {
|
|
6
|
+
packageId: string;
|
|
7
|
+
keychain: {
|
|
8
|
+
algorithm: string;
|
|
9
|
+
keys: KeychainEntry[];
|
|
10
|
+
};
|
|
11
|
+
signature: {
|
|
12
|
+
algorithm: string;
|
|
13
|
+
protected: string;
|
|
14
|
+
payload: string;
|
|
15
|
+
signature: string;
|
|
16
|
+
};
|
|
17
|
+
accessControl: {
|
|
18
|
+
expiresAt?: string;
|
|
19
|
+
};
|
|
20
|
+
deliveryPriority: string;
|
|
21
|
+
files: EncryptedFile[];
|
|
22
|
+
metadata?: CapsaMetadata;
|
|
23
|
+
encryptedSubject?: string;
|
|
24
|
+
subjectIV?: string;
|
|
25
|
+
subjectAuthTag?: string;
|
|
26
|
+
encryptedBody?: string;
|
|
27
|
+
bodyIV?: string;
|
|
28
|
+
bodyAuthTag?: string;
|
|
29
|
+
encryptedStructured?: string;
|
|
30
|
+
structuredIV?: string;
|
|
31
|
+
structuredAuthTag?: string;
|
|
32
|
+
}
|
|
33
|
+
/** Built capsa ready for upload */
|
|
34
|
+
export interface BuiltCapsa {
|
|
35
|
+
capsa: CapsaUploadData;
|
|
36
|
+
files: Array<{
|
|
37
|
+
metadata: EncryptedFile;
|
|
38
|
+
data: Buffer;
|
|
39
|
+
}>;
|
|
40
|
+
}
|
|
41
|
+
/** Server-aligned validation constants. */
|
|
42
|
+
export declare const SERVER_LIMITS: {
|
|
43
|
+
/** Maximum keychain entries (recipients + creator + delegates) */
|
|
44
|
+
readonly MAX_KEYCHAIN_KEYS: 100;
|
|
45
|
+
/** Maximum base64url-encoded encrypted subject length */
|
|
46
|
+
readonly MAX_ENCRYPTED_SUBJECT: 65536;
|
|
47
|
+
/** Maximum base64url-encoded encrypted body length */
|
|
48
|
+
readonly MAX_ENCRYPTED_BODY: 1048576;
|
|
49
|
+
/** Maximum base64url-encoded encrypted structured data length */
|
|
50
|
+
readonly MAX_ENCRYPTED_STRUCTURED: 1048576;
|
|
51
|
+
/** Maximum metadata label length */
|
|
52
|
+
readonly MAX_METADATA_LABEL: 512;
|
|
53
|
+
/** Maximum tags per envelope */
|
|
54
|
+
readonly MAX_METADATA_TAGS: 100;
|
|
55
|
+
/** Maximum characters per tag */
|
|
56
|
+
readonly MAX_TAG_LENGTH: 100;
|
|
57
|
+
/** Maximum metadata notes length */
|
|
58
|
+
readonly MAX_METADATA_NOTES: 10240;
|
|
59
|
+
/** Maximum related packages */
|
|
60
|
+
readonly MAX_RELATED_PACKAGES: 50;
|
|
61
|
+
/** Maximum party ID length */
|
|
62
|
+
readonly MAX_PARTY_ID_LENGTH: 100;
|
|
63
|
+
/** Maximum base64url-encoded encrypted filename length */
|
|
64
|
+
readonly MAX_ENCRYPTED_FILENAME: 2048;
|
|
65
|
+
/** Maximum base64url-encoded signature payload length */
|
|
66
|
+
readonly MAX_SIGNATURE_PAYLOAD: 65536;
|
|
67
|
+
/** Maximum parties a delegate can act for */
|
|
68
|
+
readonly MAX_ACTING_FOR: 10;
|
|
69
|
+
};
|
|
70
|
+
export declare class CapsaBuilder {
|
|
71
|
+
#private;
|
|
72
|
+
subject?: string;
|
|
73
|
+
body?: string;
|
|
74
|
+
structured: Record<string, unknown>;
|
|
75
|
+
/** Unencrypted metadata */
|
|
76
|
+
readonly metadata: CapsaMetadata;
|
|
77
|
+
/** Expiration date (UTC, rounded to minute) */
|
|
78
|
+
get expiresAt(): Date | undefined;
|
|
79
|
+
set expiresAt(value: Date | string | undefined);
|
|
80
|
+
constructor(creatorId: string, creatorPrivateKey: string, limits: SystemLimits);
|
|
81
|
+
/**
|
|
82
|
+
* Add a recipient to the capsa
|
|
83
|
+
* @param partyId - Party ID
|
|
84
|
+
*/
|
|
85
|
+
addRecipient(partyId: string): this;
|
|
86
|
+
/**
|
|
87
|
+
* Add multiple recipients to the capsa
|
|
88
|
+
* @param partyIds - Party IDs
|
|
89
|
+
*/
|
|
90
|
+
addRecipients(...partyIds: string[]): this;
|
|
91
|
+
/**
|
|
92
|
+
* Add a file to the capsa
|
|
93
|
+
* @param input - File input (path or buffer with filename)
|
|
94
|
+
* @throws Error if file exceeds size limit or too many files
|
|
95
|
+
*/
|
|
96
|
+
addFile(input: FileInput): this;
|
|
97
|
+
/**
|
|
98
|
+
* Add a file from a file path
|
|
99
|
+
* @param filePath - File path on disk
|
|
100
|
+
* @param filename - Filename override (defaults to basename)
|
|
101
|
+
* @param mimetype - MIME type (auto-detected if not specified)
|
|
102
|
+
*/
|
|
103
|
+
addFileFromPath(filePath: string, filename?: string, mimetype?: string): this;
|
|
104
|
+
/**
|
|
105
|
+
* Add a file from a Buffer
|
|
106
|
+
* @param buffer - File content
|
|
107
|
+
* @param filename - Filename
|
|
108
|
+
* @param mimetype - MIME type (auto-detected if not specified)
|
|
109
|
+
*/
|
|
110
|
+
addFileFromBuffer(buffer: Buffer, filename: string, mimetype?: string): this;
|
|
111
|
+
/**
|
|
112
|
+
* Add multiple files from file paths
|
|
113
|
+
* @param paths - File paths on disk
|
|
114
|
+
*/
|
|
115
|
+
addFiles(...paths: string[]): this;
|
|
116
|
+
/**
|
|
117
|
+
* Add multiple files from FileInput objects
|
|
118
|
+
* @param files - File inputs
|
|
119
|
+
*/
|
|
120
|
+
addFilesFromInputs(...files: FileInput[]): this;
|
|
121
|
+
/**
|
|
122
|
+
* Add a text file from string content
|
|
123
|
+
* @param filename - Filename
|
|
124
|
+
* @param content - Text content
|
|
125
|
+
*/
|
|
126
|
+
addTextFile(filename: string, content: string): this;
|
|
127
|
+
/**
|
|
128
|
+
* Add a JSON file from an object
|
|
129
|
+
* @param filename - Filename
|
|
130
|
+
* @param data - Object to serialize as JSON
|
|
131
|
+
*/
|
|
132
|
+
addJsonFile(filename: string, data: unknown): this;
|
|
133
|
+
/**
|
|
134
|
+
* Set a structured data field
|
|
135
|
+
* @param key - Field key
|
|
136
|
+
* @param value - Field value
|
|
137
|
+
*/
|
|
138
|
+
withStructured(key: string, value: unknown): this;
|
|
139
|
+
/**
|
|
140
|
+
* Set multiple structured data fields from an object
|
|
141
|
+
* @param data - Object with fields to add
|
|
142
|
+
*/
|
|
143
|
+
withStructured(data: Record<string, unknown>): this;
|
|
144
|
+
/**
|
|
145
|
+
* Set the subject
|
|
146
|
+
* @param subject - Subject text
|
|
147
|
+
*/
|
|
148
|
+
withSubject(subject: string): this;
|
|
149
|
+
/**
|
|
150
|
+
* Set the body
|
|
151
|
+
* @param body - Body text
|
|
152
|
+
*/
|
|
153
|
+
withBody(body: string): this;
|
|
154
|
+
/**
|
|
155
|
+
* Set the expiration
|
|
156
|
+
* @param expiresAt - Expiration date/time
|
|
157
|
+
*/
|
|
158
|
+
withExpiration(expiresAt: Date | string): this;
|
|
159
|
+
getRecipientIds(): string[];
|
|
160
|
+
getFileCount(): number;
|
|
161
|
+
/**
|
|
162
|
+
* Build the capsa with encryption and signature.
|
|
163
|
+
* @param partyKeys - Public keys for all recipients
|
|
164
|
+
*/
|
|
165
|
+
build(partyKeys: PartyKey[]): Promise<BuiltCapsa>;
|
|
166
|
+
}
|
|
167
|
+
//# sourceMappingURL=capsa-builder.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"capsa-builder.d.ts","sourceRoot":"","sources":["../../src/builder/capsa-builder.ts"],"names":[],"mappings":"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"}
|