@ixo/oracle-runtime 0.0.1

package/dist/modules/subscription/subscription.middleware.d.ts

@@ -0,0 +1,37 @@
+import { type GetMySubscriptionsResponseDto } from '@ixo/common';
+import { Cache } from '@nestjs/cache-manager';
+import { type NestMiddleware } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { type NextFunction, type Request, type Response } from 'express';
+import { UcanService } from '../ucan/ucan.service.js';
+/**
+ * Optional credit/token-limiter sink. Subscription syncs the per-DID
+ * subscription payload + balance into Redis for the credits plugin to
+ * read on the LLM hot path. The sink is provided by the credits plugin
+ * when installed. When absent, the middleware still enforces the 402
+ * gate purely from the API response — no Redis dependency.
+ */
+export interface SubscriptionCreditSink {
+    setSubscriptionPayload(userDid: string, payload: GetMySubscriptionsResponseDto): Promise<void>;
+    overrideUserBalance(userDid: string, balance: number): Promise<string>;
+}
+export declare const SUBSCRIPTION_CREDIT_SINK: unique symbol;
+declare global {
+    namespace Express {
+        interface Request {
+            subscriptionData?: GetMySubscriptionsResponseDto;
+        }
+    }
+}
+export declare class SubscriptionMiddleware implements NestMiddleware {
+    private readonly configService;
+    private cacheManager;
+    private readonly ucanService;
+    private readonly creditSink?;
+    private readonly logger;
+    constructor(configService: ConfigService, cacheManager: Cache, ucanService: UcanService, creditSink?: SubscriptionCreditSink | undefined);
+    private checkCanContinue;
+    use(req: Request, res: Response, next: NextFunction): Promise<void>;
+    private syncCreditSink;
+}
+//# sourceMappingURL=subscription.middleware.d.ts.map

package/dist/modules/subscription/subscription.middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.middleware.d.ts","sourceRoot":"","sources":["../../../src/modules/subscription/subscription.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,EAAiB,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,sBAAsB,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxE;AAED,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAmB3E,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,gBAAgB,CAAC,EAAE,6BAA6B,CAAC;SAClD;KACF;CACF;AAID,qBACa,sBAAuB,YAAW,cAAc;IAIzD,OAAO,CAAC,QAAQ,CAAC,aAAa;IACP,OAAO,CAAC,YAAY;IAG3C,OAAO,CAAC,QAAQ,CAAC,WAAW;IAM5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAb9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2C;gBAG/C,aAAa,EAAE,aAAa,EACd,YAAY,EAAE,KAAK,EAGjC,WAAW,EAAE,WAAW,EAMxB,UAAU,CAAC,EAAE,sBAAsB,YAAA;IAGtD,OAAO,CAAC,gBAAgB;IA4BlB,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;YAqI3D,cAAc;CAa7B"}

package/dist/modules/subscription/subscription.middleware.js

