@k2b/cloud 0.38.0 → 0.40.0

package/src/contracts/app-approval.ts

@@ -30,7 +30,23 @@ export const APP_ACTION_LIMITS = {
   valueChars: 300,
 } as const;
 /** Commands a Cloud serves beyond the first version, announced in `/info` as `features`. */
-export const APP_APPROVAL_FEATURES = ["actions"] as const;
+export const APP_APPROVAL_FEATURES = ["actions", "terminal-logins", "login-context", "device-changes"] as const;
+/**
+ * Optional inbox parts a device asks for in its signed `inbox` command. Without `accept`, the command, its
+ * signed message and the inbox answer keep their first form byte for byte.
+ */
+export const APP_APPROVAL_ACCEPT = ["terminal-logins", "login-context", "device-changes"] as const;
+export type AppApprovalAccept = (typeof APP_APPROVAL_ACCEPT)[number];
+export const APP_APPROVAL_PENDING_ACCEPT = ["login-context"] as const;
+export type AppApprovalPendingAccept = (typeof APP_APPROVAL_PENDING_ACCEPT)[number];
+
+const acceptList = <T extends readonly [string, ...string[]]>(values: T) =>
+  z
+    .array(z.enum(values))
+    .min(1)
+    .max(8)
+    .refine((entries) => new Set(entries).size === entries.length)
+    .optional();
 
 const Id = z.string().uuid();
 const Secret = z.string().regex(/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/);
