new StarVault(dbPath, logPath, shardCount, maxLogSize, logRetention, options)

authOptions: {
  lockout: {
    strategy: "fixed",
    scopes: ["account", "ipua"],
    maxAttempts: 5,                     // lock after N total failures
    baseDuration: 15 * 60 * 1000,       // fixed lock duration (with jitter)
    minDuration: 30 * 1000,
          jitterDuration: 15 * 1000,          // desync scripted retries
    decayDuration: 30 * 60 * 1000,      // clear counters after idle period
  
    // Optional human gates
    captchaAfter: 3,
    otpAfter: null,
    captchaVerifier: async (req) => verifyCaptcha(req.body.token),
  
    //  Heuristics amplify bursts, forgive human pace
    timingHeuristics: {
      enabled: true,
      burstDetectionDuration: 3000,
      humanDetectionDuration: 45000,
      burstWeight: 2.0,
      normalWeight: 1.0,
      graceWeight: 0.0,
      emaAlpha: 0.3,
      decayOnGrace: true,
      decayStep: 1,
      minFailures: 0,
      maxFailures: 9999
    },
  
    onLock: (info) => console.log("LOCKED", info),
    onUnlock: (info) => console.log("UNLOCKED", info),
    onChallenge: (info) => console.log("CHALLENGE", info),
    bypassed: (req) => false
  }
}

authOptions: {
  lockout: {
    strategy: "slidingWindow",
    scopes: ["account", "ipua"],
    
    windowDuration: 10 * 60 * 1000,
          windowThreshold: 7,
    
          baseDuration: 60 * 1000,
          minDuration: 30 * 1000,
          maxDuration: 24 * 60 * 60 * 1000,
          jitterDuration: 15 * 1000,
    
          windowGrowth: "exponential",
          windowGrowthFactor: 2,
          // windowGrowthStep: 30 * 1000, // if using "linear"

    // Optional Human gates
    captchaAfter: 3,
    otpAfter: null,
    captchaVerifier: async (req) => verifyCaptcha(req.body.token),

    // Heuristics amplify bursts, forgive human pace
    timingHeuristics: {
      enabled: true,
      burstDetectionDuration: 2000,
      humanDetectionDuration: 45000,
      burstWeight: 2.5,
      normalWeight: 1.0,
      graceWeight: 0.0,
      emaAlpha: 0.35,
      decayOnGrace: true,
      decayStep: 1,
      minFailures: 0,
      maxFailures: 9999
    },

    onLock: (info) => console.log("LOCKED", info),
    onUnlock: (info) => console.log("UNLOCKED", info),
    onChallenge: (info) => console.log("CHALLENGE", info),
    bypassed: (req) => false
  }
}

authOptions: {
  lockout: {
    strategy: "exponential",
    scopes: ["account", "ipua"],
    maxAttempts: 5,
    baseDuration: 30 * 1000,
          minDuration: 30 * 1000,
          maxDuration: 24 * 60 * 60 * 1000,
          jitterDuration: 10 * 1000,
    captchaAfter: 3,
    otpAfter: 5,
    captchaVerifier: async (req) => verifyCaptcha(req.body.token),
    otpVerifier: async ({ email, code }) => verifyOtp(email, code),
    onLock: (info) => console.log("LOCKED", info),
    onUnlock: (info) => console.log("UNLOCKED", info),
    timingHeuristics: {
      enabled: true,
      burstWeight: 3.0,
      graceWeight: 0.0,
      emaAlpha: 0.4
    }
  }
}

authOptions: {
  // Modern lockout (recommended)
  lockout: {
    strategy: "exponential",
    scopes: ["account", "ipua"],
    maxAttempts: 5,
    baseDuration: 15 * 60 * 1000,    // 15 minutes
    maxDuration: 24 * 60 * 60 * 1000 // 24 hours
    // ...captcha/otp/timingHeuristics, etc.
  },

 maxLoginAttempts: 5,
  lockoutDuration: 15 * 60 * 1000
}

geo: {
  requestIP: "203.0.113.45",
  ip: "203.0.113.45",
  city: "City",
  region: "Region",
  country: "Country",
  continent: "Continent",
  org: "Org / ASN",
  isp: "ISP",
  loc: "12.3456,-98.7654",
  timezone: "Area/City",
  postal: "ZIP",
  flag: "🌍",
  confidence: 0.83,
  geoAddress: "123 Main St, Example City, Country"
}

