@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/utility/operation_authorization.ts

@@ -47,6 +47,8 @@ import { handleHDBError, hdbErrors } from '../utility/errors/hdbError.ts';
 import * as regDeprecated from '../resources/registrationDeprecated.ts';
 import * as deploymentOperations from '../components/deploymentOperations.ts';
 import * as secretOperations from '../components/secretOperations.ts';
+import * as trustPolicyOperations from '../security/authn/oidc/trustPolicyOperations.ts';
+import * as tokenExchange from '../security/authn/oidc/tokenExchange.ts';
 
 const requiredPermissions = new Map();
 const DELETE_PERM = 'delete';
@@ -88,6 +90,8 @@ const BULK_OPS = {
 	CSV_FILE_LOAD: 'csvFileLoad',
 	IMPORT_FROM_S3: 'importFromS3',
 };
+/** The same set, precomputed: `isBulkLoadOperation` runs on every operations authorization. */
+const BULK_OP_NAMES = new Set(Object.values(BULK_OPS));
 
 const STRUCTURE_USER_OPS = [
 	schema.createTable.name,
@@ -147,6 +151,13 @@ requiredPermissions.set(
 	write.upsert.name,
 	new (permission as any)(false, [INSERT_PERM, UPDATE_PERM], terms.OPERATIONS_ENUM.UPSERT)
 );
+// Same grants as `upsert`, and the same as REST `PUT` enforces: creating needs insert, replacing an
+// existing record needs update. A full replace can DROP attributes, which is why the
+// attribute-scoped denial below applies to it.
+requiredPermissions.set(
+	write.put.name,
+	new (permission as any)(false, [INSERT_PERM, UPDATE_PERM], terms.OPERATIONS_ENUM.PUT)
+);
 requiredPermissions.set(
 	search.searchByConditions.name,
 	new (permission as any)(false, [READ_PERM], terms.OPERATIONS_ENUM.SEARCH_BY_CONDITIONS)
@@ -359,6 +370,28 @@ requiredPermissions.set(
 	new (permission as any)(true, [], terms.OPERATIONS_ENUM.GET_SECRETS_PUBLIC_KEY)
 );
 
+// OIDC trust policies (#2171). A policy lets an external CI run authenticate as a Harper user, so
+// these are SU-only; the handlers ALSO enforce super_user directly so they cannot be delegated
+// through a role's `operations` allowlist (gate-2 bypass below).
+requiredPermissions.set(
+	trustPolicyOperations.addOidcTrust.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.ADD_OIDC_TRUST)
+);
+requiredPermissions.set(
+	trustPolicyOperations.listOidcTrust.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.LIST_OIDC_TRUST)
+);
+requiredPermissions.set(
+	trustPolicyOperations.dropOidcTrust.name,
+	new (permission as any)(true, [], terms.OPERATIONS_ENUM.DROP_OIDC_TRUST)
+);
+// The exchange is unauthenticated by design — it authenticates its own caller against a trust
+// policy, the way create_authentication_tokens does against a password.
+requiredPermissions.set(
+	tokenExchange.exchangeOidcToken.name,
+	new (permission as any)(false, [], terms.OPERATIONS_ENUM.EXCHANGE_OIDC_TOKEN)
+);
+
 //Below are functions that are currently open to all roles
 requiredPermissions.set(regDeprecated.getRegistrationInfo.name, new (permission as any)(false, []));
 requiredPermissions.set(user.userInfo.name, new (permission as any)(false, [], terms.OPERATIONS_ENUM.USER_INFO));
