@camstack/types 1.2.327 → 1.2.328

package/dist/interfaces/addon.d.ts

@@ -4,6 +4,7 @@ import type { CustomActionCaller, CustomActionsSpec } from '../capabilities/cust
 import type { PipelineSlot } from '../types/pipeline.js';
 import type { AddonDataPlane } from './addon-data-plane.js';
 import type { AddonPeerBytes } from './addon-peer-bytes.js';
+import type { SecretsAccess } from '../keychain/secrets-access.js';
 import type { CapabilityDeclaration } from './capability.js';
 import type { ConfigUISchemaWithValues, FieldProbeResult } from './config-ui.js';
 import type { IEventBus, ReadinessScope } from './event-bus.js';
@@ -202,6 +203,14 @@ export interface IKernelServices {
      * dispatch from remote dispatch without a direct Moleculer dependency.
      */
     readonly localNodeId?: string;
+    /**
+     * The runner id hosting an addon — its `execution.group`, else itself
+     * (`resolveRunnerId`). Hub in-process contexts only: the keychain uses it to
+     * accept a grouped runner's transport stamp (the group id) for the refs of
+     * the addons that runner hosts. Absent elsewhere; callers fall back to
+     * identity.
+     */
+    readonly runnerIdForAddon?: (addonId: string) => string;
     /**
      * Local storage provider — direct filesystem access with zero serialization.
      * Use for file I/O (write/read with Buffer data) that can't go through tRPC.
@@ -695,6 +704,17 @@ export interface AddonContext<TConfig = Record<string, unknown>> {
      * (tests, tooling), which is why the field is optional.
      */
     readonly peerBytes?: AddonPeerBytes;
+    /**
+     * This addon's keychain values (D787). The owner is the addon's own id,
+     * closed over by the kernel; nothing passed to it can change that.
+     * `BaseAddon` uses it for every secret field of its schema (a marker in the
+     * blob, the value here) — reach for it directly only for values that are
+     * not settings (a business collection's credentials, a minted token).
+     *
+     * Absent when the addon is loaded in isolation (tests, tooling) or on a
+     * kernel that predates the keychain.
+     */
+    readonly secrets?: SecretsAccess;
     /**
      * Runtime accessor for the capability registry — exposed to addons that
      * need to enumerate peers of a collection cap (e.g. `turn-provider`) or
@@ -829,6 +849,11 @@ export interface ICamstackAddon {
      *  persisted store. */
     getGlobalSettings?(overlay?: Record<string, unknown>, cap?: string, nodeId?: string): Promise<ConfigUISchemaWithValues | null>;
     updateGlobalSettings?(patch: Record<string, unknown>, nodeId?: string): Promise<void>;
+    /**
+     * The same write, made by the OPERATOR (D787): the kernel's settings
+     * dispatch prefers it when the addon has it.
+     */
+    updateGlobalSettingsAsOperator?(patch: Record<string, unknown>, nodeId?: string): Promise<void>;
     /**
      * Integration-level settings — the subset of the global schema the addon
      * declared as its INTEGRATION's configuration (`BaseAddon.

package/dist/interfaces/config-ui-secrets.d.ts

@@ -35,11 +35,23 @@ import type { ConfigField } from './config-ui.js';
 export declare const REDACTED_SECRET = "__camstack_redacted__";
 /** Is this field's stored value a credential? */
 export declare function isSecretConfigField(field: ConfigField): boolean;
+/**
+ * Is this field's value stored in the KEYCHAIN (D787)? Every secret field is,
+ * by its TYPE, unless it opts out with `storage: 'inline'` — never by its name.
+ */
+export declare function isKeychainStoredField(field: ConfigField): boolean;
 /**
  * Every config key in `schema` whose value is a secret, including keys nested
  * inside `group` / `sub-tabs` containers.
  */
 export declare function collectSecretConfigKeys(schema: unknown): ReadonlySet<string>;
+/**
+ * Every top-level config key whose value the KEYCHAIN stores (D787) —
+ * {@link collectSecretConfigKeys} minus `storage: 'inline'` and minus JSON
+ * blobs (see {@link isKeychainStoredField}). What a form sends as
+ * `secretKeys` so the owner's door knows which values to keep out of the blob.
+ */
+export declare function collectKeychainStoredKeys(schema: unknown): ReadonlySet<string>;
 /**
  * True when the value is a readable schema declaring at least one field of any
  * kind. Lets a caller tell "this provider has no secrets" from "this provider's

package/dist/interfaces/config-ui.d.ts

@@ -148,6 +148,15 @@ export interface ConfigFieldBase {
      * non-admin session. It costs nothing when the field is already a password.
      */
     readonly secret?: boolean;
+    /**
+     * Where a SECRET field's value is stored (D787). Default for every field
+     * {@link isSecretConfigField} selects (`type: 'password'` or `secret: true`):
+     * `'keychain'` — the settings blob holds a `{"$secret": ref}` marker and the
+     * value lives in the encrypted keychain; the form sees "set / not set",
+     * never the value. `'inline'` opts out, for a NON-secret value that is merely
+     * drawn masked. Decided by the field's TYPE and this flag — never its name.
+     */
+    readonly storage?: 'keychain' | 'inline';
     /** Per-model knob applicability — see {@link ConfigFieldModelApplicability}. */
     readonly modelApplicability?: ConfigFieldModelApplicability;
     /**
@@ -745,6 +754,14 @@ export interface ConfigEditableArrayField extends ConfigFieldBase {
      * collapse to an em-dash. Falls back to `Row N` when not provided.
      */
     readonly rowTitleTemplate?: string;
+    /**
+     * The row field that IDENTIFIES a row (default `'id'`). A secret inside a row
+     * is stored under a ref addressed by this id — never by index — so a reorder
+     * keeps every ref, a removed row's refs are deleted, and a duplicated row's
+     * secret is "not set" rather than copied (D787). A row saved without one has
+     * an id minted for it.
+     */
+    readonly itemIdKey?: string;
 }
 export interface ConfigModelSelectorField extends ConfigFieldBase {
     type: 'model-selector';
@@ -1096,4 +1113,15 @@ export declare function resolveHydratedFieldValue(schema: unknown, key: string):
  * the schema default or `null`. This mirrors the old backend behaviour where
  * `FormBuilder` rendered `values[key] ?? field.default`.
  */
-export declare function hydrateSchema(schema: ConfigUISchema, values: Record<string, unknown>): ConfigUISchemaWithValues;
+/** How `hydrateSchema` treats keychain-stored secret fields (D789). */
+export interface HydrateSchemaOptions {
+    /**
+     * `true` — the form is the addon's OWN settings form, saved through the
+     * keychain-aware `BaseAddon` path: a pre-keychain inline value is shown as
+     * "set" too, never as text. Omitted — only a keychain MARKER becomes a view;
+     * an inline value hydrates as before, because forms saved through other
+     * paths (a camera driver's settings) need the value they were given.
+     */
+    readonly inlineSecretsAsViews?: boolean;
+}
+export declare function hydrateSchema(schema: ConfigUISchema, values: Record<string, unknown>, options?: HydrateSchemaOptions): ConfigUISchemaWithValues;

package/dist/interfaces/event-bus.d.ts

@@ -743,6 +743,16 @@ export interface TopologyNode {
  */
 export type StreamHealthReason = 'stale-timeout' | 'recovered' | 'first-packet' | 'suspended' | 'resumed' | 'broker-destroyed';
 /** All known event categories with their typed payloads */
+/**
+ * `keychain.changed` — a value was put or deleted. Never carries the value.
+ */
+export type KeychainChangedPayload = {
+    readonly ref: string;
+    readonly owner: string;
+    /** The version now stored; `null` after a delete. */
+    readonly version: number | null;
+    readonly change: 'put' | 'delete';
+};
 export interface EventCatalog {
     'system.boot': {
         mode: string;
@@ -753,6 +763,7 @@ export interface EventCatalog {
     'system.restarting': PendingRestartMarkerPayload;
     'system.restart-completed': PendingRestartMarkerPayload;
     'system.tls-cert-changed': TlsCertChangedPayload;
+    'keychain.changed': KeychainChangedPayload;
     'update.available': {
         /**
          * `addon` and `server` are npm packages a node can install for itself.

package/dist/interfaces/pipeline-runner-capability.d.ts

@@ -305,4 +305,22 @@ export interface IPipelineRunnerProvider {
     }): Promise<{
         released: number;
     }>;
+    /**
+     * Node benchmark measurement on THIS node (D791). See
+     * `pipelineRunnerCapability.startNodeBench` for the contract.
+     */
+    startNodeBench(input: import('../pipeline/node-benchmark/schemas.js').NodeBenchRunnerInputRaw): Promise<{
+        accepted: true;
+        runId: string;
+    }>;
+    /** The run's status; `null` when this runner does not know `runId`. */
+    getNodeBenchStatus(input: {
+        readonly runId: string;
+    }): Promise<import('../pipeline/node-benchmark/schemas.js').NodeBenchRunnerStatus | null>;
+    /** Stop the run; what it finished is kept. */
+    abortNodeBench(input: {
+        readonly runId: string;
+    }): Promise<{
+        aborted: boolean;
+    }>;
 }

package/dist/keychain/index.d.ts

@@ -0,0 +1,5 @@
+export { clearKnownSecrets, forgetKnownSecret, knownSecretCount, MIN_SCRUBBED_LENGTH, registerKnownSecret, scrubKnownSecrets, shortSecretRefHash, } from './known-secrets.js';
+export { classifySecretWrite, isSecretClear, isSecretFieldView, isSecretMarker, isSecretMarkerLike, makeSecretMarker, SECRET_CLEAR, type SecretClearInstruction, type SecretFieldView, type SecretMarker, type SecretWriteIntent, toSecretFieldView, } from './secret-marker.js';
+export { arrayItemFieldPath, buildSecretRef, formatSecretScope, globalSecretScope, isSecretRef, normalizeSecretOwner, parseSecretRef, SECRET_REF_SCHEME, type SecretRefParts, type SecretScope, } from './secret-ref.js';
+export { createSecretsAccess, type KeychainTransport, REVALIDATE_AFTER_MS, type SecretsAccess, type SecretsAccessOptions, } from './secrets-access.js';
+export { resolveSecretViewsIn } from './resolve-secret-views.js';

package/dist/keychain/known-secrets.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The per-process set of secret VALUES this process has resolved, so the log
+ * pipeline can scrub them wherever they turn up — a library's error message,
+ * an argv a spawn logged, a URL someone interpolated.
+ *
+ * Key-name redaction cannot catch `Command failed: cloudflared --token eyJ…`:
+ * the value is in a message, not under a named key. The only thing that can is
+ * knowing the value. `ctx.secrets` registers every value it resolves (and every
+ * value it stores), and `scrubKnownSecrets` replaces each occurrence with
+ * `‹secret:<hash of its ref>›` — enough to say WHICH secret leaked, nothing of
+ * what it is.
+ *
+ * Process-global on purpose: a forked runner scrubs its own logs before they
+ * leave over UDS, and hub-main scrubs what it resolved. Values shorter than
+ * {@link MIN_SCRUBBED_LENGTH} are not registered — a 4-digit PIN would turn
+ * every timestamp containing it into a redaction.
+ */
+/** Below this length a value is too likely to collide with ordinary text. */
+export declare const MIN_SCRUBBED_LENGTH = 8;
+/** FNV-1a, 32-bit, as 8 hex chars — a label, not a security property. */
+export declare function shortSecretRefHash(ref: string): string;
+/** Remember a value this process holds. A no-op for short or empty values. */
+export declare function registerKnownSecret(value: string, ref: string): void;
+/** Forget a value (it was replaced or deleted). */
+export declare function forgetKnownSecret(value: string): void;
+/** How many values are registered — for tests and the status page. */
+export declare function knownSecretCount(): number;
+/** Test seam: drop every registered value. */
+export declare function clearKnownSecrets(): void;
+/** Replace every registered value inside `text` with its label. */
+export declare function scrubKnownSecrets(text: string): string;

package/dist/keychain/resolve-secret-views.d.ts

@@ -0,0 +1,2 @@
+import type { SecretsAccess } from './secrets-access.js';
+export declare function resolveSecretViewsIn(args: unknown, secrets: SecretsAccess | undefined): Promise<unknown>;

package/dist/keychain/secret-marker.d.ts

@@ -0,0 +1,52 @@
+/** The marker a settings blob stores in place of a secret value. */
+export interface SecretMarker {
+    readonly $secret: string;
+    readonly v: 1;
+}
+/**
+ * What a read surface hands the UI for a secret field that holds something.
+ * `$secret` is `null` when the stored value predates the keychain (it is still
+ * plaintext in the blob until the operator's one-off migration moves it): the
+ * UI draws "set" either way and the value never leaves the hub.
+ */
+export interface SecretFieldView {
+    readonly $secret: string | null;
+    readonly v: 1;
+    readonly set: true;
+    /** The stored value is still inline plaintext (pre-keychain). */
+    readonly inline?: true;
+}
+/** The explicit "remove this secret" instruction a form sends. */
+export interface SecretClearInstruction {
+    readonly $secretClear: true;
+}
+export declare const SECRET_CLEAR: SecretClearInstruction;
+export declare function makeSecretMarker(ref: string): SecretMarker;
+/** A stored marker: an object whose `$secret` is a non-empty string. */
+export declare function isSecretMarker(value: unknown): value is SecretMarker;
+/** Anything carrying a `$secret` key — a stored marker or a UI view of one. */
+export declare function isSecretMarkerLike(value: unknown): boolean;
+export declare function isSecretClear(value: unknown): value is SecretClearInstruction;
+export declare function isSecretFieldView(value: unknown): value is SecretFieldView;
+/**
+ * The UI view of a stored secret field value: a marker becomes "set", inline
+ * plaintext becomes "set (inline)", nothing becomes `null`. A value never
+ * survives this function.
+ */
+export declare function toSecretFieldView(stored: unknown): SecretFieldView | null;
+/** How an incoming value for a secret path is to be treated. */
+export type SecretWriteIntent = {
+    readonly kind: 'keep';
+} | {
+    readonly kind: 'clear';
+} | {
+    readonly kind: 'set';
+    readonly value: string;
+};
+/**
+ * Classify an incoming value for a secret path. Only a non-empty string that is
+ * not a redaction token sets a value; only {@link SECRET_CLEAR} clears.
+ * Everything else — a marker (ours or anyone's), a UI view, `''`, `null`,
+ * `undefined`, a redaction token, a non-string — keeps what is stored.
+ */
+export declare function classifySecretWrite(incoming: unknown): SecretWriteIntent;

package/dist/keychain/secret-ref.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The address of one keychain value: `secret://<owner>/<scope>/<fieldPath>`.
+ *
+ * A ref is DETERMINISTIC from where the value lives — the owner addon, the
+ * scope (global, one node, one device, one integration, one row of a business
+ * collection) and the field path inside that scope — so saving the same field
+ * twice updates the same ref, and the ref itself says which settings blob
+ * points at it. It is also the AAD of the value's ciphertext: a ciphertext
+ * copied onto another ref does not decrypt.
+ *
+ * Array items are addressed by ITEM ID, never by index
+ * (`providers[authentik].clientSecret`), so reordering a list keeps every ref.
+ *
+ * Pure and browser-safe: no node builtins, no I/O.
+ */
+/** The URI scheme of every keychain ref. */
+export declare const SECRET_REF_SCHEME = "secret://";
+/** Where, inside its owner, a secret lives. */
+export type SecretScope = {
+    readonly kind: 'global';
+} | {
+    readonly kind: 'node';
+    readonly nodeId: string;
+} | {
+    readonly kind: 'device';
+    readonly deviceId: number;
+} | {
+    readonly kind: 'integration';
+    readonly integrationId: string;
+} | {
+    readonly kind: 'row';
+    readonly collection: string;
+    readonly rowId: string;
+};
+/** A ref, taken apart. */
+export interface SecretRefParts {
+    readonly owner: string;
+    readonly scope: SecretScope;
+    readonly fieldPath: string;
+}
+/** The scope every addon-wide (not per-node, not per-device) setting lives in. */
+export declare function globalSecretScope(): SecretScope;
+/**
+ * An addon id as a ref owner. A hub in-process builtin's context id is
+ * `addon:<id>`; the owner of its secrets is `<id>`, exactly as for the same
+ * addon running forked.
+ */
+export declare function normalizeSecretOwner(addonId: string): string;
+/** The scope as it appears inside a ref (`global`, `node/<id>`, …). */
+export declare function formatSecretScope(scope: SecretScope): string;
+/**
+ * The field path of a value inside an array item, addressed by the item's id:
+ * `arrayItemFieldPath('providers', 'authentik', 'clientSecret')` →
+ * `providers[authentik].clientSecret`.
+ */
+export declare function arrayItemFieldPath(arrayKey: string, itemId: string, fieldKey: string): string;
+/** Build a ref. Throws on an empty owner or field path — both are bugs. */
+export declare function buildSecretRef(parts: SecretRefParts): string;
+/** True when `value` is shaped like a keychain ref (not that it exists). */
+export declare function isSecretRef(value: unknown): value is string;
+/** Take a ref apart; `null` when it is not a well-formed ref. */
+export declare function parseSecretRef(ref: string): SecretRefParts | null;

package/dist/keychain/secrets-access.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `ctx.secrets` — an addon's handle on its OWN keychain values.
+ *
+ * The owner is closed over at construction (the addon's id); nothing a caller
+ * passes can change it. How the call travels is the transport's business:
+ *
+ *  - hub in-process builtin: the provider is in the same process, so the
+ *    transport states the owner explicitly (`callerAddonId`) — the one place a
+ *    claim is trusted, because no wire is involved;
+ *  - forked runner / agent addon: the transport sends the bare input and the
+ *    parent (or the agent, through `$hub-cap-fwd`) stamps who is calling.
+ *
+ * The cache holds `ref → {value, version}` with no expiry while the version is
+ * current. `keychain.changed` drops an entry; an entry older than
+ * {@link REVALIDATE_AFTER_MS} is re-fetched on its next use (the safety net
+ * for a dropped event, D8). A failed fetch answers the last good value when
+ * there is one — a locked keychain never turns a working credential into an
+ * empty one — and `unavailable` otherwise, never `missing`.
+ */
+import type { KeychainResolveResult, KeychainState } from '../capabilities/keychain.cap.js';
+import type { IEventBus } from '../interfaces/event-bus.js';
+import { type SecretScope } from './secret-ref.js';
+/** Re-fetch a cached value after this long, even with no change event. */
+export declare const REVALIDATE_AFTER_MS: number;
+/** The four calls a {@link SecretsAccess} makes. `callerAddonId` is set only in-process. */
+export interface KeychainTransport {
+    put(input: {
+        readonly ref: string;
+        readonly value: string;
+    }): Promise<{
+        readonly ref: string;
+        readonly version: number;
+    }>;
+    resolve(input: {
+        readonly refs: readonly string[];
+    }): Promise<KeychainResolveResult>;
+    delete(input: {
+        readonly refs: readonly string[];
+    }): Promise<{
+        readonly deleted: number;
+    }>;
+    getState(): Promise<KeychainState>;
+}
+export interface SecretsAccess {
+    /** The owner every ref of this handle belongs to. */
+    readonly owner: string;
+    /** Build this owner's ref for a field. */
+    ref(scope: SecretScope, fieldPath: string): string;
+    /** Resolve refs in one call; cached values are served without one. */
+    resolve(refs: readonly string[]): Promise<KeychainResolveResult>;
+    /** Store a value. Throws while the keychain is locked. */
+    put(ref: string, value: string): Promise<number>;
+    /** Remove refs. Unknown refs are ignored. */
+    delete(refs: readonly string[]): Promise<number>;
+    /** Whether values can be stored right now. */
+    state(): Promise<KeychainState>;
+    /**
+     * Subscribe to changes of refs this handle has served. The handler runs
+     * after the cache dropped the ref. Returns the unsubscribe.
+     */
+    onChange(handler: (ref: string) => void): () => void;
+    /**
+     * In-process SYSTEM builtins only (device-manager, storage-orchestrator):
+     * act as a door for another owner's values. `null` everywhere else — a
+     * forked addon has no way to state an identity the transport would accept.
+     */
+    readonly forOwner: ((owner: string) => SecretsAccess) | null;
+}
+export interface SecretsAccessOptions {
+    readonly owner: string;
+    readonly transport: KeychainTransport;
+    /** Builds the transport for another owner — in-process system builtins only. */
+    readonly transportForOwner?: (owner: string) => KeychainTransport;
+    readonly eventBus?: Pick<IEventBus, 'subscribe'>;
+    readonly now?: () => number;
+}
+export declare function createSecretsAccess(opts: SecretsAccessOptions): SecretsAccess;

package/dist/logging/log-channel.d.ts

@@ -56,8 +56,8 @@ import type { IScopedLogger, LogExtras } from '../interfaces/logging.js';
  * to read it later.
  */
 export declare const LogChannelLevelSchema: z.ZodEnum<{
-    error: "error";
     info: "info";
+    error: "error";
     warn: "warn";
 }>;
 /**
@@ -68,8 +68,8 @@ export declare const LogChannelDescriptorSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodString;
     defaultLevel: z.ZodEnum<{
-        error: "error";
         info: "info";
+        error: "error";
         warn: "warn";
     }>;
     perDevice: z.ZodBoolean;