@lanes-sh/link 0.1.0

package/src/providers/google/tasks/index.ts

@@ -0,0 +1,53 @@
+import { defineProvider } from '#connectivity';
+import { GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleSetup } from '../shared/setup.ts';
+import { TASKS_REDACT } from './redact.ts';
+
+/**
+ * The narrowest scope Google offers here is the widest one there is.
+ *
+ * Tasks publishes exactly two: `tasks` and `tasks.readonly`. There is no
+ * per-list scope, no app-created scope, and no separate create verb — so adding
+ * one task to one list means holding read, write, and delete over every list in
+ * the account. It is marked broad in `../shared/scopes.ts` for that reason, and
+ * unlike `gmail.modify` or `spreadsheets` there was no alternative to weigh:
+ * this is not the widest of several, it is the only one that can write at all.
+ *
+ * What bounds it is what bounds the others. The token can delete a whole list;
+ * the tool surface cannot, because `tasklists.delete` is not vendored — Tasks
+ * has no trash, so destroying a list destroys every task in it. `lanes link
+ * policy deny tasks.*` narrows it further.
+ *
+ * No `identity` block, and that is a decision rather than an omission. Nothing
+ * reachable under `auth/tasks` returns an address: `tasklists.list` answers
+ * with titles, and `userinfo.email` is a scope this provider has no other use
+ * for. Adding one for a cosmetic label is exactly what the documented-minimum
+ * rule refuses, so `connect` asks instead — and because it matches the typed
+ * address against existing connections, a reconnect still repairs the row it
+ * already made rather than appending `main2`.
+ *
+ * Version in the path, host without it (`tasks.googleapis.com` +
+ * `/tasks/v1/lists/...`) — the Sheets shape, not Drive's.
+ */
+const TASKS_SCOPES = ['https://www.googleapis.com/auth/tasks'];
+
+export const tasks = defineProvider({
+  id: 'tasks',
+  name: 'Google Tasks',
+  description:
+    'Read and write task lists and tasks — create, edit, complete, reorder, and delete — via the Tasks REST API.',
+  connector: {
+    kind: 'http',
+    base_url: 'https://tasks.googleapis.com',
+    openapi: specPath('tasks.v1.json'),
+  },
+  auth: {
+    kind: 'oauth',
+    registration: 'manual',
+    app: GOOGLE_APP,
+    scopes: TASKS_SCOPES,
+    ...GOOGLE_OAUTH,
+  },
+  setup: googleSetup('Tasks', TASKS_SCOPES, { apis: ['tasks.googleapis.com'] }),
+  redact: TASKS_REDACT,
+});

package/src/providers/google/tasks/redact.ts

@@ -0,0 +1,34 @@
+/**
+ * What survives into the audit log when a task is read or changed.
+ *
+ * `title` and `notes` are the task — the same call as Gmail's `labels.create`,
+ * where the name is the user's own words and the log has no business keeping
+ * them. `due` and `status` are kept, because "marked the thing due Friday done"
+ * is the shape of the change and neither argument says what the thing was.
+ *
+ * Two argument names are not what they look like, and a wrong key here fails
+ * silently — the lookup misses, every value is withheld, and it reads exactly
+ * like working redaction. The generator disambiguates a collision between a
+ * path or query parameter and a body field by prefixing the location, so
+ * `tasks.insert` takes `queryParent` (the query one) beside the body's
+ * `parent`. `tasks.move` has no such collision and takes a plain `parent`.
+ */
+export const TASKS_REDACT: Record<string, string[]> = {
+  'tasklists.list': ['maxResults'],
+  'tasklists.insert': [],
+  'tasklists.patch': ['tasklist'],
+  'tasks.list': [
+    'tasklist',
+    'showCompleted',
+    'showDeleted',
+    'showHidden',
+    'dueMin',
+    'dueMax',
+    'maxResults',
+  ],
+  'tasks.get': ['tasklist', 'task'],
+  'tasks.insert': ['tasklist', 'queryParent', 'previous', 'due', 'status'],
+  'tasks.patch': ['tasklist', 'task', 'due', 'status'],
+  'tasks.delete': ['tasklist', 'task'],
+  'tasks.move': ['tasklist', 'task', 'parent', 'previous'],
+};

package/src/providers/harness.ts

