@sap/xssec
Version:
XS Advanced Container Security API for node.js
150 lines (117 loc) • 6.44 kB
JavaScript
/** @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 {object} [validation.jwks] JWKS cache configuration
* @property {boolean} [validation.jwks.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} [validation.jwks.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} [validation.jwks.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
* @property {object} [requests] default configuration for requests against this Service
* @property {number} [requests.timeout=2000] request timeout in ms
*/
/**
* @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 {Array} [extensions] list of security context extensions that implement a context => Promise\<void\> function called extendSecurityContext
*/
// SecurityContext configurations
/**
* @typedef {object} SecurityContextConfig
* @property {string} [jwt] jwt token used to build the context
* @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 {Request} [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 {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.
*/
// 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>
*/
/**
* @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]
* @property {string} [alg]
*/
/**
* @typedef {object} JwtPayload
* Standard claims https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.
* @property {string} [iss]
* @property {string} [sub]
* @property {string | string[]} [aud]
* @property {number} [exp]
* @property {number} [nbf]
* @property {number} [iat]
* @property {string} [jti]
*/
module.exports = {};