net-snmp 3.26.2 → 3.27.0

package/.claude/skills/propose-action/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: propose-action
+description: Review a GitHub issue or PR by number and propose a concrete action plan — either a reasoned recommendation not to action it, or the code and test changes required to action it. Use when the user asks to "propose an action" for an issue/PR, "look at issue/PR #N", or invokes /propose-action with an issue or PR number. Ends by asking whether to proceed, proceed with modifications, or abandon.
+---
+
+# Propose Action
+
+## When to use
+
+- The user asks to review a GitHub issue or PR and recommend what to do about it.
+- The user invokes `/propose-action <number>`.
+
+This skill **plans only** for steps 1–5 — it does not edit code, run tests, commit, push, or comment on the issue/PR during the proposal phase. Implementation happens after the user approves the plan in step 5's closing question. Once the user has approved and you have carried out the agreed actions, step 6 produces a ready-to-paste reply to the issue/PR aligned with what was actually done — but never posts it.
+
+## Arguments
+
+- `<number>` (required) — the GitHub issue or PR number. Bare integer, or `#N`, or a full GitHub URL are all acceptable forms.
+
+If the number is missing, ambiguous, or does not resolve to an issue/PR in the current repository, stop and ask the user to clarify.
+
+## Workflow
+
+### 1. Identify the target
+
+- Determine the current repository: `gh repo view --json nameWithOwner -q .nameWithOwner`.
+- Resolve the number to either an issue or a PR. GitHub numbers them in the same namespace, so try PR first, then issue:
+  - `gh pr view <number> --json number,title,state,author,body,headRefName,baseRefName,isDraft,mergeable,additions,deletions,changedFiles,labels,comments,reviews`
+  - If that fails, `gh issue view <number> --json number,title,state,author,body,labels,comments,assignees`
+- Record whether the target is an **issue** or a **PR** — the two branches below differ.
+
+### 2a. If the target is an issue
+
+Gather context in parallel:
+- The issue body and all comments (from the `gh issue view` JSON above).
+- `gh issue view <number> --json linkedPullRequests` — check for linked PRs that may already address it.
+- Identify the files or subsystems the issue points at. Search the repo (`Grep`, `Glob`, `Read`) for the relevant code. Do not guess — read the actual files the issue describes.
+- If the issue references specific OIDs, error messages, function names, or SNMP behaviours, locate them in the source.
+
+### 2b. If the target is a PR
+
+Gather context in parallel:
+- PR body, comments, and reviews (from the `gh pr view` JSON above).
+- `gh pr diff <number>` — the full diff.
+- `gh pr view <number> --json files -q '.files[].path'` — changed files.
+- Read the **current** version of each changed file on the base branch so you understand what the PR is replacing, not just what it adds.
+- If the PR closes or references an issue (via `Fixes #N`, `Closes #N`, etc.), also fetch that issue for context.
+- Check CI status if available: `gh pr checks <number>`.
+
+### 3. Form a judgement
+
+Decide which of these recommendations fits, and be willing to recommend **against** actioning:
+
+- **Do not action** — the issue is invalid, already fixed, out of scope, based on a misunderstanding, a duplicate, or the PR is the wrong approach / would regress behaviour / conflicts with project direction. Explain *why* clearly, citing the code or prior commits that support the conclusion.
+- **Action as-is** — the issue is valid and the fix is clear, or the PR is correct and should be merged as submitted.
+- **Action with modifications** — the issue is valid but the obvious fix is wrong; or the PR has the right idea but needs specific changes before it can be merged.
+- **Needs more information** — the report is plausible but underspecified. List the exact questions to ask the reporter / author before any code change is possible.
+
+Base the judgement on what the code actually does today, not on what the issue/PR claims. If the two disagree, surface the disagreement.
+
+### 4. Draft the proposal
+
+Structure the written proposal in this order. Keep it concrete — name files, line numbers, function names, and the specific behaviours being changed.
+
+1. **Target** — `Issue #N: <title>` or `PR #N: <title>`, plus one sentence on its state (open/closed/draft/merged, CI status for PRs).
+2. **Summary of the report** — one short paragraph in your own words describing what the reporter is asking for or proposing. Do not just quote the body.
+3. **Findings** — what the code currently does, whether the report is accurate, and any related context (linked issues/PRs, prior commits, existing tests covering this area). Cite `file:line` locations.
+4. **Recommendation** — one of the four options from step 3, stated plainly in a sentence or two.
+5. **Proposed changes** (omit if the recommendation is *do not action* or *needs more information*):
+   - **Code** — for each file to change, list the edit as a bullet: `path/to/file.js:<line-range> — <what changes and why>`. For non-trivial edits, include a short before/after sketch (a few lines, not a full diff).
+   - **Tests** — list tests to **add**, **modify**, or **delete**, each with the file and a one-line description of what the test asserts. If no test changes are needed, say so explicitly and justify (e.g. "covered by existing test at `test/x.test.js:42`").
+   - **Docs / README** — note any README or inline-doc updates required. Release-note bullets are handled by `/prepare-release`; do not pre-empt them here.
+6. **Risks and unknowns** — anything that could make the plan wrong: behaviours you could not verify, edge cases the tests would not catch, compatibility concerns, or assumptions about the reporter's environment.
+7. **Out of scope** — closely-related issues you noticed while investigating but are **not** proposing to fix in this action. Keeps the scope honest.
+
+### 5. Closing question
+
+End the response with exactly one question, offering three choices:
+
+> Proceed with this plan as-is, proceed with modifications (tell me what to change), or abandon it?
+
+Do not start implementing until the user answers. If the user says "proceed", begin implementing the plan in the next turn. If the user asks for modifications, revise the proposal and ask the same question again. If the user says to abandon, stop and skip step 6.
+
+### 6. Ready-to-paste issue/PR reply
+
+After the agreed actions have been carried out (code edits, tests, docs, or a reasoned decision not to action), produce a single ready-to-paste reply for the issue/PR. This is the **last** thing you output, rendered in a fenced block or delimited by `---` so the user can copy it cleanly.
+
+The reply must be aligned with **what actually happened**, not with the original plan — if the user asked for modifications during implementation, reflect the modified outcome. If a step was skipped or failed, say so honestly; do not describe work that was not done.
+
+Tailor the content to the recommendation from step 3:
+
+- **Action as-is / with modifications** — acknowledge the report, give the user a short, concrete summary of the fix (with the key code change or snippet inline if it helps them adopt it), point at the files/sections that changed (e.g. "updated in `README.md` under *Scalar providers*"), and note when it will ship (e.g. "will land in the next release" — do not invent a version number unless `package.json` has already been bumped). If there's a workaround the reporter can apply before the release, include it.
+- **Do not action** — explain the reasoning in the reporter's terms, citing the code or prior history that supports the decision. Be respectful: the reporter put effort into the report. Offer an alternative path if one exists (a different API, a related issue, a config change). If the issue should be closed, say so; do not close it yourself.
+- **Needs more information** — list the specific questions you need answered, each as its own bullet. Explain briefly *why* each is needed so the reporter can see what would unblock progress.
+
+Style:
+
+- Match the tone of prior replies in this repository if they are visible in the issue/PR thread — don't suddenly adopt a different register.
+- Write as the maintainer would: first person, conversational, no corporate voice, no marketing copy, no emoji unless the repo's existing replies use them.
+- Do not include a signature, do not add attribution trailers (no "generated by", no `Co-Authored-By`), do not tag the reporter more than once.
+- Keep it focused — one screen of text is almost always enough. If the reply needs code blocks, prefer short, complete snippets over long diffs.
+
+Hand the reply to the user with one sentence above it saying where to paste it (e.g. "Ready-to-paste reply for issue #297:"). Do **not** run `gh issue comment` / `gh pr comment` / `gh issue close` / `gh pr merge` — the user posts it.
+
+## Rules
+
+- **Never** edit files, run tests, or modify git state during steps 1–5. Planning only.
+- **Never** post a comment on the issue/PR, add labels, request reviews, merge, or close — not in step 6, not ever within this skill. Those are the user's decision.
+- **Never** fabricate line numbers or function names — if you cite `file:line`, you must have read it.
+- If `gh` is not authenticated or the number does not exist, stop and report the error verbatim.
+- If the issue/PR is in a different repository than the current working directory, stop and confirm with the user before proceeding — the plan would target the wrong codebase.
+- Keep the proposal focused. A plan that touches ten files for a one-line bug is a signal to re-read the issue, not to write a bigger plan.

