@le-space/p2pass 0.1.0

package/dist/recovery/manifest.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @typedef {object} Manifest
+ * @property {number} version - schema version (currently 1)
+ * @property {string} registryAddress - OrbitDB address, e.g. "/orbitdb/zdpu..."
+ * @property {string} delegation - base64-encoded UCAN delegation
+ * @property {string} ownerDid - owner DID, e.g. "did:key:z6Mk..."
+ * @property {string|null} [archiveCID] - CID of encrypted archive on IPFS (for auth-free recovery)
+ * @property {number} updatedAt - unix epoch ms
+ */
+/**
+ * Create a manifest object.
+ *
+ * Pure function — no side effects.
+ *
+ * @param {object} params
+ * @param {string} params.registryAddress
+ * @param {string} params.delegation
+ * @param {string} params.ownerDid
+ * @param {string} [params.archiveCID] - CID of encrypted archive on IPFS
+ * @returns {Manifest}
+ */
+export function createManifest({ registryAddress, delegation, ownerDid, archiveCID }: {
+    registryAddress: string;
+    delegation: string;
+    ownerDid: string;
+    archiveCID?: string | undefined;
+}): Manifest;
+/**
+ * Upload an encrypted archive to IPFS via Storacha.
+ * The archive is stored as a JSON blob accessible via public gateway
+ * without authentication.
+ *
+ * @param {object} storachaClient - Storacha client with `uploadFile`
+ * @param {{ ciphertext: string, iv: string }} archiveData - hex-encoded
+ * @returns {Promise<string>} CID string
+ */
+export function uploadArchiveToIPFS(storachaClient: object, archiveData: {
+    ciphertext: string;
+    iv: string;
+}): Promise<string>;
+/**
+ * Fetch an encrypted archive from the IPFS gateway (no auth needed).
+ *
+ * @param {string} cid - IPFS CID of the archive JSON
+ * @returns {Promise<{ ciphertext: string, iv: string }|null>}
+ */
+export function fetchArchiveFromIPFS(cid: string): Promise<{
+    ciphertext: string;
+    iv: string;
+} | null>;
+/**
+ * Publish a manifest to IPFS (via Storacha) and point an IPNS name at it.
+ *
+ * If an existing IPNS record is found, the revision sequence is incremented.
+ * Otherwise a new v0 revision is created. The encoded revision is persisted
+ * in localStorage so subsequent publishes can increment correctly.
+ *
+ * @param {object} storachaClient - Storacha storage client with `uploadFile`
+ * @param {object} ipnsPrivateKey - libp2p Ed25519 private key (from deriveIPNSKeyPair)
+ * @param {Manifest} manifest
+ * @returns {Promise<{ nameString: string, manifestCID: string }>}
+ */
+export function publishManifest(storachaClient: object, ipnsPrivateKey: object, manifest: Manifest): Promise<{
+    nameString: string;
+    manifestCID: string;
+}>;
+/**
+ * Resolve a manifest from w3name using the IPNS private key.
+ *
+ * @param {object} ipnsPrivateKey - libp2p Ed25519 private key (from deriveIPNSKeyPair)
+ * @returns {Promise<Manifest|null>} parsed manifest, or null on failure
+ */
+export function resolveManifest(ipnsPrivateKey: object): Promise<Manifest | null>;
+/**
+ * Resolve a manifest by its w3name string (read-only, no private key needed).
+ *
+ * @param {string} nameString - w3name identifier, e.g. "k51qzi5uqu5di..."
+ * @returns {Promise<Manifest|null>} parsed manifest, or null on failure
+ */
+export function resolveManifestByName(nameString: string): Promise<Manifest | null>;
+export type Manifest = {
+    /**
+     * - schema version (currently 1)
+     */
+    version: number;
+    /**
+     * - OrbitDB address, e.g. "/orbitdb/zdpu..."
+     */
+    registryAddress: string;
+    /**
+     * - base64-encoded UCAN delegation
+     */
+    delegation: string;
+    /**
+     * - owner DID, e.g. "did:key:z6Mk..."
+     */
+    ownerDid: string;
+    /**
+     * - CID of encrypted archive on IPFS (for auth-free recovery)
+     */
+    archiveCID?: string | null | undefined;
+    /**
+     * - unix epoch ms
+     */
+    updatedAt: number;
+};

package/dist/recovery/manifest.js

