isitme 0.0.1 → 0.0.2

package/README.md

@@ -1,9 +1,9 @@
 # isitme
 
-Passkey authentication for Express. One line of code, no database, no passwords.
+Free passkey authentication for solo builders. One owner per domain. No accounts. No passwords. No kidding.
 
 ```
-npm install isitme
+npm i isitme
 ```
 
 ## Quick start
@@ -24,81 +24,53 @@ app.get("/", (req, res) => {
 app.listen(3000);
 ```
 
-The first visitor registers a passkey with their fingerprint or face. After that, every request requires biometric authentication.
+Visit `localhost:3000` — register a passkey with your fingerprint, and the app is locked to you.
 
-## Options
+## React
 
-```js
-app.use(isitme({
-  secret: "your-jwt-secret",       // default: random (sessions lost on restart)
-  storage: "./auth.json",           // default: "./auth.json", false for in-memory
-  publicPaths: ["/", "/about"],     // routes that skip auth
-  prefix: "/auth",                  // auth endpoint prefix
-  sessionExpiryDays: 7,             // session duration
-  page: { title: "My App" },        // customize login page, or false to disable
-}));
-```
+```jsx
+import { IsItMe } from "isitme/react";
 
-## Public paths and conditional auth
+<IsItMe>
+  <h1>Admin dashboard</h1>
+  <p>Only you can see this.</p>
+</IsItMe>
+```
 
-The middleware sets `req.isAuthenticated` on every request, even on public paths:
+## Browser API
 
 ```js
-app.use(isitme({ publicPaths: ["/"] }));
+import { signin, isItMe, logout } from "isitme/browser";
 
-app.get("/", (req, res) => {
-  if (req.isAuthenticated) {
-    res.send("Welcome back!");
-  } else {
-    res.send("Sign in to continue.");
-  }
-});
+await signin();                   // register or login — one call
+const session = await isItMe();  // silent check — no UI
+await logout();                   // end session
 ```
 
-## Browser client
+`signin()` checks if a passkey exists for this domain. First visit triggers registration, every visit after triggers login. No branching logic needed.
 
-For custom login pages, import the browser helpers:
+For manual control, use `login()` and `register()` directly:
 
 ```js
-import { register, login, getAuthStatus } from "isitme/browser";
+import { login, register, isItMe, IsitmeError } from "isitme/browser";
 
-const status = await getAuthStatus();
-
-if (!status.isSetup) {
-  await register();
-} else {
+try {
   await login();
+} catch (err) {
+  if (err instanceof IsitmeError && err.code === "NOT_SETUP") {
+    await register();  // no passkey yet — register first
+  }
 }
 ```
 
-## Custom storage
-
-Implement the `StorageAdapter` interface to use any backend:
-
-```js
-import { isitme } from "isitme";
-
-app.use(isitme({
-  storage: {
-    isSetupComplete() { /* ... */ },
-    getUser() { /* ... */ },
-    getCredentials() { /* ... */ },
-    getCredentialById(id) { /* ... */ },
-    saveUserAndCredential(user, credential) { /* ... */ },
-    updateCredentialCounter(id, counter) { /* ... */ },
-    getAuthDataJson() { /* ... */ },
-  }
-}));
-```
+## Docs
 
-## How it works
+Full API reference, configuration options, and framework guides:
 
-1. `isitme()` adds auth routes (`/auth/*`) and a guard middleware to your app
-2. Unauthenticated visitors see a built-in login page
-3. Registration creates a WebAuthn passkey tied to the device's biometrics
-4. Login verifies the passkey and sets a JWT session cookie
-5. `req.isAuthenticated` is available on every request
+**https://isitme.dev/docs**
 
-## License
+## Links
 
-MIT
+- **Docs:** https://isitme.dev/docs
+- **GitHub:** https://github.com/isitme-dev/isitme
+- **npm:** https://www.npmjs.com/package/isitme

package/dist/browser.d.ts

@@ -2,6 +2,10 @@ interface AuthStatus {
     setupComplete: boolean;
     isAuthenticated: boolean;
 }
+interface Session {
+    authenticated: true;
+    registered: true;
+}
 interface RegisterResult {
     verified: boolean;
     authData?: string;
@@ -9,15 +13,43 @@ interface RegisterResult {
 interface LoginResult {
     verified: boolean;
 }
+interface SigninResult {
+    verified: boolean;
+    action: "register" | "login";
+    authData?: string;
+}
+type IsitmeErrorCode = "NOT_SETUP" | "ALREADY_SETUP" | "CREDENTIAL_NOT_FOUND" | "CHALLENGE_EXPIRED" | "VERIFICATION_FAILED" | "SITE_NOT_FOUND" | "SITE_BLOCKED" | "NETWORK_ERROR" | "PASSKEY_CANCELLED" | "UNKNOWN";
+declare class IsitmeError extends Error {
+    code: IsitmeErrorCode;
+    cause?: Error;
+    constructor(code: IsitmeErrorCode, message: string, cause?: Error);
+}
 interface IsitmeBrowserOptions {
-    /** Auth API prefix. Default: `/auth` */
+    /** Auth API prefix. Default: `/_isitme` */
     prefix?: string;
+    /** Cloud API URL (e.g. `https://api.isitme.dev`). When set, auth uses the cloud API + localStorage instead of same-origin cookies. */
+    api?: string;
 }
 
-declare function register(opts?: IsitmeBrowserOptions): Promise<RegisterResult>;
+declare function signin(opts?: IsitmeBrowserOptions): Promise<SigninResult>;
+
+/**
+ * Silent session check. Returns session info if authenticated, null otherwise.
+ * Never shows UI — use `login()` or `register()` for that.
+ */
+declare function isItMe(opts?: IsitmeBrowserOptions): Promise<Session | null>;
+
+/**
+ * End the current session. Works in both server and cloud mode.
+ * Server mode: POSTs to `/_isitme/logout` to clear the session cookie.
+ * Cloud mode: clears the session from localStorage.
+ */
+declare function logout(opts?: IsitmeBrowserOptions): Promise<void>;
 
 declare function login(opts?: IsitmeBrowserOptions): Promise<LoginResult>;
 
+declare function register(opts?: IsitmeBrowserOptions): Promise<RegisterResult>;
+
 declare function getAuthStatus(opts?: IsitmeBrowserOptions): Promise<AuthStatus>;
 
-export { type AuthStatus, type IsitmeBrowserOptions, type LoginResult, type RegisterResult, getAuthStatus, login, register };
+export { type AuthStatus, type IsitmeBrowserOptions, IsitmeError, type IsitmeErrorCode, type LoginResult, type RegisterResult, type Session, type SigninResult, getAuthStatus, isItMe, login, logout, register, signin };

package/dist/browser.js

@@ -355,46 +355,308 @@ async function startAuthentication(options) {
 }
 
 // ../browser/dist/index.js
-async function register(opts = {}) {
-  const prefix = opts.prefix || "/auth";
-  const optRes = await fetch(`${prefix}/register/options`, { method: "POST" });
-  if (!optRes.ok) throw new Error("Failed to get registration options");
-  const { options, nonce, userId } = await optRes.json();
-  const registration = await startRegistration({ optionsJSON: options });
-  const verifyRes = await fetch(`${prefix}/register/verify`, {
+var IsitmeError = class extends Error {
+  code;
+  cause;
+  constructor(code, message, cause) {
+    super(message);
+    this.name = "IsitmeError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+var DEFAULT_PREFIX = "/_isitme";
+var STORAGE_KEY = "isitme_session";
+var Errors = {
+  SETUP_COMPLETE: "Setup already complete",
+  NO_CREDENTIALS: "No credentials registered",
+  CHALLENGE_EXPIRED: "Challenge expired",
+  VERIFICATION_FAILED: "Verification failed",
+  CREDENTIAL_NOT_FOUND: "Credential not found"
+};
+function getDomain() {
+  return location.hostname;
+}
+function getCloudSession() {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function saveSession(data) {
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+}
+function clearCloudSession() {
+  localStorage.removeItem(STORAGE_KEY);
+}
+async function apiPost(api, path, body) {
+  const res = await fetch(api + path, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ nonce, userId, response: registration })
+    body: JSON.stringify(body)
   });
-  const result = await verifyRes.json();
-  if (!verifyRes.ok) throw new Error(result.error || "Registration failed");
-  return result;
+  const data = await res.json();
+  if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+  return data;
 }
-async function login(opts = {}) {
-  const prefix = opts.prefix || "/auth";
-  const optRes = await fetch(`${prefix}/login/options`, { method: "POST" });
-  if (!optRes.ok) throw new Error("Failed to get login options");
-  const { options, nonce } = await optRes.json();
-  const authentication = await startAuthentication({ optionsJSON: options });
-  const verifyRes = await fetch(`${prefix}/login/verify`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ nonce, response: authentication })
+async function cloudRegister(api) {
+  const domain = getDomain();
+  const ch = await apiPost(api, "/v1/challenge", {
+    domain,
+    type: "registration"
+  });
+  const regResp = await startRegistration({
+    optionsJSON: {
+      challenge: ch.challenge,
+      rp: { name: ch.rpName, id: ch.rpId },
+      user: {
+        id: crypto.randomUUID(),
+        name: domain + "-owner",
+        displayName: domain + " owner"
+      },
+      pubKeyCredParams: [
+        { alg: -7, type: "public-key" },
+        { alg: -257, type: "public-key" }
+      ],
+      authenticatorSelection: {
+        residentKey: "preferred",
+        userVerification: "preferred"
+      },
+      timeout: 6e4,
+      attestation: "none"
+    }
   });
-  if (!verifyRes.ok) {
-    const data = await verifyRes.json();
-    throw new Error(data.error || "Authentication failed");
+  const result = await apiPost(api, "/v1/register", {
+    challengeId: ch.challengeId,
+    credentialId: regResp.id,
+    publicKey: regResp.response.publicKey,
+    signCount: 0,
+    transports: regResp.response.transports || []
+  });
+  saveSession({
+    userId: result.userId,
+    siteId: result.siteId,
+    credentialId: regResp.id,
+    transports: regResp.response.transports || [],
+    authenticatedAt: Date.now(),
+    domain
+  });
+  return { verified: true };
+}
+async function cloudLogin(api) {
+  const domain = getDomain();
+  const existing = getCloudSession();
+  const ch = await apiPost(api, "/v1/challenge", {
+    domain,
+    type: "authentication"
+  });
+  const allowCredentials = ch.credentialIds.map((id) => ({
+    id,
+    type: "public-key",
+    transports: existing?.transports || []
+  }));
+  const authResp = await startAuthentication({
+    optionsJSON: {
+      challenge: ch.challenge,
+      rpId: ch.rpId,
+      allowCredentials,
+      timeout: 6e4,
+      userVerification: "preferred"
+    }
+  });
+  const result = await apiPost(api, "/v1/authenticate", {
+    challengeId: ch.challengeId,
+    credentialId: authResp.id,
+    signCount: 0
+  });
+  saveSession({
+    userId: result.userId,
+    siteId: result.siteId,
+    credentialId: authResp.id,
+    transports: existing?.transports || [],
+    authenticatedAt: Date.now(),
+    domain
+  });
+  return { verified: true };
+}
+async function cloudStatus(api) {
+  const domain = getDomain();
+  const session = getCloudSession();
+  let setupComplete = false;
+  try {
+    const res = await fetch(api + "/v1/site/" + encodeURIComponent(domain));
+    if (res.ok) {
+      const data = await res.json();
+      setupComplete = data.setupComplete === true;
+    }
+  } catch {
+    setupComplete = !!session;
+  }
+  return {
+    setupComplete,
+    isAuthenticated: !!session
+  };
+}
+function cloudIsItMe() {
+  const session = getCloudSession();
+  if (session) {
+    return { authenticated: true, registered: true };
   }
-  return verifyRes.json();
+  return null;
 }
 async function getAuthStatus(opts = {}) {
-  const prefix = opts.prefix || "/auth";
-  const res = await fetch(`${prefix}/status`);
-  if (!res.ok) throw new Error("Failed to fetch auth status");
+  if (opts.api) return cloudStatus(opts.api);
+  const prefix = opts.prefix || DEFAULT_PREFIX;
+  const url = `${prefix}/status`;
+  const res = await fetch(url, { credentials: "include" });
+  if (!res.ok) throw new Error(`Auth status check failed: ${res.status} from ${url}`);
   return res.json();
 }
+function classifyRegisterError(err) {
+  if (err instanceof IsitmeError) return err;
+  const msg = err instanceof Error ? err.message : String(err);
+  if (msg.includes(Errors.SETUP_COMPLETE) || msg.includes("already has an owner"))
+    return new IsitmeError("ALREADY_SETUP", "This domain already has an owner. Use login() or signin() instead.", err instanceof Error ? err : void 0);
+  if (msg.includes(Errors.CHALLENGE_EXPIRED))
+    return new IsitmeError("CHALLENGE_EXPIRED", "Registration challenge expired. Please try again.", err instanceof Error ? err : void 0);
+  if (msg.includes(Errors.VERIFICATION_FAILED))
+    return new IsitmeError("VERIFICATION_FAILED", "Passkey verification failed during registration.", err instanceof Error ? err : void 0);
+  if (msg.includes("Site not found"))
+    return new IsitmeError("SITE_NOT_FOUND", "Domain not found. The cloud API may be unreachable.", err instanceof Error ? err : void 0);
+  if (msg.includes("blocked"))
+    return new IsitmeError("SITE_BLOCKED", "This domain has been blocked.", err instanceof Error ? err : void 0);
+  if (msg.includes("The operation either timed out") || msg.includes("NotAllowedError") || msg.includes("cancelled") || msg.includes("canceled") || msg.includes("AbortError"))
+    return new IsitmeError("PASSKEY_CANCELLED", "Passkey prompt was cancelled or timed out.", err instanceof Error ? err : void 0);
+  return new IsitmeError("UNKNOWN", `Registration failed: ${msg}`, err instanceof Error ? err : void 0);
+}
+async function register(opts = {}) {
+  try {
+    if (opts.api) return await cloudRegister(opts.api);
+    const prefix = opts.prefix || DEFAULT_PREFIX;
+    const optUrl = `${prefix}/register/start`;
+    const optRes = await fetch(optUrl, { method: "POST", credentials: "include" });
+    if (!optRes.ok) {
+      const body = await optRes.json().catch(() => null);
+      throw new Error(body?.error || `Registration options failed: ${optRes.status} from ${optUrl}`);
+    }
+    const { options, nonce, userId } = await optRes.json();
+    const registration = await startRegistration({ optionsJSON: options });
+    const verifyUrl = `${prefix}/register/finish`;
+    const verifyRes = await fetch(verifyUrl, {
+      method: "POST",
+      credentials: "include",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ nonce, userId, response: registration })
+    });
+    const result = await verifyRes.json();
+    if (!verifyRes.ok) throw new Error(result.error || `Registration verify failed: ${verifyRes.status} from ${verifyUrl}`);
+    return result;
+  } catch (err) {
+    throw classifyRegisterError(err);
+  }
+}
+function classifyLoginError(err) {
+  if (err instanceof IsitmeError) return err;
+  const msg = err instanceof Error ? err.message : String(err);
+  if (msg.includes(Errors.NO_CREDENTIALS) || msg.includes("not complete"))
+    return new IsitmeError("NOT_SETUP", "No passkey registered for this domain. Use register() or signin() first.", err instanceof Error ? err : void 0);
+  if (msg.includes(Errors.CREDENTIAL_NOT_FOUND))
+    return new IsitmeError("CREDENTIAL_NOT_FOUND", "Passkey not recognized. It may have been removed or registered on a different domain.", err instanceof Error ? err : void 0);
+  if (msg.includes(Errors.CHALLENGE_EXPIRED))
+    return new IsitmeError("CHALLENGE_EXPIRED", "Authentication challenge expired. Please try again.", err instanceof Error ? err : void 0);
+  if (msg.includes(Errors.VERIFICATION_FAILED))
+    return new IsitmeError("VERIFICATION_FAILED", "Passkey verification failed. Try again or re-register.", err instanceof Error ? err : void 0);
+  if (msg.includes("The operation either timed out") || msg.includes("NotAllowedError") || msg.includes("cancelled") || msg.includes("canceled") || msg.includes("AbortError"))
+    return new IsitmeError("PASSKEY_CANCELLED", "Passkey prompt was cancelled or timed out.", err instanceof Error ? err : void 0);
+  return new IsitmeError("UNKNOWN", `Login failed: ${msg}`, err instanceof Error ? err : void 0);
+}
+async function login(opts = {}) {
+  try {
+    if (opts.api) return await cloudLogin(opts.api);
+    const prefix = opts.prefix || DEFAULT_PREFIX;
+    const optUrl = `${prefix}/login/start`;
+    const optRes = await fetch(optUrl, { method: "POST", credentials: "include" });
+    if (!optRes.ok) {
+      const body = await optRes.json().catch(() => null);
+      throw new Error(body?.error || `Login options failed: ${optRes.status} from ${optUrl}`);
+    }
+    const { options, nonce } = await optRes.json();
+    const authentication = await startAuthentication({ optionsJSON: options });
+    const verifyUrl = `${prefix}/login/finish`;
+    const verifyRes = await fetch(verifyUrl, {
+      method: "POST",
+      credentials: "include",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ nonce, response: authentication })
+    });
+    if (!verifyRes.ok) {
+      const data = await verifyRes.json().catch(() => null);
+      throw new Error(data?.error || `Login verify failed: ${verifyRes.status} from ${verifyUrl}`);
+    }
+    return verifyRes.json();
+  } catch (err) {
+    throw classifyLoginError(err);
+  }
+}
+async function signin(opts = {}) {
+  let status;
+  try {
+    status = await getAuthStatus(opts);
+  } catch (err) {
+    throw new IsitmeError(
+      "NETWORK_ERROR",
+      "Could not check auth status. Make sure isitme middleware is running or the cloud API is reachable.",
+      err instanceof Error ? err : void 0
+    );
+  }
+  if (status.setupComplete) {
+    const result = await login(opts);
+    return { verified: result.verified, action: "login" };
+  } else {
+    const result = await register(opts);
+    return { verified: result.verified, action: "register", authData: result.authData };
+  }
+}
+async function isItMe(opts = {}) {
+  if (opts.api) return cloudIsItMe();
+  const prefix = opts.prefix || DEFAULT_PREFIX;
+  const res = await fetch(`${prefix}/status`, { credentials: "include" });
+  if (!res.ok) return null;
+  const status = await res.json();
+  if (status.isAuthenticated) {
+    return { authenticated: true, registered: true };
+  }
+  return null;
+}
+async function logout(opts = {}) {
+  if (opts.api) {
+    clearCloudSession();
+    return;
+  }
+  const prefix = opts.prefix || DEFAULT_PREFIX;
+  const url = `${prefix}/logout`;
+  try {
+    const res = await fetch(url, { method: "POST", credentials: "include" });
+    if (!res.ok) {
+      throw new Error(`Logout failed: ${res.status} from ${url}`);
+    }
+  } catch (err) {
+    throw new IsitmeError(
+      "NETWORK_ERROR",
+      "Could not reach the auth server to log out.",
+      err instanceof Error ? err : void 0
+    );
+  }
+}
 export {
+  IsitmeError,
   getAuthStatus,
+  isItMe,
   login,
-  register
+  logout,
+  register,
+  signin
 };

package/dist/express.d.ts

@@ -0,0 +1,100 @@
+import { Response, Request, Router } from 'express';
+
+interface StoredCredential {
+    id: string;
+    publicKey: string;
+    counter: number;
+    transports?: AuthenticatorTransport[];
+}
+interface StoredUser {
+    id: string;
+    username: string;
+}
+interface StorageAdapter {
+    isSetupComplete(): boolean | Promise<boolean>;
+    getUser(): StoredUser | null | Promise<StoredUser | null>;
+    getCredentials(): StoredCredential[] | Promise<StoredCredential[]>;
+    getCredentialById(id: string): StoredCredential | undefined | Promise<StoredCredential | undefined>;
+    saveUserAndCredential(user: StoredUser, credential: StoredCredential): void | Promise<void>;
+    updateCredentialCounter(id: string, counter: number): void | Promise<void>;
+    getAuthDataJson(): string | Promise<string>;
+}
+interface PageOptions {
+    title?: string;
+    heading?: string;
+    brandColor?: string;
+    logoUrl?: string;
+    description?: string;
+    brandName?: string;
+}
+interface IsitmeOptions {
+    /** JWT signing secret. If omitted, a random secret is generated (sessions won't survive restarts). */
+    sessionSecret?: string;
+    /** File path for JSON storage, `false` for in-memory, or a custom StorageAdapter. Default: `"./auth.json"` */
+    storage?: string | false | StorageAdapter;
+    /** Route prefix for auth endpoints. Default: `"/_isitme"` */
+    prefix?: string;
+    /** Session cookie name. Default: `"isitme_session"` */
+    cookieName?: string;
+    /** Session max age in seconds. Default: `86400` (1 day) */
+    sessionMaxAge?: number;
+    /** WebAuthn Relying Party ID. Default: auto from hostname */
+    rpId?: string;
+    /** WebAuthn RP display name. Default: `"isitme"` */
+    rpName?: string;
+    /** WebAuthn origin. Default: auto from request */
+    origin?: string;
+    /** Extra paths to skip auth for (in addition to auth routes and static files). */
+    publicPaths?: string[];
+    /** Login page config. Set to `false` to disable the built-in page. */
+    loginPage?: false | PageOptions;
+    /** Callback after first passkey registration. Receives the auth data JSON string. */
+    onRegister?: (authData: string) => void;
+    /** Set cookie Secure flag. Default: `true`. Express adapter passes `process.env.NODE_ENV === "production"`. */
+    secure?: boolean;
+    /** Skip auth entirely on localhost (127.0.0.1 / localhost). Only for development. Default: `false` */
+    bypassAuthOnLocalhost?: boolean;
+}
+interface RequestInfo {
+    hostname: string;
+    protocol: string;
+    host: string;
+}
+interface CookieConfig {
+    name: string;
+    maxAge: number;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "strict" | "lax" | "none";
+    path: string;
+}
+interface SetCookieAction {
+    name: string;
+    value: string;
+    options: CookieConfig;
+}
+interface ClearCookieAction {
+    name: string;
+    options: CookieConfig;
+}
+interface HandlerResult {
+    status: number;
+    body?: unknown;
+    html?: string;
+    redirect?: string;
+    setCookie?: SetCookieAction;
+    clearCookie?: ClearCookieAction;
+}
+
+declare global {
+    namespace Express {
+        interface Request {
+            isAuthenticated?: boolean;
+        }
+    }
+}
+declare function getRequestInfo(req: Request): RequestInfo;
+declare function applyResult(res: Response, result: HandlerResult): void;
+declare function isitme(options?: IsitmeOptions): Router;
+
+export { applyResult, getRequestInfo, isitme };