@try-works/dsh-tool-mode 0.0.0-stage → 0.5.45

package/lib/asset-acquisition.js

@@ -0,0 +1,175 @@
+/**
+ * Verified atomic asset acquisition (RES-03, RES-07).
+ *
+ * The requirement's rules are all about what must NOT be observable:
+ *
+ * - **A partial download must never be usable.** Bytes are written to a temporary
+ *   sibling, verified against the expected digest, and only then renamed into place.
+ *   A file at the final path is therefore either absent or complete and correct —
+ *   which is why the temp file is a sibling rather than somewhere else: a rename
+ *   within one directory is atomic, and one across filesystems is not.
+ * - **A failed or interrupted preparation cannot become ready.** A digest mismatch
+ *   deletes the partial rather than keeping it for a retry that would resume from
+ *   bytes already known to be wrong.
+ * - **Uninstall and purge are separate** (RES-03). Acquisition records ownership; it
+ *   never deletes. Deletion is `purgeCandidates`, which refuses to remove an asset
+ *   another owner still holds.
+ * - **No source changes or binary builds on the end-user machine.** This acquires
+ *   pinned bytes; there is no compile step here to disable.
+ *
+ * Everything that touches the network or the filesystem is INJECTED, so the failure
+ * paths — which are the ones that matter and the ones a real download makes hard to
+ * reach — are exercised by test.
+ *
+ * @module @try-works/dsh-tool-mode/asset-acquisition
+ */
+import { createHash } from 'node:crypto';
+/** Where an asset lives once acquired. */
+function contentPath(root, digest) {
+    return `${root}/${digest}`;
+}
+/** The temporary sibling a transfer lands in before verification. */
+function partialPath(root, digest) {
+    // A SIBLING of the final path, so the rename is within one directory and therefore
+    // atomic. A temp directory elsewhere would make the final rename a copy.
+    return `${root}/.partial-${digest}`;
+}
+/** Hash bytes with the algorithm the digest length implies. */
+function digestOf(bytes, expectedLength) {
+    // SHA-512 is 128 hex characters, SHA-256 is 64. Inferring from the expected length
+    // means a lock written in either is verified with the right algorithm rather than a
+    // mismatch that looks like corruption.
+    return createHash(expectedLength > 64 ? 'sha512' : 'sha256').update(bytes).digest('hex');
+}
+/**
+ * Whether two hex digests name the same content.
+ *
+ * HEX CASE IS NOT SEMANTIC. `crypto` emits lower case, while an extension lock may
+ * record either case (Laya's records upper case). Comparing the raw strings rejected
+ * a correctly seeded blob, so the acquisition fell through to the lock's prose source
+ * and failed with `Failed to parse URL` even though the verified bytes were on disk.
+ * @param left - one hex digest.
+ * @param right - the other hex digest.
+ * @returns true when they differ only in case.
+ */
+export function sameDigest(left, right) {
+    return left.toLowerCase() === right.toLowerCase();
+}
+/**
+ * Acquire one asset, atomically and verified (RES-03).
+ *
+ * @param asset - the planned asset.
+ * @param options - the store, the source, the root and a cancellation signal.
+ * @returns the result, which never leaves a partial at the final path.
+ */
+export async function acquireAsset(asset, options) {
+    const { store, source, root, signal } = options;
+    const finalPath = contentPath(root, asset.digest);
+    const partial = partialPath(root, asset.digest);
+    // Already acquired and verified by a previous run: nothing to do, and nothing to
+    // re-download. This is also what makes two owners share one set of bytes.
+    if (store.exists(finalPath) && sameDigest(digestOf(store.read(finalPath) ?? new Uint8Array(), asset.digest.length), asset.digest)) {
+        return { acquired: true, path: finalPath, digest: asset.digest, transferredBytes: 0, resumed: false };
+    }
+    const chunkBytes = options.chunkBytes ?? 4 * 1024 * 1024;
+    // Resumption is only attempted when the source can serve ranges. Assuming a partial
+    // is resumable against a source that cannot would append a full response to a
+    // partial and produce bytes that hash wrong for a reason that looks like corruption.
+    let offset = source.supportsRanges ? store.sizeOf(partial) : 0;
+    const resumed = offset > 0;
+    if (!source.supportsRanges && store.exists(partial))
+        store.remove(partial);
+    let transferred = 0;
+    try {
+        while (offset < asset.bytes) {
+            if (signal.aborted) {
+                // The partial is LEFT in place, because it is verifiable bytes and a later
+                // attempt can resume from it; it is not at the final path, so nothing can use
+                // it as though it were complete.
+                return { acquired: false, reason: 'the transfer was cancelled', retryable: true };
+            }
+            const to = Math.min(offset + chunkBytes, asset.bytes) - 1;
+            const chunk = await source.fetchRange(asset, offset, to, signal);
+            if (chunk.byteLength === 0) {
+                // A zero-length chunk before the declared size means the source ended early.
+                return {
+                    acquired: false,
+                    reason: `the source ended at ${offset} of ${asset.bytes} bytes`,
+                    retryable: true,
+                };
+            }
+            // Appended rather than accumulated in memory: a 349 MB asset must not need a
+            // 349 MB buffer to be resumed.
+            store.write(partial, appendTo(store.read(partial), chunk));
+            offset += chunk.byteLength;
+            transferred += chunk.byteLength;
+        }
+        const completed = store.read(partial) ?? new Uint8Array();
+        if (completed.byteLength !== asset.bytes) {
+            store.remove(partial);
+            return {
+                acquired: false,
+                reason: `received ${completed.byteLength} bytes, expected ${asset.bytes}`,
+                retryable: true,
+            };
+        }
+        const actual = digestOf(completed, asset.digest.length);
+        if (!sameDigest(actual, asset.digest)) {
+            // RES-03: a failed preparation cannot become ready, and bytes already known to
+            // be wrong must not be kept for a retry that would resume from them.
+            store.remove(partial);
+            return {
+                acquired: false,
+                reason: `the asset digest is ${actual}, not the pinned ${asset.digest}`,
+                retryable: false,
+            };
+        }
+        // The whole point: verified bytes move into place in one atomic step, so the final
+        // path is never a partial file.
+        store.rename(partial, finalPath);
+        return { acquired: true, path: finalPath, digest: asset.digest, transferredBytes: transferred, resumed };
+    }
+    catch (error) {
+        // A transport failure leaves the partial for a resume and reports retryable, so a
+        // caller can tell a flaky network from a corrupt asset.
+        return {
+            acquired: false,
+            reason: error instanceof Error ? error.message : String(error),
+            retryable: true,
+        };
+    }
+}
+/** Concatenate a previous buffer with a new chunk. */
+function appendTo(previous, chunk) {
+    if (previous === undefined)
+        return chunk;
+    const out = new Uint8Array(previous.byteLength + chunk.byteLength);
+    out.set(previous, 0);
+    out.set(chunk, previous.byteLength);
+    return out;
+}
+/**
+ * Describe a memory admission, without overstating what is enforced (RES-07).
+ * @param input - the enforced and estimated figures.
+ * @returns the estimate, with the scope stated.
+ */
+export function describeMemory(input) {
+    return {
+        enforcedBytes: input.enforcedBytes,
+        estimatedBytes: input.estimatedBytes,
+        enforcedScope: input.enforcedScope,
+        measured: input.measured ?? false,
+    };
+}
+/**
+ * Whether an enforced limit actually bounds the whole process tree (RES-07).
+ *
+ * A V8 heap cap does NOT, and treating it as though it did is the specific mistake the
+ * requirement names.
+ * @param estimate - the estimate.
+ * @returns whether the enforcement covers the process tree.
+ */
+export function boundsProcessTree(estimate) {
+    return estimate.enforcedScope === 'process-tree';
+}
+//# sourceMappingURL=asset-acquisition.js.map

