@acryldev/create-blends 1.7.0 → 1.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/{docs/framework/LICENSE → LICENSE} +1 -3
- package/package.json +2 -2
- package/docs/framework/README.md +0 -70
- package/docs/framework/agents/index.md +0 -59
- package/docs/framework/api/acryl.md +0 -247
- package/docs/framework/api/context.md +0 -478
- package/docs/framework/api/exception.md +0 -80
- package/docs/framework/api/index.md +0 -12
- package/docs/framework/api/presets.md +0 -62
- package/docs/framework/api/request.md +0 -396
- package/docs/framework/api/routing.md +0 -303
- package/docs/framework/api/summary.md +0 -143
- package/docs/framework/concepts/benchmarks.md +0 -26
- package/docs/framework/concepts/developer-experience.md +0 -5
- package/docs/framework/concepts/middleware.md +0 -21
- package/docs/framework/concepts/motivation.md +0 -14
- package/docs/framework/concepts/routers.md +0 -63
- package/docs/framework/concepts/stacks.md +0 -235
- package/docs/framework/concepts/web-standard.md +0 -27
- package/docs/framework/cordis/acryl-in-a-cordis-app.md +0 -160
- package/docs/framework/cordis/concepts.md +0 -105
- package/docs/framework/cordis/middleware.md +0 -8
- package/docs/framework/cordis/migration-from-0-3.md +0 -111
- package/docs/framework/cordis/migration-from-0-4.md +0 -14
- package/docs/framework/cordis/migration-from-dsh-webserver.md +0 -109
- package/docs/framework/cordis/migration-to-1-0.md +0 -46
- package/docs/framework/cordis/mounting.md +0 -85
- package/docs/framework/cordis/node-server.md +0 -100
- package/docs/framework/cordis/plugin-lifecycle.md +0 -111
- package/docs/framework/cordis/surfaces.md +0 -71
- package/docs/framework/cordis/transport-and-cancellation.md +0 -57
- package/docs/framework/cordis/validation.md +0 -135
- package/docs/framework/getting-started/basic.md +0 -201
- package/docs/framework/getting-started/bun.md +0 -219
- package/docs/framework/getting-started/deploy.md +0 -133
- package/docs/framework/getting-started/desktop.md +0 -80
- package/docs/framework/getting-started/nodejs.md +0 -365
- package/docs/framework/getting-started/other-runtimes.md +0 -30
- package/docs/framework/guides/best-practices.md +0 -231
- package/docs/framework/guides/bring-your-own-tool.md +0 -218
- package/docs/framework/guides/client-modules.md +0 -210
- package/docs/framework/guides/create-acrylblends.md +0 -143
- package/docs/framework/guides/data.md +0 -314
- package/docs/framework/guides/examples.md +0 -3
- package/docs/framework/guides/faq.md +0 -19
- package/docs/framework/guides/forms-and-sessions.md +0 -235
- package/docs/framework/guides/helpers.md +0 -33
- package/docs/framework/guides/jsx-dom.md +0 -301
- package/docs/framework/guides/jsx.md +0 -487
- package/docs/framework/guides/middleware.md +0 -253
- package/docs/framework/guides/production.md +0 -80
- package/docs/framework/guides/rpc.md +0 -878
- package/docs/framework/guides/testing.md +0 -133
- package/docs/framework/guides/validation.md +0 -470
- package/docs/framework/helpers/accepts.md +0 -60
- package/docs/framework/helpers/adapter.md +0 -57
- package/docs/framework/helpers/conninfo.md +0 -77
- package/docs/framework/helpers/cookie.md +0 -232
- package/docs/framework/helpers/css.md +0 -282
- package/docs/framework/helpers/dev.md +0 -64
- package/docs/framework/helpers/factory.md +0 -180
- package/docs/framework/helpers/html.md +0 -123
- package/docs/framework/helpers/jwt.md +0 -184
- package/docs/framework/helpers/proxy.md +0 -115
- package/docs/framework/helpers/route.md +0 -143
- package/docs/framework/helpers/ssg.md +0 -390
- package/docs/framework/helpers/streaming.md +0 -224
- package/docs/framework/helpers/testing.md +0 -118
- package/docs/framework/helpers/websocket.md +0 -208
- package/docs/framework/middleware/builtin/basic-auth.md +0 -165
- package/docs/framework/middleware/builtin/bearer-auth.md +0 -138
- package/docs/framework/middleware/builtin/body-limit.md +0 -71
- package/docs/framework/middleware/builtin/cache.md +0 -99
- package/docs/framework/middleware/builtin/combine.md +0 -94
- package/docs/framework/middleware/builtin/compress.md +0 -59
- package/docs/framework/middleware/builtin/context-storage.md +0 -74
- package/docs/framework/middleware/builtin/cors.md +0 -134
- package/docs/framework/middleware/builtin/csrf.md +0 -105
- package/docs/framework/middleware/builtin/etag.md +0 -54
- package/docs/framework/middleware/builtin/ip-restriction.md +0 -69
- package/docs/framework/middleware/builtin/jsx-renderer.md +0 -283
- package/docs/framework/middleware/builtin/jwk.md +0 -192
- package/docs/framework/middleware/builtin/jwt.md +0 -145
- package/docs/framework/middleware/builtin/language.md +0 -232
- package/docs/framework/middleware/builtin/logger.md +0 -74
- package/docs/framework/middleware/builtin/loopback-only.md +0 -31
- package/docs/framework/middleware/builtin/method-not-allowed.md +0 -48
- package/docs/framework/middleware/builtin/method-override.md +0 -80
- package/docs/framework/middleware/builtin/mount.md +0 -103
- package/docs/framework/middleware/builtin/pretty-json.md +0 -53
- package/docs/framework/middleware/builtin/request-id.md +0 -87
- package/docs/framework/middleware/builtin/secure-headers.md +0 -247
- package/docs/framework/middleware/builtin/timeout.md +0 -98
- package/docs/framework/middleware/builtin/timing.md +0 -100
- package/docs/framework/middleware/builtin/trailing-slash.md +0 -74
- package/docs/framework/middleware/third-party.md +0 -4
- package/docs/framework/workshop/README.md +0 -294
- package/docs/framework/workshop/facilitator.md +0 -101
|
@@ -1,48 +0,0 @@
|
|
|
1
|
-
# Method Not Allowed Middleware
|
|
2
|
-
|
|
3
|
-
The Method Not Allowed middleware returns a `405 Method Not Allowed` response with an `Allow` header when the request path matches a registered route but the request method is not supported. Without this middleware, Acryl returns a `404 Not Found` in that case.
|
|
4
|
-
|
|
5
|
-
## Import
|
|
6
|
-
|
|
7
|
-
```ts
|
|
8
|
-
import { Acryl } from '@acryldev/blends'
|
|
9
|
-
import { methodNotAllowed } from '@acryldev/blends/method-not-allowed'
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
## Usage
|
|
13
|
-
|
|
14
|
-
```ts
|
|
15
|
-
const app = new Acryl()
|
|
16
|
-
|
|
17
|
-
app.use(methodNotAllowed({ app }))
|
|
18
|
-
|
|
19
|
-
app.get('/hello', (c) => c.text('Hello!'))
|
|
20
|
-
app.post('/hello', (c) => c.text('Posted!'))
|
|
21
|
-
|
|
22
|
-
// PUT /hello -> 405 Method Not Allowed
|
|
23
|
-
// Allow: GET, HEAD, POST
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
You can customize the response with the `onMethodNotAllowed` option:
|
|
27
|
-
|
|
28
|
-
```ts
|
|
29
|
-
app.use(
|
|
30
|
-
methodNotAllowed({
|
|
31
|
-
app,
|
|
32
|
-
onMethodNotAllowed: (c, methods) =>
|
|
33
|
-
c.json({ error: 'Method Not Allowed' }, 405, {
|
|
34
|
-
Allow: methods.join(', '),
|
|
35
|
-
}),
|
|
36
|
-
})
|
|
37
|
-
)
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## Options
|
|
41
|
-
|
|
42
|
-
### **(required)** app: `Acryl`
|
|
43
|
-
|
|
44
|
-
The Acryl instance used by the application. The middleware collects the allowed methods for each path from its registered routes.
|
|
45
|
-
|
|
46
|
-
### *(optional)* onMethodNotAllowed: `(c: Context, allowedMethods: string[]) => Response | Promise<Response>`
|
|
47
|
-
|
|
48
|
-
Generates the response, including its `Allow` header. By default, the middleware returns a `405 Method Not Allowed` response with the `Allow` header set to the allowed methods.
|
|
@@ -1,80 +0,0 @@
|
|
|
1
|
-
# Method Override Middleware
|
|
2
|
-
|
|
3
|
-
This middleware executes the handler of the specified method, which is different from the actual method of the request, depending on the value of the form, header, or query, and returns its response.
|
|
4
|
-
|
|
5
|
-
## Import
|
|
6
|
-
|
|
7
|
-
```ts
|
|
8
|
-
import { Acryl } from '@acryldev/blends'
|
|
9
|
-
import { methodOverride } from '@acryldev/blends/method-override'
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
## Usage
|
|
13
|
-
|
|
14
|
-
```ts
|
|
15
|
-
const app = new Acryl()
|
|
16
|
-
|
|
17
|
-
// If no options are specified, the value of `_method` in the form,
|
|
18
|
-
// e.g. DELETE, is used as the method.
|
|
19
|
-
app.use('/posts', methodOverride({ app }))
|
|
20
|
-
|
|
21
|
-
app.delete('/posts', (c) => {
|
|
22
|
-
// ....
|
|
23
|
-
})
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## For example
|
|
27
|
-
|
|
28
|
-
Since HTML forms cannot send a DELETE method, you can put the value `DELETE` in the property named `_method` and send it. And the handler for `app.delete()` will be executed.
|
|
29
|
-
|
|
30
|
-
The HTML form:
|
|
31
|
-
|
|
32
|
-
```html
|
|
33
|
-
<form action="/posts" method="POST">
|
|
34
|
-
<input type="hidden" name="_method" value="DELETE" />
|
|
35
|
-
<input type="text" name="id" />
|
|
36
|
-
</form>
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
The application:
|
|
40
|
-
|
|
41
|
-
```ts
|
|
42
|
-
import { methodOverride } from '@acryldev/blends/method-override'
|
|
43
|
-
|
|
44
|
-
const app = new Acryl()
|
|
45
|
-
app.use('/posts', methodOverride({ app }))
|
|
46
|
-
|
|
47
|
-
app.delete('/posts', () => {
|
|
48
|
-
// ...
|
|
49
|
-
})
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
You can change the default values or use the header value and query value:
|
|
53
|
-
|
|
54
|
-
```ts
|
|
55
|
-
app.use('/posts', methodOverride({ app, form: '_custom_name' }))
|
|
56
|
-
app.use(
|
|
57
|
-
'/posts',
|
|
58
|
-
methodOverride({ app, header: 'X-METHOD-OVERRIDE' })
|
|
59
|
-
)
|
|
60
|
-
app.use('/posts', methodOverride({ app, query: '_method' }))
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
## Options
|
|
64
|
-
|
|
65
|
-
### **(required)** app: `Acryl`
|
|
66
|
-
|
|
67
|
-
The instance of `Acryl` is used in your application.
|
|
68
|
-
|
|
69
|
-
### *(optional)* form: `string`
|
|
70
|
-
|
|
71
|
-
Form key with a value containing the method name.
|
|
72
|
-
The default is `_method`.
|
|
73
|
-
|
|
74
|
-
### *(optional)* header: `boolean`
|
|
75
|
-
|
|
76
|
-
Header name with a value containing the method name.
|
|
77
|
-
|
|
78
|
-
### *(optional)* query: `boolean`
|
|
79
|
-
|
|
80
|
-
Query parameter key with a value containing the method name.
|
|
@@ -1,103 +0,0 @@
|
|
|
1
|
-
# Mount Middleware
|
|
2
|
-
|
|
3
|
-
The Mount Middleware lets you mount an application built with another framework into your Acryl application.
|
|
4
|
-
|
|
5
|
-
## Import
|
|
6
|
-
|
|
7
|
-
```ts twoslash
|
|
8
|
-
import { Acryl } from '@acryldev/blends'
|
|
9
|
-
import { mount } from '@acryldev/blends/mount'
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
## Usage
|
|
13
|
-
|
|
14
|
-
Register the middleware with `app.all()` on a path that ends with `/*`:
|
|
15
|
-
|
|
16
|
-
```ts
|
|
17
|
-
import { Router as IttyRouter } from 'itty-router'
|
|
18
|
-
|
|
19
|
-
// Create itty-router application
|
|
20
|
-
const ittyRouter = IttyRouter()
|
|
21
|
-
|
|
22
|
-
// Handle `GET /itty-router/hello`
|
|
23
|
-
ittyRouter.get('/hello', () => new Response('Hello from itty-router'))
|
|
24
|
-
|
|
25
|
-
const app = new Acryl()
|
|
26
|
-
|
|
27
|
-
app.all('/itty-router/*', mount(ittyRouter.handle))
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
By default, the mounted application receives a new `Request` with the matched path prefix removed from its URL. A request to `/itty-router/hello` reaches itty-router as `/hello`.
|
|
31
|
-
|
|
32
|
-
The mounted application is called as `handler(request, c.env, c.executionCtx)`, the three arguments a `fetch`-style handler takes. Use `optionHandler` to pass different arguments.
|
|
33
|
-
|
|
34
|
-
## Options
|
|
35
|
-
|
|
36
|
-
You can pass a function or an object as the second argument.
|
|
37
|
-
|
|
38
|
-
### *(optional)* optionHandler: `(c: Context) => unknown`
|
|
39
|
-
|
|
40
|
-
Returns the arguments passed to the mounted application after the `Request`. An array is spread into multiple arguments. You can pass the function directly as the second argument:
|
|
41
|
-
|
|
42
|
-
```ts twoslash
|
|
43
|
-
import { Acryl } from '@acryldev/blends'
|
|
44
|
-
import { mount } from '@acryldev/blends/mount'
|
|
45
|
-
const app = new Acryl()
|
|
46
|
-
const anotherApp = (request: Request, ...args: unknown[]) =>
|
|
47
|
-
new Response(request.url)
|
|
48
|
-
// ---cut---
|
|
49
|
-
// Call `anotherApp(request, c.env)`
|
|
50
|
-
app.all(
|
|
51
|
-
'/app/*',
|
|
52
|
-
mount(anotherApp, (c) => c.env)
|
|
53
|
-
)
|
|
54
|
-
|
|
55
|
-
// Call `anotherApp(request, c.env, c.executionCtx)`
|
|
56
|
-
app.all(
|
|
57
|
-
'/app/*',
|
|
58
|
-
mount(anotherApp, {
|
|
59
|
-
optionHandler: (c) => [c.env, c.executionCtx],
|
|
60
|
-
})
|
|
61
|
-
)
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
### *(optional)* replaceRequest: `((originalRequest: Request) => Request) | false`
|
|
65
|
-
|
|
66
|
-
Controls which `Request` is passed to the mounted application:
|
|
67
|
-
|
|
68
|
-
```ts twoslash
|
|
69
|
-
import { Acryl } from '@acryldev/blends'
|
|
70
|
-
import { mount } from '@acryldev/blends/mount'
|
|
71
|
-
const app = new Acryl()
|
|
72
|
-
const anotherApp = (request: Request, ...args: unknown[]) =>
|
|
73
|
-
new Response(request.url)
|
|
74
|
-
// ---cut---
|
|
75
|
-
// `/legacy/users` reaches the mounted application as `/api/users`
|
|
76
|
-
app.all(
|
|
77
|
-
'/legacy/*',
|
|
78
|
-
mount(anotherApp, {
|
|
79
|
-
replaceRequest: (req) => {
|
|
80
|
-
const url = new URL(req.url)
|
|
81
|
-
url.pathname = url.pathname.replace(/^\/legacy/, '/api')
|
|
82
|
-
return new Request(url, req)
|
|
83
|
-
},
|
|
84
|
-
})
|
|
85
|
-
)
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
To pass the original `Request` unchanged, set it to `false` as a shorthand for `(req) => req`:
|
|
89
|
-
|
|
90
|
-
```ts twoslash
|
|
91
|
-
import { Acryl } from '@acryldev/blends'
|
|
92
|
-
import { mount } from '@acryldev/blends/mount'
|
|
93
|
-
const app = new Acryl()
|
|
94
|
-
const anotherApp = (request: Request, ...args: unknown[]) =>
|
|
95
|
-
new Response(request.url)
|
|
96
|
-
// ---cut---
|
|
97
|
-
app.all(
|
|
98
|
-
'/app/*',
|
|
99
|
-
mount(anotherApp, {
|
|
100
|
-
replaceRequest: false,
|
|
101
|
-
})
|
|
102
|
-
)
|
|
103
|
-
```
|
|
@@ -1,53 +0,0 @@
|
|
|
1
|
-
# Pretty JSON Middleware
|
|
2
|
-
|
|
3
|
-
Pretty JSON middleware enables "_JSON pretty print_" for JSON response body.
|
|
4
|
-
Adding `?pretty` to url query param, the JSON strings are prettified.
|
|
5
|
-
|
|
6
|
-
```js
|
|
7
|
-
// GET /
|
|
8
|
-
{"project":{"name":"Acryl","repository":"https://github.com/acrylblends/acrylblends"}}
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
will be:
|
|
12
|
-
|
|
13
|
-
```js
|
|
14
|
-
// GET /?pretty
|
|
15
|
-
{
|
|
16
|
-
"project": {
|
|
17
|
-
"name": "Acryl",
|
|
18
|
-
"repository": "https://github.com/acrylblends/acrylblends"
|
|
19
|
-
}
|
|
20
|
-
}
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
## Import
|
|
24
|
-
|
|
25
|
-
```ts
|
|
26
|
-
import { Acryl } from '@acryldev/blends'
|
|
27
|
-
import { prettyJSON } from '@acryldev/blends/pretty-json'
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
## Usage
|
|
31
|
-
|
|
32
|
-
```ts
|
|
33
|
-
const app = new Acryl()
|
|
34
|
-
|
|
35
|
-
app.use(prettyJSON()) // With options: prettyJSON({ space: 4 })
|
|
36
|
-
app.get('/', (c) => {
|
|
37
|
-
return c.json({ message: 'Acryl!' })
|
|
38
|
-
})
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
## Options
|
|
42
|
-
|
|
43
|
-
### *(optional)* space: `number`
|
|
44
|
-
|
|
45
|
-
Number of spaces for indentation. The default is `2`.
|
|
46
|
-
|
|
47
|
-
### *(optional)* query: `string`
|
|
48
|
-
|
|
49
|
-
The name of the query string for applying. The default is `pretty`.
|
|
50
|
-
|
|
51
|
-
### *(optional)* force: `boolean`
|
|
52
|
-
|
|
53
|
-
When set to `true`, JSON responses are always prettified regardless of the query parameter. The default is `false`.
|
|
@@ -1,87 +0,0 @@
|
|
|
1
|
-
# Request ID Middleware
|
|
2
|
-
|
|
3
|
-
Request ID Middleware generates a unique ID for each request, which you can use in your handlers.
|
|
4
|
-
|
|
5
|
-
> **Note.** **Node.js**: This middleware uses `crypto.randomUUID()` to generate IDs. The global `crypto` was introduced in Node.js version 20 or later. Therefore, errors may occur in versions earlier than that. In that case, please specify `generator`. However, if you are using the Node.js adapter, it automatically sets `crypto` globally, so this is not necessary.
|
|
6
|
-
|
|
7
|
-
## Import
|
|
8
|
-
|
|
9
|
-
```ts
|
|
10
|
-
import { Acryl } from '@acryldev/blends'
|
|
11
|
-
import { requestId } from '@acryldev/blends/request-id'
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
## Usage
|
|
15
|
-
|
|
16
|
-
You can access the Request ID through the `requestId` variable in the handlers and middleware to which the Request ID Middleware is applied.
|
|
17
|
-
|
|
18
|
-
```ts
|
|
19
|
-
const app = new Acryl()
|
|
20
|
-
|
|
21
|
-
app.use('*', requestId())
|
|
22
|
-
|
|
23
|
-
app.get('/', (c) => {
|
|
24
|
-
return c.text(`Your request id is ${c.get('requestId')}`)
|
|
25
|
-
})
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
If you want to explicitly specify the type, import `RequestIdVariables` and pass it in the generics of `new Acryl()`.
|
|
29
|
-
|
|
30
|
-
```ts
|
|
31
|
-
import type { RequestIdVariables } from '@acryldev/blends/request-id'
|
|
32
|
-
|
|
33
|
-
const app = new Acryl<{
|
|
34
|
-
Variables: RequestIdVariables
|
|
35
|
-
}>()
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
### Set Request ID
|
|
39
|
-
|
|
40
|
-
You set a custom request ID in the header (default: `X-Request-Id`), the middleware will use that value instead of generating a new one:
|
|
41
|
-
|
|
42
|
-
```ts
|
|
43
|
-
const app = new Acryl()
|
|
44
|
-
|
|
45
|
-
app.use('*', requestId())
|
|
46
|
-
|
|
47
|
-
app.get('/', (c) => {
|
|
48
|
-
return c.text(`${c.get('requestId')}`)
|
|
49
|
-
})
|
|
50
|
-
|
|
51
|
-
const res = await app.request('/', {
|
|
52
|
-
headers: {
|
|
53
|
-
'X-Request-Id': 'your-custom-id',
|
|
54
|
-
},
|
|
55
|
-
})
|
|
56
|
-
console.log(await res.text()) // your-custom-id
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
If you want to disable this feature, set [`headerName` option](#headername-string) to an empty string.
|
|
60
|
-
|
|
61
|
-
## Options
|
|
62
|
-
|
|
63
|
-
### *(optional)* limitLength: `number`
|
|
64
|
-
|
|
65
|
-
The maximum length of the request ID. The default is `255`.
|
|
66
|
-
|
|
67
|
-
### *(optional)* headerName: `string`
|
|
68
|
-
|
|
69
|
-
The header name used for the request ID. The default is `X-Request-Id`.
|
|
70
|
-
|
|
71
|
-
### *(optional)* generator: `(c: Context) => string`
|
|
72
|
-
|
|
73
|
-
The request ID generation function. By default, it uses `crypto.randomUUID()`.
|
|
74
|
-
|
|
75
|
-
## An ID that came from earlier in the chain
|
|
76
|
-
|
|
77
|
-
A proxy, a load balancer or the host that starts the app may already put a request id on the request.
|
|
78
|
-
Without configuration this middleware is unaware of it and generates a new one, which makes the two logs hard to line up.
|
|
79
|
-
Use the `generator` function to read the incoming one and fall back to a fresh id:
|
|
80
|
-
|
|
81
|
-
```ts
|
|
82
|
-
app.use(
|
|
83
|
-
requestId({
|
|
84
|
-
generator: (c) => c.req.header('X-Request-Id') ?? crypto.randomUUID(),
|
|
85
|
-
})
|
|
86
|
-
)
|
|
87
|
-
```
|
|
@@ -1,247 +0,0 @@
|
|
|
1
|
-
# Secure Headers Middleware
|
|
2
|
-
|
|
3
|
-
Secure Headers Middleware simplifies the setup of security headers. Inspired in part by the capabilities of Helmet, it allows you to control the activation and deactivation of specific security headers.
|
|
4
|
-
|
|
5
|
-
## Import
|
|
6
|
-
|
|
7
|
-
```ts
|
|
8
|
-
import { Acryl } from '@acryldev/blends'
|
|
9
|
-
import { secureHeaders } from '@acryldev/blends/secure-headers'
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
## Usage
|
|
13
|
-
|
|
14
|
-
You can use the optimal settings by default.
|
|
15
|
-
|
|
16
|
-
```ts
|
|
17
|
-
const app = new Acryl()
|
|
18
|
-
app.use(secureHeaders())
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
You can suppress unnecessary headers by setting them to false.
|
|
22
|
-
|
|
23
|
-
```ts
|
|
24
|
-
const app = new Acryl()
|
|
25
|
-
app.use(
|
|
26
|
-
'*',
|
|
27
|
-
secureHeaders({
|
|
28
|
-
xFrameOptions: false,
|
|
29
|
-
xXssProtection: false,
|
|
30
|
-
})
|
|
31
|
-
)
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
You can override default header values using a string.
|
|
35
|
-
|
|
36
|
-
```ts
|
|
37
|
-
const app = new Acryl()
|
|
38
|
-
app.use(
|
|
39
|
-
'*',
|
|
40
|
-
secureHeaders({
|
|
41
|
-
strictTransportSecurity:
|
|
42
|
-
'max-age=63072000; includeSubDomains; preload',
|
|
43
|
-
xFrameOptions: 'DENY',
|
|
44
|
-
xXssProtection: '1',
|
|
45
|
-
})
|
|
46
|
-
)
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
## Supported Options
|
|
50
|
-
|
|
51
|
-
Each option corresponds to the following Header Key-Value pairs.
|
|
52
|
-
|
|
53
|
-
| Option | Header | Value | Default |
|
|
54
|
-
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------- |
|
|
55
|
-
| - | X-Powered-By | (Delete Header) | True |
|
|
56
|
-
| contentSecurityPolicy | [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) | Usage: [Setting Content-Security-Policy](#setting-content-security-policy) | No Setting |
|
|
57
|
-
| contentSecurityPolicyReportOnly | [Content-Security-Policy-Report-Only](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy-Report-Only) | Usage: [Setting Content-Security-Policy](#setting-content-security-policy) | No Setting |
|
|
58
|
-
| trustedTypes | [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types) | Usage: [Setting Content-Security-Policy](#setting-content-security-policy) | No Setting |
|
|
59
|
-
| requireTrustedTypesFor | [Require Trusted Types For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-trusted-types-for) | Usage: [Setting Content-Security-Policy](#setting-content-security-policy) | No Setting |
|
|
60
|
-
| crossOriginEmbedderPolicy | [Cross-Origin-Embedder-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) | require-corp | **False** |
|
|
61
|
-
| crossOriginResourcePolicy | [Cross-Origin-Resource-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Resource-Policy) | same-origin | True |
|
|
62
|
-
| crossOriginOpenerPolicy | [Cross-Origin-Opener-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) | same-origin | True |
|
|
63
|
-
| originAgentCluster | [Origin-Agent-Cluster](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin-Agent-Cluster) | ?1 | True |
|
|
64
|
-
| referrerPolicy | [Referrer-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy) | no-referrer | True |
|
|
65
|
-
| reportingEndpoints | [Reporting-Endpoints](https://www.w3.org/TR/reporting-1/#header) | Usage: [Setting Content-Security-Policy](#setting-content-security-policy) | No Setting |
|
|
66
|
-
| reportTo | [Report-To](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-to) | Usage: [Setting Content-Security-Policy](#setting-content-security-policy) | No Setting |
|
|
67
|
-
| strictTransportSecurity | [Strict-Transport-Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) | max-age=15552000; includeSubDomains | True |
|
|
68
|
-
| xContentTypeOptions | [X-Content-Type-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options) | nosniff | True |
|
|
69
|
-
| xDnsPrefetchControl | [X-DNS-Prefetch-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control) | off | True |
|
|
70
|
-
| xDownloadOptions | [X-Download-Options](https://learn.microsoft.com/en-us/archive/blogs/ie/ie8-security-part-v-comprehensive-protection#mime-handling-force-save) | noopen | True |
|
|
71
|
-
| xFrameOptions | [X-Frame-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) | SAMEORIGIN | True |
|
|
72
|
-
| xPermittedCrossDomainPolicies | [X-Permitted-Cross-Domain-Policies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Permitted-Cross-Domain-Policies) | none | True |
|
|
73
|
-
| xXssProtection | [X-XSS-Protection](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection) | 0 | True |
|
|
74
|
-
| permissionPolicy | [Permissions-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy) | Usage: [Setting Permission-Policy](#setting-permission-policy) | No Setting |
|
|
75
|
-
|
|
76
|
-
## Middleware Conflict
|
|
77
|
-
|
|
78
|
-
Please be cautious about the order of specification when dealing with middleware that manipulates the same header.
|
|
79
|
-
|
|
80
|
-
In this case, Secure-headers operates and the `x-powered-by` is removed:
|
|
81
|
-
|
|
82
|
-
```ts
|
|
83
|
-
const app = new Acryl()
|
|
84
|
-
app.use(secureHeaders())
|
|
85
|
-
app.use(poweredBy())
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
In this case, Powered-By operates and the `x-powered-by` is added:
|
|
89
|
-
|
|
90
|
-
```ts
|
|
91
|
-
const app = new Acryl()
|
|
92
|
-
app.use(poweredBy())
|
|
93
|
-
app.use(secureHeaders())
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
## Setting Content-Security-Policy
|
|
97
|
-
|
|
98
|
-
```ts
|
|
99
|
-
const app = new Acryl()
|
|
100
|
-
app.use(
|
|
101
|
-
'/test',
|
|
102
|
-
secureHeaders({
|
|
103
|
-
reportingEndpoints: [
|
|
104
|
-
{
|
|
105
|
-
name: 'endpoint-1',
|
|
106
|
-
url: 'https://example.com/reports',
|
|
107
|
-
},
|
|
108
|
-
],
|
|
109
|
-
// -- or alternatively
|
|
110
|
-
// reportTo: [
|
|
111
|
-
// {
|
|
112
|
-
// group: 'endpoint-1',
|
|
113
|
-
// max_age: 10886400,
|
|
114
|
-
// endpoints: [{ url: 'https://example.com/reports' }],
|
|
115
|
-
// },
|
|
116
|
-
// ],
|
|
117
|
-
contentSecurityPolicy: {
|
|
118
|
-
defaultSrc: ["'self'"],
|
|
119
|
-
baseUri: ["'self'"],
|
|
120
|
-
childSrc: ["'self'"],
|
|
121
|
-
connectSrc: ["'self'"],
|
|
122
|
-
fontSrc: ["'self'", 'https:', 'data:'],
|
|
123
|
-
formAction: ["'self'"],
|
|
124
|
-
frameAncestors: ["'self'"],
|
|
125
|
-
frameSrc: ["'self'"],
|
|
126
|
-
imgSrc: ["'self'", 'data:'],
|
|
127
|
-
manifestSrc: ["'self'"],
|
|
128
|
-
mediaSrc: ["'self'"],
|
|
129
|
-
objectSrc: ["'none'"],
|
|
130
|
-
reportTo: 'endpoint-1',
|
|
131
|
-
reportUri: '/csp-report',
|
|
132
|
-
sandbox: ['allow-same-origin', 'allow-scripts'],
|
|
133
|
-
scriptSrc: ["'self'"],
|
|
134
|
-
scriptSrcAttr: ["'none'"],
|
|
135
|
-
scriptSrcElem: ["'self'"],
|
|
136
|
-
styleSrc: ["'self'", 'https:', "'unsafe-inline'"],
|
|
137
|
-
styleSrcAttr: ['none'],
|
|
138
|
-
styleSrcElem: ["'self'", 'https:', "'unsafe-inline'"],
|
|
139
|
-
upgradeInsecureRequests: [],
|
|
140
|
-
workerSrc: ["'self'"],
|
|
141
|
-
},
|
|
142
|
-
})
|
|
143
|
-
)
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
### `nonce` attribute
|
|
147
|
-
|
|
148
|
-
You can add a [`nonce` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) to a `script` or `style` element by adding the `NONCE` imported from `acrylblends/secure-headers` to a `scriptSrc` or `styleSrc`:
|
|
149
|
-
|
|
150
|
-
```tsx
|
|
151
|
-
import { secureHeaders, NONCE } from '@acryldev/blends/secure-headers'
|
|
152
|
-
import type { SecureHeadersVariables } from '@acryldev/blends/secure-headers'
|
|
153
|
-
|
|
154
|
-
// Specify the variable types to infer the `c.get('secureHeadersNonce')`:
|
|
155
|
-
type Variables = SecureHeadersVariables
|
|
156
|
-
|
|
157
|
-
const app = new Acryl<{ Variables: Variables }>()
|
|
158
|
-
|
|
159
|
-
// Set the pre-defined nonce value to `scriptSrc`:
|
|
160
|
-
app.get(
|
|
161
|
-
'*',
|
|
162
|
-
secureHeaders({
|
|
163
|
-
contentSecurityPolicy: {
|
|
164
|
-
scriptSrc: [NONCE, 'https://allowed1.example.com'],
|
|
165
|
-
},
|
|
166
|
-
})
|
|
167
|
-
)
|
|
168
|
-
|
|
169
|
-
// Get the value from `c.get('secureHeadersNonce')`:
|
|
170
|
-
app.get('/', (c) => {
|
|
171
|
-
return c.html(
|
|
172
|
-
<html>
|
|
173
|
-
<body>
|
|
174
|
-
{/** contents */}
|
|
175
|
-
<script
|
|
176
|
-
src='/js/client.js'
|
|
177
|
-
nonce={c.get('secureHeadersNonce')}
|
|
178
|
-
/>
|
|
179
|
-
</body>
|
|
180
|
-
</html>
|
|
181
|
-
)
|
|
182
|
-
})
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
If you want to generate the nonce value yourself, you can also specify a function as the following:
|
|
186
|
-
|
|
187
|
-
```tsx
|
|
188
|
-
const app = new Acryl<{
|
|
189
|
-
Variables: { myNonce: string }
|
|
190
|
-
}>()
|
|
191
|
-
|
|
192
|
-
const myNonceGenerator: ContentSecurityPolicyOptionHandler = (c) => {
|
|
193
|
-
// This function is called on every request.
|
|
194
|
-
const nonce = Math.random().toString(36).slice(2)
|
|
195
|
-
c.set('myNonce', nonce)
|
|
196
|
-
return `'nonce-${nonce}'`
|
|
197
|
-
}
|
|
198
|
-
|
|
199
|
-
app.get(
|
|
200
|
-
'*',
|
|
201
|
-
secureHeaders({
|
|
202
|
-
contentSecurityPolicy: {
|
|
203
|
-
scriptSrc: [myNonceGenerator, 'https://allowed1.example.com'],
|
|
204
|
-
},
|
|
205
|
-
})
|
|
206
|
-
)
|
|
207
|
-
|
|
208
|
-
app.get('/', (c) => {
|
|
209
|
-
return c.html(
|
|
210
|
-
<html>
|
|
211
|
-
<body>
|
|
212
|
-
{/** contents */}
|
|
213
|
-
<script src='/js/client.js' nonce={c.get('myNonce')} />
|
|
214
|
-
</body>
|
|
215
|
-
</html>
|
|
216
|
-
)
|
|
217
|
-
})
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
## Setting Permission-Policy
|
|
221
|
-
|
|
222
|
-
The Permission-Policy header allows you to control which features and APIs can be used in the browser. Here's an example of how to set it:
|
|
223
|
-
|
|
224
|
-
```ts
|
|
225
|
-
const app = new Acryl()
|
|
226
|
-
app.use(
|
|
227
|
-
'*',
|
|
228
|
-
secureHeaders({
|
|
229
|
-
permissionsPolicy: {
|
|
230
|
-
fullscreen: ['self'], // fullscreen=(self)
|
|
231
|
-
bluetooth: ['none'], // bluetooth=(none)
|
|
232
|
-
payment: ['self', 'https://example.com'], // payment=(self "https://example.com")
|
|
233
|
-
syncXhr: [], // sync-xhr=()
|
|
234
|
-
camera: false, // camera=none
|
|
235
|
-
microphone: true, // microphone=*
|
|
236
|
-
geolocation: ['*'], // geolocation=*
|
|
237
|
-
usb: ['self', 'https://a.example.com', 'https://b.example.com'], // usb=(self "https://a.example.com" "https://b.example.com")
|
|
238
|
-
accelerometer: ['https://*.example.com'], // accelerometer=("https://*.example.com")
|
|
239
|
-
gyroscope: ['src'], // gyroscope=(src)
|
|
240
|
-
magnetometer: [
|
|
241
|
-
'https://a.example.com',
|
|
242
|
-
'https://b.example.com',
|
|
243
|
-
], // magnetometer=("https://a.example.com" "https://b.example.com")
|
|
244
|
-
},
|
|
245
|
-
})
|
|
246
|
-
)
|
|
247
|
-
```
|