@happyvertical/smrt-app-runtime 0.43.10 → 0.44.1

package/AGENTS.md

@@ -5,6 +5,9 @@ Application infrastructure composition for the validated runtime profiles in
 
 ## Local profile
 
+- `validateApplicationId()` is the canonical strict validator for explicit app
+  IDs. `encodeApplicationId()` derives a length-bounded, collision-resistant
+  ID from package names; generated operational surfaces must share these APIs.
 - `initializeLocalApplicationRuntime()` owns user data paths, SQLite tuning,
   local application-secret creation, and the single-use owner bootstrap flow.
 - SQLite is acquired through `@happyvertical/sql`'s explicit
@@ -12,6 +15,13 @@ Application infrastructure composition for the validated runtime profiles in
   runtime establishes its user-owned mode-0700 data root.
 - Application migrations are explicit through `prepareDatabase`; runtime never
   creates application model tables implicitly.
+- Standalone migration commands must call `prepareLocalDatabaseStorage()`
+  before opening SQLite so custody is established without creating schema or
+  bootstrap records.
+- Read-only/copy/import operator commands must call
+  `validateLocalDatabaseStorage()` before opening SQLite; it verifies the
+  app-bound marker, source separation, real path chain, ownership, and mode
+  without creating or repairing storage.
 - Owner bootstrap creates normal `Person`, `User`, `Tenant`, owner `Role` /
   `Membership`, and `Session` records in one transaction.
 - Bootstrap is loopback-only. Only an HMAC of the short-lived token is stored.
@@ -47,6 +57,22 @@ Application infrastructure composition for the validated runtime profiles in
 - Cloud must keep required tenant context and must never introduce a root or
   unscoped tenant fallback. RLS remains an explicit deployment/migration choice.
 
+## Public runtime diagnostics
+
+- `projectRuntimeDiagnostics()` is the only public diagnostic projection. It
+  constructs the schema-version-1 allowlist and never serializes the private
+  local or deployed diagnostics objects.
+- The allowlist is limited to active profile/coarse health, schema and
+  migration readiness, six fixed capability statuses, a sorted/capped public
+  tool inventory plus digest, explicit operational topology differences,
+  coarse worker heartbeat state, and eight stable code/timestamp errors.
+- Callers supply an explicit clock and worker-heartbeat seam. A missing
+  heartbeat is `unknown`; web-process liveness never proves worker liveness.
+- Error ingestion maps unknown codes to `runtime_error`, truncates timestamps
+  to the minute, and ignores messages, stacks, logs, records, and nested state.
+- Authentication and diagnostics-read authorization belong before every call
+  to the projector or its runtime probes.
+
 ## Invariants
 
 - Never expose application-secret bytes or bootstrap token hashes in diagnostics.

package/dist/index.d.ts

@@ -11,6 +11,12 @@ import { SessionService } from '@happyvertical/smrt-users';
 import { TaskRunner } from '@happyvertical/smrt-jobs';
 import { TaskRunnerConfig } from '@happyvertical/smrt-jobs';
 
