@superbuilders/primer-tives 4.0.4 → 4.0.5

package/README.md

@@ -19,7 +19,7 @@ bun add @superbuilders/primer-tives
 
 ## Version
 
-The current SDK version is `4.0.4`.
+The current SDK version is `4.0.5`.
 
 ## Entrypoints
 
@@ -210,12 +210,40 @@ The SDK uses Primer's production runtime by default.
 | Shape | Semantics |
 | --- | --- |
 | `accessToken` present | `start` validates the token shape locally and returns `AccessTokenStartState`. This mode cannot return sign-in states. |
-| `accessToken` absent | `start` returns managed hosted-auth state or runtime state as `ManagedStartState`. This mode does not read browser storage and does not persist tokens. |
+| `accessToken` absent | `start` uses managed hosted-auth mode. It reads and writes the SDK-managed browser session token cache documented below. |
 
 The public API exposes hosted auth as state behavior. `SignInRequiredState.login()` and `SignInFailedState.login()` are the sign-in transitions. `AuthUnavailableState` and `AuthConfigInvalidState` expose no login operation.
 
 When `subject` is present, it must be a concrete literal subject at the options declaration site. Do not pass a broad `Subject` value into `PrimerOptions`; narrow it in host control flow, then construct options with `satisfies PrimerOptionsWithManagedAuth<"math", ...>`, `satisfies PrimerOptionsWithAccessToken<"math", ...>`, or the corresponding literal subject variant.
 
+## Managed Auth Token Persistence
+
+Managed hosted auth is designed for browser-only consumers that do not have their own server-side token broker. When `accessToken` is absent, PrimerTives owns a session-scoped browser token cache with one fixed storage location:
+
+```txt
+sessionStorage["primer:access-token:<publishableKey>"]
+```
+
+This is intentionally zero config. There is no storage selector and no persistence flag. Managed-auth mode always uses `globalThis.sessionStorage`; if `sessionStorage` is unavailable, `start` returns `AuthUnavailableState`.
+
+The cache stores only the final Primer access token returned by hosted Timeback sign-in. OAuth transaction state, nonce, verifier, and callback validation state are not stored in browser storage; those remain server-managed by Primer.
+
+Managed-auth startup behavior is:
+
+| Situation | SDK behavior |
+| --- | --- |
+| Valid cached token exists | `start` uses it and enters the runtime without opening sign-in. |
+| No cached token exists | `start` returns `SignInRequiredState`. |
+| Cached token is malformed or expired | SDK clears the key and returns `SignInRequiredState`. |
+| Hosted sign-in succeeds | SDK validates the returned token, stores it at the documented key, then starts the runtime. |
+| Runtime rejects a managed cached token as expired or invalid | SDK clears the key and returns `SignInFailedState` so the app can ask the learner to sign in again. |
+
+Access-token mode bypasses this cache entirely. If `accessToken` is present in `start` options, PrimerTives does not read, write, or clear `sessionStorage`.
+
+The cached value is a bearer credential. Browser-only consumers get reload convenience from this default, but any script that can read the page can read the token. Host applications must maintain normal XSS protections and should use access-token mode if they need to own token storage themselves.
+
+The canonical managed sign-in endpoint is `/api/auth/timeback/start`. Legacy `/auth/timeback` URLs are not part of the PrimerTives 4.0.5 contract.
+
 ## Auth Semantics
 
 An access token is expected to be JWS-shaped: it starts with `eyJ` and contains exactly two dots. If a provided token does not match that shape, `start` returns `FatalState` with `ErrMalformedAccessToken`.

package/dist/client/auth/provider.d.ts

