@objectstack/core 7.8.0 → 8.0.0

package/dist/index.d.cts

@@ -1668,6 +1668,59 @@ declare class PluginSecurityScanner {
     shutdown(): void;
 }
 
+/** Default visible prefix for generated keys (helps users identify a key). */
+declare const API_KEY_PREFIX = "osk_";
+/**
+ * Derive the at-rest hash for an API key. Inbound keys are hashed the same way
+ * before the DB lookup. Because the lookup matches an indexed, high-entropy
+ * hash exactly, this doubles as a constant-effort comparison: an attacker
+ * cannot recover the raw key by probing for partial matches.
+ */
+declare function hashApiKey(raw: string): string;
+/** Result of {@link generateApiKey}. `raw` is shown to the user only once. */
+interface GeneratedApiKey {
+    /** The full secret to hand to the client. NEVER persist this. */
+    raw: string;
+    /** `sha256(raw)` hex — store this in `sys_api_key.key`. */
+    hash: string;
+    /** Short non-secret prefix for display/identification (`sys_api_key.prefix`). */
+    prefix: string;
+}
+/**
+ * Generate a fresh API key. Returns the raw secret (caller must surface it to
+ * the user exactly once and then discard it), its at-rest hash, and a short
+ * non-secret prefix for display.
+ */
+declare function generateApiKey(prefix?: string): GeneratedApiKey;
+/**
+ * Extract an API key from request headers. Accepts `X-API-Key: <token>` or
+ * `Authorization: ApiKey <token>` (case-insensitive scheme). Bearer tokens are
+ * deliberately NOT treated as API keys — those flow through the session path.
+ */
+declare function extractApiKey(headers: any): string | undefined;
+/** Parse a `scopes` value that may be a JSON-string textarea or a real array. */
+declare function parseScopes(value: unknown): string[];
+/** Return true when an expiry timestamp is in the past (i.e. the key is dead). */
+declare function isExpired(value: unknown, nowMs: number): boolean;
+/** The principal resolved from a valid `sys_api_key`. */
+interface ApiKeyPrincipal {
+    userId: string;
+    tenantId?: string;
+    scopes: string[];
+}
+/**
+ * Verify an inbound API key against `sys_api_key` and resolve its principal.
+ * This is the ONE verify path shared by the dispatcher/MCP and REST surfaces.
+ *
+ * Fail-closed: returns `undefined` for a missing key, an unusable data engine,
+ * a lookup error, or a key that is unknown / revoked / expired / owner-less.
+ *
+ * @param ql      A data engine with `find(object, { where, limit, context })`.
+ * @param headers Request headers (Web `Headers` or a plain object).
+ * @param nowMs   Clock for expiry checks (injectable for tests).
+ */
+declare function resolveApiKeyPrincipal(ql: any, headers: any, nowMs?: number): Promise<ApiKeyPrincipal | undefined>;
+
 /**
  * Environment utilities for universal (Node/Browser) compatibility.
  */
@@ -2080,4 +2133,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-export { ApiRegistry, type ApiRegistryPluginConfig, CORE_FALLBACK_FACTORIES, DependencyResolver, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, generateEd25519KeyPair, getEnv, getMemoryUsage, isNode, parseSignature, resolveLocale, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };
+export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, CORE_FALLBACK_FACTORIES, DependencyResolver, type GeneratedApiKey, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isExpired, isNode, parseScopes, parseSignature, resolveApiKeyPrincipal, resolveLocale, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };

package/dist/index.d.ts

@@ -1668,6 +1668,59 @@ declare class PluginSecurityScanner {
     shutdown(): void;
 }
 
