Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,13 @@ The first release. Nothing is tagged yet.

- A security log with a severity and a request ID on every entry, of sign ins, failures, lockouts, changes and what was refused, capped so a refused request can't fill it. Without the table it goes to your app's log.
- "Was this you?" alerts at the next sign in.
- Security emails, each a notification published into your app. The installer registers the ones about changes to how an account signs in and about suspicious attempts, as far as your features go.
- Security emails about changes to how an account signs in and about suspicious attempts, sent from the start as far as your features go. Each is a notification you can swap for your own or turn off, and `SecurityNotice::toMailUsing()` writes them all from your own template.
- `support_contact`, so every notice can say who to contact.
- `Keyring\Events\*` for everything above, with Laravel's own auth events raised beside them.

### Tooling

- `keyring:install`, which asks which sign-in methods and features you want and publishes a provider, your actions and your notifications; `keyring:import fortify`; and `keyring:prune`, scheduled daily.
- `keyring:install`, which asks which sign-in methods and features you want and publishes a config, a provider and your actions; `keyring:import fortify`; and `keyring:prune`, scheduled daily.
- Security headers on Keyring's responses: `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY` and a referrer policy.
- Test helpers, a fake, factories, a virtual WebAuthn authenticator and a conformance suite that checks your setup still keeps Keyring's guarantees.
- `@entity/keyring`, a browser package for WebAuthn, enrollment, sessions and the challenge page, with Vue and React bindings.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Fortify keeps 2FA in three columns on `users`. That gives one TOTP per user, and
- **Step-up:** `keyring:aal2` and `keyring.fresh:15m` middleware. A passkey or code counts, not just the password, and users with a second factor must use it.
- **Protected account changes:** once Keyring handles them, `email` and `password` can only change through its flows. Email changes are confirmed from both addresses and can be reverted.
- **Risk signals:** new device, new country, impossible travel, a session cookie showing up in another browser, repeated failures, a password found in a breach. Each level maps to an action, and a new app starts with the signals its features can feed.
- **A security log and security emails.** Every email is a notification class in your app, yours to reword, restyle or send another way.
- **A security log and security emails.** The emails are sent from the start, and each can be swapped for your own notification, restyled or turned off.
- **Built on OWASP ASVS 5.0.0 and NIST SP 800-63B-4:** [one page](docs/owasp-asvs.md) goes through both, requirement by requirement. Each is met, or stated as a deliberate deviation or as your app's job, with the reason.
- **Headless:** like Fortify, Keyring renders your pages with props and answers JSON, with swappable responses and published actions. A browser package handles WebAuthn and the challenge page for Vue and React.

