@byokit/connect 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.5.1 (2026-10-17)
+
+- Dependency update: pins @byokit/secrets 0.5.2.
+
 ## 0.5.0 (2026-10-17)
 
 - FEAT: `deviceSignIn(provider, options)` connects a person with an RFC 8628 device code: it returns `{ userCode, verificationUri, expiresAt, finish(), cancel() }`, polls with the app's own OAuth client ID (pending waits, `slow_down` adds 5 s), and stores the grant in the person's keystore only when they approve. An expired code rejects with `ConnectError` `expired`; a person cancelling on the provider's page, or `cancel()`, rejects with `declined`, and neither stores anything. New `github` provider (`device` endpoints on github.com) and `Provider.device`; `ConnectOptions.redirectUri` is now optional (`signIn()` still requires it). RFC 8628 error codes stay readable in `ConnectError.cause`. The `expired` message now reads "This sign-in has expired. Start again."

package/README.md

@@ -218,6 +218,44 @@ A 401 triggers one refresh/retry; redirects are refused. Close clients before
 `disconnect()` to release their streams. Arbitrary unauthenticated MCP servers and
 legacy HTTP+SSE transports are outside this sign-in kit's initial scope.
 
+## List apps to connect
+
+```ts
+import { catalog, connect, knownApps, mcpDirectory } from '@byokit/connect';
+import type { Keystore } from '@byokit/secrets';
+
+declare const store: Keystore;
+const apps = await catalog([knownApps, mcpDirectory('https://directory.your-app.example/v0/servers?version=latest')]);
+const app = apps[0]; // { id, name, icon?, auth, ...the Provider connect() takes }
+const connection = connect(app, { store, person: 'Umer', redirectUri: 'https://your-app.example/connect/callback' });
+const flow = await connection.signIn(); // Or connectLoopback(app, ...); deviceSignIn(app, ...) when app.auth is 'device'.
+```
+
+`catalog(sources)` lists the apps of the sources the host picks, in that order; an
+id listed twice keeps its first entry. Nothing is listed, and nothing is read, by
+default. Every listed app is a `Provider`, so it signs in through the same
+`connect()`, `connectLoopback()` and `deviceSignIn()` as above, under the same
+keystore record as the preset of that id. `auth` says how: `oauth` needs the app's
+registered `client`, `discovery` finds sign-in from the app's MCP server and
+registers itself where offered, `device` shows a typed code. `icon` is an HTTPS
+image address from the listing; render it as untrusted content.
+
+- `knownApps` lists the kit's presets (`providers`) and reads nothing.
+- `mcpDirectory(url, { fetch?, timeoutMs? })` reads a remote MCP directory that
+  answers in the MCP registry's `GET /v0/servers` shape, following
+  `metadata.nextCursor` (at most 100 pages), only when listed. It keeps servers
+  with a streamable HTTP remote and no address variables or required headers;
+  local packages, legacy SSE remotes and key-header servers are left out. The URL
+  must be HTTPS (or loopback); for the MCP registry add `version=latest`.
+- Any object with `list(): Promise<CatalogApp[]>` is a source, such as the host's
+  own managed connector directory behind its server.
+
+A directory that fails or answers in another shape rejects with `ConnectError`
+code `catalog` (with its `status`), an unreachable one with `network`; the whole
+`catalog()` call rejects with it, so list a source on its own to keep the rest.
+The host vouches for the directories it names: signing in to a listed app talks
+to the server that listing names.
+
 ## Read and search Gmail
 
 ```ts
@@ -342,7 +380,8 @@ the connection handle; never persist its returned access token separately.
 ## Crewhouse adoption
 
 Replace the OAuth, token-file and `RemoteMcp` portions of `src/connections.ts` with
-one handle per member/app. Pass the member's keystore and member ID, the house Google
+one handle per member/app, listing the apps from `catalog([knownApps])` (add `mcpDirectory(url)`
+or the host's own source to list more). Pass the member's keystore and member ID, the house Google
 client from `googleClientFile` when applicable, and Crewhouse's callback address. Keep
 flow handles in the host's callback routing table until completion/cancellation.
 Crewhouse retains its own connection screen, Google setup guidance and tool gates.
@@ -359,7 +398,8 @@ sh scripts/test.sh 'packages/connect/test/*.test.ts'
 ```
 
 `packages/connect/test/journey-connect.test.ts` drives the built package the way a
