@zephkelly/nuxt-authkit 0.0.1

package/dist/runtime/storage/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Storage interface for tokens/sessions
+ * Implementations can use cookies, localStorage, memory, etc.
+ */
+export interface AuthStorage {
+    get(key: string): Promise<string | null> | string | null;
+    set(key: string, value: string, options?: StorageOptions): Promise<void> | void;
+    remove(key: string): Promise<void> | void;
+    clear(): Promise<void> | void;
+}
+export interface StorageOptions {
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    domain?: string;
+    path?: string;
+}
+/**
+ * Storage adapter interface compatible with Nitro's useStorage()
+ */
+export interface StorageAdapter {
+    getItem: <T = any>(key: string) => Promise<T | null>;
+    setItem: (key: string, value: any) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+    getKeys: (prefix?: string) => Promise<string[]>;
+}

package/dist/runtime/strategy/base.d.ts

@@ -0,0 +1,40 @@
+import type { H3Event } from "h3";
+import type { IAuthStrategy, StrategyConfig } from "./types.js";
+import type { AuthResult, VerifyAuthResult, AuthError } from "../types/index.js";
+import type { AuthCallbacks } from "../types/callbacks.js";
+import type { AuthkitCredentials, AuthkitUser } from './../types/authkit-types.js';
+/**
+ * Abstract base class for authentication strategies
+ * Provides common functionality and enforces consistent interface
+ */
+export declare abstract class BaseStrategy<TCredentials = AuthkitCredentials> implements IAuthStrategy<TCredentials> {
+    readonly name: string;
+    readonly config: StrategyConfig;
+    protected callbacks: AuthCallbacks;
+    constructor(config: StrategyConfig, callbacks: AuthCallbacks);
+    protected validateConfig(): void;
+    abstract authenticate(credentials: TCredentials, event: H3Event, options?: {
+        accessExpiresIn?: number;
+        refreshExpiresIn?: number;
+    }): Promise<AuthResult>;
+    abstract verify(event: H3Event, options?: any): VerifyAuthResult;
+    abstract refresh(event: H3Event, options?: any): Promise<AuthResult>;
+    abstract revoke(event: H3Event): Promise<void>;
+    protected createError(code: AuthError['code'], message: string, details?: unknown, recoverable?: boolean): Error;
+    protected extractAuthError(error: unknown): AuthError;
+    protected notifyAuthenticated(result: AuthResult, event: H3Event): Promise<void>;
+    protected notifyAuthenticationFailed(error: AuthError, event: H3Event): Promise<void>;
+    protected notifyLogout(userId: string, event: H3Event): Promise<void>;
+    protected handleError(error: unknown, event: H3Event): Promise<AuthResult>;
+    protected getStructuredAuthenticateResult(authenticateResult: string | {
+        id: string;
+        roles?: string[];
+        user?: any;
+        claims?: Record<string, unknown>;
+    } | null): {
+        id: string;
+        roles?: string[];
+        user?: AuthkitUser;
+        claims?: Record<string, unknown>;
+    } | null;
+}

package/dist/runtime/strategy/base.js

@@ -0,0 +1,88 @@
+export class BaseStrategy {
+  name;
+  config;
+  callbacks;
+  constructor(config, callbacks) {
+    this.name = config.name;
+    this.config = config;
+    this.callbacks = callbacks;
+    this.validateConfig();
+  }
+  validateConfig() {
+    if (!this.config.name) {
+      throw new Error("Strategy name is required");
+    }
+  }
+  // ========== Helper Methods ==========
+  createError(code, message, details, recoverable = true) {
+    const error = new Error(message);
+    error.authError = {
+      code,
+      message,
+      details,
+      recoverable
+    };
+    return error;
+  }
+  extractAuthError(error) {
+    if (error && typeof error === "object" && "authError" in error) {
+      return error.authError;
+    }
+    return {
+      code: "UNKNOWN_ERROR",
+      message: error instanceof Error ? error.message : "An error occurred",
+      recoverable: true
+    };
+  }
+  async notifyAuthenticated(result, event) {
+    if (this.callbacks.onAuthenticated && result.tokens) {
+      try {
+        await this.callbacks.onAuthenticated(
+          result.tokens,
+          event
+        );
+      } catch (error) {
+        console.error("Error in onAuthenticated callback:", error);
+      }
+    }
+  }
+  async notifyAuthenticationFailed(error, event) {
+    if (this.callbacks.onAuthenticationFailed) {
+      try {
+        await this.callbacks.onAuthenticationFailed(error.code, event);
+      } catch (err) {
+        console.error("Error in onAuthenticationFailed callback:", err);
+      }
+    }
+  }
+  async notifyLogout(userId, event) {
+    if (this.callbacks.onLogout) {
+      try {
+        await this.callbacks.onLogout(userId, event);
+      } catch (error) {
+        console.error("Error in onLogout callback:", error);
+      }
+    }
+  }
+  async handleError(error, event) {
+    const authError = this.extractAuthError(error);
+    await this.notifyAuthenticationFailed(authError, event);
+    return {
+      success: false,
+      error: authError
+    };
+  }
+  getStructuredAuthenticateResult(authenticateResult) {
+    if (typeof authenticateResult === "string") {
+      return { id: authenticateResult };
+    } else if (authenticateResult && typeof authenticateResult === "object" && "id" in authenticateResult) {
+      return {
+        id: authenticateResult.id,
+        roles: authenticateResult.roles,
+        user: authenticateResult.user,
+        claims: authenticateResult.claims
+      };
+    }
+    return null;
+  }
+}

