@cellarnode/auth 0.13.3 → 0.15.0

package/README.md

@@ -13,7 +13,14 @@ npm install @cellarnode/auth
 ### Core (framework-agnostic)
 
 ```ts
-import { createAuthStore, createAuthClient, createAuthApi } from "@cellarnode/auth";
+import {
+  canReplaySession,
+  captureSessionContinuity,
+  createAuthApi,
+  createAuthClient,
+  createAuthStore,
+  resolveSessionForReplay,
+} from "@cellarnode/auth";
 
 const authStore = createAuthStore({
   baseUrl: "http://localhost:4000",
@@ -28,14 +35,107 @@ const authClient = createAuthClient({
 const authApi = createAuthApi({ client: authClient, store: authStore });
 ```
 
+All package-owned requests require HTTPS. HTTP works automatically only for
+exact loopback hosts `localhost`, `127.0.0.1`, and `[::1]` during local
+development. Invalid URLs, userinfo, other schemes, non-loopback HTTP, and
+request paths that escape the configured origin or base path fail before
+network transport. Redirects are rejected so credentials cannot follow a
+cross-origin or HTTPS-to-HTTP redirect.
+
+Resolve token and authoritative identity together before enabling protected
+work. `unavailable` preserves credentials while authority getters fail closed.
+Caller abort returns `superseded` without cancelling shared adoption.
+
+```ts
+const session = await authStore.resolveSession({ refresh: true, signal });
+if (session.status === "ready") {
+  // session.token and validated session.user are from one guarded generation
+}
+```
+
+`ensureAccessToken()` remains a legacy credential-only wrapper. It may return a
+retained token while authority is transiently `unavailable`; authority getters
+still fail closed. Never use its token as proof that user or organisation
+authority is ready. Use `resolveSession()` and require `status === "ready"` for
+authorization decisions.
+
+`onSessionStateChange` immediately reports current state. A synchronous
+`resolving` notification precedes credential or authority changes, allowing
+consumers to suspend writes and clear captured tenant queries first.
+`getSessionState()` returns the same guarded state as a defensive snapshot;
+continuity capture requires that snapshot to remain `ready`. Internal refresh
+and identity requests time out after 10 seconds by default; configure
+`resolutionTimeoutMs` on `createAuthStore` when needed.
+
+Authenticated transports that retry after 401 must capture continuity before
+their first request and replay only for same validated user and organisation:
+
+```ts
+const before = captureSessionContinuity(authStore);
+if (!before) throw new Error("Session authority unavailable");
+const response = await fetch(url, init);
+if (response.status === 401) {
+  const after = await resolveSessionForReplay(authStore, before, {
+    signal: init.signal,
+  });
+  if (canReplaySession(before, after, authStore)) {
+    // retry once with after.token
+  }
+}
+```
+
+`resolveSessionForReplay` centralizes stale-401 handling. It never refreshes a
+replacement session. A ready rotated token can be reused once only when
+validated user and organisation still match captured request authority.
+
 ### React Components
 
 ```tsx
 import { LoginForm, RegisterForm, UnauthorizedPage } from "@cellarnode/auth/react";
 ```
 
-### Tailwind CSS Content Scan
+### Dev sign-in bypass (local development only)
+
+`LoginForm` renders an extra "Dev sign-in (skip the code)" control **beside** the
+email form when `import.meta.env.DEV` is true. It calls
+`authStore.devLogin(email)`, which POSTs the backend's `/test/login` and adopts
+the returned JWE through the same path `verifyOtp` uses. The OTP flow is
+unchanged and remains the only path in production builds. There is no env var to
+set on the frontend.
+
+What is and is not dropped from a production bundle — the distinction matters,
+so do not compress it:
+
+- **Dropped.** The `DevSignInBypass` component and its markup. Vite folds
+  `import.meta.env.DEV` to `false`, Rollup removes the branch, and the module
+  goes with it. Pinned by `__tests__/dev-bypass-treeshake.test.ts`, which
+  bundles the form both ways and greps the output.
+- **Kept.** `authStore.devLogin` and its failure copy, plus the
+  `readDevLoginEmail` / `rememberDevLoginEmail` helpers. All are reached from
+  live function bodies behind runtime `if` guards, so no bundler can prove them
+  unreachable. They are inert — the helpers only run inside the DEV branch, and
+  `devLogin` calls a route that is not mounted in production.
+
+The security boundary is the **server**, not the bundle. `/test/login` is only
+mounted when `NODE_ENV`/`MODE` is non-production **and**
+`ENABLE_TEST_ENDPOINTS=true`, and every handler re-checks the same predicate.
+When it is off, `/test/login` returns a uniform 404 and `devLogin()` resolves to
+`{ ok: false, reason: "test-endpoints-disabled" }`. That 404 is deliberately
+identical to the "no local account for this address" case, so neither the helper
+nor the UI may present it as a statement about the account.
+
+`devLogin()` never rejects; every outcome is a `DevLoginResult`. Callers should
+still wrap it, because `devLogin` is optional on the `AuthStore` interface and a
+custom store may reject.
+
+```ts
+const result = await authStore.devLogin?.("producer@example.com");
+if (result?.ok) {
+  // session adopted: token set, refresh scheduled, listeners fired
+}
+```
 
