@camstack/types 1.2.332 → 1.2.334

package/dist/addon/base-addon.d.ts

@@ -128,6 +128,14 @@ export declare abstract class BaseAddon<TConfig extends object = Record<string,
     private _secretChangeUnsub;
     /** >0 while an OPERATOR's settings write is being applied. */
     private _operatorWriteDepth;
+    /**
+     * The keychain-aware settings handle (D798). Its `raw` view is the ONLY way
+     * to the marker-bearing blobs and stays private to this class: the form
+     * hydrate and config resolution need markers, addon code never does.
+     */
+    private _secretSettings;
+    /** Refs an addon-facing read could not resolve — each is logged once per process. */
+    private _loggedUnresolvedReads;
     constructor(defaults: TConfig);
     /**
      * Override to opt out of the automatic `system.ready-state` emission.
@@ -279,8 +287,25 @@ export declare abstract class BaseAddon<TConfig extends object = Record<string,
      * the store for custom option logic (option narrowing, value snapping) to
      * read it per-node — never `ctx.settings.readAddonStore()` directly.
      * `nodeId` omitted ⇒ the local node (node-blind injection from ctx).
+     *
+     * Keychain values come back RESOLVED (D798): a secret reads as its value,
+     * never as a `{ $secret }` marker. One the keychain cannot serve right now
+     * stays a marker — "stored, unavailable" (`isSecretMarker()` is true, and it
+     * is listed in {@link unresolvedSecrets}) — never `''` and never absent, so
+     * it cannot be mistaken for "nothing stored, mint a new one". Writing the
+     * resolved blob back is a no-op for every unchanged secret.
      */
     protected resolveGlobalStore(nodeId?: string, cap?: string): Promise<Record<string, unknown>>;
+    private projectForNode;
+    /** The PROJECTED store with its markers — the form hydrate only (D798). */
+    private readRawProjectedStore;
+    /**
+     * `{ ...stored, ...overlay }`, except that an overlay member equal to the
+     * RESOLVED stored one keeps the stored (marker-bearing) member — so a form
+     * hydrated from a resolved overlay still shows a secret as "set", never as
+     * its value.
+     */
+    private overlayKeepingMarkers;
     /**
      * Whether ONE global key of this addon's store was written, read three-way
      * (D651). For a question a hydrated view cannot answer: `getGlobalSettings`
@@ -422,6 +447,13 @@ export declare abstract class BaseAddon<TConfig extends object = Record<string,
      * ever written back from here.
      */
     private resolveStoredSecrets;
+    /**
+     * The marker-bearing settings reads (D798) — private on purpose. Without a
+     * keychain the context's own view is already raw.
+     */
+    private rawSettings;
+    /** An addon-facing read met markers it could not resolve: say so once per ref. */
+    private logUnresolvedRead;
     /** Re-resolve the config (a keychain-only change, or a retry) and apply it. */
     private scheduleSecretReresolve;
     /**

package/dist/addon/secret-aware-context.d.ts

@@ -1,9 +1,27 @@
 /**
- * Wrap an addon context so EVERY write to its settings store goes through the
- * keychain save path (D787) — `updateGlobalSettings`, `state()` handles, and an
- * addon's own direct `ctx.settings.writeAddonStore` / `writeDeviceStore` calls
- * alike. Reads stay raw (markers): a read surface never sees a value, and the
- * runtime resolves through `BaseAddon`.
+ * The settings view an addon sees once the kernel provides a keychain.
+ *
+ * READ (D798) — every addon-facing read answers VALUES, never markers:
+ * `readAddonStore`, `readAddonStoreResult`, `readAddonStoreKeyResult`,
+ * `readDeviceStore`, `readDeviceStoreBatch`. Markers are resolved through the
+ * addon's own `ctx.secrets` (owner-checked by the keychain, batched into one
+ * round trip per read, served from its cache). A marker that cannot be
+ * resolved STAYS a marker — "stored, unavailable right now" — and is reported
+ * through `onUnresolved`; it never reads as `''` or as absent, which is what
+ * invites a regenerate-and-save over the kept value. Three addons read their
+ * raw config and got a marker in place of their secret in one evening after
+ * the keychain migration (Wyze, ONVIF, Reolink); this is the root fix.
+ *
+ * WRITE (D787) — every write goes through the keychain save path, with the
+ * write-back of a resolved read made idempotent (`secret-write-back.ts`): an
+ * unchanged value becomes its marker again, nothing is put, a patch equal to
+ * what is stored is not written at all.
+ *
+ * RAW — the marker-bearing blob is reachable only through the handle's `raw`
+ * view, which `BaseAddon` keeps PRIVATE for the paths that need markers: the
+ * admin form hydrate (markers become "set" views), config resolution (which
+ * tracks unresolved refs for retry) and the save path itself. No addon code
+ * can reach it.
  *
  * A Proxy rather than a copy: an in-process context carries getters (`api`)
  * and a spread would freeze them at wrap time; a Proxy forwards every other
@@ -12,6 +30,8 @@
 import type { AddonContext } from '../interfaces/addon.js';
 import type { SecretsAccess } from '../keychain/secrets-access.js';
 import type { SecretTree } from './secret-paths.js';
+import { type UnresolvedSecret } from './secret-settings-view.js';
+type SettingsView = NonNullable<AddonContext['settings']>;
 export interface SecretAwareSettingsOptions {
     readonly secrets: SecretsAccess;
     /** The addon store's secret tree (schema + `secretStatePaths`). */
