@lanes-sh/link 0.1.0

package/src/cli/main.ts

@@ -0,0 +1,333 @@
+import { connect } from './commands/connect/index.ts';
+import {
+  attachFile,
+  auditTail,
+  auditVerify,
+  check,
+  configShow,
+  doctor,
+  outputs,
+  plan,
+  policyList,
+  policyRule,
+  start,
+  status,
+  tokenRotate,
+  tokenShow,
+} from './commands/operate.ts';
+import { profileAdd, profileDefault, profileList } from './commands/profile.ts';
+import { removeProfile as profileRemove } from './commands/profile/remove.ts';
+import { targetList, targetShow, targetUse } from './commands/target.ts';
+import { setupPlan } from './commands/setup.ts';
+import { mcpAdd, mcpList, mcpStdio, skillDocument } from './commands/mcp.ts';
+import { deploy } from '#deployments/deploy.ts';
+import { secretsList, secretsPush, secretsSet } from './commands/secrets.ts';
+import {
+  memoryForget,
+  memoryGet,
+  memoryList,
+  memoryWrite,
+  skillsAdd,
+  skillsList,
+  skillsRemove,
+  skillsShow,
+  vaultGet,
+  vaultKeyGenerate,
+  vaultList,
+  vaultRemove,
+  vaultSet,
+} from './commands/owner.ts';
+import { globalFlags, ownerFlags, parseArgv, text } from './argv.ts';
+import { PROGRAM, USAGE } from './usage.ts';
+import { version } from './version.ts';
+import { print } from './output.ts';
+
+/**
+ * `lanes link` — the control plane.
+ *
+ * Every control-plane operation lives here and nowhere else. Policy changes,
+ * token management, credential writing, and config mutation each authorise
+ * *future* agent behaviour, so the decision has to originate outside the
+ * agent — ADR-007. There is no admin API, and a running instance never
+ * mutates its own configuration.
+ *
+ * What is left in this file is the grammar and nothing else: which word maps to
+ * which function. Parsing argv is `argv.ts`, the help text is `usage.ts`, and
+ * every command is under `commands/`.
+ */
+
+export async function run(argv: readonly string[]): Promise<void> {
+  const { command, flags } = parseArgv(argv);
+  const [first, second, ...rest] = command;
+
+  const global = globalFlags(flags);
+  const owner = ownerFlags(flags);
+
+  const show = flags['show'] === true;
+  const raw = flags['raw'] === true;
+  const json = flags['json'] === true;
+
+  if (!first || first === 'help' || flags['help'] === true) {
+    print(USAGE);
+    return;
+  }
+
+  switch (first) {
+    case 'connect':
+      if (!second) throw new Error(`Usage: ${PROGRAM} connect <provider>`);
+      return connect(second, {
+        ...global,
+        id: text(flags, 'id'),
+        displayName: text(flags, 'display-name'),
+        replace: flags['replace'] === true,
+        nonInteractive: flags['non-interactive'] === true,
+        acceptBroadScopes: flags['accept-broad-scopes'] === true,
+        ownClient: flags['own-client'] === true,
+        json,
+      });
+
+    case 'setup':
+      if (second !== 'plan' && second !== undefined) {
+        throw new Error(`Unknown: ${PROGRAM} setup ${second}`);
+      }
+      return setupPlan(rest[0], { ...global, json, id: text(flags, 'id') });
+
+    case 'profile':
+      switch (second) {
+        case 'add':
+          if (!rest[0]) throw new Error(`Usage: ${PROGRAM} profile add <name> [--default]`);
+          return profileAdd(rest[0], { default: flags['default'] === true, json });
+        case 'list':
+        case undefined:
+          return profileList({ json });
+        case 'default':
+          if (!rest[0]) throw new Error(`Usage: ${PROGRAM} profile default <name>`);
+          return profileDefault(rest[0]);
+        case 'remove':
+          if (!rest[0]) {
+            throw new Error(
+              `Usage: ${PROGRAM} profile remove <name> [--target t] [--dry-run] [--yes]`,
+            );
+          }
+          return profileRemove(rest[0], {
+            ...global,
+            json,
+            dryRun: flags['dry-run'] === true,
+            yes: flags['yes'] === true,
+          });
+        default:
+          throw new Error(`Unknown: ${PROGRAM} profile ${second}`);
+      }
+
+    case 'target':
+      switch (second) {
+        case 'list':
+        case undefined:
+          return targetList({ ...global, json, urls: flags['urls'] === true });
+        case 'use':
+          if (!rest[0]) throw new Error(`Usage: ${PROGRAM} target use <name>`);
+          return targetUse(rest[0], global);
+        case 'show':
+          return targetShow(rest[0], { ...global, json });
+        default:
+          throw new Error(`Unknown: ${PROGRAM} target ${second}`);
+      }
+
+    case 'policy':
+      switch (second) {
+        case 'list':
+        case undefined:
+          return policyList(global);
+        case 'allow':
+        case 'deny': {
+          const [capability] = rest;
+          if (!capability) {
+            throw new Error(
+              `Usage: ${PROGRAM} policy ${second} <capability>\n` +
+                `  e.g. ${PROGRAM} policy ${second} gmail.send_message, or gmail.* for the whole provider`,
+            );
+          }
+          return policyRule(second, capability, global);
+        }
+        default:
+          throw new Error(`Unknown: ${PROGRAM} policy ${second}`);
+      }
+
+    case 'token':
+      switch (second) {
+        case 'show':
+        case undefined:
+          return tokenShow({ ...global, show, raw });
+        case 'rotate':
+          return tokenRotate({ ...global, show });
+        default:
+          throw new Error(`Unknown: ${PROGRAM} token ${second}`);
+      }
+
+    case 'audit':
+      if (second === 'verify') return auditVerify(global);
+      if (second !== 'tail' && second !== undefined) {
+        throw new Error(`Unknown: ${PROGRAM} audit ${second}`);
+      }
+      return auditTail({
+        ...global,
+        limit: typeof flags['limit'] === 'string' ? Number(flags['limit']) : undefined,
+        deniedOnly: flags['denied-only'] === true,
+        ...(typeof flags['format'] === 'string' ? { format: flags['format'] } : {}),
+      });
+
+    // The file is positional rather than `--file`, because `attach <file>` is
+    // how every other tool spells it and this one is typed by a person.
+    case 'attach':
+      return attachFile({
+        ...global,
+        file: second,
+        connection: text(flags, 'connection'),
+      });
+
+    case 'config':
+      if (second !== 'show' && second !== undefined) throw new Error(`Unknown: ${PROGRAM} config ${second}`);
+      return configShow(global);
+
+    case 'memory':
+      switch (second) {
+        case 'list':
+        case undefined:
+          return memoryList(owner);
+        case 'get':
+          return memoryGet(rest[0], owner);
+        case 'write':
+          return memoryWrite(rest[0], owner);
+        case 'forget':
+          return memoryForget(rest[0], owner);
+        default:
+          throw new Error(`Unknown: ${PROGRAM} memory ${second}`);
+      }
+
+    case 'skills':
+      switch (second) {
+        case 'list':
+        case undefined:
+          return skillsList(owner);
+        case 'show':
+          return skillsShow(rest[0], owner);
+        case 'add':
+          return skillsAdd(rest[0], owner);
+        case 'remove':
+          return skillsRemove(rest[0], owner);
+        default:
+          throw new Error(`Unknown: ${PROGRAM} skills ${second}`);
+      }
+
+    case 'vault':
+      switch (second) {
+        case 'list':
+        case undefined:
+          return vaultList(owner);
+        case 'get':
+          return vaultGet(rest[0], owner);
+        case 'set':
+          return vaultSet(rest[0], owner);
+        case 'remove':
+          return vaultRemove(rest[0], owner);
+        case 'key':
+          if (rest[0] !== 'generate') {
+            throw new Error(`Usage: ${PROGRAM} vault key generate`);
+          }
+          return vaultKeyGenerate(owner);
+        default:
+          throw new Error(`Unknown: ${PROGRAM} vault ${second}`);
+      }
+
+    case 'check':
+      return check(global);
+    case 'plan':
+      return plan(global);
+    case 'doctor':
+      return doctor({ ...global, json });
+    case 'status':
+      return status({ ...global, json });
+    case 'outputs':
+      return outputs({ ...global, show, json });
+
+    // Undocumented alias for `mcp skill`, which is where it moved when `skills`
+    // arrived. Anyone who learned the old spelling keeps it.
+    case 'skill':
+      return skillDocument({ print: flags['print'] === true });
+
+    case 'mcp':
+      switch (second) {
+        // `lanes link skill` was this, before `lanes link skills` existed. Two
+        // commands one letter apart, meaning entirely different things — the
+        // agent-side skill file that teaches a harness to register this
+        // endpoint, and the owner's own procedures — is a trap worth closing.
+        // Kept working below rather than removed, undocumented.
+        case 'skill':
+          return skillDocument({ print: flags['print'] === true });
+        case 'add':
+          return mcpAdd(rest[0], {
+            ...global,
+            name: text(flags, 'name'),
+            scope: text(flags, 'scope'),
+            tokenEnv: text(flags, 'token-env'),
+            dryRun: flags['dry-run'] === true,
+            force: flags['force'] === true,
+            noSkill: flags['no-skill'] === true,
+          });
+        case 'stdio':
+          return mcpStdio({ ...global, ...(flags['only'] === true ? { only: true } : {}) });
+        case 'list':
+        case undefined:
+          return mcpList({ name: text(flags, 'name'), scope: text(flags, 'scope') });
+        default:
+          throw new Error(`Unknown: ${PROGRAM} mcp ${second}`);
+      }
+    case 'start':
+      return start({
+        ...global,
+        port: typeof flags['port'] === 'string' ? Number(flags['port']) : undefined,
+        only: flags['only'] === true,
+      });
+
+    case 'deploy':
+      return deploy({
+        ...global,
+        dryRun: flags['dry-run'] === true,
+        // `--iam` was a boolean that meant "add the platform's own check on top".
+        // It is now one of two values of a declared field, because the opposite
+        // is a choice too and a flag that only turns something on cannot express
+        // turning it off again for a target whose config says otherwise.
+        access: flags['iam'] === true ? 'iam' : text(flags, 'access'),
+        serviceAccount: text(flags, 'service-account'),
+        tag: text(flags, 'tag'),
+        yes: flags['yes'] === true,
+        nonInteractive: flags['non-interactive'] === true,
+      });
+
+    case 'secrets':
+      switch (second) {
+        case 'push':
+          return secretsPush({
+            ...global,
+            from: text(flags, 'from'),
+            to: text(flags, 'to'),
+            overwrite: flags['overwrite'] === true,
+            dryRun: flags['dry-run'] === true,
+          });
+        case 'set':
+          return secretsSet(rest[0], global);
+        case 'list':
+        case undefined:
+          return secretsList(global);
+        default:
+          throw new Error(`Unknown: ${PROGRAM} secrets ${second}`);
+      }
+
+    case 'version':
+      print(version());
+      return;
+
+    default:
+      throw new Error(`Unknown command "${first}". Run: ${PROGRAM} help`);
+  }
+}

