@emkodev/emkore 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -8,6 +8,23 @@ and this project adheres to
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-04-08
+
+### Added
+
+- **`LlmStringParameter` extensions**: Added optional `enum?: readonly string[]`, `format?: string`, `default?: string` fields. These let LLM tool descriptions carry enum constraints (allowed values), format hints (e.g. `"date-time"`, `"uuid"`), and default values — closing the largest gap in MCP tool-call quality for typical CRUD usecases.
+- **`LlmNumberParameter` extensions**: Added optional `minimum?: number`, `maximum?: number`, `default?: number` fields for numeric parameter constraints.
+- **`LlmBooleanParameter` extensions**: Added optional `default?: boolean`.
+- **`LlmArrayParameter.items` extensions**: The `items` descriptor now carries optional `format?`, `enum?`, and `properties?` fields, so arrays of dates, enums, or nested objects can be described accurately to LLMs.
+- **`LlmStringReturnValue` / `LlmNumberReturnValue`**: Added the same optional `enum`/`format` (string) and `minimum`/`maximum` (number) fields on the return-value variants for symmetry with parameters.
+- **`apiDefinitionToJsonSchema()` forwarding**: The converter now copies all the new optional fields through to the JSON Schema output, so consumers that read the projected JSON Schema get the full information.
+
+### Notes
+
+All additions are purely additive optional fields. Existing `ApiDefinition` literals continue to type-check and behave identically. The discriminated-union narrowing on `LlmParameter.type` is preserved — adding optional fields to individual member interfaces does not affect narrowing.
+
+This release pairs with the LLM-side `apiDefinition` generation work in `@emkode/cli` 0.7.0 and the field-forwarding logic in `@emkodev/emkoord`.
+
 ## [1.0.3] - 2026-01-20
 
 ### Added

package/docs/permission.md

