viz-js-lib 0.18.2 → 0.18.3

package/lib/agent.js

@@ -0,0 +1,237 @@
+'use strict';
+
+var _bluebird = require('bluebird');
+
+var _bluebird2 = _interopRequireDefault(_bluebird);
+
+var _key_public = require('./auth/ecc/src/key_public');
+
+var _key_public2 = _interopRequireDefault(_key_public);
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+/** Mirrors the node's never_delegable_operation_names(): a row holding one of these grants nothing. */
+/**
+ * VIZ agent access (HF15, op-id 105 `set_agent_permission`) — read-side helpers.
+ *
+ * A VIZ key is no longer only an authority key. A principal may register up to
+ * CHAIN_AGENT_MAX_PER_ACCOUNT live agents: a label plus a public key that may sign an explicit,
+ * frozen list of that principal's operations, optionally scoped to off-chain addons, optionally
+ * expiring (epoch `1970-01-01T00:00:00` = perpetual).
+ *
+ * The old check — "getAccount and look at active_authority.key_auths" — silently rejects agent
+ * keys, because an agent is not an account and never appears in any authority. The recipe now is
+ * authority OR agents, and `check()` does both in one call.
+ *
+ * Mirrors `VIZ\Agent` of viz-php-lib; the node (`agent_evaluator.cpp::usable_agent_row`) is the
+ * source of truth:
+ *  - an agent answers direct active/regular requirements only, and only for operations on its list;
+ *    the master authority is never satisfied by an agent, nor is a nested/other authority;
+ *  - a row is unusable when expired or when its list holds a never-delegable name;
+ *  - one key belongs to one agent of a principal; a key change of master/active, a recovery or a
+ *    sale wipes every agent of the principal.
+ *
+ * @module viz/agent
+ */
+
+var NEVER_DELEGABLE = ['set_agent_permission', 'proposal_update', 'account_update', 'recover_account', 'change_recovery_account', 'set_account_price', 'set_subaccount_price', 'target_account_sale'];
+
+/** Authority roles a key can belong to, most privileged first. Agents answer for none of them. */
+var ROLES = ['master', 'active', 'regular'];
+
+module.exports = function (VIZ_API) {
+  /** Agent rows of a principal as the node returns them (expired rows included; it sweeps them lazily). */
+  function get(account) {
+    return VIZ_API.getAgentPermissionsAsync(account);
+  }
+
+  /** First live agent row signed by `key`, or false. A failed request reads as "no agents". */
+  function find(account, key) {
+    return _bluebird2.default.resolve(get(account)).then(function (rows) {
+      if (!Array.isArray(rows)) {
+        return false;
+      }
+      for (var i = 0; i < rows.length; i++) {
+        var row = rows[i];
+        if (row && row.agent_key && !isExpired(row) && keyEquals(row.agent_key, key)) {
+          return row;
+        }
+      }
+      return false;
+    }).catch(function () {
+      return false;
+    });
+  }
+
+  /** Resolves true when `key` is a live agent of `account` — and, when `operation` is given, may sign it. */
+  function has(account, key, operation) {
+    return find(account, key).then(function (row) {
+      if (false === row) {
+        return false;
+      }
+      if (null === operation || undefined === operation || '' === operation) {
+        return true;
+      }
+      return grants(row, operation);
+    });
+  }
+
+  /**
+   * Unified check: may `key` act for `account`? Answers for the authority roles first, then for the
+   * agents. Resolves to an object:
+   *  allowed   — bool
+   *  source    — 'authority' | 'agent' | 'none'
+   *  role      — authority role the key matched, when source is 'authority', else false
+   *  agent     — the matched agent row, when source is 'agent', else false
+   *  operation — the operation the caller asked about (null = any)
+   *
+   * With `operation` omitted an authority key is answered by membership alone, while an agent is
+   * only answered as "this is a live agent key": its grants are per-operation, so pass the wire
+   * name (`transfer`, `pm_place_bet`, ...) to check a specific operation. A key that is only in a
+   * nested authority (account_auths) is NOT resolved here — use `verify_authority` with a signed
+   * transaction for the full recursive check. Note that a node without HF15 answers every agent
+   * question with "none": the check then degrades to authorities only.
+   */
+  function check(account, key, operation) {
+    var result = {
+      allowed: false,
+      source: 'none',
+      role: false,
+      agent: false,
+      operation: null === operation ? null : operation
+    };
+
+    return _bluebird2.default.resolve(VIZ_API.getAccountAsync(account, '')).catch(function () {
+      return false;
+    }).then(function (accountObject) {
+      if (accountObject && 'string' === typeof accountObject.name && accountObject.name === account) {
+        for (var i = 0; i < ROLES.length; i++) {
+          var role = ROLES[i];
+          if (inAuthority(accountObject[role + '_authority'], key)) {
+            result.allowed = true;
+            result.source = 'authority';
+            result.role = role;
+            return result;
+          }
+        }
+      }
+      return find(account, key).then(function (row) {
+        if (false !== row && (null === operation || undefined === operation || '' === operation || grants(row, operation))) {
+          result.allowed = true;
+          result.source = 'agent';
+          result.agent = row;
+        }
+        return result;
+      });
+    });
+  }
+
+  /** True when the agent row is alive at head block time. The node's own flag wins; the timestamp is the fallback. */
+  function isExpired(row) {
+    if (undefined !== row.expired) {
+      return !!row.expired;
+    }
+    if (!row.expiration) {
+      return false;
+    }
+    // The chain reports UTC without a trailing 'Z', so parse it as UTC explicitly.
+    var time = Date.parse(row.expiration + 'Z');
+    if (isNaN(time) || time <= 0) {
+      return false; // epoch = perpetual; an unparsable value is not a reason to deny the key
+    }
+    return time <= Date.now();
+  }
+
+  /** True when the row's list covers `operation` and the row is not poisoned by a never-delegable name. */
+  function grants(row, operation) {
+    if (!Array.isArray(row.operations) || -1 === row.operations.indexOf(operation)) {
+      return false;
+    }
+    return !poisoned(row);
+  }
+
+  /**
+   * True when the row's list holds a never-delegable name. The node refuses such a row WHOLE
+   * (`usable_agent_row` bails on the first forbidden name), it does not merely drop that name — so
+   * the row grants nothing at all, including its off-chain addons.
+   */
+  function poisoned(row) {
+    if (!Array.isArray(row.operations)) {
+      return false;
+    }
+    for (var i = 0; i < row.operations.length; i++) {
+      if (-1 !== NEVER_DELEGABLE.indexOf(row.operations[i])) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * True when the row is scoped to `scope`. Addons are opaque off-chain scopes: the node stores
+   * them and never interprets them, so a service matches its OWN scope here, by exact string
+   * (case-sensitive — the chain does not normalise them for us).
+   */
+  function addonMatches(row, scope) {
+    if (!Array.isArray(row.addons)) {
+      return false;
+    }
+    return -1 !== row.addons.indexOf(scope);
+  }
+
+  /** True when `key` is a member of the authority with enough weight to meet its threshold. */
+  function inAuthority(authority, key) {
+    if (!authority || !Array.isArray(authority.key_auths)) {
+      return false;
+    }
+    var threshold = parseInt(authority.weight_threshold, 10) || 0;
+    var weight = 0;
+    for (var i = 0; i < authority.key_auths.length; i++) {
+      var member = authority.key_auths[i];
+      if (member && member.length > 1 && keyEquals(member[0], key)) {
+        weight += parseInt(member[1], 10) || 0;
+      }
+    }
+    return weight >= threshold && weight > 0;
+  }
+
+  /** Compare two encoded keys, tolerating whitespace, a missing 'VIZ' prefix and base58 spelling differences. */
+  function keyEquals(a, b) {
+    if ('string' !== typeof a || 'string' !== typeof b) {
+      return false;
+    }
+    if (a === b) {
+      return true;
+    }
+    return normalizeKey(a) === normalizeKey(b);
+  }
+
+  /** Canonical `VIZ...` form of an encoded public key; the trimmed input when it cannot be parsed. */
+  function normalizeKey(key) {
+    var value = String(key === null || undefined === key ? '' : key).trim();
+    if ('' === value) {
+      return '';
+    }
+    if (0 !== value.indexOf('VIZ')) {
+      value = 'VIZ' + value;
+    }
+    var parsed = _key_public2.default.fromString(value);
+    return parsed ? parsed.toString() : String(key).trim();
+  }
+
+  return {
+    NEVER_DELEGABLE: NEVER_DELEGABLE,
+    ROLES: ROLES,
+    get: get,
+    find: find,
+    has: has,
+    check: check,
+    isExpired: isExpired,
+    grants: grants,
+    poisoned: poisoned,
+    addonMatches: addonMatches,
+    inAuthority: inAuthority,
+    keyEquals: keyEquals,
+    normalizeKey: normalizeKey
+  };
+};

package/lib/index.js

@@ -4,6 +4,7 @@ var api = require('./api');
 var auth = require('./auth');
 var broadcast = require('./broadcast');
 var formatter = require('./formatter')(api);
+var agent = require('./agent')(api);
 var memo = require('./auth/memo');
 var aes = require('./auth/ecc/src/aes');
 var config = require('./config');
@@ -15,6 +16,7 @@ module.exports = {
   auth: auth,
   broadcast: broadcast,
   formatter: formatter,
+  agent: agent,
   memo: memo,
   aes: aes,
   config: config,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viz-js-lib",
-  "version": "0.18.2",
+  "version": "0.18.3",
   "description": "viz.js the JavaScript Library with API support for VIZ blockchain",
   "main": "lib/index.js",
   "scripts": {

package/test/agent.test.js

@@ -0,0 +1,199 @@
+/**
+ * Offline tests for the HF15 agent helpers. The decision rules are pure functions on purpose:
+ * they mirror the node's agent_evaluator.cpp::usable_agent_row and must be testable without a node.
+ */
+
+require('babel-polyfill');
+const assert = require('assert');
+const agentFactory = require('../src/agent');
+
+const KEY = 'VIZ7iiYUk6hFuieveBJcTVTV33aNuC2vZauXuYc9Hki3moxsm9WXe';
+const OTHER_KEY = 'VIZ7FzBqZJmTdve9iuHXWvB3Ncu7VeJWKwpA1FpbLi4X4ZdsVAYjC';
+
+function row(overrides) {
+  return Object.assign({
+    account: 'alice',
+    agent_name: 'shop',
+    agent_key: KEY,
+    operations: ['transfer'],
+    expiration: '1970-01-01T00:00:00',
+    addons: ['wallet'],
+    expired: false,
+  }, overrides || {});
+}
+
+describe('viz.agent', function () {
+  const agent = agentFactory({});
+
+  describe('isExpired', function () {
+    it('treats the epoch as perpetual, not as expired', function () {
+      assert.strictEqual(agent.isExpired(row()), false);
+    });
+
+    it('flags a past expiration when the node sent no flag', function () {
+      //the timestamp path is the fallback for a node that does not compute `expired`
+      assert.strictEqual(
+        agent.isExpired(row({ expiration: '2020-01-01T00:00:00', expired: undefined })),
+        true
+      );
+    });
+
+    it('keeps a future expiration live', function () {
+      assert.strictEqual(agent.isExpired(row({ expiration: '2099-01-01T00:00:00' })), false);
+    });
+
+    it('lets the node flag outrank the client clock', function () {
+      assert.strictEqual(
+        agent.isExpired(row({ expiration: '2099-01-01T00:00:00', expired: true })),
+        true
+      );
+    });
+  });
+
+  describe('grants', function () {
+    it('covers only listed operations', function () {
+      assert.strictEqual(agent.grants(row(), 'transfer'), true);
+      assert.strictEqual(agent.grants(row(), 'pm_place_bet'), false);
+    });
+
+    it('refuses a row holding a never-delegable name whole', function () {
+      const poisoned = row({ operations: ['transfer', 'account_update'] });
+      assert.strictEqual(agent.grants(poisoned, 'transfer'), false);
+    });
+
+    it('refuses a malformed row', function () {
+      assert.strictEqual(agent.grants(row({ operations: undefined }), 'transfer'), false);
+    });
+  });
+
+  describe('poisoned', function () {
+    it('flags a row holding a never-delegable name', function () {
+      assert.strictEqual(agent.poisoned(row()), false);
+      assert.strictEqual(agent.poisoned(row({ operations: ['transfer', 'account_update'] })), true);
+    });
+
+    it('does not call a row without an operation list poisoned', function () {
+      assert.strictEqual(agent.poisoned(row({ operations: undefined })), false);
+    });
+  });
+
+  describe('addonMatches', function () {
+    it('matches the service scope exactly and case-sensitively', function () {
+      assert.strictEqual(agent.addonMatches(row(), 'wallet'), true);
+      assert.strictEqual(agent.addonMatches(row(), 'Wallet'), false);
+      assert.strictEqual(agent.addonMatches(row(), 'exchange'), false);
+      assert.strictEqual(agent.addonMatches(row(), ''), false);
+    });
+
+    it('treats a row without addons as no match, not as any scope', function () {
+      assert.strictEqual(agent.addonMatches(row({ addons: [] }), 'wallet'), false);
+      assert.strictEqual(agent.addonMatches(row({ addons: undefined }), 'wallet'), false);
+    });
+  });
+
+  describe('inAuthority', function () {
+    it('accepts a member that alone meets the threshold', function () {
+      const authority = {
+        weight_threshold: 2,
+        key_auths: [[KEY, 2], [OTHER_KEY, 1]],
+      };
+      assert.strictEqual(agent.inAuthority(authority, KEY), true);
+    });
+
+    it('refuses a member below the threshold', function () {
+      const authority = { weight_threshold: 2, key_auths: [[KEY, 1]] };
+      assert.strictEqual(agent.inAuthority(authority, KEY), false);
+    });
+
+    it('refuses a missing authority', function () {
+      assert.strictEqual(agent.inAuthority(false, KEY), false);
+      assert.strictEqual(agent.inAuthority(undefined, KEY), false);
+    });
+  });
+
+  describe('keyEquals / normalizeKey', function () {
+    it('tolerates whitespace and a missing prefix', function () {
+      assert.strictEqual(agent.keyEquals(KEY, ` ${KEY} `), true);
+      assert.strictEqual(agent.keyEquals(KEY, KEY.slice(3)), true);
+      assert.strictEqual(agent.keyEquals(KEY, OTHER_KEY), false);
+    });
+
+    it('returns the canonical form', function () {
+      assert.strictEqual(agent.normalizeKey(KEY.slice(3)), KEY);
+      assert.strictEqual(agent.normalizeKey(KEY), KEY);
+    });
+
+    it('hands back an unparsable value trimmed', function () {
+      assert.strictEqual(agent.normalizeKey(' not-a-key '), 'not-a-key');
+    });
+  });
+
+  describe('find / has / check against a stubbed node', function () {
+    function stub(rows, accountObject) {
+      return agentFactory({
+        getAgentPermissionsAsync: () => Promise.resolve(rows),
+        getAccountAsync: () => Promise.resolve(accountObject),
+      });
+    }
+
+    it('finds the key and applies the operation list', function () {
+      const stubbed = stub([row()], false);
+      return stubbed.has('alice', KEY, 'transfer').then((allowed) => {
+        assert.strictEqual(allowed, true);
+        return stubbed.has('alice', KEY, 'pm_place_bet');
+      }).then((allowed) => {
+        assert.strictEqual(allowed, false);
+        return stubbed.has('alice', OTHER_KEY, 'transfer');
+      }).then((allowed) => {
+        assert.strictEqual(allowed, false);
+      });
+    });
+
+    it('skips expired rows', function () {
+      const stubbed = stub([row({ expired: true })], false);
+      return stubbed.has('alice', KEY, 'transfer').then((allowed) => {
+        assert.strictEqual(allowed, false);
+      });
+    });
+
+    it('answers an authority key from the account object', function () {
+      const stubbed = stub([], {
+        name: 'alice',
+        active_authority: { weight_threshold: 1, key_auths: [[KEY, 1]] },
+      });
+      return stubbed.check('alice', KEY, 'transfer').then((verdict) => {
+        assert.strictEqual(verdict.allowed, true);
+        assert.strictEqual(verdict.source, 'authority');
+        assert.strictEqual(verdict.role, 'active');
+      });
+    });
+
+    it('answers an agent key from the rows', function () {
+      const stubbed = stub([row()], false);
+      return stubbed.check('alice', KEY, 'transfer').then((verdict) => {
+        assert.strictEqual(verdict.allowed, true);
+        assert.strictEqual(verdict.source, 'agent');
+        assert.strictEqual(verdict.agent.agent_name, 'shop');
+      });
+    });
+
+    it('denies a key matching neither', function () {
+      const stubbed = stub([], { name: 'alice' });
+      return stubbed.check('alice', OTHER_KEY, 'transfer').then((verdict) => {
+        assert.strictEqual(verdict.allowed, false);
+        assert.strictEqual(verdict.source, 'none');
+      });
+    });
+
+    it('degrades to authorities when the node refuses the agent call', function () {
+      const stubbed = agentFactory({
+        getAgentPermissionsAsync: () => Promise.reject(new Error('unknown method')),
+        getAccountAsync: () => Promise.resolve({ name: 'alice' }),
+      });
+      return stubbed.check('alice', KEY, 'transfer').then((verdict) => {
+        assert.strictEqual(verdict.allowed, false);
+        assert.strictEqual(verdict.source, 'none');
+      });
+    });
+  });
+});

package/test/methods_by_version.js

@@ -11,6 +11,8 @@ export const methods_test = [
     "get_accounts_on_auction",
     "get_accounts_on_sale",
     "get_agent_permissions",
+    "get_key_history",
+    "get_key_history_by_key",
     "get_active_paid_subscriptions",
     "get_active_validators",
     "get_active_witnesses",