@3sixty/identity-rest-client 0.0.0-stage → 0.20.0-next.0

package/dist/types/identityRestClient.d.ts

@@ -0,0 +1,202 @@
+import { BaseRestClient } from "@3sixty/api-core";
+import type { IBaseRestClientConfig } from "@3sixty/api-models";
+import type { IJsonLdContextDefinitionRoot, IJsonLdNodeObject } from "@3sixty/data-json-ld";
+import { type IIdentityComponent } from "@3sixty/identity-models";
+import { DidVerificationMethodType, type IDidDocument, type IDidDocumentVerificationMethod, type IDidService, type IDidVerifiableCredential, type IDidVerifiablePresentation, type IProof, ProofTypes } from "@3sixty/standards-w3c-did";
+/**
+ * Client for performing identity through to REST endpoints.
+ */
+export declare class IdentityRestClient extends BaseRestClient implements IIdentityComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of IdentityRestClient.
+     * @param config The configuration for the client.
+     */
+    constructor(config: IBaseRestClientConfig);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Create a new identity.
+     * @param namespace The namespace of the connector to use for the identity, defaults to service configured namespace.
+     * @returns The created identity document.
+     */
+    identityCreate(namespace?: string): Promise<IDidDocument>;
+    /**
+     * Remove an identity.
+     * @param identity The id of the document to remove.
+     * @param options Optional settings.
+     * @param options.removeKeys Also remove any associated private keys from the vault.
+     * @param options.removeDocumentKey Also remove the document key from the vault.
+     * @returns A promise that resolves when the identity has been removed.
+     */
+    identityRemove(identity: string, options?: {
+        removeKeys?: boolean;
+        removeDocumentKey?: boolean;
+    }): Promise<void>;
+    /**
+     * Add a verification method to the document in JSON Web key Format.
+     * @param identity The id of the document to add the verification method to.
+     * @param verificationMethodType The type of the verification method to add.
+     * @param verificationMethodId The id of the verification method, if undefined uses the kid of the generated JWK.
+     * @returns The verification method.
+     * @throws NotFoundError if the id can not be resolved.
+     * @throws NotSupportedError if the platform does not support multiple keys.
+     */
+    verificationMethodCreate(identity: string, verificationMethodType: DidVerificationMethodType, verificationMethodId?: string): Promise<IDidDocumentVerificationMethod>;
+    /**
+     * Remove a verification method from the document.
+     * @param verificationMethodId The id of the verification method.
+     * @param options Optional settings.
+     * @param options.removeKeys Also remove any associated private key from the vault.
+     * @param controller Unused by the REST client; the controller is resolved server-side from the session context.
+     * @returns A promise that resolves when the verification method has been removed.
+     * @throws NotFoundError if the id can not be resolved.
+     * @throws NotSupportedError if the platform does not support multiple revocable keys.
+     */
+    verificationMethodRemove(verificationMethodId: string, options?: {
+        removeKeys?: boolean;
+    }, controller?: string): Promise<void>;
+    /**
+     * Add a service to the document.
+     * @param identity The id of the document to add the service to.
+     * @param serviceId The id of the service.
+     * @param serviceType The type of the service.
+     * @param serviceEndpoint The endpoint for the service.
+     * @returns The service.
+     * @throws NotFoundError if the id can not be resolved.
+     */
+    serviceCreate(identity: string, serviceId: string, serviceType: string | string[], serviceEndpoint: string | string[]): Promise<IDidService>;
+    /**
+     * Remove a service from the document.
+     * @param serviceId The id of the service.
+     * @returns A promise that resolves when the service has been removed.
+     * @throws NotFoundError if the id can not be resolved.
+     */
+    serviceRemove(serviceId: string): Promise<void>;
+    /**
+     * Add an alias to the alsoKnownAs property on the document.
+     * If the alias is already present the operation is a no-op.
+     * @param documentId The id of the document to update.
+     * @param alias The alias to add. Must be a Url or Urn (typically another DID).
+     * @returns A promise that resolves when the alias has been added.
+     * @throws GeneralError if the alias is not a Url or Urn.
+     * @throws NotFoundError if the id can not be resolved.
+     */
+    alsoKnownAsAdd(documentId: string, alias: string): Promise<void>;
+    /**
+     * Remove an alias from the alsoKnownAs property on the document.
+     * If the alias is not present the operation is a no-op.
+     * @param documentId The id of the document to update.
+     * @param alias The alias to remove. Must be a Url or Urn.
+     * @returns A promise that resolves when the alias has been removed.
+     * @throws GeneralError if the alias is not a Url or Urn.
+     * @throws NotFoundError if the id can not be resolved.
+     */
+    alsoKnownAsRemove(documentId: string, alias: string): Promise<void>;
+    /**
+     * Create a verifiable credential for a verification method.
+     * @param verificationMethodId The verification method id to use.
+     * @param id The id of the credential.
+     * @param subject The credential subject to store in the verifiable credential.
+     * @param options Additional options for creating the verifiable credential.
+     * @param options.revocationIndex The bitmap revocation index of the credential, if undefined will not have revocation status.
+     * @param options.expirationDate The date the verifiable credential is valid until.
+     * @param options.jwtHeaderFields Additional fields to include in the JWT header when creating the verifiable credential in jwt format.
+     * @param options.jwtPayloadFields Additional fields to include in the JWT payload when creating the verifiable credential in jwt format.
+     * @returns The created verifiable credential and its token.
+     * @throws NotFoundError if the id can not be resolved.
+     */
+    verifiableCredentialCreate(verificationMethodId: string, id: string | undefined, subject: IJsonLdNodeObject, options?: {
+        revocationIndex?: number;
+        expirationDate?: Date;
+        jwtHeaderFields?: {
+            [id: string]: string;
+        };
+        jwtPayloadFields?: {
+            [id: string]: string;
+        };
+    }): Promise<{
+        verifiableCredential: IDidVerifiableCredential;
+        jwt: string;
+    }>;
+    /**
+     * Verify a verifiable credential is valid.
+     * @param credential The credential to verify.
+     * @returns The credential stored in the jwt and the revocation status.
+     */
+    verifiableCredentialVerify(credential: string | IDidVerifiableCredential): Promise<{
+        revoked: boolean;
+        verifiableCredential?: IDidVerifiableCredential;
+    }>;
+    /**
+     * Revoke verifiable credential.
+     * @param issuerId The id of the document to update the revocation list for.
+     * @param credentialIndex The revocation bitmap index to revoke.
+     * @returns A promise that resolves when the credential has been revoked.
+     */
+    verifiableCredentialRevoke(issuerId: string, credentialIndex: number): Promise<void>;
+    /**
+     * Unrevoke verifiable credential.
+     * @param issuerId The id of the document to update the revocation list for.
+     * @param credentialIndex The revocation bitmap index to unrevoke.
+     * @returns A promise that resolves when the credential has been unrevoked.
+     */
+    verifiableCredentialUnrevoke(issuerId: string, credentialIndex: number): Promise<void>;
+    /**
+     * Create a verifiable presentation from the supplied verifiable credentials.
+     * @param verificationMethodId The method to associate with the presentation.
+     * @param presentationId The id of the presentation.
+     * @param contexts The contexts for the data stored in the verifiable credential.
+     * @param types The types for the data stored in the verifiable credential.
+     * @param verifiableCredentials The credentials to use for creating the presentation in jwt format.
+     * @param options Additional options for creating the verifiable presentation.
+     * @param options.expirationDate The date the verifiable presentation is valid until.
+     * @param options.jwtHeaderFields Additional fields to include in the JWT header when creating the verifiable presentation in jwt format.
+     * @param options.jwtPayloadFields Additional fields to include in the JWT payload when creating the verifiable presentation in jwt format.
+     * @returns The created verifiable presentation and its token.
+     * @throws NotFoundError if the id can not be resolved.
+     */
+    verifiablePresentationCreate(verificationMethodId: string, presentationId: string | undefined, contexts: IJsonLdContextDefinitionRoot | undefined, types: string | string[] | undefined, verifiableCredentials: (string | IDidVerifiableCredential)[], options?: {
+        expirationDate?: Date;
+        jwtHeaderFields?: {
+            [id: string]: string;
+        };
+        jwtPayloadFields?: {
+            [id: string]: string;
+        };
+    }): Promise<{
+        verifiablePresentation: IDidVerifiablePresentation;
+        jwt: string;
+    }>;
+    /**
+     * Verify a verifiable presentation is valid.
+     * @param presentation The presentation to verify.
+     * @returns The presentation stored in the jwt and the revocation status.
+     */
+    verifiablePresentationVerify(presentation: string | IDidVerifiablePresentation): Promise<{
+        revoked: boolean;
+        verifiablePresentation?: IDidVerifiablePresentation;
+        issuers?: IDidDocument[];
+    }>;
+    /**
+     * Create a proof for a document with the specified verification method.
+     * @param verificationMethodId The verification method id to use.
+     * @param proofType The type of proof to create.
+     * @param unsecureDocument The unsecure document to create the proof for.
+     * @returns The proof.
+     */
+    proofCreate(verificationMethodId: string, proofType: ProofTypes, unsecureDocument: IJsonLdNodeObject): Promise<IProof>;
+    /**
+     * Verify proof for a document with the specified verification method.
+     * @param document The document to verify.
+     * @param proof The proof to verify.
+     * @returns True if the proof is verified.
+     */
+    proofVerify(document: IJsonLdNodeObject, proof: IProof): Promise<boolean>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./identityRestClient.js";
+export * from "./identityProfileRestClient.js";
+export * from "./identityResolverRestClient.js";

