Build capability introduction framework

[grypez]

Overview

Dual to the notion of capability revocation is that of introduction, the convention by which a vat receives real, useful authority.

MetaMask has endowment factories which produce RPC-gated attenuations of the root MM-managed authorities (sign message, for example). The attenuations include well-known caveats, allowing the engine to restrict API invocations by both the state of a controller and the arguments of the invocation.

@endo/patterns offers an argument-only version of attenuation called narrowing via its API. Given the ocap-kernel already short-circuits cross-vat delegation chains directly to the resolving exo, this presents a unique opportunity to apply object capability principles to arbitrary kernel-managed authorities. In short, we can construct useful authority in an isolated vat, and offer a kernel.narrow operator that intersects a capability's callable interface with a new interface guard.

const readable = makeRead('~/.ocap/files/*');

async function getFile(request, path: string) {
  return kernel.narrow(
    'File',
    read,
    { read: M.call(M.path(`~/.ocap/files/${path}`)) };
}

Leaving alone that M.path does not exist, this is otherwise a straightforward motivating example. The competing, endo-native approach for narrowing is so long that I'm posting it in a comment below.

Why Kernel Level is Right

We can reuse the same routine to introduce narrowed endowments, and still keep a record of what subpaths are available where. For a subgraph kernel-internal vats which have verifiable isolation, we can track exactly which slices of authority are available to each routine. By this method, we err on the side of caution, and push onto user-code the responsibility for registering with the kernel that an exported capability has strictly less authority than the import it narrows.

Implementation suggestion

The kernel.narrow operator produces a proxy kref that only the kernel knows about. A straightforward, if inelegant, implementation of pattern intersection is available via the M.and operator. As a compelling detail of patterns' serializability, the ocap-kernel can maintain a registry of the API interface of a kref, allowing it to reject invalid invocations without even pinging the home vat. In case of a virtual object reference to a vat which is not currently live, this allows the kernel to reject an invalid invocation without revivifying the vat (or its supporting subcluster).

Bonus Algebra

Given exported objects which are kernel narrowings of the same base object (including transitively), the kernel has all of the information necessary to construct the accessible section of the base object. If an endowment carries mutual exclusion invariants (if set('x', val) exists then set('y', val) is forbidden), the kernel is in a position to enforce such rules at the authority root instead of relying upon careful use at the call sites and the inevitable TOCTOU races between those sites.

Extension opportunities

In mirror of MetaMask's rpc-engine, we can do stateful attenuation via a DSL of well-known caveats (await E.get(cap, key) matches <pattern>). We could alternatively take a monadic approach, where the guard matches against both the invocation arguments and the state-presented-as-arguments. I don't think we benefit much from monadification, but it is an interesting option to keep in mind.

[grypez]

Narrowing an exo's interface guard while presenting the faithful intersection, endo-natively

Motivation

Given a capability (remotable exo) with a partially-known interface guard, we
often want to hand out an attenuated slice of it — same methods, but with
tighter argument constraints. E.g. an fsRead with

M.interface('FileSystemReader', {
  exists: M.call(M.string()).returns(M.boolean()),
  read: M.call(M.string()).returns(M.remotable()),
});

narrowed so callers may only touch paths under ~/.ocap/user-files/.

Assume a regexp matcher (cf. #3079) M.regex(/…/u) that is a subtype of
string, so M.and(M.string(), M.regex(re)) ~ M.regex(re).

The naive wrapper and its flaw

The obvious approach is to wrap the capability in a new exo that forwards to it
under a stricter, freshly-asserted interface guard:

import { M } from '@endo/patterns';
import { makeExo } from '@endo/exo';

const pathInDir = dirPath => {
  const prefix = dirPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  const re = new RegExp(`^${prefix}(?!.*(?:^|/)\\.\\.(?:/|$))`, 'u');
  return M.and(M.string(), M.regex(re));
};

const narrowFsRead = (fsRead, dirPath) => {
  const path = pathInDir(dirPath);
  const NarrowedI = M.interface('NarrowedFileSystemReader', {
    exists: M.call(path).returns(M.boolean()),
    read: M.call(path).returns(M.remotable()),
  });
  return makeExo('NarrowedFileSystemReader', NarrowedI, {
    exists(p) { return fsRead.exists(p); },
    read(p) { return fsRead.read(p); },
  });
};

This is safe — authority is never widened; if fsRead internally permits
only *.ts, a disallowed call still gets rejected by fsRead's own guard on
delegation. But the presented guard is a fresh assertion, unrelated to what
the underlying capability actually enforces. So the slice's advertised
interface (via __getInterfaceGuard__) can be wider than reality: it claims
read('~/.ocap/user-files/foo.png') is callable when the underlying *.ts
constraint will reject it. The intersection information is lost through
composition, even though neither capability misrepresented its own surface.

The fix: present the meet (intersection) of the two guards

M.and(oldGuard, newGuard) is the right instinct but can't be applied to
method guards directly — an interface holds method guards
(M.call(...).returns(...)), while M.and(...) yields a matcher, which
M.interface rejects (MethodGuardShape won't match). So we meet one level
down: intersect each argument matcher, each optional/rest matcher, and the
return matcher, then reconstruct a valid method guard.

Introspection APIs that make this possible:

• @endo/exo → GET_INTERFACE_GUARD (the '__getInterfaceGuard__' meta-method)
• @endo/patterns → getInterfaceGuardPayload, getMethodGuardPayload

import {
  M,
  getInterfaceGuardPayload,
  getMethodGuardPayload,
} from '@endo/patterns';
import { makeExo, GET_INTERFACE_GUARD } from '@endo/exo';
import { Fail } from '@endo/errors';

const meet = (a, b) =>
  a === undefined ? b : b === undefined ? a : M.and(a, b);

// Positional meet; missing positions are the top element M.any().
const zipMeet = (as = [], bs = []) => {
  const n = Math.max(as.length, bs.length);
  return harden(
    Array.from({ length: n }, (_, i) => meet(as[i] ?? M.any(), bs[i] ?? M.any())),
  );
};

// Faithful meet of two method guards for the SAME method.
const meetMethodGuards = (parentMG, narrowMG) => {
  const p = getMethodGuardPayload(parentMG);
  const n = getMethodGuardPayload(narrowMG);
  p.callKind === n.callKind ||
    Fail`cannot intersect ${p.callKind} with ${n.callKind} method guard`;
  const make = p.callKind === 'sync' ? M.call : M.callWhen;
  return make(...zipMeet(p.argGuards, n.argGuards))
    .optional(...zipMeet(p.optionalArgGuards, n.optionalArgGuards))
    .rest(meet(p.restArgGuard, n.restArgGuard))
    .returns(meet(p.returnGuard, n.returnGuard));
};

An attenuator that (a) exposes only read/exists even if the source has more
methods, and (b) presents the true intersection guard:

const pathInDir = dirPath => {
  const prefix = dirPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  const re = new RegExp(`^${prefix}(?!.*(?:^|/)\\.\\.(?:/|$))`, 'u');
  return M.and(M.string(), M.regex(re));
};

const getPresentedGuard = cap => {
  const getter = cap[GET_INTERFACE_GUARD];
  return typeof getter === 'function' ? getter.call(cap) : undefined;
};

const narrowReader = (reader, dirPath) => {
  const path = pathInDir(dirPath);

  // Our contribution. Returns left at M.any() so the meet on the return
  // matcher reduces to whatever the parent already guarantees (variance:
  // the parent GUARANTEES its return; presenting anything narrower would be
  // an unfaithful claim and could reject values the parent legitimately
  // produces). Only tighten returns if you actually post-process the result.
  const narrowing = {
    exists: M.call(path).returns(M.any()),
    read: M.call(path).returns(M.any()),
  };

  const parentIG = getPresentedGuard(reader);
  const parentMGs = parentIG ? getInterfaceGuardPayload(parentIG).methodGuards : {};

  const methodGuards = harden(
    Object.fromEntries(
      ['exists', 'read'].map(name => {
        const narrowMG = narrowing[name];
        const parentMG = parentMGs[name];
        // No parent guard (plain unguarded remotable) => its true surface is
        // "anything", so the meet is just our narrowing. Still faithful.
        return [name, parentMG ? meetMethodGuards(parentMG, narrowMG) : narrowMG];
      }),
    ),
  );

  const NarrowedI = M.interface('NarrowedReader', methodGuards);

  return makeExo('NarrowedReader', NarrowedI, {
    exists(p) { return reader.exists(p); },
    read(p) { return reader.read(p); },
  });
};

Now slice[GET_INTERFACE_GUARD]().payload.methodGuards.read reports the arg
matcher as the genuine intersection, e.g.

M.and(M.and(M.string(), M.regex(/…inside dir…/)),
      M.and(M.string(), M.regex(/\.ts$/)))

No information is lost through composition, and it composes further:
re-narrowing a narrowed reader reads the already-intersected guard and meets
again, so the presented surface only ever shrinks.

Correctness notes

• Argument variance: a caller must satisfy both guards, so meeting arg
  matchers (fewer accepted inputs) is a true attenuation.
• Return variance: the parent guarantees a value matching its own
  returnGuard; that is what's faithful to present. Leave the narrow return at
  M.any() unless you post-process.
• callKind must match — a sync (M.call) guard can't be intersected
  with an async (M.callWhen) one; the Fail makes that explicit. (This is
  also where local-vs-remote forwarding surfaces: a remote reader would be
  forwarded with E() and both sides should be async.)
• Arity mismatch is handled by padding with M.any() (top), the correct
  lattice meet when one guard doesn't constrain a position. Fail instead if
  you want stricter composition.

Open question

Is there appetite for a first-class helper in @endo/patterns /@endo/exo
(e.g. M.and over interface/method guards, or a meetInterfaceGuards
utility + an attenuate(cap, interfaceGuard, methodNames) helper) so
attenuation faithfully presents the intersection rather than a fresh, possibly
over-wide assertion?
``

const read = makeRead('~/.ocap/files/*');

async function getFile(request, path: string) {
  const iface = await E(request)[GET_INTERFACE_GUARD]();
  
  return makeExo(
    'File',
    readFile,
    { read: M.and(iface.read), M.matches(`~/.ocap/files/${path}`) },
  );
}