@starci/auth 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.3.0 - 2026-11-03
+
+- Added: a session carries the person's full name when the account directory knows it: `AccountStanding.name` and `AuthSubject.name` in; `SessionUser.name`, the `name` access-token claim (`AUTH_CLAIMS.name`), `AccessClaims.name` and `AuthPrincipal.name` out. The client keeps it (from the grant, or from the token when the grant carries no user) and announces a change of it. An account without a name answers as before.
+
 ## 0.2.1 - 2026-11-03
 
 - Fixed: a refresh replayed inside the grace window no longer signs the person out 30 seconds later. When a rotation's response never reached the browser (a navigation or an abort cut it), the next load presented the spent token, was answered an access token with no cookie (`cookieKept`) and the first load after the grace was reuse. Now `AuthSessions.refresh` gives such a replay a successor of its own in the same session and `AuthDoors.refresh` sets it as the cookie, at most `RACED_SUCCESSORS_MAX` (3) times per rotated token (`raced_count`); one more replay is reuse and ends the session, which revokes every token of it, as sign-out does. `SessionTokens.cookieKept` is removed; the session door never touched the cookie.

package/dist/client/auth-client.d.ts

@@ -45,7 +45,7 @@ export interface AuthClient {
     accessToken(): Promise<string | undefined>;
     /** The held access token without any request. */
     peek(): string | undefined;
-    /** The signed-in person (id and email), or null when signed out. */
+    /** The signed-in person (id, email and the full name when the account has one), or null when signed out. */
     user(): Promise<SessionUser | null>;
     /** The `Authorization` header of the current session (an empty object when signed out). */
     headers(): Promise<Record<string, string>>;

package/dist/client/auth-client.js

@@ -20,11 +20,14 @@ const claimsOf = (token) => {
         return {};
     }
 };
