@xemahq/org-erasure-nest

The org-erasure participant contract, its fenced internal endpoint, and the protected-organization guard

Overview

An org-erasure participant is any service that holds an organisation's data and can be told to destroy it. An orchestrator discovers participants from the service registry by a declared capability and fans out to one internal route on each of them.

This package is the participant half of that contract, and nothing else:

• the two protocol strings — the capability a participant declares, and the route path the orchestrator POSTs to;
• OrgErasureController, the route, behind two independent fences;
• OrgProtectionGuard and its identity probe, which answer may this organisation be destroyed at all? and fail closed on every uncertainty;
• OrgErasureEndpointModule.forRunner(...), which mounts the route over an eraser you supply.

It deliberately knows nothing about storage. The Prisma-backed eraser — walk every model carrying the org column and delete its rows in an FK-safe order — lives in @xemahq/biome-database-nest, which composes this package.

Install

pnpm add @xemahq/org-erasure-nest

Peers: @nestjs/common, @nestjs/core, @nestjs/swagger, @xemahq/identity-client, @xemahq/kernel-contracts, @xemahq/platform-common, @xemahq/service-registry-nest, @xemahq/xema-decorators.

Usage

A participant whose data Prisma cannot reach supplies its own eraser:

import { OrgErasureEndpointModule } from '@xemahq/org-erasure-nest';

@Module({
  imports: [
    OrgErasureEndpointModule.forRunner({
      useFactory: (cache: CacheClient) => ({
        erase: async (orgId) => cache.dropOrgNamespace(orgId),
      }),
      inject: [CacheClient],
    }),
  ],
})
export class AppModule {}

A participant that stores rows in Postgres uses the Prisma binding instead:

import { OrgErasureModule } from '@xemahq/biome-database-nest';

imports: [OrgErasureModule.forRoot({ prismaServiceToken: PrismaService })];

Either way the service must declare ORG_DATA_ERASURE_CAPABILITY in its service descriptor, or the orchestrator will never find it.

Two fences, and why both

| guard | answers | | --- | --- | | ServiceActorGuard | is the caller a non-delegated service? | | OrgProtectionGuard | may this organisation be destroyed at all? |

Neither substitutes for the other. ServiceActorGuard proves a service token, not which service, so any service in the fleet reaches this route directly — which is why an orchestrator-side protection check cannot be the only one.

OrgProtectionGuard fails closed on every uncertainty: an unreachable or non-2xx identity service, a malformed body, a record without a boolean protection field, or an organisation that does not resolve in any realm this service can see. Erasure is irreversible; a wrongful refusal costs one retry.

The guard injects only tokens the platform bootstrap exports globally and builds its own probe, so it arms identically whether the endpoint is mounted through forRunner or declared in a module of your own. A service that has not wired the platform bootstrap refuses to start, with a named error, rather than serving an unfenced irreversible route.

Licence

Apache-2.0