@lanes-sh/link 0.1.0

package/src/policy/index.ts

@@ -0,0 +1,179 @@
+/**
+ * Policy evaluation.
+ *
+ * This is the product. `gmail.search = allow` and `gmail.send = deny` are
+ * decisions the runtime enforces, not instructions a model is asked to respect.
+ * Everything else in this codebase exists to make this module's answer binding.
+ *
+ * Two invariants, both tested:
+ *
+ *   1. DEFAULT DENY. Nothing is reachable unless a rule grants it. An empty
+ *      policy grants nothing at all.
+ *   2. TIGHTEN ONLY. Composition can narrow, never widen. A profile rule can
+ *      deny what the instance floor allowed; it can never allow what the floor
+ *      withheld. The floor is empty in M1 — the invariant is implemented
+ *      anyway, because it is what makes delegated access safe to add later,
+ *      and retrofitting it once rules exist in the wild is not possible.
+ */
+
+export type { AuthorizationResult } from '#audit';
+import type { AuthorizationResult } from '#audit';
+
+export type { LimitConfig } from './limits.ts';
+export { RateLimiter, DEFAULT_LIMITS } from './limits.ts';
+
+/**
+ * `approval_required` is RESERVED. The model carries the state so that
+ * configuration written today stays loadable, but there is no approval engine
+ * and a rule carrying it is treated as `deny` until one exists — failing
+ * closed rather than silently permitting.
+ */
+export type Effect = 'allow' | 'deny' | 'approval_required';
+
+export interface PolicyRule {
+  /** `*`, `gmail.*`, or `gmail.search`. Those three forms, and no others. */
+  readonly capability: string;
+  readonly effect: Effect;
+  readonly expiresAt?: Date;
+}
+
+export interface PolicyDocument {
+  readonly rules: readonly PolicyRule[];
+}
+
+export const EMPTY_POLICY: PolicyDocument = { rules: [] };
+
+export interface PolicyRequest {
+  /**
+   * The authenticated principal. One per profile in M1 (the owner). Carried
+   * explicitly so that adding delegated principals later is new rows rather
+   * than a new signature on the dispatch path.
+   */
+  readonly principal: string;
+  /** Fully qualified, e.g. `gmail.search`. */
+  readonly capability: string;
+  /**
+   * Fully qualified, e.g. `gmail.main`.
+   *
+   * Carried for audit, not for the decision: rules name capabilities only, so
+   * every account of a provider within a profile is governed identically.
+   * Granularity between accounts comes from a second profile, which shares no
+   * database, credential store, or URL with the first.
+   */
+  readonly connection: string;
+  /** Defaults to now; injectable so expiry is testable without clock games. */
+  readonly at?: Date;
+}
+
+export interface PolicyDecision {
+  readonly allowed: boolean;
+  readonly reason: AuthorizationResult;
+  readonly matched?: PolicyRule;
+}
+
+/** `*` matches everything, `gmail.*` matches one provider, otherwise literal. */
+export function capabilityMatches(pattern: string, capability: string): boolean {
+  if (pattern === '*') return true;
+  if (pattern === capability) return true;
+  if (!pattern.endsWith('.*')) return false;
+  const prefix = pattern.slice(0, -1); // keep the dot: `gmail.*` -> `gmail.`
+  return capability.startsWith(prefix);
+}
+
+export function isRuleActive(rule: PolicyRule, at: Date): boolean {
+  return rule.expiresAt === undefined || rule.expiresAt > at;
+}
+
+function findMatch(
+  document: PolicyDocument,
+  request: PolicyRequest,
+  at: Date,
+  effects: readonly Effect[],
+): PolicyRule | undefined {
+  return document.rules.find(
+    (rule) =>
+      effects.includes(rule.effect) &&
+      isRuleActive(rule, at) &&
+      capabilityMatches(rule.capability, request.capability),
+  );
+}
+
+/**
+ * Evaluate one profile document. Deny wins over allow regardless of order, so
+ * rule ordering in a config file cannot change the answer — a denial is never
+ * something you can accidentally out-rank by putting an allow above it.
+ */
+export function evaluateDocument(
+  document: PolicyDocument,
+  request: PolicyRequest,
+): PolicyDecision {
+  const at = request.at ?? new Date();
+
+  const denial = findMatch(document, request, at, ['deny', 'approval_required']);
+  if (denial) {
+    return { allowed: false, reason: 'denied_by_policy', matched: denial };
+  }
+
+  const allowance = findMatch(document, request, at, ['allow']);
+  if (allowance) {
+    return { allowed: true, reason: 'allowed', matched: allowance };
+  }
+
+  return { allowed: false, reason: 'denied_default' };
+}
+
+/**
+ * Compose an optional instance floor with the profile's policy.
+ *
+ * Monotonically tightening: the floor is evaluated first and its denial is
+ * final. The profile document is only ever consulted to narrow further, so
+ * there is no arrangement of profile rules that can widen past the floor.
+ */
+export function evaluate(
+  request: PolicyRequest,
+  profile: PolicyDocument,
+  floor?: PolicyDocument,
+): PolicyDecision {
+  if (floor) {
+    const floorDecision = evaluateDocument(floor, request);
+    if (!floorDecision.allowed) return floorDecision;
+  }
+  return evaluateDocument(profile, request);
+}
+
+/**
+ * The connections a principal may use for a given capability.
+ *
+ * This is what populates the `connection` argument enum, so a client cannot
+ * even discover a connection it has no grant for. Discovery filtering and
+ * invocation enforcement therefore share one implementation — if they were
+ * separate, they could disagree, and a leak in discovery is still a leak.
+ */
+export function allowedConnections(
+  capability: string,
+  connections: readonly string[],
+  principal: string,
+  profile: PolicyDocument,
+  floor?: PolicyDocument,
+  at?: Date,
+): string[] {
+  // Only this capability's own provider. `gmail.search` must never offer a
+  // Notion account, and that constraint is structural rather than a policy
+  // decision — it used to fall out of rules naming a connection, so dropping
+  // that had to put it back explicitly.
+  const provider = capability.slice(0, capability.indexOf('.'));
+  const ofProvider = connections.filter((connection) => connection.startsWith(`${provider}.`));
+
+  // All or nothing beyond that, since rules do not discriminate between
+  // accounts. The list shape is kept because it is what the `connection` enum
+  // wants, and because a future principal-scoped rule would restore the
+  // filtering without touching any caller.
+  const first = ofProvider[0];
+  if (first === undefined) return [];
+
+  const request: PolicyRequest = at
+    ? { principal, capability, connection: first, at }
+    : { principal, capability, connection: first };
+
+  return evaluate(request, profile, floor).allowed ? ofProvider : [];
+}

