@geohar/un-bien 0.7.0

package/dist/mesh/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Mesh-membership types — pi-extension side. Mirrors the wire shape defined
+ * in plan/24-mesh-membership.md and must stay bit-compatible with the Dart
+ * (app) and Rust (relay) implementations of the same protocol.
+ *
+ * On the wire, JSON field names are `snake_case` (per the plan); this module
+ * exposes `camelCase` for ergonomic TS use. Conversion happens at the
+ * (de)serialization boundary in `verify.ts` / `canonical.ts`.
+ */
+export interface MeshMember {
+    /** Pi Ed25519 pubkey, canonical RFC 4648 standard base64 with padding. */
+    remoteEpk: string;
+    /** Relay URL where this member registers. */
+    relayUrl: string;
+    /** ISO-8601 timestamp of when the pairing happened. */
+    pairedAt: string;
+    /** Optional Owner-set label. */
+    nickname?: string;
+}
+export interface MeshHeader {
+    /** Owner-scoped monotonic counter. Higher = newer. */
+    version: number;
+    /** Issued-at, ms since epoch. */
+    issuedAt: number;
+    /** Owner's Ed25519 pubkey, raw 32 bytes. */
+    ownerPk: Uint8Array;
+    members: MeshMember[];
+}
+export interface MeshEnvelope {
+    /** Canonical JSON bytes of the header (snake_case keys, sorted, no whitespace). */
+    blob: Uint8Array;
+    /** Ed25519 signature of `blob`, 64 bytes. */
+    sig: Uint8Array;
+}

package/dist/mesh/types.js

@@ -0,0 +1,11 @@
+/**
+ * Mesh-membership types — pi-extension side. Mirrors the wire shape defined
+ * in plan/24-mesh-membership.md and must stay bit-compatible with the Dart
+ * (app) and Rust (relay) implementations of the same protocol.
+ *
+ * On the wire, JSON field names are `snake_case` (per the plan); this module
+ * exposes `camelCase` for ergonomic TS use. Conversion happens at the
+ * (de)serialization boundary in `verify.ts` / `canonical.ts`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mesh/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mesh/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/mesh/verify.d.ts

@@ -0,0 +1,17 @@
+import type { MeshEnvelope, MeshHeader } from "./types.js";
+/**
+ * Verifies the Ed25519 signature on a mesh envelope and decodes the blob
+ * into a typed `MeshHeader`.
+ *
+ * The verification key is extracted *from the blob* (`owner_pk` field) —
+ * the caller MUST then check that `sha256(header.ownerPk)` matches the
+ * URL hash they queried with. Otherwise a malicious relay could serve a
+ * valid-but-different-owner blob at our hash slot.
+ *
+ * Throws on:
+ *   - JSON parse failure
+ *   - Missing or wrong-type required fields
+ *   - `owner_pk` not 32 bytes
+ *   - Signature mismatch
+ */
+export declare function verifyEnvelope(env: MeshEnvelope): Promise<MeshHeader>;

package/dist/mesh/verify.js