package/dist/runtime/strategy/jwt/callback.d.ts

@@ -0,0 +1,60 @@
+import type { H3Event } from "h3";
+import type { AuthErrorCode } from '../../types/index.js';
+import type { TokenSet } from '../../types/token.js';
+import type { AuthCallbacksGeneral, RefreshTokenLookupResult } from '../../types/callbacks.js';
+import type { AuthkitCredentials, AuthkitUser } from './../../types/authkit-types.js';
+import type { Expand } from '../../types/expand.js';
+import type { JWTServerRevokeOptions } from './types.js';
+export interface JWTAuthCallbacks extends AuthCallbacksGeneral {
+    /**
+     * Verify user credentials.
+     * Called during initial authentication.
+     *
+     * Return the user id, or an object carrying `roles` and any custom `claims`
+     * to embed in the access token.
+     */
+    onAuthenticate(credentials: Expand<AuthkitCredentials>, event: H3Event): Promise<string | {
+        id: string;
+        roles?: string[];
+        user?: AuthkitUser;
+        claims?: Record<string, unknown>;
+    } | null>;
+    onStoreRefreshToken(refreshToken: string, identifier: string, event: H3Event): Promise<void>;
+    onGetRefreshToken(refreshToken: string, identifier: string, event: H3Event): Promise<RefreshTokenLookupResult>;
+    onRemoveRefreshToken?(refreshToken: string, identifier: string, event: H3Event): Promise<void>;
+    onGetRoles?(userId: string, event: H3Event): Promise<string[] | undefined> | string[] | undefined;
+    onRevokeTokenFamily?(family: string, userId: string, event: H3Event): Promise<void>;
+    onRevokeServer?(options: Expand<JWTServerRevokeOptions>, event?: H3Event): Promise<void>;
+    /**
+     * Resolve the refresh cookie's `Domain` attribute per request.
+     *
+     * A single API can legitimately serve clients on more than one registrable
+     * domain, and the refresh cookie has to be set on the one the request
+     * actually came from — a static `cookie.domain` can only ever satisfy one of
+     * them, and the others silently get no cookie.
+     *
+     * Return a falsy value to fall back to the configured `cookie.domain`.
+     *
+     * @example
+     * ```ts
+     * onResolveCookieDomain(event) {
+     *     const origin = getHeader(event, 'origin') ?? '';
+     *     return origin.endsWith('.example.dev') ? '.example.dev' : '.example.com';
+     * }
+     * ```
+     */
+    onResolveCookieDomain?(event: H3Event): string | undefined;
+    onAuthenticated?(tokens: TokenSet, event: H3Event): Promise<void> | void;
+    /**
+     * Called when authentication fails
+     */
+    onAuthenticationFailed?(reason: AuthErrorCode, event: H3Event): Promise<void> | void;
+    /**
+     * Called when tokens are refreshed
+     */
+    onTokenRefreshed?(tokens: TokenSet, event: H3Event): Promise<void> | void;
+    /**
+     * Called when user logs out
+     */
+    onLogout?(userId: string, event: H3Event): Promise<void> | void;
+}

package/dist/runtime/strategy/jwt/index.d.ts

