h3/dist/docs/1.utils/4.security.md

Minimal H(TTP) framework built for high performance and portability.

# Security

> H3 security utilities.

## Authentication

### `basicAuth(opts)`

Create a basic authentication middleware.

**Example:**

```ts
import { H3, serve, basicAuth } from "h3";
const auth = basicAuth({ password: "test" });
app.get("/", (event) => `Hello ${event.context.basicAuth?.username}!`, [auth]);
serve(app, { port: 3000 });
```

### `requireBasicAuth(event, opts)`

Apply basic authentication for current request.

**Example:**

```ts
import { defineHandler, requireBasicAuth } from "h3";
export default defineHandler(async (event) => {
  await requireBasicAuth(event, { password: "test" });
  return `Hello, ${event.context.basicAuth.username}!`;
});
```

## Session

### `clearSession(event, config)`

Clear the session data for the current request.

### `getSession(event, config)`

Get the session for the current request.

### `sealSession(event, config)`

Encrypt and sign the session data for the current request.

### `unsealSession(_event, config, sealed)`

Decrypt and verify the session data for the current request.

### `updateSession(event, config, update?)`

Update the session data for the current request.

### `useSession(event, config)`

Create a session manager for the current request.

## Fingerprint

### `getRequestFingerprint(event, opts)`

Get a unique fingerprint for the incoming request.

## CORS

### `appendCorsHeaders(event, options)`

Append CORS headers to the response.

### `appendCorsPreflightHeaders(event, options)`

Append CORS preflight headers to the response.

### `handleCors(event, options)`

Handle CORS for the incoming request.

If the incoming request is a CORS preflight request, it will append the CORS preflight headers and send a 204 response.

If return value is not `false`, the request is handled and no further action is needed.

**Example:**

```ts
const app = new H3();
app.all("/", async (event) => {
  const corsRes = handleCors(event, {
    origin: "*",
    preflight: {
      statusCode: 204,
    },
    methods: "*",
  });
  if (corsRes !== false) {
    return corsRes;
  }
  // Your code here
});
```

### `isCorsOriginAllowed(origin, options)`

Check if the origin is allowed.

### `isPreflightRequest(event)`

Check if the incoming request is a CORS preflight request.

## Path

### `resolveDotSegments(path, opts?)`

Resolve `.` and `..` segments in a path, without ever escaping above the root `/`. The result is always an absolute path with a single leading `/`, so it can never be protocol-relative (`//host`).

Also decodes percent-encoded dot segments at any `%25`-nesting depth (`%2e`, `%252e`, ...) and normalizes `\` to `/`, so encoded or backslash-based traversal (e.g. `%2e%2e/`, `..\..\`) is caught the same way as a literal `../`.

`%2f`/`%5c` (encoded path separators) are left untouched by default — see {@link ResolveDotSegmentsOptions.decodeSlashes}.

Only `.`/`..` resolution and the decodes above alter the string; every other percent-encoding (`%20`, non-ASCII, `%3A`, and any `%2e` not forming a whole segment) is left intact, so the result stays in the same representation as an un-decoded `event.url.pathname` and matches routes/rules consistently. Interior empty segments are preserved (`/a//b` stays `/a//b`, per WHATWG URL normalization) — only the leading slash is guaranteed single, so a consumer doing exact prefix matching should normalize its allowlist the same way.