+/** The full name of a person, when a grant or a token names one. */
+const nameOf = (name) => (typeof name === "string" ? { name } : {});
 const userOf = (grant) => {
-    if (typeof grant.user === "object" && typeof grant.user.id === "string")
-        return { id: grant.user.id, email: typeof grant.user.email === "string" ? grant.user.email : "" };
-    const { sub, email } = claimsOf(grant.accessToken);
-    return typeof sub === "string" ? { id: sub, email: typeof email === "string" ? email : "" } : null;
+    if (typeof grant.user === "object" && typeof grant.user.id === "string") {
+        return { id: grant.user.id, email: typeof grant.user.email === "string" ? grant.user.email : "", ...nameOf(fieldOf(grant.user, "name")) };
+    }
+    const { sub, email, name } = claimsOf(grant.accessToken);
+    return typeof sub === "string" ? { id: sub, email: typeof email === "string" ? email : "", ...nameOf(name) } : null;
 };
 const MILLISECONDS = 1000;
 const timerPause = (ms) => new Promise((resolve) => {

package/dist/client/session.d.ts

@@ -4,6 +4,7 @@ export type SessionEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOK
 export interface SessionPerson {
     readonly id: string;
     readonly email: string;
+    readonly name?: string;
 }
 /** What a view reads: loading until the first answer, then signed in or out. The object changes only when the session does. */
 export interface SessionSnapshot<User extends SessionPerson> {
@@ -33,7 +34,7 @@ export interface SessionStore<User extends SessionPerson> {
     getSnapshot: () => SessionSnapshot<User>;
     /** The snapshot for server rendering: always loading. */
     getServerSnapshot: () => SessionSnapshot<User>;
-    /** Publishes the snapshot of a signed-in person; watchers hear it only when status, id or email changed. */
+    /** Publishes the snapshot of a signed-in person; watchers hear it only when status, id, email or name changed. */
     signedIn: (user: User | null) => void;
     /** Publishes the signed-out snapshot. */
     signedOut: () => void;

package/dist/client/session.js

@@ -5,7 +5,7 @@ export const createSessionStore = (source) => {
     const listeners = new Set();
     const watchers = new Set();
     const set = (next) => {
-        if (snapshot.status === next.status && snapshot.user?.id === next.user?.id && snapshot.user?.email === next.user?.email)
+        if (snapshot.status === next.status && snapshot.user?.id === next.user?.id && snapshot.user?.email === next.user?.email && snapshot.user?.name === next.user?.name)
             return;
         snapshot = next;
         for (const watcher of watchers)

package/dist/contracts/index.d.ts

@@ -30,6 +30,7 @@ export declare const AUTH_CLAIMS: {
     readonly role: "role";
     readonly sessionId: "session_id";
     readonly email: "email";
+    readonly name: "name";
 };
 /** The signature algorithm of every access token: pinned, never negotiated. */
 export declare const AUTH_ALGORITHM = "EdDSA";
@@ -63,6 +64,8 @@ export interface SessionUser {
     readonly id: string;
     /** The account email. */
     readonly email: string;
+    /** The person's full name, when the account has one. */
+    readonly name?: string;
 }
 /** What a sign-in, refresh or session door answers in the body. */
 export interface AccessGrant {

package/dist/contracts/index.js

@@ -28,6 +28,7 @@ export const AUTH_CLAIMS = {
     role: "role",
     sessionId: "session_id",
     email: "email",
+    name: "name",
 };
 /** The signature algorithm of every access token: pinned, never negotiated. */
 export const AUTH_ALGORITHM = "EdDSA";

package/dist/server/ports.d.ts

@@ -5,6 +5,8 @@ export interface AuthSubject {
     readonly userId: string;
     /** The account email. */
     readonly email: string;
+    /** The person's full name, when the account has one. */
+    readonly name?: string | undefined;
 }
 /** What Google told us about the person who consented. */
 export interface GoogleProfile {
@@ -34,6 +36,8 @@ export interface AccountStanding {
     readonly email: string | null;
     /** Whether the account is disabled or gone. */
     readonly disabled: boolean;
+    /** The person's full name, when the account has one (the session answers and the access token carry it). */
+    readonly name?: string | undefined;
 }
 /** The app's user table, seen only as far as sessions need it. */
 export interface AccountDirectory {
@@ -130,6 +134,8 @@ export interface AccessClaims {
     readonly email?: string | undefined;
     /** The device session the token belongs to. */
     readonly sessionId: string;
+    /** The person's full name at issue time, when the account has one. */
+    readonly name?: string | undefined;
 }
 /** The principal domain code builds from a verified access token. */
 export interface AuthPrincipal {
@@ -137,6 +143,7 @@ export interface AuthPrincipal {
     readonly role: "authenticated";
     readonly sessionId: string;
     readonly email?: string;
+    readonly name?: string;
 }
 /** A freshly signed access token. */
 export interface IssuedAccessToken {

package/dist/server/sessions.js

@@ -12,6 +12,8 @@ export const RACED_SUCCESSORS_MAX = 3;
 /** The log event of a replayed refresh token. */
 export const REFRESH_REUSE_EVENT = "auth.refresh-reuse-detected";
 const MILLISECONDS = 1000;
+/** The subject of a standing account: its id, its address and its full name when the directory knows one. */
+const subjectOf = (user, email) => ({ userId: user.id, email, ...(user.name === undefined ? {} : { name: user.name }) });
 /**
  * Device sessions: opens one at sign-in, rotates its refresh token on every refresh (a replayed token ends the session) and ends it
  * at sign-out. A token rotated within the grace window gets a successor of its own in the same session, at most
@@ -92,7 +94,7 @@ export class AuthSessions {
             throw new AuthError(AUTH_ERROR_CODES.AccountDisabled);
         }
         await this.#store.touchSession(rotation.row.sessionId, now);
-        return this.#tokensFor({ userId: user.id, email: user.email }, rotation.row.sessionId, rotation.next, now);
+        return this.#tokensFor(subjectOf(user, user.email), rotation.row.sessionId, rotation.next, now);
     }
     /**
      * Answers a fresh access token for the session of a refresh token WITHOUT rotating it, so parallel gated requests of one browser
@@ -138,17 +140,18 @@ export class AuthSessions {
             await this.#store.closeSession(row.sessionId);
             throw new AuthError(AUTH_ERROR_CODES.AccountDisabled);
         }
-        return this.#tokensFor({ userId: user.id, email: user.email }, row.sessionId, presented, now);
+        return this.#tokensFor(subjectOf(user, user.email), row.sessionId, presented, now);
     }
     async #tokensFor(subject, sessionId, refreshToken, now) {
-        const access = await this.#deps.tokens.sign({ sub: subject.userId, email: subject.email, sessionId }, now);
+        const name = subject.name === undefined ? {} : { name: subject.name };
+        const access = await this.#deps.tokens.sign({ sub: subject.userId, email: subject.email, sessionId, ...name }, now);
         return {
             accessToken: access.token,
             accessExpiresAt: access.expiresAt.toISOString(),
             accessExpiresIn: Math.round((access.expiresAt.getTime() - now.getTime()) / MILLISECONDS),
             cookieToken: refreshToken,
             refreshMaxAgeSeconds: this.#deps.options.refreshTtlSeconds,
-            user: { id: subject.userId, email: subject.email },
+            user: { id: subject.userId, email: subject.email, ...name },
         };
     }
     #refreshExpiry(now) {

package/dist/server/tokens.js

@@ -25,6 +25,7 @@ export class AuthTokens {
             [AUTH_CLAIMS.role]: AUTH_ROLE,
             [AUTH_CLAIMS.sessionId]: claims.sessionId,
             ...(claims.email === undefined ? {} : { [AUTH_CLAIMS.email]: claims.email }),
+            ...(claims.name === undefined ? {} : { [AUTH_CLAIMS.name]: claims.name }),
         })
             .setProtectedHeader({ alg: AUTH_ALGORITHM, kid: signer.keyId, typ: "JWT" })
             .setSubject(claims.sub)
@@ -50,7 +51,8 @@ export class AuthTokens {
                 return refused(AUTH_ERROR_CODES.AccessTokenInvalid);
             }
             const email = payload[AUTH_CLAIMS.email];
-            return ok({ sub: payload.sub, sessionId, ...(typeof email === "string" ? { email } : {}) });
+            const name = payload[AUTH_CLAIMS.name];
+            return ok({ sub: payload.sub, sessionId, ...(typeof email === "string" ? { email } : {}), ...(typeof name === "string" ? { name } : {}) });
         }
         catch (cause) {
             return refused(AUTH_ERROR_CODES.AccessTokenInvalid, { cause: String(cause) });

package/dist/server/verifier.js

@@ -13,8 +13,8 @@ export class AuthPrincipalVerifier {
         const verified = await this.#tokens.verify(token, now);
         if (verified.kind === "refused")
             return refused(AUTH_ERROR_CODES.AccessTokenInvalid);
-        const { sub, email, sessionId } = verified.value;
-        return ok({ id: sub, role: AUTH_ROLE, sessionId, ...(email === undefined ? {} : { email }) });
+        const { sub, email, name, sessionId } = verified.value;
+        return ok({ id: sub, role: AUTH_ROLE, sessionId, ...(email === undefined ? {} : { email }), ...(name === undefined ? {} : { name }) });
     }
 }
 /** The verifier of an app that serves no user session: every access token is refused, so the default-deny guard admits only its public and credential doors. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/auth",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The sign-in of a StarCi lite app in one package: a NestJS module (EdDSA access tokens with a multi-key JWKS, bcrypt passwords, Google OAuth with state and PKCE, rotating refresh tokens with a reuse grace window and reuse detection, a failures-only sign-in limit, the refresh cookie), the door contracts, a front-end auth client (access token in memory, one shared refresh, signed out only on 401 or 403) with React bindings, and test doubles.",
   "keywords": [
     "auth",