create-acrylblends 0.0.0-stage → 0.1.0

package/docs/framework/middleware/builtin/ip-restriction.md

@@ -0,0 +1,69 @@
+# IP Restriction Middleware
+
+IP Restriction Middleware is middleware that limits access to resources based on the IP address of the user.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { ipRestriction } from 'acrylblends/ip-restriction'
+```
+
+## Usage
+
+For your application running on Node.js, if you want to allow access only from local, you can write it as follows. Specify the rules you want to deny in the `denyList` and the rules you want to allow in the `allowList`.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getConnInfo } from 'acrylblends/node-server'
+import { ipRestriction } from 'acrylblends/ip-restriction'
+
+const app = new Acryl()
+
+app.use(
+  '*',
+  ipRestriction(getConnInfo, {
+    denyList: [],
+    allowList: ['127.0.0.1', '::1'],
+  })
+)
+
+app.get('/', (c) => c.text('Hello Acryl!'))
+```
+
+Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. For a runtime whose adapter is not yet available there is no `getConnInfo` to pass yet.
+
+## Rules
+
+Follow the instructions below for writing rules.
+
+### IPv4
+
+- `192.168.2.0` - Static IP Address
+- `192.168.2.0/24` - CIDR Notation
+- `*` - ALL Addresses
+
+### IPv6
+
+- `::1` - Static IP Address
+- `::1/10` - CIDR Notation
+- `*` - ALL Addresses
+
+## Error handling
+
+To customize the error, return a `Response` in the third argument.
+
+```ts
+app.use(
+  '*',
+  ipRestriction(
+    getConnInfo,
+    {
+      denyList: ['192.168.2.0/24'],
+    },
+    async (remote, c) => {
+      return c.text(`Blocking access from ${remote.addr}`, 403)
+    }
+  )
+)
+```

package/docs/framework/middleware/builtin/jsx-renderer.md

