@sellable/mcp 0.1.619-wip.121.2 → 0.1.619

package/dist/agent-approval-effect-port.d.ts

@@ -0,0 +1,5 @@
+import type { AgentApprovalConsumeInput, AgentApprovalConsumeResult, AgentApprovalEffectPort, AgentApprovalRequestInput, AgentApprovalRequestPort, AgentApprovalRequestResult } from "./agent-tool-policy.js";
+export declare class HttpAgentApprovalEffectPort implements AgentApprovalEffectPort, AgentApprovalRequestPort {
+    requestApproval(input: AgentApprovalRequestInput): Promise<AgentApprovalRequestResult>;
+    consumeApprovalAndStartEffect(input: AgentApprovalConsumeInput): Promise<AgentApprovalConsumeResult>;
+}

package/dist/agent-approval-effect-port.js

@@ -0,0 +1,30 @@
+import { getApi } from "./api.js";
+export class HttpAgentApprovalEffectPort {
+    async requestApproval(input) {
+        return getApi().post("/api/v3/sellable-agent/approvals/requests", {
+            requesterId: input.requesterId,
+            channelId: input.channelId,
+            providerRequestId: input.providerRequestId,
+            tool: input.tool,
+            args: input.arguments,
+        }, { workspaceId: null });
+    }
+    async consumeApprovalAndStartEffect(input) {
+        try {
+            const result = await getApi().post("/api/v3/sellable-agent/approvals/effects", {
+                approvalId: input.approvalId,
+                requesterId: input.requesterId,
+                channelId: input.channelId,
+                providerRequestId: input.providerRequestId,
+                tool: input.tool,
+                args: input.arguments,
+            }, { workspaceId: null });
+            return result.effectId
+                ? { status: "AUTHORIZED", effectId: result.effectId }
+                : { status: "MISSING" };
+        }
+        catch {
+            return { status: "MISSING" };
+        }
+    }
+}

package/dist/agent-service-auth.d.ts

@@ -0,0 +1,94 @@
+export interface McpAgentServiceContext {
+    kind: "agent_service";
+    credentialId: string;
+    workspaceId: string;
+    agentId: string;
+    generation: number;
+    policyHash: string;
+    selectedChannelIds: readonly string[];
+}
+type McpAgentEnvironment = Record<string, string | undefined>;
+export type McpCredentialIntent = "unconfigured" | "human" | "agent_service" | "invalid";
+export type McpCredentialResolution = {
+    mode: "human";
+    principal: null;
+} | {
+    mode: "agent_service";
+    principal: McpAgentServiceContext;
+} | {
+    mode: "invalid";
+    principal: null;
+    code: "invalid_agent_service_context";
+};
+export declare function resolveMcpCredentialIntent(input: {
+    env?: McpAgentEnvironment;
+    getConfig: () => {
+        token: string;
+        credentialKind?: "human" | "agent_service";
+    };
+    getCredentialIntent: () => McpCredentialIntent;
+}): McpCredentialResolution;
+export declare function createMcpCredentialBoundary<T extends {
+    name: string;
+}>(input: {
+    allTools: readonly T[];
+    resolve: () => McpCredentialResolution;
+    agentAuthorization: {
+        listTools(context: {
+            principal: McpAgentServiceContext | null;
+        }): readonly T[];
+        authorizeCall(call: {
+            name: string;
+            args: unknown;
+            context: {
+                principal: McpAgentServiceContext | null;
+                requesterId?: string | null;
+                channelId?: string | null;
+                providerRequestId?: string | null;
+                approvalId?: string | null;
+            };
+        }): Promise<unknown>;
+    };
+}): {
+    listTools(): readonly T[];
+    authorizeCall(call: {
+        name: string;
+        args: unknown;
+        requesterId?: string | null;
+        channelId?: string | null;
+        providerRequestId?: string | null;
+        approvalId?: string | null;
+    }): Promise<{
+        mode: "invalid";
+        authorization: {
+            allowed: boolean;
+            decision: string;
+            code: "invalid_agent_service_context";
+        };
+        context?: undefined;
+    } | {
+        mode: "human";
+        authorization: null;
+        context?: undefined;
+    } | {
+        mode: "agent_service";
+        authorization: {
+            allowed: false;
+            decision: "DENY";
+            code: string;
+        };
+        context?: undefined;
+    } | {
+        mode: "agent_service";
+        authorization: unknown;
+        context: {
+            principal: McpAgentServiceContext;
+            requesterId: string;
+            channelId: string;
+            providerRequestId: string;
+            approvalId: string | null;
+        };
+    }>;
+};
+export declare function readMcpAgentServiceContext(env?: McpAgentEnvironment, token?: string | null): McpAgentServiceContext | null;
+export {};

