@byokit/connect 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 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
@@ -330,7 +359,7 @@ 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`, 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/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.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,4 +1,4 @@
-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 { ConnectError } from './errors.ts';
@@ -7,6 +7,6 @@ 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,8 @@
-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 { 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,7 +4,7 @@
         "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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/connect",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Connect a person's third-party apps with PKCE, refresh and typed remote MCP.",
   "license": "Apache-2.0",
   "type": "module",