Skip to content

Commit 42212eb

Browse files
committed
Removing POST \init from the docs
1 parent 3f65386 commit 42212eb

File tree

2 files changed

+19
-81
lines changed

2 files changed

+19
-81
lines changed

docs/design/agentcube-proposal.md

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -404,13 +404,6 @@ The CodeInterpreter is a component responsible for executing code snippets or co
404404

405405
### 5.1 API design
406406

407-
Initialization
408-
409-
- POST /init - Initialize sandbox with session public key (one-time only)
410-
- Request: JWT signed by bootstrap private key containing session public key
411-
- Response: JSON confirmation message
412-
- Access: Workload Manager only
413-
414407
Command Execution
415408

416409
- POST /api/execute - Execute command and return output

docs/design/picod-proposal.md

Lines changed: 19 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -196,13 +196,6 @@ graph TB
196196

197197
#### 2. REST API Endpoints
198198

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-
206199
**Command Execution**
207200

208201
- `POST /api/execute` - Execute command and return output (replaces `execute_command()`)
@@ -235,9 +228,9 @@ graph TB
235228

236229
PicoD implements a secure, lightweight authentication system designed specifically for sandbox environments.
237230

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.
239232

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.
241234

242235
##### Authentication Architecture
243236

@@ -289,76 +282,29 @@ sequenceDiagram
289282

290283
##### Security Considerations
291284

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
296288

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**
304290
- Client-generated tokens/keypairs ensure frontend never stores user credentials
305-
- Local encryption prevents credential exposure if container is compromised
306291
- Automatic credential cleanup on container termination
307292

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
311295

312296
##### Core Authentication Components
313297

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**
353299

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
300+
- **Source**: `PICOD_AUTH_PUBLIC_KEY` environment variable
301+
- **Purpose**: Provides the RSA public key used to verify JWT signatures
302+
- **Format**: PEM-encoded RSA public key
303+
- **Loaded at**: Server startup (required, server will not start without it)
358304

359-
**3. Request Authentication**
305+
**2. Request Authentication**
360306

361-
All API requests (except `/init` and `/health`) require authentication via JWT signed by the session private key:
307+
All API requests (except `/health`) require authentication via JWT signed by the session private key:
362308

363309
- **Header**: `Authorization: Bearer <session_jwt>`
364310

@@ -371,11 +317,10 @@ All API requests (except `/init` and `/health`) require authentication via JWT s
371317
```
372318

373319
**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
379324

380325
#### 4. Core Capabilities
381326
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

Comments
 (0)