Skip to content

Make Python verified actions non-forgeable before gateway use #73

Description

@bordumb

Finding

The current Python binding describes VerifiedAction as sealed, but its constructor guard is a module-level object:

_AUTHORIZED_TOKEN = object()

class VerifiedAction:
    def __init__(self, token: object, canonical_action: bytes) -> None:
        if token is not _AUTHORIZED_TOKEN:
            raise TypeError("VerifiedAction is sealed")

Python's underscore convention does not provide an access boundary. Application code can access auths._AUTHORIZED_TOKEN and call auths.VerifiedAction(auths._AUTHORIZED_TOKEN, arbitrary_bytes). The current verifier result remains useful as a decision carrier, but this class must not be treated as a non-forgeable capability accepted directly by an effect gateway.

Security consequence

A Full Workflow Python SDK needs an authorized command boundary that application code cannot construct from unverified bytes. Treating the current object as that boundary would violate Auths' invariant that execution derives only from sealed verifier output.

Required correction

Choose and document a Python-appropriate closed design, such as:

  • a native extension type whose constructor is unavailable to Python and whose payload remains native-owned;
  • a native command decoder/gateway handoff that consumes an internal verifier result without releasing a forgeable token; or
  • another reviewed capability design with explicit adversarial evidence.

A renamed underscore attribute, name mangling, undocumented constructor, object sentinel, or stack inspection is not sufficient.

Acceptance criteria

  • Arbitrary Python application code cannot construct an effect-capable verified action or profile command.
  • Only the authorized native verification branch can produce the handle accepted by a closed profile decoder/gateway.
  • Denied and indeterminate results contain no effect-capable handle.
  • Copying, pickling, subclassing, reflection, module-global inspection, and direct constructor attacks are tested.
  • Canonical action bytes remain available only through an explicitly advanced inspection API and cannot be converted back into a capability.
  • Documentation distinguishes a decision/data wrapper from a security capability.
  • The correction preserves stable verdicts, codes, and canonical fixture agreement.

Relationship

This blocks the Python Full Workflow SDK tier tracked by the cross-language capability work in #72. It does not imply that the Rust VerifiedAction or TypeScript closure-based construction has the same implementation defect; each binding requires language-specific capability analysis.

Exclusions

This issue does not authorize package publication, a new RC, provider execution, or a claim that Python object privacy can provide a cryptographic security boundary.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions