@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/security/authentications/anonymous-session/anonymous-session.shared.contract.js

@@ -0,0 +1,198 @@
+/**
+ * Anonymous Session — Shared Contract (W7.3a)
+ *
+ * Single source of truth for the constants/keys/format/state-machine
+ * shape that any consumer of the anonymous-session feature MUST agree
+ * on, regardless of runtime (browser, Astro static page, Node service).
+ *
+ * Consumers today:
+ * - `engine/saas-frontend-lib`'s `AnonymousSessionContext.tsx` and
+ *   `local-storage.frontend.schemas.ts` (SaaS app, React, full HTTP
+ *   client integration)
+ * - `engine/saas-backend-lib`'s
+ *   `security/authentications/services/anonymous-session.backend.service.ts`
+ *   (JWT signing/verification, transposition, cleanup)
+ * - `engine/saas-website` (planned) — light, independent
+ *   `WebsiteAnonymousSessionContext` for the marketing/landing site
+ *   that intentionally does NOT depend on `saas-frontend-lib` to keep
+ *   the static-built bundle small (per `saas-website-slice.md` D16
+ *   Q17=B)
+ *
+ * Why the contract lives here (in `saas-models`) and not in
+ * `saas-frontend-lib`:
+ *
+ * The marketing-website implementation must NOT import
+ * `saas-frontend-lib` (it would pull in the full SaaS-app shell, MUI,
+ * react-router, etc. — orders of magnitude larger than a marketing
+ * site needs). At the same time, the marketing site MUST be
+ * bit-compatible with the SaaS-app implementation so a user who
+ * starts a session on `example.com` and continues on
+ * `app.example.com` keeps the same `anonymousUserId`. The only safe
+ * way to enforce that is to extract the concrete keys/headers/JWT
+ * format/state-machine vocabulary into a React-free, runtime-free
+ * module that all three consumers import from. Drift is then a
+ * compile/test failure, not a silent runtime divergence.
+ *
+ * A cross-package conformance test
+ * (`__tests__/anonymous-session.contract.conformance.test.ts`)
+ * asserts that `saas-frontend-lib`'s public surface and
+ * `saas-backend-lib`'s service implementation reference the canonical
+ * values from this file.
+ */
+import { z } from 'zod';
+import { WildoHeaderKeys } from '../../../requests/header-keys.shared.js';
+// ═══════════════════════════════════════════════════════════════
+// localStorage keys
+// ═══════════════════════════════════════════════════════════════
+/**
+ * The exact `localStorage.getItem`/`setItem` keys used to persist the
+ * anonymous session across page reloads and tabs.
+ *
+ * MUST stay in sync with
+ * `engine/saas-frontend-lib/src/core/commons/local-storage.frontend.schemas.ts`
+ * (`LOCAL_STORAGE_KEYS.ANONYMOUS_USER_ID` /
+ * `LOCAL_STORAGE_KEYS.ANONYMOUS_SESSION_TOKEN`) — that enum re-exports
+ * from this contract, so a single edit here propagates everywhere.
+ *
+ * Cross-tab sync via the `storage` event keys off these strings
+ * literally — changing them is a breaking change for any user with an
+ * existing localStorage entry.
+ */
+export const ANONYMOUS_SESSION_LOCAL_STORAGE_KEYS = {
+    ANONYMOUS_USER_ID: 'anonymousUserId',
+    ANONYMOUS_SESSION_TOKEN: 'anonymousSessionToken',
+};
+// ═══════════════════════════════════════════════════════════════
+// HTTP headers (re-exports for one-stop import ergonomics)
+// ═══════════════════════════════════════════════════════════════
+/**
+ * The canonical HTTP header names used by the anonymous-session
+ * protocol.
+ *
+ * These values are NOT redefined here — they are re-exported aliases
+ * from `WildoHeaderKeys` (the single source of truth for all
+ * platform header names, in `requests/header-keys.shared.ts`). The
+ * alias exists purely so anonymous-session consumers have a single
+ * import for everything they need.
+ *
+ * - `INIT`: client → server, on the FIRST request that creates the
+ *   AnonymousUser record. Carries the freshly-generated UUID. Server
+ *   responds with `TOKEN` (the signed JWT).
+ * - `SESSION`: client → server, on every SUBSEQUENT request once the
+ *   JWT is held. Carries the JWT in the body of the header value.
+ * - `TOKEN`: server → client, in the response that completes
+ *   initialization. Carries the freshly-signed JWT.
+ */
+export const ANONYMOUS_SESSION_HTTP_HEADERS = {
+    INIT: WildoHeaderKeys.ANONYMOUS_SESSION_INIT,
+    SESSION: WildoHeaderKeys.ANONYMOUS_SESSION,
+    TOKEN: WildoHeaderKeys.ANONYMOUS_SESSION_TOKEN,
+};
+// ═══════════════════════════════════════════════════════════════
+// JWT signing format
+// ═══════════════════════════════════════════════════════════════
+/**
+ * The cryptographic format for the anonymous-session JWT.
+ *
+ * Concrete values (algorithm, expiry) are pinned here so the backend
+ * and any client that wants to parse the JWT (for diagnostic
+ * purposes, e.g. expiry-aware UI) agree on the bit-level shape.
+ *
+ * - `algorithm`: HMAC-SHA256 — symmetric, signed with
+ *   `configService.secrets.security.session.secret`. Symmetric is
+ *   acceptable because verification only happens server-side
+ *   (clients treat the JWT as opaque); switching to RS256 would
+ *   require shipping a public key to the marketing site for nothing.
+ * - `expirySeconds`: 24 hours — long enough to cover a typical
+ *   marketing → app conversion funnel that may span multiple
+ *   sessions, short enough to bound exposure if a token leaks. The
+ *   `cleanupExpiredSessions` batch uses a 48h `sessionTtlMs` to
+ *   leave a comfortable buffer between JWT expiry and DB cleanup.
+ *
+ * The string `'24h'` is the legacy expiry encoding (jsonwebtoken
+ * accepts both `'24h'` and `expirySeconds`). The contract exposes
+ * `expirySeconds` as the canonical numeric form; consumers using the
+ * `jsonwebtoken` library can convert via
+ * `${ANONYMOUS_SESSION_JWT_FORMAT.expirySeconds}s`.
+ */
+export const ANONYMOUS_SESSION_JWT_FORMAT = {
+    algorithm: 'HS256',
+    expirySeconds: 86400,
+};
+/**
+ * Convenience: jsonwebtoken's expiresIn-friendly string form.
+ * Equivalent to `${expirySeconds}s` but pre-computed.
+ */
+export const ANONYMOUS_SESSION_JWT_EXPIRY_STRING = '24h';
+// ═══════════════════════════════════════════════════════════════
+// JWT payload schema
+// ═══════════════════════════════════════════════════════════════
+/**
+ * The exact shape of the JWT payload signed/verified for an
+ * anonymous session.
+ *
+ * Both the backend (`signSessionToken` / `verifySessionToken`) and
+ * any future client-side parser (e.g. for diagnostic UI showing
+ * "session expires in N hours") must produce/consume payloads
+ * matching this schema.
+ *
+ * - `anonymousUserId`: the client-generated session UUID — the
+ *   AnonymousUser's `uuidRef` (its relational identity), NOT the
+ *   server-minted MongoDB `_id`. The backend resolves ownership by
+ *   matching this against child `anonymousUserId` FKs (which carry the
+ *   same `uuidRef`) and the parent row's `uuidRef` during transposition.
+ *   Kept named `anonymousUserId` for wire/localStorage stability.
+ * - `iat`/`exp`: standard JWT claims (seconds since epoch). Set by
+ *   `jsonwebtoken.sign()` automatically based on
+ *   `ANONYMOUS_SESSION_JWT_FORMAT.expirySeconds`.
+ */
+export const AnonymousSessionJwtPayloadSchema = z.object({
+    anonymousUserId: z.string().min(1),
+    iat: z.number().int().nonnegative(),
+    exp: z.number().int().nonnegative(),
+});
+// ═══════════════════════════════════════════════════════════════
+// Client-side state machine vocabulary
+// ═══════════════════════════════════════════════════════════════
+/**
+ * The five client-side states an anonymous session passes through.
+ *
+ * This enum is the SHARED vocabulary between
+ * `saas-frontend-lib`'s React `AnonymousSessionContext` and
+ * `saas-website`'s lighter `WebsiteAnonymousSessionContext` — both
+ * implement reducers over the same five states so debugging tooling
+ * and conformance tests can reason about either one identically.
+ *
+ * State transitions (enforced by each implementation's reducer):
+ *
+ *   IDLE → INITIALIZING : `initAnonymousSession()` is called; UUID
+ *                          generated; first API call in flight with
+ *                          `x-anonymous-session-init` header.
+ *   INITIALIZING → ACTIVE : server responds with
+ *                          `x-anonymous-session-token`; JWT stored.
+ *   ACTIVE → ACTIVE      : token rotation (new JWT received on a
+ *                          subsequent response).
+ *   ACTIVE → TRANSPOSING : user starts to log in / register —
+ *                          subsequent anonymous-session API calls are
+ *                          blocked until backend transposition
+ *                          finishes.
+ *   TRANSPOSING → CLEARED : backend transposition complete; auth
+ *                          session takes over; localStorage entries
+ *                          removed.
+ *   * → CLEARED          : explicit logout/clear (rare on marketing
+ *                          site; common on app side).
+ *
+ * Each implementation's reducer is responsible for rejecting illegal
+ * transitions silently (return current state) — the conformance test
+ * verifies both reducers agree on the legal-transition matrix.
+ */
+export var AnonymousSessionStateMachineStatesEnum;
+(function (AnonymousSessionStateMachineStatesEnum) {
+    AnonymousSessionStateMachineStatesEnum["IDLE"] = "IDLE";
+    AnonymousSessionStateMachineStatesEnum["INITIALIZING"] = "INITIALIZING";
+    AnonymousSessionStateMachineStatesEnum["ACTIVE"] = "ACTIVE";
+    AnonymousSessionStateMachineStatesEnum["TRANSPOSING"] = "TRANSPOSING";
+    AnonymousSessionStateMachineStatesEnum["CLEARED"] = "CLEARED";
+})(AnonymousSessionStateMachineStatesEnum || (AnonymousSessionStateMachineStatesEnum = {}));
+export const AnonymousSessionStateMachineStatesSchema = z.enum(AnonymousSessionStateMachineStatesEnum);
+//# sourceMappingURL=anonymous-session.shared.contract.js.map

