Files
iam/internal/oidc/sendverificationcode.go
zeekay f5285f1fd0 otp: design the sign-in email
The link and code went out as one paragraph of plain text, which cloud's
notify sent as an HTML body, so its line breaks collapsed and the link
was not a link.  The sign-in mail is now a page: the org's mark, "Sign
in to <org>", a Sign in button to the callback with the code in its
fragment, the code large in mono, the expiry, and the line for someone
who did not ask.  Message.HTML carries it; Body carries the same words
as plain text, sent as its multipart alternative.  Light by inline
style, dark by prefers-color-scheme and Outlook's data-ogsc/ogsb.

The brand is the org row: DisplayName names it, WebsiteUrl is its site,
and the mark is <site>/email/mark.png, a PNG every client shows.  No
brand is written here.  IssueLink takes the organization for that.

testdata/signin.html pins the mail whole; -update rewrites it.
2026-10-22 18:50:22 -07:00

168 lines
6.8 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
package oidc
import (
"errors"
"net/url"
"strings"
"github.com/hanzoai/orm"
"github.com/zap-proto/zip"
"github.com/hanzoai/iam/internal/httpx"
"github.com/hanzoai/iam/internal/otp"
"github.com/hanzoai/iam/pkg/schema"
"github.com/hanzoai/iam/pkg/store"
)
// The native OTP send: POST /v1/iam/verification-codes. It mirrors
// the v1 the legacy surface SendVerificationCode contract (controllers/verification.go): the
// request is multipart/form-data (NOT JSON — a HIP-0111 §4 invariant), and the
// response is the casibase {status,msg,data} envelope with an empty data on
// success.
//
// This is an ENDPOINT, not the code itself: validating who may ask, and for which
// application, is all it does. Minting, wording, filing, delivering and spending a
// code live in internal/otp, which the second-factor challenge calls too — so a code
// sent from here and a code sent by a challenge are the same artifact, filed under
// the same key, and either one verifies wherever the other would.
// PathVerificationCodes (canonical.go) is the native OTP-send endpoint.
// sendVerificationCode validates the request and asks otp to get a code to the
// person. The request fields are read via fiber's FormValue — the escape hatch zip
// exposes for form bodies (multipart or urlencoded) — since the typed JSON Bind does
// not apply here. v1 also accepts countryCode/method/checkUser/captchaType; iam
// ignores them (the captcha/forget/MFA flows those drive are not ported), and
// CAPTCHA verification is likewise not enforced — iam models no captcha provider —
// so the code is issued once the destination and application validate.
//
// An email is the designed sign-in mail, a link beside the code and from the
// application's org as its reader knows it (otp.IssueLink), when the request's
// Origin is the origin of one of the application's redirect URIs ([landing]);
// otherwise it is the code alone.
func sendVerificationCode(db orm.DB) zip.Handler {
return func(c *zip.Ctx) error {
ctx := c.Context()
fc := c.Fiber()
dest := fc.FormValue("dest")
typ := fc.FormValue("type")
applicationId := fc.FormValue("applicationId")
// v1 form.VerificationForm.CheckParameter(SendVerifyCode): type + dest
// required, applicationId must be an owner/name id.
if typ == "" {
return httpx.Err(c, "missing parameter: type")
}
if dest == "" {
return httpx.Err(c, "missing parameter: dest")
}
if !strings.Contains(applicationId, "/") {
return httpx.Err(c, "wrong parameter: applicationId")
}
owner, name := splitSub(applicationId)
app, err := store.GetApplicationByName(ctx, db, owner, name)
if err != nil {
return httpx.Err(c, err.Error())
}
if app == nil {
return httpx.Err(c, "the application: "+applicationId+" does not exist")
}
org, err := store.GetOrganizationByName(ctx, db, app.Organization)
if err != nil {
return httpx.Err(c, err.Error())
}
if org == nil {
return httpx.Err(c, "the organization does not exist")
}
// Validate the destination by type and resolve the account it belongs to. The
// resolved account is what BINDS the code — otp.Consume refuses a record minted
// for anybody else — so this is credential material, not metadata. A number is
// accepted as typed: otp.Receiver files it under its digits, so the punctuation
// somebody used here cannot decide whether the code verifies later.
var user *schema.User
var uri string
switch typ {
case otp.Email:
if !isEmailValid(dest) {
return httpx.Err(c, "email is invalid")
}
uri = landing(app, c.Header("Origin"))
// An ambiguous address is treated as NO USER, not reported. This endpoint
// is unauthenticated too, so echoing the resolver would tell a stranger
// which addresses exist — and the endpoint below already handles a nil
// user without saying whether one was found.
if user, err = store.GetUserByEmail(ctx, db, org.Name, dest); err != nil {
if !errors.Is(err, store.ErrEmailAmbiguous) {
return httpx.Err(c, "verification code cannot be sent")
}
user = nil
}
// An account founded into an org of its own is not in the application's
// org. The org it registered in still knows it, and this endpoint and the
// sign-in that authenticates the same address must not disagree about who
// it names — otherwise a code is minted for nobody and the person is told
// nothing.
if user == nil {
if user, err = store.GetSignupByEmail(ctx, db, org.Name, dest); err != nil {
if !errors.Is(err, store.ErrEmailAmbiguous) {
return httpx.Err(c, "verification code cannot be sent")
}
user = nil
}
}
case otp.Phone:
// GetUserByPhone normalizes its argument and refuses to pick between two rows
// carrying one number (ErrPhoneAmbiguous). Returned, not swallowed: a code we
// cannot attribute to one account must not be minted, because the binding is
// what makes it a credential. Without resolving here the SMS arm filed records
// that named nobody and could therefore be spent by nobody.
if user, err = store.GetUserByPhone(ctx, db, org.Name, dest); err != nil {
return httpx.Err(c, err.Error())
}
default:
return httpx.Err(c, "unsupported verification type: "+typ)
}
if err := otp.IssueLink(ctx, db, org, dest, fc.IP(), user, nowFunc(), uri); err != nil {
// Report the real outcome. Answering ok because the code was minted would be
// the same lie one layer down: the send is what the caller asked for.
if errors.Is(err, otp.ErrNoDelivery) || errors.Is(err, otp.ErrTooSoon) {
return httpx.Err(c, err.Error())
}
return httpx.Err(c, "verification code could not be delivered: "+err.Error())
}
return httpx.Ok(c, nil)
}
}
// landing is the URI an emailed sign-in link opens: the first of the application's
// RedirectUris, in its own order, whose origin is exactly origin (scheme, host and
// port), with any fragment cut off. origin is the request's Origin header and must
// be a serialized http or https origin. No Origin, a malformed one, or one no
// registered URI is at answers "", and the email carries no link.
//
// Only a registered URI is ever returned, so a forged Origin can at most choose
// among the application's own callbacks. Host, Referer and X-Forwarded-* are never
// read: the Origin header is the one statement of which page asked.
func landing(app *schema.Application, origin string) string {
o, err := url.Parse(origin)
if err != nil || (o.Scheme != "http" && o.Scheme != "https") || o.Host == "" || o.Scheme+"://"+o.Host != origin {
return ""
}
for _, raw := range app.RedirectUris {
r, err := url.Parse(raw)
if err != nil || r.Scheme != o.Scheme || r.Host != o.Host {
continue
}
uri, _, _ := strings.Cut(raw, "#")
return uri
}
return ""
}