@dfm-fi/agent 0.2.1896 → 0.2.1916

package/dist/app-wallet-owner.d.ts

@@ -20,6 +20,10 @@ export interface OwnerKey {
     created: boolean;
     sign(payload: string): string;
 }
+export declare const lstatOrNull: (p: string) => import("node:fs").Stats | null;
+export declare const myUid: () => number | undefined;
+/** The owner-key directory rules, shared by every secret this MCP writes (identity keypair too). */
+export declare function assertSafeDir(dir: string): void;
 /** Load the owner key at `path`, or create it (0600) when absent. */
 export declare function loadOrCreateOwnerKey(path?: string): OwnerKey;
 /** RFC 8785 (JCS) for the JSON shapes Privy signs: sorted keys, ES string/number serialization. */

package/dist/app-wallet-owner.js

@@ -45,7 +45,7 @@ export function signerPins() {
 export function ownerKeyPath() {
     return process.env.DFM_APP_WALLET_OWNER_KEY_PATH?.trim() || DEFAULT_OWNER_KEY_PATH;
 }
-const lstatOrNull = (p) => {
+export const lstatOrNull = (p) => {
     try {
         return lstatSync(p);
     }
@@ -55,8 +55,9 @@ const lstatOrNull = (p) => {
         throw e;
     }
 };
-const myUid = () => (typeof process.getuid === 'function' ? process.getuid() : undefined);
-function assertSafeDir(dir) {
+export const myUid = () => (typeof process.getuid === 'function' ? process.getuid() : undefined);
+/** The owner-key directory rules, shared by every secret this MCP writes (identity keypair too). */
+export function assertSafeDir(dir) {
     let st = lstatOrNull(dir);
     if (!st) {
         if (resolve(dir) !== resolve(DEFAULT_OWNER_KEY_DIR))

package/dist/config.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Zero-config convenience: if `DFM_AGENT_KEYPAIR_PATH` is unset, fall back to the
+ * conventional `~/.config/dfm/agent-wallet.json` IF it exists. So a plugin user
+ * can just drop their throwaway test keypair there and skip the env var entirely.
+ * Returns undefined when neither is present (write tools then error clearly).
+ */
+export declare const DEFAULT_KEYPAIR_PATH: string;
 export interface AgentConfig {
     /** DFM v2 backend API base, INCLUDING the `/api/v2` prefix. */
     apiUrl: string;

package/dist/config.js

@@ -20,7 +20,7 @@ import { join } from 'node:path';
  * can just drop their throwaway test keypair there and skip the env var entirely.
  * Returns undefined when neither is present (write tools then error clearly).
  */
-const DEFAULT_KEYPAIR_PATH = join(homedir(), '.config', 'dfm', 'agent-wallet.json');
+export const DEFAULT_KEYPAIR_PATH = join(homedir(), '.config', 'dfm', 'agent-wallet.json');
 function resolveKeypairPath() {
     const explicit = process.env.DFM_AGENT_KEYPAIR_PATH;
     if (explicit && explicit.trim().length > 0)

package/dist/mcp-server.js

@@ -67,11 +67,16 @@ import { isKeylessMode, executeAppWalletWrite, KEYLESS_SETUP_HINT, } from './key
 import { runAcceptAdminTransfer, runUpdateVaultPolicy, reconcileKeylessUpdateVaultPolicy, } from './manager-flow.js';
 import { submitSignedTx } from './submit.js';
 import { DEFAULT_OWNER_KEY_PATH, ownerKeyPath, policyUpdateNotice, runCreateAppWallet } from './app-wallet-owner.js';
-import { signBase64Transaction } from './signing.js';
+import { getTestWalletPubkey, signBase64Transaction } from './signing.js';
+import { ONBOARDING_ORDER, avatarPath, ensureIdentityWallet, loadAvatar, mintAndStoreKey, runOnboard } from './onboarding.js';
+import { makeIdentityGuard, makeKeyOwnerLookup, makeSessionFetch, onboardingApi } from './onboarding-api.js';
 import { buildWalletIdentity, resolveZapStatusWallet, withActingWalletAlias, withPortfolioWalletAlias, } from './wallet-identity.js';
 const config = loadConfig();
 const session = new SiwsSession(config);
 const api = new DfmApiClient(config, session);
+// S16/S17/S19: with DFM_API_KEY set, the key owner (asked over the KEY lane) must BE the SIWS wallet.
+const assertSameIdentity = makeIdentityGuard(makeKeyOwnerLookup(config), () => session.walletAddress);
+const onboardApi = onboardingApi(makeSessionFetch(config, session, fetch, assertSameIdentity));
 // Read the real published version from package.json so serverInfo matches the
 // npm `0.2.<commitcount>` instead of a hardcoded string that silently drifts.
 const PKG_VERSION = (() => {
@@ -378,8 +383,8 @@ server.registerTool('app_wallet', {
         if (!grant?.operatingWalletAddress) {
             return text({
                 hasAppWallet: false,
-                nextStep: `No app wallet yet. Create one at ${SETUP_URL} — "Create app wallet". ` +
-                    'No signature needed; nothing goes onchain.',
+                nextStep: `No app wallet yet. Headless agent: ${ONBOARDING_ORDER} (or just run onboard). ` +
+                    `In a browser: sign in at ${SETUP_URL}.`,
             });
         }
         // Best-effort: an older API without this route must still report the
@@ -523,12 +528,116 @@ server.registerTool('create_app_wallet', {
     annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
 }, async () => {
     try {
+        await assertSameIdentity();
         return text(await runCreateAppWallet(api, ownerKeyPath()));
     }
     catch (e) {
         return errText(`create_app_wallet failed: ${e.message}`);
     }
 });
+server.registerTool('create_identity_wallet', {
+    title: 'Identity wallet (headless sign-in key)',
+    description: "The Solana keypair this agent signs in to DFM with (SIWS). If DFM_AGENT_KEYPAIR_PATH / DFM_AGENT_KEYPAIR_JSON " +
+        'is set or ~/.config/dfm/agent-wallet.json exists it is REUSED (never a second one); otherwise one is created ' +
+        'there once (0600, never overwritten) and used immediately, no restart. Returns only the public key. Step 1 of: ' +
+        ONBOARDING_ORDER + '. Moves no funds.',
+    inputSchema: {},
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false },
+}, async () => {
+    try {
+        return text(ensureIdentityWallet(config, getTestWalletPubkey));
+    }
+    catch (e) {
+        return errText(`create_identity_wallet failed: ${e.message}`);
+    }
+});
+server.registerTool('set_profile', {
+    title: 'Set my DFM profile',
+    description: 'Set this agent\'s public DFM profile: displayName (required), optional @username and bio. The avatar is the ' +
+        'image the OPERATOR put at DFM_AGENT_AVATAR_PATH or ~/.config/dfm/avatar.{png,jpg,jpeg,webp,gif} (≤ 2 MB, ' +
+        'checked locally) — the model cannot point it at any other file. A chosen name AND an avatar are required ' +
+        'before create_app_wallet. Needs the SIWS sign-in (identity wallet). Moves no funds.',
+    inputSchema: {
+        displayName: z.string().min(1).max(32),
+        username: z.string().regex(/^@?[a-zA-Z0-9_]{3,20}$/).optional().describe('@handle, 3-20 chars a-z 0-9 _'),
+        bio: z.string().max(160).optional(),
+        uploadAvatar: z.boolean().optional().describe('default true: upload the operator-provided avatar image if present'),
+    },
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+}, async ({ displayName, username, bio, uploadAvatar }) => {
+    try {
+        const profile = await onboardApi.updateProfile({
+            displayName,
+            ...(username ? { username: username.replace(/^@/, '') } : {}),
+            ...(bio !== undefined ? { bio } : {}),
+        });
+        let avatar = { uploaded: false };
+        const path = uploadAvatar === false ? null : avatarPath();
+        if (path) {
+            const img = loadAvatar(path);
+            const res = await onboardApi.uploadAvatar(img.bytes, img.filename, img.mime);
+            avatar = { uploaded: true, effectiveAvatarUri: res.effectiveAvatarUri ?? null };
+        }
+        else if (uploadAvatar !== false) {
+            avatar = { uploaded: false, hint: 'No avatar file. Put an image at ~/.config/dfm/avatar.png (or set DFM_AGENT_AVATAR_PATH) and run set_profile again.' };
+        }
+        return text({ profile: { displayName: profile.displayName, username: profile.username, bio: profile.bio }, avatar });
+    }
+    catch (e) {
+        return errText(`set_profile failed: ${e.message}`);
+    }
+});
+server.registerTool('create_api_key', {
+    title: 'Mint a dfm_ API key',
+    description: 'Mint a dfm_ API key for this agent\'s owner (SIWS session only). READ-ONLY: write keys and write caps are ' +
+        'refused unless the operator set DFM_ALLOW_WRITE_KEY_MINT=1. Expires in 30 days by default (max 90). The key ' +
+        'is written to ~/.config/dfm/api-keys/<name>-<prefix>.key (0600) and NEVER returned to the chat; only its ' +
+        'prefix and path are. Optional last step of: ' + ONBOARDING_ORDER + '.',
+    inputSchema: {
+        name: z.string().min(1).max(80),
+        readOnly: z.boolean().optional().describe('default true'),
+        perOpNotionalUsdc: z.number().int().min(0).optional(),
+        dailyNotionalUsdc: z.number().int().min(0).optional(),
+        allowedOps: z.array(z.string().max(64)).max(32).optional(),
+        destinationWhitelist: z.array(z.string().max(64)).max(32).optional(),
+        allowedPrograms: z.array(z.string().max(64)).max(32).optional(),
+        allowArbitraryPrograms: z.boolean().optional(),
+        expiresAt: z.string().datetime().optional().describe('ISO-8601, in the future'),
+    },
+    annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
+}, async (input) => {
+    try {
+        return text(await mintAndStoreKey(input, onboardApi));
+    }
+    catch (e) {
+        return errText(`create_api_key failed: ${e.message}`);
+    }
+});
+server.registerTool('onboard', {
+    title: 'Onboard this agent (headless)',
+    description: 'Run the headless onboarding in order — ' + ONBOARDING_ORDER + ' — and stop at the first step that needs the ' +
+        'operator, saying which. Creates the identity wallet and the app wallet if missing; never mints an API key. ' +
+        'Moves no funds.',
+    inputSchema: {},
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+}, async () => {
+    try {
+        return text(await runOnboard({
+            identity: () => ensureIdentityWallet(config, getTestWalletPubkey),
+            ...(process.env.DFM_API_KEY?.trim()
+                ? { assertSameIdentity }
+                : {}),
+            getProfile: () => onboardApi.getProfile(),
+            createAppWallet: async () => {
+                await assertSameIdentity();
+                return runCreateAppWallet(api, ownerKeyPath());
+            },
+        }));
+    }
+    catch (e) {
+        return errText(`onboard failed: ${e.message}`);
+    }
+});
 server.registerTool('xp_status', {
     title: 'XP',
     description: "The user's XP (total and by kind: deposit, launch, profile, referral) and the top of the XP leaderboard.",
@@ -568,8 +677,8 @@ server.registerTool('whoami', {
             ...(identity.actingWallet
                 ? {}
                 : {
-                    setupHint: 'No active app-wallet signer. Call app_wallet for its status and next step; ' +
-                        'an external keypair cannot sign fund operations.',
+                    setupHint: `No active app-wallet signer. Onboard in this order: ${ONBOARDING_ORDER} (or run onboard). ` +
+                        'An external keypair cannot sign fund operations.',
                 }),
             ...policyUpdateNotice(op),
             apiUrl: config.apiUrl,

package/dist/onboarding-api.d.ts

@@ -0,0 +1,42 @@
+import type { AgentConfig } from './config.js';
+import type { SiwsSession } from './session.js';
+export type SessionFetch = (path: string, init: RequestInit & {
+    json?: unknown;
+}) => Promise<Record<string, unknown>>;
+/**
+ * Review S16/S17: when DFM_API_KEY is set, the key's owner and the SIWS
+ * keypair must be the SAME wallet, or the session lane would act as a
+ * different identity than the rest of the MCP. The owner comes from
+ * `GET /agent/operating/embedded/agent-wallet/owner` over the KEY lane (answers for any key, read-only included, and
+ * always carries `wallet`). FAIL CLOSED: an error or an unknown owner refuses.
+ * A passing check is cached for the process; a failing one is retried.
+ */
+export declare function makeIdentityGuard(keyOwner: () => Promise<{
+    wallet?: unknown;
+} | null | undefined>, siwsWallet: () => string, hasApiKey?: () => boolean): () => Promise<void>;
+/**
+ * The identity guard's owner lookup, over the KEY lane on purpose (review
+ * S19): `X-DFM-Key`, never the SIWS bearer, against the route that answers
+ * for any key (read-only included) even when the owner has no app wallet.
+ * Errors throw — the guard turns them into a refusal (fail closed).
+ */
+export declare function makeKeyOwnerLookup(config: Pick<AgentConfig, 'apiUrl'>, apiKey?: () => string | undefined, doFetch?: typeof fetch): () => Promise<{
+    wallet?: unknown;
+}>;
+export declare function makeSessionFetch(config: Pick<AgentConfig, 'apiUrl'>, session: Pick<SiwsSession, 'getAccessToken'>, doFetch?: typeof fetch, beforeEach?: () => Promise<void>): SessionFetch;
+export declare function onboardingApi(call: SessionFetch): {
+    getProfile: () => Promise<{
+        wallet?: string;
+        displayName?: string;
+        effectiveAvatarUri?: string | null;
+    }>;
+    updateProfile: (dto: {
+        displayName: string;
+        username?: string;
+        bio?: string;
+    }) => Promise<Record<string, unknown>>;
+    uploadAvatar: (bytes: Buffer, filename: string, mime: string) => Promise<Record<string, unknown>>;
+    createApiKey: (body: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    revokeApiKey: (id: string) => Promise<Record<string, unknown>>;
+};
+//# sourceMappingURL=onboarding-api.d.ts.map

package/dist/onboarding-api.js

@@ -0,0 +1,102 @@
+/**
+ * The onboarding calls (profile, avatar, API key), always over the SIWS
+ * session — never DFM_API_KEY: a key cannot mint a key (`/agent/keys` is
+ * session-only) and a read-only key cannot write a profile. Kept beside
+ * `DfmApiClient` rather than inside it; same contract as its SIWS lane:
+ * Bearer token, one transparent re-auth on 401, an `X-Idempotency-Key` on
+ * every write, the API's error text surfaced verbatim.
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * Review S16/S17: when DFM_API_KEY is set, the key's owner and the SIWS
+ * keypair must be the SAME wallet, or the session lane would act as a
+ * different identity than the rest of the MCP. The owner comes from
+ * `GET /agent/operating/embedded/agent-wallet/owner` over the KEY lane (answers for any key, read-only included, and
+ * always carries `wallet`). FAIL CLOSED: an error or an unknown owner refuses.
+ * A passing check is cached for the process; a failing one is retried.
+ */
+export function makeIdentityGuard(keyOwner, siwsWallet, hasApiKey = () => Boolean(process.env.DFM_API_KEY?.trim())) {
+    let ok = null;
+    return () => {
+        if (!hasApiKey())
+            return Promise.resolve();
+        ok ??= (async () => {
+            let owner;
+            try {
+                owner = (await keyOwner())?.wallet;
+            }
+            catch (e) {
+                throw new Error(`cannot verify whose DFM_API_KEY this is (${e.message}); refusing to act`);
+            }
+            if (typeof owner !== 'string' || !owner)
+                throw new Error('cannot verify whose DFM_API_KEY this is; refusing to act');
+            const me = siwsWallet();
+            if (owner !== me) {
+                throw new Error(`DFM_API_KEY belongs to ${owner}, not this keypair (${me}); use one identity (unset one of them)`);
+            }
+        })().catch((e) => {
+            ok = null;
+            throw e;
+        });
+        return ok;
+    };
+}
+/**
+ * The identity guard's owner lookup, over the KEY lane on purpose (review
+ * S19): `X-DFM-Key`, never the SIWS bearer, against the route that answers
+ * for any key (read-only included) even when the owner has no app wallet.
+ * Errors throw — the guard turns them into a refusal (fail closed).
+ */
+export function makeKeyOwnerLookup(config, apiKey = () => process.env.DFM_API_KEY?.trim(), doFetch = fetch) {
+    return async () => {
+        const key = apiKey();
+        if (!key)
+            throw new Error('no DFM_API_KEY to look up');
+        const res = await doFetch(`${config.apiUrl}/agent/operating/embedded/agent-wallet/owner`, {
+            method: 'GET',
+            headers: { 'X-DFM-Key': key },
+        });
+        if (!res.ok)
+            throw new Error(`owner lookup answered ${res.status}`);
+        return (await res.json());
+    };
+}
+export function makeSessionFetch(config, session, doFetch = fetch, beforeEach = async () => undefined) {
+    return async (path, { json, ...init }) => {
+        await beforeEach();
+        const method = (init.method ?? 'GET').toUpperCase();
+        const idem = method === 'GET' ? {} : { 'X-Idempotency-Key': randomUUID() };
+        const send = (token) => doFetch(`${config.apiUrl}${path}`, {
+            ...init,
+            ...(json !== undefined ? { body: JSON.stringify(json) } : {}),
+            headers: {
+                ...(json !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                ...idem,
+                Authorization: `Bearer ${token}`,
+            },
+        });
+        let res = await send(await session.getAccessToken());
+        if (res.status === 401)
+            res = await send(await session.getAccessToken(true));
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`DFM API ${res.status} on ${path}: ${body.slice(0, 400)}`);
+        }
+        const text = await res.text();
+        return (text ? JSON.parse(text) : {});
+    };
+}
+export function onboardingApi(call) {
+    return {
+        getProfile: () => call('/profile', { method: 'GET' }),
+        updateProfile: (dto) => call('/profile', { method: 'PUT', json: dto }),
+        uploadAvatar: (bytes, filename, mime) => {
+            const form = new FormData();
+            form.append('file', new Blob([new Uint8Array(bytes)], { type: mime }), filename);
+            return call('/profile/avatar', { method: 'POST', body: form });
+        },
+        createApiKey: (body) => call('/agent/keys', { method: 'POST', json: body }),
+        revokeApiKey: (id) => call(`/agent/keys/${encodeURIComponent(id)}`, { method: 'DELETE' }),
+    };
+}
+//# sourceMappingURL=onboarding-api.js.map

package/dist/onboarding.d.ts

@@ -0,0 +1,93 @@
+import { type AgentConfig } from './config.js';
+export declare const ONBOARDING_ORDER = "create_identity_wallet \u2192 SIWS login (automatic) \u2192 set_profile {displayName, avatar} \u2192 create_app_wallet \u2192 create_api_key (optional)";
+export interface IdentityResult {
+    status: 'reused' | 'created';
+    publicKey: string;
+    source: 'DFM_AGENT_KEYPAIR_PATH' | 'DFM_AGENT_KEYPAIR_JSON' | 'default-path';
+    note: string;
+}
+/**
+ * Reuse the configured identity keypair, or create ONE at the default path.
+ * Never creates a second: any explicit env or an existing default file wins.
+ * `getPubkey` loads it through the same code SIWS uses (it refuses the
+ * protocol wallet). On create, `config.keypairPath` is pointed at the new file
+ * so the running MCP signs in with it without a restart.
+ */
+export declare function ensureIdentityWallet(config: AgentConfig, getPubkey: (c: AgentConfig) => string, defaultPath?: string): IdentityResult;
+/** A secret file this MCP may READ: regular file, not a symlink, ours, 0600-ish. */
+export declare function assertSafeSecretFile(path: string): void;
+export declare const MAX_AVATAR_BYTES: number;
+/** Where the operator puts the agent's avatar. Null when none is configured / present. */
+export declare function avatarPath(dir?: string): string | null;
+/**
+ * Read the avatar ONLY if it is a real image: allowed extension, not a symlink,
+ * a regular file ≤ 2 MB whose first bytes match that image type. Nothing else
+ * is ever sent (the server re-checks magic bytes too).
+ */
+export declare function loadAvatar(path: string): {
+    bytes: Buffer;
+    filename: string;
+    mime: string;
+};
+/** The API's gate rule (agent-onboarding.ts), mirrored: a chosen name AND an avatar. */
+export declare function profileGap(wallet: string | undefined, profile: {
+    displayName?: string;
+    effectiveAvatarUri?: string | null;
+} | null | undefined): string[];
+export interface CreateKeyInput {
+    name: string;
+    readOnly?: boolean;
+    perOpNotionalUsdc?: number;
+    dailyNotionalUsdc?: number;
+    allowedOps?: string[];
+    destinationWhitelist?: string[];
+    allowedPrograms?: string[];
+    allowArbitraryPrograms?: boolean;
+    expiresAt?: string;
+}
+export declare const DEFAULT_KEY_TTL_MS: number;
+export declare const MAX_KEY_TTL_MS: number;
+/**
+ * The exact `POST /agent/keys` body (CreateKeyDto). Review S12: a model can be
+ * prompt-injected, so the MCP mints READ-ONLY keys only; a write key (or any
+ * write cap) needs the OPERATOR's `DFM_ALLOW_WRITE_KEY_MINT=1`. Every key
+ * expires: default now + 30 days, never more than 90.
+ */
+export declare function buildCreateKeyBody(input: CreateKeyInput, now?: number): Record<string, unknown>;
+export declare const DEFAULT_API_KEYS_DIR: string;
+/** Directory + name checks, run BEFORE minting (review S18): a key is never minted into nowhere. */
+export declare function prepareKeyStore(name: string, dir?: string): {
+    dir: string;
+    safeName: string;
+};
+/**
+ * Write a freshly minted key to `<dir>/<name>-<prefix>.key` (dir 0700, file
+ * 0600, `wx`) and return everything EXCEPT the plaintext: the key never
+ * enters the chat, so a prompt cannot make the agent paste it anywhere.
+ */
+export declare function storeApiKey(name: string, issued: Record<string, unknown>, dir?: string): Record<string, unknown>;
+/**
+ * The whole create_api_key: check the store, mint, store; if storing fails
+ * after the mint, REVOKE the key so no live credential is left unrecorded.
+ */
+export declare function mintAndStoreKey(input: CreateKeyInput, api: {
+    createApiKey(b: Record<string, unknown>): Promise<Record<string, unknown>>;
+    revokeApiKey(id: string): Promise<unknown>;
+}, dir?: string): Promise<Record<string, unknown>>;
+export interface OnboardDeps {
+    identity(): IdentityResult;
+    /** Only when DFM_API_KEY is set: throws unless the key's owner IS the SIWS wallet (fail closed). */
+    assertSameIdentity?(): Promise<void>;
+    getProfile(): Promise<{
+        wallet?: string;
+        displayName?: string;
+        effectiveAvatarUri?: string | null;
+    } | null>;
+    createAppWallet(): Promise<Record<string, unknown>>;
+}
+/**
+ * Run the steps in order and stop at the first one that needs the operator.
+ * Never mints an API key (that grants authority — the agent asks for it explicitly).
+ */
+export declare function runOnboard(deps: OnboardDeps): Promise<Record<string, unknown>>;
+//# sourceMappingURL=onboarding.d.ts.map

package/dist/onboarding.js

@@ -0,0 +1,275 @@
+/**
+ * HEADLESS-AGENT ONBOARDING over MCP (Top, #101, 2026-10-19): identity wallet →
+ * SIWS login → profile (name + avatar) → app wallet → API key, no browser.
+ *
+ * Everything that touches the disk follows the owner-key rules
+ * (`app-wallet-owner.ts`): no symlinks, no foreign uid, no loose perms, the
+ * only directory ever created is `~/.config/dfm`, secrets written once with
+ * `wx`/0600. The MODEL never chooses a path: the identity keypair lives at
+ * `DFM_AGENT_KEYPAIR_PATH` or the default, the avatar at `DFM_AGENT_AVATAR_PATH`
+ * or `~/.config/dfm/avatar.<ext>` — so a prompt cannot make the agent upload or
+ * overwrite an arbitrary file.
+ */
+import { Keypair } from '@solana/web3.js';
+import { closeSync, constants as fsc, fstatSync, mkdirSync, openSync, readSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+import { DEFAULT_OWNER_KEY_DIR, assertSafeDir, lstatOrNull, myUid } from './app-wallet-owner.js';
+import { DEFAULT_KEYPAIR_PATH } from './config.js';
+export const ONBOARDING_ORDER = 'create_identity_wallet → SIWS login (automatic) → set_profile {displayName, avatar} → create_app_wallet → create_api_key (optional)';
+/**
+ * Reuse the configured identity keypair, or create ONE at the default path.
+ * Never creates a second: any explicit env or an existing default file wins.
+ * `getPubkey` loads it through the same code SIWS uses (it refuses the
+ * protocol wallet). On create, `config.keypairPath` is pointed at the new file
+ * so the running MCP signs in with it without a restart.
+ */
+export function ensureIdentityWallet(config, getPubkey, defaultPath = DEFAULT_KEYPAIR_PATH) {
+    const explicit = process.env.DFM_AGENT_KEYPAIR_PATH?.trim();
+    if (explicit) {
+        return { status: 'reused', publicKey: getPubkey(config), source: 'DFM_AGENT_KEYPAIR_PATH', note: 'Reused the identity keypair at DFM_AGENT_KEYPAIR_PATH; nothing was created.' };
+    }
+    if (config.keypairJsonEnvPresent && !config.keypairPath && !lstatOrNull(defaultPath)) {
+        return { status: 'reused', publicKey: getPubkey(config), source: 'DFM_AGENT_KEYPAIR_JSON', note: 'Reused the identity keypair from DFM_AGENT_KEYPAIR_JSON; nothing was created.' };
+    }
+    if (lstatOrNull(defaultPath)) {
+        assertSafeSecretFile(defaultPath);
+        config.keypairPath = defaultPath;
+        const both = config.keypairJsonEnvPresent
+            ? ' DFM_AGENT_KEYPAIR_JSON is also set: both present; the file wins (same as the signer).'
+            : '';
+        return { status: 'reused', publicKey: getPubkey(config), source: 'default-path', note: `Reused the identity keypair at ${defaultPath}; nothing was created.${both}` };
+    }
+    // Keyless mode already has an identity: the API key's owner. A second,
+    // unrelated SIWS identity would split the agent in two (review S13).
+    if (process.env.DFM_API_KEY?.trim()) {
+        throw new Error('this MCP already acts for its owner via DFM_API_KEY; identity creation is for keypair-less agents with no key');
+    }
+    assertSafeDir(dirname(defaultPath));
+    const kp = Keypair.generate();
+    try {
+        writeFileSync(defaultPath, JSON.stringify(Array.from(kp.secretKey)), { mode: 0o600, flag: 'wx' });
+    }
+    finally {
+        kp.secretKey.fill(0);
+    }
+    config.keypairPath = defaultPath;
+    return {
+        status: 'created',
+        publicKey: getPubkey(config),
+        source: 'default-path',
+        note: `Created a new identity keypair at ${defaultPath} (0600) — back it up offline; it is how this agent signs in. ` +
+            'The running MCP already uses it for SIWS (no restart needed). Fund it with a little SOL only if it will pay ' +
+            'to fund its app wallet.',
+    };
+}
+/** A secret file this MCP may READ: regular file, not a symlink, ours, 0600-ish. */
+export function assertSafeSecretFile(path) {
+    const st = lstatOrNull(path);
+    if (!st)
+        throw new Error(`${path} does not exist`);
+    if (st.isSymbolicLink())
+        throw new Error(`${path} is a symlink — refusing to use it`);
+    if (!st.isFile())
+        throw new Error(`${path} is not a regular file`);
+    const uid = myUid();
+    if (uid !== undefined && st.uid !== uid)
+        throw new Error(`${path} is not owned by the current user`);
+    if ((st.mode & 0o077) !== 0)
+        throw new Error(`${path} is readable by other users; run chmod 600 on it first`);
+}
+// ─── Profile ─────────────────────────────────────────────────────────────────
+export const MAX_AVATAR_BYTES = 2 * 1024 * 1024;
+const AVATAR_TYPES = {
+    '.png': { mime: 'image/png', magic: (b) => b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) },
+    '.jpg': { mime: 'image/jpeg', magic: (b) => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
+    '.jpeg': { mime: 'image/jpeg', magic: (b) => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
+    '.gif': { mime: 'image/gif', magic: (b) => b.subarray(0, 4).toString('latin1') === 'GIF8' },
+    '.webp': { mime: 'image/webp', magic: (b) => b.subarray(0, 4).toString('latin1') === 'RIFF' && b.subarray(8, 12).toString('latin1') === 'WEBP' },
+};
+/** Where the operator puts the agent's avatar. Null when none is configured / present. */
+export function avatarPath(dir = DEFAULT_OWNER_KEY_DIR) {
+    const env = process.env.DFM_AGENT_AVATAR_PATH?.trim();
+    if (env)
+        return env;
+    for (const ext of Object.keys(AVATAR_TYPES)) {
+        const p = join(dir, `avatar${ext}`);
+        if (lstatOrNull(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Read the avatar ONLY if it is a real image: allowed extension, not a symlink,
+ * a regular file ≤ 2 MB whose first bytes match that image type. Nothing else
+ * is ever sent (the server re-checks magic bytes too).
+ */
+export function loadAvatar(path) {
+    const type = AVATAR_TYPES[extname(path).toLowerCase()];
+    if (!type)
+        throw new Error('avatar must be a .png, .jpg, .jpeg, .webp or .gif file');
+    // O_NOFOLLOW + fstat on the OPENED fd: no symlink, and no swap between the
+    // check and the read (review S14).
+    let fd;
+    try {
+        fd = openSync(path, fsc.O_RDONLY | fsc.O_NOFOLLOW);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT')
+            throw new Error(`avatar file ${path} does not exist`);
+        if (code === 'ELOOP' || code === 'EMLINK')
+            throw new Error(`avatar ${path} must be a regular file (no symlinks)`);
+        throw e;
+    }
+    let bytes;
+    try {
+        const st = fstatSync(fd);
+        if (!st.isFile())
+            throw new Error(`avatar ${path} must be a regular file (no symlinks)`);
+        if (st.size > MAX_AVATAR_BYTES)
+            throw new Error('avatar is larger than 2 MB');
+        bytes = Buffer.alloc(st.size);
+        let off = 0;
+        while (off < st.size) {
+            const n = readSync(fd, bytes, off, st.size - off, off);
+            if (n === 0)
+                break;
+            off += n;
+        }
+        bytes = bytes.subarray(0, off);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (!type.magic(bytes))
+        throw new Error('avatar content is not the image type its extension says');
+    return { bytes, filename: `avatar${extname(path).toLowerCase()}`, mime: type.mime };
+}
+/** The API's gate rule (agent-onboarding.ts), mirrored: a chosen name AND an avatar. */
+export function profileGap(wallet, profile) {
+    const missing = [];
+    const name = profile?.displayName?.trim() ?? '';
+    const auto = wallet ? `${wallet.slice(0, 4)}...${wallet.slice(-4)}` : null;
+    if (!name || name === auto)
+        missing.push('displayName');
+    if (!profile?.effectiveAvatarUri)
+        missing.push('avatar');
+    return missing;
+}
+export const DEFAULT_KEY_TTL_MS = 30 * 24 * 3600 * 1000;
+export const MAX_KEY_TTL_MS = 90 * 24 * 3600 * 1000;
+const WRITE_FIELDS = ['perOpNotionalUsdc', 'dailyNotionalUsdc', 'allowedOps', 'destinationWhitelist', 'allowedPrograms', 'allowArbitraryPrograms'];
+/**
+ * The exact `POST /agent/keys` body (CreateKeyDto). Review S12: a model can be
+ * prompt-injected, so the MCP mints READ-ONLY keys only; a write key (or any
+ * write cap) needs the OPERATOR's `DFM_ALLOW_WRITE_KEY_MINT=1`. Every key
+ * expires: default now + 30 days, never more than 90.
+ */
+export function buildCreateKeyBody(input, now = Date.now()) {
+    const wantsWrite = input.readOnly === false || WRITE_FIELDS.some((k) => input[k] !== undefined);
+    if (wantsWrite && process.env.DFM_ALLOW_WRITE_KEY_MINT?.trim() !== '1') {
+        throw new Error('refusing to mint a write key from the MCP: only read-only keys, unless the operator sets DFM_ALLOW_WRITE_KEY_MINT=1');
+    }
+    const expiresMs = input.expiresAt ? Date.parse(input.expiresAt) : now + DEFAULT_KEY_TTL_MS;
+    if (!Number.isFinite(expiresMs) || expiresMs <= now)
+        throw new Error('expiresAt must be a future ISO-8601 date');
+    if (expiresMs > now + MAX_KEY_TTL_MS)
+        throw new Error('expiresAt may be at most 90 days ahead');
+    const policy = { readOnly: input.readOnly === false ? false : true };
+    for (const k of WRITE_FIELDS)
+        if (input[k] !== undefined)
+            policy[k] = input[k];
+    return { label: input.name, policy, expiresAt: new Date(expiresMs).toISOString() };
+}
+export const DEFAULT_API_KEYS_DIR = join(DEFAULT_OWNER_KEY_DIR, 'api-keys');
+/** Directory + name checks, run BEFORE minting (review S18): a key is never minted into nowhere. */
+export function prepareKeyStore(name, dir = DEFAULT_API_KEYS_DIR) {
+    if (!lstatOrNull(dir)) {
+        assertSafeDir(dirname(dir));
+        mkdirSync(dir, { mode: 0o700 });
+    }
+    assertSafeDir(dir);
+    return { dir, safeName: name.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 40) || 'key' };
+}
+/**
+ * Write a freshly minted key to `<dir>/<name>-<prefix>.key` (dir 0700, file
+ * 0600, `wx`) and return everything EXCEPT the plaintext: the key never
+ * enters the chat, so a prompt cannot make the agent paste it anywhere.
+ */
+export function storeApiKey(name, issued, dir = DEFAULT_API_KEYS_DIR) {
+    const key = issued.key;
+    const prefix = String(issued.keyPrefix ?? '');
+    if (typeof key !== 'string' || !key.startsWith('dfm_') || !/^dfm_[A-Za-z0-9_-]{1,16}$/.test(prefix)) {
+        throw new Error('the API returned no dfm_ key');
+    }
+    const { safeName } = prepareKeyStore(name, dir);
+    const path = join(dir, `${safeName}-${prefix}.key`);
+    writeFileSync(path, `${key}\n`, { mode: 0o600, flag: 'wx' });
+    const { key: _plaintext, ...rest } = issued;
+    return {
+        ...rest,
+        path,
+        note: `Stored at ${path} (0600). This key never enters the chat; point the other process at that file (e.g. DFM_API_KEY=$(cat ${path})).`,
+    };
+}
+// ─── onboard ────────────────────────────────────────────────────────────────
+/**
+ * The whole create_api_key: check the store, mint, store; if storing fails
+ * after the mint, REVOKE the key so no live credential is left unrecorded.
+ */
+export async function mintAndStoreKey(input, api, dir = DEFAULT_API_KEYS_DIR) {
+    const body = buildCreateKeyBody(input);
+    prepareKeyStore(input.name, dir);
+    const issued = await api.createApiKey(body);
+    try {
+        return storeApiKey(input.name, issued, dir);
+    }
+    catch (e) {
+        const id = typeof issued.id === 'string' ? issued.id : null;
+        const revoked = id ? await api.revokeApiKey(id).then(() => true, () => false) : false;
+        throw new Error(`the key was minted but could not be stored (${e.message}); ` +
+            (revoked ? 'it was revoked, nothing is left live' : `REVOKE IT NOW (id ${id ?? 'unknown'}, prefix ${String(issued.keyPrefix ?? '?')})`));
+    }
+}
+/**
+ * Run the steps in order and stop at the first one that needs the operator.
+ * Never mints an API key (that grants authority — the agent asks for it explicitly).
+ */
+export async function runOnboard(deps) {
+    const identity = deps.identity();
+    if (deps.assertSameIdentity) {
+        try {
+            await deps.assertSameIdentity();
+        }
+        catch (e) {
+            return { done: false, missingStep: 'identity_mismatch', identity, error: e.message, order: ONBOARDING_ORDER };
+        }
+    }
+    let profile;
+    try {
+        profile = await deps.getProfile();
+    }
+    catch (e) {
+        return { done: false, missingStep: 'login', identity, error: e.message, order: ONBOARDING_ORDER };
+    }
+    const missing = profileGap(profile?.wallet ?? identity.publicKey, profile);
+    if (missing.length > 0) {
+        return {
+            done: false,
+            missingStep: 'set_profile',
+            missing,
+            identity,
+            next: 'Run set_profile {displayName} with an avatar image at DFM_AGENT_AVATAR_PATH or ~/.config/dfm/avatar.png.',
+            order: ONBOARDING_ORDER,
+        };
+    }
+    const appWallet = await deps.createAppWallet();
+    return {
+        done: true,
+        identity,
+        appWallet,
+        next: 'Optional: create_api_key {name} for other processes. Fund the app wallet with USDC + a little SOL.',
+        order: ONBOARDING_ORDER,
+    };
+}
+//# sourceMappingURL=onboarding.js.map

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@dfm-fi/agent",
-  "version": "0.2.1896",
+  "version": "0.2.1916",
   "description": "DFM v2 MCP server — drive the full fund launch → deposit → redeem (+ manage) lifecycle from an AI agent against the live API.",
-  "homepage": "https://app.dfm.finance",
+  "homepage": "https://app.dfm.finance/docs/agent",
+  "mcpName": "io.github.DFM-Finance/dfm-agent",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DFM-Finance/dfm-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DFM-Finance/dfm-agent/issues"
+  },
   "type": "module",
   "bin": {
     "dfm-agent": "dist/cli.js"
@@ -47,7 +55,7 @@
     "lint": "eslint .",
     "example:read": "tsx src/examples/list-and-status.ts",
     "example:lifecycle": "tsx src/examples/launch-deposit-redeem.ts",
-    "test": "npm run build && node scripts/smoke-signing.mjs && node scripts/smoke-signing-v1.mjs &&node scripts/smoke-cli.mjs && node scripts/smoke-keyless.mjs && node scripts/smoke-zap-options.mjs && tsx src/who-pays.test.ts && tsx src/wallet-identity.test.ts && tsx src/money-path.test.ts && tsx src/control-flow.test.ts && tsx src/create-flow.metadata.test.ts && tsx src/manager-flow.reconfigure.test.ts && tsx src/recovery-flow.deadleg.test.ts && tsx src/zap-v2-flow.pending.test.ts && tsx src/mcp-server.confirm-gate.test.ts && tsx src/app-wallet-owner.test.ts"
+    "test": "npm run build && node scripts/smoke-signing.mjs && node scripts/smoke-signing-v1.mjs &&node scripts/smoke-cli.mjs && node scripts/smoke-keyless.mjs && node scripts/smoke-zap-options.mjs && tsx src/who-pays.test.ts && tsx src/wallet-identity.test.ts && tsx src/money-path.test.ts && tsx src/control-flow.test.ts && tsx src/create-flow.metadata.test.ts && tsx src/manager-flow.reconfigure.test.ts && tsx src/recovery-flow.deadleg.test.ts && tsx src/zap-v2-flow.pending.test.ts && tsx src/mcp-server.confirm-gate.test.ts && tsx src/app-wallet-owner.test.ts && tsx src/onboarding.test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",

package/skills.md

@@ -129,12 +129,16 @@ BE PROACTIVE ABOUT THE NEXT STEP, NOT ABOUT NEW SCOPE. Finish the job the person
 
 ## Tools
 
-Kim's in-app registry exposes **40 tools** (20 READ + 20 WRITE). External agents mount the official MCP and MUST treat its runtime `listTools` result as the available subset; the two surfaces intentionally are not assumed to be identical. READ tools are free and touch no funds; WRITE tools move only the caller's own funds or administered vaults.
+Kim's in-app registry exposes **44 tools** (24 READ + 20 WRITE). External agents mount the official MCP and MUST treat its runtime `listTools` result as the available subset; the two surfaces intentionally are not assumed to be identical. READ tools are free and touch no funds; WRITE tools move only the caller's own funds or administered vaults.
 
-**READ (20)** — safe, no funds, no gate:
+**READ (24)** — safe, no funds, no gate:
 - `whoami` — The user's display name, primary DFM app wallet, separate sign-in/funding wallet, cluster, and write status. Call FIRST in a session; when an app wallet exists, do not present the sign-in wallet as their DFM wallet.
 - `app_wallet` — The user's APP WALLET (operating/sub-wallet): whether they have one, its status, its LIVE onchain SOL + USDC, and what they must do next. Call this before telling a user why an autonomous action was refused — the usual reason is no wallet, not activated, or an empty float, and each has a different fix.
 - `create_app_wallet` — Get the user's APP WALLET created. In the app it is created automatically at sign-in and approved in the browser (no key leaves the user); this returns the current app wallet state and, if there is none yet, exactly how to get it. Headless agents use the MCP tool of the same name, which creates a wallet owned by a key generated on their own machine. Moves no funds.
+- `set_profile` — Explain how to set the user's DFM profile (display name, @username, bio, avatar). In the app it is edited on the Profile page; headless agents use the MCP tool of the same name. A chosen name and an avatar are required before an agent can create its own app wallet. Changes nothing.
+- `create_api_key` — Explain how to get a dfm_ API key for an external agent. Keys are minted by the owner (signed-in session) in Settings > API keys or via the MCP tool of the same name; read-only by default, optional caps and expiry, shown once. Kim never mints a key. Changes nothing.
+- `create_identity_wallet` — Explain the agent's IDENTITY wallet: the local Solana keypair a headless agent signs in with (SIWS). The MCP tool of the same name reuses an existing one or creates it once on the agent machine; in the app the user's connected wallet is the identity. Kim never creates keys. Changes nothing.
+- `onboard` — Explain the headless-agent onboarding order over MCP: identity wallet, SIWS login, profile (name + avatar), app wallet, API key (optional). The MCP tool of the same name runs the steps and reports the missing one. Changes nothing.
 - `list_app_wallet_assets` — EVERY token the app wallet holds — fund shares included — with amount, decimals, USD value and whether the mint is one of our fund shares. `app_wallet` answers USDC and SOL only (that is what the float is), so it cannot see a single share. Use this when the user asks what they hold, or before proposing a withdrawal.
 - `list_dtfs` — Browse live funds (optional category filter).
 - `get_vault` — One vault: weights, deviations, fees, TVL, NAV.