sealkeep 0.8.1 → 0.11.0

package/dist/src/darwin-service-policy.d.ts

@@ -0,0 +1,41 @@
+type PolicyExec = (file: string, args: string[]) => Promise<unknown>;
+export type DarwinServicePolicyOptions = {
+    /** True only for the daemon child of Sealkeep's package-independent manager. */
+    serviceOwned: boolean;
+    /** Dependency seams keep non-Darwin and live-process tests hermetic. */
+    platform?: NodeJS.Platform;
+    pid?: number;
+    exec?: PolicyExec;
+};
+export type LegacyDarwinManagerHandoffOptions = {
+    serviceOwned: boolean;
+    platform?: NodeJS.Platform;
+    environment?: NodeJS.ProcessEnv;
+    /** Rewrites the exact already-owned manager, receipt, and native unit. */
+    reconcile: () => Promise<boolean>;
+};
+/**
+ * Prepare the one upgrade generation still launched by a pre-policy manager.
+ *
+ * Returning true means durable reconciliation completed and the caller must
+ * exit 75 before acquiring a UI or worker lease. The old manager already
+ * propagates that non-zero child result, so launchd starts the newly written
+ * manager, whose generation marker makes this gate a one-shot operation.
+ */
+export declare function prepareLegacyDarwinManagerHandoff(options: LegacyDarwinManagerHandoffOptions): Promise<boolean>;
+/**
+ * Remove the legacy launchd `ProcessType=Background` runtime policy from the
+ * already-running daemon without restarting it.
+ *
+ * Older plist generations marked the whole service as background even though
+ * that process also owns the user-facing loopback UI. Reconciliation writes
+ * the corrected plist for future launches, but launchd does not apply a plist
+ * edit to a process it already started. `taskpolicy -B` changes only Darwin's
+ * PRIO_DARWIN_BG flag for this exact process; it does not change the separate
+ * Nice=5 or LowPriorityIO settings which keep archive work deferential.
+ *
+ * This is deliberately best-effort. A missing or restricted taskpolicy must
+ * never prevent memory preservation or the recovery/settings UI from opening.
+ */
+export declare function normalizeDarwinServicePolicy(options: DarwinServicePolicyOptions): Promise<boolean>;
+export {};

package/dist/src/darwin-service-policy.js

