nervur 0.3.0 → 0.6.0

package/being.mjs

@@ -0,0 +1,369 @@
+import { OPEN, STRUCTURAL, coreClass } from './blueprint.mjs';
+import { Program } from './program.mjs';
+import { MEASURE, Stamp, Tools } from './tools.mjs';
+import { Voice } from './voice.mjs';
+
+const Compartment = ({ memory, voice, address, root, classOf }) => {
+  const held = (key) => memory.read(address, key);
+  const sealed = (key) => {
+    const kind = classOf(key);
+    return kind === undefined || OPEN.includes(kind) ? undefined : Tools.derive(root, kind);
+  };
+  const put = (key, value) => {
+    const claim = { address, key, value, version: (held(key)?.version ?? 0) + 1 };
+    return memory.write({ ...claim, sig: voice.sign(Tools.canon(claim)) });
+  };
+
+  return Object.freeze({
+    classOf,
+    list: (prefix) =>
+      memory.list(address, prefix).filter((key) => memory.read(address, key)?.value !== null),
+    read: (key) => {
+      const cell = held(key);
+      if (cell === undefined || cell.value === null || classOf(key) === undefined) {
+        return undefined;
+      }
+      const secret = sealed(key);
+      return secret === undefined ? cell.value : Tools.unseal(secret, cell.value);
+    },
+    write: (key, plain) => {
+      if (classOf(key) === undefined) {
+        return undefined;
+      }
+      if (plain === undefined) {
+        return put(key, null);
+      }
+      const secret = sealed(key);
+      return put(key, secret === undefined ? plain : Tools.seal(secret, plain));
+    },
+  });
+};
+
+const scoped = (mine, program) =>
+  Object.freeze({
+    classOf: mine.classOf,
+    list: mine.list,
+    read: mine.read,
+    write: (key, plain) =>
+      key.startsWith('refs/') || key.startsWith('handles/') || program?.declares(key) !== undefined
+        ? mine.write(key, plain)
+        : undefined,
+  });
+
+const rootFor = ({ memory, voice, address }) => {
+  const cell = memory.read(address, `keyring/${Tools.address(voice.pk)}`);
+  const opened = cell === undefined ? undefined : voice.open(cell.value.wrapped);
+  return opened === undefined ? undefined : Buffer.from(opened, 'base64');
+};
+
+const Port = ({ voice, mine, modules, rights }) => {
+  const stamp = Stamp();
+  const lanes = new Map();
+  const send = async (to, op) => {
+    const turn = (lanes.get(to) ?? Promise.resolve()).then(() => {
+      const handle = mine.read(`handles/${to}`);
+      return modules.deliver(
+        Tools.envelope(handle === undefined ? voice : Voice.revive(handle.face), to, op, stamp()),
+      );
+    });
+    const settled = turn.then(
+      () => undefined,
+      () => undefined,
+    );
+    lanes.set(to, settled);
+    settled.then(() => {
+      if (lanes.get(to) === settled) {
+        lanes.delete(to);
+      }
+    });
+    return turn;
+  };
+  return Object.freeze({
+    face: (to) => {
+      const handle = mine.read(`handles/${to}`);
+      return Tools.address(handle === undefined ? voice.pk : Voice.revive(handle.face).pk);
+    },
+    mint: (to) => {
+      const minted = Voice();
+      mine.write(`handles/${to}`, { face: minted.pack() });
+      return { address: Tools.address(minted.pk), nextPkHash: minted.nextPkHash };
+    },
+    release: async (to) => {
+      const gone = await send(to, { release: {} });
+      mine.write(`handles/${to}`, undefined);
+      return gone;
+    },
+    rights,
+    send,
+  });
+};
+
+const rotates = ({ mine }, from, nextPkHash) => {
+  const claim = Tools.digest(Tools.pkOf(from));
+  const held = mine
+    .list('refs/')
+    .map((key) => ({ key, referred: mine.read(key) }))
+    .find(({ referred }) => referred?.nextPkHash === claim);
+  if (held === undefined) {
+    return undefined;
+  }
+  mine.write(`refs/${from}`, { nextPkHash, rights: held.referred.rights });
+  mine.write(held.key, undefined);
+  return from;
+};
+
+const Being = ({ voice, address, modules, registry, vouched, watch }) => {
+  const memory = modules.memory;
+  const root = rootFor({ memory, voice, address });
+  const source = memory.read(address, 'program')?.value;
+  const program = source === undefined ? undefined : Program(source);
+  const mine = Compartment({
+    memory,
+    voice,
+    address,
+    root,
+    classOf: (key) => program?.classOf(key) ?? coreClass(key),
+  });
+  const answer = (spoken) => {
+    const body = Tools.canon(spoken);
+    return body.length > MEASURE ? undefined : { body: spoken, sig: voice.sign(body) };
+  };
+  const note = (envelope, outcome) => {
+    try {
+      watch?.(
+        Object.freeze({
+          from: envelope?.from,
+          kind: envelope?.op === undefined ? undefined : Object.keys(envelope.op)[0],
+          outcome,
+          to: envelope?.to,
+        }),
+      );
+    } catch {
+      return undefined;
+    }
+  };
+
+  return Object.freeze(async (envelope, token) => {
+    let gated;
+    const spoken = await (async () => {
+      try {
+        const { from, op, seq, sig, to } = envelope;
+        const claim = Tools.canon({ from, op, seq, to });
+        const callerPk = Tools.pkOf(from);
+        const proven =
+          claim.length <= MEASURE &&
+          callerPk !== null &&
+          ((vouched !== undefined && token === vouched) || Tools.verifies(callerPk, claim, sig));
+        if (to !== address || !proven) {
+          gated = 'unproven';
+          return undefined;
+        }
+        const self = from === Tools.address(voice.pk);
+        const row = self ? undefined : mine.read(`refs/${from}`);
+        if (row !== undefined && !(vouched !== undefined && token === vouched)) {
+          if (!(seq > (row.seen ?? 0))) {
+            gated = 'replayed';
+            return undefined;
+          }
+          mine.write(`refs/${from}`, { ...row, seen: seq });
+        }
+        const rights = self ? 'SELF' : (row?.rights ?? 'STRANGER');
+        if (op?.describe !== undefined) {
+          return answer({
+            address,
+            digest: program?.digest,
+            rights,
+            sdl: program?.sdlFor(rights),
+          });
+        }
+        if (op?.introspect !== undefined) {
+          const seen = await program?.introspect(rights);
+          return seen === undefined ? undefined : answer({ introspection: seen });
+        }
+        if (op?.rotate !== undefined) {
+          const rotated = rotates({ mine }, from, op.rotate.nextPkHash);
+          return rotated === undefined ? undefined : answer({ rotated });
+        }
+        if (op?.release !== undefined) {
+          if (row === undefined) {
+            return undefined;
+          }
+          mine.write(`refs/${from}`, undefined);
+          return answer({ released: from });
+        }
+        if (op?.acceptInvite !== undefined) {
+          const offer = Tools.digest(Buffer.from(op.acceptInvite.proof, 'base64'));
+          const pending = mine.read(`refs/pending/${offer}`);
+          if (pending === undefined || pending.spent) {
+            return undefined;
+          }
+          mine.write(`refs/pending/${offer}`, { spent: true });
+          mine.write(`refs/${from}`, {
+            nextPkHash: op.acceptInvite.nextPkHash ?? null,
+            rights: pending.rights,
+            seen: seq ?? 0,
+          });
+          return answer({ referred: from, rights: pending.rights });
+        }
+        if (op?.ask === undefined || program === undefined) {
+          return undefined;
+        }
+        const asked = await program.ask({
+          context: {
+            modules: Object.freeze({ ...modules, memory: scoped(mine, program) }),
+            port: Port({ voice, mine, modules, rights }),
+            registry,
+            rights,
+          },
+          source: op.ask.source,
+          variables: op.ask.variables,
+        });
+        return asked === undefined ? undefined : answer(asked);
+      } catch {
+        return undefined;
+      }
+    })();
+    note(envelope, gated ?? (spoken === undefined ? 'mute' : 'answered'));
+    return spoken;
+  });
+};
+
+const make = ({ memory, voice, address, program }) => {
+  const root = Tools.secret();
+  const put = (key, value) => {
+    const claim = { address, key, value, version: (memory.read(address, key)?.version ?? 0) + 1 };
+    return memory.write({ ...claim, sig: voice.sign(Tools.canon(claim)) });
+  };
+  put('chain/pk', Buffer.from(voice.pk).toString('hex'));
+  put('chain/nextPkHash', voice.nextPkHash);
+  put('program', program ?? '({})');
+  put(`keyring/${Tools.address(voice.pk)}`, {
+    boxPk: Buffer.from(voice.boxPk).toString('base64'),
+    wrapped: Voice.sealTo(voice.boxPk, root.toString('base64')),
+  });
+  const written = program === undefined ? undefined : Program(program);
+  return Compartment({
+    memory,
+    voice,
+    address,
+    root,
+    classOf: (key) => written?.classOf(key) ?? coreClass(key),
+  });
+};
+
+const Registry = ({
+  memory,
+  adminMine,
+  modules,
+  modulesFor,
+  announce,
+  forget,
+  vouched,
+  attest,
+  watch,
+}) => {
+  const live = new Map();
+  const activate = (address) => {
+    if (live.has(address)) {
+      return live.get(address);
+    }
+    const held = adminMine.read(`identity/custody/${address}`);
+    const voice = held === undefined ? undefined : Voice.revive(held);
+    if (voice === undefined) {
+      return undefined;
+    }
+    const door = Being({ voice, address, modules: modulesFor(voice), vouched, watch });
+    live.set(address, door);
+    return door;
+  };
+  return Object.freeze({
+    activate,
+    active: () => live.size,
+    attest,
+    create: ({ program, refs = [], data = {}, bindings, config } = {}) => {
+      const written = program === undefined ? undefined : Program(program);
+      if (program !== undefined && written === undefined) {
+        return undefined;
+      }
+      const missing = (written?.modules ?? []).filter((one) => modules[one.module] === undefined);
+      if (missing.length > 0) {
+        return undefined;
+      }
+      const brought = written?.bindings(bindings);
+      const settings = written?.config(config);
+      if (written !== undefined && (brought === undefined || settings === undefined)) {
+        return undefined;
+      }
+      const allowed = written?.rights ?? [...STRUCTURAL, 'MEMBER'];
+      if (refs.some((ref) => !allowed.includes(ref.rights ?? 'MEMBER'))) {
+        return undefined;
+      }
+      if (refs.some((ref) => typeof ref.address !== 'string' || Tools.pkOf(ref.address) === null)) {
+        return undefined;
+      }
+      const voice = Voice();
+      const address = Tools.address(voice.pk);
+      const mine = make({ memory, voice, address, program });
+      for (const [key, value] of Object.entries(data)) {
+        if (mine.write(key, value) === undefined) {
+          forget(address);
+          return undefined;
+        }
+      }
+      if (written !== undefined) {
+        mine.write('config', settings);
+        for (const [module, bound] of Object.entries(brought)) {
+          mine.write(`bindings/${module}`, bound);
+        }
+      }
+      for (const ref of refs) {
+        mine.write(`refs/${ref.address}`, {
+          nextPkHash: ref.nextPkHash ?? null,
+          rights: ref.rights ?? 'MEMBER',
+        });
+      }
+      adminMine.write(`identity/custody/${address}`, voice.pack());
+      announce(address);
+      return address;
+    },
+    deactivate: (address) => live.delete(address),
+    upgrade: ({ address, program }) => {
+      const held = adminMine.read(`identity/custody/${address}`);
+      const voice = held === undefined ? undefined : Voice.revive(held);
+      const written = program === undefined ? undefined : Program(program);
+      if (voice === undefined || written === undefined) {
+        return undefined;
+      }
+      const orphaned = memory
+        .list(address, '')
+        .filter((key) => memory.read(address, key)?.value !== null)
+        .filter((key) => written.classOf(key) === undefined);
+      if (orphaned.length > 0) {
+        return undefined;
+      }
+      const claim = {
+        address,
+        key: 'program',
+        value: program,
+        version: (memory.read(address, 'program')?.version ?? 0) + 1,
+      };
+      if (memory.write({ ...claim, sig: voice.sign(Tools.canon(claim)) }) === undefined) {
+        return undefined;
+      }
+      live.delete(address);
+      return address;
+    },
+    destroy: (address) => {
+      if (adminMine.read(`identity/custody/${address}`) === undefined) {
+        return undefined;
+      }
+      adminMine.write(`identity/custody/${address}`, undefined);
+      live.delete(address);
+      forget(address);
+      return address;
+    },
+    stored: () => adminMine.list('identity/custody/').length,
+  });
+};
+
+export { Being, Compartment, Registry, make, rootFor };

