aimeat 1.2.0

package/dist/src/routes/agents.js

@@ -0,0 +1,946 @@
+import { Router } from 'express';
+import { randomBytes } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname_agents = dirname(fileURLToPath(import.meta.url));
+import { generateKeyPair } from '../auth/keypair.js';
+import { requireAuth, requireRole } from '../auth/middleware.js';
+import { success, error } from '../middleware/envelope.js';
+import { validateAgentName, buildGAII, generateUserCode } from '../utils/gaii.js';
+import { calculateTrustScore } from '../services/trust.js';
+import { executeHooks } from '../services/hooks.js';
+import { fireHook } from '../utils/fire-hook.js';
+import { AgentRegistrationSchema, validateBody } from '../models/schemas.js';
+import { verifyJWT, issueJWT, generateSessionId } from '../auth/jwt.js';
+import { rateLimit } from '../middleware/rate-limit.js';
+import { emitChange } from '../services/event-bus.js';
+/** Device authorization code expires after 30 minutes */
+const DEVICE_AUTH_EXPIRY_MS = 1_800_000;
+export function agentsRouter(config, storage) {
+    const router = Router();
+    // POST /v1/agents/device-authorize — start device authorization flow (RFC 8628)
+    router.post('/v1/agents/device-authorize', async (req, res) => {
+        const { agent_name, display_name, description, owner } = req.body ?? {};
+        if (!owner) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'owner is required'));
+            return;
+        }
+        if (!agent_name) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'agent_name is required'));
+            return;
+        }
+        const nameError = validateAgentName(agent_name);
+        if (nameError) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', nameError));
+            return;
+        }
+        // Rate limit: max 10 pending per owner name
+        const pendingCount = await storage.countPendingDeviceAuthByOwner(owner);
+        if (pendingCount >= 10) {
+            res.status(429).json(error(config.nodeId, 'RATE_LIMITED', 'Too many pending authorization requests for this owner'));
+            return;
+        }
+        // Cleanup expired requests lazily
+        await storage.cleanupExpiredDeviceAuth();
+        // Generate codes
+        const deviceCode = randomBytes(32).toString('hex');
+        let userCode = generateUserCode();
+        // Ensure user code uniqueness
+        let attempts = 0;
+        while (await storage.getDeviceAuthByUserCode(userCode) && attempts < 10) {
+            userCode = generateUserCode();
+            attempts++;
+        }
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + DEVICE_AUTH_EXPIRY_MS);
+        await storage.createDeviceAuth({
+            deviceCode,
+            userCode,
+            ownerName: owner,
+            agentName: agent_name,
+            displayName: display_name,
+            description,
+            status: 'pending',
+            createdAt: now.toISOString(),
+            expiresAt: expiresAt.toISOString(),
+            pollInterval: 5,
+        });
+        const baseUrl = `${req.protocol}://${req.get('host')}`;
+        const verificationUri = `${baseUrl}/v1/agents/verify`;
+        const verificationUriComplete = `${baseUrl}/v1/agents/verify?code=${userCode}`;
+        res.set('Cache-Control', 'no-store');
+        res.set('Pragma', 'no-cache');
+        res.json(success(config.nodeId, {
+            device_code: deviceCode,
+            user_code: userCode,
+            verification_uri: verificationUri,
+            verification_uri_complete: verificationUriComplete,
+            expires_in: 1800,
+            interval: 5,
+        }, [
+            { description: 'Open this URL in a browser', method: 'GET', url: `/v1/agents/verify?code=${userCode}` },
+            { description: 'Poll for authorization result', method: 'POST', url: '/v1/agents/device-token' },
+        ]));
+        emitChange('agents');
+    });
+    // POST /v1/agents/device-token — poll for device authorization result (RFC 8628)
+    router.post('/v1/agents/device-token', async (req, res) => {
+        const { device_code, grant_type } = req.body ?? {};
+        if (grant_type !== 'urn:ietf:params:oauth:grant-type:device_code') {
+            res.status(400).json({ error: 'unsupported_grant_type', error_description: 'Only device_code grant type is supported.' });
+            return;
+        }
+        if (!device_code) {
+            res.status(400).json({ error: 'invalid_request', error_description: 'device_code is required.' });
+            return;
+        }
+        const request = await storage.getDeviceAuthByDeviceCode(device_code);
+        if (!request) {
+            res.status(400).json({ error: 'invalid_grant', error_description: 'Unknown device code.' });
+            return;
+        }
+        // Check expiry
+        if (new Date(request.expiresAt) <= new Date()) {
+            if (request.status === 'pending') {
+                await storage.updateDeviceAuth(device_code, { status: 'expired' });
+            }
+            res.status(400).json({ error: 'expired_token', error_description: 'This authorization request has expired.' });
+            return;
+        }
+        // Rate limiting: enforce poll interval
+        if (request.lastPolledAt) {
+            const elapsed = Date.now() - new Date(request.lastPolledAt).getTime();
+            if (elapsed < request.pollInterval * 1000) {
+                // Increase interval by 5s on slow_down
+                await storage.updateDeviceAuth(device_code, {
+                    pollInterval: request.pollInterval + 5,
+                    lastPolledAt: new Date().toISOString(),
+                });
+                res.status(400).json({ error: 'slow_down', error_description: `Polling too frequently. Wait ${request.pollInterval + 5} seconds between requests.` });
+                return;
+            }
+        }
+        // Update last polled time
+        await storage.updateDeviceAuth(device_code, { lastPolledAt: new Date().toISOString() });
+        res.set('Cache-Control', 'no-store');
+        res.set('Pragma', 'no-cache');
+        switch (request.status) {
+            case 'pending':
+                res.status(400).json({ error: 'authorization_pending', error_description: 'The user has not yet approved this request.' });
+                return;
+            case 'denied':
+                res.status(400).json({ error: 'access_denied', error_description: 'The user denied this authorization request.' });
+                return;
+            case 'approved': {
+                if (!request.agentCredentials) {
+                    // Credentials already consumed
+                    res.status(400).json({ error: 'expired_token', error_description: 'Credentials have already been retrieved.' });
+                    return;
+                }
+                // Return credentials and immediately clear them
+                const creds = request.agentCredentials;
+                await storage.updateDeviceAuth(device_code, { agentCredentials: null });
+                res.json({
+                    gaii: creds.gaii,
+                    name: request.agentName,
+                    owner: request.ownerName,
+                    token: creds.token,
+                    expires_at: creds.expires_at,
+                    privateKey: creds.privateKey,
+                    publicKey: creds.publicKey,
+                    scopes: request.scopes,
+                    morselBalance: 0,
+                    note: 'Use the token directly: Authorization: Bearer <token>. The privateKey is provided for advanced use (Ed25519 signing) but is not required.',
+                });
+                return;
+            }
+            default:
+                res.status(400).json({ error: 'expired_token', error_description: 'This authorization request has expired.' });
+        }
+    });
+    // GET /v1/agents/verify/info/:userCode — device auth request details for consent page
+    // Rate limited by IP (10/min) to prevent user code enumeration per spec
+    router.get('/v1/agents/verify/info/:userCode', rateLimit({ max: 10, windowMs: 60_000 }), async (req, res) => {
+        const userCode = req.params.userCode.toUpperCase();
+        const request = await storage.getDeviceAuthByUserCode(userCode);
+        if (!request || new Date(request.expiresAt) <= new Date()) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', 'Authorization request not found or expired'));
+            return;
+        }
+        const remainingMs = new Date(request.expiresAt).getTime() - Date.now();
+        res.json(success(config.nodeId, {
+            user_code: request.userCode,
+            agent_name: request.agentName,
+            display_name: request.displayName,
+            description: request.description,
+            owner: request.ownerName,
+            status: request.status,
+            expires_in: Math.ceil(remainingMs / 1000),
+        }));
+    });
+    // POST /v1/agents/verify — consent form submission (approve/deny)
+    router.post('/v1/agents/verify', async (req, res) => {
+        const { user_code, action, scopes, owner_token } = req.body ?? {};
+        if (!user_code || !action || !owner_token) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'user_code, action, and owner_token are required'));
+            return;
+        }
+        // Verify owner JWT
+        const ownerPayload = await verifyJWT(owner_token);
+        if (!ownerPayload || !ownerPayload.roles?.includes('owner')) {
+            res.status(401).json(error(config.nodeId, 'AUTH_REQUIRED', 'Invalid or expired owner token'));
+            return;
+        }
+        const request = await storage.getDeviceAuthByUserCode(user_code);
+        if (!request) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', 'Authorization request not found'));
+            return;
+        }
+        if (request.status !== 'pending') {
+            res.status(409).json(error(config.nodeId, 'ALREADY_PROCESSED', `This request has already been ${request.status}`));
+            return;
+        }
+        if (new Date(request.expiresAt) <= new Date()) {
+            await storage.updateDeviceAuth(request.deviceCode, { status: 'expired' });
+            res.status(410).json(error(config.nodeId, 'EXPIRED', 'This authorization request has expired'));
+            return;
+        }
+        // Verify owner matches
+        if (ownerPayload.owner !== request.ownerName) {
+            res.status(403).json(error(config.nodeId, 'ACCESS_DENIED', 'You can only approve requests for your own account'));
+            return;
+        }
+        if (action === 'deny') {
+            await storage.updateDeviceAuth(request.deviceCode, { status: 'denied' });
+            res.json(success(config.nodeId, { status: 'denied' }));
+            emitChange('agents');
+            return;
+        }
+        if (action !== 'approve') {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'action must be "approve" or "deny"'));
+            return;
+        }
+        // === APPROVE FLOW ===
+        // Validate scopes against config.maxAgentScopes (same pattern as POST /v1/agents)
+        const finalScopes = scopes ?? config.defaultAgentScopes;
+        if (!config.maxAgentScopes.includes('*')) {
+            const invalid = finalScopes.filter((s) => {
+                if (s === '*')
+                    return true; // only operator can have global wildcard
+                const [domain] = s.split(':');
+                return !config.maxAgentScopes.includes(s) && !config.maxAgentScopes.includes(`${domain}:*`);
+            });
+            if (invalid.length > 0) {
+                res.status(400).json(error(config.nodeId, 'INVALID_SCOPES', `Scopes exceed node maximum: ${invalid.join(', ')}`));
+                return;
+            }
+        }
+        // Pre-registration hook
+        const hookResult = await executeHooks(config, storage, 'pre_agent_registration', {
+            name: request.agentName,
+            owner: request.ownerName,
+            display_name: request.displayName,
+        });
+        if (!hookResult.allowed) {
+            res.status(403).json(error(config.nodeId, 'HOOK_REJECTED', hookResult.reason ?? 'Agent registration denied by extension hook'));
+            return;
+        }
+        // Check if agent already exists — if so, issue new JWT for existing agent
+        const gaii = buildGAII(request.agentName, request.ownerName, config.nodeId);
+        const existing = await storage.getAgent(gaii);
+        let keyPair;
+        const now = new Date().toISOString();
+        if (existing) {
+            // Existing agent: generate new keypair (rotate keys) and issue JWT
+            keyPair = await generateKeyPair();
+            await storage.updateAgent(gaii, {
+                publicKey: keyPair.publicKey,
+                defaultScopes: finalScopes,
+                lastSeen: now,
+            });
+        }
+        else {
+            // New agent: create from scratch
+            keyPair = await generateKeyPair();
+            await storage.createAgent({
+                name: request.agentName,
+                owner: request.ownerName,
+                gaii,
+                displayName: request.displayName ?? request.agentName,
+                description: request.description,
+                capabilities: [],
+                defaultScopes: finalScopes,
+                publicKey: keyPair.publicKey,
+                trustScore: 50,
+                morselBalance: 0,
+                createdAt: now,
+                lastSeen: now,
+            });
+            // Post-registration hook
+            fireHook(config, storage, 'post_agent_registration', { gaii, owner: request.ownerName });
+        }
+        // Issue long-lived JWT for the agent
+        const sessionId = generateSessionId();
+        const agentJwt = await issueJWT({
+            sub: gaii,
+            owner: request.ownerName,
+            node: config.nodeId,
+            roles: ['agent'],
+            scopes: finalScopes,
+        }, config.agentJwtTtlSeconds, sessionId);
+        const expiresAt = new Date(Date.now() + config.agentJwtTtlSeconds * 1000).toISOString();
+        // Store credentials + JWT for agent to poll
+        await storage.updateDeviceAuth(request.deviceCode, {
+            status: 'approved',
+            scopes: finalScopes,
+            approvedBy: ownerPayload.owner,
+            agentCredentials: {
+                gaii,
+                privateKey: keyPair.privateKey,
+                publicKey: keyPair.publicKey,
+                token: agentJwt,
+                expires_at: expiresAt,
+            },
+        });
+        res.json(success(config.nodeId, {
+            status: 'approved',
+            gaii,
+            agent_name: request.agentName,
+            existing_agent: !!existing,
+        }));
+        emitChange('agents');
+    });
+    // POST /v1/agents — register a new agent (requires owner JWT)
+    router.post('/v1/agents', requireAuth(), requireRole('owner'), validateBody(AgentRegistrationSchema, config.nodeId), async (req, res) => {
+        const { name, owner, display_name, description, capabilities, scopes } = req.body ?? {};
+        // Extension hook: pre_agent_registration
+        const hookResult = await executeHooks(config, storage, 'pre_agent_registration', { name, owner, display_name });
+        if (!hookResult.allowed) {
+            res.status(403).json(error(config.nodeId, 'HOOK_REJECTED', hookResult.reason ?? 'Agent registration denied by extension hook'));
+            return;
+        }
+        // Verify the authenticated owner matches
+        if (req.auth.owner !== owner) {
+            res.status(403).json(error(config.nodeId, 'ACCESS_DENIED', 'You can only register agents under your own owner identity'));
+            return;
+        }
+        const nameError = validateAgentName(name);
+        if (nameError) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', nameError));
+            return;
+        }
+        // Verify owner exists
+        const ownerRecord = await storage.getOwner(owner);
+        if (!ownerRecord) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', `Owner "${owner}" not found`));
+            return;
+        }
+        const gaii = buildGAII(name, owner, config.nodeId);
+        // Check for duplicate
+        const existing = await storage.getAgent(gaii);
+        if (existing) {
+            res.status(409).json(error(config.nodeId, 'NAME_TAKEN', `Agent "${name}" already exists under owner "${owner}"`));
+            return;
+        }
+        // REQ-006 — Resolve agent scopes
+        const requestedScopes = Array.isArray(scopes) ? scopes : config.defaultAgentScopes;
+        // Validate scopes against node maximum
+        if (!config.maxAgentScopes.includes('*')) {
+            const invalid = requestedScopes.filter(s => {
+                if (s === '*')
+                    return true; // only operator can have global wildcard
+                const [domain] = s.split(':');
+                return !config.maxAgentScopes.includes(s) && !config.maxAgentScopes.includes(`${domain}:*`);
+            });
+            if (invalid.length > 0) {
+                res.status(400).json(error(config.nodeId, 'INVALID_SCOPES', `Scopes exceed node maximum: ${invalid.join(', ')}`));
+                return;
+            }
+        }
+        const keyPair = await generateKeyPair();
+        const now = new Date().toISOString();
+        const agent = await storage.createAgent({
+            name,
+            owner,
+            gaii,
+            displayName: display_name,
+            description,
+            capabilities: capabilities ?? [],
+            defaultScopes: requestedScopes,
+            publicKey: keyPair.publicKey,
+            trustScore: 50,
+            morselBalance: 0,
+            createdAt: now,
+            lastSeen: now,
+        });
+        // Extension hook: post_agent_registration (fire-and-forget)
+        fireHook(config, storage, 'post_agent_registration', { gaii: agent.gaii, owner: agent.owner });
+        // SECURITY: Prevent caching of response containing private key
+        res.set('Cache-Control', 'no-store');
+        res.set('Pragma', 'no-cache');
+        res.status(201).json(success(config.nodeId, {
+            agent: {
+                gaii: agent.gaii,
+                display_name: agent.displayName,
+                description: agent.description,
+                capabilities: agent.capabilities,
+                scopes: agent.defaultScopes,
+                trust_score: agent.trustScore,
+                morsel_balance: agent.morselBalance,
+                created_at: agent.createdAt,
+            },
+            private_key: keyPair.privateKey,
+            public_key: keyPair.publicKey,
+            note: 'Store the private key securely. It cannot be retrieved again. Use it to authenticate as this agent.',
+        }, [
+            {
+                description: 'Authenticate as this agent to get a JWT',
+                method: 'POST',
+                url: '/v1/auth/token',
+                example_body: {
+                    gaii,
+                    timestamp: new Date().toISOString(),
+                    signature: 'base64(Ed25519_sign(private_key, gaii + timestamp))',
+                },
+            },
+            {
+                description: 'Store something in memory',
+                method: 'POST',
+                url: '/v1/memory',
+                example_body: {
+                    key: 'hello',
+                    value: 'world',
+                    visibility: 'private',
+                },
+            },
+        ]));
+        emitChange('agents');
+    });
+    // GET /v1/agents/device-authorize/pending — list pending device auth requests for the logged-in owner
+    router.get('/v1/agents/device-authorize/pending', requireAuth(), requireRole('owner'), async (req, res) => {
+        const pending = await storage.listPendingDeviceAuthByOwner(req.auth.owner);
+        res.json(success(config.nodeId, {
+            requests: pending.map(r => ({
+                user_code: r.userCode,
+                agent_name: r.agentName,
+                display_name: r.displayName,
+                description: r.description,
+                status: r.status,
+                created_at: r.createdAt,
+                expires_in: Math.max(0, Math.ceil((new Date(r.expiresAt).getTime() - Date.now()) / 1000)),
+            })),
+        }));
+    });
+    // GET /v1/agents/verify — device authorization consent page (must be BEFORE :gaii catch-all)
+    router.get('/v1/agents/verify', (_req, res) => {
+        const candidates = [
+            join(__dirname_agents, '..', '..', 'public', 'agent-consent.html'), // dev: src/routes/../../public
+            join(__dirname_agents, '..', '..', '..', 'public', 'agent-consent.html'), // dist: dist/src/routes/../../../public
+        ];
+        const htmlPath = candidates.find(p => existsSync(p));
+        if (htmlPath) {
+            let html = readFileSync(htmlPath, 'utf-8');
+            const nonce = res.locals.cspNonce || '';
+            if (nonce) {
+                html = html.replace(/<script(?=[ >])/g, `<script nonce="${nonce}"`);
+                html = html.replace(/<style(?=[ >])/g, `<style nonce="${nonce}"`);
+            }
+            res.type('text/html').send(html);
+        }
+        else {
+            res.status(404).type('text/plain').send('Agent consent page not found');
+        }
+    });
+    // GET /v1/agents/:gaii — public agent profile (no auth)
+    router.get('/v1/agents/:gaii', async (req, res) => {
+        // GAII contains # and @ which need URL encoding
+        const gaii = decodeURIComponent(req.params.gaii);
+        const agent = await storage.getAgent(gaii);
+        if (!agent) {
+            // Check for redirect pointer (ported agent)
+            const redirect = await storage.getMemory(gaii, '__redirect__');
+            if (redirect && typeof redirect.value === 'object' && redirect.value !== null && 'target_node_url' in redirect.value) {
+                const val = redirect.value;
+                const location = `${val.target_node_url}/v1/agents/${encodeURIComponent(gaii)}`;
+                res.setHeader('Location', location);
+                res.status(301).json(success(config.nodeId, {
+                    ported: true,
+                    target_node_url: val.target_node_url,
+                    target_node_id: val.target_node_id,
+                    ported_at: val.ported_at,
+                    message: 'Agent has been ported. Follow the Location header.',
+                }));
+                return;
+            }
+            res.status(404).json(error(config.nodeId, 'AGENT_NOT_FOUND', `Agent not found: ${gaii}`));
+            return;
+        }
+        const trust = await calculateTrustScore(gaii, storage);
+        const actions = await storage.listActions();
+        const actionsPublished = actions.filter(a => a.providerGaii === gaii).length;
+        // Update cached trust score
+        await storage.updateAgent(gaii, { trustScore: trust.score });
+        res.json(success(config.nodeId, {
+            gaii: agent.gaii,
+            display_name: agent.displayName,
+            description: agent.description,
+            capabilities: agent.capabilities,
+            trust: {
+                '@type': 'schema:Rating',
+                'schema:ratingValue': trust.score,
+                'schema:bestRating': 100,
+                'schema:worstRating': 0,
+                score: trust.score,
+                total_deliveries: trust.totalDeliveries,
+                successful_deliveries: trust.successfulDeliveries,
+                success_rate: trust.successRate,
+                avg_delivery_time_seconds: trust.avgDeliveryTimeSeconds,
+                positive_ratings: trust.positiveRatings,
+                negative_ratings: trust.negativeRatings,
+                age_days: trust.ageDays,
+            },
+            actions_published: actionsPublished,
+            semantic: agent.semantic,
+            home_node: config.nodeId,
+            created_at: agent.createdAt,
+            last_seen: agent.lastSeen,
+        }, [
+            { description: 'Browse the action catalogue', method: 'GET', url: '/v1/catalogue' },
+            { description: 'View node discovery info', method: 'GET', url: '/.well-known/aimeat' },
+        ]));
+    });
+    // GET /v1/agents — list agents (auth required, returns own agents)
+    router.get('/v1/agents', requireAuth(), async (req, res) => {
+        const agents = await storage.getAgentsByOwner(req.auth.owner);
+        res.json(success(config.nodeId, {
+            agents: agents.map(a => ({
+                gaii: a.gaii,
+                name: a.name,
+                owner: a.owner,
+                display_name: a.displayName,
+                description: a.description,
+                capabilities: a.capabilities,
+                default_scopes: a.defaultScopes ?? ['*'],
+                trust_score: a.trustScore,
+                morsel_balance: a.morselBalance,
+                created_at: a.createdAt,
+                last_seen: a.lastSeen,
+                public_key: a.publicKey,
+            })),
+        }, [
+            { description: 'Register a new agent', method: 'POST', url: '/v1/agents' },
+        ]));
+    });
+    // POST /v1/checkin — agent heartbeat (agent auth)
+    router.post('/v1/checkin', requireAuth(), requireRole('agent'), async (req, res) => {
+        const gaii = req.auth.sub;
+        const now = new Date().toISOString();
+        const agent = await storage.updateAgent(gaii, { lastSeen: now });
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'AGENT_NOT_FOUND', `Agent not found: ${gaii}`));
+            return;
+        }
+        res.json(success(config.nodeId, {
+            gaii,
+            checked_in: now,
+            trust_score: agent.trustScore,
+            morsel_balance: agent.morselBalance,
+        }));
+        emitChange('agents');
+    });
+    // POST /v1/agents/:gaii/export — Export agent data for portability (owner auth)
+    router.post('/v1/agents/:gaii/export', requireAuth(), requireRole('owner'), async (req, res) => {
+        const gaii = decodeURIComponent(req.params.gaii);
+        const agent = await storage.getAgent(gaii);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'AGENT_NOT_FOUND', `Agent not found: ${gaii}`));
+            return;
+        }
+        if (agent.owner !== req.auth.owner) {
+            res.status(403).json(error(config.nodeId, 'ACCESS_DENIED', 'You can only export your own agents'));
+            return;
+        }
+        const memories = await storage.listMemory(gaii);
+        const transactions = await storage.getTransactions(gaii, 100_000);
+        const actions = await storage.listActionsByProvider(gaii);
+        const trust = await calculateTrustScore(gaii, storage);
+        res.json(success(config.nodeId, {
+            portability_version: '1.0',
+            exported_at: new Date().toISOString(),
+            source_node: config.nodeId,
+            agent: {
+                name: agent.name,
+                owner: agent.owner,
+                gaii: agent.gaii,
+                display_name: agent.displayName,
+                description: agent.description,
+                capabilities: agent.capabilities,
+                public_key: agent.publicKey,
+                trust_score: trust.score,
+                morsel_balance: agent.morselBalance,
+                semantic: agent.semantic,
+                created_at: agent.createdAt,
+            },
+            memory: memories.map(m => ({
+                key: m.key,
+                value: m.value,
+                visibility: m.visibility,
+                tags: m.tags,
+                ttl_hours: m.ttlHours,
+                version: m.version,
+            })),
+            actions: actions.map(a => ({
+                id: a.id,
+                display_name: a.displayName,
+                description: a.description,
+                category: a.category,
+                input_schema: a.inputSchema,
+                output_schema: a.outputSchema,
+                pricing: a.pricing,
+                tags: a.tags,
+            })),
+            trust_history: {
+                total_deliveries: trust.totalDeliveries,
+                successful_deliveries: trust.successfulDeliveries,
+                positive_ratings: trust.positiveRatings,
+                negative_ratings: trust.negativeRatings,
+            },
+            transaction_count: transactions.length,
+        }, [
+            { description: 'Import to another node', method: 'POST', url: '/v1/agents/import' },
+        ]));
+        emitChange('agents');
+    });
+    // POST /v1/agents/import — Import agent from another node (owner auth)
+    router.post('/v1/agents/import', requireAuth(), requireRole('owner'), async (req, res) => {
+        const { agent: agentData, memory: memoryData, actions: actionData } = req.body ?? {};
+        if (!agentData?.name || !agentData?.owner) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'agent.name and agent.owner are required'));
+            return;
+        }
+        if (agentData.owner !== req.auth.owner) {
+            res.status(403).json(error(config.nodeId, 'ACCESS_DENIED', 'You can only import agents under your own owner identity'));
+            return;
+        }
+        const newGaii = buildGAII(agentData.name, agentData.owner, config.nodeId);
+        const existing = await storage.getAgent(newGaii);
+        if (existing) {
+            res.status(409).json(error(config.nodeId, 'NAME_TAKEN', `Agent "${agentData.name}" already exists on this node`));
+            return;
+        }
+        const keyPair = await generateKeyPair();
+        const now = new Date().toISOString();
+        // Import with capped trust score (new node starts lower)
+        const importedTrust = Math.min(agentData.trust_score ?? 50, 65);
+        const agent = await storage.createAgent({
+            name: agentData.name,
+            owner: agentData.owner,
+            gaii: newGaii,
+            displayName: agentData.display_name,
+            description: agentData.description,
+            capabilities: agentData.capabilities ?? [],
+            publicKey: keyPair.publicKey,
+            trustScore: importedTrust,
+            morselBalance: 0, // agents use GHII owner balance
+            createdAt: now,
+            lastSeen: now,
+        });
+        // Import memories
+        let memoriesImported = 0;
+        if (Array.isArray(memoryData)) {
+            for (const m of memoryData) {
+                if (!m.key)
+                    continue;
+                await storage.setMemory({
+                    key: m.key,
+                    ownerGaii: newGaii,
+                    value: m.value,
+                    visibility: m.visibility ?? 'private',
+                    tags: m.tags ?? [],
+                    ttlHours: m.ttl_hours ?? null,
+                    version: 1,
+                    createdAt: now,
+                    updatedAt: now,
+                });
+                memoriesImported++;
+            }
+        }
+        // Import actions
+        let actionsImported = 0;
+        if (Array.isArray(actionData)) {
+            for (const a of actionData) {
+                if (!a.id || !a.display_name)
+                    continue;
+                try {
+                    await storage.createAction({
+                        id: a.id,
+                        providerGaii: newGaii,
+                        displayName: a.display_name,
+                        description: a.description ?? '',
+                        category: a.category,
+                        inputSchema: a.input_schema ?? {},
+                        outputSchema: a.output_schema ?? {},
+                        pricing: a.pricing ?? { baseMorsels: 0 },
+                        tags: a.tags ?? [],
+                        createdAt: now,
+                        updatedAt: now,
+                    });
+                    actionsImported++;
+                }
+                catch { /* skip duplicates */ }
+            }
+        }
+        // SECURITY: Prevent caching of response containing private key
+        res.set('Cache-Control', 'no-store');
+        res.set('Pragma', 'no-cache');
+        res.status(201).json(success(config.nodeId, {
+            agent: {
+                gaii: agent.gaii,
+                display_name: agent.displayName,
+                trust_score: agent.trustScore,
+                morsel_balance: agent.morselBalance,
+            },
+            imported: {
+                memories: memoriesImported,
+                actions: actionsImported,
+            },
+            private_key: keyPair.privateKey,
+            public_key: keyPair.publicKey,
+            note: 'Agent imported with new keys. Store the private key securely.',
+        }));
+        emitChange('agents');
+    });
+    // POST /v1/agents/:gaii/rekey — Rotate agent keys (owner auth)
+    router.post('/v1/agents/:gaii/rekey', requireAuth(), requireRole('owner'), async (req, res) => {
+        const gaii = decodeURIComponent(req.params.gaii);
+        const agent = await storage.getAgent(gaii);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'AGENT_NOT_FOUND', `Agent not found: ${gaii}`));
+            return;
+        }
+        if (agent.owner !== req.auth.owner) {
+            res.status(403).json(error(config.nodeId, 'ACCESS_DENIED', 'You can only rekey your own agents'));
+            return;
+        }
+        const keyPair = await generateKeyPair();
+        await storage.updateAgent(gaii, { publicKey: keyPair.publicKey });
+        // Extension hook: agent_rekey (fire-and-forget)
+        fireHook(config, storage, 'agent_rekey', { gaii, owner: agent.owner });
+        // SECURITY: Prevent caching of response containing private key
+        res.set('Cache-Control', 'no-store');
+        res.set('Pragma', 'no-cache');
+        res.json(success(config.nodeId, {
+            rekeyed: true,
+            gaii,
+            private_key: keyPair.privateKey,
+            public_key: keyPair.publicKey,
+            note: 'New keys generated. Store the private key securely. Old JWT tokens are invalidated.',
+        }));
+        emitChange('agents');
+    });
+    // POST /v1/agents/:gaii/port — Port agent to another node (owner auth)
+    // Sets a redirect pointer on this node + deducts porting fee
+    router.post('/v1/agents/:gaii/port', requireAuth(), requireRole('owner'), async (req, res) => {
+        const gaii = decodeURIComponent(req.params.gaii);
+        const agent = await storage.getAgent(gaii);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'AGENT_NOT_FOUND', `Agent not found: ${gaii}`));
+            return;
+        }
+        if (agent.owner !== req.auth.owner) {
+            res.status(403).json(error(config.nodeId, 'ACCESS_DENIED', 'You can only port your own agents'));
+            return;
+        }
+        const { target_node_url, target_node_id } = req.body ?? {};
+        if (!target_node_url) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'target_node_url is required'));
+            return;
+        }
+        // Porting fee — atomic debit prevents double-spending
+        const PORTING_FEE = config.agentPortingFeeMorsels;
+        const debited = await storage.debitBalance(gaii, PORTING_FEE);
+        if (!debited) {
+            res.status(402).json(error(config.nodeId, 'INSUFFICIENT_MORSELS', `Porting requires ${PORTING_FEE} morsels, you have ${agent.morselBalance}`));
+            return;
+        }
+        await storage.addTransaction({
+            id: `tx-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
+            gaii,
+            type: 'spent',
+            amount: -PORTING_FEE,
+            timestamp: new Date().toISOString(),
+        });
+        // Store redirect pointer (use memory to persist the redirect)
+        await storage.setMemory({
+            key: `__redirect__`,
+            ownerGaii: gaii,
+            value: { target_node_url, target_node_id: target_node_id ?? 'unknown', ported_at: new Date().toISOString() },
+            visibility: 'public',
+            tags: ['system', 'redirect'],
+            ttlHours: 30 * 24,
+            version: 1,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        });
+        res.json(success(config.nodeId, {
+            ported: true,
+            gaii,
+            target_node_url,
+            porting_fee: PORTING_FEE,
+            note: 'Redirect pointer set. Export and import agent data to complete the port.',
+        }, [
+            { description: 'Export agent data', method: 'POST', url: `/v1/agents/${encodeURIComponent(gaii)}/export` },
+        ]));
+        emitChange('agents');
+    });
+    // PATCH /v1/agents/:name/scopes — update agent scopes (owner only)
+    router.patch('/v1/agents/:name/scopes', requireAuth(), requireRole('owner'), async (req, res) => {
+        const agentName = req.params.name;
+        const ownerName = req.auth.owner;
+        const { scopes } = req.body ?? {};
+        if (!Array.isArray(scopes) || scopes.length === 0) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'scopes must be a non-empty array of strings'));
+            return;
+        }
+        // Validate all scopes are strings
+        if (!scopes.every((s) => typeof s === 'string')) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'Each scope must be a string'));
+            return;
+        }
+        // Validate scopes against node maximum
+        if (!config.maxAgentScopes.includes('*')) {
+            const invalid = scopes.filter((s) => {
+                if (s === '*')
+                    return true;
+                const [domain] = s.split(':');
+                return !config.maxAgentScopes.includes(s) && !config.maxAgentScopes.includes(`${domain}:*`);
+            });
+            if (invalid.length > 0) {
+                res.status(400).json(error(config.nodeId, 'INVALID_SCOPES', `Scopes exceed node maximum: ${invalid.join(', ')}`));
+                return;
+            }
+        }
+        // Find the agent by name under this owner
+        const agents = await storage.getAgentsByOwner(ownerName);
+        const agent = agents.find(a => a.name === agentName);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', `Agent "${agentName}" not found under owner "${ownerName}"`));
+            return;
+        }
+        // Defense-in-depth: verify ownership even though getAgentsByOwner is scoped
+        if (agent.owner !== req.auth.owner) {
+            res.status(403).json(error(config.nodeId, 'ACCESS_DENIED', 'You can only modify your own agents'));
+            return;
+        }
+        const updated = await storage.updateAgent(agent.gaii, { defaultScopes: scopes });
+        if (!updated) {
+            res.status(500).json(error(config.nodeId, 'INTERNAL', 'Failed to update agent scopes'));
+            return;
+        }
+        res.json(success(config.nodeId, {
+            gaii: updated.gaii,
+            scopes: updated.defaultScopes,
+        }, [
+            { description: 'Re-authenticate to get a new JWT with updated scopes', method: 'POST', url: '/v1/auth/token' },
+        ]));
+        emitChange('agents');
+    });
+    // DELETE /v1/agents/:name — delete an agent (owner only)
+    router.delete('/v1/agents/:name', requireAuth(), requireRole('owner'), async (req, res) => {
+        const agentName = req.params.name;
+        const ownerName = req.auth.owner;
+        const agents = await storage.getAgentsByOwner(ownerName);
+        const agent = agents.find(a => a.name === agentName);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', `Agent "${agentName}" not found under owner "${ownerName}"`));
+            return;
+        }
+        if (agent.owner !== req.auth.owner) {
+            res.status(403).json(error(config.nodeId, 'ACCESS_DENIED', 'You can only delete your own agents'));
+            return;
+        }
+        const deleted = await storage.deleteAgent(agent.gaii);
+        if (!deleted) {
+            res.status(500).json(error(config.nodeId, 'INTERNAL', 'Failed to delete agent'));
+            return;
+        }
+        res.json(success(config.nodeId, { deleted: true, name: agentName, gaii: agent.gaii }));
+        emitChange('agents');
+    });
+    // ── CORS per-agent management ──
+    // GET /v1/agents/:name/cors — Get agent CORS allowed origins
+    router.get('/v1/agents/:name/cors', requireAuth(), requireRole('owner'), async (req, res) => {
+        const agentName = req.params.name;
+        const ownerName = req.auth.owner;
+        const agents = await storage.getAgentsByOwner(ownerName);
+        const agent = agents.find(a => a.name === agentName);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', `Agent "${agentName}" not found`));
+            return;
+        }
+        // Resolve effective origins: agent → GHII owner → node default
+        let effective = config.corsAllowedOrigins;
+        let inherited = 'node';
+        if (agent.allowedOrigins?.length) {
+            effective = agent.allowedOrigins;
+            inherited = 'none';
+        }
+        else {
+            const ghii = await storage.getGHIIByOwner(ownerName);
+            if (ghii?.allowedOrigins?.length) {
+                effective = ghii.allowedOrigins;
+                inherited = 'ghii';
+            }
+        }
+        res.json(success(config.nodeId, {
+            gaii: agent.gaii,
+            allowed_origins: agent.allowedOrigins ?? null,
+            effective,
+            inherited_from: inherited,
+        }));
+    });
+    // PUT /v1/agents/:name/cors — Set agent CORS allowed origins
+    router.put('/v1/agents/:name/cors', requireAuth(), requireRole('owner'), async (req, res) => {
+        const agentName = req.params.name;
+        const ownerName = req.auth.owner;
+        const agents = await storage.getAgentsByOwner(ownerName);
+        const agent = agents.find(a => a.name === agentName);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', `Agent "${agentName}" not found`));
+            return;
+        }
+        // Defense-in-depth: verify ownership even though getAgentsByOwner is scoped
+        if (agent.owner !== req.auth.owner) {
+            res.status(403).json(error(config.nodeId, 'ACCESS_DENIED', 'You can only modify your own agents'));
+            return;
+        }
+        const { allowed_origins } = req.body ?? {};
+        if (allowed_origins !== null && !Array.isArray(allowed_origins)) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'allowed_origins must be an array of origin URLs or null to inherit'));
+            return;
+        }
+        if (Array.isArray(allowed_origins)) {
+            for (const origin of allowed_origins) {
+                if (typeof origin !== 'string' || (origin !== '*' && !/^https?:\/\//.test(origin))) {
+                    res.status(400).json(error(config.nodeId, 'INVALID_INPUT', `Invalid origin: ${origin}. Must be an http(s) URL or '*'`));
+                    return;
+                }
+            }
+        }
+        const updated = await storage.updateAgent(agent.gaii, {
+            allowedOrigins: allowed_origins === null ? undefined : allowed_origins,
+        });
+        if (!updated) {
+            res.status(500).json(error(config.nodeId, 'INTERNAL', 'Failed to update CORS settings'));
+            return;
+        }
+        res.json(success(config.nodeId, {
+            gaii: updated.gaii,
+            allowed_origins: updated.allowedOrigins ?? null,
+        }));
+        emitChange('agents');
+    });
+    return router;
+}
+//# sourceMappingURL=agents.js.map