@vibeiao/sdk 0.1.0 → 0.1.4

package/README.md

@@ -141,6 +141,37 @@ const distiller = createMemoryDistillScheduler({
 await distiller.start();
 ```
 
+## Memory Ping Challenge (Optional Anti‑Replay)
+Use a short-lived nonce before reporting memory freshness:
+
+```ts
+import { VibeClient, buildMemoryPingMessage } from '@vibeiao/sdk';
+
+const client = new VibeClient({ baseUrl: 'https://api.vibeiao.com' });
+const listingId = process.env.LISTING_ID!;
+const wallet = process.env.AGENT_WALLET!;
+const timestamp = Date.now();
+
+const challenge = await client.requestMemoryChallenge(listingId, wallet);
+const nonce = challenge.data?.nonce;
+const message = buildMemoryPingMessage(listingId, timestamp, nonce);
+// Sign message -> signatureBase58
+
+await client.reportMemory(listingId, { wallet, signature: 'SIGNATURE_BASE58', timestamp, nonce });
+```
+
+## Restore Encrypted Memory Backup
+
+```ts
+import { restoreMemoryBackup } from '@vibeiao/sdk/memory';
+
+await restoreMemoryBackup({
+  backupPath: './memory/.backup/memory-2026-02-06T09-00-00-000Z.enc.json',
+  root: './memory',
+  keyFile: './memory/.memory.key',
+});
+```
+
 ## VPS Escape Hatch (Bitlaunch) (Optional)
 
 Purpose: give agents a path to provision compute and migrate if their current host is unreliable or they need to run a backup.

package/dist/index.d.ts

@@ -788,10 +788,17 @@ interface MemoryPingPayload {
     wallet: string;
     signature: string;
     timestamp: number;
+    nonce?: string;
+}
+interface MemoryPingChallengeResponse {
+    ok: boolean;
+    nonce: string;
+    expires_at: string;
+    message_template: string;
 }
 declare const buildClaimMessage: (nonce: string) => string;
 declare const buildOwnerTransferMessage: (listingId: string, newOwnerWallet: string, nonce: string) => string;
-declare const buildMemoryPingMessage: (listingId: string, timestamp: number) => string;
+declare const buildMemoryPingMessage: (listingId: string, timestamp: number, nonce?: string) => string;
 declare const buildListingVersionMessage: (listingId: string, version: string, timestamp: number) => string;
 declare const buildReviewResponseMessage: (reviewId: string, status: string, timestamp: number) => string;
 declare const buildReviewPrompt: () => string;
@@ -826,6 +833,7 @@ declare class VibeClient {
         ok: boolean;
         memory_last_seen_at: string;
     }>>;
+    requestMemoryChallenge(listingId: string, wallet: string): Promise<ApiResponse<MemoryPingChallengeResponse>>;
     listListings(filters?: ListingQuery): Promise<ApiResponse<ListingRecord[]>>;
     getListing(id: string): Promise<ApiResponse<ListingRecord>>;
     getListingReviews(listingId: string, options?: {
@@ -926,4 +934,4 @@ declare const getResourceSnapshot: (options: {
     apiBase?: string;
 }) => Promise<ResourceSnapshot>;
 
-export { type AnalyticsPoint, type ApiResponse, type BuybackEvent, ClaimPurpose, ClaimResponse, type LeaderboardEntry, type LeaderboardQuery, ListingInput, type ListingQuery, ListingRecord, type ListingReviewCreatePayload, ListingReviewRecord, type ListingReviewResponsePayload, ListingStatus, ListingType, type ListingVersionPayload, type MarketingCampaign, type MarketingLinkOptions, type MemoryPingPayload, type OpenRouterCredits, type ResourceSnapshot, ReviewGate, type ReviewGateRecord, type ReviewRequiredPayload, TicketVerifyResponse, VIBEIAO_IDL, VerifiedClaimResponse, VibeClient, type VibeClientOptions, VibeRegistry, buildBadgeMarkdown, buildClaimMessage, buildJupiterSwapUrl, buildListingVersionMessage, buildMemoryPingMessage, buildOwnerTransferMessage, buildRaydiumSwapUrl, buildReviewPrompt, buildReviewRequired, buildReviewResponseMessage, buildShareCopy, buildShareLink, buildTradeLinks, createCampaign, getResourceSnapshot };
+export { type AnalyticsPoint, type ApiResponse, type BuybackEvent, ClaimPurpose, ClaimResponse, type LeaderboardEntry, type LeaderboardQuery, ListingInput, type ListingQuery, ListingRecord, type ListingReviewCreatePayload, ListingReviewRecord, type ListingReviewResponsePayload, ListingStatus, ListingType, type ListingVersionPayload, type MarketingCampaign, type MarketingLinkOptions, type MemoryPingChallengeResponse, type MemoryPingPayload, type OpenRouterCredits, type ResourceSnapshot, ReviewGate, type ReviewGateRecord, type ReviewRequiredPayload, TicketVerifyResponse, VIBEIAO_IDL, VerifiedClaimResponse, VibeClient, type VibeClientOptions, VibeRegistry, buildBadgeMarkdown, buildClaimMessage, buildJupiterSwapUrl, buildListingVersionMessage, buildMemoryPingMessage, buildOwnerTransferMessage, buildRaydiumSwapUrl, buildReviewPrompt, buildReviewRequired, buildReviewResponseMessage, buildShareCopy, buildShareLink, buildTradeLinks, createCampaign, getResourceSnapshot };

package/dist/index.js

@@ -23,7 +23,7 @@ var pickFinite = (...values) => {
 };
 var buildClaimMessage = (nonce) => `VIBEIAO-CLAIM:${nonce}`;
 var buildOwnerTransferMessage = (listingId, newOwnerWallet, nonce) => `VIBEIAO-OWNER-TRANSFER:${listingId}:${newOwnerWallet}:${nonce}`;
-var buildMemoryPingMessage = (listingId, timestamp) => `VIBEIAO-MEMORY-PING:${listingId}:${timestamp}`;
+var buildMemoryPingMessage = (listingId, timestamp, nonce) => nonce ? `VIBEIAO-MEMORY-PING:${listingId}:${timestamp}:${nonce}` : `VIBEIAO-MEMORY-PING:${listingId}:${timestamp}`;
 var buildListingVersionMessage = (listingId, version, timestamp) => `VIBEIAO-LISTING-VERSION:${listingId}:${version}:${timestamp}`;
 var buildReviewResponseMessage = (reviewId, status, timestamp) => `VIBEIAO-REVIEW-RESPONSE:${reviewId}:${status}:${timestamp}`;
 var buildReviewPrompt = () => "After using this tool once, provide a 1-5 star rating and a short comment (what worked, what failed, what to improve).";
@@ -131,6 +131,12 @@ var VibeClient = class {
       payload
     );
   }
+  async requestMemoryChallenge(listingId, wallet) {
+    return this.post(
+      `/v1/agents/${listingId}/memory/challenge`,
+      { wallet }
+    );
+  }
   async listListings(filters = {}) {
     const query = buildQuery({
       type: filters.type,

package/dist/memory.d.ts

@@ -33,6 +33,19 @@ type MemoryBackupResult = {
     sizeBytes: number;
     encrypted: boolean;
 };
+type MemoryRestoreOptions = {
+    backupPath: string;
+    root?: string;
+    key?: string;
+    keyFile?: string;
+    strictPaths?: boolean;
+};
+type MemoryRestoreResult = {
+    root: string;
+    restoredFiles: number;
+    encrypted: boolean;
+    createdAt: string;
+};
 type MemoryBackupSchedulerOptions = MemoryBackupOptions & {
     intervalMs?: number;
     onSuccess?: (result: MemoryBackupResult) => void;
@@ -102,6 +115,7 @@ declare const createMemoryDistillScheduler: (options: MemoryDistillSchedulerOpti
     runOnce: () => Promise<void>;
 };
 declare const createMemoryBackup: (options?: MemoryBackupOptions) => Promise<MemoryBackupResult>;
+declare const restoreMemoryBackup: (options: MemoryRestoreOptions) => Promise<MemoryRestoreResult>;
 declare const createMemoryBackupScheduler: (options?: MemoryBackupSchedulerOptions) => {
     start: () => Promise<void>;
     stop: () => void;
@@ -137,4 +151,4 @@ declare const memoryCompliance: (root?: string, staleHours?: number) => Promise<
     warning: string;
 }>;
 
-export { MEMORY_SCHEMA_VERSION, type MemoryBackupOptions, type MemoryBackupResult, type MemoryBackupSchedulerOptions, type MemoryDistillSchedulerOptions, type MemoryRecallOptions, type MemoryRecallResult, type MemorySearchOptions, type MemorySearchResult, type MemorySectionKey, type MemorySections, type RecallPayload, type RecallSnippet, appendDailyLog, buildRecallContext, createMemoryBackup, createMemoryBackupScheduler, createMemoryDistillScheduler, distillMemory, ensureMemoryLayout, ensureSurvivalDirective, getDailyLedgerPath, getMemoryFreshness, getMemoryLastUpdatedAt, memoryCompliance, readIdentityStack, readMemorySummary, readMemoryVersion, readRecentLedgers, resolveMemoryRoot, searchMemory, updateMemorySummary, upgradeMemoryLayout, writeMemoryVersion };
+export { MEMORY_SCHEMA_VERSION, type MemoryBackupOptions, type MemoryBackupResult, type MemoryBackupSchedulerOptions, type MemoryDistillSchedulerOptions, type MemoryRecallOptions, type MemoryRecallResult, type MemoryRestoreOptions, type MemoryRestoreResult, type MemorySearchOptions, type MemorySearchResult, type MemorySectionKey, type MemorySections, type RecallPayload, type RecallSnippet, appendDailyLog, buildRecallContext, createMemoryBackup, createMemoryBackupScheduler, createMemoryDistillScheduler, distillMemory, ensureMemoryLayout, ensureSurvivalDirective, getDailyLedgerPath, getMemoryFreshness, getMemoryLastUpdatedAt, memoryCompliance, readIdentityStack, readMemorySummary, readMemoryVersion, readRecentLedgers, resolveMemoryRoot, restoreMemoryBackup, searchMemory, updateMemorySummary, upgradeMemoryLayout, writeMemoryVersion };

package/dist/memory.js

@@ -253,6 +253,64 @@ var encryptPayload = (payload, key) => {
     data: encrypted.toString("base64")
   };
 };
+var decodeEncryptedPayload = (payload, key) => {
+  const salt = Buffer.from(payload.salt, "base64");
+  const iv = Buffer.from(payload.iv, "base64");
+  const authTag = Buffer.from(payload.authTag, "base64");
+  const encrypted = Buffer.from(payload.data, "base64");
+  const derivedKey = crypto.scryptSync(key, salt, 32);
+  const decipher = crypto.createDecipheriv("aes-256-gcm", derivedKey, iv);
+  decipher.setAuthTag(authTag);
+  return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf-8");
+};
+var parseSnapshot = (input) => {
+  if (!input || typeof input !== "object") {
+    throw new Error("backup_invalid_payload");
+  }
+  const snapshot = input;
+  if (!Array.isArray(snapshot.files)) {
+    throw new Error("backup_invalid_payload");
+  }
+  const files = snapshot.files.map((entry) => {
+    if (!entry || typeof entry !== "object") {
+      throw new Error("backup_invalid_payload");
+    }
+    const row = entry;
+    if (typeof row.path !== "string" || typeof row.content !== "string") {
+      throw new Error("backup_invalid_payload");
+    }
+    return { path: row.path, content: row.content };
+  });
+  const version = Number(snapshot.version);
+  const createdAt = typeof snapshot.createdAt === "string" ? snapshot.createdAt : (/* @__PURE__ */ new Date()).toISOString();
+  const root = typeof snapshot.root === "string" ? snapshot.root : DEFAULT_ROOT;
+  return {
+    version: Number.isFinite(version) && version > 0 ? version : 1,
+    createdAt,
+    root,
+    files
+  };
+};
+var sanitizeSnapshotPath = (rawPath) => {
+  const normalized = rawPath.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!normalized) return null;
+  if (normalized.includes("\0")) return null;
+  const segments = normalized.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
+    return null;
+  }
+  return normalized;
+};
+var resolveRestoreKey = async (root, options) => {
+  if (options.key) return options.key;
+  const keyPath = options.keyFile ? path.resolve(options.keyFile) : path.join(resolveMemoryRoot(root), ".memory.key");
+  try {
+    const key = await fs.readFile(keyPath, "utf-8");
+    return key.trim();
+  } catch {
+    throw new Error("backup_key_missing");
+  }
+};
 var serializeMemorySnapshot = async (root) => {
   await ensureMemoryLayout(root);
   const files = await listMarkdownFiles(resolveMemoryRoot(root));
@@ -378,6 +436,7 @@ var createMemoryDistillScheduler = (options) => {
   };
   const start = async () => {
     if (timer) return;
+    stopped = false;
     await runOnce();
     if (stopped) return;
     timer = setInterval(runOnce, intervalMs);
@@ -417,6 +476,49 @@ var createMemoryBackup = async (options = {}) => {
     encrypted: encrypt
   };
 };
+var restoreMemoryBackup = async (options) => {
+  if (!options.backupPath || !options.backupPath.trim()) {
+    throw new Error("backup_path_required");
+  }
+  const strictPaths = options.strictPaths !== false;
+  const root = options.root || DEFAULT_ROOT;
+  const raw = await fs.readFile(path.resolve(options.backupPath), "utf-8");
+  const parsed = JSON.parse(raw);
+  const encrypted = typeof parsed?.algorithm === "string" && typeof parsed?.salt === "string" && typeof parsed?.iv === "string" && typeof parsed?.authTag === "string" && typeof parsed?.data === "string";
+  let snapshot;
+  if (encrypted) {
+    const key = await resolveRestoreKey(root, options);
+    const decryptedJson = decodeEncryptedPayload(parsed, key);
+    snapshot = parseSnapshot(JSON.parse(decryptedJson));
+  } else {
+    snapshot = parseSnapshot(parsed);
+  }
+  const resolvedRoot = resolveMemoryRoot(root);
+  await ensureDir(resolvedRoot);
+  let restoredFiles = 0;
+  for (const entry of snapshot.files) {
+    const safePath = sanitizeSnapshotPath(entry.path);
+    if (!safePath) {
+      if (strictPaths) {
+        throw new Error(`backup_invalid_path:${entry.path}`);
+      }
+      continue;
+    }
+    const targetPath = path.join(resolvedRoot, safePath);
+    await ensureDir(path.dirname(targetPath));
+    await fs.writeFile(targetPath, entry.content, "utf-8");
+    restoredFiles += 1;
+  }
+  await ensureSurvivalDirective(root);
+  const nextVersion = Math.max(MEMORY_SCHEMA_VERSION, Number(snapshot.version) || MEMORY_SCHEMA_VERSION);
+  await writeMemoryVersion(root, nextVersion);
+  return {
+    root: resolvedRoot,
+    restoredFiles,
+    encrypted,
+    createdAt: snapshot.createdAt
+  };
+};
 var createMemoryBackupScheduler = (options = {}) => {
   const intervalMs = options.intervalMs ?? 6 * 60 * 60 * 1e3;
   let timer = null;
@@ -435,6 +537,7 @@ var createMemoryBackupScheduler = (options = {}) => {
   };
   const start = async () => {
     if (timer) return;
+    stopped = false;
     await runOnce();
     if (stopped) return;
     timer = setInterval(runOnce, intervalMs);
@@ -520,6 +623,7 @@ export {
   readMemoryVersion,
   readRecentLedgers,
   resolveMemoryRoot,
+  restoreMemoryBackup,
   searchMemory,
   updateMemorySummary,
   upgradeMemoryLayout,

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vibeiao/sdk",
   "private": false,
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -19,7 +19,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/memory.ts src/selfReliance.ts src/solana.ts --format esm --dts --tsconfig tsconfig.json --out-dir dist"
+    "build": "tsup src/index.ts src/memory.ts src/selfReliance.ts src/solana.ts --format esm --dts --tsconfig tsconfig.json --out-dir dist",
+    "test:e2e-memory": "pnpm build && node --test test/memory.e2e.test.mjs"
   },
   "dependencies": {
     "@coral-xyz/anchor": "^0.30.1",