@@ -0,0 +1,137 @@
+import type { AuthResult, VerifyAuthResult } from '../../types/index.js';
+import type { JWTAuthCallbacks } from './callback.js';
+import { BaseStrategy } from '../base.js';
+import type { JWTVerifyOptions, JWTRefreshOptions, JWTServerRevokeOptions } from './types.js';
+import type { AuthkitCredentials } from './../../types/authkit-types.js';
+import { type H3Event } from 'h3';
+import type { Expand } from '../../types/expand.js';
+/**
+ * JWT Authentication Strategy
+ * Implements access/refresh token pattern with rotating refresh tokens
+ */
+export declare class JWTStrategy extends BaseStrategy {
+    private readonly jwtCrypto;
+    private readonly jwtConfig;
+    protected callbacks: JWTAuthCallbacks;
+    constructor(callbacks: Expand<JWTAuthCallbacks>);
+    authenticate(credentials: AuthkitCredentials, event: H3Event, options?: {
+        accessExpiresIn?: number;
+        refreshExpiresIn?: number;
+    }): Promise<AuthResult>;
+    verify(event: H3Event, options?: JWTVerifyOptions): VerifyAuthResult;
+    /**
+     * Verify a bare access token, with no request context.
+     *
+     * `verify()` resolves the token from the ambient H3 event, which does not
+     * exist for a WebSocket peer, a queue worker, or a signed asset URL carrying
+     * its own token. Those callers have a token and nothing else, and this is the
+     * entry point for them.
+     *
+     * Claim validation is identical to `verify()` — in particular `typ` must be
+     * `'access'`, so a refresh token cannot be replayed here to open a socket.
+     */
+    verifyToken(accessToken: string): VerifyAuthResult;
+    /**
+     * Mint a token pair for a user directly, without presenting credentials.
+     *
+     * `authenticate()` is the credential path and always runs `onAuthenticate`.
+     * This is the path for the flows where the app has *already* established who
+     * the user is by some other means — an OAuth callback, an accepted invite, an
+     * admin impersonating a user, a device-linking handshake — and needs to hand
+     * out a session for a subject it chose itself.
+     *
+     * It is a session-minting primitive with no authentication of its own: the
+     * caller is asserting the identity. Never reach it from an unauthenticated
+     * route without first proving the subject some other way.
+     *
+     * Starts a fresh rotation family, so it is a real new session rather than a
+     * graft onto an existing one.
+     */
+    issueTokens(userId: string, event: H3Event, options?: {
+        roles?: string[];
+        claims?: Record<string, unknown>;
+        accessExpiresIn?: number;
+        refreshExpiresIn?: number;
+    }): Promise<AuthResult>;
+    refresh(event: H3Event, options?: JWTRefreshOptions): Promise<AuthResult>;
+    revoke(event: H3Event): Promise<void>;
+    /**
+     * Server-initiated revocation (admin force-logout, scheduled cleanup...).
+     *
+     * Throws when no `onRevokeServer` callback is configured. Only the app knows
+     * where its tokens live, so there is nothing this can do on its own — and
+     * reporting success while doing nothing is worse than failing.
+     */
+    revokeServer(options: JWTServerRevokeOptions, event?: H3Event): Promise<void>;
+    /**
+     * Decide whether a payload is an access or a refresh token.
+     *
+     * `typ` is mandatory: a token that does not say what it is, is not usable as
+     * anything. Both kinds are signed with the same key, so this claim is the only
+     * thing preventing a refresh token from being replayed as a 7-day Bearer
+     * session. There is deliberately no fallback for tokens minted before the claim
+     * existed — they are rejected, which logs their holders out once.
+     */
+    private resolveTokenUse;
+    private validateClaims;
+    /** `aud` is `string | string[]` on both sides; they match if they intersect. */
+    private audienceMatches;
+    private shouldRotate;
+    /**
+     * Accepts the legacy `string | null` return as well as the richer
+     * {@link RefreshTokenLookup}, so existing callbacks keep working unchanged.
+     */
+    private normaliseRefreshLookup;
+    private resolveRolesForRefresh;
+    private removeStoredRefreshToken;
+    private constantTimeEquals;
+    private generateTokens;
+    /**
+     * Carry an existing token's custom claims through rotation, dropping the
+     * reserved ones (which are always recomputed).
+     */
+    private extractCustomClaims;
+    private stripReservedClaims;
+    /**
+     * Static `jwt.claims` that collide with a computed claim are a configuration
+     * error, not something to silently drop: a stray `exp` there would otherwise
+     * have minted never-expiring tokens app-wide.
+     */
+    private assertNoReservedClaims;
+    private warnOnWeakConfiguration;
+    private encodeToken;
+    /**
+     * Verify and decode a token.
+     *
+     * Returns `null` for any cryptographically-invalid token — malformed, bad
+     * signature, wrong algorithm. The distinction is logged server-side but never
+     * surfaced to the caller, so it cannot become an error oracle, and callers get
+     * a single unambiguous "invalid" they can fail closed on.
+     */
+    private decodeToken;
+    private invalidToken;
+    private invalidRefresh;
+    private shouldRefreshToken;
+    private notifyTokenRefreshed;
+    private readRefreshHttpOnlyCookie;
+    private revokeRefreshHttpOnlyCookie;
+    private issueRefreshHttpOnlyCookie;
+    /**
+     * `httpOnly` is forced on rather than merged in. These helpers are named for a
+     * guarantee, and a refresh token readable from JavaScript is exactly the
+     * credential this design exists to keep out of reach.
+     *
+     * The domain is resolved per request when `onResolveCookieDomain` is supplied:
+     * one API can serve clients on several registrable domains, and a static
+     * `cookie.domain` can only ever satisfy one of them. Deletion resolves the
+     * domain the same way — a cookie set on one domain cannot be cleared by a
+     * Set-Cookie scoped to another.
+     */
+    private resolveRefreshCookieOptions;
+    /**
+     * RFC 7235 makes the auth-scheme case-insensitive, and an anchored match keeps
+     * a header without the scheme from being returned verbatim as a "token".
+     */
+    private getAuthBearerToken;
+}
+export declare function createJWTStrategy(callbacks: Expand<JWTAuthCallbacks>): JWTStrategy;