Node.js Passport strategy using decentralised identifiers

Description

This repository consists of a Node.js Password Strategy which authenticates based on roles defined in Energy Web Foundation Ethereum namespace.

Sequence diagram

sequenceDiagram
autonumber
    participant C as Client
    participant LS as LoginStrategy
    participant CV as ClaimVerifier
    participant PV as ProofVerifier
    participant CR as CredentialResolver
    participant IV as IssuerVerification
    participant SH as SSI-HUB
    participant IPFS
    participant DR as DomainReader
rect rgb(200, 255, 255)
    Note right of C: Initialisation
    C->>C: Client sets the login strategy options and initialises LoginStrategy
    Note right of C: Validation Call
    C->>LS: LoginStrategy.validate(token, payload)
end
rect rgb(255, 220, 255)
    Note right of LS: Signature and role validation
    LS->>PV: Authenticate token issuer
    LS ->> CR : Fetches role credentials {by DID}
    alt Fetch DID Document from SSI-HUB if cacheClient initialised
      CR->>SH: Fetch cached DID Document
      loop For each serviceEndpoint
        CR->>IPFS : Resolve credential from IPFS
      end
    else Resolve DID Document from Blockchain
      loop For each serviceEndpoint
        CR->>IPFS : Resolve credential from IPFS
      end
    end
    CR-->>LS: returns credentials
end
rect rgb(255, 255, 220)
    Note right of CV: Issuer verification
    LS->>LS: Initialise ClaimVerifier <br> {RoleEIP191Jwt[], getRoleDefinition, IssuerVerification}
    LS->>CV: ClaimVerifier.getVerifiedRoles(userCredentials, getRoleDefinition, issuerVerification) 
    loop For each claims
      alt Fetch role definition from SSI-HUB if cacheClient initialised
        CV->>SH: Request role definition
        SH-->>CV: return role definition
      else Fetch role definition from DomainReader
        CV->>DR: Request role definition
        DR-->>CV: return role definition
      end
      CV->>IV: IssuerVerification.verifyIssuer() <br> verifies issuers in the hierarchy along with their revocation status and expiration
      IV-->>CV : Returns VerificationResult
    end
    CV-->>LS: returns verified roles
    LS->>LS: checks if accepted roles are in verified roles
end

LoginStrategy

This class provides implementation for verification of issued roles credential. The verification ensures that the credentials were issued by the authorised issuers and are neither revoked nor expired. LoginStrategy can be configured to authenticate only EnergyWeb Roles.

To know more about LoginStrategy initialization check How to configure LoginStrategy.

Example LoginStrategy Initialisation

import {
  DidStore,
  DomainReader,
  ethrReg,
  EWC_CHAIN_ID,
  EWC_ADDRESS_1056,
  EWC_ENS_REGISTRY_ADDRESS,
  EWC_RESOLVER_V2_ADDRESS,
  LoginStrategy,
  Methods,
  RegistrySettings,
  RoleCredentialResolver,
  RoleIssuerResolver,
  RoleRevokerResolver,
  ResolverContractType,
  VOLTA_CHAIN_ID,
  VOLTA_ERC_1056_ADDRESS,
  VOLTA_ENS_REGISTRY_ADDRESS,
  VOLTA_RESOLVER_V2_ADDRESS,
} from 'passport-did-auth';
import { providers } from 'ethers';
import { verifyCredential } from 'didkit-wasm-node';
import passport from 'passport';
import { Strategy, ExtractJwt } from 'passport-jwt';

const jwtSecret = 'secret';
// Use contract addresses specific to the chain you are connected to
const didRegistryAddress = VOLTA_ERC_1056_ADDRESS;
const ensRegistryAddress = VOLTA_ENS_REGISTRY_ADDRESS;
const ensResolverAddress = VOLTA_RESOLVER_V2_ADDRESS;

const jwtOptions = {
  jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
  secretOrKey: jwtSecret,
};
const LOGIN_STRATEGY = 'login';
const provider = new providers.JsonRpcProvider(rpcUrl);

const loginStrategyOptions: LoginStrategyOptions = {
  jwtSecret: 'private_pem_secret',
  rpcUrl: `http://localhost:8544`,
  name: LOGIN_STRATEGY,
  didContractAddress: didRegistryAddress,
  ensRegistryAddress: ensRegistryAddress,
  cacheServerUrl: 'http://12.34.56.1111/',
  ...other configurations,
};

const ipfsConfig: IpfsConfig = {
  ...some ipfsConfig
};
const didStore = new DidStore(ipfsConfig);
const domainReader = new DomainReader({
  ensRegistryAddress: ensRegistryAddress,
  provider: provider,
});
domainReader.addKnownResolver({
  chainId: VOLTA_CHAIN_ID,
  address: ensResolverAddress,
  type: ResolverContractType.RoleDefinitionResolver_v2,
});

const registrySettings: RegistrySettings = {
  abi: ethrReg.abi,
  address: didRegistryAddress,
  method: Methods.Erc1056,
};
const issuerResolver = new RoleIssuerResolver(domainReader);
const revokerResolver = new RoleRevokerResolver(domainReader);
const credentialResolver = new RoleCredentialResolver(
  provider,
  registrySettings,
  didStore
);

const loginStrategy = new LoginStrategy(
  loginStrategyOptions,
  issuerResolver,
  revokerResolver,
  credentialResolver,
  verifyCredential
);

passport.use(loginStrategy);
passport.use(
  new Strategy(jwtOptions, (_payload, _done) => {
    return _done(null, _payload);
  })
);

Login with EIP191 Jwt token (Sign-in with Ethereum)

const token = 'askjad...'; // EIP191 signed JWT
const payload = {
  iss: `did:ethr:volta:0x1224....`,
  claimData: {
    blockNumber: 4242,
  },
  sub: '',
};

await loginStrategy.validate(token, payload);

where the iss is DID of the subject and blockNumber is block number (or height) of the most recently mined block.

Login with SIWE (Sign-in with Ethereum)

While login with SIWE, one must initialise LoginStrategy with siweMessageUri (one of the attribute of LoginStrategyOptions).

const token = '0xdc35c7f8ba2720df052e0092556456127f00f7707eaa8e3bbff7e56774e7f2e05a093cfc9e02964c33d86e8e066e221b7d153d27e5a2e97ccd5ca7d3f2ce06cb1b'; // EIP712 signature

const sampleSiwePayload: Partial<SiweMessagePayload> = {
  domain: 'login.xyz',
  address: '0x9D85ca56217D2bb651b00f15e694EB7E713637D4',
  statement: 'Sign-In With Ethereum Example Statement',
  uri: 'https://login.xyz',
  version: '1',
  nonce: 'bTyXgcQxn2htgkjJn',
  issuedAt: '2022-01-27T17:09:38.578Z',
  chainId: 1,
  expirationTime: '2100-01-07T14:31:43.952Z',
};

await loginStrategy.validate(token, payload);

Read more about Sign-In with Ethereum here

Prerequisities

npm version 7+
nodejs version 16.10+

Building the Passport Strategy

npm run build

Example applications

Example server applications which demonstrate the use of the passport strategy can be found in this repository. The repository also contains client examples which leverage the iam-client-lib to interact with the server applications.

energywebfoundation / passport-did-auth

readme