@socialproof/memory-mcp 0.1.1

package/dist/index.js

@@ -0,0 +1,20 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { runCliMain } from "./cli.js";
+export { runCli, runCliMain } from "./cli.js";
+export { DEFAULT_CREDENTIALS_PATH, loadCredentials, parseCredentials, } from "./credentials.js";
+export { McpRuntimeError, formatStartupError, redactSensitiveText, toStructuredMcpError, } from "./errors.js";
+export { createMemoryMcpServer } from "./server.js";
+export { createHostedMcpHttpServer } from "./hosted.js";
+export { authenticateHostedRequest, OAuthIntrospectionVerifier, } from "./oauth.js";
+export { SponsoredSocialGateway, } from "./social-gateway.js";
+export { InjectedAgentSigner, KmsSessionAgentSigner, HttpKmsSessionAuthorizer, RemoteKmsSigningProvider, LocalEd25519Signer, createCliSigner, } from "./signers.js";
+export { LocalKeychainAgentProvisioner, } from "./provisioning.js";
+export { createToolCatalog, executeTool, TOOL_OAUTH_SCOPES, } from "./tools.js";
+export { MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_SERVER_NAME, } from "./version.js";
+function isMainModule() {
+    const entrypoint = process.argv[1];
+    return Boolean(entrypoint) && path.resolve(entrypoint) === fileURLToPath(import.meta.url);
+}
+if (isMainModule())
+    runCliMain();

package/dist/oauth.d.ts

@@ -0,0 +1,25 @@
+import type { IncomingMessage } from "node:http";
+import type { OAuthTokenVerifier } from "@modelcontextprotocol/sdk/server/auth/provider.js";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+export interface OAuthIntrospectionVerifierOptions {
+    introspectionUrl: string;
+    clientId: string;
+    clientSecret: string;
+    resourceUrl: string;
+    fetch?: typeof globalThis.fetch;
+}
+/** RFC 7662 verifier. Introspection on every MCP request makes token revocation immediate. */
+export declare class OAuthIntrospectionVerifier implements OAuthTokenVerifier {
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly resource;
+    constructor(options: OAuthIntrospectionVerifierOptions);
+    verifyAccessToken(token: string): Promise<AuthInfo>;
+}
+export interface HostedMcpPrincipal {
+    auth: AuthInfo;
+    accountId: string;
+    agentObjectId: string;
+    signerSessionId: string;
+}
+export declare function authenticateHostedRequest(request: IncomingMessage, verifier: OAuthTokenVerifier, resource: URL): Promise<HostedMcpPrincipal>;

package/dist/oauth.js

