@north-light/api 0.3.579 → 0.3.587

package/dist/core/graph/reader.js

@@ -0,0 +1,218 @@
+import { coveredByAny, isSandboxedNode } from '../../shared/env.js';
+import { existsSync } from 'node:fs';
+import { CrtrError } from '../errors.js';
+import { getCachedProfile } from '../scoped-state/person-store.js';
+import { parseScope } from '@north-light/identity';
+import { activeGrant, grantFor } from '../grants/mirror.js';
+import { ApiError } from '../../api/errors.js';
+import { pluginAppToken } from '../secrets.js';
+import { loadExactProfileManifest } from '../profiles/manifest.js';
+import { ensureOwner, getById, nodeObject, ownerForGrantee, profileHandle } from './objects.js';
+import { personId } from '../canvas/person.js';
+import { warmCheckoutIdentities } from './repo-sync/repos.js';
+/** A node's view of repos: the ones enclosing its cwd, then those of each project path of its profile
+ *  (manifest order), each repo once. A project path that no longer exists, is not in a repo, or has no
+ *  work tree (a bare repository) contributes nothing. */
+export async function viewRepos(cwd, profileId, reposFn, lookups) {
+    const projectPaths = profileId === null ? [] : lookups.projectPaths(profileId);
+    const checkouts = await reposFn(cwd);
+    const seen = new Set(checkouts.map((c) => c.repo.id));
+    const projectCheckouts = [];
+    for (const path of projectPaths) {
+        if (!existsSync(path))
+            continue;
+        let found;
+        try {
+            found = await reposFn(path);
+        }
+        catch (e) {
+            if (e instanceof CrtrError && e.code === 'git-lookup-failed')
+                continue;
+            throw e;
+        }
+        for (const c of found)
+            if (!seen.has(c.repo.id)) {
+                seen.add(c.repo.id);
+                projectCheckouts.push(c);
+            }
+    }
+    return { repos: checkouts.map((c) => c.repo), checkouts, projectRepos: projectCheckouts.map((c) => c.repo), projectCheckouts };
+}
+/** Run the git lookups a node's reader needs (its cwd and its profile's project paths) now, before a canvas write opens, so
+ *  `viewRepos` inside the write hits the identity cache instead of spawning git while the write holds a pooled connection. */
+export async function warmNodeRepos(db, nodeId) {
+    const row = await db.prepare('SELECT cwd, profile_id FROM nodes WHERE node_id = ?').get(nodeId);
+    if (row === undefined)
+        return;
+    await warmCheckoutIdentities(row.cwd);
+    if (row.profile_id)
+        for (const path of liveLookups(db).projectPaths(row.profile_id))
+            if (existsSync(path))
+                await warmCheckoutIdentities(path);
+}
+export async function readerFor(db, principal, reposFn) {
+    if (principal.class === 'anonymous')
+        throw new Error('a publish token cannot read as a principal');
+    if (principal.class === 'person')
+        return { class: 'person', person: await personObject(db) };
+    if (principal.class === 'app')
+        return { class: 'app', app: await appObject(db, principal.app), scopes: principal.scopes, ...(principal.sub === undefined ? {} : { sub: principal.sub }) };
+    if (principal.class === 'machine' || principal.class === 'import')
+        throw new Error(`a ${principal.class} token cannot read as a principal`);
+    if (principal.class === 'forwarded') {
+        // The envelope's identity with this machine's current mirrored grant: a person actor reads as the person; an app actor reads as its app,
+        // bounded by the grant's resolved scopes ∩ node_scopes (null = all) and confined to its run place.
+        if (principal.actor.kind === 'person')
+            return { class: 'person', person: await personObject(db) };
+        const grant = await grantFor(principal.actor.app, principal.sub);
+        if (!grant)
+            throw new ApiError(403, 'app_not_granted', `${principal.actor.app} holds no active grant for ${principal.sub} on this machine`);
+        const stored = principal.actor.node_scopes;
+        return { class: 'app', app: await appObject(db, principal.actor.app), place: principal.actor.place, launched: stored,
+            scopes: stored === null ? grant.resolved : stored.filter((scope) => coveredByAny(grant.resolved, scope)) };
+    }
+    if (principal.class === 'cron') {
+        // A cron has no node: it reads as its app, bounded by its stored scopes, each kept while the grant's current set covers it.
+        const current = principal.grant ? (await activeGrant(principal.grant))?.resolved ?? [] : [];
+        const stored = principal.scopes;
+        return { class: 'app', app: await appObject(db, principal.app), scopes: stored === null ? current : stored.filter((scope) => coveredByAny(current, scope)), launched: stored,
+            place: { run: principal.origin_run ?? '', isolated: principal.isolated } };
+    }
+    const lookups = liveLookups(db);
+    const node = await nodeObject(db, principal.node);
+    const row = await db.prepare('SELECT cwd, profile_id, app FROM nodes WHERE node_id = ?').get(principal.node);
+    const owner = row.app === null ? null : await lookups.object(row.app);
+    if (!owner)
+        throw new Error(`node ${principal.node} has no app`);
+    return {
+        class: 'node', node, app: owner, scopes: await nodeScopes(principal.app, principal.sub, principal.grant, principal.scopes, lookups), launched: principal.scopes, cwd: row.cwd,
+        ...await viewRepos(row.cwd, row.profile_id, reposFn, lookups),
+        profile: row.profile_id === null ? null : await lookups.profile(row.profile_id, owner),
+    };
+}
+export async function readerForNode(db, nodeId, reposFn, lookups = liveLookups(db), allowRevoked = false) {
+    // Two indexed point reads: joining nodes to objects here costs ten times as much per call.
+    const node = await db.prepare(`SELECT o.* FROM objects o WHERE o.id = ? AND o.type = 'node'`).get(nodeId);
+    const row = await db.prepare(`SELECT (SELECT external_id FROM identities WHERE object = nodes.app) AS grantee,
+    sub, grant_id, scopes_json, cwd, profile_id, app FROM nodes WHERE node_id = ?`).get(nodeId);
+    if (!node || !row)
+        throw new Error(`no node ${nodeId}`);
+    const { grantee, sub, grant_id, scopes_json, cwd, profile_id, app } = row;
+    const owner = app === null ? null : await lookups.object(app);
+    if (!owner)
+        throw new Error(`node ${nodeId} has no app`);
+    const launched = scopes_json === null ? null : JSON.parse(scopes_json);
+    return {
+        class: 'node', node, app: owner, scopes: await nodeScopes(grantee, sub ?? '', grant_id, launched, lookups, allowRevoked), launched, cwd,
+        ...await viewRepos(cwd, profile_id, reposFn, lookups),
+        profile: profile_id === null ? null : await lookups.profile(profile_id, owner),
+    };
+}
+/** A receiving object reads using its owner's app grant, not its registering caller's rights. */
+export async function readerForObject(db, watcher, reposFn = async () => [], lookups = liveLookups(db)) {
+    // Delivery rechecks revoked watchers; unlike an authenticated call, a
+    // revoked node's reader must be unreadable rather than throw during publish.
+    // A stub (a watcher living on another machine) reads as the identity in its envelope under the grant this machine holds NOW.
+    const stub = await db.prepare('SELECT envelope_json FROM peer_stubs WHERE object = ?').get(watcher.id);
+    if (stub !== undefined)
+        return await readerForStub(db, watcher, stub.envelope_json === null ? null : JSON.parse(stub.envelope_json), lookups);
+    if (watcher.type === 'node')
+        return await readerForNode(db, watcher.id, reposFn, lookups, true);
+    const owner = watcher.owner === null ? null : await lookups.object(watcher.owner);
+    if (!owner)
+        throw new Error(`watcher ${watcher.id} has no owner`);
+    const app = owner.type === 'app' ? owner : owner.type === 'profile' && owner.owner !== null
+        ? await lookups.object(owner.owner) : null;
+    const owningApp = app ?? await db.prepare("SELECT o.* FROM identities i JOIN objects o ON o.id = i.object WHERE i.external_id = 'app:terminal' AND i.scheme = 'app'")
+        .get() ?? await db.prepare("SELECT * FROM objects WHERE type = 'person' AND name = 'user' AND home_machine IS NULL").get();
+    if (!owningApp)
+        throw new Error('no terminal app or person object');
+    const grantee = (await db.prepare("SELECT external_id FROM identities WHERE object = ? AND scheme = 'app'")
+        .get(owningApp.id))?.external_id ?? 'app:terminal';
+    const grants = await db.prepare("SELECT resolved_scopes_json FROM grants WHERE grantee = ? AND status = 'active'").all(grantee);
+    // No active grant: a local plugin's app reads under the scopes its `crtr_app_` token holds (a revoked or absent token yields none).
+    const scopes = owner.type === 'person' ? null : grants.length === 0
+        ? lookups.pluginScopes(grantee)
+        : (grants.length === 1
+            ? JSON.parse(grants[0].resolved_scopes_json).filter((s) => s.mode === 'always').map((s) => parseScope(s.scope))
+            : null);
+    return { class: 'object', object: watcher, node: watcher, owner, app: owningApp, scopes,
+        repos: owner.type === 'repo' ? [owner] : [] };
+}
+/** The scopes `app` (an app object) holds now: its one active grant's always-scopes, or a local plugin's `crtr_app_` token scopes when it has no
+ *  grant; null for several grants or none that applies. The same rule as an app-owned object's reader (`readerForObject`). */
+export async function appScopesNow(db, app, lookups) {
+    const grantee = (await db.prepare("SELECT external_id FROM identities WHERE object = ? AND scheme = 'app'").get(app.id))?.external_id;
+    if (grantee === undefined)
+        return null;
+    const grants = await db.prepare("SELECT resolved_scopes_json FROM grants WHERE grantee = ? AND status = 'active'").all(grantee);
+    if (grants.length === 0)
+        return lookups.pluginScopes(grantee);
+    if (grants.length > 1)
+        return null;
+    return JSON.parse(grants[0].resolved_scopes_json).filter((s) => s.mode === 'always').map((s) => parseScope(s.scope));
+}
+/** A stub's reader, recomputed at every publish and never stored. From the stored envelope it takes only the identity (app, node,
+ *  `node_scopes`, place); the scopes are the CURRENT mirrored grant's resolved scopes ∩ `node_scopes` (null = all), exactly as the
+ *  forwarded reader of C2. A missing or revoked grant, or a stub with no identity, yields `scopes = null`, which `publish` skips for
+ *  every owner but the person. A person envelope reads as the person. */
+async function readerForStub(db, stub, identity, lookups) {
+    const person = await personObject(db);
+    if (identity !== null && identity.app === null)
+        return { class: 'object', object: stub, node: stub, owner: person, app: person, scopes: null, repos: [] };
+    const app = identity?.app == null ? null : await appObject(db, identity.app);
+    const grant = identity?.app == null ? null : await lookups.grantFor(identity.app, identity.sub);
+    const scopes = identity === null || grant === null ? null
+        : identity.node_scopes === null ? grant.resolved : identity.node_scopes.filter((scope) => coveredByAny(grant.resolved, scope));
+    const owner = app ?? (stub.owner === null ? person : await lookups.object(stub.owner) ?? person);
+    return { class: 'object', object: stub, node: stub, owner, app: owner, scopes, launched: identity?.node_scopes ?? null, repos: [],
+        ...(identity?.place == null ? {} : { place: identity.place }) };
+}
+export function liveLookups(db) {
+    return {
+        grantById: activeGrant, grantFor,
+        pluginScopes: (grantee) => pluginAppToken(grantee.replace(/^app:/, ''))?.scopes ?? null,
+        object: async (id) => await getById(db, id), profile: async (id, app) => await profileObject(db, id, app),
+        projectPaths: (id) => isSandboxedNode() ? [] : getCachedProfile(id)?.manifest.projects.map((p) => p.path) ?? [],
+    };
+}
+export function publishLookups(db) {
+    const live = liveLookups(db);
+    const cache = new Map();
+    // Caches the loader's result; an async loader's promise is cached, so concurrent callers share one load.
+    const memo = (key, load) => {
+        if (!cache.has(key))
+            cache.set(key, load());
+        return cache.get(key);
+    };
+    return {
+        grantById: (id) => memo(`g\0${id}`, () => live.grantById(id)),
+        grantFor: (app, sub) => memo(`a\0${app}\0${sub}`, () => live.grantFor(app, sub)),
+        pluginScopes: (grantee) => memo(`t\0${grantee}`, () => live.pluginScopes(grantee)),
+        object: async (id) => await memo(`o\0${id}`, async () => await live.object(id)),
+        profile: async (id, app) => await memo(`p\0${id}\0${app.id}`, async () => await live.profile(id, app)),
+        projectPaths: (id) => memo(`j\0${id}`, () => live.projectPaths(id)),
+    };
+}
+/** What the run may reach beyond its own app: the active grant, narrowed by the launched scope list. */
+async function nodeScopes(app, sub, grantId, launched, lookups, allowRevoked = false) {
+    const grant = grantId ? await lookups.grantById(grantId) : await lookups.grantFor(app, sub);
+    const resolved = grant && grant.grantee === app ? grant.resolved : null;
+    if (resolved === null) {
+        if (allowRevoked)
+            return null;
+        throw new Error(`the grant of ${app} is not active`);
+    }
+    return launched === null ? resolved : launched.filter((scope) => coveredByAny(resolved, scope));
+}
+async function personObject(db) {
+    return await ownerForGrantee(db, personId());
+}
+async function appObject(db, grantee) {
+    return await ensureOwner(db, 'app', 'app', grantee, grantee.replace(/^app:/, ''));
+}
+export async function profileObject(db, profileId, app) {
+    const known = await db.prepare(`SELECT o.* FROM identities i JOIN objects o ON o.id = i.object
+    WHERE i.scheme = 'profile' AND i.external_id = ?`).get(profileId);
+    return known ?? await ensureOwner(db, 'profile', 'profile', profileId, profileHandle(profileId, loadExactProfileManifest(profileId).manifest.name), app);
+}

