diff --git a/docs/docs.go b/docs/docs.go index 759b9ce0b..d142abbf0 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -4113,6 +4113,260 @@ const docTemplate = `{ ] } }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers": { + "get": { + "description": "Lists every person holding a value for this MCP instance's per-user headers, when each was written and whether the upstream refused it. Values are never returned.", + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "List who holds per-user header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/links": { + "post": { + "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them. consumer_path names the virtual MCP that binds the server and is required for a custom server.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Issue one person's link to enter their header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Whose link", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "422": { + "description": "Unprocessable Entity", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/values": { + "put": { + "description": "Stores values for many people at once (up to 1000 rows). Every row is validated before any is written; values are encrypted and never returned.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Load per-user header values in bulk", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Values to load", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "422": { + "description": "Unprocessable Entity", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "description": "Removes the values one person holds for this instance (principal_sub), or every person's when principal_sub is omitted. The next call of each affected person answers with a connect link.", + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Reset per-user header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "One person; omitted resets everyone", + "name": "principal_sub", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, "/v1/gateways/{gateway_id}/secret-stores": { "get": { "description": "Returns the secret stores a gateway may reference, where they are configured and how healthy each is. Never returns addresses, credentials or values.", @@ -9797,6 +10051,38 @@ const docTemplate = `{ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders declares the upstream headers each caller fills with their\nown value. Omitted on update, the stored declarations are kept; an empty\nlist removes them all.", + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest": { + "type": "object", + "properties": { + "description": { + "description": "Description is the help shown to a person entering their value.", + "type": "string" + }, + "name": { + "description": "Name is the HTTP header sent upstream, e.g. X-API-Key.", + "type": "string" + }, + "required": { + "description": "Required refuses a call with a connect link until the caller has a value.", + "type": "boolean" + }, + "scheme": { + "description": "Scheme is written before the value, e.g. Bearer. Empty sends it raw.", + "type": "string" + }, + "secret": { + "description": "Secret keeps the value masked once entered.", + "type": "boolean" } } }, @@ -10054,6 +10340,49 @@ const docTemplate = `{ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest": { + "type": "object", + "properties": { + "values": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "principal_sub": { + "type": "string" + }, + "value": { + "description": "Value is the person's own value, stored encrypted and never returned.", + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest": { + "type": "object", + "properties": { + "consumer_path": { + "description": "ConsumerPath is the virtual MCP the person reaches the server through,\ne.g. /dev/mcp. Required for a custom server; empty uses the MCP Store,\nwhich serves only the servers it materialised.", + "type": "string" + }, + "principal_sub": { + "description": "PrincipalSub is the person: the subject their token carries, or\napp:\u003cconsumer_id\u003e:\u003cend_user\u003e for an end user an application names.", + "type": "string" + }, + "resume_url": { + "description": "ResumeURL is where the page sends the person once they are done.", + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2AAWSAuthResponse": { "type": "object", "properties": { @@ -10445,6 +10774,33 @@ const docTemplate = `{ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders are the upstream headers each caller fills with their own\nvalue. Only the declarations: values live per person in the vault.", + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "required": { + "type": "boolean" + }, + "scheme": { + "type": "string" + }, + "secret": { + "type": "boolean" } } }, @@ -10736,6 +11092,72 @@ const docTemplate = `{ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse": { + "type": "object", + "properties": { + "missing": { + "description": "Missing lists the required headers this person has no usable value for.", + "type": "array", + "items": { + "type": "string" + } + }, + "principal_sub": { + "type": "string" + }, + "values": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse": { + "type": "object", + "properties": { + "holders": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse": { + "type": "object", + "properties": { + "consumer_path": { + "type": "string" + }, + "ticket": { + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "rejected_at": { + "description": "RejectedAt is set when the upstream refused the value with a 401.", + "type": "string" + }, + "updated_at": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_secretstore_request.TestSecretRequest": { "type": "object", "properties": { diff --git a/docs/openapi.json b/docs/openapi.json index 5c0bd601f..b3e42a76f 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -5198,6 +5198,316 @@ ] } }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers": { + "get": { + "description": "Lists every person holding a value for this MCP instance's per-user headers, when each was written and whether the upstream refused it. Values are never returned.", + "tags": [ + "registries" + ], + "summary": "List who holds per-user header values", + "parameters": [ + { + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "description": "Registry id", + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/links": { + "post": { + "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them. consumer_path names the virtual MCP that binds the server and is required for a custom server.", + "tags": [ + "registries" + ], + "summary": "Issue one person's link to enter their header values", + "parameters": [ + { + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "description": "Registry id", + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest" + } + } + }, + "description": "Whose link", + "required": true + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + }, + "422": { + "description": "Unprocessable Entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/values": { + "put": { + "description": "Stores values for many people at once (up to 1000 rows). Every row is validated before any is written; values are encrypted and never returned.", + "tags": [ + "registries" + ], + "summary": "Load per-user header values in bulk", + "parameters": [ + { + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "description": "Registry id", + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest" + } + } + }, + "description": "Values to load", + "required": true + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + }, + "422": { + "description": "Unprocessable Entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "description": "Removes the values one person holds for this instance (principal_sub), or every person's when principal_sub is omitted. The next call of each affected person answers with a connect link.", + "tags": [ + "registries" + ], + "summary": "Reset per-user header values", + "parameters": [ + { + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "description": "Registry id", + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "description": "One person; omitted resets everyone", + "name": "principal_sub", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, "/v1/gateways/{gateway_id}/secret-stores": { "get": { "description": "Returns the secret stores a gateway may reference, where they are configured and how healthy each is. Never returns addresses, credentials or values.", @@ -11773,6 +12083,38 @@ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders declares the upstream headers each caller fills with their\nown value. Omitted on update, the stored declarations are kept; an empty\nlist removes them all.", + "type": "array", + "items": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest": { + "type": "object", + "properties": { + "description": { + "description": "Description is the help shown to a person entering their value.", + "type": "string" + }, + "name": { + "description": "Name is the HTTP header sent upstream, e.g. X-API-Key.", + "type": "string" + }, + "required": { + "description": "Required refuses a call with a connect link until the caller has a value.", + "type": "boolean" + }, + "scheme": { + "description": "Scheme is written before the value, e.g. Bearer. Empty sends it raw.", + "type": "string" + }, + "secret": { + "description": "Secret keeps the value masked once entered.", + "type": "boolean" } } }, @@ -12030,6 +12372,49 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest": { + "type": "object", + "properties": { + "values": { + "type": "array", + "items": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "principal_sub": { + "type": "string" + }, + "value": { + "description": "Value is the person's own value, stored encrypted and never returned.", + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest": { + "type": "object", + "properties": { + "consumer_path": { + "description": "ConsumerPath is the virtual MCP the person reaches the server through,\ne.g. /dev/mcp. Required for a custom server; empty uses the MCP Store,\nwhich serves only the servers it materialised.", + "type": "string" + }, + "principal_sub": { + "description": "PrincipalSub is the person: the subject their token carries, or\napp:: for an end user an application names.", + "type": "string" + }, + "resume_url": { + "description": "ResumeURL is where the page sends the person once they are done.", + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2AAWSAuthResponse": { "type": "object", "properties": { @@ -12421,6 +12806,33 @@ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders are the upstream headers each caller fills with their own\nvalue. Only the declarations: values live per person in the vault.", + "type": "array", + "items": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "required": { + "type": "boolean" + }, + "scheme": { + "type": "string" + }, + "secret": { + "type": "boolean" } } }, @@ -12712,6 +13124,72 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse": { + "type": "object", + "properties": { + "missing": { + "description": "Missing lists the required headers this person has no usable value for.", + "type": "array", + "items": { + "type": "string" + } + }, + "principal_sub": { + "type": "string" + }, + "values": { + "type": "array", + "items": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse": { + "type": "object", + "properties": { + "holders": { + "type": "array", + "items": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse": { + "type": "object", + "properties": { + "consumer_path": { + "type": "string" + }, + "ticket": { + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "rejected_at": { + "description": "RejectedAt is set when the upstream refused the value with a 401.", + "type": "string" + }, + "updated_at": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_secretstore_request.TestSecretRequest": { "type": "object", "properties": { diff --git a/docs/swagger.json b/docs/swagger.json index eea3ddb3c..c3be602a0 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -4106,6 +4106,260 @@ ] } }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers": { + "get": { + "description": "Lists every person holding a value for this MCP instance's per-user headers, when each was written and whether the upstream refused it. Values are never returned.", + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "List who holds per-user header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/links": { + "post": { + "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them. consumer_path names the virtual MCP that binds the server and is required for a custom server.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Issue one person's link to enter their header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Whose link", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "422": { + "description": "Unprocessable Entity", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/values": { + "put": { + "description": "Stores values for many people at once (up to 1000 rows). Every row is validated before any is written; values are encrypted and never returned.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Load per-user header values in bulk", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Values to load", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "422": { + "description": "Unprocessable Entity", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "description": "Removes the values one person holds for this instance (principal_sub), or every person's when principal_sub is omitted. The next call of each affected person answers with a connect link.", + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Reset per-user header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "One person; omitted resets everyone", + "name": "principal_sub", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, "/v1/gateways/{gateway_id}/secret-stores": { "get": { "description": "Returns the secret stores a gateway may reference, where they are configured and how healthy each is. Never returns addresses, credentials or values.", @@ -9790,6 +10044,38 @@ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders declares the upstream headers each caller fills with their\nown value. Omitted on update, the stored declarations are kept; an empty\nlist removes them all.", + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest": { + "type": "object", + "properties": { + "description": { + "description": "Description is the help shown to a person entering their value.", + "type": "string" + }, + "name": { + "description": "Name is the HTTP header sent upstream, e.g. X-API-Key.", + "type": "string" + }, + "required": { + "description": "Required refuses a call with a connect link until the caller has a value.", + "type": "boolean" + }, + "scheme": { + "description": "Scheme is written before the value, e.g. Bearer. Empty sends it raw.", + "type": "string" + }, + "secret": { + "description": "Secret keeps the value masked once entered.", + "type": "boolean" } } }, @@ -10047,6 +10333,49 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest": { + "type": "object", + "properties": { + "values": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "principal_sub": { + "type": "string" + }, + "value": { + "description": "Value is the person's own value, stored encrypted and never returned.", + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest": { + "type": "object", + "properties": { + "consumer_path": { + "description": "ConsumerPath is the virtual MCP the person reaches the server through,\ne.g. /dev/mcp. Required for a custom server; empty uses the MCP Store,\nwhich serves only the servers it materialised.", + "type": "string" + }, + "principal_sub": { + "description": "PrincipalSub is the person: the subject their token carries, or\napp:\u003cconsumer_id\u003e:\u003cend_user\u003e for an end user an application names.", + "type": "string" + }, + "resume_url": { + "description": "ResumeURL is where the page sends the person once they are done.", + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2AAWSAuthResponse": { "type": "object", "properties": { @@ -10438,6 +10767,33 @@ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders are the upstream headers each caller fills with their own\nvalue. Only the declarations: values live per person in the vault.", + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "required": { + "type": "boolean" + }, + "scheme": { + "type": "string" + }, + "secret": { + "type": "boolean" } } }, @@ -10729,6 +11085,72 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse": { + "type": "object", + "properties": { + "missing": { + "description": "Missing lists the required headers this person has no usable value for.", + "type": "array", + "items": { + "type": "string" + } + }, + "principal_sub": { + "type": "string" + }, + "values": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse": { + "type": "object", + "properties": { + "holders": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse": { + "type": "object", + "properties": { + "consumer_path": { + "type": "string" + }, + "ticket": { + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "rejected_at": { + "description": "RejectedAt is set when the upstream refused the value with a 401.", + "type": "string" + }, + "updated_at": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_secretstore_request.TestSecretRequest": { "type": "object", "properties": { diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 32fe8d464..08c39f370 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -1789,6 +1789,34 @@ definitions: type: string url: type: string + user_headers: + description: |- + UserHeaders declares the upstream headers each caller fills with their + own value. Omitted on update, the stored declarations are kept; an empty + list removes them all. + items: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest' + type: array + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest: + properties: + description: + description: Description is the help shown to a person entering their value. + type: string + name: + description: Name is the HTTP header sent upstream, e.g. X-API-Key. + type: string + required: + description: Required refuses a call with a connect link until the caller + has a value. + type: boolean + scheme: + description: Scheme is written before the value, e.g. Bearer. Empty sends + it raw. + type: string + secret: + description: Secret keeps the value masked once entered. + type: boolean type: object github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.OpenAPITargetRequest: properties: @@ -1964,6 +1992,40 @@ definitions: additionalProperties: {} type: object type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest: + properties: + values: + items: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue' + type: array + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue: + properties: + header: + type: string + principal_sub: + type: string + value: + description: Value is the person's own value, stored encrypted and never returned. + type: string + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest: + properties: + consumer_path: + description: |- + ConsumerPath is the virtual MCP the person reaches the server through, + e.g. /dev/mcp. Required for a custom server; empty uses the MCP Store, + which serves only the servers it materialised. + type: string + principal_sub: + description: |- + PrincipalSub is the person: the subject their token carries, or + app:: for an end user an application names. + type: string + resume_url: + description: ResumeURL is where the page sends the person once they are done. + type: string + type: object github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2AAWSAuthResponse: properties: access_key_id: @@ -2232,6 +2294,26 @@ definitions: type: string url: type: string + user_headers: + description: |- + UserHeaders are the upstream headers each caller fills with their own + value. Only the declarations: values live per person in the vault. + items: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse' + type: array + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse: + properties: + description: + type: string + name: + type: string + required: + type: boolean + scheme: + type: string + secret: + type: boolean type: object github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.OpenAPITargetResponse: properties: @@ -2425,6 +2507,51 @@ definitions: type: string type: array type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse: + properties: + count: + type: integer + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse: + properties: + missing: + description: Missing lists the required headers this person has no usable + value for. + items: + type: string + type: array + principal_sub: + type: string + values: + items: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse' + type: array + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse: + properties: + holders: + items: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse' + type: array + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse: + properties: + consumer_path: + type: string + ticket: + type: string + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse: + properties: + header: + type: string + rejected_at: + description: RejectedAt is set when the upstream refused the value with a + 401. + type: string + updated_at: + type: string + type: object github_com_NeuralTrust_TrustGate_pkg_api_handler_http_secretstore_request.TestSecretRequest: properties: field: @@ -7700,6 +7827,180 @@ paths: summary: List an MCP backend's tools tags: - registries + /v1/gateways/{gateway_id}/registries/{id}/user-headers: + get: + description: Lists every person holding a value for this MCP instance's per-user + headers, when each was written and whether the upstream refused it. Values + are never returned. + parameters: + - description: Gateway id + format: uuid + in: path + name: gateway_id + required: true + type: string + - description: Registry id + format: uuid + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + "409": + description: Conflict + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + security: + - BearerAuth: [] + summary: List who holds per-user header values + tags: + - registries + /v1/gateways/{gateway_id}/registries/{id}/user-headers/links: + post: + consumes: + - application/json + description: 'Mints the connect page one person walks to enter their own values + for this instance. Hand it to that person: it acts as them. consumer_path + names the virtual MCP that binds the server and is required for a custom server.' + parameters: + - description: Gateway id + format: uuid + in: path + name: gateway_id + required: true + type: string + - description: Registry id + format: uuid + in: path + name: id + required: true + type: string + - description: Whose link + in: body + name: body + required: true + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + "409": + description: Conflict + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + "422": + description: Unprocessable Entity + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + security: + - BearerAuth: [] + summary: Issue one person's link to enter their header values + tags: + - registries + /v1/gateways/{gateway_id}/registries/{id}/user-headers/values: + delete: + description: Removes the values one person holds for this instance (principal_sub), + or every person's when principal_sub is omitted. The next call of each affected + person answers with a connect link. + parameters: + - description: Gateway id + format: uuid + in: path + name: gateway_id + required: true + type: string + - description: Registry id + format: uuid + in: path + name: id + required: true + type: string + - description: One person; omitted resets everyone + in: query + name: principal_sub + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + security: + - BearerAuth: [] + summary: Reset per-user header values + tags: + - registries + put: + consumes: + - application/json + description: Stores values for many people at once (up to 1000 rows). Every + row is validated before any is written; values are encrypted and never returned. + parameters: + - description: Gateway id + format: uuid + in: path + name: gateway_id + required: true + type: string + - description: Registry id + format: uuid + in: path + name: id + required: true + type: string + - description: Values to load + in: body + name: body + required: true + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + "409": + description: Conflict + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + "422": + description: Unprocessable Entity + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + security: + - BearerAuth: [] + summary: Load per-user header values in bulk + tags: + - registries /v1/gateways/{gateway_id}/registries/from-catalog: post: consumes: diff --git a/pkg/api/handler/http/oauth/connect_handler.go b/pkg/api/handler/http/oauth/connect_handler.go index 567962faa..84373d5d9 100644 --- a/pkg/api/handler/http/oauth/connect_handler.go +++ b/pkg/api/handler/http/oauth/connect_handler.go @@ -363,7 +363,7 @@ func (h *ConnectHandler) showPage(c *fiber.Ctx, ticket, flash string) error { // before. A page the ticket does not scope to one server, or whose server is // already here, is returned as it is. func (h *ConnectHandler) awaitServer(ctx context.Context, ticket string, page *appoauth.ConnectPage) *appoauth.ConnectPage { - if strings.TrimSpace(page.Code) == "" || len(providerRowsForPage(page)) > 0 || h.holdFor <= 0 { + if strings.TrimSpace(page.Code) == "" || serverOnPage(page) || h.holdFor <= 0 { return page } deadline := time.NewTimer(h.holdFor) @@ -382,13 +382,19 @@ func (h *ConnectHandler) awaitServer(ctx context.Context, ticket string, page *a return page } page = next - if len(providerRowsForPage(page)) > 0 { + if serverOnPage(page) { return page } } } } +// serverOnPage reports whether the server a focused page is for has reached +// this plane: as an account to connect, or as keys to enter. +func serverOnPage(page *appoauth.ConnectPage) bool { + return len(providerRowsForPage(page)) > 0 || len(page.UserHeaders) > 0 +} + func (h *ConnectHandler) pageError(c *fiber.Ctx, err error) error { if errors.Is(err, appoauth.ErrTicketNotFound) { return fiber.NewError(fiber.StatusUnauthorized, err.Error()) diff --git a/pkg/api/handler/http/oauth/connect_user_headers_handler.go b/pkg/api/handler/http/oauth/connect_user_headers_handler.go new file mode 100644 index 000000000..19d93c716 --- /dev/null +++ b/pkg/api/handler/http/oauth/connect_user_headers_handler.go @@ -0,0 +1,108 @@ +// Copyright 2026 NeuralTrust +// +// 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 oauth + +import ( + "errors" + "net/url" + "strings" + + appoauth "github.com/NeuralTrust/TrustGate/pkg/app/oauth" + "github.com/gofiber/fiber/v2" +) + +const ( + // UserHeadersSavePath is where the connect page posts a person's header + // values for one server instance. + UserHeadersSavePath = "/oauth/user-headers/:instance" + // UserHeadersRemovePath is where it posts to remove them. + UserHeadersRemovePath = "/oauth/user-headers-remove/:instance" +) + +// maxUserHeaderFormBytes bounds the form a person posts with their keys. +const maxUserHeaderFormBytes = 64 << 10 + +// SaveUserHeaders stores the header values a person entered on the connect +// page, then shows the page again with what is now stored. +func (h *ConnectHandler) SaveUserHeaders(c *fiber.Ctx) error { + enroll, err := h.userHeaderEnrollment(c) + if err != nil { + return err + } + if !isFormURLEncoded(c.Get(fiber.HeaderContentType)) { + return fiber.NewError(fiber.StatusUnsupportedMediaType, "expected application/x-www-form-urlencoded") + } + if len(c.Body()) > maxUserHeaderFormBytes { + return fiber.NewError(fiber.StatusRequestEntityTooLarge, "form too large") + } + form, err := url.ParseQuery(string(c.Body())) + if err != nil { + return fiber.NewError(fiber.StatusBadRequest, "malformed form") + } + values := make(map[string]string, len(form)) + for name, vs := range form { + if len(vs) > 0 { + values[name] = vs[0] + } + } + ticket := c.Query("ticket") + if err := enroll.SaveUserHeaders(c.UserContext(), ticket, c.Params("instance"), values); err != nil { + return h.userHeaderError(c, ticket, err) + } + return h.showPage(c, ticket, "") +} + +// RemoveUserHeaders deletes the header values a person holds for one server. +func (h *ConnectHandler) RemoveUserHeaders(c *fiber.Ctx) error { + enroll, err := h.userHeaderEnrollment(c) + if err != nil { + return err + } + ticket := c.Query("ticket") + if err := enroll.RemoveUserHeaders(c.UserContext(), ticket, c.Params("instance")); err != nil { + return h.userHeaderError(c, ticket, err) + } + return h.showPage(c, ticket, "") +} + +// userHeaderEnrollment refuses a write that did not come from the gateway's +// own page, and one this plane's connect service cannot serve. +func (h *ConnectHandler) userHeaderEnrollment(c *fiber.Ctx) (appoauth.UserHeaderEnrollment, error) { + c.Set(fiber.HeaderCacheControl, "no-store") + if !sentFromOwnPage(c) { + return nil, h.pageError(c, errConnectNotFromPage) + } + enroll, ok := h.connect.(appoauth.UserHeaderEnrollment) + if !ok { + return nil, fiber.NewError(fiber.StatusNotFound, "per-user keys are not available here") + } + if strings.TrimSpace(c.Query("ticket")) == "" { + return nil, fiber.NewError(fiber.StatusUnauthorized, "missing ticket: re-run the tool call to get a fresh connect link") + } + return enroll, nil +} + +func (h *ConnectHandler) userHeaderError(c *fiber.Ctx, ticket string, err error) error { + switch { + case errors.Is(err, appoauth.ErrUserHeaderInvalid): + // The message names the header, never the value; the person fixes it + // on the same page. + return h.showPage(c, ticket, err.Error()) + case errors.Is(err, appoauth.ErrUserHeaderServerNotFound): + return fiber.NewError(fiber.StatusNotFound, err.Error()) + default: + return h.pageError(c, err) + } +} diff --git a/pkg/api/handler/http/oauth/connect_user_headers_handler_test.go b/pkg/api/handler/http/oauth/connect_user_headers_handler_test.go new file mode 100644 index 000000000..b19ba430b --- /dev/null +++ b/pkg/api/handler/http/oauth/connect_user_headers_handler_test.go @@ -0,0 +1,126 @@ +// Copyright 2026 NeuralTrust +// +// 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 oauth + +import ( + "context" + "net/http/httptest" + "strings" + "testing" + "time" + + appoauth "github.com/NeuralTrust/TrustGate/pkg/app/oauth" + "github.com/gofiber/fiber/v2" +) + +// enrollingConnectService is a connect service that also takes header values. +type enrollingConnectService struct { + *stubConnectService + saved map[string]string + removed bool +} + +func (s *enrollingConnectService) SaveUserHeaders(_ context.Context, _, _ string, values map[string]string) error { + s.saved = values + return nil +} + +func (s *enrollingConnectService) RemoveUserHeaders(context.Context, string, string) error { + s.removed = true + return nil +} + +func userHeaderPage(code string) *appoauth.ConnectPage { + return &appoauth.ConnectPage{ + ConsumerPath: "/dev/mcp", + Code: code, + Principal: appoauth.ConnectPrincipal{Subject: "ana", Email: "ana@acme.test"}, + UserHeaders: []appoauth.UserHeaderServer{{ + Registry: "Keyed API", Instance: "inst-1", + Fields: []appoauth.UserHeaderField{ + {Name: "X-API-Key", Required: true, Secret: true, Set: true}, + {Name: "X-Account", Value: "acct-visible", Set: true}, + }, + }}, + } +} + +func TestConnectPage_ShowsPerUserHeaderForms(t *testing.T) { + t.Parallel() + for name, code := range map[string]string{"grid": "", "focused on a header-only server": "com.keyed/mcp"} { + h := newTestConnectHandler(&stubConnectService{page: userHeaderPage(code)}, nil, "") + h.holdFor = 0 + _, body := send(t, connectFlowApp(h), httptest.NewRequest(fiber.MethodGet, "/dev/mcp/connect?ticket=abc", nil)) + if !strings.Contains(body, `action="/oauth/user-headers/inst-1?ticket=abc"`) { + t.Fatalf("%s: no save form: %s", name, body) + } + if !strings.Contains(body, `type="password"`) || !strings.Contains(body, "acct-visible") { + t.Fatalf("%s: secret must be a password field and the plain value shown: %s", name, body) + } + if strings.Contains(body, "No third-party providers") { + t.Fatalf("%s: a page with header servers says there is nothing to connect", name) + } + } +} + +func TestSaveUserHeaders_OnlyFromTheGatewaysOwnPage(t *testing.T) { + t.Parallel() + svc := &enrollingConnectService{stubConnectService: &stubConnectService{page: userHeaderPage("")}} + h := newTestConnectHandler(svc, nil, "") + h.holdFor = 0 + app := fiber.New() + app.Post(UserHeadersSavePath, h.SaveUserHeaders) + app.Post(UserHeadersRemovePath, h.RemoveUserHeaders) + + cross := httptest.NewRequest(fiber.MethodPost, "/oauth/user-headers/inst-1?ticket=abc", strings.NewReader("X-API-Key=k")) + cross.Header.Set(fiber.HeaderContentType, fiber.MIMEApplicationForm) + cross.Header.Set("Sec-Fetch-Site", "cross-site") + if res, _ := send(t, app, cross); res.StatusCode == fiber.StatusOK || svc.saved != nil { + t.Fatalf("a cross-site post was accepted (status %d)", res.StatusCode) + } + + own := httptest.NewRequest(fiber.MethodPost, "/oauth/user-headers/inst-1?ticket=abc", strings.NewReader("X-API-Key=k&X-Account=a")) + own.Header.Set(fiber.HeaderContentType, fiber.MIMEApplicationForm) + own.Header.Set("Sec-Fetch-Site", "same-origin") + res, body := send(t, app, own) + if res.StatusCode != fiber.StatusOK || svc.saved["X-API-Key"] != "k" { + t.Fatalf("own-page save failed: %d %v", res.StatusCode, svc.saved) + } + if strings.Contains(body, `value="k"`) { + t.Fatal("the saved secret was echoed into the page") + } + + remove := httptest.NewRequest(fiber.MethodPost, "/oauth/user-headers-remove/inst-1?ticket=abc", nil) + remove.Header.Set("Sec-Fetch-Site", "same-origin") + if res, _ := send(t, app, remove); res.StatusCode != fiber.StatusOK || !svc.removed { + t.Fatalf("remove failed: %d", res.StatusCode) + } +} + +// A focused page for a server whose only credential is its keys is not +// waiting for the server: it is here, with nothing to connect. +func TestConnectPage_HeaderOnlyServerDoesNotWait(t *testing.T) { + t.Parallel() + h := newTestConnectHandler(&stubConnectService{page: userHeaderPage("com.keyed/mcp")}, nil, "") + h.holdFor = time.Minute + started := time.Now() + _, body := send(t, connectFlowApp(h), httptest.NewRequest(fiber.MethodGet, "/dev/mcp/connect?ticket=abc", nil)) + if time.Since(started) > 5*time.Second { + t.Fatalf("the page waited for a server that is already here") + } + if !strings.Contains(body, "/oauth/user-headers/inst-1") { + t.Fatalf("no key form: %s", body) + } +} diff --git a/pkg/api/handler/http/oauth/page_assets.go b/pkg/api/handler/http/oauth/page_assets.go index 4be6164a2..871dd116d 100644 --- a/pkg/api/handler/http/oauth/page_assets.go +++ b/pkg/api/handler/http/oauth/page_assets.go @@ -370,6 +370,30 @@ const alertGlyph = `` +// userHeadersSection lists the servers whose upstream needs the person's own +// header values, with a form to enter, replace or remove them. A secret value +// is never written back into the page: its field stays empty, and leaving it +// empty keeps what is stored. +const userHeadersSection = `{{if .UserHeaders}}
+

Your keys

+

These servers authenticate each person with their own key. Enter yours once: it is stored encrypted in the gateway vault, sent only on your calls, and never shown to the agent.

+{{range .UserHeaders}}
+
+

{{.Registry}}

+ {{if .Missing}}Needs your key{{else}}` + badgeCheck + `Saved{{end}} +
+
+ {{range .Fields}}
+ + + {{if .Description}}

{{.Description}}

{{end}} +
{{end}} +
+
+
+
{{end}} +
{{end}}` + var connectPageTmpl = template.Must(template.New("connect").Parse(` ` + pageFonts + ` @@ -386,7 +410,7 @@ var connectPageTmpl = template.Must(template.New("connect").Parse(`
{{len .Providers}} of {{len .Providers}}
{{end}} -{{if not .Providers}}

No third-party providers are configured for this virtual MCP.

{{end}} +{{if and (not .Providers) (not .UserHeaders)}}

No third-party providers are configured for this virtual MCP.

{{end}}
{{range .Providers}}
@@ -409,6 +433,7 @@ var connectPageTmpl = template.Must(template.New("connect").Parse(` {{end}}
{{end}}
+` + userHeadersSection + ` {{if .ResumeURL}}
Done connecting?
Return to your application to finish signing in.
Continue @@ -509,6 +534,7 @@ var singleConnectPageTmpl = template.Must(template.New("single-connect").Parse(` {{if and .Owner.Name (not .AwaitingAdmin)}}
Linked to{{.Owner.Name}}{{if .Owner.Detail}}{{.Owner.Detail}}{{end}}
{{end}}

` + lockGlyph + `Credentials are encrypted in the gateway vault. The agent never sees the token.

{{end}} +` + userHeadersSection + `
{{if .Found}} diff --git a/pkg/api/handler/http/oauth/pages.go b/pkg/api/handler/http/oauth/pages.go index 85e52a6d8..4e22dc93b 100644 --- a/pkg/api/handler/http/oauth/pages.go +++ b/pkg/api/handler/http/oauth/pages.go @@ -53,6 +53,7 @@ type connectPageView struct { Providers []providerView ResumeURL template.URL Owner ownerView + UserHeaders []appoauth.UserHeaderServer } // ownerView is who an account connected from a page is linked to: Name is @@ -115,7 +116,9 @@ func renderConnectPageAfter(c *fiber.Ctx, page *appoauth.ConnectPage, ticket, fl connectPageReferrerPolicy(c) // A ticket minted for one server (e.g. a Store install) shows the focused // single-server page instead of the full provider grid. - if strings.TrimSpace(page.Code) != "" { + // A server whose only per-person credential is its header keys has no + // account row to focus on: the page lists the keys instead. + if strings.TrimSpace(page.Code) != "" && (len(page.UserHeaders) == 0 || len(providerRowsForPage(page)) > 0) { return renderSingleConnectPage(c, page, ticket, flash, justConnected, catalog) } return renderHTML(c, connectPageTmpl, connectPageView{ @@ -125,6 +128,7 @@ func renderConnectPageAfter(c *fiber.Ctx, page *appoauth.ConnectPage, ticket, fl Providers: decorateProviders(catalog, page.Providers), ResumeURL: template.URL(page.ResumeURL), // #nosec G203 -- the registered redirect_uri, or an https URL checked by NormalizeResumeURL Owner: ownerOf(page.Principal), + UserHeaders: page.UserHeaders, }) } @@ -185,6 +189,7 @@ type singleConnectView struct { Items []string ItemsMore int Owner ownerView + UserHeaders []appoauth.UserHeaderServer } // providerRowsForPage narrows a page's rows to the server it is scoped to: the @@ -214,11 +219,12 @@ func providerRowsForPage(page *appoauth.ConnectPage) []appoauth.ProviderStatus { // no connection (or is not on this consumer) and the page says so. func renderSingleConnectPage(c *fiber.Ctx, page *appoauth.ConnectPage, ticket, flash string, justConnected bool, catalog appcatalog.MCPServerCatalog) error { view := singleConnectView{ - Ticket: ticket, - Flash: flash, - ResumeURL: template.URL(page.ResumeURL), // #nosec G203 -- the registered redirect_uri, or an https URL checked by NormalizeResumeURL - Owner: ownerOf(page.Principal), - AppName: page.ClientName, + Ticket: ticket, + Flash: flash, + ResumeURL: template.URL(page.ResumeURL), // #nosec G203 -- the registered redirect_uri, or an https URL checked by NormalizeResumeURL + Owner: ownerOf(page.Principal), + AppName: page.ClientName, + UserHeaders: page.UserHeaders, } var granted []string for _, p := range providerRowsForPage(page) { diff --git a/pkg/api/handler/http/registry/request/create_registry_request.go b/pkg/api/handler/http/registry/request/create_registry_request.go index 4f34d5661..1fb062c08 100644 --- a/pkg/api/handler/http/registry/request/create_registry_request.go +++ b/pkg/api/handler/http/registry/request/create_registry_request.go @@ -53,13 +53,31 @@ type PriceOverrideRequest struct { } type MCPTargetRequest struct { - Code string `json:"code,omitempty"` - Source string `json:"source,omitempty"` - URL string `json:"url,omitempty"` - Transport string `json:"transport,omitempty"` - Headers map[string]string `json:"headers,omitempty"` - Auth *MCPAuthRequest `json:"auth,omitempty"` - OpenAPI *OpenAPITargetRequest `json:"openapi,omitempty"` + Code string `json:"code,omitempty"` + Source string `json:"source,omitempty"` + URL string `json:"url,omitempty"` + Transport string `json:"transport,omitempty"` + Headers map[string]string `json:"headers,omitempty"` + // UserHeaders declares the upstream headers each caller fills with their + // own value. Omitted on update, the stored declarations are kept; an empty + // list removes them all. + UserHeaders *[]MCPUserHeaderRequest `json:"user_headers,omitempty"` + Auth *MCPAuthRequest `json:"auth,omitempty"` + OpenAPI *OpenAPITargetRequest `json:"openapi,omitempty"` +} + +// MCPUserHeaderRequest declares one per-user upstream header. +type MCPUserHeaderRequest struct { + // Name is the HTTP header sent upstream, e.g. X-API-Key. + Name string `json:"name"` + // Description is the help shown to a person entering their value. + Description string `json:"description,omitempty"` + // Required refuses a call with a connect link until the caller has a value. + Required bool `json:"required,omitempty"` + // Secret keeps the value masked once entered. + Secret bool `json:"secret,omitempty"` + // Scheme is written before the value, e.g. Bearer. Empty sends it raw. + Scheme string `json:"scheme,omitempty"` } type OpenAPITargetRequest struct { @@ -269,6 +287,14 @@ func (t *MCPTargetRequest) ToDomain() *domain.MCPTarget { Transport: domain.MCPTransport(t.Transport), Headers: t.Headers, } + if t.UserHeaders != nil { + out.UserHeaders = make([]domain.MCPUserHeader, 0, len(*t.UserHeaders)) + for _, h := range *t.UserHeaders { + out.UserHeaders = append(out.UserHeaders, domain.MCPUserHeader{ + Name: h.Name, Description: h.Description, Required: h.Required, Secret: h.Secret, Scheme: h.Scheme, + }) + } + } if t.OpenAPI != nil { out.OpenAPI = &domain.OpenAPITarget{SpecURL: t.OpenAPI.SpecURL} } diff --git a/pkg/api/handler/http/registry/request/mcp_account_test.go b/pkg/api/handler/http/registry/request/mcp_account_test.go index f0887eece..508dce97e 100644 --- a/pkg/api/handler/http/registry/request/mcp_account_test.go +++ b/pkg/api/handler/http/registry/request/mcp_account_test.go @@ -68,3 +68,20 @@ func TestCreateRegistryRequest_NoAccountIsTheCallersOwn(t *testing.T) { require.Empty(t, string(target.Auth.Account)) require.False(t, target.Auth.Shared()) } + +// A per-user header that does not survive the wire would be dropped silently +// and every caller would dial without it. +func TestMCPTargetRequest_UserHeaders(t *testing.T) { + var omitted, cleared, set MCPTargetRequest + require.NoError(t, json.Unmarshal([]byte(`{"url":"https://x.example.com/mcp"}`), &omitted)) + require.NoError(t, json.Unmarshal([]byte(`{"url":"https://x.example.com/mcp","user_headers":[]}`), &cleared)) + require.NoError(t, json.Unmarshal([]byte(`{"url":"https://x.example.com/mcp","user_headers":[ + {"name":"X-API-Key","description":"Your key","required":true,"secret":true,"scheme":"Token"}]}`), &set)) + + require.Nil(t, omitted.ToDomain().UserHeaders) + require.NotNil(t, cleared.ToDomain().UserHeaders) + require.Empty(t, cleared.ToDomain().UserHeaders) + require.Equal(t, []domain.MCPUserHeader{{ + Name: "X-API-Key", Description: "Your key", Required: true, Secret: true, Scheme: "Token", + }}, set.ToDomain().UserHeaders) +} diff --git a/pkg/api/handler/http/registry/request/user_headers_request.go b/pkg/api/handler/http/registry/request/user_headers_request.go new file mode 100644 index 000000000..551c3ed8c --- /dev/null +++ b/pkg/api/handler/http/registry/request/user_headers_request.go @@ -0,0 +1,42 @@ +// Copyright 2026 NeuralTrust +// +// 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 request + +// UserHeaderLinkRequest asks for the connect page one person walks to enter +// their own header values. +type UserHeaderLinkRequest struct { + // PrincipalSub is the person: the subject their token carries, or + // app:: for an end user an application names. + PrincipalSub string `json:"principal_sub"` + // ConsumerPath is the virtual MCP the person reaches the server through, + // e.g. /dev/mcp. Required for a custom server; empty uses the MCP Store, + // which serves only the servers it materialised. + ConsumerPath string `json:"consumer_path,omitempty"` + // ResumeURL is where the page sends the person once they are done. + ResumeURL string `json:"resume_url,omitempty"` +} + +// UserHeaderImportRequest loads values for many people at once. +type UserHeaderImportRequest struct { + Values []UserHeaderImportValue `json:"values"` +} + +// UserHeaderImportValue is one person's value for one header. +type UserHeaderImportValue struct { + PrincipalSub string `json:"principal_sub"` + Header string `json:"header"` + // Value is the person's own value, stored encrypted and never returned. + Value string `json:"value"` +} diff --git a/pkg/api/handler/http/registry/response/registry_response.go b/pkg/api/handler/http/registry/response/registry_response.go index 6cd377fac..58f2b6f2d 100644 --- a/pkg/api/handler/http/registry/response/registry_response.go +++ b/pkg/api/handler/http/registry/response/registry_response.go @@ -132,13 +132,25 @@ type MCPTargetResponse struct { Code string `json:"code,omitempty"` // Origin is "store" when the gateway materialised this registry from the // catalog itself (self-service install, approval, consumer binding). - Origin string `json:"origin,omitempty"` - Source string `json:"source,omitempty"` - URL string `json:"url,omitempty"` - Transport string `json:"transport,omitempty"` - Headers map[string]string `json:"headers,omitempty"` - Auth *MCPAuthResponse `json:"auth,omitempty"` - OpenAPI *OpenAPITargetResponse `json:"openapi,omitempty"` + Origin string `json:"origin,omitempty"` + Source string `json:"source,omitempty"` + URL string `json:"url,omitempty"` + Transport string `json:"transport,omitempty"` + Headers map[string]string `json:"headers,omitempty"` + // UserHeaders are the upstream headers each caller fills with their own + // value. Only the declarations: values live per person in the vault. + UserHeaders []MCPUserHeaderResponse `json:"user_headers,omitempty"` + Auth *MCPAuthResponse `json:"auth,omitempty"` + OpenAPI *OpenAPITargetResponse `json:"openapi,omitempty"` +} + +// MCPUserHeaderResponse is one declared per-user upstream header. +type MCPUserHeaderResponse struct { + Name string `json:"name"` + Description string `json:"description,omitempty"` + Required bool `json:"required,omitempty"` + Secret bool `json:"secret,omitempty"` + Scheme string `json:"scheme,omitempty"` } type OpenAPITargetResponse struct { @@ -310,6 +322,11 @@ func fromMCPTarget(t *domain.MCPTarget) *MCPTargetResponse { Transport: string(t.Transport), Headers: maskHeaders(t.Headers), } + for _, h := range t.UserHeaders { + out.UserHeaders = append(out.UserHeaders, MCPUserHeaderResponse{ + Name: h.Name, Description: h.Description, Required: h.Required, Secret: h.Secret, Scheme: h.Scheme, + }) + } if t.OpenAPI != nil { out.OpenAPI = &OpenAPITargetResponse{SpecURL: t.OpenAPI.SpecURL} } diff --git a/pkg/api/handler/http/registry/response/user_headers_response.go b/pkg/api/handler/http/registry/response/user_headers_response.go new file mode 100644 index 000000000..c02578ba8 --- /dev/null +++ b/pkg/api/handler/http/registry/response/user_headers_response.go @@ -0,0 +1,76 @@ +// Copyright 2026 NeuralTrust +// +// 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 response + +import ( + "time" + + appregistry "github.com/NeuralTrust/TrustGate/pkg/app/registry" +) + +// UserHeaderHoldersResponse lists who holds a value for an instance's +// per-user headers. Values are never returned. +type UserHeaderHoldersResponse struct { + Holders []UserHeaderHolderResponse `json:"holders"` +} + +type UserHeaderHolderResponse struct { + PrincipalSub string `json:"principal_sub"` + Values []UserHeaderValueResponse `json:"values"` + // Missing lists the required headers this person has no usable value for. + Missing []string `json:"missing,omitempty"` +} + +type UserHeaderValueResponse struct { + Header string `json:"header"` + UpdatedAt time.Time `json:"updated_at"` + // RejectedAt is set when the upstream refused the value with a 401. + RejectedAt *time.Time `json:"rejected_at,omitempty"` +} + +// UserHeaderCountResponse reports how many values a reset or import touched. +type UserHeaderCountResponse struct { + Count int `json:"count"` +} + +// UserHeaderLinkResponse is the connect page one person walks. +type UserHeaderLinkResponse struct { + Ticket string `json:"ticket"` + ConsumerPath string `json:"consumer_path"` +} + +func FromUserHeaderHolders(holders []appregistry.UserHeaderHolder) UserHeaderHoldersResponse { + out := UserHeaderHoldersResponse{Holders: make([]UserHeaderHolderResponse, 0, len(holders))} + for _, h := range holders { + row := UserHeaderHolderResponse{PrincipalSub: h.PrincipalSub, Missing: h.Missing} + for _, v := range h.Values { + value := UserHeaderValueResponse{Header: v.Header, UpdatedAt: v.UpdatedAt} + if !v.RejectedAt.IsZero() { + rejected := v.RejectedAt + value.RejectedAt = &rejected + } + row.Values = append(row.Values, value) + } + out.Holders = append(out.Holders, row) + } + return out +} + +func FromUserHeaderLink(l *appregistry.UserHeaderLink) UserHeaderLinkResponse { + if l == nil { + return UserHeaderLinkResponse{} + } + return UserHeaderLinkResponse{Ticket: l.Ticket, ConsumerPath: l.ConsumerPath} +} diff --git a/pkg/api/handler/http/registry/user_headers_handler.go b/pkg/api/handler/http/registry/user_headers_handler.go new file mode 100644 index 000000000..637519844 --- /dev/null +++ b/pkg/api/handler/http/registry/user_headers_handler.go @@ -0,0 +1,153 @@ +// Copyright 2026 NeuralTrust +// +// 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 registry + +import ( + "fmt" + "strings" + + "github.com/NeuralTrust/TrustGate/pkg/api/handler/http/httpio" + "github.com/NeuralTrust/TrustGate/pkg/api/handler/http/registry/request" + "github.com/NeuralTrust/TrustGate/pkg/api/handler/http/registry/response" + appregistry "github.com/NeuralTrust/TrustGate/pkg/app/registry" + commonerrors "github.com/NeuralTrust/TrustGate/pkg/common/errors" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + "github.com/gofiber/fiber/v2" +) + +// UserHeadersHandler serves the per-user header values of an MCP instance as +// an admin sees them: who holds one, resetting them, loading them in bulk and +// handing one person their link. Values are written, never read back. +type UserHeadersHandler struct { + admin appregistry.UserHeaderAdmin +} + +func NewUserHeadersHandler(admin appregistry.UserHeaderAdmin) *UserHeadersHandler { + return &UserHeadersHandler{admin: admin} +} + +// List godoc +// @Summary List who holds per-user header values +// @Description Lists every person holding a value for this MCP instance's per-user headers, when each was written and whether the upstream refused it. Values are never returned. +// @Tags registries +// @Produce json +// @Security BearerAuth +// @Param gateway_id path string true "Gateway id" format(uuid) +// @Param id path string true "Registry id" format(uuid) +// @Success 200 {object} response.UserHeaderHoldersResponse +// @Failure 404 {object} httpio.ErrorBody +// @Failure 409 {object} httpio.ErrorBody +// @Router /v1/gateways/{gateway_id}/registries/{id}/user-headers [get] +func (h *UserHeadersHandler) List(c *fiber.Ctx) error { + gatewayID, id, err := httpio.ParseGatewayScopedID[ids.RegistryKind](c) + if err != nil { + return httpio.WriteError(c, err) + } + holders, err := h.admin.Holders(c.UserContext(), gatewayID, id) + if err != nil { + return httpio.WriteError(c, err) + } + return httpio.WriteOK(c, response.FromUserHeaderHolders(holders)) +} + +// Reset godoc +// @Summary Reset per-user header values +// @Description Removes the values one person holds for this instance (principal_sub), or every person's when principal_sub is omitted. The next call of each affected person answers with a connect link. +// @Tags registries +// @Produce json +// @Security BearerAuth +// @Param gateway_id path string true "Gateway id" format(uuid) +// @Param id path string true "Registry id" format(uuid) +// @Param principal_sub query string false "One person; omitted resets everyone" +// @Success 200 {object} response.UserHeaderCountResponse +// @Failure 404 {object} httpio.ErrorBody +// @Router /v1/gateways/{gateway_id}/registries/{id}/user-headers/values [delete] +func (h *UserHeadersHandler) Reset(c *fiber.Ctx) error { + gatewayID, id, err := httpio.ParseGatewayScopedID[ids.RegistryKind](c) + if err != nil { + return httpio.WriteError(c, err) + } + n, err := h.admin.Reset(c.UserContext(), gatewayID, id, strings.TrimSpace(c.Query("principal_sub"))) + if err != nil { + return httpio.WriteError(c, err) + } + return httpio.WriteOK(c, response.UserHeaderCountResponse{Count: n}) +} + +// Import godoc +// @Summary Load per-user header values in bulk +// @Description Stores values for many people at once (up to 1000 rows). Every row is validated before any is written; values are encrypted and never returned. +// @Tags registries +// @Accept json +// @Produce json +// @Security BearerAuth +// @Param gateway_id path string true "Gateway id" format(uuid) +// @Param id path string true "Registry id" format(uuid) +// @Param body body request.UserHeaderImportRequest true "Values to load" +// @Success 200 {object} response.UserHeaderCountResponse +// @Failure 404 {object} httpio.ErrorBody +// @Failure 409 {object} httpio.ErrorBody +// @Failure 422 {object} httpio.ErrorBody +// @Router /v1/gateways/{gateway_id}/registries/{id}/user-headers/values [put] +func (h *UserHeadersHandler) Import(c *fiber.Ctx) error { + gatewayID, id, err := httpio.ParseGatewayScopedID[ids.RegistryKind](c) + if err != nil { + return httpio.WriteError(c, err) + } + var req request.UserHeaderImportRequest + if err := c.BodyParser(&req); err != nil { + return httpio.WriteError(c, fmt.Errorf("invalid request body: %w", commonerrors.ErrValidation)) + } + rows := make([]appregistry.UserHeaderImportRow, 0, len(req.Values)) + for _, v := range req.Values { + rows = append(rows, appregistry.UserHeaderImportRow{PrincipalSub: v.PrincipalSub, Header: v.Header, Value: v.Value}) + } + n, err := h.admin.Import(c.UserContext(), gatewayID, id, rows) + if err != nil { + return httpio.WriteError(c, err) + } + return httpio.WriteOK(c, response.UserHeaderCountResponse{Count: n}) +} + +// Link godoc +// @Summary Issue one person's link to enter their header values +// @Description Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them. consumer_path names the virtual MCP that binds the server and is required for a custom server. +// @Tags registries +// @Accept json +// @Produce json +// @Security BearerAuth +// @Param gateway_id path string true "Gateway id" format(uuid) +// @Param id path string true "Registry id" format(uuid) +// @Param body body request.UserHeaderLinkRequest true "Whose link" +// @Success 200 {object} response.UserHeaderLinkResponse +// @Failure 404 {object} httpio.ErrorBody +// @Failure 409 {object} httpio.ErrorBody +// @Failure 422 {object} httpio.ErrorBody +// @Router /v1/gateways/{gateway_id}/registries/{id}/user-headers/links [post] +func (h *UserHeadersHandler) Link(c *fiber.Ctx) error { + gatewayID, id, err := httpio.ParseGatewayScopedID[ids.RegistryKind](c) + if err != nil { + return httpio.WriteError(c, err) + } + var req request.UserHeaderLinkRequest + if err := c.BodyParser(&req); err != nil { + return httpio.WriteError(c, fmt.Errorf("invalid request body: %w", commonerrors.ErrValidation)) + } + link, err := h.admin.Link(c.UserContext(), gatewayID, id, req.PrincipalSub, req.ConsumerPath, req.ResumeURL) + if err != nil { + return httpio.WriteError(c, err) + } + return httpio.WriteOK(c, response.FromUserHeaderLink(link)) +} diff --git a/pkg/app/mcp/credentials.go b/pkg/app/mcp/credentials.go index daed5dbd2..f36f1dac3 100644 --- a/pkg/app/mcp/credentials.go +++ b/pkg/app/mcp/credentials.go @@ -173,6 +173,13 @@ const rejectedCredentialRefreshCooldown = 30 * time.Second const deadGrantRetryInterval = 15 * time.Minute func (r *credentialResolver) Apply(ctx context.Context, rc *appconsumer.RoutableConsumer, reg *registrydomain.Registry, target *Target) error { + if err := r.applyAuth(ctx, rc, reg, target); err != nil { + return err + } + return r.applyUserHeaders(ctx, rc, reg, target) +} + +func (r *credentialResolver) applyAuth(ctx context.Context, rc *appconsumer.RoutableConsumer, reg *registrydomain.Registry, target *Target) error { cfg := reg.MCPTarget.Auth if cfg == nil { return nil @@ -290,7 +297,7 @@ func (r *credentialResolver) Refresh( ) error { cfg := reg.MCPTarget.Auth if cfg == nil || cfg.Mode != registrydomain.MCPAuthModeForwarded { - return errCredentialRefreshUnsupported + return r.refuseRejectedUserHeaders(ctx, rc, reg, target) } principal := identity.PrincipalFromContext(ctx) if principal == nil { diff --git a/pkg/app/mcp/discovery.go b/pkg/app/mcp/discovery.go index bdb0dece1..193f9c3d7 100644 --- a/pkg/app/mcp/discovery.go +++ b/pkg/app/mcp/discovery.go @@ -437,7 +437,7 @@ func isContextError(err error) bool { func discoveryKey(ctx context.Context, reg *registrydomain.Registry, kind string) (string, bool) { key := kind + ":" + reg.ID.String() + ":" + reg.UpdatedAt.UTC().Format("20060102150405.000") perPrincipal := perPrincipalAuth(reg) || - (reg.MCPTarget != nil && reg.MCPTarget.HasURLVariables()) + (reg.MCPTarget != nil && (reg.MCPTarget.HasURLVariables() || reg.MCPTarget.HasUserHeaders())) if !perPrincipal { return key, true } diff --git a/pkg/app/mcp/errors.go b/pkg/app/mcp/errors.go index c38c758b3..2fa0125d4 100644 --- a/pkg/app/mcp/errors.go +++ b/pkg/app/mcp/errors.go @@ -66,6 +66,10 @@ type ApplicationNotConnectedError struct { // calling can connect that one — telling them to link their own would send // them somewhere that changes nothing. Shared bool + // UserKeys marks a server whose upstream takes each person's own key in a + // header: only a person can hold one, so the only remedy is naming who the + // request acts for. A group key is refused the same way. + UserKeys bool } // UnknownToolError is a tools/call name that no bound registry owns. It wraps @@ -105,6 +109,14 @@ func (e *ApplicationNotConnectedError) Error() string { server, ) } + if e.UserKeys { + return fmt.Sprintf( + "mcp: %q takes each person's own key, and this request does not come from one person "+ + "(it carries only the application's key, or a key held for a group). Sign in as the person, "+ + "or send the %s header with the id of the end user it acts for", + server, consumerdomain.EndUserHeader, + ) + } // Every MCP client reads this, not only the SDK, so the remedy is the header // itself rather than a call in one language. return fmt.Sprintf( diff --git a/pkg/app/mcp/introspector.go b/pkg/app/mcp/introspector.go index 8c588b009..ed40335a1 100644 --- a/pkg/app/mcp/introspector.go +++ b/pkg/app/mcp/introspector.go @@ -66,5 +66,5 @@ func (i *introspector) ListRegistryTools(ctx context.Context, gatewayID ids.Gate // notIntrospectable reports whether dialing this registry needs a principal. func notIntrospectable(reg *registrydomain.Registry) bool { - return perPrincipalAuth(reg) || reg.MCPTarget.HasURLVariables() + return perPrincipalAuth(reg) || reg.MCPTarget.HasURLVariables() || reg.MCPTarget.HasUserHeaders() } diff --git a/pkg/app/mcp/target.go b/pkg/app/mcp/target.go index 2c0bfce45..39dcdb6e9 100644 --- a/pkg/app/mcp/target.go +++ b/pkg/app/mcp/target.go @@ -92,7 +92,7 @@ func targetFor(ctx context.Context, rc *appconsumer.RoutableConsumer, reg *regis t := StaticTarget(reg) if rc != nil && rc.Consumer != nil { t.PinKey = fmt.Sprintf("%s:%s:%s", rc.Consumer.GatewayID, rc.Consumer.ID, reg.ID) - if perPrincipalAuth(reg) { + if perPrincipalAuth(reg) || reg.MCPTarget.HasUserHeaders() { if p := identity.PrincipalFromContext(ctx); p != nil { t.PinKey += ":" + p.Subject } diff --git a/pkg/app/mcp/user_headers.go b/pkg/app/mcp/user_headers.go new file mode 100644 index 000000000..370c87692 --- /dev/null +++ b/pkg/app/mcp/user_headers.go @@ -0,0 +1,212 @@ +// Copyright 2026 NeuralTrust +// +// 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 mcp + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "errors" + "sort" + "time" + + appconsumer "github.com/NeuralTrust/TrustGate/pkg/app/consumer" + "github.com/NeuralTrust/TrustGate/pkg/common/logref" + consumerdomain "github.com/NeuralTrust/TrustGate/pkg/domain/consumer" + "github.com/NeuralTrust/TrustGate/pkg/domain/identity" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + registrydomain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" +) + +// Cause codes for a call refused because a per-user header has no usable value. +const ( + // ConsentCauseUserHeaderMissing: the caller never entered a value. + ConsentCauseUserHeaderMissing = "user_header_missing" + // ConsentCauseUserHeaderRejected: the upstream answered 401 with the value + // this caller entered, so it has to be entered again. + ConsentCauseUserHeaderRejected = "user_header_rejected" +) + +// applyUserHeaders sets the calling person's own value for every per-user +// header the registry declares. A required header without a usable value +// refuses the call with a connect link; an optional one is left out. +// +// A caller with no individual identity is refused before the vault is read: +// the application itself, or a group key whose owner's value would otherwise +// be sent on behalf of everyone holding the key. +func (r *credentialResolver) applyUserHeaders( + ctx context.Context, + rc *appconsumer.RoutableConsumer, + reg *registrydomain.Registry, + target *Target, +) error { + if reg == nil || !reg.MCPTarget.HasUserHeaders() { + return nil + } + principal := identity.PrincipalFromContext(ctx) + if principal == nil || principal.Subject == "" { + return ErrNoPrincipal + } + label := registryLabelFor(reg) + if principal.KeyGroup() != "" || principal.Subject == consumerdomain.AppSubject(rc.Consumer.ID) { + return &ApplicationNotConnectedError{Provider: label, Registry: label, UserKeys: true} + } + gatewayID := rc.Consumer.GatewayID + if target.Headers == nil { + target.Headers = map[string]string{} + } + resolved := make([]string, 0, len(reg.MCPTarget.UserHeaders)) + for _, h := range reg.MCPTarget.UserHeaders { + value, cause, err := r.userHeaderValue(ctx, gatewayID, principal.Subject, reg, h) + if err != nil { + return err + } + if cause != "" { + if !h.Required { + continue + } + return r.consentRequired(ctx, rc, reg, label, principal.Subject, cause, + "no usable value for a per-user upstream header", "header", h.Name) + } + target.Headers[h.Name] = h.FormatValue(value) + resolved = append(resolved, h.Name+"\x00"+value) + } + // One person's upstream session is never reused for another, and a value + // the person replaced dials a fresh session instead of riding the old one. + sort.Strings(resolved) + sum := sha256.New() + sum.Write([]byte(principal.Issuer + "\x00" + principal.Subject)) + for _, v := range resolved { + sum.Write([]byte{0}) + sum.Write([]byte(v)) + } + target.PinKey += ":h:" + hex.EncodeToString(sum.Sum(nil)[:8]) + return nil +} + +// userHeaderValue reads one person's value for one header. A non-empty cause +// means there is no usable value and says why; err is a vault failure. +func (r *credentialResolver) userHeaderValue( + ctx context.Context, + gatewayID ids.GatewayID, + subject string, + reg *registrydomain.Registry, + h registrydomain.MCPUserHeader, +) (value, cause string, err error) { + if r.vault == nil { + return "", ConsentCauseUserHeaderMissing, nil + } + cred, err := r.vault.Find(ctx, gatewayID, subject, registrydomain.UserHeaderVaultProvider(reg.ID, h.Name)) + switch { + case errors.Is(err, vaultdomain.ErrNotFound): + return "", ConsentCauseUserHeaderMissing, nil + case errors.Is(err, vaultdomain.ErrUndecryptable): + return "", ConsentCauseUndecryptable, nil + case err != nil: + return "", "", err + } + if cred == nil || cred.AccessToken == "" { + return "", ConsentCauseUserHeaderMissing, nil + } + if UserHeaderRejected(cred) { + return "", ConsentCauseUserHeaderRejected, nil + } + return cred.AccessToken, "", nil +} + +// UserHeaderRejected reports whether a stored per-user header value was +// refused by the upstream. A value carries no expiry of its own; the vault's +// reconnect mark (an expiry set to the moment of the refusal) is what records +// that the upstream answered 401 with it. +func UserHeaderRejected(cred *vaultdomain.Credential) bool { + return cred != nil && !cred.ExpiresAt.IsZero() && !cred.ExpiresAt.After(time.Now()) +} + +// rejectUserHeaders marks the per-user header values the caller sent to this +// registry as refused, after the upstream answered 401. Only a value that is +// still the one sent is marked: a person who replaced their key while the call +// was in flight keeps the new one. It reports whether a value was marked, so +// the caller can tell the person to enter it again rather than retry. +func (r *credentialResolver) rejectUserHeaders( + ctx context.Context, + rc *appconsumer.RoutableConsumer, + reg *registrydomain.Registry, + target *Target, +) bool { + if r.vault == nil || reg == nil || !reg.MCPTarget.HasUserHeaders() { + return false + } + principal := identity.PrincipalFromContext(ctx) + if principal == nil || principal.Subject == "" { + return false + } + requirer, ok := r.vault.(vaultdomain.ReconnectRequirer) + if !ok { + return false + } + gatewayID := rc.Consumer.GatewayID + marked := false + for _, h := range reg.MCPTarget.UserHeaders { + provider := registrydomain.UserHeaderVaultProvider(reg.ID, h.Name) + cred, err := r.vault.Find(ctx, gatewayID, principal.Subject, provider) + if err != nil || cred == nil || UserHeaderRejected(cred) { + continue + } + if target == nil || target.Headers[h.Name] != h.FormatValue(cred.AccessToken) { + continue + } + if err := requirer.RequireReconnect(ctx, cred); err != nil && !errors.Is(err, vaultdomain.ErrCredentialChanged) { + r.logger.Warn("mcp user headers: could not mark a rejected value", + "gateway_id", gatewayID.String(), "registry_id", reg.ID.String(), + "principal_ref", logref.Opaque(principal.Subject), "header", h.Name, "error", err) + continue + } + marked = true + r.logger.Info("security audit", + "event", "mcp_user_header_rejected", + "gateway_id", gatewayID.String(), "registry_id", reg.ID.String(), + "principal_ref", logref.Opaque(principal.Subject), "header", h.Name) + } + return marked +} + +// refuseRejectedUserHeaders answers an upstream 401 on a registry whose only +// credential is its per-user headers: the values are marked refused and the +// caller gets a connect link to enter them again. The call is not retried, +// since the same values would be refused again. +// +// A 401 does not say which credential failed. When the auth mode sends one of +// its own — the admin's static key, a client-credentials token, the caller's +// forwarded or exchanged token — that one may be the cause, and marking every +// caller's key refused would make all of them enter it again for nothing, so +// the 401 is returned as it is. +func (r *credentialResolver) refuseRejectedUserHeaders( + ctx context.Context, + rc *appconsumer.RoutableConsumer, + reg *registrydomain.Registry, + target *Target, +) error { + if auth := reg.MCPTarget.Auth; auth != nil && auth.Mode != registrydomain.MCPAuthModeNone && auth.Mode != "" { + return errCredentialRefreshUnsupported + } + if !r.rejectUserHeaders(ctx, rc, reg, target) { + return errCredentialRefreshUnsupported + } + principal := identity.PrincipalFromContext(ctx) + label := registryLabelFor(reg) + return r.consentRequired(ctx, rc, reg, label, principal.Subject, ConsentCauseUserHeaderRejected, + "the upstream refused this caller's per-user header value") +} diff --git a/pkg/app/mcp/user_headers_test.go b/pkg/app/mcp/user_headers_test.go new file mode 100644 index 000000000..231cb9310 --- /dev/null +++ b/pkg/app/mcp/user_headers_test.go @@ -0,0 +1,304 @@ +// Copyright 2026 NeuralTrust +// +// 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 mcp + +import ( + "context" + "errors" + "strings" + "testing" + "time" + + consumerdomain "github.com/NeuralTrust/TrustGate/pkg/domain/consumer" + "github.com/NeuralTrust/TrustGate/pkg/domain/identity" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + registrydomain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" +) + +// userHeaderVault is a memVault that can mark a credential refused, as the +// Postgres and Redis vaults do. +type userHeaderVault struct{ *memVault } + +func (v userHeaderVault) RequireReconnect(_ context.Context, c *vaultdomain.Credential) error { + stored := v.creds[v.key(c.GatewayID, c.PrincipalSub, c.Provider)] + if stored == nil { + return vaultdomain.ErrCredentialChanged + } + stored.ExpiresAt = time.Now().Add(-time.Second) + return nil +} + +func regWithUserHeaders(gw ids.GatewayID, headers ...registrydomain.MCPUserHeader) *registrydomain.Registry { + reg, err := registrydomain.NewMCPRegistry(gw, "keyed", "", ®istrydomain.MCPTarget{ + URL: "https://keyed.example.com/mcp", + Auth: ®istrydomain.MCPAuth{Mode: registrydomain.MCPAuthModeNone}, + Headers: map[string]string{"X-Tenant": "acme"}, + UserHeaders: headers, + }) + if err != nil { + panic(err) + } + return reg +} + +func storeUserHeader(t *testing.T, v *memVault, gw ids.GatewayID, sub string, reg *registrydomain.Registry, header, value string) { + t.Helper() + cred, err := vaultdomain.NewCredential(gw, sub, registrydomain.UserHeaderVaultProvider(reg.ID, header), "", value, "", nil, time.Time{}) + if err != nil { + t.Fatal(err) + } + if err := v.Upsert(context.Background(), cred); err != nil { + t.Fatal(err) + } +} + +func TestApplyUserHeaders_EachCallerSendsTheirOwnValue(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + vault := &memVault{} + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true, Secret: true}) + storeUserHeader(t, vault, gw, "ana", reg, "x-api-key", "ana-key") + storeUserHeader(t, vault, gw, "bruno", reg, "X-API-Key", "bruno-key") + r := NewCredentialResolver(nil, vault, &stubConnect{ticket: "t"}, nil, discardLogger()) + rc := mcpConsumer(gw) + + targets := map[string]Target{} + for _, sub := range []string{"ana", "bruno"} { + ctx := principalCtx(&identity.Principal{Subject: sub, Method: identity.MethodOAuth}) + target := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &target); err != nil { + t.Fatalf("%s: Apply() = %v", sub, err) + } + targets[sub] = target + } + if got := targets["ana"].Headers["X-API-Key"]; got != "ana-key" { + t.Fatalf("ana sent %q", got) + } + if got := targets["bruno"].Headers["X-API-Key"]; got != "bruno-key" { + t.Fatalf("bruno sent %q", got) + } + if targets["ana"].Headers["X-Tenant"] != "acme" { + t.Fatal("shared header dropped") + } + if targets["ana"].PinKey == targets["bruno"].PinKey { + t.Fatal("two callers share an upstream session") + } + for _, tg := range targets { + if strings.Contains(tg.PinKey, "key") { + t.Fatalf("pin key carries the value: %s", tg.PinKey) + } + } +} + +func TestApplyUserHeaders_SchemeAndRotation(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + vault := &memVault{} + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "Authorization", Scheme: "Bearer", Required: true}) + storeUserHeader(t, vault, gw, "ana", reg, "Authorization", "one") + r := NewCredentialResolver(nil, vault, &stubConnect{}, nil, discardLogger()) + rc := mcpConsumer(gw) + ctx := principalCtx(&identity.Principal{Subject: "ana"}) + + first := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &first); err != nil { + t.Fatal(err) + } + if first.Headers["Authorization"] != "Bearer one" { + t.Fatalf("got %q", first.Headers["Authorization"]) + } + storeUserHeader(t, vault, gw, "ana", reg, "Authorization", "two") + second := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &second); err != nil { + t.Fatal(err) + } + if first.PinKey == second.PinKey { + t.Fatal("a replaced value must dial a new session") + } +} + +func TestApplyUserHeaders_MissingValue(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + rc := mcpConsumer(gw) + ctx := principalCtx(&identity.Principal{Subject: "ana"}) + + t.Run("required asks for consent", func(t *testing.T) { + t.Parallel() + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + r := NewCredentialResolver(nil, &memVault{}, &stubConnect{ticket: "tk"}, nil, discardLogger()) + target := targetFor(ctx, rc, reg) + err := r.Apply(ctx, rc, reg, &target) + var consent *ConsentRequiredError + if !errors.As(err, &consent) || consent.Cause != ConsentCauseUserHeaderMissing || consent.Ticket != "tk" { + t.Fatalf("Apply() = %v, want consent with ticket", err) + } + }) + t.Run("optional is left out", func(t *testing.T) { + t.Parallel() + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-Account"}) + r := NewCredentialResolver(nil, &memVault{}, &stubConnect{}, nil, discardLogger()) + target := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &target); err != nil { + t.Fatal(err) + } + if _, ok := target.Headers["X-Account"]; ok { + t.Fatal("optional header without a value was sent") + } + }) +} + +func TestApplyUserHeaders_CallerWithoutIndividualIdentity(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + vault := &memVault{} + rc := mcpConsumer(gw) + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + storeUserHeader(t, vault, gw, "owner", reg, "X-API-Key", "owner-key") + r := NewCredentialResolver(nil, vault, &stubConnect{}, nil, discardLogger()) + + cases := map[string]*identity.Principal{ + "application itself": {Subject: consumerdomain.AppSubject(rc.Consumer.ID), Method: identity.MethodAPIKey}, + "group key": {Subject: "owner", Method: identity.MethodPersonalKey, + Claims: map[string]any{identity.ClaimKeyGroup: "engineering"}}, + } + for name, p := range cases { + t.Run(name, func(t *testing.T) { + t.Parallel() + ctx := principalCtx(p) + target := targetFor(ctx, rc, reg) + err := r.Apply(ctx, rc, reg, &target) + var notConnected *ApplicationNotConnectedError + if !errors.As(err, ¬Connected) { + t.Fatalf("Apply() = %v, want ApplicationNotConnectedError", err) + } + if _, sent := target.Headers["X-API-Key"]; sent { + t.Fatal("a value was sent for a caller with no individual identity") + } + }) + } + t.Run("no principal", func(t *testing.T) { + t.Parallel() + target := targetFor(context.Background(), rc, reg) + if err := r.Apply(context.Background(), rc, reg, &target); !errors.Is(err, ErrNoPrincipal) { + t.Fatalf("Apply() = %v, want ErrNoPrincipal", err) + } + }) +} + +func TestApplyUserHeaders_InstancesHoldSeparateValues(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + vault := &memVault{} + pre := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + pro := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + storeUserHeader(t, vault, gw, "ana", pre, "X-API-Key", "pre-key") + r := NewCredentialResolver(nil, vault, &stubConnect{}, nil, discardLogger()) + rc := mcpConsumer(gw) + ctx := principalCtx(&identity.Principal{Subject: "ana"}) + + target := targetFor(ctx, rc, pro) + var consent *ConsentRequiredError + if err := r.Apply(ctx, rc, pro, &target); !errors.As(err, &consent) { + t.Fatalf("PRO reused PRE's value: %v", err) + } +} + +func TestRefresh_UpstreamRejectsUserHeader(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + vault := userHeaderVault{&memVault{}} + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + storeUserHeader(t, vault.memVault, gw, "ana", reg, "X-API-Key", "stale") + r := NewCredentialResolver(nil, vault, &stubConnect{ticket: "tk"}, nil, discardLogger()).(*credentialResolver) + rc := mcpConsumer(gw) + ctx := principalCtx(&identity.Principal{Subject: "ana"}) + + target := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &target); err != nil { + t.Fatal(err) + } + var consent *ConsentRequiredError + if err := r.Refresh(ctx, rc, reg, &target); !errors.As(err, &consent) || consent.Cause != ConsentCauseUserHeaderRejected { + t.Fatalf("Refresh() = %v, want consent with rejected cause", err) + } + next := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &next); !errors.As(err, &consent) || consent.Cause != ConsentCauseUserHeaderRejected { + t.Fatalf("Apply() after a 401 = %v, want the rejected value refused before dialing", err) + } + + t.Run("a registry without user headers keeps refusing to refresh", func(t *testing.T) { + t.Parallel() + plain := regWithAuth(gw, ®istrydomain.MCPAuth{Mode: registrydomain.MCPAuthModeNone}) + tg := targetFor(ctx, rc, plain) + if err := r.Refresh(ctx, rc, plain, &tg); !errors.Is(err, errCredentialRefreshUnsupported) { + t.Fatalf("Refresh() = %v, want unsupported", err) + } + }) +} + +func TestRefresh_UserHeaderRejectionIsNarrow(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + rc := mcpConsumer(gw) + ctx := principalCtx(&identity.Principal{Subject: "ana"}) + + t.Run("a key replaced while the call was in flight is kept", func(t *testing.T) { + t.Parallel() + vault := userHeaderVault{&memVault{}} + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + storeUserHeader(t, vault.memVault, gw, "ana", reg, "X-API-Key", "old") + r := NewCredentialResolver(nil, vault, &stubConnect{}, nil, discardLogger()).(*credentialResolver) + target := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &target); err != nil { + t.Fatal(err) + } + storeUserHeader(t, vault.memVault, gw, "ana", reg, "X-API-Key", "new") + if err := r.Refresh(ctx, rc, reg, &target); !errors.Is(err, errCredentialRefreshUnsupported) { + t.Fatalf("Refresh() = %v, want the 401 returned as is", err) + } + next := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &next); err != nil || next.Headers["X-API-Key"] != "new" { + t.Fatalf("the new key was marked refused: %v %q", err, next.Headers["X-API-Key"]) + } + }) + + t.Run("an auth mode with a credential of its own leaves the keys alone", func(t *testing.T) { + t.Parallel() + vault := userHeaderVault{&memVault{}} + reg, err := registrydomain.NewMCPRegistry(gw, "both", "", ®istrydomain.MCPTarget{ + URL: "https://both.example.com/mcp", + Auth: ®istrydomain.MCPAuth{Mode: registrydomain.MCPAuthModeStatic, Header: "Authorization", Value: "Bearer admin"}, + UserHeaders: []registrydomain.MCPUserHeader{{Name: "X-API-Key", Required: true}}, + }) + if err != nil { + t.Fatal(err) + } + storeUserHeader(t, vault.memVault, gw, "ana", reg, "X-API-Key", "ana-key") + r := NewCredentialResolver(nil, vault, &stubConnect{}, nil, discardLogger()).(*credentialResolver) + target := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &target); err != nil { + t.Fatal(err) + } + if err := r.Refresh(ctx, rc, reg, &target); !errors.Is(err, errCredentialRefreshUnsupported) { + t.Fatalf("Refresh() = %v, want the 401 returned as is", err) + } + next := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &next); err != nil { + t.Fatalf("ana's key was marked refused for the admin's credential: %v", err) + } + }) +} diff --git a/pkg/app/oauth/connect.go b/pkg/app/oauth/connect.go index 38830185c..243e1bd4c 100644 --- a/pkg/app/oauth/connect.go +++ b/pkg/app/oauth/connect.go @@ -318,7 +318,12 @@ func (s *connectService) Page(ctx context.Context, ticketID string) (*ConnectPag if err != nil { return nil, err } + userHeaders, err := s.userHeaderServers(ctx, gatewayID, ticket, data, rc) + if err != nil { + return nil, err + } page := &ConnectPage{ + UserHeaders: userHeaders, ConsumerPath: ticket.ConsumerPath, ResumeURL: ticket.ResumeURL, Providers: providers, diff --git a/pkg/app/oauth/connect_types.go b/pkg/app/oauth/connect_types.go index 500d8aea8..a6d9c33fd 100644 --- a/pkg/app/oauth/connect_types.go +++ b/pkg/app/oauth/connect_types.go @@ -219,6 +219,9 @@ type ConnectPage struct { Principal ConnectPrincipal // ClientName is the app the link came from, empty when unknown. ClientName string + // UserHeaders are the servers whose upstream needs this person's own + // header values (an API key), each with what is stored. + UserHeaders []UserHeaderServer } //go:generate mockery --name=ConnectService --dir=. --output=./mocks --filename=oauth_connect_service_mock.go --case=underscore --with-expecter diff --git a/pkg/app/oauth/connect_user_headers.go b/pkg/app/oauth/connect_user_headers.go new file mode 100644 index 000000000..e3d968a7b --- /dev/null +++ b/pkg/app/oauth/connect_user_headers.go @@ -0,0 +1,243 @@ +// Copyright 2026 NeuralTrust +// +// 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 oauth + +import ( + "context" + "errors" + "fmt" + "strings" + "time" + + appconsumer "github.com/NeuralTrust/TrustGate/pkg/app/consumer" + appregistry "github.com/NeuralTrust/TrustGate/pkg/app/registry" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + registrydomain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" +) + +var ( + // ErrUserHeaderServerNotFound: the ticket cannot act on a server with + // per-user headers by that instance id. + ErrUserHeaderServerNotFound = errors.New("oauth connect: no server with per-user headers by that id on this link") + // ErrUserHeaderInvalid wraps a value or field the form cannot accept. The + // text names the header, never the value. + ErrUserHeaderInvalid = errors.New("oauth connect: invalid per-user header value") +) + +// UserHeaderField is one per-user header as the connect page shows it to the +// person whose value it is. +type UserHeaderField struct { + Name string + Description string + Required bool + Secret bool + // Set reports whether the person has a value stored. + Set bool + // Rejected reports whether the upstream refused the stored value, so it + // has to be entered again. + Rejected bool + // Value is the stored value of a non-secret header, shown so the person + // can check and edit it. Always empty for a secret header. + Value string + // UpdatedAt is when the value was last written; zero when unset. + UpdatedAt time.Time +} + +// UserHeaderServer is one registry instance whose upstream needs the +// person's own header values. +type UserHeaderServer struct { + Registry string + Instance string + Code string + Fields []UserHeaderField +} + +// Missing reports whether a required header has no usable value, so a call +// to this server is refused until the person enters it. +func (s UserHeaderServer) Missing() bool { + for _, f := range s.Fields { + if f.Required && (!f.Set || f.Rejected) { + return true + } + } + return false +} + +// UserHeaderEnrollment writes and removes a person's per-user header values +// through the connect link they were handed. The link is the authority, as it +// is for connecting an OAuth account: it names the principal the values are +// stored for. +type UserHeaderEnrollment interface { + // SaveUserHeaders stores the values entered for one instance. A secret + // field sent empty keeps the stored value; unknown fields are refused. + SaveUserHeaders(ctx context.Context, ticketID, instanceID string, values map[string]string) error + // RemoveUserHeaders deletes every value the person holds for one instance. + RemoveUserHeaders(ctx context.Context, ticketID, instanceID string) error +} + +var _ UserHeaderEnrollment = (*connectService)(nil) + +// userHeaderServers lists the instances this ticket can enter header values +// for. An application's ticket has none: an application has no individual +// identity to hold a person's key, and the runtime refuses it before reading +// one. +func (s *connectService) userHeaderServers( + ctx context.Context, + gatewayID ids.GatewayID, + ticket *ConnectTicket, + data *appconsumer.Data, + rc *appconsumer.RoutableConsumer, +) ([]UserHeaderServer, error) { + if ticket.Providers != nil || strings.TrimSpace(ticket.PrincipalSub) == "" { + return nil, nil + } + var out []UserHeaderServer + for _, reg := range data.EffectiveRegistries(rc) { + if !userHeaderRegistryAllowed(ticket, reg) { + continue + } + server := UserHeaderServer{Registry: reg.Name, Instance: reg.ID.String(), Code: reg.MCPTarget.Code} + for _, h := range reg.MCPTarget.UserHeaders { + field := UserHeaderField{Name: h.Name, Description: h.Description, Required: h.Required, Secret: h.Secret} + cred, err := s.vault.Find(ctx, gatewayID, ticket.PrincipalSub, registrydomain.UserHeaderVaultProvider(reg.ID, h.Name)) + switch { + case err == nil && cred != nil && cred.AccessToken != "": + field.Set = true + field.Rejected = !cred.ExpiresAt.IsZero() && !cred.ExpiresAt.After(time.Now()) + field.UpdatedAt = cred.UpdatedAt + if !h.Secret { + field.Value = cred.AccessToken + } + case errors.Is(err, vaultdomain.ErrUndecryptable): + field.Set = true + field.Rejected = true + case err != nil && !errors.Is(err, vaultdomain.ErrNotFound): + return nil, fmt.Errorf("oauth connect: read per-user header: %w", err) + } + server.Fields = append(server.Fields, field) + } + out = append(out, server) + } + return out, nil +} + +// userHeaderRegistryAllowed reports whether a person's ticket may show and +// write header values for reg. A ticket pinned to an instance reaches that +// instance only; one pinned to an OAuth provider reaches no header server. +func userHeaderRegistryAllowed(ticket *ConnectTicket, reg *registrydomain.Registry) bool { + if reg == nil || !reg.Enabled || !reg.IsMCP() || !reg.MCPTarget.HasUserHeaders() { + return false + } + if pinned := strings.TrimSpace(ticket.InstanceID); pinned != "" { + return pinned == reg.ID.String() + } + if code := strings.TrimSpace(ticket.Code); code != "" { + return code == strings.TrimSpace(reg.MCPTarget.Code) + } + return strings.TrimSpace(ticket.Provider) == "" +} + +func (s *connectService) userHeaderRegistry( + ctx context.Context, + ticketID, instanceID string, +) (*ConnectTicket, ids.GatewayID, *registrydomain.Registry, error) { + ticket, gatewayID, data, rc, err := s.resolve(ctx, ticketID) + if err != nil { + return nil, ids.GatewayID{}, nil, err + } + if ticket.Providers != nil || strings.TrimSpace(ticket.PrincipalSub) == "" { + return nil, ids.GatewayID{}, nil, ErrUserHeaderServerNotFound + } + for _, reg := range data.EffectiveRegistries(rc) { + if reg != nil && reg.ID.String() == instanceID && userHeaderRegistryAllowed(ticket, reg) { + return ticket, gatewayID, reg, nil + } + } + return nil, ids.GatewayID{}, nil, ErrUserHeaderServerNotFound +} + +func (s *connectService) SaveUserHeaders(ctx context.Context, ticketID, instanceID string, values map[string]string) error { + ticket, gatewayID, reg, err := s.userHeaderRegistry(ctx, ticketID, instanceID) + if err != nil { + return err + } + for name := range values { + if _, ok := reg.MCPTarget.UserHeader(name); !ok { + return fmt.Errorf("%w: %q is not a header of this server", ErrUserHeaderInvalid, name) + } + } + // Every value is checked before any is written, so a bad field never + // leaves the person half enrolled. + writes := make(map[string]string, len(values)) + for _, h := range reg.MCPTarget.UserHeaders { + value, sent := lookupFold(values, h.Name) + value = strings.TrimSpace(value) + if !sent || value == "" { + if !h.Required { + continue + } + if _, err := s.vault.Find(ctx, gatewayID, ticket.PrincipalSub, registrydomain.UserHeaderVaultProvider(reg.ID, h.Name)); err == nil { + continue + } + return fmt.Errorf("%w: header %q needs a value", ErrUserHeaderInvalid, h.Name) + } + if err := registrydomain.ValidateUserHeaderValue(h, value); err != nil { + return fmt.Errorf("%w: %w", ErrUserHeaderInvalid, err) + } + writes[h.Name] = value + } + for name, value := range writes { + cred, err := vaultdomain.NewCredential(gatewayID, ticket.PrincipalSub, + registrydomain.UserHeaderVaultProvider(reg.ID, name), "", value, "", nil, time.Time{}) + if err != nil { + return err + } + if err := appregistry.WriteUserHeaderCredential(ctx, s.vault, cred); err != nil { + return err + } + appregistry.AuditUserHeader(ctx, nil, appregistry.UserHeaderAuditSet, gatewayID, reg.ID, ticket.PrincipalSub, name, "self") + } + return nil +} + +func (s *connectService) RemoveUserHeaders(ctx context.Context, ticketID, instanceID string) error { + ticket, gatewayID, reg, err := s.userHeaderRegistry(ctx, ticketID, instanceID) + if err != nil { + return err + } + for _, h := range reg.MCPTarget.UserHeaders { + err := s.vault.Delete(ctx, gatewayID, ticket.PrincipalSub, registrydomain.UserHeaderVaultProvider(reg.ID, h.Name)) + if err != nil && !errors.Is(err, vaultdomain.ErrNotFound) { + return err + } + if err == nil { + appregistry.AuditUserHeader(ctx, nil, appregistry.UserHeaderAuditRemoved, gatewayID, reg.ID, ticket.PrincipalSub, h.Name, "self") + } + } + return nil +} + +func lookupFold(values map[string]string, name string) (string, bool) { + if v, ok := values[name]; ok { + return v, true + } + for k, v := range values { + if strings.EqualFold(k, name) { + return v, true + } + } + return "", false +} diff --git a/pkg/app/oauth/connect_user_headers_test.go b/pkg/app/oauth/connect_user_headers_test.go new file mode 100644 index 000000000..ca2e143d3 --- /dev/null +++ b/pkg/app/oauth/connect_user_headers_test.go @@ -0,0 +1,175 @@ +// Copyright 2026 NeuralTrust +// +// 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 oauth_test + +import ( + "context" + "errors" + "testing" + + appconsumer "github.com/NeuralTrust/TrustGate/pkg/app/consumer" + "github.com/NeuralTrust/TrustGate/pkg/app/oauth" + consumerdomain "github.com/NeuralTrust/TrustGate/pkg/domain/consumer" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + registrydomain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" + infraoauth "github.com/NeuralTrust/TrustGate/pkg/infra/oauth" + "github.com/stretchr/testify/require" +) + +type userHeaderFixture struct { + service oauth.ConnectService + enroll oauth.UserHeaderEnrollment + store *memConnectStore + vault *memVaultRepo + gatewayID ids.GatewayID + keyed *registrydomain.Registry + other *registrydomain.Registry +} + +func newUserHeaderFixture(t *testing.T) userHeaderFixture { + t.Helper() + gatewayID := ids.New[ids.GatewayKind]() + keyed, err := registrydomain.NewMCPRegistry(gatewayID, "Keyed API", "", ®istrydomain.MCPTarget{ + URL: "https://keyed.example/mcp", + Auth: ®istrydomain.MCPAuth{Mode: registrydomain.MCPAuthModeNone}, + UserHeaders: []registrydomain.MCPUserHeader{ + {Name: "X-API-Key", Required: true, Secret: true, Description: "Your personal key"}, + {Name: "X-Account", Description: "Account id"}, + }, + }) + require.NoError(t, err) + other, err := registrydomain.NewMCPRegistry(gatewayID, "Plain", "", ®istrydomain.MCPTarget{ + URL: "https://plain.example/mcp", + Auth: ®istrydomain.MCPAuth{Mode: registrydomain.MCPAuthModeNone}, + }) + require.NoError(t, err) + data := appconsumer.NewData(gatewayID, []appconsumer.RoutableConsumer{{ + Consumer: &consumerdomain.Consumer{ + ID: ids.New[ids.ConsumerKind](), GatewayID: gatewayID, + Type: consumerdomain.TypeMCP, Slug: "dev", Active: true, + }, + Registries: []*registrydomain.Registry{keyed, other}, + }}) + store := newMemConnectStore() + vault := &memVaultRepo{} + service := oauth.NewConnectService(store, vault, &stubDataFinder{data: data}, + infraoauth.NewProviderClient(nil), infraoauth.NewUpstreamRegistrar(store, nil), + oauth.NewConnectAuditor(nil), nil, nil, nil, nil) + enroll, ok := service.(oauth.UserHeaderEnrollment) + require.True(t, ok, "the connect service serves per-user header enrollment") + return userHeaderFixture{service: service, enroll: enroll, store: store, vault: vault, + gatewayID: gatewayID, keyed: keyed, other: other} +} + +func (f userHeaderFixture) ticketFor(t *testing.T, sub string) string { + t.Helper() + ticket, err := f.service.CreateTicket(context.Background(), f.gatewayID, sub, "/dev/mcp") + require.NoError(t, err) + return ticket +} + +func TestUserHeaders_PageListsOnlyServersWithHeaders(t *testing.T) { + f := newUserHeaderFixture(t) + page, err := f.service.Page(context.Background(), f.ticketFor(t, "ana")) + require.NoError(t, err) + require.Len(t, page.UserHeaders, 1) + server := page.UserHeaders[0] + require.Equal(t, f.keyed.ID.String(), server.Instance) + require.True(t, server.Missing()) + require.Len(t, server.Fields, 2) + require.False(t, server.Fields[0].Set) +} + +func TestUserHeaders_SaveStoresPerPrincipalAndNeverShowsSecrets(t *testing.T) { + f := newUserHeaderFixture(t) + ctx := context.Background() + ana := f.ticketFor(t, "ana") + require.NoError(t, f.enroll.SaveUserHeaders(ctx, ana, f.keyed.ID.String(), + map[string]string{"x-api-key": "ana-secret", "X-Account": "acct-1"})) + + cred, err := f.vault.Find(ctx, f.gatewayID, "ana", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-API-Key")) + require.NoError(t, err) + require.Equal(t, "ana-secret", cred.AccessToken) + _, err = f.vault.Find(ctx, f.gatewayID, "bruno", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-API-Key")) + require.ErrorIs(t, err, vaultdomain.ErrNotFound) + + page, err := f.service.Page(ctx, ana) + require.NoError(t, err) + fields := page.UserHeaders[0].Fields + require.True(t, fields[0].Set) + require.Empty(t, fields[0].Value, "a secret is never written back into the page") + require.Equal(t, "acct-1", fields[1].Value) + require.False(t, page.UserHeaders[0].Missing()) + + // An empty secret keeps the stored value: the page never sends it back. + require.NoError(t, f.enroll.SaveUserHeaders(ctx, ana, f.keyed.ID.String(), + map[string]string{"X-API-Key": "", "X-Account": "acct-2"})) + cred, err = f.vault.Find(ctx, f.gatewayID, "ana", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-API-Key")) + require.NoError(t, err) + require.Equal(t, "ana-secret", cred.AccessToken) +} + +func TestUserHeaders_SaveRefusesBadInputBeforeWriting(t *testing.T) { + f := newUserHeaderFixture(t) + ctx := context.Background() + ana := f.ticketFor(t, "ana") + cases := map[string]map[string]string{ + "required missing": {"X-Account": "acct"}, + "crlf": {"X-API-Key": "k\r\nX-Evil: 1", "X-Account": "acct"}, + "unknown header": {"X-API-Key": "k", "X-Other": "v"}, + } + for name, values := range cases { + t.Run(name, func(t *testing.T) { + err := f.enroll.SaveUserHeaders(ctx, ana, f.keyed.ID.String(), values) + require.ErrorIs(t, err, oauth.ErrUserHeaderInvalid) + require.NotContains(t, err.Error(), "X-Evil") + _, err = f.vault.Find(ctx, f.gatewayID, "ana", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-Account")) + require.ErrorIs(t, err, vaultdomain.ErrNotFound, "nothing is written when one field is refused") + }) + } +} + +func TestUserHeaders_ScopeOfTheTicket(t *testing.T) { + f := newUserHeaderFixture(t) + ctx := context.Background() + ana := f.ticketFor(t, "ana") + + err := f.enroll.SaveUserHeaders(ctx, ana, f.other.ID.String(), map[string]string{"X-API-Key": "k"}) + require.ErrorIs(t, err, oauth.ErrUserHeaderServerNotFound) + err = f.enroll.SaveUserHeaders(ctx, "no-such-ticket", f.keyed.ID.String(), map[string]string{"X-API-Key": "k"}) + require.True(t, errors.Is(err, oauth.ErrTicketNotFound)) + + pinned, err := f.service.CreateServerTicket(ctx, f.gatewayID, "ana", "/dev/mcp", "", f.other.ID.String()) + require.NoError(t, err) + err = f.enroll.SaveUserHeaders(ctx, pinned, f.keyed.ID.String(), map[string]string{"X-API-Key": "k"}) + require.ErrorIs(t, err, oauth.ErrUserHeaderServerNotFound, "a ticket pinned to another instance cannot write here") +} + +func TestUserHeaders_RemoveDeletesOnlyThisPersonsValues(t *testing.T) { + f := newUserHeaderFixture(t) + ctx := context.Background() + ana, bruno := f.ticketFor(t, "ana"), f.ticketFor(t, "bruno") + require.NoError(t, f.enroll.SaveUserHeaders(ctx, ana, f.keyed.ID.String(), map[string]string{"X-API-Key": "a"})) + require.NoError(t, f.enroll.SaveUserHeaders(ctx, bruno, f.keyed.ID.String(), map[string]string{"X-API-Key": "b"})) + + require.NoError(t, f.enroll.RemoveUserHeaders(ctx, ana, f.keyed.ID.String())) + + _, err := f.vault.Find(ctx, f.gatewayID, "ana", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-API-Key")) + require.ErrorIs(t, err, vaultdomain.ErrNotFound) + cred, err := f.vault.Find(ctx, f.gatewayID, "bruno", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-API-Key")) + require.NoError(t, err) + require.Equal(t, "b", cred.AccessToken) +} diff --git a/pkg/app/registry/updater.go b/pkg/app/registry/updater.go index 075d487ca..2a228c3a3 100644 --- a/pkg/app/registry/updater.go +++ b/pkg/app/registry/updater.go @@ -260,6 +260,9 @@ func applyMCPTargetUpdate( if incoming.Headers == nil { incoming.Headers = prev.Headers } + if incoming.UserHeaders == nil { + incoming.UserHeaders = prev.UserHeaders + } if incoming.Auth == nil { incoming.Auth = prev.Auth } diff --git a/pkg/app/registry/updater_test.go b/pkg/app/registry/updater_test.go index 45ceb6a36..13dfb8bb0 100644 --- a/pkg/app/registry/updater_test.go +++ b/pkg/app/registry/updater_test.go @@ -780,3 +780,45 @@ func TestUpdater_Update_RestoresMaskedProviderOptionHeader(t *testing.T) { t.Fatalf("Update: %v", err) } } + +func TestUpdater_Update_UserHeadersKeptWhenOmittedAndClearedWhenEmpty(t *testing.T) { + t.Parallel() + declared := []domain.MCPUserHeader{{Name: "X-API-Key", Required: true, Secret: true}} + cases := []struct { + name string + incoming []domain.MCPUserHeader + want int + }{ + {name: "omitted keeps the declarations", incoming: nil, want: 1}, + {name: "empty list removes them", incoming: []domain.MCPUserHeader{}, want: 0}, + {name: "a new list replaces them", incoming: []domain.MCPUserHeader{{Name: "X-Account"}, {Name: "X-Key"}}, want: 2}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + repo := repomocks.NewRepository(t) + existing, err := domain.NewMCPRegistry(ids.New[ids.GatewayKind](), "keyed", "", &domain.MCPTarget{ + URL: "https://keyed.example.com/mcp", + UserHeaders: declared, + }) + if err != nil { + t.Fatalf("NewMCPRegistry error: %v", err) + } + repo.EXPECT().FindByID(mock.Anything, existing.ID).Return(existing, nil).Once() + repo.EXPECT().Update(mock.Anything, mock.Anything).Return(nil).Once() + publisher := cachemocks.NewEventPublisher(t) + publisher.EXPECT().Publish(mock.Anything, mock.Anything).Return(nil).Once() + updater := appregistry.NewUpdater(repo, newCacheManager(), publisher, newTestLogger(), nil, nil) + got, err := updater.Update(context.Background(), appregistry.UpdateInput{ + ID: existing.ID, + MCPTarget: &domain.MCPTarget{UserHeaders: tc.incoming}, + }) + if err != nil { + t.Fatalf("Update error: %v", err) + } + if len(got.MCPTarget.UserHeaders) != tc.want { + t.Fatalf("user headers = %+v, want %d", got.MCPTarget.UserHeaders, tc.want) + } + }) + } +} diff --git a/pkg/app/registry/user_headers.go b/pkg/app/registry/user_headers.go new file mode 100644 index 000000000..7a78571bf --- /dev/null +++ b/pkg/app/registry/user_headers.go @@ -0,0 +1,410 @@ +// Copyright 2026 NeuralTrust +// +// 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 registry + +import ( + "context" + "errors" + "fmt" + "log/slog" + "sort" + "strings" + "time" + + appconsumer "github.com/NeuralTrust/TrustGate/pkg/app/consumer" + commonerrors "github.com/NeuralTrust/TrustGate/pkg/common/errors" + "github.com/NeuralTrust/TrustGate/pkg/common/logref" + consumerdomain "github.com/NeuralTrust/TrustGate/pkg/domain/consumer" + "github.com/NeuralTrust/TrustGate/pkg/domain/identity" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + domain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" +) + +// Audit events for per-user header values. They carry the header name and an +// opaque principal reference, never the value. +const ( + UserHeaderAuditSet = "mcp_user_header_set" + UserHeaderAuditRemoved = "mcp_user_header_removed" + UserHeaderAuditReset = "mcp_user_header_reset" + UserHeaderAuditImported = "mcp_user_header_imported" + UserHeaderAuditLink = "mcp_user_header_link_issued" +) + +// MaxUserHeaderImportRows bounds one bulk import request. +const MaxUserHeaderImportRows = 1000 + +var ( + // ErrNoUserHeaders is a registry that declares no per-user header. + ErrNoUserHeaders = fmt.Errorf("registry: this server declares no per-user headers: %w", commonerrors.ErrConflict) + // ErrUserHeaderImportInvalid wraps a row the import refuses. The text names + // the row and the header, never the value. + ErrUserHeaderImportInvalid = fmt.Errorf("registry: invalid per-user header import: %w", commonerrors.ErrValidation) + // ErrUserHeaderAdminUnavailable is a plane whose vault cannot list or + // reset values across people. + ErrUserHeaderAdminUnavailable = fmt.Errorf("registry: per-user header administration is not available here: %w", commonerrors.ErrNotFound) +) + +// UserHeaderValueState is what an admin sees of one person's value for one +// header: whether it exists and when it was written or refused. Never the value. +type UserHeaderValueState struct { + Header string + UpdatedAt time.Time + // RejectedAt is when the upstream refused the value with a 401; zero when + // it has not. + RejectedAt time.Time +} + +// UserHeaderHolder is one person and the values they hold for an instance. +type UserHeaderHolder struct { + PrincipalSub string + Values []UserHeaderValueState + // Missing lists the required headers this person has no usable value for. + Missing []string +} + +// UserHeaderImportRow is one value an admin loads for one person. +type UserHeaderImportRow struct { + PrincipalSub string + Header string + Value string +} + +// UserHeaderLink is a connect page an admin hands one person to enter their +// own values. +type UserHeaderLink struct { + Ticket string + ConsumerPath string +} + +type UserHeaderAdmin interface { + // Holders lists every person holding a value for the instance. + Holders(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID) ([]UserHeaderHolder, error) + // Reset removes the values of one person, or of everyone when + // principalSub is empty, and reports how many it removed. + Reset(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID, principalSub string) (int, error) + // Import stores values for many people at once. Every row is checked + // before any is written. + Import(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID, rows []UserHeaderImportRow) (int, error) + // Link mints the connect page for one person. consumerPath is the virtual + // MCP the person reaches the server through; empty uses the Store. + Link(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID, principalSub, consumerPath, resumeURL string) (*UserHeaderLink, error) +} + +type userHeaderAdmin struct { + registries Finder + vault vaultdomain.Repository + tickets ServerTicketMinter + logger *slog.Logger +} + +func NewUserHeaderAdmin(registries Finder, vault vaultdomain.Repository, tickets ServerTicketMinter, logger *slog.Logger) UserHeaderAdmin { + if logger == nil { + logger = slog.Default() + } + return &userHeaderAdmin{registries: registries, vault: vault, tickets: tickets, logger: logger} +} + +func (s *userHeaderAdmin) registry(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID) (*domain.Registry, error) { + reg, err := s.registries.FindByID(ctx, gatewayID, registryID) + if err != nil { + return nil, err + } + if !reg.IsMCP() || !reg.MCPTarget.HasUserHeaders() { + return nil, ErrNoUserHeaders + } + return reg, nil +} + +func (s *userHeaderAdmin) prefixStore() (vaultdomain.ProviderPrefixStore, error) { + store, ok := s.vault.(vaultdomain.ProviderPrefixStore) + if !ok { + return nil, ErrUserHeaderAdminUnavailable + } + return store, nil +} + +func (s *userHeaderAdmin) Holders(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID) ([]UserHeaderHolder, error) { + reg, err := s.registry(ctx, gatewayID, registryID) + if err != nil { + return nil, err + } + store, err := s.prefixStore() + if err != nil { + return nil, err + } + summaries, err := store.ListByProviderPrefix(ctx, gatewayID, domain.UserHeaderVaultPrefix(reg.ID)) + if err != nil { + return nil, err + } + byName := map[string]string{} + for _, h := range reg.MCPTarget.UserHeaders { + byName[domain.UserHeaderVaultProvider(reg.ID, h.Name)] = h.Name + } + holders := map[string]*UserHeaderHolder{} + now := time.Now() + for _, sum := range summaries { + name, declared := byName[sum.Provider] + if !declared { + // A value for a header the admin has since removed is not used; + // it is not shown either. + continue + } + holder := holders[sum.PrincipalSub] + if holder == nil { + holder = &UserHeaderHolder{PrincipalSub: sum.PrincipalSub} + holders[sum.PrincipalSub] = holder + } + state := UserHeaderValueState{Header: name, UpdatedAt: sum.UpdatedAt} + if !sum.ExpiresAt.IsZero() && !sum.ExpiresAt.After(now) { + state.RejectedAt = sum.ExpiresAt + } + holder.Values = append(holder.Values, state) + } + out := make([]UserHeaderHolder, 0, len(holders)) + for _, holder := range holders { + usable := map[string]bool{} + for _, v := range holder.Values { + usable[strings.ToLower(v.Header)] = v.RejectedAt.IsZero() + } + for _, h := range reg.MCPTarget.UserHeaders { + if h.Required && !usable[strings.ToLower(h.Name)] { + holder.Missing = append(holder.Missing, h.Name) + } + } + out = append(out, *holder) + } + sort.Slice(out, func(i, j int) bool { return out[i].PrincipalSub < out[j].PrincipalSub }) + return out, nil +} + +func (s *userHeaderAdmin) Reset(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID, principalSub string) (int, error) { + reg, err := s.registries.FindByID(ctx, gatewayID, registryID) + if err != nil { + return 0, err + } + principalSub = strings.TrimSpace(principalSub) + if principalSub == "" { + store, err := s.prefixStore() + if err != nil { + return 0, err + } + n, err := store.DeleteByProviderPrefix(ctx, gatewayID, domain.UserHeaderVaultPrefix(reg.ID)) + if err != nil { + return 0, err + } + s.audit(ctx, UserHeaderAuditReset, gatewayID, reg.ID, "*", "*") + return n, nil + } + removed := 0 + var headers []domain.MCPUserHeader + if reg.MCPTarget != nil { + headers = reg.MCPTarget.UserHeaders + } + for _, h := range headers { + err := s.vault.Delete(ctx, gatewayID, principalSub, domain.UserHeaderVaultProvider(reg.ID, h.Name)) + switch { + case err == nil: + removed++ + s.audit(ctx, UserHeaderAuditReset, gatewayID, reg.ID, principalSub, h.Name) + case !errors.Is(err, vaultdomain.ErrNotFound): + return removed, err + } + } + return removed, nil +} + +func (s *userHeaderAdmin) Import(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID, rows []UserHeaderImportRow) (int, error) { + reg, err := s.registry(ctx, gatewayID, registryID) + if err != nil { + return 0, err + } + if len(rows) == 0 { + return 0, fmt.Errorf("%w: no rows", ErrUserHeaderImportInvalid) + } + if len(rows) > MaxUserHeaderImportRows { + return 0, fmt.Errorf("%w: at most %d rows per request", ErrUserHeaderImportInvalid, MaxUserHeaderImportRows) + } + creds := make([]*vaultdomain.Credential, 0, len(rows)) + seen := map[string]int{} + for i, row := range rows { + sub := strings.TrimSpace(row.PrincipalSub) + if sub == "" { + return 0, fmt.Errorf("%w: row %d has no principal", ErrUserHeaderImportInvalid, i+1) + } + if !personSubject(sub) { + return 0, fmt.Errorf("%w: row %d names an application or an instance, not a person", ErrUserHeaderImportInvalid, i+1) + } + h, ok := reg.MCPTarget.UserHeader(row.Header) + if !ok { + return 0, fmt.Errorf("%w: row %d: %q is not a header of this server", ErrUserHeaderImportInvalid, i+1, row.Header) + } + value := strings.TrimSpace(row.Value) + if err := domain.ValidateUserHeaderValue(h, value); err != nil { + return 0, fmt.Errorf("%w: row %d: %w", ErrUserHeaderImportInvalid, i+1, err) + } + key := sub + "\x00" + strings.ToLower(h.Name) + if prev, dup := seen[key]; dup { + return 0, fmt.Errorf("%w: rows %d and %d set the same header for the same principal", ErrUserHeaderImportInvalid, prev, i+1) + } + seen[key] = i + 1 + cred, err := vaultdomain.NewCredential(gatewayID, sub, domain.UserHeaderVaultProvider(reg.ID, h.Name), "", value, "", nil, time.Time{}) + if err != nil { + return 0, fmt.Errorf("%w: row %d: %w", ErrUserHeaderImportInvalid, i+1, err) + } + creds = append(creds, cred) + } + written := 0 + for _, cred := range creds { + if err := WriteUserHeaderCredential(ctx, s.vault, cred); err != nil { + return written, err + } + written++ + s.audit(ctx, UserHeaderAuditImported, gatewayID, reg.ID, cred.PrincipalSub, headerOfProvider(cred.Provider)) + } + return written, nil +} + +func (s *userHeaderAdmin) Link( + ctx context.Context, + gatewayID ids.GatewayID, + registryID ids.RegistryID, + principalSub, consumerPath, resumeURL string, +) (*UserHeaderLink, error) { + reg, err := s.registry(ctx, gatewayID, registryID) + if err != nil { + return nil, err + } + principalSub = strings.TrimSpace(principalSub) + if principalSub == "" || !personSubject(principalSub) { + return nil, fmt.Errorf("%w: a person's principal is required", ErrUserHeaderImportInvalid) + } + if s.tickets == nil { + return nil, fmt.Errorf("registry: connect is not available: %w", commonerrors.ErrNotFound) + } + consumerPath = strings.TrimSpace(consumerPath) + if consumerPath == "" { + // Only a server the Store materialised is reached through the Store; a + // custom server is reached through the virtual MCP that binds it, and + // a link to the Store would show the person nothing to fill in. + if reg.MCPTarget.Origin != domain.MCPOriginStore { + return nil, fmt.Errorf("%w: consumer_path is required for a server the Store does not serve", ErrUserHeaderImportInvalid) + } + consumerPath = appconsumer.MCPPath(consumerdomain.StoreSlug) + } + ticket, err := s.tickets.CreateResumableServerTicket( + ctx, gatewayID, principalSub, consumerPath, reg.MCPTarget.Code, reg.ID.String(), strings.TrimSpace(resumeURL), + ) + if err != nil { + return nil, err + } + s.audit(ctx, UserHeaderAuditLink, gatewayID, reg.ID, principalSub, "*") + return &UserHeaderLink{Ticket: ticket, ConsumerPath: consumerPath}, nil +} + +func (s *userHeaderAdmin) audit(ctx context.Context, event string, gatewayID ids.GatewayID, registryID ids.RegistryID, principalSub, header string) { + AuditUserHeader(ctx, s.logger, event, gatewayID, registryID, principalSub, header, "admin") +} + +// WriteUserHeaderCredential stores a per-user header value in the store every +// plane reads (see vaultdomain.SharedStoreUpserter). Writing clears a refusal +// mark: the value is new. +func WriteUserHeaderCredential(ctx context.Context, vault vaultdomain.Repository, cred *vaultdomain.Credential) error { + if shared, ok := vault.(vaultdomain.SharedStoreUpserter); ok { + return shared.UpsertShared(ctx, cred) + } + return vault.Upsert(ctx, cred) +} + +// AuditUserHeader records a change to a person's header value, without it. +// actor says who made it: "self", "admin" or "upstream". +func AuditUserHeader( + ctx context.Context, + logger *slog.Logger, + event string, + gatewayID ids.GatewayID, + registryID ids.RegistryID, + principalSub, header, actor string, +) { + if logger == nil { + logger = slog.Default() + } + ref := principalSub + if principalSub != "*" { + ref = logref.Opaque(principalSub) + } + logger.InfoContext(ctx, "security audit", + slog.String("event", event), + slog.String("gateway_id", gatewayID.String()), + slog.String("registry_id", registryID.String()), + slog.String("principal_ref", ref), + slog.String("header", header), + slog.String("actor", actor), + ) +} + +func headerOfProvider(provider string) string { + if i := strings.LastIndex(provider, ":"); i >= 0 { + return provider[i+1:] + } + return provider +} + +// personSubject reports whether sub can hold a person's values: any subject a +// token carries, or an end user an application named (app::). +// The application itself and an instance's own account are nobody. +func personSubject(sub string) bool { + lowered := strings.ToLower(strings.TrimSpace(sub)) + switch { + case lowered == "": + return false + case strings.HasPrefix(lowered, identity.InstanceSubjectPrefix): + return false + case strings.HasPrefix(lowered, identity.AppSubjectPrefix): + rest := strings.TrimPrefix(lowered, identity.AppSubjectPrefix) + consumer, endUser, ok := strings.Cut(rest, ":") + return ok && consumer != "" && strings.TrimSpace(endUser) != "" + default: + return true + } +} + +// userHeaderValuesCleaner removes every person's header values for a registry +// once it is deleted, so no value outlives the server it was entered for. +type userHeaderValuesCleaner struct { + store vaultdomain.ProviderPrefixStore + logger *slog.Logger +} + +// NewUserHeaderValuesCleaner returns the registry-delete cleanup for per-user +// header values, or nil when the vault cannot remove values across people. +func NewUserHeaderValuesCleaner(vault vaultdomain.Repository, logger *slog.Logger) DependentCleaner { + store, ok := vault.(vaultdomain.ProviderPrefixStore) + if !ok { + return nil + } + return &userHeaderValuesCleaner{store: store, logger: logger} +} + +func (c *userHeaderValuesCleaner) DeleteByRegistry(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID) error { + n, err := c.store.DeleteByProviderPrefix(ctx, gatewayID, domain.UserHeaderVaultPrefix(registryID)) + if err != nil { + return err + } + if n > 0 { + AuditUserHeader(ctx, c.logger, UserHeaderAuditReset, gatewayID, registryID, "*", "*", "registry_deleted") + } + return nil +} diff --git a/pkg/app/registry/user_headers_test.go b/pkg/app/registry/user_headers_test.go new file mode 100644 index 000000000..4b4c6b8c3 --- /dev/null +++ b/pkg/app/registry/user_headers_test.go @@ -0,0 +1,223 @@ +// Copyright 2026 NeuralTrust +// +// 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 registry_test + +import ( + "context" + "strings" + "sync" + "testing" + "time" + + appregistry "github.com/NeuralTrust/TrustGate/pkg/app/registry" + appmocks "github.com/NeuralTrust/TrustGate/pkg/app/registry/mocks" + commonerrors "github.com/NeuralTrust/TrustGate/pkg/common/errors" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + domain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" + "github.com/stretchr/testify/mock" + "github.com/stretchr/testify/require" +) + +// prefixVault is an in-memory vault with the admin prefix operations and a +// replicated write, recording which path a write took. +type prefixVault struct { + mu sync.Mutex + creds map[string]*vaultdomain.Credential + shared int +} + +func newPrefixVault() *prefixVault { return &prefixVault{creds: map[string]*vaultdomain.Credential{}} } + +func vkey(gw ids.GatewayID, sub, provider string) string { + return gw.String() + "\x00" + sub + "\x00" + provider +} + +func (v *prefixVault) Upsert(_ context.Context, c *vaultdomain.Credential) error { + v.mu.Lock() + defer v.mu.Unlock() + cp := *c + cp.UpdatedAt = time.Now() + v.creds[vkey(c.GatewayID, c.PrincipalSub, c.Provider)] = &cp + return nil +} + +func (v *prefixVault) UpsertShared(ctx context.Context, c *vaultdomain.Credential) error { + v.shared++ + return v.Upsert(ctx, c) +} + +func (v *prefixVault) Find(_ context.Context, gw ids.GatewayID, sub, provider string) (*vaultdomain.Credential, error) { + v.mu.Lock() + defer v.mu.Unlock() + c, ok := v.creds[vkey(gw, sub, provider)] + if !ok { + return nil, vaultdomain.ErrNotFound + } + return c, nil +} + +func (v *prefixVault) ListByPrincipal(context.Context, ids.GatewayID, string) ([]*vaultdomain.Credential, error) { + return nil, nil +} + +func (v *prefixVault) Delete(_ context.Context, gw ids.GatewayID, sub, provider string) error { + v.mu.Lock() + defer v.mu.Unlock() + k := vkey(gw, sub, provider) + if _, ok := v.creds[k]; !ok { + return vaultdomain.ErrNotFound + } + delete(v.creds, k) + return nil +} + +func (v *prefixVault) ListByProviderPrefix(_ context.Context, gw ids.GatewayID, prefix string) ([]vaultdomain.CredentialSummary, error) { + v.mu.Lock() + defer v.mu.Unlock() + var out []vaultdomain.CredentialSummary + for _, c := range v.creds { + if c.GatewayID == gw && strings.HasPrefix(c.Provider, prefix) { + out = append(out, vaultdomain.CredentialSummary{ + PrincipalSub: c.PrincipalSub, Provider: c.Provider, ExpiresAt: c.ExpiresAt, UpdatedAt: c.UpdatedAt, + }) + } + } + return out, nil +} + +func (v *prefixVault) DeleteByProviderPrefix(_ context.Context, gw ids.GatewayID, prefix string) (int, error) { + v.mu.Lock() + defer v.mu.Unlock() + n := 0 + for k, c := range v.creds { + if c.GatewayID == gw && strings.HasPrefix(c.Provider, prefix) { + delete(v.creds, k) + n++ + } + } + return n, nil +} + +func keyedRegistry(t *testing.T, gw ids.GatewayID) *domain.Registry { + t.Helper() + reg, err := domain.NewMCPRegistry(gw, "keyed", "", &domain.MCPTarget{ + URL: "https://keyed.example.com/mcp", + Auth: &domain.MCPAuth{Mode: domain.MCPAuthModeNone}, + UserHeaders: []domain.MCPUserHeader{ + {Name: "X-API-Key", Required: true, Secret: true}, + {Name: "X-Account"}, + }, + }) + require.NoError(t, err) + return reg +} + +func TestUserHeaderAdmin_ImportListReset(t *testing.T) { + ctx := context.Background() + gw := ids.New[ids.GatewayKind]() + reg := keyedRegistry(t, gw) + finder := appmocks.NewFinder(t) + finder.EXPECT().FindByID(mock.Anything, gw, reg.ID).Return(reg, nil) + vault := newPrefixVault() + admin := appregistry.NewUserHeaderAdmin(finder, vault, &ticketRecorder{}, nil) + + n, err := admin.Import(ctx, gw, reg.ID, []appregistry.UserHeaderImportRow{ + {PrincipalSub: "ana", Header: "x-api-key", Value: "ana-key"}, + {PrincipalSub: "app:c1:bruno", Header: "X-API-Key", Value: "bruno-key"}, + {PrincipalSub: "bruno-oauth", Header: "X-Account", Value: "acct"}, + }) + require.NoError(t, err) + require.Equal(t, 3, n) + require.Equal(t, 3, vault.shared, "admin writes must land in the store the data plane reads") + + holders, err := admin.Holders(ctx, gw, reg.ID) + require.NoError(t, err) + require.Len(t, holders, 3) + require.Equal(t, "ana", holders[0].PrincipalSub) + require.Empty(t, holders[0].Missing) + require.Equal(t, "bruno-oauth", holders[2].PrincipalSub) + require.Equal(t, []string{"X-API-Key"}, holders[2].Missing) + + removed, err := admin.Reset(ctx, gw, reg.ID, "ana") + require.NoError(t, err) + require.Equal(t, 1, removed) + removed, err = admin.Reset(ctx, gw, reg.ID, "") + require.NoError(t, err) + require.Equal(t, 2, removed) + holders, err = admin.Holders(ctx, gw, reg.ID) + require.NoError(t, err) + require.Empty(t, holders) +} + +func TestUserHeaderAdmin_ImportRefusesBadRowsBeforeWriting(t *testing.T) { + ctx := context.Background() + gw := ids.New[ids.GatewayKind]() + reg := keyedRegistry(t, gw) + finder := appmocks.NewFinder(t) + finder.EXPECT().FindByID(mock.Anything, gw, reg.ID).Return(reg, nil) + cases := map[string][]appregistry.UserHeaderImportRow{ + "unknown header": {{PrincipalSub: "ana", Header: "X-API-Key", Value: "ok"}, {PrincipalSub: "ana", Header: "X-Nope", Value: "v"}}, + "crlf": {{PrincipalSub: "ana", Header: "X-API-Key", Value: "v\r\nX: 1"}}, + "application itself": {{PrincipalSub: "app:c1", Header: "X-API-Key", Value: "v"}}, + "instance subject": {{PrincipalSub: "instance:" + reg.ID.String(), Header: "X-API-Key", Value: "v"}}, + "duplicate": {{PrincipalSub: "ana", Header: "X-API-Key", Value: "a"}, {PrincipalSub: "ana", Header: "x-api-key", Value: "b"}}, + "empty": {}, + } + for name, rows := range cases { + t.Run(name, func(t *testing.T) { + vault := newPrefixVault() + admin := appregistry.NewUserHeaderAdmin(finder, vault, &ticketRecorder{}, nil) + _, err := admin.Import(ctx, gw, reg.ID, rows) + require.ErrorIs(t, err, commonerrors.ErrValidation) + require.NotContains(t, err.Error(), "X: 1", "the error must not echo a value") + require.Empty(t, vault.creds, "nothing is written when one row is refused") + }) + } +} + +func TestUserHeaderAdmin_LinkActsAsThePerson(t *testing.T) { + ctx := context.Background() + gw := ids.New[ids.GatewayKind]() + reg := keyedRegistry(t, gw) + finder := appmocks.NewFinder(t) + finder.EXPECT().FindByID(mock.Anything, gw, reg.ID).Return(reg, nil) + tickets := &ticketRecorder{} + admin := appregistry.NewUserHeaderAdmin(finder, newPrefixVault(), tickets, nil) + + link, err := admin.Link(ctx, gw, reg.ID, "ana", "/dev/mcp", "") + require.NoError(t, err) + require.Equal(t, "tk", link.Ticket) + require.Equal(t, "ana", tickets.last.principalSub) + require.Equal(t, reg.ID.String(), tickets.last.instanceID) + require.Equal(t, "/dev/mcp", tickets.last.consumerPath) + + _, err = admin.Link(ctx, gw, reg.ID, "app:c1", "/dev/mcp", "") + require.ErrorIs(t, err, commonerrors.ErrValidation) + _, err = admin.Link(ctx, gw, reg.ID, "ana", "", "") + require.ErrorIs(t, err, commonerrors.ErrValidation, "a custom server's link names the virtual MCP that binds it") +} + +func TestUserHeaderAdmin_RegistryWithoutUserHeaders(t *testing.T) { + ctx := context.Background() + gw := ids.New[ids.GatewayKind]() + reg, err := domain.NewMCPRegistry(gw, "plain", "", &domain.MCPTarget{URL: "https://p.example.com/mcp"}) + require.NoError(t, err) + finder := appmocks.NewFinder(t) + finder.EXPECT().FindByID(mock.Anything, gw, reg.ID).Return(reg, nil) + admin := appregistry.NewUserHeaderAdmin(finder, newPrefixVault(), &ticketRecorder{}, nil) + _, err = admin.Holders(ctx, gw, reg.ID) + require.ErrorIs(t, err, commonerrors.ErrConflict) +} diff --git a/pkg/app/store/catalog_reapply.go b/pkg/app/store/catalog_reapply.go index 081023e7f..e1d7c94f9 100644 --- a/pkg/app/store/catalog_reapply.go +++ b/pkg/app/store/catalog_reapply.go @@ -317,7 +317,7 @@ func catalogCustomized(target *registrydomain.MCPTarget) bool { if target.Source != "" && target.Source != registrydomain.MCPSourceRemote { return true } - if len(target.Headers) > 0 || len(target.UnreadableHeaders) > 0 { + if len(target.Headers) > 0 || len(target.UnreadableHeaders) > 0 || len(target.UserHeaders) > 0 { return true } auth := target.Auth diff --git a/pkg/container/modules/mcp.go b/pkg/container/modules/mcp.go index 419d0eb79..7c0a5f28c 100644 --- a/pkg/container/modules/mcp.go +++ b/pkg/container/modules/mcp.go @@ -168,6 +168,12 @@ func MCP(c *container.Container) error { if err := c.Provide(registryhttp.NewSharedAccountHandler); err != nil { return err } + if err := c.Provide(provideRegistryUserHeaders); err != nil { + return err + } + if err := c.Provide(registryhttp.NewUserHeadersHandler); err != nil { + return err + } if err := c.Provide(appmcp.NewPluginRunner); err != nil { return err } @@ -661,6 +667,17 @@ func MCPVaultRedis(c *container.Container) error { }) } +// provideRegistryUserHeaders serves an admin's view of the per-user header +// values people hold for an instance. +func provideRegistryUserHeaders( + registries appregistry.Finder, + vault vaultdomain.Repository, + connect appoauth.ConnectService, + logger *slog.Logger, +) appregistry.UserHeaderAdmin { + return appregistry.NewUserHeaderAdmin(registries, vault, connect, logger) +} + // provideRegistrySharedAccounts serves the account an MCP instance holds for // every caller. It is the connect service the runtime already uses, minting the // ticket for the instance instead of for whoever is calling. diff --git a/pkg/container/modules/registry.go b/pkg/container/modules/registry.go index 4ab50a73a..0097ea251 100644 --- a/pkg/container/modules/registry.go +++ b/pkg/container/modules/registry.go @@ -117,6 +117,8 @@ type registryDeleterCleaners struct { Grants storeaccessdomain.Repository `optional:"true"` Everyone storeaccessdomain.EveryoneRepository `optional:"true"` Installs installationdomain.Repository `optional:"true"` + // Vault holds per-user header values, removed with their registry. + Vault vaultdomain.Repository `optional:"true"` } func (p registryDeleterCleaners) options(logger *slog.Logger) []appregistry.DeleterOption { @@ -127,6 +129,11 @@ func (p registryDeleterCleaners) options(logger *slog.Logger) []appregistry.Dele if p.Everyone != nil { opts = append(opts, appregistry.WithAfterDeleteCleaner(appstore.NewEveryoneRegistryCleaner(p.Everyone))) } + if p.Vault != nil { + if cleaner := appregistry.NewUserHeaderValuesCleaner(p.Vault, logger); cleaner != nil { + opts = append(opts, appregistry.WithAfterDeleteCleaner(cleaner)) + } + } if denier, ok := p.Installs.(installationdomain.PendingDenier); ok { opts = append(opts, appregistry.WithDependentCleaner(appstore.NewDeletedServerRequests(denier, logger))) } diff --git a/pkg/container/modules/server_admin.go b/pkg/container/modules/server_admin.go index 298dc0592..3408abe68 100644 --- a/pkg/container/modules/server_admin.go +++ b/pkg/container/modules/server_admin.go @@ -92,8 +92,10 @@ type adminRouterParams struct { ListRegistryTools *registryhttp.ListRegistryToolsHandler // RegistrySharedAccount is absent on planes without the connect service. RegistrySharedAccount *registryhttp.SharedAccountHandler `optional:"true"` - SecretStores *secretstorehttp.ListHandler `optional:"true"` - SecretStoreTest *secretstorehttp.TestHandler `optional:"true"` + // RegistryUserHeaders is absent on planes without the connect service. + RegistryUserHeaders *registryhttp.UserHeadersHandler `optional:"true"` + SecretStores *secretstorehttp.ListHandler `optional:"true"` + SecretStoreTest *secretstorehttp.TestHandler `optional:"true"` CreatePolicy *policyhttp.CreatePolicyHandler GetPolicy *policyhttp.GetPolicyHandler @@ -198,6 +200,7 @@ func ServerAdmin(c *container.Container) error { AgentCard: p.AgentCard, ListRegistryTools: p.ListRegistryTools, RegistrySharedAccount: p.RegistrySharedAccount, + RegistryUserHeaders: p.RegistryUserHeaders, SecretStores: p.SecretStores, SecretStoreTest: p.SecretStoreTest, CreatePolicy: p.CreatePolicy, diff --git a/pkg/domain/registry/mcp_target.go b/pkg/domain/registry/mcp_target.go index 99721bce6..19d962c0b 100644 --- a/pkg/domain/registry/mcp_target.go +++ b/pkg/domain/registry/mcp_target.go @@ -183,6 +183,10 @@ type MCPTarget struct { // without re-reading the catalog. Empty for servers whose URL is fully // determined (the common case). See ResolveURL. URLVariables []MCPURLVariable `json:"url_variables,omitempty"` + // UserHeaders declares the upstream headers whose value is each caller's + // own, read from the vault per request (see MCPUserHeader). Headers stays + // the shared map: one admin-set value for every caller. + UserHeaders []MCPUserHeader `json:"user_headers,omitempty"` // InstanceConfig carries one instance's resolved plain URL-variable values when // the Store scoper exposes several instances of the same catalog code for a // principal (e.g. two Snowflake schemas). It is a request-scoped overlay set on @@ -393,6 +397,9 @@ func (t *MCPTarget) Validate() error { return fmt.Errorf("%w: header %q looks masked; send the full value or the masked value unchanged", ErrInvalidMCPTarget, name) } + if err := t.validateUserHeaders(); err != nil { + return err + } if t.Auth != nil { if err := t.Auth.Validate(); err != nil { return err diff --git a/pkg/domain/registry/mcp_user_headers.go b/pkg/domain/registry/mcp_user_headers.go new file mode 100644 index 000000000..689878796 --- /dev/null +++ b/pkg/domain/registry/mcp_user_headers.go @@ -0,0 +1,210 @@ +// Copyright 2026 NeuralTrust +// +// 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 registry + +import ( + "fmt" + "net/http" + "regexp" + "strings" + + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" +) + +// MCPUserHeader declares one upstream header whose value belongs to each +// caller rather than to the registry. The admin declares the header; every +// person enrolls their own value once, through the connect link, and the +// gateway sends the calling person's value on each request to the upstream. +// Values live in the vault under the registry instance and the caller's +// principal (UserHeaderVaultProvider), never on the registry row. +type MCPUserHeader struct { + // Name is the HTTP header sent upstream, e.g. X-API-Key. + Name string `json:"name"` + // Description is the help shown when a person enters their value. + Description string `json:"description,omitempty"` + // Required makes a call fail with a connect link until the caller has a + // value. An optional header is simply left out when the caller has none. + Required bool `json:"required,omitempty"` + // Secret hides the value once entered: the connect page shows it masked + // and it is never echoed back. A non-secret value (an account id, a + // tenant) is shown back to its owner so it can be checked and edited. + // Both are stored encrypted in the vault. + Secret bool `json:"secret,omitempty"` + // Scheme is written before the value with one space, e.g. "Bearer" sends + // "Bearer ". Empty sends the value as entered. + Scheme string `json:"scheme,omitempty"` +} + +// MaxUserHeaderValueLen bounds one per-user header value. An API key or a +// token fits comfortably; anything longer is not a credential a person typed. +const MaxUserHeaderValueLen = 4096 + +// maxUserHeaders bounds how many per-user headers one registry declares. +const maxUserHeaders = 16 + +// userHeaderVaultPrefix namespaces per-user header values in the vault, apart +// from forwarded OAuth credentials and secret URL variables. +const userHeaderVaultPrefix = "uhdr:" + +// httpToken is an RFC 9110 token: what a header name and an auth scheme are. +var httpToken = regexp.MustCompile("^[!#$%&'*+.^_`|~0-9A-Za-z-]+$") + +// reservedUpstreamHeaders are names a per-user value may never set: the +// transport owns them, the MCP protocol owns them, or a hop strips them. +var reservedUpstreamHeaders = []string{ + "Host", "Content-Length", "Content-Type", "Content-Encoding", "Transfer-Encoding", + "Connection", "Keep-Alive", "Proxy-Authenticate", "Proxy-Authorization", + "Proxy-Connection", "TE", "Trailer", "Upgrade", "Cookie", "Accept", + "Mcp-Session-Id", "Mcp-Protocol-Version", "Last-Event-ID", +} + +// reservedUpstreamHeaderPrefix is the gateway's own header namespace. +const reservedUpstreamHeaderPrefix = "x-neuraltrust-" + +// UserHeaderVaultProvider is the vault "provider" key a person's value for one +// per-user header of one registry instance is stored under. It is keyed by the +// registry, not by the catalog code, so two instances of the same upstream +// (PRE and PRO) hold separate values while one instance bound to several +// applications reads the same value. The header name is canonicalised so the +// writer and the reader agree whatever case the admin typed. +func UserHeaderVaultProvider(registryID ids.RegistryID, header string) string { + return userHeaderVaultPrefix + registryID.String() + ":" + http.CanonicalHeaderKey(strings.TrimSpace(header)) +} + +// UserHeaderVaultPrefix is the vault provider prefix every per-user header of +// one registry shares, for listing or resetting all of them at once. +func UserHeaderVaultPrefix(registryID ids.RegistryID) string { + return userHeaderVaultPrefix + registryID.String() + ":" +} + +// HasUserHeaders reports whether any upstream header of this target is +// resolved per caller. +func (t *MCPTarget) HasUserHeaders() bool { + return t != nil && len(t.UserHeaders) > 0 +} + +// UserHeader returns the declared per-user header with this name, matched +// case-insensitively as HTTP header names are. +func (t *MCPTarget) UserHeader(name string) (MCPUserHeader, bool) { + if t == nil { + return MCPUserHeader{}, false + } + for _, h := range t.UserHeaders { + if strings.EqualFold(strings.TrimSpace(h.Name), strings.TrimSpace(name)) { + return h, true + } + } + return MCPUserHeader{}, false +} + +// FormatValue is the header value sent upstream for a person's stored value. +func (h MCPUserHeader) FormatValue(value string) string { + if scheme := strings.TrimSpace(h.Scheme); scheme != "" { + return scheme + " " + value + } + return value +} + +// ValidateUserHeaderValue checks a value a person enters for a per-user +// header. It never echoes the value: the error names the header only. +func ValidateUserHeaderValue(h MCPUserHeader, value string) error { + if strings.TrimSpace(value) == "" { + return fmt.Errorf("%w: header %q needs a value", ErrInvalidMCPTarget, h.Name) + } + if len(value) > MaxUserHeaderValueLen { + return fmt.Errorf("%w: header %q value is too long (max %d characters)", ErrInvalidMCPTarget, h.Name, MaxUserHeaderValueLen) + } + for _, r := range value { + // Visible ASCII and space/tab only: CR, LF and NUL would split the + // request, and anything else is not a value an HTTP header carries + // reliably. + if r == '\t' || (r >= 0x20 && r < 0x7f) { + continue + } + return fmt.Errorf("%w: header %q value has characters an HTTP header cannot carry", ErrInvalidMCPTarget, h.Name) + } + return nil +} + +// validateUserHeaders checks the per-user header declarations against each +// other, against the shared headers and against whatever the auth mode sends. +func (t *MCPTarget) validateUserHeaders() error { + if len(t.UserHeaders) == 0 { + return nil + } + if len(t.UserHeaders) > maxUserHeaders { + return fmt.Errorf("%w: at most %d per-user headers", ErrInvalidMCPTarget, maxUserHeaders) + } + authHeader := t.authSetsHeader() + seen := make(map[string]struct{}, len(t.UserHeaders)) + for _, h := range t.UserHeaders { + name := strings.TrimSpace(h.Name) + if name == "" || !httpToken.MatchString(name) { + return fmt.Errorf("%w: per-user header name %q is not a valid HTTP header name", ErrInvalidMCPTarget, h.Name) + } + if IsReservedUpstreamHeader(name) { + return fmt.Errorf("%w: header %q is reserved and cannot be set per user", ErrInvalidMCPTarget, name) + } + key := strings.ToLower(name) + if _, dup := seen[key]; dup { + return fmt.Errorf("%w: per-user header %q is declared twice", ErrInvalidMCPTarget, name) + } + seen[key] = struct{}{} + if _, shared := storedHeader(t.Headers, name); shared { + return fmt.Errorf("%w: header %q is both shared and per-user; pick one", ErrInvalidMCPTarget, name) + } + if authHeader != "" && strings.EqualFold(authHeader, name) { + return fmt.Errorf("%w: header %q is already set by auth mode %q", ErrInvalidMCPTarget, name, t.Auth.Mode) + } + if scheme := strings.TrimSpace(h.Scheme); scheme != "" && !httpToken.MatchString(scheme) { + return fmt.Errorf("%w: per-user header %q scheme %q is not a valid token", ErrInvalidMCPTarget, name, h.Scheme) + } + if len(h.Description) > 512 { + return fmt.Errorf("%w: per-user header %q description is too long", ErrInvalidMCPTarget, name) + } + } + return nil +} + +// authSetsHeader names the header the auth mode writes on every upstream +// call, or "" when it writes none. +func (t *MCPTarget) authSetsHeader() string { + if t.Auth == nil { + return "" + } + switch t.Auth.Mode { + case MCPAuthModeStatic: + return strings.TrimSpace(t.Auth.Header) + case MCPAuthModePassthrough, MCPAuthModeExchange, MCPAuthModeForwarded, MCPAuthModeClientCredentials: + return "Authorization" + default: + return "" + } +} + +// IsReservedUpstreamHeader reports whether name is a header the gateway, the +// transport or the MCP protocol owns, so no per-user value may set it. +func IsReservedUpstreamHeader(name string) bool { + name = strings.TrimSpace(name) + if strings.HasPrefix(strings.ToLower(name), reservedUpstreamHeaderPrefix) { + return true + } + for _, r := range reservedUpstreamHeaders { + if strings.EqualFold(r, name) { + return true + } + } + return false +} diff --git a/pkg/domain/registry/mcp_user_headers_test.go b/pkg/domain/registry/mcp_user_headers_test.go new file mode 100644 index 000000000..f3998822b --- /dev/null +++ b/pkg/domain/registry/mcp_user_headers_test.go @@ -0,0 +1,153 @@ +// Copyright 2026 NeuralTrust +// +// 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 registry + +import ( + "errors" + "strings" + "testing" + + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" +) + +func TestMCPTarget_UserHeadersValidate(t *testing.T) { + t.Parallel() + cases := []struct { + name string + mutate func(*MCPTarget) + wantErr string + }{ + {name: "one api key header with no auth", mutate: func(tg *MCPTarget) { + tg.Auth = &MCPAuth{Mode: MCPAuthModeNone} + tg.UserHeaders = []MCPUserHeader{{Name: "X-API-Key", Required: true, Secret: true}} + }}, + {name: "combined with shared header and static auth on another name", mutate: func(tg *MCPTarget) { + tg.Headers = map[string]string{"X-Tenant": "acme"} + tg.UserHeaders = []MCPUserHeader{{Name: "X-API-Key", Secret: true}, {Name: "X-Account", Scheme: "Id"}} + }}, + {name: "per-user Authorization with no auth mode", mutate: func(tg *MCPTarget) { + tg.Auth = &MCPAuth{Mode: MCPAuthModeNone} + tg.UserHeaders = []MCPUserHeader{{Name: "Authorization", Scheme: "Bearer", Secret: true}} + }}, + {name: "per-user Authorization when static auth sets it", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "authorization"}} + }, wantErr: "already set by auth mode"}, + {name: "per-user Authorization when forwarded sets it", mutate: func(tg *MCPTarget) { + tg.Auth = &MCPAuth{Mode: MCPAuthModeForwarded, Provider: "p", Registration: RegistrationAuto} + tg.UserHeaders = []MCPUserHeader{{Name: "Authorization"}} + }, wantErr: "already set by auth mode"}, + {name: "static auth on a custom header collides", mutate: func(tg *MCPTarget) { + tg.Auth = &MCPAuth{Mode: MCPAuthModeStatic, Header: "X-API-Key", Value: "k"} + tg.UserHeaders = []MCPUserHeader{{Name: "x-api-key"}} + }, wantErr: "already set by auth mode"}, + {name: "shared and per-user at once", mutate: func(tg *MCPTarget) { + tg.Headers = map[string]string{"x-api-key": "shared"} + tg.UserHeaders = []MCPUserHeader{{Name: "X-API-Key"}} + }, wantErr: "both shared and per-user"}, + {name: "duplicate", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "X-Key"}, {Name: "x-key"}} + }, wantErr: "declared twice"}, + {name: "reserved host", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "Host"}} + }, wantErr: "reserved"}, + {name: "reserved session id", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "mcp-session-id"}} + }, wantErr: "reserved"}, + {name: "reserved gateway namespace", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "X-NeuralTrust-End-User"}} + }, wantErr: "reserved"}, + {name: "invalid name", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "X Key"}} + }, wantErr: "not a valid HTTP header name"}, + {name: "empty name", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: " "}} + }, wantErr: "not a valid HTTP header name"}, + {name: "invalid scheme", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "X-Key", Scheme: "Bear er"}} + }, wantErr: "not a valid token"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + tg := validMCPTarget() + tc.mutate(tg) + err := tg.Validate() + if tc.wantErr == "" { + if err != nil { + t.Fatalf("Validate() = %v, want nil", err) + } + return + } + if err == nil || !errors.Is(err, ErrInvalidMCPTarget) || !strings.Contains(err.Error(), tc.wantErr) { + t.Fatalf("Validate() = %v, want ErrInvalidMCPTarget containing %q", err, tc.wantErr) + } + }) + } +} + +func TestValidateUserHeaderValue(t *testing.T) { + t.Parallel() + h := MCPUserHeader{Name: "X-API-Key"} + cases := []struct { + name string + value string + ok bool + }{ + {"plain value", "abc.123_xyz", true}, + {"with space", "abc def", true}, + {"empty", " ", false}, + {"crlf injection", "abc\r\nX-Evil: 1", false}, + {"lf", "abc\nd", false}, + {"nul", "abc\x00", false}, + {"non ascii", "clé", false}, + {"too long", strings.Repeat("a", MaxUserHeaderValueLen+1), false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + err := ValidateUserHeaderValue(h, tc.value) + if tc.ok != (err == nil) { + t.Fatalf("ValidateUserHeaderValue() = %v, want ok=%v", err, tc.ok) + } + if err != nil && strings.Contains(err.Error(), "abc") { + t.Fatalf("error echoes the value: %v", err) + } + }) + } +} + +func TestUserHeaderVaultProvider(t *testing.T) { + t.Parallel() + pre, pro := ids.New[ids.RegistryKind](), ids.New[ids.RegistryKind]() + if UserHeaderVaultProvider(pre, "x-api-key") != UserHeaderVaultProvider(pre, " X-API-KEY ") { + t.Fatal("header case must not change the vault key") + } + if UserHeaderVaultProvider(pre, "X-API-Key") == UserHeaderVaultProvider(pro, "X-API-Key") { + t.Fatal("two instances must not share a value") + } + if !strings.HasPrefix(UserHeaderVaultProvider(pre, "X-API-Key"), UserHeaderVaultPrefix(pre)) { + t.Fatal("per-header key must sit under the registry prefix") + } +} + +func TestMCPUserHeader_FormatValue(t *testing.T) { + t.Parallel() + if got := (MCPUserHeader{Scheme: "Bearer"}).FormatValue("tok"); got != "Bearer tok" { + t.Fatalf("got %q", got) + } + if got := (MCPUserHeader{}).FormatValue("tok"); got != "tok" { + t.Fatalf("got %q", got) + } +} diff --git a/pkg/domain/vault/provider_prefix.go b/pkg/domain/vault/provider_prefix.go new file mode 100644 index 000000000..959b6648e --- /dev/null +++ b/pkg/domain/vault/provider_prefix.go @@ -0,0 +1,52 @@ +// Copyright 2026 NeuralTrust +// +// 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 vault + +import ( + "context" + "time" + + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" +) + +// CredentialSummary is a stored credential without its secrets: who holds it, +// under which provider key, and when it was written or refused. +type CredentialSummary struct { + PrincipalSub string + Provider string + // ExpiresAt is zero for a credential that does not expire. For a value + // with no expiry of its own, a past ExpiresAt is the refusal mark. + ExpiresAt time.Time + CreatedAt time.Time + UpdatedAt time.Time +} + +// ProviderPrefixStore lists and removes credentials of every principal whose +// provider key starts with a prefix: the values every person holds for one +// registry instance, for an admin roster or reset. +type ProviderPrefixStore interface { + ListByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) ([]CredentialSummary, error) + // DeleteByProviderPrefix removes them and reports how many it removed. + DeleteByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) (int, error) +} + +// SharedStoreUpserter is a store that can write a credential to the store +// every plane reads. The control-plane vault writes Postgres and reads the +// shared Redis behind it; the MCP data plane reads only that Redis. A value a +// person may write or remove from either plane is kept there alone, so no +// copy in Postgres outlives a change made on the data plane. +type SharedStoreUpserter interface { + UpsertShared(ctx context.Context, c *Credential) error +} diff --git a/pkg/infra/repository/vault/provider_prefix.go b/pkg/infra/repository/vault/provider_prefix.go new file mode 100644 index 000000000..99269b672 --- /dev/null +++ b/pkg/infra/repository/vault/provider_prefix.go @@ -0,0 +1,226 @@ +// Copyright 2026 NeuralTrust +// +// 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 vault + +import ( + "context" + "errors" + "fmt" + "sort" + "strings" + "time" + + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + domain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" + "github.com/NeuralTrust/TrustGate/pkg/infra/cache" + "github.com/NeuralTrust/TrustGate/pkg/infra/database" + "github.com/jackc/pgx/v5" +) + +var ( + _ domain.ProviderPrefixStore = (*Repository)(nil) + _ domain.ProviderPrefixStore = (*redisRepository)(nil) + _ domain.ProviderPrefixStore = (*fallbackRepository)(nil) + _ domain.SharedStoreUpserter = (*fallbackRepository)(nil) +) + +// errEmptyProviderPrefix refuses a prefix that would match every credential. +var errEmptyProviderPrefix = errors.New("vault repository: provider prefix is required") + +func (r *Repository) ListByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) ([]domain.CredentialSummary, error) { + if strings.TrimSpace(prefix) == "" { + return nil, errEmptyProviderPrefix + } + const query = ` + SELECT principal_sub, provider, expires_at, created_at, updated_at + FROM vault_credentials + WHERE gateway_id = $1 AND provider LIKE $2 ESCAPE '\' + ORDER BY principal_sub, provider` + rows, err := r.conn.Pool.Query(ctx, query, gatewayID, likePrefix(prefix)) + if err != nil { + return nil, fmt.Errorf("vault repository: list by provider prefix: %w", err) + } + defer rows.Close() + var out []domain.CredentialSummary + for rows.Next() { + var s domain.CredentialSummary + var expires *time.Time + if err := rows.Scan(&s.PrincipalSub, &s.Provider, &expires, &s.CreatedAt, &s.UpdatedAt); err != nil { + return nil, fmt.Errorf("vault repository: scan summary: %w", err) + } + if expires != nil { + s.ExpiresAt = *expires + } + out = append(out, s) + } + return out, rows.Err() +} + +func (r *Repository) DeleteByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) (int, error) { + if strings.TrimSpace(prefix) == "" { + return 0, errEmptyProviderPrefix + } + const query = `DELETE FROM vault_credentials WHERE gateway_id = $1 AND provider LIKE $2 ESCAPE '\'` + deleted := 0 + err := database.WithTx(ctx, r.conn, func(tx pgx.Tx) error { + tag, err := tx.Exec(ctx, query, gatewayID, likePrefix(prefix)) + if err != nil { + return err + } + deleted = int(tag.RowsAffected()) + return nil + }) + if err != nil { + return 0, fmt.Errorf("vault repository: delete by provider prefix: %w", err) + } + return deleted, nil +} + +// scanProviderPrefix walks every credential of the gateway and hands the ones +// under prefix to visit. Keys cannot be split back into principal and provider +// (either may contain ':'), so each record is read; this is an admin path. +func (r *redisRepository) scanProviderPrefix( + ctx context.Context, + gatewayID ids.GatewayID, + prefix string, + visit func(key string, stored *storedCredential) error, +) error { + if r == nil || r.rc == nil { + return errors.New("vault repository: redis unavailable") + } + if strings.TrimSpace(prefix) == "" { + return errEmptyProviderPrefix + } + match := fmt.Sprintf("%s:%s:*", redisKeyPrefix, escapeGlob(gatewayID.String())) + return cache.ScanKeys(ctx, r.rc, match, redisScanBatchSize, func(ctx context.Context, keys []string) error { + for _, key := range keys { + stored, err := r.load(ctx, key) + if err != nil { + if errors.Is(err, domain.ErrNotFound) { + continue + } + return err + } + if stored.GatewayID != gatewayID || !strings.HasPrefix(stored.Provider, prefix) { + continue + } + if err := visit(key, stored); err != nil { + return err + } + } + return nil + }) +} + +func (r *redisRepository) ListByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) ([]domain.CredentialSummary, error) { + var out []domain.CredentialSummary + err := r.scanProviderPrefix(ctx, gatewayID, prefix, func(_ string, stored *storedCredential) error { + s := domain.CredentialSummary{ + PrincipalSub: stored.PrincipalSub, + Provider: stored.Provider, + CreatedAt: stored.CreatedAt, + UpdatedAt: stored.UpdatedAt, + } + if stored.ExpiresAt != nil { + s.ExpiresAt = *stored.ExpiresAt + } + out = append(out, s) + return nil + }) + if err != nil { + return nil, fmt.Errorf("vault repository: list by provider prefix: %w", err) + } + sortSummaries(out) + return out, nil +} + +func (r *redisRepository) DeleteByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) (int, error) { + var keys []string + err := r.scanProviderPrefix(ctx, gatewayID, prefix, func(key string, _ *storedCredential) error { + keys = append(keys, key) + return nil + }) + if err != nil { + return 0, fmt.Errorf("vault repository: delete by provider prefix: %w", err) + } + if len(keys) == 0 { + return 0, nil + } + n, err := r.rc.Del(ctx, keys...).Result() + if err != nil { + return 0, fmt.Errorf("vault repository: delete by provider prefix: %w", err) + } + return int(n), nil +} + +func (r *fallbackRepository) ListByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) ([]domain.CredentialSummary, error) { + merged := map[string]domain.CredentialSummary{} + for _, store := range []domain.Repository{r.primary, r.fallback} { + lister, ok := store.(domain.ProviderPrefixStore) + if !ok { + continue + } + list, err := lister.ListByProviderPrefix(ctx, gatewayID, prefix) + if err != nil { + return nil, err + } + for _, s := range list { + key := s.PrincipalSub + "\x00" + s.Provider + // The same value written to both stores is one value: keep the + // newer write, which is what a reader sees. + if prev, ok := merged[key]; ok && !s.UpdatedAt.After(prev.UpdatedAt) { + continue + } + merged[key] = s + } + } + out := make([]domain.CredentialSummary, 0, len(merged)) + for _, s := range merged { + out = append(out, s) + } + sortSummaries(out) + return out, nil +} + +func (r *fallbackRepository) DeleteByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) (int, error) { + total := 0 + for _, store := range []domain.Repository{r.primary, r.fallback} { + deleter, ok := store.(domain.ProviderPrefixStore) + if !ok { + continue + } + n, err := deleter.DeleteByProviderPrefix(ctx, gatewayID, prefix) + if err != nil { + return total, err + } + total = max(total, n) + } + return total, nil +} + +// UpsertShared writes to the shared store behind the primary, the one the +// data plane reads; the control plane finds it there through the fallback. +func (r *fallbackRepository) UpsertShared(ctx context.Context, c *domain.Credential) error { + return r.fallback.Upsert(ctx, c) +} + +func sortSummaries(out []domain.CredentialSummary) { + sort.Slice(out, func(i, j int) bool { + if out[i].PrincipalSub != out[j].PrincipalSub { + return out[i].PrincipalSub < out[j].PrincipalSub + } + return out[i].Provider < out[j].Provider + }) +} diff --git a/pkg/infra/repository/vault/provider_prefix_test.go b/pkg/infra/repository/vault/provider_prefix_test.go new file mode 100644 index 000000000..bfc51f340 --- /dev/null +++ b/pkg/infra/repository/vault/provider_prefix_test.go @@ -0,0 +1,101 @@ +// Copyright 2026 NeuralTrust +// +// 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 vault_test + +import ( + "context" + "testing" + + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + domain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" + vaultrepo "github.com/NeuralTrust/TrustGate/pkg/infra/repository/vault" +) + +func TestRedisRepository_ProviderPrefixListsAndDeletesEveryPrincipal(t *testing.T) { + repo, _, _ := newRedisVaultRepo(t) + store, ok := repo.(domain.ProviderPrefixStore) + if !ok { + t.Fatal("redis vault does not implement ProviderPrefixStore") + } + ctx := context.Background() + gw, other := ids.New[ids.GatewayKind](), ids.New[ids.GatewayKind]() + const prefix = "uhdr:reg-1:" + for _, c := range []*domain.Credential{ + newTestCredential(t, gw, "ana", prefix+"X-Api-Key", "a", ""), + newTestCredential(t, gw, "app:c1:bruno", prefix+"X-Api-Key", "b", ""), + newTestCredential(t, gw, "ana", "uhdr:reg-10:X-Api-Key", "c", ""), + newTestCredential(t, gw, "ana", "com.linear/mcp|abcd", "d", "r"), + newTestCredential(t, other, "ana", prefix+"X-Api-Key", "e", ""), + } { + if err := repo.Upsert(ctx, c); err != nil { + t.Fatal(err) + } + } + list, err := store.ListByProviderPrefix(ctx, gw, prefix) + if err != nil { + t.Fatal(err) + } + if len(list) != 2 || list[0].PrincipalSub != "ana" || list[1].PrincipalSub != "app:c1:bruno" { + t.Fatalf("list = %+v, want ana and app:c1:bruno only", list) + } + n, err := store.DeleteByProviderPrefix(ctx, gw, prefix) + if err != nil || n != 2 { + t.Fatalf("deleted %d, err %v; want 2", n, err) + } + if _, err := repo.Find(ctx, gw, "ana", "uhdr:reg-10:X-Api-Key"); err != nil { + t.Fatalf("a sibling registry's value was deleted: %v", err) + } + if _, err := repo.Find(ctx, other, "ana", prefix+"X-Api-Key"); err != nil { + t.Fatalf("another gateway's value was deleted: %v", err) + } + if _, err := store.ListByProviderPrefix(ctx, gw, ""); err == nil { + t.Fatal("an empty prefix must be refused") + } +} + +func TestFallbackRepository_SharedWriteLandsWhereEveryPlaneReads(t *testing.T) { + primary, _, _ := newRedisVaultRepo(t) + secondary, _, _ := newRedisVaultRepo(t) + repo := vaultrepo.NewFallbackRepository(primary, secondary) + ctx := context.Background() + gw := ids.New[ids.GatewayKind]() + writer, ok := repo.(domain.SharedStoreUpserter) + if !ok { + t.Fatal("fallback vault does not implement SharedStoreUpserter") + } + if err := writer.UpsertShared(ctx, newTestCredential(t, gw, "ana", "uhdr:r:X-Api-Key", "v", "")); err != nil { + t.Fatal(err) + } + if _, err := secondary.Find(ctx, gw, "ana", "uhdr:r:X-Api-Key"); err != nil { + t.Fatalf("the shared store does not hold the value: %v", err) + } + if _, err := primary.Find(ctx, gw, "ana", "uhdr:r:X-Api-Key"); err == nil { + t.Fatal("no copy may stay in the primary, where a data-plane change never reaches") + } + if _, err := repo.Find(ctx, gw, "ana", "uhdr:r:X-Api-Key"); err != nil { + t.Fatalf("the control plane must still read it: %v", err) + } + lister := repo.(domain.ProviderPrefixStore) + list, err := lister.ListByProviderPrefix(ctx, gw, "uhdr:r:") + if err != nil || len(list) != 1 { + t.Fatalf("merged list = %+v err %v; want one entry", list, err) + } + if n, err := lister.DeleteByProviderPrefix(ctx, gw, "uhdr:r:"); err != nil || n != 1 { + t.Fatalf("deleted %d err %v", n, err) + } + if _, err := secondary.Find(ctx, gw, "ana", "uhdr:r:X-Api-Key"); err == nil { + t.Fatal("reset left a live copy on the data plane store") + } +} diff --git a/pkg/server/router/admin_router.go b/pkg/server/router/admin_router.go index 278b59ac5..ec123af43 100644 --- a/pkg/server/router/admin_router.go +++ b/pkg/server/router/admin_router.go @@ -88,6 +88,9 @@ type AdminRouterDeps struct { // RegistrySharedAccount serves the upstream account an MCP instance holds // on behalf of every caller. Absent on planes without the connect service. RegistrySharedAccount *registryhttp.SharedAccountHandler + // RegistryUserHeaders serves the per-user header values of an MCP + // instance: roster, reset, bulk import and per-person links. + RegistryUserHeaders *registryhttp.UserHeadersHandler // SecretStores serves the secret stores of a gateway; nil where the // plane has no connection store. SecretStores *secretstorehttp.ListHandler @@ -218,6 +221,12 @@ func (r *adminRouter) BuildRoutes(app *fiber.App) error { registries.Post("/:id/shared-account/connect-link", r.deps.RegistrySharedAccount.ConnectLink) registries.Delete("/:id/shared-account", r.deps.RegistrySharedAccount.Disconnect) } + if r.deps.RegistryUserHeaders != nil { + registries.Get("/:id/user-headers", r.deps.RegistryUserHeaders.List) + registries.Put("/:id/user-headers/values", r.deps.RegistryUserHeaders.Import) + registries.Delete("/:id/user-headers/values", r.deps.RegistryUserHeaders.Reset) + registries.Post("/:id/user-headers/links", r.deps.RegistryUserHeaders.Link) + } registries.Post("/:id/agent-card/refresh", r.deps.AgentCard.Refresh) registries.Post("/:id/agent-card/approve", r.deps.AgentCard.Approve) registries.Put("/:id", r.deps.UpdateRegistry.Handle) diff --git a/pkg/server/router/mcp_router.go b/pkg/server/router/mcp_router.go index d8e9ba62c..276f9001f 100644 --- a/pkg/server/router/mcp_router.go +++ b/pkg/server/router/mcp_router.go @@ -155,6 +155,8 @@ func (r *mcpRouter) BuildRoutes(app *fiber.App) error { app.Get(oauthhttp.ConnectStartPath, r.connectHandler.Confirm) app.Get(oauthhttp.ConnectCallbackPath, r.connectHandler.Callback) app.Post(oauthhttp.DisconnectPath, r.connectHandler.Disconnect) + app.Post(oauthhttp.UserHeadersSavePath, r.connectHandler.SaveUserHeaders) + app.Post(oauthhttp.UserHeadersRemovePath, r.connectHandler.RemoveUserHeaders) if r.endUserConnectionsHandler != nil { app.Post("/:slug/connections/links", r.endUserConnectionsHandler.Link) app.Get("/:slug/connections", r.endUserConnectionsHandler.List) diff --git a/tests/functional/a2a_common_test.go b/tests/functional/a2a_common_test.go index a9d793eef..d25e57c5e 100644 --- a/tests/functional/a2a_common_test.go +++ b/tests/functional/a2a_common_test.go @@ -123,6 +123,13 @@ func (a *fakeAgent) rpc(w http.ResponseWriter, r *http.Request) { http.Error(w, err.Error(), http.StatusBadRequest) return } + // The gateway probes the endpoint when the agent is registered, asking for + // a task that cannot exist. That is not a call a caller made, so it is + // answered as an agent would and not recorded. + if id, _ := req.Params["id"].(string); strings.HasPrefix(id, "trustgate-probe-") { + writeRPCError(w, req.ID, -32001, "Task not found") + return + } a.mu.Lock() a.calls = append(a.calls, agentCall{Method: req.Method, Header: r.Header.Clone(), Params: req.Params}) a.mu.Unlock() @@ -370,3 +377,10 @@ func a2aErrorData(body map[string]any) map[string]any { func a2aKey(key string) map[string]string { return map[string]string{"X-AG-API-Key": key} } + +func writeRPCError(w http.ResponseWriter, id json.RawMessage, code int, message string) { + w.Header().Set("Content-Type", "application/json") + _ = json.NewEncoder(w).Encode(map[string]any{ + "jsonrpc": "2.0", "id": id, "error": map[string]any{"code": code, "message": message}, + }) +} diff --git a/tests/functional/mcp_user_headers_test.go b/tests/functional/mcp_user_headers_test.go new file mode 100644 index 000000000..a9f2830b7 --- /dev/null +++ b/tests/functional/mcp_user_headers_test.go @@ -0,0 +1,345 @@ +// Copyright 2026 NeuralTrust +// +// 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. + +//go:build functional + +package functional_test + +import ( + "encoding/json" + "fmt" + "io" + "net/http" + "net/http/httptest" + "net/url" + "strings" + "sync" + "testing" + "time" + + sdk "github.com/modelcontextprotocol/go-sdk/mcp" + "github.com/stretchr/testify/require" +) + +// perUserKeyUpstream is an MCP server that authenticates each caller by their own +// X-API-Key, the way an upstream without OAuth does, and records the keys it +// was sent. +type perUserKeyUpstream struct { + server *httptest.Server + mu sync.Mutex + keys []string + revoke map[string]bool +} + +func startPerUserKeyUpstream(t *testing.T) *perUserKeyUpstream { + t.Helper() + mcp := sdk.NewServer(&sdk.Implementation{Name: "keyed-upstream", Version: "1.0"}, nil) + addTool(mcp, "echo") + handler := sdk.NewStreamableHTTPHandler(func(*http.Request) *sdk.Server { return mcp }, nil) + up := &perUserKeyUpstream{revoke: map[string]bool{}} + up.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + key := r.Header.Get("X-API-Key") + up.mu.Lock() + up.keys = append(up.keys, key) + refused := key == "" || up.revoke[key] + up.mu.Unlock() + if refused { + w.WriteHeader(http.StatusUnauthorized) + return + } + handler.ServeHTTP(w, r) + })) + t.Cleanup(up.server.Close) + return up +} + +func (u *perUserKeyUpstream) seen() []string { + u.mu.Lock() + defer u.mu.Unlock() + return append([]string(nil), u.keys...) +} + +func (u *perUserKeyUpstream) reset() { + u.mu.Lock() + defer u.mu.Unlock() + u.keys = nil +} + +func (u *perUserKeyUpstream) refuse(key string) { + u.mu.Lock() + defer u.mu.Unlock() + u.revoke[key] = true +} + +func endUserHeaders(key, endUser string) map[string]string { + return map[string]string{"X-AG-API-Key": key, "X-NeuralTrust-End-User": endUser} +} + +func importUserHeaders(t *testing.T, gatewayID, registryID string, values []map[string]any) { + t.Helper() + target := fmt.Sprintf("%s/v1/gateways/%s/registries/%s/user-headers/values", AdminURL, gatewayID, registryID) + status, body := sendRequest(t, http.MethodPut, target, nil, map[string]any{"values": values}) + require.Equal(t, http.StatusOK, status, "import failed: %v", body) + require.Equal(t, float64(len(values)), body["count"]) +} + +// requireConsentCause asserts the -32003 a person gets and returns the +// connect ticket it carries. +func requireConsentCause(t *testing.T, status int, body map[string]any, cause string) string { + t.Helper() + require.Equal(t, http.StatusOK, status) + rpcErr, ok := body["error"].(map[string]any) + require.True(t, ok, "expected a consent error, got %v", body) + require.Equal(t, float64(-32003), rpcErr["code"], "body=%v", body) + data, _ := rpcErr["data"].(map[string]any) + require.Equal(t, cause, data["cause"], "body=%v", body) + link, _ := data["connect_url"].(string) + require.NotEmpty(t, link, "a person is handed the link to enter their key: %v", body) + parsed, err := url.Parse(link) + require.NoError(t, err) + ticket := parsed.Query().Get("ticket") + require.NotEmpty(t, ticket, "the link carries a ticket: %s", link) + return ticket +} + +// enterKeyOnConnectPage does what a person's browser does: open the link, +// then post the form the page shows. +func enterKeyOnConnectPage(t *testing.T, ticket, registryID string, form url.Values) string { + t.Helper() + page := doWith(t, noRedirectClient(), http.MethodGet, MCPURL+"/+/connect?ticket="+url.QueryEscape(ticket), "connect page", nil) + html, err := io.ReadAll(page.Body) + _ = page.Body.Close() + require.NoError(t, err) + require.Equal(t, http.StatusOK, page.StatusCode) + action := "/oauth/user-headers/" + registryID + "?ticket=" + ticket + require.Contains(t, string(html), action, "the page offers the form for this server") + + req, err := http.NewRequest(http.MethodPost, MCPURL+action, strings.NewReader(form.Encode())) + require.NoError(t, err) + req.Header.Set("Content-Type", "application/x-www-form-urlencoded") + req.Header.Set("Origin", MCPURL) + resp, err := noRedirectClient().Do(req) + require.NoError(t, err) + saved, err := io.ReadAll(resp.Body) + _ = resp.Body.Close() + require.NoError(t, err) + require.Equal(t, http.StatusOK, resp.StatusCode, "save failed: %s", saved) + return string(saved) +} + +// Ana and Bruno reach the same header-authenticated upstream through one +// application; each call carries the caller's own key, never the other's, and +// the key never leaves the gateway. +func TestMCPUserHeaders_EachPersonSendsTheirOwnKey(t *testing.T) { + up := startPerUserKeyUpstream(t) + gatewayID := CreateGateway(t, map[string]any{"slug": uniqueName("mcp-gw")}) + registryID := CreateRegistry(t, gatewayID, map[string]any{ + "name": uniqueName("keyed"), "type": "mcp", "weight": 1, + "mcp_target": map[string]any{ + "url": up.server.URL, + "auth": map[string]any{"mode": "none"}, + "user_headers": []map[string]any{ + {"name": "X-API-Key", "required": true, "secret": true, "description": "Your personal API key"}, + }, + }, + }) + consumerID, key := createMCPConsumer(t, gatewayID, []string{registryID}, nil, "") + echo := map[string]any{"name": exposedToolName(registryID, "echo"), "arguments": map[string]any{"message": "hola"}} + ana, bruno := "app:"+consumerID+":ana", "app:"+consumerID+":bruno" + + t.Run("the application itself has no key of its own", func(t *testing.T) { + status, body := mcpRPC(t, gatewayID, consumerID, apiKeyHeaders(key), "tools/call", echo) + requireNotConnected(t, status, body, false) + require.Empty(t, up.seen(), "a refused call must not reach the upstream") + }) + + t.Run("a person without a key enters it through the link they are handed", func(t *testing.T) { + status, body := mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, "ana"), "tools/call", echo) + ticket := requireConsentCause(t, status, body, "user_header_missing") + require.Empty(t, up.seen()) + + page := enterKeyOnConnectPage(t, ticket, registryID, url.Values{"X-API-Key": {"ana-key"}}) + require.NotContains(t, page, "ana-key", "the saved key is never written back into the page") + require.Contains(t, page, "Saved") + }) + + // Bruno's key is loaded by an admin, the other way to enroll. + importUserHeaders(t, gatewayID, registryID, []map[string]any{ + {"principal_sub": bruno, "header": "x-api-key", "value": "bruno-key"}, + }) + + t.Run("each person's call carries their own key", func(t *testing.T) { + for person, want := range map[string]string{"ana": "ana-key", "bruno": "bruno-key"} { + up.reset() + status, body := mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, person), "tools/call", echo) + requireRPCSucceeded(t, status, body) + seen := up.seen() + require.NotEmpty(t, seen, "%s must reach the upstream", person) + for _, got := range seen { + require.Equal(t, want, got, "%s's call carried another key", person) + } + } + }) + + t.Run("a key the client sends never reaches the upstream", func(t *testing.T) { + up.reset() + headers := endUserHeaders(key, "ana") + headers["X-API-Key"] = "forged-key" + status, body := mcpRPC(t, gatewayID, consumerID, headers, "tools/call", echo) + requireRPCSucceeded(t, status, body) + for _, got := range up.seen() { + require.Equal(t, "ana-key", got) + } + }) + + t.Run("an admin sees who holds a key, never the key", func(t *testing.T) { + target := fmt.Sprintf("%s/v1/gateways/%s/registries/%s/user-headers", AdminURL, gatewayID, registryID) + status, body := sendRequest(t, http.MethodGet, target, nil, nil) + require.Equal(t, http.StatusOK, status, "body=%v", body) + raw := fmt.Sprint(body) + require.Contains(t, raw, ana) + require.Contains(t, raw, bruno) + require.NotContains(t, raw, "ana-key") + require.NotContains(t, raw, "bruno-key") + }) + + t.Run("a key the upstream refuses must be entered again", func(t *testing.T) { + up.refuse("bruno-key") + status, body := mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, "bruno"), "tools/call", echo) + _ = requireConsentCause(t, status, body, "user_header_rejected") + up.reset() + status, body = mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, "bruno"), "tools/call", echo) + _ = requireConsentCause(t, status, body, "user_header_rejected") + require.Empty(t, up.seen(), "a refused key is not sent again") + + status, body = mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, "ana"), "tools/call", echo) + requireRPCSucceeded(t, status, body) + }) + + t.Run("an admin reset asks everyone for their key again", func(t *testing.T) { + target := fmt.Sprintf("%s/v1/gateways/%s/registries/%s/user-headers/values", AdminURL, gatewayID, registryID) + status, body := sendRequest(t, http.MethodDelete, target, nil, nil) + require.Equal(t, http.StatusOK, status, "body=%v", body) + status, body = mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, "ana"), "tools/call", echo) + _ = requireConsentCause(t, status, body, "user_header_missing") + }) +} + +// mcpRPCAt is mcpRPC against a given MCP plane. +func mcpRPCAt(t *testing.T, base, gatewayID, consumerID string, headers map[string]string, method string, params any) (int, map[string]any) { + t.Helper() + raw, err := json.Marshal(map[string]any{"jsonrpc": "2.0", "id": 1, "method": method, "params": params}) + require.NoError(t, err) + req, err := http.NewRequest(http.MethodPost, base+"/"+ConsumerSlug(t, consumerID)+"/mcp", strings.NewReader(string(raw))) + require.NoError(t, err) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Accept", "application/json") + for k, v := range headers { + req.Header.Set(k, v) + } + host, ok := gatewayHosts.Load(gatewayID) + require.True(t, ok, "gateway host missing for %s", gatewayID) + req.Host = host.(string) + return doJSONRequest(t, req) +} + +// On the MCP plane as production runs it — no database, reading the vault +// from the shared Redis only — a key an admin loads on the control plane is +// the key the plane sends, and an admin reset reaches it too. +func TestDBLessMCP_UserHeaderLoadedByAnAdminReachesTheDataPlane(t *testing.T) { + defer Track(t, "DBLessDataPlane")() + up := startPerUserKeyUpstream(t) + gatewayID := CreateGateway(t, map[string]any{"slug": uniqueName("dbless-keyed")}) + registryID := CreateRegistry(t, gatewayID, map[string]any{ + "name": uniqueName("keyed"), "type": "mcp", "weight": 1, + "mcp_target": map[string]any{ + "url": up.server.URL, + "auth": map[string]any{"mode": "none"}, + "user_headers": []map[string]any{{"name": "X-API-Key", "required": true, "secret": true}}, + }, + }) + consumerID, key := createMCPConsumer(t, gatewayID, []string{registryID}, nil, "") + importUserHeaders(t, gatewayID, registryID, []map[string]any{ + {"principal_sub": "app:" + consumerID + ":ana", "header": "X-API-Key", "value": "ana-dbless-key"}, + }) + echo := map[string]any{"name": exposedToolName(registryID, "echo"), "arguments": map[string]any{"message": "hola"}} + + base, logs := startDBLessMCPPlane(t, GlobalConfig.Server.MCPPort+106, uniqueName("dbless-keyed")) + require.Eventually(t, func() bool { + up.reset() + status, body := mcpRPCAt(t, base, gatewayID, consumerID, endUserHeaders(key, "ana"), "tools/call", echo) + if status != http.StatusOK || body["error"] != nil { + return false + } + for _, got := range up.seen() { + if got != "ana-dbless-key" { + return false + } + } + return len(up.seen()) > 0 + }, 30*time.Second, 300*time.Millisecond, "the db-less plane never sent the imported key; logs:\n%s", logs.String()) + require.NotContains(t, logs.String(), "ana-dbless-key", "the key must never reach the plane's logs") + + target := fmt.Sprintf("%s/v1/gateways/%s/registries/%s/user-headers/values", AdminURL, gatewayID, registryID) + status, body := sendRequest(t, http.MethodDelete, target, nil, nil) + require.Equal(t, http.StatusOK, status, "body=%v", body) + status, body = mcpRPCAt(t, base, gatewayID, consumerID, endUserHeaders(key, "ana"), "tools/call", echo) + _ = requireConsentCause(t, status, body, "user_header_missing") +} + +// A person who signs in with the customer's IdP (OAuth inbound) holds their +// own key too: an admin hands them the link for a custom server through the +// virtual MCP that binds it, they enter the key on the page, and their calls +// carry it. +func TestMCPUserHeaders_OAuthCallerEnrollsThroughAnAdminLink(t *testing.T) { + up := startPerUserKeyUpstream(t) + gatewayID := CreateGateway(t, map[string]any{"slug": uniqueName("mcp-gw")}) + registryID := CreateRegistry(t, gatewayID, map[string]any{ + "name": uniqueName("keyed"), "type": "mcp", "weight": 1, + "mcp_target": map[string]any{ + "url": up.server.URL, + "auth": map[string]any{"mode": "none"}, + "user_headers": []map[string]any{{"name": "X-API-Key", "required": true, "secret": true}}, + }, + }) + idp := newOAuthIDPStub(t) + consumerID, audience := createOAuthMCPConsumer(t, gatewayID, []string{registryID}, idp) + subject := uniqueName("carla") + carla := bearerHeaders(idp.mint(t, audience, map[string]any{"sub": subject})) + echo := map[string]any{"name": exposedToolName(registryID, "echo"), "arguments": map[string]any{"message": "hola"}} + + status, body := mcpRPC(t, gatewayID, consumerID, carla, "tools/call", echo) + _ = requireConsentCause(t, status, body, "user_header_missing") + + links := fmt.Sprintf("%s/v1/gateways/%s/registries/%s/user-headers/links", AdminURL, gatewayID, registryID) + status, body = sendRequest(t, http.MethodPost, links, nil, map[string]any{"principal_sub": subject}) + require.Equal(t, http.StatusUnprocessableEntity, status, "a custom server's link must name its virtual MCP: %v", body) + + consumerPath := "/" + ConsumerSlug(t, consumerID) + "/mcp" + status, body = sendRequest(t, http.MethodPost, links, nil, map[string]any{"principal_sub": subject, "consumer_path": consumerPath}) + require.Equal(t, http.StatusOK, status, "body=%v", body) + ticket, _ := body["ticket"].(string) + require.NotEmpty(t, ticket, "body=%v", body) + + enterKeyOnConnectPage(t, ticket, registryID, url.Values{"X-API-Key": {"carla-key"}}) + + up.reset() + status, body = mcpRPC(t, gatewayID, consumerID, carla, "tools/call", echo) + requireRPCSucceeded(t, status, body) + seen := up.seen() + require.NotEmpty(t, seen) + for _, got := range seen { + require.Equal(t, "carla-key", got) + } +}