AuthReturn / agent accessAgent guide

One authorization protocol, multiple agent hosts

AuthReturn is the portable authority. FairyStack is one consent and credential-broker client. Apps enforce the resulting owner, actor, audience, and scopes.

Architecture proposal
Agent authorization service topologyA user approves scopes in FairyStack. AuthReturn delegates access to a named agent and supplies the web app verification contract. An encrypted vault remains a separate legacy fallback.approves scopesdevice requestdelegated tokenverificationcontractlegacy leaseUser owns outcomeFairyStack consentbrokerAuthReturn protocolauthorityNamed agentdelegated actorWeb app resourceserverEncrypted vaultlegacy fallback

Delivery path: bridge now, standard later

There is no generally adopted protocol that makes an arbitrary existing website create and delegate an account to an agent. The practical and portable paths therefore remain distinct.

Now · compatibility

SOPS on a user-controlled VPS

FairyStack brokers task-bounded access to encrypted credentials. Browser automation handles app-specific signup, login, and email confirmation. This works with legacy sites, but it is infrastructure—not interoperability.

Next · reference flow

AuthReturn + Prototype Prototype

Prove device approval, a named agent identity, scoped credentials, revocation, and owner/actor audit records without exposing a reusable human password.

Later · ecosystem

Publish the portable profile

Ship discovery metadata and a small OAuth-compatible agent-delegation contract, compare emerging proposals, and let other services adopt it without requiring FairyStack.

Service boundary

The protocol remains useful without FairyStack; FairyStack gains a standard integration instead of privileged coupling.

Responsibilities by service
ComponentOwnsMust not own
AuthReturnDiscovery, account linking, consent records, agent principals, scoped tokens, exchange, revocationAgent runtime, app business data, arbitrary-site browser automation
FairyStackUser approval surface, agent identity, policy, audit view, bounded credential leasesAuthReturn internals or universal app identity
Consuming appResources, authorization checks, owner/actor distinction, app-specific scopesUser passwords for agents or cross-app credentials
Vault adapterEncrypted refresh tokens and credentials needed by legacy sitesConsent, authorization policy, or plaintext exposure to chat

Standard path

  1. DiscoverAgent reads authorization metadata.
  2. RequestAgent asks for exact app scopes.
  3. ApproveUser confirms on a trusted surface.
  4. IssueAuthReturn creates or links the identity and returns a bounded credential.
  5. OperateApp records both owning user and acting agent.

Settled direction

  • AuthorityAuthReturn is the central protocol service.
  • HostFairyStack consumes the protocol; it does not define it.
  • IdentityThe agent is a named actor delegated by a user, not a shared human login.
  • DefaultShort-lived scoped tokens; stored passwords are a compatibility fallback.

Open decisions

  • ConsentWhich scopes can policy pre-approve, and which always interrupt the user?
  • BindingUse proof-of-possession keys immediately or phase them after bearer-token interoperability?
  • LifetimeDefault access, refresh, inactivity, and maximum delegation limits.
  • LegacySupported vault providers and the boundary for automated signup and email confirmation.

Protocol and rollout

Hard boundary: no protocol can create accounts in an arbitrary website that exposes no authorization API. Those sites require explicit browser automation and vaulted credentials until they adopt delegated access.
Reference protocol

Start with OAuth Device Authorization for the agent-to-user approval loop, OAuth Token Exchange for delegation, standard authorization-server metadata for discovery, and app-defined scopes. AuthReturn should publish one stable metadata document and keep the flow usable by agents outside FairyStack.

First vertical slice
  • AuthReturn exposes metadata, device authorization, approval, polling token, and revocation endpoints.
  • FairyStack renders approval and retains only encrypted refresh material.
  • Prototype Prototype becomes the reference resource server and distinguishes owner from acting agent.
  • A clean agent with no pre-mounted app secret creates one private study end to end.
Legacy compatibility

Use FairyStack’s existing SOPS-managed secret store as the first vault adapter rather than inventing new cryptography. The broker issues task-bounded leases to browser automation, records use, and revokes or rotates credentials after exposure. The legacy path stays visibly separate so convenience does not masquerade as delegated authorization.

Primary references: Problem statementOAuth Device Authorization · RFC 8628OAuth Token Exchange · RFC 8693Emerging Agent Auth draft