package/src/policy/limits.ts

@@ -0,0 +1,77 @@
+/**
+ * Rate limits.
+ *
+ * These blunt a runaway agent retry loop and protect a vendor's quota. They are
+ * NOT a security boundary, and the guarantee table says so: an authorised caller
+ * that stays under the limit is not constrained by this module in any way.
+ *
+ * Limits are per instance. On Cloud Run, which scales horizontally, they are
+ * therefore not global — a shared counter store would be needed for that and is
+ * deliberately out of scope. Documented rather than silently misleading.
+ */
+
+export interface LimitConfig {
+  /** Per profile — the endpoint as a whole. */
+  readonly requestsPerMinute: number;
+  /** Per connection — protects the upstream vendor's quota. */
+  readonly upstreamCallsPerMinute: number;
+}
+
+export const DEFAULT_LIMITS: LimitConfig = {
+  requestsPerMinute: 120,
+  upstreamCallsPerMinute: 60,
+};
+
+interface Bucket {
+  tokens: number;
+  lastRefill: number;
+}
+
+/**
+ * Token bucket, refilled continuously rather than on a fixed window boundary.
+ *
+ * A fixed window lets a caller spend the whole budget in the last instant of
+ * one window and again in the first instant of the next, delivering double the
+ * intended rate exactly when a retry storm is worst.
+ */
+export class RateLimiter {
+  readonly #buckets = new Map<string, Bucket>();
+  readonly #now: () => number;
+
+  constructor(now: () => number = Date.now) {
+    this.#now = now;
+  }
+
+  /**
+   * Consume one token. Returns whether the call may proceed, and when the
+   * bucket will next have capacity — callers surface that as a retry hint
+   * rather than leaving an agent to guess.
+   */
+  take(key: string, perMinute: number): { allowed: boolean; retryAfterMs: number } {
+    if (perMinute <= 0) return { allowed: false, retryAfterMs: 60_000 };
+
+    const now = this.#now();
+    const refillPerMs = perMinute / 60_000;
+    const bucket = this.#buckets.get(key) ?? { tokens: perMinute, lastRefill: now };
+
+    bucket.tokens = Math.min(perMinute, bucket.tokens + (now - bucket.lastRefill) * refillPerMs);
+    bucket.lastRefill = now;
+
+    if (bucket.tokens < 1) {
+      this.#buckets.set(key, bucket);
+      return { allowed: false, retryAfterMs: Math.ceil((1 - bucket.tokens) / refillPerMs) };
+    }
+
+    bucket.tokens -= 1;
+    this.#buckets.set(key, bucket);
+    return { allowed: true, retryAfterMs: 0 };
+  }
+
+  /** Drop idle buckets so a long-lived process does not accumulate keys forever. */
+  prune(idleMs = 300_000): void {
+    const cutoff = this.#now() - idleMs;
+    for (const [key, bucket] of this.#buckets) {
+      if (bucket.lastRefill < cutoff) this.#buckets.delete(key);
+    }
+  }
+}

