@namzu/sdk 46.0.0 → 48.1.0

package/dist/peers/address.js

@@ -0,0 +1,52 @@
+/**
+ * Peer addresses are URIs so a later cross-machine transport can be added
+ * without redesigning the registry or the protocol: `uds:<path>` and
+ * `pipe:<name>` today, `a2a:https://…` later (design §1.1). Only the two
+ * local schemes are ever SERVED or DIALED by this package; `a2a:` addresses
+ * are recognised so a reader can tell them apart, not connected to.
+ *
+ * @experimental
+ */
+import { join } from 'node:path';
+import { peerSocketFileName } from './dir.js';
+export class PeerAddressError extends Error {
+    name = 'PeerAddressError';
+}
+/** The `uds:<path>` address for a session's socket inside a hardened runtime directory. */
+export function udsPeerAddress(runtimeDir, sessionId) {
+    return `uds:${join(runtimeDir, peerSocketFileName(sessionId))}`;
+}
+/**
+ * The `pipe:<name>` address for a session's Windows named pipe.
+ *
+ * `<name>` is the full pipe path Node's `net` module dials directly
+ * (`\\.\pipe\namzu-<uid-hash>-<session-short>`, design §1.1) — coded here for
+ * completeness; this package does not run its tests on win32, so the shape
+ * is reviewed rather than exercised.
+ */
+export function pipePeerAddress(uidHash, sessionShort) {
+    return `pipe:\\\\.\\pipe\\namzu-${uidHash}-${sessionShort}`;
+}
+/** Parse a peer address URI. Throws {@link PeerAddressError} on an unrecognised or empty scheme. */
+export function parsePeerAddress(address) {
+    if (address.startsWith('uds:')) {
+        const path = address.slice('uds:'.length);
+        if (path.length === 0)
+            throw new PeerAddressError(`Empty uds: address: ${address}`);
+        return { scheme: 'uds', path };
+    }
+    if (address.startsWith('pipe:')) {
+        const path = address.slice('pipe:'.length);
+        if (path.length === 0)
+            throw new PeerAddressError(`Empty pipe: address: ${address}`);
+        return { scheme: 'pipe', path };
+    }
+    if (address.startsWith('a2a:')) {
+        const url = address.slice('a2a:'.length);
+        if (url.length === 0)
+            throw new PeerAddressError(`Empty a2a: address: ${address}`);
+        return { scheme: 'a2a', url };
+    }
+    throw new PeerAddressError(`Unrecognised peer address scheme: ${address}`);
+}
+//# sourceMappingURL=address.js.map

package/dist/peers/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../src/peers/address.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAO7C,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACxB,IAAI,GAAG,kBAAkB,CAAA;CAC3C;AAED,2FAA2F;AAC3F,MAAM,UAAU,cAAc,CAAC,UAAkB,EAAE,SAAiB;IACnE,OAAO,OAAO,IAAI,CAAC,UAAU,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC,EAAE,CAAA;AAChE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,YAAoB;IACpE,OAAO,2BAA2B,OAAO,IAAI,YAAY,EAAE,CAAA;AAC5D,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC/C,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACzC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,gBAAgB,CAAC,uBAAuB,OAAO,EAAE,CAAC,CAAA;QACnF,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAC/B,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,gBAAgB,CAAC,wBAAwB,OAAO,EAAE,CAAC,CAAA;QACpF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;IAChC,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACxC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,gBAAgB,CAAC,uBAAuB,OAAO,EAAE,CAAC,CAAA;QAClF,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;IAC9B,CAAC;IACD,MAAM,IAAI,gBAAgB,CAAC,qCAAqC,OAAO,EAAE,CAAC,CAAA;AAC3E,CAAC"}