package/lib/authority.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Caller authority: the grant a tool invocation runs under (SEC-03, SEC-06).
+ *
+ * The governing rule is BASE-05: an external request cannot supply or forge these
+ * authorities. Everything here is constructed by the HOST from operator
+ * configuration, never from a request body, a `clientInfo.name`, a requested tool
+ * list, or a path a caller supplied. A caller's arguments are then checked
+ * AGAINST the grant; they never expand it.
+ *
+ * Path handling is deliberately paranoid. SEC-06 requires resolving Windows drive
+ * letters, separators, Unicode, junctions and symlinks safely, rejecting escapes,
+ * unsupported UNC/device paths and unauthorized roots, and refusing when
+ * authorization cannot be established. The resolver therefore returns the
+ * CANONICAL path for the caller to open, rather than validating a string and
+ * letting a later open re-resolve it — that gap is the classic check-then-open
+ * race, and a symlink swapped between the two steps would win it.
+ *
+ * @module @try-works/dsh-tool-mode/authority
+ */
+/** The stable error codes a denied request reports (SPEC §4 error vocabulary). */
+export type AuthorityErrorCode = 
+/** The path was not absolute; SEC-06 admits absolute paths only. */
+'PATH_NOT_ABSOLUTE'
+/** A UNC or Windows device path, which v1 refuses outright. */
+ | 'PATH_UNSUPPORTED'
+/** The path does not exist, so it cannot be authorized. */
+ | 'PATH_NOT_FOUND'
+/** The path resolves outside every approved root. */
+ | 'PATH_OUTSIDE_GRANT'
+/** The tool is not in the grant's allowed set. */
+ | 'TOOL_NOT_GRANTED'
+/** The harness executor profile is not explicitly allowed by the grant. */
+ | 'PROFILE_NOT_GRANTED'
+/** The model capability is not explicitly allowed by the grant. */
+ | 'CAPABILITY_NOT_GRANTED'
+/** The grant does not exist or was revoked. */
+ | 'GRANT_REVOKED';
+/** A refused invocation. Carries a recovery hint, not just a refusal. */
+export declare class AuthorityError extends Error {
+    readonly name = "AuthorityError";
+    readonly code: AuthorityErrorCode;
+    /** Actionable next step for the caller or operator. */
+    readonly hint: string;
+    constructor(code: AuthorityErrorCode, message: string, hint: string);
+}
+/** Absolute resource limits applied to every invocation under a grant. */
+export interface GrantLimits {
+    /** Largest admitted input, in bytes. */
+    readonly maxInputBytes: number;
+    /** Largest admitted audio duration, in seconds. */
+    readonly maxAudioSeconds: number;
+    /** Largest admitted inline result, in bytes. */
+    readonly maxResultBytes: number;
+    /** Largest number of model calls one root invocation may make. */
+    readonly maxModelCalls: number;
+    /** Largest output-token budget one root invocation may use. */
+    readonly maxOutputTokens: number;
+    /** Largest number of image inputs one invocation may bind. */
+    readonly maxImages: number;
+    /** Root wall-clock deadline for one invocation, in milliseconds. */
+    readonly deadlineMs: number;
+}
+/** What a caller is permitted to do (SEC-03). */
+export interface ToolGrant {
+    /** Stable grant identity, recorded in receipts. */
+    readonly grantId: string;
+    /** Tool names this caller may invoke. A requested list never extends it. */
+    readonly allowedTools: readonly string[];
+    /**
+     * Filesystem roots the caller may read from, as absolute paths.
+     * Canonicalized when the grant is built, so a symlinked root cannot be declared
+     * one way and resolve another.
+     */
+    readonly approvedRoots: readonly string[];
+    /** Remote destinations this caller may reach. Empty means none. */
+    readonly remoteDestinations: readonly string[];
+    /** Operator-approved harness executor profiles this caller may select. */
+    readonly allowedHarnessProfiles: readonly string[];
+    /** Model capabilities (input/output modalities) this caller may use. */
+    readonly modelCapabilities: readonly string[];
+    /** Whether hosted code execution is permitted. */
+    readonly hostedCode: boolean;
+    /** Whether receipts may be recorded. */
+    readonly recordingPolicy: 'none' | 'receipts';
+    /** Hard resource limits. */
+    readonly limits: GrantLimits;
+}
+/** Build a grant, canonicalizing its roots. */
+export interface GrantInput {
+    readonly grantId: string;
+    readonly allowedTools: readonly string[];
+    readonly approvedRoots: readonly string[];
+    readonly remoteDestinations?: readonly string[];
+    readonly allowedHarnessProfiles?: readonly string[];
+    readonly modelCapabilities?: readonly string[];
+    readonly hostedCode?: boolean;
+    readonly recordingPolicy?: 'none' | 'receipts';
+    readonly limits?: Partial<GrantLimits>;
+}
+/** Conservative defaults: a grant that declares nothing permits almost nothing. */
+export declare const DEFAULT_LIMITS: GrantLimits;
+/**
+ * Build a grant from operator configuration.
+ *
+ * This is the only constructor: a request cannot reach it, and an approved root
+ * that is not absolute or not resolvable is dropped rather than trusted.
+ * @param input - the operator's declaration.
+ * @returns the canonicalized grant.
+ */
+export declare function createGrant(input: GrantInput): ToolGrant;
+/**
+ * Authorize one caller-supplied path against a grant (SEC-06).
+ *
+ * Returns the CANONICAL path, which the caller must open. Validating the original
+ * string and opening it later would leave a window in which a symlink could be
+ * swapped; resolving once and returning the result closes it.
+ * @param grant - the caller's grant.
+ * @param candidate - the caller-supplied path.
+ * @returns the canonical, authorized path.
+ * @throws AuthorityError when the path is inadmissible, missing, or outside the grant.
+ */
+export declare function authorizePath(grant: ToolGrant, candidate: string): string;
+/**
+ * Authorize a tool name against a grant (SEC-03).
+ * @param grant - the caller's grant.
+ * @param toolName - the requested tool.
+ * @throws AuthorityError with `TOOL_NOT_GRANTED`.
+ */
+export declare function authorizeTool(grant: ToolGrant, toolName: string): void;
+/**
+ * Authorize an operator-bound harness executor profile (SEC-03/HLM-03).
+ * @param grant - the caller's grant.
+ * @param profile - the logical profile the recipe selected.
+ * @throws AuthorityError with `PROFILE_NOT_GRANTED`.
+ */
+export declare function authorizeHarnessProfile(grant: ToolGrant, profile: string): void;
+/**
+ * Authorize the model capabilities an executor will use (SEC-03).
+ * @param grant - the caller's grant.
+ * @param required - the input/output modalities required by the selected model.
+ * @throws AuthorityError with `CAPABILITY_NOT_GRANTED`.
+ */
+export declare function authorizeModelCapabilities(grant: ToolGrant, required: readonly string[]): void;
+/**
+ * Authorize a remote destination against a grant (SEC-10).
+ *
+ * No silent local-to-remote fallback: if a destination was not explicitly
+ * approved, the call is refused rather than downgraded or upgraded.
+ * @param grant - the caller's grant.
+ * @param destination - the destination origin.
+ * @throws AuthorityError with `TOOL_NOT_GRANTED`.
+ */
+export declare function authorizeDestination(grant: ToolGrant, destination: string): void;
+/**
+ * The trusted execution context handed to an implementation.
+ *
+ * An implementation receives resolved authority, never a raw path it must
+ * re-check, and never anything a caller could have constructed.
+ */
+export interface InvocationAuthority {
+    /** Grant identity, for the receipt. */
+    readonly grantId: string;
+    /** Who is calling, as the host resolved it. */
+    readonly callerKind: 'interactive' | 'external' | 'system';
+    /** Resource limits in force. */
+    readonly limits: GrantLimits;
+    /** Whether receipts may be recorded. */
+    readonly recordingPolicy: 'none' | 'receipts';
+    /**
+     * Resolve a caller-supplied path to a canonical authorized path.
+     * @param candidate - the caller-supplied path.
+     * @returns the canonical path to open.
+     */
+    resolvePath(candidate: string): string;
+}
+/**
+ * Build the invocation authority for one call.
+ *
+ * The result is constructed by the host; a request body has no path to it.
+ * @param grant - the caller's grant.
+ * @param callerKind - how the host classified the caller.
+ * @returns the authority handed to the implementation.
+ */
+export declare function createInvocationAuthority(grant: ToolGrant, callerKind: InvocationAuthority['callerKind']): InvocationAuthority;
+//# sourceMappingURL=authority.d.ts.map

