@happyvertical/smrt-playbooks 0.44.0 → 0.45.0

package/AGENTS.md

@@ -117,6 +117,78 @@ what a lower layer disabled. Enforced in `mergePlaybookLayers()` (`enabled &&
 layer.enabled`) and rejected at `save()` with a specific message. Plane lists
 narrow the same way.
 
+## Preflight (#2590)
+
+`preflightPlaybook({ key, plane, principal, resolve, evaluate })` resolves a
+playbook through the **caller's own layer chain**, decomposes it, and returns a
+per-step verdict — `allow` | `deny` | `unknown` — plus an aggregate. It executes
+nothing.
+
+**Advisory only. Preflight predicts; it never grants.** Every step re-enforces at
+execution, unconditionally. Without that, a permission revoked mid-playbook would
+leave a cached "allowed" standing — a time-of-check/time-of-use bypass. That
+constraint is also what makes the cache free: a stale `allow` costs a
+correctly-denied step, a stale `deny` costs a briefly hidden capability that
+expires on the TTL, and neither is a security event.
+
+The two planes are **not symmetric**, deliberately:
+
+| | Server (`createServerStepEvaluator`) | Browser (`createBrowserStepEvaluator`) |
+|---|---|---|
+| Layers | `tool-allowlist`, `operation-permission` | `action-exposure`, `public-access`, `field-permissions`, `app-auth` |
+| Source | `PrincipalRun.isToolAllowed` + the operation-permission predicate | `isApiActionEnabled`, `isRoutePublic`, field read-permission slugs |
+| Intent step | `plane` — denied unless the intent declares `server` | `intent-mount` — always `unknown` |
+| App auth | n/a (the predicate *is* the gate) | **`unknown`** — never evaluated |
+
+Browser preflight covers the **static layers only**. Generated REST auth is
+`authMiddleware?: (objectName, action) => (req) => Promise<Request | Response>`:
+request-bound, `Response`-returning rather than boolean, and free to consult
+session stores, rate-limit, or audit. It is not a dry-run predicate, so preflight
+**never invokes it**, synthetically or otherwise — the `_preflight` route's
+options in `smrt-core` carry no auth handle at all, only the boolean
+`appAuthConfigured`. An optional `authPredicate` seam can later be added to
+`BrowserPreflightLayerSource` and turn the `app-auth` `unknown` into a real
+verdict **without changing the report contract**.
+
+`createBrowserPlaybookPreflight()` (in `rest-preflight.ts`) is the provider wired
+into `APIConfig.playbookPreflight`. Core owns the route and the static-layer
+facts because `ObjectRegistry` is core's; this package owns resolution and the
+verdict vocabulary — so the dependency stays one-way.
+
+### Not an oracle
+
+Every playbook the caller's chain cannot resolve — unknown key, disabled,
+wrong-plane, unresolvable intent, or an error thrown anywhere in resolution or
+evaluation — returns the single frozen `PLAYBOOK_PREFLIGHT_UNAVAILABLE` value: no
+key echo, no reason, no message, and served by the route with an unconditional
+200. An unknown key and an unauthorized key are byte-identical.
+
+Timing is held in the same class from both ends. The unknown-key path pays the
+same override-layer read a resolvable key pays (`equalizeUnknownKeyCost`),
+because `resolvePlaybook()` short-circuits a registry miss before touching the
+database; and unavailable results are cached for unknown and
+registered-but-unavailable keys **alike**, because caching only one of them would
+put every *repeat* probe of the other in a different timing class. Growth from
+probing random keys is bounded where it belongs — the preflight cache is capped
+with expiry-first eviction — not by declining to cache.
+
+### Verdict rules worth knowing
+
+- `deny` beats `unknown` beats `allow` (`worstVerdict`), and a step's `reason` is
+  always the first layer that produced its verdict — reason and verdict can never
+  describe different layers.
+- Evaluation never short-circuits: preflight exists to say *which* step of five
+  would die.
+- A missing **field** read-permission slug redacts a field, it does not fail the
+  step, so `field-permissions` stays `allow` with `reason: 'fields-redacted'` and
+  the missing slugs attached. Reporting `deny` would predict a failure that will
+  not happen.
+- A non-public route with **no** middleware wired is a real, statically knowable
+  `deny` (the generator's fail-closed 401). With one wired it is `unknown`.
+- A tool listing may filter on preflight (`filterPlaybooksByPreflight` in
+  `smrt-agents`), but that filter is a listing convenience and **never**
+  load-bearing for authorization.
+
 ## Caching
 
 Resolutions are cached per `(key, tenantId, db)` with a TTL. The cache is
@@ -127,6 +199,27 @@ tenant inherits from it. Use `clearPlaybookCache()` in tests.
 A monotonic per-`(db, key)` invalidation generation closes the read-racing-a-
 write window; see the Gotchas entry below before touching `cache.ts`.
 
+Preflight results cache separately, per `(principal, key, plane, tenant)`, with a
+shorter TTL and **no invalidation ceremony of their own** — an entry captured
+under an older generation of the playbook cache is dropped on read. `principal`
+is an opaque, caller-scoped partition key: it is never echoed in a report and
+never consulted for authority. Use `clearPlaybookPreflightCache()` in tests.
+
+Two partitioning traps, both of which produce a cross-context read rather than a
+stale one:
+
+- **The tenant is resolved, not defaulted.** `preflightPlaybook()` applies the
+  same `tenantId !== undefined ? tenantId : (getTenantId() ?? null)` fallback
+  `loadPlaybookBase()` does. Scoping an omitted tenant to `null` would let two
+  ambient `withTenant()` callers with one principal share an entry — and the
+  report carries the resolved title and description.
+- **The principal must cover every input the evaluation reads.** The REST
+  provider's default folds in `appAuthConfigured` (it decides whether
+  `public-access` / `app-auth` are verdicts or `unknown`) and distinguishes an
+  *absent* permission set (`perm:unpublished`, field layer `unknown`) from an
+  explicitly empty one (known, `allow` with redactions). A custom `principal`
+  must do the same.
+
 ## Gotchas
 
 - **`context` carries the tenant scope.** `save()` sets

