@tangle-network/agent-app 0.1.0

package/dist/stream/index.js

@@ -0,0 +1,35 @@
+import {
+  asRecord,
+  asString,
+  buildUserTextParts,
+  encodeEvent,
+  finalizeAssistantParts,
+  getPartKey,
+  mergePersistedPart,
+  messageHasTurnId,
+  normalizeClientTurnId,
+  normalizePersistedPart,
+  normalizeTime,
+  normalizeToolEvent,
+  resolveChatTurn,
+  resolveToolId,
+  resolveToolName
+} from "../chunk-GMFPCCQZ.js";
+export {
+  asRecord,
+  asString,
+  buildUserTextParts,
+  encodeEvent,
+  finalizeAssistantParts,
+  getPartKey,
+  mergePersistedPart,
+  messageHasTurnId,
+  normalizeClientTurnId,
+  normalizePersistedPart,
+  normalizeTime,
+  normalizeToolEvent,
+  resolveChatTurn,
+  resolveToolId,
+  resolveToolName
+};
+//# sourceMappingURL=index.js.map

package/dist/stream/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/tangle/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Tangle login + the developer self-service app-registration → broker-token
+ * flow, for apps built on agent-app.
+ *
+ * The platform (agent-dev-container integration hub) lets a developer register
+ * their client app and obtain a `sk-tan-broker-` bearer to call `/v1/hub/exec`
+ * on a user's connected integrations — WITHOUT being a hard-coded "trusted app".
+ * The wire client (`TangleAppsClient` — registerApp / exchangeAuthCode /
+ * mintBrokerToken) lives in `@tangle-network/agent-integrations`; this module is
+ * the app-shell layer on top, and is intentionally **structural**: it depends on
+ * the minter CONTRACT, not the concrete client, so it installs without the
+ * agent-integrations publish and is trivially testable. A consumer constructs
+ * the real client and passes it in.
+ *
+ *   1. {@link buildConsentUrl} — send the user through the ONE-TIME consent
+ *      (their Tangle session authorizes the app for a connection + scopes).
+ *   2. On the callback, the consumer's client `exchangeAuthCode`s the `agc_`
+ *      code into the first broker token + a durable grant.
+ *   3. {@link createBrokerTokenProvider} — the runtime path: a cached provider
+ *      that re-mints a fresh single-use broker token per `/v1/hub/exec` from the
+ *      durable grant using only the app credentials (no user session). Caches
+ *      until just before expiry so a burst of hub calls shares one mint.
+ */
+/** A single-use hub bearer minted from a durable grant — mirrors
+ *  `@tangle-network/agent-integrations`'s `BrokerToken`. */
+interface BrokerToken {
+    /** The `sk-tan-broker-…` bearer for a single `/v1/hub/exec` call. */
+    accessToken: string;
+    /** Seconds until expiry. */
+    expiresIn: number;
+    scope: string;
+    connectionId?: string;
+}
+/** The one method the provider needs — `TangleAppsClient` satisfies it
+ *  structurally, so `createBrokerTokenProvider({ client: tangleAppsClient, … })`
+ *  type-checks without importing the concrete class. */
+interface BrokerTokenMinter {
+    mintBrokerToken(input: {
+        clientId: string;
+        clientSecret: string;
+        grantId: string;
+        ttlSeconds?: number;
+    }): Promise<BrokerToken>;
+}
+interface ConsentUrlInput {
+    /** Platform base URL (e.g. https://id.tangle.tools). */
+    endpoint: string;
+    clientId: string;
+    /** Must match one of the app's registered redirect URIs. */
+    redirectUri: string;
+    /** Scopes the app is requesting for this connection (e.g. ['gmail.read']). */
+    scopes: string[];
+    /** Opaque CSRF/state value the callback echoes back — verify it on return. */
+    state: string;
+    /** Optionally pre-select a specific connection to authorize. */
+    connectionId?: string;
+}
+/**
+ * Build the URL to send the user to for the one-time app-consent. The user's
+ * Tangle session (not the app's credentials) authorizes it; on approval the
+ * platform redirects to `redirectUri?code=agc_…&state=…`.
+ */
+declare function buildConsentUrl(input: ConsentUrlInput): string;
+interface BrokerTokenProviderOptions {
+    client: BrokerTokenMinter;
+    clientId: string;
+    clientSecret: string;
+    /** The durable grant id from the consent exchange. */
+    grantId: string;
+    /** Requested token TTL (seconds). */
+    ttlSeconds?: number;
+    /** Re-mint this many ms BEFORE expiry so an in-flight call never uses a
+     *  just-expired token. Default 30s. */
+    refreshSkewMs?: number;
+    /** Injectable clock (ms). Default `Date.now`. */
+    now?: () => number;
+}
+interface BrokerTokenProvider {
+    /** A valid `sk-tan-broker-` bearer, minting/refreshing as needed. */
+    getToken(): Promise<string>;
+    /** Force the next `getToken` to re-mint (e.g. after a 401 from the hub). */
+    invalidate(): void;
+}
+/**
+ * Cache + auto-refresh a broker token for one grant. A burst of hub calls
+ * shares a single mint; the token is re-minted once it's within `refreshSkewMs`
+ * of expiry, or on demand via {@link BrokerTokenProvider.invalidate}.
+ * Concurrent `getToken` calls during a mint share the same in-flight promise
+ * (no thundering herd).
+ */
+declare function createBrokerTokenProvider(opts: BrokerTokenProviderOptions): BrokerTokenProvider;
+
+export { type BrokerToken, type BrokerTokenMinter, type BrokerTokenProvider, type BrokerTokenProviderOptions, type ConsentUrlInput, buildConsentUrl, createBrokerTokenProvider };

