Data Access Patterns

Defined process of accessing data in permission protocol by a consumer utilizing dataRef in a consent record for secure access of supplier provided data according to consent.

DataRef driven Access Pattern

There are two ways to access data from supplier, IPFS encrypted and Signature Gated mode

Chossing Correct Mode

• dataRef starts with ipfs:// ⇒ IPFS Encrypted Mode

• dataRef starts with http:// or https:// ⇒ API Signature-Gated Mode

---

1. Public Access Mode (disclosed: true)

Condition: When the consent record contains { disclosed: true, dataRef: "..." }

Behavior:

• Data is publicly accessible without any cryptographic protection

• No EIP-712 signatures required

• No ECDH encryption/decryption needed

• Consumer can directly fetch data using the dataRef URI

• Suitable for non-sensitive, publicly shareable datasets

Example Consent Record:

{
  agreementId: "0x...",
  supplier: "did:pkh:0xSUPPLIER",
  consumer: "did:pkh:0xCONSUMER",
  disclosed: true, // ← Public access flag
  dataRef: "ipfs://bafybeipublicdata..."
  ....
}

---

2. Restricted Access Mode (disclosed: false)

When disclosed: false (or undefined), the protocol uses secure access based on dataRef scheme:

A. Signature Gated Api Mode

Consumer Flow:

1. Sign EIP-712 ConsentRecord structure containing:

   • supplier: Supplier's blockchain address

   • agreementContract: Agreement contract address

   • agreementId: The specific agreement identifier

2. Attach signature to API request headers:

   • X-Signature: EIP-712 signature

   • X-Consent-ID: The onchain id of associated consent record

Supplier Flow:

1. Extract signature and identifiers from request headers

2. Recover signer from EIP-712 signature

3. Verify:

   • Signer matches consent consumer

4. Serve data if verification passes, otherwise reject

Supplier and Consumer doesn't need to have a DID Document when using signature based verification

Consumer Code:

import { IPublicClient, IWalletClient } from "@permission-io/protocol-sdk";
import { createDataConsumerSignature } from "@permission-io/protocol-sdk/data";

const walletClient = // Consumer Wallet for signature creation

const sig = await createDataConsumerSignature(
  { consentRecordId: BigInt(consentId) },
  {
    wallet: walletClient,
    public: publicClient,
  },
);

Supplier Code:

import { verifyDataConsumerSignature } from "@permission-io/protocol-sdk/data";

const isValid = await verifyDataConsumerSignature(
  {
    consentRecordId: BigInt(consentId),
    signature: signatureHex as Hex,
  },
  {
    public: publicClient as IPublicClient,
  },
);

if(isValid)
  // Allow data access
else
  // return 401 status

Api Request Example:

const signature = "0x..."

const response = await fetch("https://api.yourservice.com/data", {
  headers: {
    "x-signature": signature,
    "x-consent-id": "1"
  },
});

Api Middleware Example

import { parseRequestHeaders} from "@permission-io/protocol-sdk/data";

middleware((request)=>{
    const parsed = parseRequestHeaders(request.headers)
    if(parsed){
        const {signature, consentId} = parsed;
        // Logic to return data    
    }else {
        throw UnauthorizedException()
    }
})

B. IPFS Encrypted Mode

Consumer and Supplier must have DID Documents so public keys can be extracted for encryption

Condition: open: false AND dataRef.startsWith("ipfs://")

Supplier Flow:

1. Extract consumer's public key from DID Document (keyAgreement section)

2. Generate ECDH shared secret: secp256k1.getSharedSecret(supplierPrivKey, consumerPubKey)

3. Encrypt data with AES-256-GCM using SHA256(sharedSecret) as key

4. Upload envelope JSON to IPFS: { ciphertext, iv, authTag }

5. Set dataRef to the IPFS CID

Consumer Flow:

1. Fetch encrypted envelope from IPFS using the CID

2. Extract supplier's public key from DID Document

3. Generate same ECDH shared secret: secp256k1.getSharedSecret(consumerPrivKey, supplierPubKey)

4. Decrypt using AES-256-GCM with authenticated verification

Public key of the DID subject can be found in DID document under keyAgreement

Code for Supplier Encryption:

import { fetchPublicKey, encryptData } from "@permission-io/protocol-sdk/data";

// Private key of data supplier/controller
const supplierPrivateKey = "0x..."

const dataToEncrypt = "Hellow World!"

const consumerPublicKey = await fetchPublicKey({
  did: consumerDid,
  clients: { public: publicClient },
});

// Encrypt the data
const encrypted= encryptData({
  data: dataToEncrypt,
  consumerPublicKey,
  supplierPrivateKey,
});

const cid = await publishToIPFS(JSON.stringify(encrypted));
// The generated cid will be put in dataRef inside consent record
// e.g ipfs://bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4

Code for Consumer Decryption:

import { fetchPublicKey, decryptData } from "@permission-io/protocol-sdk/data";

// Private key of data consumer
const consumerPrivateKey = "0x..."

const dataToDecrypt = {
  cipherText: "0x0..",
  iv: "0x.."
}

const supplierPublicKey = await fetchPublicKey({
  did: supplierDid,
  clients: { public: publicClient },
});

// Decrypt the data
const decrypted = decryptData({
  ciphertext: dataToDecrypt.ciphertext,
  iv: dataToDecrypt.iv,
  supplierPublicKey,
  consumerPrivateKey,
});

Need to fetch file data from IPFS E.g https://docs.ipfs.tech/quickstart/retrieve/#ipfs-retrieval-methods