Files
wbin90620 aaa020f072 agent: an agent registers for a person, who approves it into a service account
WorkOS auth.md agent registration, the service_auth shape only. An agent
names its person's email at POST /v1/iam/oauth/agent/identity (no
credential) and gets a claim_token, stored only as its SHA-256, and a user
code. The person approves on the device page they already use, under a
stricter rule than a device sign-in: only the account whose verified email
is the login_hint, and only an admin of a tenant home org, checked at
approval and again at the claim.

The agent polls the token endpoint with the claim grant and is answered as
a device is. On approval, once, a service account is filed in the person's
org (no sk- key, its tag the registration) with an agent-claim audit row,
and the answer is its access token and a 7-day identity_assertion, never a
refresh token. jwt-bearer exchanges that assertion for a fresh token for as
long as the account exists; deleting it revokes the agent. Any other
jwt-bearer assertion is the workload grant's, unchanged.

A registration is a device row named ag-<reg>: the device poll never
redeems one, the claim poll never redeems a device row, and neither is an
authorization code. Discovery carries agent_auth only where
IAM_AGENT_SKILL_MAP names the issuer, and only what is implemented: no
anonymous, no identity_assertion, no claim or events endpoint.
IAM_AGENT_CLIENT names the app registrations belong to; the boot refuses
half a configuration.

Refs hanzo-inc/app#85
2026-11-09 05:30:57 -05:00

