@ixo/oracle-runtime 0.0.1

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

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview UCAN service for Oracle
+ *
+ * Handles:
+ * 1. UCAN validation for MCP tool invocations (client → oracle)
+ * 2. UCAN invocation creation for downstream services (oracle → sandbox, etc.)
+ * 3. Ed25519 signing key management (stored in memory at startup)
+ * 4. Service DID resolution via did:web (/.well-known/did.json)
+ * 5. User delegation caching (keyed by user DID)
+ */
+import { type Cache } from '@nestjs/cache-manager';
+import { type OnModuleDestroy } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+export interface MCPValidationResult {
+    valid: boolean;
+    error?: string;
+    invokerDid?: string;
+}
+export declare class UcanService implements OnModuleDestroy {
+    private readonly configService;
+    private readonly cacheManager;
+    private readonly logger;
+    private readonly config;
+    private readonly invocationStore;
+    private readonly didResolver;
+    private signingMnemonic;
+    private oracleDid;
+    private readonly serviceDidCache;
+    constructor(configService: ConfigService, cacheManager: Cache);
+    onModuleDestroy(): void;
+    private loadConfig;
+    private createDIDResolver;
+    /**
+     * Store the Ed25519 signing mnemonic in memory (called once at startup).
+     * Uses the same mnemonic from setupClaimSigningMnemonics.
+     */
+    setSigningMnemonic(mnemonic: string, did: string): void;
+    hasSigningKey(): boolean;
+    /**
+     * Read the in-memory signing mnemonic. Other runtime consumers (e.g. the
+     * credits plugin's claim-signing path) call this to avoid re-fetching and
+     * re-decrypting it from the oracle's Matrix account room on every claim.
+     * Returns `null` when boot hasn't populated it yet.
+     */
+    getSigningMnemonic(): string | null;
+    /**
+     * Cache a raw UCAN delegation string for a user.
+     * Called by auth-header.middleware after successful validation.
+     */
+    cacheDelegation(userDid: string, rawDelegation: string, expirationUnix?: number): Promise<void>;
+    getCachedDelegation(userDid: string): Promise<string | null>;
+    /**
+     * Resolve a service URL to its did:web DID.
+     * Fetches /.well-known/did.json from the service's domain and caches the result.
+     */
+    resolveServiceDid(serviceUrl: string): Promise<string | null>;
+    /**
+     * Create a serialized UCAN invocation for calling a downstream service.
+     * The invocation embeds the user's delegation as proof, forming:
+     *   user (delegation.iss) → oracle (invocation.iss) → service (invocation.aud)
+     *
+     * @param serviceUrl - URL of the downstream service (used to resolve did:web)
+     * @param userDid - The user's DID (used to look up cached delegation)
+     * @param resource - The capability resource URI (e.g., 'ixo:sandbox')
+     * @returns Base64-encoded invocation CAR, or null if unavailable
+     */
+    createServiceInvocation(serviceUrl: string, userDid: string, resource?: string): Promise<string | null>;
+    /**
+     * Mint a UCAN invocation when the downstream service DID is already known
+     * (e.g. a plugin called `resolveServiceDid` separately and now wants to
+     * mint with the resolved DID directly). Same semantics as
+     * `createServiceInvocation` minus the URL → DID lookup.
+     *
+     * `opts.skipCache` — bypass the invocation cache. Required for downstream
+     * services that enforce single-use replay protection per invocation CID
+     * (e.g. composio-worker). Without this flag a cached CID would be reused
+     * across requests and rejected as a replay.
+     */
+    mintInvocationForServiceDid(userDid: string, serviceDid: string, resource?: string, opts?: {
+        skipCache?: boolean;
+    }): Promise<string | null>;
+    /**
+     * Mint a UCAN invocation from a directly-supplied delegation CAR (rather
+     * than the per-user cached one used by {@link createServiceInvocation}).
+     *
+     * Use this when the caller already holds the user's signed delegation in
+     * hand — typically because they read it from a flow's Y.Doc by CID — and
+     * wants to mint a freshly-targeted invocation against a specific service
+     * route. The delegation MUST already name this oracle as its audience; the
+     * call fails loudly if it doesn't, since a delegation pointing at someone
+     * else can't legitimately be re-used by us.
+     *
+     * Each protected service call should use a freshly minted invocation —
+     * services typically track invocation CIDs to enforce single-use replay
+     * protection. Re-call this method before every protected request.
+     *
+     * @param delegationCar Base64-encoded delegation CAR (the user → oracle
+     *   delegation signed in the editor)
+     * @param serviceUrl URL of the target service — used to resolve the did:web
+     *   audience by fetching `<serviceUrl>/.well-known/did.json`
+     * @param capability The exact capability the service requires for this
+     *   route, e.g. `{ can: 'service/action', with: 'ixo:service' }`. Defined
+     *   by the target service; must match what its requireAuth middleware
+     *   expects.
+     * @param options.maxTtlSeconds Max invocation lifetime; clamped to the
+     *   delegation's own expiration. Default 60s — invocations are typically
+     *   single-use so a long TTL is unnecessary and just widens the replay
+     *   window.
+     *
+     * @returns Base64-encoded invocation CAR, or `{ error }` describing why it
+     *   failed (so the caller can surface a useful message to the agent).
+     */
+    createInvocationFromDelegation(delegationCar: string, serviceUrl: string, capability: {
+        can: string;
+        with: string;
+    }, options?: {
+        maxTtlSeconds?: number;
+    }): Promise<{
+        invocation: string;
+    } | {
+        error: string;
+    }>;
+    requiresAuth(serverName: string, toolName?: string): boolean;
+    validateMCPInvocation(serverName: string, toolName: string, invocationData: Uint8Array | string): Promise<MCPValidationResult>;
+    getRequiredCapabilityURI(serverName: string, toolName: string): string;
+    getOracleDid(): string;
+    getRootIssuers(): string[];
+}
+//# sourceMappingURL=ucan.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ucan.service.d.ts","sourceRoot":"","sources":["../../../src/modules/ucan/ucan.service.ts"],"names":[],"mappings":"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"}