@@ -0,0 +1,86 @@
+import { ed25519Verify } from "../pairing/crypto.js";
+import { canonicalizeEd25519PublicKey, decodeEd25519PublicKey, } from "./encoding.js";
+/**
+ * Verifies the Ed25519 signature on a mesh envelope and decodes the blob
+ * into a typed `MeshHeader`.
+ *
+ * The verification key is extracted *from the blob* (`owner_pk` field) —
+ * the caller MUST then check that `sha256(header.ownerPk)` matches the
+ * URL hash they queried with. Otherwise a malicious relay could serve a
+ * valid-but-different-owner blob at our hash slot.
+ *
+ * Throws on:
+ *   - JSON parse failure
+ *   - Missing or wrong-type required fields
+ *   - `owner_pk` not 32 bytes
+ *   - Signature mismatch
+ */
+export async function verifyEnvelope(env) {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(env.blob));
+    }
+    catch {
+        throw new Error("mesh: blob is not valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("mesh: blob is not a JSON object");
+    }
+    const o = parsed;
+    if (typeof o["owner_pk"] !== "string") {
+        throw new Error("mesh: owner_pk missing or not a string");
+    }
+    if (typeof o["version"] !== "number" || !Number.isInteger(o["version"])) {
+        throw new Error("mesh: version missing or not an integer");
+    }
+    if (typeof o["issued_at"] !== "number" || !Number.isInteger(o["issued_at"])) {
+        throw new Error("mesh: issued_at missing or not an integer");
+    }
+    if (!Array.isArray(o["members"])) {
+        throw new Error("mesh: members missing or not an array");
+    }
+    const rawMembers = o["members"].map((raw, index) => {
+        if (!raw || typeof raw !== "object") {
+            throw new Error(`mesh: members[${index}] is not an object`);
+        }
+        const member = raw;
+        if (typeof member["remote_epk"] !== "string") {
+            throw new Error(`mesh: members[${index}].remote_epk invalid`);
+        }
+        if (typeof member["relay_url"] !== "string") {
+            throw new Error(`mesh: members[${index}].relay_url invalid`);
+        }
+        if (typeof member["paired_at"] !== "string") {
+            throw new Error(`mesh: members[${index}].paired_at invalid`);
+        }
+        const nickname = member["nickname"];
+        if (nickname !== undefined &&
+            nickname !== null &&
+            typeof nickname !== "string") {
+            throw new Error(`mesh: members[${index}].nickname invalid`);
+        }
+        return {
+            remoteEpk: member["remote_epk"],
+            relayUrl: member["relay_url"],
+            pairedAt: member["paired_at"],
+            ...(typeof nickname === "string" ? { nickname } : {}),
+        };
+    });
+    const ownerPk = decodeEd25519PublicKey(o["owner_pk"], "owner_pk");
+    if (!ed25519Verify(ownerPk, env.blob, env.sig)) {
+        throw new Error("mesh: signature verification failed");
+    }
+    const members = rawMembers.map((member, index) => ({
+        remoteEpk: canonicalizeEd25519PublicKey(member.remoteEpk, `members[${index}].remote_epk`),
+        relayUrl: member.relayUrl,
+        pairedAt: member.pairedAt,
+        ...(member.nickname !== undefined ? { nickname: member.nickname } : {}),
+    }));
+    return {
+        version: o["version"],
+        issuedAt: o["issued_at"],
+        ownerPk,
+        members,
+    };
+}
+//# sourceMappingURL=verify.js.map

package/dist/mesh/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/mesh/verify.ts"],"names":[],"mappings":"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"}

package/dist/pairing/crypto.d.ts

@@ -0,0 +1,8 @@
+export interface Ed25519Keypair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+/** Generates an Ed25519 keypair for relay challenge-response auth. */
+export declare function generateEd25519Keypair(): Ed25519Keypair;
+export declare function ed25519Sign(sk: Uint8Array, msg: Uint8Array): Uint8Array;
+export declare function ed25519Verify(pk: Uint8Array, msg: Uint8Array, sig: Uint8Array): boolean;

package/dist/pairing/crypto.js

@@ -0,0 +1,22 @@
+import { createHash, randomBytes } from "node:crypto";
+import * as ed from "@noble/ed25519";
+// Configure @noble/ed25519 v3 to use Node.js built-in SHA-512
+ed.hashes["sha512"] = (...msgs) => {
+    const h = createHash("sha512");
+    for (const m of msgs)
+        h.update(m);
+    return Uint8Array.from(h.digest());
+};
+/** Generates an Ed25519 keypair for relay challenge-response auth. */
+export function generateEd25519Keypair() {
+    const secretKey = randomBytes(32);
+    const publicKey = ed.getPublicKey(secretKey);
+    return { secretKey, publicKey: Buffer.from(publicKey) };
+}
+export function ed25519Sign(sk, msg) {
+    return Buffer.from(ed.sign(msg, sk));
+}
+export function ed25519Verify(pk, msg, sig) {
+    return ed.verify(sig, msg, pk);
+}
+//# sourceMappingURL=crypto.js.map