+### Tailwind CSS Content Scan
 Add this to your CSS file so Tailwind picks up utility classes from the package:
 
 ```css
@@ -44,8 +144,24 @@ Add this to your CSS file so Tailwind picks up utility classes from the package:
 
 ## Exports
 
-- `@cellarnode/auth` — Core: `createAuthStore`, `createAuthClient`, `createAuthApi`, `validateUserType`, types
-- `@cellarnode/auth/react` — React: `LoginForm`, `RegisterForm`, `UnauthorizedPage`, `SquircleShift`
+- `@cellarnode/auth` — Core: `createAuthStore`, `createAuthClient`, `createAuthApi`, `captureSessionContinuity`, `resolveSessionForReplay`, `canReplaySession`, `validateUserType`, `hasEntitlement`, `extractAccessToken`, `AuthError`, session-resolution types, and `DevLoginResult`
+- `@cellarnode/auth/react` — React: `LoginForm`, `RegisterForm`, `UnauthorizedPage`, `SquircleShift`, `InputOTP` (+ `Group` / `Slot` / `Separator`)
+
+`DevSignInBypass`, `DEV_LOGIN_EMAIL_STORAGE_KEY`, `readDevLoginEmail` and
+`rememberDevLoginEmail` are **deliberately not exported**. They are internals of
+`LoginForm`'s `import.meta.env.DEV` branch; the gate lives at that one call site,
+and an exported symbol carries no gate — a consumer importing it could render the
+bypass UI, or write a sign-in address to `localStorage`, from a production build.
+
+## Publishing
+
+Published to npm (public access) via **npm Trusted Publishing (OIDC)** —
+`.github/workflows/publish.yml` publishes automatically on a merge to `main` that changes
+`package.json`'s version. There is no long-lived npm token in the publish job, and nobody runs
+`npm publish` by hand. Provenance is generated automatically (public repo + public package).
+
+Bump `version` in `package.json` and land it through a normal PR — merging to `main` is what
+triggers the publish job, gated on the version having actually changed.
 
 ## License
 

package/dist/auth-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-api.d.ts","sourceRoot":"","sources":["../src/auth-api.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,SAAS,EAKV,MAAM,YAAY,CAAC;AAGpB,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;CAClB,GAAG,OAAO,CAiEV"}
+{"version":3,"file":"auth-api.d.ts","sourceRoot":"","sources":["../src/auth-api.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,SAAS,EAIV,MAAM,YAAY,CAAC;AAIpB,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;CAClB,GAAG,OAAO,CAoHV"}

package/dist/auth-api.js

@@ -1,5 +1,6 @@
 import { AuthError } from "./types.js";
 import { extractAccessToken } from "./extract-token.js";
+import { parseAuthUser, parseVerifyOtpUser } from "./auth-user.js";
 export function createAuthApi(config) {
     const { client, store } = config;
     return {
@@ -27,26 +28,64 @@ export function createAuthApi(config) {
             if (!token) {
                 throw new AuthError(500, "TOKEN_EXTRACTION_FAILED", "No access token found in verify-otp response");
             }
+            const user = parseVerifyOtpUser(raw.user);
+            if (!user) {
+                throw new AuthError(500, "OTP_USER_INVALID", "Invalid user in verify-otp response");
+            }
             const expiresIn = typeof raw.expiresIn === "number" ? raw.expiresIn : 900;
             store.setAccessToken(token, expiresIn);
             return {
                 accessToken: token,
                 expiresIn,
-                user: raw.user,
+                user,
             };
         },
         async logout() {
-            await client.fetch("/auth/logout", { method: "POST" });
+            const token = store.getAccessToken();
+            await client.fetch("/auth/logout", {
+                method: "POST",
+                skipAuth: true,
+                ...(token
+                    ? { headers: { Authorization: `Bearer ${token}` } }
+                    : {}),
+            });
         },
         async getMe(token) {
-            if (token) {
-                return client.fetch("/auth/me", {
+            const currentToken = store.getAccessToken();
+            const explicitCurrentToken = token !== undefined && token === currentToken;
+            if (store.resolveSession && token === undefined) {
+                const resolution = await store.resolveSession();
+                if (resolution.status === "ready")
+                    return resolution.user;
+                if (resolution.status === "unauthorized") {
+                    throw new AuthError(401, "UNAUTHORIZED", "Session is unauthorized");
+                }
+                if (resolution.status === "superseded") {
+                    throw new AuthError(409, "SESSION_SUPERSEDED", "Session was superseded");
+                }
+                throw new AuthError(503, "AUTHORITY_UNAVAILABLE", "Session identity is unavailable");
+            }
+            const raw = token !== undefined
+                ? await client.fetch("/auth/me", {
                     method: "GET",
                     skipAuth: true,
                     headers: { Authorization: `Bearer ${token}` },
+                })
+                : await client.fetch("/auth/me", {
+                    method: "GET",
+                    skipAuth: true,
+                    ...(currentToken
+                        ? { headers: { Authorization: `Bearer ${currentToken}` } }
+                        : {}),
                 });
+            if (explicitCurrentToken && store.getAccessToken() !== token) {
+                throw new AuthError(409, "SESSION_SUPERSEDED", "Session was superseded");
+            }
+            const user = parseAuthUser(raw);
+            if (!user) {
+                throw new AuthError(503, "AUTHORITY_UNAVAILABLE", "Session identity is unavailable");
             }
-            return client.fetch("/auth/me", { method: "GET" });
+            return user;
         },
     };
 }

package/dist/auth-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-api.js","sourceRoot":"","sources":["../src/auth-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAUvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,UAAU,aAAa,CAAC,MAG7B;IACC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAEjC,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,KAAoB;YACjC,OAAO,MAAM,CAAC,KAAK,CACjB,gBAAgB,EAChB;gBACE,MAAM,EAAE,MAAM;gBACd,QAAQ,EAAE,IAAI;gBACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;aAC5B,CACF,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,KAAa;YAC5B,OAAO,MAAM,CAAC,KAAK,CAAqB,mBAAmB,EAAE;gBAC3D,MAAM,EAAE,MAAM;gBACd,QAAQ,EAAE,IAAI;gBACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC;aAChC,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,KAAa,EAAE,IAAY;YACzC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAC5B,kBAAkB,EAClB;gBACE,MAAM,EAAE,MAAM;gBACd,QAAQ,EAAE,IAAI;gBACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;aACtC,CACF,CAAC;YAEF,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;YACtC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,yBAAyB,EAAE,8CAA8C,CAAC,CAAC;YACtG,CAAC;YAED,MAAM,SAAS,GACb,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC;YAE1D,KAAK,CAAC,cAAc,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAEvC,OAAO;gBACL,WAAW,EAAE,KAAK;gBAClB,SAAS;gBACT,IAAI,EAAE,GAAG,CAAC,IAAgB;aAC3B,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,MAAM;YACV,MAAM,MAAM,CAAC,KAAK,CAAO,cAAc,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/D,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,KAAc;YACxB,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,MAAM,CAAC,KAAK,CAAW,UAAU,EAAE;oBACxC,MAAM,EAAE,KAAK;oBACb,QAAQ,EAAE,IAAI;oBACd,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE;iBAC9C,CAAC,CAAC;YACL,CAAC;YACD,OAAO,MAAM,CAAC,KAAK,CAAW,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/D,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"auth-api.js","sourceRoot":"","sources":["../src/auth-api.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"auth-client.d.ts","sourceRoot":"","sources":["../src/auth-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAqB,MAAM,YAAY,CAAC;AAElF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CAmFrE"}
+{"version":3,"file":"auth-client.d.ts","sourceRoot":"","sources":["../src/auth-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAqB,MAAM,YAAY,CAAC;AAQlF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CA8JrE"}

package/dist/auth-client.js

@@ -1,4 +1,6 @@
 import { AuthError } from "./types.js";
+import { canReplaySession, captureSessionContinuity, resolveSessionForReplay, } from "./session-continuity.js";
+import { fetchAuthRequest } from "./auth-transport.js";
 export function createAuthClient(config) {
     const { baseUrl, store, onAuthFailure } = config;
     async function parseErrorResponse(res) {
@@ -20,17 +22,32 @@ export function createAuthClient(config) {
         async fetch(path, options) {
             const { skipAuth, ...init } = options ?? {};
             const headers = new Headers(init.headers);
+            const continuity = skipAuth ? null : captureSessionContinuity(store);
             if (!skipAuth) {
                 const token = store.getAccessToken();
-                if (token) {
-                    headers.set("Authorization", `Bearer ${token}`);
+                if (!continuity) {
+                    throw token
+                        ? new AuthError(503, "SESSION_UNAVAILABLE", "Session identity is unavailable")
+                        : new AuthError(401, "UNAUTHORIZED", "Session is unauthorized");
                 }
+                headers.set("Authorization", `Bearer ${continuity.token}`);
             }
             if (!headers.has("Content-Type") && init.body) {
                 headers.set("Content-Type", "application/json");
             }
-            const url = `${baseUrl}${path}`;
-            const res = await fetch(url, {
+            const retryWithToken = async (token) => {
+                headers.set("Authorization", `Bearer ${token}`);
+                const retryRes = await fetchAuthRequest(baseUrl, path, {
+                    ...init,
+                    headers,
+                    credentials: "include",
+                });
+                if (retryRes.ok)
+                    return (await retryRes.json());
+                const retryError = await parseErrorResponse(retryRes);
+                throw new AuthError(retryRes.status, retryError.code, retryError.error, retryError.remainingAttempts);
+            };
+            const res = await fetchAuthRequest(baseUrl, path, {
                 ...init,
                 headers,
                 credentials: "include",
@@ -38,23 +55,50 @@ export function createAuthClient(config) {
             if (res.ok) {
                 return (await res.json());
             }
-            // 401: attempt one refresh + retry (only for authenticated requests)
+            // 401: refresh once. Replay only when validated user + tenant continuity
+            // matches the authority captured before original transport.
             if (res.status === 401 && !skipAuth) {
-                const newToken = await store.ensureAccessToken(true);
-                if (newToken) {
-                    headers.set("Authorization", `Bearer ${newToken}`);
-                    const retryRes = await fetch(url, {
-                        ...init,
-                        headers,
-                        credentials: "include",
+                if (!store.resolveSession) {
+                    const current = captureSessionContinuity(store);
+                    if (!continuity ||
+                        !current ||
+                        current.token !== continuity.token ||
+                        current.userId !== continuity.userId ||
+                        current.orgId !== continuity.orgId) {
+                        throw new AuthError(409, "SESSION_SUPERSEDED", "Request session was superseded");
+                    }
+                    store.clearAccessToken();
+                    if (store.getAccessToken() === null)
+                        onAuthFailure?.();
+                }
+                else {
+                    const resolution = await resolveSessionForReplay(store, continuity, {
+                        signal: init.signal ?? undefined,
                     });
-                    if (retryRes.ok) {
-                        return (await retryRes.json());
+                    if (resolution.status === "ready" &&
+                        canReplaySession(continuity, resolution, store)) {
+                        return retryWithToken(resolution.token);
+                    }
+                    if (resolution.status === "unavailable") {
+                        throw new AuthError(503, "SESSION_UNAVAILABLE", "Session identity is unavailable");
+                    }
+                    if (resolution.status === "superseded") {
+                        if (init.signal?.aborted) {
+                            throw new DOMException("Request aborted", "AbortError");
+                        }
+                        throw new AuthError(409, "SESSION_SUPERSEDED", "Request session was superseded");
+                    }
+                    if (resolution.status === "ready") {
+                        const currentState = store.getSessionState?.();
+                        if ((currentState?.status === "resolving" ||
+                            currentState?.status === "unavailable") &&
+                            currentState.token === resolution.token) {
+                            throw new AuthError(503, "SESSION_UNAVAILABLE", "Session identity is unavailable");
+                        }
+                        throw new AuthError(409, "SESSION_CONTINUITY_CHANGED", "Request session authority changed");
                     }
+                    onAuthFailure?.();
                 }
-                // Refresh failed or retry failed
-                store.clearAccessToken();
-                onAuthFailure?.();
             }
             const errBody = await parseErrorResponse(res);
             throw new AuthError(res.status, errBody.code, errBody.error, errBody.remainingAttempts);

package/dist/auth-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-client.js","sourceRoot":"","sources":["../src/auth-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth-client.js","sourceRoot":"","sources":["../src/auth-client.ts"],"names":[],"mappings":"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"}

package/dist/auth-store.d.ts

@@ -1,3 +1,3 @@
-import type { AuthStore, AuthStoreConfig } from "./types.js";
-export declare function createAuthStore(config: AuthStoreConfig): AuthStore;
+import type { AuthStoreConfig, ConcreteAuthStore } from "./types.js";
+export declare function createAuthStore(config: AuthStoreConfig): ConcreteAuthStore;
 //# sourceMappingURL=auth-store.d.ts.map

package/dist/auth-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../src/auth-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EACT,eAAe,EAKhB,MAAM,YAAY,CAAC;AAuCpB,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAsRlE"}
+{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../src/auth-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,eAAe,EAEf,iBAAiB,EASlB,MAAM,YAAY,CAAC;AAsDpB,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CAsvB1E"}