@@ -0,0 +1,95 @@
+import { createLocalConnector } from '#connectivity/transports';
+import { buildProviderContext } from '#dispatch';
+import { createMemoryCredentials, createMemoryState } from '#stores/state/testing.ts';
+import { createMemoryBlobStore } from '#stores/blobs/testing.ts';
+import type {
+  AnyConnector,
+  CapabilityResult,
+  ConnectorContext,
+  ProviderContext,
+  ProviderDefinition,
+} from '#connectivity';
+
+/**
+ * One owner provider, wired the way the runtime wires it.
+ *
+ * Through the local connector rather than by calling handlers directly, because
+ * the connector is what routes a resource read and a prompt render — the part
+ * that did not exist before M4. The dispatcher and the MCP layer are covered end
+ * to end in `apps/server/src/owner.test.ts`; this is the provider's own
+ * behaviour.
+ */
+export interface ProviderHarness {
+  readonly connector: AnyConnector;
+  readonly context: ProviderContext;
+  invoke(name: string, args?: Record<string, unknown>): Promise<CapabilityResult>;
+  annotations(): Record<string, unknown>;
+}
+
+export function harnessFor(
+  definition: ProviderDefinition,
+  connectionId = 'owner',
+): ProviderHarness {
+  const annotations: Record<string, unknown> = {};
+
+  const context = buildProviderContext({
+    manifest: definition.manifest,
+    definition,
+    connection: { id: connectionId, provider: definition.manifest.id, account: 'Owner' },
+    state: createMemoryState(),
+    // Seeded deliberately: an owner provider must not be able to read any of
+    // this, and the credential-boundary test says so by name.
+    credentials: createMemoryCredentials({
+      'gmail/main': 'refresh-token',
+      'profile/token': 'llk_token',
+    }),
+    storage: createMemoryBlobStore(),
+    audit: {
+      annotate(detail) {
+        Object.assign(annotations, detail);
+      },
+    },
+    log: { debug() {}, info() {}, warn() {}, error() {} },
+    signal: new AbortController().signal,
+    // The runtime hands this to any provider that is not `local`, so a provider
+    // authoring a capability against its own vendor's API has it here too.
+    authorize: async (request) => request,
+  });
+
+  const connector = createLocalConnector(definition);
+
+  const connectorContext: ConnectorContext = {
+    manifest: definition.manifest,
+    provider: context,
+    authorize: async (request) => request,
+  };
+
+  return {
+    connector,
+    context,
+    annotations: () => annotations,
+    invoke: (name, args = {}) =>
+      connector.invoke({ name, description: '', inputSchema: {} }, args, connectorContext),
+  };
+}
+
+/** The resource links a tool result carries, unrouted as the provider wrote them. */
+export function linksOf(result: CapabilityResult): string[] {
+  if (!('content' in result)) return [];
+  return result.content
+    .filter((block): block is { type: 'resource_link'; uri: string } => block.type === 'resource_link')
+    .map((block) => block.uri);
+}
+
+/** The text of a tool or resource result, joined — what a caller would read. */
+export function textOf(result: CapabilityResult): string {
+  if ('content' in result) {
+    return result.content
+      .filter((block): block is { type: 'text'; text: string } => block.type === 'text')
+      .map((block) => block.text)
+      .join('\n');
+  }
+  if ('contents' in result) return result.contents.map((entry) => entry.text).join('\n');
+  if ('messages' in result) return result.messages.map((message) => message.text).join('\n');
+  return result.resources.map((resource) => resource.uri).join('\n');
+}

package/src/providers/icloud/calendar/index.ts

@@ -0,0 +1,27 @@
+import { defineProvider } from '#connectivity';
+import { ICLOUD_APP, icloudSetup } from '../shared/setup.ts';
+
+export const icloudCalendar = defineProvider({
+  id: 'icloud_calendar',
+  name: 'iCloud Calendar',
+  description: 'Read and create events in iCloud calendars over CalDAV.',
+  connector: {
+    kind: 'dav',
+    base_url: 'https://caldav.icloud.com',
+    service: 'caldav',
+    // Apple's limit, declared rather than assumed by the transport.
+    max_range_days: 366,
+  },
+  auth: { kind: 'basic', app: ICLOUD_APP },
+  identity: { kind: 'connector' },
+  setup: icloudSetup('iCloud Calendar'),
+  redact: {
+    list_events: ['calendar', 'start', 'end', 'limit'],
+    get_event: ['calendar', 'uid'],
+    // The uid and calendar say *which* event changed, which is what makes the
+    // log worth having; the summary and location are the content of it.
+    update_event: ['calendar', 'uid'],
+    delete_event: ['calendar', 'uid'],
+    create_event: ['calendar'],
+  },
+});

package/src/providers/icloud/contacts/index.ts

