@endora-commerce/platform 0.100.0

package/dist/tenancy/resolve-tenant-context.d.ts

@@ -0,0 +1,91 @@
+import type { TenantContext } from './tenant-context.js';
+/**
+ * Actor → TenantContext derivation (feature 050, FR-002 / data-model §1).
+ *
+ * The context is computed server-side from the already-authenticated actor and
+ * (for scoped admins) their assignment set. It is never taken from request
+ * inputs. Kept as a pure function so it is trivially unit-testable.
+ *
+ * ## `TenantActorInput` is **not** `@endora-commerce/contracts`' `Actor`, and
+ * that survived T118b deliberately
+ *
+ * T118b collapsed three of the platform's four actor restatements — the two
+ * `*ActorSlice` interfaces and `product-audience.ts`' inline cast — because each
+ * existed for one reason, that D-52/D-53 forbade the platform an import of the
+ * module declaring the shape, and that reason is gone: the shape is
+ * `@endora-commerce/contracts`' and the `FastifyRequest` augmentation is
+ * `../http/request-actor.ts`'.
+ *
+ * This one is not that. It is the **input** of a derivation, not a reading of
+ * `request.actor`, and it differs from `Actor` in three ways that are the
+ * function's whole subject:
+ *
+ *  - {@link CustomerActorInput.rollupSubtreeOrganizationIds} is **server-derived**
+ *    — the caller resolves the buyer's org subtree and passes it. Putting it on
+ *    `Actor` would put a capability decision on the request's identity, which is
+ *    exactly what "never taken from request inputs" refuses.
+ *  - {@link ApiKeyActorInput} carries the binding and drops `scopes` and
+ *    `salesChannelId`: scope is a route gate's question and the channel is the
+ *    sales-channel resolver's, and neither reaches a tenant context.
+ *  - There is **no anonymous kind**. Anonymous traffic gets no tenant context;
+ *    the mapping's caller answers it before calling, and a fourth member here
+ *    would be a case this function has no answer for.
+ *
+ * So the two shapes agree on the fields they share and are different types on
+ * purpose. The caller that bridges them is the deployment's `buildTenantContext`.
+ */
+export interface CustomerActorInput {
+    readonly kind: 'customer';
+    readonly customerAccountId: string;
+    readonly organizationId: string | null;
+    readonly impersonatorAdminUserId?: string | null;
+    /**
+     * Feature 056 (US2) — roll-up widening for a customer actor. When the customer
+     * holds the `organizations:rollup` capability, the server passes the actor's
+     * org subtree here (`[theirOrg, ...descendants]`), and the context resolves to
+     * an `allowed-set` instead of `single-org` (FR-004/FR-005). When absent/empty,
+     * the customer stays `single-org` (flat behavior preserved).
+     *
+     * NB: there is no customer-facing capability source wired in production today
+     * (admin permissions do not attach to customer accounts), so production
+     * customer contexts stay `single-org`; the roll-up path for scoped actors is
+     * derived at the admin scope-builder seam (`resolveAdminOrdersScope` /
+     * `resolveModerationActor`) via the subtree-aware `SalesRepAssignmentService`.
+     * This field keeps the derivation server-side (Principle XI) and ready for a
+     * future customer-capability source.
+     */
+    readonly rollupSubtreeOrganizationIds?: readonly string[];
+}
+export interface AdminActorInput {
+    readonly kind: 'admin';
+    readonly adminUserId: string;
+}
+/**
+ * Feature 062 — an api-key actor. A BOUND key (organizationId present) pins the
+ * request to its organization + designated service customer account with a
+ * first-class `api_key` actor for audit attribution. An UNBOUND key keeps the
+ * legacy trusted system scope (its only mounted surface is the global-entity
+ * PIM read/write path — research §R5).
+ */
+export interface ApiKeyActorInput {
+    readonly kind: 'api_key';
+    readonly apiKeyId: string;
+    readonly organizationId?: string | null;
+    readonly customerAccountId?: string | null;
+}
+export type TenantActorInput = CustomerActorInput | AdminActorInput | ApiKeyActorInput;
+/**
+ * A scoped admin's reach. `allowAll: true` ⇒ platform admin (no restriction).
+ * Otherwise the admin is confined to `allowedOrganizationIds`. Mirrors the
+ * shape already produced by `resolveAdminOrdersScope` in composition.ts.
+ */
+export interface AdminScopeInput {
+    readonly allowAll: boolean;
+    readonly allowedOrganizationIds?: readonly string[];
+}
+export declare function resolveTenantContext(actor: TenantActorInput, adminScope?: AdminScopeInput): TenantContext;
+/** Context for platform-internal work (workers, migrations, escape hatch). */
+export declare function systemTenantContext(reason: string): TenantContext;
+/** Context pinned to a single organization (per-org jobs via the escape hatch). */
+export declare function orgPinnedTenantContext(organizationId: string, reason: string): TenantContext;
+//# sourceMappingURL=resolve-tenant-context.d.ts.map

