@harperfast/harper 5.2.10 → 5.3.0-alpha.1

package/security/deferredAuthentication.ts

@@ -0,0 +1,71 @@
+import { ClientError } from '../utility/errors/hdbError.ts';
+import { serializeMessage, findBestSerializer } from '../server/serverHelpers/contentTypes.ts';
+import { Headers } from '../server/serverHelpers/Headers.ts';
+
+export { isCredentialRejection, markCredentialRejection, credentialRejectionError } from './credentialRejection.ts';
+
+const DEFERRED_CREDENTIAL_REJECTION = Symbol('harper.deferredCredentialRejection');
+
+export type DeferredCredentialRejection = {
+	readonly status: number;
+	readonly message: string;
+	readonly strategy: string;
+};
+
+const CREDENTIAL_REJECTION_STATUS = 401;
+
+/**
+ * Records that this request presented a credential Harper rejected, without deciding the request.
+ * The caller leaves `request.user` unset and the inbound `Authorization` header untouched.
+ *
+ * The immutable, non-enumerable descriptor prevents downstream middleware from clearing it and
+ * keeps it out of request copies and serialization.
+ */
+export function deferCredentialRejection(request: any, error: { message?: string }, strategy: string): void {
+	if (getDeferredCredentialRejection(request)) return;
+	const deferred: DeferredCredentialRejection = Object.freeze({
+		status: CREDENTIAL_REJECTION_STATUS,
+		message: error?.message ?? 'Unauthorized',
+		strategy,
+	});
+	Object.defineProperty(request, DEFERRED_CREDENTIAL_REJECTION, {
+		value: deferred,
+		enumerable: false,
+		configurable: false,
+		writable: false,
+	});
+}
+
+export function getDeferredCredentialRejection(request: any): DeferredCredentialRejection | undefined {
+	return request?.[DEFERRED_CREDENTIAL_REJECTION];
+}
+
+/**
+ * The response an owning layer returns once it has established Harper owns the route: exactly the
+ * descriptor `security/auth.ts` returns in-line, so immediate and deferred rejection share a wire
+ * contract.
+ *
+ * Owner-specific error mapping must not run first. REST renders a thrown error as an RFC 9457
+ * Problem Details document and GraphQL as `{errors:[…]}` rather than authentication's negotiated
+ * `{error: message}` response. `security/auth.ts` likewise leaves a settled rejection's status and
+ * challenge headers alone, so it stays byte-identical to the in-line 401 it replaced.
+ *
+ * Returns `undefined` when nothing was deferred, so a caller can `return settled ?? …` inline.
+ */
+export function settleDeferredCredentialRejection(
+	request: any
+): { status: number; headers: Headers; body: string | Buffer } | undefined {
+	const deferred = getDeferredCredentialRejection(request);
+	if (!deferred) return undefined;
+	const contentType = (request?.headers ? findBestSerializer(request).type : undefined) ?? 'application/json';
+	return {
+		status: deferred.status,
+		headers: new Headers({ 'Content-Type': contentType }),
+		body: serializeMessage({ error: deferred.message }, request) as string | Buffer,
+	};
+}
+
+export function assertNoDeferredCredentialRejection(request: any): void {
+	const deferred = getDeferredCredentialRejection(request);
+	if (deferred) throw new ClientError(deferred.message, deferred.status);
+}

package/security/impersonation.ts

@@ -1,10 +1,46 @@
-import type { User } from './user.ts';
+import { createHash } from 'node:crypto';
+import type { User, UserRole } from './user.ts';
 import type { ImpersonatePayload } from '../server/operationsServer.ts';
 import { getUsersWithRolesCache } from './user.ts';
 import { validateOperations } from '../utility/operationPermissions.ts';
+import { addRoleValidation } from '../validation/role_validation.ts';
 import { ClientError } from '../utility/errors/hdbError.ts';
 import harperLogger from '../utility/logging/harper_logger.ts';
 import { getRoleByName } from './role.ts';