const vault = new StarVault(dataDir, logDir, 4, "869MB", "1w", {
  authOptions: {
    enableGeo: true,
    enableReverseGeo: true,
    ipinfoToken: process.env.IPINFO_TOKEN,
    geoProviders: [
      async function customProvider(ip, { signal }) {
        return { city: "Custom City", country: "Customland" };
      }
    ]
  }
});

// High-level helper
const { transactionID, result } = await vault.transact({ type: "transfer" }, async (t) => {
     await t.update("accounts", "A", { balance: v => v - 100 });
     await t.update("accounts", "B", { balance: v => v + 100 });
     await t.create("ledger", { from: "A", to: "B", amount: 100, ts: Date.now() });
     return "ok";
});

// Manual flow
const tx = await vault.begin({ type: "batch-import" });
await tx.create("users", { id: "u1", name: "Nova" });
await tx.softDelete("posts", "p-123", { reason: "policy", deletedBy: "mod-9" });
await tx.restore("posts", "p-123", { restoredBy: "mod-9" });
await tx.commit(); // or await tx.abort("reason");

await vault.transact({ actor: "u42" }, async (tx) => {
     await tx.create("users", { id: "42", name: "Orion" });
     await tx.update("profiles", "42", { visits: v => v + 1 });
     await tx.softDelete("sessions", "s-23", { reason: "expired", deletedBy: "system" });
});

vault.query("collection")
     .whereRecord("id", "value")                         // Filters root record data by key-value pairs
     .where({ key: "value" })                         // Filters record data by key-value pairs
     .search("field", "text")                         // Text search within a specific field
     .recent("timestamp", "7d")                       // Gets records from the last 7 days
     .near("location", { lat: 0, lng: 0 }, 50)        // Geospatial filter within 50 units
     .sort({ name: 1 })                               // Sorts by a field (1 = asc, -1 = desc)
     .select(["id", "name"])                          // Selects specific fields
     .limit(10)                                       // Limits results
     .offset(0)                                       // Skips first N records
     .filterBy(record => record.active)              // Filters with custom function
     .execute(exactCollection = false)                // Run the query with optional strict collection matching

// Full history (archived segments + checksum verification)
const history = vault.getRecordHistory("users/region1", "1760233994625", {
  includeArchived: true,
  verifyChecksums: true
}, { actor: "admin-1" }, { token: "valid" });

// Windowed, updates only
const updates = vault.getRecordHistory("users/region1", "1760233994625", {
  actions: "UPDATE",
  since: Date.now() - 60_000,
  until: Date.now()
});

// Compact timeline, no deletions, explicit audit
const timeline = vault.getRecordTimeline("users/region1", "1760233994625", {
  excludeActions: ["DELETE", "SOFT_DELETE"]
}, { audit: true }, { token: "valid" });

const vault = new StarVault("./data", "./logs", 4, "869MB", "1w", {
  auditHistory: true
});

vault.getRecordHistory("orders", "o-123", { audit: true });

vault.listen("create", "*", (path, data) => {
     console.log("Created:", path, data);
});

vault.listen("update", "*", (path, data) => {
     console.log("Updated:", path, data);
});

vault.listen("delete", "*", (path, data) => {
     console.log("Deleted:", path, data);
});

vault.listen("create", "users/*", (path, data) => {
     console.log("User created:", path, data);
});

vault.listen("update", "inventory/*", (path, data) => {
     console.log("Inventory updated:", path, data);
});

vault.listen("update", "orders/12345", (path, data) => {
     console.log("Order updated:", data);
});

vault.listen("delete", "accounts/user-abc", (path, data) => {
     console.log("User deleted:", data);
});

// Match nested logs by year
vault.listen("update", "logs/*/2025/*", (path, data) => {
     console.log("Log updated:", path);
});

vault.on("guest:upgraded", (info) => {
     console.log("Guest upgraded:", info);
});

vault.on("user:deleted", (info) => {
     console.log("User deleted:", info);
});

vault.on("user:reactivated", (info) => {
     console.log("User reactivated:", info);
});

vault.listen("tx:commit", "*", (id, info) => {
     console.log("Committed txn:", id, info);
});

