mrmainspring 0.1.0

package/dist/env-file.js

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export function loadLocalEnvFile(env = process.env) {
+    const envPath = resolveEnvPath(env);
+    if (!envPath || !existsSync(envPath)) {
+        return null;
+    }
+    const raw = readFileSync(envPath, "utf8");
+    for (const [key, value] of parseEnv(raw)) {
+        if (env[key] === undefined) {
+            env[key] = value;
+        }
+    }
+    return envPath;
+}
+function resolveEnvPath(env) {
+    if (env.SIGIL_ENV_FILE?.trim()) {
+        return env.SIGIL_ENV_FILE.trim();
+    }
+    const backendRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    const repoRoot = dirname(backendRoot);
+    const candidates = [join(process.cwd(), ".env"), join(backendRoot, ".env"), join(repoRoot, ".env")];
+    return candidates.find((candidate) => existsSync(candidate)) ?? candidates.at(-1) ?? null;
+}
+function parseEnv(raw) {
+    const entries = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        const separator = trimmed.indexOf("=");
+        if (separator <= 0) {
+            continue;
+        }
+        const key = trimmed.slice(0, separator).trim();
+        const value = unquote(trimmed.slice(separator + 1).trim());
+        if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            entries.push([key, value]);
+        }
+    }
+    return entries;
+}
+function unquote(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}

package/dist/grimoire/service.d.ts

@@ -0,0 +1,13 @@
+import type { AuditService } from "../audit/service.js";
+import type { GrimoireStore, PolicyRecord, PolicySetInput, SecretMetadata, SecretPutInput } from "./types.js";
+export declare class GrimoireService {
+    private readonly store;
+    private readonly masterKey;
+    private readonly audit?;
+    constructor(store: GrimoireStore, masterKey: Buffer, audit?: AuditService | undefined);
+    putSecret(input: SecretPutInput): Promise<SecretMetadata>;
+    listSecrets(agentId: string): Promise<SecretMetadata[]>;
+    setPolicy(input: PolicySetInput): Promise<PolicyRecord>;
+    getPolicy(agentId: string, policyId: string): Promise<PolicyRecord | null>;
+    recordPolicySpend(agentId: string, policyId: string, amount: string): Promise<PolicyRecord | null>;
+}

package/dist/grimoire/service.js

