@network-decode/node-guard 0.0.0-stage → 0.2.0-alpha.6

package/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+Open a focused issue or pull request with a reproducible case. Run `npm test` and `npm run smoke:package` before submitting. Do not include customer data, secrets, private HoneyMesh bridge code, or proprietary release artifacts. Security issues should follow SECURITY.md.

package/DEVELOPER_SETUP.md

@@ -0,0 +1,33 @@
+# Developer setup
+
+1. Use Node.js 20 or newer in a persistent Node process. Install `@network-decode/node-guard@0.2.0-alpha.6` and run `npx nodeguard init`.
+2. Run `npx nodeguard doctor nodeguard.policy.json`. The `source_trust: not checked` result means the CLI cannot verify your ingress topology.
+3. Inspect the generated OBSERVE policy. Set `application_id` and `route_id` to stable identifiers. Keep `mode` as `OBSERVE` until normal traffic has been reviewed.
+4. Determine the actual socket peer address. If a reverse proxy is used, list each trusted proxy IP in `createTrustedSourceResolver({ trustedProxyIps })`. Never trust `X-Forwarded-For` from an unlisted peer.
+5. Let application authentication and route handlers identify verified events. Use `createPolicyGuardV1` and call `record` for explicit events only. Use a random unique `event_id` for each observation. Avoid logging credentials or request bodies.
+6. Run `nodeguard policy test` against representative sanitized observations. Use the decision callback and your own monitoring to review normal activity in OBSERVE.
+7. To enforce, change the policy mode to `ENFORCE`, define `canActOnSource` to exclude management and other protected addresses, restart the application, and test with a noncritical source. Use `createExpressNodeGuard` or `createNextRouteGuard` to apply the resulting application restriction. If behavior is unexpected, revert to OBSERVE and restart; `guard.release(ip)` removes a specific local restriction in a running process.
+8. Treat each worker as independent. A restart clears in-memory state. There is no shared quota or durable audit store in this alpha.
+
+## Express outline
+
+```js
+import express from 'express';
+import { createPolicyGuardV1 } from '@network-decode/node-guard/policy-runtime';
+import { createExpressNodeGuard } from '@network-decode/node-guard/express';
+import { createTrustedSourceResolver } from '@network-decode/node-guard/trusted-source';
+import policy from './nodeguard.policy.json' with { type: 'json' };
+
+const app = express();
+const source = createTrustedSourceResolver({ trustedProxyIps: ['127.0.0.1'] });
+const guard = createPolicyGuardV1({ policy, canActOnSource: (ip) => !protectedIps.has(ip) });
+app.use(createExpressNodeGuard({ guard, getVerifiedSourceIp: source }));
+// In the login handler, after verifying a failed login, record an observation.
+// See examples/auth-observations.json for its complete v1 shape.
+```
+
+Replace `protectedIps` with your own explicit protected-source set and `trustedProxyIps` with the actual immediate proxies. The sample proxy IP is illustrative. `createExpressNodeGuard` replies `429` for THROTTLE and `403` for DENY and includes `Retry-After`.
+
+## Recovery
+
+Application restrictions are local and temporary. On an unexpected restriction, call `guard.release(verifiedIp)` from an authenticated operator path or switch back to OBSERVE and restart. Never expose release without authentication. HoneyMesh host enforcement, when separately installed, has its own recovery procedure.

package/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/NEXT_ROUTE_GUIDE.md