package/dist/peers/client.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A client for one connection of `namzu-peer/1`: connect, write one request
+ * line, read one response line, close. Mirrors the shape of this
+ * repository's other local control clients (`queryRunner` in
+ * `packages/cli/src/integrations/resident/runner-control.ts`,
+ * `callEndpoint` in `packages/cli/src/schedule/daemon/endpoint.ts`): an
+ * authenticated response PROVES responsiveness, and its absence never proves
+ * the peer is dead — only that this attempt could not reach it.
+ *
+ * @experimental
+ */
+import { type DeliverRequest, type DeliverResponse, type NoticeRequest, type NoticeResponse, type PingResponse, type SubscribeIdleRequest, type SubscribeIdleResponse } from './protocol.js';
+import type { PeerRecord } from './record.js';
+export declare class PeerClientError extends Error {
+    readonly name = "PeerClientError";
+}
+/** An authenticated reply proves responsiveness; every other outcome names why none arrived. */
+export type PeerClientResult<T> = ({
+    readonly kind: 'responded';
+} & T) | {
+    readonly kind: 'unreachable';
+    readonly reason: string;
+};
+export interface PeerClientOptions {
+    /** Default 2000ms. */
+    readonly timeoutMs?: number;
+}
+/**
+ * `ping`, `deliver`, `subscribe_idle` and `notice` over `namzu-peer/1`.
+ *
+ * `deliver`/`subscribeIdle`/`notice` read the RECIPIENT's token from the
+ * `PeerRecord` passed in — the wire's token is always the recipient's own,
+ * asserted by the caller and verified by the server (design §1.1, §1.3).
+ * `ping` takes a bare address and carries no token; see the file header for
+ * why.
+ */
+export declare class PeerClient {
+    private readonly timeoutMs;
+    constructor(options?: PeerClientOptions);
+    ping(address: string, timeoutMs?: number): Promise<PeerClientResult<PingResponse>>;
+    deliver(record: Pick<PeerRecord, 'address' | 'token'>, message: Omit<DeliverRequest, 'protocol' | 'op' | 'token'>): Promise<PeerClientResult<DeliverResponse>>;
+    subscribeIdle(record: Pick<PeerRecord, 'address' | 'token'>, message: Omit<SubscribeIdleRequest, 'protocol' | 'op' | 'token'>): Promise<PeerClientResult<SubscribeIdleResponse>>;
+    notice(record: Pick<PeerRecord, 'address' | 'token'>, message: Omit<NoticeRequest, 'protocol' | 'op' | 'token'>): Promise<PeerClientResult<NoticeResponse>>;
+}
+/** A bare liveness probe: `true` iff an unauthenticated `ping` answers within `timeoutMs`. Used by `listLivePeers`. */
+export declare function pingPeer(address: string, timeoutMs?: number): Promise<boolean>;
+//# sourceMappingURL=client.d.ts.map

package/dist/peers/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/peers/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,eAAe,EAGpB,KAAK,aAAa,EAClB,KAAK,cAAc,EAInB,KAAK,YAAY,EAEjB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAE1B,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAI7C,qBAAa,eAAgB,SAAQ,KAAK;IACzC,SAAkB,IAAI,qBAAoB;CAC1C;AAED,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC3B,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAAG,CAAC,CAAC,GACpC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAsE5D,MAAM,WAAW,iBAAiB;IACjC,sBAAsB;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;gBAEtB,OAAO,GAAE,iBAAsB;IAI3C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,SAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAK1F,OAAO,CACN,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,GAAG,OAAO,CAAC,EAC7C,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,GACxD,OAAO,CAAC,gBAAgB,CAAC,eAAe,CAAC,CAAC;IAe7C,aAAa,CACZ,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,GAAG,OAAO,CAAC,EAC7C,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,GAC9D,OAAO,CAAC,gBAAgB,CAAC,qBAAqB,CAAC,CAAC;IAenD,MAAM,CACL,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,GAAG,OAAO,CAAC,EAC7C,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,GACvD,OAAO,CAAC,gBAAgB,CAAC,cAAc,CAAC,CAAC;CAc5C;AAED,uHAAuH;AACvH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,SAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ1F"}

package/dist/peers/client.js

