@north-light/api 0.3.580 → 0.3.587

package/dist/core/directory/person-credential.d.ts

@@ -0,0 +1,61 @@
+import { CrtrError } from '../errors.js';
+export declare const personCredentialPath: () => string;
+export declare const personBearerPath: () => string;
+/** What the credential file holds: the secret and the directory that issued it (a Mac needs the directory before it has a `machine.json`). */
+export interface PersonCredential {
+    directoryUrl: string;
+    secret: string;
+}
+export declare const notSignedIn: (why: string) => CrtrError;
+export declare function readPersonCredential(): PersonCredential | undefined;
+export interface SignInPrompt {
+    verificationUri: string;
+    userCode: string;
+}
+/** What the directory approved: the account, and a bearer the new secret was just exchanged for (not cached until `signIn` writes it). */
+export interface ApprovedSignIn {
+    account: {
+        id: string;
+        display: string;
+    };
+    bearer: string;
+}
+export interface SignInOptions {
+    sleep?: (ms: number) => Promise<void>;
+    /** Called after approval and before anything is written. A returned error refuses the sign-in: the new credential is revoked at the directory,
+     *  nothing is written, and `signIn` throws that error. */
+    accept?: (approved: ApprovedSignIn) => Promise<CrtrError | undefined>;
+}
+/** Pair this computer with the directory: start a developer login of kind `crtr`, show the code, poll until the person allows it, then store the secret.
+ *  Nothing durable is written until the directory has approved, so an abandoned sign-in leaves the previous state untouched. */
+export declare function signIn(directoryUrl: string, show: (prompt: SignInPrompt & {
+    complete: string;
+}) => void, opts?: SignInOptions): Promise<{
+    account: string;
+    credentialId: string;
+}>;
+/** A person bearer for the control plane: the cached one while it has more than 30 seconds left, else a fresh exchange of the stored secret.
+ *  A revoked, expired or unknown credential is `not_signed_in`. */
+export declare function personBearer(directoryUrl?: string): Promise<string>;
+/** A `fetch` for the control plane at `apiUrl`: each request carries the person's bearer for `directoryUrl` (fetched per request, so a long command never sends
+ *  an ended one), a sign-in refusal crosses as its own `CrtrError`, and a request that never got an HTTP answer is `northlight_unreachable` (a caller's own abort
+ *  stays what it was). */
+export declare function northlightFetch(directoryUrl: string, apiUrl: string): typeof fetch;
+/** The account the stored sign-in acts as: a fresh exchange (the token answer names it), whose bearer is cached like `personBearer`'s. */
+export declare function personAccount(directoryUrl?: string): Promise<{
+    id: string;
+    display: string;
+}>;
+/** The control plane a person bearer is good for: its `aud`, which the directory signs as its `CRTR_PUBLIC_API_URL` (design D6). */
+export declare function controlPlaneUrl(directoryUrl?: string): Promise<string>;
+/** Delete the stored credential and cached bearer without calling the directory. */
+export declare function forgetSignIn(): void;
+/** Revoke the stored credential at the directory (best effort when it is already gone) and delete both files. Returns whether one was stored. */
+export declare function signOut(): Promise<{
+    signedOut: boolean;
+    revoked: boolean;
+}>;
+/** The sign-in a command needs when the person has none yet: pairs once with `directoryUrl`, then returns a bearer. */
+export declare function ensureSignedIn(directoryUrl: string, show: (prompt: SignInPrompt & {
+    complete: string;
+}) => void): Promise<string>;

package/dist/core/directory/person-credential.js

