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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.37
+Version: 0.3.0
 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>
@@ -57,6 +57,8 @@ src/unitysvc_core/
 │   ├── base.py            # All enums (status, type, currency, rate-limit, etc.)
 │   ├── pricing.py         # PriceStr, UsageData, all *PriceData classes,
 │   │                      # Pricing union, validate_pricing, cost calculation
+│   ├── channel.py         # UpstreamAccessConfig, ChannelConfig, per-protocol
+│   │                      # servers, ChannelParams, RETIRED_CHANNEL_KEYS
 │   ├── documents.py       # DocumentData
 │   ├── service.py         # RateLimit, ServiceConstraints, AccessInterfaceData,
 │   │                      # UpstreamAccessConfigData
@@ -135,24 +137,26 @@ MIT
 
 ### Required enrollment parameter usage
 
-The shared validator rejects required user parameters that no channel, interface,
-or document consumes. Only those consumer fields count — the offering's
-`upstream_access_config`, the listing's `user_access_interfaces`, and document
-content (a `.j2` document's template source, which the seller validator reads from
-disk as the SDK uploads it); metadata such as `display_name` or `description` is
-never rendered with `params`. File validation checks a listing against its paired offering
-when present; backend ingest calls the same `validate_required_parameter_usage`
-helper with the complete listing and offering. Schema declarations alone are not
-consumers. Jinja attribute access, string-key lookups, and `params.get("name")`
-are inspected; dynamic access and whole-map iteration conservatively consume all
-parameters. Deprecated content can still be retired.
-
-This validates usage, not channel attribution: a document reference counts as a
-consumer without proving that the intended paid channel takes enrollment.
+Each channel's required parameters must be read by that channel or by document
+content (a `.j2` document's template source, which the seller validator reads
+from disk as the SDK uploads it); another channel's use does not count. Metadata
+such as `display_name` or `description` is never rendered with `params`, and a
+user access interface never reads them. File validation checks a listing against
+its paired offering when present; backend ingest calls the same
+`validate_required_parameter_usage` helper with the complete listing and
+offering. Schema declarations alone are not consumers. Jinja attribute access,
+string-key lookups, and `params.get("name")` are inspected; dynamic access and
+whole-map iteration conservatively consume all parameters. Deprecated content can
+still be retired.
 
 ### Canonical user access interfaces
 
