@starci/auth 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.0 - 2026-11-04
+
+- Added: `RefreshCookieOptions.domains`: the refresh cookie's `Domain` follows the request host (its `Host` header without the port). A host equal to a listed domain, or ending in `.` and one, takes the longest that fits; any other host takes `domain`, else stays host-only, so one api signs in on localhost (host-only) and on a tunnel origin (its parent domain).
+- Changed: `RefreshCookie.issue(response, tokens, request)` and `clear(response, request)` take the request; `AuthDoors` passes it at every write and clear. Specs: `src/server/cookie.spec.ts` (localhost host-only, a tunnel host under a listed domain, the longest fit, an unlisted host and no host fall back).
+
+## 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/cookie.d.ts

@@ -2,8 +2,9 @@ import type { HttpRequest, HttpResponse } from "./http.js";
 import type { RefreshCookieOptions } from "./options.js";
 import type { DeviceMeta, SessionTokens } from "./ports.js";
 /**
- * The refresh cookie: httpOnly and Secure on every write and clear, SameSite lax (or strict), on the configured domain so the web
- * app and the API both see it. The token only ever leaves the back end through this cookie, never in a body or a URL.
+ * The refresh cookie: httpOnly and Secure on every write and clear, SameSite lax (or strict), on the domain the request host falls
+ * under (one of `domains`, else `domain`, else host-only) so the web app and the API both see it. The token only ever leaves the back
+ * end through this cookie, never in a body or a URL.
  */
 export declare class RefreshCookie {
     #private;
@@ -13,7 +14,7 @@ export declare class RefreshCookie {
     /** The device a request comes from: its user agent (bounded) and caller address. */
     deviceOf(request: HttpRequest): DeviceMeta;
     /** Sets the cookie to the refresh token of a session, clearing the copies older sessions kept under their paths. */
-    issue(response: HttpResponse, tokens: SessionTokens): void;
+    issue(response: HttpResponse, tokens: SessionTokens, request: HttpRequest): void;
     /** Clears the cookie on its path and on the paths older sessions used. */
-    clear(response: HttpResponse): void;
+    clear(response: HttpResponse, request: HttpRequest): void;
 }

package/dist/server/cookie.js

@@ -2,8 +2,9 @@ import { cookieValue } from "./primitives.js";
 const MAX_AGENT_LENGTH = 512;
 const MILLISECONDS = 1000;
 /**
- * The refresh cookie: httpOnly and Secure on every write and clear, SameSite lax (or strict), on the configured domain so the web
- * app and the API both see it. The token only ever leaves the back end through this cookie, never in a body or a URL.
+ * The refresh cookie: httpOnly and Secure on every write and clear, SameSite lax (or strict), on the domain the request host falls
+ * under (one of `domains`, else `domain`, else host-only) so the web app and the API both see it. The token only ever leaves the back
+ * end through this cookie, never in a body or a URL.
  */
 export class RefreshCookie {
     #options;
@@ -22,18 +23,27 @@ export class RefreshCookie {
         return { userAgent: text?.slice(0, MAX_AGENT_LENGTH) ?? null, ip: request.ip ?? null };
     }
     /** Sets the cookie to the refresh token of a session, clearing the copies older sessions kept under their paths. */
-    issue(response, tokens) {
+    issue(response, tokens, request) {
+        const domain = this.#domainOf(request);
         for (const path of this.#legacyPaths())
-            response.clearCookie(this.#options.name, this.#flags(path));
+            response.clearCookie(this.#options.name, this.#flags(path, domain));
         response.cookie(this.#options.name, tokens.cookieToken, {
-            ...this.#flags(this.#path()),
+            ...this.#flags(this.#path(), domain),
             maxAge: tokens.refreshMaxAgeSeconds * MILLISECONDS,
         });
     }
     /** Clears the cookie on its path and on the paths older sessions used. */
-    clear(response) {
+    clear(response, request) {
+        const domain = this.#domainOf(request);
         for (const path of [this.#path(), ...this.#legacyPaths()])
-            response.clearCookie(this.#options.name, this.#flags(path));
+            response.clearCookie(this.#options.name, this.#flags(path, domain));
+    }
+    /** The `Domain` for a request: the longest listed domain its host (without the port) equals or ends under, else the configured one. */
+    #domainOf(request) {
+        const header = request.headers.host;
+        const host = (Array.isArray(header) ? header[0] : header)?.replace(/:\d+$/u, "").toLowerCase() ?? "";
+        const fits = (this.#options.domains ?? []).filter((domain) => host === domain || host.endsWith(`.${domain}`));
+        return fits.sort((a, b) => b.length - a.length)[0] ?? this.#options.domain;
     }
     #path() {
         return this.#options.path ?? "/";
@@ -41,8 +51,7 @@ export class RefreshCookie {
     #legacyPaths() {
         return (this.#options.legacyPaths ?? ["/auth"]).filter((path) => path !== this.#path());
     }
-    #flags(path) {
-        const domain = this.#options.domain;
+    #flags(path, domain) {
         return {
             httpOnly: true,
             secure: true,

package/dist/server/doors.js

@@ -22,18 +22,18 @@ export class AuthDoors {
     async login(exchange) {
         const subject = await this.#deps.flows.authenticateLocal(exchange);
         const tokens = await this.#deps.sessions.start(subject, this.#deps.cookie.deviceOf(exchange.req));
-        this.#deps.cookie.issue(exchange.res, tokens);
+        this.#deps.cookie.issue(exchange.res, tokens, exchange.req);
         return accessOf(tokens);
     }
     /** Rotates the cookie token and sets the successor (every refresh rotates, a racing one included); a cookie that cannot be used is cleared and the refusal rethrown. */
     async refresh(exchange) {
         try {
             const tokens = await this.#deps.sessions.refresh(this.#deps.cookie.read(exchange.req));
-            this.#deps.cookie.issue(exchange.res, tokens);
+            this.#deps.cookie.issue(exchange.res, tokens, exchange.req);
             return accessOf(tokens);
         }
         catch (cause) {
-            this.#deps.cookie.clear(exchange.res);
+            this.#deps.cookie.clear(exchange.res, exchange.req);
             throw cause;
         }
     }
@@ -44,7 +44,7 @@ export class AuthDoors {
     /** Ends the session of the cookie and clears it. */
     async logout(exchange) {
         await this.#deps.sessions.end(this.#deps.cookie.read(exchange.req));
-        this.#deps.cookie.clear(exchange.res);
+        this.#deps.cookie.clear(exchange.res, exchange.req);
     }
     /** Sends the browser to the Google consent screen. */
     beginGoogle(exchange) {
@@ -59,11 +59,11 @@ export class AuthDoors {
         try {
             const completion = await this.#deps.flows.completeGoogle(exchange);
             const tokens = await this.#deps.sessions.start(completion.subject, this.#deps.cookie.deviceOf(exchange.req));
-            this.#deps.cookie.issue(exchange.res, tokens);
+            this.#deps.cookie.issue(exchange.res, tokens, exchange.req);
             return { url: `${this.#deps.returnOrigin}${completion.next}`, statusCode: SEE_OTHER };
         }
         catch (cause) {
-            this.#deps.cookie.clear(exchange.res);
+            this.#deps.cookie.clear(exchange.res, exchange.req);
             this.#deps.logger?.warn(GOOGLE_SIGN_IN_FAILED_EVENT, { cause: String(cause) });
             return { url: `${this.#deps.returnOrigin}/sign-in?auth=error`, statusCode: SEE_OTHER };
         }

package/dist/server/options.d.ts

@@ -24,8 +24,13 @@ export interface GoogleOptions {
 export interface RefreshCookieOptions {
     /** The cookie name. */
     readonly name: string;
-    /** The `Domain` of the cookie; undefined keeps it host-only. */
+    /** The `Domain` of the cookie when the request host is under none of `domains`; undefined keeps it host-only. */
     readonly domain?: string | undefined;
+    /**
+     * The domains a request host may set the cookie on: a host equal to one, or ending in "." and one, gets that one as the `Domain`
+     * (the longest that fits), so one api serves sign-in on localhost (host-only) and on a tunnel origin (its parent domain).
+     */
+    readonly domains?: readonly string[] | undefined;
     /** The path the cookie is sent on (the web app's server reads it on its own pages and forwards it to the api). */
     readonly path?: string | undefined;
     /** The paths older sessions wrote the cookie under; each is cleared so a stale copy never shadows the live one. */

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.4.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",