package/dist/index.d.ts

@@ -5,8 +5,130 @@ import { SmrtCollection } from '@happyvertical/smrt-core';
 import { SmrtObject } from '@happyvertical/smrt-core';
 import { SmrtObjectOptions } from '@happyvertical/smrt-core';
 
+/**
+ * Static layers a browser-plane step is evaluated against.
+ *
+ * Everything here is a build-time or configuration fact. The generated
+ * `authMiddleware` is deliberately absent: it is request-bound, returns a
+ * `Response` rather than a boolean, and may consult session stores, rate-limit,
+ * or audit — so preflight never invokes it, synthetically or otherwise, and
+ * `appAuthConfigured` is the only thing it is allowed to know about it.
+ *
+ * An `authPredicate` seam (option 1 in #2590) can later be added as an optional
+ * member here, turning the `app-auth` layer's `unknown` into a real verdict
+ * without changing the report contract.
+ */
+export declare interface BrowserPreflightLayerSource {
+    /** `isApiActionEnabled` for the referenced model operation. */
+    isActionExposed(model: string, action: string): boolean;
+    /** `isRoutePublic` for the HTTP method the action maps to. */
+    isRoutePublic(model: string, action: string): boolean;
+    /** Field-level read-permission slugs the step's model declares. */
+    requiredFieldPermissions(model: string, action: string): readonly string[];
+    /** Whether an app-level auth middleware is wired. Never invoked. */
+    appAuthConfigured: boolean;
+}
+
+export declare interface BrowserPreflightOptions {
+    layers: BrowserPreflightLayerSource;
+    /**
+     * The caller's published permission slugs, when the host publishes them.
+     * `null`/absent makes the field layer report `unknown` rather than guess.
+     */
+    permissions?: Iterable<string> | null;
+}
+
+export declare interface BrowserPreflightProviderOptions {
+    /**
+     * Resolution options shared by every request — classifier, intent registry,
+     * and any host-level runtime override. The per-request database handle and
+     * tenant come from the route.
+     */
+    resolve?: Omit<ResolvePlaybookOptions, 'plane' | 'db'>;
+    /**
+     * Derives the cache-partitioning principal identity for a request. Opaque and
+     * never echoed; defaults to the caller's permission slugs, which is the only
+     * caller-distinguishing input the static layers actually read.
+     */
+    principal?: (request: {
+        permissions?: Iterable<string>;
+        appAuthConfigured: boolean;
+    }) => string;
+}
+
 export declare function clearPlaybookCache(): void;
 
