@k2b/cloud 0.15.0 → 0.17.0

package/src/cli/plugin.ts

@@ -0,0 +1,127 @@
+/**
+ * `cld` plugin contract shared by the applications that serve plugins and by
+ * `cld`, which installs and loads them.
+ *
+ * An application serves each declared CLI module under
+ * `/cli/plugins/<name>/`: `manifest.json`, the bundled module `cli.js`, and
+ * its skill references `references/<path>.md`. The manifest lists every file
+ * with its SHA-512; the plugin digest is the SHA-512 of those lines, so one
+ * value identifies the exact module and references.
+ */
+import type { CloudCliModule } from "./index";
+
+/** Version of the `CloudCliModule` shape a plugin's default export implements. */
+export const CLOUD_CLI_API_VERSION = 1;
+
+/** Gateway route under which applications serve their `cld` plugins. */
+export const CLOUD_CLI_PLUGIN_ROUTE = "/cli/plugins";
+
+/** Module names: `cld <name>`, the plugin ID, and the route segment. */
+export const CLOUD_CLI_MODULE_NAME = /^[a-z][a-z0-9-]*$/;
+
+/** File name of the bundled module inside a plugin. */
+export const CLOUD_CLI_PLUGIN_ENTRY = "cli.js";
+
+/** Entry file of a plugin's skill references. */
+export const CLOUD_CLI_REFERENCE_INDEX = "references/index.md";
+
+const PLUGIN_FILE_PATH = /^(?:cli\.js|references\/(?:[A-Za-z0-9_][A-Za-z0-9._-]*\/)*[A-Za-z0-9_][A-Za-z0-9._-]*\.md)$/;
+const SHA512_HEX = /^[0-9a-f]{128}$/;
+
+export type CloudCliPluginFile = { path: string; size: number; sha512: string };
+
+export type CloudCliPluginManifest = {
+  apiVersion: number;
+  /** Module name and plugin ID. */
+  name: string;
+  /** ID of the application that serves the plugin. */
+  app: string;
+  /** Version of the serving application build. */
+  version: string;
+  entry: typeof CLOUD_CLI_PLUGIN_ENTRY;
+  /** SHA-512 over the file list; see {@link cloudCliPluginDigest}. */
+  digest: string;
+  files: CloudCliPluginFile[];
+};
+
+/** One entry of `GET /cli/plugins`. */
+export type CloudCliPluginSummary = { name: string; app: string; version: string };
+
+/** Whether `path` is a file name a plugin may contain. */
+export const isCloudCliPluginFilePath = (path: string): boolean => PLUGIN_FILE_PATH.test(path);
+
+export const sha512Hex = (bytes: Uint8Array | string): string => new Bun.CryptoHasher("sha512").update(bytes).digest("hex");
+
+/**
+ * Plugin digest: SHA-512 of `<sha512>  <path>\n` for every file, sorted by
+ * path. This is the `sha512sum` line format, so a plugin directory can be
+ * checked with standard tools.
+ */
+export const cloudCliPluginDigest = (files: readonly Pick<CloudCliPluginFile, "path" | "sha512">[]): string =>
+  sha512Hex(
+    [...files]
+      .sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0))
+      .map((file) => `${file.sha512}  ${file.path}\n`)
+      .join(""),
+  );
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Validate a served manifest, including its digest. Throws an `Error` naming the first problem. */
+export const parseCloudCliPluginManifest = (value: unknown): CloudCliPluginManifest => {
+  if (!isRecord(value)) throw new Error("plugin manifest is not an object");
+  const { apiVersion, name, app, version, entry, digest, files } = value;
+  if (typeof apiVersion !== "number" || !Number.isInteger(apiVersion)) throw new Error("plugin manifest needs an integer apiVersion");
+  if (typeof name !== "string" || !CLOUD_CLI_MODULE_NAME.test(name)) throw new Error("plugin manifest needs a kebab-case name");
+  if (typeof app !== "string" || app === "") throw new Error("plugin manifest needs an app");
+  if (typeof version !== "string" || version === "") throw new Error("plugin manifest needs a version");
+  if (entry !== CLOUD_CLI_PLUGIN_ENTRY) throw new Error(`plugin manifest entry must be ${CLOUD_CLI_PLUGIN_ENTRY}`);
+  if (typeof digest !== "string" || !SHA512_HEX.test(digest)) throw new Error("plugin manifest needs a SHA-512 digest");
+  if (!Array.isArray(files)) throw new Error("plugin manifest needs a file list");
+  const seen = new Set<string>();
+  const parsed = files.map((file): CloudCliPluginFile => {
+    if (
+      !isRecord(file) ||
+      typeof file.path !== "string" ||
+      !isCloudCliPluginFilePath(file.path) ||
+      typeof file.size !== "number" ||
+      !Number.isSafeInteger(file.size) ||
+      file.size < 0 ||
+      typeof file.sha512 !== "string" ||
+      !SHA512_HEX.test(file.sha512)
+    ) {
+      throw new Error("plugin manifest lists an invalid file");
+    }
+    if (seen.has(file.path)) throw new Error(`plugin manifest lists ${file.path} twice`);
+    seen.add(file.path);
+    return { path: file.path, size: file.size, sha512: file.sha512 };
+  });
+  if (!seen.has(CLOUD_CLI_PLUGIN_ENTRY)) throw new Error(`plugin manifest does not list ${CLOUD_CLI_PLUGIN_ENTRY}`);
+  if (!seen.has(CLOUD_CLI_REFERENCE_INDEX)) throw new Error(`plugin manifest does not list ${CLOUD_CLI_REFERENCE_INDEX}`);
+  if (cloudCliPluginDigest(parsed) !== digest) throw new Error("plugin manifest digest does not match its files");
+  return { apiVersion, name, app, version, entry, digest, files: parsed };
+};
+
+/**
+ * Check a plugin's default export structurally. `instanceof` would fail
+ * because every plugin bundles its own copy of `@k2b/cloud/cli`.
+ */
+export const validateCloudCliModule = (value: unknown): CloudCliModule => {
+  if (!isRecord(value)) throw new Error("default export is not a CLI module");
+  if (typeof value.name !== "string" || !CLOUD_CLI_MODULE_NAME.test(value.name)) {
+    throw new Error("default export needs a lowercase kebab-case name");
+  }
+  if (typeof value.summary !== "string") throw new Error("default export needs a string summary");
+  if (typeof value.run !== "function") throw new Error("default export needs a run function");
+  for (const key of ["help", "requiresCloudFor"] as const) {
+    if (value[key] !== undefined && typeof value[key] !== "function") throw new Error(`${key} must be a function`);
+  }
+  if (value.requiresCloud !== undefined && typeof value.requiresCloud !== "boolean") {
+    throw new Error("requiresCloud must be a boolean");
+  }
+  const flags = value.booleanFlags;
+  if (flags !== undefined && (!Array.isArray(flags) || flags.some((flag) => typeof flag !== "string"))) {
+    throw new Error("booleanFlags must be a string array");
+  }
+  return value as CloudCliModule;
+};