@@ -0,0 +1,27 @@
+# Next.js Route Handler integration
+
+Use Node Guard only in App Router Route Handlers that execute in the Node.js runtime. The default in-memory state is tied to one persistent process. Edge and serverless instances are outside this alpha's qualified scope.
+
+```js
+export const runtime = 'nodejs';
+
+import { createNextRouteGuard } from '@network-decode/node-guard/next-route';
+
+const check = createNextRouteGuard({
+  guard,
+  getVerifiedSourceIp: async (request) => ingress.getVerifiedSourceIp(request),
+});
+
+export async function POST(request) {
+  const restriction = await check(request);
+  if (restriction) return restriction;
+  // Authenticate, process the request, and record only verified security events.
+  return Response.json({ ok: true });
+}
+```
+
+`ingress.getVerifiedSourceIp` is an application-owned function backed by a trusted deployment boundary. Next Route Handler `Request` does not by itself establish a trusted socket peer. Do not take `X-Forwarded-For` directly from the request without authenticating the ingress path. If the source cannot be verified, the adapter returns `503` with `Cache-Control: no-store`.
+
+With Next.js Cache Components enabled, omit the `runtime` export; that mode uses the Node.js runtime by default. The installed Next.js 16.4.3 documentation marks Edge runtime as deprecated.
+
+For a deployment with multiple workers or changing serverless instances, use OBSERVE only until a qualified shared state adapter exists. Never claim a fleet-wide rate limit from one process's memory.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# Node Guard Free
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node Guard Free is a local application protection SDK for Node.js. It requires no account, license key, HoneyMesh agent, root access, or subscription. It does not attach XDP, enforce host firewall rules, or participate in Exchange.
+
+**Status:** experimental alpha for evaluation. This release is not a promise of production support.
+
+## Supported scope
+
+- Node.js 20 or newer, one persistent Node.js process.
+- Express adapter and Next.js App Router Route Handler adapter in the Node.js runtime.
+- Explicit source verification and application-level observe, throttle, or deny decisions.
+- In-memory state. Restart clears restrictions; workers and replicas do not share state.
+- Only explicitly recorded observations count. The SDK does not infer hostile behavior from every HTTP response.
+
+## Quick start
+
+Install the published alpha with:
+
+```sh
+npm install @network-decode/node-guard@0.2.0-alpha.6
+npx nodeguard init
+npx nodeguard doctor nodeguard.policy.json
+npx nodeguard policy validate nodeguard.policy.json
+```
+
+For source evaluation, clone this repository, run `npm ci`, `npm test`, `npm run typecheck`, and `npm run smoke:package`. `init` writes an OBSERVE policy with permissions `0600` and refuses to overwrite an existing file. Review the application ID, route, source trust, and exclusions before enabling ENFORCE.
+
+A direct application decision can be created with the v1 engine:
+
+```js
+import { createPolicyGuardV1 } from '@network-decode/node-guard/policy-runtime';
+
+const policy = {
+  schema_version: 1, policy_id: 'login-v1', application_id: 'billing-api',
+  mode: 'OBSERVE', route_id: 'auth.login', reason_code: 'authentication_failure',
+  window_seconds: 60, threshold: 5, action: 'THROTTLE', restriction_seconds: 60,
+};
+const guard = createPolicyGuardV1({ policy, canActOnSource: (ip) => !protectedIps.has(ip) });
+// After your application verifies the source and detects a failed login:
+// guard.record({ schema_version: 1, application_id: 'billing-api',
+//   event_id: crypto.randomUUID(), observed_at: new Date().toISOString(),
+//   route_id: 'auth.login', reason_code: 'authentication_failure',
+//   source_ip: verifiedSourceIp, protocol: 'HTTPS' });
+```
+
+See [developer setup](DEVELOPER_SETUP.md) and [Next route guide](NEXT_ROUTE_GUIDE.md) for complete integration rules. `nodeguard policy test` simulates decisions at a specified timestamp.
+
+## Security model
+
+The application owns authentication and supplies verified client identity. Only trust forwarding headers from explicitly named proxy IPs. The enforcement mode requires a `canActOnSource` callback so operators can protect management addresses. Never derive `source_ip` or a subject from an untrusted request body or arbitrary header. The application must call `record` only after it has verified an event, such as an authentication failure.
+
+This package stores no request bodies, tokens, or passwords. The default state is local to one process and bounded by `maxSources` and `maxObservations`. A full state store, management API, and console are later phases. The private HoneyMesh bridge remains a separate paid host integration and is not present in this package.
+
+## Commands
+
+- `nodeguard init [--output file]`
+- `nodeguard doctor [policy.json]`
+- `nodeguard policy validate policy.json`
+- `nodeguard policy test policy.json observations.json --at 2026-11-03T18:00:00Z`
+- `nodeguard inspect policy.json`
+- `nodeguard export policy.json --output sanitized-policy.json`
+
+`export` includes validated policy fields only, no observations or runtime events. It refuses to overwrite files.
+
+## License and reporting
+
+Apache-2.0. See [LICENSE](LICENSE). Report suspected security issues privately using [SECURITY.md](SECURITY.md).

package/SECURITY.md

@@ -0,0 +1,3 @@
+# Security policy
+
+Please report security issues privately to security@network-decode.com. Include the package version, a minimal reproduction, and the expected and observed behavior. Do not post credentials, customer data, or exploit details in a public issue. Node Guard Free is an alpha candidate; supported deployment scope is in README.md.