@@ -0,0 +1,220 @@
+// The person's own sign-in on this computer (proposal-mac-cli-auth, option A): a developer-login device pairing with the directory
+// (`kind: "crtr"`) that stores a revocable secret at `runtime/secrets/person-credential` (0600) and exchanges it for 5-minute person
+// bearers the control plane accepts. The bearer is cached at `runtime/secrets/person-bearer.json` (0600) until 30 seconds before it ends.
+// The calls and the `nld_` secret format mirror `packages/crouter-sdk/src/directory-client.ts` (the CLI does not import the SDK).
+import { createHash, randomBytes } from 'node:crypto';
+import { renameSync, rmSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { CrtrError, general } from '../errors.js';
+import { atomicWriteJson, readJsonOrNull } from '../fs-utils.js';
+import { secretsDir } from '../layout.js';
+import { ExitCode } from '../../types.js';
+import { northlightUnreachable } from './reach.js';
+export const personCredentialPath = () => join(secretsDir(), 'person-credential');
+export const personBearerPath = () => join(secretsDir(), 'person-bearer.json');
+const pendingPath = () => join(secretsDir(), 'person-credential.pending');
+const REFRESH_MARGIN_MS = 30_000;
+const sha256Hex = (text) => createHash('sha256').update(text).digest('hex');
+const trimUrl = (url) => url.replace(/\/+$/, '');
+export const notSignedIn = (why) => new CrtrError('not_signed_in', why, ExitCode.USAGE, { next: 'Run `crtr sys signin`, then retry.' });
+export function readPersonCredential() {
+    const raw = readJsonOrNull(personCredentialPath());
+    if (raw === null || typeof raw.secret !== 'string' || typeof raw.directoryUrl !== 'string')
+        return undefined;
+    return { directoryUrl: raw.directoryUrl, secret: raw.secret };
+}
+function errorOf(body, status) {
+    const record = (body !== null && typeof body === 'object' ? body : {});
+    const error = record['error'];
+    if (error !== null && typeof error === 'object') {
+        const e = error;
+        return { code: String(e['code'] ?? 'error'), message: String(e['message'] ?? `HTTP ${status}`) };
+    }
+    if (typeof error === 'string')
+        return { code: error, message: String(record['error_description'] ?? record['message'] ?? error) };
+    return { code: 'error', message: `the directory answered HTTP ${status}` };
+}
+async function call(directoryUrl, path, body, secret) {
+    let response;
+    try {
+        response = await fetch(`${trimUrl(directoryUrl)}${path}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...(secret === undefined ? {} : { authorization: `Bearer ${secret}` }) },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (error) {
+        throw northlightUnreachable(error, directoryUrl);
+    }
+    const text = await response.text();
+    let parsed = {};
+    try {
+        parsed = text === '' ? {} : JSON.parse(text);
+    }
+    catch { /* an HTML or empty error page reads as no body */ }
+    return { status: response.status, body: parsed };
+}
+const refuse = (status, body) => {
+    const e = errorOf(body, status);
+    throw general(`the directory refused: ${e.message}`, { code: e.code });
+};
+/** Pair this computer with the directory: start a developer login of kind `crtr`, show the code, poll until the person allows it, then store the secret.
+ *  Nothing durable is written until the directory has approved, so an abandoned sign-in leaves the previous state untouched. */
+export async function signIn(directoryUrl, show, opts = {}) {
+    const directory = trimUrl(directoryUrl);
+    const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const secret = `nld_${randomBytes(32).toString('base64url')}`;
+    const started = await call(directory, '/v1/developer/logins', {
+        credential_hash: sha256Hex(secret), name: hostname().slice(0, 64),
+        platform: process.platform === 'darwin' || process.platform === 'win32' ? process.platform : 'linux', sdk_version: 'crtr', kind: 'crtr',
+    });
+    if (started.status !== 200 && started.status !== 201)
+        refuse(started.status, started.body);
+    const login = started.body;
+    show({ verificationUri: login.verification_uri, userCode: login.user_code, complete: login.verification_uri_complete });
+    let interval = Math.max(1, login.interval) * 1000;
+    const deadline = Date.now() + login.expires_in * 1000;
+    for (;;) {
+        if (Date.now() > deadline)
+            throw general('the sign-in code expired before it was allowed: run `crtr sys signin` again', { code: 'expired_token' });
+        await sleep(interval);
+        const polled = await call(directory, '/v1/developer/logins/poll', { device_code: login.device_code });
+        if (polled.status === 200) {
+            const approved = polled.body;
+            // The new secret must exchange before it replaces a working sign-in; a failed exchange leaves both files as they were.
+            const bearer = await exchange(directory, secret);
+            const refusal = await opts.accept?.({ account: approved.account, bearer: bearer.access_token });
+            if (refusal !== undefined) {
+                await revoke(directory, secret);
+                throw refusal;
+            }
+            atomicWriteJson(pendingPath(), { directoryUrl: directory, secret }, { mode: 0o600 });
+            renameSync(pendingPath(), personCredentialPath());
+            writeBearer(directory, bearer);
+            return { account: approved.account.display, credentialId: approved.credential_id };
+        }
+        const code = errorOf(polled.body, polled.status).code;
+        if (polled.status === 400 && code === 'authorization_pending')
+            continue;
+        if (polled.status === 400 && code === 'slow_down') {
+            interval += 5000;
+            continue;
+        }
+        if (polled.status === 400 && code === 'access_denied')
+            throw general('the sign-in was declined in the browser', { code });
+        if (polled.status === 400 && code === 'expired_token')
+            throw general('the sign-in code expired before it was allowed: run `crtr sys signin` again', { code });
+        refuse(polled.status, polled.body);
+    }
+}
+const REVOKED = new Set(['credential_revoked', 'credential_expired', 'credential_unknown']);
+/** Exchange a secret for a person bearer at the directory. A revoked, expired or unknown credential is `not_signed_in`. */
+async function exchange(directory, secret, invalidateCached = false) {
+    const answer = await call(directory, '/v1/developer/token', {}, secret);
+    if (answer.status === 401 && REVOKED.has(errorOf(answer.body, 401).code)) {
+        if (invalidateCached)
+            rmSync(personBearerPath(), { force: true });
+        throw notSignedIn(`the sign-in on this computer is no longer valid (${errorOf(answer.body, 401).code})`);
+    }
+    if (answer.status !== 200)
+        refuse(answer.status, answer.body);
+    const body = answer.body;
+    if (typeof body.access_token !== 'string' || typeof body.expires_in !== 'number')
+        throw general('the directory answered without a bearer token');
+    const account = body.account;
+    return { access_token: body.access_token, expires_in: body.expires_in,
+        ...(typeof account?.id === 'string' && typeof account.display === 'string' ? { account: { id: account.id, display: account.display } } : {}) };
+}
+function writeBearer(directory, bearer) {
+    atomicWriteJson(personBearerPath(), { directoryUrl: directory, access_token: bearer.access_token, expires_at_ms: Date.now() + bearer.expires_in * 1000 }, { mode: 0o600 });
+}
+/** A person bearer for the control plane: the cached one while it has more than 30 seconds left, else a fresh exchange of the stored secret.
+ *  A revoked, expired or unknown credential is `not_signed_in`. */
+export async function personBearer(directoryUrl) {
+    const credential = readPersonCredential();
+    if (credential === undefined)
+        throw notSignedIn('this computer is not signed in');
+    const directory = trimUrl(directoryUrl ?? credential.directoryUrl);
+    const cached = readJsonOrNull(personBearerPath());
+    if (cached !== null && cached.directoryUrl === directory && typeof cached.access_token === 'string' && cached.expires_at_ms - Date.now() > REFRESH_MARGIN_MS)
+        return cached.access_token;
+    const bearer = await exchange(directory, credential.secret, true);
+    writeBearer(directory, bearer);
+    return bearer.access_token;
+}
+/** A `fetch` for the control plane at `apiUrl`: each request carries the person's bearer for `directoryUrl` (fetched per request, so a long command never sends
+ *  an ended one), a sign-in refusal crosses as its own `CrtrError`, and a request that never got an HTTP answer is `northlight_unreachable` (a caller's own abort
+ *  stays what it was). */
+export function northlightFetch(directoryUrl, apiUrl) {
+    return async (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set('authorization', `Bearer ${await personBearer(directoryUrl)}`);
+        try {
+            return await fetch(input, { ...init, headers });
+        }
+        catch (error) {
+            if (init?.signal?.aborted === true)
+                throw error;
+            throw northlightUnreachable(error, apiUrl);
+        }
+    };
+}
+/** The account the stored sign-in acts as: a fresh exchange (the token answer names it), whose bearer is cached like `personBearer`'s. */
+export async function personAccount(directoryUrl) {
+    const credential = readPersonCredential();
+    if (credential === undefined)
+        throw notSignedIn('this computer is not signed in');
+    const directory = trimUrl(directoryUrl ?? credential.directoryUrl);
+    const bearer = await exchange(directory, credential.secret, true);
+    writeBearer(directory, bearer);
+    if (bearer.account === undefined)
+        throw general('the directory\'s token answer names no account');
+    return bearer.account;
+}
+/** The control plane a person bearer is good for: its `aud`, which the directory signs as its `CRTR_PUBLIC_API_URL` (design D6). */
+export async function controlPlaneUrl(directoryUrl) {
+    const token = await personBearer(directoryUrl);
+    let aud;
+    try {
+        aud = JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString('utf8')).aud;
+    }
+    catch {
+        aud = undefined;
+    }
+    const url = Array.isArray(aud) ? aud[0] : aud;
+    if (typeof url !== 'string' || !/^https?:\/\//.test(url))
+        throw general('the directory\'s sign-in token names no control plane (no http(s) `aud`)');
+    return trimUrl(url);
+}
+/** Revoke a secret at the directory. True when it ended now; false when it was already ended. */
+async function revoke(directory, secret) {
+    const answer = await call(directory, '/v1/developer/token/revoke', {}, secret);
+    if (answer.status === 200)
+        return true;
+    if (answer.status === 401 && REVOKED.has(errorOf(answer.body, 401).code))
+        return false;
+    return refuse(answer.status, answer.body);
+}
+/** Delete the stored credential and cached bearer without calling the directory. */
+export function forgetSignIn() {
+    rmSync(personCredentialPath(), { force: true });
+    rmSync(personBearerPath(), { force: true });
+}
+/** Revoke the stored credential at the directory (best effort when it is already gone) and delete both files. Returns whether one was stored. */
+export async function signOut() {
+    const credential = readPersonCredential();
+    if (credential === undefined) {
+        return { signedOut: false, revoked: false };
+    }
+    const revoked = await revoke(credential.directoryUrl, credential.secret);
+    forgetSignIn();
+    return { signedOut: true, revoked };
+}
+/** The sign-in a command needs when the person has none yet: pairs once with `directoryUrl`, then returns a bearer. */
+export async function ensureSignedIn(directoryUrl, show) {
+    if (readPersonCredential() === undefined)
+        await signIn(directoryUrl, show);
+    return personBearer(directoryUrl);
+}

package/dist/core/directory/reach.d.ts

@@ -0,0 +1,3 @@
+import { CrtrError } from '../errors.js';
+export declare const NORTHLIGHT_UNREACHABLE = "northlight_unreachable";
+export declare function northlightUnreachable(cause: unknown, url: string): CrtrError;

package/dist/core/directory/reach.js

@@ -0,0 +1,19 @@
+// The one error for "this computer cannot reach Northlight". Only a request that never got an HTTP answer counts
+// (DNS, refused, reset, TLS, timeout — a fetch that throws, or a relay's socket error); an HTTP answer, even a 5xx, is not one.
+import { CrtrError } from '../errors.js';
+import { ExitCode } from '../../types.js';
+export const NORTHLIGHT_UNREACHABLE = 'northlight_unreachable';
+const NEXT = "Check this computer's internet connection, then retry.";
+/** Node's fetch reports the real reason on `error.cause` (`ECONNREFUSED`, `ENOTFOUND`, …); `error.message` is only "fetch failed". */
+function causeText(cause) {
+    const inner = cause?.cause;
+    const own = cause;
+    for (const candidate of [inner?.code, inner?.message, own?.code, own?.message])
+        if (typeof candidate === 'string' && candidate !== '')
+            return candidate;
+    return String(cause);
+}
+export function northlightUnreachable(cause, url) {
+    const message = `crtr cannot reach Northlight (${new URL(url).host}): ${causeText(cause)}.`;
+    return new CrtrError(NORTHLIGHT_UNREACHABLE, message, ExitCode.NETWORK, { next: NEXT });
+}

package/dist/core/document-lines.d.ts

@@ -0,0 +1,4 @@
+/** The document's logical lines: a single terminating newline closes the last
+ *  line rather than opening an empty one. Never empty — an empty document is
+ *  one empty line. */
+export declare function documentLines(text: string): string[];

package/dist/core/document-lines.js

@@ -0,0 +1,6 @@
+/** The document's logical lines: a single terminating newline closes the last
+ *  line rather than opening an empty one. Never empty — an empty document is
+ *  one empty line. */
+export function documentLines(text) {
+    return (text.endsWith('\n') ? text.slice(0, -1) : text).split('\n');
+}

package/dist/core/editor-resolver.d.ts

@@ -0,0 +1,28 @@
+/** Candidates tried, in order, when neither $VISUAL nor $EDITOR is set. */
+export declare const FALLBACK_EDITORS: readonly ["nano", "pico", "micro", "nvim", "vim", "vi"];
+export interface ResolvedEditor {
+    /** Shell fragment to run, e.g. `code --wait` or `nano`. */
+    command: string;
+    /** `env` = the person's $VISUAL/$EDITOR; `fallback` = we picked it. */
+    source: 'env' | 'fallback';
+    /** Short, human hint to show after a fallback was used; undefined for `env`. */
+    hint?: string;
+}
+export declare const NO_EDITOR_MESSAGE = "No text editor found \u2014 install nano (macOS: brew install nano; Debian/Ubuntu: apt install nano) or set $EDITOR";
+/** First-token basename of an editor fragment: `/usr/bin/nvim -p` → `nvim`. */
+export declare function editorBasename(fragment: string): string;
+export declare function isViFamilyEditor(fragment: string): boolean;
+/** Is `name` an executable file on `pathEnv`? */
+export declare function executableOnPath(name: string, pathEnv?: string | undefined): boolean;
+/**
+ * Resolve the editor to launch, or null when none is installed.
+ * `available` is injectable so tests need no real binaries.
+ */
+export declare function resolveEditor(env?: Record<string, string | undefined>, available?: (name: string) => boolean): ResolvedEditor | null;
+/**
+ * Show the fallback editor's guidance before it takes over the screen, and
+ * pause for Enter so a full-screen editor (vi uses the alternate screen) cannot
+ * erase it unread. Call after the host TUI has released the terminal. No-op for
+ * the person's own $VISUAL/$EDITOR.
+ */
+export declare function announceFallbackEditor(resolved: ResolvedEditor, write?: (text: string) => void, wait?: () => void): void;

package/dist/core/editor-resolver.js

@@ -0,0 +1,77 @@
+// One resolver for "which text editor do we open?" — used by Control+G in the
+// viewer and by document review's `e` / the comment round-trip. The person's
+// own $VISUAL / $EDITOR always wins; with neither set we pick an installed
+// editor a newcomer can leave without vim knowledge (nano first, vi last)
+// rather than failing or dropping them into vi.
+import { accessSync, constants, readSync, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+/** Candidates tried, in order, when neither $VISUAL nor $EDITOR is set. */
+export const FALLBACK_EDITORS = ['nano', 'pico', 'micro', 'nvim', 'vim', 'vi'];
+const VI_FAMILY = new Set(['nvim', 'vim', 'vi', 'view']);
+export const NO_EDITOR_MESSAGE = 'No text editor found — install nano (macOS: brew install nano; Debian/Ubuntu: apt install nano) or set $EDITOR';
+/** First-token basename of an editor fragment: `/usr/bin/nvim -p` → `nvim`. */
+export function editorBasename(fragment) {
+    const first = fragment.trim().split(/\s+/)[0] ?? '';
+    return first.split('/').pop() || first;
+}
+export function isViFamilyEditor(fragment) {
+    return VI_FAMILY.has(editorBasename(fragment));
+}
+/** Is `name` an executable file on `pathEnv`? */
+export function executableOnPath(name, pathEnv = process.env['PATH']) {
+    for (const dir of (pathEnv ?? '').split(delimiter)) {
+        if (dir === '')
+            continue;
+        try {
+            const file = join(dir, name);
+            if (!statSync(file).isFile())
+                continue; // a directory named like an editor is not one
+            accessSync(file, constants.X_OK);
+            return true;
+        }
+        catch { /* try the next PATH entry */ }
+    }
+    return false;
+}
+/**
+ * Resolve the editor to launch, or null when none is installed.
+ * `available` is injectable so tests need no real binaries.
+ */
+export function resolveEditor(env = process.env, available = (name) => executableOnPath(name, env['PATH'])) {
+    const configured = (env['VISUAL'] ?? '').trim() || (env['EDITOR'] ?? '').trim();
+    if (configured !== '')
+        return { command: configured, source: 'env' };
+    for (const name of FALLBACK_EDITORS) {
+        if (!available(name))
+            continue;
+        const quitHint = VI_FAMILY.has(name) ? ' — :wq saves and quits, :q! quits without saving' : '';
+        return { command: name, source: 'fallback', hint: `Used ${name}; set $EDITOR to choose another${quitHint}` };
+    }
+    return null;
+}
+/** Block until the person presses Enter (cooked-mode terminal, host TUI stopped). */
+function waitForEnter() {
+    const buf = Buffer.alloc(256);
+    try {
+        // Read until a newline arrives; EOF or a closed/unreadable stdin never blocks the launch.
+        for (;;) {
+            const n = readSync(0, buf, 0, buf.length, null);
+            if (n === 0 || buf.subarray(0, n).includes(0x0a))
+                return;
+        }
+    }
+    catch { /* no readable stdin: carry on without the pause */ }
+}
+/**
+ * Show the fallback editor's guidance before it takes over the screen, and
+ * pause for Enter so a full-screen editor (vi uses the alternate screen) cannot
+ * erase it unread. Call after the host TUI has released the terminal. No-op for
+ * the person's own $VISUAL/$EDITOR.
+ */
+export function announceFallbackEditor(resolved, write = (text) => { process.stdout.write(text); }, wait = waitForEnter) {
+    if (resolved.source !== 'fallback' || resolved.hint === undefined)
+        return;
+    write(`\n${resolved.hint}\nPress Enter to open ${editorBasename(resolved.command)}… `);
+    wait();
+    write('\n');
+}

package/dist/core/environments.d.ts

@@ -0,0 +1,21 @@
+import type { CanvasDb } from './canvas/db.js';
+/** Find the `environments` row for `installId`, or create its object and row; either way set `last_seen_at`, and cache
+ *  the environment id and install id for {@link machineEnvironmentId} and {@link touchMachineEnvironment}. */
+export declare function registerMachineEnvironment(installId: string): Promise<{
+    environmentId: string;
+    created: boolean;
+}>;
+/** A cloud profile's own `blaxel` environment (D105): an `environment` object owned by the profile's object, acting for `person`, and
+ *  its `environments` row with the default `memory_mb` (2048), no recipe (so the Blaxel base image) and no machine id. Runs in the
+ *  caller's write, before the profile row exists, so the profile and its environment commit together. The profile object is made
+ *  here under `grantee`'s app, with the profile id as its handle: a cloud role serves many people and a profile name is not unique
+ *  across them, while the handle is unique per object type. Returns the environment's object id. */
+export declare function createProfileBlaxelEnvironment(db: CanvasDb, spec: {
+    profileId: string;
+    grantee: string;
+    person: string;
+}): Promise<string>;
+/** Stamp `last_seen_at` on the machine environment: one statement, no read. A no-op before {@link registerMachineEnvironment}. */
+export declare function touchMachineEnvironment(now: string): Promise<void>;
+/** The machine environment's object id; throws before {@link registerMachineEnvironment} has run. */
+export declare function machineEnvironmentId(): string;

package/dist/core/environments.js

@@ -0,0 +1,56 @@
+/** The machine environment: an `environment` object (kind `machine`, owned by the terminal app) with an `environments`
+ *  sidecar row naming the install id, registered at every daemon boot and kept fresh by the storage-maintenance tick. */
+import { openDb, withCanvasWrite } from './canvas/db.js';
+import { createObject, ensureOwner, ownerForGrantee } from './graph/objects.js';
+import { writeActsFor } from './permissions/facts.js';
+import { isCloudRole, personIdAsync } from './canvas/person.js';
+import { setCloudProfileWriter } from './profiles/manifest.js';
+let registered = null;
+/** Find the `environments` row for `installId`, or create its object and row; either way set `last_seen_at`, and cache
+ *  the environment id and install id for {@link machineEnvironmentId} and {@link touchMachineEnvironment}. */
+export async function registerMachineEnvironment(installId) {
+    const now = new Date().toISOString();
+    const result = await withCanvasWrite(async (db) => {
+        const existing = await db.prepare('SELECT object FROM environments WHERE machine_id = ?').get(installId);
+        if (existing !== undefined) {
+            await db.prepare('UPDATE environments SET last_seen_at = ? WHERE machine_id = ?').run(now, installId);
+            return { environmentId: existing.object, created: false };
+        }
+        const owner = await ownerForGrantee(db, 'app:terminal');
+        const object = await createObject(db, { type: 'environment', kind: 'machine', owner: owner.id, privacy: 'public', name: installId, preview: 'machine' });
+        // A cloud-role machine belongs to no person, so it acts for nobody.
+        if (!isCloudRole())
+            await writeActsFor(db, object.id, await personIdAsync());
+        await db.prepare(`INSERT INTO environments (object, kind, machine_id, last_seen_at) VALUES (?, 'machine', ?, ?)`).run(object.id, installId, now);
+        return { environmentId: object.id, created: true };
+    });
+    registered = { environmentId: result.environmentId, machineId: installId };
+    return result;
+}
+/** A cloud profile's own `blaxel` environment (D105): an `environment` object owned by the profile's object, acting for `person`, and
+ *  its `environments` row with the default `memory_mb` (2048), no recipe (so the Blaxel base image) and no machine id. Runs in the
+ *  caller's write, before the profile row exists, so the profile and its environment commit together. The profile object is made
+ *  here under `grantee`'s app, with the profile id as its handle: a cloud role serves many people and a profile name is not unique
+ *  across them, while the handle is unique per object type. Returns the environment's object id. */
+export async function createProfileBlaxelEnvironment(db, spec) {
+    const app = await ownerForGrantee(db, spec.grantee);
+    const profile = await ensureOwner(db, 'profile', 'profile', spec.profileId, spec.profileId, app);
+    const object = await createObject(db, { type: 'environment', kind: 'blaxel', owner: profile.id, privacy: 'private', name: spec.profileId, preview: 'blaxel' });
+    await writeActsFor(db, object.id, spec.person);
+    await db.prepare(`INSERT INTO environments (object, kind, machine_id, memory_mb, last_seen_at) VALUES (?, 'blaxel', NULL, 2048, ?)`).run(object.id, new Date().toISOString());
+    return object.id;
+}
+/** Stamp `last_seen_at` on the machine environment: one statement, no read. A no-op before {@link registerMachineEnvironment}. */
+export async function touchMachineEnvironment(now) {
+    if (registered === null)
+        return;
+    await (await openDb()).prepare('UPDATE environments SET last_seen_at = ? WHERE machine_id = ?').run(now, registered.machineId);
+}
+/** The machine environment's object id; throws before {@link registerMachineEnvironment} has run. */
+export function machineEnvironmentId() {
+    if (registered === null)
+        throw new Error('the machine environment is not registered yet');
+    return registered.environmentId;
+}
+// The daemon loads this file, which is what makes a cloud role's profile creation write the environment with the profile (D105).
+setCloudProfileWriter((spec, insert) => withCanvasWrite(async (db) => { await insert(await createProfileBlaxelEnvironment(db, spec)); }));

package/dist/core/events/outbound.d.ts

@@ -0,0 +1,21 @@
+import type { EventField } from './types.js';
+/** A failed outbound request: where it was going and which step of the caller's work it was. The thrown fetch error is the `cause`. */
+export declare class OutboundError extends Error {
+    readonly step: string;
+    readonly url: string;
+    constructor(step: string, url: string, cause: unknown);
+}
+/** `fetch` whose thrown error (DNS, socket, timeout) is rethrown as an `OutboundError` naming the step and destination, with the original as its cause. */
+export declare function outboundFetch(step: string, url: string, init?: RequestInit): Promise<Response>;
+/** A request that completed with a failure status: names the step and destination, with the status as the cause. */
+export declare function outboundRefusal(step: string, url: string, message: string): OutboundError;
+/** Read a response body as JSON; a failed read (connection dropped after the headers) is an `OutboundError`, and a body that is not JSON is a `SyntaxError` as before. */
+export declare function outboundJson(step: string, url: string, response: Response): Promise<unknown>;
+/** Log fields for a caught outbound-request error: the step, the destination host and path (never the query string, headers or bodies), and the
+ *  `Error.cause` chain, including the members of an `AggregateError` (what Node's `fetch` reports for a refused connection), each with its name, message,
+ *  code, errno, syscall and hostname. The step and destination come from the first `OutboundError` met; `target` supplies them when the caller never wrapped
+ *  the request. */
+export declare function describeOutboundFailure(error: unknown, target?: {
+    step: string;
+    url?: string;
+}): Record<string, EventField>;

package/dist/core/events/outbound.js

@@ -0,0 +1,92 @@
+/** A failed outbound request: where it was going and which step of the caller's work it was. The thrown fetch error is the `cause`. */
+export class OutboundError extends Error {
+    step;
+    url;
+    constructor(step, url, cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.step = step;
+        this.url = url;
+        this.name = 'OutboundError';
+    }
+}
+/** `fetch` whose thrown error (DNS, socket, timeout) is rethrown as an `OutboundError` naming the step and destination, with the original as its cause. */
+export async function outboundFetch(step, url, init) {
+    try {
+        return await fetch(url, init);
+    }
+    catch (error) {
+        throw new OutboundError(step, url, error);
+    }
+}
+/** A request that completed with a failure status: names the step and destination, with the status as the cause. */
+export function outboundRefusal(step, url, message) {
+    return new OutboundError(step, url, new Error(message));
+}
+/** Read a response body as JSON; a failed read (connection dropped after the headers) is an `OutboundError`, and a body that is not JSON is a `SyntaxError` as before. */
+export async function outboundJson(step, url, response) {
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        throw new OutboundError(step, url, error);
+    }
+    return JSON.parse(text);
+}
+const MAX_CHAIN = 8;
+const LINK_KEYS = ['code', 'errno', 'syscall', 'hostname'];
+function link(error) {
+    if (typeof error !== 'object' || error === null)
+        return { name: 'Error', message: String(error) };
+    const value = error;
+    const result = {
+        name: typeof value['name'] === 'string' ? value['name'] : 'Error',
+        message: typeof value['message'] === 'string' ? value['message'] : String(error),
+    };
+    for (const key of LINK_KEYS) {
+        const field = value[key];
+        if (typeof field === 'string' || typeof field === 'number')
+            result[key] = field;
+    }
+    return result;
+}
+/** Log fields for a caught outbound-request error: the step, the destination host and path (never the query string, headers or bodies), and the
+ *  `Error.cause` chain, including the members of an `AggregateError` (what Node's `fetch` reports for a refused connection), each with its name, message,
+ *  code, errno, syscall and hostname. The step and destination come from the first `OutboundError` met; `target` supplies them when the caller never wrapped
+ *  the request. */
+export function describeOutboundFailure(error, target) {
+    let where = target;
+    let wrapped = false;
+    const chain = [];
+    const seen = new Set();
+    const queue = [error];
+    while (queue.length > 0 && chain.length < MAX_CHAIN) {
+        const current = queue.shift();
+        if (current === undefined || seen.has(current))
+            continue;
+        seen.add(current);
+        if (current instanceof OutboundError) {
+            if (!wrapped)
+                where = { step: current.step, url: current.url };
+            wrapped = true;
+        }
+        else
+            chain.push(link(current));
+        if (typeof current !== 'object' || current === null)
+            continue;
+        const { cause, errors } = current;
+        queue.push(cause);
+        if (current instanceof AggregateError && Array.isArray(errors))
+            queue.push(...errors.slice(0, MAX_CHAIN));
+    }
+    const fields = { cause_chain: chain };
+    if (where) {
+        fields['step'] = where.step;
+        if (where.url !== undefined) {
+            const url = new URL(where.url);
+            fields['host'] = url.host;
+            fields['path'] = url.pathname;
+        }
+    }
+    return fields;
+}