khotan-data 0.1.1 → 0.3.0

package/dist/factory.d.cts

@@ -1,5 +1,12 @@
 import { PgDatabase } from 'drizzle-orm/pg-core';
 
+/**
+ * Derives the CLI auth token: HMAC-SHA256 over the timestamp, keyed by the
+ * KHOTAN_SECRET. One-way, so the raw secret (the encryption key) never travels
+ * over the wire — even a token captured from a dev log can't be reversed into
+ * the secret. Exported so the CLI can compute the same value.
+ */
+declare function deriveCliToken(secret: string, timestamp: string): Promise<string>;
 type ResourceConnectField = string | [string, ...string[]];
 interface ResourcePlugParticipation {
     uniqueIdentifier: string;
@@ -551,12 +558,50 @@ interface KhotanAdapter {
         lastRunStatus: KhotanTerminalRunStatus;
     }): Promise<void>;
 }
+/**
+ * Authorize an incoming request to the khotan management API.
+ *
+ * Return `true` to allow the request, `false` to reject it with `401`.
+ * The function receives the raw `Request`, so it composes directly with
+ * session libraries such as better-auth:
+ *
+ * ```ts
+ * authorize: async (request) => {
+ *   const session = await auth.api.getSession({ headers: request.headers });
+ *   return session?.user?.role === "admin";
+ * }
+ * ```
+ *
+ * Throwing is treated the same as returning `false`. A rejected request gets a
+ * `401` whose JSON body includes `code: "authorize_rejected"` and a `hint`
+ * describing the auth model (useful for programmatic callers).
+ *
+ * NOTE: `KHOTAN_SECRET` is an encryption key, NOT an HTTP credential. Sending it
+ * as a `Bearer` token does not authenticate a request — only `authorize` (and
+ * the dev-only `KhotanCLI` HMAC token used by the local CLI) can. To trigger a
+ * flow from outside the app, either call `khotanData.flow(name).start()` from
+ * server code, or send a credential your `authorize` hook accepts.
+ *
+ * The following routes are intentionally exempt and are NOT passed to
+ * `authorize` (they have their own protection):
+ * - Inbound webhooks (`POST .../webhook/:plug`) — verified per-plug via `onVerify`.
+ * - The cron dispatcher (`.../cron`) — protected by `CRON_SECRET`.
+ * - Debug routes (`.../debug...`) — gated by `KHOTAN_DEBUG` and disabled in production.
+ */
+type KhotanAuthorize = (request: Request) => boolean | Promise<boolean>;
 interface KhotanConfig {
     adapter: KhotanAdapter;
     plugs: PlugRegistration[];
     resources?: ResourceRegistration[];
     caches?: CacheRegistration[];
     secret?: string;
+    /**
+     * Gate every management route (plugs, variables, flows, runs, wires,
+     * mappings, caches, resources, webhook handlers/events) behind a custom
+     * authorization check. Strongly recommended for any deployed app — without
+     * it the management API is publicly accessible. See {@link KhotanAuthorize}.
+     */
+    authorize?: KhotanAuthorize;
 }
 type KhotanHandler = (request: Request) => Promise<Response>;
 interface WireInstance {
@@ -659,4 +704,4 @@ interface NextJsRouteHandlers {
 }
 declare function toNextJsHandler(factoryHandler: KhotanHandler): NextJsRouteHandlers;
 
-export { type BindablePlug, type BoundPlug, type CacheEntryRecord, type CacheInstance, type CacheRegistration, type CacheScope, type CatchRegistration, type CatchWorkflowContext, type FlowInstance, type FlowRegistration, type FlowRunContext, type FlowRunResult, type FlowSelectorOptions, type FlowStartOptions, type FlowType, type FlowWorkflowContext, type KhotanAdapter, type KhotanConfig, type KhotanHandler, type KhotanInstance, type KhotanRunStatus, type KhotanRunUpdate, type KhotanTerminalRunStatus, type PassRegistration, type PassWorkflowContext, type PlugRegistration, type ResourceConnectField, type ResourceMappingRegistration, type ResourcePlugParticipation, type ResourceRegistration, type VarField, type WebhookRegistration, type WireInstance, type WireRegistration, type WireSubscribeContext, type WireUnsubscribeContext, type WireVerifyContext, __setWorkflowGetRunForTests, __setWorkflowGetWritableForTests, __setWorkflowStartForTests, bindWorkflowPlug, drizzleAdapter, khotan, khotanCache, khotanMappings, sendUpdate, toNextJsHandler };
+export { type BindablePlug, type BoundPlug, type CacheEntryRecord, type CacheInstance, type CacheRegistration, type CacheScope, type CatchRegistration, type CatchWorkflowContext, type FlowInstance, type FlowRegistration, type FlowRunContext, type FlowRunResult, type FlowSelectorOptions, type FlowStartOptions, type FlowType, type FlowWorkflowContext, type KhotanAdapter, type KhotanAuthorize, type KhotanConfig, type KhotanHandler, type KhotanInstance, type KhotanRunStatus, type KhotanRunUpdate, type KhotanTerminalRunStatus, type PassRegistration, type PassWorkflowContext, type PlugRegistration, type ResourceConnectField, type ResourceMappingRegistration, type ResourcePlugParticipation, type ResourceRegistration, type VarField, type WebhookRegistration, type WireInstance, type WireRegistration, type WireSubscribeContext, type WireUnsubscribeContext, type WireVerifyContext, __setWorkflowGetRunForTests, __setWorkflowGetWritableForTests, __setWorkflowStartForTests, bindWorkflowPlug, deriveCliToken, drizzleAdapter, khotan, khotanCache, khotanMappings, sendUpdate, toNextJsHandler };

package/dist/factory.d.ts

@@ -1,5 +1,12 @@
 import { PgDatabase } from 'drizzle-orm/pg-core';
 
+/**
+ * Derives the CLI auth token: HMAC-SHA256 over the timestamp, keyed by the
+ * KHOTAN_SECRET. One-way, so the raw secret (the encryption key) never travels
+ * over the wire — even a token captured from a dev log can't be reversed into
+ * the secret. Exported so the CLI can compute the same value.
+ */
+declare function deriveCliToken(secret: string, timestamp: string): Promise<string>;
 type ResourceConnectField = string | [string, ...string[]];
 interface ResourcePlugParticipation {
     uniqueIdentifier: string;
@@ -551,12 +558,50 @@ interface KhotanAdapter {
         lastRunStatus: KhotanTerminalRunStatus;
     }): Promise<void>;
 }