@@ -22,6 +42,29 @@ export interface SecretAwareSettingsOptions {
     readonly onOrphaned: (refs: readonly string[]) => void;
     /** Is the write in progress the OPERATOR's (see `SecretWriteInput.operatorWrite`)? */
     readonly isOperatorWrite?: () => boolean;
+    /** Told when an addon-facing read met markers it could not resolve. */
+    readonly onUnresolved?: (unresolved: readonly UnresolvedSecret[]) => void;
+}
+/** Whether a write reached the store or the keychain. */
+export interface SecretAwareWriteOutcome {
+    readonly changed: boolean;
+}
+export interface SecretAwareSettingsHandle {
+    /** The view addon code gets: resolved reads, secret-aware writes. */
+    readonly settings: SettingsView;
+    /**
+     * The stored blobs WITH markers. For `BaseAddon`'s private use only — the
+     * form hydrate, config resolution, the save path. Never hand it to addon code.
+     */
+    readonly raw: Pick<SettingsView, 'readAddonStore' | 'readDeviceStore'>;
+    /** `settings.writeAddonStore`, also saying whether anything changed. */
+    writeAddonStore(patch: Record<string, unknown>): Promise<SecretAwareWriteOutcome>;
 }
-/** The context the addon sees: identical, except that its settings writes are secret-aware. */
+/** The context the addon sees, plus the private raw view and write outcome. */
+export declare function createSecretAwareContext(context: AddonContext, opts: SecretAwareSettingsOptions): {
+    readonly context: AddonContext;
+    readonly handle: SecretAwareSettingsHandle | null;
+};
+/** The context the addon sees: resolved reads, secret-aware writes. */
 export declare function withSecretAwareSettings(context: AddonContext, opts: SecretAwareSettingsOptions): AddonContext;
+export {};

package/dist/addon/secret-settings-view.d.ts

@@ -73,8 +73,30 @@ export interface ResolvedSecrets<T> {
     readonly value: T;
     readonly unresolved: readonly UnresolvedSecret[];
 }
+/**
+ * What a marker that cannot be resolved becomes:
+ *  - `omit` (default) — the member is LEFT OUT, so a typed default applies
+ *    (`config`, `state()`, a driver's device config);
+ *  - `keep-marker` — the marker STAYS where it is. An addon-facing raw read
+ *    (D798) answers "stored, but unavailable right now": present, not a string,
+ *    `isSecretMarker()` true. Never `''`, never absent — both of those read as
+ *    "nothing stored" and invite a regenerate-and-save over the kept value.
+ */
+export type UnresolvedMarkerMode = 'omit' | 'keep-marker';
+export interface ResolveSecretMarkersOptions {
+    readonly unresolved?: UnresolvedMarkerMode;
+    /**
+     * Resolve only the markers this owner's refs: any other owner's marker is
+     * left exactly as it is — not resolved, not reported. A system builtin that
+     * keeps OTHER addons' markers in its own store (device-manager holds each
+     * driver's) must not ask the keychain for values it may not read.
+     */
+    readonly ownedBy?: string;
+}
+/** Is `ref` one of `owner`'s refs? */
+export declare function isSecretRefOwnedBy(ref: string, owner: string): boolean;
 /**
  * Replace every marker in `value` with its keychain value. Returns the SAME
  * reference when there is no marker (no allocation, no keychain call).
  */
