core: Tidy contributor onboarding.

- Fixes typos.
- Fixes stale links.
- Tidies Makefile so that Poetry env is optional for hygiene commands.
- Remove mismatched YAML naming.
- Uses shebang on Python scripts.
- Document semver usage.
- Redirect OpenAPI schema.

.github/codespell-words.txt

@@ -1,7 +1,32 @@
+akadmin
+asgi
+assertIn
+authentik
+authn
+crate
+docstrings
+entra
+goauthentik
+gunicorn
+hass
+jwe
+jwks
 keypair
 keypairs
-hass
-warmup
+kubernetes
+oidc
 ontext
+openid
+passwordless
+plex
+saml
+scim
 singed
-assertIn
+slo
+sso
+totp
+traefik
+# https://github.com/codespell-project/codespell/issues/1224
+upToDate
+warmup
+webauthn

.github/workflows/ci-main.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Setup authentik env
         uses: ./.github/actions/setup
       - name: run job
-        run: poetry run make ci-${{ matrix.job }}
+        run: make ci-${{ matrix.job }}
   test-migrations:
     runs-on: ubuntu-latest
     steps:
@@ -94,7 +94,7 @@ jobs:
           # Test in the main database that we just migrated from the previous stable version
           AUTHENTIK_POSTGRESQL__TEST__NAME: authentik
         run: |
-          poetry run make test
+          make test
   test-unittest:
     name: test-unittest - PostgreSQL ${{ matrix.psql }}
     runs-on: ubuntu-latest
@@ -113,7 +113,7 @@ jobs:
           postgresql_version: ${{ matrix.psql }}
       - name: run unittest
         run: |
-          poetry run make test
+          make test
           poetry run coverage xml
       - if: ${{ always() }}
         uses: codecov/codecov-action@v5

.vscode/settings.json