@@ -0,0 +1,286 @@
+# JSX Renderer Middleware
+
+> **Not yet available.** The JSX renderer middleware (`acrylblends/jsx-renderer`) is documented here so the page structure matches the rest of the framework, and is not part of acrylblends yet. The code on this page is not checked by the docs tests.
+
+
+JSX Renderer Middleware allows you to set up the layout when rendering JSX with the `c.render()` function, without the need for using `c.setRenderer()`. Additionally, it enables access to instances of Context within components through the use of `useRequestContext()`.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { jsxRenderer, useRequestContext } from 'acrylblends/jsx-renderer'
+```
+
+## Usage
+
+```jsx
+const app = new Acryl()
+
+app.get(
+  '/page/*',
+  jsxRenderer(({ children }) => {
+    return (
+      <html>
+        <body>
+          <header>Menu</header>
+          <div>{children}</div>
+        </body>
+      </html>
+    )
+  })
+)
+
+app.get('/page/about', (c) => {
+  return c.render(<h1>About me!</h1>)
+})
+```
+
+## Options
+
+### *(optional)* docType: `boolean` | `string`
+
+If you do not want to add a DOCTYPE at the beginning of the HTML, set the `docType` option to `false`.
+
+```tsx
+app.use(
+  '*',
+  jsxRenderer(
+    ({ children }) => {
+      return (
+        <html>
+          <body>{children}</body>
+        </html>
+      )
+    },
+    { docType: false }
+  )
+)
+```
+
+And you can specify the DOCTYPE.
+
+```tsx
+app.use(
+  '*',
+  jsxRenderer(
+    ({ children }) => {
+      return (
+        <html>
+          <body>{children}</body>
+        </html>
+      )
+    },
+    {
+      docType:
+        '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">',
+    }
+  )
+)
+```
+
+### *(optional)* stream: `boolean` | `Record<string, string>`
+
+If you set it to `true` or provide a Record value, it will be rendered as a streaming response.
+
+```tsx
+const AsyncComponent = async () => {
+  await new Promise((r) => setTimeout(r, 1000)) // sleep 1s
+  return <div>Hi!</div>
+}
+
+app.get(
+  '*',
+  jsxRenderer(
+    ({ children }) => {
+      return (
+        <html>
+          <body>
+            <h1>SSR Streaming</h1>
+            {children}
+          </body>
+        </html>
+      )
+    },
+    { stream: true }
+  )
+)
+
+app.get('/', (c) => {
+  return c.render(
+    <Suspense fallback={<div>loading...</div>}>
+      <AsyncComponent />
+    </Suspense>
+  )
+})
+```
+
+If `true` is set, the following headers are added:
+
+```ts
+{
+  'Transfer-Encoding': 'chunked',
+  'Content-Type': 'text/html; charset=UTF-8',
+  'Content-Encoding': 'Identity'
+}
+```
+
+You can customize the header values by specifying the Record values.
+
+### Function-based Options
+
+You can pass a function that receives a `Context` object instead of a static options object. This allows you to dynamically set options based on the request context, such as environment variables or request parameters.
+
+```tsx
+app.use(
+  '*',
+  jsxRenderer(
+    ({ children }) => {
+      return (
+        <html>
+          <body>{children}</body>
+        </html>
+      )
+    },
+    (c) => ({
+      stream: c.req.header('X-Enable-Streaming') === 'true',
+    })
+  )
+)
+```
+
+As a concrete example, you can use this to disable streaming when generating static sites (SSG) with `<Suspense>`, by using the [`isSSGContext`](../../helpers/ssg.md#isssgcontext) helper:
+
+```tsx
+app.use(
+  '*',
+  jsxRenderer(
+    ({ children }) => {
+      return (
+        <div>
+          <Suspense fallback={'loading...'}>
+            <Component />
+          </Suspense>
+        </div>
+      )
+    },
+    (c) => ({
+      stream: !isSSGContext(c),
+    })
+  )
+)
+```
+
+## Nested Layouts
+
+The `Layout` component enables nesting the layouts.
+
+```tsx
+app.use(
+  jsxRenderer(({ children }) => {
+    return (
+      <html>
+        <body>{children}</body>
+      </html>
+    )
+  })
+)
+
+const blog = new Acryl()
+blog.use(
+  jsxRenderer(({ children, Layout }) => {
+    return (
+      <Layout>
+        <nav>Blog Menu</nav>
+        <div>{children}</div>
+      </Layout>
+    )
+  })
+)
+
+app.route('/blog', blog)
+```
+
+## `useRequestContext()`
+
+`useRequestContext()` returns an instance of Context.
+
+```tsx
+import { useRequestContext, jsxRenderer } from 'acrylblends/jsx-renderer'
+
+const app = new Acryl()
+app.use(jsxRenderer())
+
+const RequestUrlBadge: FC = () => {
+  const c = useRequestContext()
+  return <b>{c.req.url}</b>
+}
+
+app.get('/page/info', (c) => {
+  return c.render(
+    <div>
+      You are accessing: <RequestUrlBadge />
+    </div>
+  )
+})
+```
+
+**Warning.**
+
+You can't use `useRequestContext()` with the Deno's `precompile` JSX option. Use the `react-jsx`:
+
+```json
+   "compilerOptions": {
+     "jsx": "react-jsx",
+     "jsxImportSource": "acrylblends/jsx"
+   }
+ }
+```
+
+## Extending `ContextRenderer`
+
+By defining `ContextRenderer` as shown below, you can pass additional content to the renderer. This is handy, for instance, when you want to change the contents of the head tag depending on the page.
+
+```tsx
+declare module 'acrylblends' {
+  interface ContextRenderer {
+    (
+      content: string | Promise<string>,
+      props: { title: string }
+    ): Response
+  }
+}
+
+const app = new Acryl()
+
+app.get(
+  '/page/*',
+  jsxRenderer(({ children, title }) => {
+    return (
+      <html>
+        <head>
+          <title>{title}</title>
+        </head>
+        <body>
+          <header>Menu</header>
+          <div>{children}</div>
+        </body>
+      </html>
+    )
+  })
+)
+
+app.get('/page/favorites', (c) => {
+  return c.render(
+    <div>
+      <ul>
+        <li>Eating sushi</li>
+        <li>Watching baseball games</li>
+      </ul>
+    </div>,
+    {
+      title: 'My favorites',
+    }
+  )
+})
+```

package/docs/framework/middleware/builtin/jwk.md

@@ -0,0 +1,192 @@
+# JWK Auth Middleware
+
+The JWK Auth Middleware authenticates requests by verifying tokens using JWK (JSON Web Key). It checks for an `Authorization` header and other configured sources, such as cookies, if specified. It validates tokens using the provided `keys`, retrieves keys from `jwks_uri` if specified, and supports token extraction from cookies if the `cookie` option is set.
+
+## What this middleware validates
+
+For each token, `jwk()`:
+
+- Parses and validates the JWT header format.
+- Requires a `kid` header and finds a matching key by `kid`.
+- Rejects symmetric algorithms (`HS256`, `HS384`, `HS512`).
+- Requires the header `alg` to be included in the configured `alg` allowlist.
+- If a matched JWK has an `alg` field, requires it to match the JWT header `alg`.
+- Verifies the token signature with the matched key.
+- By default, validates time-based claims: `nbf`, `exp`, and `iat`.
+
+Optional claim validation can be configured with the `verification` option:
+
+- `iss`: validates issuer when provided.
+- `aud`: validates audience when provided.
+
+If you need additional token checks beyond the above (for example, custom application-level authorization rules), add them in your own middleware after `jwk()`.
+
+> **Note.** The Authorization header sent from the client must have a specified scheme.
+>
+> Example: `Bearer my.token.value` or `Basic my.token.value`
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { jwk } from 'acrylblends/jwk'
+import { verifyWithJwks } from 'acrylblends/jwt'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+app.use(
+  '/auth/*',
+  jwk({
+    jwks_uri: `https://${backendServer}/.well-known/jwks.json`,
+    alg: ['RS256'],
+  })
+)
+
+app.get('/auth/page', (c) => {
+  return c.text('You are authorized')
+})
+```
+
+Get payload:
+
+```ts
+const app = new Acryl()
+
+app.use(
+  '/auth/*',
+  jwk({
+    jwks_uri: `https://${backendServer}/.well-known/jwks.json`,
+    alg: ['RS256'],
+  })
+)
+
+app.get('/auth/page', (c) => {
+  const payload = c.get('jwtPayload')
+  return c.json(payload) // eg: { "sub": "1234567890", "name": "John Doe", "iat": 1516239022 }
+})
+```
+
+Anonymous access:
+
+```ts
+const app = new Acryl()
+
+app.use(
+  '/auth/*',
+  jwk({
+    jwks_uri: (c) =>
+      `https://${c.env.authServer}/.well-known/jwks.json`,
+    alg: ['RS256'],
+    allow_anon: true,
+  })
+)
+
+app.get('/auth/page', (c) => {
+  const payload = c.get('jwtPayload')
+  return c.json(payload ?? { message: 'hello anon' })
+})
+```
+
+## Using `verifyWithJwks` outside of middleware
+
+The `verifyWithJwks` utility function can be used to verify JWT tokens outside of Acryl's middleware context, such as in SvelteKit SSR pages or other server-side environments:
+
+```ts
+const id_payload = await verifyWithJwks(
+  id_token,
+  {
+    jwks_uri: 'https://your-auth-server/.well-known/jwks.json',
+    allowedAlgorithms: ['RS256'],
+  },
+  {
+    cf: { cacheEverything: true, cacheTtl: 3600 },
+  }
+)
+```
+
+## Configuring JWKS fetch request options
+
+To configure how JWKS is retrieved from `jwks_uri`, pass fetch request options as the second argument of `jwk()`.
+
+This argument is `RequestInit` and is used only for the JWKS fetch request.
+
+```ts
+const app = new Acryl()
+
+app.use(
+  '/auth/*',
+  jwk(
+    {
+      jwks_uri: `https://${backendServer}/.well-known/jwks.json`,
+      alg: ['RS256'],
+    },
+    {
+      headers: {
+        Authorization: 'Bearer TOKEN',
+      },
+    }
+  )
+)
+```
+
+## Options
+
+### **(required)** alg: `AsymmetricAlgorithm[]`
+
+An array of allowed asymmetric algorithms used for token verification.
+
+Available types are `RS256` | `RS384` | `RS512` | `PS256` | `PS384` | `PS512` | `ES256` | `ES384` | `ES512` | `EdDSA`.
+
+### *(optional)* keys: `AcrylJsonWebKey[] | (c: Context) => Promise<AcrylJsonWebKey[]>`
+
+The values of your public keys, or a function that returns them. The function receives the Context object.
+
+### *(optional)* jwks_uri: `string` | `(c: Context) => Promise<string>`
+
+If this value is set, attempt to fetch JWKs from this URI, expecting a JSON response with `keys`, which are added to the provided `keys` option. You can also pass a callback function to dynamically determine the JWKS URI using the Context.
+
+### *(optional)* allow_anon: `boolean`
+
+If this value is set to `true`, requests without a valid token will be allowed to pass through the middleware. Use `c.get('jwtPayload')` to check if the request is authenticated. The default is `false`.
+
+### *(optional)* cookie: `string`
+
+If this value is set, then the value is retrieved from the cookie header using that value as a key, which is then validated as a token.
+
+### *(optional)* headerName: `string`
+
+The name of the header to look for the JWT token. The default is `Authorization`.
+
+### *(optional)* realm: `string`
+
+The protection space described by the `realm` parameter of the `WWW-Authenticate` challenge header returned on `401` responses. The default is the request URL.
+
+### *(optional)* verification: `VerifyOptions`
+
+Configure claim validation behavior in addition to signature verification:
+
+[Keep in sync with jwt.md]: #
+
+#### *(optional)* VerifyOptions.iss: `string | RegExp`
+
+The expected issuer used for token verification. The `iss` claim will **not** be checked if this isn't set.
+
+#### *(optional)* VerifyOptions.aud: `string | string[] | RegExp`
+
+The expected audience used for token verification. If this is set, the token must include an `aud` claim and at least one audience value must match.
+
+#### *(optional)* VerifyOptions.nbf: `boolean`
+
+The `nbf` (not before) claim will be verified if present and this is set to `true`. The default is `true`.
+
+#### *(optional)* VerifyOptions.iat: `boolean`
+
+The `iat` (issued at) claim will be verified if present and this is set to `true`. The default is `true`.
+
+#### *(optional)* VerifyOptions.exp: `boolean`
+
+The `exp` (expiration time) claim will be verified if present and this is set to `true`. The default is `true`.

package/docs/framework/middleware/builtin/jwt.md

@@ -0,0 +1,145 @@
+# JWT Auth Middleware
+
+The JWT Auth Middleware provides authentication by verifying the token with JWT.
+The middleware will check for an `Authorization` header if the `cookie` option is not set. You can customize the header name using the `headerName` option.
+
+> **Note.** The Authorization header sent from the client must have a specified scheme.
+>
+> Example: `Bearer my.token.value` or `Basic my.token.value`
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { jwt } from 'acrylblends/jwt'
+import type { JwtVariables } from 'acrylblends/jwt'
+```
+
+## Usage
+
+```ts
+// Specify the variable types to infer the `c.get('jwtPayload')`:
+type Variables = JwtVariables
+
+const app = new Acryl<{ Variables: Variables }>()
+
+app.use(
+  '/auth/*',
+  jwt({
+    secret: process.env.JWT_SECRET!,
+    alg: 'HS256',
+  })
+)
+
+app.get('/auth/page', (c) => {
+  return c.text('You are authorized')
+})
+```
+
+Get payload:
+
+```ts
+const app = new Acryl()
+
+app.use(
+  '/auth/*',
+  jwt({
+    secret: process.env.JWT_SECRET!,
+    alg: 'HS256',
+    verification: {
+      iss: 'my-trusted-issuer',
+      aud: 'my-api',
+    },
+  })
+)
+
+app.get('/auth/page', (c) => {
+  const payload = c.get('jwtPayload')
+  return c.json(payload) // eg: { "sub": "1234567890", "name": "John Doe", "iat": 1516239022, "iss": "my-trusted-issuer" }
+})
+```
+
+**Tip.**
+
+`jwt()` is just a middleware function. If you want to use an environment variable (eg: `c.env.JWT_SECRET`), you can use it as follows:
+
+```js
+app.use('/auth/*', (c, next) => {
+  const jwtMiddleware = jwt({
+    secret: c.env.JWT_SECRET,
+    alg: 'HS256',
+  })
+  return jwtMiddleware(c, next)
+})
+```
+
+## Options
+
+### **(required)** secret: `string`
+
+A value of your secret key.
+
+### **(required)** alg: `string`
+
+An algorithm type that is used for verifying.
+
+Available types are `HS256` | `HS384` | `HS512` | `RS256` | `RS384` | `RS512` | `PS256` | `PS384` | `PS512` | `ES256` | `ES384` | `ES512` | `EdDSA`.
+
+### *(optional)* cookie: `string`
+
+If this value is set, then the value is retrieved from the cookie header using that value as a key, which is then validated as a token.
+
+### *(optional)* headerName: `string`
+
+The name of the header to look for the JWT token. The default is `Authorization`.
+
+```ts
+app.use(
+  '/auth/*',
+  jwt({
+    secret: process.env.JWT_SECRET!,
+    alg: 'HS256',
+    headerName: 'x-custom-auth-header',
+  })
+)
+```
+
+### *(optional)* realm: `string`
+
+The protection space described by the `realm` parameter of the `WWW-Authenticate` challenge header returned on `401` responses. The default is the request URL.
+
+```ts
+app.use(
+  '/auth/*',
+  jwt({
+    secret: process.env.JWT_SECRET!,
+    realm: 'my-protected-api',
+  })
+)
+```
+
+### *(optional)* verification: `VerifyOptions`
+
+Options controlling verification of the token.
+
+[Keep in sync with jwk.md]: #
+
+#### *(optional)* VerifyOptions.iss: `string | RegExp`
+
+The expected issuer used for token verification. The `iss` claim will **not** be checked if this isn't set.
+
+#### *(optional)* VerifyOptions.aud: `string | string[] | RegExp`
+
+The expected audience used for token verification. If this is set, the token must include an `aud` claim and at least one audience value must match.
+
+#### *(optional)* VerifyOptions.nbf: `boolean`
+
+The `nbf` (not before) claim will be verified if present and this is set to `true`. The default is `true`.
+
+#### *(optional)* VerifyOptions.iat: `boolean`
+
+The `iat` (issued at) claim will be verified if present and this is set to `true`. The default is `true`.
+
+#### *(optional)* VerifyOptions.exp: `boolean`
+
+The `exp` (expiration time) claim will be verified if present and this is set to `true`. The default is `true`.