@devorash/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,279 @@
+# @devorash/node
+
+Recording, masking and activity preferences are configured in Devora Settings.
+SDK initialization overrides are ignored. New sessions retain the server's policy
+snapshot across exchange and resume. Developer privacy labels take effect only
+when selected in Settings; sensitive-field protection remains mandatory.
+See [migration details](https://github.com/getdevora/devora-sdks/blob/main/SETTINGS.md).
+
+Devora Backend SDK for Node.js applications. Enables secure impersonation by providing endpoints that the Devora platform can communicate with.
+
+## Installation
+
+```bash
+npm install @devorash/node
+# or
+bun add @devorash/node
+```
+
+## Quick Start
+
+```typescript
+import { devoraSDK, DEVORA_ENDPOINTS } from "@devorash/node"
+
+// Initialize SDK with your server key ID and secret key
+const sdk = devoraSDK({
+	apiKey: process.env.DEVORA_API_KEY!,
+	secretKey: process.env.DEVORA_SECRET_KEY!,
+	orgId: "your-org-id",
+	debug: process.env.NODE_ENV === "development",
+})
+
+// User search endpoint
+sdk.register(DEVORA_ENDPOINTS.USER_SEARCH, async (req) => {
+	const { term } = req.query
+	const users = await searchYourUsers(term)
+	return {
+		users: users.map((u) => ({
+			id: u.id,
+			email: u.email,
+			name: u.name,
+		})),
+	}
+})
+
+// Impersonation start endpoint
+sdk.register(DEVORA_ENDPOINTS.IMPERSONATE, async (req) => {
+	const { id } = req.params
+	const { targetUser } = req.devoraContext!
+
+	// Generate a short-lived app token for the target user.
+	const token = await generateAuthToken(targetUser.id)
+
+	// Optionally include user settings for frontend initialization.
+	const userSettings = await getUserSettings(id)
+
+	return {
+		token,
+		data: {
+			theme: userSettings.theme,
+			timezone: userSettings.timezone,
+		},
+	}
+})
+
+// Session termination endpoint
+sdk.register(DEVORA_ENDPOINTS.TERMINATE, async (req) => {
+	const { id } = req.params
+	const sessionId = req.sessionId ?? id
+
+	await invalidateUserSession(id, sessionId)
+
+	return { success: true }
+})
+
+export { sdk }
+```
+
+## Framework Integration
+
+Use the SDK with your preferred web framework:
+
+### Express
+
+```bash
+npm install @devorash/express
+```
+
+```typescript
+import express from "express"
+import { expressAdapter } from "@devorash/express"
+import { sdk } from "./devora"
+
+const app = express()
+app.use("/devora", expressAdapter(sdk))
+app.use(express.json()) // Parsers for other routes come afterwards.
+```
+
+### Hono
+
+```bash
+npm install @devorash/hono
+```
+
+```typescript
+import { Hono } from "hono"
+import { honoAdapter } from "@devorash/hono"
+import { sdk } from "./devora"
+
+const app = new Hono()
+app.route("/devora", honoAdapter(sdk))
+```
+
+### Fastify
+
+```bash
+npm install @devorash/fastify
+```
+
+```typescript
+import Fastify from "fastify"
+import { fastifyAdapter } from "@devorash/fastify"
+import { sdk } from "./devora"
+
+const server = Fastify()
+server.register(fastifyAdapter(sdk), { prefix: "/devora" })
+```
+
+## Configuration
+
+```typescript
+const sdk = devoraSDK({
+	// Required
+	apiKey: "pk_server_live_xxx", // Your public server key ID
+	secretKey: "sk_server_live_xxx", // Your server secret key
+	orgId: "org_xxx", // Your organization ID
+
+	// Optional
+	debug: false, // Enable debug logging
+	timestampTolerance: 300, // Max clock drift in seconds (default: 5 min)
+	collectStats: false, // Collect request statistics
+	logRequests: false, // Log all requests
+	logger: customLogger, // Custom logger implementation
+})
+```
+
+## Built-in Endpoints
+
+The SDK automatically provides two built-in endpoints:
+
+### `/test` - Connection Test
+
+Used by the Devora platform to verify your integration is working.
+
+```
+GET /devora/test
+```
+
+### `/health` - Health Check
+
+Returns SDK health information and registered endpoints.
+
+```
+GET /devora/health
+```
+
+## Security
+
+Every request from Devora is signed with HMAC-SHA256 (request signing v3). The
+signature covers the exact path, query and body bytes, the request's direction,
+a timestamp and a single-use request id. The adapters verify it before any route
+lookup and reject unsigned, altered, stale or replayed requests. See
+[SIGNING.md](../SIGNING.md) for the protocol and the replay-store contract.
+
+Production deployments need a shared, atomic `replayStore`: every instance
+must see every request id, and the insert must be atomic. The in-memory store
+is for `environment: "development"` or `"test"` only; any other environment
+refuses to start without a `replayStore`.
+
+```typescript
+import { createClient } from "redis"
+import { devoraSDK, type ReplayStore } from "@devorash/node"
+
+const redis = await createClient({ url: process.env.REDIS_URL }).connect()
+
+const replayStore: ReplayStore = {
+	async consume(namespace, requestId, expiresAt) {
+		// Atomic insert-if-absent that lives until expiresAt (Unix ms).
+		// Errors propagate: the SDK then fails closed with a 503.
+		const result = await redis.set(`devora:replay:${namespace}:${requestId}`, "1", {
+			NX: true,
+			PXAT: expiresAt,
+		})
+		return result === "OK"
+	},
+}
+
+const sdk = devoraSDK({
+	apiKey: process.env.DEVORA_API_KEY!,
+	secretKey: process.env.DEVORA_SECRET_KEY!,
+	orgId: process.env.DEVORA_ORG_ID!,
+	replayStore,
+})
+```
+
+Do not run the store with an eviction policy that can drop keys before they
+expire (`maxmemory-policy` must not evict these keys). A unique-key database
+insert with an expiry column works too.
+
+## Types
+
+```typescript
+import type {
+	DevoraRequest,
+	DevoraResponse,
+	DevoraUser,
+	ImpersonationStartRequest,
+	ImpersonationStartResponse,
+} from "@devorash/node"
+
+// Request handler with types
+sdk.register<
+	DevoraRequest<{ id: string }, {}, ImpersonationStartRequest>,
+	ImpersonationStartResponse
+>(DEVORA_ENDPOINTS.IMPERSONATE, async (req) => {
+	const { id } = req.params
+	const { scope, expiresAt, sessionId } = req.devoraContext!
+	return { token: "...", data: {} }
+})
+```
+
+## API Reference
+
+### `devoraSDK(config)`
+
+Create a new SDK instance.
+
+### `sdk.register(path, handler, options?)`
+
+Register an endpoint handler.
+
+### `sdk.getRoutes()`
+
+Get all registered routes.
+
+### `sdk.getStats()`
+
+Get request statistics (if `collectStats: true`).
+
+### `sdk.verifyRequest({ method, path, query, body, headers }, options?)`
+
+Verify a signed request from Devora over its exact wire bytes: `path` is
+relative to the SDK mount and still percent-encoded, `query` is everything
+after the first `?`, and `body` is a `Uint8Array`. The adapters call this for
+you; use it only for a custom framework integration.
+
+## License
+
+MIT
+
+## Request body limits
+
+Mount Express SDK routes before application-wide body parsers. The router and
+middleware include a bounded JSON parser (1 MiB by default, configurable through
+`maxBodySize`); compressed request bodies are rejected. The browser-session
+handler uses a 4 KiB limit. A parser placed earlier can already have allocated the
+entire body, so its own limit must be at least as strict for these routes.
+
+For direct `processRequest`/`createGenericHandler` integrations, apply the same
+byte limit in the host's raw-body reader before parsing or constructing
+`AdapterRequest`. The generic handler's check on an already-parsed object cannot
+bound earlier allocations. Configure request-size and read-timeout limits at the
+HTTP server/reverse proxy as well; middleware cannot undo upstream buffering.
+
+The impersonation guard retains at most 1,000 liveness verdicts and 64 distinct
+in-flight lookups per guard. Lookup waits end after five seconds. An unresponsive
+custom transport keeps its slot until it settles, preventing unlimited
+background requests; saturation follows the unavailable policy (deny by default).
+TTL hits never extend a verdict, and invalid unavailable-policy values are
+configuration errors.

package/dist/browser-session.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Browser-session bridge (server side).
+ *
+ * A browser tab that inherits the customer's own authentication (cookie or
+ * stored token) but not Devora's per-tab capability asks the customer backend
+ * to restore it. The backend, having authenticated the request through its
+ * normal middleware, resolves the impersonation context and — only when the
+ * customer session is impersonated — asks Devora for a one-time resume code.
+ * Ordinary customer traffic never contacts Devora here.
+ */
+import { type SessionBridgeResult } from "@devorash/core";
+import type { DevoraBackendSDK } from "./types.js";
+import { type ImpersonationContext } from "./middleware.js";
+export interface ResolveBrowserSessionInput {
+    /** Trusted impersonation context for the authenticated customer session, or null. */
+    context: ImpersonationContext | null | undefined;
+    /** Non-secret tab reference supplied by the browser SDK. */
+    tabRef: unknown;
+    /** Exact browser origin of the request (from the Origin header). */
+    origin: string | null | undefined;
+    /**
+     * Origins allowed to use the bridge. A request that carries an Origin header is
+     * rejected unless this is set and includes it — there is no usable default origin
+     * to compare against in a backend SDK, so an unconfigured allowlist fails closed.
+     */
+    allowedOrigins?: string[];
+}
+/** Framework-agnostic bridge decision. Adapters wrap this in a route. */
+export declare function resolveBrowserSession(sdk: DevoraBackendSDK, input: ResolveBrowserSessionInput): Promise<{
+    status: number;
+    body: SessionBridgeResult | {
+        error: string;
+    };
+}>;
+/** Response headers every bridge route must send. */
+export declare const BROWSER_SESSION_RESPONSE_HEADERS: {
+    readonly "Cache-Control": "private, no-store";
+    readonly "Content-Type": "application/json";
+};
+//# sourceMappingURL=browser-session.d.ts.map

