@k2b/cloud 0.22.0 → 0.23.0

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";