-host app does — `connect`/`signIn`/`deviceSignIn`/`token`/`mcp`, the loopback listener, the house
+host app does — `connect`/`signIn`/`deviceSignIn`/`token`/`mcp`, `catalog` over the known apps and a
+loopback MCP directory (one listed app connected end to end), the loopback listener, the house
 Google client, `MailReader`/`MailSender` and `MailHistory`. Fake providers and a real
 loopback callback only. It covers PKCE/state and exact-callback binding, per-person
 isolation, refresh races and revocation, discovery/DCR/resource binding, rich MCP

package/dist/catalog.d.ts

@@ -0,0 +1,26 @@
+import type { Provider } from './types.ts';
+/** How a listed app signs in: `oauth` with the app's own registered client, `discovery` from its MCP server
+ * (registering itself where the server offers it), `device` with a typed code and the app's own client. */
+export type CatalogAuth = 'oauth' | 'discovery' | 'device';
+/** A listed app is a `Provider`: pass it to `connect()`, `connectLoopback()` or, for `device`, `deviceSignIn()`. */
+export interface CatalogApp extends Provider {
+    /** An HTTPS (or loopback) image address from the listing; render it as untrusted content. */
+    icon?: string;
+    auth: CatalogAuth;
+}
+/** Any source of apps a host can list; the kit ships `knownApps` and `mcpDirectory(url)`. */
+export interface CatalogProvider {
+    list(): Promise<readonly CatalogApp[]>;
+}
+export interface DirectoryOptions {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+/** The kit's hand-known apps (`providers`); reads nothing. */
+export declare const knownApps: CatalogProvider;
+/** A remote MCP directory at the caller's HTTPS (or loopback) URL, answering in the MCP registry's `GET /v0/servers`
+ * shape and paged by `metadata.nextCursor`. Nothing is read until `list()`. The caller vouches for the directory:
+ * signing in to a listed app talks to the server it names. */
+export declare function mcpDirectory(url: string, options?: DirectoryOptions): CatalogProvider;
+/** Lists the apps of the providers the caller picks, in their order; an id listed twice keeps its first entry. */
+export declare function catalog(sources: readonly CatalogProvider[]): Promise<CatalogApp[]>;

package/dist/catalog.js

@@ -0,0 +1,76 @@
+import { ConnectError } from './errors.js';
+import { endpoint, json, request } from './http.js';
+import { providers } from './providers.js';
+function listed(provider, icon) {
+    return { ...provider, ...(icon ? { icon } : {}), auth: provider.device ? 'device' : provider.oauth ? 'oauth' : 'discovery' };
+}
+function web(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    try {
+        return endpoint(raw).href;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One MCP registry `server.json` entry, kept only when the kit can sign in to it: a streamable HTTP remote with no
+ * address variables or required headers for the person to fill in. */
+function fromServer(server) {
+    if (!server || typeof server !== 'object')
+        return undefined;
+    const { name, title, remotes, icons } = server;
+    if (typeof name !== 'string' || !name)
+        return undefined;
+    const remote = Array.isArray(remotes) ? remotes.find(r => r?.type === 'streamable-http' && typeof r.url === 'string' && !r.url.includes('{') &&
+        !(Array.isArray(r.headers) && r.headers.some((h) => h?.isRequired))) : undefined;
+    const mcpUrl = web(remote?.url);
+    if (!mcpUrl)
+        return undefined;
+    const icon = Array.isArray(icons) ? icons.map(i => web(i?.src)).find(Boolean) : undefined;
+    return listed({ id: name, name: typeof title === 'string' && title ? title : name, mcpUrl }, icon);
+}
+/** The kit's hand-known apps (`providers`); reads nothing. */
+export const knownApps = { list: async () => Object.values(providers).map(provider => listed(provider)) };
+/** A remote MCP directory at the caller's HTTPS (or loopback) URL, answering in the MCP registry's `GET /v0/servers`
+ * shape and paged by `metadata.nextCursor`. Nothing is read until `list()`. The caller vouches for the directory:
+ * signing in to a listed app talks to the server it names. */
+export function mcpDirectory(url, options = {}) {
+    const base = endpoint(url);
+    return { list: async () => {
+            const apps = [];
+            let cursor;
+            // ponytail: at most 100 pages per list(), so a directory that keeps paging stays finite; raise it if a real directory outgrows it.
+            for (let page = 0; page < 100; page++) {
+                const next = new URL(base);
+                if (cursor)
+                    next.searchParams.set('cursor', cursor);
+                const response = await request(options.fetch ?? globalThis.fetch, next, { headers: { accept: 'application/json' } }, options.timeoutMs ?? 20_000);
+                if (!response.ok) {
+                    await response.body?.cancel();
+                    throw new ConnectError('catalog', response.status);
+                }
+                const body = await json(response, 'catalog');
+                if (!Array.isArray(body.servers))
+                    throw new ConnectError('catalog', response.status);
+                for (const entry of body.servers) {
+                    const app = fromServer(entry?.server);
+                    if (app)
+                        apps.push(app);
+                }
+                const more = body.metadata?.nextCursor;
+                if (typeof more !== 'string' || !more || more === cursor)
+                    break;
+                cursor = more;
+            }
+            return apps;
+        } };
+}
+/** Lists the apps of the providers the caller picks, in their order; an id listed twice keeps its first entry. */
+export async function catalog(sources) {
+    const apps = new Map();
+    for (const app of (await Promise.all(sources.map(source => source.list()))).flat())
+        if (!apps.has(app.id))
+            apps.set(app.id, app);
+    return [...apps.values()];
+}

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type ConnectErrorCode = 'configuration' | 'discovery' | 'registration' | 'callback' | 'expired' | 'declined' | 'scope' | 'token' | 'signin' | 'network';
+export type ConnectErrorCode = 'configuration' | 'discovery' | 'registration' | 'callback' | 'expired' | 'declined' | 'scope' | 'token' | 'signin' | 'network' | 'catalog';
 export interface ProviderErrorCause {
     readonly error: string;
     readonly error_description?: string;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { connect, deviceSignIn, Connection } from './connect.ts';
 export { providers } from './providers.ts';
 export type { ProviderId } from './providers.ts';
+export { catalog, knownApps, mcpDirectory } from './catalog.ts';
+export type { CatalogApp, CatalogAuth, CatalogProvider, DirectoryOptions } from './catalog.ts';
 export { ConnectError } from './errors.ts';
 export { MailReader, MailSender, MailError } from './mail.ts';
 export { MailHistory, HistoryError } from './history.ts';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { connect, deviceSignIn, Connection } from './connect.js';
 export { providers } from './providers.js';
+export { catalog, knownApps, mcpDirectory } from './catalog.js';
 export { ConnectError } from './errors.js';
 export { MailReader, MailSender, MailError } from './mail.js';
 export { MailHistory, HistoryError } from './history.js';

package/dist/words.json

@@ -9,7 +9,8 @@
         "scope": "Some permissions were left out. Sign in again and select them.",
         "token": "The app did not finish connecting. Try again.",
         "signin": "Sign in to this app again.",
-        "network": "Could not reach the app. Check your connection and try again."
+        "network": "Could not reach the app. Check your connection and try again.",
+        "catalog": "Could not load the list of apps. Try again later."
     },
     "browser": {
         "unavailable": "This page is not available.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/connect",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Connect a person's third-party apps with PKCE, refresh and typed remote MCP.",
   "license": "Apache-2.0",
   "type": "module",
@@ -37,6 +37,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.31.0",
-    "@byokit/secrets": "0.5.1"
+    "@byokit/secrets": "0.5.2"
   }
 }