+declare const CAPABILITY_IDS: readonly ["asset-storage", "authentication", "background-jobs", "database", "paid-capabilities", "secret-storage"];
+
+declare type CapabilityId = (typeof CAPABILITY_IDS)[number];
+
+declare type CapabilityStatus = 'available' | 'disabled' | 'unavailable' | 'unknown';
+
 export declare interface ClaimLocalOwnerInput {
     token: string;
     name: string;
@@ -136,6 +142,11 @@ export declare interface DeployedRuntimeReadiness {
     readonly secretValuesIncluded: false;
 }
 
+/** Encode a package/project identity into a collision-resistant runtime ID. */
+export declare function encodeApplicationId(value: string): string;
+
+declare const ERROR_CODES: readonly ["authentication_unavailable", "database_unavailable", "migration_required", "provider_unavailable", "runtime_stopped", "worker_stale"];
+
 /**
  * Initialize a self-hosted or cloud application composition.
  *
@@ -263,6 +274,23 @@ export declare interface LocalRuntimePaths {
     readonly applicationSecret: string;
 }
 
+export declare const MAX_RUNTIME_DIAGNOSTIC_ERRORS = 8;
+
+export declare const MAX_RUNTIME_DIAGNOSTIC_TOOLS = 64;
+
+/**
+ * Claim the secure local database root before a standalone migration command
+ * opens SQLite. This does not create application schema or bootstrap records.
+ */
+export declare function prepareLocalDatabaseStorage(options: ResolveLocalRuntimePathsOptions): Promise<LocalRuntimePaths>;
+
+/**
+ * Project private local/deployed state into the deterministic public contract.
+ * Unknown, oversized, nested, accessor-backed, or prohibited values are never
+ * copied. Invalid error codes become `runtime_error` at ingestion.
+ */
+export declare function projectRuntimeDiagnostics(input: RuntimeDiagnosticsProjectionInput): RuntimeDiagnostics;
+
 export declare type PublicAuthenticationProvider = Exclude<AuthenticationProvider, 'owner-bootstrap'>;
 
 /**
@@ -285,4 +313,72 @@ export declare interface ResolveLocalRuntimePathsOptions {
     env?: NodeJS.ProcessEnv;
 }
 
+export declare const RUNTIME_DIAGNOSTICS_SCHEMA_VERSION: 1;
+
+export declare const RUNTIME_WORKER_FRESHNESS_SECONDS = 120;
+
+declare type RuntimeDiagnosticErrorCode = (typeof ERROR_CODES)[number] | 'runtime_error';
+
+/**
+ * Versioned public diagnostics returned only after application authorization.
+ * Every field is a fixed allowlist projection; this is intentionally not a
+ * cleaned or serialized form of either private runtime diagnostics object.
+ */
+export declare interface RuntimeDiagnostics {
+    readonly schemaVersion: 1;
+    readonly profile: ApplicationRuntimeProfile | 'unknown';
+    readonly health: 'healthy' | 'degraded' | 'stopped' | 'unknown';
+    readonly schema: {
+        readonly status: 'ready' | 'not-ready' | 'unknown';
+        readonly migrations: 'current' | 'failed' | 'pending' | 'unknown';
+    };
+    readonly capabilities: readonly {
+        readonly id: CapabilityId;
+        readonly status: CapabilityStatus;
+    }[];
+    readonly tools: {
+        readonly names: readonly string[];
+        readonly count: number;
+        readonly digest: string;
+    };
+    readonly operationalDifferences: {
+        readonly backgroundJobs: 'disabled' | 'enabled';
+        readonly workerTopology: WorkerTopology;
+    };
+    readonly worker: {
+        readonly topology: WorkerTopology;
+        readonly liveness: 'alive' | 'not-required' | 'stale' | 'unknown';
+        readonly heartbeatAt: string | null;
+        readonly observedAt: string;
+    };
+    readonly recentErrors: readonly {
+        readonly code: RuntimeDiagnosticErrorCode;
+        readonly at: string;
+    }[];
+}
+
+export declare interface RuntimeDiagnosticsProjectionInput {
+    readonly profile?: unknown;
+    readonly health?: unknown;
+    readonly schema?: unknown;
+    readonly capabilities?: unknown;
+    readonly toolNames?: unknown;
+    readonly worker?: unknown;
+    readonly recentErrors?: unknown;
+    /** Required explicit clock seam; the projector never reads the process clock. */
+    readonly observedAt?: unknown;
+}
+
+/** Validate an explicit runtime identity. */
+export declare function validateApplicationId(value: string): string;
+
+/**
+ * Verify an already-initialized local database root without creating or
+ * changing any filesystem/database artifact. Operator read/copy/import paths
+ * use this boundary before opening SQLite outside the runtime bootstrap.
+ */
+export declare function validateLocalDatabaseStorage(options: ResolveLocalRuntimePathsOptions): Promise<LocalRuntimePaths>;
+
+declare type WorkerTopology = 'embedded' | 'external' | 'inline' | 'scalable';
+
 export { }

package/dist/index.js

@@ -505,7 +505,7 @@ function createDiagnostics(runtime) {
 		provider: value,
 		configured: true
 	});
