Residency and cross-border transfers

Where data physically is has legal weight. Some regimes say a copy must stay
inside the country (Kenya, Vietnam); some say the primary copy must (China,
Russia); most say nothing about where it lives but a great deal about where
it may be sent — to a country with an adequacy decision, under standard
contractual clauses, with consent, or only after a regulator's approval.

Three pieces answer the three questions.

Question	Answered by
May this database be here at all?	the residency check in `@Jurisdiction`
May this row be sent there?	`CrossBorderLog.checkTransferAllowed()`
Where has it been sent, and on what basis?	`CrossBorderLog.logTransfer()` and the transfer table

Where the database may be

Every jurisdiction carries a residency rule:

interface ResidencyRule {
  localize: 'none' | 'copy' | 'primary';
  regions: string[];              // 'eu', 'eea', 'us', 'cn', … — the region vocabulary
  transferRequires: 'nothing' | 'adequacy' | 'safeguards' | 'consent' | 'approval';
}

Declare where the database is, in the same vocabulary, and the check runs at
class load:

import { Jurisdiction, Table, Model, applyCompliance } from 'ts-prorm-orm';

@Jurisdiction('CN')
@Table({ tableName: 'customers' })
class Customer extends Model { /* … */ }
// → refused: residency-unknown — China requires the primary copy to be in cn, and no region is declared.

@Jurisdiction('CN', { region: 'us' })          // the trailing object carries what no column can
@Table({ tableName: 'customers' })
class CustomerInUs extends Model { /* … */ }
// → refused: residency-violated — the database is in "us"; China requires the primary copy to be in cn.

@Jurisdiction('CN', { region: 'cn' })
@Table({ tableName: 'customers' })
class CustomerInCn extends Model { /* … */ }
// → loads.

applyCompliance(Customer, { jurisdictions: ['EU'], region: 'us', fields: { /* … */ } });
// → loads, with an informational finding: transfer-outside — the database is
//   outside eu/eea; transfers need adequacy.

The region is matched exactly, case-insensitively, against the regime's
list — 'eu' or 'eea' for the EU, not a provider's 'eu-west-1'; map your
provider's region names onto that vocabulary before passing one. On the
managed platform the database's own region is what you would pass, and the
compliance.residency.* policies hold it there
afterwards — a database that is moved out of its declared region is paused
until it is moved back.

When several regimes are named, residency resolves like everything else:
localize if any regime does, and then only that regime's regions count.
@Jurisdiction('EU', 'RU') must be in Russia.

@DatabaseSecurity({ region, allowedCountries }) records the same facts as
metadata on a database class, for tooling that reads it; it enforces nothing
by itself.

Whether a transfer is allowed

CrossBorderLog holds a table of regions with an adequacy flag and the
restrictions that apply when it is false, and answers the question before you
send:

import { CrossBorderLog } from 'ts-prorm-orm';

await CrossBorderLog.checkTransferAllowed('EU', 'US', 'PII');
// { allowed: false, requiresReview: true,
//   reason: 'Transfer to US requires additional safeguards (SCCs, BCRs, or adequacy decision)', … }

await CrossBorderLog.checkTransferAllowed('EU', 'UK', 'PII');
// { allowed: true, … }

await CrossBorderLog.checkTransferAllowed('EU', 'US', 'GENERAL');
// { allowed: true, reason: 'Transfer to US - target does not have adequate protection determination', … }

The built-in table marks the EU/EEA, UK, Canada, Japan, Korea, Argentina and
Uruguay as adequate, and gives the US (requires_scc), China
(requires_assessment), India, Brazil, Thailand, Singapore, Australia and
New Zealand their restrictions. PII and PHI are refused to a non-adequate
region; every other category is allowed with requiresReview: true. A code
the table does not hold ('MX', say) is refused with

Unknown source
region

or Unknown target region; only the literal 'UNKNOWN' is allowed
and flagged for review.

Your legal position may differ — a company under the EU–US Data Privacy
Framework treats the US differently from one that is not — so the table is
yours to set:

