@meantjs/profile 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meantjs/profile",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Candid Profile resolver: validates profiles, matches packs by Candid subtyping, merges layers (spec section 8) and emits the resolved form (spec section 10).",
   "license": "Apache-2.0",
   "repository": {

package/src/analyze.mjs

@@ -9,7 +9,7 @@ import { TagIndex, LayeredTags, positions } from "./tags.mjs";
 import {
   NUMERIC, METHOD_TAGS, CASE_TAGS, CONFIRM_KINDS, STALE_CODES, VALUE_CONVERSION_TAGS, EVM_LATER_TAGS,
   checkApplicability, checkDynamic, parseTemplate, outcomeCoverage, caseTargetError, otherCase, overlap, defaultEffect,
-  tokenPathError,
+  tokenPathError, grantError,
 } from "./checks.mjs";
 
 /** Spec section 8, highest precedence first. */
@@ -147,6 +147,18 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
     }
   };
 
+  /**
+   * A grant that does not hold (spec 5.3, D-056). A pack applied to a service loses only its grant, never the effect:
+   * dropping the effect would leave a transfer or approve with the default effect, which needs no confirmation.
+   */
+  const grants = []; // effects whose grant holds, checked again once dropped tags are known
+  const badGrant = (e, diag, why) => {
+    if (!e.item.apply) return diag("error", "E_GRANT", e.ann.at, why);
+    const { grant, ...args } = e.entry.args;
+    e.entry.args = args;
+    e.item.diag("info", "I_PACK_ANNOTATION_SKIPPED", e.ann.at, `effect grant dropped, the effect kept: E_GRANT: ${why}`);
+  };
+
   const sets = new Map(); // names set -> { at, method, fields: { name, value, show?, kind? } } (spec 5.3, D-045)
   const named = []; // named positions, checked once every set is known
   for (const e of entries) {
@@ -167,8 +179,10 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
       const why = caseTargetError(iface, addr, res, a.tag);
       if (why) { diag("error", "E_TAG_TARGET", at, why); continue; }
       const m = iface.methods.get(addr.method);
-      if (a.tag === "effect") checkEffectMode(m, a.args, diag, at);
-      else checkTemplate(item, addr.method, a.args.template, diag, at, addr);
+      if (a.tag === "effect") {
+        checkEffectMode(m, a.args, diag, at);
+        if (a.args.grant) badGrant(e, diag, "a grant sits on the effect of a method, not of a case, in this version (D-056)");
+      } else checkTemplate(item, addr.method, a.args.template, diag, at, addr);
       caseEntries.push({ e, diag });
       continue;
     }
@@ -176,6 +190,11 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
       const m = res.method;
       const methodName = addr.method;
       if (a.tag === "effect") checkEffectMode(m, a.args, diag, at);
+      if (a.tag === "effect" && a.args.grant) {
+        const why = grantError(iface, tags, methodName, a.args);
+        if (why) badGrant(e, diag, why);
+        else grants.push({ e, diag });
+      }
       if (a.tag === "idempotency") {
         if (m.mode !== "update") diag("error", "E_IDEMPOTENCY_MODE", at, "idempotency applies to update methods");
         const r = iface.resolveRel(methodName, "args", a.args.stamp);
@@ -289,9 +308,14 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
     }
   }
 