-A user access interface is the service's canonical address, the same for every caller, so `validate_listing_interfaces_are_canonical` refuses one that reads a per-enrollment value (`enrollment.*`, `params.*`). An enrollment is reached through the address the platform gives it: `/e/<CODE>` on the API gateway, which a listing never declares. The only per-enrollment form allowed is where the protocol has no such path and the code itself is the address: an SMTP `routing_key.username` or an S3 bucket segment that is exactly `{{ enrollment.code }}`. Values the same for every caller (`service_name`, `routing_vars`) stay allowed. The shared validator runs it on every `listing_v1`; backend ingest calls the same function (unitysvc/unitysvc#2726).
+A user access interface is the service's canonical address, the same for every caller. `validate_listing_interfaces_are_canonical` renders `{{ service_name }}` (the one value the platform fills in when it stores an interface) and then requires:
+
+- a `base_url` that is one of the four gateways, `${API_GATEWAY_BASE_URL}`, `${S3_GATEWAY_BASE_URL}`, `${SMTP_GATEWAY_BASE_URL}` or `${MCP_GATEWAY_BASE_URL}`, optionally followed by `/` and a path (`/a/<alias>` included); never an external URL, another variable or a secret reference;
+- no template left over. `{{ routing_vars.X }}` would stay literal in the stored interface and never route, and a per-enrollment value (`enrollment.*`, `params.*`) is never canonical: an enrollment is reached through `/e/<CODE>` on the API gateway, which a listing never declares.
+
+The one exception is `{{ enrollment.code }}` as the whole SMTP `routing_key.username` or the whole S3 bucket segment, a reminder of the per-enrollment address on protocols without a path for it. The shared validator runs it on every `listing_v1`; backend ingest calls the same function (unitysvc/unitysvc#2726).
 
 ### Listing audience
 
@@ -193,7 +197,7 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
 - **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.
+- `options`: a JSON Schema (draft 7) object of the customizations a grant may set on the service, like a channel's `params.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,10 +208,11 @@ 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). `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). `enrollment:<CODE>` (one enrollment of an enrollable service) may be allowed later.
 - `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.
+- **A longer-lived leased key** is asked for with one `apikey` entry: `{"object": "apikey", "limits": {"api_key_lifespan": 14400}, "justification": "Batch runs take up to four hours"}`. It names the key itself, so it takes only `limits` (exactly `api_key_lifespan`, whole seconds from 1 to 86400) and a `justification`, needs no catalog lookup, and grants nothing. Without it, a key the seller leases for the enrollment lives `DEFAULT_API_KEY_LIFESPAN` (3600 s). `api_key_lifespan` is valid only on this entry.
 
 **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:
 
@@ -224,9 +229,40 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
 - `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.
 
+**6. From approvals to a policy (`build_policy`).** When the customer enrolls, `build_policy(requests, approvals, resolve)` turns their approvals of the channel's requests into the policy the enrollment keeps and every key leased for it copies (unitysvc/unitysvc#2766):
+
+```json
+[{"object": "service:log", "permissions": ["invoke"], "options": "log_level=error", "limits": {"count_per_day": 200}},
+ {"object": "apikey", "limits": {"api_key_lifespan": 7200}}]
+```
+
+- Each approval names a requested object, at most once, with some of the permissions requested. Every `required` request must be approved; optional ones may be left out.
+- Options and limits are the customer's. They are checked against the target's `exports` (with `resolve`) and `validate_limits`, not against the request, whose values only pre-fill the form.
+- 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).
+
+### 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:
+
+| Channel key | What it is |
+| --- | --- |
+| `access_method` | `http` (default), `smtp`, `s3` or `mcp`; selects the server type |
+| `type` | normally derived by the platform; declare `external` (or `enrollable`) to state it |
+| `description`, `is_active`, `sort_order` | display text; inactive channels are skipped; rank, lowest first |
+| `request_formats`, `applicable_interfaces` | the formats the channel serves; the interfaces that reach it (display only) |
+| `rate_limit_refs` | the provider rate limits it consumes |
+| `customer_access_requests` | what the enrolling customer is asked to approve (see above) |
+| `params` | the enrollment parameters (below) |
+| `servers` | the connection: `HttpServer`, `SmtpServer`, `S3Server` or `McpServer` |
+
+The common one-server case writes the connection fields directly on the channel; they are read as `servers[0]`. When a channel has both, each server inherits the direct fields it does not set. Any string may be a template (`{{ params.X }}`, `${ secrets.X }`, `${ customer_secrets.X ?? default }`), so numeric and boolean connection fields also accept strings.
+
+Unknown keys are refused. Retired keys are refused with what to do instead (`RETIRED_CHANNEL_KEYS`): `raw`, `is_primary`, the listing-style parameter trio, `grants`, `rate_limits` (nothing reads it; use `rate_limit_refs`), `storage_type` (use `access_method: s3`), `response_rules`, `timeout_ms`, `transport`, and the platform-derived `customer_secrets_required` / `customer_secrets_optional`.
+
 ### 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):