package/blueprint.mjs

@@ -0,0 +1,281 @@
+import { Kind, buildSchema, coerceInputValue, parse, print } from 'graphql';
+import { Tools } from './tools.mjs';
+
+const STRUCTURAL = ['SELF', 'STRANGER'];
+
+const CLASSES = [
+  'bindings',
+  'chain',
+  'config',
+  'data',
+  'handles',
+  'identity',
+  'keyring',
+  'program',
+  'refs',
+];
+
+const OPEN = ['chain', 'keyring', 'program'];
+
+const CORE_ONLY = ['chain', 'identity', 'keyring', 'program'];
+
+const CORE = [
+  ['chain/', 'chain'],
+  ['keyring/', 'keyring'],
+  ['refs/', 'refs'],
+  ['handles/', 'handles'],
+  ['bindings/', 'bindings'],
+  ['identity/', 'identity'],
+  ['config', 'config'],
+  ['program', 'program'],
+];
+
+const coreClass = (key) =>
+  CORE.find(([mark]) => (mark.endsWith('/') ? key.startsWith(mark) : key === mark))?.[1];
+
+const declaredClass = (memory, key) => {
+  const held = memory[key];
+  if (held !== undefined) {
+    return held.class;
+  }
+  const under = Object.keys(memory)
+    .filter((one) => one.endsWith('/*'))
+    .find((one) => key.startsWith(one.slice(0, -1)));
+  return under === undefined ? undefined : memory[under].class;
+};
+
+const AMBIENT = [
+  'globalThis',
+  'process',
+  'require',
+  'import',
+  'eval',
+  'Function',
+  'fetch',
+  'XMLHttpRequest',
+  'WebAssembly',
+  'SharedArrayBuffer',
+  'Atomics',
+  'Buffer',
+  'crypto',
+  'Date',
+  'setTimeout',
+  'setInterval',
+  'queueMicrotask',
+];
+
+const REACHES = [
+  ['constructor', /\bconstructor\b/],
+  ['__proto__', /\b__proto__\b/],
+  ['prototype', /\bprototype\b/],
+  ['Math.random', /\bMath\s*\.\s*random\b/],
+];
+
+const FORBIDDEN = [
+  ...AMBIENT.map((name) => [name, new RegExp(`(?<![.$\\w])${name}\\b(?!\\s*:)`)]),
+  ...REACHES,
+];
+
+const RESERVED = ['eval', 'import', '__proto__', 'prototype', 'Math.random'];
+
+const SHADOWED = FORBIDDEN.map(([name]) => name).filter((name) => !RESERVED.includes(name));
+
+const RIGHTS_DIRECTIVE = 'directive @rights(is: [Rights!]!) on FIELD_DEFINITION';
+
+const DEFAULT_RIGHTS = `enum Rights { SELF MEMBER STRANGER }`;
+
+const codeOnly = (source) => {
+  const out = [];
+  const modes = [{ depth: 0, kind: 'code' }];
+  let at = 0;
+  while (at < source.length) {
+    const mode = modes[modes.length - 1];
+    const one = source[at];
+    if (mode.kind !== 'code') {
+      if (one === '\\') {
+        out.push('  ');
+        at += 2;
+      } else if (one === mode.mark) {
+        modes.pop();
+        out.push(' ');
+        at += 1;
+      } else if (mode.kind === 'template' && one === '$' && source[at + 1] === '{') {
+        modes.push({ depth: 0, kind: 'code' });
+        out.push('  ');
+        at += 2;
+      } else {
+        out.push(one === '\n' ? '\n' : ' ');
+        at += 1;
+      }
+      continue;
+    }
+    if (one === "'" || one === '"') {
+      modes.push({ kind: 'quote', mark: one });
+    } else if (one === '`') {
+      modes.push({ kind: 'template', mark: '`' });
+    } else if (one === '{') {
+      mode.depth += 1;
+    } else if (one === '}' && mode.depth === 0 && modes.length > 1) {
+      modes.pop();
+      out.push(' ');
+      at += 1;
+      continue;
+    } else if (one === '}') {
+      mode.depth -= 1;
+    }
+    out.push(one === "'" || one === '"' || one === '`' ? ' ' : one);
+    at += 1;
+  }
+  return out.join('');
+};
+
+const reads = (source) => {
+  const code = codeOnly(source);
+  return FORBIDDEN.filter(([, mark]) => mark.test(code)).map(([name]) => name);
+};
+
+const evaluated = (source) => {
+  const body = `"use strict"; return (${source});`;
+  return new Function(...SHADOWED, body)(...SHADOWED.map(() => undefined));
+};
+
+const rightsOf = (field) => {
+  const marked = field.directives?.find((one) => one.name.value === 'rights');
+  const listed = marked?.arguments?.find((one) => one.name.value === 'is');
+  return listed === undefined
+    ? undefined
+    : listed.value.values.map((one) => one.value ?? one.name?.value);
+};
+
+const resolverSources = (resolvers) =>
+  Object.keys(resolvers)
+    .sort()
+    .flatMap((type) =>
+      Object.keys(resolvers[type])
+        .sort()
+        .map((field) => `${type}.${field}=${resolvers[type][field].toString()}`),
+    );
+
+const inputCheck = (schema, typeName, given) => {
+  const type = schema.getType(typeName);
+  if (type?.getFields === undefined) {
+    return undefined;
+  }
+  let failed = false;
+  const taken = coerceInputValue(given ?? {}, type, () => {
+    failed = true;
+  });
+  return failed || taken === undefined
+    ? undefined
+    : Object.freeze(JSON.parse(JSON.stringify(taken)));
+};
+
+const Blueprint = (source) => {
+  const trespass = reads(source);
+  if (trespass.length > 0) {
+    return { trespass };
+  }
+  try {
+    const written = evaluated(source);
+    const declares = /enum\s+Rights\b/.test(written.interface) ? '' : DEFAULT_RIGHTS;
+    const sdl = [RIGHTS_DIRECTIVE, declares, written.interface].filter(Boolean).join('\n');
+    const document = parse(sdl);
+    const schema = buildSchema(sdl);
+    const rights = [
+      ...new Set([
+        ...STRUCTURAL,
+        ...(schema.getType('Rights')?.getValues() ?? []).map((one) => one.name),
+      ]),
+    ];
+
+    const admits = (typeName, fieldName, held) => {
+      const type = document.definitions.find(
+        (one) => one.kind === Kind.OBJECT_TYPE_DEFINITION && one.name.value === typeName,
+      );
+      const field = type?.fields?.find((one) => one.name.value === fieldName);
+      const allowed = field === undefined ? undefined : rightsOf(field);
+      return allowed === undefined ? true : allowed.includes(held);
+    };
+
+    const needs = written.needs ?? {};
+    const modules = needs.modules ?? [];
+    const memory = written.memory ?? {};
+    const misdeclared = Object.entries(memory).filter(
+      ([key, cell]) => !CLASSES.includes(cell?.class) || coreClass(key) !== undefined,
+    );
+    if (misdeclared.length > 0) {
+      return undefined;
+    }
+    const roots = [
+      schema.getQueryType()?.name,
+      schema.getMutationType()?.name,
+      schema.getSubscriptionType()?.name,
+    ].filter((one) => one !== undefined);
+    const undeclared = document.definitions
+      .filter((one) => one.kind === Kind.OBJECT_TYPE_DEFINITION && roots.includes(one.name.value))
+      .flatMap((one) => one.fields ?? [])
+      .filter((one) => {
+        const allowed = rightsOf(one);
+        return allowed === undefined || allowed.some((held) => !rights.includes(held));
+      });
+    if (undeclared.length > 0) {
+      return undefined;
+    }
+
+    return Object.freeze({
+      admits,
+      bindings: (given) =>
+        modules
+          .filter((one) => one.binding !== undefined)
+          .reduce((taken, one) => {
+            if (taken === undefined) {
+              return undefined;
+            }
+            const checked = inputCheck(schema, one.binding, given?.[one.module]);
+            return checked === undefined ? undefined : { ...taken, [one.module]: checked };
+          }, {}),
+      classOf: (key) => coreClass(key) ?? declaredClass(memory, key),
+      declares: (key) => declaredClass(memory, key),
+      config: (given) =>
+        needs.config === undefined ? Object.freeze({}) : inputCheck(schema, needs.config, given),
+      digest: Tools.digest(
+        Tools.canon({
+          interface: print(document),
+          memory,
+          name: written.name,
+          needs,
+          resolvers: resolverSources(written.resolvers ?? {}),
+        }),
+      ),
+      memory: Object.freeze(memory),
+      modules,
+      name: written.name,
+      resolvers: written.resolvers ?? {},
+      rights,
+      schema,
+      // The directive definition stays: pointer.mjs runs buildSchema on this output.
+      sdlFor: (held) =>
+        print({
+          ...document,
+          definitions: document.definitions
+            .map((one) =>
+              one.kind === Kind.OBJECT_TYPE_DEFINITION
+                ? {
+                    ...one,
+                    fields: one.fields.filter((field) => {
+                      const allowed = rightsOf(field);
+                      return allowed === undefined || allowed.includes(held);
+                    }),
+                  }
+                : one,
+            )
+            .filter((one) => one.kind !== Kind.OBJECT_TYPE_DEFINITION || one.fields.length > 0),
+        }),
+      trespass: [],
+    });
+  } catch {
+    return undefined;
+  }
+};
+
+export { Blueprint, CLASSES, CORE_ONLY, FORBIDDEN, OPEN, STRUCTURAL, coreClass, reads };

