@lanes-sh/link 0.1.0

package/src/dispatch/context.ts

@@ -0,0 +1,195 @@
+import type { AuditLogger } from '#audit';
+import type { SecretRef, SecretStore } from '#secrets';
+import { scopeSecrets } from '#secrets';
+import type { RuntimeState } from '#stores/state';
+import type { BlobStore } from '#stores/blobs';
+import { scopeBlobStore } from '#stores/blobs';
+import type {
+  ConnectionInfo,
+  Logger,
+  ProviderContext,
+  ProviderDefinition,
+  ProviderManifest,
+  ScopedStore,
+} from '#connectivity';
+import { credentialRefForConnection } from '#connectivity';
+import type { ConnectionConfig } from '#profile';
+
+/**
+ * Assembling what a provider is handed.
+ *
+ * Providers receive scoped capabilities, never raw backends. Every boundary
+ * here is enforced by construction rather than by asking providers to behave:
+ * the state namespace is applied before the provider sees the store, the blob
+ * namespace likewise, and credentials are restricted to an explicit allowlist
+ * computed from what the connection declares.
+ */
+
+/** `<provider>/<connection>` — the namespace both state and blobs are scoped to. */
+export function scopeNamespace(provider: string, connectionId: string): string {
+  return `${provider}/${connectionId}`;
+}
+
+export function createScopedStore(state: RuntimeState, namespace: string): ScopedStore {
+  return {
+    get: (key) => state.kv.get(namespace, key),
+    set: (key, value) => state.kv.set(namespace, key, value),
+    delete: (key) => state.kv.delete(namespace, key),
+    keys: () => state.kv.keys(namespace),
+
+    async getJson<T>(key: string): Promise<T | null> {
+      const raw = await state.kv.get(namespace, key);
+      if (raw === null) return null;
+      try {
+        return JSON.parse(raw) as T;
+      } catch {
+        // Stored state that will not parse is a provider bug, not a reason to
+        // fail the request; treat it as absent and let the provider rewrite it.
+        return null;
+      }
+    },
+
+    setJson: (key, value) => state.kv.set(namespace, key, JSON.stringify(value)),
+  };
+}
+
+/**
+ * Which credential refs this connection may read.
+ *
+ * A provider declares them via `credentialRefs`; if it declares nothing, the
+ * connection's own `credential_ref` is the entire allowlist. Either way the set
+ * is computed here rather than asked for at read time, so a provider cannot
+ * widen it by asking for more.
+ */
+export function resolveSecretRefs(
+  manifest: ProviderManifest,
+  connection: ConnectionConfig,
+  definition?: ProviderDefinition,
+  /**
+   * Which `app` entries this profile declares a client of its own for.
+   *
+   * Only consulted for a provider that could also authorise against a broker.
+   * Defaults to none, which is correct for every provider that declares no
+   * broker: the gate below leaves those exactly as they were.
+   */
+  ownClients: readonly string[] = [],
+): SecretRef[] {
+  const refs = new Set<SecretRef>(
+    definition?.credentialRefs?.(connection.id, connection.config ?? {}) ?? [],
+  );
+
+  if (connection.credential_ref) refs.add(connection.credential_ref);
+
+  const auth = manifest.auth;
+
+  if (auth.kind === 'oauth') {
+    // The tokens for this connection, and — for a manual registration — the
+    // shared app credentials every connection of that vendor authorises
+    // against. Nothing wider: `gmail.main` must not reach `gmail/side`.
+    refs.add(`${manifest.id}/${connection.id}`);
+    if (auth.registration === 'manual' && auth.app) {
+      // Only where this profile holds a client of its own. When the client is
+      // the broker's there is no id, secret, or registration anywhere in this
+      // store, so naming the three refs would grant reach to nothing while
+      // describing an arrangement that does not exist — and a grant list is
+      // read by people deciding what a provider can see.
+      if (!auth.broker || ownClients.includes(auth.app)) {
+        refs.add(`${auth.app}/client_id`);
+        refs.add(`${auth.app}/client_secret`);
+        refs.add(`${auth.app}/client`);
+      }
+    } else {
+      refs.add(`${manifest.id}/client`);
+    }
+  }
+
+  if (auth.kind !== 'none' && auth.kind !== 'oauth') {
+    // The connection's own credential, wherever the manifest puts it — which
+    // may be a ref shared with sibling providers of the same vendor
+    // (`icloud/ada` serves mail, calendar, and contacts). Shared across
+    // *providers* is not shared across *accounts*: this adds exactly one ref, so
+    // `icloud_mail.will` still cannot reach `icloud/sam`.
+    const ref = credentialRefForConnection(manifest, connection.id);
+    if (ref) refs.add(ref);
+  }
+
+  return [...refs];
+}
+
+export interface BuildContextOptions {
+  readonly manifest: ProviderManifest;
+  /** Present only for `local` providers. */
+  readonly definition?: ProviderDefinition | undefined;
+  readonly connection: ConnectionConfig;
+  readonly state: RuntimeState;
+  readonly credentials: SecretStore;
+  readonly storage: BlobStore;
+  readonly audit: AuditLogger;
+  readonly log: Logger;
+  readonly signal: AbortSignal;
+  /** The same closure the connector context gets. Absent for `local` providers. */
+  readonly authorize?: ((request: Request) => Promise<Request>) | undefined;
+  /** `oauth_apps` entries this profile declares. See `resolveSecretRefs`. */
+  readonly ownClients?: readonly string[] | undefined;
+}
+
+export function buildProviderContext(options: BuildContextOptions): ProviderContext {
+  const { manifest, definition, connection } = options;
+  const namespace = scopeNamespace(manifest.id, connection.id);
+
+  const info: ConnectionInfo = {
+    id: connection.id,
+    key: `${manifest.id}.${connection.id}`,
+    displayName: connection.account,
+    config: connection.config ?? {},
+  };
+
+  return {
+    connection: info,
+    state: createScopedStore(options.state, namespace),
+    storage: scopeBlobStore(options.storage, namespace),
+    credentials: scopeSecrets(
+      options.credentials,
+      resolveSecretRefs(manifest, connection, definition, options.ownClients ?? []),
+    ),
+    audit: options.audit,
+    log: options.log,
+    signal: options.signal,
+    ...(options.authorize ? { authorize: options.authorize } : {}),
+  };
+}
+
+/** A logger that prefixes provider and connection, so lines are attributable. */
+export function createProviderLogger(base: Logger, provider: string, connection: string): Logger {
+  const prefix = `[${provider}.${connection}]`;
+  return {
+    debug: (message, detail) => base.debug(`${prefix} ${message}`, detail),
+    info: (message, detail) => base.info(`${prefix} ${message}`, detail),
+    warn: (message, detail) => base.warn(`${prefix} ${message}`, detail),
+    error: (message, detail) => base.error(`${prefix} ${message}`, detail),
+  };
+}
+
+export function createConsoleLogger(level: 'debug' | 'info' | 'warn' | 'error' = 'info'): Logger {
+  const order = { debug: 0, info: 1, warn: 2, error: 3 } as const;
+  const threshold = order[level];
+
+  const emit = (
+    kind: keyof typeof order,
+    message: string,
+    detail?: Record<string, unknown>,
+  ): void => {
+    if (order[kind] < threshold) return;
+    const suffix = detail && Object.keys(detail).length > 0 ? ` ${JSON.stringify(detail)}` : '';
+    // stderr throughout: stdout belongs to the CLI's own output, and a log line
+    // interleaved into a printed token or config diff is worse than useless.
+    process.stderr.write(`${kind.padEnd(5)} ${message}${suffix}\n`);
+  };
+
+  return {
+    debug: (message, detail) => emit('debug', message, detail),
+    info: (message, detail) => emit('info', message, detail),
+    warn: (message, detail) => emit('warn', message, detail),
+    error: (message, detail) => emit('error', message, detail),
+  };
+}

