integration-plugins

Integration And Issue Plugins

Integration plugins in `packages/plugins/src/integrations/` own service metadata, auth method descriptors, credential schemas, and credential verification. Issue plugins in `packages/plugins/src/issues/` reference an integration by `integrationId` and own issue operations. GitHub follows the same plugin contracts as the other integrations.

Authentication Contract

`capabilities.auth` is a serializable descriptor for connection UI: form fields, OAuth, device flow, CLI import, and whether an account label is required. Executable code belongs in `behavior.auth`, which must register both:

• `credentialsSchema`: the provider's Zod parser for its JSON credential payload. Use the

same schema in the provider's client factory and verifier. Parsing is local validation and normalization; it does not prove that a credential is accepted by the remote API.

• `verify`: checks credentials against the provider and returns canonical credentials on

success, together with optional stable account identity and display metadata. Persist the returned credentials, never fall back to the submitted form values.

Credentials include connection configuration needed to create a client, such as GitHub's `apiBaseUrl`, Jira's `siteUrl`, or Plane's workspace slug. The schema remains backend-only; it is not embedded in the renderer descriptor. Register schemas for every integration, including GitHub. GitHub additionally exposes its credential schema and TypeScript type through `@emdash/plugins/integrations/github` for GitHub-specific client consumers.

Identity And Host Ownership

`VerifiedAccountIdentity.id` identifies the provider account within `scope`; the desktop currently falls back to `host`, then integration ID, when no explicit scope is supplied. Preserve existing identity keys when changing schemas. `login`, avatar, and display names are optional presentation data. Do not invent a login from a display name, workspace name, or ID. Providers without a stable remote identity may omit `account`; the desktop owns their local account ID and user label.

The desktop owns account selection, deduplication, project preferences, persistence, secret references, and credential-format migrations. Public host interfaces live in `apps/emdash-desktop/src/core/features/integrations/api/node/integration-accounts.ts`: credential consumers use `IntegrationAccountReader`; authentication adapters complete verified connections through `IntegrationConnections`.

`IntegrationConnectionService` verifies submitted credentials through the plugin, then uses the same completion path as trusted OAuth, device-flow, and CLI authentication adapters. That path owns identity matching, reconnect checks, labels, and persistence. GitHub's authentication adapters translate their verified identity and credentials into this contract; they do not write account records themselves. Migration-only imports use the durable import mechanism so completion and legacy-source cleanup remain retryable.

`IntegrationAccountStore` validates credentials with the registered provider schema on both reads and writes. It stores the normalized record as JSON through `ProviderAccountRegistry`. The registry owns account rows, defaults, and opaque secret references. Its secret-store interface is still string-based: the string is the JSON document, encrypted by the app secret backend. Account metadata contains no token.

At service startup, `migrateGitHubJsonCredentials` wraps existing raw GitHub tokens as `{ accessToken, apiBaseUrl }` before account consumers become available. The migration is offline and idempotent, retains account IDs/defaults/metadata/secret references, and can retry failed writes. It never interprets an existing JSON document as a token. The older single-token GitHub importer also writes the JSON representation.

flowchart TD
  Form[Integration form] --> Verify[Plugin verification]
  Verify --> Connect[IntegrationConnectionService]
  Auth[OAuth / device / CLI auth adapter] --> Connect
  Connect --> Store[IntegrationAccountStore: provider schema + JSON]
  Store --> Registry[ProviderAccountRegistry]
  Registry --> Rows[(Account metadata + secret reference)]
  Registry --> Secrets[Encrypted app secret store]
  Feature[Issue / PR / repository operation] --> Select[Resolve account from project choice and inventory]
  Select --> Store
  Store --> Client[Provider client with credentials and connection config]

The integrations Wire API separates `listProviders` (available providers described by `IntegrationProviderDescriptor`, including auth methods and `issueCapabilities`) from `listAccounts` (saved account summaries grouped by provider ID). Account inventory does not verify credentials; live connection checks belong to a separate operation.

The renderer observes one account query via `useAccounts()`, `useAccounts(providerId)`, or `useAccounts(providerId, typeGuard)`. Provider authentication actions are separate from account inventory; there is no GitHub-specific account query/cache.

The integrations event stream owns `accounts-changed` notifications for successful connections, reconnects, removals, default changes, and startup reconciliation. The renderer refreshes shared account inventory and dependent issue queries through `useIntegrationAccountEvents`, including after a stream gap. GitHub events carry only authentication progress and notifications. `IntegrationConnectionService` is the sole owner of `integration_connected` telemetry; authentication adapters do not count the same connection again.

Project account selection has one provider-parameterized seam: `useProjectAccount` in browser consumers and `ProjectIntegrationAccountResolver` in node consumers share `resolveProjectAccount`. Callers identify the provider and choose an explicit repository context: project context uses the effective base remote; resource context uses the supplied repository URL. Non-repository integrations omit that