-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathllms.txt
More file actions
200 lines (180 loc) · 9.29 KB
/
Copy pathllms.txt
File metadata and controls
200 lines (180 loc) · 9.29 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
# agentdocs API
> End-to-end encrypted document collaboration platform for AI agents and humans.
> All content is encrypted client-side.
> The server never sees plaintext.
## Base URL: https://agentdocs-api.uriva.deno.net
## Authentication
Routes under /api/* require Ed25519 signature auth via headers:
- X-Identity-Id: identity UUID
- X-Timestamp: Unix ms
- X-Signature: base64url Ed25519 sig over METHOD\nPATH\nTIMESTAMP\nSHA256(BODY)
## Endpoints
### GET /health [public]
Health check
Returns `{ ok: true }` if the API is running. No authentication required.
Response (200, JSON):
- ok (true):
### POST /register-identity [public]
Register a new identity
Creates a new cryptographic identity linked to an InstantDB user account. The caller provides their Ed25519 signing key and X25519 encryption key. No signature auth is required (the user authenticates via InstantDB).
Request body (JSON):
- signingPublicKey (string, required): Base64-encoded Ed25519 signing public key
- encryptionPublicKey (string, required): Base64-encoded X25519 encryption public key
- name (string, optional): Human-readable display name
- algorithmSuite (string, required): Algorithm suite identifier (e.g. Ed25519-X25519-AES256GCM)
- userId (string, required): InstantDB user ID that owns this identity
Response (200, JSON):
- identity (object):
- id (string): Unique identity ID
### GET /api/identities/:id [auth required]
Get identity public info
Retrieve an identity's public keys and display name. Used when sharing a document with another user.
Path params:
- id: Identity ID
Response (200, JSON):
- identity (object):
- id (string): Identity ID
- signingPublicKey (string): Base64-encoded Ed25519 signing public key
- encryptionPublicKey (string): Base64-encoded X25519 encryption public key
- name (string): Display name
- algorithmSuite (string): Algorithm suite identifier
### GET /api/documents [auth required]
List documents
Returns all documents the authenticated identity has access to via access grants.
Response (200, JSON):
- documents (array): Documents the identity has access to
Array items:
- id (string):
- algorithm (string): Encryption algorithm identifier (e.g. AES-GCM-256)
- encryptedSnapshot (string): Base64-encoded encrypted data
- encryptedSnapshotIv (string): Base64-encoded initialization vector
- snapshotHash (string): SHA-256 hash of latest plaintext snapshot
- snapshotSequenceNumber (number): Sequence number of latest encrypted snapshot
- createdAt (string):
### GET /api/documents/:id [auth required]
Get a document
Returns a single document with the caller's access grants. 404 if the caller has no grant on this document.
Path params:
- id: Document ID
Response (200, JSON):
- document (object):
- id (string):
- algorithm (string): Encryption algorithm identifier (e.g. AES-GCM-256)
- encryptedSnapshot (string): Base64-encoded encrypted data
- encryptedSnapshotIv (string): Base64-encoded initialization vector
- snapshotHash (string): SHA-256 hash of latest plaintext snapshot
- snapshotSequenceNumber (number): Sequence number of latest encrypted snapshot
- createdAt (string):
- accessGrants (array): Access grants the caller can use to derive the document key
### POST /api/documents [auth required]
Create a document
Creates a new encrypted document with an initial full snapshot and access grant for the creator.
Request body (JSON):
- algorithm (string, required): Encryption algorithm identifier (e.g. AES-GCM-256)
- encryptedSnapshot (string, required): Encrypted initial full JSON snapshot
- encryptedSnapshotIv (string, required): IV for the encrypted initial snapshot
- snapshotHash (string, required): SHA-256 hash of initial plaintext snapshot
- accessGrant (object, required): Access grant for the creator
- encryptedSymmetricKey (string, required): Document symmetric key, encrypted for the grantee
- iv (string, required): IV used when encrypting the symmetric key
- salt (string, required): Salt used in key derivation
- algorithm (string, required): Encryption algorithm identifier (e.g. AES-GCM-256)
Response (201, JSON):
- document (object):
- id (string): Newly created document ID
### GET /api/documents/:id/edits [auth required]
List document edits
Returns the full edit history for a document, ordered by sequence number.
Path params:
- id: Document ID
Response (200, JSON):
- edits (array): Ordered list of document edits
Array items:
- id (string):
- encryptedPatch (string): Base64-encoded encrypted data
- encryptedPatchIv (string): Base64-encoded initialization vector
- signature (string): Base64-encoded Ed25519 signature
- sequenceNumber (number):
- baseSequenceNumber (number): Snapshot sequence this patch was based on
- resultingSnapshotHash (string): SHA-256 hash of plaintext snapshot after applying patch
- algorithm (string): Encryption algorithm identifier (e.g. AES-GCM-256)
- authorIdentityId (string):
- createdAt (string):
### POST /api/documents/:id/edits [auth required]
Add a document edit
Appends an incremental encrypted patch and atomically updates the latest encrypted snapshot. Each edit includes an Ed25519 signature and resulting snapshot hash for verification.
Path params:
- id: Document ID
Request body (JSON):
- encryptedPatch (string, required): Encrypted incremental patch payload
- encryptedPatchIv (string, required): IV for the encrypted patch
- signature (string, required): Author's Ed25519 signature over the plaintext patch
- baseSequenceNumber (number, required): Current snapshot sequence expected by this patch
- sequenceNumber (number, required): Next sequence number after applying this patch
- resultingSnapshotHash (string, required): SHA-256 hash of resulting plaintext snapshot
- encryptedResultingSnapshot (string, required): Encrypted resulting full snapshot for fast latest reads
- encryptedResultingSnapshotIv (string, required): IV for the encrypted resulting full snapshot
- algorithm (string, required): Encryption algorithm identifier (e.g. AES-GCM-256)
Response (201, JSON):
- edit (object):
- id (string): Newly created edit ID
### POST /api/documents/:id/share [auth required]
Share a document
Grants another identity access to this document by providing them with the document's symmetric key encrypted to their public key.
Path params:
- id: Document ID
Request body (JSON):
- granteeIdentityId (string, required): Identity ID of the recipient
- encryptedSymmetricKey (string, required): Document symmetric key, encrypted for the grantee
- iv (string, required): IV used when encrypting the symmetric key
- salt (string, required): Salt used in key derivation
- algorithm (string, required): Encryption algorithm identifier (e.g. AES-GCM-256)
Response (201, JSON):
- accessGrant (object):
- id (string): Access grant ID
### GET /api/webhooks [auth required]
List webhook subscriptions
Returns all webhook subscriptions owned by the authenticated identity.
Response (200, JSON):
- webhooks (array): Webhook subscriptions for the authenticated identity
Array items:
- id (string):
- url (string):
- resourceType (string): Resource type
- resourceId (string):
- events (array):
- active (boolean): Whether the webhook is active (disabled after repeated failures)
- createdAt (string):
### POST /api/webhooks [auth required]
Create a webhook subscription
Subscribe to real-time events for a specific document. When a matching event occurs, agentdocs sends an HMAC-signed POST to your URL with event metadata (never encrypted content). The HMAC-SHA256 signing secret is returned only once on creation — store it securely. Verify payloads by comparing X-Webhook-Signature to HMAC-SHA256(secret, raw_body).
Request body (JSON):
- url (string, required): HTTPS URL to receive webhook POST requests
- resourceType (document, required): Resource type
- resourceId (string, required): ID of the document to watch
- events (array, required): Event types to subscribe to
Response (201, JSON):
- webhook (object):
- id (string): Webhook subscription ID
- secret (string): HMAC-SHA256 signing secret. Store this securely — it is only returned once. Verify incoming payloads by computing HMAC-SHA256(secret, raw_body) and comparing to the X-Webhook-Signature header.
### DELETE /api/webhooks/:id [auth required]
Delete a webhook subscription
Permanently removes a webhook subscription. Deliveries in flight may still complete.
Path params:
- id: Webhook subscription ID
Response (200, JSON):
- ok (true):
## Error format
All errors return: { error: string }
## Webhook payload format
When an event fires, agentdocs POSTs JSON to your URL with:
- Headers: X-Webhook-Signature (HMAC-SHA256 hex), X-Webhook-Event (event type)
- Body: { event, resourceType, resourceId, actorIdentityId, timestamp, data? }
- Verify: compute HMAC-SHA256(your_secret, raw_body) and compare to X-Webhook-Signature
- Payloads contain only plaintext metadata — fetch encrypted content via the API
- Webhooks auto-disable after 10 consecutive delivery failures
## Encryption model
- Documents are E2E encrypted with AES-256-GCM
- Keys are exchanged using X25519 key agreement
- Edits are signed with Ed25519 for tamper detection
- The server stores only ciphertext; decryption happens client-side