@lanes-sh/link 0.1.0

package/src/profile/secret-detection.ts

@@ -0,0 +1,162 @@
+/**
+ * Reject credential values that have been written into a config file.
+ *
+ * Config carries `_ref` pointers into the credential store; it never carries a
+ * value. This module is what turns that from an intention into a check, and it
+ * runs on every load and before every CLI write, so a config file cannot become
+ * a place secrets accumulate.
+ *
+ * Findings name the exact path (`oauth_apps.google.client_secret`) because "your
+ * config contains a secret" is not actionable on a file with fifty keys.
+ *
+ * Deliberately biased toward false negatives over false positives. A rule that
+ * rejects a legitimate display name makes the tool unusable, and this is a
+ * second line of defence — `.gitignore` is the first, and the credential store
+ * is what makes the whole class of mistake unnecessary.
+ */
+
+export interface SecretFinding {
+  /** Dotted path, with array indices: `connections[0].credential_ref`. */
+  readonly path: string;
+  readonly rule: string;
+  readonly detail: string;
+}
+
+/** Vendor prefixes that are never anything but a live credential. */
+const CREDENTIAL_PREFIXES: ReadonlyArray<{ prefix: string; label: string }> = [
+  { prefix: 'sk-', label: 'an OpenAI-style secret key' },
+  { prefix: 'xoxb-', label: 'a Slack bot token' },
+  { prefix: 'xoxp-', label: 'a Slack user token' },
+  { prefix: 'xapp-', label: 'a Slack app token' },
+  { prefix: 'ya29.', label: 'a Google OAuth access token' },
+  { prefix: 'ghp_', label: 'a GitHub personal access token' },
+  { prefix: 'gho_', label: 'a GitHub OAuth token' },
+  { prefix: 'github_pat_', label: 'a GitHub fine-grained token' },
+  { prefix: 'AKIA', label: 'an AWS access key id' },
+  { prefix: 'AIza', label: 'a Google API key' },
+  { prefix: 'llk_', label: 'a Lanes Link profile token' },
+  { prefix: '1//', label: 'a Google refresh token' },
+];
+
+const PRIVATE_KEY_BLOCK = /-----BEGIN[ A-Z]*PRIVATE KEY-----/;
+
+/**
+ * Key names that must hold a reference rather than a value.
+ *
+ * A key ending in `_ref` is exempt: `client_secret_ref` is exactly what config
+ * is supposed to contain, while `client_secret` is exactly what it must not.
+ */
+const VALUE_BEARING_KEY = /(?:^|_)(secret|token|password|passwd|apikey|credential)$|_key$/;
+
+/** A single opaque token — no spaces, the shape credentials actually take. */
+const OPAQUE_TOKEN = /^[A-Za-z0-9_\-+/=.]{24,}$/;
+
+export function shannonEntropy(value: string): number {
+  if (value.length === 0) return 0;
+  const counts = new Map<string, number>();
+  for (const char of value) counts.set(char, (counts.get(char) ?? 0) + 1);
+
+  let entropy = 0;
+  for (const count of counts.values()) {
+    const p = count / value.length;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+function characterClasses(value: string): number {
+  let classes = 0;
+  if (/[a-z]/.test(value)) classes++;
+  if (/[A-Z]/.test(value)) classes++;
+  if (/[0-9]/.test(value)) classes++;
+  return classes;
+}
+
+/**
+ * Does this look like a random blob rather than a path, name, or identifier?
+ *
+ * Requiring all three of length, mixed character classes, and high entropy is
+ * what keeps `./data/personal.credentials.enc` (no uppercase, no digits) and
+ * `google/client_secret` (lowercase only) from being flagged, while catching a
+ * base64 or hex credential.
+ */
+function looksHighEntropy(value: string): boolean {
+  return (
+    OPAQUE_TOKEN.test(value) &&
+    characterClasses(value) >= 3 &&
+    shannonEntropy(value) >= 3.5 &&
+    !/^https?:/i.test(value)
+  );
+}
+
+function inspectValue(path: string, key: string, value: string): SecretFinding | null {
+  if (value.length === 0) return null;
+
+  if (PRIVATE_KEY_BLOCK.test(value)) {
+    return { path, rule: 'private-key-block', detail: 'contains an inline private key block' };
+  }
+
+  for (const { prefix, label } of CREDENTIAL_PREFIXES) {
+    if (value.startsWith(prefix)) {
+      return {
+        path,
+        rule: 'credential-prefix',
+        detail: `starts with "${prefix}", which identifies ${label}`,
+      };
+    }
+  }
+
+  // A key that names a credential must carry a reference, not a value —
+  // regardless of how innocuous the value looks.
+  if (!key.endsWith('_ref') && VALUE_BEARING_KEY.test(key)) {
+    return {
+      path,
+      rule: 'value-bearing-key',
+      detail:
+        `"${key}" names a credential, so it must hold a reference rather than a value. ` +
+        `Use "${key}_ref" pointing at the credential store, e.g. "google/${key}".`,
+    };
+  }
+
+  if (looksHighEntropy(value)) {
+    return {
+      path,
+      rule: 'high-entropy',
+      detail: `is a ${value.length}-character high-entropy string, which looks like a credential`,
+    };
+  }
+
+  return null;
+}
+
+/** Walk a parsed config and report every credential-shaped value in it. */
+export function findSecrets(value: unknown, path = '', key = ''): SecretFinding[] {
+  if (typeof value === 'string') {
+    const finding = inspectValue(path, key, value);
+    return finding ? [finding] : [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => findSecrets(item, `${path}[${index}]`, key));
+  }
+
+  if (value !== null && typeof value === 'object') {
+    return Object.entries(value).flatMap(([childKey, childValue]) =>
+      findSecrets(childValue, path ? `${path}.${childKey}` : childKey, childKey),
+    );
+  }
+
+  return [];
+}
+
+export function formatSecretFindings(findings: readonly SecretFinding[]): string {
+  const lines = findings.map((finding) => `  ${finding.path} ${finding.detail}`);
+  return (
+    `Configuration must not contain credential values, only "_ref" pointers into the credential store.\n` +
+    `${findings.length === 1 ? 'This value' : 'These values'} looked like a credential:\n` +
+    `${lines.join('\n')}\n\n` +
+    `Move the value into the credential store and reference it instead. ` +
+    `If this is a false positive, rename the key or shorten the value — ` +
+    `there is deliberately no way to suppress this check.`
+  );
+}

package/src/profile/targets.ts

@@ -0,0 +1,152 @@
+import { ConfigError } from './load.ts';
+import type { Config } from './schema.ts';
+
+/**
+ * Which target a command acts on.
+ *
+ * A target names an adapter set — where credentials are kept and where bytes
+ * go — and choosing one is a different subject from finding the workspace and
+ * the profile, which is why it is a different file. `workspace.ts` reached the
+ * size budget holding both, and the budget's job is to say which of the two
+ * things a file is doing should leave.
+ *
+ * The order is `--target`, then `LANES_LINK_TARGET`, then
+ * `instance.default_target`. `deploy` resolves it differently and deliberately;
+ * see `resolveDeployTarget`.
+ */
+
+/** The variable that names a target for every command in a shell. */
+export const TARGET_ENV = 'LANES_LINK_TARGET';
+
+/**
+ * The target somebody asked for, before the config gets a say.
+ *
+ * Split out because two callers need this precedence and must not disagree
+ * about it: `resolveSelection` records a provisional answer for `announce`
+ * before any config is loaded, and `resolveTarget` settles it afterwards. While
+ * the flag was the only source, both could spell it `targetFlag ?? …` and stay
+ * accidentally correct. With a second source, one of them learning about it and
+ * the other not is a line reading `config-default` beside a target the
+ * environment chose — which is the one line that exists to prevent exactly that.
+ *
+ * Returns no target rather than a default: what an unanswered question falls
+ * back to is `instance.default_target`, and that is the config's to supply.
+ */
+export function askedTarget(
+  targetFlag: string | undefined,
+  env: Record<string, string | undefined>,
+): { target: string | undefined; source: 'flag' | 'environment' | undefined } {
+  if (targetFlag) return { target: targetFlag, source: 'flag' };
+
+  const fromEnv = env[TARGET_ENV];
+  if (fromEnv) return { target: fromEnv, source: 'environment' };
+
+  return { target: undefined, source: undefined };
+}
+
+/**
+ * The refusal for a target that is not in the file, in one spelling.
+ *
+ * It was two — here and in the CLI's `openSecretStoreFor` — which is one more
+ * than a sentence naming the available targets survives: the copies drift the
+ * moment either learns something the other does not. This one knows about
+ * `LANES_LINK_TARGET`, and that is precisely the knowledge a copy would lack —
+ * an exported typo otherwise fails every command in the shell with a message
+ * that reads as a problem with the config file.
+ */
+export function undeclaredTarget(
+  target: string,
+  config: Config,
+  source?: 'flag' | 'environment' | 'config-default',
+): ConfigError {
+  const have = Object.keys(config.targets).join(', ') || 'none';
+  return new ConfigError(
+    `Target "${target}" is not declared in this profile (have: ${have})` +
+      (source === 'environment'
+        ? `\n${TARGET_ENV}=${target} is set in this shell — unset it, or pass --target.`
+        : ''),
+  );
+}
+
+/**
+ * Fill in the target once the profile's config has been loaded.
+ *
+ * Order: `--target`, then `LANES_LINK_TARGET`, then `instance.default_target`.
+ * The middle one is the same bargain `LANES_LINK_PROFILE` already offers — a
+ * shell's worth of commands without retyping a flag, somewhere `env` shows it.
+ *
+ * `allowUndeclared` is for the one command whose job is to create the target it
+ * was given — `deploy`, on a first run. Every other command naming a target that
+ * does not exist has made a typo, and the list of what does exist is the useful
+ * answer; refusing there is what stops `--target clod` opening the default one.
+ */
+export function resolveTarget(
+  config: Config,
+  targetFlag?: string,
+  options: {
+    allowUndeclared?: boolean;
+    env?: Record<string, string | undefined>;
+  } = {},
+): { target: string; source: 'flag' | 'environment' | 'config-default' } {
+  const env = options.env ?? (process.env as Record<string, string | undefined>);
+  const asked = askedTarget(targetFlag, env);
+
+  const target = asked.target ?? config.instance.default_target;
+  const source = asked.source ?? 'config-default';
+
+  if (options.allowUndeclared !== true && !(target in config.targets)) {
+    throw undeclaredTarget(target, config, source);
+  }
+  return { target, source };
+}
+
+/**
+ * The target a deploy means, when nobody said.
+ *
+ * `--target cloud` was required on every deploy, and the reason was an accident:
+ * an absent flag falls back to `instance.default_target`, which is `local` —
+ * a target that by definition is not deployed anywhere. So the one command whose
+ * subject is never ambiguous was the one command that made you say it, and the
+ * default it would otherwise have taken was not merely unhelpful but wrong.
+ *
+ * The rule is what someone would say out loud: deploy the target that has a
+ * deployment. One is the answer; none means the first run, which conventionally
+ * creates `cloud` and is what every example in the docs names; several is a
+ * genuine question, and asking beats rolling a revision to whichever came first
+ * in a YAML mapping.
+ *
+ * `--target` still wins, which is how you deploy the second one.
+ *
+ * **`LANES_LINK_TARGET` is deliberately not read here.** It is the same kind of
+ * answer as `instance.default_target` — a shell-wide "where do my commands
+ * run" — and the paragraph above is why that kind of answer is the wrong one
+ * for this question. It is also the only place where being wrong creates cloud
+ * resources rather than an error: `deploy` is the one caller that passes
+ * `allowUndeclared`, so an exported typo would not be refused, it would be
+ * surveyed, written into the profile, and rolled out as a new service. An
+ * environment variable must not be able to name a Cloud Run service into
+ * existence. Say `--target`; `deploy` is rare enough to afford it.
+ */
+export const CONVENTIONAL_DEPLOY_TARGET = 'cloud';
+
+export function resolveDeployTarget(
+  config: Config,
+  targetFlag?: string,
+): { target: string; source: 'flag' | 'deployable' } {
+  if (targetFlag) return { target: targetFlag, source: 'flag' };
+
+  // `deploy` alone: the legacy `cloudrun:` spelling is normalised into it by the
+  // loader, so exactly one shape reaches here.
+  const deployable = Object.entries(config.targets)
+    .filter(([, declared]) => declared.deploy !== undefined)
+    .map(([name]) => name);
+
+  if (deployable.length > 1) {
+    throw new ConfigError(
+      `This profile declares ${deployable.length} deployable targets (${deployable.join(', ')}). ` +
+        'Name the one you mean with --target.',
+    );
+  }
+
+  return { target: deployable[0] ?? CONVENTIONAL_DEPLOY_TARGET, source: 'deployable' };
+}

package/src/profile/workspace.ts

@@ -0,0 +1,262 @@
+import { existsSync } from 'node:fs';
+import { isRemoteWorkspace, readWorkspaceFile, workspaceFiles } from './files.ts';
+import { parseConfig, type LoadedConfig } from './load.ts';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { parse as parseYaml } from 'yaml';
+import { ConfigError } from './load.ts';
+import { workspaceSchema, type Config, type WorkspaceConfig } from './schema.ts';
+import { askedTarget } from './targets.ts';
+
+/**
+ * Workspace and profile resolution.
+ *
+ * A workspace is a directory holding one or more profiles:
+ *
+ *   lanes-link.yaml      workspace settings: contract, default_profile
+ *   profiles/
+ *     personal.yaml
+ *     work.yaml
+ *   data/               local state per profile, gitignored
+ *
+ * There is deliberately no sticky `lanes link use` that persists a *hidden*
+ * current selection. Persisted context state is the standard way operators run
+ * destructive commands against the wrong target, and the version of it that
+ * bites is the dotfile nothing prints.
+ *
+ * So both ways of not retyping a flag are visible ones.
+ * `export LANES_LINK_PROFILE=work` and `export LANES_LINK_TARGET=cloud` live in
+ * the shell, where `env` shows them; `default_profile` and
+ * `instance.default_target` live in files the operator reads and `check`
+ * validates, written by `lanes link profile default` and `lanes link target
+ * use`. Every command prints which of the four it landed on and where that came
+ * from — see `announce`.
+ */
+
+export const WORKSPACE_FILE = 'lanes-link.yaml';
+
+export interface Resolution {
+  readonly workspaceRoot: string;
+  readonly profile: string;
+  readonly profilePath: string;
+  readonly target: string;
+  /** Where the value came from, so every command can print how it got here. */
+  readonly profileSource: 'flag' | 'environment' | 'workspace-default';
+  /**
+   * `deployable` is `deploy` choosing the only target it could have meant.
+   *
+   * It is its own source rather than reusing `config-default` because it is a
+   * different claim: the config default is what *commands* run against, and for
+   * every other command that is the local target. Printing "config-default"
+   * beside a target the config does not default to would be a lie on the one
+   * line that exists to say how the command got here.
+   *
+   * `environment` is `LANES_LINK_TARGET`, and it earns its own name for the
+   * same reason: a target chosen by a variable exported in another terminal an
+   * hour ago is the one an operator is most likely to be surprised by, and the
+   * fix — `unset` — is not the fix for a config default. `deploy` never
+   * produces it; `resolveDeployTarget` says why.
+   */
+  readonly targetSource: 'flag' | 'environment' | 'config-default' | 'deployable';
+}
+
+export interface ResolveOptions {
+  readonly profileFlag?: string | undefined;
+  readonly targetFlag?: string | undefined;
+  readonly cwd?: string;
+  readonly env?: Record<string, string | undefined>;
+}
+
+/**
+ * `LANES_LINK_HOME`, else the nearest ancestor containing `lanes-link.yaml`,
+ * else `~/.lanes-link`.
+ */
+export function resolveWorkspaceRoot(options: ResolveOptions = {}): string {
+  const env = options.env ?? (process.env as Record<string, string | undefined>);
+  const explicit = env['LANES_LINK_HOME'];
+  // A bucket URL is already absolute; `resolve` would turn `gs://b/p` into a
+  // path under the current directory and the failure would arrive much later,
+  // as a missing file rather than as a mangled root.
+  if (explicit) return isRemoteWorkspace(explicit) ? explicit.replace(/\/$/, '') : resolve(explicit);
+
+  let directory = resolve(options.cwd ?? process.cwd());
+  for (;;) {
+    // `existsSync`, not `Bun.file(path).size`: a missing file reports size 0,
+    // so a `>= 0` check would call every candidate a workspace and stop at the
+    // first directory it looked at.
+    if (existsSync(join(directory, WORKSPACE_FILE))) return directory;
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+
+  return join(homedir(), '.lanes-link');
+}
+
+/**
+ * Where Lanes Link itself is installed — the directory holding `package.json`,
+ * and with it `skills/` and `docs/`.
+ *
+ * Not the workspace: this is the code, not the operator's data. Found by
+ * walking up rather than by counting `..` segments, because the count is a
+ * function of where the calling file sits and a file that moves one level takes
+ * a silently wrong path with it. Both callers had already been through that
+ * once.
+ */
+export function installRoot(from: string): string {
+  let directory = resolve(from);
+  for (;;) {
+    if (existsSync(join(directory, 'package.json'))) return directory;
+    const parent = dirname(directory);
+    if (parent === directory) {
+      throw new Error(`No package.json in any directory above ${from}`);
+    }
+    directory = parent;
+  }
+}
+
+/**
+ * Where a profile's config lives, for display and for filesystem callers.
+ *
+ * `join` would collapse the `//` in a bucket URL, so a remote root composes by
+ * hand. Loading goes through `loadProfileConfig` rather than this — what a
+ * command prints and what it reads stopped being the same string when the
+ * workspace stopped being a directory.
+ */
+export function profilePath(workspaceRoot: string, profile: string): string {
+  const key = `profiles/${profile}.yaml`;
+  return isRemoteWorkspace(workspaceRoot) ? `${workspaceRoot}/${key}` : join(workspaceRoot, key);
+}
+
+/** A profile's config, however this workspace is stored. */
+export async function loadProfileConfig(
+  workspaceRoot: string,
+  profile: string,
+): Promise<LoadedConfig> {
+  const key = `profiles/${profile}.yaml`;
+  const text = await readWorkspaceFile(workspaceFiles(workspaceRoot), key);
+  const shown = profilePath(workspaceRoot, profile);
+
+  if (text === null) throw new ConfigError(`${shown}: no such config file`);
+  return parseConfig(text, shown);
+}
+
+export async function readWorkspace(workspaceRoot: string): Promise<WorkspaceConfig | null> {
+  const path = join(workspaceRoot, WORKSPACE_FILE);
+  const text = await readWorkspaceFile(workspaceFiles(workspaceRoot), WORKSPACE_FILE);
+  if (text === null) return null;
+
+  const parsed = workspaceSchema.safeParse(parseYaml(text));
+  if (!parsed.success) {
+    throw new ConfigError(
+      `${path}:\n${parsed.error.issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n')}`,
+    );
+  }
+  return parsed.data;
+}
+
+export async function listProfiles(workspaceRoot: string): Promise<string[]> {
+  try {
+    const entries = await workspaceFiles(workspaceRoot).list('profiles/');
+    return entries
+      .map((entry) => entry.key.slice('profiles/'.length))
+      .filter((name) => name.endsWith('.yaml') && !name.endsWith('.example.yaml'))
+      // Direct children only: a nested directory under `profiles/` is not a
+      // profile, and a bucket listing is flat so it would otherwise look like one.
+      .filter((name) => !name.includes('/'))
+      .map((name) => name.slice(0, -'.yaml'.length))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve which profile and target a command acts on.
+ *
+ * Order: `--profile`, then `LANES_LINK_PROFILE`, then the workspace's
+ * `default_profile`, then an error that lists what is available — never a
+ * silent pick, because the wrong guess here operates on the wrong accounts.
+ */
+export async function resolveSelection(options: ResolveOptions = {}): Promise<Resolution> {
+  const env = options.env ?? (process.env as Record<string, string | undefined>);
+  const workspaceRoot = resolveWorkspaceRoot(options);
+
+  let profile: string | undefined;
+  let profileSource: Resolution['profileSource'] = 'workspace-default';
+
+  if (options.profileFlag) {
+    profile = options.profileFlag;
+    profileSource = 'flag';
+  } else if (env['LANES_LINK_PROFILE']) {
+    profile = env['LANES_LINK_PROFILE'];
+    profileSource = 'environment';
+  } else {
+    profile = (await readWorkspace(workspaceRoot))?.default_profile;
+    profileSource = 'workspace-default';
+  }
+
+  if (!profile) {
+    const available = await listProfiles(workspaceRoot);
+    throw new ConfigError(
+      `No profile selected in workspace ${workspaceRoot}.\n` +
+        (available.length > 0
+          ? `Available: ${available.join(', ')}\n` +
+            `Pass --profile <name>, set LANES_LINK_PROFILE, or set default_profile in ${WORKSPACE_FILE}.`
+          : `No profiles exist yet. Create one with: lanes link profile add <name> --default`),
+    );
+  }
+
+  // Provisional: the config has not been read yet, so `instance.default_target`
+  // is not available to fall back to. `resolveTarget` settles it, from the same
+  // helper, so the two cannot disagree about what beats what.
+  const asked = askedTarget(options.targetFlag, env);
+
+  const path = profilePath(workspaceRoot, profile);
+  if (!(await workspaceFiles(workspaceRoot).has(`profiles/${profile}.yaml`))) {
+    const available = await listProfiles(workspaceRoot);
+    throw new ConfigError(
+      `Profile "${profile}" does not exist (looked for ${path}).\n` +
+        (available.length > 0 ? `Available: ${available.join(', ')}` : 'No profiles exist yet.'),
+    );
+  }
+
+  return {
+    workspaceRoot,
+    profile,
+    profilePath: path,
+    target: asked.target ?? '',
+    profileSource,
+    targetSource: asked.source ?? 'config-default',
+  };
+}
+
+/**
+ * Resolve a target-relative path against the workspace root.
+ *
+ * Only meaningful for the adapters that take a filesystem path — `file`
+ * credentials, the `filesystem` blob store. A workspace in a bucket selects
+ * none of those, so reaching here with a remote root means a target declared a
+ * local adapter against a remote workspace, and saying so beats handing a
+ * `gs://…/data/x` string to `Bun.file`.
+ */
+export function workspacePath(workspaceRoot: string, path: string): string {
+  if (isRemoteWorkspace(workspaceRoot)) {
+    throw new ConfigError(
+      `This target wants a filesystem path ("${path}"), but the workspace is ${workspaceRoot}. ` +
+        'A workspace in a bucket can only use adapters that address it as one: ' +
+        'credentials `gcp-secret-manager`, storage `gcs` or `s3`, vault `secret` or `blob`.',
+    );
+  }
+  return isAbsolute(path) ? path : resolve(workspaceRoot, path);
+}
+
+/**
+ * The line every command prints before acting, read-only commands included.
+ *
+ * This is the primary guard against operating on the wrong instance, and it
+ * costs one line.
+ */
+export function describeSelection(resolution: Resolution): string {
+  return `profile: ${resolution.profile} (${resolution.profileSource})   target: ${resolution.target} (${resolution.targetSource})`;
+}

package/src/providers/custom/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Custom providers — the ones an operator writes.
+ *
+ * A YAML manifest in `~/.lanes-link/data/<profile>/providers.d/`, validated by
+ * exactly the schema the built-ins are validated by, registered into exactly
+ * the same registry. A service nobody has integrated is a file, not a pull
+ * request someone waits on.
+ *
+ * That equivalence is the scalability claim of the manifest design, and it is
+ * only worth anything if it is literally true — so nothing here is a reduced
+ * form of a built-in. `template.ts` scaffolds one starting point per
+ * connectivity type; `load.ts` reads and validates them.
+ */
+
+export {
+  loadProfileProviders,
+  parseManifest,
+  parseManifestFile,
+  type LoadedManifest,
+} from './load.ts';
+export { manifestTemplate } from './template.ts';