@invitedlabs/cli 0.0.0-stage → 0.1.0

package/dist/main.js

@@ -0,0 +1,210 @@
+import { homedir } from 'node:os';
+import { checkOptions, COMMAND_OPTIONS, parseArgs } from './args.js';
+import { openBrowser } from './browser.js';
+import { fragments, login, logout, privateFragments, settingsLine, status, whoami, } from './commands.js';
+import { connect, HOSTS } from './connect.js';
+import { configDir, credentialStore } from './credentials.js';
+import { CliError } from './errors.js';
+import { style as outputStyle } from './format.js';
+import { VERSION } from './version.js';
+/**
+ * `invited`: the command-line client of Invited's MCP connector
+ * (docs/mcp-connector-2026-10-11.md, "3e: CLI"). It configures assistants'
+ * hosts to use the connector, and signs in itself as the pre-registered
+ * client `invited-cli` to print the member's public Identity in a terminal.
+ * It holds an OAuth refresh token like any other client, never a vault key.
+ */
+export const DEFAULT_ORIGIN = 'https://invited.you';
+const defaults = () => ({
+    fetch: (input, init) => fetch(input, init),
+    env: process.env,
+    out: text => void process.stdout.write(text),
+    err: text => void process.stderr.write(text),
+    now: Date.now,
+    home: homedir(),
+    platform: process.platform,
+    openBrowser: url => openBrowser(url, process.platform),
+    loginTimeoutMs: 5 * 60_000,
+});
+/** Invited's address: https, or http on this computer (a local Invited such
+ * as http://127.0.0.1:4180). The connector's own address (…/mcp) is accepted. */
+export function normalOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new CliError(`${value} is not an address. Use ${DEFAULT_ORIGIN}, or http://127.0.0.1:4180 for a local Invited.`);
+    }
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))
+        throw new CliError(`${value} is not safe for a sign-in: use https, or http only on this computer.`);
+    if (url.username || url.password || url.search || url.hash || !['', '/', '/mcp', '/mcp/'].includes(url.pathname))
+        throw new CliError(`Give Invited's address without a path, such as ${DEFAULT_ORIGIN}.`);
+    return url.origin;
+}
+const HELP = {
+    connect: `Usage: invited connect <host> [--dry-run] [--bridge] [--config <file>] [--origin <url>]
+
+Adds Invited's MCP server (${DEFAULT_ORIGIN}/mcp) to an assistant's host under the
+name "invited", keeping every other server in the file as it is. Hosts:
+  claude-code   ~/.claude.json (user scope)
+  cursor        ~/.cursor/mcp.json
+  codex         ~/.codex/config.toml ($CODEX_HOME)
+  gemini        ~/.gemini/settings.json
+The host then signs in to Invited itself: you approve it in your browser.
+
+  --dry-run        Show what would be written; write nothing
+  --bridge         Use the mcp-remote bridge (npx -y mcp-remote@0.14.3) instead of the
+                   host's own sign-in, for a host version without remote sign-in
+  --config <file>  The configuration file to edit, instead of the host's usual one
+  --origin <url>   Invited's address (default ${DEFAULT_ORIGIN})
+`,
+    login: `Usage: invited login [--private] [--no-browser] [--origin <url>]
+
+Connects this CLI to your Identity: your browser opens Invited, you approve the
+Invited CLI, and the browser returns to a listener on this computer
+(http://127.0.0.1, a port the system picks), which closes as soon as it answers
+or after 5 minutes. The sign-in is saved in ~/.invited/credentials.json.
+
+  --private        Also ask for your private fragments: in the browser you choose
+                   which to share with this CLI, and for how long
+  --no-browser     Print the address to open instead of opening the browser
+  --origin <url>   Invited's address (default ${DEFAULT_ORIGIN})
+`,
+    whoami: `Usage: invited whoami [--json] [--origin <url>]
+
+Prints your public Identity: what your Invited Page publishes for AI readers,
+as Markdown (invited://identity), or as JSON with --json (invited://identity.json).
+`,
+    fragments: `Usage: invited fragments --type <type> [--type <type> ...] [--json]
+       invited fragments --search <words> [--json]
+
+Prints your public fragments of the given types (get_fragments), or the ones that
+match some words, best first (search_fragments). Types are keys such as skill,
+language, experience, cuisines or dietaryPreferences.
+`,
+    private: `Usage: invited private [--type <type> ...] [--json] [--origin <url>]
+
+Prints the private fragments you share with this CLI (private_fragments), and when
+that sharing ends. You choose them in your browser with \`invited login --private\`.
+While they are shared, Invited's server can read them to pass them on.
+`,
+    status: `Usage: invited status [--json] [--origin <url>]
+
+Shows the sign-in this CLI holds: your Identity and Page, its scopes, when it was
+last used and when it expires. It reads the credentials file only. Listing every
+assistant you have connected needs your browser: Settings, Connected assistants.
+`,
+    logout: `Usage: invited logout [--origin <url>]     (also: invited revoke)
+
+Revokes this CLI's own sign-in at Invited and deletes its credentials. Other
+assistants are disconnected in Settings, not here.
+`,
+};
+HELP.revoke = HELP.logout;
+function help(topic, style) {
+    if (topic && HELP[topic])
+        return HELP[topic];
+    return `invited ${VERSION}: connect AI assistants and terminal agents to your Invited Identity.
+
+${style.bold('Usage')}
+  invited <command> [options]
+
+${style.bold('Commands')}
+  connect <host>   Add Invited's MCP server to ${HOSTS.slice(0, -1).join(', ')} or ${HOSTS.at(-1)}
+  login            Connect this CLI to your Identity (you approve in your browser)
+  whoami           Print your public Identity as Markdown
+  fragments        Print public fragments: --type <type> (repeatable) or --search <words>
+  private          Print the private fragments you share with this CLI
+  status           Show the sign-in this CLI holds
+  logout           Revoke this CLI's sign-in and delete its credentials (also: revoke)
+
+${style.bold('Options')}
+  --origin <url>   Invited's address (default ${DEFAULT_ORIGIN}, or INVITED_ORIGIN)
+  --json           Print JSON (whoami, fragments, private, status)
+  --dry-run        connect: show what would be written, write nothing
+  --bridge         connect: use the mcp-remote bridge instead of the host's own sign-in
+  --config <file>  connect: the configuration file to edit
+  --no-browser     login: print the address instead of opening a browser
+  --private        login: also choose private fragments to share with this CLI
+  -h, --help       Show help (invited help <command> for one command)
+  -v, --version    Show the version
+
+The CLI keeps its sign-in in ~/.invited/credentials.json (INVITED_CONFIG_DIR moves it)
+and reads what your Invited Page publishes, and the private fragments you choose to
+share with it, within 60 reads a minute.
+${settingsLine(DEFAULT_ORIGIN)}
+`;
+}
+/** Runs one command; resolves to the exit code (0 or 1). */
+export async function main(argv, partial = {}) {
+    const environment = { ...defaults(), ...partial };
+    const style = outputStyle(environment.env);
+    try {
+        const { command, positionals, flags, given } = parseArgs(argv);
+        if (flags.version) {
+            environment.out(`invited ${VERSION}\n`);
+            return 0;
+        }
+        if (command === null || command === 'help') {
+            environment.out(help(command === 'help' ? positionals[0] : undefined, style));
+            return command === null && !flags.help ? 1 : 0;
+        }
+        if (!(command in COMMAND_OPTIONS))
+            throw new CliError(`Unknown command ${command}. Run \`invited --help\` to see the commands.`);
+        if (flags.help) {
+            environment.out(help(command, style));
+            return 0;
+        }
+        checkOptions(command, given);
+        const most = command === 'connect' || command === 'revoke' ? 1 : 0;
+        if (positionals.length > most)
+            throw new CliError(`\`invited ${command}\` was given too many words: ${positionals.slice(most).join(' ')}.`);
+        const origin = normalOrigin(flags.origin ?? (environment.env.INVITED_ORIGIN?.trim() || DEFAULT_ORIGIN));
+        if (command === 'connect') {
+            await connect({
+                host: positionals[0],
+                origin,
+                home: environment.home,
+                env: environment.env,
+                platform: environment.platform,
+                config: flags.config,
+                dryRun: flags.dryRun,
+                bridge: flags.bridge,
+                out: environment.out,
+            });
+            return 0;
+        }
+        const store = credentialStore(configDir(environment.env, environment.home));
+        if (await store.tooOpen())
+            environment.err(`Warning: other users of this computer can read ${store.path}. Run: chmod 600 ${store.path}\n`);
+        const ctx = { ...environment, origin, store, style };
+        switch (command) {
+            case 'login':
+                await login(ctx, { noBrowser: flags.noBrowser, private: flags.private });
+                return 0;
+            case 'whoami':
+                await whoami(ctx, flags.json);
+                return 0;
+            case 'fragments':
+                await fragments(ctx, { types: flags.types, search: flags.search, json: flags.json });
+                return 0;
+            case 'private':
+                await privateFragments(ctx, { types: flags.types, json: flags.json });
+                return 0;
+            case 'status':
+                return await status(ctx, flags.json);
+            default:
+                await logout(ctx, positionals[0]);
+                return 0;
+        }
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            environment.err(error.message + '\n');
+        else
+            environment.err(`Something went wrong: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/mcp.js

@@ -0,0 +1,144 @@
+import { CliError } from './errors.js';
+import { readJson, retryAfter, send } from './http.js';
+import { mcpUrl } from './oauth.js';
+import { VERSION } from './version.js';
+/**
+ * A client of Invited's MCP server at revision 2026-07-28 only
+ * (docs/mcp-connector-2026-10-11.md, "3b: server"): one POST per message,
+ * stateless, no initialize handshake. Every request carries its protocol
+ * version, client information and capabilities in `params._meta`, and mirrors
+ * them in the headers 3b checks: MCP-Protocol-Version, Mcp-Method and, for
+ * tools/call and resources/read, Mcp-Name. This CLI talks only to Invited, so
+ * it falls back to no older revision.
+ */
+export const PROTOCOL_VERSION = '2026-07-28';
+const NAMED = { 'tools/call': 'name', 'resources/read': 'uri' };
+/** Streamable HTTP "Value Encoding": a header value outside printable ASCII
+ * is sent as =?base64?…?=. */
+export const headerValue = (value) => /^[\x20-\x7e]*$/.test(value) && !/^=\?base64\?/.test(value)
+    ? value
+    : `=?base64?${Buffer.from(value, 'utf8').toString('base64')}?=`;
+/** A JSON-RPC error in an answer the server sent with HTTP 200 (an unknown
+ * resource, a Page with nothing for AI readers). */
+export class McpError extends CliError {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+}
+/** 403 insufficient_scope: this connection lacks the scope a read needs, or
+ * (identity:private) the member shares nothing with it now. The member's
+ * consent is the way on (MCP authorization, "Scope Challenge Handling"). */
+export class ScopeRefused extends CliError {
+    scope;
+    constructor(scope, message) {
+        super(message);
+        this.scope = scope;
+    }
+}
+let nextId = 1;
+export async function mcpRequest(fetch, origin, token, method, params) {
+    const id = nextId++;
+    const body = JSON.stringify({
+        jsonrpc: '2.0',
+        id,
+        method,
+        params: {
+            ...params,
+            _meta: {
+                'io.modelcontextprotocol/protocolVersion': PROTOCOL_VERSION,
+                'io.modelcontextprotocol/clientInfo': { name: 'invited-cli', title: 'Invited CLI', version: VERSION },
+                'io.modelcontextprotocol/clientCapabilities': {},
+            },
+        },
+    });
+    const named = NAMED[method];
+    let response;
+    for (let attempt = 0;; attempt++) {
+        response = await send(fetch, mcpUrl(origin), {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${await token(attempt > 0)}`,
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+                'mcp-protocol-version': PROTOCOL_VERSION,
+                'mcp-method': headerValue(method),
+                ...(named ? { 'mcp-name': headerValue(String(params[named])) } : {}),
+            },
+            body,
+        });
+        // An access token refused once is renewed once (it may have expired, or
+        // been revoked: then the renewal says so).
+        if (response.status !== 401 || attempt > 0)
+            break;
+        await response.body?.cancel();
+    }
+    return answer(response, id);
+}
+async function answer(response, id) {
+    const type = response.headers.get('content-type') ?? '';
+    if (response.status === 200 && /^text\/event-stream/i.test(type))
+        return outcome(await fromEventStream(response, id));
+    const body = await readJson(response);
+    const error = (typeof body.error === 'object' && body.error !== null ? body.error : {});
+    const message = typeof error.message === 'string' ? error.message : null;
+    switch (response.status) {
+        case 200:
+            return outcome(body);
+        case 401: {
+            const reason = typeof body.error_description === 'string' ? ` (${body.error_description.replace(/\.$/, '')})` : '';
+            throw new CliError(`Invited did not accept this CLI's sign-in${reason}. Run \`invited login\` to connect again.`);
+        }
+        case 403: {
+            const challenge = response.headers.get('www-authenticate') ?? '';
+            const data = (error.data ?? {});
+            const scope = /(?:^|[\s,])scope="([^"]+)"/.exec(challenge)?.[1] ?? (typeof data.scope === 'string' ? data.scope : null);
+            if (/error="insufficient_scope"/.test(challenge) && scope)
+                throw new ScopeRefused(scope, `Invited refused this read: ${message ?? `it needs the ${scope} scope.`}`);
+            throw new CliError(`Invited refused this read: ${message ?? 'this connection may not read it.'}`);
+        }
+        case 429: {
+            const data = (error.data ?? {});
+            const wait = retryAfter(response) ?? (typeof data.retryAfter === 'number' ? data.retryAfter : 60);
+            throw new CliError(`Too many reads: this connection has used its 60 reads a minute, which every Invited CLI signed in to your Identity shares. Try again in ${wait} seconds.`);
+        }
+        case 503:
+            throw new CliError(`Invited could not complete this request. Try again in ${retryAfter(response) ?? 30} seconds.`);
+        default:
+            throw new CliError(`Invited answered ${response.status}${message ? ': ' + message : '.'}`);
+    }
+}
+function outcome(message) {
+    if (typeof message.error === 'object' && message.error !== null) {
+        const error = message.error;
+        throw new McpError(typeof error.code === 'number' ? error.code : 0, typeof error.message === 'string' ? error.message : 'Invited refused the request.', error.data);
+    }
+    if (typeof message.result !== 'object' || message.result === null)
+        throw new CliError('Invited answered in a form this CLI does not know.');
+    return message.result;
+}
+/** A request-scoped SSE answer (Streamable HTTP lets a server send one;
+ * Invited sends JSON): the JSON-RPC response with this request's id. */
+async function fromEventStream(response, id) {
+    for (const event of (await response.text()).split(/\r?\n\r?\n/)) {
+        const data = event
+            .split(/\r?\n/)
+            .filter(line => line.startsWith('data:'))
+            .map(line => line.slice(5).replace(/^ /, ''))
+            .join('\n');
+        if (!data)
+            continue;
+        try {
+            const message = JSON.parse(data);
+            if (message.id === id && ('result' in message || 'error' in message))
+                return message;
+        }
+        catch {
+            // Not a JSON-RPC message: skip it.
+        }
+    }
+    throw new CliError('Invited ended its answer without a result.');
+}

