@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/remote/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * One error type for every peer-facing failure, distinguished by kind.
+ *
+ * The desktop branches on `kind` alone — each kind maps to exactly one state it can show — so the
+ * prose below is display text and may change freely. `identity` means the certificate presented is
+ * not the one captured at pairing: the fail-closed state that forces re-pairing rather than a
+ * silent re-trust.
+ */
+export type RemotePeerErrorKind = 'offline' | 'identity' | 'unauthorized' | 'network' | 'rejected';
+export declare class RemotePeerError extends Error {
+    readonly kind: RemotePeerErrorKind;
+    constructor(kind: RemotePeerErrorKind, message: string);
+}
+/** Refused by the peer's pairing/redemption logic for a reason the viewer cannot fix remotely. */
+export declare class InviteRejectedError extends Error {
+    constructor(message: string);
+}
+/**
+ * The serve lock is held by a process this one cannot authenticate.
+ *
+ * Takeover is deliberately not attempted: two live listeners, or adopting a listener that cannot
+ * prove which install it belongs to, are both worse than a clear error the operator can act on.
+ */
+export declare class RemoteOwnershipError extends Error {
+    constructor(message: string);
+}

package/dist/src/remote/errors.js

@@ -0,0 +1,21 @@
+export class RemotePeerError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'RemotePeerError';
+    }
+}
+/** Refused by the peer's pairing/redemption logic for a reason the viewer cannot fix remotely. */
+export class InviteRejectedError extends Error {
+    constructor(message) { super(message); this.name = 'InviteRejectedError'; }
+}
+/**
+ * The serve lock is held by a process this one cannot authenticate.
+ *
+ * Takeover is deliberately not attempted: two live listeners, or adopting a listener that cannot
+ * prove which install it belongs to, are both worse than a clear error the operator can act on.
+ */
+export class RemoteOwnershipError extends Error {
+    constructor(message) { super(message); this.name = 'RemoteOwnershipError'; }
+}

package/dist/src/remote/network.d.ts

@@ -0,0 +1,48 @@
+import { networkInterfaces } from 'node:os';
+/** The Tailscale interface range. A literal inside it is a Tailscale address. */
+export declare function isTailscaleAddress(address: string): boolean;
+/** Loopback, RFC1918, CGNAT/Tailscale, and the private IPv6 families. */
+export declare function isPrivateAddress(address: string): boolean;
+/** A concrete MagicDNS hostname (ends in `.ts.net`). Never a wildcard, never a public name. */
+export declare function isMagicDnsName(name: string): boolean;
+/** Whether a peer host — literal private address or MagicDNS name — may be contacted at all. */
+export declare function isAllowedPeerHost(host: string): boolean;
+/** One answer a DNS lookup produced for a peer name. */
+export interface PeerAddress {
+    address: string;
+    family: 4 | 6;
+}
+/**
+ * Resolve a peer name to every validated address, IPv4 first.
+ *
+ * Every answer the resolver returns must pass the private predicate — one public record mixed in
+ * is refused rather than shuffled past — and the validated list is what the caller connects
+ * against directly, so a second, later resolution (the DNS-rebinding step) can only ever produce
+ * an address already checked here. Returning all of them lets a dual-stack name fall through to
+ * its other family when the first address is unreachable (a v4 answer while only the v6 route
+ * works, or the reverse); IPv4 sorts first because a dual-stack MagicDNS name on the same LAN
+ * usually reaches the v4 listener. Literal addresses skip the resolver entirely.
+ */
+export declare function resolvePeerAddresses(host: string, lookup?: (hostname: string, options: {
+    all: true;
+    verbatim: true;
+}) => Promise<PeerAddress[]>): Promise<PeerAddress[]>;
+/** The first of the validated addresses: the primary target when only one attempt is wanted. */
+export declare function resolvePeerAddress(host: string, lookup?: (hostname: string, options: {
+    all: true;
+    verbatim: true;
+}) => Promise<PeerAddress[]>): Promise<PeerAddress>;
+/**
+ * Discover this machine's advertiseable addresses for a pairing code.
+ *
+ * A concrete MagicDNS hostname first when the Tailscale CLI is present — names survive a machine's
+ * IP changing, which a raw address does not — then the private addresses of the machine's real
+ * interfaces. `tailscale status --json` is read with its `Self` record only; a missing CLI, a
+ * stopped daemon, or an unparsable payload all degrade to the interface addresses rather than
+ * failing pairing.
+ */
+export interface HostDiscovery {
+    tailscale?: () => Promise<string | undefined>;
+    interfaces?: () => ReturnType<typeof networkInterfaces>;
+}
+export declare function advertiseHosts(discovery?: HostDiscovery): Promise<string[]>;

