@securitydept/client 0.2.0-beta.1

package/dist/planner-host-DUZCkLj3.d.mts

@@ -0,0 +1,190 @@
+//#region src/auth-coordination/planner-host.d.ts
+/**
+ * A single requirement candidate that a guard submits to the planner-host.
+ *
+ * Each option describes:
+ * 1. What auth requirement it represents (id, kind, label)
+ * 2. How to check whether it's already satisfied
+ * 3. What to do when the planner selects it as the next pending action
+ */
+interface AuthGuardClientOption {
+  /** Unique identifier for this requirement candidate. */
+  requirementId: string;
+  /**
+   * The kind of auth requirement (opaque string).
+   * @example "session", "frontend_oidc", "backend_oidc"
+   */
+  requirementKind: string;
+  /** Human-readable label (for logging / debugging / chooser UI). */
+  label?: string;
+  /** Arbitrary metadata the adopter can attach. */
+  attributes?: Record<string, unknown>;
+  /**
+   * Check whether this requirement candidate is already authenticated.
+   * Called synchronously by the planner-host during evaluation.
+   */
+  checkAuthenticated: () => boolean;
+  /**
+   * Action to execute when this candidate is selected as the pending
+   * requirement by the planner-host.
+   *
+   * Return value semantics:
+   * - `true` — allow navigation (requirement will be resolved externally)
+   * - `false` — block navigation
+   * - `string` — redirect to the given URL
+   * - `Promise<...>` — async version of the above
+   */
+  onUnauthenticated: () => boolean | string | Promise<boolean | string>;
+}
+/** A flat collection of requirement candidates. */
+interface RequirementsClientSet {
+  readonly options: readonly AuthGuardClientOption[];
+}
+/**
+ * How a child scope's requirements client set relates to its parent.
+ *
+ * - `inherit` — use the parent's set as-is (child adds nothing)
+ * - `merge` — inherit parent's options, then append/override with child's
+ *   (child options with the same `requirementId` replace parent ones)
+ * - `replace` — discard parent's set entirely, use child's set only
+ */
+declare const RequirementsClientSetComposition: {
+  readonly Inherit: "inherit";
+  readonly Merge: "merge";
+  readonly Replace: "replace";
+};
+type RequirementsClientSetComposition = (typeof RequirementsClientSetComposition)[keyof typeof RequirementsClientSetComposition];
+/** A requirements client set annotated with its composition strategy. */
+interface ScopedRequirementsClientSet {
+  /** How this set composes with its parent scope. */
+  composition: RequirementsClientSetComposition;
+  /** The requirement candidates declared at this scope. */
+  options: readonly AuthGuardClientOption[];
+}
+/**
+ * Resolve the effective requirements client set by composing a parent set
+ * with a child scope's declaration.
+ *
+ * @param parentOptions - The parent scope's resolved options (or empty).
+ * @param child - The child scope's scoped set (with composition strategy).
+ * @returns The effective options after composition.
+ */
+declare function resolveEffectiveClientSet(parentOptions: readonly AuthGuardClientOption[], child: ScopedRequirementsClientSet): AuthGuardClientOption[];
+/** Result of a planner-host evaluation. */
+interface PlannerHostResult {
+  /** Whether all candidates are authenticated (route can activate). */
+  allAuthenticated: boolean;
+  /** All candidates that are not yet authenticated. */
+  unauthenticatedCandidates: readonly AuthGuardClientOption[];
+  /**
+   * The candidate selected by the planner as the next one to act on.
+   * `null` when `allAuthenticated` is true.
+   *
+   * Determined by the RequirementPlanner's sequential resolution discipline:
+   * the first unresolved requirement in declaration order that is still
+   * unauthenticated, then optionally further narrowed by `selectCandidate`.
+   */
+  pendingCandidate: AuthGuardClientOption | null;
+}
+/**
+ * A candidate selection strategy.
+ *
+ * Receives the list of unauthenticated candidates (in RequirementPlanner
+ * declaration order) and returns the one that should be acted on next.
+ * The default strategy picks the first one (matching the planner's
+ * `nextPending` requirement).
+ *
+ * Async selectors are supported: return a `Promise<AuthGuardClientOption>`
+ * to implement interactive chooser UIs (e.g. show a dialog and await the
+ * user's pick before navigation continues).
+ *
+ * @example
+ * ```ts
+ * // Async chooser: show a dialog and await user's selection
+ * const selectCandidate: CandidateSelector = async (candidates) => {
+ *   const chosen = await showChooserDialog(candidates);
+ *   return chosen;
+ * };
+ * ```
+ */
+type CandidateSelector = (unauthenticated: readonly AuthGuardClientOption[]) => AuthGuardClientOption | Promise<AuthGuardClientOption>;
+/** The planner-host coordination contract. */
+interface PlannerHost {
+  /**
+   * Evaluate a set of requirement candidates using RequirementPlanner's
+   * sequential resolution discipline.
+   *
+   * Always returns a Promise so that custom async selectors (e.g. chooser
+   * dialog) are fully supported. Callers should always `await` the result.
+   *
+   * @param candidates - The resolved candidates from the guard's client options.
+   * @returns Promise resolving to the evaluation result.
+   */
+  evaluate(candidates: readonly AuthGuardClientOption[]): Promise<PlannerHostResult>;
+}
+/** Options for {@link createPlannerHost}. */
+interface CreatePlannerHostOptions {
+  /**
+   * Custom candidate selection strategy.
+   *
+   * The default strategy picks the candidate that corresponds to the
+   * RequirementPlanner's `nextPending` requirement (first unauthenticated
+   * in declaration order).
+   *
+   * A custom strategy can further filter or reorder the unauthenticated
+   * candidates, e.g. to implement a chooser UI that lets the user pick.
+   *
+   * @default first-unauthenticated-matching-planner-nextPending
+   *
+   * @example
+   * ```ts
+   * // Async chooser: present all options and await user's pick
+   * createPlannerHost({
+   *   selectCandidate: async (candidates) => {
+   *     return await showChooserDialog(candidates);
+   *   },
+   * })
+   * ```
+   */
+  selectCandidate?: CandidateSelector;
+}
+/**
+ * Create a planner-host instance backed by {@link createRequirementPlanner}.
+ *
+ * **How it works:**
+ *
+ * 1. `evaluate()` builds an `AuthRequirement[]` from `candidates`
+ *    (using each candidate's `requirementId`, `requirementKind`, `label`,
+ *    and `attributes`).
+ * 2. A `RequirementPlanner` is created for this evaluation cycle.
+ * 3. Already-authenticated requirements are auto-resolved as `Fulfilled`,
+ *    respecting the planner's sequential discipline.
+ * 4. The planner's `nextPending` determines the first unresolved requirement
+ *    in declaration order.
+ * 5. `selectCandidate` is called with all unauthenticated candidates so
+ *    adopters can implement custom chooser strategies (e.g. UI dialog).
+ *    The default strategy picks the first candidate (matching nextPending).
+ *
+ * `evaluate()` always returns a `Promise` to accommodate async selectors.
+ * For synchronous selectors the Promise resolves in the same microtask tick.
+ *
+ * @example
+ * ```ts
+ * import { createPlannerHost } from "@securitydept/client/auth-coordination";
+ *
+ * // Default sequential strategy (sync selector, wrapped in Promise)
+ * const host = createPlannerHost();
+ * const result = await host.evaluate(candidates);
+ *
+ * // Async chooser strategy — show a dialog and await user's pick
+ * const hostWithChooser = createPlannerHost({
+ *   selectCandidate: async (candidates) => {
+ *     return await showChooserDialog(candidates);
+ *   },
+ * });
+ * ```
+ */
+declare function createPlannerHost(options?: CreatePlannerHostOptions): PlannerHost;
+//#endregion
+export { PlannerHostResult as a, ScopedRequirementsClientSet as c, PlannerHost as i, createPlannerHost as l, CandidateSelector as n, RequirementsClientSet as o, CreatePlannerHostOptions as r, RequirementsClientSetComposition as s, AuthGuardClientOption as t, resolveEffectiveClientSet as u };
+//# sourceMappingURL=planner-host-DUZCkLj3.d.mts.map

