@nexartis/sentinel-sdk 1.6.0

package/dist/core/types.d.ts

@@ -0,0 +1,269 @@
+import type { SentinelLogger } from './logger.js';
+export interface SentinelConfig {
+    apiUrl: string;
+    baseUrl: string;
+    /**
+     * When true, validateToken() performs a second GET /users/me request after
+     * POST /auth/validate to refresh DB-backed profile fields such as roles.
+     * Default: false. Keep disabled for high-volume per-request validation paths.
+     */
+    hydrateUserProfile?: boolean;
+    /**
+     * Timeout in milliseconds for each individual fetch call to the Sentinel API.
+     * Default: 8000 (8 seconds).
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum number of retries for retryable errors (network timeout, HTTP 502/503/504).
+     * Non-retryable errors (400, 401, 403) are never retried.
+     * Default: 1.
+     */
+    maxRetries?: number;
+    /** Optional structured logger. Falls back to console if not provided. */
+    logger?: SentinelLogger;
+}
+/** Base fields shared by all Sentinel API responses. */
+export interface SentinelResponseBase {
+    success?: boolean;
+    code?: number;
+    message?: string;
+    error?: string;
+}
+/** Response from POST /auth/login-passwordless */
+export interface StartLoginResponse extends SentinelResponseBase {
+    transactionId?: string;
+    clientToken?: string;
+}
+/** Response from POST /auth/poll */
+export interface PollResponse extends SentinelResponseBase {
+    status?: 'pending' | 'completed' | 'expired';
+}
+/** Response from POST /auth/claim */
+export interface ClaimResponse extends SentinelResponseBase {
+    access_token?: string;
+    refresh_token?: string;
+}
+/** Response from POST /auth/refresh */
+export interface RefreshResponse extends SentinelResponseBase {
+    access_token?: string;
+    refresh_token?: string;
+}
+/** Response from POST /auth/validate */
+export interface ValidateResponse extends SentinelResponseBase {
+    valid?: boolean;
+    payload?: DecodedToken;
+    user?: {
+        sub: string;
+        email: string;
+        roles: string[];
+    };
+}
+/** Response from GET /users/me. */
+export interface CurrentUserResponse extends SentinelResponseBase {
+    id?: string;
+    email?: string;
+    role?: string;
+    roles?: string[];
+    status?: string;
+    legalName?: string;
+    ocmeMemberNumber?: string;
+    walletAddress?: string;
+    aliasName?: string;
+    twitterAccount?: string;
+    youtubeAccount?: string;
+    cubicubeAddress?: string;
+}
+/** Response from POST /auth/register */
+export interface RegisterResponse extends SentinelResponseBase {
+}
+/** Response from POST /auth/verify */
+export interface VerifyResponse extends SentinelResponseBase {
+    access_token?: string;
+    refresh_token?: string;
+}
+/** Response from POST /auth/complete-passwordless */
+export interface CompletePasswordlessResponse extends SentinelResponseBase {
+    access_token?: string;
+    refresh_token?: string;
+}
+/**
+ * @deprecated Use the specific typed response interfaces instead.
+ * Kept for backward compatibility — will be removed in v2.0.0.
+ */
+export interface SentinelResponse {
+    success?: boolean;
+    code?: number;
+    message?: string;
+    error?: string;
+    [key: string]: unknown;
+}
+export interface DecodedToken {
+    sub: string;
+    email: string;
+    roles: string[];
+    exp: number;
+    iat: number;
+}
+export interface UserLocals {
+    isAuthenticated: boolean;
+    id: string;
+    email: string;
+    roles: string[];
+}
+export interface SentinelHandleOptions {
+    protectedRoutes?: string[];
+    loginRedirect?: string;
+    apiUrl?: string;
+    baseUrl?: string;
+    /** Optional structured logger for auth middleware. */
+    logger?: SentinelLogger;
+}
+/** Data passed to the onBeforeLogin hook. */
+export interface BeforeLoginContext {
+    email: string;
+    rememberMe: boolean;
+    redirectTo?: string;
+}
+/**
+ * Return this from onBeforeLogin to reject the request.
+ *
+ * When `redirect` is set and is a safe relative path (starts with `/`, no
+ * protocol, no `//` / `\\` prefix), the SDK issues a `303 See Other` to that
+ * path instead of returning the JSON error body. Unsafe redirects are ignored
+ * and the JSON-reject path is used as a fallback.
+ *
+ * @example
+ * ```ts
+ * onBeforeLogin: async (_event, { email }) => {
+ *   const gate = await isLoginAllowed(email);
+ *   if (!gate.ok) {
+ *     return {
+ *       error: gate.reason,
+ *       status: 403,
+ *       redirect: gate.reason === 'waitlisted' ? '/waitlist' : '/unauthorized'
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface BeforeLoginReject {
+    error: string;
+    status?: number;
+    /**
+     * Optional branded destination the SDK will 303-redirect to instead of
+     * returning a JSON error. Must be a safe relative path (starts with `/`,
+     * no protocol, no `//` / `\\` prefix). Unsafe values fall back to the
+     * JSON-reject behaviour.
+     */
+    redirect?: string;
+}
+/** Data passed to the onAfterLogin hook. */
+export interface AfterLoginContext {
+    email: string;
+    transactionId: string;
+}
+/** Data passed to the onAfterClaim hook. */
+export interface AfterClaimContext {
+    accessToken: string;
+    refreshToken: string;
+    redirectTo?: string;
+}
+/** Data passed to the onError hook. */
+export interface ErrorContext {
+    handler: 'start-login' | 'poll' | 'claim' | 'logout' | 'refresh' | 'register' | 'verify';
+    error: unknown;
+}
+/**
+ * Context passed to the `resolveRedirect` hook after a successful token claim.
+ * Hosts use this to pick a post-login destination based on the user's roles,
+ * a requested redirect, or fall back to the configured default.
+ */
+export interface ResolveRedirectContext {
+    /** Newly authenticated user, decoded from the access token. */
+    user: UserLocals;
+    /** Access token just issued for this user. */
+    accessToken: string;
+    /** Whether the user opted into a longer session at login time. */
+    rememberMe: boolean;
+    /**
+     * The redirect the client originally requested (from the `login_redirect_to`
+     * cookie, `?redirect=` on `/auth`, or the `redirectTo` body field).
+     * Already sanitised to a safe relative path by the SDK.
+     */
+    requestedRedirect?: string;
+    /** The redirect that would be used if the resolver is absent. Always safe. */
+    defaultRedirect: string;
+}
+/**
+ * Context passed to the `logoutRedirect` function form, if the host wants to
+ * decide the post-logout landing at request time (e.g. send authenticated
+ * users to `/` and anonymous users to `/auth`).
+ */
+export interface LogoutRedirectContext {
+    /** User present when logout was invoked, if any (may be null for stale sessions). */
+    user: UserLocals | null;
+}
+export interface AuthHandlerOptions {
+    /**
+     * Login cookie TTL in seconds. Controls how long the login transaction
+     * cookies (transaction ID, client token, remember-me) persist.
+     * Default: 300 (5 minutes).
+     */
+    loginCookieTtlSeconds?: number;
+    /**
+     * Path to redirect unauthenticated users (logout, claim errors).
+     * Default: '/auth'.
+     */
+    loginRedirect?: string;
+    /**
+     * Store a `login_redirect_to` cookie from the request body's `redirectTo`
+     * field, then use it on claim to redirect the user back to their original page.
+     * Default: true.
+     */
+    redirectCookie?: boolean;
+    /** Optional structured logger for auth handlers. */
+    logger?: SentinelLogger;
+    /**
+     * Runs before the startLogin API call.
+     * Return `{ error, status? }` to reject the request.
+     */
+    onBeforeLogin?: (event: import('@sveltejs/kit').RequestEvent, ctx: BeforeLoginContext) => Promise<BeforeLoginReject | void> | BeforeLoginReject | void;
+    /** Runs after a successful startLogin (transaction cookies set). */
+    onAfterLogin?: (event: import('@sveltejs/kit').RequestEvent, ctx: AfterLoginContext) => Promise<void> | void;
+    /** Runs after successful token claim (session cookies set). */
+    onAfterClaim?: (event: import('@sveltejs/kit').RequestEvent, ctx: AfterClaimContext) => Promise<void> | void;
+    /** Runs on any handler error. */
+    onError?: (event: import('@sveltejs/kit').RequestEvent, ctx: ErrorContext) => Promise<void> | void;
+    /**
+     * Called after a successful token claim to decide the post-login destination.
+     * Return a safe relative path (starts with `/`, no protocol, no `//` prefix).
+     * If the resolver throws, returns a non-string, an empty string, or an unsafe
+     * path, the SDK falls back to `ctx.defaultRedirect`.
+     *
+     * @example
+     * ```ts
+     * resolveRedirect: async ({ user, requestedRedirect, defaultRedirect }) => {
+     *   if (user.roles.includes('admin')) return '/admin';
+     *   return requestedRedirect || defaultRedirect;
+     * }
+     * ```
+     */
+    resolveRedirect?: (event: import('@sveltejs/kit').RequestEvent, ctx: ResolveRedirectContext) => Promise<string> | string;
+    /**
+     * Where `POST /logout` and `GET /logout` redirect after clearing cookies.
+     *
+     * - Omitted: falls back to `loginRedirect` (current behaviour, `/auth` by default).
+     * - String: treated as a literal safe relative path. Unsafe values fall back to `loginRedirect`.
+     * - Function: called with the pre-logout user context; return a safe relative
+     *   path (async permitted). Throws / empty / unsafe → falls back to `loginRedirect`.
+     *
+     * @example
+     * ```ts
+     * logoutRedirect: '/'
+     * // or
+     * logoutRedirect: ({ user }) => user ? '/' : '/auth'
+     * ```
+     */
+    logoutRedirect?: string | ((event: import('@sveltejs/kit').RequestEvent, ctx: LogoutRedirectContext) => Promise<string> | string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

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

package/dist/core/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"","sourcesContent":["// src/core/types.ts\nimport type { SentinelLogger } from './logger.js';\n\n// ---------------------------------------------------------------------------\n// Config\n// ---------------------------------------------------------------------------\n\nexport interface SentinelConfig {\n\tapiUrl: string;\n\tbaseUrl: string;\n\t/**\n\t * When true, validateToken() performs a second GET /users/me request after\n\t * POST /auth/validate to refresh DB-backed profile fields such as roles.\n\t * Default: false. Keep disabled for high-volume per-request validation paths.\n\t */\n\thydrateUserProfile?: boolean;\n\t/**\n\t * Timeout in milliseconds for each individual fetch call to the Sentinel API.\n\t * Default: 8000 (8 seconds).\n\t */\n\ttimeoutMs?: number;\n\t/**\n\t * Maximum number of retries for retryable errors (network timeout, HTTP 502/503/504).\n\t * Non-retryable errors (400, 401, 403) are never retried.\n\t * Default: 1.\n\t */\n\tmaxRetries?: number;\n\t/** Optional structured logger. Falls back to console if not provided. */\n\tlogger?: SentinelLogger;\n}\n\n// ---------------------------------------------------------------------------\n// Typed API Responses  (replaces the old untyped SentinelResponse bag)\n// ---------------------------------------------------------------------------\n\n/** Base fields shared by all Sentinel API responses. */\nexport interface SentinelResponseBase {\n\tsuccess?: boolean;\n\tcode?: number;\n\tmessage?: string;\n\terror?: string;\n}\n\n/** Response from POST /auth/login-passwordless */\nexport interface StartLoginResponse extends SentinelResponseBase {\n\ttransactionId?: string;\n\tclientToken?: string;\n}\n\n/** Response from POST /auth/poll */\nexport interface PollResponse extends SentinelResponseBase {\n\tstatus?: 'pending' | 'completed' | 'expired';\n}\n\n/** Response from POST /auth/claim */\nexport interface ClaimResponse extends SentinelResponseBase {\n\taccess_token?: string;\n\trefresh_token?: string;\n}\n\n/** Response from POST /auth/refresh */\nexport interface RefreshResponse extends SentinelResponseBase {\n\taccess_token?: string;\n\trefresh_token?: string;\n}\n\n/** Response from POST /auth/validate */\nexport interface ValidateResponse extends SentinelResponseBase {\n\tvalid?: boolean;\n\tpayload?: DecodedToken;\n\tuser?: {\n\t\tsub: string;\n\t\temail: string;\n\t\troles: string[];\n\t};\n}\n\n/** Response from GET /users/me. */\nexport interface CurrentUserResponse extends SentinelResponseBase {\n\tid?: string;\n\temail?: string;\n\trole?: string;\n\troles?: string[];\n\tstatus?: string;\n\tlegalName?: string;\n\tocmeMemberNumber?: string;\n\twalletAddress?: string;\n\taliasName?: string;\n\ttwitterAccount?: string;\n\tyoutubeAccount?: string;\n\tcubicubeAddress?: string;\n}\n\n/** Response from POST /auth/register */\nexport interface RegisterResponse extends SentinelResponseBase {}\n\n/** Response from POST /auth/verify */\nexport interface VerifyResponse extends SentinelResponseBase {\n\taccess_token?: string;\n\trefresh_token?: string;\n}\n\n/** Response from POST /auth/complete-passwordless */\nexport interface CompletePasswordlessResponse extends SentinelResponseBase {\n\taccess_token?: string;\n\trefresh_token?: string;\n}\n\n/**\n * @deprecated Use the specific typed response interfaces instead.\n * Kept for backward compatibility — will be removed in v2.0.0.\n */\nexport interface SentinelResponse {\n\tsuccess?: boolean;\n\tcode?: number;\n\tmessage?: string;\n\terror?: string;\n\t[key: string]: unknown;\n}\n\n// ---------------------------------------------------------------------------\n// JWT / Auth\n// ---------------------------------------------------------------------------\n\nexport interface DecodedToken {\n\tsub: string;\n\temail: string;\n\troles: string[];\n\texp: number;\n\tiat: number;\n}\n\nexport interface UserLocals {\n\tisAuthenticated: boolean;\n\tid: string;\n\temail: string;\n\troles: string[];\n}\n\n// ---------------------------------------------------------------------------\n// SvelteKit Handle Options\n// ---------------------------------------------------------------------------\n\nexport interface SentinelHandleOptions {\n\tprotectedRoutes?: string[];\n\tloginRedirect?: string;\n\tapiUrl?: string;\n\tbaseUrl?: string;\n\t/** Optional structured logger for auth middleware. */\n\tlogger?: SentinelLogger;\n}\n\n// ---------------------------------------------------------------------------\n// Auth Handler Options & Lifecycle Hooks\n// ---------------------------------------------------------------------------\n\n/** Data passed to the onBeforeLogin hook. */\nexport interface BeforeLoginContext {\n\temail: string;\n\trememberMe: boolean;\n\tredirectTo?: string;\n}\n\n/**\n * Return this from onBeforeLogin to reject the request.\n *\n * When `redirect` is set and is a safe relative path (starts with `/`, no\n * protocol, no `//` / `\\\\` prefix), the SDK issues a `303 See Other` to that\n * path instead of returning the JSON error body. Unsafe redirects are ignored\n * and the JSON-reject path is used as a fallback.\n *\n * @example\n * ```ts\n * onBeforeLogin: async (_event, { email }) => {\n *   const gate = await isLoginAllowed(email);\n *   if (!gate.ok) {\n *     return {\n *       error: gate.reason,\n *       status: 403,\n *       redirect: gate.reason === 'waitlisted' ? '/waitlist' : '/unauthorized'\n *     };\n *   }\n * }\n * ```\n */\nexport interface BeforeLoginReject {\n\terror: string;\n\tstatus?: number;\n\t/**\n\t * Optional branded destination the SDK will 303-redirect to instead of\n\t * returning a JSON error. Must be a safe relative path (starts with `/`,\n\t * no protocol, no `//` / `\\\\` prefix). Unsafe values fall back to the\n\t * JSON-reject behaviour.\n\t */\n\tredirect?: string;\n}\n\n/** Data passed to the onAfterLogin hook. */\nexport interface AfterLoginContext {\n\temail: string;\n\ttransactionId: string;\n}\n\n/** Data passed to the onAfterClaim hook. */\nexport interface AfterClaimContext {\n\taccessToken: string;\n\trefreshToken: string;\n\tredirectTo?: string;\n}\n\n/** Data passed to the onError hook. */\nexport interface ErrorContext {\n\thandler: 'start-login' | 'poll' | 'claim' | 'logout' | 'refresh' | 'register' | 'verify';\n\terror: unknown;\n}\n\n/**\n * Context passed to the `resolveRedirect` hook after a successful token claim.\n * Hosts use this to pick a post-login destination based on the user's roles,\n * a requested redirect, or fall back to the configured default.\n */\nexport interface ResolveRedirectContext {\n\t/** Newly authenticated user, decoded from the access token. */\n\tuser: UserLocals;\n\t/** Access token just issued for this user. */\n\taccessToken: string;\n\t/** Whether the user opted into a longer session at login time. */\n\trememberMe: boolean;\n\t/**\n\t * The redirect the client originally requested (from the `login_redirect_to`\n\t * cookie, `?redirect=` on `/auth`, or the `redirectTo` body field).\n\t * Already sanitised to a safe relative path by the SDK.\n\t */\n\trequestedRedirect?: string;\n\t/** The redirect that would be used if the resolver is absent. Always safe. */\n\tdefaultRedirect: string;\n}\n\n/**\n * Context passed to the `logoutRedirect` function form, if the host wants to\n * decide the post-logout landing at request time (e.g. send authenticated\n * users to `/` and anonymous users to `/auth`).\n */\nexport interface LogoutRedirectContext {\n\t/** User present when logout was invoked, if any (may be null for stale sessions). */\n\tuser: UserLocals | null;\n}\n\nexport interface AuthHandlerOptions {\n\t/**\n\t * Login cookie TTL in seconds. Controls how long the login transaction\n\t * cookies (transaction ID, client token, remember-me) persist.\n\t * Default: 300 (5 minutes).\n\t */\n\tloginCookieTtlSeconds?: number;\n\n\t/**\n\t * Path to redirect unauthenticated users (logout, claim errors).\n\t * Default: '/auth'.\n\t */\n\tloginRedirect?: string;\n\n\t/**\n\t * Store a `login_redirect_to` cookie from the request body's `redirectTo`\n\t * field, then use it on claim to redirect the user back to their original page.\n\t * Default: true.\n\t */\n\tredirectCookie?: boolean;\n\n\t/** Optional structured logger for auth handlers. */\n\tlogger?: SentinelLogger;\n\n\t/**\n\t * Runs before the startLogin API call.\n\t * Return `{ error, status? }` to reject the request.\n\t */\n\tonBeforeLogin?: (event: import('@sveltejs/kit').RequestEvent, ctx: BeforeLoginContext) => Promise<BeforeLoginReject | void> | BeforeLoginReject | void;\n\n\t/** Runs after a successful startLogin (transaction cookies set). */\n\tonAfterLogin?: (event: import('@sveltejs/kit').RequestEvent, ctx: AfterLoginContext) => Promise<void> | void;\n\n\t/** Runs after successful token claim (session cookies set). */\n\tonAfterClaim?: (event: import('@sveltejs/kit').RequestEvent, ctx: AfterClaimContext) => Promise<void> | void;\n\n\t/** Runs on any handler error. */\n\tonError?: (event: import('@sveltejs/kit').RequestEvent, ctx: ErrorContext) => Promise<void> | void;\n\n\t/**\n\t * Called after a successful token claim to decide the post-login destination.\n\t * Return a safe relative path (starts with `/`, no protocol, no `//` prefix).\n\t * If the resolver throws, returns a non-string, an empty string, or an unsafe\n\t * path, the SDK falls back to `ctx.defaultRedirect`.\n\t *\n\t * @example\n\t * ```ts\n\t * resolveRedirect: async ({ user, requestedRedirect, defaultRedirect }) => {\n\t *   if (user.roles.includes('admin')) return '/admin';\n\t *   return requestedRedirect || defaultRedirect;\n\t * }\n\t * ```\n\t */\n\tresolveRedirect?: (\n\t\tevent: import('@sveltejs/kit').RequestEvent,\n\t\tctx: ResolveRedirectContext\n\t) => Promise<string> | string;\n\n\t/**\n\t * Where `POST /logout` and `GET /logout` redirect after clearing cookies.\n\t *\n\t * - Omitted: falls back to `loginRedirect` (current behaviour, `/auth` by default).\n\t * - String: treated as a literal safe relative path. Unsafe values fall back to `loginRedirect`.\n\t * - Function: called with the pre-logout user context; return a safe relative\n\t *   path (async permitted). Throws / empty / unsafe → falls back to `loginRedirect`.\n\t *\n\t * @example\n\t * ```ts\n\t * logoutRedirect: '/'\n\t * // or\n\t * logoutRedirect: ({ user }) => user ? '/' : '/auth'\n\t * ```\n\t */\n\tlogoutRedirect?:\n\t\t| string\n\t\t| ((\n\t\t\t\tevent: import('@sveltejs/kit').RequestEvent,\n\t\t\t\tctx: LogoutRedirectContext\n\t\t  ) => Promise<string> | string);\n}\n"]}

package/dist/sveltekit/client/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Extended options for {@link authFetch} / {@link authFetchJson}.
+ *
+ * Adds a per-attempt request timeout on top of the standard `RequestInit`.
+ * The timeout is applied INDEPENDENTLY to the initial request and to the
+ * post-401-refresh retry, so a slow first attempt does not steal budget from
+ * the retry.
+ */
+export interface AuthFetchOptions extends RequestInit {
+    /**
+     * Per-attempt timeout in milliseconds.
+     *
+     * - Defaults to `60_000` (60 s) when omitted.
+     * - `0` or `Infinity` disables the internal timeout entirely (caller's
+     *   own `signal` still applies).
+     * - The timeout is applied SEPARATELY to attempt #1 and to the post-401
+     *   refresh retry — each gets a fresh budget.
+     * - Composed with `options.signal` via `AbortSignal.any([...])` so caller
+     *   cancellation still works and a tighter caller signal wins.
+     * - Does NOT apply to the internal `/api/auth/refresh` sub-call.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Authenticated fetch wrapper with automatic token refresh.
+ *
+ * Applies a per-attempt timeout (default 60 s) to attempt #1 and to the
+ * post-401-refresh retry. Each attempt gets its OWN fresh timeout budget so
+ * a slow first attempt cannot starve the retry. See {@link AuthFetchOptions}.
+ */
+export declare function authFetch(url: string | URL, options?: AuthFetchOptions): Promise<Response>;
+/**
+ * Authenticated fetch wrapper with JSON response parsing
+ */
+export declare function authFetchJson<T = any>(url: string | URL, options?: AuthFetchOptions): Promise<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/sveltekit/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sveltekit/client/index.ts"],"names":[],"mappings":"AAkDA;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACpD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAgCD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC9B,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,OAAO,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,QAAQ,CAAC,CAqCnB;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,CAAC,GAAG,GAAG,EAC1C,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,OAAO,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,CAAC,CAAC,CAQZ"}

package/dist/sveltekit/client/index.js

@@ -0,0 +1,121 @@
+// src/sveltekit/client/index.ts
+/**
+ * Authenticated fetch wrapper with automatic token refresh.
+ *
+ * Use for:
+ * - Multipart/chunked file uploads
+ * - Sequential API calls with delays
+ * - Any scenario where token might expire between requests
+ */
+let isRefreshing = false;
+let refreshPromise = null;
+async function refreshAccessToken() {
+    if (isRefreshing && refreshPromise) {
+        return refreshPromise;
+    }
+    isRefreshing = true;
+    refreshPromise = (async () => {
+        try {
+            // The refresh sub-call is intentionally NOT wrapped in the caller's
+            // timeoutMs. It has its own well-behaved backend contract and we do
+            // not want a mid-refresh abort to leave the client with partially
+            // rotated tokens. If refresh itself hangs pathologically the
+            // browser/network stack will eventually fail it.
+            const response = await fetch('/api/auth/refresh', {
+                method: 'POST',
+                credentials: 'include'
+            });
+            if (response.ok) {
+                const result = await response.json();
+                return result.success === true;
+            }
+            return false;
+        }
+        catch (error) {
+            console.error('Token refresh error:', error);
+            return false;
+        }
+        finally {
+            isRefreshing = false;
+            refreshPromise = null;
+        }
+    })();
+    return refreshPromise;
+}
+/** Default per-attempt timeout when `timeoutMs` is not provided. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * Build the effective per-attempt AbortSignal for a single fetch attempt.
+ *
+ * - When `timeoutMs` disables the timeout, we pass through the caller signal
+ *   (or `undefined`).
+ * - When timeout is enabled and the caller supplied a signal, we compose them
+ *   with `AbortSignal.any` so whichever aborts first wins.
+ *
+ * Node engine is >=20 so `AbortSignal.any` / `AbortSignal.timeout` are
+ * available; modern browsers (Chrome 116+, Firefox 124+, Safari 17.4+)
+ * also ship them.
+ */
+function buildAttemptSignal(callerSignal, timeoutMs) {
+    const timeoutDisabled = timeoutMs === 0 || !Number.isFinite(timeoutMs);
+    if (timeoutDisabled) {
+        return callerSignal ?? undefined;
+    }
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    if (!callerSignal) {
+        return timeoutSignal;
+    }
+    return AbortSignal.any([callerSignal, timeoutSignal]);
+}
+/**
+ * Authenticated fetch wrapper with automatic token refresh.
+ *
+ * Applies a per-attempt timeout (default 60 s) to attempt #1 and to the
+ * post-401-refresh retry. Each attempt gets its OWN fresh timeout budget so
+ * a slow first attempt cannot starve the retry. See {@link AuthFetchOptions}.
+ */
+export async function authFetch(url, options) {
+    const { timeoutMs, signal: callerSignal, ...restOptions } = options ?? {};
+    const effectiveTimeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // Attempt #1 — fresh timeout budget composed with caller signal.
+    let response = await fetch(url, {
+        ...restOptions,
+        credentials: 'include',
+        signal: buildAttemptSignal(callerSignal, effectiveTimeout)
+    });
+    if (response.status === 401) {
+        const refreshed = await refreshAccessToken();
+        if (refreshed) {
+            // Attempt #2 — brand new timeout budget. Do NOT reuse attempt #1's
+            // signal (that budget may already be nearly exhausted); build a
+            // fresh one instead. The caller's signal is still honored via
+            // AbortSignal.any so external cancellation continues to work.
+            response = await fetch(url, {
+                ...restOptions,
+                credentials: 'include',
+                signal: buildAttemptSignal(callerSignal, effectiveTimeout)
+            });
+        }
+        // If refresh failed, do NOT hard-redirect to /auth.
+        // With Sentinel's rotating refresh tokens, concurrent requests can
+        // race: one wins the refresh (R1→R2) while the others fail because
+        // R1 is already invalidated. A hard redirect would log the user out
+        // even though the browser already has fresh cookies from the winning
+        // response. Instead, return the original 401 response and let the
+        // caller handle it — polling callers will silently retry on the next
+        // interval with the updated cookies, and SvelteKit's protected-route
+        // redirect handles truly expired sessions.
+    }
+    return response;
+}
+/**
+ * Authenticated fetch wrapper with JSON response parsing
+ */
+export async function authFetchJson(url, options) {
+    const response = await authFetch(url, options);
+    if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+    }
+    return response.json();
+}
+//# sourceMappingURL=index.js.map

package/dist/sveltekit/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sveltekit/client/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAEhC;;;;;;;GAOG;AAEH,IAAI,YAAY,GAAG,KAAK,CAAC;AACzB,IAAI,cAAc,GAA4B,IAAI,CAAC;AAEnD,KAAK,UAAU,kBAAkB;IAChC,IAAI,YAAY,IAAI,cAAc,EAAE,CAAC;QACpC,OAAO,cAAc,CAAC;IACvB,CAAC;IAED,YAAY,GAAG,IAAI,CAAC;IACpB,cAAc,GAAG,CAAC,KAAK,IAAI,EAAE;QAC5B,IAAI,CAAC;YACJ,oEAAoE;YACpE,oEAAoE;YACpE,kEAAkE;YAClE,6DAA6D;YAC7D,iDAAiD;YACjD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,mBAAmB,EAAE;gBACjD,MAAM,EAAE,MAAM;gBACd,WAAW,EAAE,SAAS;aACtB,CAAC,CAAC;YAEH,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACrC,OAAO,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;YAChC,CAAC;YAED,OAAO,KAAK,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,KAAK,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;YAC7C,OAAO,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACV,YAAY,GAAG,KAAK,CAAC;YACrB,cAAc,GAAG,IAAI,CAAC;QACvB,CAAC;IACF,CAAC,CAAC,EAAE,CAAC;IAEL,OAAO,cAAc,CAAC;AACvB,CAAC;AA0BD,oEAAoE;AACpE,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,SAAS,kBAAkB,CAC1B,YAA4C,EAC5C,SAAiB;IAEjB,MAAM,eAAe,GAAG,SAAS,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACvE,IAAI,eAAe,EAAE,CAAC;QACrB,OAAO,YAAY,IAAI,SAAS,CAAC;IAClC,CAAC;IACD,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACrD,IAAI,CAAC,YAAY,EAAE,CAAC;QACnB,OAAO,aAAa,CAAC;IACtB,CAAC;IACD,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC9B,GAAiB,EACjB,OAA0B;IAE1B,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,WAAW,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAC1E,MAAM,gBAAgB,GAAG,SAAS,IAAI,kBAAkB,CAAC;IAEzD,iEAAiE;IACjE,IAAI,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC/B,GAAG,WAAW;QACd,WAAW,EAAE,SAAS;QACtB,MAAM,EAAE,kBAAkB,CAAC,YAAY,EAAE,gBAAgB,CAAC;KAC1D,CAAC,CAAC;IAEH,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,MAAM,kBAAkB,EAAE,CAAC;QAE7C,IAAI,SAAS,EAAE,CAAC;YACf,mEAAmE;YACnE,gEAAgE;YAChE,8DAA8D;YAC9D,8DAA8D;YAC9D,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC3B,GAAG,WAAW;gBACd,WAAW,EAAE,SAAS;gBACtB,MAAM,EAAE,kBAAkB,CAAC,YAAY,EAAE,gBAAgB,CAAC;aAC1D,CAAC,CAAC;QACJ,CAAC;QACD,oDAAoD;QACpD,mEAAmE;QACnE,mEAAmE;QACnE,oEAAoE;QACpE,qEAAqE;QACrE,kEAAkE;QAClE,qEAAqE;QACrE,qEAAqE;QACrE,2CAA2C;IAC5C,CAAC;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,GAAiB,EACjB,OAA0B;IAE1B,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAE/C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,uBAAuB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC","sourcesContent":["// src/sveltekit/client/index.ts\n\n/**\n * Authenticated fetch wrapper with automatic token refresh.\n *\n * Use for:\n * - Multipart/chunked file uploads\n * - Sequential API calls with delays\n * - Any scenario where token might expire between requests\n */\n\nlet isRefreshing = false;\nlet refreshPromise: Promise<boolean> | null = null;\n\nasync function refreshAccessToken(): Promise<boolean> {\n\tif (isRefreshing && refreshPromise) {\n\t\treturn refreshPromise;\n\t}\n\n\tisRefreshing = true;\n\trefreshPromise = (async () => {\n\t\ttry {\n\t\t\t// The refresh sub-call is intentionally NOT wrapped in the caller's\n\t\t\t// timeoutMs. It has its own well-behaved backend contract and we do\n\t\t\t// not want a mid-refresh abort to leave the client with partially\n\t\t\t// rotated tokens. If refresh itself hangs pathologically the\n\t\t\t// browser/network stack will eventually fail it.\n\t\t\tconst response = await fetch('/api/auth/refresh', {\n\t\t\t\tmethod: 'POST',\n\t\t\t\tcredentials: 'include'\n\t\t\t});\n\n\t\t\tif (response.ok) {\n\t\t\t\tconst result = await response.json();\n\t\t\t\treturn result.success === true;\n\t\t\t}\n\n\t\t\treturn false;\n\t\t} catch (error) {\n\t\t\tconsole.error('Token refresh error:', error);\n\t\t\treturn false;\n\t\t} finally {\n\t\t\tisRefreshing = false;\n\t\t\trefreshPromise = null;\n\t\t}\n\t})();\n\n\treturn refreshPromise;\n}\n\n/**\n * Extended options for {@link authFetch} / {@link authFetchJson}.\n *\n * Adds a per-attempt request timeout on top of the standard `RequestInit`.\n * The timeout is applied INDEPENDENTLY to the initial request and to the\n * post-401-refresh retry, so a slow first attempt does not steal budget from\n * the retry.\n */\nexport interface AuthFetchOptions extends RequestInit {\n\t/**\n\t * Per-attempt timeout in milliseconds.\n\t *\n\t * - Defaults to `60_000` (60 s) when omitted.\n\t * - `0` or `Infinity` disables the internal timeout entirely (caller's\n\t *   own `signal` still applies).\n\t * - The timeout is applied SEPARATELY to attempt #1 and to the post-401\n\t *   refresh retry — each gets a fresh budget.\n\t * - Composed with `options.signal` via `AbortSignal.any([...])` so caller\n\t *   cancellation still works and a tighter caller signal wins.\n\t * - Does NOT apply to the internal `/api/auth/refresh` sub-call.\n\t */\n\ttimeoutMs?: number;\n}\n\n/** Default per-attempt timeout when `timeoutMs` is not provided. */\nconst DEFAULT_TIMEOUT_MS = 60_000;\n\n/**\n * Build the effective per-attempt AbortSignal for a single fetch attempt.\n *\n * - When `timeoutMs` disables the timeout, we pass through the caller signal\n *   (or `undefined`).\n * - When timeout is enabled and the caller supplied a signal, we compose them\n *   with `AbortSignal.any` so whichever aborts first wins.\n *\n * Node engine is >=20 so `AbortSignal.any` / `AbortSignal.timeout` are\n * available; modern browsers (Chrome 116+, Firefox 124+, Safari 17.4+)\n * also ship them.\n */\nfunction buildAttemptSignal(\n\tcallerSignal: AbortSignal | null | undefined,\n\ttimeoutMs: number\n): AbortSignal | undefined {\n\tconst timeoutDisabled = timeoutMs === 0 || !Number.isFinite(timeoutMs);\n\tif (timeoutDisabled) {\n\t\treturn callerSignal ?? undefined;\n\t}\n\tconst timeoutSignal = AbortSignal.timeout(timeoutMs);\n\tif (!callerSignal) {\n\t\treturn timeoutSignal;\n\t}\n\treturn AbortSignal.any([callerSignal, timeoutSignal]);\n}\n\n/**\n * Authenticated fetch wrapper with automatic token refresh.\n *\n * Applies a per-attempt timeout (default 60 s) to attempt #1 and to the\n * post-401-refresh retry. Each attempt gets its OWN fresh timeout budget so\n * a slow first attempt cannot starve the retry. See {@link AuthFetchOptions}.\n */\nexport async function authFetch(\n\turl: string | URL,\n\toptions?: AuthFetchOptions\n): Promise<Response> {\n\tconst { timeoutMs, signal: callerSignal, ...restOptions } = options ?? {};\n\tconst effectiveTimeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;\n\n\t// Attempt #1 — fresh timeout budget composed with caller signal.\n\tlet response = await fetch(url, {\n\t\t...restOptions,\n\t\tcredentials: 'include',\n\t\tsignal: buildAttemptSignal(callerSignal, effectiveTimeout)\n\t});\n\n\tif (response.status === 401) {\n\t\tconst refreshed = await refreshAccessToken();\n\n\t\tif (refreshed) {\n\t\t\t// Attempt #2 — brand new timeout budget. Do NOT reuse attempt #1's\n\t\t\t// signal (that budget may already be nearly exhausted); build a\n\t\t\t// fresh one instead. The caller's signal is still honored via\n\t\t\t// AbortSignal.any so external cancellation continues to work.\n\t\t\tresponse = await fetch(url, {\n\t\t\t\t...restOptions,\n\t\t\t\tcredentials: 'include',\n\t\t\t\tsignal: buildAttemptSignal(callerSignal, effectiveTimeout)\n\t\t\t});\n\t\t}\n\t\t// If refresh failed, do NOT hard-redirect to /auth.\n\t\t// With Sentinel's rotating refresh tokens, concurrent requests can\n\t\t// race: one wins the refresh (R1→R2) while the others fail because\n\t\t// R1 is already invalidated. A hard redirect would log the user out\n\t\t// even though the browser already has fresh cookies from the winning\n\t\t// response. Instead, return the original 401 response and let the\n\t\t// caller handle it — polling callers will silently retry on the next\n\t\t// interval with the updated cookies, and SvelteKit's protected-route\n\t\t// redirect handles truly expired sessions.\n\t}\n\n\treturn response;\n}\n\n/**\n * Authenticated fetch wrapper with JSON response parsing\n */\nexport async function authFetchJson<T = any>(\n\turl: string | URL,\n\toptions?: AuthFetchOptions\n): Promise<T> {\n\tconst response = await authFetch(url, options);\n\n\tif (!response.ok) {\n\t\tthrow new Error(`HTTP error! status: ${response.status}`);\n\t}\n\n\treturn response.json();\n}\n"]}

package/dist/sveltekit/cookies.d.ts

@@ -0,0 +1,54 @@
+import type { Cookies } from '@sveltejs/kit';
+export declare const COOKIE_NAMES: {
+    readonly ACCESS_TOKEN: "access_token";
+    readonly REFRESH_TOKEN: "refresh_token";
+    readonly VERIFY_ACCESS_TOKEN: "verify_access_token";
+    readonly VERIFY_REFRESH_TOKEN: "verify_refresh_token";
+};
+export declare const COOKIE_OPTIONS: {
+    readonly ACCESS_TOKEN: {
+        readonly path: "/";
+        readonly httpOnly: true;
+        readonly secure: true;
+        readonly sameSite: "lax";
+        readonly maxAge: number;
+    };
+    readonly REFRESH_TOKEN_LONG: {
+        readonly path: "/";
+        readonly httpOnly: true;
+        readonly secure: true;
+        readonly sameSite: "lax";
+        readonly maxAge: number;
+    };
+    readonly REFRESH_TOKEN_SHORT: {
+        readonly path: "/";
+        readonly httpOnly: true;
+        readonly secure: true;
+        readonly sameSite: "lax";
+        readonly maxAge: number;
+    };
+    readonly VERIFY_TOKEN: {
+        readonly path: "/auth";
+        readonly httpOnly: true;
+        readonly secure: true;
+        readonly sameSite: "lax";
+        readonly maxAge: 60;
+    };
+};
+/**
+ * Set session cookies (access + refresh tokens)
+ * @param rememberMe - If true, refresh token lasts 7 days. If false, 2 hours.
+ */
+export declare function setSessionCookies(cookies: Cookies, accessToken: string, refreshToken: string, rememberMe?: boolean): void;
+/**
+ * Get session cookies (access + refresh tokens)
+ */
+export declare function getSessionCookies(cookies: Cookies): {
+    accessToken: string | undefined;
+    refreshToken: string | undefined;
+};
+/**
+ * Clear all authentication cookies
+ */
+export declare function clearAuthCookies(cookies: Cookies): void;
+//# sourceMappingURL=cookies.d.ts.map

package/dist/sveltekit/cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/sveltekit/cookies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BjB,CAAC;AAEX;;;GAGG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,UAAU,GAAE,OAAe,GACzB,IAAI,CAQN;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG;IACpD,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC,CAKA;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAGvD"}

package/dist/sveltekit/cookies.js

@@ -0,0 +1,64 @@
+export const COOKIE_NAMES = {
+    ACCESS_TOKEN: 'access_token',
+    REFRESH_TOKEN: 'refresh_token',
+    VERIFY_ACCESS_TOKEN: 'verify_access_token',
+    VERIFY_REFRESH_TOKEN: 'verify_refresh_token'
+};
+export const COOKIE_OPTIONS = {
+    ACCESS_TOKEN: {
+        path: '/',
+        httpOnly: true,
+        secure: true,
+        sameSite: 'lax',
+        maxAge: 60 * 15 // 15 minutes
+    },
+    REFRESH_TOKEN_LONG: {
+        path: '/',
+        httpOnly: true,
+        secure: true,
+        sameSite: 'lax',
+        maxAge: 60 * 60 * 24 * 7 // 7 days (when "Remember Me" is checked)
+    },
+    REFRESH_TOKEN_SHORT: {
+        path: '/',
+        httpOnly: true,
+        secure: true,
+        sameSite: 'lax',
+        maxAge: 60 * 60 * 2 // 2 hours (when "Remember Me" is NOT checked)
+    },
+    VERIFY_TOKEN: {
+        path: '/auth',
+        httpOnly: true,
+        secure: true,
+        sameSite: 'lax',
+        maxAge: 60 // 1 minute — single-use, consumed immediately by /auth/verified
+    }
+};
+/**
+ * Set session cookies (access + refresh tokens)
+ * @param rememberMe - If true, refresh token lasts 7 days. If false, 2 hours.
+ */
+export function setSessionCookies(cookies, accessToken, refreshToken, rememberMe = false) {
+    cookies.set(COOKIE_NAMES.ACCESS_TOKEN, accessToken, COOKIE_OPTIONS.ACCESS_TOKEN);
+    const refreshTokenOptions = rememberMe
+        ? COOKIE_OPTIONS.REFRESH_TOKEN_LONG
+        : COOKIE_OPTIONS.REFRESH_TOKEN_SHORT;
+    cookies.set(COOKIE_NAMES.REFRESH_TOKEN, refreshToken, refreshTokenOptions);
+}
+/**
+ * Get session cookies (access + refresh tokens)
+ */
+export function getSessionCookies(cookies) {
+    return {
+        accessToken: cookies.get(COOKIE_NAMES.ACCESS_TOKEN),
+        refreshToken: cookies.get(COOKIE_NAMES.REFRESH_TOKEN)
+    };
+}
+/**
+ * Clear all authentication cookies
+ */
+export function clearAuthCookies(cookies) {
+    cookies.delete(COOKIE_NAMES.ACCESS_TOKEN, { path: '/' });
+    cookies.delete(COOKIE_NAMES.REFRESH_TOKEN, { path: '/' });
+}
+//# sourceMappingURL=cookies.js.map

package/dist/sveltekit/cookies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.js","sourceRoot":"","sources":["../../src/sveltekit/cookies.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,YAAY,GAAG;IAC3B,YAAY,EAAE,cAAc;IAC5B,aAAa,EAAE,eAAe;IAC9B,mBAAmB,EAAE,qBAAqB;IAC1C,oBAAoB,EAAE,sBAAsB;CACnC,CAAC;AAEX,MAAM,CAAC,MAAM,cAAc,GAAG;IAC7B,YAAY,EAAE;QACb,IAAI,EAAE,GAAG;QACT,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,KAAc;QACxB,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,aAAa;KAC7B;IACD,kBAAkB,EAAE;QACnB,IAAI,EAAE,GAAG;QACT,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,KAAc;QACxB,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,yCAAyC;KAClE;IACD,mBAAmB,EAAE;QACpB,IAAI,EAAE,GAAG;QACT,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,KAAc;QACxB,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,8CAA8C;KAClE;IACD,YAAY,EAAE;QACb,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,KAAc;QACxB,MAAM,EAAE,EAAE,CAAC,gEAAgE;KAC3E;CACQ,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAChC,OAAgB,EAChB,WAAmB,EACnB,YAAoB,EACpB,aAAsB,KAAK;IAE3B,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,YAAY,EAAE,WAAW,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;IAEjF,MAAM,mBAAmB,GAAG,UAAU;QACrC,CAAC,CAAC,cAAc,CAAC,kBAAkB;QACnC,CAAC,CAAC,cAAc,CAAC,mBAAmB,CAAC;IAEtC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,aAAa,EAAE,YAAY,EAAE,mBAAmB,CAAC,CAAC;AAC5E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAIjD,OAAO;QACN,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,YAAY,CAAC;QACnD,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,aAAa,CAAC;KACrD,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAChD,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;IACzD,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;AAC3D,CAAC","sourcesContent":["// src/sveltekit/cookies.ts\nimport type { Cookies } from '@sveltejs/kit';\n\nexport const COOKIE_NAMES = {\n\tACCESS_TOKEN: 'access_token',\n\tREFRESH_TOKEN: 'refresh_token',\n\tVERIFY_ACCESS_TOKEN: 'verify_access_token',\n\tVERIFY_REFRESH_TOKEN: 'verify_refresh_token'\n} as const;\n\nexport const COOKIE_OPTIONS = {\n\tACCESS_TOKEN: {\n\t\tpath: '/',\n\t\thttpOnly: true,\n\t\tsecure: true,\n\t\tsameSite: 'lax' as const,\n\t\tmaxAge: 60 * 15 // 15 minutes\n\t},\n\tREFRESH_TOKEN_LONG: {\n\t\tpath: '/',\n\t\thttpOnly: true,\n\t\tsecure: true,\n\t\tsameSite: 'lax' as const,\n\t\tmaxAge: 60 * 60 * 24 * 7 // 7 days (when \"Remember Me\" is checked)\n\t},\n\tREFRESH_TOKEN_SHORT: {\n\t\tpath: '/',\n\t\thttpOnly: true,\n\t\tsecure: true,\n\t\tsameSite: 'lax' as const,\n\t\tmaxAge: 60 * 60 * 2 // 2 hours (when \"Remember Me\" is NOT checked)\n\t},\n\tVERIFY_TOKEN: {\n\t\tpath: '/auth',\n\t\thttpOnly: true,\n\t\tsecure: true,\n\t\tsameSite: 'lax' as const,\n\t\tmaxAge: 60 // 1 minute — single-use, consumed immediately by /auth/verified\n\t}\n} as const;\n\n/**\n * Set session cookies (access + refresh tokens)\n * @param rememberMe - If true, refresh token lasts 7 days. If false, 2 hours.\n */\nexport function setSessionCookies(\n\tcookies: Cookies,\n\taccessToken: string,\n\trefreshToken: string,\n\trememberMe: boolean = false\n): void {\n\tcookies.set(COOKIE_NAMES.ACCESS_TOKEN, accessToken, COOKIE_OPTIONS.ACCESS_TOKEN);\n\n\tconst refreshTokenOptions = rememberMe\n\t\t? COOKIE_OPTIONS.REFRESH_TOKEN_LONG\n\t\t: COOKIE_OPTIONS.REFRESH_TOKEN_SHORT;\n\n\tcookies.set(COOKIE_NAMES.REFRESH_TOKEN, refreshToken, refreshTokenOptions);\n}\n\n/**\n * Get session cookies (access + refresh tokens)\n */\nexport function getSessionCookies(cookies: Cookies): {\n\taccessToken: string | undefined;\n\trefreshToken: string | undefined;\n} {\n\treturn {\n\t\taccessToken: cookies.get(COOKIE_NAMES.ACCESS_TOKEN),\n\t\trefreshToken: cookies.get(COOKIE_NAMES.REFRESH_TOKEN)\n\t};\n}\n\n/**\n * Clear all authentication cookies\n */\nexport function clearAuthCookies(cookies: Cookies): void {\n\tcookies.delete(COOKIE_NAMES.ACCESS_TOKEN, { path: '/' });\n\tcookies.delete(COOKIE_NAMES.REFRESH_TOKEN, { path: '/' });\n}\n\n"]}

package/dist/sveltekit/handle.d.ts

@@ -0,0 +1,20 @@
+import type { Handle } from '@sveltejs/kit';
+import type { SentinelHandleOptions, UserLocals } from '../core/types.js';
+/** Locals shape set by the Sentinel auth middleware. */
+export interface SentinelLocals {
+    user: UserLocals | null;
+    accessToken: string | null;
+}
+/**
+ * Creates a SvelteKit handle function with Sentinel authentication built-in.
+ *
+ * Features:
+ * - Local JWT decode on every request (no per-request API call)
+ * - API-validated token refresh when expired or structurally invalid
+ * - Local expiration check (saves API calls)
+ * - Protected route redirection
+ * - Sets event.locals.user for all routes
+ * - Never clears cookies (only explicit logout does)
+ */
+export declare function createSentinelHandle(options?: SentinelHandleOptions): Handle;
+//# sourceMappingURL=handle.d.ts.map

package/dist/sveltekit/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../../src/sveltekit/handle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAgB,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAgC,MAAM,kBAAkB,CAAC;AAMxG,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CA0DhF"}