@sap/xssec/src/util/Types.js

XS Advanced Container Security API for node.js

/** @typedef {import('crypto').X509Certificate} X509Certificate */

// Credentials
/**
 * @typedef {object} ServiceCredentials
 * @property {string} [clientid]
 * @property {string} [url]
 * @property {string} [certificate] PEM-encoded client certificate
 * @property {string} [key] PEM-encoded client key
 * @property {string} [clientsecret] to be used as alternative authentication method to mTLS-based authentication. Must be defined when `certificate` is NOT defined.
 */

/**
 * @typedef {object} IdentityServiceCredentials
 * @property {string} [app_tid] tenant
 */

/**
 * @typedef {object} XsuaaServiceCredentials
 * @property {string} [xsappname]
 * @property {string} [uaadomain] domain of service
 * @property {string} [certurl] URL to fetch tokens based on mTLS. Must be defined when `certificate` is defined.
*/

/**
 * @typedef {object} XsaServiceCredentials
 * @property {string} [xsappname]
 * @property {string} [certurl] URL to fetch tokens based on mTLS. Must be defined when `certificate` is defined.
 */

/**
 * @typedef {object} UaaServiceCredentials
 * @property {string} [uaadomain] domain of service
 */


// Service configurations
/**
 * @typedef {object} ServiceConfig
 * @property {object} [endpoints] key/value object whose entries override default endpoints of service
 * @property {object} [validation] configures different kinds of validation
 * @property {boolean} [validation.enabled=true] If false, this service will accept TOKENS FOR ITS AUDIENCE WITHOUT VALIDATION. CAUTION! This flag MUST NOT BE ENABLED, except for tests or when it is impossible for the application to receive malicious or expired (etc.) tokens due to a central validating ingress gateway in front.
 * @property {JwksConfig} [validation.jwks] JWKS cache configuration
 * @property {CacheConfig} [validation.signatureCache] enables (true) signature cache with default configuration or configures signature cache.
 * @property {TokenFetchConfig} [tokenfetch] configures token fetch behaviour.
 * @property {object} [requests] default configuration for requests against this Service
 * @property {number} [requests.timeout=2000] request timeout in ms 
 * @property {boolean|ExponentialBackoffRetryConfig} [requests.retry] retry configuration. If set to true, the default retry configuration is used. If set to an object, parts of the default retry configuration are overridden with the provided values.
 */

/**
 * @typedef {object} TokenFetchConfig
 * @property {CacheConfig} [cache] configures the token fetch response cache used by the cached token getter methods (getClientCredentialsToken, getJwtBearerToken, getPasswordToken). Enabled by default with a built-in LRU cache of size 100. Set cache.enabled=false to disable.
 */

/**
 * @typedef {object} JwksConfig
 * @property {boolean} [shared=false] if true, shares the JWKS cache with the first instance of the same Service type that was created with this flag set to true, otherwise creates a new JWKS cache for each instance
 * @property {number} [expirationTime=1800000] time in *ms* since last refresh until a JWK counts as expired which requires a synchronous refresh on the next validation using this JWK
 * @property {number} [refreshPeriod=900000] time in *ms* since last refresh until a JWK counts as stale which triggers an asynchronous refresh in the background on the next validation using this JWK
 */

/**
 * @typedef {object} CacheConfig
 * @property {boolean} [enabled] - enables the cache
 * @property {Number} [size=100] - Size of the cache, defaults to 100
 * @property {import("../util/Types").Cache} [impl] - A custom cache instance that is used instead of the default LRUCache. 
 */

/**
 * @typedef {object} RetryConfig
 * @property {string} [name] name of the retry configuration strategy
 * @property {number} [retries=3] maximum number of retries
 * @property {number} [initialDelay=500] initial delay in ms between retries
 * @property {number} [factor=3] factor to exponentially increase the delay between retries
 * @property {number} [maxDelay=4000] maximum delay in ms between retries
 */

/**
 * @typedef {RetryConfig} ExponentialBackoffRetryConfig
 * @property {"exponential"} [name] name of the retry configuration
 */

/**
 * @typedef {object} IdentityServiceConfig
 * @property {object} [validation] configures different kinds of validation
 * @property {object} [validation.x5t] configures x5t validation
 * @property {boolean} [validation.x5t.enabled=false] enables x5t validation
 * @property {object} [validation.proofToken] configures proof token validation
 * @property {boolean} [validation.proofToken.enabled=false] enables proof token validation
 * @property {CacheConfig} [idTokenCache] configures id token cache (enabled with size 100 by default)
 * @property {object} [context] configuration for SecurityContexts created by this service
 * @property {boolean|XsuaaLegacyExtensionConfig} [xsuaaLegacyExtension] activation flag or custom configuration options for XSUAA legacy extension
 * @property {ContextExtension<import("../context/IdentityServiceSecurityContext")>[]} [context.extensions] a list of explicitly created SecurityContext extensions
 */

/**
 * @typedef {object} XsuaaLegacyExtensionConfig
 * @property {string} [primaryContextType="IdentityServiceSecurityContext"] Which context type should be returned after token validation.
 * @property {CacheConfig} [cache] Optional cache configuration. Defaults to an in-memory LRU with max size 100.
 */

/**
 * @template SC
 * @typedef {object} ContextExtension<SC>
 * @property {function(SC): Promise<void | import("../context/SecurityContext")>} extendSecurityContext a function that extends or patches properties of the SecurityContext, e.g. by fetching additional tokens to add a secondary SecurityContext
 */



