@orbitmem/sdk 0.1.0

package/src/persistence/persistence-layer.ts

@@ -0,0 +1,236 @@
+import type { IPersistenceLayer, Snapshot, WalletAddress } from "../types.js";
+
+const DEFAULT_GATEWAY = "https://w3s.link";
+
+interface PersistenceConfig {
+  mock?: boolean;
+  relayUrl?: string;
+  proof?: string;
+  gatewayUrl?: string;
+  author?: WalletAddress;
+  signer?: string;
+}
+
+interface ArchiveOptions {
+  data?: Uint8Array;
+  entryCount?: number;
+  label?: string;
+  pinToFilecoin?: boolean;
+}
+
+function generateCID(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  return (
+    "bafy" +
+    Array.from(bytes)
+      .map((b) => b.toString(36))
+      .join("")
+      .slice(0, 55)
+  );
+}
+
+// ── Mock Persistence ─────────────────────────────────────────
+
+function createMockPersistence(config: PersistenceConfig): IPersistenceLayer {
+  const store = new Map<string, { data: Uint8Array; snapshot: Snapshot }>();
+
+  return {
+    async archive(opts: ArchiveOptions = {}) {
+      const data = opts.data ?? new Uint8Array(0);
+      const cid = generateCID();
+      const snapshot: Snapshot = {
+        cid,
+        size: data.length,
+        archivedAt: Date.now(),
+        author: config.author ?? ("0x0" as WalletAddress),
+        entryCount: opts.entryCount ?? 0,
+        encrypted: true,
+        filecoinStatus: "pending",
+      };
+      store.set(cid, { data, snapshot });
+      return snapshot;
+    },
+
+    async retrieve(cid) {
+      const entry = store.get(cid);
+      if (!entry) throw new Error(`Snapshot not found: ${cid}`);
+      return entry.data;
+    },
+
+    async restore(cid) {
+      const entry = store.get(cid);
+      if (!entry) throw new Error(`Snapshot not found: ${cid}`);
+      return { merged: entry.snapshot.entryCount, conflicts: 0 };
+    },
+
+    async listSnapshots(opts) {
+      const all = Array.from(store.values()).map((e) => e.snapshot);
+      const offset = opts?.offset ?? 0;
+      const limit = opts?.limit ?? all.length;
+      return all.slice(offset, offset + limit);
+    },
+
+    async deleteSnapshot(cid) {
+      store.delete(cid);
+    },
+
+    async getDealStatus(cid) {
+      const entry = store.get(cid);
+      if (!entry) throw new Error(`Snapshot not found: ${cid}`);
+      return { status: entry.snapshot.filecoinStatus };
+    },
+  };
+}
+
+// ── Managed Persistence (relay-backed) ───────────────────────
+
+function createManagedPersistence(config: PersistenceConfig): IPersistenceLayer {
+  const relayUrl = config.relayUrl!;
+  const gateway = config.gatewayUrl ?? DEFAULT_GATEWAY;
+
+  return {
+    async archive(opts: ArchiveOptions = {}) {
+      const data = opts.data ?? new Uint8Array(0);
+      const body = JSON.stringify({
+        data: new TextDecoder().decode(data),
+        entryCount: opts.entryCount ?? 0,
+      });
+
+      const res = await fetch(`${relayUrl}/v1/snapshots/archive`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body,
+      });
+
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Archive failed (${res.status}): ${text}`);
+      }
+
+      const snap = await res.json();
+      return snap as Snapshot;
+    },
+
+    async retrieve(cid) {
+      const res = await fetch(`${gateway}/ipfs/${cid}`);
+      if (!res.ok) throw new Error(`Failed to retrieve ${cid}: ${res.status}`);
+      return new Uint8Array(await res.arrayBuffer());
+    },
+
+    async restore(cid) {
+      const res = await fetch(`${gateway}/ipfs/${cid}`);
+      if (!res.ok) throw new Error(`Failed to retrieve ${cid}: ${res.status}`);
+      return { merged: 0, conflicts: 0 };
+    },
+
+    async listSnapshots(_opts) {
+      const res = await fetch(`${relayUrl}/v1/snapshots`);
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`List snapshots failed (${res.status}): ${text}`);
+      }
+      const items = await res.json();
+      return items as Snapshot[];
+    },
+
+    async deleteSnapshot(cid) {
+      const res = await fetch(`${relayUrl}/v1/snapshots/${cid}`, {
+        method: "DELETE",
+      });
+      if (!res.ok && res.status !== 204) {
+        const text = await res.text();
+        throw new Error(`Delete failed (${res.status}): ${text}`);
+      }
+    },
+
+    async getDealStatus(_cid) {
+      return { status: "pending" as const };
+    },
+  };
+}
+
+// ── Direct Persistence (Storacha UCAN) ───────────────────────
+
+function createDirectPersistence(config: PersistenceConfig): IPersistenceLayer {
+  const gateway = config.gatewayUrl ?? DEFAULT_GATEWAY;
+  let clientPromise: Promise<any> | null = null;
+
+  async function getClient() {
+    if (!clientPromise) {
+      clientPromise = (async () => {
+        const { create } = await import("@storacha/client");
+        const { parse } = await import("@storacha/client/proof");
+        const client = await create();
+        const proof = await parse(config.proof!);
+        const space = await client.addSpace(proof);
+        await client.setCurrentSpace(space.did());
+        return client;
+      })();
+    }
+    return clientPromise;
+  }
+
+  return {
+    async archive(opts: ArchiveOptions = {}) {
+      const client = await getClient();
+      const data = opts.data ?? new Uint8Array(0);
+      const blob = new Blob([data as BlobPart]);
+      const cid = await client.uploadFile(blob);
+
+      const snapshot: Snapshot = {
+        cid: cid.toString(),
+        size: data.length,
+        archivedAt: Date.now(),
+        author: config.author ?? ("0x0" as WalletAddress),
+        entryCount: opts.entryCount ?? 0,
+        encrypted: true,
+        filecoinStatus: "pending",
+      };
+      return snapshot;
+    },
+
+    async retrieve(cid) {
+      const res = await fetch(`${gateway}/ipfs/${cid}`);
+      if (!res.ok) throw new Error(`Failed to retrieve ${cid}: ${res.status}`);
+      return new Uint8Array(await res.arrayBuffer());
+    },
+
+    async restore(cid) {
+      const res = await fetch(`${gateway}/ipfs/${cid}`);
+      if (!res.ok) throw new Error(`Failed to retrieve ${cid}: ${res.status}`);
+      return { merged: 0, conflicts: 0 };
+    },
+
+    async listSnapshots(_opts) {
+      const client = await getClient();
+      const result = await client.capability.upload.list();
+      return (result.results ?? []).map((entry: any) => ({
+        cid: entry.root.toString(),
+        size: entry.size ?? 0,
+        archivedAt: entry.insertedAt ? new Date(entry.insertedAt).getTime() : Date.now(),
+        author: config.author ?? ("0x0" as WalletAddress),
+        entryCount: 0,
+        encrypted: true,
+        filecoinStatus: "pending" as const,
+      }));
+    },
+
+    async deleteSnapshot(cid) {
+      const client = await getClient();
+      const { CID: CIDClass } = await import("multiformats/cid");
+      await client.capability.upload.remove(CIDClass.parse(cid));
+    },
+
+    async getDealStatus(_cid) {
+      return { status: "pending" as const };
+    },
+  };
+}
+
+// ── Factory (mode detection) ─────────────────────────────────
+
+export function createPersistenceLayer(config: PersistenceConfig): IPersistenceLayer {
+  if (config.proof) return createDirectPersistence(config);
+  if (config.relayUrl) return createManagedPersistence(config);
+  return createMockPersistence(config);
+}

package/src/transport/__tests__/solana-transport.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from "bun:test";
+
+import { ed25519 } from "@noble/curves/ed25519.js";
+
+import { createTransportLayer } from "../transport-layer.js";
+
+describe("TransportLayer — Solana Ed25519", () => {
+  const privateKey = ed25519.utils.randomSecretKey();
+  const publicKey = ed25519.getPublicKey(privateKey);
+  const solanaAddress = "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU";
+
+  test("createSignedRequest adds Solana headers with ed25519", async () => {
+    const transport = createTransportLayer({
+      signer: async (payload: Uint8Array) => ({
+        signature: ed25519.sign(payload, privateKey),
+        algorithm: "ed25519" as const,
+      }),
+      signerAddress: solanaAddress,
+      family: "solana",
+    });
+
+    const signed = await transport.createSignedRequest({
+      url: "https://relay.orbitmem.com/v1/vault/read",
+      method: "POST",
+      body: { key: "preferences" },
+    });
+
+    expect(signed.proof.signer).toBe(solanaAddress);
+    expect(signed.proof.family).toBe("solana");
+    expect(signed.proof.algorithm).toBe("ed25519");
+    expect(signed.proof.signature).toBeInstanceOf(Uint8Array);
+    expect(signed.proof.nonce).toBeTruthy();
+    expect(signed.proof.timestamp).toBeGreaterThan(0);
+    expect(signed.headers["X-OrbitMem-Signer"]).toBe(solanaAddress);
+    expect(signed.headers["X-OrbitMem-Family"]).toBe("solana");
+    expect(signed.headers["X-OrbitMem-Algorithm"]).toBe("ed25519");
+  });
+
+  test("verifyRequest validates Ed25519 signature round-trip", async () => {
+    const transport = createTransportLayer({
+      signer: async (payload: Uint8Array) => ({
+        signature: ed25519.sign(payload, privateKey),
+        algorithm: "ed25519" as const,
+      }),
+      verifier: async (payload: Uint8Array, signature: Uint8Array) => {
+        return ed25519.verify(signature, payload, publicKey);
+      },
+      signerAddress: solanaAddress,
+      family: "solana",
+    });
+
+    const signed = await transport.createSignedRequest({
+      url: "https://relay.orbitmem.com/v1/vault/read",
+      method: "POST",
+      body: { key: "test" },
+    });
+
+    const result = await transport.verifyRequest(signed);
+    expect(result.valid).toBe(true);
+    expect(result.signer).toBe(solanaAddress);
+    expect(result.family).toBe("solana");
+    expect(result.isReplay).toBe(false);
+  });
+
+  test("rejects tampered Ed25519 signature", async () => {
+    const transport = createTransportLayer({
+      signer: async (payload: Uint8Array) => ({
+        signature: ed25519.sign(payload, privateKey),
+        algorithm: "ed25519" as const,
+      }),
+      verifier: async (payload: Uint8Array, signature: Uint8Array) => {
+        return ed25519.verify(signature, payload, publicKey);
+      },
+      signerAddress: solanaAddress,
+      family: "solana",
+    });
+
+    const signed = await transport.createSignedRequest({
+      url: "https://relay.orbitmem.com/v1/vault/read",
+      method: "POST",
+      body: { key: "test" },
+    });
+
+    signed.proof.signature = new Uint8Array(64).fill(0xab);
+
+    const result = await transport.verifyRequest(signed);
+    expect(result.valid).toBe(false);
+  });
+
+  test("replay detection works for Solana signer", async () => {
+    const transport = createTransportLayer({
+      signer: async (_payload) => ({
+        signature: new Uint8Array(64).fill(1),
+        algorithm: "ed25519" as const,
+      }),
+      verifier: async () => true,
+      signerAddress: solanaAddress,
+      family: "solana",
+    });
+
+    const signed = await transport.createSignedRequest({
+      url: "https://relay.orbitmem.com/v1/health",
+      method: "GET",
+    });
+
+    const first = await transport.verifyRequest(signed);
+    expect(first.isReplay).toBe(false);
+
+    const second = await transport.verifyRequest(signed);
+    expect(second.isReplay).toBe(true);
+  });
+});

package/src/transport/__tests__/transport.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+
+import { createTransportLayer } from "../transport-layer.js";
+
+describe("TransportLayer", () => {
+  test("createSignedRequest adds ERC-8128 headers", async () => {
+    const transport = createTransportLayer({
+      signer: async (_payload: Uint8Array) => ({
+        signature: new Uint8Array(65).fill(0xab),
+        algorithm: "ecdsa-secp256k1" as const,
+      }),
+      signerAddress: "0x1234567890abcdef1234567890abcdef12345678",
+      family: "evm",
+    });
+
+    const signed = await transport.createSignedRequest({
+      url: "https://orbitmem-relay.fly.dev/v1/vault/read",
+      method: "POST",
+      body: { key: "preferences" },
+    });
+
+    expect(signed.proof.signer).toBe("0x1234567890abcdef1234567890abcdef12345678");
+    expect(signed.proof.family).toBe("evm");
+    expect(signed.proof.algorithm).toBe("ecdsa-secp256k1");
+    expect(signed.proof.signature).toBeInstanceOf(Uint8Array);
+    expect(signed.proof.nonce).toBeTruthy();
+    expect(signed.proof.timestamp).toBeGreaterThan(0);
+    expect(signed.headers["X-OrbitMem-Signer"]).toBe("0x1234567890abcdef1234567890abcdef12345678");
+  });
+
+  test("verifyRequest validates signature round-trip", async () => {
+    const transport = createTransportLayer({
+      signer: async (payload: Uint8Array) => {
+        // Simple "sign" = hash of payload (for testing)
+        const hash = await crypto.subtle.digest("SHA-256", payload as BufferSource);
+        return {
+          signature: new Uint8Array(hash),
+          algorithm: "ecdsa-secp256k1" as const,
+        };
+      },
+      verifier: async (payload: Uint8Array, signature: Uint8Array) => {
+        const hash = await crypto.subtle.digest("SHA-256", payload as BufferSource);
+        const expected = new Uint8Array(hash);
+        return signature.length === expected.length && signature.every((b, i) => b === expected[i]);
+      },
+      signerAddress: "0xAGENT",
+      family: "evm",
+    });
+
+    const signed = await transport.createSignedRequest({
+      url: "https://orbitmem-relay.fly.dev/v1/vault/read",
+      method: "POST",
+      body: { key: "test" },
+    });
+
+    const result = await transport.verifyRequest(signed);
+    expect(result.valid).toBe(true);
+    expect(result.signer).toBe("0xAGENT");
+    expect(result.isReplay).toBe(false);
+  });
+
+  test("replay detection rejects seen nonce", async () => {
+    const transport = createTransportLayer({
+      signer: async (_payload) => ({
+        signature: new Uint8Array(32).fill(1),
+        algorithm: "ecdsa-secp256k1" as const,
+      }),
+      verifier: async () => true,
+      signerAddress: "0xAGENT",
+      family: "evm",
+    });
+
+    const signed = await transport.createSignedRequest({
+      url: "https://orbitmem-relay.fly.dev/v1/health",
+      method: "GET",
+    });
+
+    const first = await transport.verifyRequest(signed);
+    expect(first.isReplay).toBe(false);
+
+    const second = await transport.verifyRequest(signed);
+    expect(second.isReplay).toBe(true);
+  });
+});

package/src/transport/index.ts

@@ -0,0 +1,2 @@
+export { createRelaySession } from "./relay-session.js";
+export { createTransportLayer } from "./transport-layer.js";

package/src/transport/relay-session.ts

@@ -0,0 +1,118 @@
+/**
+ * Relay session transport — acquires a bearer token via ERC-8128 auth
+ * and caches it for subsequent requests. Designed for browser use with
+ * sessionStorage, but works anywhere with a custom storage adapter.
+ */
+
+import { createSignerClient } from "@slicekit/erc8128";
+import type { EthHttpSigner } from "@slicekit/erc8128";
+
+export interface RelaySessionConfig {
+  /** Relay server URL (e.g. "https://orbitmem-relay.fly.dev") */
+  relayUrl: string;
+  /** Wallet address (checksummed) */
+  address: `0x${string}`;
+  /** Chain ID (default: 84532 = Base Sepolia) */
+  chainId?: number;
+  /** Wallet signMessage function */
+  signMessage: (message: Uint8Array) => Promise<`0x${string}`>;
+  /** Session TTL in seconds (default: 1800 = 30 min) */
+  ttl?: number;
+  /** Storage adapter for caching (default: sessionStorage if available) */
+  storage?: {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+  };
+}
+
+interface CachedSession {
+  token: string;
+  expiresAt: number;
+  address: string;
+}
+
+const CACHE_KEY = "orbitmem:session";
+
+/**
+ * Create a relay session transport that handles session token
+ * acquisition, caching, and authenticated fetch.
+ *
+ * Usage:
+ * ```ts
+ * const relay = createRelaySession({ relayUrl, address, signMessage });
+ * const res = await relay.fetch("/v1/vault/keys", { method: "POST", body: ... });
+ * relay.clear(); // on disconnect
+ * ```
+ */
+export function createRelaySession(config: RelaySessionConfig) {
+  const { relayUrl, address, chainId = 84532, signMessage, ttl = 1800 } = config;
+  const storage = config.storage ?? (typeof sessionStorage !== "undefined" ? sessionStorage : null);
+
+  const signer: EthHttpSigner = {
+    address,
+    chainId,
+    signMessage: async (message: Uint8Array) => signMessage(message),
+  };
+
+  const client = createSignerClient(signer, {
+    preferReplayable: true,
+    ttlSeconds: ttl,
+  });
+
+  function getCached(): CachedSession | null {
+    if (!storage) return null;
+    const raw = storage.getItem(CACHE_KEY);
+    if (!raw) return null;
+    try {
+      const session: CachedSession = JSON.parse(raw);
+      if (session.address !== address) return null;
+      if (session.expiresAt <= Date.now() + 30_000) return null;
+      return session;
+    } catch {
+      return null;
+    }
+  }
+
+  async function acquireToken(): Promise<string> {
+    const cached = getCached();
+    if (cached) return cached.token;
+
+    const res = await client.fetch(
+      `${relayUrl}/v1/auth/session`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ ttl }),
+      },
+      {
+        binding: "class-bound",
+        replay: "replayable",
+        components: ["@authority"],
+      },
+    );
+    if (!res.ok) throw new Error(`Session request failed: ${res.status}`);
+    const data: CachedSession = await res.json();
+    storage?.setItem(CACHE_KEY, JSON.stringify(data));
+    return data.token;
+  }
+
+  return {
+    /** Make an authenticated fetch to the relay using a cached session token. */
+    async fetch(path: string, init?: RequestInit): Promise<Response> {
+      const token = await acquireToken();
+      return globalThis.fetch(`${relayUrl}${path}`, {
+        ...init,
+        headers: {
+          ...init?.headers,
+          Authorization: `Bearer ${token}`,
+        },
+      });
+    },
+
+    /** Clear the cached session token. Call on disconnect. */
+    clear() {
+      storage?.removeItem(CACHE_KEY);
+    },
+  };
+}