@byokit/connect 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.2.0 (2026-10-01)
+
+- FIX: Preserve provider refresh-token lifetimes and sanitized OAuth error causes for setup guidance.
+- Add a client-details check without a user grant, with plain outcomes for accepted, rejected and uncertain replies.
+
 ## 0.1.0 (2026-10-01)
 
 

package/README.md

@@ -24,7 +24,7 @@ import type { Keystore } from '@byokit/secrets';
 declare const store: Keystore;
 const drive = connect('drive', {
   store,
-  person: 'person-42',
+  person: 'Umer',
   redirectUri: 'https://your-app.example/connect/callback',
   client: { id: 'your-google-client-id', secret: 'your-google-client-secret' },
 });
@@ -60,6 +60,37 @@ 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.
 
+## Check app details and inspect grant lifetime
+
+```ts
+import type { Connection } from '@byokit/connect';
+
+declare const drive: Connection;
+declare const enteredClientId: string;
+declare const enteredClientSecret: string;
+
+const check = await drive.verifyClient(); // Uses options.client.
+// Or check newly entered details without changing the saved connection:
+const entered = await drive.verifyClient({ id: enteredClientId, secret: enteredClientSecret });
+const grant = await drive.grant(); // Trusted app code only; contains credentials.
+```
+
+`grant()` returns a snapshot or `null` and makes no provider call. Times are Unix
+milliseconds. `refreshTokenExpiresIn` preserves the provider's
+`refresh_token_expires_in` seconds; `refreshTokenExpiresAt` is its absolute deadline.
+Sign-in/refresh responses calculate the deadline when received, and omitted refresh
+lifetime fields retain the previous deadline. Expired refresh grants require
+sign-in without sending another refresh request.
+
+`verifyClient(client?)` uses the selected token endpoint with a deliberately
+nonexistent refresh grant, without reading or changing the person's grant. For
+Google, `invalid_client` yields `outcome: 'invalid'`; a 400 `invalid_grant` yields
+`'valid'`; network failures and all other replies yield `'inconclusive'`. Each
+outcome includes a plain `message`; failed provider replies may carry the same
+sanitized diagnostic `cause` as `ConnectError`. A secret is required. This checks
+client authentication only; it does not check consent-screen publishing, enabled
+APIs, redirect registration or scopes. Tests use injected fake endpoints only.
+
 ## Loopback on a computer
 
 ```ts
@@ -70,7 +101,7 @@ declare const store: Keystore;
 declare const yourApp: { openExternal(url: string): Promise<void> };
 
 const attempt = await connectLoopback('notion', {
-  store, person: 'person-42',
+  store, person: 'Umer',
   open: url => yourApp.openExternal(url),
 });
 await attempt.done;
@@ -91,7 +122,7 @@ 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',
+  store, person: 'Umer', redirectUri: 'https://your-app.example/connect/callback',
 });
 // Sign in once, then reconstruct this handle across app restarts.
 const mcp = await notion.mcp({
@@ -131,7 +162,10 @@ 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
+OAuth errors expose an optional typed `cause` with `error` and
+`error_description`, sanitized against supplied/returned credentials and URLs.
+The message remains a plain sentence. Treat provider descriptions as untrusted
+text; they are diagnostics for the host, not ready-to-render UI. 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.
 

package/SECURITY.md

@@ -7,8 +7,11 @@ server pool or account sharing is provided. Connection keys are fixed-length SHA
 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
+Treat `token()` and `grant()` as trusted app code: never display or log their results.
+The kit does not log credentials or include raw provider response bodies in OAuth
+errors. OAuth causes retain only `error` and `error_description`, with supplied and
+returned credentials (including URL/form encodings), URLs and authorization headers
+redacted. Treat descriptions as untrusted diagnostic text, never as HTML. The full
 MCP client can return private content and server error messages; handle those as
 private app data. Close each MCP client when finished.
 

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, Provider, SignIn, McpOptions } from './types.ts';
+import type { ConnectOptions, OAuthClient, Provider, SignIn, 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>;
@@ -14,6 +14,11 @@ export declare class Connection {
     private get timeout();
     private get now();
     private saved;
+    /** Snapshot for trusted app code, including the provider's refresh lifetime. */
+    grant(): Promise<Grant | null>;
+    /** Google checks app credentials before rejecting this deliberately nonexistent refresh grant.
+     * Only invalid_grant confirms the details; other responses cannot prove validity. */
+    verifyClient(input?: OAuthClient): Promise<ClientVerification>;
     connected(): Promise<boolean>;
     disconnect(): Promise<void>;
     /** Starts a fresh browser sign-in. No opt-in flag or server-held account is required. */

package/dist/connect.js

@@ -1,6 +1,7 @@
+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 } from "./errors.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";
@@ -26,6 +27,15 @@ function serial(slot, action) {
 }
 function base64url(bytes) { return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); }
 function random() { return base64url(crypto.getRandomValues(new Uint8Array(32))); }
+function validClient(client) {
+    if (!client || typeof client.id !== 'string' || !client.id.trim() ||
+        (client.secret !== undefined && (typeof client.secret !== 'string' || !client.secret)) ||
+        (client.authMethod !== undefined && !['none', 'client_secret_post', 'client_secret_basic'].includes(client.authMethod)) ||
+        (client.authMethod?.startsWith('client_secret_') && !client.secret))
+        throw new ConnectError('configuration');
+    return { id: client.id, secret: client.secret, authMethod: client.authMethod };
+}
+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 {
     provider;
@@ -73,6 +83,36 @@ export class Connection {
             throw new ConnectError('token');
         }
     }
+    /** Snapshot for trusted app code, including the provider's refresh lifetime. */
+    async grant() {
+        const saved = await this.saved();
+        if (!saved)
+            return null;
+        const t = saved.tokens;
+        return { accessToken: t.access, refreshToken: t.refresh, expiresAt: t.expires, scope: t.scope,
+            refreshTokenExpiresIn: t.refreshExpiresIn, refreshTokenExpiresAt: t.refreshExpiresAt };
+    }
+    /** Google checks app credentials before rejecting this deliberately nonexistent refresh grant.
+     * Only invalid_grant confirms the details; other responses cannot prove validity. */
+    async verifyClient(input) {
+        const client = validClient((input ?? this.options.client));
+        if (!client.secret || client.authMethod === 'none')
+            throw new ConnectError('configuration');
+        try {
+            const info = await discover(this.provider, this.fetcher, this.timeout);
+            await this.exchange(info, client, { grant_type: 'refresh_token', refresh_token: 'byokit-client-check-not-a-grant' });
+        }
+        catch (error) {
+            if (!(error instanceof ConnectError))
+                throw error;
+            if (error.cause?.error === 'invalid_client' && (error.status === 400 || error.status === 401))
+                return { outcome: 'invalid', message: WORDS.verification.invalid, cause: error.cause };
+            if (error.cause?.error === 'invalid_grant' && error.status === 400)
+                return { outcome: 'valid', message: WORDS.verification.valid };
+            return { outcome: 'inconclusive', message: WORDS.verification.inconclusive, cause: error.cause };
+        }
+        return { outcome: 'inconclusive', message: WORDS.verification.inconclusive };
+    }
     async connected() { return !!await this.saved(); }
     async disconnect() {
         ++this.slot.epoch;
@@ -122,7 +162,7 @@ export class Connection {
                         throw new ConnectError('callback');
                 consumed = true;
                 if (returned.searchParams.has('error'))
-                    throw new ConnectError('declined');
+                    throw new ConnectError('declined', undefined, providerCause(Object.fromEntries(returned.searchParams), [state, verifier, client.id, client.secret ?? '', ...returned.searchParams.getAll('code')]));
                 if (returned.searchParams.getAll('code').length !== 1 || !returned.searchParams.get('code'))
                     throw new ConnectError('callback');
                 await serial(this.slot, async () => {
@@ -148,11 +188,9 @@ export class Connection {
             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 (!response.ok || m.error)
+            throw new ConnectError('registration', response.status, providerCause(m, [this.options.clientName ?? 'BYOKit', this.options.redirectUri]));
         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' };
@@ -172,15 +210,20 @@ export class Connection {
         const m = await json(response, 'token');
         if (!response.ok || m.error) {
             // Only an explicit invalid grant proves revocation. Transient failures preserve the sign-in.
+            const cause = providerCause(m, [client.id, client.secret ?? '', previous?.access ?? '', previous?.refresh ?? '', ...Object.values(fields)]);
             if (m.error === 'invalid_grant' && previous)
-                throw new ConnectError('signin', response.status);
-            throw new ConnectError('token', response.status);
+                throw new ConnectError('signin', response.status, cause);
+            throw new ConnectError('token', response.status, cause);
         }
         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');
+        if (m.refresh_token_expires_in !== undefined && (!validTime(m.refresh_token_expires_in) || !Number.isFinite(this.now + Number(m.refresh_token_expires_in) * 1000)))
+            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 };
+            scope: typeof m.scope === 'string' ? m.scope : previous?.scope,
+            refreshExpiresIn: typeof m.refresh_token_expires_in === 'number' ? m.refresh_token_expires_in : previous?.refreshExpiresIn,
+            refreshExpiresAt: typeof m.refresh_token_expires_in === 'number' ? this.now + m.refresh_token_expires_in * 1000 : previous?.refreshExpiresAt };
     }
     /** For trusted app code (mail/calendar/API calls). Never display or log this value. */
     async token(rejectedAccessToken) {
@@ -202,6 +245,11 @@ export class Connection {
                     return old.access;
                 throw new ConnectError('signin');
             }
+            if (old.refreshExpiresAt !== undefined && old.refreshExpiresAt <= this.now) {
+                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)

package/dist/errors.d.ts

@@ -1,7 +1,14 @@
 export type ConnectErrorCode = 'configuration' | 'discovery' | 'registration' | 'callback' | 'expired' | 'declined' | 'scope' | 'token' | 'signin' | 'network';
-/** Never includes provider bodies, callback codes, credentials or URLs. */
+export interface ProviderErrorCause {
+    readonly error: string;
+    readonly error_description?: string;
+}
+/** Preserve OAuth diagnostics, removing credentials supplied to or returned by the provider. */
+export declare function providerCause(body: Record<string, unknown>, secrets: readonly string[]): ProviderErrorCause | undefined;
+/** Plain message and optional sanitized OAuth cause; never includes raw response bodies. */
 export declare class ConnectError extends Error {
     readonly code: ConnectErrorCode;
     readonly status?: number;
-    constructor(code: ConnectErrorCode, status?: number);
+    readonly cause?: ProviderErrorCause;
+    constructor(code: ConnectErrorCode, status?: number, cause?: ProviderErrorCause);
 }

package/dist/errors.js

@@ -1,11 +1,31 @@
 import WORDS from './words.json' with { type: 'json' };
 const words = WORDS.errors;
-/** Never includes provider bodies, callback codes, credentials or URLs. */
+/** Preserve OAuth diagnostics, removing credentials supplied to or returned by the provider. */
+export function providerCause(body, secrets) {
+    if (typeof body.error !== 'string')
+        return undefined;
+    const values = [...secrets, ...['access_token', 'refresh_token', 'id_token', 'client_secret', 'client_id'].map(k => body[k]).filter((v) => typeof v === 'string')];
+    const redact = (text) => {
+        for (const value of values.filter(Boolean).sort((a, b) => b.length - a.length)) {
+            const variants = new Set([value, new URLSearchParams({ v: value }).toString().slice(2)]);
+            try {
+                variants.add(encodeURIComponent(value));
+            }
+            catch { /* Malformed Unicode still gets literal/form redaction. */ }
+            for (const encoded of variants)
+                text = text.split(encoded).join('[redacted]');
+        }
+        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'];
+    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. */
 export class ConnectError extends Error {
     code;
     status;
-    constructor(code, status) {
-        super(words[code]);
+    constructor(code, status, cause) {
+        super(words[code], cause ? { cause } : undefined);
         this.name = 'ConnectError';
         this.code = code;
         this.status = status;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ 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 type { ConnectErrorCode, ProviderErrorCause } from './errors.ts';
+export type { Provider, OAuthClient, OAuthEndpoints, ConnectOptions, SignIn, McpOptions, Grant, ClientVerification } from './types.ts';
 export { Client } from '@modelcontextprotocol/sdk/client/index.js';
 export * from '@modelcontextprotocol/sdk/types.js';

package/dist/types.d.ts

@@ -53,3 +53,26 @@ export interface McpOptions {
     /** Register sampling/elicitation/request/notification handlers before connecting. */
     configure?: (client: import('@modelcontextprotocol/sdk/client/index.js').Client) => void;
 }
+/** Trusted app data only: never display or log credentials. Times are Unix milliseconds. */
+export interface Grant {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    scope?: string;
+    /** The provider's refresh_token_expires_in value, in seconds. */
+    refreshTokenExpiresIn?: number;
+    /** Absolute deadline; unlike the duration, this does not restart on restore. */
+    refreshTokenExpiresAt?: number;
+}
+export type ClientVerification = {
+    outcome: 'valid';
+    message: string;
+} | {
+    outcome: 'invalid';
+    message: string;
+    cause?: import('./errors.ts').ProviderErrorCause;
+} | {
+    outcome: 'inconclusive';
+    message: string;
+    cause?: import('./errors.ts').ProviderErrorCause;
+};

package/dist/words.json

@@ -17,5 +17,10 @@
         "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."
+    },
+    "verification": {
+        "valid": "Your app details work.",
+        "invalid": "Check your app details and try again.",
+        "inconclusive": "Your app details could not be checked. Try again later."
     }
 }

package/package.json

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