+import { attachScopeToUser } from './operationScope.ts';
+import { attachWorkloadIdentityToUser } from './credentialProvenance.ts';
+
+/**
+ * Content-derived identity for synthetic (inline) roles. getRolePermissions memoizes translated
+ * permissions by role name, so synthetic roles must never share a constant name: two inline roles
+ * with different permissions would alias in that cache and leak permissions across principals.
+ * Hashing the (already downgraded) permission content isolates distinct permission sets while
+ * letting identical ones share a cache entry. The paired __updatedtime__ of 0 keeps the memo key
+ * stable across requests; the content hash in the name is what invalidates on permission change.
+ *
+ * Object keys are canonicalized before hashing so two structurally-identical permission sets that
+ * differ only in key order (e.g. from different client request shapes) map to the same name and
+ * share one cache slot — otherwise they would each consume a distinct slot (never an aliasing bug,
+ * but it worsens the bounded synthetic-role cache pressure).
+ */
+export function syntheticRoleName(prefix: string, permission: object): string {
+	return `${prefix}_${createHash('sha256').update(canonicalJSON(permission)).digest('hex').slice(0, 24)}`;
+}
+
+// Array order is intentionally preserved: operations is order-insensitive semantically, but
+// canonicalizing it too would be a broader behavior change than this cache-sharing fix needs.
+function canonicalJSON(value: any): string {
+	return JSON.stringify(value, (_key, v) =>
+		v && typeof v === 'object' && !Array.isArray(v)
+			? Object.keys(v)
+					.sort()
+					.reduce((acc: any, k) => {
+						acc[k] = v[k];
+						return acc;
+					}, {})
+			: v
+	);
+}
 
 /**
  * Applies impersonation to a request. The authenticated user must be a super_user.
@@ -38,6 +74,26 @@ export async function applyImpersonation(authenticatedUser: User, payload: Imper
 	// Enforce downgrade: never allow escalation
 	enforceDowngrade(impersonatedUser);
 
+	// A token's operation scope (#2174) constrains the credential regardless of which principal it
+	// acts as, so it survives impersonation. enforceDowngrade only bounds the impersonated role's
+	// permissions; without carrying the scope, a scoped super_user token would shed it by impersonating.
+	attachScopeToUser(impersonatedUser, (authenticatedUser as any).tokenOperations);
+	// Same reasoning for provenance (#2171), and the omission would be worse: impersonation returns a
+	// NEW principal, so dropping the marker here would let a workload token impersonate — even down to
+	// a lesser role — and then mint a 30-day credential that createTokens would no longer refuse.
+	attachWorkloadIdentityToUser(impersonatedUser, (authenticatedUser as any).fromWorkloadIdentity);
+
+	// Re-key the synthetic role by its effective (post-downgrade) content so it can never alias
+	// another impersonation's permissions or poison a persisted role's memoized translation —
+	// getRolePermissions caches by role name (see syntheticRoleName).
+	if (impersonatedUser.role) {
+		impersonatedUser.role = {
+			...impersonatedUser.role,
+			role: syntheticRoleName('_impersonated', impersonatedUser.role.permission),
+			__updatedtime__: 0,
+		};
+	}
+
 	// Tag for audit trail
 	impersonatedUser._impersonated = true;
 	impersonatedUser._impersonatedBy = authenticatedUser.username;
@@ -49,9 +105,60 @@ export async function applyImpersonation(authenticatedUser: User, payload: Imper
 	return impersonatedUser;
 }
 
-function validatePayload(payload: ImpersonatePayload): void {
+/**
+ * Builds the synthetic user embedded in a scoped authentication token
+ * (create_authentication_tokens with an inline `role` object). Same gate and downgrade rules as
+ * impersonation Mode A. `trusted` marks internal dispatch (operation authorization bypassed),
+ * where no authenticated minter exists.
+ */
+export async function buildScopedTokenUser(
+	minter: User | undefined,
+	payload: ImpersonatePayload,
+	trusted = false
+): Promise<User> {
+	if (!trusted && !minter?.role?.permission?.super_user) {
+		throw new ClientError('Only super_user can create a token with an inline role', 403);
+	}
+	validatePayload(payload, 'scoped token role');
+	if (!payload.role) {
+		throw new ClientError("A scoped token requires 'role' with 'permission'");
+	}
+	const username = payload.username || (minter?.username && `scoped:${minter.username}`);
+	if (!username || typeof username !== 'string') {
+		throw new ClientError("A scoped token requires a 'username'");
+	}
+	// The attribution name must never collide with a real principal: paths that rehydrate a user
+	// by name (e.g. MQTT last-will replay) would resolve the token's bearer to that user's full
+	// permissions. This also keeps scoped-token activity distinguishable in audit logs.
+	if ((await getUsersWithRolesCache())?.has(username)) {
+		throw new ClientError(`'username' must not name an existing user; scoped-token attribution is a label`);
+	}
+	// Downgrade first so validation and the content hash see the effective permission set.
+	const permission = {
+		...payload.role.permission,
+		super_user: false,
+		cluster_user: false,
+	} as UserRole['permission'];
+	// Full persisted-role validation: a malformed shape must fail at mint (400), not at every use.
+	const deepValidation = addRoleValidation({ role: 'scoped_token', permission });
+	if (deepValidation) throw deepValidation;
+	const roleName = syntheticRoleName('_scoped_token', permission);
+	return {
+		username,
+		active: true,
+		role: {
+			permission,
+			role: roleName,
+			id: roleName,
+			__updatedtime__: 0,
+			__createdtime__: 0,
+		},
+	};
+}
+
+function validatePayload(payload: ImpersonatePayload, context = 'impersonate payload'): void {
 	if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
-		throw new ClientError('Invalid impersonate payload: must be an object');
+		throw new ClientError(`Invalid ${context}: must be an object`);
 	}
 
 	const hasRole = payload.role !== undefined;