package/dist/browser-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-session.d.ts","sourceRoot":"","sources":["../src/browser-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAgC,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAEzF,MAAM,WAAW,0BAA0B;IAC1C,qFAAqF;IACrF,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,CAAA;IAChD,4DAA4D;IAC5D,MAAM,EAAE,OAAO,CAAA;IACf,oEAAoE;IACpE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB;AAED,yEAAyE;AACzE,wBAAsB,qBAAqB,CAC1C,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,0BAA0B,GAC/B,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,mBAAmB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CA8B5E;AAED,qDAAqD;AACrD,eAAO,MAAM,gCAAgC;;;CAGnC,CAAA"}

package/dist/browser-session.js

@@ -0,0 +1,48 @@
+/**
+ * Browser-session bridge (server side).
+ *
+ * A browser tab that inherits the customer's own authentication (cookie or
+ * stored token) but not Devora's per-tab capability asks the customer backend
+ * to restore it. The backend, having authenticated the request through its
+ * normal middleware, resolves the impersonation context and — only when the
+ * customer session is impersonated — asks Devora for a one-time resume code.
+ * Ordinary customer traffic never contacts Devora here.
+ */
+import { BROWSER_SESSION_BRIDGE } from "@devorash/core";
+import { validateImpersonationContext } from "./middleware.js";
+/** Framework-agnostic bridge decision. Adapters wrap this in a route. */
+export async function resolveBrowserSession(sdk, input) {
+    if (typeof input.tabRef !== "string" ||
+        !BROWSER_SESSION_BRIDGE.TAB_REF_PATTERN.test(input.tabRef))
+        return { status: 400, body: { error: "Invalid tab reference" } };
+    const context = input.context;
+    if (context === null || context === undefined || context.isImpersonation === false)
+        return { status: 200, body: { status: "none" } };
+    // Origin only matters once we're about to mint a resume code for a real
+    // impersonation session; ordinary traffic through this bridge is unaffected.
+    // An Origin header must be listed in allowedOrigins (unconfigured fails
+    // closed). Devora binds every resume code to the origin that will redeem it,
+    // so a request without an Origin header cannot use one and gets none.
+    if (input.origin && (!input.allowedOrigins || !input.allowedOrigins.includes(input.origin)))
+        return { status: 403, body: { error: "Invalid request origin" } };
+    // The same strict validation as the guard: malformed or expired contexts
+    // never mint a resume code.
+    if (!input.origin || !validateImpersonationContext(context).valid)
+        return { status: 200, body: { status: "blocked", reason: "session_invalid" } };
+    const result = await sdk.createBrowserResumeCode({
+        sessionId: context.sessionId,
+        tabRef: input.tabRef,
+        origin: input.origin,
+    });
+    if (result === null)
+        return { status: 200, body: { status: "blocked", reason: "control_plane_unavailable" } };
+    if ("error" in result)
+        return { status: 200, body: { status: "blocked", reason: "session_invalid" } };
+    return { status: 200, body: { status: "resume", code: result.code } };
+}
+/** Response headers every bridge route must send. */
+export const BROWSER_SESSION_RESPONSE_HEADERS = {
+    "Cache-Control": "private, no-store",
+    "Content-Type": "application/json",
+};
+//# sourceMappingURL=browser-session.js.map