package/dist/core/graph/receiver-url.d.ts

@@ -0,0 +1,11 @@
+import * as dns from 'node:dns/promises';
+import { request } from 'node:https';
+export declare function isPublicReceiverAddress(address: string): boolean;
+export declare function receiverEndpoint(raw: string): URL;
+/** Resolve all answers, not merely the first: a mixed public/private DNS response is unsafe. */
+export declare function resolveReceiverAddress(url: URL, resolve?: typeof dns.lookup, signal?: AbortSignal, isAllowedAddress?: (address: string) => boolean): Promise<{
+    address: string;
+    family: 4 | 6;
+}>;
+/** The vetted DNS answer is pinned to this one socket; never delegate a second lookup to TLS. */
+export declare function postReceiverUrl(raw: string, body: string, headers: Record<string, string>, timeoutMs: number, resolve?: typeof dns.lookup, send?: typeof request, isAllowedAddress?: (address: string) => boolean): Promise<number>;

package/dist/core/graph/receiver-url.js

@@ -0,0 +1,83 @@
+import * as dns from 'node:dns/promises';
+import { BlockList, isIP } from 'node:net';
+import { request } from 'node:https';
+// Fail closed on non-global, documentation, shared, multicast and reserved space.
+// The IPv6 global-unicast allocation is 2000::/3; its special-purpose blocks below
+// are not suitable receiver destinations even where some addresses are routable.
+const blocked = new BlockList();
+for (const [prefix, bits] of [
+    ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8],
+    ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24],
+    ['192.0.2.0', 24], ['192.88.99.0', 24], ['192.168.0.0', 16],
+    ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24],
+    ['224.0.0.0', 4], ['240.0.0.0', 4],
+])
+    blocked.addSubnet(prefix, bits, 'ipv4');
+for (const [prefix, bits] of [
+    ['2001::', 23], ['2001:4:112::', 48], ['2001:db8::', 32], ['2002::', 16], ['3fff::', 20],
+])
+    blocked.addSubnet(prefix, bits, 'ipv6');
+const globalV6 = new BlockList();
+globalV6.addSubnet('2000::', 3, 'ipv6');
+export function isPublicReceiverAddress(address) {
+    const family = isIP(address);
+    return family === 4 ? !blocked.check(address, 'ipv4') :
+        family === 6 && globalV6.check(address, 'ipv6') && !blocked.check(address, 'ipv6');
+}
+export function receiverEndpoint(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error('receiver URL must be an absolute HTTPS URL');
+    }
+    if (url.protocol !== 'https:' || !url.hostname || url.username || url.password || url.hash)
+        throw new Error('receiver URL must be HTTPS without credentials or fragment');
+    return url;
+}
+/** Resolve all answers, not merely the first: a mixed public/private DNS response is unsafe. */
+export async function resolveReceiverAddress(url, resolve = dns.lookup, signal = AbortSignal.timeout(5_000), isAllowedAddress = isPublicReceiverAddress) {
+    const hostname = url.hostname.replace(/^\[|\]$/g, '');
+    const literal = isIP(hostname);
+    const answers = literal ? [{ address: hostname, family: literal }] : await Promise.race([
+        resolve(hostname, { all: true, verbatim: true }),
+        new Promise((_, reject) => {
+            if (signal.aborted)
+                reject(signal.reason);
+            else
+                signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+        }),
+    ]);
+    if (!answers.length || answers.some((answer) => !isAllowedAddress(answer.address)))
+        throw new Error('receiver URL resolves to a non-public IP address');
+    const answer = answers[0];
+    return { address: answer.address, family: answer.family };
+}
+/** The vetted DNS answer is pinned to this one socket; never delegate a second lookup to TLS. */
+export async function postReceiverUrl(raw, body, headers, timeoutMs, resolve = dns.lookup, send = request, 
+// Test-only: permit a loopback TLS fixture without changing the production address policy.
+isAllowedAddress = isPublicReceiverAddress) {
+    const url = receiverEndpoint(raw);
+    const signal = AbortSignal.timeout(timeoutMs);
+    const address = await resolveReceiverAddress(url, resolve, signal, isAllowedAddress);
+    return new Promise((resolve, reject) => {
+        const req = send(url, {
+            method: 'POST', headers, agent: false, signal,
+            lookup: (_hostname, options, callback) => {
+                if (options.all)
+                    callback(null, [address]);
+                else
+                    callback(null, address.address, address.family);
+            },
+        }, (response) => { response.resume(); resolve(response.statusCode ?? 0); });
+        req.on('socket', (socket) => {
+            socket.on('connect', () => {
+                if (!socket.remoteAddress || socket.remoteAddress !== address.address || !isAllowedAddress(socket.remoteAddress))
+                    req.destroy(new Error('receiver socket connected to a non-public or unexpected IP address'));
+            });
+        });
+        req.on('error', reject);
+        req.end(body);
+    });
+}

