@devorash/node 0.1.0 → 0.1.1

package/README.md

@@ -1,32 +1,54 @@
 # @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).
+Recording, masking, capture and scope policy are configured in the Devora
+dashboard and authorized server-side for each session. The backend SDK accepts
+no settings for them: `devoraSDK` ignores any option not listed under
+[Configuration](#configuration).
+See [SETTINGS.md](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.
 
+Requires Node.js 20 or later. Use it through a framework adapter:
+[`@devorash/express`](https://www.npmjs.com/package/@devorash/express),
+[`@devorash/fastify`](https://www.npmjs.com/package/@devorash/fastify) or
+[`@devorash/hono`](https://www.npmjs.com/package/@devorash/hono).
+
 ## Installation
 
 ```bash
-npm install @devorash/node
+npm install @devorash/node redis
 # or
-bun add @devorash/node
+bun add @devorash/node redis
 ```
 
 ## Quick Start
 
 ```typescript
+import { createClient } from "redis"
 import { devoraSDK, DEVORA_ENDPOINTS } from "@devorash/node"
 
+// Replay protection shared by every instance of your backend (required in production).
+const redis = createClient({ url: process.env.REDIS_URL }).on("error", (err) => console.error("Redis error", err))
+let redisReady: Promise<unknown> | undefined // one connection, shared by concurrent first requests
+
 // 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",
+	apiKey: process.env.DEVORA_API_KEY!, // pk_server_live_...
+	secretKey: process.env.DEVORA_SECRET_KEY!, // sk_server_live_...
+	orgId: process.env.DEVORA_ORG_ID!,
 	debug: process.env.NODE_ENV === "development",
+	replayStore: {
+		async consume(namespace, requestId, expiresAt) {
+			await (redisReady ??= redis.connect().catch((err) => {
+				redisReady = undefined // retry on the next request
+				throw err
+			}))
+			const key = `devora:replay:${namespace}:${requestId}`
+			// Atomic insert-if-absent kept until expiresAt; an error makes the SDK fail closed (503).
+			const reply = await redis.sendCommand<string | null>(["SET", key, "1", "NX", "PXAT", String(expiresAt)])
+			return reply === "OK"
+		},
+	},
 })
 
 // User search endpoint
@@ -45,10 +67,12 @@ sdk.register(DEVORA_ENDPOINTS.USER_SEARCH, async (req) => {
 // Impersonation start endpoint
 sdk.register(DEVORA_ENDPOINTS.IMPERSONATE, async (req) => {
 	const { id } = req.params
-	const { targetUser } = req.devoraContext!
+	const ctx = req.devoraContext
+	if (!ctx) throw new Error("Missing verified Devora context")
 
-	// Generate a short-lived app token for the target user.
-	const token = await generateAuthToken(targetUser.id)
+	// Generate a short-lived app token for the target user. Store ctx unchanged in
+	// it: createImpersonationGuard reads every field back. Expire it by ctx.expiresAt.
+	const token = await generateAuthToken(ctx.targetUser.id, ctx)
 
 	// Optionally include user settings for frontend initialization.
 	const userSettings = await getUserSettings(id)
@@ -75,6 +99,19 @@ sdk.register(DEVORA_ENDPOINTS.TERMINATE, async (req) => {
 export { sdk }
 ```
 
+The environment comes from the `environment` option, else `DEVORA_ENV`, else
+`NODE_ENV`. Anything other than `development` or `test` (including unset) is
+production, and production refuses to start without a `replayStore`; see
+[Security](#security).
+
+**Local development only:** to run without Redis, omit `replayStore` and start
+the process with `DEVORA_ENV=development` (or pass `environment: "development"`).
+The SDK then keeps request ids in memory, which protects a single process only.
+Never use this in production.
+
+Register every handler before creating an adapter: adapters read the route list
+once, when they are created.
+
 ## Framework Integration
 
 Use the SDK with your preferred web framework:
@@ -133,43 +170,64 @@ const sdk = devoraSDK({
 	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
+	replayStore, // Required in production (see Security)
 
 	// 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
+	environment: "production", // "development" | "test" | "production"; defaults from DEVORA_ENV, then NODE_ENV, else production
+	debug: false, // SDK debug logging (default: on when NODE_ENV=development)
+	timestampTolerance: 300, // Max clock drift in seconds, a non-negative integer (default: 300)
+	collectStats: false, // Per-endpoint counts in getStats() and counters in the /health response
 })
 ```
 
+`apiKey` must be `pk_server_live_` followed by 32 characters and `secretKey`
+`sk_server_live_` followed by 64; `devoraSDK` throws on anything else. `apiUrl`
+(an https origin) overrides the Devora API origin for self-hosted deployments.
+
 ## Built-in Endpoints
 
-The SDK automatically provides two built-in endpoints:
+The SDK automatically provides two signed endpoints. Like every SDK route, they
+answer unsigned requests with `401`.
 
-### `/test` - Connection Test
+### `/health` - Health Check
 
-Used by the Devora platform to verify your integration is working.
+Returns SDK health information and the registered endpoints. Devora's **Test
+connection** check calls it.
 
 ```
-GET /devora/test
+GET /devora/health
 ```
 
-### `/health` - Health Check
+### `/test` - Connection Test
 
-Returns SDK health information and registered endpoints.
+Returns the verified organization and key ID, for your own signed checks.
 
 ```
-GET /devora/health
+GET /devora/test
 ```
 
+## Responses and errors
+
+A handler's return value is sent as `{ success: true, data, timestamp }` with
+status 200. Failures are `{ success: false, error, errorCode, timestamp }`:
+
+| Status | `errorCode`                                                                                          | Cause                                                                   |
+| ------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| 401    | `INVALID_SIGNATURE_HEADERS`, `UNSUPPORTED_SIGNATURE_VERSION`, `ORG_MISMATCH`, `TIMESTAMP_EXPIRED`, `INVALID_SIGNATURE`, `REPLAYED_REQUEST` | Unsigned, altered, stale or replayed request, or a different key or org |
+| 401    | `INVALID_IMPERSONATION_CONTEXT`                                                                      | Incomplete or expired impersonation-start body                          |
+| 400    | `INVALID_REQUEST_TARGET`, `INVALID_BODY`                                                             | Malformed path or query; body that is not strict JSON                   |
+| 400    | `HANDLER_ERROR`                                                                                      | Your handler threw (its message is not sent)                            |
+| 413    | `BODY_TOO_LARGE`                                                                                     | Body larger than `maxBodySize`                                          |
+| 415    | `UNSUPPORTED_CONTENT_ENCODING`                                                                       | `Content-Encoding` other than `identity`                                |
+| 503    | `REPLAY_STORE_UNAVAILABLE`                                                                           | `replayStore.consume` threw or did not return a boolean                 |
+
 ## 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.
+a timestamp and a single-use request id. The adapters verify it before any
+handler runs and reject unsigned, altered, stale or replayed requests. See
+[SIGNING.md](https://github.com/getdevora/devora-sdks/blob/main/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
@@ -180,17 +238,19 @@ refuses to start without a `replayStore`.
 import { createClient } from "redis"
 import { devoraSDK, type ReplayStore } from "@devorash/node"
 
-const redis = await createClient({ url: process.env.REDIS_URL }).connect()
+const redis = createClient({ url: process.env.REDIS_URL }).on("error", (err) => console.error("Redis error", err))
+let redisReady: Promise<unknown> | undefined // one connection, shared by concurrent first requests
 
 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"
+		await (redisReady ??= redis.connect().catch((err) => {
+			redisReady = undefined // retry on the next request
+			throw err
+		}))
+		const key = `devora:replay:${namespace}:${requestId}`
+		// Atomic insert-if-absent kept until expiresAt; an error makes the SDK fail closed (503).
+		const reply = await redis.sendCommand<string | null>(["SET", key, "1", "NX", "PXAT", String(expiresAt)])
+		return reply === "OK"
 	},
 }
 
@@ -232,11 +292,13 @@ sdk.register<
 
 ### `devoraSDK(config)`
 
-Create a new SDK instance.
+Create a new SDK instance. It starts loading the dashboard-managed scope policy
+in the background (`sdk.ready` resolves when that first attempt finishes).
 
 ### `sdk.register(path, handler, options?)`
 
-Register an endpoint handler.
+Register an endpoint handler. The method is detected for `DEVORA_ENDPOINTS`
+paths; `/test` and `/health` cannot be overridden.
 
 ### `sdk.getRoutes()`
 
@@ -244,7 +306,8 @@ Get all registered routes.
 
 ### `sdk.getStats()`
 
-Get request statistics (if `collectStats: true`).
+Get request statistics. Totals are always counted; `requestsByEndpoint` is
+filled only with `collectStats: true`.
 
 ### `sdk.verifyRequest({ method, path, query, body, headers }, options?)`
 
@@ -253,23 +316,25 @@ 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
+### `createImpersonationGuard(options)`
 
-MIT
+Backend scope enforcement for your application routes, using the policy managed
+in the dashboard. See the
+[`@devorash/node` reference](https://docs.devora.sh/reference/node#scope-guard).
 
 ## 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.
+The Express router and middleware read the raw body themselves (1 MiB by
+default, configurable through `maxBodySize`); compressed request bodies are
+rejected. Mount them before application-wide body parsers: a body another
+parser already consumed is rejected with `DEVORA_BODY_ALREADY_PARSED`. The
+Express browser-session handler uses a 4 KiB limit.
 
-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.
+For direct `processRequest`/`createGenericHandler` integrations, pass the exact
+body bytes as a `Uint8Array` and apply the byte limit in the host's raw-body
+reader: the handler's own `maxBodySize` check runs only after the body is
+buffered. 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
@@ -277,3 +342,7 @@ 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.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -5,29 +5,47 @@
  *
  * @example
  * ```typescript
- * import { devoraSDK, DEVORA_ENDPOINTS } from "@devorash/node";
+ * import { createClient } from "redis"
+ * import { devoraSDK, DEVORA_ENDPOINTS } from "@devorash/node"
+ *
+ * // Replay protection shared by every instance of your backend (required in production).
+ * const redis = createClient({ url: process.env.REDIS_URL }).on("error", (err) => console.error("Redis error", err))
+ * let redisReady: Promise<unknown> | undefined // one connection, shared by concurrent first requests
  *
  * const sdk = devoraSDK({
  *   apiKey: process.env.DEVORA_API_KEY!,
  *   secretKey: process.env.DEVORA_SECRET_KEY!,
- *   orgId: "your-org-id",
- * });
- *
- * const routes = [
- *   sdk.register(DEVORA_ENDPOINTS.USER_SEARCH, async (req) => {
- *     const { term } = req.query;
- *     return { users: await searchUsers(term) };
- *   }),
- *   sdk.register(DEVORA_ENDPOINTS.IMPERSONATE, async (req) => {
- *     const { id } = req.params;
- *     return { token: await generateToken(id), data: {} };
- *   }),
- *   sdk.register(DEVORA_ENDPOINTS.TERMINATE, async (req) => {
- *     const { id } = req.params;
- *     await invalidateSession(id);
- *     return { success: true };
- *   }),
- * ];
+ *   orgId: process.env.DEVORA_ORG_ID!,
+ *   replayStore: {
+ *     async consume(namespace, requestId, expiresAt) {
+ *       await (redisReady ??= redis.connect().catch((err) => {
+ *         redisReady = undefined // retry on the next request
+ *         throw err
+ *       }))
+ *       const key = `devora:replay:${namespace}:${requestId}`
+ *       // Atomic insert-if-absent kept until expiresAt; an error makes the SDK fail closed (503).
+ *       const reply = await redis.sendCommand<string | null>(["SET", key, "1", "NX", "PXAT", String(expiresAt)])
+ *       return reply === "OK"
+ *     },
+ *   },
+ * })
+ *
+ * sdk.register(DEVORA_ENDPOINTS.USER_SEARCH, async (req) => ({
+ *   users: await searchUsers(String(req.query.term ?? "")),
+ * }))
+ *
+ * sdk.register(DEVORA_ENDPOINTS.IMPERSONATE, async (req) => {
+ *   const ctx = req.devoraContext // set only after the signed request is verified
+ *   if (!ctx) throw new Error("Missing verified Devora context")
+ *   // Store ctx unchanged in the credential: createImpersonationGuard reads every
+ *   // field of it back. Expire the credential no later than ctx.expiresAt.
+ *   return { token: await generateToken(ctx.targetUser.id, ctx) }
+ * })
+ *
+ * sdk.register(DEVORA_ENDPOINTS.TERMINATE, async (req) => {
+ *   await invalidateSession(req.sessionId ?? req.params.id)
+ *   return { success: true }
+ * })
  * ```
  *
  * @packageDocumentation

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAGxD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EACN,iBAAiB,EACjB,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,GAC1B,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EACN,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,KAAK,cAAc,GACnB,MAAM,cAAc,CAAA;AAGrB,OAAO,EACN,wBAAwB,EACxB,4BAA4B,EAC5B,8BAA8B,EAC9B,gBAAgB,GAChB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACX,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,aAAa,GACb,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AAC5D,YAAY,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAG/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAGpD,YAAY,EACX,oBAAoB,EACpB,MAAM,EACN,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GACjB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAEN,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EAEnB,gBAAgB,EAEhB,YAAY,EACZ,WAAW,EAEX,WAAW,EAEX,cAAc,EACd,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EAEjB,SAAS,EACT,qBAAqB,EACrB,mBAAmB,GACnB,MAAM,gBAAgB,CAAA;AAGvB,YAAY,EACX,aAAa,EACb,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,0BAA0B,EAC1B,6BAA6B,EAC7B,8BAA8B,EAC9B,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,mBAAmB,GACnB,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EACN,qBAAqB,EACrB,gCAAgC,EAChC,KAAK,0BAA0B,GAC/B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AACvD,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAGH,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAGxD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EACN,iBAAiB,EACjB,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,GAC1B,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EACN,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,KAAK,cAAc,GACnB,MAAM,cAAc,CAAA;AAGrB,OAAO,EACN,wBAAwB,EACxB,4BAA4B,EAC5B,8BAA8B,EAC9B,gBAAgB,GAChB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACX,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,aAAa,GACb,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AAC5D,YAAY,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAG/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAGpD,YAAY,EACX,oBAAoB,EACpB,MAAM,EACN,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GACjB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAEN,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EAEnB,gBAAgB,EAEhB,YAAY,EACZ,WAAW,EAEX,WAAW,EAEX,cAAc,EACd,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EAEjB,SAAS,EACT,qBAAqB,EACrB,mBAAmB,GACnB,MAAM,gBAAgB,CAAA;AAGvB,YAAY,EACX,aAAa,EACb,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,0BAA0B,EAC1B,6BAA6B,EAC7B,8BAA8B,EAC9B,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,mBAAmB,GACnB,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EACN,qBAAqB,EACrB,gCAAgC,EAChC,KAAK,0BAA0B,GAC/B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AACvD,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -5,29 +5,47 @@
  *
  * @example
  * ```typescript
- * import { devoraSDK, DEVORA_ENDPOINTS } from "@devorash/node";
+ * import { createClient } from "redis"
+ * import { devoraSDK, DEVORA_ENDPOINTS } from "@devorash/node"
+ *
+ * // Replay protection shared by every instance of your backend (required in production).
+ * const redis = createClient({ url: process.env.REDIS_URL }).on("error", (err) => console.error("Redis error", err))
+ * let redisReady: Promise<unknown> | undefined // one connection, shared by concurrent first requests
  *
  * const sdk = devoraSDK({
  *   apiKey: process.env.DEVORA_API_KEY!,
  *   secretKey: process.env.DEVORA_SECRET_KEY!,
- *   orgId: "your-org-id",
- * });
+ *   orgId: process.env.DEVORA_ORG_ID!,
+ *   replayStore: {
+ *     async consume(namespace, requestId, expiresAt) {
+ *       await (redisReady ??= redis.connect().catch((err) => {
+ *         redisReady = undefined // retry on the next request
+ *         throw err
+ *       }))
+ *       const key = `devora:replay:${namespace}:${requestId}`
+ *       // Atomic insert-if-absent kept until expiresAt; an error makes the SDK fail closed (503).
+ *       const reply = await redis.sendCommand<string | null>(["SET", key, "1", "NX", "PXAT", String(expiresAt)])
+ *       return reply === "OK"
+ *     },
+ *   },
+ * })
+ *
+ * sdk.register(DEVORA_ENDPOINTS.USER_SEARCH, async (req) => ({
+ *   users: await searchUsers(String(req.query.term ?? "")),
+ * }))
+ *
+ * sdk.register(DEVORA_ENDPOINTS.IMPERSONATE, async (req) => {
+ *   const ctx = req.devoraContext // set only after the signed request is verified
+ *   if (!ctx) throw new Error("Missing verified Devora context")
+ *   // Store ctx unchanged in the credential: createImpersonationGuard reads every
+ *   // field of it back. Expire the credential no later than ctx.expiresAt.
+ *   return { token: await generateToken(ctx.targetUser.id, ctx) }
+ * })
  *
- * const routes = [
- *   sdk.register(DEVORA_ENDPOINTS.USER_SEARCH, async (req) => {
- *     const { term } = req.query;
- *     return { users: await searchUsers(term) };
- *   }),
- *   sdk.register(DEVORA_ENDPOINTS.IMPERSONATE, async (req) => {
- *     const { id } = req.params;
- *     return { token: await generateToken(id), data: {} };
- *   }),
- *   sdk.register(DEVORA_ENDPOINTS.TERMINATE, async (req) => {
- *     const { id } = req.params;
- *     await invalidateSession(id);
- *     return { success: true };
- *   }),
- * ];
+ * sdk.register(DEVORA_ENDPOINTS.TERMINATE, async (req) => {
+ *   await invalidateSession(req.sessionId ?? req.params.id)
+ *   return { success: true }
+ * })
  * ```
  *
  * @packageDocumentation

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,WAAW;AACX,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAExD,iBAAiB;AACjB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EACN,iBAAiB,EACjB,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,GAC1B,MAAM,gBAAgB,CAAA;AAEvB,kBAAkB;AAClB,OAAO,EACN,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,qBAAqB,GAErB,MAAM,cAAc,CAAA;AAErB,2BAA2B;AAC3B,OAAO,EACN,wBAAwB,EACxB,4BAA4B,EAC5B,8BAA8B,EAC9B,gBAAgB,GAChB,MAAM,iBAAiB,CAAA;AAWxB,sBAAsB;AACtB,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AAG5D,+BAA+B;AAC/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAkBvD,0CAA0C;AAC1C,OAAO;AACN,YAAY;AACZ,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB;AACnB,mBAAmB;AACnB,gBAAgB;AAChB,WAAW;AACX,YAAY,EACZ,WAAW;AACX,cAAc;AACd,WAAW;AACX,SAAS;AACT,cAAc,EACd,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB;AACjB,YAAY;AACZ,SAAS,EACT,qBAAqB,EACrB,mBAAmB,GACnB,MAAM,gBAAgB,CAAA;AAsBvB,uCAAuC;AACvC,OAAO,EACN,qBAAqB,EACrB,gCAAgC,GAEhC,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,WAAW;AACX,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAExD,iBAAiB;AACjB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EACN,iBAAiB,EACjB,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,GAC1B,MAAM,gBAAgB,CAAA;AAEvB,kBAAkB;AAClB,OAAO,EACN,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,qBAAqB,GAErB,MAAM,cAAc,CAAA;AAErB,2BAA2B;AAC3B,OAAO,EACN,wBAAwB,EACxB,4BAA4B,EAC5B,8BAA8B,EAC9B,gBAAgB,GAChB,MAAM,iBAAiB,CAAA;AAWxB,sBAAsB;AACtB,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AAG5D,+BAA+B;AAC/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAkBvD,0CAA0C;AAC1C,OAAO;AACN,YAAY;AACZ,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB;AACnB,mBAAmB;AACnB,gBAAgB;AAChB,WAAW;AACX,YAAY,EACZ,WAAW;AACX,cAAc;AACd,WAAW;AACX,SAAS;AACT,cAAc,EACd,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB;AACjB,YAAY;AACZ,SAAS,EACT,qBAAqB,EACrB,mBAAmB,GACnB,MAAM,gBAAgB,CAAA;AAsBvB,uCAAuC;AACvC,OAAO,EACN,qBAAqB,EACrB,gCAAgC,GAEhC,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devorash/node",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Devora Node.js Backend SDK for secure impersonation",
   "keywords": [
     "backend",
@@ -42,7 +42,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@devorash/core": "0.1.0"
+    "@devorash/core": "0.1.1"
   },
   "engines": {
     "node": ">=20.0.0"