@zephkelly/nuxt-authkit 0.0.1

package/dist/runtime/strategy/jwt/jwt-crypto.d.ts

@@ -0,0 +1,122 @@
+import type { TokenPayload } from '../../types/token.js';
+export interface JWTCryptoConfig {
+    /**
+     * RSA private key in PEM format for signing tokens
+     */
+    privateKey?: string;
+    /**
+     * RSA public key in PEM format for verifying tokens
+     */
+    publicKey?: string;
+    /**
+     * Algorithm to use for signing (default: RS256)
+     */
+    algorithm?: 'RS256' | 'RS384' | 'RS512';
+    /**
+     * Reject tokens longer than this before doing any parsing or signature work.
+     * @default 16384
+     */
+    maxTokenLength?: number;
+}
+export interface JWTHeader {
+    alg: string;
+    typ: string;
+}
+/**
+ * Why a token was rejected. Callers map these to a stable, non-leaking error
+ * taxonomy — a malformed or badly-signed token is a hard failure, never a
+ * "recoverable" one that a client should retry.
+ */
+export type JWTCryptoErrorCode = 'TOKEN_MALFORMED' | 'TOKEN_SIGNATURE_INVALID' | 'TOKEN_ALGORITHM_MISMATCH' | 'TOKEN_TOO_LARGE' | 'KEY_UNAVAILABLE';
+/**
+ * A token-level failure carrying a machine-readable code.
+ *
+ * The `message` is for server logs only — it distinguishes malformed-from-
+ * bad-signature and must never be relayed to a client, or it becomes an oracle.
+ */
+export declare class JWTCryptoError extends Error {
+    readonly code: JWTCryptoErrorCode;
+    constructor(code: JWTCryptoErrorCode, message: string);
+}
+/**
+ * Secure JWT token handler using RSA cryptography
+ * Supports RS256, RS384, and RS512 algorithms
+ */
+export declare class JWTCrypto {
+    private privateKey?;
+    private publicKey?;
+    private algorithm;
+    private maxTokenLength;
+    constructor(config: JWTCryptoConfig);
+    /**
+     * Sign and encode a JWT token
+     * @throws Error if private key is not configured
+     */
+    sign(payload: TokenPayload): string;
+    /**
+     * Verify and decode a JWT token
+     * @throws Error if token is invalid or public key is not configured
+     */
+    verify(token: string): TokenPayload;
+    /**
+     * Decode a token WITHOUT verifying its signature.
+     *
+     * The returned claims are attacker-controlled and must never be used for an
+     * authentication or authorization decision. Use {@link verify} for anything
+     * that matters. Kept only for diagnostics.
+     *
+     * @internal
+     * @deprecated Use {@link verify}. This performs no signature check.
+     */
+    unsafeDecodeNoVerify(token: string): TokenPayload | null;
+    /**
+     * Decode token without verification (use with caution!)
+     * Useful for extracting claims before verification or when signature verification is not required
+     *
+     * @internal
+     * @deprecated Use {@link verify}. This performs no signature check, so its
+     * output is attacker-controlled.
+     */
+    decode(token: string): TokenPayload | null;
+    private createSignature;
+    private verifySignature;
+    private getHashAlgorithm;
+    private parsePrivateKey;
+    private parsePublicKey;
+    /**
+     * The configured algorithm (RS*) names RSA. An EC or Ed25519 PEM would
+     * otherwise be accepted here and used under an "RS256" label.
+     */
+    private assertRsaKey;
+    /**
+     * Encode string to base64url
+     */
+    private base64UrlEncode;
+    /**
+     * Decode base64url string to UTF-8 string
+     */
+    private base64UrlDecode;
+    /**
+     * Convert binary buffer to base64url (for signatures)
+     */
+    private bufferToBase64Url;
+    /**
+     * Convert base64url to binary buffer (for signatures)
+     */
+    private base64UrlToBuffer;
+    /**
+     * Generate a new RSA key pair for development/testing
+     * In production, use properly generated and stored keys
+     *
+     * Defaults to 3072 bits: NIST SP 800-57 rates 2048-bit RSA as adequate only
+     * through ~2030, which is inside the lifetime of a key minted today.
+     */
+    static generateKeyPair(modulusLength?: 2048 | 3072 | 4096): {
+        privateKey: string;
+        publicKey: string;
+    };
+    /**
+     * Validate that a key pair matches (public key can verify tokens signed by private key)
+     */
+    static validateKeyPair(privateKey: string, publicKey: string): boolean;
+}