package/src/dispatch/dispatch.ts

@@ -0,0 +1,350 @@
+import type { AuditDraft, AuditLogger, AuditSink, AuthorizationResult } from '#audit';
+import { keepKeys, redactAllValues } from '#audit';
+import type { Principal } from '#auth';
+import type { SecretStore } from '#secrets';
+import type { RuntimeState } from '#stores/state';
+import type { PolicyDocument } from '#policy';
+import { RateLimiter, evaluate } from '#policy';
+import type { BlobStore } from '#stores/blobs';
+import type { AnyConnector, CapabilityResult, ConnectorContext, Logger } from '#connectivity';
+import { isToolResult } from '#connectivity';
+import type { Config } from '#profile';
+import { buildProviderContext, createProviderLogger } from './context.ts';
+import { stageAttachment, type StagedAttachment, type StageRequest } from './staging.ts';
+import type { ProviderRegistry } from '#registry';
+
+/**
+ * The dispatch path.
+ *
+ * Every invocation goes through here in one fixed order — authenticate,
+ * resolve, authorize, rate-limit, dispatch, audit — with no way around it.
+ * The ordering is not stylistic: policy is evaluated before a provider is
+ * reached, so a provider never sees a request it was not authorised to serve,
+ * and authorization is never something provider code could get wrong.
+ *
+ * Exactly one audit event is written per invocation, on every path including
+ * denials. That is enforced structurally by `finally` rather than by
+ * remembering to call it at each return.
+ */
+
+export interface DispatchDeps {
+  readonly config: Config;
+  readonly registry: ProviderRegistry;
+  /**
+   * Resolve the connector for a provider. Supplied by the caller so core does
+   * not import connector implementations, keeping the dependency direction
+   * intact: infrastructure -> sdk -> core -> connectors.
+   */
+  readonly connectorFor: (providerId: string, connectionId: string) => AnyConnector | undefined;
+  /** Attach whatever the manifest's auth kind requires to an outbound request. */
+  readonly authorizeRequest?: (
+    providerId: string,
+    connectionId: string,
+    request: Request,
+  ) => Promise<Request>;
+  readonly policy: PolicyDocument;
+  /** Optional instance floor. Empty in M1; composition is tighten-only. */
+  readonly floor?: PolicyDocument;
+  readonly state: RuntimeState;
+  /**
+   * Where events go. Separate from `state` because the log is no longer in
+   * it — and because dispatch only ever writes, so taking the sink rather than
+   * the whole store means this path structurally cannot read the log back.
+   */
+  readonly audit: AuditSink;
+  readonly credentials: SecretStore;
+  readonly storage: BlobStore;
+  readonly limiter: RateLimiter;
+  readonly log: Logger;
+  readonly now?: () => number;
+}
+
+export interface DispatchRequest {
+  readonly principal: Principal;
+  /** Fully qualified, e.g. `example.echo`. */
+  readonly capabilityId: string;
+  /** Fully qualified, e.g. `example.a`. */
+  readonly connectionKey: string;
+  readonly arguments: Readonly<Record<string, unknown>>;
+  /** Self-reported by the client. Observability only — never authorization. */
+  readonly clientLabel?: string | undefined;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * `result` is a union because a capability is not necessarily a tool — a
+ * resource read, a resource listing, and a prompt render come back through this
+ * same path, deliberately, so that all four are policy-checked and audited
+ * identically. Narrow it with the `is*Result` guards from the provider SDK.
+ */
+export type DispatchOutcome =
+  | { readonly ok: true; readonly result: CapabilityResult }
+  | { readonly ok: false; readonly authorization: AuthorizationResult; readonly message: string };
+
+export class Dispatcher {
+  readonly #deps: DispatchDeps;
+  readonly #now: () => number;
+
+  constructor(deps: DispatchDeps) {
+    this.#deps = deps;
+    this.#now = deps.now ?? Date.now;
+  }
+
+  /**
+   * Take bytes for a later call to name, and record that it happened.
+   *
+   * The body is in `staging.ts`; what belongs here is that it goes through the
+   * dispatcher at all. Staging is a write against one account — it puts the
+   * operator's file inside the endpoint, where a later send can post it outward
+   * — so it is audited on the same path as the send rather than beside it.
+   */
+  async stageAttachment(request: StageRequest): Promise<StagedAttachment> {
+    return stageAttachment(
+      {
+        storage: this.#deps.storage,
+        audit: this.#deps.audit,
+        profile: this.#deps.config.instance.profile,
+        now: this.#now,
+      },
+      request,
+    );
+  }
+
+  /**
+   * Record an attempt that was refused before dispatch.
+   *
+   * Policy-filtered discovery means a capability the caller may not use is
+   * never advertised, so a call naming it is rejected by the protocol layer
+   * and never reaches `invoke`. Nothing was invoked — but an agent probing for
+   * tools it does not have is precisely the behaviour the log exists to
+   * capture, and without this it would leave no trace at all.
+   */
+  async recordRefusal(request: {
+    readonly principal: Principal;
+    readonly capabilityId: string;
+    readonly connectionKey?: string | undefined;
+    readonly clientLabel?: string | undefined;
+  }): Promise<void> {
+    const [providerId = ''] = splitKey(request.capabilityId);
+
+    await this.#deps.audit.append({
+      profile: this.#deps.config.instance.profile,
+      principal: request.principal.id,
+      ...(request.clientLabel ? { clientLabel: request.clientLabel } : {}),
+      provider: providerId,
+      ...(request.connectionKey ? { connection: request.connectionKey } : {}),
+      capability: request.capabilityId,
+      arguments: {},
+      authorization: 'denied_default',
+      status: 'not_invoked',
+      durationMs: 0,
+      error: {
+        kind: 'not_available',
+        message: 'capability is not advertised to this principal',
+      },
+    });
+  }
+
+  async invoke(request: DispatchRequest): Promise<DispatchOutcome> {
+    const started = this.#now();
+    const { config, registry, state, audit } = this.#deps;
+    const [providerId = ''] = splitKey(request.capabilityId);
+
+    const annotations: Record<string, unknown> = {};
+    let authorization: AuthorizationResult = 'denied_default';
+    let status: AuditDraft['status'] = 'not_invoked';
+    let auditArguments: Record<string, unknown> = redactAllValues(request.arguments);
+    let error: { kind: string; message: string } | undefined;
+    let outcome: DispatchOutcome = {
+      ok: false,
+      authorization: 'denied_default',
+      message: 'not evaluated',
+    };
+
+    try {
+      const registered = registry.findCapability(request.capabilityId);
+      if (!registered) {
+        error = { kind: 'unknown_capability', message: `No such capability: ${request.capabilityId}` };
+        // An unknown capability is reported as a plain denial rather than
+        // "no such tool", so probing cannot distinguish a capability that does
+        // not exist from one this profile may not use.
+        return (outcome = deny('denied_default', `Capability ${request.capabilityId} is not available`));
+      }
+
+      const entry = registry.get(providerId)!;
+
+      // Apply redaction now that we know which capability this is, so a denial
+      // is logged with the same redaction an allowed call would get.
+      //
+      // Local capabilities carry their own rule. Discovered ones cannot: we did
+      // not author them and cannot know what is sensitive, so the default
+      // withholds every value and a manifest opts specific keys back in.
+      const declaredKeys = entry.manifest.redact?.[registered.capability?.name ?? registered.discovered?.name ?? ''];
+      const redact =
+        registered.capability?.redact ?? (declaredKeys ? keepKeys(...declaredKeys) : undefined);
+
+      auditArguments = (redact ?? redactAllValues)(request.arguments);
+
+      const declared = config.connections.find(
+        (connection) => `${connection.provider}.${connection.id}` === request.connectionKey,
+      );
+      if (!declared || declared.provider !== providerId) {
+        return (outcome = deny(
+          'denied_default',
+          `Connection ${request.connectionKey} is not available`,
+        ));
+      }
+
+      const decision = evaluate(
+        {
+          principal: request.principal.id,
+          capability: request.capabilityId,
+          connection: request.connectionKey,
+        },
+        this.#deps.policy,
+        this.#deps.floor,
+      );
+
+      authorization = decision.reason;
+      if (!decision.allowed) {
+        return (outcome = deny(
+          decision.reason,
+          `Not permitted: ${request.capabilityId} on ${request.connectionKey}`,
+        ));
+      }
+
+      // Two buckets: one for the endpoint as a whole, one per connection to
+      // protect a vendor's quota from an agent stuck in a retry loop.
+      const perProfile = this.#deps.limiter.take(
+        `profile:${config.instance.profile}`,
+        config.limits.requests_per_minute,
+      );
+      const perConnection = perProfile.allowed
+        ? this.#deps.limiter.take(
+            `connection:${request.connectionKey}`,
+            config.limits.upstream_calls_per_minute,
+          )
+        : perProfile;
+
+      if (!perProfile.allowed || !perConnection.allowed) {
+        const retryAfterMs = Math.max(perProfile.retryAfterMs, perConnection.retryAfterMs);
+        authorization = 'denied_rate_limited';
+        return (outcome = deny(
+          'denied_rate_limited',
+          `Rate limit exceeded. Retry in ${Math.ceil(retryAfterMs / 1000)}s.`,
+        ));
+      }
+
+      const record = await state.connections.get(declared.provider, declared.id);
+      if (record && record.status !== 'active') {
+        authorization = 'denied_connection_unauthorized';
+        return (outcome = deny(
+          'denied_connection_unauthorized',
+          record.status === 'unauthorized'
+            ? `Connection ${request.connectionKey} has no valid credential. Run: lanes link connect ${request.connectionKey}`
+            : `Connection ${request.connectionKey} is disabled.`,
+        ));
+      }
+
+      const auditLogger: AuditLogger = {
+        annotate(detail) {
+          Object.assign(annotations, detail);
+        },
+      };
+
+      // One closure, handed to both contexts. A provider that authors a
+      // capability its transport cannot express still calls the vendor through
+      // the same authorizer the transport would have used.
+      const authorize = (outbound: Request): Promise<Request> =>
+        this.#deps.authorizeRequest
+          ? this.#deps.authorizeRequest(providerId, declared.id, outbound)
+          : Promise.resolve(outbound);
+
+      const providerContext = buildProviderContext({
+        manifest: entry.manifest,
+        definition: entry.definition,
+        connection: declared,
+        state,
+        credentials: this.#deps.credentials,
+        storage: this.#deps.storage,
+        audit: auditLogger,
+        log: createProviderLogger(this.#deps.log, providerId, declared.id),
+        signal: request.signal ?? new AbortController().signal,
+        // Which vendors this profile registered a client of its own for. A
+        // provider that could be brokered but is not reads its client from the
+        // store, so it has to be able to.
+        ownClients: Object.keys(this.#deps.config.oauth_apps),
+        ...(entry.manifest.connector.kind === 'local' ? {} : { authorize }),
+      });
+
+      const connector = this.#deps.connectorFor(providerId, declared.id);
+      if (!connector) {
+        status = 'error';
+        error = { kind: 'no_connector', message: `No connector for provider ${providerId}` };
+        return (outcome = {
+          ok: false,
+          authorization: 'allowed',
+          message: `Provider ${providerId} has no usable connector.`,
+        });
+      }
+
+      const connectorContext: ConnectorContext = {
+        manifest: entry.manifest,
+        provider: providerContext,
+        authorize,
+      };
+
+      // The connector owns argument validation: a local provider validates
+      // against its Zod schema, a proxied one against the upstream JSON Schema
+      // the MCP layer already enforced at registration.
+      const target = registered.discovered ?? {
+        name: registered.capability!.name,
+        description: registered.capability!.description,
+        inputSchema: {},
+      };
+
+      const result = await connector.invoke(target, request.arguments, connectorContext);
+      // Only a tool can report a soft failure. A resource or a prompt that
+      // cannot produce its answer throws, and lands in the catch below.
+      status = isToolResult(result) && result.isError ? 'error' : 'ok';
+      return (outcome = { ok: true, result });
+    } catch (caught) {
+      status = 'error';
+      error = { kind: 'provider_error', message: (caught as Error).message };
+      return (outcome = {
+        ok: false,
+        authorization,
+        message: `${request.capabilityId} failed: ${(caught as Error).message}`,
+      });
+    } finally {
+      // One event per invocation, on every path. An audit log that records
+      // only successes cannot answer "what did this agent try to do", which is
+      // the question worth asking.
+      await audit.append({
+        profile: config.instance.profile,
+        principal: request.principal.id,
+        ...(request.clientLabel ? { clientLabel: request.clientLabel } : {}),
+        provider: providerId,
+        connection: request.connectionKey,
+        capability: request.capabilityId,
+        arguments:
+          Object.keys(annotations).length > 0
+            ? { ...auditArguments, _annotations: annotations }
+            : auditArguments,
+        authorization: outcome.ok ? 'allowed' : authorization,
+        status,
+        durationMs: this.#now() - started,
+        ...(error ? { error } : {}),
+      });
+    }
+  }
+}
+
+function deny(authorization: AuthorizationResult, message: string): DispatchOutcome {
+  return { ok: false, authorization, message };
+}
+
+function splitKey(key: string): [string, string] {
+  const index = key.indexOf('.');
+  return index === -1 ? [key, ''] : [key.slice(0, index), key.slice(index + 1)];
+}