@@ -0,0 +1,132 @@
+/**
+ * A client for one connection of `namzu-peer/1`: connect, write one request
+ * line, read one response line, close. Mirrors the shape of this
+ * repository's other local control clients (`queryRunner` in
+ * `packages/cli/src/integrations/resident/runner-control.ts`,
+ * `callEndpoint` in `packages/cli/src/schedule/daemon/endpoint.ts`): an
+ * authenticated response PROVES responsiveness, and its absence never proves
+ * the peer is dead — only that this attempt could not reach it.
+ *
+ * @experimental
+ */
+import { createConnection } from 'node:net';
+import { parsePeerAddress } from './address.js';
+import { DeliverResponseSchema, MAX_PEER_REQUEST_BYTES, NoticeResponseSchema, PEER_PROTOCOL_VERSION, PingResponseSchema, SubscribeIdleResponseSchema, } from './protocol.js';
+const DEFAULT_TIMEOUT_MS = 2_000;
+export class PeerClientError extends Error {
+    name = 'PeerClientError';
+}
+function connectPath(address) {
+    const parsed = parsePeerAddress(address);
+    if (parsed.scheme === 'a2a') {
+        throw new PeerClientError(`PeerClient cannot dial an a2a: address directly: ${address}`);
+    }
+    return parsed.path;
+}
+/** One request, one response, one connection. */
+function sendPeerRequest(address, request, parseResponse, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(result);
+        };
+        const unreachable = (error) => finish({
+            kind: 'unreachable',
+            reason: error instanceof Error ? error.message : String(error),
+        });
+        const timer = setTimeout(() => unreachable(new Error('Peer request timed out.')), timeoutMs);
+        let path;
+        try {
+            path = connectPath(address);
+        }
+        catch (error) {
+            clearTimeout(timer);
+            resolve({
+                kind: 'unreachable',
+                reason: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        const socket = createConnection({ path });
+        let buffered = Buffer.alloc(0);
+        socket.once('error', unreachable);
+        socket.once('close', () => unreachable(new Error('Peer connection closed before a response arrived.')));
+        socket.once('connect', () => {
+            socket.write(`${JSON.stringify(request)}\n`);
+        });
+        socket.on('data', (chunk) => {
+            if (buffered.length + chunk.length > MAX_PEER_REQUEST_BYTES) {
+                unreachable(new Error('Peer response exceeded the size limit.'));
+                return;
+            }
+            buffered = Buffer.concat([buffered, chunk]);
+            const newline = buffered.indexOf(10);
+            if (newline < 0)
+                return;
+            try {
+                const parsed = JSON.parse(buffered.subarray(0, newline).toString('utf8'));
+                finish({ kind: 'responded', ...parseResponse(parsed) });
+            }
+            catch (error) {
+                unreachable(error);
+            }
+        });
+    });
+}
+/**
+ * `ping`, `deliver`, `subscribe_idle` and `notice` over `namzu-peer/1`.
+ *
+ * `deliver`/`subscribeIdle`/`notice` read the RECIPIENT's token from the
+ * `PeerRecord` passed in — the wire's token is always the recipient's own,
+ * asserted by the caller and verified by the server (design §1.1, §1.3).
+ * `ping` takes a bare address and carries no token; see the file header for
+ * why.
+ */
+export class PeerClient {
+    timeoutMs;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    ping(address, timeoutMs = this.timeoutMs) {
+        const request = { protocol: PEER_PROTOCOL_VERSION, op: 'ping' };
+        return sendPeerRequest(address, request, (value) => PingResponseSchema.parse(value), timeoutMs);
+    }
+    deliver(record, message) {
+        const request = {
+            protocol: PEER_PROTOCOL_VERSION,
+            op: 'deliver',
+            token: record.token,
+            ...message,
+        };
+        return sendPeerRequest(record.address, request, (value) => DeliverResponseSchema.parse(value), this.timeoutMs);
+    }
+    subscribeIdle(record, message) {
+        const request = {
+            protocol: PEER_PROTOCOL_VERSION,
+            op: 'subscribe_idle',
+            token: record.token,
+            ...message,
+        };
+        return sendPeerRequest(record.address, request, (value) => SubscribeIdleResponseSchema.parse(value), this.timeoutMs);
+    }
+    notice(record, message) {
+        const request = {
+            protocol: PEER_PROTOCOL_VERSION,
+            op: 'notice',
+            token: record.token,
+            ...message,
+        };
+        return sendPeerRequest(record.address, request, (value) => NoticeResponseSchema.parse(value), this.timeoutMs);
+    }
+}
+/** A bare liveness probe: `true` iff an unauthenticated `ping` answers within `timeoutMs`. Used by `listLivePeers`. */
+export function pingPeer(address, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const request = { protocol: PEER_PROTOCOL_VERSION, op: 'ping' };
+    return sendPeerRequest(address, request, (value) => PingResponseSchema.parse(value), timeoutMs).then((result) => result.kind === 'responded');
+}
+//# sourceMappingURL=client.js.map

package/dist/peers/client.js.map

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