-  // Dropping a value tag can leave an idempotency stamp without its timestamp tag: drop that idempotency too.
+  // Dropping a value tag can leave an idempotency stamp without its timestamp tag: drop that idempotency too. It can
+  // also leave a grant without the amount, timestamp or account tag it needs.
   if (dropped.size) {
     const without = buildLayers(entries, (e) => !dropped.has(e));
+    for (const { e, diag } of grants) {
+      const why = !dropped.has(e) && grantError(iface, without, e.addr.method, e.entry.args);
+      if (why) badGrant(e, diag, `${why} (a tag it needs was dropped in this service)`);
+    }
     for (const e of entries) {
       if (!e.item.apply || e.ann.tag !== "idempotency" || dropped.has(e)) continue;
       const r = iface.resolveRel(e.addr.method, "args", e.ann.args.stamp);

package/src/checks.mjs

@@ -18,7 +18,7 @@ export const CASE_TAGS = new Set(["intent", "effect"]);
 export const CONFIRM_KINDS = new Set(["transfer", "approve", "admin", "destroy"]);
 /** Tags that convert a value between its wire form and a human form; a stale profile must not supply them (spec section 7). */
 export const VALUE_CONVERSION_TAGS = new Set(["amount", "timestamp", "duration", "account", "subaccount", "bytes", "named"]);
-export const STALE_CODES = new Set(["E_ADDR_UNRESOLVED", "E_TYPE_NODE", "E_TAG_NOT_APPLICABLE", "E_REF_UNRESOLVED", "E_REF_NOT_QUERY", "E_REF_SHAPE", "E_REF_TYPE", "E_STAMP_UNTAGGED", "E_OUTCOME_NOT_CASE", "E_TEMPLATE_PATH", "E_TAG_TARGET", "E_NAMES_MODE", "E_NAMES_SHAPE", "E_NAMES_FIELD", "E_NAMED_SET", "E_NAMED_TYPE", "E_CASE_OVERLAP", "E_CASE_EFFECT", "E_TOKEN_PATH"]);
+export const STALE_CODES = new Set(["E_ADDR_UNRESOLVED", "E_TYPE_NODE", "E_TAG_NOT_APPLICABLE", "E_REF_UNRESOLVED", "E_REF_NOT_QUERY", "E_REF_SHAPE", "E_REF_TYPE", "E_STAMP_UNTAGGED", "E_OUTCOME_NOT_CASE", "E_TEMPLATE_PATH", "E_TAG_TARGET", "E_NAMES_MODE", "E_NAMES_SHAPE", "E_NAMES_FIELD", "E_NAMED_SET", "E_NAMED_TYPE", "E_CASE_OVERLAP", "E_CASE_EFFECT", "E_TOKEN_PATH", "E_GRANT"]);
 
 export function checkApplicability(iface, tag, ref) {
   const { ref: r } = iface.unwrapOpt(ref);
@@ -57,6 +57,55 @@ export function tokenPathError(iface, addr, token) {
   return null;
 }
 
+/**
+ * An effect's grant (spec 5.3, D-056): who may take the tokens, how many and until when, as positions in the arguments
+ * of the method the effect is on. `tags` is the merged view: the amount, timestamp and account tags a grant needs may
+ * come from another profile. The reason it is wrong, or null.
+ */
+export function grantError(iface, tags, methodName, { kind, grant }) {
+  if (kind !== "transfer" && kind !== "approve") return `a grant goes with effect kind transfer or approve, not ${kind}`;
+  if ((grant.spender === undefined) === (grant.to === undefined)) return "a grant names exactly one of spender and to";
+  if (kind === "approve" && grant.to !== undefined) return "an approve's grant names a spender: an allowance is taken by its spender, not paid to it";
+  const at = (name, rel, mayBeAbsent) => {
+    const p = parseRelPath(rel);
+    const r = iface.resolveRel(methodName, "args", rel);
+    const what = `grant ${name} ${JSON.stringify(rel)}`;
+    if (!p || r.error) return { error: `${what}: ${r.error ?? "not a relative path"}` };
+    if (p.segs.some((s) => s.kind === "elem")) return { error: `${what} steps into []: a grant covers one token, so a request that grants several has none` };
+    // The value must be in every call: no case of a variant on the way, and no opt unless it may be left out.
+    let cur = iface.methods.get(methodName).args[p.index ?? 0];
+    let optional = false;
+    for (const s of p.segs) {
+      const u = iface.unwrapOpt(cur);
+      optional ||= u.optional;
+      const n = iface.node(u.ref);
+      if (n.kind === "variant") return { error: `${what} passes through a case of a variant, so a call need not hold it` };
+      cur = n.fields.find((f) => f.id === s.id).type;
+    }
+    if ((optional || iface.unwrapOpt(cur).optional) && !mayBeAbsent) return { error: `${what} is optional, but a grant needs its ${name} in every call` };
+    return { r, t: tags.at(r, iface) ?? {} };
+  };
+  const who = grant.spender !== undefined ? "spender" : "to";
+  const party = at(who, grant[who], false);
+  if (party.error) return party.error;
+  if (iface.prim(party.r.ref) !== "address" && !party.t.account) {
+    return `grant ${who} ${JSON.stringify(grant[who])} is ${iface.describeType(party.r.ref)}; it must be an address or carry an account tag`;
+  }
+  const amount = at("amount", grant.amount, false);
+  if (amount.error) return amount.error;
+  const p = iface.prim(amount.r.ref);
+  if (p !== "bool") {
+    if (!amount.t.amount) return `grant amount ${JSON.stringify(grant.amount)} is ${iface.describeType(amount.r.ref)} without an amount tag; it must carry one, or be a bool`;
+    if (!/^(nat|uint)/.test(p)) return `grant amount ${JSON.stringify(grant.amount)} is ${p}; an amount granted is never negative, so its type is unsigned`;
+  }
+  for (const rel of grant.ends ?? []) {
+    const end = at("ends", rel, true);
+    if (end.error) return end.error;
+    if (!end.t.timestamp) return `grant ends ${JSON.stringify(rel)} has no timestamp tag`;
+  }
+  return null;
+}
+
 export function checkDynamic(iface, value, want, diag, at) {
   if (!value || typeof value !== "object") return;
   const from = value.from;