Files
iam/internal/oidc/zipdoc_gen.go
zeekayandHanzo Dev 0b0b3941d4 A session-cookie write comes only from the issuer's own page, and a process with no issuer names none
The session cookie is SameSite=Lax, which keeps it off requests from other
sites but not from other hosts of the same site. Once hanzo.ai signs people
in, any page on any *.hanzo.ai host could post a form to /v1/iam/login with
type=device and approve an attacker's `hanzo login` code, or with type=code
mint an authorization code, or edit the account. sessions.Forgeable is now
the one rule for a write the cookie authorizes: Sec-Fetch-Site must be
same-origin or none, and a request with a body must carry it as JSON.
sessions.Writer resolves the session only past it, and every cookie write
goes through it: the login SSO and device branches, callerOf/callerFrom
(profile, password rotation, terms, consent, preferences, onboarding,
link, unlink, passkey enrollment), and invitation accept. A refused write
is 403 before the session is read. The passkey finish, which the challenge
cookie authorizes, asks the same rule. A bearer from a client that is not a
browser needs no fetch metadata, with or without a cookie riding along.

Signing out ends sessions, so sessions.Clear asks the rule too, with one
exception: a top-level navigation (Sec-Fetch-Mode navigate, Sec-Fetch-Dest
document), which is how a relying party signs a person out. An image, a
frame or a sibling's form ends nothing.

The federation binding cookie is __Host-hanzo_fed and only that name is
read; a test now pins that the bare hanzo_fed name is refused.

server.RequireIssuer is the boot check for issuers: it installs IAM_ISSUER
and IAM_ISSUER_MAP, then IAM_FEDERATION_ORIGIN_MAP, and returns an error for
an empty or non-https IAM_ISSUER (outside IAM_DEV_HOST_RELATIVE=1), a
malformed issuer map, or a sign-in map that would strand the binding. `iam
serve` calls it, and a host that embeds IAM must call it before NewApp.
devFallbackIssuer and the lazy env resolvers are gone: a process that never
installed an issuer has none, so every issuer read is an error, discovery
answers 503, no token is minted and none is accepted, where it used to
answer https://hanzo.id. No issuer value changes.

Co-authored-by: Hanzo Dev <[email protected]>
2026-10-17 19:45:43 -07:00

213 lines
38 KiB
Go

