every-plugin 2.7.1 → 2.9.0

package/skills/plugin-client/references/api-keys.md

@@ -0,0 +1,145 @@
+# API Keys Reference
+
+## Route Table
+
+All routes are exposed via the Better-Auth `apiKeyClient()` plugin (not the oRPC `apiClient`). Call them through `authClient.apiKey.*`:
+
+| Method | Input | Output | Notes |
+|--------|-------|--------|-------|
+| `list` | `{ organizationId?, limit?, offset?, sortBy?, sortDirection?, configId? }` | `ApiKey[]` | Returns metadata only — no secret |
+| `create` | `{ name?, prefix?, expiresIn?, permissions?, metadata?, rateLimit?, organizationId?, configId? }` | `ApiKey & { key: string }` | Full secret returned **once** |
+| `update` | `{ id, name?, enabled?, permissions?, metadata?, expiresIn?, rateLimit? }` | `ApiKey` | No secret returned |
+| `delete` | `{ id }` | `{ success: boolean }` | Irreversible |
+
+### UI Usage
+
+```ts
+const authClient = useAuthClient();
+
+// List keys for an organization
+const { data } = await authClient.apiKey.list({
+  query: { configId: "org-keys", organizationId: orgId },
+});
+const keys = data?.apiKeys ?? [];
+
+// Create a key
+const { data, error } = await authClient.apiKey.create({
+  configId: "org-keys",
+  organizationId: orgId,
+  name: "CI deploy key",
+  expiresIn: 60 * 60 * 24 * 30,  // 30 days
+});
+if (data) {
+  saveSecret(data.apiKey.key);  // "edk_xxxxx..." — only available here
+}
+
+// Delete a key
+const { error } = await authClient.apiKey.delete({
+  keyId: "key_abc123",
+  configId: "org-keys",
+});
+```
+
+## ApiKey Shape
+
+```ts
+type ApiKey = {
+  id: string;
+  name: string | null;
+  prefix: string;          // first chars for identification (e.g., "edk_abc")
+  enabled: boolean;
+  permissions: Record<string, string[]> | null;  // resource → actions
+  requestCount: number;
+  expiresAt: number | null;  // epoch seconds
+  metadata: Record<string, unknown> | null;
+  rateLimit: { limit: number; window: number } | null;
+};
+```
+
+## Permission Schema
+
+Permissions are a map of resource name to allowed action arrays:
+
+```ts
+{
+  things: ["create", "read", "delete"],
+  projects: ["read"],
+  registry: ["publish", "relay"],
+}
+```
+
+### Server-Side Permission Checks
+
+`requireApiKey(requiredPermissions)` validates that the presented key's `permissions` cover all required entries:
+
+```ts
+const { requireApiKey } = createAuthMiddleware(builder);
+
+builder.deleteThing
+  .use(requireApiKey({ things: ["delete"] }))
+  .handler(async ({ context }) => {
+    context.apiKey;        // ApiKeyContext — non-null, narrowed by middleware
+    context.apiKey.permissions;  // Record<string, string[]>
+  });
+```
+
+If any required action is missing, throws `FORBIDDEN` with:
+
+```ts
+{
+  message: "API key lacks permission: things:delete",
+  data: { requiredPermissions, keyPermissions },
+}
+```
+
+### Multi-Resource Permissions
+
+```ts
+builder.deployApp
+  .use(requireApiKey({
+    registry: ["publish"],
+    projects: ["update"],
+  }))
+  .handler(...)
+```
+
+All specified resources must be satisfied — partial matches are rejected.
+
+## Key Lifecycle
+
+1. **Create** — `authClient.apiKey.create()` returns `{ ...apiKey, key }`. The `key` field is the full secret (`edk_...`). Save it now — it is never returned again.
+2. **Identify** — subsequent `list` / `update` calls return only `prefix` (first few chars) for identification.
+3. **Disable** — `update({ id, enabled: false })` revokes the key without deleting it.
+4. **Delete** — `delete({ id })` permanently removes the key.
+
+## Scoping
+
+### `configId`
+
+Keys can be grouped under a config ID (e.g., `"org-keys"`). This is an opaque label for organizing keys by purpose. Pass the same `configId` on create, list, and delete.
+
+### `organizationId`
+
+Keys scoped to an organization inherit the org's context. The host's session middleware resolves the active organization from the session, and `requireOrganization` / `requireOrgRole` middlewares check org membership.
+
+## Browser vs Server Limitations
+
+Permissions, rate limits, and refill configuration are **server-only** — they cannot be set from the browser client. The `create` call from the UI accepts `name`, `expiresIn`, `permissions` (if allowed), and `metadata`. Server-side key management (e.g., via a plugin route) can set the full set of options.
+
+## Auth Context
+
+When an API key is validated, the host's `getContext()` populates:
+
+```ts
+{
+  authMethod: "apiKey",
+  apiKey: {
+    id: "key_abc123",
+    name: "CI deploy key",
+    permissions: { things: ["create", "read"], ... },
+  },
+  // user, organization, etc. are null unless the key is tied to a user/org
+}
+```
+
+The `authMethod` field is one of `"session" | "anonymous" | "apiKey" | "none"`. Plugin routes can branch on this to customize responses for programmatic vs interactive access.

