mirror of
https://github.com/hanzoai/ai.git
synced 2026-11-20 14:13:23 +00:00
Every billing refusal is object.BillingError: message, type, code, class, model, topup_url, actions. The wallet's refusal (denied), the policy's (limitReached) and the hold inside a handler (ApiController.refuseFunds: chat, images, speech, embeddings, video) write it, and refuse puts X-Hanzo-Usage, X-Hanzo-Usage-Reason and X-Hanzo-Topup-Url on every 402 that lacks them. The handover of a signed-in app's Free chat to Enso is the host's call per class (object.SetHandover); with no hook it stays on. Off for a class the app gets the 402 a program gets. /v1/models rows carry endpoint, the path the model is called at, so a chat picker lists the rows whose endpoint is /v1/chat/completions. Claude-Session: https://claude.ai/code/session_015XYKLnjAuGqkk4ssA1Jusy
501 lines
19 KiB
Go
501 lines
19 KiB
Go
// Copyright 2023-2025 Hanzo AI Inc. All Rights Reserved.
|
|
// Portions Copyright 2023 The OpenAgent Authors. All Rights Reserved.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
|
|
package controllers
|
|
|
|
import (
|
|
"crypto/sha256"
|
|
"encoding/hex"
|
|
"errors"
|
|
"fmt"
|
|
"net"
|
|
"net/http"
|
|
"strings"
|
|
|
|
"github.com/hanzoai/ai/conf"
|
|
"github.com/hanzoai/ai/i18n"
|
|
iam "github.com/hanzoai/ai/internal/iam"
|
|
"github.com/hanzoai/ai/log"
|
|
"github.com/hanzoai/ai/object"
|
|
"github.com/hanzoai/ai/util"
|
|
"github.com/zap-proto/zip"
|
|
)
|
|
|
|
type Response struct {
|
|
Status string `json:"status"`
|
|
Msg string `json:"msg"`
|
|
Code string `json:"code,omitempty"` // machine name of the failure; clients switch on this, never on Msg
|
|
Data any `json:"data"`
|
|
Data2 any `json:"data2"`
|
|
}
|
|
|
|
func (c *ApiController) ResponseOk(data ...any) {
|
|
resp := Response{Status: "ok"}
|
|
switch len(data) {
|
|
case 2:
|
|
resp.Data2 = data[1]
|
|
fallthrough
|
|
case 1:
|
|
resp.Data = data[0]
|
|
}
|
|
c.JSON(http.StatusOK, resp)
|
|
}
|
|
|
|
// ResponseError writes the envelope with HTTP 200: the admin contract, where the
|
|
// envelope's own Status field carries the failure and the transport says nothing.
|
|
// The React admin reads that field, so this is the shape it expects.
|
|
func (c *ApiController) ResponseError(error string, data ...any) {
|
|
c.ResponseErrorWithStatus(http.StatusOK, error, data...)
|
|
}
|
|
|
|
// ResponseErrorWithStatus writes the envelope with an explicit HTTP status, which
|
|
// is what the OpenAI-compatible /v1 handlers need: a missing or invalid Bearer
|
|
// token is a 401 on the wire, not a 200 carrying a sad sentence.
|
|
//
|
|
// The status is an ARGUMENT of the write, and has to be. This used to set it on
|
|
// the response and then call ResponseError to write the body — but a write takes
|
|
// the status too, so the second one silently replaced the first with 200 and every
|
|
// refusal in the service answered OK. A denial that arrives as a success is worse
|
|
// than an outage: the client reads 200 and believes it.
|
|
func (c *ApiController) ResponseErrorWithStatus(status int, error string, data ...any) {
|
|
resp := Response{Status: "error", Msg: error}
|
|
switch len(data) {
|
|
case 2:
|
|
resp.Data2 = data[1]
|
|
fallthrough
|
|
case 1:
|
|
resp.Data = data[0]
|
|
}
|
|
c.JSON(status, resp)
|
|
}
|
|
|
|
// apiError carries an HTTP status alongside the message so the OpenAI-compatible
|
|
// handlers map auth / billing / validation failures to the right code instead of
|
|
// The router's default 200 (ServeJSON never sets a status). The shared auth+routing
|
|
// policy (authResolveProvider and the resolveProvider* functions it composes)
|
|
// returns exactly one category per failure, so the status is unambiguous:
|
|
//
|
|
// authError 401 unknown / invalid key, bad JWT, IAM lookup failure
|
|
// billingError 402 valid key, insufficient / starter-only balance
|
|
// forbiddenError 403 valid principal, org selection they may not bill
|
|
// modelError 400 valid key, model not in the routing table
|
|
// supplyError 503 the caller is fine; WE cannot buy the inference right now
|
|
// serverError 500 provider misconfig or balance lookup transport failure
|
|
//
|
|
// busyError (429) also travels this way but is not an auth outcome: it is raised
|
|
// AFTER the policy has admitted the caller, by the capacity check that stands
|
|
// between a valid request and work the service cannot currently do.
|
|
//
|
|
// Fail-secure: an untyped error reaching statusOf defaults to 401 (deny), never
|
|
// 200 (grant).
|
|
type apiError struct {
|
|
status int
|
|
msg string
|
|
// code names the failure for a program. A message is written for a person and
|
|
// gets rewritten; a status answers several different questions at once (503 is
|
|
// both "our upstream refused" and "we could not read your balance"). Only this
|
|
// is safe to branch on, which is why the shapes that need telling apart carry
|
|
// one and the rest carry nothing rather than something invented.
|
|
code string
|
|
}
|
|
|
|
func (e *apiError) Error() string { return e.msg }
|
|
|
|
func authError(format string, a ...any) error {
|
|
return &apiError{status: http.StatusUnauthorized, msg: fmt.Sprintf(format, a...)}
|
|
}
|
|
|
|
func billingError(format string, a ...any) error {
|
|
return &apiError{status: http.StatusPaymentRequired, msg: fmt.Sprintf(format, a...), code: object.CodeInsufficientBalance}
|
|
}
|
|
|
|
// refuseFunds answers 402 insufficient_balance for a call whose hold the wallet cannot
|
|
// cover, in the one billing error object the gate writes (object.BillingNotice:
|
|
// code, class, model, topup_url, actions) with the top-up headers. A caller reads the
|
|
// same refusal whether the gate in front of the handler or the hold inside it refused.
|
|
func (c *ApiController) refuseFunds(ledger, noun, model string) {
|
|
n := object.InsufficientBalance(c.Host(), ledger, noun).For(model, ClassOf(model))
|
|
for k, v := range n.Headers() {
|
|
c.SetHeader(k, v)
|
|
}
|
|
c.SetHeader("Content-Type", "application/json")
|
|
c.Bytes(n.Status, n.ErrorJSON())
|
|
}
|
|
|
|
// codeSupply names the refusal where WE cannot buy: our account with a vendor is
|
|
// spent, or our own cash breaker is holding. The caller's wallet is untouched.
|
|
//
|
|
// It is a separate code from CodeInsufficientBalance rather than a separate status
|
|
// alone, because the status is what a person sees and the code is what a program
|
|
// acts on. A client that switches on insufficient_balance offers a top-up — which
|
|
// is the right move for a caller who owes money and exactly the wrong one for a
|
|
// caller who owes nothing and is being told to pay our bill.
|
|
const codeSupply = "supply_unavailable"
|
|
|
|
// supplyError is 503: the request is well formed, the credential is valid, the
|
|
// balance is funded, and we still cannot serve it because OUR side cannot pay.
|
|
//
|
|
// Not 402. 402 says the caller owes money, which is false here, and a client that
|
|
// acts on it goes and tops up a balance that is already funded — the expensive
|
|
// half of this being wrong. Not 500 either: nothing is broken, the condition
|
|
// clears on its own or when somebody tops an account up, and 503 is the status
|
|
// that says "try again" rather than "file a bug".
|
|
func supplyError(format string, a ...any) error {
|
|
return &apiError{status: http.StatusServiceUnavailable, msg: fmt.Sprintf(format, a...), code: codeSupply}
|
|
}
|
|
|
|
// forbiddenError is 403: the credential is VALID and the caller is known — they
|
|
// simply may not act in the org they asked for. Distinct from authError (401,
|
|
// "who are you") and billingError (402, "you owe money"), because answering an
|
|
// unauthorized org selection with either of those tells the caller something
|
|
// untrue about their own credential. Unauthorized and nonexistent orgs share
|
|
// this one status so the ask cannot enumerate orgs.
|
|
func forbiddenError(format string, a ...any) error {
|
|
return &apiError{status: http.StatusForbidden, msg: fmt.Sprintf(format, a...)}
|
|
}
|
|
|
|
func modelError(format string, a ...any) error {
|
|
return &apiError{status: http.StatusBadRequest, msg: fmt.Sprintf(format, a...)}
|
|
}
|
|
|
|
func serverError(format string, a ...any) error {
|
|
return &apiError{status: http.StatusInternalServerError, msg: fmt.Sprintf(format, a...)}
|
|
}
|
|
|
|
// busyError is 429: the credential is valid, the request is well formed, and
|
|
// there is simply no capacity for it right now. Distinct from billingError (402,
|
|
// "you owe money") because the caller owes nothing, and from serverError (500)
|
|
// because nothing is broken — the condition is transient and, for a caller at its
|
|
// own share, one the caller itself can clear. The message names which of those
|
|
// two it is (speech_admission.go).
|
|
func busyError(format string, a ...any) error {
|
|
return &apiError{status: http.StatusTooManyRequests, msg: fmt.Sprintf(format, a...)}
|
|
}
|
|
|
|
// statusOf returns the HTTP status carried by an apiError, or 401 for an untyped
|
|
// error reaching an auth-gated handler (fail-secure: deny, never grant).
|
|
func statusOf(err error) int {
|
|
if ae, ok := errors.AsType[*apiError](err); ok {
|
|
return ae.status
|
|
}
|
|
return http.StatusUnauthorized
|
|
}
|
|
|
|
// codeOf returns the machine name a failure carries, or "" for one that has none.
|
|
func codeOf(err error) string {
|
|
if ae, ok := errors.AsType[*apiError](err); ok {
|
|
return ae.code
|
|
}
|
|
return ""
|
|
}
|
|
|
|
// wrapAuth tags an untyped error as a 401 auth failure, but leaves an already
|
|
// typed apiError untouched — so the provider-key branch of
|
|
// authResolveProvider fails closed as 401 while the IAM / JWT branches keep the
|
|
// precise 400 / 402 / 500 status produced deeper in the routing policy.
|
|
func wrapAuth(err error) error {
|
|
if err == nil {
|
|
return nil
|
|
}
|
|
if _, ok := errors.AsType[*apiError](err); ok {
|
|
return err
|
|
}
|
|
return &apiError{status: http.StatusUnauthorized, msg: err.Error()}
|
|
}
|
|
|
|
// ResponseAuthError renders an error from the auth / routing path with its
|
|
// carried HTTP status (401 / 402 / 400 / 500). It never emits 200, so an invalid
|
|
// key, an empty balance, or a bad model is unambiguous to OpenAI-compatible
|
|
// clients. This is the ONE renderer for that surface (chat, embeddings, rerank).
|
|
func (c *ApiController) ResponseAuthError(err error) {
|
|
c.ResponseFailure(err)
|
|
}
|
|
|
|
// ResponseFailure renders a typed failure with the status AND the machine name it
|
|
// carries. ResponseError writes neither: it answers 200 with a message, so a
|
|
// completion that no provider could serve reached clients as a success whose body
|
|
// had no choices in it.
|
|
func (c *ApiController) ResponseFailure(err error) {
|
|
c.JSON(statusOf(err), Response{Status: "error", Msg: err.Error(), Code: codeOf(err)})
|
|
}
|
|
|
|
// ResponseModelFailure renders a model call that nothing answered, with the
|
|
// status a client should see for it (statusForModelError: an upstream 429 stays a
|
|
// 429, a vendor's 402 is our 503) and the machine name it carries.
|
|
func (c *ApiController) ResponseModelFailure(err error) {
|
|
c.JSON(statusForModelError(err), Response{Status: "error", Msg: err.Error(), Code: codeOf(err)})
|
|
}
|
|
|
|
// ResponseUnauthorized renders an authentication denial (no/invalid session or
|
|
// credential) as a real HTTP 401 — never The router's default 200. Same body shape.
|
|
func (c *ApiController) ResponseUnauthorized(error string, data ...any) {
|
|
c.ResponseErrorWithStatus(http.StatusUnauthorized, error, data...)
|
|
}
|
|
|
|
// ResponseForbidden renders an authorization denial (authenticated but not
|
|
// permitted) as a real HTTP 403 — never The router's default 200. Same body shape.
|
|
func (c *ApiController) ResponseForbidden(error string, data ...any) {
|
|
c.ResponseErrorWithStatus(http.StatusForbidden, error, data...)
|
|
}
|
|
|
|
func (c *ApiController) T(error string) string {
|
|
return i18n.Translate(c.GetAcceptLanguage(), error)
|
|
}
|
|
|
|
func (c *ApiController) ResponseAudio(audioData []byte, contentType string, filename string) {
|
|
if contentType == "" {
|
|
contentType = "audio/mp3"
|
|
}
|
|
if filename == "" {
|
|
filename = "audio.mp3"
|
|
}
|
|
|
|
c.SetHeader("Content-Type", contentType)
|
|
c.SetHeader("Content-Disposition", fmt.Sprintf("attachment; filename=%s", filename))
|
|
err := c.Bytes(http.StatusOK, audioData)
|
|
if err != nil {
|
|
responseError(c.Ctx, http.StatusInternalServerError, err.Error())
|
|
}
|
|
}
|
|
|
|
func (c *ApiController) GetAcceptLanguage() string {
|
|
language := c.Header("Accept-Language")
|
|
if len(language) > 2 {
|
|
language = language[0:2]
|
|
}
|
|
return conf.GetLanguage(language)
|
|
}
|
|
|
|
func (c *ApiController) RequireSignedIn() (string, bool) {
|
|
userId := c.GetSessionUsername()
|
|
if userId == "" {
|
|
c.ResponseUnauthorized(c.T("auth:Please sign in first"))
|
|
return "", false
|
|
}
|
|
return userId, true
|
|
}
|
|
|
|
func (c *ApiController) RequireSignedInUser() (*iam.User, bool) {
|
|
user := c.GetSessionUser()
|
|
if user == nil {
|
|
c.ResponseUnauthorized(c.T("auth:Please sign in first"))
|
|
return nil, false
|
|
}
|
|
return user, true
|
|
}
|
|
|
|
// RequirePrincipal resolves the request principal from EITHER the browser session
|
|
// cookie OR a verified Bearer JWT (c.principalUser), returning a real 401 when
|
|
// neither is present. It is the Bearer-aware sibling of RequireSignedInUser: an
|
|
// endpoint that must serve BOTH the console (session cookie) and the token-bearing
|
|
// surfaces (app / chat / billing, which carry an IAM Bearer, not the console
|
|
// cookie) with the SAME resolved identity uses this. The Bearer branch is
|
|
// signature- AND issuer/audience-validated via object.ParseAndValidateJWT (never
|
|
// raw iam.ParseJwtToken), so a forged token cannot pose as anyone.
|
|
//
|
|
// The returned user is the SOLE authority for any downstream org/role scope
|
|
// decision — the caller MUST derive scope from THIS user (its Owner, its role via
|
|
// util.IsSuperAdmin), NEVER from a request header or query param. That is what
|
|
// keeps a Bearer-reachable, org-scoped read tenant-safe.
|
|
func (c *ApiController) RequirePrincipal() (*iam.User, bool) {
|
|
user := c.principalUser()
|
|
if user == nil {
|
|
c.ResponseUnauthorized(c.T("auth:Please sign in first"))
|
|
return nil, false
|
|
}
|
|
return user, true
|
|
}
|
|
|
|
func (c *ApiController) CheckSignedIn() (string, bool) {
|
|
userId := c.GetSessionUsername()
|
|
if userId == "" {
|
|
return "", false
|
|
}
|
|
return userId, true
|
|
}
|
|
|
|
func (c *ApiController) RequireAdmin() bool {
|
|
// conf.IsPreviewMode() is env-first (DISABLE_PREVIEW_MODE), so flipping the
|
|
// lever on the deployed CR makes this enforce real admin with no rebuild.
|
|
if conf.IsPreviewMode() {
|
|
return true
|
|
}
|
|
|
|
if !c.IsAdmin() {
|
|
c.ResponseForbidden(c.T("auth:this operation requires admin privilege"))
|
|
return false
|
|
}
|
|
|
|
return true
|
|
}
|
|
|
|
// RequireSuperAdmin is the controller-level self-guard for platform-sensitive
|
|
// endpoints (provider-admin, upstream-key/topology config). It mirrors the authz
|
|
// filter's superAdminEndpoints gate EXACTLY — same principal (session or VERIFIED
|
|
// Bearer JWT via c.principalUser) and same policy (util.IsSuperAdmin) — so it is
|
|
// belt-AND-suspenders: even if the filter is ever bypassed (e.g. a path-normalization
|
|
// disagreement), the controller still refuses. Fail-closed: no principal → 401,
|
|
// authenticated non-super-admin → 403. Unlike RequireAdmin it is NOT relaxed by
|
|
// preview mode and checks the SuperAdmin, not org admin — these routes
|
|
// govern the primary provider that backs the whole model catalog.
|
|
func (c *ApiController) RequireSuperAdmin() bool {
|
|
user := c.principalUser()
|
|
if user == nil {
|
|
c.ResponseUnauthorized(c.T("auth:Please sign in first"))
|
|
return false
|
|
}
|
|
if !util.IsSuperAdmin(user) {
|
|
c.ResponseForbidden(c.T("auth:this operation requires super admin privilege"))
|
|
return false
|
|
}
|
|
return true
|
|
}
|
|
|
|
func (c *ApiController) IsPreviewMode() bool {
|
|
return conf.IsPreviewMode()
|
|
}
|
|
|
|
func (c *ApiController) IsAdmin() bool {
|
|
user := c.GetSessionUser()
|
|
return util.IsAdmin(user)
|
|
}
|
|
|
|
func DenyRequest(ctx *zip.Ctx) {
|
|
responseError(ctx, http.StatusForbidden, "auth:Unauthorized operation")
|
|
}
|
|
|
|
// responseError writes the translated envelope with an explicit status. The status
|
|
// used to arrive by being set on the response and read back here — which works, and
|
|
// is the same side channel that made every refusal in this file answer 200 when a
|
|
// write that carries its own status came along. Say it at the call.
|
|
func responseError(ctx *zip.Ctx, status int, error string, data ...any) {
|
|
// Get language from Accept-Language header
|
|
language := ctx.Header("Accept-Language")
|
|
if len(language) > 2 {
|
|
language = language[0:2]
|
|
}
|
|
language = conf.GetLanguage(language)
|
|
|
|
// Translate error message if it contains namespace prefix
|
|
translatedError := error
|
|
if strings.Contains(error, ":") {
|
|
translatedError = i18n.Translate(language, error)
|
|
}
|
|
|
|
resp := Response{Status: "error", Msg: translatedError}
|
|
switch len(data) {
|
|
case 2:
|
|
resp.Data2 = data[1]
|
|
fallthrough
|
|
case 1:
|
|
resp.Data = data[0]
|
|
}
|
|
|
|
// A refusal that cannot be written is not something a panic improves: the client
|
|
// either receives the bytes or the connection is already gone. This is also the
|
|
// function the router's recover reaches for when reporting a panic, so raising
|
|
// one here would answer a panic with a panic.
|
|
if err := ctx.JSON(status, resp); err != nil {
|
|
log.Error("responseError: %v", err)
|
|
}
|
|
}
|
|
|
|
func isIpAddress(host string) bool {
|
|
// Attempt to split the host and port, ignoring the error
|
|
hostWithoutPort, _, err := net.SplitHostPort(host)
|
|
if err != nil {
|
|
// If an error occurs, it might be because there's no port
|
|
// In that case, use the original host string
|
|
hostWithoutPort = host
|
|
}
|
|
|
|
// Attempt to parse the host as an IP address (both IPv4 and IPv6)
|
|
ip := net.ParseIP(hostWithoutPort)
|
|
// if host is not nil is an IP address else is not an IP address
|
|
return ip != nil
|
|
}
|
|
|
|
func getOriginFromHost(host string) string {
|
|
protocol := "https://"
|
|
if !strings.Contains(host, ".") {
|
|
// "localhost:14000"
|
|
protocol = "http://"
|
|
} else if isIpAddress(host) {
|
|
// "192.168.0.10"
|
|
protocol = "http://"
|
|
}
|
|
|
|
return fmt.Sprintf("%s%s", protocol, host)
|
|
}
|
|
|
|
func getContentHash(content string) string {
|
|
hasher := sha256.New()
|
|
hasher.Write([]byte(content))
|
|
|
|
res := hex.EncodeToString(hasher.Sum(nil))
|
|
res = res[:8]
|
|
return res
|
|
}
|
|
|
|
func (c *ApiController) getClientIp() string {
|
|
res := strings.Replace(util.GetIPInfo(c.Fiber().IP()), ": ", "", -1)
|
|
return res
|
|
}
|
|
|
|
func (c *ApiController) getUserAgent() string {
|
|
res := c.Header("User-Agent")
|
|
return res
|
|
}
|
|
|
|
// isName reports whether s is a NAME: the half of an id (`owner/name`) that names a
|
|
// row inside its owner, and the half of a billing subject that names a payer inside
|
|
// its org. Neither half may be empty and neither may carry the separator.
|
|
//
|
|
// On the chat plane that makes it a predicate about money. AddTransactionForMessage
|
|
// builds the subject it debits by joining a row's Owner to its User — but only when
|
|
// the User carries no "/", so "victim/bob" is passed through whole and names another
|
|
// tenant's wallet directly. An empty User leaves the subject "admin/", which is the
|
|
// admin ORG's own pool wallet: Hanzo's platform account, not any customer's.
|
|
func isName(s string) bool {
|
|
return s != "" && !strings.Contains(s, "/")
|
|
}
|
|
|
|
// IsCurrentUser reports whether this request may act as usernameInput, and refuses
|
|
// the request when it may not.
|
|
//
|
|
// It answers for NAMES, on both sides, and only for names. Empty used to pass: an
|
|
// unauthenticated request has no session username, so the comparison below read
|
|
// "" != "" and every anonymous caller was the current user of the empty user. The
|
|
// chat plane then wrote that onto a row whose answer bills `admin/` — the admin org's
|
|
// own pool wallet. A usernameInput carrying "/" is not a user either but a whole
|
|
// billing subject, and the admin branch below would wave it through.
|
|
func (c *ApiController) IsCurrentUser(usernameInput string) bool {
|
|
username := c.GetSessionUsername()
|
|
if username == "" && c.getAnonymousUsername() == usernameInput {
|
|
username = c.getAnonymousUsername()
|
|
}
|
|
|
|
if !isName(username) || !isName(usernameInput) {
|
|
c.ResponseForbidden(c.T("auth:Unauthorized operation"))
|
|
return false
|
|
}
|
|
|
|
if !c.IsAdmin() && username != usernameInput {
|
|
c.ResponseForbidden(c.T("auth:Unauthorized operation"))
|
|
return false
|
|
}
|
|
return true
|
|
}
|