@@ -67,21 +83,42 @@ export const AppLoginStartSchema = z
 export const AppLoginReferenceSchema = z.object({ requestId: Id, browserSecret: Secret }).strict();
 export const AppDeviceMutationSchema = z.discriminatedUnion("operation", [
   z.object({ operation: z.literal("rename"), deviceId: Id, name: z.string().trim().min(1).max(80) }).strict(),
-  z.object({ operation: z.literal("revoke"), deviceId: Id }).strict(),
+  /**
+   * Asks the account's paired devices to approve removing this device. `endSessions` (default `true`) also ends
+   * the sign-ins this device approved, except the requesting session.
+   */
+  z.object({ operation: z.literal("revoke"), deviceId: Id, endSessions: z.boolean().optional() }).strict(),
 ]);
 export const AppDeviceCommandSchema = z.discriminatedUnion("operation", [
-  z.object({ operation: z.literal("pending") }).strict(),
+  z.object({ operation: z.literal("pending"), accept: acceptList(APP_APPROVAL_PENDING_ACCEPT) }).strict(),
   z.object({ operation: z.literal("revoke") }).strict(),
   /** Reads the signing device's own account and device record, e.g. to show which account it signs in. */
   z.object({ operation: z.literal("account") }).strict(),
   /** Stores the authenticator's opaque push token for sign-in wake-ups on this device. */
   z.object({ operation: z.literal("push"), token: z.string().regex(/^[A-Za-z0-9_-]{43}$/) }).strict(),
   /** Pending sign-ins and the newest open Action approvals of the signing device's account in one call. */
-  z.object({ operation: z.literal("inbox") }).strict(),
+  z
+    .object({
+      operation: z.literal("inbox"),
+      /** Optional inbox parts this device shows; only send values the Cloud lists in `/info` `features`. */
+      accept: acceptList(APP_APPROVAL_ACCEPT),
+    })
+    .strict(),
   /** One open Action approval as the device shows it, with the digest the device recomputes before it decides. */
   z.object({ operation: z.literal("action"), actionId: Id }).strict(),
   /** Decides an Action approval. `digest` binds the decision to exactly the view the person saw. */
   z.object({ operation: z.literal("act"), actionId: Id, digest: Digest, decision: z.enum(["approve", "deny"]) }).strict(),
+  /** Decides a request to pair or remove a device of the signing device's account. Binds every fact the device showed. */
+  z
+    .object({
+      operation: z.literal("change"),
+      changeId: Id,
+      kind: z.enum(["pair", "revoke"]),
+      targetId: Id,
+      endSessions: z.boolean(),
+      decision: z.enum(["approve", "deny"]),
+    })
+    .strict(),
   z
     .object({
       operation: z.literal("decide"),
@@ -121,6 +158,8 @@ export const appDeviceProofMessage = (proof: AppDeviceProof): string => {
     c.operation,
     ...(c.operation === "decide" ? [c.requestId, c.challenge, c.comparison, c.decision] : []),
     ...(c.operation === "push" ? [c.token] : []),
+    ...((c.operation === "inbox" || c.operation === "pending") && c.accept !== undefined ? [c.accept] : []),
+    ...(c.operation === "change" ? [c.changeId, c.kind, c.targetId, c.endSessions, c.decision] : []),
     ...(c.operation === "action" ? [c.actionId] : []),
     ...(c.operation === "act" ? [c.actionId, c.digest, c.decision] : []),
   ]);
@@ -151,8 +190,79 @@ export const AppDeviceViewSchema = z
     assisted: z.boolean(),
   })
   .strict();
+/** Plain text on one line: no control, format or bidirectional characters, so an app cannot fake Cloud's own frame. */
+const PlainText = (max: number) =>
+  z
+    .string()
+    .refine((value) => Array.from(value).length <= max, `Must contain at most ${max} code points`)
+    .regex(/^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]*$/u);
+export const AppTerminalLoginSchema = z
+  .object({
+    client: z
+      .object({
+        // Bound encoded bytes including escapes, so five complete consent rows fit the response budget.
+        id: PlainText(256)
+          .min(1)
+          .refine((value) => new TextEncoder().encode(JSON.stringify(value)).length <= 258),
+        name: PlainText(APP_ACTION_LIMITS.nameChars).min(1),
+      })
+      .strict(),
+    scopes: z
+      .array(z.string().regex(/^[a-z][a-z0-9_:.-]{0,39}$/))
+      .min(1)
+      .max(16),
+    lifetimeSeconds: z.number().int().positive(),
+  })
+  .strict();
+export type AppTerminalLogin = z.infer<typeof AppTerminalLoginSchema>;
+export const APP_LOGIN_CONTEXT_BROWSERS = ["firefox", "chrome", "safari", "edge", "samsung", "opera", "other"] as const;
+export const APP_LOGIN_CONTEXT_OSES = ["windows", "macos", "mac-or-ipad", "ios", "android", "linux", "chromeos", "other"] as const;
+const ContextName = PlainText(96)
+  .min(1)
+  .refine((value) => new TextEncoder().encode(value).length <= 96);
+/** Core alone computes the level. The app displays it and never derives its own.
+ * Terminal logins never carry context. Opted-in browser logins carry it unless
+ * started before the upgrade or omitted to fit the response budget.
+ * History is null during introduction; sameNetwork is a positive, transient hint. */
+export const AppLoginContextSchema = z
+  .object({
+    /** Computed by Core only; descriptive signals never change it. */
+    level: z.enum(["info", "hint", "warn"]),
+    browser: z.enum(APP_LOGIN_CONTEXT_BROWSERS),
+    os: z.enum(APP_LOGIN_CONTEXT_OSES),
+    country: z
+      .string()
+      .regex(/^[A-Z]{2}$/)
+      .nullable(),
+    city: ContextName.nullable(),
+    /** Operator name, never a VPN or data-center classification. */
+    network: ContextName.nullable(),
+    history: z
+      .object({
+        /** This browser's first_seen_at for the account, or null when unknown. */
+        knownSince: DateTime.nullable(),
+        /** A request country, geoip_since set, and no sign-in from it inside the 90-day window. */
+        newCountry: z.boolean(),
+        /** geoip_since only when less than 90 days ago; the app can say "since {date}". */
+        countriesSince: DateTime.nullable(),
+      })
+      .strict()
+      .nullable(),
+    sameNetwork: z.literal(true).optional(),
+  })
+  .strict();
+export type AppLoginContext = z.infer<typeof AppLoginContextSchema>;
+
 export const AppPendingLoginSchema = z
