🔌 WebSocket API

Real-time admin operations via WebSocket. The admin panel uses this API internally.

Connection

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:4873/-/admin/ws?token=YOUR_TOKEN');

// Token is auto-injected in admin panel as:
// window.ADMIN_SESSION_TOKEN

Message Format

// Send
{ "action": "getStats", "payload": {} }

// Receive
{ "type": "stats", "data": {...}, "timestamp": 1706100000000 }

Operations Reference

📊 Stats & Metrics

Action	Response Type	Description
`getStats`	`stats`	Server stats: uptime, memory, packages, requests
`getQuarantine`	`quarantine`	List packages in quarantine
`getCache`	`cache`	List cached packages with metadata
`getPackages`	`packages`	All local packages

🛡️ IP Allowlist

Action	Payload	Response Type
`getAllowlist`	`{}`	`allowlist`
`updateAllowlistConfig`	`{ enabled, mode }`	`allowlistUpdated`
`addAllowlistEntry`	`{ pattern, description }`	`allowlistUpdated`
`removeAllowlistEntry`	`{ id }`	`allowlistUpdated`
`toggleAllowlistEntry`	`{ id, enabled }`	`allowlistUpdated`
`testIP`	`{ ip }`	`ipTestResult`

🔍 CVE Scanning

Action	Payload	Response Type
`getCVESummary`	`{}`	`cveSummary`
`getAllCVEs`	`{}`	`allCVEs`
`scanPackageCVE`	`{ name, version }`	`cveScanResult`

🕸️ Dependency Graph

Action	Payload	Response Type
`getGraphRoots`	`{}`	`graphRoots`
`getGraphNode`	`{ name }`	`graphNode`

📋 Audit Logs

Action	Payload	Response Type
`getAuditLogs`	`{ limit? }`	`auditLogs`
`getScanHistory`	`{ limit? }`	`scanHistory`
`triggerDeepScan` 🧪	`{ package_name, version }`	`deepScanResult`
`getRequestLogs`	`{ limit? }`	`requestLogs`

📦 Package Management

Action	Payload	Response Type
`deletePackage`	`{ name }`	`packageDeleted`
`approveQuarantine`	`{ file }`	`quarantineApproved`
`deleteQuarantineFile`	`{ file }`	`quarantineDeleted`
`clearQuarantine`	`{}`	`quarantineCleared`

⚡ Auto-Allow Settings

Action	Payload	Response Type	Description
`getAutoAllowSetting`	`{}`	`autoAllowSetting`	Get current auto-allow local publish setting
`setAutoAllowSetting`	`{ enabled: boolean }`	`autoAllowSetting`	Enable/disable auto-allow for locally published packages

💡 Tip

When auto_allow_local_publish is enabled (default), packages published via npm publish --registry http://localhost:4873 bypass quarantine and security scanning for faster agent workflows.

Example: Full Flow

// 1. Connect
const token = window.ADMIN_SESSION_TOKEN;
const ws = new WebSocket(`ws://localhost:4873/-/admin/ws?token=${token}`);

// 2. Wait for connection
ws.onopen = () => console.log('Connected');

// 3. Handle messages
ws.onmessage = (e) => {
    const msg = JSON.parse(e.data);
    console.log(msg.type, msg.data);
};

// 4. Send request
ws.send(JSON.stringify({ action: 'getStats', payload: {} }));

// 5. Add IP to allowlist
ws.send(JSON.stringify({
    action: 'addAllowlistEntry',
    payload: { pattern: '192.168.1.*', description: 'Local network' }
}));