package/src/cli/oauth-error.ts

@@ -0,0 +1,13 @@
+/**
+ * The one error type the OAuth flow throws.
+ *
+ * Its own file because both halves of the flow raise it — the listener in
+ * `oauth.ts` and the exchange in `oauth-exchange.ts` — and having either import
+ * the other would be a cycle for the sake of one class.
+ */
+export class OAuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'OAuthError';
+  }
+}

package/src/cli/oauth-exchange.ts

@@ -0,0 +1,146 @@
+import { BrokerError, brokerExchange } from '#connectivity/auth/index.ts';
+import { OAuthError } from './oauth-error.ts';
+
+/**
+ * Turning an authorization code into tokens — the one step that needs a secret.
+ *
+ * Split from `oauth.ts` because it is the only part of the flow that differs
+ * between a client the operator registered and a client somebody operates on
+ * their behalf. Everything else — the loopback listener, PKCE, the state check,
+ * the browser — is identical either way, and keeping it that way is the point:
+ * a connection should not behave differently at runtime because of where its
+ * client came from.
+ */
+
+export interface OAuthTokens {
+  readonly refreshToken: string;
+  readonly accessToken: string;
+  readonly expiresIn: number;
+  readonly scope: string;
+  /**
+   * An identity assertion, present when `openid` was granted.
+   *
+   * Opaque here on purpose. It is stored and handed back to whoever asked for
+   * it, never decoded — the claim inside is unverified, and a tamperable local
+   * store is not somewhere to read an identity from. What names an account is
+   * the provider's own identity call, which asks and gets a checkable answer.
+   */
+  readonly idToken?: string;
+}
+
+export interface ExchangeInput {
+  readonly code: string;
+  readonly redirectUri: string;
+  readonly codeVerifier: string;
+  /** What was asked for, used only to fill in a response that omits `scope`. */
+  readonly scopes: readonly string[];
+}
+
+export type ExchangeCode = (input: ExchangeInput) => Promise<OAuthTokens>;
+
+/** Straight to the vendor, signed with a client this machine holds. */
+export function directExchange(options: {
+  readonly tokenUrl: string;
+  readonly clientId: string;
+  readonly clientSecret: string;
+  readonly fetch?: typeof globalThis.fetch | undefined;
+}): ExchangeCode {
+  return async (input) => {
+    const doFetch = options.fetch ?? globalThis.fetch;
+
+    const response = await doFetch(options.tokenUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: input.code,
+        redirect_uri: input.redirectUri,
+        client_id: options.clientId,
+        client_secret: options.clientSecret,
+        code_verifier: input.codeVerifier,
+      }),
+    });
+
+    const body = (await response.json().catch(() => ({}))) as {
+      access_token?: string;
+      refresh_token?: string;
+      id_token?: string;
+      expires_in?: number;
+      scope?: string;
+      error?: string;
+      error_description?: string;
+    };
+
+    if (!response.ok || !body.access_token) {
+      throw new OAuthError(
+        `Token exchange failed: ${body.error ?? response.status} ${body.error_description ?? ''}`.trim(),
+      );
+    }
+
+    return settle(body, input.scopes);
+  };
+}
+
+/** Through a broker, which holds the secret this machine does not have. */
+export function brokerExchangeVia(options: {
+  readonly url: string;
+  readonly fetch?: typeof globalThis.fetch | undefined;
+}): ExchangeCode {
+  return async (input) => {
+    let tokens;
+    try {
+      tokens = await brokerExchange(
+        options.url,
+        {
+          code: input.code,
+          codeVerifier: input.codeVerifier,
+          redirectUri: input.redirectUri,
+        },
+        options.fetch ?? globalThis.fetch,
+      );
+    } catch (cause) {
+      // Rethrown as-is when it is a BrokerError: it carries the notice and the
+      // "your own client would fix this" flag that the caller renders, and
+      // flattening it to a string here would throw both away.
+      if (cause instanceof BrokerError) throw cause;
+      throw new OAuthError(`Token exchange failed: ${String(cause)}`);
+    }
+
+    if (!tokens.access_token) {
+      throw new OAuthError('The token exchange returned no access token.');
+    }
+
+    return settle(tokens, input.scopes);
+  };
+}
+
+function settle(
+  body: {
+    access_token?: string | undefined;
+    refresh_token?: string | undefined;
+    id_token?: string | undefined;
+    expires_in?: number | undefined;
+    scope?: string | undefined;
+  },
+  scopes: readonly string[],
+): OAuthTokens {
+  if (!body.refresh_token) {
+    // Without one, the connection works until the access token expires and then
+    // quietly stops. Better to fail now with the actual cause. Google is named
+    // because Google is who reaches this path: every provider that redeems a
+    // code here is a Google REST one, and the others hand the exchange to the
+    // MCP SDK. Naming the page beats describing it.
+    throw new OAuthError(
+      'Google returned no refresh token. This usually means the account was already authorised ' +
+        'for this app; revoke it at https://myaccount.google.com/permissions and try again.',
+    );
+  }
+
+  return {
+    refreshToken: body.refresh_token,
+    accessToken: body.access_token!,
+    expiresIn: body.expires_in ?? 3600,
+    scope: body.scope ?? scopes.join(' '),
+    ...(body.id_token ? { idToken: body.id_token } : {}),
+  };
+}