@enbox/agent 0.0.1

package/src/oidc.ts

@@ -0,0 +1,857 @@
+import { Convert, logger, RequireOnly } from '@enbox/common';
+import {
+  Ed25519,
+  EdDsaAlgorithm,
+  JoseHeaderParams,
+  Jwk,
+  Sha256,
+  X25519,
+  CryptoUtils,
+} from '@enbox/crypto';
+import { concatenateUrl } from './utils.js';
+import { xchacha20poly1305 } from '@noble/ciphers/chacha';
+import type { ConnectPermissionRequest } from './connect.js';
+import { DidDocument, DidJwk, PortableDid, type BearerDid } from '@enbox/dids';
+import { DwnDataEncodedRecordsWriteMessage, DwnInterface, DwnPermissionScope, DwnProtocolDefinition } from './types/dwn.js';
+import { AgentPermissionsApi } from './permissions-api.js';
+import type { Web5Agent } from './types/agent.js';
+import { isRecordPermissionScope } from './dwn-api.js';
+import { DwnInterfaceName, DwnMethodName } from '@enbox/dwn-sdk-js';
+
+/**
+ * Sent to an OIDC server to authorize a client. Allows clients
+ * to securely send authorization request parameters directly to
+ * the server via POST. This avoids exposing sensitive data in URLs
+ * and ensures the server validates the request before user interaction.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9126.html | OAuth 2.0 Pushed Authorization Requests}
+ */
+export type PushedAuthRequest = {
+  /** The JWT which contains the {@link Web5ConnectAuthRequest} */
+  request: string;
+};
+
+/**
+ * Sent back by OIDC server in response to {@link PushedAuthRequest}
+ * The server generates a TTL and a unique request_uri. The request_uri can be shared
+ * with the Provider using a link or a QR code along with additional params
+ * to access the url and decrypt the payload.
+ */
+export type PushedAuthResponse = {
+  request_uri: string;
+  expires_in: number;
+};
+
+/**
+ * Used in decentralized apps. The SIOPv2 Auth Request is created by a client relying party (RP)
+ * often a web service or an app who wants to obtain information from a provider
+ * The contents of this are inserted into a JWT inside of the {@link PushedAuthRequest}.
+ * @see {@link https://github.com/TBD54566975/known-customer-credential | TBD OIDC Documentation for SIOPv2 }
+ */
+export type SIOPv2AuthRequest = {
+  /** The DID of the client (RP) */
+  client_id: string;
+
+  /** The scope of the access request (e.g., `openid profile`). */
+  scope: string;
+
+  /** The type of response desired (e.g. `id_token`) */
+  response_type: string;
+
+  /** the URL to which the Identity Provider will post the Authorization Response */
+  redirect_uri: string;
+
+  /** The URI to which the SIOPv2 Authorization Response will be sent (Tim's note: not used with encrypted request JWT)*/
+  response_uri?: string;
+
+  /**
+   * An opaque value used to maintain state between the request and the callback.
+   * Recommended for security to prevent CSRF attacks.
+   */
+  state: string;
+
+  /**
+   * A string value used to associate a client session with an ID token to mitigate replay attacks.
+   * Recommended when requesting ID tokens.
+   */
+  nonce: string;
+
+  /**
+   * The PKCE code challenge.
+   * Required if `code_challenge_method` is used. Enhances security for public clients (e.g., single-page apps,
+   * mobile apps) by requiring an additional verification step during token exchange.
+   */
+  code_challenge?: string;
+
+  /** The method used for the PKCE challenge (typically `S256`). Must be present if `code_challenge` is included. */
+  code_challenge_method?: 'S256';
+
+  /**
+   * An ID token previously issued to the client, passed as a hint about the end-user’s current or past authenticated
+   * session with the client. Can streamline user experience if already logged in.
+   */
+  id_token_hint?: string;
+
+  /** A hint to the authorization server about the login identifier the user might use. Useful for pre-filling login information. */
+  login_hint?: string;
+
+  /** Requested Authentication Context Class Reference values. Specifies the authentication context requirements. */
+  acr_values?: string;
+
+  /** When using a PAR for secure cross device flows we use a "form_post" rather than a "direct_post" */
+  response_mode: 'direct_post';
+
+  /** Used by PFI to request VCs as input to IDV process. If present, `response_type: "vp_token""` MUST also be present */
+  presentation_definition?: any;
+
+  /** A JSON object containing the Verifier metadata values (Tim's note: from TBD KCC Repo) */
+  client_metadata?: {
+    /** Array of strings, each a DID method supported for the subject of ID Token	*/
+    subject_syntax_types_supported: string[];
+    /** Human-readable string name of the client to be presented to the end-user during authorization */
+    client_name?: string;
+    /** URI of a web page providing information about the client */
+    client_uri?: string;
+    /** URI of an image logo for the client */
+    logo_uri?: string;
+    /** Array of strings representing ways to contact people responsible for this client, typically email addresses */
+    contacts?: string[];
+    /** URI that points to a terms of service document for the client */
+    tos_uri?: string;
+    /** URI that points to a privacy policy document */
+    policy_uri?: string;
+  };
+};
+
+/**
+ * An auth request that is compatible with both Web5 Connect and (hopefully, WIP) OIDC SIOPv2
+ * The contents of this are inserted into a JWT inside of the {@link PushedAuthRequest}.
+ */
+export type Web5ConnectAuthRequest = {
+  /** The user friendly name of the client/app to be displayed when prompting end-user with permission requests. */
+  displayName: string;
+
+  /** PermissionGrants that are to be sent to the provider */
+  permissionRequests: ConnectPermissionRequest[];
+} & SIOPv2AuthRequest;
+
+/** The fields for an OIDC SIOPv2 Auth Repsonse */
+export type SIOPv2AuthResponse = {
+  /** Issuer MUST match the value of sub (Applicant's DID) */
+  iss: string;
+  /** Subject Identifier. A locally unique and never reassigned identifier
+   * within the Issuer for the End-User, which is intended to be consumed
+   * by the Client. */
+  sub: string;
+  /** Audience(s) that this ID Token is intended for. It MUST contain the
+   * OAuth 2.0 client_id of the Relying Party as an audience value. */
+  aud: string;
+  /** Time at which the JWT was issued. */
+  iat: number;
+  /** Expiration time on or after which the ID Token MUST NOT be accepted
+   * for processing. */
+  exp: number;
+  /** Time when the End-User authentication occurred. */
+  auth_time?: number;
+  /** b64url encoded nonce used to associate a Client session with an ID Token, and to
+   * mitigate replay attacks. */
+  nonce?: string;
+  /** Custom claims. */
+  [key: string]: any;
+};
+
+/** An auth response that is compatible with both Web5 Connect and (hopefully, WIP) OIDC SIOPv2 */
+export type Web5ConnectAuthResponse = {
+  delegateGrants: DwnDataEncodedRecordsWriteMessage[];
+  delegatePortableDid: PortableDid;
+} & SIOPv2AuthResponse;
+
+/** Represents the different OIDC endpoint types.
+ * 1. `pushedAuthorizationRequest`: client sends {@link PushedAuthRequest} receives {@link PushedAuthResponse}
+ * 2. `authorize`: provider gets the {@link Web5ConnectAuthRequest} JWT that was stored by the PAR
+ * 3. `callback`: provider sends {@link Web5ConnectAuthResponse} to this endpoint
+ * 4. `token`: client gets {@link Web5ConnectAuthResponse} from this endpoint
+ */
+type OidcEndpoint =
+  | 'pushedAuthorizationRequest'
+  | 'authorize'
+  | 'callback'
+  | 'token';
+
+/**
+ * Gets the correct OIDC endpoint out of the {@link OidcEndpoint} options provided.
+ * Handles a trailing slash on baseURL
+ *
+ * @param {Object} options the options object
+ * @param {string} options.baseURL for example `http://foo.com/connect/
+ * @param {OidcEndpoint} options.endpoint the OIDC endpoint desired
+ * @param {string} options.authParam this is the unique id which must be provided when getting the `authorize` endpoint
+ * @param {string} options.tokenParam this is the random state as b64url which must be provided with the `token` endpoint
+ */
+function buildOidcUrl({
+  baseURL,
+  endpoint,
+  authParam,
+  tokenParam,
+}: {
+  baseURL: string;
+  endpoint: OidcEndpoint;
+  authParam?: string;
+  tokenParam?: string;
+}) {
+  switch (endpoint) {
+    /** 1. client sends {@link PushedAuthRequest} & client receives {@link PushedAuthResponse} */
+    case 'pushedAuthorizationRequest':
+      return concatenateUrl(baseURL, 'par');
+    /** 2. provider gets {@link Web5ConnectAuthRequest} */
+    case 'authorize':
+      if (!authParam)
+        throw new Error(
+          `authParam must be providied when building a token URL`
+        );
+      return concatenateUrl(baseURL, `authorize/${authParam}.jwt`);
+    /** 3. provider sends {@link Web5ConnectAuthResponse} */
+    case 'callback':
+      return concatenateUrl(baseURL, `callback`);
+    /**  4. client gets {@link Web5ConnectAuthResponse */
+    case 'token':
+      if (!tokenParam)
+        throw new Error(
+          `tokenParam must be providied when building a token URL`
+        );
+      return concatenateUrl(baseURL, `token/${tokenParam}.jwt`);
+    // TODO: metadata endpoints?
+    default:
+      throw new Error(`No matches for endpoint specified: ${endpoint}`);
+  }
+}
+
+/**
+ * Generates a cryptographically random "code challenge" in
+ * accordance with the RFC 7636 PKCE specification.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7636#section-4.2 | RFC 7636 }
+ */
+async function generateCodeChallenge() {
+  const codeVerifierBytes = CryptoUtils.randomBytes(32);
+  const codeChallengeBytes = await Sha256.digest({ data: codeVerifierBytes });
+  const codeChallengeBase64Url =
+    Convert.uint8Array(codeChallengeBytes).toBase64Url();
+
+  return { codeChallengeBytes, codeChallengeBase64Url };
+}
+
+/** Client creates the {@link Web5ConnectAuthRequest} */
+async function createAuthRequest(
+  options: RequireOnly<
+    Web5ConnectAuthRequest,
+    'client_id' | 'scope' | 'redirect_uri' | 'permissionRequests' | 'displayName'
+  >
+) {
+  // Generate a random state value to associate the authorization request with the response.
+  const stateBytes = CryptoUtils.randomBytes(16);
+
+  // Generate a random nonce value to associate the ID Token with the authorization request.
+  const nonceBytes = CryptoUtils.randomBytes(16);
+
+  const requestObject: Web5ConnectAuthRequest = {
+    ...options,
+    nonce           : Convert.uint8Array(nonceBytes).toBase64Url(),
+    response_type   : 'id_token',
+    response_mode   : 'direct_post',
+    state           : Convert.uint8Array(stateBytes).toBase64Url(),
+    client_metadata : {
+      subject_syntax_types_supported: ['did:dht', 'did:jwk'],
+    },
+  };
+
+  return requestObject;
+}
+
+/** Encrypts the auth request with the key which will be passed through QR code */
+async function encryptAuthRequest({
+  jwt,
+  encryptionKey,
+}: {
+  jwt: string;
+  encryptionKey: Uint8Array;
+}) {
+  const protectedHeader = {
+    alg : 'dir',
+    cty : 'JWT',
+    enc : 'XC20P',
+    typ : 'JWT',
+  };
+  const nonce = CryptoUtils.randomBytes(24);
+  const additionalData = Convert.object(protectedHeader).toUint8Array();
+  const jwtBytes = Convert.string(jwt).toUint8Array();
+  const chacha = xchacha20poly1305(encryptionKey, nonce, additionalData);
+  const ciphertextAndTag = chacha.encrypt(jwtBytes);
+
+  /** The cipher output concatenates the encrypted data and tag
+   * so we need to extract the values for use in the JWE. */
+  const ciphertext = ciphertextAndTag.subarray(0, -16);
+  const authenticationTag = ciphertextAndTag.subarray(-16);
+
+  const compactJwe = [
+    Convert.object(protectedHeader).toBase64Url(),
+    '', // Empty string since there is no wrapped key.
+    Convert.uint8Array(nonce).toBase64Url(),
+    Convert.uint8Array(ciphertext).toBase64Url(),
+    Convert.uint8Array(authenticationTag).toBase64Url(),
+  ].join('.');
+
+  return compactJwe;
+}
+
+/** Create a response object compatible with Web5 Connect and OIDC SIOPv2 */
+async function createResponseObject(
+  options: RequireOnly<
+    Web5ConnectAuthResponse,
+    'iss' | 'sub' | 'aud' | 'delegateGrants' | 'delegatePortableDid'
+  >
+) {
+  const currentTimeInSeconds = Math.floor(Date.now() / 1000);
+
+  const responseObject: Web5ConnectAuthResponse = {
+    ...options,
+    iat : currentTimeInSeconds,
+    exp : currentTimeInSeconds + 600, // Expires in 10 minutes.
+  };
+
+  return responseObject;
+}
+
+/** sign an object and transform it into a jwt using a did */
+async function signJwt({
+  did,
+  data,
+}: {
+  did: BearerDid;
+  data: Record<string, unknown>;
+}) {
+  const header = Convert.object({
+    alg : 'EdDSA',
+    kid : did.document.verificationMethod![0].id,
+    typ : 'JWT',
+  }).toBase64Url();
+
+  const payload = Convert.object(data).toBase64Url();
+
+  // signs using ed25519 EdDSA
+  const signer = await did.getSigner();
+  const signature = await signer.sign({
+    data: Convert.string(`${header}.${payload}`).toUint8Array(),
+  });
+
+  const signatureBase64Url = Convert.uint8Array(signature).toBase64Url();
+
+  const jwt = `${header}.${payload}.${signatureBase64Url}`;
+
+  return jwt;
+}
+
+/** Take the decrypted JWT and verify it was signed by its public DID. Return parsed object. */
+async function verifyJwt({ jwt }: { jwt: string }) {
+  const [headerB64U, payloadB64U, signatureB64U] = jwt.split('.');
+
+  // Convert the header back to a JOSE object and verify that the 'kid' header value is present.
+  const header: JoseHeaderParams = Convert.base64Url(headerB64U).toObject();
+
+  if (!header.kid)
+    throw new Error(
+      `OIDC: Object could not be verified due to missing 'kid' header value.`
+    );
+
+  // Resolve the Client DID document.
+  const { didDocument } = await DidJwk.resolve(header.kid.split('#')[0]);
+
+  if (!didDocument)
+    throw new Error(
+      'OIDC: Object could not be verified due to Client DID resolution issue.'
+    );
+
+  // Get the public key used to sign the Object from the DID document.
+  const { publicKeyJwk } =
+    didDocument.verificationMethod?.find((method: any) => {
+      return method.id === header.kid;
+    }) ?? {};
+
+  if (!publicKeyJwk)
+    throw new Error(
+      'OIDC: Object could not be verified due to missing public key in DID document.'
+    );
+
+  const EdDsa = new EdDsaAlgorithm();
+  const isValid = await EdDsa.verify({
+    key       : publicKeyJwk,
+    signature : Convert.base64Url(signatureB64U).toUint8Array(),
+    data      : Convert.string(`${headerB64U}.${payloadB64U}`).toUint8Array(),
+  });
+
+  if (!isValid)
+    throw new Error(
+      'OIDC: Object failed verification due to invalid signature.'
+    );
+
+  const object = Convert.base64Url(payloadB64U).toObject();
+
+  return object;
+}
+
+/**
+ * Fetches the {@Web5ConnectAuthRequest} from the authorize endpoint and decrypts it
+ * using the encryption key passed via QR code.
+ */
+const getAuthRequest = async (request_uri: string, encryption_key: string) => {
+  const authRequest = await fetch(request_uri);
+  const jwe = await authRequest.text();
+  const jwt = decryptAuthRequest({
+    jwe,
+    encryption_key,
+  });
+  const web5ConnectAuthRequest = (await verifyJwt({
+    jwt,
+  })) as Web5ConnectAuthRequest;
+
+  return web5ConnectAuthRequest;
+};
+
+/** Take the encrypted JWE, decrypt using the code challenge and return a JWT string which will need to be verified */
+function decryptAuthRequest({
+  jwe,
+  encryption_key,
+}: {
+  jwe: string;
+  encryption_key: string;
+}) {
+  const [
+    protectedHeaderB64U,
+    ,
+    nonceB64U,
+    ciphertextB64U,
+    authenticationTagB64U,
+  ] = jwe.split('.');
+
+  const encryptionKeyBytes = Convert.base64Url(encryption_key).toUint8Array();
+  const protectedHeader = Convert.base64Url(protectedHeaderB64U).toUint8Array();
+  const additionalData = protectedHeader;
+  const nonce = Convert.base64Url(nonceB64U).toUint8Array();
+  const ciphertext = Convert.base64Url(ciphertextB64U).toUint8Array();
+  const authenticationTag = Convert.base64Url(
+    authenticationTagB64U
+  ).toUint8Array();
+
+  // The cipher expects the encrypted data and tag to be concatenated.
+  const ciphertextAndTag = new Uint8Array([
+    ...ciphertext,
+    ...authenticationTag,
+  ]);
+  const chacha = xchacha20poly1305(encryptionKeyBytes, nonce, additionalData);
+  const decryptedJwtBytes = chacha.decrypt(ciphertextAndTag);
+  const jwt = Convert.uint8Array(decryptedJwtBytes).toString();
+
+  return jwt;
+}
+
+/**
+ * The client uses to decrypt the jwe obtained from the auth server which contains
+ * the {@link Web5ConnectAuthResponse} that was sent by the provider to the auth server.
+ *
+ * @async
+ * @param {BearerDid} clientDid - The did that was initially used by the client for ECDH at connect init.
+ * @param {string} jwe - The encrypted data as a jwe.
+ * @param {string} pin - The pin that was obtained from the user.
+ */
+async function decryptAuthResponse(
+  clientDid: BearerDid,
+  jwe: string,
+  pin: string
+) {
+  const [
+    protectedHeaderB64U,
+    ,
+    nonceB64U,
+    ciphertextB64U,
+    authenticationTagB64U,
+  ] = jwe.split('.');
+
+  // get the delegatedid public key from the header
+  const header = Convert.base64Url(protectedHeaderB64U).toObject() as Jwk;
+  const delegateResolvedDid = await DidJwk.resolve(header.kid!.split('#')[0]);
+
+  // derive ECDH shared key using the provider's public key and our clientDid private key
+  const sharedKey = await Oidc.deriveSharedKey(
+    clientDid,
+    delegateResolvedDid.didDocument!
+  );
+
+  // add the pin to the AAD
+  const additionalData = { ...header, pin: pin };
+  const AAD = Convert.object(additionalData).toUint8Array();
+
+  const nonce = Convert.base64Url(nonceB64U).toUint8Array();
+  const ciphertext = Convert.base64Url(ciphertextB64U).toUint8Array();
+  const authenticationTag = Convert.base64Url(
+    authenticationTagB64U
+  ).toUint8Array();
+
+  // The cipher expects the encrypted data and tag to be concatenated.
+  const ciphertextAndTag = new Uint8Array([
+    ...ciphertext,
+    ...authenticationTag,
+  ]);
+
+  // decrypt using the sharedKey
+  const chacha = xchacha20poly1305(sharedKey, nonce, AAD);
+  const decryptedJwtBytes = chacha.decrypt(ciphertextAndTag);
+  const jwt = Convert.uint8Array(decryptedJwtBytes).toString();
+
+  return jwt;
+}
+
+/** Derives a shared ECDH private key in order to encrypt the {@link Web5ConnectAuthResponse} */
+async function deriveSharedKey(
+  privateKeyDid: BearerDid,
+  publicKeyDid: DidDocument
+) {
+  const privatePortableDid = await privateKeyDid.export();
+
+  const publicJwk = publicKeyDid.verificationMethod?.[0].publicKeyJwk!;
+  const privateJwk = privatePortableDid.privateKeys?.[0]!;
+  publicJwk.alg = 'EdDSA';
+
+  const publicX25519 = await Ed25519.convertPublicKeyToX25519({
+    publicKey: publicJwk,
+  });
+  const privateX25519 = await Ed25519.convertPrivateKeyToX25519({
+    privateKey: privateJwk,
+  });
+
+  const sharedKey = await X25519.sharedSecret({
+    privateKeyA : privateX25519,
+    publicKeyB  : publicX25519,
+  });
+
+  const derivedKey = await crypto.subtle.importKey(
+    'raw',
+    sharedKey,
+    { name: 'HKDF' },
+    false,
+    ['deriveBits']
+  );
+  const derivedKeyBits = await crypto.subtle.deriveBits(
+    {
+      name : 'HKDF',
+      hash : 'SHA-256',
+      info : new Uint8Array(),
+      salt : new Uint8Array(),
+    },
+    derivedKey,
+    256
+  );
+  const sharedEncryptionKey = new Uint8Array(derivedKeyBits);
+  return sharedEncryptionKey;
+}
+
+/**
+ * Encrypts the auth response jwt. Requires a randomPin is added to the AAD of the
+ * encryption algorithm in order to prevent man in the middle and eavesdropping attacks.
+ * The keyid of the delegate did is used to pass the public key to the client in order
+ * for the client to derive the shared ECDH private key.
+ */
+function encryptAuthResponse({
+  jwt,
+  encryptionKey,
+  delegateDidKeyId,
+  randomPin,
+}: {
+  jwt: string;
+  encryptionKey: Uint8Array;
+  delegateDidKeyId: string;
+  randomPin: string;
+}) {
+  const protectedHeader = {
+    alg : 'dir',
+    cty : 'JWT',
+    enc : 'XC20P',
+    typ : 'JWT',
+    kid : delegateDidKeyId,
+  };
+  const nonce = CryptoUtils.randomBytes(24);
+  const additionalData = Convert.object({
+    ...protectedHeader,
+    pin: randomPin,
+  }).toUint8Array();
+
+  const jwtBytes = Convert.string(jwt).toUint8Array();
+  const chacha = xchacha20poly1305(encryptionKey, nonce, additionalData);
+  const ciphertextAndTag = chacha.encrypt(jwtBytes);
+
+  /** The cipher output concatenates the encrypted data and tag
+   * so we need to extract the values for use in the JWE. */
+  const ciphertext = ciphertextAndTag.subarray(0, -16);
+  const authenticationTag = ciphertextAndTag.subarray(-16);
+
+  const compactJwe = [
+    Convert.object(protectedHeader).toBase64Url(),
+    '', // Empty string since there is no wrapped key.
+    Convert.uint8Array(nonce).toBase64Url(),
+    Convert.uint8Array(ciphertext).toBase64Url(),
+    Convert.uint8Array(authenticationTag).toBase64Url(),
+  ].join('.');
+
+  return compactJwe;
+}
+
+function shouldUseDelegatePermission(scope: DwnPermissionScope): boolean {
+  // Currently all record permissions are treated as delegated permissions
+  // In the future only methods that modify state will be delegated and the rest will be normal permissions
+  if (isRecordPermissionScope(scope)) {
+    return true;
+  } else if (scope.interface === DwnInterfaceName.Protocols && scope.method === DwnMethodName.Configure) {
+    // ProtocolConfigure messages are also delegated, as they modify state
+    return true;
+  }
+
+  // All other permissions are not treated as delegated
+  return false;
+}
+
+/**
+ * Creates the permission grants that assign to the selectedDid the level of
+ * permissions that the web app requested in the {@link Web5ConnectAuthRequest}
+ */
+async function createPermissionGrants(
+  selectedDid: string,
+  delegateBearerDid: BearerDid,
+  agent: Web5Agent,
+  scopes: DwnPermissionScope[],
+) {
+  const permissionsApi = new AgentPermissionsApi({ agent });
+
+  // TODO: cleanup all grants if one fails by deleting them from the DWN: https://github.com/TBD54566975/web5-js/issues/849
+  logger.log(`Creating permission grants for ${scopes.length} scopes given...`);
+  const permissionGrants = await Promise.all(
+    scopes.map((scope) => {
+      // check if the scope is a records permission scope, or a protocol configure scope, if so it should use a delegated permission.
+      const delegated = shouldUseDelegatePermission(scope);
+      return permissionsApi.createGrant({
+        delegated,
+        store       : true,
+        grantedTo   : delegateBearerDid.uri,
+        scope,
+        dateExpires : '2040-06-25T16:09:16.693356Z', // TODO: make dateExpires optional
+        author      : selectedDid,
+      });
+    })
+  );
+
+  logger.log(`Sending ${permissionGrants.length} permission grants to remote DWN...`);
+  const messagePromises = permissionGrants.map(async (grant) => {
+    // Quirk: we have to pull out encodedData out of the message the schema validator doesn't want it there
+    const { encodedData, ...rawMessage } = grant.message;
+
+    const data = Convert.base64Url(encodedData).toUint8Array();
+    const { reply } = await agent.sendDwnRequest({
+      author      : selectedDid,
+      target      : selectedDid,
+      messageType : DwnInterface.RecordsWrite,
+      dataStream  : new Blob([data]),
+      rawMessage,
+    });
+
+    // check if the message was sent successfully, if the remote returns 409 the message may have come through already via sync
+    if (reply.status.code !== 202 && reply.status.code !== 409) {
+      logger.error(`Error sending RecordsWrite: ${reply.status.detail}`);
+      logger.error(`RecordsWrite message: ${rawMessage}`);
+      throw new Error(
+        `Could not send the message. Error details: ${reply.status.detail}`
+      );
+    }
+
+    return grant.message;
+  });
+
+  try {
+    const messages = await Promise.all(messagePromises);
+    return messages;
+  } catch (error) {
+    logger.error(`Error during batch-send of permission grants: ${error}`);
+    throw error;
+  }
+}
+
+/**
+ * Installs the protocol required by the Client on the Provider if it doesn't already exist.
+ */
+async function prepareProtocol(
+  selectedDid: string,
+  agent: Web5Agent,
+  protocolDefinition: DwnProtocolDefinition
+): Promise<void> {
+
+  const queryMessage = await agent.processDwnRequest({
+    author        : selectedDid,
+    messageType   : DwnInterface.ProtocolsQuery,
+    target        : selectedDid,
+    messageParams : { filter: { protocol: protocolDefinition.protocol } },
+  });
+
+  if ( queryMessage.reply.status.code !== 200) {
+    // if the query failed, throw an error
+    throw new Error(
+      `Could not fetch protocol: ${queryMessage.reply.status.detail}`
+    );
+  } else if (queryMessage.reply.entries === undefined || queryMessage.reply.entries.length === 0) {
+    logger.log(`Protocol does not exist, creating: ${protocolDefinition.protocol}`);
+
+    // send the protocol definition to the remote DWN first, if it passes we can process it locally
+    const { reply: sendReply, message: configureMessage } = await agent.sendDwnRequest({
+      author        : selectedDid,
+      target        : selectedDid,
+      messageType   : DwnInterface.ProtocolsConfigure,
+      messageParams : { definition: protocolDefinition },
+    });
+
+    // check if the message was sent successfully, if the remote returns 409 the message may have come through already via sync
+    if (sendReply.status.code !== 202 && sendReply.status.code !== 409) {
+      throw new Error(`Could not send protocol: ${sendReply.status.detail}`);
+    }
+
+    // process the protocol locally, we don't have to check if it exists as this is just a convenience over waiting for sync.
+    await agent.processDwnRequest({
+      author      : selectedDid,
+      target      : selectedDid,
+      messageType : DwnInterface.ProtocolsConfigure,
+      rawMessage  : configureMessage
+    });
+
+  } else {
+    logger.log(`Protocol already exists: ${protocolDefinition.protocol}`);
+
+    // the protocol already exists, let's make sure it exists on the remote DWN as the requesting app will need it
+    const configureMessage = queryMessage.reply.entries![0];
+    const { reply: sendReply } = await agent.sendDwnRequest({
+      author      : selectedDid,
+      target      : selectedDid,
+      messageType : DwnInterface.ProtocolsConfigure,
+      rawMessage  : configureMessage,
+    });
+
+    if (sendReply.status.code !== 202 && sendReply.status.code !== 409) {
+      throw new Error(`Could not send protocol: ${sendReply.status.detail}`);
+    }
+  }
+}
+
+/**
+ * Creates a delegate did which the web app will use as its future indentity.
+ * Assigns to that DID the level of permissions that the web app requested in
+ * the {@link Web5ConnectAuthRequest}. Encrypts via ECDH key that the web app
+ * will have access to because the web app has the public key which it provided
+ * in the {@link Web5ConnectAuthRequest}. Then sends the ciphertext of this
+ * {@link Web5ConnectAuthResponse} to the callback endpoint. Which the
+ * web app will need to retrieve from the token endpoint and decrypt with the pin to access.
+ */
+async function submitAuthResponse(
+  selectedDid: string,
+  authRequest: Web5ConnectAuthRequest,
+  randomPin: string,
+  agent: Web5Agent
+) {
+  const delegateBearerDid = await DidJwk.create();
+  const delegatePortableDid = await delegateBearerDid.export();
+
+  // TODO: roll back permissions and protocol configurations if an error occurs. Need a way to delete protocols to achieve this.
+  const delegateGrantPromises = authRequest.permissionRequests.map(
+    async (permissionRequest) => {
+      const { protocolDefinition, permissionScopes } = permissionRequest;
+
+      // We validate that all permission scopes match the protocol uri of the protocol definition they are provided with.
+      const grantsMatchProtocolUri = permissionScopes.every(scope => 'protocol' in scope && scope.protocol === protocolDefinition.protocol);
+      if (!grantsMatchProtocolUri) {
+        throw new Error('All permission scopes must match the protocol uri they are provided with.');
+      }
+
+      await prepareProtocol(selectedDid, agent, protocolDefinition);
+
+      const permissionGrants = await Oidc.createPermissionGrants(
+        selectedDid,
+        delegateBearerDid,
+        agent,
+        permissionScopes
+      );
+
+      return permissionGrants;
+    }
+  );
+
+  const delegateGrants = (await Promise.all(delegateGrantPromises)).flat();
+
+  logger.log('Generating auth response object...');
+  const responseObject = await Oidc.createResponseObject({
+    //* the IDP's did that was selected to be connected
+    iss   : selectedDid,
+    //* the client's new identity
+    sub   : delegateBearerDid.uri,
+    //* the client's temporary ephemeral did used for connect
+    aud   : authRequest.client_id,
+    //* the nonce of the original auth request
+    nonce : authRequest.nonce,
+    delegateGrants,
+    delegatePortableDid,
+  });
+
+  // Sign the Response Object using the ephemeral DID's signing key.
+  logger.log('Signing auth response object...');
+  const responseObjectJwt = await Oidc.signJwt({
+    did  : delegateBearerDid,
+    data : responseObject,
+  });
+  const clientDid = await DidJwk.resolve(authRequest.client_id);
+
+  const sharedKey = await Oidc.deriveSharedKey(
+    delegateBearerDid,
+    clientDid?.didDocument!
+  );
+
+  logger.log('Encrypting auth response object...');
+  const encryptedResponse = Oidc.encryptAuthResponse({
+    jwt              : responseObjectJwt!,
+    encryptionKey    : sharedKey,
+    delegateDidKeyId : delegateBearerDid.document.verificationMethod![0].id,
+    randomPin,
+  });
+
+  const formEncodedRequest = new URLSearchParams({
+    id_token : encryptedResponse,
+    state    : authRequest.state,
+  }).toString();
+
+  logger.log(`Sending auth response object to Web5 Connect server: ${authRequest.redirect_uri}`);
+  await fetch(authRequest.redirect_uri, {
+    body    : formEncodedRequest,
+    method  : 'POST',
+    headers : {
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+  });
+}
+
+export const Oidc = {
+  createAuthRequest,
+  encryptAuthRequest,
+  getAuthRequest,
+  decryptAuthRequest,
+  createPermissionGrants,
+  createResponseObject,
+  encryptAuthResponse,
+  decryptAuthResponse,
+  deriveSharedKey,
+  signJwt,
+  verifyJwt,
+  buildOidcUrl,
+  generateCodeChallenge,
+  submitAuthResponse,
+};