@orbitmem/sdk 0.1.0

package/src/identity/identity-layer.ts

@@ -0,0 +1,123 @@
+import type {
+  ChainFamily,
+  IdentityConfig,
+  IIdentityLayer,
+  SessionKey,
+  SignatureAlgorithm,
+  WalletConnection,
+} from "../types.js";
+import { deriveSessionKey } from "./session.js";
+
+export function createIdentityLayer(config: IdentityConfig): IIdentityLayer {
+  let connection: WalletConnection | null = null;
+  let activeSession: SessionKey | null = null;
+  const sessions = new Map<string, SessionKey>();
+  const listeners: Set<(conn: WalletConnection | null) => void> = new Set();
+
+  // Store signer function set by external wallet adapters
+  let signFn:
+    | ((message: string) => Promise<{ signature: Uint8Array; algorithm: SignatureAlgorithm }>)
+    | null = null;
+
+  return {
+    async connect(opts) {
+      // If an OWS wallet was provided (CLI / server usage), auto-connect via OWS adapter
+      if (config.owsWallet) {
+        const { createOwsAdapter } = await import("./ows-adapter.js");
+        const owsChain = config.owsChain ?? "eip155:84532";
+        const adapter = createOwsAdapter(config.owsWallet, owsChain);
+        const address = await adapter.getAddress();
+
+        const family: ChainFamily = owsChain.startsWith("solana:") ? "solana" : "evm";
+        const algorithm: SignatureAlgorithm = family === "solana" ? "ed25519" : "ecdsa-secp256k1";
+
+        connection = {
+          address,
+          family,
+          signatureAlgorithm: algorithm,
+          connectedAt: Date.now(),
+        };
+
+        signFn = async (message: string) => {
+          return adapter.signMessage(message);
+        };
+
+        for (const cb of listeners) cb(connection);
+        return connection;
+      }
+
+      throw new Error(
+        `connect(${opts.method}) requires a wallet adapter or owsWallet config. ` +
+          "Use setConnection() for testing or integrate a wallet provider.",
+      );
+    },
+
+    async createPasskey() {
+      throw new Error("Passkey creation requires browser WebAuthn API");
+    },
+
+    async disconnect() {
+      connection = null;
+      activeSession = null;
+      signFn = null;
+      for (const cb of listeners) cb(null);
+    },
+
+    async signChallenge(message) {
+      if (!signFn) throw new Error("No signer available — connect a wallet first");
+      return signFn(message);
+    },
+
+    async createSessionKey(permissions, opts) {
+      if (!connection) throw new Error("No wallet connected");
+      if (!signFn) throw new Error("No signer available");
+
+      const challenge = `OrbitMem Authentication\nTimestamp: ${Date.now()}\nNonce: ${crypto.randomUUID()}`;
+      const { signature } = await signFn(challenge);
+
+      const session = await deriveSessionKey({
+        family: connection.family,
+        signature,
+        parentAddress: connection.address,
+        permissions,
+        ttl: opts?.ttl ?? config.sessionTTL ?? 3600,
+      });
+
+      sessions.set(session.id, session);
+      activeSession = session;
+      return session;
+    },
+
+    async resumeSession(sessionId) {
+      const session = sessions.get(sessionId);
+      if (!session) return null;
+      if (session.expiresAt <= Date.now()) {
+        sessions.delete(sessionId);
+        return null;
+      }
+      activeSession = session;
+      return session;
+    },
+
+    async revokeSession(sessionId) {
+      sessions.delete(sessionId);
+      if (activeSession?.id === sessionId) activeSession = null;
+    },
+
+    getConnection() {
+      return connection;
+    },
+
+    getActiveSession() {
+      if (activeSession && activeSession.expiresAt <= Date.now()) {
+        activeSession = null;
+      }
+      return activeSession;
+    },
+
+    onConnectionChange(callback) {
+      listeners.add(callback);
+      return () => listeners.delete(callback);
+    },
+  };
+}

package/src/identity/index.ts

@@ -0,0 +1,3 @@
+export { createIdentityLayer } from "./identity-layer.js";
+export { deriveSessionKey } from "./session.js";
+export { createOwsAdapter, type OwsAdapter } from "./ows-adapter.js";

package/src/identity/ows-adapter.ts