@@ -0,0 +1,104 @@
+import { McpRuntimeError } from "./errors.js";
+/** RFC 7662 verifier. Introspection on every MCP request makes token revocation immediate. */
+export class OAuthIntrospectionVerifier {
+    options;
+    fetchImpl;
+    resource;
+    constructor(options) {
+        this.options = options;
+        if (!options.introspectionUrl.startsWith("https://") && !options.introspectionUrl.startsWith("http://localhost")) {
+            throw new McpRuntimeError("INVALID_CONFIGURATION", "OAuth introspection must use HTTPS.");
+        }
+        if (!options.clientId || !options.clientSecret) {
+            throw new McpRuntimeError("INVALID_CONFIGURATION", "OAuth introspection client credentials are required.");
+        }
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.resource = new URL(options.resourceUrl);
+    }
+    async verifyAccessToken(token) {
+        const form = new URLSearchParams({ token, token_type_hint: "access_token" });
+        const basic = Buffer.from(`${this.options.clientId}:${this.options.clientSecret}`).toString("base64");
+        const response = await this.fetchImpl(this.options.introspectionUrl, {
+            method: "POST",
+            headers: {
+                authorization: `Basic ${basic}`,
+                "content-type": "application/x-www-form-urlencoded",
+                accept: "application/json",
+            },
+            body: form,
+        });
+        if (!response.ok) {
+            throw new McpRuntimeError("AUTHENTICATION_FAILED", "OAuth token introspection failed.");
+        }
+        const result = await response.json();
+        if (result.active !== true) {
+            throw new McpRuntimeError("AUTHENTICATION_FAILED", "OAuth token is inactive or revoked.");
+        }
+        const audience = Array.isArray(result.aud) ? result.aud : [result.aud];
+        const expected = normalizeResource(this.resource);
+        if (!audience.some((value) => typeof value === "string" && safeNormalizedResource(value) === expected)) {
+            throw new McpRuntimeError("AUTHENTICATION_FAILED", "OAuth token audience is invalid.");
+        }
+        const scopes = typeof result.scope === "string" ? result.scope.split(/\s+/).filter(Boolean) : [];
+        const clientId = typeof result.client_id === "string" ? result.client_id : "";
+        if (!clientId) {
+            throw new McpRuntimeError("AUTHENTICATION_FAILED", "OAuth token client_id is missing.");
+        }
+        return {
+            token,
+            clientId,
+            scopes,
+            expiresAt: typeof result.exp === "number" ? result.exp : undefined,
+            resource: this.resource,
+            extra: {
+                accountId: result.account_id,
+                agentObjectId: result.agent_object_id,
+                signerSessionId: result.signer_session_id,
+            },
+        };
+    }
+}
+function safeNormalizedResource(value) {
+    try {
+        return normalizeResource(new URL(value));
+    }
+    catch {
+        return "";
+    }
+}
+function extraString(auth, name) {
+    const value = auth.extra?.[name];
+    if (typeof value !== "string" || !value.trim()) {
+        throw new McpRuntimeError("AUTHENTICATION_FAILED", `OAuth token is missing ${name}.`);
+    }
+    return value;
+}
+export async function authenticateHostedRequest(request, verifier, resource) {
+    const header = request.headers.authorization;
+    const match = typeof header === "string" ? /^Bearer ([A-Za-z0-9._~+\/-]+=*)$/.exec(header) : null;
+    if (!match) {
+        throw new McpRuntimeError("AUTHENTICATION_FAILED", "A Bearer access token is required.");
+    }
+    const auth = await verifier.verifyAccessToken(match[1]);
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (auth.expiresAt !== undefined && auth.expiresAt <= nowSeconds) {
+        throw new McpRuntimeError("AUTHENTICATION_FAILED", "The OAuth access token expired.");
+    }
+    if (!auth.scopes.includes("mcp:connect")) {
+        throw new McpRuntimeError("CAPABILITY_DENIED", "The OAuth token lacks mcp:connect.");
+    }
+    if (!auth.resource || normalizeResource(auth.resource) !== normalizeResource(resource)) {
+        throw new McpRuntimeError("AUTHENTICATION_FAILED", "The OAuth token audience does not match this MCP resource.");
+    }
+    return {
+        auth,
+        accountId: extraString(auth, "accountId"),
+        agentObjectId: extraString(auth, "agentObjectId"),
+        signerSessionId: extraString(auth, "signerSessionId"),
+    };
+}
+function normalizeResource(value) {
+    const copy = new URL(value);
+    copy.hash = "";
+    return copy.toString().replace(/\/$/, "");
+}

package/dist/provisioning.d.ts

@@ -0,0 +1,19 @@
+export interface ProvisionedAgentSigner {
+    publicKeyHex: string;
+    derivedAddress: string;
+    signer: {
+        type: "keychain" | "kms-session";
+        keyId: string;
+        service?: string;
+        account?: string;
+    };
+}
+export interface AgentSignerProvisioner {
+    provision(label: string): Promise<ProvisionedAgentSigner>;
+}
+/** Generates an Ed25519 seed and stores it in macOS Keychain without returning it. */
+export declare class LocalKeychainAgentProvisioner implements AgentSignerProvisioner {
+    private readonly service;
+    constructor(service?: string);
+    provision(label: string): Promise<ProvisionedAgentSigner>;
+}

package/dist/provisioning.js

