mirror of
https://github.com/hanzoai/iam.git
synced 2026-11-19 18:37:16 +00:00
keys/principal takes an optional ?org=. store.HolderIn admits it exactly where a member's key filed there would act: the holder's home or an org-wide membership their standing acts in (Acts). Anything else is key_org_not_open. The answer names the org the key is filed in as keyOrg, so a resource server still addresses the key's own policy there. Without ?org= nothing changes. For hanzo-inc/cloud#429: cloud billed a key's own org whatever X-Org-Id the caller sent. Testing: go test ./... passes (45 packages). New store tests: selecting a membership acts there as member with the key's name and limit; the key's own org or none is unchanged; another tenant, an unknown org and admin are refused; a member's key may select its holder's home; removing the membership ends the selection on the next call; a plain member of a platform org (hanzo) is refused. Risk: medium. It widens where a secret key acts, but only into orgs its holder already acts in with a token, and the check is the same Acts and MembershipIn the key resolver uses. Reads one membership per selected request; no caching here. How to revert: revert this commit; ?org= is then ignored again. Co-authored-by: Claude Opus 5.5 <[email protected]>
205 lines
9.2 KiB
Go
205 lines
9.2 KiB
Go
// Copyright 2026 Hanzo AI, Inc.
|
|
// SPDX-License-Identifier: MIT OR Apache-2.0
|
|
|
|
// Package resolve answers whose an API key is.
|
|
//
|
|
// Two endpoints, split by the one property that makes a publishable key safe to ship
|
|
// in client JavaScript. A SECRET sk- asks WHO, and /v1/iam/keys/principal answers
|
|
// with the person or machine it belongs to — how a service of yours turns a
|
|
// credential on an incoming request into an identity. A PUBLISHABLE pk- asks
|
|
// WHICH ORG, and /v1/iam/keys/org answers with the tenant and nothing else: no
|
|
// path through it can load or return a user, so a key in client code can never
|
|
// become a way to learn who anyone is.
|
|
//
|
|
// Both are machine boundaries. The caller must be a confidential app holding the
|
|
// matching capability; a human, even a SuperAdmin, is refused, because a
|
|
// capability is held vacuously by non-apps and key resolution is never an
|
|
// interactive admin action.
|
|
//
|
|
// It is its own package because it needs both halves and they sit on opposite
|
|
// sides of the graph: authz (the Principal the Guard attached) already depends on
|
|
// keys, so keys cannot depend back on authz.
|
|
package resolve
|
|
|
|
import (
|
|
"errors"
|
|
"net/http"
|
|
"strings"
|
|
"time"
|
|
|
|
"github.com/hanzoai/account"
|
|
policy "github.com/hanzoai/authz"
|
|
"github.com/hanzoai/orm"
|
|
"github.com/zap-proto/zip"
|
|
|
|
"github.com/hanzoai/iam/internal/httpx"
|
|
"github.com/hanzoai/iam/internal/principal"
|
|
"github.com/hanzoai/iam/pkg/store"
|
|
)
|
|
|
|
//go:generate go run github.com/zap-proto/zip/cmd/zipdoc
|
|
|
|
// unauthorized is v1's refusal message, verbatim — the envelope a denied caller
|
|
// receives from a handler-authorized read.
|
|
const unauthorized = "auth:Unauthorized operation"
|
|
|
|
// Route registers the two key endpoints on app. Both carry their target in
|
|
// `?accessKey=` rather than an (owner, name) the Guard could authorize, so both
|
|
// are handler-authorized (authz.handlerAuthorizedExact) and each authorizes
|
|
// itself behind its own capability.
|
|
func Route(app *zip.Group, db orm.DB) {
|
|
app.Raw(http.MethodGet, "/v1/iam/keys/org", org(db))
|
|
app.Raw(http.MethodGet, "/v1/iam/keys/principal", who(db))
|
|
}
|
|
|
|
// orgOnly is the ORG-ONLY projection: the tenant a publishable key belongs to and
|
|
// its write-only scope, and no more. It carries no user, name, email or admin
|
|
// flag — no principal — so resolving a pk- discloses only WHICH org, never WHO.
|
|
type orgOnly struct {
|
|
Org string `json:"org"`
|
|
Scope string `json:"scope"`
|
|
}
|
|
|
|
// org answers which organization a PUBLISHABLE key belongs to — what a service of
|
|
// yours calls to attribute a request that arrived carrying a key shipped in a
|
|
// browser.
|
|
//
|
|
// It names an organization and never a person. A key that is expired, secret
|
|
// rather than publishable, or simply unknown all answer with the same sentence,
|
|
// and with a `code` saying which of those it was. Only a confidential service
|
|
// that already proved it may resolve keys at all ever reads that code — there is
|
|
// no anonymous caller here to probe for which keys exist — and telling it apart
|
|
// is what lets the holder be told to re-mint an expired key instead of hunting a
|
|
// configuration error.
|
|
func org(db orm.DB) zip.Handler {
|
|
return func(c *zip.Ctx) error {
|
|
ctx := c.Context()
|
|
p, ok := principal.From(ctx)
|
|
if !ok || p.App == nil || !p.Holds(policy.CapPublishableResolve, principal.Env) {
|
|
return httpx.Err(c, unauthorized)
|
|
}
|
|
k, err := store.PublishableKeyByAccessKey(ctx, db, c.Query("accessKey"), time.Now())
|
|
if err != nil {
|
|
// Not found, not a pk-, not publishable, expired, or a store error — one
|
|
// envelope, and `code` distinguishes them for the confidential app that
|
|
// already passed CapPublishableResolve above. A store fault yields no
|
|
// reason at all (store.Reason returns ""), so infrastructure trouble is
|
|
// never reported to the holder as a bad key.
|
|
return httpx.ErrCode(c, "the entity does not exist", string(store.Reason(err)))
|
|
}
|
|
return httpx.Ok(c, orgOnly{Org: k.Owner, Scope: k.Scope})
|
|
}
|
|
}
|
|
|
|
// holder is the minimal principal projection the secret endpoint returns — EXACTLY
|
|
// the fields cloud's key resolver consumes (auth_apikey.go) and no more. It is a
|
|
// TIGHTER redaction than schema.User.Mask, deliberately: Mask blanks the secret
|
|
// digests and bearer tokens but leaves AccessKey populated, and an sk- resolution
|
|
// must never disclose the resolved user's OTHER credential (the value on its User
|
|
// row) to a caller that only presented a secret key. A projection carrying no
|
|
// secret field is leak-proof by construction.
|
|
//
|
|
// BillingAccount is here because WHO PAYS travels with the identity or it is
|
|
// guessed. account.Payer honours the named account above all else and otherwise
|
|
// falls back to a shape rule that hands anyone in the signup org a PERSONAL
|
|
// wallet — a ghost for a machine, which no funding path can name. Omitting the
|
|
// field did not leave the payer unknown, it made it confidently wrong: every
|
|
// first-party service key resolved to an unfundable wallet and 402'd against a
|
|
// funded org pool. It names a LEDGER, never a secret, so the projection stays
|
|
// leak-proof.
|
|
type holder struct {
|
|
Owner string `json:"owner"`
|
|
Name string `json:"name"`
|
|
// Org is the org the KEY acts in. It is Owner for a key minted in its holder's
|
|
// home org, and the org they were added to for a member's key, which speaks
|
|
// for them there and nowhere else.
|
|
Org string `json:"org"`
|
|
Email string `json:"email"`
|
|
IsAdmin bool `json:"isAdmin"`
|
|
BillingAccount string `json:"billing_account,omitempty"`
|
|
// Scope is what this CREDENTIAL may reach — the key row's own limit, as
|
|
// distinct from what the user it resolves to may reach. Empty means the key
|
|
// carries no limit, which is what a key minted before limits existed carries
|
|
// and means unrestricted.
|
|
//
|
|
// A resource server cannot enforce a per-key limit it is never told, and this
|
|
// is the only endpoint that knows both halves at once.
|
|
Scope string `json:"scope,omitempty"`
|
|
// Key is the key's name within Org — which credential this is, so a resource
|
|
// server can count and limit each key on its own.
|
|
Key string `json:"key,omitempty"`
|
|
// KeyOrg is the org the key is filed in, when ?org= moved the holder to
|
|
// another Org: Key names a row there. Absent when the key acts where it is
|
|
// filed, which is every answer to a request that selected no org.
|
|
KeyOrg string `json:"keyOrg,omitempty"`
|
|
}
|
|
|
|
// who answers which account a SECRET key belongs to — what a gateway of yours calls
|
|
// to attribute and bill a request that arrived carrying an sk-.
|
|
//
|
|
// A publishable key resolves to nobody here, deliberately: it is safe to ship in
|
|
// a browser precisely because it names an organization and never a person.
|
|
//
|
|
// THE `msg` STAYS UNIFORM AND THE `code` SAYS WHY. Every unresolvable key answers
|
|
// the same not-exist sentence, so nothing that reads the prose can tell a missing
|
|
// key from a denied one. The machine-readable reason rides beside it because THE
|
|
// CAPABILITY ABOVE IS THE BOUNDARY, not the vagueness of this sentence: a caller
|
|
// that reaches this line has already proven it is a confidential app holding
|
|
// CapKeyResolve, and such a caller can resolve any key it likes to a full
|
|
// principal. Telling it which refusal occurred discloses nothing it could not
|
|
// already obtain, and withholding it is what made a revoked key
|
|
// indistinguishable from a deleted org for every human downstream. There is no
|
|
// anonymous reader of this envelope to oracle.
|
|
func who(db orm.DB) zip.Handler {
|
|
return func(c *zip.Ctx) error {
|
|
ctx := c.Context()
|
|
p, ok := principal.From(ctx)
|
|
if !ok || p.App == nil || !p.Holds(policy.CapKeyResolve, principal.Env) {
|
|
return httpx.Err(c, unauthorized)
|
|
}
|
|
h, err := store.HolderByAccessKey(ctx, db, strings.TrimSpace(c.Query("accessKey")))
|
|
if errors.Is(err, orm.ErrNotFound) {
|
|
return httpx.ErrCode(c, "the entity does not exist", string(store.Reason(err)))
|
|
}
|
|
if err != nil {
|
|
return httpx.Err(c, err.Error())
|
|
}
|
|
// ?org= is the org the caller selected for this request. The key acts there
|
|
// only if its holder does (store.HolderIn); otherwise key_org_not_open,
|
|
// never a silent fall back to the key's own org, which billed the wrong
|
|
// tenant (hanzo-inc/cloud#429).
|
|
if sel := strings.TrimSpace(c.Query("org")); sel != "" {
|
|
h, err = store.HolderIn(ctx, db, h, sel)
|
|
if errors.Is(err, orm.ErrNotFound) {
|
|
return httpx.ErrCode(c, "the entity does not exist", string(store.Reason(err)))
|
|
}
|
|
if err != nil {
|
|
return httpx.Err(c, err.Error())
|
|
}
|
|
}
|
|
u := h.User
|
|
// IsAdmin describes the holder in the key's org: their home flag at home,
|
|
// their membership role elsewhere.
|
|
// A member's key always spends from the pool of the org it acts in: the member
|
|
// has no wallet there of their own, and naming none would leave the payer to a
|
|
// rule that addresses wallets by username.
|
|
billing := store.BillingAccount(u, store.MemberOrgRefs(ctx, db, u))
|
|
admin := u.IsAdmin
|
|
if h.Org != u.Owner {
|
|
billing = account.Org(h.Org).String()
|
|
admin = h.Role == store.RoleOwner || h.Role == store.RoleAdmin
|
|
}
|
|
return httpx.Ok(c, holder{
|
|
Owner: u.Owner,
|
|
Name: u.Name,
|
|
Org: h.Org,
|
|
Email: u.Email,
|
|
IsAdmin: admin,
|
|
BillingAccount: billing,
|
|
Scope: h.Scope,
|
|
Key: h.Key,
|
|
KeyOrg: h.KeyOrg,
|
|
})
|
|
}
|
|
}
|