+A channel declares the enrollment parameters it reads, so each plan of a service asks for what it needs (unitysvc/unitysvc#2726). A listing declares none: `user_parameters_schema`, `user_parameters_ui_schema` and `service_options.ops_testing_parameters` are refused.
 
 ```json
 "upstream_access_config": {
@@ -241,11 +277,8 @@ A channel may declare its own enrollment parameters, so each plan of a service a
 }
 ```
 
-`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`.
+`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. Rules:
 
-When no channel declares `params`, the listing-level `user_parameters_schema` applies to the whole service as before.
+- a channel reads only the parameters its `params.schema` declares, and a channel that reads `{{ params.* }}` must declare `params` (`validate_channel_parameters`, on every `offering_v1`);
+- each required parameter has a value in that channel's `params.testing_defaults`, which is also what `${ customer_secrets.{{ params.X }} }` renders with when secret references are checked;
+- each required parameter is read by its own channel or by document content (`validate_required_parameter_usage`, which backend ingest also calls).

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

@@ -22,6 +22,8 @@ src/unitysvc_core/
 │   ├── base.py            # All enums (status, type, currency, rate-limit, etc.)
 │   ├── pricing.py         # PriceStr, UsageData, all *PriceData classes,
 │   │                      # Pricing union, validate_pricing, cost calculation
+│   ├── channel.py         # UpstreamAccessConfig, ChannelConfig, per-protocol
+│   │                      # servers, ChannelParams, RETIRED_CHANNEL_KEYS
 │   ├── documents.py       # DocumentData
 │   ├── service.py         # RateLimit, ServiceConstraints, AccessInterfaceData,
 │   │                      # UpstreamAccessConfigData
@@ -100,24 +102,26 @@ MIT
 
 ### Required enrollment parameter usage
 
-The shared validator rejects required user parameters that no channel, interface,
-or document consumes. Only those consumer fields count — the offering's
-`upstream_access_config`, the listing's `user_access_interfaces`, and document
-content (a `.j2` document's template source, which the seller validator reads from
-disk as the SDK uploads it); metadata such as `display_name` or `description` is
-never rendered with `params`. File validation checks a listing against its paired offering
-when present; backend ingest calls the same `validate_required_parameter_usage`
-helper with the complete listing and offering. Schema declarations alone are not
-consumers. Jinja attribute access, string-key lookups, and `params.get("name")`
-are inspected; dynamic access and whole-map iteration conservatively consume all
-parameters. Deprecated content can still be retired.
-
-This validates usage, not channel attribution: a document reference counts as a
-consumer without proving that the intended paid channel takes enrollment.
+Each channel's required parameters must be read by that channel or by document
+content (a `.j2` document's template source, which the seller validator reads
+from disk as the SDK uploads it); another channel's use does not count. Metadata
+such as `display_name` or `description` is never rendered with `params`, and a
+user access interface never reads them. File validation checks a listing against
+its paired offering when present; backend ingest calls the same
+`validate_required_parameter_usage` helper with the complete listing and
+offering. Schema declarations alone are not consumers. Jinja attribute access,
+string-key lookups, and `params.get("name")` are inspected; dynamic access and
+whole-map iteration conservatively consume all parameters. Deprecated content can
+still be retired.
 
 ### Canonical user access interfaces
 
-A user access interface is the service's canonical address, the same for every caller, so `validate_listing_interfaces_are_canonical` refuses one that reads a per-enrollment value (`enrollment.*`, `params.*`). An enrollment is reached through the address the platform gives it: `/e/<CODE>` on the API gateway, which a listing never declares. The only per-enrollment form allowed is where the protocol has no such path and the code itself is the address: an SMTP `routing_key.username` or an S3 bucket segment that is exactly `{{ enrollment.code }}`. Values the same for every caller (`service_name`, `routing_vars`) stay allowed. The shared validator runs it on every `listing_v1`; backend ingest calls the same function (unitysvc/unitysvc#2726).
+A user access interface is the service's canonical address, the same for every caller. `validate_listing_interfaces_are_canonical` renders `{{ service_name }}` (the one value the platform fills in when it stores an interface) and then requires:
+
+- a `base_url` that is one of the four gateways, `${API_GATEWAY_BASE_URL}`, `${S3_GATEWAY_BASE_URL}`, `${SMTP_GATEWAY_BASE_URL}` or `${MCP_GATEWAY_BASE_URL}`, optionally followed by `/` and a path (`/a/<alias>` included); never an external URL, another variable or a secret reference;
+- no template left over. `{{ routing_vars.X }}` would stay literal in the stored interface and never route, and a per-enrollment value (`enrollment.*`, `params.*`) is never canonical: an enrollment is reached through `/e/<CODE>` on the API gateway, which a listing never declares.
+
+The one exception is `{{ enrollment.code }}` as the whole SMTP `routing_key.username` or the whole S3 bucket segment, a reminder of the per-enrollment address on protocols without a path for it. The shared validator runs it on every `listing_v1`; backend ingest calls the same function (unitysvc/unitysvc#2726).
 
 ### Listing audience
 
@@ -158,7 +162,7 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
 - **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.
+- `options`: a JSON Schema (draft 7) object of the customizations a grant may set on the service, like a channel's `params.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,10 +173,11 @@ 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). `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). `enrollment:<CODE>` (one enrollment of an enrollable service) may be allowed later.
 - `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.
