You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/design/picod-proposal.md
+19-74Lines changed: 19 additions & 74 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -196,13 +196,6 @@ graph TB
196
196
197
197
#### 2. REST API Endpoints
198
198
199
-
**Initialization**
200
-
201
-
-`POST /init` - Initialize sandbox with session public key (one-time only)
202
-
- Request: JWT signed by bootstrap private key containing session public key
203
-
- Response: JSON confirmation message
204
-
- Access: Workload Manager only
205
-
206
199
**Command Execution**
207
200
208
201
-`POST /api/execute` - Execute command and return output (replaces `execute_command()`)
@@ -235,9 +228,9 @@ graph TB
235
228
236
229
PicoD implements a secure, lightweight authentication system designed specifically for sandbox environments.
237
230
238
-
The core approach provides an **init interface** (`POST /api/init`) that establishes authentication credentials when a sandbox is allocated to an end user. The primary protection scenario is ensuring that **user-requested sandboxes can only be accessed by the designated user** - we only need to guarantee that the sandbox allocated to a user remains exclusive to that user throughout its lifecycle.
231
+
The authentication credentials are established at sandbox creation time by injecting the public key via the `PICOD_AUTH_PUBLIC_KEY` environment variable. The primary protection scenario is ensuring that **user-requested sandboxes can only be accessed by the designated user** - we only need to guarantee that the sandbox allocated to a user remains exclusive to that user throughout its lifecycle.
239
232
240
-
The authentication model balances security with operational simplicity, using client-generated tokens and one-time initialization to bind each sandbox securely to its designated end user.
233
+
The authentication model balances security with operational simplicity, using environment-injected public keys to bind each sandbox securely to its designated end user.
241
234
242
235
##### Authentication Architecture
243
236
@@ -289,76 +282,29 @@ sequenceDiagram
289
282
290
283
##### Security Considerations
291
284
292
-
**1. One-Time Initialization**
293
-
- Init interface can only be called once per sandbox lifecycle
294
-
- Credentials cannot be modified after initial setup
295
-
- Implementation includes atomic file operations to prevent race conditions
285
+
**1. Key Injection at Startup**
286
+
- Public key is injected via the `PICOD_AUTH_PUBLIC_KEY` environment variable at pod creation
287
+
- Credentials are established once at startup and cannot be modified at runtime
296
288
297
-
**2. Bootstrap Key Protection**
298
-
- Bootstrap key pair generated and managed by Workload Manager
299
-
- Bootstrap public key embedded in sandbox pod at creation time
300
-
- Bootstrap private key used only by Workload Manager to sign init JWTs
301
-
- Init endpoint validates JWT signature using embedded bootstrap public key
302
-
303
-
**3. Credential Security**
289
+
**2. Credential Security**
304
290
- Client-generated tokens/keypairs ensure frontend never stores user credentials
305
-
- Local encryption prevents credential exposure if container is compromised
306
291
- Automatic credential cleanup on container termination
307
292
308
-
**4. Warmpool Compatibility**
309
-
- Containers start without authentication credentials
310
-
- Init interface called only when sandbox allocated to specific user
293
+
**3. Warmpool Compatibility**
294
+
- Public key is injected into the pod environment when sandbox is allocated to a specific user
311
295
312
296
##### Core Authentication Components
313
297
314
-
**1. Initialization Interface**
315
-
316
-
-**Endpoint**: `POST /init`
317
-
-**Purpose**: One-time setup of authentication credentials when sandbox is allocated to end user
318
-
-**Access Control**: Requires JWT signed by bootstrap private key (Workload Manager only)
319
-
-**Request Headers**:
320
-
321
-
```http
322
-
Authorization: Bearer <init_jwt>
323
-
```
324
-
325
-
**Init JWT Claims** (signed by Bootstrap Private Key):
326
-
```json
327
-
{
328
-
"session_public_key": "LS0tLS1CRUdJTi...", // Base64-encoded session public key
329
-
"iat": 1732531800,
330
-
"exp": 1732553400
331
-
}
332
-
```
333
-
334
-
-**Response**:
335
-
336
-
```json
337
-
{
338
-
"message": "Server initialized successfully. This PicoD instance is now locked to your public key."
339
-
}
340
-
```
341
-
342
-
**2. Session Public Key Storage**
343
-
344
-
-**Local Storage**: Session public key stored in `picod_public_key.pem` (current working directory)
345
-
-**File Permissions**: 0400 (read-only, immutable via `chattr +i` on Linux)
346
-
-**Storage Format**: PEM-encoded RSA public key
347
-
348
-
```
349
-
-----BEGIN PUBLIC KEY-----
350
-
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
351
-
-----END PUBLIC KEY-----
352
-
```
298
+
**1. Public Key Loading**
353
299
354
-
**Security Features**:
355
-
-File is made immutable after creation (Linux `chattr +i`)
356
-
-Cannot be modified or deleted once initialized
357
-
-Prevents credential tampering even with container access
@@ -371,11 +317,10 @@ All API requests (except `/init` and `/health`) require authentication via JWT s
371
317
```
372
318
373
319
**Validation Process**:
374
-
1. Check if server is initialized (session public key exists)
375
-
2. Extract JWT from Authorization header
376
-
3. Verify JWT signature using stored session public key
377
-
4. Validate JWT expiration and issued-at time
378
-
5. Enforce maximum body size (32MB) to prevent memory exhaustion
320
+
1. Extract JWT from Authorization header
321
+
2. Verify JWT signature using the loaded public key
322
+
3. Validate JWT expiration and issued-at time
323
+
4. Enforce maximum body size (32MB) to prevent memory exhaustion
379
324
380
325
#### 4. Core Capabilities
381
326
PicoD provides a lightweight REST API that replaces traditional SSH‑based operations with secure, stateless HTTP endpoints. The two primary capabilities are code execution and file transfer, exposed via JSON or multipart requests.
0 commit comments