@@ -0,0 +1,80 @@
+import type { SignatureAlgorithm, WalletAddress } from "../types.js";
+
+export interface OwsAdapter {
+  getAddress(): Promise<WalletAddress>;
+  signMessage(message: string): Promise<{ signature: Uint8Array; algorithm: SignatureAlgorithm }>;
+  toViemAccount(): Promise<import("viem").Account>;
+}
+
+/**
+ * @param walletName — OWS wallet name (e.g., "orbitmem")
+ * @param chain — CAIP-2 chain ID (e.g., "eip155:84532" for Base Sepolia)
+ */
+export function createOwsAdapter(walletName: string, chain: string): OwsAdapter {
+  // OWS NAPI-RS bindings are synchronous — wrap in lazy import for ESM compat.
+  const ows = () => import("@open-wallet-standard/core");
+
+  function hexToBytes(hex: string): Uint8Array {
+    const clean = hex.replace(/^0x/, "");
+    return new Uint8Array(clean.match(/.{2}/g)!.map((b) => Number.parseInt(b, 16)));
+  }
+
+  /**
+   * Find the EVM address for the given CAIP-2 chain from WalletInfo.accounts.
+   * Falls back to the first eip155 account if exact chain not found.
+   */
+  function resolveAddress(accounts: Array<{ chainId: string; address: string }>): string {
+    const exact = accounts.find((a) => a.chainId === chain);
+    if (exact) return exact.address;
+    const evm = accounts.find((a) => a.chainId.startsWith("eip155:"));
+    if (evm) return evm.address;
+    throw new Error(`No EVM account found for chain ${chain} in wallet "${walletName}"`);
+  }
+
+  return {
+    async getAddress(): Promise<WalletAddress> {
+      const { getWallet } = await ows();
+      const wallet = getWallet(walletName);
+      return resolveAddress(wallet.accounts) as WalletAddress;
+    },
+
+    async signMessage(
+      message: string,
+    ): Promise<{ signature: Uint8Array; algorithm: SignatureAlgorithm }> {
+      const { signMessage: owsSign } = await ows();
+      const result = owsSign(walletName, chain, message);
+      return { signature: hexToBytes(result.signature), algorithm: "ecdsa-secp256k1" };
+    },
+
+    async toViemAccount(): Promise<import("viem").Account> {
+      const address = await this.getAddress();
+      const { toAccount } = await import("viem/accounts");
+      return toAccount({
+        address: address as `0x${string}`,
+        async signMessage({ message }) {
+          const { signMessage: owsSign } = await ows();
+          const msg =
+            typeof message === "string"
+              ? message
+              : typeof message === "object" && "raw" in message
+                ? typeof message.raw === "string"
+                  ? message.raw
+                  : new TextDecoder().decode(message.raw)
+                : String(message);
+          const result = owsSign(walletName, chain, msg);
+          return result.signature as `0x${string}`;
+        },
+        async signTransaction(tx) {
+          const { signTransaction: owsSignTx } = await ows();
+          const result = owsSignTx(walletName, chain, JSON.stringify(tx));
+          return result.signature as `0x${string}`;
+        },
+        async signTypedData(typedData) {
+          const { signTypedData: owsSignTyped } = await ows();
+          const result = owsSignTyped(walletName, chain, JSON.stringify(typedData));
+          return result.signature as `0x${string}`;
+        },
+      });
+    },
+  };
+}

package/src/identity/session.ts

