IP Access Control (Keystore)

Persistent allow/deny lists stored in your configured KeyStore. Manage lists at runtime and keep them across restarts.

How It Works

Store IP rules in your database so they persist across app restarts:

Saves allow/deny lists in your key storage system
Changes survive app restarts and server changes
Manage lists at runtime with helper functions
Same blocking logic as other IP plugins

Settings

Option	Type	Default	Description
`allow`	`string[]`	`[]`	Starting allowed IPs
`deny`	`string[]`	`[]`	Starting blocked IPs
`recordId`	`string`	`"__uk_ip_acl__"`	Database key for storing rules

Usage

import { usefulkey, ipAccessControlKeystore } from "usefulkey";

// Start with empty lists (stored in database)
const uk = usefulkey({}, { plugins: [ipAccessControlKeystore()] });

// Add/remove IPs (saved to database automatically)
await uk.ipAccessControlStore.addAllow("127.0.0.1");
await uk.ipAccessControlStore.addDeny("10.0.0.1");
await uk.ipAccessControlStore.removeAllow("127.0.0.1");

// Check current rules
const allowed = await uk.ipAccessControlStore.getAllow();
const blocked = await uk.ipAccessControlStore.getDeny();

// Clear all rules
await uk.ipAccessControlStore.clearAllow();
await uk.ipAccessControlStore.clearDeny();

// Reload from database (if needed)
await uk.ipAccessControlStore.refresh();

// Verify with IP
const result = await uk.verifyKey({ key, ip: "192.168.1.1" });

Starting with Pre-loaded Rules

const uk = usefulkey({}, {
  plugins: [
    ipAccessControlKeystore({
      allow: ["127.0.0.1"],     // Start with these allowed
      deny: ["10.0.0.1"],       // Start with these blocked
      recordId: "__my_ip_rules__", // Custom storage key
    })
  ]
});

New Functions

Manage persistent IP rules with uk.ipAccessControlStore:

addAllow(ip) / removeAllow(ip) - Add/remove allowed IPs
addDeny(ip) / removeDeny(ip) - Add/remove blocked IPs
clearAllow() / clearDeny() - Clear all rules
getAllow() / getDeny() - See current lists
refresh() - Reload rules from database

What Happens During Verification

IP in deny list → { valid: false, reason: "ip_denied" }
Allow list exists but IP not in it → { valid: false, reason: "ip_not_allowed" }

Analytics Events

Tracks all IP access decisions:

Blocked: "ip_access.blocked" with IP and reason
Allowed: "ip_access.allowed" with IP and rule used

Combining with Other IP Plugins

Use multiple IP plugins together for maximum control:

const uk = usefulkey({}, {
  plugins: [
    ipAccessControlStatic({
      deny: ["9.9.9.9"]  // Always block this IP
    }),
    ipAccessControlMemory({
      allow: ["1.2.3.4"]  // Temporary access
    }),
    ipAccessControlKeystore({
      allow: ["5.6.7.8"]  // Persistent access
    }),
  ],
});

How they work together:

Deny rules: IP blocked if in ANY plugin's deny list
Allow rules: Must be in ALL plugins' allow lists
Order doesn't matter - same result regardless of plugin order
Only affects logging - which plugin reports the event

IP Access Control (Keystore)

On this page