@rytass/bpm-core-nestjs-module 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -9,6 +9,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Releases are managed by [`nx release`](https://nx.dev/recipes/nx-release) with
 Conventional Commits — see `nx.json` for the release config.
 
+## 0.1.10 — 2026-05-28
+
+### Documentation
+
+- **Pattern A response status contract table** added — explicit success
+  / auth-fail / validation-fail HTTP status codes for `/auth/login`,
+  `/auth/me`, `/auth/logout`. Also notes that `roles` and `permissions`
+  must be arrays (not `null`/`undefined`), and shows the
+  `projectMemberToApiMember` skeleton mapping `ApiMember.email: string`
+  (not `string | null`).
+- **"Concrete wiring" snippet** for the recommended same-database
+  separate-schema option B: dual `TypeOrmModule.forRootAsync` with
+  `name: 'bpm'` so the host's existing connection and BPM's stay
+  isolated. Also shows handing `typeormConnectionName: 'bpm'` to
+  `BPMRootModule.forRootAsync`.
+- **`createBPMMemberBaseResolverProvider<HostMember>` generic** added
+  to the README example with a callout about why omitting it causes
+  TS to infer `unknown`.
+- "Current version" line refreshed to `0.1.10`.
+
+### Why a patch
+
+Documentation only.
+
+## 0.1.9 — 2026-05-28
+
+### Documentation
+
+- **README "Machine-to-machine authentication" section** added under
+  Auth Context. Documents three patterns for server-side scripts (org
+  seeds, cron workers, integration tests) to authenticate against BPM:
+  (1) service member + login flow with cookie-jar fetch (recommended),
+  (2) service token header for hosts that issue long-lived JWTs,
+  (3) direct cookie injection for testing only.
+- **README "Coexisting with a host's existing `<AuthProvider>`"** added
+  under Auth Context. Explains that BPM's React provider is a separate
+  context safe to nest under a host provider, with three rules of
+  thumb (scope to sub-tree, share cookie jar same-origin, don't
+  double-wrap `<AuthProvider>` directly).
+
+### Why a patch
+
+Documentation only.
+
 ## 0.1.8 — 2026-05-28
 
 ### Documentation

package/README.md

@@ -14,7 +14,7 @@ directory integration, storage adapters, and deployment.
 
 ## Package Status
 
-Current version: `0.1.7`
+Current version: `0.1.10`
 
 The package is intended for NestJS backend hosts. It does not include the
 Next.js backoffice UI and does not provide a production auth system by itself.
@@ -273,6 +273,31 @@ member shape to BPM's expectations, project Casbin roles into the BPM
 role-literal strings (see "Mapping from a host RBAC system" below),
 and compute `expiresAt` from the token TTL.
 
+```ts
+function projectMemberToApiMember(member: HostMember): ApiMember {
+  return {
+    memberId: member.id,
+    email: member.email ?? '',         // ApiMember.email is `string`, not `string | null`
+    name: member.name,
+    roles: projectHostRolesToBPMRoles(member.roles), // [] if no admin/designer claim
+    permissions: [],                   // optional — return [] if not used
+    expiresAt: new Date(Date.now() + JWT_TTL_MS).toISOString(),
+  };
+}
+```
+
+Response status contract that BPM's React client expects:
+
+| Endpoint | Success | Auth fail | Validation fail |
+|---|---|---|---|
+| `POST /auth/login` | `200` + `ApiMember` JSON, set HTTP-only cookie | `401` | `400` |
+| `GET /auth/me` | `200` + `ApiMember` JSON | `401` (client treats as anonymous, **not error**) | n/a |
+| `POST /auth/logout` | `204` (or `200` with empty body) | `401` ignored — client clears local state anyway | n/a |
+
+`roles` and `permissions` MUST be arrays (use `[]` for no claim), not
+`null` or `undefined` — the React client's `member.roles.includes(...)`
+checks would crash otherwise.
+
 #### Pattern B — Run BPM on a separate auth host
 
 When BPM lives on its own subdomain (e.g. `bpm.example.com`) separate
@@ -296,6 +321,125 @@ the simplest path is to **not mount `<AuthProvider>` from
 `useAuth()` shim that returns the host's session. This is rare — most
 consumers find Pattern A simpler.
 
+### Machine-to-machine authentication
+
+Server-side scripts (org seeds, cron workers, integration tests) call
+`configureBPMClient` to set the GraphQL base URL and optional default
+headers, then must establish a session. Three patterns work:
+
+#### Pattern 1 — Service member + login flow (recommended)
+
+Create a dedicated BPM admin member (e.g. `bpm-sync@svc.example.com`),
+store its credentials in Vault, and let the script call `loginApi`
+during bootstrap. The login response sets an HTTP-only session cookie
+that subsequent `requestGraphQl` calls automatically include.
+
+```ts
+import { configureBPMClient, loginApi } from '@rytass/bpm-core-client';
+
+async function bootstrap(): Promise<void> {
+  configureBPMClient({
+    baseUrl: process.env.BPM_API_URL ?? 'http://localhost:17603',
+    fetch: globalThis.fetch,
+  });
+  await loginApi({
+    identifier: process.env.BPM_SYNC_IDENTIFIER!,
+    password: process.env.BPM_SYNC_PASSWORD!,
+  });
+  // Subsequent calls to readOrganizationDashboard / createOrgUnit / etc.
+  // automatically forward the session cookie.
+}
+```
+
+Caveats: `globalThis.fetch` on Node 20+ does **not** maintain a cookie
+jar across calls by default — set up one of:
+
+- `undici`'s `Agent` with `cookies` enabled, then `setGlobalDispatcher(agent)`
+- the `tough-cookie` + `node-fetch-cookies` pairing
+- BPM's `configureBPMClient({ fetch: cookieAwareFetch })` injection
+
+Without a cookie jar, the login succeeds but no subsequent call carries
+the session. Most production deployments already use `undici` with
+cookie support; verify before shipping.
+
+#### Pattern 2 — Service token header (when supported by host)
+
+If your wrapper host issues a long-lived service token (e.g. a JWT
+signed with a known shared secret), pass it through
+`configureBPMClient`'s `headers`:
+
+```ts
+configureBPMClient({
+  baseUrl: process.env.BPM_API_URL!,
+  headers: { Authorization: `Bearer ${process.env.BPM_SERVICE_TOKEN!}` },
+});
+```
+
+This requires the wrapper host's auth middleware to honor `Authorization`
+headers (member-base hosts can be configured to do so via
+`authStrategy: 'jwt'` in addition to `cookieMode: true`).
+
+#### Pattern 3 — Direct cookie injection (testing only)
+
+For integration tests where you've already obtained a session cookie
+out-of-band (e.g. from a Playwright fixture), pass it raw:
+
+```ts
+configureBPMClient({
+  baseUrl: 'http://localhost:17603',
+  headers: { Cookie: 'access_token=<jwt>; refresh_token=<jwt>' },
+});
+```
+
+Do not use this in production scripts — cookies expire and the script
+must handle refresh, which means you actually want Pattern 1.
+
+### Coexisting with a host's existing `<AuthProvider>`
+
+Many host applications (Shuttle, custom admin panels) already mount
+their own `<AuthProvider>` at the root of the Next.js tree. BPM's
+`<AuthProvider>` (mounted indirectly via `<BPMNextProviders>`) is a
+**separate context** that only tracks BPM session state. The two do
+not conflict — they coexist as parallel React contexts:
+
+```tsx
+// app/layout.tsx — host's root layout (untouched)
+import { HostAuthProvider } from '@your-host/auth';
+
+export default function RootLayout({ children }) {
+  return (
+    <html><body>
+      <HostAuthProvider>{children}</HostAuthProvider>
+    </body></html>
+  );
+}
+
+// app/operations/approval/layout.tsx — BPM sub-tree
+'use client';
+import { BPMNextProviders } from '@rytass/bpm-core-react/next';
+
+export default function ApprovalLayout({ children }) {
+  return (
+    <BPMNextProviders loginPath="/login">
+      {children}
+    </BPMNextProviders>
+  );
+}
+```
+
+Rules of thumb:
+
+- **Scope `<BPMNextProviders>` to the BPM sub-tree** — never put it at
+  the root. Otherwise every host page goes through BPM's auth gate,
+  which redirects unauthenticated users to BPM's `/login`.
+- **BPM auth and host auth share the cookie jar** when same-origin.
+  If `<BPMNextProviders loginPath="/login">` and the host's auth share
+  `/login`, the same login form can satisfy both — implement the host
+  login endpoint to also satisfy `/auth/login` from BPM's contract.
+- **Do not import `<AuthProvider>` from `@rytass/bpm-core-react`
+  directly** if you've already mounted `<BPMNextProviders>` —
+  double-wrapping creates redundant `/auth/me` polls.
+
 ## Role and Permission Contract
 
 BPM guards inspect `BPMAuthContext.roles` and `BPMAuthContext.permissions` with
@@ -412,7 +556,10 @@ export const hostMemberProviders: readonly Provider[] = [
     provide: HOST_MEMBER_DIRECTORY,
     useClass: HostMemberDirectory,
   },
-  createBPMMemberBaseResolverProvider({
+  createBPMMemberBaseResolverProvider<HostMember>({
+    // ^^^^^^^^^^^^ explicit generic is recommended — without it,
+    // TS infers `unknown` for the adapter callbacks below and you get
+    // "Parameter 'member' implicitly has an 'any' type" errors.
     adapterOptions: {
       readEmail: (member): string => member.email,
       readMemberId: (member): string => member.id,
@@ -544,7 +691,7 @@ interface HostOrgUnit {
   readonly hostId: string;          // e.g. ERP primary key — your host-FK
   readonly code: string;            // stable across sync runs
   readonly name: string;
-  readonly type: OrgUnitType;       // 'company' | 'division' | 'department' | 'team'
+  readonly type: OrgUnitType;       // 'COMPANY' | 'DIVISION' | 'DEPARTMENT' | 'TEAM'
   readonly parentCode: string | null;
 }
 
@@ -791,6 +938,40 @@ BPM's `buildTypeOrmModuleOptions` create **two distinct connections**
 to the same Postgres cluster with different `schema:` settings — that
 is the cleanest separation Nest's TypeORM module supports.
 
+Concrete wiring:
+
+```ts
+// apps/api/src/app/app.module.ts
+@Module({
+  imports: [
+    // Host's existing TypeORM connection (default name, host's schema).
+    TypeOrmModule.forRootAsync({
+      imports: [HostVaultModule],
+      inject: [HostVaultService],
+      useFactory: (vault) => buildHostDataSourceOptions(vault),  // schema: 'public'
+    }),
+    // BPM's own connection (named, separate schema, separate Vault path).
+    TypeOrmModule.forRootAsync({
+      name: 'bpm',                              // <-- distinct connection name
+      imports: [BPMVaultModule],
+      inject: [BPMVaultService],
+      useFactory: buildTypeOrmModuleOptions,    // reads DB_SCHEMA=bpm_core from Vault
+    }),
+    // Hand BPM the connection name so its repositories bind to the right pool.
+    BPMRootModule.forRootAsync({
+      typeormConnectionName: 'bpm',
+      // ...
+    }),
+  ],
+})
+```
+
+If the host runs only one Vault path (e.g. `shuttle/develop`) and you
+want to keep secrets there, expose `bpm_core/*` keys under the host
+path with a prefix and provide a custom factory that reads them — BPM
+doesn't require its own Vault path, only that the secrets are
+available to `buildTypeOrmModuleOptions`.
+
 Vault paths can be split independently: keep `shuttle/develop` for the
 host and create `bpm_core/develop` for BPM secrets. BPM's helper reads
 its own path; the host's auth module reads its own. They do not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-nestjs-module",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Embeddable NestJS BPM approval workflow module: workflow engine, approval templates, forms, organization/member contracts, attachments, signatures, notifications, delegation, and TypeORM migrations.",
   "keywords": [
     "bpm",
@@ -141,7 +141,7 @@
     "@nestjs/core": "^11.0.0",
     "@nestjs/graphql": "^13.4.0",
     "@nestjs/typeorm": "^11.0.1",
-    "@rytass/bpm-core-shared": "^0.1.8",
+    "@rytass/bpm-core-shared": "^0.1.10",
     "@rytass/secret-adapter-vault-nestjs": "^0.4.5 || ^0.5.0",
     "express": "^4.0.0 || ^5.0.0",
     "graphql": "^16.0.0",