Files
wbin90620 f2cc8e2f43 Merge branch 'main' of https://github.com/hanzoai/iam into feat/agent-auth
# Conflicts:
#	LLM.md
#	internal/oidc/oidc.go
#	pkg/schema/audit_log.go
2026-11-09 12:55:01 -05:00

250 lines
13 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
// Package oidc serves the IAM OpenID Connect / OAuth2 surface on zip. The
// handlers are RAW zip handlers (func(c *zip.Ctx) error), not typed generics,
// because the auth surface needs query params, form bodies, redirects, and
// headers a JSON-in/JSON-out handler can't reach.
//
// The surface is the canonical hanzo.id contract, unchanged across the v1→v2
// backend swap: discovery + JWKS under .well-known, the oauth/{authorize,token,
// userinfo,logout} endpoints, and the native {get-app-login, auth/methods,
// login} the hosted UI calls. Tokens are signed JWTs (RS256 interop, ES/ML-DSA
// behind the same JWKS); every value is verified, never trusted.
package oidc
import (
"net/http"
"github.com/hanzoai/orm"
"github.com/zap-proto/zip"
)
// Canonical OIDC paths — the single source of truth the @hanzo/iam SDK and every
// existing relying party hard-code. iam serves them directly; the transition
// off v1 is a backend swap behind the same paths, never a parallel version.
const (
PathAuthorize = "/v1/iam/oauth/authorize"
PathToken = "/v1/iam/oauth/token"
PathUserInfo = "/v1/iam/oauth/userinfo"
PathLogout = "/v1/iam/oauth/logout"
PathJWKS = "/v1/iam/.well-known/jwks"
PathJWKSRoot = "/.well-known/jwks"
// PathDelegationKeys serves the public half of the delegation key to a client
// allowed to delegate, and to nobody else (delegate.go).
PathDelegationKeys = "/v1/iam/oauth/delegation/keys"
PathDiscovery = "/.well-known/openid-configuration"
PathDiscoveryV1 = "/v1/iam/.well-known/openid-configuration"
PathASMetadata = "/.well-known/oauth-authorization-server" // RFC 8414 (root)
PathASMetadataV1 = "/v1/iam/.well-known/oauth-authorization-server" // RFC 8414 (v1)
PathDevice = "/v1/iam/oauth/device" // RFC 8628 device authorization
// PathDeviceInfo names the application a pending user_code belongs to — what
// the approval page must show a human before they authorize it.
PathDeviceInfo = "/v1/iam/oauth/device/info"
// PathDeviceVerify is the user-facing device-approval PAGE (a route in the
// hosted SPA, on the application's sign-in origin: verificationOrigin), not an
// API path: RFC 8628's verification_uri is somewhere a human opens and signs
// in, which the JSON token API can never be.
PathDeviceVerify = "/login/oauth/device"
// PathAgentIdentity is where an agent registers to act for a person (WorkOS
// auth.md `agent_auth.identity_endpoint`, agent.go). Under the OAuth subtree
// because it is a protocol endpoint named by that profile, like token or device.
PathAgentIdentity = "/v1/iam/oauth/agent/identity"
)
// CodeLoginRequired is the STABLE machine-readable reason for "this needs a
// signed-in session and there isn't one". The human `msg` beside it is prose and
// several causes share it; a caller that must ROUTE on the cause — the device
// approval page deciding to show a sign-in form rather than an error — cannot
// parse prose.
//
// It exists because the alternative was a lie: an unauthenticated device approval
// used to fall through to the credential check and answer "organization, username
// and password are required", naming three fields that page has never rendered and
// never sends. An error must describe the thing the caller can actually do.
const CodeLoginRequired = "login_required"
// CodeAccountSelectionRequired is the `code` beside a session sign-in refused
// because several people are signed in on this browser and the request named none
// of them, or asked the person to choose (prompt=select_account): the page shows
// its account chooser and posts again naming the one picked (loginHint).
const CodeAccountSelectionRequired = "account_selection_required"
// CodeAccountNotPermitted is the `code` beside a sign-in refused because the
// account itself may not sign in — archived by an operator (isForbidden) or
// deleted — after its credential was proven. The client says the account is
// archived rather than reading it as a wrong password or a failed exchange.
const CodeAccountNotPermitted = "account_not_permitted"
// PathRefreshToken is the spelling signed-in clients POST their refresh to. It is
// the SAME handler as PathToken at a second address — grant_type=refresh_token
// travels in the body, so this is a second spelling of the endpoint, never a
// separate grant. Discovery advertises only PathToken.
//
// It is registered because callers hold it: refreshes arrive here continuously,
// and serving them anywhere else logs every signed-in session out. It is the only
// legacy token spelling kept — the Casdoor-era `access_token` path and the
// `/v1/iam/userinfo` spelling draw no traffic, so neither is registered.
const PathRefreshToken = "/v1/iam/oauth/refresh_token"
// Route registers the entire OIDC/OAuth2 surface on r, backed by db. This is the
//go:generate go run github.com/zap-proto/zip/cmd/zipdoc
// one entry point the route table calls — discovery, JWKS, the protocol
// endpoints, and the native surface are all bound here so it all lives in one
// place. r is the PUBLIC group (registered before the router's authentication
// Guard): the whole OIDC/OAuth + native surface is pre-authentication by
// construction, so membership in this group IS what makes it reachable without a
// bearer — there is no separate allow-list to keep in sync.
func Route(r *zip.Group, db orm.DB) {
// Discovery and the JWKS are each served at BOTH the root well-known path
// (RFC 8414 §3, where a bare-origin client and the gateway's default look)
// and the /v1/iam-prefixed path, matching the live hanzo.id surface. Both
// paths are the same handler over the same keys — one key set, two spellings
// of where to find it.
r.Raw(http.MethodGet, PathDiscovery, Discovery)
r.Raw(http.MethodGet, PathDiscoveryV1, Discovery)
// RFC 8414 OAuth Authorization Server Metadata — the same self-consistent
// document at the OAuth well-known path (a superset serves it), so an OAuth-only
// client that looks for `oauth-authorization-server` finds the AS too.
r.Raw(http.MethodGet, PathASMetadata, Discovery)
r.Raw(http.MethodGet, PathASMetadataV1, Discovery)
// One handler, two addresses: the same key set under the subsystem's prefix
// and at the host root, because a relying party configured with either must
// find it.
r.Raw(http.MethodGet, PathJWKS, jwksHandler(db))
r.Raw(http.MethodGet, PathJWKSRoot, jwksHandler(db))
// The delegation key, which the set above never carries: served only to a
// client allowed to delegate (delegate.go).
r.Raw(http.MethodGet, PathDelegationKeys, delegationKeysHandler(db))
// OAuth2 / OIDC protocol endpoints.
r.Raw(http.MethodGet, PathAuthorize, authorizeHandler(db))
r.Raw(http.MethodPost, PathAuthorize, authorizeHandler(db))
r.Raw(http.MethodGet, PathUserInfo, userinfoHandler(db))
r.Raw(http.MethodPost, PathUserInfo, userinfoHandler(db))
r.Raw(http.MethodGet, PathLogout, logoutHandler(db))
r.Raw(http.MethodPost, PathLogout, logoutHandler(db))
// The token endpoint, the credential login that mints codes, and the
// read-only endpoints the hosted <Login> self-configures from.
routeToken(r.Group(""), db)
routeLogin(r.Group(""), db)
routeFrontDoor(r, db)
// The two WebAuthn ceremonies: enroll a passkey, and sign in with one. Both
// are public — a passkey sign-in has no bearer to present, and the enrollment
// pair authenticates itself from the portal's session cookie.
routeWebauthn(r.Group(""), db)
// Identity federation: the external-IdP callback (Google/GitHub, …). The
// authorize endpoint kicks a federation off when the request names a
// `provider`; this registers the fixed return endpoint the IdP redirects to.
routeFederation(r.Group(""), db)
routeFederationMfa(r.Group(""), db)
// The two halves of the linking law: connect a provider to the account you
// already hold, and disconnect one.
routeLink(r.Group(""), db)
routeUnlink(r.Group(""), db)
// RFC 7662 introspection + RFC 7009 revocation — the standard token-management
// endpoints a resource server / confidential client uses (client-authenticated).
routeIntrospectRevoke(r.Group(""), db)
// RFC 8628 device authorization grant — the browserless CLI sign-in. The
// request endpoint is registered here; the poll rides the token endpoint and
// the approval rides the login endpoint, both already public above.
routeDevice(r.Group(""), db)
// Agent registration (WorkOS auth.md, service_auth only): an agent names the
// person it acts for, that person approves on the device page above, and the
// agent's poll and its later exchanges ride the token endpoint (agent.go).
routeAgent(r.Group(""), db)
// The confidential-client "act on behalf of a user" primitive (the console +
// keyless-AI proxies mint their forwarded bearer here). Authenticates the
// client itself, so it is not Bearer-gated.
routeIssueToken(r.Group(""), db)
// RFC 7591 dynamic client registration, for a deployment that turned it on
// (IAM_REGISTRATION): how an MCP client that holds no client_id gets one.
routeRegister(r.Group(""), db)
}
// Discovery returns the OpenID Connect discovery document — the one URL you
// point a standards-compliant client at so it can find every other endpoint on
// its own, instead of you configuring them by hand.
//
// It advertises only what is actually implemented, so a client that reads it
// cannot ask for a flow that will fail: the authorization-code flow, PKCE with
// S256, the supported grants, and the signing algorithms whose public keys the
// JWKS really publishes.
//
// The issuer is derived from the host you asked on and is the same value the
// tokens carry, so a client that pins the issuer never sees it change.
func Discovery(c *zip.Ctx) error {
iss, err := tokenIssuer(c)
if err != nil {
return c.JSON(503, map[string]string{"error": "temporarily_unavailable", "error_description": "this server has no issuer configured"})
}
// The document is fixed per host: the issuer comes from the trusted request
// host (part of every cache key), and nothing in it rotates — keys rotate in
// the JWKS, which keeps its own shorter lifetime. A sign-in page fetches this
// when a provider button is pressed, so a cached copy takes a round trip off
// every press.
c.SetHeader("Cache-Control", "public, max-age=3600")
doc := map[string]any{
"issuer": iss,
"authorization_endpoint": iss + PathAuthorize,
"token_endpoint": iss + PathToken,
"userinfo_endpoint": iss + PathUserInfo,
"introspection_endpoint": iss + PathIntrospect,
"revocation_endpoint": iss + PathRevoke,
"end_session_endpoint": iss + PathLogout,
"device_authorization_endpoint": iss + PathDevice,
"jwks_uri": iss + PathJWKS,
"response_types_supported": []string{"code"},
"response_modes_supported": []string{"query", "fragment", "form_post"},
"grant_types_supported": grantsSupported(iss),
// The sign-in modes a client may ask for. Advertised because a relying
// party CANNOT discover them by trying: a server that ignores prompt=none
// answers with a login page, which to the client is indistinguishable from
// a server that honoured it and found no session. Saying so here is what
// lets a client rely on the silent flow instead of guessing.
//
// `consent` is absent because there is no consent screen to show, and
// `create` because there is no signup-first mode on this endpoint. This
// document advertises only what is implemented.
"prompt_values_supported": promptValues,
"subject_types_supported": []string{"public"},
"id_token_signing_alg_values_supported": []string{"RS256", "RS512", "ES256", "ES384", "ES512", "MLDSA65"},
"scopes_supported": []string{"openid", "email", "profile", "address", "phone", "offline_access"},
"token_endpoint_auth_methods_supported": []string{"client_secret_basic", "client_secret_post", "none"},
"code_challenge_methods_supported": []string{"S256"},
"claims_supported": []string{
"iss", "sub", "aud", "iat", "exp", "nbf", "jti", "nonce", "azp", "act", "imp",
"owner", "organization", "scope", "tokenType",
// `name` and `preferred_username` are both the USERNAME here; the human's
// name is `displayName`. Advertising a claim nothing emits is what left
// consumers reading `name` as a display name for a year, so the list says
// exactly what a token carries.
"name", "preferred_username", "displayName", "email", "email_verified",
"picture", "address", "phone", "groups", "is_verified",
// The on-chain half of the same identity: the wallets this person
// proved control of, and the identifier derived from `sub`.
"wallets", "did",
},
}
// Advertised only where the endpoint is served: a client that reads it asks for
// a client_id there, and a 404 would be its answer.
if registration.Load() != nil {
doc["registration_endpoint"] = iss + PathRegister
}
// The auth.md bootstrap block, only where this issuer offers agent registration
// and only what is implemented (agentAuthMetadata).
if block := agentAuthMetadata(iss); block != nil {
doc["agent_auth"] = block
}
return c.JSON(200, doc)
}