package/dist/oauth.js

@@ -0,0 +1,166 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { CliError } from './errors.js';
+import { readJson, retryAfter, send } from './http.js';
+/**
+ * The CLI as an OAuth 2.1 client of Invited's authorization server
+ * (docs/mcp-connector-2026-10-11.md, "3a"): the pre-registered public client
+ * `invited-cli`, whose return addresses are http://127.0.0.1/callback and
+ * http://localhost/callback on any port (RFC 8252 section 7.3). PKCE (S256),
+ * `state`, the `resource` indicator (RFC 8707) and the `iss` response
+ * parameter (RFC 9207). It only ever talks to the Invited origin it was
+ * given: discovery must name that origin as the issuer and every endpoint.
+ */
+export const CLIENT_ID = 'invited-cli';
+/** What the CLI asks for: the public Identity, and with `login --private` the
+ * private fragments the member chooses to share on the consent screen
+ * (Phase 4, step 4b). */
+export const PUBLIC_SCOPE = 'identity:public';
+export const PRIVATE_SCOPE = 'identity:private';
+export const mcpUrl = (origin) => origin + '/mcp';
+async function getJson(fetch, url) {
+    const response = await send(fetch, url, { headers: { accept: 'application/json' } });
+    if (response.status !== 200)
+        throw new CliError(`${new URL(url).origin} answered ${response.status} for ${new URL(url).pathname}.`);
+    return readJson(response);
+}
+const notInvited = (origin) => new CliError(`${origin} does not describe itself as Invited's connector, so this CLI will not sign in there.`);
+/** The protected resource metadata (RFC 9728), then the authorization server
+ * metadata (RFC 8414), each checked against the origin. */
+export async function discover(fetch, origin) {
+    const resource = mcpUrl(origin);
+    const protectedResource = await getJson(fetch, origin + '/.well-known/oauth-protected-resource/mcp');
+    if (protectedResource.resource !== resource ||
+        !Array.isArray(protectedResource.authorization_servers) ||
+        !protectedResource.authorization_servers.includes(origin))
+        throw notInvited(origin);
+    const server = await getJson(fetch, origin + '/.well-known/oauth-authorization-server');
+    const endpoint = (value) => (typeof value === 'string' && value.startsWith(origin + '/') ? value : null);
+    const authorization = endpoint(server.authorization_endpoint), token = endpoint(server.token_endpoint), revocation = endpoint(server.revocation_endpoint);
+    const methods = server.code_challenge_methods_supported;
+    if (server.issuer !== origin ||
+        !authorization ||
+        !token ||
+        !revocation ||
+        !Array.isArray(methods) ||
+        !methods.includes('S256'))
+        throw notInvited(origin);
+    return {
+        issuer: origin,
+        resource,
+        authorization,
+        token,
+        revocation,
+        issInResponse: server.authorization_response_iss_parameter_supported === true,
+    };
+}
+/** RFC 7636: a 43-character verifier from 32 random bytes, and its S256 challenge. */
+export function pkcePair() {
+    const verifier = randomBytes(32).toString('base64url');
+    return { verifier, challenge: createHash('sha256').update(verifier, 'ascii').digest('base64url') };
+}
+export const newState = () => randomBytes(24).toString('base64url');
+export function authorizationUrl(endpoints, redirectUri, challenge, state, scopes = [PUBLIC_SCOPE]) {
+    const url = new URL(endpoints.authorization);
+    url.search = new URLSearchParams({
+        response_type: 'code',
+        client_id: CLIENT_ID,
+        redirect_uri: redirectUri,
+        code_challenge: challenge,
+        code_challenge_method: 'S256',
+        state,
+        scope: scopes.join(' '),
+        resource: endpoints.resource,
+    }).toString();
+    return url.href;
+}
+/** The token endpoint refused the grant (RFC 6749 section 5.2). */
+export class GrantRefused extends CliError {
+    error;
+    description;
+    constructor(error, description) {
+        super(description);
+        this.error = error;
+        this.description = description;
+    }
+}
+/** The Identity the access token names. Invited's access tokens are JWTs
+ * (RFC 9068) whose `identity` claim is the member's Identity; the CLI reads
+ * it as information only (it is not the token's audience). */
+function identityOf(accessToken) {
+    try {
+        const payload = JSON.parse(Buffer.from(accessToken.split('.')[1] ?? '', 'base64url').toString('utf8'));
+        if (typeof payload.identity === 'string' && payload.identity)
+            return payload.identity;
+    }
+    catch {
+        // Not a JWT: refused below.
+    }
+    throw new CliError('Invited answered with an access token this CLI cannot read.');
+}
+async function tokenRequest(fetch, endpoint, form, now) {
+    const response = await send(fetch, endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+        body: new URLSearchParams(form).toString(),
+    });
+    const body = await readJson(response);
+    if (response.status === 429)
+        throw new CliError(`Invited is limiting requests for this sign-in. Try again in ${retryAfter(response) ?? 60} seconds.`);
+    if (response.status >= 500)
+        throw new CliError(`Invited could not complete this request. Try again in ${retryAfter(response) ?? 30} seconds.`);
+    if (response.status !== 200)
+        throw new GrantRefused(typeof body.error === 'string' ? body.error : 'invalid_request', typeof body.error_description === 'string' ? body.error_description : `Invited answered ${response.status}.`);
+    const { access_token: accessToken, refresh_token: refreshToken, token_type: type, expires_in: expiresIn } = body;
+    if (typeof accessToken !== 'string' ||
+        typeof refreshToken !== 'string' ||
+        !refreshToken ||
+        typeof type !== 'string' ||
+        type.toLowerCase() !== 'bearer' ||
+        typeof expiresIn !== 'number')
+        throw new CliError('Invited answered the token request in a form this CLI does not know.');
+    const tokens = {
+        accessToken,
+        accessExpiresAt: now + expiresIn * 1000,
+        refreshToken,
+        scopes: typeof body.scope === 'string' ? body.scope.split(' ').filter(Boolean) : [PUBLIC_SCOPE],
+        identityId: identityOf(accessToken),
+    };
+    return tokens;
+}
+/** The authorization code grant with the PKCE verifier (OAuth 2.1 section 4.1.3). */
+export const exchangeCode = (fetch, endpoints, values, now) => tokenRequest(fetch, endpoints.token, {
+    grant_type: 'authorization_code',
+    code: values.code,
+    code_verifier: values.verifier,
+    redirect_uri: values.redirectUri,
+    client_id: CLIENT_ID,
+    resource: endpoints.resource,
+}, now);
+/** The refresh token grant: Invited spends the token and issues the next one
+ * in the same family (rotation), with a new one-hour access token. */
+export const refreshTokens = (fetch, connection, now) => tokenRequest(fetch, connection.tokenEndpoint, {
+    grant_type: 'refresh_token',
+    refresh_token: connection.refreshToken,
+    client_id: connection.clientId,
+    resource: connection.resource,
+}, now);
+/** RFC 7009: revoking the refresh token ends its whole family, which is this
+ * CLI's own connection and never another assistant's. */
+export async function revokeRefreshToken(fetch, connection) {
+    const response = await send(fetch, connection.revocationEndpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+        body: new URLSearchParams({
+            token: connection.refreshToken,
+            token_type_hint: 'refresh_token',
+            client_id: connection.clientId,
+        }).toString(),
+    });
+    if (response.status === 200)
+        return;
+    const body = await readJson(response);
+    const wait = retryAfter(response);
+    const detail = typeof body.error_description === 'string' ? `: ${body.error_description}` : '';
+    throw new CliError(`Invited did not revoke the sign-in (${response.status}${detail}).` +
+        (wait ? ` Try again in ${wait} seconds.` : ''));
+}