@lanes-sh/link 0.7.2 → 0.9.0

package/src/cli/accepts.ts

@@ -0,0 +1,109 @@
+import { CONNECT_CUSTOM_FLAGS } from './commands/connect/custom/spec.ts';
+
+/**
+ * The flags each command reads, beyond the universal set and its own selection.
+ *
+ * Split from `selection.ts` so that file stays inside the size budget, and on
+ * the seam it already had: that file answers *what a command must be told*, and
+ * this answers *what it will listen to*. Both are read by `assertKnownFlags`,
+ * and a flag missing from here is refused rather than ignored — which is the
+ * defect the whole arrangement exists to prevent.
+ */
+
+/**
+ * What each command accepts beyond the universal set and its own selection.
+ *
+ * Only commands with flags of their own appear. Anything absent accepts the
+ * universal set plus whatever `SELECTION` says it must be told.
+ */
+export const ACCEPTS: Record<string, readonly string[]> = {
+  // Imported rather than written out. Thirty-odd entries here would take this
+  // file past the size budget for a data literal, and the command's own
+  // `spec.ts` already derives most of them from the per-kind field tables — so
+  // a flag added there cannot be forgotten here.
+  'connect custom': CONNECT_CUSTOM_FLAGS,
+  // `own-client` is the older spelling of one of the routes `auth` names, kept
+  // because it is in scripts and a year of documentation (ADR-038).
+  connect: [
+    'id',
+    'display-name',
+    // Repeatable: `--set host=cloud.example.com`. The only way to give a
+    // provider its address without a terminal to ask at.
+    'set',
+    'label',
+    'replace',
+    'non-interactive',
+    'accept-broad-scopes',
+    'own-client',
+    'auth',
+  ],
+  setup: ['id'],
+  'profile add': ['workspace', 'non-interactive'],
+  // `--delete-data` and `--migrate-to` say what becomes of the bytes the
+  // profile owns (ADR-066). Neither is optional in effect: `--yes` skips
+  // confirmations of things the command was told to do, and this is a question
+  // it has not been asked, so a run with no terminal is refused rather than
+  // guessing.
+  'profile remove': ['dry-run', 'yes', 'workspace', 'delete-data', 'migrate-to'],
+  'profile members': ['me', 'role'],
+  disconnect: ['yes', 'keep-credential'],
+  // The one repair `doctor` can apply rather than only name. Narrow on purpose:
+  // it undoes a provider rename this project shipped, and every other finding
+  // there is something only the operator can decide.
+  doctor: ['fix'],
+  // A filter, not a second subject: it narrows the answer to one connection so
+  // a caller can re-ask about the row it just repaired. Same shape as `attach`.
+  auth: ['connection'],
+  relabel: [],
+  // A rule lands in a grant row, and a row names one connection (ADR-058), so
+  // the flag is required rather than optional. It is listed here as well as
+  // enforced in the command because `assertKnownFlags` refuses anything absent
+  // from this table — the flag existing everywhere except the allowlist is the
+  // exact defect this file was written for.
+  'policy allow': ['connection'],
+  'policy deny': ['connection'],
+  'workspace list': ['urls', 'workspace'],
+  'target list': ['urls', 'workspace'],
+  'workspace show': ['workspace'],
+  'target show': ['workspace'],
+  'mcp install-instructions': ['client'],
+  pair: ['print', 'rotate', 'yes'],
+  'token show': ['show', 'raw'],
+  'token rotate': ['show', 'raw', 'yes'],
+  'audit tail': ['limit', 'denied-only', 'format'],
+  'audit verify': ['limit', 'format'],
+  attach: ['connection'],
+  outputs: ['show'],
+  start: ['port', 'only'],
+  'mcp stdio': ['only'],
+  'mcp add': ['name', 'scope', 'token-env', 'dry-run', 'force', 'no-skill', 'headless'],
+  'mcp skill': ['print', 'force'],
+  'mcp list': ['name', 'scope'],
+  // `--yes` because it installs the app when nothing answers the scheme, and
+  // that is the one prompt in this CLI that puts an application on the machine.
+  dashboard: ['print', 'yes'],
+  desktop: ['print', 'yes'],
+  skill: ['print', 'force'],
+  deploy: ['dry-run', 'iam', 'access', 'service-account', 'tag', 'yes', 'non-interactive'],
+  'secrets push': ['from', 'to', 'overwrite', 'dry-run'],
+  sync: ['dry-run', 'from', 'discover', 'prefer'],
+  'sync targets': ['dry-run', 'from', 'discover', 'prefer'],
+  'sync workspaces': ['dry-run', 'from', 'discover', 'prefer'],
+  update: ['check'],
+  'identity add': ['note'],
+  memory: ['connection', 'title', 'description', 'file', 'tag'],
+  // `--yes` on both, because both have a delete that asks first.
+  tasks: ['connection', 'title', 'status', 'due', 'tag', 'yes'],
+  assets: ['connection', 'name', 'content-type', 'yes'],
+  skills: ['connection', 'title', 'description', 'file'],
+  vault: ['connection'],
+  // `alias`, `attr` and `related` are repeatable — see `ownerFlags`. `name`
+  // overrides the id derived from the positional name, which is how you get
+  // `acme-bv` rather than `acme-b-v`.
+  entities: ['connection', 'type', 'name', 'alias', 'attr', 'related', 'tag', 'yes'],
+  // `no-migrate` is listed beside `migrate` because they are three states
+  // rather than two: neither one asks, and a run with no terminal has to be
+  // able to say which it meant (ADR-041).
+  knowledge: ['repo', 'branch', 'path', 'migrate', 'no-migrate', 'keep', 'allow-public', 'replace', 'yes'],
+};
+