package/bin/nodeguard.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { simulatePolicyV1, validatePolicyV1 } from "../policy.mjs";
+
+const usage = "Usage: nodeguard init [--output <policy.json>] | nodeguard doctor [policy.json] | nodeguard policy validate <policy.json> | nodeguard policy test <policy.json> <observations.json> --at <UTC timestamp> | nodeguard inspect <policy.json> | nodeguard export <policy.json> --output <file>";
+const examplePolicy = new URL("../examples/auth-policy.json", import.meta.url);
+
+async function readJson(path) {
+  const info = await stat(path);
+  if (!info.isFile() || info.size > 1_048_576) throw new Error("input must be a JSON file no larger than 1 MiB");
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function main(args) {
+  if (args[0] === "init" && (args.length === 1 || (args.length === 3 && args[1] === "--output"))) {
+    const output = args.length === 3 ? args[2] : "nodeguard.policy.json";
+    if (!output || output.startsWith("-")) throw new Error("choose a policy output path");
+    const policyText = await readFile(examplePolicy, "utf8");
+    validatePolicyV1(JSON.parse(policyText));
+    await writeFile(output, policyText, { flag: "wx", mode: 0o600 });
+    process.stdout.write(`Created OBSERVE policy: ${output}\nReview application_id, route_id, trusted source, and exclusions before integration.\n`);
+    return;
+  }
+  if (args[0] === "doctor" && (args.length === 1 || args.length === 2)) {
+    const major = Number(process.versions.node.split(".")[0]);
+    if (major < 20) throw new Error("Node.js 20 or newer is required");
+    const output = { node: process.version, runtime: "supported", source_trust: "not checked",
+      state_scope: "one_process", multi_worker_consistency: "not provided" };
+    if (args.length === 2) {
+      const policy = validatePolicyV1(await readJson(args[1]));
+      output.policy_id = policy.policy_id;
+      output.policy_mode = policy.mode;
+    }
+    process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    return;
+  }
+  if (args[0] === "inspect" && args.length === 2) {
+    const policy = validatePolicyV1(await readJson(args[1]));
+    process.stdout.write(`${JSON.stringify({ schema_version: 1, policy_id: policy.policy_id,
+      application_id: policy.application_id, route_id: policy.route_id, mode: policy.mode,
+      action: policy.action, threshold: policy.threshold, window_seconds: policy.window_seconds,
+      restriction_seconds: policy.restriction_seconds, state_scope: "one_process" }, null, 2)}\n`);
+    return;
+  }
+  if (args[0] === "export" && args.length === 4 && args[2] === "--output") {
+    const policy = validatePolicyV1(await readJson(args[1]));
+    if (!args[3] || args[3].startsWith("-")) throw new Error("choose an export output path");
+    const exported = { schema_version: policy.schema_version, policy_id: policy.policy_id,
+      application_id: policy.application_id, mode: policy.mode, route_id: policy.route_id,
+      reason_code: policy.reason_code, window_seconds: policy.window_seconds,
+      threshold: policy.threshold, action: policy.action,
+      restriction_seconds: policy.restriction_seconds };
+    await writeFile(args[3], `${JSON.stringify(exported, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    process.stdout.write(`Exported policy without runtime events: ${args[3]}\n`);
+    return;
+  }
+  if (args[0] !== "policy") throw new Error(usage);
+  if (args[1] === "validate" && args.length === 3) {
+    const policy = validatePolicyV1(await readJson(args[2]));
+    process.stdout.write(`Valid policy v1: ${policy.policy_id}\n`);
+    return;
+  }
+  if (args[1] === "test" && args.length === 6 && args[4] === "--at") {
+    const policy = await readJson(args[2]);
+    const observations = await readJson(args[3]);
+    const results = simulatePolicyV1(policy, observations, { at: args[5] });
+    process.stdout.write(`${JSON.stringify({ schema_version: 1, results }, null, 2)}\n`);
+    return;
+  }
+  throw new Error(usage);
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  process.stderr.write(`nodeguard: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/examples/auth-observations.json

@@ -0,0 +1,22 @@
+[
+  {
+    "schema_version": 1,
+    "application_id": "billing-api",
+    "event_id": "example-event-0001",
+    "observed_at": "2026-11-03T17:59:25Z",
+    "route_id": "auth.login",
+    "reason_code": "authentication_failure",
+    "source_ip": "8.8.8.8",
+    "protocol": "HTTPS"
+  },
+  {
+    "schema_version": 1,
+    "application_id": "billing-api",
+    "event_id": "example-event-0002",
+    "observed_at": "2026-11-03T17:59:35Z",
+    "route_id": "auth.login",
+    "reason_code": "authentication_failure",
+    "source_ip": "8.8.8.8",
+    "protocol": "HTTPS"
+  }
+]

package/examples/auth-policy.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "policy_id": "auth-login-v1",
+  "application_id": "billing-api",
+  "mode": "OBSERVE",
+  "route_id": "auth.login",
+  "reason_code": "authentication_failure",
+  "window_seconds": 60,
+  "threshold": 2,
+  "action": "THROTTLE",
+  "restriction_seconds": 120
+}

package/express.d.ts

@@ -0,0 +1,14 @@
+export declare function createExpressNodeGuard<Request = unknown>(options: {
+  guard: {
+    restriction(sourceIp: string): {
+      expiresAt: string;
+      retryAfterSeconds: number;
+      action?: "THROTTLE" | "DENY";
+    } | null;
+  };
+  /** Return only an address verified by the application's trusted ingress. */
+  getVerifiedSourceIp: (request: Request) => string;
+}): (request: Request, response: {
+  set(field: string, value: string): unknown;
+  status(code: number): { json(body: unknown): unknown };
+}, next: (error?: unknown) => void) => unknown;

package/express.mjs

@@ -0,0 +1,24 @@
+/** Express adapter for a Guard instance and an application-verified source. */
+export function createExpressNodeGuard({ guard, getVerifiedSourceIp } = {}) {
+  if (!guard || typeof guard.restriction !== "function") {
+    throw new TypeError("guard must provide restriction(sourceIp)");
+  }
+  if (typeof getVerifiedSourceIp !== "function") {
+    throw new TypeError("getVerifiedSourceIp must be a function");
+  }
+
+  return function nodeGuardMiddleware(req, res, next) {
+    try {
+      const sourceIp = getVerifiedSourceIp(req);
+      if (typeof sourceIp !== "string" || sourceIp.length === 0) {
+        throw new TypeError("trusted ingress did not provide a verified source IP");
+      }
+      const restriction = guard.restriction(sourceIp);
+      if (!restriction) return next();
+      res.set("Retry-After", String(restriction.retryAfterSeconds));
+      return res.status(restriction.action === "DENY" ? 403 : 429).json({ error: "node_guard_restricted" });
+    } catch (error) {
+      return next(error);
+    }
+  };
+}

package/guard-core.mjs

@@ -0,0 +1,162 @@
+import { BlockList, isIP } from "node:net";
+
+export const REASON_CODES = Object.freeze([
+  "invalid_signature_burst",
+  "replay_burst",
+  "anonymous_rate_burst",
+  "oversized_body_burst",
+  "api_probe_burst",
+]);
+
+const DEFAULT_THRESHOLDS = Object.freeze({
+  invalid_signature_burst: 12,
+  replay_burst: 12,
+  anonymous_rate_burst: 40,
+  oversized_body_burst: 12,
+  api_probe_burst: 20,
+});
+
+const nonPublic = new BlockList();
+const globalV6 = new BlockList();
+globalV6.addSubnet("2000::", 3, "ipv6");
+for (const [address, prefix] of [
+  ["0.0.0.0", 8], ["10.0.0.0", 8], ["127.0.0.0", 8],
+  ["100.64.0.0", 10], ["169.254.0.0", 16], ["172.16.0.0", 12],
+  ["192.0.0.0", 24], ["192.0.2.0", 24], ["192.168.0.0", 16],
+  ["198.18.0.0", 15], ["198.51.100.0", 24], ["203.0.113.0", 24],
+  ["224.0.0.0", 4], ["240.0.0.0", 4],
+]) nonPublic.addSubnet(address, prefix, "ipv4");
+for (const [address, prefix] of [
+  ["::", 128], ["::1", 128], ["2001:db8::", 32], ["fc00::", 7],
+  ["fe80::", 10], ["ff00::", 8],
+]) nonPublic.addSubnet(address, prefix, "ipv6");
+
+function validPositiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 1) throw new TypeError(`${name} must be a positive integer`);
+  return value;
+}
+
+function eligibleAddress(address) {
+  const family = isIP(address);
+  return family !== 0 && !address.toLowerCase().startsWith("::ffff:") &&
+    (family === 4 || globalV6.check(address, "ipv6")) &&
+    !nonPublic.check(address, family === 4 ? "ipv4" : "ipv6");
+}
+
+export function isEligibleSource(address) {
+  return typeof address === "string" && eligibleAddress(address);
+}
+
+/**
+ * A bounded application-level guard. The caller must provide a verified client IP.
+ * This does not attach XDP or infer an attacker from arbitrary HTTP traffic.
+ */
+export function createGuardCore(options = {}) {
+  const mode = options.mode ?? "observe";
+  if (mode !== "observe" && mode !== "enforce") throw new TypeError("mode must be observe or enforce");
+  if (mode === "enforce" && typeof options.canActOnSource !== "function") {
+    throw new TypeError("enforce mode requires canActOnSource");
+  }
+  const canActOnSource = options.canActOnSource ?? (() => true);
+  const onDecision = options.onDecision ?? (() => {});
+  const now = options.now ?? Date.now;
+  if (typeof canActOnSource !== "function" || typeof onDecision !== "function" || typeof now !== "function") {
+    throw new TypeError("callbacks must be functions");
+  }
+  const windowMs = validPositiveInteger(options.windowMs ?? 60_000, "windowMs");
+  const blockMs = validPositiveInteger(options.blockMs ?? 120_000, "blockMs");
+  const maxSources = validPositiveInteger(options.maxSources ?? 20_000, "maxSources");
+  if (windowMs > 300_000 || blockMs > 300_000 || maxSources > 100_000) {
+    throw new RangeError("guard windows and capacity exceed safety limits");
+  }
+  const thresholds = { ...DEFAULT_THRESHOLDS, ...options.thresholds };
+  if (Object.keys(thresholds).some((key) => !REASON_CODES.includes(key))) {
+    throw new TypeError("unknown reason code in thresholds");
+  }
+  for (const [reason, threshold] of Object.entries(thresholds)) {
+    validPositiveInteger(threshold, reason);
+    if (threshold < 2) throw new RangeError(`${reason} requires at least two observations`);
+  }
+
+  const state = new Map();
+  const keyFor = (reasonCode, sourceIp) => `${reasonCode}|${sourceIp}`;
+  function policyAllows(sourceIp) {
+    try { return canActOnSource(sourceIp) === true; }
+    catch { return false; }
+  }
+
+  function prune(at) {
+    for (const [key, entry] of state) {
+      entry.hits = entry.hits.filter((hit) => at - hit < windowMs);
+      if (entry.hits.length === 0 && entry.blockedUntil <= at && entry.reportedUntil <= at) state.delete(key);
+    }
+  }
+
+  function record({ sourceIp, reasonCode, protocol = "HTTP" } = {}) {
+    if (typeof sourceIp !== "string" || !eligibleAddress(sourceIp)) return { accepted: false, reason: "ineligible_source" };
+    if (!REASON_CODES.includes(reasonCode)) return { accepted: false, reason: "unknown_reason" };
+    if (protocol !== "HTTP" && protocol !== "HTTPS") return { accepted: false, reason: "invalid_protocol" };
+    if (!policyAllows(sourceIp)) return { accepted: false, reason: "source_excluded" };
+    const at = now();
+    const key = keyFor(reasonCode, sourceIp);
+    let entry = state.get(key);
+    if (!entry) {
+      if (state.size >= maxSources) prune(at);
+      if (state.size >= maxSources) return { accepted: false, reason: "capacity_exhausted" };
+      entry = { hits: [], blockedUntil: 0, reportedUntil: 0, protocol };
+      state.set(key, entry);
+    }
+    entry.hits = entry.hits.filter((hit) => at - hit < windowMs);
+    entry.hits.push(at);
+    const threshold = thresholds[reasonCode];
+    if (entry.hits.length > threshold) entry.hits.shift();
+    entry.protocol = protocol;
+    if (entry.hits.length < threshold || entry.reportedUntil > at) return { accepted: true, action: "recorded" };
+
+    entry.reportedUntil = at + windowMs;
+    if (mode === "enforce") entry.blockedUntil = at + blockMs;
+    const decision = Object.freeze({
+      sourceIp, reasonCode, protocol, hitCount: entry.hits.length,
+      observedAt: new Date(at).toISOString(),
+      action: mode === "enforce" ? "limit_armed" : "observed",
+      expiresAt: mode === "enforce" ? new Date(entry.blockedUntil).toISOString() : null,
+    });
+    Promise.resolve().then(() => onDecision(decision)).catch(() => {});
+    return { accepted: true, action: decision.action, decision };
+  }
+
+  function restriction(sourceIp) {
+    if (mode !== "enforce" || typeof sourceIp !== "string" || !eligibleAddress(sourceIp) || !policyAllows(sourceIp)) return null;
+    const at = now();
+    let blockedUntil = 0;
+    for (const reasonCode of REASON_CODES) {
+      blockedUntil = Math.max(blockedUntil, state.get(keyFor(reasonCode, sourceIp))?.blockedUntil ?? 0);
+    }
+    if (blockedUntil <= at) return null;
+    return { expiresAt: new Date(blockedUntil).toISOString(), retryAfterSeconds: Math.ceil((blockedUntil - at) / 1_000) };
+  }
+
+  function isBlocked(sourceIp) {
+    return restriction(sourceIp) !== null;
+  }
+
+  function release(sourceIp) {
+    let removed = 0;
+    for (const reasonCode of REASON_CODES) removed += Number(state.delete(keyFor(reasonCode, sourceIp)));
+    return removed;
+  }
+
+  function snapshot() {
+    const at = now();
+    prune(at);
+    return [...state.entries()].filter(([key, entry]) => entry.blockedUntil > at && policyAllows(key.slice(key.indexOf("|") + 1))).map(([key, entry]) => {
+      const separator = key.indexOf("|");
+      return {
+        reasonCode: key.slice(0, separator), sourceIp: key.slice(separator + 1),
+        protocol: entry.protocol, expiresAt: new Date(entry.blockedUntil).toISOString(),
+      };
+    });
+  }
+
+  return Object.freeze({ record, restriction, isBlocked, release, snapshot });
+}

package/index.d.ts

@@ -0,0 +1,45 @@
+export type ReasonCode =
+  | "invalid_signature_burst"
+  | "replay_burst"
+  | "anonymous_rate_burst"
+  | "oversized_body_burst"
+  | "api_probe_burst";
+
+export type GuardDecision = Readonly<{
+  sourceIp: string;
+  reasonCode: ReasonCode;
+  protocol: "HTTP" | "HTTPS";
+  hitCount: number;
+  observedAt: string;
+  action: "observed" | "limit_armed";
+  expiresAt: string | null;
+}>;
+
+export type RecordResult =
+  | { accepted: false; reason: "ineligible_source" | "unknown_reason" | "invalid_protocol" | "source_excluded" | "capacity_exhausted" }
+  | { accepted: true; action: "recorded" | "observed" | "limit_armed"; decision?: GuardDecision };
+
+export declare const REASON_CODES: readonly ReasonCode[];
+export declare function isEligibleSource(address: string): boolean;
+
+export type GuardOptions = {
+  mode?: "observe" | "enforce";
+  thresholds?: Partial<Record<ReasonCode, number>>;
+  windowMs?: number;
+  blockMs?: number;
+  maxSources?: number;
+  canActOnSource?: (verifiedClientIp: string) => boolean;
+  onDecision?: (decision: GuardDecision) => void | Promise<void>;
+  now?: () => number;
+};
+
+export type GuardInstance = Readonly<{
+  record(event: { sourceIp: string; reasonCode: ReasonCode; protocol?: "HTTP" | "HTTPS" }): RecordResult;
+  restriction(sourceIp: string): { expiresAt: string; retryAfterSeconds: number } | null;
+  isBlocked(sourceIp: string): boolean;
+  release(sourceIp: string): number;
+  snapshot(): Array<{ sourceIp: string; reasonCode: ReasonCode; protocol: "HTTP" | "HTTPS"; expiresAt: string }>;
+}>;
+
+/** License-free, in-process application protection; no host-level enforcement. */
+export declare function createNodeGuard(options?: GuardOptions): GuardInstance;

package/index.mjs

@@ -0,0 +1,8 @@
+import { createGuardCore, isEligibleSource, REASON_CODES } from "./guard-core.mjs";
+
+export { isEligibleSource, REASON_CODES };
+
+/** Standalone application protection. It cannot create host or XDP grants. */
+export function createNodeGuard(options = {}) {
+  return createGuardCore(options);
+}

package/next-route.d.ts

@@ -0,0 +1,11 @@
+export declare function createNextRouteGuard<RequestType = Request>(options: {
+  guard: {
+    restriction(sourceIp: string): {
+      expiresAt: string;
+      retryAfterSeconds: number;
+      action?: "THROTTLE" | "DENY";
+    } | null;
+  };
+  /** Must use a deployment-verified source; never raw client headers. */
+  getVerifiedSourceIp: (request: RequestType) => string | Promise<string>;
+}): (request: RequestType) => Promise<Response | null>;

package/next-route.mjs

@@ -0,0 +1,28 @@
+/** Check one Next.js App Router Route Handler request in the Node.js runtime. */
+export function createNextRouteGuard({ guard, getVerifiedSourceIp } = {}) {
+  if (!guard || typeof guard.restriction !== "function") {
+    throw new TypeError("guard must provide restriction(sourceIp)");
+  }
+  if (typeof getVerifiedSourceIp !== "function") {
+    throw new TypeError("getVerifiedSourceIp must be a function");
+  }
+
+  return async function checkRoute(request) {
+    try {
+      const sourceIp = await getVerifiedSourceIp(request);
+      if (typeof sourceIp !== "string" || sourceIp.length === 0) {
+        throw new TypeError("trusted ingress did not provide a verified source IP");
+      }
+      const restriction = guard.restriction(sourceIp);
+      if (!restriction) return null;
+      return Response.json({ error: "node_guard_restricted" }, {
+        status: restriction.action === "DENY" ? 403 : 429,
+        headers: { "Retry-After": String(restriction.retryAfterSeconds), "Cache-Control": "no-store" },
+      });
+    } catch {
+      return Response.json({ error: "verified_source_unavailable" }, {
+        status: 503, headers: { "Cache-Control": "no-store" },
+      });
+    }
+  };
+}

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@network-decode/node-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0-alpha.6",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Smccann01/node-guard-free.git"
+  },
+  "homepage": "https://github.com/Smccann01/node-guard-free#readme",
+  "bugs": "https://github.com/Smccann01/node-guard-free/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    "DEVELOPER_SETUP.md",
+    "NEXT_ROUTE_GUIDE.md",
+    "index.mjs",
+    "index.d.ts",
+    "guard-core.mjs",
+    "express.mjs",
+    "express.d.ts",
+    "policy.mjs",
+    "policy.d.ts",
+    "policy-runtime.mjs",
+    "policy-runtime.d.ts",
+    "trusted-source.mjs",
+    "trusted-source.d.ts",
+    "next-route.mjs",
+    "next-route.d.ts",
+    "bin/nodeguard.mjs",
+    "examples/auth-policy.json",
+    "examples/auth-observations.json",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.mjs"
+    },
+    "./express": {
+      "types": "./express.d.ts",
+      "default": "./express.mjs"
+    },
+    "./policy": {
+      "types": "./policy.d.ts",
+      "default": "./policy.mjs"
+    },
+    "./policy-runtime": {
+      "types": "./policy-runtime.d.ts",
+      "default": "./policy-runtime.mjs"
+    },
+    "./trusted-source": {
+      "types": "./trusted-source.d.ts",
+      "default": "./trusted-source.mjs"
+    },
+    "./next-route": {
+      "types": "./next-route.d.ts",
+      "default": "./next-route.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "nodeguard": "bin/nodeguard.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 --lib ES2022,DOM scripts/types-smoke.mts",
+    "smoke:package": "node scripts/clean-install-smoke.mjs",
+    "smoke:next": "node scripts/next-clean-app-smoke.mjs"
+  },
+  "devDependencies": {
+    "express": "^5.3.0",
+    "typescript": "5.9.3"
+  }
+}