package/client.mjs

@@ -0,0 +1,43 @@
+import { Stamp, Tools } from './tools.mjs';
+
+const Client = ({ voice, deliver, resolve = (one) => one }) => {
+  const stamp = Stamp();
+  const lanes = new Map();
+  const send = async (to, op) => {
+    const at = resolve(to);
+    const answering = at === undefined ? null : Tools.pkOf(at);
+    if (answering === null) {
+      return undefined;
+    }
+    const turn = (lanes.get(at) ?? Promise.resolve()).then(async () => {
+      const reply = await deliver(Tools.envelope(voice, at, op, stamp()));
+      return reply?.body === undefined ||
+        !Tools.verifies(answering, Tools.canon(reply.body), reply.sig)
+        ? undefined
+        : reply;
+    });
+    const settled = turn.then(
+      () => undefined,
+      () => undefined,
+    );
+    lanes.set(at, settled);
+    settled.then(() => {
+      if (lanes.get(at) === settled) {
+        lanes.delete(at);
+      }
+    });
+    return turn;
+  };
+
+  return Object.freeze({
+    address: Tools.address(voice.pk),
+    ask: (to, source, variables) => send(to, { ask: { source, variables } }),
+    describe: (to) => send(to, { describe: {} }),
+    introspect: (to) => send(to, { introspect: {} }),
+    pk: voice.pk,
+    release: (to) => send(to, { release: {} }),
+    send,
+  });
+};
+
+export { Client };