-export declare function resolveSecretMarkers<T>(value: T, secrets: SecretsAccess): Promise<ResolvedSecrets<T>>;
+export declare function resolveSecretMarkers<T>(value: T, secrets: SecretsAccess, options?: ResolveSecretMarkersOptions): Promise<ResolvedSecrets<T>>;

package/dist/addon/secret-write-back.d.ts

@@ -0,0 +1,40 @@
+import type { SecretsAccess } from '../keychain/secrets-access.js';
+import type { SecretTree } from './secret-paths.js';
+/** An addon tried to replace a stored secret it could not read. Nothing was written. */
+export declare class SecretOverwriteRefusedError extends Error {
+    readonly ref: string;
+    readonly reason: string;
+    constructor(ref: string, reason: string);
+}
+export interface RestoreSecretsInput {
+    readonly patch: Record<string, unknown>;
+    /** The blob as stored now (markers). */
+    readonly stored: Record<string, unknown>;
+    readonly secrets: SecretsAccess;
+    /** The write is the operator's (a form, an admin API call), not the addon's own code. */
+    readonly operatorWrite: boolean;
+}
+export interface RestoreSecretsResult {
+    readonly patch: Record<string, unknown>;
+    /** Refs whose keychain value this pass changed (a `put`). */
+    readonly changedRefs: readonly string[];
+}
+/** Restore markers a write-back carries as values. See the file doc. */
+export declare function restoreUnchangedSecrets(input: RestoreSecretsInput): Promise<RestoreSecretsResult>;
+/** Structural equality over JSON-shaped values (key order does not matter). */
+export declare function isJsonEqual(a: unknown, b: unknown): boolean;
+/** The patch without the keys whose value already equals the stored one. */
+export declare function dropUnchangedKeys(patch: Record<string, unknown>, stored: Record<string, unknown>): Record<string, unknown>;
+/** The top-level keys of a blob that hold at least one of `owner`'s markers. */
+export declare function markerKeysOf(blob: Record<string, unknown>, owner: string): Set<string>;
+/**
+ * The declared secret tree, widened by every place the STORED blob holds a
+ * marker under one of `keys` — so a marker the schema no longer declares (or
+ * never declared: Wyze before b4906cec6) still gets the save path's
+ * KEEP / SET / CLEAR semantics instead of being overwritten by whatever the
+ * addon writes. Markers inside arrays are not added: a row has no id field to
+ * match by unless the schema declares one. Only `owner`'s markers count: a
+ * builtin that keeps another addon's marker (device-manager) never takes it
+ * over.
+ */
+export declare function widenTreeWithStoredMarkers(declared: SecretTree, stored: Record<string, unknown>, keys: readonly string[], owner: string): SecretTree;

package/dist/addon.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-ClNXPpWR.js");
+const require_sleep = require("./sleep-DiQYrfm9.js");
 const require_event_category = require("./event-category-CHduMGvg.js");
 const require_err_msg = require("./err-msg-Dx2Kor0g.js");
 //#region src/generated/cap-input-defaults.ts
@@ -16,7 +16,7 @@ const require_err_msg = require("./err-msg-Dx2Kor0g.js");
 * Plain data, zero Zod: a forked runner must not import the schema barrel
 * (~144MB RSS per runner — D28).
 *
