ptbk 0.119.0-70 → 0.119.0-72

package/README.md

@@ -11,6 +11,7 @@
   <a href="#quickstart"><strong>Quickstart</strong></a> ·
   <a href="#deploy-to-your-own-server"><strong>Deploy</strong></a> ·
   <a href="https://www.ptbk.io/en"><strong>Website</strong></a> ·
+  <a href="design/README.md"><strong>Brand</strong></a> ·
   <a href="specs/_main.md"><strong>Specifications</strong></a> ·
   <a href="https://www.ptbk.io/en/partnership"><strong>For partners</strong></a>
 </p>
@@ -63,10 +64,12 @@ Agents explicitly call you with `+@User` when they need a response. Viewing that
 
 A background engine [updates itself](specs/cli/updates.md) when it has no other work: stable minor and patch releases of its major version, or a running prerelease to its stable release. It never installs a version your `ptbk.json` `updates` pin or range excludes, or one that needs a newer Node.js than your host runs, and you can switch it off on the dashboard's System page. Release signing and rollout delays are still being agreed with the platform, so your host access and backups still matter.
 
-**Windows:** download the EXE from [GitHub Releases](https://github.com/webgptorg/promptbook/releases), or follow the [installation guide](https://www.ptbk.io/en/open-source). The installer offers the local desktop client (selected by default), Codex and Claude Code. The desktop uses the same engine and initializer as the CLI, with an embedded CLI terminal; closing a window leaves your engines running. CLI-only installation remains available.
+**Windows:** download the EXE from [GitHub Releases](https://github.com/webgptorg/promptbook/releases), or follow the [installation guide](https://www.ptbk.io/en/open-source). The installer offers the local desktop client (selected by default). Open the app to set up your project and choose AI tools. The desktop uses the same engine and initializer as the CLI, with an embedded CLI terminal; closing a window leaves your engines running. CLI-only installation remains available.
 
 **macOS:** download the matching DMG from [GitHub Releases](https://github.com/webgptorg/promptbook/releases). Choose `arm64` for Apple Silicon or `x64` for Intel, then drag Promptbook into Applications. Node.js, npm and the matching engine are included. Project setup uses Git from your Mac, such as Git from the Xcode Command Line Tools. See the [desktop installation guide](apps/desktop/README.md#macos-installation) for signing and login details.
 
+**Android preview:** download the ARM64 APK from [GitHub Releases](https://github.com/webgptorg/promptbook/releases). It includes the local engine, Node.js, Git and Gemini CLI. The app runs the engine in an Android foreground service and opens the project dashboard. See the [Android installation guide](apps/android/README.md) for setup and signing details.
+
 ## Deploy to your own server
 
 **A clean Ubuntu 24.04 LTS x86-64 server** with systemd, outbound HTTPS and root or sudo access over SSH needs no preinstalled Node.js, npm, Git, Chrome or AI harness: use the [one-command installation](#clean-ubuntu-vps). It prepares the server through the [shared installer](deploy/ubuntu/install.sh) and opens `ptbk init` as a dedicated non-sudo `promptbook` user. Sign-in to Codex or Claude Code is finished on your phone or computer; see the [server guide](deploy/README.md#finish-setup-over-ssh).

package/dist/app/connection.d.ts

@@ -0,0 +1,77 @@
+import type { AppConnectionView } from '../engine/snapshot.js';
+import { type HeartbeatUpdateState } from './heartbeat.js';
+import type { TestTlsOptions } from './net.js';
+import { type TunnelStreamHandler } from './tunnel/relay-link.js';
+/**
+ * The App view of a project whose engine is not running, from the stored identity and registration only (no network,
+ * nothing created).
+ *
+ * @private App connection
+ */
+export declare function storedAppView(directory: string, env: NodeJS.ProcessEnv): Promise<AppConnectionView>;
+/**
+ * Live figures the heartbeat reports from the engine.
+ *
+ * @private App connection
+ */
+export type AppEngineFigures = {
+    /** Project agents (not deleted). */
+    readonly agents: number;
+    /** People who can sign in to this engine through the App (0 until App sign-in exists). */
+    readonly members: number;
+    readonly update: HeartbeatUpdateState;
+};
+/**
+ * Options of a project's App connection.
+ *
+ * @private App connection
+ */
+export type AppConnectionOptions = {
+    /** The App data directory (`.ptbk/app/`). */
+    readonly directory: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly onChange: () => void;
+    readonly figures: () => AppEngineFigures;
+    readonly log?: (text: string, level: 'info' | 'warning' | 'error') => void;
+    /** Browser streams; refused until the engine ends browser TLS itself. */
+    readonly onStream?: TunnelStreamHandler;
+    /** Heartbeat cadence (tests only shorten it). */
+    readonly heartbeatIntervalMs?: number;
+    readonly tls?: TestTlsOptions;
+};
+/**
+ * Keeps one project's App connection: the signed heartbeat and one tunnel per relay while the project is linked. It
+ * never blocks the engine: every failure becomes part of its view.
+ *
+ * @private App connection
+ */
+export declare class AppConnection {
+    private readonly options;
+    private identity?;
+    private registration?;
+    private problem?;
+    private links;
+    private heartbeat?;
+    private heartbeatTimer?;
+    private dashboardUrl;
+    private running;
+    /** Serializes start, reload and stop. */
+    private queue;
+    constructor(options: AppConnectionOptions);
+    /** Loads the link and connects when the project is linked. */
+    start(): Promise<void>;
+    /** Re-reads the link after `ptbk connect` or `ptbk disconnect`. */
+    reload(): Promise<AppConnectionView>;
+    /** Closes every tunnel and stops the heartbeat. */
+    stop(): Promise<void>;
+    /** Runs one lifecycle step after the previous one. */
+    private serialize;
+    /** Reads settings, identity and registration, then connects when linked. */
+    private load;
+    /** Starts the relay links and the heartbeat loop. */
+    private connect;
+    /** Stops every link and the heartbeat. */
+    private disconnect;
+    /** The App page's view of this connection (no secrets: no key, signature or link code). */
+    view(): AppConnectionView;
+}

package/dist/app/connection.js

@@ -0,0 +1,170 @@
+import { errorMessage } from '../common/errors.js';
+import { HEARTBEAT_INTERVAL_MS, buildHeartbeat, hostFigures, nextHeartbeatSeq, sendHeartbeat } from './heartbeat.js';
+import { loadEngineIdentity } from './identity.js';
+import { engineVersion, readRegistration } from './registration.js';
+import { DEFAULT_DASHBOARD_URL, appSettings } from './settings.js';
+import { RelayLink } from './tunnel/relay-link.js';
+/**
+ * The App view of a project whose engine is not running, from the stored identity and registration only (no network,
+ * nothing created).
+ *
+ * @private App connection
+ */
+export async function storedAppView(directory, env) {
+    let dashboardUrl = DEFAULT_DASHBOARD_URL;
+    try {
+        const settings = appSettings(env);
+        dashboardUrl = settings.dashboardUrl;
+        const identity = await loadEngineIdentity(directory, { create: false });
+        const registration = await readRegistration(directory, identity, settings);
+        return {
+            state: registration ? 'offline' : 'unlinked',
+            dashboardUrl: registration?.dashboardUrl ?? dashboardUrl,
+            ...(identity ? { engineId: identity.engineId, fingerprint: identity.fingerprint.formatted } : {}),
+            ...(registration ? { hostname: registration.hostname, url: `https://${registration.hostname}/`, linkedAt: registration.registeredAt } : {}),
+            relays: [],
+            browserAccess: 'unavailable',
+        };
+    }
+    catch (error) {
+        return { state: 'problem', dashboardUrl, relays: [], browserAccess: 'unavailable', problem: errorMessage(error) };
+    }
+}
+/**
+ * Keeps one project's App connection: the signed heartbeat and one tunnel per relay while the project is linked. It
+ * never blocks the engine: every failure becomes part of its view.
+ *
+ * @private App connection
+ */
+export class AppConnection {
+    options;
+    identity;
+    registration;
+    problem;
+    links = [];
+    heartbeat;
+    heartbeatTimer;
+    dashboardUrl = DEFAULT_DASHBOARD_URL;
+    running = false;
+    /** Serializes start, reload and stop. */
+    queue = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+    }
+    /** Loads the link and connects when the project is linked. */
+    async start() {
+        await this.serialize(async () => {
+            this.running = true;
+            await this.load();
+        });
+    }
+    /** Re-reads the link after `ptbk connect` or `ptbk disconnect`. */
+    async reload() {
+        await this.serialize(async () => {
+            if (!this.running)
+                return;
+            this.disconnect();
+            await this.load();
+        });
+        return this.view();
+    }
+    /** Closes every tunnel and stops the heartbeat. */
+    async stop() {
+        await this.serialize(async () => {
+            this.running = false;
+            this.disconnect();
+        });
+    }
+    /** Runs one lifecycle step after the previous one. */
+    async serialize(step) {
+        const next = this.queue.then(step, step);
+        this.queue = next.catch(() => undefined);
+        await next;
+    }
+    /** Reads settings, identity and registration, then connects when linked. */
+    async load() {
+        this.problem = undefined;
+        this.identity = undefined;
+        this.registration = undefined;
+        this.heartbeat = undefined;
+        try {
+            const settings = appSettings(this.options.env);
+            this.dashboardUrl = settings.dashboardUrl;
+            this.identity = await loadEngineIdentity(this.options.directory, { create: false });
+            this.registration = await readRegistration(this.options.directory, this.identity, settings);
+            if (this.registration && this.identity)
+                this.connect(this.identity, this.registration, settings.relays);
+        }
+        catch (error) {
+            this.problem = errorMessage(error);
+            this.options.log?.(`The App connection is not available: ${this.problem}`, 'error');
+        }
+        this.options.onChange();
+    }
+    /** Starts the relay links and the heartbeat loop. */
+    connect(identity, registration, override) {
+        const version = engineVersion();
+        const relays = override ?? registration.relays.map((id) => ({ id, port: 443 }));
+        this.links = relays.map((relay) => new RelayLink({
+            relay,
+            identity,
+            version,
+            env: this.options.env,
+            onChange: this.options.onChange,
+            onStream: this.options.onStream,
+            log: this.options.log,
+            tls: this.options.tls,
+        }));
+        for (const link of this.links)
+            link.start();
+        const beat = async () => {
+            try {
+                const figures = this.options.figures();
+                const host = await hostFigures(this.options.directory);
+                const seq = await nextHeartbeatSeq(this.options.directory);
+                const body = buildHeartbeat({ engineId: identity.engineId, seq, ts: new Date().toISOString(), version, uptimeS: process.uptime(), ...host, ...figures });
+                const result = await sendHeartbeat({ identity, dashboardUrl: registration.dashboardUrl, body, env: this.options.env, tls: this.options.tls });
+                if (!this.running || this.registration !== registration)
+                    return;
+                this.heartbeat = { ...result, nextAt: new Date(Date.now() + (this.options.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS)).toISOString() };
+                if (result.outcome !== 'accepted')
+                    this.options.log?.(`The App heartbeat was ${result.outcome === 'refused' ? `refused (HTTP ${String(result.status)}${result.code ? `, ${result.code}` : ''})` : 'not delivered'}.`, 'warning');
+            }
+            catch (error) {
+                this.heartbeat = { at: new Date().toISOString(), outcome: 'failed', body: '', message: errorMessage(error) };
+            }
+            this.options.onChange();
+        };
+        void beat();
+        this.heartbeatTimer = setInterval(() => void beat(), this.options.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS);
+        this.heartbeatTimer.unref();
+    }
+    /** Stops every link and the heartbeat. */
+    disconnect() {
+        clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = undefined;
+        for (const link of this.links)
+            link.stop();
+        this.links = [];
+    }
+    /** The App page's view of this connection (no secrets: no key, signature or link code). */
+    view() {
+        const identity = this.identity;
+        const registration = this.registration;
+        const relays = this.links.map((link) => link.view());
+        const connected = relays.filter((relay) => relay.state === 'connected').length;
+        const refusal = relays.find((relay) => relay.refusal)?.refusal;
+        const state = this.problem ? 'problem' : !registration ? 'unlinked' : connected ? 'linked' : refusal || this.heartbeat?.code === 'engine-suspended' ? 'refused' : 'connecting';
+        return {
+            state,
+            dashboardUrl: registration?.dashboardUrl ?? this.dashboardUrl,
+            ...(identity ? { engineId: identity.engineId, fingerprint: identity.fingerprint.formatted } : {}),
+            ...(registration ? { hostname: registration.hostname, url: `https://${registration.hostname}/`, linkedAt: registration.registeredAt } : {}),
+            relays,
+            ...(this.heartbeat ? { heartbeat: this.heartbeat } : {}),
+            browserAccess: 'unavailable',
+            ...(this.problem ? { problem: this.problem } : {}),
+        };
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/app/connection.js.map

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

package/dist/app/encoding.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Byte encodings of the App platform protocol (`@ptbk/protocol` in `webgptorg/app`, ported natively because `ptbk`
+ * ships without runtime dependencies). Each byte string has exactly one accepted encoding: decoders refuse anything
+ * an encoder would not produce, so a signed value can never be read two ways.
+ */
+/**
+ * Encodes bytes as RFC 4648 §5 base64url without padding.
+ *
+ * @private App platform protocol
+ */
+export declare function encodeBase64Url(bytes: Uint8Array): string;
+/**
+ * Decodes canonical base64url: no padding, `+`, `/` or whitespace, no length ≡ 1 (mod 4) and zero unused trailing
+ * bits. Returns `undefined` for anything else.
+ *
+ * @private App platform protocol
+ */
+export declare function decodeBase64Url(text: string): Uint8Array | undefined;
+/**
+ * Whether a text is the canonical base64url of exactly `length` bytes.
+ *
+ * @private App platform protocol
+ */
+export declare function isBase64UrlOfLength(text: unknown, length: number): text is string;
+/**
+ * Encodes bytes as lowercase RFC 4648 base32 without padding.
+ *
+ * @private App platform protocol
+ */
+export declare function encodeBase32Lower(bytes: Uint8Array): string;
+/**
+ * Encodes a string of `0`/`1` bits (a multiple of five long) in Crockford base32.
+ *
+ * @private App platform protocol
+ */
+export declare function encodeCrockfordBits(bits: string): string;
+/**
+ * UTF-8 bytes of a text.
+ *
+ * @private App platform protocol
+ */
+export declare function utf8(text: string): Uint8Array;
+/**
+ * Concatenates byte strings.
+ *
+ * @private App platform protocol
+ */
+export declare function concatBytes(...parts: readonly Uint8Array[]): Uint8Array;

package/dist/app/encoding.js

@@ -0,0 +1,133 @@
+/**
+ * Byte encodings of the App platform protocol (`@ptbk/protocol` in `webgptorg/app`, ported natively because `ptbk`
+ * ships without runtime dependencies). Each byte string has exactly one accepted encoding: decoders refuse anything
+ * an encoder would not produce, so a signed value can never be read two ways.
+ */
+/**
+ * Alphabet of RFC 4648 §5 base64url.
+ */
+const BASE64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+/**
+ * Character code → 6-bit value of base64url, or -1.
+ */
+const BASE64URL_VALUES = new Int8Array(128).fill(-1);
+for (let value = 0; value < BASE64URL_ALPHABET.length; value++)
+    BASE64URL_VALUES[BASE64URL_ALPHABET.charCodeAt(value)] = value;
+/**
+ * Lowercase RFC 4648 §6 base32 alphabet (engine IDs and link codes).
+ */
+const BASE32_LOWER_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+/**
+ * Crockford base32 alphabet of the engine fingerprint code.
+ */
+const CROCKFORD_BASE32_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/**
+ * Encodes bytes as RFC 4648 §5 base64url without padding.
+ *
+ * @private App platform protocol
+ */
+export function encodeBase64Url(bytes) {
+    let text = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const chunk = ((bytes[index] ?? 0) << 16) | ((bytes[index + 1] ?? 0) << 8) | (bytes[index + 2] ?? 0);
+        const chars = Math.min(bytes.length - index, 3) + 1;
+        for (let char = 0; char < chars; char++)
+            text += BASE64URL_ALPHABET.charAt((chunk >>> (18 - 6 * char)) & 0x3f);
+    }
+    return text;
+}
+/**
+ * Decodes canonical base64url: no padding, `+`, `/` or whitespace, no length ≡ 1 (mod 4) and zero unused trailing
+ * bits. Returns `undefined` for anything else.
+ *
+ * @private App platform protocol
+ */
+export function decodeBase64Url(text) {
+    if (text.length % 4 === 1)
+        return undefined;
+    const bytes = new Uint8Array(Math.floor((text.length * 3) / 4));
+    let buffer = 0;
+    let bits = 0;
+    let offset = 0;
+    for (let index = 0; index < text.length; index++) {
+        const code = text.charCodeAt(index);
+        const value = code < 128 ? (BASE64URL_VALUES[code] ?? -1) : -1;
+        if (value < 0)
+            return undefined;
+        buffer = ((buffer << 6) | value) & 0xfff;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes[offset++] = (buffer >>> bits) & 0xff;
+        }
+    }
+    if ((buffer & ((1 << bits) - 1)) !== 0)
+        return undefined;
+    return bytes;
+}
+/**
+ * Whether a text is the canonical base64url of exactly `length` bytes.
+ *
+ * @private App platform protocol
+ */
+export function isBase64UrlOfLength(text, length) {
+    if (typeof text !== 'string' || text.length !== Math.ceil((length * 4) / 3))
+        return false;
+    return decodeBase64Url(text)?.length === length;
+}
+/**
+ * Encodes bytes as lowercase RFC 4648 base32 without padding.
+ *
+ * @private App platform protocol
+ */
+export function encodeBase32Lower(bytes) {
+    let text = '';
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buffer = ((buffer << 8) | byte) & 0xfff;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            text += BASE32_LOWER_ALPHABET.charAt((buffer >>> bits) & 0x1f);
+        }
+    }
+    if (bits > 0)
+        text += BASE32_LOWER_ALPHABET.charAt((buffer << (5 - bits)) & 0x1f);
+    return text;
+}
+/**
+ * Encodes a string of `0`/`1` bits (a multiple of five long) in Crockford base32.
+ *
+ * @private App platform protocol
+ */
+export function encodeCrockfordBits(bits) {
+    let text = '';
+    for (let offset = 0; offset + 5 <= bits.length; offset += 5)
+        text += CROCKFORD_BASE32_ALPHABET.charAt(Number.parseInt(bits.slice(offset, offset + 5), 2));
+    return text;
+}
+/**
+ * UTF-8 bytes of a text.
+ *
+ * @private App platform protocol
+ */
+export function utf8(text) {
+    return new Uint8Array(Buffer.from(text, 'utf8'));
+}
+/**
+ * Concatenates byte strings.
+ *
+ * @private App platform protocol
+ */
+export function concatBytes(...parts) {
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const result = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.length;
+    }
+    return result;
+}
+//# sourceMappingURL=encoding.js.map

package/dist/app/encoding.js.map

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

package/dist/app/files.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Refuses an App data directory or file that is a symbolic link, of the wrong type, owned by another user or
+ * accessible to group or others. Names the path and mode, never the content.
+ *
+ * @private App connection
+ */
+export declare function assertPrivate(path: string, kind: 'directory' | 'file'): Promise<void>;
+/**
+ * Creates the App data directory (mode 0700) when missing and checks that it is private.
+ *
+ * @private App connection
+ */
+export declare function ensurePrivateDirectory(path: string): Promise<void>;
+/**
+ * Flushes a directory entry (skipped where the platform cannot open directories).
+ *
+ * @private App connection
+ */
+export declare function syncDirectory(directory: string): Promise<void>;
+/**
+ * Writes a new private file (mode 0600) exclusively, flushing it and then its directory. Fails with `EEXIST` when the
+ * file exists.
+ *
+ * @private App connection
+ */
+export declare function createPrivateFile(directory: string, name: string, content: string | Uint8Array): Promise<void>;
+/**
+ * Replaces a private file durably: a fresh 0600 temporary file is written and flushed, renamed over the target and
+ * the directory is flushed, so a crash leaves either the old or the new content.
+ *
+ * @private App connection
+ */
+export declare function writePrivateFile(directory: string, name: string, content: string): Promise<void>;
+/**
+ * Reads a private file after checking it, or `undefined` when it does not exist.
+ *
+ * @private App connection
+ */
+export declare function readPrivateFile(directory: string, name: string): Promise<string | undefined>;
+/**
+ * Removes a private file when it exists, flushing the directory.
+ *
+ * @private App connection
+ */
+export declare function removePrivateFile(directory: string, name: string): Promise<void>;

package/dist/app/files.js

@@ -0,0 +1,139 @@
+import { randomBytes } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PtbkError } from '../common/errors.js';
+/**
+ * Whether POSIX ownership and modes protect files on this platform.
+ */
+const POSIX_MODES = process.platform !== 'win32';
+/**
+ * Refuses an App data directory or file that is a symbolic link, of the wrong type, owned by another user or
+ * accessible to group or others. Names the path and mode, never the content.
+ *
+ * @private App connection
+ */
+export async function assertPrivate(path, kind) {
+    const stats = await lstat(path);
+    if (stats.isSymbolicLink())
+        throw new PtbkError(`The App connection refuses ${path}: it is a symbolic link.`, { kind: 'configuration' });
+    if (kind === 'directory' ? !stats.isDirectory() : !stats.isFile())
+        throw new PtbkError(`The App connection refuses ${path}: it is not a ${kind === 'directory' ? 'directory' : 'regular file'}.`, { kind: 'configuration' });
+    if (!POSIX_MODES)
+        return;
+    const uid = process.getuid?.();
+    if (uid !== undefined && stats.uid !== uid)
+        throw new PtbkError(`The App connection refuses ${path}: it is owned by user ${String(stats.uid)}, not by this engine's user ${String(uid)}.`, { kind: 'configuration' });
+    const mode = stats.mode & 0o777;
+    if (mode & 0o077)
+        throw new PtbkError(`The App connection refuses ${path}: its mode is ${mode.toString(8).padStart(4, '0')}; it must not be accessible to group or others (${kind === 'directory' ? '0700' : '0600'}).`, { kind: 'configuration' });
+}
+/**
+ * Creates the App data directory (mode 0700) when missing and checks that it is private.
+ *
+ * @private App connection
+ */
+export async function ensurePrivateDirectory(path) {
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        await mkdir(path, { recursive: true, mode: 0o700 });
+        if (POSIX_MODES)
+            await chmod(path, 0o700);
+    }
+    await assertPrivate(path, 'directory');
+}
+/**
+ * Flushes a directory entry (skipped where the platform cannot open directories).
+ *
+ * @private App connection
+ */
+export async function syncDirectory(directory) {
+    if (!POSIX_MODES)
+        return;
+    const handle = await open(directory, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Writes a new private file (mode 0600) exclusively, flushing it and then its directory. Fails with `EEXIST` when the
+ * file exists.
+ *
+ * @private App connection
+ */
+export async function createPrivateFile(directory, name, content) {
+    const handle = await open(join(directory, name), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        await handle.writeFile(content);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await syncDirectory(directory);
+}
+/**
+ * Replaces a private file durably: a fresh 0600 temporary file is written and flushed, renamed over the target and
+ * the directory is flushed, so a crash leaves either the old or the new content.
+ *
+ * @private App connection
+ */
+export async function writePrivateFile(directory, name, content) {
+    const temporary = `.${name}.${randomBytes(6).toString('hex')}.tmp`;
+    await createPrivateFile(directory, temporary, content);
+    try {
+        for (let attempt = 1;; attempt++) {
+            try {
+                await rename(join(directory, temporary), join(directory, name));
+                break;
+            }
+            catch (error) {
+                const code = error.code ?? '';
+                if (!['EPERM', 'EACCES', 'EBUSY'].includes(code) || attempt >= 8)
+                    throw error;
+                await new Promise((resolve) => setTimeout(resolve, 25 * attempt));
+            }
+        }
+    }
+    catch (error) {
+        await rm(join(directory, temporary), { force: true }).catch(() => undefined);
+        throw error;
+    }
+    await syncDirectory(directory);
+}
+/**
+ * Reads a private file after checking it, or `undefined` when it does not exist.
+ *
+ * @private App connection
+ */
+export async function readPrivateFile(directory, name) {
+    const path = join(directory, name);
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    await assertPrivate(directory, 'directory');
+    await assertPrivate(path, 'file');
+    return await readFile(path, 'utf8');
+}
+/**
+ * Removes a private file when it exists, flushing the directory.
+ *
+ * @private App connection
+ */
+export async function removePrivateFile(directory, name) {
+    await rm(join(directory, name), { force: true });
+    await syncDirectory(directory).catch(() => undefined);
+}
+//# sourceMappingURL=files.js.map