137 lines
7.2 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
package schema
import (
"slices"
"strings"
"github.com/hanzoai/orm"
)
// Inference is the scope of a DELEGATED token: one a confidential client obtained
// for a person so that a process it runs on their behalf can make model calls,
// and do nothing else (iam LLM.md "Delegation").
//
// A token whose scope names it is CONFINED. A resource server serves it only the
// addresses that answer a model call, and IAM accepts it as a bearer nowhere on
// its own surface. A scope only ever narrows, so the rule holds for any token that
// names it, however it was minted: a person who asks for it at sign-in confines
// their own token and gains nothing.
const Inference = "ai:inference"
// Confined reports whether scope — the space-separated OAuth list (RFC 6749
// §3.3) — names Inference.
func Confined(scope string) bool {
return slices.Contains(strings.Fields(scope), Inference)
}
// Token is an issued OAuth2/OIDC token record (v1 the legacy surface `token`, v2 kind
// "tokens"). One row is the authorization-server's persistent memory of a
// single grant: the short-lived authorization code and its PKCE challenge, the
// minted access and refresh tokens (stored verbatim for reissue plus as salted
// hashes for constant-shape lookup), the scope, token type, lifetimes, and the
// RFC 8707 resource indicator that binds the grant to an audience. It ties an
// application, its organization, and the authenticated user together for the
// life of the session. Field complete against the v1 row so no credential,
// challenge, or lifetime is lost on migration — a dropped field here is lost
// auth state. Identity is the (Owner, Name) pair; the orm string key is
// "owner/name".
//
// Code, AccessTokenHash, and RefreshTokenHash carry orm:"index": v1 resolves a
// live grant by presented code or by the hash of a bearer/refresh token, so
// those columns are the hot lookup paths and stay indexed. Owner, Name, and
// CreatedTime are indexed for owner-scoped listing in newest-first order.
// AccessToken and RefreshToken are the full secret material (v1 mediumtext) and
// are left unindexed — lookups go through the hash siblings, never the plaintext.
type Token struct {
orm.Model[Token]
Owner string `json:"owner" orm:"index"`
Name string `json:"name" orm:"index"`
CreatedTime string `json:"createdTime" orm:"index" url:"-"`
Application string `json:"application"`
Organization string `json:"organization"`
User string `json:"user"`
Code string `json:"code" orm:"index" url:"-"`
UserCode string `json:"userCode,omitempty" orm:"index" url:"-"`
AccessToken string `json:"accessToken" url:"-"`
RefreshToken string `json:"refreshToken" url:"-"`
AccessTokenHash string `json:"accessTokenHash" orm:"index" url:"-"`
RefreshTokenHash string `json:"refreshTokenHash" orm:"index" url:"-"`
ExpiresIn int `json:"expiresIn" url:"-"`
Scope string `json:"scope" url:"-"`
TokenType string `json:"tokenType" url:"-"`
CodeChallenge string `json:"codeChallenge" url:"-"`
CodeChallengeMethod string `json:"codeChallengeMethod" url:"-"`
CodeIsUsed bool `json:"codeIsUsed" url:"-"`
CodeExpireIn int64 `json:"codeExpireIn" url:"-"`
Resource string `json:"resource" url:"-"` // RFC 8707 resource indicator
// Denied records that the person a device authorization (UserCode set) was shown
// to refused it. The device's next poll is told access_denied once and the
// code is burned (device.go); until then it cannot be approved.
Denied bool `json:"denied,omitempty" url:"-"`
// Where and when a device authorization was STARTED, shown to the person asked to
// approve it: the device is the requester's, not theirs, and the one thing a
// stranger's request cannot hide is that it comes from somewhere else. RequestIp is
// the address the edge saw connect, RequestCountry the edge's two-letter answer
// for it, Requested the unix second. Polled is the last poll in unix milliseconds,
// which is what the interval of RFC 8628 §3.5 is held to.
RequestIp string `json:"requestIp,omitempty" url:"-"`
RequestCountry string `json:"requestCountry,omitempty" url:"-"`
Requested int64 `json:"requested,omitempty" url:"-"`
Polled int64 `json:"polled,omitempty" url:"-"`
// LoginHint is the address an agent registration (internal/oidc agent.go) named
// as the person it acts for, normalized. Only the account whose VERIFIED email is
// this address may approve the registration; empty on every other row.
LoginHint string `json:"loginHint,omitempty" url:"-"`
// RedirectUri binds the authorization code to the exact redirect URI of the
// authorize request (RFC 6749 §4.1.3): the token endpoint refuses a code
// redeemed with a different redirect_uri, closing code-injection across a
// client's registered URIs.
RedirectUri string `json:"redirectUri,omitempty" url:"-"`
// Nonce is the OIDC authorize nonce, stored on the code and echoed into the
// id_token minted at the exchange (OIDC Core §3.1.3.6) so a relying party
// binds the id_token to its own request and detects replay.
Nonce string `json:"nonce,omitempty" url:"-"`
// Refresh-token rotation state (v2). Each refresh belongs to a family (the
// grant); rotation mints a new row in the same family and marks the prior
// one consumed. Presenting a consumed refresh is reuse — the whole family is
// revoked (RFC 9700 §4.14.2). RefreshExpireIn is the refresh token's own
// absolute expiry (unix), independent of the access token's shorter life.
RefreshFamily string `json:"refreshFamily,omitempty" orm:"index" url:"-"`
RefreshConsumed bool `json:"refreshConsumed,omitempty" url:"-"`
RefreshExpireIn int64 `json:"refreshExpireIn,omitempty" url:"-"`
// PublicGrant records that this grant was established WITHOUT client
// authentication — a PKCE code exchange from a client that presented no
// secret. Whether a client is confidential is a property of the GRANT, not
// only of the registration: `hanzo-cli` and every @hanzo/iam SPA keep a
// registered secret for a BACKEND path while the surface that actually signs
// in is a public PKCE client that cannot hold one. authorizationCodeGrant
// already makes exactly that bounded relaxation; this is the same fact,
// recorded so refreshTokenGrant can honour it instead of demanding a secret
// the client never had (which 401s invalid_client and kills the session at
// the access token's expiry). Carried across rotation, so the second refresh
// behaves like the first.
PublicGrant bool `json:"publicGrant,omitempty" url:"-"`
// Actor is the SuperAdmin ("owner/name") who opened this grant AS its User —
// impersonation, /v1/iam/impersonate — and Reason is why they said they did.
// Both empty on every grant a person established themselves. A grant with an
// Actor mints a short access token that names the actor in `act` and carries
// `imp`, and never a refresh token (issueTokens), and /v1/iam/signin refuses
// its code, so it cannot become a session at the issuer.
Actor string `json:"actor,omitempty" url:"-"`
Reason string `json:"reason,omitempty" url:"-"`
}