@k2b/cloud 0.22.0 → 0.24.0

package/src/contracts/capability-compatibility.ts

@@ -8,6 +8,8 @@ import type { CapabilityActionManifest, CapabilityQueryManifest } from "./capabi
 export type CapabilityContract = {
   kind: "query" | "action";
   idempotency?: "required";
+  /** The binary stream direction the operation must declare. Without it, streaming operations do not match. */
+  stream?: "read" | "write";
   input: z.ZodType;
   data: z.ZodType;
 };
@@ -102,6 +104,20 @@ const patternMatches = (pattern: string, value: string): boolean => {
   }
 };
 
+type Bound = { value: number; exclusive: boolean };
+const lowerBound = (schema: Json): Bound | null =>
+  typeof schema.exclusiveMinimum === "number"
+    ? { value: schema.exclusiveMinimum, exclusive: true }
+    : typeof schema.minimum === "number"
+      ? { value: schema.minimum, exclusive: false }
+      : null;
+const upperBound = (schema: Json): Bound | null =>
+  typeof schema.exclusiveMaximum === "number"
+    ? { value: schema.exclusiveMaximum, exclusive: true }
+    : typeof schema.maximum === "number"
+      ? { value: schema.maximum, exclusive: false }
+      : null;
+
 /** Checks one literal value against a provider or contract schema. Unknown keywords never pass. */
 const valueIssue = (value: unknown, sup: Side, depth: number): string | null => {
   const resolved = deref(sup, depth);
@@ -126,22 +142,15 @@ const valueIssue = (value: unknown, sup: Side, depth: number): string | null =>
     if (typeof schema.maxLength === "number" && value.length > schema.maxLength) return "value is too long";
     if (typeof schema.pattern === "string" && !patternMatches(schema.pattern, value)) return "value does not match the pattern";
   }
+  if (typeof value === "number") {
+    const lower = lowerBound(schema);
+    const upper = upperBound(schema);
+    if (lower && (lower.exclusive ? value <= lower.value : value < lower.value)) return `value ${value} is out of range`;
+    if (upper && (upper.exclusive ? value >= upper.value : value > upper.value)) return `value ${value} is out of range`;
+  }
   return null;
 };
 
-type Bound = { value: number; exclusive: boolean };
-const lowerBound = (schema: Json): Bound | null =>
-  typeof schema.exclusiveMinimum === "number"
-    ? { value: schema.exclusiveMinimum, exclusive: true }
-    : typeof schema.minimum === "number"
-      ? { value: schema.minimum, exclusive: false }
-      : null;
-const upperBound = (schema: Json): Bound | null =>
-  typeof schema.exclusiveMaximum === "number"
-    ? { value: schema.exclusiveMaximum, exclusive: true }
-    : typeof schema.maximum === "number"
-      ? { value: schema.maximum, exclusive: false }
-      : null;
 const withinLower = (sub: Bound | null, sup: Bound | null): boolean =>
   !sup || (sub !== null && (sub.value > sup.value || (sub.value === sup.value && (sub.exclusive || !sup.exclusive))));
 const withinUpper = (sub: Bound | null, sup: Bound | null): boolean =>
@@ -356,7 +365,12 @@ export const capabilityContractIssues = (
     return [{ code: "kind", path: "$", message: `Expected ${contract.kind === "query" ? "a Query" : "an Action"}` }];
   }
   const issues: CapabilityContractIssue[] = [];
-  if (candidate.operation.stream) issues.push({ code: "stream", path: "$", message: "Streaming capabilities are not supported" });
+  const direction = candidate.operation.stream?.direction;
+  if (contract.stream && direction !== contract.stream) {
+    issues.push({ code: "stream", path: "$", message: `Expected a ${contract.stream} stream` });
+  } else if (!contract.stream && direction) {
+    issues.push({ code: "stream", path: "$", message: "Streaming capabilities are not supported" });
+  }
   if (contract.idempotency === "required" && candidate.kind === "action" && candidate.operation.idempotency !== "required") {
     issues.push({ code: "idempotency", path: "$", message: "The Action must require an idempotency key" });
   }

package/src/contracts/file-provider.ts

