@enbox/agent 0.3.1 → 0.4.0

package/src/oidc.ts

@@ -1,864 +0,0 @@
-import type { ConnectPermissionRequest } from './connect.js';
-import type { EnboxAgent } from './types/agent.js';
-import type { RequireOnly } from '@enbox/common';
-import type { DidDocument, PortableDid } from '@enbox/dids';
-import type { DwnDataEncodedRecordsWriteMessage, DwnPermissionScope, DwnProtocolDefinition } from './types/dwn.js';
-import type {
-  JoseHeaderParams,
-  Jwk } from '@enbox/crypto';
-
-import { type BearerDid, DidJwk } from '@enbox/dids';
-import { Convert, logger } from '@enbox/common';
-import {
-  CryptoUtils,
-  Ed25519,
-  EdDsaAlgorithm,
-  Hkdf,
-  Sha256,
-  X25519,
-  XChaCha20Poly1305,
-} from '@enbox/crypto';
-import { DwnInterfaceName, DwnMethodName } from '@enbox/dwn-sdk-js';
-
-import { AgentPermissionsApi } from './permissions-api.js';
-import { concatenateUrl } from './utils.js';
-import { DwnInterface } from './types/dwn.js';
-import { isRecordPermissionScope } from './dwn-api.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 EnboxConnectAuthRequest} */
-  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/enboxorg/enbox | Enbox 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 EnboxConnectAuthRequest = {
-  /** 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 EnboxConnectAuthResponse = {
-  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 EnboxConnectAuthRequest} JWT that was stored by the PAR
- * 3. `callback`: provider sends {@link EnboxConnectAuthResponse} to this endpoint
- * 4. `token`: client gets {@link EnboxConnectAuthResponse} 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;
-}): string {
-  switch (endpoint) {
-    /** 1. client sends {@link PushedAuthRequest} & client receives {@link PushedAuthResponse} */
-    case 'pushedAuthorizationRequest':
-      return concatenateUrl(baseURL, 'par');
-    /** 2. provider gets {@link EnboxConnectAuthRequest} */
-    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 EnboxConnectAuthResponse} */
-    case 'callback':
-      return concatenateUrl(baseURL, `callback`);
-    /**  4. client gets {@link EnboxConnectAuthResponse */
-    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(): Promise<{ codeChallengeBytes: Uint8Array; codeChallengeBase64Url: string }> {
-  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 EnboxConnectAuthRequest} */
-async function createAuthRequest(
-  options: RequireOnly<
-    EnboxConnectAuthRequest,
-    'client_id' | 'scope' | 'redirect_uri' | 'permissionRequests' | 'displayName'
-  >
-): Promise<EnboxConnectAuthRequest> {
-  // 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: EnboxConnectAuthRequest = {
-    ...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;
-}): Promise<string> {
-  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 ciphertextAndTag = await XChaCha20Poly1305.encryptRaw({ data: jwtBytes, keyBytes: encryptionKey, nonce, additionalData });
-
-  /** 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<
-    EnboxConnectAuthResponse,
-    'iss' | 'sub' | 'aud' | 'delegateGrants' | 'delegatePortableDid'
-  >
-): Promise<EnboxConnectAuthResponse> {
-  const currentTimeInSeconds = Math.floor(Date.now() / 1000);
-
-  const responseObject: EnboxConnectAuthResponse = {
-    ...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>;
-}): Promise<string> {
-  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 }): Promise<Record<string, unknown>> {
-  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() as Record<string, unknown>;
-
-  return object;
-}
-
-/**
- * Fetches the {@EnboxConnectAuthRequest} from the authorize endpoint and decrypts it
- * using the encryption key passed via QR code.
- */
-const getAuthRequest = async (request_uri: string, encryption_key: string): Promise<EnboxConnectAuthRequest> => {
-  const authRequest = await fetch(request_uri, { signal: AbortSignal.timeout(30_000) });
-  const jwe = await authRequest.text();
-  const jwt = await decryptAuthRequest({
-    jwe,
-    encryption_key,
-  });
-  const web5ConnectAuthRequest = (await verifyJwt({
-    jwt,
-  })) as EnboxConnectAuthRequest;
-
-  return web5ConnectAuthRequest;
-};
-
-/** Take the encrypted JWE, decrypt using the code challenge and return a JWT string which will need to be verified */
-async function decryptAuthRequest({
-  jwe,
-  encryption_key,
-}: {
-  jwe: string;
-  encryption_key: string;
-}): Promise<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 decryptedJwtBytes = await XChaCha20Poly1305.decryptRaw({ data: ciphertextAndTag, keyBytes: encryptionKeyBytes, nonce, additionalData });
-  const jwt = Convert.uint8Array(decryptedJwtBytes).toString();
-
-  return jwt;
-}
-
-/**
- * The client uses to decrypt the jwe obtained from the auth server which contains
- * the {@link EnboxConnectAuthResponse} 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
-): Promise<string> {
-  const [
-    protectedHeaderB64U,
-    ,
-    nonceB64U,
-    ciphertextB64U,
-    authenticationTagB64U,
-  ] = jwe.split('.');
-
-  // get the delegatedid public key from the header
-  const header = Convert.base64Url(protectedHeaderB64U).toObject() as Jwk;
-  if (!header.kid) {
-    throw new Error('JWE protected header is missing required "kid" property');
-  }
-  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 decryptedJwtBytes = await XChaCha20Poly1305.decryptRaw({ data: ciphertextAndTag, keyBytes: sharedKey, nonce, additionalData: AAD });
-  const jwt = Convert.uint8Array(decryptedJwtBytes).toString();
-
-  return jwt;
-}
-
-/** Derives a shared ECDH private key in order to encrypt the {@link EnboxConnectAuthResponse} */
-async function deriveSharedKey(
-  privateKeyDid: BearerDid,
-  publicKeyDid: DidDocument
-): Promise<Uint8Array> {
-  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 sharedEncryptionKey = await Hkdf.deriveKeyBytes({
-    baseKeyBytes : new Uint8Array(sharedKey),
-    hash         : 'SHA-256',
-    salt         : new Uint8Array(),
-    info         : new Uint8Array(),
-    length       : 256,
-  });
-
-  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.
- */
-async function encryptAuthResponse({
-  jwt,
-  encryptionKey,
-  delegateDidKeyId,
-  randomPin,
-}: {
-  jwt: string;
-  encryptionKey: Uint8Array;
-  delegateDidKeyId: string;
-  randomPin: string;
-}): Promise<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 ciphertextAndTag = await XChaCha20Poly1305.encryptRaw({ data: jwtBytes, keyBytes: encryptionKey, nonce, additionalData });
-
-  /** 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 EnboxConnectAuthRequest}
- */
-async function createPermissionGrants(
-  selectedDid: string,
-  delegateBearerDid: BearerDid,
-  agent: EnboxAgent,
-  scopes: DwnPermissionScope[],
-): Promise<DwnDataEncodedRecordsWriteMessage[]> {
-  const permissionsApi = new AgentPermissionsApi({ agent });
-
-  // TODO: cleanup all grants if one fails by deleting them from the DWN: https://github.com/enboxorg/enbox/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: EnboxAgent,
-  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 EnboxConnectAuthRequest}. 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 EnboxConnectAuthRequest}. Then sends the ciphertext of this
- * {@link EnboxConnectAuthResponse} 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: EnboxConnectAuthRequest,
-  randomPin: string,
-  agent: EnboxAgent
-): Promise<void> {
-  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 = await 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',
-    },
-    signal: AbortSignal.timeout(30_000),
-  });
-}
-
-export const Oidc = {
-  createAuthRequest,
-  encryptAuthRequest,
-  getAuthRequest,
-  decryptAuthRequest,
-  createPermissionGrants,
-  createResponseObject,
-  encryptAuthResponse,
-  decryptAuthResponse,
-  deriveSharedKey,
-  signJwt,
-  verifyJwt,
-  buildOidcUrl,
-  generateCodeChallenge,
-  submitAuthResponse,
-};
-
-// ---------------------------------------------------------------------------
-// Deprecated aliases — migration aid
-// ---------------------------------------------------------------------------
-
-/** @deprecated Use {@link EnboxConnectAuthRequest} instead. */
-export type Web5ConnectAuthRequest = EnboxConnectAuthRequest;
-
-/** @deprecated Use {@link EnboxConnectAuthResponse} instead. */
-export type Web5ConnectAuthResponse = EnboxConnectAuthResponse;