package/src/build/rspack/dev-server-middleware.ts

@@ -74,7 +74,8 @@ export function setupPluginMiddleware(
       handlers.rpc = new RPCHandler(loaded.router, {
         interceptors: [
           onError((error: any) => {
-            formatORPCError(error);
+            const formatted = formatORPCError(error);
+            if (formatted) console.error(formatted);
           }),
         ],
       });
@@ -87,7 +88,8 @@ export function setupPluginMiddleware(
         ],
         interceptors: [
           onError((error: any) => {
-            formatORPCError(error);
+            const formatted = formatORPCError(error);
+            if (formatted) console.error(formatted);
           }),
         ],
       });

package/src/plugin.ts

@@ -173,7 +173,8 @@ export const createPlugin: CreatePluginFn = function createPlugin<
           throw unwrapped;
         }
 
-        formatORPCError(error);
+        const formatted = formatORPCError(error);
+        if (formatted) console.error(formatted);
         throw error;
       }) as any;
 

package/src/runtime/errors.ts

@@ -116,15 +116,14 @@ const formatORPCValidationError = (error: any): string[] | null => {
   return lines;
 };
 
-export const formatORPCError = (error: any): void => {
+export const formatORPCError = (error: any): string | null => {
   if (!(error instanceof ORPCError)) {
-    return;
+    return null;
   }
 
   const validationLines = formatORPCValidationError(error);
   if (validationLines) {
-    console.error(validationLines.join("\n"));
-    return;
+    return validationLines.join("\n");
   }
 
   const lines: string[] = [];
@@ -182,49 +181,7 @@ export const formatORPCError = (error: any): void => {
   }
 
   lines.push(`╰${"─".repeat(50)}\n`);
-  console.error(lines.join("\n"));
-};
-
-const formatPluginError = (
-  pluginId: string | undefined,
-  operation: string | undefined,
-  message: string,
-): void => {
-  const lines: string[] = [];
-
-  lines.push(`\n╭─ Plugin Error ${"─".repeat(40)}`);
-  if (pluginId) lines.push(`│  Plugin: ${pluginId}`);
-  if (operation) lines.push(`│  During: ${operation}`);
-  lines.push(`│`);
-
-  if (message.includes("ECONNREFUSED")) {
-    lines.push(`│  ❌ Connection refused`);
-    lines.push(`│  `);
-    lines.push(`│  A required service is not running.`);
-    lines.push(`│  → Run: docker compose up -d`);
-  } else if (message.includes("ENOTFOUND")) {
-    lines.push(`│  ❌ Host not found`);
-    lines.push(`│  `);
-    lines.push(`│  Check your connection URL or network settings.`);
-  } else if (message.includes("ETIMEDOUT") || message.includes("timeout")) {
-    lines.push(`│  ❌ Connection timeout`);
-    lines.push(`│  `);
-    lines.push(`│  The service took too long to respond.`);
-  } else if (message.includes("EACCES") || message.includes("permission")) {
-    lines.push(`│  ❌ Permission denied`);
-    lines.push(`│  `);
-    lines.push(`│  Check credentials or access permissions.`);
-  } else if (message.includes("401") || message.includes("unauthorized")) {
-    lines.push(`│  ❌ Authentication failed`);
-    lines.push(`│  `);
-    lines.push(`│  Check your API key or credentials.`);
-  } else {
-    lines.push(`│  ❌ ${message}`);
-  }
-
-  lines.push(`╰${"─".repeat(50)}\n`);
-
-  console.error(lines.join("\n"));
+  return lines.join("\n");
 };
 
 const isRetryableError = (message: string): boolean => {
@@ -253,11 +210,6 @@ export const wrapORPCError = (
   procedureName?: string,
   operation?: string,
 ): PluginRuntimeError => {
-  const validationLines = formatORPCValidationError(orpcError);
-  if (validationLines) {
-    console.error(validationLines.join("\n"));
-  }
-
   return new PluginRuntimeError({
     pluginId,
     operation,
@@ -314,14 +266,6 @@ export const toPluginRuntimeError = (
     return error;
   }
 
-  const validationLines = formatORPCValidationError(error);
-  if (validationLines) {
-    console.error(validationLines.join("\n"));
-  } else {
-    const message = extractErrorMessage(error);
-    formatPluginError(pluginId, operation, message);
-  }
-
   return new PluginRuntimeError({
     pluginId,
     operation,

package/src/runtime/index.ts

@@ -84,7 +84,7 @@ export class PluginRuntime<R = RegisteredPlugins> {
         const initialized = yield* pluginService.initializePlugin(instance, config, plugins);
 
         return initialized;
-      }).pipe(Effect.provide(this.runtime));
+      }).pipe(Effect.annotateLogs({ plugin: pluginId }), Effect.provide(this.runtime));
 
       cachedPlugin = Effect.cached(operation).pipe(Effect.flatten);
       this.pluginCache.set(cacheKey, cachedPlugin);
@@ -112,7 +112,7 @@ export class PluginRuntime<R = RegisteredPlugins> {
     const effect = Effect.gen(function* () {
       const pluginService = yield* PluginService;
       return yield* pluginService.loadPlugin(pluginId);
-    });
+    }).pipe(Effect.annotateLogs({ plugin: pluginId }));
     return this.runPromise(effect) as Promise<LoadedPlugin<RegisteredPlugin<K, R>>>;
   }
 
@@ -123,7 +123,7 @@ export class PluginRuntime<R = RegisteredPlugins> {
     const effect = Effect.gen(function* () {
       const pluginService = yield* PluginService;
       return yield* pluginService.instantiatePlugin(pluginId, loadedPlugin);
-    });
+    }).pipe(Effect.annotateLogs({ plugin: pluginId }));
     return this.runPromise(effect) as Promise<PluginInstance<RegisteredPlugin<K, R>>>;
   }
 