-  .object({ requestId: Id, challenge: Secret, comparison: Comparison, createdAt: DateTime, expiresAt: DateTime })
+  .object({
+    requestId: Id,
+    challenge: Secret,
+    comparison: Comparison,
+    createdAt: DateTime,
+    expiresAt: DateTime,
+    terminal: AppTerminalLoginSchema.optional(),
+    context: AppLoginContextSchema.optional(),
+  })
   .strict();
 export const AppPairingPayloadSchema = z
   .object({ protocol: z.literal(APP_APPROVAL_PROTOCOL), issuer: z.string().url(), pairingId: Id, secret: Secret, expiresAt: DateTime })
@@ -205,8 +315,29 @@ export const AppPairingClaimResultSchema = z.object({ deviceId: Id, comparison:
 export const AppPairingResultSchema = z
   .object({ state: z.enum(["pending", "claimed", "confirmed", "cancelled"]), deviceId: Id.nullable(), comparison: Comparison.nullable() })
   .strict();
+/** Approval of a pairing by one of the account's paired devices, as the initiating browser follows it. */
+export const AppDeviceChangeStatusSchema = z
+  .object({ state: z.enum(["pending", "approved", "denied", "cancelled", "expired"]), expiresAt: DateTime })
+  .strict();
+export type AppDeviceChangeStatus = z.infer<typeof AppDeviceChangeStatusSchema>;
 /** Initiating Cloud session only; never returned to an unpaired device. */
-export const AppPairingInspectionSchema = AppPairingResultSchema.extend({ name: z.string().nullable(), userId: Id });
+export const AppPairingInspectionSchema = AppPairingResultSchema.extend({
+  name: z.string().nullable(),
+  userId: Id,
+  /** Set once the code was confirmed while the account already had a paired device: one of them approves. */
+  approval: AppDeviceChangeStatusSchema.nullable(),
+});
+/** `approval` is set when one of the account's paired devices must approve before the device is paired. */
+export const AppPairingConfirmResultSchema = z.object({ deviceId: Id, approval: AppDeviceChangeStatusSchema.nullable() }).strict();
+export const AppDeviceChangeReferenceSchema = z.object({ changeId: Id }).strict();
+/** A removal by its id, or this session's newest removal of a device, e.g. after the answer that named it was lost. */
+export const AppDeviceChangeLookupSchema = z.union([AppDeviceChangeReferenceSchema, z.object({ deviceId: Id }).strict()]);
+export const AppDeviceRemovalStatusSchema = AppDeviceChangeStatusSchema.extend({ changeId: Id, endSessions: z.boolean() }).strict();
+/** A device that is already revoked answers `revoked`; an active one waits for approval on a paired device. */
+export const AppDeviceRevokeResultSchema = z.union([
+  z.object({ state: z.literal("revoked") }).strict(),
+  z.object({ state: z.literal("pending"), changeId: Id, expiresAt: DateTime }).strict(),
+]);
 /** Answer to the `account` command: only the signing device's own account, never secrets or other users. */
 export const AppDeviceAccountSchema = z
   .object({
@@ -215,12 +346,6 @@ export const AppDeviceAccountSchema = z
   })
   .strict();
 export type AppDeviceAccount = z.infer<typeof AppDeviceAccountSchema>;
-/** Plain text on one line: no control, format or bidirectional characters, so an app cannot fake Cloud's own frame. */
-const PlainText = (max: number) =>
-  z
-    .string()
-    .refine((value) => Array.from(value).length <= max, `Must contain at most ${max} code points`)
-    .regex(/^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]*$/u);
 const ActionApp = z
   .object({ id: PlainText(APP_ACTION_LIMITS.nameChars).min(1), name: PlainText(APP_ACTION_LIMITS.nameChars).min(1) })
   .strict();
@@ -276,6 +401,27 @@ export const AppDeviceInboxSchema = z
   })
   .strict();
 export type AppDeviceInbox = z.infer<typeof AppDeviceInboxSchema>;