@@ -0,0 +1,158 @@
+import { z } from "zod";
+import type { CapabilityManifest } from "./capabilities";
+import { type CapabilityContract, type CapabilityContractIssue, capabilityContractIssues } from "./capability-compatibility";
+
+/**
+ * Provider-neutral file-provider contract.
+ *
+ * An application offers files to other applications by declaring
+ * `fileProvider: { list, read, save? }` in `defineCapabilities`. Each entry
+ * names one of its own Queries or Actions; the schemas below are the minimum
+ * both sides share. Identifiers and cursors are opaque provider strings, and
+ * the provider authorizes every call with the caller's own access.
+ */
+
+// Bounds follow the shared provider page: 100 entries, 3 tags of 40 characters.
+const ProviderIdSchema = z.string().min(1).max(2048);
+const CursorSchema = z.string().min(1).max(16384);
+const TimestampSchema = z.string().datetime({ offset: true });
+
+/** One display chip. Tags describe an entry; they are not a filter or a permission. */
+export const FileProviderTagSchema = z
+  .object({
+    label: z.string().min(1).max(40),
+    tone: z.enum(["neutral", "info", "success", "warning", "danger"]).optional(),
+  })
+  .strict();
+
+export const FileProviderListInputSchema = z
+  .object({
+    parent: ProviderIdSchema.optional().describe("Folder ID returned by this provider; omit for the provider root."),
+    query: z.string().max(200).optional().describe("Optional name filter inside the folder."),
+    cursor: CursorSchema.optional().describe("Opaque cursor returned by the previous page; keep parent, query, and limit unchanged."),
+    limit: z.number().int().min(1).max(100).default(50).describe("Maximum number of entries to return."),
+  })
+  .strict();
+
+const entryFacts = {
+  id: ProviderIdSchema,
+  name: z.string().min(1).max(255),
+  updatedAt: TimestampSchema.optional(),
+  icon: z.string().min(1).max(120).optional(),
+  tags: z.array(FileProviderTagSchema).max(3).optional(),
+};
+
+export const FileProviderEntrySchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("folder"), ...entryFacts }).loose(),
+  z
+    .object({
+      kind: z.literal("file"),
+      ...entryFacts,
+      size: z.number().int().min(0),
+      mediaType: z.string().min(1).max(255).optional(),
+    })
+    .loose(),
+]);
+
+/** One folder page. Folders may be virtual; pages may be short or empty and still continue while `next` is set. */
+export const FileProviderListDataSchema = z
+  .object({
+    writable: z.boolean(),
+    items: z.array(FileProviderEntrySchema).max(100),
+    next: CursorSchema.nullable(),
+  })
+  .loose();
+
+export const FileProviderReadInputSchema = z
+  .object({ id: ProviderIdSchema.describe("File ID returned by this provider's list.") })
+  .strict();
+export const FileProviderReadDataSchema = z.object({}).loose();
+
+/** A single file name: no path separators, control characters, `.` or `..`. */
+const FileNameSchema = z
+  .string()
+  .min(1)
+  .max(255)
+  .regex(/^(?!\.{1,2}$)[^/\\\u0000-\u001f\u007f]+$/);
+
+export const FileProviderSaveInputSchema = z
+  .object({
+    parent: ProviderIdSchema.describe("Writable folder ID returned by this provider's list."),
+    name: FileNameSchema.describe("Name of the new file."),
+    mediaType: z
+      .string()
+      .min(1)
+      .max(255)
+      .regex(/^[\x20-\x7e]+$/)
+      .describe("Media type of the content."),
+    size: z.number().int().min(0).describe("Exact byte count of the content."),
+  })
+  .strict();
+
+/** `file` is present once the write stream completed; the call that opens the stream has no file yet. */
+export const FileProviderSaveDataSchema = z
+  .object({
+    file: z
+      .object({ id: ProviderIdSchema, name: z.string().min(1).max(255), size: z.number().int().min(0) })
+      .loose()
+      .optional(),
+  })
+  .loose();
+
+/**
+ * The error code `save` answers, with status `409`, when the name already
+ * exists in the folder. Consumers ask for another name only on this code;
+ * every other failure keeps its own code, even with status `409`.
+ */
+export const FILE_PROVIDER_NAME_CONFLICT = "FILE_NAME_CONFLICT";
+
+/**
+ * The three file-provider functions. `read` streams the file's bytes, `save`
+ * is an idempotent Action with a write stream that only creates files: an
+ * existing name fails with `FILE_PROVIDER_NAME_CONFLICT`.
+ */
+export const fileProvider = {
+  list: { kind: "query", input: FileProviderListInputSchema, data: FileProviderListDataSchema },
+  read: { kind: "query", input: FileProviderReadInputSchema, data: FileProviderReadDataSchema, stream: "read" },
+  save: {
+    kind: "action",
+    idempotency: "required",
+    input: FileProviderSaveInputSchema,
+    data: FileProviderSaveDataSchema,
+    stream: "write",
+  },
+} as const satisfies Record<string, CapabilityContract>;
+
+export type FileProviderFunction = keyof typeof fileProvider;
+export const FILE_PROVIDER_FUNCTIONS = ["list", "read", "save"] as const satisfies readonly FileProviderFunction[];
+
+export type FileProviderTag = z.output<typeof FileProviderTagSchema>;
+export type FileProviderEntry = z.output<typeof FileProviderEntrySchema>;
+export type FileProviderListData = z.output<typeof FileProviderListDataSchema>;
+export type FileProviderSaveData = z.output<typeof FileProviderSaveDataSchema>;
+
+export type FileProviderIssue = CapabilityContractIssue & { function: FileProviderFunction; localId: string };
+
+/**
+ * Explains why a manifest's `fileProvider` declaration cannot serve the
+ * contract. Apps run it at start and fail; Core runs it when it reads a live
+ * manifest and ignores an invalid declaration. An empty list means valid or
+ * not declared.
+ */
+export const fileProviderIssues = (manifest: CapabilityManifest): FileProviderIssue[] => {
+  const declaration = manifest.fileProvider;
+  if (!declaration) return [];
+  return FILE_PROVIDER_FUNCTIONS.flatMap((name) => {
+    const localId = declaration[name];
+    if (localId === undefined) return [];
+    const contract = fileProvider[name];
+    const query = manifest.queries.find((operation) => operation.localId === localId);
+    const action = manifest.actions.find((operation) => operation.localId === localId);
+    const issues = query
+      ? capabilityContractIssues(contract, { kind: "query", operation: query })
+      : action
+        ? capabilityContractIssues(contract, { kind: "action", operation: action })
+        : [{ code: "kind" as const, path: "$", message: `No Query or Action named ${localId}` }];
+    return issues.map((issue) => ({ ...issue, function: name, localId }));
+  });
+};

