@le-space/aleph-bootstrap 0.9.2 → 0.9.4

package/README.md

@@ -12,6 +12,8 @@ It is designed for two complementary jobs:
 
 - `discoverAlephBootstrapMultiaddrs(options)`
 - `createLibp2pAlephBootstrap(options)`
+- `filterRelayBootstrapPostsByProfile(posts, profile?)`
+- `filterRelayBootstrapPostsByRegistration(posts, registrationId?)`
 - `filterPublicMultiaddrs(addrs, options?)`
 - `createRelayBootstrapPost(options)`
 - `signRelayBootstrapAuthorization(args)`
@@ -45,6 +47,34 @@ By default, discovery will:
 - verify dual-key records when they are present
 - ignore malformed or invalid dual-key records
 
+## Scoping discovery
+
+The channel is shared. Several relay implementations register in it, and so
+does every throwaway relay an E2E run starts — under the same profile as the
+production one, with a registration that outlives the machine it describes,
+because guests self-publish with generated keys and no remaining key can
+FORGET the post.
+
+Two scopes, and most consumers want both:
+
+```ts
+const list = await discoverAlephBootstrapMultiaddrs({
+  profile: 'orbitdb-relay',                          // not uc-go-peer's relays
+  registrationId: 'relay:orbitdb-relay:orbitdb-relay' // and not the E2E ones
+})
+```
+
+`profile` keeps out relays a consumer cannot use at all — an orbitdb app that
+dials a `uc-go-peer` relay never gets a shared circuit and sits at
+`candidates: 0`. `registrationId` keeps out its own corpses: measured
+downstream, a browser probe wave against an unscoped list spent its outbound
+stream budget on dead addresses and wrote off the one healthy relay along with
+them.
+
+Use `registrationId` for anything that bakes addresses into a build or dials
+them on start. Omit both to see the whole channel, which is what a dashboard
+wants.
+
 If a consumer wants to require the stronger model:
 
 ```ts

package/index.d.ts

@@ -85,6 +85,13 @@ interface DiscoverAlephBootstrapOptions {
     maxAgeMs?: number;
     compactMultiaddrLimit?: number;
     browserDialableOnly?: boolean;
+    /**
+     * Keep plaintext `/ws` relays in a browser-dialable result. Defaults to
+     * false so an https page never receives an address the browser will block as
+     * mixed content. Set it for consumers that dial from node or a plain-http
+     * origin.
+     */
+    allowInsecureWebSockets?: boolean;
     requireDualKeyAttestation?: boolean;
     verifyDualKeyAttestation?: boolean;
     /**
@@ -96,11 +103,29 @@ interface DiscoverAlephBootstrapOptions {
      * When omitted, posts of every profile are returned (previous behaviour).
      */
     profile?: string | readonly string[];
+    /**
+     * Restrict discovery further, to the registrations published under this id
+     * (e.g. `"relay:orbitdb-relay:orbitdb-relay"`). Profile is not fine enough:
+     * an E2E run's throwaway relays register under the same profile as the
+     * production one, and a registration outlives the machine it describes. Use
+     * this for anything that bakes addresses into a build or dials them on
+     * start; omit it to see the whole channel.
+     */
+    registrationId?: string | readonly string[];
     fetch?: typeof fetch;
 }
 interface FilterPublicMultiaddrsOptions {
     browserDialableOnly?: boolean;
     requirePeerId?: boolean;
+    /**
+     * Keep plaintext `/ws` addresses in the browser-dialable set. Defaults to
+     * false: a page served over https cannot open a `ws://` socket, the browser
+     * blocks it as mixed content, so a plaintext relay is dead weight in a
+     * browser bootstrap list. Publishers pass true — a relay should still
+     * announce the plaintext port it really serves, for node peers that can use
+     * it.
+     */
+    allowInsecureWebSockets?: boolean;
 }
 interface CreateRelayBootstrapPostOptions {
     sender: string;
@@ -122,7 +147,14 @@ interface CreateRelayBootstrapPostOptions {
 }
 type RelayBootstrapTrustMode = "wallet-signed" | "dual-key-attested";
 declare function relayBootstrapMultiaddrsHash(addrs: readonly string[]): string;
+/**
+ * Publish-side helper: pick the addresses a relay announces to the registry.
+ * Plaintext `/ws` is kept here on purpose — announcing the port the relay
+ * really serves is honest, and node peers can dial it. Browsers filter it out
+ * again on the read side, where the https origin makes it undialable.
+ */
 declare function selectCompactRelayBootstrapMultiaddrs(addrs: readonly string[], limit?: number): string[];
+declare function isBrowserDialableMultiaddr(addr: string, options?: Pick<FilterPublicMultiaddrsOptions, "allowInsecureWebSockets">): boolean;
 declare function dedupeMultiaddrs(addrs: readonly string[]): string[];
 declare function isPublicMultiaddr(addr: string): boolean;
 declare function filterPublicMultiaddrs(addrs: readonly string[], options?: FilterPublicMultiaddrsOptions): string[];
@@ -196,10 +228,30 @@ declare function selectCurrentRelayBootstrapPosts(posts: readonly RelayBootstrap
  * A missing/empty filter is a no-op so existing callers are unaffected.
  */
 declare function filterRelayBootstrapPostsByProfile(posts: readonly RelayBootstrapPostRecord[], profile?: string | readonly string[]): RelayBootstrapPostRecord[];
+/**
+ * Keep only the registrations a consumer published for itself.
+ *
+ * Profile is not fine enough. Every ephemeral relay an E2E run starts
+ * registers under the same profile as the production one - as
+ * `relay:<profile>:<name>-e2e-*` - and a registration outlives the machine it
+ * describes, because guests self-publish with generated keys and no remaining
+ * key can FORGET the post. So the channel accumulates registrations that are
+ * indistinguishable from the real one by profile alone, and were alive when
+ * they were written.
+ *
+ * Measured downstream: a browser probe wave against that list exhausted its
+ * outbound stream budget on dead addresses and wrote off the one healthy relay
+ * along with the corpses, leaving both browsers with nothing to dial.
+ *
+ * Omitting the scope returns every registration, which is the previous
+ * behaviour and the right default for a consumer that wants to see the channel
+ * rather than its own corner of it.
+ */
+declare function filterRelayBootstrapPostsByRegistration(posts: readonly RelayBootstrapPostRecord[], registrationId?: string | readonly string[]): RelayBootstrapPostRecord[];
 declare function discoverAlephBootstrapMultiaddrs(options?: DiscoverAlephBootstrapOptions): Promise<string[]>;
 declare function createLibp2pAlephBootstrap(options?: DiscoverAlephBootstrapOptions & {
     timeout?: number;
     tagName?: string;
 }): Promise<ReturnType<typeof bootstrap>>;
 
-export { type CreateRelayBootstrapPostOptions, DEFAULT_ALEPH_API_HOST, DEFAULT_ALEPH_BOOTSTRAP_CHANNEL, DEFAULT_ALEPH_BOOTSTRAP_POST_TYPE, DEFAULT_ALEPH_BOOTSTRAP_REF, DEFAULT_BOOTSTRAP_COMPACT_MULTIADDR_LIMIT, DEFAULT_BOOTSTRAP_MAX_AGE_MS, DEFAULT_BOOTSTRAP_MAX_PAGES, DEFAULT_BOOTSTRAP_PAGINATION, type DiscoverAlephBootstrapOptions, type FilterPublicMultiaddrsOptions, RELAY_BOOTSTRAP_SIGNATURE_SCHEME, type RelayBootstrapAuthorizationPayload, type RelayBootstrapAuthorizationRecord, type RelayBootstrapContent, type RelayBootstrapPostContent, type RelayBootstrapPostRecord, type RelayBootstrapProofPayload, type RelayBootstrapProofRecord, type RelayBootstrapProofSigner, type RelayBootstrapTrustMode, type RelayBootstrapVerificationResult, buildRelayBootstrapPostContent, createLibp2pAlephBootstrap, createRelayBootstrapPost, dedupeMultiaddrs, discoverAlephBootstrapMultiaddrs, fetchAlephBootstrapPosts, filterPublicMultiaddrs, filterRelayBootstrapPostsByProfile, isPublicMultiaddr, relayBootstrapMultiaddrsHash, relayBootstrapTrustMode, selectCompactRelayBootstrapMultiaddrs, selectCurrentRelayBootstrapPosts, signRelayBootstrapAuthorization, signRelayBootstrapProof, verifyRelayBootstrapAuthorization, verifyRelayBootstrapDualKeyContent, verifyRelayBootstrapProof };
+export { type CreateRelayBootstrapPostOptions, DEFAULT_ALEPH_API_HOST, DEFAULT_ALEPH_BOOTSTRAP_CHANNEL, DEFAULT_ALEPH_BOOTSTRAP_POST_TYPE, DEFAULT_ALEPH_BOOTSTRAP_REF, DEFAULT_BOOTSTRAP_COMPACT_MULTIADDR_LIMIT, DEFAULT_BOOTSTRAP_MAX_AGE_MS, DEFAULT_BOOTSTRAP_MAX_PAGES, DEFAULT_BOOTSTRAP_PAGINATION, type DiscoverAlephBootstrapOptions, type FilterPublicMultiaddrsOptions, RELAY_BOOTSTRAP_SIGNATURE_SCHEME, type RelayBootstrapAuthorizationPayload, type RelayBootstrapAuthorizationRecord, type RelayBootstrapContent, type RelayBootstrapPostContent, type RelayBootstrapPostRecord, type RelayBootstrapProofPayload, type RelayBootstrapProofRecord, type RelayBootstrapProofSigner, type RelayBootstrapTrustMode, type RelayBootstrapVerificationResult, buildRelayBootstrapPostContent, createLibp2pAlephBootstrap, createRelayBootstrapPost, dedupeMultiaddrs, discoverAlephBootstrapMultiaddrs, fetchAlephBootstrapPosts, filterPublicMultiaddrs, filterRelayBootstrapPostsByProfile, filterRelayBootstrapPostsByRegistration, isBrowserDialableMultiaddr, isPublicMultiaddr, relayBootstrapMultiaddrsHash, relayBootstrapTrustMode, selectCompactRelayBootstrapMultiaddrs, selectCurrentRelayBootstrapPosts, signRelayBootstrapAuthorization, signRelayBootstrapProof, verifyRelayBootstrapAuthorization, verifyRelayBootstrapDualKeyContent, verifyRelayBootstrapProof };

package/index.js

@@ -58,7 +58,8 @@ function browserMultiaddrTransport(addr) {
 }
 function selectCompactRelayBootstrapMultiaddrs(addrs, limit = DEFAULT_BOOTSTRAP_COMPACT_MULTIADDR_LIMIT) {
   const entries = filterPublicMultiaddrs(addrs, {
-    browserDialableOnly: true
+    browserDialableOnly: true,
+    allowInsecureWebSockets: true
   }).map((addr, index) => ({
     addr,
     index,
@@ -134,12 +135,23 @@ function isLocalHostname(host) {
 function hasPeerId(addr) {
   return splitMultiaddr(addr).includes("p2p");
 }
-function isBrowserDialableMultiaddr(addr) {
+function isSecureWebSocketMultiaddr(addr) {
+  const parts = splitMultiaddr(addr.toLowerCase());
+  if (parts.includes("wss")) return true;
+  const wsIndex = parts.indexOf("ws");
+  return wsIndex > 0 && parts.lastIndexOf("tls", wsIndex) >= 0;
+}
+function isWebSocketMultiaddr(addr) {
+  const parts = splitMultiaddr(addr.toLowerCase());
+  return parts.includes("ws") || parts.includes("wss");
+}
+function isBrowserDialableMultiaddr(addr, options = {}) {
   const normalized = addr.toLowerCase();
   if (normalized.includes("/webtransport") || normalized.includes("/webrtc-direct")) {
     return normalized.includes("/certhash/");
   }
-  return normalized.includes("/ws") || normalized.includes("/wss");
+  if (!isWebSocketMultiaddr(addr)) return false;
+  return (options.allowInsecureWebSockets ?? false) || isSecureWebSocketMultiaddr(addr);
 }
 function dedupeMultiaddrs(addrs) {
   const seen = /* @__PURE__ */ new Set();
@@ -173,7 +185,9 @@ function filterPublicMultiaddrs(addrs, options = {}) {
   return dedupeMultiaddrs(addrs).filter((addr) => {
     if (!isPublicMultiaddr(addr)) return false;
     if (options.requirePeerId !== false && !hasPeerId(addr)) return false;
-    if (options.browserDialableOnly && !isBrowserDialableMultiaddr(addr)) {
+    if (options.browserDialableOnly && !isBrowserDialableMultiaddr(addr, {
+      allowInsecureWebSockets: options.allowInsecureWebSockets
+    })) {
       return false;
     }
     return true;
@@ -288,7 +302,8 @@ function buildRelayBootstrapPostContent(args) {
   const updatedAt = args.now ?? Date.now();
   const fullMultiaddrs = filterPublicMultiaddrs(args.multiaddrs);
   const fullBrowserMultiaddrs = args.browserMultiaddrs ? filterPublicMultiaddrs(args.browserMultiaddrs, {
-    browserDialableOnly: true
+    browserDialableOnly: true,
+    allowInsecureWebSockets: true
   }) : void 0;
   const compactMultiaddrs = selectCompactRelayBootstrapMultiaddrs(
     fullBrowserMultiaddrs && fullBrowserMultiaddrs.length > 0 ? fullBrowserMultiaddrs : fullMultiaddrs,
@@ -376,7 +391,8 @@ async function signRelayBootstrapAuthorization(args) {
 async function signRelayBootstrapProof(args) {
   const fullMultiaddrs = filterPublicMultiaddrs(args.multiaddrs);
   const fullBrowserMultiaddrs = args.browserMultiaddrs ? filterPublicMultiaddrs(args.browserMultiaddrs, {
-    browserDialableOnly: true
+    browserDialableOnly: true,
+    allowInsecureWebSockets: true
   }) : void 0;
   const compactMultiaddrs = selectCompactRelayBootstrapMultiaddrs(
     fullBrowserMultiaddrs && fullBrowserMultiaddrs.length > 0 ? fullBrowserMultiaddrs : fullMultiaddrs,
@@ -637,6 +653,14 @@ function filterRelayBootstrapPostsByProfile(posts, profile) {
     (post) => post.content != null && allowed.has(String(post.content.profile))
   );
 }
+function filterRelayBootstrapPostsByRegistration(posts, registrationId) {
+  const wanted = (typeof registrationId === "string" ? [registrationId] : registrationId ?? []).map((entry) => entry.trim()).filter(Boolean);
+  if (wanted.length === 0) return [...posts];
+  const allowed = new Set(wanted);
+  return posts.filter(
+    (post) => post.content != null && allowed.has(String(post.content.registrationId))
+  );
+}
 async function filterTrustedRelayBootstrapPosts(posts, options = {}) {
   const requireDualKeyAttestation = options.requireDualKeyAttestation ?? false;
   const verifyDualKeyAttestation = options.verifyDualKeyAttestation ?? true;
@@ -676,11 +700,14 @@ async function discoverAlephBootstrapMultiaddrs(options = {}) {
       pagination
     });
     collectedPosts.push(...pagePosts);
-    const selectedPosts = filterRelayBootstrapPostsByProfile(
-      selectCurrentRelayBootstrapPosts(collectedPosts, {
-        maxAgeMs: options.maxAgeMs
-      }),
-      options.profile
+    const selectedPosts = filterRelayBootstrapPostsByRegistration(
+      filterRelayBootstrapPostsByProfile(
+        selectCurrentRelayBootstrapPosts(collectedPosts, {
+          maxAgeMs: options.maxAgeMs
+        }),
+        options.profile
+      ),
+      options.registrationId
     );
     const trustedPosts = await filterTrustedRelayBootstrapPosts(selectedPosts, {
       requireDualKeyAttestation: options.requireDualKeyAttestation,
@@ -688,7 +715,8 @@ async function discoverAlephBootstrapMultiaddrs(options = {}) {
     });
     const addrs = relayBootstrapPostsToMultiaddrs(
       trustedPosts,
-      browserDialableOnly
+      browserDialableOnly,
+      options.allowInsecureWebSockets ?? false
     );
     if (addrs.length > 0) {
       return addrs;
@@ -699,7 +727,7 @@ async function discoverAlephBootstrapMultiaddrs(options = {}) {
   }
   return [];
 }
-function relayBootstrapPostsToMultiaddrs(posts, browserDialableOnly) {
+function relayBootstrapPostsToMultiaddrs(posts, browserDialableOnly, allowInsecureWebSockets) {
   const addrs = [];
   for (const post of posts) {
     const content = post.content;
@@ -707,7 +735,8 @@ function relayBootstrapPostsToMultiaddrs(posts, browserDialableOnly) {
     const candidates = browserDialableOnly && Array.isArray(content.browserMultiaddrs) && content.browserMultiaddrs.length > 0 ? content.browserMultiaddrs : content.multiaddrs;
     addrs.push(
       ...filterPublicMultiaddrs(candidates, {
-        browserDialableOnly
+        browserDialableOnly,
+        allowInsecureWebSockets
       })
     );
   }
@@ -739,6 +768,8 @@ export {
   fetchAlephBootstrapPosts,
   filterPublicMultiaddrs,
   filterRelayBootstrapPostsByProfile,
+  filterRelayBootstrapPostsByRegistration,
+  isBrowserDialableMultiaddr,
   isPublicMultiaddr,
   relayBootstrapMultiaddrsHash,
   relayBootstrapTrustMode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/aleph-bootstrap",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Aleph-backed libp2p bootstrap discovery and relay registration helpers.",
   "license": "MIT",
   "type": "module",