@@ -0,0 +1,70 @@
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { McpRuntimeError } from "./errors.js";
+import { LocalEd25519Signer } from "./signers.js";
+/** Generates an Ed25519 seed and stores it in macOS Keychain without returning it. */
+export class LocalKeychainAgentProvisioner {
+    service;
+    constructor(service = "network.mysocial.memory-agent") {
+        this.service = service;
+    }
+    async provision(label) {
+        if (process.platform !== "darwin") {
+            throw new McpRuntimeError("SIGNER_UNAVAILABLE", "Local agent provisioning requires macOS Keychain; hosted runtimes must inject a KMS provisioner.");
+        }
+        const account = label.trim();
+        if (!/^[A-Za-z0-9._-]{1,64}$/.test(account)) {
+            throw new McpRuntimeError("INVALID_ARGUMENT", "Agent signer label must contain 1-64 letters, numbers, dots, underscores, or hyphens.");
+        }
+        try {
+            execFileSync("/usr/bin/security", [
+                "find-generic-password",
+                "-s",
+                this.service,
+                "-a",
+                account,
+            ], { stdio: "ignore" });
+            throw new McpRuntimeError("CONFLICT", "A Keychain signer already exists for this label; choose a new label.");
+        }
+        catch (error) {
+            if (error instanceof McpRuntimeError)
+                throw error;
+        }
+        const secret = Uint8Array.from(randomBytes(32));
+        const signer = new LocalEd25519Signer("keychain", `${this.service}:${account}`, secret);
+        try {
+            const [publicKey, derivedAddress] = await Promise.all([
+                signer.getPublicKey(),
+                signer.getMySoAddress(),
+            ]);
+            execFileSync("/usr/bin/security", [
+                "add-generic-password",
+                "-s",
+                this.service,
+                "-a",
+                account,
+                "-w",
+                Buffer.from(secret).toString("hex"),
+            ], { stdio: ["ignore", "ignore", "ignore"] });
+            return {
+                publicKeyHex: Buffer.from(publicKey).toString("hex"),
+                derivedAddress,
+                signer: {
+                    type: "keychain",
+                    keyId: `${this.service}:${account}`,
+                    service: this.service,
+                    account,
+                },
+            };
+        }
+        catch (error) {
+            throw new McpRuntimeError("SIGNER_UNAVAILABLE", "Unable to provision the agent signer.", {
+                cause: error,
+            });
+        }
+        finally {
+            signer.destroy();
+            secret.fill(0);
+        }
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type ToolDependencies } from "./tools.js";
+export declare function createMemoryMcpServer(dependencies: ToolDependencies): Server;

package/dist/server.js

@@ -0,0 +1,28 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { MCP_PACKAGE_VERSION, MCP_SERVER_NAME } from "./version.js";
+import { createToolCatalog, executeTool } from "./tools.js";
+export function createMemoryMcpServer(dependencies) {
+    const socialToolNames = dependencies.social?.supportedToolNames ?? [];
+    const server = new Server({ name: MCP_SERVER_NAME, version: MCP_PACKAGE_VERSION }, {
+        capabilities: { tools: {} },
+        instructions: "Use memory tools for encrypted recall and registered social tools for agent-authorized actions. Tool annotations are descriptive; server and chain policy remain authoritative.",
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: createToolCatalog(socialToolNames, dependencies.oauthScopes),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const name = request.params.name;
+        const args = (request.params.arguments ?? {});
+        const envelope = await executeTool(name, args, dependencies);
+        const summary = envelope.ok
+            ? `${name} completed successfully.`
+            : `${envelope.error.code}: ${envelope.error.message}`;
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: envelope,
+            ...(envelope.ok ? {} : { isError: true }),
+        };
+    });
+    return server;
+}

package/dist/signers.d.ts

