@entifix/service-shell 0.7.1 → 0.7.2

package/README.md

@@ -16,17 +16,17 @@ pnpm add @opentelemetry/api @effect/opentelemetry @opentelemetry/sdk-trace-base
 
 ## Entry points
 
-| Import                                 | What it holds                                                                                                                                                           |
-| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@entifix/service-shell`               | What a route set is written against: `requirePrincipal`, `requirePermission`, `requireOrganization`, `requireSharedToken`, `entityMetadataRoute`, health and SSE routes |
-| `@entifix/service-shell/runtime`       | Running a service: `makeService`, `makeServerLayer`, `loadRemoteConfiguration`. Needs `@effect/platform-node`                                                           |
-| `@entifix/service-shell/observability` | `makeObservabilityLayer` and the OpenTelemetry wiring. Needs `@effect/opentelemetry` and the OpenTelemetry SDK packages                                                 |
-| `@entifix/service-shell/testing`       | `serveTestService`, a service on an ephemeral port for a spec                                                                                                           |
+| Import                                 | What it holds                                                                                                                                                                                                         |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@entifix/service-shell`               | What a route set is written against: `makeEntityRoutes`, `requirePrincipal`, `requirePermission`, `requireOrganization`, `requireServiceCrossing`, `requireSharedToken`, `entityMetadataRoute`, health and SSE routes |
+| `@entifix/service-shell/runtime`       | Running a service: `makeService`, `makeServerLayer`, `loadRemoteConfiguration`. Needs `@effect/platform-node`                                                                                                         |
+| `@entifix/service-shell/observability` | `makeObservabilityLayer` and the OpenTelemetry wiring. Needs `@effect/opentelemetry` and the OpenTelemetry SDK packages                                                                                               |
+| `@entifix/service-shell/testing`       | `serveTestService`, a service on an ephemeral port for a spec                                                                                                                                                         |
 
 The runtime and observability halves are optional peers: a package that only declares routes installs neither. The configuration service's URL and credential, and the header and secret that gate `GET /api/$service`, are values the host passes — `loadRemoteConfiguration({ url, headers })` and `makeService({ description: { header, token } })`.
 
 ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `@entifix/service-shell` | `makeService`, `makeServerLayer`, `requirePrincipal`, `requirePermission`, `requireOrganization`, `entityMetadataRoute`, `loadRemoteConfiguration`, `makeObservabilityLayer`, `serveTestService` |
+| `@entifix/service-shell` | `makeService`, `makeServerLayer`, `makeEntityRoutes`, `requirePrincipal`, `requirePermission`, `requireOrganization`, `entityMetadataRoute`, `loadRemoteConfiguration`, `makeObservabilityLayer`, `serveTestService` |
 
 ---
 

package/dist/auth/require-service-crossing.d.ts

@@ -26,6 +26,11 @@ export declare const CROSSING_TOKEN_HEADER = "x-crossing-token";
  * that authorizes.
  */
 export declare const ORGANIZATION_HEADER = "x-organization-id";
+/**
+ * The header a saga dispatch carries its command id in — what a participant
+ * dedupes a redelivered command on, and what its unit of work claims.
+ */
+export declare const COMMAND_ID_HEADER = "x-command-id";
 declare const ServiceCrossingTokenTag_base: Context.ServiceClass<ServiceCrossingTokenTag, "ServiceCrossingTokenTag", string>;
 /**
  * The crossing secret this service expects, provided at the composition root

package/dist/auth/require-service-crossing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"require-service-crossing.d.ts","sourceRoot":"","sources":["../../src/auth/require-service-crossing.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEpE;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;;AAEvD;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,SAAQ,4BAGf;CAAG;AAgCjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,sBAAsB,GAChC,YAAY,UAAU,MACtB,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,cAAc,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,6MAwB7D,CAAC;AAEP;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GACzB,YAAY,UAAU,MACtB,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,6MAenC,CAAC"}
+{"version":3,"file":"require-service-crossing.d.ts","sourceRoot":"","sources":["../../src/auth/require-service-crossing.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEpE;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;;AAEhD;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,SAAQ,4BAGf;CAAG;AAgCjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,sBAAsB,GAChC,YAAY,UAAU,MACtB,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,cAAc,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,6MAwB7D,CAAC;AAEP;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GACzB,YAAY,UAAU,MACtB,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,6MAenC,CAAC"}

package/dist/auth/require-service-crossing.js

@@ -25,6 +25,10 @@ import { HttpServerRequest, HttpServerResponse } from 'effect/http';
  * the caller is the fleet, so the input the caller controls is never the input
  * that authorizes.
  */ export const ORGANIZATION_HEADER = 'x-organization-id';
