Files
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

250 lines
10 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
// Package httpx is the shared HTTP layer for the IAM v2 handlers: the
// the legacy surface-compatible Response envelope that the @hanzo/iam SDK and the hanzo.id
// portal consume, plus small helpers over zip.Ctx. Every native JSON
// endpoint (get-app-login, login, signup) returns this shape; the OIDC
// endpoints (token/authorize/userinfo) use their own RFC 6749 shapes.
package httpx
import (
"crypto/subtle"
"encoding/base64"
"net/netip"
"os"
"strings"
"github.com/zap-proto/zip"
)
// Response is the the legacy surface-compatible envelope. status is "ok" or
// "error", and it stays the field an SDK branches on for the REASON a call
// failed. The HTTP status says whether it failed at all, and the two agree:
// a refusal is a 4xx carrying status:"error".
//
// It used to ride on a 200. That inherited the upstream's habit of using the
// envelope as the only channel, and it made every refusal indistinguishable from
// a success to the layer that checks first — `res.ok` in fetch,
// `raise_for_status()` in requests, `StatusCode/100 == 2` in Go. A signup that was
// refused therefore READ as a signup that had happened, and the caller went on to
// the next step of an onboarding that did not exist.
type Response struct {
Status string `json:"status"`
Msg string `json:"msg"`
// Code is a STABLE machine-readable reason, where the human `msg` is
// deliberately generic. `msg` is prose for a person and several distinct causes
// legitimately share one sentence; a caller that must BRANCH on the cause — or
// tell its own user which of them happened — cannot parse prose. Optional, so
// every existing envelope is byte-identical and no SDK changes.
Code string `json:"code,omitempty"`
Sub string `json:"sub,omitempty"`
Name string `json:"name,omitempty"`
Data any `json:"data"`
Data2 any `json:"data2,omitempty"`
Data3 any `json:"data3,omitempty"`
}
// ServiceToken returns the configured unified service token — the first non-empty
// of HANZO_API_KEY / KMS_SERVICE_TOKEN / IAM_SERVICE_TOKEN — or "" (fail closed).
// This is the ONE system credential the service-token surfaces (operator bootstrap
// and admin provisioning) authenticate against.
func ServiceToken() string {
for _, key := range []string{"HANZO_API_KEY", "KMS_SERVICE_TOKEN", "IAM_SERVICE_TOKEN"} {
if v := strings.TrimSpace(os.Getenv(key)); v != "" {
return v
}
}
return ""
}
// ServiceAuth reports whether an `Authorization` header VALUE carries the unified
// service token, compared in constant time. An unset expected token, or any
// mismatch, is false — fail closed: no token configured means no service surface.
//
// It takes the header rather than the request because a TYPED op never sees a
// *zip.Ctx: the credential arrives on its input, declared `header:"Authorization"`,
// and the check has to run on that value. So this is the ONE implementation and
// ServiceTokenAuth is the same check on a raw handler's request — the same split
// as Good/Bad against Ok/Fail below, a value and a place.
func ServiceAuth(h string) bool {
expected := ServiceToken()
if expected == "" {
return false
}
got := token(h)
return got != "" && subtle.ConstantTimeCompare([]byte(got), []byte(expected)) == 1
}
// ServiceTokenAuth reports whether the request carries the unified service token as
// a Bearer credential.
func ServiceTokenAuth(c *zip.Ctx) bool { return ServiceAuth(c.Header("Authorization")) }
// Answer is a Response together with the status it rides on — the envelope as a
// VALUE, for a handler that returns its reply instead of writing it.
//
// A typed op is a function, so its answer has to BE a value: zip renders what the
// handler returns and there is no *zip.Ctx to write through. The status has to
// ride with it because this envelope's whole contract is that the two agree — a
// refusal is a 4xx carrying status:"error" — and a typed op that returned a bare
// Response would answer every refusal 200 and break exactly that.
//
// The wire shape is Response's and only Response's: the embedding promotes its
// fields, `code` is unexported, so an Answer and the Response inside it marshal
// to the same bytes. One envelope, two ways of holding it, no second shape to
// keep in sync.
//
// It is a distinct type rather than a method on Response because zip reads
// [zip.StatusCoder] off the value an op returns and refuses any status the op did
// not declare with zip.WithStatus. Response is already returned by typed ops that
// declare none, so teaching Response to state a status would make every one of
// them answer a status zip then refuses.
type Answer struct {
Response
code int
}
// StatusCode is [zip.StatusCoder]: the status this answer rides on. Zero means
// the answer never named one, and 200 is what an unnamed answer has always been.
func (a *Answer) StatusCode() int {
if a.code == 0 {
return 200
}
return a.code
}
// Good is the 200 { status:"ok", data } envelope. The success half of the pair,
// as a value.
func Good(data any, more ...any) *Answer {
a := &Answer{Response: Response{Status: "ok", Data: data}, code: 200}
if len(more) > 0 {
a.Data2 = more[0]
}
return a
}
// Bad is the { status:"error", msg, code } envelope under the status that
// matches it. The refusal half of the pair, as a value.
func Bad(status int, msg, code string) *Answer {
return &Answer{Response: Response{Status: "error", Msg: msg, Code: code}, code: status}
}
// Ok writes 200 { status:"ok", data }.
func Ok(c *zip.Ctx, data any, more ...any) error {
return write(c, Good(data, more...))
}
// Fail writes { status:"error", msg, code } under an HTTP status that MATCHES it.
// ONE implementation writes the error envelope; everything below names a status
// for it, and nothing else in this package may write one.
func Fail(c *zip.Ctx, status int, msg, code string) error {
return write(c, Bad(status, msg, code))
}
// write sends an Answer through a raw handler's Ctx. Unexported: a typed op
// RETURNS its answer and never needs this, so the only callers are the two
// writers above — which is what makes Good/Bad the one place each variant of the
// envelope is built, whether it is returned or written.
func write(c *zip.Ctx, a *Answer) error {
return c.JSON(a.StatusCode(), a.Response)
}
// Err writes a refusal the CALLER can act on: bad input, a credential we would
// not take, a name already spoken for. 400 is the honest default for this
// surface — these are validation and authentication failures on the native
// endpoints, and the
// caller is the one holding the thing that was wrong. A handler that knows better
// says so by calling Fail with the status it means.
func Err(c *zip.Ctx, msg string) error {
return ErrCode(c, msg, "")
}
// ErrCode is Err carrying a machine-readable reason alongside the human message.
func ErrCode(c *zip.Ctx, msg, code string) error {
return Fail(c, 400, msg, code)
}
// A note on 401. Several refusals here are authentication failures ("please sign
// in first", CodeLoginRequired) and 401 is their honest status. They are NOT
// spelled that way, deliberately: these handlers sit on the PRE-GUARD group, and
// the Guard's own refusal is a 401 too, so a handler that answered 401 would
// become indistinguishable from a route that was never public — which is exactly
// what internal/authz's public-route tests assert on. Separating those two needs
// the Guard to be told apart from a handler by something other than the status,
// which is a change to the authz surface and not to this envelope. Until then the
// machine-readable `code` carries the distinction, which is what it is for.
// ClientIP is the address an audit row records for a request: X-Forwarded-For as
// the edge delivered it, which is what the typed handlers bind for their rows,
// else the peer the connection came from.
func ClientIP(c *zip.Ctx) string {
if f := c.Header("X-Forwarded-For"); f != "" {
return f
}
return c.Fiber().IP()
}
// Client is who is asking, for a decision that counts requests by it: the
// address the edge saw connect (CF-Connecting-IP), else the last
// X-Forwarded-For hop, which the nearest proxy wrote. Hops before it are the
// client's own words and are never read. Anything that is not an address is
// the zero Addr, which every such request shares.
func Client(connecting, forwarded string) netip.Addr {
raw := strings.TrimSpace(connecting)
if raw == "" {
hops := strings.Split(forwarded, ",")
raw = strings.TrimSpace(hops[len(hops)-1])
}
ip, err := netip.ParseAddr(raw)
if err != nil {
return netip.Addr{}
}
return ip.Unmap()
}
// Bearer returns the token from an `Authorization: Bearer <token>` header, or "".
func Bearer(c *zip.Ctx) string { return token(c.Header("Authorization")) }
// BearerValue is Bearer for a caller holding the header VALUE rather than the
// request — a typed handler, which zip binds headers into and hands no *Ctx.
func BearerValue(authorization string) string { return token(authorization) }
// token is the credential an `Authorization: Bearer <token>` header VALUE carries,
// or "". The parse lives here once, for the request half and the value half alike.
func token(h string) string {
const p = "Bearer "
if len(h) > len(p) && h[:len(p)] == p {
return h[len(p):]
}
return ""
}
// Basic returns the (id, secret) an `Authorization: Basic <base64>` header carries,
// and whether it carried one — RFC 7617: base64 of "<id>:<secret>", split on the
// FIRST colon so a secret may contain one. This is the ONE Basic parser; a caller
// bound by RFC 6749 §2.3.1 (client_secret_basic, whose halves are form-urlencoded
// before the base64) form-decodes the two values afterwards.
func Basic(c *zip.Ctx) (id, secret string, ok bool) {
const p = "Basic "
h := c.Header("Authorization")
if len(h) <= len(p) || !strings.EqualFold(h[:len(p)], p) {
return "", "", false
}
raw, err := base64.StdEncoding.DecodeString(strings.TrimSpace(h[len(p):]))
if err != nil {
return "", "", false
}
id, secret, found := strings.Cut(string(raw), ":")
if !found {
return "", "", false
}
return id, secret, true
}
// The request host is read through the ONE header-immune accessor, zip.Ctx.Host()
// — the same seam the OIDC issuer resolver uses. It ignores X-Forwarded-Host (zip
// has no trusted-proxy knob), so the brand host a client authenticates to cannot
// be spoofed by a request header. There is deliberately no EffectiveHost helper
// here: a second accessor that honored X-Forwarded-Host would reopen that spoof.