@camstack/system 1.2.375 → 1.2.377

package/dist/builtins/keychain/key-sources.d.ts

@@ -0,0 +1,37 @@
+import { KeychainKeySource } from '@camstack/types';
+/** The `keychain` section of `config.yaml`. */
+export interface KeychainKeyConfig {
+    readonly keyFile?: string | undefined;
+    readonly previousKeyFile?: string | undefined;
+}
+export type KeyLoadResult = {
+    readonly kind: 'loaded';
+    readonly key: Buffer;
+} | {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'unreadable';
+    readonly error: string;
+};
+export interface KeySourceCandidate {
+    readonly source: KeychainKeySource;
+    readonly primary: boolean;
+    load(): Promise<KeyLoadResult>;
+}
+/** The default key file's location under the data root. */
+export declare function defaultKeyFilePath(dataDir: string): string;
+export interface KeySourceOptions {
+    readonly config: KeychainKeyConfig;
+    readonly dataDir: string;
+}
+/** Every candidate, primary first. */
+export declare function buildKeySourceCandidates(opts: KeySourceOptions): readonly KeySourceCandidate[];
+/**
+ * Write a master key to the default location: directory 0700, file 0600,
+ * atomically (temp + rename), never over an existing file unless `replace`.
+ * Returns the previous file's new name when one was moved aside.
+ */
+export declare function writeDefaultKeyFile(dataDir: string, key: Buffer, opts: {
+    readonly replace: boolean;
+    readonly nowMs: number;
+}): Promise<string | null>;

package/dist/builtins/keychain/keychain-crypto.d.ts

@@ -0,0 +1,28 @@
+export declare const KEY_BYTES = 32;
+/** 32 fresh random bytes — a master or a data key. */
+export declare function generateKey(): Buffer;
+/** A short random id for a data key (no dots — it is a segment of `ck1`). */
+export declare function generateKeyId(): string;
+/** The full fingerprint of a master key. */
+export declare function kekFingerprint(kek: Buffer): string;
+/** What the operator sees: the first 16 hex chars. */
+export declare function shortFingerprint(fingerprint: string): string;
+/** Constant-time string equality (lengths may differ). */
+export declare function constantTimeEquals(a: string, b: string): boolean;
+/**
+ * Key material from a key file: base64 (the format we write) or hex of
+ * exactly 32 bytes, surrounding whitespace ignored. Anything else is `null` —
+ * a file holding a password or a PEM is refused, never stretched into a key.
+ */
+export declare function decodeKeyMaterial(text: string): Buffer | null;
+export declare function encodeKeyMaterial(key: Buffer): string;
+/** Wrap a data key under a master key. */
+export declare function wrapDek(kek: Buffer, dek: Buffer, keyId: string): string;
+/** Unwrap; `null` when the master key is not the one that wrapped it. */
+export declare function unwrapDek(kek: Buffer, wrapped: string, keyId: string): Buffer | null;
+/** Encrypt one value for one ref. */
+export declare function encryptValue(dek: Buffer, keyId: string, ref: string, value: string): string;
+/** The data-key id an envelope was written under, or `null` if it is not one. */
+export declare function envelopeKeyId(envelope: string): string | null;
+/** Decrypt; `null` on any failure — wrong key, wrong ref, tampered bytes. */
+export declare function decryptValue(dek: Buffer, ref: string, envelope: string): string | null;

package/dist/builtins/keychain/keychain-service.d.ts

