[pve-devel] GET /access/users/{userid} has parameter 'tokens' with 'additionalProperties' containing object definition

[Wolfgang Bumiller]

On Tue, Apr 02, 2024 at 09:27:57AM +0200, Fabian Grünbichler wrote:
> 
> > Jona Draaijer via pve-devel <pve-devel at lists.proxmox.com> hat am 01.04.2024 22:00 CEST geschrieben:
> > Hi,
> > 
> > As per the title, that endpoint has an additionalProperties value that is
> > not a bool, but rather an object definition. (It's defined in
> > pve-access-control/src/PVE/API2/User.pm).
> > 
> > As far as I can tell, all other 'additionalProperties' are bools. Does
> > anyone know why this specific one is different, or if this difference is
> > intentional?
> 
> I think this was just an accident.
> 
> > From the looks of it it seems like it's used as a "we need this standard
> > option, but also have to make it optional". I am still quite new to perl,
> > so I don't know if there is a way to do what was intended.
> 
> My guess is the intent was to have
> 
> 	    tokens => get_standard_option('token-info', { optional => 1 }),
> 
> instead, @Wolfgang?

The `token-info` standard option defines the structure of a single
token, which is a hash containing `expire`, `privsep` and `comment`.
If we map `tokens` to that, then `tokens` would be exactly one token.

The returned `tokens` value is a hash mapping token names to their info,
like:

      "tokens" : {
         "first" : {
            "expire" : 0,
            "privsep" : 1
         },
         "second" : {
            "expire" : 0,
            "privsep" : 1
         }
      }

So, each value inside the `tokens` object has the `token-info` schema.

Most other API calls seem to return an array with the id merged into it
as "tokenid", but this call did it this way from the beginning...

But yes, we don't *usually* do this, but our JSON schema validator
supported this and the API call was added like this originally, so
declaring its schema this way was easier.

You can see the definition in the JSON schema spec[1]. Note that `true`
and `false` are not explicitly mentioned there, as these values are
themselves considered schemas that "produce themselves as assertion
results"[2].

Also note that our schema isn't fully compliant with the spec
(for instance we declare required vs optional fields differently), but
at least feature-wise we do try to stick to keeping it a subset of it
(with the occasional weirdness-extension to deal with legacy cruft such
as how you can use the *value* of the *model* property as a *key* to
declare the mac address in a network interface for a VM's network
device... please don't :-) )

[1] https://json-schema.org/draft/2020-12/json-schema-core#section-10.3.2.3
[2] https://json-schema.org/draft/2020-12/json-schema-core#section-4.3.2