+- **A longer-lived leased key** is asked for with one `apikey` entry: `{"object": "apikey", "limits": {"api_key_lifespan": 14400}, "justification": "Batch runs take up to four hours"}`. It names the key itself, so it takes only `limits` (exactly `api_key_lifespan`, whole seconds from 1 to 86400) and a `justification`, needs no catalog lookup, and grants nothing. Without it, a key the seller leases for the enrollment lives `DEFAULT_API_KEY_LIFESPAN` (3600 s). `api_key_lifespan` is valid only on this entry.
 
 **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:
 
@@ -189,9 +194,40 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
 - `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.
 
+**6. From approvals to a policy (`build_policy`).** When the customer enrolls, `build_policy(requests, approvals, resolve)` turns their approvals of the channel's requests into the policy the enrollment keeps and every key leased for it copies (unitysvc/unitysvc#2766):
+
+```json
+[{"object": "service:log", "permissions": ["invoke"], "options": "log_level=error", "limits": {"count_per_day": 200}},
+ {"object": "apikey", "limits": {"api_key_lifespan": 7200}}]
+```
+
+- Each approval names a requested object, at most once, with some of the permissions requested. Every `required` request must be approved; optional ones may be left out.
+- Options and limits are the customer's. They are checked against the target's `exports` (with `resolve`) and `validate_limits`, not against the request, whose values only pre-fill the form.
+- 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).
+
+### 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:
+
+| Channel key | What it is |
+| --- | --- |
+| `access_method` | `http` (default), `smtp`, `s3` or `mcp`; selects the server type |
+| `type` | normally derived by the platform; declare `external` (or `enrollable`) to state it |
+| `description`, `is_active`, `sort_order` | display text; inactive channels are skipped; rank, lowest first |
+| `request_formats`, `applicable_interfaces` | the formats the channel serves; the interfaces that reach it (display only) |
+| `rate_limit_refs` | the provider rate limits it consumes |
+| `customer_access_requests` | what the enrolling customer is asked to approve (see above) |
+| `params` | the enrollment parameters (below) |
+| `servers` | the connection: `HttpServer`, `SmtpServer`, `S3Server` or `McpServer` |
+
+The common one-server case writes the connection fields directly on the channel; they are read as `servers[0]`. When a channel has both, each server inherits the direct fields it does not set. Any string may be a template (`{{ params.X }}`, `${ secrets.X }`, `${ customer_secrets.X ?? default }`), so numeric and boolean connection fields also accept strings.
+
+Unknown keys are refused. Retired keys are refused with what to do instead (`RETIRED_CHANNEL_KEYS`): `raw`, `is_primary`, the listing-style parameter trio, `grants`, `rate_limits` (nothing reads it; use `rate_limit_refs`), `storage_type` (use `access_method: s3`), `response_rules`, `timeout_ms`, `transport`, and the platform-derived `customer_secrets_required` / `customer_secrets_optional`.
+
 ### 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):
+A channel declares the enrollment parameters it reads, so each plan of a service asks for what it needs (unitysvc/unitysvc#2726). A listing declares none: `user_parameters_schema`, `user_parameters_ui_schema` and `service_options.ops_testing_parameters` are refused.
 
 ```json
 "upstream_access_config": {
@@ -206,11 +242,8 @@ A channel may declare its own enrollment parameters, so each plan of a service a
 }
 ```
 
-`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`.
+`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. Rules:
 