package/dist/esm/security/authentications/anonymous-session/anonymous-session.shared.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anonymous-session.shared.contract.js","sourceRoot":"","sources":["../../../../../../src/security/authentications/anonymous-session/anonymous-session.shared.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAGvE,kEAAkE;AAClE,oBAAoB;AACpB,kEAAkE;AAElE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG;IAClD,iBAAiB,EAAQ,iBAAiB;IAC1C,uBAAuB,EAAE,uBAAuB;CACxC,CAAC;AAMX,kEAAkE;AAClE,2DAA2D;AAC3D,kEAAkE;AAElE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,IAAI,EAAK,eAAe,CAAC,sBAAsB;IAC/C,OAAO,EAAE,eAAe,CAAC,iBAAiB;IAC1C,KAAK,EAAI,eAAe,CAAC,uBAAuB;CACxC,CAAC;AAMX,kEAAkE;AAClE,qBAAqB;AACrB,kEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,SAAS,EAAM,OAAO;IACtB,aAAa,EAAE,KAAK;CACZ,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,KAAc,CAAC;AAGlE,kEAAkE;AAClE,qBAAqB;AACrB,kEAAkE;AAElE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAIxC,CAAC,CAAC,MAAM,CAAC;IACZ,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC,GAAG,EAAc,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC/C,GAAG,EAAc,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CAChD,CAAC,CAAC;AAKH,kEAAkE;AAClE,uCAAuC;AACvC,kEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAN,IAAY,sCAMX;AAND,WAAY,sCAAsC;IAChD,uDAAqB,CAAA;IACrB,uEAA6B,CAAA;IAC7B,2DAAuB,CAAA;IACvB,qEAA4B,CAAA;IAC5B,6DAAwB,CAAA;AAC1B,CAAC,EANW,sCAAsC,KAAtC,sCAAsC,QAMjD;AAED,MAAM,CAAC,MAAM,wCAAwC,GACnD,CAAC,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC","sourcesContent":["/**\n * Anonymous Session — Shared Contract (W7.3a)\n *\n * Single source of truth for the constants/keys/format/state-machine\n * shape that any consumer of the anonymous-session feature MUST agree\n * on, regardless of runtime (browser, Astro static page, Node service).\n *\n * Consumers today:\n * - `engine/saas-frontend-lib`'s `AnonymousSessionContext.tsx` and\n *   `local-storage.frontend.schemas.ts` (SaaS app, React, full HTTP\n *   client integration)\n * - `engine/saas-backend-lib`'s\n *   `security/authentications/services/anonymous-session.backend.service.ts`\n *   (JWT signing/verification, transposition, cleanup)\n * - `engine/saas-website` (planned) — light, independent\n *   `WebsiteAnonymousSessionContext` for the marketing/landing site\n *   that intentionally does NOT depend on `saas-frontend-lib` to keep\n *   the static-built bundle small (per `saas-website-slice.md` D16\n *   Q17=B)\n *\n * Why the contract lives here (in `saas-models`) and not in\n * `saas-frontend-lib`:\n *\n * The marketing-website implementation must NOT import\n * `saas-frontend-lib` (it would pull in the full SaaS-app shell, MUI,\n * react-router, etc. — orders of magnitude larger than a marketing\n * site needs). At the same time, the marketing site MUST be\n * bit-compatible with the SaaS-app implementation so a user who\n * starts a session on `example.com` and continues on\n * `app.example.com` keeps the same `anonymousUserId`. The only safe\n * way to enforce that is to extract the concrete keys/headers/JWT\n * format/state-machine vocabulary into a React-free, runtime-free\n * module that all three consumers import from. Drift is then a\n * compile/test failure, not a silent runtime divergence.\n *\n * A cross-package conformance test\n * (`__tests__/anonymous-session.contract.conformance.test.ts`)\n * asserts that `saas-frontend-lib`'s public surface and\n * `saas-backend-lib`'s service implementation reference the canonical\n * values from this file.\n */\n\nimport { z } from 'zod';\nimport { WildoHeaderKeys } from '../../../requests/header-keys.shared';\n\n\n// ═══════════════════════════════════════════════════════════════\n// localStorage keys\n// ═══════════════════════════════════════════════════════════════\n\n/**\n * The exact `localStorage.getItem`/`setItem` keys used to persist the\n * anonymous session across page reloads and tabs.\n *\n * MUST stay in sync with\n * `engine/saas-frontend-lib/src/core/commons/local-storage.frontend.schemas.ts`\n * (`LOCAL_STORAGE_KEYS.ANONYMOUS_USER_ID` /\n * `LOCAL_STORAGE_KEYS.ANONYMOUS_SESSION_TOKEN`) — that enum re-exports\n * from this contract, so a single edit here propagates everywhere.\n *\n * Cross-tab sync via the `storage` event keys off these strings\n * literally — changing them is a breaking change for any user with an\n * existing localStorage entry.\n */\nexport const ANONYMOUS_SESSION_LOCAL_STORAGE_KEYS = {\n  ANONYMOUS_USER_ID:       'anonymousUserId',\n  ANONYMOUS_SESSION_TOKEN: 'anonymousSessionToken',\n} as const;\n\nexport type AnonymousSessionLocalStorageKey =\n  typeof ANONYMOUS_SESSION_LOCAL_STORAGE_KEYS[keyof typeof ANONYMOUS_SESSION_LOCAL_STORAGE_KEYS];\n\n\n// ═══════════════════════════════════════════════════════════════\n// HTTP headers (re-exports for one-stop import ergonomics)\n// ═══════════════════════════════════════════════════════════════\n\n/**\n * The canonical HTTP header names used by the anonymous-session\n * protocol.\n *\n * These values are NOT redefined here — they are re-exported aliases\n * from `WildoHeaderKeys` (the single source of truth for all\n * platform header names, in `requests/header-keys.shared.ts`). The\n * alias exists purely so anonymous-session consumers have a single\n * import for everything they need.\n *\n * - `INIT`: client → server, on the FIRST request that creates the\n *   AnonymousUser record. Carries the freshly-generated UUID. Server\n *   responds with `TOKEN` (the signed JWT).\n * - `SESSION`: client → server, on every SUBSEQUENT request once the\n *   JWT is held. Carries the JWT in the body of the header value.\n * - `TOKEN`: server → client, in the response that completes\n *   initialization. Carries the freshly-signed JWT.\n */\nexport const ANONYMOUS_SESSION_HTTP_HEADERS = {\n  INIT:    WildoHeaderKeys.ANONYMOUS_SESSION_INIT,\n  SESSION: WildoHeaderKeys.ANONYMOUS_SESSION,\n  TOKEN:   WildoHeaderKeys.ANONYMOUS_SESSION_TOKEN,\n} as const;\n\nexport type AnonymousSessionHttpHeader =\n  typeof ANONYMOUS_SESSION_HTTP_HEADERS[keyof typeof ANONYMOUS_SESSION_HTTP_HEADERS];\n\n\n// ═══════════════════════════════════════════════════════════════\n// JWT signing format\n// ═══════════════════════════════════════════════════════════════\n\n/**\n * The cryptographic format for the anonymous-session JWT.\n *\n * Concrete values (algorithm, expiry) are pinned here so the backend\n * and any client that wants to parse the JWT (for diagnostic\n * purposes, e.g. expiry-aware UI) agree on the bit-level shape.\n *\n * - `algorithm`: HMAC-SHA256 — symmetric, signed with\n *   `configService.secrets.security.session.secret`. Symmetric is\n *   acceptable because verification only happens server-side\n *   (clients treat the JWT as opaque); switching to RS256 would\n *   require shipping a public key to the marketing site for nothing.\n * - `expirySeconds`: 24 hours — long enough to cover a typical\n *   marketing → app conversion funnel that may span multiple\n *   sessions, short enough to bound exposure if a token leaks. The\n *   `cleanupExpiredSessions` batch uses a 48h `sessionTtlMs` to\n *   leave a comfortable buffer between JWT expiry and DB cleanup.\n *\n * The string `'24h'` is the legacy expiry encoding (jsonwebtoken\n * accepts both `'24h'` and `expirySeconds`). The contract exposes\n * `expirySeconds` as the canonical numeric form; consumers using the\n * `jsonwebtoken` library can convert via\n * `${ANONYMOUS_SESSION_JWT_FORMAT.expirySeconds}s`.\n */\nexport const ANONYMOUS_SESSION_JWT_FORMAT = {\n  algorithm:     'HS256',\n  expirySeconds: 86400,\n} as const;\n\n/**\n * Convenience: jsonwebtoken's expiresIn-friendly string form.\n * Equivalent to `${expirySeconds}s` but pre-computed.\n */\nexport const ANONYMOUS_SESSION_JWT_EXPIRY_STRING = '24h' as const;\n\n\n// ═══════════════════════════════════════════════════════════════\n// JWT payload schema\n// ═══════════════════════════════════════════════════════════════\n\n/**\n * The exact shape of the JWT payload signed/verified for an\n * anonymous session.\n *\n * Both the backend (`signSessionToken` / `verifySessionToken`) and\n * any future client-side parser (e.g. for diagnostic UI showing\n * \"session expires in N hours\") must produce/consume payloads\n * matching this schema.\n *\n * - `anonymousUserId`: the client-generated session UUID — the\n *   AnonymousUser's `uuidRef` (its relational identity), NOT the\n *   server-minted MongoDB `_id`. The backend resolves ownership by\n *   matching this against child `anonymousUserId` FKs (which carry the\n *   same `uuidRef`) and the parent row's `uuidRef` during transposition.\n *   Kept named `anonymousUserId` for wire/localStorage stability.\n * - `iat`/`exp`: standard JWT claims (seconds since epoch). Set by\n *   `jsonwebtoken.sign()` automatically based on\n *   `ANONYMOUS_SESSION_JWT_FORMAT.expirySeconds`.\n */\nexport const AnonymousSessionJwtPayloadSchema: z.ZodObject<{\n  anonymousUserId: z.ZodString;\n  iat:             z.ZodNumber;\n  exp:             z.ZodNumber;\n}> = z.object({\n  anonymousUserId: z.string().min(1),\n  iat:             z.number().int().nonnegative(),\n  exp:             z.number().int().nonnegative(),\n});\n\nexport type AnonymousSessionJwtPayload = z.infer<typeof AnonymousSessionJwtPayloadSchema>;\n\n\n// ═══════════════════════════════════════════════════════════════\n// Client-side state machine vocabulary\n// ═══════════════════════════════════════════════════════════════\n\n/**\n * The five client-side states an anonymous session passes through.\n *\n * This enum is the SHARED vocabulary between\n * `saas-frontend-lib`'s React `AnonymousSessionContext` and\n * `saas-website`'s lighter `WebsiteAnonymousSessionContext` — both\n * implement reducers over the same five states so debugging tooling\n * and conformance tests can reason about either one identically.\n *\n * State transitions (enforced by each implementation's reducer):\n *\n *   IDLE → INITIALIZING : `initAnonymousSession()` is called; UUID\n *                          generated; first API call in flight with\n *                          `x-anonymous-session-init` header.\n *   INITIALIZING → ACTIVE : server responds with\n *                          `x-anonymous-session-token`; JWT stored.\n *   ACTIVE → ACTIVE      : token rotation (new JWT received on a\n *                          subsequent response).\n *   ACTIVE → TRANSPOSING : user starts to log in / register —\n *                          subsequent anonymous-session API calls are\n *                          blocked until backend transposition\n *                          finishes.\n *   TRANSPOSING → CLEARED : backend transposition complete; auth\n *                          session takes over; localStorage entries\n *                          removed.\n *   * → CLEARED          : explicit logout/clear (rare on marketing\n *                          site; common on app side).\n *\n * Each implementation's reducer is responsible for rejecting illegal\n * transitions silently (return current state) — the conformance test\n * verifies both reducers agree on the legal-transition matrix.\n */\nexport enum AnonymousSessionStateMachineStatesEnum {\n  IDLE         = 'IDLE',\n  INITIALIZING = 'INITIALIZING',\n  ACTIVE       = 'ACTIVE',\n  TRANSPOSING  = 'TRANSPOSING',\n  CLEARED      = 'CLEARED',\n}\n\nexport const AnonymousSessionStateMachineStatesSchema: z.ZodEnum<typeof AnonymousSessionStateMachineStatesEnum> =\n  z.enum(AnonymousSessionStateMachineStatesEnum);\n\nexport type AnonymousSessionStateMachineState = z.infer<typeof AnonymousSessionStateMachineStatesSchema>;\n"]}