@byokit/connect 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 (2026-10-01)
+
+
+
+- Document a secrets-sealed desktop store and verify encrypted refresh-token persistence.
+- Add per-person third-party sign-in, token refresh and typed remote MCP connections.
+
+- OAuth authorization-code sign-in with S256 PKCE, protected-resource discovery and dynamic client registration.
+- App-supplied redirects and an optional Node loopback helper; the host supplies each person's keystore.
+- Single-flight refresh, rotating refresh tokens, disconnect and full typed MCP client pass-through.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,210 @@
+# @byokit/connect
+
+Connect a person's Google, Drive, Notion, Canva or other remote MCP 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.
+
+```sh
+npm install @byokit/connect
+```
+
+The main export is portable to Node, Electron, browsers and PWAs. It needs `fetch`,
+Web Crypto, `btoa`, and URL APIs; native hosts must provide those globals before
+importing it. The optional `/node` export owns only the loopback callback listener.
+The main entry has no runtime dependency on Node or keystore backends.
+
+## Sign in with an app-supplied redirect
+
+```ts
+import { connect } from '@byokit/connect';
+import type { Keystore } from '@byokit/secrets';
+
+// Supply your app's store, scoped to this person on this device.
+declare const store: Keystore;
+const drive = connect('drive', {
+  store,
+  person: 'person-42',
+  redirectUri: 'https://your-app.example/connect/callback',
+  client: { id: 'your-google-client-id', secret: 'your-google-client-secret' },
+});
+
+const flow = await drive.signIn();
+// Open flow.url in the host's browser/auth session.
+// Route its complete callback URL to the same flow instance:
+await flow.finish('https://your-app.example/connect/callback?state=...&code=...');
+
+const accessToken = await drive.token(); // Trusted API calls only; never show/log it.
+await drive.disconnect();
+```
+
+`connect(target, options)` creates a handle. `signIn()` returns `{ url, redirectUri,
+finish, cancel }`. Call `cancel()` when closing the sign-in sheet. Calls to
+`connected()`, `token()` and `disconnect()` work after reconstructing the handle
+with the same store, person, target and configured client ID. The redirect port
+can change without losing the saved connection. A newer sign-in invalidates the
+older flow; callbacks have a 15-minute deadline and can be used only once.
+
+Google requires the host's registered client. Use a Desktop client with loopback,
+or register the exact HTTPS/native redirect for that client. Presets keep Google's
+offline/consent parameters and request one service at a time: `google` (identity),
+`drive` (`drive.file`), `gmail` (read-only) and `calendar` (events). The host owns
+Google consent-screen publishing and API enablement. The kit does not probe
+undocumented provider pages or impose a product-specific approval policy.
+
+`notion`, `canva` and arbitrary HTTPS MCP URLs discover their protected-resource
+metadata, authorization server and dynamic registration endpoint. If the server
+does not offer registration, pass the app's registered `client`. Custom `Provider`
+objects can supply `oauth` endpoints, an `issuer`, scopes and extra authorization
+parameters. Options `scopes` override the preset/discovered scopes; security
+parameters (`state`, PKCE, response type, client and redirect) cannot be overridden
+through `extra`. A sign-in with explicitly incomplete granted scopes is not saved.
+
+## Loopback on a computer
+
+```ts
+import { connectLoopback } from '@byokit/connect/node';
+import type { Keystore } from '@byokit/secrets';
+
+declare const store: Keystore;
+declare const yourApp: { openExternal(url: string): Promise<void> };
+
+const attempt = await connectLoopback('notion', {
+  store, person: 'person-42',
+  open: url => yourApp.openExternal(url),
+});
+await attempt.done;
+const connection = attempt.connection;
+// Or attempt.cancel() to close the listener and reject done.
+```
+
+The listener binds only `127.0.0.1`, with an OS-assigned port, and closes on success,
+cancel, failure or timeout. The host opens the browser; the kit never runs a CLI.
+Use `connect()` with `redirectUri` for web/PWA or native auth sessions instead.
+
+## Full typed MCP client
+
+```ts
+import { connect, CallToolResultSchema } from '@byokit/connect';
+import type { Keystore } from '@byokit/secrets';
+
+declare const store: Keystore;
+
+const notion = connect('notion', {
+  store, person: 'person-42', redirectUri: 'https://your-app.example/connect/callback',
+});
+// Sign in once, then reconstruct this handle across app restarts.
+const mcp = await notion.mcp({
+  clientInfo: { name: 'your-app', version: '1' },
+  clientOptions: { capabilities: {} },
+  configure: client => { /* register SDK request/notification handlers here */ },
+});
+try {
+  const page = await mcp.listTools(); // Follow nextCursor when present.
+  const result = await mcp.callTool({ name: page.tools[0].name, arguments: {} }, CallToolResultSchema);
+  // result preserves text, images, structuredContent, isError and other MCP data.
+  const resources = await mcp.listResources();
+  const prompts = await mcp.listPrompts();
+} finally {
+  await mcp.close();
+}
+```
+
+`mcp()` returns the official SDK `Client`, pinned at 1.31.0. Its typed tools,
+resources, prompts, pagination, cancellation, sampling/elicitation handlers,
+notifications, generic schema-validated `request()` and transport negotiation stay
+available. The package re-exports `Client` and the SDK's protocol types/schemas for
+pass-through. Streamable HTTP supports JSON and SSE responses and session headers.
+Every request obtains the person's current token, scoped to the connected resource.
+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.
+
+## Refresh, errors and storage
+
+Refresh runs when the token is within one minute of expiry, or after a 401. It is
+single-flight across handles sharing the same keystore object/person/connection.
+Rotated refresh tokens are persisted; responses that omit a refresh token keep the
+previous one. Transient failures preserve the sign-in. Only explicit
+`invalid_grant` removes it. An unexpired token can still be used after a network
+failure; an expired token is never returned. Tokens without `expires_in` remain
+valid until rejected, then refresh if possible. No background timer is needed.
+
+`ConnectError.code` is a typed app diagnostic and `message` is a plain sentence.
+OAuth errors never include provider bodies, callback codes or tokens. No errors or
+tokens are logged. MCP results/errors are private application content and should
+be treated accordingly. `fetch`, `now`, request and flow timeouts are injectable.
+
+The keystore dependency supplies the shared TypeScript contract; no backend is
+imported at runtime. Pass any `@byokit/secrets` backend (or a
+host adapter implementing its `get`/`set`/`delete` contract). The kit writes one
+JSON secret containing the grant, refresh tokens, scopes, issuer/endpoints and
+client registration per person/provider/resource/client under a fixed-length hashed
+name. Use a durable device
+store; do not send this record to a shared server. See [SECURITY.md](SECURITY.md)
+for concurrency and callback boundaries.
+
+## Sealed desktop token storage
+
+In Node or Electron's main process, wrap the host's durable store before passing
+it to connect. This adapter writes only authenticated ciphertext, including after
+refresh; the store's names are bound inside the sealed payload.
+
+```ts
+import { connect } from '@byokit/connect';
+import { osKeyringSeal, type Keystore } from '@byokit/secrets/node';
+
+// Your app's durable, per-person store; it receives ciphertext only.
+declare const ciphertextStore: Keystore;
+const seal = osKeyringSeal({ service: 'crewhouse-connect-Umer', dualWrap: true });
+const store: Keystore = {
+  async get(name) {
+    const value = await ciphertextStore.get(name);
+    if (value === null) return null;
+    const record = JSON.parse(seal.decryptString(Buffer.from(value, 'base64')));
+    if (record.name !== name || typeof record.secret !== 'string') throw new Error('Stored sign-in could not be opened.');
+    return record.secret;
+  },
+  async set(name, secret) {
+    const bytes = seal.encryptString(JSON.stringify({ name, secret }));
+    await ciphertextStore.set(name, Buffer.from(bytes).toString('base64'));
+  },
+  delete: name => ciphertextStore.delete(name),
+};
+const notion = connect('notion', {
+  store, person: 'Umer', redirectUri: 'https://your-app.example/connect/callback',
+});
+```
+
+Keep one adapter/store instance per person and app, and use an app writer lock if
+multiple processes share storage. Dual wrapping permits reads through an owner-only
+host key when the keyring is locked; keep that key separate from ciphertext backups.
+Omit `dualWrap` and pass `fallback: false` when an accessible OS keyring is required.
+See [secrets' sealing guide](../secrets/README.md#seal-accounts-files-on-desktop) for
+platform behavior, key protection and rotation. Sign in and refresh normally through
+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 host's
+registered Google client 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.
+For remote apps, call `mcp()` and use `listTools`/`callTool` with their full results;
+for Gmail/Calendar use `token()` until their typed kits sit on this connection.
+No raw OAuth, refresh or MCP transport needs to remain in the consumer.
+
+## Verification
+
+```sh
+npm run build
+npm run check
+sh scripts/test.sh 'packages/connect/test/*.test.ts'
+```
+
+Tests use fake providers and a real loopback callback only. They cover PKCE/state,
+replay/cancel/expiry, discovery/DCR/resource binding, refresh races and revocation,
+per-person isolation, rich MCP JSON/SSE responses and browser bundling. No real
+accounts or outbound network calls are used. Live provider/device sign-ins are not
+claimed by these tests.

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Security
+
+The host supplies a keystore and person identifier. Scope it to the person and app on
+this device. Tokens and dynamic client credentials are written only to that store;
+the kit never reads ambient accounts, environment keys or credential files. No
+server pool or account sharing is provided. Connection keys are fixed-length SHA-256 names over person, provider,
+resource, issuer/token endpoint and configured client ID. Long identities therefore
+fit every keystore backend without exposing those identities in keyring labels.
+
+Treat `token()` as trusted app code: never display or log its result. The kit does
+not log credentials or include provider response bodies in OAuth errors. The full
+MCP client can return private content and server error messages; handle those as
+private app data. Close each MCP client when finished.
+
+Each handle snapshots and freezes its provider settings so an existing grant cannot
+be retargeted by a later settings mutation.
+
+Remote endpoints require HTTPS, with HTTP allowed only on loopback. Requests refuse
+redirects, so credentials cannot follow a server redirect. Callback addresses support
+HTTPS, loopback HTTP and host-registered native app schemes. PKCE, unpredictable
+state, exact callback address checks, deadlines and one-shot callbacks protect each
+sign-in. The host must claim its native callback scheme or use verified app links.
+
+Refresh is serialized across handles sharing the same store object and connection
+identity. Separate processes/store objects need host coordination; do not open the
+same person's writable store in multiple processes. Explicit invalid-grant refresh
+responses remove the sign-in; temporary server/network failures preserve it.

package/dist/connect.d.ts

@@ -0,0 +1,28 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { type ProviderId } from './providers.ts';
+import type { ConnectOptions, Provider, SignIn, McpOptions } 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>;
+    private options;
+    private key;
+    private storageKey?;
+    private slot;
+    constructor(target: ProviderId | Provider | string, options: ConnectOptions);
+    private storeKey;
+    private get fetcher();
+    private get timeout();
+    private get now();
+    private saved;
+    connected(): Promise<boolean>;
+    disconnect(): Promise<void>;
+    /** Starts a fresh browser sign-in. No opt-in flag or server-held account is required. */
+    signIn(): Promise<SignIn>;
+    private register;
+    private exchange;
+    /** For trusted app code (mail/calendar/API calls). Never display or log this value. */
+    token(rejectedAccessToken?: string): Promise<string>;
+    /** The full official SDK Client: typed helpers, schemas, handlers, notifications and requests. */
+    mcp(options?: McpOptions): Promise<Client>;
+}
+export declare function connect(provider: ProviderId | Provider | string, options: ConnectOptions): Connection;

