@gnldev/server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+import { type FetchHandler } from './handler.js';
+import type { CreateGnlConfig, BudgetLimit, RunLimits } from '@gnldev/durable';
+import { type AuthProvider, type ReadWriteAuth, type Principal } from '@gnldev/auth';
+/**
+ * D4-FGA (EE-2): structural mirror of @gnldev/auth-ee's `FgaResource`/`FgaAction` — @gnldev/server does NOT
+ * depend on the paid @gnldev/auth-ee package, so these are typed here rather than imported (see
+ * `RestApiOptions.resourceAuth` below).
+ */
+export interface ResourceAuthResource {
+    type: 'agent' | 'workflow' | 'tool' | 'run';
+    id: string;
+}
+/**
+ * The verbs @gnldev/server ACTUALLY dispatches, and the ones it does not.
+ *
+ * DISPATCHED: `'run'` (agent run/stream/resume, workflow run) and `'cancel'` (run/workflow cancel).
+ *
+ * NOT DISPATCHED: `'read'`. It is kept in the union because the union is open (`string & {}`) and a
+ * host may dispatch its own verbs — but nothing in this package ever calls the gate with it, so a
+ * host that writes an `action === 'read'` branch gets a rule that never runs. That was measured as a
+ * real hazard rather than a cosmetic one: a signature that names a verb reads as a promise that the
+ * verb is checked, and the read paths are exactly where subject binding was missing
+ * (`subjectBinding`). Read authorisation lives there, not here.
+ *
+ * `'resume'` IS dispatched — but as `'run'`: resuming executes the agent and carries `approvals`,
+ * so denying `run` while allowing `resume` would be the wrong way round (see the resume endpoint's
+ * own note). The member stays for hosts that want to distinguish them in their own dispatch.
+ */
+export type ResourceAuthAction = 'run' | 'read' | 'cancel' | 'resume' | (string & {});
+/** Per-request multi-organization (opt-in): resolve organization from the request → journal is scoped to that organization. */
+export interface OrgOptions {
+    /** Resolve the organization from the request. If not given, the `x-gnl-org` header is read. */
+    /**
+     * Takes a web `Request`, not a Hono `Context` — kept in step with @gnldev/studio, and for the same
+     * reason: a host binding this handler from Express or Fastify has a Request and no Context.
+     */
+    resolve?: (req: Request) => string | undefined | Promise<string | undefined>;
+    /** true → a request without an organization gets 400. false (default) → a request without an organization runs in the shared scope. */
+    required?: boolean;
+    /**
+     * HARDENING (opt-in): reject any request whose resolved organization is NOT explicitly REGISTERED
+     * (an `__org__:<id>` record written by studio's `POST /organizations`; a DELETED org is a `null`
+     * tombstone → also rejected → its ghost tokens stop working). Default false = the legacy IMPLICIT-org
+     * behavior (an org springs into existence on first activity, no registration needed) — byte-for-byte
+     * unchanged. Turn ON for strict provisioning: only orgs you deliberately created may run. NOTE: requires
+     * a registration PATH in the deployment (studio's org management, or a direct `__org__:<id>` write);
+     * with it on and no such path, every org-scoped request is rejected. */
+    requireRegistration?: boolean;
+    /**
+     * Ceiling on how many per-organization registries are held in memory at once (default 512).
+     *
+     * The cache is keyed by the RESOLVED organization id, and with `requireRegistration` off — the
+     * default — that id is whatever `resolve` returned, i.e. the `x-gnl-org` header. Every distinct
+     * value built a full `createGnl` registry and kept it forever, so a loop over random header values
+     * grew the process until it died. Nothing in the request has to be valid for that: an unregistered
+     * org is served, and serving it is what allocates.
+     *
+     * Least-recently-used entries are evicted past the cap. Eviction is state-preserving, and the parts
+     * that could have made it otherwise were measured rather than assumed: an instance is a CACHE over
+     * the org-scoped journal (memory comes from `memoryFactory(scoped)`, the frozen model spec lives in
+     * the journal), `createGnl` opens no connections and starts no timers, the rebuild re-derives
+     * `withOrg(base, id)` without double-scoping the key prefix, and cancellation is unaffected because
+     * `inflight` hangs off the API closure keyed `org:<id>:<runId>` — not off the instance — so the key
+     * survives a rebuild.
+     *
+     * The one exception is a `memoryFactory` that IGNORES its argument and returns a process-local store.
+     * That is a split rather than a loss: an in-flight run holds the evicted instance by reference, so
+     * for a window one organization has two live stores and half a conversation lands in the one nothing
+     * will read again. A factory that uses the journal it is handed — which is why it is handed one —
+     * has no such window.
+     *
+     * Raise it if you legitimately serve more than 512 organizations from one process and want them all
+     * warm. A non-integer or a value below 1 is REJECTED at construction, `Infinity` included: the growth
+     * this bounds is reachable by anyone who can send a header, so opting out of the bound is not a
+     * setting, and a negative one used to spin the eviction loop forever.
+     */
+    maxInstances?: number;
+}
+export interface RestApiOptions {
+    /** OpenAPI title. */
+    title?: string;
+    /**
+     * Optional auth (opt-in). If not given, all endpoints are OPEN (existing behavior). Accepts an
+     * AuthProvider (@gnldev/auth or the paid @gnldev/auth-ee) or a backward-compatible {read,write} predicate pair.
+     * GET → read, POST → write.
+     */
+    auth?: AuthProvider | ReadWriteAuth;
+    /**
+     * Who a request is allowed to speak FOR, on the read paths.
+     *
+     * `'declared'` (default, today's behaviour): the expectation comes only from what the CALLER
+     * states (`?resourceId=` or the body). State nobody and nothing is checked — the rule was written
+     * for operators, who work across an organization by design and name nobody.
+     *
+     * `'strict'`: an authenticated NON-OPERATOR identity speaks for ITSELF. `principal.id` becomes the
+     * expectation and a caller-supplied name cannot replace it.
+     *
+     * WHY THE OPTION EXISTS RATHER THAN A STRAIGHT FIX. Measured on a deployment that hands user-store
+     * tokens to end users: `mallory` read `GET /threads` (the whole subject inventory), then
+     * `/threads/t-ayse/messages` (`AYSE-SECRET`), then `/runs/r-ayse` (the full journal) — all 200,
+     * and naming someone else explicitly was 200 as well. The same identity is a SUBJECT when it
+     * writes (`resolveResourceId`) and an OPERATOR when it reads; that asymmetry is the hole.
+     *
+     * It is not flipped by default because doing so turns today's 200s into 403s for every deployment
+     * whose operators read across their organization — which is the documented, intended use. The flag
+     * lets a deployment that gives end users tokens close the hole now; the default follows once the
+     * operator/end-user split has a first-class shape.
+     */
+    subjectBinding?: 'declared' | 'strict';
+    /**
+     * DELIBERATE permission for a provider-less API in production. Auth remains opt-in; but in
+     * NODE_ENV=production, calling createRestApi without `auth` throws a setup ERROR — silent fail-open is
+     * disabled (audit #2). Set this flag to true if open access is genuinely intended. Outside production:
+     * only a single console.warn on the first request.
+     */
+    allowOpenAccess?: boolean;
+    /**
+     * Opt-in multi-organization support: each request descends into that organization's journal (withOrg)
+     * → runs, memory, and exactly-once guarantees are isolated per organization. The resolved organization
+     * is injected into requestContext as `org` (visible to dynamic agents). The registry is lazily built
+     * and cached per organization.
+     */
+    org?: OrgOptions;
+    /**
+     * Budget/quota FALLBACK limits (ENFORCED on the write path): an organization's effective limit is
+     * journal's `__budget__:<id>`/`__budget__:default` (managed from Studio) > `perOrg[id]` > `default`.
+     * A new run/stream/workflow request from an organization that is over budget gets 402 (resume remains
+     * free — suspended work can finish). Even without this option, budgets written to the journal are
+     * enforced (no limit → cost-free early exit).
+     */
+    budgets?: {
+        default?: BudgetLimit;
+        perOrg?: Record<string, BudgetLimit>;
+    };
+    /**
+     * SERVER-SIDE UPPER BOUND (opt-in) for per-run cost cap + loop detection. The `limits` in the
+     * request body (client request) CANNOT EXCEED this cap — the effective limit for each field is computed
+     * as `min(server, client)` (see `clampLimits`); if the client doesn't specify a field, the server cap
+     * applies, and if neither server nor client specifies it, that field is never enforced. If neither is
+     * given (default), behavior is preserved EXACTLY AS IS (unlimited).
+     */
+    limits?: RunLimits;
+    /**
+     * (audit: A2A unsigned) — opt-in A2A request verification: if given, the `x-gnl-signature`/
+     * `x-gnl-timestamp` header pair produced by `@gnldev/a2a`'s `createA2ATool({ secret })` becomes REQUIRED on
+     * `/agents/:name/run` POSTs (see verifyA2ASignature) — missing/wrong signature or a timestamp outside
+     * ±300s → 401. If not given, behavior is preserved EXACTLY AS IS (unsigned requests are accepted as
+     * before). Works TOGETHER WITH the existing auth gate (opts.auth) — the two are independent layers,
+     * both must pass.
+     */
+    a2aSecret?: string;
+    /**
+     * D4-FGA (EE-2) opt-in hook: fine-grained (resource-scoped) authorization, consulted AFTER the existing
+     * coarse gate (opts.auth) already allowed the request — on agents run/stream, workflows run, and the
+     * two cancel endpoints (`/runs/:id/cancel`, `/workflows/runs/:id/cancel`). A denial → 403
+     * `{error, code: 'resource_denied'}`, distinct from the coarse gate's 403 (which carries no `code`).
+     * Structurally typed (`ResourceAuthResource`/`ResourceAuthAction` above) — @gnldev/server does NOT import
+     * @gnldev/auth-ee; an EE user wires this to `createEnterpriseAuth(...).checkResource` (see @gnldev/auth-ee's
+     * `createFga`/`EnterpriseAuthProvider.checkResource`), e.g.:
+     *   resourceAuth: (p, r, a) => enterpriseAuth.checkResource!(p, r, a).then((res) => res.allowed)
+     * If NOT given, behavior is preserved EXACTLY AS IS (no resource-level gate — existing coarse auth only).
+     */
+    resourceAuth?: (principal: Principal | null, resource: ResourceAuthResource, action: ResourceAuthAction) => Promise<boolean> | boolean;
+    /**
+     * Agent approval registry (opt-in governance gate, default false — BACKWARD COMPAT: existing
+     * deployments are byte-for-byte unchanged). When true, run/resume/stream ALSO require the target
+     * agent to be `approved` in the journal-backed registry (@gnldev/durable's `isAgentServable`) — a
+     * pending/changed/blocked agent gets 403 `{error, code: 'agent_not_approved'}`. Every `config.agents`
+     * entry is recorded (idempotent, fingerprinted) once at construction so a platform-admin can review
+     * it via `GET /agents/registry` and approve/block it (see the `/agents/registry*` endpoints below) —
+     * those endpoints are ALWAYS available (regardless of this flag) so approval can be set up ahead of
+     * turning the gate on.
+     */
+    requireAgentApproval?: boolean;
+    /**
+     * The startup protection matrix (default ON). Set false when something ELSE is already printing
+     * one for this config.
+     *
+     * That is not hypothetical: `gnl dev` mounts this host and prints its own matrix, and its version
+     * knows one thing this one cannot — that the dev server DERIVES a memory store the project's
+     * `src/app.ts` will not have. Two blocks describing the same config, one of them less informed, is
+     * how a reader learns to skip both. This flag exists so there is exactly one.
+     *
+     * It is an opt-OUT rather than an opt-in on purpose: the matrix is most needed by the deployment
+     * that has not thought about any of these rows.
+     */
+    protectionsBanner?: boolean;
+}
+/** Leak-free metadata from agent records (the model object is hidden → only string id / 'custom'). */
+export interface AgentMeta {
+    name: string;
+    model: string;
+    system?: string;
+    hasTools: boolean;
+    maxSteps: number;
+    /** Orgs this org-scoped agent belongs to (UI label); undefined for global agents. */
+    orgs?: string[];
+}
+export type { FetchHandler, RouteInfo } from './handler.js';
+export { buildOpenApi } from './openapi.js';
+export { EDGE_ERROR_CODES, type EdgeErrorCode } from './edge-errors.js';
+export { pipeAgentStream, interruptsFromSteps, sseResponse } from './sse.js';
+/**
+ * The REST API as a fetch handler.
+ *
+ * Hono host:      app.mount('/api', createRestApi(config))
+ * Anything else:  bridge it (see @gnldev/studio/node for the same job on the Studio side)
+ * Standalone:     serve({ fetch: createRestApi(config).fetch })
+ *
+ * The `run?: never; agent?: never` is a guard, not decoration. Every field of `CreateGnlConfig` is
+ * optional, so ANY object satisfies it — including the REGISTRY that `createGnl(config)` returns,
+ * which is the one thing callers reach for by mistake (`createRestApi(gnl)` instead of
+ * `createRestApi(config)`). It typechecked, started, and then answered every request from an empty
+ * config: no agents, no journal, and nothing anywhere saying so. `run` and `agent` exist on the
+ * registry and on no config, so naming them `never` rejects exactly that object and costs a real
+ * config nothing. Documented because it was shipped wrong in the guide first, and because a
+ * signature that looks decorative is the kind that gets "simplified" away.
+ */
+export declare function createRestApi(config: CreateGnlConfig & {
+    run?: never;
+    agent?: never;
+}, opts?: RestApiOptions): FetchHandler;