@mcpherson-ai/observa-local-node 0.1.3

package/sdk/contracts/entry-boundary.mjs

@@ -0,0 +1,417 @@
+// THE PUBLIC ENTRY BOUNDARY. One mechanism, installed over the declared public
+// surface, holding one invariant:
+//
+//     NO PUBLIC H1 ENTRY POINT MAY EXECUTE CALLER-CONTROLLED ACCESSOR,
+//     DESTRUCTURING OR COERCION CODE BEFORE THE CLOSED REFUSAL BOUNDARY.
+//
+// WHY THIS FILE EXISTS RATHER THAN THIRTY PATCHES.
+//
+// Round 12B closed six entry points that let a raw `TypeError` escape, wrapped
+// them in `refuseOnRawThrow`, and pinned seven hand-picked sites with a test
+// named for a universal property. Independent review #1 then found roughly
+// THIRTY public entry points with the same shape, and the reason is structural
+// rather than clerical: the seam is the PARAMETER LIST.
+//
+//     adoptAuthorityBinding({ tenantLocalId, boundIntentId, authorityBindingId } = {})
+//
+// Destructuring in a parameter list runs `[[Get]]` on the caller's object
+// BEFORE the first statement of the function body — so before any guard, any
+// snapshot, any `refuseOnRawThrow`. A getter runs there. A Proxy `get` trap runs
+// there. `...rest` runs `ownKeys` there. A revoked Proxy throws there. The
+// escaping error carries THE CALLER'S OWN MESSAGE TEXT, which is the leak
+// `errors.mjs` opens by forbidding — a probe put a subject-identifying string in
+// a getter's `TypeError` and read it back out of a public method.
+//
+// No amount of guarding INSIDE the body can close a seam that fires before the
+// body. The only fix that generalizes is to stop the body from ever seeing the
+// caller's object: materialize the argument record at the boundary, and hand the
+// body a frozen, null-prototype, data-only clone. Then the existing
+// destructuring in every method is safe by construction, because there is
+// nothing left to trap.
+//
+// TWO LEVERS, BOTH MECHANICAL:
+//
+//   `entryRecord`      materializes ONE argument record inside a closed refusal
+//                      boundary. Accessors are REFUSED, never invoked; symbol
+//                      keys, non-plain prototypes, arrays and strings are
+//                      refused; no value is coerced.
+//
+//   `entryArray`       the same lever for the ARRAY carrier. Added by review #1
+//                      (H1R-01/02/05), which found the record half of this
+//                      boundary complete and the array half missing entirely:
+//                      three public exports validated an array with
+//                      `Array.isArray` and then CONSUMED it through `for...of`
+//                      or `.length`/`[i]`, both of which a caller controls.
+//
+//   `sealEntryPoints`  installs `entryRecord` over a declared method table, in
+//                      one call, so a method cannot be left out by forgetting
+//                      to edit it. The table is compared against the contract's
+//                      own method list by test, so a method added to the surface
+//                      without a boundary code fails rather than shipping bare.
+//
+// WHAT `entryRecord` DELIBERATELY DOES NOT DO. It is SHALLOW. Members keep their
+// identity — a function stays a function, a nested record stays a reference —
+// because the entry points that take functions (`registerDomainProfile`, and
+// every `clock`) could not otherwise be sealed at all, and because each member
+// already has its own validator that snapshots to the depth that member needs.
+// The boundary's job is to make sure the BODY never touches caller-controlled
+// STRUCTURE; the validators' job is to make sure each MEMBER is what it claims.
+// ROUND-2 REVIEW #1, H1R2-01 — WRAPPING THE WALK WAS NOT WRAPPING THE TRAPS.
+//
+// Every `Reflect.ownKeys`, `getOwnPropertyDescriptor` and `getPrototypeOf`
+// below EXECUTES CALLER CODE. Round 12B put the whole walk inside
+// `refuseOnRawThrow`, which closed the raw-`TypeError` half; it did not close
+// the other half, because a trap that raised a publicly constructed
+// `SdkContractError` was rethrown unchanged with the caller's own text in it.
+//
+// Each trap-invoking primitive now runs inside `runUntrusted`, which is the
+// smallest dynamic extent that is genuinely foreign code. Contract refusals in
+// the loop body sit OUTSIDE those regions and keep their own codes; anything a
+// trap raises is re-coded. `errors.mjs` states the provenance model.
+import { types as nodeTypes } from "node:util";
+import { refuse, runUntrusted } from "./errors.mjs";
+import { stableStringHas } from "./stable-primitives.mjs";
+
+// The installer makes a security boundary durable.  Capture the ordinary
+// object operations it needs so a later ambient replacement cannot turn the
+// commit phase back into a caller-controlled dispatch point.  A Proxy cannot
+// offer transactional property definition, so it is rejected before any
+// target inspection or mutation.
+const isProxy = nodeTypes.isProxy;
+const objectDefineProperty = Object.defineProperty;
+const objectGetOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
+const objectKeys = Object.keys;
+const objectFreeze = Object.freeze;
+const reflectApply = Reflect.apply;
+const arrayIsArray = Array.isArray;
+const NativeArray = Array;
+const functionToString = Function.prototype.toString;
+
+// A shared frozen empty record, so `undefined` keeps meaning "no arguments" —
+// the behaviour the `= {}` parameter defaults used to provide, without the
+// default-parameter evaluation those defaults performed.
+const NO_ARGUMENTS = Object.freeze(Object.create(null));
+
+// THE STRUCTURAL CODE POLICY, stated once for both levers.
+//
+// Three facts are decided identically wherever structure is inspected — "the
+// prototype is not plain", "an unsafe or non-addressable key was found", "an
+// accessor was found where a data property was required" — and by default they
+// carry `canonical.mjs`'s own three codes, so one condition has one name across
+// the whole SDK.
+//
+// A boundary that already publishes its OWN closed code for those facts passes
+// `structuralCode` and gets it. That is not drift: it is the rule
+// `text-safety.mjs` states for the same situation — "this append is malformed",
+// "this history is malformed" and "this envelope is malformed" are different
+// facts about different boundaries and each keeps its own code, but they can
+// never disagree about WHICH value is unsafe, because one implementation
+// decides. `projection.mjs` has published `PROJECTION_EVENT_INVALID` for an
+// accessor on an event since round 10 and keeps it; the node's sealed methods
+// have published `VALUE_ACCESSOR_REFUSED` and keep that.
+//
+// IT IS A PLAIN STRING PARAMETER, NOT AN OPTIONS RECORD, and the reason is this
+// file's own first sentence. The first draft wrote it as
+// `{ structuralCode = null } = {}` — DESTRUCTURING IN A PARAMETER LIST, the
+// exact seam `entryRecord` exists to close, reintroduced into the boundary
+// itself. `entry-position-sweep.test.mjs` caught it on its first run:
+// `entryRecord(x, code, null)` raised a raw TypeError, and a Proxy third
+// argument leaked the caller's own message text straight back out. A scalar has
+// no structure to trap.
+function structuralCodes(structuralCode) {
+  return {
+    notPlain: structuralCode ?? "VALUE_NOT_PLAIN",
+    unsafeKey: structuralCode ?? "VALUE_UNSAFE_KEY",
+    accessor: structuralCode ?? "VALUE_ACCESSOR_REFUSED",
+    hole: structuralCode ?? "VALUE_NOT_JSON_COMPATIBLE",
+  };
+}
+
+// Materialize a caller-supplied argument record.
+//
+// Null-prototype, so a field lookup can never reach `Object.prototype` and
+// answer with an inherited function — the shape that turns `record[name]` into
+// an execution seam. Frozen, so nothing downstream can write back into it.
+export function entryRecord(rawArguments, code, structuralCode) {
+  const CODES = structuralCodes(structuralCode);
+  if (rawArguments === undefined) return NO_ARGUMENTS;
+    // A string is an object-ish thing with indexed own properties, and reading
+    // one as a record silently yields a per-character map rather than failing.
+  if (typeof rawArguments === "string") refuse(code);
+  if (rawArguments === null || typeof rawArguments !== "object" ||
+      runUntrusted(code, () => arrayIsArray(rawArguments))) {
+    refuse(code);
+  }
+    // Prototype first: a class instance or a `Proxy` over one can carry
+    // accessors on its prototype that plain-object callers never have. Reading
+    // the prototype of a revoked Proxy throws, which the wrapper closes.
+    // THE STRUCTURAL CODES ARE canonical.mjs's OWN, NOT THE CALLER'S.
+    //
+    // "this is not an argument record at all" is a fact about THIS boundary and
+    // takes the caller's code. "an accessor was found where a data property was
+    // required", "a symbol key was found", "the prototype is not plain" are the
+    // same three facts `dataRecordEntries` already names, and this file answers
+    // them with the same three codes. One condition, one code, wherever it is
+    // detected — the drift this codebase has paid for three times was always two
+    // places describing one rule slightly differently.
+  const prototype = runUntrusted(code, () => Object.getPrototypeOf(rawArguments));
+  if (prototype !== Object.prototype && prototype !== null) refuse(CODES.notPlain);
+  const record = Object.create(null);
+  const keys = runUntrusted(code, () => Reflect.ownKeys(rawArguments));
+  for (let index = 0; index < keys.length; index += 1) {
+    const key = keys[index];
+      // A symbol-keyed field is not addressable by any declared parameter, so
+      // it can only be a channel. Refused rather than dropped: dropping would
+      // mean the record validated is not the record the caller handed over.
+      if (typeof key !== "string") refuse(CODES.unsafeKey);
+    const descriptor = runUntrusted(code, () => Object.getOwnPropertyDescriptor(rawArguments, key));
+      // A Proxy may legally report a key from `ownKeys` and then answer
+      // `getOwnPropertyDescriptor` with `undefined` for it. Reading `"value" in
+      // undefined` raised a raw TypeError out of `projectStateAt` (review #1,
+      // H1R-01); a key that will not describe itself is refused here instead.
+    if (descriptor === undefined) refuse(code);
+      // THE ACCESSOR IS REFUSED WITHOUT BEING INVOKED. `"value" in descriptor`
+      // asks the question `descriptor.get` would answer by RUNNING. A
+      // non-enumerable data property is refused by the same rule and for the
+      // same reason `dataRecordEntries` refuses it: it is invisible to
+      // destructuring and visible to `Reflect.ownKeys`, so copying it would make
+      // the body see a field the caller's own spread would not.
+    if (!("value" in descriptor) || !descriptor.enumerable) refuse(CODES.accessor);
+      // THE DESCRIPTOR'S VALUE, NEVER `rawArguments[key]`. A Proxy can present a
+      // perfectly ordinary DATA descriptor and still answer `get` with something
+      // else, and answer it differently on every read — which is how the same
+      // argument object produced three different projections (review #1,
+      // H1R-01). Reading the descriptor is the only read that cannot be
+      // re-answered.
+    record[key] = descriptor.value;
+  }
+  return objectFreeze(record);
+}
+
+// Bound so a hostile oversized carrier is refused before it is walked or
+// copied. A contract limit, not a tuning knob — the same posture `canonical.mjs`
+// takes toward depth, node count and string length.
+const MAX_ENTRY_ARRAY_LENGTH = 100_000;
+
+// Materialize a caller-supplied ARRAY argument.
+//
+// WHY THE ARRAY CARRIER NEEDED ITS OWN LEVER. `Array.isArray` answers one
+// question — "is the carrier an Array" — and every way of then CONSUMING that
+// array is caller-controlled:
+//
+//   `for...of`     dispatches `value[Symbol.iterator]`, and a plain array may
+//                  own one. `assertAdapterProvides(adapter, ["EMIT_..."])` with
+//                  an own iterator yielding a DIFFERENT capability returned
+//                  `true` for a capability the adapter never declared — the
+//                  gate certified a sequence it had not validated.
+//   `.length`/`[i]` are `[[Get]]`s, which a Proxy over an array traps, so both
+//                  could throw the caller's own message text out of
+//                  `projectStateAt`.
+//
+// So the rule is the same one `entryRecord` holds, applied to indices:
+// VALIDATE ONCE, CAPTURE ONCE, USE THE CAPTURE. Elements are read from their
+// DESCRIPTORS in a single `Reflect.ownKeys` walk, and the frozen dense copy
+// returned is the only thing any caller may go on to consume.
+export function entryArray(rawArguments, code, structuralCode, maxLength = MAX_ENTRY_ARRAY_LENGTH) {
+  const CODES = structuralCodes(structuralCode);
+    // `Array.isArray` is not a pure predicate: it THROWS on a revoked Proxy.
+    // It runs inside the wrapper for the same reason `snapshotRecord`'s does.
+  if (!runUntrusted(code, () => arrayIsArray(rawArguments))) refuse(code);
+    // Plain arrays only, exactly as `canonical.mjs`'s `arrayElements` requires:
+    // a subclass could carry a prototype method that consumption dispatches
+    // through.
+  if (runUntrusted(code, () => Object.getPrototypeOf(rawArguments)) !== Array.prototype) {
+    refuse(CODES.notPlain);
+  }
+  const byIndex = new Map();
+  const keys = runUntrusted(code, () => Reflect.ownKeys(rawArguments));
+  for (let keyIndex = 0; keyIndex < keys.length; keyIndex += 1) {
+    const key = keys[keyIndex];
+      // A SYMBOL KEY ON AN ARRAY IS SKIPPED, NOT REFUSED — and the asymmetry
+      // with `entryRecord` is deliberate. On a record a symbol key is a channel
+      // carrying a value the body might read. On an array it can never be an
+      // indexed element, so it carries nothing this boundary reads; the one
+      // symbol a caller realistically attaches is `Symbol.iterator`, and the
+      // contract's answer to a hostile iterator is that IT IS NEVER CONSULTED,
+      // not that the array is rejected. `sdk-export-contract.test.mjs` has
+      // pinned that acceptance since round 10 and it stays true.
+      if (typeof key === "symbol") continue;
+      if (key === "length") continue;
+      if (!ARRAY_INDEX.test(key)) refuse(CODES.unsafeKey);
+    const descriptor = runUntrusted(code, () => Object.getOwnPropertyDescriptor(rawArguments, key));
+    if (descriptor === undefined) refuse(code);
+    if (!("value" in descriptor) || !descriptor.enumerable) refuse(CODES.accessor);
+    byIndex.set(Number(key), descriptor.value);
+    if (byIndex.size > maxLength) refuse(code);
+  }
+    // Dense, built from the CAPTURED indices rather than from a second read of
+    // `length` — which is itself a trappable `[[Get]]`. A hole would read as
+    // `undefined`, which is not a value any caller of this boundary accepts.
+  const elements = new NativeArray(byIndex.size);
+  for (let index = 0; index < byIndex.size; index += 1) {
+    if (!byIndex.has(index)) refuse(CODES.hole);
+    elements[index] = byIndex.get(index);
+  }
+  return objectFreeze(elements);
+}
+
+const ARRAY_INDEX = /^(?:0|[1-9][0-9]*)$/u;
+
+// HOW MANY ARGUMENT SLOTS A FUNCTION ACTUALLY DECLARES.
+//
+// NOT `Function.length`, which stops counting at the first defaulted parameter —
+// so `method({ a, b } = {})` reports 0 and `method(raw)` reports 1, and a
+// wrapper that dropped a second argument would look identical to one that did
+// not. The parameter list is read from the source text and split on TOP-LEVEL
+// commas, so a destructured or defaulted parameter counts as one slot.
+//
+// It lives here rather than in a test because `sealEntryPoints` is the last
+// moment the UNSEALED function exists: after installation every method reports
+// the wrapper's single parameter, and the number this measures is gone
+// (round-2 review #1, H1R2-09).
+function declaredParameterCount(fn) {
+  const source = reflectApply(functionToString, fn, []);
+  const start = source.indexOf("(");
+  if (start < 0) return 0;
+  let depth = 0;
+  let params = "";
+  for (let index = start; index < source.length; index += 1) {
+    const char = source[index];
+    if (stableStringHas("([{", char)) depth += 1;
+    if (stableStringHas(")]}", char)) {
+      depth -= 1;
+      if (depth === 0) break;
+    }
+    if (depth >= 1) params += char;
+  }
+  let inner = 0;
+  let slots = 1;
+  let seen = false;
+  for (const char of params.slice(1)) {
+    if (stableStringHas("([{", char)) inner += 1;
+    else if (stableStringHas(")]}", char)) inner -= 1;
+    else if (char === "," && inner === 0) slots += 1;
+    if (!/\s/u.test(char)) seen = true;
+  }
+  return seen ? slots : 0;
+}
+
+// Install the boundary over a declared method table.
+//
+// `codes` maps method name to the refusal code that method's malformed
+// arguments produce, so a caller still gets the boundary-specific code its
+// sibling validators use rather than one generic entry-point code.
+//
+// The wrapper is the ONLY thing that touches the caller's object; the wrapped
+// method receives the materialized record and may destructure it freely.
+// Returns the frozen table so a test can prove the installed set IS the
+// declared public surface, rather than trusting that the two were kept level.
+// ROUND-2 REVIEW #1, H1R2-07 — THE INSTALLER WAS OUTSIDE THE BOUNDARY IT
+// INSTALLS, AND IT INSTALLED NON-ATOMICALLY.
+//
+// Two defects, one shape. `Object.entries(codes)` ran the caller's accessors
+// before any guard, so a getter on the codes table raised a RAW `TypeError`
+// carrying the caller's own text out of a public export — the exact seam this
+// file's first sentence forbids, in the function that exists to close it. And
+// the loop mutated the prototype AS IT WENT, so a refusal partway through the
+// table left the prototype HALF-SEALED: some methods behind the boundary, some
+// bare, and a returned attestation naming methods that were never wrapped. A
+// partially installed security boundary is worse than an absent one, because
+// the attestation says it is present.
+//
+// Both close the same way the rest of this file works: MATERIALIZE, VALIDATE
+// EVERYTHING, THEN ACT. The codes table is materialized by `entryRecord`, every
+// entry is resolved and checked before a single property is redefined, and the
+// install loop touches the prototype only once the whole table is known good.
+//
+// The pre-seal arity is captured here as well, because it is the only place it
+// still exists: after installation every method reports the wrapper's arity of
+// 1, so a test reading the prototype can no longer observe what the method
+// itself declared (H1R2-09).
+export function sealEntryPoints(rawPrototype, rawCodes) {
+  // A Proxy may execute arbitrary traps during descriptor inspection or claim
+  // a successful define without making the write.  There is no rollback-safe
+  // commit over that protocol, so reject it before even validating the table.
+  if (rawPrototype === null || typeof rawPrototype !== "object" || isProxy(rawPrototype)) {
+    refuse("ENTRY_POINT_NOT_DECLARED");
+  }
+  const codes = entryRecord(rawCodes, "ENTRY_POINT_NOT_DECLARED");
+  // PHASE 1 — resolve and validate the WHOLE table. Nothing is mutated here.
+  const names = objectKeys(codes);
+  const planned = new Array(names.length);
+  for (let index = 0; index < names.length; index += 1) {
+    const name = names[index];
+    const code = codes[name];
+    if (typeof code !== "string") refuse("ENTRY_POINT_NOT_DECLARED");
+    const descriptor = runUntrusted(
+      "ENTRY_POINT_NOT_DECLARED",
+      () => objectGetOwnPropertyDescriptor(rawPrototype, name),
+    );
+    // A non-configurable slot cannot be replaced reliably.  Reject all such
+    // tables during phase 1, before a sibling slot has been touched.
+    if (!descriptor || typeof descriptor.value !== "function" || descriptor.configurable !== true) {
+      refuse("ENTRY_POINT_NOT_DECLARED");
+    }
+    planned[index] = {
+      name, code, descriptor,
+      inner: descriptor.value,
+      arity: declaredParameterCount(descriptor.value),
+    };
+  }
+  // Nothing in the ordinary-object commit phase can run caller code.  Check
+  // once more after all planning work so a target altered during validation is
+  // refused before its first sibling is installed.  (Proxies were rejected
+  // above because JavaScript cannot make this guarantee for their traps.)
+  for (let index = 0; index < planned.length; index += 1) {
+    const { name, descriptor } = planned[index];
+    const current = objectGetOwnPropertyDescriptor(rawPrototype, name);
+    if (!current || current.value !== descriptor.value ||
+        current.enumerable !== descriptor.enumerable ||
+        current.configurable !== descriptor.configurable ||
+        current.writable !== descriptor.writable) {
+      refuse("ENTRY_POINT_NOT_DECLARED");
+    }
+  }
+  // PHASE 2 — install. Every entry is already known good, so this cannot refuse
+  // partway and cannot leave the prototype in a mixed state.
+  const arities = Object.create(null);
+  const installedCodes = Object.create(null);
+  for (let index = 0; index < planned.length; index += 1) {
+    const { name, code, descriptor, inner, arity } = planned[index];
+    // Defined through a computed-name literal so the sealed function keeps the
+    // method's own name. The surface guard reads names off the prototype, and a
+    // wrapper reporting `name: ""` would make every stack trace and every
+    // reflective check read as anonymous.
+    const sealed = {
+      [name](rawArguments) {
+        return reflectApply(inner, this, [entryRecord(rawArguments, code)]);
+      },
+    }[name];
+    // The wrapper itself is the entry-security boundary.  It cannot remain
+    // writable/configurable after attestation or a later assignment could
+    // restore a raw caller-facing method.
+    objectDefineProperty(rawPrototype, name, {
+      value: sealed,
+      enumerable: descriptor.enumerable,
+      writable: false,
+      configurable: false,
+    });
+    const installed = objectGetOwnPropertyDescriptor(rawPrototype, name);
+    if (!installed || installed.value !== sealed || installed.writable !== false ||
+        installed.configurable !== false || installed.enumerable !== descriptor.enumerable) {
+      // This is unreachable for the preflighted ordinary-object commit, but a
+      // false attestation is never acceptable if a runtime violates it.
+      refuse("ENTRY_POINT_NOT_DECLARED");
+    }
+    arities[name] = arity;
+    installedCodes[name] = code;
+  }
+  return objectFreeze({
+    codes: objectFreeze(installedCodes),
+    // The declared parameter count of each method BEFORE sealing. Read by
+    // `entry-position-sweep.test.mjs`, which previously asserted arity against
+    // the installed wrapper — a value this function fixes at 1, so the
+    // assertion could never fail and the drift it guarded was invisible.
+    declaredArity: objectFreeze(arities),
+  });
+}