From 1f58580e8d124bec165d8fd7f7568768b9e3377f Mon Sep 17 00:00:00 2001 From: rsouza Date: Mon, 18 Dec 2017 13:12:54 -0300 Subject: [PATCH] Add Iron typings https://github.com/hueniverse/iron --- types/iron/index.d.ts | 96 ++++++++++++++++++++++++++++++++++++++++ types/iron/iron-tests.ts | 78 ++++++++++++++++++++++++++++++++ types/iron/tsconfig.json | 23 ++++++++++ types/iron/tslint.json | 79 +++++++++++++++++++++++++++++++++ 4 files changed, 276 insertions(+) create mode 100644 types/iron/index.d.ts create mode 100644 types/iron/iron-tests.ts create mode 100644 types/iron/tsconfig.json create mode 100644 types/iron/tslint.json diff --git a/types/iron/index.d.ts b/types/iron/index.d.ts new file mode 100644 index 0000000000..6e5a77bc9e --- /dev/null +++ b/types/iron/index.d.ts @@ -0,0 +1,96 @@ +// Type definitions for iron 5.0 +// Project: https://github.com/hueniverse/iron +// Definitions by: Simon Schick +// Rafael Souza Fijalkowski +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 2.4 + +/// + +/** + * 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) + */ +declare module 'iron' { + + export interface ISomething { + saltBits: number; + algorithm: string; + iterations: number; + minPasswordlength: 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 interface ISealOptions { + encryption: ISomething; + integrity: ISomething; + ttl: number; + timestampSkewSec: number; + localtimeOffsetMsec: number; + } + + export interface IAlgorithms { + 'aes-128-ctr': { + keyBits: number; + ivBits: number; + }; + 'aes-256-cbc': { + keyBits: number; + ivBits: number; + }; + 'sha256': { + keyBits: number; + }; + } + + export const defaults: ISealOptions; + export const algorithms: IAlgorithms; + 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/iron/iron-tests.ts b/types/iron/iron-tests.ts new file mode 100644 index 0000000000..7fb095a0bf --- /dev/null +++ b/types/iron/iron-tests.ts @@ -0,0 +1,78 @@ +import * as Iron from "iron"; + +const options:Iron.ISealOptions = { + encryption: { + saltBits: 256, + algorithm: 'aes-256-cbc', + iterations: 1, + minPasswordlength: 32 + }, + integrity: { + saltBits: 256, + algorithm: 'sha256', + iterations: 1, + minPasswordlength: 32 + }, + ttl: 0, + timestampSkewSec: 60, + localtimeOffsetMsec: 0 +}; + +const algorithms:Iron.IAlgorithms = { + 'aes-128-ctr': { keyBits: 128, ivBits: 128 }, + 'aes-256-cbc': { keyBits: 256, ivBits: 128 }, + 'sha256': { keyBits: 256 } +}; + +const optionsGenerateKey:Iron.IGenerateKeyOptions = { + saltBits: 256, + salt: '4d8nr9q384nr9q384nr93q8nruq9348run', + algorithm: 'aes-128-ctr', + iterations: 10000, + iv: 'sdfsdfsdfsdfscdrgercgesrcgsercg', + minPasswordlength: 32 +}; + +const obj:object = { + a: 1, + b: 2, + c: [3, 4, 5], + d: { + e: 'f' + } +}; + +Iron.seal(obj, 'password', options) + .then((sealed: string) => { + console.log(sealed); + }); + +Iron.unseal('data', 'password', Iron.defaults) + .then((unsealed: object) => { + console.log(unsealed); + }); + +Iron.generateKey('password', options.encryption) + .then((value: Iron.IKey) => { + console.log(value); + }); + +Iron.generateKey('password', optionsGenerateKey) + .then((value: Iron.IKey) => { + console.log(value); + }); + +Iron.encrypt('password', Iron.defaults.encryption, 'data') + .then((obj: { data: Buffer, key: Iron.IKey }) => { + console.log(obj); + }); + +Iron.decrypt('password', Iron.defaults.encryption, 'data') + .then((buffer: Buffer) => { + console.log(buffer); + }); + +Iron.hmacWithPassword('password', Iron.defaults.integrity, 'data') + .then((value: Iron.IHMacResult) => { + console.log(value); + }); diff --git a/types/iron/tsconfig.json b/types/iron/tsconfig.json new file mode 100644 index 0000000000..d322f47b49 --- /dev/null +++ b/types/iron/tsconfig.json @@ -0,0 +1,23 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": false, + "strictFunctionTypes": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "iron-tests.ts" + ] +} diff --git a/types/iron/tslint.json b/types/iron/tslint.json new file mode 100644 index 0000000000..a41bf5d19a --- /dev/null +++ b/types/iron/tslint.json @@ -0,0 +1,79 @@ +{ + "extends": "dtslint/dt.json", + "rules": { + "adjacent-overload-signatures": false, + "array-type": false, + "arrow-return-shorthand": false, + "ban-types": false, + "callable-types": false, + "comment-format": false, + "dt-header": false, + "eofline": false, + "export-just-namespace": false, + "import-spacing": false, + "interface-name": false, + "interface-over-type-literal": false, + "jsdoc-format": false, + "max-line-length": false, + "member-access": false, + "new-parens": false, + "no-any-union": false, + "no-boolean-literal-compare": false, + "no-conditional-assignment": false, + "no-consecutive-blank-lines": false, + "no-construct": false, + "no-declare-current-package": false, + "no-duplicate-imports": false, + "no-duplicate-variable": false, + "no-empty-interface": false, + "no-for-in-array": false, + "no-inferrable-types": false, + "no-internal-module": false, + "no-irregular-whitespace": false, + "no-mergeable-namespace": false, + "no-misused-new": false, + "no-namespace": false, + "no-object-literal-type-assertion": false, + "no-padding": false, + "no-redundant-jsdoc": false, + "no-redundant-jsdoc-2": false, + "no-redundant-undefined": false, + "no-reference-import": false, + "no-relative-import-in-test": false, + "no-self-import": false, + "no-single-declare-module": false, + "no-string-throw": false, + "no-unnecessary-callback-wrapper": false, + "no-unnecessary-class": false, + "no-unnecessary-generics": false, + "no-unnecessary-qualifier": false, + "no-unnecessary-type-assertion": false, + "no-useless-files": false, + "no-var-keyword": false, + "no-var-requires": false, + "no-void-expression": false, + "no-trailing-whitespace": false, + "object-literal-key-quotes": false, + "object-literal-shorthand": false, + "one-line": false, + "one-variable-per-declaration": false, + "only-arrow-functions": false, + "prefer-conditional-expression": false, + "prefer-const": false, + "prefer-declare-function": false, + "prefer-for-of": false, + "prefer-method-signature": false, + "prefer-template": false, + "radix": false, + "semicolon": false, + "space-before-function-paren": false, + "space-within-parens": false, + "strict-export-declare-modifiers": false, + "trim-file": false, + "triple-equals": false, + "typedef-whitespace": false, + "unified-signatures": false, + "void-return": false, + "whitespace": false + } +}