package/dist/agent-service-auth.js

@@ -0,0 +1,177 @@
+export function resolveMcpCredentialIntent(input) {
+    const env = input.env ?? process.env;
+    let intent;
+    try {
+        intent = input.getCredentialIntent();
+    }
+    catch {
+        return {
+            mode: "invalid",
+            principal: null,
+            code: "invalid_agent_service_context",
+        };
+    }
+    if (intent === "human" || intent === "unconfigured") {
+        return { mode: "human", principal: null };
+    }
+    if (intent !== "agent_service") {
+        return {
+            mode: "invalid",
+            principal: null,
+            code: "invalid_agent_service_context",
+        };
+    }
+    try {
+        const config = input.getConfig();
+        if (config.credentialKind !== "agent_service") {
+            return {
+                mode: "invalid",
+                principal: null,
+                code: "invalid_agent_service_context",
+            };
+        }
+        const principal = readMcpAgentServiceContext(env, config.token);
+        return principal
+            ? { mode: "agent_service", principal }
+            : {
+                mode: "invalid",
+                principal: null,
+                code: "invalid_agent_service_context",
+            };
+    }
+    catch {
+        return {
+            mode: "invalid",
+            principal: null,
+            code: "invalid_agent_service_context",
+        };
+    }
+}
+export function createMcpCredentialBoundary(input) {
+    return {
+        listTools() {
+            const resolved = input.resolve();
+            if (resolved.mode === "invalid")
+                return [];
+            if (resolved.mode === "human")
+                return input.allTools;
+            return input.agentAuthorization.listTools({
+                principal: resolved.principal,
+            });
+        },
+        async authorizeCall(call) {
+            const resolved = input.resolve();
+            if (resolved.mode === "invalid") {
+                return {
+                    mode: "invalid",
+                    authorization: {
+                        allowed: false,
+                        decision: "DENY",
+                        code: resolved.code,
+                    },
+                };
+            }
+            if (resolved.mode === "human") {
+                return { mode: "human", authorization: null };
+            }
+            const requesterId = call.requesterId?.trim();
+            const channelId = call.channelId?.trim();
+            const providerRequestId = call.providerRequestId?.trim();
+            if (!requesterId ||
+                requesterId.length > 160 ||
+                !channelId ||
+                channelId.length > 160 ||
+                !providerRequestId ||
+                providerRequestId.length > 160) {
+                return {
+                    mode: "agent_service",
+                    authorization: {
+                        allowed: false,
+                        decision: "DENY",
+                        code: "agent_request_context_required",
+                    },
+                };
+            }
+            if (!resolved.principal.selectedChannelIds.includes(channelId)) {
+                return {
+                    mode: "agent_service",
+                    authorization: {
+                        allowed: false,
+                        decision: "DENY",
+                        code: "agent_channel_not_selected",
+                    },
+                };
+            }
+            const context = {
+                principal: resolved.principal,
+                requesterId,
+                channelId,
+                providerRequestId,
+                approvalId: call.approvalId?.trim() || null,
+            };
+            return {
+                mode: "agent_service",
+                authorization: await input.agentAuthorization.authorizeCall({
+                    name: call.name,
+                    args: call.args,
+                    context,
+                }),
+                context,
+            };
+        },
+    };
+}
+export function readMcpAgentServiceContext(env = process.env, token) {
+    const values = {
+        workspaceId: env.SELLABLE_AGENT_WORKSPACE_ID,
+        agentId: env.SELLABLE_AGENT_ID,
+        generation: env.SELLABLE_AGENT_CREDENTIAL_GENERATION,
+        policyHash: env.SELLABLE_AGENT_POLICY_HASH,
+        selectedChannelIds: env.SELLABLE_AGENT_SELECTED_CHANNEL_IDS,
+    };
+    if (Object.values(values).every((value) => value == null)) {
+        if (token?.startsWith("sat_")) {
+            throw new Error("Sellable Agent service token has no bound Agent context");
+        }
+        return null;
+    }
+    const tokenMatch = token?.match(/^sat_([^_\s]+)_(\S+)$/);
+    if (!tokenMatch ||
+        !values.workspaceId ||
+        !values.agentId ||
+        !values.generation ||
+        !values.policyHash ||
+        !values.selectedChannelIds ||
+        !/^\d+$/.test(values.generation) ||
+        Number(values.generation) < 1 ||
+        !/^[a-f0-9]{64}$/.test(values.policyHash) ||
+        env.SELLABLE_LOCK_WORKSPACE_ID !== values.workspaceId ||
+        !["1", "true", "yes"].includes((env.SELLABLE_REQUIRE_WORKSPACE_LOCK ?? "").trim().toLowerCase())) {
+        throw new Error("Incomplete Sellable Agent service context");
+    }
+    let selectedChannelIds;
+    try {
+        const parsed = JSON.parse(values.selectedChannelIds);
+        if (!Array.isArray(parsed) ||
+            parsed.length < 1 ||
+            parsed.length > 100 ||
+            parsed.some((channelId) => typeof channelId !== "string" ||
+                !/^[A-Za-z0-9_-]{1,128}$/.test(channelId)) ||
+            new Set(parsed).size !== parsed.length) {
+            throw new Error("invalid selected channels");
+        }
+        selectedChannelIds = [...parsed].sort();
+    }
+    catch {
+        throw new Error("Incomplete Sellable Agent service context");
+    }
+    return {
+        kind: "agent_service",
+        credentialId: tokenMatch[1],
+        workspaceId: values.workspaceId,
+        agentId: values.agentId,
+        generation: Number(values.generation),
+        policyHash: values.policyHash,
+        selectedChannelIds,
+    };
+}

