unitysvc-core 0.2.36__tar.gz → 0.2.37__tar.gz

{unitysvc_core-0.2.36/src/unitysvc_core.egg-info → unitysvc_core-0.2.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.36
+Version: 0.2.37
 Summary: Shared data models and validation helpers for UnitySVC packages
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>
@@ -190,9 +190,10 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
 }
 ```
 
-- `invoke` is always exported and covers every route; it may not be redeclared. A service that declares nothing (most of them) exports `invoke` only, with no options, which `service:<name>` or `service:*` covers.
-- `permissions`: a name → the routes it covers, each `"<METHOD> /<path>"` (`*` for any method, `*` globs in the path). Permissions are never inferred from HTTP methods.
-- `options`: a JSON Schema (draft 7) object of the query arguments the service accepts as customizations, like an enrollment's `user_parameters_schema`, with an optional react-jsonschema-form `options_ui_schema`; the frontend renders it with the same form component. It covers limits only the service can apply (a message size). Restrictions so every value is one query argument: property names are lowercase letters, digits and `_`; each property is a `string`, `integer`, `number`, `boolean` or an `array` of strings, serialized as an OpenAPI form-style query parameter with arrays comma-joined (`style: form, explode: false`); options are optional (no `required`) and only declared properties are accepted; the schema is self-contained (no `$ref`), so validating against it never fetches anything. A property's `default` is what the service does when the option is not sent.
+- **Without `permissions`** (most services, including one that declares only `options`), the service exports one permission, `invoke`, on every route (`"* /*"`); `service:<name>` and the `service:*` wildcard grant it.
+- **With `permissions`**, the service exports exactly those, and `invoke` only if it declares it too. A data service (`me`, `log`, `needs`) declares `read` / `write` and no `invoke`: it holds the customer's own data, so only a grant that names its permissions reaches it, never `invoke` or a wildcard.
+- `permissions`: a name (lowercase letters, digits and `_`) → the routes it covers, each `"<METHOD> /<path>"` (`*` for any method, `*` globs in the path). Permissions are never inferred from HTTP methods.
+- `options`: a JSON Schema (draft 7) object of the customizations a grant may set on the service, like an enrollment's `user_parameters_schema`, with an optional react-jsonschema-form `options_ui_schema`; the frontend renders it with the same form component. It covers limits only the service can apply (a message size). Restrictions so a grant can write every value in query-string syntax: property names are lowercase letters, digits and `_`; each property is a `string`, `integer`, `number`, `boolean` or an `array` of strings, serialized as an OpenAPI form-style query parameter with arrays comma-joined (`style: form, explode: false`); options are optional (no `required`) and only declared properties are accepted; the schema is self-contained (no `$ref`), so validating against it never fetches anything. A property's `default` is what the service does when the policy does not set the option.
 
 **2. A customer access request (`upstream_access_config.<channel>.customer_access_requests`), and the policy entry it becomes.** Any channel may declare its own list; each approved request becomes an entry (a grant) in the issued key's policy, in the same shape:
 
@@ -204,21 +205,47 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
 ```
 
 - `object` names one service (`service:<name>`, no wildcards). `enrollment:<CODE>` (one enrollment of an enrollable service) may be allowed later.