// SecurityContext configurations
/**
 * @typedef {object} SecurityContextConfig
 * @property {object[]} [services] all Service instances passed to createSecurityContext global function
 * @property {string} [jwt] jwt token used to build the context if no Token instance is provided
 * @property {import("../token/Token")} [token] an already decoded Token instance used to build the context without decoding the jwt again
 * @property {string} [clientCertificatePem] client certificate in PEM format
 * @property {X509Certificate} [clientCertificate] parsed client certificate which will be automatically created from clientCertificatePem
 * @property {string} [correlationId] correlation id that will be sent along with external requests
 * @property {object} [req] request object from which the jwt and additional information, such as a correlation id and the forwarded client certificate, will be extracted if not provided directly
 * @property {object} [req.headers] request object from which the jwt and additional information, such as a correlation id and the forwarded client certificate, will be extracted if not provided directly
 * @property {boolean} [skipValidation=false] if true, the SecurityContext is created without validating the token. Caution! This flag MUST NOT BE ENABLED, except for testing or when the token has already been validated before, e.g. in DwC contexts.
 */

/**
 * @typedef {object} Cache A cache object that can be used to store and retrieve values via set and get methods.
 * @property {function} set Sets the value of the given key in the cache.
 * @property {function} get Retrieves the value of the given key from the cache.
 */


// Token fetch options
/** 
 * @typedef {object} TokenFetchOptions
 * @property {string} [correlationId] correlationId to correlate log entries with the request
 * @property {number} [timeout] request timeout in ms 
 * @property {"jwt"|"opaque"} [token_format] "jwt" or "opaque" (Default: "jwt")
*/

/** 
 * @typedef {object} IdentityServiceTokenFetchOptions
 * @property {string} [app_tid] can be used to override the app_tid from credentials for this token fetch
 * @property {string|string[]} [resource] name (or array of names) of API dependency to another application that shall be consumed with this token in the format urn:sap:identity:application:provider:name:<dependencyName>
 * @property {number} [refresh_expiry] expiration of refresh token. If set to 0, no refresh_token will be contained in the response
*/

/** 
 * @typedef {object} XsuaaTokenFetchOptions
 * @property {string[]} [scope] requested scope of token
 * @property {string} [tenant] (aka subdomain) the subdomain of a tenant on the same subaccount from which to fetch a token. Note that this parameter does NOT accept a tenant ID. To pass a zone ID, use the zid parameter instead.
 * @property {string} [zid] the zone id from which to fetch a token
 * @property {object} [authorities] additional authorities that can be freely chosen during token fetch that will be put into the token under az_attr claim (see https://github.com/cloudfoundry/uaa/blob/24c0c23fa36d7c604e365e1be4df658d55dcb211/docs/UAA-APIs.rst#support-for-additional-authorization-attributes)
*/

/**
 * @typedef {"client_credentials"|"password"|"urn:ietf:params:oauth:grant-type:jwt-bearer"} GrantType
*/



// Token fetch responses
/**
 * @typedef {object} TokenFetchResponse
 * @property {string} access_token access token as JWT
 * @property {number} expires_in number of seconds until the access token expires
 * @property {string} token_type
*/

/**
 * @typedef {object} IdTokenFetchResponse
 * @property {string} id_token - ID token as JWT
*/

/**
 * @typedef {object} RefreshableTokenFetchResponse
 * @property {string} refresh_token
*/

/** @typedef {TokenFetchResponse & IdTokenFetchResponse & RefreshableTokenFetchResponse} IdentityServicePasswordTokenFetchResponse */
/** @typedef {TokenFetchResponse & IdTokenFetchResponse & RefreshableTokenFetchResponse} IdentityServiceJwtBearerTokenFetchResponse */




// JWT structure
/**
 * @typedef {object} JwtHeader
 * @property {string} [kid] Key ID
 * @property {string} [alg] Algorithm
 */

/**
 * @typedef {object} JwtPayload
 * Standard claims https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.
 * @property {string} [iss] Issuer
 * @property {string} [sub] Subject
 * @property {string | string[]} [aud] Audience
 * @property {number} [exp] Expiration time
 * @property {number} [nbf] Not before
 * @property {number} [iat] Issued at
 * @property {string} [jti] JWT ID
 * Additional known claims
 * @property {string} [azp] Authorized party
 * @property {string} [email] Email
 * @property {string} [familiy_name] Family name
 * @property {string} [given_name] First name
 * @property {string} [grant_type] Grant type
 * @property {string} [user_name] User name
 * @property {string} [user_uuid] User UUID
*/

/**
 * @typedef {object} IdentityServiceJwtPayload
 * @property {string} [app_tid] The ID of the caller's tenant within the SAP Cloud Identity Service application for which the token was fetched.
 * @property {string[]} [ias_apis] SAP Cloud Identity Service APIs consumed by the caller
 * @property {string} [scim_id] SCIM ID
 * @property {string} [zone_uuid] Deprecated claim for app_tid
*/

/**
 * @typedef {object} XsuaaJwtPayload
 * @property {string} [cid] Client ID
 * @property {string} [client_id] Client ID
 * @property {string} [origin] Origin
 * @property {string[]} [scope] Scopes
 * @property {string} [user_id] User ID
 * @property {string} [zid] Zone ID
 */



module.exports = {};