+/**
+ * Authorize an incoming request to the khotan management API.
+ *
+ * Return `true` to allow the request, `false` to reject it with `401`.
+ * The function receives the raw `Request`, so it composes directly with
+ * session libraries such as better-auth:
+ *
+ * ```ts
+ * authorize: async (request) => {
+ *   const session = await auth.api.getSession({ headers: request.headers });
+ *   return session?.user?.role === "admin";
+ * }
+ * ```
+ *
+ * Throwing is treated the same as returning `false`. A rejected request gets a
+ * `401` whose JSON body includes `code: "authorize_rejected"` and a `hint`
+ * describing the auth model (useful for programmatic callers).
+ *
+ * NOTE: `KHOTAN_SECRET` is an encryption key, NOT an HTTP credential. Sending it
+ * as a `Bearer` token does not authenticate a request — only `authorize` (and
+ * the dev-only `KhotanCLI` HMAC token used by the local CLI) can. To trigger a
+ * flow from outside the app, either call `khotanData.flow(name).start()` from
+ * server code, or send a credential your `authorize` hook accepts.
+ *
+ * The following routes are intentionally exempt and are NOT passed to
+ * `authorize` (they have their own protection):
+ * - Inbound webhooks (`POST .../webhook/:plug`) — verified per-plug via `onVerify`.
+ * - The cron dispatcher (`.../cron`) — protected by `CRON_SECRET`.
+ * - Debug routes (`.../debug...`) — gated by `KHOTAN_DEBUG` and disabled in production.
+ */
+type KhotanAuthorize = (request: Request) => boolean | Promise<boolean>;
 interface KhotanConfig {
     adapter: KhotanAdapter;
     plugs: PlugRegistration[];
     resources?: ResourceRegistration[];
     caches?: CacheRegistration[];
     secret?: string;
+    /**
+     * Gate every management route (plugs, variables, flows, runs, wires,
+     * mappings, caches, resources, webhook handlers/events) behind a custom
+     * authorization check. Strongly recommended for any deployed app — without
+     * it the management API is publicly accessible. See {@link KhotanAuthorize}.
+     */
+    authorize?: KhotanAuthorize;
 }
 type KhotanHandler = (request: Request) => Promise<Response>;
 interface WireInstance {
@@ -659,4 +704,4 @@ interface NextJsRouteHandlers {
 }
 declare function toNextJsHandler(factoryHandler: KhotanHandler): NextJsRouteHandlers;
 
-export { type BindablePlug, type BoundPlug, type CacheEntryRecord, type CacheInstance, type CacheRegistration, type CacheScope, type CatchRegistration, type CatchWorkflowContext, type FlowInstance, type FlowRegistration, type FlowRunContext, type FlowRunResult, type FlowSelectorOptions, type FlowStartOptions, type FlowType, type FlowWorkflowContext, type KhotanAdapter, type KhotanConfig, type KhotanHandler, type KhotanInstance, type KhotanRunStatus, type KhotanRunUpdate, type KhotanTerminalRunStatus, type PassRegistration, type PassWorkflowContext, type PlugRegistration, type ResourceConnectField, type ResourceMappingRegistration, type ResourcePlugParticipation, type ResourceRegistration, type VarField, type WebhookRegistration, type WireInstance, type WireRegistration, type WireSubscribeContext, type WireUnsubscribeContext, type WireVerifyContext, __setWorkflowGetRunForTests, __setWorkflowGetWritableForTests, __setWorkflowStartForTests, bindWorkflowPlug, drizzleAdapter, khotan, khotanCache, khotanMappings, sendUpdate, toNextJsHandler };
+export { type BindablePlug, type BoundPlug, type CacheEntryRecord, type CacheInstance, type CacheRegistration, type CacheScope, type CatchRegistration, type CatchWorkflowContext, type FlowInstance, type FlowRegistration, type FlowRunContext, type FlowRunResult, type FlowSelectorOptions, type FlowStartOptions, type FlowType, type FlowWorkflowContext, type KhotanAdapter, type KhotanAuthorize, type KhotanConfig, type KhotanHandler, type KhotanInstance, type KhotanRunStatus, type KhotanRunUpdate, type KhotanTerminalRunStatus, type PassRegistration, type PassWorkflowContext, type PlugRegistration, type ResourceConnectField, type ResourceMappingRegistration, type ResourcePlugParticipation, type ResourceRegistration, type VarField, type WebhookRegistration, type WireInstance, type WireRegistration, type WireSubscribeContext, type WireUnsubscribeContext, type WireVerifyContext, __setWorkflowGetRunForTests, __setWorkflowGetWritableForTests, __setWorkflowStartForTests, bindWorkflowPlug, deriveCliToken, drizzleAdapter, khotan, khotanCache, khotanMappings, sendUpdate, toNextJsHandler };

package/dist/factory.js

@@ -259,6 +259,47 @@ function hexToBytes(hex) {
 function bytesToHex(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+var CLI_TOKEN_SCHEME = "KhotanCLI";
+var CLI_TOKEN_WINDOW_MS = 6e4;
+async function deriveCliToken(secret, timestamp2) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(`khotan-cli:${timestamp2}`)
+  );
+  return bytesToHex(new Uint8Array(sig));
+}
+function timingSafeEqualHex(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+async function isCliRequestAuthorized(request, secret) {
+  if (process.env["NODE_ENV"] === "production") return false;
+  if (!secret) return false;
+  const header = request.headers.get("authorization");
+  if (!header?.startsWith(`${CLI_TOKEN_SCHEME} `)) return false;
+  const token = header.slice(CLI_TOKEN_SCHEME.length + 1).trim();
+  const dotIdx = token.indexOf(".");
+  if (dotIdx === -1) return false;
+  const timestamp2 = token.slice(0, dotIdx);
+  const provided = token.slice(dotIdx + 1);
+  const ts = Number.parseInt(timestamp2, 10);
+  if (!Number.isFinite(ts)) return false;
+  if (Math.abs(Date.now() - ts) > CLI_TOKEN_WINDOW_MS) return false;
+  const expected = await deriveCliToken(secret, timestamp2);
+  return timingSafeEqualHex(provided, expected);
+}
 function bindPlugWithVars(plug, vars, setVars) {
   const opts = (extra) => ({
     ...extra,
@@ -1104,9 +1145,14 @@ function coerceDate(value) {
 }
 function isCronRequestAuthorized(request) {
   const secret = process.env["CRON_SECRET"]?.trim();
-  if (!secret) return true;
+  if (!secret) {
+    return process.env["NODE_ENV"] !== "production";
+  }
   return request.headers.get("authorization") === `Bearer ${secret}`;
 }
+function isDebugEnabled() {
+  return Boolean(process?.env?.["KHOTAN_DEBUG"]) && process?.env?.["NODE_ENV"] !== "production";
+}
 function isWorkflowCancelledError(error) {
   if (!error || typeof error !== "object") return false;
   const record = error;
@@ -1400,8 +1446,18 @@ function canonicalizeConnectValue(resource, connectValue) {
   );
 }
 function khotan(config) {
-  const { adapter, plugs, resources = [], caches = [] } = config;
+  const { adapter, plugs, resources = [], caches = [], authorize } = config;
   const instanceId = crypto.randomUUID();
+  if (!authorize) {
+    console.warn(
+      "[khotan] No `authorize` hook configured: the management API (/api/khotan/*) is publicly accessible. Pass `authorize` to gate it behind your auth layer (e.g. better-auth). This is required for any deployed environment."
+    );
+  }
+  if (!(config.secret ?? process.env["KHOTAN_SECRET"])) {
+    console.warn(
+      "[khotan] No `secret`/`KHOTAN_SECRET` configured: plug credentials and wire metadata will not be encrypted at rest. Set KHOTAN_SECRET to a high-entropy value."
+    );
+  }
   const plugNames = /* @__PURE__ */ new Set();
   for (const plug of plugs) {
     if (plugNames.has(plug.name)) {
@@ -2228,7 +2284,31 @@ function khotan(config) {
     const webhookEventsIdx = segments.indexOf("webhook-events");
     const variablesIdx = segments.indexOf("variables");
     const cronIdx = segments.indexOf("cron");
+    const webhookIdx = segments.indexOf("webhook");
     const debugIdx = segments.indexOf("debug");
+    const isInboundWebhook = webhookIdx !== -1 && webhookIdx === segments.length - 2;
+    const isCronRoute = cronIdx !== -1 && cronIdx === segments.length - 1;
+    const isDebugRoute = debugIdx !== -1;
+    if (authorize && !isInboundWebhook && !isCronRoute && !isDebugRoute) {
+      let allowed = await isCliRequestAuthorized(request, secret);
+      if (!allowed) {
+        try {
+          allowed = await authorize(request);
+        } catch {
+          allowed = false;
+        }
+      }
+      if (!allowed) {
+        return Response.json(
+          {
+            error: "Unauthorized",
+            code: "authorize_rejected",
+            hint: "Management routes (/api/khotan/*) require your `authorize` hook to pass. KHOTAN_SECRET is an encryption key, not an HTTP credential \u2014 sending it as a Bearer token will not authenticate the request. To trigger a flow: call khotanData.flow(name).start() from server code (no HTTP/auth needed), or send a credential your authorize hook accepts (e.g. a session cookie or your own token). The khotan CLI authenticates automatically via a dev-only token derived from KHOTAN_SECRET."
+          },
+          { status: 401 }
+        );
+      }
+    }
     const limit = Math.min(
       Math.max(
         Number.parseInt(url.searchParams.get("limit") ?? "20", 10) || 20,
@@ -2270,15 +2350,13 @@ function khotan(config) {
         return Response.json(result);
       }
       if (debugIdx !== -1 && debugIdx === segments.length - 1) {
-        const debugActive = process?.env?.["KHOTAN_DEBUG"];
-        if (!debugActive) {
+        if (!isDebugEnabled()) {
           return Response.json({ error: "Not found" }, { status: 404 });
         }
         return Response.json({ enabled: true });
       }
       if (debugIdx !== -1 && debugIdx === segments.length - 2) {
-        const debugActive = process?.env?.["KHOTAN_DEBUG"];
-        if (!debugActive) {
+        if (!isDebugEnabled()) {
           return Response.json({ error: "Not found" }, { status: 404 });
         }
         const plugName = segments[debugIdx + 1];
@@ -2580,7 +2658,6 @@ function khotan(config) {
         const result = await dispatchScheduledFlows({ runType });
         return Response.json(result);
       }
-      const webhookIdx = segments.indexOf("webhook");
       if (webhookIdx !== -1 && webhookIdx === segments.length - 2) {
         const plugName = segments[webhookIdx + 1];
         const plugReg = plugs.find((p) => p.name === plugName);
@@ -2797,8 +2874,7 @@ function khotan(config) {
         return Response.json({ received: true }, { status: 202 });
       }
       if (debugIdx !== -1 && debugIdx === segments.length - 2) {
-        const debugActive = process?.env?.["KHOTAN_DEBUG"];
-        if (!debugActive) {
+        if (!isDebugEnabled()) {
           return Response.json({ error: "Not found" }, { status: 404 });
         }
         const plugName = segments[debugIdx + 1];
@@ -3287,6 +3363,6 @@ function toNextJsHandler(factoryHandler) {
   };
 }
 
-export { __setWorkflowGetRunForTests, __setWorkflowGetWritableForTests, __setWorkflowStartForTests, bindWorkflowPlug, drizzleAdapter, khotan, khotanCache, khotanMappings, sendUpdate, toNextJsHandler };
+export { __setWorkflowGetRunForTests, __setWorkflowGetWritableForTests, __setWorkflowStartForTests, bindWorkflowPlug, deriveCliToken, drizzleAdapter, khotan, khotanCache, khotanMappings, sendUpdate, toNextJsHandler };
 //# sourceMappingURL=factory.js.map
 //# sourceMappingURL=factory.js.map