@@ -9,6 +9,7 @@ type AccessTokenResolverOptions = {
 type ResolvedAccessTokenResult = {
     readonly kind: "resolved";
     readonly accessToken: ResolvedAccessToken;
+    readonly clearCachedAccessToken?: () => void;
 };
 type MissingAccessTokenResult = {
     readonly kind: "missing";
@@ -17,7 +18,11 @@ type FatalAccessTokenResult = {
     readonly kind: "fatal";
     readonly error: Error;
 };
-type ExistingAccessTokenResult = ResolvedAccessTokenResult | MissingAccessTokenResult | FatalAccessTokenResult;
+type AuthUnavailableResult = {
+    readonly kind: "auth-unavailable";
+    readonly error: Error;
+};
+type ExistingAccessTokenResult = ResolvedAccessTokenResult | MissingAccessTokenResult | AuthUnavailableResult | FatalAccessTokenResult;
 type HostedLoginResult = ResolvedAccessTokenResult | {
     readonly kind: "sign-in-failed";
     readonly error: Error;

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

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/client/auth/provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAGtE,OAAO,EAEN,KAAK,mBAAmB,EACxB,MAAM,sDAAsD,CAAA;AAG7D,KAAK,0BAA0B,GAAG;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAC7B,CAAA;AAED,KAAK,yBAAyB,GAAG;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAA;CACzC,CAAA;AAED,KAAK,wBAAwB,GAAG;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CACxB,CAAA;AAED,KAAK,sBAAsB,GAAG;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACrB,CAAA;AAED,KAAK,yBAAyB,GAC3B,yBAAyB,GACzB,wBAAwB,GACxB,sBAAsB,CAAA;AAEzB,KAAK,iBAAiB,GACnB,yBAAyB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAA;AAyBlE,iBAAS,0BAA0B,CAClC,OAAO,EAAE,0BAA0B,GACjC,yBAAyB,CAK3B;AAYD,iBAAe,gBAAgB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAwB/F;AAED,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,CAAA;AACvD,YAAY,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,CAAA"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/client/auth/provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAGtE,OAAO,EAEN,KAAK,mBAAmB,EACxB,MAAM,sDAAsD,CAAA;AAS7D,KAAK,0BAA0B,GAAG;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAC7B,CAAA;AAED,KAAK,yBAAyB,GAAG;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAA;IACzC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,IAAI,CAAA;CAC5C,CAAA;AAED,KAAK,wBAAwB,GAAG;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CACxB,CAAA;AAED,KAAK,sBAAsB,GAAG;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACrB,CAAA;AAED,KAAK,qBAAqB,GAAG;IAC5B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACrB,CAAA;AAED,KAAK,yBAAyB,GAC3B,yBAAyB,GACzB,wBAAwB,GACxB,qBAAqB,GACrB,sBAAsB,CAAA;AAEzB,KAAK,iBAAiB,GACnB,yBAAyB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAA;AA4DlE,iBAAS,0BAA0B,CAClC,OAAO,EAAE,0BAA0B,GACjC,yBAAyB,CAW3B;AAYD,iBAAe,gBAAgB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAyB/F;AAED,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,CAAA;AACvD,YAAY,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/client/auth/storage.d.ts

@@ -0,0 +1,8 @@
+import type { PrimerLogger } from "../../logger";
+declare function managedAuthAccessTokenStorageKey(publishableKey: string): string;
+declare function managedAuthStorage(logger: PrimerLogger): Storage;
+declare function loadManagedAuthAccessToken(storage: Storage, publishableKey: string): string | null;
+declare function storeManagedAuthAccessToken(storage: Storage, publishableKey: string, accessToken: string): void;
+declare function clearManagedAuthAccessToken(storage: Storage, publishableKey: string): void;
+export { clearManagedAuthAccessToken, loadManagedAuthAccessToken, managedAuthAccessTokenStorageKey, managedAuthStorage, storeManagedAuthAccessToken };
+//# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/client/auth/storage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAItE,iBAAS,gCAAgC,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,iBAAS,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAMzD;AAED,iBAAS,0BAA0B,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3F;AAED,iBAAS,2BAA2B,CACnC,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GACjB,IAAI,CAEN;AAED,iBAAS,2BAA2B,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAEnF;AAED,OAAO,EACN,2BAA2B,EAC3B,0BAA0B,EAC1B,gCAAgC,EAChC,kBAAkB,EAClB,2BAA2B,EAC3B,CAAA"}

package/dist/client/index.js

@@ -6783,7 +6783,7 @@ function submissionValidationMessage(result) {
 import * as errors3 from "@superbuilders/errors";
 
 // src/version.ts
-var SDK_VERSION = "4.0.4";
+var SDK_VERSION = "4.0.5";
 var NPM_PACKAGE_URL = "https://www.npmjs.com/package/@superbuilders/primer-tives";
 
 // src/client/transport.ts
@@ -7507,9 +7507,9 @@ function makeSession(sc) {
     };
     const result = await sc.transport(body);
     if (!result.ok) {
-      if (errors10.is(result.error, ErrTokenExpired) && sc.reauthenticate !== null) {
-        logger.warn({ phase, intentKind: intent.kind }, "session token expired");
-        return sc.reauthenticate();
+      if ((errors10.is(result.error, ErrTokenExpired) || errors10.is(result.error, ErrInvalidAccessToken)) && sc.reauthenticate !== null) {
+        logger.warn({ phase, intentKind: intent.kind }, "session token rejected");
+        return sc.reauthenticate(result.error);
       }
       if (isFatalError(result.error)) {
         logger.error({
@@ -7841,6 +7841,32 @@ function resolveAccessToken(token, logger) {
   return { value: token, [resolvedAccessTokenBrand]: true };
 }
 
+// src/client/auth/storage.ts
+var MANAGED_AUTH_ACCESS_TOKEN_KEY_PREFIX = "primer:access-token";
+function managedAuthAccessTokenStorageKey(publishableKey) {
+  return `${MANAGED_AUTH_ACCESS_TOKEN_KEY_PREFIX}:${publishableKey}`;
+}
+function managedAuthStorage(logger) {
+  if (typeof globalThis.sessionStorage === "undefined") {
+    logger.error("managed auth storage unavailable");
+    throw ErrAuthUnavailable;
+  }
+  return globalThis.sessionStorage;
+}
+function loadManagedAuthAccessToken(storage, publishableKey) {
+  const token = storage.getItem(managedAuthAccessTokenStorageKey(publishableKey));
+  if (token === null || token.length === 0) {
+    return null;
+  }
+  return token;
+}
+function storeManagedAuthAccessToken(storage, publishableKey, accessToken) {
+  storage.setItem(managedAuthAccessTokenStorageKey(publishableKey), accessToken);
+}
+function clearManagedAuthAccessToken(storage, publishableKey) {
+  storage.removeItem(managedAuthAccessTokenStorageKey(publishableKey));
+}
+
 // src/client/auth/provider.ts
 function resolveProvidedAccessToken(token, logger) {
   const result = errors12.trySync(function resolveProvidedToken() {
@@ -7851,20 +7877,53 @@ function resolveProvidedAccessToken(token, logger) {
   }
   return { kind: "resolved", accessToken: result.data };
 }
-function resolveHostedAccessToken(token, logger) {
+function resolveHostedAccessToken(token, storage, options) {
   const result = errors12.trySync(function resolveHostedToken() {
-    return resolveAccessToken(token, logger);
+    return resolveAccessToken(token, options.logger);
   });
   if (result.error) {
     return { kind: "sign-in-failed", error: result.error };
   }
-  return { kind: "resolved", accessToken: result.data };
+  storeManagedAuthAccessToken(storage, options.publishableKey, token);
+  return {
+    kind: "resolved",
+    accessToken: result.data,
+    clearCachedAccessToken: function clearCachedAccessToken() {
+      clearManagedAuthAccessToken(storage, options.publishableKey);
+    }
+  };
+}
+function resolveStoredAccessToken(storage, options) {
+  const stored = loadManagedAuthAccessToken(storage, options.publishableKey);
+  if (stored === null) {
+    return { kind: "missing" };
+  }
+  const result = errors12.trySync(function resolveStoredToken() {
+    return resolveAccessToken(stored, options.logger);
+  });
+  if (result.error) {
+    clearManagedAuthAccessToken(storage, options.publishableKey);
+    return { kind: "missing" };
+  }
+  return {
+    kind: "resolved",
+    accessToken: result.data,
+    clearCachedAccessToken: function clearCachedAccessToken() {
+      clearManagedAuthAccessToken(storage, options.publishableKey);
+    }
+  };
 }
 function resolveExistingAccessToken(options) {
   if (options.accessToken !== undefined) {
     return resolveProvidedAccessToken(options.accessToken, options.logger);
   }
-  return { kind: "missing" };
+  const storageResult = errors12.trySync(function readManagedAuthStorage() {
+    return managedAuthStorage(options.logger);
+  });
+  if (storageResult.error) {
+    return { kind: "auth-unavailable", error: storageResult.error };
+  }
+  return resolveStoredAccessToken(storageResult.data, options);
 }
 function authFailureResult(error) {
   if (errors12.is(error, ErrAuthConfigInvalid)) {
@@ -7878,9 +7937,10 @@ function authFailureResult(error) {
 async function beginHostedLogin(options) {
   const logger = options.logger;
   const contextResult = errors12.trySync(function readContext() {
+    const storage = managedAuthStorage(logger);
     const url = currentUrl(logger);
     const clientState = randomClientState(logger);
-    return { url, clientState };
+    return { storage, url, clientState };
   });
   if (contextResult.error) {
     return authFailureResult(contextResult.error);
@@ -7896,7 +7956,7 @@ async function beginHostedLogin(options) {
   if (accessTokenResult.error) {
     return authFailureResult(accessTokenResult.error);
   }
-  return resolveHostedAccessToken(accessTokenResult.data, logger);
+  return resolveHostedAccessToken(accessTokenResult.data, context.storage, options);
 }
 
 // src/client/auth-state.ts
@@ -7965,8 +8025,11 @@ function primerOrigin(origin) {
 }
 async function startRuntime(config, resolved) {
   let reauthenticate = null;
-  if (resolved.reauthenticate !== undefined) {
-    reauthenticate = resolved.reauthenticate;
+  if (resolved.clearCachedAccessToken !== undefined) {
+    reauthenticate = function reauthenticateManagedAuth(error) {
+      resolved.clearCachedAccessToken?.();
+      return Promise.resolve(makeSignInFailedState(config, error));
+    };
   }
   const transport = createTransport({
     accessToken: resolved.accessToken,
@@ -8018,9 +8081,7 @@ async function loginAndStart(config) {
   }
   return startRuntime(config, {
     accessToken: result.accessToken,
-    reauthenticate: function reauthenticate() {
-      return Promise.resolve(makeSignInFailedState(config, ErrTokenExpired));
-    }
+    clearCachedAccessToken: result.clearCachedAccessToken
   });
 }
 async function start(options) {
@@ -8050,6 +8111,9 @@ async function start(options) {
       toJSON: poisonToJSON
     };
   }
+  if (accessToken.kind === "auth-unavailable") {
+    return authUnavailableState(accessToken.error);
+  }
   if (accessToken.kind === "missing") {
     return makeSignInRequiredState(config);
   }
@@ -8059,4 +8123,4 @@ export {
   start
 };
 
-//# debugId=1270BDB9A874B19364756E2164756E21
+//# debugId=D2887B68B961EF6364756E2164756E21