@@ -0,0 +1,57 @@
+import type {
+  ChainFamily,
+  SessionKey,
+  SessionPermission,
+  SignatureAlgorithm,
+  WalletAddress,
+} from "../types.js";
+
+export async function deriveSessionKey(opts: {
+  family: ChainFamily;
+  signature: Uint8Array;
+  parentAddress: WalletAddress;
+  permissions: SessionPermission[];
+  ttl: number; // seconds
+  nonce?: Uint8Array;
+}): Promise<SessionKey> {
+  const nonce = opts.nonce ?? crypto.getRandomValues(new Uint8Array(32));
+
+  // Derive session address from signature + nonce
+  const combined = new Uint8Array(opts.signature.length + nonce.length);
+  combined.set(opts.signature, 0);
+  combined.set(nonce, opts.signature.length);
+
+  const hashBuffer = await crypto.subtle.digest("SHA-256", combined);
+  const hashArray = new Uint8Array(hashBuffer);
+
+  // Use first 20 bytes as session address (EVM-style)
+  const sessionAddrBytes = hashArray.slice(0, 20);
+  const sessionAddress = ("0x" +
+    Array.from(sessionAddrBytes)
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("")) as WalletAddress;
+
+  // Session ID from hash
+  const id = Array.from(hashArray.slice(20, 32))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+
+  const expiresAt = Date.now() + opts.ttl * 1000;
+
+  const algorithmMap: Record<ChainFamily, SignatureAlgorithm> = {
+    passkey: "p256",
+    evm: "ecdsa-secp256k1",
+    solana: "ed25519",
+  };
+
+  return {
+    id,
+    parentAddress: opts.parentAddress,
+    family: opts.family,
+    sessionAddress,
+    permissions: opts.permissions,
+    expiresAt,
+    isActive: expiresAt > Date.now(),
+    algorithm: algorithmMap[opts.family],
+  };
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { createOrbitMem } from "./client.js";
+export type { NetworkConfig, NetworkId } from "./contracts.js";
+export { DEFAULT_NETWORK, getNetwork, NETWORKS } from "./contracts.js";
+export { createOrbitDBInstance, createVault } from "./data/index.js";
+export { createDiscoveryLayer, MockRegistry, OnChainRegistry } from "./discovery/index.js";
+// Layer-level exports for advanced usage
+export { AESEngine, createEncryptionLayer } from "./encryption/index.js";
+export { createIdentityLayer } from "./identity/index.js";
+export { createPersistenceLayer } from "./persistence/index.js";
+export { createRelaySession, createTransportLayer } from "./transport/index.js";
+export { deriveVaultKeyWithCache } from "./encryption/vault-key.js";
+export * from "./types.js";

package/src/persistence/__tests__/create-agent.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, test } from "bun:test";
+
+describe("createStorachaAgent", () => {
+  test("returns agentDID, proof, and instructions", async () => {
+    const { createStorachaAgent } = await import("../create-agent.js");
+    expect(createStorachaAgent).toBeDefined();
+    expect(typeof createStorachaAgent).toBe("function");
+  });
+});

package/src/persistence/__tests__/persistence.test.ts

