owltide/docs/admin/config.md

<!--
	SPDX-FileCopyrightText: © 2025 Hornwitser <code@hornwitser.no>
	SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Configuration

## Quoting

Environment variables are parsed using [destr](https://github.com/unjs/destr) which contain arbitrary unspecified and undocumented rules for converting strings to data. If an environment input looks like JSON it'll most likely be parsed as JSON and my cause a type missmatch error to be reported. To avoid strings being converted into other unintended values put the value into `"` marks. Depending on your configuration environment you may have to double up the quotation marks and/or use escapes.

## Environment Variables

### NUXT_SESSION_ROTATES_TIMEOUT

Time in seconds before a session need to be rotated over into a new session. When an endpoint using a session is hit after the session rotates timeout but before the session is discarded a new session is created as the successor with a new rotates and discard timeout. The old session then marked to expire in 10 seconds any requests using the old session will result in a 403 Forbidden with the message the session has been taken after the expiry.

### NUXT_SESSION_DISCARD_TIMEOUT

Time in seconds before a session is deleted from the client and server, resulting in the user having to authenticate again if the session wasn't rotated over into a new session before this timeout.

This should be several times greater that `NUXT_SESSION_ROTATES_TIMEOUT`.

### NUXT_PUBLIC_AUTH_DEMO_ENABLED

Boolean indicating if the demo authentication provider should be enabled. This allows logging in using only a name with no additional checks or security and should _never_ be enabled on a production system. The purpose of this is to make it easier to demo the system.

Defaults to `false`.

### NUXT_TELEGRAM_BOT_TOKEN_FILE

Path to a file containing the token for the Telegram bot used for authenticating users via Telegram.

Does nothing if `NUXT_PUBLIC_AUTH_TELEGRAM_ENABLED` is not enabled.

### NUXT_PUBLIC_TELEGRAM_BOT_USERNAME

Username of the Telegram bot used for authenticating users via Telegram.

Does nothing if `NUXT_PUBLIC_AUTH_TELEGRAM_ENABLED` is not enabled.

### NUXT_PUBLIC_AUTH_TELEGRAM_ENABLED

Boolean indicating if authentication via Telegram is enabled or not. Requires `NUXT_PUBLIC_TELEGRAM_BOT_USERNAME` and `NUXT_TELEGRAM_BOT_TOKEN_FILE` to be set in order to work.

Defaults to `false`.
Refactor sessions to frequently rotate In order to minimise the window of opportunity to steal a session, automatically rotate it onto a new session on a frequent basis. This makes a session cookie older than the automatic rollover time less likely to grant access and more likely to be detected. Should a stolen session cookie get rotated while the attacker is using it, the user will be notificed that their session has been taken the next time they open the app if the user re-visits the website before the session is discarded. 2025-07-07 22:42:49 +02:00			`<!--`
			`SPDX-FileCopyrightText: © 2025 Hornwitser <code@hornwitser.no>`
			`SPDX-License-Identifier: AGPL-3.0-or-later`
			`-->`
			`# Configuration`

Add note about quoting in configuration guide The way Nuxt handles environment variables is weird. Document this to help others from not falling into its pitfalls. 2025-07-09 14:59:19 +02:00			`## Quoting`

			Environment variables are parsed using [destr](https://github.com/unjs/destr) which contain arbitrary unspecified and undocumented rules for converting strings to data. If an environment input looks like JSON it'll most likely be parsed as JSON and my cause a type missmatch error to be reported. To avoid strings being converted into other unintended values put the value into `"` marks. Depending on your configuration environment you may have to double up the quotation marks and/or use escapes.

Refactor sessions to frequently rotate In order to minimise the window of opportunity to steal a session, automatically rotate it onto a new session on a frequent basis. This makes a session cookie older than the automatic rollover time less likely to grant access and more likely to be detected. Should a stolen session cookie get rotated while the attacker is using it, the user will be notificed that their session has been taken the next time they open the app if the user re-visits the website before the session is discarded. 2025-07-07 22:42:49 +02:00			`## Environment Variables`

Separate rotation and expiry of sessions If a session is rotate in the middle of a server side rendering then some random portions of requests made on the server side will fail with a session taken error as the server is not going to update the cookies of the client during these requests. To avoid this pitfall extend the expiry time of sessions to be 10 seconds after the session has been rotated. This is accomplished by introducing a new timestamp on sessions called the rotateAt at time alongside the expiresAt time. Sessions used after rotateAt that haven't been rotated get rotated into a new session and the existing session gets the expiresAt time set to 10 seconds in the future. Sessions that are past the expiredAt time have no access. This makes the logic around session expiry simpler, and also makes it possible to audit when a session got rotated, and to mark sessions as expired without a chance to rotate to a new session without having to resort to a finished flag. 2025-07-09 14:54:54 +02:00			`### NUXT_SESSION_ROTATES_TIMEOUT`
Refactor sessions to frequently rotate In order to minimise the window of opportunity to steal a session, automatically rotate it onto a new session on a frequent basis. This makes a session cookie older than the automatic rollover time less likely to grant access and more likely to be detected. Should a stolen session cookie get rotated while the attacker is using it, the user will be notificed that their session has been taken the next time they open the app if the user re-visits the website before the session is discarded. 2025-07-07 22:42:49 +02:00
Separate rotation and expiry of sessions If a session is rotate in the middle of a server side rendering then some random portions of requests made on the server side will fail with a session taken error as the server is not going to update the cookies of the client during these requests. To avoid this pitfall extend the expiry time of sessions to be 10 seconds after the session has been rotated. This is accomplished by introducing a new timestamp on sessions called the rotateAt at time alongside the expiresAt time. Sessions used after rotateAt that haven't been rotated get rotated into a new session and the existing session gets the expiresAt time set to 10 seconds in the future. Sessions that are past the expiredAt time have no access. This makes the logic around session expiry simpler, and also makes it possible to audit when a session got rotated, and to mark sessions as expired without a chance to rotate to a new session without having to resort to a finished flag. 2025-07-09 14:54:54 +02:00			`Time in seconds before a session need to be rotated over into a new session. When an endpoint using a session is hit after the session rotates timeout but before the session is discarded a new session is created as the successor with a new rotates and discard timeout. The old session then marked to expire in 10 seconds any requests using the old session will result in a 403 Forbidden with the message the session has been taken after the expiry.`
Refactor sessions to frequently rotate In order to minimise the window of opportunity to steal a session, automatically rotate it onto a new session on a frequent basis. This makes a session cookie older than the automatic rollover time less likely to grant access and more likely to be detected. Should a stolen session cookie get rotated while the attacker is using it, the user will be notificed that their session has been taken the next time they open the app if the user re-visits the website before the session is discarded. 2025-07-07 22:42:49 +02:00
			`### NUXT_SESSION_DISCARD_TIMEOUT`

			`Time in seconds before a session is deleted from the client and server, resulting in the user having to authenticate again if the session wasn't rotated over into a new session before this timeout.`

Separate rotation and expiry of sessions If a session is rotate in the middle of a server side rendering then some random portions of requests made on the server side will fail with a session taken error as the server is not going to update the cookies of the client during these requests. To avoid this pitfall extend the expiry time of sessions to be 10 seconds after the session has been rotated. This is accomplished by introducing a new timestamp on sessions called the rotateAt at time alongside the expiresAt time. Sessions used after rotateAt that haven't been rotated get rotated into a new session and the existing session gets the expiresAt time set to 10 seconds in the future. Sessions that are past the expiredAt time have no access. This makes the logic around session expiry simpler, and also makes it possible to audit when a session got rotated, and to mark sessions as expired without a chance to rotate to a new session without having to resort to a finished flag. 2025-07-09 14:54:54 +02:00			This should be several times greater that `NUXT_SESSION_ROTATES_TIMEOUT`.
Implement register and login with Telegram Add the concept of authentication methods that authenticate an account where using the telegram login widget is one such method. If a login is done with an authentication method that's not associated with any account the session ends up with the data from the authentication method in order to allow registering a new account with the authentication method. This has to be stored on the session as otherwise it wouldn't be possible to implement authentication methods such as OAuth2 that takes the user to a third-party site and then redirects the browser back. 2025-07-09 15:21:39 +02:00
Fix AUTH variables missing PUBLIC prefix in docs 2025-07-09 19:26:38 +02:00			`### NUXT_PUBLIC_AUTH_DEMO_ENABLED`
Refactor demo login as an authentication method Use the authentication method system for the demo login and the generated accounts. This makes it possible to toggle it off on production systems as these shouldn't have it enabled at all. 2025-07-09 17:57:49 +02:00
			`Boolean indicating if the demo authentication provider should be enabled. This allows logging in using only a name with no additional checks or security and should _never_ be enabled on a production system. The purpose of this is to make it easier to demo the system.`

			Defaults to `false`.

Implement register and login with Telegram Add the concept of authentication methods that authenticate an account where using the telegram login widget is one such method. If a login is done with an authentication method that's not associated with any account the session ends up with the data from the authentication method in order to allow registering a new account with the authentication method. This has to be stored on the session as otherwise it wouldn't be possible to implement authentication methods such as OAuth2 that takes the user to a third-party site and then redirects the browser back. 2025-07-09 15:21:39 +02:00			`### NUXT_TELEGRAM_BOT_TOKEN_FILE`

			`Path to a file containing the token for the Telegram bot used for authenticating users via Telegram.`

Fix AUTH variables missing PUBLIC prefix in docs 2025-07-09 19:26:38 +02:00			Does nothing if `NUXT_PUBLIC_AUTH_TELEGRAM_ENABLED` is not enabled.
Implement register and login with Telegram Add the concept of authentication methods that authenticate an account where using the telegram login widget is one such method. If a login is done with an authentication method that's not associated with any account the session ends up with the data from the authentication method in order to allow registering a new account with the authentication method. This has to be stored on the session as otherwise it wouldn't be possible to implement authentication methods such as OAuth2 that takes the user to a third-party site and then redirects the browser back. 2025-07-09 15:21:39 +02:00
			`### NUXT_PUBLIC_TELEGRAM_BOT_USERNAME`

			`Username of the Telegram bot used for authenticating users via Telegram.`

Fix AUTH variables missing PUBLIC prefix in docs 2025-07-09 19:26:38 +02:00			Does nothing if `NUXT_PUBLIC_AUTH_TELEGRAM_ENABLED` is not enabled.
Implement register and login with Telegram Add the concept of authentication methods that authenticate an account where using the telegram login widget is one such method. If a login is done with an authentication method that's not associated with any account the session ends up with the data from the authentication method in order to allow registering a new account with the authentication method. This has to be stored on the session as otherwise it wouldn't be possible to implement authentication methods such as OAuth2 that takes the user to a third-party site and then redirects the browser back. 2025-07-09 15:21:39 +02:00
Fix AUTH variables missing PUBLIC prefix in docs 2025-07-09 19:26:38 +02:00			`### NUXT_PUBLIC_AUTH_TELEGRAM_ENABLED`
Implement register and login with Telegram Add the concept of authentication methods that authenticate an account where using the telegram login widget is one such method. If a login is done with an authentication method that's not associated with any account the session ends up with the data from the authentication method in order to allow registering a new account with the authentication method. This has to be stored on the session as otherwise it wouldn't be possible to implement authentication methods such as OAuth2 that takes the user to a third-party site and then redirects the browser back. 2025-07-09 15:21:39 +02:00
			Boolean indicating if authentication via Telegram is enabled or not. Requires `NUXT_PUBLIC_TELEGRAM_BOT_USERNAME` and `NUXT_TELEGRAM_BOT_TOKEN_FILE` to be set in order to work.

			Defaults to `false`.