vault.listen("tx:abort", "*", (id, info) => {
     console.log("Aborted txn:", id, info);
});

vault.on("tx:summary", (transactionID, summary) => {
    console.log("Transaction Summary:", transactionID, summary);
});

const StarVault = require("@trap_stevo/star-vault");

const vault = new StarVault(
     "./data",
     "./logs",
     4,
     "869MB",
     "1w",
     {
          enableEncryption : true,
          masterKey : "supersecretkey",
          authHandler : (auth) => auth.token === "valid-token"
     }
);

vault.create("users", { id : "001", name : "Nova" }, { source : "init" }, { token : "valid-token" });

const results = vault.query("users")
     .where({ role : "admin" })
     .sort({ name : 1 })
     .select(["id", "name"])
     .limit(10)
     .execute();

vault.listen("create", "*", (path, data) => {
     console.log("[CREATE - ANY] Path:", path, data);
});

vault.listen("create", "users/*", (path, data) => {
     console.log("[CREATE - users] Path:", path, data);
});

vault.listen("update", "users/*", (path, data) => {
     console.log("[UPDATE - users] Path:", path, data);
});

// Listen for updates to a specific user record (e.g., user ID '001')
vault.listen("update", "users/user-001", (path, data) => {
     console.log("[UPDATE - users/user-001] Path:", path, data);
});

vault.listen("delete", "users/*", (path, data) => {
     console.log("[DELETE - users] Path:", path, data);
});

vault.listen("delete", "logs/*/2025", (path, data) => {
     console.log("[DELETE - logs/*/2025] Path:", path, data);
});

// Listen for a specific log record inside a structured path (e.g., logs/server1/2025/log-99)
vault.listen("create", "logs/server1/2025/log-99", (path, data) => {
     console.log("[CREATE - logs/server1/2025/log-99] Path:", path, data);
});

// Listen to everything happening in 'auth-sessions'
vault.listen("create", "auth-sessions", (path, data) => {
     console.log("[CREATE - auth-sessions] Path:", path, data);
});

vault.listen("update", "auth-sessions", (path, data) => {
     console.log("[UPDATE - auth-sessions] Path:", path, data);
});

vault.listen("delete", "auth-sessions", (path, data) => {
     console.log("[DELETE - auth-sessions] Path:", path, data);
});

vault.query("logs/*/2025")
     .recent("timestamp", "7d")
     .execute();

const StarVault = require("@trap_stevo/star-vault");

const vault = new StarVault(
     "./data",
     "./logs",
     4,
     "869MB",
     "1w",
     {
          enableEncryption : true,
          masterKey : "supersecretkey",
          authHandler : (auth) => auth.token === "star-vault-demo",
          authOptions : {
               allowGuestSessions : true,
               generateGuestID : () =>  "guest-" + Math.floor(Math.random() * 1000000)
          }
     }
);

// Register a full user
const userResult = await vault.registerUser("nova@example.com", "strongpassword123", { source : "site" }, { token : "star-vault-demo" });
console.log("Registered user:", userResult);

// Register a guest user
const guestResult = await vault.registerGuestUser({ ip : "127.0.0.1" }, { referrer : "home" }, { source : "guest-form" }, { token : "star-vault-demo" });
console.log("Registered guest:", guestResult);

const StarVault = require("@trap_stevo/star-vault");

const vault = new StarVault(
     "./data",
     "./logs",
     4,
     "869MB",
     "1w",
     {
          enableEncryption : true,
          masterKey : "supersecretkey",
          authHandler : (auth) => auth.token === "star-vault-demo"
     }
);

// List all users
const users = await vault.listUsers({}, { limit : 25 }, { token : "star-vault-demo" });
console.log("All users:", users);

// List all sessions (including inactive and deleted)
const sessions = await vault.listAllSessions({ includeDeleted : "only" }, true, { token : "star-vault-demo" });
console.log("All sessions:", sessions);

// List sessions for a specific user
const userSessions = await vault.listSessions("user-001", { device : "mobile" }, false, { token : "star-vault-demo" });
console.log("Sessions for user-001:", userSessions);

// List recent user activity (active and inactive)
const activity = await vault.listUserActivity({
     includeInactive : true,
     onlyMostRecent : true
}, { token : "star-vault-demo" });

console.log("User activity:", activity);