@@ -0,0 +1,141 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var SubscriptionMiddleware_1;
+import { getUserSubscription, getSubscriptionUrlByNetwork, } from '@ixo/common';
+import { Cache, CACHE_MANAGER } from '@nestjs/cache-manager';
+import { HttpException, HttpStatus, Inject, Injectable, Logger, Optional, } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { minutes } from '@nestjs/throttler';
+import { UcanService } from '../ucan/ucan.service.js';
+export const SUBSCRIPTION_CREDIT_SINK = Symbol('SUBSCRIPTION_CREDIT_SINK');
+const THREE_MINUTES = minutes(3);
+let SubscriptionMiddleware = SubscriptionMiddleware_1 = class SubscriptionMiddleware {
+    configService;
+    cacheManager;
+    ucanService;
+    creditSink;
+    logger = new Logger(SubscriptionMiddleware_1.name);
+    constructor(configService, cacheManager, 
+    // UCAN is core runtime (global `UcanModule` exports `UcanService`).
+    // Direct DI — no port indirection.
+    ucanService, creditSink) {
+        this.configService = configService;
+        this.cacheManager = cacheManager;
+        this.ucanService = ucanService;
+        this.creditSink = creditSink;
+    }
+    checkCanContinue(subscription) {
+        const disableCredits = this.configService.get('DISABLE_CREDITS', false);
+        if (disableCredits) {
+            this.logger.debug('Subscription check skipped (DISABLE_CREDITS=true)');
+            return true;
+        }
+        if (subscription.status !== 'active' && subscription.status !== 'trial') {
+            throw new HttpException('User has inactive subscription, please subscribe to continue', HttpStatus.PAYMENT_REQUIRED);
+        }
+        if (subscription.totalCredits <= 10) {
+            throw new HttpException('User has less than 10 credits, please top up to continue', HttpStatus.PAYMENT_REQUIRED);
+        }
+        return true;
+    }
+    async use(req, res, next) {
+        this.logger.debug(`SubscriptionMiddleware processing request for: ${req.originalUrl}`);
+        if (!this.creditSink) {
+            this.logger.warn('No SubscriptionCreditSink configured; credits plugin is not active. Enforcing 402 policy directly based on subscription API only.');
+        }
+        try {
+            // Check if authData is available (set upstream by AuthHeaderMiddleware)
+            const authData = req.authData;
+            if (!authData) {
+                this.logger.warn('No auth data available, skipping subscription check');
+                req.subscriptionData = undefined;
+                return next();
+            }
+            const { did, ucanDelegation } = authData;
+            if (!ucanDelegation) {
+                throw new HttpException('Missing UCAN delegation; cannot verify subscription', HttpStatus.UNAUTHORIZED);
+            }
+            const cachedSubscription = await this.cacheManager.get(`subscription_${did}`);
+            if (cachedSubscription) {
+                this.logger.debug(`Subscription found in cache for user: ${did}`);
+                req.subscriptionData = cachedSubscription;
+                this.checkCanContinue(cachedSubscription);
+                // Credit sink was already synced on the original cache miss; the
+                // subscription cache TTL is the source of truth for "this user's
+                // Redis state is fresh enough." Re-syncing on every cached request
+                // adds two Redis writes for no gain.
+                next();
+                return;
+            }
+            const network = this.configService.get('NETWORK') ??
+                'devnet';
+            const subscriptionUrl = this.configService.get('SUBSCRIPTION_URL') ??
+                getSubscriptionUrlByNetwork(network);
+            if (!this.ucanService.hasSigningKey()) {
+                throw new HttpException('UCAN signing key not configured; subscription check unavailable', HttpStatus.UNAUTHORIZED);
+            }
+            const invocation = await this.ucanService.createServiceInvocation(subscriptionUrl, did, 'ixo:subscriptions');
+            if (!invocation) {
+                throw new HttpException('Failed to mint UCAN invocation for subscription check', HttpStatus.UNAUTHORIZED);
+            }
+            this.logger.debug(`[UCAN] Using UCAN invocation for subscription check: ${did}`);
+            const subscription = await getUserSubscription({
+                bearerToken: invocation,
+                network,
+                subscriptionUrl,
+                authType: 'ucan',
+            });
+            if (!subscription) {
+                this.logger.warn(`No subscription found for user: ${did}. This could mean: 1) API returned non-OK status, 2) API returned null/undefined data, 3) API call failed with error`);
+                req.subscriptionData = undefined;
+                throw new HttpException('No subscription found, please subscribe to continue', HttpStatus.PAYMENT_REQUIRED);
+            }
+            req.subscriptionData = subscription;
+            this.logger.debug(`Subscription validated for user: ${did}, status: ${subscription.status}`);
+            this.checkCanContinue(subscription);
+            await this.syncCreditSink(did, subscription);
+            await this.cacheManager.set(`subscription_${did}`, subscription, THREE_MINUTES);
+            next();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const errorStack = error instanceof Error ? error.stack : undefined;
+            // Re-throw HttpExceptions (the 402 gates) unchanged so the original
+            // status + message reach the client.
+            if (error instanceof HttpException) {
+                this.logger.error(`Subscription validation failed: ${message}`, errorStack);
+                throw error;
+            }
+            this.logger.error(`Subscription check failed: ${message}`, errorStack);
+            req.subscriptionData = undefined;
+            throw new HttpException('Subscription validation failed', HttpStatus.PAYMENT_REQUIRED);
+        }
+    }
+    async syncCreditSink(userDid, subscription) {
+        if (!this.creditSink) {
+            return;
+        }
+        await this.creditSink.setSubscriptionPayload(userDid, subscription);
+        await this.creditSink.overrideUserBalance(userDid, subscription.totalCredits);
+    }
+};
+SubscriptionMiddleware = SubscriptionMiddleware_1 = __decorate([
+    Injectable(),
+    __param(1, Inject(CACHE_MANAGER)),
+    __param(3, Optional()),
+    __param(3, Inject(SUBSCRIPTION_CREDIT_SINK)),
+    __metadata("design:paramtypes", [ConfigService,
+        Cache,
+        UcanService, Object])
+], SubscriptionMiddleware);
+export { SubscriptionMiddleware };

package/dist/modules/subscription/subscription.module.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wraps `SubscriptionMiddleware` so `RuntimeAppModule` can pull it in via
+ * `MiddlewareConsumer.apply(...)`. The middleware itself is the unit of
+ * work — this module just owns the provider registration.
+ *
+ * `UcanService` flows in via Nest's global UCAN module (always present).
+ * `SUBSCRIPTION_CREDIT_SINK` is plugin-supplied (credits plugin's
+ * `getNestModules()`); the middleware tolerates it being absent.
+ */
+export declare class SubscriptionModule {
+}
+//# sourceMappingURL=subscription.module.d.ts.map

package/dist/modules/subscription/subscription.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.module.d.ts","sourceRoot":"","sources":["../../../src/modules/subscription/subscription.module.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,qBAIa,kBAAkB;CAAG"}

package/dist/modules/subscription/subscription.module.js

@@ -0,0 +1,26 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from '@nestjs/common';
+import { SubscriptionMiddleware } from './subscription.middleware.js';
+/**
+ * Wraps `SubscriptionMiddleware` so `RuntimeAppModule` can pull it in via
+ * `MiddlewareConsumer.apply(...)`. The middleware itself is the unit of
+ * work — this module just owns the provider registration.
+ *
+ * `UcanService` flows in via Nest's global UCAN module (always present).
+ * `SUBSCRIPTION_CREDIT_SINK` is plugin-supplied (credits plugin's
+ * `getNestModules()`); the middleware tolerates it being absent.
+ */
+let SubscriptionModule = class SubscriptionModule {
+};
+SubscriptionModule = __decorate([
+    Module({
+        providers: [SubscriptionMiddleware],
+        exports: [SubscriptionMiddleware],
+    })
+], SubscriptionModule);
+export { SubscriptionModule };

package/dist/modules/throttler/throttler.module.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-exports `@nestjs/throttler` configured with the runtime's default
+ * rate-limit policy (10 requests per 60 seconds, applied globally via
+ * the `ThrottlerGuard` registered by `RuntimeAppModule`).
+ *
+ * Forks that need a different policy can swap this module in their
+ * own AppModule, but most should leave it alone.
+ */
+export declare class ThrottlerModule {
+}
+//# sourceMappingURL=throttler.module.d.ts.map

package/dist/modules/throttler/throttler.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttler.module.d.ts","sourceRoot":"","sources":["../../../src/modules/throttler/throttler.module.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,qBAWa,eAAe;CAAG"}

