Files
PaperClipAI/server/src/services/index.ts
T
DottaandPaperclip 0ffc091473 feat(connections): add durable GitHub identities and webhooks (#12843)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents need source control access for repository work
> - A shared token cannot preserve the responsible person's identity or
an agent's dedicated identity
> - GitHub App tokens also need durable refresh, repository access
checks, and webhook delivery
> - Paperclip already has managed connections, encrypted grants, run
secret leases, and merge-confirmation behavior
> - This pull request extends those systems with GitHub identities
instead of adding a parallel credential system
> - The benefit is durable GitHub access with explicit identity,
repository, runtime, and webhook boundaries

## Linked Issues or Issue Description

No public GitHub issue describes this connection change. This
description follows the feature request template.

**Subsystem affected**

Connected Apps, connection grants, secret resolution, native Git runtime
setup, webhook processing, and the Apps UI.

**Problem or motivation**

Users need to connect GitHub once and let agents use the correct GitHub
identity. A run should use a dedicated agent account when one exists.
Otherwise, it should use the responsible person's account. The
connection must survive token expiry, repository access changes, and
temporary instance downtime.

**Proposed solution**

Add user-owned and agent-owned GitHub grants to the existing connection
model. Resolve one identity for MCP, Git, `gh`, health checks, and
webhook bindings. Store provider tokens in the existing encrypted secret
system. Refresh expiring token pairs under the existing lease and
compare-and-swap path. Register signed Cloud webhook bindings and
process normalized pull request and installation events through a
durable local inbox.

**Alternatives considered**

An organization-wide GitHub token would lose person and agent
attribution. Environment variables alone would bypass the managed
connection and grant model. A new GitHub-only credential store would
duplicate the existing secret and access systems. GitHub App
installation tokens and private-key custody remain outside this first
version.

**Roadmap alignment**

This change implements the Connected Apps direction. It also extends the
shipped MCP Tool Gateway, per-agent secret access, and
action-attribution systems. It does not add a repository catalog. The
open repository catalog work in
[#11234](https://github.com/paperclipai/paperclip/pull/11234) is related
and complementary.

## What Changed

- Added agent-owned connection grants and a per-agent credential policy
with company and subject constraints.
- Added a managed GitHub App method while keeping the personal access
token method as an advanced fallback.
- Added durable access-token and refresh-token handling with proactive
rotation and one automatic recovery after a provider `401`.
- Added GitHub identity and installation summaries without storing
repository-name lists.
- Added signed Cloud webhook binding, event lease, acknowledgement,
local idempotency, pull request merge processing, and installation
access handling.
- Added one identity resolver for MCP, native Git, `gh`, checkout,
health checks, and webhook bindings.
- Added a class-3 run projection for `GH_TOKEN`, `GITHUB_TOKEN`, a
`github.com`-only credential helper, SSH-to-HTTPS rewrite, and GitHub
noreply commit attribution.
- Added personal and dedicated-agent setup choices plus identity,
repository, continuity, and webhook status in the Apps UI.
- Added schema migrations, tests, and connection documentation.

## Verification

- The current head is fully green in GitHub CI, including build,
typecheck, all serialized/general server shards, all browser shards,
policy, canary dry run, review, and security checks.
- Live staging proof completed with a non-expiring GitHub App user
token, selected-repository installation, repository add/remove refresh,
managed MCP, native `gh`, HTTPS clone/push/delete, GitHub noreply commit
attribution, signed merged-PR webhook acceptance, durable
Cloud-to-instance delivery, and installation-access event processing.
Temporary branches and temporary repository access were removed
afterward.
- `pnpm check:token-gates` passed.
- `pnpm -r typecheck` passed before and after the rebase onto
`origin/master`.
- `pnpm build` passed.
- The focused connector suite passed 285 tests after the rebase.
- The full stable suite passed 5,790 tests and failed 22 tests across 8
general server files. The failures reproduced as shared-runner
environment issues. They included `/tmp` versus `/private/tmp`, closed
database connections, and invalid high ephemeral ports. The focused
connection tests pass in isolation.

## Risks

- Migrations add agent grant subjects and a durable connection-event
inbox. Migration numbering and safety checks pass.
- A raw GitHub user token enters the agent process for Git and `gh`.
Per-tool Ask-first controls cannot limit those shell operations. The UI
warns users about this boundary.
- GitHub App user tokens can be non-expiring. Paperclip performs a
continuity check every 30 days, but provider revocation still requires a
reconnect.
- The webhook path accepts only signed and bounded payloads. It stores a
minimal normalized record and no raw provider payload.
- GitHub repository permissions remain authoritative. Removed access can
make a cached repository count temporarily stale, but runtime access
fails immediately.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

OpenAI Codex, `gpt-5.6-sol`, extended reasoning, tool use, code
execution, browser control, and multi-file repository editing. The
context window size was not provided.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-09-04 18:02:52 -05:00

217 lines
9.0 KiB
TypeScript

export { companyService } from "./companies.js";
export { companyArtifactsService } from "./company-artifacts.js";
export { companySearchService } from "./company-search.js";
export { companySearchExtractService } from "./company-search-extract.js";
export { feedbackService } from "./feedback.js";
export { companySkillService } from "./company-skills.js";
export { companySkillPolicyService, normalizeSkillPolicySourceType } from "./company-skill-policy.js";
export { folderService } from "./folders.js";
export { agentService, deduplicateAgentName } from "./agents.js";
export {
builtInAgentService,
deriveBuiltInAgentStatus,
getBuiltInAgentDefinition,
listBuiltInAgentDefinitions,
reconcileBuiltInAgentsOnStartup,
validateBuiltInAgentDefinitions,
type BuiltInAgentDefinition,
type BuiltInManagedResourceState,
type BuiltInManagedResourceStockStatus,
type BuiltInAgentState,
type BuiltInAgentStatus,
} from "./built-in-agents.js";
export { agentInstructionsService, syncInstructionsBundleConfigFromFilePath } from "./agent-instructions.js";
export { assetService } from "./assets.js";
export { documentService, extractLegacyPlanBody } from "./documents.js";
export { artifactReviewDocumentService } from "./artifact-review-documents.js";
export { statusCardService } from "./status-cards.js";
export { finalizeStatusCardsForStalledGeneration } from "./status-card-finalization.js";
export { documentAnnotationService } from "./document-annotations.js";
export {
ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY,
buildContinuationSummaryMarkdown,
getIssueContinuationSummaryDocument,
refreshIssueContinuationSummary,
} from "./issue-continuation-summary.js";
export { projectService } from "./projects.js";
export {
clampIssueListLimit,
ISSUE_LIST_DEFAULT_LIMIT,
ISSUE_LIST_MAX_LIMIT,
issueService,
type IssueFilters,
} from "./issues.js";
export { issueThreadInteractionService } from "./issue-thread-interactions.js";
export { githubConnectionEventService, type GitHubConnectionEventPollResult } from "./github-connection-events.js";
export {
assertIssueReviewVerdictActorAllowed,
type IssueReviewVerdictActor,
} from "./issue-review-policy.js";
export { issueTreeControlService } from "./issue-tree-control.js";
export { issueApprovalService } from "./issue-approvals.js";
export { issueReferenceService } from "./issue-references.js";
export { issueRecoveryActionService } from "./issue-recovery-actions.js";
export {
stalledReviewDecisionService,
type DecideStalledReviewInput,
type StalledReviewDecisionActor,
} from "./stalled-review-decisions.js";
export { taskWatchdogService } from "./task-watchdogs.js";
export {
issueIsInTaskWatchdogSubtree,
resolveTaskWatchdogMutationScope,
taskWatchdogScopeAllowsIssueMutation,
} from "./task-watchdog-scope.js";
export {
createExternalObjectDetectorRegistry,
createExternalObjectResolverRegistry,
externalObjectService,
type ExternalObjectDetector,
type ExternalObjectResolver,
type ExternalObjectResolveResult,
type ExternalObjectResolverSnapshot,
} from "./external-objects.js";
export { goalService } from "./goals.js";
export { activityService, type ActivityFilters } from "./activity.js";
export { workTimelineService, normalizeTimelineWindow } from "./work-timeline.js";
export { attentionService } from "./attention.js";
export { captureDecisionSnapshot, decisionTrainingService } from "./decision-training.js";
export { decisionService } from "./decisions.js";
export { decisionRetentionService } from "./decision-retention.js";
export type {
WorkTimelineActor,
WorkTimelineEdge,
WorkTimelineEvent,
WorkTimelineQuery,
WorkTimelineResult,
WorkTimelineSpan,
} from "./work-timeline.js";
export { approvalService } from "./approvals.js";
export { budgetService } from "./budgets.js";
export { secretService } from "./secrets.js";
export { createRunSecretRedactionRegistry } from "./run-secret-redaction.js";
export { createSecretProposalsService } from "./secret-proposals.js";
export { googleSheetsRobotEmailFromEnv, toolAccessService } from "./tool-access.js";
export {
createVercelConnectClient,
vercelConnectIntegrationStatus,
VercelConnectClientError,
type VercelConnectClient,
} from "./vercel-connect.js";
export { createComposioClient, ComposioApiError, type ComposioClient } from "./composio.js";
export { smokeLabService } from "./smoke-lab.js";
export { backfillLegacyToolOAuthTokens } from "./tool-oauth-legacy-backfill.js";
export { toolAccessPolicyService } from "./tool-access-policy.js";
export { routineService } from "./routines.js";
export { costService } from "./costs.js";
export { financeService } from "./finance.js";
export { heartbeatService, resolveHeartbeatSchedulingSuppression } from "./heartbeat.js";
export {
productivityReviewService,
PRODUCTIVITY_REVIEW_ORIGIN_KIND,
} from "./productivity-review.js";
export { classifyIssueGraphLiveness, type IssueLivenessFinding } from "./recovery/index.js";
export { dashboardService } from "./dashboard.js";
export { sidebarBadgeService } from "./sidebar-badges.js";
export { sidebarPreferenceService } from "./sidebar-preferences.js";
export { resourceMembershipService, type ResourceMembershipPolicyHook } from "./resource-memberships.js";
export { inboxDismissalService } from "./inbox-dismissals.js";
export { accessService } from "./access.js";
export {
backfillPrincipalAccessCompatibility,
ensureHumanRoleDefaultGrants,
insertMissingPrincipalGrants,
type PrincipalAccessCompatibilityBackfillStats,
} from "./principal-access-compatibility.js";
export { authorizationService } from "./authorization.js";
export { inboxAgentPolicyService } from "./inbox-agent-policy.js";
export type {
AuthorizationAction,
AuthorizationActor,
AuthorizationDecision,
AuthorizationResource,
} from "./authorization.js";
export { boardAuthService } from "./board-auth.js";
export { instanceSettingsService, applyManagedExperimentalOverlay } from "./instance-settings.js";
export {
getManagedInstanceConfig,
managedFeatureKeySet,
parseManagedConfigEnv,
MANAGED_CONFIG_ENV_KEY,
type ManagedEnvironmentSpec,
type ManagedInstanceConfig,
} from "./managed-config.js";
export { bootstrapExecutionPolicyFromEnv } from "./execution-policy-bootstrap.js";
export { applyManagedEnvironments } from "./managed-environments.js";
export { buildExportFidelityReport, collectExportFidelityCounts } from "./export-fidelity.js";
export { companyPortabilityService } from "./company-portability.js";
export { teamsCatalogService } from "./teams-catalog.js";
export { environmentService } from "./environments.js";
export {
applyCustomImageTemplateToSandboxConfig,
fingerprintEnvironmentSandboxProviderConfig,
} from "./environment-custom-image-runtime.js";
export {
environmentCustomImageService,
} from "./environment-custom-images.js";
export {
environmentCustomImageTerminalConnectionRegistry,
environmentCustomImageTerminalSessionStore,
EnvironmentCustomImageTerminalConnectionRegistry,
EnvironmentCustomImageTerminalSessionStore,
parseCustomImageSetupSshCommand,
type EnvironmentCustomImageTerminalConnectionClose,
type EnvironmentCustomImageTerminalSessionRecord,
type MintedEnvironmentCustomImageTerminalSession,
type ParsedCustomImageSetupSshCommand,
} from "./environment-custom-image-terminal-sessions.js";
export { executionWorkspaceService } from "./execution-workspaces.js";
export { workspaceOperationService } from "./workspace-operations.js";
export {
workspaceRuntimeLeaseService,
buildWorkspaceRuntimeLeaseOwnerKey,
LEASED_WORKSPACE_RUNTIME_ACTIONS,
WORKSPACE_RUNTIME_ELIGIBLE_ISSUE_STATUSES,
WORKSPACE_RUNTIME_LEASE_TTL_MS,
type WorkspaceRuntimeLeaseClaim,
type WorkspaceRuntimeLeaseOwner,
type WorkspaceRuntimeLeaseService,
} from "./workspace-runtime-leases.js";
export { workspaceFileResourceService } from "./workspace-file-resources.js";
export {
createWorkspaceGitOperationScheduler,
getWorkspaceGitOperationSchedulerSnapshot,
workspaceGitOperationScheduler,
type WorkspaceGitSchedulerSnapshot,
} from "./workspace-git-operation-scheduler.js";
export {
enrichWorkProductMetadataWithDiff,
workProductService,
} from "./work-products.js";
export {
logActivity,
persistActivity,
publishActivity,
type ActivityPublication,
type LogActivityInput,
} from "./activity-log.js";
export { summarySlotService, SUMMARIZER_BUILT_IN_KEY } from "./summary-slots.js";
export { notifyHireApproved, type NotifyHireApprovedInput } from "./hire-hook.js";
export { publishLiveEvent, subscribeCompanyLiveEvents } from "./live-events.js";
export {
reconcileCodexLocalManagedHomesOnStartup,
type CodexAuthReconciliationSummary,
} from "./codex-auth-reconciliation.js";
export { reconcilePersistedRuntimeServicesOnStartup, restartDesiredRuntimeServicesOnStartup } from "./workspace-runtime.js";
export { createStorageServiceFromConfig, getStorageService } from "../storage/index.js";
export {
managedAgentProfileService,
CLAUDE_MANAGED_BETA_VERSION,
type ManagedAgentProfileInput,
} from "./managed-agent-profiles.js";
export {
remoteAgentProfileService,
type RemoteAgentProfileInput,
type RemoteAgentService,
} from "./remote-agent-profiles.js";