@le-space/aleph-bootstrap 0.9.3 → 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

@@ -103,6 +103,15 @@ 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 {
@@ -219,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, isBrowserDialableMultiaddr, 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

@@ -653,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;
@@ -692,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,
@@ -757,6 +768,7 @@ export {
   fetchAlephBootstrapPosts,
   filterPublicMultiaddrs,
   filterRelayBootstrapPostsByProfile,
+  filterRelayBootstrapPostsByRegistration,
   isBrowserDialableMultiaddr,
   isPublicMultiaddr,
   relayBootstrapMultiaddrsHash,

package/package.json

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