package/dist/types-DKluXsWS.d.mts

@@ -0,0 +1,52 @@
+//#region src/persistence/types.d.ts
+/** Low-level key-value record store. */
+interface RecordStore {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  /**
+   * Atomically read and remove a record within the store's consistency domain.
+   */
+  take?(key: string): Promise<string | null>;
+  remove(key: string): Promise<void>;
+}
+/** Serialization codec for typed values. */
+interface Codec<T> {
+  encode(value: T): string;
+  decode(raw: string): T;
+}
+/** Semantic store for long-lived auth state. */
+interface PersistentAuthStore<T> {
+  load(): Promise<T | null>;
+  save(value: T): Promise<void>;
+  clear(): Promise<void>;
+}
+/** Semantic store for recoverable state (survives page reload). */
+interface RecoverableStateStore<T> {
+  load(): Promise<T | null>;
+  save(value: T): Promise<void>;
+  clear(): Promise<void>;
+}
+/** Semantic store for ephemeral flow state (one-time-use). */
+interface EphemeralFlowStore<T> {
+  load(): Promise<T | null>;
+  save(value: T): Promise<void>;
+  consume(): Promise<T | null>;
+  clear(): Promise<void>;
+}
+/** Semantic store for keyed ephemeral flow state (one-time-use per key). */
+interface KeyedEphemeralFlowStore<T> {
+  load(key: string): Promise<T | null>;
+  save(key: string, value: T): Promise<void>;
+  take(key: string): Promise<T | null>;
+  clear(key: string): Promise<void>;
+}
+/** Versioned storage envelope — first-version migration support. */
+interface StoredEnvelope<T> {
+  version: number;
+  storedAt: number;
+  expiresAt?: number;
+  value: T;
+}
+//#endregion
+export { RecordStore as a, PersistentAuthStore as i, EphemeralFlowStore as n, RecoverableStateStore as o, KeyedEphemeralFlowStore as r, StoredEnvelope as s, Codec as t };
+//# sourceMappingURL=types-DKluXsWS.d.mts.map