@@ -0,0 +1,60 @@
+import { execFile } from "node:child_process";
+import { platform } from "node:os";
+import { promisify } from "node:util";
+import { INTEGRATION_MANAGER_GENERATION, INTEGRATION_MANAGER_GENERATION_ENV, } from "./integration-manager.js";
+const run = promisify(execFile);
+/**
+ * Prepare the one upgrade generation still launched by a pre-policy manager.
+ *
+ * Returning true means durable reconciliation completed and the caller must
+ * exit 75 before acquiring a UI or worker lease. The old manager already
+ * propagates that non-zero child result, so launchd starts the newly written
+ * manager, whose generation marker makes this gate a one-shot operation.
+ */
+export async function prepareLegacyDarwinManagerHandoff(options) {
+    const environment = options.environment ?? process.env;
+    if (!options.serviceOwned
+        || (options.platform ?? platform()) !== "darwin"
+        || environment[INTEGRATION_MANAGER_GENERATION_ENV] === INTEGRATION_MANAGER_GENERATION)
+        return false;
+    try {
+        return await options.reconcile();
+    }
+    catch {
+        // The runtime normalization below is still a safe fallback. Never turn a
+        // service-definition inspection failure into an unavailable local UI.
+        return false;
+    }
+}
+/**
+ * Remove the legacy launchd `ProcessType=Background` runtime policy from the
+ * already-running daemon without restarting it.
+ *
+ * Older plist generations marked the whole service as background even though
+ * that process also owns the user-facing loopback UI. Reconciliation writes
+ * the corrected plist for future launches, but launchd does not apply a plist
+ * edit to a process it already started. `taskpolicy -B` changes only Darwin's
+ * PRIO_DARWIN_BG flag for this exact process; it does not change the separate
+ * Nice=5 or LowPriorityIO settings which keep archive work deferential.
+ *
+ * This is deliberately best-effort. A missing or restricted taskpolicy must
+ * never prevent memory preservation or the recovery/settings UI from opening.
+ */
+export async function normalizeDarwinServicePolicy(options) {
+    if (!options.serviceOwned || (options.platform ?? platform()) !== "darwin")
+        return false;
+    const pid = options.pid ?? process.pid;
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    const exec = options.exec ?? ((file, args) => run(file, args, {
+        timeout: 2_000,
+        killSignal: "SIGTERM",
+    }));
+    try {
+        await exec("/usr/sbin/taskpolicy", ["-B", "-p", String(pid)]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/dashboard-cli.js

@@ -1,21 +1,21 @@
 #!/usr/bin/env node
-// `npm run dashboard` is a thin alias for the local API, which serves the dashboard
-// from the same origin. Keeping one server means one authentication path and no
-// second copy of the business logic.
+// `npm run dashboard` is a thin alias for the singleton local UI. Keeping one
+// owner per vault means the development shortcut cannot create a second process
+// that races the installed service's upload/reclaim journals.
 import { defaultDataDir } from "./vault.js";
-import { createLocalApiServer, localApiToken, localApiTokenPath } from "./local-api.js";
-import { freePort } from "./net.js";
+import { localApiTokenPath } from "./local-api.js";
 import { envVar } from "./env.js";
+import { startUi } from "./ui-server.js";
 const dataDir = envVar("DATA_DIR") ?? defaultDataDir();
 async function listen() {
-    const token = await localApiToken(dataDir);
-    const server = createLocalApiServer(dataDir, token);
-    const port = await freePort(Number(process.env.PORT ?? "4173"));
-    server.once("error", (error) => { console.error(`Unable to start dashboard on port ${port}: ${error.message}`); process.exitCode = 1; });
-    server.listen(port, "127.0.0.1", () => {
-        // The token travels in the URL fragment, which the browser never sends to a server.
-        console.log(`Sealkeep dashboard: http://127.0.0.1:${port}/#token=${token}`);
-        console.log(`Token file (do not share): ${localApiTokenPath(dataDir)}`);
-    });
+    const requestedPort = Number(process.env.PORT ?? "4173");
+    const ui = await startUi(dataDir, { port: requestedPort, openBrowser: false, owner: "interactive" });
+    console.log(`Sealkeep dashboard: ${ui.url}`);
+    console.log(`Token file (do not share): ${localApiTokenPath(dataDir)}`);
+    if (ui.reused)
+        console.log("Using the Sealkeep local UI that already owns this vault.");
 }
-void listen();
+void listen().catch((error) => {
+    console.error(`Unable to start dashboard: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+});

package/dist/src/device-authorization.d.ts

@@ -0,0 +1,37 @@
+import { type CloudAccount, type CloudDeviceAuthorizationMemory } from "./cloud.js";
+import { type DeviceEnrollmentDraft } from "./device-enrollment.js";
+import { type BackendName } from "./secrets.js";
+export type DeviceOsFamily = "macos" | "linux" | "windows";
+export type DeviceAuthorizationStart = {
+    requestId: string;
+    approvalUrl: string;
+    expiresAt: string;
+    pollAfterMs: number;
+    status: "waiting_for_approval";
+};
+/** The browser needs a comparison code and timing, never even the target's public key. */
+type PublicEnrollment = Pick<DeviceEnrollmentDraft, "requestId" | "label" | "verificationCode" | "createdAt" | "expiresAt"> & {
+    status: "waiting_for_approval";
+};
+export type DeviceAuthorizationCompletion = {
+    status: "waiting_for_approval" | "denied" | "expired" | "complete";
+    expiresAt?: string;
+    retryAfterMs?: number;
+    account?: {
+        plan: CloudAccount["plan"];
+        email: string;
+        quotaBytes: number;
+        usedBytes: number;
+    };
+    memory?: CloudDeviceAuthorizationMemory;
+    enrollment?: PublicEnrollment;
+};
+export declare function currentOsFamily(value?: NodeJS.Platform): DeviceOsFamily;
+export declare function publicDetectedAgents(values: readonly string[]): string[];
+export declare function beginDeviceAuthorization(dataDir: string, input: {
+    label: string;
+    osFamily?: DeviceOsFamily;
+    agents?: string[];
+}, preferred?: BackendName): Promise<DeviceAuthorizationStart>;
+export declare function completeDeviceAuthorization(dataDir: string, requestId: string, preferred?: BackendName): Promise<DeviceAuthorizationCompletion>;
+export {};

package/dist/src/device-authorization.js

@@ -0,0 +1,199 @@
+import { createHash, randomBytes } from "node:crypto";
+import { platform } from "node:os";
+import { resolve } from "node:path";
+import { claimCloudDeviceAuthorization, cloudUrl, rememberCloudDeviceAuthorization, startCloudDeviceAuthorization, } from "./cloud.js";
+import { generateDeviceEnrollmentKeys, rememberHostedDeviceEnrollment, } from "./device-enrollment.js";
+import { fail } from "./errors.js";
+import { chooseBackend } from "./secrets.js";
+const STATE_SERVICE = "sealkeep-device-authorization";
+const REQUEST_ID = /^[A-Za-z0-9._~-]{1,200}$/;
+const SAFE_AGENT_IDS = new Set(["codex", "claude", "cursor", "gemini", "windsurf", "antigravity"]);
+function publicEnrollment(draft) {
+    return {
+        requestId: draft.requestId,
+        label: draft.label,
+        verificationCode: draft.verificationCode,
+        createdAt: draft.createdAt,
+        expiresAt: draft.expiresAt,
+        status: "waiting_for_approval",
+    };
+}
+export function currentOsFamily(value = platform()) {
+    if (value === "darwin")
+        return "macos";
+    if (value === "win32")
+        return "windows";
+    return "linux";
+}
+export function publicDetectedAgents(values) {
+    return [...new Set(values.filter((value) => SAFE_AGENT_IDS.has(value)))].sort();
+}
+function stateRef(dataDir) {
+    const scope = createHash("sha256").update(resolve(dataDir)).digest("hex");
+    return { service: STATE_SERVICE, account: `${scope}@${cloudUrl()}` };
+}
+const s256 = (verifier) => createHash("sha256").update(verifier).digest("base64url");
+function normalPoll(value) {
+    const number = Number(value);
+    return Number.isFinite(number) ? Math.min(10_000, Math.max(1_000, Math.round(number))) : 3_000;
+}
+function assertApprovalUrl(value) {
+    if (typeof value !== "string")
+        return fail("internal", "Sealkeep Cloud did not return an account approval page");
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return fail("internal", "Sealkeep Cloud returned an invalid account approval page");
+    }
+    if (url.protocol !== "https:" || url.username || url.password) {
+        return fail("internal", "Sealkeep Cloud returned an unsafe account approval page");
+    }
+    // The opaque request id may identify the browser approval, but credentials,
+    // verifier material and one-time codes never belong in a browser URL.
+    if (/(?:token|secret|verifier|machine_key|account_token|pairing_code)=/i.test(`${url.search}&${url.hash}`)) {
+        return fail("internal", "Sealkeep Cloud put secret material in the account approval URL");
+    }
+    return url.toString();
+}
+async function rememberDraft(dataDir, draft, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    await backend.set(stateRef(dataDir), JSON.stringify(draft));
+}
+async function readDraft(dataDir, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    const raw = await backend.get(stateRef(dataDir));
+    if (!raw)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        if (value.version !== 1 || typeof value.requestId !== "string" || !REQUEST_ID.test(value.requestId))
+            return null;
+        if (typeof value.verifier !== "string" || value.verifier.length < 32)
+            return null;
+        if (!value.keys || typeof value.keys.publicKey !== "string" || typeof value.keys.privateKey !== "string")
+            return null;
+        if (typeof value.label !== "string" || !value.label.trim())
+            return null;
+        if (typeof value.expiresAt !== "string" || !Number.isFinite(Date.parse(value.expiresAt)))
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+async function forgetDraft(dataDir, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    await backend.delete(stateRef(dataDir)).catch(() => undefined);
+}
+export async function beginDeviceAuthorization(dataDir, input, preferred) {
+    const label = input.label.trim();
+    if (!label || label.length > 80)
+        fail("invalid_argument", "Name this machine with 1 to 80 characters");
+    const verifier = randomBytes(32).toString("base64url");
+    const keys = generateDeviceEnrollmentKeys();
+    const created = await startCloudDeviceAuthorization({
+        challenge: s256(verifier),
+        label,
+        osFamily: input.osFamily ?? currentOsFamily(),
+        agents: publicDetectedAgents(input.agents ?? []),
+        publicKey: keys.publicKey,
+    });
+    const requestId = String(created?.request_id ?? "");
+    if (!REQUEST_ID.test(requestId))
+        fail("internal", "Sealkeep Cloud returned an invalid device authorization request");
+    const approvalUrl = assertApprovalUrl(created.approval_url);
+    const expiresAt = String(created.expires_at ?? "");
+    if (!Number.isFinite(Date.parse(expiresAt)) || Date.parse(expiresAt) <= Date.now()) {
+        fail("internal", "Sealkeep Cloud returned an expired device authorization request");
+    }
+    const draft = {
+        version: 1,
+        requestId,
+        verifier,
+        label,
+        keys,
+        createdAt: created.created_at && Number.isFinite(Date.parse(created.created_at)) ? created.created_at : new Date().toISOString(),
+        expiresAt,
+        pollAfterMs: normalPoll(created.poll_after_ms),
+    };
+    try {
+        await rememberDraft(dataDir, draft, preferred);
+    }
+    catch (error) {
+        fail("internal", `This machine could not protect its authorization request locally: ${error instanceof Error ? error.message : "secret backend refused it"}`);
+    }
+    return { requestId, approvalUrl, expiresAt, pollAfterMs: draft.pollAfterMs, status: "waiting_for_approval" };
+}
+function publicAccount(account) {
+    return {
+        plan: account.plan,
+        email: account.email,
+        quotaBytes: account.quota_bytes,
+        usedBytes: account.used_bytes,
+    };
+}
+export async function completeDeviceAuthorization(dataDir, requestId, preferred) {
+    if (!REQUEST_ID.test(requestId))
+        fail("invalid_argument", "That device authorization request is not valid");
+    const draft = await readDraft(dataDir, preferred);
+    if (!draft || draft.requestId !== requestId) {
+        fail("archive_not_found", "This machine no longer holds that account authorization request. Start a new one.");
+    }
+    if (Date.parse(draft.expiresAt) <= Date.now()) {
+        await forgetDraft(dataDir, preferred);
+        return { status: "expired", expiresAt: draft.expiresAt };
+    }
+    const claimed = await claimCloudDeviceAuthorization({ requestId, verifier: draft.verifier });
+    if (claimed.status === "pending") {
+        return {
+            status: "waiting_for_approval",
+            expiresAt: claimed.expires_at ?? draft.expiresAt,
+            retryAfterMs: normalPoll(claimed.poll_after_ms ?? draft.pollAfterMs),
+        };
+    }
+    if (claimed.status === "denied" || claimed.status === "declined" || claimed.status === "expired") {
+        await forgetDraft(dataDir, preferred);
+        return {
+            // Older hosted requests could still answer `declined`; the loopback
+            // contract intentionally has one public denial state.
+            status: claimed.status === "expired" ? "expired" : "denied",
+            expiresAt: claimed.expires_at ?? draft.expiresAt,
+        };
+    }
+    const accountToken = claimed.account_token ?? claimed.token;
+    if (claimed.status !== "approved" || typeof accountToken !== "string" || !accountToken || !claimed.machine || !claimed.account || !claimed.memory) {
+        fail("internal", "Sealkeep Cloud returned an incomplete device authorization");
+    }
+    if (!Number.isSafeInteger(claimed.machine.device_id) || claimed.machine.device_id < 1 || !claimed.machine.machine_key) {
+        fail("internal", "Sealkeep Cloud returned an invalid machine credential");
+    }
+    if (typeof claimed.memory.preserved !== "boolean" || !Number.isFinite(claimed.memory.bytes) || claimed.memory.bytes < 0) {
+        fail("internal", "Sealkeep Cloud returned an invalid preserved-memory summary");
+    }
+    await rememberCloudDeviceAuthorization(dataDir, {
+        accountToken,
+        machine: claimed.machine,
+    }, preferred);
+    let enrollment;
+    if (claimed.memory.preserved && claimed.enrollment) {
+        const started = await rememberHostedDeviceEnrollment(dataDir, {
+            requestId: claimed.enrollment.request_id,
+            requestSecret: claimed.enrollment.request_secret,
+            label: draft.label,
+            createdAt: claimed.enrollment.created_at,
+            expiresAt: claimed.enrollment.expires_at,
+            keys: draft.keys,
+        }, preferred);
+        enrollment = publicEnrollment(started);
+    }
+    await forgetDraft(dataDir, preferred);
+    return {
+        status: "complete",
+        account: publicAccount(claimed.account),
+        memory: claimed.memory,
+        ...(enrollment ? { enrollment } : {}),
+    };
+}

package/dist/src/device-enrollment.d.ts

@@ -0,0 +1,91 @@
+import { type Envelope } from "../packages/sealkeep-crypto/src/index.js";
+import { type CloudDeviceEnrollmentRequest } from "./cloud.js";
+import { type BackendName } from "./secrets.js";
+import type { VaultConfig } from "./types.js";
+export type DeviceEnrollmentDraft = {
+    version: 1;
+    requestId: number;
+    label: string;
+    publicKey: string;
+    privateKey: string;
+    requestSecret: string;
+    verificationCode: string;
+    createdAt: string;
+    expiresAt: string;
+};
+export type PersonalVaultMaterial = {
+    vaultId: string;
+    recoveryPhrase: string;
+    storageMode: "sealed" | "plain";
+    recipients?: VaultConfig["recipients"];
+    remoteNaming?: VaultConfig["remoteNaming"];
+};
+export type DeviceEnrollmentCompletion = {
+    requestId: number;
+    vaultId: string;
+    verificationCode: string;
+    cloudReceiptCleared: boolean;
+};
+/** A short comparison code derived from the key itself, never supplied by Cloud. */
+export declare function deviceEnrollmentVerificationCode(publicKey: string): string;
+export type DeviceEnrollmentKeyPair = {
+    publicKey: string;
+    privateKey: string;
+};
+export declare function generateDeviceEnrollmentKeys(): DeviceEnrollmentKeyPair;
+export declare function readDeviceEnrollmentDraft(dataDir: string, requestId: number, preferred?: BackendName): Promise<DeviceEnrollmentDraft | null>;
+/**
+ * Starts the target side after ordinary Cloud sign-in. The request secret is a
+ * capability for claiming this one response; it is not a vault key and cannot
+ * decrypt any archive.
+ */
+export declare function beginDeviceEnrollment(dataDir: string, label: string, preferred?: BackendName): Promise<Omit<DeviceEnrollmentDraft, "privateKey" | "requestSecret">>;
+/**
+ * Starts the existing-vault approval lane with a key pair prepared before
+ * hosted account authorization. Reusing that exact public key means the
+ * account page and the existing device approve the same target, instead of
+ * silently changing identity between the two steps.
+ */
+export declare function beginDeviceEnrollmentWithKeys(dataDir: string, label: string, keys: DeviceEnrollmentKeyPair, preferred?: BackendName): Promise<Omit<DeviceEnrollmentDraft, "privateKey" | "requestSecret">>;
+/**
+ * Persists a request the hosted approval endpoint already created from the
+ * public key supplied at authorization start. The returned request secret is
+ * consumed only here, over the verifier-protected claim response, and then
+ * remains in the native secret backend with the private key.
+ */
+export declare function rememberHostedDeviceEnrollment(dataDir: string, input: {
+    requestId: number;
+    requestSecret: string;
+    label: string;
+    createdAt: string;
+    expiresAt: string;
+    keys: DeviceEnrollmentKeyPair;
+}, preferred?: BackendName): Promise<Omit<DeviceEnrollmentDraft, "privateKey" | "requestSecret">>;
+export declare function sealDeviceEnrollmentPayload(config: VaultConfig, phrase: string, targetPublicKey: string): {
+    envelope: Envelope;
+    sealed: string;
+};
+/**
+ * Existing-device side. Requiring the independently displayed code prevents a
+ * Cloud-side public-key substitution from being approved silently.
+ */
+export declare function approveDeviceEnrollment(dataDir: string, requestId: number, displayedCode: string, preferred?: BackendName): Promise<{
+    approved: true;
+    requestId: number;
+    label: string;
+}>;
+/**
+ * Read-only adoption gate. Recovery codes call this before atomically spending
+ * a code, so an occupied data directory or a lost Cloud login cannot burn a
+ * valid code and then fail locally.
+ */
+export declare function assertPersonalVaultAdoptable(dataDir: string, payload: PersonalVaultMaterial, preferred?: BackendName): Promise<void>;
+/**
+ * Checks everything a fresh recovery target can check before a one-time code
+ * is redeemed. This deliberately does not need the encrypted vault payload.
+ */
+export declare function assertFreshPersonalVaultTarget(dataDir: string, preferred?: BackendName): Promise<VaultConfig | null>;
+export declare function adoptPersonalVaultMaterial(dataDir: string, payload: PersonalVaultMaterial, preferred?: BackendName): Promise<void>;
+/** Target side: claim ciphertext, decrypt locally, adopt, then acknowledge. */
+export declare function completeDeviceEnrollment(dataDir: string, requestId: number, preferred?: BackendName): Promise<DeviceEnrollmentCompletion>;
+export type { CloudDeviceEnrollmentRequest };