From 39809c736baef2b5112adbe03f643f0bc616c16a Mon Sep 17 00:00:00 2001 From: Steve Boyd Date: Tue, 9 Apr 2024 16:09:20 +1200 Subject: [PATCH] DOC Linting --- .doclintrc | 1 + README.md | 4 ++-- composer.json | 6 ++++++ docs/en/{readme.md => index.md} | 32 +++++++++++++++++++++----------- 4 files changed, 30 insertions(+), 13 deletions(-) create mode 100644 .doclintrc rename docs/en/{readme.md => index.md} (77%) diff --git a/.doclintrc b/.doclintrc new file mode 100644 index 0000000..15a00f5 --- /dev/null +++ b/.doclintrc @@ -0,0 +1 @@ +/docs/en/ diff --git a/README.md b/README.md index 56c174d..15e284f 100644 --- a/README.md +++ b/README.md @@ -17,13 +17,13 @@ authenticators such as fingerprint scanners. More information on this can be fou ## Installation -```sh +```bash composer require silverstripe/webauthn-authenticator ``` ## Documentation -For detailed developer and CMS user documentation, see [the documentation readme](docs/en/readme.md). +Read the [WebAuthn authenticator documentation](https://docs.silverstripe.org/en/optional_features/mfa/authentictors/webauthn). ## License diff --git a/composer.json b/composer.json index 01a6cee..a64d44a 100644 --- a/composer.json +++ b/composer.json @@ -18,6 +18,7 @@ "require-dev": { "phpunit/phpunit": "^9.6", "squizlabs/php_codesniffer": "^3", + "silverstripe/documentation-lint": "^1", "silverstripe/standards": "^1", "phpstan/extension-installer": "^1.3" }, @@ -33,6 +34,11 @@ "client/lang" ] }, + "config": { + "allow-plugins": { + "dealerdirect/phpcodesniffer-composer-installer": true + } + }, "minimum-stability": "dev", "prefer-stable": true } diff --git a/docs/en/readme.md b/docs/en/index.md similarity index 77% rename from docs/en/readme.md rename to docs/en/index.md index c3fc8d1..545da47 100644 --- a/docs/en/readme.md +++ b/docs/en/index.md @@ -1,6 +1,16 @@ -# Developer documentation +--- +title: WebAuthn Authenticator +--- -## What is Web Authentication (WebAuthn)? +# WebAuthn authenticator + +## Installation + +```bash +composer require silverstripe/webauthn-authenticator +``` + +## What is web authentication (`WebAuthn`)? We use the [web-auth/webauthn-framework PHP library](https://github.com/web-auth/webauthn-framework) to provide support for the Web Authentication protocol: @@ -8,7 +18,7 @@ for the Web Authentication protocol: > Webauthn defines an API enabling the creation and use of strong, attested, scoped, public key-based credentials by > web applications, for the purpose of strongly authenticating users. -This module is a SilverStripe wrapper for implementing this library, and provides the frontend UI components to work +This module is a Silverstripe wrapper for implementing this library, and provides the frontend UI components to work with [the silverstripe/mfa module](https://github.com/silverstripe/silverstripe-mfa). For more information about WebAuthn, see [the Guide to Web Authentication](https://webauthn.guide/). @@ -21,30 +31,30 @@ You can configure (or remove) the "help" links shown to users when the "Security option is shown in multi-factor authentication registration or verification flows by adjusting the user help link in configuration: -```yaml +```yml SilverStripe\WebAuthn\RegisterHandler: user_help_link: 'http://intranet.mycompany.com/help/how-to-use-mfa' ``` -### Authenticator Selection Criteria +### Authenticator selection criteria The way the `Webauthn\AuthenticatorSelectionCriteria` instance is configured will define how appropriate authenticators are selected to participate in the creation operation of WebAuthn attestations. It has three settings, which are explained in [the MDN web docs for authenticatorSelection](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredentialCreationOptions/authenticatorSelection#Syntax). -The SilverStripe WebAuthn module allows you to configure the `authenticatorAttachment` option, which is responsible +The Silverstripe WebAuthn module allows you to configure the `authenticatorAttachment` option, which is responsible for determining whether single or cross-platform authenticators can be used in the registration operation. The default is that devices must be cross-platform (e.g. security keys) while single-platform devices (e.g. touch ID on mobile phones) are disabled. You can adjust this setting by configuring -`SilverStripe\WebAuthn\RegisterHandler.authenticator_attachment` to use one of these options: +[`RegisterHandler.authenticator_attachment`](api:SilverStripe\WebAuthn\RegisterHandler->authenticator_attachment) to use one of these options: -* `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE`: allows either -* `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM`: single-platform only -* `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_CROSS_PLATFORM `: cross-platform only +- `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE`: allows either +- `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM`: single-platform only +- `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_CROSS_PLATFORM`: cross-platform only For more information, see [Authenticator Selection Criteria](https://github.com/web-auth/webauthn-framework/blob/v1.2/doc/webauthn/PublicKeyCredentialCreation.md#authenticator-selection-criteria) -## Compatibility with Subsites +## Compatibility with subsites This module is not recommended for use if your project has the [silverstripe/subsites](https://github.com/silverstripe/silverstripe-subsites) module installed.