@happyvertical/smrt-app-runtime 0.53.3 → 0.53.5

package/AGENTS.md

@@ -33,6 +33,30 @@ Application infrastructure composition for the validated runtime profiles in
   A token that cannot claim fails a read-only preflight before role/catalog
   seeding (#3323); the claim transaction's conditional UPDATE stays the
   authority for single use, expiry, and concurrency.
+- Local MCP tokens (`mcpTokens`, `openLocalMcpTokenStore`, `smrt app token`):
+  owner-bound, scoped, expiring (default 30 d, max 365 d), revocable. Only a
+  domain-separated HMAC (application secret) is stored, in the runtime-owned
+  `_smrt_local_mcp_tokens` system table (created like the bootstrap table;
+  never application schema). Issue refuses scopes the owner lacks; verify
+  returns token scopes ∩ live permissions and `null` for anything else.
+- Bearer binding is explicit (`tenantBinding`, set by the auth adapter;
+  `direct-membership.ts`): `direct` (local tokens, default hosted resolver)
+  needs an active direct membership in exactly the tenant; the default
+  `direct-or-inherited` (hosted app mappings) applies
+  `isSessionTenantAuthorized`'s rule. The direct row, when present, is pinned
+  into `PermissionResolver`, so inheritance never substitutes for it.
+  `verify()` principals (and their `scopes` arrays) are frozen;
+  `runAsPrincipal` takes a validated, deep-frozen, null-prototype copy of
+  the principal before any await (`plain-data.ts`: own data only; poison
+  keys `__proto__`/`constructor`/`prototype`, accessors, inherited or
+  non-plain data, sparse arrays and functions rejected), authorizes from it,
+  and hands `fn` that snapshot. Token `issue()` input is read the same way.
+  They carry
+  `tenantBinding: 'direct'` and the
+  `LOCAL_MCP_TOKEN_PRINCIPAL` brand; `runAsPrincipal` rejects a copy that
+  widens the binding, so the two public APIs compose safely.
+  Never log or return the token outside `issue()`. The operator store opens an
+  uncached connection and takes no writer lease (revocation is per request).
 - Background jobs and application-defined paid capabilities are default-off.
 - The embedded runner reuses `TaskRunner`; it is not a second job contract.
 
@@ -68,6 +92,65 @@ 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.
 
+## SvelteKit entry (`./sveltekit`)
+
+- Server-only subpath; `@sveltejs/kit` is an optional peer and is externalized
+  in `vite.config.ts` (kit recognizes `redirect`/`fail` by class identity).
+  The root entry must never import kit or Svelte.
+- Without a `runtime` option the profile comes from smrt-config's
+  `resolveEffectiveApplicationRuntime(await loadConfig())`, the same rule as
+  `smrt app` (#3446): no block → `local`; `null`/`false`/`0`/`''` fail closed.
+- `createSmrtSvelteKitRuntime()` order is fixed: readiness gate → URL tenant
+  selection (`locals.selectedTenant*`, never tenant context, headers ignored) →
+  verified session (tenant context entered only when
+  `isSessionTenantAuthorized()` accepts it, else unauthenticated; never via
+  `createSessionHandler`, which re-runs `resolve` on downstream errors) →
+  publish `locals.tenantContext` only for that verified tenant.
+- `database-rls` isolation forces `postgresRls: true`, including on
+  `skipPaths` (anonymous principal). `resolve` runs at most once;
+  session-layer failure before it is a 500 with cleared locals.
+- In an RLS request `classOptions()`/`databaseConfig()` return the
+  transaction-bound request db (class `db` overrides win). Anything that
+  outlives a request (session service, tenant selector) must use the base
+  config, never these.
+- The local writer lease defaults to `defaultWriterLease()` (root
+  `acquireWriterLease` over `prepareApplicationStateRoot`, presenting
+  `SMRT_OPERATION_INSTANCE`); `acquireWriterLease` replaces it, `false` opts
+  out, deployed profiles never take it. Provider readiness stays injected:
+  apps pass `createProviderReadinessProbe`; deployed startup fails closed
+  without `providerReadiness`.
+- `getCollection()` builds from `classOptions()` on every call (RLS request db
+  inside a request); each generated route's embedded prelude imports the
+  app's `smrt.ts` and reaches it through core's
+  `createGeneratedCollectionAccess()` (a legacy accessor export wins,
+  deprecated for one release).
+- Owner setup removes the `smrt app` onboarding hand-off files by default,
+  immediately after the claim commits (before cookie serialization or hooks);
+  `onOwnerClaimed` is for additional cleanup and
+  `removeOnboardingHandoff: false` is the explicit opt-out.
+- Owner setup re-checks loopback peer and loopback URL host per request and
+  returns only fixed `{ code, message }` failures.
+- `verifyLocalMcpToken` (local only) and `resolveMcpPrincipal` (hosted only:
+  issuer/subject → `oidc_identities` → exactly one active user with exactly
+  one active direct membership, else `null`) are the runtime's MCP credential
+  bindings; pass the runtime as `createHostedMcpResourceAuth({ runtime })`.
+  Token claims never select a tenant.
+- `resolveApplicationId()` / `runtimeConfigurationFingerprint()` must stay
+  byte-compatible with process managers (golden vectors in tests).
+
+## Operator state (root entry)
+
+- One owner for the state shared by the web process and `smrt app`
+  (`@happyvertical/smrt-cli/app` re-exports these): `resolveApplicationStateRoot`
+  / `prepareApplicationStateRoot` (private app-bound mode-0700 root and
+  marker), `withOperationLock` (`operation.lock`), `acquireWriterLease` /
+  `readActiveWriterLease` (`writer.lease`), `reclaimStaleRecord`, and
+  `createProviderReadinessProbe` (`SMRT_*_READINESS_MODULE`, resolved from the
+  app root with Node's own ESM rules). File names, record formats, and
+  messages are a cross-process contract; never change them unilaterally.
+- Tests that hook `node:fs` interleavings must live in this package: from a
+  consumer the package is an externalized dependency a mock cannot reach.
+
 ## Public runtime diagnostics
 
 - `projectRuntimeDiagnostics()` is the only public diagnostic projection. It

package/README.md

@@ -102,6 +102,117 @@ 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.
 
+## SvelteKit entry
+
+`@happyvertical/smrt-app-runtime/sveltekit` composes the profile runtime,
+tenant selection, the signed session, and authorized-tenant locals so an app's
+server hooks are a few lines. `@sveltejs/kit` is an optional peer dependency;
+the root entry never imports it.
+
+```ts
+// src/hooks.server.ts
+import { createSmrtSvelteKitRuntime } from '@happyvertical/smrt-app-runtime/sveltekit';
+
+export const runtime = createSmrtSvelteKitRuntime({
+  prepareDatabase: runApplicationMigrations, // optional, idempotent
+});
+export const { handle, init } = runtime;
+```
+
+```ts
+// src/app.d.ts
+import type { SmrtRuntimeLocals } from '@happyvertical/smrt-app-runtime/sveltekit';
+declare global {
+  namespace App {
+    interface Locals extends SmrtRuntimeLocals {}
+  }
+}
+```
+
+`init` is the fail-closed startup gate (local runtime or deployed bindings) and
+`handle` waits for it, then runs, in order: URL tenant selection into
+`locals.selectedTenant*` (never tenant context; tenant headers are ignored),
+the signed session, and publication of `locals.tenantContext` only when the
+active context matches the verified session tenant. A session's tenant is
+accepted only for an active direct membership or a legitimately inherited
+one (`isSessionTenantAuthorized()`, the same rule deployed `restoreSession()`
+applies); otherwise the request is unauthenticated (no user, permissions,
+tenant, or tenant context). `database-rls` isolation always runs the request
+RLS transaction (`session.postgresRls` cannot disable it); a
+`session.skipPaths` prefix skips session loading only and still runs inside
+that transaction as an anonymous principal. During such a request
+`runtime.classOptions()` / `runtime.databaseConfig()` return the
+transaction-bound request database (unless the class has its own `db`
+override), so call them per request and never retain the result. Downstream code runs
+at most once: its error propagates unchanged, and a session-layer failure
+before it returns 500 with no authenticated locals. Defaults read `SMRT_APP_ID`, `SMRT_DATA_DIR`, `HOST`, `DATABASE_URL`,
+`TENANT_BASE_DOMAIN`, and `SMRT_BACKGROUND_JOBS`; `smrt.config` `runtime`
+selects the profile (local when absent; a present `null`/`false`/`0`/`''`
+fails closed, as in `smrt app`). Deployed profiles additionally require
+`providerReadiness` probes and fail closed without them. In the local profile
+the runtime holds the single-writer lease shared with `smrt app` operations by
+default (`defaultWriterLease()`: `writer.lease` under
+`prepareApplicationStateRoot()`, presenting `SMRT_OPERATION_INSTANCE`); pass
+`acquireWriterLease` to replace it or `acquireWriterLease: false` to hold none.
+Optional hooks: `onBootstrapInvitation` (present a newly issued setup token),
+`selectTenant`, `session`, and `classOverrides`.
+`runtime.getCollection(className)` returns the registered collection built
+from `runtime.classOptions(className)` on that call. Each generated `/api/*`
+route embeds a prelude that imports the app's `src/lib/server/smrt.ts` and
+resolves collections through its exported `runtime` (core's
+`createGeneratedCollectionAccess()`), so an app's `smrt.ts` is only the
+runtime and its options. A legacy `getCollection`/`getSmrtConfig` export there
+still takes precedence for one release, with a deprecation warning.
+
+Mountable routes:
+
+```ts
+// src/routes/api/_runtime/health/+server.ts
+export const GET = createRuntimeHealthHandler(runtime);
+// src/routes/api/_runtime/diagnostics/+server.ts
+export const GET = createRuntimeDiagnosticsHandler({ runtime, toolNames });
+// src/routes/setup/+page.server.ts
+export const { load, actions } = createOwnerSetupPage(runtime);
+// src/routes/+layout.server.ts
+export const load = createSessionLayoutLoad();
+```
+
+Diagnostics authorize (owner role or `runtime_diagnostics.read` on an active,
+session-matching membership) before reading the runtime and return only stable
+`{ schemaVersion: 1, error: { code } }` failures. Owner setup is local-only and
+re-checks on every request that both the peer address and the URL host are
+loopback; its `default` action reads `token`, `name`, `email`, and optional
+`tenantName`, sets the session cookie, and redirects 303, or returns
+`fail(status, { code, message })` with `setup_disabled` (404),
+`setup_unavailable` (403), `setup_invalid_input` (400), or `setup_invalid`
+(400). Claim error text is never returned. After the claim commits, the
+runtime removes the `smrt app setup` / `recover` hand-off files
+(`ONBOARDING_HANDOFF_FILES`: `onboarding.json`, `onboarding-launch.html`) from
+`runtime.applicationStateRoot()`, so `pnpm app:open` stops offering the spent
+invitation; failed claims leave them untouched. `onOwnerClaimed` remains for
+extra app cleanup and `removeOnboardingHandoff: false` opts out.
+
+`resolveApplicationId()` and `runtimeConfigurationFingerprint()` (root entry)
+are the canonical app ID and secret-free configuration fingerprint shared by
+the web health route and process managers.
+
+The root entry also owns the operator state shared with `smrt app`:
+`prepareApplicationStateRoot()` (private, app-bound state directory),
+`withOperationLock()`, `acquireWriterLease()` / `readActiveWriterLease()`,
+and `createProviderReadinessProbe()`. The SvelteKit runtime takes the writer
+lease itself; a SvelteKit app passes only the readiness probe and its own
+options, without depending on the CLI:
+
+```ts
+// src/lib/server/smrt.ts
+import { createProviderReadinessProbe } from '@happyvertical/smrt-app-runtime';
+import { createSmrtSvelteKitRuntime } from '@happyvertical/smrt-app-runtime/sveltekit';
+
+export const runtime = createSmrtSvelteKitRuntime({
+  providerReadiness: createProviderReadinessProbe,
+});
+```
+
 ## Self-hosted and cloud applications
 
 The deployed initializer validates the selected profile against concrete,

package/dist/application-identity.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Canonical application identity shared by the web process, operator commands,
+ * and generated operational surfaces.
+ *
+ * Every process that manages the same application must derive the same app ID
+ * and the same configuration fingerprint, so these helpers live next to
+ * `validateApplicationId()` / `encodeApplicationId()` rather than in copied
+ * template scripts.
+ */
+export interface ResolveApplicationIdOptions {
+    /** Directory containing the application's `package.json`. Defaults to cwd. */
+    sourceRoot?: string;
+    /** Package name to encode instead of reading `package.json`. */
+    packageName?: string;
+    /** Explicit, strictly validated app ID (for example `SMRT_APP_ID`). */
+    explicitId?: string;
+}
+/**
+ * Resolve one stable application identity.
+ *
+ * An explicit ID is validated with {@link validateApplicationId}; otherwise
+ * the package name is encoded with {@link encodeApplicationId}.
+ */
+export declare function resolveApplicationId(options?: ResolveApplicationIdOptions): string;
+/**
+ * Runtime selection the fingerprint covers. Structural so operator tooling
+ * can fingerprint a resolved runtime it loaded itself; a
+ * {@link ResolvedApplicationRuntime} always satisfies it.
+ */
+export interface FingerprintRuntime {
+    readonly profile: string;
+    readonly providers: unknown;
+}
+/**
+ * Secret-safe identity used to reject stale managed processes after profile,
+ * provider, database-target, or listener configuration changes.
+ *
+ * Credentials, query strings, and fragments of `DATABASE_URL` are excluded;
+ * only `sslmode` survives. The digest is stable for identical inputs so a
+ * process manager and the web process can compare it.
+ */
+export declare function runtimeConfigurationFingerprint(runtime: FingerprintRuntime, environment?: Readonly<Record<string, string | undefined>>): string;
+//# sourceMappingURL=application-identity.d.ts.map

package/dist/application-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-identity.d.ts","sourceRoot":"","sources":["../src/application-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,MAAM,WAAW,2BAA2B;IAC1C,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,2BAAgC,GACxC,MAAM,CAeR;AAkBD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,kBAAkB,EAC3B,WAAW,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GACtE,MAAM,CAyBR"}