package/dist/src/remote/network.js

@@ -0,0 +1,135 @@
+import { execFile } from 'node:child_process';
+import { networkInterfaces } from 'node:os';
+import { isIP } from 'node:net';
+import { promisify } from 'node:util';
+/**
+ * Which addresses a remote peer may live at, and how a peer's DNS name is turned into one.
+ *
+ * The predicate accepts the private IPv4 ranges, Tailscale's carrier-grade NAT range (100.64/10,
+ * the addresses a MagicDNS name resolves to when both machines run Tailscale), loopback, and the
+ * IPv6 loopback/ULA/link-local ranges — the same families `config.ts` already restricts provider
+ * and Graphiti endpoints to, plus 100.64/10 which only Tailscale assigns. A peer name is therefore
+ * either a literal private address or a concrete MagicDNS hostname; anything public is refused
+ * before a socket is opened.
+ */
+const execFileAsync = promisify(execFile);
+/** The Tailscale interface range. A literal inside it is a Tailscale address. */
+export function isTailscaleAddress(address) {
+    if (isIP(address) !== 4)
+        return false;
+    const [first, second] = address.split('.').map(Number);
+    return first === 100 && second >= 64 && second <= 127;
+}
+/** Loopback, RFC1918, CGNAT/Tailscale, and the private IPv6 families. */
+export function isPrivateAddress(address) {
+    const value = address.replace(/^\[|\]$/g, '').toLowerCase();
+    if (value === 'localhost' || value === '::1')
+        return true;
+    if (isTailscaleAddress(value))
+        return true;
+    if (isIP(value) === 4) {
+        const [first, second] = value.split('.').map(Number);
+        return first === 127 || first === 10 || (first === 172 && second >= 16 && second <= 31) || (first === 192 && second === 168);
+    }
+    return isIP(value) === 6 && (/^f[cd]/.test(value) || /^fe80/.test(value));
+}
+/** A concrete MagicDNS hostname (ends in `.ts.net`). Never a wildcard, never a public name. */
+export function isMagicDnsName(name) {
+    const value = name.toLowerCase();
+    if (!value.endsWith('.ts.net') || value.includes('*'))
+        return false;
+    // Each label is 1–63 characters: the leading and trailing characters must be alphanumeric, and the
+    // interior (which may hold hyphens) is optional — a one-character label like `a.example.ts.net`
+    // is a valid MagicDNS name, and refusing it would force an IP fallback or strand a saved name.
+    const label = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
+    return new RegExp(`^(?:${label}\\.)+${label}$`).test(value);
+}
+/** Whether a peer host — literal private address or MagicDNS name — may be contacted at all. */
+export function isAllowedPeerHost(host) {
+    const value = host.replace(/^\[|\]$/g, '');
+    if (isIP(value))
+        return isPrivateAddress(value);
+    return isMagicDnsName(host);
+}
+/**
+ * Resolve a peer name to every validated address, IPv4 first.
+ *
+ * Every answer the resolver returns must pass the private predicate — one public record mixed in
+ * is refused rather than shuffled past — and the validated list is what the caller connects
+ * against directly, so a second, later resolution (the DNS-rebinding step) can only ever produce
+ * an address already checked here. Returning all of them lets a dual-stack name fall through to
+ * its other family when the first address is unreachable (a v4 answer while only the v6 route
+ * works, or the reverse); IPv4 sorts first because a dual-stack MagicDNS name on the same LAN
+ * usually reaches the v4 listener. Literal addresses skip the resolver entirely.
+ */
+export async function resolvePeerAddresses(host, lookup) {
+    const value = host.replace(/^\[|\]$/g, '');
+    if (isIP(value)) {
+        if (!isPrivateAddress(value))
+            throw new Error(`Refusing to contact ${host}: it is not a private or Tailscale address`);
+        return [{ address: value, family: isIP(value) === 6 ? 6 : 4 }];
+    }
+    if (!isAllowedPeerHost(host))
+        throw new Error(`Refusing to contact ${host}: peer hosts must be private addresses or Tailscale names`);
+    const resolve = lookup ?? (async (hostname) => {
+        const { promises } = await import('node:dns');
+        return await promises.lookup(hostname, { all: true, verbatim: true });
+    });
+    const answers = await resolve(host, { all: true, verbatim: true });
+    const list = Array.isArray(answers) ? answers : [answers];
+    if (!list.length)
+        throw new Error(`Could not resolve ${host}: no addresses returned`);
+    for (const answer of list) {
+        if (!isPrivateAddress(answer.address))
+            throw new Error(`Refusing to contact ${host}: it resolved to the non-private address ${answer.address}`);
+    }
+    const seen = new Set();
+    return [...list]
+        .sort((left, right) => left.family === right.family ? 0 : left.family === 4 ? -1 : 1)
+        .filter(answer => { if (seen.has(answer.address))
+        return false; seen.add(answer.address); return true; });
+}
+/** The first of the validated addresses: the primary target when only one attempt is wanted. */
+export async function resolvePeerAddress(host, lookup) {
+    return (await resolvePeerAddresses(host, lookup))[0];
+}
+async function tailscaleSelfName() {
+    try {
+        const { stdout } = await execFileAsync('tailscale', ['status', '--json'], { timeout: 4000, windowsHide: true, maxBuffer: 1 << 20 });
+        const parsed = JSON.parse(stdout);
+        const name = (parsed.Self?.DNSName ?? '').toLowerCase().replace(/\.$/, '');
+        return isMagicDnsName(name) ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function advertiseHosts(discovery = {}) {
+    const discoverTailscale = discovery.tailscale ?? tailscaleSelfName;
+    const hosts = [];
+    try {
+        const name = await discoverTailscale();
+        if (name !== undefined && isAllowedPeerHost(name))
+            hosts.push(name);
+    }
+    catch { /* Interface addresses still describe the machine. */ }
+    const interfaces = (discovery.interfaces ?? networkInterfaces)();
+    for (const entries of Object.values(interfaces)) {
+        for (const entry of entries ?? []) {
+            if (entry.internal)
+                continue;
+            const address = entry.address.replace(/^\[|\]$/g, '');
+            // Skip the IPv6 representation of IPv4 loopback; 127.0.0.1 already represents loopback.
+            if (address.startsWith('::ffff:'))
+                continue;
+            // Link-local IPv6 is scoped to the interface it arrived on, and the code has no scope id to
+            // carry: a viewer cannot dial the bare `fe80::…` this would advertise, so the pairing code
+            // must not name it. A machine reachable only over link-local simply gets no address here.
+            if (/^fe80:/i.test(address))
+                continue;
+            if (isPrivateAddress(address) && !hosts.includes(address))
+                hosts.push(address);
+        }
+    }
+    return hosts.slice(0, 8);
+}

package/dist/src/remote/pairing.d.ts

@@ -0,0 +1,98 @@
+import type { RemoteDevice, RemoteInvitation, RemoteShare, RemoteTransport, RemoteGrant, RemoteWorkspace } from './types.js';
+/**
+ * Pairing codes and every mutation of the remote configuration.
+ *
+ * The code is the whole handshake plan in one string the user moves by eye or clipboard:
+ * `andorra-pair://<base64url(JSON)>` carrying the host's candidate addresses, port, transport,
+ * certificate fingerprint, and the single-use invitation token. Decoding re-validates every field
+ * — a code is attacker-influenceable text, and nothing downstream may assume it was produced by
+ * `encodePairingCode`.
+ *
+ * All writes here run through `changeConfigFile`, whose callback must be a pure function of the
+ * configuration it is given because the transaction re-applies it when the file changed under it.
+ * That is why redemption generates the device id and credential BEFORE entering the callback: a
+ * retry then re-applies deterministically with the same values, and exactly one concurrent redeem
+ * commits.
+ */
+/** Ten minutes: long enough to type or paste between two machines, short enough to reissue freely. */
+export declare const INVITE_TTL_MS: number;
+export interface PairingCode {
+    v: 1;
+    hosts: string[];
+    port: number;
+    invite: string;
+    fp: string;
+    transport: RemoteTransport;
+    n: string;
+}
+export declare function encodePairingCode(code: PairingCode): string;
+/** Strict decode: unknown versions, public hosts, malformed tokens, and stray fields are all refusals. */
+export declare function decodePairingCode(value: string): PairingCode;
+/** Whether an invitation can still be redeemed right now. */
+export declare function invitationIsUsable(invitation: RemoteInvitation | null | undefined, now?: number): boolean;
+/**
+ * Create (or replace) the one active invitation and return its live code fragments.
+ *
+ * Replacing an unused invitation is ordinary (the user reopened Settings and wants a fresh code),
+ * which is why this is idempotent-by-new-token rather than refuse-when-one-exists.
+ */
+export declare function createRemoteInvitation(directory?: string, now?: number, grant?: RemoteGrant): Promise<RemoteInvitation>;
+/** Drop the active invitation without redeeming it (the Cancel button). */
+export declare function clearRemoteInvitation(directory?: string): Promise<void>;
+/**
+ * Redeem an invitation inside one locked transaction.
+ *
+ * The id and credential are generated before the callback so a re-apply sees identical values;
+ * the callback throws (aborting the write) unless the stored invitation is present, unredeemed,
+ * and unexpired. Two concurrent redemptions therefore race on the lock, and the loser's re-read
+ * finds `redeemedAt` set — it throws instead of appending a second device.
+ */
+export declare function redeemRemoteInvitation(invite: string, options?: {
+    label?: string;
+    directory?: string;
+    now?: number;
+}): Promise<{
+    deviceId: string;
+    credential: string;
+    grant: RemoteGrant;
+}>;
+/** Remove a paired device. The next request carrying its token fails: the table is re-read per request. */
+export declare function revokeRemoteDevice(deviceId: string, directory?: string): Promise<boolean>;
+/**
+ * Raise a paired device's authority to full owner access — the Settings action for a device paired
+ * under browse-only consent, so the owner does not have to revoke and re-pair a machine they already
+ * trust with the stronger credential it now wants.
+ *
+ * Authority is granted, never acquired by upgrade: the grant is an explicit write the owner makes,
+ * refused while hosting runs over cleartext HTTP exactly as a full-scope invitation is, because a
+ * bearer token on the wire in cleartext must never carry owner authority.
+ */
+export declare function grantRemoteDevice(deviceId: string, directory?: string): Promise<RemoteDevice | null>;
+export declare function addRemoteShare(path: string, options?: {
+    label?: string;
+    directory?: string;
+}): Promise<RemoteShare>;
+export declare function removeRemoteShare(shareId: string, directory?: string): Promise<boolean>;
+/** The listener's persisted port, written once when the OS assigned it. */
+export declare function persistRemotePort(port: number, directory?: string): Promise<void>;
+/** Give this installation its stable 128-bit identity, creating it on first serve. */
+export declare function ensureRemoteInstallId(directory?: string): Promise<string>;
+export declare function setRemoteTransport(transport: RemoteTransport, directory?: string): Promise<void>;
+export declare function newWorkspaceId(): string;
+export declare function addRemoteWorkspace(workspace: RemoteWorkspace, directory?: string): Promise<void>;
+export declare function removeRemoteWorkspace(workspaceId: string, directory?: string): Promise<boolean>;
+export declare function updateRemoteWorkspace(workspaceId: string, changes: {
+    nickname?: string;
+    host?: string | null;
+}, directory?: string): Promise<RemoteWorkspace | undefined>;
+/**
+ * The project registry: list, add (idempotent by path), remove.
+ *
+ * The caller resolves realpath before adding, so registry entries are canonical paths and two
+ * spellings of one folder cannot both appear.
+ */
+export declare function addProjectEntry(path: string, options?: {
+    name?: string;
+    directory?: string;
+}): Promise<void>;
+export declare function removeProjectEntry(path: string, directory?: string): Promise<boolean>;

package/dist/src/remote/pairing.js

@@ -0,0 +1,306 @@
+import { randomBytes } from 'node:crypto';
+import { changeConfigFile, configDirectory, loadConfig } from '../config.js';
+import { InviteRejectedError } from './errors.js';
+import { isAllowedPeerHost } from './network.js';
+/**
+ * Pairing codes and every mutation of the remote configuration.
+ *
+ * The code is the whole handshake plan in one string the user moves by eye or clipboard:
+ * `andorra-pair://<base64url(JSON)>` carrying the host's candidate addresses, port, transport,
+ * certificate fingerprint, and the single-use invitation token. Decoding re-validates every field
+ * — a code is attacker-influenceable text, and nothing downstream may assume it was produced by
+ * `encodePairingCode`.
+ *
+ * All writes here run through `changeConfigFile`, whose callback must be a pure function of the
+ * configuration it is given because the transaction re-applies it when the file changed under it.
+ * That is why redemption generates the device id and credential BEFORE entering the callback: a
+ * retry then re-applies deterministically with the same values, and exactly one concurrent redeem
+ * commits.
+ */
+/** Ten minutes: long enough to type or paste between two machines, short enough to reissue freely. */
+export const INVITE_TTL_MS = 10 * 60 * 1000;
+const BASE64URL_32 = /^[A-Za-z0-9_-]{43}$/;
+export function encodePairingCode(code) {
+    return `andorra-pair://${Buffer.from(JSON.stringify(code)).toString('base64url')}`;
+}
+/** Strict decode: unknown versions, public hosts, malformed tokens, and stray fields are all refusals. */
+export function decodePairingCode(value) {
+    const text = typeof value === 'string' ? value.trim() : '';
+    if (!text.startsWith('andorra-pair://'))
+        throw new InviteRejectedError('That is not an Andorra pairing code.');
+    let parsed;
+    try {
+        const decoded = Buffer.from(text.slice('andorra-pair://'.length), 'base64url');
+        // Buffer's base64url decoder is lenient; re-encoding must reproduce the input or it was noise.
+        if (decoded.toString('base64url') !== text.slice('andorra-pair://'.length))
+            throw new Error('not canonical');
+        parsed = JSON.parse(decoded.toString('utf8'));
+    }
+    catch {
+        throw new InviteRejectedError('That pairing code could not be read.');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new InviteRejectedError('That pairing code could not be read.');
+    const raw = parsed;
+    const allowed = new Set(['v', 'hosts', 'port', 'invite', 'fp', 'transport', 'n']);
+    if (Object.keys(raw).some(key => !allowed.has(key)))
+        throw new InviteRejectedError('That pairing code is from an unsupported version.');
+    if (raw.v !== 1)
+        throw new InviteRejectedError('That pairing code is from an unsupported version.');
+    if (!Array.isArray(raw.hosts) || raw.hosts.length < 1 || raw.hosts.length > 8 || raw.hosts.some(host => typeof host !== 'string' || !isAllowedPeerHost(host))) {
+        throw new InviteRejectedError('That pairing code names an address that is not private or on Tailscale.');
+    }
+    if (!Number.isSafeInteger(raw.port) || raw.port < 1 || raw.port > 65535)
+        throw new InviteRejectedError('That pairing code has an invalid port.');
+    if (typeof raw.invite !== 'string' || !BASE64URL_32.test(raw.invite))
+        throw new InviteRejectedError('That pairing code has an invalid invitation.');
+    if (typeof raw.fp !== 'string' || !BASE64URL_32.test(raw.fp))
+        throw new InviteRejectedError('That pairing code has an invalid fingerprint.');
+    if (raw.transport !== 'https' && raw.transport !== 'http')
+        throw new InviteRejectedError('That pairing code has an invalid transport.');
+    if (typeof raw.n !== 'string' || !raw.n.trim() || raw.n.length > 64 || /[\0\r\n]/.test(raw.n))
+        throw new InviteRejectedError('That pairing code has an invalid name.');
+    return { v: 1, hosts: raw.hosts, port: raw.port, invite: raw.invite, fp: raw.fp, transport: raw.transport, n: raw.n };
+}
+/** Whether an invitation can still be redeemed right now. */
+export function invitationIsUsable(invitation, now = Date.now()) {
+    if (!invitation)
+        return false;
+    if (invitation.redeemedAt !== undefined)
+        return false;
+    return Date.parse(invitation.expiresAt) > now;
+}
+/**
+ * Create (or replace) the one active invitation and return its live code fragments.
+ *
+ * Replacing an unused invitation is ordinary (the user reopened Settings and wants a fresh code),
+ * which is why this is idempotent-by-new-token rather than refuse-when-one-exists.
+ */
+export async function createRemoteInvitation(directory = configDirectory(), now = Date.now(), grant = 'browse') {
+    const token = randomBytes(32).toString('base64url');
+    const createdAt = new Date(now).toISOString();
+    const expiresAt = new Date(now + INVITE_TTL_MS).toISOString();
+    await changeConfigFile(directory, config => ({
+        ...config,
+        remote: { ...config.remote, hosting: { ...config.remote?.hosting, invitation: { token, createdAt, expiresAt, ...(grant === 'full' ? { grant } : {}) } } },
+    }));
+    return { token, createdAt, expiresAt, ...(grant === 'full' ? { grant } : {}) };
+}
+/** Drop the active invitation without redeeming it (the Cancel button). */
+export async function clearRemoteInvitation(directory = configDirectory()) {
+    await changeConfigFile(directory, config => ({
+        ...config,
+        remote: { ...config.remote, hosting: { ...config.remote?.hosting, invitation: null } },
+    }));
+}
+/**
+ * Redeem an invitation inside one locked transaction.
+ *
+ * The id and credential are generated before the callback so a re-apply sees identical values;
+ * the callback throws (aborting the write) unless the stored invitation is present, unredeemed,
+ * and unexpired. Two concurrent redemptions therefore race on the lock, and the loser's re-read
+ * finds `redeemedAt` set — it throws instead of appending a second device.
+ */
+export async function redeemRemoteInvitation(invite, options = {}) {
+    const directory = options.directory ?? configDirectory();
+    const now = options.now ?? Date.now();
+    const deviceId = randomBytes(8).toString('hex');
+    const credential = randomBytes(32).toString('base64url');
+    const label = typeof options.label === 'string' && options.label.trim() && options.label.length <= 64 && !/[\0\r\n]/.test(options.label) ? options.label.trim() : undefined;
+    let granted = 'browse';
+    await changeConfigFile(directory, config => {
+        const invitation = config.remote?.hosting?.invitation;
+        if (!invitation || invitation.token !== invite)
+            throw new InviteRejectedError('That pairing code is not active on this machine.');
+        if (invitation.redeemedAt !== undefined)
+            throw new InviteRejectedError('That pairing code has already been used.');
+        if (Date.parse(invitation.expiresAt) <= now)
+            throw new InviteRejectedError('That pairing code has expired. Generate a new one.');
+        if (invitation.grant === 'full' && config.remote?.hosting?.transport === 'http')
+            throw new InviteRejectedError('Full-control pairing is not permitted over insecure HTTP.');
+        granted = invitation.grant === 'full' ? 'full' : 'browse';
+        const device = { id: deviceId, token: credential, ...(label ? { label } : {}), ...(invitation.grant === 'full' ? { grant: 'full' } : {}), addedAt: new Date(now).toISOString() };
+        const devices = [...(config.remote?.hosting?.devices ?? []), device];
+        if (devices.length > 32)
+            throw new InviteRejectedError('This machine already has the maximum number of paired devices.');
+        return {
+            ...config,
+            remote: {
+                ...config.remote,
+                hosting: {
+                    ...config.remote?.hosting,
+                    invitation: { ...invitation, redeemedAt: new Date(now).toISOString() },
+                    devices,
+                },
+            },
+        };
+    });
+    // The successful locked redemption determines this scope; a later device-table read
+    // could race with revocation and falsely report a different grant.
+    return { deviceId, credential, grant: granted };
+}
+/** Remove a paired device. The next request carrying its token fails: the table is re-read per request. */
+export async function revokeRemoteDevice(deviceId, directory = configDirectory()) {
+    let removed = false;
+    const next = await changeConfigFile(directory, config => {
+        const devices = config.remote?.hosting?.devices ?? [];
+        const kept = devices.filter(device => device.id !== deviceId);
+        removed = kept.length !== devices.length;
+        if (!removed)
+            return config;
+        return { ...config, remote: { ...config.remote, hosting: { ...config.remote?.hosting, devices: kept } } };
+    });
+    return removed && !(next.remote?.hosting?.devices ?? []).some(device => device.id === deviceId);
+}
+/**
+ * Raise a paired device's authority to full owner access — the Settings action for a device paired
+ * under browse-only consent, so the owner does not have to revoke and re-pair a machine they already
+ * trust with the stronger credential it now wants.
+ *
+ * Authority is granted, never acquired by upgrade: the grant is an explicit write the owner makes,
+ * refused while hosting runs over cleartext HTTP exactly as a full-scope invitation is, because a
+ * bearer token on the wire in cleartext must never carry owner authority.
+ */
+export async function grantRemoteDevice(deviceId, directory = configDirectory()) {
+    let granted = null;
+    await changeConfigFile(directory, config => {
+        if ((config.remote?.hosting?.transport ?? 'https') === 'http') {
+            throw new Error('Full-control consent requires HTTPS. Stop insecure HTTP hosting before granting owner authority.');
+        }
+        const devices = config.remote?.hosting?.devices ?? [];
+        const device = devices.find(entry => entry.id === deviceId);
+        if (!device)
+            return config;
+        const raised = { ...device, grant: 'full' };
+        granted = raised;
+        return { ...config, remote: { ...config.remote, hosting: { ...config.remote?.hosting, devices: devices.map(entry => entry.id === deviceId ? raised : entry) } } };
+    });
+    return granted;
+}
+export async function addRemoteShare(path, options = {}) {
+    const directory = options.directory ?? configDirectory();
+    const share = { id: randomBytes(6).toString('hex'), path, ...(options.label && options.label.trim() ? { label: options.label.trim().slice(0, 64) } : {}) };
+    // Adding a folder that is already shared is an idempotent success, and the answer is the STORED
+    // entry: returning the freshly generated one would hand the caller an id no configuration holds,
+    // so `andorra remote share` would print a phantom id whose `unshare` can only ever miss.
+    let stored = share;
+    await changeConfigFile(directory, config => {
+        const shares = config.remote?.hosting?.shares ?? [];
+        const existing = shares.find(entry => entry.path === share.path);
+        if (existing) {
+            stored = existing;
+            return config;
+        }
+        if (shares.length >= 64)
+            throw new Error('This machine already shares the maximum number of folders.');
+        return { ...config, remote: { ...config.remote, hosting: { ...config.remote?.hosting, shares: [...shares, share] } } };
+    });
+    return stored;
+}
+export async function removeRemoteShare(shareId, directory = configDirectory()) {
+    let removed = false;
+    await changeConfigFile(directory, config => {
+        const shares = config.remote?.hosting?.shares ?? [];
+        const kept = shares.filter(share => share.id !== shareId);
+        removed = kept.length !== shares.length;
+        return removed ? { ...config, remote: { ...config.remote, hosting: { ...config.remote?.hosting, shares: kept } } } : config;
+    });
+    return removed;
+}
+/** The listener's persisted port, written once when the OS assigned it. */
+export async function persistRemotePort(port, directory = configDirectory()) {
+    await changeConfigFile(directory, config => {
+        if (config.remote?.hosting?.port === port)
+            return config;
+        return { ...config, remote: { ...config.remote, hosting: { ...config.remote?.hosting, port } } };
+    });
+}
+/** Give this installation its stable 128-bit identity, creating it on first serve. */
+export async function ensureRemoteInstallId(directory = configDirectory()) {
+    const current = await loadConfig(directory);
+    if (current.remote?.hosting?.installId)
+        return current.remote.hosting.installId;
+    const installId = randomBytes(16).toString('hex');
+    await changeConfigFile(directory, config => {
+        if (config.remote?.hosting?.installId)
+            return config;
+        return { ...config, remote: { ...config.remote, hosting: { ...config.remote?.hosting, installId } } };
+    });
+    return installId;
+}
+export async function setRemoteTransport(transport, directory = configDirectory()) {
+    await changeConfigFile(directory, config => {
+        if (config.remote?.hosting?.transport === transport)
+            return config;
+        return { ...config, remote: { ...config.remote, hosting: { ...config.remote?.hosting, transport } } };
+    });
+}
+export function newWorkspaceId() {
+    return `ws-${randomBytes(6).toString('hex')}`;
+}
+export async function addRemoteWorkspace(workspace, directory = configDirectory()) {
+    await changeConfigFile(directory, config => {
+        const workspaces = config.remote?.workspaces ?? [];
+        if (workspaces.length >= 32)
+            throw new Error('This machine already pairs with the maximum number of workspaces.');
+        return { ...config, remote: { ...config.remote, workspaces: [...workspaces, workspace] } };
+    });
+}
+export async function removeRemoteWorkspace(workspaceId, directory = configDirectory()) {
+    let removed = false;
+    await changeConfigFile(directory, config => {
+        const workspaces = config.remote?.workspaces ?? [];
+        const kept = workspaces.filter(workspace => workspace.id !== workspaceId);
+        removed = kept.length !== workspaces.length;
+        return removed ? { ...config, remote: { ...config.remote, workspaces: kept } } : config;
+    });
+    return removed;
+}
+export async function updateRemoteWorkspace(workspaceId, changes, directory = configDirectory()) {
+    let updated;
+    await changeConfigFile(directory, config => {
+        const workspaces = config.remote?.workspaces ?? [];
+        const current = workspaces.find(workspace => workspace.id === workspaceId);
+        if (!current)
+            return config;
+        const next = {
+            ...current,
+            ...(changes.nickname !== undefined ? { nickname: changes.nickname } : {}),
+        };
+        if (changes.host === null)
+            delete next.host;
+        else if (changes.host !== undefined)
+            next.host = changes.host;
+        updated = next;
+        return { ...config, remote: { ...config.remote, workspaces: workspaces.map(workspace => workspace.id === workspaceId ? next : workspace) } };
+    });
+    return updated;
+}
+/**
+ * The project registry: list, add (idempotent by path), remove.
+ *
+ * The caller resolves realpath before adding, so registry entries are canonical paths and two
+ * spellings of one folder cannot both appear.
+ */
+export async function addProjectEntry(path, options = {}) {
+    const directory = options.directory ?? configDirectory();
+    const name = typeof options.name === 'string' && options.name.trim() ? options.name.trim().slice(0, 100) : undefined;
+    await changeConfigFile(directory, config => {
+        const projects = config.projects ?? [];
+        if (projects.some(project => project.path === path))
+            return config;
+        if (projects.length >= 256)
+            throw new Error('The project registry is full.');
+        return { ...config, projects: [...projects, { path, ...(name ? { name } : {}), addedAt: new Date().toISOString() }] };
+    });
+}
+export async function removeProjectEntry(path, directory = configDirectory()) {
+    let removed = false;
+    await changeConfigFile(directory, config => {
+        const projects = config.projects ?? [];
+        const kept = projects.filter(project => project.path !== path);
+        removed = kept.length !== projects.length;
+        return removed ? { ...config, projects: kept } : config;
+    });
+    return removed;
+}

package/dist/src/remote/roots.d.ts

@@ -0,0 +1,29 @@
+import type { Config } from '../config.js';
+/**
+ * The folders a peer may see, and the only identifiers it ever learns.
+ *
+ * v1 exposes exactly two kinds: the installation's registered projects (shared by default — that
+ * is what "display the projects of that machine" means) and host-side explicit shares. Home and
+ * drive letters are never roots; the host adds a folder as a share or it does not appear. A root
+ * is addressed by an opaque id (`proj-<hash>` / the share's stored id), never by its absolute
+ * path, so the browse API cannot be probed for the shape of the host's disk.
+ *
+ * Entries that no longer resolve — a deleted project folder, an unmounted volume — are dropped
+ * rather than erroring, so one stale registry entry cannot break the whole listing.
+ */
+export interface AuthorizedRoot {
+    id: string;
+    label: string;
+    path: string;
+    kind: 'project' | 'share';
+}
+/**
+ * Stable id from the realpath: the same folder keeps its id across restarts and renames.
+ *
+ * Case is folded on Windows only, whose filesystems treat one directory's spellings as one folder
+ * (and where a drive letter arrives in either case). On POSIX, `/work/Foo` and `/work/foo` are two
+ * distinct folders at once — folding would hand them one id, and browsing the second would open
+ * the first's contents.
+ */
+export declare function projectRootId(realPath: string): string;
+export declare function authorizedRoots(config: Config): Promise<AuthorizedRoot[]>;