package/src/profile/authorization.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { credentialRef } from './primitives.ts';
+
+/**
+ * How a remote MCP client gets a token, when a bearer string is not enough.
+ *
+ * A bearer token is what `claude mcp add --header` and every local registration
+ * carry, and it stays the mechanism for those. It is not a mechanism a *remote*
+ * client can use: Claude's and ChatGPT's connector flows expect the OAuth
+ * handshake the MCP specification describes — a `401` naming a protected
+ * resource, discovery, an authorization code with PKCE — and offer nowhere to
+ * paste a fixed string.
+ *
+ * Two modes, because the choice is a real one and neither answer suits
+ * everybody:
+ *
+ * - `self` — this endpoint issues the tokens. It registers clients dynamically,
+ *   so adding a connector is pasting the URL and approving once. Nothing to set
+ *   up, which is why it is the documented default: an identity provider you must
+ *   first go and configure in a console is the most expensive step in the whole
+ *   product, and it is paid by every user.
+ * - `oidc` — an issuer you already run does it, and this endpoint only verifies.
+ *   The cost is that the issuer must be reachable, must be registerable by the
+ *   client (Google, for instance, supports neither dynamic registration nor
+ *   client-ID metadata documents, so its client id has to be pasted in by hand),
+ *   and must be told this endpoint's callback.
+ *
+ * Named for the protocol, not for a vendor — `issuer` is a URL, so pointing this
+ * at Entra, Auth0, or an internal provider is an edit rather than a code path.
+ * Absent means neither: bearer token only, exactly as before.
+ */
+const selfAuthorizationSchema = z.object({
+  mode: z.literal('self'),
+  /**
+   * How long an issued access token lives.
+   *
+   * Short by design and refreshed rather than lengthened: a client that holds a
+   * long-lived token has something worth stealing, and the refresh path is the
+   * one that can be revoked by dropping a row.
+   */
+  access_token_ttl_minutes: z.number().int().positive().max(1440).default(60),
+});
+
+const oidcAuthorizationSchema = z.object({
+  mode: z.literal('oidc'),
+  /** Discovery root — `<issuer>/.well-known/openid-configuration` must resolve. */
+  issuer: z.url(),
+  /**
+   * The audience a presented token must name.
+   *
+   * Not decoration. Without it, any token the same issuer minted for any other
+   * application would open this endpoint — the confused-deputy case the MCP
+   * authorization spec calls out by name.
+   */
+  client_id_ref: credentialRef,
+  /**
+   * Where to ask about a token, when the issuer's discovery document does not
+   * say.
+   *
+   * Access tokens are often opaque, so checking one means asking the issuer.
+   * RFC 7662 standardised that as `introspection_endpoint` in the metadata, and
+   * several large issuers ship an equivalent without advertising one. A URL
+   * here rather than a case in a switch — the same reasoning that puts the
+   * S3-compatible service endpoint in config rather than naming a vendor.
+   */
+  introspection_endpoint: z.url().optional(),
+  /**
+   * Which subjects the issuer may vouch for. Matched against `sub` and against
+   * a verified `email`.
+   *
+   * At least one, always. An empty list is the kind of default that reads as
+   * "everyone" to whoever writes it and "no one" to whoever implemented it, and
+   * default deny is not a thing to leave ambiguous.
+   */
+  allowed_subjects: z.array(z.string().min(1)).min(1),
+});
+
+export const authorizationSchema = z.discriminatedUnion('mode', [
+  selfAuthorizationSchema,
+  oidcAuthorizationSchema,
+]);

