{"id":14978576,"url":"https://github.com/theonethread/falkor-auth-server","last_synced_at":"2026-03-04T21:32:07.374Z","repository":{"id":37805439,"uuid":"383736958","full_name":"theonethread/falkor-auth-server","owner":"theonethread","description":"Nginx authentication preflight proxy server","archived":false,"fork":false,"pushed_at":"2023-06-21T15:39:48.000Z","size":688,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-08-14T16:42:37.515Z","etag":null,"topics":["authentication","falkor","nginx","server"],"latest_commit_sha":null,"homepage":"https://falkor.world","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theonethread.png","metadata":{"funding":{"ko_fi":"falkor_framework","custom":"https://www.linkedin.com/in/barnabas-bucsy"},"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-07T09:02:56.000Z","updated_at":"2022-11-05T14:22:34.000Z","dependencies_parsed_at":"2024-09-28T01:40:45.935Z","dependency_job_id":"349aefe9-129b-417e-9043-e4aaf6afc6e2","html_url":"https://github.com/theonethread/falkor-auth-server","commit_stats":{"total_commits":286,"total_committers":1,"mean_commits":286.0,"dds":0.0,"last_synced_commit":"aadde33037dc482a66d08849c6ea055c4d1b17e5"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/theonethread/falkor-auth-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theonethread%2Ffalkor-auth-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theonethread%2Ffalkor-auth-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theonethread%2Ffalkor-auth-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theonethread%2Ffalkor-auth-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theonethread","download_url":"https://codeload.github.com/theonethread/falkor-auth-server/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theonethread%2Ffalkor-auth-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30093744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T20:42:30.420Z","status":"ssl_error","status_checked_at":"2026-03-04T20:42:30.057Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","falkor","nginx","server"],"created_at":"2024-09-24T13:57:56.651Z","updated_at":"2026-03-04T21:32:07.347Z","avatar_url":"https://github.com/theonethread.png","language":"JavaScript","funding_links":["https://ko-fi.com/falkor_framework","https://www.linkedin.com/in/barnabas-bucsy"],"categories":[],"sub_categories":[],"readme":"# **Falkor Authentication Server**\n\n[![Npm Keywords](https://img.shields.io/github/package-json/keywords/theonethread/falkor-auth-server \"Keywords\")](https://www.npmjs.com/package/@falkor/falkor-auth-server \"Visit\") \u0026nbsp; [![Npm Package](https://img.shields.io/npm/v/@falkor/falkor-auth-server \"Npm\")](https://www.npmjs.com/package/@falkor/falkor-auth-server \"Visit\") \u0026nbsp; [![Node Version](https://img.shields.io/node/v/@falkor/falkor-auth-server \"Node\")](https://nodejs.org/ \"Visit\") \u0026nbsp; [![Build](https://img.shields.io/github/workflow/status/theonethread/falkor-auth-server/Falkor%20CI%20-%20Release \"Build\")](https://github.com/theonethread/falkor-auth-server/actions \"Visit\") \u0026nbsp; [![Security](https://img.shields.io/github/workflow/status/theonethread/falkor-auth-server/Falkor%20CI%20-%20Security?label=security \"Security\")](https://github.com/theonethread/falkor-auth-server/actions \"Visit\") \u0026nbsp; [![Activity](https://img.shields.io/github/last-commit/theonethread/falkor-auth-server \"Activity\")](https://github.com/theonethread/falkor-auth-server \"Visit\") \u0026nbsp; [![Falkor Bundler](https://img.shields.io/npm/dependency-version/@falkor/falkor-auth-server/dev/@falkor/falkor-bundler \"Falkor Bundler\")](https://www.npmjs.com/package/@falkor/falkor-bundler \"Visit\") \u0026nbsp; [![Fastify](https://img.shields.io/npm/dependency-version/@falkor/falkor-auth-server/fastify \"Fastify\")](https://www.npmjs.com/package/fastify \"Visit\") \u0026nbsp; [![Snyk Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/github/theonethread/falkor-auth-server \"Snyk\")](https://snyk.io/test/github/theonethread/falkor-auth-server \"Visit\") \u0026nbsp; [![License](https://img.shields.io/npm/l/@falkor/falkor-auth-server \"MIT\")](https://github.com/theonethread/falkor-auth-server/blob/master/license.txt \"Visit\")\n\nThe `falkor-auth-server` project is a standalone `npm` command-line application written in JavaScript to be used as an Nginx authentication proxy server (mainly to be used with the **Falkor Framework**).\n\n## **Installation**\n\nInstall the package globally, so it's available in your `PATH`:\n\n```\n$ npm install --global @falkor/falkor-auth-server\n```\n\n## **Usage**\n\n### **Command Line Interface**\n\n#### `falkor-auth-server`\n\nUsage:\n\n```\nfalkor-auth-server [(--id \u003cid\u003e)] [(--port \u003cport\u003e)] [(--domain \u003cdomain\u003e)] [(--host \u003chost\u003e)] [(--cookie \u003ccookie\u003e)]\n    [(--ttl \u003cttl\u003e)] [(--secret \u003csecret\u003e)] [(--user \u003cuser\u003e)] [(--role \u003crole\u003e)] [(--db \u003cdb\u003e)] [(--stamp \u003cstamp\u003e)]\n    [(--level \u003clevel\u003e)] [(--file \u003cfile\u003e)]\nfalkor-auth-server [(--i \u003cid\u003e)] [(--p \u003cport\u003e)] [(--d \u003cdomain\u003e)] [(--H \u003chost\u003e)] [(--c \u003ccookie\u003e)][(--t \u003cttl\u003e)]\n    [(--s \u003csecret\u003e)] [(--u \u003cuser\u003e)] [(--r \u003crole\u003e)] [(--D \u003cdb\u003e)] [(--S \u003cstamp\u003e)] [(--l \u003clevel\u003e)] [(--f \u003cfile\u003e)]\nfalkor-auth-server (-v | --version | -h | --help)\n```\n\nOptions:\n\n- `-v` or `--version`: Show version and exit\n- `-h` or `--help`: Show help and exit\n- `-i \u003cid\u003e` or `--id \u003cid\u003e`: ID of server (default: `falkor-auth`)\n- `-p \u003cport\u003e` or `--port \u003cport\u003e`: Port of server (default: `9999`)\n- `-d \u003cdomain\u003e` or `--domain \u003cdomain\u003e`: Domain of the cookies to set\n- `-H \u003chost\u003e` or `--host \u003chost\u003e`: Host of the server (default: `0.0.0.0`)\n- `-c \u003ccookie\u003e` or `--cookie \u003ccookie\u003e`: Cookie name (default: `@falkor_token`)\n- `-t \u003cttl\u003e` or `--ttl \u003cttl\u003e`: Cookie TTL (default: `14400`)\n- `-s \u003csecret\u003e` or `--secret \u003csecret\u003e`: 32 characters long secret for token and password encryption\n- `-u \u003cuser\u003e` or `--user \u003cuser\u003e`: User response header name (default: `X-Falkor-Header`)\n- `-r \u003crole\u003e` or `--role \u003crole\u003e`: Role response header name (default: `X-Falkor-Role`)\n- `-D \u003cdb\u003e` or `--db \u003cdb\u003e`: User database address (`mongodb://` or `mongodb+srv://` address)\n- `-S \u003cstamp\u003e` or `--stamp \u003cstamp\u003e`: Add timestamp to logs (default: `true`)\n- `-l \u003clevel\u003e` or `--level \u003clevel\u003e`: Log level (default: `debug`)\n- `-f \u003cfile\u003e` or `--file \u003cfile\u003e`: Log file destination, if set logs will be dumped here\n\n\u003e _**SEE:** [`config.js`](https://github.com/theonethread/falkor-auth-server/blob/master/src/util/config.js \"Open\") for further reference._\n\n#### `falkor-auth-passwd`\n\nThe accompanying `falkor-auth-passwd` binary is also a standalone `npm` command-line application written in JavaScript to be used with the `falkor-auth-server`. It generates hashes out of passwords based on the server's secret to be stored in the database.\n\nUsage:\n\n```\nfalkor-auth-passwd (--password \u003cpassword\u003e) (--secret \u003csecret\u003e)\nfalkor-auth-passwd (-p \u003cpassword\u003e) (-s \u003csecret\u003e)\nfalkor-auth-passwd (-v | --version | -h | --help)\n```\n\nOptions:\n\n`-v` or `--version`: Show version and exit `-h` or `--help`: Show help and exit `-s \u003csecret\u003e` or `--secret \u003csecret\u003e`: 32 characters long secret for token and password encryption `-p \u003cpassword\u003e` or `--password \u003cpassword\u003e`: Password to create encrypted hash for\n\n### **Environment Variables**\n\nAll `falkor-auth-server` CLI options can be set as environment variables too, though CLI flags overpower them.\n\n- `SERVER_ID=\u003cid\u003e`: ID of server (default: `falkor-auth`)\n- `SERVER_PORT=\u003cport\u003e`: Port of server (default: `9999`)\n- `SERVER_DOMAIN=\u003cdomain\u003e`: Domain of the cookies to set\n- `SERVER_HOST=\u003chost\u003e`: Host of the server (default: `0.0.0.0`)\n- `COOKIE_NAME=\u003ccookie\u003e`: Cookie name (default: `@falkor_token`)\n- `COOKIE_TTL=\u003cttl\u003e`: Cookie TTL (default: `14400`)\n- `AUTH_SECRET=\u003csecret\u003e`: 32 characters long secret for token and password encryption\n- `AUTH_HEADER_USER=\u003cuser\u003e`: User response header name (default: `X-Falkor-Header`)\n- `AUTH_HEADER_ROLE=\u003crole\u003e`: Role response header name (default: `X-Falkor-Role`)\n- `AUTH_DB=\u003cdb\u003e`: User database address (`mongodb://` or `mongodb+srv://` address)\n- `LOG_TIMESTAMP=\u003cstamp\u003e`: Add timestamp to logs (default: `true`)\n- `LOG_LEVEL=\u003clevel\u003e`: Log level (default: `debug`)\n- `LOG_FILE=\u003cfile\u003e`: Log file destination, if set logs will be dumped here\n\n\u003e _**SEE:** Example [`config.env`](https://github.com/theonethread/falkor-auth-server/blob/master/res/config.env \"Open\") for further reference._\n\n### **Must Have Settings**\n\nThe following settings must be present either running the application with CLI options, or using environment variables:\n\n- Domain of the cookies to set:\n  - `-d \u003cdomain\u003e` or `--domain \u003cdomain\u003e`\n  - `SERVER_DOMAIN=\u003cdomain\u003e`\n- 16 characters long secret for token encryption:\n  - `-s \u003csecret\u003e` or `--secret \u003csecret\u003e`\n  - `AUTH_SECRET=\u003csecret\u003e`\n- User database address (or relative path to `.yml` file in `debug` builds):\n  - `-D \u003cdb\u003e` or `--db \u003cdb\u003e`\n  - `AUTH_DB=\u003cdb\u003e`\n\n## **User Data**\n\nThe server needs an existing MongoDB database, for testing purposes one can create a free account at [MongoDB Atlas](https://www.mongodb.com/atlas \"Visit\"). The application will assume the following database setup:\n\n- Database: `authentication`\n- Collection: `users`\n- Entries:\n\n```javascript\n{\n    name: { type: \"string\" }\n    pwd: { type: \"string\" }\n    roles: {\n        type: \"array\",\n        items: { type: \"string\" }\n    }\n}\n```\n\nThe `pwd` entry must be an encoded password hash. To generate one with the application's `crypto` library, with a global install run:\n\n```\n$ falkor-auth-passwd --secret \u003cyour-secret\u003e --password \u003cyour-password\u003e\n```\n\nOr from the installed project's root:\n\n```\n$ npm run passwd -- --secret \u003cyour-secret\u003e --password \u003cyour-password\u003e\n```\n\n\u003e _**NOTE:** Since randomization, you will get different values running this command multiple times._\n\n## **Server Setup**\n\nTo set up a Fedora-based Nginx webserver using Node.js as authentication service you can follow my tutorials in the Hetzner Community:\n\n- [Setting Up a Secure Fedora Webserver](https://community.hetzner.com/tutorials/secure-fedora-webserver \"Visit\")\n- [Nginx Authentication Preflight Request with Node.js Backend](https://community.hetzner.com/tutorials/nginx-auth-preflight-nodejs-api \"Visit\")\n\n## **Further Development**\n\nThe project uses the [`@falkor/falkor-bundler`](https://www.npmjs.com/package/@falkor/falkor-bundler \"Visit\") module to compile sources. To clone the repository and compile `falkor-auth-server` one can use the commands:\n\n```\n$ git clone --branch develop git@github.com:theonethread/falkor-auth-server.git\n$ cd falkor-auth-server\n$ npm install\n$ npm run [ debug | release ]\n```\n\n\u003e _**SEE:** `\"scripts\"` entry in [`package.json`](https://github.com/theonethread/falkor-auth-server/blob/master/package.json \"Open\") for further reference._\n\n\u003e _**NOTE:** Compiling the `develop` sources might need locally linked `develop` versions of downstream module:_\n\u003e\n\u003e - _[`@falkor/falkor-bundler`](https://github.com/theonethread/falkor-bundler/tree/develop \"Visit\")_\n\u003e\n\u003e _**SEE:** [`npm-link`](https://docs.npmjs.com/cli/v7/commands/npm-link \"Visit\") for further reference._\n\n### **Database**\n\nIf compiled in `debug` mode, and the application finds user data in MongoDB with unencrypted `pass` field (when logging a user in), **it will update the user record** with an encrypted `pwd` field, and unset `pass`. This behavior can be controlled with the `#UPDATE_PWD` context variable in the `\"scripts\"` block of [`package.json`](https://github.com/theonethread/falkor-auth-server/blob/master/package.json \"Open\") - for further details see [`@falkor/falkor-bundler`](https://www.npmjs.com/package/@falkor/falkor-bundler \"Visit\").\n\n#### **Database Mock**\n\nIf compiled in `debug` mode and the DB option does not start with `mongodb://` or `mongodb+srv://`, the application will assume a relative path to a `.yml` file with the following structure:\n\n```yaml\nusers:\n  - name: string\n    pass: string\n    roles: [string]\n```\n\n\u003e _**SEE:** Example [`auth.yml`](https://github.com/theonethread/falkor-auth-server/blob/master/res/auth.yml \"Open\") for further reference._\n\n### **Man Page**\n\nBy default the `falkor-auth-server` project ships with pre-compiled man pages when installed on Unix-like operating systems. The manuals were created by converting the files [`man/man.md`](https://github.com/theonethread/falkor-auth-server/blob/master/man/man.md \"Open\") and [`man/passwd.md`](https://github.com/theonethread/falkor-auth-server/blob/master/man/passwd.md \"Open\").\n\nTo recompile the manuals, make sure that [`Pandoc`](https://pandoc.org/ \"Visit\") is installed, and present in the `PATH`, then run:\n\n```\n$ npm run man\n```\n\n### **Linting**\n\nThe project uses [`prettier`](https://www.npmjs.com/package/prettier \"Visit\") for code formatting and [`cspell`](https://www.npmjs.com/package/cspell \"Visit\") to avoid general typos in both sources and documentation - it is advised to install these packages as extensions in your IDE to prevent CI errors beforehand. To lint the project run:\n\n```\n$ npm run lint\n```\n\n\u003e _**SEE:** [`.prettierrc.cjs`](https://github.com/theonethread/falkor-auth-server/blob/develop/.prettierrc.cjs \"Open\") and [`cspell.config.cjs`](https://github.com/theonethread/falkor-auth-server/blob/develop/cspell.config.cjs \"Open\") for further reference._\n\n- To fix formatting issues run `$ npx prettier --write \u003cpath-to-file\u003e`. This will overwrite the file with the default formatting applied locally, so then you can review the changes in `git` and **ensure those did not affect production artifacts**.\n- To fix spelling errors run `$ npx cspell lint --wordsOnly --unique --gitignore --exclude .git ** .*` for details, and either make the fixes in the sources listed, add `cspell` favored comments, or extend the project-wide `cspell.config.cjs` accordingly.\n\n### **Versioning and Branching Strategy**\n\nRelease sources can be found on the `master` branch, this one always points to the latest tagged release. Previous sources of releases can be found using `git` version tags (or browsing GitHub releases). Released packages can be found on [npmjs](https://www.npmjs.com/package/@falkor/falkor-auth-server \"Visit\").\n\nThe repository's main branch is `develop` (due to technical reasons), this holds all developments that are already decided to be included in the next release. Usually this branch is ahead of `master` one patch version (but based on upcoming features to include this can become minor, or major), so prepared external links may yet be broken.\n\nThe `feature/*` branches usually hold ideas and POC code, these will only be merged into `develop` once their impact measured and quality meets release requirements.\n\n\u003e _The project uses [SemVer](https://semver.org \"Visit\"), `git` tags are prefixed with a `v` character._\n\n### **GitHub Actions**\n\nThe workflows can be found [here](https://github.com/theonethread/falkor-auth-server/blob/develop/.github/workflows \"Open\").\n\n#### **Continuous Integration**\n\nAutomatic builds are achieved via GitHub actions, CI will make nightly builds of the `develop` branch (using Ubuntu image), and test `master` when there is a pull request, or commit on it (using Ubuntu - Win - MacOS image matrix).\n\n### **Security**\n\nThe project uses [CodeQL](https://codeql.github.com \"Visit\") and [Snyk](https://snyk.io \"Visit\") to ensure standard security.\n\n\u003e _The **Falkor Framework** supports a healthy and ubiquitous Internet Immune System enabled by security research, reporting, and disclosure. Check out our [Vulnerability Disclosure Policy](https://github.com/theonethread/falkor-auth-server/security/policy \"Open\") - based on [disclose.io](https://disclose.io \"Visit\")'s best practices._\n\n### **Free and Open Source**\n\nThe latest sources can always be found on [GitHub](https://github.com/theonethread/falkor-auth-server \"Visit\").\n\n#### **Getting Involved**\n\nWe believe - and we hope you do too - that learning how to code, how to think, and how to contribute to free- and open source software can empower the next generation of coders and creators. We **value** first time contributors just the same as rock stars of the OSS world, so if you're interested in getting involved, just head over to our [Contribution Guidelines](https://github.com/theonethread/.github/blob/master/.github/contributing.md \"Open\") for a quick heads-up!\n\n#### **License**\n\n[MIT](https://github.com/theonethread/falkor-auth-server/blob/master/license.txt \"Open\")\n\n##\n\n---\n\n_©2020-2023 Barnabas Bucsy - All rights reserved._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheonethread%2Ffalkor-auth-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheonethread%2Ffalkor-auth-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheonethread%2Ffalkor-auth-server/lists"}