package/dist/pairing/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../src/pairing/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAErC,8DAA8D;AAC7D,EAAE,CAAC,MAAkC,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAkB,EAAE,EAAE;IAC3E,MAAM,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAClC,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACrC,CAAC,CAAC;AAOF,sEAAsE;AACtE,MAAM,UAAU,sBAAsB;IACpC,MAAM,SAAS,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;IAC7C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,EAAc,EAAE,GAAe;IACzD,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,EAAc,EACd,GAAe,EACf,GAAe;IAEf,OAAO,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC"}

package/dist/pairing/qr.d.ts

@@ -0,0 +1,59 @@
+/** Default ephemeral-token lifetime (also the QR rotation period). */
+export declare const TOKEN_TTL_MS = 60000;
+/** Bounds for a caller-supplied pairing TTL (e.g. `/unbien pair --ttl <s>`). */
+export declare const PAIR_TTL_MIN_MS = 10000;
+export declare const PAIR_TTL_MAX_MS = 600000;
+/** Clamp an arbitrary ttl (ms) into the safe pairing range; NaN → default. */
+export declare function clampPairTtlMs(ttlMs: number): number;
+/** Encapsulates the single active QR token. One instance per Pi process. */
+export declare class QRSession {
+    private active;
+    /** Generates a fresh 16-byte random token encoded as base64url. */
+    generateToken(): string;
+    /**
+     * Issues a new active token, invalidating any previous one.
+     * Returns the token and its expiry timestamp.
+     */
+    issueToken(ttlMs?: number): {
+        token: string;
+        expiresAt: number;
+    };
+    /** Validates and atomically consumes a token. */
+    consumeToken(token: string): "ok" | "expired" | "consumed" | "unknown";
+    clear(): void;
+}
+export declare const qrSession: QRSession;
+export declare function buildQRUri(token: string, longtermEdPk: Uint8Array, // Ed25519 — only peer ID after E2E rollback
+sessionName: string, 
+/**
+ * Pi room id (12 chars, base64url) derived from cwd. App routes pair_request
+ * to this room so the relay delivers it to the right Pi instance among N
+ * paralelos com mesmo epk. Adicionado no fix do plano 17 (sem `rm` o app
+ * cai em room=main e o relay drops com "dest not found").
+ */
+roomId?: string): string;
+/**
+ * Returns the QR ASCII as a string (pure Unicode block characters —
+ * `█ ▀ ▄` and space, NO ANSI escapes — qrcode-terminal v0.12 small mode
+ * is escape-free, see lib/main.js:48-53).
+ *
+ * The caller can either write the string to stderr (legacy path, breaks
+ * the Pi TUI layout) or inject it via `pi.sendMessage` (renders inside
+ * the chat panel as proper content).
+ */
+export declare function renderQRAscii(uri: string): string;
+/**
+ * Legacy stderr writer — kept for the standalone CLI mode
+ * (`pi-extension/src/index.ts` bottom block, which runs outside a Pi TUI).
+ * Inside the Pi TUI extension flow, use `renderQRAscii` + `pi.sendMessage`
+ * instead — direct stderr writes from inside an extension break the TUI's
+ * scrollable output widget (the QR overflows the panel and other writes
+ * collide with the prompt area).
+ */
+export declare function displayQR(uri: string): void;
+/**
+ * Starts a rotating QR session: generates a new QR every 60s, printing it
+ * to stdout. Returns a `stop()` function that cancels the rotation and clears
+ * the active token.
+ */
+export declare function startQRRotation(longtermEdPk: Uint8Array, sessionName: string, roomId?: string): () => void;

package/dist/pairing/qr.js