package/dist/core/graph/receivers.d.ts

@@ -0,0 +1,28 @@
+import type { ObjectRow, Level, ListenDelivery } from './types.js';
+import type { CanvasDb } from '../canvas/db.js';
+export interface ReceiverDestination {
+    id: string;
+    reception: 1 | 2;
+    delivery: ListenDelivery; /** Delivered on the strength of an app's `link` rather than the destination's own read access. */
+    linked?: boolean;
+}
+export interface ReceivedMessage {
+    messageId: string;
+    event: string;
+    level: Level;
+    senderNodeId: string | null;
+    elevatesTier: boolean;
+    idempotencyKey?: string;
+}
+export interface Receiver {
+    bodyOwner(destinations: readonly ReceiverDestination[]): string | null;
+    enqueue(db: CanvasDb, message: ReceivedMessage, destinations: readonly ReceiverDestination[]): Promise<void>;
+}
+export type ReceiverName = 'inbox' | 'argv' | 'url' | 'queue' | 'peer';
+/** The receiver is per instance, not per kind. An action's historical argv JSON is unchanged. */
+export declare function receiverForObject(db: CanvasDb, object: ObjectRow): Promise<ReceiverName | undefined>;
+export declare const BACKLOG_CAP = 1000;
+export declare function onQueueSignal(objectId: string, cb: () => void): Promise<() => void>;
+export declare function signalQueue(id: string): void;
+export declare const argvReceiver: Receiver;
+export declare const RECEIVERS: Readonly<Record<ReceiverName, Receiver>>;