+/**
+ * The header a saga dispatch carries its command id in — what a participant
+ * dedupes a redelivered command on, and what its unit of work claims.
+ */ export const COMMAND_ID_HEADER = 'x-command-id';
 /**
  * The crossing secret this service expects, provided at the composition root
  * from its own configuration.

package/dist/auth/require-service-crossing.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/auth/require-service-crossing.ts"],"sourcesContent":["import { timingSafeEqual } from 'node:crypto';\n\nimport { type Permission, ServiceCrossingPolicyTag } from '@entifix/authz';\nimport { Context, Effect } from 'effect';\nimport { HttpServerRequest, HttpServerResponse } from 'effect/http';\n\n/**\n * The header carrying the crossing secret.\n *\n * ⚠️ **Deliberately not `x-service-token`.** That header is config-service's\n * fleet lookup, and the two secrets are not comparable: one grants a\n * configuration *read*, this one a tenant-data *write* for any organization the\n * caller names. Sharing the header name is how a proxy configured to forward the\n * fleet token ends up presenting it to a route that writes stock, and how a\n * copy-pasted value looks right while being the wrong secret entirely.\n */\nexport const CROSSING_TOKEN_HEADER = 'x-crossing-token';\n\n/**\n * The header naming the organization the caller is acting for.\n *\n * It rides beside the token rather than inside the request body because\n * entities are organization-agnostic by rule — no `organizationId` member, no\n * tenant filter — so there is nowhere in an entity envelope for it to live. A\n * header also serves the crossings that carry no body at all (releasing a hold,\n * converting one), which a body field would have needed a second convention for.\n *\n * On its own it grants **nothing**: it is only read after the token has proved\n * the caller is the fleet, so the input the caller controls is never the input\n * that authorizes.\n */\nexport const ORGANIZATION_HEADER = 'x-organization-id';\n\n/**\n * The crossing secret this service expects, provided at the composition root\n * from its own configuration.\n *\n * A `Context.Tag` rather than an environment read, which is the difference from\n * {@link requireServiceToken}: the value is a per-service secret held in\n * config-service as an `is_secret` row, so it arrives through the same boot\n * fetch as `mongo.uri` and can be rotated without redeploying a container.\n */\nexport class ServiceCrossingTokenTag extends Context.Service<\n  ServiceCrossingTokenTag,\n  string\n>()('ServiceCrossingTokenTag') {}\n\n/** Constant-time comparison, so the secret cannot be recovered byte by byte. */\nconst matches = (provided: string | undefined, expected: string): boolean => {\n  if (provided === undefined) return false;\n  const left = Buffer.from(provided);\n  const right = Buffer.from(expected);\n  // `timingSafeEqual` throws on a length mismatch, so lengths are compared\n  // first — the length of a shared secret is not what protects it.\n  return left.length === right.length && timingSafeEqual(left, right);\n};\n\nconst unauthenticated = HttpServerResponse.json(\n  { error: 'unauthenticated', code: 'unauthenticated' },\n  { status: 401 },\n);\n\nconst forbidden = (permission: Permission) =>\n  HttpServerResponse.json(\n    { error: 'forbidden', code: 'forbidden', permission },\n    { status: 403 },\n  );\n\nconst organizationRequired = HttpServerResponse.json(\n  {\n    error: 'the crossing must name an organization',\n    code: 'invalidRequest',\n    detail: `${ORGANIZATION_HEADER} is required`,\n  },\n  { status: 400 },\n);\n\n/**\n * Guard a **service-to-service** tenant crossing: the second — and only other —\n * way a request resolves the organization it acts for.\n *\n * The first is {@link requireOrganization}, which reads the session's\n * `activeOrganizationId` and is the only *user-facing* resolution. This one\n * exists because a platform-plane caller sometimes acts for an organization the\n * principal is not a member of: checkout reserving a vendor's stock, where the\n * organization comes from the **item** and a buyer's session carries none — and\n * never will, since making a buyer a member of every vendor they buy from would\n * be a far worse breach than the problem it solved.\n *\n * There is no third path, no fallback and no operator branch. A request\n * satisfying neither guard simply never reaches a tenant handle. An operator\n * reaching into a tenant is a *different* mechanism — a person choosing an\n * organization, which needs a human's permission, a time box and a record of\n * the crossing — and does not belong in this guard.\n *\n * ⚠️ **This guard reads no cookie and no `Authorization` header, and that is\n * the design.** A route guarded here accepts the crossing token and nothing\n * else: two accepted credentials on one route means the weaker one is the\n * security level. It matters concretely — `super-admin` holds `*:*:*`, which\n * matches every crossing permission, so a route that also took a session would\n * be reachable by an operator's browser tab.\n *\n * Three checks, in this order, so nothing is revealed before fleet membership is\n * proven:\n *\n * 1. the token, compared in constant time → `401`;\n * 2. the permission, against `ServiceCrossingPolicyTag` → `403`. The token\n *    proves the caller is the fleet; it does not say what the caller may do, and\n *    fleet membership is not a capability;\n * 3. the organization header, non-blank → `400`.\n *\n * **The residual, stated rather than argued away**: a shared secret\n * means any process holding it can name any organization. What bounds it is the\n * permission above, the fact that only the slices needing it are configured with\n * the key, and the request log. What would remove it is an RS256 service token\n * carrying a scope claim, which is named work rather than a gap nobody noticed.\n */\nexport const requireServiceCrossing =\n  (permission: Permission) =>\n  <A, E, R>(use: (organizationId: string) => Effect.Effect<A, E, R>) =>\n    // The return type is inferred rather than written out, for the reason\n    // `requireServiceToken` records: `HttpServerResponse.json` contributes an\n    // `HttpBodyError` to the failure channel, and spelling the type out while\n    // omitting it is what makes the declaration emit fail invisibly.\n    Effect.gen(function* () {\n      const request = yield* HttpServerRequest.HttpServerRequest;\n      const expected = yield* ServiceCrossingTokenTag;\n\n      if (!matches(request.headers[CROSSING_TOKEN_HEADER], expected)) {\n        return yield* unauthenticated;\n      }\n\n      const crossing = yield* ServiceCrossingPolicyTag;\n      if (!crossing.allows(permission)) {\n        return yield* forbidden(permission);\n      }\n\n      const organizationId = request.headers[ORGANIZATION_HEADER]?.trim();\n      if (organizationId === undefined || organizationId === '') {\n        return yield* organizationRequired;\n      }\n\n      return yield* use(organizationId);\n    });\n\n/**\n * The same fleet check, for a participant that has **no organization to name**.\n *\n * ⚠️ **A platform-plane store is the whole difference.** `requireServiceCrossing`\n * above ends with an organization header because it is about to resolve a tenant\n * database handle from it, and a blank one there would read some other vendor's\n * storage. order-service names one database at boot, so there is no handle to\n * choose — and demanding a header nothing consumes would be theatre that a\n * caller learns to satisfy with any value.\n *\n * What is unchanged, and is the part that matters: the token proves the caller\n * is the fleet, the host's `ServiceCrossingPolicy` says what the fleet may do,\n * and **no session is accepted**. A saga step is not a person's act — the buyer\n * behind a checkout holds no grant over the order the coordinator is writing on\n * their behalf, and accepting their session here would make the weaker\n * credential the security level.\n *\n * The recorded residual carries over verbatim: a shared secret means any process\n * holding it can act, bounded by the permission and by which slices are\n * configured with the key.\n */\nexport const requireCrossing =\n  (permission: Permission) =>\n  <A, E, R>(route: Effect.Effect<A, E, R>) =>\n    Effect.gen(function* () {\n      const request = yield* HttpServerRequest.HttpServerRequest;\n      const expected = yield* ServiceCrossingTokenTag;\n\n      if (!matches(request.headers[CROSSING_TOKEN_HEADER], expected)) {\n        return yield* unauthenticated;\n      }\n\n      const crossing = yield* ServiceCrossingPolicyTag;\n      if (!crossing.allows(permission)) {\n        return yield* forbidden(permission);\n      }\n\n      return yield* route;\n    });\n"],"names":["timingSafeEqual","ServiceCrossingPolicyTag","Context","Effect","HttpServerRequest","HttpServerResponse","CROSSING_TOKEN_HEADER","ORGANIZATION_HEADER","ServiceCrossingTokenTag","Service","matches","provided","expected","undefined","left","Buffer","from","right","length","unauthenticated","json","error","code","status","forbidden","permission","organizationRequired","detail","requireServiceCrossing","use","gen","request","headers","crossing","allows","organizationId","trim","requireCrossing","route"],"mappings":"AAAA,SAASA,eAAe,QAAQ,cAAc;AAE9C,SAA0BC,wBAAwB,QAAQ,iBAAiB;AAC3E,SAASC,OAAO,EAAEC,MAAM,QAAQ,SAAS;AACzC,SAASC,iBAAiB,EAAEC,kBAAkB,QAAQ,cAAc;AAEpE;;;;;;;;;CASC,GACD,OAAO,MAAMC,wBAAwB,mBAAmB;AAExD;;;;;;;;;;;;CAYC,GACD,OAAO,MAAMC,sBAAsB,oBAAoB;AAEvD;;;;;;;;CAQC,GACD,OAAO,MAAMC,gCAAgCN,QAAQO,OAAO,GAGxD;AAA4B;AAEhC,8EAA8E,GAC9E,MAAMC,UAAU,CAACC,UAA8BC;IAC7C,IAAID,aAAaE,WAAW,OAAO;IACnC,MAAMC,OAAOC,OAAOC,IAAI,CAACL;IACzB,MAAMM,QAAQF,OAAOC,IAAI,CAACJ;IAC1B,yEAAyE;IACzE,iEAAiE;IACjE,OAAOE,KAAKI,MAAM,KAAKD,MAAMC,MAAM,IAAIlB,gBAAgBc,MAAMG;AAC/D;AAEA,MAAME,kBAAkBd,mBAAmBe,IAAI,CAC7C;IAAEC,OAAO;IAAmBC,MAAM;AAAkB,GACpD;IAAEC,QAAQ;AAAI;AAGhB,MAAMC,YAAY,CAACC,aACjBpB,mBAAmBe,IAAI,CACrB;QAAEC,OAAO;QAAaC,MAAM;QAAaG;IAAW,GACpD;QAAEF,QAAQ;IAAI;AAGlB,MAAMG,uBAAuBrB,mBAAmBe,IAAI,CAClD;IACEC,OAAO;IACPC,MAAM;IACNK,QAAQ,GAAGpB,oBAAoB,YAAY,CAAC;AAC9C,GACA;IAAEgB,QAAQ;AAAI;AAGhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCC,GACD,OAAO,MAAMK,yBACX,CAACH,aACD,CAAUI,MACR,sEAAsE;QACtE,0EAA0E;QAC1E,0EAA0E;QAC1E,iEAAiE;QACjE1B,OAAO2B,GAAG,CAAC;gBAacC;YAZvB,MAAMA,UAAU,OAAO3B,kBAAkBA,iBAAiB;YAC1D,MAAMQ,WAAW,OAAOJ;YAExB,IAAI,CAACE,QAAQqB,QAAQC,OAAO,CAAC1B,sBAAsB,EAAEM,WAAW;gBAC9D,OAAO,OAAOO;YAChB;YAEA,MAAMc,WAAW,OAAOhC;YACxB,IAAI,CAACgC,SAASC,MAAM,CAACT,aAAa;gBAChC,OAAO,OAAOD,UAAUC;YAC1B;YAEA,MAAMU,kBAAiBJ,uCAAAA,QAAQC,OAAO,CAACzB,oBAAoB,qBAApCwB,qCAAsCK,IAAI;YACjE,IAAID,mBAAmBtB,aAAasB,mBAAmB,IAAI;gBACzD,OAAO,OAAOT;YAChB;YAEA,OAAO,OAAOG,IAAIM;QACpB,GAAG;AAEP;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,MAAME,kBACX,CAACZ,aACD,CAAUa,QACRnC,OAAO2B,GAAG,CAAC;YACT,MAAMC,UAAU,OAAO3B,kBAAkBA,iBAAiB;YAC1D,MAAMQ,WAAW,OAAOJ;YAExB,IAAI,CAACE,QAAQqB,QAAQC,OAAO,CAAC1B,sBAAsB,EAAEM,WAAW;gBAC9D,OAAO,OAAOO;YAChB;YAEA,MAAMc,WAAW,OAAOhC;YACxB,IAAI,CAACgC,SAASC,MAAM,CAACT,aAAa;gBAChC,OAAO,OAAOD,UAAUC;YAC1B;YAEA,OAAO,OAAOa;QAChB,GAAG"}
+{"version":3,"sources":["../../src/auth/require-service-crossing.ts"],"sourcesContent":["import { timingSafeEqual } from 'node:crypto';\n\nimport { type Permission, ServiceCrossingPolicyTag } from '@entifix/authz';\nimport { Context, Effect } from 'effect';\nimport { HttpServerRequest, HttpServerResponse } from 'effect/http';\n\n/**\n * The header carrying the crossing secret.\n *\n * ⚠️ **Deliberately not `x-service-token`.** That header is config-service's\n * fleet lookup, and the two secrets are not comparable: one grants a\n * configuration *read*, this one a tenant-data *write* for any organization the\n * caller names. Sharing the header name is how a proxy configured to forward the\n * fleet token ends up presenting it to a route that writes stock, and how a\n * copy-pasted value looks right while being the wrong secret entirely.\n */\nexport const CROSSING_TOKEN_HEADER = 'x-crossing-token';\n\n/**\n * The header naming the organization the caller is acting for.\n *\n * It rides beside the token rather than inside the request body because\n * entities are organization-agnostic by rule — no `organizationId` member, no\n * tenant filter — so there is nowhere in an entity envelope for it to live. A\n * header also serves the crossings that carry no body at all (releasing a hold,\n * converting one), which a body field would have needed a second convention for.\n *\n * On its own it grants **nothing**: it is only read after the token has proved\n * the caller is the fleet, so the input the caller controls is never the input\n * that authorizes.\n */\nexport const ORGANIZATION_HEADER = 'x-organization-id';\n\n/**\n * The header a saga dispatch carries its command id in — what a participant\n * dedupes a redelivered command on, and what its unit of work claims.\n */\nexport const COMMAND_ID_HEADER = 'x-command-id';\n\n/**\n * The crossing secret this service expects, provided at the composition root\n * from its own configuration.\n *\n * A `Context.Tag` rather than an environment read, which is the difference from\n * {@link requireServiceToken}: the value is a per-service secret held in\n * config-service as an `is_secret` row, so it arrives through the same boot\n * fetch as `mongo.uri` and can be rotated without redeploying a container.\n */\nexport class ServiceCrossingTokenTag extends Context.Service<\n  ServiceCrossingTokenTag,\n  string\n>()('ServiceCrossingTokenTag') {}\n\n/** Constant-time comparison, so the secret cannot be recovered byte by byte. */\nconst matches = (provided: string | undefined, expected: string): boolean => {\n  if (provided === undefined) return false;\n  const left = Buffer.from(provided);\n  const right = Buffer.from(expected);\n  // `timingSafeEqual` throws on a length mismatch, so lengths are compared\n  // first — the length of a shared secret is not what protects it.\n  return left.length === right.length && timingSafeEqual(left, right);\n};\n\nconst unauthenticated = HttpServerResponse.json(\n  { error: 'unauthenticated', code: 'unauthenticated' },\n  { status: 401 },\n);\n\nconst forbidden = (permission: Permission) =>\n  HttpServerResponse.json(\n    { error: 'forbidden', code: 'forbidden', permission },\n    { status: 403 },\n  );\n\nconst organizationRequired = HttpServerResponse.json(\n  {\n    error: 'the crossing must name an organization',\n    code: 'invalidRequest',\n    detail: `${ORGANIZATION_HEADER} is required`,\n  },\n  { status: 400 },\n);\n\n/**\n * Guard a **service-to-service** tenant crossing: the second — and only other —\n * way a request resolves the organization it acts for.\n *\n * The first is {@link requireOrganization}, which reads the session's\n * `activeOrganizationId` and is the only *user-facing* resolution. This one\n * exists because a platform-plane caller sometimes acts for an organization the\n * principal is not a member of: checkout reserving a vendor's stock, where the\n * organization comes from the **item** and a buyer's session carries none — and\n * never will, since making a buyer a member of every vendor they buy from would\n * be a far worse breach than the problem it solved.\n *\n * There is no third path, no fallback and no operator branch. A request\n * satisfying neither guard simply never reaches a tenant handle. An operator\n * reaching into a tenant is a *different* mechanism — a person choosing an\n * organization, which needs a human's permission, a time box and a record of\n * the crossing — and does not belong in this guard.\n *\n * ⚠️ **This guard reads no cookie and no `Authorization` header, and that is\n * the design.** A route guarded here accepts the crossing token and nothing\n * else: two accepted credentials on one route means the weaker one is the\n * security level. It matters concretely — `super-admin` holds `*:*:*`, which\n * matches every crossing permission, so a route that also took a session would\n * be reachable by an operator's browser tab.\n *\n * Three checks, in this order, so nothing is revealed before fleet membership is\n * proven:\n *\n * 1. the token, compared in constant time → `401`;\n * 2. the permission, against `ServiceCrossingPolicyTag` → `403`. The token\n *    proves the caller is the fleet; it does not say what the caller may do, and\n *    fleet membership is not a capability;\n * 3. the organization header, non-blank → `400`.\n *\n * **The residual, stated rather than argued away**: a shared secret\n * means any process holding it can name any organization. What bounds it is the\n * permission above, the fact that only the slices needing it are configured with\n * the key, and the request log. What would remove it is an RS256 service token\n * carrying a scope claim, which is named work rather than a gap nobody noticed.\n */\nexport const requireServiceCrossing =\n  (permission: Permission) =>\n  <A, E, R>(use: (organizationId: string) => Effect.Effect<A, E, R>) =>\n    // The return type is inferred rather than written out, for the reason\n    // `requireServiceToken` records: `HttpServerResponse.json` contributes an\n    // `HttpBodyError` to the failure channel, and spelling the type out while\n    // omitting it is what makes the declaration emit fail invisibly.\n    Effect.gen(function* () {\n      const request = yield* HttpServerRequest.HttpServerRequest;\n      const expected = yield* ServiceCrossingTokenTag;\n\n      if (!matches(request.headers[CROSSING_TOKEN_HEADER], expected)) {\n        return yield* unauthenticated;\n      }\n\n      const crossing = yield* ServiceCrossingPolicyTag;\n      if (!crossing.allows(permission)) {\n        return yield* forbidden(permission);\n      }\n\n      const organizationId = request.headers[ORGANIZATION_HEADER]?.trim();\n      if (organizationId === undefined || organizationId === '') {\n        return yield* organizationRequired;\n      }\n\n      return yield* use(organizationId);\n    });\n\n/**\n * The same fleet check, for a participant that has **no organization to name**.\n *\n * ⚠️ **A platform-plane store is the whole difference.** `requireServiceCrossing`\n * above ends with an organization header because it is about to resolve a tenant\n * database handle from it, and a blank one there would read some other vendor's\n * storage. order-service names one database at boot, so there is no handle to\n * choose — and demanding a header nothing consumes would be theatre that a\n * caller learns to satisfy with any value.\n *\n * What is unchanged, and is the part that matters: the token proves the caller\n * is the fleet, the host's `ServiceCrossingPolicy` says what the fleet may do,\n * and **no session is accepted**. A saga step is not a person's act — the buyer\n * behind a checkout holds no grant over the order the coordinator is writing on\n * their behalf, and accepting their session here would make the weaker\n * credential the security level.\n *\n * The recorded residual carries over verbatim: a shared secret means any process\n * holding it can act, bounded by the permission and by which slices are\n * configured with the key.\n */\nexport const requireCrossing =\n  (permission: Permission) =>\n  <A, E, R>(route: Effect.Effect<A, E, R>) =>\n    Effect.gen(function* () {\n      const request = yield* HttpServerRequest.HttpServerRequest;\n      const expected = yield* ServiceCrossingTokenTag;\n\n      if (!matches(request.headers[CROSSING_TOKEN_HEADER], expected)) {\n        return yield* unauthenticated;\n      }\n\n      const crossing = yield* ServiceCrossingPolicyTag;\n      if (!crossing.allows(permission)) {\n        return yield* forbidden(permission);\n      }\n\n      return yield* route;\n    });\n"],"names":["timingSafeEqual","ServiceCrossingPolicyTag","Context","Effect","HttpServerRequest","HttpServerResponse","CROSSING_TOKEN_HEADER","ORGANIZATION_HEADER","COMMAND_ID_HEADER","ServiceCrossingTokenTag","Service","matches","provided","expected","undefined","left","Buffer","from","right","length","unauthenticated","json","error","code","status","forbidden","permission","organizationRequired","detail","requireServiceCrossing","use","gen","request","headers","crossing","allows","organizationId","trim","requireCrossing","route"],"mappings":"AAAA,SAASA,eAAe,QAAQ,cAAc;AAE9C,SAA0BC,wBAAwB,QAAQ,iBAAiB;AAC3E,SAASC,OAAO,EAAEC,MAAM,QAAQ,SAAS;AACzC,SAASC,iBAAiB,EAAEC,kBAAkB,QAAQ,cAAc;AAEpE;;;;;;;;;CASC,GACD,OAAO,MAAMC,wBAAwB,mBAAmB;AAExD;;;;;;;;;;;;CAYC,GACD,OAAO,MAAMC,sBAAsB,oBAAoB;AAEvD;;;CAGC,GACD,OAAO,MAAMC,oBAAoB,eAAe;AAEhD;;;;;;;;CAQC,GACD,OAAO,MAAMC,gCAAgCP,QAAQQ,OAAO,GAGxD;AAA4B;AAEhC,8EAA8E,GAC9E,MAAMC,UAAU,CAACC,UAA8BC;IAC7C,IAAID,aAAaE,WAAW,OAAO;IACnC,MAAMC,OAAOC,OAAOC,IAAI,CAACL;IACzB,MAAMM,QAAQF,OAAOC,IAAI,CAACJ;IAC1B,yEAAyE;IACzE,iEAAiE;IACjE,OAAOE,KAAKI,MAAM,KAAKD,MAAMC,MAAM,IAAInB,gBAAgBe,MAAMG;AAC/D;AAEA,MAAME,kBAAkBf,mBAAmBgB,IAAI,CAC7C;IAAEC,OAAO;IAAmBC,MAAM;AAAkB,GACpD;IAAEC,QAAQ;AAAI;AAGhB,MAAMC,YAAY,CAACC,aACjBrB,mBAAmBgB,IAAI,CACrB;QAAEC,OAAO;QAAaC,MAAM;QAAaG;IAAW,GACpD;QAAEF,QAAQ;IAAI;AAGlB,MAAMG,uBAAuBtB,mBAAmBgB,IAAI,CAClD;IACEC,OAAO;IACPC,MAAM;IACNK,QAAQ,GAAGrB,oBAAoB,YAAY,CAAC;AAC9C,GACA;IAAEiB,QAAQ;AAAI;AAGhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCC,GACD,OAAO,MAAMK,yBACX,CAACH,aACD,CAAUI,MACR,sEAAsE;QACtE,0EAA0E;QAC1E,0EAA0E;QAC1E,iEAAiE;QACjE3B,OAAO4B,GAAG,CAAC;gBAacC;YAZvB,MAAMA,UAAU,OAAO5B,kBAAkBA,iBAAiB;YAC1D,MAAMS,WAAW,OAAOJ;YAExB,IAAI,CAACE,QAAQqB,QAAQC,OAAO,CAAC3B,sBAAsB,EAAEO,WAAW;gBAC9D,OAAO,OAAOO;YAChB;YAEA,MAAMc,WAAW,OAAOjC;YACxB,IAAI,CAACiC,SAASC,MAAM,CAACT,aAAa;gBAChC,OAAO,OAAOD,UAAUC;YAC1B;YAEA,MAAMU,kBAAiBJ,uCAAAA,QAAQC,OAAO,CAAC1B,oBAAoB,qBAApCyB,qCAAsCK,IAAI;YACjE,IAAID,mBAAmBtB,aAAasB,mBAAmB,IAAI;gBACzD,OAAO,OAAOT;YAChB;YAEA,OAAO,OAAOG,IAAIM;QACpB,GAAG;AAEP;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,MAAME,kBACX,CAACZ,aACD,CAAUa,QACRpC,OAAO4B,GAAG,CAAC;YACT,MAAMC,UAAU,OAAO5B,kBAAkBA,iBAAiB;YAC1D,MAAMS,WAAW,OAAOJ;YAExB,IAAI,CAACE,QAAQqB,QAAQC,OAAO,CAAC3B,sBAAsB,EAAEO,WAAW;gBAC9D,OAAO,OAAOO;YAChB;YAEA,MAAMc,WAAW,OAAOjC;YACxB,IAAI,CAACiC,SAASC,MAAM,CAACT,aAAa;gBAChC,OAAO,OAAOD,UAAUC;YAC1B;YAEA,OAAO,OAAOa;QAChB,GAAG"}

package/dist/entity-routes.d.ts

@@ -0,0 +1,112 @@
+import { type PolicyDecisionTag, type ServiceCrossingPolicyTag } from '@entifix/authz';
+import { EntityRepositoryFactoryTag, type RepositoryScope, type TokenServiceTag } from '@entifix/business';
+import { EntifixBuildError, type EntifixEnvelopeLink, type Entity, type EntityConstructor, type EntityId, type FilterGroup } from '@entifix/core';
+import { Effect } from 'effect';
+import { HttpRouter, HttpServerResponse } from 'effect/http';
+import { type RequestPrincipal, type ServiceCrossingTokenTag } from './auth/index.js';
+/** The five generic verbs a route set can mount. */
+export type EntityVerb = 'list' | 'get' | 'create' | 'update' | 'delete';
+/**
+ * Who may reach a route, and where the organization a per-organization store
+ * needs comes from.
+ *
+ * - `public` — anybody; nothing is checked and no organization is known.
+ * - `permission` — a verified session holding the permission the entity
+ *   derives for the verb.
+ * - `organization` — the same, plus the session's active organization, which
+ *   is what a per-organization store opens.
+ * - `crossing` — the fleet's crossing token and no session at all. With
+ *   `organization: true` the caller names the organization in a header, which
+ *   only a caller that has proved it is the fleet may do.
+ */
+export type EntityRouteGuard = {
+    readonly kind: 'public';
+} | {
+    readonly kind: 'permission';
+} | {
+    readonly kind: 'organization';
+} | {
+    readonly kind: 'crossing';
+    readonly organization: boolean;
+};
+/** What a route learned about its caller from its guard. */
+export interface EntityRouteContext extends RepositoryScope {
+    readonly principal?: RequestPrincipal;
+}
+/**
+ * Which records of an entity a caller may see.
+ *
+ * `filter` narrows a list and `includes` decides a by-id read — both are
+ * needed, because `id` is the one member no query can name. `'none'` is a
+ * caller who holds the read grant and owns nothing: an empty page and a `404`,
+ * never a `403`, because owning no records is not an error.
+ */
+export type EntityReadScope<T extends Entity> = 'all' | 'none' | {
+    readonly filter: FilterGroup<T>;
+    readonly includes: (entity: T) => boolean;
+};
+/**
+ * A save refused by a rule the entity's own deserializer does not make — a
+ * closed set, a rule over the other records — answered as `status` with
+ * `code`, which is what a client translates.
+ */
+export declare class EntityRouteRefusal {
+    readonly status: 400 | 409 | 422;
+    readonly code: string;
+    readonly detail?: string | undefined;
+    readonly _tag = "EntityRouteRefusal";
+    constructor(status: 400 | 409 | 422, code: string, detail?: string | undefined);
+}
+/** A hand-written handler for one verb, mounted under the derived guard. */
+export type EntityRouteOverride<R> = (context: EntityRouteContext, links: EntityRouteLinks) => Effect.Effect<HttpServerResponse.HttpServerResponse, unknown, R>;
+/** The affordances a route set derives from the verbs it mounts. */
+export interface EntityRouteLinks {
+    readonly record: (id: EntityId) => EntifixEnvelopeLink[];
+    readonly collection: () => EntifixEnvelopeLink[];
+}
+export interface EntityRoutesOptions<T extends Entity, R, G extends EntityRouteGuard = EntityRouteGuard> {
+    readonly verbs: readonly EntityVerb[];
+    /** One guard for every verb, or one for the reads and one for the writes. */
+    readonly guard: G | {
+        readonly read: G;
+        readonly write: G;
+    };
+    /** Defaults to `/api/<entity key>`. */
+    readonly basePath?: `/${string}`;
+    /** Narrows the reads to what this caller may see. */
+    readonly scope?: (context: EntityRouteContext) => Effect.Effect<EntityReadScope<T>, never, R>;
+    /**
+     * Runs on every create and update, after the body is read and before the
+     * save — and may change what is saved, or refuse it.
+     */
+    readonly prepare?: (entity: T, context: EntityRouteContext & {
+        readonly verb: 'create' | 'update';
+    }) => Effect.Effect<T, EntityRouteRefusal | EntifixBuildError, R>;
+    /**
+     * A hand-written handler in place of the generic one for a verb. It keeps
+     * the derived guard and receives the derived links, so the escape hatch
+     * cannot drift from the rest of the set.
+     */
+    readonly override?: Partial<Record<EntityVerb, EntityRouteOverride<R>>>;
+}
+/** The `500` for anything a route did not anticipate. */
+export declare const routeFailure: (error: unknown) => Effect.Effect<HttpServerResponse.HttpServerResponse, import("effect/http/HttpBody").HttpBodyError, never>;
+/**
+ * The generic routes for one entity — list, read, create, update, delete and
+ * its `$metadata` — derived from the entity and bound to storage through the
+ * host's {@link EntityRepositoryFactoryTag}.
+ *
+ * What a route set varies on is stated, not written: which verbs exist, who may
+ * reach them, which records a reader sees, and what a save must pass. What it
+ * never varies on is the wire: the load request is parsed against the entity's
+ * own metadata (so a query can only name a member the entity declared
+ * filterable or sortable), every answer is an envelope, and the links name
+ * exactly the verbs mounted — never one that would `404`.
+ *
+ * A path that is not one of these verbs is written by hand beside it, and a
+ * verb whose generic form does not fit is replaced with `override`.
+ */
+export declare const makeEntityRoutes: <T extends Entity, R = never, const G extends EntityRouteGuard = EntityRouteGuard>(entityConstructor: EntityConstructor<T>, options: EntityRoutesOptions<T, R, G>) => import("effect/Layer").Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Requires", PolicyDecisionTag> | HttpRouter.Request<"Requires", EntityRepositoryFactoryTag> | HttpRouter.Request<"Requires", TokenServiceTag> | HttpRouter.Request.From<"Requires", Exclude<Exclude<R, HttpRouter.Provided>, HttpRouter.Provided>> | HttpRouter.Request.From<"Requires", Exclude<Exclude<G extends {
+    readonly kind: "crossing";
+} ? ServiceCrossingPolicyTag | ServiceCrossingTokenTag : never, HttpRouter.Provided>, HttpRouter.Provided>> | HttpRouter.Request<"Error", unknown>>;
+//# sourceMappingURL=entity-routes.d.ts.map