package/dist/connect.js

@@ -0,0 +1,261 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { ConnectError } 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) {
+    let slots = stores.get(store);
+    if (!slots) {
+        slots = new Map();
+        stores.set(store, slots);
+    }
+    let slot = slots.get(key);
+    if (!slot) {
+        slot = { tail: Promise.resolve(), epoch: 0 };
+        slots.set(key, slot);
+    }
+    return slot;
+}
+function serial(slot, action) {
+    const next = slot.tail.then(action, action);
+    slot.tail = next.catch(() => { });
+    return next;
+}
+function base64url(bytes) { return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); }
+function random() { return base64url(crypto.getRandomValues(new Uint8Array(32))); }
+/** One person's connection on one device; the host owns the store and browser. */
+export class Connection {
+    provider;
+    options;
+    key;
+    storageKey;
+    slot;
+    constructor(target, options) {
+        const provider = typeof target === 'string'
+            ? (Object.hasOwn(providers, target) ? providers[target] : { id: endpoint(target).href, name: 'App', mcpUrl: endpoint(target).href })
+            : target;
+        this.provider = Object.freeze({ ...provider,
+            oauth: provider.oauth && Object.freeze({ ...provider.oauth }),
+            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 (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.slot = slotFor(options.store, this.key);
+    }
+    storeKey() {
+        return this.storageKey ??= crypto.subtle.digest('SHA-256', new TextEncoder().encode(this.key))
+            .then(bytes => `byokit.connect.${base64url(new Uint8Array(bytes))}`);
+    }
+    get fetcher() { return this.options.fetch ?? globalThis.fetch; }
+    get timeout() { return this.options.timeoutMs ?? 20_000; }
+    get now() { return (this.options.now ?? Date.now)(); }
+    async saved() {
+        const raw = await this.options.store.get(await this.storeKey());
+        if (!raw)
+            return null;
+        try {
+            const value = JSON.parse(raw);
+            if (!value.tokens?.access || typeof value.tokens.access !== 'string' || !value.client?.id || !value.endpoints?.token || !Array.isArray(value.scopes))
+                throw new Error();
+            endpoint(value.endpoints.token);
+            return value;
+        }
+        catch {
+            throw new ConnectError('token');
+        }
+    }
+    async connected() { return !!await this.saved(); }
+    async disconnect() {
+        ++this.slot.epoch;
+        await serial(this.slot, async () => { await this.options.store.delete(await this.storeKey()); });
+    }
+    /** Starts a fresh browser sign-in. No opt-in flag or server-held account is required. */
+    async signIn() {
+        const epoch = ++this.slot.epoch;
+        const info = await discover(this.provider, this.fetcher, this.timeout);
+        const scopes = this.options.scopes ?? info.scopes;
+        const client = this.options.client ?? await this.register(info);
+        if (!client.id || (client.authMethod !== 'none' && client.authMethod && !client.secret))
+            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 } : {}) };
+        for (const [key, value] of Object.entries(fields))
+            url.searchParams.set(key, value);
+        if (scopes.length)
+            url.searchParams.set('scope', scopes.join(' '));
+        else
+            url.searchParams.delete('scope');
+        const ends = this.now + (this.options.flowTimeoutMs ?? 15 * 60_000);
+        let consumed = false, cancelled = false;
+        return { url: url.href, redirectUri: uri, cancel: () => { consumed = true; cancelled = true; }, finish: async (callback) => {
+                if (consumed || epoch !== this.slot.epoch)
+                    throw new ConnectError('callback');
+                if (this.now >= ends) {
+                    consumed = true;
+                    throw new ConnectError('expired');
+                }
+                let returned;
+                try {
+                    returned = new URL(callback);
+                }
+                catch {
+                    throw new ConnectError('callback');
+                }
+                const expected = new URL(uri);
+                if (returned.protocol !== expected.protocol || returned.host !== expected.host || returned.pathname !== expected.pathname || returned.username || returned.password || returned.hash || returned.searchParams.getAll('state').length !== 1 || returned.searchParams.get('state') !== state)
+                    throw new ConnectError('callback');
+                for (const [key, value] of expected.searchParams)
+                    if (returned.searchParams.getAll(key).length !== 1 || returned.searchParams.get(key) !== value)
+                        throw new ConnectError('callback');
+                consumed = true;
+                if (returned.searchParams.has('error'))
+                    throw new ConnectError('declined');
+                if (returned.searchParams.getAll('code').length !== 1 || !returned.searchParams.get('code'))
+                    throw new ConnectError('callback');
+                await serial(this.slot, async () => {
+                    if (epoch !== this.slot.epoch)
+                        throw new ConnectError('callback');
+                    const tokens = await this.exchange(info, client, { grant_type: 'authorization_code', code: returned.searchParams.get('code'), redirect_uri: uri, code_verifier: verifier });
+                    if (cancelled)
+                        throw new ConnectError('declined');
+                    if (this.now >= ends)
+                        throw new ConnectError('expired');
+                    if (tokens.scope !== undefined && !scopes.every(sc => tokens.scope.split(/\s+/).includes(sc)))
+                        throw new ConnectError('scope');
+                    if (epoch !== this.slot.epoch)
+                        throw new ConnectError('callback');
+                    await this.options.store.set(await this.storeKey(), JSON.stringify({ ...info, scopes, client, tokens }));
+                });
+            } };
+    }
+    async register(info) {
+        if (!info.endpoints.register)
+            throw new ConnectError('configuration');
+        const response = await request(this.fetcher, info.endpoints.register, {
+            method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json' },
+            body: JSON.stringify({ client_name: this.options.clientName ?? 'BYOKit', redirect_uris: [this.options.redirectUri], grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], token_endpoint_auth_method: 'none' }),
+        }, this.timeout);
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new ConnectError('registration', response.status);
+        }
+        const m = await json(response, 'registration');
+        if (typeof m.client_id !== 'string' || !m.client_id || (m.token_endpoint_auth_method !== undefined && m.token_endpoint_auth_method !== 'none'))
+            throw new ConnectError('registration');
+        return { id: m.client_id, authMethod: 'none' };
+    }
+    async exchange(info, client, fields, previous) {
+        const form = new URLSearchParams({ ...fields, client_id: client.id, ...(info.resource ? { resource: info.resource } : {}) });
+        const headers = { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' };
+        const method = client.authMethod ?? (client.secret ? 'client_secret_post' : 'none');
+        if (method === 'client_secret_post' && client.secret)
+            form.set('client_secret', client.secret);
+        if (method === 'client_secret_basic' && client.secret) {
+            const encode = (s) => new URLSearchParams({ v: s }).toString().slice(2);
+            headers.authorization = `Basic ${btoa(`${encode(client.id)}:${encode(client.secret)}`)}`;
+            form.delete('client_id');
+        }
+        const response = await request(this.fetcher, info.endpoints.token, { method: 'POST', headers, body: form }, this.timeout);
+        const m = await json(response, 'token');
+        if (!response.ok || m.error) {
+            // Only an explicit invalid grant proves revocation. Transient failures preserve the sign-in.
+            if (m.error === 'invalid_grant' && previous)
+                throw new ConnectError('signin', response.status);
+            throw new ConnectError('token', response.status);
+        }
+        if (typeof m.access_token !== 'string' || !m.access_token || typeof m.token_type !== 'string' || m.token_type.toLowerCase() !== 'bearer' || (m.expires_in !== undefined && (!Number.isFinite(Number(m.expires_in)) || Number(m.expires_in) < 0)))
+            throw new ConnectError('token');
+        return { access: m.access_token, refresh: typeof m.refresh_token === 'string' ? m.refresh_token : previous?.refresh,
+            expires: m.expires_in === undefined ? undefined : this.now + Number(m.expires_in) * 1000,
+            scope: typeof m.scope === 'string' ? m.scope : previous?.scope };
+    }
+    /** For trusted app code (mail/calendar/API calls). Never display or log this value. */
+    async token(rejectedAccessToken) {
+        const epoch = this.slot.epoch;
+        if (this.slot.tokenFlight?.epoch === epoch)
+            return this.slot.tokenFlight.promise;
+        const promise = serial(this.slot, async () => {
+            if (epoch !== this.slot.epoch)
+                throw new ConnectError('signin');
+            const saved = await this.saved();
+            if (!saved)
+                throw new ConnectError('signin');
+            const old = saved.tokens;
+            const force = rejectedAccessToken !== undefined && rejectedAccessToken === old.access;
+            if (!force && (old.expires === undefined || old.expires - this.now > 60_000))
+                return old.access;
+            if (!old.refresh) {
+                if (!force && old.expires !== undefined && old.expires > this.now)
+                    return old.access;
+                throw new ConnectError('signin');
+            }
+            try {
+                const tokens = await this.exchange(saved, saved.client, { grant_type: 'refresh_token', refresh_token: old.refresh }, old);
+                if (epoch !== this.slot.epoch)
+                    throw new ConnectError('signin');
+                await this.options.store.set(await this.storeKey(), JSON.stringify({ ...saved, tokens }));
+                return tokens.access;
+            }
+            catch (error) {
+                if (error instanceof ConnectError && error.code === 'signin' && epoch === this.slot.epoch)
+                    await this.options.store.delete(await this.storeKey());
+                if (!force && error instanceof ConnectError && error.code === 'network' && old.expires !== undefined && old.expires > this.now)
+                    return old.access;
+                throw error;
+            }
+        });
+        this.slot.tokenFlight = { epoch, promise };
+        try {
+            return await promise;
+        }
+        finally {
+            if (this.slot.tokenFlight?.promise === promise)
+                this.slot.tokenFlight = undefined;
+        }
+    }
+    /** The full official SDK Client: typed helpers, schemas, handlers, notifications and requests. */
+    async mcp(options = {}) {
+        if (!this.provider.mcpUrl)
+            throw new ConnectError('configuration');
+        const url = endpoint(this.provider.mcpUrl);
+        const fetcher = async (input, init) => {
+            // Transport may issue POST/GET/DELETE; credentials remain bound to this resource.
+            const requested = input instanceof Request ? input.url : String(input);
+            if (endpoint(requested).href !== url.href)
+                throw new ConnectError('configuration');
+            const access = await this.token();
+            const headers = new Headers(init?.headers);
+            headers.set('authorization', `Bearer ${access}`);
+            const response = await request(this.fetcher, url, { ...init, headers }, this.timeout);
+            if (response.status !== 401)
+                return response;
+            await response.body?.cancel();
+            headers.set('authorization', `Bearer ${await this.token(access)}`);
+            return request(this.fetcher, url, { ...init, headers }, this.timeout);
+        };
+        const client = new Client(options.clientInfo ?? { name: this.options.clientName ?? 'byokit', version: '0.1.0' }, options.clientOptions);
+        try {
+            options.configure?.(client);
+            await client.connect(new StreamableHTTPClientTransport(url, { fetch: fetcher }));
+            return client;
+        }
+        catch (error) {
+            await client.close().catch(() => { });
+            throw error;
+        }
+    }
+}
+export function connect(provider, options) { return new Connection(provider, options); }

