Files
zeekay 5c067f1791 keys: a member lists the keys they hold in their org
The key collection now authorizes itself.  A person names an org they
belong to: its admin, or a SuperAdmin, reads every key it holds, and
anyone else reads the keys they hold there.  A stranger is refused with
the bytes every stranger gets, and a reserved org's keys stay a
SuperAdmin's alone.  A confidential client still needs key-mint and
still reads only the org it serves, so its credential alone never reads
another tenant's keys.  A named key stays the Guard's.

The allowlist lookup moves to the principal leaf, so a collection that
authentication is built on asks a capability the way the Guard does.

Claude-Session: https://claude.ai/code/session_01HvACxex9ZZTzJCCHgirsGy
2026-10-06 20:14:00 -07:00

778 lines
31 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
// Package keys serves the owner-scoped CRUD surface for the `keys` entity
// (v1 the legacy surface `key`) as typed zip handlers over hanzoai/orm.
//
// Identity is the (owner, name) pair; it maps onto the orm storage id as
// "owner/name", exactly as the v1 record addressed itself, and onto the URL as
// /v1/iam/keys/:owner/:name — the method carries the verb, the path carries the
// key. Every handler closes over the one orm.DB entity store so the typed
// signatures carry no transport or storage plumbing.
package keys
import (
"cmp"
"context"
"crypto/rand"
"encoding/hex"
"errors"
"fmt"
"strings"
"time"
policy "github.com/hanzoai/authz"
"github.com/hanzoai/orm"
"github.com/zap-proto/zip"
"github.com/hanzoai/iam/internal/principal"
"github.com/hanzoai/iam/pkg/schema"
"github.com/hanzoai/iam/pkg/store"
)
//go:generate go run github.com/zap-proto/zip/cmd/zipdoc
// Route registers the key CRUD routes on app, binding each handler to db.
// Called from routes.Route once it is threaded the entity store.
//
// ONE noun, plural, for every op — the same shape users.Route uses
// (/v1/iam/users, /v1/iam/users/:owner/:name). It used to be two nouns, `keys` for
// the list and `key` for everything else, and that was not merely inconsistent:
// authz.entityOf reads the FIRST path segment as the entity, so the list
// authorized on "keys" and every write on "key". Two entity strings for one
// entity means every capability keyed on it is dead on one of the two surfaces —
// the same defect entityNoun was written to fix for the legacy verb spellings.
func Route(app *zip.Group, db orm.DB) {
app.Get("/v1/iam/keys", list(db), zip.WithTags("keys"))
app.Post("/v1/iam/keys", create(db), zip.WithTags("keys"))
app.Get("/v1/iam/keys/:owner/:name", get(db), zip.WithTags("keys"))
app.Put("/v1/iam/keys/:owner/:name", update(db), zip.WithTags("keys"))
app.Delete("/v1/iam/keys/:owner/:name", del(db), zip.WithTags("keys"))
}
// ListRequest names the organization to read. Omitting it means "the one my
// credential is scoped to", which for a credential that spans tenants is all of
// them; visible turns the two into one answer.
type ListRequest struct {
Owner string `json:"owner,omitempty"`
}
// ListResponse is the owner-scoped key set, newest first.
type ListResponse struct {
Keys []schema.Key `json:"keys"`
}
// Ref addresses one key by its (owner, name) identity.
type Ref struct {
Owner string `json:"owner"`
Name string `json:"name"`
}
// DeleteResponse reports whether the key was removed.
type DeleteResponse struct {
Deleted bool `json:"deleted"`
}
// id joins the owner-scoped natural key into the orm storage id — the same
// "owner/name" identity the v1 record used.
func id(owner, name string) string { return owner + "/" + name }
// list returns the API keys of an organization that you may see, newest first —
// what each is called, what it may reach, its publishable half, and when it was
// last used. Secret halves are never listed.
//
// Which keys come from your credentials, not from the request. You may name an
// organization you belong to: its admin sees every key it holds, and a member sees
// the keys they hold there. Naming any other organization is refused.
func list(db orm.DB) zip.TypedHandler[ListRequest, ListResponse] {
return func(ctx context.Context, in *ListRequest) (*ListResponse, error) {
owner, holder, err := visible(ctx, in.Owner)
if err != nil {
return nil, err
}
q := orm.TypedQuery[schema.Key](db)
if owner != "" {
q = q.Filter("Owner=", owner)
}
items, err := q.Order("-CreatedTime").GetAll(ctx)
if err != nil {
return nil, zip.ErrInternal(err.Error())
}
seen, err := store.Sightings(ctx, db, owner)
if err != nil {
return nil, zip.ErrInternal(err.Error())
}
out := &ListResponse{Keys: make([]schema.Key, 0, len(items))}
for _, k := range items {
if holder != "" && qualify(k.Owner, k.User) != holder {
continue
}
m := k.Mask()
m.UsedTime = seen[k.Owner+"/"+k.Name]
out.Keys = append(out.Keys, *m)
}
return out, nil
}
}
// get returns one API key: what it is called, what it may reach, and when it was
// issued.
func get(db orm.DB) zip.TypedHandler[Ref, schema.Key] {
return func(_ context.Context, in *Ref) (*schema.Key, error) {
if in.Owner == "" || in.Name == "" {
return nil, zip.ErrBadRequest("owner and name are required")
}
k, err := orm.Get[schema.Key](db, id(in.Owner, in.Name))
if errors.Is(err, orm.ErrNotFound) {
return nil, zip.ErrNotFound("key not found: " + id(in.Owner, in.Name))
}
if err != nil {
return nil, zip.ErrInternal(err.Error())
}
return k.Mask(), nil
}
}
// create issues an API key. A standard key comes back as a publishable half you
// may ship in client code and a secret half you must not — the secret is shown
// once, at creation, and cannot be retrieved afterwards. A publish-scoped key is
// issued with the publishable half only, so there is no secret to leak.
//
// A name already used in your organization is refused rather than reissued, so
// creating twice never silently invalidates a key that is in production.
//
// A key you create is yours: it names you as its holder and speaks for you in the
// organization it is filed in. Naming anyone else as its holder is refused; a
// SuperAdmin names the person a key is for.
func create(db orm.DB) zip.TypedHandler[schema.Key, schema.Key] {
return func(ctx context.Context, in *schema.Key) (*schema.Key, error) {
if in.Owner == "" || in.Name == "" {
return nil, zip.ErrBadRequest("owner and name are required")
}
user, err := holder(ctx, in.Owner, in.User)
if err != nil {
return nil, err
}
in.User = user
if err := holdable(ctx, db, in.Owner, in.User, in.Scope); err != nil {
return nil, err
}
if err := application(ctx, db, in.Owner, in.Application); err != nil {
return nil, err
}
if _, err := orm.Get[schema.Key](db, id(in.Owner, in.Name)); err == nil {
return nil, zip.ErrConflict("key already exists: " + id(in.Owner, in.Name))
} else if !errors.Is(err, orm.ErrNotFound) {
return nil, zip.ErrInternal(err.Error())
}
k := orm.New[schema.Key](db)
k.SetId(id(in.Owner, in.Name))
k.Owner, k.Name = in.Owner, in.Name
apply(k, in)
// Scope is settable HERE and only here: it is the key's access class, chosen
// when the key is minted and fixed thereafter (apply deliberately does not
// carry it, so an update cannot flip a secret key to publish scope and blank
// its secret).
k.Scope = in.Scope
if k.AccessKey == "" {
k.AccessKey = Mint("pk", k.State)
}
if ClassOf(k.Scope) == schema.KeyScopePublish {
// A publishable key is WRITE-ONLY: a pk- publishable half and NEVER a
// confidential sk- secret — even if the caller supplied one — so it can
// carry no full-access material. Its authority is resolved org-only at the
// ingest endpoint (/v1/iam/keys/org), never as a principal.
k.AccessSecret = ""
} else if k.AccessSecret == "" {
k.AccessSecret = Mint("sk", k.State)
}
now := time.Now().UTC().Format(time.RFC3339)
k.CreatedTime, k.UpdatedTime = now, now
// The row keeps the DIGEST and never the secret. The plaintext goes back
// on the struct afterwards because minting reveals it exactly once — this
// response is the only time its holder can ever read it — but what is
// written down is a value that cannot be replayed if the table leaks.
secret := k.AccessSecret
k.Prefix = schema.PrefixOf(cmp.Or(secret, k.AccessKey))
k.AccessSecretDigest = schema.DigestSecret(secret)
k.AccessSecret = ""
if err := k.CreateCtx(ctx); err != nil {
return nil, zip.ErrInternal(err.Error())
}
k.AccessSecret = secret
return k, nil
}
}
// update changes what a key is called, what it may reach, when it expires, or
// revokes it. The credential itself is not reissued — the key in your deployment
// keeps working until it expires or is revoked.
//
// An update writes the whole set of editable fields, so send the key as you read
// it with your changes made. The class in its scope (publishable or secret) is
// fixed at creation and an update naming the other is refused. Setting state to
// "Revoked" revokes the key: the row stays, records who revoked it and when, and
// is never updated again.
func update(db orm.DB) zip.TypedHandler[schema.Key, schema.Key] {
return func(ctx context.Context, in *schema.Key) (*schema.Key, error) {
if in.Owner == "" || in.Name == "" {
return nil, zip.ErrBadRequest("owner and name are required")
}
// The read, the checks and the write are one transaction, so an edit cannot
// write back a row a revoke changed under it.
var out *schema.Key
err := db.RunInTransaction(ctx, func(tx orm.DB) error {
var err error
out, err = edit(ctx, tx, in)
return err
})
var refused *zip.HTTPError
if errors.As(err, &refused) {
return nil, err
}
if err != nil {
return nil, zip.ErrInternal(err.Error())
}
return out, nil
}
}
// edit is update's body, run inside its transaction.
func edit(ctx context.Context, db orm.DB, in *schema.Key) (*schema.Key, error) {
k, err := orm.Get[schema.Key](db, id(in.Owner, in.Name))
if errors.Is(err, orm.ErrNotFound) {
return nil, zip.ErrNotFound("key not found: " + id(in.Owner, in.Name))
}
if err != nil {
return nil, zip.ErrInternal(err.Error())
}
if k.State == schema.KeyStateRevoked {
return nil, zip.ErrConflict("a revoked key is final; create a new key instead")
}
// A member's key names its member for as long as it exists. Its secret is in
// the member's hands, so repointing it would hand them whoever it now names.
if o, _, ok := strings.Cut(k.User, "/"); ok && o != k.Owner && in.User != k.User {
return nil, zip.ErrBadRequest("a member's key names its member for as long as it exists")
}
// A person edits a key and never who it speaks for, the same rule create holds
// them to: repointing it would hand its secret's holder whoever it named next.
// Leaving the holder out, or naming the one it has, keeps it; naming anyone
// else is refused.
if _, ok := person(ctx); ok {
if in.User != "" && qualify(k.Owner, in.User) != qualify(k.Owner, k.User) {
return nil, zip.ErrForbidden("a key names its holder for as long as it exists; create a new key instead")
}
in.User = k.User
}
if err := holdable(ctx, db, k.Owner, in.User, k.Scope); err != nil {
return nil, err
}
if in.Application != k.Application {
if err := application(ctx, db, k.Owner, in.Application); err != nil {
return nil, err
}
}
if (ClassOf(in.Scope) == schema.KeyScopePublish) != (ClassOf(k.Scope) == schema.KeyScopePublish) {
return nil, zip.ErrBadRequest("a key's class is fixed when it is minted; create a new key instead")
}
apply(k, in)
// The reach half of the scope is policy and changes here; the class half is
// equal, checked above, so this never turns one kind of key into the other.
k.Scope = in.Scope
if ClassOf(k.Scope) == schema.KeyScopePublish {
// Keep a publishable key write-only for its whole lifecycle: an update can
// never attach a confidential sk- secret to a pk--only browser key.
k.AccessSecret = ""
}
now := time.Now().UTC().Format(time.RFC3339)
k.UpdatedTime = now
if k.State == schema.KeyStateRevoked {
// Revoking keeps the row and says who and when. A person revokes as
// themselves; a minter names the person it acts for.
k.Revoker, k.RevokeTime = in.Revoker, now
if p, ok := person(ctx); ok {
k.Revoker = self(p)
}
}
if err := k.UpdateCtx(ctx); err != nil {
return nil, zip.ErrInternal(err.Error())
}
// An edit is not a mint: the secret is revealed ONCE, by create. Echoing it
// from every update would turn "rename this key" into "re-read its secret".
return k.Mask(), nil
}
// del revokes an API key. Anything still presenting it stops being authorized at
// once, so roll the replacement out before you revoke.
func del(db orm.DB) zip.TypedHandler[Ref, DeleteResponse] {
return func(ctx context.Context, in *Ref) (*DeleteResponse, error) {
if in.Owner == "" || in.Name == "" {
return nil, zip.ErrBadRequest("owner and name are required")
}
k, err := orm.Get[schema.Key](db, id(in.Owner, in.Name))
if errors.Is(err, orm.ErrNotFound) {
return nil, zip.ErrNotFound("key not found: " + id(in.Owner, in.Name))
}
if err != nil {
return nil, zip.ErrInternal(err.Error())
}
if err := k.DeleteCtx(ctx); err != nil {
return nil, zip.ErrInternal(err.Error())
}
return &DeleteResponse{Deleted: true}, nil
}
}
// visible resolves which key rows the caller may list: the organization, and the
// one holder whose rows they are when the caller may see only their own.
//
// - A confidential client holding the key-mint capability reads the org it SERVES
// (principal.Scope). Its mint reaches every tenant and its read does not, so a
// client credential alone never reads another tenant's keys.
// - A SuperAdmin, and a person who administers the org (AdminOf), read every key
// the org holds — the same people the Guard admits to a named key.
// - Any other person reads the keys they hold in an org they BELONG to
// (principal.ScopeRead), and no colleague's. The membership set is read from the
// store when the principal is built, never from a claim the caller supplies.
//
// A stranger to the org is refused with the bytes every stranger gets, and so is a
// principal with no account behind it, which holds no key. The reserved orgs
// (admin, built-in, app) are a SuperAdmin's alone, as the Guard holds every row
// they own: belonging to one, or serving it, reads none of its keys.
func visible(ctx context.Context, owner string) (org, holder string, err error) {
p, ok := principal.From(ctx)
if !ok {
return "", "", zip.ErrForbidden("no principal")
}
if p.App != nil {
if !p.Holds(policy.CapKeyMint, principal.Env) {
return "", "", zip.ErrForbidden("forbidden")
}
org, err = principal.Scope(ctx, owner)
} else {
org, err = principal.ScopeRead(ctx, owner)
}
if err != nil {
return "", "", err
}
if policy.IsReservedOrg(org) && !p.Sudo {
return "", "", zip.ErrForbidden("forbidden: a reserved organization's keys are read by a SuperAdmin only")
}
if p.App != nil || p.Sudo || p.AdminOf(org) {
return org, "", nil
}
if holder = self(p); holder == "" {
return "", "", zip.ErrForbidden("forbidden: this credential holds no keys")
}
return org, holder, nil
}
// person reports whether the caller writes keys for itself — a principal that is
// neither a confidential client nor a SuperAdmin, both of which mint on a
// person's behalf — and returns it.
func person(ctx context.Context) (*principal.Principal, bool) {
p, ok := principal.From(ctx)
return p, ok && p != nil && p.App == nil && !p.Sudo
}
// self is the account a principal is, "<org>/<name>", or "" for one with no
// account behind it.
func self(p *principal.Principal) string {
if p == nil || p.Org == "" || p.User == "" {
return ""
}
return p.Org + "/" + p.User
}
// holder is the account a key created by the caller names. A person's key names
// the person: an empty user is the caller, the caller named either way — bare
// within the key's owner, or "<org>/<name>" — is the caller, and anyone else is
// refused. A confidential client or a SuperAdmin names the holder it mints for,
// which holdable then judges; so does a write with no principal, which the
// authorization hook never admits to a route.
func holder(ctx context.Context, owner, user string) (string, error) {
p, ok := person(ctx)
if !ok {
return user, nil
}
me := self(p)
if me == "" {
return "", zip.ErrForbidden("a key speaks for the account that creates it, and this caller has none")
}
if user == "" {
return me, nil
}
if qualify(owner, user) != me {
return "", zip.ErrForbidden("a key you create speaks for you; only a SuperAdmin names another holder")
}
return me, nil
}
// qualify spells a key's holder as "<org>/<name>": a bare name is an account of
// the key's owner, as the resolver reads it (store.keyUserRef).
func qualify(owner, user string) string {
if strings.Contains(user, "/") {
return user
}
return owner + "/" + user
}
// application gates the application a key names. A token minted with the key
// names that application as its client (azp), so a key may name only an
// application of its own org — never another tenant's, and never one of the
// platform's that its org does not run. A SuperAdmin may name any. The
// application is read by client id, as a token names it, then by name.
func application(ctx context.Context, db orm.DB, owner, ref string) error {
if ref == "" {
return nil
}
if p, ok := principal.From(ctx); ok && p != nil && p.Sudo {
return nil
}
app, err := store.GetApplicationByClientId(ctx, db, ref)
if err == nil && app == nil {
app, err = store.GetApplicationNamed(ctx, db, ref)
}
if err != nil {
return zip.ErrInternal(err.Error())
}
if app == nil || app.Organization != owner {
return zip.ErrForbidden("a key names an application of its own organization only")
}
return nil
}
// holdable rejects a Key whose User names someone the key's org does not admit —
// the write-side half of the F1 credential-forgery gate (store.holderOwningKey is
// the authoritative half). Key.User and the credential halves are caller-supplied,
// and the key write is authorized only on (Owner, Name), so a "/"-qualified User
// naming "admin/z" or a victim tenant would otherwise persist and let a presented
// sk- resolve to that identity. A bare username or an empty User resolves within
// the key's own owner and is fine.
//
// No secret key speaks for a SuperAdmin, whoever writes it (ErrSuperAdminKey).
// scope is the key's access class as it will be stored; a publishable key names
// an org and no principal, so it is not asked.
//
// A MEMBER of the key's org whose home is elsewhere may hold a key there, because
// that is how a person works for an org they were added to. Such a row is written
// only by a caller that mints on a person's behalf — a confidential app, which the
// Guard admitted to keys only by the key-mint capability, or a SuperAdmin — or by
// that member for themselves, and never by a tenant admin for anyone else, who
// could otherwise mint a credential that speaks as any of the org's members. And
// only while the membership exists.
func holdable(ctx context.Context, db orm.DB, owner, user, scope string) error {
if err := operatorFree(owner, user, scope); err != nil {
return err
}
o, _, ok := strings.Cut(user, "/")
if !ok || o == owner {
return nil
}
p, found := principal.From(ctx)
if !found || p == nil || (p.App == nil && !p.Sudo && user != self(p)) {
return zip.ErrBadRequest("key user must belong to the key's owner")
}
member, err := store.MemberKey(ctx, db, user, owner)
if err != nil {
return zip.ErrInternal(err.Error())
}
if !member {
return zip.ErrBadRequest("key user must be a member of the key's owner")
}
return nil
}
// ErrSuperAdminKey refuses a secret key that would speak for an account in the
// admin org (store.SuperAdminKey). A SuperAdmin signs in and holds short-lived
// tokens; a durable credential that authenticates as the platform's operator is
// one nobody can see expire.
var ErrSuperAdminKey = errors.New("keys: a SuperAdmin holds no API key; sign in for a short-lived token")
// operatorFree refuses a secret key, filed in owner and naming user, that would
// speak for an account in the admin org (store.SuperAdminKey) — as a zip error,
// so every handler answers it alike.
func operatorFree(owner, user, scope string) error {
if ClassOf(scope) == schema.KeyScopePublish {
return nil
}
if store.SuperAdminKey(&schema.Key{Owner: owner, User: user}) {
return zip.ErrForbidden(ErrSuperAdminKey.Error())
}
return nil
}
// apply copies the caller-settable fields from src onto dst, leaving the
// (owner, name) identity, storage id, audit stamps AND THE CREDENTIAL ITSELF under
// handler control.
//
// AccessKey/AccessSecret are deliberately NOT copied. They authenticate: a secret
// key's sk- half resolves its owning user by exact match (store.userOwningKey), so
// copying a caller-supplied value lets the sender choose a credential it already
// knows and then present it as that key's principal. Minting is the only writer.
// This matters more the moment the secret is stored as a digest rather than
// verbatim — a chosen digest is a forgery, not merely a chosen password.
//
// Scope is not copied either. Its CLASS is fixed at create: letting an update flip
// a secret key to publish scope would blank its AccessSecret and make its pk- half
// org-resolvable at the ingest endpoint — a privilege change disguised as an edit.
// Its REACH is policy, so update writes the scope itself once it has checked the
// class is unchanged. Rotation is a mint operation, not a field write.
func apply(dst, src *schema.Key) {
dst.DisplayName = src.DisplayName
dst.Type = src.Type
dst.Organization = src.Organization
dst.Application = src.Application
dst.User = src.User
dst.ExpireTime = src.ExpireTime
dst.State = src.State
}
// mint generates a prefixed credential half — "{pk|sk}-{live|test}-{random}"
// — mirroring the v1 key format. State == "test" selects the test env.
func Mint(prefix, state string) string {
env := "live"
if state == "test" {
env = "test"
}
var b [16]byte
_, _ = rand.Read(b[:])
return fmt.Sprintf("%s-%s-%s", prefix, env, hex.EncodeToString(b[:]))
}
// UserKeyName and PublishKeyName are the deterministic name STEMS of the ONE key a
// user holds AT EACH SCOPE (NameFor spells the rest). Deterministic so a re-mint
// REPLACES the previous credential instead of leaving a second live one behind — a
// user has one key per scope, and revoking it revokes them at that scope.
//
// Two rows, not one, because the two scopes are different credentials with opposite
// exposure: the secret key authenticates its holder as the user, the publishable key
// resolves to an org and is shipped in client JS. Holding both is the normal case (a
// server SDK and a browser beacon), and rotating the browser key must not sign the
// user out of their own API.
const (
UserKeyName = "cloud-api"
PublishKeyName = "publishable"
)
// NameFor is the deterministic key Name for the credential `user` holds at `scope`:
// the ONE mapping from a key's access class to the row that holds it, so mint,
// revoke and read can never disagree about which row a scope means.
//
// A secret key authenticates a USER, so the user is part of the row's identity. It
// used to be the scope alone, which made "(owner, scope)" the identity of a
// session-equivalent credential and gave an entire org ONE secret key row: the
// second member to mint overwrote the first member's key in place, silently
// revoking them, and the row's User field then named only whoever minted last — so
// every other member's GET reported no key while their live credential kept
// authenticating as someone else's row. Naming the user makes that unrepresentable.
//
// A publishable key resolves the ORG and never a principal, so one row per org is
// the whole truth about it and the user plays no part in its name.
func NameFor(user, scope string) string {
if ClassOf(scope) == schema.KeyScopePublish {
return PublishKeyName
}
return user + "-" + UserKeyName
}
// ClassOf reads the ACCESS CLASS out of a scope, ignoring any reach entries
// beside it.
//
// Scope carries two independent facts in one comma-separated field: the class
// ("publish", or empty for a confidential key) and the REACH a credential is
// limited to ("model:zen5"). The class decides which key is minted and what the
// row is named; the reach decides nothing here and is stored verbatim for the
// resource server to enforce.
//
// They were the same string once, so a limited publishable key compared
// unequal to KeyScopePublish and minted a SECRET key under the secret name —
// the caller asked for a browser credential and got a session-equivalent one.
// The class is the first entry because that is the one this package acts on.
func ClassOf(scope string) string { return schema.ClassOf(scope) }
// MintUserKey (re)mints the single credential a user holds at `scope` and returns the
// half its holder presents — revealed once:
//
// - "" (the default, secret): the confidential sk- half. Resolves to the USER
// (store.userOwningKey queries schema.Key.AccessSecret), so it is session-
// equivalent and must never be shipped to a browser.
// - schema.KeyScopePublish: the publishable pk- half, and NO secret is stored at
// all. Resolves to just the ORG (store.PublishableKeyByAccessKey), never a
// principal, which is exactly what makes it safe in client JS. This is the ONLY
// path that mints one, and its absence is why every surface configured its own
// ingest credential.
//
// It writes a schema.Key row because that is the ONLY thing the resolvers read. The
// previous implementation stamped the sk- onto schema.User.AccessKey, which NOTHING
// resolves: every key minted that way authenticated nobody. Writing the row the
// resolver actually reads is the fix.
//
// Idempotent by (Owner, NameFor(user, scope)): re-minting replaces that user's
// credential in place, and leaves every other member of the org untouched.
//
// A SuperAdmin is minted no secret key (ErrSuperAdminKey); a publishable key names
// only the org and is minted as for anyone.
func MintUserKey(ctx context.Context, db orm.DB, owner, user, scope string) (string, error) {
if strings.TrimSpace(owner) == "" || strings.TrimSpace(user) == "" {
return "", fmt.Errorf("keys: owner and user are required")
}
publish := ClassOf(scope) == schema.KeyScopePublish
if !publish && store.SuperAdminKey(&schema.Key{Owner: owner, User: user}) {
return "", ErrSuperAdminKey
}
// The credential the holder presents, and the ONE value returned. A publishable
// key has no secret half — not an empty one, none — so there is nothing else it
// could return and nothing a leak of the row could reveal.
access, secret := Mint("pk", ""), Mint("sk", "")
presented := secret
if publish {
secret = ""
presented = access
}
name := NameFor(user, scope)
now := time.Now().UTC().Format(time.RFC3339)
// Retire the org-wide secret row an older build left behind. Its secret still
// authenticates, as whichever member minted last — a live session-equivalent
// credential nobody can see in their own listing and nobody can revoke from
// their own account. Minting is the moment this org is known to be moving to
// per-user rows, so it is the moment the shared one stops existing.
if !publish {
shared, err := orm.Get[schema.Key](db, id(owner, UserKeyName))
if err == nil {
if err := shared.DeleteCtx(ctx); err != nil {
return "", err
}
} else if !errors.Is(err, orm.ErrNotFound) {
return "", err
}
}
label := "Cloud API key"
if publish {
label = "Publishable key"
}
if err := write(ctx, db, row{
owner: owner,
name: name,
user: user,
scope: scope,
label: label,
access: access,
secret: secret,
now: now,
}); err != nil {
return "", err
}
return presented, nil
}
// DefaultKeyName and DefaultKeyLabel name the API key an organization's founder
// is issued when the org is founded: the row <org>/default, labelled "Default",
// held by the founder.
const (
DefaultKeyName = "default"
DefaultKeyLabel = "Default"
)
// Issue (re)mints the secret key filed in owner at name, held by user
// ("<org>/<name>") and labelled label, and returns both halves — the pk- its
// holder is known by and the sk- it authenticates with, revealed once. The row
// keeps the secret's digest and never the secret. Re-issuing the same (owner,
// name) replaces that row, so a rotation leaves no second live credential beside
// the one it replaced.
//
// No key is issued that would speak for an account in the admin org
// (ErrSuperAdminKey): the resolver would refuse it, and a SuperAdmin or platform
// machine signs in for a short-lived token instead.
func Issue(ctx context.Context, db orm.DB, owner, user, name, label string) (access, secret string, err error) {
if strings.TrimSpace(owner) == "" || strings.TrimSpace(user) == "" || strings.TrimSpace(name) == "" {
return "", "", fmt.Errorf("keys: owner, user and name are required")
}
if store.SuperAdminKey(&schema.Key{Owner: owner, User: user}) {
return "", "", ErrSuperAdminKey
}
access, secret = Mint("pk", ""), Mint("sk", "")
err = write(ctx, db, row{
owner: owner,
name: name,
user: user,
label: label,
access: access,
secret: secret,
now: time.Now().UTC().Format(time.RFC3339),
})
if err != nil {
return "", "", err
}
return access, secret, nil
}
// MintAccountKey (re)mints the credential a SERVICE ACCOUNT presents, at
// <owner>/<account>-key, and returns both halves (Issue). A service account's
// first credential and every rotation after it land on that ONE row.
//
// The row is what the resolvers read. The account's own User row holds no
// credential material at all — nothing resolves a secret from there, so a value
// written to it authenticates nobody however carefully it was hashed.
func MintAccountKey(ctx context.Context, db orm.DB, owner, account string) (access, secret string, err error) {
if strings.TrimSpace(owner) == "" || strings.TrimSpace(account) == "" {
return "", "", fmt.Errorf("keys: owner and account are required")
}
return Issue(ctx, db, owner, owner+"/"+account, account+"-key", "Service account key")
}
// row is one credential as a mint states it: who holds it, what it reaches, and
// the two halves it was minted with.
type row struct {
owner, name, user, scope, label, access, secret, now string
}
// write puts the credential row at (owner, name) — the ONE write behind every
// mint, and the ONE place that decides what a minted row says.
//
// It states the WHOLE row every time, so nothing of the credential it replaces
// can survive into it. Mint used to read the previous row and overwrite only the
// credential fields, which left State and ExpireTime describing the credential
// that was just replaced: re-minting onto a key that had run out or been switched
// off handed the holder a fresh sk- and a row that still said it was dead, so the
// key they were given authenticated nobody. A row built from scratch cannot
// inherit that, and a put lands on the same id whether or not one was there.
func write(ctx context.Context, db orm.DB, r row) error {
k := orm.New[schema.Key](db)
k.SetId(id(r.owner, r.name))
k.Owner, k.Name = r.owner, r.name
k.DisplayName = r.label
k.Type, k.User = "User", r.user
k.AccessKey = r.access
k.Prefix = schema.PrefixOf(cmp.Or(r.secret, r.access))
// The digest is what is written; the secret leaves with its holder and is
// never stored, so a leak of this table reveals nothing that can be replayed.
k.AccessSecret = ""
k.AccessSecretDigest = schema.DigestSecret(r.secret)
k.Scope = r.scope
k.State = "Active"
k.CreatedTime, k.UpdatedTime = r.now, r.now
return k.PutCtx(ctx)
}
// RevokeUserKey deletes the user's key row at `scope`. Absent is success — revoke is
// a statement about the END state, so a caller can always assert "this user holds no
// credential" without racing a prior revoke. Scoped, so revoking the browser key
// leaves the server key working and vice versa; and named by the same NameFor the
// mint used, so one member's revoke cannot reach another member's secret key.
func RevokeUserKey(ctx context.Context, db orm.DB, owner, user, scope string) error {
k, err := orm.Get[schema.Key](db, id(owner, NameFor(user, scope)))
if errors.Is(err, orm.ErrNotFound) {
return nil
}
if err != nil {
return err
}
return k.DeleteCtx(ctx)
}