package/.claude/skills/publish-release/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: publish-release
+description: Publish the currently-committed release by pushing master to origin, publishing to npm, tagging the commit with the package.json version, and pushing the tag. Use when the user asks to "publish the release", "push and publish", or invokes /publish-release. Stops immediately on any failure.
+---
+
+# Publish Release
+
+## When to use
+
+- After `/prepare-release` and the release commit have both been completed — this skill assumes the release commit (version bump + README entry + fix) is already `HEAD` on `master`.
+- User asks to publish / ship / release to npm.
+- User invokes `/publish-release`.
+
+Run after `/prepare-release` + `/git-commit`, never in place of them. This skill does not run lint, tests, or modify any files.
+
+## Workflow
+
+Run steps in order. **If any step fails, stop immediately, report the failure, and do not proceed.** There is no rollback — each step is externally observable (a push, a publish, a tag on origin), so a mid-flight failure leaves the release in a partial state the user will need to reason about. Be explicit about which steps succeeded and which did not.
+
+### 1. Pre-flight checks (parallel)
+
+- `git rev-parse --abbrev-ref HEAD` — confirm the current branch is `master`. If not, stop and ask the user.
+- `git status --short` — confirm the working tree is clean. If not, stop — the release commit must already exist as `HEAD`, with nothing else pending.
+- Read the current version from `package.json` (this becomes the tag name).
+- `git tag --list <version>` — confirm the tag does not already exist locally. If it does, stop.
+- `git ls-remote --tags origin refs/tags/<version>` — confirm the tag does not already exist on the remote. If it does, stop.
+- `git log -1 --format=%s` — capture the subject of the HEAD commit for the summary.
+
+### 2. Push master to origin
+
+Run `git push origin master`. **Stop on non-zero exit.** Report the output.
+
+### 3. Publish to npm
+
+Run `npm publish`. **Stop on non-zero exit.**
+
+Notes:
+- If the registry prompts for a one-time password (2FA OTP), relay the prompt to the user and wait for their input. Do not attempt to bypass 2FA.
+- If the registry rejects with `403` or `You do not have permission`, stop and surface the full error — the user may need to `npm login` or check their credentials.
+- If the registry rejects with `You cannot publish over the previously published versions`, stop — the version was not bumped correctly upstream of this skill.
+
+### 4. Tag the release
+
+Tags in this repo are bare version numbers (no `v` prefix) — verified against the existing tag list.
+
+Run `git tag <version>` where `<version>` is the exact value read from `package.json` in step 1 (e.g., `3.26.2`, not `v3.26.2`).
+
+**Stop on non-zero exit.**
+
+### 5. Push the tag
+
+Run `git push origin <version>`. **Stop on non-zero exit.**
+
+### 6. Summary
+
+Report to the user, concisely:
+- The version that was published.
+- Confirmation of: master pushed, npm publish succeeded, tag created, tag pushed.
+- The release commit subject (from pre-flight).
+- The npm package URL, if it can be derived from `package.json` name (`https://www.npmjs.com/package/<name>`).
+
+## Things to watch for
+
+- If step 2 (push master) succeeds but step 3 (npm publish) fails, the commit is on GitHub but not on npm. Do not tag — the user must either resolve the npm issue and re-run publish, or roll back the push.
+- If step 3 (npm publish) succeeds but step 4 (tag) or step 5 (tag push) fails, the package is on npm but not tagged. Surface this clearly — the user needs to manually create / push the tag, and an un-tagged published release is a fix-it-now situation, not something to leave for later.
+- Never use `--force`, `--no-verify`, or any flag that bypasses checks, even to recover from a mid-flight failure. Always ask the user.
+- Never create or push tags for versions other than the one in `package.json`.
+- Never run this skill on a branch other than `master` without explicit user confirmation.

