@lanes-sh/link 0.1.0

package/src/cli/scopes.ts

@@ -0,0 +1,63 @@
+import { SCOPE_MEANINGS } from '#providers/scopes.ts';
+
+/**
+ * Saying out loud what a connection is about to be granted.
+ *
+ * Least privilege is the goal, and a vendor's *advertised* scope list is not the
+ * same as its required one. Google's Gmail MCP server advertises five, including
+ * `mail.google.com` — read, send, and permanently delete — while its own
+ * documentation names two. Granting all five was tested against the real service
+ * and changed nothing, so the two are what we ask for.
+ *
+ * Where a grant does have to be broad, it must not happen quietly: an over-broad
+ * grant is invisible after the fact, and a consent screen listing five
+ * Google-worded scopes is not where someone discovers that "Gmail" meant
+ * permanent delete. We print it first, in plain words, and make the broad ones an
+ * explicit yes.
+ *
+ * What each scope *means* is the provider's knowledge and lives in its folder
+ * (`#providers/scopes.ts` merges the contributions). This file is the rendering,
+ * and it works the same for a provider it has never heard of: a scope missing
+ * from the table is printed unannotated rather than mis-described — silence is
+ * the safe failure here.
+ */
+
+export interface ScopeDescription {
+  readonly scope: string;
+  /** Plain-English meaning, where the provider supplied one. */
+  readonly meaning?: string;
+  /** Unrestricted access to the service, or close enough to warrant a stop. */
+  readonly broad: boolean;
+}
+
+export function describeScope(scope: string): ScopeDescription {
+  const known = SCOPE_MEANINGS[scope];
+  return {
+    scope,
+    ...(known?.meaning ? { meaning: known.meaning } : {}),
+    broad: known?.broad === true,
+  };
+}
+
+export function describeScopes(scopes: readonly string[]): ScopeDescription[] {
+  return scopes.map(describeScope);
+}
+
+/**
+ * Shorten a scope for display; the full value is still what is requested.
+ *
+ * Generic on purpose. The last path segment after `/auth/` is the convention
+ * every OAuth vendor that uses URL-shaped scopes follows, and anything else is
+ * left alone rather than guessed at.
+ */
+export function shortScope(scope: string): string {
+  const match = scope.match(/\/auth\/([^/]+)$/);
+  if (match?.[1]) return match[1];
+
+  // A bare host with nothing after it — `https://mail.google.com/` — reads
+  // better without the scheme, and there is nothing else to take.
+  const url = URL.parse?.(scope);
+  if (url && (url.pathname === '/' || url.pathname === '')) return url.host;
+
+  return scope;
+}

package/src/cli/usage.ts

