Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
2116ce5
feat(sessions): end every session of an account the app keeps out at …
entity Nov 11, 2026
df12b9c
fix(assurance): take aal2 to need a factor the user has, as nist sp 8…
entity Nov 11, 2026
dd484ae
feat(risk): require a new password by default when the one just used …
entity Nov 11, 2026
caed3f9
feat(install): start a new app with the risk signals its features can…
entity Nov 11, 2026
d322835
feat(notices): register the new device, failed second factor, suspici…
entity Nov 11, 2026
1c8380f
feat(notices): say who to contact in every notice once the app sets a…
entity Nov 11, 2026
85424c3
fix(passwords): follow no redirect when keyring asks have i been pwne…
entity Nov 11, 2026
67061d2
feat(log): record a refusal by the form rate limiter in the security log
entity Nov 11, 2026
814328a
fix(js): encode the factor or id a route helper puts in a path
entity Nov 11, 2026
3eed47a
feat(authenticators): present when a sign-in method was added and las…
entity Nov 11, 2026
c395e5e
feat(conformance): fail an app whose password broker has no throttle
entity Nov 11, 2026
0f006b5
Merge remote-tracking branch 'origin/main' into feat/standards-close-out
entity Nov 11, 2026
d6b1a83
feat(log): give an entry written to the app's log its time with an of…
entity Nov 11, 2026
92fed91
docs(source): cite the revision and section of each standard in comme…
entity Nov 11, 2026
1d7cc5d
docs(asvs): rewrite the asvs page from the code, with nist sp 800-63b…
entity Nov 11, 2026
1e32b8e
docs(security): correct the standards citations and state each deviat…
entity Nov 11, 2026
935dd3e
docs: bring the readme, changelog and remaining pages in line with wh…
entity Nov 11, 2026
004ceee
docs(security): read the page as one document, and show where a bot c…
entity Nov 11, 2026
05d58b6
docs(recipes): pass the support contact to a template of your own
entity Nov 11, 2026
f381dba
test: satisfy rector and phpstan in the new tests
entity Nov 11, 2026
9f5be6b
test(log): set the clock in the app's timezone so the offset test hol…
entity Nov 11, 2026
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
70 changes: 55 additions & 15 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,62 @@

The first release. Nothing is tagged yet.

### Signing In

- Sign in, sign out, registration, password resets and email verification, with your own actions and pages.
- Registration that doesn't reveal who has an account: the same answer for a free and a taken address, with new users signing in once they've verified theirs.
- Factors behind one contract: password, authenticator apps, passkeys, security keys, email codes and recovery codes, plus your own.
- Registration that doesn't reveal who has an account: the same answer for a free and a taken address, with new users signing in once they've verified theirs. `registration.reveal_taken` says when an address is taken instead.
- Factors behind one contract: password, authenticator apps, passkeys, security keys, email codes and recovery codes, plus your own. Many authenticators per user, with a default and "try another way".
- Passkeys and security keys from one WebAuthn driver: ES256 and EdDSA by default, RS256 when you ask for it, a challenge that is answered once and runs out on the server, and sign in with Laravel's `@laravel/passkeys` client.
- `WebAuthn::securityKeys()->requireAttestation()` to only add hardware keys whose attestation chains to root certificates you list, and `allowOnly()` to limit them to certain models by AAGUID.
- Many authenticators per user, with a default and "try another way".
- Policies built from assurance levels, with `ifEnrolled()` and `noDowngrade()`.
- Step-up middleware: `keyring:aal2` and `keyring.fresh:15m`.
- Devices and sessions: trusted devices, new-device emails with a "this wasn't me" link, a list of the user's sessions to end one by one, and signing out everywhere else, on any session driver. A limit on sessions per account, and idle and absolute timeouts.
- "Remember me" tied to the session it was ticked for: it carries that session on and can't outlast its timeouts, a revocation or a risk response. Its cookie works once and is replaced each time. A used one sent again ends the session for everyone holding it, with a `RememberMeReused` event and a `remember_me_reused` log entry.
- Protected `email` and `password` attributes, with email changes confirmed from both addresses and revertable from the old one.
- Risk signals with an action for each level.
- A security log, "was this you?" alerts and security emails, each a notification published into your app.
- `keyring:install`, `keyring:import fortify`, `keyring:prune`, and `keyring:sign-out` to end one user's sessions or everyone's.
- Authenticator app codes that work once, with SHA-1, SHA-256 or SHA-512, and a window of one time step or none.
- Email codes as an extra step at sign in. They are opt-in and never count as a second factor.
- Recovery codes of 128 random bits, stored as keyed hashes, with a flag that says when a used set should be replaced.
- `Keyring::attempt()` to start a sign in from your own route, for social logins and the like.
- `Keyring::allowSignInWhen()` to keep banned or unapproved accounts out, however they try to sign in.
- `Keyring::allowSignInWhen()` to keep banned or unapproved accounts out, however they try to sign in. The first request it refuses ends every session the account has.
- A verification pipeline you can add steps to, with the steps that enforce Keyring's guarantees protected from being removed by accident.