+/** A request to pair or remove a device of this account, shown to the account's paired devices. */
+export const AppDeviceChangeSchema = z
+  .object({
+    changeId: Id,
+    kind: z.enum(["pair", "revoke"]),
+    /** The device to pair or remove, with the name the account gave it. The name may be empty. */
+    device: z.object({ id: Id, name: PlainText(80) }).strict(),
+    /** Removal only: also end the sign-ins this device approved. Always `false` for a pairing. */
+    endSessions: z.boolean(),
+    createdAt: DateTime,
+    expiresAt: DateTime,
+  })
+  .strict();
+export type AppDeviceChange = z.infer<typeof AppDeviceChangeSchema>;
+/** The inbox for a device that sent `accept: ["device-changes"]`. Oldest first. */
+export const AppDeviceInboxWithChangesSchema = AppDeviceInboxSchema.extend({
+  changes: z.array(AppDeviceChangeSchema).max(APP_APPROVAL_LIMITS.pendingPerAccount),
+  /** Pending device changes omitted to fit the response budget. */
+  moreChanges: z.number().int().nonnegative().max(APP_APPROVAL_LIMITS.pendingPerAccount),
+}).strict();
+export type AppDeviceInboxWithChanges = z.infer<typeof AppDeviceInboxWithChangesSchema>;
 
 /** UTF-8 of this exact JSON array is hashed into an Action's `digest`. Every field the device shows is part of it. */
 export const appActionDigestMessage = (issuer: string, view: Omit<AppActionView, "digest">): string =>
@@ -316,6 +462,7 @@ export const AppDeviceResponseSchema = z.union([
   z.object({ state: z.enum(["approved", "denied", "revoked", "updated"]) }).strict(),
   AppDeviceAccountSchema,
   AppDeviceInboxSchema,
+  AppDeviceInboxWithChangesSchema,
   AppActionViewSchema,
 ]);
 export const AppLoginStartResultSchema = z

package/src/contracts/app.ts

@@ -58,6 +58,7 @@ export type AppAdminNavigationGroup = {
 
 export type AppPresentationTranslation = {
   name?: string;
+  panelLabel?: string;
   description?: string;
   /** Group labels keyed by `adminNav[].id`. */
   adminGroups?: Readonly<Record<string, string>>;
@@ -107,6 +108,18 @@ export type AppPwaPart = {
   requiresRoles?: Role[];
 };
 
+/** One same-origin panel page contributed by an application. Routes and services still authorize. */
+export type AppPanel = {
+  /** GET page below the app's routes, rendered with PanelLayout. */
+  href: string;
+  /** Panel name in the app's base locale; translated with presentation.translations[locale].panelLabel. */
+  label: string;
+  /** Icon class, for example "ti ti-sparkles". */
+  icon: string;
+  /** Coarse visibility like nav.requiresRoles; the slot grants no access. */
+  requiresRoles?: Role[];
+};
+
 export type AppMeta = {
   platformPermissions?: readonly PlatformPermission[];
   id: string;
@@ -142,6 +155,7 @@ export type AppMeta = {
   searchLinks?: readonly AppSearchLink[];
   /** The app's pages in the installable mobile app (preview), at `href` = `/pwa/<id>`. */
   pwa?: AppPwaPart;
+  panel?: AppPanel;
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
    * HTTP endpoint that returns a `WidgetResponse` (see `contracts/widgets.ts`).

package/src/contracts/approvals.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { APP_APPROVAL_LIMITS } from "./app-approval";
-import { CapabilityActionReviewSchema, CapabilityAppIdSchema } from "./capabilities";
+import { CapabilityActionReviewDataSchema, CapabilityAppIdSchema } from "./capabilities";
 
 export { APPROVAL_COUNTS_PATH, APPROVALS_API_PATH, APPROVALS_PAGE_PATH } from "./approval-paths";
 
@@ -42,7 +42,7 @@ export const PendingApprovalSchema = z
     /** What the person reads: the first line names the app and the Action, later lines add `Label: value` details. */
     sentence: z.string(),
     /** The owning app's review as the person saw it when Cloud asked. */
-    review: CapabilityActionReviewSchema.nullable(),
+    review: CapabilityActionReviewDataSchema.nullable(),
     /** Where the request waits. The title is chat content, written by a person or a model, never Cloud's own words. */
     requester: z.object({ kind: z.literal("chat"), appId: z.string(), title: z.string().nullable(), href: z.string() }).strict(),
     /** Ways the person may remember this approval, the same the chat card offers. */