package/dist/modules/throttler/throttler.module.js

@@ -0,0 +1,32 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from '@nestjs/common';
+import { ThrottlerModule as NestThrottlerModule } from '@nestjs/throttler';
+/**
+ * Re-exports `@nestjs/throttler` configured with the runtime's default
+ * rate-limit policy (10 requests per 60 seconds, applied globally via
+ * the `ThrottlerGuard` registered by `RuntimeAppModule`).
+ *
+ * Forks that need a different policy can swap this module in their
+ * own AppModule, but most should leave it alone.
+ */
+let ThrottlerModule = class ThrottlerModule {
+};
+ThrottlerModule = __decorate([
+    Module({
+        imports: [
+            NestThrottlerModule.forRoot([
+                {
+                    ttl: 60000,
+                    limit: 10,
+                },
+            ]),
+        ],
+        exports: [NestThrottlerModule],
+    })
+], ThrottlerModule);
+export { ThrottlerModule };

package/dist/modules/ucan/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview UCAN module exports for the Oracle runtime
+ */
+export { UcanModule } from './ucan.module.js';
+export { UcanService, type MCPValidationResult } from './ucan.service.js';
+export { createMCPUCANConfig, requiresUCANAuth, buildRequiredCapability, loadUCANConfigFromEnv, } from './ucan.config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/ucan/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/ucan/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/modules/ucan/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview UCAN module exports for the Oracle runtime
+ */
+export { UcanModule } from './ucan.module.js';
+export { UcanService } from './ucan.service.js';
+export { createMCPUCANConfig, requiresUCANAuth, buildRequiredCapability, loadUCANConfigFromEnv, } from './ucan.config.js';

package/dist/modules/ucan/ucan.config.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview UCAN configuration for Oracle MCP endpoints
+ *
+ * This module defines the UCAN authorization requirements for MCP tools.
+ * Each MCP server/tool can be configured to require UCAN authorization.
+ */
+/**
+ * MCP capability actions
+ */
+type MCPAction = 'mcp/call' | 'mcp/*';
+/**
+ * Configuration for MCP tool UCAN requirements
+ */
+interface MCPUCANRequirement {
+    /** The action required (e.g., 'mcp/call') */
+    can: MCPAction;
+    /** Pattern for the resource URI */
+    withPattern: string;
+    /** Whether this MCP server/tool requires UCAN authorization */
+    requiresAuth: boolean;
+}
+/**
+ * Map of MCP server names to their UCAN requirements
+ */
+export interface MCPUCANConfig {
+    /** This oracle's DID (will be the audience for invocations) */
+    oracleDid: string;
+    /** Root DIDs allowed to self-issue capabilities */
+    rootIssuers: string[];
+    /** Per-MCP-server authorization requirements */
+    requirements: Record<string, MCPUCANRequirement>;
+}
+/**
+ * Create the UCAN configuration for this oracle
+ *
+ * @param oracleDid - The oracle's DID (audience for invocations)
+ * @param rootIssuers - DIDs allowed to be root issuers
+ * @param protectedServers - Map of MCP server names to whether they require UCAN
+ * @returns The complete UCAN configuration
+ *
+ * @example
+ * ```typescript
+ * const config = createMCPUCANConfig(
+ *   'did:ixo:oracle123',
+ *   ['did:ixo:admin'],
+ *   {
+ *     postgres: true,    // Requires UCAN
+ *     filesystem: false, // No UCAN required
+ *   }
+ * );
+ * ```
+ */
+export declare function createMCPUCANConfig(oracleDid: string, rootIssuers: string[], protectedServers?: Record<string, boolean>): MCPUCANConfig;
+/**
+ * Check if an MCP tool requires UCAN authorization
+ *
+ * @param config - The UCAN configuration
+ * @param serverName - The MCP server name
+ * @param toolName - The tool name (optional, for tool-level checks)
+ * @returns Whether the tool requires UCAN authorization
+ */
+export declare function requiresUCANAuth(config: MCPUCANConfig, serverName: string, _toolName?: string): boolean;
+/**
+ * Build the required capability for an MCP tool
+ *
+ * @param config - The UCAN configuration
+ * @param serverName - The MCP server name
+ * @param toolName - The tool name
+ * @returns The required capability object
+ */
+export declare function buildRequiredCapability(config: MCPUCANConfig, serverName: string, toolName: string): {
+    can: string;
+    with: string;
+};
+/**
+ * Environment-based configuration loader
+ *
+ * Reads UCAN configuration from environment variables:
+ * - ORACLE_ENTITY_DID: The oracle's DID
+ * - UCAN_ROOT_ISSUERS: Comma-separated list of root issuer DIDs
+ * - UCAN_PROTECTED_MCP_SERVERS: Comma-separated list of MCP server names that require UCAN
+ *
+ * @returns The UCAN configuration from environment
+ */
+export declare function loadUCANConfigFromEnv(): MCPUCANConfig;
+export {};
+//# sourceMappingURL=ucan.config.d.ts.map

