@muxoai/sdk 1.2.3 → 1.4.2

package/dist/oauth.d.ts

@@ -0,0 +1,32 @@
+/** Shared OAuth 2.1 (PKCE + consent) helpers for the Node server and the edge worker. */
+export declare const DEFAULT_OAUTH_SCOPE = "mcp:tools muxo:mcp muxo:read muxo:execute muxo:provision";
+export declare const PKCE_VERIFIER_PATTERN: RegExp;
+export declare const OAUTH_CODE_TTL_MS: number;
+/** API keys minted through OAuth do not expire; this is the advisory lifetime clients see. */
+export declare const OAUTH_ACCESS_TOKEN_TTL_SECONDS = 2592000;
+export declare const LOOPBACK_CLIENT_NAME = "An app on this computer";
+export interface AuthorizeRequest {
+    clientId: string;
+    clientName: string;
+    redirectUri: string;
+    state: string;
+    codeChallenge: string | null;
+    codeChallengeMethod: "S256" | "plain" | null;
+    scope: string;
+}
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+export declare function pkceS256(verifier: string): Promise<string>;
+export declare function timingSafeEqualText(a: string, b: string): boolean;
+/** Checks a token-endpoint code_verifier against the challenge stored with the authorization code. */
+export declare function verifyPkce(verifier: string, challenge: string, method: "S256" | "plain" | null): Promise<"ok" | "missing" | "mismatch">;
+export declare function oauthClientName(redirect: URL, clientId: string): string;
+/** Name of the workspace API key minted for an OAuth connection, as listed in the console. */
+export declare function oauthConnectionKeyName(clientName: string): string;
+/** Origin shown on the consent screen; app-scheme redirects have no origin, so show the scheme. */
+export declare function oauthRedirectOrigin(redirectUri: string): string;
+export declare function parseAuthorizeRequest(params: URLSearchParams): AuthorizeRequest | {
+    error: string;
+};
+/** Parses a token-endpoint body (form or JSON) and HTTP Basic client credentials into one parameter set. */
+export declare function parseOAuthFormBody(rawBody: string, contentType: string, authorizationHeader: string): URLSearchParams;
+export declare function oauthSecretToken(prefix: string): string;

package/dist/oauth.js

