Ship AFAuth in your CLI

​

The shape

npm i @afauthhq/agent

​

Provision in one call

import { loadOrCreateAgent, loadBinding, saveBinding } from "@afauthhq/agent/node";

const { agent } = await loadOrCreateAgent(); // reads the shared ~/.afauth/key.json

import { signup } from "@afauthhq/agent";

const existing = (await loadBinding({ agentDid: agent.did })) ?? undefined;

const result = await signup({
  agent,
  baseUrl: "https://api.acme.dev",
  binding: existing,
  label: "acme-cli",
  onLink: (url) => {
    // Fires ONLY when your service is attested_only and this machine isn't
    // linked yet — the one-time human approval. Under `optional`, never called.
    console.error("Approve this agent once — you, in a browser:\n  " + url);
  },
});

// Persist a freshly-established link so the human is never prompted again.
if (result.binding && result.binding !== existing) {
  await saveBinding({ agentDid: agent.did, binding: result.binding });
}

const signed = await agent.buildOwnerInvitation({
  baseUrl: "https://api.acme.dev",
  recipient: { type: "email", value: "you@example.com" },
});
await fetch(signed.url, { method: signed.method, headers: signed.headers, body: signed.body });

​

Pick your attestation mode

• attested_only — a human links once at the trust attestor before the agent gets anything. Choose it when your free tier is expensive (compute, storage, inference — anything costly you give away per user): you want a real person on the hook before granting it, so a flood of throwaway keys can’t drain you. The CLI’s first signup then includes the one-time onLink approval (reused across every AFAuth service thereafter).
• optional — the agent signs up with just its key: no attestor, no browser. Choose it when free resources are cheap and content moderation + graded rate limits are enough anti-abuse. You can grade trust — give unclaimed keys a lower quota/rate than claimed, human-owned accounts.

​

The login ladder — and no merge

• Claim — turn the current identity into an account in place (your existing owner-invitation/claim ceremony). Keeps everything.
• Sign in to an existing account — switch this machine to it. The identity’s prior work stays with the key — it is not merged.

​

Logout: go dormant, don’t delete

• Drop any stored bearer key and persist a signed_out flag. The client now resolves to anonymous — it signs nothing — until an explicit login.
• Leave ~/.afauth/ untouched. acme login --afauth lifts the marker and the same did:key is active again, intact, still owning its artifacts.

​

Don’t rebrand the plumbing

• The account verb is acme login (or fold it into your flow) — never afauth init. Sending a user to a second, unfamiliar tool is friction at the worst moment.
• Don’t mirror AFAuth’s subcommands (acme trust link, …). Fold the human step into login/signup; the user’s vocabulary stays at your verbs.
• Name “AFAuth” at most once, as reassurance. The one unavoidable AFAuth-branded moment is the trust attestor’s approval page — and only for attested_only services. Pass a clear label so it shows what’s being linked.

​

Notes & gotchas

• Pin @afauthhq/agent@^0.6.1. (0.6.0 fails to load on a clean install — it re-exported a helper from a @afauthhq/core that hadn’t shipped it.)
• Signing multipart uploads: fetch serializes a FormData with a boundary you can’t see up front, so a pre-computed Content-Digest won’t match. Serialize it yourself first, then sign over the bytes:
  const probe = new Request(url, { method, body: formData });
  const bytes = new Uint8Array(await probe.arrayBuffer());
  const headers = await agent.signRequest({ method, url, body: bytes });
  await fetch(url, { method, headers, body: bytes }); // + probe.headers.get("content-type")
  
  Signing JSON bodies needs none of this — pass the JSON string straight to signRequest.
• Auth resolution in your request layer: an explicit key → bearer; else a stored/env key → bearer; else sign with the did:key; --anonymous → no auth.
• Tests: point $AFAUTH_HOME at a temp dir so signing never touches a developer’s real ~/.afauth.

​

Next steps