package/src/contracts/index.ts

@@ -6,9 +6,11 @@ export * from "./capabilities";
 export * from "./capability-compatibility";
 export * from "./commands";
 export * from "./contact-directory";
+export * from "./file-provider";
 export * from "./notification-types";
 export * from "./posix";
 export * from "./profile";
+export * from "./pwa";
 // Core app bar administration and shared shortcut values.
 export { RailAccessSchema, type RailAdminEntry, RailAdminInputSchema, RailAdminSchema, type RailAdminState } from "./rail-admin";
 export type { RailShortcut } from "./rail-preferences";

package/src/contracts/pwa-paths.ts

@@ -0,0 +1,6 @@
+/**
+ * Paths of the installable mobile app, without schemas, so browser code that runs on every page can test for an
+ * app page without loading the contract's validators.
+ */
+export const PWA_SCOPE = "/pwa/";
+export const PWA_AUTH_PATH = "/pwa/_auth";

package/src/contracts/pwa.ts

@@ -0,0 +1,156 @@
+import { z } from "zod";
+import { PWA_AUTH_PATH, PWA_SCOPE } from "./pwa-paths";
+
+export { PWA_AUTH_PATH, PWA_SCOPE };
+
+/**
+ * The installable mobile app (preview). One shell application `pwa` owns the
+ * manifest scope `/pwa/`; Core owns the phone-side identity endpoints below
+ * `/pwa/_auth` and the web-side pairing API.
+ */
+export const PWA_SHELL_APP_ID = "pwa";
+export const PWA_API_PATH = "/api/auth/pwa/v1";
+export const PWA_MANIFEST_PATH = "/pwa/manifest.webmanifest";
+export const PWA_SERVICE_WORKER_PATH = "/pwa/sw.js";
+/** Ids that can never own a part: the shell itself and its own pages `/pwa/settings` and `/pwa/offline`. */
+export const PWA_RESERVED_IDS = ["pwa", "settings", "offline"] as const;
+/** Whether the app with this id may have a part at `/pwa/<id>`: a plain app id that the shell does not reserve. */
+export const isPwaPartId = (id: string): boolean => /^[a-z][a-z0-9-]*$/.test(id) && !PWA_RESERVED_IDS.some((reserved) => reserved === id);
+/**
+ * The page canvas of the app (`--k2b-surface-canvas` of `@k2b/ui`) in light and dark. App documents paint it
+ * before any stylesheet loads and give it to the status bar.
+ */
+export const PWA_CANVAS_COLORS = { light: "#fafafa", dark: "#090d12" } as const;
+
+/** Cookie names. Only `pwa_session` reaches every application; the others use Core-only paths. */
+export const PWA_COOKIES = {
+  session: "pwa_session",
+  device: "pwa_device",
+  pairing: "pwa_pairing",
+} as const;
+
+export const PWA_LIMITS = {
+  /** Same as the Cloud Login API. */
+  bodyBytes: 8192,
+  /** A visible link can be claimed for five minutes. */
+  linkClaimSeconds: 300,
+  /** Claim, typing the code and completion. */
+  pairingSeconds: 600,
+  /** Starting a pairing needs a web sign-in from the last ten minutes. */
+  recentSessionSeconds: 600,
+  /** Wrong codes before the pairing is cancelled. */
+  confirmAttempts: 3,
+  devicesPerAccount: 20,
+  pendingPerAccount: 5,
+  /** A paired phone ends after this many days without use. */
+  idleDays: 150,
+  /** Lifetime of one app session. */
+  sessionSeconds: 86_400,
+  /** Renew when the app session has less than this left. */
+  renewWithinSeconds: 43_200,
+  /** Parallel renewals within this window do not re-issue. */
+  rotationGraceSeconds: 60,
+  pollSeconds: 5,
+  nameMaxLength: 80,
+} as const;
+
+/** True while a live app with id "pwa" owns "/pwa". Pure; Core uses it for gating. */
+export const isPwaShellAvailable = (apps: readonly { id: string; routes: readonly string[] }[]): boolean =>
+  apps.some((app) => app.id === PWA_SHELL_APP_ID && app.routes.includes("/pwa"));
+
+const SECRET_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+
+/** The link the web shows as QR code and copy text. The secret lives only in the fragment. */
+export const pairingLink = (origin: string, secret: string): string => {
+  if (!SECRET_PATTERN.test(secret)) throw new Error("Invalid pairing secret");
+  return `${new URL(origin).origin}${PWA_SCOPE}#pair=${secret}`;
+};
+
+export type PairingLinkResult = { ok: true; secret: string } | { ok: false; reason: "invalid" | "other-cloud" | "cloud-login" };
+
+/** Strict parser for scanned or pasted text. Never fetches anything. */
+export const parsePairingLink = (text: string, origin: string): PairingLinkResult => {
+  if (text.length > PWA_LIMITS.bodyBytes) return { ok: false, reason: "invalid" };
+  let url: URL;
+  try {
+    url = new URL(text.trim());
+  } catch {
+    return { ok: false, reason: "invalid" };
+  }
+  if (url.hash.startsWith("#pairing=")) return { ok: false, reason: "cloud-login" };
+  if (!url.hash.startsWith("#pair=") || url.pathname !== PWA_SCOPE || url.search || url.username || url.password) {
+    return { ok: false, reason: "invalid" };
+  }
+  if (url.origin !== new URL(origin).origin) return { ok: false, reason: "other-cloud" };
+  const secret = url.hash.slice("#pair=".length);
+  return SECRET_PATTERN.test(secret) ? { ok: true, secret } : { ok: false, reason: "invalid" };
+};
+
+const Id = z.string().uuid();
+const DateTime = z.string().datetime();
+const Code = z.string().regex(/^\d{6}$/);
+
+export const PwaPlatformSchema = z.enum(["ios", "android", "other"]);
+export type PwaPlatform = z.infer<typeof PwaPlatformSchema>;
+export const PwaPairingStateSchema = z.enum(["pending", "claimed", "confirmed", "completed", "cancelled"]);
+export type PwaPairingState = z.infer<typeof PwaPairingStateSchema>;
+/** States of `/pwa/` the launch bounce leads to when it cannot renew. */
+export const PwaLaunchStateSchema = z.enum(["new", "ended", "blocked", "unavailable"]);
+export type PwaLaunchState = z.infer<typeof PwaLaunchStateSchema>;
+
+export const PwaErrorCodeSchema = z.enum([
+  "UNAVAILABLE",
+  "REAUTHENTICATE",
+  "FORBIDDEN",
+  "ACCOUNT_BLOCKED",
+  "INVALID_REQUEST",
+  "NOT_FOUND",
+  "EXPIRED",
+  "ALREADY_USED",
+  "WRONG_CODE",
+  "CONFLICT",
+  "ALREADY_PAIRED",
+  "ACCOUNT_MISMATCH",
+  "LIMIT_REACHED",
+  "UNPAIRED",
+]);
+export type PwaErrorCode = z.infer<typeof PwaErrorCodeSchema>;
+export const PwaErrorSchema = z.object({ code: PwaErrorCodeSchema, message: z.string(), attemptsLeft: z.number().int().optional() });
+
+// Web side (`/api/auth/pwa/v1`).
+export const PwaPairingStartResultSchema = z
+  .object({ id: Id, secret: z.string().regex(SECRET_PATTERN), claimUntil: DateTime, expiresAt: DateTime })
+  .strict();
+export const PwaPairingStatusSchema = z
+  .object({
+    state: PwaPairingStateSchema,
+    claimUntil: DateTime,
+    expiresAt: DateTime,
+    device: z.object({ name: z.string(), platform: PwaPlatformSchema }).strict().nullable(),
+    attemptsLeft: z.number().int().min(0),
+  })
+  .strict();
+export const PwaPairingConfirmSchema = z.object({ code: Code }).strict();
+export const PwaDeviceViewSchema = z
+  .object({
+    id: Id,
+    name: z.string(),
+    platform: PwaPlatformSchema,
+    createdAt: DateTime,
+    lastUsedAt: DateTime,
+    current: z.boolean(),
+  })
+  .strict();
+export type PwaDeviceView = z.infer<typeof PwaDeviceViewSchema>;
+export const PwaDeviceListSchema = z.object({ items: z.array(PwaDeviceViewSchema) }).strict();
+
+// Phone side (`/pwa/_auth`).
+export const PwaClaimSchema = z.object({ secret: z.string().regex(SECRET_PATTERN), platform: PwaPlatformSchema }).strict();
+const Account = z.object({ name: z.string() }).strict();
+export const PwaClaimResultSchema = z.object({ code: Code, account: Account, expiresAt: DateTime }).strict();
+export const PwaCompleteResultSchema = z.discriminatedUnion("state", [
+  z.object({ state: z.literal("paired") }).strict(),
+  z.object({ state: z.literal("waiting"), code: Code, account: Account, expiresAt: DateTime }).strict(),
+]);
+export const PwaRenewResultSchema = z.object({ renewed: z.boolean(), otherAccount: Account.optional() }).strict();
+export const PwaRenameSchema = z.object({ name: z.string().trim().min(1).max(PWA_LIMITS.nameMaxLength) }).strict();