@@ -0,0 +1,199 @@
+import { createCipheriv, randomBytes, randomUUID } from "node:crypto";
+import { canonicalizeJson, toJsonObject } from "../memory/canonical.js";
+import { sha256Hex } from "../memory/hash.js";
+export class GrimoireService {
+    store;
+    masterKey;
+    audit;
+    constructor(store, masterKey, audit) {
+        this.store = store;
+        this.masterKey = masterKey;
+        this.audit = audit;
+    }
+    async putSecret(input) {
+        const now = new Date().toISOString();
+        const encrypted = encrypt(input.value, this.masterKey);
+        const existing = await this.store.getSecretByName(input.agent_id, input.name);
+        const record = {
+            id: existing?.id ?? createId("sec"),
+            agent_id: input.agent_id,
+            name: input.name,
+            type: input.type,
+            scopes: [...new Set(input.scopes)].sort(),
+            ciphertext: encrypted.ciphertext,
+            nonce: encrypted.nonce,
+            auth_tag: encrypted.authTag,
+            key_version: "local-v1",
+            created_at: existing?.created_at ?? now,
+            updated_at: now,
+            deleted_at: null
+        };
+        await this.store.saveSecret(record);
+        await this.audit?.record({
+            agent_id: record.agent_id,
+            event_type: "secret.stored",
+            subject_type: "secret",
+            subject_id: record.id,
+            metadata: {
+                name: record.name,
+                type: record.type,
+                scopes: record.scopes
+            }
+        });
+        return toSecretMetadata(record);
+    }
+    async listSecrets(agentId) {
+        const secrets = await this.store.listSecrets(agentId);
+        const metadata = secrets.filter((secret) => !secret.deleted_at).map(toSecretMetadata);
+        await this.audit?.record({
+            agent_id: agentId,
+            event_type: "secret.listed",
+            subject_type: "secret",
+            metadata: { count: metadata.length }
+        });
+        return metadata;
+    }
+    async setPolicy(input) {
+        assertDecimalAmount("max_amount_per_call", input.max_amount_per_call);
+        assertDecimalAmount("max_amount_per_period", input.max_amount_per_period);
+        const now = new Date().toISOString();
+        const existing = await this.store.getPolicy(input.agent_id, input.policy_id);
+        const policyBody = {
+            agent_id: input.agent_id,
+            policy_id: input.policy_id,
+            enabled: input.enabled ?? true,
+            allowed_urls: input.allowed_urls,
+            allowed_methods: input.allowed_methods.map((method) => method.toUpperCase()).sort(),
+            allowed_asset: toJsonObject(input.allowed_asset, "allowed_asset"),
+            max_amount_per_call: input.max_amount_per_call,
+            max_amount_per_period: input.max_amount_per_period,
+            period_seconds: input.period_seconds,
+            secret_scopes: [...new Set(input.secret_scopes)].sort()
+        };
+        const record = {
+            ...policyBody,
+            policy_hash: sha256Hex(canonicalizeJson(policyBody)),
+            current_period_spend: existing?.current_period_spend ?? "0",
+            period_started_at: existing?.period_started_at ?? now,
+            created_at: existing?.created_at ?? now,
+            updated_at: now
+        };
+        await this.store.savePolicy(record);
+        await this.audit?.record({
+            agent_id: record.agent_id,
+            event_type: "policy.set",
+            subject_type: "policy",
+            subject_id: record.policy_id,
+            metadata: {
+                enabled: record.enabled,
+                policy_hash: record.policy_hash,
+                allowed_urls: record.allowed_urls,
+                allowed_methods: record.allowed_methods
+            }
+        });
+        return record;
+    }
+    async getPolicy(agentId, policyId) {
+        const policy = await this.store.getPolicy(agentId, policyId);
+        await this.audit?.record({
+            agent_id: agentId,
+            event_type: "policy.get",
+            subject_type: "policy",
+            subject_id: policyId,
+            metadata: { found: Boolean(policy) }
+        });
+        return policy;
+    }
+    async recordPolicySpend(agentId, policyId, amount) {
+        assertDecimalAmount("amount", amount);
+        const policy = await this.store.getPolicy(agentId, policyId);
+        if (!policy) {
+            await this.audit?.record({
+                agent_id: agentId,
+                event_type: "policy.spend_record_failed",
+                subject_type: "policy",
+                subject_id: policyId,
+                severity: "warn",
+                metadata: { reason: "policy_not_found" }
+            });
+            return null;
+        }
+        const now = new Date();
+        const nowIso = now.toISOString();
+        const periodStartedAt = Date.parse(policy.period_started_at);
+        const periodExpired = Number.isNaN(periodStartedAt) ||
+            now.getTime() - periodStartedAt >= policy.period_seconds * 1000;
+        const currentSpend = periodExpired ? "0" : policy.current_period_spend;
+        const updated = {
+            ...policy,
+            current_period_spend: addDecimalAmounts(currentSpend, amount),
+            period_started_at: periodExpired ? nowIso : policy.period_started_at,
+            updated_at: nowIso
+        };
+        await this.store.savePolicy(updated);
+        await this.audit?.record({
+            agent_id: agentId,
+            event_type: "policy.spend_recorded",
+            subject_type: "policy",
+            subject_id: policyId,
+            metadata: {
+                amount,
+                current_period_spend: updated.current_period_spend,
+                policy_hash: updated.policy_hash
+            }
+        });
+        return updated;
+    }
+}
+function encrypt(value, key) {
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, nonce);
+    const ciphertext = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return {
+        ciphertext: ciphertext.toString("base64"),
+        nonce: nonce.toString("base64"),
+        authTag: authTag.toString("base64")
+    };
+}
+function toSecretMetadata(secret) {
+    return {
+        id: secret.id,
+        agent_id: secret.agent_id,
+        name: secret.name,
+        type: secret.type,
+        scopes: secret.scopes,
+        created_at: secret.created_at,
+        updated_at: secret.updated_at
+    };
+}
+function createId(prefix) {
+    return `${prefix}_${randomUUID().replaceAll("-", "")}`;
+}
+function assertDecimalAmount(name, value) {
+    if (!/^\d+(\.\d+)?$/.test(value)) {
+        throw new Error(`${name} must be a non-negative decimal amount`);
+    }
+}
+function addDecimalAmounts(left, right) {
+    const leftParts = parseDecimalAmount(left);
+    const rightParts = parseDecimalAmount(right);
+    const scale = Math.max(leftParts.scale, rightParts.scale);
+    const leftValue = leftParts.value * 10n ** BigInt(scale - leftParts.scale);
+    const rightValue = rightParts.value * 10n ** BigInt(scale - rightParts.scale);
+    const sum = (leftValue + rightValue).toString().padStart(scale + 1, "0");
+    if (scale === 0) {
+        return sum;
+    }
+    const whole = sum.slice(0, -scale);
+    const fraction = sum.slice(-scale).replace(/0+$/, "");
+    return fraction ? `${whole}.${fraction}` : whole;
+}
+function parseDecimalAmount(value) {
+    assertDecimalAmount("amount", value);
+    const [whole, fraction = ""] = value.split(".");
+    return {
+        value: BigInt(`${whole}${fraction}`),
+        scale: fraction.length
+    };
+}