package/dist/tangle/index.js

@@ -0,0 +1,9 @@
+import {
+  buildConsentUrl,
+  createBrokerTokenProvider
+} from "../chunk-YGUNTIT5.js";
+export {
+  buildConsentUrl,
+  createBrokerTokenProvider
+};
+//# sourceMappingURL=index.js.map

package/dist/tangle/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/tools/index.d.ts

@@ -0,0 +1,213 @@
+import { b as AppToolContext, f as AppToolTaxonomy, c as AppToolHandlers, e as AppToolProducedEvent, d as AppToolOutcome } from '../types-CeWor4bQ.js';
+export { A as AddCitationArgs, a as AddCitationResult, R as RenderUiArgs, g as RenderUiResult, S as ScheduleFollowupArgs, h as ScheduleFollowupResult, i as SubmitProposalArgs, j as SubmitProposalResult } from '../types-CeWor4bQ.js';
+
+/** A correctable bad-input error a tool handler throws; the HTTP layer maps it
+ *  to a 4xx with the code, the runtime layer to a failed tool_result. So the
+ *  agent learns the call failed and can correct, instead of a silent success. */
+declare class ToolInputError extends Error {
+    code: string;
+    status: number;
+    constructor(code: string, message: string, status?: number);
+}
+
+/**
+ * Per-user capability token — the sandbox→app auth primitive behind the
+ * `verifyToken` seam in {@link authenticateToolRequest}.
+ *
+ * An app-agent runs inside the sandbox and reaches the host app back over HTTP
+ * (the app tools, the integration-invoke bridge). The route must act AS the
+ * connecting user without trusting any model-supplied identity, so the turn
+ * mints a short HMAC token bound to the user id and bakes it into the per-turn
+ * MCP server header; the route verifies it to recover the user.
+ *
+ * `HMAC-SHA256(secret, "user:<userId>")`, base64url, with an app-chosen prefix.
+ * The token encodes no scopes — the hub's policy engine authorizes per action.
+ * Fail-closed: with no secret, no token is minted (the caller MUST omit the MCP
+ * server rather than fake an authorized call). WebCrypto only — runs on
+ * Workers, Node, and the browser with no Node `crypto` dependency.
+ */
+interface CapabilityTokenOptions {
+    /** Shared HMAC secret. When absent, mint returns undefined / verify returns false. */
+    secret?: string;
+    /** Token prefix (namespaces the credential; lets verify reject foreign tokens
+     *  cheaply). Default `cap_`. */
+    prefix?: string;
+}
+/** Mint a capability token for `userId`, or `undefined` when no secret is
+ *  configured (fail-closed — the caller omits the MCP server rather than fake it). */
+declare function createCapabilityToken(userId: string, opts: CapabilityTokenOptions): Promise<string | undefined>;
+/** Verify a capability token against `userId`. Returns false (never throws) for
+ *  an unconfigured secret, a wrong prefix, a malformed token, or a mismatch. */
+declare function verifyCapabilityToken(userId: string, token: string, opts: CapabilityTokenOptions): Promise<boolean>;
+
+/**
+ * Header names carrying the server-set per-turn context + the capability token.
+ * Defaults are product-neutral (`X-Agent-App-*`); a product that already ships
+ * a header convention (e.g. `X-Insurance-User-Id`) passes its own.
+ */
+interface ToolHeaderNames {
+    userId: string;
+    workspaceId: string;
+    threadId: string;
+}
+declare const DEFAULT_HEADER_NAMES: ToolHeaderNames;
+interface AuthenticateOptions {
+    /** Verify the bearer capability token belongs to `userId`. The product's
+     *  HMAC/JWT impl — the seam that keeps token crypto out of this package. */
+    verifyToken: (userId: string, bearer: string) => Promise<boolean>;
+    headerNames?: ToolHeaderNames;
+}
+type ToolAuthResult = {
+    ok: true;
+    ctx: AppToolContext;
+} | {
+    ok: false;
+    response: Response;
+};
+/**
+ * Recover + verify the trusted context for a tool request. The user comes from
+ * a server-set header and the bearer token MUST verify against THAT user; the
+ * workspace comes from a header too — never from tool args — so the model can
+ * neither forge identity nor target another workspace. Fail-closed: any missing
+ * credential or a token minted for another user yields a 401/400 Response.
+ */
+declare function authenticateToolRequest(request: Request, opts: AuthenticateOptions): Promise<ToolAuthResult>;
+/** Read a tool's argument object from the request body, tolerant of MCP host
+ *  aliases (`args` / `arguments`) or a bare body. Returns null on non-JSON. */
+declare function readToolArgs<T>(request: Request): Promise<T | null>;
+
+/** The four canonical app-tool names. Stable identifiers the model calls in
+ *  both the sandbox (MCP server name) and runtime (function-tool name) paths. */
+declare const APP_TOOL_NAMES: readonly ["submit_proposal", "schedule_followup", "render_ui", "add_citation"];
+type AppToolName = (typeof APP_TOOL_NAMES)[number];
+declare function isAppToolName(name: string): name is AppToolName;
+/** A minimal OpenAI Chat Completions function-tool shape — structurally
+ *  compatible with `@tangle-network/agent-runtime`'s `OpenAIChatTool` without
+ *  importing it (keeps this package runtime-free). */
+interface OpenAIFunctionTool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/**
+ * Build the four app tools in OpenAI function-tool shape. `submit_proposal`'s
+ * `type` enum is the product's {@link AppToolTaxonomy.proposalTypes}; the other
+ * three are fixed. Pass the result to the agent-runtime backend's `tools`.
+ */
+declare function buildAppToolOpenAITools(taxonomy: AppToolTaxonomy): OpenAIFunctionTool[];
+
+interface DispatchOptions {
+    handlers: AppToolHandlers;
+    taxonomy: AppToolTaxonomy;
+    /** Called at the real side-effect site for proposals (proposal_created) and
+     *  generated views (artifact) so a consumer's completion oracle credits
+     *  persisted state. Omit when produced state isn't tracked. */
+    onProduced?: (event: AppToolProducedEvent) => void;
+}
+/**
+ * The ONE place an app-tool call is validated, dispatched to the product's
+ * handler, and turned into an {@link AppToolOutcome} + produced events. Shared
+ * by the HTTP route layer and the agent-runtime executor so both paths apply
+ * identical validation and identical side effects. A {@link ToolInputError}
+ * (bad input the agent can correct) and any other throw both become
+ * `{ ok: false }` — a tool call never silently "succeeds" without its effect.
+ */
+declare function dispatchAppTool(toolName: string, rawArgs: Record<string, unknown>, ctx: AppToolContext, opts: DispatchOptions): Promise<AppToolOutcome>;
+/** HTTP status for a failed outcome — the handler's `ToolInputError.status`
+ *  when present, else 400 for a validation reject. */
+declare function outcomeStatus(outcome: Extract<AppToolOutcome, {
+    ok: false;
+}>): number;
+
+/** Executes an app-tool call the model emits on the agent-runtime chat path.
+ *  Plug into `runChatThroughRuntime({ appToolExecutor })` (or any loop that
+ *  dispatches function tool_calls). */
+type AppToolRuntimeExecutor = (call: {
+    toolName: string;
+    args: Record<string, unknown>;
+}) => Promise<AppToolOutcome>;
+interface RuntimeExecutorOptions extends DispatchOptions {
+    /** The trusted per-turn context — supplied directly (not from headers), since
+     *  the runtime path has no HTTP request. */
+    ctx: AppToolContext;
+}
+/**
+ * Build the runtime executor for one turn. The agent-runtime backend must also
+ * advertise the tools (`buildAppToolOpenAITools(taxonomy)` on the backend's
+ * `tools`) for the model to call them; this executor fulfils each call against
+ * the product's handlers and emits produced events via `opts.onProduced`.
+ */
+declare function createAppToolRuntimeExecutor(opts: RuntimeExecutorOptions): AppToolRuntimeExecutor;
+
+interface HandleToolRequestOptions extends DispatchOptions {
+    /** Which app tool this route serves. */
+    tool: AppToolName;
+    /** Verify the bearer capability token belongs to the header user. */
+    verifyToken: (userId: string, bearer: string) => Promise<boolean>;
+    headerNames?: ToolHeaderNames;
+    /** Optional success-message builder for a friendlier tool result. */
+    message?: (result: unknown) => string;
+}
+/**
+ * Handle one app-tool HTTP request end to end — the sandbox MCP path. The
+ * agent's per-turn HTTP MCP server POSTs here; this authenticates (header user
+ * + capability token), reads the args (MCP-alias tolerant), dispatches to the
+ * product handler, and returns a JSON Response. A product's route file becomes
+ * a one-liner: `export const action = ({ request }) => handleAppToolRequest(request, cfg)`.
+ */
+declare function handleAppToolRequest(request: Request, opts: HandleToolRequestOptions): Promise<Response>;
+
+/** Default route path each app tool is served at. A product mounts its routes
+ *  at these paths (or supplies its own via {@link BuildMcpServerOptions.paths}). */
+declare const DEFAULT_APP_TOOL_PATHS: Record<AppToolName, string>;
+/** The portable MCP server entry the sandbox SDK accepts (transport + url +
+ *  headers). Matches `AgentProfileMcpServer` structurally without importing the
+ *  sandbox SDK — products spread it into their profile's `mcp` map. */
+interface AppToolMcpServer {
+    transport: 'http';
+    url: string;
+    headers: Record<string, string>;
+    enabled: true;
+    metadata: {
+        description: string;
+    };
+}
+interface BuildHttpMcpServerOptions {
+    /** Route path on the app the sandbox POSTs to (e.g. `/api/tools/propose`). */
+    path: string;
+    /** App base URL the sandbox reaches back to (no trailing slash required). */
+    baseUrl: string;
+    /** Per-user capability token, baked into the Authorization header. */
+    token: string;
+    ctx: AppToolContext;
+    /** Tool description the model sees. */
+    description: string;
+    headerNames?: ToolHeaderNames;
+}
+/**
+ * Build ONE HTTP MCP server entry — the generic agent→app bridge. The
+ * capability token + the user/workspace/thread ids ride in server-set headers
+ * (never tool args), so the model can't forge identity or target another
+ * workspace. Workspace/thread headers are omitted when their `ctx` value is
+ * empty/null (e.g. an integration-invoke bridge that's user-scoped only). Used
+ * directly for non-app-tool bridges (integration_invoke) and via
+ * {@link buildAppToolMcpServer} for the four app tools.
+ */
+declare function buildHttpMcpServer(opts: BuildHttpMcpServerOptions): AppToolMcpServer;
+interface BuildMcpServerOptions {
+    tool: AppToolName;
+    baseUrl: string;
+    token: string;
+    ctx: AppToolContext;
+    description: string;
+    headerNames?: ToolHeaderNames;
+    paths?: Partial<Record<AppToolName, string>>;
+}
+/** Build one of the four app-tool MCP servers — a thin wrapper over
+ *  {@link buildHttpMcpServer} that maps the tool name to its route path. */
+declare function buildAppToolMcpServer(opts: BuildMcpServerOptions): AppToolMcpServer;
+
+export { APP_TOOL_NAMES, AppToolContext, AppToolHandlers, type AppToolMcpServer, type AppToolName, AppToolOutcome, AppToolProducedEvent, type AppToolRuntimeExecutor, AppToolTaxonomy, type AuthenticateOptions, type BuildHttpMcpServerOptions, type BuildMcpServerOptions, type CapabilityTokenOptions, DEFAULT_APP_TOOL_PATHS, DEFAULT_HEADER_NAMES, type DispatchOptions, type HandleToolRequestOptions, type OpenAIFunctionTool, type RuntimeExecutorOptions, type ToolAuthResult, type ToolHeaderNames, ToolInputError, authenticateToolRequest, buildAppToolMcpServer, buildAppToolOpenAITools, buildHttpMcpServer, createAppToolRuntimeExecutor, createCapabilityToken, dispatchAppTool, handleAppToolRequest, isAppToolName, outcomeStatus, readToolArgs, verifyCapabilityToken };