@@ -0,0 +1,242 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+import { createPersistenceLayer } from "../persistence-layer.js";
+
+// ── Mode detection ───────────────────────────────────────────
+
+describe("createPersistenceLayer mode detection", () => {
+  test("mock: true → creates mock persistence (archive returns bafy CID)", async () => {
+    const layer = createPersistenceLayer({ mock: true });
+    const snap = await layer.archive({});
+    expect(snap.cid).toMatch(/^bafy/);
+  });
+
+  test("relayUrl → creates managed persistence (methods exist)", () => {
+    const layer = createPersistenceLayer({ relayUrl: "http://localhost:3000" });
+    expect(layer.archive).toBeFunction();
+    expect(layer.retrieve).toBeFunction();
+    expect(layer.listSnapshots).toBeFunction();
+    expect(layer.deleteSnapshot).toBeFunction();
+    expect(layer.getDealStatus).toBeFunction();
+  });
+
+  test("proof → creates direct persistence (methods exist)", () => {
+    const layer = createPersistenceLayer({ proof: "ucan-proof-string" });
+    expect(layer.archive).toBeFunction();
+    expect(layer.retrieve).toBeFunction();
+    expect(layer.listSnapshots).toBeFunction();
+    expect(layer.deleteSnapshot).toBeFunction();
+    expect(layer.getDealStatus).toBeFunction();
+  });
+
+  test("empty config {} → defaults to mock", async () => {
+    const layer = createPersistenceLayer({});
+    const snap = await layer.archive({});
+    expect(snap.cid).toMatch(/^bafy/);
+  });
+});
+
+// ── Mock persistence ─────────────────────────────────────────
+
+describe("PersistenceLayer (mock)", () => {
+  const layer = createPersistenceLayer({ mock: true });
+
+  test("archive creates a snapshot", async () => {
+    const snapshot = await (layer.archive as any)({
+      data: new TextEncoder().encode('{"test": true}'),
+      entryCount: 1,
+    });
+    expect(snapshot.cid).toBeTruthy();
+    expect(snapshot.size).toBeGreaterThan(0);
+    expect(snapshot.encrypted).toBe(true);
+  });
+
+  test("listSnapshots returns archived snapshots", async () => {
+    const list = await layer.listSnapshots();
+    expect(list.length).toBeGreaterThan(0);
+  });
+
+  test("retrieve returns snapshot data", async () => {
+    const snapshots = await layer.listSnapshots();
+    const data = await layer.retrieve(snapshots[0].cid);
+    expect(data).toBeInstanceOf(Uint8Array);
+  });
+
+  test("restore returns merged count", async () => {
+    const snapshots = await layer.listSnapshots();
+    const result = await layer.restore(snapshots[0].cid);
+    expect(result.merged).toBeDefined();
+    expect(result.conflicts).toBe(0);
+  });
+
+  test("deleteSnapshot removes a snapshot", async () => {
+    const snap = await (layer.archive as any)({
+      data: new TextEncoder().encode("delete me"),
+      entryCount: 1,
+    });
+    const beforeCount = (await layer.listSnapshots()).length;
+    await layer.deleteSnapshot(snap.cid);
+    const afterCount = (await layer.listSnapshots()).length;
+    expect(afterCount).toBe(beforeCount - 1);
+  });
+
+  test("getDealStatus returns status for existing snapshot", async () => {
+    const snap = await (layer.archive as any)({
+      data: new TextEncoder().encode("status check"),
+      entryCount: 1,
+    });
+    const deal = await layer.getDealStatus(snap.cid);
+    expect(deal.status).toBe("pending");
+  });
+});
+
+// ── Managed persistence ──────────────────────────────────────
+
+describe("PersistenceLayer (managed)", () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test("archive POSTs to relay and returns mapped snapshot", async () => {
+    const mockResponse = {
+      cid: "bafyrelay123",
+      size: 42,
+      archivedAt: Date.now(),
+      author: "0xabc",
+      entryCount: 5,
+      encrypted: true,
+      filecoinStatus: "pending",
+    };
+
+    globalThis.fetch = mock((url: string, init?: RequestInit) => {
+      expect(url).toBe("http://localhost:3000/v1/snapshots/archive");
+      expect(init?.method).toBe("POST");
+      const body = JSON.parse(init?.body as string);
+      expect(body.data).toBeDefined();
+      expect(body.entryCount).toBe(5);
+      return Promise.resolve(new Response(JSON.stringify(mockResponse), { status: 200 }));
+    }) as unknown as typeof fetch;
+
+    const layer = createPersistenceLayer({
+      relayUrl: "http://localhost:3000",
+      author: "0xabc" as `0x${string}`,
+    });
+
+    const snap = await (layer.archive as any)({
+      data: new TextEncoder().encode("hello relay"),
+      entryCount: 5,
+    });
+
+    expect(snap.cid).toBe("bafyrelay123");
+    expect(snap.entryCount).toBe(5);
+  });
+
+  test("listSnapshots GETs from relay and returns mapped array", async () => {
+    const mockSnapshots = [
+      {
+        cid: "bafy1",
+        size: 10,
+        archivedAt: Date.now(),
+        author: "0xabc",
+        entryCount: 2,
+        encrypted: true,
+        filecoinStatus: "pending",
+      },
+      {
+        cid: "bafy2",
+        size: 20,
+        archivedAt: Date.now(),
+        author: "0xabc",
+        entryCount: 3,
+        encrypted: true,
+        filecoinStatus: "active",
+      },
+    ];
+
+    globalThis.fetch = mock((url: string) => {
+      expect(url).toBe("http://localhost:3000/v1/snapshots");
+      return Promise.resolve(new Response(JSON.stringify(mockSnapshots), { status: 200 }));
+    }) as unknown as typeof fetch;
+
+    const layer = createPersistenceLayer({ relayUrl: "http://localhost:3000" });
+    const list = await layer.listSnapshots();
+
+    expect(list).toHaveLength(2);
+    expect(list[0].cid).toBe("bafy1");
+    expect(list[1].cid).toBe("bafy2");
+  });
+
+  test("retrieve fetches from IPFS gateway", async () => {
+    const payload = new TextEncoder().encode("snapshot data");
+
+    globalThis.fetch = mock((url: string) => {
+      expect(url).toBe("https://w3s.link/ipfs/bafytest");
+      return Promise.resolve(new Response(payload, { status: 200 }));
+    }) as unknown as typeof fetch;
+
+    const layer = createPersistenceLayer({ relayUrl: "http://localhost:3000" });
+    const data = await layer.retrieve("bafytest");
+
+    expect(data).toBeInstanceOf(Uint8Array);
+    expect(new TextDecoder().decode(data)).toBe("snapshot data");
+  });
+
+  test("retrieve uses custom gatewayUrl when provided", async () => {
+    const payload = new TextEncoder().encode("custom gw");
+
+    globalThis.fetch = mock((url: string) => {
+      expect(url).toBe("https://custom.gw/ipfs/bafycustom");
+      return Promise.resolve(new Response(payload, { status: 200 }));
+    }) as unknown as typeof fetch;
+
+    const layer = createPersistenceLayer({
+      relayUrl: "http://localhost:3000",
+      gatewayUrl: "https://custom.gw",
+    });
+    const data = await layer.retrieve("bafycustom");
+    expect(new TextDecoder().decode(data)).toBe("custom gw");
+  });
+
+  test("archive throws on non-ok response", async () => {
+    globalThis.fetch = mock(() => {
+      return Promise.resolve(new Response("Internal Server Error", { status: 500 }));
+    }) as unknown as typeof fetch;
+
+    const layer = createPersistenceLayer({ relayUrl: "http://localhost:3000" });
+    expect((layer.archive as any)({ data: new Uint8Array(0), entryCount: 0 })).rejects.toThrow(
+      "500",
+    );
+  });
+
+  test("deleteSnapshot sends DELETE to relay", async () => {
+    globalThis.fetch = mock((url: string, init?: RequestInit) => {
+      expect(url).toBe("http://localhost:3000/v1/snapshots/bafydel");
+      expect(init?.method).toBe("DELETE");
+      return Promise.resolve(new Response(null, { status: 204 }));
+    }) as unknown as typeof fetch;
+
+    const layer = createPersistenceLayer({ relayUrl: "http://localhost:3000" });
+    await layer.deleteSnapshot("bafydel");
+  });
+
+  test("restore retrieves then returns merge info", async () => {
+    const payload = new TextEncoder().encode("data");
+
+    globalThis.fetch = mock(() => {
+      return Promise.resolve(new Response(payload, { status: 200 }));
+    }) as unknown as typeof fetch;
+
+    const layer = createPersistenceLayer({ relayUrl: "http://localhost:3000" });
+    const result = await layer.restore("bafyrestore");
+    expect(result.merged).toBe(0);
+    expect(result.conflicts).toBe(0);
+  });
+
+  test("getDealStatus returns pending", async () => {
+    const layer = createPersistenceLayer({ relayUrl: "http://localhost:3000" });
+    const deal = await layer.getDealStatus("bafydeal");
+    expect(deal.status).toBe("pending");
+  });
+});