@@ -0,0 +1,134 @@
+import { MCP_TOOLS_OAUTH_SCOPE } from "./mcp-schema.js";
+/** Shared OAuth 2.1 (PKCE + consent) helpers for the Node server and the edge worker. */
+export const DEFAULT_OAUTH_SCOPE = `${MCP_TOOLS_OAUTH_SCOPE} muxo:mcp muxo:read muxo:execute muxo:provision`;
+export const PKCE_VERIFIER_PATTERN = /^[A-Za-z0-9._~-]{43,128}$/;
+export const OAUTH_CODE_TTL_MS = 10 * 60 * 1000;
+/** API keys minted through OAuth do not expire; this is the advisory lifetime clients see. */
+export const OAUTH_ACCESS_TOKEN_TTL_SECONDS = 2_592_000;
+export const LOOPBACK_CLIENT_NAME = "An app on this computer";
+const BLOCKED_REDIRECT_SCHEMES = new Set(["javascript:", "data:", "file:", "vbscript:", "about:", "blob:", "ftp:"]);
+export function base64UrlEncode(bytes) {
+    let binary = "";
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export async function pkceS256(verifier) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+    return base64UrlEncode(new Uint8Array(digest));
+}
+export function timingSafeEqualText(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** Checks a token-endpoint code_verifier against the challenge stored with the authorization code. */
+export async function verifyPkce(verifier, challenge, method) {
+    if (!PKCE_VERIFIER_PATTERN.test(verifier))
+        return "missing";
+    const computed = method === "S256" ? await pkceS256(verifier) : verifier;
+    return timingSafeEqualText(computed, challenge) ? "ok" : "mismatch";
+}
+export function oauthClientName(redirect, clientId) {
+    const host = redirect.hostname.toLowerCase();
+    if (host === "chatgpt.com" || host.endsWith(".chatgpt.com") || host.endsWith(".openai.com"))
+        return "ChatGPT";
+    if (host === "claude.ai" || host.endsWith(".claude.ai") || host.endsWith(".anthropic.com"))
+        return "Claude";
+    if (host === "127.0.0.1" || host === "localhost" || host === "[::1]")
+        return LOOPBACK_CLIENT_NAME;
+    if (redirect.protocol !== "https:" && redirect.protocol !== "http:")
+        return redirect.protocol.replace(/:$/, "");
+    return clientId.length <= 64 && /^[\w.-]+$/.test(clientId) && !clientId.startsWith("muxo_dcr_") ? clientId : host;
+}
+/** Name of the workspace API key minted for an OAuth connection, as listed in the console. */
+export function oauthConnectionKeyName(clientName) {
+    return `${clientName === LOOPBACK_CLIENT_NAME ? "Local app" : clientName} connection`;
+}
+/** Origin shown on the consent screen; app-scheme redirects have no origin, so show the scheme. */
+export function oauthRedirectOrigin(redirectUri) {
+    const target = new URL(redirectUri);
+    return target.origin === "null" ? target.protocol : target.origin;
+}
+export function parseAuthorizeRequest(params) {
+    const responseType = params.get("response_type");
+    if (responseType && responseType !== "code")
+        return { error: "Only response_type=code is supported." };
+    const redirectUri = (params.get("redirect_uri") || "").trim();
+    if (!redirectUri || redirectUri.length > 2048)
+        return { error: "A valid redirect_uri is required." };
+    let redirect;
+    try {
+        redirect = new URL(redirectUri);
+    }
+    catch {
+        return { error: "redirect_uri is not a valid URL." };
+    }
+    const loopback = ["127.0.0.1", "localhost", "[::1]"].includes(redirect.hostname);
+    if (redirect.hash ||
+        BLOCKED_REDIRECT_SCHEMES.has(redirect.protocol) ||
+        (redirect.protocol === "http:" && !loopback)) {
+        return { error: "redirect_uri must use https, a loopback http address, or an app scheme." };
+    }
+    const clientId = (params.get("client_id") || "muxo-mcp-client").trim().slice(0, 256);
+    const codeChallenge = (params.get("code_challenge") || "").trim() || null;
+    const rawMethod = (params.get("code_challenge_method") || "").trim();
+    if (codeChallenge && !PKCE_VERIFIER_PATTERN.test(codeChallenge)) {
+        return { error: "code_challenge is malformed." };
+    }
+    if (rawMethod && rawMethod !== "S256" && rawMethod !== "plain") {
+        return { error: "code_challenge_method must be S256 or plain." };
+    }
+    return {
+        clientId,
+        clientName: oauthClientName(redirect, clientId),
+        redirectUri,
+        state: (params.get("state") || "").slice(0, 1024),
+        codeChallenge,
+        codeChallengeMethod: codeChallenge ? (rawMethod === "S256" ? "S256" : "plain") : null,
+        scope: (params.get("scope") || DEFAULT_OAUTH_SCOPE).slice(0, 512),
+    };
+}
+/** Parses a token-endpoint body (form or JSON) and HTTP Basic client credentials into one parameter set. */
+export function parseOAuthFormBody(rawBody, contentType, authorizationHeader) {
+    const params = new URLSearchParams();
+    if (contentType.includes("application/json")) {
+        let body = {};
+        try {
+            const parsed = JSON.parse(rawBody || "{}");
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                body = parsed;
+        }
+        catch {
+            body = {};
+        }
+        for (const [k, v] of Object.entries(body))
+            if (typeof v === "string")
+                params.set(k, v);
+    }
+    else {
+        for (const [k, v] of new URLSearchParams(rawBody))
+            params.set(k, v);
+    }
+    const basic = authorizationHeader.match(/^basic\s+(.+)$/i);
+    if (basic && !params.get("client_id")) {
+        try {
+            const decoded = atob(basic[1].trim());
+            params.set("client_id", decodeURIComponent(decoded.split(":")[0] || ""));
+        }
+        catch {
+            // Public clients do not need client credentials, so a malformed header is ignored.
+        }
+    }
+    return params;
+}
+export function oauthSecretToken(prefix) {
+    const bytes = new Uint8Array(24);
+    crypto.getRandomValues(bytes);
+    return `${prefix}_${Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("")}`;
+}

package/dist/policy.d.ts

@@ -0,0 +1,190 @@
+import type { GovernancePolicy, HumanFriendlyExplanation, LanguageMode, ParameterPolicyRule, RiskLevel } from "./types.js";
+export declare function sanitizeParameterPolicyRule(r: Record<string, unknown>, idx?: number): ParameterPolicyRule;
+export declare class PolicyValidationError extends Error {
+}
+export declare function formatHumanFriendlyExplanation(params: {
+    headline: string;
+    nonTechnical: string;
+    technical: string;
+    policy?: Partial<GovernancePolicy> | null;
+    languageMode?: LanguageMode;
+}): HumanFriendlyExplanation;
+/**
+ * Validates a client-supplied policy patch. Kill-switch fields are rejected so
+ * that pausing and resuming always goes through /api/v1/governance/kill-switch,
+ * which records the trust-score penalty and audit entry.
+ */
+export declare function sanitizePolicyPatch(body: unknown): Partial<GovernancePolicy>;
+export declare const DEFAULT_WORKSPACE_POLICY: GovernancePolicy;
+export interface ParsedNaturalLanguageGuardrail {
+    isGuardrail: boolean;
+    patch: Partial<GovernancePolicy>;
+    ruleText: string;
+    summary: string;
+    humanRules: string[];
+    compiledBy?: "deterministic" | "llm" | "mcp_harness";
+    memoryFact: {
+        title: string;
+        content: string;
+        subject: string;
+        predicate: string;
+        object: string;
+        tags: string[];
+    };
+}
+export interface GuardrailCompileOptions {
+    parameterRules?: Array<Record<string, unknown> | ParameterPolicyRule>;
+    policyPatch?: Partial<GovernancePolicy>;
+    source?: ParameterPolicyRule["source"];
+    llmApiKey?: string | null;
+    llmProvider?: "openai" | "anthropic";
+}
+/**
+ * Compiles plain-English user guardrails (e.g. "Hey Muxo, don't go over 25 credits",
+ * "Only allow sending emails to @muxo.ai", or "Require approval for Stripe refunds over $50,
+ * auto-approve under $50") and/or structured MCP harness parameter rules into enforced
+ * GovernancePolicy fields while keeping human-readable rule descriptions.
+ */
+export declare function parseNaturalLanguageGuardrail(prompt: string, currentPolicy?: GovernancePolicy, options?: GuardrailCompileOptions): ParsedNaturalLanguageGuardrail;
+/**
+ * Async LLM-assisted policy compiler: first runs deterministic semantic compilation
+ * (plus any structured `parameterRules` supplied by an MCP LLM harness), and when an
+ * OpenAI or Anthropic key is available and a complex natural-language rule produced no
+ * structured patch fields, invokes the LLM to synthesize validated `ParameterPolicyRule[]`.
+ */
+export declare function compileNaturalLanguageGuardrailWithLlm(prompt: string, currentPolicy?: GovernancePolicy, options?: GuardrailCompileOptions): Promise<ParsedNaturalLanguageGuardrail>;
+export declare function describePolicyInPlainEnglish(policy?: GovernancePolicy): {
+    headline: string;
+    rules: string[];
+    activeCustomRules: string[];
+    badges: Array<{
+        label: string;
+        tone: "safe" | "warn" | "strict";
+    }>;
+    languageMode: LanguageMode;
+    customInstructions: string[];
+    nonTechnical: string;
+    technical: string;
+    preferred: string;
+    explanation: HumanFriendlyExplanation;
+};
+export declare function evaluateParameterPolicyRules(paramsOrToolSlug: {
+    policy?: Partial<GovernancePolicy> | null;
+    toolSlug: string;
+    input: Record<string, unknown>;
+} | string, maybeInput?: Record<string, unknown>, maybePolicy?: Partial<GovernancePolicy> | null): {
+    violated: boolean;
+    allowed: boolean;
+    explicitAllow: boolean;
+    action: "allow" | "auto_approve" | "block" | "deny" | "require_approval";
+    matchedRule: ParameterPolicyRule | null;
+    violatedRule: ParameterPolicyRule | null;
+    reason: string | null;
+};
+export declare function describeParameterRuleCompliance(rule: ParameterPolicyRule): string;
+export interface LlmRiskLaneRule {
+    riskLevel: RiskLevel;
+    status: "auto_approved" | "requires_approval" | "blocked";
+    executeTool: string;
+    reason: string;
+}
+export interface LlmPolicyAndGovernanceBrief {
+    workspaceId?: string;
+    posture: "paused" | "read_only_sandbox" | "ask_every_time" | "safe_default" | "hands_off" | "monitor";
+    mode: "enforce" | "monitor";
+    executionRing: 0 | 1 | 2 | 3;
+    headline: string;
+    preferredExplanation: string;
+    plainEnglish: ReturnType<typeof describePolicyInPlainEnglish>;
+    languageMode: LanguageMode;
+    customInstructions: string[];
+    killSwitch: {
+        active: boolean;
+        reason: string | null;
+        howToToggleMcp: {
+            pause: {
+                tool: "get_run_context";
+                arguments: Record<string, unknown>;
+            };
+            resume: {
+                tool: "get_run_context";
+                arguments: Record<string, unknown>;
+            };
+        };
+    };
+    budgetGuardrail: {
+        maxCreditsPerRun: number;
+        maxUsdPerRun: number;
+        allowInstantWallet: boolean;
+        allowProvisioning: boolean;
+        blockDestructiveSql: boolean;
+    };
+    riskLaneMatrix: Record<RiskLevel, LlmRiskLaneRule>;
+    autoApproveRiskLevels: RiskLevel[];
+    requireApprovalRiskLevels: RiskLevel[];
+    blockedRiskLevels: RiskLevel[];
+    blockedToolSlugs: string[];
+    parameterRules: Array<ParameterPolicyRule & {
+        howToComply: string;
+    }>;
+    naturalLanguageRules: string[];
+    activeDefaults: Record<string, unknown>;
+    trustScore?: {
+        overall: number;
+        tier: string;
+    };
+    agentDid?: string;
+    llmSystemDirective: string;
+    agentControlCheatsheet: Array<{
+        intent: string;
+        mcpTool: string;
+        arguments: Record<string, unknown>;
+    }>;
+}
+export declare function buildLlmPolicyAndGovernanceBrief(policy?: GovernancePolicy, options?: {
+    workspaceId?: string;
+    workspaceName?: string;
+    workspaceSlug?: string;
+    activeDefaults?: Record<string, unknown>;
+    trustScore?: {
+        overall: number;
+        tier: string;
+    };
+    agentDid?: string;
+}): LlmPolicyAndGovernanceBrief;
+export interface PolicySimulationResult {
+    ok: true;
+    action: "check_policy";
+    toolSlug: string;
+    toolName?: string;
+    riskLevel: RiskLevel;
+    creditCost: number;
+    decision: "auto_approved" | "pending_approval" | "blocked";
+    approvalStatus: "auto_approved" | "pending_approval" | "blocked";
+    allowed: boolean;
+    requiresApproval: boolean;
+    blocked: boolean;
+    executeTool: string;
+    effectiveInput: Record<string, unknown>;
+    autoFilledInput: Record<string, unknown>;
+    reasons: string[];
+    matchedParameterRule: ParameterPolicyRule | null;
+    violatedParameterRule: ParameterPolicyRule | null;
+    remediationForLlm: string;
+    nextToolCalls: Array<{
+        tool: string;
+        input: Record<string, unknown>;
+        when: string;
+    }>;
+}
+export declare function simulatePolicyEvaluation(params: {
+    policy?: GovernancePolicy | null;
+    toolSlug: string;
+    toolName?: string;
+    riskLevel?: RiskLevel;
+    creditCost?: number;
+    creditsBalance?: number;
+    lane?: string;
+    input?: Record<string, unknown>;
+    activeDefaults?: Record<string, unknown>;
+}): PolicySimulationResult;