mirror of
https://github.com/hanzoai/iam.git
synced 2026-11-21 11:41:56 +00:00
This repo is public and its LICENSE called the source "confidential and
proprietary ... All rights reserved". Public visibility contradicts
confidentiality, and HIP-0130 puts `iam` in the OSS core tier. The declaration
now matches both.
LICENSE-APACHE and LICENSE-MIT carry the canonical texts, unedited —
LICENSE-APACHE is byte-identical to apache.org/licenses/LICENSE-2.0.txt
(sha256 cfc7749b…, 11358 bytes, blob d645695). LICENSE declares the pair.
LICENSE-MIT carries the copyright line the notice requires.
249 Go files led with `// Copyright 2026 Hanzo AI, Inc. All rights reserved.`
— the classic proprietary reservation, and a per-file contradiction of the new
grant. Each now carries `// SPDX-License-Identifier: MIT OR Apache-2.0`. The
word "confidential" survives untouched in the OIDC sense (confidential client),
which is protocol vocabulary, not a licence claim.
There is nothing else to declare: `go.mod` has no licence field and this repo
ships no Cargo/npm/PyPI manifest.
Relicensing is ours alone to do. The tree is original work, not a fork:
`fork: false` with no parent, its own root commit, and no Casdoor-lineage tag
is an ancestor of `main`. The retired Casdoor fork is `hanzoai/iam-v1`; the
provenance note in LICENSE names it, restoring the vendor name a clean-room
assertion needs in order to say what it is clean of.
Build, vet and all 29 test packages green.
Co-authored-by: Hanzo Dev <[email protected]>
252 lines
9.9 KiB
Go
252 lines
9.9 KiB
Go
// Copyright 2026 Hanzo AI, Inc.
|
|
// SPDX-License-Identifier: MIT OR Apache-2.0
|
|
|
|
package registry
|
|
|
|
import (
|
|
"crypto/rand"
|
|
"crypto/rsa"
|
|
"crypto/sha256"
|
|
"crypto/x509"
|
|
"encoding/base32"
|
|
"encoding/base64"
|
|
"encoding/pem"
|
|
"errors"
|
|
"fmt"
|
|
"math/big"
|
|
"os"
|
|
"strings"
|
|
"sync"
|
|
"time"
|
|
|
|
"github.com/golang-jwt/jwt/v5"
|
|
)
|
|
|
|
// The registry-token signing key: ONE RSA key per process, its libtrust key id,
|
|
// and the two operations the endpoint performs with it — mint a Docker token and
|
|
// publish the verifying JWKS.
|
|
//
|
|
// This key is DELIBERATELY separate from the OIDC signing Certs (schema.Cert): a
|
|
// Docker Distribution verifier keys its ROOTCERTBUNDLE trust by the libtrust key
|
|
// id below and reads a token whose `iss` is the fixed "hanzo-iam" and whose `aud`
|
|
// is a bare string — a different HTTP contract from an OIDC access token (per-host
|
|
// `iss`, `aud` as an array). Reusing the OIDC Signer would emit the wrong shape
|
|
// and the registry would reject every token. So the registry carries its own key,
|
|
// loaded from the SAME source the deployment already trusts (envSigningKey /
|
|
// envSigningKeyFile), which is how cutover stays continuous: inject the current
|
|
// key material and the registry's existing ROOTCERTBUNDLE keeps verifying — no
|
|
// repoint. See LLM.md "registry-token continuity".
|
|
//
|
|
// Resolution is FAIL-CLOSED by default: with no key configured and no explicit
|
|
// dev opt-in (envAllowEphemeral), the process refuses to sign rather than mint a
|
|
// throwaway key the registry's ROOTCERTBUNDLE does not trust. Prod need set only
|
|
// the key; a dev box that wants a throwaway key sets envAllowEphemeral=true.
|
|
|
|
const (
|
|
// envSigningKey carries the PEM (PKCS#1 or PKCS#8) RSA registry signing key
|
|
// inline. The operator injects it from a KMSSecret-synced Secret — the one
|
|
// clean-room secret path (KMS → KMSSecret CR → k8s Secret → env), not an
|
|
// in-process KMS fetch.
|
|
envSigningKey = "REGISTRY_SIGNING_KEY"
|
|
// envSigningKeyFile is the path to a registered PEM file, when the operator registers
|
|
// the Secret as a file instead of an env var.
|
|
envSigningKeyFile = "REGISTRY_SIGNING_KEY_FILE"
|
|
// envAllowEphemeral, when "true", is the EXPLICIT dev opt-in that permits a
|
|
// throwaway signing key when none is configured. It is the ONLY thing that lets
|
|
// resolution mint an ephemeral key; absent it, a missing key FAILS CLOSED. This
|
|
// inverts the earlier (fail-open) default: production need set nothing special
|
|
// to be safe — a deploy that forgets the key is refused, not silently signing
|
|
// tokens the registry's ROOTCERTBUNDLE cannot trust. Mirrors the OIDC issuer
|
|
// resolver's IAM_DEV_HOST_RELATIVE opt-in for its loose path.
|
|
envAllowEphemeral = "REGISTRY_ALLOW_EPHEMERAL"
|
|
)
|
|
|
|
// issuer is the fixed `iss` every registry token carries. Docker Distribution
|
|
// matches it against its configured token issuer; it is NOT the per-host OIDC
|
|
// issuer (those tokens are a different audience shape).
|
|
const issuer = "hanzo-iam"
|
|
|
|
// tokenTTL is the registry token lifetime — short-lived, since a docker client
|
|
// re-authenticates per operation.
|
|
const tokenTTL = 15 * time.Minute
|
|
|
|
// keyring is the process registry signing key together with its libtrust key id.
|
|
// Immutable after construction: (key, kid) are fixed so a token can never be
|
|
// signed under a key whose id the header does not advertise.
|
|
type keyring struct {
|
|
key *rsa.PrivateKey
|
|
kid string
|
|
}
|
|
|
|
// newKeyring binds an RSA key to its libtrust key id — the value the JWKS `kid`
|
|
// and every token header carry, and the id the registry's ROOTCERTBUNDLE trusts.
|
|
func newKeyring(key *rsa.PrivateKey) *keyring {
|
|
return &keyring{key: key, kid: libtrustKeyID(&key.PublicKey)}
|
|
}
|
|
|
|
// libtrustKeyID computes the Docker/libtrust key id of an RSA public key: the
|
|
// first 240 bits (30 bytes) of SHA-256(PKIX DER of the public key), base32-encoded
|
|
// without padding and grouped into colon-separated quads (AAAA:BBBB:...). This is
|
|
// the exact scheme github.com/docker/libtrust uses, so the id equals the one the
|
|
// registry derives from its ROOTCERTBUNDLE cert for the same public key — the
|
|
// match that makes the token "signed by a trusted key" rather than rejected.
|
|
func libtrustKeyID(pub *rsa.PublicKey) string {
|
|
der, err := x509.MarshalPKIXPublicKey(pub)
|
|
if err != nil {
|
|
return ""
|
|
}
|
|
sum := sha256.Sum256(der)
|
|
s := strings.TrimRight(base32.StdEncoding.EncodeToString(sum[:30]), "=")
|
|
var b strings.Builder
|
|
b.Grow(len(s) + len(s)/4)
|
|
for i := 0; i < len(s); i += 4 {
|
|
if i > 0 {
|
|
b.WriteByte(':')
|
|
}
|
|
end := i + 4
|
|
if end > len(s) {
|
|
end = len(s)
|
|
}
|
|
b.WriteString(s[i:end])
|
|
}
|
|
return b.String()
|
|
}
|
|
|
|
// sign mints the Docker registry v2 token: a MapClaims that serializes to EXACTLY
|
|
// the Docker ClaimSet shape — `iss` fixed, `aud` a bare STRING (not the RFC 7519
|
|
// string-or-array), `exp`/`nbf`/`iat` integer seconds, and the `access` array —
|
|
// signed RS256 with the libtrust `kid` in the header. golang-jwt's typed
|
|
// RegisteredClaims would emit `aud` as an array and the registry rejects it with
|
|
// "cannot unmarshal array into ClaimSet.aud", so the map shape is load-bearing.
|
|
func (kr *keyring) sign(subject, service string, access []access, now time.Time) (string, error) {
|
|
jti, err := newJTI()
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
claims := jwt.MapClaims{
|
|
"iss": issuer,
|
|
"sub": subject,
|
|
"aud": service,
|
|
"exp": now.Add(tokenTTL).Unix(),
|
|
"nbf": now.Unix(),
|
|
"iat": now.Unix(),
|
|
"jti": jti,
|
|
"access": access,
|
|
}
|
|
tok := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
|
|
tok.Header["kid"] = kr.kid
|
|
return tok.SignedString(kr.key)
|
|
}
|
|
|
|
// publicJWKS is the JWKS the registry's ROOTCERTBUNDLE trust set reads: the public
|
|
// half of the one signing key as an RS256 RSA JWK, keyed by the libtrust `kid`.
|
|
func (kr *keyring) publicJWKS() map[string]any {
|
|
pub := &kr.key.PublicKey
|
|
return map[string]any{
|
|
"keys": []map[string]string{{
|
|
"kty": "RSA",
|
|
"alg": "RS256",
|
|
"use": "sig",
|
|
"kid": kr.kid,
|
|
"n": base64.RawURLEncoding.EncodeToString(pub.N.Bytes()),
|
|
"e": base64.RawURLEncoding.EncodeToString(big.NewInt(int64(pub.E)).Bytes()),
|
|
}},
|
|
}
|
|
}
|
|
|
|
// newJTI is a random 128-bit token id, base32 (no padding) — the unique `jti`.
|
|
func newJTI() (string, error) {
|
|
b := make([]byte, 16)
|
|
if _, err := rand.Read(b); err != nil {
|
|
return "", err
|
|
}
|
|
return base32.StdEncoding.WithPadding(base32.NoPadding).EncodeToString(b), nil
|
|
}
|
|
|
|
// processKeyring resolves THE registry signing key once per process, LAZILY — on
|
|
// first registry request, not at registration — and memoizes the (keyring, error). Lazy
|
|
// is load-bearing: registering the IAM surface (routes.Route, which every non-registry
|
|
// test also does) must NOT force key resolution, or a box without a registry key
|
|
// could not run the rest of IAM. Only an actual registry request resolves; a
|
|
// fail-closed resolution surfaces as a 503 on THAT request (no untrusted token
|
|
// ever minted), never a panic that takes the whole binary down.
|
|
var processKeyring = sync.OnceValues(resolveKeyring)
|
|
|
|
// resolveKeyring loads the signing key and decides the fallback, FAIL-CLOSED by
|
|
// default: a configured key (envSigningKey / envSigningKeyFile) is used; a
|
|
// configured-but-broken key is an error in every environment; and when NOTHING is
|
|
// configured, resolution ERRORS — no ephemeral key is minted — UNLESS the explicit
|
|
// dev opt-in envAllowEphemeral="true" is set. So a production deploy that forgets
|
|
// the key fails closed with no action required, and only a dev box that WANTS a
|
|
// throwaway key opts in.
|
|
func resolveKeyring() (*keyring, error) {
|
|
key, err := loadSigningKey()
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
if key != nil {
|
|
return newKeyring(key), nil
|
|
}
|
|
if !allowEphemeral() {
|
|
return nil, fmt.Errorf(
|
|
"no registry signing key: set %s or %s to the current KMS key (prod), "+
|
|
"or %s=true for a throwaway dev key",
|
|
envSigningKey, envSigningKeyFile, envAllowEphemeral)
|
|
}
|
|
// Explicit dev opt-in only: mint a throwaway key so a local box serves a
|
|
// coherent token+JWKS pair (the same key signs and verifies).
|
|
eph, err := rsa.GenerateKey(rand.Reader, 2048)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("ephemeral signing key: %w", err)
|
|
}
|
|
return newKeyring(eph), nil
|
|
}
|
|
|
|
// loadSigningKey resolves the persistent registry signing key from configuration,
|
|
// in order: envSigningKey (inline PEM), then envSigningKeyFile (a registered PEM).
|
|
// Returns (nil, nil) when NO source is configured — the caller decides whether an
|
|
// ephemeral dev key is acceptable. A configured-but-broken source is (nil, error),
|
|
// never silently skipped.
|
|
func loadSigningKey() (*rsa.PrivateKey, error) {
|
|
if inline := strings.TrimSpace(os.Getenv(envSigningKey)); inline != "" {
|
|
return parseRSAPEM([]byte(inline))
|
|
}
|
|
if path := strings.TrimSpace(os.Getenv(envSigningKeyFile)); path != "" {
|
|
data, err := os.ReadFile(path)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("read %s=%s: %w", envSigningKeyFile, path, err)
|
|
}
|
|
return parseRSAPEM(data)
|
|
}
|
|
return nil, nil
|
|
}
|
|
|
|
// allowEphemeral reports the explicit dev opt-in to mint a throwaway signing key
|
|
// when none is configured. Absent it, a missing key fails closed.
|
|
func allowEphemeral() bool {
|
|
return strings.EqualFold(strings.TrimSpace(os.Getenv(envAllowEphemeral)), "true")
|
|
}
|
|
|
|
// parseRSAPEM decodes a PEM RSA private key (PKCS#1 or PKCS#8). Registry tokens are
|
|
// RS256 by the Docker protocol, so this is RSA-only by design — it does not accept
|
|
// EC/ML-DSA keys the OIDC signer handles, which is why it is a small dedicated
|
|
// parser rather than a reuse of the (polymorphic, unexported) OIDC one.
|
|
func parseRSAPEM(data []byte) (*rsa.PrivateKey, error) {
|
|
block, _ := pem.Decode(data)
|
|
if block == nil {
|
|
return nil, errors.New("signing key is not valid PEM")
|
|
}
|
|
if k, err := x509.ParsePKCS1PrivateKey(block.Bytes); err == nil {
|
|
return k, nil
|
|
}
|
|
k8, err := x509.ParsePKCS8PrivateKey(block.Bytes)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("parse signing key: %w", err)
|
|
}
|
|
rk, ok := k8.(*rsa.PrivateKey)
|
|
if !ok {
|
|
return nil, errors.New("signing key is not RSA")
|
|
}
|
|
return rk, nil
|
|
}
|