Hyperauth

1. Purpose

Hyperauth is the identity layer of Hypernet: how an agent proves which agent it is, how a Hyperapp verifies that and scopes work to it, and how that identity carries from one Hyperapp to the next.

A Hyperapp is free to authenticate however it likes — the Hyperapp specification keeps authentication mechanism-agnostic, and an app may use none, its own scheme, or Hyperauth. Hyperauth is the shared convention that lets apps across Hypernet recognize the same acting agent — the connective tissue that turns isolated apps into a network an agent can move through.

2. Model

• The acting agent is the token. Every request carries a bearer credential that names a verifiable agent identity (sub). The app does not ask "who are you?" out of band; the identity is in the request.
• Verification is offline. A central issuer publishes its public keys; an app verifies a token's signature itself, with no per-request call back to the issuer.
• Audience-bound. A token names the one app it is for. Presented anywhere else, it is refused — a token leaked or replayed to another app is useless there.
• Short-lived. Tokens are minted per interaction, not held long-term.
• Per-agent scoping. An app reads sub and scopes data and capabilities to that agent — the same mechanism that keeps one agent's files private from another's.

3. Presenting identity

Identity rides on the request in one of two ways:

• Authorization: Bearer <token> on every agent-facing request — page fetches and Action submissions alike.
• a ?t= viewer token for views framed in a browser (Embedded Views, Hyperapp §12.1) that cannot set a header.

A request with no valid token is rejected with 401; a valid token meant for a different app is rejected with 403.

4. Delegation — acting across apps

For one Hyperapp to call another as the same agent, it exchanges its own token for one scoped to the target app's origin. The exchanged token keeps the same sub, so the downstream app sees the original agent, not the calling app.

This is what lets a Hyperapp build on another: an app saving a result into Hyperfile writes as the calling agent, and Hyperfile's per-agent isolation still holds. Delegation is the difference between a pile of apps and a network — identity travels with the work.

5. The AGX realization

On AGX, Hyperauth is concrete: a central issuer (hyperauth.agx.computer) mints EdDSA JWTs, each app verifies them against the issuer's JWKS while pinning its own origin as the audience, and the issuer's /exchange performs the audience swap that preserves sub. The wire format, claims, viewer token, and host contract are specified in the AGX Deployment Profile (an AGX-platform document).

The @agx-computer/hyperauth package implements that profile for a Hyperapp:

import { createHyperauth } from "@agx-computer/hyperauth"

const auth = createHyperauth({ home: "https://slides.hyperapp.sh" })

app.use("*", auth.protect()) // gate: 401 unauthenticated, 403 wrong audience

// inside a handler:
const agentId = auth.agent(c) // the acting agent (sub)
const filesToken = await auth.exchange(auth.token(c)!, "https://files.hyperapp.sh")

See the AGX Authoring Conventions for where this sits in an app, and hyperapps/apps/slides for a worker that uses it.

6. Principles

• Identity, not secrets. A token asserts who the agent is; it is not an API key for any downstream service. Access to an external provider is a separate grant — see Hypervault, the credential layer — so an app never holds long-lived secrets by way of identity.
• Offline and audience-bound. Verification needs only the public JWKS, and a token is good at exactly one app — no central session store, no token that works everywhere.
• Optional per app, valuable across the network. Any single Hyperapp may opt out; the worth is in apps agreeing on it, so an agent's identity — and its reach — carries between them.