@@ -0,0 +1,111 @@
+import { style } from './output.ts';
+
+/**
+ * The help text, and the name the CLI calls itself.
+ *
+ * `PROGRAM` is a constant rather than 59 string literals because it had been 59
+ * string literals: the rename that produced `lanes link` meant editing the
+ * usage text, every `Usage:` line, and every `Unknown:` line by hand, with no
+ * way to tell from a green test suite whether one had been missed. The next
+ * rename touches this line, and `argv.test.ts` holds the two to each other.
+ *
+ * The text lives here rather than in `main.ts` because it is 65 lines of prose
+ * that changes for entirely different reasons from the dispatch below it.
+ */
+
+/** How this CLI is invoked — the `link` area of the `lanes` command. */
+export const PROGRAM = 'lanes link';
+
+export const USAGE = `${style.bold(PROGRAM)} — a self-hosted MCP gateway for your accounts, memory, skills, and secrets
+
+${style.bold('Everyday')}
+  ${PROGRAM} setup plan [--json]        what each provider needs, and which are connected
+  ${PROGRAM} setup plan <provider>      the console steps, the values, and the command
+  ${PROGRAM} connect <provider>         add an account (run once per account)
+  ${PROGRAM} connect <provider>.<id>    re-authorise one existing account
+  ${PROGRAM} connect <...> --replace    ask for the stored password or key again
+  ${PROGRAM} connect <...> --non-interactive [--json]
+                                        answer nothing from a terminal: take every value
+                                        from the credential store, or say what is missing
+  ${PROGRAM} start [--only]             reconcile and serve every profile on one endpoint
+  ${PROGRAM} outputs [--show] [--json]  the endpoint an agent needs
+  ${PROGRAM} mcp add [claude|codex]     register this endpoint, and install the agent skill
+  ${PROGRAM} mcp add --no-skill         register only, leaving the agent's own files alone
+  ${PROGRAM} mcp list                   where it is registered, and whether the skill is current
+  ${PROGRAM} mcp stdio                  serve on stdin/stdout, for a client that spawns it
+  ${PROGRAM} mcp skill [--print]        the bundled skill — its path, or the document itself
+  ${PROGRAM} status [--json]            connections, reachable capabilities, endpoint
+
+${style.bold('Profiles')}
+  ${PROGRAM} profile add <name> [--default] [--json]
+  ${PROGRAM} profile list [--json]
+  ${PROGRAM} profile default <name>
+  ${PROGRAM} profile remove <name> [--target t] [--dry-run] [--yes] [--json]
+                                 the profile, its credentials, and its data
+
+${style.bold('Targets')}
+  ${PROGRAM} target list [--urls]      where this profile can run, and which one is in play
+  ${PROGRAM} target show [<name>]      one target's adapters, and the address it answers on
+  ${PROGRAM} target use <name>         make one the profile's default_target
+
+${style.bold('Permissions')}
+  ${PROGRAM} policy list
+  ${PROGRAM} policy allow <capability>  e.g. gmail.* or gmail.send_message
+  ${PROGRAM} policy deny  <capability>
+  ${PROGRAM} token show [--show|--raw]  --raw prints only the token, for $(…)
+  ${PROGRAM} token rotate [--show]
+
+${style.bold('Your own context')}
+  ${PROGRAM} memory list [--tag t]      what you have stored
+  ${PROGRAM} memory get <id>
+  ${PROGRAM} memory write <id> --title <t> [--tag t]   body on stdin
+  ${PROGRAM} memory forget <id>
+
+  ${PROGRAM} skills list                the procedures agents can invoke
+  ${PROGRAM} skills show <name>
+  ${PROGRAM} skills add <name> [--file f]             document on stdin
+  ${PROGRAM} skills remove <name>
+
+  ${PROGRAM} vault list                 names only, never values
+  ${PROGRAM} vault get <id> [--show|--raw]
+  ${PROGRAM} vault set <id> [--description d]         value on stdin
+  ${PROGRAM} vault remove <id>
+  ${PROGRAM} vault key generate         a fresh LANES_LINK_VAULT_KEY, printed once
+
+${style.bold('Deploying')}
+  ${PROGRAM} deploy [--dry-run]         set up, build, and roll a revision
+  ${PROGRAM} deploy --non-interactive   take the stored answers, never prompt
+  ${PROGRAM} deploy --access iam|public who gets past the platform's own door
+  ${PROGRAM} deploy --target <name>     deploy a second one, under its own name
+  ${PROGRAM} secrets list               credential references in this target
+  ${PROGRAM} secrets set <ref>          store one value, read from stdin
+  ${PROGRAM} secrets push --from local --to cloud
+
+${style.bold('Inspection')}
+  ${PROGRAM} check                      static validation, no external calls
+  ${PROGRAM} doctor [--json]            credentials resolve, stores reachable
+  ${PROGRAM} plan                       what reconcile would change
+  ${PROGRAM} audit tail [--limit N] [--denied-only] [--format md]
+  ${PROGRAM} audit verify           has anything in the log been altered or removed
+  ${PROGRAM} config show
+  ${PROGRAM} version                    which release this is — same as lanes --version
+
+${style.bold('Attachments')}
+  ${PROGRAM} attach <file> --connection <provider>.<account>
+                                        stage a file, print a handle to send it by
+
+${style.bold('Global flags')}
+  --profile <name>               overrides LANES_LINK_PROFILE and the workspace default
+  --target <name>                overrides LANES_LINK_TARGET and instance.default_target
+  --connection <id>              which memory/skills/vault connection, if a profile has several
+  --yes                          skip the confirmation a destructive command would ask for
+  --json                         machine-readable output, where a command offers it
+  --non-interactive              never prompt: connect refuses with what to store,
+                                 deploy takes the answers its config already holds
+  --accept-broad-scopes          agree in advance to scopes broader than a provider needs
+  --own-client                   register your own OAuth client instead of using the
+                                 one this project operates (connect only)
+  --port <n>                     override the configured port (start only)
+
+Every command prints the resolved profile and target before acting.
+`;