package/dist/modules/ucan/ucan.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ucan.config.d.ts","sourceRoot":"","sources":["../../../src/modules/ucan/ucan.config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,KAAK,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;AAEtC;;GAEG;AACH,UAAU,kBAAkB;IAC1B,6CAA6C;IAC7C,GAAG,EAAE,SAAS,CAAC;IACf,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAClD;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EAAE,EACrB,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAC7C,aAAa,CAef;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAQT;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAa/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,IAAI,aAAa,CAmBrD"}

package/dist/modules/ucan/ucan.config.js

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview UCAN configuration for Oracle MCP endpoints
+ *
+ * This module defines the UCAN authorization requirements for MCP tools.
+ * Each MCP server/tool can be configured to require UCAN authorization.
+ */
+/**
+ * Default UCAN requirement for MCP tools
+ * Requires the 'mcp/call' action on the specific tool resource
+ */
+const defaultMCPRequirement = {
+    can: 'mcp/call',
+    // Pattern: ixo:oracle:{oracleDid}:mcp/{serverName}/{toolName}
+    withPattern: 'ixo:oracle:{oracleDid}:mcp/{serverName}/{toolName}',
+};
+/**
+ * Create the UCAN configuration for this oracle
+ *
+ * @param oracleDid - The oracle's DID (audience for invocations)
+ * @param rootIssuers - DIDs allowed to be root issuers
+ * @param protectedServers - Map of MCP server names to whether they require UCAN
+ * @returns The complete UCAN configuration
+ *
+ * @example
+ * ```typescript
+ * const config = createMCPUCANConfig(
+ *   'did:ixo:oracle123',
+ *   ['did:ixo:admin'],
+ *   {
+ *     postgres: true,    // Requires UCAN
+ *     filesystem: false, // No UCAN required
+ *   }
+ * );
+ * ```
+ */
+export function createMCPUCANConfig(oracleDid, rootIssuers, protectedServers = {}) {
+    const requirements = {};
+    for (const [serverName, requiresAuth] of Object.entries(protectedServers)) {
+        requirements[serverName] = {
+            ...defaultMCPRequirement,
+            requiresAuth,
+        };
+    }
+    return {
+        oracleDid,
+        rootIssuers,
+        requirements,
+    };
+}
+/**
+ * Check if an MCP tool requires UCAN authorization
+ *
+ * @param config - The UCAN configuration
+ * @param serverName - The MCP server name
+ * @param toolName - The tool name (optional, for tool-level checks)
+ * @returns Whether the tool requires UCAN authorization
+ */
+export function requiresUCANAuth(config, serverName, _toolName) {
+    const requirement = config.requirements[serverName];
+    if (!requirement) {
+        // Default: no UCAN required for unconfigured servers
+        return false;
+    }
+    return requirement.requiresAuth;
+}
+/**
+ * Build the required capability for an MCP tool
+ *
+ * @param config - The UCAN configuration
+ * @param serverName - The MCP server name
+ * @param toolName - The tool name
+ * @returns The required capability object
+ */
+export function buildRequiredCapability(config, serverName, toolName) {
+    const requirement = config.requirements[serverName] ?? defaultMCPRequirement;
+    // Replace placeholders in the pattern
+    const withUri = requirement.withPattern
+        .replace('{oracleDid}', config.oracleDid)
+        .replace('{serverName}', serverName)
+        .replace('{toolName}', toolName);
+    return {
+        can: requirement.can,
+        with: withUri,
+    };
+}
+/**
+ * Environment-based configuration loader
+ *
+ * Reads UCAN configuration from environment variables:
+ * - ORACLE_ENTITY_DID: The oracle's DID
+ * - UCAN_ROOT_ISSUERS: Comma-separated list of root issuer DIDs
+ * - UCAN_PROTECTED_MCP_SERVERS: Comma-separated list of MCP server names that require UCAN
+ *
+ * @returns The UCAN configuration from environment
+ */
+export function loadUCANConfigFromEnv() {
+    const oracleDid = process.env.ORACLE_ENTITY_DID ?? '';
+    const rootIssuers = (process.env.UCAN_ROOT_ISSUERS ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const protectedServerNames = (process.env.UCAN_PROTECTED_MCP_SERVERS ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const protectedServers = {};
+    for (const serverName of protectedServerNames) {
+        protectedServers[serverName] = true;
+    }
+    return createMCPUCANConfig(oracleDid, rootIssuers, protectedServers);
+}
+// TODO: Add support for per-tool authorization requirements
+// TODO: Add support for capability caveats (e.g., rate limiting)
+// TODO: Add support for time-based restrictions

package/dist/modules/ucan/ucan.module.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview UCAN module for Oracle
+ *
+ * This module provides UCAN authorization services for the Oracle application.
+ */
+/**
+ * UCAN Module
+ *
+ * Provides UCAN authorization services for MCP tool invocations.
+ * Marked as @Global so the UcanService can be injected anywhere.
+ *
+ * @example
+ * ```typescript
+ * // In your app.module.ts
+ * @Module({
+ *   imports: [UcanModule],
+ * })
+ * export class AppModule {}
+ *
+ * // Then inject UcanService where needed
+ * @Injectable()
+ * class MyService {
+ *   constructor(private readonly ucanService: UcanService) {}
+ * }
+ * ```
+ */
+export declare class UcanModule {
+}
+//# sourceMappingURL=ucan.module.d.ts.map

package/dist/modules/ucan/ucan.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ucan.module.d.ts","sourceRoot":"","sources":["../../../src/modules/ucan/ucan.module.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAMa,UAAU;CAAG"}

package/dist/modules/ucan/ucan.module.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview UCAN module for Oracle
+ *
+ * This module provides UCAN authorization services for the Oracle application.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Global, Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { UcanService } from './ucan.service.js';
+/**
+ * UCAN Module
+ *
+ * Provides UCAN authorization services for MCP tool invocations.
+ * Marked as @Global so the UcanService can be injected anywhere.
+ *
+ * @example
+ * ```typescript
+ * // In your app.module.ts
+ * @Module({
+ *   imports: [UcanModule],
+ * })
+ * export class AppModule {}
+ *
+ * // Then inject UcanService where needed
+ * @Injectable()
+ * class MyService {
+ *   constructor(private readonly ucanService: UcanService) {}
+ * }
+ * ```
+ */
+let UcanModule = class UcanModule {
+};
+UcanModule = __decorate([
+    Global(),
+    Module({
+        imports: [ConfigModule],
+        providers: [UcanService],
+        exports: [UcanService],
+    })
+], UcanModule);
+export { UcanModule };