{"id":20913807,"url":"https://github.com/strangerlabs/webauthn","last_synced_at":"2025-04-29T23:28:33.236Z","repository":{"id":38991386,"uuid":"185597704","full_name":"strangerlabs/webauthn","owner":"strangerlabs","description":"W3C Web Authentication API Relying Party for Node.js and Express","archived":false,"fork":false,"pushed_at":"2023-01-05T05:48:59.000Z","size":1699,"stargazers_count":86,"open_issues_count":36,"forks_count":28,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-30T12:21:54.857Z","etag":null,"topics":["authentication","ctap2","express","express-middleware","expressjs","fido2","password-replacement","webauthn"],"latest_commit_sha":null,"homepage":"","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/strangerlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-08T12:02:59.000Z","updated_at":"2024-11-23T22:19:10.000Z","dependencies_parsed_at":"2023-02-03T14:15:21.681Z","dependency_job_id":null,"html_url":"https://github.com/strangerlabs/webauthn","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangerlabs%2Fwebauthn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangerlabs%2Fwebauthn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangerlabs%2Fwebauthn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangerlabs%2Fwebauthn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strangerlabs","download_url":"https://codeload.github.com/strangerlabs/webauthn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251598943,"owners_count":21615438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","ctap2","express","express-middleware","expressjs","fido2","password-replacement","webauthn"],"created_at":"2024-11-18T15:08:03.023Z","updated_at":"2025-04-29T23:28:33.211Z","avatar_url":"https://github.com/strangerlabs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebAuthn\n\n[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)\n[![build-status](https://travis-ci.com/strangerlabs/webauthn.svg?branch=master)](https://travis-ci.com/strangerlabs/webauthn)\n[![codecov](https://codecov.io/gh/strangerlabs/webauthn/branch/master/graph/badge.svg)](https://codecov.io/gh/strangerlabs/webauthn)\n\n\u003e W3C Web Authentication API Relying Party for Node.js and Express\n\nWebAuthn is a [W3C standard][w3c] that enables web developers to replace passwords in their applications with [FIDO authentication][fido2]. This repository implements a NPM package for use in Node.js services. **This package is in active development and not yet ready for production use. You can use it to kick the tires on WebAuthn. Please file issues to ask questions or provide feedback.**\n\n[w3c]: https://w3c.github.io/webauthn/\n[fido2]: https://fidoalliance.org/fido2/\n\n## Table of Contents\n\n- [WebAuthn](#webauthn)\n  - [Table of Contents](#table-of-contents)\n  - [Security](#security)\n  - [Install](#install)\n  - [Usage](#usage)\n  - [API](#api)\n    - [Relying Party](#relying-party)\n    - [Storage Adapater](#storage-adapater)\n    - [Browser Client](#browser-client)\n  - [Maintainers](#maintainers)\n  - [Contributing](#contributing)\n    - [Issues](#issues)\n    - [Pull requests](#pull-requests)\n      - [Policy](#policy)\n      - [Style guide](#style-guide)\n      - [Code reviews](#code-reviews)\n    - [Tests](#tests)\n    - [Code of conduct](#code-of-conduct)\n  - [License](#license)\n\n## Security\n\nThis package is not yet ready for use in production software. For more information on security considerations see [W3C Web Authentication][w3c-sec] and [FIDO Security Reference][fido-sec].\n\n[w3c-sec]: https://w3c.github.io/webauthn/#security-considerations\n[fido-sec]: https://fidoalliance.org/specs/fido-v2.0-rd-20180702/fido-security-ref-v2.0-rd-20180702.html\n\n## Install\n\n```sh\n$ npm install webauthn\n```\n\n## Usage\n\nSee [examples](./example) for a complete example. The package currently works on its own and we plan to support Passport.js integration in future releases.\n\n```javascript\nconst WebAuthn = require('webauthn')\n\n// configure express and session middleware; see \"examples\" in this repository\n// ...\n\n// Create webauthn\nconst webauthn = new WebAuthn({\n  origin: 'http://localhost:3000',\n  usernameField: 'username',\n  userFields: {\n    username: 'username',\n    name: 'displayName',\n  },\n  store: new LevelAdapter(),\n  // OR\n  // store: {\n  //   put: async (id, value) =\u003e {/* return \u003cvoid\u003e */},\n  //   get: async (id) =\u003e {/* return User */},\n  //   search: async (search) =\u003e {/* return { [username]: User } */},\n  //   delete: async (id) =\u003e {/* return boolean */},\n  // },\n  rpName: 'Stranger Labs, Inc.',\n  enableLogging: false,\n})\n\n// Mount webauthn endpoints\napp.use('/webauthn', webauthn.initialize())\n\n// Endpoint without passport\napp.get('/secret', webauthn.authenticate(), (req, res) =\u003e {\n  res.status(200).json({ status: 'ok', message: 'Super Secret!' })\n})\n```\n\nClient\n\n```javascript\nimport Client from 'webauthn/client'\n\nconst client = new Client({ pathPrefix: '/webauthn' })\n\nawait client.register({\n  username: 'AL1C3',\n  name: 'Alice',\n})\n\n// ...\n\nawait client.login({ username: 'AL1C3' })\n```\n\n## API\n\n[cred-mgmt-api]: https://developer.mozilla.org/en-US/docs/Web/API/Credential_Management_API\n[express-js-router]: https://expressjs.com/en/api.html#express.router\n[express-js-middleware]: https://expressjs.com/en/guide/using-middleware.html\n\n### Relying Party\n\n**`new WebAuthn(options)`**\n\nThe main entrypoint for creating a new WebAuthn RP instance. `options` is used\nto configure the behaviour of the RP. Available options include:\n\n- `origin` - The origin of the deployed application.\n- `rpName` - The display name of RP. This will be shown in the WebAuthn consent\ninterface.\n- `[usernameField = 'name']` - The name of the field that uniquely identifies a\nuser.\n- `[userFields = ['name', 'displayName'] ]` - One of:\n  - An array of properties from registration request to be included in the saved\n  user object\n  - An object mapping, where the key is the name of a property from the\n  registration request to be included in the user object and the value is the\n  name of that property on the user object.\n- `[store = MemoryAdapter]` - The storage interface for user objects. Defaults\nto an object in memory (for testing only).\n- `[attestation = 'none']` - the [attestation conveyance preference](\nhttps://w3c.github.io/webauthn/#enum-attestation-convey). Setting this to\nanything other than `'none'` will require attestation and validate it.\n- `[credentialEndpoint = '/register']` - the path of the credential attestation\nchallenge endpoint.\n- `[assertionEndpoint = '/login']` - the path of the challenge assertion\nendpoint.\n- `[challengeEndpoint = '/response']` - the path of the challenge response\nendpoint.\n- `[logoutEndpoint = '/logout']` - the path of the logout endpoint.\n- `[enableLogging = true]` - Enable or disable logging to stdout.\n\n**`webauthn.initialize()`**\n\nReturns an [Express Router][express-js-router] with the mounted WebAuthn\nendpoints.\n\n**`webauthn.authenticate([options])`**\n\nReturns an [Express Middleware][express-js-middleware] that will set `req.user`\nfor subsequent middlewares, or produce a `401 Unauthorized` error if the user is\nnot authenticated. Available options include:\n\n- `[failureRedirect]` - If the user fails to authenticate then they will be\nredirected to the supplied URL.\n\n### Storage Adapater\n\nStorage adapters provide an interface to the WebAuthn RP to store and retrieve\ndata necessary for authentication, such as authenticator public keys. Storage\nadapters must implement the following interface:\n\n**`async get (id)`**\n\nRetrieves and returns the previously stored object with the provided `id`.\n\n**`async put (id, value)`**\n\nStores an object so that it may be retrieved with the provided `id`. Returns\nnothing.\n\n**`async search (startsWith, [options])`**\n\nReturns a mapping of objects where the `id` of the objects return starts with\nthe provided query value. Available options include:\n\n- `limit`: Return the first N results.\n- `reverse`: Return results in reverse lexicographical order. If used in\nconjunction with limit then the _last_ N results are returned.\n\n**`async delete (id)`**\n\nDelete a previously stored object. Returns a boolean indicating success.\n\n### Browser Client\n\n**`new Client([options])`**\n\nConstructs a new client for handling interaction with the Web Authentication API\nand the server authentication endpoints. Available options include:\n\n- `[pathPrefix = '/webauthn']` - A mounting prefix to all authorization\nendpoints.\n- `[credentialEndpoint = '/register']` - The path of the credential registration\nendpoint.\n- `[assertionEndpoint = '/login']` - The path of the challenge assertion\nendpoint.\n- `[challengeEndpoint = '/response']` - The path of the challenge response\nendpoint.\n- `[logoutEndpoint = '/logout']` - The path of the logout endpoint.\n\nReturns a new client instance.\n\n**`async client.register(data)`**\n\nCompletes a start-to-finish registration of a new authenticator at the remote\nservice with the following steps:\n\n1. Fetch a register credential challenge from the remote server's\n`credentialEndpoint`.\n2. Prompt the [Credentials Management API][cred-mgmt-api] to generate a new\nlocal credential.\n   - The Credentials Management API prompts the user for consent.\n   - The challenge is signed using the user-selected method and returned.\n3. The signed challenge is returned to the remote server's `challengeEndpoint`.\n\nReturns the response of the request to the `challengeEndpoint`.\n\n**`async client.login(data)`**\n\nCompletes a start-to-finish assertion challenge on a previously registered\nremote service with the following steps:\n\n1. Fetch an assertion challenge from the remote server's `assertionEndpoint`.\n2. Prompt the [Credentials Management API][cred-mgmt-api] to get an existing\nlocal credential and sign the response.\n   - The Credentials Management API prompts the user for consent.\n   - The challenge is signed and returned.\n3. The signed challenge is returned to the remote server's `challengeEndpoint`.\n\nReturns the response of the request to the `challengeEndpoint`.\n\n**`async client.logout()`**\n\nDestroys the current session on the remote server. Returns the result of the\nrequest to the `logoutEndpoint`.\n\n## Maintainers\n\n[@Terrahop](https://github.com/Terrahop)\n\n[@EternalDeiwos](https://github.com/EternalDeiwos)\n\n[@christiansmith](https://github.com/christiansmith)\n\nOriginally adapted from [fidoalliance/webauthn-demo](https://github.com/fido-alliance/webauthn-demo).\n\n## Contributing\n\n### Issues\n\n* Please file [issues](https://github.com/strangerlabs/webauthn/issues) :)\n* When writing a bug report, include relevant details such as platform, version, relevant data, and stack traces\n* Ensure to check for existing issues before opening new ones\n* Read the documentation before asking questions\n* It is strongly recommended to open an issue before hacking and submitting a PR\n\n### Pull requests\n\n#### Policy\n\n* We're not presently accepting *unsolicited* pull requests\n* Create an issue to discuss proposed features before submitting a pull request\n* Create an issue to propose changes of code style or introduce new tooling\n* Ensure your work is harmonious with the overall direction of the project\n* Ensure your work does not duplicate existing effort\n* Keep the scope compact; avoid PRs with more than one feature or fix\n* Code review with maintainers is required before any merging of pull requests\n* New code must respect the style guide and overall architecture of the project\n* Be prepared to defend your work\n\n#### Style guide\n\n* [Conventional Changelog](https://github.com/conventional-changelog/conventional-changelog)\n* [ECMAScript](https://tc39.github.io/ecma262/)\n* [Standard JavaScript](https://standardjs.com)\n* [Standard README](https://github.com/RichardLitt/standard-readme)\n* [jsdoc](https://jsdoc.app)\n\n#### Code reviews\n\n* required before merging PRs\n* reviewers MUST run and test the code under review\n\n### Tests\n\nRun the test suite with `npm test`.\n\n### Code of conduct\n\n* @strangerlabs/webauthn follows the [Contributor Covenant](http://contributor-covenant.org/version/1/3/0/) Code of Conduct.\n\n## License\n\nMIT © 2019 Stranger Labs, Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrangerlabs%2Fwebauthn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrangerlabs%2Fwebauthn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrangerlabs%2Fwebauthn/lists"}