package/dist/runtime/strategy/jwt/jwt-crypto.js

@@ -0,0 +1,298 @@
+import { createSign, createVerify, generateKeyPairSync, createPrivateKey, createPublicKey } from "node:crypto";
+export class JWTCryptoError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "JWTCryptoError";
+    this.code = code;
+  }
+}
+const SUPPORTED_ALGORITHMS = ["RS256", "RS384", "RS512"];
+const DEFAULT_MAX_TOKEN_LENGTH = 16384;
+export class JWTCrypto {
+  privateKey;
+  publicKey;
+  algorithm;
+  maxTokenLength;
+  constructor(config) {
+    this.algorithm = config.algorithm || "RS256";
+    this.maxTokenLength = config.maxTokenLength ?? DEFAULT_MAX_TOKEN_LENGTH;
+    if (!SUPPORTED_ALGORITHMS.includes(this.algorithm)) {
+      throw new Error(
+        `Unsupported JWT algorithm "${this.algorithm}". Supported: ${SUPPORTED_ALGORITHMS.join(", ")}`
+      );
+    }
+    if (config.privateKey) {
+      try {
+        this.privateKey = this.parsePrivateKey(config.privateKey);
+      } catch (error) {
+        throw new Error(`Failed to parse private key: ${error instanceof Error ? error.message : "Unknown error"}`);
+      }
+    }
+    if (config.publicKey) {
+      try {
+        this.publicKey = this.parsePublicKey(config.publicKey);
+      } catch (error) {
+        throw new Error(`Failed to parse public key: ${error instanceof Error ? error.message : "Unknown error"}`);
+      }
+    }
+    if (!this.privateKey && !this.publicKey) {
+      throw new Error("At least one of privateKey or publicKey must be provided");
+    }
+  }
+  /**
+   * Sign and encode a JWT token
+   * @throws Error if private key is not configured
+   */
+  sign(payload) {
+    if (!this.privateKey) {
+      throw new Error("Private key is required for signing tokens");
+    }
+    const header = {
+      alg: this.algorithm,
+      typ: "JWT"
+    };
+    const encodedHeader = this.base64UrlEncode(JSON.stringify(header));
+    const encodedPayload = this.base64UrlEncode(JSON.stringify(payload));
+    const signatureInput = `${encodedHeader}.${encodedPayload}`;
+    const signature = this.createSignature(signatureInput);
+    return `${signatureInput}.${signature}`;
+  }
+  /**
+   * Verify and decode a JWT token
+   * @throws Error if token is invalid or public key is not configured
+   */
+  verify(token) {
+    if (!this.publicKey) {
+      throw new JWTCryptoError("KEY_UNAVAILABLE", "Public key is required for verifying tokens");
+    }
+    if (typeof token !== "string" || token.length === 0) {
+      throw new JWTCryptoError("TOKEN_MALFORMED", "Invalid token format: not a string");
+    }
+    if (token.length > this.maxTokenLength) {
+      throw new JWTCryptoError(
+        "TOKEN_TOO_LARGE",
+        `Token exceeds maximum length of ${this.maxTokenLength} characters`
+      );
+    }
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      throw new JWTCryptoError("TOKEN_MALFORMED", "Invalid token format: expected 3 parts");
+    }
+    const [encodedHeader, encodedPayload, signature] = parts;
+    if (!encodedHeader || !encodedPayload || !signature) {
+      throw new JWTCryptoError("TOKEN_MALFORMED", "Invalid token format: missing parts");
+    }
+    const signatureInput = `${encodedHeader}.${encodedPayload}`;
+    const isValid = this.verifySignature(signatureInput, signature);
+    if (!isValid) {
+      throw new JWTCryptoError("TOKEN_SIGNATURE_INVALID", "Invalid token signature");
+    }
+    let header;
+    try {
+      header = JSON.parse(this.base64UrlDecode(encodedHeader));
+    } catch {
+      throw new JWTCryptoError("TOKEN_MALFORMED", "Invalid token header");
+    }
+    if (header.alg !== this.algorithm) {
+      throw new JWTCryptoError(
+        "TOKEN_ALGORITHM_MISMATCH",
+        `Algorithm mismatch: expected ${this.algorithm}, got ${header.alg}`
+      );
+    }
+    if (header.typ !== "JWT") {
+      throw new JWTCryptoError(
+        "TOKEN_MALFORMED",
+        `Invalid JOSE header typ: expected "JWT", got ${JSON.stringify(header.typ)}`
+      );
+    }
+    let payload;
+    try {
+      payload = JSON.parse(this.base64UrlDecode(encodedPayload));
+    } catch {
+      throw new JWTCryptoError("TOKEN_MALFORMED", "Invalid token payload");
+    }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new JWTCryptoError("TOKEN_MALFORMED", "Invalid token payload: not an object");
+    }
+    return payload;
+  }
+  /**
+   * Decode a token WITHOUT verifying its signature.
+   *
+   * The returned claims are attacker-controlled and must never be used for an
+   * authentication or authorization decision. Use {@link verify} for anything
+   * that matters. Kept only for diagnostics.
+   *
+   * @internal
+   * @deprecated Use {@link verify}. This performs no signature check.
+   */
+  unsafeDecodeNoVerify(token) {
+    return this.decode(token);
+  }
+  /**
+   * Decode token without verification (use with caution!)
+   * Useful for extracting claims before verification or when signature verification is not required
+   *
+   * @internal
+   * @deprecated Use {@link verify}. This performs no signature check, so its
+   * output is attacker-controlled.
+   */
+  decode(token) {
+    try {
+      const parts = token.split(".");
+      if (parts.length !== 3) {
+        return null;
+      }
+      if (!parts[0] || !parts[1]) {
+        return null;
+      }
+      const payload = this.base64UrlDecode(parts[1]);
+      return JSON.parse(payload);
+    } catch {
+      return null;
+    }
+  }
+  createSignature(data) {
+    if (!this.privateKey) {
+      throw new Error("Private key is required for signing");
+    }
+    const hashAlgorithm = this.getHashAlgorithm();
+    const sign = createSign(hashAlgorithm);
+    sign.update(data);
+    sign.end();
+    const signature = sign.sign(this.privateKey);
+    return this.bufferToBase64Url(signature);
+  }
+  verifySignature(data, signature) {
+    if (!this.publicKey) {
+      throw new Error("Public key is required for verification");
+    }
+    try {
+      const hashAlgorithm = this.getHashAlgorithm();
+      const verify = createVerify(hashAlgorithm);
+      verify.update(data);
+      verify.end();
+      const signatureBuffer = this.base64UrlToBuffer(signature);
+      return verify.verify(this.publicKey, signatureBuffer);
+    } catch {
+      return false;
+    }
+  }
+  getHashAlgorithm() {
+    switch (this.algorithm) {
+      case "RS256":
+        return "RSA-SHA256";
+      case "RS384":
+        return "RSA-SHA384";
+      case "RS512":
+        return "RSA-SHA512";
+      default:
+        throw new Error(`Unsupported algorithm: ${this.algorithm}`);
+    }
+  }
+  parsePrivateKey(keyData) {
+    const key = createPrivateKey({
+      key: keyData,
+      format: "pem"
+    });
+    this.assertRsaKey(key, "private");
+    return key;
+  }
+  parsePublicKey(keyData) {
+    const key = createPublicKey({
+      key: keyData,
+      format: "pem"
+    });
+    this.assertRsaKey(key, "public");
+    return key;
+  }
+  /**
+   * The configured algorithm (RS*) names RSA. An EC or Ed25519 PEM would
+   * otherwise be accepted here and used under an "RS256" label.
+   */
+  assertRsaKey(key, kind) {
+    if (key.asymmetricKeyType !== "rsa" && key.asymmetricKeyType !== "rsa-pss") {
+      throw new Error(
+        `Expected an RSA ${kind} key for ${this.algorithm}, got "${key.asymmetricKeyType}"`
+      );
+    }
+  }
+  /**
+   * Encode string to base64url
+   */
+  base64UrlEncode(str) {
+    const base64 = Buffer.from(str, "utf-8").toString("base64");
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  }
+  /**
+   * Decode base64url string to UTF-8 string
+   */
+  base64UrlDecode(str) {
+    let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = base64.length % 4;
+    if (pad) {
+      base64 += "=".repeat(4 - pad);
+    }
+    return Buffer.from(base64, "base64").toString("utf-8");
+  }
+  /**
+   * Convert binary buffer to base64url (for signatures)
+   */
+  bufferToBase64Url(buffer) {
+    return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  }
+  /**
+   * Convert base64url to binary buffer (for signatures)
+   */
+  base64UrlToBuffer(str) {
+    let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = base64.length % 4;
+    if (pad) {
+      base64 += "=".repeat(4 - pad);
+    }
+    return Buffer.from(base64, "base64");
+  }
+  /**
+   * Generate a new RSA key pair for development/testing
+   * In production, use properly generated and stored keys
+   *
+   * Defaults to 3072 bits: NIST SP 800-57 rates 2048-bit RSA as adequate only
+   * through ~2030, which is inside the lifetime of a key minted today.
+   */
+  static generateKeyPair(modulusLength = 3072) {
+    const { publicKey, privateKey } = generateKeyPairSync("rsa", {
+      modulusLength,
+      publicKeyEncoding: {
+        type: "spki",
+        format: "pem"
+      },
+      privateKeyEncoding: {
+        type: "pkcs8",
+        format: "pem"
+      }
+    });
+    return {
+      privateKey,
+      publicKey
+    };
+  }
+  /**
+   * Validate that a key pair matches (public key can verify tokens signed by private key)
+   */
+  static validateKeyPair(privateKey, publicKey) {
+    try {
+      const crypto = new JWTCrypto({ privateKey, publicKey });
+      const testPayload = {
+        sub: "test",
+        iat: Math.floor(Date.now() / 1e3),
+        exp: Math.floor(Date.now() / 1e3) + 60
+      };
+      const token = crypto.sign(testPayload);
+      const verified = crypto.verify(token);
+      return verified.sub === testPayload.sub;
+    } catch {
+      return false;
+    }
+  }
+}

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