-- `options` is a query string (`parse_options`): each name once, each value non-empty; with a catalog, each value is converted to its declared type and validated against the target's `options` schema.
+- `options` is written in query-string syntax (`parse_options`; a notation, not how options are delivered): each name once, each value non-empty; with a catalog, each value is converted to its declared type and validated against the target's `options` schema.
 - **Enrollment is where options and limits are set.** In a request, `options` and `limits` only pre-fill the enrollment form for convenience. When enrolling, the customer confirms and sets the options (a form rendered from the target's `options` schema) and the limits, and adds their own limits; the result is the issued key's policy.
 - `limits` (`validate_limits`): `count_per_hour` / `count_per_day` / `count_per_month` / `count_total` (positive integer) and the same for `amount_` (finite positive decimal, as a number or a string). Limits are universal: the platform meters every call, so any service can be limited without exporting anything. The seller's limits are a pre-fill; the customer sets them at enrollment, and an enrollment's own limits (unitysvc/unitysvc#2687) use the same shape. They are counted per policy entry (the enrollment's calls to that service) from the usage stream (counters keyed by scope, metric and window bucket), and the gateway refuses calls once one is exceeded.
 
-**3. How options reach the service.** No new channel: the upstream URL. When the gateway constructs the target's upstream URL for a call made under a policy entry, it appends that entry's `options` as query arguments, `?log_level=warn&max_size=2000`, the way query arguments already reach every upstream, `log://` included. Rules:
+**3. How options reach the service.** Not through the upstream URL: the gateway never changes a target's `base_url` or query to carry policy. How an option is applied is up to the service's implementation:
 
-- The gateway first strips any query argument the client sent under one of the target's exported option names, then appends the policy's values. Today the client's arguments win on a name collision, so without this a caller could override its own policy.
-- An option the policy does not set is not sent; the service applies its own default. A plain `service:*` key sends none.
-- Enrollment parameters are unchanged and keep working alongside: `{{ params.X }}` still renders into the channel config, including a templated `base_url` query.
-- The platform's own services are terminated in gateway stages before the upstream URI is built, so each stage reads its options from the request's arguments (`log_dispatch` drops entries below `log_level`).
-- SMTP has no query string; options for pure-SMTP delivery are out of scope.
+- **A service implemented in the gateway** (`me`, `log`, `ai`, `notify`, `email`, `bill`) reads the calling key's policy from the routing context and applies the option itself (`me` gives values only for the grant's `profile` paths; `log` would drop entries below a grant's `log_level`).
+- **A proxied service** can only be influenced through its own upstream's interface, so it applies an option only where its configuration maps it into the upstream request in a form that upstream understands, for example a request transformer setting a body field. Until such a mapping exists, options are enforced by gateway-implemented services only.
+- The policy itself never reaches a seller: a seller's upstream sees at most the effect of an option, in its own vocabulary.
+- An option the policy does not set takes the service's `default`. A plain `service:*` key sets none.
+- Enrollment parameters are unchanged and keep working alongside: `{{ params.X }}` still renders into the channel config.
 
 **4. Where exports are published.** In the public catalog bundle: every service row carries its `exports` exactly as declared (`null` when none). `GET /v1/catalog/bundle` returns the bundle's URL; a `service:<name>` is the row whose `name` is `<name>`.
 
-**5. Validating `customer_access_requests`.** `validate_channel_access_requests(upstream_access_config, resolve)` checks every channel's requests. Limits and a default claim (`invoke`, no options) need no lookup. For any other claim, `resolve(name)` returns the target's `exports` from the catalog (`{}` when it declares none) or `None` when no such service is published; core parses it with `parse_exports` and checks the claimed permissions and the options (names, then values against its `options` schema) against it, refusing an unpublished target. Without a resolver only the shape is checked.
+**5. Validating `customer_access_requests`.** `validate_channel_access_requests(upstream_access_config, resolve)` checks every channel's requests. Limits need no lookup. Every claim's permissions and options, `invoke` included (a service that declares permissions may not export it), are looked up: `resolve(name)` returns the target's `exports` from the catalog (`{}` when it declares none) or `None` when no such service is published; core parses it with `parse_exports` and checks the claimed permissions and the options (names, then values against its `options` schema) against it, refusing an unpublished target. Without a resolver only the shape is checked.
 
 - `DataValidator(data_dir, schema_dir, exports_resolver=...)` runs both checks on every `offering_v1` (`exports` and each channel's `customer_access_requests`). The seller SDK passes a resolver that downloads the catalog bundle once and reads the target row's `exports`; offline it passes none and gets the shape checks.
 - Backend ingest calls the same function with a resolver over the published services, so an unknown target, permission or option fails at upload.
+
+### Enrollment parameters on channels
+
+A channel may declare its own enrollment parameters, so each plan of a service asks for what it needs (unitysvc/unitysvc#2726):
+
+```json
+"upstream_access_config": {
+  "plus": {
+    "base_url": "https://u/{{ params.folder }}",
+    "params": {
+      "schema": {"type": "object", "properties": {"folder": {"type": "string"}}, "required": ["folder"]},
+      "ui_schema": {},
+      "testing_defaults": {"folder": "ops"}
+    }
+  }
+}
+```
+
+`params.schema` is a JSON Schema of the parameters (a property's own `default` pre-fills the customer's form), `params.ui_schema` holds form hints, and `params.testing_defaults` holds the values the platform tests the channel with. Once any channel declares `params`:
+
+- a channel reads only the parameters its `params.schema` declares, and a channel that reads `{{ params.* }}` must declare its own `params` (`validate_channel_parameters`, on every `offering_v1`);
+- each required parameter has a value in that channel's `params.testing_defaults`;
+- each required parameter is read by its own channel or by document content; another channel's use does not count (`validate_required_parameter_usage`, which backend ingest also calls);
+- the listing must not also declare `user_parameters_schema`.
+
+When no channel declares `params`, the listing-level `user_parameters_schema` applies to the whole service as before.

{unitysvc_core-0.2.36 → unitysvc_core-0.2.37}/README.md

@@ -155,9 +155,10 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
 }
 ```
 
-- `invoke` is always exported and covers every route; it may not be redeclared. A service that declares nothing (most of them) exports `invoke` only, with no options, which `service:<name>` or `service:*` covers.
-- `permissions`: a name → the routes it covers, each `"<METHOD> /<path>"` (`*` for any method, `*` globs in the path). Permissions are never inferred from HTTP methods.
-- `options`: a JSON Schema (draft 7) object of the query arguments the service accepts as customizations, like an enrollment's `user_parameters_schema`, with an optional react-jsonschema-form `options_ui_schema`; the frontend renders it with the same form component. It covers limits only the service can apply (a message size). Restrictions so every value is one query argument: property names are lowercase letters, digits and `_`; each property is a `string`, `integer`, `number`, `boolean` or an `array` of strings, serialized as an OpenAPI form-style query parameter with arrays comma-joined (`style: form, explode: false`); options are optional (no `required`) and only declared properties are accepted; the schema is self-contained (no `$ref`), so validating against it never fetches anything. A property's `default` is what the service does when the option is not sent.
+- **Without `permissions`** (most services, including one that declares only `options`), the service exports one permission, `invoke`, on every route (`"* /*"`); `service:<name>` and the `service:*` wildcard grant it.
+- **With `permissions`**, the service exports exactly those, and `invoke` only if it declares it too. A data service (`me`, `log`, `needs`) declares `read` / `write` and no `invoke`: it holds the customer's own data, so only a grant that names its permissions reaches it, never `invoke` or a wildcard.
+- `permissions`: a name (lowercase letters, digits and `_`) → the routes it covers, each `"<METHOD> /<path>"` (`*` for any method, `*` globs in the path). Permissions are never inferred from HTTP methods.
+- `options`: a JSON Schema (draft 7) object of the customizations a grant may set on the service, like an enrollment's `user_parameters_schema`, with an optional react-jsonschema-form `options_ui_schema`; the frontend renders it with the same form component. It covers limits only the service can apply (a message size). Restrictions so a grant can write every value in query-string syntax: property names are lowercase letters, digits and `_`; each property is a `string`, `integer`, `number`, `boolean` or an `array` of strings, serialized as an OpenAPI form-style query parameter with arrays comma-joined (`style: form, explode: false`); options are optional (no `required`) and only declared properties are accepted; the schema is self-contained (no `$ref`), so validating against it never fetches anything. A property's `default` is what the service does when the policy does not set the option.
 
 **2. A customer access request (`upstream_access_config.<channel>.customer_access_requests`), and the policy entry it becomes.** Any channel may declare its own list; each approved request becomes an entry (a grant) in the issued key's policy, in the same shape:
 
@@ -169,21 +170,47 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
 ```
 
 - `object` names one service (`service:<name>`, no wildcards). `enrollment:<CODE>` (one enrollment of an enrollable service) may be allowed later.
-- `options` is a query string (`parse_options`): each name once, each value non-empty; with a catalog, each value is converted to its declared type and validated against the target's `options` schema.
+- `options` is written in query-string syntax (`parse_options`; a notation, not how options are delivered): each name once, each value non-empty; with a catalog, each value is converted to its declared type and validated against the target's `options` schema.
 - **Enrollment is where options and limits are set.** In a request, `options` and `limits` only pre-fill the enrollment form for convenience. When enrolling, the customer confirms and sets the options (a form rendered from the target's `options` schema) and the limits, and adds their own limits; the result is the issued key's policy.
 - `limits` (`validate_limits`): `count_per_hour` / `count_per_day` / `count_per_month` / `count_total` (positive integer) and the same for `amount_` (finite positive decimal, as a number or a string). Limits are universal: the platform meters every call, so any service can be limited without exporting anything. The seller's limits are a pre-fill; the customer sets them at enrollment, and an enrollment's own limits (unitysvc/unitysvc#2687) use the same shape. They are counted per policy entry (the enrollment's calls to that service) from the usage stream (counters keyed by scope, metric and window bucket), and the gateway refuses calls once one is exceeded.
 
-**3. How options reach the service.** No new channel: the upstream URL. When the gateway constructs the target's upstream URL for a call made under a policy entry, it appends that entry's `options` as query arguments, `?log_level=warn&max_size=2000`, the way query arguments already reach every upstream, `log://` included. Rules:
+**3. How options reach the service.** Not through the upstream URL: the gateway never changes a target's `base_url` or query to carry policy. How an option is applied is up to the service's implementation:
 
-- The gateway first strips any query argument the client sent under one of the target's exported option names, then appends the policy's values. Today the client's arguments win on a name collision, so without this a caller could override its own policy.
-- An option the policy does not set is not sent; the service applies its own default. A plain `service:*` key sends none.
-- Enrollment parameters are unchanged and keep working alongside: `{{ params.X }}` still renders into the channel config, including a templated `base_url` query.
-- The platform's own services are terminated in gateway stages before the upstream URI is built, so each stage reads its options from the request's arguments (`log_dispatch` drops entries below `log_level`).
-- SMTP has no query string; options for pure-SMTP delivery are out of scope.
+- **A service implemented in the gateway** (`me`, `log`, `ai`, `notify`, `email`, `bill`) reads the calling key's policy from the routing context and applies the option itself (`me` gives values only for the grant's `profile` paths; `log` would drop entries below a grant's `log_level`).
+- **A proxied service** can only be influenced through its own upstream's interface, so it applies an option only where its configuration maps it into the upstream request in a form that upstream understands, for example a request transformer setting a body field. Until such a mapping exists, options are enforced by gateway-implemented services only.
+- The policy itself never reaches a seller: a seller's upstream sees at most the effect of an option, in its own vocabulary.
+- An option the policy does not set takes the service's `default`. A plain `service:*` key sets none.
+- Enrollment parameters are unchanged and keep working alongside: `{{ params.X }}` still renders into the channel config.
 
 **4. Where exports are published.** In the public catalog bundle: every service row carries its `exports` exactly as declared (`null` when none). `GET /v1/catalog/bundle` returns the bundle's URL; a `service:<name>` is the row whose `name` is `<name>`.
 
-**5. Validating `customer_access_requests`.** `validate_channel_access_requests(upstream_access_config, resolve)` checks every channel's requests. Limits and a default claim (`invoke`, no options) need no lookup. For any other claim, `resolve(name)` returns the target's `exports` from the catalog (`{}` when it declares none) or `None` when no such service is published; core parses it with `parse_exports` and checks the claimed permissions and the options (names, then values against its `options` schema) against it, refusing an unpublished target. Without a resolver only the shape is checked.
+**5. Validating `customer_access_requests`.** `validate_channel_access_requests(upstream_access_config, resolve)` checks every channel's requests. Limits need no lookup. Every claim's permissions and options, `invoke` included (a service that declares permissions may not export it), are looked up: `resolve(name)` returns the target's `exports` from the catalog (`{}` when it declares none) or `None` when no such service is published; core parses it with `parse_exports` and checks the claimed permissions and the options (names, then values against its `options` schema) against it, refusing an unpublished target. Without a resolver only the shape is checked.
 
 - `DataValidator(data_dir, schema_dir, exports_resolver=...)` runs both checks on every `offering_v1` (`exports` and each channel's `customer_access_requests`). The seller SDK passes a resolver that downloads the catalog bundle once and reads the target row's `exports`; offline it passes none and gets the shape checks.
 - Backend ingest calls the same function with a resolver over the published services, so an unknown target, permission or option fails at upload.
+
+### Enrollment parameters on channels
+
+A channel may declare its own enrollment parameters, so each plan of a service asks for what it needs (unitysvc/unitysvc#2726):
+
+```json
+"upstream_access_config": {
+  "plus": {
+    "base_url": "https://u/{{ params.folder }}",
+    "params": {
+      "schema": {"type": "object", "properties": {"folder": {"type": "string"}}, "required": ["folder"]},
+      "ui_schema": {},
+      "testing_defaults": {"folder": "ops"}
+    }
+  }
+}
+```
+
+`params.schema` is a JSON Schema of the parameters (a property's own `default` pre-fills the customer's form), `params.ui_schema` holds form hints, and `params.testing_defaults` holds the values the platform tests the channel with. Once any channel declares `params`:
+
+- a channel reads only the parameters its `params.schema` declares, and a channel that reads `{{ params.* }}` must declare its own `params` (`validate_channel_parameters`, on every `offering_v1`);
+- each required parameter has a value in that channel's `params.testing_defaults`;
+- each required parameter is read by its own channel or by document content; another channel's use does not count (`validate_required_parameter_usage`, which backend ingest also calls);
+- the listing must not also declare `user_parameters_schema`.
+
+When no channel declares `params`, the listing-level `user_parameters_schema` applies to the whole service as before.

{unitysvc_core-0.2.36 → unitysvc_core-0.2.37}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unitysvc-core"
-version = "0.2.36"
+version = "0.2.37"
 description = "Shared data models and validation helpers for UnitySVC packages"
 readme = "README.md"
 authors = [{ name = "Bo Peng", email = "bo.peng@unitysvc.com" }]

{unitysvc_core-0.2.36 → unitysvc_core-0.2.37}/src/unitysvc_core/grants.py

@@ -12,17 +12,24 @@ Three stages (unitysvc/unitysvc#2720):
           "max_size": {"type": "integer", "minimum": 1}}}
       }
 
-  ``invoke`` is always exported and covers every route. A service that
-  declares nothing exports just that: ``invoke``, no options, which
-  ``service:<name>`` or ``service:*`` already covers. Permissions name the
-  routes they cover; they are never inferred from HTTP methods
+  A service that declares no ``permissions`` has one implicit permission,
+  ``invoke``, covering every route (``"* /*"``); that is what
+  ``service:<name>`` and the ``service:*`` wildcard grant. A service that
+  declares ``permissions`` has exactly those, each covering the routes it
+  lists, and ``invoke`` only if it declares it too. A data service (``me``,
+  ``log``, ``needs``) therefore declares ``read`` / ``write`` and no
+  ``invoke``: holding the customer's own data, it is reached only by a grant
+  that names its permissions, never by ``invoke`` or a wildcard. Permissions
+  name the routes they cover; they are never inferred from HTTP methods
   (``POST /chat/completions`` modifies nothing). ``options`` is a JSON Schema,
   like an enrollment's ``user_parameters_schema`` (with an optional
-  ``options_ui_schema``), of the query arguments the service accepts as
-  customizations, including limits only it can apply (a message size); a
-  property's ``default`` is what the service does when the option is not sent.
-  Each property is a string, integer, number, boolean or array of strings,
-  serialized as an OpenAPI form-style query parameter (arrays comma-joined).
+  ``options_ui_schema``), of the customizations a grant may set on the
+  service, including limits only it can apply (a message size); a property's
+  ``default`` is what the service does when the policy does not set the
+  option. Each property is a string, integer, number, boolean or array of
+  strings, so a grant can write its options in query-string syntax
+  (``"log_level=warn"``, arrays comma-joined). That is only how a grant stores
+  them, not how they reach the service (below).
 
 * **Customer access requests** — what a seller asks the enrolling customer to
   approve: to use other services through that customer's account and
@@ -48,11 +55,18 @@ customer's delegated identity, within the approved permissions, options and
 limits. Looking up a target's ``exports`` validates a request's *capabilities*;
 customer consent and key issuance establish its *authority*.
 
-* **Options travel as a query string.** When the gateway constructs the target's
-  upstream URL, it appends the policy entry's ``options`` (``?log_level=warn``),
-  so they reach any upstream, ``log://`` included, the way query arguments
-  already do. An option the policy does not set is left to the service's own
-  default.
+* **The service applies its options; the upstream URL is never the channel.**
+  The gateway does not change a target's upstream URL (its ``base_url`` or
+  query) to carry policy. A service implemented in the gateway (``me``,
+  ``log``, ``ai``, ``notify``, ``email``, ``bill``) reads the calling key's
+  policy from the routing context and applies the option itself. A proxied
+  service can only be influenced through its own upstream's interface, so it
+  applies an option only where its configuration maps it into the upstream
+  request in a form that upstream understands (for example a request
+  transformer setting a body field); until such a mapping exists, options are
+  enforced by gateway-implemented services only. Either way the policy itself
+  never reaches a seller. An option the policy does not set takes the
+  service's ``default``.
 
 * **Limits are universal**: the platform meters every call, so any service can
   be limited by ``count`` or ``amount`` per hour, day or month, or in total,
@@ -61,12 +75,13 @@ customer consent and key issuance establish its *authority*.
 Today a request's ``object`` is ``service:<name>``; ``enrollment:<CODE>`` (one
 enrollment of an enrollable service) may follow.
 
-There is no central list of services. Core does no I/O: a request that claims
-more than the default (a permission other than ``invoke``, or any option) is
-checked against its target's ``exports`` when the caller passes an
-:data:`ExportsResolver` that looks the target up in the published catalog
-bundle, where every service row carries its ``exports``. Limits need no lookup.
-Without a resolver, only the shape of each entry is checked.
+There is no central list of services. Core does no I/O: every request's
+permissions and options are checked against its target's ``exports`` when the
+caller passes an :data:`ExportsResolver` that looks the target up in the
+published catalog bundle, where every service row carries its ``exports``. An
+``invoke`` claim is looked up too, since a service that declares permissions
+may not export ``invoke``. Limits need no lookup. Without a resolver, only the
+shape of each entry is checked.
 """
 
 from __future__ import annotations
@@ -94,8 +109,10 @@ ExportsResolver = Callable[[str], dict[str, Any] | None]
 or ``None`` when the catalog has no such service."""
 
 _ROUTE = re.compile(r"^(\*|GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS) /\S*$")
-# An option is a query argument, so its name stays plain.
+# A grant writes its options in query-string syntax, so an option's name stays
+# plain; so does a permission's.
 _OPTION_NAME = re.compile(r"^[a-z][a-z0-9_]*$")
+_PERMISSION_NAME = _OPTION_NAME
 # ``count_per_day``, ``amount_per_month``, ``count_total`` ...
 _LIMIT = re.compile(r"^(count|amount)_(per_hour|per_day|per_month|total)$")
 
@@ -114,14 +131,17 @@ class Exports:
 
     @property
     def permission_names(self) -> tuple[str, ...]:
-        return (INVOKE, *self.permissions)
+        return tuple(self.permissions)
 
     @property
     def option_names(self) -> tuple[str, ...]:
         return tuple(self.options.get("properties", {}))
 
 
-DEFAULT_EXPORTS = Exports({}, {})
+# Every route, for the implicit ``invoke`` of a service that declares no permissions.
+ALL_ROUTES = "* /*"
+DEFAULT_PERMISSIONS: dict[str, tuple[str, ...]] = {INVOKE: (ALL_ROUTES,)}
+DEFAULT_EXPORTS = Exports(DEFAULT_PERMISSIONS, {})
 
 _REQUEST_KEYS = frozenset({"object", "permissions", "required", "justification", "options", "limits"})
 
@@ -140,6 +160,9 @@ def parse_exports(where: str, declared: Any) -> Exports:
     """Read an offering's ``exports``, refusing a malformed one.
 
     ``None`` or ``{}`` is the default: ``invoke`` on every route, no options.
+    Without ``permissions`` (options only), ``invoke`` is still the one
+    permission. With ``permissions``, the service exports exactly those; it
+    may declare ``invoke`` among them.
     """
     if declared is None:
         return DEFAULT_EXPORTS
@@ -148,12 +171,15 @@ def parse_exports(where: str, declared: Any) -> Exports:
     if extra := set(declared) - {"permissions", "options", "options_ui_schema"}:
         raise ValueError(f"{where}: unknown keys {sorted(extra)}")
     permissions = declared.get("permissions", {})
-    if not isinstance(permissions, dict):
-        raise ValueError(f'{where}.permissions must be {{"<name>": ["<METHOD> /<path>", ...]}}')
+    if not isinstance(permissions, dict) or ("permissions" in declared and not permissions):
+        raise ValueError(
+            f'{where}.permissions must be {{"<name>": ["<METHOD> /<path>", ...]}} with at least one '
+            f"permission; omit it to export only '{INVOKE}' on every route"
+        )
     for name, routes in permissions.items():
         at = f"{where}.permissions.{name}"
-        if name == INVOKE:
-            raise ValueError(f"{at}: '{INVOKE}' is always exported and covers every route")
+        if not _PERMISSION_NAME.match(name):
+            raise ValueError(f"{at}: a permission name is lowercase letters, digits and '_'")
         if not _strings(routes) or not all(_ROUTE.match(r) for r in routes):
             raise ValueError(f"{at} must be a non-empty list of routes like 'GET /records/*'")
     options = declared.get("options", {})
@@ -162,6 +188,8 @@ def parse_exports(where: str, declared: Any) -> Exports:
     ui_schema = declared.get("options_ui_schema")
     if ui_schema is not None and not isinstance(ui_schema, dict):
         raise ValueError(f"{where}.options_ui_schema must be an object")
+    if not permissions:
+        return Exports(DEFAULT_PERMISSIONS, options)
     return Exports({name: tuple(routes) for name, routes in permissions.items()}, options)
 
 
@@ -185,7 +213,7 @@ def _check_options_schema(where: str, schema: Any) -> None:
     for name, prop in schema["properties"].items():
         at = f"{where}.properties.{name}"
         if not _OPTION_NAME.match(name):
-            raise ValueError(f"{at}: an option is a query argument; name it in lowercase letters, digits and '_'")
+            raise ValueError(f"{at}: an option name is lowercase letters, digits and '_'")
         kind = prop.get("type") if isinstance(prop, dict) else None
         if not isinstance(kind, str):
             raise ValueError(f"{at}.type must be one type, one of {sorted(_SCALAR_TYPES | {'array'})}")
@@ -309,10 +337,11 @@ def validate_access_requests(where: str, requests: Any, resolve: ExportsResolver
 
     ``where`` prefixes error messages
     (``upstream_access_config.<channel>.customer_access_requests``).
-    With ``resolve``, an entry claiming more than the default (a permission
-    other than ``invoke``, or any option) is checked against its target's
-    ``exports``, and an unknown target is refused; a default claim and limits
-    need no lookup. Without ``resolve``, only the shape is checked.
+    With ``resolve``, every entry's permissions and options are checked
+    against its target's ``exports`` (``invoke`` included: a service that
+    declares permissions may not export it), and an unknown target is
+    refused. Limits need no lookup. Without ``resolve``, only the shape is
+    checked.
     """
     if not isinstance(requests, list):
         raise ValueError(f"{where} must be a list of access request objects")
@@ -346,23 +375,31 @@ def validate_access_requests(where: str, requests: Any, resolve: ExportsResolver
             raise ValueError(f"{at}.permissions must be a non-empty list of distinct names")
         options = parse_options(f"{at}.options", entry.get("options", ""))
         validate_limits(f"{at}.limits", entry.get("limits", {}))
-        # A default claim (``invoke``, no options) is what every service
-        # exports, so only a claim beyond it needs the target's exports.
-        if resolve is None or (set(permissions) <= {INVOKE} and not options):
+        if resolve is None:
             continue
         declared = resolve(name)
         if declared is None:
             raise ValueError(f"{at}: {obj} is not a published service")
-        target = parse_exports(f"{obj} exports", declared)
-        if not set(permissions) <= set(target.permission_names):
-            raise ValueError(f"{at}.permissions: {obj} exports only {list(target.permission_names)}")
-        if unknown := sorted(set(options) - set(target.option_names)):
-            raise ValueError(
-                f"{at}.options: {obj} accepts no option {unknown[0]!r} "
-                f"(options: {sorted(target.option_names) or 'none'})"
-            )
-        if error := _options_error(target.options, options):
-            raise ValueError(f"{at}.options: {error}")
+        check_claim(at, obj, permissions, options, parse_exports(f"{obj} exports", declared))
+
+
+def check_claim(where: str, obj: str, permissions: list[str], options: dict[str, str], exports: Exports) -> None:
+    """Refuse a claim on ``obj`` (``service:<name>``) that its ``exports`` don't cover.
+
+    The check shared by a seller's access request and a key's policy entry:
+    every permission must be one the target exports (``invoke`` only if it
+    does), and every option, already split by :func:`parse_options`, must be
+    one it declares, with a value valid for that option's schema.
+    """
+    if not set(permissions) <= set(exports.permission_names):
+        raise ValueError(f"{where}.permissions: {obj} exports only {list(exports.permission_names)}")
+    if unknown := sorted(set(options) - set(exports.option_names)):
+        raise ValueError(
+            f"{where}.options: {obj} accepts no option {unknown[0]!r} "
+            f"(options: {sorted(exports.option_names) or 'none'})"
+        )
+    if error := _options_error(exports.options, options):
+        raise ValueError(f"{where}.options: {error}")
 
 
 def validate_channel_access_requests(config: Any, resolve: ExportsResolver | None = None) -> None:

{unitysvc_core-0.2.36 → unitysvc_core-0.2.37}/src/unitysvc_core/models/offering_data.py

@@ -108,9 +108,11 @@ class ServiceOfferingData(BaseModel):
         description=(
             "How other services may use this one (what a customer access request can ask for): "
             '{"permissions": {<name>: ["<METHOD> /<path>", ...]}, '
-            '"options": <JSON Schema object of the query arguments it accepts>, '
+            '"options": <JSON Schema object of the options a grant may set>, '
             '"options_ui_schema": <rjsf uiSchema>}. '
-            "invoke is always exported and covers every route; omitted: invoke only, no options. "
+            "Without permissions, the service exports one, invoke, on every route; with permissions, "
+            "exactly those (invoke only if declared), so a data service declaring read/write is never "
+            "reached by invoke or service:*. Omitted: invoke only, no options. "
             "See unitysvc_core.grants."
         ),
     )