package/dist/web/index.d.mts

@@ -0,0 +1,329 @@
+import { S as ClientRuntime, d as Subscription, n as FetchTransportRedirectKind, r as createFetchTransport, t as FetchTransportOptions, z as CancellationTokenTrait } from "../fetch-transport-CMG4tfDu.mjs";
+
+//#region src/web/cancellation.d.ts
+interface AbortSignalBridge {
+  signal?: AbortSignal;
+  dispose(): void;
+}
+/**
+ * Bridge a web `AbortSignal` back into the foundation cancellation contract.
+ *
+ * This is the canonical consumer-side path for browser hosts that receive an
+ * `AbortSignal` from framework/runtime APIs (for example React Query queryFns)
+ * but need to call SDK surfaces that accept `CancellationTokenTrait`.
+ */
+declare function createCancellationTokenFromAbortSignal(signal?: AbortSignal): CancellationTokenTrait | undefined;
+/**
+ * Bridge foundation cancellation to web `AbortSignal` without exposing
+ * `AbortSignal` in core contracts.
+ */
+declare function createAbortSignalBridge(token?: CancellationTokenTrait): AbortSignalBridge;
+declare function normalizeAbortError(token: CancellationTokenTrait | undefined, error: unknown): unknown;
+//#endregion
+//#region src/web/cross-tab-sync.d.ts
+/** Callback invoked when a cross-tab storage change is detected for the watched key. */
+type CrossTabSyncCallback = (event: {
+  /** The new value written by the other tab, or null if the key was removed. */newValue: string | null; /** The old value before the other tab's write. */
+  oldValue: string | null;
+}) => void;
+/** Options for {@link createCrossTabSync}. */
+interface CreateCrossTabSyncOptions {
+  /** The localStorage key to watch for cross-tab changes. */
+  key: string;
+  /** Called when another tab modifies the watched key. */
+  onSync: CrossTabSyncCallback;
+  /**
+   * Override the window target (primarily for testing).
+   * Defaults to `globalThis`.
+   */
+  target?: {
+    addEventListener(type: string, listener: EventListener): void;
+    removeEventListener(type: string, listener: EventListener): void;
+  };
+}
+/** Handle returned by {@link createCrossTabSync}. */
+interface CrossTabSync {
+  /** Stop listening for cross-tab storage events. */
+  dispose(): void;
+  /** Number of times a sync event has been received. */
+  readonly syncCount: number;
+}
+/**
+ * Create a cross-tab sync listener for a specific localStorage key.
+ *
+ * The browser `storage` event fires on ALL tabs EXCEPT the one that made the
+ * change. This makes it a natural primitive for cross-tab state notification.
+ *
+ * @example
+ * ```ts
+ * const sync = createCrossTabSync({
+ *   key: "auth:v1",
+ *   onSync: ({ newValue }) => {
+ *     if (newValue) {
+ *       // Another tab updated auth state — reconcile
+ *       controller.restoreFromPersistence();
+ *     } else {
+ *       // Another tab cleared auth state — log out
+ *       controller.clearState({ clearPersisted: false });
+ *     }
+ *   },
+ * });
+ * // Later:
+ * sync.dispose();
+ * ```
+ */
+declare function createCrossTabSync(options: CreateCrossTabSyncOptions): CrossTabSync;
+//#endregion
+//#region src/web/input-sources.d.ts
+interface AbortSignalSource {
+  aborted: boolean;
+  reason: unknown;
+  addEventListener(type: string, listener: EventListener): void;
+  removeEventListener(type: string, listener: EventListener): void;
+}
+interface FromAbortSignalOptions {
+  /** AbortSignal to observe. */
+  signal?: AbortSignalSource;
+  /** Callback invoked when the signal aborts. */
+  callback: (reason: unknown) => void;
+  /**
+   * Emit immediately when the signal is already aborted at subscribe time.
+   * Defaults to `false`.
+   */
+  emitIfAborted?: boolean;
+}
+interface StorageEventTarget {
+  addEventListener(type: string, listener: EventListener): void;
+  removeEventListener(type: string, listener: EventListener): void;
+}
+interface FromStorageEventOptions {
+  /**
+   * Storage-event target. Defaults to `globalThis`, which is appropriate for
+   * browser hosts and jsdom-based tests.
+   */
+  target?: StorageEventTarget;
+  /** Callback invoked for each browser `storage` event. */
+  callback: (event: StorageEvent) => void;
+}
+/**
+ * Adapt a browser AbortSignal into the shared Subscription model.
+ */
+declare function fromAbortSignal(options: FromAbortSignalOptions): Subscription;
+/**
+ * Adapt browser `storage` events into the shared Subscription model.
+ */
+declare function fromStorageEvent(options: FromStorageEventOptions): Subscription;
+//#endregion
+//#region src/web/popup.d.ts
+/** Stable error codes for popup-related failures. */
+declare const PopupErrorCode: {
+  /** The browser blocked the popup window from opening. */readonly Blocked: "popup.blocked"; /** The popup was closed by the user before completing the flow. */
+  readonly Closed: "popup.closed_by_user"; /** The relay message was not received within the timeout. */
+  readonly Timeout: "popup.relay_timeout"; /** The relay message contained an error from the callback page. */
+  readonly RelayError: "popup.relay_error"; /** An unexpected error occurred during popup lifecycle. */
+  readonly Internal: "popup.internal";
+};
+type PopupErrorCode = (typeof PopupErrorCode)[keyof typeof PopupErrorCode];
+/**
+ * Options for computing the popup window features string.
+ */
+interface PopupFeaturesOptions {
+  /** Width in pixels (default: 500). */
+  width?: number;
+  /** Height in pixels (default: 600). */
+  height?: number;
+}
+/**
+ * Compute the `features` string for `window.open()`, centered on screen.
+ */
+declare function computePopupFeatures(options?: PopupFeaturesOptions): string;
+/**
+ * Result of opening a popup window.
+ */
+interface PopupWindowHandle {
+  /** The opened window reference. */
+  window: Window;
+}
+/**
+ * Open a popup window to the given URL.
+ *
+ * Throws a `ClientError` with code `popup.blocked` if the browser
+ * blocks the popup.
+ */
+declare function openPopupWindow(url: string, options?: PopupFeaturesOptions & {
+  target?: string;
+}): PopupWindowHandle;
+/**
+ * Expected shape of a relay message from the popup callback page.
+ */
+interface PopupRelayMessage {
+  /** Discriminator for the message type. */
+  type: "securitydept:popup_callback";
+  /** The callback URL or fragment received by the popup. */
+  payload: string;
+  /** Optional error from the callback page. */
+  error?: string;
+}
+/**
+ * Options for waiting for a popup relay message.
+ */
+interface WaitForPopupRelayOptions {
+  /** The popup window handle to monitor. */
+  popup: PopupWindowHandle;
+  /** Maximum time to wait in milliseconds (default: 120000 = 2 minutes). */
+  timeoutMs?: number;
+  /** Expected origin for the relay message (default: current origin). */
+  expectedOrigin?: string;
+  /** Poll interval for checking if the popup is closed (default: 500ms). */
+  pollIntervalMs?: number;
+}
+/**
+ * Wait for a relay message from a popup callback page.
+ *
+ * The popup callback page should call `relayPopupCallback()` to post
+ * the callback URL back to the opener.
+ *
+ * Resolves with the callback payload (URL or fragment string).
+ * Rejects with a `ClientError` if:
+ *   - the popup is closed without relaying (popup.closed_by_user)
+ *   - the timeout expires (popup.relay_timeout)
+ *   - the relay message contains an error (popup.relay_error)
+ */
+declare function waitForPopupRelay(options: WaitForPopupRelayOptions): Promise<string>;
+/**
+ * Options for relaying the callback from the popup window back to the opener.
+ */
+interface RelayPopupCallbackOptions {
+  /** The callback payload (URL or fragment) to relay. */
+  payload?: string;
+  /** An error message to relay instead of a successful payload. */
+  error?: string;
+  /** Whether to close the popup after relaying (default: true). */
+  closeAfterRelay?: boolean;
+  /** Target origin for the postMessage (default: current origin). */
+  targetOrigin?: string;
+}
+/**
+ * Relay the popup callback result back to the opener window.
+ *
+ * Call this function from the popup callback page to send the callback
+ * URL/fragment back to the parent window that initiated the popup login.
+ *
+ * @example
+ * ```html
+ * <script type="module">
+ *   import { relayPopupCallback } from "@securitydept/client/web";
+ *   relayPopupCallback({ payload: window.location.href });
+ * </script>
+ * ```
+ */
+declare function relayPopupCallback(options?: RelayPopupCallbackOptions): void;
+//#endregion
+//#region src/web/runtime.d.ts
+interface CreateWebRuntimeOptions extends Partial<Omit<ClientRuntime, "transport">> {
+  transport?: ClientRuntime["transport"];
+  fetchTransport?: FetchTransportOptions;
+}
+/**
+ * Create a `ClientRuntime` for browser/Web-capable environments.
+ */
+declare function createWebRuntime(overrides?: CreateWebRuntimeOptions): ClientRuntime;
+//#endregion
+//#region src/web/visibility.d.ts
+/** Visibility state snapshot passed to the callback. */
+declare const VisibilityState: {
+  readonly Visible: "visible";
+  readonly Hidden: "hidden";
+};
+type VisibilityState = (typeof VisibilityState)[keyof typeof VisibilityState];
+/** Options for {@link fromVisibilityChange}. */
+interface FromVisibilityChangeOptions {
+  /**
+   * Callback invoked when the document visibility state changes.
+   *
+   * The callback receives the new visibility state ("visible" or "hidden").
+   */
+  callback: (state: VisibilityState) => void;
+  /**
+   * Override the document target (primarily for testing).
+   * Defaults to `globalThis.document`.
+   */
+  document?: Pick<Document, "addEventListener" | "removeEventListener" | "visibilityState">;
+}
+/**
+ * Subscribe to browser document visibility changes.
+ *
+ * Built on {@link fromEventPattern} so it follows the same Subscription
+ * contract. Returns a {@link Subscription} handle for cleanup.
+ *
+ * @example
+ * ```ts
+ * const sub = fromVisibilityChange({
+ *   callback: (state) => {
+ *     if (state === VisibilityState.Visible) {
+ *       scheduleRefresh();
+ *     }
+ *   },
+ * });
+ * // Cleanup:
+ * sub.unsubscribe();
+ * ```
+ */
+declare function fromVisibilityChange(options: FromVisibilityChangeOptions): Subscription;
+//#endregion
+//#region src/web/visibility-reconciler.d.ts
+/** Callback invoked when the page becomes visible and reconciliation is needed. */
+type ReconcileCallback = () => void | Promise<void>;
+/** Options for {@link createVisibilityReconciler}. */
+interface CreateVisibilityReconcilerOptions {
+  /**
+   * Called when the document transitions from hidden → visible.
+   * The reconciler only fires on the hidden→visible edge; repeated
+   * visible→visible events are suppressed.
+   */
+  onReconcile: ReconcileCallback;
+  /**
+   * Minimum interval (ms) between reconciliation triggers.
+   * Prevents rapid-fire reconciliation when the user toggles tabs quickly.
+   * Defaults to 5000ms (5 seconds).
+   */
+  throttleMs?: number;
+  /**
+   * Override the document target (primarily for testing).
+   * Defaults to `globalThis.document`.
+   */
+  document?: FromVisibilityChangeOptions["document"];
+  /**
+   * Clock override for testing.
+   */
+  now?: () => number;
+}
+/** Handle returned by {@link createVisibilityReconciler}. */
+interface VisibilityReconciler {
+  /** Stop listening for visibility changes. */
+  dispose(): void;
+  /** Number of times reconciliation has been triggered. */
+  readonly reconcileCount: number;
+}
+/**
+ * Create a visibility reconciler that triggers a callback when the page
+ * transitions from hidden → visible.
+ *
+ * @example
+ * ```ts
+ * const reconciler = createVisibilityReconciler({
+ *   onReconcile: () => {
+ *     // Re-check token freshness or sync cross-tab state
+ *     if (controller.snapshot?.tokens.accessTokenExpiresAt) {
+ *       scheduleRefreshIfExpired();
+ *     }
+ *   },
+ * });
+ * // Later:
+ * reconciler.dispose();
+ * ```
+ */
+declare function createVisibilityReconciler(options: CreateVisibilityReconcilerOptions): VisibilityReconciler;
+//#endregion
+export { type AbortSignalBridge, type CreateCrossTabSyncOptions, type CreateVisibilityReconcilerOptions, type CreateWebRuntimeOptions, type CrossTabSync, type CrossTabSyncCallback, type FetchTransportOptions, FetchTransportRedirectKind, type FromAbortSignalOptions, type FromStorageEventOptions, type FromVisibilityChangeOptions, PopupErrorCode, type PopupFeaturesOptions, type PopupRelayMessage, type PopupWindowHandle, type ReconcileCallback, type RelayPopupCallbackOptions, type VisibilityReconciler, VisibilityState, type WaitForPopupRelayOptions, computePopupFeatures, createAbortSignalBridge, createCancellationTokenFromAbortSignal, createCrossTabSync, createFetchTransport, createVisibilityReconciler, createWebRuntime, fromAbortSignal, fromStorageEvent, fromVisibilityChange, normalizeAbortError, openPopupWindow, relayPopupCallback, waitForPopupRelay };
+//# sourceMappingURL=index.d.mts.map