package/README.md

@@ -351,6 +351,7 @@ Actions
 - `11 -  EUnexpectedReport`
 - `12 -  EResponseNotHandled`
 - `13 -  EUnexpectedResponse`
+- `14 -  ENotInTimeWindow`
 
 ## snmp.OidFormat
 - `oid - oid`
@@ -1950,7 +1951,12 @@ var myScalarProvider = {
     scalarType: snmp.ObjectType.OctetString,
     maxAccess: snmp.MaxAccess["read-write"],
     handler: function (mibRequest) {
-       // e.g. can update the MIB data before responding to the request here
+       // For a dynamically-calculated read-only scalar, publish the current value
+       // by assigning to the instance node before calling done().  For read-write scalars,
+       // the agent has already cast and validated mibRequest.setValue by the
+       // time the handler runs, and will commit it on your behalf — the handler
+       // usually just needs to call done().
+       mibRequest.instanceNode.value = yourFunctionToComputeCurrentValue ();
        mibRequest.done ();
     }
     // Note: handler is optional for scalar providers - if omitted, 
@@ -2174,6 +2180,29 @@ objects`, below, for details.
  with the instance OID being operated on, and an `operation` field with the request type from
  `snmp.PduType`.  If the `MibRequest` is for a `SetRequest` PDU, then variables `setValue` and
  `setType` contain the value and type received in the `SetRequest` varbind.
+
+ How the handler should interact with the MIB value depends on the request type:
+
+ * For `GetRequest`, `GetNextRequest` and `GetBulkRequest`, the response varbind is taken
+   from `mibRequest.instanceNode.value` at the moment `done()` is called.  A handler that
+   serves a dynamically-computed read-only scalar (e.g. `sysUpTime`) should therefore
+   assign the current value to `mibRequest.instanceNode.value` before calling `done()`.
+   Equivalent and validated alternative: call `mib.setScalarValue(providerName, value)`
+   from the handler, which casts and constraint-checks the value before storing it.
+   For table columns the pattern is the same — assign to `mibRequest.instanceNode.value`.
+ * For `SetRequest`, the agent has already cast and validated the incoming value into
+   `mibRequest.setValue` before the handler runs, and will commit it to
+   `mibRequest.instanceNode.value` on your behalf during the commit pass.  A handler
+   typically only needs to call `done()` (or `done({errorStatus: ...})` to reject the set).
+   You generally don't need to assign to `instanceNode.value` yourself on the set path.
+
+ If you do need to validate an externally-supplied value inside a handler, three helpers
+ are exposed on the public API: `ObjectTypeUtil.castSetValue(type, value, constraints)`
+ casts and range/constraint-checks a value (throwing on bad input);
+ `MibNode#validateValue(type, value)` returns a boolean against the node's provider
+ constraints; and `MibNode#getConstraintsFromProvider()` returns the constraints object
+ for the current instance node.
+
  * `constraints` *(optional for scalar types)* - an optional object to specify constraints for
  integer-based enumerated types, integer range restrictions and string size restrictions.  Note that
  table columns can specify such `constraints` in an identical way, except that these are stored under
@@ -3723,6 +3752,16 @@ Example programs are included under the module's `example` directory.
 
  * Fix TypeError in oidInSubtree when varbind OID is null
 
+# Version 3.26.3 - 21/04/2026
+
+ * Document how MIB scalar and table handlers should interact with `mibRequest.instanceNode.value` for Get vs Set operations
+
+# Version 3.27.0 - 11/09/2026
+
+ * Fix SNMPv3 requests being rejected with `usmStatsNotInTimeWindows` once a session has been open for a while - the authoritative engine time is now advanced with a monotonic local clock and resynchronised from every authenticated response, instead of staying frozen at the value learned during discovery
+
+ * Discard SNMPv3 responses that fall outside the USM time window, reported as the new `ResponseInvalidCode.ENotInTimeWindow`
+
 # License
 
 Copyright (c) 2020 Mark Abrahams <mark@abrahams.co.nz>

package/index.js

@@ -9,10 +9,13 @@ const util = require ("util");
 const crypto = require ("crypto");
 const mibparser = require ("./lib/mib");
 const Buffer = require('buffer').Buffer;
+const { performance } = require ("perf_hooks");
 
 var DEBUG = false;
 var STRICT_INT_RANGE_CHECKS = false;
 
+const USM_TIME_WINDOW_SECONDS = 150;
+
 const MIN_SIGNED_INT32 = -2147483648;
 const MAX_SIGNED_INT32 = 2147483647;
 const MIN_UNSIGNED_INT32 = 0;
@@ -280,7 +283,8 @@ var ResponseInvalidCode = {
 	10: "ECommunityNoMatch",
 	11: "EUnexpectedReport",
 	12: "EResponseNotHandled",
-	13: "EUnexpectedResponse"
+	13: "EUnexpectedResponse",
+	14: "ENotInTimeWindow"
 };
 
 _expandConstantObject (ResponseInvalidCode);
@@ -2084,6 +2088,18 @@ var Session = function (target, authenticator, options) {
 	this.reqs = {};
 	this.reqCount = 0;
 
+	// Local notion of the authoritative (remote) engine's snmpEngineBoots and
+	// snmpEngineTime, per RFC 3414 section 2.3.  engineTimeBase is the
+	// snmpEngineTime learned at engineTimeReceivedAt (a monotonic millisecond
+	// reading), and the current notion is derived from the two by
+	// getEngineTime().  latestReceivedEngineTime is the highest snmpEngineTime
+	// ever received from the authoritative engine, and exists solely to stop a
+	// replayed message from holding our notion of time back.
+	this.engineTimeBoots = null;
+	this.engineTimeBase = null;
+	this.engineTimeReceivedAt = null;
+	this.latestReceivedEngineTime = null;
+
 	const dgramMod = options.dgramModule || dgram;
 	this.dgram = dgramMod.createSocket (this.transport);
 	this.dgram.unref();
@@ -2425,6 +2441,21 @@ Session.prototype.onMsg = function (buffer) {
 	if ( ! message.processIncomingSecurity (this.user, req.responseCb) )
 		return;
 
+	// RFC 3414 sections 2.3 and 3.2 step 7b: synchronise our notion of the
+	// authoritative engine's time from this message, then discard the message if
+	// it falls outside the time window.  Both are no-ops for SNMPv1 and v2c, and
+	// for v3 messages which were not authenticated.
+	this.setEngineTime (message);
+	if ( ! this.isInTimeWindow (message) ) {
+		req.responseCb (new ResponseInvalidError ("Message with engineBoots '"
+				+ message.msgSecurityParameters.msgAuthoritativeEngineBoots
+				+ "' and engineTime '" + message.msgSecurityParameters.msgAuthoritativeEngineTime
+				+ "' is outside the time window of engineBoots '" + this.engineTimeBoots
+				+ "' and engineTime '" + this.getEngineTime ().engineTime + "'",
+				ResponseInvalidCode.ENotInTimeWindow));
+		return;
+	}
+
 	if (message.version != req.message.version) {
 		req.responseCb (new ResponseInvalidError ("Version in request '"
 				+ req.message.version + "' does not match version in "
@@ -2974,7 +3005,93 @@ Session.prototype.walk  = function () {
 	return this;
 };
 
+// RFC 3414 section 2.3: between authentic messages, the non-authoritative
+// engine's notion of the authoritative engine's snmpEngineTime advances with
+// the local clock.  A monotonic clock source is used, so that a step of the
+// system clock cannot move our notion of time.  Returns null while no notion
+// has been established.
+Session.prototype.getEngineTime = function () {
+	if ( this.engineTimeReceivedAt == null )
+		return null;
+	var elapsedSeconds = Math.floor ((performance.now () - this.engineTimeReceivedAt) / 1000);
+	var engineBoots = this.engineTimeBoots;
+	var engineTime = this.engineTimeBase + elapsedSeconds;
+	// RFC 3414 section 2.2.2: when snmpEngineTime reaches its maximum value,
+	// snmpEngineBoots is incremented and snmpEngineTime is reset to zero.
+	// snmpEngineBoots latches at its maximum value and never wraps.
+	if ( engineTime > MAX_SIGNED_INT32 ) {
+		engineBoots = Math.min (engineBoots + Math.floor (engineTime / (MAX_SIGNED_INT32 + 1)),
+				MAX_SIGNED_INT32);
+		engineTime = engineTime % (MAX_SIGNED_INT32 + 1);
+	}
+	return {
+		engineBoots: engineBoots,
+		engineTime: engineTime
+	};
+};
+
+// RFC 3414 section 3.2 step 7b(1): update our notion of the authoritative
+// engine's time from an authentic message, but only when that message advances
+// it - either snmpEngineBoots has increased, or snmpEngineTime is higher than
+// any snmpEngineTime yet seen for the current snmpEngineBoots.  The latter
+// comparison is against the highest value received rather than against our
+// locally advanced notion, so that a fast local clock cannot lock the session
+// out of ever resynchronising.
+Session.prototype.setEngineTime = function (message) {
+	var params = message.msgSecurityParameters;
+	if ( ! params || ! message.hasAuthentication () )
+		return;
+	var engineBoots = params.msgAuthoritativeEngineBoots;
+	var engineTime = params.msgAuthoritativeEngineTime;
+	var advances = this.engineTimeBoots == null
+			|| engineBoots > this.engineTimeBoots
+			|| ( engineBoots == this.engineTimeBoots
+				&& engineTime > this.latestReceivedEngineTime );
+	if ( ! advances )
+		return;
+	this.engineTimeBoots = engineBoots;
+	this.engineTimeBase = engineTime;
+	this.latestReceivedEngineTime = engineTime;
+	this.engineTimeReceivedAt = performance.now ();
+};
+
+// RFC 3414 section 3.2 step 7b(2): an authentic message from the authoritative
+// engine is outside the time window - and so must be discarded - if our notion
+// of its snmpEngineBoots has latched at its maximum value, if the message
+// disagrees with our notion of snmpEngineBoots, or if it disagrees with our
+// notion of snmpEngineTime by more than the time window.  This must be
+// evaluated after setEngineTime (), so that a message which legitimately
+// advances our notion of time is never rejected by it.
+Session.prototype.isInTimeWindow = function (message) {
+	var params = message.msgSecurityParameters;
+	if ( ! params || ! message.hasAuthentication () )
+		return true;
+	var notion = this.getEngineTime ();
+	if ( ! notion )
+		return true;
+	if ( notion.engineBoots == MAX_SIGNED_INT32 )
+		return false;
+	if ( params.msgAuthoritativeEngineBoots != notion.engineBoots )
+		return false;
+	return Math.abs (params.msgAuthoritativeEngineTime - notion.engineTime)
+			<= USM_TIME_WINDOW_SECONDS;
+};
+
+// RFC 3414 section 2.3: an outgoing request carries our current notion of the
+// authoritative engine's snmpEngineBoots and snmpEngineTime, not the values
+// learned when the session was first synchronised.
+Session.prototype.advanceEngineTime = function () {
+	if ( ! this.msgSecurityParameters )
+		return;
+	var notion = this.getEngineTime ();
+	if ( ! notion )
+		return;
+	this.msgSecurityParameters.msgAuthoritativeEngineBoots = notion.engineBoots;
+	this.msgSecurityParameters.msgAuthoritativeEngineTime = notion.engineTime;
+};
+
 Session.prototype.sendV3Req = function (pdu, feedCb, responseCb, options, port, allowReport) {
+	this.advanceEngineTime ();
 	var message = Message.createRequestV3 (this.user, this.msgSecurityParameters, pdu);
 	var reqOptions = options || {};
 	var req = new Req (this, message, feedCb, responseCb, reqOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "net-snmp",
-  "version": "3.26.2",
+  "version": "3.27.0",
   "description": "JavaScript implementation of the Simple Network Management Protocol (SNMP)",
   "author": "Mark Abrahams <mark@abrahams.co.nz>",
   "license": "MIT",

package/test/snmpv3-engine-time.test.js

@@ -0,0 +1,563 @@
+const assert = require('assert');
+const { performance } = require('perf_hooks');
+const snmp = require('../');
+
+const MAX_SIGNED_INT32 = 2147483647;
+const USM_TIME_WINDOW_SECONDS = 150;
+
+// A stand-in for a parsed Message, carrying only what the engine time methods
+// read: the USM security parameters and whether the message was authenticated.
+// The real Message.prototype.hasAuthentication returns a truthy number rather
+// than a boolean, so this mirrors that. The end-to-end suite at the bottom of
+// this file exercises the same code paths with real parsed messages.
+const fakeMessage = (engineBoots, engineTime, authenticated) => ({
+    msgSecurityParameters: {
+        msgAuthoritativeEngineID: Buffer.from('8000B98380ABCDEF12345678', 'hex'),
+        msgAuthoritativeEngineBoots: engineBoots,
+        msgAuthoritativeEngineTime: engineTime
+    },
+    hasAuthentication: () => authenticated ? 1 : 0
+});
+
+// An SNMPv1 or v2c message has no USM security parameters at all.
+const fakeCommunityMessage = () => ({
+    hasAuthentication: () => undefined
+});
+
+describe('SNMPv3 authoritative engine time (RFC 3414)', function () {
+
+    const user = {
+        name: 'betty',
+        level: snmp.SecurityLevel.authNoPriv,
+        authProtocol: snmp.AuthProtocols.sha,
+        authKey: 'illhavesomeauth'
+    };
+
+    let session;
+
+    beforeEach(function () {
+        session = snmp.createV3Session('127.0.0.1', user, { port: 16210 });
+    });
+
+    afterEach(function () {
+        if (session) {
+            session.close();
+            session = null;
+        }
+    });
+
+    // Pretend the current anchor was established `seconds` ago, without waiting.
+    const rewindAnchor = (seconds) => {
+        session.engineTimeReceivedAt -= seconds * 1000;
+    };
+
+    describe('setEngineTime - time window updates (section 3.2 step 7b(1))', function () {
+
+        it('establishes a notion of time from the first authentic message', function () {
+            session.setEngineTime(fakeMessage(3, 5000, true));
+
+            assert.strictEqual(session.engineTimeBoots, 3);
+            assert.strictEqual(session.engineTimeBase, 5000);
+            assert.strictEqual(session.latestReceivedEngineTime, 5000);
+            assert.notStrictEqual(session.engineTimeReceivedAt, null);
+        });
+
+        it('ignores a message that was not authenticated', function () {
+            session.setEngineTime(fakeMessage(3, 5000, false));
+
+            assert.strictEqual(session.engineTimeBoots, null);
+            assert.strictEqual(session.engineTimeBase, null);
+            assert.strictEqual(session.latestReceivedEngineTime, null);
+            assert.strictEqual(session.engineTimeReceivedAt, null);
+        });
+
+        it('ignores a message with no USM security parameters', function () {
+            session.setEngineTime(fakeCommunityMessage());
+
+            assert.strictEqual(session.engineTimeBoots, null);
+            assert.strictEqual(session.engineTimeReceivedAt, null);
+        });
+
+        it('updates when engineBoots has increased', function () {
+            session.setEngineTime(fakeMessage(3, 5000, true));
+            session.setEngineTime(fakeMessage(4, 20, true));
+
+            assert.strictEqual(session.engineTimeBoots, 4);
+            assert.strictEqual(session.engineTimeBase, 20);
+            assert.strictEqual(session.latestReceivedEngineTime, 20);
+        });
+
+        it('ignores a message whose engineBoots has decreased', function () {
+            session.setEngineTime(fakeMessage(3, 5000, true));
+            session.setEngineTime(fakeMessage(2, 900000, true));
+
+            assert.strictEqual(session.engineTimeBoots, 3);
+            assert.strictEqual(session.engineTimeBase, 5000);
+        });
+
+        it('updates when engineBoots is unchanged and engineTime has advanced', function () {
+            session.setEngineTime(fakeMessage(3, 5000, true));
+            session.setEngineTime(fakeMessage(3, 5060, true));
+
+            assert.strictEqual(session.engineTimeBoots, 3);
+            assert.strictEqual(session.engineTimeBase, 5060);
+            assert.strictEqual(session.latestReceivedEngineTime, 5060);
+        });
+
+        it('ignores a replay of the highest engineTime already received', function () {
+            session.setEngineTime(fakeMessage(3, 5000, true));
+            const anchoredAt = session.engineTimeReceivedAt;
+
+            session.setEngineTime(fakeMessage(3, 5000, true));
+
+            assert.strictEqual(session.engineTimeBase, 5000);
+            assert.strictEqual(session.engineTimeReceivedAt, anchoredAt);
+        });
+
+        it('ignores a replay of an engineTime below the highest already received', function () {
+            session.setEngineTime(fakeMessage(3, 5000, true));
+            session.setEngineTime(fakeMessage(3, 4000, true));
+
+            assert.strictEqual(session.engineTimeBase, 5000);
+            assert.strictEqual(session.latestReceivedEngineTime, 5000);
+        });
+
+        // Regression test: the comparison in section 3.2 step 7b(1) is against
+        // latestReceivedEngineTime, not against the locally advanced notion of
+        // snmpEngineTime. Comparing against the advanced notion would mean that
+        // a local clock running ahead of the agent could never resynchronise,
+        // leaving the session permanently outside the agent's time window.
+        it('resynchronises downwards when the local clock has raced ahead of the agent', function () {
+            session.setEngineTime(fakeMessage(1, 1000, true));
+            rewindAnchor(2000);
+            assert.strictEqual(session.getEngineTime().engineTime, 3000);
+
+            session.setEngineTime(fakeMessage(1, 1100, true));
+
+            assert.strictEqual(session.engineTimeBase, 1100);
+            assert.strictEqual(session.latestReceivedEngineTime, 1100);
+            assert.strictEqual(session.getEngineTime().engineTime, 1100);
+        });
+    });
+
+    describe('getEngineTime - local advancement (section 2.3)', function () {
+
+        it('has no notion of time before any authentic message', function () {
+            assert.strictEqual(session.getEngineTime(), null);
+        });
+
+        it('advances the notion of engineTime with the local clock', function () {
+            session.setEngineTime(fakeMessage(2, 1000, true));
+            rewindAnchor(75);
+
+            const notion = session.getEngineTime();
+            assert.strictEqual(notion.engineBoots, 2);
+            assert.strictEqual(notion.engineTime, 1075);
+        });
+
+        it('does not advance engineBoots while engineTime is in range', function () {
+            session.setEngineTime(fakeMessage(2, 1000, true));
+            rewindAnchor(100000);
+
+            assert.strictEqual(session.getEngineTime().engineBoots, 2);
+        });
+
+        it('uses a monotonic clock, so a system clock step cannot move it', function () {
+            session.setEngineTime(fakeMessage(2, 1000, true));
+
+            // engineTimeReceivedAt is a performance.now() reading, which is
+            // unrelated to Date.now() and unaffected by system clock steps.
+            assert.ok(Math.abs(session.engineTimeReceivedAt - performance.now()) < 1000);
+            assert.ok(Math.abs(session.engineTimeReceivedAt - Date.now()) > 1000000);
+        });
+
+        // RFC 3414 section 2.2.2: when snmpEngineTime reaches its maximum value,
+        // snmpEngineBoots is incremented and snmpEngineTime is reset to zero.
+        it('rolls engineTime over and increments engineBoots at the 31-bit limit', function () {
+            session.setEngineTime(fakeMessage(7, MAX_SIGNED_INT32 - 10, true));
+            rewindAnchor(30);
+
+            const notion = session.getEngineTime();
+            assert.strictEqual(notion.engineBoots, 8);
+            assert.strictEqual(notion.engineTime, 19);
+            assert.ok(notion.engineTime >= 0 && notion.engineTime <= MAX_SIGNED_INT32);
+        });
+
+        it('emits the maximum engineTime rather than rolling over early', function () {
+            session.setEngineTime(fakeMessage(7, MAX_SIGNED_INT32 - 10, true));
+            rewindAnchor(10);
+
+            const notion = session.getEngineTime();
+            assert.strictEqual(notion.engineBoots, 7);
+            assert.strictEqual(notion.engineTime, MAX_SIGNED_INT32);
+        });
+
+        it('latches engineBoots at its maximum value rather than wrapping', function () {
+            session.setEngineTime(fakeMessage(MAX_SIGNED_INT32 - 1, 0, true));
+            rewindAnchor((MAX_SIGNED_INT32 + 1) * 5);
+
+            assert.strictEqual(session.getEngineTime().engineBoots, MAX_SIGNED_INT32);
+        });
+    });
+
+    describe('isInTimeWindow - timeliness checks (section 3.2 step 7b(2))', function () {
+
+        it('accepts a message when no notion of time has been established', function () {
+            assert.strictEqual(session.isInTimeWindow(fakeMessage(1, 1000, true)), true);
+        });
+
+        it('accepts an unauthenticated message without checking the window', function () {
+            session.setEngineTime(fakeMessage(1, 1000, true));
+
+            assert.strictEqual(session.isInTimeWindow(fakeMessage(1, 999999, false)), true);
+        });
+
+        it('accepts a message with no USM security parameters', function () {
+            assert.strictEqual(session.isInTimeWindow(fakeCommunityMessage()), true);
+        });
+
+        it('accepts the message that just established the notion of time', function () {
+            const message = fakeMessage(1, 1000, true);
+            session.setEngineTime(message);
+
+            assert.strictEqual(session.isInTimeWindow(message), true);
+        });
+
+        it('accepts a message inside the time window', function () {
+            session.setEngineTime(fakeMessage(1, 1000, true));
+
+            assert.strictEqual(session.isInTimeWindow(fakeMessage(1, 900, true)), true);
+        });
+
+        it('accepts a message exactly at the edge of the time window', function () {
+            session.setEngineTime(fakeMessage(1, 1000, true));
+
+            assert.strictEqual(
+                session.isInTimeWindow(fakeMessage(1, 1000 - USM_TIME_WINDOW_SECONDS, true)), true);
+        });
+
+        it('rejects a message more than the time window behind our notion', function () {
+            session.setEngineTime(fakeMessage(1, 1000, true));
+
+            assert.strictEqual(
+                session.isInTimeWindow(fakeMessage(1, 1000 - USM_TIME_WINDOW_SECONDS - 1, true)),
+                false);
+        });
+
+        it('rejects a message whose engineBoots disagrees with our notion', function () {
+            session.setEngineTime(fakeMessage(5, 1000, true));
+
+            assert.strictEqual(session.isInTimeWindow(fakeMessage(4, 1000, true)), false);
+        });
+
+        it('rejects every message once engineBoots has latched at its maximum', function () {
+            session.setEngineTime(fakeMessage(MAX_SIGNED_INT32, 1000, true));
+
+            assert.strictEqual(session.isInTimeWindow(fakeMessage(MAX_SIGNED_INT32, 1000, true)),
+                false);
+        });
+
+        it('measures the window against the advanced notion, not the anchor', function () {
+            session.setEngineTime(fakeMessage(1, 1000, true));
+            rewindAnchor(200);
+
+            // Our notion is now 1200, so the original anchor value of 1000 has
+            // fallen outside the window, while 1200 is at its centre.
+            assert.strictEqual(session.isInTimeWindow(fakeMessage(1, 1000, true)), false);
+            assert.strictEqual(session.isInTimeWindow(fakeMessage(1, 1200, true)), true);
+        });
+    });
+
+    describe('advanceEngineTime - outgoing requests (section 2.3)', function () {
+
+        it('does nothing when the session has no cached security parameters', function () {
+            session.setEngineTime(fakeMessage(1, 1000, true));
+            assert.strictEqual(session.msgSecurityParameters, undefined);
+
+            session.advanceEngineTime();
+
+            assert.strictEqual(session.msgSecurityParameters, undefined);
+        });
+
+        it('does nothing when no notion of time has been established', function () {
+            session.msgSecurityParameters = {
+                msgAuthoritativeEngineBoots: 0,
+                msgAuthoritativeEngineTime: 0
+            };
+
+            session.advanceEngineTime();
+
+            assert.strictEqual(session.msgSecurityParameters.msgAuthoritativeEngineBoots, 0);
+            assert.strictEqual(session.msgSecurityParameters.msgAuthoritativeEngineTime, 0);
+        });
+
+        it('writes the advanced notion into the cached security parameters', function () {
+            session.msgSecurityParameters = {
+                msgAuthoritativeEngineBoots: 1,
+                msgAuthoritativeEngineTime: 1000
+            };
+            session.setEngineTime(fakeMessage(1, 1000, true));
+            rewindAnchor(600);
+
+            session.advanceEngineTime();
+
+            assert.strictEqual(session.msgSecurityParameters.msgAuthoritativeEngineBoots, 1);
+            assert.strictEqual(session.msgSecurityParameters.msgAuthoritativeEngineTime, 1600);
+        });
+
+        it('carries the advanced engineTime on the outgoing request', function () {
+            session.msgSecurityParameters = {
+                msgAuthoritativeEngineID: Buffer.from('8000B98380ABCDEF12345678', 'hex'),
+                msgAuthoritativeEngineBoots: 1,
+                msgAuthoritativeEngineTime: 1000
+            };
+            session.setEngineTime(fakeMessage(1, 1000, true));
+            rewindAnchor(420);
+
+            let sent;
+            session.send = (req) => { sent = req; };
+            session.get(['1.3.6.1.2.1.1.1.0'], function () {});
+
+            assert.ok(sent, 'a request should have been handed to send()');
+            assert.strictEqual(sent.message.msgSecurityParameters.msgAuthoritativeEngineBoots, 1);
+            assert.strictEqual(sent.message.msgSecurityParameters.msgAuthoritativeEngineTime, 1420);
+        });
+    });
+});
+
+// These tests drive a real agent over the loopback interface, so the engine
+// time methods are fed genuine parsed and authenticated Messages rather than
+// the stand-in above. They confirm the wiring in Session.onMsg as well as the
+// assumption that Message.hasAuthentication distinguishes the authenticated
+// GetResponse from the unauthenticated discovery Report.
+describe('SNMPv3 authoritative engine time over the wire', function () {
+
+    const agentPort = 16211;
+    const engineID = '8000B98380DEADBEEF00000001';
+    const sysDescrOid = '1.3.6.1.2.1.1.1.0';
+
+    const authUser = {
+        name: 'betty',
+        level: snmp.SecurityLevel.authNoPriv,
+        authProtocol: snmp.AuthProtocols.sha,
+        authKey: 'illhavesomeauth'
+    };
+
+    const authPrivUser = {
+        name: 'wilma',
+        level: snmp.SecurityLevel.authPriv,
+        authProtocol: snmp.AuthProtocols.sha,
+        authKey: 'illhavesomeauth',
+        privProtocol: snmp.PrivProtocols.aes,
+        privKey: 'andsomepriv'
+    };
+
+    const noAuthUser = {
+        name: 'fred',
+        level: snmp.SecurityLevel.noAuthNoPriv
+    };
+
+    let agent;
+    let sessions;
+
+    // The agent echoes the request's engineBoots and engineTime back in its
+    // response, so to model an authoritative engine with a clock of its own we
+    // overwrite those values on the way out. Clearing the cached buffer makes
+    // the message re-serialise and re-authenticate over the new values, so the
+    // session receives a properly authenticated message throughout.
+    let agentEngineBoots = null;
+    let agentEngineTime = null;
+    // Values used for the unauthenticated discovery Report only, so that tests
+    // can tell which message a session actually synchronised from.
+    let agentReportEngineBoots = null;
+    let agentReportEngineTime = null;
+
+    before(function () {
+        agent = snmp.createAgent({ port: agentPort, engineID: engineID, disableAuthorization: false },
+            function () {});
+        const authorizer = agent.getAuthorizer();
+        authorizer.addUser(authUser);
+        authorizer.addUser(authPrivUser);
+        authorizer.addUser(noAuthUser);
+        agent.registerProvider({
+            name: 'sysDescr',
+            type: snmp.MibProviderType.Scalar,
+            oid: '1.3.6.1.2.1.1.1',
+            scalarType: snmp.ObjectType.OctetString,
+            maxAccess: snmp.MaxAccess['read-only']
+        });
+        agent.getMib().setScalarValue('sysDescr', 'engine time test agent');
+
+        const listenerSend = agent.listener.send.bind(agent.listener);
+        agent.listener.send = function (message, rinfo, socket) {
+            const isReport = message.pdu && message.pdu.type === snmp.PduType.Report;
+            const boots = isReport && agentReportEngineBoots !== null
+                ? agentReportEngineBoots
+                : agentEngineBoots;
+            const time = isReport && agentReportEngineTime !== null
+                ? agentReportEngineTime
+                : agentEngineTime;
+            if (time !== null && message.msgSecurityParameters
+                    && message.msgSecurityParameters.msgAuthoritativeEngineBoots !== undefined) {
+                message.msgSecurityParameters.msgAuthoritativeEngineBoots = boots;
+                message.msgSecurityParameters.msgAuthoritativeEngineTime = time;
+                message.buffer = null;
+            }
+            return listenerSend(message, rinfo, socket);
+        };
+    });
+
+    after(function (done) {
+        agent.close(() => done());
+    });
+
+    beforeEach(function () {
+        sessions = [];
+        agentEngineBoots = null;
+        agentEngineTime = null;
+        agentReportEngineBoots = null;
+        agentReportEngineTime = null;
+    });
+
+    afterEach(function () {
+        sessions.forEach((s) => s.close());
+        sessions = [];
+    });
+
+    const createSession = (user) => {
+        const session = snmp.createV3Session('127.0.0.1', user,
+            { port: agentPort, timeout: 2000, retries: 0 });
+        sessions.push(session);
+        return session;
+    };
+
+    const get = (session) => new Promise((resolve, reject) => {
+        session.get([sysDescrOid], (error, varbinds) => {
+            if (error) {
+                reject(error);
+            } else if (varbinds[0] instanceof Error) {
+                reject(varbinds[0]);
+            } else {
+                resolve(varbinds);
+            }
+        });
+    });
+
+    it('synchronises from an authenticated GetResponse, not the discovery Report',
+        async function () {
+            agentEngineBoots = 12;
+            agentEngineTime = 345678;
+            // The discovery Report is not authenticated, so these values must be
+            // ignored no matter how far ahead of the real engine time they are.
+            agentReportEngineBoots = 99;
+            agentReportEngineTime = MAX_SIGNED_INT32 - 1;
+
+            const session = createSession(authUser);
+            await get(session);
+
+            assert.strictEqual(session.engineTimeBoots, 12);
+            assert.strictEqual(session.engineTimeBase, 345678);
+            assert.strictEqual(session.latestReceivedEngineTime, 345678);
+        });
+
+    it('synchronises over authPriv as well as authNoPriv', async function () {
+        agentEngineBoots = 4;
+        agentEngineTime = 99000;
+
+        const session = createSession(authPrivUser);
+        await get(session);
+
+        assert.strictEqual(session.engineTimeBoots, 4);
+        assert.strictEqual(session.engineTimeBase, 99000);
+    });
+
+    it('never synchronises for a noAuthNoPriv user, since no message is authentic',
+        async function () {
+            agentEngineBoots = 4;
+            agentEngineTime = 99000;
+
+            const session = createSession(noAuthUser);
+            await get(session);
+
+            assert.strictEqual(session.engineTimeBoots, null);
+            assert.strictEqual(session.engineTimeReceivedAt, null);
+        });
+
+    it('sends an advanced engineTime on a later request', async function () {
+        agentEngineBoots = 2;
+        agentEngineTime = 1000;
+
+        const session = createSession(authUser);
+        await get(session);
+
+        // Pretend 500 seconds have passed since the response arrived, and let
+        // the agent's clock advance by the same amount.
+        session.engineTimeReceivedAt -= 500 * 1000;
+        agentEngineTime = 1500;
+
+        const sent = [];
+        const send = session.send.bind(session);
+        session.send = function (req, noWait) {
+            sent.push(req.message.msgSecurityParameters.msgAuthoritativeEngineTime);
+            return send(req, noWait);
+        };
+
+        await get(session);
+
+        assert.deepStrictEqual(sent, [1500]);
+        assert.strictEqual(session.engineTimeBase, 1500);
+    });
+
+    it('tracks the agent across a reboot that resets its engineTime', async function () {
+        agentEngineBoots = 2;
+        agentEngineTime = 900000;
+
+        const session = createSession(authUser);
+        await get(session);
+        assert.strictEqual(session.engineTimeBase, 900000);
+
+        agentEngineBoots = 3;
+        agentEngineTime = 12;
+        await get(session);
+
+        assert.strictEqual(session.engineTimeBoots, 3);
+        assert.strictEqual(session.engineTimeBase, 12);
+    });
+
+    it('reports a response that falls outside the time window', async function () {
+        agentEngineBoots = 2;
+        agentEngineTime = 1000;
+
+        const session = createSession(authUser);
+        await get(session);
+
+        // A response claiming an engineTime below the highest already received
+        // cannot advance our notion of time, and is far enough behind it to be
+        // outside the window - RFC 3414 section 3.2 step 7b(2) discards it.
+        agentEngineTime = 1000 - 151;
+
+        await assert.rejects(get(session), (error) => {
+            assert.ok(error instanceof snmp.ResponseInvalidError, 'expected ResponseInvalidError');
+            assert.strictEqual(error.code, snmp.ResponseInvalidCode.ENotInTimeWindow);
+            return true;
+        });
+
+        // Our notion of the agent's time is left untouched by the discard.
+        assert.strictEqual(session.engineTimeBoots, 2);
+        assert.strictEqual(session.latestReceivedEngineTime, 1000);
+    });
+
+    it('still accepts a response that is only slightly out of order', async function () {
+        agentEngineBoots = 2;
+        agentEngineTime = 1000;
+
+        const session = createSession(authUser);
+        await get(session);
+
+        agentEngineTime = 1000 - 20;
+        const varbinds = await get(session);
+
+        assert.strictEqual(varbinds[0].oid, sysDescrOid);
+        assert.strictEqual(session.latestReceivedEngineTime, 1000);
+    });
+});