+/** Drops every cached preflight result. Use in tests. */
+export declare function clearPlaybookPreflightCache(): void;
+
+/**
+ * Builds the provider wired into `APIConfig.playbookPreflight`.
+ *
+ * ```typescript
+ * const api = new APIGenerator(manifest, {
+ *   playbookPreflight: createBrowserPlaybookPreflight(),
+ * });
+ * ```
+ *
+ * Every unresolvable key — unknown, disabled, browser-invalid, unresolvable
+ * intent — comes back as the single uniform unavailable report, so the endpoint
+ * is not an enumeration oracle.
+ */
+export declare function createBrowserPlaybookPreflight(options?: BrowserPreflightProviderOptions): (request: {
+    key: string;
+    plane: 'browser';
+    permissions?: Iterable<string>;
+    appAuthConfigured: boolean;
+    db?: unknown;
+}) => Promise<PlaybookPreflightReport>;
+
+/**
+ * Browser-plane evaluator: the static layers only.
+ *
+ * - `action-exposure` — `isApiActionEnabled`. A disabled action is a hard,
+ *   statically knowable deny (the route answers 405).
+ * - `public-access` — `isRoutePublic`. A non-public route with **no** app auth
+ *   middleware wired is a hard deny (the generator's fail-closed 401); with one
+ *   wired it is `unknown`, because whether that middleware passes is exactly
+ *   what preflight refuses to guess.
+ * - `field-permissions` — the model's declared field read-permission slugs
+ *   against the caller's published set. Missing slugs redact fields rather than
+ *   fail the step, so the verdict stays `allow` and carries
+ *   `reason: 'fields-redacted'` plus the missing slugs; an unpublished
+ *   permission set reports `unknown`.
+ * - `app-auth` — `unknown` whenever a middleware is wired. This is the layer an
+ *   `authPredicate` seam would later fill in.
+ *
+ * An intent step never crosses the REST boundary at all, so it is reported
+ * `unknown` against `intent-mount`: whether the surface is mounted and what its
+ * staged-control review does are runtime facts of the page, not of the build.
+ */
+export declare function createBrowserStepEvaluator(options: BrowserPreflightOptions): PreflightStepEvaluator;
+
+/**
+ * A layer source reading the generated REST surface's own static rules.
+ *
+ * A model this build does not register resolves to no object name, and every
+ * layer then fails closed: an unregistered model has no route, so a step naming
+ * one can only die.
+ */
+export declare function createRestPreflightLayerSource(options: {
+    appAuthConfigured: boolean;
+}): BrowserPreflightLayerSource;
+
+/**
+ * Server-plane evaluator: the intersection of the persona tool allow-list and
+ * the operation-permission predicate, per step, with nothing executed.
+ *
+ * An intent step is reported against its **declared** plane validity: an intent
+ * that does not declare `server` is denied with reason `plane`, and one that
+ * does is `unknown`, because server validity rides the #2446 command/ack bridge
+ * whose acknowledgement is not statically knowable. This repeats a check
+ * resolution already made, deliberately — the same defense-in-depth shape as
+ * `assertToolAllowed()` gating both the tool offer and its execution.
+ */
+export declare function createServerStepEvaluator(options: ServerPreflightOptions): PreflightStepEvaluator;
+
 /**
  * Registers a code-default playbook. Packages call this at import time so a
  * bundled playbook resolves without any application registration.
@@ -21,12 +143,26 @@ export declare const FAIL_CLOSED_CLASSIFICATION: CapabilityClassification;
 
 export declare function getPlaybookCacheTtlMs(): number;
 
+/** TTL applied to every cached preflight result. */
+export declare function getPlaybookPreflightCacheTtlMs(): number;
+
 export declare function normalizeEditableConfig(editable?: Partial<PlaybookEditableConfig>): PlaybookEditableConfig;
 
 /* Excluded from this release type: PACKAGE_VERSION_INITIALIZED */
 
 export declare const PLAYBOOK_PLANES: readonly PlaybookPlane[];
 
