mirror of
https://github.com/hanzoai/iam.git
synced 2026-11-19 18:37:16 +00:00
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.
344 lines
14 KiB
Go
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) }
|