@@ -0,0 +1,103 @@
+import { EventCategory, KeychainAuditEntry, KeychainKeySource, KeychainResolveResult, KeychainSecretMeta, KeychainSecretUsage, KeychainState, KeychainStatus, KeychainUnavailableReason } from '@camstack/types';
+import { KeychainRepository, KeychainSecretRow } from './keychain-store.js';
+import { KeySourceCandidate } from './key-sources.js';
+/** `lastReadAt` is written at most this often per ref (hub I/O is the bottleneck). */
+export declare const LAST_READ_GRANULARITY_MS: number;
+export declare class KeychainLockedError extends Error {
+    readonly reason: KeychainUnavailableReason;
+    constructor(reason: KeychainUnavailableReason);
+}
+export declare class KeychainForbiddenError extends Error {
+    readonly ref: string;
+    constructor(ref: string, caller: string | null);
+}
+export interface KeychainEventSink {
+    emit(payload: {
+        readonly ref: string;
+        readonly owner: string;
+        readonly version: number | null;
+        readonly change: 'put' | 'delete';
+    }): void;
+}
+export interface KeychainLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/** Answers whether a stored ref is still pointed at by its owner's settings. */
+export type KeychainUsageCheck = (rows: readonly KeychainSecretRow[]) => Promise<ReadonlyMap<string, KeychainSecretUsage>>;
+export interface KeychainServiceDeps {
+    readonly repo: KeychainRepository;
+    /** Rebuilt on every unlock / rotation — the configuration may have changed. */
+    readonly candidates: () => Promise<readonly KeySourceCandidate[]>;
+    readonly dataDir: string;
+    readonly events: KeychainEventSink;
+    readonly logger: KeychainLogger;
+    /** The runner id hosting an addon (its group, or itself). */
+    readonly runnerIdOf: (addonId: string) => string;
+    readonly usage: KeychainUsageCheck;
+    readonly now?: () => number;
+}
+export declare class KeychainService {
+    private readonly deps;
+    private unlock;
+    private configuredSource;
+    private readonly now;
+    constructor(deps: KeychainServiceDeps);
+    /** Load the keys and unlock. Never throws for a key problem — it locks. */
+    init(): Promise<KeychainState>;
+    private computeUnlock;
+    /** No wrapped data key yet: create one — only when nothing could be lost. */
+    private firstBoot;
+    getState(): KeychainState;
+    private requireReady;
+    /** May `caller` touch values owned by `owner`? */
+    owns(caller: string | null, owner: string): boolean;
+    private ownerOf;
+    put(caller: string | null, ref: string, value: string): Promise<{
+        ref: string;
+        version: number;
+    }>;
+    resolve(caller: string | null, refs: readonly string[]): Promise<KeychainResolveResult>;
+    private touchLastRead;
+    delete(caller: string | null, refs: readonly string[]): Promise<number>;
+    listMeta(caller: string | null): Promise<readonly KeychainSecretMeta[]>;
+    status(): Promise<KeychainStatus>;
+    listSecrets(): Promise<readonly (KeychainSecretMeta & {
+        usage: KeychainSecretUsage;
+    })[]>;
+    listAudit(limit: number): Promise<readonly KeychainAuditEntry[]>;
+    reveal(userId: string, ref: string): Promise<{
+        value: string;
+        version: number;
+    }>;
+    deleteOrphans(userId: string, refs: readonly string[]): Promise<{
+        deleted: readonly string[];
+        kept: readonly {
+            ref: string;
+            usage: KeychainSecretUsage;
+        }[];
+    }>;
+    downloadRecoveryKey(userId: string): Promise<{
+        key: string;
+        fingerprint: string;
+        keySource: KeychainKeySource;
+    }>;
+    /** See `keychain-admin.rotateMasterKey`. */
+    rotateMasterKey(userId: string): Promise<{
+        fingerprint: string;
+        keySource: KeychainKeySource;
+    }>;
+    /** Delete retired wraps, and the default file's previous copies with them. */
+    purgeRetiredKeys(userId: string): Promise<number>;
+    /** Lost-key recovery — see `keychain-admin.resetKeychain`. */
+    resetKeychain(userId: string): Promise<{
+        archivedCollection: string | null;
+        archived: number;
+    }>;
+    private audit;
+    /** Daily ring prune, driven by the addon's timer. */
+    pruneAudit(): Promise<void>;
+}
+/** The event the provider emits — exported for the addon's bus adapter. */
+export declare const KEYCHAIN_CHANGED = EventCategory.KeychainChanged;

package/dist/builtins/keychain/keychain-store.d.ts

