{"id":40069947,"url":"https://github.com/vestauth/vestauth","last_synced_at":"2026-03-03T00:04:44.319Z","repository":{"id":333354307,"uuid":"1135122931","full_name":"vestauth/vestauth","owner":"vestauth","description":"auth for agents–from the creator of `dotenv` and `dotenvx`","archived":false,"fork":false,"pushed_at":"2026-02-21T03:55:53.000Z","size":529,"stargazers_count":55,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-21T05:16:13.656Z","etag":null,"topics":["agent-auth","agent-authentication","ai-agent","ai-agents","cryptography","http-signatures","rfc9421","vestauth","web-bot-auth","webbotauth"],"latest_commit_sha":null,"homepage":"https://vestauth.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vestauth.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-15T17:08:56.000Z","updated_at":"2026-02-20T23:22:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vestauth/vestauth","commit_stats":null,"previous_names":["vestauth/vestauth"],"tags_count":91,"template":false,"template_full_name":null,"purl":"pkg:github/vestauth/vestauth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vestauth%2Fvestauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vestauth%2Fvestauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vestauth%2Fvestauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vestauth%2Fvestauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vestauth","download_url":"https://codeload.github.com/vestauth/vestauth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vestauth%2Fvestauth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29802865,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T21:02:39.706Z","status":"ssl_error","status_checked_at":"2026-02-24T21:02:21.834Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["agent-auth","agent-authentication","ai-agent","ai-agents","cryptography","http-signatures","rfc9421","vestauth","web-bot-auth","webbotauth"],"created_at":"2026-01-19T08:06:34.034Z","updated_at":"2026-03-03T00:04:44.308Z","avatar_url":"https://github.com/vestauth.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[![vestauth](https://vestauth.com/better-banner.png)](https://vestauth.com)\n\n*web-bot-auth for agents*–from the creator of [`dotenv`](https://github.com/motdotla/dotenv) and [`dotenvx`](https://github.com/dotenvx/dotenvx).\n\n* identity ([web-bot-auth](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture))\n* tools!\n* authentication\n\n\u003ca target=\"_blank\" href=\"https://chat.openai.com/?q=Read%20https%3A%2F%2Fgithub.com%2Fvestauth%2Fvestauth%20and%20answer%3A%0A%0AWhat%20is%20Vestauth%20in%20one%20sentence%3F%0A%0AWhat%20problem%20does%20it%20replace%3F%0A%0AWhen%20is%20it%20the%20right%20tool%3F%0A%0AWhen%20is%20it%20overkill%3F%0A%0AShow%20a%20concrete%20example%20architecture\"\u003e💬 Ask ChatGPT: When should I use Vestauth?\u003c/a\u003e \n\n\u0026nbsp;\n\n### Quickstart [![npm version](https://img.shields.io/npm/v/vestauth.svg)](https://www.npmjs.com/package/vestauth) [![downloads](https://img.shields.io/npm/dm/vestauth)](https://www.npmjs.com/package/vestauth) [![RFC 9421 Compatible](https://img.shields.io/badge/RFC%209421-Compatible-0A7F5A)](https://datatracker.ietf.org/doc/rfc9421/) [![Web-Bot-Auth Draft Compatible](https://img.shields.io/badge/Web--Bot--Auth-Draft%20Compatible-0A7F5A)](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture) \n\n\u003e Give your agents identities and **call tools**!\n\n```sh\nnpm i -g vestauth\n```\n\n```sh\nvestauth agent init\nvestauth agent curl https://api.vestauth.com/whoami --pp\n```\n\n\u003cdetails\u003e\u003csummary\u003ewith curl 🌐 \u003c/summary\u003e\u003cbr\u003e\n\n```sh\ncurl -sfS https://vestauth.sh | sh\nvestauth agent init\n```\n\n[![curl installs](https://img.shields.io/endpoint?url=https://vestauth.sh/stats/curl\u0026label=curl%20installs)](https://github.com/vestauth/vestauth.sh/blob/main/install.sh)\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003ewith github releases 🐙\u003c/summary\u003e\u003cbr\u003e\n\n```sh\ncurl -L -o vestauth.tar.gz \"https://github.com/vestauth/vestauth/releases/latest/download/vestauth-$(uname -s)-$(uname -m).tar.gz\"\ntar -xzf vestauth.tar.gz\n./vestauth agent init\n```\n\n[![github releases](https://img.shields.io/github/downloads/vestauth/vestauth/total)](https://github.com/vestauth/vestauth/releases)\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eor windows 🪟\u003c/summary\u003e\u003cbr\u003e\n\nDownload [the windows executable](https://github.com/vestauth/vestauth/releases) directly from the [releases page](https://github.com/vestauth/vestauth/releases).\n\n\u003e * [vestauth-windows-amd64.zip\n](https://github.com/vestauth/releases/raw/main/latest/vestauth-windows-amd64.zip)\n\u003e * [vestauth-windows-x86_64.zip\n](https://github.com/vestauth/releases/raw/main/latest/vestauth-windows-x86_64.zip)\n\n(unzip to extract `vestauth.exe`)\n\n\u003c/details\u003e\n\n\u0026nbsp;\n\n## Identity\n\n\u003e Give agents cryptographic identities.\n\n```sh\n$ mkdir your-agent\n$ cd your-agent\n\n$ vestauth agent init\n✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)\n```\n\n\u003cdetails\u003e\u003csummary\u003elearn more\u003c/summary\u003e\u003cbr\u003e\n\nYour agent's identity lives in a simple `.env` file.\n\n```ini\n# .env\nAGENT_UID=\"agent-4b94ccd425e939fac5016b6b\"\nAGENT_PUBLIC_JWK=\"{\"crv\":\"Ed25519\",\"x\":\"py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg\",\"kty\":\"OKP\",\"kid\":\"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I\"}\"\nAGENT_PRIVATE_JWK=\"{\"crv\":\"Ed25519\",\"d\":\"Z9vbwN-3eiFMVv_TPWXOxqSMJAT21kZvejWi72yiAaQ\",\"x\":\"py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg\",\"kty\":\"OKP\",\"kid\":\"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I\"}\"\n```\n\n[💬 Ask ChatGPT: Are HTTP message signatures more secure than API keys?](https://chat.openai.com/?q=Are%20HTTP%20message%20signatures%20more%20secure%20than%20API%20keys%3F)\n\n\u003c/details\u003e\n\n\u0026nbsp;\n\n## Tools\n\n\u003e Call tools!\n\n```sh\nvestauth agent curl https://sfs.vestauth.com/write -d '{\"filepath\":\"/hello.md\", \"content\":\"hello\"}'\nvestauth agent curl https://sfs.vestauth.com/list\n```\n\n#### First Party\n\n\u003cdetails\u003e\u003csummary\u003e`SFS` Simple File System\u003c/summary\u003e\u003cbr/\u003e\n\n\u003e SFS is a simple file system for vestauth agents.\n\u003e\n\u003e [sfs.vestauth.com](https://sfs.vestauth.com)\n\n```sh\n# write a file\nvestauth agent curl https://sfs.vestauth.com/write -d '{\"filepath\":\"/hello.md\", \"content\":\"hello\"}'\n\n# delete a file\nvestauth agent curl https://sfs.vestauth.com/delete -d '{\"filepath\":\"/hello.md\"}'\n\n# list files\nvestauth agent curl https://sfs.vestauth.com/list\n\n# read a file\nvestauth agent curl https://sfs.vestauth.com/read -d '{\"filepath\":\"/hello.md\"}'\n```\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`GEO` Latitude and Longitude\u003c/summary\u003e\u003cbr/\u003e\n\n\u003e GEO returns the current latitude and longitude of a vestauth agent.\n\u003e\n\u003e [geo.vestauth.com](https://geo.vestauth.com)\n\n```sh\n# return latitude and longitude\nvestauth agent curl https://geo.vestauth.com/geo\n```\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n#### Third Party\n\n\u003cdetails\u003e\u003csummary\u003e`AS2` Agentic Secret Storage\u003c/summary\u003e\u003cbr/\u003e\n\n\u003e AS2 is a simple, agent-friendly secret storage.\n\u003e\n\u003e [as2.dotenvx.com](https://as2.dotenvx.com)\n\n```sh\n# set a secret\nvestauth agent curl https://as2.dotenvx.com/set -d '{\"KEY\":\"value\"}'\n\n# get all secrets\nvestauth agent curl \"https://as2.dotenvx.com/get\"\n\n# get single secret\nvestauth agent curl \"https://as2.dotenvx.com/get?key=KEY\"\n\n# get multiple secrets\nvestauth agent curl \"https://as2.dotenvx.com/get?key=KEY,TWILIO\"\n```\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`Docle` Check if email address is real\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Check if an email address is real before you hit send. Verifies syntax, DNS, MX records, SMTP mailbox existence, and cross-references multiple providers. All in real time, no signup required.\n\u003e\n\u003e [github.com/treadiehq/docle](https://github.com/treadiehq/docle) \n\n```sh\n# verify an email\nvestauth agent curl https://docle.co/api/verify -d '{\"emails\":[\"test@example.com\"]}'\n\n# check your usage\nvestauth agent curl https://docle.co/api/agent/usage\n```\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003emore coming soon\u003c/summary\u003e\u003cbr/\u003e\n\n* Geo IP - coming soon\n* Send/Receive Email - coming\n* Send/Receive SMS - coming\n* Send/Receive Telegram - coming\n* Send/Receive WhatsApp - coming\n* Human-in-the-loop - coming\n* Rotate NPM Tokens - coming\n* Rotate GitHub Tokens - coming\n* Working on a tool? Tell us and we'll list it.\n\n\u003c/details\u003e\n\n\u0026nbsp;\n\n## Authentication\n\n\u003e Build your own tools. Authenticate them with a single line of code – `vestauth.tool.verify`…\n\n```js\n...\nconst vestauth = require('vestauth')\n\napp.post('/whoami', async (req, res) =\u003e {\n  try {\n    const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`\n    const agent = await vestauth.tool.verify(req.method, url, req.headers)\n\n    res.json(agent)\n  } catch (err) {\n    res.status(401).json({ code: 401, error: { message: err.message }})\n  }\n})\n...\n```\n\n\u003e …the agents sign HTTP requests with a drop-in curl wrapper.\n\n```sh\n\u003e SIGNED - 200\n$ vestauth agent curl https://api.vestauth.com/whoami\n{\"uid\":\"agent-4b94ccd425e939fac5016b6b\",...}\n```\n\n\u003cdetails\u003e\u003csummary\u003elearn more\u003c/summary\u003e\u003cbr\u003e\n\n`vestauth agent curl` autosigns `curl` requests – injecting valid signed headers according to the [web-bot-auth draft](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture). You can peek these with the built-in `headers` primitive.\n\n```sh\n$ vestauth primitives headers GET https://api.vestauth.com/whoami --pp\n{\n  \"Signature\": \"sig1=:d4Id5SXhUExsf1XyruD8eBmlDtWzt/vezoCS+SKf0M8CxSkhKBtdHH7KkYyMN6E0hmxmNHsYus11u32nhvpWBQ==:\",\n  \"Signature-Input\": \"sig1=(\\\"@authority\\\");created=1770247189;keyid=\\\"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I\\\";alg=\\\"ed25519\\\";expires=1770247489;nonce=\\\"NURxn28X7zyKJ9k5bHxuOyO5qdvF9L5s2qHmhTrGUzbwGSIoUCHmwSlwiiCRgTDGuum83yyWMHJU4jmrVI_XPg\\\";tag=\\\"web-bot-auth\\\"\",\n  \"Signature-Agent\": \"sig1=agent-4b94ccd425e939fac5016b6b.api.vestauth.com\"\n}\n```\n\n\u003c/details\u003e\n\nVestauth handles usage, payments, and spam protection for your tool!\n\n\u0026nbsp;\n\n## Self-hosting\n\n\u003e Run your own Vestauth server.\n\n| |\n|---|\n| \u003ca target=\"_blank\" href=\"https://github.com/user-attachments/assets/b05ba917-c37a-4a53-9ec7-c5c8d78ad1c7\"\u003e\u003cimg src=\"https://github.com/user-attachments/assets/b05ba917-c37a-4a53-9ec7-c5c8d78ad1c7\" alt=\"self-hosting vestauth\" width=\"480\"\u003e\u003c/a\u003e |\n\nInitialize the server and run migrations (postgres).\n\n```sh\n$ curl -sSf https://vestauth.sh | sh\n$ vestauth server init\n$ vestauth server db:create\n$ vestauth server db:migrate\n```\n\nStart the server.\n\n```sh\n$ vestauth server start\nvestauth server listening on http://localhost:3000\n```\n\nAnd use your server's hostname when creating agents.\n\n```sh\n$ mkdir your-agent\n$ cd your-agent\n\n$ vestauth agent init --hostname http://localhost:3000\n✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)\n```\n\nThat's it. Your Vestauth ([web-bot-auth](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture)) infrastructure is now running under your control.\n\nMore details\n\n\u003cdetails\u003e\u003csummary\u003econfig\u003c/summary\u003e\u003cbr\u003e\n\nEdit the `.env` file to configure your server.\n\n```ini\nPORT=\"3000\"\nHOSTNAME=\"http://localhost:3000\"\nDATABASE_URL=\"postgres://localhost/vestauth_production\"\n```\n\nFor example, in production:\n\n* Change `HOSTNAME` to its production url - e.g. `vestauth.yoursite.com`\n* Change `DATABASE_URL` to a managed postgres - e.g. `postgresql://USER:PASS@aws-1-us-east-1.pooler.supabase.com:5432/postgres`\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eproduction note\u003c/summary\u003e\u003cbr\u003e\n\n\u003e [!WARNING]\n\u003e\n\u003e **Production note:** Configure a wildcard DNS record for `*.${HOSTNAME}`.\n\u003e \n\u003e Example: if `HOSTNAME=vestauth.yourapp.com`, add `*.vestauth.yourapp.com`.\n\u003e \n\u003e Required for `.well-known` discovery per the [web-bot-auth](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture) spec.\n\n\u003c/details\u003e\n\n\u0026nbsp;\n\n## Advanced\n\n\u003e Become a `vestauth` power user.\n\u003e\n\n### CLI 📟\n\nAdvanced CLI commands.\n\n\u003cdetails\u003e\u003csummary\u003e`agent init`\u003c/summary\u003e\u003cbr\u003e\n\nCreate agent.\n\n```sh\n$ vestauth agent init\n✔ agent created (.env/AGENT_UID=agent-609a4fd2ebf4e6347108c517)\n⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`agent init --hostname`\u003c/summary\u003e\u003cbr\u003e\n\nUse `--hostname` to override the agent API hostname (defaults to `AGENT_HOSTNAME`, then `api.vestauth.com`):\nWhen no scheme is provided, `https://` is assumed. For local non-TLS endpoints, pass `http://...` explicitly.\n\n```sh\n$ vestauth agent init --hostname https://vestauth.yoursite.com\n✔ agent created (.env/AGENT_UID=agent-609a4fd2ebf4e6347108c517)\n⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`agent curl`\u003c/summary\u003e\u003cbr\u003e\n\nRun curl as agent.\n\n```sh\n$ vestauth agent curl https://api.vestauth.com/whoami\n{\"uid\":\"agent-609a4fd2ebf4e6347108c517\", ...}\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`agent curl --pretty-print`\u003c/summary\u003e\u003cbr\u003e\n\nPretty print curl json output.\n\n```sh\n$ vestauth agent curl https://api.vestauth.com/whoami --pp\n{\n  \"uid\": \"agent-609a4fd2ebf4e6347108c517\",\n  \"kid\": \"FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM\",\n  \"public_jwk\": {\n    ...\n  },\n  \"well_known_url\": \"https://agent-609a4fd2ebf4e6347108c517.api.vestauth.com/.well-known/http-message-signatures-directory\"\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e`agent headers`\u003c/summary\u003e\u003cbr\u003e\n\nGenerate signed headers as agent.\n\n```sh\n$ vestauth agent headers GET https://api.vestauth.com/whoami --pp\n{\n  \"Signature\": \"sig1=:UW6A7j8jo+gQxd+EeVgDddY51ZOc9plrSaupW/N53hQnQFvP9BuwQHgL7SVPLQIu4cnRzLgvwm7Yu9YMO+HUDQ==:\",\n  \"Signature-Input\": \"sig1=(\\\"@authority\\\");created=1770396357;keyid=\\\"FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM\\\";alg=\\\"ed25519\\\";expires=1770396657;nonce=\\\"PrE7A6I_5fWnxBsBigNvxjp3-YangXl71V1uM3hPZavh918JqzjMSRcjHv_n5XIb3N8WivZEeigCBH6QGDSqgA\\\";tag=\\\"web-bot-auth\\\"\",\n  \"Signature-Agent\": \"sig1=agent-609a4fd2ebf4e6347108c517.api.vestauth.com\"\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e`agent headers --uid`\u003c/summary\u003e\u003cbr\u003e\n\nChange the `AGENT_UID`.\n\n```sh\n$ vestauth agent headers GET https://api.vestauth.com/whoami --uid agent-1234 --pp\n{\n  \"Signature\": \"sig1=:UW6A7j8jo+gQxd+EeVgDddY51ZOc9plrSaupW/N53hQnQFvP9BuwQHgL7SVPLQIu4cnRzLgvwm7Yu9YMO+HUDQ==:\",\n  \"Signature-Input\": \"sig1=(\\\"@authority\\\");created=1770396357;keyid=\\\"FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM\\\";alg=\\\"ed25519\\\";expires=1770396657;nonce=\\\"PrE7A6I_5fWnxBsBigNvxjp3-YangXl71V1uM3hPZavh918JqzjMSRcjHv_n5XIb3N8WivZEeigCBH6QGDSqgA\\\";tag=\\\"web-bot-auth\\\"\",\n  \"Signature-Agent\": \"sig1=agent-1234.api.vestauth.com\"\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e`agent headers --private-jwk`\u003c/summary\u003e\u003cbr\u003e\n\nChange the `AGENT_PRIVATE_JWK` used to sign the headers.\n\n```sh\n$ vestauth agent headers GET https://api.vestauth.com/whoami --private-jwk '{\"crv\":\"Ed25519\",\"d\":\"RyFk7QTOk_bMjFQKjyAR-vJDp7BITn9U0YBFNdpR9wE\",\"x\":\"hyAxNMbuTcFQq420Dr46ucF0dRZ_FIyxgsujruEoklM\",\"kty\":\"OKP\",\"kid\":\"UfHTArlyLsqM8cB8sNfH2z6XOwc0RmJIq2CAPGfvMjk\"}' --pp\n{\n  \"Signature\": \"sig1=:PZUVVjqiECYuk8Hg1GZKKeJmwhLrcRdRA7nm1R595UFK9cx0q9atNFBzKP5wBEmszMIgvpYdMrIQbPEeKz4tCQ==:\",\n  \"Signature-Input\": \"sig1=(\\\"@authority\\\");created=1770396546;keyid=\\\"UfHTArlyLsqM8cB8sNfH2z6XOwc0RmJIq2CAPGfvMjk\\\";alg=\\\"ed25519\\\";expires=1770396846;nonce=\\\"BSIugautfZvN3u5QUgl1mMuyxgmeRsRy9XxX7GXxjJxq1mI0kJl4F-C1nITtOfSeEt6xR1YBfyxsffNKy_wKSA\\\";tag=\\\"web-bot-auth\\\"\",\n  \"Signature-Agent\": \"sig1=agent-609a4fd2ebf4e6347108c517.api.vestauth.com\"\n}\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`agent rotate`\u003c/summary\u003e\u003cbr\u003e\n\nRotate your `AGENT_PRIVATE_JWK` and `AGENT_PUBLIC_JWK`.\n\n```sh\n$ vestauth agent rotate\n✔ agent keys rotated (.env/AGENT_UID=agent-8f1b347e2e58899f3147c05b)\n⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`tool verify`\u003c/summary\u003e\u003cbr\u003e\n\nVerify agent.\n\n```sh\n$ vestauth tool verify GET https://api.vestauth.com/whoami --signature \"sig1=:H1kxwSRWFbIzKbHaUy4hQFp/JrmVTX//72JPHcW4W7cPt9q6LytRJgx5pUgWrrr7DCcMWgx/jpTPc8Ht8SZ3CQ==:\" --signature-input \"sig1=(\\\"@authority\\\");created=1770396709;keyid=\\\"FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM\\\";alg=\\\"ed25519\\\";expires=1770397009;nonce=\\\"BZSDVktdkjO6XH5jafAdPDttsB6eytXO7u8KXJN1tMtd5bprE3rp08HiaTRo7H6gZGtYb4_qtL7RiGi8P2Gq7w\\\";tag=\\\"web-bot-auth\\\"\" --signature-agent \"sig1=agent-609a4fd2ebf4e6347108c517.api.vestauth.com\"\n{\"uid\":\"agent-609a4fd2ebf4e6347108c517\",...}\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`server init`\u003c/summary\u003e\u003cbr\u003e\n\nCreate/update server `.env` for self-hosting (`PORT`, `HOSTNAME`, `DATABASE_URL`).\n\n```sh\n$ vestauth server init\n✔ ready (.env/HOSTNAME=http://localhost:3000)\n⮕ next run: [vestauth server start]\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`server db:create`\u003c/summary\u003e\u003cbr\u003e\n\nCreate `vestauth_production` database.\n\n```sh\n$ vestauth server db:create \nCreated database 'vestauth_production'\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`server db:migrate`\u003c/summary\u003e\u003cbr\u003e\n\nRun `vestauth_production` migrations.\n\n```sh\n$ vestauth server db:migrate \n== 20260223204000 CreateAgentsTable: migrating ================================================\n== 20260223204000 CreateAgentsTable: migrated (0.0160s) ===========================\n== 20260223205500 CreatePublicJwksTable: migrating ================================================\n== 20260223205500 CreatePublicJwksTable: migrated (0.0100s) ===========================\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`server db:drop`\u003c/summary\u003e\u003cbr\u003e\n\nDrop `vestauth_production` table.\n\n```sh\n$ vestauth server db:drop\nDropped database 'vestauth_production'\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`server start`\u003c/summary\u003e\u003cbr\u003e\n\nStart vestauth server.\n\n```sh\n$ vestauth server start \nvestauth server listening on http://localhost:3000\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`server start --port`\u003c/summary\u003e\u003cbr\u003e\n\nStart vestauth server on specific port.\n\n```sh\n$ vestauth server start --port 4567\nvestauth server listening on http://localhost:4567\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`server start --hostname`\u003c/summary\u003e\u003cbr\u003e\n\nSpecify hostname for vestauth server (default: localhost:3000).\n\n```sh\n$ vestauth server start --hostname vestauth.yoursite.com\nvestauth server listening on https://vestauth.yoursite.com\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`server start --database-url`\u003c/summary\u003e\u003cbr\u003e\n\nSpecify database url for vestauth server (default: localhost/vestauth_production).\n\n```sh\n$ vestauth server start --database-url postgresql://USER:PASS@aws-1-us-east-1.pooler.supabase.com:5432/postgres\nvestauth server listening on http://localhost:3000\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`primitives keypair`\u003c/summary\u003e\u003cbr\u003e\n\nGenerate public/private keypair.\n\n```sh\n$ vestauth primitives keypair --pp\n{\n  \"public_jwk\": {\n    \"crv\": \"Ed25519\",\n    \"x\": \"QjutZ3_tt2jRD_XSOq4EFCDivnwEzKIrQB2yReddsNo\",\n    \"kty\": \"OKP\",\n    \"kid\": \"ZCa5pijSUCw7QKgBs6nkvBBzbEjTMKYSt6iwCDQdIYc\"\n  },\n  \"private_jwk\": {\n    \"crv\": \"Ed25519\",\n    \"d\": \"RTyREuKAEfIMMs2ejwaKtFefZxt14HmsRR0rFj4U5iM\",\n    \"x\": \"QjutZ3_tt2jRD_XSOq4EFCDivnwEzKIrQB2yReddsNo\",\n    \"kty\": \"OKP\",\n    \"kid\": \"ZCa5pijSUCw7QKgBs6nkvBBzbEjTMKYSt6iwCDQdIYc\"\n  }\n}\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`primitives headers`\u003c/summary\u003e\u003cbr\u003e\n\nGenerate signed headers.\n\n```sh\n$ vestauth primitives headers GET http://example.com --pp\n{\n  \"Signature\": \"sig1=:K7z3Nozcq1z5zfJhrd540DWYbjyQ1kR/S7ZDcMXE5gVhxezvG6Rn9BxEvfteiAnBuQhOkvbpGtF83WpQQerGBw==:\",\n  \"Signature-Input\": \"sig1=(\\\"@authority\\\");created=1770263541;keyid=\\\"_4GFBGmXKinLBoh3-GJZCiLBt-84GP9Fb0iBzmYncUg\\\";alg=\\\"ed25519\\\";expires=1770263841;nonce=\\\"0eu7hVMVFm61lQvIryKNmZXIbzkkgpVocoKvN0de5QO8Eu5slTxklJAcVLQs0L_UTVtx4f8qJcqYZ21JTeOQww\\\";tag=\\\"web-bot-auth\\\"\",\n  \"Signature-Agent\": \"sig1=agent-35e4a794a904d227ee2373b6.api.vestauth.com\"\n}\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`primitives verify`\u003c/summary\u003e\u003cbr\u003e\n\nVerify signed headers.\n\n```sh\n$ vestauth primitives verify GET https://api.vestauth.com/whoami --signature \"sig1=:UHqXQbWZmyYW40JRcdCl+NLccLgPmcoirUKwLtdcpEcIgxG2+i+Q2U3yIYeMquseON3fKm29WSL2ntHeRefHBQ==:\" --signature-input \"sig1=(\\\"@authority\\\");created=1770395703;keyid=\\\"FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM\\\";alg=\\\"ed25519\\\";expires=1770396003;nonce=\\\"O8JOC1reBofwbpPcdD-MRRCdrtAf4khvJTuhpRI_RiaH_hpU93okLkmPZVFFcUEdYtYfcduaB8Sca54GTd2GXA\\\";tag=\\\"web-bot-auth\\\"\" --signature-agent \"sig1=agent-609a4fd2ebf4e6347108c517.api.vestauth.com\"\n{\"uid\":\"agent-609a4fd2ebf4e6347108c517\", ...}\n```\n\n\u003c/details\u003e\n\n### Library 📦\n\nUse vestauth directly in code.\n\n\u003cdetails\u003e\u003csummary\u003e`tool.verify()`\u003c/summary\u003e\u003cbr\u003e\n\nVerify and authenticate an agent's cryptographic identity.\n\n```js\nconst agent = await vestauth.tool.verify(httpMethod, url, headers)\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e`primitives.verify()`\u003c/summary\u003e\u003cbr\u003e\n\nVerify and authenticate a signed http request.\n\n```js\nawait vestauth.primitives.verify(httpMethod, url, headers, publicJwk)\n```\n\n\u003c/details\u003e\n\n\u0026nbsp;\n\n## Standards\n\n\u003e Vestauth gives agents a cryptographic identity and a simple way to authenticate HTTP requests. Most agent systems rely on API keys, bearer tokens, or username/passwords. These approaches are difficult to rotate, easy to leak, and hard to attribute to a specific agent. Vestauth replaces shared secrets with public/private key cryptography. Agents sign requests using a private key, and tools verify those requests using the agent's public key. All built on open internet standards. It's elegant and the future.\n\n| Specification | Purpose |\n|------------|------------|\n| **[RFC 9421](https://datatracker.ietf.org/doc/rfc9421/)** | Defines how requests are cryptographically signed and verified |\n| **[Web-Bot-Auth Draft](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture)** | Defines headers and authentication architecture for autonomous agents |\n\nVestauth follows these specifications to ensure interoperability between agents and tools while avoiding vendor lock-in. Vestauth focuses on developer ergonomics while staying compliant with these emerging standards.\n\n\u0026nbsp;\n\n## Compare\n\n**Agent + Tool Matrix** – Compare Vestauth vs existing auth.\n\n| Capability | Vestauth | API Keys | OAuth | Cookies |\n|---|---|---|---|---|\n| **Agent: no browser required** | ✅ | ✅ | ⚠️ (depends on flow) | ❌ |\n| **Agent: easy to automate** | ✅ | ✅ | ⚠️ | ❌ |\n| **Agent: no shared secret** | ✅ | ❌ | ⚠️ (bearer tokens) | ❌ |\n| **Agent: per‑request identity proof** | ✅ | ❌ | ⚠️ (token‑based) | ❌ |\n| **Agent: easy key/token rotation** | ✅ | ⚠️ | ⚠️ | ⚠️ |\n| **Tool: no secret storage** | ✅ (public keys only) | ❌ | ❌ | ❌ |\n| **Tool: strong attribution to agent** | ✅ | ⚠️ | ⚠️ | ❌ |\n| **Tool: stateless verification** | ✅ | ✅ | ✅ | ❌ |\n| **Tool: simple to implement** | ⚠️ (sig verification) | ✅ | ❌ | ✅ |\n| **Tool: revocation control** | ✅ | ⚠️ | ✅ | ⚠️ |\n\nLegend: ✅ strong fit, ⚠️ partial/conditional, ❌ poor fit\n\n#### How It Works\n\n1. An agent generates a public/private keypair.\n2. The agent signs each HTTP request with its private key.\n3. The tool verifies the signature using the agent’s public key.\n4. Requests are attributable, auditable, and do not require shared secrets or browser sessions.\n\n\u0026nbsp;\n\n## FAQ\n\n\u003cdetails\u003e\u003csummary\u003eWhat problem does Vestauth solve?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Vestauth gives agents a cryptographic identity and a simple way to authenticate HTTP requests.\n\u003e\n\u003e Most agent systems rely on API keys, bearer tokens, or username/passwords. These approaches are difficult to rotate, easy to leak, and hard to attribute to a specific agent.\n\u003e\n\u003e Vestauth replaces shared secrets with public/private key cryptography. Agents sign requests using a private key, and tools verify those requests using the agent's public key.\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eIs there a demo video?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Yes\n\u003e\n\u003e [Watch the demo](https://www.youtube.com/watch?v=cHARyULr_qk)\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eWhy not just use API keys?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e API keys are shared secrets. Anyone who obtains the key can impersonate the client, and keys are difficult to rotate safely.\n\u003e\n\u003e Vestauth uses cryptographic signing instead of shared secrets. This allows tools to verify identity without storing or distributing sensitive credentials.\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eWhere are agent keys stored?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Agent keys are generated locally and stored in the agent's environment configuration (`.env`).\n\u003e\n\u003e * `AGENT_PRIVATE_JWK` is used to sign requests and must never be shared.\n\u003e * `AGENT_PUBLIC_JWK` is safe to publish and is used by tools for verification.\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eIs Vestauth only for AI agents?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e No.\n\u003e\n\u003e Vestauth can authenticate any automated system including:\n\u003e\n\u003e * developer tools\n\u003e * CLIs\n\u003e * automation services\n\u003e * bots\n\u003e * infrastructure tools\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eCan Vestauth work without curl?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Yes.\n\u003e\n\u003e Vestauth provides libraries and primitives that can be integrated into any HTTP client or framework. The CLI simply makes it easy to adopt and demonstrate.\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eDo I need to run a Vestauth server?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e No.\n\u003e\n\u003e Vestauth is primarily a client-side and verification library. Agents generate keys locally and sign requests directly. Tools verify requests using public keys exposed via .well-known discovery endpoints.\n\u003e\n\u003e There is no central authentication server required.\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eCan I host my own Vestauth server?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Yes.\n\u003e\n\u003e To host your own Vestauth server create the database, run the migrations, and start the server.\n\u003e\n\u003e ```\n\u003e $ vestauth server db:create\n\u003e $ vestauth server db:migrate\n\u003e $ vestauth server start\n\u003e vestauth server listening on http://localhost:3000\n\u003e ```\n\u003e\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\u003csummary\u003eWhy does Vestauth use Ed25519 keys?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Ed25519 provides:\n\u003e\n\u003e * Strong modern cryptographic security\n\u003e * Fast signing and verification\n\u003e * Small key sizes\n\u003e * Wide ecosystem support\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eHow does Vestauth authentication work?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Vestauth uses HTTP Message Signatures ([RFC 9421](https://datatracker.ietf.org/doc/rfc9421/)). Each request is signed using the agent's private key. The request includes signed headers such as:\n\u003e\n\u003e * Signature\n\u003e * Signature-Input\n\u003e * Signature-Agent\n\u003e\n\u003e Tools verify the request by retrieving the agent's public key from a discovery endpoint and verifying the signature cryptographically.\n\u003e\n\u003e If the signature is valid, the tool knows the request was created by the agent that owns that private key.\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eHow does Vestauth prevent replay attacks?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Vestauth prevents replay attacks using multiple mechanisms built into HTTP Message Signatures.\n\u003e\n\u003e Each signed request includes:\n\u003e\n\u003e * created timestamp - limits how old a signature can be\n\u003e * expires timestamp - defines a short validity window\n\u003e * nonce value - ensures each request is unique\n\u003e\n\u003e Tools verify that:\n\u003e\n\u003e 1. The signature is still within the allowed time window\n\u003e 2. The nonce has not been used before\n\u003e 3. The signature cryptographically matches the request\n\u003e\n\u003e Because signatures are short-lived and tied to unique nonce values, an intercepted request cannot be reused successfully.\n\u003e\n\u003e Tools may optionally store nonce values for additional replay protection.\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eWhy does Vestauth use public key discovery?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Public key discovery allows tools to verify agent signatures without manual key exchange. Each agent hosts its public keys in a standardized .well-known directory.\n\u003e\n\u003e This enables dynamic agent onboarding while preserving cryptographic verification.\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eDoes Vestauth send secrets over the network?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e No.\n\u003e\n\u003e Vestauth signs requests using private keys locally. Only public keys are shared for verification.\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eHow does Vestauth avoid SSRF during public key discovery?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Vestauth prevents Server-Side Request Forgery (SSRF) by restricting public key discovery to trusted domains.\n\u003e\n\u003e By default, Vestauth only resolves agent discovery endpoints inside the controlled namespace:\n\u003e\n\u003e ```ini\n\u003e *.api.vestauth.com\n\u003e ```\n\u003e\n\u003e When a tool verifies a request, Vestauth converts the agent identity into a fixed .well-known endpoint within this trusted domain. Because this domain is controlled by Vestauth, tools never fetch attacker-supplied URLs or internal network addresses.\n\u003e\n\u003e This removes the most common SSRF attack vector during signature verification.\n\u003e\n\u003e **Custom trusted discovery domains**\n\u003e\n\u003e Tools can optionally configure additional trusted discovery domains using:\n\u003e\n\u003e ```ini\n\u003e TOOL_FQDN_REGEX\n\u003e ```\n\u003e\n\u003e This allows organizations to:\n\u003e\n\u003e * Host their own agent discovery infrastructure\n\u003e * Support private internal agents\n\u003e * Implement federated trust models\n\u003e\n\u003e For example:\n\u003e\n\u003e ```ini\n\u003e TOOL_FQDN_REGEX=\".*\\.agents\\.vestauth\\.com|.*\\.agents\\.example\\.internal\"\n\u003e ```\n\u003e\n\u003e Only discovery endpoints matching this allowlist will be fetched.\n\u003e\n\u003e **Defense in depth**\n\u003e\n\u003e Even with domain scoping, tools may optionally add safeguards such as:\n\u003e\n\u003e * HTTPS-only enforcement\n\u003e * Request timeouts\n\u003e * Response size limits\n\u003e * Public key caching\n\u003e\n\u003e Vestauth removes SSRF by design, while still allowing controlled federation when needed.\n\n\u0026nbsp;\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eWhy does Vestauth use .well-known discovery instead of embedding public keys directly?\u003c/summary\u003e\u003cbr\u003e\n\n\u003e Vestauth uses .well-known discovery to keep requests small, enable key rotation, and support long-term identity management.\n\u003e\n\u003e Embedding public keys directly in every request would increase header size, reduce caching opportunities, and make key rotation difficult. By publishing keys through a discovery endpoint, Vestauth allows tools to fetch and cache keys independently from individual requests.\n\u003e\n\u003e This approach provides several benefits:\n\u003e\n\u003e **Efficient requests**\n\u003e\n\u003e Public keys are retrieved once and can be cached by tools. Agents do not need to send large key material with every request.\n\u003e\n\u003e **Key rotation support**\n\u003e\n\u003e Agents can rotate signing keys without changing their identity. Tools simply refresh keys from the discovery endpoint.\n\u003e\n\u003e **Multi-key support**\n\u003e\n\u003e Agents can safely publish multiple active keys (for rotation or staged rollouts) using the standard HTTP Message Signatures directory format.\n\u003e\n\u003e **Standards alignment**\n\u003e\n\u003e Vestauth follows the discovery model used in:\n\u003e\n\u003e * HTTP Message Signatures directories\n\u003e * OAuth / OpenID Connect key discovery\n\u003e * Web identity federation systems\n\n\u003c/details\u003e\n\n\u0026nbsp;\n\n## Contributing\n\nYou can fork this repo and create [pull requests](https://github.com/vestauth/vestauth/pulls) or if you have questions or feedback:\n\n* [github.com/vestauth/vestauth](https://github.com/vestauth/vestauth/issues) - bugs and discussions\n* [@vestauth 𝕏](https://x.com/vestauthx) (DMs are open)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvestauth%2Fvestauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvestauth%2Fvestauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvestauth%2Fvestauth/lists"}