diff --git a/anton/core/tools/connector_auth_rules.py b/anton/core/tools/connector_auth_rules.py index 44fc245e7..69a219e44 100644 --- a/anton/core/tools/connector_auth_rules.py +++ b/anton/core/tools/connector_auth_rules.py @@ -24,6 +24,9 @@ "basic": frozenset({"type", "username", "password"}), "query": frozenset({"type", "params"}), } +#: The type of a connection's own section when it holds no key to place. Never +#: part of a template, so it stays out of ``AUTH_KEYS`` and the tool schema. +AUTH_NONE = "none" HEADER_NAME = re.compile(r"[A-Za-z][A-Za-z0-9-]{0,40}") #: No ``.``: it would split the token-run rule, and some frameworks read it as ``_``. @@ -212,8 +215,18 @@ def _check_keys(data: dict, allowed: frozenset[str], where: str) -> None: raise AuthRuleError(f"{where} has a key that is not allowed. Allowed keys: {', '.join(sorted(allowed))}.") +def _check_optional_placement(names: set[str], optional: frozenset[str], where: str) -> None: + """Refuse a template that places an optional field together with another field. + + Dropping the optional field must drop the whole header or parameter, so + nothing else may ride in it. + """ + if names & optional and len(names) > 1: + raise AuthRuleError(f"{where} places an optional field with another field; give it a place of its own.") + + def _parse_headers( - value: Any, declared: frozenset[str], looks_secret: LooksSecret | None + value: Any, declared: frozenset[str], looks_secret: LooksSecret | None, optional: frozenset[str] ) -> tuple[dict[str, str], set[str]]: """Return the ``header`` type's headers and the fields they place.""" if not isinstance(value, dict) or not 1 <= len(value) <= MAX_AUTH_HEADERS: @@ -228,6 +241,7 @@ def _parse_headers( raise AuthRuleError("auth.headers has a header name that is not allowed.") seen.add(name.lower()) text, names = check_template(template, f"auth.headers[{index}]", declared, looks_secret=looks_secret) + _check_optional_placement(names, optional, f"auth.headers[{index}]") # Basic needs base64 of user:password, which a header template cannot build. if text.lower().startswith("basic"): raise AuthRuleError("auth.headers must not hold a Basic value; use auth type 'basic'.") @@ -237,7 +251,7 @@ def _parse_headers( def _parse_params( - value: Any, declared: frozenset[str], looks_secret: LooksSecret | None + value: Any, declared: frozenset[str], looks_secret: LooksSecret | None, optional: frozenset[str] ) -> tuple[dict[str, str], set[str]]: """Return the ``query`` type's parameters and the fields they place.""" if not isinstance(value, dict) or not 1 <= len(value) <= MAX_AUTH_PARAMS: @@ -252,6 +266,7 @@ def _parse_params( seen.add(name.lower()) where = f"auth.params[{index}]" text, names = check_template(template, where, declared, looks_secret=looks_secret) + _check_optional_placement(names, optional, where) if QUERY_LITERAL_REFUSED & set(PLACEHOLDER.sub("", text)): raise AuthRuleError(f"{where} may not hold &, #, +, = or a space outside {{field_name}}.") params[name] = text @@ -284,7 +299,7 @@ def render(auth: Mapping[str, Any], values: Mapping[str, str]) -> tuple[dict[str HTTP client. Args: - auth: An auth section as ``parse_auth`` returned it. + auth: An auth section as ``parse_auth`` returned it; ``none`` places nothing. values: Each placed field's value. Returns: @@ -294,6 +309,8 @@ def render(auth: Mapping[str, Any], values: Mapping[str, str]) -> tuple[dict[str AuthRuleError: when the type is not one this file knows, or a placed field has no value or holds a control character. """ + if auth["type"] == AUTH_NONE: + return {}, [] if auth["type"] == "basic": pair = f"{_fill(auth['username'], values)}:{_fill(auth['password'], values)}" return {"Authorization": "Basic " + base64.b64encode(pair.encode()).decode("ascii")}, [] @@ -325,17 +342,33 @@ def query_collides(auth: Mapping[str, Any], names: Iterable[str]) -> bool: def parse_auth( - data: Any, fields: Sequence[tuple[str, bool]], looks_secret: LooksSecret | None = None + data: Any, + fields: Sequence[tuple[str, bool]], + looks_secret: LooksSecret | None = None, + *, + optional: frozenset[str] = frozenset(), + stored: bool = False, ) -> dict[str, Any]: """Check an auth section against the template's fields and return it canonical. - It must place at least one secret field and every field: a field it never - uses would ask the member for a value that goes nowhere. + A template's section must place at least one secret field and every + field: a field it never uses would ask the member for a value that goes + nowhere. A header or parameter that places an optional field places only + that field. In Basic only the password may be optional, as the whole + password template, and only beside a username that places a required + secret field, so a skipped password never leaves a bare identity. + + A stored section is a connection's own: the template's section with the + placements of skipped optional fields taken out. It may be ``none``, may + place no secret field and may be literal only, but must still place every + field the connection holds. Args: data: The auth section as the template gives it. fields: Each field's name and whether it is secret, in template order. looks_secret: The host's detector for a value it holds or a known key shape. + optional: The names of the fields a member may leave out; each must be secret. + stored: Whether ``data`` is a connection's section, not a template's. Returns: The section rebuilt from what was checked, holding only its type's keys. @@ -348,15 +381,24 @@ def parse_auth( if not isinstance(data, dict): raise AuthRuleError("auth must be an object.") kind = data.get("type") - if not isinstance(kind, str) or kind not in AUTH_KEYS: - raise AuthRuleError(f"auth.type must be one of: {', '.join(sorted(AUTH_KEYS))}.") - _check_keys(data, AUTH_KEYS[kind], "auth") + stored_none = stored and kind == AUTH_NONE + if not stored_none and (not isinstance(kind, str) or kind not in AUTH_KEYS): + types = sorted({*AUTH_KEYS, AUTH_NONE} if stored else AUTH_KEYS) + raise AuthRuleError(f"auth.type must be one of: {', '.join(types)}.") + _check_keys(data, frozenset({"type"}) if stored_none else AUTH_KEYS[kind], "auth") declared = frozenset(name for name, _ in fields) - if kind == "header": - headers, placed = _parse_headers(data.get("headers"), declared, looks_secret) - canonical: dict[str, Any] = {"type": kind, "headers": headers} + secrets = {name for name, secret in fields if secret} + optional = frozenset(optional) + if not optional <= secrets: + raise AuthRuleError("An optional field must be a secret field the template declares.") + if stored_none: + placed: set[str] = set() + canonical: dict[str, Any] = {"type": kind} + elif kind == "header": + headers, placed = _parse_headers(data.get("headers"), declared, looks_secret, optional) + canonical = {"type": kind, "headers": headers} elif kind == "query": - params, placed = _parse_params(data.get("params"), declared, looks_secret) + params, placed = _parse_params(data.get("params"), declared, looks_secret, optional) canonical = {"type": kind, "params": params} else: username, placed = check_template(data.get("username"), "auth.username", declared, looks_secret=looks_secret) @@ -367,12 +409,91 @@ def parse_auth( password, in_password = check_template( data["password"], "auth.password", declared, may_be_empty=True, looks_secret=looks_secret ) + _check_basic_optional(placed, password, in_password, optional, secrets) placed |= in_password canonical = {"type": kind, "username": username, "password": password} - secrets = {name for name, secret in fields if secret} - if not placed & secrets: + # Basic is kept to a secret even stored, so no request carries an identity with an empty password. + if (not stored or kind == "basic") and not placed & secrets: raise AuthRuleError("auth must place a secret field, such as {api_key}.") unused = [i for i, (name, _) in enumerate(fields) if name not in placed] if unused: raise AuthRuleError(f"auth must place every field; fields[{unused[0]}] is never used.") return canonical + + +def _check_basic_optional( + in_username: set[str], password: str, in_password: set[str], optional: frozenset[str], secrets: set[str] +) -> None: + """Refuse a Basic section whose optional fields sit anywhere but the whole password. + + The username must place a required secret field whenever the password may + be skipped, so a keyless request never carries an identity with no password. + """ + if in_username & optional: + raise AuthRuleError("auth.username may not place an optional field; only the password may be optional.") + if not in_password & optional: + return + if len(in_password) > 1 or password != "{" + next(iter(in_password)) + "}": + raise AuthRuleError("auth.password must be only the optional field, with nothing around it.") + if not (in_username & secrets) - optional: + raise AuthRuleError("An optional auth.password needs a username that places a required secret field.") + + +def _check_drops_only_missing(placed: set[str], missing: set[str]) -> None: + """Refuse dropping a placement that also places a field the connection holds.""" + if placed & missing and placed - missing: + raise AuthRuleError("A placement of a missing field also places a field the connection holds.") + + +def without_missing(auth: Mapping[str, Any], held: Iterable[str], optional: Iterable[str]) -> dict[str, Any]: + """Take out of a template's auth section the placements of fields a connection does not hold. + + A header or parameter that places a missing field is dropped, and so + must place nothing else the connection holds. A missing + Basic password becomes empty, and a section left with no header or + parameter becomes ``none``. The result is the section ``parse_auth`` takes + with ``stored=True``. Computed once from the stored template, never from + a request. + + Args: + auth: The template's section as ``parse_auth`` returned it. + held: The names of the fields the connection holds. + optional: The names of the fields the template lets a member leave out. + + Returns: + A new section; ``auth`` is not changed. + + Raises: + AuthRuleError: when a missing field is not optional, a placement of a + missing field also places a held one, or the type is not one these + rules can apply. + """ + held = set(held) + optional = set(optional) + kind = auth["type"] + if kind == "basic": + names = set(PLACEHOLDER.findall(auth["username"])) | set(PLACEHOLDER.findall(auth["password"])) + elif kind in ("header", "query"): + key = "headers" if kind == "header" else "params" + names = {n for template in auth[key].values() for n in PLACEHOLDER.findall(template)} + elif kind == AUTH_NONE: + return {"type": AUTH_NONE} + else: + raise AuthRuleError("auth.type is not one these rules can apply.") + if names - held - optional: + raise AuthRuleError("A field that is not optional has no value.") + missing = names - held + if kind == "basic": + if set(PLACEHOLDER.findall(auth["username"])) & missing: + raise AuthRuleError("A field that is not optional has no value.") + in_password = set(PLACEHOLDER.findall(auth["password"])) + _check_drops_only_missing(in_password, missing) + password = "" if in_password & missing else auth["password"] + return {"type": kind, "username": auth["username"], "password": password} + kept = {} + for name, template in auth[key].items(): + placed = set(PLACEHOLDER.findall(template)) + _check_drops_only_missing(placed, missing) + if not placed & missing: + kept[name] = template + return {"type": kind, key: kept} if kept else {"type": AUTH_NONE} diff --git a/anton/core/tools/connector_draft.py b/anton/core/tools/connector_draft.py index 45094dde7..194980712 100644 --- a/anton/core/tools/connector_draft.py +++ b/anton/core/tools/connector_draft.py @@ -58,7 +58,7 @@ _TOP_KEYS = frozenset({"connector_id", "help_url", "fields", "check", "auth", *_TOP_TEXT_CAPS}) _FIELD_KEYS = frozenset({"name", "secret", "required", *_FIELD_TEXT_CAPS}) -_CHECK_KEYS = frozenset({"path"}) +_CHECK_KEYS = frozenset({"path", "public_path"}) _CHECK_PATH_MAX = 300 @@ -74,7 +74,9 @@ class ConnectorCheckError(ConnectorDraftError): @dataclass(frozen=True) class ConnectorDraftField: - """One credential field the member fills in; it describes, never holds, a value.""" + """One credential field the member fills in; it describes, never holds, a value. + + ``required`` is false only for a secret field the member may leave out.""" name: str label: str @@ -87,13 +89,20 @@ class ConnectorDraftField: @dataclass(frozen=True) class ConnectorDraftCheck: """How to test the credentials: one GET of ``path`` on the address the - member types, carrying the template's ``auth``.""" + member types, carrying the template's ``auth``. + + ``public_path`` is for a member who skipped every optional key: one GET + that the API answers without credentials. Set only when no secret field + is required.""" path: str + public_path: str | None = None def to_dict(self) -> dict[str, Any]: - """The check as JSON-ready data.""" - return {"path": self.path} + """The check as JSON-ready data, with ``public_path`` only when set.""" + if self.public_path is None: + return {"path": self.path} + return {"path": self.path, "public_path": self.public_path} @dataclass(frozen=True) @@ -283,27 +292,27 @@ def _check_help_url(value: Any) -> str | None: return text -def _check_path(value: Any) -> str: - """Return the check's path: an absolute path with an optional query, never a host. +def _check_path(value: Any, where: str = "check.path") -> str: + """Return a check's path: an absolute path with an optional query, never a host. A path the request URL could read as naming another host (``//``, ``\\``, a ``.`` or ``..`` segment) is refused, and so is anything a placeholder could reach: a value never goes into the URL. ``%`` is refused too, so an encoded value cannot pass the token rule. """ - text = _check_text(value, "check.path", _CHECK_PATH_MAX, long_text=False) + text = _check_text(value, where, _CHECK_PATH_MAX, long_text=False) if text is None: - raise ConnectorDraftError("check.path is required.") + raise ConnectorDraftError(f"{where} is required.") if ( not text.startswith("/") or "//" in text or not is_printable_ascii(text, space=False) or any(c in text for c in "\\#{}%") ): - raise ConnectorDraftError("check.path must be a path from the host, with any version, such as /v2/me, and no host.") + raise ConnectorDraftError(f"{where} must be a path from the host, with any version, such as /v2/me, and no host.") segments = text.split("?", 1)[0].split("/") if any(segment in (".", "..") for segment in segments): - raise ConnectorDraftError("check.path must not have . or .. segments.") + raise ConnectorDraftError(f"{where} must not have . or .. segments.") return text @@ -315,7 +324,12 @@ def _parse_auth(data: Any, fields: tuple[ConnectorDraftField, ...]) -> Connector it, with the scrubber as its secret detector. """ try: - canonical = rules.parse_auth(data, [(f.name, f.secret) for f in fields], _scrubbed) + canonical = rules.parse_auth( + data, + [(f.name, f.secret) for f in fields], + _scrubbed, + optional=frozenset(f.name for f in fields if not f.required), + ) except rules.AuthRuleError as e: raise ConnectorDraftError(str(e)) from e return ConnectorDraftAuth( @@ -327,11 +341,13 @@ def _parse_auth(data: Any, fields: tuple[ConnectorDraftField, ...]) -> Connector ) -def _parse_check(data: Any, auth: ConnectorDraftAuth) -> ConnectorDraftCheck | None: +def _parse_check(data: Any, auth: ConnectorDraftAuth, fields: tuple[ConnectorDraftField, ...]) -> ConnectorDraftCheck | None: """Parse the optional ``check``, or return None when absent. - For a ``query`` template the path may not carry a parameter the template - places, or the check would send the key under two values. + For a ``query`` template a path may not carry a parameter the template + places, or the check would send the key under two values. A member can + connect without any key only when every secret field is optional, so + only then is ``public_path`` required, and otherwise it is refused. """ if data is None: return None @@ -342,9 +358,30 @@ def _parse_check(data: Any, auth: ConnectorDraftAuth) -> ConnectorDraftCheck | N path = _check_path(data.get("path")) except ConnectorDraftError as e: raise ConnectorCheckError(str(e)) from e + _check_no_collision(path, auth, "check.path") + keyless_possible = any(not f.required for f in fields) and all(not f.required for f in fields if f.secret) + public_path = data.get("public_path") + if not keyless_possible: + if public_path is not None: + raise ConnectorDraftError( + "check.public_path is only for a template whose every secret field is optional." + ) + return ConnectorDraftCheck(path=path) + if public_path is None: + raise ConnectorDraftError( + "check.public_path is required: the template has optional keys, so give a path that answers without one." + ) + public_path = _check_path(public_path, "check.public_path") + if public_path == path: + raise ConnectorDraftError("check.public_path must differ from check.path.") + _check_no_collision(public_path, auth, "check.public_path") + return ConnectorDraftCheck(path=path, public_path=public_path) + + +def _check_no_collision(path: str, auth: ConnectorDraftAuth, where: str) -> None: + """Refuse a path whose query carries a parameter name the template's auth places.""" if rules.query_collides(auth.to_dict(), rules.query_names(urlsplit(path).query)): - raise ConnectorDraftError("check.path may carry only plain parameter names, none of them one auth places.") - return ConnectorDraftCheck(path=path) + raise ConnectorDraftError(f"{where} may carry only plain parameter names, none of them one auth places.") def _parse_field(data: Any, index: int) -> ConnectorDraftField: @@ -368,14 +405,16 @@ def _parse_field(data: Any, index: int) -> ConnectorDraftField: } if texts["label"] is None: raise ConnectorDraftError(f"{where}.label is required.") - # auth places every field on every request, so a field left blank would send an empty value. - if not _check_bool(data.get("required"), f"{where}.required", True): - raise ConnectorDraftError(f"{where}.required must be true: every field goes on a request.") + secret = _check_bool(data.get("secret"), f"{where}.secret", True) + required = _check_bool(data.get("required"), f"{where}.required", True) + # A skipped field is dropped from the request, which only a key can be. + if not required and not secret: + raise ConnectorDraftError(f"{where}.required may be false only on a secret field.") return ConnectorDraftField( name=name, label=texts["label"], - secret=_check_bool(data.get("secret"), f"{where}.secret", True), - required=True, + secret=secret, + required=required, placeholder=texts["placeholder"], help=texts["help"], ) @@ -423,7 +462,7 @@ def parse_connector_draft(data: Any) -> ConnectorDraft: category=texts["category"], help_url=_check_help_url(data.get("help_url")), usage_notes=texts["usage_notes"], - check=_parse_check(data.get("check"), auth), + check=_parse_check(data.get("check"), auth, fields), ) @@ -452,7 +491,7 @@ def drain(self) -> list[dict[str, Any]]: _NO_CONNECTOR_CASES = ( - "If an API takes no key or token, do not build a connector: call it directly " + "If an API takes no key or token at all, do not build a connector: call it directly " "from code. If it has no GET that answers only with valid credentials, it " "cannot be a custom connector yet: tell the user so." ) @@ -468,6 +507,10 @@ def drain(self) -> list[dict[str, Any]]: "password such as {email}/token and {api_token}, or type 'query' with " "the URL parameters that carry the key, such as access_key: {api_key}; " "{field_name} places a field's value and every field must be placed. " + "Mark a key required: false only when the provider documents public " + "access without it. When every key is optional, also give " + "check.public_path, a GET that answers without a key; path still " + "answers only with one. With any key required, leave public_path out. " "The user types only the API's host when connecting (such as " "api.example.com), so leave it out, and start every path at the host: " "include any version the provider's docs put after the host " @@ -515,8 +558,10 @@ def drain(self) -> list[dict[str, Any]]: "secret": {"type": "boolean", "description": "Mask the input. Defaults to true."}, "required": { "type": "boolean", - "enum": [True], - "description": "Must be true or left out: auth sends every field on a request.", + "description": ( + "Defaults to true. Set false only on a secret key the provider documents " + "public access without. Give check.public_path only when every key is optional." + ), }, "placeholder": _TEXT, "help": {"type": "string", "description": "Where the user finds this value."}, @@ -576,6 +621,13 @@ def drain(self) -> list[dict[str, Any]]: "required": ["path"], "additionalProperties": False, } +_INPUT_SCHEMA["properties"]["check"]["properties"]["public_path"] = { + "type": "string", + "description": ( + "Only when every key is required: false. A GET path, from the host as above, that the API " + "answers with 200 without any key, used when the user skips the key. It must differ from path." + ), +} _CHECK_REQUIRED = ( diff --git a/tests/fixtures/auth_section_cases.json b/tests/fixtures/auth_section_cases.json index e07cd8ec7..13035d639 100644 --- a/tests/fixtures/auth_section_cases.json +++ b/tests/fixtures/auth_section_cases.json @@ -892,6 +892,519 @@ true ] ] + }, + { + "accepted": true, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}" + }, + "type": "header" + }, + "fields": [ + [ + "api_key", + true + ] + ], + "optional": [ + "api_key" + ], + "result": { + "headers": { + "Authorization": "Bearer {api_key}" + }, + "type": "header" + } + }, + { + "accepted": true, + "auth": { + "params": { + "access_key": "{api_key}" + }, + "type": "query" + }, + "fields": [ + [ + "api_key", + true + ] + ], + "optional": [ + "api_key" + ], + "result": { + "params": { + "access_key": "{api_key}" + }, + "type": "query" + } + }, + { + "accepted": true, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}", + "X-Account": "{account}" + }, + "type": "header" + }, + "fields": [ + [ + "api_key", + true + ], + [ + "account", + false + ] + ], + "optional": [ + "api_key" + ], + "result": { + "headers": { + "Authorization": "Bearer {api_key}", + "X-Account": "{account}" + }, + "type": "header" + } + }, + { + "accepted": false, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}.{account}" + }, + "type": "header" + }, + "error": "auth.headers[0] places an optional field with another field; give it a place of its own.", + "fields": [ + [ + "api_key", + true + ], + [ + "account", + false + ] + ], + "optional": [ + "api_key" + ] + }, + { + "accepted": false, + "auth": { + "params": { + "k": "{api_key}{token}" + }, + "type": "query" + }, + "error": "auth.params[0] places an optional field with another field; give it a place of its own.", + "fields": [ + [ + "api_key", + true + ], + [ + "token", + true + ] + ], + "optional": [ + "api_key" + ] + }, + { + "accepted": false, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}" + }, + "type": "header" + }, + "error": "An optional field must be a secret field the template declares.", + "fields": [ + [ + "api_key", + true + ], + [ + "account", + false + ] + ], + "optional": [ + "account" + ] + }, + { + "accepted": false, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}" + }, + "type": "header" + }, + "error": "An optional field must be a secret field the template declares.", + "fields": [ + [ + "api_key", + true + ] + ], + "optional": [ + "missing" + ] + }, + { + "accepted": true, + "auth": { + "password": "{password}", + "type": "basic", + "username": "{email}" + }, + "fields": [ + [ + "email", + true + ], + [ + "password", + true + ] + ], + "optional": [ + "password" + ], + "result": { + "password": "{password}", + "type": "basic", + "username": "{email}" + } + }, + { + "accepted": false, + "auth": { + "password": "{password}", + "type": "basic", + "username": "{email}" + }, + "error": "auth.username may not place an optional field; only the password may be optional.", + "fields": [ + [ + "email", + true + ], + [ + "password", + true + ] + ], + "optional": [ + "email" + ] + }, + { + "accepted": false, + "auth": { + "password": "{password}", + "type": "basic", + "username": "{email}" + }, + "error": "An optional auth.password needs a username that places a required secret field.", + "fields": [ + [ + "email", + false + ], + [ + "password", + true + ] + ], + "optional": [ + "password" + ] + }, + { + "accepted": false, + "auth": { + "password": "{password}{tail}", + "type": "basic", + "username": "{user}" + }, + "error": "auth.password must be only the optional field, with nothing around it.", + "fields": [ + [ + "user", + true + ], + [ + "password", + true + ], + [ + "tail", + true + ] + ], + "optional": [ + "password" + ] + }, + { + "accepted": false, + "auth": { + "type": "none" + }, + "error": "auth.type must be one of: basic, header, query.", + "fields": [ + [ + "api_key", + true + ] + ] + }, + { + "accepted": true, + "auth": { + "type": "none" + }, + "fields": [], + "result": { + "type": "none" + }, + "stored": true + }, + { + "accepted": false, + "auth": { + "type": "none" + }, + "error": "auth must place every field; fields[0] is never used.", + "fields": [ + [ + "api_key", + true + ] + ], + "stored": true + }, + { + "accepted": false, + "auth": { + "headers": {}, + "type": "none" + }, + "error": "auth has a key that is not allowed. Allowed keys: type.", + "fields": [ + [ + "base", + false + ] + ], + "stored": true + }, + { + "accepted": true, + "auth": { + "headers": { + "Notion-Version": "2022-06-28" + }, + "type": "header" + }, + "fields": [], + "result": { + "headers": { + "Notion-Version": "2022-06-28" + }, + "type": "header" + }, + "stored": true + }, + { + "accepted": true, + "auth": { + "params": { + "format": "json" + }, + "type": "query" + }, + "fields": [], + "result": { + "params": { + "format": "json" + }, + "type": "query" + }, + "stored": true + }, + { + "accepted": false, + "auth": { + "headers": { + "Notion-Version": "2022-06-28" + }, + "type": "header" + }, + "error": "auth must place every field; fields[0] is never used.", + "fields": [ + [ + "api_key", + true + ] + ], + "stored": true + }, + { + "accepted": true, + "auth": { + "headers": { + "X-Account": "{account}" + }, + "type": "header" + }, + "fields": [ + [ + "account", + false + ] + ], + "result": { + "headers": { + "X-Account": "{account}" + }, + "type": "header" + }, + "stored": true + }, + { + "accepted": false, + "auth": { + "password": "", + "type": "basic", + "username": "{email}" + }, + "error": "auth.username names a field the draft does not declare.", + "fields": [], + "stored": true + }, + { + "accepted": false, + "auth": { + "password": "", + "type": "basic", + "username": "{email}" + }, + "error": "auth must place a secret field, such as {api_key}.", + "fields": [ + [ + "email", + false + ] + ], + "stored": true + }, + { + "accepted": false, + "auth": { + "type": "oauth" + }, + "error": "auth.type must be one of: basic, header, none, query.", + "fields": [], + "stored": true + }, + { + "accepted": false, + "auth": { + "headers": { + "Notion-Version": "2022-06-28" + }, + "type": "header" + }, + "error": "auth must place a secret field, such as {api_key}.", + "fields": [ + [ + "api_key", + true + ] + ] + }, + { + "accepted": true, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}" + }, + "type": "header" + }, + "fields": [ + [ + "api_key", + true + ] + ], + "result": { + "headers": { + "Authorization": "Bearer {api_key}" + }, + "type": "header" + }, + "stored": true + }, + { + "accepted": true, + "auth": { + "password": "", + "type": "basic", + "username": "{email}" + }, + "fields": [ + [ + "email", + true + ] + ], + "result": { + "password": "", + "type": "basic", + "username": "{email}" + }, + "stored": true + }, + { + "accepted": true, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}", + "X-Account": "{account}" + }, + "type": "header" + }, + "fields": [ + [ + "api_key", + true + ], + [ + "account", + false + ] + ], + "optional": [ + "api_key" + ], + "result": { + "headers": { + "Authorization": "Bearer {api_key}", + "X-Account": "{account}" + }, + "type": "header" + }, + "stored": true } ], "query_collides": [ @@ -1369,6 +1882,318 @@ }, "error": "auth.type is not one these rules can apply.", "values": {} + }, + { + "accepted": true, + "auth": { + "type": "none" + }, + "result": [ + {}, + [] + ], + "values": {} + }, + { + "accepted": true, + "auth": { + "type": "none" + }, + "result": [ + {}, + [] + ], + "values": { + "api_key": "k0" + } + } + ], + "without_missing": [ + { + "accepted": true, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}" + }, + "type": "header" + }, + "held": [ + "api_key" + ], + "optional": [ + "api_key" + ], + "result": { + "headers": { + "Authorization": "Bearer {api_key}" + }, + "type": "header" + } + }, + { + "accepted": true, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}" + }, + "type": "header" + }, + "held": [], + "optional": [ + "api_key" + ], + "result": { + "type": "none" + } + }, + { + "accepted": false, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}" + }, + "type": "header" + }, + "error": "A field that is not optional has no value.", + "held": [], + "optional": [] + }, + { + "accepted": true, + "auth": { + "params": { + "access_key": "{api_key}" + }, + "type": "query" + }, + "held": [], + "optional": [ + "api_key" + ], + "result": { + "type": "none" + } + }, + { + "accepted": true, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}", + "Notion-Version": "2022-06-28" + }, + "type": "header" + }, + "held": [], + "optional": [ + "api_key" + ], + "result": { + "headers": { + "Notion-Version": "2022-06-28" + }, + "type": "header" + } + }, + { + "accepted": true, + "auth": { + "params": { + "access_key": "{api_key}", + "format": "json" + }, + "type": "query" + }, + "held": [], + "optional": [ + "api_key" + ], + "result": { + "params": { + "format": "json" + }, + "type": "query" + } + }, + { + "accepted": true, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}", + "X-Account": "{account}" + }, + "type": "header" + }, + "held": [ + "account" + ], + "optional": [ + "api_key" + ], + "result": { + "headers": { + "X-Account": "{account}" + }, + "type": "header" + } + }, + { + "accepted": false, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}", + "X-Account": "{account}" + }, + "type": "header" + }, + "error": "A field that is not optional has no value.", + "held": [ + "api_key" + ], + "optional": [ + "api_key" + ] + }, + { + "accepted": true, + "auth": { + "headers": { + "Authorization": "Bearer {api_key}", + "X-Account": "{account}" + }, + "type": "header" + }, + "held": [ + "api_key" + ], + "optional": [ + "api_key", + "account" + ], + "result": { + "headers": { + "Authorization": "Bearer {api_key}" + }, + "type": "header" + } + }, + { + "accepted": true, + "auth": { + "password": "{password}", + "type": "basic", + "username": "{email}" + }, + "held": [ + "email" + ], + "optional": [ + "password" + ], + "result": { + "password": "", + "type": "basic", + "username": "{email}" + } + }, + { + "accepted": true, + "auth": { + "password": "{password}", + "type": "basic", + "username": "{email}" + }, + "held": [ + "email", + "password" + ], + "optional": [ + "password" + ], + "result": { + "password": "{password}", + "type": "basic", + "username": "{email}" + } + }, + { + "accepted": false, + "auth": { + "password": "{password}", + "type": "basic", + "username": "{email}" + }, + "error": "A field that is not optional has no value.", + "held": [ + "password" + ], + "optional": [ + "password" + ] + }, + { + "accepted": false, + "auth": { + "password": "{password}", + "type": "basic", + "username": "{email}" + }, + "error": "A field that is not optional has no value.", + "held": [ + "email" + ], + "optional": [] + }, + { + "accepted": true, + "auth": { + "type": "none" + }, + "held": [], + "optional": [], + "result": { + "type": "none" + } + }, + { + "accepted": false, + "auth": { + "type": "oauth" + }, + "error": "auth.type is not one these rules can apply.", + "held": [], + "optional": [] + }, + { + "accepted": false, + "auth": { + "password": "{password}", + "type": "basic", + "username": "{email}" + }, + "error": "A field that is not optional has no value.", + "held": [ + "password" + ], + "optional": [ + "email", + "password" + ] + }, + { + "accepted": false, + "auth": { + "headers": { + "A": "{acct}-{api_key}" + }, + "type": "header" + }, + "error": "A placement of a missing field also places a field the connection holds.", + "held": [ + "acct" + ], + "optional": [ + "api_key" + ] } ] } diff --git a/tests/test_connector_auth_rules.py b/tests/test_connector_auth_rules.py index 61ac2989c..6268652bc 100644 --- a/tests/test_connector_auth_rules.py +++ b/tests/test_connector_auth_rules.py @@ -17,10 +17,17 @@ import pytest -from anton.core.tools.connector_auth_rules import AuthRuleError, parse_auth, query_collides, query_names, render +from anton.core.tools.connector_auth_rules import ( + AuthRuleError, + parse_auth, + query_collides, + query_names, + render, + without_missing, +) _MODULE = Path(__file__).resolve().parents[1] / "anton" / "core" / "tools" / "connector_auth_rules.py" -_MODULE_SHA256 = "a74acd12e07e275effa6e9dbf0aac6c5b0eeba69aeaf05fbf0372978dcc22873" +_MODULE_SHA256 = "e6d4db34127c0ca1565ec4a3f21f3ae57075d0c27a122e378aa10c4eb248b75d" #: Copies to update, and the hash their tests pin, whenever the module changes. _COPIES = ( "auth: auth/datavault/connector_auth_rules.py", @@ -48,7 +55,7 @@ def test_the_module_hash_is_pinned_so_its_copies_are_resynced(): _CASES = Path(__file__).parent / "fixtures" / "auth_section_cases.json" -_CASES_SHA256 = "a5ad27ce4ef1239d5f2f2110b8cfabcd34aa2cde5cc2535b2ce7b3a920e1e9a0" +_CASES_SHA256 = "c541a8e0b516371a71c683b910a5146e0cc4c8de5e4456ec5088ea5d1336ed76" #: Rewrites the case list after a rule change; copy the result to every service that carries the module. _REGENERATE = ( "uv run python -c \"from tests.test_connector_auth_rules import _CASES, _cases_text; " @@ -116,6 +123,61 @@ def test_the_module_hash_is_pinned_so_its_copies_are_resynced(): (_KEY, {"headers": {"X-Api-Key": "{api_key}"}}), (_KEY, {"type": "oauth"}), ] +_OPT_KEY = [["api_key", True]] +_OPT_ACCOUNT = [["api_key", True], ["account", False]] +_OPT_BASIC = [["email", True], ["password", True]] +_BEARER = {"type": "header", "headers": {"Authorization": "Bearer {api_key}"}} +_LITERAL = {"type": "header", "headers": {"Notion-Version": "2022-06-28"}} +#: (fields, auth, optional names, stored) for parse_auth with the optional rules; a case +#: records ``optional`` and ``stored`` only when set, so the cases above keep their shape. +_PARSE_OPTIONAL_INPUTS = [ + (_OPT_KEY, _BEARER, ["api_key"], False), + (_OPT_KEY, _QUERY, ["api_key"], False), + (_OPT_ACCOUNT, {"type": "header", "headers": {"Authorization": "Bearer {api_key}", "X-Account": "{account}"}}, ["api_key"], False), + (_OPT_ACCOUNT, {"type": "header", "headers": {"Authorization": "Bearer {api_key}.{account}"}}, ["api_key"], False), + ([["api_key", True], ["token", True]], {"type": "query", "params": {"k": "{api_key}{token}"}}, ["api_key"], False), + (_OPT_ACCOUNT, _BEARER, ["account"], False), + (_OPT_KEY, _BEARER, ["missing"], False), + ([["email", True], ["password", True]], {"type": "basic", "username": "{email}", "password": "{password}"}, ["password"], False), + ([["email", True], ["password", True]], {"type": "basic", "username": "{email}", "password": "{password}"}, ["email"], False), + ([["email", False], ["password", True]], {"type": "basic", "username": "{email}", "password": "{password}"}, ["password"], False), + ([["user", True], ["password", True], ["tail", True]], {"type": "basic", "username": "{user}", "password": "{password}{tail}"}, ["password"], False), + (_OPT_KEY, {"type": "none"}, [], False), + ([], {"type": "none"}, [], True), + (_OPT_KEY, {"type": "none"}, [], True), + ([["base", False]], {"type": "none", "headers": {}}, [], True), + ([], _LITERAL, [], True), + ([], {"type": "query", "params": {"format": "json"}}, [], True), + (_OPT_KEY, _LITERAL, [], True), + ([["account", False]], {"type": "header", "headers": {"X-Account": "{account}"}}, [], True), + ([], {"type": "basic", "username": "{email}", "password": ""}, [], True), + ([["email", False]], {"type": "basic", "username": "{email}", "password": ""}, [], True), + ([], {"type": "oauth"}, [], True), + (_KEY, _LITERAL, [], False), + (_OPT_KEY, _BEARER, [], True), + ([["email", True]], {"type": "basic", "username": "{email}", "password": ""}, [], True), + (_OPT_ACCOUNT, {"type": "header", "headers": {"Authorization": "Bearer {api_key}", "X-Account": "{account}"}}, ["api_key"], True), +] +#: (auth, held names, optional names) for without_missing. +_WITHOUT_MISSING_INPUTS = [ + (_BEARER, ["api_key"], ["api_key"]), + (_BEARER, [], ["api_key"]), + (_BEARER, [], []), + (_QUERY, [], ["api_key"]), + ({"type": "header", "headers": {"Authorization": "Bearer {api_key}", "Notion-Version": "2022-06-28"}}, [], ["api_key"]), + ({"type": "query", "params": {"access_key": "{api_key}", "format": "json"}}, [], ["api_key"]), + ({"type": "header", "headers": {"Authorization": "Bearer {api_key}", "X-Account": "{account}"}}, ["account"], ["api_key"]), + ({"type": "header", "headers": {"Authorization": "Bearer {api_key}", "X-Account": "{account}"}}, ["api_key"], ["api_key"]), + ({"type": "header", "headers": {"Authorization": "Bearer {api_key}", "X-Account": "{account}"}}, ["api_key"], ["api_key", "account"]), + ({"type": "basic", "username": "{email}", "password": "{password}"}, ["email"], ["password"]), + ({"type": "basic", "username": "{email}", "password": "{password}"}, ["email", "password"], ["password"]), + ({"type": "basic", "username": "{email}", "password": "{password}"}, ["password"], ["password"]), + ({"type": "basic", "username": "{email}", "password": "{password}"}, ["email"], []), + ({"type": "none"}, [], []), + ({"type": "oauth"}, [], []), + ({"type": "basic", "username": "{email}", "password": "{password}"}, ["password"], ["email", "password"]), + ({"type": "header", "headers": {"A": "{acct}-{api_key}"}}, ["acct"], ["api_key"]), +] #: (auth, values) pairs for render. _RENDER_INPUTS = [ ({"type": "header", "headers": {"Authorization": "Bearer {token}", "Notion-Version": "2022-06-28"}}, {"token": "t0"}), @@ -128,6 +190,8 @@ def test_the_module_hash_is_pinned_so_its_copies_are_resynced(): ({"type": "query", "params": {"access_key": "{api_key}"}}, {"api_key": "k0\x85"}), ({"type": "header", "headers": {"X-Api-Key": "{api_key}"}}, {"api_key": "k0
"}), ({"type": "oauth"}, {}), + ({"type": "none"}, {}), + ({"type": "none"}, {"api_key": "k0"}), ] #: Raw query strings for query_names. _QUERY_NAME_INPUTS = ["a=1&access_key=2", "a=1;access_key=2", "access%5Fkey=2&b", "access+key=2", ""] @@ -152,12 +216,33 @@ def _outcome(call) -> dict: return {"accepted": False, "error": str(e)} +def _parse_optional_case(fields: list, auth: object, optional: list[str], stored: bool) -> dict: + """One parse_auth case run with the optional and stored rules, recording only what is set.""" + kwargs: dict = {} + case: dict = {"fields": fields, "auth": auth} + if optional: + kwargs["optional"] = frozenset(optional) + case["optional"] = optional + if stored: + kwargs["stored"] = True + case["stored"] = True + return {**case, **_outcome(lambda: parse_auth(auth, [tuple(x) for x in fields], **kwargs))} + + def _build_cases() -> dict[str, list[dict]]: """Run every input through the module with no secret detector, as each copy will.""" return { "parse_auth": [ {"fields": fields, "auth": auth, **_outcome(lambda f=fields, a=auth: parse_auth(a, [tuple(x) for x in f]))} for fields, auth in _PARSE_INPUTS + ] + + [_parse_optional_case(fields, auth, optional, stored) for fields, auth, optional, stored in _PARSE_OPTIONAL_INPUTS], + "without_missing": [ + { + "auth": auth, "held": held, "optional": optional, + **_outcome(lambda a=auth, h=held, o=optional: without_missing(a, h, o)), + } + for auth, held, optional in _WITHOUT_MISSING_INPUTS ], "render": [ {"auth": auth, "values": values, **_outcome(lambda a=auth, v=values: list(render(a, v)))} @@ -188,6 +273,11 @@ def test_the_auth_section_cases_cover_both_outcomes_for_each_function(): outcomes = {c["accepted"] for c in cases["parse_auth"] if isinstance(c["auth"], dict) and c["auth"].get("type") == kind} assert outcomes == {True, False} assert {c["accepted"] for c in cases["render"]} == {True, False} + assert {c["accepted"] for c in cases["without_missing"]} == {True, False} + stored = [c for c in cases["parse_auth"] if c.get("stored")] + assert {c["accepted"] for c in stored} == {True, False} + optional = [c for c in cases["parse_auth"] if c.get("optional")] + assert {c["accepted"] for c in optional} == {True, False} assert {c["collides"] for c in cases["query_collides"]} == {True, False} @@ -270,3 +360,180 @@ def test_the_module_loads_with_the_standard_library_alone(): loaded = json.loads(result.stdout) top_level = {name.split(".")[0] for name in loaded} assert top_level <= set(sys.stdlib_module_names) | {"connector_auth_rules"} + + +def _stored(auth, fields, **kwargs): + return parse_auth(auth, [tuple(x) for x in fields], stored=True, **kwargs) + + +def test_an_optional_key_placed_alone_is_accepted_in_a_template(): + assert parse_auth(_BEARER, [("api_key", True)], optional=frozenset({"api_key"})) == _BEARER + + +def test_a_template_with_no_optional_field_behaves_as_before(): + assert parse_auth(_BEARER, [("api_key", True)], optional=frozenset()) == _BEARER + with pytest.raises(AuthRuleError, match="must place a secret field"): + parse_auth(_LITERAL, []) + + +def test_an_optional_field_must_be_a_declared_secret_field(): + with pytest.raises(AuthRuleError, match="optional field must be a secret"): + parse_auth(_BEARER, [("api_key", True), ("account", False)], optional=frozenset({"account"})) + with pytest.raises(AuthRuleError, match="optional field must be a secret"): + parse_auth(_BEARER, [("api_key", True)], optional=frozenset({"missing"})) + + +def test_an_optional_field_sharing_a_header_or_parameter_is_refused(): + shared = {"type": "header", "headers": {"Authorization": "Bearer {api_key}.{account}"}} + with pytest.raises(AuthRuleError, match=r"auth\.headers\[0\] places an optional field with another"): + parse_auth(shared, [("api_key", True), ("account", False)], optional=frozenset({"api_key"})) + query = {"type": "query", "params": {"k": "{api_key}{token}"}} + with pytest.raises(AuthRuleError, match=r"auth\.params\[0\] places an optional field with another"): + parse_auth(query, [("api_key", True), ("token", True)], optional=frozenset({"api_key"})) + + +def test_a_basic_username_may_not_be_optional(): + auth = {"type": "basic", "username": "{email}", "password": "{password}"} + with pytest.raises(AuthRuleError, match="only the password may be optional"): + parse_auth(auth, [("email", True), ("password", True)], optional=frozenset({"email"})) + + +def test_a_basic_password_is_optional_only_as_the_whole_password_beside_a_required_secret_username(): + auth = {"type": "basic", "username": "{email}", "password": "{password}"} + fields = [("email", True), ("password", True)] + assert parse_auth(auth, fields, optional=frozenset({"password"})) == auth + wrapped = {"type": "basic", "username": "{user}", "password": "{password}{tail}"} + with pytest.raises(AuthRuleError, match="only the optional field"): + parse_auth(wrapped, [("user", True), ("password", True), ("tail", True)], optional=frozenset({"password"})) + with pytest.raises(AuthRuleError, match="needs a username that places a required secret"): + parse_auth(auth, [("email", False), ("password", True)], optional=frozenset({"password"})) + + +def test_a_template_may_not_be_none_and_the_type_list_never_offers_it(): + with pytest.raises(AuthRuleError, match=r"must be one of: basic, header, query\.$"): + parse_auth({"type": "none"}, []) + + +def test_a_stored_section_may_be_none_when_the_connection_holds_no_field_it_places(): + assert _stored({"type": "none"}, []) == {"type": "none"} + + +def test_a_stored_none_that_leaves_out_a_held_field_is_refused(): + with pytest.raises(AuthRuleError, match="must place every field"): + _stored({"type": "none"}, [["api_key", True]]) + + +def test_a_stored_none_holds_no_other_key(): + with pytest.raises(AuthRuleError, match="key that is not allowed"): + _stored({"type": "none", "headers": {}}, []) + + +def test_a_stored_section_need_not_place_a_secret_or_any_field(): + assert _stored(_LITERAL, []) == _LITERAL + account = {"type": "header", "headers": {"X-Account": "{account}"}} + assert _stored(account, [["account", False]]) == account + + +def test_a_stored_section_must_still_place_every_held_field(): + with pytest.raises(AuthRuleError, match="must place every field"): + _stored(_LITERAL, [["api_key", True]]) + + +def test_stored_mode_still_refuses_an_unknown_type(): + with pytest.raises(AuthRuleError, match="auth.type must be one of"): + _stored({"type": "oauth"}, []) + + +def test_render_of_none_sends_nothing_even_when_values_exist(): + assert render({"type": "none"}, {"api_key": "k0"}) == ({}, []) + + +def test_without_missing_keeps_a_section_whose_fields_are_all_held(): + assert without_missing(_BEARER, ["api_key"], ["api_key"]) == _BEARER + + +def test_without_missing_drops_the_header_of_a_skipped_field(): + auth = {"type": "header", "headers": {"Authorization": "Bearer {api_key}", "X-Account": "{account}"}} + + assert without_missing(auth, ["account"], ["api_key"]) == {"type": "header", "headers": {"X-Account": "{account}"}} + + +def test_without_missing_drops_the_parameter_of_a_skipped_field_and_keeps_a_literal_one(): + auth = {"type": "query", "params": {"access_key": "{api_key}", "format": "json"}} + + assert without_missing(auth, [], ["api_key"]) == {"type": "query", "params": {"format": "json"}} + + +def test_without_missing_keeps_a_literal_header_beside_a_dropped_one(): + auth = {"type": "header", "headers": {"Authorization": "Bearer {api_key}", "Notion-Version": "2022-06-28"}} + + assert without_missing(auth, [], ["api_key"]) == _LITERAL + + +def test_without_missing_gives_none_when_nothing_is_left_to_send(): + assert without_missing(_BEARER, [], ["api_key"]) == {"type": "none"} + assert without_missing(_QUERY, [], ["api_key"]) == {"type": "none"} + + +def test_without_missing_empties_a_skipped_basic_password(): + auth = {"type": "basic", "username": "{email}", "password": "{password}"} + + assert without_missing(auth, ["email"], ["password"]) == {"type": "basic", "username": "{email}", "password": ""} + + +def test_without_missing_refuses_a_missing_field_that_is_not_optional(): + with pytest.raises(AuthRuleError, match="not optional"): + without_missing(_BEARER, [], []) + basic = {"type": "basic", "username": "{email}", "password": "{password}"} + with pytest.raises(AuthRuleError, match="not optional"): + without_missing(basic, ["password"], ["password"]) + + +def test_without_missing_does_not_change_its_input(): + auth = {"type": "header", "headers": {"Authorization": "Bearer {api_key}", "Notion-Version": "2022-06-28"}} + + without_missing(auth, [], ["api_key"]) + + assert auth["headers"]["Authorization"] == "Bearer {api_key}" + + +def test_what_without_missing_gives_is_a_valid_stored_section(): + auth = {"type": "header", "headers": {"Authorization": "Bearer {api_key}", "X-Account": "{account}"}} + fields = [("api_key", True), ("account", False)] + for held in (["account"], ["api_key", "account"]): + reduced = without_missing(auth, held, ["api_key"]) + assert parse_auth(reduced, [f for f in fields if f[0] in held], stored=True) == reduced + + +def test_a_stored_basic_section_must_place_a_secret_field(): + auth = {"type": "basic", "username": "{email}", "password": ""} + with pytest.raises(AuthRuleError, match="must place a secret field"): + _stored(auth, [["email", False]]) + assert _stored(auth, [["email", True]]) == auth + + +def test_a_stored_type_error_lists_none_and_a_template_one_does_not(): + with pytest.raises(AuthRuleError, match="basic, header, none, query"): + _stored({"type": "oauth"}, []) + with pytest.raises(AuthRuleError) as exc: + parse_auth({"type": "oauth"}, []) + assert "none" not in str(exc.value) + + +def test_a_stored_keyed_section_still_parses(): + assert _stored(_BEARER, [["api_key", True]]) == _BEARER + + +def test_without_missing_refuses_a_missing_username_even_when_the_password_is_held(): + auth = {"type": "basic", "username": "{email}", "password": "{password}"} + with pytest.raises(AuthRuleError, match="not optional"): + without_missing(auth, ["password"], ["email", "password"]) + + +@pytest.mark.parametrize("auth,held,optional", [ + ({"type": "header", "headers": {"A": "{acct}-{api_key}"}}, ["acct"], ["api_key"]), + ({"type": "query", "params": {"a": "{acct}{api_key}"}}, ["acct"], ["api_key"]), +]) +def test_without_missing_refuses_to_drop_a_placement_that_also_places_a_held_field(auth, held, optional): + with pytest.raises(AuthRuleError, match="also places a field the connection holds"): + without_missing(auth, held, optional) diff --git a/tests/test_connector_draft.py b/tests/test_connector_draft.py index b28ce40d3..8d4e8b7f7 100644 --- a/tests/test_connector_draft.py +++ b/tests/test_connector_draft.py @@ -176,10 +176,10 @@ def test_a_boolean_must_be_a_boolean(): parse_connector_draft(_draft(fields=[{"name": "k", "label": "K", "required": "false"}])) -def test_an_optional_field_is_refused_since_auth_sends_every_field(): +def test_an_optional_field_that_is_not_secret_is_refused(): fields = [{"name": "api_key", "label": "Key"}, {"name": "region", "label": "Region", "secret": False, "required": False}] - with pytest.raises(ConnectorDraftError, match=r"^fields\[1\]\.required must be true"): + with pytest.raises(ConnectorDraftError, match=r"^fields\[1\]\.required may be false only on a secret field"): parse_connector_draft(_draft(fields=fields)) @@ -768,7 +768,7 @@ def test_the_tool_describes_the_check(): check = tool.input_schema["properties"]["check"] assert check["required"] == ["path"] - assert set(check["properties"]) == {"path"} + assert set(check["properties"]) == {"path", "public_path"} assert check["additionalProperties"] is False assert "check" in tool.description assert "call it directly from code" in tool.description @@ -830,7 +830,7 @@ def test_the_tool_describes_auth_as_one_flat_object(): assert "type 'query'" in tool.description assert auth["properties"]["params"]["maxProperties"] == 5 field = schema["properties"]["fields"]["items"]["properties"]["required"] - assert field["enum"] == [True] + assert "enum" not in field and field["type"] == "boolean" assert auth["additionalProperties"] is False assert _union_keywords(schema) == set() assert "call_minds_api" in schema["properties"]["usage_notes"]["description"] @@ -846,3 +846,96 @@ def test_the_examples_the_tool_gives_parse(): ) for data in (header, basic, notion): parse_connector_draft(data) + + +_OPTIONAL_FIELDS = [{"name": "api_key", "label": "Key", "required": False}] +_OPTIONAL_CHECK = {"path": "/api/3/action/user_show", "public_path": "/api/3/action/package_list"} + + +def _optional_draft(**overrides): + """A one-key template whose key a member may leave out, with both check paths.""" + return _draft(**{"fields": _OPTIONAL_FIELDS, "auth": _one_field_auth(), "check": _OPTIONAL_CHECK, **overrides}) + + +def test_an_optional_key_with_a_public_path_parses_and_round_trips(): + draft = parse_connector_draft(_optional_draft()) + + assert draft.fields[0].required is False + assert draft.check.public_path == "/api/3/action/package_list" + assert draft.to_dict()["check"] == _OPTIONAL_CHECK + assert draft.to_dict()["fields"][0]["required"] is False + assert parse_connector_draft(draft.to_dict()) == draft + + +def test_a_check_without_an_optional_key_keeps_its_old_shape(): + assert parse_connector_draft(_draft(check=_CHECK)).check.public_path is None + assert parse_connector_draft(_draft(check=_CHECK)).to_dict()["check"] == _CHECK + + +def test_a_public_path_is_required_when_every_secret_field_is_optional(): + with pytest.raises(ConnectorDraftError, match=r"^check\.public_path is required"): + parse_connector_draft(_optional_draft(check={"path": "/api/3/action/user_show"})) + + +@pytest.mark.parametrize("fields,auth", [ + (_BASIC_FIELDS, {"type": "basic", "username": "{email}/token", "password": "{api_token}"}), + ( + [{"name": "api_key", "label": "Key"}, {"name": "extra", "label": "Extra", "required": False}], + {"type": "header", "headers": {"Authorization": "Bearer {api_key}", "X-Extra": "{extra}"}}, + ), +], ids=["no optional field", "a required secret beside the optional one"]) +def test_a_public_path_is_refused_when_no_connection_could_be_keyless(fields, auth): + check = {"path": "/v2/me", "public_path": "/v2/status"} + + with pytest.raises(ConnectorDraftError, match=r"^check\.public_path is only for"): + parse_connector_draft(_draft(fields=fields, auth=auth, check=check)) + + +def test_a_public_path_may_not_equal_the_path(): + check = {"path": "/v2/me", "public_path": "/v2/me"} + + with pytest.raises(ConnectorDraftError, match=r"^check\.public_path must differ"): + parse_connector_draft(_optional_draft(check=check)) + + +@pytest.mark.parametrize("path", ["v2/status", "//evil.example/x", "/v2/../x", "/v2/{api_key}"]) +def test_a_public_path_follows_the_path_rules(path): + with pytest.raises(ConnectorDraftError, match=r"^check\.public_path\b"): + parse_connector_draft(_optional_draft(check={"path": "/v2/me", "public_path": path})) + + +def test_a_public_path_carrying_the_placed_parameter_is_refused(): + fields = [{"name": "api_key", "label": "Key", "required": False}] + check = {"path": "/v1/me", "public_path": "/v1/eod?access_key=demo"} + + with pytest.raises(ConnectorDraftError, match=r"^check\.public_path may carry only plain parameter names"): + parse_connector_draft(_draft(fields=fields, auth=_QUERY_AUTH, check=check)) + + +def test_an_optional_key_may_not_share_a_header_with_another_field(): + fields = [{"name": "api_key", "label": "Key", "required": False}, {"name": "account", "label": "Account", "secret": False}] + auth = {"type": "header", "headers": {"Authorization": "Bearer {api_key}.{account}"}} + + with pytest.raises(ConnectorDraftError, match=r"^auth\.headers\[0\] places an optional field with another"): + parse_connector_draft(_draft(fields=fields, auth=auth, check=_OPTIONAL_CHECK)) + + +def test_the_tool_stages_an_optional_key_and_names_it_in_its_text(): + box = ConnectorDraftBox() + tool = connector_draft_tool(box) + + outcome = asyncio.run(tool.handler(None, _optional_draft())) + + assert outcome.ok and box.drain()[0]["check"] == _OPTIONAL_CHECK + assert "required: false" in tool.description and "public_path" in tool.description + assert "no key or token at all" in tool.description + assert "none" not in tool.input_schema["properties"]["auth"]["properties"]["type"]["enum"] + + +def test_the_tool_texts_say_public_path_goes_only_with_every_key_optional(): + tool = connector_draft_tool(ConnectorDraftBox()) + required = tool.input_schema["properties"]["fields"]["items"]["properties"]["required"]["description"] + + assert "every key is optional" in tool.description and "every key is optional" in required + assert "public_path" in tool.input_schema["properties"]["check"]["properties"] + assert "every key is required: false" in tool.input_schema["properties"]["check"]["properties"]["public_path"]["description"]