@happyvertical/smrt-app-runtime 0.43.9

package/AGENTS.md

@@ -0,0 +1,36 @@
+# @happyvertical/smrt-app-runtime
+
+Application infrastructure composition for the validated runtime profiles in
+`@happyvertical/smrt-config`.
+
+## Local profile
+
+- `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
+  `{ driver: 'node:sqlite', custody: 'trusted-parent' }` boundary after the
+  runtime establishes its user-owned mode-0700 data root.
+- Application migrations are explicit through `prepareDatabase`; runtime never
+  creates application model tables implicitly.
+- 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.
+- Background jobs and application-defined paid capabilities are default-off.
+- The embedded runner reuses `TaskRunner`; it is not a second job contract.
+
+## Invariants
+
+- Never expose application-secret bytes or bootstrap token hashes in diagnostics.
+- Keep local data, assets, database, and secrets outside the source tree.
+- Do not reach into collection/database private fields. Add an upstream public
+  API if composition cannot be expressed through exported surfaces.
+- Keep profile selection out of domain models, generated APIs, MCP/WebMCP
+  surfaces, effects, approvals, and authorization records.
+
+## Validation
+
+```bash
+pnpm --filter @happyvertical/smrt-app-runtime test
+pnpm --filter @happyvertical/smrt-app-runtime typecheck
+pnpm --filter @happyvertical/smrt-app-runtime build
+```

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @happyvertical/smrt-app-runtime
+
+Reusable infrastructure composition for s-m-r-t applications. The package
+implements the validated profiles from `@happyvertical/smrt-config` without
+forking domain objects, generated surfaces, effects, approvals, or job calls.
+
+## Private local applications
+
+```ts
+import {
+  initializeLocalApplicationRuntime,
+} from '@happyvertical/smrt-app-runtime';
+
+const { runtime, bootstrap, diagnostics } =
+  await initializeLocalApplicationRuntime({
+    appId: 'my-app',
+    sourceRoot: process.cwd(),
+    prepareDatabase: runApplicationMigrations,
+  });
+
+// Show bootstrap.token only in the loopback onboarding URL. The plaintext is
+// returned once and only its HMAC is persisted.
+```
+
+The path resolver selects the current user's OS application-data directory
+(`~/Library/Application Support` on macOS, `%LOCALAPPDATA%` on Windows, or
+`$XDG_DATA_HOME` / `~/.local/share` on Linux). Secure initialization currently
+requires Node to expose nonzero `O_NOFOLLOW` and `O_DIRECTORY` filesystem
+flags; it fails closed on platforms without that custody support and therefore
+does not yet claim Windows runtime support. The data root contains a mode-0600
+SQLite database, a user-owned asset directory, and generated mode-0600
+application secret material. The root must be a dedicated application
+directory: placing it inside the source checkout or choosing an ancestor is
+refused, as is choosing the user home itself or the filesystem root. An
+explicitly configured root that already exists must already be
+owned by the current user with mode `0700`; initialization rejects it without
+changing permissions or creating artifacts when that custody proof fails.
+An empty root is claimed with an app-specific, empty mode-0600 marker. A
+populated root is accepted only with that valid marker, so selecting an
+unrelated private directory fails without changing its contents. A pending
+marker makes the claim crash-recoverable while the database is first acquired;
+it is promoted atomically after the released SQL custody boundary verifies the
+complete ancestor/root chain, including macOS ACLs. Failed custody removes the
+pending claim and every directory only when they were created by that attempt;
+an inherited pending claim and its database remain authoritative for retry.
+Initializers for the same data root are serialized across processes by an
+exclusive transaction in a dedicated SQLite lock database under a private
+per-user, root-keyed custody directory. The released `@happyvertical/sql`
+trusted-parent boundary validates that directory, its ancestors, and the lock
+leaf for ownership, write permissions, static links, and macOS ACLs before it
+opens the lock database. Atomic SQLite locking elects one owner without deleting
+or replacing a pathname, so there is no stale-file ABA window and no PID or
+clock lease. Process or worker death releases the kernel lock automatically. A
+read-only path, custody, and ownership-marker preflight rejects an obviously
+invalid application root before creating its lock-registry entry; the complete
+checks run again under the lease before application-root mutation. The lease
+covers storage acquisition, secret publication, SQLite tuning,
+application migrations, and bootstrap construction. Contenders wait up to two
+minutes for that complete sequence, so normal migrations can finish without
+overlap. Marker or temporary-secret cleanup therefore cannot race another
+active initializer.
+Every existing path component is opened without following symbolic links and
+checked against its canonical path before descendants or secret bytes are
+written. The runtime then acquires SQLite through `@happyvertical/sql`'s
+explicit `node:sqlite` trusted-parent custody boundary, rooted at the mode-0700
+application data directory. Unsupported runtimes or platforms and unsafe
+ownership, permissions, ACLs, or path components fail closed.
+
+The application secret is published by atomically linking a fully written,
+synced mode-0600 temporary file into place. Concurrent installers validate and
+reuse the one winning value; an incomplete or malformed existing secret is
+rejected rather than overwritten, and stale interrupted temporary files are
+removed after a complete value is durably available.
+
+The custody boundary prevents static link traversal and mutation by other OS
+principals while the application retains control of that directory. Hostile
+code already running as the same user is outside this boundary; isolating
+same-account processes requires an OS sandbox and a descriptor-relative SQLite
+VFS.
+
+Owner onboarding binds to `127.0.0.1` by default and accepts only loopback IP
+literals (`127.0.0.0/8` or `::1`), avoiding hostname-resolution ambiguity.
+The first valid claim creates a real global `Person`, `User`, default `Tenant`,
+owner `Role` / `Membership`, and server-side `Session` atomically. Startup and
+setup are idempotent; replayed, expired, or concurrent claims fail closed.
+Authenticated session TTLs are configured in whole seconds with a minimum of
+one second, and invalid values are rejected before filesystem mutation.
+
+Background jobs and application-defined paid capabilities remain disabled until
+explicitly enabled. With embedded job topology, `createEmbeddedJobRunner()`
+returns the normal s-m-r-t `TaskRunner`, so the application keeps one enqueue
+and execution contract without requiring a separate worker service.

package/dist/index.d.ts

@@ -0,0 +1,155 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+import { ResolvedApplicationRuntime } from '@happyvertical/smrt-config';
+import { RuntimeProviderOverrides } from '@happyvertical/smrt-config';
+import { SessionService } from '@happyvertical/smrt-users';
+import { TaskRunner } from '@happyvertical/smrt-jobs';
+import { TaskRunnerConfig } from '@happyvertical/smrt-jobs';
+
+export declare interface ClaimLocalOwnerInput {
+    token: string;
+    name: string;
+    email: string;
+    tenantName?: string;
+    userAgent?: string;
+    ipAddress?: string;
+}
+
+/**
+ * Initialize or reopen a local application runtime.
+ *
+ * A plaintext bootstrap token is returned only when this call creates a new
+ * invitation. Existing unexpired invitations remain valid but cannot be read
+ * back because only their HMAC is stored.
+ */
+export declare function initializeLocalApplicationRuntime(options: LocalApplicationRuntimeOptions): Promise<LocalRuntimeInitialization>;
+
+/** Initialized local runtime used by server startup and onboarding handlers. */
+export declare interface LocalApplicationRuntime {
+    readonly db: DatabaseInterface;
+    readonly paths: LocalRuntimePaths;
+    readonly bindHost: string;
+    readonly resolvedRuntime: ResolvedApplicationRuntime;
+    readonly backgroundJobsEnabled: boolean;
+    readonly paidCapabilitiesEnabled: boolean;
+    ensureBootstrapInvitation(): Promise<LocalOwnerBootstrapInvitation | null>;
+    rotateBootstrapInvitation(): Promise<LocalOwnerBootstrapInvitation>;
+    claimOwner(input: ClaimLocalOwnerInput): Promise<LocalOwnerClaimResult>;
+    restoreSession(sessionId: string): ReturnType<SessionService['loadSessionContext']>;
+    createEmbeddedJobRunner(config?: TaskRunnerConfig): Promise<TaskRunner>;
+    diagnostics(): Promise<LocalRuntimeDiagnostics>;
+}
+
+export declare interface LocalApplicationRuntimeOptions extends ResolveLocalRuntimePathsOptions {
+    /** Actual HTTP bind host. Owner bootstrap refuses non-loopback values. */
+    bindHost?: string;
+    /**
+     * Explicit application migration/schema hook, invoked before identity access.
+     * It must be idempotent; runtime code never synthesizes application tables.
+     */
+    prepareDatabase?: (db: DatabaseInterface) => Promise<void>;
+    /** Local profile provider overrides (only validated local combinations survive). */
+    providers?: RuntimeProviderOverrides;
+    /** Short-lived bootstrap token lifetime. Range: 1..900 seconds. */
+    bootstrapTtlSeconds?: number;
+    /** Normal authenticated session lifetime in whole seconds. Minimum 1. */
+    sessionTtlSeconds?: number;
+    /** Explicit opt-in for persisted background work. Default false. */
+    backgroundJobs?: boolean;
+    /** Explicit opt-in for application-defined paid capabilities. Default false. */
+    paidCapabilities?: boolean;
+    /** Testable clock. */
+    now?: () => Date;
+}
+
+export declare type LocalBootstrapStatus = 'available' | 'expired' | 'claimed' | 'unavailable';
+
+export declare interface LocalOwnerBootstrapInvitation {
+    /** Plaintext is returned exactly when a new claim is issued; it is never persisted. */
+    readonly token: string;
+    readonly expiresAt: string;
+}
+
+export declare interface LocalOwnerClaimResult {
+    readonly profileId: string;
+    readonly userId: string;
+    readonly tenantId: string;
+    readonly membershipId: string;
+    readonly sessionId: string;
+}
+
+/** Secret-free, machine-readable local runtime state. */
+export declare interface LocalRuntimeDiagnostics {
+    readonly schemaVersion: 1;
+    readonly runtime: ResolvedApplicationRuntime;
+    readonly bind: {
+        readonly host: string;
+        readonly loopback: true;
+    };
+    readonly paths: LocalRuntimePaths;
+    readonly storage: {
+        readonly database: 'sqlite-file';
+        readonly assets: 'user-owned-directory';
+        readonly secrets: 'mode-0600-local-file';
+    };
+    readonly bootstrap: {
+        readonly status: LocalBootstrapStatus;
+        readonly expiresAt: string | null;
+        readonly tokenValuesIncluded: false;
+        readonly tokenHashesIncluded: false;
+    };
+    readonly tenancy: {
+        readonly mode: 'real-default-tenant';
+        readonly ui: 'hidden';
+    };
+    readonly jobs: {
+        readonly topology: 'inline' | 'embedded';
+        readonly backgroundEnabled: boolean;
+    };
+    readonly paidCapabilitiesEnabled: boolean;
+    readonly secretValuesIncluded: false;
+}
+
+/** Stable, secret-free local-runtime failure. */
+export declare class LocalRuntimeError extends Error {
+    readonly code: LocalRuntimeErrorCode;
+    constructor(code: LocalRuntimeErrorCode, message: string);
+}
+
+export declare type LocalRuntimeErrorCode = 'bootstrap_claimed' | 'bootstrap_expired' | 'bootstrap_invalid' | 'bootstrap_unavailable' | 'capability_disabled' | 'invalid_configuration' | 'unsafe_public_exposure';
+
+export declare interface LocalRuntimeInitialization {
+    readonly runtime: LocalApplicationRuntime;
+    readonly bootstrap: LocalOwnerBootstrapInvitation | null;
+    readonly diagnostics: LocalRuntimeDiagnostics;
+}
+
+/** Paths owned by the local user, outside the source tree by default. */
+export declare interface LocalRuntimePaths {
+    readonly root: string;
+    readonly database: string;
+    readonly assets: string;
+    readonly secrets: string;
+    readonly applicationSecret: string;
+}
+
+/**
+ * Resolve deterministic user-owned paths and reject source-tree placement.
+ */
+export declare function resolveLocalRuntimePaths(options: ResolveLocalRuntimePathsOptions): LocalRuntimePaths;
+
+export declare interface ResolveLocalRuntimePathsOptions {
+    /** Stable application identifier, e.g. `lolaus`. */
+    appId: string;
+    /** Explicit user-owned data directory. Defaults to the OS application-data directory. */
+    dataDirectory?: string;
+    /** Source checkout to protect from accidental data placement. Defaults to cwd. */
+    sourceRoot?: string;
+    /** Testable default-root and filesystem case-sensitivity override. */
+    platform?: NodeJS.Platform;
+    /** Testable home-directory override. */
+    homeDirectory?: string;
+    /** Testable environment override. */
+    env?: NodeJS.ProcessEnv;
+}
+
+export { }