package/dist/peers/dir.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The private per-user runtime directory peer sockets and the live-session
+ * registry live in.
+ *
+ * Boundary = the OS user (design: cross-session messaging §1.1). Any process
+ * of the same user can already read the user's files, so the directory only
+ * has to keep OTHER users and the network out, and every candidate is
+ * checked the same way: created 0700, refused if it turns out to be a
+ * symlink, and — on POSIX — verified by `lstat` to really be owned by this
+ * uid and to carry no group/other permission.
+ *
+ * The SDK cannot depend on the CLI's `ensurePrivateStateDirectory`
+ * (`packages/cli/src/integrations/state/private-directory.ts`, which also
+ * tightens a Windows ACL); {@link hardenPeerRuntimeDir} is the small subset
+ * of that contract this module needs, reimplemented here so the dependency
+ * direction (`sdk` never imports `cli`) holds. A caller with its own
+ * directory-hardening policy may supply `hardenDirectory` instead.
+ *
+ * @experimental
+ */
+export declare class PeerDirectoryError extends Error {
+    readonly name = "PeerDirectoryError";
+}
+/**
+ * Session ids are UUIDv7 (`generateSessionId`, `utils/id.ts`): 36 characters.
+ * `.sock` is the longest suffix {@link peerSocketFileName} ever appends, so
+ * this is the longest socket filename the peers module creates — the figure
+ * {@link resolvePeerRuntimeDir} subtracts from the platform's
+ * `sockaddr_un.sun_path` limit before choosing a runtime directory.
+ */
+export declare const LONGEST_PEER_SOCKET_FILE_NAME_LENGTH: number;
+/** The socket filename for one session, placed directly inside the runtime directory. */
+export declare function peerSocketFileName(sessionId: string): string;
+/** Harden one directory in place; see {@link hardenPeerRuntimeDir}. Injectable for tests. */
+export type HardenPeerDirectory = (path: string, uid: number | undefined) => void;
+/**
+ * Create (or re-verify) a private directory for peer sockets and registry
+ * records.
+ *
+ * Existing directories are tightened (`chmod`) on POSIX, then re-checked by
+ * `lstat` — tightening a directory this uid does not own would fail, which is
+ * exactly the outcome wanted, so the check afterward is the real gate. Skips
+ * the POSIX-only steps on win32, where `chmod` only toggles the read-only
+ * attribute and there is no uid to compare (`process.getuid` does not exist).
+ */
+export declare function hardenPeerRuntimeDir(path: string, uid: number | undefined): void;
+export interface ResolvePeerRuntimeDirOptions {
+    readonly env: NodeJS.ProcessEnv;
+    readonly namzuHome: string;
+    /** `undefined` models a platform with no uid (win32; `process.getuid` does not exist there). */
+    readonly uid: number | undefined;
+    /** Default `process.platform`; override for tests. */
+    readonly platform?: NodeJS.Platform;
+    /** Default `os.tmpdir()`; override for tests, matching `TempRootOptions.tmpdir` in `session/paths.ts`. */
+    readonly tmpDir?: string;
+    /** Overrides {@link hardenPeerRuntimeDir}; primarily for tests that need to fabricate a failure. */
+    readonly hardenDirectory?: HardenPeerDirectory;
+}
+export interface PeerRuntimeDir {
+    /** The directory sockets are created in. */
+    readonly path: string;
+    /** `<path>/sessions`, holding one registry record per live session. */
+    readonly sessionsDir: string;
+}
+/**
+ * Choose and harden the per-session peer runtime directory.
+ *
+ * Candidates, in order: `$XDG_RUNTIME_DIR/namzu`, `$NAMZU_HOME/run`,
+ * `$TMPDIR/namzu-<uid>`. Every candidate whose resulting socket paths fit
+ * this platform's `sockaddr_un` limit is a length-eligible candidate; among
+ * those, the first that can actually be created and hardened 0700 (see
+ * {@link hardenPeerRuntimeDir}), along with its `sessions/` subdirectory, is
+ * the one used.
+ *
+ * Fitting the length budget and being hardenable are different failure
+ * modes, so they get different handling. A candidate that is too long for
+ * this platform's socket path is never even attempted — trying it would
+ * only fail later, at `listen()`, with a less useful error. A candidate
+ * that DOES fit but cannot be hardened (owned by another uid, a symlink, a
+ * permission this process cannot chmod away) is skipped in favour of the
+ * next length-eligible candidate rather than failing the whole call: a
+ * hostile or merely misconfigured `$XDG_RUNTIME_DIR` should not deny peer
+ * messaging to a session that could perfectly well fall back to
+ * `$NAMZU_HOME/run`. Only when every length-eligible candidate has failed to
+ * harden does this throw, naming each one and why.
+ */
+export declare function resolvePeerRuntimeDir(options: ResolvePeerRuntimeDirOptions): PeerRuntimeDir;
+//# sourceMappingURL=dir.d.ts.map

