Files
Darkhorse7starsandGitHub 9f52638aa8 oidc: an organization's application signs with its own cert, held in KMS and published in the org's own JWKS (#43)
An organization's applications now sign with the organization's own cert, under the
organization's own issuer, published only in the organization's own key set. Tenant
tokens never carry the platform issuer and never appear in platform discovery or the
platform JWKS; the platform trusts only platform issuers.

- Tenant cert: an org-owned cert row (Scope "tenant") whose RSA key IAM generates when an
  org admin of that org, or a SuperAdmin, creates it. The private half goes only to the
  host's keyring.Vault (server.UseVault; cloud keeps it in KMS under the org), never to the
  row, a response, a log or IAM_SIGNING_KEYS. No Vault installed: no tenant cert is created
  and none signs. At most 5 per org; a name may not equal any platform cert name.
- Issuer: https://<IAM_TENANT_ISSUER origin>/<org>, discovery and key set under it
  (`/.well-known/openid-configuration`, `/.well-known/jwks`). Unset: no tenant issuer, the
  paths answer 404. Boot refuses a tenant origin equal to or above a platform issuer.
- Reserved slugs (pkg/schema/slug.go): the hanzo.ai site's routes, IAM's root routes and the
  platform and brand names are not creatable as organizations and get no tenant issuer.
- IAM's own verifiers: userinfo, introspection and id_token_hint accept a tenant token only
  through that org's certs and exact issuer; every platform-authority path refuses one.
- Removed: the IAM_TENANT_SIGNING_CERT env fallback.

Testing: go generate, go vet ./... and go test ./... pass; CI test-amd64 passes. Two red
reviews: no break of the trust boundary. Known and accepted, fails closed: a tenant cert and
a platform cert created under one name in the same instant leave the org without that cert.
Risk: inert until a host installs a Vault and sets IAM_TENANT_ISSUER; org creation refuses 229
reserved names (8 existing orgs already hold one and get no tenant issuer).
How to revert: revert this commit.

Claude-Session: https://claude.ai/code/session_015XYKLn69gF4x75RWePpDBV
2026-11-20 20:13:44 -08:00

38 lines
4.3 KiB
Go

// Code generated by zipdoc; DO NOT EDIT.
package certs
import (
"github.com/zap-proto/zip"
)
func init() {
zip.Describe("github.com/hanzoai/iam/internal/certs DELETE /v1/iam/certs/:owner/:name", zip.Doc{
Description: "Removes a signing certificate. Tokens signed with it can no longer be\nverified, so retire it only once nothing is still presenting them.",
})
zip.Describe("github.com/hanzoai/iam/internal/certs GET /v1/iam/certs", zip.Doc{
Description: "Returns your organization's signing certificates, newest first — the keys\nthe tokens your applications verify are signed with. Private key material is\nmasked.\n\nYou see your own organization's certificates and no one else's; which\norganization that is comes from your credentials, not from the request, so a\nquery parameter can never widen the listing.",
Fields: map[string]string{
"Model[github.com/hanzoai/iam/pkg/schema.Cert].id": "Persisted fields",
},
})
zip.Describe("github.com/hanzoai/iam/internal/certs GET /v1/iam/certs/:owner/:name", zip.Doc{
Description: "Returns one signing certificate — its algorithm, its validity window and\nits public half. The private key is masked.",
Fields: map[string]string{
"Model[github.com/hanzoai/iam/pkg/schema.Cert].id": "Persisted fields",
},
})
zip.Describe("github.com/hanzoai/iam/internal/certs POST /v1/iam/certs", zip.Doc{
Description: "Adds a signing certificate your applications can verify tokens against\n— the call you make to stage the next one before a rotation. A name already\nused in your organization is refused.\n\nIt registers the certificate's IDENTITY: its name (which is the JWKS `kid`),\nits algorithm, its expiry. Key material does not travel this way and cannot:\nthe private key is not part of the Cert's JSON, so it is neither served here\nnor accepted here. It is supplied to the process by the deployment, under the\nname registered here (internal/keyring). Staging a rotation is therefore two\nhalves — this call names the key, and the deployment provides it.\n\nA cert created with scope \"tenant\" is the one exception, and it is the\norganization's own: IAM generates its key pair, keeps the private half in the\ndeployment's tenant key vault and stores the public half, so the organization's\napplications can sign with a key no platform verifier trusts. It is published\nonly in the organization's own key set, under the organization's own issuer.\nSend a lowercase name and, optionally, expireInYears; any key material in the\nrequest is refused. Its name may not be one a platform signing cert holds.",
Fields: map[string]string{
"Model[github.com/hanzoai/iam/pkg/schema.Cert].id": "Persisted fields",
},
})
zip.Describe("github.com/hanzoai/iam/internal/certs PUT /v1/iam/certs/:owner/:name", zip.Doc{
Description: "Changes a signing certificate's settings. What it is called does not\nchange, and neither does when it was added.\n\nA PUT here is a METADATA edit — display name, expiry, provider. It overlays\nonly the fields the request actually SET onto the loaded row: a field the JSON\nomits (or leaves at its zero value) keeps what the row holds, rather than\nblanking it. That is load-bearing, not a nicety. A read serves the public\nCertificate (Mask hides only PrivateKey and AccessSecret), so a client that\nreads a cert, changes one field, and writes it back sends the masked halves\nempty and every other field it did not touch at its zero value — and the old\nfull-struct overlay wrote all of those blanks back. Blanking CryptoAlgorithm\nalone drops the cert from the JWKS (oidc.Publishes turns false), so every\ntoken under its `kid` stops verifying; blanking Provider/Account/ExpireTime\nbreaks ACME renewal and expiry — all from a request that only meant to rename\nit. Absent-or-zero means \"unchanged\", so the deployment (key) and a rotation\n(cert) remain the only way key or published material changes; the metadata API\ncannot clear it.\n\nThe overlay is generic — it copies every set field, so a field nobody has added\nyet is carried without a line here — and leaves three things the request may\nnot move: the bound Model (id, createdAt, key, snapshot), the natural key\n(owner/name address the row, they do not mutate it), and the creation stamp.",
Fields: map[string]string{
"Model[github.com/hanzoai/iam/pkg/schema.Cert].id": "Persisted fields",
},
})
}