-	return deepFreeze({
+	return deepFreeze$1({
 		schemaVersion: 1,
 		runtime,
 		providers: {
@@ -547,7 +547,7 @@ function createStoppedReadiness(profile) {
 	}, false);
 }
 function freezeReadiness(profile, components, ready) {
-	return deepFreeze({
+	return deepFreeze$1({
 		schemaVersion: 1,
 		profile,
 		status: ready ? "ready" : "not-ready",
@@ -581,12 +581,247 @@ async function cleanupAfterStartupFailure(binding, db, startupError) {
 	}
 	throw startupError;
 }
-function deepFreeze(value, seen = /* @__PURE__ */ new WeakSet()) {
+function deepFreeze$1(value, seen = /* @__PURE__ */ new WeakSet()) {
 	if (value && typeof value === "object") {
 		if (seen.has(value)) return value;
 		seen.add(value);
 		if (!Object.isFrozen(value)) Object.freeze(value);
-		for (const child of Object.values(value)) deepFreeze(child, seen);
+		for (const child of Object.values(value)) deepFreeze$1(child, seen);
+	}
+	return value;
+}
+//#endregion
+//#region src/runtime-diagnostics.ts
+var RUNTIME_DIAGNOSTICS_SCHEMA_VERSION = 1;
+var MAX_RUNTIME_DIAGNOSTIC_TOOLS = 64;
+var MAX_RUNTIME_DIAGNOSTIC_ERRORS = 8;
+var RUNTIME_WORKER_FRESHNESS_SECONDS = 120;
+var CAPABILITY_IDS = [
+	"asset-storage",
+	"authentication",
+	"background-jobs",
+	"database",
+	"paid-capabilities",
+	"secret-storage"
+];
+var ERROR_CODES = [
+	"authentication_unavailable",
+	"database_unavailable",
+	"migration_required",
+	"provider_unavailable",
+	"runtime_stopped",
+	"worker_stale"
+];
+var PROHIBITED_IDENTIFIER_PARTS = /* @__PURE__ */ new Set([
+	"authorization",
+	"cookie",
+	"constructor",
+	"credential",
+	"email",
+	"hash",
+	"key",
+	"log",
+	"logs",
+	"password",
+	"path",
+	"record",
+	"prototype",
+	"secret",
+	"session",
+	"stack",
+	"tenant",
+	"token",
+	"url",
+	"user"
+]);
+function projectRuntimeDiagnostics(input) {
+	const source = plainRecord(input);
+	const observedAtValue = read(source, "observedAt");
+	const observedAtMilliseconds = timestampMilliseconds(observedAtValue);
+	const observedAt = coarseTimestamp(observedAtValue) ?? EPOCH;
+	const profile = runtimeProfile(read(source, "profile"));
+	const worker = projectWorker(read(source, "worker"), observedAt, observedAtMilliseconds);
+	const capabilities = projectCapabilities(read(source, "capabilities"));
+	const tools = canonicalTools(read(source, "toolNames"));
+	return deepFreeze({
+		schemaVersion: 1,
+		profile,
+		health: oneOf(read(source, "health"), HEALTH_VALUES, "unknown"),
+		schema: projectSchema(read(source, "schema")),
+		capabilities,
+		tools: {
+			names: tools,
+			count: tools.length,
+			digest: createHash("sha256").update(tools.join("\n")).digest("hex")
+		},
+		operationalDifferences: {
+			backgroundJobs: capabilityStatus(capabilities, "background-jobs") === "available" ? "enabled" : "disabled",
+			workerTopology: worker.topology
+		},
+		worker,
+		recentErrors: projectErrors(read(source, "recentErrors"))
+	});
+}
+var EPOCH = "1970-01-01T00:00:00.000Z";
+var PROFILES = [
+	"local",
+	"self-hosted",
+	"cloud",
+	"unknown"
+];
+var HEALTH_VALUES = [
+	"healthy",
+	"degraded",
+	"stopped",
+	"unknown"
+];
+var SCHEMA_VALUES = [
+	"ready",
+	"not-ready",
+	"unknown"
+];
+var MIGRATION_VALUES = [
+	"current",
+	"failed",
+	"pending",
+	"unknown"
+];
+var CAPABILITY_VALUES = [
+	"available",
+	"disabled",
+	"unavailable",
+	"unknown"
+];
+var WORKER_TOPOLOGIES = [
+	"embedded",
+	"external",
+	"inline",
+	"scalable"
+];
+function runtimeProfile(value) {
+	return oneOf(value, PROFILES, "unknown");
+}
+function projectSchema(value) {
+	const source = plainRecord(value);
+	return {
+		status: oneOf(read(source, "status"), SCHEMA_VALUES, "unknown"),
+		migrations: oneOf(read(source, "migrations"), MIGRATION_VALUES, "unknown")
+	};
+}
+function projectCapabilities(value) {
+	const source = plainRecord(value);
+	return CAPABILITY_IDS.map((id) => ({
+		id,
+		status: oneOf(read(source, id), CAPABILITY_VALUES, "unknown")
+	}));
+}
+function canonicalTools(value) {
+	const names = /* @__PURE__ */ new Set();
+	for (const candidate of safeArrayItems(value, 256)) {
+		if (typeof candidate !== "string" || !isPublicIdentifier(candidate)) continue;
+		names.add(candidate);
+	}
+	return [...names].sort().slice(0, 64);
+}
+function isPublicIdentifier(value) {
+	if (value.length < 1 || value.length > 80 || !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(value)) return false;
+	return !value.split(/[._-]/).some((part) => PROHIBITED_IDENTIFIER_PARTS.has(part));
+}
+function projectWorker(value, observedAt, observedAtMilliseconds) {
+	const source = plainRecord(value);
+	const topology = oneOf(read(source, "topology"), WORKER_TOPOLOGIES, "inline");
+	const required = read(source, "required") === true;
+	const heartbeatValue = read(source, "heartbeatAt");
+	const heartbeatMilliseconds = timestampMilliseconds(heartbeatValue);
+	const heartbeatAt = coarseTimestamp(heartbeatValue);
+	let liveness = "not-required";
+	if (required) {
+		liveness = "unknown";
+		if (heartbeatMilliseconds !== null && observedAtMilliseconds !== null) {
+			const ageSeconds = (observedAtMilliseconds - heartbeatMilliseconds) / 1e3;
+			if (ageSeconds >= 0) liveness = ageSeconds <= 120 ? "alive" : "stale";
+		}
+	}
+	return {
+		topology,
+		liveness,
+		heartbeatAt,
+		observedAt
+	};
+}
+function projectErrors(value) {
+	const errors = [];
+	for (const candidate of safeArrayItems(value, 32)) {
+		const source = plainRecord(candidate);
+		const at = coarseTimestamp(read(source, "at"));
+		if (!at) continue;
+		const rawCode = read(source, "code");
+		const code = ERROR_CODES.includes(rawCode) ? rawCode : "runtime_error";
+		errors.push({
+			code,
+			at
+		});
+	}
+	return errors.sort((left, right) => left.at === right.at ? left.code.localeCompare(right.code) : right.at.localeCompare(left.at)).slice(0, 8);
+}
+function capabilityStatus(capabilities, id) {
+	return capabilities.find((capability) => capability.id === id)?.status ?? "unknown";
+}
+function coarseTimestamp(value) {
+	const milliseconds = timestampMilliseconds(value);
+	if (milliseconds === null) return null;
+	const minute = Math.floor(milliseconds / 6e4) * 6e4;
+	return new Date(minute).toISOString();
+}
+function timestampMilliseconds(value) {
+	try {
+		if (!(typeof value === "string" || value instanceof Date)) return null;
+		const milliseconds = value instanceof Date ? value.getTime() : Date.parse(value);
+		return Number.isFinite(milliseconds) ? milliseconds : null;
+	} catch {
+		return null;
+	}
+}
+function oneOf(value, values, fallback) {
+	return typeof value === "string" && values.includes(value) ? value : fallback;
+}
+function plainRecord(value) {
+	try {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+		const prototype = Object.getPrototypeOf(value);
+		return prototype === Object.prototype || prototype === null ? value : null;
+	} catch {
+		return null;
+	}
+}
+function read(source, key) {
+	try {
+		if (!source || !Object.hasOwn(source, key)) return;
+		return source[key];
+	} catch {
+		return;
+	}
+}
+function safeArrayItems(value, maximum) {
+	try {
+		if (!Array.isArray(value)) return [];
+		const length = Math.min(value.length, maximum);
+		if (!Number.isSafeInteger(length) || length < 0) return [];
+		const items = [];
+		for (let index = 0; index < length; index += 1) try {
+			items.push(value[index]);
+		} catch {
+			items.push(void 0);
+		}
+		return items;
+	} catch {
+		return [];
+	}
+}
+function deepFreeze(value) {
+	if (value && typeof value === "object") {
+		Object.freeze(value);
+		for (const child of Object.values(value)) if (child && typeof child === "object" && !Object.isFrozen(child)) deepFreeze(child);
 	}
 	return value;
 }
@@ -645,6 +880,44 @@ var INITIALIZATION_LOCK_WORKER = `
   });
 `;
 var execFileAsync = promisify(execFile);
+async function prepareLocalDatabaseStorage(options) {
+	const paths = resolveLocalRuntimePaths(options);
+	const sourceRoot = resolve(options.sourceRoot ?? process.cwd());
+	const appId = validateApplicationId(options.appId);
+	await preflightLocalApplicationRoot(paths.root, sourceRoot, appId);
+	const initializationLock = await acquireInitializationLock(paths.root);
+	let db;
+	let failure;
+	try {
+		await preflightLocalApplicationRoot(paths.root, sourceRoot, appId);
+		db = (await acquireLocalDatabase(paths, sourceRoot, appId)).db;
+		await db.close?.();
+		db = void 0;
+	} catch (error) {
+		failure = db ? await closeDatabaseAfterFailure(db, error) : error;
+		db = void 0;
+	}
+	try {
+		await initializationLock.release();
+	} catch (releaseError) {
+		failure = failure ? preservePrimaryFailure(failure, releaseError, "initializationLockReleaseError", "Local database storage preparation and initialization-lock release both failed.") : releaseError;
+	}
+	if (failure) throw failure;
+	return paths;
+}
+async function validateLocalDatabaseStorage(options) {
+	const paths = resolveLocalRuntimePaths(options);
+	const sourceRoot = resolve(options.sourceRoot ?? process.cwd());
+	const appId = validateApplicationId(options.appId);
+	await preflightLocalApplicationRoot(paths.root, sourceRoot, appId);
+	const canonicalSourceRoot = await realpath(sourceRoot);
+	await validateRootMarker(resolve(paths.root, `${ROOT_MARKER_PREFIX}${appId}`), canonicalSourceRoot);
+	await validateExistingPathChain(paths.database, canonicalSourceRoot, "file");
+	const database = await lstat(paths.database);
+	const currentUid = process.getuid?.();
+	if (database.isSymbolicLink() || !database.isFile() || currentUid !== void 0 && database.uid !== currentUid || (database.mode & 511) !== 384) throw unsafeFilesystemEntry(`Local application database must be a current-user-owned mode-0600 file: ${paths.database}`);
+	return paths;
+}
 var LocalRuntimeError = class extends Error {
 	constructor(code, message) {
 		super(message);
@@ -654,7 +927,7 @@ var LocalRuntimeError = class extends Error {
 	code;
 };
 function resolveLocalRuntimePaths(options) {
-	const appId = normalizeAppId(options.appId);
+	const appId = validateApplicationId(options.appId);
 	const runtimePlatform = options.platform ?? platform();
 	const runtimeHome = options.homeDirectory ?? homedir();
 	const defaultRoot = defaultApplicationDataRoot(runtimePlatform, runtimeHome, options.env ?? process.env);
@@ -679,7 +952,7 @@ async function initializeLocalApplicationRuntime(options) {
 	});
 	const paths = resolveLocalRuntimePaths(options);
 	const sourceRoot = resolve(options.sourceRoot ?? process.cwd());
-	const appId = normalizeAppId(options.appId);
+	const appId = validateApplicationId(options.appId);
 	await preflightLocalApplicationRoot(paths.root, sourceRoot, appId);
 	const initializationLock = await acquireInitializationLock(paths.root);
 	let db;
@@ -1075,13 +1348,16 @@ async function acquireLocalDatabase(paths, sourceRoot, appId) {
 				root: paths.root
 			}
 		});
+		await enforcePrivateDatabaseMode(paths.database, canonicalSourceRoot);
 	} catch (error) {
+		if (db) throw await closeDatabaseAfterFailure(db, error);
 		if (prepared.pendingMarkerCreatedByAttempt) {
 			await removeMarkerIfPresent(prepared.pendingMarker, canonicalSourceRoot);
 			await removeCreatedDirectories(createdDirectories);
 		}
 		throw error;
 	}
+	if (!db) throw new Error("Local runtime database acquisition returned no database.");
 	try {
 		await publishRootMarker(prepared.finalMarker, canonicalSourceRoot);
 		await removeMarkerIfPresent(prepared.pendingMarker, canonicalSourceRoot);
@@ -1093,6 +1369,15 @@ async function acquireLocalDatabase(paths, sourceRoot, appId) {
 		db
 	};
 }
+async function enforcePrivateDatabaseMode(path, canonicalSourceRoot) {
+	const database = await openSafeFile(path, constants.O_RDWR, 384, "Local application database", canonicalSourceRoot);
+	try {
+		await database.chmod(384);
+		await database.sync();
+	} finally {
+		await database.close();
+	}
+}
 async function closeDatabaseAfterFailure(db, primaryFailure) {
 	try {
 		await db.close?.();
@@ -1475,11 +1760,17 @@ function normalizeLoopbackHost(value) {
 	if (octets.length === 4 && octets.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255) && Number(octets[0]) === 127) return host;
 	throw new LocalRuntimeError("unsafe_public_exposure", "Owner bootstrap is restricted to a loopback IP literal. Use ::1 or 127.0.0.0/8.");
 }
-function normalizeAppId(value) {
+function validateApplicationId(value) {
 	const appId = value.trim().toLowerCase();
 	if (!/^[a-z0-9][a-z0-9.-]{0,62}$/.test(appId)) throw new LocalRuntimeError("invalid_configuration", "appId must contain only lowercase letters, digits, dots, or hyphens.");
 	return appId;
 }
+function encodeApplicationId(value) {
+	const source = value.trim().toLowerCase();
+	if (/^[a-z0-9][a-z0-9.-]{0,62}$/.test(source)) return source;
+	const digest = createHash("sha256").update(value.trim()).digest("hex").slice(0, 10);
+	return validateApplicationId(`${source.replace(/[^a-z0-9.-]+/g, "-").replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "").slice(0, 52).replace(/[^a-z0-9]+$/g, "") || "app"}-${digest}`);
+}
 function defaultApplicationDataRoot(runtimePlatform, runtimeHome, env) {
 	if (runtimePlatform === "darwin") return resolve(runtimeHome, "Library", "Application Support");
 	if (runtimePlatform === "win32") return resolve(env.LOCALAPPDATA ?? env.APPDATA ?? runtimeHome);
@@ -1511,6 +1802,6 @@ function isDirectoryNotEmpty(error) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOTEMPTY";
 }
 //#endregion
-export { DeployedRuntimeCleanupError, DeployedRuntimeError, LocalRuntimeError, initializeDeployedApplicationRuntime, initializeLocalApplicationRuntime, resolveLocalRuntimePaths };
+export { DeployedRuntimeCleanupError, DeployedRuntimeError, LocalRuntimeError, MAX_RUNTIME_DIAGNOSTIC_ERRORS, MAX_RUNTIME_DIAGNOSTIC_TOOLS, RUNTIME_DIAGNOSTICS_SCHEMA_VERSION, RUNTIME_WORKER_FRESHNESS_SECONDS, encodeApplicationId, initializeDeployedApplicationRuntime, initializeLocalApplicationRuntime, prepareLocalDatabaseStorage, projectRuntimeDiagnostics, resolveLocalRuntimePaths, validateApplicationId, validateLocalDatabaseStorage };
 
 //# sourceMappingURL=index.js.map