package/src/persistence/create-agent.ts

@@ -0,0 +1,55 @@
+/**
+ * One-time setup helper for BYOS (Bring Your Own Storacha) users.
+ * Creates a Storacha agent, provisions a space, and returns the
+ * serialized proof to store in config.
+ */
+export async function createStorachaAgent(name = "orbitmem"): Promise<{
+  agentDID: string;
+  proof: string;
+  instructions: string;
+}> {
+  const { Client } = await import("@storacha/client");
+
+  const client = await (Client as any).create();
+  const space = await client.createSpace(name);
+  await client.setCurrentSpace(space.did());
+
+  const delegation = await client.createDelegation(client.agent, ["*"], {
+    expiration: Infinity,
+  });
+
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of delegation.archive()) {
+    chunks.push(chunk);
+  }
+  const totalLength = chunks.reduce((acc, c) => acc + c.length, 0);
+  const car = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    car.set(chunk, offset);
+    offset += chunk.length;
+  }
+
+  const proof = btoa(String.fromCharCode(...car));
+
+  return {
+    agentDID: client.agent.did(),
+    proof,
+    instructions: [
+      "Storacha agent created successfully.",
+      `Agent DID: ${client.agent.did()}`,
+      `Space DID: ${space.did()}`,
+      "",
+      "Save the 'proof' string in your OrbitMem config:",
+      "",
+      "  createOrbitMem({ persistence: { proof: '<proof string>' } })",
+      "",
+      "Or set it as an environment variable:",
+      "",
+      "  ORBITMEM_STORACHA_PROOF=<proof string>",
+      "",
+      "Note: You must register this agent with Storacha before uploading.",
+      "Run: npx @storacha/cli login <email>",
+    ].join("\n"),
+  };
+}

package/src/persistence/index.ts

@@ -0,0 +1,2 @@
+export { createStorachaAgent } from "./create-agent.js";
+export { createPersistenceLayer } from "./persistence-layer.js";