Merge pull request #3072 from XRPLF/js-credentials-issuer-tutorial

Tutorial [JS]: Build a Credential Issuer Service

Author: amarantha-k

_code-samples/issue-credentials/js/.env

@@ -0,0 +1,2 @@
+ISSUER_ACCOUNT_SEED=<your-seed-goes-here>
+PORT=3005

_code-samples/issue-credentials/js/README.md

@@ -0,0 +1,12 @@
+# Credential Issuing Service - Python sample code
+
+This code implements an HTTP API that issues credentials on the XRPL on request.
+
+Quick install & usage:
+
+```sh
+npm install
+node issuer_service.js
+```
+
+For more detail, see the full tutorial for [How to build a service that issues credentials on the XRP Ledger](https://xrpl.org/docs/tutorials/javascript/build-apps/credential-issuing-service).

_code-samples/issue-credentials/js/accept_credential.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import dotenv from "dotenv";
+import inquirer from "inquirer";
+import { Client, Wallet } from "xrpl";
+import { lookUpCredentials } from "./look_up_credentials.js";
+import { hexToString } from "@xrplf/isomorphic/dist/utils/index.js";
+
+const XRPL_SERVER = "wss://s.devnet.rippletest.net:51233"
+
+dotenv.config();
+
+async function initWallet() {
+  let seed = process.env.SUBJECT_ACCOUNT_SEED;
+  if (!seed) {
+    const { seedInput } = await inquirer.prompt([
+      {
+        type: "password",
+        name: "seedInput",
+        message: "Subject account seed:",
+        validate: (input) => (input ? true : "Please specify the subject's master seed"),
+      },
+    ]);
+    seed = seedInput;
+  }
+
+  return Wallet.fromSeed(seed);
+}
+
+async function main() {
+  const client = new Client(XRPL_SERVER);
+  await client.connect();    
+
+  const wallet = await initWallet();
+
+  const pendingCredentials = await lookUpCredentials(
+    client,
+    "",
+    wallet.address,
+    "no"
+  );
+
+  const choices = pendingCredentials.map((cred, i) => ({
+    name: `${i+1}) '${hexToString(cred.CredentialType)}' issued by ${cred.Issuer}`,
+    value: i,
+  }));
+  choices.unshift({ name: "0) No, quit.", value: -1 });
+
+  const { selectedIndex } = await inquirer.prompt([
+    {
+      type: "list",
+      name: "selectedIndex",
+      message: "Accept a credential?",
+      choices,
+    },
+  ]);
+
+  if (selectedIndex === -1) {
+    process.exit(0);
+  }
+
+  const chosenCred = pendingCredentials[selectedIndex];
+  const tx = {
+    TransactionType: "CredentialAccept",
+    Account: wallet.address,
+    CredentialType: chosenCred.CredentialType,
+    Issuer: chosenCred.Issuer,
+  };
+
+  console.log("Submitting transaction:", tx);
+  const response = await client.submit(tx, { autofill: true, wallet });
+  console.log("Response:", response);
+
+  await client.disconnect();
+}
+
+main().catch((err) => {
+  console.error("❌ Error:", err.message);
+  process.exit(1);
+})
+

_code-samples/issue-credentials/js/credential.js

@@ -0,0 +1,138 @@
+import {
+  isoTimeToRippleTime,
+  rippleTimeToISOTime,
+  isValidClassicAddress,
+} from "xrpl";
+import { stringToHex, hexToString } from "@xrplf/isomorphic/dist/utils/index.js";
+
+import { ValueError } from "./errors.js";
+
+// Regex constants
+const CREDENTIAL_REGEX = /^[A-Za-z0-9_.-]{1,128}$/;
+const URI_REGEX = /^[A-Za-z0-9\-._~:/?#\[\]@!$&'()*+,;=%]{1,256}$/;
+
+/**
+ * Validate credential request.
+ * This function performs parameter validation. Validated fields:
+ *   - subject (required): the subject of the credential, as a classic address
+ *   - credential (required): the credential type, in human-readable (ASCII) chars
+ *   - uri (optional): URI of the credential in human-readable (ASCII) chars
+ *   - expiration (optional): time when the credential expires (displayed as an ISO 8601 format string in JSON)
+ */
+export function validateCredentialRequest({ subject, credential, uri, expiration }) {
+  // Validate subject
+  if (typeof subject !== "string") {
+    throw new ValueError("Must provide a string 'subject' field");
+  }
+  if (!isValidClassicAddress(subject)) {
+    throw new ValueError(`subject not valid address: '${subject}'`);
+  }
+
+  // Validate credential
+  if (typeof credential !== "string") {
+    throw new ValueError("Must provide a string 'credential' field");
+  }
+  if (!CREDENTIAL_REGEX.test(credential)) {
+    /**
+     * Checks if the specified credential type is one that this service issues.
+     * XRPL credential types can be any binary data; this service issues
+     * any credential that can be encoded from the following ASCII chars:
+     * alphanumeric characters, underscore, period, and dash. (min length 1, max 128)
+     *
+     * You might want to further limit the credential types, depending on your
+     * use case; for example, you might only issue one specific credential type.
+     */
+    throw new ValueError(`credential not allowed: '${credential}'.`);
+  }
+
+  /*
+  (Optional) Checks if the specified URI is acceptable for this service.
+  
+  XRPL Credentials' URI values can be any binary data; this service
+  adds any user-requested URI to a Credential as long as the URI
+  can be encoded from the characters usually allowed in URIs, namely
+  the following ASCII chars:
+
+    alphanumeric characters (upper and lower case)
+    the following symbols: -._~:/?#[]@!$&'()*+,;=%
+    (minimum length 1 and max length 256 chars)
+
+  You might want to instead define your own URI and attach it to the
+  Credential regardless of user input, or you might want to verify that the
+  URI points to a valid Verifiable Credential document that matches the user.
+  */
+  if (uri !== undefined) {
+    if (typeof uri !== "string" || !URI_REGEX.test(uri)) {
+      throw new ValueError(`URI isn't valid: ${uri}`);
+    }
+  }
+
+  // Validate and parse expiration
+  let parsedExpiration;
+  if (expiration !== undefined) {
+    if (typeof expiration !== "string") {
+      throw new ValueError(`Unsupported expiration format: ${typeof expiration}`);
+    }
+    parsedExpiration = new Date(expiration);
+    if (isNaN(parsedExpiration.getTime())) {
+      throw new ValueError(`Invalid expiration date: ${expiration}`);
+    }
+  }
+
+  return {
+    subject,
+    credential,
+    uri,
+    expiration: parsedExpiration,
+  };
+}
+
+// Convert an XRPL ledger entry into a usable credential object
+export function credentialFromXrpl(entry) {
+  const { Subject, CredentialType, URI, Expiration, Flags } = entry;
+  return {
+    subject: Subject,
+    credential: hexToString(CredentialType),
+    uri: URI ? hexToString(URI) : undefined,
+    expiration: Expiration ? rippleTimeToISOTime(Expiration) : undefined,
+    accepted: Boolean(Flags & 0x00010000), // lsfAccepted
+  };
+}
+
+// Convert to an object in a format closer to the XRP Ledger representation
+export function credentialToXrpl(cred) {
+   // Credential type and URI are hexadecimal;
+   // Expiration, if present, is in seconds since the Ripple Epoch.
+  return {
+    subject: cred.subject,
+    credential: stringToHex(cred.credential),
+    uri: cred.uri ? stringToHex(cred.uri) : undefined,
+    expiration: cred.expiration
+      ? isoTimeToRippleTime(cred.expiration)
+      : undefined,
+  };
+}
+
+
+export function verifyDocuments({ documents }) {
+ /**
+  * This is where you would check the user's documents to see if you
+  * should issue the requested Credential to them.
+  * Depending on the type of credentials your service needs, you might
+  * need to implement different types of checks here.
+  */
+  if (typeof documents !== "object" || Object.keys(documents).length === 0) {
+    throw new ValueError("you must provide a non-empty 'documents' field");
+  }
+
+  // As a placeholder, this example checks that the documents field
+  // contains a string field named "reason" containing the word "please".
+  const reason = documents.reason;
+  if (typeof reason !== "string") {
+    throw new ValueError("documents must contain a 'reason' string");
+  }
+
+  if (!reason.toLowerCase().includes("please")) {
+    throw new ValueError("reason must include 'please'");
+  }
+}

_code-samples/issue-credentials/js/errors.js

@@ -0,0 +1,17 @@
+export class ValueError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ValueError";
+    this.status = 400;
+    this.type = "badRequest";
+  }
+}
+
+export class XRPLTxError extends Error {
+  constructor(xrplResponse, status = 400) {
+    super("XRPL transaction failed");
+    this.name = "XRPLTxError";
+    this.status = status;
+    this.body = xrplResponse.result;
+  }
+}