package/src/cli/argv.ts

@@ -50,7 +50,52 @@ export function parseArgv(argv: readonly string[]): Parsed {
     }
   }
 
-  return { command, flags };
+  return { command, flags: normaliseWorkspace(flags) };
+}
+
+/**
+ * `--target` is the old spelling of `--workspace`, accepted for one minor.
+ *
+ * A workspace *is* a target and has been since ADR-052; contract 3 finishes the
+ * rename (ADR-061). The alias exists because the word is in a year of notes and
+ * in the desktop app's hardcoded argument arrays, and cutting it in the same
+ * release would break the app for anyone who updates the CLI first.
+ *
+ * Normalised here rather than in `selection.ts` so exactly one table knows the
+ * new word. A command reading `flags['target']` after this would be reading a
+ * key that is never set, which is the kind of silent miss `assertKnownFlags`
+ * exists to prevent.
+ *
+ * Both spellings is a mistake rather than a preference, so it is refused: they
+ * could name different workspaces, and picking either would be a guess.
+ *
+ * **It says so, on stderr.** A deprecation nobody sees is one nobody acts on,
+ * and the alias has exactly one minor to live. Stderr rather than stdout because
+ * `--json` and `--raw` callers parse the other stream, and a deprecation notice
+ * that broke a script would be a worse way to make the point. `notify` is
+ * injectable so a test can read what was said without capturing a global.
+ */
+export function normaliseWorkspace(
+  flags: Flags,
+  notify: (line: string) => void = (line) => void process.stderr.write(`${line}\n`),
+): Flags {
+  const legacy = flags['target'];
+  if (legacy === undefined) return flags;
+
+  if (flags['workspace'] !== undefined && flags['workspace'] !== legacy) {
+    throw new Error(
+      `--target and --workspace name different things ("${String(legacy)}" and ` +
+        `"${String(flags['workspace'])}"). --target is the old spelling of --workspace; pass one.`,
+    );
+  }
+
+  notify(
+    `warn  --target is now --workspace, and this spelling goes in the next minor. ` +
+      `Read it as: --workspace ${String(legacy)}`,
+  );
+
+  const { target: _legacy, ...rest } = flags;
+  return { ...rest, workspace: legacy };
 }
 
 /**
@@ -91,11 +136,20 @@ export function all(argv: readonly string[], name: string): string[] {
   return values.flatMap((value) => value.split(',').map((part) => part.trim())).filter(Boolean);
 }
 
-/** The flags every command accepts. */
+/**
+ * The flags every command accepts.
+ *
+ * Read from `workspace`, which is what `parseArgv` normalises both spellings
+ * into. The field it lands on is still called `target` and that is deliberate
+ * rather than missed: `#profile` resolves a *target* — an adapter set, a
+ * credential store, a bucket — and renaming the internal identifier is a
+ * separate change from renaming the word an operator types (ADR-061). The
+ * boundary is here, in one function, rather than scattered.
+ */
 export function globalFlags(flags: Flags): GlobalFlags {
   return {
     profile: text(flags, 'profile'),
-    target: text(flags, 'target'),
+    target: text(flags, 'workspace'),
     quiet: flags['quiet'] === true,
   };
 }