package/dist/core/graph/receivers.js

@@ -0,0 +1,66 @@
+import { randomBytes } from 'node:crypto';
+import { nodeInbox } from './kinds/node.js';
+import { peerReceiver } from '../peer/receiver.js';
+/** The receiver is per instance, not per kind. An action's historical argv JSON is unchanged. */
+export async function receiverForObject(db, object) {
+    const row = await db.prepare('SELECT receiver_json FROM custom_objects WHERE object = ?').get(object.id);
+    if (!row?.receiver_json)
+        return undefined;
+    const value = JSON.parse(row.receiver_json);
+    if (value === 'queue')
+        return 'queue';
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        if ('url' in value)
+            return 'url';
+        if ('argv' in value)
+            return 'argv';
+    }
+    return undefined;
+}
+export const BACKLOG_CAP = 1000;
+const signals = new Map();
+export async function onQueueSignal(objectId, cb) {
+    const set = signals.get(objectId) ?? new Set();
+    set.add(cb);
+    signals.set(objectId, set);
+    return () => { set.delete(cb); if (set.size === 0)
+        signals.delete(objectId); };
+}
+export function signalQueue(id) { setImmediate(() => { for (const cb of signals.get(id) ?? [])
+    cb(); }); }
+async function cap(db, id) {
+    const count = (await db.prepare(`SELECT COUNT(*) AS n FROM deliveries WHERE destination_id = ?
+    AND state = 'pending' AND canceled_at IS NULL`).get(id)).n;
+    if (count <= BACKLOG_CAP)
+        return;
+    const excess = await db.prepare(`SELECT delivery_id, message_id FROM deliveries
+    WHERE destination_id = ? AND state = 'pending' AND canceled_at IS NULL
+    ORDER BY created_at, seq LIMIT ?`).all(id, count - BACKLOG_CAP);
+    for (const row of excess) {
+        await db.prepare('DELETE FROM deliveries WHERE delivery_id = ?').run(row.delivery_id);
+        await db.prepare('DELETE FROM messages WHERE message_id = ? AND NOT EXISTS (SELECT 1 FROM deliveries WHERE message_id = ?)').run(row.message_id, row.message_id);
+    }
+    if (excess.length)
+        await db.prepare(`UPDATE custom_objects SET dropped = dropped + ? WHERE object = ?`).run(excess.length, id);
+}
+function pushReceiver(due, notify) {
+    return {
+        bodyOwner: () => null,
+        async enqueue(db, message, destinations) {
+            const now = Date.now();
+            const insert = db.prepare(`INSERT INTO deliveries
+        (delivery_id, message_id, destination_id, urgency, wake, state, next_attempt_at, created_at, updated_at)
+        VALUES (?, ?, ?, 'normal', 0, 'pending', ?, ?, ?)`);
+            for (const destination of destinations) {
+                await insert.run(randomBytes(16).toString('hex'), message.messageId, destination.id, due ? now : null, now, now);
+                await cap(db, destination.id);
+                if (notify)
+                    signalQueue(destination.id);
+            }
+        },
+    };
+}
+export const argvReceiver = pushReceiver(true, false);
+export const RECEIVERS = {
+    inbox: nodeInbox, argv: argvReceiver, url: pushReceiver(true, false), queue: pushReceiver(false, true), peer: peerReceiver,
+};