@@ -0,0 +1,127 @@
+import { randomBytes } from "node:crypto";
+import qrTerminal from "qrcode-terminal";
+/** Default ephemeral-token lifetime (also the QR rotation period). */
+export const TOKEN_TTL_MS = 60_000;
+/** Bounds for a caller-supplied pairing TTL (e.g. `/unbien pair --ttl <s>`). */
+export const PAIR_TTL_MIN_MS = 10_000;
+export const PAIR_TTL_MAX_MS = 600_000;
+/** Clamp an arbitrary ttl (ms) into the safe pairing range; NaN → default. */
+export function clampPairTtlMs(ttlMs) {
+    if (!Number.isFinite(ttlMs))
+        return TOKEN_TTL_MS;
+    return Math.min(PAIR_TTL_MAX_MS, Math.max(PAIR_TTL_MIN_MS, Math.floor(ttlMs)));
+}
+/** Encapsulates the single active QR token. One instance per Pi process. */
+export class QRSession {
+    active = null;
+    /** Generates a fresh 16-byte random token encoded as base64url. */
+    generateToken() {
+        return randomBytes(16).toString("base64url");
+    }
+    /**
+     * Issues a new active token, invalidating any previous one.
+     * Returns the token and its expiry timestamp.
+     */
+    issueToken(ttlMs = TOKEN_TTL_MS) {
+        const token = this.generateToken();
+        const expiresAt = Date.now() + ttlMs;
+        this.active = { token, expiresAt, consumed: false };
+        return { token, expiresAt };
+    }
+    /** Validates and atomically consumes a token. */
+    consumeToken(token) {
+        if (!this.active || this.active.token !== token)
+            return "unknown";
+        if (this.active.consumed)
+            return "consumed";
+        if (Date.now() > this.active.expiresAt)
+            return "expired";
+        this.active.consumed = true;
+        return "ok";
+    }
+    clear() {
+        this.active = null;
+    }
+}
+export const qrSession = new QRSession();
+// ── URI + display ─────────────────────────────────────────────────────────────
+export function buildQRUri(token, longtermEdPk, // Ed25519 — only peer ID after E2E rollback
+sessionName, 
+/**
+ * Pi room id (12 chars, base64url) derived from cwd. App routes pair_request
+ * to this room so the relay delivers it to the right Pi instance among N
+ * paralelos com mesmo epk. Adicionado no fix do plano 17 (sem `rm` o app
+ * cai em room=main e o relay drops com "dest not found").
+ */
+roomId) {
+    // `r` (relay URL) removed in plano 14 — relay now comes from app config /
+    // pi-ext env|config|default chain. Keeps QR ~30-50 chars shorter.
+    // `n` (session name) is kept: the app uses it for the pre-pair_ok preview
+    // screen (showing the agent name immediately after scan, before the
+    // handshake completes). Dropping it briefly shrank the QR but the QR
+    // size no longer matters now that the copy-paste URI is rendered via
+    // `pi.sendMessage` into the chat panel (not the QR overflow area).
+    const epkB64 = Buffer.from(longtermEdPk).toString("base64url");
+    const params = new URLSearchParams({
+        t: token,
+        epk: epkB64,
+        n: sessionName.slice(0, 80),
+    });
+    if (roomId)
+        params.set("rm", roomId);
+    return `unbien://pair?${params.toString()}`;
+}
+/**
+ * Returns the QR ASCII as a string (pure Unicode block characters —
+ * `█ ▀ ▄` and space, NO ANSI escapes — qrcode-terminal v0.12 small mode
+ * is escape-free, see lib/main.js:48-53).
+ *
+ * The caller can either write the string to stderr (legacy path, breaks
+ * the Pi TUI layout) or inject it via `pi.sendMessage` (renders inside
+ * the chat panel as proper content).
+ */
+export function renderQRAscii(uri) {
+    let out = "";
+    qrTerminal.generate(uri, { small: true }, (qrcode) => {
+        out = qrcode;
+    });
+    return out;
+}
+/**
+ * Legacy stderr writer — kept for the standalone CLI mode
+ * (`pi-extension/src/index.ts` bottom block, which runs outside a Pi TUI).
+ * Inside the Pi TUI extension flow, use `renderQRAscii` + `pi.sendMessage`
+ * instead — direct stderr writes from inside an extension break the TUI's
+ * scrollable output widget (the QR overflows the panel and other writes
+ * collide with the prompt area).
+ */
+export function displayQR(uri) {
+    const qrcode = renderQRAscii(uri);
+    process.stderr.write(`\n📱 Scan to pair:\n\n${qrcode}\n`);
+}
+/**
+ * Starts a rotating QR session: generates a new QR every 60s, printing it
+ * to stdout. Returns a `stop()` function that cancels the rotation and clears
+ * the active token.
+ */
+export function startQRRotation(longtermEdPk, sessionName, roomId) {
+    let timer = null;
+    let stopped = false;
+    const rotate = () => {
+        if (stopped)
+            return;
+        const { token, expiresAt } = qrSession.issueToken();
+        const uri = buildQRUri(token, longtermEdPk, sessionName, roomId);
+        displayQR(uri);
+        console.log(`⏱  Renews at ${new Date(expiresAt).toLocaleTimeString()} — waiting for scan…`);
+        timer = setTimeout(rotate, TOKEN_TTL_MS);
+    };
+    rotate();
+    return () => {
+        stopped = true;
+        if (timer !== null)
+            clearTimeout(timer);
+        qrSession.clear();
+    };
+}
+//# sourceMappingURL=qr.js.map