package/src/cli/audit-change.ts

@@ -0,0 +1,140 @@
+import { openAudit, openSecrets, openStorage } from '#deployments/target.ts';
+import { openTarget, type Config } from '#profile';
+import { readSession } from '#auth/lanes/session.ts';
+
+/**
+ * Config changes, in the same log as the calls they permit.
+ *
+ * The audit log recorded capability invocations and nothing else, which meant
+ * it could answer "what did this agent try to do" and could not answer "who
+ * changed what it was allowed to do". Those are halves of one investigation. A
+ * member added by hand at 14:02 and the first call that member made at 14:03
+ * are one story, and keeping them in two places means reconstructing the join
+ * by timestamp across two formats — so they go in one chain, in order, and
+ * `audit verify` covers both.
+ *
+ * **The event shape does not change.** A config change is written as an
+ * invocation of a capability that only the CLI can invoke, which is true rather
+ * than a convenient fiction: `config.member.add` is a thing that was done, by
+ * someone, to something, with arguments worth keeping. Adding a second record
+ * type would fork every reader, the chain encoding, and `tail`'s filters, to
+ * express something the existing five fields already carry.
+ *
+ * **`provider: 'config'` is not a provider**, and `config.test.ts` asserts no
+ * manifest may claim that id — the guarantee is a test rather than a comment,
+ * because the day someone writes `providers.d/config.yaml` the two kinds of row
+ * become indistinguishable in a log whose value is that they are not.
+ *
+ * **None of this is reachable over MCP.** These capabilities are not in the
+ * registry, no profile can grant them, and `control-plane.test.ts` is the
+ * standing check that config never becomes a surface an agent can call. Writing
+ * a row about a change is not the same as offering to make one.
+ *
+ * **Failing to log never fails the command.** The change is already on disk by
+ * the time this is called; throwing here would report failure for something
+ * that succeeded, and leave the operator to guess which half happened. It warns
+ * and returns.
+ */
+
+/**
+ * The vocabulary, in one place so it cannot drift command by command.
+ *
+ * `<area>.<verb>`, with the area named for the thing that changed rather than
+ * for the command that changed it — `lanes link connect` and a hand-edited
+ * `connections.yaml` are the same event, and a log that called them different
+ * things would be reporting the route rather than the change.
+ */
+export const CONFIG_CAPABILITIES = [
+  'config.connection.create',
+  'config.connection.remove',
+  'config.connection.relabel',
+  'config.profile.add',
+  'config.profile.remove',
+  'config.member.add',
+  'config.member.remove',
+  'config.policy.allow',
+  'config.policy.deny',
+  'config.pair.mint',
+  'config.pair.rotate',
+] as const;
+
+export type ConfigCapability = (typeof CONFIG_CAPABILITIES)[number];
+
+/** The pseudo-provider every config row carries. Reserved by `config.test.ts`. */
+export const CONFIG_PROVIDER = 'config';
+
+export interface ConfigChange {
+  readonly capability: ConfigCapability;
+  /**
+   * The scope of the change: the profile it altered, or the workspace where it
+   * altered something the whole workspace shares.
+   *
+   * A connection belongs to the workspace now (ADR-057), so `connect` has no
+   * profile to name and naming one would be a guess. The workspace's own name
+   * goes here instead — informative, and never mistakable for a profile,
+   * because a reader who filters by a profile they have gets rows about it and
+   * a reader who does not gets the workspace's.
+   */
+  readonly scope: string;
+  /** `<provider>.<id>`, where the change was about one connection. */
+  readonly connection?: string | undefined;
+  /**
+   * What changed, and it is the operator's own config rather than anybody's
+   * content — so unlike a provider's arguments there is nothing here to redact.
+   * Names, ids, subjects and capability patterns are the whole point of the
+   * record. Do not put a credential in it.
+   */
+  readonly arguments?: Readonly<Record<string, unknown>> | undefined;
+}
+
+export async function recordConfigChange(
+  config: Config,
+  root: string,
+  target: string,
+  change: ConfigChange,
+  warn?: (message: string) => void,
+): Promise<void> {
+  try {
+    const resolved = await openTarget(root, target);
+    const input = { declared: resolved.declared, config, root: resolved.workspaceRoot, target };
+    const audit = openAudit(await openStorage(input, await openSecrets(input)));
+
+    try {
+      await audit.append({
+        profile: change.scope,
+        principal: await principal(),
+        provider: CONFIG_PROVIDER,
+        ...(change.connection ? { connection: change.connection } : {}),
+        capability: change.capability,
+        arguments: change.arguments ?? {},
+        // Every one of these is written after the change is on disk, so there
+        // is no denied case to record and no duration worth measuring: the
+        // number would be how long a file write took, which answers nothing.
+        authorization: 'allowed',
+        status: 'ok',
+        durationMs: 0,
+      });
+    } finally {
+      await audit.close();
+    }
+  } catch (error) {
+    warn?.(`the change was made but not recorded in the audit log: ${message(error)}`);
+  }
+}
+
+/**
+ * Who made the change.
+ *
+ * The signed-in Lanes subject, which since ADR-060 is a real person rather than
+ * whoever held a token. `cli:unsigned` is the honest answer where there is no
+ * session — some commands do not require one, and attributing their changes to
+ * the last person who signed in on this machine would be worse than saying so.
+ */
+async function principal(): Promise<string> {
+  const session = await readSession().catch(() => null);
+  return session?.subject ?? 'cli:unsigned';
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/cli/callback-page.ts

@@ -69,100 +69,44 @@ const ICON =
   'stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
   '<path d="M20 6 9 17l-5-5"/></svg>';
 
-export interface ApprovalPage {
-  /** What is asking. A client's self-reported name, or a stand-in. */
-  readonly client: string;
-  /** Where the code would be sent. The part of the request that cannot be faked. */
-  readonly redirectHost: string;
-  /**
-   * The same destination as a CSP source, so the browser will follow the
-   * redirect this form's approval ends in rather than blocking it.
-   */
-  readonly formAction?: string;
-  /** Hidden fields carrying the authorization request through the POST. */
-  readonly fields: Readonly<Record<string, string>>;
-  readonly action: string;
-  /** A previous attempt presented the wrong token. */
-  readonly retry: boolean;
-  /** The target this endpoint runs as, so the hint below names the right store. */
-  readonly target: string;
-}
-
 /**
- * The one screen a remote client's authorization stops at.
+ * Something went wrong, said to the person it went wrong for.
  *
- * Same card as the page above, because it is the same product and the reader
- * arrived here from a connector rather than from a terminal. What it asks for is
- * the endpoint token — the string `lanes link outputs` prints — because that is
- * already the proof of being the owner and inventing a second one would mean
- * inventing a password to go with it.
+ * This replaces the consent form (ADR-062), and the two are worth contrasting.
+ * The form asked a browser on loopback for the endpoint token — the one
+ * credential that opened everything — which made it the most valuable thing a
+ * hostile local page could reach. Identity now comes from lanes.sh, so the only
+ * page this endpoint renders is one that *tells* rather than asks.
  *
- * The hint names the target rather than leaving it out. Credentials are
- * per-target, and the reader runs that command in a shell resolving a target of
- * its own — `local` by default, which is the one store a deployed endpoint's
- * token is never in. Omitting it sends them to fetch the wrong secret, and
- * `outputs` mints a fresh one when that store is empty rather than saying so.
- *
- * `autocomplete="off"` and `type="password"` are not theatre: this form is
- * submitted in whatever browser the phone opened, and a token remembered by a
- * shared browser is a token in the hands of whoever borrows the phone.
+ * Rendered as a page rather than returned as text because of who reads it. The
+ * important message here is "you signed in, and no profile on this endpoint
+ * lists you" — which arrives at a browser, at the end of a sign-in, addressed
+ * to somebody who needs to know what to ask their operator for.
  */
-export function approvalPage(page: ApprovalPage): Response {
-  const hidden = Object.entries(page.fields)
-    .map(([name, value]) => `<input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`)
-    .join('\n');
-
-  // The name is self-reported and the host is not, so the host is what the
-  // reader is asked to recognise. Registration is open by design, which means
-  // anything can call itself anything — but an impostor still has to nominate
-  // somewhere for the code to go, and that is on the screen.
-  const body = `
-${page.retry ? '<p class="label err-text">That token was not accepted.</p>\n' : ''}<h1>Authorise ${escapeHtml(page.client)}?</h1>
-<p class="detail">It will be sent back to <strong>${escapeHtml(page.redirectHost)}</strong>, and will be able to reach every profile this endpoint serves, within the policy each one declares.</p>
-<form method="post" action="${escapeHtml(page.action)}">
-${hidden}
-<input class="field" type="password" name="token" placeholder="Endpoint token" autocomplete="off" autofocus required>
-<button class="go" type="submit">Approve</button>
-</form>
-<p class="small"><code>lanes link outputs --show --target ${escapeHtml(page.target)}</code></p>`;
+export function noticePage(message: string, status: number): Response {
+  // Deliberately whole-text-escaped and then split on blank lines: these
+  // messages carry a subject and sometimes a command, and neither is markup.
+  const body =
+    `<h1>Not authorised</h1>` +
+    message
+      .split('\n\n')
+      .map((paragraph) => `<p class="detail">${escapeHtml(paragraph)}</p>`)
+      .join('\n');
 
-  return shell(body, 'Authorise', page.retry ? 401 : 200, '', {
-    script: SUBMIT_SPINNER,
-    ...(page.formAction ? { formAction: [page.formAction] } : {}),
-  });
+  return shell(body, 'Not authorised', status, ' err');
 }
 
 /**
- * What runs while the approval is in flight.
- *
- * Approving is a round trip to an authorization server, and until it returns the
- * page looks exactly as it did before the click — so the honest reading is that
- * nothing happened, and the second click is the one that produces a duplicated
- * request. The button disables itself, which is the part that matters; the
- * spinner is what says why.
+ * One document, both pages.
  *
- * The cost is real and worth naming: this is the one page that asks for the
- * endpoint token, and an inline listener means its policy admits inline script.
- * It is the minimum that does the job — one listener, no interpolation, nothing
- * read from the page — and the alternative, a static file, is an asset pipeline
- * this repository does not have.
+ * No script hook any more, and no `form-action` parameter. Both existed for the
+ * consent form: it ran an inline listener to disable its own button, and it had
+ * to name in its policy the client origin its approval redirected to. Identity
+ * moved to lanes.sh (ADR-062) and the form went with it, so the policy narrows
+ * back to what it was before — which is the rare direction for a CSP to move
+ * and worth saying out loud.
  */
-const SUBMIT_SPINNER = `
-document.querySelector('form').addEventListener('submit', function (event) {
-  var button = event.currentTarget.querySelector('.go');
-  button.classList.add('busy');
-  button.disabled = true;
-});
-`.trim();
-
-function shell(
-  inner: string,
-  title: string,
-  status: number,
-  cardClass = '',
-  policy: { readonly script?: string; readonly formAction?: readonly string[] } = {},
-): Response {
-  const script = policy.script ?? '';
+function shell(inner: string, title: string, status: number, cardClass = ''): Response {
   return new Response(
     `<!doctype html>
 <html lang="en">
@@ -184,48 +128,25 @@ ${inner}
 </div>
 ${FOOTER}
 </div>
-${script ? `<script>\n${script}\n</script>` : ''}
 </body>
 </html>`,
     {
       status,
-      headers: {
-        ...PAGE_HEADERS,
-        'content-security-policy': pageCsp({
-          ...(script ? { script: true } : {}),
-          ...(policy.formAction ? { formAction: policy.formAction } : {}),
-        }),
-      },
+      headers: { ...PAGE_HEADERS, 'content-security-policy': pageCsp({}) },
     },
   );
 }
 
+/**
+ * What is left of the form styles.
+ *
+ * `.small` alone: the consent form's field, button and spinner went with the
+ * form (ADR-062). Kept as its own constant rather than folded into `STYLE`
+ * because the completion page still uses it for the line under the card.
+ */
 const FORM_STYLE = `
-.field { width: 100%; margin: 20px 0 12px; padding: 11px 13px; font: inherit; font-size: 15px;
-         color: inherit; background: var(--background); border: 1px solid var(--border);
-         border-radius: 6px; }
-.field:focus { outline: none; border-color: var(--accent-gold); }
-.go { width: 100%; padding: 11px 13px; font: inherit; font-size: 15px; font-weight: 500;
-      color: var(--foreground); background: transparent; border: 1px solid var(--border);
-      border-radius: 6px; cursor: pointer; }
-.go:hover { background: var(--muted); }
 .small { margin-top: 16px; font-size: 12px; color: var(--muted-foreground); opacity: 0.8; }
 .small code { font-size: 12px; }
-.err-text { color: var(--destructive); }
-
-/* The button, mid-flight. The label goes transparent rather than away, so the
-   button keeps the width it had and the card does not reflow under the cursor. */
-.go.busy { color: transparent; position: relative; pointer-events: none; }
-.go.busy::after { content: ''; position: absolute; inset: 0; margin: auto;
-                  width: 15px; height: 15px; border-radius: 50%;
-                  border: 2px solid var(--border); border-top-color: var(--foreground);
-                  animation: spin 0.6s linear infinite; }
-@keyframes spin { to { transform: rotate(360deg); } }
-/* Monochrome deliberately: gold says a thing turned out well, and a request in
-   flight has not turned out yet. */
-@media (prefers-reduced-motion: reduce) {
-  .go.busy::after { animation-duration: 2.4s; }
-}
 `.trim();
 
 export function completionPage(page: CallbackPage): Response {

package/src/cli/commands/auth-dispatch.ts

@@ -0,0 +1,48 @@
+import { parseArgv } from '../argv.ts';
+import { authLogin, authLogout, authStatus, authWorkspaces } from './auth.ts';
+
+/**
+ * `lanes auth <command>` — the grammar, and nothing else.
+ *
+ * Its own file for the reason `main.ts` is one: a dispatcher that also does the
+ * work is a file that grows a case at a time until nobody can see the grammar.
+ * Four commands, one line each.
+ */
+
+const USAGE = `lanes auth — who this machine is signed in as
+
+  lanes auth login        sign in, in a browser
+  lanes auth logout       forget this machine's session
+  lanes auth status       who you are, and how long the token lasts
+  lanes auth workspaces   the Lanes workspaces you are a member of
+
+  --json                  the same answer, as a document
+  --api-url <url>         a self-hosted API, instead of the default
+`;
+
+export async function runAuth(argv: readonly string[]): Promise<void> {
+  const { command, flags } = parseArgv(argv);
+  const [first] = command;
+
+  const options = {
+    json: flags['json'] === true,
+    ...(typeof flags['api-url'] === 'string' ? { apiUrl: flags['api-url'] } : {}),
+  };
+
+  switch (first) {
+    case 'login':
+      return authLogin(options);
+    case 'logout':
+      return authLogout(options);
+    case 'status':
+    case undefined:
+      return authStatus(options);
+    case 'workspaces':
+      return authWorkspaces(options);
+    case 'help':
+      console.log(USAGE);
+      return;
+    default:
+      throw new Error(`Unknown: lanes auth ${first}\n\n${USAGE}`);
+  }
+}