package/dist/tenancy/resolve-tenant-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-tenant-context.d.ts","sourceRoot":"","sources":["../../src/tenancy/resolve-tenant-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,qBAAqB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,4BAA4B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3D;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED,MAAM,MAAM,gBAAgB,GAAG,kBAAkB,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAEvF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,aAAa,CA6DzG;AAcD,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAEjE;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAO5F"}

package/dist/tenancy/resolve-tenant-context.js

@@ -0,0 +1,85 @@
+export function resolveTenantContext(actor, adminScope) {
+    if (actor.kind === 'customer') {
+        // Feature 056 — a roll-up-enabled customer widens from single-org to the
+        // subtree allowed-set (server-derived). Absent/empty ⇒ single-org (flat).
+        if (actor.rollupSubtreeOrganizationIds && actor.rollupSubtreeOrganizationIds.length > 0) {
+            return {
+                mode: 'allowed-set',
+                allowedOrganizationIds: [...actor.rollupSubtreeOrganizationIds],
+                notices: newScopeNotices(),
+                customerAccountId: actor.customerAccountId,
+                actor: { kind: 'customer', id: actor.customerAccountId },
+                ...(actor.impersonatorAdminUserId
+                    ? {
+                        impersonation: {
+                            realAdminUserId: actor.impersonatorAdminUserId,
+                            impersonatedCustomerAccountId: actor.customerAccountId,
+                        },
+                    }
+                    : {}),
+            };
+        }
+        return {
+            mode: 'single-org',
+            organizationId: actor.organizationId,
+            customerAccountId: actor.customerAccountId,
+            actor: { kind: 'customer', id: actor.customerAccountId },
+            ...(actor.impersonatorAdminUserId
+                ? {
+                    impersonation: {
+                        realAdminUserId: actor.impersonatorAdminUserId,
+                        impersonatedCustomerAccountId: actor.customerAccountId,
+                    },
+                }
+                : {}),
+        };
+    }
+    // Feature 062 — api-key actor: bound ⇒ single-org pinned to the binding;
+    // unbound ⇒ trusted system scope (unchanged legacy behavior, FR-020).
+    if (actor.kind === 'api_key') {
+        if (actor.organizationId) {
+            return {
+                mode: 'single-org',
+                organizationId: actor.organizationId,
+                customerAccountId: actor.customerAccountId ?? null,
+                actor: { kind: 'api_key', id: actor.apiKeyId },
+            };
+        }
+        return systemTenantContext('actor:api_key');
+    }
+    // Admin actor.
+    if (!adminScope || adminScope.allowAll) {
+        return { mode: 'all', actor: { kind: 'admin', id: actor.adminUserId } };
+    }
+    return {
+        mode: 'allowed-set',
+        allowedOrganizationIds: adminScope.allowedOrganizationIds ?? [],
+        notices: newScopeNotices(),
+        actor: { kind: 'admin', id: actor.adminUserId },
+    };
+}
+/**
+ * A fresh observation sink for one execution (feature 087). Attached to the two
+ * `allowed-set` branches above and to nothing else: `all` and `system` refuse
+ * nothing, and `single-org` refuses per row rather than per table, so neither
+ * has an emptiness to explain. One object per call, so a context can never
+ * carry another request's observation — `resolveTenantContext` is called once
+ * per request by the host's scope hook.
+ */
+function newScopeNotices() {
+    return { organizationAttributionRefused: false };
+}
+/** Context for platform-internal work (workers, migrations, escape hatch). */
+export function systemTenantContext(reason) {
+    return { mode: 'system', actor: { kind: 'system' }, reason };
+}
+/** Context pinned to a single organization (per-org jobs via the escape hatch). */
+export function orgPinnedTenantContext(organizationId, reason) {
+    return {
+        mode: 'single-org',
+        organizationId,
+        actor: { kind: 'system' },
+        reason,
+    };
+}
+//# sourceMappingURL=resolve-tenant-context.js.map

