@vorionsys/platform-core 0.1.0

package/dist/car-extensions/registry.js

@@ -0,0 +1,450 @@
+/**
+ * CAR Extension Registry
+ *
+ * Manages registration, lookup, and validation of CAR extensions.
+ * Extensions are identified by their unique extensionId and can also
+ * be looked up by their shortcode for CAR string parsing.
+ *
+ * @packageDocumentation
+ * @module @vorion/car-extensions/registry
+ * @license Apache-2.0
+ */
+import { isValidExtensionId, isValidShortcode, } from "./car-string-extensions.js";
+import { CARExtensionMetadataSchema } from "./types.js";
+import { ValidationError, ConflictError, NotFoundError, } from "../common/errors.js";
+import { createLogger } from "../common/logger.js";
+const logger = createLogger({ component: "car-extension-registry" });
+/**
+ * Registry for CAR extensions
+ *
+ * Provides centralized management of Layer 4 extensions including:
+ * - Registration and unregistration
+ * - Lookup by ID or shortcode
+ * - Validation of extension metadata and structure
+ * - Lifecycle management (load/unload hooks)
+ *
+ * @example
+ * ```typescript
+ * const registry = new ExtensionRegistry();
+ *
+ * // Register an extension
+ * registry.register(myExtension);
+ *
+ * // Look up by ID
+ * const ext = registry.get('car-ext-governance-v1');
+ *
+ * // Look up by shortcode
+ * const ext2 = registry.getByShortcode('gov');
+ *
+ * // List all extensions
+ * const all = registry.list();
+ * ```
+ */
+export class ExtensionRegistry {
+    /** Map of extensionId to extension instance */
+    extensions = new Map();
+    /** Map of shortcode to extensionId for quick lookup */
+    shortcodes = new Map();
+    /** Map of extensionId to registration timestamp */
+    registrationTimes = new Map();
+    /** Map of extensionId to loaded state */
+    loadedState = new Map();
+    /**
+     * Register an extension with the registry
+     *
+     * Validates the extension metadata and structure, then registers it
+     * for use. If the extension has an onLoad hook, it will be called.
+     *
+     * @param extension - The extension to register
+     * @throws {ValidationError} If extension fails validation
+     * @throws {ConflictError} If extensionId or shortcode is already registered
+     *
+     * @example
+     * ```typescript
+     * registry.register({
+     *   extensionId: 'car-ext-custom-v1',
+     *   name: 'Custom Extension',
+     *   version: '1.0.0',
+     *   shortcode: 'cust',
+     *   publisher: 'did:web:example.com',
+     *   description: 'A custom extension',
+     *   requiredCARVersion: '>=1.0.0',
+     * });
+     * ```
+     */
+    async register(extension) {
+        // Validate extension
+        const validation = this.validate(extension);
+        if (!validation.valid) {
+            throw new ValidationError(`Extension validation failed: ${validation.errors.join(", ")}`, { extensionId: extension.extensionId, errors: validation.errors });
+        }
+        // Check for duplicate extensionId
+        if (this.extensions.has(extension.extensionId)) {
+            throw new ConflictError(`Extension already registered: ${extension.extensionId}`, { extensionId: extension.extensionId });
+        }
+        // Check for duplicate shortcode
+        if (this.shortcodes.has(extension.shortcode)) {
+            const existingId = this.shortcodes.get(extension.shortcode);
+            throw new ConflictError(`Shortcode '${extension.shortcode}' already registered by ${existingId}`, { shortcode: extension.shortcode, existingExtensionId: existingId });
+        }
+        // Register the extension
+        this.extensions.set(extension.extensionId, extension);
+        this.shortcodes.set(extension.shortcode, extension.extensionId);
+        this.registrationTimes.set(extension.extensionId, new Date());
+        this.loadedState.set(extension.extensionId, false);
+        // Call onLoad hook if present
+        if (extension.hooks?.onLoad) {
+            try {
+                await extension.hooks.onLoad();
+                this.loadedState.set(extension.extensionId, true);
+                logger.info({
+                    extensionId: extension.extensionId,
+                    shortcode: extension.shortcode,
+                }, "Extension loaded successfully");
+            }
+            catch (error) {
+                // Rollback registration on load failure
+                this.extensions.delete(extension.extensionId);
+                this.shortcodes.delete(extension.shortcode);
+                this.registrationTimes.delete(extension.extensionId);
+                this.loadedState.delete(extension.extensionId);
+                const message = error instanceof Error ? error.message : "Unknown error";
+                logger.error({ extensionId: extension.extensionId, error: message }, "Extension onLoad hook failed");
+                throw new ValidationError(`Extension onLoad failed: ${message}`, {
+                    extensionId: extension.extensionId,
+                });
+            }
+        }
+        else {
+            this.loadedState.set(extension.extensionId, true);
+            logger.info({ extensionId: extension.extensionId, shortcode: extension.shortcode }, "Extension registered");
+        }
+        // Log warnings from validation
+        if (validation.warnings.length > 0) {
+            logger.warn({ extensionId: extension.extensionId, warnings: validation.warnings }, "Extension registered with warnings");
+        }
+    }
+    /**
+     * Unregister an extension from the registry
+     *
+     * If the extension has an onUnload hook, it will be called before removal.
+     *
+     * @param extensionId - The ID of the extension to unregister
+     * @throws {NotFoundError} If extension is not registered
+     *
+     * @example
+     * ```typescript
+     * await registry.unregister('car-ext-custom-v1');
+     * ```
+     */
+    async unregister(extensionId) {
+        const extension = this.extensions.get(extensionId);
+        if (!extension) {
+            throw new NotFoundError(`Extension not found: ${extensionId}`, {
+                extensionId,
+            });
+        }
+        // Call onUnload hook if present
+        if (extension.hooks?.onUnload) {
+            try {
+                await extension.hooks.onUnload();
+                logger.info({ extensionId }, "Extension onUnload hook completed");
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "Unknown error";
+                logger.error({ extensionId, error: message }, "Extension onUnload hook failed (continuing with unregistration)");
+            }
+        }
+        // Remove from registry
+        this.shortcodes.delete(extension.shortcode);
+        this.extensions.delete(extensionId);
+        this.registrationTimes.delete(extensionId);
+        this.loadedState.delete(extensionId);
+        logger.info({ extensionId }, "Extension unregistered");
+    }
+    /**
+     * Get an extension by its ID
+     *
+     * @param extensionId - The extension ID to look up
+     * @returns The extension if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const ext = registry.get('car-ext-governance-v1');
+     * if (ext) {
+     *   // Use extension
+     * }
+     * ```
+     */
+    get(extensionId) {
+        return this.extensions.get(extensionId);
+    }
+    /**
+     * Get an extension by its shortcode
+     *
+     * @param shortcode - The shortcode to look up (e.g., "gov", "audit")
+     * @returns The extension if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const ext = registry.getByShortcode('gov');
+     * ```
+     */
+    getByShortcode(shortcode) {
+        const extensionId = this.shortcodes.get(shortcode);
+        if (!extensionId) {
+            return undefined;
+        }
+        return this.extensions.get(extensionId);
+    }
+    /**
+     * Get extension ID by shortcode
+     *
+     * @param shortcode - The shortcode to look up
+     * @returns The extension ID if found, undefined otherwise
+     */
+    getIdByShortcode(shortcode) {
+        return this.shortcodes.get(shortcode);
+    }
+    /**
+     * Check if an extension is registered
+     *
+     * @param extensionId - The extension ID to check
+     * @returns True if registered, false otherwise
+     */
+    has(extensionId) {
+        return this.extensions.has(extensionId);
+    }
+    /**
+     * Check if a shortcode is registered
+     *
+     * @param shortcode - The shortcode to check
+     * @returns True if registered, false otherwise
+     */
+    hasShortcode(shortcode) {
+        return this.shortcodes.has(shortcode);
+    }
+    /**
+     * List all registered extensions
+     *
+     * @returns Array of extension information
+     *
+     * @example
+     * ```typescript
+     * const extensions = registry.list();
+     * for (const info of extensions) {
+     *   console.log(`${info.name} (${info.shortcode})`);
+     * }
+     * ```
+     */
+    list() {
+        const result = [];
+        for (const [extensionId, extension] of Array.from(this.extensions.entries())) {
+            result.push({
+                extensionId,
+                name: extension.name,
+                version: extension.version,
+                shortcode: extension.shortcode,
+                publisher: extension.publisher,
+                description: extension.description,
+                registeredAt: this.registrationTimes.get(extensionId) ?? new Date(),
+                loaded: this.loadedState.get(extensionId) ?? false,
+                hooks: this.getAvailableHooks(extension),
+            });
+        }
+        return result;
+    }
+    /**
+     * Get multiple extensions by their IDs
+     *
+     * @param extensionIds - Array of extension IDs
+     * @returns Array of found extensions (missing ones are omitted)
+     */
+    getMany(extensionIds) {
+        const result = [];
+        for (const id of extensionIds) {
+            const ext = this.extensions.get(id);
+            if (ext) {
+                result.push(ext);
+            }
+        }
+        return result;
+    }
+    /**
+     * Get multiple extensions by their shortcodes
+     *
+     * @param shortcodes - Array of shortcodes
+     * @returns Array of found extensions (missing ones are omitted)
+     */
+    getManyByShortcode(shortcodes) {
+        const result = [];
+        for (const shortcode of shortcodes) {
+            const ext = this.getByShortcode(shortcode);
+            if (ext) {
+                result.push(ext);
+            }
+        }
+        return result;
+    }
+    /**
+     * Validate an extension's metadata and structure
+     *
+     * Checks:
+     * - Extension ID format (car-ext-{name}-v{version})
+     * - Shortcode format (lowercase, 1-10 chars)
+     * - Required metadata fields
+     * - Version format (semver)
+     * - Hook implementations
+     *
+     * @param extension - The extension to validate
+     * @returns Validation result with errors and warnings
+     *
+     * @example
+     * ```typescript
+     * const result = registry.validate(myExtension);
+     * if (!result.valid) {
+     *   console.error('Validation errors:', result.errors);
+     * }
+     * ```
+     */
+    validate(extension) {
+        const errors = [];
+        const warnings = [];
+        // Validate metadata with Zod
+        const metadataResult = CARExtensionMetadataSchema.safeParse({
+            extensionId: extension.extensionId,
+            name: extension.name,
+            version: extension.version,
+            shortcode: extension.shortcode,
+            publisher: extension.publisher,
+            description: extension.description,
+            requiredCARVersion: extension.requiredCARVersion,
+        });
+        if (!metadataResult.success) {
+            for (const issue of metadataResult.error.issues) {
+                errors.push(`${issue.path.join(".")}: ${issue.message}`);
+            }
+        }
+        // Additional validation beyond Zod
+        if (!isValidExtensionId(extension.extensionId)) {
+            errors.push(`Invalid extension ID format: ${extension.extensionId}. Expected: car-ext-{name}-v{version}`);
+        }
+        if (!isValidShortcode(extension.shortcode)) {
+            errors.push(`Invalid shortcode format: ${extension.shortcode}. Expected: 1-10 lowercase letters`);
+        }
+        // Validate that extension ID version matches extension.version major
+        const idVersionMatch = extension.extensionId.match(/-v(\d+)$/);
+        const versionMajor = extension.version.split(".")[0];
+        if (idVersionMatch && idVersionMatch[1] !== versionMajor) {
+            warnings.push(`Extension ID version (v${idVersionMatch[1]}) does not match version major (${versionMajor})`);
+        }
+        // Check for at least one hook implementation
+        const hasHooks = this.getAvailableHooks(extension).length > 0;
+        if (!hasHooks) {
+            warnings.push("Extension has no hook implementations");
+        }
+        // Validate publisher DID format
+        if (!extension.publisher.startsWith("did:")) {
+            warnings.push("Publisher should be a DID (e.g., did:web:example.com)");
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    /**
+     * Get the count of registered extensions
+     *
+     * @returns Number of registered extensions
+     */
+    get size() {
+        return this.extensions.size;
+    }
+    /**
+     * Clear all registered extensions
+     *
+     * Calls onUnload for each extension before clearing.
+     * Use with caution - primarily for testing.
+     */
+    async clear() {
+        const extensionIds = Array.from(this.extensions.keys());
+        for (const extensionId of extensionIds) {
+            try {
+                await this.unregister(extensionId);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "Unknown error";
+                logger.error({ extensionId, error: message }, "Error unregistering extension during clear");
+            }
+        }
+        this.extensions.clear();
+        this.shortcodes.clear();
+        this.registrationTimes.clear();
+        this.loadedState.clear();
+        logger.info("Extension registry cleared");
+    }
+    /**
+     * Get available hooks for an extension
+     *
+     * @param extension - The extension to check
+     * @returns Array of hook names that are implemented
+     */
+    getAvailableHooks(extension) {
+        const hooks = [];
+        // Lifecycle hooks
+        if (extension.hooks?.onLoad)
+            hooks.push("hooks.onLoad");
+        if (extension.hooks?.onUnload)
+            hooks.push("hooks.onUnload");
+        // Capability hooks
+        if (extension.capability?.preCheck)
+            hooks.push("capability.preCheck");
+        if (extension.capability?.postGrant)
+            hooks.push("capability.postGrant");
+        if (extension.capability?.onExpiry)
+            hooks.push("capability.onExpiry");
+        // Action hooks
+        if (extension.action?.preAction)
+            hooks.push("action.preAction");
+        if (extension.action?.postAction)
+            hooks.push("action.postAction");
+        if (extension.action?.onFailure)
+            hooks.push("action.onFailure");
+        // Monitoring hooks
+        if (extension.monitoring?.verifyBehavior)
+            hooks.push("monitoring.verifyBehavior");
+        if (extension.monitoring?.collectMetrics)
+            hooks.push("monitoring.collectMetrics");
+        if (extension.monitoring?.onAnomaly)
+            hooks.push("monitoring.onAnomaly");
+        // Trust hooks
+        if (extension.trust?.onRevocation)
+            hooks.push("trust.onRevocation");
+        if (extension.trust?.adjustTrust)
+            hooks.push("trust.adjustTrust");
+        if (extension.trust?.verifyAttestation)
+            hooks.push("trust.verifyAttestation");
+        // Policy engine
+        if (extension.policy?.evaluate)
+            hooks.push("policy.evaluate");
+        if (extension.policy?.loadPolicy)
+            hooks.push("policy.loadPolicy");
+        return hooks;
+    }
+}
+/**
+ * Create a new extension registry instance
+ *
+ * @returns A new ExtensionRegistry instance
+ *
+ * @example
+ * ```typescript
+ * const registry = createExtensionRegistry();
+ * await registry.register(myExtension);
+ * ```
+ */
+export function createExtensionRegistry() {
+    return new ExtensionRegistry();
+}
+//# sourceMappingURL=registry.js.map

package/dist/car-extensions/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/car-extensions/registry.ts"],"names":[],"mappings":"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"}

package/dist/car-extensions/service.d.ts

@@ -0,0 +1,220 @@
+/**
+ * CAR Extension Service
+ *
+ * Main service for coordinating extension execution. Provides a high-level
+ * API for processing capability requests, actions, and behavioral verification
+ * through the registered extensions.
+ *
+ * @packageDocumentation
+ * @module @vorion/car-extensions/service
+ * @license Apache-2.0
+ */
+import { ExtensionExecutor } from "./executor.js";
+import { ExtensionRegistry } from "./registry.js";
+import type { CARExtension, AgentIdentity, CapabilityRequest, CapabilityGrant, ActionRequest, ActionResult, RevocationEvent, BehaviorVerificationResult, ExtensionServiceConfig } from "./types.js";
+/**
+ * Result of processing a capability request
+ */
+export interface CapabilityRequestResult {
+    /** Whether the request was granted */
+    granted: boolean;
+    /** The capability grant if successful */
+    grant?: CapabilityGrant;
+    /** Denial reason if not granted */
+    denialReason?: string;
+    /** Extension that denied the request */
+    deniedBy?: string;
+    /** Extensions that were evaluated */
+    extensionsEvaluated: string[];
+}
+/**
+ * Result of processing an action
+ */
+export interface ActionProcessingResult {
+    /** Whether the action was allowed to proceed */
+    proceeded: boolean;
+    /** The action result if executed */
+    result?: ActionResult;
+    /** Blocking reason if not allowed */
+    blockingReason?: string;
+    /** Extension that blocked the action */
+    blockedBy?: string;
+    /** Required approvals if any */
+    requiredApprovals?: Array<{
+        type: "human" | "system" | "manager";
+        approver?: string;
+        timeout?: number;
+    }>;
+    /** Extensions that were evaluated */
+    extensionsEvaluated: string[];
+}
+/**
+ * CAR Extension Service
+ *
+ * Provides the main interface for integrating extensions into the
+ * Vorion governance system. Coordinates extension loading, execution,
+ * and result aggregation.
+ *
+ * @example
+ * ```typescript
+ * // Create service
+ * const registry = new ExtensionRegistry();
+ * const executor = new ExtensionExecutor(registry);
+ * const service = new CARExtensionService(registry, executor);
+ *
+ * // Register extensions
+ * await service.registerExtension(cognigateExtension);
+ * await service.registerExtension(auditExtension);
+ *
+ * // Process a capability request
+ * const result = await service.processCapabilityRequest(agent, {
+ *   domains: ['data', 'compute'],
+ *   level: 3,
+ *   context: { source: 'api', purpose: 'data-analysis' },
+ * });
+ *
+ * if (result.granted) {
+ *   console.log('Capability granted:', result.grant);
+ * }
+ * ```
+ */
+export declare class CARExtensionService {
+    private registry;
+    private executor;
+    private config;
+    /**
+     * Create a new extension service
+     *
+     * @param registry - Extension registry to use
+     * @param executor - Extension executor to use
+     * @param config - Optional service configuration
+     */
+    constructor(registry: ExtensionRegistry, executor: ExtensionExecutor, config?: ExtensionServiceConfig);
+    /**
+     * Register an extension with the service
+     *
+     * @param extension - Extension to register
+     */
+    registerExtension(extension: CARExtension): Promise<void>;
+    /**
+     * Unregister an extension from the service
+     *
+     * @param extensionId - ID of extension to unregister
+     */
+    unregisterExtension(extensionId: string): Promise<void>;
+    /**
+     * Load extensions for an agent based on their CAR string
+     *
+     * Parses the CAR string's extension suffix and returns the
+     * corresponding registered extensions.
+     *
+     * @param carId - Agent's CAR string (may include #extension suffixes)
+     * @returns Array of loaded extensions
+     *
+     * @example
+     * ```typescript
+     * // CAR: a3i.vorion.agent:FHC-L3@1.0.0#gov,audit
+     * const extensions = service.loadAgentExtensions(agent.carId);
+     * // Returns [cognigateExtension, auditExtension]
+     * ```
+     */
+    loadAgentExtensions(carId: string): CARExtension[];
+    /**
+     * Get extension IDs for an agent
+     *
+     * @param carId - Agent's CAR string
+     * @returns Array of extension IDs
+     */
+    getAgentExtensionIds(carId: string): string[];
+    /**
+     * Process a capability request through all applicable extensions
+     *
+     * Executes preCheck hooks from all extensions, and if all allow,
+     * creates a capability grant and runs postGrant hooks.
+     *
+     * @param agent - Agent making the request
+     * @param request - Capability request
+     * @returns Result of processing the request
+     */
+    processCapabilityRequest(agent: AgentIdentity, request: CapabilityRequest): Promise<CapabilityRequestResult>;
+    /**
+     * Process an action through all applicable extensions
+     *
+     * Executes preAction hooks, and if all allow, executes the action
+     * and runs postAction hooks. If the action fails, runs onFailure hooks.
+     *
+     * @param agent - Agent performing the action
+     * @param actionRequest - Action to perform
+     * @param executeAction - Function to execute the actual action
+     * @returns Result of processing the action
+     */
+    processAction(agent: AgentIdentity, actionRequest: ActionRequest, executeAction?: (request: ActionRequest) => Promise<ActionResult>): Promise<ActionProcessingResult>;
+    /**
+     * Run behavioral verification for an agent
+     *
+     * Collects metrics and runs behavior verification hooks from all
+     * applicable extensions.
+     *
+     * @param agent - Agent to verify
+     * @returns Behavior verification result
+     */
+    verifyBehavior(agent: AgentIdentity): Promise<BehaviorVerificationResult>;
+    /**
+     * Handle a revocation event
+     *
+     * Propagates the revocation to all registered extensions that have
+     * onRevocation handlers.
+     *
+     * @param revocation - Revocation event to handle
+     */
+    handleRevocation(revocation: RevocationEvent): Promise<void>;
+    /**
+     * Evaluate policies for a given context
+     *
+     * @param agent - Agent to evaluate policies for
+     * @param action - Optional action being evaluated
+     * @param capability - Optional capability being requested
+     * @returns Policy decision
+     */
+    evaluatePolicy(agent: AgentIdentity, action?: ActionRequest, capability?: CapabilityRequest): Promise<{
+        decision: "allow" | "deny" | "require_approval";
+        reasons: string[];
+    }>;
+    /**
+     * Create a default capability grant
+     */
+    private createDefaultGrant;
+    /**
+     * Apply modifications to an action request
+     */
+    private applyModifications;
+}
+/**
+ * Create a new CAR Extension Service with default configuration
+ *
+ * @param config - Optional service configuration
+ * @returns Configured extension service
+ *
+ * @example
+ * ```typescript
+ * const service = createExtensionService();
+ *
+ * // Register built-in extensions
+ * await service.registerExtension(cognigateExtension);
+ * await service.registerExtension(monitoringExtension);
+ * await service.registerExtension(auditExtension);
+ *
+ * // Use the service
+ * const result = await service.processCapabilityRequest(agent, request);
+ * ```
+ */
+export declare function createExtensionService(config?: ExtensionServiceConfig): CARExtensionService;
+/**
+ * Create an extension service with a pre-configured registry
+ *
+ * @param registry - Pre-configured registry
+ * @param config - Optional service configuration
+ * @returns Configured extension service
+ */
+export declare function createExtensionServiceWithRegistry(registry: ExtensionRegistry, config?: ExtensionServiceConfig): CARExtensionService;
+//# sourceMappingURL=service.d.ts.map