package/policy-runtime.d.ts

@@ -0,0 +1,31 @@
+import type { ObservationV1, PolicyV1 } from "./policy.js";
+
+export type PolicyRuntimeDecision = Readonly<{
+  schema_version: 1;
+  policy_id: string;
+  application_id: string;
+  route_id: string;
+  source_ip: string;
+  reason_code: string;
+  action: "OBSERVE" | "THROTTLE" | "DENY";
+  hit_count: number;
+  observed_at: string;
+  restriction_expires_at: string | null;
+}>;
+export declare function createPolicyGuardV1(options: {
+  policy: PolicyV1;
+  canActOnSource?: (verifiedSourceIp: string) => boolean;
+  onDecision?: (decision: PolicyRuntimeDecision) => void | Promise<void>;
+  now?: () => number;
+  maxSources?: number;
+  maxObservations?: number;
+}): Readonly<{
+  policy: Readonly<PolicyV1>;
+  record(observation: ObservationV1):
+    | { accepted: false; reason: "policy_mismatch" | "source_excluded" | "outside_window" | "capacity_exhausted" | "duplicate_event" }
+    | { accepted: true; action: "recorded" | "OBSERVE" | "THROTTLE" | "DENY"; decision?: PolicyRuntimeDecision };
+  restriction(sourceIp: string): { action: "THROTTLE" | "DENY"; policyId: string; expiresAt: string; retryAfterSeconds: number } | null;
+  isBlocked(sourceIp: string): boolean;
+  release(sourceIp: string): number;
+  snapshot(): Array<{ sourceIp: string; action: "THROTTLE" | "DENY"; policyId: string; expiresAt: string; retryAfterSeconds: number }>;
+}>;

