@autonomys/auto-id NPM

Autonomys Auto ID SDK

Overview

The Autonomys Auto ID SDK (@autonomys/auto-id) provides functionalities for managing certificates, authenticating users, and integrating Zero-Knowledge Proofs (ZKPs) on the Autonomys Network. It enables developers to:

Authenticate Users: Verify user identities using their Auto IDs.
Manage Certificates: Create, issue, and handle x509 certificates associated with Auto IDs.
Integrate Zero-Knowledge Proofs (ZKPs): Utilize ZKP claims for enhanced privacy and authentication.

Features

Certificate Management: Create and manage x509 certificates linked to Auto IDs.
Zero-Knowledge Proof Integration: Implement privacy-preserving claims using ZKPs.
User Authentication: Authenticate users through their Auto IDs and certificates.
TypeScript Support: Fully typed for enhanced developer experience.
Blockchain Interaction: Interact with the Autonomys Network without dealing with low-level blockchain complexities.

Installation

Install the package via npm or yarn:

# Using npm
npm install @autonomys/auto-id

# Using yarn
yarn add @autonomys/auto-id

Getting Started

Prerequisites

Node.js (version 14 or higher)
TypeScript (recommended for development)
Familiarity with async/await and promise handling in JavaScript/TypeScript.
@autonomys/auto-utils package installed (for utility functions and API activation).

Importing the SDK

You can import specific functions from the package as needed:

import {
  authenticateAutoIdUser,
  selfIssueCertificate,
  issueCertificate,
  createAndSignCSR,
  ReclaimZKPClaim,
  buildReclaimRequest,
} from '@autonomys/auto-id'

Usage Examples

Below are examples demonstrating how to use the functions provided by @autonomys/auto-id.

1. User Authentication

Authenticate a User with Auto ID

Verify a user's identity using their Auto ID, challenge message, and signature.

import { authenticateAutoIdUser } from '@autonomys/auto-id';
import { activate } from '@autonomys/auto-utils';

(async () => {
  // Activate the network API
  const api = await activate();

  // User's Auto ID
  const autoId = 'user-auto-id'; // Replace with the user's Auto ID

  // Challenge message that the user needs to sign
  const challengeMessage = 'Please sign this message to authenticate.';
  const challenge = new TextEncoder().encode(challengeMessage);

  // Assume the user provides the signature
  const signature = new Uint8Array([...]); // User's signature as Uint8Array

  // Authenticate the user
  const isAuthenticated = await authenticateAutoIdUser(api, autoId, challenge, signature);

  if (isAuthenticated) {
    console.log('User authenticated successfully.');
  } else {
    console.log('Authentication failed.');
  }

  // Disconnect when done
  await api.disconnect();
})();

Parameters:

api (ApiPromise): Connected API instance.
autoId (string): User's Auto ID.
challenge (BufferSource): The challenge message.
signature (BufferSource): User's signature over the challenge.

Returns:

A Promise that resolves to true if authentication is successful, or false otherwise.

2. Certificate Management

Self-Issuing a Certificate

Generate a self-signed x509 certificate for an Auto ID.

import { selfIssueCertificate } from '@autonomys/auto-id'
import { generateKeyPair } from '@autonomys/auto-utils'

;(async () => {
  // Generate a key pair
  const keyPair = await generateKeyPair()

  // Subject name for the certificate
  const subjectName = 'CN=User Name' // Replace with appropriate subject

  // Generate a self-signed certificate
  const certificate = await selfIssueCertificate(subjectName, keyPair)

  console.log('Certificate created:', certificate)

  // Optionally, save the certificate to a file or store it securely
})()

Parameters:

subjectName (string): The subject name for the certificate (e.g., 'CN=User Name').
keyPair (CryptoKeyPair): The key pair for the certificate.

Returns:

A Promise that resolves to the generated X509Certificate.

Issuing a Certificate

Issue a certificate based on a Certificate Signing Request (CSR).

import { createAndSignCSR, issueCertificate, selfIssueCertificate } from '@autonomys/auto-id'
import { generateKeyPair } from '@autonomys/auto-utils'

;(async () => {
  // Generate key pairs for the subject and issuer
  const subjectKeyPair = await generateKeyPair()
  const issuerKeyPair = await generateKeyPair()

  // Subject and issuer names
  const subjectName = 'CN=Subject Name'
  const issuerName = 'CN=Issuer Name'

  // Create issuer's self-signed certificate
  const issuerCertificate = await selfIssueCertificate(issuerName, issuerKeyPair)

  // Create and sign CSR for the subject
  const csr = await createAndSignCSR(subjectName, subjectKeyPair)

  // Issue certificate for the subject using issuer's certificate and key pair
  const issuedCertificate = await issueCertificate(csr, {
    certificate: issuerCertificate,
    keyPair: issuerKeyPair,
  })

  console.log('Issued Certificate:', issuedCertificate)
})()

