unitysvc-core 0.3.0__tar.gz → 0.3.1__tar.gz

{unitysvc_core-0.3.0/src/unitysvc_core.egg-info → unitysvc_core-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.3.0
+Version: 0.3.1
 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>
@@ -208,7 +208,7 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
                 "limits": {"count_per_day": 1000}}]
 ```
 
-- `object` names one service (`service:<name>`, no wildcards), or `apikey` for the leased key's lifespan (below). `enrollment:<CODE>` (one enrollment of an enrollable service) may be allowed later.
+- `object` names one service (`service:<name>`, no wildcards), or `apikey` for the leased key's lifespan (below).
 - `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.
@@ -241,6 +241,14 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
 - The `apikey` lifespan may be shortened, never lengthened beyond the request.
 - The result drops `required` / `justification` and empty `options` / `limits`. `api_key_lifespan(policy)` reads the lifespan back (the default when there is none).
 
+A policy has three kinds of entry (unitysvc/unitysvc#2770):
+
+| Entry | Means |
+| --- | --- |
+| `{"object": "enrollment", "limits": {"amount_per_day": "1.00"}}` | This enrollment's own limits (total spending, say). The customer adds it without a request; it takes only `limits`, at least one, at most one entry. It grants nothing. |
+| `{"object": "service:ai", ...}` | A service the app calls for the customer. A seller may name a specific one (`service:labs/llm-premium` instead of `service:ai` with `options="service=labs/llm-premium"`), at the cost of the customer's choice of provider, which a customer may decline. |
+| `{"object": "service:<name>", "enrollment": "<CODE>", ...}` | One of the customer's enrollments of a service that requires enrolling (a chain enrollment), called through `/e/<CODE>`. The customer picks the enrollment when approving the request for `service:<name>`, so a request never carries a code. A canonical code, no `options` (the enrollment's params are fixed), permissions and limits as for any service entry. Core checks the code's form; the caller checks the enrollment is the customer's. |
+
 ### Upstream access channels
 
 `upstream_access_config` maps a channel name to a channel (`UpstreamAccessConfig`, `ChannelConfig`; unitysvc/unitysvc#2730). A channel describes one way the platform reaches the upstream, as a whole, and its `servers` hold the connection, typed by the channel's protocol:

{unitysvc_core-0.3.0 → unitysvc_core-0.3.1}/README.md

@@ -173,7 +173,7 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
                 "limits": {"count_per_day": 1000}}]
 ```
 
-- `object` names one service (`service:<name>`, no wildcards), or `apikey` for the leased key's lifespan (below). `enrollment:<CODE>` (one enrollment of an enrollable service) may be allowed later.
+- `object` names one service (`service:<name>`, no wildcards), or `apikey` for the leased key's lifespan (below).
 - `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.
@@ -206,6 +206,14 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
 - The `apikey` lifespan may be shortened, never lengthened beyond the request.
 - The result drops `required` / `justification` and empty `options` / `limits`. `api_key_lifespan(policy)` reads the lifespan back (the default when there is none).
 
+A policy has three kinds of entry (unitysvc/unitysvc#2770):
+
+| Entry | Means |
+| --- | --- |
+| `{"object": "enrollment", "limits": {"amount_per_day": "1.00"}}` | This enrollment's own limits (total spending, say). The customer adds it without a request; it takes only `limits`, at least one, at most one entry. It grants nothing. |
+| `{"object": "service:ai", ...}` | A service the app calls for the customer. A seller may name a specific one (`service:labs/llm-premium` instead of `service:ai` with `options="service=labs/llm-premium"`), at the cost of the customer's choice of provider, which a customer may decline. |
+| `{"object": "service:<name>", "enrollment": "<CODE>", ...}` | One of the customer's enrollments of a service that requires enrolling (a chain enrollment), called through `/e/<CODE>`. The customer picks the enrollment when approving the request for `service:<name>`, so a request never carries a code. A canonical code, no `options` (the enrollment's params are fixed), permissions and limits as for any service entry. Core checks the code's form; the caller checks the enrollment is the customer's. |
+
 ### Upstream access channels
 
 `upstream_access_config` maps a channel name to a channel (`UpstreamAccessConfig`, `ChannelConfig`; unitysvc/unitysvc#2730). A channel describes one way the platform reaches the upstream, as a whole, and its `servers` hold the connection, typed by the channel's protocol:

{unitysvc_core-0.3.0 → unitysvc_core-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unitysvc-core"
-version = "0.3.0"
+version = "0.3.1"
 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.3.0 → unitysvc_core-0.3.1}/src/unitysvc_core/grants.py

@@ -74,10 +74,26 @@ customer consent and key issuance establish its *authority*.
 
 Today a request's ``object`` is ``service:<name>``, or ``apikey``: how long a
 key leased for the enrollment lives (``limits.api_key_lifespan``, up to a day,
-with a justification), which grants nothing. ``enrollment:<CODE>`` (one
-enrollment of an enrollable service) may follow. :func:`build_policy` turns a
+with a justification), which grants nothing. :func:`build_policy` turns a
 customer's approvals into the policy an enrollment keeps.
 
