feat: platform delegation - onBehalfOf (1.3.0)

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to the ValidPay React Native SDK will be documented in this
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2026-06-19
+
+### Added
+
+- **Platform delegation — `onBehalfOf`** (Fork B). Platforms that seal on behalf
+  of the businesses they serve can name the business per seal: pass
+  `onBehalfOf: { ref, name }` in the options to `createIntent`,
+  `createFileIntent`, `createSelectiveIntent`, or per-item in
+  `createIntentBatch`. `ref` is your own id for the business (the dedupe key —
+  same `ref` rolls up); `name` is who the verifier sees. The verifier sees that
+  business as the issuer, attributed *through* your platform, at the `delegated`
+  trust rung. ValidPay stays blind to the document contents — identity only.
+- `verifyIntent` now surfaces `verificationLevel` (`none` < `delegated` <
+  `domain` < `business`) and `delegatedBy` (`{ platform, platformLevel }` or
+  `null`).
+
+> Requires the ValidPay API with platform-delegation support (live 2026-06-19).
+
 ## [1.0.1] - 2026-06-08
 
 ### Changed

README.md

@@ -129,6 +129,31 @@ client.verifySplitKeyIntent(retrievalId, shareA): Promise<VerifyIntentResult>
 document as you would the regular key. Share B stays on the server and is
 fetched at verify time.
 