@@ -0,0 +1,82 @@
+import { ISettingsStoreProvider, KeychainAuditAction } from '@camstack/types';
+/**
+ * @durable class=config owner=keychain
+ *   write="`keychain.put` upserts one row per ref; `delete` removes it"
+ *   retention="none — a row lives until its owner deletes the ref or the
+ *     operator deletes it as an orphan. Losing the table loses every secret
+ *     value; the settings blobs then point at refs that resolve `missing`."
+ */
+export declare const KEYCHAIN_SECRETS_COLLECTION = "keychain:secrets";
+/**
+ * @durable class=config owner=keychain
+ *   write="first boot writes the wrapped data key; `rotateMasterKey` adds a
+ *     wrap and retires the previous one"
+ *   retention="retired wraps until `purgeRetiredKeys`. Losing the table with
+ *     the secrets intact makes every value undecryptable."
+ */
+export declare const KEYCHAIN_KEYS_COLLECTION = "keychain:keys";
+/**
+ * @durable class=ring owner=keychain
+ *   write="one row per write / delete / rotation / reveal / recovery download"
+ *   retention="90 days and at most 20 000 rows, pruned at boot and daily"
+ */
+export declare const KEYCHAIN_AUDIT_COLLECTION = "keychain:audit";
+export declare const AUDIT_RETENTION_MS: number;
+export declare const AUDIT_MAX_ROWS = 20000;
+export interface KeychainSecretRow {
+    readonly ref: string;
+    readonly owner: string;
+    readonly scope: string;
+    readonly fieldPath: string;
+    readonly ciphertext: string;
+    readonly keyId: string;
+    readonly version: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly updatedBy: string;
+    readonly lastReadAt: number | null;
+}
+export type KeyWrapState = 'active' | 'retired';
+export interface KeychainKeyRow {
+    readonly wrapId: string;
+    readonly keyId: string;
+    readonly wrappedDek: string;
+    readonly kekFingerprint: string;
+    readonly kekSource: string;
+    readonly createdAt: number;
+    readonly state: KeyWrapState;
+    readonly recoveryDownloadedAt: number | null;
+}
+export interface KeychainAuditRow {
+    readonly id: string;
+    readonly at: number;
+    readonly action: KeychainAuditAction;
+    readonly actor: string;
+    readonly ref: string | null;
+    readonly detail: string | null;
+}
+/** The subset of the settings door the repository uses. */
+export type KeychainDoor = Pick<ISettingsStoreProvider, 'declareCollection' | 'get' | 'set' | 'query' | 'delete' | 'deleteWhere'>;
+export declare class KeychainRepository {
+    private readonly door;
+    constructor(door: KeychainDoor);
+    init(): Promise<void>;
+    getSecrets(refs: readonly string[]): Promise<ReadonlyMap<string, KeychainSecretRow>>;
+    /** Every row, paged by primary key. */
+    listSecrets(): Promise<readonly KeychainSecretRow[]>;
+    putSecret(row: KeychainSecretRow): Promise<void>;
+    deleteSecrets(refs: readonly string[]): Promise<number>;
+    listKeys(): Promise<readonly KeychainKeyRow[]>;
+    putKey(row: KeychainKeyRow): Promise<void>;
+    deleteKey(wrapId: string): Promise<void>;
+    appendAudit(row: KeychainAuditRow): Promise<void>;
+    listAudit(limit: number): Promise<readonly KeychainAuditRow[]>;
+    /** Drop audit rows older than the retention window, then beyond the row bound. */
+    pruneAudit(nowMs: number): Promise<number>;
+    /**
+     * Lost-key recovery: copy every secret row into `archive`, then empty the
+     * live table. The archive is ciphertext under a key nobody has — it exists
+     * so a key that turns up later can still recover it.
+     */
+    archiveAllSecrets(archive: string): Promise<number>;
+}

package/dist/builtins/keychain/keychain-usage.d.ts

@@ -0,0 +1,6 @@
+import { KeychainSecretUsage } from '@camstack/types';
+import { KeychainDoor, KeychainSecretRow } from './keychain-store.js';
+/** Every `$secret` ref inside a value, at any depth. */
+export declare function collectMarkerRefs(value: unknown, out?: Set<string>): Set<string>;
+/** Build the usage check the service uses. */
+export declare function createKeychainUsageCheck(door: KeychainDoor): (rows: readonly KeychainSecretRow[]) => Promise<ReadonlyMap<string, KeychainSecretUsage>>;

package/dist/builtins/keychain/keychain.addon.d.ts

@@ -0,0 +1,11 @@
+import { BaseAddon, ProviderRegistration } from '@camstack/types';
+/** The caller the transport stamped (or an in-process caller stated). */
+export declare function callerOf(input: unknown): string | null;
+export declare class KeychainAddon extends BaseAddon {
+    readonly id = "keychain";
+    private pruneTimer;
+    constructor();
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
+}
+export default KeychainAddon;