package/dist/core/graph/repo-sync/exchange.d.ts

@@ -0,0 +1,36 @@
+import type { ReposFn } from '../reader.js';
+import type { ObjectRow } from '../types.js';
+import { type CanvasDb } from '../../canvas/db.js';
+/**
+ * The tree (path → file text) of every public document the repo space owns, deleted ones
+ * included. A revision already in `previous` is copied verbatim, so a remote author and the
+ * links it was written with survive; a revision made here carries its author's object id, and
+ * a head carries the document's current `links-to` edges. `carry` names paths of `previous` that
+ * are copied through untouched (files whose import was refused and is still pending).
+ */
+export declare function exportRepo(db: CanvasDb, repo: ObjectRow, previous: Map<string, string> | null, imported?: Map<string, string> | null): Promise<Map<string, string>>;
+/** Paths of `tree` whose text differs from the baseline last imported: files that arrived but
+ *  have not landed in canvas.db. */
+export declare function pendingPaths(tree: Map<string, string> | null, imported: Map<string, string> | null): string[];
+export interface ImportResult {
+    created: number;
+    revisions: number;
+    deleted: number;
+    needsMerge: string[];
+    refused: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+/**
+ * Apply the difference between two trees (the one last imported and the new one) to the
+ * repo's documents, in one transaction. Per changed file: a file that does not parse, is not
+ * public, or names an id held by an object outside this repo is refused and reported; a new
+ * document is created with its id; arriving revisions are added (author NULL); changed record
+ * fields and a rename are applied; a tombstone or a removed file deletes. Each document
+ * publishes once: `created`, `edited` (with `heads` and `needs_merge`) or `deleted`. A
+ * document that fails is rolled back alone and reported in `refused`.
+ */
+export declare function importTree(db: CanvasDb, repo: ObjectRow, before: Map<string, string>, after: Map<string, string>, reposFn?: ReposFn): Promise<ImportResult>;
+/** Whether any link target in a serialized ref file is one of `arrived`. */
+export declare function namesArrived(text: string, arrived: ReadonlySet<string>): boolean;