package/lib/authority.d.ts.map

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

package/lib/authority.js

@@ -0,0 +1,223 @@
+/**
+ * Caller authority: the grant a tool invocation runs under (SEC-03, SEC-06).
+ *
+ * The governing rule is BASE-05: an external request cannot supply or forge these
+ * authorities. Everything here is constructed by the HOST from operator
+ * configuration, never from a request body, a `clientInfo.name`, a requested tool
+ * list, or a path a caller supplied. A caller's arguments are then checked
+ * AGAINST the grant; they never expand it.
+ *
+ * Path handling is deliberately paranoid. SEC-06 requires resolving Windows drive
+ * letters, separators, Unicode, junctions and symlinks safely, rejecting escapes,
+ * unsupported UNC/device paths and unauthorized roots, and refusing when
+ * authorization cannot be established. The resolver therefore returns the
+ * CANONICAL path for the caller to open, rather than validating a string and
+ * letting a later open re-resolve it — that gap is the classic check-then-open
+ * race, and a symlink swapped between the two steps would win it.
+ *
+ * @module @try-works/dsh-tool-mode/authority
+ */
+import { realpathSync } from 'node:fs';
+import { isAbsolute, sep } from 'node:path';
+/** A refused invocation. Carries a recovery hint, not just a refusal. */
+export class AuthorityError extends Error {
+    name = 'AuthorityError';
+    code;
+    /** Actionable next step for the caller or operator. */
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+    }
+}
+/** Conservative defaults: a grant that declares nothing permits almost nothing. */
+export const DEFAULT_LIMITS = {
+    maxInputBytes: 64 * 1024 * 1024,
+    maxAudioSeconds: 3600,
+    maxResultBytes: 8 * 1024 * 1024,
+    maxModelCalls: 1,
+    maxOutputTokens: 1024,
+    maxImages: 2,
+    deadlineMs: 60_000,
+};
+/** Whether this process is on a case-insensitive filesystem. */
+const CASE_INSENSITIVE = process.platform === 'win32' || process.platform === 'darwin';
+/**
+ * Canonicalize a root for containment comparison.
+ *
+ * A root that does not exist is still admitted, because an operator may declare a
+ * root before creating it; it simply can never contain anything until it exists,
+ * which fails closed.
+ * @param root - the declared root.
+ * @returns the canonical root, or undefined when it cannot be resolved yet.
+ */
+function canonicalizeRoot(root) {
+    if (!isAbsolute(root))
+        return undefined;
+    try {
+        return realpathSync.native(root);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build a grant from operator configuration.
+ *
+ * This is the only constructor: a request cannot reach it, and an approved root
+ * that is not absolute or not resolvable is dropped rather than trusted.
+ * @param input - the operator's declaration.
+ * @returns the canonicalized grant.
+ */
+export function createGrant(input) {
+    const roots = [];
+    for (const root of input.approvedRoots) {
+        const canonical = canonicalizeRoot(root);
+        // A root that cannot be canonicalized is dropped, not guessed at. Dropping
+        // fails closed; keeping an unresolved string would fail open.
+        if (canonical !== undefined)
+            roots.push(canonical);
+    }
+    return {
+        grantId: input.grantId,
+        allowedTools: [...input.allowedTools],
+        approvedRoots: roots,
+        remoteDestinations: [...(input.remoteDestinations ?? [])],
+        allowedHarnessProfiles: [...(input.allowedHarnessProfiles ?? [])],
+        modelCapabilities: [...(input.modelCapabilities ?? [])],
+        hostedCode: input.hostedCode ?? false,
+        recordingPolicy: input.recordingPolicy ?? 'none',
+        limits: { ...DEFAULT_LIMITS, ...input.limits },
+    };
+}
+/** Compare two paths for equality under this platform's case rules. */
+function samePath(a, b) {
+    return CASE_INSENSITIVE ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+/** Whether `child` is `root` itself or lies beneath it, on a separator boundary. */
+function isWithin(child, root) {
+    if (samePath(child, root))
+        return true;
+    const prefix = root.endsWith(sep) ? root : root + sep;
+    return CASE_INSENSITIVE
+        ? child.toLowerCase().startsWith(prefix.toLowerCase())
+        : child.startsWith(prefix);
+}
+/**
+ * Reject path shapes v1 does not admit, before any filesystem call.
+ * @param candidate - the caller-supplied path.
+ * @throws AuthorityError with `PATH_UNSUPPORTED` or `PATH_NOT_ABSOLUTE`.
+ */
+function assertAdmissibleShape(candidate) {
+    // Windows device namespaces bypass normal path handling entirely, and a UNC
+    // path reaches another host that no approved root can describe.
+    if (candidate.startsWith('\\\\') || candidate.startsWith('//')) {
+        throw new AuthorityError('PATH_UNSUPPORTED', 'UNC and Windows device paths are not admitted', 'Use an absolute path on a local drive that lies under an approved root.');
+    }
+    if (candidate.includes('\0')) {
+        throw new AuthorityError('PATH_UNSUPPORTED', 'the path contains a NUL byte', 'Pass the path as a plain string without embedded control characters.');
+    }
+    if (!isAbsolute(candidate)) {
+        throw new AuthorityError('PATH_NOT_ABSOLUTE', 'relative paths are not admitted; v1 authorizes absolute paths only', 'Resolve the path to an absolute path under an approved root before calling.');
+    }
+}
+/**
+ * Authorize one caller-supplied path against a grant (SEC-06).
+ *
+ * Returns the CANONICAL path, which the caller must open. Validating the original
+ * string and opening it later would leave a window in which a symlink could be
+ * swapped; resolving once and returning the result closes it.
+ * @param grant - the caller's grant.
+ * @param candidate - the caller-supplied path.
+ * @returns the canonical, authorized path.
+ * @throws AuthorityError when the path is inadmissible, missing, or outside the grant.
+ */
+export function authorizePath(grant, candidate) {
+    if (typeof candidate !== 'string' || candidate.length === 0) {
+        throw new AuthorityError('PATH_NOT_ABSOLUTE', 'a path is required', 'Supply an absolute path under an approved root.');
+    }
+    assertAdmissibleShape(candidate);
+    let canonical;
+    try {
+        // Resolves junctions and symlinks, so containment is checked against what the
+        // path actually IS rather than what it spells.
+        canonical = realpathSync.native(candidate);
+    }
+    catch {
+        throw new AuthorityError('PATH_NOT_FOUND', 'the path does not exist, so it cannot be authorized', 'Check the path, or ask the operator to add its root to the grant.');
+    }
+    for (const root of grant.approvedRoots) {
+        if (isWithin(canonical, root))
+            return canonical;
+    }
+    // The message names the grant, not the allowed roots: enumerating a caller's
+    // permitted directories would disclose the operator's configuration.
+    throw new AuthorityError('PATH_OUTSIDE_GRANT', 'the path resolves outside every root approved for this caller', 'Ask the operator to add the containing root to this grant.');
+}
+/**
+ * Authorize a tool name against a grant (SEC-03).
+ * @param grant - the caller's grant.
+ * @param toolName - the requested tool.
+ * @throws AuthorityError with `TOOL_NOT_GRANTED`.
+ */
+export function authorizeTool(grant, toolName) {
+    if (!grant.allowedTools.includes(toolName)) {
+        throw new AuthorityError('TOOL_NOT_GRANTED', `tool "${toolName}" is not granted to this caller`, 'Request access from the operator; a requested tool list does not extend a grant.');
+    }
+}
+/**
+ * Authorize an operator-bound harness executor profile (SEC-03/HLM-03).
+ * @param grant - the caller's grant.
+ * @param profile - the logical profile the recipe selected.
+ * @throws AuthorityError with `PROFILE_NOT_GRANTED`.
+ */
+export function authorizeHarnessProfile(grant, profile) {
+    if (!grant.allowedHarnessProfiles.includes(profile)) {
+        throw new AuthorityError('PROFILE_NOT_GRANTED', `harness executor profile "${profile}" is not granted to this caller`, 'The operator must authorize the profile for this client/workspace; a caller cannot select another client\'s profile.');
+    }
+}
+/**
+ * Authorize the model capabilities an executor will use (SEC-03).
+ * @param grant - the caller's grant.
+ * @param required - the input/output modalities required by the selected model.
+ * @throws AuthorityError with `CAPABILITY_NOT_GRANTED`.
+ */
+export function authorizeModelCapabilities(grant, required) {
+    const missing = required.filter(capability => !grant.modelCapabilities.includes(capability));
+    if (missing.length > 0) {
+        throw new AuthorityError('CAPABILITY_NOT_GRANTED', `model capability ${missing.map(capability => JSON.stringify(capability)).join(', ')} is not granted to this caller`, 'The grant must name the model capabilities this caller may use; a request cannot widen it.');
+    }
+}
+/**
+ * Authorize a remote destination against a grant (SEC-10).
+ *
+ * No silent local-to-remote fallback: if a destination was not explicitly
+ * approved, the call is refused rather than downgraded or upgraded.
+ * @param grant - the caller's grant.
+ * @param destination - the destination origin.
+ * @throws AuthorityError with `TOOL_NOT_GRANTED`.
+ */
+export function authorizeDestination(grant, destination) {
+    if (!grant.remoteDestinations.includes(destination)) {
+        throw new AuthorityError('TOOL_NOT_GRANTED', `destination "${destination}" is not authorized for this caller`, 'A remote destination requires explicit authorization; there is no silent fallback.');
+    }
+}
+/**
+ * Build the invocation authority for one call.
+ *
+ * The result is constructed by the host; a request body has no path to it.
+ * @param grant - the caller's grant.
+ * @param callerKind - how the host classified the caller.
+ * @returns the authority handed to the implementation.
+ */
+export function createInvocationAuthority(grant, callerKind) {
+    return {
+        grantId: grant.grantId,
+        callerKind,
+        limits: grant.limits,
+        recordingPolicy: grant.recordingPolicy,
+        resolvePath: candidate => authorizePath(grant, candidate),
+    };
+}
+//# sourceMappingURL=authority.js.map