@@ -0,0 +1,68 @@
+import type { NuxtAuthkitCookieOptions } from '../../types/cookie.js';
+/**
+ * JWT Strategy Configuration
+ */
+export interface JwtStrategyConfig {
+    name: string;
+    tokens: {
+        access: {
+            expiresIn: number;
+        };
+        refresh?: {
+            expiresIn: number;
+            storageKey?: string;
+            cookie?: NuxtAuthkitCookieOptions;
+            /**
+             * Rotate the refresh token on every successful refresh: a new
+             * refresh token is issued, stored via `onStoreRefreshToken`, and
+             * the presented one is invalidated via `onRemoveRefreshToken`.
+             *
+             * Disabling this means a leaked refresh token stays valid for its
+             * full lifetime and cannot be contained server-side.
+             *
+             * @default true
+             */
+            rotate?: boolean;
+        };
+    };
+    autoRefresh?: {
+        enabled: boolean;
+        beforeExpiry: number;
+    };
+    jwt?: {
+        issuer?: string;
+        audience?: string | string[];
+        /**
+         * Static claims added to every access token.
+         *
+         * Reserved claims (`sub`, `exp`, `iat`, `nbf`, `iss`, `aud`, `jti`,
+         * `roles`, `typ`, `family`) are rejected at strategy construction —
+         * they are computed per request and must not be overridden.
+         */
+        claims?: Record<string, unknown>;
+        algorithm?: 'RS256' | 'RS384' | 'RS512';
+        privateKey: string;
+        publicKey: string;
+    };
+}
+export interface JWTServerRevokeOptions {
+    userId?: string;
+    exceptCredentialId?: string;
+    expiredOnly?: boolean;
+    refreshTokenId?: string;
+}
+export interface JWTVerifyOptions {
+    accessToken?: string;
+    ignoreExpiration?: boolean;
+}
+export interface JWTRefreshOptions {
+    /**
+     * Override `tokens.refresh.rotate` for this call.
+     */
+    rotate?: boolean;
+    /**
+     * @deprecated Use `rotate`. Rotation is now on by default; this flag is
+     * honoured only for backwards compatibility with 0.0.x callers.
+     */
+    refreshToken?: boolean;
+}

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