package/src/profile/files.ts

@@ -0,0 +1,71 @@
+import { createFilesystemBlobStore } from '#deployments/adapters/filesystem.ts';
+import { createGcsBlobStore } from '#deployments/adapters/gcs.ts';
+import type { BlobStore } from '#stores/blobs';
+
+/**
+ * The workspace as a store, so a deployment's config does not have to be baked
+ * into its image.
+ *
+ * `LANES_LINK_HOME` used to be a directory and nothing else, which is why the
+ * Dockerfile copies `lanes-link.yaml` and `profiles/` in at build time. Its own
+ * comment records the trade and its expiry: *"the image **is** the config, so a
+ * revision fully describes what it serves and rollback is a revision switch.
+ * The cost is a rebuild per config change, which is the tradeoff docs/detailed/init.md
+ * accepts until it becomes annoying."*
+ *
+ * It became annoying. A policy change should not be a Docker build, and because
+ * those paths are gitignored the image cannot be built from a clean checkout at
+ * all — which is what stops there ever being one image that serves any
+ * workspace.
+ *
+ * So the root may be a `gs://` URL, and everything that reads config goes
+ * through a `BlobStore` rather than through `Bun.file`. There is no bootstrap
+ * problem: opening a GCS store needs only the URL and whatever identity is
+ * already present, and config carries secret *references* rather than values
+ * (`./secret-detection.ts` enforces that), so nothing has to be decrypted
+ * before the config that says how to decrypt things can be read.
+ *
+ * See ADR-023 for what this gives up — a Cloud Run revision no longer fully
+ * describes what it serves — and how the guarantee it kept is kept.
+ */
+
+const GCS_SCHEME = 'gs://';
+
+/** Whether a workspace root names a bucket rather than a directory. */
+export function isRemoteWorkspace(root: string): boolean {
+  return root.startsWith(GCS_SCHEME);
+}
+
+/**
+ * The workspace's files.
+ *
+ * Rooted at the workspace, so every caller addresses `lanes-link.yaml` and
+ * `profiles/<name>.yaml` by the same relative key whichever backing it has.
+ */
+export function workspaceFiles(root: string): BlobStore {
+  if (!isRemoteWorkspace(root)) return createFilesystemBlobStore({ root });
+
+  const withoutScheme = root.slice(GCS_SCHEME.length);
+  const slash = withoutScheme.indexOf('/');
+  const bucket = slash === -1 ? withoutScheme : withoutScheme.slice(0, slash);
+  const prefix = slash === -1 ? '' : withoutScheme.slice(slash + 1);
+
+  if (bucket.length === 0) {
+    throw new Error(`LANES_LINK_HOME is "${root}", which names no bucket. Expected gs://<bucket>[/prefix].`);
+  }
+  return createGcsBlobStore({ bucket, ...(prefix ? { prefix } : {}) });
+}
+
+/** Read a UTF-8 document from the workspace, or null when it is not there. */
+export async function readWorkspaceFile(files: BlobStore, key: string): Promise<string | null> {
+  const bytes = await files.get(key);
+  return bytes === null ? null : new TextDecoder().decode(bytes);
+}
+
+export async function writeWorkspaceFile(
+  files: BlobStore,
+  key: string,
+  text: string,
+): Promise<void> {
+  await files.put(key, new TextEncoder().encode(text), { contentType: 'application/yaml' });
+}

