Configuration

The server is configured entirely through environment variables. Copy .env.example to .env for local work; pnpm dev:server loads .env without overriding anything already set in your environment.

Server

Required in production

With NODE_ENV=production the server refuses to start unless all of these are set, and its error lists every missing one at once with what would have quietly stopped working. Outside production they are optional (a development server has no Clerk), and a server that has Clerk sign-in on but lacks the key or the webhook secret logs a warning at boot saying what that costs.

A forgotten NODE_ENV means none of this applies, so set it on every real deployment.

Scheduler and limits

Signing secrets

KMS calls use the standard AWS credential chain. Against LocalStack, any credentials work, but the AWS SDK refuses to start with none, so set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to anything.

Operator identity

Operator identity is a static token map: each token:name pair in FOLIOT_OPERATOR_TOKENS is one person, and every action they take is recorded against that name. A name may not begin with user: or app:: Foliot records those for a signed-in person and for an app’s own key, and refuses to start if an operator is named that way. Operator tokens and app API keys are unaffected by everything below.

An operator token must be an opaque random string. The server refuses to start if one has the shape of a JWT (three base64url parts, the first beginning eyJ), because that shape is how it tells a Clerk session token from every other credential.

Sign-in with Clerk

People sign in to Foliot Console through Clerk. The server verifies the Clerk session token the browser sends and learns who the person is, and nothing else: no organisation, role or metadata claim in the token is ever read to decide what they may do. That is decided from the server’s own tables.

Clerk is off by default. With no FOLIOT_CLERK_ISSUER, a Clerk token is just an unrecognised credential and is answered 401, exactly like any other.

The three are checked together at boot. Setting the origins or the key URL without an issuer, or an issuer without origins, stops the server rather than leaving sign-in silently off or too permissive. URLs must be https (plain http is accepted only for localhost and 127.0.0.1).

The Clerk webhook

A second, independent variable turns on the webhook that keeps people’s names and emails in step with their Clerk accounts and removes a deleted account (see Workspaces, members and Clerk). It does not depend on the sign-in settings above, and either can be on without the other.

A third variable lets Foliot call Clerk’s Backend API, so that invitations send email and a pending invitation can let a person in (see Managing members). Like the webhook, it is independent of sign-in.

The key is a secret. It lets the holder send email as your Clerk instance and read every user’s addresses, so it belongs in the server’s secret store and nowhere else, and it is never logged: printing the server’s configuration shows it as [redacted].

For a Clerk development instance such as https://your-instance.clerk.accounts.dev, the sign-in values are:

FOLIOT_CLERK_ISSUER=https://your-instance.clerk.accounts.dev
# Defaults to <issuer>/.well-known/jwks.json, which is
# https://your-instance.clerk.accounts.dev/.well-known/jwks.json
FOLIOT_CLERK_AUTHORIZED_PARTIES=http://localhost:4101

What the server checks on every token: an RS256 signature against the instance’s published keys (the algorithm is fixed, never read from the token), the issuer, the authorized party, expiry and not-before with five seconds of leeway, that the session is not pending, and that the subject is a Clerk user id.

• Keys are fetched on first use and refreshed after an hour. The refresh happens behind a request that still holds a cached key, so one failed attempt at the hour mark signs nobody out: the server keeps verifying with its cached keys while Clerk’s endpoint is down, for up to six hours since the last good fetch, and then refuses with 503 (not 401, which would send a client back through sign-in) until the endpoint answers again. A key Clerk has revoked stops verifying at the first refresh that succeeds; during an outage it stays usable for at most those six hours. A token signed with an unknown key id triggers a refetch, at most one every 30 seconds however many such tokens arrive, so a flood of junk tokens cannot be turned into traffic to Clerk. After a rotation, a token signed with the new key can therefore be refused for up to 30 seconds. Each fetch has a 5-second timeout and a 64 KiB body cap.
• A failed token is always the same 401 invalid token, whichever check failed; the reason is in the server log, never the token.
• A verified person with no row in the users table gets one, with no workspace memberships, so they see nothing until someone adds them. Their email and name are copied from the token only if the session token template includes them.
• What a person may do is decided on every request from their membership, read from the database each time and never cached: the app’s workspace, then their role in it. A viewer can read, an operator can also act on runs, workflows and step controls, and nothing about an app’s credentials or details is reachable by a person yet (those routes answer 403 whatever the role). An app in a workspace they are not in, an app with no workspace, and an app that does not exist all answer the same 404. An operator token and an app key are unaffected.