@k2b/cloud 0.43.0 → 0.44.0

package/src/_internal/object-store-config.ts

@@ -0,0 +1,101 @@
+import { S3Client } from "bun";
+import { z } from "zod";
+import { readStates } from "../services/settings/store";
+
+export const objectStoreSettingKeys = [
+  "storage.endpoint",
+  "storage.region",
+  "storage.bucket",
+  "storage.access_key_id",
+  "storage.secret_access_key",
+  "storage.max_object_bytes",
+] as const;
+const bucket = z
+  .string()
+  .min(3)
+  .max(63)
+  .regex(/^[a-z0-9][a-z0-9.-]*[a-z0-9]$/);
+const Config = z.object({
+  endpoint: z.string().min(1),
+  region: z.string().min(1),
+  bucket,
+  access_key_id: z.string().min(1),
+  secret_access_key: z.string().min(1),
+  max_object_bytes: z
+    .number()
+    .int()
+    .min(1)
+    .max(5 * 1024 ** 3),
+});
+export class ObjectStoreConfigurationError extends Error {}
+export class ObjectStoreConnectionError extends Error {}
+let cached: { signature: string; client: S3Client } | undefined;
+
+export const objectStoreBackend = async () => {
+  // Read one coherent DB snapshot, including stored-state checks. No local TTL:
+  // changes and secret rotation apply to the next operation in every process.
+  const states = await readStates(objectStoreSettingKeys);
+  if (objectStoreSettingKeys.some((key) => states.get(key)?.stored === "unreadable")) {
+    throw new ObjectStoreConfigurationError(
+      "Storage settings cannot be decrypted. Check this process uses the installation APP_SECRET, then replace unreadable settings in Administration > Settings > Storage.",
+    );
+  }
+  const parsed = Config.safeParse(
+    Object.fromEntries(objectStoreSettingKeys.map((key) => [key.slice("storage.".length), states.get(key)?.value])),
+  );
+  if (!parsed.success)
+    throw new ObjectStoreConfigurationError(
+      "Storage is not configured. Set the Garage endpoint, region, bucket and credentials in Administration > Settings > Storage.",
+    );
+  const config = parsed.data;
+  const endpoint = URL.parse(config.endpoint);
+  if (
+    !endpoint ||
+    !["http:", "https:"].includes(endpoint.protocol) ||
+    endpoint.username ||
+    endpoint.password ||
+    endpoint.search ||
+    endpoint.hash ||
+    endpoint.pathname !== "/"
+  ) {
+    throw new ObjectStoreConfigurationError("Storage endpoint must be an HTTP(S) origin without credentials, path, query or fragment.");
+  }
+  const signature = JSON.stringify(config);
+  if (cached?.signature !== signature) {
+    const options = {
+      endpoint: endpoint.href,
+      accessKeyId: config.access_key_id,
+      secretAccessKey: config.secret_access_key,
+      region: config.region,
+    };
+    cached = { signature, client: new S3Client({ ...options, bucket: config.bucket }) };
+  }
+  return { client: cached.client, limit: config.max_object_bytes };
+};
+
+/** Internal administrator check; never an application API or a credential response. */
+export const testObjectStoreConnection = async (): Promise<void> => {
+  const backend = await objectStoreBackend();
+  const file = backend.client.file(`cloud-connection-test/${crypto.randomUUID()}`);
+  const content = "Cloud storage connection test";
+  let step = "write";
+  try {
+    await file.write(content, { type: "text/plain" });
+    step = "read";
+    if ((await file.text()) !== content) throw new Error("Unexpected content");
+    step = "delete";
+    await file.delete();
+    if (await file.exists()) throw new Error("Object still exists");
+  } catch {
+    try {
+      await file.delete();
+    } catch {
+      throw new ObjectStoreConnectionError(
+        `Storage test failed at ${step}; cleanup failed. Remove cloud-connection-test/ objects after fixing the connection.`,
+      );
+    }
+    throw new ObjectStoreConnectionError(
+      `Storage test failed at ${step}. Check the saved settings, Garage availability and bucket permissions, then retry.`,
+    );
+  }
+};

package/src/_internal/object-store-key.ts