package/dist/discovery.d.ts

@@ -0,0 +1,7 @@
+import type { OAuthEndpoints, Provider } from './types.ts';
+export interface Discovered {
+    endpoints: OAuthEndpoints;
+    scopes: readonly string[];
+    resource?: string;
+}
+export declare function discover(provider: Provider, fetcher: typeof fetch, timeout: number): Promise<Discovered>;

package/dist/discovery.js

@@ -0,0 +1,57 @@
+import { checkResourceAllowed } from '@modelcontextprotocol/sdk/shared/auth-utils.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))
+            endpoint(url);
+        return { endpoints: provider.oauth, scopes: provider.scopes ?? [], resource: provider.mcpUrl };
+    }
+    let issuer = provider.issuer;
+    let resource;
+    let scopes = provider.scopes;
+    if (provider.mcpUrl) {
+        const server = endpoint(provider.mcpUrl);
+        // RFC 9728: use the 401 challenge when present, otherwise well-known path then origin.
+        const probe = await request(fetcher, server, { headers: { accept: 'application/json, text/event-stream' } }, timeout);
+        const challenge = probe.headers.get('www-authenticate');
+        await probe.body?.cancel();
+        const advertised = challenge?.match(/resource_metadata\s*=\s*"([^"]+)"/i)?.[1];
+        const candidates = advertised ? [advertised] : [...new Set([`${server.origin}/.well-known/oauth-protected-resource${server.pathname === '/' ? '' : server.pathname}`, `${server.origin}/.well-known/oauth-protected-resource`])];
+        let metadata;
+        for (const url of candidates) {
+            const response = await request(fetcher, url, {}, timeout);
+            if (response.status === 404 && !advertised) {
+                await response.body?.cancel();
+                continue;
+            }
+            if (!response.ok)
+                throw new ConnectError('discovery', response.status);
+            metadata = await json(response, 'discovery');
+            break;
+        }
+        if (!metadata || typeof metadata.resource !== 'string' || !strings(metadata.authorization_servers) || metadata.authorization_servers.length === 0)
+            throw new ConnectError('discovery');
+        const canonical = endpoint(metadata.resource).href;
+        if (!checkResourceAllowed({ requestedResource: server, configuredResource: canonical }))
+            throw new ConnectError('discovery');
+        resource = metadata.resource;
+        if (issuer && !metadata.authorization_servers.includes(issuer))
+            throw new ConnectError('discovery');
+        issuer ??= metadata.authorization_servers[0];
+        if (!scopes && strings(metadata.scopes_supported))
+            scopes = metadata.scopes_supported;
+    }
+    if (!issuer)
+        throw new ConnectError('configuration');
+    const base = endpoint(issuer);
+    const response = await request(fetcher, `${base.origin}/.well-known/oauth-authorization-server${base.pathname === '/' ? '' : base.pathname.replace(/\/$/, '')}`, {}, timeout);
+    if (!response.ok)
+        throw new ConnectError('discovery', response.status);
+    const m = await json(response, 'discovery');
+    if (m.issuer !== issuer || typeof m.authorization_endpoint !== 'string' || typeof m.token_endpoint !== 'string' || (m.code_challenge_methods_supported !== undefined && (!strings(m.code_challenge_methods_supported) || !m.code_challenge_methods_supported.includes('S256'))))
+        throw new ConnectError('discovery');
+    for (const raw of [m.authorization_endpoint, m.token_endpoint, m.registration_endpoint].filter((x) => typeof x === 'string'))
+        endpoint(raw);
+    return { endpoints: { authorize: m.authorization_endpoint, token: m.token_endpoint, register: typeof m.registration_endpoint === 'string' ? m.registration_endpoint : undefined, issuer }, scopes: scopes ?? (strings(m.scopes_supported) ? m.scopes_supported : []), resource };
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export type ConnectErrorCode = 'configuration' | 'discovery' | 'registration' | 'callback' | 'expired' | 'declined' | 'scope' | 'token' | 'signin' | 'network';
+/** Never includes provider bodies, callback codes, credentials or URLs. */
+export declare class ConnectError extends Error {
+    readonly code: ConnectErrorCode;
+    readonly status?: number;
+    constructor(code: ConnectErrorCode, status?: number);
+}

