passkey-magic 0.1.0

package/dist/types-BjM1f6uu.d.mts

@@ -0,0 +1,249 @@
+import { AuthenticationResponseJSON, AuthenticatorTransportFuture, CredentialDeviceType, RegistrationResponseJSON } from "@simplewebauthn/server";
+
+//#region src/types.d.ts
+/** A registered user account. */
+interface User {
+  id: string;
+  email?: string;
+  createdAt: Date;
+}
+/** A WebAuthn credential (passkey) associated with a user. */
+interface Credential {
+  id: string;
+  userId: string;
+  publicKey: Uint8Array;
+  counter: number;
+  deviceType: CredentialDeviceType;
+  backedUp: boolean;
+  transports?: AuthenticatorTransportFuture[];
+  /** Human-readable label (e.g. "iPhone", "YubiKey"). */
+  label?: string;
+  createdAt: Date;
+}
+/** An authenticated session bound to a user. */
+interface Session {
+  id: string;
+  token: string;
+  userId: string;
+  expiresAt: Date;
+  createdAt: Date;
+  /** User-agent string from the request that created the session. */
+  userAgent?: string;
+  /** IP address from the request that created the session. */
+  ipAddress?: string;
+}
+/** A cross-device login session initiated by QR code scan. */
+interface QRSession {
+  id: string;
+  state: 'pending' | 'scanned' | 'authenticated' | 'expired';
+  userId?: string;
+  sessionToken?: string;
+  expiresAt: Date;
+  createdAt: Date;
+}
+/** Discriminated union returned from all authentication flows. */
+type AuthResult = {
+  method: 'passkey';
+  user: User;
+  session: Session;
+} | {
+  method: 'magic-link';
+  user: User;
+  session: Session;
+  isNewUser: boolean;
+} | {
+  method: 'qr';
+  user: User;
+  session: Session;
+};
+/**
+ * Persistence layer interface. Implement this to use any database.
+ *
+ * All methods must be safe to call concurrently. Implementations should
+ * handle their own serialization of `Date` and `Uint8Array` fields.
+ */
+interface StorageAdapter {
+  createUser(user: User): Promise<User>;
+  getUserById(id: string): Promise<User | null>;
+  getUserByEmail(email: string): Promise<User | null>;
+  updateUser(id: string, update: Partial<Pick<User, 'email'>>): Promise<User>;
+  deleteUser(id: string): Promise<void>;
+  createCredential(credential: Credential): Promise<Credential>;
+  getCredentialById(id: string): Promise<Credential | null>;
+  getCredentialsByUserId(userId: string): Promise<Credential[]>;
+  updateCredential(id: string, update: Partial<Pick<Credential, 'counter' | 'label'>>): Promise<void>;
+  deleteCredential(id: string): Promise<void>;
+  createSession(session: Session): Promise<Session>;
+  getSessionByToken(token: string): Promise<Session | null>;
+  getSessionsByUserId(userId: string): Promise<Session[]>;
+  deleteSession(id: string): Promise<void>;
+  deleteSessionsByUserId(userId: string): Promise<void>;
+  storeChallenge(key: string, challenge: string, ttlMs: number): Promise<void>;
+  getChallenge(key: string): Promise<string | null>;
+  deleteChallenge(key: string): Promise<void>;
+  storeMagicLink(token: string, email: string, ttlMs: number): Promise<void>;
+  getMagicLink(token: string): Promise<{
+    email: string;
+  } | null>;
+  deleteMagicLink(token: string): Promise<void>;
+  createQRSession(session: QRSession): Promise<QRSession>;
+  getQRSession(id: string): Promise<QRSession | null>;
+  updateQRSession(id: string, update: Partial<QRSession>): Promise<void>;
+}
+/**
+ * Email delivery interface. Implement this to send magic link emails.
+ *
+ * @example
+ * ```ts
+ * const resendAdapter: EmailAdapter = {
+ *   async sendMagicLink(email, url, token) {
+ *     await resend.emails.send({ to: email, subject: 'Login', html: `<a href="${url}">Login</a>` })
+ *   }
+ * }
+ * ```
+ */
+interface EmailAdapter {
+  sendMagicLink(email: string, url: string, token: string): Promise<void>;
+}
+/** Lifecycle hooks for intercepting auth flows. Return `false` from `before*` hooks to abort. */
+interface AuthHooks {
+  beforeRegister?: (ctx: {
+    email?: string;
+  }) => Promise<void | false>;
+  afterRegister?: (ctx: {
+    user: User;
+    credential: Credential;
+  }) => Promise<void>;
+  beforeAuthenticate?: (ctx: {
+    credentialId?: string;
+  }) => Promise<void | false>;
+  afterAuthenticate?: (ctx: {
+    user: User;
+    session: Session;
+  }) => Promise<void>;
+  beforeMagicLink?: (ctx: {
+    email: string;
+  }) => Promise<void | false>;
+  afterMagicLink?: (ctx: {
+    user: User;
+    session: Session;
+    isNewUser: boolean;
+  }) => Promise<void>;
+  beforeQRComplete?: (ctx: {
+    sessionId: string;
+    userId: string;
+  }) => Promise<void | false>;
+  afterQRComplete?: (ctx: {
+    user: User;
+    session: Session;
+  }) => Promise<void>;
+}
+/** Map of all auth events and their payload types. */
+interface AuthEventMap {
+  'user:created': {
+    user: User;
+  };
+  'user:deleted': {
+    userId: string;
+  };
+  'session:created': {
+    session: Session;
+    user: User;
+    method: 'passkey' | 'magic-link' | 'qr';
+  };
+  'session:revoked': {
+    sessionId: string;
+    userId: string;
+  };
+  'credential:created': {
+    credential: Credential;
+    user: User;
+  };
+  'credential:updated': {
+    credentialId: string;
+    userId: string;
+  };
+  'credential:removed': {
+    credentialId: string;
+    userId: string;
+  };
+  'magic-link:sent': {
+    email: string;
+  };
+  'qr:scanned': {
+    sessionId: string;
+  };
+  'qr:completed': {
+    sessionId: string;
+    user: User;
+  };
+  'email:linked': {
+    userId: string;
+    email: string;
+  };
+  'email:unlinked': {
+    userId: string;
+    email: string;
+  };
+}
+/** Typed event handler for a specific auth event. */
+type AuthEventHandler<K extends keyof AuthEventMap> = (event: AuthEventMap[K]) => void;
+/** Configuration for `createAuth()`. */
+interface AuthConfig<TEmail extends EmailAdapter | undefined = undefined> {
+  /** Relying party name shown during passkey prompts. */
+  rpName: string;
+  /** Relying party ID — typically the domain (e.g. "example.com"). */
+  rpID: string;
+  /** Expected origin(s) for WebAuthn verification. */
+  origin: string | string[];
+  /** Storage adapter for persistence. */
+  storage: StorageAdapter;
+  /** Email adapter — enables magic link auth when provided. */
+  email?: TEmail;
+  /** Base URL for magic link verification. Required if `email` is set. */
+  magicLinkURL?: TEmail extends EmailAdapter ? string : string | undefined;
+  /** Session TTL in ms. Default: 7 days. */
+  sessionTTL?: number;
+  /** WebAuthn challenge TTL in ms. Default: 60s. */
+  challengeTTL?: number;
+  /** Magic link token TTL in ms. Default: 15 minutes. */
+  magicLinkTTL?: number;
+  /** QR session TTL in ms. Default: 5 minutes. */
+  qrSessionTTL?: number;
+  /** Custom ID generator. Default: `crypto.randomUUID()`. */
+  generateId?: () => string;
+  /** Lifecycle hooks. */
+  hooks?: AuthHooks;
+}
+/** Methods only available when an `EmailAdapter` is configured. */
+interface MagicLinkMethods {
+  /** Send a magic link email. Throws if email format is invalid. */
+  sendMagicLink(params: {
+    email: string;
+  }): Promise<{
+    sent: true;
+  }>;
+  /** Verify a magic link token and create a session. Single-use — token is consumed. */
+  verifyMagicLink(params: {
+    token: string;
+  }): Promise<AuthResult & {
+    method: 'magic-link';
+  }>;
+}
+/**
+ * Client configuration. Provide a `request` function that handles
+ * transport to your server (fetch, tRPC, WebSocket, etc.).
+ */
+interface ClientConfig {
+  request: <T = unknown>(endpoint: string, body?: unknown) => Promise<T>;
+}
+/** Status of a QR cross-device login session. */
+interface QRSessionStatus {
+  state: QRSession['state'];
+  session?: {
+    token: string;
+    expiresAt: string;
+  };
+}
+//#endregion
+export { AuthResult as a, Credential as c, QRSessionStatus as d, RegistrationResponseJSON as f, User as h, AuthHooks as i, EmailAdapter as l, StorageAdapter as m, AuthEventHandler as n, AuthenticationResponseJSON as o, Session as p, AuthEventMap as r, ClientConfig as s, AuthConfig as t, MagicLinkMethods as u };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "passkey-magic",
+  "version": "0.1.0",
+  "description": "Passkey-first authentication with QR cross-device login and magic link fallback",
+  "type": "module",
+  "exports": {
+    "./server": {
+      "import": "./dist/server/index.mjs",
+      "types": "./dist/server/index.d.mts"
+    },
+    "./client": {
+      "import": "./dist/client/index.mjs",
+      "types": "./dist/client/index.d.mts"
+    },
+    "./adapters/memory": {
+      "import": "./dist/adapters/memory.mjs",
+      "types": "./dist/adapters/memory.d.mts"
+    },
+    "./adapters/unstorage": {
+      "import": "./dist/adapters/unstorage.mjs",
+      "types": "./dist/adapters/unstorage.d.mts"
+    },
+    "./nitro": {
+      "import": "./dist/nitro/index.mjs",
+      "types": "./dist/nitro/index.d.mts"
+    },
+    "./better-auth": {
+      "import": "./dist/better-auth/index.mjs",
+      "types": "./dist/better-auth/index.d.mts"
+    },
+    "./better-auth/client": {
+      "import": "./dist/better-auth/client.mjs",
+      "types": "./dist/better-auth/client.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "passkey",
+    "webauthn",
+    "auth",
+    "magic-link",
+    "qr",
+    "fido2"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@simplewebauthn/browser": "^13.3.0",
+    "@simplewebauthn/server": "^13.3.0",
+    "unstorage": "^1.17.4",
+    "uqr": "^0.1.2"
+  },
+  "peerDependencies": {
+    "better-auth": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "better-auth": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "better-auth": "^1.5.5",
+    "tsdown": "^0.21.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}