package/dist/peers/dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dir.d.ts","sourceRoot":"","sources":["../../src/peers/dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,wBAAuB;CAC7C;AAID;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC,QAAsB,CAAA;AAEvE,yFAAyF;AACzF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5D;AAqBD,6FAA6F;AAC7F,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAA;AAEjF;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAsBhF;AAED,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,gGAAgG;IAChG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAA;IACnC,0GAA0G;IAC1G,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,oGAAoG;IACpG,QAAQ,CAAC,eAAe,CAAC,EAAE,mBAAmB,CAAA;CAC9C;AAED,MAAM,WAAW,cAAc;IAC9B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC5B;AAUD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,cAAc,CAwB3F"}

package/dist/peers/dir.js

@@ -0,0 +1,139 @@
+/**
+ * The private per-user runtime directory peer sockets and the live-session
+ * registry live in.
+ *
+ * Boundary = the OS user (design: cross-session messaging §1.1). Any process
+ * of the same user can already read the user's files, so the directory only
+ * has to keep OTHER users and the network out, and every candidate is
+ * checked the same way: created 0700, refused if it turns out to be a
+ * symlink, and — on POSIX — verified by `lstat` to really be owned by this
+ * uid and to carry no group/other permission.
+ *
+ * The SDK cannot depend on the CLI's `ensurePrivateStateDirectory`
+ * (`packages/cli/src/integrations/state/private-directory.ts`, which also
+ * tightens a Windows ACL); {@link hardenPeerRuntimeDir} is the small subset
+ * of that contract this module needs, reimplemented here so the dependency
+ * direction (`sdk` never imports `cli`) holds. A caller with its own
+ * directory-hardening policy may supply `hardenDirectory` instead.
+ *
+ * @experimental
+ */
+import { chmodSync, lstatSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export class PeerDirectoryError extends Error {
+    name = 'PeerDirectoryError';
+}
+const PRIVATE_DIR_MODE = 0o700;
+/**
+ * Session ids are UUIDv7 (`generateSessionId`, `utils/id.ts`): 36 characters.
+ * `.sock` is the longest suffix {@link peerSocketFileName} ever appends, so
+ * this is the longest socket filename the peers module creates — the figure
+ * {@link resolvePeerRuntimeDir} subtracts from the platform's
+ * `sockaddr_un.sun_path` limit before choosing a runtime directory.
+ */
+export const LONGEST_PEER_SOCKET_FILE_NAME_LENGTH = 36 + '.sock'.length;
+/** The socket filename for one session, placed directly inside the runtime directory. */
+export function peerSocketFileName(sessionId) {
+    return `${sessionId}.sock`;
+}
+const DARWIN_SUN_PATH_LIMIT = 104;
+/** Linux, and every other POSIX platform this runs on. */
+const DEFAULT_SUN_PATH_LIMIT = 108;
+function platformSocketPathLimit(platform) {
+    return platform === 'darwin' ? DARWIN_SUN_PATH_LIMIT : DEFAULT_SUN_PATH_LIMIT;
+}
+/**
+ * Whether a socket file directly inside `dir` fits the platform's
+ * `sockaddr_un.sun_path`. Windows named pipes live in a virtual namespace,
+ * not the filesystem, so no directory ever fails this check there.
+ */
+function fitsSocketPath(dir, platform) {
+    if (platform === 'win32')
+        return true;
+    // +1 for the path separator joining `dir` to the socket filename.
+    return dir.length + 1 + LONGEST_PEER_SOCKET_FILE_NAME_LENGTH <= platformSocketPathLimit(platform);
+}
+/**
+ * Create (or re-verify) a private directory for peer sockets and registry
+ * records.
+ *
+ * Existing directories are tightened (`chmod`) on POSIX, then re-checked by
+ * `lstat` — tightening a directory this uid does not own would fail, which is
+ * exactly the outcome wanted, so the check afterward is the real gate. Skips
+ * the POSIX-only steps on win32, where `chmod` only toggles the read-only
+ * attribute and there is no uid to compare (`process.getuid` does not exist).
+ */
+export function hardenPeerRuntimeDir(path, uid) {
+    mkdirSync(path, { recursive: true, mode: PRIVATE_DIR_MODE });
+    const created = lstatSync(path);
+    if (created.isSymbolicLink()) {
+        throw new PeerDirectoryError(`Refusing peer runtime path ${path}: it is a symbolic link.`);
+    }
+    if (!created.isDirectory()) {
+        throw new PeerDirectoryError(`Refusing peer runtime path ${path}: it is not a directory.`);
+    }
+    if (process.platform === 'win32')
+        return;
+    chmodSync(path, PRIVATE_DIR_MODE);
+    const entry = lstatSync(path);
+    if (uid !== undefined && entry.uid !== uid) {
+        throw new PeerDirectoryError(`Refusing peer runtime path ${path}: it belongs to uid ${entry.uid}, not ${uid}.`);
+    }
+    if ((entry.mode & 0o777) !== PRIVATE_DIR_MODE) {
+        throw new PeerDirectoryError(`Refusing peer runtime path ${path}: mode ${(entry.mode & 0o777).toString(8)} is not 0700.`);
+    }
+}
+function peerRuntimeDirCandidates(options) {
+    const candidates = [];
+    if (options.env.XDG_RUNTIME_DIR)
+        candidates.push(join(options.env.XDG_RUNTIME_DIR, 'namzu'));
+    candidates.push(join(options.namzuHome, 'run'));
+    candidates.push(join(options.tmpDir ?? tmpdir(), `namzu-${options.uid ?? 'user'}`));
+    return candidates;
+}
+/**
+ * Choose and harden the per-session peer runtime directory.
+ *
+ * Candidates, in order: `$XDG_RUNTIME_DIR/namzu`, `$NAMZU_HOME/run`,
+ * `$TMPDIR/namzu-<uid>`. Every candidate whose resulting socket paths fit
+ * this platform's `sockaddr_un` limit is a length-eligible candidate; among
+ * those, the first that can actually be created and hardened 0700 (see
+ * {@link hardenPeerRuntimeDir}), along with its `sessions/` subdirectory, is
+ * the one used.
+ *
+ * Fitting the length budget and being hardenable are different failure
+ * modes, so they get different handling. A candidate that is too long for
+ * this platform's socket path is never even attempted — trying it would
+ * only fail later, at `listen()`, with a less useful error. A candidate
+ * that DOES fit but cannot be hardened (owned by another uid, a symlink, a
+ * permission this process cannot chmod away) is skipped in favour of the
+ * next length-eligible candidate rather than failing the whole call: a
+ * hostile or merely misconfigured `$XDG_RUNTIME_DIR` should not deny peer
+ * messaging to a session that could perfectly well fall back to
+ * `$NAMZU_HOME/run`. Only when every length-eligible candidate has failed to
+ * harden does this throw, naming each one and why.
+ */
+export function resolvePeerRuntimeDir(options) {
+    const platform = options.platform ?? process.platform;
+    const harden = options.hardenDirectory ?? hardenPeerRuntimeDir;
+    const candidates = peerRuntimeDirCandidates(options);
+    const fitting = candidates.filter((candidate) => fitsSocketPath(candidate, platform));
+    if (fitting.length === 0) {
+        throw new PeerDirectoryError(`No candidate peer runtime directory fits this platform's socket path limit (${platformSocketPathLimit(platform)} bytes): ${candidates.join(', ')}`);
+    }
+    const failures = [];
+    for (const candidate of fitting) {
+        try {
+            harden(candidate, options.uid);
+            const sessionsDir = join(candidate, 'sessions');
+            harden(sessionsDir, options.uid);
+            return { path: candidate, sessionsDir };
+        }
+        catch (error) {
+            failures.push(`${candidate}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    throw new PeerDirectoryError(`No candidate peer runtime directory could be hardened:\n${failures.join('\n')}`);
+}
+//# sourceMappingURL=dir.js.map

package/dist/peers/dir.js.map

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

package/dist/peers/endpoint.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The `namzu-peer/1` server: one UDS path (POSIX) or named pipe (win32) per
+ * session, newline-delimited JSON framing, a closed op set (design §1.1,
+ * §1.3). Mirrors the shape of this repository's other local control
+ * endpoints (`startEndpoint` in
+ * `packages/cli/src/schedule/daemon/endpoint.ts`, `createRunnerControlServer`
+ * in `packages/cli/src/integrations/resident/runner-control.ts`): a total
+ * read deadline per connection (not an inactivity timer a slow sender can
+ * reset), a bounded connection count, and a destroyed socket rather than an
+ * error response for anything malformed — request bytes and tokens are
+ * never logged, so there is nothing to say about a bad request beyond
+ * closing the connection.
+ *
+ * This package tests only the POSIX (UDS) path; the win32 branch is written
+ * and reviewed, not exercised, since this environment cannot run a win32
+ * test.
+ *
+ * @experimental
+ */
+import { type Logger } from '../utils/logger.js';
+import { type DeliverRequest, type DeliverResponse, type NoticeRequest, type PeerFrom, type PeerSessionState, type SubscribeIdleRequest, type SubscribeIdleResponse } from './protocol.js';
+export declare class PeerEndpointError extends Error {
+    readonly name = "PeerEndpointError";
+}
+export interface CreatePeerEndpointOptions {
+    readonly address: string;
+    /** This session's own token; compared against every request but `ping` with `timingSafeEqual`. */
+    readonly token: string;
+    /** `undefined` models a platform with no uid (win32). Gates the stale-socket removal below. */
+    readonly uid?: number;
+    /** Answered verbatim on every `ping`; `ping` has no other way to learn the current state. */
+    readonly getState: () => PeerSessionState;
+    /**
+     * Directory holding the live-session registry (`sessions/<id>.json`),
+     * used by the DEFAULT `verifySender`. Not read at all if `verifySender`
+     * is supplied.
+     */
+    readonly sessionsDir?: string;
+    readonly onDeliver: (request: DeliverRequest) => Promise<DeliverResponse> | DeliverResponse;
+    readonly onSubscribeIdle: (request: SubscribeIdleRequest) => Promise<SubscribeIdleResponse> | SubscribeIdleResponse;
+    readonly onNotice: (request: NoticeRequest) => Promise<void> | void;
+    /**
+     * Verify a sender's asserted identity, and return the identity the
+     * recipient should actually use — which is never simply `from` handed
+     * back, because a value the recipient uses for a decision (`mode`,
+     * `kind`) or shows the operator (`name`, `ref`) must come from something
+     * the sender does not control on this one connection. `false` refuses.
+     *
+     * Default ({@link defaultVerifySender}): the sender's registry record
+     * exists, is live ({@link isPeerRecordLive}), its `address` equals
+     * `from.address`, and its `permissionMode`/`kind` equal `from.mode`/
+     * `from.kind` (design §1.3) — so a process cannot claim to be a session
+     * it does not own, and a session cannot claim a mode or kind other than
+     * the one it registered. The identity returned on success is built
+     * entirely from the record: `name` is the record's own display name
+     * (`title`, or the last path segment of `cwd` when unset), never the
+     * wire's `from.name`.
+     */
+    readonly verifySender?: (from: PeerFrom) => Promise<PeerFrom | false> | PeerFrom | false;
+    /** Default 2000ms; override for tests so a deadline test does not have to wait 2 real seconds. */
+    readonly readDeadlineMs?: number;
+    /** Default 16; override for tests. */
+    readonly maxConnections?: number;
+    /** Default 64 KiB; override for tests. */
+    readonly maxRequestBytes?: number;
+    /** Default 500ms; the timeout the default `verifySender`'s liveness ping uses. */
+    readonly livenessPingTimeoutMs?: number;
+    /** Default {@link MAX_OUTSTANDING_PEERS}; override for tests. */
+    readonly maxOutstandingPeers?: number;
+    /** Default {@link MAX_OUTSTANDING_PER_PEER}; override for tests. */
+    readonly maxOutstandingPerPeer?: number;
+    /** Default {@link OUTSTANDING_EXPIRY_MS}; override for tests. */
+    readonly outstandingExpiryMs?: number;
+    /** Default `Date.now`; injectable so an expiry test does not have to wait 24 real hours. */
+    readonly now?: () => number;
+    /**
+     * Discards when absent ({@link resolveLogger}). Used only to warn, at
+     * most once per peer per minute, when the outstanding-delivery or
+     * outstanding-subscription table drops a registration at the per-peer
+     * cap or evicts one to stay under the peer-count cap — never for
+     * anything else this endpoint does, and never with message content.
+     */
+    readonly logger?: Logger;
+}
+export interface PeerEndpoint {
+    readonly address: string;
+    /** Refuse new connections and destroy remaining sockets before resolving. */
+    close(): Promise<void>;
+    /**
+     * Record that THIS session sent a `deliver` to `peerSessionId` and so
+     * expects a `delivery` notice back about it. A `notice` naming a peer
+     * with no outstanding delivery is refused (§1.3): a session that never
+     * dealt with this recipient cannot manufacture an outcome for a message
+     * that was never sent. Counted, not boolean — several messages to the
+     * same peer may be outstanding at once, and each accepted notice
+     * consumes exactly one. Bounded and expiring
+     * ({@link MAX_OUTSTANDING_PEERS} distinct peers, {@link
+     * MAX_OUTSTANDING_PER_PEER} per peer, {@link OUTSTANDING_EXPIRY_MS}
+     * idle), so a peer that never answers cannot pin memory forever and a
+     * session cannot be driven to register unbounded distinct peer ids.
+     */
+    registerOutstandingDelivery(peerSessionId: string): void;
+    /**
+     * Record that THIS session subscribed (directly, or via
+     * `deliver.subscribeIdle`) to `peerSessionId`'s idle/exit notice. An
+     * `idle`/`exited` notice naming a peer with no outstanding subscription
+     * is refused, the same reasoning as {@link registerOutstandingDelivery},
+     * with the same bound and expiry.
+     */
+    registerOutstandingSubscription(peerSessionId: string): void;
+}
+/**
+ * Distinct peer sessions an endpoint's outstanding-delivery or
+ * outstanding-subscription table tracks at once, before the oldest is
+ * evicted to make room. A session that talks to hundreds of distinct peers
+ * without ever hearing back from most of them is already an anomaly this
+ * table should not have to hold unbounded memory for.
+ */
+export declare const MAX_OUTSTANDING_PEERS = 256;
+/**
+ * Outstanding relationships tracked for any ONE peer at once, before further
+ * registrations for that same peer stop increasing the count. Generous
+ * enough for many messages or resubscriptions in flight to a single busy
+ * peer; still a bound, so one peer cannot itself grow this table's memory
+ * without limit by being registered against repeatedly.
+ */
+export declare const MAX_OUTSTANDING_PER_PEER = 64;
+/**
+ * How long an outstanding delivery or subscription is honoured with no
+ * activity before it is swept away on its own, matching the design's
+ * `notify_when_idle` subscription expiry (§1.7): a peer that never answers —
+ * crashed, or simply never will — must not pin memory forever.
+ */
+export declare const OUTSTANDING_EXPIRY_MS: number;
+/**
+ * Start serving `namzu-peer/1` on `options.address`.
+ *
+ * The four business-decision callbacks (`onDeliver`, `onSubscribeIdle`,
+ * `onNotice`, and the default-overriding `verifySender`) decide outcomes;
+ * this function owns only the transport: framing, the size/connection/
+ * deadline limits, the closed op set, and token comparison.
+ */
+export declare function createPeerEndpoint(options: CreatePeerEndpointOptions): Promise<PeerEndpoint>;
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/peers/endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../../src/peers/endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,oBAAoB,CAAA;AAG/D,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,eAAe,EAGpB,KAAK,aAAa,EAElB,KAAK,QAAQ,EAEb,KAAK,gBAAgB,EAErB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,MAAM,eAAe,CAAA;AAItB,qBAAa,iBAAkB,SAAQ,KAAK;IAC3C,SAAkB,IAAI,uBAAsB;CAC5C;AAED,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,kGAAkG;IAClG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,+FAA+F;IAC/F,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,MAAM,gBAAgB,CAAA;IACzC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAA;IAC3F,QAAQ,CAAC,eAAe,EAAE,CACzB,OAAO,EAAE,oBAAoB,KACzB,OAAO,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAAA;IAC3D,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACnE;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC,GAAG,QAAQ,GAAG,KAAK,CAAA;IACxF,kGAAkG;IAClG,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,sCAAsC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,kFAAkF;IAClF,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAA;IACvC,iEAAiE;IACjE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,oEAAoE;IACpE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAA;IACvC,iEAAiE;IACjE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,4FAA4F;IAC5F,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,6EAA6E;IAC7E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB;;;;;;;;;;;;OAYG;IACH,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IACxD;;;;;;OAMG;IACH,+BAA+B,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5D;AAyCD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAsB,CAAA;AAqJxD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACvC,OAAO,EAAE,yBAAyB,GAChC,OAAO,CAAC,YAAY,CAAC,CAwMvB"}