package/dist/errors.js

@@ -0,0 +1,13 @@
+import WORDS from './words.json' with { type: 'json' };
+const words = WORDS.errors;
+/** Never includes provider bodies, callback codes, credentials or URLs. */
+export class ConnectError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(words[code]);
+        this.name = 'ConnectError';
+        this.code = code;
+        this.status = status;
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,7 @@
+import { type ConnectErrorCode } from './errors.ts';
+/** Remote secrets go over HTTPS; loopback HTTP is useful for local servers and tests. */
+export declare function endpoint(raw: string): URL;
+export declare function redirect(raw: string): URL;
+export declare function request(fetcher: typeof fetch, url: string | URL, init: RequestInit, timeout: number): Promise<Response>;
+export declare function json(response: Response, code: ConnectErrorCode): Promise<Record<string, unknown>>;
+export declare function strings(v: unknown): v is string[];

package/dist/http.js

@@ -0,0 +1,48 @@
+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;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new ConnectError('configuration');
+    }
+    if (u.username || u.password || u.hash || (u.protocol !== 'https:' && !(u.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(u.hostname))))
+        throw new ConnectError('configuration');
+    return u;
+}
+export function redirect(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new ConnectError('configuration');
+    }
+    if (u.username || u.password || u.hash || u.searchParams.has('state') || u.searchParams.has('code') || u.searchParams.has('error'))
+        throw new ConnectError('configuration');
+    if (u.protocol === 'http:' || u.protocol === 'https:')
+        return endpoint(raw);
+    if (['javascript:', 'data:', 'file:', 'ftp:', 'ws:', 'wss:'].includes(u.protocol))
+        throw new ConnectError('configuration');
+    return u;
+}
+export async function request(fetcher, url, init, timeout) {
+    try {
+        return await fetcher(endpoint(String(url)), { ...init, redirect: 'error', signal: init.signal ?? AbortSignal.timeout(timeout) });
+    }
+    catch {
+        throw new ConnectError('network');
+    }
+}
+export async function json(response, code) {
+    try {
+        const value = await response.json();
+        if (value && typeof value === 'object' && !Array.isArray(value))
+            return value;
+    }
+    catch { /* Do not expose response text. */ }
+    throw new ConnectError(code, response.status);
+}
+export function strings(v) { return Array.isArray(v) && v.every(x => typeof x === 'string'); }

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { connect, Connection } from './connect.ts';
+export { providers } from './providers.ts';
+export type { ProviderId } from './providers.ts';
+export { ConnectError } from './errors.ts';
+export type { ConnectErrorCode } from './errors.ts';
+export type { Provider, OAuthClient, OAuthEndpoints, ConnectOptions, SignIn, McpOptions } from './types.ts';
+export { Client } from '@modelcontextprotocol/sdk/client/index.js';
+export * from '@modelcontextprotocol/sdk/types.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { connect, Connection } from "./connect.js";
+export { providers } from "./providers.js";
+export { ConnectError } from "./errors.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.d.ts