@@ -0,0 +1,14 @@
+// S3's complete object key, including the area, is limited to 1,024 UTF-8 bytes.
+// Reject percent signs altogether, including nested encodings, before Bun sees a key.
+export const validateObjectKey = (key: string, area: string, allowPrefix = false): string => {
+  if (typeof key !== "string" || !key.isWellFormed() || key !== key.normalize("NFC") || /[\\%\p{Cc}\p{Cf}]/u.test(key)) {
+    throw new TypeError("Object keys must be NFC text without controls, backslashes, or percent escapes.");
+  }
+  if (allowPrefix && key === "") return key;
+  const path = allowPrefix && key.endsWith("/") ? key.slice(0, -1) : key;
+  if (!path || path.split("/").some((segment) => !segment || segment === "." || segment === "..")) {
+    throw new TypeError("Object keys must be relative paths without empty, dot, or parent segments.");
+  }
+  if (Buffer.byteLength(area + key) > 1024) throw new RangeError("Object key exceeds S3's 1,024-byte limit including its area.");
+  return key;
+};

package/src/_internal/process-identity.ts

@@ -2,20 +2,25 @@ import type { PlatformPermission } from "../contracts/outgoing-mail";
 
 /** Identity of the application started in this process, derived from its declaration. */
 let applicationId: string | undefined;
+let applicationPackage: string | undefined;
 let platformPermissions: readonly PlatformPermission[] = [];
 export const getProcessPlatformPermissions = (): readonly PlatformPermission[] => platformPermissions;
 
 export const getProcessApplicationId = (): string | undefined => applicationId;
 