package/src/dispatch/index.ts

@@ -0,0 +1,32 @@
+/**
+ * The invocation path — the one sequence every call runs, with no way around
+ * it:
+ *
+ *   policy → limits → provider → audit
+ *
+ * The ordering is not stylistic. Policy is evaluated *before* a provider is
+ * reached, so a provider never sees a request it was not authorised to serve
+ * and authorization is never something provider code could get wrong. Exactly
+ * one audit event is written per invocation, by a `finally` rather than by
+ * remembering to call it at each return.
+ *
+ * `context.ts` is what a provider is handed: scoped state, scoped blobs, an
+ * allowlist of credential refs, and a logger. Never a raw backend.
+ */
+
+export {
+  buildProviderContext,
+  createConsoleLogger,
+  createProviderLogger,
+  createScopedStore,
+  resolveSecretRefs,
+  scopeNamespace,
+  type BuildContextOptions,
+} from './context.ts';
+
+export {
+  Dispatcher,
+  type DispatchDeps,
+  type DispatchOutcome,
+  type DispatchRequest,
+} from './dispatch.ts';

package/src/dispatch/staging.ts

@@ -0,0 +1,102 @@
+import { createHash } from 'node:crypto';
+import type { AuditSink } from '#audit';
+import type { Principal } from '#auth';
+import { newHandle, putStaged, sweepStaged, STAGED_TTL_MS } from '#connectivity/mail';
+import type { BlobStore } from '#stores/blobs';
+import { scopeBlobStore } from '#stores/blobs';
+import { scopeNamespace } from './context.ts';
+
+/**
+ * Taking bytes now for a call to name later.
+ *
+ * In dispatch rather than in the transport that receives the upload, for two
+ * reasons. The dependency direction is one: `server` may not reach a store, and
+ * should not — how blobs are namespaced is not something a component that speaks
+ * HTTP has any business knowing. The audit log is the other, and the better one.
+ * Staging is a write against one account: it puts the operator's file *inside*
+ * the endpoint, where a later send can post it outward. That belongs in the same
+ * log as the send, and this is the only place that writes it.
+ *
+ * Beside `dispatch.ts` rather than in it because it shares nothing with `invoke`
+ * but the deps — no policy evaluation, no rate limit, no connector — and that
+ * file was at the size budget, which is the budget doing its job.
+ */
+
+export interface StageRequest {
+  readonly principal: Principal;
+  readonly providerId: string;
+  readonly connectionId: string;
+  readonly bytes: Uint8Array;
+  readonly filename: string;
+  readonly contentType: string;
+  readonly clientLabel?: string | undefined;
+}
+
+export interface StagedAttachment {
+  readonly handle: string;
+  readonly sha256: string;
+  readonly expiresAt: number;
+}
+
+export async function stageAttachment(
+  deps: {
+    readonly storage: BlobStore;
+    readonly audit: AuditSink;
+    readonly profile: string;
+    readonly now: () => number;
+  },
+  request: StageRequest,
+): Promise<StagedAttachment> {
+  // Namespaced per provider and connection, exactly as `buildProviderContext`
+  // scopes the store it hands a provider — which is what makes the handle
+  // resolvable from that connection and from no other.
+  const storage = scopeBlobStore(
+    deps.storage,
+    scopeNamespace(request.providerId, request.connectionId),
+  );
+
+  // Swept before writing: staging is the only thing that creates this garbage,
+  // and there is no scheduler in this process, so the moment someone stages is
+  // both the cheapest and the most reliable time to clear the last batch. A
+  // failure to sweep must not fail the upload — the worst case is a stale blob
+  // that the next sweep catches.
+  await sweepStaged(storage).catch(() => 0);
+
+  const handle = newHandle();
+  const sha256 = createHash('sha256').update(request.bytes).digest('hex');
+  const expiresAt = deps.now() + STAGED_TTL_MS;
+
+  await putStaged(storage, {
+    handle,
+    bytes: request.bytes,
+    metadata: {
+      filename: request.filename,
+      content_type: request.contentType,
+      sha256,
+      expires_at: expiresAt,
+    },
+  });
+
+  await deps.audit.append({
+    profile: deps.profile,
+    principal: request.principal.id,
+    ...(request.clientLabel ? { clientLabel: request.clientLabel } : {}),
+    provider: request.providerId,
+    connection: `${request.providerId}.${request.connectionId}`,
+    capability: 'attachments.stage',
+    // Identifiers, not content — the same rule the send path follows. The
+    // filename and digest are what make "which file entered the endpoint" an
+    // answerable question; the bytes are the thing being withheld.
+    arguments: {
+      filename: request.filename,
+      bytes: request.bytes.byteLength,
+      content_type: request.contentType,
+      sha256,
+    },
+    authorization: 'allowed',
+    status: 'ok',
+    durationMs: 0,
+  });
+
+  return { handle, sha256, expiresAt };
+}