viz-js-lib 0.18.2 → 0.18.3

package/README.md

@@ -70,6 +70,53 @@ viz.api.getAccounts(['ned', 'dan'], function(err, result) {
 });
 ```
 
+### Key checks: authority or agent (HF15)
+
+HF15 added `set_agent_permission` (op 105): a principal may hand a key an explicit, frozen list of
+its operations — an *agent*. An agent is not an account and never appears in any authority, so the
+old check ("`getAccount` and look at `active_authority.key_auths`") silently rejects agent keys.
+The recipe is now **authority OR agents**, and `viz.agent.check()` does both in one call.
+
+Rules the helper mirrors from the node (`agent_evaluator.cpp::usable_agent_row`):
+
+- 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;
+- `expiration` epoch (`1970-01-01T00:00:00`) = perpetual; a date in the past = revoked;
+- empty `operations` and `addons` = revoked; `addons` are off-chain scopes the node stores and
+  never interprets, so a service matches its own scope there;
+- one key belongs to one agent of a principal; a change of master/active, a recovery or a sale
+  wipes every agent of the principal.
+
+`check(account, key, operation)` resolves to `{allowed, source: 'authority'|'agent'|'none', role,
+agent, operation}`; `find()` resolves to the raw row (or `false`), `has()` to a bool. Pass the wire
+operation name (`transfer`, `pm_place_bet`, ...) to check a specific operation — with no operation
+an agent key is only answered as "this is a live agent key", because its grants are per-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. On a node without HF15
+the agent call fails, `find()` reads that as "no agents", and the check degrades to authorities
+only.
+
+`poisoned(row)` and `addonMatches(row, scope)` are the two pure row predicates the verdicts are
+built from, exported for callers that already hold a row (and mirrored by `VIZ\Agent` in the PHP
+lib).
+
+```js
+viz.config.set('websocket', 'https://api.viz.world/');
+
+//the key recovered from the request signature
+viz.agent.check('altbettor', 'VIZ7iiYUk6hFuieveBJcTVTV33aNuC2vZauXuYc9Hki3moxsm9WXe', 'transfer')
+	.then(verdict => {
+		if (verdict.allowed) console.log('allowed by', verdict.source);//'authority' or 'agent'
+		else console.log('denied');
+	});
+
+viz.agent.get('altbettor').then(rows => console.log(rows));//every agent of the principal
+viz.agent.find('altbettor', 'VIZ7ii...').then(row => console.log(row));//live row, or false
+```
+
+The write side is `viz.broadcast.setAgentPermission(...)`. The raw read method is
+`viz.api.getAgentPermissionsAsync(account)`.
+
 ## Contributions
 Patches are welcome! Contributors are listed in the package.json file. Please run the tests before opening a pull request and make sure that you are passing all of them. If you would like to contribute, but don't know what to work on, check the issues list.
 

package/api-frontend/app.js

@@ -43,6 +43,8 @@ const METHODS = [
   {api:"database_api",method:"get_accounts_on_auction",params:["from","limit","name_prefix"]},
   {api:"database_api",method:"get_subaccounts_on_sale",params:["from","limit","name_prefix"]},
   {api:"database_api",method:"get_agent_permissions",params:["account"]},
+  {api:"database_api",method:"get_key_history",params:["account","from","limit"]},
+  {api:"database_api",method:"get_key_history_by_key",params:["key","limit"]},
   {api:"account_by_key",method:"get_key_references",params:["account_name_type"]},
   {api:"network_broadcast_api",method:"broadcast_transaction",params:["trx"]},
   {api:"network_broadcast_api",method:"broadcast_transaction_with_callback",params:["confirmationCallback","trx"]},
@@ -422,7 +424,9 @@ const SPEC = {
     get_accounts_on_sale: {d:"Returns accounts currently on sale (direct sale, not auction).",p:{from:{c:"From Offset",d:"Number of results to skip for pagination."},limit:{c:"Limit",d:"Maximum number of results (max 1000)."},name_prefix:{c:"Name Prefix",d:"Optional. Only accounts whose name starts with this prefix. Matched against the account-name index, so it searches the whole set and finds accounts past the first page. Empty or omitted returns all."}}},
     get_accounts_on_auction: {d:"Returns accounts currently on auction (no target buyer set).",p:{from:{c:"From Offset",d:"Number of results to skip for pagination."},limit:{c:"Limit",d:"Maximum number of results (max 1000)."},name_prefix:{c:"Name Prefix",d:"Optional. Only accounts whose name starts with this prefix. Matched against the account-name index, so it searches the whole set and finds accounts past the first page. Empty or omitted returns all."}}},
     get_subaccounts_on_sale: {d:"Returns subaccounts currently on sale.",p:{from:{c:"From Offset",d:"Number of results to skip for pagination."},limit:{c:"Limit",d:"Maximum number of results (max 1000)."},name_prefix:{c:"Name Prefix",d:"Optional. Only subaccounts whose name starts with this prefix. Matched against the account-name index, so it searches the whole set and finds subaccounts past the first page. Empty or omitted returns all."}}},
-    get_agent_permissions: {d:"Returns the agents of a principal (HF15 agent access): name, public key, allowed operations, expiration (1970-01-01T00:00:00 = perpetual), addons (off-chain scopes such as vizhub) and an expired flag. At most 16 rows, ordered by agent name. Nodes without HF15 answer with an unknown-method error.",p:{account:{c:"Account Name",d:"The principal whose agents to return."}}}
+    get_agent_permissions: {d:"Returns the agents of a principal (HF15 agent access): name, public key, allowed operations, expiration (1970-01-01T00:00:00 = perpetual), addons (off-chain scopes such as vizhub) and an expired flag. At most 16 rows, ordered by agent name. Nodes without HF15 answer with an unknown-method error.",p:{account:{c:"Account Name",d:"The principal whose agents to return."}}},
+    get_key_history: {d:"Permanent key history of an account (HF15): every key or account it stopped standing behind — role (master/active/regular/memo), key or auth_account, weight, weight_threshold, valid_until_block (last block the key still held) and valid_until_time. Oldest first; rows are never pruned. Nodes without HF15 answer with an unknown-method error.",p:{account:{c:"Account Name",d:"Whose key history to return."},from:{c:"From",d:"Row id to start at (0 = first row); for the next page pass the last id + 1."},limit:{c:"Limit",d:"Max rows, up to 1000."}}},
+    get_key_history_by_key: {d:"Who held a public key in the past and until which block (HF15 key history). Keys currently in use are not listed — they are in the accounts themselves.",p:{key:{c:"Public Key",d:"The key to look up (VIZ...)."},limit:{c:"Limit",d:"Max rows, up to 1000."}}}
   },
   account_by_key: {
     get_key_references: {d:"Returns all account names that reference the given public keys in their authority.",p:{account_name_type:{c:"Public Keys",d:"Array of public keys to look up.",t:"array"}}}