IP Access Control (Static)

How it works

• Provide allow and/or deny lists at startup. They cannot be changed at runtime.
• On verify, pass the caller IP (ip) so the plugin can evaluate.
• If the IP is present in deny, verification rejects with "ip_denied".
• If allow is non-empty and the IP is not in it, verification rejects with "ip_not_allowed".

Settings

Usage

import { usefulkey } from "betterkey";
import { ipAccessControlStatic, ipAccessControlMemory } from "betterkey/plugins";

const uk = usefulkey({}, {
  plugins: [
    ipAccessControlStatic({ allow: ["127.0.0.1"], deny: ["10.0.0.1"] }),
  ],
});

// On verify, provide the caller IP
const res = await uk.verifyKey({ key, ip: "127.0.0.1" });

Functions added

This static variant does not add runtime management helpers.

Verification behavior

• Deny list match → { valid: false, reason: "ip_denied" }
• Allow list present and no match → { valid: false, reason: "ip_not_allowed" }

Emitted analytics on block: "ip_access.blocked" with { ip, rule: "deny" | "allow_list_missing", plugin: "ip-access-control:static", ts }.

Using with Memory IP Access Control

You can enable the static and memory variants at the same time. Both plugins run on each verification and the decision is combined:

• Deny lists are a union: if the IP appears in any plugin's deny, it is blocked.
• Allow lists act as an intersection: if any plugin has a non-empty allow, the IP must be present in all such allow lists.
• Order does not change the outcome. It only affects which plugin logs the block event.

import { usefulkey } from "betterkey";

const uk = usefulkey({}, {
  plugins: [
    ipAccessControlStatic({ allow: ["1.2.3.4"], deny: ["9.9.9.9"] }),
    ipAccessControlMemory({ allow: ["1.2.3.4", "2.2.2.2"] }),
  ],
});

// On verify, provide the caller IP
await uk.verifyKey({ key, ip: "1.2.3.4" });