From 5ed542cb1887e077dc6d6fb875faf322b449d4fb Mon Sep 17 00:00:00 2001 From: Gregor Date: Tue, 2 Jul 2019 15:57:30 -0700 Subject: [PATCH 1/3] docs(README): initial version --- README.md | 536 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 536 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d79a8a8 --- /dev/null +++ b/README.md @@ -0,0 +1,536 @@ +# 🚧 This library is work in progress + +# auth-basic.js + +> Basic authentication for browsers and Node.js + +`@octokit/auth-basic` is implementing one of [GitHub’s authentication strategies](https://github.com/octokit/auth.js). + +Authenticating using username and password. + +GitHub recommends to use basic authentication only for managing [personal access tokens](https://github.com/settings/tokens). Other endpoints won’t even work if a user enabled [two-factor authentication](https://github.com/settings/security) ith SMS as method, because an SMS with the time-based one-time password (TOTP) will only be sent if a request is made to one of these endpoints + +- [`POST /authorizations`](https://developer.github.com/v3/oauth_authorizations/#create-a-new-authorization) - Create a new authorization +- [`PUT /authorizations/clients/:client_id`](https://developer.github.com/v3/oauth_authorizations/#get-or-create-an-authorization-for-a-specific-app) - Get-or-create an authorization for a specific app +- [`PUT /authorizations/clients/:client_id/:fingerprint`](https://developer.github.com/v3/oauth_authorizations/#get-or-create-an-authorization-for-a-specific-app-and-fingerprint) - Get-or-create an authorization for a specific app and fingerprint +- [`PATCH /authorizations/:authorization_id`](https://developer.github.com/v3/oauth_authorizations/#update-an-existing-authorization) - Update an existing authorization +- [`DELETE /authorizations/:authorization_id`](https://developer.github.com/v3/oauth_authorizations/#delete-an-authorization) - Delete an authorization + +By default, `@octokit/auth` implements this best practice and retrieves a personal access token. + +Some endpoint however do require basic authentication, such as [List your authorizations](https://developer.github.com/v3/oauth_authorizations/#list-your-authorizations) or [Delete an authorization](https://developer.github.com/v3/oauth_authorizations/#delete-an-authorization). In order to retrieve the right authentication for the right endpoint, you can pass an optional `url` parameter to `auth()`. + +## Usage + +Minimal + +```js +import { createBasicAuth } from "@octokit/auth"; + +const auth = createBasicAuth({ + username: "octocat", + password: "secret", + async on2Fa() { + // prompt user for the one-time password retrieved via SMS or authenticator app + return prompt("Two-factor authentication Code:"); + } +}); + +const authentication = await auth(); +``` + +All strategy options + +```js +import { createBasicAuth } from "@octokit/auth"; + +const auth = createBasicAuth({ + username: "octocat", + password: "secret", + async on2Fa() { + return prompt("Two-factor authentication Code:"); + }, + token: { + note: "octokit 2019-04-03 abc4567", + scopes: [], + noteUrl: "https://github.com/octokit/auth.js#basic-auth", + fingerprint: "abc4567", + clientId: "1234567890abcdef1234", + clientSecret: "1234567890abcdef1234567890abcdef12345678" + } +}); +``` + +Retrieve basic authentication + +```js +const authentication = await auth({ url: "/authorizations/:authorization_id" }); +``` + +## `createBasicAuth(token)` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ name + + type + + description +
+ username + + string + + Required. Username of the account to login with. +
+ password + + string + + Required. Password of the account to login with. +
+ on2Fa + + function + + Required. If the user has two-factor authentication (2FA) enabled, the on2Fa method will be called and expected to return a time-based one-time password (TOTP) which the user retrieves either via SMS or an authenticator app, based on their account settings. You can pass an empty function if you are certain the account has 2FA disabled.
+
+ Alias: on2fa +
+ token + + object + + An object matching "Create a new authorization" parameters, but camelCased. +
+ token.note + + string + + A note to remind you what the OAuth token is for. Personal access tokens must have a unique note. Attempting to create a token with with an existing note results in a 409 conflict error.
+
+ Defaults to "octokit <timestamp> <fingerprint>", where <timestamp> has the format YYYY-MM-DD and <fingerprint> is a random string. Example: "octokit 2019-04-03 abc4567". +
+ token.scopes + + array of strings + + A list of scopes that this authorization is in. See available scopes
+
+ Defaults to an empty array +
+ token.noteUrl + + string + + A URL to remind you what app the OAuth token is for.
+
+ Defaults to "https://github.com/octokit/auth.js#basic-auth" +
+ token.fingerprint + + string + + A unique string to distinguish an authorization from others created for the same client ID and user.
+
+ Defaults to a random string +
+ token.clientId + + string + + The 20 character OAuth app client key for which to create the token. +
+ token.clientSecret + + string + + The 40 character OAuth app client secret for which to create the token.
+
+ Note: do not share an OAuth app’s client secret with an untrusted client such as a website or native app. +
+ +## `auth()` + + + + + + + + + + + + + + + + + + + + + +
+ name + + type + + description +
+ url + + string + + An absolute URL or endpoint route path. Examples +
    +
  • "https://enterprise.github.com/api/v3/authorizations"
    • +
  • "/authorizations/123"
    • +
  • "/authorizations/:authorization_id"
    • +