@@ -0,0 +1,17 @@
+import { defineProvider } from '#connectivity';
+import { ICLOUD_APP, icloudSetup } from '../shared/setup.ts';
+
+export const icloudContacts = defineProvider({
+  id: 'icloud_contacts',
+  name: 'iCloud Contacts',
+  description: 'Search and read contacts in an iCloud address book over CardDAV.',
+  connector: { kind: 'dav', base_url: 'https://contacts.icloud.com', service: 'carddav' },
+  auth: { kind: 'basic', app: ICLOUD_APP },
+  identity: { kind: 'connector' },
+  setup: icloudSetup('iCloud Contacts'),
+  redact: {
+    // Not `query`: a name is content.
+    search_contacts: ['addressbook', 'limit'],
+    create_contact: ['addressbook'],
+  },
+});

package/src/providers/icloud/drive/index.ts

@@ -0,0 +1,47 @@
+import { defineProvider } from '#connectivity';
+
+/**
+ * iCloud Drive, which is only reachable from the Mac that holds it.
+ *
+ * Not a fourth service on the same app-specific password: Apple exposes no
+ * protocol for Drive at all. What it does expose is a folder, synced by the
+ * system, that any process on that Mac may read with the operating system's
+ * permission. So this is `auth: none` — there is no credential, and nothing that
+ * could be copied to a server somewhere else. ADR-011 covers why the cloud
+ * answer has to be a relay to a local instance rather than a stored token.
+ */
+export const icloudDrive = defineProvider({
+  id: 'icloud_drive',
+  name: 'iCloud Drive',
+  description: 'Read and organise files in iCloud Drive, on the Mac that syncs them.',
+  connector: {
+    kind: 'fs',
+    root: '~/Library/Mobile Documents/com~apple~CloudDocs',
+    // Desktop and Documents sync into here, so the root is most of a person's
+    // files. The read limit is deliberately modest.
+    max_file_bytes: 262_144,
+    // macOS names an undownloaded file `.<name>.icloud`, and `brctl` is how you
+    // pull it down. Both are Apple's conventions, so both are declared here
+    // rather than known by the filesystem transport.
+    placeholder: {
+      suffix: '.icloud',
+      hint: 'Open it once in Finder, or run: brctl download',
+    },
+  },
+  auth: { kind: 'none' },
+  identity: { kind: 'connector' },
+  redact: {
+    // Paths are recorded — an audit line that cannot say *which* file was read
+    // answers nothing — but never contents.
+    list_files: ['path', 'recursive', 'limit'],
+    read_file: ['path'],
+    file_info: ['path'],
+    // Not `query` or `contains`: a search term is frequently more revealing than
+    // the result, which is the same reasoning mail search uses.
+    search_files: ['path', 'limit'],
+    write_file: ['path', 'overwrite'],
+    move_file: ['from', 'to'],
+    create_folder: ['path'],
+    trash_file: ['path'],
+  },
+});

package/src/providers/icloud/index.ts

@@ -0,0 +1,8 @@
+/**
+ * iCloud's four providers: three sharing one app-specific password, and Drive,
+ * which shares nothing because Apple exposes no protocol for it at all.
+ */
+export { icloudCalendar } from './calendar/index.ts';
+export { icloudContacts } from './contacts/index.ts';
+export { icloudDrive } from './drive/index.ts';
+export { icloudMail } from './mail/index.ts';

package/src/providers/icloud/mail/index.ts

@@ -0,0 +1,37 @@
+import { defineProvider } from '#connectivity';
+import { ICLOUD_APP, icloudSetup } from '../shared/setup.ts';
+
+export const icloudMail = defineProvider({
+  id: 'icloud_mail',
+  name: 'iCloud Mail',
+  description: 'Read, search, and send mail in an iCloud mailbox over IMAP and SMTP.',
+  connector: {
+    kind: 'imap',
+    host: 'imap.mail.me.com',
+    port: 993,
+    smtp: { host: 'smtp.mail.me.com', port: 587, starttls: true },
+  },
+  auth: { kind: 'basic', app: ICLOUD_APP },
+  identity: { kind: 'connector' },
+  setup: icloudSetup('iCloud Mail'),
+  redact: {
+    // Opted back in one key at a time; everything unlisted is withheld. Never
+    // the search terms — a query is content, and "who did I email about the
+    // diagnosis" is the whole message.
+    search_messages: ['mailbox', 'limit', 'unseen', 'flagged'],
+    get_message: ['mailbox', 'uid', 'include_body'],
+    mark_messages: ['mailbox', 'add_flags', 'remove_flags'],
+    // `destination_flag` alongside `destination`: they are two spellings of the
+    // same fact, and keeping only one means a junk move — the case the flag
+    // exists for — logs with no destination at all.
+    move_messages: ['mailbox', 'destination', 'destination_flag'],
+    // Still nothing, now that this can carry attachments — and *especially* now.
+    // The recipients and the body are the message, and `attachments` is the one
+    // argument that may literally contain a file, so keeping it verbatim would
+    // put base64 in the log. What did get attached is recorded instead by the
+    // send path itself, through `audit.annotate`: filename, size, type, SHA-256
+    // and where the bytes came from. Identifiers, not content — and with `path`
+    // unrestricted, that record is the only trace of which file left the machine.
+    send_message: [],
+  },
+});

