@nxgt/janus 0.24.0 → 0.25.0

package/dist/permissions/index.js

@@ -4,16 +4,16 @@ import {
   UNSTORABLE,
   MAX_PAGE_SIZE2,
   pageLimit2
-} from "../chunks/index-4khsm7mw.js";
+} from "../chunks/index-y9b327j8.js";
 import {
   PermissionDepthError2,
   isSubjectSet2,
   isSetOf2,
   formatEntity2
-} from "../chunks/index-kppkcbn5.js";
+} from "../chunks/index-spwh8b9z.js";
 import {
   createMemoryRelations2
-} from "../chunks/index-cntabs9d.js";
+} from "../chunks/index-rpp0bw6e.js";
 
 // src/permissions/resolve/resolved.ts
 function admits(holders, subject) {

package/docs/guide/adapters.md

@@ -31,7 +31,7 @@ describeJanusStores({
 
 | Port | Taken by | Methods |
 | --- | --- | --- |
-| `JanusStores` — `{ users: UserStore, sessions: SessionStore, tokens: TokenStore }` | `janus({ store })` | 6 (+ 1 optional) + 7 (+ 1 optional) + 5 |
+| `JanusStores` — `{ users: UserStore, sessions: SessionStore, tokens: TokenStore }` | `janus({ store })` | 6 (+ 1 optional) + 7 (+ 1 optional) + 5 (+ 1 optional) |
 | `RelationStore` | `permissions({ store })`, `janus({ relations })` | 6 |
 
 They are separate on purpose: an application that only authenticates
@@ -184,6 +184,7 @@ interface TokenStore {
 	countAttempt(tokenHash: string, kind: TokenKind): Promise<TokenRecord | null>;
 	spendUserTokens(userId: Id, kind: TokenKind, at: Date, except?: string): Promise<number>; // the unspent ones, but except
 	deleteUserTokens(userId: Id): Promise<number>;
+	deleteExpiredTokens?(before: Date): Promise<number>; // optional: omit it if the database expires on its own
 }
 ```
 
@@ -368,6 +369,41 @@ of the right `kind` whose `spentAt` is empty, skipping the one named by
 `except`. `spendUserTokens` has its own
 outage case.
 
+### `TokenStore.deleteExpiredTokens` (optional)
+
+What `collectExpired()` asks for, beside `SessionStore.deleteExpiredSessions`:
+**delete every token whose `expiresAt` is at or before `before`**, and answer
+how many. Leave it out when your database expires records on its own (a TTL
+index, a key TTL) — nothing breaks, the core compares `expiresAt` on every
+redemption — and implement it when it does not, or the rows pile up.
+
+| The stored token | Written |
+| --- | --- |
+| `expiresAt` at or before `before`, spent or not, of any kind and any user | deleted, and counted |
+| `expiresAt` later than `before`, spent or not | **kept** |
+| none at all | `0`, an absence — never a failure |
+
+**Never delete a token whose `expiresAt` is later, spent or not**: a spent
+token is kept, answered as spent, until it lapses, or a count would start
+over. That includes the throttles' counts — ordinary `secondFactor` tokens
+under a keyed-hash user id, which `deleteUserTokens` never reaches and this
+method is the only thing to collect. The core calls it with `clock.now()`, no
+margin: a link collected answers `TOKEN_UNKNOWN`.
+
+```ts
+import type { TokenStore } from '@nxgt/janus';
+
+// PostgreSQL through Drizzle — one statement, over an index on expires_at
+deleteExpiredTokens: async (before) =>
+	(await db.delete(tokens).where(lte(tokens.expiresAt, before)).returning({ tokenHash: tokens.tokenHash })).length,
+```
+
+`janus()` reads its presence once (`StoreCapabilities.collectExpiredTokens`),
+and refuses a `deleteExpiredTokens` that is there but not a function with a
+`TypeError`. The suite's `tokens.deleteExpired` and `outage.deleteExpiredTokens`
+cases check it, and are skipped with their reason for a store that leaves it
+out. A failure throws, as everywhere on the port.
+
 ### `RelationStore`
 
 ```ts
@@ -449,7 +485,7 @@ compile error naming the missing method.
 
 | Suite | Cases | Harness opens |
 | --- | --- | --- |
-| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 59: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — fifteen of them | `{ stores, faults?, close? }` |
+| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 61: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — sixteen of them | `{ stores, faults?, close? }` |
 | `describeRelationStores({ name, harness, runner?, faults?, skip? })` | 16: the relation store, ids of edge characters, and one outage per method | `{ store, faults?, close? }` |
 
 `harness.open()` is called **once per case** and must answer fresh, empty
@@ -546,7 +582,8 @@ describeJanusStores({
 
 A skipped case still appears in the run, with its reason in its name. A case
 that cannot run on the stores it was given — an outage case with no `faults`,
-`collectExpired` on a store without `deleteExpiredSessions`, a `findUsers`
+`sessions.deleteExpired` on a store without `deleteExpiredSessions`,
+`tokens.deleteExpired` on one without `deleteExpiredTokens`, a `findUsers`
 case on a store without `findUsers` — passes, and emits a
 `JANUS_CONFORMANCE_SKIPPED` warning with the reason. A case's `needs` says what
 it cannot run without — one `CaseNeed` or a list: `outage.findUsers` needs

package/docs/guide/email-flows.md

@@ -511,8 +511,8 @@ answers again. A refused request is counted too but cannot extend the wait.
 **Where the counts live.** In the tokens store, as `secondFactor` tokens named
 by a keyed hash of the flow and the address or user id: no port change, no new
 infrastructure, and never the address. That is one row per flow per address or
-user per window. On PostgreSQL, `collectExpired()` does not collect lapsed
-ones: schedule the delete, as for the sign-in throttle. A flushed or evicting
+user per window. `collectExpired()` collects the lapsed ones on a tokens store that implements
+`deleteExpiredTokens`; a store with a TTL expires them on its own. A flushed or evicting
 Redis forgets the counts, and a tokens store that cannot count throws
 `STORE_FAILED` with nothing issued: it fails closed.
 

package/docs/guide/errors.md

@@ -64,7 +64,7 @@ that wired the library, so no handler needs to tell it apart.
 | `SECOND_FACTOR_NOT_ENROLLED` | `SecondFactorError` | 409 | `activate` before `enroll`; `regenerateRecoveryCodes` without an active factor; `confirm` or `recover` after the factor was disabled | `userId` |
 | `SECOND_FACTOR_ACTIVE` | `SecondFactorError` | 409 | `enroll` or `activate` on a factor already active: `disable` it first | `userId` |
 | `INVALID_CURSOR` | `InvalidCursorError` | 400 | A cursor this store did not mint. Never a silent first page | |
-| `UNSUPPORTED` | `UnsupportedError` | 501 | The wired store lacks an optional capability — `collectExpired` without `deleteExpiredSessions` | `slot`, `operation` |
+| `UNSUPPORTED` | `UnsupportedError` | 501 | The wired store lacks an optional capability — `collectExpired` with neither `deleteExpiredSessions` nor `deleteExpiredTokens` | `slot`, `operation` |
 | `PERMISSION_DEPTH` | `PermissionDepthError` | 500 | A check or list walked past `maxDepth`. **Not a denial** | `permission`, `maxDepth` |
 
 Every class extends `JanusError`, which extends `Error`, so no `catch` block

package/docs/guide/passwords.md

@@ -195,16 +195,13 @@ counts correctly. Each is named by a keyed hash of the login, never the login
 otherwise, which only keeps the login out of plain sight: a dump of the
 tokens then tells which logins were tried, for a guessed list. Each expires
 two windows after its window starts — half an hour by default — **Redis and MongoDB drop it then;
-PostgreSQL keeps it** until something deletes it, and every login tried,
-registered or not, adds a row per window. Schedule a delete with
-`@nxgt/janus-drizzle`:
-
-```sql
-delete from tokens where expires_at < now() - interval '1 hour'; -- janus.tokens when your tables have a schema of their own
-```
-
-`tokens` has no index on `expires_at`, so the delete scans the table: add
-`create index on tokens (expires_at)` in a migration of yours if it grows.
+a store with no TTL keeps it** until `collectExpired()` deletes it (the
+tokens store's optional `deleteExpiredTokens`), and every login tried,
+registered or not, adds a row per window. Schedule `collectExpired()` on such
+a store: `@nxgt/janus-drizzle` implements `deleteExpiredTokens` (since 0.9),
+with an index on `expires_at` that its
+[migration](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-drizzle/docs/guide/migrations.md#to-09-an-index-on-tokensexpires_at)
+adds. A store of your own implements the method, or its rows stay.
 
 The key is your first `secondFactor` key: wiring
 `secondFactor` for the first time, or putting a new key first, starts every

package/docs/guide/sessions.md

@@ -329,10 +329,21 @@ a link or a code already in the person's inbox still works afterwards.
 const removed: number = await auth.collectExpired();
 ```
 
-Deletes lapsed sessions, for a store that keeps them. It rejects with
-`UNSUPPORTED` when the sessions store does not implement the optional
-`deleteExpiredSessions` — a store with its own TTL, such as
-`@nxgt/janus-mongo`'s, does not. The reference store implements it.
+Deletes lapsed sessions and lapsed one-time tokens, from the stores that keep
+them, and answers how many in all. The tokens include the sign-in and mail
+throttles' counts, which are ordinary tokens. It runs whichever of the
+optional `sessions.deleteExpiredSessions` and `tokens.deleteExpiredTokens` the
+stores implement, sessions first, and rejects with `UNSUPPORTED` only when
+neither does — a store with its own TTL, such as `@nxgt/janus-mongo`'s, does
+not implement them. The reference store implements both.
+
+A token is deleted once its `expiresAt` is at or before now, spent or not;
+one that has not lapsed is never deleted, so a throttle keeps counting and a
+link still redeems until its time is up. After a token is collected, its link
+answers `TOKEN_UNKNOWN` rather than `TOKEN_EXPIRED` or `TOKEN_SPENT`, as it
+already does on a store with a TTL. A failure in the tokens store, after the
+sessions went, is `STORE_FAILED`; both deletions are idempotent, so call it
+again.
 
 ## Testing expiry
 

package/docs/roadmap.md

@@ -5,7 +5,7 @@ dates here, and the version something shipped in is the only number.
 
 ## Now
 
-Nothing between releases.
+Nothing yet.
 
 ## Next
 
@@ -13,13 +13,6 @@ Nothing yet.
 
 ## Later
 
-- **Collecting lapsed one-time tokens** — `collectExpired()` deletes lapsed
-  sessions only. On a store with no TTL (PostgreSQL), lapsed tokens stay
-  until you delete them, and the sign-in throttle adds one per login tried
-  per window, and the mail throttle one per flow per address or user per
-  window. A port method to collect them, as sessions are, would let the
-  core do it.
-
 - **A batch read across types** — `findMany` reads one user type, as `find`
   does. The shared `findUser(id)` has no batch counterpart yet; one on the
   instance, answering a union narrowed by `user.type`, would serve a list that
@@ -76,6 +69,13 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Collecting lapsed one-time tokens, v0.25.0** — `collectExpired()` deletes
+  lapsed sessions and, through a new optional `TokenStore.deleteExpiredTokens`,
+  lapsed one-time tokens too: the sign-in and mail throttles' counts
+  included, which a store with no TTL (PostgreSQL) kept for ever, one per
+  login tried per window and one per flow per address or user per window.
+  The reference store and `@nxgt/janus-drizzle` 0.9 implement it; MongoDB and
+  Redis expire tokens themselves and do not.
 - **Finding a user, or creating them, v0.24.0** —
   `auth.<type>.findOrCreate(key, input)` answers `{ user, created }`: the
   holder of the key — the login on a type with a password, the e-mail on one

package/docs/troubleshooting.md

@@ -75,7 +75,7 @@ How the messages are shaped:
 - [`TOKEN_STALE` — `<call>: the token was sent to an e-mail the user no longer has`](#token_stale--call-the-token-was-sent-to-an-e-mail-the-user-no-longer-has)
 - [`INVALID_CURSOR` — `<call>: this cursor was not minted by this store …`](#invalid_cursor--call-this-cursor-was-not-minted-by-this-store-or-was-minted-for-another-ordering-n-characters)
 - [`<call>: limit must be an integer of at least 1, or absent`](#call-limit-must-be-an-integer-of-at-least-1-or-absent)
-- [`UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions …`](#unsupported--collectexpired-storesessions-does-not-implement-deleteexpiredsessions--its-store-expires-sessions-on-its-own-or-implement-the-method)
+- [`UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions, nor store.tokens deleteExpiredTokens …`](#unsupported--collectexpired-storesessions-does-not-implement-deleteexpiredsessions-nor-storetokens-deleteexpiredtokens--their-stores-expire-records-on-their-own-or-implement-the-methods)
 - [`<call>: the <type> type does not sign in with a password …`](#call-the-type-type-does-not-sign-in-with-a-password--add-password--login--to-it)
 - [`authenticate()` answers `null` although a valid cookie was sent](#authenticate-answers-null-although-a-valid-cookie-was-sent)
 
@@ -297,10 +297,10 @@ janus({ ..., hasher: scryptHasher(), verifiers: [legacyBcrypt] }); // not [scryp
 
 ### `janus: store.<slot> has no method <method>, which the port requires`
 
-Also: `janus: store.<slot> is missing`, `janus: store must be an object with users, sessions and tokens`, `janus: store.sessions.deleteExpiredSessions must be a function or absent`, `janus: store.users.findUsers must be a function or absent`.
+Also: `janus: store.<slot> is missing`, `janus: store must be an object with users, sessions and tokens`, `janus: store.sessions.deleteExpiredSessions must be a function or absent`, `janus: store.tokens.deleteExpiredTokens must be a function or absent`, `janus: store.users.findUsers must be a function or absent`.
 
 **When:** `janus({...})`, from JavaScript or with a store typed loosely. TypeScript refuses a partial store at compile time and names the method.
-**Why:** `store` is `{ users, sessions, tokens }`, and each slot must answer every method of the port. Two methods are optional — `sessions.deleteExpiredSessions` and `users.findUsers` — and each is absent, or a function: a value in its place (`findUsers: true`, a property copied from a config) is a wiring mistake, not an absent capability.
+**Why:** `store` is `{ users, sessions, tokens }`, and each slot must answer every method of the port. Three methods are optional — `sessions.deleteExpiredSessions`, `tokens.deleteExpiredTokens` and `users.findUsers` — and each is absent, or a function: a value in its place (`findUsers: true`, a property copied from a config) is a wiring mistake, not an absent capability.
 An adapter written for an earlier `@nxgt/janus` reports the method a later
 release added to the port: `store.tokens has no method countAttempt` for one
 written against 0.3 (the method came in 0.4), and
@@ -1069,11 +1069,11 @@ const page = await access.list(user, 'view', 'record', {
 });
 ```
 
-### `UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions — its store expires sessions on its own, or implement the method`
+### `UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions, nor store.tokens deleteExpiredTokens — their stores expire records on their own, or implement the methods`
 
 **When:** `auth.collectExpired()`.
-**Why:** the sessions store does not implement the optional `deleteExpiredSessions` — usually because it expires sessions itself (a MongoDB TTL index, a Redis `EXPIRE`).
-**Fix:** do not schedule `collectExpired` for that store. Expiry does not depend on it: the core compares `expiresAt` on every `authenticate`.
+**Why:** neither the sessions store implements the optional `deleteExpiredSessions` nor the tokens store the optional `deleteExpiredTokens` — usually because they expire records themselves (a MongoDB TTL index, a Redis `EXPIRE`). With one of the two, `collectExpired` collects that one and does not throw.
+**Fix:** do not schedule `collectExpired` for those stores. Expiry does not depend on it: the core compares `expiresAt` on every `authenticate` and on every redemption. If your database has no TTL, implement the methods ([adapters](guide/adapters.md#tokenstoredeleteexpiredtokens-optional)).
 
 ### `<call>: the <type> type does not sign in with a password — add password: { login } to it`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus",
-	"version": "0.24.0",
+	"version": "0.25.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",