@spfn/core 0.3.0-beta.2 → 0.3.0-beta.21

package/dist/surface/index.d.ts

@@ -0,0 +1,115 @@
+import { MiddlewareHandler } from 'hono';
+import { a as NamedMiddleware } from '../define-middleware-CVKgqo8S.js';
+import { R as RouteDef } from '../route-builder-DRW-MSCJ.js';
+import { R as Router } from '../router-4YoIy5fN.js';
+import { c as SurfaceRouteBuilder, d as SurfaceCommand, b as SurfaceModule } from '../error-TsUIjp_x.js';
+export { S as SurfaceEffect, g as SurfaceError, e as SurfaceManifest, a as SurfaceModuleCommand, f as SurfaceModuleDescriptor, h as collectSurfaceCommands, i as defineSurfaceModule } from '../error-TsUIjp_x.js';
+import '@sinclair/typebox';
+import 'hono/utils/http-status';
+import '../route/types.js';
+import '../types-5Rl11_Nb.js';
+
+/**
+ * Command Surface
+ *
+ * A namespace of commands an app exposes to a caller that is not its own
+ * frontend — operators on `/_ops`, an issuer's signed tokens on `/_app`, any
+ * other machine caller on a namespace the app picks. An app develops the
+ * commands as ordinary routes; `defineSurface` turns them into a mountable
+ * package router that:
+ *
+ * - requires every route to carry the surface's namespace, applied by the
+ *   surface's own `route`, so a command is recognizable by its path and can
+ *   never shadow an app route;
+ * - injects the given auth middleware into every command, so a command
+ *   reachable without authentication cannot be created by accident — there is
+ *   no opt-out;
+ * - serves `GET <namespace>/_manifest`, the self-description a client
+ *   discovers commands from, registered first so no command takes its URL.
+ *   The manifest is the one route that may be public, and only when the
+ *   surface says so: its commands stay behind auth regardless.
+ *
+ * What the path looks like after the namespace is the app's business, decided
+ * when the route is written — this factory does not audit its shape.
+ *
+ * The auth middleware lives with the app's auth stack (`@spfn/auth` ships
+ * `opsTokenAuth` and `signedTokenAuth`); core owns only the structure, so a
+ * surface has no opinion about how a credential is stored or verified.
+ * `@spfn/core/ops` is this factory fixed to `/_ops`.
+ *
+ * @example
+ * ```ts
+ * import { defineSurface } from '@spfn/core/surface';
+ * import { signedTokenAuth } from '@spfn/auth/server';
+ *
+ * export const app = defineSurface({
+ *     namespace: '/_app',
+ *     auth: signedTokenAuth({ keysUrl, iss, aud }),
+ *     manifest: 'public',
+ * });
+ *
+ * export const pageAdd = app.route.post('/pages')     // POST /_app/pages
+ *     .input({ body: PageAddBody })
+ *     .handler(async (c) => pagesRepository.add((await c.data()).body));
+ *
+ * // mounted like any package router, beside `/_ops`:
+ * export const appRouter = defineRouter({ ... }).packages([app.router({ pageAdd }), opsRouter]);
+ * ```
+ */
+
+type SurfaceMiddleware = NamedMiddleware<string> | MiddlewareHandler;
+/**
+ * Build the guard for one command, or `undefined` for none. Called once per
+ * command when the router is built; the guard runs after `auth` and before the
+ * command's own middlewares.
+ *
+ * The command is the manifest entry, so its `effect` is there to read — a
+ * guard can be stricter for a `destructive` command than for a `read`.
+ */
+type SurfaceAuthorize = (command: SurfaceCommand) => SurfaceMiddleware | undefined;
+interface SurfaceOptions {
+    /** Every command lives under it, e.g. `/_app`. Must be a plain absolute path. */
+    namespace: string;
+    /**
+     * The middleware that authenticates every command. Required — a surface
+     * without authentication is refused at definition time, not discovered in
+     * production.
+     */
+    auth: NamedMiddleware<string>;
+    /** Per-command guard. Required when modules are mounted. */
+    authorize?: SurfaceAuthorize;
+    /**
+     * `'authenticated'` (default): the manifest carries `auth` like every
+     * command. `'public'`: it carries none and skips a global `auth`
+     * middleware, so a caller can discover commands before it holds a token.
+     */
+    manifest?: 'authenticated' | 'public';
+    /** Capability modules this application explicitly chooses to expose here. */
+    modules?: readonly SurfaceModule[];
+}
+interface Surface {
+    /** The validated namespace, as given. */
+    readonly namespace: string;
+    /** `route` with the namespace applied. */
+    readonly route: SurfaceRouteBuilder;
+    /**
+     * Build the unmapped package router: the manifest first, then the
+     * secured commands, then the secured module commands.
+     */
+    router<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>>(routes: TRoutes): Router<any>;
+}
+/**
+ * Define a command surface on a namespace.
+ *
+ * The namespace, the auth middleware, and the `authorize` requirement are
+ * checked here; routes and modules when `router()` builds the package router.
+ * Every app command must declare its effect with
+ * `.effect('read' | 'write' | 'destructive')` — `router()` refuses one that
+ * does not, so a client is never handed a command it cannot classify.
+ * The router is an ordinary `Router` meant to be mounted with `.packages()`,
+ * so its routes stay out of the app's client types exactly like other
+ * package routes.
+ */
+declare function defineSurface(options: SurfaceOptions): Surface;
+
+export { type Surface, type SurfaceAuthorize, SurfaceCommand, SurfaceModule, type SurfaceOptions, SurfaceRouteBuilder, defineSurface };