@starci/auth 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.5.0 - 2026-11-08
+
+- Changed: `AuthError` extends `DomainError<AuthErrorCode>` of `@starci/common` (new dependency); its name, codes, constructor, `kind`, `context` and `cause` are unchanged, and it gains `params` (always empty).
+- Changed: the package's own non-array object guard is `isPlainRecord` of `@starci/common`.
+- Changed: requires `@starci/common` 1.0.1 (exact), the one copy an app installs, so `DomainError` stays one class (this version had not reached npm).
+
+## 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.

package/README.md

@@ -12,6 +12,8 @@ The sign-in of a lite StarCi app: one package, four entries.
 
 An app reaches the package only through `integrations/passport` (back end) and `modules/auth/client.ts` (front end); the lint refuses `passport*`, `jose`, `bcryptjs` and `@nestjs/jwt` in an app.
 
+The server throws one error class, `AuthError`: a `DomainError` of `@starci/common` whose `code` is a wire code, with the `kind` it travels as and a non-secret `context`.
+
 ## Back end
 
 ```ts

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/errors.d.ts

@@ -1,7 +1,7 @@
+import { DomainError } from "@starci/common";
 import type { AuthErrorCode, AuthErrorKind } from "../contracts/index.js";
 /** The one error class of sign-in: a wire code, the kind it travels as and optional context for the log. */
-export declare class AuthError extends Error {
-    readonly code: AuthErrorCode;
+export declare class AuthError extends DomainError<AuthErrorCode> {
     readonly kind: AuthErrorKind;
     readonly context: Readonly<Record<string, unknown>>;
     constructor(code: AuthErrorCode, options?: {

package/dist/server/errors.js

@@ -1,13 +1,11 @@
+import { DomainError } from "@starci/common";
 import { AUTH_ERROR_KINDS } from "../contracts/index.js";
 /** The one error class of sign-in: a wire code, the kind it travels as and optional context for the log. */
-export class AuthError extends Error {
-    code;
+export class AuthError extends DomainError {
     kind;
     context;
     constructor(code, options = {}) {
-        super(code, options.cause === undefined ? undefined : { cause: options.cause });
-        this.name = "AuthError";
-        this.code = code;
+        super(options.cause === undefined ? { code } : { code, cause: options.cause });
         this.kind = AUTH_ERROR_KINDS[code];
         this.context = options.context ?? {};
     }

package/dist/server/flows.js

@@ -1,8 +1,9 @@
 import passport from "passport";
 import { AUTH_ERROR_CODES } from "../contracts/index.js";
 import { AuthError } from "./errors.js";
-import { isRecord, sameSitePath } from "./primitives.js";
-const isSubject = (value) => isRecord(value) && typeof value.userId === "string" && typeof value.email === "string";
+import { isPlainRecord } from "@starci/common";
+import { sameSitePath } from "./primitives.js";
+const isSubject = (value) => isPlainRecord(value) && typeof value.userId === "string" && typeof value.email === "string";
 const isHandler = (value) => typeof value === "function";
 /** The middleware passport built; passport types it as any, so it is checked once here. */
 const handlerOf = (built) => {
@@ -57,7 +58,7 @@ export class AuthFlows {
                     reject(new AuthError(AUTH_ERROR_CODES.GoogleStateInvalid));
                     return;
                 }
-                const state = isRecord(info) && isRecord(info.state) ? info.state.next : undefined;
+                const state = isPlainRecord(info) && isPlainRecord(info.state) ? info.state.next : undefined;
                 resolve({ subject: user, next: sameSitePath(state, "/") });
             };
             handlerOf(passport.authenticate("google", { session: false }, settled))(exchange.req, exchange.res, reject);

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/primitives.d.ts

@@ -14,8 +14,6 @@ export interface SignedState {
     readonly e: number;
     readonly p?: string;
 }
-/** A record: a non-null object that is not an array. */
-export declare const isRecord: (value: unknown) => value is Readonly<Record<string, unknown>>;
 /** A same-site path (one leading slash, no line break), else the fallback path. */
 export declare const sameSitePath: (value: unknown, fallback: string) => string;
 /** Signs a state: base64url(JSON).base64url(HMAC-SHA256). */

package/dist/server/primitives.js

@@ -1,15 +1,14 @@
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { isPlainRecord } from "@starci/common";
 import { PASSWORD_BOUNDS } from "../contracts/index.js";
 /** The text of a secret input. */
 export const revealed = (secret) => (typeof secret === "string" ? secret : secret.reveal());
-/** A record: a non-null object that is not an array. */
-export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const SAME_SITE_PATH = /^\/(?![/\\])/u;
 const LINE_BREAK = /[\r\n]/u;
 /** A same-site path (one leading slash, no line break), else the fallback path. */
 export const sameSitePath = (value, fallback) => typeof value === "string" && SAME_SITE_PATH.test(value) && !LINE_BREAK.test(value) ? value : fallback;
 const encode = (buffer) => buffer.toString("base64url");
-const isSignedState = (value) => isRecord(value) &&
+const isSignedState = (value) => isPlainRecord(value) &&
     typeof value.w === "string" &&
     typeof value.u === "string" &&
     typeof value.r === "string" &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/auth",
-  "version": "0.3.0",
+  "version": "0.5.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",
@@ -74,6 +74,7 @@
     "prepublishOnly": "npm test && npm run build"
   },
   "dependencies": {
+    "@starci/common": "1.0.1",
     "@nestjs/passport": "11.0.5",
     "bcryptjs": "3.0.3",
     "jose": "6.2.12",
@@ -106,6 +107,7 @@
     "@nestjs/common": "11.2.5",
     "@nestjs/core": "11.2.5",
     "@nestjs/testing": "11.2.5",
+    "@starci/common": "file:../common",
     "@types/express": "4.17.25",
     "@types/node": "22.20.4",
     "@types/passport-google-oauth20": "2.0.17",
@@ -124,5 +126,7 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
-  }
+  },
+  "gitHead": "f464f759079854716389ba92feb7e4a1512a0ee3",
+  "starciSource": "d302420a970828a385f4e2325e7ed2b3e34b10e48f9d4d552326ff9fa292d945"
 }