@@ -0,0 +1,325 @@
+# Permissions
+
+## Design philosophy
+
+Every permission is explicit. If an actor has access, it is because someone
+created a `Permission` object that says so. There are no wildcards, no deny
+rules, no implicit inheritance, no role abstractions. This is deliberate:
+
+- **No `*` wildcards.** A grant covers exactly what it names. You cannot grant
+  `{ resource: "*" }` to cover all resources. If an actor needs access to five
+  resources, they get five grants.
+- **No deny rules.** The model is allow-only. Access is the union of what is
+  explicitly granted — never subtracted.
+- **No implicit inheritance.** A grant on one resource does not imply access to
+  related resources. A grant with a broad scope does not bypass non-scope
+  constraints.
+- **No roles.** Consumers map roles to permissions externally. Emkore only sees
+  flat permission arrays.
+- **No authentication.** The system does not distinguish "authenticated" from
+  "guest." It only sees actors and their grants. A guest is an actor with
+  grants — possibly none, possibly explicit grants for public resources.
+  Authentication is an external concern.
+
+The cost is verbosity. The benefit is that every access decision is traceable to
+a specific grant with no ambiguity.
+
+## Permission structure
+
+```ts
+interface Permission {
+  readonly resource: string; // e.g. "invoice", "document"
+  readonly action: string; // e.g. "create", "retrieve", "update"
+  readonly constraints?: ResourceConstraints;
+}
+```
+
+A permission is a `resource + action` pair with optional `ResourceConstraints`.
+
+## ResourceConstraints
+
+```ts
+interface ResourceConstraints {
+  scope?: ResourceScope;
+  statuses?: string[];
+  timeRestriction?: { from: Date; to: Date };
+  businessId?: string;
+  teamId?: string;
+  projectId?: string;
+  resourceId?: string;
+}
+```
+
+Every field is optional. Constraints narrow when and where a permission applies.
+
+## ResourceScope
+
+```
+BUSINESS ────── tenant-wide (the ceiling)
+├─ PROJECT ──>  OWNED
+└─ TEAM    ──>  OWNED
+```
+
+`BUSINESS` is the largest organizational scope — it covers the entire tenant.
+`PROJECT` and `TEAM` are parallel siblings under it — neither satisfies the
+other. `OWNED` is the smallest meaningful scope — the baseline that comes with
+any grant. Whatever scope you have, you can access your own resources.
+
+The scope hierarchy determines **how much beyond your own resources** you can
+see:
+
+- `OWNED` — only your resources
+- `TEAM` — your team's resources (and your own)
+- `PROJECT` — your project's resources (and your own)
+- `BUSINESS` — everything in the tenant (and your own, trivially)
+
+### ALL scope
+
+`ALL` sits above `BUSINESS` as a god-mode scope. On the grant side, it
+satisfies every scope requirement. On the requirement side, only `ALL` grants
+satisfy it — making it the most restrictive requirement.
+
+`ALL` exists for consumers who need a scope tier above the tenant. If a consumer
+does not use it, it is invisible — no grants are issued, no usecases require
+it, and it has no effect.
+
+`BUSINESS` is the broadest organizational scope for normal use. `ALL` is
+opt-in for exceptional cases.
+
+### Scope satisfaction
+
+A grant's scope satisfies a requirement's scope if it is equal to or above it
+in the hierarchy:
+
+| Grant \ Requirement | ALL | BUSINESS | PROJECT | TEAM | OWNED |
+| ------------------- | --- | -------- | ------- | ---- | ----- |
+| ALL                 | Y   | Y        | Y       | Y    | Y     |
+| BUSINESS            |     | Y        | Y       | Y    | Y     |
+| PROJECT             |     |          | Y       |      | Y     |
+| TEAM                |     |          |         | Y    | Y     |
+| OWNED               |     |          |         |      | Y     |
+
+## How constraint matching works
+
+All constraints follow the same pattern: **the grant defines what the actor can
+do, the requirement defines what the usecase needs, the interceptor checks if
+the grant covers the requirement.**
+
+- Scope: grant must satisfy requirement (hierarchy).
+- Statuses: grant must be a superset of requirement.
+- Time: grant window must cover requirement window.
+- IDs: grant must match requirement (exact).
+
+When an actor has multiple grants for the same `resource + action`, each grant
+is checked independently. If any single grant satisfies all required
+constraints, the actor passes.
+
+### Rules
+
+1. If the usecase requires **no constraints**, any grant with a matching
+   `resource + action` passes — regardless of what constraints the grant
+   carries.
+
+2. If the usecase requires constraints but the grant has **none**,
+   authorization fails.
+
+3. Each required constraint is checked independently. All must pass (AND logic).
+
+4. **Grant-side constraints that the usecase does not require are ignored.**
+   This applies to all constraints except `timeRestriction` — see below.
+
+### Rule 4 in practice
+
+If an actor's grant has `{ scope: ResourceScope.BUSINESS, teamId: "sales" }`,
+the `teamId: "sales"` is only enforced when a usecase explicitly requires a
+`teamId`. A usecase that only requires `{ scope: ResourceScope.TEAM }` will not
+check the `teamId` — the actor passes.
+
+Grant-side constraints are **not hard limits on the actor**. They are data the
+actor carries. They are enforced only when a usecase asks for them. If you need
+a constraint to always be enforced, every relevant usecase must include it in
+its `requiredPermissions`.
+
+### timeRestriction
+
+`timeRestriction` is the exception to rule 4. A grant's time window is always
+enforced against the current time, regardless of whether the usecase requires a
+time restriction. If the actor's grant has a `timeRestriction` and `now` falls
+outside that window, the permission is invalid.
+
+When both the grant and the requirement have a `timeRestriction`, both windows
+are checked against `now`. The effective window is their intersection. This
+covers:
+
+- **Temporary access** — grant the actor a time window. No usecase changes
+  needed. The contractor's grant expires on its own.
+- **Subscription expiration** — the grant's time window represents the
+  subscription period.
+- **Narrowed operational windows** — if the usecase restricts its availability
+  to certain hours and the grant restricts the actor to different hours, both
+  are enforced.
+
+> Note: this is the intended behavior. The current implementation does not yet
+> enforce grant-side `timeRestriction` independently — it only checks when the
+> requirement also has one. This is a known issue to be fixed.
+
+### Constraint-by-constraint behavior
+
+| Constraint        | Comparison                                                                       |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `scope`           | Hierarchical: granted scope must satisfy the required scope per the scope table.  |
+| `statuses`        | Set containment: granted statuses must be a superset of required statuses.        |
+| `timeRestriction` | Grant window and requirement window both checked against `now`.                   |
+| `businessId`      | Exact match.                                                                      |
+| `teamId`          | Exact match.                                                                      |
+| `projectId`       | Exact match.                                                                      |
+| `resourceId`      | Exact match.                                                                      |
+
+## Public access
+
+"Public" is not a system concept. It is the result of granting a guest actor
+explicit permissions for specific resources and actions.
+
+A guest actor with `{ resource: "article", action: "retrieve" }` can retrieve
+articles. The same usecase, same interceptor, same authorization path as any
+other actor. What makes it "public" is that the guest was given the grant.
+
+Usecases with empty `requiredPermissions` skip the interceptor entirely. This
+means no authorization runs at all — use this for operations that genuinely need
+no access control (health checks, internal tools), not for public access.
+
+## Recipes
+
+### 1. "Can this user edit this specific resource?"
+
+The usecase requires `resourceId` so the interceptor verifies the actor has
+access to that exact entity. `resourceId` is an exact match — no pattern or
+prefix matching.
+
+```ts
+// Usecase requires:
+{ resource: "document", action: "update",
+  constraints: { scope: ResourceScope.TEAM, resourceId: "doc-42" } }
+
+// Actor grant — access to one specific document
+{ resource: "document", action: "update",
+  constraints: { scope: ResourceScope.TEAM, resourceId: "doc-42" } }
+```
+
+The actor can only update `doc-42`. Any other `resourceId` requirement fails.
+
+### 2. "Can this user see everything in their team?"
+
+The usecase requires `TEAM` scope and a `teamId`. The actor's grant must match
+both.
+
+```ts
+// Usecase requires:
+{ resource: "ticket", action: "list",
+  constraints: { scope: ResourceScope.TEAM, teamId: "engineering" } }
+
+// Actor grant
+{ resource: "ticket", action: "list",
+  constraints: { scope: ResourceScope.TEAM, teamId: "engineering" } }
+```
+
+A `BUSINESS`-scoped grant with `teamId: "engineering"` also passes (BUSINESS
+satisfies TEAM). A grant with `teamId: "sales"` fails.
+
+### 3. "Can this user only modify draft resources?"
+
+The usecase requires certain statuses; the actor's grant must cover all of them.
+
+```ts
+// Usecase requires:
+{ resource: "invoice", action: "update",
+  constraints: { statuses: ["draft"] } }
+
+// Actor grant — can update drafts and pending invoices
+{ resource: "invoice", action: "update",
+  constraints: { statuses: ["draft", "pending"] } }
+```
+
+Passes because the granted statuses are a superset of the required statuses. An
+actor with only `statuses: ["pending"]` would fail — `"draft"` is not covered.
+
+### 4. "How do I make something publicly accessible?"
+
+Give the guest actor explicit grants for the resources and actions that should
+be public. The guest goes through the same authorization path as everyone else.
+
+```ts
+// Guest actor grants
+{ resource: "article", action: "retrieve" }
+{ resource: "product", action: "list" }
+
+// Usecase — same as for any other actor
+override get requiredPermissions(): Permission[] {
+  return [{
+    resource: "article",
+    action: "retrieve",
+    constraints: { scope: ResourceScope.OWNED },
+  }];
+}
+```
+
+The guest's grant matches the resource and action. The scope on the requirement
+is `OWNED` — the smallest scope, satisfied by any grant. The interceptor passes.
+
+What is "public" is determined entirely by which grants the guest actor
+carries — not by the usecase, not by a special scope, not by empty
+requirements.
+
+### 5. "Can this user only act during a specific time window?"
+
+Put a `timeRestriction` on the grant. No usecase changes needed.
+
+```ts
+// Actor grant — temporary contractor access, March 16 only, 10am to 2pm
+{ resource: "report", action: "retrieve",
+  constraints: {
+    scope: ResourceScope.TEAM,
+    teamId: "engineering",
+    timeRestriction: { from: new Date("2026-03-16T10:00"), to: new Date("2026-03-16T14:00") },
+  } }
+```
+
+The interceptor checks `now` against the grant's time window. Outside the
+window, the grant is invalid. The usecase does not need to know about the time
+restriction.
+
+## Grant-side constraints as metadata
+
+Grant-side constraints serve a secondary purpose beyond authorization: they
+carry data that usecases and repositories can use at runtime.
+
+`Actor.getTeamIds()` extracts all unique `teamId` values from the actor's
+permission constraints. This is useful for filtering queries — e.g. a
+repository can use the actor's team IDs to scope a database query without the
+interceptor needing to understand the query.
+
+The `OWNED` scope implies a runtime filter: the usecase or repository should
+return only records owned by the actor. This avoids the need for individual
+`resourceId` grants for every record the actor owns.
+
+## What the permissions model does not do
+
+- **No wildcard matching.** You cannot grant `{ resource: "*" }` to cover all
+  resources. Every grant names exactly what it covers.
+- **No deny rules.** The model is allow-only. You cannot deny a permission to
+  override a broader grant.
+- **No roles.** There is no built-in role abstraction. Consumers manage
+  role-to-permission mapping externally.
+- **No authentication.** The system does not know about authentication. It sees
+  actors and grants. A "guest" is an actor with explicit grants for public
+  resources.
+- **No dynamic/contextual checks.** Constraints are static on the permission
+  object. There is no hook to evaluate permissions based on the resource's
+  runtime state. The exception is `OWNED` scope, which implies the usecase or
+  repository should filter by the actor's identity.
+- **No field-level access control.** Permissions operate at the resource level.
+- **No permission delegation.** An actor cannot grant a subset of its
+  permissions to another actor.
+- **No custom scope levels.** The scope hierarchy is fixed.
+- **No built-in persistence.** Emkore provides the model and enforcement.
+  Consumers decide how to store and load permissions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emkodev/emkore",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "A TypeScript foundation framework for building robust, type-safe business applications with clean architecture patterns",
   "license": "MIT",
   "author": "emko.dev",