package/src/contracts/app.ts

@@ -77,6 +77,17 @@ export type AppPresentationCatalog = {
   translations: Readonly<Record<string, AppPresentationTranslation>>;
 };
 
+/** One `cld` module an application serves as a plugin. Paths are relative to the application directory. */
+export type AppCliModule = {
+  /** Source file whose default export is the module from `defineCliCommands()`, e.g. `src/cli.ts`. */
+  module: string;
+  /** Directory of the module's skill references: `index.md` plus any further Markdown files. */
+  references: string;
+};
+
+/** `cld` modules keyed by module name, the command `cld <name>`. */
+export type AppCliModules = Readonly<Record<string, AppCliModule>>;
+
 export type AppMeta = {
   id: string;
   name: string;
@@ -119,6 +130,8 @@ export type AppMeta = {
   settingKeys?: readonly string[];
   /** Gateway-relative URL where this app's OpenAPI JSON is served, or undefined. */
   openapi?: string;
+  /** `cld` modules this app serves as plugins. */
+  cli?: AppCliModules;
 };
 
 export type WidgetEndpoint = {

package/src/contracts/registry.ts

@@ -85,4 +85,6 @@ export type AppRegistryEntry = {
   settingKeys?: readonly string[];
   /** Gateway-relative URL where this app serves its OpenAPI JSON spec. */
   openapi?: string;
+  /** Names of the `cld` modules this app serves under `/cli/plugins/<name>`. */
+  cliModules?: readonly string[];
 };

package/src/contracts/shared.ts

@@ -104,6 +104,9 @@ export const BaseGroupSchema = z.object({
 });
 export type BaseGroup = z.infer<typeof BaseGroupSchema>;
 
+export const ServiceAccountKindSchema = z.enum(["user_delegated", "resource_bound", "standalone", "agent"]);
+export type ServiceAccountKind = z.infer<typeof ServiceAccountKindSchema>;
+
 export const EntityKindSchema = z.enum(["user", "group", "service_account"]);
 export type EntityKind = z.infer<typeof EntityKindSchema>;
 
@@ -128,7 +131,7 @@ export const EntityListItemSchema = z.discriminatedUnion("kind", [
     serviceAccount: z.object({
       id: z.uuid(),
       name: z.string(),
-      kind: z.enum(["user_delegated", "resource_bound"]),
+      kind: ServiceAccountKindSchema,
       status: z.enum(["active", "disabled"]),
       delegatedUserId: z.uuid().nullable(),
       appId: z.string().nullable(),
@@ -208,9 +211,6 @@ export type MutationResult<T = void> = { ok: true; data: T } | { ok: false; erro
 export const PermissionLevelSchema = z.enum(["none", "read", "write", "admin"]);
 export type PermissionLevel = z.infer<typeof PermissionLevelSchema>;
 
-export const ServiceAccountKindSchema = z.enum(["user_delegated", "resource_bound"]);
-export type ServiceAccountKind = z.infer<typeof ServiceAccountKindSchema>;
-
 export const ServiceAccountStatusSchema = z.enum(["active", "disabled"]);
 export type ServiceAccountStatus = z.infer<typeof ServiceAccountStatusSchema>;
 
@@ -327,6 +327,8 @@ export const AccessEntrySchema = z.object({
   createdAt: z.string(),
   displayName: z.string().optional(),
   avatarHash: z.string().nullable().optional(),
+  /** Kind of a `service_account` principal; presentation only, never authorization. */
+  serviceAccountKind: ServiceAccountKindSchema.optional(),
 });
 export type AccessEntry = z.infer<typeof AccessEntrySchema>;
 

package/src/server/services/access.ts

@@ -2,6 +2,7 @@ import { err, fail, ok, type Result } from "@k2b/stdlib";
 import { type SQLQuery, sql } from "bun";
 import { recursiveGroupIdsSubquery } from "../../services/accounts/group-sql";
 import { toPgUuidArray } from "../../services/postgres";
+import type { ServiceAccountKind } from "../../services/service-accounts";
 
 export type AccessDb = typeof sql;
 
@@ -67,6 +68,7 @@ export type AccessEntry = {
   // Resolved display info (populated by service)
   displayName?: string;
   avatarHash?: string | null;
+  serviceAccountKind?: ServiceAccountKind;
 };
 
 export type AccessUserSource =
@@ -566,11 +568,12 @@ export const listUsersWithAccess = async (params: {
 
 /**
  * Resolve display names for access entries.
- * Populates the displayName field based on principal type.
+ * Populates the displayName field based on principal type, and the
+ * serviceAccountKind field for service-account principals.
  */
 export const resolveDisplayNames = async <T extends { principal: Principal }>(
   entries: T[],
-): Promise<(T & { displayName: string; avatarHash?: string | null })[]> => {
+): Promise<(T & { displayName: string; avatarHash?: string | null; serviceAccountKind?: ServiceAccountKind })[]> => {
   const userIds = entries.filter((e) => e.principal.type === "user").map((e) => (e.principal as { type: "user"; userId: string }).userId);
 
   const groupIds = entries
@@ -606,21 +609,22 @@ export const resolveDisplayNames = async <T extends { principal: Principal }>(
     }
   }
 
-  const serviceAccountNames = new Map<string, string>();
+  const serviceAccountsById = new Map<string, { id: string; name: string; kind: ServiceAccountKind }>();
   if (serviceAccountIds.length > 0) {
-    const serviceAccounts = await sql<{ id: string; name: string }[]>`
-      SELECT id, name
+    const serviceAccounts = await sql<{ id: string; name: string; kind: ServiceAccountKind }[]>`
+      SELECT id, name, kind
       FROM auth.service_accounts
       WHERE id = ANY(${toPgUuidArray(serviceAccountIds)}::uuid[])
     `;
     for (const serviceAccount of serviceAccounts) {
-      serviceAccountNames.set(serviceAccount.id, serviceAccount.name);
+      serviceAccountsById.set(serviceAccount.id, serviceAccount);
     }
   }
 
   return entries.map((entry) => {
     let displayName: string;
     let avatarHash: string | null | undefined;
+    let serviceAccountKind: ServiceAccountKind | undefined;
     switch (entry.principal.type) {
       case "user": {
         const user = userNames.get(entry.principal.userId);
@@ -631,9 +635,12 @@ export const resolveDisplayNames = async <T extends { principal: Principal }>(
       case "group":
         displayName = groupNames.get(entry.principal.groupId) ?? "Unknown Group";
         break;
-      case "service_account":
-        displayName = serviceAccountNames.get(entry.principal.serviceAccountId) ?? "Unknown Service Account";
+      case "service_account": {
+        const serviceAccount = serviceAccountsById.get(entry.principal.serviceAccountId);
+        displayName = serviceAccount?.name ?? "Unknown Service Account";
+        serviceAccountKind = serviceAccount?.kind;
         break;
+      }
       case "authenticated":
         displayName = "All users (incl. guests)";
         break;
@@ -641,6 +648,6 @@ export const resolveDisplayNames = async <T extends { principal: Principal }>(
         displayName = "Public";
         break;
     }
-    return { ...entry, displayName, avatarHash };
+    return { ...entry, displayName, avatarHash, serviceAccountKind };
   });
 };

package/src/services/accounts/entities.ts

@@ -2,6 +2,7 @@ import { sql } from "bun";
 import type { EntityKind, EntityListItem, UserProfile, UserProvider } from "../../contracts/shared";
 import { getFreeIpaConfig } from "../freeipa-config";
 import { escapeLikePattern, toPgTextArray, toPgUuidArray } from "../postgres";
+import type { ServiceAccountKind } from "../service-accounts";
 import { buildBaseGroup, personalOwnerJoin } from "./base-group";
 import { buildBaseUser } from "./base-user";
 import { buildManagedGroupScopeCondition, recursiveGroupIdsSubquery } from "./group-sql";
@@ -369,6 +370,9 @@ const buildQuerySpec = (params: EntityListParams): EntityQuerySpec => {
   return buildNoRelationSpec();
 };
 
+const serviceAccountKind = (value: unknown): ServiceAccountKind =>
+  value === "resource_bound" || value === "standalone" || value === "agent" ? value : "user_delegated";
+
 const mapEntityRow = (row: DbRow): EntityListItem => {
   const direct = typeof row.direct === "boolean" ? row.direct : undefined;
 
@@ -386,7 +390,7 @@ const mapEntityRow = (row: DbRow): EntityListItem => {
       serviceAccount: {
         id: String(row.id),
         name: String(row.name ?? ""),
-        kind: row.service_account_kind === "resource_bound" ? "resource_bound" : "user_delegated",
+        kind: serviceAccountKind(row.service_account_kind),
         status: row.status === "disabled" ? "disabled" : "active",
         delegatedUserId: typeof row.delegated_user_id === "string" ? row.delegated_user_id : null,
         appId: typeof row.app_id === "string" ? row.app_id : null,
@@ -596,6 +600,8 @@ export const list = async (
           sa.name,
           CASE
             WHEN sa.kind = 'user_delegated' THEN 'Personal automation keys'
+            WHEN sa.kind = 'agent' THEN 'Agent'
+            WHEN sa.kind = 'standalone' THEN 'Service account'
             ELSE CONCAT_WS(' · ', sa.app_id, sa.resource_type, sa.resource_id)
           END AS description,
           NULL::int AS gid_number,

package/src/services/index.ts

@@ -90,7 +90,8 @@ export type {
   MandateSubject,
 } from "./mandates";
 export { serviceAccounts } from "./service-accounts";
-export type { ServiceAccount, ServiceAccountKind, ServiceAccountStatus } from "./service-accounts";
+export type { ServiceAccount, ServiceAccountKind, ServiceAccountStatus, StandaloneServiceAccountKind } from "./service-accounts";
+export { isStandaloneServiceAccountKind, STANDALONE_SERVICE_ACCOUNT_KINDS } from "./service-accounts";
 export { serviceAccountCredentials } from "./service-account-credentials";
 export type {
   AuthenticatedServiceAccountCredential,

package/src/services/service-account-credentials.ts

@@ -5,7 +5,12 @@ import type { User } from "../contracts/shared";
 import { accounts } from "./accounts";
 import { audit } from "./audit";
 import { isUniqueViolation, toPgTextArray } from "./postgres";
-import { type ServiceAccount, serviceAccounts } from "./service-accounts";
+import {
+  isStandaloneServiceAccountKind,
+  type ServiceAccount,
+  type StandaloneServiceAccountKind,
+  serviceAccounts,
+} from "./service-accounts";
 
 export type ServiceAccountCredentialStatus = "active" | "revoked";
 export type ServiceAccountCredentialKind = "api_token";
@@ -46,6 +51,12 @@ export type ServiceAccountCredentialOwner =
       appId: string;
       resourceType: string;
       resourceId: string;
+    }
+  | {
+      type: "standalone";
+      serviceAccountId: string;
+      name: string;
+      kind: StandaloneServiceAccountKind;
     };
 
 export type ServiceAccountCredentialOverview = ServiceAccountCredential & {
@@ -139,30 +150,33 @@ const mapServiceAccount = (row: DbCredentialServiceAccountFields): ServiceAccoun
   createdAt: row.service_account_created_at.toISOString(),
 });
 
-const mapCredentialOverview = (row: DbCredentialOverviewRow): ServiceAccountCredentialOverview => {
-  const serviceAccount = mapServiceAccount(row);
+const credentialOwner = (row: DbCredentialOverviewRow, serviceAccount: ServiceAccount): ServiceAccountCredentialOwner => {
+  if (serviceAccount.kind === "user_delegated" && serviceAccount.delegatedUserId) {
+    return {
+      type: "user",
+      userId: serviceAccount.delegatedUserId,
+      uid: row.delegated_uid ?? serviceAccount.delegatedUserId,
+      displayName: row.delegated_display_name ?? "",
+      mail: row.delegated_mail,
+      avatarHash: row.delegated_avatar_hash,
+    };
+  }
+  if (isStandaloneServiceAccountKind(serviceAccount.kind)) {
+    return { type: "standalone", serviceAccountId: serviceAccount.id, name: serviceAccount.name, kind: serviceAccount.kind };
+  }
   return {
-    ...mapCredential(row),
-    serviceAccount,
-    owner:
-      serviceAccount.kind === "user_delegated" && serviceAccount.delegatedUserId
-        ? {
-            type: "user",
-            userId: serviceAccount.delegatedUserId,
-            uid: row.delegated_uid ?? serviceAccount.delegatedUserId,
-            displayName: row.delegated_display_name ?? "",
-            mail: row.delegated_mail,
-            avatarHash: row.delegated_avatar_hash,
-          }
-        : {
-            type: "resource",
-            appId: serviceAccount.appId ?? "",
-            resourceType: serviceAccount.resourceType ?? "",
-            resourceId: serviceAccount.resourceId ?? "",
-          },
+    type: "resource",
+    appId: serviceAccount.appId ?? "",
+    resourceType: serviceAccount.resourceType ?? "",
+    resourceId: serviceAccount.resourceId ?? "",
   };
 };
 
+const mapCredentialOverview = (row: DbCredentialOverviewRow): ServiceAccountCredentialOverview => {
+  const serviceAccount = mapServiceAccount(row);
+  return { ...mapCredential(row), serviceAccount, owner: credentialOwner(row, serviceAccount) };
+};
+
 const actorForUser = (user: Pick<User, "id" | "uid" | "provider" | "roles">) => ({
   userId: user.id,
   uid: user.uid,
@@ -438,6 +452,43 @@ export const createResourceApiToken = async (params: {
   });
 };
 
+/** Static bearer for a standalone principal (kind standalone or agent); the raw token is returned once. */
+export const createStandaloneApiToken = async (params: {
+  serviceAccountId: string;
+  actor: User;
+  name: string;
+  expiresAt?: string | null;
+  scopes?: string[];
+}): Promise<Result<{ credential: ServiceAccountCredential; token: string }>> => {
+  const serviceAccount = await serviceAccounts.get({ id: params.serviceAccountId });
+  if (!serviceAccount || !isStandaloneServiceAccountKind(serviceAccount.kind)) return fail(err.notFound("Service account"));
+  if (serviceAccount.status !== "active") return fail(err.badInput("Service account is disabled"));
+
+  return sql.begin(async (tx) => {
+    const result = await insertApiToken(tx, {
+      serviceAccountId: serviceAccount.id,
+      name: params.name,
+      expiresAt: params.expiresAt,
+      createdBy: params.actor.id,
+      scopes: params.scopes,
+    });
+
+    return audit.recordResult({
+      action: "service_account_credential.create",
+      actor: actorForUser(params.actor),
+      target: { type: "service_account_credential", id: result.ok ? result.data.credential.id : null, label: params.name },
+      metadata: {
+        serviceAccountId: serviceAccount.id,
+        kind: "api_token",
+        serviceAccountKind: serviceAccount.kind,
+        expiresAt: params.expiresAt ?? null,
+      },
+      result,
+      db: tx,
+    });
+  });
+};
+
 export const listForDelegatedUser = async (params: { userId: string }): Promise<ServiceAccountCredential[]> => {
   const rows = await sql<DbCredentialRow[]>`
     SELECT c.id, c.service_account_id, c.name, c.kind, c.status, c.token_prefix, c.scopes, c.expires_at,
@@ -880,6 +931,7 @@ export const serviceAccountCredentials = {
   createApiToken,
   createUserApiToken,
   createResourceApiToken,
+  createStandaloneApiToken,
   listForDelegatedUser,
   listOverview,
   getOverview,

package/src/services/service-accounts.ts

@@ -2,9 +2,20 @@ import { err, fail, ok, type Result } from "@k2b/stdlib";
 import { sql } from "bun";
 import { isUniqueViolation } from "./postgres";
 
-export type ServiceAccountKind = "user_delegated" | "resource_bound";
+export type ServiceAccountKind = "user_delegated" | "resource_bound" | "standalone" | "agent";
 export type ServiceAccountStatus = "active" | "disabled";
 
+/**
+ * Kinds of a standalone principal: not delegated by a user and not bound to one
+ * app resource. `agent` is a standalone account that surfaces as an agent
+ * (badge, pickers, activity); it carries no extra permission.
+ */
+export type StandaloneServiceAccountKind = Extract<ServiceAccountKind, "standalone" | "agent">;
+export const STANDALONE_SERVICE_ACCOUNT_KINDS = ["standalone", "agent"] as const satisfies readonly StandaloneServiceAccountKind[];
+
+export const isStandaloneServiceAccountKind = (kind: ServiceAccountKind): kind is StandaloneServiceAccountKind =>
+  kind === "standalone" || kind === "agent";
+
 export type ServiceAccount = {
   id: string;
   name: string;
@@ -48,6 +59,8 @@ const trimRequired = (value: string): string => value.trim();
 
 const isForeignKeyViolation = (error: unknown): boolean => (error as { code?: string } | null)?.code === "23503";
 const RESOURCE_BOUND_UNIQUE_CONSTRAINT = "uniq_service_accounts_resource_bound";
+const STANDALONE_NAME_UNIQUE_CONSTRAINT = "uniq_service_accounts_standalone_name";
+const MAX_NAME_LENGTH = 120;
 
 export const getByResource = async (params: {
   appId: string;
@@ -125,6 +138,60 @@ export const createResourceBound = async (params: {
   }
 };
 
+export const createStandalone = async (params: {
+  name: string;
+  kind: StandaloneServiceAccountKind;
+  createdBy?: string | null;
+}): Promise<Result<ServiceAccount>> => {
+  const name = trimRequired(params.name);
+  if (!name) return fail(err.badInput("Service account name is required"));
+  if (name.length > MAX_NAME_LENGTH) return fail(err.badInput(`Service account name must be ${MAX_NAME_LENGTH} characters or fewer`));
+  if (!isStandaloneServiceAccountKind(params.kind)) return fail(err.badInput("Service account kind must be standalone or agent"));
+
+  try {
+    const [row] = await sql<DbServiceAccount[]>`
+      INSERT INTO auth.service_accounts (name, kind, created_by)
+      VALUES (${name}, ${params.kind}, ${params.createdBy ?? null}::uuid)
+      RETURNING id, name, kind, status, delegated_user_id, app_id, resource_type, resource_id, created_by, created_at
+    `;
+    return row ? ok(mapServiceAccount(row)) : fail(err.internal("Failed to create service account"));
+  } catch (error) {
+    if (isForeignKeyViolation(error)) return fail(err.notFound("Creator"));
+    if (isUniqueViolation(error, STANDALONE_NAME_UNIQUE_CONSTRAINT)) return fail(err.conflict("Service account name"));
+    throw error;
+  }
+};
+
+/** Bounded page of standalone principals; user-delegated and resource-bound accounts stay with their owners. */
+export const listStandalone = async (params: {
+  kind?: StandaloneServiceAccountKind;
+  status?: ServiceAccountStatus;
+  search?: string;
+  page?: number;
+  perPage?: number;
+}): Promise<{ items: ServiceAccount[]; page: number; perPage: number; total: number; hasNext: boolean }> => {
+  const page = Math.max(1, params.page ?? 1);
+  const perPage = Math.max(1, Math.min(params.perPage ?? 100, 500));
+  const offset = (page - 1) * perPage;
+  const kind = params.kind ?? null;
+  const status = params.status ?? null;
+  const search = params.search?.trim() || null;
+  const rows = await sql<(DbServiceAccount & { total: number })[]>`
+    SELECT id, name, kind, status, delegated_user_id, app_id, resource_type, resource_id, created_by, created_at,
+      COUNT(*) OVER()::int AS total
+    FROM auth.service_accounts
+    WHERE kind IN ('standalone', 'agent')
+      AND (${kind}::text IS NULL OR kind = ${kind})
+      AND (${status}::text IS NULL OR status = ${status})
+      AND (${search}::text IS NULL OR name ILIKE '%' || ${search} || '%')
+    ORDER BY created_at DESC, id DESC
+    LIMIT ${perPage}
+    OFFSET ${offset}
+  `;
+  const total = rows[0]?.total ?? 0;
+  return { items: rows.map(mapServiceAccount), page, perPage, total, hasNext: page * perPage < total };
+};
+
 export const getOrCreateResourceBound = async (params: {
   name: string;
   appId: string;
@@ -176,6 +243,8 @@ export const serviceAccounts = {
   get,
   createUserDelegated,
   createResourceBound,
+  createStandalone,
+  listStandalone,
   getByResource,
   getOrCreateResourceBound,
   setStatus,

package/src/services/settings/core-settings.ts

@@ -709,6 +709,19 @@ export const CORE_SETTINGS = {
     description: "Maximum API requests per second per IP address",
   },
 
+  // ── Command line ────────────────────────────────────────────────────────
+  "cli.plugins.access": {
+    kind: "enum",
+    label: "Who may install cld plugins",
+    default: "full_users",
+    options: [
+      { value: "full_users", label: "Full accounts" },
+      { value: "all_users", label: "All accounts, including guests" },
+    ],
+    description:
+      "Applies to the plugin list and every plugin download. Signed-out requests never get plugins. Commands stay authorized by the server either way.",
+  },
+
   // ── Legal documents (Imprint, Privacy, Terms) ──────────────────────────
   // mode = "local"    → render markdown from `legal.<kind>.content`
   // mode = "external" → 302-redirect to `legal.<kind>.url`

package/src/ssr/Layout.tsx

@@ -210,7 +210,9 @@ export default function Layout(props: LayoutProps) {
     user?.avatarHash && user.id
       ? `/api/accounts/users/${encodeURIComponent(user.id)}/avatar?rev=${encodeURIComponent(user.avatarHash)}`
       : undefined;
-  const mainLayoutClass = fullPage || fullWidth ? "flex flex-col" : "lg:overflow-auto";
+  // From lg, `main` is the page scroller of regular pages. Its stable gutter
+  // keeps short and long pages at the same width where scrollbars take space.
+  const mainLayoutClass = fullPage || fullWidth ? "flex flex-col" : "lg:overflow-auto lg:[scrollbar-gutter:stable]";
   const canvasStyle =
     [appAppearanceStyle(currentApp?.appearance), appWorkspaceLayoutStyle(workspaceLayout), focusMode && flushCanvas ? "padding:0" : ""]
       .filter(Boolean)

package/src/styles/global.css

@@ -280,6 +280,10 @@ solid-island {
     padding: env(safe-area-inset-top, 0px) env(safe-area-inset-right, 0px) env(safe-area-inset-bottom, 0px) env(safe-area-inset-left, 0px);
     background: var(--ui-surface);
   }
+  /* Below lg the document is the page scroller; reserve its scrollbar gutter
+     so short and long pages keep the same width. Full-page surfaces own their
+     inner scrolling. */
+  html:has(.cloud-app-canvas:not([data-layout-full-page])) { scrollbar-gutter: stable; }
   .cloud-app-canvas > .layout-shell-content { gap: 0; }
   .cloud-app-canvas .layout-header {
     border-radius: 0; border: 0; border-bottom: 1px solid var(--ui-border);

package/src/types/ambient.d.ts

@@ -7,6 +7,11 @@ declare module "*.md" {
   export default content;
 }
 
+declare module "*.yaml" {
+  const content: string;
+  export default content;
+}
+
 declare module "*.sql" {
   const content: string;
   export default content;