@nxgt/janus 0.2.2 → 0.4.0

package/dist/permissions/reverse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reverse.d.ts","sourceRoot":"","sources":["../../src/permissions/reverse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAEN,KAAK,aAAa,EAGlB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,OAAO;IAOlB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAX1B,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,OAAO,CAA0C;IACzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,MAAM,CAAS;gBAGL,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM;IAG5B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAcvE,gFAAgF;IAChF,OAAO,CAAC,IAAI;IAOZ,8EAA8E;YAChE,KAAK;YA2BL,QAAQ;YAgCR,UAAU;IAmBxB,oGAAoG;YACtF,KAAK;IAgCnB,+CAA+C;YACjC,OAAO;IAqBrB,yEAAyE;YAC3D,MAAM;IAoBpB,gEAAgE;IAChE,OAAO,CAAC,MAAM;CAYd"}
+{"version":3,"file":"reverse.d.ts","sourceRoot":"","sources":["../../src/permissions/reverse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAEN,KAAK,aAAa,EAGlB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,OAAO;IAOlB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAX1B,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,OAAO,CAA0C;IACzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,MAAM,CAAS;gBAGL,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM;IAG5B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAcvE,gFAAgF;IAChF,OAAO,CAAC,IAAI;IAOZ,8EAA8E;YAChE,KAAK;YA2BL,QAAQ;YAgCR,UAAU;IAmBxB,oGAAoG;YACtF,KAAK;IAiCnB,+CAA+C;YACjC,OAAO;IAqBrB,yEAAyE;YAC3D,MAAM;IAoBpB,gEAAgE;IAChE,OAAO,CAAC,MAAM;CAYd"}

package/dist/subjects/notation.d.ts

@@ -1,4 +1,4 @@
-import { type Entity, type RelationTuple, type Subject } from './subject';
+import { type Entity, type RelationTuple, type SetOf, type Subject } from './subject';
 /**
  * Zanzibar's notation, with typed subjects:
  *
@@ -30,6 +30,10 @@ export declare function formatTuple(tuple: RelationTuple): string;
  * developer's own code.
  */
 export declare function parseTuple(text: string): RelationTuple;
-/** Reads one subject back: `staff:u1`, or `team:t1#member`. */
-export declare function parseSubject(text: string): Subject;
+/**
+ * Reads one subject back: `staff:u1`, or `team:t1#member`. A set is answered
+ * as `setOf()` makes it, so `can()` and `grant()` read it as the set it names
+ * on a user type too.
+ */
+export declare function parseSubject(text: string): Entity | SetOf;
 //# sourceMappingURL=notation.d.ts.map

package/dist/subjects/notation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notation.d.ts","sourceRoot":"","sources":["../../src/subjects/notation.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,MAAM,EAEX,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAItD;AAED,iDAAiD;AACjD,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAExD;AASD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAkBtD;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAiBlD"}
+{"version":3,"file":"notation.d.ts","sourceRoot":"","sources":["../../src/subjects/notation.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,MAAM,EAEX,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,OAAO,EAEZ,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAItD;AAED,iDAAiD;AACjD,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAExD;AASD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAkBtD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,CAiBzD"}

package/dist/subjects/subject.d.ts

@@ -72,4 +72,57 @@ export declare function subjectOf(user: {
     readonly type: string;
     readonly id: SubjectId;
 }): Entity;
+/**
+ * The mark `setOf()` puts on a set: a symbol property, so it survives a spread
+ * and `Object.assign`, and no value read from a database or from JSON can
+ * carry it. Registered with `Symbol.for`, so two copies of this module — two
+ * bundles, two entry points — still agree on it.
+ */
+declare const SET_OF: unique symbol;
+/**
+ * A subject set `setOf()` made: everyone who holds `relation` on `type:id`.
+ *
+ * Marked, because a user is passed to `can()` and `grant()` as it is, fields
+ * flat on it: a user whose fields include `relation` must stay that user, and
+ * never read as the set of whoever holds that relation on them. For an object
+ * type, `{ type, id, relation }` is a set as written; for a user type — one
+ * the model also declares as an object type — only `setOf()` makes one.
+ *
+ * A spread keeps the mark. `JSON.stringify` and `structuredClone` drop it:
+ * through either, a set comes back as a user — call `setOf()` again, or
+ * `parseSubject()` on its notation.
+ */
+export type SetOf<Type extends string = string, Relation extends string = string> = SubjectSet & {
+    readonly type: Type;
+    readonly relation: Relation;
+    readonly [SET_OF]: true;
+};
+/**
+ * A user or an object, never a set `setOf()` made: where a relation admits
+ * `staff` but not `staff#managers`, a set passed there is refused at compile
+ * time as it is at run time.
+ */
+export type NotASet = {
+    readonly [SET_OF]?: never;
+};
+/**
+ * Everyone who holds `relation` on this user or object — `staff:s1#managers`.
+ *
+ * ```ts
+ * await access.grant(record, 'viewers', setOf(ada, 'managers'));
+ * ```
+ *
+ * Copies `type` and `id` only, like {@link subjectOf}: none of a user's own
+ * fields reaches a tuple.
+ */
+export declare function setOf<const Type extends string, const Relation extends string>(entity: {
+    readonly type: Type;
+    readonly id: SubjectId;
+}, relation: Relation): SetOf<Type, Relation>;
+/**
+ * Whether `setOf()` made this value, or a spread of one — what `can()` and
+ * `grant()` read to tell a set on a user type from a user.
+ */
+export declare function isSetOf(value: unknown): value is SetOf;
+export {};
 //# sourceMappingURL=subject.d.ts.map

package/dist/subjects/subject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../../src/subjects/subject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;;;;;;GAQG;AACH,MAAM,WAAW,MAAM;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAW,SAAQ,MAAM;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,UAAU,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;CACvB,GAAG,MAAM,CAET"}
+{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../../src/subjects/subject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;;;;;;GAQG;AACH,MAAM,WAAW,MAAM;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAW,SAAQ,MAAM;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,UAAU,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;CACvB,GAAG,MAAM,CAET;AAED;;;;;GAKG;AACH,QAAA,MAAM,MAAM,EAAE,OAAO,MAAwC,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,KAAK,CAChB,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,QAAQ,SAAS,MAAM,GAAG,MAAM,IAC7B,UAAU,GAAG;IAChB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;CACxB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG;IAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpD;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,KAAK,CAAC,QAAQ,SAAS,MAAM,EAC7E,MAAM,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAA;CAAE,EACvD,QAAQ,EAAE,QAAQ,GAChB,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAkBvB;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAMtD"}

package/docs/README.md

@@ -28,6 +28,6 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | --- | --- |
 | [The shared vocabulary](guide/vocabulary.md) | You want the words the documentation uses, or subjects and the tuple notation, ids, cursors, durations or `fixedClock` |
 | [Errors](guide/errors.md) | You are turning what the package throws into a status code, and want every code and what it carries |
-| [Writing an adapter](guide/adapters.md) | You are implementing the identity stores or the relation store for your database, and running the conformance suites |
+| [Writing an adapter](guide/adapters.md) | You are implementing the identity stores or the relation store for your database, upgrading one for `countAttempt` and the second factor, or running the conformance suites |
 | [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |
 | [Roadmap](roadmap.md) | You want to know what is coming, what shipped, and what is deliberately not planned |

package/docs/guide/adapters.md

@@ -31,7 +31,7 @@ describeJanusStores({
 
 | Port | Taken by | Methods |
 | --- | --- | --- |
-| `JanusStores` — `{ users: UserStore, sessions: SessionStore, tokens: TokenStore }` | `janus({ store })` | 6 + 6 (+ 1 optional) + 3 |
+| `JanusStores` — `{ users: UserStore, sessions: SessionStore, tokens: TokenStore }` | `janus({ store })` | 6 + 6 (+ 1 optional) + 4 |
 | `RelationStore` | `permissions({ store })`, `janus({ relations })` | 6 |
 
 They are separate on purpose: an application that only authenticates
@@ -77,6 +77,43 @@ interface UserStore {
 - `listUsers` pages in ascending id order; `after` is the last id of the
   previous page, already checked by the core.
 
+#### A user's password and second factor
+
+Both are one field of `UserRecord`, `null` when the user has none, and a
+patch treats both alike: **absent keeps it, `null` removes it, a value
+replaces it whole**.
+
+```ts
+interface UserRecord {
+	// …id, type, schemaVersion, active, fields, logins…
+	readonly password: { readonly hash: string; readonly updatedAt: Date } | null;
+	readonly secondFactor: {
+		readonly method: 'totp';
+		readonly secret: string; // opaque: store it byte for byte
+		readonly confirmedAt: Date | null; // null while enrolment waits for a first code
+		readonly lastStep: number | null; // the time step of the last code accepted
+	} | null;
+	// …emailVerifiedAt, version, createdAt, updatedAt
+}
+```
+
+`secret` is **opaque to a store**: once the second factor ships, the core
+will seal it with a key the application holds before a store sees it, so a
+dump of the users cannot produce a code. Keep it like a password hash — byte
+for byte, no parsing, no trimming. Store
+the second factor whole: a method without a secret, or a `lastStep` without a
+method, is a record the core never writes.
+
+```ts
+import type { UserPatch } from '@nxgt/janus';
+
+const keep: UserPatch = { updatedAt: new Date() }; // secondFactor untouched
+const remove: UserPatch = { updatedAt: new Date(), secondFactor: null };
+```
+
+An adapter that stored users before this field existed reads its absence as
+`null`, never `undefined` (rule 2): a user with no second factor holds `null`.
+
 ### `SessionStore` and `TokenStore`
 
 ```ts
@@ -93,6 +130,7 @@ interface SessionStore {
 interface TokenStore {
 	insertToken(record: TokenRecord): Promise<void>;
 	consumeToken(tokenHash: string, kind: TokenKind, at: Date): Promise<TokenRecord | null>;
+	countAttempt(tokenHash: string, kind: TokenKind): Promise<TokenRecord | null>;
 	deleteUserTokens(userId: Id): Promise<number>;
 }
 ```
@@ -103,12 +141,83 @@ Twenty concurrent calls must produce exactly one answer with `spentAt: null`;
 in MongoDB that is one `findOneAndUpdate` returning the document before the
 update. A read followed by a write lets two requests redeem one reset token.
 
+A token is its hash, never its secret, and what it is for:
+
+```ts
+type TokenKind = 'verifyEmail' | 'resetPassword' | 'secondFactor' | 'signInCode';
+
+interface TokenRecord {
+	readonly tokenHash: string;
+	readonly kind: TokenKind;
+	readonly userId: Id;
+	readonly address: string;
+	readonly codeHash: string | null; // a signInCode's code, hashed; null for every other kind
+	readonly attempts: number; // 0 at insertion
+	readonly expiresAt: Date;
+	readonly spentAt: Date | null;
+	readonly createdAt: Date;
+}
+```
+
+A token redeemed for another kind is unknown: every method that takes a
+`kind` matches on it. `codeHash` and `attempts` round-trip like every other
+field. An adapter whose stored tokens predate them reads them as `null` and
+`0`, as the three published adapters do, so no data migration is needed for
+them.
+
 Expiry is the core's decision: a read answers a stored session verbatim,
 lapsed or revoked, and never a record it has changed. A store with its own
 expiry — a TTL index, a Redis key TTL — may drop a lapsed session or token
 before anyone asks: reads then answer `null`, and `deleteUserSessions` does
 not count it. The conformance suite accepts both.
 
+### `TokenStore.countAttempt`
+
+Counts one attempt at a code against a token, and answers the token **as it
+is after the call** — what bounds the attempts at a six-digit code:
+
+| The stored token | Written | Answered |
+| --- | --- | --- |
+| unspent, of this `kind` | `attempts + 1` | the token, with the new count |
+| spent, of this `kind` | nothing | the token as it is |
+| another `kind`, or no token with this hash | nothing | `null` |
+
+Like `consumeToken`, it is **one conditional write**, never a read followed by
+a write: twenty concurrent calls answer the counts 1 to 20, each once. A count
+two attempts both read is an attempt for free. Whether the count is past the
+limit, and whether the code matches, is the core's decision after the call;
+spending the token stays `consumeToken`'s.
+
+A **lapsed** token is counted all the same, or answered `null` by a store that
+has already dropped it (a TTL index, a Redis key TTL). Do not compare
+`expiresAt` in the store: as for `consumeToken`, the core compares it after
+the call.
+
+In MongoDB, one `findOneAndUpdate` answering the document after it, then a
+plain read for the spent case:
+
+```ts
+import type { TokenStore } from '@nxgt/janus';
+
+// tokens: your collection; toToken: your document → TokenRecord
+export const countAttempt: TokenStore['countAttempt'] = async (tokenHash, kind) => {
+	const after = await tokens.findOneAndUpdate(
+		{ _id: tokenHash, kind, spentAt: null },
+		{ $inc: { attempts: 1 } },
+		{ returnDocument: 'after' },
+	);
+	if (after !== null) return toToken(after);
+	const spent = await tokens.findOne({ _id: tokenHash, kind }); // written nothing
+	return spent === null ? null : toToken(spent);
+};
+```
+
+In SQL, `update … set attempts = attempts + 1 where token_hash = $1 and kind =
+$2 and spent_at is null returning *`, then the same plain read. In Redis, one
+Lua script: `HINCRBY` only when `spentAt` is empty, then `HGETALL`. Wrap the
+driver's error in `StoreFailure` as in [the six rules](#the-six-rules):
+`countAttempt` has its own outage case.
+
 ### `RelationStore`
 
 ```ts
@@ -172,7 +281,7 @@ An adapter **defines no error class**. It throws `@nxgt/janus`'s own
 copy of each class and `instanceof` holds in the application. A cursor it
 cannot read is `invalidCursor(where, cursor)`. Records, patches and page
 requests are exported as types: `UserRecord`, `UserPatch`, `UserPageRequest`,
-`PasswordRecord`, `SessionRecord`, `TokenRecord`, `TokenKind`, `Json`,
+`PasswordRecord`, `SecondFactorRecord`, `SessionRecord`, `TokenRecord`, `TokenKind`, `Json`,
 `JsonObject`, and `ObjectPageRequest`, `RelationChanges` from
 `@nxgt/janus/permissions`.
 
@@ -185,7 +294,7 @@ compile error naming the missing method.
 
 | Suite | Cases | Harness opens |
 | --- | --- | --- |
-| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 38: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" | `{ stores, faults?, close? }` |
+| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 44: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — twelve of them | `{ stores, faults?, close? }` |
 | `describeRelationStores({ name, harness, runner?, faults?, skip? })` | 15: the relation store, and one outage per method | `{ store, faults?, close? }` |
 
 `harness.open()` is called **once per case** and must answer fresh, empty
@@ -202,6 +311,18 @@ stores: a case that leaks into the next is the hardest failure to debug.
 
 The suites import no test framework and no assertion library.
 
+The second factor and attempts have their own cases — skip one by its id
+while you work on it, never to ship:
+
+| Case | Checks |
+| --- | --- |
+| `users.secondFactorSlot` | round-trip; a patch not naming it keeps it; `null` removes it |
+| `tokens.countAttempt` | two calls answer `attempts` 1 then 2, `codeHash` as written; `consumeToken` answers the count |
+| `tokens.countAttemptConcurrency` | twenty concurrent calls answer 1 to 20, each once |
+| `tokens.countAttemptRace` | attempts racing one redemption: the counts answered unspent are 1 to the final count, and every answer after the spend carries that final count |
+| `tokens.countAttemptSpent` | a spent token answered unchanged; another kind and an unknown hash answer `null` and count nothing |
+| `outage.countAttempt` | a store that cannot answer rejects, never `null` |
+
 ### `faults`: prove the outage invariant
 
 `faults` is optional, and **its absence is reported, never passed over**:

package/docs/guide/permissions.md

@@ -182,8 +182,6 @@ the key you wrote, `types.record.permits.view` or `types.team.related.members`:
 - `relations` or `permissions` — the keys before 0.2 — and any key other than
   `related` and `permits`;
 - a name that is not camelCase;
-- an object type named like a user type — see
-  [permissions on a user](#permissions-on-a-user);
 - a permission that reaches itself without crossing a relation (`view:
   ['edit'], edit: ['view']`) — no data could ever end that loop;
 - a subject set or an arrow that would have to read **another** object's
@@ -196,8 +194,8 @@ fine: the data ends it. See [a hierarchy](#a-hierarchy).
 ## Use cases
 
 Each case below runs against the clinic above, in order — except the two that
-say otherwise: a folder tree for a hierarchy, and an `account` for
-permissions on a user.
+say otherwise: a folder tree for a hierarchy, and staff members who manage
+each other for permissions on a user.
 
 ### A direct relation
 
@@ -231,6 +229,10 @@ await access.grant(team, 'members', { type: 'team', id: 't2', relation: 'members
 await access.can(grace, 'view', team); // true: grace is a member of t2, whose members are members of t1
 ```
 
+`setOf(cardiology, 'members')`, from `@nxgt/janus`, writes the same set. On an
+object type the two are the same; on a user type only `setOf` makes a set —
+see [permissions on a user](#permissions-on-a-user).
+
 The set is followed as the data stands: revoke grace from `t2`, and she no
 longer views `t1`. A team member of itself — a cycle in the data — is cut, and
 is not an error.
@@ -347,38 +349,68 @@ await access.list(grace, 'edit', 'record', { ctx: { onShift: true } });
 
 ### Permissions on a user
 
-A user type cannot also be an object type: `defineModel` refuses `staff` in
-`types` — `"staff" names a user type and an object type`. To decide who may
-edit a staff member's account, declare an object type **whose id is the
-user's id**, and read it with `fromField('id', …)`:
+A user type may also be an object type: declare `staff` under `types`, and a
+staff member is an object like a record — asked `can()`, granted relations,
+listed. To decide who may edit a staff member, give `staff` the relations that
+say so:
 
 ```ts
-const accounts = permissions({
+import { setOf } from '@nxgt/janus';
+
+const people = permissions({
 	model: defineModel({
 		subjects: auth.types,
 		types: {
-			account: {
+			staff: {
 				related: {
 					self: fromField('id', 'staff', { lookup: async (staffId) => [staffId] }),
-					managers: ['staff'],
+					managers: ['staff', 'staff#managers'],
 				},
 				permits: { edit: ['self', 'managers'] },
 			},
+			note: {
+				related: { readers: ['staff', 'staff#managers'] },
+				permits: { read: ['readers'] },
+			},
 		},
 	}),
 	store: relations,
 });
 
 const bob = await auth.staff.create({ username: 'bob' });
-await accounts.can(bob, 'edit', { type: 'account', id: bob.id }); // true: his own account
-await accounts.can(ada, 'edit', { type: 'account', id: bob.id }); // false
-await accounts.grant({ type: 'account', id: bob.id }, 'managers', ada);
-await accounts.can(ada, 'edit', { type: 'account', id: bob.id }); // true: she manages it
-await accounts.list(ada, 'edit', 'account');                      // her own account, and bob's
+await people.can(bob, 'edit', bob);              // true: himself, read from his id
+await people.can(ada, 'edit', bob);              // false
+await people.grant(bob, 'managers', ada);
+await people.can(ada, 'edit', bob);              // true: she manages him
+await people.list(ada, 'edit', 'staff');         // herself, and bob
+```
+
+**A user passed as it is, is that user** — never a set, even when one of its
+fields is named `relation`. A set on a user type is made by **`setOf`**: every
+staff member who manages bob reads the note, as the data stands:
+
+```ts
+const note = { type: 'note', id: 'n1' } as const;
+await people.grant(note, 'readers', setOf(bob, 'managers'));
+await people.can(ada, 'read', note); // true: she manages bob
+await people.can(bob, 'read', note); // false: bob is not his own manager
 ```
 
-The `lookup` answers the one account whose id is the subject's, so `list()`
-finds a user's own account too.
+Only `setOf` marks a set. `{ type: 'staff', id: bob.id, relation: 'managers' }`
+written out is bob himself at run time: granted silently where the relation
+admits a staff member, refused where it does not. The compiler refuses it in
+`grant()` and `revoke()`; `can()` and `list()` accept it and ask about bob, a
+gap the README names. A spread
+of a set keeps the mark; `JSON` and `structuredClone` drop it, so a set read
+back from either is bob again — call `setOf` on it, or keep its notation
+(`staff:…#managers`), which `parseSubject` reads back as the set. It copies
+`type` and `id` only, so none of bob's fields reaches a tuple. A set on a user type
+the model does not also declare under `types` is refused by `can()`, `list()`,
+`grant()` and `revoke()` — and by the compiler first: there is no relation to
+hold.
+
+The `lookup` of `self` answers the one staff member whose id is the subject's,
+so `list()` finds ada herself too.
 
 ## `permissions()`
 

package/docs/guide/vocabulary.md

@@ -37,7 +37,7 @@ either finds this row.
 | Word | Means | Not |
 | --- | --- | --- |
 | **user** | One stored person or machine, of one user type | "account" — kept only in *account takeover* and *account enumeration*, the names of those attacks |
-| **user type** | A kind of user with its own schema and login: `staff`, `patient`. Wired to permissions, its name is a subject type | "role": a role is a relation in the model |
+| **user type** | A kind of user with its own schema and login: `staff`, `patient`. Wired to permissions, its name is a subject type — and may also be an object type, whose users are then objects too | "role": a role is a relation in the model |
 | **schema** | A user type's Standard Schema: the fields a user carries | the model |
 | **login** | The value a user signs in with: an e-mail, a username. **sign in** is the verb, **sign-in** the noun | "identifier" |
 | **credential** | What a caller presents to prove who they are: a login and a password at sign-in (`CredentialError`, `CREDENTIALS_INVALID`), or a token on a request — always written *session credential* | |
@@ -47,7 +47,9 @@ either finds this row.
 | **anonymous** | A request that presents no session credential, or one that authenticates nobody: `authenticate` answers `null` | "unauthenticated", "guest", "logged out" |
 | **bearer client** | A client that sends its session token as `Authorization: Bearer` rather than in a cookie | |
 | **one-time token** | A single-use token sent by e-mail, for verification or a password reset | "code" alone — `code` is an error's code |
-| **one-time code** | Planned, see [the roadmap](../roadmap.md#next): a one-time token short enough to type, sent by e-mail — or, for TOTP, computed by an authenticator app and never sent | "OTP", "PIN", "code" alone |
+| **one-time code** | In progress, see [the roadmap](../roadmap.md): a one-time token short enough to type, sent by e-mail — or, for TOTP, computed by an authenticator app and never sent | "OTP", "PIN", "code" alone |
+| **second factor** | What a user proves at sign-in beyond their password: a TOTP secret their authenticator app holds, `UserRecord.secondFactor`. **Enrolled** when stored, **confirmed** once a first code matched (`confirmedAt`) | "2FA", "MFA", "OTP device" |
+| **attempt** | One code tried against a one-time token, counted by `countAttempt` in the token's `attempts` | "try"; "retry" is a repeated write, never a guess |
 | **token** | Never alone in prose: a *session token* or a *one-time token*. The `tokens` store and the `TOKEN_*` codes are one-time tokens only | |
 | **e-mail flow** | `verifyEmail` or `resetPassword`: send a one-time token, then confirm it | |
 
@@ -57,10 +59,11 @@ either finds this row.
 | --- | --- | --- |
 | **model** | What `defineModel()` answers: the subject types, the object types, their relations and permissions | "schema", "policy" |
 | **subject type** | A name listed in `subjects`: `auth.types` when wired to `janus()`, your own names otherwise | |
-| **object** | What a permission is about: `{ type: 'document', id }` | "resource" |
+| **object** | What a permission is about: `{ type: 'document', id }`, or a user whose type the model also declares under `types` | "resource" |
 | **subject** | Who a permission is about: a user, an object, or a subject set | "principal", "actor" |
 | **entity** | `{ type, id }`: a user or an object — a subject that is not a set (`Entity`, `deleteEntity`) | |
-| **subject set** | Everyone holding one relation on one object: `team:t1#members` | "group" — a group is an object with a `members` relation |
+| **subject set** | Everyone holding one relation on one object: `team:t1#members`. On a user type the model also declares as an object type, only `setOf()` makes one | "group" — a group is an object with a `members` relation |
+| **`setOf`** | The function that makes a subject set from a user or an object and a relation: `setOf(bob, 'managers')`. What it answers is a `SetOf`, and `isSetOf` tells it from a user | |
 | **relation** | A named link, stored as tuples or read from a field (`fromField`). Declared under `related`, named in the plural: `members`, `doctors` | |
 | **`related`** | The key of an object type that declares its relations: `related: { members: ['staff'] }`. It was `relations` before 0.2, and the old key is refused | "relations" as a key — the word stays for the idea, and for `janus({ relations })` |
 | **holder** | What a relation admits: `'staff'`, or the subject set `'team#members'` | |
@@ -114,10 +117,12 @@ a tuple.
 | --- | --- |
 | `subjectOf(user)` | `{ type, id }` of any object carrying both |
 | `isSubjectSet(subject)` | whether `relation` is a string |
+| `setOf(entity, relation)` | the subject set `{ type, id, relation }`, marked: on a user type, the only way to write one |
+| `isSetOf(value)` | whether `setOf` made it, or a spread of it |
 | `formatEntity(entity)` | `'record:r1'` |
 | `formatSubject(subject)` | `'staff:u1'`, or `'team:t1#members'` |
 | `formatTuple(tuple)` | `'team:t1#members@team:t2#members'` |
-| `parseSubject(text)` | the `Subject` back |
+| `parseSubject(text)` | the `Entity` back, or a `SetOf` — a set as `setOf` makes it |
 | `parseTuple(text)` | the `RelationTuple` back |
 
 ```ts

package/docs/roadmap.md

@@ -5,14 +5,16 @@ dates here, and the version something shipped in is the only number.
 
 ## Now
 
-Nothing yet.
-
-## Next
-
 - **One-time codes** — a one-time token short enough to type, sent by e-mail
   to sign in without a password, or to confirm a sensitive action, issued
   and redeemed by `janus` like the verification and reset tokens today; and
-  TOTP, the one-time codes of an authenticator app, as a second factor.
+  TOTP, the one-time codes of an authenticator app, as a second factor, its
+  secret sealed with a key your application holds. `signIn` will answer
+  `{ status: 'signedIn' }` or `{ status: 'secondFactor', challenge }`. The
+  store port that holds them shipped in v0.4.0, below.
+
+## Next
+
 - **Sending the e-mails** — in a package of its own, `@nxgt/janus-mail`, built
   on a general mail toolkit shared with applications that are not about
   sign-in: a `Mailer` port you plug your transport into (SMTP, Resend, SES…) —
@@ -84,6 +86,18 @@ Nothing yet.
 
 Each entry names the version it came in.
 
+- **The store port holds a second factor and counts attempts on a token,
+  v0.4.0** — `UserRecord.secondFactor`, a token's `codeHash` and `attempts`,
+  the token kinds `'secondFactor'` and `'signInCode'`, and
+  `TokenStore.countAttempt`, one conditional write per attempt, with six new
+  conformance cases. No flow uses them yet; the published adapters implement
+  them in `@nxgt/janus-drizzle` 0.2, `@nxgt/janus-mongo` 0.3 and
+  `@nxgt/janus-redis` 0.2.
+- **Permissions on a user, v0.3.0** — a user type may also be an object type:
+  a staff member is the object `can()` asks about and is granted relations
+  on, like a record, and `grant(note, 'readers', setOf(bob, 'managers'))`
+  grants everyone who manages bob at once. A user
+  passed as it is stays that user, even with a field named `relation`.
 - **The adapters and the kit, each at its first release, v0.1.0, beside
   `@nxgt/janus` 0.2.2** —
   [`@nxgt/janus-drizzle`](https://www.npmjs.com/package/@nxgt/janus-drizzle),

package/docs/troubleshooting.md

@@ -208,6 +208,10 @@ Also: `janus: store.<slot> is missing`, `janus: store must be an object with use
 
 **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. `deleteExpiredSessions` is the one optional method: absent, or a function.
+An adapter written against `@nxgt/janus` 0.3 reports
+`store.tokens has no method countAttempt` until it implements the method 0.4
+added.
+
 **Fix:** pass the three stores, whole:
 
 ```ts
@@ -216,6 +220,18 @@ import { createMemoryStores, janus } from '@nxgt/janus';
 janus({ ..., store: createMemoryStores() });
 ```
 
+For `countAttempt`, upgrade the published adapter to the release that
+implements it — `@nxgt/janus-drizzle` 0.2, `@nxgt/janus-mongo` 0.3,
+`@nxgt/janus-redis` 0.2:
+
+```bash
+bun add @nxgt/janus@^0.4 @nxgt/janus-drizzle@^0.2 # or @nxgt/janus-mongo@^0.3, @nxgt/janus-redis@^0.2
+```
+
+Your own adapter implements it as
+[`TokenStore.countAttempt`](guide/adapters.md#tokenstorecountattempt) sets
+out, then runs the conformance suite.
+
 ### `janus: relations must be a relation store — relations.deleteEntity is missing`
 
 **When:** `janus({ ..., relations })`.
@@ -571,11 +587,12 @@ Each is a `TypeError` naming the call. TypeScript refuses most of them on the ar
 | Message | Fix |
 | --- | --- |
 | `can: "<name>" is not a relation or a permission of <type>` | Ask a name the type declares. |
-| `<call>: "<type>" is not an object type of the model` | Use a type declared under `types`. |
+| `<call>: "<type>" is not an object type of the model` | Use a type declared under `types`. Also for a subject set — `setOf` included — whose type is neither a user type nor an object type. |
 | `<call>: the object must be { type, id, …its fields }` | `{ type: 'record', ...record }`. |
 | `<call>: the subject must be a user, or { type, id }` | Pass the user from `janus()`, or `{ type, id }`. `null` is anonymous and answers `false`. |
 | `<call>: the object id must be a non-empty string without @, # or parentheses` | Also for `the subject id`. Those characters belong to the tuple notation. |
-| `<call>: "<relation>" is not a relation of <type>, so <type>:<id>#<relation> is no subject set` | A subject set names a relation of its type: `{ type: 'team', id, relation: 'members' }`. |
+| `<call>: "<relation>" is not a relation of <type>, so <type>#<relation> is no subject set` | A subject set names a relation of its type: `{ type: 'team', id, relation: 'members' }`. |
+| `<call>: <type> is a user type the model does not declare as an object type, so <type>#<relation> is no subject set` | `setOf(user, relation)` names a relation on that user: declare the user type under `types` too, with that relation — see [permissions on a user](guide/permissions.md#permissions-on-a-user). The compiler refuses it first. |
 | `grant: "<relation>" is not a relation of <type>` | Grant a relation, never a permission. |
 | `list: the type must be an object type of the model` | The third argument is a type name: `'record'`. |
 | `list: after must be the nextCursor of a page, or null` | Pass `nextCursor` back as it came. |
@@ -594,7 +611,6 @@ most common:
 | `defineModel: types declares no object type` | Declare at least one type under `types`. |
 | `defineModel: types.<type> must be an object` | Also `types.<type>.related must be an object` and `types.<type>.permits must be an object`: each is keyed by name — `related: { members: ['staff'] }`. |
 | `defineModel: the object type "<name>" must be a camelCase name — letters and digits, starting with a lowercase letter` | Also `types.<type>.related: "<name>" must be a camelCase name — …` for a relation, and `types.<type>.permits: …` for a permission. |
-| `defineModel: "<name>" names a user type and an object type; a subject of type "<name>" would be ambiguous` | Rename the object type. For permissions on a user, see [the guide](guide/permissions.md#permissions-on-a-user). |
 | `defineModel: types.<type>: "<name>" names a relation and a permission; rename one` | One name, one meaning. |
 | `defineModel: types.<type>.related.<relation> must be a non-empty array of subject types, or fromField()` | `members: ['staff']`, or `doctors: fromField('doctorId', 'staff')`. |
 | `defineModel: types.<type>.related.<relation>: "<holder>" is not a subject type` | Also `"<holder>" is not a subject set — it must name an object type and one of its relations`: `'team#members'`, a declared type and one of its relations. |
@@ -634,6 +650,21 @@ parseTuple('record:r1#teams@team:t1');
 parseTuple('team:t1#members@team:t2#members');
 ```
 
+### `setOf: pass a user or { type, id }, then a relation`
+
+Also `setOf: the relation must be a non-empty string`.
+
+**When:** `setOf(...)`, a `TypeError`.
+**Why:** a set is everyone holding one relation on one user or object: it needs both.
+**Fix:**
+
+```ts
+import { setOf } from '@nxgt/janus';
+
+setOf(bob, 'managers');                          // a user from janus()
+setOf({ type: 'team', id: 't1' }, 'members');    // an object
+```
+
 ---
 
 ## Conformance (adapter authors)

package/package.json

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