@lanes-sh/link 0.7.2 → 0.8.0

package/src/profile/connections.ts

@@ -0,0 +1,183 @@
+import { ConfigError, describeRename } from './load.ts';
+import type { Config, ConnectionConfig, GrantConfig, TargetConfig } from './schema.ts';
+
+/**
+ * The join between a profile and the workspace it lives in.
+ *
+ * A connection is declared once, in `connections.yaml`, and a profile names the
+ * ones it selects in `grants:` (ADR-057). Nothing downstream should perform
+ * that join itself: `dispatch`, `visibility`, `status`, `setup` and the
+ * reconciler all want the same answer — *which accounts does this profile
+ * reach, and what may be done with each* — and three implementations of one
+ * join is three chances for discovery and enforcement to disagree, which is the
+ * failure `allowedConnections` exists to prevent on the capability axis.
+ *
+ * So this file answers it once and everything else asks.
+ */
+
+/** `<provider>.<id>` — the same string an agent passes as `connection`. */
+export function connectionRefOf(connection: ConnectionConfig): string {
+  return `${connection.provider}.${connection.id}`;
+}
+
+/**
+ * One account this profile reaches, with the rules that govern it.
+ *
+ * The grant travels with the connection deliberately. Every caller that has a
+ * connection in its hand is about to ask what may be done with it, and handing
+ * back a pair removes the second lookup — along with the possibility of pairing
+ * a connection with the wrong profile's grant, which is the one mistake this
+ * shape makes unrepresentable.
+ */
+export interface SelectedConnection {
+  readonly ref: string;
+  readonly connection: ConnectionConfig;
+  readonly grant: GrantConfig;
+}
+
+/**
+ * The connections a profile selects, in the order it declares them.
+ *
+ * Declaration order rather than the workspace's, because the profile is what
+ * this is a view of, and a listing that reordered the owner's own file would be
+ * answering a question nobody asked. A grant naming a connection that does not
+ * exist is skipped here and refused by `assertGrantsResolve` at load — this
+ * function is a view, not a gate, and a view that threw would make every
+ * listing depend on the config being valid.
+ */
+export function selectConnections(
+  config: Config,
+  available: readonly ConnectionConfig[],
+): SelectedConnection[] {
+  const byRef = new Map(available.map((connection) => [connectionRefOf(connection), connection]));
+
+  return config.grants.flatMap((grant) => {
+    const connection = byRef.get(grant.connection);
+    return connection === undefined ? [] : [{ ref: grant.connection, connection, grant }];
+  });
+}
+
+/**
+ * Every reference in a profile resolves, and nothing is granted twice.
+ *
+ * Two failures, and the second is the one worth having a check for. A grant
+ * naming a connection the workspace does not hold is visible the moment anyone
+ * looks — the surface is simply absent. Two grants naming the *same* connection
+ * is not: one of them silently wins, and which one depends on iteration order,
+ * so a profile could deny a capability in one row and allow it in another and
+ * behave differently between releases. Refusing at load is what keeps
+ * `grants:` a set rather than a sequence with precedence.
+ */
+export function assertGrantsResolve(
+  config: Config,
+  available: readonly ConnectionConfig[],
+): void {
+  const refs = new Set(available.map(connectionRefOf));
+
+  const missing = config.grants
+    .map((grant) => grant.connection)
+    .filter((ref) => !refs.has(ref));
+
+  if (missing.length > 0) {
+    throw new ConfigError(
+      `Profile "${config.instance.profile}" grants a connection this workspace does not hold: ` +
+        `${[...new Set(missing)].join(', ')}.\n` +
+        `  Connections live in connections.yaml. Run "lanes link connection list" to see them.`,
+    );
+  }
+
+  const seen = new Set<string>();
+  const duplicated = config.grants
+    .map((grant) => grant.connection)
+    .filter((ref) => (seen.has(ref) ? true : (seen.add(ref), false)));
+
+  if (duplicated.length > 0) {
+    throw new ConfigError(
+      `Profile "${config.instance.profile}" grants the same connection more than once: ` +
+        `${[...new Set(duplicated)].join(', ')}.\n` +
+        `  One row per connection — merge the allow and deny lists into it.`,
+    );
+  }
+}
+
+/**
+ * No two connections in a workspace share a reference.
+ *
+ * `<provider>.<id>` is what a credential ref is derived from and what an agent
+ * names, so a duplicate is two accounts answering to one address. It was
+ * impossible to express before contract 3 only because a profile held its own
+ * list; one workspace-wide list makes it expressible, so it has to be refused.
+ */
+export function assertConnectionsUnique(connections: readonly ConnectionConfig[]): void {
+  const seen = new Set<string>();
+  const duplicated = connections
+    .map(connectionRefOf)
+    .filter((ref) => (seen.has(ref) ? true : (seen.add(ref), false)));
+
+  if (duplicated.length > 0) {
+    throw new ConfigError(
+      `connections.yaml declares the same connection more than once: ` +
+        `${[...new Set(duplicated)].join(', ')}.\n` +
+        `  A connection is addressed as "<provider>.<id>", so two rows sharing one ` +
+        `are two accounts at one address.`,
+    );
+  }
+}
+
+/**
+ * The one connection this profile grants for a single-instance provider.
+ *
+ * `undefined` when it grants none, which is a legitimate state: a profile that
+ * denies `skills.*` reaches no skills, and the surface is absent rather than
+ * empty.
+ */
+export function soleGrantFor(config: Config, provider: string): string | undefined {
+  const prefix = `${provider}.`;
+  const granted = config.grants.find((grant) => grant.connection.startsWith(prefix));
+  return granted?.connection.slice(prefix.length);
+}
+
+/**
+ * Where this profile's vault document lives, in one spelling.
+ *
+ * **Two places derived this, and they disagreed.** `openVault` names it per
+ * connection (ADR-059) — `vault/main` for a profile granting `vault.main` — and
+ * the deploy's provisioning step named `vault/document`, the contract-2 constant.
+ * So every deployed workspace that did not hand-write `vault.ref` created and
+ * granted one secret and then asked Secret Manager for another: the revision got
+ * `PERMISSION_DENIED` on the ref nothing had made, exited 1, and never listened
+ * on its port. A deploy that hand-wrote a `ref` worked, which is what kept this
+ * out of sight — a rehearsal that sets one is testing the path nobody takes.
+ *
+ * `ref` still wins where it is written, because a deployment already sealing
+ * under one name has to keep opening it.
+ */
+export function vaultRef(declared: TargetConfig | undefined, config: Config): string {
+  return declared?.vault?.ref ?? `vault/${soleGrantFor(config, 'vault') ?? 'main'}`;
+}
+
+/**
+ * A connection whose provider id moved out from under it.
+ *
+ * `tasks` is the built-in task list; Google's is `google_tasks` (ADR-051). A row
+ * that still says `tasks` and names an address rather than the built-in's own
+ * label is somebody's Google account resolving to the wrong provider — and the
+ * failure is silent in the worst way: the row loads, reconcile calls it active,
+ * and every call goes to an empty local store.
+ *
+ * Here rather than in the profile loader, because the evidence is the *account*
+ * and accounts live in this file.
+ */
+export function assertNoRenamedProviders(
+  connections: readonly ConnectionConfig[],
+  repair: string,
+): void {
+  const problems = connections.flatMap((connection, index) => {
+    const renamed = describeRename(connection, repair);
+    return renamed === null ? [] : [`connections[${index}]: ${renamed}`];
+  });
+
+  if (problems.length > 0) {
+    throw new ConfigError(`connections.yaml:\n${problems.map((p) => `  ${p}`).join('\n')}`, problems);
+  }
+}