+### Platform delegation — `onBehalfOf`
+
+If you integrate as a **platform** and seal on behalf of the businesses you
+serve, name the business on each seal. The verifier sees that business as the
+issuer ("who"), attributed *through* your platform ("through whom"), at the
+`delegated` trust rung. Those businesses never touch ValidPay, and ValidPay
+stays blind to the document contents.
+
+```ts
+const { retrievalId, key } = await client.createIntent(
+  'lease',
+  { unit: '4B', term: '12mo' },
+  { onBehalfOf: { ref: 'landlord_8675309', name: 'Smith Properties LLC' } },
+);
+
+const result = await client.verifyIntent(retrievalId, key);
+result.issuer;             // 'Smith Properties LLC'
+result.verificationLevel;  // 'delegated'
+result.delegatedBy;        // { platform: 'Your Platform', platformLevel: 'domain' }
+```
+
+Same `ref` ⇒ same tracked business (its documents and verification counts roll
+up). A sub-issuer surfaces as `delegated` only once **your** platform account is
+domain-verified.
+
 ### Selective disclosure (Patent E)
 
 ```ts

__tests__/client.test.ts

@@ -101,6 +101,16 @@ describe('createIntent', () => {
     expect(JSON.parse(decrypted)).toEqual({ payee: 'Alice', amount: 1500 });
   });
 
+  test('sends on_behalf_of for platform delegation', async () => {
+    pushResponse({ retrieval_id: 'vp_d' }, 201);
+    const c = newClient();
+    await c.createIntent('lease', { a: 1 }, {
+      onBehalfOf: { ref: 'cust_42', name: 'Smith Properties' },
+    });
+    const body = calls[0].body as Record<string, unknown>;
+    expect(body.on_behalf_of).toEqual({ ref: 'cust_42', name: 'Smith Properties' });
+  });
+
   test('passes through valid_from / valid_until', async () => {
     pushResponse({ retrieval_id: 'vp_a' }, 201);
     const c = newClient();
@@ -226,6 +236,26 @@ describe('verifyIntent', () => {
     expect(auth).toBeUndefined();
   });
 
+  test('surfaces verificationLevel + delegatedBy for a delegated issuer', async () => {
+    const { key, encrypted_payload, commitment_hash } = await buildActiveIntent({ a: 1 });
+    pushResponse({
+      intent_id: 'vp_d',
+      encrypted_payload,
+      commitment_hash,
+      commitment_version: 2,
+      issuer: 'Smith Properties',
+      issuer_verified: false,
+      registered_at: '2026-05-01T00:00:00Z',
+      status: 'active',
+      verification_level: 'delegated',
+      delegated_by: { platform: 'Acme Platform', platform_level: 'domain' },
+    });
+    const c = newClient();
+    const result = await c.verifyIntent('vp_d', key);
+    expect(result.verificationLevel).toBe('delegated');
+    expect(result.delegatedBy).toEqual({ platform: 'Acme Platform', platformLevel: 'domain' });
+  });
+
   test('throws intent_revoked when status=revoked', async () => {
     pushResponse({
       intent_id: 'vp_1',

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@validpay/react-native-sdk",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "ValidPay verification SDK for React Native — 8 patented protections for document authenticity",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/client.ts

@@ -28,9 +28,22 @@ export interface ValidPayClientOptions {
   timeoutMs?: number;
 }
 
+/**
+ * Platform delegation (Fork B). Seal on behalf of one of the businesses your
+ * platform serves: `ref` is your own id for that business (the dedupe key —
+ * same ref rolls up), `name` is who the verifier sees. The verifier sees that
+ * business as the issuer, through your platform, at the `delegated` rung.
+ */
+export interface OnBehalfOf {
+  ref: string;
+  name: string;
+}
+
 export interface TimeLockOptions {
   validFrom?: string | null;
   validUntil?: string | null;
+  /** Seal on behalf of one of your businesses (platform delegation). */
+  onBehalfOf?: OnBehalfOf;
 }
 
 export interface CreateBoundIntentOptions {
@@ -47,6 +60,8 @@ export interface BatchIntentInput {
   payload: unknown;
   validFrom?: string | null;
   validUntil?: string | null;
+  /** Seal on behalf of one of your businesses (platform delegation). */
+  onBehalfOf?: OnBehalfOf;
 }
 
 interface IntentApiResponse {
@@ -73,6 +88,8 @@ interface IntentApiResponse {
   valid_until?: string | null;
   revoked_at?: string | null;
   revocation_reason?: string | null;
+  verification_level?: 'none' | 'delegated' | 'domain' | 'business';
+  delegated_by?: { platform: string; platform_level: 'domain' | 'business' } | null;
 }
 
 /**
@@ -126,6 +143,7 @@ export class ValidPayClient {
     };
     if (opts.validFrom != null) body.valid_from = opts.validFrom;
     if (opts.validUntil != null) body.valid_until = opts.validUntil;
+    if (opts.onBehalfOf != null) body.on_behalf_of = opts.onBehalfOf;
 
     const data = await this.request<{ retrieval_id?: string }>(
       'POST',
@@ -187,6 +205,7 @@ export class ValidPayClient {
       };
       if (item.validFrom != null) reqItem.valid_from = item.validFrom;
       if (item.validUntil != null) reqItem.valid_until = item.validUntil;
+      if (item.onBehalfOf != null) reqItem.on_behalf_of = item.onBehalfOf;
       requestItems.push(reqItem);
     }
 
@@ -279,6 +298,13 @@ export class ValidPayClient {
       validFrom: data.valid_from ?? null,
       validUntil: data.valid_until ?? null,
       timeLockStatus: computeTimeLockStatus(data.valid_from, data.valid_until),
+      verificationLevel: data.verification_level,
+      delegatedBy: data.delegated_by
+        ? {
+            platform: data.delegated_by.platform,
+            platformLevel: data.delegated_by.platform_level,
+          }
+        : null,
     };
   }
 
@@ -315,6 +341,7 @@ export class ValidPayClient {
     };
     if (opts.validFrom != null) body.valid_from = opts.validFrom;
     if (opts.validUntil != null) body.valid_until = opts.validUntil;
+    if (opts.onBehalfOf != null) body.on_behalf_of = opts.onBehalfOf;
 
     const data = await this.request<{ retrieval_id?: string }>(
       'POST',
@@ -396,6 +423,13 @@ export class ValidPayClient {
       validFrom: data.valid_from ?? null,
       validUntil: data.valid_until ?? null,
       timeLockStatus: computeTimeLockStatus(data.valid_from, data.valid_until),
+      verificationLevel: data.verification_level,
+      delegatedBy: data.delegated_by
+        ? {
+            platform: data.delegated_by.platform,
+            platformLevel: data.delegated_by.platform_level,
+          }
+        : null,
     };
   }
 
@@ -407,7 +441,7 @@ export class ValidPayClient {
     documentType: string,
     payload: Record<string, unknown>,
     disclosurePolicy: Record<string, string[]>,
-    opts: { splitKey?: boolean; validFrom?: string | null; validUntil?: string | null } = {},
+    opts: { splitKey?: boolean; validFrom?: string | null; validUntil?: string | null; onBehalfOf?: OnBehalfOf } = {},
   ): Promise<CreateIntentResult> {
     if (!documentType) {
       throw new ValidPayError('invalid_argument', 'documentType is required');
@@ -470,6 +504,7 @@ export class ValidPayClient {
     if (keyFragmentB != null) body.key_fragment_b = keyFragmentB;
     if (opts.validFrom != null) body.valid_from = opts.validFrom;
     if (opts.validUntil != null) body.valid_until = opts.validUntil;
+    if (opts.onBehalfOf != null) body.on_behalf_of = opts.onBehalfOf;
 
     const data = await this.request<{ retrieval_id?: string }>(
       'POST',
@@ -579,6 +614,13 @@ export class ValidPayClient {
       validFrom: data.valid_from ?? null,
       validUntil: data.valid_until ?? null,
       timeLockStatus: computeTimeLockStatus(data.valid_from, data.valid_until),
+      verificationLevel: data.verification_level,
+      delegatedBy: data.delegated_by
+        ? {
+            platform: data.delegated_by.platform,
+            platformLevel: data.delegated_by.platform_level,
+          }
+        : null,
     };
   }
 

src/types.ts

@@ -32,6 +32,10 @@ export interface VerifyIntentResult {
   validFrom: string | null;
   validUntil: string | null;
   timeLockStatus: 'valid' | 'not_yet_valid' | 'expired' | null;
+  /** Graded trust rung: 'none' < 'delegated' < 'domain' < 'business'. */
+  verificationLevel?: 'none' | 'delegated' | 'domain' | 'business';
+  /** Set when sealed on behalf of, via a platform (delegation); else null. */
+  delegatedBy?: { platform: string; platformLevel: 'domain' | 'business' } | null;
 }
 
 /**