@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.
Files changed (98) hide show
  1. package/{docs/framework/LICENSE → LICENSE} +1 -3
  2. package/package.json +2 -2
  3. package/docs/framework/README.md +0 -70
  4. package/docs/framework/agents/index.md +0 -59
  5. package/docs/framework/api/acryl.md +0 -247
  6. package/docs/framework/api/context.md +0 -478
  7. package/docs/framework/api/exception.md +0 -80
  8. package/docs/framework/api/index.md +0 -12
  9. package/docs/framework/api/presets.md +0 -62
  10. package/docs/framework/api/request.md +0 -396
  11. package/docs/framework/api/routing.md +0 -303
  12. package/docs/framework/api/summary.md +0 -143
  13. package/docs/framework/concepts/benchmarks.md +0 -26
  14. package/docs/framework/concepts/developer-experience.md +0 -5
  15. package/docs/framework/concepts/middleware.md +0 -21
  16. package/docs/framework/concepts/motivation.md +0 -14
  17. package/docs/framework/concepts/routers.md +0 -63
  18. package/docs/framework/concepts/stacks.md +0 -235
  19. package/docs/framework/concepts/web-standard.md +0 -27
  20. package/docs/framework/cordis/acryl-in-a-cordis-app.md +0 -160
  21. package/docs/framework/cordis/concepts.md +0 -105
  22. package/docs/framework/cordis/middleware.md +0 -8
  23. package/docs/framework/cordis/migration-from-0-3.md +0 -111
  24. package/docs/framework/cordis/migration-from-0-4.md +0 -14
  25. package/docs/framework/cordis/migration-from-dsh-webserver.md +0 -109
  26. package/docs/framework/cordis/migration-to-1-0.md +0 -46
  27. package/docs/framework/cordis/mounting.md +0 -85
  28. package/docs/framework/cordis/node-server.md +0 -100
  29. package/docs/framework/cordis/plugin-lifecycle.md +0 -111
  30. package/docs/framework/cordis/surfaces.md +0 -71
  31. package/docs/framework/cordis/transport-and-cancellation.md +0 -57
  32. package/docs/framework/cordis/validation.md +0 -135
  33. package/docs/framework/getting-started/basic.md +0 -201
  34. package/docs/framework/getting-started/bun.md +0 -219
  35. package/docs/framework/getting-started/deploy.md +0 -133
  36. package/docs/framework/getting-started/desktop.md +0 -80
  37. package/docs/framework/getting-started/nodejs.md +0 -365
  38. package/docs/framework/getting-started/other-runtimes.md +0 -30
  39. package/docs/framework/guides/best-practices.md +0 -231
  40. package/docs/framework/guides/bring-your-own-tool.md +0 -218
  41. package/docs/framework/guides/client-modules.md +0 -210
  42. package/docs/framework/guides/create-acrylblends.md +0 -143
  43. package/docs/framework/guides/data.md +0 -314
  44. package/docs/framework/guides/examples.md +0 -3
  45. package/docs/framework/guides/faq.md +0 -19
  46. package/docs/framework/guides/forms-and-sessions.md +0 -235
  47. package/docs/framework/guides/helpers.md +0 -33
  48. package/docs/framework/guides/jsx-dom.md +0 -301
  49. package/docs/framework/guides/jsx.md +0 -487
  50. package/docs/framework/guides/middleware.md +0 -253
  51. package/docs/framework/guides/production.md +0 -80
  52. package/docs/framework/guides/rpc.md +0 -878
  53. package/docs/framework/guides/testing.md +0 -133
  54. package/docs/framework/guides/validation.md +0 -470
  55. package/docs/framework/helpers/accepts.md +0 -60
  56. package/docs/framework/helpers/adapter.md +0 -57
  57. package/docs/framework/helpers/conninfo.md +0 -77
  58. package/docs/framework/helpers/cookie.md +0 -232
  59. package/docs/framework/helpers/css.md +0 -282
  60. package/docs/framework/helpers/dev.md +0 -64
  61. package/docs/framework/helpers/factory.md +0 -180
  62. package/docs/framework/helpers/html.md +0 -123
  63. package/docs/framework/helpers/jwt.md +0 -184
  64. package/docs/framework/helpers/proxy.md +0 -115
  65. package/docs/framework/helpers/route.md +0 -143
  66. package/docs/framework/helpers/ssg.md +0 -390
  67. package/docs/framework/helpers/streaming.md +0 -224
  68. package/docs/framework/helpers/testing.md +0 -118
  69. package/docs/framework/helpers/websocket.md +0 -208
  70. package/docs/framework/middleware/builtin/basic-auth.md +0 -165
  71. package/docs/framework/middleware/builtin/bearer-auth.md +0 -138
  72. package/docs/framework/middleware/builtin/body-limit.md +0 -71
  73. package/docs/framework/middleware/builtin/cache.md +0 -99
  74. package/docs/framework/middleware/builtin/combine.md +0 -94
  75. package/docs/framework/middleware/builtin/compress.md +0 -59
  76. package/docs/framework/middleware/builtin/context-storage.md +0 -74
  77. package/docs/framework/middleware/builtin/cors.md +0 -134
  78. package/docs/framework/middleware/builtin/csrf.md +0 -105
  79. package/docs/framework/middleware/builtin/etag.md +0 -54
  80. package/docs/framework/middleware/builtin/ip-restriction.md +0 -69
  81. package/docs/framework/middleware/builtin/jsx-renderer.md +0 -283
  82. package/docs/framework/middleware/builtin/jwk.md +0 -192
  83. package/docs/framework/middleware/builtin/jwt.md +0 -145
  84. package/docs/framework/middleware/builtin/language.md +0 -232
  85. package/docs/framework/middleware/builtin/logger.md +0 -74
  86. package/docs/framework/middleware/builtin/loopback-only.md +0 -31
  87. package/docs/framework/middleware/builtin/method-not-allowed.md +0 -48
  88. package/docs/framework/middleware/builtin/method-override.md +0 -80
  89. package/docs/framework/middleware/builtin/mount.md +0 -103
  90. package/docs/framework/middleware/builtin/pretty-json.md +0 -53
  91. package/docs/framework/middleware/builtin/request-id.md +0 -87
  92. package/docs/framework/middleware/builtin/secure-headers.md +0 -247
  93. package/docs/framework/middleware/builtin/timeout.md +0 -98
  94. package/docs/framework/middleware/builtin/timing.md +0 -100
  95. package/docs/framework/middleware/builtin/trailing-slash.md +0 -74
  96. package/docs/framework/middleware/third-party.md +0 -4
  97. package/docs/framework/workshop/README.md +0 -294
  98. 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
- ```