package/src/profile/deployments.ts

@@ -78,12 +78,12 @@ async function editRegistry(
     (await readWorkspaceFile(files, WORKSPACE_FILE)) ?? `contract: ${SUPPORTED_CONTRACT}\n`;
 
   const document = parseDocument(text);
-  const targets = (document.toJSON()?.targets ?? {}) as Record<string, WorkspaceTarget>;
+  const targets = (document.toJSON()?.workspaces ?? {}) as Record<string, WorkspaceTarget>;
 
   edit(targets);
 
-  if (Object.keys(targets).length === 0) document.deleteIn(['targets']);
-  else document.setIn(['targets'], sorted(targets));
+  if (Object.keys(targets).length === 0) document.deleteIn(['workspaces']);
+  else document.setIn(['workspaces'], sorted(targets));
 
   // Validated before it lands, on the rendered tree rather than the input, so
   // what is checked is what would be read back.

package/src/profile/index.ts

@@ -1,10 +1,14 @@
 /**
  * A profile: its file, its schema, and where it lives on disk.
  *
- * **One profile = one config = one database = one credential store.** Profiles
- * share an endpoint and its token (ADR-009); they never share state. This
- * component owns everything about what a profile *is* — the YAML contract, the
- * loader that validates it, and the workspace resolution that finds it.
+ * **A profile is a selection, not an inventory.** Since contract 3 the accounts
+ * live in the workspace's `connections.yaml` and a profile names the ones it
+ * grants (ADR-057), so profiles share an endpoint, its token, the credential
+ * store, and any connection they both select. What they do not share is the
+ * grant: two profiles on one mailbox can permit entirely different things
+ * (ADR-058). This component owns everything about what a profile *is* — the
+ * YAML contract, the loader that validates it, the join onto the workspace's
+ * connections, and the resolution that finds them.
  *
  * What it deliberately does not own: which providers exist (`#registry`) and
  * how a call runs (`#dispatch`). Those were all one package called `core`,
@@ -15,21 +19,41 @@ export {
   DEPLOY_DEFAULTS,
   SUPPORTED_CONTRACT,
   configSchema,
+  SINGLE_INSTANCE_PROVIDERS,
+  connectionsFileSchema,
   declaredTarget,
+  grantSchema,
   isPointer,
+  memberSchema,
   workspaceSchema,
   workspaceTargetSchema,
   type AuthorizationConfig,
   type Config,
   type ConnectionConfig,
+  type ConnectionsFile,
   type DeployConfig,
+  type GrantConfig,
   type IdentityEntry,
+  type MemberConfig,
   type PolicyRuleConfig,
   type TargetConfig,
   type WorkspaceConfig,
   type WorkspaceTarget,
 } from './schema.ts';
 
+export {
+  assertConnectionsUnique,
+  assertGrantsResolve,
+  assertNoRenamedProviders,
+  connectionRefOf,
+  selectConnections,
+  soleGrantFor,
+  vaultRef,
+  type SelectedConnection,
+} from './connections.ts';
+
+export { PAIR_CERT_REF, PAIR_KEY_REF, PAIR_TOKEN_REF } from './pairing.ts';
+
 export {
   KNOWLEDGE_LAYOUT,
   knowledgeRoot,
@@ -103,6 +127,8 @@ export {
   writeWorkspaceFile,
 } from './files.ts';
 export {
+  CONNECTIONS_FILE,
+  readConnections,
   type ProfileSelection,
   type Resolution,
   type ResolveOptions,
@@ -111,5 +137,4 @@ export {
 export {
   DATA_DIR,
   layout,
-  profileDir,
 } from './layout.ts';

package/src/profile/layout.ts

@@ -1,123 +1,120 @@
 /**
- * Where a profile's data lives, in one place.
+ * Where a workspace's data lives, in one place.
  *
  * ```
  * ~/.lanes-link/
- * ├── lanes-link.yaml           which profiles exist, which is default
- * ├── profiles/<name>.yaml      each profile's declared config
+ * ├── lanes-link.yaml           the workspaces this machine knows, and the default
+ * ├── connections.yaml          every account authorised in this workspace
+ * ├── profiles/<name>.yaml      which of them a profile selects, and who may use it
  * └── data/
- *     └── <profile>/            everything one profile owns
- *         ├── state.kv/         state, connections, cursors
- *         ├── audit.log/        one object per event
- *         ├── credentials.enc   system credentials, and its .key
- *         ├── vault.enc         the owner's items, its own key
- *         ├── skills.d/         procedures, one <name>/SKILL.md each
- *         ├── providers.d/      the operator's own provider manifests
- *         └── <provider>/<connection>/…   whatever that provider stores
+ *     ├── state.kv/             state, connections, cursors
+ *     ├── audit.log/            one object per event, one chain
+ *     ├── credentials.enc       system credentials, and its .key
+ *     ├── vault.d/<id>.enc      one sealed document per vault connection
+ *     ├── skills.d/<id>/        procedures, one <name>/SKILL.md each
+ *     ├── providers.d/          the operator's own provider manifests
+ *     └── <provider>/<connection>/…   whatever that provider stores
  * ```
  *
- * **One profile, one directory.** Before this, `data/` held
- * `personal.db`, `personal.credentials.enc`, `personal.credentials.enc.key`,
- * `work.db`, and a `personal/` directory, all in one flat listing — three
- * profiles' worth of state interleaved, and no single thing to copy, back up, or
- * delete. Now `rm -r data/work` is exactly "remove the work profile's data" and
- * nothing else.
+ * **Nothing here takes a profile.** It used to take one for everything: a
+ * profile owned a directory, and `rm -r data/work` was the whole answer to
+ * "remove the work profile's data". A connection belongs to the workspace now
+ * (ADR-057) and so do the stores behind the owner layer (ADR-059), so a profile
+ * owns no bytes at all — it owns a selection, and the thing a selection points
+ * at outlives it. `profile remove` prints what survives rather than letting the
+ * difference go unnoticed.
  *
- * **The blob root is the profile directory itself.** It used to be a `files/`
- * subdirectory, which bought nothing and cost a level: a memory entry landed at
- * `data/personal/files/memory/memory/entry/<id>.md`. The provider name and the
- * connection name are the isolation boundary (`scopeBlobStore` namespaces
- * `<provider>/<connection>`) and they are enough on their own, so an entry is
- * now `data/personal/memory/main/<id>.md`. There is no collision risk with the
- * files beside it: a provider id is `[a-z][a-z0-9_]*` and every reserved name
- * here contains a dot.
+ * **The dot is load-bearing, and it is the only thing keeping these apart from
+ * a provider.** The blob root is `data/` and a provider is namespaced
+ * `<provider>/<connection>` under it; a provider id is `[a-z][a-z0-9_]*`, so a
+ * name carrying a dot is one no provider can be scoped into. That is not
+ * hypothetical for three of the five names below — `skills`, `vault` and
+ * `audit` are all real provider ids, and without the dot each would be handed a
+ * store rooted inside the thing it is meant to be walled off from, which is a
+ * hole in ADR-007's wall rather than an untidy filename.
  *
- * **Skills and provider manifests are the profile's too**, which reverses where
- * both used to sit. They were at the workspace root, shared by every profile, on
- * the reasoning that a procedure is not private to a profile the way its
- * knowledge is. That was wrong twice over. A skill is instructions an agent will
- * be handed, and ADR-014 §1 already treats authoring one as a grant worth
- * governing — an odd thing to say about a document every profile reads anyway.
- * And a procedure written for work names work's accounts, its people, and its
- * conventions, so it is exactly as private as the knowledge it operates on.
- * ADR-030 has the argument; ADR-009's "profiles share nothing" is what it
- * restores.
+ * `vault.d/<id>.enc` rather than `vault/<id>.enc` for exactly that reason. The
+ * sealed document is not a blob the vault provider serves, and a `vault/`
+ * prefix shared between the two would put the ciphertext inside the namespace
+ * the provider is given.
  *
- * The `.d` suffix is the dot rule above rather than decoration. A plain
- * `data/<profile>/skills/` is precisely the namespace the skills provider's own
- * blobs scope into, so the one name that could not be used is the obvious one.
- *
- * These are **defaults**. A profile that declares its own paths keeps them.
- *
- * There is no migration from the layout this replaced, deliberately: a
- * workspace is profiles, credentials, and whatever the owner has stored, and
- * re-creating one is `lanes link profile add` plus `lanes link connect` per account. Machinery
- * to move an old one would be more code than the thing it moves, and it would
- * have to keep working forever to be worth having. Skills and manifests left at
- * the old workspace-root paths are the same case: they stop loading, and moving
- * them is one `mv` per profile that should see them.
+ * These are **defaults**. A workspace that declares its own paths keeps them.
  */
 
-/** The directory under the workspace root that holds every profile's data. */
+/** The directory under the workspace root that holds everything the workspace owns. */
 export const DATA_DIR = 'data';
 
 /**
- * Everything one profile owns, relative to the workspace root.
+ * No leading `./` on any of these.
  *
- * No leading `./`. It used to carry one, which `path.resolve` discards and an
- * object key does not: a bucket read `./data/personal/state.kv/x` as a
- * directory literally named `.`, so every deployed key landed one level away
- * from where the config said it did. The visible cost was that the conditioned
- * IAM binding `deployments/gcp/provision.ts` writes — which grants writes under
+ * It used to carry one, which `path.resolve` discards and an object key does
+ * not: a bucket read `./data/state.kv/x` as a directory literally named `.`, so
+ * every deployed key landed one level away from where the config said it did.
+ * The visible cost was that the conditioned IAM binding
+ * `deployments/gcp/provision.ts` writes — which grants writes under
  * `objects/data/` — matched nothing, and the first revision 403'd on its boot
  * reconcile. A relative path is relative without being spelled that way.
  */
-export function profileDir(profile: string): string {
-  return `${DATA_DIR}/${profile}`;
-}
-
 export const layout = {
+  /** Connections, provider state, and cursors: one object per key. */
+  state: (): string => `${DATA_DIR}/state.kv`,
+  /**
+   * System credentials — OAuth refresh tokens, the CI token. Never reachable
+   * from MCP.
+   *
+   * One store for the workspace, where there used to be one per profile. That
+   * is what makes a `credential_ref` unique by construction and retires
+   * `collidingRefs`, the deploy preflight that existed because two profiles
+   * deployed into one project shared this namespace and the collision was
+   * "silent until one profile is reading the other's account" (ADR-043,
+   * ADR-057).
+   */
+  credentials: (): string => `${DATA_DIR}/credentials.enc`,
+  /** Every vault connection's sealed document lives under here. */
+  vaultRoot: (): string => `${DATA_DIR}/vault.d`,
+  /** One sealed document per vault connection, each under its own key. */
+  vault: (connection: string): string => `${DATA_DIR}/vault.d/${connection}.enc`,
   /**
-   * Connections, provider state, and cursors: one object per key.
+   * The same document, keyed relative to the blob store.
    *
-   * The dot is load-bearing, exactly as it is for `audit` below — a provider
-   * is namespaced `<provider>/<connection>` under `blobs`, and a provider id
-   * is `[a-z][a-z0-9_]*`, so a name carrying a dot is one no provider can be
-   * scoped into.
+   * `blobs()` is already rooted at `data/`, so a blob adapter handed the path
+   * above would write `data/data/vault.d/...`. Two spellings of one location is
+   * exactly what this file exists to prevent, so the second one lives here
+   * beside the first rather than being assembled at the call site.
    */
-  state: (profile: string): string => `${profileDir(profile)}/state.kv`,
-  /** System credentials — OAuth tokens, the profile token. Never reachable from MCP. */
-  credentials: (profile: string): string => `${profileDir(profile)}/credentials.enc`,
-  /** The owner's own items, under their own key. */
-  vault: (profile: string): string => `${profileDir(profile)}/vault.enc`,
+  vaultKey: (connection: string): string => `vault.d/${connection}.enc`,
   /**
-   * This profile's skills — `<name>.md` or `<name>/SKILL.md`, either layout.
+   * Every skills connection's procedures live under here.
    *
-   * The dot carries the same weight it does for `state` and `audit`, and here
-   * it is not hypothetical: `skills` is a real provider id, so `skills/` under
-   * the blob root is the prefix its own connection blobs would scope into.
+   * The root is exported beside the per-connection path because `deploy` needs
+   * to recognise the *area* without knowing which connections exist — and
+   * `upload.ts` composes its allowlist back out of these rather than comparing
+   * against literals, so a renamed directory moves the store and the thing that
+   * sends it together, or neither.
    */
-  skills: (profile: string): string => `${profileDir(profile)}/skills.d`,
+  skillsRoot: (): string => `${DATA_DIR}/skills.d`,
+  /** One skills connection's procedures — `<name>.md` or `<name>/SKILL.md`, either layout. */
+  skills: (connection: string): string => `${DATA_DIR}/skills.d/${connection}`,
   /**
-   * The provider manifests this profile declares.
+   * The provider manifests this workspace declares.
    *
-   * Per profile for the same reason a connection is. A manifest names a host,
-   * an OpenAPI document, and the credential refs that reach them — which is a
-   * description of somebody's infrastructure, and work's is not personal's to
-   * read.
+   * Workspace-level, where ADR-030 put them in the profile. A manifest names a
+   * host, an OpenAPI document, and the credential refs that reach them — which
+   * is to say it *defines a connection*, and connections do not live in a
+   * profile any more. ADR-030's argument was about a procedure being as private
+   * as the knowledge it operates on; that argument is answered by ADR-059's
+   * instances, not by where a manifest sits.
    */
-  providers: (profile: string): string => `${profileDir(profile)}/providers.d`,
+  providers: (): string => `${DATA_DIR}/providers.d`,
   /** The blob root every provider is namespaced under. */
-  blobs: (profile: string): string => profileDir(profile),
+  blobs: (): string => DATA_DIR,
   /**
-   * The audit log: one object per event, under the profile's blob root.
+   * The audit log: one object per event, one chain for the workspace.
    *
-   * The dot is doing real work. A provider is namespaced to
-   * `<provider>/<connection>` under `blobs` above, and a provider id is
-   * `[a-z][a-z0-9_]*` — so a name carrying a dot is one no provider can be
-   * scoped to. Without it, a provider called `audit` would be handed a store
-   * rooted inside the log, which is a hole in ADR-007's wall rather than an
-   * untidy filename.
+   * One chain rather than one per profile, because one endpoint serves them all
+   * (ADR-009) and every event already records the profile it acted in. It is
+   * also what lets `audit tail` filter where it used to select, and what gives
+   * the dashboard a single log to read.
    */
-  audit: (profile: string): string => `${profileDir(profile)}/audit.log`,
+  audit: (): string => `${DATA_DIR}/audit.log`,
 } as const;