@devorash/core 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,187 @@
+# @devorash/core
+
+Core utilities, types, and constants shared across all Devora SDKs.
+
+## Installation
+
+```bash
+npm install @devorash/core
+# or
+bun add @devorash/core
+```
+
+## Usage
+
+This package is primarily used as a dependency by other Devora SDK packages. You typically won't need to install it directly unless you're building custom integrations.
+
+### Types
+
+```typescript
+import type {
+	DevoraRequest,
+	DevoraResponse,
+	ImpersonationScope,
+	BackendSDKConfig,
+	FrontendSDKConfig,
+} from "@devorash/core"
+```
+
+### Constants
+
+```typescript
+import { DEVORA_ENDPOINTS, SECURITY_HEADERS, SDK_DEFAULTS, SDK_VERSION } from "@devorash/core"
+
+// Use predefined endpoints for type safety
+console.log(DEVORA_ENDPOINTS.USER_SEARCH) // "/user/search"
+console.log(DEVORA_ENDPOINTS.USER_BY_ID) // "/user/:id"
+console.log(DEVORA_ENDPOINTS.IMPERSONATE) // "/impersonate/:id"
+console.log(DEVORA_ENDPOINTS.TERMINATE) // "/impersonate/:id/terminate"
+```
+
+### Security Utilities
+
+```typescript
+import {
+	validateTimestamp,
+	extractSecurityHeaders,
+	timingSafeEqual,
+	isWriteMethod,
+} from "@devorash/core"
+
+// Validate request timestamp
+const { valid, error } = validateTimestamp(requestTimestamp)
+
+// Check if HTTP method is a write operation (blocked in read-only mode)
+if (isWriteMethod("POST")) {
+	console.log("This is a write operation")
+}
+```
+
+### Utility Functions
+
+```typescript
+import {
+	matchPath,
+	createSuccessResponse,
+	createErrorResponse,
+	validateApiKeyFormat,
+} from "@devorash/core"
+
+// Match path patterns
+const { match, params } = matchPath("/impersonate/:id", "/impersonate/user123")
+console.log(match) // true
+console.log(params) // { id: "user123" }
+
+// Create SDK responses
+const success = createSuccessResponse({ users: [] })
+const error = createErrorResponse("Not found", "NOT_FOUND")
+
+// Validate API key format
+const validation = validateApiKeyFormat("pk_server_live_abc123")
+console.log(validation) // { valid: true, type: "server", environment: "live" }
+```
+
+## Exports
+
+### Subpath Exports
+
+This package supports subpath exports for tree-shaking:
+
+```typescript
+// Import only types
+import type { DevoraRequest } from "@devorash/core/types"
+
+// Import only constants
+import { DEVORA_ENDPOINTS } from "@devorash/core/constants"
+
+// Import only security utilities
+import { validateTimestamp } from "@devorash/core/security"
+
+// Import only utility functions
+import { matchPath } from "@devorash/core/utils"
+```
+
+## API Reference
+
+### Types
+
+| Type                 | Description                                  |
+| -------------------- | -------------------------------------------- |
+| `DevoraRequest`      | Normalized request object passed to handlers |
+| `DevoraResponse`     | Standard response format                     |
+| `DevoraUser`         | User object for search results               |
+| `ImpersonationScope` | "read" or "write" scope                      |
+| `BackendSDKConfig`   | Backend SDK configuration                    |
+| `FrontendSDKConfig`  | Frontend SDK configuration                   |
+| `RouteDefinition`    | Route handler definition                     |
+| `LogEvent`           | Activity log event                           |
+
+### Constants
+
+| Constant           | Description                     |
+| ------------------ | ------------------------------- |
+| `DEVORA_ENDPOINTS` | Predefined endpoint paths       |
+| `SECURITY_HEADERS` | HTTP header names for HMAC auth |
+| `SDK_DEFAULTS`     | Default configuration values    |
+| `ERROR_CODES`      | SDK error codes                 |
+| `WRITE_METHODS`    | HTTP methods considered writes  |
+
+### Security Functions
+
+| Function                    | Description                           |
+| --------------------------- | ------------------------------------- |
+| `validateTimestamp()`       | Validate request timestamp            |
+| `extractSecurityHeaders()`  | Extract security headers from request |
+| `validateSecurityHeaders()` | Full security validation              |
+| `timingSafeEqual()`         | Timing-safe string comparison         |
+| `isWriteMethod()`           | Check if method is a write operation  |
+
+### Utility Functions
+
+| Function                  | Description                        |
+| ------------------------- | ---------------------------------- |
+| `matchPath()`             | Match path pattern with parameters |
+| `createSuccessResponse()` | Create success response            |
+| `createErrorResponse()`   | Create error response              |
+| `validateApiKeyFormat()`  | Validate API key format            |
+
+### Logger Service
+
+The SDK includes a configurable logger service that automatically adjusts based on environment.
+
+```typescript
+import { configureLogger, LogLevel, createLogger } from "@devorash/core"
+
+// Configure globally at app initialization (optional)
+configureLogger({
+	level: LogLevel.DEBUG, // DEBUG, INFO, WARN, ERROR, SILENT
+	enabled: true, // Override auto-detection
+	includeTimestamp: true, // Add timestamps to log messages
+})
+
+// Create a logger instance
+const logger = createLogger("MyComponent")
+
+logger.debug("Verbose debugging info") // Only in development
+logger.info("General information") // Only if level <= INFO
+logger.warn("Warning message") // Only if level <= WARN
+logger.error("Error message") // Always logged (unless disabled)
+```
+
+**Environment Auto-Detection:**
+
+- Development: `NODE_ENV=development` or running on `localhost`
+- Production: All other cases (logging disabled by default)
+
+**Log Levels:**
+| Level | Value | Description |
+|-------|-------|-------------|
+| `DEBUG` | 0 | Verbose debugging (dev only) |
+| `INFO` | 1 | General information |
+| `WARN` | 2 | Warnings (default in dev) |
+| `ERROR` | 3 | Errors only (default in prod) |
+| `SILENT` | 4 | No logging |
+
+## License
+
+MIT

