@north-light/api 0.3.580 → 0.3.587

package/dist/core/providers/files.d.ts

@@ -0,0 +1,90 @@
+import { type StorageClient } from '../storage/client.js';
+/** The fields of `ProviderCaller` (daemon/api/handlers/providers.ts) this module
+ *  reads; a `ProviderCaller` is passed as is. */
+export interface FileCallCaller {
+    class: 'person' | 'app' | 'broker';
+    sub?: string | null;
+    grantee: string | null;
+    resolved: readonly string[] | null;
+    nodeScopes: readonly string[] | null;
+    run_id: string | null;
+    node_id: string | null;
+}
+/** What a leaf's manifest declares about files: its `file`-typed params and its
+ *  one top-level `file` output field (D3-FILE-5), if any. */
+export interface LeafFiles {
+    params: readonly string[];
+    output: string | null;
+}
+export interface FileOptions {
+    /** Test seam: the storage client (default: the configured one). */
+    storage?: () => StorageClient;
+    signal?: AbortSignal;
+}
+/** One file argument copied to storage's `outbound` area. */
+export interface FileArgumentCopy {
+    param: string;
+    /** The caller's absolute runtime path (never sent to the provider). */
+    path: string;
+    name: string;
+    object_id: string;
+    /** The signed GET URL the provider receives, valid 15 minutes. */
+    url: string;
+}
+/** The upload a file result is PUT to. */
+export interface ResultUpload {
+    field: string;
+    upload_id: string;
+    upload_link: string;
+    /** The app the upload is recorded under (`uploads.grantee`). */
+    grantee: string;
+}
+export interface PreparedFileCall {
+    /** The call's arguments with every file argument replaced by its URL. */
+    arguments: Record<string, unknown>;
+    copies: FileArgumentCopy[];
+    upload: ResultUpload | null;
+    /** `Crtr-Upload-Id` and `Crtr-Upload-Link` for a leaf with a file output;
+     *  empty otherwise (D3-WIRE-9). */
+    headers: Record<string, string>;
+}
+export interface ResolvedFileResult {
+    /** The result with the file field replaced by a runtime path (unchanged when
+     *  the provider omitted the field). */
+    result: unknown;
+    /** Where the file landed, or null when the field was absent. */
+    file: {
+        path: string;
+        upload_id: string;
+    } | null;
+    /** Remove what this resolve wrote (for a failure after it). Idempotent. */
+    cleanup: () => Promise<void>;
+}
+/** The fetch of a file result is bounded like an attachment fetch. */
+export declare const FILE_RESULT_FETCH_BUDGET_MS = 110000;
+/** Step 2 of a `provider.call` for a leaf with files, before any token is
+ *  minted: D3-FILE-1..3 for each file argument, then D3-FILE-6 for the output.
+ *  Refusals: `invalid_request` (`param`; also a file output on a cloud role), `scope_missing` (`scope`),
+ *  `not_found`, `storage_unavailable`. A leaf with no files never touches
+ *  storage. */
+export declare function prepareFileCall(caller: FileCallCaller, leaf: LeafFiles, args: Record<string, unknown>, options?: FileOptions): Promise<PreparedFileCall>;
+/** The approval retry (D3-FILE-10, R5): a new GET URL for each copy and a new
+ *  PUT link for the upload. A copy storage no longer has (404, over 24 hours)
+ *  is made again from the caller's original path under the same checks. An
+ *  upload gone (404) is replaced by a new upload; one already holding bytes
+ *  (409: the provider PUT before asking for approval) is kept with its link
+ *  unchanged, since a stored upload's link cannot be re-signed and the
+ *  provider answers with that upload's id (G20). `args` are the caller's
+ *  original arguments (paths, not URLs). */
+export declare function resignForRetry(caller: FileCallCaller, leaf: LeafFiles, args: Record<string, unknown>, prepared: PreparedFileCall, options?: FileOptions): Promise<PreparedFileCall>;
+/** D3-FILE-8/9 on a 2xx result: accept the file field only when it names this
+ *  call's upload and storage's stored size equals `size` (and the bytes hash to
+ *  `sha256`); fetch it into the calling node's `attachments/` folder (outside a
+ *  run, `/apps/<app>/files/`), named after the field and unique there; record
+ *  it against the run; replace the field with the absolute runtime path.
+ *  `provider_error` for a wrong field, upload, size, digest or nothing stored;
+ *  `storage_unavailable` when storage cannot be reached. On any refusal nothing
+ *  is left in the caller's folder. */
+export declare function resolveFileResult(caller: FileCallCaller, prepared: PreparedFileCall, result: unknown, options?: FileOptions & {
+    budgetMs?: number;
+}): Promise<ResolvedFileResult>;