+/** Default visible prefix for generated keys (helps users identify a key). */
+declare const API_KEY_PREFIX = "osk_";
+/**
+ * Derive the at-rest hash for an API key. Inbound keys are hashed the same way
+ * before the DB lookup. Because the lookup matches an indexed, high-entropy
+ * hash exactly, this doubles as a constant-effort comparison: an attacker
+ * cannot recover the raw key by probing for partial matches.
+ */
+declare function hashApiKey(raw: string): string;
+/** Result of {@link generateApiKey}. `raw` is shown to the user only once. */
+interface GeneratedApiKey {
+    /** The full secret to hand to the client. NEVER persist this. */
+    raw: string;
+    /** `sha256(raw)` hex — store this in `sys_api_key.key`. */
+    hash: string;
+    /** Short non-secret prefix for display/identification (`sys_api_key.prefix`). */
+    prefix: string;
+}
+/**
+ * Generate a fresh API key. Returns the raw secret (caller must surface it to
+ * the user exactly once and then discard it), its at-rest hash, and a short
+ * non-secret prefix for display.
+ */
+declare function generateApiKey(prefix?: string): GeneratedApiKey;
+/**
+ * Extract an API key from request headers. Accepts `X-API-Key: <token>` or
+ * `Authorization: ApiKey <token>` (case-insensitive scheme). Bearer tokens are
+ * deliberately NOT treated as API keys — those flow through the session path.
+ */
+declare function extractApiKey(headers: any): string | undefined;
+/** Parse a `scopes` value that may be a JSON-string textarea or a real array. */
+declare function parseScopes(value: unknown): string[];
+/** Return true when an expiry timestamp is in the past (i.e. the key is dead). */
+declare function isExpired(value: unknown, nowMs: number): boolean;
+/** The principal resolved from a valid `sys_api_key`. */
+interface ApiKeyPrincipal {
+    userId: string;
+    tenantId?: string;
+    scopes: string[];
+}
+/**
+ * Verify an inbound API key against `sys_api_key` and resolve its principal.
+ * This is the ONE verify path shared by the dispatcher/MCP and REST surfaces.
+ *
+ * Fail-closed: returns `undefined` for a missing key, an unusable data engine,
+ * a lookup error, or a key that is unknown / revoked / expired / owner-less.
+ *
+ * @param ql      A data engine with `find(object, { where, limit, context })`.
+ * @param headers Request headers (Web `Headers` or a plain object).
+ * @param nowMs   Clock for expiry checks (injectable for tests).
+ */
+declare function resolveApiKeyPrincipal(ql: any, headers: any, nowMs?: number): Promise<ApiKeyPrincipal | undefined>;
+
 /**
  * Environment utilities for universal (Node/Browser) compatibility.
  */
@@ -2080,4 +2133,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-export { ApiRegistry, type ApiRegistryPluginConfig, CORE_FALLBACK_FACTORIES, DependencyResolver, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, generateEd25519KeyPair, getEnv, getMemoryUsage, isNode, parseSignature, resolveLocale, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };
+export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, CORE_FALLBACK_FACTORIES, DependencyResolver, type GeneratedApiKey, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isExpired, isNode, parseScopes, parseSignature, resolveApiKeyPrincipal, resolveLocale, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };

package/dist/index.js

@@ -3884,6 +3884,109 @@ var PluginSecurityScanner = class {
   }
 };
 