package/dist/constants/api-url.gen.d.ts

@@ -0,0 +1,4 @@
+/** Generated by scripts/generate-api-url.mjs - do not edit */
+export declare const DEVORA_API_ORIGIN: "https://beloved-bee-737.convex.site";
+export declare const DEVORA_DASHBOARD_ORIGIN: "https://app.devora.sh";
+//# sourceMappingURL=api-url.gen.d.ts.map

package/dist/constants/api-url.gen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-url.gen.d.ts","sourceRoot":"","sources":["../../src/constants/api-url.gen.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,EAAG,qCAA8C,CAAA;AAC/E,eAAO,MAAM,uBAAuB,EAAG,uBAAgC,CAAA"}

package/dist/constants/api-url.gen.example.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Example of the generated api-url.gen.ts file.
+ * Run: node packages/sdks/scripts/generate-api-url.mjs (with DEVORA_SDK_API_ORIGIN set)
+ */
+export declare const DEVORA_API_ORIGIN: "https://YOUR_DEPLOYMENT.convex.site";
+export declare const DEVORA_DASHBOARD_ORIGIN: "https://app.devora.sh";
+//# sourceMappingURL=api-url.gen.example.d.ts.map

package/dist/constants/api-url.gen.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-url.gen.example.d.ts","sourceRoot":"","sources":["../../src/constants/api-url.gen.example.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAG,qCAA8C,CAAA;AAC/E,eAAO,MAAM,uBAAuB,EAAG,uBAAgC,CAAA"}

package/dist/constants/api-url.gen.example.js

@@ -0,0 +1,7 @@
+/**
+ * Example of the generated api-url.gen.ts file.
+ * Run: node packages/sdks/scripts/generate-api-url.mjs (with DEVORA_SDK_API_ORIGIN set)
+ */
+export const DEVORA_API_ORIGIN = "https://YOUR_DEPLOYMENT.convex.site";
+export const DEVORA_DASHBOARD_ORIGIN = "https://app.devora.sh";
+//# sourceMappingURL=api-url.gen.example.js.map