package/policy-runtime.mjs

@@ -0,0 +1,128 @@
+import { isEligibleSource } from "./guard-core.mjs";
+import { validateObservationV1, validatePolicyV1 } from "./policy.mjs";
+
+function boundedInteger(value, name, maximum) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+    throw new RangeError(`${name} must be 1-${maximum}`);
+  }
+  return value;
+}
+
+/** One policy, one application, one exact route. State is local to this process. */
+export function createPolicyGuardV1({ policy: policyInput, canActOnSource, onDecision = () => {},
+  now = Date.now, maxSources = 20_000, maxObservations = 50_000 } = {}) {
+  const policy = validatePolicyV1(policyInput);
+  if (policy.mode === "ENFORCE" && typeof canActOnSource !== "function") {
+    throw new TypeError("ENFORCE requires canActOnSource");
+  }
+  if (canActOnSource !== undefined && typeof canActOnSource !== "function") throw new TypeError("canActOnSource must be a function");
+  if (typeof onDecision !== "function" || typeof now !== "function") throw new TypeError("callbacks must be functions");
+  boundedInteger(maxSources, "maxSources", 100_000);
+  boundedInteger(maxObservations, "maxObservations", 100_000);
+  if (maxObservations < policy.threshold) throw new RangeError("maxObservations must meet the policy threshold");
+  const windowMs = policy.window_seconds * 1_000;
+  const restrictionMs = policy.restriction_seconds * 1_000;
+  const state = new Map();
+  const seenIds = new Map();
+
+  function allows(sourceIp) {
+    try { return (canActOnSource ?? (() => true))(sourceIp) === true; }
+    catch { return false; }
+  }
+
+  function pruneEntry(entry, at) {
+    for (const [id, observedAt] of entry.hits) {
+      if (observedAt <= at - windowMs) {
+        entry.hits.delete(id);
+      }
+    }
+  }
+
+  function pruneSeen(at) {
+    for (const [id, observedAt] of seenIds) {
+      if (observedAt <= at - windowMs) seenIds.delete(id);
+    }
+  }
+
+  function prune(at) {
+    pruneSeen(at);
+    for (const [sourceIp, entry] of state) {
+      pruneEntry(entry, at);
+      if (entry.hits.size === 0 && entry.restrictionUntil <= at && entry.reportedUntil <= at) state.delete(sourceIp);
+    }
+  }
+
+  function record(input) {
+    const observation = validateObservationV1(input);
+    if (observation.application_id !== policy.application_id || observation.route_id !== policy.route_id ||
+        observation.reason_code !== policy.reason_code) return { accepted: false, reason: "policy_mismatch" };
+    if (!allows(observation.source_ip)) return { accepted: false, reason: "source_excluded" };
+    const at = now();
+    if (!Number.isSafeInteger(at)) throw new TypeError("now must return epoch milliseconds");
+    const observedAt = Date.parse(observation.observed_at);
+    if (observedAt <= at - windowMs || observedAt > at + 5_000) return { accepted: false, reason: "outside_window" };
+    const prior = seenIds.get(observation.event_id);
+    if (prior !== undefined && prior > at - windowMs) return { accepted: false, reason: "duplicate_event" };
+    if (prior !== undefined) seenIds.delete(observation.event_id);
+    if (seenIds.size >= maxObservations) pruneSeen(at);
+    if (seenIds.size >= maxObservations) return { accepted: false, reason: "capacity_exhausted" };
+
+    let entry = state.get(observation.source_ip);
+    if (entry) pruneEntry(entry, at);
+    if (!entry) {
+      if (state.size >= maxSources) prune(at);
+      if (state.size >= maxSources) return { accepted: false, reason: "capacity_exhausted" };
+      entry = { hits: new Map(), restrictionUntil: 0, reportedUntil: 0 };
+      state.set(observation.source_ip, entry);
+    }
+    if (entry.hits.size >= policy.threshold) {
+      entry.hits.delete(entry.hits.keys().next().value);
+    }
+    entry.hits.set(observation.event_id, observedAt);
+    seenIds.set(observation.event_id, observedAt);
+    if (entry.hits.size < policy.threshold || entry.reportedUntil > at) return { accepted: true, action: "recorded" };
+
+    entry.reportedUntil = at + windowMs;
+    if (policy.mode === "ENFORCE") entry.restrictionUntil = at + restrictionMs;
+    const decision = Object.freeze({
+      schema_version: 1, policy_id: policy.policy_id, application_id: policy.application_id,
+      route_id: policy.route_id, source_ip: observation.source_ip, reason_code: policy.reason_code,
+      action: policy.mode === "OBSERVE" ? "OBSERVE" : policy.action,
+      hit_count: entry.hits.size, observed_at: new Date(at).toISOString(),
+      restriction_expires_at: policy.mode === "ENFORCE" ? new Date(entry.restrictionUntil).toISOString() : null,
+    });
+    Promise.resolve().then(() => onDecision(decision)).catch(() => {});
+    return { accepted: true, action: decision.action, decision };
+  }
+
+  function restriction(sourceIp) {
+    if (policy.mode !== "ENFORCE" || !isEligibleSource(sourceIp) || !allows(sourceIp)) return null;
+    const at = now();
+    const entry = state.get(sourceIp);
+    if (!entry || entry.restrictionUntil <= at) return null;
+    return {
+      action: policy.action, policyId: policy.policy_id,
+      expiresAt: new Date(entry.restrictionUntil).toISOString(),
+      retryAfterSeconds: Math.ceil((entry.restrictionUntil - at) / 1_000),
+    };
+  }
+
+  function release(sourceIp) {
+    const entry = state.get(sourceIp);
+    if (!entry) return 0;
+    state.delete(sourceIp);
+    return 1;
+  }
+
+  function snapshot() {
+    const at = now();
+    prune(at);
+    if (policy.mode !== "ENFORCE") return [];
+    return [...state.keys()].filter((sourceIp) => allows(sourceIp)).map((sourceIp) => {
+      const active = restriction(sourceIp);
+      return active ? { sourceIp, ...active } : null;
+    }).filter(Boolean);
+  }
+
+  return Object.freeze({ policy, record, restriction, isBlocked: (sourceIp) => restriction(sourceIp) !== null, release, snapshot });
+}