-export const bindProcessApplicationId = (id: string, permissions: readonly PlatformPermission[] = []): void => {
-  if (applicationId !== undefined && applicationId !== id) {
+export const getProcessApplicationPackage = (): string | undefined => applicationPackage;
+
+export const bindProcessApplicationId = (id: string, permissions: readonly PlatformPermission[] = [], packageName = id): void => {
+  if (applicationId !== undefined && (applicationId !== id || applicationPackage !== packageName)) {
     throw new Error(`This process already hosts application "${applicationId}"`);
   }
   applicationId = id;
+  applicationPackage = packageName;
   platformPermissions = [...permissions];
 };
 
 export const clearProcessApplicationId = (): void => {
   applicationId = undefined;
+  applicationPackage = undefined;
   platformPermissions = [];
 };

package/src/_internal/registry-validation.ts

@@ -1,4 +1,5 @@
 import { CLOUD_CLI_MODULE_NAME } from "../cli/plugin";
+import { APP_ADMIN_AREAS } from "../contracts/app";
 import { AppAccessRuleSchema } from "../contracts/app-access";
 import { validateInstallable } from "../contracts/installable";
 import { PlatformPermissionSchema } from "../contracts/outgoing-mail";
@@ -19,6 +20,9 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
   for (const field of ["id", "name", "icon", "description", "baseUrl"] as const) {
     if (!isString(value[field]) || value[field].length === 0) return invalid(field, "a non-empty string");
   }
+  if (value.package !== undefined && (typeof value.package !== "string" || !/^[a-z][a-z0-9-]{0,79}$/.test(value.package))) {
+    return invalid("package", "a lowercase package name of 1–80 characters");
+  }
   try {
     const baseUrl = new URL(value.baseUrl as string);
     if (!(["http:", "https:"] as const).includes(baseUrl.protocol as "http:" | "https:") || baseUrl.username || baseUrl.password) {
@@ -100,7 +104,7 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
         (group) =>
           !isRecord(group) ||
           (group.id !== undefined && !isString(group.id)) ||
-          (group.section !== undefined && group.section !== "ai") ||
+          (group.section !== undefined && !(APP_ADMIN_AREAS as readonly unknown[]).includes(group.section)) ||
           !isString(group.label) ||
           !Array.isArray(group.links) ||
           group.links.some((link) => !isRecord(link) || !isString(link.label) || !isString(link.href) || !isString(link.icon)),
@@ -141,6 +145,12 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
     if (value.pwa.requiresRoles !== undefined && !isStringArray(value.pwa.requiresRoles)) {
       return invalid("pwa.requiresRoles", "an array of strings");
     }
+    for (const field of ["badge", "summary"] as const) {
+      const path = value.pwa[field];
+      if (path !== undefined && (!isString(path) || !isOwnAppPath(path, value.routes))) {
+        return invalid(`pwa.${field}`, "a same-origin path below one of the app's routes");
+      }
+    }
   }
   if (value.widgets !== undefined) {
     if (

package/src/_internal/registry.ts

@@ -5,6 +5,7 @@ import { calendarSourceIssues } from "../contracts/calendar-source";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
 import { fileProviderIssues } from "../contracts/file-provider";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
+import { resourcePageIssue } from "../contracts/resource-pages";
 import { type Role, RoleSchema } from "../contracts/shared";
 import {
   type DashboardWidgetPresentation,
@@ -333,7 +334,13 @@ export const resolveLiveCapabilityRegistryEntry = (
   if (!endpoint) return null;
   try {
     const read = parseCapabilityManifest(record.manifest, app.id);
-    const manifest = withValidCalendarSource(withValidFileProvider(read));
+    const supported = withValidCalendarSource(withValidFileProvider(read));
+    const manifest = supported.resourcePages
+      ? {
+          ...supported,
+          resourcePages: supported.resourcePages.filter((page) => !resourcePageIssue(page.path, app.routes, app.id)),
+        }
+      : supported;
     const presentation = compileCapabilityPresentation(manifest, record.presentation, "reader");
     if (app.capabilities.protocolVersion !== manifest.protocolVersion || app.capabilities.manifestHash !== manifest.manifestHash) {
       return null;

package/src/_internal/runtime-context.ts

@@ -71,7 +71,14 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
       ),
       legalLinks: e.legalLinks ? e.legalLinks.map((l) => ({ ...l })) : undefined,
       searchLinks: e.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
-      pwa: e.pwa ? { href: e.pwa.href, requiresRoles: e.pwa.requiresRoles ? ([...e.pwa.requiresRoles] as Role[]) : undefined } : undefined,
+      pwa: e.pwa
+        ? {
+            href: e.pwa.href,
+            requiresRoles: e.pwa.requiresRoles ? ([...e.pwa.requiresRoles] as Role[]) : undefined,
+            ...(e.pwa.badge ? { badge: e.pwa.badge } : {}),
+            ...(e.pwa.summary ? { summary: e.pwa.summary } : {}),
+          }
+        : undefined,
       installable: e.installable ? structuredClone(e.installable) : undefined,
       openapi: e.openapi,
     };

package/src/access/AppAccessEditor.tsx

@@ -217,6 +217,8 @@ export default function AppAccessEditor(props: AppAccessEditorProps) {
   };
   const fixedDescription = () => {
     switch (props.app.access?.kind) {
+      case "resources":
+        return t().resources;
       case "signedIn":
         return t().fixedSignedIn;
       case "noGuests":

package/src/access/PermissionEditor.tsx

@@ -3,7 +3,7 @@ import { announce, Button, IconButton, Placeholder, prompts, Select, SelectChip,
 import { createEffect, createMemo, createSignal, For, on, onCleanup, Show } from "solid-js";
 import { createStore, reconcile } from "solid-js/store";
 import { CloudAvatar } from "../account/Avatar";
-import type { AccessEntry, PermissionLevel, Principal, ServiceAccountKind } from "../contracts/shared";
+import type { AccessEntry, PermissionLevel, Principal, ServiceAccountKind, ServiceAccountStatus } from "../contracts/shared";
 import { createGroupCoverage, type GroupCoverage, GroupCoveragePanel, GroupCoverageToggle } from "./GroupCoverage";
 import { isManagerEntry } from "./managers";
 import { accessMessages } from "./messages";
@@ -81,9 +81,13 @@ type PermissionEditorProps = {
    *  true; resources with an explicit principal allowlist can disable it. */
   allowAuthenticated?: boolean;
 
-  /** Allow granting service accounts. Off by default so ordinary
-   *  permission pickers stay user/group focused. */
+  /** Allow granting service accounts. Defaults to true, including agents.
+   *  Disable only when the resource documents a user-backed identity requirement. */
   allowServiceAccounts?: boolean;
+  /** Optional directory filters for the resource's accepted credential kinds. */
+  serviceAccountKinds?: ServiceAccountKind[];
+  /** Grant selection defaults to active accounts; existing entries are unaffected. */
+  serviceAccountStatus?: ServiceAccountStatus;
 
   /** The principal search's placeholder, in the consumer's terms. Defaults to the principal kinds it offers. */
   placeholder?: string;
@@ -563,6 +567,8 @@ export default function PermissionEditor(props: PermissionEditorProps) {
           allowPublic={allowPublic()}
           allowAuthenticated={allowAuthenticated()}
           allowServiceAccounts={props.allowServiceAccounts}
+          serviceAccountKinds={props.serviceAccountKinds}
+          serviceAccountStatus={props.serviceAccountStatus ?? "active"}
           placeholder={props.placeholder}
           signedIn={props.signedIn}
           readOnly={grantPending()}

package/src/access/PrincipalPicker.tsx

@@ -1,5 +1,5 @@
 import { Combobox, type ComboboxOption, useLocale } from "@k2b/ui";
-import type { Principal, ServiceAccountKind } from "../contracts/shared";
+import type { Principal, ServiceAccountKind, ServiceAccountStatus } from "../contracts/shared";
 import { accessMessages } from "./messages";
 import { principalLabel } from "./principal-label";
 import { serviceAccountKindDisplay } from "./service-account-kind";
@@ -34,7 +34,11 @@ export default function PrincipalPicker(props: {
   existing?: Principal[];
   allowPublic?: boolean;
   allowAuthenticated?: boolean;
+  /** Defaults to true; disable only for a documented user-backed workflow. */
   allowServiceAccounts?: boolean;
+  /** Optional directory filters for the resource's accepted credential kinds. */
+  serviceAccountKinds?: ServiceAccountKind[];
+  serviceAccountStatus?: ServiceAccountStatus;
   /** Offers only the service accounts this returns `true` for, such as active accounts the resource can accept. */
   serviceAccountFilter?: (account: PrincipalPickerServiceAccount) => boolean;
   disabled?: boolean;
@@ -78,7 +82,13 @@ export default function PrincipalPicker(props: {
     if (search.length >= 2) {
       const url = new URL("/api/accounts/entities", window.location.origin);
       url.searchParams.set("search", search);
-      url.searchParams.set("kinds", props.allowServiceAccounts ? "user,group,service_account" : "user,group");
+      url.searchParams.set("kinds", props.allowServiceAccounts !== false ? "user,group,service_account" : "user,group");
+      if (props.allowServiceAccounts !== false && props.serviceAccountKinds?.length) {
+        url.searchParams.set("service_account_kinds", props.serviceAccountKinds.join(","));
+      }
+      if (props.allowServiceAccounts !== false && props.serviceAccountStatus) {
+        url.searchParams.set("service_account_status", props.serviceAccountStatus);
+      }
       url.searchParams.set("per_page", "10");
       const users = props.existing?.flatMap((p) => (p.type === "user" ? [p.userId] : [])) ?? [];
       const groups = props.existing?.flatMap((p) => (p.type === "group" ? [p.groupId] : [])) ?? [];
@@ -145,10 +155,10 @@ export default function PrincipalPicker(props: {
       placeholder={
         props.placeholder ??
         (props.allowAuthenticated !== false || props.allowPublic
-          ? props.allowServiceAccounts
+          ? props.allowServiceAccounts !== false
             ? t().addAll
             : t().addAudience
-          : props.allowServiceAccounts
+          : props.allowServiceAccounts !== false
             ? t().addService
             : t().addBasic)
       }

package/src/access/ResourceApiKeys.tsx

@@ -217,12 +217,11 @@ export default function ResourceApiKeys(props: ResourceApiKeysProps) {
     if (confirmed) await revokeMutation.mutate({ id: key.id, name: key.name });
   };
 
-  // The heading is a detail panel section heading: in a detail panel the keys line up with the sections around them,
-  // and below a settings group title they read as one level down.
+  // The heading is a detail panel section heading without an icon: in a details panel the keys line up with the
+  // sections around them, and below a settings group title they read as one level down. Keys are flat rows.
   return (
     <DetailPanel.Section
       title={props.title ?? t().apiKeys}
-      icon="ti ti-key"
       description={props.description ?? t().apiKeysDescription}
       actions={
         <Button type="button" variant="secondary" size="sm" onClick={openCreate} disabled={createMutation.loading()}>
@@ -235,7 +234,7 @@ export default function ResourceApiKeys(props: ResourceApiKeysProps) {
         <div class="flex flex-col gap-2">
           <For each={keys()}>
             {(key) => (
-              <div class="group/api-key flex items-center gap-3 rounded-lg bg-zinc-50/70 p-3 dark:bg-zinc-900/35">
+              <div class="group/api-key flex items-center gap-3 py-1.5">
                 <div class="min-w-0 flex-1">
                   {/* The name and its tags wrap instead of squeezing the name to a few letters in a narrow section. */}
                   <div class="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">

package/src/access/app-access-messages.ts

@@ -55,12 +55,15 @@ export const appAccessMessages = i18n.define({
       fixedNoGuests: "Signed-in people except guests. The app sets this rule; there is nothing to configure here.",
       fixedAdmins: "Cloud administrators only. The app sets this rule; there is nothing to configure here.",
       fixedRoles: "People with the Cloud roles required by the app. The app sets this rule.",
+      resources: "Accounts with an effective resource permission in this app. Manage permissions within the app.",
+      resourcesLabel: "Resource permissions",
       legacy: "This app uses its existing access checks.",
       deniedTitle: ({ name }: { name: string }) => `${name} is not available to you`,
       revokedTitle: ({ name }: { name: string }) => `Your access to ${name} was removed`,
       revokedDescription: "You had access until now. If this was a mistake, ask:",
       deniedGrants: "Only people with access may use this app. Access is managed by:",
       deniedFixed: "If you need this app, contact your Cloud administration.",
+      deniedResources: "Ask someone who manages resource permissions in this app for access.",
       deniedAdmins: ({ name }: { name: string }) => `Only Cloud administrators use ${name}.`,
       deniedNoGuests: ({ name }: { name: string }) => `Guests cannot use ${name}.`,
       deniedRoles: ({ name }: { name: string }) => `Only people with specific Cloud roles use ${name}.`,
@@ -134,12 +137,15 @@ export const appAccessMessages = i18n.define({
       fixedNoGuests: "Angemeldete Personen außer Gästen. Das legt die App fest; hier gibt es dazu nichts einzustellen.",
       fixedAdmins: "Nur Cloud-Admins. Das legt die App fest; hier gibt es dazu nichts einzustellen.",
       fixedRoles: "Personen mit den von der App verlangten Cloud-Rollen. Das legt die App fest.",
+      resources: "Konten mit einer wirksamen Ressourcenberechtigung in dieser App. Berechtigungen werden innerhalb der App verwaltet.",
+      resourcesLabel: "Ressourcenberechtigungen",
       legacy: "Diese App verwendet ihre bisherigen Zugriffsprüfungen.",
       deniedTitle: ({ name }: { name: string }) => `${name} ist für dich nicht freigegeben`,
       revokedTitle: ({ name }: { name: string }) => `Dein Zugriff auf ${name} wurde entfernt`,
       revokedDescription: "Du hattest bis eben Zugriff. Wenn das ein Versehen ist, frag:",
       deniedGrants: "Diese App nutzen nur Personen mit Freigabe. Den Zugriff verwalten:",
       deniedFixed: "Wenn du die App brauchst, wende dich an die Cloud-Verwaltung.",
+      deniedResources: "Bitte jemanden, der Ressourcenberechtigungen in dieser App verwaltet, um Zugriff.",
       deniedAdmins: ({ name }: { name: string }) => `${name} nutzen nur Cloud-Admins.`,
       deniedNoGuests: ({ name }: { name: string }) => `${name} nutzen nur angemeldete Personen außer Gästen.`,
       deniedRoles: ({ name }: { name: string }) => `${name} nutzen nur Personen mit bestimmten Cloud-Rollen.`,