package/dist/browser-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-session.js","sourceRoot":"","sources":["../src/browser-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,sBAAsB,EAA4B,MAAM,gBAAgB,CAAA;AAEjF,OAAO,EAAE,4BAA4B,EAA6B,MAAM,iBAAiB,CAAA;AAiBzF,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAC1C,GAAqB,EACrB,KAAiC;IAEjC,IACC,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QAChC,CAAC,sBAAsB,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QAE1D,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,uBAAuB,EAAE,EAAE,CAAA;IACjE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAA;IAC7B,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,eAAe,KAAK,KAAK;QACjF,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAA;IACjD,wEAAwE;IACxE,6EAA6E;IAC7E,wEAAwE;IACxE,6EAA6E;IAC7E,sEAAsE;IACtE,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,cAAc,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC1F,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,wBAAwB,EAAE,EAAE,CAAA;IAClE,yEAAyE;IACzE,4BAA4B;IAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,4BAA4B,CAAC,OAAO,CAAC,CAAC,KAAK;QAChE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,iBAAiB,EAAE,EAAE,CAAA;IAC/E,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,uBAAuB,CAAC;QAChD,SAAS,EAAE,OAAO,CAAC,SAAU;QAC7B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,KAAK,CAAC,MAAM;KACpB,CAAC,CAAA;IACF,IAAI,MAAM,KAAK,IAAI;QAClB,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,2BAA2B,EAAE,EAAE,CAAA;IACzF,IAAI,OAAO,IAAI,MAAM;QACpB,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,iBAAiB,EAAE,EAAE,CAAA;IAC/E,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAA;AACtE,CAAC;AAED,qDAAqD;AACrD,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC/C,eAAe,EAAE,mBAAmB;IACpC,cAAc,EAAE,kBAAkB;CACzB,CAAA"}

