appduct 0.9.0

package/dist/daemon/timers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.d.ts","sourceRoot":"","sources":["../../src/daemon/timers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAE5D,MAAM,MAAM,QAAQ,GAAG;IACrB,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,WAAW,CAAC;IAC9D,YAAY,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;IAC5C,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,cAAc,CAAC;IAClE,aAAa,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;CACjD,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,QAK1B,CAAC"}

package/dist/daemon/timers.js

@@ -0,0 +1,12 @@
+/**
+ * Injectable timer seam (LOOP.md: "use injectable clock/timer seams for tests"). Every daemon
+ * module that schedules a TTL/grace/pre-claim/keepalive timer takes a {@link TimerFns} so tests
+ * can substitute an implementation that fires deterministically instead of waiting on real wall
+ * time, and so every timer this package creates can be traced back to a single seam for cleanup.
+ */
+export const systemTimers = {
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+    setInterval: (callback, ms) => setInterval(callback, ms),
+    clearInterval: (handle) => clearInterval(handle),
+};

package/dist/daemon/tls.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Host key loading and leaf-certificate minting (ARCHITECTURE.md §3, §8). Reuses
+ * `host-certificate.ts` for the actual X.509 generation; this module
+ * owns key-file hygiene (refusing over-permissive key files) and re-minting the leaf when
+ * the advertised address changes so the certificate's SAN stays valid.
+ *
+ * The SPKI pin is derived from the key's public key alone (`spki-pin.ts`), so it never changes
+ * across re-mints — only the certificate's SAN entries do.
+ *
+ * Opt-in hardening, dev-mode zero-config bootstrap: a *missing* key file is no longer fatal.
+ * `createTlsManager` auto-generates one (same material/hygiene as `appduct keygen`, via
+ * `key-material.ts`) so a first-time `appduct daemon` needs no manual keygen step, and reports
+ * the new key's SPKI fingerprint through the optional `warn` callback. An existing key with bad
+ * permissions is still refused outright — auto-generation only fills the *missing* case, it never
+ * silently replaces a key that's already there.
+ */
+import type { AgentEndpoint } from "@appduct/shared";
+import type { AdvertisedAddress } from "./address.js";
+export declare class HostKeyError extends Error {
+    constructor(message: string);
+}
+/** Reports informational (non-error) messages, e.g. the fingerprint of an auto-generated key.
+ * Deliberately the same shape as `ConfigWarnFn` (`config.ts`) so callers can pass the same
+ * function through without an adapter. */
+export type TlsWarnFn = (message: string) => void;
+/** Refuses a key file that is group/world-readable. Missing files are handled by the caller
+ * (`loadOrGenerateHostKeyPem`), which auto-generates instead of throwing. */
+export declare const loadHostKeyPem: (keyPath: string) => Promise<string>;
+/**
+ * Loads the host key at `keyPath`, generating one in its place if none exists yet (dev-mode
+ * zero-config bootstrap). Only the ENOENT case auto-generates: any other `stat`/`readFile` failure
+ * (including bad permissions) still propagates as before, so a deliberately hardened/misconfigured
+ * key file is never silently overwritten.
+ */
+export declare const loadOrGenerateHostKeyPem: (keyPath: string, warn?: TlsWarnFn) => Promise<string>;
+export type TlsMaterial = {
+    certPem: string;
+    keyPem: string;
+    spkiPin: string;
+    advertisedAddress: AdvertisedAddress;
+};
+export type TlsManager = {
+    /** Current cert/key material for the TLS listener. */
+    current: () => TlsMaterial;
+    /** Re-mints the leaf cert if the advertised address changed; returns the (possibly unchanged) material. */
+    refresh: (address?: AdvertisedAddress) => Promise<TlsMaterial>;
+    /** SPKI pin-set for `daemon.status`. Single-entry today (no key rotation in v2.0 — ARCHITECTURE.md §14). */
+    pinnedKeys: () => string[];
+};
+export type CreateTlsManagerOptions = {
+    keyPath: string;
+    detectAddress: () => AdvertisedAddress;
+    /** Reports the fingerprint when a missing key is auto-generated (dev-mode bootstrap). */
+    warn?: TlsWarnFn;
+};
+export declare const createTlsManager: (options: CreateTlsManagerOptions) => Promise<TlsManager>;
+export declare const toAgentEndpoint: (address: AdvertisedAddress, port: number) => AgentEndpoint;
+//# sourceMappingURL=tls.d.ts.map