package/dist/grimoire/store.d.ts

@@ -0,0 +1,10 @@
+import type { GrimoireStore, PolicyRecord, SecretRecord } from "./types.js";
+export declare class FileGrimoireStore implements GrimoireStore {
+    private readonly store;
+    constructor(dataDir: string);
+    saveSecret(secret: SecretRecord): Promise<void>;
+    getSecretByName(agentId: string, name: string): Promise<SecretRecord | null>;
+    listSecrets(agentId: string): Promise<SecretRecord[]>;
+    savePolicy(policy: PolicyRecord): Promise<void>;
+    getPolicy(agentId: string, policyId: string): Promise<PolicyRecord | null>;
+}

package/dist/grimoire/store.js

@@ -0,0 +1,64 @@
+import { join } from "node:path";
+import { JsonFileStore } from "../storage/json-file-store.js";
+export class FileGrimoireStore {
+    store;
+    constructor(dataDir) {
+        this.store = new JsonFileStore({
+            filePath: join(dataDir, "grimoire.json"),
+            empty: emptyStore,
+            normalize: normalizeStore
+        });
+    }
+    async saveSecret(secret) {
+        await this.store.update((data) => {
+            const existingIndex = data.secrets.findIndex((item) => item.id === secret.id);
+            if (existingIndex >= 0) {
+                data.secrets[existingIndex] = secret;
+            }
+            else {
+                data.secrets.push(secret);
+            }
+        });
+    }
+    async getSecretByName(agentId, name) {
+        const data = await this.store.read();
+        return (data.secrets.find((secret) => secret.agent_id === agentId && secret.name === name && !secret.deleted_at) ?? null);
+    }
+    async listSecrets(agentId) {
+        const data = await this.store.read();
+        return data.secrets.filter((secret) => secret.agent_id === agentId);
+    }
+    async savePolicy(policy) {
+        await this.store.update((data) => {
+            const existingIndex = data.policies.findIndex((item) => item.agent_id === policy.agent_id && item.policy_id === policy.policy_id);
+            if (existingIndex >= 0) {
+                data.policies[existingIndex] = policy;
+            }
+            else {
+                data.policies.push(policy);
+            }
+        });
+    }
+    async getPolicy(agentId, policyId) {
+        const data = await this.store.read();
+        return (data.policies.find((policy) => policy.agent_id === agentId && policy.policy_id === policyId) ?? null);
+    }
+}
+function emptyStore() {
+    return {
+        schema_version: "sigil.grimoire-store.v1",
+        secrets: [],
+        policies: []
+    };
+}
+function normalizeStore(parsed) {
+    const data = asStoreObject(parsed);
+    return {
+        schema_version: "sigil.grimoire-store.v1",
+        secrets: Array.isArray(data.secrets) ? data.secrets : [],
+        policies: Array.isArray(data.policies) ? data.policies : []
+    };
+}
+function asStoreObject(parsed) {
+    return parsed && typeof parsed === "object" ? parsed : {};
+}

package/dist/grimoire/supabase-store.d.ts

@@ -0,0 +1,13 @@
+import { SupabaseRestClient } from "../storage/supabase-rest.js";
+import type { GrimoireStore, PolicyRecord, SecretRecord } from "./types.js";
+export declare class SupabaseGrimoireStore implements GrimoireStore {
+    private readonly client;
+    private readonly secretsTable;
+    private readonly policiesTable;
+    constructor(client: SupabaseRestClient);
+    saveSecret(secret: SecretRecord): Promise<void>;
+    getSecretByName(agentId: string, name: string): Promise<SecretRecord | null>;
+    listSecrets(agentId: string): Promise<SecretRecord[]>;
+    savePolicy(policy: PolicyRecord): Promise<void>;
+    getPolicy(agentId: string, policyId: string): Promise<PolicyRecord | null>;
+}