-When no channel declares `params`, the listing-level `user_parameters_schema` applies to the whole service as before.
+- a channel reads only the parameters its `params.schema` declares, and a channel that reads `{{ params.* }}` must declare `params` (`validate_channel_parameters`, on every `offering_v1`);
+- each required parameter has a value in that channel's `params.testing_defaults`, which is also what `${ customer_secrets.{{ params.X }} }` renders with when secret references are checked;
+- each required parameter is read by its own channel or by document content (`validate_required_parameter_usage`, which backend ingest also calls).

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

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

@@ -22,7 +22,7 @@ Three stages (unitysvc/unitysvc#2720):
   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
+  like a channel's ``params.schema`` (with an optional
   ``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
@@ -72,8 +72,11 @@ customer consent and key issuance establish its *authority*.
   be limited by ``count`` or ``amount`` per hour, day or month, or in total,
   without exporting anything (``{"count_per_day": 2, "amount_per_month": "2.00"}``).
 
-Today a request's ``object`` is ``service:<name>``; ``enrollment:<CODE>`` (one
-enrollment of an enrollable service) may follow.
+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
+customer's approvals into the policy an enrollment keeps.
 
 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
@@ -101,6 +104,13 @@ from .models.validators import validate_service_identifier
 
 SERVICE_PREFIX = "service:"
 INVOKE = "invoke"
+# The key itself: a request for a longer-lived leased key, and the approved
+# lifespan in a policy. It grants nothing.
+APIKEY_OBJECT = "apikey"
+API_KEY_LIFESPAN = "api_key_lifespan"
+# Seconds a leased key lives unless the policy says otherwise, and at most.
+DEFAULT_API_KEY_LIFESPAN = 3600
+MAX_API_KEY_LIFESPAN = 86400
 # The channel key a seller's requests are declared under.
 REQUESTS_KEY = "customer_access_requests"
 
@@ -144,6 +154,9 @@ DEFAULT_PERMISSIONS: dict[str, tuple[str, ...]] = {INVOKE: (ALL_ROUTES,)}
 DEFAULT_EXPORTS = Exports(DEFAULT_PERMISSIONS, {})
 
 _REQUEST_KEYS = frozenset({"object", "permissions", "required", "justification", "options", "limits"})
+_APIKEY_REQUEST_KEYS = frozenset({"object", "justification", "limits"})
+# What a policy entry (an approved request) holds.
+_POLICY_KEYS = frozenset({"object", "permissions", "options", "limits"})
 
 
 def _strings(value: Any) -> bool:
@@ -310,15 +323,29 @@ def parse_options(where: str, options: Any) -> dict[str, str]:
     return parsed
 
 