+// src/security/api-key.ts
+import { createHash, randomBytes } from "crypto";
+var API_KEY_PREFIX = "osk_";
+var API_KEY_ENTROPY_BYTES = 32;
+var VISIBLE_PREFIX_LEN = 12;
+function hashApiKey(raw) {
+  return createHash("sha256").update(raw, "utf8").digest("hex");
+}
+function generateApiKey(prefix = API_KEY_PREFIX) {
+  const secret = randomBytes(API_KEY_ENTROPY_BYTES).toString("base64url");
+  const raw = `${prefix}${secret}`;
+  return {
+    raw,
+    hash: hashApiKey(raw),
+    prefix: raw.slice(0, VISIBLE_PREFIX_LEN)
+  };
+}
+function extractApiKey(headers) {
+  const x = readHeader(headers, "x-api-key");
+  if (x && x.trim()) return x.trim();
+  const auth = readHeader(headers, "authorization");
+  if (!auth) return void 0;
+  const m = auth.match(/^ApiKey\s+(.+)$/i);
+  const token = m?.[1]?.trim();
+  return token || void 0;
+}
+function parseScopes(value) {
+  if (Array.isArray(value)) {
+    return value.filter((s) => typeof s === "string" && s.length > 0);
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = safeJsonParse(value, []);
+    if (Array.isArray(parsed)) {
+      return parsed.filter((s) => typeof s === "string" && s.length > 0);
+    }
+  }
+  return [];
+}
+function isExpired(value, nowMs) {
+  if (value == null) return false;
+  let ms;
+  if (typeof value === "number") {
+    ms = value < 1e12 ? value * 1e3 : value;
+  } else if (value instanceof Date) {
+    ms = value.getTime();
+  } else if (typeof value === "string") {
+    ms = Date.parse(value);
+  } else {
+    return false;
+  }
+  if (Number.isNaN(ms)) return false;
+  return ms <= nowMs;
+}
+async function resolveApiKeyPrincipal(ql, headers, nowMs = Date.now()) {
+  const apiKey = extractApiKey(headers);
+  if (!apiKey) return void 0;
+  if (!ql || typeof ql.find !== "function") return void 0;
+  let rows;
+  try {
+    rows = await ql.find("sys_api_key", {
+      where: { key: hashApiKey(apiKey), revoked: false },
+      limit: 1,
+      context: { isSystem: true }
+    });
+  } catch {
+    return void 0;
+  }
+  if (rows && rows.value) rows = rows.value;
+  const row = Array.isArray(rows) ? rows[0] : void 0;
+  if (!row || row.revoked === true) return void 0;
+  const expiresAt = row.expires_at ?? row.expiresAt;
+  if (isExpired(expiresAt, nowMs)) return void 0;
+  const userId = row.user_id ?? row.userId;
+  if (!userId || typeof userId !== "string") return void 0;
+  return {
+    userId,
+    tenantId: row.organization_id ?? row.organizationId ?? void 0,
+    scopes: parseScopes(row.scopes)
+  };
+}
+function readHeader(headers, name) {
+  if (!headers) return void 0;
+  const lower = name.toLowerCase();
+  if (typeof headers.get === "function") {
+    const v = headers.get(name) ?? headers.get(lower);
+    return v == null ? void 0 : String(v);
+  }
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === lower) {
+      const v = headers[key];
+      return Array.isArray(v) ? v[0] : v == null ? void 0 : String(v);
+    }
+  }
+  return void 0;
+}
+function safeJsonParse(s, fallback) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return fallback;
+  }
+}
+
 // src/health-monitor.ts
 var PluginHealthMonitor = class {
   constructor(logger) {
@@ -4127,7 +4230,7 @@ var PluginHealthMonitor = class {
 };
 
 // src/hot-reload.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 var generateUUID = () => {
   if (typeof crypto !== "undefined" && crypto.randomUUID) {
     return crypto.randomUUID();
@@ -4222,7 +4325,7 @@ var PluginStateManager = class {
    */
   calculateChecksum(state) {
     const stateStr = JSON.stringify(state);
-    return createHash("sha256").update(stateStr).digest("hex");
+    return createHash2("sha256").update(stateStr).digest("hex");
   }
   /**
    * Shutdown state manager
@@ -4798,6 +4901,7 @@ var NamespaceResolver = class {
   }
 };
 export {
+  API_KEY_PREFIX,
   ApiRegistry,
   CORE_FALLBACK_FACTORIES,
   DependencyResolver,
@@ -4831,11 +4935,17 @@ export {
   createMemoryQueue,
   createPluginConfigValidator,
   createPluginPermissionEnforcer,
+  extractApiKey,
+  generateApiKey,
   generateEd25519KeyPair,
   getEnv,
   getMemoryUsage,
+  hashApiKey,
+  isExpired,
   isNode,
+  parseScopes,
   parseSignature,
+  resolveApiKeyPrincipal,
   resolveLocale,
   safeExit,
   signPayload,