package/docs/examples.md

@@ -0,0 +1,175 @@
+# Identity REST Client Examples
+
+Use these examples to call identity REST endpoints from applications that need document lifecycle, credential, and profile operations.
+
+## IdentityRestClient
+
+```typescript
+import { IdentityRestClient } from '@3sixty/identity-rest-client';
+
+const client = new IdentityRestClient({
+  endpoint: 'http://localhost:8080'
+});
+
+const className = client.className();
+const createdDocument = await client.identityCreate('iota');
+
+await client.identityRemove(createdDocument.id);
+
+console.log(className); // IdentityRestClient
+console.log(createdDocument.id); // did:iota:tst:0x...
+```
+
+```typescript
+import { IdentityRestClient } from '@3sixty/identity-rest-client';
+import { DidVerificationMethodType, ProofTypes } from '@3sixty/standards-w3c-did';
+
+const client = new IdentityRestClient({
+  endpoint: 'http://localhost:8080'
+});
+
+const did = 'did:iota:tst:0x1234abcd';
+
+const verificationMethod = await client.verificationMethodCreate(
+  did,
+  DidVerificationMethodType.VerificationMethod,
+  'signing-key'
+);
+
+await client.verificationMethodRemove(verificationMethod.id);
+
+const service = await client.serviceCreate(
+  did,
+  'linked-domain',
+  'LinkedDomains',
+  'https://example.org'
+);
+
+await client.serviceRemove(service.id);
+
+const credentialCreateResult = await client.verifiableCredentialCreate(
+  `${did}#signing-key`,
+  'urn:uuid:credential-001',
+  {
+    id: 'did:iota:tst:0x5678efab',
+    name: 'Alice'
+  },
+  {
+    revocationIndex: 2
+  }
+);
+
+const credentialVerificationResult = await client.verifiableCredentialVerify(
+  credentialCreateResult.jwt
+);
+
+await client.verifiableCredentialRevoke(did, 2);
+await client.verifiableCredentialUnrevoke(did, 2);
+
+const presentationCreateResult = await client.verifiablePresentationCreate(
+  `${did}#signing-key`,
+  'urn:uuid:presentation-001',
+  ['https://www.w3.org/2018/credentials/v1'],
+  ['VerifiablePresentation'],
+  [credentialCreateResult.jwt]
+);
+
+const presentationVerificationResult = await client.verifiablePresentationVerify(
+  presentationCreateResult.jwt
+);
+
+const proof = await client.proofCreate(`${did}#signing-key`, ProofTypes.DataIntegrityProof, {
+  id: 'urn:example:doc-1',
+  name: 'Sample'
+});
+
+const proofVerified = await client.proofVerify(
+  {
+    id: 'urn:example:doc-1',
+    name: 'Sample'
+  },
+  proof
+);
+
+console.log(credentialVerificationResult.revoked); // false
+console.log(presentationVerificationResult.revoked); // false
+console.log(proofVerified); // true
+```
+
+## IdentityProfileRestClient
+
+```typescript
+import { IdentityProfileRestClient } from '@3sixty/identity-rest-client';
+
+interface PublicProfile {
+  displayName: string;
+  website: string;
+}
+
+interface PrivateProfile {
+  contactEmail: string;
+}
+
+const profileClient = new IdentityProfileRestClient<PublicProfile, PrivateProfile>({
+  endpoint: 'http://localhost:8080'
+});
+
+const className = profileClient.className();
+
+await profileClient.create(
+  {
+    displayName: 'Alice',
+    website: 'https://example.org'
+  },
+  {
+    contactEmail: 'alice@example.org'
+  }
+);
+
+const profile = await profileClient.get(['displayName'], ['contactEmail']);
+const publicProfile = await profileClient.getPublic(profile.identity, ['displayName']);
+
+await profileClient.update(
+  {
+    displayName: 'Alice Doe',
+    website: 'https://example.org'
+  },
+  {
+    contactEmail: 'alice.doe@example.org'
+  }
+);
+
+const profileList = await profileClient.list(
+  [
+    {
+      propertyName: 'displayName',
+      propertyValue: 'Alice Doe'
+    }
+  ],
+  ['displayName'],
+  undefined,
+  10
+);
+
+await profileClient.remove();
+
+console.log(className); // IdentityProfileRestClient
+console.log(publicProfile.displayName); // Alice
+console.log(profileList.items.length); // 1
+```
+
+## IdentityResolverRestClient
+
+```typescript
+import { IdentityResolverRestClient } from '@3sixty/identity-rest-client';
+
+const resolverClient = new IdentityResolverRestClient({
+  endpoint: 'http://localhost:8080'
+});
+
+const className = resolverClient.className();
+const didDocument = await resolverClient.identityResolve('did:iota:tst:0x1234abcd');
+
+console.log(className); // IdentityResolverRestClient
+console.log(didDocument.id); // did:iota:tst:0x1234abcd
+```