@hue-run/sdk 0.3.2 → 0.4.1

package/dist/setup/configure.js

@@ -0,0 +1,454 @@
+import { constants } from "node:fs";
+import { link, lstat, open, readdir, realpath, rename, unlink } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { setupManagedDigest, } from "./installation.js";
+async function cleanupTemporary(path) {
+    try {
+        const info = await lstat(path);
+        if (info.isFile())
+            await unlink(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function inside(parent, child) {
+    const path = relative(parent, child);
+    return path === "" || (!path.startsWith("..") && !path.startsWith("/"));
+}
+async function safeDirectory(path) {
+    const paths = [];
+    let current = resolve(path);
+    for (;;) {
+        paths.unshift(current);
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    for (const entry of paths) {
+        const info = await lstat(entry);
+        if (info.isSymbolicLink() || !info.isDirectory())
+            throw new Error("Refusing a setup configuration path with a symlink ancestor");
+    }
+    if ((await realpath(path)) !== resolve(path))
+        throw new Error("Refusing a setup configuration path outside its actual directory");
+}
+async function readManaged(path) {
+    await safeDirectory(dirname(path));
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error("Refusing unsafe setup configuration");
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > 1024 * 1024 || (info.mode & 0o7000) !== 0)
+            throw new Error("Refusing unsafe setup configuration");
+        const contents = await handle.readFile("utf8");
+        const after = await handle.stat();
+        if (info.mtimeMs !== after.mtimeMs ||
+            info.ctimeMs !== after.ctimeMs ||
+            info.size !== after.size)
+            throw new Error("Refusing setup configuration changed while reading");
+        return { contents, info };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function sameSnapshot(left, right) {
+    if (!left || !right)
+        return left === right;
+    return (left.contents === right.contents &&
+        left.info.dev === right.info.dev &&
+        left.info.ino === right.info.ino &&
+        left.info.mode === right.info.mode &&
+        left.info.mtimeMs === right.info.mtimeMs &&
+        left.info.ctimeMs === right.info.ctimeMs);
+}
+function serviceName(root) {
+    const normalized = basename(root).replace(/[^A-Za-z0-9_.-]+/gu, "-");
+    let start = 0;
+    let end = normalized.length;
+    while (normalized[start] === "-")
+        start += 1;
+    while (end > start && normalized[end - 1] === "-")
+        end -= 1;
+    const value = normalized.slice(start, end).slice(0, 220);
+    return value ? `hue-setup-${value}` : "hue-setup-project";
+}
+function typescriptConfig(store) {
+    return `// Managed by Hue setup. This file contains no credential.
+import { closeSync, constants, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createHmac } from "node:crypto";
+import { createServer, createConnection } from "node:net";
+import { createHue } from "@hue-run/sdk";
+import { context, createContextKey, ROOT_CONTEXT, SpanKind } from "@opentelemetry/api";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+
+// Generated application bootstrap owns this policy; the SDK core registers nothing.
+const contextCheck = createContextKey("hue.setup.context-check");
+async function hasWorkingContext() {
+  try {
+    return await context.with(ROOT_CONTEXT.setValue(contextCheck, true), async () => {
+      await Promise.resolve();
+      await new Promise((resolve) => setImmediate(resolve));
+      return context.active().getValue(contextCheck) === true;
+    });
+  } catch { return false; }
+}
+let ownedContext;
+if (!(await hasWorkingContext())) {
+  const candidate = new AsyncLocalStorageContextManager().enable();
+  if (!context.setGlobalContextManager(candidate)) {
+    candidate.disable();
+    throw new Error("Existing OpenTelemetry context ownership is unsupported; review the application bootstrap");
+  }
+  ownedContext = candidate;
+  if (!(await hasWorkingContext())) {
+    ownedContext.disable();
+    throw new Error("This runtime does not support the setup context integration");
+  }
+}
+process.once("beforeExit", () => { ownedContext?.disable(); ownedContext = undefined; });
+
+const installation = JSON.parse(
+  readFileSync(fileURLToPath(new URL("./.hue/${basename(store.path)}", import.meta.url)), "utf8"),
+);
+if (!installation.credential?.apiKey) throw new Error("Run hue resume to recover Hue credentials");
+
+export const hue = createHue({
+  apiKey: installation.credential.apiKey,
+  baseUrl: installation.origin,
+  serviceName: ${JSON.stringify(serviceName(store.projectRoot))},
+  captureContent: false,
+});
+
+const evidencePath = fileURLToPath(new URL("./.hue/${basename(store.applicationEvidencePath)}", import.meta.url));
+const expressInstalled = Symbol.for("hue.setup.express.installed");
+
+// Setup-only transport. Normal app serving never sends an ownership frame.
+function installOwnedListener(app) {
+  const proof = process.env.HUE_SETUP_SOCKET_PROOF;
+  delete process.env.HUE_SETUP_SOCKET_PROOF;
+  if (proof === undefined) return;
+  if (!/^[A-Za-z0-9_-]{43}$/u.test(proof)) throw new Error("Invalid setup invocation");
+  const original = app.listen;
+  app.listen = function (port, host) {
+    if ((host !== undefined && host !== "127.0.0.1") || arguments.length > 2)
+      throw new Error("Unsupported setup listener ownership");
+    const inner = original.call(app, 0, "127.0.0.1");
+    let accepted = false;
+    const sockets = new Set();
+    const outer = createServer((socket) => {
+      if (accepted || !inner.listening) { socket.destroy(); return; }
+      accepted = true;
+      sockets.add(socket);
+      const upstream = createConnection({ host: "127.0.0.1", port: inner.address().port });
+      sockets.add(upstream);
+      const close = () => { socket.destroy(); upstream.destroy(); sockets.delete(socket); sockets.delete(upstream); };
+      socket.on("error", close); upstream.on("error", close);
+      socket.on("close", close); upstream.on("close", close);
+      socket.setTimeout(15000, close); upstream.setTimeout(15000, close);
+      upstream.once("connect", () => {
+        if (!inner.listening || socket.destroyed) { close(); return; }
+        const digest = createHmac("sha256", Buffer.from(proof, "base64url"))
+          .update("hue-setup-owned-v1\\0" + socket.localPort + "\\0" + socket.remotePort).digest("base64url");
+        socket.write("Hue-setup-owned:" + digest + "\\n");
+        socket.pipe(upstream); upstream.pipe(socket);
+      });
+    });
+    const close = () => { for (const socket of sockets) socket.destroy(); inner.close(); };
+    outer.on("error", close); outer.on("close", close);
+    inner.on("error", () => outer.close());
+    inner.once("listening", () => outer.listen(Number(port), "127.0.0.1"));
+    return outer;
+  };
+}
+
+function saveEvidence(value) {
+  if (process.env.HUE_SETUP_EVIDENCE_FILE !== evidencePath) return;
+  const temporary = evidencePath + "." + process.pid + ".tmp";
+  let descriptor;
+  try {
+    descriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    writeFileSync(descriptor, JSON.stringify(value) + "\\n", "utf8");
+    fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = undefined;
+    renameSync(temporary, evidencePath);
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+    try { unlinkSync(temporary); } catch (error) { if (error?.code !== "ENOENT") throw error; }
+  }
+}
+
+export function installHueExpress(app, requestPath) {
+  if (app[expressInstalled]) throw new Error("Duplicate Hue setup middleware requires explicit review");
+  app[expressInstalled] = true;
+  installOwnedListener(app);
+  app.use((request, response, next) => {
+    void (async () => {
+      const ids = await hue.withSpan("hue.metadata", async (span) => {
+        const finished = new Promise((resolve) => {
+          response.once("finish", resolve);
+          response.once("close", resolve);
+        });
+        next();
+        await finished;
+        return { traceId: span.traceId, spanId: span.spanId };
+      }, { kind: SpanKind.SERVER });
+      await hue.flush();
+      if (request.method === "GET" && request.route?.path === requestPath && request.path === requestPath && response.statusCode >= 200 && response.statusCode < 300 && response.writableFinished)
+        saveEvidence({ ...ids, credentialVersion: installation.credential.version, source: "existing-application-request" });
+    })().catch(() => undefined);
+  });
+}
+`;
+}
+function pythonConfig(store) {
+    return `# Managed by Hue setup. This file contains no credential.
+import json
+import os
+import base64
+import hashlib
+import hmac
+from pathlib import Path
+
+from flask import g, request
+from hue_sdk import Hue
+from opentelemetry.trace import SpanKind, use_span
+from werkzeug.serving import WSGIRequestHandler
+
+_installation = json.loads(
+    (Path(__file__).parent / ".hue" / ${JSON.stringify(basename(store.path))}).read_text(encoding="utf-8")
+)
+if not _installation.get("credential", {}).get("apiKey"):
+    raise RuntimeError("Run hue resume to recover Hue credentials")
+
+hue = Hue(
+    api_key=_installation["credential"]["apiKey"],
+    base_url=_installation["origin"],
+    service_name=${JSON.stringify(serviceName(store.projectRoot))},
+    capture_content=False,
+)
+
+_evidence_path = Path(__file__).parent / ".hue" / ${JSON.stringify(basename(store.applicationEvidencePath))}
+
+
+def _save_evidence(value):
+    if os.environ.get("HUE_SETUP_EVIDENCE_FILE") != str(_evidence_path):
+        return
+    temporary = _evidence_path.with_name(f".{_evidence_path.name}.{os.getpid()}.tmp")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    descriptor = os.open(temporary, flags, 0o600)
+    try:
+        os.write(descriptor, (json.dumps(value) + "\\n").encode("utf-8"))
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+    os.replace(temporary, _evidence_path)
+
+
+def install_hue_flask(app, request_path):
+    if app.extensions.get("hue_setup_installed"):
+        raise RuntimeError("Duplicate Hue setup middleware requires explicit review")
+    app.extensions["hue_setup_installed"] = True
+    proof = os.environ.pop("HUE_SETUP_SOCKET_PROOF", None)
+    if proof is not None:
+        if len(proof) != 43 or any(char not in "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-" for char in proof):
+            raise RuntimeError("Invalid setup invocation")
+        accepted = False
+        class OwnedHandler(WSGIRequestHandler):
+            def handle(self):
+                nonlocal accepted
+                if accepted:
+                    return
+                accepted = True
+                try:
+                    self.connection.settimeout(15)
+                    message = "hue-setup-owned-v1\\0" + str(self.connection.getsockname()[1]) + "\\0" + str(self.connection.getpeername()[1])
+                    digest = base64.urlsafe_b64encode(hmac.new(base64.urlsafe_b64decode(proof + "="), message.encode("ascii"), hashlib.sha256).digest()).rstrip(b"=")
+                    self.connection.sendall(b"Hue-setup-owned:" + digest + b"\\n")
+                    super().handle()
+                except (OSError, ValueError):
+                    pass
+        original_run = app.run
+        def owned_run(*args, **kwargs):
+            if args or set(kwargs) - {"host", "port"} or kwargs.get("host", "127.0.0.1") != "127.0.0.1":
+                raise RuntimeError("Unsupported setup listener ownership")
+            return original_run(**kwargs, request_handler=OwnedHandler, load_dotenv=False, use_reloader=False, threaded=False)
+        app.run = owned_run
+
+    @app.before_request
+    def _hue_setup_before_request():
+        try:
+            span = hue.tracer.start_span("hue.metadata", kind=SpanKind.SERVER)
+            context = use_span(span, end_on_exit=False, record_exception=False, set_status_on_exception=False)
+            context.__enter__()
+            g._hue_setup_context = context
+            g._hue_setup_span = span
+        except Exception:
+            pass
+
+    @app.after_request
+    def _hue_setup_after_request(response):
+        try:
+            context = getattr(g, "_hue_setup_context", None)
+            span = getattr(g, "_hue_setup_span", None)
+            g._hue_setup_context = None
+            g._hue_setup_span = None
+            if context is not None:
+                context.__exit__(None, None, None)
+            if span is None:
+                return response
+            matched = request.method == "GET" and request.url_rule is not None and request.url_rule.rule == request_path and 200 <= response.status_code < 300
+            ended = False
+            def finish(complete):
+                nonlocal ended
+                if ended:
+                    return
+                ended = True
+                try:
+                    ids = span.get_span_context()
+                    span.end()
+                    if complete and matched and os.environ.get("HUE_SETUP_EVIDENCE_FILE") == str(_evidence_path) and hue.force_flush():
+                        _save_evidence({"traceId": format(ids.trace_id, "032x"), "spanId": format(ids.span_id, "016x"), "credentialVersion": _installation["credential"]["version"], "source": "existing-application-request"})
+                except Exception:
+                    pass
+            if response.is_streamed:
+                original = response.response
+                def streamed():
+                    complete = False
+                    try:
+                        with use_span(span, end_on_exit=False, record_exception=False, set_status_on_exception=False):
+                            yield from original
+                        complete = True
+                    finally:
+                        finish(complete)
+                response.response = streamed()
+                response.call_on_close(lambda: finish(False))
+            else:
+                finish(True)
+        except Exception:
+            pass
+        return response
+`;
+}
+async function atomicManagedWrite(path, contents, previous) {
+    await safeDirectory(dirname(path));
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, previous ? previous.info.mode & 0o777 : 0o644);
+        await handle.chmod(previous ? previous.info.mode & 0o777 : 0o644);
+        await handle.writeFile(contents, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        if (!sameSnapshot(previous, await readManaged(path)))
+            throw new Error("Refusing setup configuration changed before replacement");
+        if (previous)
+            await rename(temporary, path);
+        else {
+            // link is an atomic create-if-absent: never replace a file created after validation.
+            await link(temporary, path);
+            await unlink(temporary);
+        }
+    }
+    finally {
+        await handle?.close();
+        await cleanupTemporary(temporary);
+    }
+}
+async function writeManaged(store, record, relativePath, contents) {
+    const path = join(store.projectRoot, relativePath);
+    if (!inside(store.projectRoot, path))
+        throw new Error("Unsafe setup configuration path");
+    const expected = setupManagedDigest(contents);
+    const previous = await readManaged(path);
+    if (previous !== undefined && setupManagedDigest(previous.contents) === expected) {
+        if (record.managedFiles[relativePath] !== expected) {
+            record.managedFiles[relativePath] = expected;
+            await store.save(record);
+        }
+        return undefined;
+    }
+    const savedDigest = record.managedFiles[relativePath];
+    if (previous && (!savedDigest || setupManagedDigest(previous.contents) !== savedDigest))
+        throw new Error(`Refusing to overwrite custom or unexpectedly edited configuration at ${relativePath}`);
+    await atomicManagedWrite(path, contents, previous);
+    record.managedFiles[relativePath] = expected;
+    await store.save(record);
+    return { path: relativePath, change: previous ? "updated" : "created" };
+}
+async function rejectCustomEnvironment(projectRoot) {
+    await safeDirectory(projectRoot);
+    if (process.env.HUE_API_KEY)
+        throw new Error("Refusing to replace an existing custom Hue credential from HUE_API_KEY");
+    const entries = await readdir(projectRoot, { withFileTypes: true });
+    if (entries.length > 10_000)
+        throw new Error("Refusing to scan an oversized project directory");
+    for (const entry of entries) {
+        if (!(entry.name === ".env" || entry.name.startsWith(".env.")))
+            continue;
+        if (entry.isSymbolicLink())
+            throw new Error(`Refusing unsafe credential file at ${entry.name}`);
+        if (!entry.isFile())
+            continue;
+        const path = join(projectRoot, entry.name);
+        const source = (await readManaged(path))?.contents;
+        if (source === undefined)
+            throw new Error("Refusing credential file changed during inspection");
+        if (/^\s*(?:export\s+)?HUE_API_KEY\s*=/mu.test(source))
+            throw new Error(`Refusing to replace an existing custom Hue credential in ${entry.name}`);
+    }
+}
+/** Refuses credential/config conflicts before setup makes a provisioning request. */
+export async function validateSetupConfiguration(store, record, project) {
+    if (project.root !== store.projectRoot)
+        throw new Error("Setup project identity changed");
+    if (project.languages.length === 0)
+        throw new Error("No supported TypeScript or Python project was detected");
+    await rejectCustomEnvironment(store.projectRoot);
+    const candidates = [];
+    if (project.languages.includes("typescript"))
+        candidates.push(["hue.setup.mjs", typescriptConfig(store)]);
+    if (project.languages.includes("python"))
+        candidates.push(["hue_setup.py", pythonConfig(store)]);
+    for (const [relativePath, expected] of candidates) {
+        const path = join(store.projectRoot, relativePath);
+        const previous = await readManaged(path);
+        if (previous) {
+            const digest = setupManagedDigest(previous.contents);
+            if (digest !== setupManagedDigest(expected) && digest !== record?.managedFiles[relativePath])
+                throw new Error(`Refusing to overwrite custom or unexpectedly edited configuration at ${relativePath}`);
+        }
+    }
+}
+/** Writes only secret-free, metadata-only integration modules and never executes project code. */
+export async function configureSetupProject(store, record, project) {
+    await validateSetupConfiguration(store, record, project);
+    const changes = [];
+    if (project.languages.includes("typescript")) {
+        const change = await writeManaged(store, record, "hue.setup.mjs", typescriptConfig(store));
+        if (change)
+            changes.push(change);
+    }
+    if (project.languages.includes("python")) {
+        const change = await writeManaged(store, record, "hue_setup.py", pythonConfig(store));
+        if (change)
+            changes.push(change);
+    }
+    return changes;
+}

package/dist/setup/credential.d.ts

@@ -0,0 +1,2 @@
+/** Validates both the bearer namespace and its exact stored key identity. */
+export declare function validSetupCredentialIdentity(apiKey: unknown, keyId: unknown): apiKey is string;

package/dist/setup/credential.js

@@ -0,0 +1,9 @@
+/** Closed pre-release setup credential grammar, distinct from ordinary project service keys. */
+const SETUP_KEY = /^hue_setup_(live|test)_setup-([a-f0-9]{24})_([A-Za-z0-9_-]{43})$/u;
+/** Validates both the bearer namespace and its exact stored key identity. */
+export function validSetupCredentialIdentity(apiKey, keyId) {
+    if (typeof apiKey !== "string" || typeof keyId !== "string")
+        return false;
+    const match = SETUP_KEY.exec(apiKey);
+    return match !== null && keyId === `setup-${match[2]}`;
+}

package/dist/setup/detect.js

@@ -86,7 +86,10 @@ export async function detectSetupProject(projectRoot) {
         .filter((value) => value !== undefined)
         .join("\n");
     const languages = [];
-    if (contents.has("tsconfig.json") || nodeDependencies.has("typescript"))
+    // The existing public language discriminator covers JavaScript as well as TypeScript.
+    if (contents.has("tsconfig.json") ||
+        nodeDependencies.has("typescript") ||
+        nodeDependencies.has("express"))
         languages.push("typescript");
     if (python || contents.has("pyproject.toml"))
         languages.push("python");

package/dist/setup/installation.d.ts

@@ -0,0 +1,118 @@
+/** Telemetry credential saved only in an ignored owner-only installation file. */
+export interface SetupStoredCredential {
+    /** Fixed setup-only key family; never an ordinary account-managed key. */
+    kind: "anonymous_trial";
+    /** Setup credentials have exactly one metadata-only permission in both generations. */
+    capabilities: ["setup_telemetry_write"];
+    /** Bearer credential used solely for telemetry export and receipt verification. */
+    apiKey: string;
+    /** Server identifier for the credential generation. */
+    keyId: string;
+    /** Anonymous or post-claim credential generation. */
+    version: 0 | 1;
+}
+/** Exact metadata probe identifiers retained for resumable receipt verification. */
+export interface SetupStoredProbe {
+    /** Lowercase external trace identifier. */
+    traceId: string;
+    /** Lowercase external span identifier expected in the receipt. */
+    spanId: string;
+    /** Credential generation that exported the probe. */
+    credentialVersion: 0 | 1;
+    /** Whether an exact metadata-only receipt was observed. */
+    verified: boolean;
+}
+/** Exact identifiers emitted by a request through the repository's existing application. */
+export interface SetupStoredApplicationEvidence extends SetupStoredProbe {
+    /** Closed source label that distinguishes app evidence from a synthetic setup probe. */
+    source: "existing-application-request";
+}
+/** Durable no-replay marker written before starting an existing application request. */
+export interface SetupStoredApplicationAttempt {
+    /** Credential generation for which application work was attempted once. */
+    credentialVersion: 0 | 1;
+    /** Bounded ISO timestamp for diagnostics and explicit recovery. */
+    startedAt: string;
+}
+/** Durable client identity for an idempotent one-time browser handoff request. */
+export interface SetupStoredClaimHandoff {
+    /** Lowercase UUIDv4 persisted before the handoff request is sent. */
+    id: string;
+    /** Compare-and-swap predecessor supplied when this handoff was created. */
+    previousHandoffId: string | null;
+    /** Last strictly validated server state, when a response was received. */
+    state?: "pending" | "consumed" | "expired" | "revoked";
+    /** Fixed server expiry, when a response was received. */
+    expiresAt?: string;
+    /** Fixed browser session expiry, when an exchange succeeded. */
+    sessionExpiresAt?: string | null;
+}
+/** Secret local installation state. It must never be emitted or copied into diagnostics. */
+export interface SetupInstallationRecord {
+    /** Local file format version. */
+    format: 1;
+    /** Exact normalized Hue origin owning this installation. */
+    origin: string;
+    /** Lowercase UUIDv4 installation identity. */
+    installationId: string;
+    /** Unpadded base64url installation proof; never log or diagnose this value. */
+    installationSecret: string;
+    /** Latest locally managed telemetry credential. */
+    credential?: SetupStoredCredential;
+    /** Superseded anonymous credential retained only until its revocation is verified. */
+    revocationCredential?: SetupStoredCredential;
+    /** Durable positive verification of the superseded key on the dedicated receipt route. */
+    anonymousKeyRevoked?: true;
+    /** Latest probe awaiting or carrying exact receipt evidence. */
+    probe?: SetupStoredProbe;
+    /** Latest existing-application request awaiting or carrying exact receipt evidence. */
+    applicationEvidence?: SetupStoredApplicationEvidence;
+    /** Prevents automatic replay after startup, request, export or evidence loss. */
+    applicationAttempt?: SetupStoredApplicationAttempt;
+    /** Current proof-bound one-time browser handoff identity; never a bearer capability. */
+    claimHandoff?: SetupStoredClaimHandoff;
+    /** Provision request timestamps used to enforce the local hourly bound. */
+    provisionAttempts: string[];
+    /** Digests of files setup owns and may safely replace. */
+    managedFiles: Record<string, string>;
+}
+/** Owner-only, project/origin-scoped storage for installation proof and telemetry credentials. */
+export declare class FileSetupInstallationStore {
+    private lastSnapshot?;
+    /** Resolved project directory containing the installation state. */
+    readonly projectRoot: string;
+    /** Exact normalized Hue origin scoped to this store. */
+    readonly origin: string;
+    /** Owner-only `.hue` directory. */
+    readonly directory: string;
+    /** Origin-scoped ignored installation record path. */
+    readonly path: string;
+    /** Origin-scoped owner-only browser handoff; its contents are never emitted. */
+    readonly claimHandoffPath: string;
+    /** Origin-scoped private application evidence transfer path. */
+    readonly applicationEvidencePath: string;
+    constructor(projectRoot: string, origin: string);
+    private rejectUnsafeProjectRoot;
+    private hasGitWorktree;
+    private privatePaths;
+    private assertPrivateGitProtection;
+    private snapshot;
+    private ensureIgnoreFile;
+    private ensureRootIgnored;
+    /** Revalidates owner-only storage and ignore rules before an existing proof is used for I/O. */
+    ensureIgnored(): Promise<void>;
+    /** Loads a valid owner-only record without creating one. */
+    load(): Promise<SetupInstallationRecord | undefined>;
+    /** Creates and durably saves the installation proof before any caller may perform network I/O. */
+    loadOrCreate(): Promise<SetupInstallationRecord>;
+    /** Atomically replaces this store's validated owner-only record. */
+    save(record: SetupInstallationRecord): Promise<void>;
+    /** Saves a private browser redirect without putting its capability in a process argument. */
+    saveClaimHandoff(claimUrl: string): Promise<string>;
+    /** Removes a consumed or terminal claim handoff without following symlinks. */
+    removeClaimHandoff(): Promise<void>;
+    /** Removes the private child-to-parent evidence transfer file without following symlinks. */
+    removeApplicationEvidence(): Promise<void>;
+}
+/** Computes the digest used to detect unexpected edits to managed files. */
+export declare function setupManagedDigest(contents: string): string;