package/dist/constants/api-url.gen.example.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-url.gen.example.js","sourceRoot":"","sources":["../../src/constants/api-url.gen.example.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,qCAA8C,CAAA;AAC/E,MAAM,CAAC,MAAM,uBAAuB,GAAG,uBAAgC,CAAA"}

package/dist/constants/api-url.gen.js

@@ -0,0 +1,4 @@
+/** Generated by scripts/generate-api-url.mjs - do not edit */
+export const DEVORA_API_ORIGIN = "https://beloved-bee-737.convex.site";
+export const DEVORA_DASHBOARD_ORIGIN = "https://app.devora.sh";
+//# sourceMappingURL=api-url.gen.js.map

package/dist/constants/api-url.gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-url.gen.js","sourceRoot":"","sources":["../../src/constants/api-url.gen.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,qCAA8C,CAAA;AAC/E,MAAM,CAAC,MAAM,uBAAuB,GAAG,uBAAgC,CAAA"}

package/dist/constants/index.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Constants for Devora SDKs
+ * @module @devorash/core/constants
+ */
+/**
+ * Predefined endpoint constants for Devora SDK integration.
+ * Using these constants ensures:
+ * - Typo prevention (/impersonation vs /impersonate)
+ * - Automatic HTTP method detection
+ * - IDE autocomplete and documentation
+ * - Consistency across all customer integrations
+ */
+export declare const DEVORA_ENDPOINTS: {
+    /**
+     * User search endpoint - allows Devora to search customer's users
+     * @method GET
+     * @path /user/search
+     * @query term - Search term (name, email, or user ID)
+     */
+    readonly USER_SEARCH: "/user/search";
+    /**
+     * Get user by ID endpoint - retrieves a specific user's details
+     * @method GET
+     * @path /user/:id
+     * @params id - User ID to look up
+     */
+    readonly USER_BY_ID: "/user/:id";
+    /**
+     * Impersonation start endpoint - generates auth token for session
+     * @method POST
+     * @path /impersonate/:id
+     * @params id - Target user ID to impersonate
+     */
+    readonly IMPERSONATE: "/impersonate/:id";
+    /**
+     * Session termination endpoint - revokes impersonation session
+     * @method DELETE
+     * @path /impersonate/:id/terminate
+     * @params id - Session ID to terminate
+     */
+    readonly TERMINATE: "/impersonate/:id/terminate";
+    /**
+     * Connection test endpoint - validates SDK setup (built-in)
+     * @method GET
+     * @path /test
+     * @internal This endpoint is automatically provided by the SDK
+     */
+    readonly TEST: "/test";
+    /**
+     * Health check endpoint - SDK health and metrics (built-in)
+     * @method GET
+     * @path /health
+     * @internal This endpoint is automatically provided by the SDK
+     */
+    readonly HEALTH: "/health";
+};
+/** Type for endpoint keys */
+export type DevoraEndpointKey = keyof typeof DEVORA_ENDPOINTS;
+/** Type for endpoint values */
+export type DevoraEndpointPath = (typeof DEVORA_ENDPOINTS)[keyof typeof DEVORA_ENDPOINTS];
+/**
+ * HTTP methods for each endpoint (auto-detected when using constants)
+ */
+export declare const ENDPOINT_METHODS: Record<DevoraEndpointPath, "GET" | "POST" | "DELETE">;
+/**
+ * Built-in endpoints that cannot be overridden
+ */
+export declare const PROTECTED_ENDPOINTS: readonly DevoraEndpointPath[];
+/**
+ * HTTP headers used for HMAC authentication
+ */
+export declare const SECURITY_HEADERS: {
+    /** HMAC-SHA256 signature (hex encoded) */
+    readonly SIGNATURE: "x-devora-signature";
+    /** Unix timestamp in seconds when request was sent */
+    readonly SENT_AT: "x-devora-sent-at";
+    /** API Key ID (public identifier) */
+    readonly KEY_ID: "x-devora-key-id";
+    /** Organization ID */
+    readonly ORG_ID: "x-devora-org-id";
+    /** Unique request identifier used for replay prevention */
+    readonly REQUEST_ID: "x-devora-request-id";
+    /** Signature payload version */
+    readonly SIGNATURE_VERSION: "x-devora-signature-version";
+    /** Session ID (for impersonation requests) */
+    readonly SESSION_ID: "x-devora-session-id";
+};
+/**
+ * Frontend SDK headers
+ */
+export declare const FRONTEND_HEADERS: {
+    /** Client API Key */
+    readonly API_KEY: "x-devora-key";
+    /** Session ID */
+    readonly SESSION: "x-devora-session";
+    /** Short-lived impersonation-session bearer token (never the customer auth token). */
+    readonly SESSION_TOKEN: "x-devora-session-token";
+};
+/**
+ * URL parameters used for impersonation payload passing
+ */
+/**
+ * Browser-session bridge: the customer route the browser SDK calls to restore
+ * an impersonation session in a new tab. Always allowed by the scope guards
+ * because it only mints a Devora resume code for an already-authenticated
+ * customer session.
+ */
+export declare const BROWSER_SESSION_BRIDGE: {
+    /** Default customer route path. */
+    readonly PATH: "/api/devora/browser-session";
+    /** Devora endpoint the customer backend calls with a signed server request. */
+    readonly RESUME_CODE_ENDPOINT: "/api/sdk/browser-resume-code";
+    /** Devora endpoint the browser calls to redeem the code for its own capability. */
+    readonly RESUME_ENDPOINT: "/api/sdk/browser-resume";
+    /** Non-secret per-tab identifier shape (also stored in sessionStorage). */
+    readonly TAB_REF_PATTERN: RegExp;
+};
+export declare const URL_PARAMS: {
+    /** One-time code exchanged for the encrypted impersonation payload */
+    readonly EXCHANGE_CODE: "devora_exchange";
+};
+/**
+ * Default SDK configuration values
+ */
+export declare const SDK_DEFAULTS: {
+    /** Devora API origin baked into the SDK package at build time. */
+    readonly API_URL: "https://beloved-bee-737.convex.site";
+    /**
+     * The Devora dashboard origin, baked in at build time. Only a tab at this
+     * origin (or, for a customer app on loopback, a loopback dashboard) may hand
+     * an exchange verifier to the browser SDK.
+     */
+    readonly DASHBOARD_ORIGIN: "https://app.devora.sh";
+    /** Timestamp tolerance in seconds (5 minutes) */
+    readonly TIMESTAMP_TOLERANCE: 300;
+    /** Log batch size before flush */
+    readonly LOG_BATCH_SIZE: 10;
+    /** Log flush interval in milliseconds (5 seconds) */
+    readonly LOG_FLUSH_INTERVAL: 5000;
+    /** Maximum log queue size */
+    readonly MAX_LOG_QUEUE_SIZE: 100;
+};
+/**
+ * SDK package names
+ */
+export declare const SDK_PACKAGES: {
+    readonly CORE: "@devorash/core";
+    readonly NODE: "@devorash/node";
+    readonly BROWSER: "@devorash/browser";
+    readonly EXPRESS: "@devorash/express";
+    readonly HONO: "@devorash/hono";
+    readonly FASTIFY: "@devorash/fastify";
+    readonly REACT: "@devorash/react";
+    readonly VUE: "@devorash/vue";
+    readonly SVELTE: "@devorash/svelte";
+    readonly SOLID: "@devorash/solid";
+    readonly NEXT: "@devorash/nextjs";
+};
+/**
+ * Current SDK version (synced across all packages)
+ */
+export declare const SDK_VERSION = "0.1.0";
+/**
+ * SDK error codes
+ */
+export declare const ERROR_CODES: {
+    readonly MISSING_HEADERS: "DEVORA_101";
+    readonly INVALID_TIMESTAMP: "DEVORA_102";
+    readonly TIMESTAMP_EXPIRED: "DEVORA_103";
+    readonly INVALID_SIGNATURE: "DEVORA_104";
+    readonly ORG_MISMATCH: "DEVORA_105";
+    readonly KEY_NOT_FOUND: "DEVORA_106";
+    readonly KEY_REVOKED: "DEVORA_107";
+    readonly MISSING_SIGNATURE: "DEVORA_108";
+    readonly INVALID_CONFIG: "DEVORA_201";
+    readonly MISSING_ENDPOINT: "DEVORA_202";
+    readonly INVALID_HANDLER: "DEVORA_203";
+    readonly DUPLICATE_ENDPOINT: "DEVORA_204";
+    readonly BODY_TOO_LARGE: "DEVORA_205";
+    readonly INVALID_API_KEY: "DEVORA_206";
+    readonly INVALID_ORG_ID: "DEVORA_207";
+    readonly HANDLER_ERROR: "DEVORA_301";
+    readonly NETWORK_ERROR: "DEVORA_302";
+    readonly SESSION_EXPIRED: "DEVORA_303";
+    readonly TOKEN_CONSUMED: "DEVORA_304";
+    readonly SCOPE_VIOLATION: "DEVORA_401";
+    readonly WRITE_BLOCKED: "DEVORA_402";
+    readonly RATE_LIMITED: "DEVORA_501";
+    readonly TOO_MANY_REQUESTS: "DEVORA_502";
+};
+export type DevoraErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * HTTP methods considered as write operations (blocked in read-only mode)
+ */
+export declare const WRITE_METHODS: readonly ["POST", "PUT", "DELETE", "PATCH"];
+/**
+ * HTTP methods considered as read operations (allowed in read-only mode)
+ */
+export declare const READ_METHODS: readonly ["GET", "HEAD", "OPTIONS"];
+export type WriteMethod = (typeof WRITE_METHODS)[number];
+export type ReadMethod = (typeof READ_METHODS)[number];
+export * from "./sessionLifecycle.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/constants/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;IAC5B;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;CAEM,CAAA;AAEV,6BAA6B;AAC7B,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,gBAAgB,CAAA;AAE7D,+BAA+B;AAC/B,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAA;AAEzF;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,kBAAkB,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAOlF,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,kBAAkB,EAG5D,CAAA;AAMD;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC5B,0CAA0C;;IAE1C,sDAAsD;;IAEtD,qCAAqC;;IAErC,sBAAsB;;IAEtB,2DAA2D;;IAE3D,gCAAgC;;IAEhC,8CAA8C;;CAErC,CAAA;AAEV;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC5B,qBAAqB;;IAErB,iBAAiB;;IAEjB,sFAAsF;;CAE7E,CAAA;AAMV;;GAEG;AACH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;IAClC,mCAAmC;;IAEnC,+EAA+E;;IAE/E,mFAAmF;;IAEnF,2EAA2E;;CAElE,CAAA;AAEV,eAAO,MAAM,UAAU;IACtB,sEAAsE;;CAE7D,CAAA;AAQV;;GAEG;AACH,eAAO,MAAM,YAAY;IACxB,kEAAkE;;IAElE;;;;OAIG;;IAEH,iDAAiD;;IAEjD,kCAAkC;;IAElC,qDAAqD;;IAErD,6BAA6B;;CAEpB,CAAA;AAMV;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;CAYf,CAAA;AAEV;;GAEG;AACH,eAAO,MAAM,WAAW,UAAU,CAAA;AAMlC;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;CAiCd,CAAA;AAEV,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAA;AAM5E;;GAEG;AACH,eAAO,MAAM,aAAa,6CAA8C,CAAA;AAExE;;GAEG;AACH,eAAO,MAAM,YAAY,qCAAsC,CAAA;AAE/D,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AACxD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAA;AAMtD,cAAc,uBAAuB,CAAA"}