@@ -0,0 +1,68 @@
+import type { H3Event } from "h3";
+import type { VerificationType } from "../types/2fac.js";
+import type { AuthResult, VerifyAuthResult } from "../types/index.js";
+import type { AuthStorage } from "../storage/types.js";
+import type { AuthkitCredentials } from "../types/authkit-types.js";
+export interface StrategyConfig {
+    /** Strategy name */
+    name: string;
+    /** Enable 2FA support */
+    twoFactor?: {
+        enabled: boolean;
+        methods: VerificationType[];
+        /** Grace period before requiring 2FA (in seconds) */
+        gracePeriod?: number;
+    };
+    /** Token configuration (strategy-specific) */
+    tokens?: unknown;
+    /** Storage configuration */
+    storage?: AuthStorage;
+    /** Custom options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Base interface that all authentication strategies must implement
+ */
+export interface AuthStrategyGeneral<TCredentials = AuthkitCredentials> {
+    /** Strategy name (e.g., 'jwt', 'session', 'oauth') */
+    readonly name: string;
+    /** Configuration */
+    readonly config: StrategyConfig;
+    /**
+     * Authenticate user with credentials
+     * Returns tokens and user data on success
+     */
+    authenticate(credentials: TCredentials, event?: H3Event, options?: any): Promise<AuthResult>;
+    /**
+     * Verify a token and return payload
+     * Used for protected routes
+     */
+    verify(event?: H3Event, options?: any): VerifyAuthResult;
+    /**
+     * Verify a bare token with no request context — WebSocket peers, workers,
+     * signed asset URLs. Optional: not every strategy has a context-free token.
+     */
+    verifyToken?(token: string): VerifyAuthResult;
+    /**
+     * Mint a session for a subject the app has already identified by other means
+     * (OAuth callback, accepted invite, impersonation), bypassing credentials.
+     * Optional: strategies without a token pair to hand out need not implement it.
+     */
+    issueTokens?(userId: string, event?: H3Event, options?: any): Promise<AuthResult>;
+    /**
+     * Refresh tokens using refresh token
+     */
+    refresh(event?: H3Event, options?: any): Promise<AuthResult>;
+    /**
+     * Revoke/invalidate tokens
+     * Used during logout
+     */
+    revoke(event?: H3Event): Promise<void>;
+    /**
+     * Server-initiated revocation (admin force-logout, scheduled cleanup).
+     * Implementations must fail loudly if they cannot actually revoke anything.
+     */
+    revokeServer?(options?: any, event?: H3Event): Promise<void>;
+}
+export interface IAuthStrategy<TCredentials = AuthkitCredentials> extends AuthStrategyGeneral<TCredentials> {
+}

package/dist/runtime/types/2fac.d.ts

@@ -0,0 +1,32 @@
+export type VerificationType = 'totp' | 'sms' | 'email' | 'backup_code' | 'webauthn' | 'push';
+export interface TwoFactorChallenge {
+    /** Unique challenge ID */
+    id: string;
+    /** Type of 2FA */
+    type: VerificationType;
+    /** When the challenge expires */
+    expiresAt: number;
+    /** Additional data needed for the challenge */
+    data?: {
+        /** For TOTP: QR code data URL (during setup) */
+        qrCode?: string;
+        /** For TOTP: Secret key (during setup) */
+        secret?: string;
+        /** For SMS/Email: Masked destination */
+        destination?: string;
+        /** For WebAuthn: Challenge data */
+        challenge?: unknown;
+    };
+    /** Available methods if multiple 2FA methods enabled */
+    availableMethods?: VerificationType[];
+}
+export interface TwoFactorVerification {
+    /** The challenge ID */
+    challengeId: string;
+    /** The verification code/response */
+    code: string;
+    /** Type of verification being provided */
+    type: VerificationType;
+    /** Whether to remember this device */
+    trustDevice?: boolean;
+}

package/dist/runtime/types/authkit-types.d.ts

@@ -0,0 +1,6 @@
+export interface AuthkitRole {
+}
+export interface AuthkitUser {
+}
+export interface AuthkitCredentials {
+}