@@ -406,6 +439,7 @@ requiredPermissions.set(terms.VALID_SQL_OPS_ENUM.UPDATE, new (permission as any)
 module.exports = {
 	verifyPerms,
 	verifyPermsAST,
+	verifyOperationsAllowlist,
 	verifyBulkLoadAttributePerms,
 	registerOperationPermission,
 	unregisterOperationPermission,
@@ -418,7 +452,77 @@ module.exports = {
  * @param operation - The operation specified in the call.
  * @returns {null | PermissionResponseObject} - null if permissions match, errors returned in the PermissionResponseObject
  */
-export function verifyPermsAST(ast, userObject, operation) {
+/**
+ * Token-scoped narrowing: a minted operation token may carry a subset of what its user's role allows,
+ * so one credential can be handed out with less authority than the user has (an OIDC trust policy
+ * uses this to scope a single workflow). Returns a denial, or undefined when the scope permits — or
+ * when there is no scope, which is every token minted before this existed.
+ *
+ * Shared by verifyPerms AND verifyPermsAST, and called first in both. Four ways this gets bypassed
+ * if it moves or is incomplete:
+ *
+ * 1. `sql` dispatches to verifyPermsAST, in a branch mutually exclusive with the verifyPerms call
+ *    (server/serverHelpers/serverUtilities.ts). A gate in only one of them means a token scoped to
+ *    `get_status` can still run arbitrary SQL against whatever its role can reach.
+ * 2. Both functions `return null` early for a super_user — the identity that most needs constraining.
+ * 3. verifyPerms' `operations` gate 2 also returns null, treating an explicit listing of an SU-only
+ *    operation as a deliberate grant.
+ * 4. Operations that never reach verifyPerms at all: create_authentication_tokens (NO_AUTH),
+ *    refresh_operation_token, and impersonation each PRODUCE a new credential or principal, so the
+ *    scope has to be carried forward there too or a scoped token mints an unscoped one. That carry-
+ *    forward lives in tokenAuthentication.ts and impersonation.ts, not here.
+ *
+ * It can only subtract. The scope is deliberately NOT merged into `permission.operations`, because
+ * that field is not purely narrowing (see gate 2) — merging into it could widen instead.
+ *
+ * `apiOperation` MUST be the snake_case API operation the caller actually invoked (`deploy_component`,
+ * `sql`, `export_local`, ...) — i.e. `requestJson.operation`, the same namespace the policy's scope is
+ * written in. It is emphatically NOT the handler function name: many handlers have no `api_name`
+ * mapping (deploy_component → `deployComponent`) and some are shared across operations
+ * (`search_by_id`/`search_by_hash`), so resolving the scope name from the handler both denies the
+ * feature's own headline op and conflates aliases. Callers pass the real operation.
+ */
+function tokenScopeDenial(userObject: any, apiOperation: string) {
+	// `!= null`, not `!== undefined`: an unscoped policy stores `operations: null`, and expanding a
+	// null would throw rather than fall through to the role.
+	const tokenOperations = userObject?.tokenOperations;
+	if (tokenOperations == null) return undefined;
+
+	// `instanceof Set`, not just presence: this memo rides on hdb_user, and a job persists that user
+	// into hdb_job.request, where msgpackr round-trips a Set back as a plain Array. Trusting the
+	// memo's presence would then call .has() on an Array and throw a TypeError out of the auth gate
+	// — still fail-closed, but as a 500 rather than a denial, and only inside a job worker.
+	let scopedOps = userObject._expandedTokenOperations;
+	if (!(scopedOps instanceof Set)) {
+		scopedOps = userObject._expandedTokenOperations = expandOperationsPerms(tokenOperations);
+	}
+	if (scopedOps.has(apiOperation)) return undefined;
+
+	harperLogger.info(`Operation '${apiOperation}' is outside the scope of the presented token`);
+	return new PermissionResponseObject().handleUnauthorizedItem(HDB_ERROR_MSGS.OP_NOT_IN_OPERATIONS(apiOperation));
+}
+
+/**
+ * A scope naming `sql` grants the SQL interface, not unrestricted DML through it.
+ *
+ * `read_only` expands to include `sql` — the group defers DML enforcement to table CRUD permissions
+ * (see its note in operationPermissions.ts) — but verifyPermsAST returns null outright for a
+ * super_user before any table check runs. Without this, a token scoped to `read_only` could DELETE,
+ * which is the one thing that name promises it cannot do.
+ *
+ * So a write statement additionally requires its matching data operation in scope. That is exactly
+ * what separates `read_only` (no insert/update/delete) from `standard_user` (all three), with no
+ * need to track which group admitted `sql`. A bare `['sql']` therefore admits SELECT only; name the
+ * write operations alongside it to allow more. Anything that is not a recognized SELECT falls
+ * through to the same check and is denied unless named, so an unfamiliar statement type fails closed.
+ */
+function sqlWriteScopeDenial(userObject: any, sqlVariant: string) {
+	if (userObject?.tokenOperations == null) return undefined;
+	if (sqlVariant === terms.VALID_SQL_OPS_ENUM.SELECT) return undefined;
+	return tokenScopeDenial(userObject, sqlVariant);
+}
+
+export function verifyPermsAST(ast, userObject, operation, apiOperation = terms.OPERATIONS_ENUM.SQL) {
 	//TODO - update these validation checks to use validate.js
 	if (commonUtils.isEmptyOrZeroLength(ast)) {
 		harperLogger.info('verify_perms_ast has an empty user parameter');
@@ -432,6 +536,15 @@ export function verifyPermsAST(ast, userObject, operation) {
 		harperLogger.info('verify_perms_ast has a null operation parameter');
 		throw handleHDBError(new Error());
 	}
+
+	// `operation` here is the SQL statement variant (select/insert/...), not the API operation. The
+	// scope is checked against `apiOperation` — the top-level operation the caller invoked, which is
+	// `sql` for a direct SQL call but `export_local`/`export_to_s3` for a job whose inner
+	// search_operation is SQL. Checking a hardcoded `sql` would let a token scoped only to `sql` start
+	// an export that its scope excludes. Ahead of the super_user bypass, as on the NoSQL path.
+	const scopeDenial = tokenScopeDenial(userObject, apiOperation) ?? sqlWriteScopeDenial(userObject, operation);
+	if (scopeDenial) return scopeDenial;
+
 	try {
 		const bucketModule = require('../sqlTranslator/sql_statement_bucket');
 		const bucket = bucketModule.default || bucketModule;
@@ -520,6 +633,28 @@ export function verifyPermsAST(ast, userObject, operation) {
 	}
 }
 
+/**
+ * Gate 1 of the role `operations` allowlist, callable from every authorization path. The SQL path
+ * (chooseOperation → checkASTPermissions) never reaches verifyPerms, so it must call this
+ * directly — otherwise an allowlisted role could reach unlisted operations through `sql`.
+ * Returns null when allowed (or no allowlist present), a PermissionResponseObject denial otherwise.
+ */
+export function verifyOperationsAllowlist(requestJson: any, operationFunctionName: string) {
+	const rolePermission = requestJson.hdb_user?.role?.permission;
+	const allowedOperationsList = rolePermission?.operations;
+	if (allowedOperationsList == null) return null;
+	// _expandedOperations is pre-built at cache-load time (O(1) lookup).
+	// Fall back to on-demand expansion for inline-asserted roles (e.g. impersonation via hdb_user in body).
+	const allowedOps = rolePermission._expandedOperations ?? expandOperationsPerms(allowedOperationsList);
+	// operationFunctionName is the internal camelCase function name; allowedOps contains snake_case
+	// API names. Resolve via the api_name stored on the permission entry (set at registration time).
+	const opApiName = requiredPermissions.get(operationFunctionName)?.api_name ?? operationFunctionName;
+	if (!allowedOps.has(opApiName)) {
+		return new PermissionResponseObject().handleUnauthorizedItem(HDB_ERROR_MSGS.OP_NOT_IN_OPERATIONS(opApiName));
+	}
+	return null;
+}
+
 /**
  * Verifies permissions and restrictions for the NoSQL operation based on the user's assigned role.
  *
@@ -527,7 +662,7 @@ export function verifyPermsAST(ast, userObject, operation) {
  * @param operation - The name of the operation specified in the request.
  * @returns { null | PermissionResponseObject } - null if permissions match, errors are consolidated into PermissionResponseObj.
  */
-export function verifyPerms(requestJson: any, operation: any, _options?: any) {
+export function verifyPerms(requestJson: any, operation: any, options?: { apiOperation?: string }) {
 	if (
 		requestJson === null ||
 		operation === null ||
@@ -546,18 +681,51 @@ export function verifyPerms(requestJson: any, operation: any, _options?: any) {
 		op = operation;
 	}
 	//we need to use the action value, if present, to ensure the correct permission is checked below
-	let action = requestJson.action;
-
-	let operationSchema = requestJson.schema ?? requestJson.database;
+	// `action` narrows the required permissions to just that one — `hasPermissions` does it for table
+	// permissions and `checkAttributePerms` for attribute permissions — because a bulk load carries
+	// `action: insert|update|upsert` and only needs the permission for what it will actually do.
+	//
+	// Honoured ONLY for a real bulk-load operation. `action` is an unknown-but-accepted key on the
+	// shared write validator, so taking it from any request let a caller pick which half of an
+	// operation's permissions to be checked against: `{operation:'put', action:'insert'}` from a role
+	// with `insert: true, update: false` replaced an existing record, and `action:'update'` created a
+	// missing one with no insert permission. `upsert` had the same shape before `put` existed.
+	//
+	// Both narrowing sites read this one variable, so gating it here covers both. The bulk path is
+	// unaffected: `verifyBulkLoadAttributePerms` receives the real action from
+	// `bulkLoad.validateChunk`, not from here.
+	let action = isBulkLoadOperation(op) ? requestJson.action : undefined;
+
+	// Resolved through the same helper the handlers use (`transformReq` delegates to it), because
+	// authorization runs BEFORE `transformReq` and any disagreement about the target means the
+	// permissions checked are not the permissions for the write that happens. This used to be a
+	// local `schema ?? database`, which diverged from the handlers in two separately exploitable
+	// ways: it kept a falsy-but-present `database: 0` instead of defaulting, and it preferred
+	// `schema` where the handlers prefer `database` — so a request could be authorized against one
+	// database and written to another. With no target resolved at all, `schemaTableMap` stayed empty
+	// and `hasPermissions` iterated nothing, authorizing by vacuous truth.
+	let operationSchema = commonUtils.resolveTargetDatabase(requestJson);
 	let table = requestJson.table;
 
 	let schemaTableMap = new Map();
-	if (operationSchema && table) {
+	// `table != undefined`, not truthy: `hdbTable` is `Joi.alternatives(Joi.string(), Joi.number())`
+	// (validation/common_validators.ts), so a table named `0` validates and a truthy test drops it
+	// from the map — leaving `hasPermissions` nothing to iterate, which authorizes by vacuous truth.
+	// The same falsy-vs-nullish distinction the database resolution above turns on.
+	if (operationSchema != undefined && table != undefined) {
 		schemaTableMap.set(operationSchema, [table]);
 	}
 
 	const permsResponse = new PermissionResponseObject();
 
+	// The top-level API operation the caller invoked — the namespace the policy scope is written in.
+	// For a job (export_local/export_to_s3), the dispatcher passes the nested search_operation as
+	// requestJson, so requestJson.operation is the *inner* op (e.g. search_by_conditions); the caller
+	// threads the real top-level op through `options.apiOperation` so a read-scoped token cannot ride
+	// an export. Never `op` (the handler name), which would deny deploy_component and conflate aliases.
+	const scopeDenial = tokenScopeDenial(requestJson.hdb_user, options?.apiOperation ?? requestJson.operation);
+	if (scopeDenial) return scopeDenial;
+
 	if (
 		commonUtils.isEmptyOrZeroLength(requestJson.hdb_user?.role) ||
 		commonUtils.isEmptyOrZeroLength(requestJson.hdb_user?.role?.permission)
@@ -568,6 +736,15 @@ export function verifyPerms(requestJson: any, operation: any, _options?: any) {
 		return permsResponse.handleUnauthorizedItem(HDB_ERROR_MSGS.USER_HAS_NO_PERMS(requestJson.hdb_user?.username));
 	}
 
+	// Gate 1 of the optional `operations` allowlist: when present, only ops explicitly listed (or
+	// expanded from a group) are reachable. This must run before EVERY privilege early-return below
+	// (super_user, structure_user, system-table allowances) — otherwise a role combining one of
+	// those flags with a restrictive allowlist could reach ops outside its list. Gate 2 (the
+	// SU-only-op bypass for explicitly listed ops) stays below, after the ambient privilege checks.
+	const allowlistDenial = verifyOperationsAllowlist(requestJson, op);
+	if (allowlistDenial) return allowlistDenial;
+	const allowedOperationsList = requestJson.hdb_user?.role?.permission?.operations;
+
 	const isSuperUser = !!requestJson.hdb_user?.role?.permission?.super_user;
 	const structureUser = requestJson.hdb_user?.role?.permission?.structure_user;
 	// set to true if this operation affects a system table.  Only su can read from system tables, but can't update/delete.
@@ -618,36 +795,18 @@ export function verifyPerms(requestJson: any, operation: any, _options?: any) {
 		);
 	}
 
-	// operations is an optional allowlist on the role. When present, it acts as a two-gate check:
-	// Gate 1 — operation allowlist: only ops explicitly listed (or expanded from a group) are reachable.
-	//           Any unlisted op is denied here, before table CRUD checks even run.
-	// Gate 2 — SU bypass: if the op passed gate 1 and is normally restricted to super_user, the explicit
-	//           listing is treated as a deliberate admin grant and allowed immediately (return null).
-	//           Non-SU ops that pass gate 1 fall through to the normal table CRUD checks below.
-	const permission = requestJson.hdb_user?.role?.permission;
-	const operations = permission?.operations;
-	if (operations !== undefined) {
-		// _expandedOperations is pre-built at cache-load time (O(1) lookup).
-		// Fall back to on-demand expansion for inline-asserted roles (e.g. impersonation via hdb_user in body).
-		const allowedOps = permission._expandedOperations ?? expandOperationsPerms(operations);
-		// op is the internal camelCase function name; allowedOps contains snake_case API names.
-		// Resolve via the api_name stored on the permission entry (set at registration time).
-		const opApiName = requiredPermissions.get(op)?.api_name ?? op;
-		// Gate 1: op not in allowlist — deny regardless of table CRUD permissions.
-		if (!allowedOps.has(opApiName)) {
-			return permsResponse.handleUnauthorizedItem(HDB_ERROR_MSGS.OP_NOT_IN_OPERATIONS(opApiName));
-		}
-		// Gate 2: op is SU-only but was explicitly granted via operations — allow without super_user.
-		// Without this, the SU check further below would still deny it even though it passed gate 1.
-		// TODO: ops registered with both requires_su AND non-empty CRUD perms have their table-level
-		// CRUD check bypassed here. Should fall through for those instead of returning null
-		// unconditionally. The managed-backup ops share this shape but self-enforce super_user in their
-		// handlers/validators (dataLayer/rocksdbBackup.ts requireSuperUser), so they are not delegable
-		// regardless; get_backup remains the one that relies solely on this gate. Low risk today but
-		// worth tightening.
-		if (requiredPermissions.get(op)?.requires_su) {
-			return null;
-		}
+	// Gate 2 of the `operations` allowlist (gate 1 ran above, before the privilege early-returns):
+	// the op passed the allowlist, so if it is normally restricted to super_user, the explicit
+	// listing is treated as a deliberate admin grant and allowed immediately (return null).
+	// Non-SU ops that passed gate 1 fall through to the normal table CRUD checks below.
+	// TODO: ops registered with both requires_su AND non-empty CRUD perms have their table-level
+	// CRUD check bypassed here. Should fall through for those instead of returning null
+	// unconditionally. The managed-backup ops share this shape but self-enforce super_user in their
+	// handlers/validators (dataLayer/rocksdbBackup.ts requireSuperUser), so they are not delegable
+	// regardless; get_backup remains the one that relies solely on this gate. Low risk today but
+	// worth tightening.
+	if (allowedOperationsList !== undefined && requiredPermissions.get(op)?.requires_su) {
+		return null;
 	}
 
 	const fullRolePerms = permsTranslator.getRolePermissions(requestJson.hdb_user?.role);
@@ -676,6 +835,16 @@ export function verifyPerms(requestJson: any, operation: any, _options?: any) {
 		}
 	}
 
+	// Fail closed on an unresolved target. `hasPermissions` iterates `schemaTableMap`, so an empty map
+	// authorizes by vacuous truth — the shape of this whole bug class, and of the SQL path's
+	// GHSA-5c29-q62v-jrwf, whose fix carries the same backstop. `resolveTargetDatabase` always
+	// returns a database, so a named table always populates the map and this is unreachable today; it
+	// is here so that a future change to target resolution fails safe instead of silently authorizing
+	// everything. That also means no test can cover it, which is the point rather than an omission.
+	if (table != undefined && schemaTableMap.size === 0) {
+		return permsResponse.handleUnauthorizedItem(HDB_ERROR_MSGS.UNKNOWN_OP_AUTH_ERROR(op, operationSchema, table));
+	}
+
 	let failedPermissions = hasPermissions(requestJson.hdb_user, op, schemaTableMap, permsResponse, action);
 	//check if failedTablePerms are back and return them B/C it will be an op-level permission issue
 	if (failedPermissions) {
@@ -706,8 +875,17 @@ export function verifyPerms(requestJson: any, operation: any, _options?: any) {
 		}
 	}
 
-	const recordAttrs = getRecordAttributes(requestJson);
+	const recordAttrs = getRecordAttributes(requestJson, op);
 	const attrPermissions = getAttributePermissions(requestJson.hdb_user?.role?.permission, operationSchema, table);
+	// A `put` replaces the whole record, so it REMOVES every attribute the request omits — and
+	// `checkAttributePerms` below only sees the attributes a request SUPPLIES, so it cannot police
+	// those removals. An attribute-scoped role could otherwise erase an attribute it has no `update`
+	// permission for by leaving it out. REST closes the same gap in `Table.allowUpdate` by restoring
+	// such attributes from the stored record, which needs the stored record; this runs before anything
+	// is read, so it denies instead. Roles that scope no attribute are unaffected.
+	if (attrPermissions.size > 0 && op === write.put.name) {
+		return permsResponse.handleUnauthorizedItem(HDB_ERROR_MSGS.PUT_WITH_ATTRIBUTE_PERMS(operationSchema, table));
+	}
 	checkAttributePerms(recordAttrs, attrPermissions, op, table, operationSchema, permsResponse, action);
 
 	//This result value will be null if no perms issues were found in checkAttributePerms
@@ -913,12 +1091,20 @@ export function checkAttributePerms(
  * @param json - json containing the request
  * @returns {Set} - all attributes affected by the request statement.
  */
-function getRecordAttributes(json) {
+/** Whether the operation checks attribute permissions per chunk rather than from this request. */
+function isBulkLoadOperation(operationName): boolean {
+	return BULK_OP_NAMES.has(operationName);
+}
+
+function getRecordAttributes(json, operationName?) {
 	let affectedAttributes = new Set();
 	try {
-		//Bulk load operations need to have attr-level permissions checked during the validateChunk step of the operation
-		// in the bulkLoad.js methods
-		if (json.action) {
+		// Bulk load operations have their attribute permissions checked per chunk instead, in
+		// `bulkLoad.validateChunk` — the records aren't in this request. That opt-out is keyed on the
+		// OPERATION, never on the caller-supplied `action` field: `action` is an unknown-but-accepted
+		// key on the insert/update/upsert validator, so inferring the opt-out from its presence let any
+		// direct request skip every attribute check by adding `action: "update"` to the body.
+		if (isBulkLoadOperation(operationName)) {
 			return affectedAttributes;
 		}
 		if (json.operation === terms.OPERATIONS_ENUM.SEARCH_BY_CONDITIONS) {
@@ -980,7 +1166,10 @@ export function getAttributePermissions(rolePerms, operationSchema, table) {
 	}
 	//Some commands do not require a table to be specified.  If there is no table, there is likely not
 	// anything attribute permissions needs to check.
-	if (!operationSchema || !table) {
+	// Nullish rather than falsy for the same reason as the map guard in verifyPerms: a table named `0`
+	// validates (`hdbTable` accepts a number), and skipping it here means its attribute permissions
+	// go unchecked.
+	if (operationSchema == undefined || table == undefined) {
 		return roleAttributePermissions;
 	}
 	try {

package/utility/watchPath.ts

@@ -0,0 +1,63 @@
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { loggerWithTag } from './logging/harper_logger.ts';
+
+const watchPathLogger = loggerWithTag('watcher');
+let canonicalizationWarned = false;
+
+/**
+ * Canonicalize an absolute path before it is handed to a native file watch (`fs.watch`, directly or
+ * through chokidar).
+ *
+ * libuv's Windows fs-event callback rebuilds each event's absolute path, expands it with
+ * `GetLongPathNameW`, and then asserts the expansion still starts with the directory it stored when
+ * the watch was armed. An 8.3 short directory (`C:\Users\RUNNER~1\...`) never survives that
+ * comparison, and the assertion aborts the process rather than failing the watch, so a short path
+ * reaching a native watch takes down the whole server (harper#2234).
+ *
+ * Every Windows path is resolved rather than only the ones that look short: `GetLongPathNameW`'s
+ * documentation is explicit that a short name need not contain a tilde, and NTFS allows an
+ * explicitly assigned one, so any spelling test would leave the abort reachable. `realpathSync` is
+ * not a substitute for the `.native` variant — it resolves symlinks but leaves 8.3 names intact.
+ *
+ * Returns `undefined` when the long form cannot be established, because a path we cannot prove is
+ * expanded is exactly the one that must never reach a native watch.
+ */
+export function canonicalizeWatchPath(watchPath: string, platform: string = process.platform): string | undefined {
+	if (platform !== 'win32') return watchPath;
+	try {
+		return realpathSync.native(watchPath);
+	} catch (error) {
+		if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'ENOENT') return undefined;
+		// libuv stores only the parent directory of a file target and compares only that prefix, so a
+		// leaf that does not exist yet — a config file whose watcher is armed during the install window
+		// — still yields a watch path that cannot trip the assertion.
+		try {
+			return join(realpathSync.native(dirname(watchPath)), basename(watchPath));
+		} catch {
+			return undefined;
+		}
+	}
+}
+
+/**
+ * Watch target for a chokidar/`fs.watch` call: the canonical path, or the original path with
+ * `mustPoll`, which callers turn into their polling options. Polling stats the file instead of
+ * arming a native watch, so it cannot reach the abort.
+ */
+export function resolveWatchTarget(watchPath: string): { path: string; mustPoll: boolean } {
+	const canonical = canonicalizeWatchPath(watchPath);
+	if (canonical !== undefined) return { path: canonical, mustPoll: false };
+	if (!canonicalizationWarned) {
+		canonicalizationWarned = true;
+		watchPathLogger.warn?.(
+			`Could not resolve the long-path form of ${watchPath}. Falling back to polling-based watching for ` +
+				'affected watchers, because handing a Windows 8.3 short path to a native watch aborts the process.'
+		);
+	}
+	return { path: watchPath, mustPoll: true };
+}
+
+export function _resetForTests(): void {
+	canonicalizationWarned = false;
+}

package/utility/watcherFallback.ts

@@ -5,6 +5,7 @@
 // events. Polling-based watching doesn't consume inotify handles or per-watcher
 // file descriptors, so we fall back to it once and warn — see harper#488.
 
+import chokidar, { type ChokidarOptions, type FSWatcher } from 'chokidar';
 import { loggerWithTag } from './logging/harper_logger.ts';
 
 // One-time process-wide warning so a thundering herd of failing watchers doesn't
@@ -71,4 +72,151 @@ export function warnWatcherFallback(watchedPath: string): void {
 // Test-only hook to reset the one-time warning gate between cases.
 export function _resetForTests(): void {
 	exhaustionWarned = false;
+	lostNativeWatchCount = 0;
+	lostNativeWatchWarnThreshold = 1;
+	// Also drop the process listener, so a case that installed the guard can't leave one
+	// attached to the test runner's process for every case that follows.
+	process.removeListener('uncaughtException', handleUncaughtException);
+	lostNativeWatchGuardInstalled = false;
+}
+
+// ---------------------------------------------------------------------------
+// Lost native watch (predominantly Windows)
+// ---------------------------------------------------------------------------
+//
+// Every Harper watcher runs `persistent: false`, which is the one chokidar
+// branch that never attaches an 'error' listener to the underlying Node
+// `fs.FSWatcher` (chokidar `handler.js`, `setFsWatchListener`; still so at
+// 5.0.0). Its `errHandler` covers only a synchronous throw out of `fs.watch()`
+// — the ENOSPC/EMFILE route above. An asynchronous failure is emitted on a
+// handle with no listener, so Node makes it an uncaughtException without it
+// ever reaching chokidar; `.on('error')` on the wrapper we hold cannot see it.
+// The process is therefore the only place it is observable, which is what
+// `installLostNativeWatchGuard()` uses.
+
+/**
+ * Returns `true` for the asynchronous "the watched path went away" error raised
+ * by Node's `fs.FSWatcher` — on Windows, `EPERM: operation not permitted, watch`
+ * (errno -4048) when a watched directory is removed or swapped out. Unlike
+ * {@link isWatcherExhaustionError} there is nothing to degrade to: polling a
+ * path that no longer exists only burns CPU.
+ *
+ * All three conditions are load-bearing, because whatever this claims is
+ * swallowed process-wide:
+ *
+ *   - `syscall === 'watch'` is only ever set by fs watch handles.
+ *   - `EPERM` only. An async `ENOENT` from a watch handle has never been
+ *     observed, whereas a *synchronous* one is the ordinary "watch a path that
+ *     isn't there" misconfiguration, which must stay fatal.
+ *   - no `path`. Node populates `path` on the error it throws out of
+ *     `fs.watch()` and leaves it absent on the one it delivers to the handle,
+ *     so without this a raw `fs.watch(missingPath)` reaching the guard would be
+ *     mistaken for a benign lost watch and swallowed.
+ */
+export function isLostNativeWatchError(error: unknown): boolean {
+	if (typeof error !== 'object' || error === null) return false;
+	const { code, syscall, path } = error as { code?: unknown; syscall?: unknown; path?: unknown };
+	return syscall === 'watch' && code === 'EPERM' && path == null;
+}
+
+let lostNativeWatchCount = 0;
+let lostNativeWatchWarnThreshold = 1;
+
+/**
+ * If `error` is a lost native watch error, mark it handled, log it, and report
+ * that it has been claimed. Exported so the per-watcher error routes can give it
+ * the same benign treatment on the day chokidar does deliver it to the wrapper
+ * (its polling and `persistent: true` branches already would).
+ */
+export function claimLostNativeWatchError(error: unknown): boolean {
+	if (!isLostNativeWatchError(error)) return false;
+	const claimed = error as { isHandled?: boolean };
+	// Counting one instance twice would trip the warn threshold early.
+	if (claimed.isHandled) return true;
+	lostNativeWatchCount++;
+	// The claim is the classification above; the bookkeeping that follows must not be able to
+	// undo it. A frozen error (`isHandled` unassignable) or a throwing logger would otherwise
+	// make a failure just classified as benign fatal — here, or in a caller's 'error' route.
+	try {
+		fallbackLogger.trace?.(`Lost native file watch handle (occurrence ${lostNativeWatchCount}):`, error);
+		// A subsystem that has silently stopped being watched is what an operator needs to see, and
+		// the default level is `warn`, so trace alone would hide every occurrence after the first.
+		// Warning at each decade keeps a delete storm bounded without ever going fully silent.
+		if (lostNativeWatchCount >= lostNativeWatchWarnThreshold) {
+			lostNativeWatchWarnThreshold *= 10;
+			fallbackLogger.warn?.(
+				`A native file watch handle failed asynchronously (EPERM, syscall=watch) and was suppressed to ` +
+					`keep the thread alive; occurrence ${lostNativeWatchCount}. Node reports no path for this error, ` +
+					`so it cannot be attributed to a specific watcher — whatever was watching that path has stopped ` +
+					`reporting changes until it is re-established. On Windows this is usually a watched directory ` +
+					`being deleted or replaced (a component redeploy, a package install, a test teardown). If file ` +
+					`changes stop being picked up somewhere, this is why. Subsequent occurrences log at trace, with ` +
+					`a warning at each tenfold increase.`
+			);
+		}
+		// Last: threadServer.js and socketRouter.ts skip errors already marked handled, so failing
+		// to mark one costs only a duplicate log line.
+		claimed.isHandled = true;
+	} catch {
+		// Marked or not, logged or not, the error stays claimed.
+	}
+	return true;
+}
+
+let lostNativeWatchGuardInstalled = false;
+
+function handleUncaughtException(error: unknown): void {
+	let claimed = false;
+	try {
+		claimed = claimLostNativeWatchError(error);
+	} catch {
+		// Classification is all that can still throw (a property getter that does), and a throw
+		// from inside an 'uncaughtException' listener would replace Node's report with it and
+		// exit 7. An error that cannot be classified is not ours to claim.
+		claimed = false;
+	}
+	if (claimed) return;
+	// Node suppresses its default fatal handling as soon as *any* 'uncaughtException' listener
+	// exists, so being the only listener would turn unrelated crashes into silent hangs.
+	if (process.listenerCount('uncaughtException') > 1) return;
+	process.removeListener('uncaughtException', handleUncaughtException);
+	// A process that somehow survives re-arms on its next guardedWatch() rather than running
+	// unguarded thereafter.
+	lostNativeWatchGuardInstalled = false;
+	// nextTick, not a throw from inside the handler: that keeps Node's report and exit code 1.
+	process.nextTick(() => {
+		throw error;
+	});
+}
+
+/**
+ * Idempotently install the process-level listener that supplies the 'error'
+ * handler chokidar omits for non-persistent watchers. Called by
+ * {@link guardedWatch} so no watcher call site can forget it.
+ */
+export function installLostNativeWatchGuard(): void {
+	if (lostNativeWatchGuardInstalled) return;
+	lostNativeWatchGuardInstalled = true;
+	// prepend, not append: threadServer.js already has an 'uncaughtException'
+	// listener, and the `isHandled` mark above only suppresses its log line if
+	// this guard runs first.
+	process.prependListener('uncaughtException', handleUncaughtException);
+}
+
+/**
+ * `chokidar.watch()` with the lost-native-watch guard installed. Every Harper
+ * chokidar watcher must go through this — a raw `chokidar.watch(..., { persistent: false })`
+ * can take down the thread the first time its path is deleted.
+ */
+export function guardedWatch(paths: string | string[], options?: ChokidarOptions): FSWatcher {
+	installLostNativeWatchGuard();
+	// Deliberately a property access on the default export rather than a named `watch` import:
+	// unitTests/server/threads/watchDirFallback.test.js drives the reopen-on-exhaustion chain by
+	// swapping `chokidar.default.watch`, and a named import binds past that seam.
+	return chokidar.watch(paths, options);
+}
+
+// Test-only: number of lost native watch errors claimed so far.
+export function _lostNativeWatchCountForTests(): number {
+	return lostNativeWatchCount;
 }