### Policies and Step-Up

- Policies built from assurance levels that follow NIST SP 800-63B-4: AAL2 needs a factor the user has, and AAL3 an attested key that can't leave its device. `ifEnrolled()` and `noDowngrade()` say how a policy treats users who can't meet it yet, or who have a passkey.
- `keyring.enrolled` to make everyone set up a second factor, which the installer adds when you pick one.
- Step-up middleware: `keyring:aal2` and `keyring.fresh:15m`, with a shared confirm flow. Changing how an account signs in takes the strongest proof the account can give.

### Sessions and Devices

- A registry of signed-in sessions that works on any session driver: a list of the user's sessions to end one by one, signing out everywhere else, a limit on sessions per account, and idle and absolute timeouts kept on the server.
- Assurance levels that lapse on NIST's clock, with `sessions.end_on_lapse` to end the session with its level.
- "Remember me" tied to the session it was ticked for: it carries that session on and can't outlast its timeouts, a revocation or a risk response. Its cookie works once and is replaced each time. A used one sent again ends the session for everyone holding it, with a `RememberMeReused` event and a `remember_me_reused` log entry.
- Devices: trusted devices, new-device emails with a "this wasn't me" link, and a limit on devices per account.
- `Secure`, `__Host-` prefixed cookies named for what they do (`known_device`, `remembered_session`).
- `keyring:sign-out` to end one user's sessions or everyone's.

### Account Changes

- Protected `email` and `password` attributes, which only change through Keyring's flows once it handles them.
- Email changes confirmed from both addresses and revertable from the old one, with the old address reserved while they can be undone.
- Password changes that take the current password, and resets that sign nobody in, end every session and leave second factors alone.
- Password rules that follow OWASP ASVS 5.0.0 and NIST SP 800-63B-4: 15 characters alone or 8 with a second factor, no composition rules, a bundled list of the most common passwords, your own context words, a breach check that can refuse what it couldn't check, and Unicode normalised to NFC.
- `Keyring::requirePasswordChange()`, and a risk action of the same name, to hold a user until they choose a new password when theirs is known to someone else.
- Rate limits per account, per typed username and per IP address, with locks that double, a cap on failures in a row, and `limits.lock_after` to keep an account locked until its password is reset.
- Test helpers, a fake, factories, a virtual WebAuthn authenticator and a conformance suite.
- `@entity/keyring`, a browser package for WebAuthn, enrollment and the challenge page, with Vue and React bindings. Passkey sign in works with Laravel's `@laravel/passkeys` client too.
- Emailed links that only act on a button press, with the token or signature posted in the body, built from `APP_URL` and opened on pages that send no referrer.

### Rate Limits and Risk

- Rate limits per account, per typed username and per IP address, with locks that double, a count of their own for browsers the account has signed in from, a cap on failures in a row kept in the database, and `limits.lock_after` to keep an account locked until its password is reset.
- A timebox around every verification, so a refusal takes the same time whatever the reason.
- Risk signals with an action for each level: a new device, a new country, impossible travel, a session turning up in another browser, repeated failed second factors, a sign in after several failures or after a long quiet period, a recently changed email address and a password found in a breach. A new app starts with the ones its features can feed, and a password found in a breach holds its user until they choose another.