package/src/common/llm/api-definition.type.ts

@@ -13,14 +13,21 @@ interface LlmBaseParameter {
 // Primitive type parameters
 interface LlmStringParameter extends LlmBaseParameter {
   readonly type: "string";
+  readonly enum?: readonly string[];
+  readonly format?: string;
+  readonly default?: string;
 }
 
 interface LlmNumberParameter extends LlmBaseParameter {
   readonly type: "number" | "integer";
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly default?: number;
 }
 
 interface LlmBooleanParameter extends LlmBaseParameter {
   readonly type: "boolean";
+  readonly default?: boolean;
 }
 
 interface LlmNullParameter extends LlmBaseParameter {
@@ -33,6 +40,8 @@ interface LlmArrayParameter extends LlmBaseParameter {
   readonly items: {
     readonly type: string;
     readonly description?: string;
+    readonly format?: string;
+    readonly enum?: readonly string[];
     readonly properties?: JsonSchema;
   };
 }
@@ -60,10 +69,14 @@ interface LlmBaseReturnValue {
 // Primitive type returns
 interface LlmStringReturnValue extends LlmBaseReturnValue {
   readonly type: "string";
+  readonly enum?: readonly string[];
+  readonly format?: string;
 }
 
 interface LlmNumberReturnValue extends LlmBaseReturnValue {
   readonly type: "number" | "integer";
+  readonly minimum?: number;
+  readonly maximum?: number;
 }
 
 interface LlmBooleanReturnValue extends LlmBaseReturnValue {
@@ -80,7 +93,10 @@ interface LlmArrayReturnValue extends LlmBaseReturnValue {
   readonly items: {
     readonly type: string;
     readonly description?: string;
+    readonly format?: string;
+    readonly enum?: readonly string[];
     readonly properties?: JsonSchema;
+    readonly required?: readonly string[];
   };
 }
 
@@ -118,6 +134,42 @@ export function apiDefinitionToJsonSchema(
       description: param.description,
     };
 
+    // String-typed parameter extras
+    if (param.type === "string") {
+      const stringParam = param as LlmStringParameter;
+      if (stringParam.enum) {
+        paramSchema.enum = [...stringParam.enum];
+      }
+      if (stringParam.format !== undefined) {
+        paramSchema.format = stringParam.format;
+      }
+      if (stringParam.default !== undefined) {
+        paramSchema.default = stringParam.default;
+      }
+    }
+
+    // Number/integer-typed parameter extras
+    if (param.type === "number" || param.type === "integer") {
+      const numberParam = param as LlmNumberParameter;
+      if (numberParam.minimum !== undefined) {
+        paramSchema.minimum = numberParam.minimum;
+      }
+      if (numberParam.maximum !== undefined) {
+        paramSchema.maximum = numberParam.maximum;
+      }
+      if (numberParam.default !== undefined) {
+        paramSchema.default = numberParam.default;
+      }
+    }
+
+    // Boolean-typed parameter extras
+    if (param.type === "boolean") {
+      const booleanParam = param as LlmBooleanParameter;
+      if (booleanParam.default !== undefined) {
+        paramSchema.default = booleanParam.default;
+      }
+    }
+
     // Add items for array types (JSON Schema 2020-12 compliance)
     if (param.type === "array" && "items" in param) {
       const arrayParam = param as LlmArrayParameter;
@@ -150,6 +202,30 @@ export function apiDefinitionToJsonSchema(
     description: definition.returns.description,
   };
 
+  // String-typed return extras
+  if (definition.returns.type === "string") {
+    const stringReturn = definition.returns as LlmStringReturnValue;
+    if (stringReturn.enum) {
+      returnsSchema.enum = [...stringReturn.enum];
+    }
+    if (stringReturn.format !== undefined) {
+      returnsSchema.format = stringReturn.format;
+    }
+  }
+
+  // Number/integer-typed return extras
+  if (
+    definition.returns.type === "number" || definition.returns.type === "integer"
+  ) {
+    const numberReturn = definition.returns as LlmNumberReturnValue;
+    if (numberReturn.minimum !== undefined) {
+      returnsSchema.minimum = numberReturn.minimum;
+    }
+    if (numberReturn.maximum !== undefined) {
+      returnsSchema.maximum = numberReturn.maximum;
+    }
+  }
+
   // Add items for array return types (JSON Schema 2020-12 compliance)
   if (definition.returns.type === "array" && "items" in definition.returns) {
     const arrayReturn = definition.returns as LlmArrayReturnValue;