@@ -135,7 +135,7 @@ export class PluginRuntime<R = RegisteredPlugins> {
     const effect = Effect.gen(function* () {
       const pluginService = yield* PluginService;
       return yield* pluginService.initializePlugin(instance, config, plugins);
-    });
+    }).pipe(Effect.annotateLogs({ plugin: instance.plugin.id }));
     return this.runPromise(effect);
   }
 

package/src/runtime/services/module-federation.service.ts

@@ -86,7 +86,7 @@ export class ModuleFederationService extends Effect.Service<ModuleFederationServ
       return {
         registerRemote: (pluginId: string, url: string) =>
           Effect.gen(function* () {
-            console.log(`[MF] Registering ${pluginId}`);
+            yield* Effect.logDebug(`[MF] Registering ${pluginId}`);
 
             const remoteName = getNormalizedRemoteName(pluginId);
             const type = url.endsWith("/mf-manifest.json")
@@ -112,16 +112,16 @@ export class ModuleFederationService extends Effect.Service<ModuleFederationServ
                 }),
             });
 
-            console.log(`[MF] ✅ Registered ${pluginId}`);
+            yield* Effect.logInfo(`[MF] ✅ Registered ${pluginId}`);
           }),
 
         loadRemoteConstructor: (pluginId: string, url: string) =>
           Effect.gen(function* () {
             const remoteName = getNormalizedRemoteName(pluginId);
-            console.log(`[MF] Loading remote ${remoteName}`);
+            yield* Effect.logDebug(`[MF] Loading remote ${remoteName}`);
             const modulePath = `${remoteName}/plugin`;
 
-            return yield* Effect.tryPromise({
+            const pluginConstructor = yield* Effect.tryPromise({
               try: async () => {
                 const container = await mf.loadRemote<RemoteModule>(modulePath);
                 if (!container) {
@@ -181,7 +181,6 @@ export class ModuleFederationService extends Effect.Service<ModuleFederationServ
                   );
                 }
 
-                console.log(`[MF] ✅ Loaded constructor for ${pluginId}`);
                 return Constructor;
               },
               catch: (error): ModuleFederationError =>
@@ -191,6 +190,9 @@ export class ModuleFederationService extends Effect.Service<ModuleFederationServ
                   cause: error instanceof Error ? error : new Error(String(error)),
                 }),
             });
+
+            yield* Effect.logInfo(`[MF] ✅ Loaded constructor for ${pluginId}`);
+            return pluginConstructor;
           }),
       };
     }),

