Files
zeekayandHanzo Dev b327b40a38 claims: email_verified, the issuer's assertion that a mailbox answered
An address is what a signup form typed; nobody had to hold it. Consumers gate
FUNDING on identity (cloud's starter credit is $5 a bot can mint), and no
signal for "this one was proven" reached them at all — so the money path had to
treat a typed address and a proven one as the same fact.

The claim is minted by IAM, which is the only party that ran the proof, and
restated at the edge as X-User-Email-Verified. Both spell absence as the
negative: omitempty on the wire, and a header written only for the true case.
That is the same shape every token minted before this claim carries, which is
why missing has to read as unverified — the alternative hands the answer to
every legacy token at once.

The name goes in Headers, not just beside it. Headers is what edge.Strip
deletes, so a name that is written and not listed is a name a client can send
and have believed; listing it is what makes the forgery impossible rather than
unlikely.

Co-authored-by: Hanzo Dev <[email protected]>
2026-08-01 22:13:01 -07:00

93 lines
4.6 KiB
Go

// The header contract: the decision, in transport.
//
// Whoever holds the EDGE role strips every identity header on ingress and rewrites
// it from verified claims. Everything behind reads them and forwards them unchanged.
// A consumer that writes one is a second authority (HIP-0519).
//
// Writing them is not MINTING. IAM mints — it signs the token, which is where the
// authority is created. The edge verifies one and restates it in a form a transport
// that cannot carry a token can read. Two operations, two words.
package authz
// The identity headers, named once by the party that writes their values.
//
// These are STRINGS, so naming them costs a consumer nothing: reading a header is
// the whole of what a service behind the edge does with identity. Minting them is
// the edge's job and lives in authz/edge, which links a transport — this package
// deliberately does not.
const (
HeaderOrg = "X-Org-Id"
HeaderWorkspace = "X-Workspace-Id"
HeaderProject = "X-Project-Id"
HeaderUser = "X-User-Id"
HeaderUserName = "X-User-Name"
HeaderUserEmail = "X-User-Email"
HeaderUserOwner = "X-User-Owner"
HeaderUserAdmin = "X-User-IsAdmin"
HeaderUserOrgAdmin = "X-User-IsOrgAdmin"
HeaderBillingAccount = "X-Billing-Account-Id"
HeaderRequestID = "X-Request-Id"
// HeaderUserEmailVerified restates [Claims.EmailVerified]: the issuer proved the
// address, not merely received it. It is written ONLY for the true case, so the
// value is always exactly "true" and ABSENCE IS THE NEGATIVE — the same wire
// shape a token minted before the claim existed produces, and the same one an
// unverified signup produces. A reader that treats missing as anything but false
// re-opens the hole for every legacy token at once.
//
// One value, never a general boolean: there is no "false" spelling to get wrong,
// no parse to disagree about, and a stripped header is indistinguishable from an
// unverified one — which is the correct outcome for both.
HeaderUserEmailVerified = "X-User-Email-Verified"
// HeaderScope carries the resolved LOCATION a request acts at, printed as a path
// (acme/prod/web), and HeaderScopeRole the role held there. This pair is why a
// token stays constant-size: the edge resolves the requested scope against the
// grant set ONCE, writes the outcome here, and no decision behind the edge performs
// I/O. The grant SET stays in IAM, which signs it; the resolved DECISION travels.
HeaderScope = "X-Scope"
HeaderScopeRole = "X-Scope-Role"
// HeaderUserPermissions carries the money authority as a bit-field: commerce
// gates every credit-creating and card-charging endpoint on it, with
// intersection semantics, so whoever carries the admin bit satisfies them all.
//
// It is named HERE, and stripped with the rest, because it is written at the edge
// and a forged copy would be believed. Its VALUE is not computed here: the bit
// vocabulary is a deployment's commerce contract, not part of what an identity
// IS, so the edge that holds that contract fills it in. Naming it without owning
// its value is the point — the strip list has to be complete even where the write
// is someone else's.
HeaderUserPermissions = "X-User-Permissions"
// HeaderApp is the application a request is attributed to — a caller LABEL, not
// an isolation boundary: nothing scopes access by it, and the org header bounds
// any mislabel to the caller's own subtree.
//
// It is named here anyway, because it is WRITTEN at an edge and the strip list has
// to be complete: a name an edge writes and ingress does not delete is a name a
// client can set. Being a label rather than a boundary is why forging it is cheap,
// not a reason to leave it forgeable.
HeaderApp = "X-App-Id"
)
// Headers is every header the edge writes, and therefore every header it must
// strip. A header that is written but not stripped is forgeable; the two lists
// being one list is what makes that impossible.
var Headers = []string{
HeaderOrg, HeaderWorkspace, HeaderProject,
HeaderScope, HeaderScopeRole,
HeaderUser, HeaderUserName, HeaderUserEmail, HeaderUserEmailVerified, HeaderUserOwner,
HeaderUserAdmin, HeaderUserOrgAdmin, HeaderUserPermissions,
HeaderBillingAccount, HeaderApp,
}
// Retired are header names an older edge wrote and no edge writes now. They are
// still STRIPPED, and exported so an edge can strip them: a name some consumer may
// still read is a name a client must not be able to set.
var Retired = []string{
"X-User-IsGlobalAdmin", "X-Roles", "X-User-Role", "X-User-Roles",
"X-Tenant-Id", "X-Phone-Number", "X-Org",
}