README
Selfkey Agent
A Selfkey SSI agent library. Utilizes heavily the veramo framework and did-jwt-vc library
For storage typeorm is used.
Usage
yarn add @selfkey/agent
Agent example:
const Entities = require('@selfkey/agent/lib/entities').default;
const SelfkeyAgent = require('@selfkey/agent').default;
const {createConnection} = require('typeorm');
async function main(){
const infuraId = 'INSERT PROJECT ID';
const dbConnection = createConnection({
type: 'sqlite',
database: 'db.sqlite',
synchronize: true,
logging: ['error', 'info', 'warn'],
entities: Entities
});
const kmsKey = await SelfkeyAgent.generateKMSKey();
const agent = new SelfkeyAgent({
dbConnection,
infuraId,
kmsKey,
agentName: 'example.com,
didProvider: 'did:web'
});
const did = await agent.ensureAgentDID();
// 'did:web:example.com
const didDoc = await agent.generateDIDDoc(did);
/*
{
"@context": "https://w3id.org/did/v1",
"id": "did:web:example.com",
"publicKey": [
{
"id": "did:web:example.com#0409e2da3624c81b9116c9da841b786cef96b7f4af09107d11c16b39fc5607bbf12be877b6fa7e8c570b3fa736e2d98958981403acba77130ce401ef9056bad5ca",
"type": "Secp256k1VerificationKey2018",
"controller": "did:web:example.com",
"publicKeyHex": "0409e2da3624c81b9116c9da841b786cef96b7f4af09107d11c16b39fc5607bbf12be877b6fa7e8c570b3fa736e2d98958981403acba77130ce401ef9056bad5ca"
}
],
"authentication": [
{
"id": "did:web:example.com#0409e2da3624c81b9116c9da841b786cef96b7f4af09107d11c16b39fc5607bbf12be877b6fa7e8c570b3fa736e2d98958981403acba77130ce401ef9056bad5ca",
"type": "Secp256k1SignatureAuthentication2018",
"publicKey": "did:web:example.com#0409e2da3624c81b9116c9da841b786cef96b7f4af09107d11c16b39fc5607bbf12be877b6fa7e8c570b3fa736e2d98958981403acba77130ce401ef9056bad5ca",
"controller": "did:web:example.com"
}
],
"service": []
}
*/
const credentialSubject = {
firstName: 'First',
lastName: 'Last',
nationality: 'Armenia',
id: 'did:ethr:0xsdasda2dsadasdas...'
};
const credential = await agent.issueCredential({credentialSubject});
const verifiedCredential = await agent.verifyCredential(credential);
const presentation = await agent.issuePresentation([credential], 'did:web:verifier.com');
// agent with did 'did:web:verifier.com'
await agent.verifyPresentation(presentation);
}
Binary
When installing the library, a script executable will be installed as well into node_modules/.bin
You can generate a Secret Box private key with it
sagent-gen-pk
API
interface ISelfkeyAgentOptions {
dbConnection: Promise<Connection>;
infuraId?: string;
kmsKey?: string;
kmsName?: string;
agentName?: string;
didProvider: 'did:web' | 'did:ethr' | 'did:ethr:ropsten';
}
interface IUnsignedCredential {
'@context'?: string[];
id?: string;
type?: string[];
issuer?: { id: string; [x: string]: any };
issuanceDate?: string;
expirationDate?: string;
credentialSubject: {
id?: string;
[x: string]: any;
};
credentialStatus?: {
id: string;
type: string;
};
[x: string]: any;
}
constructor(private options: ISelfkeyAgentOptions)
static async generateKMSKey(): string
Generates a private key that can be used as an input for KMS Secret Box
Used in the sagent-gen-pk bin script.
async importIdentifier(identifier: IIdentifier)
Pass trough function for veramo import method
Allows to import an existing identifier to the agent.
If you are importing main agent identifier, please specify the alias options the same as agentName as provided in constructor.
If no agent name was provided, specify the default selfkey-agent
async ensureAgentDID(options?: object)
Returns agent did. If no existing did found, creates a new one.
Please make sure to use importIdentifier before calling this function if you want to use an existing key for your agent.
sync getAgentDIDDocument(options?: object): Promise<DIDDocument | null>
Generates a DID document for the agent
async resolveDIDDoc(didUrl: string): Promise<DIDDocument | null>
Uses DID resolver to resolve a DID doc
async generateDIDDoc(did: string): Promise<DIDDocument | null>
Generates a DID doc for a did that is stored in the local store. Useful for generating DID Documents for non resolvable DID's
async issueCredential(
credential: IUnsignedCredential,
options: {
save?: boolean;
proofFormat?: string;
} = { save: false, proofFormat: 'JWT' }
): Promise<VerifiableCredential>
Issues a new JWT Verifiable credential
async issuePresentation(
credentials: VerifiableCredential[],
verifierDID: string,
holderDid?: string,
options?: { save: boolean }
): Promise<VerifiablePresentation>
Issues a new JWT verifiable presentation
async verifyCredential(
vc: string | VerifiableCredential,
options?: object
): Promise<VerifiedCredential>
Verifies a JWT verifiable credential. A VC object or a JWT string can be provided
async verifyPresentation(
vp: string | VerifiablePresentation,
options?: object
): Promise<VerifiedPresentation>
Verifies a JWT verifiable presentation. A VP object or a JWT string can be provided
async listCredentials(): Promise<UniqueVerifiableCredential[]>
List all credentials stored in local store
async listCredentialsForSubjectId(id: string): Promise<UniqueVerifiableCredential[]>
Lists credentials from local store filtered by subject id
async listCredentialsForIssuerId(id: string | string[]): Promise<UniqueVerifiableCredential[]>
Lists credentials from local store filtered by issuer id
Tests
From monorepo root directory run jest agent
NOTE: verify presentation / credential tests might fail sporadically because they rely on network requests to resolve DID. They should be mocked instead.
Deploy
Navigate to packages/agent
Run yarn version to update the package version
Run git push --tags to push the new version and tag to the github repo
Then run yarn publish to publish the new version to npm
TODO: Deploy process should happen automatically from CI. Also, versioning and deploy should be managed by lerna on the root of the monorepo.