@openape/openclaw-plugin-grants 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,342 @@
+import { ScopeRiskLevel, GrantType, OpenApeCliAuthorizationDetail, OpenApeExecutionContext } from '@openape/core';
+import * as jose from 'jose';
+
+interface PluginConfig {
+    mode: 'local' | 'idp';
+    audience: string;
+    defaultApproval: GrantType;
+    adapterPaths?: string[];
+    agentEmail?: string;
+    agentKeyPath?: string;
+    idpUrl?: string;
+    apes?: {
+        enabled: boolean;
+        binaryPath?: string;
+    };
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (input: ToolInput) => Promise<ToolResult>;
+}
+interface ToolInput {
+    command: string;
+    reason?: string;
+    privileged?: boolean;
+}
+interface ToolResult {
+    success: boolean;
+    output?: string;
+    error?: string;
+}
+interface HookHandler {
+    (context: HookContext): Promise<HookResult>;
+}
+interface HookContext {
+    toolName: string;
+    toolInput: Record<string, unknown>;
+}
+interface HookResult {
+    allow: boolean;
+    message?: string;
+}
+interface HttpRouteDefinition {
+    path: string;
+    method: 'GET' | 'POST';
+    handler: (req: HttpRequest) => Promise<HttpResponse>;
+}
+interface HttpRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    body?: unknown;
+}
+interface HttpResponse {
+    status: number;
+    headers?: Record<string, string>;
+    body: unknown;
+}
+interface CliCommandDefinition {
+    name: string;
+    description: string;
+    subcommands?: CliSubcommand[];
+    handler: (args: string[]) => Promise<void>;
+}
+interface CliSubcommand {
+    name: string;
+    description: string;
+    handler: (args: string[]) => Promise<void>;
+}
+interface ChannelMessage {
+    text: string;
+    actions?: ChannelAction[];
+}
+interface ChannelAction {
+    label: string;
+    value: string;
+}
+interface PluginApi {
+    registerTool(tool: ToolDefinition): void;
+    on(event: 'before_tool_call', handler: HookHandler, options?: {
+        priority?: number;
+    }): void;
+    registerHttpRoute(route: HttpRouteDefinition): void;
+    registerCli(command: CliCommandDefinition): void;
+    sendChannelMessage(message: ChannelMessage): Promise<string | undefined>;
+    onChannelCommand(command: string, handler: (args: string[], responderId?: string) => Promise<void>): void;
+    runtime: {
+        system: {
+            runCommandWithTimeout(command: string, args: string[], options?: {
+                timeout?: number;
+                cwd?: string;
+                env?: Record<string, string>;
+            }): Promise<{
+                stdout: string;
+                stderr: string;
+                exitCode: number;
+            }>;
+        };
+        config: {
+            getStateDir(): string;
+            getWorkspaceDir(): string;
+        };
+    };
+    log: {
+        info(message: string, ...args: unknown[]): void;
+        warn(message: string, ...args: unknown[]): void;
+        error(message: string, ...args: unknown[]): void;
+        debug(message: string, ...args: unknown[]): void;
+    };
+}
+type GrantApproval = 'once' | 'timed' | 'always';
+interface GrantRecord {
+    id: string;
+    permission: string;
+    approval: GrantApproval;
+    status: 'pending' | 'approved' | 'denied' | 'used' | 'expired' | 'revoked';
+    command: string;
+    reason?: string;
+    risk: ScopeRiskLevel;
+    display: string;
+    jwt?: string;
+    createdAt: string;
+    decidedAt?: string;
+    expiresAt?: string;
+    usedAt?: string;
+}
+interface AuditEntry {
+    ts: string;
+    event: 'grant_requested' | 'grant_approved' | 'grant_denied' | 'grant_used' | 'grant_revoked' | 'grant_expired' | 'exec_success' | 'exec_failed' | 'exec_blocked';
+    grantId?: string;
+    permission?: string;
+    command?: string;
+    detail?: string;
+}
+
+interface AdapterDefinition {
+    schema: string;
+    cli: {
+        id: string;
+        executable: string;
+        audience?: string;
+        version?: string;
+    };
+    operations: AdapterOperation[];
+}
+interface AdapterOperation {
+    id: string;
+    command: string[];
+    positionals?: string[];
+    required_options?: string[];
+    display: string;
+    action: string;
+    risk: ScopeRiskLevel;
+    resource_chain: string[];
+    exact_command?: boolean;
+}
+interface LoadedAdapter {
+    adapter: AdapterDefinition;
+    source: string;
+    digest: string;
+}
+interface ResolvedCommand {
+    adapter: AdapterDefinition;
+    source: string;
+    digest: string;
+    executable: string;
+    commandArgv: string[];
+    bindings: Record<string, string>;
+    detail: OpenApeCliAuthorizationDetail;
+    executionContext: OpenApeExecutionContext;
+    permission: string;
+}
+interface CommandResolutionResult {
+    resolved: ResolvedCommand | null;
+    fallback: FallbackCommand | null;
+}
+interface FallbackCommand {
+    command: string;
+    argv: string[];
+    hash: string;
+    permission: string;
+    display: string;
+    risk: ScopeRiskLevel;
+}
+
+declare function parseAdapterToml(content: string): AdapterDefinition;
+
+declare function resolveCommand(loaded: LoadedAdapter, fullArgv: string[]): Promise<ResolvedCommand>;
+declare function createFallbackCommand(commandString: string): Promise<FallbackCommand>;
+declare function parseCommandString(command: string): string[];
+declare function resolveCommandFromAdapters(adapters: LoadedAdapter[], commandString: string): Promise<CommandResolutionResult>;
+
+interface AdapterSearchPaths {
+    explicit?: string[];
+    workspaceDir?: string;
+}
+declare function loadAdapterFromFile(filePath: string): LoadedAdapter;
+declare function loadAdapter(cliId: string, options?: AdapterSearchPaths): LoadedAdapter;
+declare function discoverAdapters(options?: AdapterSearchPaths): LoadedAdapter[];
+
+interface CreateGrantInput {
+    permission: string;
+    command: string;
+    reason?: string;
+    risk: ScopeRiskLevel;
+    display: string;
+}
+declare class GrantStore {
+    private grants;
+    private filePath;
+    constructor(stateDir?: string);
+    createGrant(input: CreateGrantInput): GrantRecord;
+    approveGrant(id: string, approval: GrantApproval, expiresAt?: string): GrantRecord | null;
+    denyGrant(id: string): GrantRecord | null;
+    consumeGrant(id: string): boolean;
+    revokeGrant(id: string): boolean;
+    getGrant(id: string): GrantRecord | undefined;
+    listGrants(filter?: {
+        status?: GrantRecord['status'];
+    }): GrantRecord[];
+    getActiveGrantCount(): number;
+    private load;
+    private save;
+}
+
+declare class GrantCache {
+    private entries;
+    put(grant: GrantRecord, detail: OpenApeCliAuthorizationDetail): void;
+    lookup(permission: string, detail: OpenApeCliAuthorizationDetail): GrantRecord | null;
+    remove(permission: string): boolean;
+    clear(): void;
+    size(): number;
+    private isExpired;
+}
+
+declare class AuditLog {
+    private filePath;
+    constructor(stateDir?: string);
+    write(entry: Omit<AuditEntry, 'ts'>): void;
+}
+
+declare class LocalJwtSigner {
+    private privateKey;
+    private publicKey;
+    private kid;
+    private stateDir;
+    constructor(stateDir: string);
+    init(): Promise<void>;
+    signGrant(options: {
+        grant: GrantRecord;
+        audience: string;
+        detail: OpenApeCliAuthorizationDetail;
+        executionContext: OpenApeExecutionContext;
+    }): Promise<string>;
+    getJwks(): Promise<jose.JSONWebKeySet>;
+    getIssuer(): string;
+    private getExpiration;
+}
+
+declare class ChannelApproval {
+    private api;
+    private store;
+    private timeoutMs;
+    private pending;
+    constructor(api: PluginApi, store: GrantStore, timeoutMs?: number);
+    requestApproval(grant: GrantRecord): Promise<{
+        approved: boolean;
+        approval?: 'once' | 'timed' | 'always';
+    }>;
+    private registerCommands;
+}
+
+interface ExecuteOptions {
+    command: string;
+    args: string[];
+    jwt?: string;
+    privileged?: boolean;
+    apesBinaryPath?: string;
+    timeout?: number;
+}
+declare function executeCommand(api: PluginApi, options: ExecuteOptions): Promise<ToolResult>;
+
+declare function detectApes(binaryPath?: string): {
+    available: boolean;
+    path: string;
+    version?: string;
+};
+declare function buildApesArgs(jwt: string, command: string, args: string[]): string[];
+
+interface AgentAuthState {
+    idpUrl: string;
+    token: string;
+    email: string;
+    expiresAt: number;
+}
+declare function authenticateAgent(options: {
+    idpUrl: string;
+    email: string;
+    keyPath: string;
+}): Promise<AgentAuthState>;
+declare function isTokenExpired(state: AgentAuthState): boolean;
+
+interface GrantExecContext {
+    config: PluginConfig;
+    api: PluginApi;
+    adapters: LoadedAdapter[];
+    store: GrantStore;
+    cache: GrantCache;
+    audit: AuditLog;
+    localJwt: LocalJwtSigner | null;
+    channelApproval: ChannelApproval | null;
+    idpAuthState: AgentAuthState | null;
+}
+declare function handleGrantExec(ctx: GrantExecContext, input: ToolInput): Promise<ToolResult>;
+
+declare function discoverIdpUrl(email: string, pinnedUrl?: string): Promise<string>;
+declare function discoverEndpoints(idpUrl: string): Promise<Record<string, unknown>>;
+declare function getGrantsEndpoint(idpUrl: string): Promise<string>;
+declare function clearDiscoveryCache(): void;
+
+interface IdpGrantContext {
+    config: PluginConfig;
+    api: PluginApi;
+    authState: AgentAuthState;
+    store: GrantStore;
+    cache: GrantCache;
+    audit: AuditLog;
+}
+declare function handleIdpGrantExec(ctx: IdpGrantContext, options: {
+    resolved: ResolvedCommand | null;
+    fallback: FallbackCommand | null;
+    command: string;
+    reason?: string;
+    privileged?: boolean;
+}): Promise<ToolResult>;
+
+declare function register(api: PluginApi, userConfig?: Partial<PluginConfig>): void;
+
+export { type AdapterDefinition, type AdapterOperation, type AdapterSearchPaths, type AgentAuthState, AuditLog, ChannelApproval, type CommandResolutionResult, type FallbackCommand, GrantCache, GrantStore, type LoadedAdapter, LocalJwtSigner, type PluginApi, type PluginConfig, type ResolvedCommand, authenticateAgent, buildApesArgs, clearDiscoveryCache, createFallbackCommand, detectApes, discoverAdapters, discoverEndpoints, discoverIdpUrl, executeCommand, getGrantsEndpoint, handleGrantExec, handleIdpGrantExec, isTokenExpired, loadAdapter, loadAdapterFromFile, parseAdapterToml, parseCommandString, register, resolveCommand, resolveCommandFromAdapters };