+A policy has three kinds of entry (unitysvc/unitysvc#2770):
+
+* ``{"object": "enrollment", "limits": {...}}``: this enrollment's own limits
+  (what it may cost in total, say). The customer's own; no seller requests it,
+  and it grants nothing.
+* ``{"object": "service:<name>", ...}``: a service the enrolled app calls for
+  the customer, usually a common one (``service:ai``, ``service:notify``). A
+  seller may name a specific service (``service:labs/llm-premium`` rather than
+  ``service:ai`` with ``options="service=labs/llm-premium"``), at the cost of
+  the customer's choice of provider, which a customer may decline.
+* ``{"object": "service:<name>", "enrollment": "<CODE>", ...}``: one of the
+  customer's enrollments of a service that requires enrolling (a chain
+  enrollment), which the app calls through ``/e/<CODE>``. Its params are fixed
+  by that enrollment, so it takes no ``options``. Which enrollment is the
+  customer's choice when approving, so a request never names one; core checks
+  the code's form, the caller that the enrollment is the customer's.
+
 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
@@ -157,6 +173,12 @@ _REQUEST_KEYS = frozenset({"object", "permissions", "required", "justification",
 _APIKEY_REQUEST_KEYS = frozenset({"object", "justification", "limits"})
 # What a policy entry (an approved request) holds.
 _POLICY_KEYS = frozenset({"object", "permissions", "options", "limits"})
+# This enrollment itself: an entry capping what it may cost. It grants nothing.
+ENROLLMENT_OBJECT = "enrollment"
+# On a service entry, one enrollment of that service (a chain enrollment).
+ENROLLMENT_KEY = "enrollment"
+# An enrollment code: canonical Crockford base32 (no I, L, O, U).
+_ENROLLMENT_CODE = re.compile(r"^[0-9A-HJKMNP-TV-Z]+$")
 
 
 def _strings(value: Any) -> bool:
@@ -469,6 +491,13 @@ def build_policy(requests: Any, approvals: Any, resolve: ExportsResolver | None
     :func:`validate_limits`, not against the request. A key lifespan may only
     be shortened. Returns the approvals as policy entries, without empty
     ``options`` / ``limits``. Raises ``ValueError``.
+
+    The customer may also add, at most once and without a request, this
+    enrollment's own limits: ``{"object": "enrollment", "limits": {...}}``,
+    with at least one limit and nothing else (unitysvc/unitysvc#2770). And an
+    approval of a service may select one of the customer's enrollments of it
+    (``"enrollment": "<CODE>"``, a chain enrollment): a canonical code, and no
+    ``options``. The caller checks the enrollment is the customer's.
     """
     validate_access_requests("requests", requests)
     requested = {entry["object"]: entry for entry in requests}
@@ -480,6 +509,11 @@ def build_policy(requests: Any, approvals: Any, resolve: ExportsResolver | None
         if not isinstance(approval, dict) or not isinstance(approval.get("object"), str):
             raise ValueError(f'{at} must be {{"object": ..., "permissions": [...]}}')
         obj = approval["object"]
+        if obj == ENROLLMENT_OBJECT:
+            if any(entry["object"] == obj for entry in policy):
+                raise ValueError(f"{at}: {obj} is listed twice")
+            policy.append(_enrollment_entry(at, approval))
+            continue
         request = requested.get(obj)
         if request is None:
             raise ValueError(f"{at}: {obj} is not requested")
@@ -494,8 +528,14 @@ def build_policy(requests: Any, approvals: Any, resolve: ExportsResolver | None
                 raise ValueError(f"{at}.limits.{API_KEY_LIFESPAN}: the service asks for at most {asked} seconds")
             policy.append({"object": obj, "limits": dict(approval["limits"])})
             continue
-        if extra := set(approval) - _POLICY_KEYS:
+        if extra := set(approval) - _POLICY_KEYS - {ENROLLMENT_KEY}:
             raise ValueError(f"{at}: unknown keys {sorted(extra)}")
+        code = approval.get(ENROLLMENT_KEY)
+        if ENROLLMENT_KEY in approval:
+            if not isinstance(code, str) or not _ENROLLMENT_CODE.match(code):
+                raise ValueError(f"{at}.{ENROLLMENT_KEY} must be an enrollment code, like JYY87Y")
+            if approval.get("options"):
+                raise ValueError(f"{at}.options: an enrollment's params are fixed; it takes no options")
         permissions: list[str] = approval.get("permissions") or []
         if not _strings(permissions):
             raise ValueError(f"{at}.permissions must be a non-empty list of distinct names")
@@ -511,6 +551,8 @@ def build_policy(requests: Any, approvals: Any, resolve: ExportsResolver | None
                 raise ValueError(f"{at}: {obj} is not a published service")
             check_claim(at, obj, permissions, options, parse_exports(f"{obj} exports", declared))
         entry: dict[str, Any] = {"object": obj, "permissions": list(permissions)}
+        if code is not None:
+            entry[ENROLLMENT_KEY] = code
         if options:
             entry["options"] = options_text
         if limits:
@@ -522,6 +564,17 @@ def build_policy(requests: Any, approvals: Any, resolve: ExportsResolver | None
     return policy
 
 
+def _enrollment_entry(at: str, approval: dict[str, Any]) -> dict[str, Any]:
+    """This enrollment's own entry: limits only, and at least one."""
+    if extra := set(approval) - {"object", "limits"}:
+        raise ValueError(f"{at}: unknown keys {sorted(extra)} (the {ENROLLMENT_OBJECT} entry takes only limits)")
+    limits = approval.get("limits")
+    if not limits:
+        raise ValueError(f"{at}.limits: the {ENROLLMENT_OBJECT} entry must set at least one limit")
+    validate_limits(f"{at}.limits", limits)
+    return {"object": ENROLLMENT_OBJECT, "limits": dict(limits)}
+
+
 def api_key_lifespan(policy: Any) -> int:
     """Seconds a key leased with ``policy`` lives: its ``apikey`` entry's
     ``api_key_lifespan``, else :data:`DEFAULT_API_KEY_LIFESPAN`. A malformed

{unitysvc_core-0.3.0 → unitysvc_core-0.3.1/src/unitysvc_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.3.0
+Version: 0.3.1
 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>
@@ -208,7 +208,7 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
                 "limits": {"count_per_day": 1000}}]
 ```
 
-- `object` names one service (`service:<name>`, no wildcards), or `apikey` for the leased key's lifespan (below). `enrollment:<CODE>` (one enrollment of an enrollable service) may be allowed later.
+- `object` names one service (`service:<name>`, no wildcards), or `apikey` for the leased key's lifespan (below).
 - `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.
@@ -241,6 +241,14 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
 - The `apikey` lifespan may be shortened, never lengthened beyond the request.
 - The result drops `required` / `justification` and empty `options` / `limits`. `api_key_lifespan(policy)` reads the lifespan back (the default when there is none).
 
+A policy has three kinds of entry (unitysvc/unitysvc#2770):
+
+| Entry | Means |
+| --- | --- |
+| `{"object": "enrollment", "limits": {"amount_per_day": "1.00"}}` | This enrollment's own limits (total spending, say). The customer adds it without a request; it takes only `limits`, at least one, at most one entry. It grants nothing. |
+| `{"object": "service:ai", ...}` | A service the app calls for the customer. A seller may name a specific one (`service:labs/llm-premium` instead of `service:ai` with `options="service=labs/llm-premium"`), at the cost of the customer's choice of provider, which a customer may decline. |
+| `{"object": "service:<name>", "enrollment": "<CODE>", ...}` | One of the customer's enrollments of a service that requires enrolling (a chain enrollment), called through `/e/<CODE>`. The customer picks the enrollment when approving the request for `service:<name>`, so a request never carries a code. A canonical code, no `options` (the enrollment's params are fixed), permissions and limits as for any service entry. Core checks the code's form; the caller checks the enrollment is the customer's. |
+
 ### Upstream access channels
 
 `upstream_access_config` maps a channel name to a channel (`UpstreamAccessConfig`, `ChannelConfig`; unitysvc/unitysvc#2730). A channel describes one way the platform reaches the upstream, as a whole, and its `servers` hold the connection, typed by the channel's protocol:

{unitysvc_core-0.3.0 → unitysvc_core-0.3.1}/tests/test_grants.py

@@ -511,3 +511,84 @@ def test_malformed_requests_build_no_policy() -> None:
 )
 def test_a_policy_without_a_valid_lifespan_gets_the_default(policy: Any) -> None:
     assert api_key_lifespan(policy) == DEFAULT_API_KEY_LIFESPAN
+
+
+# This enrollment's own limits (unitysvc/unitysvc#2770) ---------------------------
+
+
+def test_the_enrollment_entry_needs_no_request() -> None:
+    policy = _approve(_LOG_APPROVAL, {"object": "enrollment", "limits": {"amount_per_day": "1.00"}})
+    assert policy[-1] == {"object": "enrollment", "limits": {"amount_per_day": "1.00"}}
+    # Any enrollment may carry one, even of a channel that requests nothing.
+    assert build_policy([], [{"object": "enrollment", "limits": {"count_total": 5}}]) == [
+        {"object": "enrollment", "limits": {"count_total": 5}}
+    ]
+    assert api_key_lifespan(policy) == DEFAULT_API_KEY_LIFESPAN
+
+
+@pytest.mark.parametrize(
+    ("entry", "error"),
+    [
+        ({"object": "enrollment"}, "at least one limit"),
+        ({"object": "enrollment", "limits": {}}, "at least one limit"),
+        ({"object": "enrollment", "limits": {"calls": 1}}, "count_/amount_"),
+        ({"object": "enrollment", "permissions": ["invoke"], "limits": {"count_total": 1}}, "takes only limits"),
+        ({"object": "enrollment", "options": "a=b", "limits": {"count_total": 1}}, "takes only limits"),
+        ({"object": "enrollment", "enrollment": "ABC123", "limits": {"count_total": 1}}, "takes only limits"),
+    ],
+)
+def test_the_enrollment_entry_takes_only_limits(entry: dict[str, Any], error: str) -> None:
+    with pytest.raises(ValueError, match=error):
+        _approve(_LOG_APPROVAL, entry)
+
+
+def test_the_enrollment_entry_appears_once() -> None:
+    entry = {"object": "enrollment", "limits": {"count_total": 1}}
+    with pytest.raises(ValueError, match="listed twice"):
+        _approve(_LOG_APPROVAL, entry, entry)
+
+
+def test_an_approval_may_select_one_of_the_customers_enrollments() -> None:
+    policy = _approve(
+        _LOG_APPROVAL,
+        {"object": "service:me", "permissions": ["read"], "enrollment": "JYY87Y", "limits": {"count_per_day": 3}},
+    )
+    assert policy[-1] == {
+        "object": "service:me",
+        "permissions": ["read"],
+        "enrollment": "JYY87Y",
+        "limits": {"count_per_day": 3},
+    }
+
+
+@pytest.mark.parametrize(
+    ("extra", "error"),
+    [
+        ({"enrollment": "jyy87y"}, "must be an enrollment code"),
+        ({"enrollment": "AB-12"}, "must be an enrollment code"),
+        ({"enrollment": "ABCDIO"}, "must be an enrollment code"),
+        ({"enrollment": ""}, "must be an enrollment code"),
+        ({"enrollment": 123}, "must be an enrollment code"),
+        ({"enrollment": "JYY87Y", "options": "profile=address"}, "takes no options"),
+    ],
+)
+def test_a_chain_enrollment_names_a_code_and_takes_no_options(extra: dict[str, Any], error: str) -> None:
+    with pytest.raises(ValueError, match=error):
+        _approve(_LOG_APPROVAL, {"object": "service:me", "permissions": ["read"], **extra})
+
+
+def test_a_chain_enrollment_is_still_an_approval_of_a_request() -> None:
+    with pytest.raises(ValueError, match="is not requested"):
+        _approve(_LOG_APPROVAL, {"object": "service:notify", "permissions": ["invoke"], "enrollment": "JYY87Y"})
+    with pytest.raises(ValueError, match="requests only"):
+        _approve(_LOG_APPROVAL, {"object": "service:me", "permissions": ["delete"], "enrollment": "JYY87Y"})
+
+
+def test_a_request_never_names_an_enrollment() -> None:
+    with pytest.raises(ValueError, match="unknown keys"):
+        validate_access_requests(_WHERE, [_dep("service:me", enrollment="JYY87Y")])
+
+
+def test_a_seller_cannot_request_the_enrollment_entry() -> None:
+    with pytest.raises(ValueError, match="cannot be requested"):
+        validate_access_requests(_WHERE, [{"object": "enrollment", "justification": "x", "limits": {"count_total": 1}}])