Interfaces for Extensibility

The @ithena-one/mcp-governance SDK is designed to be pluggable. You integrate it with your existing infrastructure (Identity Providers, Secret Managers, Logging/Auditing systems) by implementing these core interfaces and providing them in the GovernedServerOptions.

IdentityResolver

• File: src/interfaces/identity.ts
• Purpose: Determines the identity of the user/system making the request. Foundation for authentication & authorization.

Methods

• initialize?(): Promise<void>: Optional setup (e.g., init SDKs, warm caches). Called during connect(). Throw to abort.
• resolveIdentity(opCtx: OperationContext): Promise<UserIdentity | null>:
  • Required. Examines opCtx (headers, message) for credentials (JWT, API key, etc.).
  • Validates credentials against your IDP.
  • Returns UserIdentity (string or {id: ...}) on success.
  • Returns null for anonymous access (if allowed).
  • Throws AuthenticationError on failure.
• shutdown?(): Promise<void>: Optional cleanup (e.g., close connections). Called during close().

Implementation Notes

RoleStore

• File: src/interfaces/rbac.ts
• Purpose: Retrieves roles for a resolved identity. Required if enableRbac is true.

Methods

• initialize?(): Promise<void>: Optional setup.
• getRoles(identity: UserIdentity, opCtx: OperationContext): Promise<string[]>:
  • Required if RBAC enabled. Queries your system (LDAP, DB, IDP claims) for roles assigned to the identity.
  • Returns an array of role strings (e.g., ['admin', 'editor']). Return [] if no roles.
• shutdown?(): Promise<void>: Optional cleanup.

Implementation Notes

• Map the UserIdentity object/string returned by your IdentityResolver to the roles defined in your authorization system.

PermissionStore

• File: src/interfaces/rbac.ts
• Purpose: Checks if a role possesses a specific permission. Required if enableRbac is true.

Methods

• initialize?(): Promise<void>: Optional setup.
• hasPermission(role: string, permission: string, opCtx: OperationContext): Promise<boolean>:
  • Required if RBAC enabled. Checks if the given role grants the permission string (from derivePermission).
  • Check against your system’s rules (DB, policy engine, etc.).
  • Return true if granted, false otherwise.
• shutdown?(): Promise<void>: Optional cleanup.

Implementation Notes

• Can be simple role-to-permission mapping or integrate with policy engines (e.g., OPA). Consider wildcard support (*).

CredentialResolver

• File: src/interfaces/credentials.ts
• Purpose: Securely fetches sensitive credentials (API keys, tokens) needed by your handlers.

Methods

• initialize?(): Promise<void>: Optional setup (e.g., connect to secrets manager).
• resolveCredentials(identity: UserIdentity | null, opCtx: OperationContext): Promise<ResolvedCredentials | null | undefined>:
  • Optional. Called after authorization.
  • Determine needed credentials based on identity or opCtx.mcpMessage.
  • Fetch securely from secrets manager (Vault, AWS Secrets Manager, Azure Key Vault). Avoid hardcoding secrets.
  • Return ResolvedCredentials (a Record<string, any>) or null/undefined if none needed.
  • Throws CredentialResolutionError if fetching fails (may fail request based on config).
• shutdown?(): Promise<void>: Optional cleanup.

Implementation Notes

• Focus on secure retrieval. Returned credentials are passed to handlers via GovernedRequestHandlerExtra.

AuditLogStore

• File: src/interfaces/audit.ts
• Purpose: Receives audit records for storage/analysis (SIEM, DB, log platform).

Methods

• initialize?(): Promise<void>: Optional setup (e.g., connect to logging platform).
• log(record: AuditRecord): Promise<void>:
  • Required for Auditing. Called async at end of pipeline.
  • Receives the complete, potentially sanitized AuditRecord.
  • Send the record to your auditing system (Splunk, Elasticsearch, DB).
  • Important: Must handle own errors gracefully and not throw.
• shutdown?(): Promise<void>: Optional cleanup (e.g., flush buffers).

Implementation Notes

• Handle serialization and network issues. Consider batching/async sending.

Logger

• File: src/interfaces/logger.ts
• Purpose: Standard interface for structured logging.

Methods

• initialize?(): Promise<void>: Optional setup.
• debug(message: string, context?: LogContext): void
• info(message: string, context?: LogContext): void
• warn(message: string, context?: LogContext): void
• error(message: string, error?: Error | unknown, context?: LogContext): void
• child?(bindings: LogContext): Logger: Optional but Recommended. Creates new logger with bound context (used for request-scoping).
• shutdown?(): Promise<void>: Optional cleanup (e.g., flush buffers).

Implementation Notes

• Adapt your preferred Node.js logger (Pino, Winston) to this interface. Implement child for best context propagation.

TraceContextProvider

• File: src/interfaces/tracing.ts
• Purpose: Extracts distributed tracing info (Trace IDs, Span IDs) from request context.
• Type: Function: (transportCtx, mcpMessage) => TraceContext | undefined

Implementation Notes

• Default (defaultTraceContextProvider) handles W3C Trace Context headers.
• Provide custom function for other standards (e.g., B3).
• Returned TraceContext added to OperationContext, AuditRecord, etc.