package/dist/handler.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Generic request handler for all framework adapters
+ * @module @devorash/node
+ */
+import { type DevoraResponse } from "@devorash/core";
+import type { DevoraBackendSDK, SDKRoute } from "./types.js";
+/**
+ * A request exactly as received, for signature verification. Nothing here may
+ * be re-serialized: the signature covers these bytes.
+ */
+export interface AdapterRequest {
+    method: string;
+    /** Path relative to the SDK mount, still percent-encoded exactly as received. */
+    path: string;
+    /** Raw query after the first `?`, exactly as received ("" when absent). */
+    query: string;
+    /** Exact request body bytes ("" body = empty array). */
+    body: Uint8Array;
+    headers: Record<string, string | string[] | undefined>;
+}
+/**
+ * Options for processRequest
+ */
+export interface ProcessRequestOptions {
+    /** Override timestamp tolerance (defaults to SDK config) */
+    timestampTolerance?: number;
+    /** Maximum allowed body size in bytes (default: 1MB) */
+    maxBodySize?: number;
+}
+/**
+ * Default maximum body size (1MB)
+ * Framework/ingress parsers must apply this limit before buffering the body.
+ */
+export declare const DEFAULT_MAX_BODY_SIZE: number;
+/**
+ * Process an incoming request through the SDK.
+ *
+ * The signature is verified before any route lookup, so unauthenticated
+ * callers learn nothing about registered routes. Only verified bytes are
+ * parsed, with one parser for every framework.
+ */
+export declare function processRequest(sdk: DevoraBackendSDK, routes: SDKRoute[], request: AdapterRequest, options?: ProcessRequestOptions): Promise<DevoraResponse>;
+/**
+ * Strip a literal mount prefix (e.g. "/devora" or "/api/devora") from a raw
+ * request path. Used by middleware-style adapters where the framework does not
+ * strip the mount point. Devora signs the path relative to the mount.
+ */
+export declare function stripMountPath(path: string, mountPath: string): string;
+/**
+ * Create a generic handler function for framework adapters
+ */
+export declare function createGenericHandler(sdk: DevoraBackendSDK, routes: SDKRoute[], options?: ProcessRequestOptions): (request: AdapterRequest) => Promise<DevoraResponse>;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EASN,KAAK,cAAc,EAInB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE5D;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAA;IACZ,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,IAAI,EAAE,UAAU,CAAA;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,4DAA4D;IAC5D,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAc,CAAA;AAEhD;;;;;;GAMG;AACH,wBAAsB,cAAc,CACnC,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,QAAQ,EAAE,EAClB,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,qBAA0B,GACjC,OAAO,CAAC,cAAc,CAAC,CAwFzB;AAoBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAMtE;AAuHD;;GAEG;AACH,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,QAAQ,EAAE,EAClB,OAAO,CAAC,EAAE,qBAAqB,IAEjB,SAAS,cAAc,KAAG,OAAO,CAAC,cAAc,CAAC,CAG/D"}

