Add Sign in with AFAuth

Add a Sign in with AFAuth button and a human lands in the account their agent created. Your service acts as an OIDC relying party to the trust attestor’s OpenID Provider. This page is the how-to; the concept is the why.

No SDK helper yet. The trust attestor’s OIDC side is live, but the reference SDK doesn’t ship a drop-in RP handler — you hand-wire the callback (roughly the same shape as a “Sign in with Google” route). It’s a small amount of standard OIDC code; the snippets below are complete.

Prerequisites

A service_did you already use for attestation (§4.3) — sign-in reuses it, it is not a new identifier.
Agents that sign up attested (linked to their human), so accounts carry a sub_h. See Preconditions if some accounts were created as guests first.

1. Register as an OIDC client

Ask the attestor operator to register your service. A client binds three things (§10.8.3):

Field	Value
`client_id`	Your service identifier (your `service_did` is a fine value).
`service_did`	MUST equal the `aud` / `service_did` you use for attestation. It is the audience input to the `sub_h` derivation — a mismatch lands humans in a different, empty account.
`redirect_uris`	Exact callback URLs. Anything not on the allowlist is rejected before a code is issued.

For trust.afauth.org, the operator sets this in the TRUST_OIDC_CLIENTS environment variable:

[
  {
    "client_id": "did:web:api.example.com",
    "service_did": "did:web:api.example.com",
    "redirect_uris": ["https://api.example.com/auth/afauth/callback"]
  }
]

Running your own attestor? The same registry lives in your attestor’s config — see Run your own attestor.

2. The flow

Standard OIDC Authorization Code + PKCE (S256). Discovery is at https://trust.afauth.org/.well-known/openid-configuration.

  Human                  Your service (RP)              trust.afauth.org (OP)
    │  GET /login          │                                │
    │─────────────────────▶│ 302 /oidc/authorize            │
    │                      │  ?client_id&redirect_uri        │
    │                      │  &response_type=code&scope=openid│
    │                      │  &code_challenge&…=S256&state&nonce
    │                      │────────────────────────────────▶│
    │        authenticate as the human   ◀───────────────────│
    │                      │  302 redirect_uri?code&state     │
    │                      │◀────────────────────────────────│
    │                      │ POST /oidc/token (code_verifier) │
    │                      │────────────────────────────────▶│
    │                      │  { id_token, token_type, … }     │
    │                      │◀────────────────────────────────│
    │  session cookie  ◀───│ verify → resolve (iss, sub_h)    │

Generate a PKCE verifier + challenge and a state/nonce, stash them in a short-lived store keyed by state, and redirect:

import { generators } from "openid-client"; // or any PKCE helper

const verifier = generators.codeVerifier();
const challenge = generators.codeChallenge(verifier); // S256
const state = generators.state();
const nonce = generators.nonce();
await pending.put(state, { verifier, nonce }, { ttlSeconds: 600 });

const authorize = new URL("https://trust.afauth.org/oidc/authorize");
authorize.search = new URLSearchParams({
  client_id: SERVICE_DID,
  redirect_uri: "https://api.example.com/auth/afauth/callback",
  response_type: "code",
  scope: "openid",
  code_challenge: challenge,
  code_challenge_method: "S256",
  state,
  nonce,
}).toString();

return Response.redirect(authorize.toString(), 302);

4. Handle the callback (token + verify)

Exchange the code at the token endpoint, then verify the id_token against the trust JWKS:

import { createRemoteJWKSet, jwtVerify } from "jose";

const ISSUER = "https://trust.afauth.org";
const jwks = createRemoteJWKSet(new URL(`${ISSUER}/.well-known/jwks.json`));

// callback: GET /auth/afauth/callback?code&state
const { code, state } = Object.fromEntries(new URL(req.url).searchParams);
const stash = await pending.take(state); // missing → reject (CSRF / replay)

const res = await fetch(`${ISSUER}/oidc/token`, {
  method: "POST",
  headers: { "content-type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code,
    code_verifier: stash.verifier,
    client_id: SERVICE_DID,
    redirect_uri: "https://api.example.com/auth/afauth/callback",
  }),
});
const { id_token } = await res.json();

const { payload } = await jwtVerify(id_token, jwks, {
  issuer: ISSUER,        // iss === https://trust.afauth.org
  audience: SERVICE_DID, // aud === your service_did
});
if (payload.nonce !== stash.nonce) throw new Error("nonce mismatch");

jwtVerify checks the signature, iss, aud, and exp for you; the explicit nonce check closes the loop opened at the authorize step.

5. Resolve to the account — canonicalize the issuer

The account lives under (iss, sub_h), where sub_h is id_token.sub. The catch: your attestation path stored iss = "afauth-trust", but the id_token carries the URL. Map both to one issuer before you look up, or the human lands in a new empty account:

const canonicalIss = (iss) =>
  iss === "afauth-trust" ? "https://trust.afauth.org" : iss;

const account = await users.findByPrincipal(canonicalIss(payload.iss), payload.sub);
if (!account) {
  // No agent has signed up under this human yet at your service.
  // Don't auto-create — tell them to point their agent here first.
  return noAgentAccountYet();
}
return startSession(account); // they're in

This canonicalization is the one thing that silently breaks sign-in. The agent’s attestation iss is the bare string afauth-trust; the id_token iss is https://trust.afauth.org. They are the same attestor — treat them as one before keying the account (§10.8.4). Store your attestation issuer canonicalized too, so both paths agree.

Preconditions

Sign-in resolves an account by (iss, sub_h), so the account needs a sub_h. That is written when an agent signs up attested (after linking to its human). Two cases to know:

Attested signup, then sign-in — works immediately; the signup wrote sub_h.
Guest signup, then link, then sign-in — the guest account had no sub_h. Because signup is idempotent on the agent’s did:key, the principal binds on the agent’s next attested request after linking. After that one request, sign-in resolves to the same account. (Until then, the human signing in would resolve to nothing and see “no account yet”.)

Signing in authenticates the human to the (iss, sub_h) account — it does not transfer ownership. It does not run the claim ceremony or raise the §7.5 owner-binding floor. If you want a recoverable human owner (recovery contacts, credential enrollment), run a claim alongside sign-in — they compose. See §10.8.5.

Where to next

Sign in with AFAuth (concept)

The (iss, sub_h) = OIDC (issuer, subject) idea, in full.

Accept trust attestations

The agent-side gate that writes sub_h in the first place.

Invite and claim

Establish a recoverable human owner alongside sign-in.

Trust API reference

Full OIDC endpoint and id_token shapes.

Build an agent

Operate a service

Troubleshooting

Add Sign in with AFAuth

Prerequisites

1. Register as an OIDC client

2. The flow

4. Handle the callback (token + verify)

5. Resolve to the account — canonicalize the issuer

Preconditions

Where to next

Sign in with AFAuth (concept)

Accept trust attestations

Invite and claim

Trust API reference

​Prerequisites

​1. Register as an OIDC client

​2. The flow

​3. Start the sign-in (authorize)

​4. Handle the callback (token + verify)

​5. Resolve to the account — canonicalize the issuer

​Preconditions

​What sign-in does not do

​Where to next

Sign in with AFAuth (concept)

Accept trust attestations

Invite and claim

Trust API reference

Prerequisites

1. Register as an OIDC client

2. The flow

3. Start the sign-in (authorize)

4. Handle the callback (token + verify)

5. Resolve to the account — canonicalize the issuer

Preconditions

What sign-in does not do

Where to next