nucleus-core-ts 0.9.967 → 0.9.968

package/dist/src/Client/ApiCaller/types.d.ts

@@ -1027,6 +1027,49 @@ export type AdminHardDeleteUserResponse = {
         cleanedRelations: string[];
     };
 };
+/**
+ * Account-state administration. These three exist because the generic entity
+ * API refuses `is_locked`, `locked_until`, `failed_login_attempts`,
+ * `verified_at` and `email_verified` — a write grant on `users` must not be a
+ * way to self-verify or defeat lockout. A UI that PATCHes `users` with those
+ * fields gets `200 success: true` and changes nothing, so it must call these
+ * instead.
+ */
+export type AdminLockUserPayload = {
+    userId: string;
+    /** ISO timestamp for a temporary lock; omit to lock indefinitely. */
+    until?: string;
+};
+export type AdminLockUserResponse = {
+    success: boolean;
+    message?: string;
+    data?: {
+        isLocked: boolean;
+        lockedUntil: string | null;
+    };
+};
+export type AdminUnlockUserPayload = {
+    userId: string;
+};
+export type AdminUnlockUserResponse = {
+    success: boolean;
+    message?: string;
+    data?: {
+        wasLocked: boolean;
+        clearedFailedAttempts: number;
+    };
+};
+export type AdminMarkEmailVerifiedPayload = {
+    userId: string;
+};
+export type AdminMarkEmailVerifiedResponse = {
+    success: boolean;
+    message?: string;
+    data?: {
+        verifiedAt: string;
+        alreadyVerified: boolean;
+    };
+};
 export type AuthFeatureKey = keyof typeof AUTH_ENDPOINT_CONFIGS;
 type AuthEndpointMap = {
     login: {
@@ -1487,6 +1530,30 @@ export declare const AUTH_ENDPOINTS: {
         _success: AdminHardDeleteUserResponse;
         _error: BaseErrorResponse;
     };
+    ADMIN_LOCK_USER: {
+        method: "POST";
+        path: string;
+        isPublic: false;
+        _payload: AdminLockUserPayload;
+        _success: AdminLockUserResponse;
+        _error: BaseErrorResponse;
+    };
+    ADMIN_UNLOCK_USER: {
+        method: "POST";
+        path: string;
+        isPublic: false;
+        _payload: AdminUnlockUserPayload;
+        _success: AdminUnlockUserResponse;
+        _error: BaseErrorResponse;
+    };
+    ADMIN_MARK_EMAIL_VERIFIED: {
+        method: "POST";
+        path: string;
+        isPublic: false;
+        _payload: AdminMarkEmailVerifiedPayload;
+        _success: AdminMarkEmailVerifiedResponse;
+        _error: BaseErrorResponse;
+    };
     API_KEYS_CREATE: {
         method: "POST";
         path: string;

package/dist/src/Client/Proxy/httpProxy.js

@@ -134,11 +134,11 @@ function appendSetCookieHeaders(responseHeaders, setCookieHeaders) {
         responseHeaders.append('Set-Cookie', cookie);
     }
 }
-/**
- * Preserve individual Set-Cookie headers when copying via new Headers().
- * new Headers(response.headers) may combine multiple Set-Cookie headers
- * into a single comma-separated value — browsers cannot parse this for
- * Set-Cookie (RFC 6265). This function re-adds them individually.
+/**
+ * Preserve individual Set-Cookie headers when copying via new Headers().
+ * new Headers(response.headers) may combine multiple Set-Cookie headers
+ * into a single comma-separated value — browsers cannot parse this for
+ * Set-Cookie (RFC 6265). This function re-adds them individually.
  */ function preserveSetCookieHeaders(target, source) {
     const setCookies = typeof source.getSetCookie === 'function' ? source.getSetCookie() : [];
     if (setCookies.length > 1) {
@@ -148,10 +148,10 @@ function appendSetCookieHeaders(responseHeaders, setCookieHeaders) {
         }
     }
 }
-/**
- * Resolve the user id to inject as x-user-id from a bearer token, or null if it can't be
- * TRUSTED. Fail-closed: returns null unless BOTH a secret and a token are present AND the token
- * passes HS256 signature + expiry verification. Never trusts a bare/forged/unsigned token.
+/**
+ * Resolve the user id to inject as x-user-id from a bearer token, or null if it can't be
+ * TRUSTED. Fail-closed: returns null unless BOTH a secret and a token are present AND the token
+ * passes HS256 signature + expiry verification. Never trusts a bare/forged/unsigned token.
  */ export function resolveInjectedUserId(token, secret) {
     if (!secret || !token) return null;
     const payload = verifyJwtHS256(token, secret);
@@ -178,9 +178,9 @@ export function createHttpProxyHandler(config) {
             }
         }
     }
-    /**
-   * Claim-gate a request for a target. Returns a 403 Response to block (enforce
-   * mode), or null to allow (also null in audit mode, where a would-block is logged).
+    /**
+   * Claim-gate a request for a target. Returns a 403 Response to block (enforce
+   * mode), or null to allow (also null in audit mode, where a would-block is logged).
    */ async function checkAuthorize(req, target, path) {
         const az = target.authorize;
         if (!az) return null;
@@ -368,30 +368,30 @@ export function createHttpProxyHandler(config) {
     function injectToken(headers, token, headerName) {
         headers.set(headerName, `Bearer ${token}`);
     }
-    /**
-   * Forward one request upstream, bounded by BOTH clocks that can end it.
-   *
-   * The timeout below only bounds time-to-first-headers: it is cleared the
-   * moment headers arrive, because a streamed body (SSE, a long download, a
-   * model's token stream) legitimately takes as long as it takes. That is
-   * correct — but on its own it left a streamed request with NO way to end.
-   *
-   * So when the person closed the tab, the browser's connection went away and
-   * ours did not. The upstream request stayed open, holding one of the
-   * runtime's outgoing connection slots, forever.
-   *
-   * That is not a slow leak. Measured on Bun 1.3.14: 256 clients that connect
-   * and hang up leave 256 upstream requests open (0 cancelled), and the process
-   * can then make no outgoing request at all — every later fetch times out.
-   * A single tab reconnecting an EventSource 256 times does it alone.
-   *
-   * Cancelling the body we hand back (`body.cancel()`) does NOT release the
-   * slot; only aborting the upstream fetch does. Measured both ways.
-   *
-   * Hence `clientSignal`: the client's hangup is wired to the same controller
-   * the timeout uses, so whichever ends first ends the upstream request. The
-   * listener is left attached deliberately — it belongs to this one request and
-   * is collected with it, and aborting an already-finished fetch is a no-op.
+    /**
+   * Forward one request upstream, bounded by BOTH clocks that can end it.
+   *
+   * The timeout below only bounds time-to-first-headers: it is cleared the
+   * moment headers arrive, because a streamed body (SSE, a long download, a
+   * model's token stream) legitimately takes as long as it takes. That is
+   * correct — but on its own it left a streamed request with NO way to end.
+   *
+   * So when the person closed the tab, the browser's connection went away and
+   * ours did not. The upstream request stayed open, holding one of the
+   * runtime's outgoing connection slots, forever.
+   *
+   * That is not a slow leak. Measured on Bun 1.3.14: 256 clients that connect
+   * and hang up leave 256 upstream requests open (0 cancelled), and the process
+   * can then make no outgoing request at all — every later fetch times out.
+   * A single tab reconnecting an EventSource 256 times does it alone.
+   *
+   * Cancelling the body we hand back (`body.cancel()`) does NOT release the
+   * slot; only aborting the upstream fetch does. Measured both ways.
+   *
+   * Hence `clientSignal`: the client's hangup is wired to the same controller
+   * the timeout uses, so whichever ends first ends the upstream request. The
+   * listener is left attached deliberately — it belongs to this one request and
+   * is collected with it, and aborting an already-finished fetch is a no-op.
    */ async function forwardRequest(finalUrl, method, headers, body, timeout, followRedirects, clientSignal) {
         const controller = new AbortController();
         const timeoutId = setTimeout(()=>controller.abort(), timeout);
@@ -407,13 +407,13 @@ export function createHttpProxyHandler(config) {
                     clientGone = true;
                     clearTimeout(timeoutId);
                     controller.abort();
-                    /*
-             * Logged HERE, not in the catch below, because the common case
-             * never reaches the catch: once headers have arrived this function
-             * has already returned, and the hangup happens while the body is
-             * still streaming. That is exactly the case that used to leak, so
-             * it is exactly the case that has to be visible — a cancellation
-             * nobody can see is how this went unnoticed for months.
+                    /*
+             * Logged HERE, not in the catch below, because the common case
+             * never reaches the catch: once headers have arrived this function
+             * has already returned, and the hangup happens while the body is
+             * still streaming. That is exactly the case that used to leak, so
+             * it is exactly the case that has to be visible — a cancellation
+             * nobody can see is how this went unnoticed for months.
              */ logger.info(`Client disconnected, upstream cancelled: ${finalUrl}`);
                 }, {
                     once: true
@@ -519,30 +519,30 @@ export function createHttpProxyHandler(config) {
                 logger.warn(`[Auth:proxy] NO TOKEN available for ${path} — request will likely fail with 401`);
             }
             const baseTimeout = target.timeout ?? 30000;
-            /*
-       * A file needs minutes, not thirty seconds.
-       *
-       * The fixed timeout aborted a 200 MB video long before the last byte, and
-       * the browser had no way to tell that from a slow line — the bar simply
-       * stopped. The allowance now grows with the declared size.
+            /*
+       * A file needs minutes, not thirty seconds.
+       *
+       * The fixed timeout aborted a 200 MB video long before the last byte, and
+       * the browser had no way to tell that from a slow line — the bar simply
+       * stopped. The allowance now grows with the declared size.
        */ const timeout = timeoutForBody(req.headers, baseTimeout);
             const followRedirects = target.followRedirects !== false;
             // Buffer body for potential retry (only if 401 retry is enabled)
             let bodyForRetry = null;
             let bodyToSend = req.body;
-            /*
-       * Only a body small enough to hold.
-       *
-       * Buffering exists so a 401 can be answered by refreshing the token and
-       * sending the same request again — worth it for a form post, fatal for a
-       * file. An 800 MB video was read into an ArrayBuffer inside a container
-       * limited to 256 MiB: the upload appeared to run, because the browser
-       * really was sending bytes, and then died with nothing to show for it.
-       *
-       * A large body streams straight through and gives up the retry. That is
-       * the right way round: an upload that is refused can be started again by
-       * the person who chose the file; an upload that never completes cannot be
-       * rescued by anybody.
+            /*
+       * Only a body small enough to hold.
+       *
+       * Buffering exists so a 401 can be answered by refreshing the token and
+       * sending the same request again — worth it for a form post, fatal for a
+       * file. An 800 MB video was read into an ArrayBuffer inside a container
+       * limited to 256 MiB: the upload appeared to run, because the browser
+       * really was sending bytes, and then died with nothing to show for it.
+       *
+       * A large body streams straight through and gives up the retry. That is
+       * the right way round: an upload that is refused can be started again by
+       * the person who chose the file; an upload that never completes cannot be
+       * rescued by anybody.
        */ const bufferable = canBufferForRetry(req.headers);
             if (refreshEnabled && (refreshConfig.retryOn401 ?? true) && req.body && bufferable) {
                 try {
@@ -616,14 +616,14 @@ export function createHttpProxyHandler(config) {
             } catch (error) {
                 const duration = performance.now() - startTime;
                 const err = error instanceof Error ? error : new Error(String(error));
-                /*
-         * The person closed the tab. Nothing failed, and there is nobody left
-         * to send a status to — so this is not an error, and calling it one
-         * sends whoever reads the log hunting a timeout that never happened.
-         *
-         * Reported with the elapsed time, because on a streaming path "the
-         * client left after 4 minutes" is genuinely useful and "Gateway
-         * Timeout" is genuinely misleading.
+                /*
+         * The person closed the tab. Nothing failed, and there is nobody left
+         * to send a status to — so this is not an error, and calling it one
+         * sends whoever reads the log hunting a timeout that never happened.
+         *
+         * Reported with the elapsed time, because on a streaming path "the
+         * client left after 4 minutes" is genuinely useful and "Gateway
+         * Timeout" is genuinely misleading.
          */ if (err.name === 'ClientGoneError') {
                     logger.info(`Client disconnected after ${duration.toFixed(0)}ms, upstream cancelled: ${path}`);
                     return new Response(null, {

package/dist/src/Client/Proxy/wsProxy.js

@@ -1,9 +1,9 @@
 import { deduplicatedRefresh } from './httpProxy';
 import { addQueryParam, createProxyLogger, httpToWs, matchPath, parseCookies, rewritePath } from './utils';
-/**
- * True when an access token is absent or within `skewMs` of expiring. Decodes the JWT
- * exp WITHOUT verifying (verification happens at the backend) — this only decides whether
- * to pre-emptively refresh before the WS handshake.
+/**
+ * True when an access token is absent or within `skewMs` of expiring. Decodes the JWT
+ * exp WITHOUT verifying (verification happens at the backend) — this only decides whether
+ * to pre-emptively refresh before the WS handshake.
  */ function accessTokenExpiringSoon(token, skewMs = 60000) {
     if (!token) return true;
     try {
@@ -16,20 +16,20 @@ import { addQueryParam, createProxyLogger, httpToWs, matchPath, parseCookies, re
         return true;
     }
 }
-/**
- * Keeps the proxy→backend socket alive with a PROTOCOL ping, not a data frame.
- *
- * This used to send `''`. An empty text frame is still application data, so it
- * arrived at the backend's `message` handler, where `JSON.parse('')` throws —
- * and nucleus' own PubSub route logged "Failed to parse client message" once per
- * interval per connected client. On a busy IDP that is the entire debug log, and
- * it names the proxy's own heartbeat as a misbehaving client.
- *
- * `ping()` is a control frame: it never reaches `message`, the peer answers with
- * pong automatically, and it resets the idle timer the same way. Bun's WebSocket
- * client implements it; the JSON heartbeat is the fallback for a runtime that
- * does not, because `{"type":"ping"}` is a frame the PubSub route understands and
- * replies to, rather than one it can only fail to parse.
+/**
+ * Keeps the proxy→backend socket alive with a PROTOCOL ping, not a data frame.
+ *
+ * This used to send `''`. An empty text frame is still application data, so it
+ * arrived at the backend's `message` handler, where `JSON.parse('')` throws —
+ * and nucleus' own PubSub route logged "Failed to parse client message" once per
+ * interval per connected client. On a busy IDP that is the entire debug log, and
+ * it names the proxy's own heartbeat as a misbehaving client.
+ *
+ * `ping()` is a control frame: it never reaches `message`, the peer answers with
+ * pong automatically, and it resets the idle timer the same way. Bun's WebSocket
+ * client implements it; the JSON heartbeat is the fallback for a runtime that
+ * does not, because `{"type":"ping"}` is a frame the PubSub route understands and
+ * replies to, rather than one it can only fail to parse.
  */ function pingBackend(backendWs) {
     const withPing = backendWs;
     if (typeof withPing.ping === 'function') {
@@ -51,14 +51,14 @@ export function createWsProxyHandler(config) {
         }
         return null;
     }
-    /**
-   * The backend URL, plus whether this handshake carries a credential at all.
-   *
-   * The second half is the point. This function already KNEW when it had no
-   * token — it logged "No token found" and handed back a URL anyway, and the
-   * caller upgraded the socket regardless. That silence is what turns one
-   * logged-out browser tab into a permanent reconnect storm; see the refusal in
-   * `upgrade()` for the measurements.
+    /**
+   * The backend URL, plus whether this handshake carries a credential at all.
+   *
+   * The second half is the point. This function already KNEW when it had no
+   * token — it logged "No token found" and handed back a URL anyway, and the
+   * caller upgraded the socket regardless. That silence is what turns one
+   * logged-out browser tab into a permanent reconnect storm; see the refusal in
+   * `upgrade()` for the measurements.
    */ async function buildBackendUrl(path, target, cookies, query) {
         let baseUrl = target.url.replace(/\/$/, '');
         if (baseUrl.startsWith('http')) {

package/dist/src/Client/PubSub/usePubSub.js

@@ -14,13 +14,13 @@ function buildWsUrl(config) {
     const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
     return `${protocol}//${window.location.host}${path}${query}`;
 }
-/**
- * One WebSocket per distinct URL, shared across every `usePubSub` caller via
- * ref-counting. Previously each hook instance opened its own socket, so two
- * components subscribing for the same user (e.g. the header bell and the chat
- * panel) created competing connections — the server de-dupes by user, dropping
- * one and breaking realtime delivery (and the message chime). Sharing a single
- * socket eliminates that and the duplicate events it produced.
+/**
+ * One WebSocket per distinct URL, shared across every `usePubSub` caller via
+ * ref-counting. Previously each hook instance opened its own socket, so two
+ * components subscribing for the same user (e.g. the header bell and the chat
+ * panel) created competing connections — the server de-dupes by user, dropping
+ * one and breaking realtime delivery (and the message chime). Sharing a single
+ * socket eliminates that and the duplicate events it produced.
  */ const connections = new Map();
 let eventIdCounter = 0;
 function log(conn, ...args) {
@@ -58,11 +58,11 @@ function startHeartbeat(conn) {
         }
     }, conn.options.heartbeatInterval);
 }
-/**
- * How many refused handshakes in a row before the client stops trying.
- *
- * Small on purpose: a refused handshake is a session problem, and the second
- * attempt tells you the first was not a fluke. Anything beyond that is a storm.
+/**
+ * How many refused handshakes in a row before the client stops trying.
+ *
+ * Small on purpose: a refused handshake is a session problem, and the second
+ * attempt tells you the first was not a fluke. Anything beyond that is a storm.
  */ const HANDSHAKE_FAILURE_LIMIT = 3;
 function scheduleReconnect(conn) {
     if (!conn.options.autoReconnect) return;
@@ -258,13 +258,13 @@ export function usePubSub(config) {
     return {
         isConnected: store.connection.status === 'connected',
         isConnecting: store.connection.status === 'connecting' || store.connection.status === 'reconnecting',
-        /**
-     * The session is over and realtime will not return on its own.
-     *
-     * Exposed as its own flag so a screen can say so. Without it the page keeps
-     * its live appearance and quietly delivers nothing — which is worse than
-     * the reconnect storm this replaced, because at least the storm was visible
-     * to somebody.
+        /**
+     * The session is over and realtime will not return on its own.
+     *
+     * Exposed as its own flag so a screen can say so. Without it the page keeps
+     * its live appearance and quietly delivers nothing — which is worse than
+     * the reconnect storm this replaced, because at least the storm was visible
+     * to somebody.
      */ sessionExpired: store.connection.status === 'unauthorized',
         clientId: store.connection.clientId,
         subscribedTopics: store.connection.subscribedTopics,

package/dist/src/ElysiaPlugin/routes/auth/admin/lockoutState.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The columns that decide whether an account is allowed to attempt a login.
+ *
+ * They are written together, always, because clearing a subset is how an
+ * account ends up in the state that reads as fine and is not. The login route
+ * consults them in two independent places:
+ *
+ * - `isLocked` / `lockedUntil` refuse the attempt outright, and
+ * - `failedLoginAttempts` decides whether the captcha gate applies — a gate that
+ *   runs BEFORE the password is checked and before the counter can move.
+ *
+ * So an account released by unsetting `isLocked` alone still cannot log in, and
+ * nothing in the database says why: `is_locked` reads false, `failed_login_
+ * attempts` reads 1, and the account is stuck on a gate that only a successful
+ * login could clear. Seven farplas accounts sat exactly there.
+ */
+export type LockoutState = {
+    failedLoginAttempts: number;
+    isLocked: boolean;
+    lockedUntil: Date | null;
+};
+export declare function clearedLockoutState(): LockoutState;
+/**
+ * Whether the login route will let this account reach the password check.
+ *
+ * `captchaThreshold` is `login.captcha.requireAfterFailures`; pass `undefined`
+ * when the captcha is disabled for login. An `undefined` threshold with the
+ * captcha ENABLED means "always", which is the login route's own reading of a
+ * missing value — a detail worth keeping in one place, since a config that
+ * misspells the key gets every account gated rather than none.
+ */
+export declare function isHeldOutOfLogin(user: {
+    failedLoginAttempts?: number | null;
+    isLocked?: boolean | null;
+    lockedUntil?: Date | null;
+}, captchaThreshold: number | undefined, captchaEnabled: boolean, now?: Date): boolean;

package/dist/src/ElysiaPlugin/routes/auth/admin/passwordAdmin.d.ts

@@ -12,8 +12,15 @@ import type { AuthRouteConfig } from '../types';
  * The two endpoints are siblings on purpose. The sweep leaves everybody holding
  * a password nobody knows, which is the point; the single-account one is how an
  * administrator then gets a person who has no email address back to work.
+ *
+ * Both stay opt-in: a bulk rotation is irreversible, and an installation that
+ * never shared an opening password has no use for either. Releasing an account
+ * from lockout is deliberately NOT here — it is neither irreversible nor
+ * optional, so it lives in `userState.ts` and mounts unconditionally.
  */
-export declare function createPasswordAdminRoutes(config: AuthRouteConfig): Elysia<"", {
+export declare function createPasswordAdminRoutes(config: AuthRouteConfig, options?: {
+    passwordTools?: boolean;
+}): Elysia<"", {
     decorator: {};
     store: {};
     derive: {};

package/dist/src/ElysiaPlugin/routes/auth/admin/requireGodmin.d.ts

@@ -0,0 +1,17 @@
+import type { AuthRouteConfig } from '../types';
+export type GodminGate = {
+    ok: true;
+    callerId: string;
+} | {
+    ok: false;
+    status: 401 | 403 | 500;
+    message: string;
+};
+/**
+ * The gate every account-administration route stands behind.
+ *
+ * It was a closure inside the password module until a second module needed the
+ * same check; a copy would have been a second place to forget the deactivation
+ * kill-switch below.
+ */
+export declare function createRequireGodmin(config: AuthRouteConfig): (request: Request) => Promise<GodminGate>;

package/dist/src/ElysiaPlugin/routes/auth/admin/userState.d.ts

@@ -0,0 +1,46 @@
+import { Elysia } from 'elysia';
+import type { AuthRouteConfig } from '../types';
+/**
+ * Setting the three account-state flags an administrator actually needs:
+ * locked, released, email-verified.
+ *
+ * These columns are refused by the generic entity CRUD API on purpose — a write
+ * grant on `users` must not be a way to self-verify or to defeat lockout. But
+ * refusing them there without offering anywhere else left administration UIs
+ * PATCHing `users` with `isLocked: false` and getting `200 success: true` back
+ * while nothing changed: the fields were dropped silently and `updatedAt` moved,
+ * so the request looked like it worked, the audit log recorded a successful
+ * PATCH, and the account stayed shut out. Three buttons in the Vorion portal
+ * were doing exactly that.
+ *
+ * So the capability lives here, where it is godmin-gated, audited by name, and
+ * answers honestly about what it changed.
+ */
+export declare function createUserStateRoutes(config: AuthRouteConfig): Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/src/Services/Authorization/ClaimsCache/index.d.ts

@@ -1,7 +1,14 @@
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 import type { Logger } from '../../Logger';
 type RedisAdapter = {
-    get: (key: string) => Promise<string | null>;
+    /**
+     * `unknown`: direct Redis returns the written string, Dapr returns an
+     * already-deserialized value (see `Utils/storedJson`). Reading it as `string`
+     * and calling `JSON.parse` threw on every Dapr install — and the caller
+     * swallows that throw, so `resolve` claims mode silently produced no claims
+     * at all rather than failing loudly.
+     */
+    get: (key: string) => Promise<unknown>;
     set: (key: string, value: string) => Promise<void>;
     delete: (key: string) => Promise<void>;
 };

package/dist/src/Services/Captcha/types.d.ts

@@ -53,7 +53,14 @@ export interface CaptchaValidateResult {
 }
 export interface CaptchaServiceDeps {
     redis: {
-        get: (key: string) => Promise<string | null>;
+        /**
+         * `unknown`, not `string`, and deliberately so: the direct-Redis store
+         * returns the string that was written while the Dapr store returns an
+         * already-deserialized object (see `Utils/storedJson`). Typing this as
+         * `string` was the lie that let `JSON.parse(stored)` ship and take every
+         * captcha-gated login to a 500. Read it through `parseStoredJson`.
+         */
+        get: (key: string) => Promise<unknown>;
         set: (key: string, value: string, options?: {
             ex?: number;
         }) => Promise<void>;

package/dist/src/Utils/storedJson.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Read back a value that was written to the state store as JSON.
+ *
+ * The state store has two implementations and, for the same `create()` call,
+ * they hand back two different shapes:
+ *
+ * - `DirectRedisStore` (`src/Managers/Redis/index.ts`) stringifies on write and
+ *   parses once on read. A caller that stringified its own object before
+ *   calling `set` therefore gets its **string** back — the two layers of
+ *   encoding and decoding cancel out.
+ * - `DaprRedisStore` hands the value to the Dapr SDK, whose HTTP client already
+ *   `JSON.parse`s the response body; `DaprStateClient.get` then parses a second
+ *   time. The same caller gets a fully deserialized **object** back.
+ *
+ * So `IStateStore.read` is typed `string` but is only a string half the time.
+ * Any consumer that trusted the type and called `JSON.parse(stored)` directly
+ * threw `SyntaxError: Unexpected identifier "object"` on every Dapr install —
+ * `JSON.parse` stringifies its argument first, and an object stringifies to
+ * `"[object Object]"`. That is what took captcha validation, and with it every
+ * login that required a captcha, to a 500.
+ *
+ * `SessionStore` had already grown its own copy of this guard
+ * (`deserializeSession`). This is that guard, once, for everyone — so the next
+ * consumer does not have to rediscover the asymmetry the hard way.
+ *
+ * Never throws: a value that cannot be understood is `null`, which every caller
+ * already has to handle for the expired / evicted case.
+ */
+export declare function parseStoredJson<T>(stored: unknown): T | null;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.967",
+	"version": "0.9.968",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",

package/scripts/build.ts

@@ -377,8 +377,30 @@ async function obfuscateFiles() {
 
 async function removeSourceMaps() {
   log.info('Removing any source maps...')
-  await $`find ${config.build.outDir} -name "*.map" -delete`.quiet()
-  log.success('Source maps removed')
+  // Walked in JS rather than shelled out to `find`: Bun's shell does not carry
+  // a `find` builtin, so on Windows this step exited 2 and took the whole build
+  // with it — the release could only ever be cut from a machine that happened
+  // to have GNU findutils on PATH.
+  let removed = 0
+  const walk = async (dir: string): Promise<void> => {
+    let entries: Awaited<ReturnType<typeof readdir>>
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      return // the directory is optional; nothing to clean if it was never built
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        await walk(full)
+      } else if (entry.name.endsWith('.map')) {
+        await rm(full, { force: true })
+        removed++
+      }
+    }
+  }
+  await walk(config.build.outDir)
+  log.success(removed > 0 ? `Source maps removed (${removed})` : 'Source maps removed')
 }
 
 async function verifyBuild() {