package/src/runtime/services/plugin-loader.service.ts

@@ -111,19 +111,23 @@ export class PluginLoaderService extends Effect.Service<PluginLoaderService>()(
 
             const resolvedUrl = resolveUrl(url);
 
-            yield* moduleFederationService
-              .registerRemote(pluginId, resolvedUrl)
-              .pipe(
-                Effect.mapError((error) =>
-                  toPluginRuntimeError(error, pluginId, undefined, "register-remote", true),
-                ),
-              );
+            yield* moduleFederationService.registerRemote(pluginId, resolvedUrl).pipe(
+              Effect.tapError((_error) =>
+                Effect.logError(`Plugin ${pluginId} failed during register-remote`),
+              ),
+              Effect.mapError((error) =>
+                toPluginRuntimeError(error, pluginId, undefined, "register-remote", true),
+              ),
+            );
 
             yield* Effect.logDebug("Loading plugin from remote", { pluginId, url: resolvedUrl });
 
             const ctor = yield* moduleFederationService
               .loadRemoteConstructor(pluginId, resolvedUrl)
               .pipe(
+                Effect.tapError((_error) =>
+                  Effect.logError(`Plugin ${pluginId} failed during load-remote`),
+                ),
                 Effect.mapError((error) =>
                   toPluginRuntimeError(error, pluginId, undefined, "load-remote", false),
                 ),
@@ -138,6 +142,9 @@ export class PluginLoaderService extends Effect.Service<PluginLoaderService>()(
         instantiatePlugin: <T extends AnyPlugin>(pluginId: string, loadedPlugin: LoadedPlugin<T>) =>
           Effect.gen(function* () {
             const instance = yield* Effect.try(() => new loadedPlugin.ctor()).pipe(
+              Effect.tapError((_error) =>
+                Effect.logError(`Plugin ${pluginId} failed during instantiate-plugin`),
+              ),
               Effect.mapError((error) =>
                 toPluginRuntimeError(error, pluginId, undefined, "instantiate-plugin", false),
               ),
@@ -235,6 +242,9 @@ export class PluginLoaderService extends Effect.Service<PluginLoaderService>()(
               .initialize({ variables: _variables, secrets: hydratedConfig.secrets }, plugins ?? {})
               .pipe(
                 Effect.provideService(Scope.Scope, scope),
+                Effect.tapError((_error) =>
+                  Effect.logError(`Plugin ${plugin.id} failed during initialize-plugin`),
+                ),
                 Effect.mapError((error) =>
                   toPluginRuntimeError(error, plugin.id, undefined, "initialize-plugin", false),
                 ),