Adding a connection

Your Hyperapp fronts a third-party service, and the agent needs access to it. A connection is that access: the service's identity and credential, bound to one agent, authorized by a human. This page describes the pieces a connection involves and the shapes hosts understand. How you implement them is up to you.

What a connection is

Your Hyperapp is the service's third-party client: the GitHub Hyperapp is a client of GitHub. The connection binds the service's access to the agent, under an identity a human authorizes out of band. From then on the agent acts on the service, as that identity, through your pages. The connection is inherently to the service you front, so the provider needs no naming.

Give each agent its own identity wherever the service allows it: its own app, or at least its own token. Separate credentials mean separate revocation, and the app lives under the user's own account. Fall back to a shared identity only where the service cannot grant a distinct one.

What you end up holding is a grant: the external identity and its credential, bound to the agent. The agent itself holds no external credential. It acts through the grant your Hyperapp carries.

Keep the two identity layers apart. Hyperauth is who the agent is within Hypernet, verified on every request. A connection is the agent's access to an external service, set up once and bound to it.

Choosing a method

The human establishes the connection through a method you declare, and the host renders the matching UI. The methods differ in how isolated an identity the agent gets:

• manifest: the agent gets its own app on the service. The human is redirected to create an app under their own account, from a template you provide. The service returns the new app's credentials, which become the grant. This is the most isolated form: a distinct app, credentials, and webhooks per agent.
• oauth: the agent gets its own token under a shared app. The declaration carries an authorize URL, the host opens it, and a callback turns the authorization into a grant.
• form: the human fills the fields you declare and submits them to your Hyperapp. Use it for an API key, or, where a service has no redirect flow but a per-agent app is still possible, for a manifest and instructions the human follows by hand before pasting the credentials.

Prefer them in that order: a per-agent app, then a per-agent token, then per-agent credentials entered by hand. A service that can do none of these shares one identity. Every method ends in a grant scoped to the agent.

A method may take more than one step: create an app, then install it. You drive this from record: return a next URL from a step, and the host opens it and records again, until no next remains. The host sequences the steps. Each step's meaning is yours.

What you expose

• a declaration, { title, description, icon, authorize }: the card and the method. For manifest or oauth, authorize carries the URL to open. For form, it carries the fields, with any instructions and template.
• a callback a redirect method returns through, and a record endpoint the host posts each step's result to. Record stores the grant and may return a next URL to continue.
• a status: is this agent connected?
• a revoke: drop the grant.

Example: a per-agent GitHub App

The GitHub Hyperapp's pages browse public repositories with no credentials at all. The connection exists for the rest: private repositories, and every write. It uses the manifest method, so every agent gets its own GitHub App. Its declaration:

{
  "title": "GitHub",
  "description": "Create this agent its own GitHub App",
  "authorize": {
    "method": "manifest",
    "url": "https://github.hyperapp.sh/connection/start",
    "fields": [
      {
        "name": "org",
        "label": "Create under an organization (empty = personal account)",
        "type": "text"
      }
    ]
  }
}

The flow, driven by record and next:

1. The host opens start. The page submits a GitHub App manifest to the service (the org field decides a personal or organization app), naming the app after the agent and pointing its webhook at the trigger's events endpoint.
2. GitHub returns through the callback with a code, and the host posts it to record.
3. Record converts the code into the new app's credentials, stores them as the grant, and returns next: the app's install URL.
4. The host opens next, and the human installs the app on the repositories they choose.
5. The callback returns an installation_id. Record resolves the account and completes the grant, and status now answers connected.

One connection, two steps, and the agent ends up with an app of its own: distinct credentials, a distinct webhook secret, revocable in one place. Until then, the app's pages answer with a connect hint instead of data. The not-connected state is a page too.

Where the grant lives

Your choice. Hypervault is the shared store, or keep your own. The grant is provider-agnostic and opaque: a per-agent app's keys, an OAuth token, or an API key, encrypted. Either way your Hyperapp acts on the service itself: read the grant, then mint or present the credential. A trigger verifies the service's events with the same grant's per-agent secret. Credentials and provider logic stay in your app.