package/dist/builtins/keychain/platform-key-source.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The OS-keychain master key of a DESKTOP hub.
+ *
+ * Electron's `safeStorage` exists only in the Electron main process, and the
+ * hub runs as a plain Node child of it. So the desktop app reads (or creates)
+ * the master key through `safeStorage`, and hands the raw bytes to the hub
+ * over an inherited pipe (`--keychain-key-fd=<n>`) — never an env var, never a
+ * file at rest in the clear. The hub's boot reads the descriptor once and
+ * registers the key here; the keychain builtin, in the same process, asks.
+ *
+ * Process-global through a registered symbol, so a second copy of this module
+ * (an addon bundle) sees the same key rather than none.
+ */
+export interface PlatformKeychainKey {
+    /** Where it came from, for the status page (`macOS Keychain`, `Windows DPAPI`, …). */
+    readonly label: string;
+    readonly key: Buffer;
+}
+/** Register the platform key. Called once, by the hub's boot. */
+export declare function setPlatformKeychainKey(entry: PlatformKeychainKey): void;
+/** Drop the platform key (tests). */
+export declare function clearPlatformKeychainKey(): void;
+/** The platform key, when this hub was started by the desktop app with one. */
+export declare function getPlatformKeychainKey(): PlatformKeychainKey | null;

package/dist/builtins/liveness-monitor/liveness-monitor.addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CNbnikIh.js");
+const require_dist = require("../../dist-D_a9mUiM.js");
 //#region src/builtins/liveness-monitor/liveness-checks.ts
 var NO_DEVICES = "liveness:no-devices";
 var ALL_OFFLINE = "liveness:all-devices-offline";

package/dist/builtins/liveness-monitor/liveness-monitor.addon.mjs

@@ -1,4 +1,4 @@
-import { I as RecordingStatusSchema, N as RECORDING_SOURCE_CAMSTACK_ADDON, Nr as EventCategory, cr as BaseAddon, sr as errMsg, vr as createEvent } from "../../dist-ZdSg09GJ.mjs";
+import { F as RecordingStatusSchema, Gr as EventCategory, N as RECORDING_SOURCE_CAMSTACK_ADDON, Sr as createEvent, cr as errMsg, lr as BaseAddon } from "../../dist-BWNoS-1S.mjs";
 //#region src/builtins/liveness-monitor/liveness-checks.ts
 var NO_DEVICES = "liveness:no-devices";
 var ALL_OFFLINE = "liveness:all-devices-offline";

package/dist/builtins/local-auth/auth-schema.d.ts

@@ -60,6 +60,20 @@ export declare const OAUTH_SESSIONS_COLLECTION = "oauth_sessions";
  *     enrollment row outlives the account."
  */
 export declare const USER_TOTP_COLLECTION = "user_totp";
+/**
+ * External sign-in identities linked to local users (D782): one row per
+ * `(provider, subject)` — the row id IS the identity, so one identity maps to
+ * one user by primary key. Written only by the identity's owner completing a
+ * "Link" flow from their profile (bound to their session).
+ *
+ * @durable class=config owner=local-auth
+ *   write="`ExternalIdentityManager.link` when a signed-in user completes a
+ *     link flow; `unlink` from the profile or the Users page"
+ *   retention="`unlink` deletes one row; deleting the user deletes all of its
+ *     rows (`deleteUser` → `removeAllForUser`). A row whose provider instance
+ *     was renamed or removed stays, inert, until someone unlinks it."
+ */
+export declare const USER_EXTERNAL_IDENTITIES_COLLECTION = "user_external_identities";
 /**
  * Declare every auth collection with the typed schema. Called by
  * `LocalAuthAddon.onInitialize` before constructing the per-collection

package/dist/builtins/local-auth/local-auth.addon.d.ts

@@ -12,6 +12,7 @@ export declare class LocalAuthAddon extends BaseAddon<LocalAuthConfig> {
     private oauthSessionManager;
     private reapTimer;
     private totpManager;
+    private externalIdentities;
     constructor();
     protected onInitialize(): Promise<ProviderRegistration[]>;
     /**