package/dist/tools/index.js

@@ -0,0 +1,37 @@
+import {
+  APP_TOOL_NAMES,
+  DEFAULT_APP_TOOL_PATHS,
+  DEFAULT_HEADER_NAMES,
+  ToolInputError,
+  authenticateToolRequest,
+  buildAppToolMcpServer,
+  buildAppToolOpenAITools,
+  buildHttpMcpServer,
+  createAppToolRuntimeExecutor,
+  createCapabilityToken,
+  dispatchAppTool,
+  handleAppToolRequest,
+  isAppToolName,
+  outcomeStatus,
+  readToolArgs,
+  verifyCapabilityToken
+} from "../chunk-EDIQ6F55.js";
+export {
+  APP_TOOL_NAMES,
+  DEFAULT_APP_TOOL_PATHS,
+  DEFAULT_HEADER_NAMES,
+  ToolInputError,
+  authenticateToolRequest,
+  buildAppToolMcpServer,
+  buildAppToolOpenAITools,
+  buildHttpMcpServer,
+  createAppToolRuntimeExecutor,
+  createCapabilityToken,
+  dispatchAppTool,
+  handleAppToolRequest,
+  isAppToolName,
+  outcomeStatus,
+  readToolArgs,
+  verifyCapabilityToken
+};
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-CeWor4bQ.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The structured agent→app tool side channel, domain-seamed.
+ *
+ * Every Tangle agent product needs the same thing: a way for the in-sandbox
+ * agent to reach the host app with a STRUCTURED, validated tool call (not a
+ * fenced `:::` block scraped from prose). Four canonical tools cover it:
+ *
+ *   - `submit_proposal`   — route a regulated/state-changing action to a human
+ *                           approval queue (the human-in-the-loop gate).
+ *   - `schedule_followup` — register a dated cadence step (executes immediately).
+ *   - `render_ui`         — persist a generated view as an artifact (immediate).
+ *   - `add_citation`      — anchor a grounding reference (immediate).
+ *
+ * The shapes, validation, OpenAI tool definitions, MCP-server wiring, HTTP
+ * route handling, and runtime-loop executor are GENERIC and live here. The
+ * persistence (which DB, which tables) and the product's proposal taxonomy are
+ * the DOMAIN SEAM: each product supplies {@link AppToolHandlers} +
+ * {@link AppToolTaxonomy}. This package imports no product code and no agent
+ * runtime — it depends only on the Web `Request`/`Response` types.
+ */
+/** Server-set, trusted per-turn context. Recovered from request headers (HTTP
+ *  path) or supplied directly (runtime path) — never from model tool args, so
+ *  the model cannot forge identity or target another workspace. */
+interface AppToolContext {
+    userId: string;
+    workspaceId: string;
+    threadId: string | null;
+}
+/** The product's proposal taxonomy — the only domain-specific vocabulary the
+ *  generic layer needs (to validate `submit_proposal.type` and label the
+ *  regulated subset). */
+interface AppToolTaxonomy {
+    /** Every accepted proposal type. */
+    proposalTypes: readonly string[];
+    /** The subset that cannot execute without a named certified human (regulated
+     *  steps). Used only to label the tool result; enforcement is the product's
+     *  approval executor. */
+    regulatedTypes: readonly string[];
+}
+interface SubmitProposalArgs {
+    type: string;
+    title: string;
+    description?: string | null;
+}
+interface SubmitProposalResult {
+    proposalId: string;
+    /** True when an identical (workspace, title) proposal already existed. */
+    deduped: boolean;
+}
+interface ScheduleFollowupArgs {
+    title: string;
+    dueDate: string;
+    priority?: string;
+}
+interface ScheduleFollowupResult {
+    id: string;
+    dueDate: string;
+    deduped: boolean;
+}
+interface RenderUiArgs {
+    title: string;
+    schema: unknown;
+}
+interface RenderUiResult {
+    /** The persisted artifact path. */
+    path: string;
+    /** The exact persisted body — surfaced as the `artifact` produced event so a
+     *  consumer's completion oracle sees the real content. */
+    content: string;
+}
+interface AddCitationArgs {
+    path: string;
+    quote: string;
+    label?: string;
+}
+interface AddCitationResult {
+    citationId: string;
+    path: string;
+}
+/**
+ * The domain seam. Each product implements these against its own D1/KV/vault.
+ * A handler MAY throw {@link ToolInputError} for correctable bad input (mapped
+ * to a 4xx / failed tool_result); any other throw is an internal error.
+ * `submitProposal` is the only handler whose result feeds the approval queue;
+ * the others execute immediately.
+ */
+interface AppToolHandlers {
+    submitProposal(args: SubmitProposalArgs, ctx: AppToolContext): Promise<SubmitProposalResult>;
+    scheduleFollowup(args: ScheduleFollowupArgs, ctx: AppToolContext): Promise<ScheduleFollowupResult>;
+    renderUi(args: RenderUiArgs, ctx: AppToolContext): Promise<RenderUiResult>;
+    addCitation(args: AddCitationArgs, ctx: AppToolContext): Promise<AddCitationResult>;
+}
+/** Produced-state events the runtime executor emits at the real side-effect
+ *  site, so a consumer's eval/completion oracle credits a persisted proposal or
+ *  artifact. Deliberately substrate-free (no RuntimeStreamEvent import); the
+ *  consumer maps these onto its own telemetry shape. */
+type AppToolProducedEvent = {
+    type: 'proposal_created';
+    proposalId: string;
+    title: string;
+    status: 'pending';
+} | {
+    type: 'artifact';
+    path: string;
+    content: string;
+};
+/** Outcome of one tool dispatch — structurally compatible with the integration
+ *  tool-outcome union the agent-runtime chat loop already folds into a
+ *  tool_result. */
+type AppToolOutcome = {
+    ok: true;
+    result: unknown;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    status?: number;
+};
+
+export type { AddCitationArgs as A, RenderUiArgs as R, ScheduleFollowupArgs as S, AddCitationResult as a, AppToolContext as b, AppToolHandlers as c, AppToolOutcome as d, AppToolProducedEvent as e, AppToolTaxonomy as f, RenderUiResult as g, ScheduleFollowupResult as h, SubmitProposalArgs as i, SubmitProposalResult as j };

