Xen.Utils.ApiKeyMinting 4.2.0

Xen.Utils.ApiKeyMinting

Delegated, self-service API keys: a caller asks for a key, and gets one carrying only the permissions someone has separately been granted the right to hand out.

Carries no framework dependencies. Permissions, policy names and subject claims are plain strings; persistence and the policy/endpoint catalogs are interfaces the host implements, with whatever it already uses. The ASP.NET binding lives in Xen.Utils.AspnetAuthorizationHelper.Minting.

The validity rule

A permission on a key is live only while an active grant still authorises that permission for the subject the key was minted under. Everything else follows from that:

• By default the minter changing role or leaving does not affect the key. Validity follows the rule, never the person - which is why keys are required to expire. For personal delegations see below.
• Withdrawing a grant suspends every key that depended on it, immediately and without touching those keys.
• Reinstating the grant revives them. The check matches on (subject, permission), not on the grant id recorded at mint time, because reinstating often means re-creating and that yields a new id.
• One key can span several subjects the caller holds (MintRequest.AdditionalSubjects), for someone with several roles. Each permission then records the subject backing it, and only that subject's grant decides whether it is live.

Keys that follow their minter

Some keys are personal delegations: "my script may do what I may do, as long as I may". Mint them with Validity = KeyValidity.FollowsMinter (and MintedBy set). Such a key's permissions are live only while the grant is active and the minter still holds the subject backing them, as the host's IMinterSubjectSource reports it. Losing the role suspends the key; regaining it revives it.

• Keys are KeyValidity.FollowsGrant unless asked otherwise, so existing keys and stores behave as before. Stores that should support personal keys persist MintedKey.Validity.
• Register IMinterSubjectSource with a lifetime the authorizer can consume (it is a singleton in the ASP.NET binding). Without it, minter-bound keys carry nothing: failing closed is the only safe reading of "follows the minter".
• Use grant-following keys for automation that must outlive any one person (a team's nightly sync), minter-following keys for personal scripts and tools.

Pieces

What the host provides

IMintingGrantStore          // grants; anything at all - EF, Dapper, a list
IMintedKeyStore             // issued keys
IApiKeyHasher               // must produce exactly what your auth layer will compare against
IPolicyRequirementCatalog   // policy name -> the permission sets that satisfy it
IEndpointPolicyCatalog      // optional: endpoints, so callers can pick those instead

IApiKeyHasher is the one worth care. If the stored hash is not byte-identical to what the authentication layer derives from a presented key, keys authenticate perfectly and then match nothing — a failure that looks nothing like its cause. The ASP.NET binding derives it from the API key standard for exactly that reason.

Two rules worth deciding out loud

• Union across grants. Holding two roles lets a caller combine their permissions onto one key, which is more capable than either grant alone. That is the simpler rule and almost certainly what you want, but it should be a decision, not an accident.
• Never-mintable permissions. Anything that bypasses your policies — an admin-like claim — belongs in MintingOptions.NeverMintablePermissions, in code, so no grants table can ever hand it out.