package/dist/tenancy/resolve-tenant-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-tenant-context.js","sourceRoot":"","sources":["../../src/tenancy/resolve-tenant-context.ts"],"names":[],"mappings":"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"}

package/dist/tenancy/scoped-em.d.ts

@@ -0,0 +1,10 @@
+import type { EntityManager, MikroORM } from '@mikro-orm/postgresql';
+/**
+ * EM fork used across composition.ts (feature 050). The tenant filters read the
+ * ambient TenantContext from AsyncLocalStorage at query time (see filters.ts),
+ * so no per-fork `setFilterParams` is required — a plain fork already carries the
+ * guard. This wrapper is retained as the single, named injection seam so the
+ * intent is explicit at call sites and future per-fork wiring has one home.
+ */
+export declare function forkScopedEm(orm: MikroORM): EntityManager;
+//# sourceMappingURL=scoped-em.d.ts.map

package/dist/tenancy/scoped-em.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-em.d.ts","sourceRoot":"","sources":["../../src/tenancy/scoped-em.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAErE;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,GAAG,aAAa,CAEzD"}

package/dist/tenancy/scoped-em.js

@@ -0,0 +1,11 @@
+/**
+ * EM fork used across composition.ts (feature 050). The tenant filters read the
+ * ambient TenantContext from AsyncLocalStorage at query time (see filters.ts),
+ * so no per-fork `setFilterParams` is required — a plain fork already carries the
+ * guard. This wrapper is retained as the single, named injection seam so the
+ * intent is explicit at call sites and future per-fork wiring has one home.
+ */
+export function forkScopedEm(orm) {
+    return orm.em.fork();
+}
+//# sourceMappingURL=scoped-em.js.map

package/dist/tenancy/scoped-em.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-em.js","sourceRoot":"","sources":["../../src/tenancy/scoped-em.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAa;IACxC,OAAO,GAAG,CAAC,EAAE,CAAC,IAAI,EAAmB,CAAC;AACxC,CAAC"}