package/dist/handler.js

@@ -0,0 +1,226 @@
+/**
+ * Generic request handler for all framework adapters
+ * @module @devorash/node
+ */
+import { DEVORA_ENDPOINTS, matchPath, createSuccessResponse, createErrorResponse, getSingleHeader, parseVerifiedJsonBody, parseVerifiedQuery, } from "@devorash/core";
+/**
+ * Default maximum body size (1MB)
+ * Framework/ingress parsers must apply this limit before buffering the body.
+ */
+export const DEFAULT_MAX_BODY_SIZE = 1024 * 1024; // 1MB
+/**
+ * Process an incoming request through the SDK.
+ *
+ * The signature is verified before any route lookup, so unauthenticated
+ * callers learn nothing about registered routes. Only verified bytes are
+ * parsed, with one parser for every framework.
+ */
+export async function processRequest(sdk, routes, request, options = {}) {
+    const { method, path, query, body, headers } = request;
+    // path is attacker-controlled and unbounded before a route has matched; every
+    // caller here that hasn't matched a route omits the second argument.
+    const record = (outcome, endpoint = "UNMATCHED") => {
+        sdk._recordRequest?.(endpoint, outcome);
+    };
+    const maxBodySize = options.maxBodySize ?? DEFAULT_MAX_BODY_SIZE;
+    if (!(body instanceof Uint8Array)) {
+        record("failure");
+        return createErrorResponse("Adapter must supply the raw request body bytes", "INVALID_BODY");
+    }
+    if (body.byteLength > maxBodySize) {
+        record("failure");
+        return createErrorResponse("Request body too large", "BODY_TOO_LARGE");
+    }
+    if ((method === "GET" || method === "HEAD") && body.byteLength > 0) {
+        record("failure");
+        return createErrorResponse("GET and HEAD requests must not have a body", "INVALID_BODY");
+    }
+    // Signature v3: headers, key/org, timestamp, target grammar, body digest,
+    // direction and single-use request id, over the exact wire bytes.
+    const verification = await sdk.verifyRequest({ method, path, query, body, headers }, { timestampTolerance: options.timestampTolerance });
+    if (!verification.valid) {
+        record("security_error");
+        return createErrorResponse(verification.error ?? "Security validation failed", verification.errorCode ?? "INVALID_SIGNATURE");
+    }
+    const route = findMatchingRoute(routes, method, path);
+    if (!route) {
+        record("failure");
+        return createErrorResponse("No handler found for this request", "NOT_FOUND");
+    }
+    const { params } = matchPath(route.path, path);
+    const parsedBody = parseVerifiedJsonBody(body, getSingleHeader(headers, "content-type"));
+    if (!parsedBody.ok) {
+        record("failure", route.path);
+        return createErrorResponse(parsedBody.error, "INVALID_BODY");
+    }
+    const parsedQuery = parseVerifiedQuery(query);
+    const devoraContextResult = buildDevoraContext(route, path, parsedBody.value, params);
+    if (!devoraContextResult.valid) {
+        record("security_error", route.path);
+        return createErrorResponse(devoraContextResult.error ?? "Invalid impersonation context", "INVALID_IMPERSONATION_CONTEXT");
+    }
+    // Devora never sends SECURITY_HEADERS.SESSION_ID and it isn't part of the signed
+    // payload, so trusting it here would let an unsigned header pick the session id.
+    const requestSessionId = devoraContextResult.context?.sessionId ?? getSessionIdFromRoute(route, params, parsedBody.value);
+    // Build Devora request object
+    const devoraRequest = {
+        method,
+        path,
+        params,
+        query: parsedQuery,
+        body: parsedBody.value,
+        headers,
+        orgId: verification.orgId ?? "",
+        keyId: verification.keyId ?? "",
+        sessionId: requestSessionId,
+        devoraContext: devoraContextResult.context,
+    };
+    // Execute handler
+    try {
+        const result = await route.handler(devoraRequest);
+        record("success", route.path);
+        return createSuccessResponse(result);
+    }
+    catch (error) {
+        if (sdk.config.debug)
+            console.error("[Devora] Customer handler failed", error);
+        record("failure", route.path);
+        return createErrorResponse("Customer handler failed", "HANDLER_ERROR");
+    }
+}
+/**
+ * Find a matching route for the given method and path
+ */
+function findMatchingRoute(routes, method, path) {
+    for (const route of routes) {
+        if (route.method !== method.toUpperCase()) {
+            continue;
+        }
+        const { match } = matchPath(route.path, path);
+        if (match) {
+            return route;
+        }
+    }
+    return undefined;
+}
+/**
+ * Strip a literal mount prefix (e.g. "/devora" or "/api/devora") from a raw
+ * request path. Used by middleware-style adapters where the framework does not
+ * strip the mount point. Devora signs the path relative to the mount.
+ */
+export function stripMountPath(path, mountPath) {
+    const normalizedMount = `/${mountPath}`.replace(/\/+/g, "/").replace(/\/$/, "");
+    if (!normalizedMount || normalizedMount === "/")
+        return path;
+    if (path === normalizedMount)
+        return "/";
+    if (path.startsWith(`${normalizedMount}/`))
+        return path.slice(normalizedMount.length);
+    return path;
+}
+function buildDevoraContext(route, path, body, params) {
+    if (route.path !== DEVORA_ENDPOINTS.IMPERSONATE) {
+        return { valid: true };
+    }
+    const bodyObject = asRecord(body);
+    if (!bodyObject) {
+        return { valid: false, error: "Impersonation request body must be an object" };
+    }
+    const sessionId = readString(bodyObject.sessionId);
+    if (!sessionId || sessionId.length > 128) {
+        return { valid: false, error: "Impersonation request is missing a valid session ID" };
+    }
+    const scope = bodyObject.scope;
+    if (scope !== "read" && scope !== "write") {
+        return { valid: false, error: "Impersonation request is missing a valid scope" };
+    }
+    const expiresAt = readFiniteNumber(bodyObject.expiresAt);
+    if (!expiresAt || expiresAt <= Date.now()) {
+        return { valid: false, error: "Impersonation request is expired or missing expiration" };
+    }
+    let targetUser = readUserInfo(bodyObject.targetUser, params.id);
+    if (!targetUser) {
+        const matchedParams = matchPath(route.path, path).params;
+        targetUser = readUserInfo(bodyObject.targetUser, matchedParams.id);
+        if (!targetUser) {
+            return { valid: false, error: "Impersonation request is missing target user context" };
+        }
+    }
+    const impersonator = readUserInfo(bodyObject.impersonator);
+    if (!impersonator) {
+        return { valid: false, error: "Impersonation request is missing impersonator context" };
+    }
+    if (bodyObject.authMethod !== "devora_impersonation") {
+        return { valid: false, error: "Impersonation request has an invalid authentication method" };
+    }
+    if (bodyObject.authorizationSource !== "standard" &&
+        bodyObject.authorizationSource !== "self_approved" &&
+        bodyObject.authorizationSource !== "self_approved_read" &&
+        bodyObject.authorizationSource !== "break_glass") {
+        return { valid: false, error: "Impersonation request is missing authorization context" };
+    }
+    if (typeof bodyObject.recordingAllowed !== "boolean") {
+        return { valid: false, error: "Impersonation request is missing recording authorization" };
+    }
+    return {
+        valid: true,
+        context: {
+            isImpersonation: true,
+            sessionId,
+            scope: scope,
+            expiresAt,
+            impersonator,
+            targetUser,
+            actor: { id: impersonator.id },
+            subject: { id: targetUser.id },
+            authMethod: "devora_impersonation",
+            authorizationSource: bodyObject.authorizationSource,
+            recordingAllowed: bodyObject.recordingAllowed,
+        },
+    };
+}
+function getSessionIdFromRoute(route, params, body) {
+    if (route.path === DEVORA_ENDPOINTS.TERMINATE && params.id) {
+        return params.id;
+    }
+    const bodyObject = asRecord(body);
+    return readString(bodyObject?.sessionId);
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function readFiniteNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function readUserInfo(value, fallbackId) {
+    const source = asRecord(value);
+    const id = readString(source?.id) ?? fallbackId;
+    if (!id)
+        return null;
+    return {
+        id,
+        email: readString(source?.email),
+        name: readString(source?.name),
+    };
+}
+/**
+ * Create a generic handler function for framework adapters
+ */
+export function createGenericHandler(sdk, routes, options) {
+    return async (request) => {
+        return processRequest(sdk, routes, request, options);
+    };
+}
+//# sourceMappingURL=handler.js.map