package/src/providers/icloud/shared/setup.ts

@@ -0,0 +1,66 @@
+export const ICLOUD_APP = 'icloud';
+
+/**
+ * iCloud: one account, three providers.
+ *
+ * Apple publishes no REST API and no MCP server for Mail, Calendar, or
+ * Contacts. There *is* an OAuth path — shipped October 2025 and used by Outlook
+ * — but it is partner-gated, with no scopes published for these services, so an
+ * app-specific password over IMAP and DAV is the only route actually open. If
+ * that changes, auth is orthogonal to connectivity here: it is a change to those
+ * three `auth` blocks and nothing else.
+ *
+ * Three manifests because a manifest has one connector and mail is a different
+ * protocol from calendars — and because that is the better shape anyway.
+ * `connect` writes one policy line per provider, so an operator can allow
+ * `icloud_calendar.*` while never granting mail. They share `app: icloud`, which
+ * resolves all three to the same `icloud/<account>` credential, so the
+ * app-specific password is typed exactly once: Apple issues it at *account*
+ * scope, so one password genuinely does unlock all three.
+ *
+ * Reminders and Notes are deliberately absent. Apple moved to-do lists to a
+ * private store after iOS 13, and CalDAV now returns either legacy data or
+ * tombstones for them; Notes were never exposed. Saying so here is better than
+ * letting someone discover it as a bug.
+ */
+export const icloudSetup = (product: string) => ({
+  summary:
+    `${product} uses an app-specific password. Your Apple Account password will not work — Apple refuses it ` +
+    `for third-party clients — and Lanes Link never sees it. You are asked once: the same password covers ` +
+    `Mail, Calendar, and Contacts, because Apple issues it per account rather than per service.`,
+  docs: 'docs/detailed/setup/icloud.md',
+  docs_url: 'https://support.apple.com/en-us/102654',
+  steps: [
+    'Sign in at https://account.apple.com and open "Sign-In and Security".',
+    'Two-factor authentication must be on. Without it Apple does not offer app-specific passwords at all, and the section below simply will not appear.',
+    'App-Specific Passwords → Generate. Name it "Lanes Link" — the name is the only way to revoke this one later without cutting off your other devices.',
+    'Copy the sixteen characters. Apple shows them once, as xxxx-xxxx-xxxx-xxxx; the hyphens are cosmetic and it is accepted either way.',
+    'Note that changing your Apple Account password revokes every app-specific password at once. That is the cause of most sudden iCloud sync failures, and the fix is to generate a new one and run: lanes link connect icloud --replace.',
+  ],
+  // What a transport cannot say for itself, because it must not know which
+  // vendor it is talking to. This is the sentence that used to be hard-coded in
+  // three places across `imap` and `dav`.
+  //
+  // `--replace` rather than a bare re-run: the stored credential is the one
+  // that was just refused, and every other spelling of the command finds it
+  // already there and reuses it. Advising the loop is how a mistyped password
+  // became unrecoverable.
+  troubleshooting:
+    'For iCloud this is almost always an Apple Account password used where an app-specific password belongs. Generate one at https://account.apple.com and re-run: lanes link connect icloud --replace.',
+  prompts: [
+    {
+      key: 'username',
+      label: 'Apple Account (the full email address)',
+      secret: false,
+      scope: 'connection' as const,
+      field: 'username' as const,
+    },
+    {
+      key: 'password',
+      label: 'App-specific password',
+      secret: true,
+      scope: 'connection' as const,
+      field: 'password' as const,
+    },
+  ],
+});

package/src/providers/index.ts