package/src/cli/version.ts

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { installRoot } from '#profile';
+
+/**
+ * What this CLI calls itself when asked.
+ *
+ * Read from `package.json` at call time rather than substituted in at build
+ * time, because there is no build step: the file that declares the version and
+ * the file that ships are the same file. `installRoot` walks up to whichever
+ * root this is — a checkout during development, or the package directory under
+ * `node_modules` once installed — which is the same way `mcp/assets.ts` finds
+ * `instructions/`.
+ *
+ * Answering at all is new with publishing to npm. While the only way to get
+ * this CLI was to clone it, `git log` was the answer and a better one; two
+ * machines can now be a release apart with nothing on either to say so.
+ */
+export function version(): string {
+  const path = join(installRoot(import.meta.dir), 'package.json');
+  const declared = (JSON.parse(readFileSync(path, 'utf8')) as { version?: string }).version;
+
+  if (!declared) throw new Error(`No "version" in ${path}`);
+  return declared;
+}

package/src/connectivity/auth/README.md

@@ -0,0 +1,36 @@
+# Credential types
+
+One folder per method. Each owns both halves of its job: `resolve*` turns the
+stored secret into a `ResolvedCredential`, and `attach*` puts that shape on an
+outbound request. `resolve.ts` and `authorize.ts` are the only files that know
+the whole set.
+
+| Folder | `auth.kind` | What is stored |
+|---|---|---|
+| `none/` | `none` | nothing — `fs` and `local` providers hold no account |
+| `bearer/` | `bearer` | a token, sent as `Authorization: Bearer <token>` |
+| `header/` | `header` | a value, sent raw in a named header (shares api-key's attach) |
+| `api-key/` | `api_key` | a key, in a header or the query string |
+| `basic/` | `basic` | `username:password`, RFC 7617's own encoding |
+| `oauth-authcode/` | `oauth` | a refresh token, exchanged on every use |
+| `strategy/` | `strategy` | the escape hatch — per-vendor code, none registered |
+
+## Adding one
+
+A folder, a member of `authSchema` in `../manifest/auth.ts`, and a case in
+`resolve.ts` (plus `authorize.ts` if it touches the request). Nothing else in
+the codebase learns about it — that is the point of the split.
+
+These are named in the credential-type list this design is measured against and
+are **not built**:
+
+- `sigv4/` — AWS SigV4 request signing
+- `gcp-token/` — service account → GCP access token
+- `gcp-iap/` — service account → an IAP-signed JWT
+- `oauth-jwt/` — OAuth 2.0 JWT bearer (RFC 7523)
+- `oauth-client-creds/` — OAuth 2.0 client credentials
+- `body-param/` — the credential as a request body parameter
+
+Each is a folder here plus a schema member. None of them is a change to a
+transport, a provider, or the dispatch path, which is the property this layout
+exists to give.

package/src/connectivity/auth/api-key/index.ts

@@ -0,0 +1,43 @@
+import type { ResolvedCredential } from '../credential.ts';
+
+/**
+ * A key in a header, or — where a vendor insists — in the query string.
+ *
+ * `query` had been in the schema since M2 and was never read, so an
+ * api-key-in-query manifest sent an unauthenticated request and got a 401
+ * naming nothing.
+ */
+export function resolveApiKey(
+  value: string,
+  options: { header?: string | undefined; query?: string | undefined },
+): ResolvedCredential {
+  return {
+    kind: 'api_key',
+    value,
+    ...(options.query ? { query: options.query } : { header: options.header ?? 'x-api-key' }),
+  };
+}
+
+/**
+ * Returns a replacement request when the key belongs in the URL.
+ *
+ * A Request's URL is immutable, so moving the key into the query means
+ * rebuilding rather than mutating. Passing the Request itself as the init
+ * carries method, headers, and body verbatim; the cast is only because
+ * TypeScript types the init as `RequestInit`, whose `body` is narrower than the
+ * `ReadableStream` a built Request holds.
+ */
+export function attachApiKey(
+  credential: Extract<ResolvedCredential, { kind: 'api_key' }>,
+  request: Request,
+  original: Request,
+): Request | undefined {
+  if (!credential.query) {
+    request.headers.set(credential.header ?? 'x-api-key', credential.value);
+    return undefined;
+  }
+
+  const relocated = new URL(original.url);
+  relocated.searchParams.set(credential.query, credential.value);
+  return new Request(relocated.href, request as unknown as RequestInit);
+}

package/src/connectivity/auth/authorize.ts

@@ -0,0 +1,49 @@
+import type { ProviderRegistry } from '#registry';
+import type { SecretStore } from '#secrets';
+import { attachApiKey } from './api-key/index.ts';
+import { attachBasic } from './basic/index.ts';
+import { attachBearer } from './bearer/index.ts';
+import { credentialResolver } from './resolve.ts';
+
+/**
+ * Attach whatever the manifest's auth method requires to an outbound request.
+ *
+ * Connectors never see a raw credential: they hand core a request and get an
+ * authorised one back. A pure function of the resolved shape, so there is one
+ * place that reads the store (`resolve.ts`) and one that decides what a request
+ * looks like.
+ */
+export function requestAuthorizer(
+  registry: ProviderRegistry,
+  secrets: SecretStore,
+): (providerId: string, connectionId: string, request: Request) => Promise<Request> {
+  const resolve = credentialResolver(registry, secrets);
+
+  return async (providerId, connectionId, request) => {
+    const credential = await resolve(providerId, connectionId);
+    if (credential.kind === 'none') return request;
+
+    const authorised = new Request(request, { headers: new Headers(request.headers) });
+
+    switch (credential.kind) {
+      case 'oauth':
+        authorised.headers.set('authorization', `Bearer ${credential.accessToken}`);
+        break;
+      case 'bearer':
+        attachBearer(credential, authorised);
+        break;
+      case 'basic':
+        attachBasic(credential, authorised);
+        break;
+      case 'api_key': {
+        // The only method that may need to rebuild the request rather than add
+        // a header, because a key in the query string changes the URL.
+        const relocated = attachApiKey(credential, authorised, request);
+        if (relocated) return relocated;
+        break;
+      }
+    }
+
+    return authorised;
+  };
+}

package/src/connectivity/auth/basic/index.ts

@@ -0,0 +1,68 @@
+import { credentialRefForConnection, type ProviderManifest } from '#connectivity';
+import type { ProviderRegistry } from '#registry';
+import type { SecretStore } from '#secrets';
+import type { ResolvedCredential } from '../credential.ts';
+
+/**
+ * RFC 7617 Basic — a username and a password, stored as one string.
+ *
+ * `user:pass`, split on the *first* colon, which is lossless because the spec
+ * forbids a colon in the userid. Storing the pair exactly as the header carries
+ * it means nothing has to agree about a JSON shape.
+ */
+export function resolveBasic(value: string, ref: string, providerId: string): ResolvedCredential {
+  const colon = value.indexOf(':');
+  if (colon === -1) {
+    throw new Error(
+      `The credential at ${ref} is not a "username:password" pair, which basic auth requires. ` +
+        `Re-run: lanes link connect ${providerId}`,
+    );
+  }
+
+  return { kind: 'basic', username: value.slice(0, colon), password: value.slice(colon + 1) };
+}
+
+export function attachBasic(
+  credential: Extract<ResolvedCredential, { kind: 'basic' }>,
+  request: Request,
+): void {
+  // `btoa` is wrong here twice: it throws outright above U+00FF, and below it
+  // silently encodes Latin-1 bytes where RFC 7617 requires UTF-8 — so a
+  // password with an umlaut produced a header that was well-formed, accepted by
+  // the type system, and rejected by the server.
+  request.headers.set(
+    'authorization',
+    `Basic ${Buffer.from(`${credential.username}:${credential.password}`, 'utf8').toString('base64')}`,
+  );
+}
+
+/**
+ * The username and password for a connection, for a protocol that wants them as
+ * a pair rather than as a header.
+ *
+ * IMAP and DAV take this closure as a constructor option. It is bound to one
+ * provider and one connection and takes no arguments, so a connector holding it
+ * cannot name a *different* account's credential — the same boundary
+ * `scopeSecrets` enforces with an allowlist, reached here by having nothing to
+ * pass.
+ */
+export async function basicCredential(
+  manifest: ProviderManifest,
+  connectionId: string,
+  secrets: SecretStore,
+): Promise<{ username: string; password: string }> {
+  const { credentialResolver } = await import('../resolve.ts');
+  const registry = { manifest: () => manifest } as unknown as ProviderRegistry;
+  const resolved = await credentialResolver(registry, secrets)(manifest.id, connectionId);
+
+  if (resolved.kind !== 'basic') {
+    throw new Error(
+      `Provider "${manifest.id}" needs a username and password, but its auth resolves to "${resolved.kind}".`,
+    );
+  }
+
+  return { username: resolved.username, password: resolved.password };
+}
+
+/** Re-exported so the factory can derive a ref without reaching for the manifest module. */
+export { credentialRefForConnection };

package/src/connectivity/auth/bearer/index.ts

@@ -0,0 +1,13 @@
+import type { ResolvedCredential } from '../credential.ts';
+
+/** A long-lived token the operator pasted in, sent as `Bearer <token>`. */
+export function resolveBearer(value: string, header: string | undefined): ResolvedCredential {
+  return { kind: 'bearer', token: value, header: header ?? 'authorization' };
+}
+
+export function attachBearer(
+  credential: Extract<ResolvedCredential, { kind: 'bearer' }>,
+  request: Request,
+): void {
+  request.headers.set(credential.header, `Bearer ${credential.token}`);
+}

package/src/connectivity/auth/credential.ts

@@ -0,0 +1,19 @@
+/**
+ * A credential, resolved but not yet attached to anything.
+ *
+ * The seam between "read the store and work out what this secret is" and "put
+ * it on an outbound request". Two steps rather than one because not every
+ * transport has a request to put it on: IMAP wants a username and password as a
+ * pair, and gets this value directly.
+ */
+export type ResolvedCredential =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'bearer'; readonly token: string; readonly header: string }
+  | { readonly kind: 'basic'; readonly username: string; readonly password: string }
+  | {
+      readonly kind: 'api_key';
+      readonly value: string;
+      readonly header?: string;
+      readonly query?: string;
+    }
+  | { readonly kind: 'oauth'; readonly accessToken: string };