-* Coverage: 24 caps, 62 methods with defaults.
+* Coverage: 24 caps, 61 methods with defaults.
 */
 var CAP_INPUT_DEFAULTS = Object.freeze({
 	"addons": { "getLogs": { "limit": 100 } },
@@ -254,10 +254,7 @@ var CAP_INPUT_DEFAULTS = Object.freeze({
 		}
 	},
 	"terminal-session": { "pullOutput": { "waitMs": 0 } },
-	"user-management": {
-		"createApiKey": { "isAdmin": false },
-		"createUser": { "isAdmin": false }
-	},
+	"user-management": { "createUser": { "isAdmin": false } },
 	"vector-store": {
 		"declareIndex": { "metric": "cosine" },
 		"scan": { "cursor": 0 }
@@ -337,7 +334,7 @@ function materialise(defaults) {
 * barrel (`ALL_CAPABILITY_DEFINITIONS`), which would cost ~144MB RSS per
 * forked runner. See docs/decisions/adr-0028.md.
 *
-* Coverage: 25 collection caps, 41 array methods.
+* Coverage: 26 collection caps, 43 array methods.
 */
 var COLLECTION_ARRAY_METHODS = Object.freeze({
 	"addon-pages-source": ["listPages"],
@@ -375,6 +372,7 @@ var COLLECTION_ARRAY_METHODS = Object.freeze({
 	"recording": ["listSources"],
 	"storage-occupancy": ["getOccupancy"],
 	"storage-provider": ["list"],
+	"training-provider": ["describe", "listJobs"],
 	"turn-provider": ["getTurnServers"],
 	"user-passkeys": ["listPasskeys"],
 	"videoclips": ["listClips", "listSources"]

package/dist/addon.mjs

@@ -1,4 +1,4 @@
-import { $t as normalizeSecretOwner, A as adminUiCapability, At as PEER_BYTES_MAX_OUTSTANDING, C as deviceOpsCapability, Ct as clearKnownSecrets, Dt as scrubKnownSecrets, Et as registerKnownSecret, I as expandCapMethods, It as DisposerChain, Jt as arrayItemFieldPath, K as ReadinessRegistry, Lt as BaseAddon, Mt as PEER_BYTES_TICKET_TTL_MS, O as describeCustomActions, Ot as shortSecretRefHash, Pt as DATAPLANE_SECRET_HEADER, Qt as isSecretRef, Rt as normalizeAddonInitResult, St as MIN_SCRUBBED_LENGTH, T as DEVICE_CHILDREN_BATCH_MAX, Tt as knownSecretCount, U as nodePin, W as readNodePin, X as scopeKey, Xt as formatSecretScope, Yt as buildSecretRef, Zt as globalSecretScope, _n as isSecretMarkerLike, a as asJsonObject, b as collectZodSecretPaths, bt as REVALIDATE_AFTER_MS, d as BOOT_RECOVERY_BACKOFF_MS, en as parseSecretRef, f as DEVICE_SCOPED_CAPS, fn as SECRET_CLEAR, gn as isSecretMarker, h as createEventBusSliceSource, hn as isSecretFieldView, in as emitReadiness, jt as PEER_BYTES_STALL_MS, kt as PEER_BYTES_CHUNK_BYTES, m as createDeviceProxy, mn as isSecretClear, p as isDeviceScopedCap, pn as classifySecretWrite, q as ReadinessTimeoutError, qt as SECRET_REF_SCHEME, s as asString, t as sleep, u as parseJsonUnknown, vn as makeSecretMarker, w as viewerUiCapability, wt as forgetKnownSecret, x as isZodSecret, xt as createSecretsAccess, yn as toSecretFieldView, yt as resolveSecretViewsIn } from "./sleep-DujUvOcb.mjs";
+import { $t as normalizeSecretOwner, A as adminUiCapability, At as PEER_BYTES_MAX_OUTSTANDING, C as deviceOpsCapability, Ct as clearKnownSecrets, Dt as scrubKnownSecrets, Et as registerKnownSecret, I as expandCapMethods, It as DisposerChain, Jt as arrayItemFieldPath, K as ReadinessRegistry, Lt as BaseAddon, Mt as PEER_BYTES_TICKET_TTL_MS, O as describeCustomActions, Ot as shortSecretRefHash, Pt as DATAPLANE_SECRET_HEADER, Qt as isSecretRef, Rt as normalizeAddonInitResult, St as MIN_SCRUBBED_LENGTH, T as DEVICE_CHILDREN_BATCH_MAX, Tt as knownSecretCount, U as nodePin, W as readNodePin, X as scopeKey, Xt as formatSecretScope, Yt as buildSecretRef, Zt as globalSecretScope, _n as isSecretMarkerLike, a as asJsonObject, b as collectZodSecretPaths, bt as REVALIDATE_AFTER_MS, d as BOOT_RECOVERY_BACKOFF_MS, en as parseSecretRef, f as DEVICE_SCOPED_CAPS, fn as SECRET_CLEAR, gn as isSecretMarker, h as createEventBusSliceSource, hn as isSecretFieldView, in as emitReadiness, jt as PEER_BYTES_STALL_MS, kt as PEER_BYTES_CHUNK_BYTES, m as createDeviceProxy, mn as isSecretClear, p as isDeviceScopedCap, pn as classifySecretWrite, q as ReadinessTimeoutError, qt as SECRET_REF_SCHEME, s as asString, t as sleep, u as parseJsonUnknown, vn as makeSecretMarker, w as viewerUiCapability, wt as forgetKnownSecret, x as isZodSecret, xt as createSecretsAccess, yn as toSecretFieldView, yt as resolveSecretViewsIn } from "./sleep-r3RWkGVx.mjs";
 import { t as EventCategory } from "./event-category-DaIZi00R.mjs";
 import { a as DeviceType, t as errMsg } from "./err-msg-DX6i_MY4.mjs";
 //#region src/generated/cap-input-defaults.ts
@@ -15,7 +15,7 @@ import { a as DeviceType, t as errMsg } from "./err-msg-DX6i_MY4.mjs";
 * Plain data, zero Zod: a forked runner must not import the schema barrel
 * (~144MB RSS per runner — D28).
 *
-* Coverage: 24 caps, 62 methods with defaults.
+* Coverage: 24 caps, 61 methods with defaults.
 */
 var CAP_INPUT_DEFAULTS = Object.freeze({
 	"addons": { "getLogs": { "limit": 100 } },
@@ -253,10 +253,7 @@ var CAP_INPUT_DEFAULTS = Object.freeze({
 		}
 	},
 	"terminal-session": { "pullOutput": { "waitMs": 0 } },
-	"user-management": {
-		"createApiKey": { "isAdmin": false },
-		"createUser": { "isAdmin": false }
-	},
+	"user-management": { "createUser": { "isAdmin": false } },
 	"vector-store": {
 		"declareIndex": { "metric": "cosine" },
 		"scan": { "cursor": 0 }
@@ -336,7 +333,7 @@ function materialise(defaults) {
 * barrel (`ALL_CAPABILITY_DEFINITIONS`), which would cost ~144MB RSS per
 * forked runner. See docs/decisions/adr-0028.md.
 *
-* Coverage: 25 collection caps, 41 array methods.
+* Coverage: 26 collection caps, 43 array methods.
 */
 var COLLECTION_ARRAY_METHODS = Object.freeze({
 	"addon-pages-source": ["listPages"],
@@ -374,6 +371,7 @@ var COLLECTION_ARRAY_METHODS = Object.freeze({
 	"recording": ["listSources"],
 	"storage-occupancy": ["getOccupancy"],
 	"storage-provider": ["list"],
+	"training-provider": ["describe", "listJobs"],
 	"turn-provider": ["getTurnServers"],
 	"user-passkeys": ["listPasskeys"],
 	"videoclips": ["listClips", "listSources"]

package/dist/auth/app-callback.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The viewer app's custom-scheme callback — the ONE list of URLs a hub flow
+ * may hand a browser back to the native app at.
+ *
+ * Two readers, one answer: the admin-ui login page (`redirect=` for the
+ * native sign-in handoff) and the hub itself (`auth.beginExternalLink`'s
+ * `returnTo` for a native account link, D801). Both validate against this
+ * list, so a scheme added for one flow can never be accepted by one side and
+ * refused by the other.
+ *
+ * `camstack` is the production app; `camstack.dev` the dev client
+ * (`APP_VARIANT=development`). Exact match after canonicalisation — no
+ * query or fragment riders, no http(s).
+ */
+export declare const APP_AUTH_CALLBACK_URLS: readonly string[];
+/** Longest raw callback value considered at all. */
+export declare const APP_AUTH_CALLBACK_MAX_LENGTH = 512;
+/**
+ * The variants the OS / linking layer produces for the same callback:
+ * `scheme:///auth-callback` (expo-linking's empty-host standalone form — three
+ * slashes) and a trailing `/` both mean `scheme://auth-callback`. Nothing else
+ * is normalised: riders keep failing the exact match.
+ */
+export declare function canonicalizeAppCallback(raw: string): string;
+/** The canonical allowlisted callback `raw` names, or `null`. */
+export declare function parseAppAuthCallback(raw: string | null | undefined): string | null;
+/** True for a URL with a scheme (`camstack://…`, `https://…`) — not a hub-relative path. */
+export declare function hasUrlScheme(url: string): boolean;

package/dist/auth/sso-state.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The cookie that binds an SSO sign-in to the browser that started it.
+ *
+ * An IdP `/start` sets it to a random value and keeps only its SHA-256 in the
+ * server-side pending state; the login bridge carries that hash. The hub's
+ * `/api/auth/sso/finish` swaps a bridge for a session only when the request
+ * presents the cookie whose hash the bridge names — so a bridge copied out of
+ * a URL (history, a proxy log, a screenshot) is useless in any other browser.
+ * The finish clears the cookie, and records the bridge's `jti` so the same
+ * bridge never finishes twice.
+ *
+ * One name, two readers (the OIDC addon that sets it, the hub that checks it).
+ */
+export declare const SSO_STATE_COOKIE = "camstack_sso_state";
+/** Seconds the state cookie lives — the pending IdP state lasts 5 minutes, the bridge 5 more. */
+export declare const SSO_STATE_COOKIE_MAX_AGE_SEC = 600;

package/dist/capabilities/addon-routes.cap.d.ts

@@ -50,6 +50,9 @@ export declare const addonRoutesCapability: {
                 authenticated: "authenticated";
             }>>;
             description: z.ZodOptional<z.ZodString>;
+            rateLimit: z.ZodOptional<z.ZodEnum<{
+                auth: "auth";
+            }>>;
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
         /**
          * Cross-process dispatch entry point. Forked addons implement this

package/dist/capabilities/addons.cap.d.ts

@@ -139,8 +139,8 @@ declare const AddonAutoUpdateSchema: z.ZodEnum<{
  *    copy when the node registers again (only once the hub no longer has it).
  */
 declare const UninstallNodeOutcomeSchema: z.ZodEnum<{
-    failed: "failed";
     refused: "refused";
+    failed: "failed";
     uninstalled: "uninstalled";
     "not-installed": "not-installed";
     "pending-reconnect": "pending-reconnect";
@@ -148,8 +148,8 @@ declare const UninstallNodeOutcomeSchema: z.ZodEnum<{
 declare const UninstallNodeResultSchema: z.ZodObject<{
     nodeId: z.ZodString;
     outcome: z.ZodEnum<{
-        failed: "failed";
         refused: "refused";
+        failed: "failed";
         uninstalled: "uninstalled";
         "not-installed": "not-installed";
         "pending-reconnect": "pending-reconnect";
@@ -165,8 +165,8 @@ declare const UninstallPackageResultSchema: z.ZodObject<{
     results: z.ZodReadonly<z.ZodArray<z.ZodObject<{
         nodeId: z.ZodString;
         outcome: z.ZodEnum<{
-            failed: "failed";
             refused: "refused";
+            failed: "failed";
             uninstalled: "uninstalled";
             "not-installed": "not-installed";
             "pending-reconnect": "pending-reconnect";
@@ -427,8 +427,8 @@ export declare const addonsCapability: {
             results: z.ZodReadonly<z.ZodArray<z.ZodObject<{
                 nodeId: z.ZodString;
                 outcome: z.ZodEnum<{
-                    failed: "failed";
                     refused: "refused";
+                    failed: "failed";
                     uninstalled: "uninstalled";
                     "not-installed": "not-installed";
                     "pending-reconnect": "pending-reconnect";

package/dist/capabilities/backup.cap.d.ts

@@ -57,6 +57,34 @@ declare const BackupDestinationInfoSchema: z.ZodObject<{
     lastAttemptAt: z.ZodOptional<z.ZodNumber>;
     lastError: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * How an archive is encrypted (operator decision 2026-10-09): to a backup
+ * PUBLIC key the hub holds, so only the operator's secret key opens it.
+ * Absent on a plain `.tar.gz` — every archive made before encryption, or
+ * with it off — which restores without a key.
+ */
+declare const BackupArchiveEncryptionSchema: z.ZodObject<{
+    scheme: z.ZodString;
+    keyId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The backup encryption setting. The hub keeps PUBLIC keys only: the active
+ * one new archives are encrypted to, and the retired ones older archives
+ * still need. The secret key is shown once, at `setupEncryption`.
+ */
+declare const BackupEncryptionStatusSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    active: z.ZodNullable<z.ZodObject<{
+        keyId: z.ZodString;
+        publicKey: z.ZodString;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>>;
+    keys: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        keyId: z.ZodString;
+        createdAt: z.ZodNumber;
+        retiredAt: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 /**
  * Per-archive entry returned by `backup.listArchives({ destinationId })`.
  * Same shape the destination drill-in renders. Sourced from the per-
@@ -69,6 +97,10 @@ declare const BackupArchiveEntrySchema: z.ZodObject<{
     sizeBytes: z.ZodNumber;
     label: z.ZodOptional<z.ZodString>;
     locations: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    encryption: z.ZodOptional<z.ZodObject<{
+        scheme: z.ZodString;
+        keyId: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const BackupEntrySchema: z.ZodObject<{
     id: z.ZodString;
@@ -77,6 +109,10 @@ declare const BackupEntrySchema: z.ZodObject<{
     createdAt: z.ZodNumber;
     sizeBytes: z.ZodNumber;
     locations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    encryption: z.ZodOptional<z.ZodObject<{
+        scheme: z.ZodString;
+        keyId: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const ArchiveEntrySchema: z.ZodObject<{
     path: z.ZodString;
@@ -200,6 +236,10 @@ declare const BackupTriggerResultSchema: z.ZodObject<{
         createdAt: z.ZodNumber;
         sizeBytes: z.ZodNumber;
         locations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        encryption: z.ZodOptional<z.ZodObject<{
+            scheme: z.ZodString;
+            keyId: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 /**
@@ -293,6 +333,10 @@ export declare const backupCapability: {
                 createdAt: z.ZodNumber;
                 sizeBytes: z.ZodNumber;
                 locations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                encryption: z.ZodOptional<z.ZodObject<{
+                    scheme: z.ZodString;
+                    keyId: z.ZodString;
+                }, z.core.$strip>>;
             }, z.core.$strip>>>;
         }, z.core.$strip>, "mutation">;
         /**
@@ -354,6 +398,10 @@ export declare const backupCapability: {
             createdAt: z.ZodNumber;
             sizeBytes: z.ZodNumber;
             locations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            encryption: z.ZodOptional<z.ZodObject<{
+                scheme: z.ZodString;
+                keyId: z.ZodString;
+            }, z.core.$strip>>;
         }, z.core.$strip>>>, import("./capability-definition.js").CapabilityMethodKind>;
         /**
          * Pre-backup snapshot of the well-known locations on disk — sizes
@@ -413,7 +461,53 @@ export declare const backupCapability: {
             destinationId: z.ZodString;
             backupId: z.ZodString;
             locations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            backupSecretKey: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** The encryption setting — public keys only. */
+        readonly getEncryption: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodObject<{
+            enabled: z.ZodBoolean;
+            active: z.ZodNullable<z.ZodObject<{
+                keyId: z.ZodString;
+                publicKey: z.ZodString;
+                createdAt: z.ZodNumber;
+            }, z.core.$strip>>;
+            keys: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                keyId: z.ZodString;
+                createdAt: z.ZodNumber;
+                retiredAt: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Turn encryption on, or replace the key: generates a new key pair, keeps
+         * the PUBLIC key, and returns the SECRET key — once. It is never stored
+         * on the hub and cannot be shown again; archives made from now on need
+         * it to be restored. A previous key is retired: archives made with it
+         * still need IT.
+         */
+        readonly setupEncryption: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+            keyId: z.ZodString;
+            secretKey: z.ZodString;
+            publicKey: z.ZodString;
+            createdAt: z.ZodNumber;
+            replacedKeyId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, "mutation">;
+        /** New archives are plain again. Existing encrypted archives keep needing their key. */
+        readonly disableEncryption: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+            disabledKeyId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, "mutation">;
+        /**
+         * Does this secret key parse, and which backup key is it? A mutation so
+         * the key never travels in a URL. Nothing is stored.
+         */
+        readonly checkBackupKey: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            backupSecretKey: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            valid: z.ZodBoolean;
+            keyId: z.ZodNullable<z.ZodString>;
+            known: z.ZodBoolean;
+            active: z.ZodBoolean;
+            error: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, "mutation">;
         readonly delete: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             destinationId: z.ZodString;
             backupId: z.ZodString;
@@ -432,6 +526,10 @@ export declare const backupCapability: {
             sizeBytes: z.ZodNumber;
             label: z.ZodOptional<z.ZodString>;
             locations: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+            encryption: z.ZodOptional<z.ZodObject<{
+                scheme: z.ZodString;
+                keyId: z.ZodString;
+            }, z.core.$strip>>;
         }, z.core.$strip>>>, import("./capability-definition.js").CapabilityMethodKind>;
         /**
          * Upsert a per-destination policy row. The `locationId` MUST be
@@ -510,7 +608,9 @@ export declare const backupCapability: {
     };
 };
 export type IBackupProvider = InferProvider<typeof backupCapability>;
-export { ArchiveEntrySchema, ArchiveManifestSchema, BackupArchiveEntrySchema, BackupDestinationInfoSchema, BackupEntrySchema, BackupRunPhaseSchema, BackupRunSchema, BackupRunStateSchema, BackupScheduleSchema, BackupSubDestinationInfoSchema, BackupTriggerResultSchema, LocationStatSchema, };
+export { ArchiveEntrySchema, ArchiveManifestSchema, BackupArchiveEncryptionSchema, BackupArchiveEntrySchema, BackupEncryptionStatusSchema, BackupDestinationInfoSchema, BackupEntrySchema, BackupRunPhaseSchema, BackupRunSchema, BackupRunStateSchema, BackupScheduleSchema, BackupSubDestinationInfoSchema, BackupTriggerResultSchema, LocationStatSchema, };
+export type BackupArchiveEncryption = z.infer<typeof BackupArchiveEncryptionSchema>;
+export type BackupEncryptionStatus = z.infer<typeof BackupEncryptionStatusSchema>;
 export type BackupRunState = z.infer<typeof BackupRunStateSchema>;
 export type BackupRunPhase = z.infer<typeof BackupRunPhaseSchema>;
 export type BackupRun = z.infer<typeof BackupRunSchema>;

package/dist/capabilities/broker.cap.d.ts

@@ -47,8 +47,8 @@ import { type InferProvider } from './capability-definition.js';
  */
 export declare const BrokerStatusEnum: z.ZodEnum<{
     error: "error";
-    connecting: "connecting";
     unreachable: "unreachable";
+    connecting: "connecting";
     connected: "connected";
     disconnected: "disconnected";
     "auth-failed": "auth-failed";
@@ -61,8 +61,8 @@ declare const BrokerInfoSchema: z.ZodObject<{
     kind: z.ZodString;
     status: z.ZodEnum<{
         error: "error";
-        connecting: "connecting";
         unreachable: "unreachable";
+        connecting: "connecting";
         connected: "connected";
         disconnected: "disconnected";
         "auth-failed": "auth-failed";
@@ -162,8 +162,8 @@ export declare const brokerCapability: {
             kind: z.ZodString;
             status: z.ZodEnum<{
                 error: "error";
-                connecting: "connecting";
                 unreachable: "unreachable";
+                connecting: "connecting";
                 connected: "connected";
                 disconnected: "disconnected";
                 "auth-failed": "auth-failed";
@@ -181,8 +181,8 @@ export declare const brokerCapability: {
             kind: z.ZodString;
             status: z.ZodEnum<{
                 error: "error";
-                connecting: "connecting";
                 unreachable: "unreachable";
+                connecting: "connecting";
                 connected: "connected";
                 disconnected: "disconnected";
                 "auth-failed": "auth-failed";