package/dist/pairing/qr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr.js","sourceRoot":"","sources":["../../src/pairing/qr.ts"],"names":[],"mappings":"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"}

package/dist/pairing/storage.d.ts

@@ -0,0 +1,120 @@
+import { type Ed25519Keypair } from "./crypto.js";
+/** Raised when the keyring is unreadable on a platform where it's a core OS
+ *  service (macOS Keychain, Windows Credential Manager) AND no prior file
+ *  identity exists. We refuse to generate a NEW identity here because that
+ *  would break existing pairing — the caller surfaces this so the user can
+ *  unlock the keychain and retry instead of silently re-pairing. */
+export declare class KeyringUnavailableError extends Error {
+    constructor(cause: unknown);
+}
+/** Raised when no identity can be resolved (keyring unreadable, no identity
+ *  file) BUT `peers.json` already lists paired devices. Minting a fresh key
+ *  here would make SelfRevoke wipe those pairings — see issues #95 / #69. */
+export declare class PairedIdentityMissingError extends Error {
+    constructor(pairedCount: number, cause: unknown);
+}
+/**
+ * Minimal backend interface for credential reads/writes. Swappable so
+ * tests can inject a controlled in-memory store without touching the OS
+ * keyring (which is shared with the developer's own credentials).
+ *
+ * Errors thrown by `read`/`write`/`delete` signal "backend unavailable on
+ * this platform" — callers fall back to the file store on first failure.
+ * Returning `undefined` from `read` means "no such entry" (a normal,
+ * non-error condition).
+ */
+export interface KeyStoreBackend {
+    read(service: string, account: string): Promise<string | undefined>;
+    write(service: string, account: string, value: string): Promise<void>;
+    delete(service: string, account: string): Promise<boolean>;
+}
+/** Test-only: force (or clear with `null`) a memoized binding-load failure, so
+ *  the Bun/no-native-binding branch is reachable without a Bun host. */
+export declare function _setNativeBindingErrorForTest(err: unknown): void;
+/** Test-only: swap (or clear with `null`) the keyring backend. */
+export declare function _setKeyStoreBackendForTest(backend: KeyStoreBackend | null): void;
+/** Test-only: force `_keyringExpectedAvailable()` (so a darwin test host can
+ *  exercise the Linux/headless branch and vice-versa). `null` restores the
+ *  real platform check. */
+export declare function _setKeyringExpectedForTest(value: boolean | null): void;
+/** Test-only: shrink retry attempts/delay so the persistent-failure path is
+ *  fast. `null`/omitted restores defaults. */
+export declare function _setKeyringRetryForTest(attempts: number | null, delayMs?: number): void;
+/**
+ * Returns the Pi-secret Ed25519 keypair, generating + persisting one on
+ * first call. Resolution order:
+ *   1. Existing file `~/.pi/un-bien/identity.json`, if present — it WINS over
+ *      the keyring. A file identity is only ever written by the headless/
+ *      degraded fallback (step 4) or an explicit `UNBIEN_ALLOW_FILE_IDENTITY`
+ *      opt-in, so its mere presence means this machine established its identity
+ *      as a file and the mobile device paired against THAT pubkey. If the
+ *      platform keyring later becomes readable (D-Bus/libsecret installed, a
+ *      desktop session, or a stale/other entry from another install), reading
+ *      it first would mask the file identity — returning a DIFFERENT key, or
+ *      (when the keyring is empty) minting a fresh one and persisting it —
+ *      silently breaking the existing pairing. So when both exist, file wins.
+ *   2. New keyring service `dev.unbien.pi` (read retried — a transiently
+ *      locked Keychain throws; we don't treat that as "no key")
+ *   3. Old keyring service `dev.unbien.mac` (migrate → step 2, delete old)
+ *   4. Generate a fresh keypair, BUT only when it's safe to: either both
+ *      keyring reads succeeded and returned nothing (genuine first run), or
+ *      the keyring is genuinely unavailable on a platform without a core one
+ *      (headless Linux → a file identity is minted here). On macOS/Windows a
+ *      persistent read failure with no file identity throws
+ *      `KeyringUnavailableError` instead of minting a new key — generating
+ *      there silently breaks existing pairing (the "lost pairing after idle"
+ *      bug). `UNBIEN_ALLOW_FILE_IDENTITY=1` opts back into a file identity
+ *      for headless macOS/Windows hosts.
+ *
+ * Idempotent: subsequent calls return the same identity. The migration
+ * runs at most once per machine (the old entry is deleted after copy).
+ */
+export declare function getOrCreateEd25519Keypair(): Promise<Ed25519Keypair>;
+export interface PeerRecord {
+    name: string;
+    remote_epk: string;
+    paired_at: string;
+}
+export declare function listPeers(): Promise<PeerRecord[]>;
+declare const _ownerStorageTokenBrand: unique symbol;
+/** Opaque, process-local provenance for one canonical Owner storage slot. */
+export type OwnerStorageToken = {
+    readonly [_ownerStorageTokenBrand]: true;
+};
+export interface OwnerStorageSnapshotRecord {
+    readonly rawOwnerPubkey: unknown;
+    readonly token: OwnerStorageToken;
+}
+export type ConditionalPeerRemoval = {
+    readonly outcome: "removed";
+    readonly nextToken: OwnerStorageToken;
+} | {
+    readonly outcome: "stale" | "not_found" | "no_authority";
+};
+export declare function addPeer(record: PeerRecord): Promise<void>;
+/**
+ * Returns the set of distinct `remote_epk` values in peers.json.
+ *
+ * In the current pairing model (plan/23 + plan/24), each `remote_epk` is the
+ * Owner's Ed25519 pubkey — and we treat each as a distinct Owner the Pi has
+ * been paired with. Used by the mesh self-revoke poller (plan/24 Wave 3) to
+ * know which Owners' mesh blobs to fetch.
+ */
+export declare function listOwnerPubkeys(): Promise<unknown[]>;
+/**
+ * Atomically snapshots raw Owner handles and their canonical-slot provenance.
+ * The token is deliberately process-local and opaque to callers.
+ */
+export declare function snapshotOwnerPubkeys(): Promise<readonly OwnerStorageSnapshotRecord[]>;
+/**
+ * Removes one exact raw handle only when its snapshot provenance still owns
+ * the target canonical Owner slot. The final authority/token checks and sync
+ * write share the existing serialized mutation lane.
+ */
+export declare function conditionalRemovePeer(remoteEpk: string, expectedToken: OwnerStorageToken, canCommit?: () => boolean): Promise<ConditionalPeerRemoval>;
+export declare function removePeer(remoteEpk: string, canCommit?: () => boolean): Promise<boolean>;
+/** Test-only: expose the identity-file path so tests can clean it. */
+export declare const _IDENTITY_FILE_FOR_TEST: string;
+/** Test-only: expose unlink for cleanup. */
+export declare const _unlinkIdentityFileForTest: () => Promise<void>;
+export {};