package/src/contracts/registry.ts

@@ -18,6 +18,11 @@ export type AppRegistryNav = {
   adminHref?: string;
 };
 
+export type AppRegistryPwaPart = {
+  href: string;
+  requiresRoles?: Role[];
+};
+
 export type AppRegistryCapabilitySummary = {
   protocolVersion: number;
   manifestHash: string;
@@ -80,6 +85,8 @@ export type AppRegistryEntry = {
   help?: AppRegistryHelpSummary;
   legalLinks?: AppRegistryLegalLink[];
   searchLinks?: readonly AppSearchLink[];
+  /** The app's part of the mobile app (preview); `href` is `/pwa/<id>`. Older readers ignore it. */
+  pwa?: AppRegistryPwaPart;
   widgets?: AppRegistryWidget[];
   /** Setting keys declared by this app. Used by admin tooling to avoid treating live app-owned settings as legacy. */
   settingKeys?: readonly string[];

package/src/contracts/shared.ts

@@ -414,7 +414,13 @@ export type InvocationProvenance = {
   workloadId?: string;
 };
 
-export type UserRequestActor = { kind: "user"; user: User; delegation?: InvocationProvenance };
+export type UserRequestActor = {
+  kind: "user";
+  user: User;
+  delegation?: InvocationProvenance;
+  /** `"app"` when the person acts through the mobile app's session; see the server's `UserRequestActor`. */
+  sessionKind?: "app";
+};
 
 export type ServiceAccountRequestActor = {
   kind: "service_account";

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export type { LiveChannel, LiveViewer } from "./live";
+export { defineLive } from "./live";