@@ -0,0 +1,119 @@
+export interface AgentSigner {
+    readonly kind: "keychain" | "development-file" | "injected" | "kms-session";
+    readonly keyId: string;
+    getPublicKey(): Promise<Uint8Array>;
+    sign(message: Uint8Array): Promise<Uint8Array>;
+    getMySoAddress(): Promise<string>;
+    signTransaction(transactionBytes: Uint8Array): Promise<string>;
+    destroy(): void;
+}
+export type KmsSigningOperation = "http-auth" | "transaction";
+export interface KmsSessionPolicy {
+    sessionId: string;
+    keyId: string;
+    accountId: string;
+    agentObjectId: string;
+    expectedAddress: string;
+    expiresAtMs: number;
+}
+/** Vendor adapter; implementations may use GCP KMS, an HSM, or a TEE signer. */
+export interface KmsSigningProvider {
+    getPublicKey(keyId: string): Promise<Uint8Array>;
+    signEd25519(keyId: string, message: Uint8Array): Promise<Uint8Array>;
+    signTransaction(keyId: string, transactionBytes: Uint8Array): Promise<string>;
+}
+/** Must check the hosted session and current on-chain agent state, not a stale login cache. */
+export interface KmsSessionAuthorizer {
+    assertActive(policy: Readonly<KmsSessionPolicy>, operation: KmsSigningOperation): Promise<void>;
+}
+export declare class KmsSessionAgentSigner implements AgentSigner {
+    private readonly policy;
+    private readonly provider;
+    private readonly authorizer;
+    readonly kind: "kms-session";
+    readonly keyId: string;
+    private active;
+    constructor(policy: Readonly<KmsSessionPolicy>, provider: KmsSigningProvider, authorizer: KmsSessionAuthorizer);
+    getPublicKey(): Promise<Uint8Array>;
+    sign(message: Uint8Array): Promise<Uint8Array>;
+    getMySoAddress(): Promise<string>;
+    signTransaction(transactionBytes: Uint8Array): Promise<string>;
+    destroy(): void;
+    private guard;
+}
+export interface RemoteKmsClientOptions {
+    baseUrl: string;
+    bearerToken(): string | Promise<string>;
+    fetch?: typeof globalThis.fetch;
+}
+/** HTTP adapter for a private KMS/HSM signing service. No private key is returned. */
+export declare class RemoteKmsSigningProvider implements KmsSigningProvider {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: RemoteKmsClientOptions);
+    getPublicKey(keyId: string): Promise<Uint8Array>;
+    signEd25519(keyId: string, message: Uint8Array): Promise<Uint8Array>;
+    signTransaction(keyId: string, transactionBytes: Uint8Array): Promise<string>;
+    private request;
+}
+export declare class HttpKmsSessionAuthorizer implements KmsSessionAuthorizer {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: RemoteKmsClientOptions);
+    assertActive(policy: Readonly<KmsSessionPolicy>, operation: KmsSigningOperation): Promise<void>;
+}
+export interface LocalSecretAgentSigner extends AgentSigner {
+    /**
+     * Makes a temporary in-process copy available to a local SDK adapter.
+     * The copy is zeroed immediately after the callback resolves and must never
+     * be serialized, logged, or attached to a request.
+     */
+    withLocalSecret<T>(callback: (secretKey: Uint8Array) => T | Promise<T>): Promise<T>;
+}
+export interface KeychainSignerReference {
+    type: "keychain";
+    service: string;
+    account: string;
+}
+export interface DevelopmentFileSignerReference {
+    type: "development-file";
+    path: string;
+}
+export type CliSignerReference = KeychainSignerReference | DevelopmentFileSignerReference;
+export interface InjectedSignerCallbacks {
+    keyId: string;
+    getPublicKey: () => Promise<Uint8Array> | Uint8Array;
+    sign: (message: Uint8Array) => Promise<Uint8Array> | Uint8Array;
+    getMySoAddress: () => Promise<string> | string;
+    signTransaction: (transactionBytes: Uint8Array) => Promise<string> | string;
+    destroy?: () => void;
+}
+export declare class LocalEd25519Signer implements LocalSecretAgentSigner {
+    readonly kind: "keychain" | "development-file";
+    readonly keyId: string;
+    private secretKey;
+    private privateKey;
+    private publicKey;
+    constructor(kind: "keychain" | "development-file", keyId: string, secretKey: Uint8Array);
+    getPublicKey(): Promise<Uint8Array>;
+    sign(message: Uint8Array): Promise<Uint8Array>;
+    withLocalSecret<T>(callback: (secretKey: Uint8Array) => T | Promise<T>): Promise<T>;
+    getMySoAddress(): Promise<string>;
+    signTransaction(transactionBytes: Uint8Array): Promise<string>;
+    destroy(): void;
+    private assertActive;
+}
+export declare class InjectedAgentSigner implements AgentSigner {
+    readonly kind: "injected";
+    readonly keyId: string;
+    private readonly callbacks;
+    constructor(callbacks: InjectedSignerCallbacks);
+    getPublicKey(): Promise<Uint8Array>;
+    sign(message: Uint8Array): Promise<Uint8Array>;
+    getMySoAddress(): Promise<string>;
+    signTransaction(transactionBytes: Uint8Array): Promise<string>;
+    destroy(): void;
+}
+export declare function createCliSigner(reference: CliSignerReference): LocalSecretAgentSigner;