package/dist/web/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Web-boundary utilities every agent app's routes hand-roll: JSON body parsing
+ * + narrowing, request-context extraction (real client IP behind Cloudflare),
+ * a KV-backed sliding-window rate limiter, and security response headers. Pure
+ * mechanism — no DB, no domain. The KV is a structural interface so this needs
+ * no `@cloudflare/workers-types` dependency.
+ */
+type JsonObject = Record<string, unknown>;
+/** Parse + object-narrow a Request body. `[body, null]` on success, `[null,
+ *  errorResponse]` on a non-object body (callers `if (err) return err`). */
+declare function parseJsonObjectBody(request: Request): Promise<[JsonObject, null] | [null, Response]>;
+/** Narrow one required string field, 400 if missing/empty. */
+declare function requireString(body: JsonObject, field: string): string | Response;
+interface RequestContext {
+    ipAddress: string;
+    userAgent: string;
+    timestamp: string;
+    requestId: string;
+}
+/** Extract request context for audit trails. Uses `CF-Connecting-IP` for the
+ *  real client IP behind Cloudflare. */
+declare function extractRequestContext(request: Request): RequestContext;
+/** Minimal KV contract (Cloudflare `KVNamespace` satisfies it structurally). */
+interface KvLike {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+}
+interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetAt: number;
+}
+/** KV-backed sliding-window rate limit. Stores recent timestamps per key,
+ *  prunes the window, allows until `limit` is hit. */
+declare function checkRateLimit(kv: KvLike, key: string, limit: number, windowSeconds: number): Promise<RateLimitResult>;
+interface SecurityHeaderOptions {
+    /** Product disclaimer (e.g. "AI-powered tool. Not legal advice."). Omitted if absent. */
+    disclaimer?: string;
+    /** Data-retention label (e.g. "7-years"). Omitted if absent. */
+    retention?: string;
+    /** Extra headers to set. */
+    extra?: Record<string, string>;
+}
+/** Set standard security headers on a response (HSTS, nosniff, frame-options,
+ *  referrer-policy, XSS) + optional product disclaimer/retention. The security
+ *  set is generic; the disclaimer/retention are the product's. */
+declare function addSecurityHeaders(response: Response, opts?: SecurityHeaderOptions): Response;
+
+export { type JsonObject, type KvLike, type RateLimitResult, type RequestContext, type SecurityHeaderOptions, addSecurityHeaders, checkRateLimit, extractRequestContext, parseJsonObjectBody, requireString };

package/dist/web/index.js

@@ -0,0 +1,15 @@
+import {
+  addSecurityHeaders,
+  checkRateLimit,
+  extractRequestContext,
+  parseJsonObjectBody,
+  requireString
+} from "../chunk-CN75FIPT.js";
+export {
+  addSecurityHeaders,
+  checkRateLimit,
+  extractRequestContext,
+  parseJsonObjectBody,
+  requireString
+};
+//# sourceMappingURL=index.js.map

package/dist/web/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}