package/dist/daemon/tls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tls.d.ts","sourceRoot":"","sources":["../../src/daemon/tls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAKrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED;;0CAE0C;AAC1C,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAElD;6EAC6E;AAC7E,eAAO,MAAM,cAAc,GAAU,SAAS,MAAM,KAAG,OAAO,CAAC,MAAM,CAWpE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAU,SAAS,MAAM,EAAE,OAAO,SAAS,KAAG,OAAO,CAAC,MAAM,CAiBhG,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,iBAAiB,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,sDAAsD;IACtD,OAAO,EAAE,MAAM,WAAW,CAAC;IAC3B,2GAA2G;IAC3G,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,iBAAiB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/D,4GAA4G;IAC5G,UAAU,EAAE,MAAM,MAAM,EAAE,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,iBAAiB,CAAC;IACvC,yFAAyF;IACzF,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAU,SAAS,uBAAuB,KAAG,OAAO,CAAC,UAAU,CAuB3F,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,SAAS,iBAAiB,EAAE,MAAM,MAAM,KAAG,aAE1E,CAAC"}

package/dist/daemon/tls.js

@@ -0,0 +1,79 @@
+/**
+ * Host key loading and leaf-certificate minting (ARCHITECTURE.md §3, §8). Reuses
+ * `host-certificate.ts` for the actual X.509 generation; this module
+ * owns key-file hygiene (refusing over-permissive key files) and re-minting the leaf when
+ * the advertised address changes so the certificate's SAN stays valid.
+ *
+ * The SPKI pin is derived from the key's public key alone (`spki-pin.ts`), so it never changes
+ * across re-mints — only the certificate's SAN entries do.
+ *
+ * Opt-in hardening, dev-mode zero-config bootstrap: a *missing* key file is no longer fatal.
+ * `createTlsManager` auto-generates one (same material/hygiene as `appduct keygen`, via
+ * `key-material.ts`) so a first-time `appduct daemon` needs no manual keygen step, and reports
+ * the new key's SPKI fingerprint through the optional `warn` callback. An existing key with bad
+ * permissions is still refused outright — auto-generation only fills the *missing* case, it never
+ * silently replaces a key that's already there.
+ */
+import { stat, readFile } from "node:fs/promises";
+import { generateHostCertificate } from "../host-certificate.js";
+import { generatePrivateKeyPem, writePrivateKeyAtomically } from "../key-material.js";
+import { getSpkiPinFromPrivateKeyPem } from "../spki-pin.js";
+export class HostKeyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HostKeyError";
+    }
+}
+/** Refuses a key file that is group/world-readable. Missing files are handled by the caller
+ * (`loadOrGenerateHostKeyPem`), which auto-generates instead of throwing. */
+export const loadHostKeyPem = async (keyPath) => {
+    const fileStat = await stat(keyPath);
+    if ((fileStat.mode & 0o077) !== 0) {
+        throw new HostKeyError(`Appduct host key at "${keyPath}" is group- or world-readable (mode ${(fileStat.mode & 0o777).toString(8)}). ` +
+            `Refusing to load it — run "chmod 600 ${keyPath}" or re-run "appduct keygen".`);
+    }
+    return readFile(keyPath, "utf8");
+};
+/**
+ * Loads the host key at `keyPath`, generating one in its place if none exists yet (dev-mode
+ * zero-config bootstrap). Only the ENOENT case auto-generates: any other `stat`/`readFile` failure
+ * (including bad permissions) still propagates as before, so a deliberately hardened/misconfigured
+ * key file is never silently overwritten.
+ */
+export const loadOrGenerateHostKeyPem = async (keyPath, warn) => {
+    try {
+        return await loadHostKeyPem(keyPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    const keyPem = generatePrivateKeyPem();
+    await writePrivateKeyAtomically(keyPath, keyPem);
+    warn?.(`Appduct: no host key found at "${keyPath}" — generated one (dev mode). ` +
+        `SPKI pin: ${getSpkiPinFromPrivateKeyPem(keyPem)}`);
+    return keyPem;
+};
+export const createTlsManager = async (options) => {
+    const keyPem = await loadOrGenerateHostKeyPem(options.keyPath, options.warn);
+    const mint = async (address) => {
+        const { certPem, spkiPin } = await generateHostCertificate(keyPem, address.address);
+        return { certPem, keyPem, spkiPin, advertisedAddress: address };
+    };
+    let material = await mint(options.detectAddress());
+    return {
+        current: () => material,
+        refresh: async (address) => {
+            const next = address ?? options.detectAddress();
+            if (next.address !== material.advertisedAddress.address || next.family !== material.advertisedAddress.family) {
+                material = await mint(next);
+            }
+            return material;
+        },
+        pinnedKeys: () => [material.spkiPin],
+    };
+};
+export const toAgentEndpoint = (address, port) => {
+    return { family: address.family, address: address.address, port };
+};

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+import type { CliError, CliErrorType } from "./cli/result-types.js";
+export declare class AppductCliError extends Error {
+    readonly type: CliErrorType;
+    readonly details?: unknown;
+    constructor(type: CliErrorType, message: string, details?: unknown);
+}
+export declare const usageError: (message: string, details?: unknown) => AppductCliError;
+export declare const validationError: (message: string, details?: unknown) => AppductCliError;
+export declare const connectionError: (message: string, details?: unknown) => AppductCliError;
+export declare const sessionError: (message: string, details?: unknown) => AppductCliError;
+export declare const toolError: (message: string, details?: unknown) => AppductCliError;
+export declare const permissionError: (message: string, details?: unknown) => AppductCliError;
+export declare const internalError: (message: string, details?: unknown) => AppductCliError;
+export declare const inspectionError: (message: string, details?: unknown) => AppductCliError;
+export declare const assertionError: (message: string, details?: unknown) => AppductCliError;
+export declare const isAppductCliError: (value: unknown) => value is AppductCliError;
+/**
+ * Converts any error thrown from a command handler into the CLI's rendered `CliError` shape.
+ * RPC/app-originated failures (`DaemonRpcError` with a preserved `data.type`) keep that type
+ * **verbatim** in `type` — never re-wrapped under a generic bucket (ARCHITECTURE.md §5) — so e.g.
+ * `invoke --json` on a failing tool call renders `error.type === "tool_execution_error"`, not
+ * `"tool_error"`. `getExitCodeForError` still buckets that same error into a sysexits class.
+ */
+export declare const toCliError: (error: unknown) => CliError;
+/** Computes the process exit code for the *original* thrown error (not the rendered `CliError`) so
+ * that the sysexits classification never depends on — or leaks into — the rendered `type` field. */
+export declare const getExitCodeForError: (error: unknown) => number;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AA4CpE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEf,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAMnE;AAED,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,OAAO,KAAG,eAE/D,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,EAAE,UAAU,OAAO,KAAG,eAEpE,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,EAAE,UAAU,OAAO,KAAG,eAEpE,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,EAAE,UAAU,OAAO,KAAG,eAEjE,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,EAAE,UAAU,OAAO,KAAG,eAE9D,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,EAAE,UAAU,OAAO,KAAG,eAEpE,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,EAAE,UAAU,OAAO,KAAG,eAElE,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,EAAE,UAAU,OAAO,KAAG,eAEpE,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,UAAU,OAAO,KAAG,eAEnE,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAE3D,CAAC;AAUF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,QAqD3C,CAAC;AAEF;oGACoG;AACpG,eAAO,MAAM,mBAAmB,GAAI,OAAO,OAAO,KAAG,MAmBpD,CAAC"}

package/dist/errors.js

@@ -0,0 +1,162 @@
+import { DaemonRpcError, DaemonVersionMismatchError, isDaemonUnreachableError } from "./rpc/client.js";
+const EXIT_CODE_BY_ERROR_TYPE = {
+    usage_error: 64,
+    validation_error: 65,
+    // EX_NOINPUT (66): "an input file did not exist or was not readable" — `doctor` throws this for a
+    // missing external tool or an unreadable/corrupt artifact, deliberately distinct from every other
+    // code here so a release pipeline can't mistake "we couldn't tell" for either a clean pass or an
+    // assertion failure (docs/tasks/08-appduct-doctor.md).
+    inspection_error: 66,
+    connection_error: 70,
+    session_error: 71,
+    tool_error: 72,
+    permission_error: 77,
+    internal_error: 1,
+    // `doctor --assert-present`/`--assert-absent`: the artifact was inspected successfully and the
+    // assertion did not hold. Distinct from `inspection_error` (66) — this means the answer is known
+    // and it's "no", not "couldn't tell" — and distinct from `internal_error` (1) so a caller can't
+    // conflate a normal assertion failure with an unexpected crash.
+    assertion_error: 3,
+};
+/**
+ * Maps the daemon's wire `error.data.type` (ARCHITECTURE.md §5) onto a sysexits class for exit-code
+ * purposes only — the CLI error's rendered `type` field still preserves the wire type verbatim
+ * (see {@link toCliError}); this table never leaks into rendered output.
+ */
+const RPC_ERROR_EXIT_CLASS = {
+    no_session: "session_error",
+    ambiguous_session: "session_error",
+    unknown_session: "session_error",
+    session_not_active: "session_error",
+    session_suspended: "session_error",
+    tool_not_found: "tool_error",
+    tool_input_validation_error: "tool_error",
+    tool_output_validation_error: "tool_error",
+    tool_execution_error: "tool_error",
+    tool_serialization_error: "tool_error",
+    tool_timeout: "tool_error",
+    tool_cancelled: "tool_error",
+    policy_denied: "permission_error",
+    invalid_request: "validation_error",
+};
+export class AppductCliError extends Error {
+    type;
+    details;
+    constructor(type, message, details) {
+        super(message);
+        this.name = "AppductCliError";
+        this.type = type;
+        this.details = details;
+    }
+}
+export const usageError = (message, details) => {
+    return new AppductCliError("usage_error", message, details);
+};
+export const validationError = (message, details) => {
+    return new AppductCliError("validation_error", message, details);
+};
+export const connectionError = (message, details) => {
+    return new AppductCliError("connection_error", message, details);
+};
+export const sessionError = (message, details) => {
+    return new AppductCliError("session_error", message, details);
+};
+export const toolError = (message, details) => {
+    return new AppductCliError("tool_error", message, details);
+};
+export const permissionError = (message, details) => {
+    return new AppductCliError("permission_error", message, details);
+};
+export const internalError = (message, details) => {
+    return new AppductCliError("internal_error", message, details);
+};
+export const inspectionError = (message, details) => {
+    return new AppductCliError("inspection_error", message, details);
+};
+export const assertionError = (message, details) => {
+    return new AppductCliError("assertion_error", message, details);
+};
+export const isAppductCliError = (value) => {
+    return value instanceof AppductCliError;
+};
+/** True for a `DaemonRpcError` whose `data.type` is a known wire `ErrorType` (always the case for
+ * `RpcApplicationError`-originated failures; JSON-RPC transport-level errors like "Method not
+ * found" carry no `data` and fall through to `internal_error`). */
+const rpcErrorClass = (error) => {
+    const type = error.data?.type;
+    return type ? RPC_ERROR_EXIT_CLASS[type] : undefined;
+};
+/**
+ * Converts any error thrown from a command handler into the CLI's rendered `CliError` shape.
+ * RPC/app-originated failures (`DaemonRpcError` with a preserved `data.type`) keep that type
+ * **verbatim** in `type` — never re-wrapped under a generic bucket (ARCHITECTURE.md §5) — so e.g.
+ * `invoke --json` on a failing tool call renders `error.type === "tool_execution_error"`, not
+ * `"tool_error"`. `getExitCodeForError` still buckets that same error into a sysexits class.
+ */
+export const toCliError = (error) => {
+    if (isAppductCliError(error)) {
+        return {
+            type: error.type,
+            message: error.message,
+            details: error.details,
+        };
+    }
+    // Daemon/CLI version drift that could not be resolved automatically (issue #30). Rendered as a
+    // `connection_error` — the daemon is reachable, but not one this client can safely talk to —
+    // with both versions and the live-session count in `details` so `--json` consumers can act on it
+    // without parsing the message.
+    if (error instanceof DaemonVersionMismatchError) {
+        return {
+            type: "connection_error",
+            message: error.message,
+            details: {
+                daemon_version: error.daemonVersion,
+                client_version: error.clientVersion,
+                session_count: error.sessionCount,
+                pending_link_count: error.pendingLinkCount,
+            },
+        };
+    }
+    if (error instanceof DaemonRpcError && error.data?.type) {
+        return {
+            type: error.data.type,
+            message: error.message,
+            details: error.data.details,
+        };
+    }
+    if (isDaemonUnreachableError(error)) {
+        return {
+            type: "connection_error",
+            message: error instanceof Error ? error.message : "The Appduct daemon is unreachable.",
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            type: "internal_error",
+            message: error.message,
+        };
+    }
+    return {
+        type: "internal_error",
+        message: "An unexpected error occurred.",
+        details: error,
+    };
+};
+/** Computes the process exit code for the *original* thrown error (not the rendered `CliError`) so
+ * that the sysexits classification never depends on — or leaks into — the rendered `type` field. */
+export const getExitCodeForError = (error) => {
+    if (isAppductCliError(error)) {
+        return EXIT_CODE_BY_ERROR_TYPE[error.type];
+    }
+    if (error instanceof DaemonVersionMismatchError) {
+        return EXIT_CODE_BY_ERROR_TYPE.connection_error;
+    }
+    if (error instanceof DaemonRpcError) {
+        const cliErrorClass = rpcErrorClass(error);
+        return EXIT_CODE_BY_ERROR_TYPE[cliErrorClass ?? "internal_error"];
+    }
+    if (isDaemonUnreachableError(error)) {
+        return EXIT_CODE_BY_ERROR_TYPE.connection_error;
+    }
+    return EXIT_CODE_BY_ERROR_TYPE.internal_error;
+};

package/dist/host-certificate.d.ts

@@ -0,0 +1,8 @@
+import "reflect-metadata";
+type GeneratedHostCertificate = {
+    certPem: string;
+    spkiPin: string;
+};
+export declare const generateHostCertificate: (keyPem: string, advertisedIp: string) => Promise<GeneratedHostCertificate>;
+export {};
+//# sourceMappingURL=host-certificate.d.ts.map

package/dist/host-certificate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-certificate.d.ts","sourceRoot":"","sources":["../src/host-certificate.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAyB1B,KAAK,wBAAwB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAwHF,eAAO,MAAM,uBAAuB,GAClC,QAAQ,MAAM,EACd,cAAc,MAAM,KACnB,OAAO,CAAC,wBAAwB,CAyClC,CAAC"}

package/dist/host-certificate.js

@@ -0,0 +1,111 @@
+import "reflect-metadata";
+import { createPrivateKey, createPublicKey, randomBytes, webcrypto, } from "node:crypto";
+import { BasicConstraintsExtension, DNS, ExtendedKeyUsage, ExtendedKeyUsageExtension, IP, KeyUsageFlags, KeyUsagesExtension, SubjectAlternativeNameExtension, SubjectKeyIdentifierExtension, X509CertificateGenerator, } from "@peculiar/x509";
+import { getSpkiPinFromPrivateKeyPem } from "./spki-pin.js";
+const CERT_VALIDITY_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const CERT_CLOCK_SKEW_MS = 5 * 60 * 1000;
+const toArrayBuffer = (view) => {
+    return Uint8Array.from(view).buffer;
+};
+const decodeBase64Url = (value) => {
+    return Uint8Array.from(Buffer.from(value, "base64url"));
+};
+const resolveEcHash = (curve) => {
+    switch (curve) {
+        case "P-256":
+            return "SHA-256";
+        case "P-384":
+            return "SHA-384";
+        case "P-521":
+            return "SHA-512";
+        default:
+            throw new Error(`Unsupported EC named curve "${curve}" for Appduct host certificates.`);
+    }
+};
+const importSigningKeyPair = async (keyPem) => {
+    const privateKeyObject = createPrivateKey(keyPem);
+    const publicKeyObject = createPublicKey(privateKeyObject);
+    const privateKeyDer = Buffer.from(privateKeyObject.export({ format: "der", type: "pkcs8" }));
+    const publicKeyDer = Buffer.from(publicKeyObject.export({ format: "der", type: "spki" }));
+    const jwk = privateKeyObject.export({ format: "jwk" });
+    if (jwk.kty === "RSA") {
+        const modulusLength = privateKeyObject.asymmetricKeyDetails?.modulusLength;
+        if (typeof modulusLength !== "number" || typeof jwk.e !== "string") {
+            throw new Error("Appduct could not determine RSA key details for certificate generation.");
+        }
+        const publicExponent = decodeBase64Url(jwk.e);
+        const importAlgorithm = {
+            name: "RSASSA-PKCS1-v1_5",
+            hash: "SHA-256",
+            modulusLength,
+            publicExponent,
+        };
+        return {
+            keyType: "rsa",
+            privateKey: await webcrypto.subtle.importKey("pkcs8", toArrayBuffer(privateKeyDer), importAlgorithm, false, ["sign"]),
+            publicKey: await webcrypto.subtle.importKey("spki", toArrayBuffer(publicKeyDer), importAlgorithm, true, ["verify"]),
+            signingAlgorithm: {
+                name: "RSASSA-PKCS1-v1_5",
+                hash: "SHA-256",
+            },
+        };
+    }
+    if (jwk.kty === "EC") {
+        const namedCurve = jwk.crv;
+        if (typeof namedCurve !== "string") {
+            throw new Error("Appduct could not determine the EC named curve for certificate generation.");
+        }
+        const importAlgorithm = {
+            name: "ECDSA",
+            namedCurve,
+        };
+        const signingAlgorithm = {
+            ...importAlgorithm,
+            hash: resolveEcHash(namedCurve),
+        };
+        return {
+            keyType: "ec",
+            privateKey: await webcrypto.subtle.importKey("pkcs8", toArrayBuffer(privateKeyDer), importAlgorithm, false, ["sign"]),
+            publicKey: await webcrypto.subtle.importKey("spki", toArrayBuffer(publicKeyDer), importAlgorithm, true, ["verify"]),
+            signingAlgorithm: {
+                name: "ECDSA",
+                hash: resolveEcHash(namedCurve),
+            },
+        };
+    }
+    throw new Error(`Appduct does not support "${jwk.kty ?? privateKeyObject.asymmetricKeyType}" host keys.`);
+};
+export const generateHostCertificate = async (keyPem, advertisedIp) => {
+    const keys = await importSigningKeyPair(keyPem);
+    const sanEntries = [
+        { type: DNS, value: "localhost" },
+        { type: IP, value: "127.0.0.1" },
+    ];
+    if (advertisedIp !== "127.0.0.1") {
+        sanEntries.push({ type: IP, value: advertisedIp });
+    }
+    const keyUsage = KeyUsageFlags.digitalSignature |
+        (keys.keyType === "rsa" ? KeyUsageFlags.keyEncipherment : KeyUsageFlags.keyAgreement);
+    const certificate = await X509CertificateGenerator.createSelfSigned({
+        name: "CN=Appduct Host",
+        notBefore: new Date(Date.now() - CERT_CLOCK_SKEW_MS),
+        notAfter: new Date(Date.now() + CERT_VALIDITY_WINDOW_MS),
+        signingAlgorithm: keys.signingAlgorithm,
+        keys: {
+            privateKey: keys.privateKey,
+            publicKey: keys.publicKey,
+        },
+        extensions: [
+            new BasicConstraintsExtension(false, undefined, true),
+            new KeyUsagesExtension(keyUsage, true),
+            new ExtendedKeyUsageExtension([ExtendedKeyUsage.serverAuth], false),
+            new SubjectAlternativeNameExtension(sanEntries, false),
+            await SubjectKeyIdentifierExtension.create(keys.publicKey),
+        ],
+    });
+    const certPem = certificate.toString("pem");
+    return {
+        certPem,
+        spkiPin: getSpkiPinFromPrivateKeyPem(keyPem),
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./cli.js";
+export * from "./errors.js";
+export * from "./output.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./cli.js";
+export * from "./errors.js";
+export * from "./output.js";

package/dist/key-material.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Host private-key generation and atomic persistence (ARCHITECTURE.md §3, §10). Shared by
+ * `appduct keygen` (explicit, user-invoked) and the daemon's zero-config dev-mode
+ * auto-generation at startup (`daemon/tls.ts`) — both call sites need byte-identical key material
+ * (RSA-2048, PKCS8 PEM) and identical file hygiene (0600, atomic rename via a `wx`-flagged temp
+ * file so a concurrent writer can never observe a partial key).
+ */
+export declare const generatePrivateKeyPem: () => string;
+/** Writes `keyPem` at `path` atomically (temp file + rename) with mode 0600. The temp file uses
+ * `wx` so two concurrent writers can never interleave; callers that want to overwrite an existing
+ * `path` still succeed, since `rename` replaces the destination on POSIX regardless of whether it
+ * already existed — only the *temp* path must be exclusive. */
+export declare const writePrivateKeyAtomically: (path: string, keyPem: string) => Promise<void>;
+//# sourceMappingURL=key-material.d.ts.map

package/dist/key-material.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-material.d.ts","sourceRoot":"","sources":["../src/key-material.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,eAAO,MAAM,qBAAqB,QAAO,MAYxC,CAAC;AAEF;;;+DAG+D;AAC/D,eAAO,MAAM,yBAAyB,GAAU,MAAM,MAAM,EAAE,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAgB1F,CAAC"}

package/dist/key-material.js

@@ -0,0 +1,42 @@
+/**
+ * Host private-key generation and atomic persistence (ARCHITECTURE.md §3, §10). Shared by
+ * `appduct keygen` (explicit, user-invoked) and the daemon's zero-config dev-mode
+ * auto-generation at startup (`daemon/tls.ts`) — both call sites need byte-identical key material
+ * (RSA-2048, PKCS8 PEM) and identical file hygiene (0600, atomic rename via a `wx`-flagged temp
+ * file so a concurrent writer can never observe a partial key).
+ */
+import { generateKeyPairSync } from "node:crypto";
+import { dirname } from "node:path";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+export const generatePrivateKeyPem = () => {
+    const { privateKey } = generateKeyPairSync("rsa", {
+        modulusLength: 2048,
+        publicExponent: 0x10001,
+    });
+    return privateKey
+        .export({
+        format: "pem",
+        type: "pkcs8",
+    })
+        .toString("utf8");
+};
+/** Writes `keyPem` at `path` atomically (temp file + rename) with mode 0600. The temp file uses
+ * `wx` so two concurrent writers can never interleave; callers that want to overwrite an existing
+ * `path` still succeed, since `rename` replaces the destination on POSIX regardless of whether it
+ * already existed — only the *temp* path must be exclusive. */
+export const writePrivateKeyAtomically = async (path, keyPem) => {
+    const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await mkdir(dirname(path), { recursive: true });
+    try {
+        await writeFile(temporaryPath, keyPem, {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        await rename(temporaryPath, path);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true }).catch(() => { });
+        throw error;
+    }
+};

package/dist/link.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared core of `link.create` + deep-link composition + optional emulator/simulator delivery
+ * (ARCHITECTURE.md §8, §10): mints a pending session via `link.create`, then composes
+ * `<scheme>:///?appduct=<payload>&pin=<spki-pin>` and optionally delivers it to a booted
+ * Android emulator/device or iOS simulator. Used by `commands/link.ts` (`appduct link`) and
+ * `client/bootstrap.ts` (`appduct/client`'s `link()`) so this shape — scheme resolution, the
+ * `pin` query param, the `127.0.0.1` emulator/simulator address override (which the experimental
+ * `ios-device` target deliberately opts out of) — can't drift between the CLI and the programmatic
+ * client.
+ *
+ * The `pin` param is separate from the `appduct` bootstrap blob (opt-in hardening dev-mode) — it
+ * is never part of that binary v2 payload, so old apps that don't know about it simply ignore it.
+ * It carries the daemon's SPKI pin (same value as `daemon.status`'s `pinnedKeys[0]` / `appduct
+ * keygen`'s output) so a debug build with no build-time `cliPins` configured can trust it for this
+ * one connection instead of requiring a native rebuild just to test locally. The pin is standard
+ * (non-URL-safe) base64 (`sha256/<44-char-base64>`, may contain `+`/`/`/`=`), so it is percent-
+ * encoded here; native/JS parsers use `URLSearchParams`, which decodes it back.
+ */
+import { type AgentEndpoint, type LinkCreateResult } from "@appduct/shared";
+import { type ExecFn, type OpenTarget } from "./cli/open-target.js";
+import { type SpawnFn } from "./rpc/client.js";
+/**
+ * The deep-link shape, in one place: `<scheme>:///?appduct=<payload>&pin=<spki-pin>`. Exported
+ * so `mcp/connect-tool.ts` composes byte-identical links rather than a second, drifting copy — the
+ * `pin` param went missing from the MCP side exactly because there were two of these.
+ *
+ * The pin is standard (non-URL-safe) base64 (`sha256/<44 chars>`, possibly containing `+`/`/`/`=`),
+ * so it is percent-encoded; parsers use `URLSearchParams`, which decodes it back. It is appended
+ * *after* the bootstrap blob, so anything reading `appduct=` must stop at the `&`.
+ */
+export declare const composeDeepLink: (scheme: string, result: LinkCreateResult) => string;
+export type MintLinkOptions = {
+    stateDir: string;
+    spawn?: SpawnFn;
+    autoSpawn?: boolean;
+    ttlSeconds?: number;
+    /** Delivers the link directly to a booted Android emulator/device or iOS simulator instead of
+     * leaving delivery to the caller. */
+    target?: OpenTarget;
+    /** An adb device serial (`target: "android"`), a simulator udid (`target: "ios-sim"`) or a
+     * paired-device udid (`target: "ios-device"`). Only meaningful alongside a target. */
+    device?: string;
+    /** Overrides `config.json`'s `iosBundleId`. Only meaningful with `target: "ios-device"`. */
+    bundleId?: string;
+    /** `target: "ios-device"` only: terminate a running instance before launching
+     * (`--terminate-existing`). Off by default. */
+    relaunch?: boolean;
+    /** Highest-precedence scheme source (`--scheme`); see `scheme.ts` for the full order. */
+    scheme?: string;
+    /** Where scheme discovery starts (project `.appduct/config.json` walk-up, then `app.json`).
+     * Defaults to `process.cwd()`. */
+    cwd?: string;
+    exec?: ExecFn;
+    /** The environment handed to `adb`/`simctl` when delivering to a device. This is deliberately
+     * *not* where `APPDUCT_SCHEME` is read from — callers narrow this env on purpose, and reading
+     * the scheme out of it would silently drop one the user really had exported. See {@link schemeEnv}. */
+    env?: NodeJS.ProcessEnv;
+    /** The environment `APPDUCT_SCHEME` is read from; defaults to `process.env`. Separate from
+     * {@link env} so a narrowed exec environment cannot change scheme resolution. */
+    schemeEnv?: NodeJS.ProcessEnv;
+};
+export type MintLinkResult = {
+    sessionId: string;
+    deepLink: string;
+    endpoint: AgentEndpoint;
+    /** Unix seconds. */
+    expiresAt: number;
+    pin: string;
+    delivered?: true;
+    target?: OpenTarget;
+};
+/** Throws `usageError`/`AppductCliError` on validation failure — `commands/link.ts` renders
+ * that straight through the CLI's own error path; `client/bootstrap.ts` converts it to a
+ * `AppductError` via `toAppductError` (which already understands `AppductCliError`). */
+export declare const mintLink: (options: MintLinkOptions) => Promise<MintLinkResult>;
+//# sourceMappingURL=link.d.ts.map

package/dist/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../src/link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAe,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEzF,OAAO,EAUL,KAAK,MAAM,EACX,KAAK,UAAU,EAChB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAU3D;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,EAAE,QAAQ,gBAAgB,KAAG,MACc,CAAC;AAE1F,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;yCACqC;IACrC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;0FACsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;mDAC+C;IAC/C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;sCACkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;2GAEuG;IACvG,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;qFACiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,aAAa,CAAC;IACxB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CAAC;AAEF;;wFAEwF;AACxF,eAAO,MAAM,QAAQ,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,cAAc,CA8F/E,CAAC"}