Externs

The externs are provided via the types/externs directory.

Compiler Externs
/** * @fileoverview * @externs */ /* typal types/index.xml externs */ /** @const */ var _goa = {} /** * The interface for Cookies: signed and unsigned cookies based on Keygrip. * Creates a new cookies object to handle cookies. * @param {!http.IncomingMessage} request The request object. * @param {!http.ServerResponse} response The response object. * @param {!_goa.CookiesOptions=} [options] Options for the constructor. * @interface */ _goa.Cookies = function(request, response, options) {} /** * The keys object constructed from passed keys (private, will be installed from options). * @type {(!_goa.Keygrip)|undefined} */ _goa.Cookies.prototype.keys /** * Explicitly specifies if the connection is secure (private, will be installed from options). * @type {boolean|undefined} */ _goa.Cookies.prototype.secure /** * This extracts the cookie with the given name from the Cookie header in the request. If such a cookie exists, its value is returned. Otherwise, nothing is returned. `{ signed: true }` can optionally be passed as the second parameter options. In this case, a signature cookie (a cookie of same name ending with the .sig suffix appended) is fetched. If no such cookie exists, nothing is returned. If the signature cookie does exist, the provided Keygrip object is used to check whether the hash of cookie-name=cookie-value matches that of any registered key: * - If the signature cookie hash matches the first key, the original cookie value is returned. * - If the signature cookie hash matches any other key, the original cookie value is returned AND an outbound header is set to update the signature cookie's value to the hash of the first key. This enables automatic freshening of signature cookies that have become stale due to key rotation. * - If the signature cookie hash does not match any key, nothing is returned, and an outbound header with an expired date is used to delete the cookie. * @param {string} name The name of the cookie to get. * @param {{ signed: boolean }} opts The options. * @return {(string|undefined)} */ _goa.Cookies.prototype.get = function(name, opts) {} /** * This sets the given cookie in the response and returns the current context to allow chaining. If the value is omitted, an outbound header with an expired date is used to delete the cookie. * @param {string} name The name of the cookie to set. * @param {?string=} [value] The value to set. * @param {!_goa.CookieSetOptions=} [attributes] The attributes and `signed` option. */ _goa.Cookies.prototype.set = function(name, value, attributes) {}
The externs provide the Cookies interface with the get and set methods.
/** * @fileoverview * @externs */ /* typal types/options.xml externs */ /** @const */ var _goa = {} /** * Options for the constructor. * @record */ _goa.CookiesOptions /** * The array of keys, or the `Keygrip` object. * @type {(!(Array<string>|_goa.Keygrip))|undefined} */ _goa.CookiesOptions.prototype.keys /** * Explicitly specifies if the connection is secure, rather than this module examining request. * @type {boolean|undefined} */ _goa.CookiesOptions.prototype.secure /* typal types/set.xml externs */ /** * How the cookie will be set. * @typedef {{ signed: (boolean|undefined) }} */ _goa.CookieSetOptions
The Cookies Options can be used in the constructor method of the Cookies class.
/** * @fileoverview * @externs */ /* typal types/attributes.xml externs */ /** @const */ var _goa = {} /** * Used to generate the outbound cookie header. * @record */ _goa.CookieAttributes /** * Represents the milliseconds from `Date.now()` for expiry. * @type {number|undefined} */ _goa.CookieAttributes.prototype.maxAge /** * Indicates the cookie's expiration date (expires at the end of session by default). * @type {(!Date)|undefined} */ _goa.CookieAttributes.prototype.expires /** * Indicates the path of the cookie. Default `/`. * @type {string|undefined} */ _goa.CookieAttributes.prototype.path /** * Indicates the domain of the cookie. * @type {string|undefined} */ _goa.CookieAttributes.prototype.domain /** * Indicates whether the cookie is only to be sent over HTTPS (false by default for HTTP, true by default for HTTPS). * @type {boolean|undefined} */ _goa.CookieAttributes.prototype.secure /** * Indicates whether the cookie is only to be sent over HTTP(S), and not made available to client JavaScript. Default `true`. * @type {boolean|undefined} */ _goa.CookieAttributes.prototype.httpOnly /** * Indicates whether the cookie is a "same site" cookie. This can be set to `'strict'`, `'lax'`, or `true` (which maps to `'strict'`). Default `false`. * @type {(boolean|string)|undefined} */ _goa.CookieAttributes.prototype.sameSite /** * Indicates whether to overwrite previously set cookies of the same name. If this is true, all cookies set during the same request with the same name (regardless of path or domain) are filtered out of the Set-Cookie header when setting this cookie. Default `false`. * @type {boolean|undefined} */ _goa.CookieAttributes.prototype.overwrite
The Cookies Attribute Records are the key-value pairs that are used to create string representation of the cookie, e.g., httpOnly=true.
/** * @fileoverview * @externs */ /* typal types/keygrip.xml externs */ /** @const */ var _goa = {} /** * Signing and verifying data (such as cookies or URLs) through a rotating credential system. * Creates a new Keygrip instance. Default algorithm is `sha1` and default encoding is `base64`. * @param {!Array<string>} keys The keys to use for signing. * @param {string=} [algorithm] The algorithm. Default `sha1`. * @param {string=} [encoding] The encoding. Default `base64`. * @interface */ _goa.Keygrip = function(keys, algorithm, encoding) {} /** * This creates a SHA1 HMAC based on the _first_ key in the keylist, and outputs it as a 27-byte url-safe base64 digest (base64 without padding, replacing `+` with `-` and `/` with `_`). * @param {*} data The value to sign. * @return {string} */ _goa.Keygrip.prototype.sign = function(data) {} /** * This loops through all of the keys currently in the keylist until the digest of the current key matches the given digest, at which point the current index is returned. If no key is matched, -1 is returned. The idea is that if the index returned is greater than `0`, the data should be re-signed to prevent premature credential invalidation, and enable better performance for subsequent challenges. * @param {*} data The value to verify. * @param {string} digest The digest to verify against. * @return {number} */ _goa.Keygrip.prototype.index = function(data, digest) {} /** * This uses `index` to return true if the digest matches any existing keys, and false otherwise. * @param {*} data The value to verify. * @param {string} digest The digest to verify against. * @return {boolean} */ _goa.Keygrip.prototype.verify = function(data, digest) {}
Keygrip is the class that implements _goa.Keygrip interface with the 3 methods declared in the API. It is then called by the Cookies instances to verify correct decoding of signed cookies.