Files
iam/pkg/store/store.go

1142 lines
45 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
// Package store is the IAM object layer: thin, typed reads over hanzoai/orm
// against the Phase-1 entities. It replaces the v1 xorm ormer.Engine fluent
// calls with orm.TypedQuery, so handlers depend on named operations
// (GetApplicationByClientId, GetProvider, …) rather than a query builder.
//
// Every function takes a context and an orm.DB — one storage abstraction,
// backend-agnostic (sqlite / hanzoai/sql / hanzoai/datastore).
package store
import (
"context"
"errors"
"fmt"
"strings"
"time"
policy "github.com/hanzoai/authz"
"github.com/hanzoai/orm"
"github.com/hanzoai/iam/internal/keyring"
"github.com/hanzoai/iam/pkg/schema"
)
// GetApplicationByClientId resolves an OAuth2/OIDC client by its clientId,
// DETERMINISTICALLY: among any rows carrying clientId it returns the platform-
// preferred one — a reserved signing owner (admin/built-in) outranks a tenant, and
// within a tier the lexically-least (owner,name) wins. clientId is globally unique
// by the applications create/update guard, so this normally has exactly one
// candidate; the ordering is defense-in-depth that makes a stray duplicate resolve
// to the PLATFORM row rather than whichever row the storage engine's heap happened
// to return first. A First() with no ORDER BY was the collidable-mint vector (safe
// on dev sqlite by rowid, UNSPECIFIED on Postgres): a tenant that registered a row
// with a mint-allow-listed clientId could have its row win resolution and
// authenticate a mint. This can no longer happen — the platform row always wins,
// and the owner-pin on the mint/capability gates denies a non-signing owner even if
// it did. Returns (nil, nil) when no application matches.
func GetApplicationByClientId(ctx context.Context, db orm.DB, clientId string) (*schema.Application, error) {
apps, err := ListApplicationsByClientId(ctx, db, clientId)
if err != nil {
return nil, err
}
return preferredApp(apps), nil
}
// ListApplicationsByClientId returns EVERY application row carrying clientId — the
// ONE place "which applications share this clientId" is answered. It backs both the
// deterministic single resolve above and the global-uniqueness guard the
// applications create/update path enforces: a JSON-document store has no per-field
// column to hang a DB UNIQUE index on, so clientId uniqueness is enforced at the
// write, exactly as the (owner,name) natural key already is. Returns nil when
// clientId is empty or unmatched.
func ListApplicationsByClientId(ctx context.Context, db orm.DB, clientId string) ([]*schema.Application, error) {
if clientId == "" {
return nil, nil
}
return orm.TypedQuery[schema.Application](db).Filter("ClientId=", clientId).GetAll(ctx)
}
// ListApplicationsByOwner returns every application row a given organization owns.
// The boot-time signing check reads it for the reserved owner: the certs those
// applications name are the ones this process must be able to sign with, so a
// mount that omits one is a partial deployment the pod must refuse rather than
// serve. Scoped by owner because a tenant's applications name a tenant's own
// certs and must never enter that decision.
func ListApplicationsByOwner(ctx context.Context, db orm.DB, owner string) ([]*schema.Application, error) {
if owner == "" {
return nil, nil
}
return orm.TypedQuery[schema.Application](db).Filter("Owner=", owner).GetAll(ctx)
}
// preferredApp deterministically selects the platform-preferred application among
// rows sharing a clientId (see morePreferredApp for the total order). Returns nil
// for an empty set, preserving GetApplicationByClientId's (nil, nil) not-found
// contract.
func preferredApp(apps []*schema.Application) *schema.Application {
var best *schema.Application
for _, a := range apps {
if a == nil {
continue
}
if best == nil || morePreferredApp(a, best) {
best = a
}
}
return best
}
// morePreferredApp reports whether a outranks b for clientId resolution: a reserved
// signing owner (admin/built-in) outranks a non-reserved one; within the same tier
// the lexically-least (owner,name) wins. The order is total and independent of
// storage/heap order, so resolution is deterministic on every backend.
func morePreferredApp(a, b *schema.Application) bool {
if sa, sb := policy.IsSigningOwner(a.Owner), policy.IsSigningOwner(b.Owner); sa != sb {
return sa
}
return a.Owner+"/"+a.Name < b.Owner+"/"+b.Name
}
// GetApplicationByName resolves an application by (owner, name).
func GetApplicationByName(_ context.Context, db orm.DB, owner, name string) (*schema.Application, error) {
app, err := orm.TypedQuery[schema.Application](db).
Filter("Owner=", owner).Filter("Name=", name).First()
if err == orm.ErrNotFound {
return nil, nil
}
return app, err
}
// GetApplicationNamed resolves an application from a NAME ALONE — for the callers
// that hold a name and no owner, which is what a User's SignupApplication is.
//
// A name is not the whole key, so those callers used to supply the owner they
// assumed: "admin". Applications are NOT all platform-owned — a tenant registers
// its own (federationOrgAllowed distinguishes the two cases, and the red-team
// suite exercises a tenant-owned app) — so that lookup missed the row entirely
// for every tenant-registered app and its caller read the miss as policy.
//
// Among rows sharing a name the platform-preferred one wins, by the SAME total
// order clientId resolution uses (morePreferredApp), so this is deterministic on
// every backend and can never resolve a tenant row ahead of a platform one.
// Returns (nil, nil) when the name is empty or unmatched.
func GetApplicationNamed(ctx context.Context, db orm.DB, name string) (*schema.Application, error) {
if name == "" {
return nil, nil
}
apps, err := orm.TypedQuery[schema.Application](db).Filter("Name=", name).GetAll(ctx)
if err != nil {
return nil, err
}
return preferredApp(apps), nil
}
// NameHeldElsewhere reports whether an application of an owner other than owner is
// named name.
//
// A name must name one application. An account records the application that
// registered it by name alone (SignupApplication), sign-in reaches a person through
// the org that name resolves to, and GetApplicationNamed settles a shared name by
// preferring the platform's row. A second row under a name would therefore file its
// registrations under the first row's org. Every write that creates an application
// asks this first and refuses a name that is held.
func NameHeldElsewhere(ctx context.Context, db orm.DB, owner, name string) (bool, error) {
apps, err := orm.TypedQuery[schema.Application](db).Filter("Name=", name).GetAll(ctx)
if err != nil && err != orm.ErrNotFound {
return false, err
}
for _, a := range apps {
if a != nil && a.Owner != owner {
return true, nil
}
}
return false, nil
}
// An account's wallet reads live in wallet.go — HasWallet, WalletsOf, WalletRefs
// and DetachWallet together, so "what can this person sign in as" has one home.
// GetUserByName resolves a user by (owner, name) — owner is the organization.
// Returns (nil, nil) when absent.
//
// Case does not distinguish principals. New names are normalized to lowercase at
// creation (schema.Username), but rows written before that rule are stored as they
// arrived, and renaming them would move real principals — so the RESOLUTION
// tolerates case instead of the data being rewritten. Three indexed lookups,
// cheapest first: the exact name, then the lower-cased name (between them they
// answer every all-lowercase row, which is all of them going forward), then the
// NameKey (schema.Fold) for a legacy mixed-case row, which reads at most two rows
// of the org, never the org.
//
// It FAILS CLOSED when the folding is ambiguous — the same rule GetUserById
// applies to a duplicated subject. If "Alice" and "ALICE" both exist, "alice"
// names neither of them in particular, and answering with the storage engine's
// arbitrary first row would let whoever registered the second one be resolved as
// the first. An exact match always wins, so a row that is spelled the way it was
// asked for is never subject to this.
func GetUserByName(ctx context.Context, db orm.DB, owner, name string) (*schema.User, error) {
u, err := orm.TypedQuery[schema.User](db).Filter("Owner=", owner).Filter("Name=", name).First()
if err == nil {
return u, nil
}
if err != orm.ErrNotFound {
return nil, err
}
folded := strings.ToLower(strings.TrimSpace(name))
if folded == "" {
return nil, nil
}
if folded != name {
u, err := orm.TypedQuery[schema.User](db).Filter("Owner=", owner).Filter("Name=", folded).First()
if err == nil {
return u, nil
}
if err != orm.ErrNotFound {
return nil, err
}
}
// The rest of the fold is an indexed equality on NameKey (schema.Fold), not a
// read of the organization: two rows are enough to know the name is ambiguous.
us, err := orm.TypedQuery[schema.User](db).Filter("Owner=", owner).
Filter("NameKey=", schema.Fold(folded)).Limit(2).GetAll(ctx)
if err != nil && !errors.Is(err, orm.ErrNotFound) {
return nil, err
}
var match *schema.User
for _, cand := range us {
if !strings.EqualFold(cand.Name, folded) {
continue
}
if match != nil {
return nil, fmt.Errorf("store: %q and %q in organization %q both fold to %q — ambiguous username", match.Name, cand.Name, owner, folded)
}
match = cand
}
return match, nil
}
// GetUserById resolves a user by its stable opaque Id — the UUID the OIDC `sub`
// carries (schema.User.Id). Filters on the persisted "id" field, which the
// domain Id dominates over the embedded orm storage id, so the value matched is
// the UUID, never the (owner,name) key. Returns (nil, nil) when id is empty or
// unmatched (a pre-cutover user with no Id has "" here and is never matched by a
// non-empty subject).
//
// It FAILS CLOSED on multiplicity: the store has no DB UNIQUE index on Id, so if two
// rows ever shared one UUID (a broken invariant — Id is the OIDC `sub` and the authz
// principal key), returning the storage engine's arbitrary First() would let an
// attacker who planted a colliding row be resolved AS a victim. More than one match
// is therefore an error, never a silently-chosen row.
func GetUserById(ctx context.Context, db orm.DB, id string) (*schema.User, error) {
if id == "" {
return nil, nil
}
us, err := orm.TypedQuery[schema.User](db).Filter("Id=", id).GetAll(ctx)
if err != nil {
return nil, err
}
switch len(us) {
case 0:
return nil, nil
case 1:
return us[0], nil
default:
return nil, fmt.Errorf("store: %d users share id %q — ambiguous subject", len(us), id)
}
}
// GetUserByExternalId resolves a user by the externalId its tenant filed it
// under, CONFINED to owner — the id an operator keys a member by in its own
// directory, and the value as() accepts beside the stable subject. externalId is
// unique only within a tenant, so owner is half the question; a cross-tenant
// match cannot arise. Returns (nil, nil) when empty or unmatched, and FAILS CLOSED
// on multiplicity: two rows sharing one externalId in an org name neither in
// particular, so answering with the storage engine's arbitrary first row would let
// whoever registered the second be resolved as the first — the same refusal
// GetUserById makes for a duplicated subject.
func GetUserByExternalId(ctx context.Context, db orm.DB, owner, externalId string) (*schema.User, error) {
if owner == "" || externalId == "" {
return nil, nil
}
us, err := orm.TypedQuery[schema.User](db).Filter("Owner=", owner).Filter("ExternalId=", externalId).GetAll(ctx)
if err != nil {
return nil, err
}
switch len(us) {
case 0:
return nil, nil
case 1:
return us[0], nil
default:
return nil, fmt.Errorf("store: %d users in organization %q share externalId %q — ambiguous", len(us), owner, externalId)
}
}
// GetUserBySubject resolves the user a token's `sub` names — the ONE place the
// subject→user mapping lives, shared by userinfo, get-account, token exchange,
// and the authz principal, so `sub` is decoded the same way everywhere. The
// discriminator is deterministic and matches how a `sub` is MINTED (subjectOf):
// a stable opaque UUID carries no "/" and resolves by Id; an "owner/name" subject
// (a pre-cutover user with no Id, or a machine token's app identity) resolves by
// its natural key. Returns (nil, nil) when no user matches — a machine token's
// app-id subject, or a since-deleted user — the callers fail closed on nil.
func GetUserBySubject(ctx context.Context, db orm.DB, sub string) (*schema.User, error) {
if sub == "" {
return nil, nil
}
if owner, name, hasSlash := strings.Cut(sub, "/"); hasSlash {
if owner == "" || name == "" {
return nil, nil
}
return GetUserByName(ctx, db, owner, name)
}
return GetUserById(ctx, db, sub)
}
// ErrEmailAmbiguous reports that an email address identifies more than one
// account in an org, so it identifies nobody. Returned instead of a user, on
// purpose — the same refusal [GetUserByPhone] makes, for the same reason.
var ErrEmailAmbiguous = errors.New("email address matches more than one account")
// NormalizeEmail reduces an email address to the ONE form this system stores and
// compares: trimmed, and lowercase throughout.
//
// Lowercasing the LOCAL part as well as the domain is a deliberate choice, and it
// is the choice already made everywhere an address is written — signup and both
// IdP readers each lowered the whole thing before this function existed. RFC 5321
// permits a local part to be case-sensitive; no mail provider anyone signs up
// with treats it that way, and a system that stores Alice@x and alice@x as two
// accounts hands one person two identities and the other person's address to
// nobody.
//
// Applying it on WRITE and on READ is what makes one address one value. Applied
// on only one side it is a lookup that silently never matches: signup lowered on
// the way in while [GetUserByEmail] compared the raw spelling, so anyone who
// capitalized a letter of their own address created an account and was then told
// "the username or password is incorrect" for the password they had just chosen —
// forever, and with no way to tell why.
func NormalizeEmail(s string) string {
return strings.ToLower(strings.TrimSpace(s))
}
// GetUserByEmail resolves a user by (owner, email) — the email-login identifier.
//
// It FAILS CLOSED on ambiguity for the same reason [GetUserByPhone] does: the
// document store hangs no per-field UNIQUE constraint, so two rows in one org can
// carry one address, and a `.First()` would hand back an arbitrary one of them for
// the caller to authenticate somebody against. Which row that is is not even
// stable — the query carries no ORDER BY, so it is whatever the index yields. An
// address that names two accounts names none.
func GetUserByEmail(ctx context.Context, db orm.DB, owner, email string) (*schema.User, error) {
email = NormalizeEmail(email)
if email == "" {
return nil, nil
}
// Two, not one: enough to detect a collision, bounded so an address shared by
// many rows cannot pull them all into memory.
us, err := orm.TypedQuery[schema.User](db).Filter("Owner=", owner).Filter("Email=", email).Limit(2).GetAll(ctx)
if err == orm.ErrNotFound {
return nil, nil
}
if err != nil {
return nil, err
}
switch len(us) {
case 0:
return nil, nil
case 1:
return us[0], nil
default:
return nil, ErrEmailAmbiguous
}
}
// GetSignupByEmail resolves an account registered in org, by the address it
// registered with: a row whose [schema.User.SignupApplication] names an application
// of org, carrying email.
//
// It exists because the org an account is registered in is not the tenant the
// person works in. An application that founds an org per person has its accounts
// spread across every org it founded, so scoping sign-in to the registration org
// resolves nobody; this is the scope that matches the population.
//
// The scope is the ORG, not the one application, because an org's applications
// are one front door with several entrances. hanzo.ai, the console, the CLI and
// chat are each their own client of org hanzo, and a person who registered at one
// of them is the same person at every other: keyed by the application, they could
// not sign in anywhere but where they started, and a social sign-in anywhere else
// gave them a second account and a second org. Usernames are unique per org for
// the same reason — the org is the registration namespace.
//
// It is still NARROWER than a cross-org lookup by address, which is a different
// thing and stays refused: it reads only rows some application of org registered,
// so another org's registrations — and seeded or imported rows, which carry no
// SignupApplication at all — are unreachable through it. An empty org therefore
// matches nothing rather than everything.
//
// Ambiguity FAILS CLOSED, as [GetUserByEmail] does and for the same reason: two
// rows carrying one address name nobody, and handing back an arbitrary one is how
// a person is authenticated as somebody else.
func GetSignupByEmail(ctx context.Context, db orm.DB, org, email string) (*schema.User, error) {
email = NormalizeEmail(email)
if org == "" || email == "" {
return nil, nil
}
us, err := orm.TypedQuery[schema.User](db).
Filter("Email=", email).Filter("SignupApplication!=", "").GetAll(ctx)
if err == orm.ErrNotFound {
return nil, nil
}
if err != nil {
return nil, err
}
if us, err = registeredIn(ctx, db, org, us); err != nil {
return nil, err
}
switch len(us) {
case 0:
return nil, nil
case 1:
return us[0], nil
default:
return nil, ErrEmailAmbiguous
}
}
// nameScan bounds the rows the first username read takes from every org at once.
// A name is held by at most one account per registration org, so a fuller read
// means many orgs hold it, and the lookup reads org's own applications instead.
const nameScan = 64
// SignupByName finds the account registered in org that holds a username: a row
// whose [schema.User.SignupApplication] names an application of org, compared by
// [schema.Fold], never a reserved org. held counts the matches, stopping at two, and
// the account is returned only when held is exactly one.
//
// It is [GetSignupByEmail] for the other identifier a sign-in form takes. A
// founding application moves each account it registers into an org of its own, and
// the account keeps its username there, so the registration org — the only org a
// sign-in screen can name — no longer holds that name. This is the reach that finds
// it, under the same scope.
//
// A name two accounts hold (usernames written before they were unique across a
// registration org) names nobody. That is reported as a count, not an error, so a
// sign-in refuses it exactly as it refuses a name nobody holds, and signup reads the
// same count to keep a name from being handed out twice.
func SignupByName(ctx context.Context, db orm.DB, org, name string) (user *schema.User, held int, err error) {
key := schema.Fold(strings.TrimSpace(name))
if org == "" || key == "" {
return nil, 0, nil
}
us, err := orm.TypedQuery[schema.User](db).
Filter("NameKey=", key).Filter("SignupApplication!=", "").Limit(nameScan).GetAll(ctx)
if err == orm.ErrNotFound {
return nil, 0, nil
}
if err != nil {
return nil, 0, err
}
if len(us) >= nameScan {
us, err = registeredNamed(ctx, db, org, key)
} else {
us, err = registeredIn(ctx, db, org, us)
}
if err != nil {
return nil, 0, err
}
switch len(us) {
case 0:
return nil, 0, nil
case 1:
return us[0], 1, nil
default:
return nil, 2, nil
}
}
// registeredNamed reads, application by application, the accounts org's
// applications registered under key, stopping at two: the exact answer for a name
// too many orgs hold to read in one pass, reading nothing another org registered.
func registeredNamed(ctx context.Context, db orm.DB, org, key string) ([]*schema.User, error) {
apps, err := orm.TypedQuery[schema.Application](db).Filter("Organization=", org).GetAll(ctx)
if err != nil && err != orm.ErrNotFound {
return nil, err
}
var out []*schema.User
for _, app := range apps {
us, err := orm.TypedQuery[schema.User](db).
Filter("NameKey=", key).Filter("SignupApplication=", app.Name).Limit(2).GetAll(ctx)
if err != nil && err != orm.ErrNotFound {
return nil, err
}
for _, u := range us {
if !policy.IsReservedOrg(u.Owner) {
out = append(out, u)
}
}
if len(out) >= 2 {
return out[:2], nil
}
}
return out, nil
}
// RegisteredIn reports whether an application of org registered u — the reach
// [GetSignupByEmail] makes by address, asked of an account already in hand.
func RegisteredIn(ctx context.Context, db orm.DB, org string, u *schema.User) (bool, error) {
kept, err := registeredIn(ctx, db, org, []*schema.User{u})
return len(kept) == 1, err
}
// registeredIn keeps the rows an application of org registered.
//
// A reserved owner is never kept. Nothing should ever file a row of the admin org
// under an application's signup, and if something does, this must not be the
// lookup that authenticates it — the reserved orgs hold the SuperAdmin and the
// signing certs.
func registeredIn(ctx context.Context, db orm.DB, org string, us []*schema.User) ([]*schema.User, error) {
orgOf := map[string]string{}
var out []*schema.User
for _, u := range us {
if u == nil || u.SignupApplication == "" || policy.IsReservedOrg(u.Owner) {
continue
}
o, seen := orgOf[u.SignupApplication]
if !seen {
app, err := GetApplicationNamed(ctx, db, u.SignupApplication)
if err != nil {
return nil, err
}
if app != nil {
o = app.Organization
}
orgOf[u.SignupApplication] = o
}
if o == org {
out = append(out, u)
}
}
return out, nil
}
// ErrPhoneAmbiguous reports that a phone number identifies more than one account
// in an org, so it identifies nobody. Returned instead of a user, on purpose —
// see [GetUserByPhone].
var ErrPhoneAmbiguous = errors.New("phone number matches more than one account")
// LooksLikePhone reports whether an identifier is a phone NUMBER rather than an
// address or a username: at least seven digits, and nothing but digits and the
// punctuation people put in phone numbers. Seven is the shortest national subscriber
// number in general use, and requiring it keeps a short numeric username out of the
// phone arm.
//
// It is a SHAPE test, not validation — whether the number names anyone is a lookup's
// business. It lives here, beside [NormalizePhone], because the two answer one
// question together ("is this a number, and what is its canonical form") and every
// caller that normalizes has first to decide whether it should. Sign-in's identifier
// resolution and the verification code's receiver key both ask it, and a second copy
// would be a second answer.
func LooksLikePhone(s string) bool {
digits := 0
for i, r := range s {
switch {
case r >= '0' && r <= '9':
digits++
case r == '+' && i == 0, r == ' ', r == '-', r == '(', r == ')', r == '.':
default:
return false
}
}
return digits >= 7
}
// NormalizePhone reduces a phone number to the ONE form this system stores and
// compares: a leading "+" if the caller gave one, then digits, nothing else.
//
// It exists because a phone typed by a human ("(415) 555-0134", "415-555-0134",
// "+1 415 555 0134") and a phone written by SCIM are the same number in different
// clothes, and an equality lookup cannot see through clothes. Applying it on WRITE
// and on READ is what makes one number one value; applying it on only one side
// would be a lookup that silently never matches.
//
// It deliberately does NOT infer a country code. Guessing "+1" for a bare
// ten-digit string would silently claim a number in one country for a user in
// another, and this function has no idea which country anyone is in. A number
// stored without a country code matches only a number typed without one, which is
// the honest behaviour; making country codes canonical is a data decision for
// whoever collects the number, not a guess for a string function.
func NormalizePhone(s string) string {
s = strings.TrimSpace(s)
if s == "" {
return ""
}
var b strings.Builder
for i, r := range s {
switch {
case r >= '0' && r <= '9':
b.WriteRune(r)
case r == '+' && i == 0:
b.WriteRune(r)
}
}
out := b.String()
if out == "+" {
return ""
}
return out
}
// GetUserByPhone resolves a user by (owner, phone) — the SMS-login identifier.
//
// It FAILS CLOSED on ambiguity, exactly as [GetUserByEmail] does: `schema.User.
// Phone` is indexed but NOT unique, so two rows in one org can carry the same
// number; a `.First()` would then hand back an arbitrary one of them and the
// caller would authenticate a person against somebody else's account. That is the
// same defect class as the cross-org collision the login path already refuses to
// rely on. A number that names two accounts names none, so this returns
// [ErrPhoneAmbiguous] and lets the caller refuse rather than choose.
//
// One ambiguity policy for every identifier is the point. This one was argued
// here first and the address was left picking arbitrarily for a while, which is
// how a rule stated in one place drifts from the rule stated beside it.
//
// phone is normalized here so every caller compares the same way; a blank or
// punctuation-only argument returns (nil, nil) rather than matching the many rows
// that legitimately store no phone at all.
func GetUserByPhone(ctx context.Context, db orm.DB, owner, phone string) (*schema.User, error) {
phone = NormalizePhone(phone)
if phone == "" {
return nil, nil
}
// Two, not one: enough to detect a collision, and bounded so a shared number
// on many rows cannot pull them all into memory.
us, err := orm.TypedQuery[schema.User](db).Filter("Owner=", owner).Filter("Phone=", phone).Limit(2).GetAll(ctx)
if err == orm.ErrNotFound {
return nil, nil
}
if err != nil {
return nil, err
}
switch len(us) {
case 0:
return nil, nil
case 1:
return us[0], nil
default:
return nil, ErrPhoneAmbiguous
}
}
// GetTokenByCode resolves a token row by its authorization code. Returns
// (nil, nil) when no row carries the code.
func GetTokenByCode(_ context.Context, db orm.DB, code string) (*schema.Token, error) {
if code == "" {
return nil, nil
}
t, err := orm.TypedQuery[schema.Token](db).Filter("Code=", code).First()
if err == orm.ErrNotFound {
return nil, nil
}
return t, err
}
// GetCert resolves a signing certificate by (owner, name), with its private key
// filled in from the keyring.
//
// The row carries the key's identity; the key itself is never a column. Filling
// it HERE is what let that change stay invisible to everything downstream: the
// signer, the verifier, the JWKS and the session-cookie key each still read
// cert.PrivateKey off the value the store handed them, and none of them had to
// learn where key material comes from.
func GetCert(_ context.Context, db orm.DB, owner, name string) (*schema.Cert, error) {
c, err := orm.TypedQuery[schema.Cert](db).Filter("Owner=", owner).Filter("Name=", name).First()
if err == orm.ErrNotFound {
return nil, nil
}
keyring.Fill(c)
return c, err
}
// GetTokenByUserCode resolves a pending device authorization by the user_code a
// human transcribes at the verification URI (RFC 8628 §3.3). Returns (nil, nil)
// when no row carries the code.
func GetTokenByUserCode(_ context.Context, db orm.DB, userCode string) (*schema.Token, error) {
if userCode == "" {
return nil, nil
}
t, err := orm.TypedQuery[schema.Token](db).Filter("UserCode=", userCode).First()
if err == orm.ErrNotFound {
return nil, nil
}
return t, err
}
// GetSigningCert resolves a TRUSTED signing certificate by name (the JWKS
// `kid`), searching only the reserved platform owners in order. A cert owned by
// any other org is never returned, so an attacker-created cert with a colliding
// name can neither sign a token iam will verify nor be published in the JWKS.
// Returns (nil, nil) when no trusted cert carries the name.
func GetSigningCert(ctx context.Context, db orm.DB, name string) (*schema.Cert, error) {
if name == "" {
return nil, nil
}
for _, owner := range policy.SigningOwners() {
c, err := GetCert(ctx, db, owner, name)
if err != nil {
return nil, err
}
if c != nil {
return c, nil
}
}
return nil, nil
}
// PersistToken binds a domain Token onto the store and creates it. Used to
// persist an authorization code minted by oidc.MintCode. The id is (owner, name);
// callers set Name to a unique value (e.g. the code) before persisting.
func PersistToken(ctx context.Context, db orm.DB, tok *schema.Token) error {
t := orm.New[schema.Token](db)
model := t.Model
*t = *tok
t.Model = model
name := tok.Name
if name == "" {
name = tok.Code // codes are unique; use as the row name when none given
t.Name = name
}
t.SetId(tok.Owner + "/" + name)
return t.CreateCtx(ctx)
}
// SaveToken read-modify-writes an existing token row (e.g. after redemption:
// CodeIsUsed=true + AccessToken set). It looks the row up by (owner, name),
// copies the mutated fields, and updates in place.
func SaveToken(ctx context.Context, db orm.DB, tok *schema.Token) error {
existing, err := orm.Get[schema.Token](db, tok.Owner+"/"+tok.Name)
if err != nil {
return err
}
model := existing.Model
*existing = *tok
existing.Model = model
return existing.UpdateCtx(ctx)
}
// ListCerts returns every certificate ordered by name, each with its private key
// filled in from the keyring (see GetCert). The JWKS endpoint calls this and
// filters to the token-signing certs it publishes.
func ListCerts(ctx context.Context, db orm.DB) ([]*schema.Cert, error) {
certs, err := orm.TypedQuery[schema.Cert](db).Order("Name").GetAll(ctx)
if err != nil {
return nil, err
}
for _, c := range certs {
keyring.Fill(c)
}
return certs, nil
}
// PlatformSigningCert returns a deterministic trusted signing cert — the
// lexically-least by (owner, name) among the reserved platform owners that both
// carries a private key AND is NAMED by a reserved-owner application. It keys
// deployment-stable secret derivations (the session-cookie MAC), so there is no
// new secret to provision; a tenant cert can never be chosen. Returns (nil, nil)
// when none is available.
//
// The choice is from the REFERENCED set, not from whatever is mounted, because
// the session-cookie MAC must be the SAME cert on every replica or a browser's
// session flaps as the load balancer moves it between them. server.RequireSigning
// requires every cert a reserved-owner application names to be mounted on any
// replica that serves, so the referenced-and-mounted set is identical on every
// booting replica and this choice is therefore identical too. An unreferenced
// cert someone happened to mount — the mounted-but-not-yet-repointed half of a
// staged rotation — is deliberately not a candidate: it would otherwise sort
// ahead of the incumbent on one replica and split the MAC across the fleet.
//
// Falls back to the plain mounted set ONLY when no reserved-owner application
// names any cert — a bare install with no sessions to flap — so a first boot
// still resolves a key.
func PlatformSigningCert(ctx context.Context, db orm.DB) (*schema.Cert, error) {
certs, err := ListCerts(ctx, db)
if err != nil {
return nil, err
}
apps, err := ListApplicationsByOwner(ctx, db, policy.AdminOrg)
if err != nil {
return nil, err
}
referenced := make(map[string]bool, len(apps))
for _, a := range apps {
if a != nil && a.Cert != "" {
referenced[a.Cert] = true
}
}
pick := func(eligible func(*schema.Cert) bool) *schema.Cert {
var best *schema.Cert
for _, c := range certs {
if c == nil || c.PrivateKey == "" || !policy.IsSigningOwner(c.Owner) || c.Delegates() || !eligible(c) {
continue
}
if best == nil || c.Owner+"/"+c.Name < best.Owner+"/"+best.Name {
best = c
}
}
return best
}
if best := pick(func(c *schema.Cert) bool { return referenced[c.Name] }); best != nil {
return best, nil
}
return pick(func(*schema.Cert) bool { return true }), nil
}
// GetTokenByAccessTokenHash resolves a live token row by the SHA-256 hash of a
// presented access token — the userinfo bearer lookup. Because the row is the
// authorization server's memory of the grant, a deleted/rotated row means the
// bearer is revoked, independent of the JWT's own expiry.
func GetTokenByAccessTokenHash(_ context.Context, db orm.DB, hash string) (*schema.Token, error) {
if hash == "" {
return nil, nil
}
t, err := orm.TypedQuery[schema.Token](db).Filter("AccessTokenHash=", hash).First()
if err == orm.ErrNotFound {
return nil, nil
}
return t, err
}
// GetTokenByRefreshHash resolves a token row by the SHA-256 hash of a presented
// refresh token — the refresh-grant lookup.
func GetTokenByRefreshHash(_ context.Context, db orm.DB, hash string) (*schema.Token, error) {
if hash == "" {
return nil, nil
}
t, err := orm.TypedQuery[schema.Token](db).Filter("RefreshTokenHash=", hash).First()
if err == orm.ErrNotFound {
return nil, nil
}
return t, err
}
// ListTokensByRefreshFamily returns every row sharing a refresh-token family —
// the rotation chain a reuse-detection event revokes as a unit.
func ListTokensByRefreshFamily(ctx context.Context, db orm.DB, family string) ([]*schema.Token, error) {
if family == "" {
return nil, nil
}
return orm.TypedQuery[schema.Token](db).Filter("RefreshFamily=", family).GetAll(ctx)
}
// ListTokensByUserApp returns every token row one user holds for one application
// — the grant an RP-initiated logout retires. User is the "owner/name" pair the
// mint stamps on the row, and BOTH filters are required: a query missing either
// would revoke across users or across applications, so an empty argument returns
// nothing rather than matching everything.
func ListTokensByUserApp(ctx context.Context, db orm.DB, user, application string) ([]*schema.Token, error) {
if user == "" || application == "" {
return nil, nil
}
return orm.TypedQuery[schema.Token](db).
Filter("User=", user).Filter("Application=", application).GetAll(ctx)
}
// RekeyTokens moves every token row a user holds from one identity key to
// another — the "owner/name" pair the mint stamps on the row as User. Moving a
// user between orgs re-keys their identity, and a grant still naming the old key
// resolves nobody: its refresh would answer invalid_grant to the person it was
// issued to. Both keys are required; an empty one moves nothing.
func RekeyTokens(ctx context.Context, db orm.DB, from, to string) error {
if from == "" || to == "" || from == to {
return nil
}
rows, err := orm.TypedQuery[schema.Token](db).Filter("User=", from).GetAll(ctx)
if err != nil && !errors.Is(err, orm.ErrNotFound) {
return err
}
for _, tk := range rows {
tk.User = to
if err := tk.UpdateCtx(ctx); err != nil {
return err
}
}
return nil
}
// DeleteToken removes a token row by (owner, name). A missing row is not an
// error — revocation is idempotent.
func DeleteToken(ctx context.Context, db orm.DB, tok *schema.Token) error {
existing, err := orm.Get[schema.Token](db, tok.Owner+"/"+tok.Name)
if err != nil {
if err == orm.ErrNotFound {
return nil
}
return err
}
return existing.DeleteCtx(ctx)
}
// GetProvider resolves a provider record by (owner, name) — e.g.
// ("admin", "provider-github"). Providers are shared org-level records the
// application's ProviderItem links to by name.
func GetProvider(_ context.Context, db orm.DB, owner, name string) (*schema.Provider, error) {
p, err := orm.TypedQuery[schema.Provider](db).
Filter("Owner=", owner).Filter("Name=", name).First()
if err == orm.ErrNotFound {
return nil, nil
}
return p, err
}
// EnrichProviders resolves each of the application's ProviderItem links to its
// shared Provider record (Category/Type/ClientId), attaching it to
// item.Provider. A link whose provider record is missing is left with a nil
// Provider (the caller treats that as unconfigured — never a dead-end button).
func EnrichProviders(ctx context.Context, db orm.DB, app *schema.Application) {
if app == nil {
return
}
for _, item := range app.Providers {
if item == nil || item.Name == "" {
continue
}
if p, err := GetProvider(ctx, db, ProviderOwner(item), item.Name); err == nil && p != nil {
item.Provider = p
}
}
}
// ProviderOwner is the organization a link's provider record is read from: the one
// the link names, or the platform's where it names none, since that is where the
// shared connectors are seeded.
//
// It is ONE function because two callers must agree: the resolution above, and the
// authorization in front of the write that stores the link. A link is a reference
// to credentials — the identity provider's client id and secret run the sign-in leg
// — so a gate that resolved the owner differently from this would authorize one
// record and use another.
func ProviderOwner(item *schema.ProviderItem) string {
if item == nil || item.Owner == "" {
return policy.AdminOrg
}
return item.Owner
}
// GetOrganizationByName resolves the organization a name refers to. Returns
// (nil, nil) when absent.
//
// Every organization row is filed under the admin owner: the NAME is the tenant
// identity and the owner half is the registry the row lives in. That is what the
// signup converge writes, what the console's list reads, and what authz states
// when it decides an organization write on its reserved-owner branch — so the
// owner is pinned here too, and a name resolves to one row rather than to
// whichever row a scan reaches first.
//
// A name is a key only WITH it. What this answer settles is which algorithm
// verifies a password, which complexity rules a new one must meet, and whether
// the organization demands a second factor — questions that take one answer.
func GetOrganizationByName(_ context.Context, db orm.DB, name string) (*schema.Organization, error) {
if name == "" {
return nil, nil
}
o, err := orm.TypedQuery[schema.Organization](db).
Filter("Owner=", policy.AdminOrg).
Filter("Name=", name).
First()
if err == orm.ErrNotFound {
return nil, nil
}
return o, err
}
// AddVerificationRecord persists a freshly minted verification code. The id is
// (owner, name); the caller sets Name to a unique value before persisting.
// Mirrors PersistToken: the orm.Model is preserved while the caller's fields are
// copied onto the fresh, db-bound entity.
func AddVerificationRecord(ctx context.Context, db orm.DB, rec *schema.VerificationRecord) error {
r := orm.New[schema.VerificationRecord](db)
model := r.Model
*r = *rec
r.Model = model
r.SetId(rec.Owner + "/" + rec.Name)
return r.CreateCtx(ctx)
}
// GetLatestVerificationRecord resolves the most recent UNUSED verification
// record sent to receiver WITHIN owner — the row the check path validates a
// submitted code against. Returns (nil, nil) when none exists.
//
// The owner filter is tenant isolation: an address is not unique across
// organizations, so unscoped this answered across every tenant at once. Every
// caller resolves the account first and therefore knows the org, so the scope costs
// nothing and closes it at the lookup rather than by a check each caller must
// remember.
func GetLatestVerificationRecord(ctx context.Context, db orm.DB, owner, receiver string) (*schema.VerificationRecord, error) {
return GetLatestVerificationRecordFor(ctx, db, owner, receiver, "")
}
// GetLatestVerificationRecordFor is GetLatestVerificationRecord for one purpose
// (schema.VerificationRecord.Purpose). The purpose is compared here rather than in
// the query, so a record written before purposes existed reads as the general one.
func GetLatestVerificationRecordFor(ctx context.Context, db orm.DB, owner, receiver, purpose string) (*schema.VerificationRecord, error) {
if owner == "" || receiver == "" {
return nil, nil
}
recs, err := orm.TypedQuery[schema.VerificationRecord](db).
Filter("Owner=", owner).Filter("Receiver=", receiver).
Filter("IsUsed=", false).Order("-Time").GetAll(ctx)
if err == orm.ErrNotFound {
return nil, nil
}
if err != nil {
return nil, err
}
for _, rec := range recs {
if rec.Purpose == purpose {
return rec, nil
}
}
return nil, nil
}
// PersistFederationState creates a fresh in-flight federation transaction. The
// id is (owner, name); the caller sets Name to the opaque `state` token before
// persisting. Mirrors PersistToken — the orm.Model is preserved while the
// caller's fields are copied onto the db-bound entity.
func PersistFederationState(ctx context.Context, db orm.DB, st *schema.FederationState) error {
s := orm.New[schema.FederationState](db)
model := s.Model
*s = *st
s.Model = model
s.SetId(st.Owner + "/" + st.Name)
return s.CreateCtx(ctx)
}
// GetFederationState resolves an in-flight federation transaction by its opaque
// `state` token (the row Name). The state is a 256-bit random value, so a
// name-only lookup is unambiguous. Returns (nil, nil) when no row carries it —
// the callback treats that as an invalid/expired state and fails closed.
func GetFederationState(_ context.Context, db orm.DB, state string) (*schema.FederationState, error) {
if state == "" {
return nil, nil
}
s, err := orm.TypedQuery[schema.FederationState](db).Filter("Name=", state).First()
if err == orm.ErrNotFound {
return nil, nil
}
return s, err
}
// ErrFederationConsumed is the ONE opaque refusal for a federation state that is
// gone, already burned, expired, or that lost a concurrent burn — the single-use
// guard's "no". Callers collapse it to the same "invalid or expired" answer so a
// prober cannot tell a replay from a race from a forged state.
var ErrFederationConsumed = errors.New("federation state is invalid, used, or expired")
// BurnFederationState atomically consumes an in-flight federation transaction — the
// single-use guard for the OAuth callback. The find-and-burn runs inside a
// GetForUpdate transaction (mirroring the wallet challenge burn and TakeChallenge),
// so two concurrent callbacks on ONE state cannot both flip Used=false→true: the
// loser blocks until the winner commits, then reads it spent. It resolves the row's
// real storage key via the (owner,name) query path (Name is the opaque `state`
// token), locks by that key, refuses a used/expired row with ErrFederationConsumed
// (no write), else sets Used and returns the burned row. A store fault returns the
// raw error so the caller can distinguish it from the opaque refusal.
//
// The caller performs the browser bind-cookie (CSRF) check on a prior read BEFORE
// calling this, so a request that fails the cookie check never reaches — and never
// burns — a victim's pending state.
func BurnFederationState(ctx context.Context, db orm.DB, state string, now time.Time) (*schema.FederationState, error) {
if state == "" {
return nil, ErrFederationConsumed
}
keyed, err := GetFederationState(ctx, db, state)
if err != nil {
return nil, err
}
if keyed == nil {
return nil, ErrFederationConsumed
}
storageID := keyed.Key().Encode()
var out *schema.FederationState
txErr := db.RunInTransaction(ctx, func(tx orm.DB) error {
fresh, err := orm.GetForUpdate[schema.FederationState](tx, storageID)
if err != nil {
if errors.Is(err, orm.ErrNotFound) {
return ErrFederationConsumed
}
return err
}
if fresh.Used || (fresh.ExpireIn != 0 && now.Unix() > fresh.ExpireIn) {
return ErrFederationConsumed
}
fresh.Used = true
if err := fresh.UpdateCtx(ctx); err != nil {
return err
}
out = fresh
return nil
})
if txErr != nil {
return nil, txErr
}
return out, nil
}
// GetUserByConnector resolves the user in an organization whose federated
// connector column (field — the EXACT lowercase orm/json name, e.g. "google" or
// "github") holds subject. It is the "already linked by provider subject" lookup
// the federation broker runs first. subject must be non-empty (an empty subject
// would match every unlinked row, so it is refused). Returns (nil, nil) when no
// user is linked to that subject.
func GetUserByConnector(_ context.Context, db orm.DB, owner, field, subject string) (*schema.User, error) {
if owner == "" || field == "" || subject == "" {
return nil, nil
}
u, err := orm.TypedQuery[schema.User](db).
Filter("Owner=", owner).Filter(field+"=", subject).First()
if err == orm.ErrNotFound {
return nil, nil
}
return u, err
}
// GetSignupByConnector is [GetUserByConnector] over the accounts registered in
// org, for the same reason [GetSignupByEmail] exists: an application that founds
// an org per person has its accounts spread across the orgs it founded, so the
// registration org is not where a returning person is.
//
// The provider's subject is the authoritative match for a returning federated
// user — immune to email churn — so this is the reach that has to work, or a
// person who signed in with the same social identity yesterday, at any of org's
// applications, is treated as new and given a second account today. Two rows
// carrying one subject name nobody, so that fails closed as a duplicated user id
// does.
func GetSignupByConnector(ctx context.Context, db orm.DB, org, field, subject string) (*schema.User, error) {
if org == "" || field == "" || subject == "" {
return nil, nil
}
us, err := orm.TypedQuery[schema.User](db).
Filter(field+"=", subject).Filter("SignupApplication!=", "").GetAll(ctx)
if err == orm.ErrNotFound {
return nil, nil
}
if err != nil {
return nil, err
}
if us, err = registeredIn(ctx, db, org, us); err != nil {
return nil, err
}
switch len(us) {
case 0:
return nil, nil
case 1:
return us[0], nil
default:
return nil, fmt.Errorf("store: %d accounts registered in %q share one %s subject", len(us), org, field)
}
}