### Logging and Emails

- 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.
- `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.
- 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.
- Documentation of where Keyring stands on every requirement of OWASP ASVS 5.0.0 and NIST SP 800-63B-4 that bears on it, and of each place it deliberately does something else.
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,12 @@ Fortify keeps 2FA in three columns on `users`. That gives one TOTP per user, and
- **Devices and sessions:** new-device events, "this wasn't me" links, a sessions list, and "sign out everywhere else". It works with **any session driver** (database, cache, file, cookie).
- **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. Each level maps to an action.
- **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.
- **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.

Everything beyond signing in 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 [Adding Features](docs/quick-start.md#adding-features).

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

Expand Down Expand Up @@ -88,7 +89,7 @@ npm install @entity/keyring
- [Recipes](docs/recipes.md)
- [Testing](docs/testing.md)
- [Security](docs/security.md)
- [OWASP ASVS](docs/owasp-asvs.md)
- [OWASP ASVS and NIST SP 800-63B](docs/owasp-asvs.md)

The [changelog](CHANGELOG.md) lists what each release changes, and the [upgrade guide](UPGRADE.md) covers anything you need to do when updating.

Expand Down
35 changes: 27 additions & 8 deletions config/keyring.php
Original file line number Diff line number Diff line change
Expand Up @@ -174,12 +174,27 @@
|
| Where a user who has to choose a new password is sent from every other
| page until they have: after Keyring::requirePasswordChange($user), or a
| risk response with requirePasswordChange(). Null answers 403.
| risk response with requirePasswordChange(), which is Keyring's own for
| the BreachedPassword signal. Null answers 403.
|
*/

'password_change_url' => null,

/*
|--------------------------------------------------------------------------
| Support Contact
|--------------------------------------------------------------------------
|
| 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
| it's set. Null leaves the line out.
|
*/

'support_contact' => null,

/*
|--------------------------------------------------------------------------
| Devices
Expand Down Expand Up @@ -227,8 +242,8 @@
| "levels" are how long each assurance level keeps counting: past them the
| user stays signed in, and routes that need the level ask them to verify
| again. With "end_on_lapse" a session ends instead when the level it
| signed in at runs out, as NIST SP 800-63B words it, and "remember me"
| brings nothing back. "remember_cookie" names the cookie that ties
| signed in at runs out, as NIST SP 800-63B-4 words it (Sec. 5.2), and
| "remember me" brings nothing back. "remember_cookie" names the cookie that ties
| "remember me" to the session it was ticked for: null is
| remembered_session, prefixed over HTTPS like the device cookie. Each one
| works once and is replaced. For "remember_grace" a browser's other
Expand Down Expand Up @@ -299,7 +314,8 @@
| than truncate it: the real limit is then 72 bytes, which is 72 plain
| characters but only 36 accented or Cyrillic ones, 24 Chinese, Japanese
| or Korean ones, or 18 emoji. Set HASH_DRIVER=argon2id to take every
| password up to "max", as OWASP ASVS 6.2.9 asks (at least 64 characters).
| password up to "max": OWASP ASVS 5.0.0 (6.2.9) asks for at least 64
| characters.
|
| "uncompromised" checks new passwords against Have I Been Pwned over the
| network. Null runs it in production only, so local and test runs make
Expand Down Expand Up @@ -330,9 +346,12 @@
|--------------------------------------------------------------------------
|
| Signal scores add up (0-100) into a level. Pick signals and what to do at
| each level with Keyring::risk()->signals([...])->respond(fn ...). By
| default: medium asks for another factor, high also notifies, critical
| refuses the sign in, or on a signed-in request signs out every session.
| each level with Keyring::risk()->signals([...])->respond(fn ...), in
| your KeyringServiceProvider: keyring:install starts it with the signals
| your features can feed. By default: medium asks for another factor, high
| also notifies, critical refuses the sign in, or on a signed-in request
| signs out every session. A password found in a breach also holds its
| user until they choose a new one.
|
*/

Expand Down Expand Up @@ -432,7 +451,7 @@
|
| Default attempts per minute, per account and per IP address, and the
| failures in a row one of an account's authenticators allows however
| slowly they come (100 is the most NIST SP 800-63B allows, null is no
| slowly they come (100 is the most NIST SP 800-63B-4 allows, null is no
| cap). They're counted in the database, and at the cap the authenticator
| is refused until a password reset or Keyring::unlock() clears it, or a
| second factor is removed and added again. "consecutive_elsewhere" is
Expand Down
4 changes: 2 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ Keyring is an authentication backend for Laravel. It handles sign in, registrati
- [Risk](risk.md): risk signals and what to do about them.
- [Security Log & Emails](security-log-and-emails.md): the activity log, "was this you?" alerts and security emails.
- [Events](events.md): every event Keyring dispatches and what it carries.
- [Security](security.md): what Keyring guarantees, and its known limitations.
- [OWASP ASVS](owasp-asvs.md): what to turn on for each level of ASVS 5.0's authentication and session management chapters.
- [Security](security.md): what Keyring guarantees, where each choice comes from, and its known limitations.
- [OWASP ASVS and NIST SP 800-63B](owasp-asvs.md): where Keyring stands on every requirement of ASVS 5.0.0 that bears on it, what to turn on for each level, and what its assurance levels mean in NIST's terms.

## Building Your App

Expand Down
8 changes: 5 additions & 3 deletions docs/authenticators.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,16 +101,18 @@ Authenticator apps and email codes take an optional `name` when beginning or con

A wrong proof fails with `keyring::keyring.invalid`, and an expired or missing enrollment, or one that was already confirmed, with `keyring::keyring.enrollment_expired`, both on the factor's field (`code`, or `credential` for passkeys and security keys). Email enrollment codes keep their guess count between tries, like email codes at sign in.

On success, the response contains the new authenticator, presented the same way as on the challenge page:
On success, the response contains the new authenticator, as its factor's `present()` gives it:

```json
{
"status": "authenticator-added",
"authenticator": { "factor": "totp", "id": "01JC4...", "name": "Authenticator app" },
"authenticator": { "factor": "totp", "id": "01JC4...", "name": "Authenticator app", "createdAt": "2026-11-08T14:05:00+00:00", "lastUsedAt": null },
"recoveryCodes": ["jbsw-y3dp-ehpk-3pxp-jbsw-y3dp-eh", "..."]
}
```

`createdAt` and `lastUsedAt` are when it was added and last used to sign in or confirm, as ISO 8601 dates, for the list on your settings page: OWASP's Passkey Security Cheat Sheet has a page that manages credentials show both. The [challenge page](sign-in-flow.md#page-props) gets the same shape without them.

`recoveryCodes` is only there when Keyring generated recovery codes along with this authenticator (see below).

The user's first saved authenticator becomes their default (never recovery codes). A passkey or security key that's already registered, to anyone, can't be registered again. Confirming a factor that allows only one per user (`email-code`, `recovery`) replaces the one they had.
Expand Down Expand Up @@ -163,7 +165,7 @@ It also forgets the failures counted against it. An authenticator that failed to

The password can't be removed this way. It isn't stored in `keyring_authenticators`.

Removing the user's last second factor (the last one beyond recovery codes and email codes) also needs their current password in the request as `password`. Their password may have been as short as `min_with_mfa` while it had a second factor beside it, and on its own NIST SP 800-63B asks for `min_without_mfa`. Keyring only stores a hash, so it checks the length then: a missing or wrong password, or one that's too short, gets an error on `password` asking them to change it first.
Removing the user's last second factor (the last one beyond recovery codes and email codes) also needs their current password in the request as `password`. Their password may have been as short as `min_with_mfa` while it had a second factor beside it, and on its own NIST SP 800-63B-4 asks for `min_without_mfa` (15 characters, Sec. 3.1.1.2). Keyring only stores a hash, so it checks the length then: a missing or wrong password, or one that's too short, gets an error on `password` asking them to change it first.

## Signing Out Other Sessions

Expand Down
Loading
Loading