@@ -0,0 +1,13 @@
+import { type Connection } from './connect.ts';
+import type { ConnectOptions, Provider } from './types.ts';
+import type { ProviderId } from './providers.ts';
+export interface LoopbackOptions extends Omit<ConnectOptions, 'redirectUri'> {
+    /** Host opens the browser; BYOKit never spawns the person's browser or CLI. */
+    open(url: string): Promise<void> | void;
+}
+/** One-shot loopback listener on an OS-assigned port; closes on completion, cancel or timeout. */
+export declare function connectLoopback(target: ProviderId | Provider | string, options: LoopbackOptions): Promise<{
+    connection: Connection;
+    done: Promise<void>;
+    cancel(): void;
+}>;

package/dist/node.js

@@ -0,0 +1,89 @@
+import WORDS from './words.json' with { type: 'json' };
+import { createServer } from 'node:http';
+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;
+    let resolve, reject;
+    const done = new Promise((yes, no) => { resolve = yes; reject = no; });
+    // The caller receives the promise after browser opening; a timeout before then is still handled.
+    void done.catch(() => { });
+    let settled = false;
+    let timer;
+    const settle = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        server.close();
+        server.closeAllConnections();
+        if (error) {
+            cancelFlow?.();
+            reject(error);
+        }
+        else
+            resolve();
+    };
+    let origin = '';
+    let state;
+    let completing = false;
+    let cancelFlow;
+    const server = createServer(async (req, res) => {
+        res.setHeader('content-type', 'text/plain; charset=utf-8');
+        res.setHeader('cache-control', 'no-store');
+        res.setHeader('x-content-type-options', 'nosniff');
+        if (req.method !== 'GET' || req.headers.host !== new URL(origin).host || req.url?.split('?')[0] !== '/callback' || !finish || settled) {
+            res.writeHead(404);
+            res.end(WORDS.browser.unavailable);
+            return;
+        }
+        const callback = new URL(req.url, origin);
+        if (callback.searchParams.getAll('state').length !== 1 || callback.searchParams.get('state') !== state) {
+            res.writeHead(400);
+            res.end(WORDS.browser.mismatch);
+            return;
+        }
+        if (completing) {
+            res.writeHead(409);
+            res.end(WORDS.browser.finishing);
+            return;
+        }
+        completing = true;
+        try {
+            await finish(callback.href);
+            res.end(WORDS.browser.connected);
+            setImmediate(() => settle());
+        }
+        catch (error) {
+            res.writeHead(400);
+            res.end(WORDS.browser.failed);
+            setImmediate(() => settle(error));
+        }
+    });
+    await new Promise((yes, no) => { server.once('error', no); server.listen(0, '127.0.0.1', () => { server.removeListener('error', no); yes(); }); });
+    server.on('error', error => settle(error));
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        settle(new ConnectError('configuration'));
+        throw new ConnectError('configuration');
+    }
+    origin = `http://127.0.0.1:${address.port}`;
+    timer = setTimeout(() => settle(new ConnectError('expired')), options.flowTimeoutMs ?? 15 * 60_000);
+    try {
+        const connection = connect(target, { ...options, redirectUri: `${origin}/callback` });
+        const flow = await connection.signIn();
+        state = new URL(flow.url).searchParams.get('state');
+        finish = callback => flow.finish(callback);
+        cancelFlow = flow.cancel;
+        if (settled)
+            throw new ConnectError('expired');
+        await options.open(flow.url);
+        return { connection, done, cancel: () => { cancelFlow?.(); settle(new ConnectError('declined')); } };
+    }
+    catch (error) {
+        cancelFlow?.();
+        settle(error);
+        throw error;
+    }
+}

