@north-light/api 0.3.580 → 0.3.587

package/dist/core/grants/mirror.js

@@ -0,0 +1,379 @@
+import { createHash } from 'node:crypto';
+import { parseScope } from '@north-light/identity';
+import { openDb, withCanvasWrite } from '../canvas/db.js';
+import { isUnsandboxedMachine } from '../runtime/unsandboxed.js';
+import { replaceWrittenBy, userSubject } from '../permissions/facts.js';
+import { GROUP_TYPE } from '../permissions/builtin.js';
+const SETUP_STATES = ['not_started', 'pending', 'ready', 'failed', 'unavailable'];
+const STRENGTHS = ['ultra', 'strong', 'medium', 'light'];
+/** The fleet's runtime principal (`CRTR_RUNTIME`): a cloud role reads only its own runtime's grants, so a person's VM or laptop grants are never used. A Mac sets none. */
+function runtimeScope() {
+    const runtime = process.env['CRTR_RUNTIME'];
+    return runtime ? { sql: ' AND runtime = ?', args: [runtime] } : { sql: '', args: [] };
+}
+/** Run `SELECT <columns> FROM grants WHERE <where>` limited to this process's runtime. */
+async function grantRows(columns, where, args = []) {
+    const scope = runtimeScope();
+    return await (await openDb()).prepare(`SELECT ${columns} FROM grants WHERE ${where}${scope.sql}`).all(...args, ...scope.args);
+}
+async function grantRow(columns, where, args = []) {
+    return (await grantRows(columns, where, args))[0];
+}
+function entries(value) {
+    if (!Array.isArray(value))
+        throw new TypeError('grant scopes must be a list');
+    return value.map((entry) => {
+        if (!entry || typeof entry !== 'object' ||
+            typeof entry.scope !== 'string' ||
+            !['always', 'ask'].includes(entry.mode)) {
+            throw new TypeError('invalid grant scope entry');
+        }
+        return { scope: entry.scope, mode: entry.mode };
+    });
+}
+/** One `dependencies` entry, or null when it is not `{ state, message?, next, step? }`
+ *  with a known setup state, a string message and string step when present, and a non-empty
+ *  string `next`. Only this shape is read: a bare state string is dropped. */
+function dependencyOf(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const { state, message, next, step } = value;
+    if (typeof state !== 'string' || !SETUP_STATES.includes(state))
+        return null;
+    if (message !== undefined && typeof message !== 'string')
+        return null;
+    if (step !== undefined && typeof step !== 'string')
+        return null;
+    if (typeof next !== 'string' || !next)
+        return null;
+    return { state: state, ...(message === undefined ? {} : { message }), next, ...(step === undefined ? {} : { step }) };
+}
+/** The `dependencies` a grant sync answer carried. Advisory data, so a missing or
+ *  malformed value never fails the sync (which also carries every grant's
+ *  authorization): absent or non-object reads as `{}`, and a malformed entry
+ *  (see `dependencyOf`) is dropped. A directory older than the Context stage sends none. */
+export function dependenciesOf(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [provider, entry] of Object.entries(value)) {
+        const dependency = dependencyOf(entry);
+        if (dependency)
+            out[provider] = dependency;
+    }
+    return out;
+}
+/** The `inference_endpoint` a grant sync answer carried: `{ base_url, rungs }` with a non-empty string `base_url` and at
+ *  least one known strength naming a catalog model id. Anything else reads as null — an app-paid grant without a usable
+ *  endpoint is refused `model_unavailable` at its first call, never served from the owner's routes. */
+export function inferenceEndpointOf(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const { base_url, rungs } = value;
+    if (typeof base_url !== 'string' || !base_url || !rungs || typeof rungs !== 'object' || Array.isArray(rungs))
+        return null;
+    const kept = {};
+    for (const strength of STRENGTHS) {
+        const model = rungs[strength];
+        if (typeof model === 'string' && model)
+            kept[strength] = model;
+    }
+    return Object.keys(kept).length ? { base_url: base_url.replace(/\/+$/, ''), rungs: kept } : null;
+}
+function record(row) {
+    // A row whose computed columns lag its revision (a consent written but not yet computed) reads as no grant, never as the previous scopes.
+    if (row.computed_rev !== row.rev || row.scopes_json === null || row.resolved_scopes_json === null)
+        throw new TypeError('grant columns are not computed for this revision');
+    return { id: row.id, runtime: row.runtime, sub: row.sub, grantee: row.grantee,
+        rev: row.rev, scopes: entries(JSON.parse(row.scopes_json)),
+        resolved_scopes: entries(JSON.parse(row.resolved_scopes_json)),
+        spend_cap: row.spend_cap, expires_at: row.expires_at, status: row.status,
+        revoked_at: row.revoked_at, approved_at: row.approved_at, payer: row.payer,
+        dependencies: dependenciesOf(JSON.parse(row.dependencies_json ?? '{}')), run_notice_url: row.run_notice_url ?? null,
+        inference_endpoint: row.inference_endpoint_json ? inferenceEndpointOf(JSON.parse(row.inference_endpoint_json)) : null, synced_at: row.synced_at ?? '' };
+}
+function active(row) {
+    if (!row || row.status !== 'active')
+        return null;
+    try {
+        return activeRecord(record(row));
+    }
+    catch (error) {
+        if (error instanceof TypeError || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+/** A grant this machine only mirrors. An unsandboxed machine runs only
+ *  `app:terminal`; the directory also fans the account's hosted-runtime app
+ *  grants out to it, read-only, so a forwarded app caller can be authorized
+ *  (`grantFor`, `activeGrant`). They drive nothing here: no sandbox stop, removal
+ *  cascade, provider install, or run notice. */
+export function mirrorOnly(grant) {
+    return grant.grantee !== 'app:terminal' && isUnsandboxedMachine();
+}
+/** Every mirrored grant this machine acts on: `allGrants()` without the mirror-only ones. */
+export async function localGrants() {
+    return (await allGrants()).filter((grant) => !mirrorOnly(grant));
+}
+/** Contract 1's `<id>` grammar, shared by provider ids and group ids. */
+const ID = '[A-Za-z0-9_-]{1,64}';
+const PROVIDER_SCOPE = new RegExp(`^(${ID}):(${ID})$`);
+/** Every provider id a scope of an active grant's resolved set names: a
+ *  `<id>:<group>` string whose id is not `crtr` (the runtime's own namespace). */
+export function providerIdsFromGrants(grants) {
+    const ids = new Set();
+    for (const grant of grants) {
+        if (grant.status !== 'active')
+            continue;
+        for (const { scope } of grant.resolved_scopes) {
+            const match = PROVIDER_SCOPE.exec(scope);
+            if (match && match[1] !== 'crtr')
+                ids.add(match[1]);
+        }
+    }
+    return [...ids].sort();
+}
+/** The provider ids an active grant of `person` names: the directory's provider bundles that person has, and so the only
+ *  rows of their plugin list that a provider call installs on its own (`ensureProviderBundle`) rather than from a source. */
+export async function grantedProviderIds(person) {
+    const rows = await grantRows('*', "sub = ? AND status = 'active'", [person]);
+    return new Set(providerIdsFromGrants(rows.flatMap((row) => { try {
+        return [record(row)];
+    }
+    catch (error) {
+        if (error instanceof TypeError || error instanceof SyntaxError)
+            return [];
+        throw error;
+    } })));
+}
+/** Whether a `scope_plugins` row is a directory provider bundle rather than a plugin that has no source this process can read:
+ *  it carries neither a marketplace nor a path (what `ensureProviderBundle` writes) AND its name is a provider an active grant of the
+ *  person names. A source-less row for any other name (a git, local or HTTP-bundle install) is not one. */
+export function isProviderBundleRow(row, granted) {
+    return row.source_marketplace === null && row.source_path === null && granted.has(row.name);
+}
+/** `person`'s (`user:<id>`) active, unexpired grants on this runtime, every grantee: what a cloud role reads for one request's person, where `localGrants()`
+ *  would hand back every person the fleet serves. */
+export async function activeGrantsOfPerson(person) {
+    const rows = await grantRows('*', "sub = ? AND status = 'active'", [person]);
+    return rows.flatMap((row) => { const grant = active(row); return grant === null ? [] : [grant]; });
+}
+/** Every mirrored grant, whatever its status. */
+export async function allGrants() {
+    return (await grantRows('*', 'true')).flatMap((row) => {
+        try {
+            return [record(row)];
+        }
+        catch (error) {
+            if (error instanceof TypeError || error instanceof SyntaxError)
+                return [];
+            throw error;
+        }
+    });
+}
+/** Whether a grant's `expires_at` has passed. An unparsable time reads as expired (fail closed). */
+export function grantExpired(grant) {
+    return grant.expires_at !== null && !(Date.parse(grant.expires_at) > Date.now());
+}
+/** The active form of a grant record read earlier, or null when it is not active, is past `expires_at`, or is unparsable. */
+export function activeRecord(grant) {
+    if (grant.status !== 'active' || grantExpired(grant))
+        return null;
+    try {
+        const resolved = grant.resolved_scopes.map(({ scope }) => parseScope(scope));
+        return { ...grant, resolved: grant.resolved_scopes.flatMap(({ mode }, i) => mode === 'always' ? [resolved[i]] : []) };
+    }
+    catch (error) {
+        if (error instanceof TypeError || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+/** JSON with every object's keys sorted, at every depth, and arrays kept in order. */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.keys(value).sort().filter((key) => value[key] !== undefined)
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/** `grant.get`'s `version`: an opaque string that changes exactly when what an app
+ *  reads from its grant changes — `rev`, `resolved_scopes` (order kept), `spend_cap`,
+ *  `payer`, `inference_endpoint`, `dependencies`. `synced_at` and the token's claims are left out, so a
+ *  periodic sync with the same content (or a daemon restart) keeps it. */
+export function grantVersion(grant) {
+    // `inference_endpoint` joins the version only when present, so a user-paid grant keeps the version it had before the field existed.
+    const covered = { rev: grant.rev, resolved_scopes: grant.resolved_scopes, spend_cap: grant.spend_cap,
+        payer: grant.payer, dependencies: grant.dependencies ?? {}, ...(grant.inference_endpoint ? { inference_endpoint: grant.inference_endpoint } : {}) };
+    return createHash('sha256').update(canonicalJson(covered)).digest('base64url').slice(0, 22);
+}
+export async function hasGrant(grantId) {
+    return !!await grantRow('1', 'id = ?', [grantId]);
+}
+/** The mirrored state of grant `grantId`, or null when the mirror lacks it. */
+export async function grantSyncState(grantId) {
+    return (await grantRow('rev, status', 'id = ?', [grantId])) ?? null;
+}
+/** The mirrored state of the grant `sub` gave `grantee`, whatever its status, or null when the mirror lacks it. */
+export async function grantSyncStateFor(grantee, sub) {
+    return (await grantRow('rev, status', 'grantee = ? AND sub = ?', [grantee, sub])) ?? null;
+}
+/** The mirrored grant `grantId`, whatever its status, or null when the mirror lacks it or the row is unparsable. */
+export async function grantRecord(grantId) {
+    const row = await grantRow('*', 'id = ?', [grantId]);
+    if (!row)
+        return null;
+    try {
+        return record(row);
+    }
+    catch (error) {
+        if (error instanceof TypeError || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+export async function grantStanding(grantId) {
+    const row = await grantRow('*', 'id = ?', [grantId]);
+    if (!row)
+        return { standing: 'inactive', sub: null, grantee: null, status: null, removal_done_at: null, record: null };
+    const base = { sub: row.sub, grantee: row.grantee, status: row.status, removal_done_at: row.removal_done_at ?? null };
+    if (row.status !== 'active')
+        return { ...base, standing: 'inactive', record: null };
+    if (row.computed_rev !== row.rev)
+        return { ...base, standing: 'lagging', record: null };
+    const grant = active(row);
+    return grant === null ? { ...base, standing: 'inactive', record: null } : { ...base, standing: 'active', record: grant };
+}
+/** Ids of the grants in `status` (this runtime's), for a catch-up pass. */
+export async function grantIdsWhere(where) {
+    return (await grantRows('id', where)).map((row) => row.id);
+}
+/** Who a grant's model calls are charged to: `app` only for a mirrored grant the directory marked app-paid, else the person. */
+export async function payerOfGrant(grantId) {
+    return (grantId ? (await grantRecord(grantId))?.payer : null) ?? 'user';
+}
+export async function activeGrant(grantId) {
+    return active(await grantRow('*', 'id = ?', [grantId]));
+}
+export async function grantFor(grantee, sub) {
+    return active(await grantRow('*', 'grantee = ? AND sub = ?', [grantee, sub]));
+}
+/** The app's own active grant on this machine. Null for a mirror-only grant: an
+ *  unsandboxed machine runs no app, so a fanned-out hosted grant is never "the
+ *  app's grant" for a local app caller, sandbox or install. */
+export async function activeGrantForApp(grantee) {
+    if (mirrorOnly({ grantee }))
+        return null;
+    const rows = await grantRows('*', "grantee = ? AND status = 'active'", [grantee]);
+    if (rows.length > 1)
+        throw new Error(`multiple active grants for ${grantee}`);
+    return active(rows[0]);
+}
+/** Where a run's notice goes: its grant's registered `run_notice_url`, with the grant's `sub` and `grantee`. Null when the run has no active grant or the grantee registered no URL. */
+export async function runNoticeTarget(grantId) {
+    const grant = await activeGrant(grantId);
+    return grant && grant.run_notice_url && !mirrorOnly(grant) ? { url: grant.run_notice_url, sub: grant.sub, grantee: grant.grantee } : null;
+}
+/** `person`'s (`user:<id>`) active `app:terminal` grant on this runtime, or null. A runtime serves many people on the fleet, so the person is always
+ *  named: it is the request's person, or the `sub` of the node the call is about. Throws only when that one person holds two. */
+export async function terminalGrant(person) {
+    const rows = await grantRows('*', "grantee = 'app:terminal' AND sub = ? AND status = 'active'", [person]);
+    if (rows.length > 1)
+        throw new Error(`multiple active terminal grants for ${person}`);
+    return active(rows[0]);
+}
+/** Where the grant mirror came from: `'local'` for an unjoined runtime's own grant, the directory issuer once joined, null before any install. */
+export async function grantsSource() {
+    const state = await (await openDb()).prepare("SELECT value FROM runtime_state WHERE key = 'grants_source'").get();
+    return state?.value ?? null;
+}
+export async function hasSyncedGrants(source) {
+    const state = await (await openDb()).prepare("SELECT value FROM runtime_state WHERE key = 'grants_source'").get();
+    return state?.value === source;
+}
+/** OWN-11 for a joined runtime: the unjoined runtime's local mirror grants
+ *  the install's person full local scopes and is not the directory's. Delete it so no
+ *  grant exists until grant sync installs the directory's mirror. */
+export async function dropLocalGrantMirror(db) {
+    const state = await db.prepare("SELECT value FROM runtime_state WHERE key = 'grants_source'").get();
+    if (state?.value !== 'local')
+        return 0;
+    await db.prepare("DELETE FROM runtime_state WHERE key = 'grants_source'").run();
+    return Number((await db.prepare('DELETE FROM grants').run()).changes);
+}
+/** Mark rows a build older than C-D2 wrote as computed for their revision. That build computed every column locally in the same
+ *  write but never set `computed_rev`, so its rows are complete; left NULL they read as no grant until the next successful
+ *  sync rewrites them, and the terminal grant then refuses every launch (NL-550). A directory-written row with lagging
+ *  columns has NULL scopes, so it is never matched. Returns the rows changed. */
+export async function backfillComputedRev() {
+    return await withCanvasWrite(async (db) => Number((await db.prepare('UPDATE grants SET computed_rev = rev WHERE computed_rev IS NULL AND scopes_json IS NOT NULL AND resolved_scopes_json IS NOT NULL').run()).changes));
+}
+/** The `teams` a grant sync answer carried; absent (an unjoined install, an older directory) reads as none. */
+export function teamsOf(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new TypeError('invalid grant sync response');
+    return value.map((entry) => {
+        const { team, members } = (entry ?? {});
+        if (typeof team !== 'string' || !/^team:\S+$/.test(team) || !Array.isArray(members) ||
+            members.some((member) => typeof member !== 'string' || !/^user:[^\s*]+$/.test(member)))
+            throw new TypeError('invalid grant sync response');
+        return { team, members };
+    });
+}
+/** Replace the mirror with `grants` and the `written_by = 'directory'` team `member` facts with `teams`, in one transaction. The
+ *  ledger's `grant:<id>` limit rows follow from the `grants` trigger `crtr_grant_limit` (schema delta 002). */
+export async function replaceGrants(grants, syncedAt, source, teams = []) {
+    const ids = new Set();
+    for (const grant of grants) {
+        if (ids.has(grant.id) || !grant.id || !grant.runtime || !grant.sub || !grant.grantee ||
+            !Number.isInteger(grant.rev) || !['active', 'revoked', 'removed'].includes(grant.status)) {
+            throw new TypeError('invalid grant sync response');
+        }
+        ids.add(grant.id);
+        entries(grant.scopes);
+        entries(grant.resolved_scopes);
+    }
+    await withCanvasWrite(async (db) => {
+        // Only a changed grant is written: an unchanged one writes no row, so its `crtr_sig_grant_*` trigger fires nothing and
+        // `synced_at` alone never counts as a change. A grant the answer no longer holds is deleted.
+        let changed = 0;
+        const kept = [...ids];
+        changed += Number((await (kept.length
+            ? db.prepareUncached(`DELETE FROM grants WHERE id NOT IN (${kept.map(() => '?').join(',')})`).run(...kept)
+            : db.prepareUncached('DELETE FROM grants').run())).changes);
+        const upsert = db.prepare(`INSERT INTO grants
+      (id, runtime, sub, grantee, rev, scopes_json, resolved_scopes_json, spend_cap, expires_at,
+       status, revoked_at, approved_at, payer, dependencies_json, run_notice_url, inference_endpoint_json, synced_at, computed_rev)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT (id) DO UPDATE SET runtime = excluded.runtime, sub = excluded.sub, grantee = excluded.grantee, rev = excluded.rev,
+        scopes_json = excluded.scopes_json, resolved_scopes_json = excluded.resolved_scopes_json, spend_cap = excluded.spend_cap,
+        expires_at = excluded.expires_at, status = excluded.status, revoked_at = excluded.revoked_at, approved_at = excluded.approved_at,
+        removal_done_at = CASE WHEN excluded.status = 'removed' AND grants.status = 'removed' THEN grants.removal_done_at END,
+        payer = excluded.payer, dependencies_json = excluded.dependencies_json, run_notice_url = excluded.run_notice_url,
+        inference_endpoint_json = excluded.inference_endpoint_json, synced_at = excluded.synced_at, computed_rev = excluded.computed_rev
+      WHERE (grants.runtime, grants.sub, grants.grantee, grants.rev, grants.scopes_json, grants.resolved_scopes_json, grants.spend_cap,
+             grants.expires_at, grants.status, grants.revoked_at, grants.approved_at, grants.payer, grants.dependencies_json,
+             grants.run_notice_url, grants.inference_endpoint_json, grants.computed_rev)
+        IS DISTINCT FROM (excluded.runtime, excluded.sub, excluded.grantee, excluded.rev, excluded.scopes_json, excluded.resolved_scopes_json,
+             excluded.spend_cap, excluded.expires_at, excluded.status, excluded.revoked_at, excluded.approved_at, excluded.payer,
+             excluded.dependencies_json, excluded.run_notice_url, excluded.inference_endpoint_json, excluded.computed_rev)`);
+        for (const grant of grants) {
+            changed += Number((await upsert.run(grant.id, grant.runtime, grant.sub, grant.grantee, grant.rev, JSON.stringify(grant.scopes), JSON.stringify(grant.resolved_scopes), grant.spend_cap, grant.expires_at, grant.status, grant.revoked_at, grant.approved_at, grant.payer, JSON.stringify(dependenciesOf(grant.dependencies)), grant.run_notice_url ?? null, grant.inference_endpoint ? JSON.stringify(grant.inference_endpoint) : null, grant.synced_at, grant.rev)).changes);
+        }
+        await replaceWrittenBy(db, 'directory', GROUP_TYPE, 'member', teams.flatMap(({ team, members }) => members.map((member) => ({ resourceId: team, subject: userSubject(member) }))));
+        await db.prepare("INSERT INTO runtime_state (key, value) VALUES ('grants_source', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(source);
+        if (changed > 0)
+            await db.prepare("INSERT INTO runtime_state (key, value) VALUES ('grants_generation', '1') ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(runtime_state.value AS INTEGER) + 1 AS TEXT)").run();
+    });
+}
+/** Bumped by every `replaceGrants`. A launch compiled against one generation
+ *  and started under another may hold mounts the new mirror no longer grants. */
+export async function grantsGeneration() {
+    const state = await (await openDb()).prepare("SELECT value FROM runtime_state WHERE key = 'grants_generation'").get();
+    return state ? Number(state.value) : 0;
+}

package/dist/core/grants/on-sync.d.ts

@@ -0,0 +1,26 @@
+import type { SandboxRecord } from '../../launcher/spec.js';
+/** Work that outlives the sync that started it; the daemon keeps ownership of it during shutdown. */
+export type Detach = (work: Promise<void>) => void;
+/** Why a sandbox must stop under the current mirror, or null when every
+ *  granted mount it was launched with is still granted. */
+export declare function exceeds(sandbox: Pick<SandboxRecord, 'uid' | 'nodeId' | 'mounts'>, owners?: ReadonlyMap<number, {
+    app: string;
+    status: string;
+}>): Promise<string | null>;
+/** After a confirmed revocation stop: the node waits for its next message,
+ *  whose broker gets the current mounts (runtime spec §15), and its run reads
+ *  idle rather than running. */
+export declare function afterRevocationStop(nodeId: string): Promise<void>;
+/** R26 from current state (runtime spec §15 "Ending revoked file access"):
+ *  compare every live launcher sandbox's launched mounts with what the current
+ *  mirror grants, and stop each one that holds more. Runs after every sync and
+ *  once at daemon start, so a stop an earlier daemon never confirmed is retried.
+ *  Resolves once every stop has been started; `completion` settles when they end. */
+export declare function sweepSandboxes(): Promise<{
+    completion: Promise<void>;
+}>;
+/** R26 after a sync replaced the grant mirror (runtime spec §15): stop the launcher sandboxes that now hold more than the mirror
+ *  grants. Everything else a grant change causes (waking `grant.get` holds, closing streams, discarding tokens, stopping the
+ *  grant's nodes, the removal cascade, provider bundles) is done by the `grant:<id>` handlers of `daemon/reconcilers/grant-effects.ts`,
+ *  which the sync's row writes fire. Resolves once the stops have started; their completion continues as detached work. */
+export declare function onGrantSync(detach?: Detach): Promise<void>;

package/dist/core/grants/on-sync.js

@@ -0,0 +1,161 @@
+import { relative, sep } from 'node:path';
+import { runningJobs } from '../graph/jobs.js';
+import { appSpace } from '../layout.js';
+import { getNode, recordSettledTurn } from '../canvas/index.js';
+import { transition } from '../runtime/lifecycle.js';
+import { openDb } from '../canvas/db.js';
+import { emitEvent } from '../events/emit.js';
+import { grantedMounts, isGrantedSource, mountAllowed } from '../spaces/mounts.js';
+import { permissionsForRun } from '../spaces/permissions.js';
+import { stopNodeSandboxes } from '../spaces/stop.js';
+import { activeGrantForApp } from './mirror.js';
+import { launcherPresent, listSandboxes, stopSandboxPid } from './sandboxes.js';
+import { checkCronFire } from '../../daemon/cron/authority.js';
+import { cronExecutionFor } from '../../daemon/cron/live-runs.js';
+import { cronExecutionsReady } from '../../daemon/cron/run-socket.js';
+import { flatMapAsync } from '../async-array.js';
+import { personId } from '../canvas/person.js';
+async function appUserOwners() {
+    return new Map((await (await openDb()).prepare('SELECT uid, app, status FROM app_users').all())
+        .map((row) => [row.uid, { app: row.app, status: row.status }]));
+}
+/** Why a sandbox must stop under the current mirror, or null when every
+ *  granted mount it was launched with is still granted. */
+export async function exceeds(sandbox, owners) {
+    owners ??= await appUserOwners();
+    const owner = owners.get(sandbox.uid);
+    // A cron execution runs under its stored principal, not the app's whole grant: it stops when that principal's
+    // grant is gone or no longer covers its scopes, or when it holds more mounts than its own scopes grant. This runs
+    // before the terminal exemption below: a terminal cron is still bound to its stored grant, and fails closed.
+    const isCron = sandbox.nodeId.startsWith('cron-');
+    const cronExecution = isCron ? cronExecutionFor(sandbox.nodeId.slice('cron-'.length)) : undefined;
+    if (isCron && (cronExecution === undefined || !owner))
+        return 'permission_revoked';
+    if (cronExecution !== undefined && owner.status === 'active') {
+        const authority = await checkCronFire({ grantee: cronExecution.grantee, sub: cronExecution.sub, grant_id: cronExecution.grantId, scopes: cronExecution.scopes });
+        if (!authority.allowed) {
+            cronExecution.refusal ??= { reason: authority.reason, message: authority.message };
+            return 'permission_revoked';
+        }
+    }
+    if (!owner || owner.app === 'app:terminal')
+        return null;
+    if (owner.status !== 'active')
+        return 'app_removed';
+    const node = await getNode(sandbox.nodeId);
+    try {
+        let permissions;
+        if (cronExecution !== undefined) {
+            permissions = await permissionsForRun(cronExecution.grantee, cronExecution.sub, cronExecution.grantId, cronExecution.scopes);
+        }
+        else if (node && node.grantee === owner.app) {
+            permissions = await permissionsForRun(owner.app, node.sub ?? personId(), node.grant_id ?? null, node.scopes ?? null);
+        }
+        else {
+            // A process without a node (an unanchored cron, a delivery) runs on the app's whole grant.
+            const grant = await activeGrantForApp(owner.app);
+            if (!grant)
+                return 'permission_revoked';
+            permissions = await permissionsForRun(owner.app, grant.sub, grant.id, null);
+        }
+        const allowed = grantedMounts(permissions);
+        const ownRoot = appSpace(owner.app).root;
+        return sandbox.mounts.every((mount) => {
+            // On macOS the default user-files root is the parent of CRTR_HOME, so it
+            // also contains app spaces. An app's own mounts are not grant-derived.
+            const ownRelative = relative(ownRoot, mount.source);
+            const own = ownRelative === '' || (ownRelative !== '..' && !ownRelative.startsWith(`..${sep}`) && !ownRelative.startsWith(sep));
+            return own || !isGrantedSource(owner.app, mount.source) || mountAllowed(mount, allowed);
+        }) ? null : 'permission_revoked';
+    }
+    catch {
+        return 'permission_revoked';
+    }
+}
+/** After a confirmed revocation stop: the node waits for its next message,
+ *  whose broker gets the current mounts (runtime spec §15), and its run reads
+ *  idle rather than running. */
+export async function afterRevocationStop(nodeId) {
+    const node = await getNode(nodeId);
+    if (!node)
+        return;
+    if (node.status === 'active' || node.status === 'idle')
+        await transition(nodeId, 'release');
+    const at = new Date().toISOString();
+    await recordSettledTurn(nodeId, at);
+    if (node.run_id && node.run_id !== nodeId) {
+        await (await openDb()).prepare('UPDATE nodes SET last_settled_at = COALESCE(last_settled_at, ?) WHERE node_id = ?').run(at, node.run_id);
+    }
+}
+/** Every broker and job pid of a node that the launcher tracks. */
+async function nodePids(nodeId) {
+    const pids = new Set();
+    const node = await getNode(nodeId);
+    if (node?.pi_pid != null)
+        pids.add(node.pi_pid);
+    for (const job of await runningJobs(await openDb(), nodeId)) {
+        if (job.pgid !== null)
+            pids.add(job.pgid);
+    }
+    return pids;
+}
+/** R26 from current state (runtime spec §15 "Ending revoked file access"):
+ *  compare every live launcher sandbox's launched mounts with what the current
+ *  mirror grants, and stop each one that holds more. Runs after every sync and
+ *  once at daemon start, so a stop an earlier daemon never confirmed is retried.
+ *  Resolves once every stop has been started; `completion` settles when they end. */
+export async function sweepSandboxes() {
+    if (!launcherPresent())
+        return { completion: Promise.resolve() };
+    // A restart rebuild registers live cron executions first, so the sweep never stops one it has not yet re-registered.
+    await cronExecutionsReady();
+    const sandboxes = await listSandboxes();
+    const owners = await appUserOwners();
+    const excess = (await flatMapAsync(sandboxes, async (sandbox) => {
+        const reason = await exceeds(sandbox, owners);
+        return reason ? [{ sandbox, reason }] : [];
+    }));
+    const stops = [];
+    const byNode = new Map();
+    for (const entry of excess) {
+        emitEvent({ level: 'info', event: 'daemon.grants.sandbox_stop', fields: { sandbox_node: entry.sandbox.nodeId, pid: entry.sandbox.pid,
+                grantee: owners.get(entry.sandbox.uid).app, reason: entry.reason } });
+        const group = byNode.get(entry.sandbox.nodeId) ?? [];
+        group.push(entry);
+        byNode.set(entry.sandbox.nodeId, group);
+    }
+    for (const [nodeId, group] of byNode) {
+        const node = await getNode(nodeId);
+        const owned = node ? await nodePids(nodeId) : new Set();
+        const viaNode = node !== null && group.some(({ sandbox }) => owned.has(sandbox.pid));
+        stops.push((async () => {
+            // A broker or bash job stops through the node: its turn ends permission_revoked,
+            // its jobs record the reason, and the node is released only once the stop is confirmed.
+            if (viaNode) {
+                const result = await stopNodeSandboxes(nodeId, 'permission_revoked', { holdRecovery: true, after: () => afterRevocationStop(nodeId) });
+                if (!result.confirmed)
+                    throw result.error ?? new Error(`stop of ${nodeId} was not confirmed`);
+            }
+            // Foreground bash, hook, cron, and delivery sandboxes have no record beyond the launcher's.
+            for (const { sandbox } of group)
+                if (!viaNode || !owned.has(sandbox.pid))
+                    await stopSandboxPid(sandbox.pid);
+        })().catch((error) => {
+            emitEvent({ level: 'error', event: 'daemon.grants.sandbox_stop_failed', ...(node ? { node_id: nodeId } : { fields: { sandbox_node: nodeId } }), error });
+        }));
+    }
+    return { completion: Promise.all(stops).then(() => undefined) };
+}
+/** R26 after a sync replaced the grant mirror (runtime spec §15): stop the launcher sandboxes that now hold more than the mirror
+ *  grants. Everything else a grant change causes (waking `grant.get` holds, closing streams, discarding tokens, stopping the
+ *  grant's nodes, the removal cascade, provider bundles) is done by the `grant:<id>` handlers of `daemon/reconcilers/grant-effects.ts`,
+ *  which the sync's row writes fire. Resolves once the stops have started; their completion continues as detached work. */
+export async function onGrantSync(detach = (work) => { void work; }) {
+    try {
+        const { completion } = await sweepSandboxes();
+        detach(completion);
+    }
+    catch (error) {
+        emitEvent({ level: 'error', event: 'daemon.grants.sweep_failed', error });
+    }
+}

package/dist/core/grants/sandboxes.d.ts

@@ -0,0 +1,7 @@
+import { type SandboxRecord } from '../../launcher/spec.js';
+/** App sandboxes exist only where the root launcher runs (Linux). */
+export declare function launcherPresent(): boolean;
+/** Every live launcher sandbox with the mounts it was launched with. */
+export declare function listSandboxes(): Promise<SandboxRecord[]>;
+/** Kill one launcher sandbox. A pid the launcher no longer knows has already exited. */
+export declare function stopSandboxPid(pid: number): Promise<void>;

package/dist/core/grants/sandboxes.js

@@ -0,0 +1,24 @@
+import { existsSync } from 'node:fs';
+import { launcherRequest } from '../../launcher/client.js';
+import { LAUNCHER_SOCKET, LaunchRefused } from '../../launcher/spec.js';
+/** App sandboxes exist only where the root launcher runs (Linux). */
+export function launcherPresent() {
+    return process.platform === 'linux' && existsSync(LAUNCHER_SOCKET);
+}
+/** Every live launcher sandbox with the mounts it was launched with. */
+export async function listSandboxes() {
+    const reply = await launcherRequest({ operation: 'list' });
+    if (!('sandboxes' in reply))
+        throw new Error('launcher did not list sandboxes');
+    return reply.sandboxes;
+}
+/** Kill one launcher sandbox. A pid the launcher no longer knows has already exited. */
+export async function stopSandboxPid(pid) {
+    try {
+        await launcherRequest({ operation: 'stop', pid, signal: 'SIGKILL' });
+    }
+    catch (error) {
+        if (!(error instanceof LaunchRefused && error.refusal === 'invalid_spec'))
+            throw error;
+    }
+}

package/dist/core/grants/sync.d.ts

@@ -0,0 +1,46 @@
+import { type JsonWebKey } from 'node:crypto';
+import { type Detach } from './on-sync.js';
+export declare const GRANT_SYNC_INTERVAL_S = 300;
+export interface RuntimeClient {
+    jwk: JsonWebKey & {
+        kid: string;
+    };
+    kid: string;
+    alg: 'ES256';
+    client_id: string;
+    runtime: string;
+}
+/** A `private_key_jwt` client assertion for `endpoint` (the directory's token endpoint), signed by the runtime client key. */
+export declare function assertion(client: RuntimeClient, endpoint: string): string;
+export declare function runtimeClient(): RuntimeClient;
+/** The runtime's id as storage names it: the directory principal id without `runtime:`. */
+export declare function runtimeId(client?: RuntimeClient): string;
+/** The text a person sees when the directory no longer recognises this machine. */
+export declare function machineRevokedMessage(issuer: string): string;
+/** The directory answered `invalid_client` to this runtime's key: the machine was revoked. */
+export declare class MachineRevokedError extends Error {
+    constructor(issuer: string);
+}
+export interface DirectoryToken {
+    access_token: string;
+    expires_at: number;
+}
+/** A `client_credentials` token for the runtime client. With `audience`, the
+ *  directory issues it for that audience (the storage service); without, for
+ *  the directory's own `/v1`. `expires_at` is epoch ms. */
+export declare function mintDirectoryToken(issuer: string, audience?: string): Promise<DirectoryToken>;
+export type GrantSync = (options?: {
+    fresh?: boolean;
+}) => Promise<void>;
+/** Ask the daemon's grant sync (the latest `createGrantSync`) for a pull; a
+ *  no-op where none exists (v0, a process that is not the daemon). */
+export declare function requestGrantSync(options?: {
+    fresh?: boolean;
+}): Promise<void>;
+/** Calls share one in-flight pull, including the start, periodic, and
+ *  unknown-grant triggers. A `fresh` call (a directory sync notice) needs a pull
+ *  that started after it arrived: while one is in flight it queues exactly one
+ *  more, which every later fresh call shares. A pull resolves once the mirror is
+ *  committed and the R26 stops have started; stop completion and removal
+ *  cascades run as `detach`ed work. */
+export declare function createGrantSync(issuer: string, detach?: Detach): GrantSync;