package/dist/entity-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-routes.d.ts","sourceRoot":"","sources":["../src/entity-routes.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC9B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAIL,0BAA0B,EAK1B,KAAK,eAAe,EAEpB,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,MAAM,EACX,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EAIb,KAAK,WAAW,EAKjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,UAAU,EAAqB,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,EACL,KAAK,gBAAgB,EAKrB,KAAK,uBAAuB,EAC7B,MAAM,iBAAiB,CAAC;AAGzB,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEzE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC;AAElE,4DAA4D;AAC5D,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,IACxC,KAAK,GACL,MAAM,GACN;IACE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC;CAC3C,CAAC;AAEN;;;;GAIG;AACH,qBAAa,kBAAkB;IAI3B,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAL1B,QAAQ,CAAC,IAAI,wBAAwB;gBAG1B,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,EACvB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,YAAA;CAE3B;AAED,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CACnC,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,gBAAgB,KACpB,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;AAEtE,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,mBAAmB,EAAE,CAAC;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,mBAAmB,EAAE,CAAC;CAClD;AAED,MAAM,WAAW,mBAAmB,CAClC,CAAC,SAAS,MAAM,EAChB,CAAC,EACD,CAAC,SAAS,gBAAgB,GAAG,gBAAgB;IAE7C,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAC;IAC5D,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,MAAM,EAAE,CAAC;IACjC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,CACf,OAAO,EAAE,kBAAkB,KACxB,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACjD;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CACjB,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,kBAAkB,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAA;KAAE,KACjE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,kBAAkB,GAAG,iBAAiB,EAAE,CAAC,CAAC,CAAC;IACjE;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACzE;AAwBD,yDAAyD;AACzD,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,8GAIxC,CAAC;AA8BJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,GAC3B,CAAC,SAAS,MAAM,EAChB,CAAC,GAAG,KAAK,EACT,KAAK,CAAC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB,EAEnD,mBAAmB,iBAAiB,CAAC,CAAC,CAAC,EACvC,SAAS,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;mBA5DP,UAAU;mJA6UzC,CAAC"}