package/dist/providers.d.ts

@@ -0,0 +1,66 @@
+export declare const providers: {
+    readonly google: {
+        readonly id: "google";
+        readonly name: "Google";
+        readonly oauth: {
+            authorize: string;
+            token: string;
+        };
+        readonly scopes: readonly ["openid", "email", "profile"];
+        readonly extra: {
+            access_type: string;
+            prompt: string;
+        };
+    };
+    readonly drive: {
+        readonly id: "drive";
+        readonly name: "Google Drive";
+        readonly oauth: {
+            authorize: string;
+            token: string;
+        };
+        readonly scopes: readonly ["https://www.googleapis.com/auth/drive.file"];
+        readonly extra: {
+            access_type: string;
+            prompt: string;
+        };
+        readonly mcpUrl: "https://drivemcp.googleapis.com/mcp/v1";
+    };
+    readonly gmail: {
+        readonly id: "gmail";
+        readonly name: "Gmail";
+        readonly oauth: {
+            authorize: string;
+            token: string;
+        };
+        readonly scopes: readonly ["https://www.googleapis.com/auth/gmail.readonly"];
+        readonly extra: {
+            access_type: string;
+            prompt: string;
+        };
+    };
+    readonly calendar: {
+        readonly id: "calendar";
+        readonly name: "Google Calendar";
+        readonly oauth: {
+            authorize: string;
+            token: string;
+        };
+        readonly scopes: readonly ["https://www.googleapis.com/auth/calendar.events"];
+        readonly extra: {
+            access_type: string;
+            prompt: string;
+        };
+    };
+    readonly notion: {
+        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";
+    };
+};
+export type ProviderId = keyof typeof providers;