-def validate_limits(where: str, limits: Any) -> None:
+def validate_limits(where: str, limits: Any, *, apikey: bool = False) -> None:
     """Refuse ``limits`` unless it maps ``<metric>_per_<window>`` or
     ``<metric>_total`` to a maximum: ``count`` a positive integer, ``amount`` a
     finite positive decimal, as a number (``2.5``) or a string (``"2.50"``).
     Windows: hour, day, month. The same shape serves a request's suggested
     limits, the limits a customer sets in a key's policy, and an enrollment's own
-    limits."""
+    limits.
+
+    With ``apikey`` (the ``apikey`` entry), the only limit is
+    ``api_key_lifespan``: how many seconds a leased key lives, an integer from 1
+    to :data:`MAX_API_KEY_LIFESPAN`.
+    """
     if not isinstance(limits, dict):
         raise ValueError(f'{where} must be an object like {{"count_per_day": 2}}')
+    if apikey:
+        if set(limits) != {API_KEY_LIFESPAN}:
+            raise ValueError(f'{where} must be {{"{API_KEY_LIFESPAN}": <seconds>}}')
+        value = limits[API_KEY_LIFESPAN]
+        if not isinstance(value, int) or isinstance(value, bool) or not 0 < value <= MAX_API_KEY_LIFESPAN:
+            raise ValueError(
+                f"{where}.{API_KEY_LIFESPAN} must be a whole number of seconds from 1 to {MAX_API_KEY_LIFESPAN}"
+            )
+        return
     for key, value in limits.items():
         at = f"{where}.{key}"
         match = _LIMIT.match(key) if isinstance(key, str) else None
@@ -351,6 +378,12 @@ def validate_access_requests(where: str, requests: Any, resolve: ExportsResolver
         if not isinstance(entry, dict) or not isinstance(entry.get("object"), str):
             raise ValueError(f'{at} must be {{"object": "service:<name>", ...}}')
         obj = entry["object"]
+        if obj == APIKEY_OBJECT:
+            if obj in seen:
+                raise ValueError(f"{at}: {obj} is listed twice")
+            seen.add(obj)
+            _check_apikey_request(at, entry)
+            continue
         if not obj.startswith(SERVICE_PREFIX):
             raise ValueError(f"{at}: {obj!r} cannot be requested; name one service as 'service:<name>'")
         name = obj.removeprefix(SERVICE_PREFIX)
@@ -383,6 +416,16 @@ def validate_access_requests(where: str, requests: Any, resolve: ExportsResolver
         check_claim(at, obj, permissions, options, parse_exports(f"{obj} exports", declared))
 
 
+def _check_apikey_request(at: str, entry: dict[str, Any]) -> None:
+    """The ``apikey`` request: how long a leased key should live, with why."""
+    if extra := set(entry) - _APIKEY_REQUEST_KEYS:
+        raise ValueError(f"{at}: unknown keys {sorted(extra)} (the {APIKEY_OBJECT} request takes only limits)")
+    justification = entry.get("justification")
+    if not isinstance(justification, str) or not justification.strip():
+        raise ValueError(f"{at}.justification must say why a leased key needs to live this long; the customer reads it")
+    validate_limits(f"{at}.limits", entry.get("limits"), apikey=True)
+
+
 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.
 
@@ -410,3 +453,84 @@ def validate_channel_access_requests(config: Any, resolve: ExportsResolver | Non
     for name, channel in config.items():
         if isinstance(channel, dict) and REQUESTS_KEY in channel:
             validate_access_requests(f"upstream_access_config.{name}.{REQUESTS_KEY}", channel[REQUESTS_KEY], resolve)
+
+
+def build_policy(requests: Any, approvals: Any, resolve: ExportsResolver | None = None) -> list[dict[str, Any]]:
+    """The key policy a customer's ``approvals`` of a channel's ``requests``
+    make (unitysvc/unitysvc#2766).
+
+    ``requests`` is the channel's ``customer_access_requests``; ``approvals``
+    lists the requests the customer approves, each ``{"object", "permissions",
+    "options", "limits"}`` (the ``apikey`` entry only ``{"object", "limits"}``).
+    Each approval names a requested object, at most once; its permissions are
+    some of those requested; every ``required`` request is approved. The
+    customer sets options and limits: a request's own only pre-fill them, so
+    they are checked against the target's ``exports`` (with ``resolve``) and
+    :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``.
+    """
+    validate_access_requests("requests", requests)
+    requested = {entry["object"]: entry for entry in requests}
+    if not isinstance(approvals, list):
+        raise ValueError("approvals must be a list of approved requests")
+    policy: list[dict[str, Any]] = []
+    for index, approval in enumerate(approvals):
+        at = f"approvals[{index}]"
+        if not isinstance(approval, dict) or not isinstance(approval.get("object"), str):
+            raise ValueError(f'{at} must be {{"object": ..., "permissions": [...]}}')
+        obj = approval["object"]
+        request = requested.get(obj)
+        if request is None:
+            raise ValueError(f"{at}: {obj} is not requested")
+        if any(entry["object"] == obj for entry in policy):
+            raise ValueError(f"{at}: {obj} is approved twice")
+        if obj == APIKEY_OBJECT:
+            if extra := set(approval) - {"object", "limits"}:
+                raise ValueError(f"{at}: unknown keys {sorted(extra)} (the {APIKEY_OBJECT} entry takes only limits)")
+            validate_limits(f"{at}.limits", approval.get("limits"), apikey=True)
+            asked = request["limits"][API_KEY_LIFESPAN]
+            if approval["limits"][API_KEY_LIFESPAN] > asked:
+                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:
+            raise ValueError(f"{at}: unknown keys {sorted(extra)}")
+        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")
+        if not set(permissions) <= set(request["permissions"]):
+            raise ValueError(f"{at}.permissions: the service requests only {request['permissions']}")
+        options_text = approval.get("options", "")
+        options = parse_options(f"{at}.options", options_text)
+        limits = approval.get("limits", {})
+        validate_limits(f"{at}.limits", limits)
+        if resolve is not None:
+            declared = resolve(obj.removeprefix(SERVICE_PREFIX))
+            if declared is 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 options:
+            entry["options"] = options_text
+        if limits:
+            entry["limits"] = dict(limits)
+        policy.append(entry)
+    approved = {entry["object"] for entry in policy}
+    if missing := sorted(obj for obj, request in requested.items() if request.get("required") and obj not in approved):
+        raise ValueError(f"approvals: the service requires {', '.join(missing)}")
+    return policy
+
+
+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
+    entry gets the default, never more."""
+    for entry in policy if isinstance(policy, list) else []:
+        if isinstance(entry, dict) and entry.get("object") == APIKEY_OBJECT:
+            try:
+                validate_limits("apikey.limits", entry.get("limits"), apikey=True)
+            except ValueError:
+                return DEFAULT_API_KEY_LIFESPAN
+            return int(entry["limits"][API_KEY_LIFESPAN])
+    return DEFAULT_API_KEY_LIFESPAN

{unitysvc_core-0.2.37 → unitysvc_core-0.3.0}/src/unitysvc_core/models/__init__.py

@@ -26,6 +26,21 @@ from .base import (
     TimeWindow,
     UpstreamStatusEnum,  # Backwards compatibility alias for OfferingStatusEnum
 )
+from .channel import (
+    RETIRED_CHANNEL_KEYS,
+    ChannelConfig,
+    ChannelParams,
+    HttpChannel,
+    HttpServer,
+    McpChannel,
+    McpServer,
+    RequestTransformer,
+    S3Channel,
+    S3Server,
+    SmtpChannel,
+    SmtpServer,
+    UpstreamAccessConfig,
+)
 from .documents import DocumentData
 from .listing_data import ServiceListingData
 from .listing_v1 import ListingV1
@@ -104,6 +119,20 @@ __all__ = [
     "ListingV1",
     "PromotionV1",
     "ServiceGroupV1",
+    # Upstream access channels
+    "UpstreamAccessConfig",
+    "ChannelConfig",
+    "ChannelParams",
+    "HttpChannel",
+    "SmtpChannel",
+    "S3Channel",
+    "McpChannel",
+    "HttpServer",
+    "SmtpServer",
+    "S3Server",
+    "McpServer",
+    "RequestTransformer",
+    "RETIRED_CHANNEL_KEYS",
     # Data models (for API/backend use)
     "ProviderAccountRateLimit",
     "ProviderData",