package/dist/entity-routes.js

@@ -0,0 +1,302 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { permissionForEntity } from '@entifix/authz';
+import { deleteUCFactory, EntityIdTag, EntityLoadRequestTag, EntityRepositoryFactoryTag, EntityRepositoryTag, EntityTag, getUCFactory, loadUCFactory, saveUCFactory } from '@entifix/business';
+import { EntifixBuildError, envelopeEntityName, extractMetaEntity, makeEntityEnvelope, makeEntityPageEnvelope, parseLoadRequestParams, readEntityEnvelope } from '@entifix/core';
+import { Effect } from 'effect';
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from 'effect/http';
+import { requireCrossing, requireOrganization, requirePermission, requireServiceCrossing } from './auth/index.js';
+import { entityMetadataRoute } from './entity-metadata-route.js';
+/**
+ * A save refused by a rule the entity's own deserializer does not make — a
+ * closed set, a rule over the other records — answered as `status` with
+ * `code`, which is what a client translates.
+ */ export class EntityRouteRefusal {
+    constructor(status, code, detail){
+        this.status = status;
+        this.code = code;
+        this.detail = detail;
+        this._tag = 'EntityRouteRefusal';
+    }
+}
+const ACTION = {
+    list: 'read',
+    get: 'read',
+    create: 'write',
+    update: 'write',
+    delete: 'delete'
+};
+const READS = new Set([
+    'list',
+    'get'
+]);
+/** The `500` for anything a route did not anticipate. */ export const routeFailure = (error)=>HttpServerResponse.json({
+        error: 'request failed',
+        code: 'unexpected',
+        detail: String(error)
+    }, {
+        status: 500
+    });
+const invalid = (error, label, code)=>{
+    var _refusalCode;
+    return error instanceof EntifixBuildError ? HttpServerResponse.json({
+        error: label,
+        code: (_refusalCode = refusalCode(error)) != null ? _refusalCode : code,
+        detail: error.message
+    }, {
+        status: 400
+    }) : error instanceof EntityRouteRefusal ? HttpServerResponse.json(_extends({
+        error: 'the record cannot be saved',
+        code: error.code
+    }, error.detail === undefined ? {} : {
+        detail: error.detail
+    }), {
+        status: error.status
+    }) : routeFailure(error);
+};
+/**
+ * A domain error may carry its own code (`mediaNotHttps`), so the client can
+ * say which rule failed rather than "invalid body".
+ */ const refusalCode = (error)=>'code' in error && typeof error.code === 'string' ? error.code : undefined;
+/**
+ * The generic routes for one entity — list, read, create, update, delete and
+ * its `$metadata` — derived from the entity and bound to storage through the
+ * host's {@link EntityRepositoryFactoryTag}.
+ *
+ * What a route set varies on is stated, not written: which verbs exist, who may
+ * reach them, which records a reader sees, and what a save must pass. What it
+ * never varies on is the wire: the load request is parsed against the entity's
+ * own metadata (so a query can only name a member the entity declared
+ * filterable or sortable), every answer is an envelope, and the links name
+ * exactly the verbs mounted — never one that would `404`.
+ *
+ * A path that is not one of these verbs is written by hand beside it, and a
+ * verb whose generic form does not fit is replaced with `override`.
+ */ export const makeEntityRoutes = (entityConstructor, options)=>{
+    var _options_basePath;
+    const key = envelopeEntityName(entityConstructor);
+    const base = (_options_basePath = options.basePath) != null ? _options_basePath : `/api/${key}`;
+    const mounted = new Set(options.verbs);
+    const links = {
+        record: (id)=>{
+            const href = `${base}/${String(id)}`;
+            return [
+                ...mounted.has('get') ? [
+                    {
+                        rel: 'self',
+                        href,
+                        method: 'GET'
+                    }
+                ] : [],
+                ...mounted.has('list') ? [
+                    {
+                        rel: 'list',
+                        href: base,
+                        method: 'GET'
+                    }
+                ] : [],
+                ...mounted.has('update') ? [
+                    {
+                        rel: 'update',
+                        href,
+                        method: 'PUT'
+                    }
+                ] : [],
+                ...mounted.has('delete') ? [
+                    {
+                        rel: 'delete',
+                        href,
+                        method: 'DELETE'
+                    }
+                ] : []
+            ];
+        },
+        collection: ()=>[
+                ...mounted.has('list') ? [
+                    {
+                        rel: 'self',
+                        href: base,
+                        method: 'GET'
+                    }
+                ] : [],
+                ...mounted.has('create') ? [
+                    {
+                        rel: 'create',
+                        href: base,
+                        method: 'POST'
+                    }
+                ] : []
+            ]
+    };
+    const guardFor = (verb)=>{
+        const guard = options.guard;
+        return 'kind' in guard ? guard : READS.has(verb) ? guard.read : guard.write;
+    };
+    const guarded = (verb, use)=>{
+        const guard = guardFor(verb);
+        const permission = permissionForEntity(entityConstructor, ACTION[verb]);
+        switch(guard.kind){
+            case 'public':
+                return use({});
+            case 'permission':
+                return requirePermission(permission)((principal)=>use({
+                        principal
+                    }));
+            case 'organization':
+                return requireOrganization(permission)((organizationId, principal)=>use({
+                        organizationId,
+                        principal
+                    }));
+            case 'crossing':
+                return guard.organization ? requireServiceCrossing(permission)((organizationId)=>use({
+                        organizationId
+                    })) : requireCrossing(permission)(use({}));
+        }
+    };
+    const repository = (context)=>Effect.gen(function*() {
+            const factory = yield* EntityRepositoryFactoryTag;
+            return yield* factory.for(entityConstructor, _extends({}, context.organizationId === undefined ? {} : {
+                organizationId: context.organizationId
+            }));
+        });
+    const scopeOf = (context)=>options.scope ? options.scope(context) : Effect.succeed('all');
+    const readLoadRequest = Effect.gen(function*() {
+        const request = yield* HttpServerRequest.HttpServerRequest;
+        const search = new URL(request.url, 'http://localhost').searchParams;
+        return yield* Effect.try({
+            try: ()=>parseLoadRequestParams(entityConstructor, search),
+            catch: (error)=>error
+        });
+    });
+    const notFound = HttpServerResponse.json({
+        message: 'not found',
+        code: 'notFound',
+        entity: extractMetaEntity(entityConstructor).key
+    }, {
+        status: 404
+    });
+    const list = (context)=>Effect.gen(function*() {
+            var _parsed_filtering;
+            const parsed = yield* readLoadRequest;
+            const scope = yield* scopeOf(context);
+            if (scope === 'none') {
+                // Still parsed: whether a query is well-formed must not depend on who
+                // asked.
+                return yield* HttpServerResponse.json(makeEntityPageEnvelope(entityConstructor, {
+                    items: [],
+                    total: 0,
+                    request: parsed
+                }, links.collection()));
+            }
+            // Conjoined, never substituted: the translator `$and`s every top-level
+            // element, so an added element can only narrow, and no `or` in a query
+            // string can escape it.
+            const request = scope === 'all' ? parsed : _extends({}, parsed, {
+                filtering: [
+                    ...(_parsed_filtering = parsed.filtering) != null ? _parsed_filtering : [],
+                    scope.filter
+                ]
+            });
+            const page = yield* loadUCFactory().pipe(Effect.provideService(EntityRepositoryTag, (yield* repository(context))), Effect.provideService(EntityLoadRequestTag, request));
+            return yield* HttpServerResponse.json(makeEntityPageEnvelope(entityConstructor, page, links.collection()));
+        }).pipe(Effect.catch((error)=>invalid(error, 'invalid query', 'invalidQuery')));
+    const get = (context)=>Effect.gen(function*() {
+            const params = yield* HttpRouter.params;
+            const scope = yield* scopeOf(context);
+            if (scope === 'none') return yield* notFound;
+            const found = yield* getUCFactory().pipe(Effect.provideService(EntityRepositoryTag, (yield* repository(context))), Effect.provideService(EntityIdTag, params.id), Effect.option);
+            // Out of scope answers exactly as absent does: a `403` would confirm the
+            // record exists to somebody who may not read it.
+            if (found._tag === 'None' || scope !== 'all' && !scope.includes(found.value)) {
+                return yield* notFound;
+            }
+            return yield* HttpServerResponse.json(makeEntityEnvelope(entityConstructor, found.value, links.record(params.id)));
+        }).pipe(Effect.catch(routeFailure));
+    const save = (verb)=>(context)=>Effect.gen(function*() {
+                const request = yield* HttpServerRequest.HttpServerRequest;
+                const body = yield* request.json;
+                let entity = yield* readEntityEnvelope(entityConstructor, body);
+                // On update the URL is authoritative, so a record cannot be renamed
+                // onto another one by editing its payload.
+                if (verb === 'update') {
+                    const params = yield* HttpRouter.params;
+                    entity.id = params.id;
+                }
+                if (options.prepare) {
+                    entity = yield* options.prepare(entity, _extends({}, context, {
+                        verb
+                    }));
+                }
+                const saved = yield* saveUCFactory().pipe(Effect.provideService(EntityRepositoryTag, (yield* repository(context))), Effect.provideService(EntityTag, entity));
+                return yield* HttpServerResponse.json(makeEntityEnvelope(entityConstructor, saved, links.record(saved.id)));
+            }).pipe(Effect.catch((error)=>invalid(error, 'invalid request body', 'invalidBody')));
+    /**
+   * Answers with an envelope rather than a bare `204`: every message between
+   * entifix artifacts is one, and the fetch client parses every response as
+   * JSON.
+   */ const remove = (context)=>Effect.gen(function*() {
+            const params = yield* HttpRouter.params;
+            yield* deleteUCFactory().pipe(Effect.provideService(EntityRepositoryTag, (yield* repository(context))), Effect.provideService(EntityIdTag, params.id));
+            return yield* HttpServerResponse.json({
+                meta: {
+                    type: 'entity',
+                    entity: key,
+                    links: links.collection()
+                },
+                data: {
+                    id: params.id
+                }
+            });
+        }).pipe(Effect.catch(routeFailure));
+    const generic = (verb, context)=>{
+        switch(verb){
+            case 'list':
+                return list(context);
+            case 'get':
+                return get(context);
+            case 'create':
+                return save('create')(context);
+            case 'update':
+                return save('update')(context);
+            case 'delete':
+                return remove(context);
+        }
+    };
+    /**
+   * Each guard asks for different services, so the branches do not unify on
+   * their own; the cast states the union every guard this set can reach
+   * actually needs.
+   */ const handlerFor = (verb)=>guarded(verb, (context)=>{
+            var _options_override;
+            const override = (_options_override = options.override) == null ? void 0 : _options_override[verb];
+            return override ? override(context, links) : generic(verb, context);
+        });
+    const ROUTES = {
+        list: {
+            method: 'GET',
+            path: base
+        },
+        get: {
+            method: 'GET',
+            path: `${base}/:id`
+        },
+        create: {
+            method: 'POST',
+            path: base
+        },
+        update: {
+            method: 'PUT',
+            path: `${base}/:id`
+        },
+        delete: {
+            method: 'DELETE',
+            path: `${base}/:id`
+        }
+    };
+    return HttpRouter.addAll([
+        // A literal, so it wins over `/:id` regardless of order.
+        HttpRouter.route('GET', `${base}/$metadata`, entityMetadataRoute(entityConstructor)),
+        ...options.verbs.map((verb)=>HttpRouter.route(ROUTES[verb].method, ROUTES[verb].path, handlerFor(verb)))
+    ]);
+};
+
+//# sourceMappingURL=entity-routes.js.map