package/dist/providers.js

@@ -0,0 +1,10 @@
+const googleOAuth = { authorize: 'https://accounts.google.com/o/oauth2/v2/auth', token: 'https://oauth2.googleapis.com/token' };
+const googleExtra = { access_type: 'offline', prompt: 'consent' };
+export const providers = {
+    google: { id: 'google', name: 'Google', oauth: googleOAuth, scopes: ['openid', 'email', 'profile'], extra: googleExtra },
+    drive: { id: 'drive', name: 'Google Drive', oauth: googleOAuth, scopes: ['https://www.googleapis.com/auth/drive.file'], extra: googleExtra, mcpUrl: 'https://drivemcp.googleapis.com/mcp/v1' },
+    gmail: { id: 'gmail', name: 'Gmail', oauth: googleOAuth, scopes: ['https://www.googleapis.com/auth/gmail.readonly'], extra: googleExtra },
+    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' },
+};

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+import type { Keystore } from '@byokit/secrets';
+import type { ClientOptions } from '@modelcontextprotocol/sdk/client/index.js';
+export interface OAuthClient {
+    id: string;
+    secret?: string;
+    authMethod?: 'none' | 'client_secret_post' | 'client_secret_basic';
+}
+export interface OAuthEndpoints {
+    authorize: string;
+    token: string;
+    register?: string;
+    issuer?: string;
+}
+export interface Provider {
+    id: string;
+    name: string;
+    mcpUrl?: string;
+    issuer?: string;
+    oauth?: OAuthEndpoints;
+    scopes?: readonly string[];
+    /** Provider-specific authorization parameters; PKCE/state cannot be overridden. */
+    extra?: Readonly<Record<string, string>>;
+}
+export interface ConnectOptions {
+    /** A store scoped by the host to this person on this device. */
+    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;
+    client?: OAuthClient;
+    clientName?: string;
+    scopes?: readonly string[];
+    fetch?: typeof fetch;
+    now?: () => number;
+    timeoutMs?: number;
+    flowTimeoutMs?: number;
+}
+export interface SignIn {
+    readonly url: string;
+    readonly redirectUri: string;
+    /** Pass the complete callback URL; rejects mismatched, expired and reused callbacks. */
+    finish(callback: string | URL): Promise<void>;
+    cancel(): void;
+}
+export interface McpOptions {
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Includes capabilities and all official SDK client options. */
+    clientOptions?: ClientOptions;
+    /** Register sampling/elicitation/request/notification handlers before connecting. */
+    configure?: (client: import('@modelcontextprotocol/sdk/client/index.js').Client) => void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/words.json

@@ -0,0 +1,21 @@
+{
+    "errors": {
+        "configuration": "This app needs its connection settings filled in.",
+        "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.",
+        "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."
+    },
+    "browser": {
+        "unavailable": "This page is not available.",
+        "mismatch": "This sign-in link does not match. Return to the app.",
+        "finishing": "Sign-in is already finishing. Return to the app.",
+        "connected": "Connected. You can return to the app.",
+        "failed": "Sign-in did not finish. Return to the app and try again."
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@byokit/connect",
+  "version": "0.1.0",
+  "description": "Connect a person's third-party apps with PKCE, refresh and typed remote MCP.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umeranjum17/byokit.git",
+    "directory": "packages/connect"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "prepack": "tsc -b"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.31.0",
+    "@byokit/secrets": "0.5.0"
+  }
+}