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
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ The first release. Nothing is tagged yet.

### Tooling

- `keyring:install`, which asks which sign-in methods and features you want and publishes a config, a provider and your actions. Its defaults give an authenticator app that every user must set up, and `--factor=none` the password alone. Also `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. Its defaults give the password alone, and every other sign-in method is in the provider, commented out, to turn on later. Also `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`, `Cross-Origin-Opener-Policy: same-origin-allow-popups` 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
20 changes: 19 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Fortify keeps 2FA in three columns on `users`. That gives one TOTP per user, and
- **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, partly met, waiting on something you turn on, a deliberate deviation or your app's job, and the page says which and why.
- **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.

Every feature and sign-in method beyond the password is opt-in. See [Adding Features](docs/quick-start.md#adding-features).
Every feature and sign-in method beyond the password is opt-in. See [Start Small, Add What You Need](#start-small-add-what-you-need).

> Work in progress: not tagged or production-tested yet.

Expand Down Expand Up @@ -66,6 +66,24 @@ npm install @entity/keyring

> It isn't on npm yet either. Until it is, build it from the Composer package: see [Frontend](docs/frontend.md#introduction).

## Start Small, Add What You Need

A new install is password sign-in, registration, password resets, email verification and password changes. You build five pages: `login`, `register`, `forgot-password`, `reset-password`, and `confirm`, which asks for the password again before it's changed.

What costs you nothing is on from the start: rate limits, password rules, session timeouts, the security log, security emails and the risk signals that need no setup.

Everything else is already in your app, commented out. Adding it is uncommenting a line:

| To add | Uncomment |
|---|---|
| An authenticator app, passkeys, security keys or email codes | Its line in `Keyring::factors([...])` in your provider, and `Features::manageAuthenticators()` in the config |
| A second factor for everyone | The `keyring.enrolled` line in your provider |
| "Trust this device", a list of where users are signed in, new-device emails | `Features::devices()` |
| Email changes confirmed from the new address and undoable from the old one | `Features::emailChanges()` |
| More risk signals: a new device, a breached password, a new country, impossible travel | Their lines in `Keyring::risk()->signals([...])` |

See [Adding Features](docs/quick-start.md#adding-features) and [Adding Sign-In Methods](docs/quick-start.md#adding-sign-in-methods) for the pages each one needs.

## Documentation

- [Quick Start](docs/quick-start.md)
Expand Down
8 changes: 4 additions & 4 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,17 +37,17 @@ php artisan migrate

The command asks three things:

1. **Which sign-in methods besides the password?** An authenticator app by default, so a new app starts with a second factor. Untick it for the password alone. 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.
1. **Which sign-in methods besides the password?** None by default: a new app starts with the password, and the others stay in your provider, commented out, to add later. 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).

Without prompts (`--no-interaction`, or in CI) you get the same defaults: an authenticator app that everyone must set up. You can also answer with options:
Without prompts (`--no-interaction`, or in CI) you get the same defaults: the password alone. 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`, or `none` for the password alone. `--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.
`--factor` takes `totp`, `passkeys`, `security-keys` or `email-codes`, or `none` to keep the password alone without being asked. `--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 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.

Expand All @@ -61,7 +61,7 @@ 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 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/Providers/KeyringServiceProvider.php` | Where you register sign-in methods, the policy, the risk signals and your actions. It has every sign-in method, with the ones you didn't pick commented out, and the same for the `keyring.enrolled` middleware that requires a second factor and for the [risk signals](risk.md) your features can't feed yet. Adding one later is uncommenting its line. 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. |

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.
Expand Down
Loading
Loading