package/dist/agent-tool-policy.d.ts

@@ -0,0 +1,156 @@
+export type AgentToolDecision = "AUTO" | "REQUESTER_CONFIRM" | "WORKSPACE_APPROVER" | "DENY";
+export interface AgentToolPolicyEntry {
+    tool: string;
+    version: string;
+    decision: AgentToolDecision;
+    method: "GET" | "PUT" | "POST";
+    route: string;
+    handler: string;
+    workspaceBinding: string;
+}
+export interface CompiledAgentToolPolicy {
+    policyHash: string;
+    entries: readonly AgentToolPolicyEntry[];
+}
+export interface AgentPolicyPrincipal {
+    kind: "agent_service";
+    workspaceId: string;
+    agentId: string;
+    generation: number;
+    policyHash: string;
+}
+export interface AgentApprovalConsumeInput {
+    approvalId: string;
+    requesterId: string;
+    channelId: string;
+    providerRequestId: string;
+    argumentHash: string;
+    workspaceId: string;
+    agentId: string;
+    tool: string;
+    toolVersion: string;
+    policyHash: string;
+    credentialGeneration: number;
+    decision: "REQUESTER_CONFIRM" | "WORKSPACE_APPROVER";
+    now: Date;
+    arguments?: unknown;
+}
+export type AgentApprovalConsumeResult = {
+    status: "AUTHORIZED";
+    effectId: string;
+} | {
+    status: "MISSING" | "MISMATCH" | "EXPIRED" | "REVOKED" | "CONSUMED";
+};
+export interface AgentApprovalEffectPort {
+    consumeApprovalAndStartEffect(input: AgentApprovalConsumeInput): Promise<AgentApprovalConsumeResult>;
+}
+export interface AgentApprovalRequestInput {
+    requesterId: string;
+    channelId: string;
+    providerRequestId: string;
+    tool: string;
+    arguments: unknown;
+}
+export type AgentApprovalRequestStatus = "PENDING" | "APPROVED" | "DENIED" | "CONSUMED" | "REVOKED" | "EXPIRED";
+export interface AgentApprovalRequestResult {
+    approvalId: string;
+    workspaceId: string;
+    agentId: string;
+    requesterId: string;
+    channelId: string;
+    providerRequestId: string;
+    tool: string;
+    toolVersion: string;
+    decision: "REQUESTER_CONFIRM" | "WORKSPACE_APPROVER";
+    status: AgentApprovalRequestStatus;
+    expiresAt: string;
+    replayed: boolean;
+}
+export interface AgentApprovalRequestPort {
+    requestApproval(input: AgentApprovalRequestInput): Promise<AgentApprovalRequestResult>;
+}
+export interface ApprovalBinding {
+    approvalId: string;
+    actorId: string;
+    workspaceId: string;
+    agentId: string;
+    tool: string;
+    toolVersion: string;
+    policyHash: string;
+    credentialGeneration: number;
+    channelId: string;
+    argumentHash: string;
+    expiresAt: Date;
+    consumedAt: Date | null;
+    revokedAt: Date | null;
+    decision: "REQUESTER_CONFIRM" | "WORKSPACE_APPROVER";
+}
+export interface AgentMcpRequestContext {
+    principal: AgentPolicyPrincipal | null;
+    requesterId?: string | null;
+    channelId?: string | null;
+    providerRequestId?: string | null;
+    approvalId?: string | null;
+}
+export type AgentToolAuthorization = {
+    allowed: true;
+    decision: Exclude<AgentToolDecision, "DENY">;
+    policy: AgentToolPolicyEntry;
+    effectId?: string;
+} | {
+    allowed: false;
+    decision: AgentToolDecision;
+    code: string;
+    approval?: AgentApprovalRequestResult;
+};
+export declare const DEFAULT_AGENT_TOOL_CATALOGUE: readonly AgentToolPolicyEntry[];
+export declare function compileAgentToolPolicy(entries?: readonly AgentToolPolicyEntry[]): CompiledAgentToolPolicy;
+export declare function decideAgentTool(compiled: CompiledAgentToolPolicy, tool: string): AgentToolPolicyEntry & {
+    allowed: boolean;
+};
+export declare function listToolsForAgent<T extends {
+    name: string;
+}>(compiled: CompiledAgentToolPolicy, definitions: readonly T[]): readonly T[];
+export declare function portableSha256(value: string): string;
+export declare function hashApprovalArguments(args: unknown): string;
+export declare function canonicalAgentToolArguments(tool: string, args: unknown): unknown;
+export declare function hashAgentToolArguments(tool: string, args: unknown): string;
+export declare function deriveAgentApprovalRequestId(input: {
+    workspaceId: string;
+    agentId: string;
+    requesterId: string;
+    channelId: string;
+    providerRequestId: string;
+    tool: string;
+    toolVersion: string;
+    arguments: unknown;
+    policyHash: string;
+    credentialGeneration: number;
+    decision: "REQUESTER_CONFIRM" | "WORKSPACE_APPROVER";
+}): string;
+export declare function validateApprovalBinding(input: {
+    approval: ApprovalBinding | null;
+    expected: Omit<ApprovalBinding, "approvalId" | "expiresAt" | "consumedAt" | "revokedAt">;
+    now?: Date;
+}): {
+    ok: boolean;
+    code: string;
+};
+export declare function createAgentMcpAuthorizationHandlers(input: {
+    allTools: readonly {
+        name: string;
+    }[];
+    policy?: CompiledAgentToolPolicy;
+    approvalPort?: (AgentApprovalEffectPort & Partial<AgentApprovalRequestPort>) | null;
+    now?: () => Date;
+}): {
+    listTools(context: AgentMcpRequestContext): readonly {
+        name: string;
+    }[];
+    authorizeCall(call: {
+        name: string;
+        args: unknown;
+        context: AgentMcpRequestContext;
+    }): Promise<AgentToolAuthorization>;
+    policy: CompiledAgentToolPolicy;
+};