@@ -1,26 +1,4 @@
 {
-    "cSpell.words": [
-        "akadmin",
-        "asgi",
-        "authentik",
-        "authn",
-        "entra",
-        "goauthentik",
-        "jwe",
-        "jwks",
-        "kubernetes",
-        "oidc",
-        "openid",
-        "passwordless",
-        "plex",
-        "saml",
-        "scim",
-        "slo",
-        "sso",
-        "totp",
-        "traefik",
-        "webauthn"
-    ],
     "todo-tree.tree.showCountsInTree": true,
     "todo-tree.tree.showBadges": true,
     "yaml.customTags": [

Makefile

@@ -4,31 +4,17 @@
 PWD = $(shell pwd)
 UID = $(shell id -u)
 GID = $(shell id -g)
-NPM_VERSION = $(shell python -m scripts.npm_version)
+NPM_VERSION = $(shell poetry run scripts/generate_semver.py)
 PY_SOURCES = authentik tests scripts lifecycle .github
 DOCKER_IMAGE ?= "authentik:test"
 
 GEN_API_TS = "gen-ts-api"
 GEN_API_PY = "gen-py-api"
 GEN_API_GO = "gen-go-api"
 
-pg_user := $(shell python -m authentik.lib.config postgresql.user 2>/dev/null)
-pg_host := $(shell python -m authentik.lib.config postgresql.host 2>/dev/null)
-pg_name := $(shell python -m authentik.lib.config postgresql.name 2>/dev/null)
-
-CODESPELL_ARGS = -D - -D .github/codespell-dictionary.txt \
-		-I .github/codespell-words.txt \
-		-S 'web/src/locales/**' \
-		-S 'website/docs/developer-docs/api/reference/**' \
-		authentik \
-		internal \
-		cmd \
-		web/src \
-		website/src \
-		website/blog \
-		website/docs \
-		website/integrations \
-		website/src
+pg_user := $(shell poetry run python -m authentik.lib.config postgresql.user 2>/dev/null)
+pg_host := $(shell poetry run python -m authentik.lib.config postgresql.host 2>/dev/null)
+pg_name := $(shell poetry run python -m authentik.lib.config postgresql.name 2>/dev/null)
 
 all: lint-fix lint test gen web  ## Lint, build, and test everything
 
@@ -46,34 +32,34 @@ go-test:
 	go test -timeout 0 -v -race -cover ./...
 
 test: ## Run the server tests and produce a coverage report (locally)
-	coverage run manage.py test --keepdb authentik
-	coverage html
-	coverage report
+	poetry run coverage run manage.py test --keepdb authentik
+	poetry run coverage html
+	poetry run coverage report
 
 lint-fix: lint-codespell  ## Lint and automatically fix errors in the python source code. Reports spelling errors.
-	black $(PY_SOURCES)
-	ruff check --fix $(PY_SOURCES)
+	poetry run black $(PY_SOURCES)
+	poetry run ruff check --fix $(PY_SOURCES)
 
 lint-codespell:  ## Reports spelling errors.
-	codespell -w $(CODESPELL_ARGS)
+	poetry run codespell -w
 
 lint: ## Lint the python and golang sources
-	bandit -r $(PY_SOURCES) -x web/node_modules -x tests/wdio/node_modules -x website/node_modules
+	poetry run bandit -c pyproject.toml -r $(PY_SOURCES)
 	golangci-lint run -v
 
 core-install:
 	poetry install
 
 migrate: ## Run the Authentik Django server's migrations
-	python -m lifecycle.migrate
+	poetry run python -m lifecycle.migrate
 
 i18n-extract: core-i18n-extract web-i18n-extract  ## Extract strings that require translation into files to send to a translation service
 
 aws-cfn:
 	cd lifecycle/aws && npm run aws-cfn
 
 core-i18n-extract:
-	ak makemessages \
+	poetry run ak makemessages \
 		--add-location file \
 		--no-obsolete \
 		--ignore web \
@@ -104,11 +90,11 @@ gen-build:  ## Extract the schema from the database
 	AUTHENTIK_DEBUG=true \
 		AUTHENTIK_TENANTS__ENABLED=true \
 		AUTHENTIK_OUTPOSTS__DISABLE_EMBEDDED_OUTPOST=true \
-		ak make_blueprint_schema > blueprints/schema.json
+		poetry run ak make_blueprint_schema > blueprints/schema.json
 	AUTHENTIK_DEBUG=true \
 		AUTHENTIK_TENANTS__ENABLED=true \
 		AUTHENTIK_OUTPOSTS__DISABLE_EMBEDDED_OUTPOST=true \
-		ak spectacular --file schema.yml
+		poetry run ak spectacular --file schema.yml
 
 gen-changelog:  ## (Release) generate the changelog based from the commits since the last tag
 	git log --pretty=format:" - %s" $(shell git describe --tags $(shell git rev-list --tags --max-count=1))...$(shell git branch --show-current) | sort > changelog.md
@@ -187,7 +173,7 @@ gen-client-go: gen-clean-go  ## Build and install the authentik API for Golang
 	rm -rf ./${GEN_API_GO}/config.yaml ./${GEN_API_GO}/templates/
 
 gen-dev-config:  ## Generate a local development config file
-	python -m scripts.generate_config
+	poetry run scripts/generate_config.py
 
 gen: gen-build gen-client-ts
 
@@ -268,16 +254,16 @@ ci--meta-debug:
 	node --version
 
 ci-black: ci--meta-debug
-	black --check $(PY_SOURCES)
+	poetry run black --check $(PY_SOURCES)
 
 ci-ruff: ci--meta-debug
-	ruff check $(PY_SOURCES)
+	poetry run ruff check $(PY_SOURCES)
 
 ci-codespell: ci--meta-debug
-	codespell $(CODESPELL_ARGS) -s
+	poetry run codespell -s
 
 ci-bandit: ci--meta-debug
-	bandit -r $(PY_SOURCES)
+	poetry run bandit -r $(PY_SOURCES)
 
 ci-pending-migrations: ci--meta-debug
-	ak makemigrations --check
+	poetry run ak makemigrations --check

SECURITY.md

@@ -2,7 +2,7 @@ authentik takes security very seriously. We follow the rules of [responsible di
 
 ## Independent audits and pentests
 
-We are committed to engaging in regular pentesting and security audits of authentik. Defining and adhering to a cadence of external testing ensures a stronger probability that our code base, our features, and our architecture is as secure and non-exploitable as possible. For more details about specfic audits and pentests, refer to "Audits and Certificates" in our [Security documentation](https://docs.goauthentik.io/docs/security).
+We are committed to engaging in regular pentesting and security audits of authentik. Defining and adhering to a cadence of external testing ensures a stronger probability that our code base, our features, and our architecture is as secure and non-exploitable as possible. For more details about specific audits and pentests, refer to "Audits and Certificates" in our [Security documentation](https://docs.goauthentik.io/docs/security).
 
 ## What authentik classifies as a CVE
 

lifecycle/wait_for_db.py

@@ -63,7 +63,9 @@ def wait_for_db():
     # Sanity check, ensure SECRET_KEY is set before we even check for database connectivity
     if CONFIG.get("secret_key") is None or len(CONFIG.get("secret_key")) == 0:
         CONFIG.log("info", "----------------------------------------------------------------------")
-        CONFIG.log("info", "Secret key missing, check https://goauthentik.io/docs/installation/.")
+        CONFIG.log(
+            "info", "Secret key missing, check https://docs.goauthentik.io/docs/install-config/"
+        )
         CONFIG.log("info", "----------------------------------------------------------------------")
         sysexit(1)
     check_postgres()

pyproject.toml

@@ -4,6 +4,26 @@ version = "2024.12.2"
 description = ""
 authors = ["authentik Team <[email protected]>"]
 
+[tool.bandit]
+exclude_dirs = ["**/node_modules/**"]
+
+[tool.codespell]
+skip = [
+    "**/node_modules",
+    "**/package-lock.json",
+    "schema.yml",
+    "unittest.xml",
+    "./blueprints/schema.json",
+    "go.sum",
+    "locale",
+    "**/dist",
+    "**/web/src/locales",
+    "**/web/xliff",
+    "./website/build",
+    "*.api.mdx",
+]
+dictionary = ".github/codespell-dictionary.txt,-"
+ignore-words = ".github/codespell-words.txt"
 [tool.black]
 line-length = 100
 target-version = ['py312']
@@ -122,7 +142,9 @@ kubernetes = "*"
 ldap3 = "*"
 lxml = "*"
 msgraph-sdk = "*"
-opencontainers = { git = "https://github.com/vsoch/oci-python", rev = "20d69d9cc50a0fef31605b46f06da0c94f1ec3cf", extras = ["reggie"] }
+opencontainers = { git = "https://github.com/vsoch/oci-python", rev = "20d69d9cc50a0fef31605b46f06da0c94f1ec3cf", extras = [
+    "reggie",
+] }
 packaging = "*"
 paramiko = "*"
 psycopg = { extras = ["c"], version = "*" }

scripts/generate_config.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 """Generate config for development"""
 
 from yaml import safe_dump

scripts/generate_semver.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+"""
+Generates a Semantic Versioning identifier, suffixed with a timestamp.
+"""
+
+from time import time
+
+from authentik import __version__ as package_version
+
+"""
+See: https://semver.org/#spec-item-9 (Pre-release spec)
+"""
+pre_release_timestamp = int(time())
+
+print(f"{package_version}-{pre_release_timestamp}")

tests/e2e/proxy_forward_auth/traefik_single/config-static.yaml

@@ -12,7 +12,7 @@ entryPoints:
   web:
     address: ":80"
 
-# Re-use the same config file to define everything
+# Reuse the same config file to define everything
 providers:
   file:
     filename: /etc/traefik/traefik.yml

web/src/admin/applications/wizard/steps/ak-application-wizard-submit-step.ts

@@ -328,7 +328,7 @@ export class ApplicationWizardSubmitStep extends CustomEmitterElement(Applicatio
         if (!(this.wizard && app && provider)) {
             throw new Error("Submit step received uninitialized wizard context");
         }
-        // An empty object is truthy, an empty array is falsey. *WAT Javascript*.
+        // An empty object is truthy, an empty array is falsey. *WAT JavaScript*.
         const keys = Object.keys(this.wizard.errors);
         return match([this.state, keys])
             .with(["submitted", P._], () =>

website/.gitignore

@@ -24,5 +24,5 @@ yarn-debug.log*
 yarn-error.log*
 
 static/docker-compose.yml
-static/schema.yaml
+static/schema.yml
 docs/developer-docs/api/reference/**

website/docusaurus.config.ts

@@ -134,7 +134,7 @@ module.exports = async function (): Promise<Config> {
                     docsPluginId: "docs",
                     config: {
                         authentik: {
-                            specPath: "static/schema.yaml",
+                            specPath: "static/schema.yml",
                             outputDir: "docs/developer-docs/api/reference/",
                             hideSendButton: true,
                             sidebarOptions: {

website/integrations/services/frappe/index.md

@@ -13,7 +13,7 @@ These instructions apply to all projects in the Frappe Family.
 
 ## What is Frappe
 
-> Frappe is a full stack, batteries-included, web framework written in Python and Javascript.
+> Frappe is a full stack, batteries-included, web framework written in Python and JavaScript.
 >
 > -- https://frappe.io/
 

website/netlify.toml

@@ -1002,6 +1002,12 @@
   status = 302
   force = true
 
+[[redirects]]
+  from = "/schema.yaml"
+  to = "/schema.yml"
+  status = 302
+  force = true
+
 [[redirects]]
   from = "/developer-docs/api/api"
   to = "/docs/developer-docs/api/api"

website/package.json

@@ -4,8 +4,8 @@
     "private": true,
     "license": "MIT",
     "scripts": {
-        "build": "cp ../docker-compose.yml static/docker-compose.yml && cp ../schema.yml static/schema.yaml && docusaurus gen-api-docs all && cross-env NODE_OPTIONS='--max_old_space_size=65536' docusaurus build",
-        "build-bundled": "cp ../schema.yml static/schema.yaml && docusaurus gen-api-docs all && cross-env NODE_OPTIONS='--max_old_space_size=65536' docusaurus build",
+        "build": "cp ../docker-compose.yml static/docker-compose.yml && cp ../schema.yml static/schema.yml && docusaurus gen-api-docs all && cross-env NODE_OPTIONS='--max_old_space_size=65536' docusaurus build",
+        "build-bundled": "cp ../schema.yml static/schema.yml && docusaurus gen-api-docs all && cross-env NODE_OPTIONS='--max_old_space_size=65536' docusaurus build",
         "deploy": "docusaurus deploy",
         "docusaurus": "docusaurus",
         "lint:lockfile": "wireit",

website/scripts/docsmg/src/migrate.rs

@@ -124,7 +124,7 @@ fn replace_links(migrate_path: PathBuf, moves: Vec<(PathBuf, PathBuf)>) {
             r#move.1.display(),
             tmp_file
         ));
-        // delete file if it didnt already exist
+        // delete file if it didn't already exist
         if let Ok(_) = tmp_file {
             let _ = remove_file(&r#move.1);
         };
@@ -223,7 +223,7 @@ fn replace_links(migrate_path: PathBuf, moves: Vec<(PathBuf, PathBuf)>) {
                 );
                 continue;
             };
-            // delete file if it didnt already exist
+            // delete file if it didn't already exist
             //if let Ok(_) = tmp_file {
             //    let _ = remove_file(&absolute_link);
             //};
@@ -275,7 +275,7 @@ fn replace_links(migrate_path: PathBuf, moves: Vec<(PathBuf, PathBuf)>) {
                 .collect::<PathBuf>();
 
             let new_link = escapes.join(tmp_absolute_link.iter().collect::<PathBuf>());
-            // add a . to the begining if it doesnt already start with . or ..
+            // add a . to the beginning if it doesn't already start with . or ..
             let new_link = match new_link
                 .components()
                 .collect::<Vec<_>>()