Files
iam/internal/wallet/verify.go
zeekay 5c9b1d6397 wallet: cap the accounts sign-up creates per address and network
A wallet is a free key, so headless web3 sign-up minted one free account
per key without limit. Cap counts account creations, never sign-ins,
per client address and per IPv4 /24 or IPv6 /64 in a window: default
10 and 50 per 24h, set by IAM_WALLET_CAP_IP, IAM_WALLET_CAP_SUBNET and
IAM_WALLET_CAP_WINDOW (0 = off).

The count is the wallet-signup audit ledger, read and written in the
account's own transaction, so a refusal writes no row and concurrent
creations cannot share a count. Past a bound: 429, Retry-After, code
wallet_signup_capped and the bound in data.

The client address is httpx.Client, the identifier throttle's rule
moved so both read one: CF-Connecting-IP, else the last
X-Forwarded-For hop.
2026-10-26 16:17:31 -07:00

344 lines
14 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
package wallet
import (
"context"
"crypto/sha256"
"encoding/hex"
"errors"
"fmt"
"net/netip"
"strings"
"time"
"github.com/hanzoai/orm"
wc "github.com/luxwallet/connect/go/walletconnect"
"github.com/hanzoai/iam/internal/oidc"
"github.com/hanzoai/iam/pkg/schema"
"github.com/hanzoai/iam/pkg/store"
)
// The chain-agnostic wallet-login core, decomplected from HTTP: the handler
// parses and resolves, this burns, verifies, and resolves the user. It takes no
// zip.Ctx, so it is directly unit-testable and "what the login does" stays
// separate from "how HTTP delivers it".
// ttl is how long a minted challenge stays valid.
const ttl = 10 * time.Minute
// statement is the human line the wallet renders in its signing prompt. It is
// part of the SIGNED message, so changing it changes what wallets display.
const statement = "Sign in to Hanzo. This request will not trigger a blockchain transaction or cost any gas."
// Policy failures. Each is a closed, non-probing message: none reveals whether
// an account exists, only what this caller may do.
var (
errLinked = errors.New("web3: this wallet is already linked to another account")
errNoAccount = errors.New("web3: no account is linked to this wallet")
errNoSignup = errors.New("web3: the account does not exist and sign up is disabled")
errForbidden = errors.New("web3: the user is forbidden to sign in")
errDeleted = errors.New("web3: the user has been deleted")
errRouting = errors.New("web3: missing application or organization")
errMessage = errors.New("web3: malformed login message")
errDomain = errors.New("web3: domain mismatch")
errChain = errors.New("web3: chain mismatch for this nonce")
)
// login is everything the core needs to verify a proof and resolve it to a user.
// The proof itself IS the SDK's own value — the seven attacker-controlled fields
// are never re-declared here, so Go and TypeScript verify the identical value.
type login struct {
// Domain is what site() names for this request: the page's origin when the
// application registers it, else Host. Host is the header-immune c.Host() the
// request arrived on (X-Forwarded-Host is ignored). The burned challenge must
// name one of the two. Host stays acceptable beside a registered Origin
// because a browser sends no Origin on a same-origin GET, so a page that
// reaches IAM through its own host mints a Host-bound challenge and redeems it
// with a POST that does carry Origin.
Domain string
Host string
Proof wc.Proof
Method string // "signup" (default) | "login"
App *schema.Application
Org *schema.Organization
// Session is a caller who is already authenticated AND same-site — the one
// branch carrying ambient authority. nil when anonymous or cross-site.
Session *schema.User
// Client is who is asking (httpx.Client), and Cap the bound on the accounts
// it may create. Neither is read unless this proof would create one.
Client netip.Addr
Cap Cap
}
// supported reports whether a chain family is one this build knows. Per-chain
// verifier readiness is a separate gate; an unverifiable chain fails closed in
// VerifyProof.
//
// It reads schema.WalletChains — the SAME list the login descriptor advertises
// from — so a screen can never offer a chain these endpoints refuse. The names
// are pinned against the luxwallet constants by TestWalletChainsMatchSDK.
func supported(chain wc.Chain) bool {
for _, name := range schema.WalletChains() {
if wc.Chain(name) == chain {
return true
}
}
return false
}
// verify is the one server-side entry point for wallet login. It fails closed at
// every step, and the ORDER is the security property:
//
// 1. Parse the SIGNED message and read the nonce FROM IT — never from the
// request body, or a forged body could desync the nonce from the signature.
// 2. BURN the nonce atomically, BEFORE any crypto, so a captured proof can
// never be replayed even when verification would succeed.
// 3. Re-check the burned row's domain and chain: the nonce is pinned to the
// site it was minted for (site) and the chain it was minted for.
// 4. VerifyProof — address binding, domain, nonce, time window, and the
// per-chain cryptographic check, all in the shared SDK.
// 5. Resolve (chain, VERIFIED address) -> wallet -> user. Identity is the
// verified address, never the client-claimed one.
func verify(ctx context.Context, db orm.DB, in login, now time.Time) (signin, error) {
if in.App == nil || in.Org == nil {
return signin{}, errRouting
}
if !supported(in.Proof.Chain) {
return signin{}, fmt.Errorf("web3: unsupported chain: %s", in.Proof.Chain)
}
// 1. The nonce comes from the SIGNED message.
parsed, err := wc.ParseSiwxMessage(in.Proof.Message)
if err != nil {
return signin{}, errMessage
}
nonce := parsed.Nonce
// 2. Burn first — before crypto.
ch, err := burn(ctx, db, nonce, now)
if err != nil {
return signin{}, err
}
// 3. The challenge pins the site and the chain.
if ch.Domain != in.Domain && ch.Domain != in.Host {
return signin{}, errDomain
}
// Without this the chain label is decorative: a nonce minted for chain A
// could be redeemed with a valid chain-B proof, making the signed "sign in
// with your X account" statement meaningless.
if ch.Chain != "" && ch.Chain != string(in.Proof.Chain) {
return signin{}, errChain
}
// 4. Cryptographic verification, in the SAME SDK the TypeScript client runs.
// Expect the domain from the BURNED ROW, not the request.
res := wc.VerifyProof(in.Proof, wc.Expectation{
Domain: ch.Domain,
Nonce: nonce,
ClockSkew: wc.DefaultClockSkew,
Now: now,
})
if !res.OK {
// res.Reason is a stable machine code (bad-signature, expired, …).
return signin{}, fmt.Errorf("web3: verification failed: %s", res.Reason)
}
// 5. Identity is the VERIFIED address, canonicalized.
address := canonical(in.Proof.Chain, res.Address)
return resolve(ctx, db, in, address, now)
}
// resolve turns a verified (chain, address) into the user it signs in as:
// an existing link logs that user in; no link + a same-site session links the
// wallet to that identity; no link + signup logs a fresh wallet user in, as the
// Cap allows. Only the last two BIND, and only those report a bound wallet.
func resolve(ctx context.Context, db orm.DB, in login, address string, now time.Time) (signin, error) {
chain := string(in.Proof.Chain)
// The wallet lookup is scoped to the application's organization — the accounts
// that live there or registered there — a resolved server value, never a
// request parameter.
w, err := link(ctx, db, in.App.Organization, chain, address)
if err != nil {
return signin{}, err
}
var user *schema.User
var bound *schema.Wallet
if w != nil {
if user, err = store.GetUserByName(ctx, db, w.Owner, w.User); err != nil {
return signin{}, err
}
// A dangling link (the user was deleted under it) is treated as
// not-linked so the signup/login policy below decides, rather than 500.
}
if user == nil {
if err := db.RunInTransaction(ctx, func(tx orm.DB) error {
// One wallet, one identity — globally. orm has no UNIQUE constraint,
// so this probe and the bind below MUST share one transaction or a
// concurrent double-link slips through. It runs BEFORE provisioning
// so a wallet linked elsewhere can never leave an orphan user row.
other, err := anywhere(ctx, tx, chain, address)
if err != nil {
return err
}
if other != nil {
return errLinked
}
switch {
case in.Session != nil:
// Link a new wallet to an existing identity. We NEVER link by
// address alone across identities — that would let a wallet
// hijack a social/password account.
user = in.Session
case in.Method == "login":
return errNoAccount
case !in.App.EnableSignUp || !oidc.Registers(in.App, in.App.Organization):
// The SAME rule the password and provider doors keep (oidc.Registers):
// never a reserved org — an application row owned by a reserved org
// (admin/built-in/service) with EnableSignUp set would otherwise let
// an unauthenticated, wallet-signed POST mint a user under a platform
// org, and a user under "admin" IS a SuperAdmin — and never the org
// of a shared application that founds nothing, whose org is the
// operator's. Folded into the EXISTING case, not a new one, so the
// refusal stays byte-identical to "signup is off here" and a prober
// cannot distinguish the two (no authority oracle).
return errNoSignup
default:
// A creation, so the Cap is asked first and the ledger row is
// written with the account: a refused one writes nothing.
if err := admit(ctx, tx, in.Cap, in.Client, now); err != nil {
return err
}
if user, err = provision(ctx, tx, in, address, now); err != nil {
return err
}
if err := file(ctx, tx, in, user); err != nil {
return err
}
}
fresh := &schema.Wallet{
Owner: user.Owner,
User: user.Name,
Chain: chain,
Address: address,
Scheme: string(in.Proof.Scheme),
PublicKey: in.Proof.PublicKey,
CreatedTime: stamp(now),
}
if err := bind(ctx, tx, fresh); err != nil {
return err
}
// Set only on the committed path: the transaction returns nil here,
// so a later failure inside it cannot leave a link reported that was
// rolled back.
bound = fresh
return nil
}); err != nil {
return signin{}, err
}
}
if user.IsForbidden {
return signin{}, errForbidden
}
if user.IsDeleted {
return signin{}, errDeleted
}
return signin{user: user, bound: bound}, nil
}
// signin is what a verified proof resolved to: the account it signs in as and,
// only when THIS proof created the binding, the wallet that was bound.
//
// The second field is here because LINKING is the event worth reacting to and
// signing in is not. A wallet already on file signs its holder in and changes
// nothing, so anything that records a link — the on-chain anchor — has to be
// able to tell the two apart, and asking "is there a row" afterwards cannot,
// because the row is there either way. It carries the wallet rather than a flag
// so the reader gets the CANONICAL address the verifier settled on, never the
// client-claimed spelling.
type signin struct {
user *schema.User
bound *schema.Wallet
}
// provision creates a fresh user for a first-seen wallet. No password is set —
// this is a wallet-only identity; the user can add email/password later. At an
// application that founds each new account an org of its own, the wallet's gets
// one too, and the link is then bound where the account lives.
func provision(ctx context.Context, db orm.DB, in login, address string, now time.Time) (*schema.User, error) {
// Machine-generated, but still checked against THE username rule: a generated
// name is only conformant while whatever generates it stays conformant, and this
// path writes through orm directly rather than users.Create, so nothing else
// would notice if a new chain's identifier stopped fitting.
uname, err := schema.Username(name(in.Proof.Chain, address))
if err != nil {
return nil, err
}
u := orm.New[schema.User](db)
u.Owner = in.App.Organization
u.Name = uname
u.Type = "normal-user"
u.DisplayName = fmt.Sprintf("%s:%s", in.Proof.Chain, short(address))
u.Avatar = in.Org.DefaultAvatar
u.SignupApplication = in.App.Name
u.CreatedTime = stamp(now)
u.UpdatedTime = u.CreatedTime
// Subject is the (owner,name) natural key, NOT a minted UUID — this bypasses the
// canonical users.Create path, so it diverges from the "sub is always a UUID"
// invariant (F-A1). It is NOT an impersonation vector: owner is the app's own org
// and name is the deterministic wallet digest (see name()), both server-set with no
// client input, and store.GetUserById fails closed on an empty/duplicate Id — an
// Id="" row is resolved ONLY by its owner/name, never captured by a UUID subject.
// Minting a UUID here would change the token sub for wallet re-login, so it is
// deferred to a deliberate migration rather than folded into this security rework.
u.SetId(u.Owner + "/" + u.Name)
if err := u.CreateCtx(ctx); err != nil {
return nil, err
}
return oidc.Charter(ctx, db, in.App, u)
}
// name is the bounded, stable, collision-resistant username of a wallet user.
// user.Name is the natural key (varchar(100) in v1), and a raw "<chain>_<address>"
// overflows it on long-address chains (a Cardano addr1 runs ~103 chars), so the
// address is digested. It is chain-qualified, so one address on two chains is
// two identities. The full address stays the source of truth on the wallet row.
func name(chain wc.Chain, address string) string {
sum := sha256.Sum256([]byte(string(chain) + ":" + address))
return fmt.Sprintf("wallet_%s_%s", chain, hex.EncodeToString(sum[:8]))
}
// short renders an address for display: 0x1234…cdef.
func short(a string) string {
if len(a) <= 12 {
return a
}
return a[:6] + "..." + a[len(a)-4:]
}
// canonical normalizes a VERIFIED address into the single form used as an
// identity key, so whitespace/case variants of one key resolve to one identity.
// The SDK's verifier accepts those variants (the crypto binding holds for all of
// them), so without this one key could mint N identities. EVM addresses are
// case-insensitive hex -> lowercase; base58/bech32/SS58 chains are
// case-SENSITIVE, so they are only trimmed.
func canonical(chain wc.Chain, address string) string {
a := strings.TrimSpace(address)
if chain == wc.ChainEVM {
a = strings.ToLower(a)
}
return a
}
// stamp is the one timestamp format for v1-compatible string times.
func stamp(now time.Time) string { return now.UTC().Format(time.RFC3339) }