package/src/connectivity/auth/header/index.ts

@@ -0,0 +1,18 @@
+import { resolveApiKey } from '../api-key/index.ts';
+import type { ResolvedCredential } from '../credential.ts';
+
+/**
+ * A raw value in a named header.
+ *
+ * Distinct from `bearer`, which prefixes `Bearer `. Resolves to the same shape
+ * as `api_key` and travels the same attach path, because "put this string in
+ * this header" is one behaviour whichever of the two names a manifest picked —
+ * and `api_key` is the one that also knows how to put it in the query string.
+ *
+ * Its own folder rather than an alias in the dispatcher because the *names* are
+ * what a manifest declares, and a reader asking "what does `kind: header` do"
+ * should find a file rather than a missing case.
+ */
+export function resolveHeader(value: string, header: string | undefined): ResolvedCredential {
+  return resolveApiKey(value, { header });
+}

package/src/connectivity/auth/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Credential types — how we prove who we are to a service.
+ *
+ * One folder per method, each owning both halves of its job: turning the stored
+ * secret into a resolved shape (`resolve*`) and putting that shape on an
+ * outbound request (`attach*`). The two dispatchers here are the only files
+ * that know the whole set.
+ *
+ * This is the axis the manifest's `auth:` block selects, and it is deliberately
+ * independent of `../transports/` — which is why iCloud can speak IMAP with a
+ * password while Gmail speaks HTTP with OAuth, and neither costs the other any
+ * code.
+ */
+
+export { credentialResolver, type ResolvedCredential } from './resolve.ts';
+export { requestAuthorizer } from './authorize.ts';
+export { basicCredential } from './basic/index.ts';
+export {
+  CredentialOAuthProvider,
+  clearUpstreamTokens,
+  upstreamAccessToken,
+  type OAuthProviderOptions,
+} from './oauth-authcode/provider.ts';
+export { resolveUpstreamToken } from './oauth-authcode/index.ts';
+export {
+  BROKER_ORIGIN_ENV,
+  BROKERED,
+  BrokerError,
+  brokerConfig,
+  brokerExchange,
+  brokerOriginOverride,
+  brokerRefresh,
+  type BrokerConfig,
+  type BrokerTokens,
+} from './oauth-authcode/broker.ts';

package/src/connectivity/auth/none/index.ts

@@ -0,0 +1,12 @@
+import type { ResolvedCredential } from '../credential.ts';
+
+/**
+ * No credential at all.
+ *
+ * Not an absence to be handled everywhere — a method like any other, so the
+ * `fs` and `local` transports go down the same path as Gmail and the callers
+ * never branch on "is there auth".
+ */
+export function resolveNone(): ResolvedCredential {
+  return { kind: 'none' };
+}