From 9d38a1c91e0cc6644c51bc5f928e58e46bf06a9b Mon Sep 17 00:00:00 2001 From: Owen Pearson Date: Fri, 28 Apr 2023 17:07:23 +0100 Subject: [PATCH] feat: add `Auth#revokeTokens` specs Co-authored-by: Lawrence Forooghian --- textile/features.textile | 44 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/textile/features.textile b/textile/features.textile index 9ae386463..ef16bdae4 100644 --- a/textile/features.textile +++ b/textile/features.textile @@ -256,6 +256,13 @@ h3(#rest-auth). Auth ** @(RSA16b)@ If the library is provided with a token without the corresponding @TokenDetails@, then this holds a @TokenDetails@ instance in which only the @token@ attribute is populated with that token string ** @(RSA16c)@ Is set with the current token (if applicable) on instantiation and each time it is replaced, whether the result of an explicit @Auth#authorize@ operation, or a library-initiated renewal resulting from expiry or a token error response ** @(RSA16d)@ Is @null@ if there is no current token, including after a previous token has been determined to be invalid or expired, or if the library is using basic auth +* @(RSA17)@ @Auth#revokeTokens@ function: +** @(RSA17a)@ Takes a @TokenRevocationTargetSpecifier@ or an array of @TokenRevocationTargetSpecifier@s and sends them in a POST request to /keys/{API_KEY_NAME}/revokeTokens, with the newBatchResponse query param set to "true", where @API_KEY_NAME@ is the API key name obtained by reading @AuthOptions#key@ up until the first @:@ character. +** @(RSA17b)@ The @TokenRevocationTargetSpecifier@s should be mapped to strings by joining the @type@ and @value@ with a ":" character and sent in the @targets@ field of the request body +** @(RSA17c)@ Returns an array of @BatchResult@s. Optionally, in languages where this is idiomatic, an overload may be implemented whereby the method can be called with a single @TokenRevocationTargetSpecifier@ and return a single @BatchResult@. This is not a feature of the REST API, whose response will still be an array, so if implementing this overload, the SDK will have to extract the element from the array. +** @(RSA17d)@ If called from a client using token authentication, should raise an @ErrorInfo@ with a @40162@ error code +** @(RSA17e)@ Accepts an optional @issuedBefore@ timestamp, represented as milliseconds since the epoch, or a `Time` object if idiomatic to the language +** @(RSA17f)@ If an @allowReauthMargin@ boolean is supplied, it should be included in the @allowReauthMargin@ field of the request body h3(#rest-channels). Channels @@ -1555,6 +1562,28 @@ h4. BatchPresenceFailureResult ** @(BGF2a)@ @channel@ string - the name of the channel ** @(BGF2b)@ @error@ @ErrorInfo@ - @ErrorInfo@ indicating the reason the presence request failed for the given channel +h4. TokenRevocationTargetSpecifier + +* @(TRT1)@ Describes which tokens should be affected by a token revocation request +* @(TRT2)@ The attributes of @TokenRevocationTargetSpecifier@ consist of: +** @(TRT2a)@ @type@ string - the type of token revocation target specifier (eg. "clientId", "revocationKey", "channel") +** @(TRT2b)@ @value@ string - the value of the token revocation target specifier + +h4. TokenRevocationSuccessResult + +* @(TRS1)@ Contains information about the result of a successful token revocation request for a single target specifier +* @(TRS2)@ The attributes of @TokenRevocationSuccessResult@ consist of: +** @(TRS2a)@ @target@ string - the target specifier +** @(TRS2b)@ @appliesAt@ Time - a timestamp at which the token revocation will take effect +** @(TRS2c)@ @issuedBefore@ Time - a timestamp for which tokens previously issued will be revoked + +h4. TokenRevocationFailureResult + +* @(TRF1)@ Contains information about the result of an unsuccessful token revocation request for a single target specifier +* @(TRF2)@ The attributes of @TokenRevocationFailureResult@ consist of: +** @(TRF2a)@ @target@ string - the target specifier +** @(TRF2b)@ @error@ @ErrorInfo@ - an @ErrorInfo@ indicating the reason the token revocation request failed for the given specified + h4. MessageFilter * @(MFI1)@ Supplies filter options to subscribe as defined in #RTL22 * @(MFI2)@ Contains the following attributes: @@ -1872,6 +1901,8 @@ class Auth: // RSA* createTokenRequest(TokenParams?, AuthOptions?) => io TokenRequest // RSA9 requestToken(TokenParams?, AuthOptions?) => io TokenDetails // RSA8 tokenDetails: TokenDetails? // RSA16 + revokeTokens(TokenRevocationTargetSpecifier, issuedBefore Time?, allowReauthMargin boolean?) => io BatchResult // RSA17 + revokeTokens(TokenRevocationTargetSpecifier[], issuedBefore Time?, allowReauthMargin boolean?) => io BatchResult[] // RSA17 class TokenDetails: // TD* +fromJson(String | JsonObject) -> TokenDetails // TD7 @@ -2424,6 +2455,19 @@ class BatchPresenceSuccessResult: class BatchPresenceFailureResult channel: string // BGF2a error: ErrorInfo // BGF2b + +class TokenRevocationTargetSpecifier: + type: string // TRT2a + value: string // TRT2b + +class TokenRevocationSuccessResult: + target: string // TRS2a + appliesAt: Time // TRS2b + issuedBefore: Time // TRS2c + +class TokenRevocationFailureResult: + target: string // TRF2a + error: ErrorInfo // TRF2b h2(#old-specs). Old specs