package/dist/core/providers/files.js

@@ -0,0 +1,389 @@
+// Provider file arguments and file results (contract 3 "Files"; D3-FILE-1..10,
+// D3-WIRE-9). The only place a caller's file crosses to a provider, and a
+// provider's file crosses back: a provider sees storage URLs the daemon made,
+// never a runtime path, and the daemon never fetches a URL the provider chose.
+//
+// R4 (`provider.call`) uses three functions per call:
+//   1. `prepareFileCall` before minting: checks and copies every file argument,
+//      replaces each with a signed GET URL, and creates the result upload whose
+//      id and PUT link go out as `Crtr-Upload-Id` / `Crtr-Upload-Link`.
+//   2. `resolveFileResult` on a 2xx: validates the `{upload_id, size, sha256}`
+//      field, fetches the stored bytes into the caller's folder and replaces the
+//      field with that runtime path.
+//   3. `resignForRetry` (R5, the approval retry): new GET URLs for the same
+//      copies and a new PUT link for the same upload; a copy or upload that is
+//      gone (404) is made again under the same checks.
+// A connection-error retry reuses the prepared call unchanged.
+import { createHash } from 'node:crypto';
+import { closeSync, constants, createWriteStream } from 'node:fs';
+import { basename, extname, isAbsolute, join } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { appSpace } from '../layout.js';
+import { RunError } from '../runs/operations.js';
+import { createFileBeneath, existsBeneath, openBeneath, removeTreeBeneath, setModeBeneath, unlinkBeneath, withDirBeneath } from '../spaces/open-beneath.js';
+import { ensureAppSpace } from '../spaces/space.js';
+import { isCloudRole } from '../canvas/person-state.js';
+import { invalidStorageName, storageClient, StorageRefused, UPLOAD_MAX_BYTES } from '../storage/client.js';
+import { contentTypeFor, openCallerFile } from '../storage/download.js';
+import { withCanvasWrite } from '../canvas/db.js';
+import { deleteUploadUse, getUpload, insertUpload, insertUploadUses, setUploadSize, uploadUseAt } from '../storage/tables.js';
+import { ProviderError } from './errors.js';
+/** The fetch of a file result is bounded like an attachment fetch. */
+export const FILE_RESULT_FETCH_BUDGET_MS = 110_000;
+/** The person holds every file (contract 1 OWN-4) and acts as `app:terminal`
+ *  where a grantee is needed (the upload row, the landing folder). */
+const PERSON_APP = 'app:terminal';
+function grantee(caller) {
+    if (caller.class === 'person')
+        return caller.grantee ?? PERSON_APP;
+    if (!caller.grantee)
+        throw new ProviderError('server_error', 'provider caller has no grantee');
+    return caller.grantee;
+}
+/** The caller as contract 2's path rule reads it: the person holds every file;
+ *  an app token its grant; a broker node its grant narrowed by its `scopes`. */
+function fileCaller(caller) {
+    // A cloud role's person (`sub` set) is on another computer: this runtime holds none of their files, and `null` would let the path rule read its own.
+    if (caller.class === 'person' && caller.sub)
+        throw new ProviderError('invalid_request', 'the control plane cannot read files from your computer, so a file argument cannot be sent from here');
+    if (caller.class === 'person')
+        return null;
+    return { app: grantee(caller), resolved: caller.resolved ?? [], launched: caller.class === 'broker' ? caller.nodeScopes : null };
+}
+/** A storage failure (unreachable, not configured, or an unexpected refusal) as
+ *  the call's `storage_unavailable` (503, retryable; a storage that is not configured stays non-retryable). Anything else passes. */
+function storageFailure(error) {
+    if (error instanceof ProviderError)
+        return error;
+    if (error instanceof StorageRefused)
+        return new ProviderError('storage_unavailable', `storage refused: ${error.message}`);
+    if (error instanceof RunError && error.code === 'storage_unavailable')
+        return error.retryable ? new ProviderError('storage_unavailable', error.message) : error;
+    return error;
+}
+const providerError = (message) => new ProviderError('provider_error', message, { origin: 'provider' });
+/** D3-FILE-1/2 for one argument: absolute path → the path rule → an open
+ *  regular file beneath the covering permission's root, ≤ 100 MiB. The caller
+ *  closes the returned descriptor. */
+function checkFileArgument(caller, param, value) {
+    if (typeof value !== 'string' || !value || !isAbsolute(value) || value.includes('\0')) {
+        throw new ProviderError('invalid_request', `${param} must be an absolute runtime path`, { param });
+    }
+    let file;
+    try {
+        file = openCallerFile(fileCaller(caller), value);
+    }
+    catch (error) {
+        if (!(error instanceof RunError))
+            throw error;
+        if (error.code === 'scope_missing') {
+            throw new ProviderError('scope_missing', error.message, { param, ...(error.scope ? { scope: error.scope } : {}) });
+        }
+        // `openCallerFile` answers a symlink on the way with `invalid_request`; a
+        // provider file argument answers every path that is not a regular file the
+        // caller may read — absent, withheld, a directory, a symlink — `not_found`.
+        if (error.code === 'not_found' || error.code === 'invalid_request')
+            throw new ProviderError('not_found', `no such file: ${value}`, { param });
+        throw error;
+    }
+    try {
+        if (file.size > UPLOAD_MAX_BYTES)
+            throw new ProviderError('invalid_request', `${param} exceeds 100 MiB`, { param });
+        const name = basename(file.path);
+        const bad = invalidStorageName(name);
+        if (bad)
+            throw new ProviderError('invalid_request', `${param}: file name cannot be sent: ${bad}`, { param });
+        return { param, file, name, mediaType: contentTypeFor(file.path) };
+    }
+    catch (error) {
+        closeSync(file.fd);
+        throw error;
+    }
+}
+/** D3-FILE-3: copy an open, checked file to an `outbound` object, then sign a
+ *  GET URL for it (signed after the PUT so the provider has the full 15 min). */
+async function copyOutbound(storage, checked) {
+    try {
+        const created = await storage.createOutbound({ name: checked.name, size: checked.file.size, media_type: checked.mediaType });
+        await storage.putFileBytes(created.upload_link, checked.file.fd, checked.file.size, checked.mediaType);
+        const signed = await storage.signOutbound(created.object_id);
+        return { param: checked.param, path: checked.file.path, name: checked.name, object_id: created.object_id, url: signed.url };
+    }
+    catch (error) {
+        throw storageFailure(error);
+    }
+}
+/** Check every file argument, then copy them: a refusal of any argument copies
+ *  nothing. Absent (or null) optional file arguments pass through. */
+async function copyArguments(caller, params, args, storage) {
+    const checked = [];
+    try {
+        for (const param of params) {
+            if (args[param] === undefined || args[param] === null)
+                continue;
+            checked.push(checkFileArgument(caller, param, args[param]));
+        }
+        if (!checked.length)
+            return [];
+        let client;
+        try {
+            client = storage();
+        }
+        catch (error) {
+            throw storageFailure(error);
+        }
+        const copies = [];
+        for (const one of checked)
+            copies.push(await copyOutbound(client, one));
+        return copies;
+    }
+    finally {
+        for (const one of checked)
+            closeSync(one.file.fd);
+    }
+}
+/** D3-FILE-6: the upload a file result is PUT to, created with `max_size`
+ *  100 MiB and named after the output field (G19, G21). */
+function checkOutputField(field) {
+    const bad = invalidStorageName(field);
+    if (bad)
+        throw new ProviderError('server_error', `file output ${field} cannot name an upload: ${bad}`);
+}
+async function createResultUpload(caller, field, storage) {
+    checkOutputField(field);
+    const app = grantee(caller);
+    const mediaType = 'application/octet-stream';
+    let created;
+    try {
+        created = await storage().createResultUpload({ name: field, media_type: mediaType, max_size: UPLOAD_MAX_BYTES });
+    }
+    catch (error) {
+        throw storageFailure(error);
+    }
+    // `size` records the declared maximum until the file result is fetched,
+    // when it becomes the stored size.
+    // A row with no use is deleted by the due-work tick after 24 h (D3-FILE-9).
+    await insertUpload({ upload_id: created.upload_id, grantee: app, name: field, media_type: mediaType, size: UPLOAD_MAX_BYTES, created_at: new Date().toISOString() });
+    return { field, upload_id: created.upload_id, upload_link: created.upload_link, grantee: app };
+}
+function uploadHeaders(upload) {
+    return upload ? { 'Crtr-Upload-Id': upload.upload_id, 'Crtr-Upload-Link': upload.upload_link } : {};
+}
+function withUrls(args, copies) {
+    const out = { ...args };
+    for (const copy of copies)
+        out[copy.param] = copy.url;
+    return out;
+}
+/** Step 2 of a `provider.call` for a leaf with files, before any token is
+ *  minted: D3-FILE-1..3 for each file argument, then D3-FILE-6 for the output.
+ *  Refusals: `invalid_request` (`param`; also a file output on a cloud role), `scope_missing` (`scope`),
+ *  `not_found`, `storage_unavailable`. A leaf with no files never touches
+ *  storage. */
+export async function prepareFileCall(caller, leaf, args, options = {}) {
+    const storage = options.storage ?? storageClient;
+    if (leaf.output) {
+        checkOutputField(leaf.output);
+        // A cloud role has no folder to land a file result in (a node's files live in its sandbox), so it refuses the call here, before the provider runs
+        // and does anything it cannot take back, rather than after the upload.
+        if (isCloudRole())
+            throw new ProviderError('invalid_request', 'this command returns a file, which cannot be delivered to your computer from here yet, so it is not available from a moved Mac');
+    }
+    const copies = await copyArguments(caller, leaf.params, args, storage);
+    const upload = leaf.output ? await createResultUpload(caller, leaf.output, storage) : null;
+    return { arguments: withUrls(args, copies), copies, upload, headers: uploadHeaders(upload) };
+}
+/** The approval retry (D3-FILE-10, R5): a new GET URL for each copy and a new
+ *  PUT link for the upload. A copy storage no longer has (404, over 24 hours)
+ *  is made again from the caller's original path under the same checks. An
+ *  upload gone (404) is replaced by a new upload; one already holding bytes
+ *  (409: the provider PUT before asking for approval) is kept with its link
+ *  unchanged, since a stored upload's link cannot be re-signed and the
+ *  provider answers with that upload's id (G20). `args` are the caller's
+ *  original arguments (paths, not URLs). */
+export async function resignForRetry(caller, leaf, args, prepared, options = {}) {
+    const storage = options.storage ?? storageClient;
+    const copies = [];
+    for (const copy of prepared.copies) {
+        try {
+            const signed = await storage().signOutbound(copy.object_id);
+            copies.push({ ...copy, url: signed.url });
+        }
+        catch (error) {
+            if (!(error instanceof StorageRefused))
+                throw storageFailure(error);
+            copies.push(...await copyArguments(caller, [copy.param], args, storage));
+        }
+    }
+    let upload = prepared.upload;
+    if (upload) {
+        try {
+            const signed = await storage().signUploadLink(upload.upload_id);
+            upload = { ...upload, upload_link: signed.upload_link };
+        }
+        catch (error) {
+            if (!(error instanceof StorageRefused))
+                throw storageFailure(error);
+            if (error.status === 404)
+                upload = await createResultUpload(caller, leaf.output ?? upload.field, storage);
+        }
+    }
+    return { arguments: withUrls(args, copies), copies, upload, headers: uploadHeaders(upload) };
+}
+const SHA256 = /^[0-9a-f]{64}$/i;
+/** `out`, `out-2`, `out-3`, … (`report.pdf`, `report-2.pdf`, …). */
+function candidate(name, n) {
+    if (n === 1)
+        return name;
+    const ext = extname(name);
+    return ext && ext !== name ? `${name.slice(0, -ext.length)}-${n}${ext}` : `${name}-${n}`;
+}
+/** D3-FILE-8/9 on a 2xx result: accept the file field only when it names this
+ *  call's upload and storage's stored size equals `size` (and the bytes hash to
+ *  `sha256`); fetch it into the calling node's `attachments/` folder (outside a
+ *  run, `/apps/<app>/files/`), named after the field and unique there; record
+ *  it against the run; replace the field with the absolute runtime path.
+ *  `provider_error` for a wrong field, upload, size, digest or nothing stored;
+ *  `storage_unavailable` when storage cannot be reached. On any refusal nothing
+ *  is left in the caller's folder. */
+export async function resolveFileResult(caller, prepared, result, options = {}) {
+    const unchanged = { result, file: null, cleanup: async () => undefined };
+    const upload = prepared.upload;
+    if (!upload || !result || typeof result !== 'object' || Array.isArray(result))
+        return unchanged;
+    const body = result;
+    const value = body[upload.field];
+    // An omitted field leaves the upload unused; storage deletes it (D3-FILE-9).
+    if (value === undefined || value === null)
+        return unchanged;
+    if (typeof value !== 'object' || Array.isArray(value))
+        throw providerError(`${upload.field} must be {upload_id, size, sha256}`);
+    const claim = value;
+    if (typeof claim.upload_id !== 'string' || typeof claim.size !== 'number' || !Number.isSafeInteger(claim.size) || claim.size < 0 || typeof claim.sha256 !== 'string' || !SHA256.test(claim.sha256)) {
+        throw providerError(`${upload.field} must be {upload_id, size, sha256}`);
+    }
+    if (claim.upload_id !== upload.upload_id)
+        throw providerError(`${upload.field} names an upload other than Crtr-Upload-Id`);
+    const size = claim.size;
+    const sha256 = claim.sha256.toLowerCase();
+    const deadline = AbortSignal.timeout(options.budgetMs ?? FILE_RESULT_FETCH_BUDGET_MS);
+    const signal = options.signal ? AbortSignal.any([deadline, options.signal]) : deadline;
+    let fetched;
+    try {
+        fetched = await (options.storage ?? storageClient)().fetchUpload(upload.upload_id, signal);
+    }
+    catch (error) {
+        if (error instanceof StorageRefused)
+            throw providerError(`${upload.field} names an upload with nothing stored`);
+        throw storageFailure(error);
+    }
+    if (fetched.size === null) {
+        fetched.body.destroy();
+        throw new ProviderError('storage_unavailable', `storage did not say how many bytes ${upload.field} holds`);
+    }
+    if (fetched.size !== size) {
+        fetched.body.destroy();
+        throw providerError(`${upload.field} claims ${size} bytes; storage holds ${fetched.size}`);
+    }
+    const app = upload.grantee;
+    const inNode = caller.node_id !== null;
+    const space = await ensureAppSpace(app);
+    const root = inNode ? appSpace(app).nodes : appSpace(app).files;
+    const nodeDir = inNode ? join(root, caller.node_id) : root;
+    const dir = inNode ? join(nodeDir, 'attachments') : root;
+    // Owner and mode as for an attachment: the daemon keeps ownership; group and
+    // 0660 let the agent change and delete its copy.
+    const owner = { uid: process.getuid?.() ?? 0, gid: space.gid };
+    const createdNodeDir = inNode && !existsBeneath(root, nodeDir);
+    const createdDir = inNode && !createdNodeDir && !existsBeneath(root, dir);
+    let path = null;
+    let use = null;
+    let cleaned = false;
+    const cleanup = async () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        if (use) {
+            try {
+                await deleteUploadUse(use);
+            }
+            catch { /* best-effort */ }
+        }
+        if (path) {
+            try {
+                unlinkBeneath(root, path);
+            }
+            catch { /* already gone */ }
+        }
+        try {
+            if (createdNodeDir)
+                removeTreeBeneath(root, nodeDir);
+            else if (createdDir)
+                removeTreeBeneath(root, dir);
+        }
+        catch { /* best-effort */ }
+    };
+    try {
+        withDirBeneath(root, dir, () => undefined, true);
+        for (let n = 1;; n++) {
+            const next = join(dir, candidate(upload.field, n));
+            // A name whose file is gone may still carry a recorded use (the agent
+            // deleted its copy); `upload_uses` is keyed by (run, path), so skip it.
+            if (await uploadUseAt(next))
+                continue;
+            try {
+                createFileBeneath(root, next, Buffer.alloc(0), 0o660);
+                path = next;
+                break;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+        let bytes = 0;
+        const hash = createHash('sha256');
+        const count = new Transform({ transform(chunk, _encoding, done) { bytes += chunk.length; hash.update(chunk); done(null, chunk); } });
+        const fd = openBeneath(root, path, constants.O_WRONLY);
+        try {
+            await pipeline(fetched.body, count, createWriteStream('', { fd, autoClose: true }), { signal });
+        }
+        catch (error) {
+            if (deadline.aborted)
+                throw new ProviderError('storage_unavailable', 'the file result could not be fetched within 110 s');
+            if (error instanceof RunError)
+                throw storageFailure(error);
+            throw new ProviderError('storage_unavailable', `storage stopped sending ${upload.field}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (bytes !== size)
+            throw new ProviderError('storage_unavailable', `storage sent ${bytes} of ${size} bytes of ${upload.field}`);
+        if (hash.digest('hex') !== sha256)
+            throw providerError(`${upload.field}: the stored bytes do not match sha256`);
+        setModeBeneath(root, path, 0o660, owner);
+        const landed = path;
+        // One write accepts the result: the upload row takes the stored size and,
+        // inside a run, the upload is recorded against it so `run.delete` releases
+        // it — unless the run was deleted, or the upload marked for deletion, while
+        // the bytes were fetched (the upload then has no use and storage deletes it).
+        await withCanvasWrite(async (tx) => {
+            const row = await getUpload(upload.upload_id, tx);
+            if (!row || row.delete_pending_since)
+                throw new ProviderError('not_found', `${upload.field}: the upload was deleted while it was fetched`);
+            await setUploadSize(upload.upload_id, size, tx);
+            if (!caller.run_id)
+                return;
+            const run = await tx.prepare('SELECT deleting_at FROM nodes WHERE node_id = ?').get(caller.run_id);
+            if (!run || run.deleting_at)
+                throw new ProviderError('not_found', `run ${caller.run_id} was deleted while its file result was fetched`);
+            use = { upload_id: upload.upload_id, run_id: caller.run_id, path: landed };
+            await insertUploadUses([use], tx);
+        });
+    }
+    catch (error) {
+        fetched.body.destroy();
+        await cleanup();
+        throw error;
+    }
+    return { result: { ...body, [upload.field]: path }, file: { path, upload_id: upload.upload_id }, cleanup };
+}

package/dist/core/providers/inflight.d.ts

@@ -0,0 +1,13 @@
+export interface InflightProviderCall {
+    request_id: string;
+    run_id: string | null;
+    node_id: string | null;
+    controller: AbortController;
+}
+/** Register a call for its entire lifetime (including backoff and file retrieval). */
+export declare function registerProviderCall(call: InflightProviderCall): () => void;
+/** R9's run operations can abort matching calls without closing unrelated sockets. */
+export declare function abortProviderCalls(target: {
+    run?: string;
+    nodes?: readonly string[];
+}): void;

package/dist/core/providers/inflight.js

@@ -0,0 +1,14 @@
+const calls = new Map();
+/** Register a call for its entire lifetime (including backoff and file retrieval). */
+export function registerProviderCall(call) {
+    calls.set(call.request_id, call);
+    return () => { if (calls.get(call.request_id) === call)
+        calls.delete(call.request_id); };
+}
+/** R9's run operations can abort matching calls without closing unrelated sockets. */
+export function abortProviderCalls(target) {
+    for (const call of calls.values()) {
+        if ((target.run && call.run_id === target.run) || (target.nodes && call.node_id && target.nodes.includes(call.node_id)))
+            call.controller.abort();
+    }
+}

package/dist/core/providers/mint.d.ts

@@ -0,0 +1,29 @@
+import { type GrantSync } from '../grants/sync.js';
+import { type CachedToken, type OutboundTokenRequest } from './token-cache.js';
+export type { OutboundTokenRequest } from './token-cache.js';
+export { discardFile } from './token-cache.js';
+/** How long the token endpoint has to answer. */
+export declare const MINT_TIMEOUT_MS = 10000;
+/** Waits before the second and third attempt at a token endpoint that answered 502, 503 or 504. */
+export declare const MINT_RETRY_DELAYS_MS: number[];
+export interface MintOptions {
+    /** The directory issuer; default `directoryIssuer()`. */
+    issuer?: string;
+    /** The caller's signal: an abort rethrows its reason, not a mapped error. */
+    signal?: AbortSignal;
+    /** Test seam for the token endpoint. */
+    fetch?: typeof fetch;
+    /** The grant sync a stale-grant refusal triggers; default the daemon's (`requestGrantSync`). */
+    syncGrants?: GrantSync;
+    /** Clock for the reuse window (epoch ms). */
+    now?: () => number;
+}
+/** A token ready to send, plus the cache key R4 passes to `discardFile` on a provider 401. */
+export interface OutboundToken extends CachedToken {
+    key: string;
+}
+/** Mint one outbound token (no cache). Throws a mapped `ProviderError`. */
+export declare function mintOutboundToken(request: OutboundTokenRequest, options?: MintOptions): Promise<CachedToken>;
+/** The outbound token for `request`: the cached one while `now < exp − 30 s`
+ *  (D3-TOK-9), else a fresh mint, cached. Throws a mapped `ProviderError`. */
+export declare function outboundToken(request: OutboundTokenRequest, options?: MintOptions): Promise<OutboundToken>;