package/src/profile/index.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ *
+ * What it deliberately does not own: which providers exist (`#registry`) and
+ * how a call runs (`#dispatch`). Those were all one package called `core`,
+ * which was a name for "the rest of it" rather than for anything.
+ */
+
+export {
+  SUPPORTED_CONTRACT,
+  configSchema,
+  workspaceSchema,
+  type AuthorizationConfig,
+  type Config,
+  type ConnectionConfig,
+  type DeployConfig,
+  type PolicyRuleConfig,
+  type TargetConfig,
+  type WorkspaceConfig,
+} from './schema.ts';
+
+export {
+  ConfigError,
+  loadConfigFile,
+  parseConfig,
+  validateConfig,
+  type LoadedConfig,
+} from './load.ts';
+
+export {
+  findSecrets,
+  formatSecretFindings,
+  shannonEntropy,
+  type SecretFinding,
+} from './secret-detection.ts';
+
+export {
+  WORKSPACE_FILE,
+  describeSelection,
+  installRoot,
+  listProfiles,
+  loadProfileConfig,
+  profilePath,
+  readWorkspace,
+  resolveSelection,
+  resolveWorkspaceRoot,
+  workspacePath,
+} from './workspace.ts';
+export {
+  TARGET_ENV,
+  askedTarget,
+  resolveDeployTarget,
+  resolveTarget,
+  undeclaredTarget,
+} from './targets.ts';
+export {
+  isRemoteWorkspace,
+  readWorkspaceFile,
+  workspaceFiles,
+  writeWorkspaceFile,
+} from './files.ts';
+export {
+  type Resolution,
+  type ResolveOptions,
+} from './workspace.ts';
+
+export {
+  DATA_DIR,
+  layout,
+  profileDir,
+} from './layout.ts';

package/src/profile/layout.ts

@@ -0,0 +1,123 @@
+/**
+ * Where a profile'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
+ * └── 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
+ * ```
+ *
+ * **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.
+ *
+ * **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.
+ *
+ * **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.
+ *
+ * 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.
+ */
+
+/** The directory under the workspace root that holds every profile's data. */
+export const DATA_DIR = 'data';
+
+/**
+ * Everything one profile owns, relative to the workspace root.
+ *
+ * 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
+ * `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.
+   *
+   * 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.
+   */
+  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`,
+  /**
+   * This profile's skills — `<name>.md` or `<name>/SKILL.md`, either layout.
+   *
+   * 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.
+   */
+  skills: (profile: string): string => `${profileDir(profile)}/skills.d`,
+  /**
+   * The provider manifests this profile 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.
+   */
+  providers: (profile: string): string => `${profileDir(profile)}/providers.d`,
+  /** The blob root every provider is namespaced under. */
+  blobs: (profile: string): string => profileDir(profile),
+  /**
+   * The audit log: one object per event, under the profile's blob root.
+   *
+   * 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.
+   */
+  audit: (profile: string): string => `${profileDir(profile)}/audit.log`,
+} as const;