package/policy.d.ts

@@ -0,0 +1,33 @@
+export type PolicyReasonCode = import("./index.js").ReasonCode | "authentication_failure";
+export type PolicyV1 = {
+  schema_version: 1;
+  policy_id: string;
+  application_id: string;
+  mode: "OBSERVE" | "ENFORCE";
+  route_id: string;
+  reason_code: PolicyReasonCode;
+  window_seconds: number;
+  threshold: number;
+  action: "THROTTLE" | "DENY";
+  restriction_seconds: number;
+};
+export type ObservationV1 = {
+  schema_version: 1;
+  application_id: string;
+  event_id: string;
+  observed_at: string;
+  route_id: string;
+  reason_code: PolicyReasonCode;
+  source_ip: string;
+  protocol: "HTTP" | "HTTPS";
+};
+export declare const POLICY_REASON_CODES: readonly PolicyReasonCode[];
+export declare function validatePolicyV1(policy: unknown): Readonly<PolicyV1>;
+export declare function validateObservationV1(observation: unknown): Readonly<ObservationV1>;
+export declare function simulatePolicyV1(policy: unknown, observations: unknown[], options: { at: string }): Array<{
+  policy_id: string;
+  source_ip: string;
+  hit_count: number;
+  decision: "NONE" | "OBSERVE" | "THROTTLE" | "DENY";
+  restriction_expires_at: string | null;
+}>;

