@blacksandscyber/mcp-server-bursar 0.5.0

package/build/shield/client.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Shield API Client — Broker mode only.
+ *
+ * Every request flows through the Blacksands Broker:
+ *   Step 1: POST {authorizer}/api/agent/auth with { password, serviceId }
+ *           — the Authorizer validates the mTLS client cert (presented by our
+ *           httpsAgent), authenticates the password, and resolves the serviceId
+ *           to a Receiver URL — all in one round trip. Returns a sessionToken
+ *           plus { service: { serviceUrl } }.
+ *   Step 2: All subsequent Shield API calls go to service.serviceUrl (the
+ *           Receiver), which authenticates us and proxies to Shield API.
+ *
+ * The mTLS client certificate and auth password are issued by a human
+ * administrator through Overwatch or SysAdmin (or by the Phase-2 setup-token
+ * bootstrap flow, which is just a thin wrapper around the same issuance).
+ */
+import * as https from "https";
+import type { Organization, App, Certificate, Endpoint, Policy, PolicyRule, DnsRule, Manifest, Operation, VerifyResult, ComplianceReport, ComplianceFramework, Session, ListResponse } from "./types";
+export interface ShieldClientOptions {
+    timeout?: number;
+    maxRetries?: number;
+    /** PEM-encoded client certificate for mTLS authentication */
+    clientCert: string;
+    /** PEM-encoded client private key for mTLS authentication */
+    clientKey: string;
+    /** Optional PEM-encoded CA certificate to pin the Authorizer/Receiver server cert */
+    caCert?: string | null;
+    /**
+     * Broker connection settings. Required for client-side (stdio) mode where
+     * the MCP server connects to Shield API via the full Authorizer handshake.
+     * Mutually exclusive with `directUrl`.
+     */
+    broker?: {
+        authorizerUrl: string;
+        serviceId: string;
+        authPassword: string;
+    };
+    /**
+     * Direct Shield API base URL. Used when the MCP server is deployed as an
+     * internal HTTP service behind a Receiver and authenticates to Shield API
+     * using a service-level mTLS certificate (no broker handshake).
+     * Mutually exclusive with `broker`.
+     */
+    directUrl?: string;
+}
+export declare class BrokerConnector {
+    private authorizerUrl;
+    private serviceId;
+    private authPassword;
+    private httpsAgent;
+    private sessionToken;
+    private receiverUrl;
+    private connectedAt;
+    private sessionTtlMs;
+    private heartbeatTimer;
+    private readonly requestedTtlSec?;
+    constructor(authorizerUrl: string, serviceId: string, authPassword: string, httpsAgent: https.Agent, requestedTtlSec?: number | undefined);
+    get isConnected(): boolean;
+    get url(): string;
+    connect(): Promise<string>;
+    ensureConnected(): Promise<void>;
+    reconnect(): Promise<string>;
+    /**
+     * Tear down state and stop the heartbeat. Tests/teardown call this; runtime
+     * normally stays connected for the process lifetime.
+     */
+    close(): void;
+    private startHeartbeat;
+    private stopHeartbeat;
+}
+export declare class ShieldClient {
+    private http;
+    private maxRetries;
+    private broker;
+    private httpsAgent;
+    private options;
+    private mode;
+    constructor(options: ShieldClientOptions);
+    /** Complete the Broker handshake. No-op in direct mode. */
+    connect(): Promise<void>;
+    get authMethod(): "broker" | "direct";
+    request<T = unknown>(method: string, path: string, data?: unknown): Promise<T>;
+    pollOperation(operationId: string, opts?: {
+        interval?: number;
+        timeout?: number;
+    }): Promise<Operation>;
+    listMcpCerts(): Promise<{
+        data: Array<{
+            id: string;
+            name: string;
+            cn: string;
+            fingerprint: string;
+            expires: string;
+        }>;
+    }>;
+    revokeMcpCert(clientName: string): Promise<void>;
+    /**
+     * Issue a full MCP client certificate bundle. Internal use only —
+     * consumed by bursar_install_agent_remotely's SSH and aws-ssm transports,
+     * which need the key material in-process to ship to the target.
+     *
+     * The returned `key_pem` is SENSITIVE: callers MUST treat it as tainted
+     * and MUST NOT persist it. See bursar_install_agent_remotely §FR-1.
+     */
+    issueMcpCert(clientName: string, orgId: string): Promise<{
+        cn: string;
+        cert_pem: string;
+        key_pem: string;
+        ca_pem: string | null;
+        auth_password: string;
+        fingerprint: string;
+        expires: string;
+        client_id: string;
+    }>;
+    /**
+     * Mint a short-lived single-use setup token bound to {clientName, orgId}.
+     * Consumed by bursar_install_agent_remotely's bootstrap-token transport —
+     * the token is handed to the target, which calls POST /mcp/setup-tokens/redeem
+     * to exchange it for a cert bundle. The private key is returned to the
+     * redeemer; the MCP host holding this call never sees it.
+     *
+     * `expiresIn` accepts a number of seconds or a shorthand like "1h"/"30m".
+     *
+     * `role` ('master' | 'consumer') stamps the role on the token row so the
+     * redeem flow propagates it to the issued McpClient.role, and the redeem
+     * response echoes it back so setup.js can write
+     * ~/.blacksands/mcp-certs/.role for boot-time tool filtering. Defaults
+     * to 'master' on the server side.
+     */
+    mintSetupToken(clientName: string, orgId: string, expiresIn?: string | number, role?: "master" | "consumer"): Promise<{
+        token: string;
+        token_id: string;
+        token_prefix: string;
+        client_name: string;
+        org_id: string;
+        role: "master" | "consumer";
+        expires_at: string;
+        ttl_seconds: number;
+        url: string;
+    }>;
+    /**
+     * Revoke a pending (unconsumed) setup token by ID. Internal rollback
+     * helper for bursar_install_agent_remotely — NOT exposed as a tool.
+     * A 404 from the server means the token was already consumed or
+     * expired; callers should treat that as success for rollback purposes.
+     */
+    revokeSetupToken(tokenId: string): Promise<void>;
+    /**
+     * Check whether the named MCP client has completed its first broker
+     * handshake since issuance. Polled by the install orchestrator with
+     * exponential backoff until waitForHandshake timeout.
+     */
+    getHandshakeStatus(clientName: string): Promise<{
+        success: boolean;
+        verified: boolean;
+        client_name?: string;
+        cn?: string;
+        fingerprint?: string;
+        expires?: string;
+        first_handshake_at?: string | null;
+        last_handshake_at?: string | null;
+        receiver_url?: string | null;
+        reason?: string | null;
+    }>;
+    /**
+     * Acquire the per-clientName advisory lock. Throws on 409 (conflict).
+     */
+    acquireInstallLock(clientName: string, opts?: {
+        ttlSeconds?: number;
+        auditId?: string;
+    }): Promise<{
+        owner_id: string;
+        expires_at: string;
+        ttl_seconds: number;
+    }>;
+    /** Release the advisory lock. Owner-match enforced server-side. */
+    releaseInstallLock(clientName: string): Promise<void>;
+    /** Append an audit row for a bursar_install_agent_remotely invocation. */
+    recordInstallAudit(row: {
+        auditId: string;
+        clientName: string;
+        transportType: string;
+        agentType?: string;
+        status: string;
+        phase?: string;
+        dryRun?: boolean;
+        target?: Record<string, unknown>;
+        errorMessage?: string;
+    }): Promise<{
+        id: string;
+        audit_id: string;
+    }>;
+    createOrg(name: string, plan?: string): Promise<Organization>;
+    getOrg(orgId: string): Promise<Organization>;
+    listOrgs(page?: number, pageSize?: number): Promise<ListResponse<Organization>>;
+    createApp(orgId: string, name: string, opts?: {
+        type?: "web" | "mobile" | "api" | "iot" | "service";
+        framework?: string;
+        runtime?: string;
+        environment?: "development" | "staging" | "production";
+        domain?: string;
+    }): Promise<App>;
+    getApp(appId: string): Promise<App>;
+    listApps(orgId: string): Promise<ListResponse<App>>;
+    submitManifest(manifest: unknown, orgId: string): Promise<Manifest>;
+    getManifest(manifestId: string): Promise<Manifest>;
+    provisionManifest(manifestId: string): Promise<{
+        operationId: string;
+    }>;
+    listCerts(appId: string): Promise<ListResponse<Certificate>>;
+    rotateCert(appId: string, certId: string): Promise<Certificate>;
+    revokeCert(appId: string, certId: string, reason?: string): Promise<void>;
+    listEndpoints(appId: string): Promise<ListResponse<Endpoint>>;
+    listPolicies(appId: string): Promise<ListResponse<Policy>>;
+    createPolicy(appId: string, name: string, type: string, rules: PolicyRule[]): Promise<Policy>;
+    updateDnsRules(appId: string, rules: Array<{
+        domain: string;
+        action: "allow" | "block";
+        reason?: string;
+    }>): Promise<DnsRule[]>;
+    triggerVerify(appId: string, scanType?: "full" | "quick" | "compliance" | "penetration"): Promise<{
+        operationId: string;
+    }>;
+    getLatestPosture(appId: string): Promise<VerifyResult>;
+    getComplianceReport(appId: string, framework: ComplianceFramework): Promise<ComplianceReport>;
+    getComplianceControls(framework: ComplianceFramework): Promise<{
+        controls: Array<{
+            id: string;
+            name: string;
+            description: string;
+        }>;
+    }>;
+    listSessions(appId: string): Promise<ListResponse<Session>>;
+    revokeSession(appId: string, sessionId: string): Promise<void>;
+    emergencyLockdown(appId: string, reason: string): Promise<{
+        locked: boolean;
+        timestamp: string;
+    }>;
+    liftLockdown(appId: string): Promise<void>;
+    getReceiver(receiverUID: string): Promise<Record<string, unknown>>;
+    listReceivers(filters?: {
+        status?: string;
+        organizationId?: string;
+    }): Promise<Record<string, unknown>[]>;
+    initializeReceiver(installerEmail: string, organizationId: string, notes?: string): Promise<Record<string, unknown>>;
+    getReceiverStatus(receiverUID: string): Promise<Record<string, unknown>>;
+    activateReceiver(receiverUID: string): Promise<Record<string, unknown>>;
+    resendReceiverEmail(receiverUID: string): Promise<Record<string, unknown>>;
+    cancelReceiverInit(receiverUID: string): Promise<Record<string, unknown>>;
+    getReceiverStatistics(): Promise<Record<string, unknown>>;
+    onboardReceiverService(receiverUID: string, svc: {
+        name: string;
+        host: string;
+        port: number;
+        protocol: "http" | "https" | "ssh" | "rdp";
+        path?: string;
+    }): Promise<Record<string, unknown>>;
+    removeReceiverService(receiverUID: string, serviceName: string): Promise<Record<string, unknown>>;
+    listReceiverServices(receiverUID: string): Promise<Record<string, unknown>[]>;
+    pauseService(receiverUID: string, serviceName: string): Promise<Record<string, unknown>>;
+    resumeService(receiverUID: string, serviceName: string): Promise<Record<string, unknown>>;
+    disableService(receiverUID: string, serviceName: string): Promise<Record<string, unknown>>;
+    getServiceStatus(receiverUID: string, serviceName: string): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=client.d.ts.map