@yefengr/pi-reach 0.0.0-stage → 0.0.2

package/dist/pairing/owner_storage.js

@@ -0,0 +1,263 @@
+import { writeFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { canonicalizeEd25519PublicKey } from "./crypto.js";
+const PEERS_PATH = join(homedir(), ".pi", "pi-reach", "peers.json");
+export async function listPeers() {
+    try {
+        const raw = await readFile(PEERS_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.peers) ? parsed.peers : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Strict container read used by serialized storage mutations. Valid records
+ * remain verbatim so one corrupt entry never erases other pairings.
+ */
+async function _readPeerContainerStrict() {
+    let raw;
+    try {
+        raw = await readFile(PEERS_PATH, "utf8");
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed.peers)) {
+        throw new Error("Invalid peers.json container");
+    }
+    return parsed.peers;
+}
+let _peerMutationQueue = Promise.resolve();
+const _ownerSlotTokens = new Map();
+const _ownerStorageTokenBrand = Symbol("owner-storage-token");
+function _ownerSlotKey(rawOwnerPubkey) {
+    if (typeof rawOwnerPubkey !== "string") {
+        // Invalid non-string records remain isolated; their quarantine slots never
+        // collide with a valid canonical Owner identity.
+        return `raw:quarantine:${typeof rawOwnerPubkey}`;
+    }
+    try {
+        return `owner:${canonicalizeEd25519PublicKey(rawOwnerPubkey, "Owner record")}`;
+    }
+    catch {
+        return `raw:string:${rawOwnerPubkey}`;
+    }
+}
+function _tokenForSlot(slot) {
+    const existing = _ownerSlotTokens.get(slot);
+    if (existing)
+        return existing;
+    const token = Object.freeze({ [_ownerStorageTokenBrand]: true });
+    _ownerSlotTokens.set(slot, token);
+    return token;
+}
+function _invalidateOwnerSlot(rawOwnerPubkey) {
+    const slot = _ownerSlotKey(rawOwnerPubkey);
+    const token = Object.freeze({ [_ownerStorageTokenBrand]: true });
+    _ownerSlotTokens.set(slot, token);
+    return token;
+}
+function _serializePeerMutation(mutation) {
+    const result = _peerMutationQueue.then(mutation, mutation);
+    _peerMutationQueue = result.then(() => undefined, () => undefined);
+    return result;
+}
+export function addPeer(record) {
+    return _serializePeerMutation(async () => {
+        const peers = await listPeers();
+        const idx = peers.findIndex((peer) => !!peer &&
+            typeof peer === "object" &&
+            peer.remote_epk === record.remote_epk);
+        const previousRecord = idx >= 0 ? peers[idx] : undefined;
+        if (idx >= 0) {
+            peers[idx] = record; // idempotent re-pair
+        }
+        else {
+            peers.push(record);
+        }
+        await mkdir(dirname(PEERS_PATH), { recursive: true });
+        await writeFile(PEERS_PATH, JSON.stringify({ peers }, null, 2));
+        // A successful re-pair is a new storage provenance event even when the
+        // record bytes happen to be identical.
+        const token = _invalidateOwnerSlot(record.remote_epk);
+        return idx >= 0
+            ? { record, token, previousRecord }
+            : { record, token };
+    });
+}
+/**
+ * Returns the set of distinct `remote_epk` values in peers.json.
+ *
+ * Each `remote_epk` is the paired Owner's Ed25519 public key and represents a
+ * machine-scoped authorization entry.
+ */
+export async function listOwnerPubkeys() {
+    const peers = await listPeers();
+    const seen = new Set();
+    for (const peer of peers) {
+        if (!peer || typeof peer !== "object") {
+            seen.add(peer);
+            continue;
+        }
+        seen.add(peer.remote_epk);
+    }
+    return [...seen];
+}
+/**
+ * Atomically snapshots raw Owner handles and their canonical-slot provenance.
+ * The token is process-local and opaque to callers.
+ */
+export function snapshotOwnerPubkeys() {
+    return _serializePeerMutation(async () => {
+        const peers = await _readPeerContainerStrict();
+        const rawOwners = new Set();
+        for (const peer of peers) {
+            if (!peer || typeof peer !== "object") {
+                rawOwners.add(peer);
+            }
+            else {
+                rawOwners.add(peer.remote_epk);
+            }
+        }
+        return [...rawOwners].map((rawOwnerPubkey) => ({
+            rawOwnerPubkey,
+            token: _tokenForSlot(_ownerSlotKey(rawOwnerPubkey)),
+        }));
+    });
+}
+/**
+ * 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 function conditionalRemovePeer(remoteEpk, expectedToken, canCommit) {
+    return _serializePeerMutation(async () => {
+        const slot = _ownerSlotKey(remoteEpk);
+        // Provenance belongs to the canonical Owner slot, not the exact raw
+        // spelling. A stale slot must therefore win over an absent old spelling.
+        if (_tokenForSlot(slot) !== expectedToken)
+            return { outcome: "stale" };
+        const peers = await _readPeerContainerStrict();
+        const filtered = peers.filter((peer) => !peer ||
+            typeof peer !== "object" ||
+            peer.remote_epk !== remoteEpk);
+        if (filtered.length === peers.length)
+            return { outcome: "not_found" };
+        await mkdir(dirname(PEERS_PATH), { recursive: true });
+        // No await may intervene between the final token/authority checks and
+        // synchronous write, preserving the lane's fail-closed commit boundary.
+        if (_tokenForSlot(slot) !== expectedToken)
+            return { outcome: "stale" };
+        if (canCommit) {
+            let authorized = false;
+            try {
+                authorized = canCommit();
+            }
+            catch {
+                return { outcome: "no_authority" };
+            }
+            if (!authorized)
+                return { outcome: "no_authority" };
+        }
+        writeFileSync(PEERS_PATH, JSON.stringify({ peers: filtered }, null, 2));
+        return { outcome: "removed", nextToken: _invalidateOwnerSlot(remoteEpk) };
+    });
+}
+/**
+ * Compensates a specific addPeer write only while that write still owns its
+ * canonical Owner slot. The receipt's raw written record must still be
+ * present, so an out-of-band replacement cannot be removed or overwritten.
+ */
+export function conditionalRollbackPeer(receipt, canCommit) {
+    return _serializePeerMutation(async () => {
+        const slot = _ownerSlotKey(receipt.record.remote_epk);
+        if (_tokenForSlot(slot) !== receipt.token)
+            return { outcome: "stale" };
+        const peers = await _readPeerContainerStrict();
+        const idx = peers.findIndex((peer) => {
+            try {
+                return JSON.stringify(peer) === JSON.stringify(receipt.record);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (idx < 0)
+            return { outcome: "not_found" };
+        const restoringPreviousRecord = "previousRecord" in receipt;
+        const nextPeers = [...peers];
+        if (restoringPreviousRecord) {
+            nextPeers[idx] = receipt.previousRecord;
+        }
+        else {
+            nextPeers.splice(idx, 1);
+        }
+        await mkdir(dirname(PEERS_PATH), { recursive: true });
+        // No await may intervene between the final token/authority checks and
+        // synchronous write, preserving the lane's fail-closed commit boundary.
+        if (_tokenForSlot(slot) !== receipt.token)
+            return { outcome: "stale" };
+        if (canCommit) {
+            let authorized = false;
+            try {
+                authorized = canCommit();
+            }
+            catch {
+                return { outcome: "no_authority" };
+            }
+            if (!authorized)
+                return { outcome: "no_authority" };
+        }
+        writeFileSync(PEERS_PATH, JSON.stringify({ peers: nextPeers }, null, 2));
+        return {
+            outcome: restoringPreviousRecord ? "restored" : "removed",
+            nextToken: _invalidateOwnerSlot(receipt.record.remote_epk),
+        };
+    });
+}
+export function removePeer(remoteEpk, canCommit) {
+    return _serializePeerMutation(async () => {
+        const peers = await listPeers();
+        const filtered = peers.filter((peer) => !peer ||
+            typeof peer !== "object" ||
+            peer.remote_epk !== remoteEpk);
+        if (filtered.length === peers.length)
+            return false;
+        await mkdir(dirname(PEERS_PATH), { recursive: true });
+        const serialized = JSON.stringify({ peers: filtered }, null, 2);
+        if (canCommit) {
+            // Guarded commits are atomic with their final authority check: fail
+            // closed on false/throw, then synchronously persist the small JSON rewrite.
+            let authorized = false;
+            try {
+                authorized = canCommit();
+            }
+            catch {
+                return false;
+            }
+            if (!authorized)
+                return false;
+            writeFileSync(PEERS_PATH, serialized);
+        }
+        else {
+            // Manual removals keep the established asynchronous storage behavior.
+            await writeFile(PEERS_PATH, serialized);
+        }
+        const removed = true;
+        if (removed)
+            _invalidateOwnerSlot(remoteEpk);
+        return removed;
+    });
+}
+//# sourceMappingURL=owner_storage.js.map

package/dist/pairing/owner_storage.js.map

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

package/dist/pairing/qr.d.ts

@@ -0,0 +1,39 @@
+import { PAIRING_INVITE_TTL_MS, PAIR_TTL_MAX_MS, PAIR_TTL_MIN_MS } from "../vendor/protocol/outer/index.js";
+export { PAIRING_INVITE_TTL_MS, PAIR_TTL_MAX_MS, PAIR_TTL_MIN_MS };
+export declare const PAIRING_CODE_LENGTH = 8;
+export declare const PAIRING_CODE_PATTERN: RegExp;
+export declare function clampPairTtlMs(ttlMs: number): number;
+export type PairingInvite = Readonly<{
+    code: string;
+    expiresAt: number;
+}>;
+export type CodeReservation = Readonly<{
+    code: string;
+    ownerId: string;
+    requestId: string;
+}>;
+export type CodeReservationResult<T = unknown> = {
+    status: "reserved";
+    reservation: CodeReservation;
+} | {
+    status: "committed";
+    completion: T;
+} | {
+    status: "expired" | "consumed" | "unknown";
+};
+export declare class QRSession {
+    private active;
+    generateCode(): string;
+    issueCode(ttlMs?: number): PairingInvite;
+    issueInvite(ttlMs?: number): PairingInvite;
+    getActiveInvite(): PairingInvite | null;
+    reserveCode<T = unknown>(code: string, ownerId: string, requestId: string): CodeReservationResult<T>;
+    commitCode<T>(reservation: CodeReservation, completion: T): boolean;
+    releaseCode(reservation: CodeReservation): boolean;
+    isReservationCurrent(reservation: CodeReservation): boolean;
+    consumeCode(code: string): "ok" | "expired" | "consumed" | "unknown";
+    clear(): void;
+}
+export declare const qrSession: QRSession;
+export declare function renderQRAscii(code: string): string;
+export declare function displayQR(code: string): void;

package/dist/pairing/qr.js

@@ -0,0 +1,113 @@
+import { randomBytes } from "node:crypto";
+import { PAIRING_INVITE_TTL_MS, PAIR_TTL_MAX_MS, PAIR_TTL_MIN_MS } from "../vendor/protocol/outer/index.js";
+import qrTerminal from "qrcode-terminal";
+export { PAIRING_INVITE_TTL_MS, PAIR_TTL_MAX_MS, PAIR_TTL_MIN_MS };
+export const PAIRING_CODE_LENGTH = 8;
+export const PAIRING_CODE_PATTERN = /^[0-9A-HJKMNP-TV-Z]{8}$/;
+const CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export function clampPairTtlMs(ttlMs) {
+    if (!Number.isFinite(ttlMs))
+        return PAIRING_INVITE_TTL_MS;
+    return Math.min(PAIR_TTL_MAX_MS, Math.max(PAIR_TTL_MIN_MS, Math.floor(ttlMs)));
+}
+export class QRSession {
+    active = null;
+    generateCode() {
+        const random = randomBytes(PAIRING_CODE_LENGTH);
+        let code = "";
+        for (const byte of random)
+            code += CROCKFORD_BASE32[byte & 31];
+        return code;
+    }
+    issueCode(ttlMs = PAIRING_INVITE_TTL_MS) {
+        const invite = Object.freeze({ code: this.generateCode(), expiresAt: Date.now() + ttlMs });
+        this.active = { ...invite, consumed: false };
+        return invite;
+    }
+    issueInvite(ttlMs = PAIRING_INVITE_TTL_MS) {
+        return this.issueCode(ttlMs);
+    }
+    getActiveInvite() {
+        if (!this.active)
+            return null;
+        return { code: this.active.code, expiresAt: this.active.expiresAt };
+    }
+    reserveCode(code, ownerId, requestId) {
+        const active = this.active;
+        if (!active || active.code !== code)
+            return { status: "unknown" };
+        const existing = active.reservation;
+        if (existing) {
+            if (existing.reservation.ownerId !== ownerId || existing.reservation.requestId !== requestId) {
+                return { status: "consumed" };
+            }
+            // A committed result belongs to the exact Owner/request and remains
+            // replayable until this invite is replaced or cleared, even after its TTL.
+            if (existing.status === "committed") {
+                return { status: "committed", completion: existing.completion };
+            }
+        }
+        if (Date.now() >= active.expiresAt)
+            return { status: "expired" };
+        if (active.consumed)
+            return { status: "consumed" };
+        if (existing) {
+            if (existing.status === "reserved")
+                return { status: "reserved", reservation: existing.reservation };
+            // A released reservation remains private to the original attempt. A
+            // retry by that exact Owner/request may reacquire it; nobody else can.
+        }
+        const reservation = existing?.status === "released"
+            ? Object.freeze({ code, ownerId, requestId })
+            : existing?.reservation ?? Object.freeze({ code, ownerId, requestId });
+        active.reservation = { reservation, status: "reserved" };
+        return { status: "reserved", reservation };
+    }
+    commitCode(reservation, completion) {
+        const active = this.active;
+        const state = active?.reservation;
+        if (!active || !state || state.reservation !== reservation || state.status !== "reserved")
+            return false;
+        if (active.code !== reservation.code || Date.now() >= active.expiresAt)
+            return false;
+        state.status = "committed";
+        state.completion = completion;
+        return true;
+    }
+    releaseCode(reservation) {
+        const active = this.active;
+        const state = active?.reservation;
+        if (!active || !state || state.reservation !== reservation || state.status !== "reserved")
+            return false;
+        state.status = "released";
+        return true;
+    }
+    isReservationCurrent(reservation) {
+        const active = this.active;
+        const state = active?.reservation;
+        return !!active && !!state && state.reservation === reservation && state.status === "reserved" && active.code === reservation.code && Date.now() < active.expiresAt;
+    }
+    consumeCode(code) {
+        if (!this.active || this.active.code !== code)
+            return "unknown";
+        if (this.active.consumed || this.active.reservation)
+            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();
+export function renderQRAscii(code) {
+    let out = "";
+    qrTerminal.generate(code, { small: true }, (qrcode) => { out = qrcode; });
+    return out;
+}
+export function displayQR(code) {
+    process.stderr.write(`\nScan to pair:\n\n${renderQRAscii(code)}\n`);
+}
+//# 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,36 @@
+import { type Ed25519Keypair } from "./crypto.js";
+import { type KeyStoreBackend } from "./identity-keyring.js";
+export { addPeer, listPeers, listOwnerPubkeys, snapshotOwnerPubkeys, conditionalRemovePeer, conditionalRollbackPeer, removePeer, } from "./owner_storage.js";
+export type { PeerRecord, OwnerStorageToken, OwnerStorageSnapshotRecord, ConditionalPeerRemoval, PeerWriteReceipt, ConditionalPeerRollback, } from "./owner_storage.js";
+export { _setKeyringOperationTimeoutForTest, _setNativeBindingErrorForTest, KeyringMutationTimeoutError, KeyringReadTimeoutError, } from "./identity-keyring.js";
+export type { KeyStoreBackend } from "./identity-keyring.js";
+export { IdentityLockTimeoutError } from "./identity-lock.js";
+export declare class KeyringUnavailableError extends Error {
+    constructor(cause: unknown);
+}
+export declare class PairedIdentityMissingError extends Error {
+    constructor(pairedCount: number, cause: unknown);
+}
+type IdentityFileErrorCategory = "read_failed" | "invalid_format";
+export declare class IdentityFileError extends Error {
+    readonly identityPath: string;
+    readonly category: IdentityFileErrorCategory;
+    constructor(identityPath: string, category: IdentityFileErrorCategory);
+}
+export declare class KeyringIdentityError extends Error {
+    readonly service: string;
+    constructor(service: string);
+}
+export declare function _setKeyStoreBackendForTest(value: KeyStoreBackend | null): void;
+export declare function _setKeyringExpectedForTest(value: boolean | null): void;
+export declare function _setKeyringRetryForTest(attempts: number | null, delayMs?: number): void;
+export declare function _setIdentityLockTimingForTest(waitTimeoutMs: number | null, pollIntervalMs?: number): void;
+/**
+ * Returns the stable Host identity. Existing file identity wins; otherwise all
+ * keyring reads, generation, and persistence run under the fixed
+ * cross-process identity lock. Every source is read again after lock acquisition.
+ */
+export declare function getOrCreateEd25519Keypair(): Promise<Ed25519Keypair>;
+export declare const _IDENTITY_FILE_FOR_TEST: string;
+export declare const _IDENTITY_LOCK_FILE_FOR_TEST: string;
+export declare const _unlinkIdentityFileForTest: () => Promise<void>;