+/**
+ * The one response every unresolvable playbook produces.
+ *
+ * Frozen and shared so an unknown key and an unauthorized key are byte-for-byte
+ * identical: same shape, same values, no key echo, no reason code, no message.
+ * Preflight answers only for playbooks resolvable through the caller's own
+ * layer chain, and says nothing about anything else — including whether it
+ * exists.
+ */
+export declare const PLAYBOOK_PREFLIGHT_UNAVAILABLE: PlaybookPreflightUnavailableReport;
+
 export declare interface PlaybookAcceptance {
     ok: true;
     plan: PlaybookPlan;
@@ -289,6 +425,56 @@ export declare interface PlaybookPlanStep {
     classificationDeclared: boolean;
 }
 
+export declare interface PlaybookPreflightAvailableReport {
+    available: true;
+    /**
+     * Literal `true` on every report, as a type-level reminder: a report is a
+     * prediction, never a grant, and every step is authorized again where it
+     * executes.
+     */
+    advisory: true;
+    key: string;
+    plane: PlaybookPlane;
+    title: string;
+    description: string;
+    verdict: PreflightVerdict;
+    steps: readonly PreflightStepReport[];
+    summary: PreflightSummary;
+}
+
+/** A preflight result. Advisory only — see the two variants above. */
+export declare type PlaybookPreflightReport = PlaybookPreflightAvailableReport | PlaybookPreflightUnavailableReport;
+
+export declare interface PlaybookPreflightRequest {
+    key: string;
+    plane: PlaybookPlane;
+    /**
+     * Opaque, caller-scoped principal identity used to partition the cache. It is
+     * never echoed in the report and never consulted for authority. The cache key
+     * also folds in `resolve.tenantId`, so a principal string need not encode the
+     * tenant to stay correct.
+     */
+    principal: string;
+    /** Options handed to `resolvePlaybook()` — the caller's own layer chain. */
+    resolve?: ResolvePlaybookOptions;
+    /** Evaluates each resolved step. */
+    evaluate: PreflightStepEvaluator;
+}
+
+/**
+ * The single, uniform answer for every playbook the caller's own layer chain
+ * cannot resolve. An unknown key and an unauthorized key produce this exact
+ * frozen value, so preflight is not an enumeration oracle: it carries no key,
+ * no plane, and no reason to tell the two apart.
+ */
+export declare interface PlaybookPreflightUnavailableReport {
+    available: false;
+    advisory: true;
+    verdict: 'deny';
+    steps: readonly [];
+    summary: PreflightSummary;
+}
+
 /**
  * Global process registry of code-default playbooks, keyed by namespaced key.
  *
@@ -319,6 +505,87 @@ export declare type PlaybookResolution = PlaybookAcceptance | PlaybookRejection;
 /** A playbook step. Exactly two kinds exist in v1; playbooks cannot nest. */
 export declare type PlaybookStep = PlaybookOperationStep | PlaybookIntentStep;
 
+/**
+ * The authority layers preflight reports on. The two planes are deliberately
+ * asymmetric and report different layers:
+ *
+ * - server plane — `tool-allowlist`, `operation-permission`, and `plane` for an
+ *   intent step;
+ * - browser plane — `action-exposure`, `public-access`, `field-permissions`,
+ *   `app-auth`, and `intent-mount` for an intent step.
+ */
+export declare type PreflightLayer = 'tool-allowlist' | 'operation-permission' | 'plane' | 'action-exposure' | 'public-access' | 'field-permissions' | 'app-auth' | 'intent-mount';
+
+/** One authority layer's verdict for one step. */
+export declare interface PreflightLayerReport {
+    layer: PreflightLayer;
+    verdict: PreflightVerdict;
+    reason: PreflightReason;
+    /**
+     * Permission slugs this layer found missing, when it knows them. Present only
+     * on layers that evaluate a slug set.
+     */
+    missingPermissions?: readonly string[];
+}
+
+/**
+ * Decomposes a resolved plan into per-step verdicts using `evaluate`.
+ *
+ * Every step is evaluated — evaluation does not short-circuit on the first
+ * denial, because the point of preflight is to show the caller *which* step of
+ * five would die, not merely that one would.
+ */
+export declare function preflightPlan(plan: PlaybookPlan, evaluate: PreflightStepEvaluator): Promise<PlaybookPreflightAvailableReport>;
+
+/**
+ * Preflights one playbook for one caller on one plane.
+ *
+ * Resolves through the **caller's own layer chain** (their tenant, their
+ * overrides, their plane), decomposes the plan, and evaluates each step with the
+ * plane's evaluator. Any playbook the chain cannot resolve — unknown, disabled,
+ * wrong plane, unresolvable intent — returns the single
+ * {@link PLAYBOOK_PREFLIGHT_UNAVAILABLE} value.
+ *
+ * Results are cached per `(principal, key, plane)` under the playbook cache's
+ * generation counter; see `preflight-cache.ts` for why that is safe.
+ */
+export declare function preflightPlaybook(request: PlaybookPreflightRequest): Promise<PlaybookPreflightReport>;
+
+/** Why a layer reached its verdict. A stable code, never a free-form message. */
+export declare type PreflightReason = 'ok' | 'tool-not-allowed' | 'permission-denied' | 'permission-unknown' | 'plane' | 'action-not-exposed' | 'not-public' | 'auth-required' | 'app-auth-not-evaluated' | 'app-auth-not-configured' | 'fields-redacted' | 'field-permissions-unknown' | 'intent-not-mounted' | 'intent-bridge-not-evaluated' | 'not-evaluated';
+
+/** What a step evaluator returns; `preflightPlan` supplies `index` and `kind`. */
+export declare interface PreflightStepEvaluation {
+    layers: readonly PreflightLayerReport[];
+}
+
+/** Evaluates one resolved plan step without executing any part of it. */
+export declare type PreflightStepEvaluator = (step: PlaybookPlanStep) => PreflightStepEvaluation | Promise<PreflightStepEvaluation>;
+
+/** A step's aggregate verdict plus the per-layer detail behind it. */
+export declare interface PreflightStepReport {
+    index: number;
+    kind: PlaybookStep['kind'];
+    verdict: PreflightVerdict;
+    /** Reason of the first layer that produced the step's aggregate verdict. */
+    reason: PreflightReason;
+    layers: readonly PreflightLayerReport[];
+}
+
+export declare interface PreflightSummary {
+    allow: number;
+    deny: number;
+    unknown: number;
+}
+
+/**
+ * Verdict for one authority layer, one step, or a whole plan.
+ *
+ * `unknown` is a first-class answer, never a rounded-down `allow`: a layer that
+ * cannot be evaluated without executing something says so.
+ */
+export declare type PreflightVerdict = 'allow' | 'deny' | 'unknown';
+
 /**
  * Resolves a playbook to a plan for a caller on a given plane.
  *
@@ -342,4 +609,19 @@ export declare interface ResolvePlaybookOptions {
     intents?: PlaybookIntentResolver;
 }
 
+export declare interface ServerPreflightOptions {
+    /** `PrincipalRun.isToolAllowed` for the slug that gates this step. */
+    isToolAllowed(step: PlaybookOperationStep): boolean;
+    /**
+     * The operation-permission predicate. Evaluates the catalog gate for the
+     * step's `(collection, action)` without performing the operation.
+     */
+    checkOperationPermission(step: PlaybookOperationStep): PreflightVerdict | Promise<PreflightVerdict>;
+    /** Declared plane validity of a view intent, from the #2588 registry. */
+    intentPlanes?(id: string): readonly PlaybookPlane[] | null | undefined;
+}
+
+/** Fail-closed combination: `deny` beats `unknown` beats `allow`. */
+export declare function worstVerdict(left: PreflightVerdict, right: PreflightVerdict): PreflightVerdict;
+
 export { }