@enbox/agent 0.3.1 → 0.5.0

package/dist/esm/{oidc.js → enbox-connect-protocol.js}

@@ -1,3 +1,17 @@
+/**
+ * Enbox Connect Protocol
+ *
+ * A capability delegation protocol for DWN access. Enables apps to request
+ * scoped permission grants from a wallet (provider), receiving a delegate DID
+ * with the granted permissions.
+ *
+ * Two transport modes:
+ * - Local (`dwn://connect`): same-device, direct HTTP against the local DWN
+ * - Remote (`enbox://connect`): cross-device, relay-mediated with QR/deep link
+ *
+ * The protocol uses JWTs for signing, JWE (XChaCha20-Poly1305) for encryption,
+ * and ECDH (Ed25519 → X25519 + HKDF) for key agreement.
+ */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -20,110 +34,47 @@ var __rest = (this && this.__rest) || function (s, e) {
 };
 import { DidJwk } from '@enbox/dids';
 import { Convert, logger } from '@enbox/common';
-import { CryptoUtils, Ed25519, EdDsaAlgorithm, Hkdf, Sha256, X25519, XChaCha20Poly1305, } from '@enbox/crypto';
+import { CryptoUtils, Ed25519, EdDsaAlgorithm, Hkdf, 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';
+// ---------------------------------------------------------------------------
+// URL building
+// ---------------------------------------------------------------------------
 /**
- * Gets the correct OIDC endpoint out of the {@link OidcEndpoint} options provided.
- * Handles a trailing slash on baseURL
+ * Builds the URL for a connect server endpoint.
  *
- * @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
+ * @param options.baseURL - The connect server base URL (e.g. `http://localhost:3000/connect/`)
+ * @param options.endpoint - The endpoint type
+ * @param options.authParam - Required for `authorize` endpoint (the request ID)
+ * @param options.tokenParam - Required for `token` endpoint (the state value)
  */
-function buildOidcUrl({ baseURL, endpoint, authParam, tokenParam, }) {
+function buildConnectUrl({ baseURL, endpoint, authParam, tokenParam, }) {
     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`);
+                throw new Error('authParam must be provided when building an authorize URL');
             }
             return concatenateUrl(baseURL, `authorize/${authParam}.jwt`);
-        /** 3. provider sends {@link EnboxConnectAuthResponse} */
         case 'callback':
-            return concatenateUrl(baseURL, `callback`);
-        /**  4. client gets {@link EnboxConnectAuthResponse */
+            return concatenateUrl(baseURL, 'callback');
         case 'token':
             if (!tokenParam) {
-                throw new Error(`tokenParam must be providied when building a token URL`);
+                throw new Error('tokenParam must be provided when building a token URL');
             }
             return concatenateUrl(baseURL, `token/${tokenParam}.jwt`);
-        // TODO: metadata endpoints?
         default:
-            throw new Error(`No matches for endpoint specified: ${endpoint}`);
+            throw new Error(`Unknown connect endpoint: ${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 }
- */
-function generateCodeChallenge() {
-    return __awaiter(this, void 0, void 0, function* () {
-        const codeVerifierBytes = CryptoUtils.randomBytes(32);
-        const codeChallengeBytes = yield Sha256.digest({ data: codeVerifierBytes });
-        const codeChallengeBase64Url = Convert.uint8Array(codeChallengeBytes).toBase64Url();
-        return { codeChallengeBytes, codeChallengeBase64Url };
-    });
-}
-/** Client creates the {@link EnboxConnectAuthRequest} */
-function createAuthRequest(options) {
-    return __awaiter(this, void 0, void 0, function* () {
-        // 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 = Object.assign(Object.assign({}, 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 */
-function encryptAuthRequest(_a) {
-    return __awaiter(this, arguments, void 0, function* ({ jwt, encryptionKey, }) {
-        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 = yield 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 */
-function createResponseObject(options) {
-    return __awaiter(this, void 0, void 0, function* () {
-        const currentTimeInSeconds = Math.floor(Date.now() / 1000);
-        const responseObject = Object.assign(Object.assign({}, options), { iat: currentTimeInSeconds, exp: currentTimeInSeconds + 600 });
-        return responseObject;
-    });
-}
-/** sign an object and transform it into a jwt using a did */
+// ---------------------------------------------------------------------------
+// JWT signing and verification
+// ---------------------------------------------------------------------------
+/** Signs an object as a JWT using an Ed25519 DID key. */
 function signJwt(_a) {
     return __awaiter(this, arguments, void 0, function* ({ did, data, }) {
         const header = Convert.object({
@@ -132,37 +83,32 @@ function signJwt(_a) {
             typ: 'JWT',
         }).toBase64Url();
         const payload = Convert.object(data).toBase64Url();
-        // signs using ed25519 EdDSA
         const signer = yield did.getSigner();
         const signature = yield signer.sign({
             data: Convert.string(`${header}.${payload}`).toUint8Array(),
         });
         const signatureBase64Url = Convert.uint8Array(signature).toBase64Url();
-        const jwt = `${header}.${payload}.${signatureBase64Url}`;
-        return jwt;
+        return `${header}.${payload}.${signatureBase64Url}`;
     });
 }
-/** Take the decrypted JWT and verify it was signed by its public DID. Return parsed object. */
+/** Verifies a JWT signature using the DID in the `kid` header. Returns the parsed payload. */
 function verifyJwt(_a) {
     return __awaiter(this, arguments, void 0, function* ({ jwt }) {
         var _b, _c;
         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 = Convert.base64Url(headerB64U).toObject();
         if (!header.kid) {
-            throw new Error(`OIDC: Object could not be verified due to missing 'kid' header value.`);
+            throw new Error('Connect: JWT missing required "kid" header value.');
         }
-        // Resolve the Client DID document.
         const { didDocument } = yield DidJwk.resolve(header.kid.split('#')[0]);
         if (!didDocument) {
-            throw new Error('OIDC: Object could not be verified due to Client DID resolution issue.');
+            throw new Error('Connect: JWT verification failed — could not resolve DID.');
         }
-        // Get the public key used to sign the Object from the DID document.
         const { publicKeyJwk } = (_c = (_b = didDocument.verificationMethod) === null || _b === void 0 ? void 0 : _b.find((method) => {
             return method.id === header.kid;
         })) !== null && _c !== void 0 ? _c : {};
         if (!publicKeyJwk) {
-            throw new Error('OIDC: Object could not be verified due to missing public key in DID document.');
+            throw new Error('Connect: JWT verification failed — public key not found in DID document.');
         }
         const EdDsa = new EdDsaAlgorithm();
         const isValid = yield EdDsa.verify({
@@ -171,86 +117,56 @@ function verifyJwt(_a) {
             data: Convert.string(`${headerB64U}.${payloadB64U}`).toUint8Array(),
         });
         if (!isValid) {
-            throw new Error('OIDC: Object failed verification due to invalid signature.');
+            throw new Error('Connect: JWT verification failed — invalid signature.');
         }
-        const object = Convert.base64Url(payloadB64U).toObject();
-        return object;
+        return Convert.base64Url(payloadB64U).toObject();
     });
 }
-/**
- * Fetches the {@EnboxConnectAuthRequest} from the authorize endpoint and decrypts it
- * using the encryption key passed via QR code.
- */
-const getAuthRequest = (request_uri, encryption_key) => __awaiter(void 0, void 0, void 0, function* () {
-    const authRequest = yield fetch(request_uri, { signal: AbortSignal.timeout(30000) });
-    const jwe = yield authRequest.text();
-    const jwt = yield decryptAuthRequest({
-        jwe,
-        encryption_key,
-    });
-    const web5ConnectAuthRequest = (yield verifyJwt({
-        jwt,
-    }));
-    return web5ConnectAuthRequest;
-});
-/** Take the encrypted JWE, decrypt using the code challenge and return a JWT string which will need to be verified */
-function decryptAuthRequest(_a) {
-    return __awaiter(this, arguments, void 0, function* ({ jwe, encryption_key, }) {
-        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 = yield XChaCha20Poly1305.decryptRaw({ data: ciphertextAndTag, keyBytes: encryptionKeyBytes, nonce, additionalData });
-        const jwt = Convert.uint8Array(decryptedJwtBytes).toString();
-        return jwt;
+// ---------------------------------------------------------------------------
+// Encryption: request (symmetric key via QR/deep link)
+// ---------------------------------------------------------------------------
+/** Encrypts the connect request JWT with a symmetric key (shared via QR code or deep link). */
+function encryptRequest(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ jwt, encryptionKey, }) {
+        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 = yield XChaCha20Poly1305.encryptRaw({ data: jwtBytes, keyBytes: encryptionKey, nonce, additionalData });
+        const ciphertext = ciphertextAndTag.subarray(0, -16);
+        const authenticationTag = ciphertextAndTag.subarray(-16);
+        return [
+            Convert.object(protectedHeader).toBase64Url(),
+            '', // No wrapped key (direct encryption).
+            Convert.uint8Array(nonce).toBase64Url(),
+            Convert.uint8Array(ciphertext).toBase64Url(),
+            Convert.uint8Array(authenticationTag).toBase64Url(),
+        ].join('.');
     });
 }
-/**
- * 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.
- */
-function decryptAuthResponse(clientDid, jwe, pin) {
-    return __awaiter(this, void 0, void 0, function* () {
+/** Decrypts an encrypted connect request JWE using the symmetric key from the QR/deep link. */
+function decryptRequest(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ jwe, encryptionKey, }) {
         const [protectedHeaderB64U, , nonceB64U, ciphertextB64U, authenticationTagB64U,] = jwe.split('.');
-        // get the delegatedid public key from the header
-        const header = Convert.base64Url(protectedHeaderB64U).toObject();
-        if (!header.kid) {
-            throw new Error('JWE protected header is missing required "kid" property');
-        }
-        const delegateResolvedDid = yield DidJwk.resolve(header.kid.split('#')[0]);
-        // derive ECDH shared key using the provider's public key and our clientDid private key
-        const sharedKey = yield Oidc.deriveSharedKey(clientDid, delegateResolvedDid.didDocument);
-        // add the pin to the AAD
-        const additionalData = Object.assign(Object.assign({}, header), { pin: pin });
-        const AAD = Convert.object(additionalData).toUint8Array();
+        const encryptionKeyBytes = Convert.base64Url(encryptionKey).toUint8Array();
+        const additionalData = Convert.base64Url(protectedHeaderB64U).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 = yield XChaCha20Poly1305.decryptRaw({ data: ciphertextAndTag, keyBytes: sharedKey, nonce, additionalData: AAD });
-        const jwt = Convert.uint8Array(decryptedJwtBytes).toString();
-        return jwt;
+        const ciphertextAndTag = new Uint8Array([...ciphertext, ...authenticationTag]);
+        const decryptedJwtBytes = yield XChaCha20Poly1305.decryptRaw({ data: ciphertextAndTag, keyBytes: encryptionKeyBytes, nonce, additionalData });
+        return Convert.uint8Array(decryptedJwtBytes).toString();
     });
 }
-/** Derives a shared ECDH private key in order to encrypt the {@link EnboxConnectAuthResponse} */
+// ---------------------------------------------------------------------------
+// Encryption: response (ECDH shared key + optional PIN)
+// ---------------------------------------------------------------------------
+/** Derives a shared ECDH key for encrypting/decrypting the connect response. */
 function deriveSharedKey(privateKeyDid, publicKeyDid) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b;
@@ -258,34 +174,32 @@ function deriveSharedKey(privateKeyDid, publicKeyDid) {
         const publicJwk = (_a = publicKeyDid.verificationMethod) === null || _a === void 0 ? void 0 : _a[0].publicKeyJwk;
         const privateJwk = (_b = privatePortableDid.privateKeys) === null || _b === void 0 ? void 0 : _b[0];
         publicJwk.alg = 'EdDSA';
-        const publicX25519 = yield Ed25519.convertPublicKeyToX25519({
-            publicKey: publicJwk,
-        });
-        const privateX25519 = yield Ed25519.convertPrivateKeyToX25519({
-            privateKey: privateJwk,
-        });
+        const publicX25519 = yield Ed25519.convertPublicKeyToX25519({ publicKey: publicJwk });
+        const privateX25519 = yield Ed25519.convertPrivateKeyToX25519({ privateKey: privateJwk });
         const sharedKey = yield X25519.sharedSecret({
             privateKeyA: privateX25519,
             publicKeyB: publicX25519,
         });
-        const sharedEncryptionKey = yield Hkdf.deriveKeyBytes({
+        return 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.
+ * Encrypts the connect response JWT.
+ *
+ * For remote (relay-mediated) flows, `pin` is required — it is added to the
+ * AAD to prevent MITM attacks via the untrusted relay.
+ *
+ * For local (same-device) flows, `pin` may be omitted — the ECDH encryption
+ * alone is sufficient when there is no untrusted intermediary.
  */
-function encryptAuthResponse(_a) {
-    return __awaiter(this, arguments, void 0, function* ({ jwt, encryptionKey, delegateDidKeyId, randomPin, }) {
+function encryptResponse(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ jwt, encryptionKey, delegateDidKeyId, pin, }) {
         const protectedHeader = {
             alg: 'dir',
             cty: 'JWT',
@@ -294,60 +208,117 @@ function encryptAuthResponse(_a) {
             kid: delegateDidKeyId,
         };
         const nonce = CryptoUtils.randomBytes(24);
-        const additionalData = Convert.object(Object.assign(Object.assign({}, protectedHeader), { pin: randomPin })).toUint8Array();
+        // Build AAD — include PIN if provided (remote flows).
+        const aadObject = pin
+            ? Object.assign(Object.assign({}, protectedHeader), { pin }) : Object.assign({}, protectedHeader);
+        const additionalData = Convert.object(aadObject).toUint8Array();
         const jwtBytes = Convert.string(jwt).toUint8Array();
         const ciphertextAndTag = yield 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 = [
+        return [
             Convert.object(protectedHeader).toBase64Url(),
-            '', // Empty string since there is no wrapped key.
+            '', // No wrapped key (direct encryption).
             Convert.uint8Array(nonce).toBase64Url(),
             Convert.uint8Array(ciphertext).toBase64Url(),
             Convert.uint8Array(authenticationTag).toBase64Url(),
         ].join('.');
-        return compactJwe;
     });
 }
+/**
+ * Decrypts the connect response JWE using ECDH + optional PIN.
+ *
+ * @param clientDid - The ephemeral DID used at connect initiation (for ECDH).
+ * @param jwe - The encrypted response JWE.
+ * @param pin - The PIN entered by the user (required for remote flows, omit for local).
+ */
+function decryptResponse(clientDid, jwe, pin) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const [protectedHeaderB64U, , nonceB64U, ciphertextB64U, authenticationTagB64U,] = jwe.split('.');
+        const header = Convert.base64Url(protectedHeaderB64U).toObject();
+        if (!header.kid) {
+            throw new Error('Connect: JWE protected header is missing required "kid" property.');
+        }
+        const delegateResolvedDid = yield DidJwk.resolve(header.kid.split('#')[0]);
+        const sharedKey = yield EnboxConnectProtocol.deriveSharedKey(clientDid, delegateResolvedDid.didDocument);
+        // Build AAD — include PIN if provided (must match what was used during encryption).
+        const aadObject = pin
+            ? Object.assign(Object.assign({}, header), { pin }) : Object.assign({}, header);
+        const AAD = Convert.object(aadObject).toUint8Array();
+        const nonce = Convert.base64Url(nonceB64U).toUint8Array();
+        const ciphertext = Convert.base64Url(ciphertextB64U).toUint8Array();
+        const authenticationTag = Convert.base64Url(authenticationTagB64U).toUint8Array();
+        const ciphertextAndTag = new Uint8Array([...ciphertext, ...authenticationTag]);
+        const decryptedJwtBytes = yield XChaCha20Poly1305.decryptRaw({ data: ciphertextAndTag, keyBytes: sharedKey, nonce, additionalData: AAD });
+        return Convert.uint8Array(decryptedJwtBytes).toString();
+    });
+}
+// ---------------------------------------------------------------------------
+// Request creation and retrieval
+// ---------------------------------------------------------------------------
+/** Creates an {@link EnboxConnectRequest}. */
+function createConnectRequest(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const stateBytes = CryptoUtils.randomBytes(16);
+        const nonceBytes = CryptoUtils.randomBytes(16);
+        return Object.assign(Object.assign({}, options), { nonce: Convert.uint8Array(nonceBytes).toBase64Url(), responseMode: 'direct_post', state: Convert.uint8Array(stateBytes).toBase64Url(), supportedDidMethods: (_a = options.supportedDidMethods) !== null && _a !== void 0 ? _a : ['did:dht', 'did:jwk'] });
+    });
+}
+/**
+ * Fetches an encrypted connect request from the authorize endpoint
+ * and decrypts it using the encryption key from the QR/deep link.
+ */
+function getConnectRequest(requestUri, encryptionKey) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const response = yield fetch(requestUri, { signal: AbortSignal.timeout(30000) });
+        const jwe = yield response.text();
+        const jwt = yield decryptRequest({ jwe, encryptionKey });
+        return (yield verifyJwt({ jwt }));
+    });
+}
+// ---------------------------------------------------------------------------
+// Response creation
+// ---------------------------------------------------------------------------
+/** Creates an {@link EnboxConnectResponse} with timestamps. */
+function createConnectResponse(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const currentTimeInSeconds = Math.floor(Date.now() / 1000);
+        return Object.assign(Object.assign({}, options), { iat: currentTimeInSeconds, exp: currentTimeInSeconds + 600 });
+    });
+}
+// ---------------------------------------------------------------------------
+// Permission grants
+// ---------------------------------------------------------------------------
 function shouldUseDelegatePermission(scope) {
-    // 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}
+ * Creates permission grants that assign the requested scopes to a delegate DID.
  */
 function createPermissionGrants(selectedDid, delegateBearerDid, agent, scopes) {
     return __awaiter(this, void 0, void 0, function* () {
         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...`);
+        logger.log(`Creating permission grants for ${scopes.length} scopes...`);
         const permissionGrants = yield 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
+                dateExpires: '2040-06-25T16:09:16.693356Z', // TODO: make dateExpires configurable
                 author: selectedDid,
             });
         }));
         logger.log(`Sending ${permissionGrants.length} permission grants to remote DWN...`);
         const messagePromises = permissionGrants.map((grant) => __awaiter(this, void 0, void 0, function* () {
-            // Quirk: we have to pull out encodedData out of the message the schema validator doesn't want it there
             const _a = grant.message, { encodedData } = _a, rawMessage = __rest(_a, ["encodedData"]);
             const data = Convert.base64Url(encodedData).toUint8Array();
             const { reply } = yield agent.sendDwnRequest({
@@ -357,17 +328,14 @@ function createPermissionGrants(selectedDid, delegateBearerDid, agent, scopes) {
                 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}`);
+                throw new Error(`Could not send permission grant. Error: ${reply.status.detail}`);
             }
             return grant.message;
         }));
         try {
-            const messages = yield Promise.all(messagePromises);
-            return messages;
+            return yield Promise.all(messagePromises);
         }
         catch (error) {
             logger.error(`Error during batch-send of permission grants: ${error}`);
@@ -375,8 +343,12 @@ function createPermissionGrants(selectedDid, delegateBearerDid, agent, scopes) {
         }
     });
 }
+// ---------------------------------------------------------------------------
+// Protocol installation
+// ---------------------------------------------------------------------------
 /**
- * Installs the protocol required by the Client on the Provider if it doesn't already exist.
+ * Installs a DWN protocol on the provider's DWN if it doesn't already exist.
+ * Ensures the protocol is available on both the local and remote DWN.
  */
 function prepareProtocol(selectedDid, agent, protocolDefinition) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -387,23 +359,19 @@ function prepareProtocol(selectedDid, agent, protocolDefinition) {
             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 } = yield 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.
             yield agent.processDwnRequest({
                 author: selectedDid,
                 target: selectedDid,
@@ -413,7 +381,6 @@ function prepareProtocol(selectedDid, agent, protocolDefinition) {
         }
         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 } = yield agent.sendDwnRequest({
                 author: selectedDid,
@@ -427,66 +394,65 @@ function prepareProtocol(selectedDid, agent, protocolDefinition) {
         }
     });
 }
+// ---------------------------------------------------------------------------
+// Full wallet-side flow (provider submits response)
+// ---------------------------------------------------------------------------
 /**
- * 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.
+ * Executes the full wallet-side (provider) flow:
+ * 1. Creates a delegate DID
+ * 2. Installs requested protocols
+ * 3. Creates permission grants
+ * 4. Builds, signs, and encrypts the response
+ * 5. POSTs the encrypted response to the callback URL
+ *
+ * @param selectedDid - The provider's DID that is granting access.
+ * @param connectRequest - The decoded connect request from the app.
+ * @param pin - The PIN for response encryption AAD (required for remote flows).
+ * @param agent - The agent instance for DWN operations.
  */
-function submitAuthResponse(selectedDid, authRequest, randomPin, agent) {
+function submitConnectResponse(selectedDid, connectRequest, pin, agent) {
     return __awaiter(this, void 0, void 0, function* () {
         const delegateBearerDid = yield DidJwk.create();
         const delegatePortableDid = yield 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((permissionRequest) => __awaiter(this, void 0, void 0, function* () {
+        const delegateGrantPromises = connectRequest.permissionRequests.map((permissionRequest) => __awaiter(this, void 0, void 0, function* () {
             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.');
+                throw new Error('All permission scopes must match the protocol URI they are provided with.');
             }
             yield prepareProtocol(selectedDid, agent, protocolDefinition);
-            const permissionGrants = yield Oidc.createPermissionGrants(selectedDid, delegateBearerDid, agent, permissionScopes);
-            return permissionGrants;
+            return EnboxConnectProtocol.createPermissionGrants(selectedDid, delegateBearerDid, agent, permissionScopes);
         }));
         const delegateGrants = (yield Promise.all(delegateGrantPromises)).flat();
-        logger.log('Generating auth response object...');
-        const responseObject = yield 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,
+        logger.log('Building connect response...');
+        const responseObject = yield EnboxConnectProtocol.createConnectResponse({
+            providerDid: selectedDid,
+            delegateDid: delegateBearerDid.uri,
+            aud: connectRequest.clientDid,
+            nonce: connectRequest.nonce,
             delegateGrants,
             delegatePortableDid,
         });
-        // Sign the Response Object using the ephemeral DID's signing key.
-        logger.log('Signing auth response object...');
-        const responseObjectJwt = yield Oidc.signJwt({
+        logger.log('Signing connect response...');
+        const responseObjectJwt = yield EnboxConnectProtocol.signJwt({
             did: delegateBearerDid,
             data: responseObject,
         });
-        const clientDid = yield DidJwk.resolve(authRequest.client_id);
-        const sharedKey = yield Oidc.deriveSharedKey(delegateBearerDid, clientDid === null || clientDid === void 0 ? void 0 : clientDid.didDocument);
-        logger.log('Encrypting auth response object...');
-        const encryptedResponse = yield Oidc.encryptAuthResponse({
+        const clientDid = yield DidJwk.resolve(connectRequest.clientDid);
+        const sharedKey = yield EnboxConnectProtocol.deriveSharedKey(delegateBearerDid, clientDid === null || clientDid === void 0 ? void 0 : clientDid.didDocument);
+        logger.log('Encrypting connect response...');
+        const encryptedResponse = yield EnboxConnectProtocol.encryptResponse({
             jwt: responseObjectJwt,
             encryptionKey: sharedKey,
             delegateDidKeyId: delegateBearerDid.document.verificationMethod[0].id,
-            randomPin,
+            pin,
         });
         const formEncodedRequest = new URLSearchParams({
             id_token: encryptedResponse,
-            state: authRequest.state,
+            state: connectRequest.state,
         }).toString();
-        logger.log(`Sending auth response object to Web5 Connect server: ${authRequest.redirect_uri}`);
-        yield fetch(authRequest.redirect_uri, {
+        logger.log(`Sending connect response to: ${connectRequest.callbackUrl}`);
+        yield fetch(connectRequest.callbackUrl, {
             body: formEncodedRequest,
             method: 'POST',
             headers: {
@@ -496,20 +462,22 @@ function submitAuthResponse(selectedDid, authRequest, randomPin, agent) {
         });
     });
 }
-export const Oidc = {
-    createAuthRequest,
-    encryptAuthRequest,
-    getAuthRequest,
-    decryptAuthRequest,
-    createPermissionGrants,
-    createResponseObject,
-    encryptAuthResponse,
-    decryptAuthResponse,
-    deriveSharedKey,
+// ---------------------------------------------------------------------------
+// Namespace export
+// ---------------------------------------------------------------------------
+export const EnboxConnectProtocol = {
+    buildConnectUrl,
     signJwt,
     verifyJwt,
-    buildOidcUrl,
-    generateCodeChallenge,
-    submitAuthResponse,
+    encryptRequest,
+    decryptRequest,
+    encryptResponse,
+    decryptResponse,
+    deriveSharedKey,
+    createConnectRequest,
+    getConnectRequest,
+    createConnectResponse,
+    createPermissionGrants,
+    submitConnectResponse,
 };
-//# sourceMappingURL=oidc.js.map
+//# sourceMappingURL=enbox-connect-protocol.js.map