Interface: AuthGateConfig

Options for the authGate plugin (all resolvable from env - see below).

Extends

BasePluginConfig.AuthStorageConfig

Indexable

[key: string]: unknown

Properties

allow?

optional allow?: string | string[]

Allow-list patterns (domain / glob / /regex/). Empty = allow nobody. Env TUNNEL_AUTH_ALLOW.

authorizeIdentity?

optional authorizeIdentity?: AuthorizeIdentity

Identity authorization independent of authentication. Defaults to the configured allow-list and is re-evaluated for every accepted session.

brandName?

optional brandName?: string

Display name used in the code email copy. Env TUNNEL_AUTH_BRAND_NAME.

Defaults to the brand context’s name - the app’s own branding/brand.yaml when it has one, else the dbx-tools default. Set this only to override the brand for this gate.

codeTtlSeconds?

optional codeTtlSeconds?: number

One-time-code lifetime (seconds). Env TUNNEL_AUTH_CODE_TTL. Default 600 (10m).

forwardHeaders?

optional forwardHeaders?: string | string[]

Extra x- request headers tunnel traffic may forward (literal / glob / /regex/), unioned with the built-in allow-list. Env TUNNEL_FORWARD_HEADERS.

gatePaths?

optional gatePaths?: string | string[]

Path prefixes to gate beyond the built-in /api/ (literal prefixes, comma- or space-separated as a string). For an app whose privileged surface is not under /api/ — e.g. a WebSocket at /ws — list those prefixes so they require a session too. Env TUNNEL_GATE_PATHS.

host?

optional host?: string

Inherited from

BasePluginConfig.host

insecure?

optional insecure?: boolean

Run OPEN with no gate (env TUNNEL_INSECURE=true). The login routes and gate middleware are not mounted, and the SMTP fail-fast is skipped. Use only when the tunnel is deliberately public.

logoutRedirectPath?

optional logoutRedirectPath?: string

Same-origin path returned after a successful logout. Env TUNNEL_AUTH_LOGOUT_REDIRECT. Defaults to /, where the AuthGate presents login again.

maxAttempts?

optional maxAttempts?: number

Max verify attempts per issued code. Default 5.

message?

optional message?: string

Line shown immediately above the code in the email. Env TUNNEL_AUTH_MESSAGE.

Keep the code on its OWN line directly after this text - that adjacency is what the platform code-detection heuristics key on.

name?

optional name?: string

Inherited from

BasePluginConfig.name

publicDomain?

optional publicDomain?: string

The public <subdomain>.<server> that identifies portr traffic by its Host header. Only requests whose Host matches this are gated; everything else (the platform front door, other local callers) passes through. Env TUNNEL_PUBLIC_DOMAIN. When absent, the gate is inert (nothing is tunnel traffic).

publicDomains?

optional publicDomains?: string | string[]

Additional public tunnel domains accepted by the gate.

sendCode?

optional sendCode?: (email, code, opts) => Promise<void>

Deliver a code to an address. Defaults to sending through the host app’s shared @dbx-tools/email transport (see ./send-code); override to wire a different delivery path.

Parameters

email

string

code

string

opts

SendCodeOptions

Returns

Promise<void>

sessionCutoff?

optional sessionCutoff?: string | number | Date

Force-clear cutoff: every session issued BEFORE it stops verifying, so moving it forward signs everyone out. Env TUNNEL_AUTH_SESSION_CUTOFF.

Anything object.toDate accepts: a Date, 2026-08-02, an ISO instant, epoch seconds/millis, or a relative duration (-30d, 7 days ago). Unset means no cutoff.

sessionTtlSeconds?

optional sessionTtlSeconds?: number

Session lifetime (seconds). Env TUNNEL_AUTH_SESSION_TTL. Default 2592000 (30d).

Matched to the cache-backed signing key’s own 30-day TTL (see ./signing-key.ts): the cookie and the key that validates it should expire together, or one silently outlives the other.

sqlitePath?

optional sqlitePath?: string

Inherited from

AuthStorageConfig.sqlitePath

storage?

optional storage?: AuthStorageMode

Inherited from

AuthStorageConfig.storage

subject?

optional subject?: string

Subject line for the code email. Env TUNNEL_AUTH_SUBJECT.

Defaults to “Your verification code”. The wording of the subject and message is deliberately the conventional phrasing rather than anything branded: iOS, Gmail, Outlook, and Android all detect a one-time code from this shape and offer to autofill it, and a novel phrasing is what breaks that detection.

This is the subject TEMPLATE, not the literal line sent: the code is spliced into it ("123456 is your verification code") because a push notification shows only the subject and preheader, and that notification is what mobile autofill reads. See codeEmailSubject in ./code-email.ts.

telemetry?

optional telemetry?: TelemetryOptions

Inherited from

BasePluginConfig.telemetry