package/dist/grimoire/supabase-store.js

@@ -0,0 +1,50 @@
+export class SupabaseGrimoireStore {
+    client;
+    secretsTable;
+    policiesTable;
+    constructor(client) {
+        this.client = client;
+        this.secretsTable = client.table("secrets");
+        this.policiesTable = client.table("policies");
+    }
+    async saveSecret(secret) {
+        await this.client.upsert(this.secretsTable, {
+            id: secret.id,
+            agent_id: secret.agent_id,
+            name: secret.name,
+            created_at: secret.created_at,
+            updated_at: secret.updated_at,
+            deleted_at: secret.deleted_at,
+            record: secret
+        }, "id");
+    }
+    async getSecretByName(agentId, name) {
+        const records = await this.client.selectRecords(this.secretsTable, {
+            filters: { agent_id: agentId, name },
+            order: { column: "created_at" }
+        });
+        return records.find((secret) => !secret.deleted_at) ?? null;
+    }
+    async listSecrets(agentId) {
+        return this.client.selectRecords(this.secretsTable, {
+            filters: { agent_id: agentId },
+            order: { column: "created_at" }
+        });
+    }
+    async savePolicy(policy) {
+        await this.client.upsert(this.policiesTable, {
+            agent_id: policy.agent_id,
+            policy_id: policy.policy_id,
+            created_at: policy.created_at,
+            updated_at: policy.updated_at,
+            record: policy
+        }, "agent_id,policy_id");
+    }
+    async getPolicy(agentId, policyId) {
+        const [record] = await this.client.selectRecords(this.policiesTable, {
+            filters: { agent_id: agentId, policy_id: policyId },
+            limit: 1
+        });
+        return record ?? null;
+    }
+}

package/dist/grimoire/types.d.ts

@@ -0,0 +1,60 @@
+import type { JsonObject } from "../memory/types.js";
+export type SecretType = "casper_private_key_ref" | "x402_client_key_ref" | "api_key" | "webhook_secret";
+export type SecretPutInput = {
+    agent_id: string;
+    name: string;
+    type: SecretType;
+    value: string;
+    scopes: string[];
+};
+export type SecretRecord = {
+    id: string;
+    agent_id: string;
+    name: string;
+    type: SecretType;
+    scopes: string[];
+    ciphertext: string;
+    nonce: string;
+    auth_tag: string;
+    key_version: string;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+};
+export type SecretMetadata = Pick<SecretRecord, "id" | "agent_id" | "name" | "type" | "scopes" | "created_at" | "updated_at">;
+export type PolicySetInput = {
+    agent_id: string;
+    policy_id: string;
+    enabled?: boolean;
+    allowed_urls: string[];
+    allowed_methods: string[];
+    allowed_asset: unknown;
+    max_amount_per_call: string;
+    max_amount_per_period: string;
+    period_seconds: number;
+    secret_scopes: string[];
+};
+export type PolicyRecord = {
+    agent_id: string;
+    policy_id: string;
+    enabled: boolean;
+    allowed_urls: string[];
+    allowed_methods: string[];
+    allowed_asset: JsonObject;
+    max_amount_per_call: string;
+    max_amount_per_period: string;
+    period_seconds: number;
+    secret_scopes: string[];
+    policy_hash: string;
+    current_period_spend: string;
+    period_started_at: string;
+    created_at: string;
+    updated_at: string;
+};
+export type GrimoireStore = {
+    saveSecret(secret: SecretRecord): Promise<void>;
+    getSecretByName(agentId: string, name: string): Promise<SecretRecord | null>;
+    listSecrets(agentId: string): Promise<SecretRecord[]>;
+    savePolicy(policy: PolicyRecord): Promise<void>;
+    getPolicy(agentId: string, policyId: string): Promise<PolicyRecord | null>;
+};

package/dist/grimoire/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { loadLocalEnvFile } from "./env-file.js";
+import { createSigilServer } from "./server.js";
+async function main() {
+    loadLocalEnvFile();
+    const config = loadConfig();
+    const server = createSigilServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.stack ?? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+});

package/dist/mcp/auditTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AuditService } from "../audit/service.js";
+export declare function registerAuditTools(server: McpServer, auditService: AuditService): void;