+
+ refresh + + boolean + + Information for a personal access token is retrieved from GET /user and cached for subsequent requests. To bypass and update cache, set refresh to true.
+
+ Defaults to false. +
+ +## Authentication object + +### Authentication object + +There are three possible results + +1. **A personal access token authentication** + ❌ `url` parameter _does not_ match and endpoint requiring basic authentication + ❌ `basic.token.clientId` / `basic.token.clientSecret` not passed as strategy options. +2. **An oauth access token authentication** + ❌ `url` parameter _does not_ match and endpoint requiring basic authentication + ✅ `basic.token.clientId` / `basic.token.clientSecret` passed as strategy options. +3. **Basic authentication** + ✅ `url` parameter matches and endpoint requiring basic authentication. + +#### Personal access token authentication + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ name + + type + + description +
+ type + + string + + "token" +
+ token + + string + + The personal access token +
+ user + + object + + { login, id } - username and database id +
+ scopes + + array of strings + + array of scope names +
+ headers + + object + + { authorization } - value for the "Authorization" header. +
+ query + + object + + {} - not used +
+ +#### OAuth access token authentication + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ name + + type + + description +
+ type + + string + + "token" +
+ token + + string + + The oauth access token +
+ user + + object + + { login } - username +
+ scopes + + array of strings + + array of scope names +
+ headers + + object + + { authorization } - value for the "Authorization" header. +
+ query + + object + + {} - not used +
+ +#### Basic authentication result + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ name + + type + + description +
+ type + + string + + "basic" +
+ username + + string + + The decoded username +
+ password + + string + + The decoded password +
+ user + + object + + { login, id } - username and database id +
+ headers + + object + + { authorization } - value for the "Authorization" header. +
+ query + + object + + {} - not used +
+ +## License + +[MIT](LICENSE) From adf04052588d1083944956df59d8de32b2c5da85 Mon Sep 17 00:00:00 2001 From: Gregor Date: Tue, 2 Jul 2019 15:57:41 -0700 Subject: [PATCH 2/3] docs(LICENSE): MIT --- LICENSE | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ef2c18e --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +The MIT License + +Copyright (c) 2019 Octokit contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. From ca91e56cb1d75453c92b7a724ca08a4def77005f Mon Sep 17 00:00:00 2001 From: Gregor Date: Tue, 2 Jul 2019 15:57:51 -0700 Subject: [PATCH 3/3] docs(CODE_OF_CONDUCT): contributor covenant --- CODE_OF_CONDUCT.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..8124607 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,46 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at opensource+octokit@github.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/