@usvc/server
Creates a bootstrapped server based on Express.
Scope
Installation
npm i @usvc/server;
# OR
yarn add @usvc/server;
Usage
const {createServer} = require('@usvc/server');
// OR
import {createServer} from '@usvc/server';
Basic
// require as ^
const server = createServer();
const instance = server.listen(() => {
const {port} = instance.address;
console.info(`Listening on http://localhost:${port}`)
});
Full Configuration
// require as ^
const server = createServer({
enableCookies: true,
enableCors: true,
enableJsonBody: true,
enableUrlEncodedBody: true,
cookies: {
keys: [],
name: 'session',
secret: undefined,
domain: 'localhost',
httpOnly: true,
maxAge: 60e3 * 60,
path: '/',
},
cors: {
allowedHeaders: undefined,
credentials: true,
exposedHeaders: undefined,
maxAge: ONE_DAY,
methods: ALL_HTTP_METHODS,
optionsSuccessStatus: 204,
preflightContinue: true,
urls: [],
},
csp: {
childSrc: ['"self"'],
connectSrc: ['"self"'],
defaultSrc: ['"self"'],
disableAndroid: false,
fontSrc: ['"self"'],
imgSrc: ['"self"'],
logger: console,
logLevel: 'warn',
objectSrc: ['"none"'],
reportUri: '/csp-report',
sandbox: ['allow-forms', 'allow-scripts'],
scriptSrc: ['"self"'],
styleSrc: ['"self"'],
},
jsonBody: {
limit: '100kb',
type: '*/json',
},
logger: console,
middlewares: {},
urlEncodedBody: {
limit: '100kb',
type: '*/x-www-form-urlencoded',
},
});
const instance = server.listen(() => {
const {port} = instance.address;
console.info(`Listening on http://localhost:${port}`)
});
API Documentaiton
.createServer(:options)
Returns a bootstrapped Express server. The :options
parameter has the following schema:
Key | Type | Defaults To | Description |
---|
enableCookies | Boolean | true | Enables use of .cookies and .session in the request object in Express handlers |
enableJsonBody | Boolean | true | Enables use of .body in the request object if the Content-Type matches the :jsonBodyType parameter |
enableUrlEncodedBody | Boolean | true | Enables use of .body in the request object if the Content-Type matches the :urlEncodedType parameter |
cookies | DataCookieOptions | Options for configuring cookies management |
cors | SecurityCorsOptions | Options for configuring CORS |
jsonBody | DataJsonOptions | - | Options for configuring parsing of JSON body data |
logger | Object | console | The logger to use for this server instance |
middlewares | CreateServerHooks | {} | Any pre/post middleware injections you may need |
urlEncodedBody | DataUrlEncodedOptions | Options for configuring parsing of URL encoded body data |
Options Documentation
Options for cookies
(DataCookiesOptions
)
Key | Type | Defaults To | Description |
---|
keys | String[] | [] | Keys used to sign (index zero) and verify cookies (other index numbers) |
name | String | "session" | Name of the cookie |
secret | String | - | Secret used to compute the hash |
domain | String | "localhost" | Domain which the cookie is registered on |
httpOnly | Boolean | true | Set the HTTP-Only flag or not |
maxAge | Number | 60e3 * 60 | Maximum time the cookie is cacheable |
path | String | "/" | Path of the cookie |
Options for cors
(SecurityCorsOptions
)
Key | Type | Defaults To | Description |
---|
allowedHeaders | String[] | undefined | Sets the Access-Control-Allow-Headers HTTP response header |
credentials | Boolean | true | Specifies if credentials are allowed |
exposedHeaders | String[] | undefined | Sets the allowed headers to be exposed |
maxAge | Number | One day | The maximum age of caching in milliseconds |
methods | String[] | All HTTP methods | The allowed HTTP methods |
optionsSuccessStatus | Number | 204 | Specifies the HTTP status code to send on OPTIONS success |
preflightContinue | Boolean | true | Specifies if the preflight response should be sent immediately (false ) or not (true ) |
urls | String[] | [] | An array of allowed URLs for which the Origin request header can be |
Options for csp
(SecurityCspOptions
)
Key | Type | Defaults To | Description |
---|
childSrc | String[] | ['"self"'] | Sets the child-src in the CSP |
connectSrc | String[] | ['"self"'] | Sets the connect-src in the CSP |
defaultSrc | String[] | ['"self"'] | Sets the default-src in the CSP |
disableAndroid | Boolean | false | |
fontSrc | String[] | ['"self"'] | Sets the font-src in the CSP |
imgSrc | String[] | ['"self"'] | Sets the img-src in the CSP |
logger | Object | console | The logger object to use for logging |
logLevel | String | "warn" | The log level to use with the logger object. If this level is not found as a property of the logger object, an error will be thrown at runtime |
objectSrc | String[] | ['"none"'] | Sets the object-src in the CSP |
reportUri | URI | "/csp-report" | Sets the report-uri in the CSP where browsers will post to if a CSP violation is found. |
sandbox | String[] | ['allow-forms', 'allow-scripts] | Sets the sandbox in the CSP |
scriptSrc | String[] | ['"self"'] | Sets the script-src in the CSP |
styleSrc | String[] | ['"self"'] | Sets the style-src in the CSP |
Options for jsonBody
(DataJsonOptions
)
Key | Type | Defaults To | Description |
---|
limit | String | "100kb" | Maximum size of the JSON body |
type | String | "*/json" | Pattern of the Content-Type HTTP header value to invoke JSON body parsing |
Options for middlewares
(CreateServerHooks
)
Key | type | Defaults To | Description |
---|
after | RequestHandler[] | [] | Any post-initialisation middlewares |
before | RequestHandler[] | [] | Any pre-initialisation middlewares |
Options for urlEncodedBody
(DataUrlEncodedOptions
)
Key | Type | Defaults To | Description |
---|
limit | String | "100kb" | Maximum size of the JSON body |
type | String | "*/x-www-form-urlencoded" | Pattern of the Content-Type HTTP header value to invoke JSON body parsing |
Examples
WIP
Development
WIP
License
This package is licensed under the MIT license.
View the license at LICENSE.
Changelog
0.1.x
0.1.0
- Added cookie sessions
- Added CSP support
- Added server middleware hooks
0.x
0.0.2
- Cross Origin Resource Sharing (CORS) support
0.0.1
- Cookie parsing
- Basic HTTP header security
- Parsing of JSON encoded boday data
- Parsing of URL encoded body data
Contributors
Cheers