package/dist/tenancy/tenant-context.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Systemic Organization Tenant Scoping (feature 050).
+ *
+ * The ambient `TenantContext` is the single source of truth for "which tenant
+ * is this async execution allowed to see?". It is derived server-side from the
+ * authenticated actor (never from request inputs) and read by the MikroORM
+ * filter's `cond` thunk **when a query is built** (`filters.ts`) — never stamped
+ * onto an EntityManager. `forkScopedEm` is a bare `orm.em.fork()`; a manager
+ * therefore carries no tenancy of its own, and the same fork yields different
+ * rows under different ambient contexts (feature 072, T038).
+ *
+ * Modes:
+ *  - `single-org`   — a customer (or an org-pinned job); confined to one org.
+ *  - `allowed-set`  — a scoped sales-rep admin; confined to an assigned set.
+ *  - `all`          — a platform admin; no org restriction (still explicit).
+ *  - `system`       — worker / migration / escape hatch; crosses all orgs.
+ *
+ * Fail-closed: a query against a tenant-scoped entity with NO ambient context
+ * raises `MissingTenantContextError` (see `filters.ts`) — it never returns
+ * unscoped rows.
+ */
+export type TenantScopeMode = 'single-org' | 'allowed-set' | 'all' | 'system';
+export interface TenantActor {
+    /** `api_key` (feature 062) = a bound distributor key acting as the tenant principal. */
+    readonly kind: 'customer' | 'admin' | 'system' | 'api_key';
+    readonly id?: string;
+}
+export interface TenantImpersonation {
+    readonly realAdminUserId: string;
+    readonly impersonatedCustomerAccountId: string;
+}
+/**
+ * What the tenant guard **did** to this execution, as opposed to what it was
+ * allowed to do (feature 087, owner decision of 2026-08-29).
+ *
+ * A predicate that refuses every row of a table is correct and silent, and the
+ * two properties are in tension: the caller receives an empty result and cannot
+ * tell "your reach excludes all of these" from "there are none". The filter is
+ * the only thing that knows which it meant, so it records it here and the host
+ * discloses it on the response envelope (`kernel/request-scope-hook.ts`).
+ *
+ * Mutable, and deliberately so: one object per request, created beside the
+ * context it hangs off, written by the filter as queries run and read once the
+ * handler has answered. It is an observation of this execution, never an input
+ * to a decision — nothing in the guard reads it, so a stale or missing sink can
+ * widen no authority.
+ */
+export interface TenantScopeNotices {
+    /**
+     * Set when the `customerAccount` filter answered its `allowed-set` arm with
+     * the match-nothing predicate, i.e. the filtered entity carries no
+     * organization column of its own. See `customerFilterCond`.
+     */
+    organizationAttributionRefused: boolean;
+}
+export interface TenantContext {
+    readonly mode: TenantScopeMode;
+    /** Present for `single-org`. */
+    readonly organizationId?: string | null;
+    /** Present for `allowed-set`. */
+    readonly allowedOrganizationIds?: readonly string[];
+    /** Present for customer actors — drives the `customerAccount` filter. */
+    readonly customerAccountId?: string | null;
+    readonly actor: TenantActor;
+    readonly impersonation?: TenantImpersonation;
+    /** Required for `system` scope entered via the escape hatch. */
+    readonly reason?: string;
+    /**
+     * Per-request observation sink. Attached by `resolveTenantContext` to the
+     * contexts whose predicates can refuse wholesale (`allowed-set`), absent
+     * everywhere else — a mode that never refuses has nothing to disclose.
+     */
+    readonly notices?: TenantScopeNotices;
+}
+/**
+ * Record that the ambient execution was refused a whole table for want of an
+ * organization column. A context with no sink (every mode but `allowed-set`,
+ * and any context a caller built by hand) drops the observation, which is the
+ * right failure: the disclosure goes missing, never the refusal.
+ */
+export declare function noteOrganizationAttributionRefusal(ctx: TenantContext): void;
+/**
+ * Thrown when a tenant-scoped entity is queried with no ambient context. This is
+ * the fail-closed guarantee: forgetting to establish a context surfaces as a loud
+ * error, never a silent cross-tenant read.
+ */
+export declare class MissingTenantContextError extends Error {
+    constructor(detail?: string);
+}
+/**
+ * Thrown when a write carries an `organizationId` the ambient scope may not act
+ * on (D-260/A). It sits beside {@link MissingTenantContextError} because the two
+ * are one guarantee failing in the two directions the data layer has: that one
+ * is "no scope was established", this one is "a scope was established and this
+ * row is outside it".
+ *
+ * **It names no organization** — neither the one the write carried nor the set
+ * the actor holds. The refusal reaches a caller that supplied the id, so
+ * "outside your scope" tells it nothing it did not already know, while echoing
+ * the *set* would put the actor's reach into a log and an HTTP body. The entity
+ * class is carried because a flush-time refusal is otherwise undiagnosable: the
+ * stack frame belongs to MikroORM's unit of work and names no caller.
+ *
+ * Thrown by `org-write-guard.ts`; mapped to `403 FORBIDDEN` in
+ * `http/error-envelope.ts`, which explains there why 403 and not 404.
+ */
+export declare class OrgWriteOutOfScopeError extends Error {
+    /** The entity class whose write was refused. Never the organization id. */
+    readonly entityName: string;
+    constructor(entityName: string);
+}
+/** The ambient context for the current async execution, or `undefined` if none is set. */
+export declare function getTenantContext(): TenantContext | undefined;
+/** Run `fn` with `ctx` as the ambient context for its entire async subtree. */
+export declare function runWithTenantContext<T>(ctx: TenantContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Set the ambient context for the current async execution. NOTE: when called
+ * inside an *async* Fastify hook this does not propagate to the route handler
+ * (the handler resumes in the hook's parent async context). Prefer
+ * `runInTenantContext` in the request pipeline; keep this only for synchronous
+ * top-level entrypoints (e.g. a worker process bootstrap).
+ */
+export declare function enterTenantContext(ctx: TenantContext): void;
+/**
+ * Establish `ctx` for the remainder of a Fastify request via the callback-style
+ * hook pattern: `addHook('onRequest', (req, reply, done) => runInTenantContext(ctx, done))`.
+ * Fastify invokes the next hook/handler synchronously inside `callback`, so the
+ * store propagates across the handler's awaited continuations. This is the
+ * reliable AsyncLocalStorage-with-Fastify pattern (cf. @fastify/request-context).
+ */
+export declare function runInTenantContext(ctx: TenantContext, callback: () => void): void;
+/**
+ * Run `fn` with NO ambient context (fail-closed testing / explicit clears).
+ *
+ * **`storage.run(undefined, fn)`, never `storage.exit(fn)`.** On the
+ * pre-`AsyncContextFrame` runtime — which is every Node before 24, and this
+ * repository's floor is 22.17 — `exit` is `disable(); try { fn() } finally
+ * { enable() }`: a *synchronous* try/finally around a callback that may be
+ * `async`. Where the caller's context was installed with `enterWith` and `fn`
+ * opens a nested `run()` of its own, the re-enable resurfaces the caller's
+ * store and everything after that point reads it, so the "no context" this
+ * function promises silently ends partway through. Node 24 made
+ * `AsyncContextFrame` the default and `exit` frame-scoped, which is why the
+ * defect was invisible on a developer's machine and red in CI for as long as it
+ * stood (`test/unit/seeds/seed-scope.test.ts`,
+ * `packages/platform/src/kernel/lifecycle/registry-cache-scope.test.ts`).
+ *
+ * Running with `undefined` as the store is the same observable contract —
+ * `getStore()` answers `undefined`, and the caller's context is restored on
+ * both return and throw — and it is a real frame, so it holds across `await`
+ * on both runtimes. Verified on 22.17 and on 26.
+ */
+export declare function runWithoutTenantContext<T>(fn: () => T): T;
+//# sourceMappingURL=tenant-context.d.ts.map

package/dist/tenancy/tenant-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-context.d.ts","sourceRoot":"","sources":["../../src/tenancy/tenant-context.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,aAAa,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE9E,MAAM,WAAW,WAAW;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3D,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,6BAA6B,EAAE,MAAM,CAAC;CAChD;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,8BAA8B,EAAE,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,gCAAgC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,iCAAiC;IACjC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpD,yEAAyE;IACzE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,mBAAmB,CAAC;IAC7C,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAE3E;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,MAAM,CAAC,EAAE,MAAM;CAQ5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM;CAS/B;AASD,0FAA0F;AAC1F,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE5F;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAEjF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEzD"}

package/dist/tenancy/tenant-context.js

@@ -0,0 +1,109 @@
+import { AsyncLocalStorage } from 'async_hooks';
+/**
+ * Record that the ambient execution was refused a whole table for want of an
+ * organization column. A context with no sink (every mode but `allowed-set`,
+ * and any context a caller built by hand) drops the observation, which is the
+ * right failure: the disclosure goes missing, never the refusal.
+ */
+export function noteOrganizationAttributionRefusal(ctx) {
+    if (ctx.notices)
+        ctx.notices.organizationAttributionRefused = true;
+}
+/**
+ * Thrown when a tenant-scoped entity is queried with no ambient context. This is
+ * the fail-closed guarantee: forgetting to establish a context surfaces as a loud
+ * error, never a silent cross-tenant read.
+ */
+export class MissingTenantContextError extends Error {
+    constructor(detail) {
+        super(`No tenant context is active for a tenant-scoped query.${detail ? ` (${detail})` : ''} Establish one via the request pipeline, or opt out explicitly with withSystemScope()/withOrgScope().`);
+        this.name = 'MissingTenantContextError';
+    }
+}
+/**
+ * Thrown when a write carries an `organizationId` the ambient scope may not act
+ * on (D-260/A). It sits beside {@link MissingTenantContextError} because the two
+ * are one guarantee failing in the two directions the data layer has: that one
+ * is "no scope was established", this one is "a scope was established and this
+ * row is outside it".
+ *
+ * **It names no organization** — neither the one the write carried nor the set
+ * the actor holds. The refusal reaches a caller that supplied the id, so
+ * "outside your scope" tells it nothing it did not already know, while echoing
+ * the *set* would put the actor's reach into a log and an HTTP body. The entity
+ * class is carried because a flush-time refusal is otherwise undiagnosable: the
+ * stack frame belongs to MikroORM's unit of work and names no caller.
+ *
+ * Thrown by `org-write-guard.ts`; mapped to `403 FORBIDDEN` in
+ * `http/error-envelope.ts`, which explains there why 403 and not 404.
+ */
+export class OrgWriteOutOfScopeError extends Error {
+    /** The entity class whose write was refused. Never the organization id. */
+    entityName;
+    constructor(entityName) {
+        super(`A write to ${entityName} carries an organization outside the active tenant scope ` +
+            '(feature 050 FR-003, D-260/A). Writing for another organization needs an explicit ' +
+            'widening — withSystemScope() / withOrgScope() — or it is a scope defect.');
+        this.name = 'OrgWriteOutOfScopeError';
+        this.entityName = entityName;
+    }
+}
+/**
+ * The store is `TenantContext | undefined` rather than `TenantContext` so that
+ * `runWithoutTenantContext` can express "no context" as a value it *runs* with
+ * — see the note on that function for why it may not use `exit()`.
+ */
+const storage = new AsyncLocalStorage();
+/** The ambient context for the current async execution, or `undefined` if none is set. */
+export function getTenantContext() {
+    return storage.getStore();
+}
+/** Run `fn` with `ctx` as the ambient context for its entire async subtree. */
+export function runWithTenantContext(ctx, fn) {
+    return storage.run(ctx, fn);
+}
+/**
+ * Set the ambient context for the current async execution. NOTE: when called
+ * inside an *async* Fastify hook this does not propagate to the route handler
+ * (the handler resumes in the hook's parent async context). Prefer
+ * `runInTenantContext` in the request pipeline; keep this only for synchronous
+ * top-level entrypoints (e.g. a worker process bootstrap).
+ */
+export function enterTenantContext(ctx) {
+    storage.enterWith(ctx);
+}
+/**
+ * Establish `ctx` for the remainder of a Fastify request via the callback-style
+ * hook pattern: `addHook('onRequest', (req, reply, done) => runInTenantContext(ctx, done))`.
+ * Fastify invokes the next hook/handler synchronously inside `callback`, so the
+ * store propagates across the handler's awaited continuations. This is the
+ * reliable AsyncLocalStorage-with-Fastify pattern (cf. @fastify/request-context).
+ */
+export function runInTenantContext(ctx, callback) {
+    storage.run(ctx, callback);
+}
+/**
+ * Run `fn` with NO ambient context (fail-closed testing / explicit clears).
+ *
+ * **`storage.run(undefined, fn)`, never `storage.exit(fn)`.** On the
+ * pre-`AsyncContextFrame` runtime — which is every Node before 24, and this
+ * repository's floor is 22.17 — `exit` is `disable(); try { fn() } finally
+ * { enable() }`: a *synchronous* try/finally around a callback that may be
+ * `async`. Where the caller's context was installed with `enterWith` and `fn`
+ * opens a nested `run()` of its own, the re-enable resurfaces the caller's
+ * store and everything after that point reads it, so the "no context" this
+ * function promises silently ends partway through. Node 24 made
+ * `AsyncContextFrame` the default and `exit` frame-scoped, which is why the
+ * defect was invisible on a developer's machine and red in CI for as long as it
+ * stood (`test/unit/seeds/seed-scope.test.ts`,
+ * `packages/platform/src/kernel/lifecycle/registry-cache-scope.test.ts`).
+ *
+ * Running with `undefined` as the store is the same observable contract —
+ * `getStore()` answers `undefined`, and the caller's context is restored on
+ * both return and throw — and it is a real frame, so it holds across `await`
+ * on both runtimes. Verified on 22.17 and on 26.
+ */
+export function runWithoutTenantContext(fn) {
+    return storage.run(undefined, fn);
+}
+//# sourceMappingURL=tenant-context.js.map

package/dist/tenancy/tenant-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-context.js","sourceRoot":"","sources":["../../src/tenancy/tenant-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAkFhD;;;;;GAKG;AACH,MAAM,UAAU,kCAAkC,CAAC,GAAkB;IACnE,IAAI,GAAG,CAAC,OAAO;QAAE,GAAG,CAAC,OAAO,CAAC,8BAA8B,GAAG,IAAI,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,YAAY,MAAe;QACzB,KAAK,CACH,yDACE,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,EAC5B,uGAAuG,CACxG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,2EAA2E;IAClE,UAAU,CAAS;IAE5B,YAAY,UAAkB;QAC5B,KAAK,CACH,cAAc,UAAU,2DAA2D;YACjF,oFAAoF;YACpF,0EAA0E,CAC7E,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAA6B,CAAC;AAEnE,0FAA0F;AAC1F,MAAM,UAAU,gBAAgB;IAC9B,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,oBAAoB,CAAI,GAAkB,EAAE,EAAoB;IAC9E,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAkB;IACnD,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAkB,EAAE,QAAoB;IACzE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,uBAAuB,CAAI,EAAW;IACpD,OAAO,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC"}

package/package.json

@@ -0,0 +1,123 @@
+{
+  "name": "@endora-commerce/platform",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "endora": {
+    "type": "platform"
+  },
+  "description": "The host package (feature 080, T042a). Publishes the surface an installed extension package compiles against: five enumerated subpaths, one per platform directory that has published API. No root export and no wildcard (D-160.7). The remaining subpaths are host-internal and no module may name any of them (D-160.14) — how many that is is not written here, `HOST_INTERNAL_SUBPATHS` in packages/cli/src/lib/platform-surface.ts carries one reason per member and this sentence read 'three' over six of them: ./composition, the host composition surface; ./db, the ORM configuration, the migration ordering and the bootstrap (specs/110-instance-repository/, T116); ./migrations, the platform's own twelve migrations and the frozen historical prefix an execution order is computed from (specs/110-instance-repository/, R1.5); ./lifecycle, the operator surface that drives the platform presence axis (specs/115-lifecycle-container-move/, D115-4); ./env, the environment inputs the host reads; ./packages, installed extension-package discovery; ./overlay, the loader that composes a deployment's client-only modules (specs/110-instance-repository/, T113 and T114); ./cli, the host's side of a module-declared operator command (T117); and ./demo, the demo-data guard, plan, runner and report (feature 113, T119b).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/platform"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./kernel": {
+      "types": "./dist/kernel/index.d.ts",
+      "default": "./dist/kernel/index.js"
+    },
+    "./http": {
+      "types": "./dist/http/index.d.ts",
+      "default": "./dist/http/index.js"
+    },
+    "./tenancy": {
+      "types": "./dist/tenancy/index.d.ts",
+      "default": "./dist/tenancy/index.js"
+    },
+    "./commands": {
+      "types": "./dist/commands/index.d.ts",
+      "default": "./dist/commands/index.js"
+    },
+    "./events": {
+      "types": "./dist/events/index.d.ts",
+      "default": "./dist/events/index.js"
+    },
+    "./composition": {
+      "types": "./dist/composition/index.d.ts",
+      "default": "./dist/composition/index.js"
+    },
+    "./db": {
+      "types": "./dist/db/index.d.ts",
+      "default": "./dist/db/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./lifecycle": {
+      "types": "./dist/lifecycle/index.d.ts",
+      "default": "./dist/lifecycle/index.js"
+    },
+    "./env": {
+      "types": "./dist/env/index.d.ts",
+      "default": "./dist/env/index.js"
+    },
+    "./packages": {
+      "types": "./dist/packages/index.d.ts",
+      "default": "./dist/packages/index.js"
+    },
+    "./overlay": {
+      "types": "./dist/overlay/index.d.ts",
+      "default": "./dist/overlay/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    },
+    "./demo": {
+      "types": "./dist/demo/index.d.ts",
+      "default": "./dist/demo/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.5.0",
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/helmet": "^13.0.2",
+    "@fastify/rate-limit": "^10.3.0",
+    "@fastify/type-provider-zod": "^1.0.0",
+    "argon2": "^0.44.0",
+    "awilix": "^13.0.5",
+    "bullmq": "^5.76.1",
+    "fastify-plugin": "^5.1.0",
+    "ioredis": "^5.10.1",
+    "openapi-types": "^12.1.3",
+    "pino": "^10.3.1",
+    "@endora-commerce/contracts": "0.100.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "fastify": "^5.12.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/copy-package-assets.mjs --src src --out dist",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}