@nxgt/janus 0.2.0 → 0.2.2

package/docs/guide/users.md

@@ -66,7 +66,11 @@ time. A schema is any [Standard Schema](https://standardschema.dev) (Zod 4,
 Valibot, ArkType), and its output must be JSON: a schema that produces a
 `Date` is refused at compile time, because a `Date` round-trips through one
 database and not the next. An optional field left `undefined` is dropped
-before the store sees it.
+before the store sees it. A string or a key holding a NUL character (`\u0000`)
+or a lone surrogate is refused with `USER_INVALID`, on every adapter: PostgreSQL
+keeps neither, so janus refuses them everywhere rather than fail on one. So is
+a login your own `password.normalize` function turns into one — a `slice`
+that cuts an emoji in half, say.
 
 ## Options
 
@@ -179,7 +183,7 @@ With a `password`, besides:
 | --- | --- | --- |
 | `signUp(fields & { password })` | `{ user, session, token }` | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `LOGIN_TAKEN` |
 | `signIn({ [login]: string, password })` | `{ user, session, token }` | `CREDENTIALS_INVALID`, `USER_INACTIVE`, `HASH_UNSUPPORTED` |
-| `findByLogin(login)` | the user, or `null`; the login is normalised first | |
+| `findByLogin(login)` | the user, or `null`; the login is normalised first, and one holding a NUL or a lone surrogate is nobody's | |
 | `setPassword(user, password, { ifVersion? })` | the user — an admin's call | `PASSWORD_TOO_SHORT` |
 | `changePassword(user, { current, next }, { ifVersion? })` | the user — the user's own call | `CREDENTIALS_INVALID`, `PASSWORD_TOO_SHORT` |
 

package/docs/guide/vocabulary.md

@@ -46,7 +46,8 @@ either finds this row.
 | **lapsed**, **revoked**, **renewed** | A session past its `expiresAt`; one ended by a sign-out or a password reset; one whose `expiresAt` moved in passing (`renewAfter`) | "expired" — kept for `TOKEN_EXPIRED`, a one-time token |
 | **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" — `code` is an error's code |
+| **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 |
 | **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 | |
 
@@ -77,7 +78,7 @@ either finds this row.
 | --- | --- | --- |
 | **store** | Where a side keeps its data, behind a port. The **identity stores** are `users`, `sessions` and `tokens`; the **relation store** holds the tuples | "database", "repository" |
 | **port** | The interface a store implements: `JanusStores` for the identity stores — named after the package, not the side — and `RelationStore` | "driver" |
-| **adapter** | A package implementing the ports for one database: `@nxgt/janus-mongo`. What its `create…Adapter(db)` answers is its stores, keyed as `janus()` takes them — `{ store, relations }` | "plugin", "connector" |
+| **adapter** | A package implementing the ports for one database: `@nxgt/janus-mongo`, `@nxgt/janus-drizzle`, `@nxgt/janus-redis`. What its `create…Adapter(db)` answers is its stores, keyed as `janus()` takes them — `{ store, relations }` | "plugin", "connector" |
 | **integration** | A package fitting Janus into one web framework or one observability library: `@nxgt/janus-hono`, `@nxgt/janus-telemetry`. It implements no port | "plugin", "adapter" |
 | **kit** | A package that opens the connections and wires adapters and integrations into one object for an application: `@nxgt/janus-kit`'s `connectKit` answers `{ auth, access, db, redis, ping, close }`. It implements no port, and `janus()` and `permissions()` are still written by the application | "framework", "starter" |
 

package/docs/roadmap.md

@@ -5,21 +5,37 @@ dates here, and the version something shipped in is the only number.
 
 ## Now
 
-- **A PostgreSQL adapter** — in a package of its own, `@nxgt/janus-drizzle`,
-  on Drizzle: both sides over one database, the tables in your own drizzle-kit
-  migrations. Built, not yet published.
-- **Tracing and an audit trail** — in a package of its own,
-  `@nxgt/janus-telemetry`: a span per flow and per permission check, and the
-  security events worth keeping, never a login, a password or a token. Built,
-  not yet published.
-- **A Redis adapter for sessions and tokens** — in a package of its own,
-  `@nxgt/janus-redis`: both are read on every request and ephemeral, so they
-  live in Redis, expired by Redis itself, while users stay in another store.
-  Built, not yet published.
+Nothing yet.
 
 ## Next
 
-Nothing yet.
+- **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.
+- **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…) —
+  a transport that fails throws, like a store — and default templates for
+  verification, password reset and one-time codes, in English and French. One
+  template per e-mail, never one HTML file per language: the layout is built
+  once with Maizzle and Tailwind CSS 4 — CSS inlined for mail clients — and
+  its text lives in ICU message catalogues, one per language, plurals and
+  dates included. Both are compiled when the package is built into typed
+  functions: `templates.verifyEmail({ locale: 'fr', link })` answers
+  `{ subject, html, text }`, every value escaped, a missing variable or an
+  unknown locale a compile error, a message that fails to format a throw —
+  never an e-mail sent with `{link}` in it. No template engine at run time.
+  The defaults are a starting point, not a requirement: add a language with a
+  catalogue, or replace any one template with your own function of the same
+  shape — built with the same toolkit, React Email or a plain string — and
+  keep the defaults for the rest.
+- **Webhooks** — signed HTTP events when something happens to a user
+  (created, e-mail verified, password reset, deleted), so another service can
+  follow without polling: a signature it can check, retries on failure, and
+  the same rule as the audit trail — the user named by id, never a login, a
+  password, a session token or a one-time token in a payload, and every key
+  camelCase. Retries that run out are reported, never dropped in silence.
 
 ## Later
 
