@byokit/connect 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## 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."
+
 ## 0.4.0 (2026-10-12)
 
 - Dependency update: pins @byokit/secrets 0.5.1.

package/README.md

@@ -1,6 +1,6 @@
 # @byokit/connect
 
-Connect a person's Google, Drive, Notion, Canva or other remote MCP account.
+Connect a person's online files, mail, calendar, notes, designs, code or other remote account.
 Sign-in opens the provider's own page. Credentials stay in the keystore the app
 passes, scoped to that person on their device. There is no account pool, proxy,
 ambient credential lookup, logging or extra opt-in switch.
@@ -129,6 +129,35 @@ sanitized diagnostic `cause` as `ConnectError`. A secret is required. This check
 client authentication only; it does not check consent-screen publishing, enabled
 APIs, redirect registration or scopes. Tests use injected fake endpoints only.
 
+## Connect GitHub with a device code
+
+```ts
+import { connect, deviceSignIn } from '@byokit/connect';
+import type { Keystore } from '@byokit/secrets';
+
+declare const store: Keystore;
+const options = { store, person: 'Umer', client: { id: 'your-github-oauth-app-client-id' }, scopes: ['repo'] };
+const flow = await deviceSignIn('github', options);
+// Show flow.userCode and flow.verificationUri (github.com/login/device);
+// the person types the code there on any device.
+await flow.finish(); // Resolves once they approve; call flow.cancel() when the sheet closes.
+
+const github = connect('github', options);
+await github.connected(); // true
+```
+
+`deviceSignIn(provider, options)` starts an RFC 8628 device sign-in and returns
+`{ userCode, verificationUri, expiresAt, finish, cancel }`; `expiresAt` is Unix
+milliseconds. It needs the app's own OAuth client ID with device flow enabled;
+there is no house GitHub client, and no `redirectUri`. `finish()` polls at the
+provider's interval, adds 5 seconds on `slow_down`, and keeps waiting through a
+poll that cannot get through. Only an approved code stores a grant, in the same
+keystore record `connect()` reads, so `connected()`, `grant()` and `token()`
+work afterwards. An expired code rejects with `ConnectError` code `expired`; a
+person pressing Cancel on GitHub, or `cancel()`, rejects with `declined`. Both
+store nothing. Any provider with `device: { code, token }` endpoints works the
+same way.
+
 ## Loopback on a computer
 
 ```ts
@@ -189,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
@@ -313,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.
@@ -330,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`/`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/connect.d.ts

@@ -1,6 +1,6 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { type ProviderId } from './providers.ts';
-import type { ConnectOptions, OAuthClient, Provider, SignIn, McpOptions, Grant, ClientVerification } from './types.ts';
+import type { ConnectOptions, OAuthClient, Provider, SignIn, DeviceSignIn, McpOptions, Grant, ClientVerification } from './types.ts';
 /** One person's connection on one device; the host owns the store and browser. */
 export declare class Connection {
     readonly provider: Readonly<Provider>;
@@ -23,6 +23,9 @@ export declare class Connection {
     disconnect(): Promise<void>;
     /** Starts a fresh browser sign-in. No opt-in flag or server-held account is required. */
     signIn(): Promise<SignIn>;
+    /** RFC 8628 device sign-in with the app's own client: show `userCode` at `verificationUri`, then await `finish()`.
+     * The poll follows the token endpoint: pending waits, slow_down adds 5 s, and an unreachable poll waits for the next. */
+    deviceSignIn(): Promise<DeviceSignIn>;
     private register;
     private exchange;
     /** For trusted app code (mail/calendar/API calls). Never display or log this value. */
@@ -31,3 +34,4 @@ export declare class Connection {
     mcp(options?: McpOptions): Promise<Client>;
 }
 export declare function connect(provider: ProviderId | Provider | string, options: ConnectOptions): Connection;
+export declare function deviceSignIn(provider: ProviderId | Provider, options: ConnectOptions): Promise<DeviceSignIn>;

package/dist/connect.js

@@ -1,10 +1,10 @@
 import WORDS from './words.json' with { type: 'json' };
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { ConnectError, providerCause } from "./errors.js";
-import { discover } from "./discovery.js";
-import { endpoint, redirect, request, json } from "./http.js";
-import { providers } from "./providers.js";
+import { ConnectError, providerCause } from './errors.js';
+import { discover } from './discovery.js';
+import { endpoint, redirect, request, json } from './http.js';
+import { providers } from './providers.js';
 // Across handles, only the same store + person + connection share work. No global token cache.
 const stores = new WeakMap();
 function slotFor(store, key) {
@@ -35,6 +35,9 @@ function validClient(client) {
         throw new ConnectError('configuration');
     return { id: client.id, secret: client.secret, authMethod: client.authMethod };
 }
+function wait(ms, signal) {
+    return new Promise(resolve => { const timer = setTimeout(resolve, ms); signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true }); });
+}
 function validTime(value) { return value === undefined || (typeof value === 'number' && Number.isFinite(value) && value >= 0); }
 /** One person's connection on one device; the host owns the store and browser. */
 export class Connection {
@@ -49,16 +52,18 @@ export class Connection {
             : target;
         this.provider = Object.freeze({ ...provider,
             oauth: provider.oauth && Object.freeze({ ...provider.oauth }),
+            device: provider.device && Object.freeze({ ...provider.device }),
             scopes: provider.scopes && Object.freeze([...provider.scopes]),
             extra: provider.extra && Object.freeze({ ...provider.extra }),
         });
         if (!options.person || !this.provider.id)
             throw new ConnectError('configuration');
-        redirect(options.redirectUri);
+        if (options.redirectUri !== undefined)
+            redirect(options.redirectUri);
         if (this.provider.mcpUrl)
             endpoint(this.provider.mcpUrl);
         this.options = { ...options, scopes: options.scopes && Object.freeze([...options.scopes]), client: options.client && { ...options.client } };
-        this.key = `byokit.connect:${JSON.stringify([options.person, this.provider.id, this.provider.mcpUrl ?? '', this.provider.oauth?.token ?? this.provider.issuer ?? '', options.client?.id ?? ''])}`;
+        this.key = `byokit.connect:${JSON.stringify([options.person, this.provider.id, this.provider.mcpUrl ?? '', this.provider.oauth?.token ?? this.provider.device?.token ?? this.provider.issuer ?? '', options.client?.id ?? ''])}`;
         this.slot = slotFor(options.store, this.key);
     }
     storeKey() {
@@ -120,6 +125,9 @@ export class Connection {
     }
     /** Starts a fresh browser sign-in. No opt-in flag or server-held account is required. */
     async signIn() {
+        const uri = this.options.redirectUri;
+        if (!uri)
+            throw new ConnectError('configuration');
         const epoch = ++this.slot.epoch;
         const info = await discover(this.provider, this.fetcher, this.timeout);
         const scopes = this.options.scopes ?? info.scopes;
@@ -128,7 +136,6 @@ export class Connection {
             throw new ConnectError('configuration');
         const state = random(), verifier = random();
         const challenge = base64url(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))));
-        const uri = this.options.redirectUri;
         const url = endpoint(info.endpoints.authorize);
         const fields = { ...this.provider.extra, response_type: 'code', client_id: client.id, redirect_uri: uri, state,
             code_challenge: challenge, code_challenge_method: 'S256', ...(info.resource ? { resource: info.resource } : {}) };
@@ -181,6 +188,68 @@ export class Connection {
                 });
             } };
     }
+    /** RFC 8628 device sign-in with the app's own client: show `userCode` at `verificationUri`, then await `finish()`.
+     * The poll follows the token endpoint: pending waits, slow_down adds 5 s, and an unreachable poll waits for the next. */
+    async deviceSignIn() {
+        const device = this.provider.device;
+        if (!device || !this.options.client)
+            throw new ConnectError('configuration');
+        const client = validClient(this.options.client);
+        const epoch = ++this.slot.epoch;
+        const scopes = this.options.scopes ?? this.provider.scopes ?? [];
+        const info = { endpoints: { authorize: endpoint(device.code).href, token: endpoint(device.token).href }, scopes };
+        const response = await request(this.fetcher, device.code, { method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+            body: new URLSearchParams({ client_id: client.id, ...(scopes.length ? { scope: scopes.join(' ') } : {}) }) }, this.timeout);
+        const m = await json(response, 'token');
+        if (!response.ok || m.error)
+            throw new ConnectError('token', response.status, providerCause(m, [client.id, client.secret ?? '']));
+        const lives = Number(m.expires_in), seconds = m.interval === undefined ? 5 : Number(m.interval);
+        if (typeof m.device_code !== 'string' || !m.device_code || typeof m.user_code !== 'string' || !m.user_code || typeof m.verification_uri !== 'string' ||
+            !Number.isFinite(lives) || lives <= 0 || !Number.isFinite(seconds) || seconds < 0)
+            throw new ConnectError('token');
+        const code = m.device_code, verificationUri = endpoint(m.verification_uri).href, expiresAt = this.now + lives * 1000;
+        const stop = new AbortController();
+        let interval = Math.max(1000, seconds * 1000), done;
+        const ended = () => stop.signal.aborted || epoch !== this.slot.epoch;
+        const poll = async () => {
+            for (;;) {
+                if (ended())
+                    throw new ConnectError('declined');
+                if (this.now >= expiresAt)
+                    throw new ConnectError('expired');
+                const tokens = await this.exchange(info, client, { grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: code }).catch((error) => {
+                    if (!(error instanceof ConnectError))
+                        throw error;
+                    const answer = error.cause?.error;
+                    if (answer === 'expired_token')
+                        throw new ConnectError('expired', error.status, error.cause);
+                    if (answer === 'access_denied')
+                        throw new ConnectError('declined', error.status, error.cause);
+                    if (answer === 'slow_down')
+                        interval += 5000;
+                    // A poll that cannot get through waits for the next, as a phone cuts a backgrounded app's network.
+                    else if (answer !== 'authorization_pending' && error.code !== 'network')
+                        throw error;
+                    return undefined;
+                });
+                if (tokens)
+                    return serial(this.slot, async () => {
+                        if (ended())
+                            throw new ConnectError('declined');
+                        // GitHub lists granted scopes with commas; RFC 6749 with spaces.
+                        if (tokens.scope !== undefined && !scopes.every(sc => tokens.scope.split(/[\s,]+/).includes(sc)))
+                            throw new ConnectError('scope');
+                        const key = await this.storeKey();
+                        if (ended())
+                            throw new ConnectError('declined');
+                        await this.options.store.set(key, JSON.stringify({ ...info, client, tokens }));
+                    });
+                await wait(interval, stop.signal);
+            }
+        };
+        return { userCode: m.user_code, verificationUri, expiresAt, finish: () => done ??= poll(), cancel: () => stop.abort() };
+    }
     async register(info) {
         if (!info.endpoints.register)
             throw new ConnectError('configuration');
@@ -307,3 +376,4 @@ export class Connection {
     }
 }
 export function connect(provider, options) { return new Connection(provider, options); }
+export function deviceSignIn(provider, options) { return connect(provider, options).deviceSignIn(); }

package/dist/discovery.js

@@ -1,6 +1,6 @@
 import { checkResourceAllowed } from '@modelcontextprotocol/sdk/shared/auth-utils.js';
-import { ConnectError } from "./errors.js";
-import { endpoint, json, request, strings } from "./http.js";
+import { ConnectError } from './errors.js';
+import { endpoint, json, request, strings } from './http.js';
 export async function discover(provider, fetcher, timeout) {
     if (provider.oauth) {
         for (const url of [provider.oauth.authorize, provider.oauth.token, provider.oauth.register].filter((x) => !!x))

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/errors.js

@@ -17,7 +17,7 @@ export function providerCause(body, secrets) {
         }
         return text.replace(/https?:\/\/[^\s<>"']+/gi, '[redacted]').replace(/(?:Bearer|Basic)\s+[^\s,;]+/gi, '[redacted]');
     };
-    const standard = ['invalid_request', 'invalid_client', 'invalid_grant', 'unauthorized_client', 'unsupported_grant_type', 'invalid_scope', 'access_denied', 'server_error', 'temporarily_unavailable', 'invalid_client_metadata', 'invalid_redirect_uri'];
+    const standard = ['invalid_request', 'invalid_client', 'invalid_grant', 'unauthorized_client', 'unsupported_grant_type', 'invalid_scope', 'access_denied', 'server_error', 'temporarily_unavailable', 'invalid_client_metadata', 'invalid_redirect_uri', 'authorization_pending', 'slow_down', 'expired_token'];
     return Object.freeze({ error: standard.includes(body.error) && !values.includes(body.error) ? body.error : redact(body.error), ...(typeof body.error_description === 'string' ? { error_description: redact(body.error_description) } : {}) });
 }
 /** Plain message and optional sanitized OAuth cause; never includes raw response bodies. */

package/dist/history.js

@@ -1,7 +1,7 @@
 // Owner-bound mail history and export. The credential (a Connection) stays the
 // only authentication; every call names its principal and anything but the bound
 // owner is denied before any provider fetch. This module never sends.
-import { MailReader, MailError } from "./mail.js";
+import { MailReader, MailError } from './mail.js';
 export class HistoryError extends Error {
     code;
     status;

package/dist/http.js

@@ -1,4 +1,4 @@
-import { ConnectError } from "./errors.js";
+import { ConnectError } from './errors.js';
 /** Remote secrets go over HTTPS; loopback HTTP is useful for local servers and tests. */
 export function endpoint(raw) {
     let u;

package/dist/index.d.ts

@@ -1,12 +1,14 @@
-export { connect, Connection } from './connect.ts';
+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';
 export type { HistoryFormat, HistoryErrorCode, MailHistoryOptions, HistoryQuery, HistoryExportQuery } from './history.ts';
 export type { MailErrorCode, MailCredential, MailReaderOptions, MailEnvelope, MailBody, MailMessage, MailPage, MailListOptions, MailGetOptions, MailSenderOptions, MailDraft, OutgoingMail, MailApproval, MailSendOptions, SentMail } from './mail.ts';
 export type { ConnectErrorCode, ProviderErrorCause } from './errors.ts';
-export type { Provider, OAuthClient, OAuthEndpoints, ConnectOptions, SignIn, McpOptions, Grant, ClientVerification } from './types.ts';
+export type { Provider, OAuthClient, OAuthEndpoints, ConnectOptions, SignIn, DeviceSignIn, McpOptions, Grant, ClientVerification } from './types.ts';
 export { Client } from '@modelcontextprotocol/sdk/client/index.js';
 export * from '@modelcontextprotocol/sdk/types.js';

package/dist/index.js

@@ -1,8 +1,9 @@
-export { connect, Connection } from "./connect.js";
-export { providers } from "./providers.js";
-export { ConnectError } from "./errors.js";
-export { MailReader, MailSender, MailError } from "./mail.js";
-export { MailHistory, HistoryError } from "./history.js";
+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';
 // Expose the pinned engine for typed protocol pass-through without a second SDK pin.
 export { Client } from '@modelcontextprotocol/sdk/client/index.js';
 export * from '@modelcontextprotocol/sdk/types.js';

package/dist/node.js

@@ -2,8 +2,8 @@ import WORDS from './words.json' with { type: 'json' };
 import { createServer } from 'node:http';
 import { constants } from 'node:fs';
 import { open } from 'node:fs/promises';
-import { connect } from "./connect.js";
-import { ConnectError } from "./errors.js";
+import { connect } from './connect.js';
+import { ConnectError } from './errors.js';
 /** One-shot loopback listener on an OS-assigned port; closes on completion, cancel or timeout. */
 export async function connectLoopback(target, options) {
     let finish;

package/dist/providers.d.ts

@@ -1,7 +1,7 @@
 export declare const providers: {
     readonly google: {
-        readonly id: "google";
-        readonly name: "Google";
+        readonly id: 'google';
+        readonly name: 'Google';
         readonly oauth: {
             authorize: string;
             token: string;
@@ -13,8 +13,8 @@ export declare const providers: {
         };
     };
     readonly drive: {
-        readonly id: "drive";
-        readonly name: "Google Drive";
+        readonly id: 'drive';
+        readonly name: 'Google Drive';
         readonly oauth: {
             authorize: string;
             token: string;
@@ -24,11 +24,11 @@ export declare const providers: {
             access_type: string;
             prompt: string;
         };
-        readonly mcpUrl: "https://drivemcp.googleapis.com/mcp/v1";
+        readonly mcpUrl: 'https://drivemcp.googleapis.com/mcp/v1';
     };
     readonly gmail: {
-        readonly id: "gmail";
-        readonly name: "Gmail";
+        readonly id: 'gmail';
+        readonly name: 'Gmail';
         readonly oauth: {
             authorize: string;
             token: string;
@@ -40,8 +40,8 @@ export declare const providers: {
         };
     };
     readonly calendar: {
-        readonly id: "calendar";
-        readonly name: "Google Calendar";
+        readonly id: 'calendar';
+        readonly name: 'Google Calendar';
         readonly oauth: {
             authorize: string;
             token: string;
@@ -53,14 +53,22 @@ export declare const providers: {
         };
     };
     readonly notion: {
-        readonly id: "notion";
-        readonly name: "Notion";
-        readonly mcpUrl: "https://mcp.notion.com/mcp";
+        readonly id: 'notion';
+        readonly name: 'Notion';
+        readonly mcpUrl: 'https://mcp.notion.com/mcp';
     };
     readonly canva: {
-        readonly id: "canva";
-        readonly name: "Canva";
-        readonly mcpUrl: "https://mcp.canva.com/mcp";
+        readonly id: 'canva';
+        readonly name: 'Canva';
+        readonly mcpUrl: 'https://mcp.canva.com/mcp';
+    };
+    readonly github: {
+        readonly id: 'github';
+        readonly name: 'GitHub';
+        readonly device: {
+            readonly code: 'https://github.com/login/device/code';
+            readonly token: 'https://github.com/login/oauth/access_token';
+        };
     };
 };
 export type ProviderId = keyof typeof providers;

package/dist/providers.js

@@ -7,4 +7,5 @@ export const providers = {
     calendar: { id: 'calendar', name: 'Google Calendar', oauth: googleOAuth, scopes: ['https://www.googleapis.com/auth/calendar.events'], extra: googleExtra },
     notion: { id: 'notion', name: 'Notion', mcpUrl: 'https://mcp.notion.com/mcp' },
     canva: { id: 'canva', name: 'Canva', mcpUrl: 'https://mcp.canva.com/mcp' },
+    github: { id: 'github', name: 'GitHub', device: { code: 'https://github.com/login/device/code', token: 'https://github.com/login/oauth/access_token' } },
 };

package/dist/types.d.ts

@@ -17,6 +17,11 @@ export interface Provider {
     mcpUrl?: string;
     issuer?: string;
     oauth?: OAuthEndpoints;
+    /** RFC 8628 device authorization: the person types a code on any device instead of returning to a redirect. */
+    device?: {
+        code: string;
+        token: string;
+    };
     scopes?: readonly string[];
     /** Provider-specific authorization parameters; PKCE/state cannot be overridden. */
     extra?: Readonly<Record<string, string>>;
@@ -26,8 +31,8 @@ export interface ConnectOptions {
     store: Keystore;
     /** Distinguishes connections belonging to different people sharing a store. */
     person: string;
-    /** HTTPS, loopback HTTP, or the host's registered native app URI. */
-    redirectUri: string;
+    /** HTTPS, loopback HTTP, or the host's registered native app URI. Needed by `signIn()`, not by `deviceSignIn()`. */
+    redirectUri?: string;
     client?: OAuthClient;
     clientName?: string;
     scopes?: readonly string[];
@@ -43,6 +48,16 @@ export interface SignIn {
     finish(callback: string | URL): Promise<void>;
     cancel(): void;
 }
+export interface DeviceSignIn {
+    /** Show this code and `verificationUri`; the person types the code there on any device. */
+    readonly userCode: string;
+    readonly verificationUri: string;
+    /** Unix milliseconds when the code stops working. */
+    readonly expiresAt: number;
+    /** Waits for the person; stores the grant only when they approve. The same promise on every call. */
+    finish(): Promise<void>;
+    cancel(): void;
+}
 export interface McpOptions {
     clientInfo?: {
         name: string;

package/dist/words.json

@@ -4,12 +4,13 @@
         "discovery": "Could not find the app’s sign-in page.",
         "registration": "The app could not set up sign-in. Try again.",
         "callback": "This sign-in link does not match. Start again.",
-        "expired": "This sign-in link has expired. Start again.",
+        "expired": "This sign-in has expired. Start again.",
         "declined": "Nothing was connected. Try again whenever you like.",
         "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.4.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"
   }
 }