Basic Auth

@point0/basic-auth is an HTTP Basic auth gate. basicAuth(options) returns a Point0 middleware function: give it a user table, mount it on a point, and every request without valid username:password credentials gets a 401. It runs server-side only and adds per-user / per-IP brute-force throttling.

The most direct use is to close your whole site off — a staging deploy, a private preview, an internal tool. Mount it on root and the browser pops its native login dialog before anyone reaches a single page:

import { basicAuth } from '@point0/basic-auth'

export const root = Point0.lets
  .root()
  // ...
  // every request under root needs admin:secret first
  .middleware(basicAuth({ users: { admin: 'secret' } }))
  .root()

No page knows or cares it's there.

Mounting it

basicAuth(...) is a plain Point0 middleware, so it goes wherever .middleware goes. Three useful placements:

Guard everything on a point. Pass it straight to .middleware() and it gates every request reaching that point's scope — this is the whole-site gate from above:

// guards every request under root
.middleware(basicAuth({ users: { admin: 'secret' } }))

Guard one path. .middleware also takes a route, so you can scope the gate to a subtree — e.g. an /admin/* area while the rest of the site stays open:

.middleware('/admin/*', basicAuth({ users: { admin: 'secret' } }))

Guard the OpenAPI docs. Pass it as the before option of openapi(...), which runs it only on the doc routes. This is how every shipped example uses it:

import { openapi } from '@point0/openapi'

// examples/basic/src/lib/root.tsx
.middleware(
  openapi({
    route: '/openapi.json',
    scalar: '/scalar',
    swagger: '/swagger',
    filter: 'all',
    before: basicAuth({ users: { admin: 'admin' } }), // ← the gate
  }),
)

Now /openapi.json, /scalar, and /swagger prompt for a login; anything else stays open.

basicAuth is a no-op on the client — middleware runs server-side only, and the compiler strips server middleware bodies out of the client bundle.

The user table: users

users is the built-in credential check. It accepts three shapes, all normalized to a { username: password } record:

basicAuth({ users: { admin: 'secret', john: 'pass123' } }) // record
basicAuth({ users: 'admin:secret' }) //                       single "user:pass" string
basicAuth({ users: ['admin:secret', 'john:pass123'] }) //     list of "user:pass" strings

Use the string form in production — keep the credentials in an env var, not in source. This is what create-point0-app scaffolds and what Start0 ships:

// packages/create-app/template/src/lib/root.tsx
before: basicAuth({ users: serverEnv.OPENAPI_CREDENTIALS }) // e.g. "admin:admin"

A "user:pass" string splits on the first :, so the password may itself contain colons. An empty username or empty password (':pass', 'user:', or a string with no :) throws at config time — when basicAuth(...) is called, not per request:

basicAuth({ users: 'admin:' }) // throws: Invalid user string format. Expected "username:password".

Passwords are compared as plaintext with strict ===, guarded by hasOwnProperty (so prototype keys like toString can't be used as a login). There's no hashing — for hashed passwords or a database lookup, use validator below.

A custom check: validator

Pass a validator function instead of users to replace the built-in table entirely. It receives the parsed credentials plus the full request, returns a boolean, and may be async:

basicAuth({
  validator: async ({ username, password, request }) => {
    const user = await db.user.findUnique({ where: { username } })
    return !!user && (await verifyHash(password, user.passwordHash))
  },
})

users and validator are mutually exclusive — pass exactly one. The type is a discriminated union, so passing both (or neither) is a compile error.

Hooks: logging failures

Three optional callbacks fire on each failure path, before the failure response is built — for logging or metrics. They may be async (and are awaited) but can't change the response:

basicAuth({
  users: { admin: 'secret' },
  onUnauthorized: ({ ip }) => console.warn('no credentials', { ip }),
  onWrongCredentials: ({ username, ip }) =>
    console.warn('bad credentials', { username, ip }),
  onLimitExceeded: ({ username, ip }) =>
    console.error('throttled', { username, ip }),
})

onLimitExceeded also receives limitPerUser, limitPerIp, and staleTimeMs. All three receive { request, username, ip } (username/ip may be undefined).

The responses

The gate produces three outcomes, each a real HTTP response:

The WWW-Authenticate header is the constant Basic realm="Restricted", charset="UTF-8" — it's what makes a browser pop its native login dialog. The realm is fixed to "Restricted" and the charset to UTF-8; there is no option to change either.

The Basic scheme is matched case-insensitively, so Basic, basic, and BASIC all parse.

challenge: false — suppress the browser dialog

Set challenge: false to drop the WWW-Authenticate header from 401s — useful for an API where you handle the 401 in your own client and don't want a browser prompt:

basicAuth({ users: { admin: 'secret' }, challenge: false }) // 401s carry no WWW-Authenticate

The 429 never carries the challenge header, even with challenge: true.

Brute-force throttling

Every failed credential attempt (a valid Basic header with a wrong username/password) is recorded in memory as { dateMs, username, ip }. Requests with no or malformed header are not counted toward the throttle. Once a client crosses a limit, further attempts return 429 instead of 401:

basicAuth({
  users: { admin: 'secret' },
  limitPerUser: 100, //              max failures per username (default 100)
  limitPerIp: 100, //                max failures per IP       (default 100)
  staleTimeMs: 1000 * 60 * 60 * 24, // failures older than this are forgotten (default 24h)
  memorySize: 1000, //               hard cap on remembered attempts (default 1000)
})

The limit trips when either the per-user or the per-IP count is reached (they're OR-combined). A successful login clears every recorded failure matching that IP or that username — so a login from one user can also wipe another user's recorded failures that share the same IP. The IP comes from request.from.ip (Bun's trusted source first, then x-forwarded-for / x-real-ip / cf-connecting-ip); requests with no resolvable IP all share one 'unknown' bucket.

Gotcha — the memory is in-process and volatile. It resets on restart and is per-instance. Across multiple server processes, the limit counts per process, not globally. There's no shared / persistent store option.

Advanced API

basicAuth(options) is the high-level factory. The package also exposes a lower-level surface:

• BasicAuth.create(options) — the class behind the factory (the constructor is private). Its .middleware getter is exactly what basicAuth() returns. validateRequest and getFailureResponse are methods on a BasicAuth instance, not separate top-level exports.
• instance.validateRequest(request) — returns the full BasicAuthValidationResult ({ ok, username, ip, response, reason } on failure) instead of acting as middleware.
• instance.getFailureResponse(request) — returns the failure Response, or undefined when the request is authorized. For gating by hand, outside .middleware().
• getBasicAuthHeader(username, password) — a top-level export that builds a Basic <base64> header value, for crafting authenticated requests in tests.

Reference

basicAuth(options)

Exactly one of users / validator is required; everything else is optional.

Behavior at a glance