> ## Documentation Index
> Fetch the complete documentation index at: https://spec.conveniencepro.cc/llms.txt
> Use this file to discover all available pages before exploring further.
# Security
> Security requirements and best practices
# Security
CTP defines security requirements to ensure safe tool execution.
## Core Principles
Client-executed tools MUST NOT transmit input data to external servers
All inputs MUST be validated before processing
Default configurations MUST be secure
Errors MUST NOT expose sensitive information
## Privacy Requirements
### Client-Mode Tools
Tools with `executionMode: 'client'` MUST:
1. Execute entirely in the browser
2. NOT make network requests with user data
3. NOT use tracking or analytics on input
4. NOT persist input data beyond the session
```typescript theme={null}
// ✅ Correct: Pure client-side processing
export const hashFn: ToolFunction = async (params) => {
const data = new TextEncoder().encode(params.input as string);
const hash = await crypto.subtle.digest('SHA-256', data);
return { success: true, data: { hash: arrayToHex(hash) } };
};
// ❌ Wrong: Sending data to external server
export const hashFn: ToolFunction = async (params) => {
// VIOLATION: Transmitting user input
const response = await fetch('https://api.example.com/hash', {
method: 'POST',
body: JSON.stringify({ input: params.input }),
});
return { success: true, data: await response.json() };
};
```
### Server-Mode Tools
Tools with `executionMode: 'server'`:
1. MUST document what data is transmitted
2. SHOULD use HTTPS for all requests
3. MUST handle credentials securely
4. SHOULD implement rate limiting
## Input Validation
### Required Validation
All tools MUST validate:
1. **Required fields** - Presence of required parameters
2. **Type checking** - Parameters match expected types
3. **Constraints** - Values within allowed ranges
4. **Sanitization** - Dangerous content neutralized
```typescript theme={null}
export const myFn: ToolFunction = (params) => {
const input = params.input;
// 1. Required check
if (!input) {
return {
success: false,
error: 'Input is required',
errorCode: 'MISSING_REQUIRED',
};
}
// 2. Type check
if (typeof input !== 'string') {
return {
success: false,
error: 'Input must be a string',
errorCode: 'TYPE_ERROR',
};
}
// 3. Constraint check
if (input.length > 100000) {
return {
success: false,
error: 'Input exceeds maximum length of 100,000 characters',
errorCode: 'CONSTRAINT_VIOLATION',
};
}
// 4. Process safely
return { success: true, data: process(input) };
};
```
### Validation Constraints
```typescript theme={null}
{
name: 'input',
type: 'textarea',
validation: {
minLength: 1,
maxLength: 100000,
pattern: '^[\\s\\S]*$', // Safe pattern
},
}
```
## Output Security
### Safe Error Messages
```typescript theme={null}
// ✅ Correct: Generic error message
return {
success: false,
error: 'Invalid input format',
errorCode: 'INVALID_INPUT',
};
// ❌ Wrong: Exposing internal details
return {
success: false,
error: `Database error: ${dbError.message} at ${dbError.stack}`,
errorCode: 'INTERNAL_ERROR',
};
```
### Sanitize Output
When generating HTML or code:
```typescript theme={null}
// Escape HTML entities
function escapeHtml(text: string): string {
return text
.replace(/&/g, '&')
.replace(//g, '>')
.replace(/"/g, '"')
.replace(/'/g, ''');
}
```
## Embedding Security
### Content Security Policy
Recommended CSP for embedded tools:
```
Content-Security-Policy:
default-src 'self';
script-src 'self' https://cdn.conveniencepro.cc;
style-src 'self' 'unsafe-inline';
connect-src 'self';
frame-ancestors 'self' https://*.yourdomain.com;
```
### Iframe Sandboxing
```html theme={null}
```
### Cross-Origin Communication
```typescript theme={null}
// Validate message origin
window.addEventListener('message', (event) => {
// Always check origin
if (!trustedOrigins.includes(event.origin)) {
return;
}
// Validate message structure
if (!isValidCTPMessage(event.data)) {
return;
}
handleMessage(event.data);
});
```
## Rate Limiting
### Definition
```typescript theme={null}
export const myDefinition: ToolDefinition = {
// ...
rateLimit: {
requests: 100, // Max requests
window: 60, // Per 60 seconds
},
};
```
### Runtime Enforcement
```typescript theme={null}
import { RateLimiter } from '@conveniencepro/ctp-runtime';
const limiter = new RateLimiter({
requests: 100,
window: 60,
});
const result = await limiter.check('user-id');
if (!result.allowed) {
return {
success: false,
error: `Rate limit exceeded. Try again in ${result.retryAfter} seconds.`,
errorCode: 'RATE_LIMITED',
};
}
```
## Authentication
For tools requiring authentication:
```typescript theme={null}
export const myDefinition: ToolDefinition = {
// ...
requiresAuth: true,
};
export const myFn: ToolFunction = async (params, context) => {
// Check authentication
if (!context?.userId) {
return {
success: false,
error: 'Authentication required',
errorCode: 'UNAUTHORIZED',
};
}
// Proceed with authenticated user
return executeForUser(context.userId, params);
};
```
## Security Checklist
* [ ] All inputs validated before processing
* [ ] Required parameters enforced
* [ ] Type checking implemented
* [ ] Constraint validation (min/max lengths, ranges)
* [ ] Error messages don't expose internals
* [ ] Client tools don't transmit user data
* [ ] Rate limiting configured
* [ ] Authentication enforced where required
* [ ] Output properly escaped/sanitized
* [ ] CSP headers configured for embedding
* [ ] HTTPS used for all external requests
* [ ] Dependencies audited for vulnerabilities