@@ -66,7 +82,19 @@ Nothing yet.
 
 ## Shipped
 
-The first public release, v0.1.
+Each entry names the version it came in.
+
+- **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),
+  both sides over one PostgreSQL database on Drizzle;
+  [`@nxgt/janus-redis`](https://www.npmjs.com/package/@nxgt/janus-redis),
+  sessions and one-time tokens in Redis, expired by Redis itself;
+  [`@nxgt/janus-telemetry`](https://www.npmjs.com/package/@nxgt/janus-telemetry),
+  a span per flow and per permission check, and the security events worth an
+  audit trail, never a login, a password, a session token or a one-time token;
+  and [`@nxgt/janus-kit`](https://www.npmjs.com/package/@nxgt/janus-kit), all
+  of it wired in one call.
 
 - **The model's keys read `related` and `permits`** — Keto's OPL words: an
   object type declares `related: { members: ['staff', 'team#members'] }` and
@@ -74,13 +102,17 @@ The first public release, v0.1.
   `relations` and `permissions` as keys are refused, by the compiler and by
   `defineModel`, with a message naming the new key —
   `types.team.relations is now related: rename the key`. The `permissions()`
-  function and `janus({ relations })` keep their names. — next minor
+  function and `janus({ relations })` keep their names. — v0.2.0
 - **`LOGIN_TAKEN` no longer quotes the login in its message**, in the memory
   store and in both adapters; `error.login` still names it, and the
-  conformance suite checks it. — next patch
+  conformance suite checks it. — v0.2.0
 - **The conformance suite accepts a store with its own expiry** — a store
   that drops a lapsed session at once, as a Redis TTL does, passes
-  `sessions.deleteUser`; one that still holds it must count it. — next patch
+  `sessions.deleteUser`; one that still holds it must count it. — v0.2.0
+- **A NUL character or a lone surrogate never reaches a store** — refused in
+  fields with `USER_INVALID` on every adapter, rather than `STORE_FAILED` on
+  PostgreSQL alone; a login holding one is nobody's. The conformance suite
+  holds every adapter to round-tripping every other character. — v0.2.1
 
 - **A Hono integration** — [`@nxgt/janus-hono`](https://www.npmjs.com/package/@nxgt/janus-hono):
   the session middleware, the cookie, a route guarded by a permission,

package/docs/troubleshooting.md

@@ -354,7 +354,7 @@ await auth.update(user, { name }, { ifVersion: user.version });
 `UserInvalidError`, carrying `issues` — each a `path` and a `message`.
 
 **When:** `signUp`, `create`, `update`.
-**Why:** your schema refused the fields. `update` merges the patch over the stored fields and validates the whole, so the refusal can name a field the patch did not touch. An issue whose message is `set by janus, not by a request` means the input carried a field janus sets (`id`, `active`, `version`, …) and your schema let it through.
+**Why:** your schema refused the fields. `update` merges the patch over the stored fields and validates the whole, so the refusal can name a field the patch did not touch. An issue whose message is `set by janus, not by a request` means the input carried a field janus sets (`id`, `active`, `version`, …) and your schema let it through. An issue whose message is `holds a NUL character or a lone surrogate, which no store can keep` means a string — or, with `a key holds …`, an object key — carried `\u0000` or half of a surrogate pair: PostgreSQL refuses both, so janus refuses them on every adapter rather than answer `STORE_FAILED` on one. A key is reported by the path of the object holding it, never by the key itself — in janus's issues and in your schema's alike. An issue at your login field whose message is `normalises to a login that holds …` means your own `password.normalize` function produced such a login from a valid field: fix the function. On MongoDB or the memory store, a user written before janus refused these characters may already hold one: every `update` of that user is refused, whatever it patches, until the field is cleaned — patch it with a clean value in the same `update`.
 **Fix:** answer 400, field by field:
 
 ```ts
@@ -374,7 +374,7 @@ if (error instanceof UserInvalidError) {
 Also `changePassword: the current password does not match`.
 
 **When:** `signIn`, `changePassword`.
-**Why:** no user holds the login, the user has no password, or the password is wrong — **one code for the three**. `error.reason` (`unknownLogin`, `noPassword`, `wrongPassword`) tells them apart for your logs and your rate limiter.
+**Why:** no user holds the login, the user has no password, or the password is wrong — **one code for the three**. `error.reason` (`unknownLogin`, `noPassword`, `wrongPassword`) tells them apart for your logs and your rate limiter. A login holding a NUL character or a lone surrogate is `unknownLogin`: no user can hold one.
 **Fix:** answer 401 with the same body whatever the reason:
 
 ```ts

package/package.json

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