package/dist/entity-routes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/entity-routes.ts"],"sourcesContent":["import {\n  type Action,\n  permissionForEntity,\n  type PolicyDecisionTag,\n  type ServiceCrossingPolicyTag,\n} from '@entifix/authz';\nimport {\n  deleteUCFactory,\n  EntityIdTag,\n  EntityLoadRequestTag,\n  EntityRepositoryFactoryTag,\n  EntityRepositoryTag,\n  EntityTag,\n  getUCFactory,\n  loadUCFactory,\n  type RepositoryScope,\n  saveUCFactory,\n  type TokenServiceTag,\n} from '@entifix/business';\nimport {\n  EntifixBuildError,\n  type EntifixEnvelopeLink,\n  type Entity,\n  type EntityConstructor,\n  type EntityId,\n  type EntityLoadRequest,\n  envelopeEntityName,\n  extractMetaEntity,\n  type FilterGroup,\n  makeEntityEnvelope,\n  makeEntityPageEnvelope,\n  parseLoadRequestParams,\n  readEntityEnvelope,\n} from '@entifix/core';\nimport { Effect } from 'effect';\nimport { HttpRouter, HttpServerRequest, HttpServerResponse } from 'effect/http';\n\nimport {\n  type RequestPrincipal,\n  requireCrossing,\n  requireOrganization,\n  requirePermission,\n  requireServiceCrossing,\n  type ServiceCrossingTokenTag,\n} from './auth/index.js';\nimport { entityMetadataRoute } from './entity-metadata-route.js';\n\n/** The five generic verbs a route set can mount. */\nexport type EntityVerb = 'list' | 'get' | 'create' | 'update' | 'delete';\n\n/**\n * Who may reach a route, and where the organization a per-organization store\n * needs comes from.\n *\n * - `public` — anybody; nothing is checked and no organization is known.\n * - `permission` — a verified session holding the permission the entity\n *   derives for the verb.\n * - `organization` — the same, plus the session's active organization, which\n *   is what a per-organization store opens.\n * - `crossing` — the fleet's crossing token and no session at all. With\n *   `organization: true` the caller names the organization in a header, which\n *   only a caller that has proved it is the fleet may do.\n */\nexport type EntityRouteGuard =\n  | { readonly kind: 'public' }\n  | { readonly kind: 'permission' }\n  | { readonly kind: 'organization' }\n  | { readonly kind: 'crossing'; readonly organization: boolean };\n\n/** What a route learned about its caller from its guard. */\nexport interface EntityRouteContext extends RepositoryScope {\n  readonly principal?: RequestPrincipal;\n}\n\n/**\n * Which records of an entity a caller may see.\n *\n * `filter` narrows a list and `includes` decides a by-id read — both are\n * needed, because `id` is the one member no query can name. `'none'` is a\n * caller who holds the read grant and owns nothing: an empty page and a `404`,\n * never a `403`, because owning no records is not an error.\n */\nexport type EntityReadScope<T extends Entity> =\n  | 'all'\n  | 'none'\n  | {\n      readonly filter: FilterGroup<T>;\n      readonly includes: (entity: T) => boolean;\n    };\n\n/**\n * A save refused by a rule the entity's own deserializer does not make — a\n * closed set, a rule over the other records — answered as `status` with\n * `code`, which is what a client translates.\n */\nexport class EntityRouteRefusal {\n  readonly _tag = 'EntityRouteRefusal';\n\n  constructor(\n    readonly status: 400 | 409 | 422,\n    readonly code: string,\n    readonly detail?: string,\n  ) {}\n}\n\n/** A hand-written handler for one verb, mounted under the derived guard. */\nexport type EntityRouteOverride<R> = (\n  context: EntityRouteContext,\n  links: EntityRouteLinks,\n) => Effect.Effect<HttpServerResponse.HttpServerResponse, unknown, R>;\n\n/** The affordances a route set derives from the verbs it mounts. */\nexport interface EntityRouteLinks {\n  readonly record: (id: EntityId) => EntifixEnvelopeLink[];\n  readonly collection: () => EntifixEnvelopeLink[];\n}\n\nexport interface EntityRoutesOptions<\n  T extends Entity,\n  R,\n  G extends EntityRouteGuard = EntityRouteGuard,\n> {\n  readonly verbs: readonly EntityVerb[];\n  /** One guard for every verb, or one for the reads and one for the writes. */\n  readonly guard: G | { readonly read: G; readonly write: G };\n  /** Defaults to `/api/<entity key>`. */\n  readonly basePath?: `/${string}`;\n  /** Narrows the reads to what this caller may see. */\n  readonly scope?: (\n    context: EntityRouteContext,\n  ) => Effect.Effect<EntityReadScope<T>, never, R>;\n  /**\n   * Runs on every create and update, after the body is read and before the\n   * save — and may change what is saved, or refuse it.\n   */\n  readonly prepare?: (\n    entity: T,\n    context: EntityRouteContext & { readonly verb: 'create' | 'update' },\n  ) => Effect.Effect<T, EntityRouteRefusal | EntifixBuildError, R>;\n  /**\n   * A hand-written handler in place of the generic one for a verb. It keeps\n   * the derived guard and receives the derived links, so the escape hatch\n   * cannot drift from the rest of the set.\n   */\n  readonly override?: Partial<Record<EntityVerb, EntityRouteOverride<R>>>;\n}\n\nconst ACTION: Record<EntityVerb, Action> = {\n  list: 'read',\n  get: 'read',\n  create: 'write',\n  update: 'write',\n  delete: 'delete',\n};\n\nconst READS: ReadonlySet<EntityVerb> = new Set(['list', 'get']);\n\n/**\n * What a route set needs from the host beyond the repository factory: a\n * session's services always (its `$metadata` reads the caller), the fleet's\n * crossing services only when a guard is a crossing.\n */\ntype GuardServices<G extends EntityRouteGuard> =\n  | TokenServiceTag\n  | PolicyDecisionTag\n  | (G extends { readonly kind: 'crossing' }\n      ? ServiceCrossingTokenTag | ServiceCrossingPolicyTag\n      : never);\n\n/** The `500` for anything a route did not anticipate. */\nexport const routeFailure = (error: unknown) =>\n  HttpServerResponse.json(\n    { error: 'request failed', code: 'unexpected', detail: String(error) },\n    { status: 500 },\n  );\n\nconst invalid = (error: unknown, label: string, code: string) =>\n  error instanceof EntifixBuildError\n    ? HttpServerResponse.json(\n        {\n          error: label,\n          code: refusalCode(error) ?? code,\n          detail: error.message,\n        },\n        { status: 400 },\n      )\n    : error instanceof EntityRouteRefusal\n      ? HttpServerResponse.json(\n          {\n            error: 'the record cannot be saved',\n            code: error.code,\n            ...(error.detail === undefined ? {} : { detail: error.detail }),\n          },\n          { status: error.status },\n        )\n      : routeFailure(error);\n\n/**\n * A domain error may carry its own code (`mediaNotHttps`), so the client can\n * say which rule failed rather than \"invalid body\".\n */\nconst refusalCode = (error: EntifixBuildError): string | undefined =>\n  'code' in error && typeof error.code === 'string' ? error.code : undefined;\n\n/**\n * The generic routes for one entity — list, read, create, update, delete and\n * its `$metadata` — derived from the entity and bound to storage through the\n * host's {@link EntityRepositoryFactoryTag}.\n *\n * What a route set varies on is stated, not written: which verbs exist, who may\n * reach them, which records a reader sees, and what a save must pass. What it\n * never varies on is the wire: the load request is parsed against the entity's\n * own metadata (so a query can only name a member the entity declared\n * filterable or sortable), every answer is an envelope, and the links name\n * exactly the verbs mounted — never one that would `404`.\n *\n * A path that is not one of these verbs is written by hand beside it, and a\n * verb whose generic form does not fit is replaced with `override`.\n */\nexport const makeEntityRoutes = <\n  T extends Entity,\n  R = never,\n  const G extends EntityRouteGuard = EntityRouteGuard,\n>(\n  entityConstructor: EntityConstructor<T>,\n  options: EntityRoutesOptions<T, R, G>,\n) => {\n  const key = envelopeEntityName(entityConstructor);\n  const base: `/${string}` = options.basePath ?? `/api/${key}`;\n  const mounted = new Set(options.verbs);\n\n  const links: EntityRouteLinks = {\n    record: id => {\n      const href = `${base}/${String(id)}`;\n      return [\n        ...(mounted.has('get')\n          ? [{ rel: 'self', href, method: 'GET' } as const]\n          : []),\n        ...(mounted.has('list')\n          ? [{ rel: 'list', href: base, method: 'GET' } as const]\n          : []),\n        ...(mounted.has('update')\n          ? [{ rel: 'update', href, method: 'PUT' } as const]\n          : []),\n        ...(mounted.has('delete')\n          ? [{ rel: 'delete', href, method: 'DELETE' } as const]\n          : []),\n      ];\n    },\n    collection: () => [\n      ...(mounted.has('list')\n        ? [{ rel: 'self', href: base, method: 'GET' } as const]\n        : []),\n      ...(mounted.has('create')\n        ? [{ rel: 'create', href: base, method: 'POST' } as const]\n        : []),\n    ],\n  };\n\n  const guardFor = (verb: EntityVerb): EntityRouteGuard => {\n    const guard = options.guard as\n      | EntityRouteGuard\n      | { readonly read: EntityRouteGuard; readonly write: EntityRouteGuard };\n    return 'kind' in guard ? guard : READS.has(verb) ? guard.read : guard.write;\n  };\n\n  const guarded = <A, E, RR>(\n    verb: EntityVerb,\n    use: (context: EntityRouteContext) => Effect.Effect<A, E, RR>,\n  ) => {\n    const guard = guardFor(verb);\n    const permission = permissionForEntity(entityConstructor, ACTION[verb]);\n    switch (guard.kind) {\n      case 'public':\n        return use({});\n      case 'permission':\n        return requirePermission(permission)(principal => use({ principal }));\n      case 'organization':\n        return requireOrganization(permission)((organizationId, principal) =>\n          use({ organizationId, principal }),\n        );\n      case 'crossing':\n        return guard.organization\n          ? requireServiceCrossing(permission)(organizationId =>\n              use({ organizationId }),\n            )\n          : requireCrossing(permission)(use({}));\n    }\n  };\n\n  const repository = (context: EntityRouteContext) =>\n    Effect.gen(function* () {\n      const factory = yield* EntityRepositoryFactoryTag;\n      return yield* factory.for(entityConstructor, {\n        ...(context.organizationId === undefined\n          ? {}\n          : { organizationId: context.organizationId }),\n      });\n    });\n\n  const scopeOf = (context: EntityRouteContext) =>\n    options.scope ? options.scope(context) : Effect.succeed('all' as const);\n\n  const readLoadRequest = Effect.gen(function* () {\n    const request = yield* HttpServerRequest.HttpServerRequest;\n    const search = new URL(request.url, 'http://localhost').searchParams;\n    return yield* Effect.try({\n      try: () =>\n        parseLoadRequestParams(\n          entityConstructor,\n          search,\n        ) as unknown as EntityLoadRequest<T>,\n      catch: error => error as EntifixBuildError,\n    });\n  });\n\n  const notFound = HttpServerResponse.json(\n    {\n      message: 'not found',\n      code: 'notFound',\n      entity: extractMetaEntity(entityConstructor).key,\n    },\n    { status: 404 },\n  );\n\n  const list = (context: EntityRouteContext) =>\n    Effect.gen(function* () {\n      const parsed = yield* readLoadRequest;\n      const scope = yield* scopeOf(context);\n      if (scope === 'none') {\n        // Still parsed: whether a query is well-formed must not depend on who\n        // asked.\n        return yield* HttpServerResponse.json(\n          makeEntityPageEnvelope(\n            entityConstructor,\n            { items: [], total: 0, request: parsed },\n            links.collection(),\n          ),\n        );\n      }\n      // Conjoined, never substituted: the translator `$and`s every top-level\n      // element, so an added element can only narrow, and no `or` in a query\n      // string can escape it.\n      const request: EntityLoadRequest<T> =\n        scope === 'all'\n          ? parsed\n          : {\n              ...parsed,\n              filtering: [...(parsed.filtering ?? []), scope.filter],\n            };\n      const page = yield* loadUCFactory<T>().pipe(\n        Effect.provideService(EntityRepositoryTag, yield* repository(context)),\n        Effect.provideService(\n          EntityLoadRequestTag,\n          request as unknown as EntityLoadRequest,\n        ),\n      );\n      return yield* HttpServerResponse.json(\n        makeEntityPageEnvelope(entityConstructor, page, links.collection()),\n      );\n    }).pipe(\n      Effect.catch(error => invalid(error, 'invalid query', 'invalidQuery')),\n    );\n\n  const get = (context: EntityRouteContext) =>\n    Effect.gen(function* () {\n      const params = yield* HttpRouter.params;\n      const scope = yield* scopeOf(context);\n      if (scope === 'none') return yield* notFound;\n      const found = yield* getUCFactory<T>().pipe(\n        Effect.provideService(EntityRepositoryTag, yield* repository(context)),\n        Effect.provideService(EntityIdTag, params.id),\n        Effect.option,\n      );\n      // Out of scope answers exactly as absent does: a `403` would confirm the\n      // record exists to somebody who may not read it.\n      if (\n        found._tag === 'None' ||\n        (scope !== 'all' && !scope.includes(found.value))\n      ) {\n        return yield* notFound;\n      }\n      return yield* HttpServerResponse.json(\n        makeEntityEnvelope(\n          entityConstructor,\n          found.value,\n          links.record(params.id),\n        ),\n      );\n    }).pipe(Effect.catch(routeFailure));\n\n  const save = (verb: 'create' | 'update') => (context: EntityRouteContext) =>\n    Effect.gen(function* () {\n      const request = yield* HttpServerRequest.HttpServerRequest;\n      const body = yield* request.json;\n      let entity = yield* readEntityEnvelope(entityConstructor, body);\n\n      // On update the URL is authoritative, so a record cannot be renamed\n      // onto another one by editing its payload.\n      if (verb === 'update') {\n        const params = yield* HttpRouter.params;\n        entity.id = params.id;\n      }\n      if (options.prepare) {\n        entity = yield* options.prepare(entity, { ...context, verb });\n      }\n\n      const saved = yield* saveUCFactory<T>().pipe(\n        Effect.provideService(EntityRepositoryTag, yield* repository(context)),\n        Effect.provideService(EntityTag, entity),\n      );\n      return yield* HttpServerResponse.json(\n        makeEntityEnvelope(entityConstructor, saved, links.record(saved.id)),\n      );\n    }).pipe(\n      Effect.catch(error =>\n        invalid(error, 'invalid request body', 'invalidBody'),\n      ),\n    );\n\n  /**\n   * Answers with an envelope rather than a bare `204`: every message between\n   * entifix artifacts is one, and the fetch client parses every response as\n   * JSON.\n   */\n  const remove = (context: EntityRouteContext) =>\n    Effect.gen(function* () {\n      const params = yield* HttpRouter.params;\n      yield* deleteUCFactory<T>().pipe(\n        Effect.provideService(EntityRepositoryTag, yield* repository(context)),\n        Effect.provideService(EntityIdTag, params.id),\n      );\n      return yield* HttpServerResponse.json({\n        meta: { type: 'entity', entity: key, links: links.collection() },\n        data: { id: params.id },\n      });\n    }).pipe(Effect.catch(routeFailure));\n\n  const generic = (verb: EntityVerb, context: EntityRouteContext) => {\n    switch (verb) {\n      case 'list':\n        return list(context);\n      case 'get':\n        return get(context);\n      case 'create':\n        return save('create')(context);\n      case 'update':\n        return save('update')(context);\n      case 'delete':\n        return remove(context);\n    }\n  };\n\n  /**\n   * Each guard asks for different services, so the branches do not unify on\n   * their own; the cast states the union every guard this set can reach\n   * actually needs.\n   */\n  const handlerFor = (verb: EntityVerb) =>\n    guarded(verb, context => {\n      const override = options.override?.[verb];\n      return override ? override(context, links) : generic(verb, context);\n    }) as Effect.Effect<\n      HttpServerResponse.HttpServerResponse,\n      unknown,\n      | R\n      | EntityRepositoryFactoryTag\n      | GuardServices<G>\n      | HttpServerRequest.HttpServerRequest\n      | HttpRouter.RouteContext\n    >;\n\n  const ROUTES: Record<\n    EntityVerb,\n    { method: 'GET' | 'POST' | 'PUT' | 'DELETE'; path: `/${string}` }\n  > = {\n    list: { method: 'GET', path: base },\n    get: { method: 'GET', path: `${base}/:id` },\n    create: { method: 'POST', path: base },\n    update: { method: 'PUT', path: `${base}/:id` },\n    delete: { method: 'DELETE', path: `${base}/:id` },\n  };\n\n  return HttpRouter.addAll([\n    // A literal, so it wins over `/:id` regardless of order.\n    HttpRouter.route(\n      'GET',\n      `${base}/$metadata`,\n      entityMetadataRoute(entityConstructor),\n    ),\n    ...options.verbs.map(verb =>\n      HttpRouter.route(\n        ROUTES[verb].method,\n        ROUTES[verb].path,\n        handlerFor(verb),\n      ),\n    ),\n  ]);\n};\n"],"names":["permissionForEntity","deleteUCFactory","EntityIdTag","EntityLoadRequestTag","EntityRepositoryFactoryTag","EntityRepositoryTag","EntityTag","getUCFactory","loadUCFactory","saveUCFactory","EntifixBuildError","envelopeEntityName","extractMetaEntity","makeEntityEnvelope","makeEntityPageEnvelope","parseLoadRequestParams","readEntityEnvelope","Effect","HttpRouter","HttpServerRequest","HttpServerResponse","requireCrossing","requireOrganization","requirePermission","requireServiceCrossing","entityMetadataRoute","EntityRouteRefusal","status","code","detail","_tag","ACTION","list","get","create","update","delete","READS","Set","routeFailure","error","json","String","invalid","label","refusalCode","message","undefined","makeEntityRoutes","entityConstructor","options","key","base","basePath","mounted","verbs","links","record","id","href","has","rel","method","collection","guardFor","verb","guard","read","write","guarded","use","permission","kind","principal","organizationId","organization","repository","context","gen","factory","for","scopeOf","scope","succeed","readLoadRequest","request","search","URL","url","searchParams","try","catch","notFound","entity","parsed","items","total","filtering","filter","page","pipe","provideService","params","found","option","includes","value","save","body","prepare","saved","remove","meta","type","data","generic","handlerFor","override","ROUTES","path","addAll","route","map"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './auth/index.js';
 export * from './entity-metadata-route.js';
+export * from './entity-routes.js';
 export * from './health-routes.js';
 export * from './redact-configuration.js';
 export * from './service-description-route.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './auth/index.js';
 export * from './entity-metadata-route.js';
+export * from './entity-routes.js';
 export * from './health-routes.js';
 export * from './redact-configuration.js';
 export * from './service-description-route.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './auth/index.js';\nexport * from './entity-metadata-route.js';\nexport * from './health-routes.js';\nexport * from './redact-configuration.js';\nexport * from './service-description-route.js';\nexport * from './sse.js';\n"],"names":[],"mappings":"AAAA,cAAc,kBAAkB;AAChC,cAAc,6BAA6B;AAC3C,cAAc,qBAAqB;AACnC,cAAc,4BAA4B;AAC1C,cAAc,iCAAiC;AAC/C,cAAc,WAAW"}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './auth/index.js';\nexport * from './entity-metadata-route.js';\nexport * from './entity-routes.js';\nexport * from './health-routes.js';\nexport * from './redact-configuration.js';\nexport * from './service-description-route.js';\nexport * from './sse.js';\n"],"names":[],"mappings":"AAAA,cAAc,kBAAkB;AAChC,cAAc,6BAA6B;AAC3C,cAAc,qBAAqB;AACnC,cAAc,qBAAqB;AACnC,cAAc,4BAA4B;AAC1C,cAAc,iCAAiC;AAC/C,cAAc,WAAW"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entifix/service-shell",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Effect HTTP service skeleton: server layer, health and metadata routes, permission guards, remote configuration and OpenTelemetry.",
   "license": "MIT",
   "repository": {
@@ -66,10 +66,10 @@
   },
   "dependencies": {
     "@swc/helpers": "0.5.23",
-    "@entifix/business": "0.7.1",
-    "@entifix/tooling": "0.7.1",
-    "@entifix/authz": "0.7.1",
-    "@entifix/core": "0.7.1"
+    "@entifix/authz": "0.7.2",
+    "@entifix/core": "0.7.2",
+    "@entifix/business": "0.7.2",
+    "@entifix/tooling": "0.7.2"
   },
   "devDependencies": {
     "@effect/opentelemetry": "4.0.5",
@@ -81,7 +81,7 @@
     "@opentelemetry/sdk-metrics": "2.12.0",
     "@opentelemetry/sdk-trace-base": "2.12.0",
     "effect": "4.0.5",
-    "@entifix/testing-unit": "0.7.1"
+    "@entifix/testing-unit": "0.7.2"
   },
   "peerDependencies": {
     "@effect/opentelemetry": "^4.0.5",