@geohar/un-bien 0.7.0 → 0.9.0

package/dist/pairing/storage.d.ts

@@ -13,6 +13,13 @@ export declare class KeyringUnavailableError extends Error {
 export declare class PairedIdentityMissingError extends Error {
     constructor(pairedCount: number, cause: unknown);
 }
+/** Raised when the file-backend identity EXISTS but cannot be read or parsed
+ *  (bad permissions, corruption). Treating that as "no identity" would let the
+ *  resolver mint a fresh seed over a real one — the file-side version of the
+ *  flop — so we FAIL LOUD instead of minting. */
+export declare class FileIdentityUnreadableError extends Error {
+    constructor(path: string, cause: unknown);
+}
 /**
  * Minimal backend interface for credential reads/writes. Swappable so
  * tests can inject a controlled in-memory store without touching the OS
@@ -40,36 +47,54 @@ 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;
+export type IdentityStorageBackend = "keychain" | "file";
 /**
- * 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.
+ * Returns this Pi's long-term Ed25519 identity, minting one only on a genuine
+ * first run. The seed is portable and its public key (epk) is what the relay
+ * routes on and what devices pair against — so this resolver's ONE job is to
+ * never change the identity out from under an existing pairing (the "flop").
+ *
+ * Resolution (operator-selectable backend — see design):
+ *   0. `UNBIEN_IDENTITY_SEED` env override — always wins, read-only.
+ *   1. The SELECTED backend (`identity.storage`, default keychain): keychain
+ *      (retried — a locked Keychain throws, which is NOT "empty") or the 0600
+ *      file at `identity.path`.
+ *   2. Migration READ-IN-PLACE of the OTHER backend — recovers an existing
+ *      identity (a keychain key when file is selected, or a file when keychain
+ *      is selected) WITHOUT writing it through.
+ *   3. Generate + persist to the selected backend, but ONLY when every
+ *      consulted source was genuinely empty. A keychain that THREW on a
+ *      core-OS-keyring platform (macOS/Windows) is possibly-present →
+ *      `KeyringUnavailableError`, never minted over. Existing pairings →
+ *      `PairedIdentityMissingError`. A present-but-unreadable file →
+ *      `FileIdentityUnreadableError`. This is write-only-if-nonexistent: the
+ *      resolver's only mutation is a genuine-first-run mint.
  *
- * Idempotent: subsequent calls return the same identity. The migration
- * runs at most once per machine (the old entry is deleted after copy).
+ * Idempotent. On headless Linux / a Bun-built pi (no usable keyring) the file
+ * backend is used automatically.
  */
 export declare function getOrCreateEd25519Keypair(): Promise<Ed25519Keypair>;
+export interface IdentityInfo {
+    /** Base64 Ed25519 public key (epk) — PUBLIC, safe to display. `null` when no
+     *  identity exists yet (one is minted on first real use). */
+    readonly epk: string | null;
+    /** The selected/effective storage backend. */
+    readonly backend: IdentityStorageBackend;
+    /** Where the identity resolved from (or would come from). */
+    readonly source: "env-override" | "keychain" | "file" | "none" | "error";
+    /** Resolved file-backend path. */
+    readonly filePath: string;
+    /** Human note (migration recovery, error cause, first-run hint). */
+    readonly detail?: string;
+}
+/**
+ * Reports the CURRENT identity state WITHOUT minting or mutating anything — the
+ * read-only backing for `unbien identity show`. Returns only NON-SECRET fields
+ * (epk is public); the private seed is NEVER included, since command output is
+ * LLM-visible. Read errors are surfaced as `source:"error"` with a `detail`,
+ * not thrown — this is a diagnostic.
+ */
+export declare function describeIdentity(): Promise<IdentityInfo>;
 export interface PeerRecord {
     name: string;
     remote_epk: string;