@@ -59,33 +166,31 @@ function validatePayload(payload: ImpersonatePayload): void {
 	const hasRoleName = typeof payload.role_name === 'string' && payload.role_name.length > 0;
 
 	if (!hasRole && !hasUsername && !hasRoleName) {
-		throw new ClientError(
-			"Invalid impersonate payload: must include 'username', 'role_name', or 'role' with 'permission'"
-		);
+		throw new ClientError(`Invalid ${context}: must include 'username', 'role_name', or 'role' with 'permission'`);
 	}
 
 	if (hasRole) {
 		if (typeof payload.role !== 'object' || payload.role === null) {
-			throw new ClientError("Invalid impersonate payload: 'role' must be an object");
+			throw new ClientError(`Invalid ${context}: 'role' must be an object`);
 		}
 		if (typeof payload.role.permission !== 'object' || payload.role.permission === null) {
-			throw new ClientError("Invalid impersonate payload: 'role.permission' must be an object");
+			throw new ClientError(`Invalid ${context}: 'role.permission' must be an object`);
 		}
-		validateOperationsField(payload.role.permission);
+		validateOperationsField(payload.role.permission, context);
 	}
 }
 
-function validateOperationsField(permission: Record<string, unknown>): void {
+function validateOperationsField(permission: Record<string, unknown>, context = 'impersonate payload'): void {
 	const operations = permission.operations;
 	if (operations === undefined) return;
 
 	if (!Array.isArray(operations)) {
-		throw new ClientError("Invalid impersonate payload: 'operations' must be an array");
+		throw new ClientError(`Invalid ${context}: 'operations' must be an array`);
 	}
 
 	const invalidOp = validateOperations(operations);
 	if (invalidOp !== null) {
-		throw new ClientError(`Invalid impersonate payload: unknown operation '${invalidOp}'`);
+		throw new ClientError(`Invalid ${context}: unknown operation '${invalidOp}'`);
 	}
 }
 

package/security/jsLoader.ts

@@ -1,9 +1,9 @@
 import { Resource } from '../resources/Resource.ts';
 import { contextStorage, transaction } from '../resources/transaction.ts';
 import { RequestTarget } from '../resources/RequestTarget.ts';
-import { tables, databases } from '../resources/databases.ts';
+import { tables, databases, scopedTableFactory } from '../resources/databases.ts';
 import { models as harperModelsSingleton } from '../resources/models/Models.ts';
-import { defineTable, types } from '../resources/defineTable.ts';
+import { defineTable, defineTableUsing, types } from '../resources/defineTable.ts';
 import { defineResource, t, schemaOf, projectTableFragment } from '../resources/defineResource.ts';
 import { readFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
@@ -15,10 +15,12 @@ import logger from '../utility/logging/harper_logger.ts';
 import { createRequire } from 'node:module';
 import * as env from '../utility/environment/environmentManager';
 import * as child_process from 'node:child_process';
-import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
+import { CONFIG_PARAMS, DEFAULT_DATABASE_NAME } from '../utility/hdbTerms.ts';
+
 import { contentTypes } from '../server/serverHelpers/contentTypes.ts';
 import type {} from 'ses';
 import {
+	existsSync,
 	mkdirSync,
 	readFileSync,
 	writeFileSync,
@@ -174,13 +176,13 @@ function walkExportsConditions(entry: unknown, conditions: readonly string[]): s
 
 /**
  * Resolve a bare package specifier to a file:// URL using the package's exports map
- * with ESM import conditions. Used as a fallback when createRequire().resolve() throws
- * ERR_PACKAGE_PATH_NOT_EXPORTED for pure-ESM packages (exports map with only "import"
- * conditions and no "require").
+ * with ESM import conditions. Used as a fallback when the runtime's CommonJS resolver
+ * cannot match a pure-ESM package (exports map with only "import" conditions).
  */
 function resolveESMPackageExports(
 	specifier: string,
-	fromDir: string
+	fromDir: string,
+	preferRequireConditions = false
 ): { resolvedUrl: string; packageJsonUrl: string; packageJsonSource: Buffer } | null {
 	const isScoped = specifier.startsWith('@');
 	const parts = specifier.split('/');
@@ -223,11 +225,23 @@ function resolveESMPackageExports(
 
 		if (!entry) return null;
 
-		const relative = walkExportsConditions(entry, ['import', 'node', 'default']);
+		const relative = preferRequireConditions
+			? (walkExportsConditions(entry, ['bun', 'require', 'node', 'default']) ??
+				walkExportsConditions(entry, ['bun', 'import', 'node', 'default']))
+			: walkExportsConditions(entry, ['import', 'node', 'default']);
 		if (!relative) return null;
 
+		let resolvedPath = join(pkgRoot, relative);
+		if (preferRequireConditions && !existsSync(resolvedPath)) {
+			// The runtime's preferred condition (Bun's `require`) named a target that isn't
+			// actually on disk -- fall back to the plain ESM `import` condition instead of
+			// failing resolution outright.
+			const importRelative = walkExportsConditions(entry, ['import', 'node', 'default']);
+			if (importRelative) resolvedPath = join(pkgRoot, importRelative);
+		}
+
 		return {
-			resolvedUrl: pathToFileURL(realpathSync(join(pkgRoot, relative))).toString(),
+			resolvedUrl: pathToFileURL(realpathSync(resolvedPath)).toString(),
 			packageJsonUrl: pathToFileURL(realpathSync(packageJsonPath)).toString(),
 			packageJsonSource,
 		};
@@ -325,9 +339,10 @@ async function loadModuleWithVM(moduleUrl: string, scope: ApplicationScope, useC
 				const referrerDir = resolveReferrer.startsWith('file:')
 					? dirname(fileURLToPath(resolveReferrer))
 					: dirname(resolveReferrer);
-				const esmResolved = resolveESMPackageExports(specifier, referrerDir);
+				const esmResolved = resolveESMPackageExports(specifier, referrerDir, (err as any)?.code === 'MODULE_NOT_FOUND');
 				if (esmResolved) {
 					scope.recordLoadedModule?.(esmResolved.packageJsonUrl, esmResolved.packageJsonSource);
+					scope.recordLoadedModule?.(esmResolved.resolvedUrl, readFileSync(new URL(esmResolved.resolvedUrl)));
 					return esmResolved.resolvedUrl;
 				}
 			}
@@ -849,6 +864,52 @@ function getGlobalObject(scope: ApplicationScope, copyIntrinsics = false) {
 // `Resource`/`tables`/`databases`/`createBlob`/… below are the live, process-wide singletons (the
 // same values surfaced as the top-level package exports and bare globals), not per-compartment
 // copies — only `server`/`logger`/`resources`/`config` are scope-overridable.
+/**
+ * The `databases`/`tables` a scope sees. An application that declared `branchedDatabases` gets a view
+ * in which those names resolve to its private graph and everything else falls through to the real
+ * map, live: `databases` gains entries at runtime (`ensureDB`), so a copy taken at load would
+ * silently stop showing databases created afterwards.
+ *
+ * An unbranched scope gets the process-wide singletons **by identity**, not a view: that is the
+ * overwhelmingly common case and it must stay indistinguishable from before, and it means only
+ * branched applications pay for the indirection. Proxying rather than copying also keeps
+ * `databases.system` — deliberately non-enumerable (`resources/databases.ts`) — reachable for free.
+ */
+function scopedDatabaseBindings(scope: ApplicationScope): { databases: any; tables: any } {
+	const branches = scope.branches;
+	if (!branches?.size) return { databases, tables };
+	// Every branched name already exists on the target as a writable, configurable property (a branch
+	// is only ever taken of a database that exists), so overriding it here breaks no Proxy invariant.
+	const scoped = new Proxy(databases, {
+		get: (target, key, receiver) =>
+			typeof key === 'string' && branches.has(key) ? branches.get(key)!.tables : Reflect.get(target, key, receiver),
+		getOwnPropertyDescriptor(target, key) {
+			if (typeof key !== 'string' || !branches.has(key)) return Reflect.getOwnPropertyDescriptor(target, key);
+			return { value: branches.get(key)!.tables, writable: true, enumerable: true, configurable: true };
+		},
+	});
+	// `tables` is the flat alias for the default database, so it follows that database's branch.
+	return { databases: scoped, tables: branches.get(DEFAULT_DATABASE_NAME)?.tables ?? tables };
+}
+
+/**
+ * `defineTable` for a branched application registers through that application's table factory, so
+ * a branched name lands in its branch; an unbranched application gets `defineTable` itself.
+ */
+function scopedDefineTable(scope: ApplicationScope): typeof defineTable {
+	const branches = scope.branches;
+	if (!branches?.size) return defineTable;
+	const declareTable = scopedTableFactory(branches);
+	return function (name: string, shape: any, options?: any) {
+		return defineTableUsing(declareTable, name, shape, options);
+	} as typeof defineTable;
+}
+
+/** Everything an application sees differently because of what it declared. Built once, at load. */
+export function scopedBindings(scope: ApplicationScope): { databases: any; tables: any; defineTable: any } {
+	return { ...scopedDatabaseBindings(scope), defineTable: scopedDefineTable(scope) };
+}
+
 function getHarperExports(scope: ApplicationScope) {
 	return {
 		server: scope.server ?? server,
@@ -859,9 +920,7 @@ function getHarperExports(scope: ApplicationScope) {
 		// the process-wide singletons below.
 		secrets: getSecretsForComponent(scope.name),
 		Resource,
-		tables,
-		databases,
-		defineTable,
+		...scopedBindings(scope),
 		types,
 		defineResource,
 		t,
@@ -914,7 +973,6 @@ const ALLOWED_NODE_BUILTIN_MODULES = env.get(CONFIG_PARAMS.APPLICATIONS_ALLOWEDB
 				return true;
 			},
 		};
-const ALLOWED_COMMANDS = new Set(env.get(CONFIG_PARAMS.APPLICATIONS_ALLOWEDSPAWNCOMMANDS) ?? []);
 const child_processConstrained: any = {
 	exec: createSpawn(child_process.exec),
 	execFile: createSpawn(child_process.execFile),
@@ -1070,10 +1128,15 @@ function acquirePidFileLock(
 }
 
 function createSpawn(spawnFunction: (...args: any) => child_process.ChildProcess, alwaysAllow?: boolean) {
-	const basePath = env.getHdbBasePath();
 	return function (command: string, args?: any, options?: any, callback?: (...args: any[]) => void) {
-		if (!ALLOWED_COMMANDS.has(command.split(' ')[0]) && !alwaysAllow) {
-			throw new Error(`Command ${command} is not allowed`);
+		// componentLoader imports this module, so it can load before the config is resolved; a value
+		// captured out here would pin an empty allowlist, and an undefined base path, for the life of
+		// the process. Anything but a configured list denies.
+		if (!alwaysAllow) {
+			const allowedCommands = env.get(CONFIG_PARAMS.APPLICATIONS_ALLOWEDSPAWNCOMMANDS);
+			if (!Array.isArray(allowedCommands) || !allowedCommands.includes(command.split(' ')[0])) {
+				throw new Error(`Command ${command} is not allowed`);
+			}
 		}
 		const processName = options?.name;
 		if (!processName)
@@ -1083,7 +1146,7 @@ function createSpawn(spawnFunction: (...args: any) => child_process.ChildProcess
 		const requestedVersion = options?.version;
 
 		// Ensure PID directory exists
-		const pidDir = join(basePath, 'pids');
+		const pidDir = join(env.getHdbBasePath(), 'pids');
 		mkdirSync(pidDir, { recursive: true });
 
 		const pidFilePath = join(pidDir, `${processName}.pid`);