@@ -0,0 +1,243 @@
+/**
+ * IPNS manifest publishing and resolution via Storacha w3name.
+ *
+ * A recovery manifest is a small JSON document pinned on IPFS (via Storacha)
+ * and pointed to by a deterministic IPNS name derived from the user's PRF
+ * seed. It contains enough information to locate and restore the user's
+ * OrbitDB registry from any device.
+ *
+ * @module recovery/manifest
+ */
+
+import * as W3Name from 'w3name';
+
+const PREFIX = '[recovery]';
+
+/** Gateway URL template for fetching IPFS content */
+const GATEWAY = 'https://{cid}.ipfs.w3s.link/';
+
+/** localStorage key for persisting the latest IPNS revision */
+const REVISION_KEY = 'p2p_passkeys_ipns_revision';
+
+/** Fetch timeout for gateway requests (ms) */
+const FETCH_TIMEOUT_MS = 30_000;
+
+/**
+ * @typedef {object} Manifest
+ * @property {number} version - schema version (currently 1)
+ * @property {string} registryAddress - OrbitDB address, e.g. "/orbitdb/zdpu..."
+ * @property {string} delegation - base64-encoded UCAN delegation
+ * @property {string} ownerDid - owner DID, e.g. "did:key:z6Mk..."
+ * @property {string|null} [archiveCID] - CID of encrypted archive on IPFS (for auth-free recovery)
+ * @property {number} updatedAt - unix epoch ms
+ */
+
+/**
+ * Create a manifest object.
+ *
+ * Pure function — no side effects.
+ *
+ * @param {object} params
+ * @param {string} params.registryAddress
+ * @param {string} params.delegation
+ * @param {string} params.ownerDid
+ * @param {string} [params.archiveCID] - CID of encrypted archive on IPFS
+ * @returns {Manifest}
+ */
+export function createManifest({ registryAddress, delegation, ownerDid, archiveCID }) {
+  return {
+    version: 1,
+    registryAddress,
+    delegation,
+    ownerDid,
+    archiveCID: archiveCID || null,
+    updatedAt: Date.now(),
+  };
+}
+
+/**
+ * Upload an encrypted archive to IPFS via Storacha.
+ * The archive is stored as a JSON blob accessible via public gateway
+ * without authentication.
+ *
+ * @param {object} storachaClient - Storacha client with `uploadFile`
+ * @param {{ ciphertext: string, iv: string }} archiveData - hex-encoded
+ * @returns {Promise<string>} CID string
+ */
+export async function uploadArchiveToIPFS(storachaClient, archiveData) {
+  const blob = new Blob(
+    [JSON.stringify({ ciphertext: archiveData.ciphertext, iv: archiveData.iv })],
+    { type: 'application/json' }
+  );
+  const cid = await storachaClient.uploadFile(blob);
+  console.log(PREFIX, 'Encrypted archive uploaded to IPFS:', cid.toString());
+  return cid.toString();
+}
+
+/**
+ * Fetch an encrypted archive from the IPFS gateway (no auth needed).
+ *
+ * @param {string} cid - IPFS CID of the archive JSON
+ * @returns {Promise<{ ciphertext: string, iv: string }|null>}
+ */
+export async function fetchArchiveFromIPFS(cid) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const url = GATEWAY.replace('{cid}', cid);
+    console.log(PREFIX, 'Fetching encrypted archive from gateway:', cid);
+    const res = await fetch(url, { signal: controller.signal });
+    if (!res.ok) {
+      console.log(PREFIX, `Gateway returned ${res.status} for archive CID ${cid}`);
+      return null;
+    }
+    const data = await res.json();
+    if (!data.ciphertext || !data.iv) {
+      console.log(PREFIX, 'Invalid archive format — missing ciphertext or iv');
+      return null;
+    }
+    return data;
+  } catch (err) {
+    console.log(PREFIX, 'Failed to fetch archive from gateway:', err?.message ?? err);
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Publish a manifest to IPFS (via Storacha) and point an IPNS name at it.
+ *
+ * If an existing IPNS record is found, the revision sequence is incremented.
+ * Otherwise a new v0 revision is created. The encoded revision is persisted
+ * in localStorage so subsequent publishes can increment correctly.
+ *
+ * @param {object} storachaClient - Storacha storage client with `uploadFile`
+ * @param {object} ipnsPrivateKey - libp2p Ed25519 private key (from deriveIPNSKeyPair)
+ * @param {Manifest} manifest
+ * @returns {Promise<{ nameString: string, manifestCID: string }>}
+ */
+export async function publishManifest(storachaClient, ipnsPrivateKey, manifest) {
+  // 1. Derive the WritableName from the raw key bytes
+  const name = await W3Name.from(ipnsPrivateKey.raw);
+
+  // 2. Upload the manifest JSON to Storacha
+  const manifestBlob = new Blob([JSON.stringify(manifest)], { type: 'application/json' });
+  const cid = await storachaClient.uploadFile(manifestBlob);
+
+  // 3. Build the IPNS value pointing at the uploaded CID
+  const value = `/ipfs/${cid.toString()}`;
+
+  // 4. Create or increment the IPNS revision
+  let revision;
+  try {
+    const current = await W3Name.resolve(name);
+    revision = await W3Name.increment(current, value);
+  } catch {
+    // No existing record — create the initial revision
+    revision = await W3Name.v0(name, value);
+  }
+
+  // 5. Publish the revision
+  await W3Name.publish(revision, name.key);
+
+  // 6. Persist the revision locally for future increments
+  try {
+    const encoded = W3Name.Revision.encode(revision);
+    localStorage.setItem(REVISION_KEY, JSON.stringify(Array.from(encoded)));
+  } catch {
+    console.log(PREFIX, 'Could not persist IPNS revision to localStorage');
+  }
+
+  console.log(PREFIX, `Published manifest to w3name: ${name.toString()}`);
+
+  return {
+    nameString: name.toString(),
+    manifestCID: cid.toString(),
+  };
+}
+
+/**
+ * Resolve a manifest from w3name using the IPNS private key.
+ *
+ * @param {object} ipnsPrivateKey - libp2p Ed25519 private key (from deriveIPNSKeyPair)
+ * @returns {Promise<Manifest|null>} parsed manifest, or null on failure
+ */
+export async function resolveManifest(ipnsPrivateKey) {
+  try {
+    const name = await W3Name.from(ipnsPrivateKey.raw);
+    console.log(PREFIX, `Resolving manifest from w3name: ${name.toString()}`);
+    return await fetchManifestForName(name);
+  } catch (err) {
+    console.log(PREFIX, 'Failed to resolve manifest:', err?.message ?? err);
+    return null;
+  }
+}
+
+/**
+ * Resolve a manifest by its w3name string (read-only, no private key needed).
+ *
+ * @param {string} nameString - w3name identifier, e.g. "k51qzi5uqu5di..."
+ * @returns {Promise<Manifest|null>} parsed manifest, or null on failure
+ */
+export async function resolveManifestByName(nameString) {
+  try {
+    const name = W3Name.parse(nameString);
+    console.log(PREFIX, `Resolving manifest from w3name: ${nameString}`);
+    return await fetchManifestForName(name);
+  } catch (err) {
+    console.log(PREFIX, 'Failed to resolve manifest by name:', err?.message ?? err);
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the IPNS name, fetch the manifest from the IPFS gateway, and
+ * validate the basic structure.
+ *
+ * @param {object} name - W3Name Name object (writable or read-only)
+ * @returns {Promise<Manifest|null>}
+ * @private
+ */
+async function fetchManifestForName(name) {
+  // Resolve the IPNS record to get the /ipfs/... value
+  const revision = await W3Name.resolve(name);
+  const ipfsPath = revision.value; // e.g. "/ipfs/bafyabc..."
+
+  // Extract the CID from the path
+  const cid = ipfsPath.replace(/^\/ipfs\//, '');
+  if (!cid) {
+    console.log(PREFIX, 'Resolved IPNS value has no CID:', ipfsPath);
+    return null;
+  }
+
+  // Fetch the manifest from the Storacha/IPFS gateway with a timeout
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  try {
+    const url = GATEWAY.replace('{cid}', cid);
+    const res = await fetch(url, { signal: controller.signal });
+
+    if (!res.ok) {
+      console.log(PREFIX, `Gateway returned ${res.status} for CID ${cid}`);
+      return null;
+    }
+
+    const manifest = await res.json();
+
+    // Basic validation
+    if (!manifest.version || !manifest.registryAddress) {
+      console.log(PREFIX, 'Invalid manifest schema — missing version or registryAddress');
+      return null;
+    }
+
+    return manifest;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/dist/registry/device-registry.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Convert P-256 x/y byte arrays from a WebAuthn attestation into JWK format.
+ * @param {Uint8Array} x - 32-byte x coordinate
+ * @param {Uint8Array} y - 32-byte y coordinate
+ * @returns {Object} JWK object
+ */
+export function coseToJwk(x: Uint8Array, y: Uint8Array): Object;
+/**
+ * Hash a string to a 64-char lowercase hex key for DB storage.
+ * @param {string} input - string to hash
+ * @returns {Promise<string>} 64-char hex string
+ */
+export function hashCredentialId(input: string): Promise<string>;
+/**
+ * Open (or create) the multi-device registry KV database.
+ *
+ * @param {Object} orbitdb - OrbitDB instance
+ * @param {string} ownerIdentityId - Ed25519 DID of the device creating the registry
+ * @param {string} [address] - Existing DB address to reopen (for Device B)
+ * @returns {Promise<Object>} Opened OrbitDB KeyValue database
+ */
+export function openDeviceRegistry(orbitdb: Object, ownerIdentityId: string, address?: string): Promise<Object>;
+/**
+ * Register a device entry in the registry.
+ * @param {Object} db - OrbitDB KV database
+ * @param {Object} entry - { credential_id, public_key, device_label, created_at, status, ed25519_did }
+ */
+export function registerDevice(db: Object, entry: Object): Promise<void>;
+/**
+ * List all registered devices from the registry.
+ * @param {Object} db - OrbitDB KV database
+ * @returns {Promise<Array>} Array of device entry objects
+ */
+export function listDevices(db: Object): Promise<any[]>;
+/**
+ * Look up a device by its credential ID.
+ * @param {Object} db - OrbitDB KV database
+ * @param {string} credentialId - base64url credential ID
+ * @returns {Promise<Object|null>}
+ */
+export function getDeviceByCredentialId(db: Object, credentialId: string): Promise<Object | null>;
+/**
+ * Look up a device by its Ed25519 DID.
+ * @param {Object} db - OrbitDB KV database
+ * @param {string} did - Ed25519 DID (did:key:z6Mk...)
+ * @returns {Promise<Object|null>}
+ */
+export function getDeviceByDID(db: Object, did: string): Promise<Object | null>;
+/**
+ * Grant write access to a new device DID via OrbitDBAccessController.
+ * @param {Object} db - OrbitDB KV database (must use OrbitDBAccessController)
+ * @param {string} did - Ed25519 DID of the new device
+ */
+export function grantDeviceWriteAccess(db: Object, did: string): Promise<void>;
+/**
+ * Revoke write access from a device DID and mark its registry entry as 'revoked'.
+ * @param {Object} db - OrbitDB KV database
+ * @param {string} did - Ed25519 DID to revoke
+ */
+export function revokeDeviceAccess(db: Object, did: string): Promise<void>;
+/**
+ * Store a UCAN delegation in the registry.
+ * @param {Object} db - OrbitDB KV database
+ * @param {string} delegationBase64 - raw delegation string
+ * @param {string} [spaceDid] - Storacha space DID
+ * @param {string} [label] - human-readable label
+ */
+export function storeDelegationEntry(db: Object, delegationBase64: string, spaceDid?: string, label?: string): Promise<void>;
+/**
+ * List all stored UCAN delegations.
+ * @param {Object} db - OrbitDB KV database
+ * @returns {Promise<Array>}
+ */
+export function listDelegations(db: Object): Promise<any[]>;
+/**
+ * Get a specific delegation by its base64 string.
+ * @param {Object} db - OrbitDB KV database
+ * @param {string} delegationBase64
+ * @returns {Promise<Object|null>}
+ */
+export function getDelegation(db: Object, delegationBase64: string): Promise<Object | null>;
+/**
+ * Remove a delegation from the registry.
+ * @param {Object} db - OrbitDB KV database
+ * @param {string} delegationBase64
+ */
+export function removeDelegation(db: Object, delegationBase64: string): Promise<void>;
+/**
+ * Store an encrypted Ed25519 archive in the registry.
+ * @param {Object} db - OrbitDB KV database
+ * @param {string} did - Ed25519 DID
+ * @param {string} ciphertext - hex-encoded ciphertext
+ * @param {string} iv - hex-encoded IV
+ */
+export function storeArchiveEntry(db: Object, did: string, ciphertext: string, iv: string): Promise<void>;
+/**
+ * Get an encrypted archive entry by DID.
+ * @param {Object} db - OrbitDB KV database
+ * @param {string} did
+ * @returns {Promise<Object|null>}
+ */
+export function getArchiveEntry(db: Object, did: string): Promise<Object | null>;
+/**
+ * Store Ed25519 keypair metadata (no private key) in the registry.
+ * @param {Object} db - OrbitDB KV database
+ * @param {string} did - Ed25519 DID
+ * @param {string} publicKeyHex - hex-encoded public key
+ */
+export function storeKeypairEntry(db: Object, did: string, publicKeyHex: string): Promise<void>;
+/**
+ * Get keypair metadata by DID.
+ * @param {Object} db - OrbitDB KV database
+ * @param {string} did
+ * @returns {Promise<Object|null>}
+ */
+export function getKeypairEntry(db: Object, did: string): Promise<Object | null>;
+/**
+ * List all stored keypair entries.
+ * @param {Object} db - OrbitDB KV database
+ * @returns {Promise<Array>}
+ */
+export function listKeypairs(db: Object): Promise<any[]>;