package/dist/mcp/auditTools.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { jsonResult } from "./jsonResult.js";
+export function registerAuditTools(server, auditService) {
+    server.registerTool("audit.tail", {
+        title: "Tail Audit Events",
+        description: "Return recent Mr Mainspring audit events for memory, Grimoire, payment, and anchor activity.",
+        inputSchema: {
+            agent_id: z.string().min(1).optional(),
+            event_type: z.string().min(1).optional(),
+            limit: z.number().int().min(1).max(200).optional()
+        }
+    }, async (input) => jsonResult(await auditService.tail(input)));
+}

package/dist/mcp/grimoireTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { GrimoireService } from "../grimoire/service.js";
+export declare function registerGrimoireTools(server: McpServer, grimoireService: GrimoireService): void;

package/dist/mcp/grimoireTools.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { jsonResult } from "./jsonResult.js";
+const secretTypeSchema = z.enum([
+    "casper_private_key_ref",
+    "x402_client_key_ref",
+    "api_key",
+    "webhook_secret"
+]);
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+const nonEmptyStringSchema = z.string().trim().min(1);
+const urlSchema = z.string().trim().url();
+const decimalAmountSchema = z
+    .string()
+    .trim()
+    .regex(/^\d+(\.\d+)?$/, "Expected a non-negative decimal amount");
+export function registerGrimoireTools(server, grimoireService) {
+    server.registerTool("grimoire.secret.put", {
+        title: "Store Secret",
+        description: "Encrypt and store a scoped Mr Mainspring secret. The plaintext is never returned.",
+        inputSchema: {
+            agent_id: nonEmptyStringSchema,
+            name: nonEmptyStringSchema,
+            type: secretTypeSchema,
+            value: nonEmptyStringSchema,
+            scopes: z.array(nonEmptyStringSchema).min(1)
+        }
+    }, async (input) => {
+        const secret = await grimoireService.putSecret(input);
+        return jsonResult({
+            status: "stored",
+            secret
+        });
+    });
+    server.registerTool("grimoire.secret.list", {
+        title: "List Secrets",
+        description: "List Mr Mainspring secret metadata for an agent without exposing secret values.",
+        inputSchema: {
+            agent_id: nonEmptyStringSchema
+        }
+    }, async ({ agent_id }) => {
+        const secrets = await grimoireService.listSecrets(agent_id);
+        return jsonResult({
+            agent_id,
+            count: secrets.length,
+            secrets
+        });
+    });
+    server.registerTool("grimoire.policy.set", {
+        title: "Set Policy",
+        description: "Create or update a Mr Mainspring spending/access policy commitment.",
+        inputSchema: {
+            agent_id: nonEmptyStringSchema,
+            policy_id: nonEmptyStringSchema,
+            enabled: z.boolean().optional(),
+            allowed_urls: z.array(urlSchema).min(1),
+            allowed_methods: z.array(nonEmptyStringSchema).min(1),
+            allowed_asset: jsonObjectSchema,
+            max_amount_per_call: decimalAmountSchema,
+            max_amount_per_period: decimalAmountSchema,
+            period_seconds: z.number().int().positive(),
+            secret_scopes: z.array(nonEmptyStringSchema).default([])
+        }
+    }, async (input) => {
+        const policy = await grimoireService.setPolicy(input);
+        return jsonResult({
+            status: "stored",
+            policy
+        });
+    });
+    server.registerTool("grimoire.policy.get", {
+        title: "Get Policy",
+        description: "Read one Mr Mainspring policy and current local spend metadata.",
+        inputSchema: {
+            agent_id: nonEmptyStringSchema,
+            policy_id: nonEmptyStringSchema
+        }
+    }, async ({ agent_id, policy_id }) => {
+        const policy = await grimoireService.getPolicy(agent_id, policy_id);
+        if (!policy) {
+            return jsonResult({
+                found: false,
+                agent_id,
+                policy_id
+            });
+        }
+        return jsonResult({
+            found: true,
+            policy
+        });
+    });
+}

package/dist/mcp/jsonResult.d.ts

@@ -0,0 +1,2 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function jsonResult(data: unknown): CallToolResult;

package/dist/mcp/jsonResult.js

@@ -0,0 +1,10 @@
+export function jsonResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2)
+            }
+        ]
+    };
+}

package/dist/mcp/memoryTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { MemoryService } from "../memory/service.js";
+export declare function registerMemoryTools(server: McpServer, memoryService: MemoryService): void;