From 62ae76a50e133263072db5b9262cd60df5dc3292 Mon Sep 17 00:00:00 2001 From: rafaelsouzaf Date: Sun, 17 Dec 2017 19:48:08 -0300 Subject: [PATCH] Add Iron typings, wrote by @SimonSchick --- .../server/server-state-options.d.ts | 6 +- types/hapi/definitions/util/iron.d.ts | 88 +++++++++++++++++++ types/hapi/index.d.ts | 1 + 3 files changed, 92 insertions(+), 3 deletions(-) create mode 100644 types/hapi/definitions/util/iron.d.ts diff --git a/types/hapi/definitions/server/server-state-options.d.ts b/types/hapi/definitions/server/server-state-options.d.ts index 55f749792f..cddc15c37e 100644 --- a/types/hapi/definitions/server/server-state-options.d.ts +++ b/types/hapi/definitions/server/server-state-options.d.ts @@ -1,4 +1,4 @@ -import {Request} from "hapi"; +import {Iron, Request} from "hapi"; /** * Optional cookie settings @@ -43,13 +43,13 @@ export interface ServerStateCookieOptions { * * password - password used for HMAC key generation (must be at least 32 characters long). */ sign?: { - integrity?: object; // TODO make iron definitions and getting typing from iron. Needs review! + integrity?: Iron.ISomething; password: string; }; /** password used for 'iron' encoding (must be at least 32 characters long). */ password?: string; /** options for 'iron' encoding. Defaults to require('iron').defaults. */ - iron?: object; // TODO make iron definitions and getting typing from iron. Needs review! + iron?: Iron.ISealOptions; /** if true, errors are ignored and treated as missing cookies. */ ignoreErrors?: boolean; /** if true, automatically instruct the client to remove invalid cookies. Defaults to false. */ diff --git a/types/hapi/definitions/util/iron.d.ts b/types/hapi/definitions/util/iron.d.ts new file mode 100644 index 0000000000..5f3d711803 --- /dev/null +++ b/types/hapi/definitions/util/iron.d.ts @@ -0,0 +1,88 @@ +/** + * iron is a cryptographic utility for sealing a JSON object using symmetric key encryption with message integrity + * verification. Or in other words, it lets you encrypt an object, send it around (in cookies, authentication + * credentials, etc.), then receive it back and decrypt it. The algorithm ensures that the message was not tampered + * with, and also provides a simple mechanism for password rotation. + * [See docs](https://github.com/hueniverse/iron) + * @author typings wrote by SimonSchick + */ +export namespace Iron { + + export interface ISomething { + saltBits: number; + algorithm: string; + iterations: number; + minPasswordlength: number; + } + + export interface ISealOptions { + encryption: ISomething; + integrity: ISomething; + + ttl: number; + timestampSkewSec: number; + localtimeOffsetMsec: number; + } + + /** + * iron provides a few options for customizing the key deriviation algorithm used to generate encryption and + * integrity verification keys as well as the algorithms and salt sizes used. The 'seal()' and 'unseal()' + * methods take an options object with the following required keys: + * * encryption - defines the options used by the encryption process. + * * integrity - defines the options used by the HMAC integrity verification process. + * Each of these option objects includes the following required keys: + * * saltBits - the size of the salt (random buffer used to ensure that two identical objects will generate a different encrypted result. + * * algorithm - the algorithm used ('aes-256-cbc' for encryption and 'sha256' for integrity are the only two supported at this time). + * * iterations - the number of iterations used to derive a key from the password. Set to 1 by default. The number of ideal iterations to use is dependent on your application's performance requirements. More iterations means it takes longer to generate the key. + * The 'seal()' and 'unseal()' methods also take the following optional options keys: + * * ttl - sealed object lifetime in milliseconds where 0 means forever. Defaults to 0. + * * timestampSkewSec - number of seconds of permitted clock skew for incoming expirations. Defaults to 60 seconds. + * * localtimeOffsetMsec - local clock time offset, expressed in number of milliseconds (positive or negative). Defaults to 0. + * [See docs](https://github.com/hueniverse/iron#options) + */ + export const defaults: ISealOptions; + + export const algorithms: { + 'aes-128-ctr': { + keyBits: number; + ivBits: number; + }; + 'aes-256-cbc': { + keyBits: number; + ivBits: number; + }; + 'sha256': { + keyBits: number; + }; + }; + + export const macFormatVersion: string; + export const macPrefix: string; + + export interface IGenerateKeyOptions extends Pick { + saltBits?: number; + salt?: string; + iv?: string; + } + + export interface IKey { + key: Buffer; + salt: string; + iv: string; + } + + export function generateKey (password: string, options: IGenerateKeyOptions): Promise; + export function encrypt (password: string, options: IGenerateKeyOptions, data: string): Promise<{ data: Buffer, key: IKey }>; + export function decrypt (password: string, options: IGenerateKeyOptions, data: string): Promise; + + export interface IHMacResult { + digest: string; + salt: string; + } + + export function hmacWithPassword(password: string, options: IGenerateKeyOptions, data: string): Promise; + + export function seal (obj: object, password: string, options: ISealOptions): Promise; + export function unseal (data: string, password: string, options: ISealOptions): Promise; + +} diff --git a/types/hapi/index.d.ts b/types/hapi/index.d.ts index 151246f5e9..58d84ba89f 100644 --- a/types/hapi/index.d.ts +++ b/types/hapi/index.d.ts @@ -65,6 +65,7 @@ export * from './definitions/server/server-state' export * from './definitions/server/server-state-options' /** UTIL */ +export * from './definitions/util/iron' export * from './definitions/util/json' export * from './definitions/util/lifecycle' export * from './definitions/util/util'