JLINC ZCAP
This module, using authorization capabilities as described in ZCAP-LD, provides methods intended to:
- create a delegable ZCAP so that one organization can provide a means for another organization to delegate to its members the ability to access data or be logged into the first organization
- use a delegable ZCAP to delegate that authority to an individual
- invoke the delegated authority
- verify that the invocation is correct and authoritative
Prerequisites:
- the organizations involved can persist ZCAPs and can revoke the authority by updating their internal records
- each organization and individual involved has obtained a DID that can be resolved to obtain its status and signing public key
Usage
const zcap = require('jlinc-zcap');
Create a delegable ZCAP
const delegable = zcap.createDelegable( invokerDid, parentCapability );
// invokerDid is the DID of the entity to which this authority is being granted.
// parentCapability is an object that includes a pointer to the target url that
// this capability will operate against, as well as cryptographic material for
// the granting authority.
//
//
// The proof is signed by the parentCapability granting authority's secret key.
Delegate a ZCAP
const delegated = zcap.delegate( invoker, parentId, delegator, caveats );
// In this case the invoker is an object containing the DID and keys of
// the invoker (the entity receiving the delegated authority).
// The parentId is the ID of the delegable ZCAP object created by createDelegable.
// The delegator is an object containing the DID and keys of the delegator.
//
// The caveats is an optional argument consisting of an array of caveat objects.
//
// The proof is signed by the secret keys of both the delegatorDid and the invokerDid.
Invoke a delegated ZCAP
// TODO: zcap.invokeDelegated(invoker, delegated, action);
// Packages an invocation in a JWT signed by the invoker
// for transmission to the target to invoke an action.
Invoke a delegable ZCAP
const token = zcap.invokeDelegable(invoker, delegable, action);
// Packages an invocation in a JWT signed by the invoker
// for transmission to the target to invoke an action.
//
// In this case the invoker is an object containing the DID and keys of
// the invoker (the entity being delegated the delegable authority).
//
// The delegable argument must be a valid delegable ZCAP.
//
// The target MUST ascertain that the action argument is allowed
// by the delegable object's caveat array.
Verify an invocation
const verified = zcap.verifyZcapInvocation(zcap);
// The zcap argument may be an object, a JSON string or a JWT.
// If a JWT, it unpacks and verifies the JWT submitted.
// Then it verifies all signatures.
// Returns the delegator and invoker DIDs and parentCapability ID so they can be verified as unrevoked.
Asynchronously retrieve and cache a DID's signing key
zcap.didServerUrl = 'http://localhost:5001';
zcap.getSigningKey(did)
.then(function(response){...})
.catch(function(err){...});
// Accepts a DID in the did:jlinc:xxx format.
// Returns a promise which resolves to an object { signingKey: [base64 encoded public key] },
// or a status object, e.g { status: 'not found' },
// or an error.