# V7 Hypersync SDK migration guide

## Version 6.x to version 7.0

The Hypersync SDK version 7.0 includes security improvements and internal updates that may require small changes to Hypersync apps that use version 6.x.

**This is an optional upgrade.** Hypersyncs built with version 6.x of the SDK will continue to function normally. Version 7 introduces an SSRF guard on all outbound requests and upgrades several core dependencies. Apps that only target publicly resolvable hosts can usually upgrade with minimal effort.

### Package versions

All three packages are released together at the same version. Update the `dependencies` section of your app's `package.json` file as follows:

```json
{
  "dependencies": {
    "@hyperproof/hypersync-models": "^7.0.1",
    "@hyperproof/hypersync-sdk": "^7.0.1",
    "@hyperproof/integration-sdk": "^7.0.1"
  }
}
```

### Install the updated packages

Ensure the package dependencies are installed:

```
yarn install
```

Verify that the build is error free, correct any issues, and rebuild if necessary.

### Build and deploy your Hypersync

Build your updated Hypersync:

```
yarn build
```

Make sure you are signed into your Hyperproof organization:

```
hp signin
```

Deploy your updated Hypersync:

```
hp customapps import -d .
```

## Required code updates

### Outbound requests are now SSRF-guarded

All requests made through the SDK's HTTP layer (`ApiClient` and therefore every `RestDataSourceBase` data set) now pass through a guarded agent. The guard:

- Allows only `http:` and `https:` schemes
- Resolves hostnames using a public DNS-over-HTTPS resolver
- Rejects private, reserved, or link-local IP ranges
- Rejects IP-literal hosts (e.g. `https://10.0.0.5/api`)
- Pins sockets to validated public IPs on every redirect


A blocked request fails with HTTP `400` and error code `EGRESS_BLOCKED`.

**If your app targets a host that is not publicly resolvable, it may stop working.** There is no environment-variable opt-out. Contact Hyperproof if your integration legitimately requires a private-network target.

No code changes are needed for apps that only reach public endpoints.

### Logger is now synchronous

All logger methods (`Logger.info`, `Logger.warn`, `Logger.error`, etc.) now return `void` instead of `Promise<void>`.

Remove any `await` calls on logger methods:

```ts
// Before (v6)
await Logger.info('Fetching users');

// After (v7)
Logger.info('Fetching users');
```

`Logger.init()` has been removed and is no longer needed.

### JSONata upgraded to 2.2.2

The `jsonata` library was upgraded from 1.8.7 to 2.2.2. All JSONata evaluations now return promises.

Update any direct or indirect calls that use JSONata expressions (commonly inside `transformObject`, `getPropertyValue`, or `isPredicateMatch` overrides):

```ts
// Before (v6)
const result = jsonata(expr).evaluate(data);

// After (v7)
const result = await jsonata(expr).evaluate(data);
```

The following `RestDataSourceBase` methods are now `async` because they internally use JSONata:

- `transformObject`
- `getPropertyValue`
- `isPredicateMatch`


Update any overrides of these methods to be `async` and `await` their results where necessary.

### Renamed types

`ICriteriaPageMessage` has been replaced by `IInfoMessage`.

- Replace all references to `ICriteriaPageMessage` with `IInfoMessage`.
- The `info` property on criteria pages is now typed as `IInfoMessage[]`.
- `IInfoMessage` adds an optional `action` field that can render an actionable prompt.


### Updated method signatures

#### HypersyncApp.onLastUserDeleted

The signature changed to support custom-auth Hypersyncs:

```diff
- public async onLastUserDeleted(user: TUserProfile, accessToken: string): Promise<void>
+ public async onLastUserDeleted(user: TUserProfile, credentials?: string | CustomAuthCredentials): Promise<void>
```

Update any implementation of `onLastUserDeleted` to accept the new second parameter.

#### Sync.page type change

`Sync.page` is now a `string` (opaque page token) instead of a `number`. Update any code that treats the page value as numeric.

### Credential field validation

The `credentialsMetadata` schema is now enforced server-side. Values that are not in the defined options will be rejected with a `400` error.

If your code programmatically sets a credential field to a value that is not one of the offered select options (for example, an auto-discovered region), add that value to the field's options using the new `hidden: true` flag:

```json
{
  "value": "us-gov-west-1",
  "label": "US Gov West",
  "hidden": true
}
```

### Layout is now automatic

Every proof now receives a central layout pass. You no longer need to call `calcLayoutInfo` yourself. Explicit widths you set on fields are preserved; orientation and zoom are computed automatically.

Remove any manual calls to `calcLayoutInfo` and delete the now-removed `IProofSpec.autoLayout` flag from your proof specifications.

## Optional new capabilities

These features are additive and do not require changes, but may allow you to simplify your code:

- Override `filterProofFields(fields, proofType, criteriaValues)` or `filterProofCriteria(criteria, proofType)` on `HypersyncApp` to dynamically shape proofs based on criteria.
- Implement `applyAdditionalAuthorizationConfig` on `HypersyncApp` to add fields to the authorization config.
- Use the new `HypersyncPeriod.YearToDate` proof period.
- Set `IProofSpec.sourceDateTimeZone` to format date-only fields correctly.
- Set `IDataSet.keepEmptyRows = true` to preserve all-empty rows when they are meaningful.
- Use the new `RestDataSourceBase.getBaseUrl()` and `getAdditionalContext()` helpers.


## Finishing up

After making the changes above:

1. Run `yarn install`
2. Run `yarn build` and resolve any TypeScript or compilation errors
3. Deploy with `hp customapps import -d .`
4. Test connecting to your Hypersync and run existing syncs to verify behavior


Version 6 Hypersyncs remain fully supported. Upgrade to version 7 only when you are ready to take advantage of the security improvements and new capabilities.  Contact support with any additional questions.

```

```