Expand Down
4 changes: 2 additions & 2 deletions config/keyring.php
Original file line number Diff line number Diff line change
Expand Up @@ -187,8 +187,8 @@
|--------------------------------------------------------------------------
|
| Where users can reach you about their account: a page's URL or an email
| address. Every notification is handed it as $contact, and the published
| ones end with "if this wasn't you and you need help, contact us" when
| address. Every notification is handed it as $contact, and Keyring's
| own end with "if this wasn't you and you need help, contact us" when
| it's set. Null leaves the line out.
|
*/
Expand Down
8 changes: 4 additions & 4 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ Where a user who has to choose a new password is sent from every other page unti
'support_contact' => null,
```

Where users can reach you about their account: a page's URL (`'https://example.com/support'`) or an email address (`'support@example.com'`). Every notification is handed it as `$contact`, and the published security notices, the emailed code and the email change notice end with "If this wasn't you and you need help, contact us" and a link to it. `null` leaves the line out. See [Security Emails](security-log-and-emails.md#a-support-contact).
Where users can reach you about their account: a page's URL (`'https://example.com/support'`) or an email address (`'support@example.com'`). Every notification is handed it as `$contact`, and Keyring's security notices, the emailed code and the email change notice end with "If this wasn't you and you need help, contact us" and a link to it. `null` leaves the line out. See [Security Emails](security-log-and-emails.md#a-support-contact).

```php
'enrollments' => [
Expand Down Expand Up @@ -410,7 +410,7 @@ php artisan vendor:publish --tag=keyring-lang
| `Keyring::respondWith($contract, $implementation)` | Swaps a response. See [Responses](sign-in-flow.md#responses). |
| `Keyring::page($name, $component)` | Changes the component a page renders. See [Pages](sign-in-flow.md#pages). |
| `Keyring::risk()->signals([...])->respond(...)` | Configures risk signals and actions. `Keyring::risk()->push(...)` adds to the signals already on. See [Risk](risk.md). |
| `Keyring::notifications([...])` | Registers your notification class for each email Keyring sends. A security notice with none isn't sent, and unknown types throw an `InvalidArgumentException`. See [Security Emails](security-log-and-emails.md#security-emails). |
| `Keyring::notifications([...])` | Swaps the notification Keyring sends for a type with your own class, or `null` to send none. Types left out keep Keyring's own, and unknown types throw an `InvalidArgumentException`. See [Security Emails](security-log-and-emails.md#security-emails). |
| `Keyring::createUsersUsing($action)` | Sets the registration action. See [Registration](sign-in-flow.md#registration). |
| `Keyring::resetUserPasswordsUsing($action)` | Sets the password reset action. See [Resetting the Password](protected-changes.md#resetting-the-password). |
| `Keyring::updateUserPasswordsUsing($action)` | Sets the password change action. See [Changing the Password](protected-changes.md#changing-the-password). |
Expand Down Expand Up @@ -452,15 +452,15 @@ It also answers questions about your setup, for your own controllers, factors an
| `Keyring::requirementFor($user, $attempt)` | What this user must prove to finish the attempt. See [Checking Requirements in Code](policies.md#checking-requirements-in-code). |
| `Keyring::statusMessage($status)` | The translated message for a status slug, or `null`. See [Flash Messages and Alerts](frontend.md#flash-messages-and-alerts). |
| `Keyring::render($name, $props)` | Renders one of Keyring's [pages](sign-in-flow.md#pages), as Inertia or Blade, for a route of your own. |
| `Keyring::hasNotification($type)` | Whether a notification is registered for a [type](security-log-and-emails.md#email-types). |
| `Keyring::hasNotification($type)` | Whether a notification is sent for a [type](security-log-and-emails.md#email-types). |
| `Keyring::protectedAttributes($user = null)` | The attributes that only change through Keyring's flows. Pass a user whose model keeps its password under another name to get that name. See [Protected Attributes](protected-changes.md#protected-attributes). |
| `Keyring::response($contract, ...$with)` | Builds one of Keyring's [responses](sign-in-flow.md#responses), yours when you swapped it, for a route of your own. |
| `Keyring::describeDevice($userAgent)` | A user agent as a name people recognise, or `null`. |
| `Keyring::linkRoot()` | Where emailed links start. |
| `Keyring::email()` | The attribute holding the user's address, `email` by default. |
| `Keyring::policy($user, $attempt)` | What the policy asks of this user, before considering what they've enrolled. |
| `Keyring::steps()` | The pipeline's steps, in order. `Keyring::dangerouslyChangedSteps()` lists the mandatory ones an app took out. |
| `Keyring::notification($type, $arguments)` | The app's notification for a type, or `null`. `Keyring::requiredNotification()` throws when there isn't one. |
| `Keyring::notification($type, $arguments)` | The notification for a type, Keyring's own or yours, or `null` when it's turned off. `Keyring::requiredNotification()` throws when it is. |
| `Keyring::belongsToGuard($user)` | Whether Keyring's guard would load this user back, so they can be signed in. |
| `Keyring::recordedIp($request)` | The request's IP address as Keyring stores it. |
| `Keyring::allowsSignIn($user)` | Whether the app lets this user be signed in. See [Who May Sign In](sign-in-flow.md#who-may-sign-in). |
Expand Down
2 changes: 1 addition & 1 deletion docs/extending.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ This page lists them all, with where each is explained. [Recipes](recipes.md) ha
| How a user is found, and how usernames are normalised | `Keyring::findUsersUsing()`, `Keyring::normalizeUsernamesUsing()` | [Finding the User](sign-in-flow.md#finding-the-user) |
| The attribute users sign in with, and the one holding their address | `username` and `email` | [Guard and Users](configuration.md#guard-and-users) |
| Creating users, resetting and changing passwords, validating a new address | The published actions in `app/Actions/Keyring` | [Protected Changes](protected-changes.md) |
| Every email: wording, template, channel, or whether it's sent | The published notifications in `app/Notifications/Keyring` and `Keyring::notifications()` | [Security Emails](security-log-and-emails.md#security-emails) |
| Every email: wording, template, channel, or whether it's sent | `Keyring::notifications()`, with your own class for a type or `null`, and `SecurityNotice::toMailUsing()` | [Security Emails](security-log-and-emails.md#security-emails) |
| What a page renders | `Keyring::page()` | [Pages](sign-in-flow.md#pages) |
| What Keyring answers with | `Keyring::respondWith()` and the contracts in `Keyring\Contracts\Responses` | [Responses](sign-in-flow.md#responses) |
| Validation and status messages | The `keyring-lang` translation files | [Messages and Translations](configuration.md#messages-and-translations) |
Expand Down
12 changes: 6 additions & 6 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,22 +35,21 @@ php artisan migrate
> composer require entity/keyring:dev-main
> ```

The command asks four things:
The command asks three things:

1. **Which sign-in methods besides the password?** None by default. Recovery codes come with any of them. Email codes are listed as what they are, an extra step at sign in and not a second factor: a password and an emailed code is still AAL1 (see [Email Codes](factors.md#what-turning-email-codes-on-means)), and the provider says so above their line.
2. **Require a second factor for everyone?** Asked when you picked an authenticator app, passkeys or security keys, and yes by default. Users still sign in with what they have, then every page sends them to `/settings/security` until they've set one up (see [Requiring a Second Factor](policies.md#requiring-a-second-factor)). It isn't asked with the password alone or with only email codes, where nobody could meet it: then nothing requires a second factor.
3. **Which features?** Registration, password resets, email verification, changing the password and the security log by default, plus managing sign-in methods when you picked one. Registration always brings email verification, because by default [new users sign in once they've verified their address](sign-in-flow.md#without-revealing-who-has-an-account).
4. **Email users when their password, sign-in methods or email address change?** Yes by default: password changed, sign-in method added or removed, recovery code used, new recovery codes made, email address changed, account locked and a suspicious sign in or session, and with the features that give them something to announce, a sign in on a new device (devices), a second factor that failed after the right password (any sign-in method besides the password) and an email change undone (email changes). See [Security Emails](security-log-and-emails.md#security-emails).

Without prompts (`--no-interaction`, or in CI) you get the same defaults. You can also answer with options:

```bash
php artisan keyring:install --factor=totp --factor=passkeys --feature=registration --feature=manage-authenticators --require-second-factor
```

`--factor` takes `totp`, `passkeys`, `security-keys` or `email-codes`. `--feature` takes `registration`, `reset-passwords`, `email-verification`, `update-passwords`, `manage-authenticators`, `devices`, `email-changes` or `security-log`, and replaces the defaults (`registration`, `reset-passwords`, `email-verification`, `update-passwords` and `security-log`), so list those too if you want them. An unknown value stops the command before it writes anything, and an unknown feature in `config/keyring.php` stops the app booting, rather than leaving that feature off. `--require-second-factor` and `--optional-second-factor` answer the second question; requiring one without a sign-in method that counts stops the command too. `--emails` and `--no-emails` say whether the provider registers the security notices about changes; the classes are published either way.
`--factor` takes `totp`, `passkeys`, `security-keys` or `email-codes`. `--feature` takes `registration`, `reset-passwords`, `email-verification`, `update-passwords`, `manage-authenticators`, `devices`, `email-changes` or `security-log`, and replaces the defaults (`registration`, `reset-passwords`, `email-verification`, `update-passwords` and `security-log`), so list those too if you want them. An unknown value stops the command before it writes anything, and an unknown feature in `config/keyring.php` stops the app booting, rather than leaving that feature off. `--require-second-factor` and `--optional-second-factor` answer the second question; requiring one without a sign-in method that counts stops the command too.

Pass `--force` to overwrite files that already exist; without it, existing files are skipped, and with `config/keyring.php` already there it doesn't ask which features to turn on. It's safe to run again: a migration you already have is never added a second time under a new timestamp, and one a later version brought is added on its own. Running it again on an older install adds any new actions and notifications too, but leaves your provider alone, so register them there yourself. A new action's routes fail until you do, with an exception that says which `Keyring::*Using()` call is missing. A new notification is simply never sent: add its line to `Keyring::notifications()`, using the [list of emails](security-log-and-emails.md#security-emails) for the key.
Pass `--force` to overwrite files that already exist; without it, existing files are skipped, and with `config/keyring.php` already there it doesn't ask which features to turn on. It's safe to run again: a migration you already have is never added a second time under a new timestamp, and one a later version brought is added on its own. Running it again on an older install adds any new actions too, but leaves your provider alone, so register them there yourself. A new action's routes fail until you do, with an exception that says which `Keyring::*Using()` call is missing. A new email needs nothing: Keyring's emails are its own, so one a later version brings is sent from the start.

If you're moving from Fortify, read [Upgrading From Fortify](upgrading-from-fortify.md) before migrating.

Expand All @@ -62,9 +61,10 @@ If you're moving from Fortify, read [Upgrading From Fortify](upgrading-from-fort
|---|---|
| `config/keyring.php` | A short config: the guard, username, home, your features, how registration answers, your enrollment page and your support contact. Every other option keeps Keyring's default; copy any from [Configuration](configuration.md) to change it. |
| `database/migrations/*_create_keyring_*_table.php` | Seven tables: `keyring_authenticators`, `keyring_devices`, `keyring_sessions`, `keyring_pending_changes`, `keyring_events`, `keyring_failure_counts` and `keyring_password_holds`. They're all created, so turning a feature on later needs no new migration. Tables for features you don't use stay empty. |
| `app/Providers/KeyringServiceProvider.php` | Where you register sign-in methods, the policy, the risk signals, your actions and your emails. It lists the sign-in methods you picked, adds the `keyring.enrolled` middleware when a second factor is required, turns on the [risk signals](risk.md) your features can feed and lists the rest commented out, and it's added to `bootstrap/providers.php` for you. |
| `app/Providers/KeyringServiceProvider.php` | Where you register sign-in methods, the policy, the risk signals and your actions. It lists the sign-in methods you picked, adds the `keyring.enrolled` middleware when a second factor is required, turns on the [risk signals](risk.md) your features can feed and lists the rest commented out, and it's added to `bootstrap/providers.php` for you. |
| `app/Actions/Keyring/*.php` | Your code for the features that need it, all published and registered so a feature works as soon as you turn it on: registration (`CreateNewUser`), password resets (`ResetUserPassword`), password changes (`UpdateUserPassword`), email change requests (`ValidateEmailChange`), and the password rules they share (`PasswordValidationRules`). Keyring does the security work around them. |
| `app/Notifications/Keyring/*.php` | Every email Keyring sends, as ordinary Laravel notifications that are yours to reword, restyle or send another way. The ones a flow needs are registered, and so are the security notices unless you said no to them; one with nothing to announce until a feature is on is listed commented out. See [Security Emails](security-log-and-emails.md#security-emails). |

Keyring's emails aren't published: they're [its own](security-log-and-emails.md#security-emails), sent from the start, and you change one by giving `Keyring::notifications()` your class for it.

You can publish files on their own with the `keyring-config`, `keyring-migrations` and `keyring-lang` tags. `keyring-config` publishes the full config file, with every option and its default:

Expand Down
Loading
Loading