@@ -0,0 +1,93 @@
+import type { ProviderDefinition, ProviderManifest } from '#connectivity';
+import { calendar } from './google/calendar/index.ts';
+import { contacts } from './google/contacts/index.ts';
+import { docs } from './google/docs/index.ts';
+import { drive } from './google/drive/index.ts';
+import { driveMcp } from './google/drive-mcp/index.ts';
+import { gmail } from './google/gmail/index.ts';
+import { gmailMcp } from './google/gmail-mcp/index.ts';
+import { sheets } from './google/sheets/index.ts';
+import { tasks } from './google/tasks/index.ts';
+import { icloudCalendar } from './icloud/calendar/index.ts';
+import { icloudContacts } from './icloud/contacts/index.ts';
+import { icloudDrive } from './icloud/drive/index.ts';
+import { icloudMail } from './icloud/mail/index.ts';
+import { linear } from './linear/index.ts';
+import { notion } from './notion/index.ts';
+
+/**
+ * Every provider, in one list.
+ *
+ * Names and imports only. There is no vendor knowledge in this file and there
+ * must never be any — a Google scope, an Apple error message, or a spec path
+ * appearing here means it has escaped the folder that owns it.
+ *
+ * Each folder holds *all* of its provider: the manifest, the scopes it asks
+ * for, what it redacts from the audit log, the setup walkthrough, and any
+ * vendored specification. Adding a provider is a folder and a line below.
+ *
+ * The list is a convenience, not a boundary: anything not here is a YAML
+ * manifest in the profile's own `providers.d/`, validated by the same schema and
+ * loaded by `./custom/load.ts`.
+ *
+ * The owner layer — `memory/`, `skills/`, `vault/` — is deliberately absent
+ * from this list and not from this directory. Those three are providers in
+ * every sense the architecture cares about, but they are *constructed* rather
+ * than declared: each needs a store handed to it at startup, so they are
+ * registered by `#profile`'s registry builder instead of being static data.
+ */
+/**
+ * Manifests, and the rare provider that carries a capability of its own.
+ *
+ * The union is not an invitation. A provider is a *declaration*, and that is what
+ * makes adding one cheap; `gmail` is a definition only because sending mail means
+ * assembling a MIME message and no document describes doing that. Everything else
+ * here is still fifteen lines of data. `registry.register` already accepted both
+ * shapes, so nothing downstream had to change.
+ */
+export const PROVIDERS: readonly (ProviderManifest | ProviderDefinition)[] = [
+  notion,
+  linear,
+  gmail,
+  drive,
+  sheets,
+  docs,
+  calendar,
+  tasks,
+  contacts,
+  gmailMcp,
+  driveMcp,
+  icloudMail,
+  icloudCalendar,
+  icloudContacts,
+  icloudDrive,
+];
+
+/** The manifest half of an entry, whichever shape it arrived in. */
+export const manifestOf = (entry: ProviderManifest | ProviderDefinition): ProviderManifest =>
+  'manifest' in entry ? entry.manifest : entry;
+
+/**
+ * Every provider's manifest, for the callers that only ask about declarations —
+ * which scopes are requested, which are `http`, what `base_url` each names.
+ *
+ * Derived rather than a second list, so it cannot fall out of step with the one
+ * above.
+ */
+export const PROVIDER_MANIFESTS: readonly ProviderManifest[] = PROVIDERS.map(manifestOf);
+
+export {
+  calendar,
+  contacts,
+  docs,
+  drive,
+  driveMcp,
+  gmail,
+  gmailMcp,
+  sheets,
+  tasks,
+} from './google/index.ts';
+export { icloudCalendar, icloudContacts, icloudDrive, icloudMail } from './icloud/index.ts';
+export { linear } from './linear/index.ts';
+export { notion } from './notion/index.ts';
+export { SCOPE_MEANINGS, type ScopeMeaning } from './scopes.ts';

package/src/providers/linear/index.ts

@@ -0,0 +1,11 @@
+import { defineProvider } from '#connectivity';
+
+/** Linear, like Notion, registers itself — nothing for an operator to set up. */
+export const linear = defineProvider({
+  id: 'linear',
+  name: 'Linear',
+  description: 'Issues, projects, comments, and cycles, via Linear\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.linear.app/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic', scopes: ['read', 'write'] },
+  identity: { kind: 'tool', tool: 'get_workspace', field: 'name' },
+});

package/src/providers/linear/scopes.ts

@@ -0,0 +1,7 @@
+import type { ScopeMeaning } from '../scopes.ts';
+
+/** Linear's two scopes, which are as plain as they look. */
+export const LINEAR_SCOPE_MEANINGS: Record<string, ScopeMeaning> = {
+  read: { meaning: 'read-only access' },
+  write: { meaning: 'create and modify' },
+};