// Code generated by zipdoc; DO NOT EDIT.
package oidc
import (
"github.com/zap-proto/zip"
)
func init() {
zip.Describe("github.com/hanzoai/iam/internal/oidc DELETE /v1/iam/users/:owner/:name/keys", zip.Doc{
Description: "Clears the target user's key of the requested TYPE (immediate\nrevoke). Scoped by the same `?type` field mint takes, so revoking the browser key\nleaves the server key working. A secret key's stored value is the sk- in its\nschema.Key row.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /.well-known/jwks", zip.Doc{
Description: "Publishes the public keys that verify the tokens issued here — the\none URL you point a service at so it can check a token itself, offline, without\ncalling back and without holding any secret of ours.\n\nKeys appear here before they start signing and stay after they stop, so a\nrotation never leaves a live token unverifiable. Nothing private is ever\npublished.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /.well-known/oauth-authorization-server", zip.Doc{
Description: "Returns the OpenID Connect discovery document — the one URL you\npoint a standards-compliant client at so it can find every other endpoint on\nits own, instead of you configuring them by hand.\n\nIt advertises only what is actually implemented, so a client that reads it\ncannot ask for a flow that will fail: the authorization-code flow, PKCE with\nS256, the supported grants, and the signing algorithms whose public keys the\nJWKS really publishes.\n\nThe issuer is derived from the host you asked on and is the same value the\ntokens carry, so a client that pins the issuer never sees it change.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /.well-known/openid-configuration", zip.Doc{
Description: "Returns the OpenID Connect discovery document — the one URL you\npoint a standards-compliant client at so it can find every other endpoint on\nits own, instead of you configuring them by hand.\n\nIt advertises only what is actually implemented, so a client that reads it\ncannot ask for a flow that will fail: the authorization-code flow, PKCE with\nS256, the supported grants, and the signing algorithms whose public keys the\nJWKS really publishes.\n\nThe issuer is derived from the host you asked on and is the same value the\ntokens carry, so a client that pins the issuer never sees it change.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/.well-known/jwks", zip.Doc{
Description: "Publishes the public keys that verify the tokens issued here — the\none URL you point a service at so it can check a token itself, offline, without\ncalling back and without holding any secret of ours.\n\nKeys appear here before they start signing and stay after they stop, so a\nrotation never leaves a live token unverifiable. Nothing private is ever\npublished.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/.well-known/oauth-authorization-server", zip.Doc{
Description: "Returns the OpenID Connect discovery document — the one URL you\npoint a standards-compliant client at so it can find every other endpoint on\nits own, instead of you configuring them by hand.\n\nIt advertises only what is actually implemented, so a client that reads it\ncannot ask for a flow that will fail: the authorization-code flow, PKCE with\nS256, the supported grants, and the signing algorithms whose public keys the\nJWKS really publishes.\n\nThe issuer is derived from the host you asked on and is the same value the\ntokens carry, so a client that pins the issuer never sees it change.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/.well-known/openid-configuration", zip.Doc{
Description: "Returns the OpenID Connect discovery document — the one URL you\npoint a standards-compliant client at so it can find every other endpoint on\nits own, instead of you configuring them by hand.\n\nIt advertises only what is actually implemented, so a client that reads it\ncannot ask for a flow that will fail: the authorization-code flow, PKCE with\nS256, the supported grants, and the signing algorithms whose public keys the\nJWKS really publishes.\n\nThe issuer is derived from the host you asked on and is the same value the\ntokens carry, so a client that pins the issuer never sees it change.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/account", zip.Doc{
Description: "Returns the signed-in person's own account and the organization\nthey belong to — what a console reads to draw the account menu.\n\nPasswords, API secrets and MFA material are stripped. It answers for a session\ncookie or a bearer token alike.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/accounts", zip.Doc{
Description: "Returns the people signed in on this browser, the most recent\nsign-in first — what the sign-in page lists when an application asks the person\nto choose an account.\n\nIt reads the session cookie and nothing else, so it only ever answers the\nbrowser holding the sessions. An account forbidden or deleted since it signed\nin is left out. A browser with nobody signed in gets an empty list.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/auth/application", zip.Doc{
Description: "Returns everything a login screen needs to draw itself for one\napplication: its branding, and each sign-in method it offers with the provider\ndetails that method needs.\n\nThe client secret is masked. Read before anyone has signed in, so it carries\nonly what is safe for a browser to see.",
Fields: map[string]string{
"Response.code": "Code is a STABLE machine-readable reason, where the human `msg` is\ndeliberately generic. `msg` is prose for a person and several distinct causes\nlegitimately share one sentence; a caller that must BRANCH on the cause — or\ntell its own user which of them happened — cannot parse prose. Optional, so\nevery existing envelope is byte-identical and no SDK changes.",
"screen.clientId": "ClientId is the application's OAuth client id — the one field that selects\nwhich login screen this is.",
"screen.responseType": "ResponseType is the OAuth response type the screen will ask for. Only \"code\"\nis served; anything else is refused here rather than at the authorize leg,\nwhere the person has already typed a password.",
},
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/auth/methods", zip.Doc{
Description: "Returns the sign-in methods one application actually has switched\non, so a login screen can render the right buttons for it without you\nhard-coding a list that drifts the moment you add a provider.\n\nPublic by design: it is read before anyone has signed in, and it exposes only\nwhich methods exist, never their credentials.",
Fields: map[string]string{
"Response.code": "Code is a STABLE machine-readable reason, where the human `msg` is\ndeliberately generic. `msg` is prose for a person and several distinct causes\nlegitimately share one sentence; a caller that must BRANCH on the cause — or\ntell its own user which of them happened — cannot parse prose. Optional, so\nevery existing envelope is byte-identical and no SDK changes.",
"offer.clientId": "ClientId is the application's OAuth client id.",
},
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/consent", zip.Doc{
Description: "Returns the calling person's own privacy and communication\nchoices. Somebody who has never set them gets the defaults rather than\nnothing, so a consent screen always has something to show — insights on, and\ntraining UNANSWERED, which is the state that means the screen still has to ask.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/linked-accounts", zip.Doc{
Description: "Returns the sign-in identities linked to the calling\nperson's account — every provider they can currently sign in with. It is what\na security page lists next to the option to disconnect one.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/oauth/authorize", zip.Doc{
Description: "Starts a sign-in — the address you send a browser to, and the\nbeginning of every OAuth and OpenID Connect flow.\n\nIf the person is ALREADY signed in here, it does not ask them again: it\nreturns them to the application with a one-time code and they never see this\npage. Otherwise it shows the right way to sign in for the application they are\nsigning in to, or hands off to another identity provider if that is what they\npick.\n\nA client can say what it wants with `prompt`: `none` means answer without any\nscreen at all — with the code if a session exists, with an error if not, but\nnever with a page; `login` means ask for the password again even if a session\nexists; `select_account` means let the person choose among the accounts signed\nin on this browser, or sign in to another. `login_hint` names which of those\naccounts the request is for.\n\nIt returns only to an address the application has registered. That check\nhappens before anything else, so a request naming an unregistered address is\nrefused where the person can see it rather than being bounced onwards.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/oauth/callback", zip.Doc{
Description: "Completes the round-trip: it resolves and burns the\nsingle-use transaction (checking expiry + browser binding), exchanges and\nverifies the IdP response, links or provisions the local user, and mints the\niam authorization code the relying party expects — then redirects to the\noriginal redirect_uri with code + state.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/oauth/delegation/keys", zip.Doc{
Description: "Serves the public half of every delegation key, as a\nJWKS, to a confidential client allowed to delegate — the one resource server\nthat verifies what it is handed, reading with the credential it delegates with.\nTo anyone else it answers as the token endpoint does: who are you, or not you.\n\nThe key is not a secret; publishing it is the hazard. A verifier that fetches\nthe public JWKS and trusts what verifies would admit a delegated token as the\nperson. So it is not in that document, and this one is not an address a relying\nparty is ever pointed at.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/oauth/logout", zip.Doc{
Description: "Ends a sign-in and sends the browser somewhere sensible. Accepts\nGET or POST, so it works as a plain link.\n\nIt ACTUALLY signs you out — worth stating, because a logout that computes a\nredirect and answers {\"status\":\"ok\"} while ending no session and revoking no\ntoken is worse than none: the person on the shared machine believes it worked.\nThree things happen here, in this order:\n\n 1. The browser session dies — sid revoked server-side AND the cookie expired\n (sessions.Clear). Server-side revocation is the load-bearing half: a copy\n of the cookie taken before logout must not still resolve.\n 2. The relying party's tokens are revoked when an id_token_hint names it, so\n the refresh token cannot mint a fresh access token after the human left.\n Revocation state is authoritative — a JWT's `exp` still reads valid for\n days, so expiry is necessary but never sufficient.\n 3. Only then is a redirect considered, and only to a REGISTERED uri.\n\nThe open-redirect guard: a redirect happens only when a VERIFIED\nid_token_hint (or client_id) identifies the application and that application\nhas registered the target. Nobody can turn your logout link into a redirect to\na site of their choosing.\n\nA GET is the end-session navigation (OIDC RP-Initiated Logout 1.0 §2), so it\nalways ends on a page: the registered address when one was asked for, else\nthis issuer's sign-in page for the application being signed out of. A relying\nparty therefore needs no configuration to sign someone out. A POST is also how\na program signs out, so it keeps the JSON answer unless it asks for HTML.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/oauth/userinfo", zip.Doc{
Description: "Returns the profile claims for whoever the access token\nbelongs to — the standard OpenID Connect way to find out who is calling you\nwithout your application storing anything itself.\n\nThe token must still be live: revoke it and this stops answering.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/webauthn/signin/begin", zip.Doc{
Description: "Starts a passkey sign-in: it returns the challenge the person's\nauthenticator signs.\n\nThe account is named in the query, and the challenge is bound to it, so what may\nanswer is decided here — by the server, from the row — and the finish checks the\nanswer against that decision rather than recomputing it.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/webauthn/signup/begin", zip.Doc{
Description: "Starts enrolling a passkey for the signed-in person: it returns the\noptions their browser hands to the authenticator.\n\nPasskeys already on the account are EXCLUDED, so a second enrollment on a device\nthat already holds one is refused by the authenticator itself rather than\nsilently producing a duplicate the person cannot tell apart.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc GET /v1/iam/whoami", zip.Doc{
Description: "Tells you who the current caller is — the lightweight check a\npage makes on load to decide whether to render signed-in or signed-out.\n\nIt answers for a session cookie or a bearer token alike, and says plainly when\nnobody is signed in rather than failing.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/admin/provision", zip.Doc{
Description: "Founds an org on someone's behalf — the same onboarding\na person gets themselves, driven by one of your own services instead of by\nthem. The person keeps their account and owns the org by membership.\n\nIt authenticates as your service rather than as a person, which is why the\nperson to provision is named in the request. The setup it performs is\nidentical to self-service onboarding; there is one provisioning path, not\ntwo that can drift.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/assume", zip.Doc{
Description: "Steps a platform operator into an organization: it returns their\nown access token re-scoped to that tenant, so they see what the tenant sees.\n\nThe token still names the operator — stepping in is not becoming somebody\nelse — and records the organization it was scoped to, so everything done with\nit is attributed to the person who did it. Only a platform operator may, and\nthe attempt is recorded whether or not it succeeds.",
Fields: map[string]string{
"Response.code": "Code is a STABLE machine-readable reason, where the human `msg` is\ndeliberately generic. `msg` is prose for a person and several distinct causes\nlegitimately share one sentence; a caller that must BRANCH on the cause — or\ntell its own user which of them happened — cannot parse prose. Optional, so\nevery existing envelope is byte-identical and no SDK changes.",
},
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/auth/identifier", zip.Doc{
Description: "Answers whether an account holds an email address at an\napplication, and whether that account signs in with a password. Only an\napplication that registers strangers answers, since its signup says as much\nalready. The address is resolved exactly as sign-in resolves it, so the screen\nand the sign-in cannot disagree. A client asking faster than a person types is\nrefused with 429.",
Fields: map[string]string{
"Response.code": "Code is a STABLE machine-readable reason, where the human `msg` is\ndeliberately generic. `msg` is prose for a person and several distinct causes\nlegitimately share one sentence; a caller that must BRANCH on the cause — or\ntell its own user which of them happened — cannot parse prose. Optional, so\nevery existing envelope is byte-identical and no SDK changes.",
"identifierBody.clientId": "ClientId is the application's OAuth client id.",
"identifierBody.identifier": "Identifier is the email address the person typed.",
},
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/impersonate", zip.Doc{
Description: "Lets a SuperAdmin open an application signed in as somebody\nelse, to see what they see.\n\nIt returns a one-time login_hint for that application, good for a few minutes\nand only in a browser where the operator is signed in here. The token the\napplication finally receives belongs to the person, names the operator in `act`,\ncarries `imp`, lasts at most fifteen minutes and cannot be refreshed. A reason\nis required and every attempt is recorded, refused or not.",
Fields: map[string]string{
"Response.code": "Code is a STABLE machine-readable reason, where the human `msg` is\ndeliberately generic. `msg` is prose for a person and several distinct causes\nlegitimately share one sentence; a caller that must BRANCH on the cause — or\ntell its own user which of them happened — cannot parse prose. Optional, so\nevery existing envelope is byte-identical and no SDK changes.",
"impersonateBody.clientId": "ClientId is the application the operator will open as the target.",
"impersonateBody.reason": "Reason is why: a ticket, a sentence. Required — it is what the trail is for.",
"impersonateBody.target": "Target is the person, \"<owner>/<name>\". Body only, like the reason: a URL\nlands in access logs.",
},
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/invitations/accept", zip.Doc{
Description: "Joins the caller to an organization through an invitation, for\na person who already has an account. Signing up through the invitation is the\nother way in (signupHandler); this one spends the same seat under the same rules.\n\nOnly the caller joins, as a member and never more; the request names nobody\nelse. An invitation pinned to an address admits only the account holding that\naddress, and only with a code IAM sent to it for this join — the account's own\nverified flag is not enough, because a tenant's identity provider can set it. An\ninvitation pinned to a phone number or a username admits no other org's account\nthis way. Joining an org the caller already belongs to succeeds and spends\nnothing. Every refusal is recorded, and an account refused acceptLimit times in\nacceptWindow is refused before anything is looked at.",
Fields: map[string]string{
"Response.code": "Code is a STABLE machine-readable reason, where the human `msg` is\ndeliberately generic. `msg` is prose for a person and several distinct causes\nlegitimately share one sentence; a caller that must BRANCH on the cause — or\ntell its own user which of them happened — cannot parse prose. Optional, so\nevery existing envelope is byte-identical and no SDK changes.",
},
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/link", zip.Doc{
Description: "Starts connecting another sign-in identity to the account you are already\nsigned in as. It answers with the provider's URL for the browser to follow; when\nthe provider returns, that identity is attached and you come back to returnUri.\n\nYour account is fixed here, from the credential you are already holding, and is\ncarried server-side for the rest of the round-trip — so nothing that happens at\nthe provider can point the link at somebody else.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/login", zip.Doc{
Description: "Signs a person in with the credential they typed, and — when the\nrequest is part of an OAuth flow — hands back the one-time code that finishes\nit. A second factor, if the account has one, is asked for and required here.\n\nThe password is compared against a stored one-way hash and is never logged,\nechoed or stored as typed.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/oauth/authorize", zip.Doc{
Description: "Starts a sign-in — the address you send a browser to, and the\nbeginning of every OAuth and OpenID Connect flow.\n\nIf the person is ALREADY signed in here, it does not ask them again: it\nreturns them to the application with a one-time code and they never see this\npage. Otherwise it shows the right way to sign in for the application they are\nsigning in to, or hands off to another identity provider if that is what they\npick.\n\nA client can say what it wants with `prompt`: `none` means answer without any\nscreen at all — with the code if a session exists, with an error if not, but\nnever with a page; `login` means ask for the password again even if a session\nexists; `select_account` means let the person choose among the accounts signed\nin on this browser, or sign in to another. `login_hint` names which of those\naccounts the request is for.\n\nIt returns only to an address the application has registered. That check\nhappens before anything else, so a request naming an unregistered address is\nrefused where the person can see it rather than being bounced onwards.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/oauth/device", zip.Doc{
Description: "Starts a sign-in on a device with no browser and no keyboard —\na TV, a CLI, a headless box. It returns a short code to show the person and\nthe address to send them to on a phone or laptop.\n\nNothing is granted until a human approves it there; until then the code is\njust a pending request.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/oauth/device/info", zip.Doc{
Description: "Answers \"what am I approving?\" for a pending device code.\n\nThe approval page exists to tell a human WHICH application they are authorizing;\na page that names any other one defeats the control it implements. The client is\na property of the CODE, not of the page or of whatever app the browser happens\nto be signed in to, so it is read from the code's row here and nowhere else.\n\nRequires a signed-in session, and answers with the same ONE opaque refusal\napproveDevice uses. That is deliberate: the user_code is only 40 bits and is the\none secret in this flow, so an unauthenticated lookup — or one that\ndistinguished unknown from expired from already-approved — would be an oracle\nfor hunting live codes. Gated and opaque, it reveals strictly less than the\napproval the same caller could already attempt.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/oauth/federation/mfa", zip.Doc{
Description: "Completes a sign-in that came in through another identity\nprovider and still owes a second factor. The person supplies the factor here\nand the login finishes.\n\nThe account is fixed when the challenge is issued, not by the request, so no\none can redirect a half-finished login onto somebody else's account. A wrong\nfactor uses the challenge up: retrying means starting the sign-in again, the\nsame as a mistyped password.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/oauth/introspect", zip.Doc{
Description: "Answers whether an access token is still good, and what it\nis good for — the check a resource server of yours makes before honouring a\ntoken it did not mint.\n\nA token counts as active only if it verifies AND has not been revoked, so a\nrevoked token reads as dead here immediately rather than until it expires. A\ntoken that is unknown, expired or revoked answers simply that it is not\nactive, and nothing more — the endpoint is not a way to learn about tokens you\nwere not given.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/oauth/logout", zip.Doc{
Description: "Ends a sign-in and sends the browser somewhere sensible. Accepts\nGET or POST, so it works as a plain link.\n\nIt ACTUALLY signs you out — worth stating, because a logout that computes a\nredirect and answers {\"status\":\"ok\"} while ending no session and revoking no\ntoken is worse than none: the person on the shared machine believes it worked.\nThree things happen here, in this order:\n\n 1. The browser session dies — sid revoked server-side AND the cookie expired\n (sessions.Clear). Server-side revocation is the load-bearing half: a copy\n of the cookie taken before logout must not still resolve.\n 2. The relying party's tokens are revoked when an id_token_hint names it, so\n the refresh token cannot mint a fresh access token after the human left.\n Revocation state is authoritative — a JWT's `exp` still reads valid for\n days, so expiry is necessary but never sufficient.\n 3. Only then is a redirect considered, and only to a REGISTERED uri.\n\nThe open-redirect guard: a redirect happens only when a VERIFIED\nid_token_hint (or client_id) identifies the application and that application\nhas registered the target. Nobody can turn your logout link into a redirect to\na site of their choosing.\n\nA GET is the end-session navigation (OIDC RP-Initiated Logout 1.0 §2), so it\nalways ends on a page: the registered address when one was asked for, else\nthis issuer's sign-in page for the application being signed out of. A relying\nparty therefore needs no configuration to sign someone out. A POST is also how\na program signs out, so it keeps the JSON answer unless it asks for HTML.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/oauth/refresh_token", zip.Doc{
Description: "Exchanges what your application is holding for the tokens it\nneeds — the one-time code from a finished sign-in, a refresh token, or your\nown client credentials when the caller is a program rather than a person.\n\nA refresh returns a NEW refresh token and retires the one you sent. If a\nretired one is ever presented again the whole chain is revoked, on the\nassumption that a token which came back from the dead was copied — so a stolen\nrefresh token buys an attacker one use and costs them the session.\n\nResponses are never cached, by any hop.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/oauth/revoke", zip.Doc{
Description: "Retires a token before it expires — what you call when someone\nsigns out or a credential may have leaked.\n\nRevoking an access token kills that token. Revoking a REFRESH token kills the\nwhole chain it belongs to, so no further access tokens can be minted from it\nand every token already minted from it dies with it.\n\nA token that is not yours, or that never existed, answers success and does\nnothing — so the endpoint cannot be used to discover which tokens are real.\n\nPUBLIC clients revoke too, and must: sign-out is the only control a long-lived\nrefresh token has (RFC 7009 §2.1 — a public client identifies itself with\nclient_id). A browser app or CLI is a public PKCE client and holds no secret,\nand that includes the public half of a registration that keeps a secret for a\nbackend path, so requiring one here would leave signing out as a local delete —\nforgetting a credential that stays spendable for the rest of its lifetime.\n\nWidening authentication does not widen authority. The caller must still POSSESS\nthe token — and possession already permits USE, of which revocation is the\nstrict opposite — and the row must belong to the client that presents it. A\ncaller that did not prove the registration's secret revokes only a grant that\nwas itself established without it, so a public client_id buys the ability to\ndestroy exactly what its holder could otherwise spend.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/oauth/token", zip.Doc{
Description: "Exchanges what your application is holding for the tokens it\nneeds — the one-time code from a finished sign-in, a refresh token, or your\nown client credentials when the caller is a program rather than a person.\n\nA refresh returns a NEW refresh token and retires the one you sent. If a\nretired one is ever presented again the whole chain is revoked, on the\nassumption that a token which came back from the dead was copied — so a stolen\nrefresh token buys an attacker one use and costs them the session.\n\nResponses are never cached, by any hop.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/oauth/userinfo", zip.Doc{
Description: "Returns the profile claims for whoever the access token\nbelongs to — the standard OpenID Connect way to find out who is calling you\nwithout your application storing anything itself.\n\nThe token must still be live: revoke it and this stops answering.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/onboard", zip.Doc{
Description: "Finishes setting up the account of whoever is calling — it\ncreates their organization if they have none and puts them in it, so a person\nwho has just signed up lands somewhere they can work.\n\nIt always acts on the caller and never on somebody named in the request, so\nthere is no way to onboard another person's account through it.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/preferences", zip.Doc{
Description: "Saves the calling person's own settings and returns\nthe full set afterwards. Send only the settings you are changing — the rest\nare kept, so two screens can save at once without one undoing the other.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/release", zip.Doc{
Description: "Steps a platform operator back out: it returns their own access\ntoken with no organization assumed, which is the credential they had before\nthey stepped in. Recorded like the step in.",
Fields: map[string]string{
"Response.code": "Code is a STABLE machine-readable reason, where the human `msg` is\ndeliberately generic. `msg` is prose for a person and several distinct causes\nlegitimately share one sentence; a caller that must BRANCH on the cause — or\ntell its own user which of them happened — cannot parse prose. Optional, so\nevery existing envelope is byte-identical and no SDK changes.",
},
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/signin", zip.Doc{
Description: "Completes a sign-in: it exchanges the one-time code your\napplication was handed at the end of the login flow for a live session, and\nreturns the signed-in account.\n\nThe code works once. This is the call that turns a finished login into\nsomething your application can act on.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/signup", zip.Doc{
Description: "Creates an account from the sign-up form and applies the\napplication's own sign-up rules — whether self-service registration is open at\nall, and which fields it requires.\n\nThe password is hashed before it is stored and is never returned.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/tokens/issue", zip.Doc{
Description: "Mints an access token for the `?id=<owner>/<name>` target\nuser (optional `?aud=` resource, RFC 8707), issued by the authenticated +\nallow-listed confidential client. The token's subject + owner are the TARGET\nUSER's, so a resource server scopes on the validated owner claim to the user's\ntenant — indistinguishable from a token the user obtained directly. Response is\nthe camelCase `{accessToken, expiresIn}` body identity.ts consumes. Equivalent to\nthe RFC 8693 token-exchange grant, minus the subject_token proof (the console has\nthe user's id, not a token) — the reason this compat shim exists.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/unlink", zip.Doc{
Description: "Disconnects one sign-in identity from an account, so that provider can\nno longer be used to sign in as that person. Their account and every other way\nthey sign in are untouched. Two principals may do it, and\nonly two: the account holder itself, and a SuperAdmin (schema.User.SuperAdmin,\nasked of the caller's own row). An ORG ADMIN deliberately may NOT — unlinking\nis not tenant administration, it is unpicking someone's own sign-in method, so\nthe generic org-admin rule is the wrong answer here. A SuperAdmin unlinking\nsomeone else's method is recorded on the SuperAdmin trail.\n\nA holder unlinking itself must also be permitted by the application — the\nprovider link's CanUnlink flag — so an organization that mandates federated\nsign-in cannot have its users strand themselves. A SuperAdmin is not bound by\nthat flag; it is the platform's own recovery path. Fail-closed throughout.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/users/:owner/:name/keys", zip.Doc{
Description: "(re)generates the target user's key of the requested TYPE and\nreturns it once, over the shared authorizeMinter + mintTarget seam. `?type=secret`\n(the default) yields the confidential sk-; `?type=publishable` yields the pk- that\nis safe to ship in client JS and resolves to an org, never a principal.\n\nIt writes the schema.Key row that the resolvers actually read. schema.User.AccessKey\nis not a credential and nothing resolves it, so a key stamped there would\nauthenticate nobody.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/verification-codes", zip.Doc{
Description: "Validates the request and asks otp to get a code to the\nperson. The request fields are read via fiber's FormValue — the escape hatch zip\nexposes for form bodies (multipart or urlencoded) — since the typed JSON Bind does\nnot apply here. v1 also accepts countryCode/method/checkUser/captchaType; iam\nignores them (the captcha/forget/MFA flows those drive are not ported), and\nCAPTCHA verification is likewise not enforced — iam models no captcha provider —\nso the code is issued once the destination and application validate.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/webauthn/signin/finish", zip.Doc{
Description: "Verifies the signed challenge and signs the person in.\n\nIt answers exactly as a password sign-in does — the same envelope, through the\nsame grant — so nothing downstream branches on how somebody arrived.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc POST /v1/iam/webauthn/signup/finish", zip.Doc{
Description: "Verifies the newly created passkey and stores it, so the person\ncan sign in with their device from then on.\n\nOnly this site's own pages may finish an enrollment, and only as JSON.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc PUT /v1/iam/account", zip.Doc{
Description: "Saves the calling person's own profile — the name they are\nshown by, their picture, a line about themselves and a link.\n\nOnly their own: the request names nobody, so it cannot reach another account.\nSend only what you are changing; a field you leave out keeps the value it had,\nand a field you send empty is cleared.\n\nA picture is an https link or an inline image up to 96 KiB, the same value an\norganization's mark is (schema.AvatarRef) — one rule for how a subject appears,\nwhether the subject is a person or an organization.",
Fields: map[string]string{
"Response.code": "Code is a STABLE machine-readable reason, where the human `msg` is\ndeliberately generic. `msg` is prose for a person and several distinct causes\nlegitimately share one sentence; a caller that must BRANCH on the cause — or\ntell its own user which of them happened — cannot parse prose. Optional, so\nevery existing envelope is byte-identical and no SDK changes.",
},
})
zip.Describe("github.com/hanzoai/iam/internal/oidc PUT /v1/iam/consent", zip.Doc{
Description: "Records the calling person's privacy and communication\nchoices. Only their own — there is no way to set consent for somebody else.\n\nSend only the answers you are changing. A question you leave out keeps the\nanswer it already had, so a screen that saves one switch never revokes the\nother, and two screens saving at once do not undo each other.\n\nAn answer this version does not recognize is refused here rather than stored,\nso nothing is ever persisted for a later reader to have to interpret.",
})
zip.Describe("github.com/hanzoai/iam/internal/oidc PUT /v1/iam/password", zip.Doc{
Description: "Replaces the calling person's password. Only their own —\nthere is no shape of this request that writes somebody else's.\n\nProve who you are with the password you are replacing, or — when you cannot\nsign in at all — with a code sent to the address the account already holds.\nExactly one of the two: a request carrying both proves nothing more than\neither, and answering it would mean deciding which one mattered.\n\nA reset also clears the account lockout, in the SAME transaction as the\ndigest. Replacing a credential retires the run of guesses against the old one,\nand without this a person who reset a forgotten password was still refused for\nup to fifteen more minutes — with the brand-new password they had just chosen.",
Fields: map[string]string{
"Response.code": "Code is a STABLE machine-readable reason, where the human `msg` is\ndeliberately generic. `msg` is prose for a person and several distinct causes\nlegitimately share one sentence; a caller that must BRANCH on the cause — or\ntell its own user which of them happened — cannot parse prose. Optional, so\nevery existing envelope is byte-identical and no SDK changes.",
"passwordBody.code": "Code is the one-time code delivered to the account's own address.",
"passwordBody.oldPassword": "OldPassword is the credential being replaced, the proof a signed-in caller\ngives instead of a code.",
"passwordBody.organization": "The account being recovered, for a caller who cannot be signed in. Read on\nthe CODE arm only — a signed-in caller is resolved from its own session or\ntoken, never from these.",
"passwordBody.password": "Password is the new credential. It must satisfy the platform floor and the\norganization's own complexity options.",
"passwordBody.username": "email, username OR phone",
},
})
zip.Describe("github.com/hanzoai/iam/internal/oidc PUT /v1/iam/terms", zip.Doc{
Description: "Records that the signed-in caller accepted the terms and the\nacceptable use policy, at the versions named. It is how a person who arrived by\na social provider, whose account the callback already made, records the same\nacceptance a code sign-up records at creation. Only the caller's own row is\nreachable.",
Fields: map[string]string{
"Response.code": "Code is a STABLE machine-readable reason, where the human `msg` is\ndeliberately generic. `msg` is prose for a person and several distinct causes\nlegitimately share one sentence; a caller that must BRANCH on the cause — or\ntell its own user which of them happened — cannot parse prose. Optional, so\nevery existing envelope is byte-identical and no SDK changes.",
},
})
}