Parameters for issueCertificate:

csr (Pkcs10CertificateRequest): The CSR from the subject.
issuerCertificateData (CertificateData): Contains the issuer's certificate and key pair.
validityPeriodDays (number, optional): Certificate validity period in days.

Returns:

A Promise that resolves to the issued X509Certificate.

3. Zero-Knowledge Proofs (ZKPs)

Creating a ZKP Claim

Generate a Zero-Knowledge Proof claim using the Reclaim protocol.

import { ReclaimZKPClaim, buildReclaimRequest } from '@autonomys/auto-id'
import { Proof } from '@reclaimprotocol/js-sdk'

;(async () => {
  // Application ID from Reclaim Protocol
  const appId = 'your-app-id' // Replace with your actual app ID

  // Supported claim hash (e.g., 'GoogleEmail')
  const claimType = 'GoogleEmail'

  // Build a Reclaim proof request
  const reclaimRequest = await buildReclaimRequest(appId, claimType)

  // Start the Reclaim session and get the proof (this may involve user interaction)
  const proofs = await reclaimRequest.startSession({
    onSuccessCallback: (proofs) => {
      // Handle the proofs
      const proof = proofs[0]

      // Create a ZKP claim
      const zkpClaim = new ReclaimZKPClaim('your-service-id', proof)

      // Verify the proof validity
      zkpClaim.verify().then((isValid) => {
        if (isValid) {
          console.log('ZKP Claim is valid:', zkpClaim)
        } else {
          console.log('ZKP Claim verification failed.')
        }
      })
    },
    onFailureCallback: (error) => {
      console.error('Reclaim session failed:', error)
    },
  })
})()

Parameters:

serviceId (string): An identifier for your service.
proof (Proof): The proof object obtained from the Reclaim protocol.

Returns:

A Promise that resolves when the ZKP claim has been processed.

API Reference

Functions

`authenticateAutoIdUser(api: ApiPromise, autoId: string, challenge: BufferSource, signature: BufferSource): Promise<boolean>`

Authenticate a user using their Auto ID.

`selfIssueCertificate(subjectName: string, keyPair: CryptoKeyPair, validityPeriodDays?: number): Promise<X509Certificate>`

Create a self-signed x509 certificate.

`issueCertificate(csr: Pkcs10CertificateRequest, issuerCertificateData: CertificateData, validityPeriodDays?: number): Promise<X509Certificate>`

Issue a certificate based on a CSR.

`createAndSignCSR(subjectName: string, keyPair: CryptoKeyPair): Promise<Pkcs10CertificateRequest>`

Create and sign a Certificate Signing Request.

`buildReclaimRequest(appId: string, claimType: SupportedClaimHashes): Promise<ProofRequest>`

Build a Reclaim proof request for a specific claim type.

Error Handling

Ensure to handle errors appropriately, especially when dealing with network operations and cryptographic functions.

Example:

import { selfIssueCertificate } from '@autonomys/auto-id'
import { generateKeyPair } from '@autonomys/auto-utils'

;(async () => {
  try {
    const keyPair = await generateKeyPair()
    const subjectName = 'CN=User Name'

    const certificate = await selfIssueCertificate(subjectName, keyPair)
    console.log('Certificate created:', certificate)
  } catch (error) {
    console.error('Error creating certificate:', error)
  }
})()

Contributing

We welcome contributions to @autonomys/auto-id! Please follow these guidelines:

Fork the repository on GitHub.

Clone your fork locally:

git clone https://github.com/your-username/auto-sdk.git
cd auto-sdk/packages/auto-id

Install dependencies:
```
yarn install
```
Make your changes and ensure all tests pass:
```
yarn test
```
Commit your changes with clear and descriptive messages.
Push to your fork and create a pull request against the main branch of the original repository.

Code Style

Use TypeScript for all code.
Follow the existing coding conventions.
Run yarn lint to ensure code style consistency.

Testing

Add tests for any new features or bug fixes.
Ensure all existing tests pass.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Additional Resources

Autonomys Academy: Learn more at Autonomys Academy.
Auto-Utils Package: Utility functions used alongside auto-id can be found in @autonomys/auto-utils.