CrossBorderLog.configureRegions({
  EU: { adequateProtection: true, regulations: ['GDPR'] },
  US: { adequateProtection: true, regulations: ['CCPA'], requirements: { mechanism: 'EU-US DPF' } },
  CN: { adequateProtection: false, regulations: ['PIPL'], restrictions: ['requires_assessment'] },
});
CrossBorderLog.listRegions();
CrossBorderLog.resetRegions();     // back to the built-in table

Recording what was sent

Article 30 records, transfer impact assessments and most audits want a log of
every cross-border transfer with its legal basis.

CrossBorderLog.enable(prorm, Customer, {
  getUserId: () => currentUser()?.id,
  getIpAddress: () => currentRequest()?.ip,
  tableName: 'cross_border_transfers',     // default
});

await CrossBorderLog.logTransfer('EU', 'US', 'PII', rows, {
  initiatedBy: currentUser()?.id,
  purpose: 'support ticket escalation',
  legalBasis: 'SCCs 2021/914, module 2',
  status: 'completed',                      // 'pending' | 'completed' | 'blocked' | 'reviewed'
});

await CrossBorderLog.getTransferHistory(Customer, customerId);
await CrossBorderLog.getAllTransfers(Customer, { sourceRegion: 'EU', status: 'blocked' });

The line: logTransfer() is called by you. applyHooks() / the
autoLog option stash the context on the model and do not log
automatically — the ORM does not know that a findAll() is about to leave
the continent. Put the call where the data leaves: the export endpoint, the
replication job, the support tool.

At the point the data leaves

A support tool that hands an EU customer's ticket history to a US-based
vendor checks, sends, and logs, and logs the refusals too:

import { CrossBorderLog } from 'ts-prorm-orm';

declare const Customer: any, Ticket: any;
declare const vendor: { send(rows: unknown[]): Promise<void> };

export async function escalateToVendor(customerId: string, agentId: string) {
  const rows = await Ticket.findAll({ where: { customerId } });
  const verdict = await CrossBorderLog.checkTransferAllowed('EU', 'US', 'PII');

  if (!verdict.allowed) {
    await CrossBorderLog.logTransfer('EU', 'US', 'PII', rows, {
      recordId: customerId, initiatedBy: agentId,
      purpose: 'support ticket escalation', status: 'blocked',
      metadata: { reason: verdict.reason },
    });
    throw new Error(`transfer refused: ${verdict.reason}`);
  }

  await vendor.send(rows);
  await CrossBorderLog.logTransfer('EU', 'US', 'PII', rows, {
    recordId: customerId, initiatedBy: agentId,
    purpose: 'support ticket escalation',
    legalBasis: 'SCCs 2021/914, module 2',
    status: verdict.requiresReview ? 'pending' : 'completed',
  });
}

With the built-in table this refuses, because the US is not marked adequate
and the tickets are PII. Once configureRegions() records your transfer
mechanism, as in the previous section, the same call passes and the log
carries the mechanism as legalBasis.

Putting it together

For a database serving EU residents from the US:

Declare where the database is

@Jurisdiction('EU', { region: 'us' }) loads, and the sheet carries the
transfer-outside finding so nobody forgets the data is exported by its
location.

Record your transfer mechanism

CrossBorderLog.configureRegions() with your actual mechanism (DPF, SCCs).

Check and log where data leaves

checkTransferAllowed('EU', 'US', category) in the paths that send data
onward; logTransfer() on the way out.

Make the importer unable to read it

Field encryption or pseudonymisation on the special categories, so the
Schrems II question — can the importer read it? — has a technical answer.
@Security({ frameworks: [SecurityFramework.Schrems_II] })
requires exactly those two.

Next: Evidence — the sheet that shows all of this.

Residency and cross-border transfers

Where the database may be#

Whether a transfer is allowed#

Recording what was sent#

At the point the data leaves#

Putting it together#

Declare where the database is#

Record your transfer mechanism#

Check and log where data leaves#

Make the importer unable to read it#