package/policy.mjs

@@ -0,0 +1,92 @@
+import { isEligibleSource, REASON_CODES } from "./guard-core.mjs";
+
+export const POLICY_REASON_CODES = Object.freeze([...REASON_CODES, "authentication_failure"]);
+const POLICY_FIELDS = new Set(["schema_version", "policy_id", "application_id", "mode", "route_id", "reason_code", "window_seconds", "threshold", "action", "restriction_seconds"]);
+const OBSERVATION_FIELDS = new Set(["schema_version", "application_id", "event_id", "observed_at", "route_id", "reason_code", "source_ip", "protocol"]);
+const IDENTIFIER = /^[a-z][a-z0-9._-]{1,63}$/;
+const EVENT_ID = /^[A-Za-z0-9_-]{8,128}$/;
+const UTC_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+
+function object(value, name, fields) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  for (const key of Object.keys(value)) {
+    if (!fields.has(key)) throw new TypeError(`${name} has unknown field ${key}`);
+  }
+}
+
+function identifier(value, name) {
+  if (typeof value !== "string" || !IDENTIFIER.test(value)) throw new TypeError(`${name} must be a 2-64 character identifier`);
+}
+
+function integer(value, name, min, max) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new RangeError(`${name} must be ${min}-${max}`);
+}
+
+function timestamp(value, name) {
+  if (typeof value !== "string" || !UTC_TIME.test(value) || !Number.isFinite(Date.parse(value))) {
+    throw new TypeError(`${name} must be an ISO 8601 UTC timestamp`);
+  }
+  const milliseconds = Date.parse(value);
+  const canonical = value.replace(/(?:\.(\d{1,3}))?Z$/, (_match, fraction) => `.${(fraction ?? "").padEnd(3, "0")}Z`);
+  if (new Date(milliseconds).toISOString() !== canonical) throw new TypeError(`${name} must be a valid UTC timestamp`);
+  return milliseconds;
+}
+
+export function validatePolicyV1(policy) {
+  object(policy, "policy", POLICY_FIELDS);
+  if (policy.schema_version !== 1) throw new TypeError("unsupported policy schema_version");
+  identifier(policy.policy_id, "policy_id");
+  identifier(policy.application_id, "application_id");
+  identifier(policy.route_id, "route_id");
+  if (!POLICY_REASON_CODES.includes(policy.reason_code)) throw new TypeError("unknown policy reason_code");
+  if (policy.mode !== "OBSERVE" && policy.mode !== "ENFORCE") throw new TypeError("mode must be OBSERVE or ENFORCE");
+  if (policy.action !== "THROTTLE" && policy.action !== "DENY") throw new TypeError("action must be THROTTLE or DENY");
+  integer(policy.window_seconds, "window_seconds", 1, 300);
+  integer(policy.threshold, "threshold", 2, 10_000);
+  integer(policy.restriction_seconds, "restriction_seconds", 1, 300);
+  return Object.freeze({ ...policy });
+}
+
+export function validateObservationV1(observation) {
+  object(observation, "observation", OBSERVATION_FIELDS);
+  if (observation.schema_version !== 1) throw new TypeError("unsupported observation schema_version");
+  identifier(observation.application_id, "application_id");
+  identifier(observation.route_id, "route_id");
+  if (typeof observation.event_id !== "string" || !EVENT_ID.test(observation.event_id)) throw new TypeError("invalid event_id");
+  timestamp(observation.observed_at, "observed_at");
+  if (!POLICY_REASON_CODES.includes(observation.reason_code)) throw new TypeError("unknown observation reason_code");
+  if (!isEligibleSource(observation.source_ip)) throw new TypeError("source_ip must be an eligible public IP");
+  if (observation.protocol !== "HTTP" && observation.protocol !== "HTTPS") throw new TypeError("protocol must be HTTP or HTTPS");
+  return Object.freeze({ ...observation });
+}
+
+/** Pure, source-scoped simulation. It does not install a live restriction. */
+export function simulatePolicyV1(policyInput, observationInputs, { at } = {}) {
+  const policy = validatePolicyV1(policyInput);
+  if (!Array.isArray(observationInputs) || observationInputs.length > 10_000) {
+    throw new RangeError("observations must be an array of at most 10000 events");
+  }
+  const atMs = timestamp(at, "at");
+  const seen = new Set();
+  const counts = new Map();
+  for (const input of observationInputs) {
+    const observation = validateObservationV1(input);
+    const observedMs = Date.parse(observation.observed_at);
+    if (observedMs > atMs) throw new RangeError("observation occurs after simulation time");
+    if (observation.application_id !== policy.application_id ||
+        observation.route_id !== policy.route_id || observation.reason_code !== policy.reason_code ||
+        observedMs <= atMs - policy.window_seconds * 1_000) continue;
+    if (seen.has(observation.event_id)) continue;
+    seen.add(observation.event_id);
+    counts.set(observation.source_ip, (counts.get(observation.source_ip) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([sourceIp, hitCount]) => {
+    const triggered = hitCount >= policy.threshold;
+    return {
+      policy_id: policy.policy_id, source_ip: sourceIp, hit_count: hitCount,
+      decision: !triggered ? "NONE" : policy.mode === "OBSERVE" ? "OBSERVE" : policy.action,
+      restriction_expires_at: triggered && policy.mode === "ENFORCE"
+        ? new Date(atMs + policy.restriction_seconds * 1_000).toISOString() : null,
+    };
+  });
+}

package/trusted-source.d.ts

@@ -0,0 +1,7 @@
+export declare function createTrustedSourceResolver(options?: {
+  /** Exact proxy addresses. CIDR ranges are intentionally unsupported in v1. */
+  trustedProxyIps?: string[];
+}): (request: {
+  socket?: { remoteAddress?: string };
+  headers?: { "x-forwarded-for"?: string | string[] };
+}) => string;

package/trusted-source.mjs

@@ -0,0 +1,40 @@
+import { isIP } from "node:net";
+
+const MAX_TRUSTED_PROXIES = 32;
+const MAX_FORWARDED_HOPS = 16;
+const MAX_FORWARDED_LENGTH = 1024;
+
+function normalizeIp(value, name) {
+  if (typeof value !== "string" || value.length === 0 || value !== value.trim()) {
+    throw new TypeError(`${name} must be an IP address`);
+  }
+  const mapped = value.toLowerCase().startsWith("::ffff:") && isIP(value.slice(7)) === 4 ? value.slice(7) : value;
+  const family = isIP(mapped);
+  if (family === 0) throw new TypeError(`${name} must be an IP address`);
+  return family === 6 ? new URL(`http://[${mapped}]/`).hostname.slice(1, -1) : mapped;
+}
+
+/** Resolve an address using only explicitly named immediate and upstream proxies. */
+export function createTrustedSourceResolver({ trustedProxyIps = [] } = {}) {
+  if (!Array.isArray(trustedProxyIps) || trustedProxyIps.length > MAX_TRUSTED_PROXIES) {
+    throw new TypeError(`trustedProxyIps must contain at most ${MAX_TRUSTED_PROXIES} addresses`);
+  }
+  const trusted = new Set(trustedProxyIps.map((ip) => normalizeIp(ip, "trusted proxy")));
+
+  return function getVerifiedSourceIp(request) {
+    const remote = normalizeIp(request?.socket?.remoteAddress, "socket remoteAddress");
+    if (!trusted.has(remote)) return remote;
+
+    const forwarded = request?.headers?.["x-forwarded-for"];
+    if (typeof forwarded !== "string" || forwarded.length === 0 || forwarded.length > MAX_FORWARDED_LENGTH) {
+      throw new TypeError("trusted proxy must provide one bounded X-Forwarded-For header");
+    }
+    const hops = forwarded.split(",");
+    if (hops.length > MAX_FORWARDED_HOPS) throw new RangeError("too many forwarded hops");
+    const chain = hops.map((hop) => normalizeIp(hop.trim(), "forwarded hop"));
+    for (let index = chain.length - 1; index >= 0; index--) {
+      if (!trusted.has(chain[index])) return chain[index];
+    }
+    throw new TypeError("forwarded chain has no untrusted source");
+  };
+}